fix(mcp): a sequential chat_with_agent call that ends in a receipt reports back to the caller's conversation (#3295)

[vybe]

Summary

• A plain sequential chat_with_agent (parallel=false → POST /chat) could never post its outcome into the Slack, Telegram or Workspace thread the caller serves. When the MCP server gave up at 25 s and returned a receipt, the person heard nothing when the work finished.
• The parent still never travels in the /chat body. The MCP server asks for the report at the one moment it knows the caller did not get the reply — when it builds a queued_timeout receipt (its own abort, a 409 in-flight replay, or the backend's own 504, now recovered through the same execution lookup) — via a new POST /api/agents/{name}/executions/{id}/report-back naming the caller's turn. A call that answers inline is never armed, so it cannot post a second "done".
• Design choice vs the issue's AC1 (stamp at /chat row creation): stamping at creation double-posts on a pull pilot (the sink reports before the waiting handler returns the reply), and a probe on the real image showed request.is_disconnected() reads False behind the app's two @app.middleware("http") wrappers, so a "caller still waiting" hold could not be released. Recorded in docs/memory/learnings.md.

Changes

• src/backend/services/chat_execution_service.py — arm_chat_report_back (dispatcher-of-row gate: agent key = source_agent_name, person = source_user_id, connector 403, anything else one uniform 404; /chat rows only; inheritance through the unchanged _inherited_channel_context; ent#498's add-only stamp; re-read + spawn if already terminal) and spawn_completion_report on the four push /chat terminal writes (CAS-won only).
• src/backend/routers/chat.py, src/backend/models.py — the route and ReportBackRequest (extra=forbid, 1..128).
• src/mcp-server/src/client.ts — armChatReportBack (own 2 s deadline, never throws; only an explicit refusal reads as off), backend 504 on /chat → the bug: chat_with_agent MCP tool returns 'fetch failed' but still queues execution — silent duplicates burn budget on naive retry #914 lookup → receipt.
• src/mcp-server/src/tools/chat.ts — resolveReportBack defaults the chat route on under the /task rules; chatRouteFields picks result fields from the outcome; reasons answered_inline / not_armed replace sequential_chat; one clause added to EXECUTION_ID_PARAM_DESCRIPTION.
• tests/unit/_route_census.py — the route is listed agent-callable with its reason.
• Docs: requirements §15.1h, channel-completion-report.md (route table, new "How a sequential /chat call is armed" section, chokepoint table), api-endpoints.md, agent-to-agent-collaboration.md, user docs, learnings.md, CSO diff report.

Test Plan

• tests/unit/test_3295_chat_report_back.py — 19 tests against the real DB layer and the real reporter + effect_guard: both provenance arms read back, every refusal, arm-after-terminal and arm-before-terminal each deliver exactly once, the reporter reads the row fresh, an un-armed row reports nothing, the success finalizer spawns the sanitized response on a CAS win only.
• src/mcp-server/src/chat-parent-execution.test.ts — 64 tests over a real MCP transport: a receipt arms once with the header turn (both tools), the 504 path, a refused arm, manual / manual header / no header / kill switch arm nothing, the oracle over the full input product; T5/T6/T13 consciously re-pinned.
• Neighbouring suites (ent#224/265/457/498/614, feat(pull): UI /chat on the durable queue for pull pilots #3127, bug: chat_with_agent never forwards its execution_id argument, so a delegated task cannot report back to the caller's channel #3232, bug(auth): agent-scoped keys can toggle their own agent's autonomy — PUT /api/agents/{name}/autonomy lacks reject_agent_principal #2996, refactor(auth): consolidate duplicated auth/dependency patterns behind factories (INV-8, split from #654) #1310, SEC: User and Agent Enumeration via differential API responses #186, bug: schedule enable/disable/trigger always 422 — OwnedAgentByName on {name} routes (regression from #2081 CSO M1) #2094, fix: Slack message formatting is ugly — markdown not rendering properly #293, models-centralized): 436 passed. tsc --noEmit clean.
• /review: 0 critical. /cso --diff: 0 findings (one hardening applied — the not-dispatcher refusal is the same uniform 404 as a missing row).
• Manual: from an agent serving a Slack/Telegram thread, chat_with_agent(agent, long_task) sequentially; after the 25 s receipt (report_back: requested), the child's note lands in the thread when it finishes; a call that answers in time posts nothing extra.

Fixes #3295

🤖 Generated with Claude Code

[vybe]

merge-train (2026-10-09): ejected — the regression diff job on the current head (685470b) reports 8 new failures introduced by HEAD, including the PR's own test_3295_chat_report_back.TestDelivery cases and the existing budget-exhausted 503 path (test_1483_run_chat_and_finalize_characterization::test_budget_exhausted_maps_503_and_fails_idem, test_2433_dispatch_wiring::test_chat_budget_finalizer_*, test_ent279_secret_scrub::test_finalize_budget_exhausted_scrubs_error). A failing behaviour test needs the author's intent, not a train fix. Rides the next train once fixed.

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

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

[vybe]

merge-train (2026-10-11): ejected. This PR's own regression diff (head 685470bf, run 37962621860) has 8 new failures against the cached dev baseline. None reproduces on dev:

• test_3295_chat_report_back.TestDelivery — 4 of this PR's own new tests (test_a_failure_terminal_reports_too, test_arm_after_terminal_delivers_once, test_arm_before_terminal_leaves_the_report_to_the_terminal, test_report_completion_reads_the_row_fresh)
• test_1483_run_chat_and_finalize_characterization::test_budget_exhausted_maps_503_and_fails_idem
• test_2433_dispatch_wiring::test_chat_budget_finalizer_keeps_failed_503_for_a_real_exhaustion and …_writes_cancelled_and_raises_409_for_a_cancelled_park
• test_ent279_secret_scrub.TestChatExecutionChokepoints::test_finalize_budget_exhausted_scrubs_error

The last four all go through the budget-exhaustion finalizer in chat_execution_service.py, so the change there looks like it altered that path. That needs the author's judgment rather than a train fix. The branch also conflicts with dev now. It rides the next train once it's fixed and green.