fix: include real errors in event detail, handle None payload explicitly, extract monitoring helper, add integration test

Co-authored-by: openhands <openhands@all-hands.dev>

.github/workflows/py-tests.yml

@@ -55,7 +55,7 @@ jobs:
       - name: Build Environment
         run: make build
       - name: Run Unit Tests
-        run: PYTHONPATH=".:$PYTHONPATH" poetry run pytest -n auto -s ./tests/unit --cov=openhands --cov-branch
+        run: PYTHONPATH=".:$PYTHONPATH" poetry run pytest --forked -n auto -s ./tests/unit --cov=openhands --cov-branch
         env:
           COVERAGE_FILE: ".coverage.${{ matrix.python_version }}"
       - name: Run Runtime Tests with CLIRuntime
@@ -91,7 +91,7 @@ jobs:
         run: poetry install --with dev,test
       - name: Run Unit Tests
         # Use base working directory for coverage paths to line up.
-        run: PYTHONPATH=".:$PYTHONPATH" poetry run --project=enterprise pytest -n auto -s -p no:ddtrace -p no:ddtrace.pytest_bdd -p no:ddtrace.pytest_benchmark ./enterprise/tests/unit --cov=enterprise --cov-branch
+        run: PYTHONPATH=".:$PYTHONPATH" poetry run --project=enterprise pytest --forked -n auto -s -p no:ddtrace -p no:ddtrace.pytest_bdd -p no:ddtrace.pytest_benchmark ./enterprise/tests/unit --cov=enterprise --cov-branch
         env:
           COVERAGE_FILE: ".coverage.enterprise.${{ matrix.python_version }}"
       - name: Store coverage file

enterprise/poetry.lock

@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 2.3.2 and should not be changed by hand.
+# This file is automatically @generated by Poetry 2.2.1 and should not be changed by hand.
 
 [[package]]
 name = "agent-client-protocol"
@@ -3501,7 +3501,7 @@ files = [
 [package.dependencies]
 googleapis-common-protos = ">=1.5.5"
 grpcio = ">=1.71.2"
-protobuf = ">=5.26.1,<6.0.dev0"
+protobuf = ">=5.26.1,<6.0dev"
 
 [[package]]
 name = "gspread"
@@ -3819,7 +3819,7 @@ pfzy = ">=0.3.1,<0.4.0"
 prompt-toolkit = ">=3.0.1,<4.0.0"
 
 [package.extras]
-docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17b43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
+docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17-beta.43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
 
 [[package]]
 name = "installer"
@@ -4258,7 +4258,7 @@ fqdn = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 idna = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 isoduration = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 jsonpointer = {version = ">1.13", optional = true, markers = "extra == \"format-nongpl\""}
-jsonschema-specifications = ">=2023.3.6"
+jsonschema-specifications = ">=2023.03.6"
 referencing = ">=0.28.4"
 rfc3339-validator = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 rfc3986-validator = {version = ">0.1.0", optional = true, markers = "extra == \"format-nongpl\""}
@@ -4648,7 +4648,7 @@ files = [
 ]
 
 [package.dependencies]
-certifi = ">=14.5.14"
+certifi = ">=14.05.14"
 durationpy = ">=0.7"
 google-auth = ">=1.0.1"
 oauthlib = ">=3.2.2"
@@ -6889,7 +6889,7 @@ files = [
 ]
 
 [package.extras]
-docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17b43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
+docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17-beta.43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
 
 [[package]]
 name = "pg8000"
@@ -7551,6 +7551,18 @@ files = [
     {file = "puremagic-1.30.tar.gz", hash = "sha256:f9ff7ac157d54e9cf3bff1addfd97233548e75e685282d84ae11e7ffee1614c9"},
 ]
 
+[[package]]
+name = "py"
+version = "1.11.0"
+description = "library with cross-python path, ini-parsing, io, code, log facilities"
+optional = false
+python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+groups = ["test"]
+files = [
+    {file = "py-1.11.0-py2.py3-none-any.whl", hash = "sha256:607c53218732647dff4acdfcd50cb62615cedf612e72d1724fb1a0cc6405b378"},
+    {file = "py-1.11.0.tar.gz", hash = "sha256:51c75c4126074b472f746a24399ad32f6053d1b34b68d2fa41e558e6f4a98719"},
+]
+
 [[package]]
 name = "py-key-value-aio"
 version = "0.4.4"
@@ -11691,6 +11703,22 @@ pytest = ">=7"
 [package.extras]
 testing = ["process-tests", "pytest-xdist", "virtualenv"]
 
+[[package]]
+name = "pytest-forked"
+version = "1.6.0"
+description = "run tests in isolated forked subprocesses"
+optional = false
+python-versions = ">=3.7"
+groups = ["test"]
+files = [
+    {file = "pytest-forked-1.6.0.tar.gz", hash = "sha256:4dafd46a9a600f65d822b8f605133ecf5b3e1941ebb3588e943b4e3eb71a5a3f"},
+    {file = "pytest_forked-1.6.0-py3-none-any.whl", hash = "sha256:810958f66a91afb1a1e2ae83089d8dc1cd2437ac96b12963042fbb9fb4d16af0"},
+]
+
+[package.dependencies]
+py = "*"
+pytest = ">=3.10"
+
 [[package]]
 name = "pytest-xdist"
 version = "3.8.0"
@@ -12838,10 +12866,10 @@ files = [
 ]
 
 [package.dependencies]
-botocore = ">=1.37.4,<2.0a0"
+botocore = ">=1.37.4,<2.0a.0"
 
 [package.extras]
-crt = ["botocore[crt] (>=1.37.4,<2.0a0)"]
+crt = ["botocore[crt] (>=1.37.4,<2.0a.0)"]
 
 [[package]]
 name = "scantree"
@@ -14978,9 +15006,9 @@ files = [
 ]
 
 [package.extras]
-cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and python_version < \"3.14\"", "cffi (>=2.0.0b0) ; platform_python_implementation != \"PyPy\" and python_version >= \"3.14\""]
+cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and python_version < \"3.14\"", "cffi (>=2.0.0b) ; platform_python_implementation != \"PyPy\" and python_version >= \"3.14\""]
 
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.12,<3.14"
-content-hash = "4221146bf5d0dda799dde9ecdec5d38db556db8a759549efe7d67372b5750b67"
+content-hash = "ef037f6d6085d26166d35c56ce266439f8f1a4fea90bc43ccf15cfeaf116cae5"

enterprise/pyproject.toml

@@ -61,6 +61,7 @@ types-requests = "^2.32.4.20250611"
 pytest = "*"
 pytest-cov = "*"
 pytest-asyncio = "*"
+pytest-forked = "*"
 pytest-xdist = "*"
 flake8 = "*"
 openai = "*"

enterprise/run_automation_executor.py

@@ -0,0 +1,71 @@
+"""Entry point for the automation executor.
+
+Usage: python -m run_automation_executor
+
+This runs as a Kubernetes Deployment (long-running). It polls the automation_events
+inbox, matches events to automations, claims and executes runs, and monitors
+conversation completion.
+
+Environment variables:
+    OPENHANDS_API_URL        Base URL for the V1 API (default: http://openhands-service:3000)
+    MAX_CONCURRENT_RUNS      Max concurrent runs per executor (default: 5)
+    RUN_TIMEOUT_SECONDS      Max time for a single run (default: 7200)
+    POLL_INTERVAL_SECONDS    Fallback poll interval (default: 30)
+    HEARTBEAT_INTERVAL_SECONDS  Heartbeat update interval (default: 60)
+"""
+
+import asyncio
+import logging
+import signal
+import sys
+
+logger = logging.getLogger('saas.automation.executor')
+
+
+def _setup_logging() -> None:
+    """Configure logging, deferring to enterprise logger if available."""
+    try:
+        from server.logger import setup_all_loggers
+
+        setup_all_loggers()
+    except ImportError:
+        logging.basicConfig(
+            level=logging.INFO,
+            format='%(asctime)s %(name)s %(levelname)s %(message)s',
+            stream=sys.stdout,
+        )
+
+
+def _install_signal_handlers(loop: asyncio.AbstractEventLoop) -> None:
+    """Install signal handlers for graceful shutdown."""
+    from services.automation_executor import request_shutdown
+
+    def _handle_signal(signum: int, _frame: object) -> None:
+        sig_name = signal.Signals(signum).name
+        logger.info('Received %s, initiating graceful shutdown...', sig_name)
+        request_shutdown()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, _handle_signal)
+
+
+async def main() -> None:
+    from services.automation_executor import executor_main
+
+    await executor_main()
+
+
+if __name__ == '__main__':
+    _setup_logging()
+
+    loop = asyncio.new_event_loop()
+    _install_signal_handlers(loop)
+
+    logger.info('Starting automation executor')
+    try:
+        loop.run_until_complete(main())
+    except KeyboardInterrupt:
+        logger.info('Interrupted by user')
+    finally:
+        loop.close()
+        logger.info('Automation executor process exiting')

enterprise/services/automation_executor.py

