feat(#1068): deprecate per-task timeout_seconds override (task-shape demotion PR 1)

[obasilakis]

Summary

First of the six task-shape demotions from docs/planning/ACTOR_MODEL_TASK_DEMOTION_MAP.md (shipped in #991). Deprecates the per-task timeout_seconds override on ParallelTaskRequest — the agent's execution_timeout_seconds (#665) / schedule cap (#913, clamped to the agent cap by #929) is the authoritative deadline.

Additive-first: honored-but-clamped this release, field removed in a follow-up after one release of soak.

Closes #1068. Part of #945.

What changed

• routers/chat.py — new pure helper _resolve_deprecated_task_timeout() normalizes the override once at /task entry (mutating the request in place so every downstream site — capacity acquire, sync/async execute_task, persisted backlog payload — sees one resolved value and the warning fires exactly once). It:
  • clamps to the agent cap so a per-task value can no longer exceed it. This also closes a latent bug: the per-task override was previously unclamped — an escape hatch around the bug/design: schedule vs agent timeout precedence is silent + SIGKILL error message is ambiguous #929 invariant that schedules already respect (ad-hoc/MCP tasks could set a timeout above the agent cap; schedules can't).
  • warns on any use so callers migrate before deletion.
  • common no-override path is unchanged and skips the cap lookup.
• models.py / MCP chat_with_agent — field marked DEPRECATED (#1068) in its surface.
• tests/unit/test_1068_task_timeout_demotion.py — hermetic unit coverage of clamp / warn / pass-through / boundary / never-exceeds-cap. AST-extracts the pure helper to avoid the router's heavy import graph (same convention as test_backlog.py).

Scope / audit

git grep timeout_seconds audited. Only ParallelTaskRequest.timeout_seconds + the MCP chat_with_agent per-task param are in scope. The scheduler (src/scheduler/service.py, uses schedule.timeout_seconds), fan-out (own outer-deadline model), internal.py, and sessions.py all use separate models/owners — untouched.

Test plan

• Unit: 5 passed (pytest tests/unit/test_1068_task_timeout_demotion.py)
• py_compile clean (chat.py, models.py)
• Live smoke (localhost, uvicorn --reload running the edit):
  • above cap 99999 → clamped to 3600, logs [#1068] … exceeds the agent cap 3600s; clamping
  • below cap 30 → honored, logs [#1068] … deprecated … agent cap (3600s) is authoritative
  • no override → no [#1068] line (hot path untouched)
• tsc not run locally (no node_modules); MCP change is a .describe() string only, no type change.

Follow-up

After one release of soak: delete the field from ParallelTaskRequest, drop the MCP param, and update backlog_service.py reconstruction. That's the second half of demotion PR 1.

🤖 Generated with Claude Code

---

Soak gate (how the follow-up deletion PR knows it's safe)

The field is deleted in a follow-up, but only once it's gone quiet. Two facts make that gate trustworthy:

1. Zero in-repo originators. Audited: nothing in Trinity originates ParallelTaskRequest.timeout_seconds — event_subscriptions.py doesn't send it, backlog_service.py only replays the already-clamped persisted value. The field is set exclusively by external/out-of-repo callers (MCP chat_with_agent, agent-authored skills in their own template repos, external API scripts, per-instance eu2 configs). Those are structurally invisible to a static audit of this repo — the runtime signal is the only way to find them.

2. Durable usage counter. Each deprecated use bumps a Redis hash that survives log rotation:

   redis-cli HGETALL deprecation:task_timeout_seconds
   # → { "2026-06-04": "3", ..., "last_seen": "2026-06-04T14:15:05Z" }
   

   Before opening the deletion PR, check there are no hits for the trailing soak window (≥1 release). Self-expires 180d after traffic stops.

Fail-safe on deletion: ParallelTaskRequest has no model_config, so Pydantic defaults to extra="ignore". A straggler that still sends timeout_seconds after deletion has it silently dropped and falls back to the agent cap — degrades, doesn't 422. So even a caller both the audit and the soak miss fails safe.

Optional upgrade: a B-04-style canary invariant could push a Slack alert if the counter is still non-zero near a planned deletion date, replacing the manual HGETALL check. Not built here.

[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]

Merged to dev (squash 762d7344). I rebased onto current dev and resolved the routers/chat.py conflict for you: it was a clean both-added — your _resolve_deprecated_task_timeout() and dev's #1038 extracted post-task helpers (_persist_and_broadcast_chat_session/_complete_collaboration_activity/_finalize_self_task) landed at the same spot, so I kept both. The /task-entry normalize block is orthogonal to #1038's post-task refactor. test_1068_task_timeout_demotion.py green (5 passed) against the resolved tree. Net diff vs dev = your 4 files only.