feat(loops): loop-level wall-clock deadline (max_duration_seconds) (#1156)

[dolho]

Summary

Adds an optional loop-level wall-clock deadline (max_duration_seconds) to sequential agent loops — the third hard stop alongside the max_runs iteration cap (and the separately-tracked cost budget). A loop legally configured today (max_runs=100 × timeout_per_run up to 2h + delay_seconds) can run for days; this bounds total duration.

Related to #1156.

What changed (end-to-end)

• Schema/migration: agent_loops.max_duration_seconds INTEGER (nullable) in schema.py + idempotent agent_loops_max_duration migration for existing DBs.
• Runner (loop_service._run): deadline measured from started_at, checked only at iteration boundaries — before the next run and before/after the inter-run delay (the delay_seconds sleep is capped to the remaining budget, never sleeping past the deadline). An in-flight run is never killed mid-turn, so overshoot is bounded by one timeout_per_run. Expiry → terminal status stopped, stop_reason="deadline_exceeded".
• Router: optional max_duration_seconds (1–604800 = 7d); 400 when smaller than the effective per-run timeout (timeout_per_run, else the agent's execution_timeout_seconds). GET /api/loops/{id} now returns max_duration_seconds + a computed elapsed_seconds.
• MCP run_agent_loop + Loops UI (form field + deadline/elapsed in detail, deadline_exceeded label).
• Docs: architecture.md (feature + schema) and requirements.md §38.2.

Acceptance criteria

• POST /loops accepts optional max_duration_seconds; persisted on agent_loops
• Deadline from started_at, checked at iteration boundaries; in-flight run completes
• Expired deadline → stop_reason="deadline_exceeded", status stopped
• Validation: reject < timeout_per_run (or agent execution timeout) with 400
• GET /loops/{id} returns deadline + elapsed; MCP run_agent_loop exposes the param
• Loops UI shows the deadline when set
• Schema migration + tests (deadline stop, boundary semantics, validation error)

Testing

tests/unit/test_loop_service.py (deadline suite) + tests/unit/test_loops_router_validation.py — 24 passed locally. Also verified the migration is idempotent and create_loop/get_loop round-trips the column on a fresh schema and via the ALTER path.

🤖 Generated with Claude Code

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[vybe]

@dependabot rebase

[vybe]

Thanks — the feature itself looks good (clean SQLite migration, schema.py/tables.py updated, docs + tests present). One blocker before merge:

Missing the PostgreSQL Alembic revision (dual-track migration, CLAUDE.md §9 / Invariant #9).

This PR adds agent_loops.max_duration_seconds via the SQLite track (_migrate_agent_loops_max_duration in db/migrations.py) but there is no matching Alembic revision under src/backend/migrations/versions/. On a PostgreSQL deployment the column would never be created, so the loop deadline feature would crash there.

Please add a revision (down_revision = current head, e.g. 0001_baseline) that runs op.add_column('agent_loops', sa.Column('max_duration_seconds', sa.Integer(), nullable=True)). Once that's in, this is good to go.

[dolho]

PR Validation Report — /validate-pr

Rebased onto dev (was CONFLICTING) and fixed an Alembic revision-number collision — the new revision was 0004 off 0003, colliding with dev's 0004_agent_ownership_voice_name; renumbered to 0005 chained after the current head. Now MERGEABLE.

Category	Status	Notes
Commit messages	✅	conventional (feat/fix/docs)
Base branch	✅	→ dev
PR size	✅	15 files
Issue link	✅	resolves public #1156 (p1, type-feature); "Related to" per relate-don't-close convention
Requirements	✅	requirements.md updated (param 1–604800)
Architecture	✅	loops section + agent_loops DDL + endpoint behavior
Feature flow	✅	run-agent-loop.md updated in 53ed5aa (was the one ⚠️)
Security	✅	no secrets / emails / IPs / .env / cred files
Build/Config packaging	➖	no new top-level module; no new os.getenv()
Dual-track migration (Inv. #9)	✅	SQLite + Alembic 0005 + schema.py + tables.py consistent
Code quality	✅	iteration-boundary deadline, overshoot ≤ one timeout_per_run, 400 if deadline < per-run timeout

Verification: schema-parity pytest ✅ (4) · loop tests ✅ (test_loop_service + test_loops_router_validation, 25).

Recommendation: APPROVE ✅

Clean, well-tested, dual-track migration correct after the rebase fix, docs complete. P1 feature — /review + /cso --diff remain part of the pipeline if not already run.