@@ -0,0 +1,555 @@
+"""Automation executor — processes events, claims and executes runs.
+
+The executor is a long-running process with three phases:
+  1. Process inbox: match NEW events to automations, create PENDING runs
+  2. Claim and execute: claim PENDING runs, submit to V1 API, heartbeat
+  3. Stale recovery: recover RUNNING runs with expired heartbeats
+"""
+
+import asyncio
+import logging
+import os
+import socket
+from datetime import datetime, timedelta, timezone
+from uuid import uuid4
+
+from services.openhands_api_client import OpenHandsAPIClient
+from sqlalchemy import or_, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+from storage.automation import Automation, AutomationRun
+from storage.automation_event import AutomationEvent
+
+logger = logging.getLogger('saas.automation.executor')
+
+# Environment-configurable settings
+POLL_INTERVAL_SECONDS = float(os.getenv('POLL_INTERVAL_SECONDS', '30'))
+HEARTBEAT_INTERVAL_SECONDS = float(os.getenv('HEARTBEAT_INTERVAL_SECONDS', '60'))
+RUN_TIMEOUT_SECONDS = float(os.getenv('RUN_TIMEOUT_SECONDS', '7200'))
+MAX_CONCURRENT_RUNS = int(os.getenv('MAX_CONCURRENT_RUNS', '5'))
+STALE_THRESHOLD_MINUTES = 5
+MAX_EVENTS_PER_BATCH = 50
+MAX_RETRIES_DEFAULT = 3
+
+# Terminal conversation statuses
+TERMINAL_STATUSES = frozenset({'STOPPED', 'ERROR', 'COMPLETED', 'CANCELLED'})
+
+# Shutdown flag — set by signal handlers
+_shutdown_event: asyncio.Event | None = None
+
+# Background task tracking for graceful shutdown
+_pending_tasks: set[asyncio.Task] = set()
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def get_shutdown_event() -> asyncio.Event:
+    global _shutdown_event
+    if _shutdown_event is None:
+        _shutdown_event = asyncio.Event()
+    return _shutdown_event
+
+
+def should_continue() -> bool:
+    return not get_shutdown_event().is_set()
+
+
+def request_shutdown() -> None:
+    get_shutdown_event().set()
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: Process inbox (event matching)
+# ---------------------------------------------------------------------------
+
+
+async def find_matching_automations(
+    session: AsyncSession, event: AutomationEvent
+) -> list[Automation]:
+    """Find automations that match the given event.
+
+    Phase 1 supports cron and manual triggers only — both carry
+    ``automation_id`` in the event payload.
+    """
+    source_type = event.source_type
+    payload = event.payload
+    if payload is None:
+        logger.error('Event %s has None payload — possible data corruption', event.id)
+        return []
+
+    if source_type in ('cron', 'manual'):
+        automation_id = payload.get('automation_id')
+        if not automation_id:
+            logger.warning(
+                'Event %s (source=%s) missing automation_id in payload',
+                event.id,
+                source_type,
+            )
+            return []
+
+        result = await session.execute(
+            select(Automation).where(
+                Automation.id == automation_id,
+                Automation.enabled.is_(True),
+            )
+        )
+        automation = result.scalar_one_or_none()
+        return [automation] if automation else []
+
+    logger.debug('Unhandled event source_type=%s for event %s', source_type, event.id)
+    return []
+
+
+async def process_new_events(session: AsyncSession) -> int:
+    """Claim NEW events from inbox, match to automations, create runs.
+
+    Returns the number of events processed.
+    """
+    result = await session.execute(
+        select(AutomationEvent)
+        .where(AutomationEvent.status == 'NEW')
+        .order_by(AutomationEvent.created_at)
+        .limit(MAX_EVENTS_PER_BATCH)
+        .with_for_update(skip_locked=True)
+    )
+    events = list(result.scalars())
+
+    processed = 0
+    for event in events:
+        try:
+            automations = await find_matching_automations(session, event)
+            if not automations:
+                event.status = 'NO_MATCH'
+                event.processed_at = utc_now()
+            else:
+                for automation in automations:
+                    run = AutomationRun(
+                        id=uuid4().hex,
+                        automation_id=automation.id,
+                        event_id=event.id,
+                        status='PENDING',
+                        event_payload=event.payload,
+                    )
+                    session.add(run)
+                event.status = 'PROCESSED'
+                event.processed_at = utc_now()
+            processed += 1
+        except Exception as e:
+            logger.exception('Error processing event %s', event.id)
+            event.status = 'ERROR'
+            event.error_detail = f'Failed during event matching: {type(e).__name__}: {e}'
+            event.processed_at = utc_now()
+
+    if processed:
+        await session.commit()
+        logger.info('Processed %d events', processed)
+
+    return processed
+
+
+# ---------------------------------------------------------------------------
+# Phase 2: Claim and execute runs
+# ---------------------------------------------------------------------------
+
+
+async def resolve_user_api_key(session: AsyncSession, user_id: str) -> str | None:
+    """Look up a user's API key from the api_keys table.
+
+    Returns the first active key found, or None.
+    """
+    from storage.api_key import ApiKey
+
+    result = await session.execute(
+        select(ApiKey.key).where(ApiKey.user_id == user_id).limit(1)
+    )
+    row = result.scalar_one_or_none()
+    return row
+
+
+async def download_automation_file(file_store_key: str) -> bytes:
+    """Download the automation .py file from object storage."""
+    try:
+        from openhands.server.shared import file_store
+    except ImportError as exc:
+        raise RuntimeError(
+            'file_store is not available — ensure the enterprise server '
+            'has been initialised before calling download_automation_file'
+        ) from exc
+
+    content = file_store.read(file_store_key)
+    if isinstance(content, str):
+        return content.encode('utf-8')
+    return content
+
+
+def is_terminal(conversation: dict) -> bool:
+    """Check if a conversation has reached a terminal status."""
+    status = (conversation.get('status') or '').upper()
+    return status in TERMINAL_STATUSES
+
+
+async def _prepare_run(
+    run: AutomationRun,
+    automation: Automation,
+    session_factory: object,
+) -> tuple[str, bytes]:
+    """Resolve the user's API key and download the automation file.
+
+    Returns:
+        (api_key, automation_file) tuple ready for submission.
+
+    Raises:
+        ValueError: If no API key is found.
+        RuntimeError: If file_store is unavailable.
+    """
+    async with session_factory() as key_session:
+        api_key = await resolve_user_api_key(key_session, automation.user_id)
+
+    if not api_key:
+        raise ValueError(f'No API key found for user {automation.user_id}')
+
+    automation_file = await download_automation_file(automation.file_store_key)
+    return api_key, automation_file
+
+
+async def _monitor_conversation(
+    run: AutomationRun,
+    conversation_id: str,
+    api_client: OpenHandsAPIClient,
+    api_key: str,
+    session_factory: object,
+) -> bool:
+    """Monitor a conversation until completion or timeout.
+
+    Returns True if completed successfully, False if shutdown requested.
+
+    Raises:
+        TimeoutError: If the run exceeds RUN_TIMEOUT_SECONDS.
+    """
+    start_time = utc_now()
+    while should_continue():
+        elapsed = (utc_now() - start_time).total_seconds()
+        if elapsed > RUN_TIMEOUT_SECONDS:
+            raise TimeoutError(f'Run exceeded {RUN_TIMEOUT_SECONDS}s timeout')
+
+        await asyncio.sleep(HEARTBEAT_INTERVAL_SECONDS)
+
+        # Update heartbeat
+        async with session_factory() as session:
+            run_obj = await session.get(AutomationRun, run.id)
+            if run_obj:
+                run_obj.heartbeat_at = utc_now()
+                await session.commit()
+
+        # Check conversation status
+        conversation = (
+            await api_client.get_conversation(api_key, conversation_id) or {}
+        )
+        if is_terminal(conversation):
+            return True
+
+    return False  # shutdown requested
+
+
+async def _submit_and_monitor(
+    run: AutomationRun,
+    api_key: str,
+    automation_file: bytes,
+    automation: Automation,
+    api_client: OpenHandsAPIClient,
+    session_factory: object,
+) -> None:
+    """Submit the automation to the V1 API and monitor until completion.
+
+    Updates the run's conversation_id, sends heartbeats, and marks the
+    final status when the conversation reaches a terminal state.
+    """
+    conversation = await api_client.start_conversation(
+        api_key=api_key,
+        automation_file=automation_file,
+        title=f'Automation: {automation.name}',
+        event_payload=run.event_payload,
+    )
+
+    conversation_id = conversation.get('app_conversation_id') or conversation.get(
+        'conversation_id'
+    )
+
+    # Persist conversation ID
+    async with session_factory() as update_session:
+        run_obj = await update_session.get(AutomationRun, run.id)
+        if run_obj:
+            run_obj.conversation_id = conversation_id
+            await update_session.commit()
+
+    # Monitor with heartbeats
+    completed = await _monitor_conversation(
+        run, conversation_id, api_client, api_key, session_factory
+    )
+
+    # Update final status
+    async with session_factory() as final_session:
+        run_obj = await final_session.get(AutomationRun, run.id)
+        if run_obj:
+            if not completed:
+                # Leave as RUNNING — stale recovery will handle it if needed.
+                # The conversation may still be running on the API side.
+                logger.info(
+                    'Run %s left as RUNNING due to executor shutdown', run.id
+                )
+            else:
+                run_obj.status = 'COMPLETED'
+                run_obj.completed_at = utc_now()
+                logger.info('Run %s completed successfully', run.id)
+            await final_session.commit()
+
+
+async def execute_run(
+    run: AutomationRun,
+    automation: Automation,
+    api_client: OpenHandsAPIClient,
+    session_factory: object,
+) -> None:
+    """Execute a single automation run end-to-end.
+
+    Orchestrates preparation (API key + file download) and submission/monitoring.
+    On failure, marks the run for retry or dead-letter.
+    """
+    try:
+        api_key, automation_file = await _prepare_run(
+            run, automation, session_factory
+        )
+        await _submit_and_monitor(
+            run, api_key, automation_file, automation, api_client, session_factory
+        )
+    except Exception as e:
+        logger.exception('Run %s failed: %s', run.id, e)
+        await _mark_run_failed(run, str(e), session_factory)
+
+
+async def _mark_run_failed(
+    run: AutomationRun, error: str, session_factory: object
+) -> None:
+    """Mark a run as FAILED or return to PENDING for retry."""
+    async with session_factory() as session:
+        run_obj = await session.get(AutomationRun, run.id)
+        if not run_obj:
+            return
+
+        run_obj.retry_count = (run_obj.retry_count or 0) + 1
+        run_obj.error_detail = error
+
+        if run_obj.retry_count >= (run_obj.max_retries or MAX_RETRIES_DEFAULT):
+            run_obj.status = 'DEAD_LETTER'
+            run_obj.completed_at = utc_now()
+            logger.error(
+                'Run %s moved to DEAD_LETTER after %d retries',
+                run.id,
+                run_obj.retry_count,
+            )
+        else:
+            run_obj.status = 'PENDING'
+            run_obj.claimed_by = None
+            backoff_seconds = 30 * (2 ** (run_obj.retry_count - 1))
+            run_obj.next_retry_at = utc_now() + timedelta(seconds=backoff_seconds)
+            logger.warning(
+                'Run %s returned to PENDING, retry %d/%d in %ds',
+                run.id,
+                run_obj.retry_count,
+                run_obj.max_retries or MAX_RETRIES_DEFAULT,
+                backoff_seconds,
+            )
+
+        await session.commit()
+
+
+async def claim_and_execute_runs(
+    session: AsyncSession,
+    executor_id: str,
+    api_client: OpenHandsAPIClient,
+    session_factory: object,
+) -> bool:
+    """Claim a PENDING run and start executing it.
+
+    Returns True if a run was claimed, False otherwise.
+    """
+    result = await session.execute(
+        select(AutomationRun)
+        .where(
+            AutomationRun.status == 'PENDING',
+            or_(
+                AutomationRun.next_retry_at.is_(None),
+                AutomationRun.next_retry_at <= utc_now(),
+            ),
+        )
+        .order_by(AutomationRun.created_at)
+        .limit(1)
+        .with_for_update(skip_locked=True)
+    )
+    run = result.scalar_one_or_none()
+    if not run:
+        return False
+
+    # Claim the run
+    run.status = 'RUNNING'
+    run.claimed_by = executor_id
+    run.claimed_at = utc_now()
+    run.heartbeat_at = utc_now()
+    run.started_at = utc_now()
+    await session.commit()
+
+    # Load automation for the run
+    auto_result = await session.execute(
+        select(Automation).where(Automation.id == run.automation_id)
+    )
+    automation = auto_result.scalar_one_or_none()
+    if not automation:
+        logger.error('Automation %s not found for run %s', run.automation_id, run.id)
+        await _mark_run_failed(
+            run, f'Automation {run.automation_id} not found', session_factory
+        )
+        return True
+
+    # Execute in background (long-running) with task tracking
+    task = asyncio.create_task(
+        execute_run(run, automation, api_client, session_factory),
+        name=f'execute-run-{run.id}',
+    )
+    _pending_tasks.add(task)
+    task.add_done_callback(_pending_tasks.discard)
+
+    logger.info(
+        'Claimed run %s (automation=%s) by executor %s',
+        run.id,
+        run.automation_id,
+        executor_id,
+    )
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Phase 3: Stale run recovery
+# ---------------------------------------------------------------------------
+
+
+async def recover_stale_runs(session: AsyncSession) -> int:
+    """Mark RUNNING runs with expired heartbeats as PENDING for retry.
+
+    Returns the number of recovered runs.
+    """
+    stale_threshold = utc_now() - timedelta(minutes=STALE_THRESHOLD_MINUTES)
+    timeout_threshold = utc_now() - timedelta(seconds=RUN_TIMEOUT_SECONDS)
+
+    # Recover stale runs (heartbeat expired)
+    result = await session.execute(
+        update(AutomationRun)
+        .where(
+            AutomationRun.status == 'RUNNING',
+            AutomationRun.heartbeat_at < stale_threshold,
+            AutomationRun.heartbeat_at >= timeout_threshold,
+        )
+        .values(
+            status='PENDING',
+            claimed_by=None,
+            retry_count=AutomationRun.retry_count + 1,
+            next_retry_at=utc_now() + timedelta(seconds=30),
+        )
+        .returning(AutomationRun.id)
+    )
+    recovered_rows = result.fetchall()
+
+    # Mark truly timed-out runs as DEAD_LETTER
+    timeout_result = await session.execute(
+        update(AutomationRun)
+        .where(
+            AutomationRun.status == 'RUNNING',
+            AutomationRun.heartbeat_at < timeout_threshold,
+        )
+        .values(
+            status='DEAD_LETTER',
+            error_detail='Run exceeded timeout',
+            completed_at=utc_now(),
+        )
+        .returning(AutomationRun.id)
+    )
+    timed_out_rows = timeout_result.fetchall()
+
+    await session.commit()
+
+    recovered_count = len(recovered_rows)
+    timed_out_count = len(timed_out_rows)
+
+    if recovered_count:
+        logger.warning('Recovered %d stale automation runs', recovered_count)
+    if timed_out_count:
+        logger.warning(
+            'Marked %d automation runs as DEAD_LETTER (timeout)', timed_out_count
+        )
+
+    return recovered_count + timed_out_count
+
+
+# ---------------------------------------------------------------------------
+# Main executor loop
+# ---------------------------------------------------------------------------
+
+
+async def executor_main(session_factory: object | None = None) -> None:
+    """Main executor loop.
+
+    Args:
+        session_factory: Async context manager that yields AsyncSession instances.
+            If None, uses the default ``a_session_maker`` from database module.
+    """
+    if session_factory is None:
+        from storage.database import a_session_maker
+
+        session_factory = a_session_maker
+
+    executor_id = f'executor-{socket.gethostname()}-{os.getpid()}'
+    api_url = os.getenv('OPENHANDS_API_URL', 'http://openhands-service:3000')
+    api_client = OpenHandsAPIClient(base_url=api_url)
+
+    logger.info(
+        'Automation executor %s starting (api_url=%s, poll=%ss, heartbeat=%ss)',
+        executor_id,
+        api_url,
+        POLL_INTERVAL_SECONDS,
+        HEARTBEAT_INTERVAL_SECONDS,
+    )
+
+    try:
+        while should_continue():
+            try:
+                async with session_factory() as session:
+                    await process_new_events(session)
+
+                async with session_factory() as session:
+                    await claim_and_execute_runs(
+                        session, executor_id, api_client, session_factory
+                    )
+
+                async with session_factory() as session:
+                    await recover_stale_runs(session)
+
+            except Exception:
+                logger.exception('Error in executor main loop iteration')
+
+            # Wait for next poll interval (or early wakeup on shutdown)
+            try:
+                await asyncio.wait_for(
+                    get_shutdown_event().wait(),
+                    timeout=POLL_INTERVAL_SECONDS,
+                )
+            except asyncio.TimeoutError:
+                pass  # Normal — poll interval elapsed
+
+    finally:
+        if _pending_tasks:
+            logger.info(
+                'Waiting for %d running tasks to complete...', len(_pending_tasks)
+            )
+            await asyncio.gather(*_pending_tasks, return_exceptions=True)
+        await api_client.close()
+        logger.info('Automation executor %s shut down', executor_id)

enterprise/services/openhands_api_client.py

@@ -0,0 +1,93 @@
+"""HTTP client for the main OpenHands V1 API (internal cluster calls).
+
+Used by the automation executor to create and monitor conversations
+in the main OpenHands server.
+"""
+
+import base64
+import logging
+
+import httpx
+
+logger = logging.getLogger('saas.automation.api_client')
+
+
+def _raise_with_body(resp: httpx.Response) -> None:
+    """Call raise_for_status, enriching the error with the response body."""
+    try:
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as e:
+        error_body = resp.text[:500] if resp.text else 'no response body'
+        raise httpx.HTTPStatusError(
+            f'{e.args[0]} — Response: {error_body}',
+            request=e.request,
+            response=e.response,
+        ) from e
+
+
+class OpenHandsAPIClient:
+    """Async HTTP client for the OpenHands V1 API."""
+
+    def __init__(self, base_url: str = 'http://openhands-service:3000'):
+        self.base_url = base_url.rstrip('/')
+        self.client = httpx.AsyncClient(base_url=self.base_url, timeout=30.0)
+
+    async def start_conversation(
+        self,
+        api_key: str,
+        automation_file: bytes,
+        title: str,
+        event_payload: dict | None = None,
+    ) -> dict:
+        """Submit an SDK script for sandboxed execution via V1 API.
+
+        Args:
+            api_key: User's API key for authentication.
+            automation_file: Raw bytes of the .py automation script.
+            title: Display title for the conversation.
+            event_payload: Optional trigger event data (injected as env var).
+
+        Returns:
+            Parsed JSON response containing conversation details.
+
+        Raises:
+            httpx.HTTPStatusError: If the API returns a non-2xx status.
+        """
+        resp = await self.client.post(
+            '/api/v1/app-conversations',
+            json={
+                'automation_file': base64.b64encode(automation_file).decode(),
+                'trigger': 'automation',
+                'title': title,
+                'event_payload': event_payload,
+            },
+            headers={'Authorization': f'Bearer {api_key}'},
+        )
+        _raise_with_body(resp)
+        return resp.json()
+
+    async def get_conversation(self, api_key: str, conversation_id: str) -> dict | None:
+        """Get conversation status.
+
+        Args:
+            api_key: User's API key for authentication.
+            conversation_id: The conversation ID to look up.
+
+        Returns:
+            Conversation data dict, or None if not found.
+
+        Raises:
+            httpx.HTTPStatusError: If the API returns a non-2xx status.
+        """
+        resp = await self.client.get(
+            '/api/v1/app-conversations',
+            params={'ids': [conversation_id]},
+            headers={'Authorization': f'Bearer {api_key}'},
+        )
+        _raise_with_body(resp)
+        conversations = resp.json()
+        return conversations[0] if conversations else None
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self.client.aclose()

enterprise/storage/automation.py

@@ -0,0 +1,77 @@
+"""SQLAlchemy models for automations and automation runs.
+
+Stub for Task 1 (Data Foundation). These models will be replaced when Task 1
+is merged into automations-phase1.
+"""
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    text,
+)
+from sqlalchemy.orm import relationship
+from sqlalchemy.types import JSON
+from storage.base import Base
+
+
+class Automation(Base):
+    __tablename__ = 'automations'
+
+    id = Column(String, primary_key=True)
+    user_id = Column(String, nullable=False, index=True)
+    org_id = Column(String, nullable=True, index=True)
+
+    name = Column(String, nullable=False)
+    enabled = Column(Boolean, nullable=False, server_default=text('true'))
+
+    config = Column(JSON, nullable=False)
+    trigger_type = Column(String, nullable=False)
+    file_store_key = Column(String, nullable=False)
+
+    last_triggered_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=text('CURRENT_TIMESTAMP'),
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=text('CURRENT_TIMESTAMP'),
+    )
+
+    runs = relationship('AutomationRun', back_populates='automation')
+
+
+class AutomationRun(Base):
+    __tablename__ = 'automation_runs'
+
+    id = Column(String, primary_key=True)
+    automation_id = Column(
+        String, ForeignKey('automations.id', ondelete='CASCADE'), nullable=False
+    )
+    event_id = Column(Integer, ForeignKey('automation_events.id'), nullable=True)
+    conversation_id = Column(String, nullable=True)
+    status = Column(String, nullable=False, server_default=text("'PENDING'"))
+    claimed_by = Column(String, nullable=True)
+    claimed_at = Column(DateTime(timezone=True), nullable=True)
+    heartbeat_at = Column(DateTime(timezone=True), nullable=True)
+    retry_count = Column(Integer, nullable=False, server_default=text('0'))
+    max_retries = Column(Integer, nullable=False, server_default=text('3'))
+    next_retry_at = Column(DateTime(timezone=True), nullable=True)
+    event_payload = Column(JSON, nullable=True)
+    error_detail = Column(Text, nullable=True)
+    started_at = Column(DateTime(timezone=True), nullable=True)
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=text('CURRENT_TIMESTAMP'),
+    )
+
+    automation = relationship('Automation', back_populates='runs')

enterprise/storage/automation_event.py

@@ -0,0 +1,27 @@
+"""SQLAlchemy model for automation events (the inbox).
+
+Stub for Task 1 (Data Foundation). This model will be replaced when Task 1
+is merged into automations-phase1.
+"""
+
+from sqlalchemy import Column, DateTime, Integer, String, Text, text
+from sqlalchemy.types import JSON
+from storage.base import Base
+
+
+class AutomationEvent(Base):
+    __tablename__ = 'automation_events'
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    source_type = Column(String, nullable=False)
+    payload = Column(JSON, nullable=False)
+    metadata_ = Column('metadata', JSON, nullable=True)
+    dedup_key = Column(String, nullable=False, unique=True)
+    status = Column(String, nullable=False, server_default=text("'NEW'"))
+    error_detail = Column(Text, nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=text('CURRENT_TIMESTAMP'),
+    )
+    processed_at = Column(DateTime(timezone=True), nullable=True)

