Review: Scheduled recurring tasks in Agent UI

Solid, well-tested feature that lands cleanly on current architecture — persistence, fail-loudly config handling, a concurrency cap, and the tunnel gate are all here, backed by 85+ tests across unit/API/integration tiers. No security or breaking-change concerns. The one thing worth addressing before merge: the tunnel "suspend" path doesn't suspend — it fails every run and inflates error_count, which contradicts the docs and pollutes each schedule's session history.

Issues

🟡 Tunnel-active runs fail loudly instead of suspending (src/gaia/ui/server.py:2872, surfaced in scheduler.py:_execute_task)

The executor raises RuntimeError("Scheduled run suspended…") when a tunnel is active. But _execute_task catches every exception, so each fire still increments run_count and error_count, stores an error row in schedule_results, and writes Error: Scheduled run suspended… as an assistant message to the schedule's session. For an every 1m schedule with the tunnel up overnight, that's hundreds of bogus error rows and session messages — and the card shows a climbing error count. The docs say runs are "suspended while mobile access is active," which is not what happens.

Recommend gating in the run loop before counting a run — skip and re-sleep rather than execute-and-fail. Sketch:

# in _run_loop, before await self._execute_task(task):
if self._tunnel_blocked():   # inject the same tunnel check the server uses
    logger.info("Schedule '%s' skipped: tunnel active", task.name)
    await asyncio.sleep(min(task.interval_seconds, 60))
    continue

That keeps the security guarantee (LLM never runs) without the error-count/history noise. The tunnel check currently lives in the server closure; passing a small predicate into Scheduler keeps the suspend logic where the counting happens.

🟡 No minimum-interval floor; fresh ChatAgent per run (scheduler.py:parse_schedule_input, server.py:_run)

every 1s parses and runs — and each run constructs a brand-new ChatAgent (server.py:2878-2887), which can trigger a model (re)load through Lemonade. A sub-minute schedule against a single-tenant local backend will keep the machine pegged with construction churn. max_concurrent_runs=1 prevents overlap but not the back-to-back hammering. Consider rejecting intervals below a sane floor (e.g. 30–60 s) in create_task with an actionable ValueError, and/or caching the agent across runs if fresh-context isn't strictly required.

Minor

🟢 Unused imports in the integration test (tests/integration/test_scheduler_e2e.py:19,24) — pytest_asyncio, ScheduledTask, and parse_interval are imported but never used.

from gaia.ui.database import ChatDatabase
from gaia.ui.routers.schedules import get_scheduler, router
from gaia.ui.scheduler import Scheduler

(drop the import pytest_asyncio line too).

🟢 Inaccurate type hint (scheduler.py:2137) — after: datetime = None should be Optional[datetime] = None to match the rest of the module's annotations.

🟢 HTTPException re-raises drop the cause (routers/schedules.py — the except ValueError as e: raise HTTPException(...) blocks). CLAUDE.md prefers raise … from e so the original traceback is preserved. Boundary translation is allowed, but from e costs nothing here.

🟢 Timing-based tests (test_scheduler.py, test_scheduler_e2e.py) lean on real asyncio.sleep(1.5–3.5s) with >= count asserts. Correct, but can flake on a loaded CI runner and adds ~30 s+ of wall time. Not blocking — flagging in case intermittent failures show up later.

Strengths

• Fail-loudly done right — ScheduleConfig.from_json raises on malformed/unknown-key JSON instead of returning a silently-empty config, _load_tasks propagates schema errors rather than booting with zero tasks, and the executor/concurrency guards reject bad construction. This is exactly the CLAUDE.md "no silent fallbacks" posture, and it's tested directly (TestScheduleConfigFromJson).
• Persistence + restart coverage is genuinely thorough — paused/cancelled status, results, and active timers all verified to survive a scheduler restart against a real :memory: DB.
• Clean layering — DB access goes through the public ChatDatabase API (parameterized SQL throughout, ON DELETE CASCADE + explicit result cleanup), the router uses a proper Depends(get_scheduler) with a 503 when the lifespan didn't start it, and docs were updated in the same PR.

Verdict

Approve with suggestions. No blocking correctness or security issues; the feature works and is well-covered. Please address the tunnel-suspend behavior (or at least reconcile the docs with what actually happens) — the rest are quick cleanups.

🟡 tests/unit/test_scheduler_api.py:3971 — dual event-loop deadlock risk

app_with_scheduler starts the scheduler on a manually-created loop, but TestClient uses its own internal anyio-backed event loop. When any test creates a schedule via client.post(...), create_task calls asyncio.create_task(self._run_loop(task)) inside the TestClient's loop — so the timer task lives there. Teardown then calls loop.run_until_complete(scheduler.shutdown()), which tries to await task._timer_task on the wrong loop. The task's done-callback is dispatched on the TestClient's loop, not loop, so loop may never be woken up — potential hang on teardown.

The other test files in this PR (test_scheduler.py, test_scheduler_e2e.py) use @pytest_asyncio.fixture correctly and avoid this entirely. test_scheduler_api.py should do the same:

@pytest_asyncio.fixture
async def app_with_scheduler():
    db = ChatDatabase(":memory:")
    scheduler = Scheduler(db=db, executor=fake_executor)
    await scheduler.start()
    app = FastAPI()
    app.include_router(router)
    app.state.scheduler = scheduler
    app.dependency_overrides[get_scheduler] = lambda: scheduler
    yield app, scheduler, db
    await scheduler.shutdown()
    db.close()

And replace TestClient with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") (same pattern as test_scheduler_e2e.py).

🟡 tests/unit/test_scheduler_api.py:70 — event-loop mismatch will cause teardown ValueError

The app_with_scheduler fixture starts the scheduler on a manually-created loop, but TestClient processes each request on its own anyio event loop. When a POST /api/schedules request fires, scheduler.create_task() calls asyncio.create_task(self._run_loop(task)) on TestClient's loop — not loop.

Teardown then calls loop.run_until_complete(scheduler.shutdown()). Inside shutdown():

task._timer_task.cancel()
try:
    await task._timer_task   # ← Task lives on a different loop → ValueError
except asyncio.CancelledError:
    pass

Only CancelledError is swallowed; ValueError: Task attached to a different loop propagates, causing pytest teardown errors for every test that creates a schedule.

Fix: use a pytest-asyncio async fixture so everything shares one loop:

@pytest_asyncio.fixture
async def app_with_scheduler():
    db = ChatDatabase(":memory:")
    scheduler = Scheduler(db=db, executor=fake_executor)
    await scheduler.start()
    app = FastAPI()
    app.include_router(router)
    app.dependency_overrides[get_scheduler] = lambda: scheduler
    yield app, scheduler, db
    await scheduler.shutdown()
    db.close()

The tests would then use httpx.AsyncClient + @pytest.mark.asyncio (same pattern as test_scheduler_e2e.py).

🟡 scheduler.py — zero-interval creates a spin-loop against the LLM

parse_interval("every 0s") returns 0, and create_task accepts it without validation. The run loop then does await asyncio.sleep(0) → yield → fire → repeat indefinitely at full speed. The UI blocks it (parsed.valid is false when interval_seconds == 0), but a direct API call can trigger it.

src/gaia/ui/scheduler.py — create_task, just before self._tasks[name] = task:

        if interval_seconds <= 0:
            raise ValueError(
                f"Interval must be at least 1 second; got {interval_seconds}. "
                "Check your schedule string (e.g. 'every 30m', 'daily at 9am')."
            )