enterprise/storage/saas_settings_store.py

@@ -11,9 +11,10 @@ from pydantic import SecretStr
 from server.auth.token_manager import TokenManager
 from server.constants import LITE_LLM_API_URL
 from server.logger import logger
-from sqlalchemy import select
+from sqlalchemy import select, update
 from sqlalchemy.orm import joinedload
 from storage.database import a_session_maker
+from storage.encrypt_utils import encrypt_value
 from storage.lite_llm_manager import LiteLlmManager, get_openhands_cloud_key_alias
 from storage.org import Org
 from storage.org_member import OrgMember
@@ -186,6 +187,30 @@ class SaasSettingsStore(SettingsStore):
                     if hasattr(model, key):
                         setattr(model, key, value)
 
+            # Propagate LLM settings to all org members
+            # This ensures all members see the same LLM configuration when an admin saves
+            # Note: Concurrent saves by multiple admins will result in last-write-wins.
+            # Consider adding optimistic locking if this becomes a problem.
+            member_update_values: dict = {}
+            if item.llm_model is not None:
+                member_update_values['llm_model'] = item.llm_model
+            if item.llm_base_url is not None:
+                member_update_values['llm_base_url'] = item.llm_base_url
+            if item.max_iterations is not None:
+                member_update_values['max_iterations'] = item.max_iterations
+            if item.llm_api_key is not None:
+                member_update_values['_llm_api_key'] = encrypt_value(
+                    item.llm_api_key.get_secret_value()
+                )
+
+            if member_update_values:
+                stmt = (
+                    update(OrgMember)
+                    .where(OrgMember.org_id == org_id)
+                    .values(**member_update_values)
+                )
+                await session.execute(stmt)
+
             await session.commit()
 
     @classmethod

enterprise/tests/unit/services/conftest.py

@@ -0,0 +1,68 @@
+"""Shared fixtures for services tests.
+
+Note: We pre-load ``storage`` as a namespace package to avoid the heavy
+``storage/__init__.py`` that imports the entire enterprise model graph.
+This must happen *before* any ``from storage.…`` import.
+"""
+
+import contextlib
+import sys
+import types
+
+# Prevent storage/__init__.py from loading the full model graph.
+# We only need the lightweight automation models for these tests.
+if 'storage' not in sys.modules:
+    import pathlib
+
+    _storage_dir = str(pathlib.Path(__file__).resolve().parents[3] / 'storage')
+    _mod = types.ModuleType('storage')
+    _mod.__path__ = [_storage_dir]
+    sys.modules['storage'] = _mod
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import StaticPool
+from storage.automation import Automation, AutomationRun  # noqa: F401
+from storage.automation_event import AutomationEvent  # noqa: F401
+from storage.base import Base
+
+
+@pytest.fixture
+async def async_engine():
+    """Create an async SQLite engine for testing."""
+    engine = create_async_engine(
+        'sqlite+aiosqlite:///:memory:',
+        poolclass=StaticPool,
+        connect_args={'check_same_thread': False},
+        echo=False,
+    )
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    yield engine
+    await engine.dispose()
+
+
+@pytest.fixture
+async def async_session_factory(async_engine):
+    """Create an async session factory that yields context-managed sessions."""
+    factory = async_sessionmaker(
+        bind=async_engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+    @contextlib.asynccontextmanager
+    async def _session_ctx():
+        async with factory() as session:
+            yield session
+
+    return _session_ctx
+
+
+@pytest.fixture
+async def async_session(async_session_factory):
+    """Create a single async session for testing."""
+    async with async_session_factory() as session:
+        yield session

enterprise/tests/unit/services/test_automation_executor.py

@@ -0,0 +1,624 @@
+"""Tests for the automation executor.
+
+Uses real SQLite database operations for event processing, run claiming,
+and stale run recovery. HTTP calls to the V1 API are mocked.
+"""
+
+from datetime import datetime, timedelta
+from unittest.mock import AsyncMock, patch
+from uuid import uuid4
+
+import pytest
+from services.automation_executor import (
+    _mark_run_failed,
+    claim_and_execute_runs,
+    find_matching_automations,
+    is_terminal,
+    process_new_events,
+    recover_stale_runs,
+    utc_now,
+)
+from sqlalchemy import select
+from storage.automation import Automation, AutomationRun
+from storage.automation_event import AutomationEvent
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def make_automation(
+    automation_id: str = 'auto-1',
+    user_id: str = 'user-1',
+    enabled: bool = True,
+    trigger_type: str = 'cron',
+    name: str = 'Test Automation',
+) -> Automation:
+    return Automation(
+        id=automation_id,
+        user_id=user_id,
+        org_id='org-1',
+        name=name,
+        enabled=enabled,
+        config={'triggers': {'cron': {'schedule': '0 9 * * 5'}}},
+        trigger_type=trigger_type,
+        file_store_key=f'automations/{automation_id}/script.py',
+    )
+
+
+def make_event(
+    source_type: str = 'cron',
+    payload: dict | None = None,
+    status: str = 'NEW',
+    dedup_key: str | None = None,
+) -> AutomationEvent:
+    return AutomationEvent(
+        source_type=source_type,
+        payload=payload or {'automation_id': 'auto-1'},
+        dedup_key=dedup_key or f'dedup-{uuid4().hex[:8]}',
+        status=status,
+        created_at=utc_now(),
+    )
+
+
+def make_run(
+    run_id: str | None = None,
+    automation_id: str = 'auto-1',
+    status: str = 'PENDING',
+    claimed_by: str | None = None,
+    heartbeat_at: datetime | None = None,
+    retry_count: int = 0,
+    max_retries: int = 3,
+    next_retry_at: datetime | None = None,
+) -> AutomationRun:
+    return AutomationRun(
+        id=run_id or uuid4().hex,
+        automation_id=automation_id,
+        status=status,
+        claimed_by=claimed_by,
+        heartbeat_at=heartbeat_at,
+        retry_count=retry_count,
+        max_retries=max_retries,
+        next_retry_at=next_retry_at,
+        event_payload={'automation_id': automation_id},
+        created_at=utc_now(),
+    )
+
+
+# ---------------------------------------------------------------------------
+# find_matching_automations
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_cron_event(async_session):
+    """Cron events match by automation_id in payload."""
+    automation = make_automation()
+    async_session.add(automation)
+    await async_session.commit()
+
+    event = make_event(source_type='cron', payload={'automation_id': 'auto-1'})
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert len(result) == 1
+    assert result[0].id == 'auto-1'
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_manual_event(async_session):
+    """Manual events also match by automation_id in payload."""
+    automation = make_automation()
+    async_session.add(automation)
+    await async_session.commit()
+
+    event = make_event(source_type='manual', payload={'automation_id': 'auto-1'})
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert len(result) == 1
+    assert result[0].id == 'auto-1'
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_disabled_automation(async_session):
+    """Disabled automations are not matched."""
+    automation = make_automation(enabled=False)
+    async_session.add(automation)
+    await async_session.commit()
+
+    event = make_event(payload={'automation_id': 'auto-1'})
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_missing_automation_id(async_session):
+    """Events without automation_id in payload return empty list."""
+    event = make_event(payload={'something_else': 'value'})
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_nonexistent_automation(async_session):
+    """Events referencing a non-existent automation return empty list."""
+    event = make_event(payload={'automation_id': 'nonexistent'})
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_unknown_source_type(async_session):
+    """Unknown source types return empty list."""
+    event = make_event(source_type='unknown', payload={'automation_id': 'auto-1'})
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert len(result) == 0
+
+
+# ---------------------------------------------------------------------------
+# process_new_events
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_process_new_events_creates_runs(async_session):
+    """Processing NEW events creates PENDING runs and marks events PROCESSED."""
+    automation = make_automation()
+    event = make_event(payload={'automation_id': 'auto-1'})
+    async_session.add_all([automation, event])
+    await async_session.commit()
+
+    count = await process_new_events(async_session)
+
+    assert count == 1
+
+    # Event should be PROCESSED
+    await async_session.refresh(event)
+    assert event.status == 'PROCESSED'
+    assert event.processed_at is not None
+
+    # A run should have been created
+    runs = (await async_session.execute(select(AutomationRun))).scalars().all()
+    assert len(runs) == 1
+    assert runs[0].automation_id == 'auto-1'
+    assert runs[0].status == 'PENDING'
+    assert runs[0].event_payload == {'automation_id': 'auto-1'}
+
+
+@pytest.mark.asyncio
+async def test_process_new_events_no_match(async_session):
+    """Events with no matching automation are marked NO_MATCH."""
+    event = make_event(payload={'automation_id': 'nonexistent'})
+    async_session.add(event)
+    await async_session.commit()
+
+    count = await process_new_events(async_session)
+
+    assert count == 1
+
+    await async_session.refresh(event)
+    assert event.status == 'NO_MATCH'
+    assert event.processed_at is not None
+
+    # No runs created
+    runs = (await async_session.execute(select(AutomationRun))).scalars().all()
+    assert len(runs) == 0
+
+
+@pytest.mark.asyncio
+async def test_process_new_events_skips_processed(async_session):
+    """Already processed events are not re-processed."""
+    event = make_event(status='PROCESSED')
+    async_session.add(event)
+    await async_session.commit()
+
+    count = await process_new_events(async_session)
+
+    assert count == 0
+
+
+@pytest.mark.asyncio
+async def test_process_new_events_multiple_events(async_session):
+    """Multiple NEW events are processed in one batch."""
+    auto1 = make_automation(automation_id='auto-1')
+    auto2 = make_automation(automation_id='auto-2', name='Auto 2')
+    event1 = make_event(payload={'automation_id': 'auto-1'}, dedup_key='dedup-1')
+    event2 = make_event(payload={'automation_id': 'auto-2'}, dedup_key='dedup-2')
+    event3 = make_event(payload={'automation_id': 'nonexistent'}, dedup_key='dedup-3')
+    async_session.add_all([auto1, auto2, event1, event2, event3])
+    await async_session.commit()
+
+    count = await process_new_events(async_session)
+
+    assert count == 3
+
+    # Two runs created (for auto-1 and auto-2), none for nonexistent
+    runs = (await async_session.execute(select(AutomationRun))).scalars().all()
+    assert len(runs) == 2
+
+    await async_session.refresh(event1)
+    await async_session.refresh(event2)
+    await async_session.refresh(event3)
+    assert event1.status == 'PROCESSED'
+    assert event2.status == 'PROCESSED'
+    assert event3.status == 'NO_MATCH'
+
+
+# ---------------------------------------------------------------------------
+# claim_and_execute_runs
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_claim_and_execute_runs_claims_pending(
+    async_session, async_session_factory
+):
+    """Claims a PENDING run and transitions to RUNNING."""
+    automation = make_automation()
+    run = make_run(run_id='run-1')
+    async_session.add_all([automation, run])
+    await async_session.commit()
+
+    api_client = AsyncMock()
+
+    with patch('services.automation_executor.execute_run', new_callable=AsyncMock):
+        claimed = await claim_and_execute_runs(
+            async_session, 'executor-test-1', api_client, async_session_factory
+        )
+
+    assert claimed is True
+
+    await async_session.refresh(run)
+    assert run.status == 'RUNNING'
+    assert run.claimed_by == 'executor-test-1'
+    assert run.claimed_at is not None
+    assert run.heartbeat_at is not None
+    assert run.started_at is not None
+
+
+@pytest.mark.asyncio
+async def test_claim_and_execute_runs_no_pending(async_session, async_session_factory):
+    """Returns False when no PENDING runs exist."""
+    api_client = AsyncMock()
+
+    claimed = await claim_and_execute_runs(
+        async_session, 'executor-test-1', api_client, async_session_factory
+    )
+
+    assert claimed is False
+
+
+@pytest.mark.asyncio
+async def test_claim_and_execute_runs_respects_next_retry_at(
+    async_session, async_session_factory
+):
+    """Runs with future next_retry_at are not claimed."""
+    automation = make_automation()
+    run = make_run(
+        run_id='run-retry',
+        next_retry_at=utc_now() + timedelta(hours=1),
+    )
+    async_session.add_all([automation, run])
+    await async_session.commit()
+
+    api_client = AsyncMock()
+
+    claimed = await claim_and_execute_runs(
+        async_session, 'executor-test-1', api_client, async_session_factory
+    )
+
+    assert claimed is False
+
+
+@pytest.mark.asyncio
+async def test_claim_and_execute_runs_past_retry_at(
+    async_session, async_session_factory
+):
+    """Runs with past next_retry_at are claimable."""
+    automation = make_automation()
+    run = make_run(
+        run_id='run-retry-past',
+        next_retry_at=utc_now() - timedelta(minutes=5),
+    )
+    async_session.add_all([automation, run])
+    await async_session.commit()
+
+    api_client = AsyncMock()
+
+    with patch('services.automation_executor.execute_run', new_callable=AsyncMock):
+        claimed = await claim_and_execute_runs(
+            async_session, 'executor-test-1', api_client, async_session_factory
+        )
+
+    assert claimed is True
+
+
+@pytest.mark.asyncio
+async def test_claim_skips_running_runs(async_session, async_session_factory):
+    """RUNNING runs are not claimed."""
+    automation = make_automation()
+    run = make_run(run_id='run-running', status='RUNNING', claimed_by='other-executor')
+    async_session.add_all([automation, run])
+    await async_session.commit()
+
+    api_client = AsyncMock()
+
+    claimed = await claim_and_execute_runs(
+        async_session, 'executor-test-1', api_client, async_session_factory
+    )
+
+    assert claimed is False
+
+
+# ---------------------------------------------------------------------------
+# recover_stale_runs
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_recover_stale_runs_recovers_stale(async_session):
+    """RUNNING runs with expired heartbeats are recovered to PENDING."""
+    automation = make_automation()
+    stale_run = make_run(
+        run_id='stale-1',
+        status='RUNNING',
+        claimed_by='crashed-executor',
+        heartbeat_at=utc_now() - timedelta(minutes=10),
+        retry_count=0,
+    )
+    async_session.add_all([automation, stale_run])
+    await async_session.commit()
+
+    count = await recover_stale_runs(async_session)
+
+    assert count >= 1
+
+    await async_session.refresh(stale_run)
+    assert stale_run.status == 'PENDING'
+    assert stale_run.claimed_by is None
+    assert stale_run.retry_count == 1
+    assert stale_run.next_retry_at is not None
+
+
+@pytest.mark.asyncio
+async def test_recover_stale_runs_ignores_fresh(async_session):
+    """RUNNING runs with recent heartbeats are not recovered."""
+    automation = make_automation()
+    fresh_run = make_run(
+        run_id='fresh-1',
+        status='RUNNING',
+        claimed_by='active-executor',
+        heartbeat_at=utc_now() - timedelta(seconds=30),
+    )
+    async_session.add_all([automation, fresh_run])
+    await async_session.commit()
+
+    count = await recover_stale_runs(async_session)
+
+    assert count == 0
+
+    await async_session.refresh(fresh_run)
+    assert fresh_run.status == 'RUNNING'
+    assert fresh_run.claimed_by == 'active-executor'
+
+
+@pytest.mark.asyncio
+async def test_recover_stale_runs_ignores_pending(async_session):
+    """PENDING runs are not affected by recovery."""
+    automation = make_automation()
+    pending_run = make_run(run_id='pending-1', status='PENDING')
+    async_session.add_all([automation, pending_run])
+    await async_session.commit()
+
+    count = await recover_stale_runs(async_session)
+
+    assert count == 0
+
+    await async_session.refresh(pending_run)
+    assert pending_run.status == 'PENDING'
+
+
+@pytest.mark.asyncio
+async def test_recover_stale_runs_increments_retry_count(async_session):
+    """Recovery increments the retry_count."""
+    automation = make_automation()
+    stale_run = make_run(
+        run_id='stale-retry',
+        status='RUNNING',
+        claimed_by='old-executor',
+        heartbeat_at=utc_now() - timedelta(minutes=10),
+        retry_count=2,
+    )
+    async_session.add_all([automation, stale_run])
+    await async_session.commit()
+
+    await recover_stale_runs(async_session)
+
+    await async_session.refresh(stale_run)
+    assert stale_run.retry_count == 3
+
+
+# ---------------------------------------------------------------------------
+# _mark_run_failed (error handling)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_mark_run_failed_retries(async_session_factory):
+    """Failed runs with retries left return to PENDING."""
+    async with async_session_factory() as session:
+        automation = make_automation()
+        run = make_run(run_id='fail-retry', retry_count=0, max_retries=3)
+        session.add_all([automation, run])
+        await session.commit()
+
+    async with async_session_factory() as session:
+        run_obj = await session.get(AutomationRun, 'fail-retry')
+        await _mark_run_failed(run_obj, 'API error', async_session_factory)
+
+    async with async_session_factory() as session:
+        run_obj = await session.get(AutomationRun, 'fail-retry')
+        assert run_obj.status == 'PENDING'
+        assert run_obj.retry_count == 1
+        assert run_obj.error_detail == 'API error'
+        assert run_obj.next_retry_at is not None
+        assert run_obj.claimed_by is None
+
+
+@pytest.mark.asyncio
+async def test_mark_run_failed_dead_letter(async_session_factory):
+    """Failed runs that exceed max_retries go to DEAD_LETTER."""
+    async with async_session_factory() as session:
+        automation = make_automation()
+        run = make_run(run_id='fail-dead', retry_count=2, max_retries=3)
+        session.add_all([automation, run])
+        await session.commit()
+
+    async with async_session_factory() as session:
+        run_obj = await session.get(AutomationRun, 'fail-dead')
+        await _mark_run_failed(run_obj, 'Final failure', async_session_factory)
+
+    async with async_session_factory() as session:
+        run_obj = await session.get(AutomationRun, 'fail-dead')
+        assert run_obj.status == 'DEAD_LETTER'
+        assert run_obj.retry_count == 3
+        assert run_obj.error_detail == 'Final failure'
+        assert run_obj.completed_at is not None
+
+
+# ---------------------------------------------------------------------------
+# is_terminal
+# ---------------------------------------------------------------------------
+
+
+def test_is_terminal_stopped():
+    assert is_terminal({'status': 'STOPPED'}) is True
+
+
+def test_is_terminal_error():
+    assert is_terminal({'status': 'ERROR'}) is True
+
+
+def test_is_terminal_completed():
+    assert is_terminal({'status': 'COMPLETED'}) is True
+
+
+def test_is_terminal_cancelled():
+    assert is_terminal({'status': 'CANCELLED'}) is True
+
+
+def test_is_terminal_running():
+    assert is_terminal({'status': 'RUNNING'}) is False
+
+
+def test_is_terminal_empty():
+    assert is_terminal({}) is False
+
+
+def test_is_terminal_case_insensitive():
+    assert is_terminal({'status': 'stopped'}) is True
+    assert is_terminal({'status': 'Completed'}) is True
+
+
+# ---------------------------------------------------------------------------
+# find_matching_automations — None payload
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_find_matching_automations_none_payload(async_session):
+    """Events with None payload return empty list (data corruption guard)."""
+    event = make_event(source_type='cron')
+    event.payload = None
+    async_session.add(event)
+    await async_session.commit()
+
+    result = await find_matching_automations(async_session, event)
+
+    assert result == []
+
+
+# ---------------------------------------------------------------------------
+# Integration: event → run creation → claim
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_integration_event_to_run_to_claim(
+    async_session_factory,
+):
+    """Full flow: create event + automation → process_new_events → claim_and_execute_runs.
+
+    Uses a real SQLite database; only the external API client is mocked.
+    """
+    # 1. Seed an automation and a NEW event
+    async with async_session_factory() as session:
+        automation = make_automation(automation_id='integ-auto')
+        event = make_event(
+            source_type='cron',
+            payload={'automation_id': 'integ-auto'},
+            dedup_key='integ-dedup',
+        )
+        session.add_all([automation, event])
+        await session.commit()
+        event_id = event.id
+
+    # 2. Process inbox — should match and create a PENDING run
+    async with async_session_factory() as session:
+        processed = await process_new_events(session)
+
+    assert processed == 1
+
+    # Verify event is PROCESSED and run was created
+    async with async_session_factory() as session:
+        evt = await session.get(AutomationEvent, event_id)
+        assert evt.status == 'PROCESSED'
+
+        runs = (await session.execute(select(AutomationRun))).scalars().all()
+        assert len(runs) == 1
+        run = runs[0]
+        assert run.automation_id == 'integ-auto'
+        assert run.status == 'PENDING'
+        assert run.event_payload == {'automation_id': 'integ-auto'}
+
+    # 3. Claim the run — mock execute_run to avoid real API calls
+    api_client = AsyncMock()
+
+    with patch('services.automation_executor.execute_run', new_callable=AsyncMock):
+        async with async_session_factory() as session:
+            claimed = await claim_and_execute_runs(
+                session, 'executor-integ', api_client, async_session_factory
+            )
+
+    assert claimed is True
+
+    # 4. Verify the run moved to RUNNING with correct executor
+    async with async_session_factory() as session:
+        runs = (await session.execute(select(AutomationRun))).scalars().all()
+        assert len(runs) == 1
+        run = runs[0]
+        assert run.status == 'RUNNING'
+        assert run.claimed_by == 'executor-integ'
+        assert run.started_at is not None
+        assert run.heartbeat_at is not None

enterprise/tests/unit/services/test_openhands_api_client.py

@@ -0,0 +1,185 @@
+"""Tests for OpenHandsAPIClient with mocked HTTP responses."""
+
+import base64
+
+import httpx
+import pytest
+from services.openhands_api_client import OpenHandsAPIClient
+
+
+@pytest.fixture
+def api_client():
+    client = OpenHandsAPIClient(base_url='http://test-server:3000')
+    yield client
+    # close handled in tests that need it
+
+
+# ---------------------------------------------------------------------------
+# start_conversation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_start_conversation_sends_correct_request(api_client, respx_mock):
+    """start_conversation sends properly formatted POST with auth header."""
+    automation_file = b'print("hello")'
+    expected_b64 = base64.b64encode(automation_file).decode()
+
+    route = respx_mock.post('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                'app_conversation_id': 'conv-123',
+                'status': 'RUNNING',
+            },
+        )
+    )
+
+    result = await api_client.start_conversation(
+        api_key='sk-oh-test123',
+        automation_file=automation_file,
+        title='Test Automation',
+        event_payload={'automation_id': 'auto-1'},
+    )
+
+    assert route.called
+    request = route.calls[0].request
+
+    assert request.headers['Authorization'] == 'Bearer sk-oh-test123'
+
+    import json
+
+    body = json.loads(request.content)
+    assert body['automation_file'] == expected_b64
+    assert body['trigger'] == 'automation'
+    assert body['title'] == 'Test Automation'
+    assert body['event_payload'] == {'automation_id': 'auto-1'}
+
+    assert result == {'app_conversation_id': 'conv-123', 'status': 'RUNNING'}
+
+
+@pytest.mark.asyncio
+async def test_start_conversation_without_event_payload(api_client, respx_mock):
+    """start_conversation works with event_payload=None."""
+    respx_mock.post('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(200, json={'app_conversation_id': 'conv-456'})
+    )
+
+    result = await api_client.start_conversation(
+        api_key='sk-oh-test',
+        automation_file=b'code',
+        title='Test',
+        event_payload=None,
+    )
+
+    assert result['app_conversation_id'] == 'conv-456'
+
+
+@pytest.mark.asyncio
+async def test_start_conversation_http_error(api_client, respx_mock):
+    """start_conversation raises on HTTP errors."""
+    respx_mock.post('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(500, json={'error': 'Internal Server Error'})
+    )
+
+    with pytest.raises(httpx.HTTPStatusError) as exc_info:
+        await api_client.start_conversation(
+            api_key='sk-oh-test',
+            automation_file=b'code',
+            title='Test',
+        )
+
+    assert exc_info.value.response.status_code == 500
+
+
+@pytest.mark.asyncio
+async def test_start_conversation_auth_error(api_client, respx_mock):
+    """start_conversation raises on 401 Unauthorized."""
+    respx_mock.post('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(401, json={'error': 'Unauthorized'})
+    )
+
+    with pytest.raises(httpx.HTTPStatusError) as exc_info:
+        await api_client.start_conversation(
+            api_key='bad-key',
+            automation_file=b'code',
+            title='Test',
+        )
+
+    assert exc_info.value.response.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# get_conversation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_get_conversation_returns_data(api_client, respx_mock):
+    """get_conversation returns the first conversation from the list."""
+    respx_mock.get('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(
+            200,
+            json=[
+                {
+                    'conversation_id': 'conv-123',
+                    'status': 'RUNNING',
+                    'title': 'My Automation',
+                }
+            ],
+        )
+    )
+
+    result = await api_client.get_conversation('sk-oh-test', 'conv-123')
+
+    assert result is not None
+    assert result['conversation_id'] == 'conv-123'
+    assert result['status'] == 'RUNNING'
+
+
+@pytest.mark.asyncio
+async def test_get_conversation_returns_none_when_empty(api_client, respx_mock):
+    """get_conversation returns None when API returns empty list."""
+    respx_mock.get('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(200, json=[])
+    )
+
+    result = await api_client.get_conversation('sk-oh-test', 'nonexistent')
+
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_get_conversation_sends_auth_header(api_client, respx_mock):
+    """get_conversation sends the correct authorization header."""
+    route = respx_mock.get('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(200, json=[])
+    )
+
+    await api_client.get_conversation('sk-oh-mykey', 'conv-1')
+
+    assert route.called
+    request = route.calls[0].request
+    assert request.headers['Authorization'] == 'Bearer sk-oh-mykey'
+
+
+@pytest.mark.asyncio
+async def test_get_conversation_http_error(api_client, respx_mock):
+    """get_conversation raises on HTTP errors."""
+    respx_mock.get('http://test-server:3000/api/v1/app-conversations').mock(
+        return_value=httpx.Response(503, text='Service Unavailable')
+    )
+
+    with pytest.raises(httpx.HTTPStatusError):
+        await api_client.get_conversation('sk-oh-test', 'conv-1')
+
+
+# ---------------------------------------------------------------------------
+# close
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_close(api_client):
+    """close() shuts down the HTTP client without errors."""
+    await api_client.close()

enterprise/tests/unit/test_saas_settings_store.py

@@ -1,3 +1,4 @@
+import uuid
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -233,3 +234,165 @@ async def test_ensure_api_key_generates_new_key_when_verification_fails(
 
         assert item.llm_api_key is not None
         assert item.llm_api_key.get_secret_value() == new_key
+
+
+@pytest.fixture
+def org_with_multiple_members_fixture(session_maker):
+    """Set up an organization with multiple members for testing LLM settings propagation.
+
+    Uses sync session to avoid UUID conversion issues with async SQLite.
+    """
+    from storage.encrypt_utils import decrypt_value
+    from storage.org import Org
+    from storage.org_member import OrgMember
+    from storage.role import Role
+    from storage.user import User
+
+    # Use realistic UUIDs that work well with SQLite
+    org_id = uuid.UUID('5594c7b6-f959-4b81-92e9-b09c206f5081')
+    admin_user_id = uuid.UUID('5594c7b6-f959-4b81-92e9-b09c206f5082')
+    member1_user_id = uuid.UUID('5594c7b6-f959-4b81-92e9-b09c206f5083')
+    member2_user_id = uuid.UUID('5594c7b6-f959-4b81-92e9-b09c206f5084')
+
+    with session_maker() as session:
+        # Create role
+        role = Role(id=10, name='member', rank=3)
+        session.add(role)
+
+        # Create org
+        org = Org(
+            id=org_id,
+            name='test-org',
+            org_version=1,
+            enable_default_condenser=True,
+            enable_proactive_conversation_starters=True,
+        )
+        session.add(org)
+
+        # Create users
+        admin_user = User(
+            id=admin_user_id, current_org_id=org_id, user_consents_to_analytics=True
+        )
+        session.add(admin_user)
+
+        member1_user = User(
+            id=member1_user_id, current_org_id=org_id, user_consents_to_analytics=True
+        )
+        session.add(member1_user)
+
+        member2_user = User(
+            id=member2_user_id, current_org_id=org_id, user_consents_to_analytics=True
+        )
+        session.add(member2_user)
+
+        # Create org members with DIFFERENT initial LLM settings
+        admin_member = OrgMember(
+            org_id=org_id,
+            user_id=admin_user_id,
+            role_id=10,
+            llm_api_key='admin-initial-key',
+            llm_model='old-model-v1',
+            llm_base_url='http://old-url-1.com',
+            max_iterations=10,
+            status='active',
+        )
+        session.add(admin_member)
+
+        member1 = OrgMember(
+            org_id=org_id,
+            user_id=member1_user_id,
+            role_id=10,
+            llm_api_key='member1-initial-key',
+            llm_model='old-model-v2',
+            llm_base_url='http://old-url-2.com',
+            max_iterations=20,
+            status='active',
+        )
+        session.add(member1)
+
+        member2 = OrgMember(
+            org_id=org_id,
+            user_id=member2_user_id,
+            role_id=10,
+            llm_api_key='member2-initial-key',
+            llm_model='old-model-v3',
+            llm_base_url='http://old-url-3.com',
+            max_iterations=30,
+            status='active',
+        )
+        session.add(member2)
+
+        session.commit()
+
+    return {
+        'org_id': org_id,
+        'admin_user_id': admin_user_id,
+        'member1_user_id': member1_user_id,
+        'member2_user_id': member2_user_id,
+        'decrypt_value': decrypt_value,
+    }
+
+
+@pytest.mark.asyncio
+async def test_store_propagates_llm_settings_to_all_org_members(
+    session_maker, async_session_maker, mock_config, org_with_multiple_members_fixture
+):
+    """When admin saves LLM settings, all org members should receive the updated settings.
+
+    This test verifies using a real database that:
+    1. The bulk UPDATE targets the correct organization (WHERE clause is correct)
+    2. All LLM fields are correctly set (llm_model, llm_base_url, max_iterations, llm_api_key)
+    3. The llm_api_key is properly encrypted
+    4. All members in the org receive the same updated values
+    """
+    from sqlalchemy import select
+    from storage.org_member import OrgMember
+
+    # Arrange
+    fixture = org_with_multiple_members_fixture
+    org_id = fixture['org_id']
+    admin_user_id = str(fixture['admin_user_id'])
+    decrypt_value = fixture['decrypt_value']
+
+    store = SaasSettingsStore(admin_user_id, mock_config)
+
+    new_settings = DataSettings(
+        llm_model='new-shared-model/gpt-4',
+        llm_base_url='http://new-shared-url.com',
+        max_iterations=100,
+        llm_api_key=SecretStr('new-shared-api-key'),
+    )
+
+    # Act - call store() with async session
+    with patch('storage.saas_settings_store.a_session_maker', async_session_maker):
+        await store.store(new_settings)
+
+    # Assert - verify ALL org members have the updated LLM settings using sync session
+    with session_maker() as session:
+        result = session.execute(select(OrgMember).where(OrgMember.org_id == org_id))
+        members = result.scalars().all()
+
+        # Verify we have all 3 members
+        assert len(members) == 3, f'Expected 3 org members, got {len(members)}'
+
+        for member in members:
+            # Verify LLM model is updated
+            assert (
+                member.llm_model == 'new-shared-model/gpt-4'
+            ), f'Expected llm_model to be updated for member {member.user_id}'
+
+            # Verify LLM base URL is updated
+            assert (
+                member.llm_base_url == 'http://new-shared-url.com'
+            ), f'Expected llm_base_url to be updated for member {member.user_id}'
+
+            # Verify max_iterations is updated
+            assert (
+                member.max_iterations == 100
+            ), f'Expected max_iterations to be 100 for member {member.user_id}'
+
+            # Verify the API key is encrypted and decrypts to the correct value
+            decrypted_key = decrypt_value(member._llm_api_key)
+            assert (
+                decrypted_key == 'new-shared-api-key'
+            ), f'Expected llm_api_key to decrypt to new-shared-api-key for member {member.user_id}'

frontend/__tests__/components/features/chat/task-tracking-observation-content.test.tsx

@@ -84,12 +84,12 @@ describe("TaskTrackingObservationContent", () => {
     expect(taskItems).toHaveLength(3);
   });
 
-  it("displays task IDs and notes", () => {
+  it("does not display task IDs but displays notes", () => {
     render(<TaskTrackingObservationContent event={mockEvent} />);
 
-    expect(screen.getByText("ID: task-1")).toBeInTheDocument();
-    expect(screen.getByText("ID: task-2")).toBeInTheDocument();
-    expect(screen.getByText("ID: task-3")).toBeInTheDocument();
+    expect(screen.queryByText("ID: task-1")).not.toBeInTheDocument();
+    expect(screen.queryByText("ID: task-2")).not.toBeInTheDocument();
+    expect(screen.queryByText("ID: task-3")).not.toBeInTheDocument();
 
     expect(screen.getByText("Notes: This is a test task")).toBeInTheDocument();
     expect(

frontend/__tests__/components/features/conversation/conversation-tabs-context-menu.test.tsx

@@ -0,0 +1,83 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ConversationTabsContextMenu } from "#/components/features/conversation/conversation-tabs/conversation-tabs-context-menu";
+
+const CONVERSATION_ID = "conv-abc123";
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: CONVERSATION_ID }),
+}));
+
+let mockHasTaskList = false;
+vi.mock("#/hooks/use-task-list", () => ({
+  useTaskList: () => ({
+    hasTaskList: mockHasTaskList,
+    taskList: [],
+  }),
+}));
+
+describe("ConversationTabsContextMenu", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    mockHasTaskList = false;
+  });
+
+  it("should render nothing when isOpen is false", () => {
+    const { container } = render(
+      <ConversationTabsContextMenu isOpen={false} onClose={vi.fn()} />,
+    );
+
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("should render all default tabs when open", () => {
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    const expectedTabs = [
+      "COMMON$PLANNER",
+      "COMMON$CHANGES",
+      "COMMON$CODE",
+      "COMMON$TERMINAL",
+      "COMMON$APP",
+      "COMMON$BROWSER",
+    ];
+    for (const tab of expectedTabs) {
+      expect(screen.getByText(tab)).toBeInTheDocument();
+    }
+  });
+
+  it("should re-pin a tab when clicking an unpinned tab", async () => {
+    const user = userEvent.setup();
+
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    const terminalItem = screen.getByText("COMMON$TERMINAL");
+
+    // Unpin
+    await user.click(terminalItem);
+    let storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.unpinnedTabs).toContain("terminal");
+
+    // Re-pin
+    await user.click(terminalItem);
+    storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.unpinnedTabs).not.toContain("terminal");
+  });
+
+  describe("with tasklist", () => {
+    beforeEach(() => {
+      mockHasTaskList = true;
+    });
+
+    it("should show tasklist in context menu when hasTaskList is true", () => {
+      render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+      expect(screen.getByText("COMMON$TASK_LIST")).toBeInTheDocument();
+    });
+  });
+});

frontend/__tests__/components/features/conversation/conversation-tabs.test.tsx

@@ -4,7 +4,6 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { MemoryRouter } from "react-router";
 import { ConversationTabs } from "#/components/features/conversation/conversation-tabs/conversation-tabs";
-import { ConversationTabsContextMenu } from "#/components/features/conversation/conversation-tabs/conversation-tabs-context-menu";
 import { useConversationStore } from "#/stores/conversation-store";
 
 const TASK_CONVERSATION_ID = "task-ec03fb2ab8604517b24af632b058c2fd";
@@ -16,6 +15,14 @@ vi.mock("#/hooks/use-conversation-id", () => ({
   useConversationId: () => ({ conversationId: mockConversationId }),
 }));
 
+let mockHasTaskList = false;
+vi.mock("#/hooks/use-task-list", () => ({
+  useTaskList: () => ({
+    hasTaskList: mockHasTaskList,
+    taskList: [],
+  }),
+}));
+
 const createWrapper = (conversationId: string) => {
   return ({ children }: { children: React.ReactNode }) => (
     <MemoryRouter initialEntries={[`/conversations/${conversationId}`]}>
@@ -31,6 +38,7 @@ describe("ConversationTabs localStorage behavior", () => {
     localStorage.clear();
     vi.resetAllMocks();
     mockConversationId = TASK_CONVERSATION_ID;
+    mockHasTaskList = false;
     useConversationStore.setState({
       selectedTab: null,
       isRightPanelShown: false,
@@ -71,47 +79,6 @@ describe("ConversationTabs localStorage behavior", () => {
       expect(parsed).toHaveProperty("rightPanelShown");
       expect(parsed).toHaveProperty("unpinnedTabs");
     });
-
-    it("should store unpinned tabs in consolidated key via context menu", async () => {
-      mockConversationId = REAL_CONVERSATION_ID;
-      const user = userEvent.setup();
-
-      render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
-
-      const terminalItem = screen.getByText("COMMON$TERMINAL");
-      await user.click(terminalItem);
-
-      const consolidatedKey = `conversation-state-${REAL_CONVERSATION_ID}`;
-      const storedState = localStorage.getItem(consolidatedKey);
-      expect(storedState).not.toBeNull();
-
-      const parsed = JSON.parse(storedState!);
-      expect(parsed.unpinnedTabs).toContain("terminal");
-    });
-
-    it("should hide a tab after unpinning it from context menu", async () => {
-      mockConversationId = REAL_CONVERSATION_ID;
-      const user = userEvent.setup();
-
-      render(
-        <>
-          <ConversationTabs />
-          <ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />
-        </>,
-        { wrapper: createWrapper(REAL_CONVERSATION_ID) },
-      );
-
-      expect(
-        screen.getByTestId("conversation-tab-terminal"),
-      ).toBeInTheDocument();
-
-      const terminalItem = screen.getByText("COMMON$TERMINAL");
-      await user.click(terminalItem);
-
-      expect(
-        screen.queryByTestId("conversation-tab-terminal"),
-      ).not.toBeInTheDocument();
-    });
   });
 
   describe("hook integration", () => {
@@ -205,4 +172,37 @@ describe("ConversationTabs localStorage behavior", () => {
       expect(storedState.selectedTab).toBe("browser");
     });
   });
+
+  describe("tasklist tab", () => {
+    beforeEach(() => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      mockHasTaskList = true;
+    });
+
+    it("should show tasklist tab when hasTaskList is true", () => {
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        screen.getByTestId("conversation-tab-tasklist"),
+      ).toBeInTheDocument();
+    });
+
+    it("should select tasklist tab when clicked", async () => {
+      const user = userEvent.setup();
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      const tasklistTab = screen.getByTestId("conversation-tab-tasklist");
+      await user.click(tasklistTab);
+
+      const { selectedTab, hasRightPanelToggled } =
+        useConversationStore.getState();
+      expect(selectedTab).toBe("tasklist");
+      expect(hasRightPanelToggled).toBe(true);
+    });
+  });
 });

frontend/__tests__/hooks/use-task-list.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useTaskList } from "#/hooks/use-task-list";
+import { useEventStore } from "#/stores/use-event-store";
+import type { OHEvent } from "#/stores/use-event-store";
+import type { TaskTrackingObservation } from "#/types/core/observations";
+
+function createV0TaskTrackingObservation(
+  id: number,
+  command: string,
+  taskList: TaskTrackingObservation["extras"]["task_list"],
+): TaskTrackingObservation {
+  return {
+    id,
+    source: "agent",
+    observation: "task_tracking",
+    message: "Task tracking update",
+    timestamp: `2025-07-01T00:00:0${id}Z`,
+    cause: 0,
+    content: "",
+    extras: {
+      command,
+      task_list: taskList,
+    },
+  };
+}
+
+function createV1TaskTrackerObservation(
+  id: string,
+  command: string,
+  taskList: Array<{
+    title: string;
+    notes: string;
+    status: "todo" | "in_progress" | "done";
+  }>,
+): OHEvent {
+  return {
+    id,
+    timestamp: `2025-07-01T00:00:0${id}Z`,
+    source: "environment",
+    tool_name: "task_tracker",
+    tool_call_id: `call_${id}`,
+    action_id: `action_${id}`,
+    observation: {
+      kind: "TaskTrackerObservation",
+      content: "Task list updated",
+      command,
+      task_list: taskList,
+    },
+  } as unknown as OHEvent;
+}
+
+beforeEach(() => {
+  useEventStore.setState({
+    events: [],
+    eventIds: new Set(),
+    uiEvents: [],
+  });
+});
+
+describe("useTaskList", () => {
+  it("returns empty taskList and hasTaskList=false when no events exist", () => {
+    const { result } = renderHook(() => useTaskList());
+
+    expect(result.current.taskList).toEqual([]);
+    expect(result.current.hasTaskList).toBe(false);
+  });
+
+  it("returns empty taskList when no task tracking observations exist", () => {
+    useEventStore.setState({
+      events: [
+        {
+          id: 1,
+          source: "user",
+          action: "message",
+          args: { content: "Hello", image_urls: [], file_urls: [] },
+          message: "Hello",
+          timestamp: "2025-07-01T00:00:01Z",
+        },
+      ],
+      eventIds: new Set([1]),
+      uiEvents: [],
+    });
+
+    const { result } = renderHook(() => useTaskList());
+
+    expect(result.current.taskList).toEqual([]);
+    expect(result.current.hasTaskList).toBe(false);
+  });
+
+  describe("v0 events", () => {
+    it('returns the task list from a TaskTrackingObservation with command="plan"', () => {
+      const tasks = [
+        { id: "1", title: "First task", status: "todo" as const },
+        { id: "2", title: "Second task", status: "in_progress" as const },
+      ];
+      const event = createV0TaskTrackingObservation(1, "plan", tasks);
+
+      useEventStore.setState({
+        events: [event],
+        eventIds: new Set([1]),
+        uiEvents: [event],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual(tasks);
+      expect(result.current.hasTaskList).toBe(true);
+    });
+
+    it('ignores TaskTrackingObservation events with command !== "plan"', () => {
+      const tasks = [{ id: "1", title: "First task", status: "todo" as const }];
+      const event = createV0TaskTrackingObservation(1, "update", tasks);
+
+      useEventStore.setState({
+        events: [event],
+        eventIds: new Set([1]),
+        uiEvents: [event],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual([]);
+      expect(result.current.hasTaskList).toBe(false);
+    });
+
+    it("returns the latest task list when multiple plan events exist", () => {
+      const earlyTasks = [
+        { id: "1", title: "First task", status: "todo" as const },
+      ];
+      const lateTasks = [
+        { id: "1", title: "First task", status: "done" as const },
+        { id: "2", title: "New task", status: "in_progress" as const },
+      ];
+
+      const event1 = createV0TaskTrackingObservation(1, "plan", earlyTasks);
+      const event2 = createV0TaskTrackingObservation(2, "plan", lateTasks);
+
+      useEventStore.setState({
+        events: [event1, event2],
+        eventIds: new Set([1, 2]),
+        uiEvents: [event1, event2],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual(lateTasks);
+      expect(result.current.hasTaskList).toBe(true);
+    });
+
+    it("updates when new events are added to the store", () => {
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.hasTaskList).toBe(false);
+
+      const tasks = [{ id: "1", title: "New task", status: "todo" as const }];
+      const event = createV0TaskTrackingObservation(1, "plan", tasks);
+
+      act(() => {
+        useEventStore.setState({
+          events: [event],
+          eventIds: new Set([1]),
+          uiEvents: [event],
+        });
+      });
+
+      expect(result.current.taskList).toEqual(tasks);
+      expect(result.current.hasTaskList).toBe(true);
+    });
+
+    it("returns hasTaskList=false when the latest plan has an empty task list", () => {
+      const event = createV0TaskTrackingObservation(1, "plan", []);
+
+      useEventStore.setState({
+        events: [event],
+        eventIds: new Set([1]),
+        uiEvents: [event],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual([]);
+      expect(result.current.hasTaskList).toBe(false);
+    });
+  });
+
+  describe("v1 events", () => {
+    it('returns the task list from a v1 TaskTrackerObservation with command="plan"', () => {
+      const tasks = [
+        { title: "First task", notes: "", status: "todo" as const },
+        {
+          title: "Second task",
+          notes: "some note",
+          status: "in_progress" as const,
+        },
+      ];
+      const event = createV1TaskTrackerObservation("1", "plan", tasks);
+
+      useEventStore.setState({
+        events: [event],
+        eventIds: new Set(["1"]),
+        uiEvents: [event],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual([
+        { id: "1", title: "First task", notes: undefined, status: "todo" },
+        {
+          id: "2",
+          title: "Second task",
+          notes: "some note",
+          status: "in_progress",
+        },
+      ]);
+      expect(result.current.hasTaskList).toBe(true);
+    });
+
+    it('ignores v1 TaskTrackerObservation with command !== "plan"', () => {
+      const tasks = [
+        { title: "First task", notes: "", status: "todo" as const },
+      ];
+      const event = createV1TaskTrackerObservation("1", "view", tasks);
+
+      useEventStore.setState({
+        events: [event],
+        eventIds: new Set(["1"]),
+        uiEvents: [event],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual([]);
+      expect(result.current.hasTaskList).toBe(false);
+    });
+
+    it("returns the latest v1 task list when multiple plan events exist", () => {
+      const earlyTasks = [
+        { title: "First task", notes: "", status: "todo" as const },
+      ];
+      const lateTasks = [
+        { title: "First task", notes: "", status: "done" as const },
+        { title: "New task", notes: "wip", status: "in_progress" as const },
+      ];
+
+      const event1 = createV1TaskTrackerObservation("1", "plan", earlyTasks);
+      const event2 = createV1TaskTrackerObservation("2", "plan", lateTasks);
+
+      useEventStore.setState({
+        events: [event1, event2],
+        eventIds: new Set(["1", "2"]),
+        uiEvents: [event1, event2],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual([
+        { id: "1", title: "First task", notes: undefined, status: "done" },
+        { id: "2", title: "New task", notes: "wip", status: "in_progress" },
+      ]);
+      expect(result.current.hasTaskList).toBe(true);
+    });
+
+    it("returns hasTaskList=false when the latest v1 plan has an empty task list", () => {
+      const event = createV1TaskTrackerObservation("1", "plan", []);
+
+      useEventStore.setState({
+        events: [event],
+        eventIds: new Set(["1"]),
+        uiEvents: [event],
+      });
+
+      const { result } = renderHook(() => useTaskList());
+
+      expect(result.current.taskList).toEqual([]);
+      expect(result.current.hasTaskList).toBe(false);
+    });
+  });
+});

frontend/__tests__/routes/login.test.tsx

@@ -2,7 +2,7 @@ import { render, screen, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import userEvent from "@testing-library/user-event";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { createRoutesStub } from "react-router";
+import { createRoutesStub, useSearchParams } from "react-router";
 import LoginPage from "#/routes/login";
 import OptionService from "#/api/option-service/option-service.api";
 import AuthService from "#/api/auth-service/auth-service.api";
@@ -80,6 +80,29 @@ const RouterStub = createRoutesStub([
   },
 ]);
 
+function DestinationStub() {
+  const [params] = useSearchParams();
+  const loginMethod = params.get("login_method");
+  return (
+    <div data-testid="destination-page">
+      {loginMethod && (
+        <span data-testid="login-method-param">{loginMethod}</span>
+      )}
+    </div>
+  );
+}
+
+const RouterStubWithDestination = createRoutesStub([
+  {
+    Component: LoginPage,
+    path: "/login",
+  },
+  {
+    Component: DestinationStub,
+    path: "/settings",
+  },
+]);
+
 const createWrapper = () => {
   const queryClient = new QueryClient({
     defaultOptions: {
@@ -282,7 +305,9 @@ describe("LoginPage", () => {
       await user.click(gitlabButton);
 
       // URL includes state parameter added by handleAuthRedirect
-      expect(window.location.href).toContain("https://gitlab.com/oauth/authorize");
+      expect(window.location.href).toContain(
+        "https://gitlab.com/oauth/authorize",
+      );
     });
 
     it("should redirect to Bitbucket auth URL when Bitbucket button is clicked", async () => {
@@ -347,6 +372,30 @@ describe("LoginPage", () => {
       );
     });
 
+    it("should preserve login_method param when redirecting authenticated users", async () => {
+      // Arrange
+      vi.spyOn(AuthService, "authenticate").mockResolvedValue(true);
+
+      // Act
+      render(
+        <RouterStubWithDestination
+          initialEntries={["/login?returnTo=/settings&login_method=github"]}
+        />,
+        { wrapper: createWrapper() },
+      );
+
+      // Assert
+      await waitFor(
+        () => {
+          expect(screen.getByTestId("destination-page")).toBeInTheDocument();
+          expect(screen.getByTestId("login-method-param")).toHaveTextContent(
+            "github",
+          );
+        },
+        { timeout: 2000 },
+      );
+    });
+
     it("should redirect OSS mode users to home", async () => {
       // @ts-expect-error - partial mock for testing
       vi.spyOn(OptionService, "getConfig").mockResolvedValue({
@@ -552,10 +601,12 @@ describe("LoginPage", () => {
 
     it("should pass buildOAuthStateData to LoginContent for OAuth state encoding", async () => {
       const user = userEvent.setup();
-      const mockBuildOAuthStateData = vi.fn((baseState: Record<string, string>) => ({
-        ...baseState,
-        invitation_token: "inv-test-token-12345",
-      }));
+      const mockBuildOAuthStateData = vi.fn(
+        (baseState: Record<string, string>) => ({
+          ...baseState,
+          invitation_token: "inv-test-token-12345",
+        }),
+      );
 
       useInvitationMock.mockReturnValue({
         invitationToken: "inv-test-token-12345",
@@ -585,10 +636,12 @@ describe("LoginPage", () => {
 
     it("should include invitation token in OAuth state when invitation is present", async () => {
       const user = userEvent.setup();
-      const mockBuildOAuthStateData = vi.fn((baseState: Record<string, string>) => ({
-        ...baseState,
-        invitation_token: "inv-test-token-12345",
-      }));
+      const mockBuildOAuthStateData = vi.fn(
+        (baseState: Record<string, string>) => ({
+          ...baseState,
+          invitation_token: "inv-test-token-12345",
+        }),
+      );
 
       useInvitationMock.mockReturnValue({
         invitationToken: "inv-test-token-12345",
@@ -634,9 +687,14 @@ describe("LoginPage", () => {
         clearInvitation: vi.fn(),
       });
 
-      render(<RouterStub initialEntries={["/login?invitation_token=inv-url-token-67890"]} />, {
-        wrapper: createWrapper(),
-      });
+      render(
+        <RouterStub
+          initialEntries={["/login?invitation_token=inv-url-token-67890"]}
+        />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
 
       await waitFor(() => {
         expect(screen.getByText("AUTH$INVITATION_PENDING")).toBeInTheDocument();

frontend/__tests__/routes/root-layout.test.tsx

@@ -366,6 +366,130 @@ describe("MainApp", () => {
     });
   });
 
+  describe("Re-authentication with stored login method", () => {
+    it("should show ReauthModal instead of redirecting to /login when login method exists", async () => {
+      // Arrange - user is unauthenticated but has a stored login method
+      vi.spyOn(AuthService, "authenticate").mockRejectedValue({
+        response: { status: 401 },
+        isAxiosError: true,
+      });
+
+      vi.stubGlobal("localStorage", {
+        getItem: vi.fn((key: string) => {
+          if (key === "openhands_login_method") {
+            return "github";
+          }
+          return null;
+        }),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+      });
+
+      // Act
+      renderWithLoginStub(RouterStubWithLogin, ["/"]);
+
+      // Assert - should show ReauthModal (with "Logging back in" text), not redirect to /login
+      await waitFor(
+        () => {
+          expect(screen.getByText("AUTH$LOGGING_BACK_IN")).toBeInTheDocument();
+        },
+        { timeout: 2000 },
+      );
+
+      // Login page should NOT be shown when login method exists
+      expect(screen.queryByTestId("login-page")).not.toBeInTheDocument();
+    });
+
+    it("should redirect to /login when no login method is stored", async () => {
+      // Arrange - user is unauthenticated and has no stored login method
+      vi.spyOn(AuthService, "authenticate").mockRejectedValue({
+        response: { status: 401 },
+        isAxiosError: true,
+      });
+
+      vi.stubGlobal("localStorage", {
+        getItem: vi.fn(() => null),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+      });
+
+      // Act
+      renderWithLoginStub(RouterStubWithLogin, ["/"]);
+
+      // Assert - should redirect to /login
+      await waitFor(
+        () => {
+          expect(screen.getByTestId("login-page")).toBeInTheDocument();
+        },
+        { timeout: 2000 },
+      );
+    });
+  });
+
+  describe("Loading states", () => {
+    it("should show loading spinner while config is loading without redirecting", async () => {
+      // Arrange - config never resolves (loading state)
+      vi.spyOn(OptionService, "getConfig").mockImplementation(
+        () => new Promise(() => {}),
+      );
+
+      vi.stubGlobal("localStorage", {
+        getItem: vi.fn((key: string) => {
+          if (key === "openhands_login_method") {
+            return "github";
+          }
+          return null;
+        }),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+      });
+
+      // Act
+      renderWithLoginStub(RouterStubWithLogin, ["/"]);
+
+      // Assert - should show loading spinner
+      await waitFor(() => {
+        expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+      });
+
+      // Should NOT redirect to login while loading
+      expect(screen.queryByTestId("login-page")).not.toBeInTheDocument();
+    });
+
+    it("should show loading spinner while auth is loading without redirecting", async () => {
+      // Arrange - auth never resolves (loading state)
+      vi.spyOn(AuthService, "authenticate").mockImplementation(
+        () => new Promise(() => {}),
+      );
+
+      vi.stubGlobal("localStorage", {
+        getItem: vi.fn((key: string) => {
+          if (key === "openhands_login_method") {
+            return "github";
+          }
+          return null;
+        }),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+      });
+
+      // Act
+      renderWithLoginStub(RouterStubWithLogin, ["/"]);
+
+      // Assert - should show loading spinner
+      await waitFor(() => {
+        expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+      });
+
+      // Should NOT redirect to login while loading
+      expect(screen.queryByTestId("login-page")).not.toBeInTheDocument();
+    });
+  });
+
   describe("Invitation URL Parameters", () => {
     beforeEach(() => {
       vi.spyOn(AuthService, "authenticate").mockRejectedValue({

frontend/__tests__/routes/task-list-tab.test.tsx

@@ -0,0 +1,167 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import TaskListTab from "#/routes/task-list-tab";
+import { useEventStore } from "#/stores/use-event-store";
+import type { TaskTrackingObservation } from "#/types/core/observations";
+
+// Mock i18n
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        COMMON$NO_TASKS: "No tasks yet",
+        TASK_TRACKING_OBSERVATION$TASK_NOTES: "Notes",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+function createTaskTrackingObservation(
+  id: number,
+  tasks: TaskTrackingObservation["extras"]["task_list"],
+): TaskTrackingObservation {
+  return {
+    id,
+    source: "agent",
+    observation: "task_tracking",
+    message: "Task tracking update",
+    timestamp: `2025-07-01T00:00:0${id}Z`,
+    cause: 0,
+    content: "",
+    extras: {
+      command: "plan",
+      task_list: tasks,
+    },
+  };
+}
+
+function setTasks(tasks: TaskTrackingObservation["extras"]["task_list"]) {
+  const event = createTaskTrackingObservation(1, tasks);
+  useEventStore.setState({
+    events: [event],
+    eventIds: new Set([1]),
+    uiEvents: [event],
+  });
+}
+
+beforeEach(() => {
+  useEventStore.setState({
+    events: [],
+    eventIds: new Set(),
+    uiEvents: [],
+  });
+});
+
+describe("TaskListTab", () => {
+  it("renders empty state with icon and message when there are no tasks", () => {
+    const { container } = render(<TaskListTab />);
+
+    expect(screen.getByText("No tasks yet")).toBeInTheDocument();
+    // Empty state should show the check-circle icon (rendered as SVG)
+    expect(container.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("renders empty state message using Text component (span)", () => {
+    render(<TaskListTab />);
+
+    const message = screen.getByText("No tasks yet");
+    expect(message.tagName).toBe("SPAN");
+  });
+
+  it("renders task items when tasks exist", () => {
+    setTasks([
+      { id: "1", title: "Implement feature", status: "todo" },
+      { id: "2", title: "Write tests", status: "in_progress" },
+      { id: "3", title: "Deploy", status: "done" },
+    ]);
+
+    const { container } = render(<TaskListTab />);
+
+    expect(screen.getByText("Implement feature")).toBeInTheDocument();
+    expect(screen.getByText("Write tests")).toBeInTheDocument();
+    expect(screen.getByText("Deploy")).toBeInTheDocument();
+
+    const taskItems = container.querySelectorAll('[data-name="item"]');
+    expect(taskItems).toHaveLength(3);
+  });
+
+  it("does not display task IDs", () => {
+    setTasks([
+      { id: "task-1", title: "First task", status: "todo" },
+    ]);
+
+    render(<TaskListTab />);
+
+    expect(screen.queryByText(/task-1/)).not.toBeInTheDocument();
+  });
+
+  it("highlights in_progress tasks with a background", () => {
+    setTasks([
+      { id: "1", title: "Todo task", status: "todo" },
+      { id: "2", title: "Active task", status: "in_progress" },
+      { id: "3", title: "Done task", status: "done" },
+    ]);
+
+    render(<TaskListTab />);
+
+    // Find each task item via its text, then check the wrapper div
+    const activeItem = screen.getByText("Active task").closest("[data-name]");
+    const activeWrapper = activeItem?.parentElement;
+    expect(activeWrapper?.className).toContain("bg-[#2D3039]");
+
+    const todoItem = screen.getByText("Todo task").closest("[data-name]");
+    expect(todoItem?.parentElement?.className).not.toContain("bg-[#2D3039]");
+
+    const doneItem = screen.getByText("Done task").closest("[data-name]");
+    expect(doneItem?.parentElement?.className).not.toContain("bg-[#2D3039]");
+  });
+
+  it("displays task notes when present and omits when absent", () => {
+    setTasks([
+      {
+        id: "1",
+        title: "Task with notes",
+        status: "todo",
+        notes: "Important note",
+      },
+      { id: "2", title: "Task without notes", status: "todo" },
+    ]);
+
+    render(<TaskListTab />);
+
+    expect(screen.getByText("Notes: Important note")).toBeInTheDocument();
+    expect(screen.getAllByText(/^Notes:/)).toHaveLength(1);
+  });
+
+  it("uses the latest plan event when multiple exist", () => {
+    const event1 = createTaskTrackingObservation(1, [
+      { id: "1", title: "Old task", status: "todo" },
+    ]);
+    const event2 = createTaskTrackingObservation(2, [
+      { id: "1", title: "Updated task", status: "done" },
+      { id: "2", title: "New task", status: "in_progress" },
+    ]);
+
+    useEventStore.setState({
+      events: [event1, event2],
+      eventIds: new Set([1, 2]),
+      uiEvents: [event1, event2],
+    });
+
+    render(<TaskListTab />);
+
+    expect(screen.queryByText("Old task")).not.toBeInTheDocument();
+    expect(screen.getByText("Updated task")).toBeInTheDocument();
+    expect(screen.getByText("New task")).toBeInTheDocument();
+  });
+
+  it("renders as a scrollable main element when tasks exist", () => {
+    setTasks([{ id: "1", title: "A task", status: "todo" }]);
+
+    render(<TaskListTab />);
+
+    const main = screen.getByRole("main");
+    expect(main).toBeInTheDocument();
+  });
+});

frontend/__tests__/utils/get-git-path.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { getGitPath } from "#/utils/get-git-path";
+
+describe("getGitPath", () => {
+  it("should return /workspace/project when no repository is selected", () => {
+    expect(getGitPath(null)).toBe("/workspace/project");
+    expect(getGitPath(undefined)).toBe("/workspace/project");
+  });
+
+  it("should handle standard owner/repo format (GitHub)", () => {
+    expect(getGitPath("OpenHands/OpenHands")).toBe("/workspace/project/OpenHands");
+    expect(getGitPath("facebook/react")).toBe("/workspace/project/react");
+  });
+
+  it("should handle nested group paths (GitLab)", () => {
+    expect(getGitPath("modernhealth/frontend-guild/pan")).toBe("/workspace/project/pan");
+    expect(getGitPath("group/subgroup/repo")).toBe("/workspace/project/repo");
+    expect(getGitPath("a/b/c/d/repo")).toBe("/workspace/project/repo");
+  });
+
+  it("should handle single segment paths", () => {
+    expect(getGitPath("repo")).toBe("/workspace/project/repo");
+  });
+
+  it("should handle empty string", () => {
+    expect(getGitPath("")).toBe("/workspace/project");
+  });
+});

frontend/src/components/features/chat/task-tracking/task-item.tsx

@@ -35,23 +35,17 @@ export function TaskItem({ task }: TaskItemProps) {
   const isDoneStatus = task.status === "done";
 
   return (
-    <div
-      className="flex gap-[14px] items-center px-4 py-2 w-full"
-      data-name="item"
-    >
+    <div className="flex gap-2 items-center w-full" data-name="item">
       <div className="shrink-0">{icon}</div>
-      <div className="flex flex-col items-start justify-center leading-[20px] text-nowrap whitespace-pre font-normal">
+      <div className="flex flex-col items-start justify-center leading-[16px] text-nowrap whitespace-pre font-normal">
         <Typography.Text
           className={cn(
-            "text-[12px] text-white",
-            isDoneStatus && "text-[#A3A3A3]",
+            "text-[12px]",
+            isDoneStatus ? "text-[#A3A3A3]" : "text-white",
           )}
         >
           {task.title}
         </Typography.Text>
-        <Typography.Text className="text-[10px] text-[#A3A3A3] font-normal">
-          {t(I18nKey.TASK_TRACKING_OBSERVATION$TASK_ID)}: {task.id}
-        </Typography.Text>
         {task.notes && (
           <Typography.Text className="text-[10px] text-[#A3A3A3]">
             {t(I18nKey.TASK_TRACKING_OBSERVATION$TASK_NOTES)}: {task.notes}

frontend/src/components/features/conversation/conversation-tabs/conversation-tab-content/conversation-tab-content.tsx

@@ -16,8 +16,13 @@ const BrowserTab = lazy(() => import("#/routes/browser-tab"));
 const ServedTab = lazy(() => import("#/routes/served-tab"));
 const VSCodeTab = lazy(() => import("#/routes/vscode-tab"));
 const PlannerTab = lazy(() => import("#/routes/planner-tab"));
+const TaskListTab = lazy(() => import("#/routes/task-list-tab"));
 
 const TAB_CONFIG = {
+  tasklist: {
+    component: TaskListTab,
+    titleKey: I18nKey.COMMON$TASK_LIST,
+  },
   editor: {
     component: EditorTab,
     titleKey: I18nKey.COMMON$CHANGES,

frontend/src/components/features/conversation/conversation-tabs/conversation-tab-nav.tsx

@@ -27,7 +27,7 @@ export function ConversationTabNav({
       data-testid={`conversation-tab-${tabValue}`}
       className={cn(
         "flex items-center gap-2 rounded-md cursor-pointer",
-        "pl-1.5 pr-2 py-1",
+        "pl-1.5 pr-2 py-1 lg:py-1.5",
         "text-[#9299AA] bg-[#0D0F11]",
         isActive && "bg-[#25272D] text-white",
         isActive

frontend/src/components/features/conversation/conversation-tabs/conversation-tabs-context-menu.tsx

@@ -13,6 +13,8 @@ import VSCodeIcon from "#/icons/vscode.svg?react";
 import PillIcon from "#/icons/pill.svg?react";
 import PillFillIcon from "#/icons/pill-fill.svg?react";
 import LessonPlanIcon from "#/icons/lesson-plan.svg?react";
+import DoubleCheckIcon from "#/icons/double-check.svg?react";
+import { useTaskList } from "#/hooks/use-task-list";
 
 interface ConversationTabsContextMenuProps {
   isOpen: boolean;
@@ -29,6 +31,8 @@ export function ConversationTabsContextMenu({
   const { state, setUnpinnedTabs } =
     useConversationLocalStorageState(conversationId);
 
+  const { hasTaskList } = useTaskList();
+
   const tabConfig = [
     {
       tab: "planner",
@@ -42,6 +46,14 @@ export function ConversationTabsContextMenu({
     { tab: "browser", icon: GlobeIcon, i18nKey: I18nKey.COMMON$BROWSER },
   ];
 
+  if (hasTaskList) {
+    tabConfig.unshift({
+      tab: "tasklist",
+      icon: DoubleCheckIcon,
+      i18nKey: I18nKey.COMMON$TASK_LIST,
+    });
+  }
+
   if (!isOpen) return null;
 
   const handleTabClick = (tab: string) => {

frontend/src/components/features/conversation/conversation-tabs/conversation-tabs.tsx

@@ -7,6 +7,7 @@ import GitChanges from "#/icons/git_changes.svg?react";
 import VSCodeIcon from "#/icons/vscode.svg?react";
 import ThreeDotsVerticalIcon from "#/icons/three-dots-vertical.svg?react";
 import LessonPlanIcon from "#/icons/lesson-plan.svg?react";
+import DoubleCheckIcon from "#/icons/double-check.svg?react";
 import { cn } from "#/utils/utils";
 import { useConversationLocalStorageState } from "#/utils/conversation-local-storage";
 import { ConversationTabNav } from "./conversation-tab-nav";
@@ -17,6 +18,7 @@ import { useConversationStore } from "#/stores/conversation-store";
 import { ConversationTabsContextMenu } from "./conversation-tabs-context-menu";
 import { useConversationId } from "#/hooks/use-conversation-id";
 import { useSelectConversationTab } from "#/hooks/use-select-conversation-tab";
+import { useTaskList } from "#/hooks/use-task-list";
 
 export function ConversationTabs() {
   const { conversationId } = useConversationId();
@@ -27,6 +29,8 @@ export function ConversationTabs() {
   const { state: persistedState } =
     useConversationLocalStorageState(conversationId);
 
+  const { hasTaskList } = useTaskList();
+
   const {
     selectTab,
     isTabActive,
@@ -120,6 +124,18 @@ export function ConversationTabs() {
     },
   ];
 
+  if (hasTaskList) {
+    tabs.unshift({
+      tabValue: "tasklist",
+      isActive: isTabActive("tasklist"),
+      icon: DoubleCheckIcon,
+      onClick: () => selectTab("tasklist"),
+      tooltipContent: t(I18nKey.COMMON$TASK_LIST),
+      tooltipAriaLabel: t(I18nKey.COMMON$TASK_LIST),
+      label: t(I18nKey.COMMON$TASK_LIST),
+    });
+  }
+
   // Filter out unpinned tabs
   const visibleTabs = tabs.filter(
     (tab) => !persistedState.unpinnedTabs.includes(tab.tabValue),

frontend/src/hooks/use-task-list.ts

@@ -0,0 +1,64 @@
+import { useMemo } from "react";
+import { useEventStore } from "#/stores/use-event-store";
+import type { OHEvent } from "#/stores/use-event-store";
+import { isTaskTrackingObservation } from "#/types/core/guards";
+import type { OpenHandsParsedEvent } from "#/types/core";
+import { isObservationEvent } from "#/types/v1/type-guards";
+import type { OpenHandsEvent } from "#/types/v1/core";
+import type { TaskTrackerObservation } from "#/types/v1/core/base/observation";
+import type { ObservationEvent } from "#/types/v1/core/events/observation-event";
+
+export interface TaskListItem {
+  id: string;
+  title: string;
+  status: "todo" | "in_progress" | "done";
+  notes?: string;
+}
+
+function getTaskListFromEvent(event: OHEvent): TaskListItem[] | null {
+  // v0 event format: observation is a string "task_tracking"
+  const v0 = event as OpenHandsParsedEvent;
+  if (isTaskTrackingObservation(v0) && v0.extras.command === "plan") {
+    return v0.extras.task_list.map((t) => ({
+      id: t.id,
+      title: t.title,
+      status: t.status,
+      notes: t.notes,
+    }));
+  }
+
+  // v1 event format: observation is an object with kind "TaskTrackerObservation"
+  const v1 = event as OpenHandsEvent;
+  if (
+    isObservationEvent(v1) &&
+    v1.observation.kind === "TaskTrackerObservation"
+  ) {
+    const obs = (v1 as ObservationEvent<TaskTrackerObservation>).observation;
+    if (obs.command === "plan") {
+      return obs.task_list.map((t, i) => ({
+        id: String(i + 1),
+        title: t.title,
+        status: t.status,
+        notes: t.notes || undefined,
+      }));
+    }
+  }
+
+  return null;
+}
+
+export function useTaskList() {
+  const events = useEventStore((state) => state.events);
+
+  return useMemo(() => {
+    // Iterate in reverse to find the latest TaskTrackingObservation with command="plan"
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const taskList = getTaskListFromEvent(events[i]);
+      if (taskList) {
+        return { taskList, hasTaskList: taskList.length > 0 };
+      }
+    }
+
+    return { taskList: [] as TaskListItem[], hasTaskList: false };
+  }, [events]);
+}

frontend/src/i18n/declaration.ts

@@ -993,6 +993,8 @@ export enum I18nKey {
   COMMON$MORE_OPTIONS = "COMMON$MORE_OPTIONS",
   COMMON$CREATE_A_PLAN = "COMMON$CREATE_A_PLAN",
   COMMON$TASKS = "COMMON$TASKS",
+  COMMON$TASK_LIST = "COMMON$TASK_LIST",
+  COMMON$NO_TASKS = "COMMON$NO_TASKS",
   COMMON$PLAN_MD = "COMMON$PLAN_MD",
   COMMON$READ_MORE = "COMMON$READ_MORE",
   COMMON$BUILD = "COMMON$BUILD",

frontend/src/i18n/translation.json

@@ -15891,6 +15891,38 @@
     "de": "Aufgaben",
     "uk": "Завдання"
   },
+  "COMMON$TASK_LIST": {
+    "en": "Task List",
+    "ja": "タスクリスト",
+    "zh-CN": "任务列表",
+    "zh-TW": "任務列表",
+    "ko-KR": "작업 목록",
+    "no": "Oppgaveliste",
+    "it": "Elenco attività",
+    "pt": "Lista de tarefas",
+    "es": "Lista de tareas",
+    "ar": "قائمة المهام",
+    "fr": "Liste des tâches",
+    "tr": "Görev listesi",
+    "de": "Aufgabenliste",
+    "uk": "Список завдань"
+  },
+  "COMMON$NO_TASKS": {
+    "en": "No tasks yet",
+    "ja": "タスクはまだありません",
+    "zh-CN": "暂无任务",
+    "zh-TW": "尚無任務",
+    "ko-KR": "아직 작업이 없습니다",
+    "no": "Ingen oppgaver ennå",
+    "it": "Nessuna attività",
+    "pt": "Nenhuma tarefa ainda",
+    "es": "Sin tareas aún",
+    "ar": "لا توجد مهام بعد",
+    "fr": "Aucune tâche pour le moment",
+    "tr": "Henüz görev yok",
+    "de": "Noch keine Aufgaben",
+    "uk": "Завдань поки немає"
+  },
   "COMMON$PLAN_MD": {
     "en": "Plan.md",
     "ja": "Plan.md",

frontend/src/icons/double-check.svg

@@ -0,0 +1,4 @@
+<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M3 10.5L6.5 14L14 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M7 10.5L10.5 14L18 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

frontend/src/routes/login.tsx

@@ -40,11 +40,18 @@ export default function LoginPage() {
   }, [config.isLoading, config.data?.app_mode, navigate]);
 
   // Redirect authenticated users away from login page
+  // Preserve login_method param so useAuthCallback can store it for auto-login
   React.useEffect(() => {
     if (!isAuthLoading && isAuthed) {
-      navigate(returnTo, { replace: true });
+      const loginMethod = searchParams.get("login_method");
+      let destination = returnTo;
+      if (loginMethod) {
+        const separator = returnTo.includes("?") ? "&" : "?";
+        destination = `${returnTo}${separator}login_method=${encodeURIComponent(loginMethod)}`;
+      }
+      navigate(destination, { replace: true });
     }
-  }, [isAuthed, isAuthLoading, navigate, returnTo]);
+  }, [isAuthed, isAuthLoading, navigate, returnTo, searchParams]);
 
   if (isAuthLoading || config.isLoading) {
     return (

frontend/src/routes/root-layout.tsx

@@ -173,14 +173,17 @@ export default function MainApp() {
     setLoginMethodExists(checkLoginMethodExists());
   }, [isAuthed, checkLoginMethodExists]);
 
+  // Show loading spinner while config or auth is loading
+  const isLoading = config.isLoading || isAuthLoading;
+
+  // Only decide to redirect AFTER loading completes
   const shouldRedirectToLogin =
-    config.isLoading ||
-    isAuthLoading ||
-    (!isAuthed &&
-      !isAuthError &&
-      !isOnIntermediatePage &&
-      config.data?.app_mode === "saas" &&
-      !loginMethodExists);
+    !isLoading &&
+    !isAuthed &&
+    !isAuthError &&
+    !isOnIntermediatePage &&
+    config.data?.app_mode === "saas" &&
+    !loginMethodExists;
 
   React.useEffect(() => {
     if (shouldRedirectToLogin) {
@@ -197,7 +200,8 @@ export default function MainApp() {
     }
   }, [shouldRedirectToLogin, pathname, searchParams, navigate]);
 
-  if (shouldRedirectToLogin) {
+  // Show loading spinner while loading OR when about to redirect
+  if (isLoading || shouldRedirectToLogin) {
     return (
       <div className="min-h-screen flex items-center justify-center bg-base">
         <LoadingSpinner size="large" />

frontend/src/routes/task-list-tab.tsx

@@ -0,0 +1,41 @@
+import { useTranslation } from "react-i18next";
+import { I18nKey } from "#/i18n/declaration";
+import CheckCircleIcon from "#/icons/u-check-circle.svg?react";
+import { TaskItem } from "#/components/features/chat/task-tracking/task-item";
+import { useTaskList } from "#/hooks/use-task-list";
+import { Text } from "#/ui/typography";
+import { cn } from "#/utils/utils";
+
+function TaskListTab() {
+  const { t } = useTranslation();
+  const { taskList } = useTaskList();
+
+  if (taskList.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center w-full h-full p-10 gap-4">
+        <CheckCircleIcon width={109} height={109} color="#A1A1A1" />
+        <Text className="text-[#8D95A9] text-[19px] font-normal leading-5">
+          {t(I18nKey.COMMON$NO_TASKS)}
+        </Text>
+      </div>
+    );
+  }
+
+  return (
+    <main className="h-full overflow-y-auto flex flex-col custom-scrollbar-always">
+      {taskList.map((task) => (
+        <div
+          key={task.id}
+          className={cn(
+            "px-4 py-2",
+            task.status === "in_progress" && "bg-[#2D3039]",
+          )}
+        >
+          <TaskItem task={task} />
+        </div>
+      ))}
+    </main>
+  );
+}
+
+export default TaskListTab;

frontend/src/stores/conversation-store.ts

@@ -11,7 +11,8 @@ export type ConversationTab =
   | "served"
   | "vscode"
   | "terminal"
-  | "planner";
+  | "planner"
+  | "tasklist";
 
 export type ConversationMode = "code" | "plan";
 

frontend/src/utils/get-git-path.ts

@@ -3,7 +3,7 @@
  * If a repository is selected, returns /workspace/project/{repo-name}
  * Otherwise, returns /workspace/project
  *
- * @param selectedRepository The selected repository (e.g., "OpenHands/OpenHands" or "owner/repo")
+ * @param selectedRepository The selected repository (e.g., "OpenHands/OpenHands", "owner/repo", or "group/subgroup/repo")
  * @returns The git path to use
  */
 export function getGitPath(
@@ -13,10 +13,10 @@ export function getGitPath(
     return "/workspace/project";
   }
 
-  // Extract the repository name from "owner/repo" format
-  // The folder name is the second part after "/"
+  // Extract the repository name from the path
+  // The folder name is always the last part (handles both "owner/repo" and "group/subgroup/repo" formats)
   const parts = selectedRepository.split("/");
-  const repoName = parts.length > 1 ? parts[1] : parts[0];
+  const repoName = parts[parts.length - 1];
 
   return `/workspace/project/${repoName}`;
 }

frontend/src/utils/verified-models.ts

@@ -16,6 +16,7 @@ export const VERIFIED_MODELS = [
   "gpt-5.2",
   "minimax-m2.5",
   "gemini-3-pro-preview",
+  "gemini-3.1-pro-preview",
   "gemini-3-flash-preview",
   "deepseek-chat",
   "devstral-medium-2512",
@@ -65,6 +66,7 @@ export const VERIFIED_OPENHANDS_MODELS = [
   "gpt-5.2",
   "minimax-m2.5",
   "gemini-3-pro-preview",
+  "gemini-3.1-pro-preview",
   "gemini-3-flash-preview",
   "devstral-medium-2512",
   "kimi-k2-0711-preview",

openhands/integrations/bitbucket_data_center/service/base.py

@@ -216,13 +216,18 @@ class BitbucketDCMixinBase(BaseGitService, HTTPClient):
         )
 
     async def _parse_repository(
-        self, repo: dict, link_header: str | None = None
+        self,
+        repo: dict,
+        link_header: str | None = None,
+        fetch_default_branch: bool = False,
     ) -> Repository:
         """Parse a Bitbucket data center API repository response into a Repository object.
 
         Args:
             repo: Repository data from Bitbucket data center API
             link_header: Optional link header for pagination
+            fetch_default_branch: Whether to make an additional API call to fetch the
+                default branch. Set to False for listing endpoints to avoid N+1 queries.
 
         Returns:
             Repository object
@@ -240,14 +245,15 @@ class BitbucketDCMixinBase(BaseGitService, HTTPClient):
         is_public = repo.get('public', False)
 
         main_branch: str | None = None
-        try:
-            default_branch_url = (
-                f'{self._repo_api_base(project_key, repo_slug)}/default-branch'
-            )
-            default_branch_data, _ = await self._make_request(default_branch_url)
-            main_branch = default_branch_data.get('displayId') or None
-        except Exception as e:
-            logger.debug(f'Could not fetch default branch for {full_name}: {e}')
+        if fetch_default_branch:
+            try:
+                default_branch_url = (
+                    f'{self._repo_api_base(project_key, repo_slug)}/default-branch'
+                )
+                default_branch_data, _ = await self._make_request(default_branch_url)
+                main_branch = default_branch_data.get('displayId') or None
+            except Exception as e:
+                logger.debug(f'Could not fetch default branch for {full_name}: {e}')
 
         return Repository(
             id=str(repo.get('id', '')),
@@ -275,7 +281,7 @@ class BitbucketDCMixinBase(BaseGitService, HTTPClient):
         owner, repo = self._extract_owner_and_repo(repository)
         url = self._repo_api_base(owner, repo)
         data, _ = await self._make_request(url)
-        return await self._parse_repository(data)
+        return await self._parse_repository(data, fetch_default_branch=True)
 
     async def _get_cursorrules_url(self, repository: str) -> str:
         """Get the URL for checking .cursorrules file."""

openhands/llm/model_features.py

@@ -115,6 +115,7 @@ REASONING_EFFORT_PATTERNS: list[str] = [
     'o4-mini-2025-04-16',
     'gemini-2.5-flash',
     'gemini-2.5-pro',
+    'gemini-3.1-pro*',
     'gpt-5*',
     # DeepSeek reasoning family
     'deepseek-r1-0528*',
@@ -139,6 +140,7 @@ PROMPT_CACHE_PATTERNS: list[str] = [
     'claude-3-opus-20240229',
     'claude-sonnet-4*',
     'claude-opus-4*',
+    'gemini-3.1-pro*',
     # Kimi series - verified via litellm config
     'kimi-k2.5',
     # GLM series - verified via litellm config

openhands/utils/llm.py

@@ -22,6 +22,7 @@ OPENHANDS_MODELS = [
     'openhands/gpt-5.2',
     'openhands/minimax-m2.5',
     'openhands/gemini-3-pro-preview',
+    'openhands/gemini-3.1-pro-preview',
     'openhands/gemini-3-flash-preview',
     'openhands/deepseek-chat',
     'openhands/devstral-medium-2512',

poetry.lock

@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 2.3.2 and should not be changed by hand.
+# This file is automatically @generated by Poetry 2.2.1 and should not be changed by hand.
 
 [[package]]
 name = "agent-client-protocol"
@@ -3468,7 +3468,7 @@ files = [
 [package.dependencies]
 googleapis-common-protos = ">=1.5.5"
 grpcio = ">=1.71.2"
-protobuf = ">=5.26.1,<6.0.dev0"
+protobuf = ">=5.26.1,<6.0dev"
 
 [[package]]
 name = "grpclib"
@@ -3836,7 +3836,7 @@ pfzy = ">=0.3.1,<0.4.0"
 prompt-toolkit = ">=3.0.1,<4.0.0"
 
 [package.extras]
-docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17b43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
+docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17-beta.43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
 
 [[package]]
 name = "installer"
@@ -4287,7 +4287,7 @@ fqdn = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 idna = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 isoduration = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 jsonpointer = {version = ">1.13", optional = true, markers = "extra == \"format-nongpl\""}
-jsonschema-specifications = ">=2023.3.6"
+jsonschema-specifications = ">=2023.03.6"
 referencing = ">=0.28.4"
 rfc3339-validator = {version = "*", optional = true, markers = "extra == \"format-nongpl\""}
 rfc3986-validator = {version = ">0.1.0", optional = true, markers = "extra == \"format-nongpl\""}
@@ -4752,7 +4752,7 @@ files = [
 ]
 
 [package.dependencies]
-certifi = ">=14.5.14"
+certifi = ">=14.05.14"
 durationpy = ">=0.7"
 google-auth = ">=1.0.1"
 oauthlib = ">=3.2.2"
@@ -6942,7 +6942,6 @@ files = [
     {file = "pexpect-4.9.0-py2.py3-none-any.whl", hash = "sha256:7236d1e080e4936be2dc3e326cec0af72acf9212a7e1d060210e70a47e253523"},
     {file = "pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f"},
 ]
-markers = {runtime = "sys_platform != \"win32\" and sys_platform != \"emscripten\""}
 
 [package.dependencies]
 ptyprocess = ">=0.5"
@@ -6960,7 +6959,7 @@ files = [
 ]
 
 [package.extras]
-docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17b43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
+docs = ["Sphinx (>=4.1.2,<5.0.0)", "furo (>=2021.8.17-beta.43,<2022.0.0)", "myst-parser (>=0.15.1,<0.16.0)", "sphinx-autobuild (>=2021.3.14,<2022.0.0)", "sphinx-copybutton (>=0.4.0,<0.5.0)"]
 
 [[package]]
 name = "pg8000"
@@ -7517,7 +7516,6 @@ files = [
     {file = "ptyprocess-0.7.0-py2.py3-none-any.whl", hash = "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35"},
     {file = "ptyprocess-0.7.0.tar.gz", hash = "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220"},
 ]
-markers = {runtime = "sys_platform != \"win32\" and sys_platform != \"emscripten\" or os_name != \"nt\""}
 
 [[package]]
 name = "pure-eval"
@@ -7546,6 +7544,18 @@ files = [
     {file = "puremagic-1.30.tar.gz", hash = "sha256:f9ff7ac157d54e9cf3bff1addfd97233548e75e685282d84ae11e7ffee1614c9"},
 ]
 
+[[package]]
+name = "py"
+version = "1.11.0"
+description = "library with cross-python path, ini-parsing, io, code, log facilities"
+optional = false
+python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+groups = ["test"]
+files = [
+    {file = "py-1.11.0-py2.py3-none-any.whl", hash = "sha256:607c53218732647dff4acdfcd50cb62615cedf612e72d1724fb1a0cc6405b378"},
+    {file = "py-1.11.0.tar.gz", hash = "sha256:51c75c4126074b472f746a24399ad32f6053d1b34b68d2fa41e558e6f4a98719"},
+]
+
 [[package]]
 name = "py-key-value-aio"
 version = "0.4.4"
@@ -11690,6 +11700,22 @@ pytest = ">=7"
 [package.extras]
 testing = ["process-tests", "pytest-xdist", "virtualenv"]
 
+[[package]]
+name = "pytest-forked"
+version = "1.6.0"
+description = "run tests in isolated forked subprocesses"
+optional = false
+python-versions = ">=3.7"
+groups = ["test"]
+files = [
+    {file = "pytest-forked-1.6.0.tar.gz", hash = "sha256:4dafd46a9a600f65d822b8f605133ecf5b3e1941ebb3588e943b4e3eb71a5a3f"},
+    {file = "pytest_forked-1.6.0-py3-none-any.whl", hash = "sha256:810958f66a91afb1a1e2ae83089d8dc1cd2437ac96b12963042fbb9fb4d16af0"},
+]
+
+[package.dependencies]
+py = "*"
+pytest = ">=3.10"
+
 [[package]]
 name = "pytest-playwright"
 version = "0.7.2"
@@ -12875,10 +12901,10 @@ files = [
 ]
 
 [package.dependencies]
-botocore = ">=1.37.4,<2.0a0"
+botocore = ">=1.37.4,<2.0a.0"
 
 [package.extras]
-crt = ["botocore[crt] (>=1.37.4,<2.0a0)"]
+crt = ["botocore[crt] (>=1.37.4,<2.0a.0)"]
 
 [[package]]
 name = "scantree"
@@ -14814,7 +14840,7 @@ files = [
 ]
 
 [package.extras]
-cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and python_version < \"3.14\"", "cffi (>=2.0.0b0) ; platform_python_implementation != \"PyPy\" and python_version >= \"3.14\""]
+cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and python_version < \"3.14\"", "cffi (>=2.0.0b) ; platform_python_implementation != \"PyPy\" and python_version >= \"3.14\""]
 
 [extras]
 third-party-runtimes = ["daytona", "e2b-code-interpreter", "modal", "runloop-api-client"]
@@ -14822,4 +14848,4 @@ third-party-runtimes = ["daytona", "e2b-code-interpreter", "modal", "runloop-api
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.12,<3.14"
-content-hash = "54d8d1b20ca7d88287c479f43f7bbe0402c9202cbdb24c9d091b2c23245d6c47"
+content-hash = "7319bfec87aed5ed2803ad7cb947f875e83fa62216b1662a87b9b84078dc03e4"

pyproject.toml

@@ -130,6 +130,7 @@ test = [
   "pytest",
   "pytest-asyncio",
   "pytest-cov",
+  "pytest-forked",
   "pytest-playwright>=0.7",
   "pytest-timeout>=2.4",
   "pytest-xdist",
@@ -280,6 +281,7 @@ optional = true
 pytest = "*"
 pytest-cov = "*"
 pytest-asyncio = "*"
+pytest-forked = "*"
 pytest-xdist = "*"
 pytest-playwright = "^0.7.0"
 pytest-timeout = "^2.4.0"

tests/unit/integrations/bitbucket_data_center/test_bitbucket_dc_repos.py

@@ -112,21 +112,15 @@ async def test_search_repositories_slash_query():
     query = 'PROJ/myrepo'
 
     mock_repo = _repo_dict('PROJ', slug='myrepo', name='My Repository')
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_fetch_paginated_data',
         new=AsyncMock(return_value=[mock_repo]),
     ) as mock_fetch:
-        with patch.object(
-            svc,
-            '_make_request',
-            new=AsyncMock(return_value=(mock_default_branch, {})),
-        ):
-            repos = await svc.search_repositories(
-                query, 25, 'name', 'asc', False, AppMode.SAAS
-            )
+        repos = await svc.search_repositories(
+            query, 25, 'name', 'asc', False, AppMode.SAAS
+        )
 
     mock_fetch.assert_called_once_with(
         'https://host.example.com/rest/api/1.0/projects/PROJ/repos',
@@ -135,6 +129,7 @@ async def test_search_repositories_slash_query():
     )
     assert len(repos) == 1
     assert repos[0].full_name == 'PROJ/myrepo'
+    assert repos[0].main_branch is None
 
 
 @pytest.mark.asyncio
@@ -143,24 +138,19 @@ async def test_search_repositories_slash_query_filters_by_name():
     svc = make_service()
     matching = _repo_dict('PROJ', slug='proj-alpha', name='My Repository')
     non_matching = _repo_dict('PROJ', slug='proj-beta', name='Other Repo')
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_fetch_paginated_data',
         new=AsyncMock(return_value=[matching, non_matching]),
     ):
-        with patch.object(
-            svc,
-            '_make_request',
-            new=AsyncMock(return_value=(mock_default_branch, {})),
-        ):
-            repos = await svc.search_repositories(
-                'PROJ/my repository', 25, 'name', 'asc', False, AppMode.SAAS
-            )
+        repos = await svc.search_repositories(
+            'PROJ/my repository', 25, 'name', 'asc', False, AppMode.SAAS
+        )
 
     assert len(repos) == 1
     assert repos[0].full_name == 'PROJ/proj-alpha'
+    assert repos[0].main_branch is None
 
 
 @pytest.mark.asyncio
@@ -169,24 +159,19 @@ async def test_search_repositories_slash_query_filters_by_slug():
     svc = make_service()
     matching = _repo_dict('PROJ', slug='my-repo', name='My Repository')
     non_matching = _repo_dict('PROJ', slug='other-repo', name='Other Repository')
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_fetch_paginated_data',
         new=AsyncMock(return_value=[matching, non_matching]),
     ):
-        with patch.object(
-            svc,
-            '_make_request',
-            new=AsyncMock(return_value=(mock_default_branch, {})),
-        ):
-            repos = await svc.search_repositories(
-                'PROJ/my-repo', 25, 'name', 'asc', False, AppMode.SAAS
-            )
+        repos = await svc.search_repositories(
+            'PROJ/my-repo', 25, 'name', 'asc', False, AppMode.SAAS
+        )
 
     assert len(repos) == 1
     assert repos[0].full_name == 'PROJ/my-repo'
+    assert repos[0].main_branch is None
 
 
 # ── get_paginated_repos ───────────────────────────────────────────────────────
@@ -199,18 +184,18 @@ async def test_get_paginated_repos_parses_values():
         'values': [_repo_dict()],
         'isLastPage': True,
     }
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_make_request',
-        side_effect=[(mock_response, {}), (mock_default_branch, {})],
+        return_value=(mock_response, {}),
     ):
         repos = await svc.get_paginated_repos(1, 25, 'name', 'PROJ')
 
     assert len(repos) == 1
     assert repos[0].full_name == 'PROJ/myrepo'
     assert repos[0].link_header == ''
+    assert repos[0].main_branch is None
 
 
 @pytest.mark.asyncio
@@ -221,17 +206,17 @@ async def test_get_paginated_repos_has_next_page():
         'isLastPage': False,
         'nextPageStart': 25,
     }
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_make_request',
-        side_effect=[(mock_response, {}), (mock_default_branch, {})],
+        return_value=(mock_response, {}),
     ):
         repos = await svc.get_paginated_repos(1, 25, 'name', 'PROJ')
 
     assert len(repos) == 1
     assert 'rel="next"' in repos[0].link_header
+    assert repos[0].main_branch is None
 
 
 @pytest.mark.asyncio
@@ -241,17 +226,17 @@ async def test_get_paginated_repos_last_page():
         'values': [_repo_dict()],
         'isLastPage': True,
     }
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_make_request',
-        side_effect=[(mock_response, {}), (mock_default_branch, {})],
+        return_value=(mock_response, {}),
     ):
         repos = await svc.get_paginated_repos(1, 25, 'name', 'PROJ')
 
     assert len(repos) == 1
     assert repos[0].link_header == ''
+    assert repos[0].main_branch is None
 
 
 @pytest.mark.asyncio
@@ -265,17 +250,17 @@ async def test_get_paginated_repos_filters_by_slug():
         ],
         'isLastPage': True,
     }
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_make_request',
-        side_effect=[(mock_response, {}), (mock_default_branch, {})],
+        return_value=(mock_response, {}),
     ):
         repos = await svc.get_paginated_repos(1, 25, 'name', 'PROJ', query='my-repo')
 
     assert len(repos) == 1
     assert repos[0].full_name == 'PROJ/my-repo'
+    assert repos[0].main_branch is None
 
 
 @pytest.mark.asyncio
@@ -289,12 +274,11 @@ async def test_get_paginated_repos_filters_by_name():
         ],
         'isLastPage': True,
     }
-    mock_default_branch = {'displayId': 'main'}
 
     with patch.object(
         svc,
         '_make_request',
-        side_effect=[(mock_response, {}), (mock_default_branch, {})],
+        return_value=(mock_response, {}),
     ):
         repos = await svc.get_paginated_repos(
             1, 25, 'name', 'PROJ', query='my repository'
@@ -302,6 +286,7 @@ async def test_get_paginated_repos_filters_by_name():
 
     assert len(repos) == 1
     assert repos[0].full_name == 'PROJ/proj-alpha'
+    assert repos[0].main_branch is None
 
 
 # ── get_all_repositories ──────────────────────────────────────────────────────
@@ -320,14 +305,14 @@ async def test_get_all_repositories_iterates_projects():
             return [_repo_dict('PROJ2', 'repo2')]
         return []
 
-    mock_default_branch = {'displayId': 'main'}
     with patch.object(svc, '_fetch_paginated_data', side_effect=fake_fetch):
-        with patch.object(svc, '_make_request', return_value=(mock_default_branch, {})):
-            repos = await svc.get_all_repositories('name', AppMode.SAAS)
+        repos = await svc.get_all_repositories('name', AppMode.SAAS)
 
     full_names = {r.full_name for r in repos}
     assert 'PROJ1/repo1' in full_names
     assert 'PROJ2/repo2' in full_names
+    for repo in repos:
+        assert repo.main_branch is None
 
 
 # ── get_installations ─────────────────────────────────────────────────────────
@@ -352,4 +337,4 @@ async def test_get_installations_returns_project_keys():
 async def _make_parsed_repo(svc, repo_dict):
     """Helper to create a parsed Repository from a repo dict (with mocked default branch)."""
     with patch.object(svc, '_make_request', return_value=({'displayId': 'main'}, {})):
-        return await svc._parse_repository(repo_dict)
+        return await svc._parse_repository(repo_dict, fetch_default_branch=True)