feat(events): system-emitted agent.task.completed/failed at execution terminal (#1578)

[AndriiPasternak31]

Fixes #1578

What

The backend now deterministically emits agent.task.completed / agent.task.failed at every CAS-won execution terminal, delivered over the existing EVT-001 subscription-dispatch machinery — so a subscribed orchestrator is woken with a report-back task when a long async task finishes, instead of polling get_execution_result. Implements the missing half of TARGET_ARCHITECTURE.md §Async-First Communication; a down-payment on Epic #1045 → #1081.

These are the first system-emitted events (deterministic backend chokepoint, no LLM in the loop), distinct from EVT-001's agent-emitted emit_event. Same tables, same delivery, reserved agent.task.* namespace.

How

• Shared emit helper services/event_dispatch_service.py::emit_task_terminal_event (+ strong-ref spawn_task_terminal_event), matching-subscription gated (zero subs ⇒ zero rows, no dispatch). The EVT-001 dispatch primitives (trigger_subscription, _interpolate_template, _get_internal_token) were extracted verbatim out of routers/event_subscriptions.py so the service layer no longer imports a router (Invariant Fix: Add missing Docker labels to system agent container #1, verified cycle-free).
• CAS-won coverage across every terminal writer: apply_result (success + failure), _write_terminal_and_gate (timeout/budget/crash + inline circuit-open/capacity/ephemeral — the wedge cases that never reach apply_result), the refactor: fire-and-forget dispatch — a hung turn holds zero backend resource #1083 lease-reaper (cleanup_service), and the pull sink (pull_coordination_service, dark until a pilot). Both refactor: fire-and-forget dispatch — a hung turn holds zero backend resource #1083 caller paths (inline sync + async callback) converge on apply_result.
• Exactly-once: emit runs strictly inside the won CAS branch — a replayed/late refactor: fire-and-forget dispatch — a hung turn holds zero backend resource #1083 callback or lease-expiry race fires nothing.
• Reserved namespace + 3-layer loop safety: agents can't emit_event into agent.task.* (400); reserved self-subscription blocked on create and update (400); recursion-break — a task spawned by a reserved-namespace dispatch is persisted triggered_by="event" and the helper suppresses re-emission, breaking self / A↔B / A→B→C→A cycles at the root.
• Payload {execution_id, status, triggered_by, summary_or_error, duration_ms, cost, fan_out_id, loop_id} — flat, {{payload.field}}-interpolable; status is the string value. fan_out_id/loop_id carried for the future pull fan-out join envelope.
• Additive & inert: reuses agent_events / agent_event_subscriptions + the existing triggered_by column — no schema change, no migration, no flag, no config. Fail-open: a broken emit never touches the billed terminal.

Security hardening (final commit)

• Recursion-break X-Event-Trigger is honored only with a valid backend-internal X-Internal-Secret (C-003, constant-time) — an external /task caller can't spoof it to suppress a real completion.
• summary_or_error is credential-sanitized at the single emit chokepoint over a 2×cap window before truncation, so a secret straddling TASK_EVENT_SUMMARY_MAX can't leak an un-redactable head.

Delivery scope (honest)

Best-effort today: wakes a running (incl. #1402 parked-but-running) subscriber via loopback async /task; a stopped subscriber's wake is dropped though the agent_events row persists. Durable "lands in the caller's queue" delivery is the pull migration's job — the same names + payload carry over unchanged.

Acceptance criteria

• CAS-won terminal in apply_result dispatches matching subs with templated payload; no matching sub ⇒ no row/dispatch (AC Fix: Add missing Docker labels to system agent container #1, Setup improvements #5)
• Replayed / CAS-lost terminals fire nothing (AC Feature/gemini runtime support #2)
• subscribe_to_event unchanged; permission gate holds; self-sub to reserved namespace blocked (AC Feature/vector log retention #3)
• All terminal paths converging on apply_result covered — sync inline + refactor: fire-and-forget dispatch — a hung turn holds zero backend resource #1083 async callback + timeout/crash writer + lease-reaper + pull sink (AC fix: add missing logging_config.py to backend Dockerfile #4)
• Additive & inert by default (AC Setup improvements #5)
• Docs: architecture.md (EVT-001 + task-execution) + feature flow; events.ts notes the reserved agent.task.* namespace (AC Feature/process engine #6)
• TARGET_ARCHITECTURE.md §Async-First reconciled → IMPLEMENTED with event-bus→EVT-001 divergence note; Epic Epic: Agent Infrastructure #1045 table row added under feat: pull / work-stealing coordination (push→pull dispatch) #1081 (AC security: Fix token logging and add HTML reports to gitignore #7)

Tests

tests/unit/test_1578_task_completion_events.py — 37 unit tests: fired / not-fired (no sub) / replay / CAS-lost, recursion-break, spoof-guard (helper + router call-site), summary sanitize incl. boundary-straddle, and every terminal writer including both #1083 entry points. Adjacent test_1083_* / test_946_* suites re-run green (no regression).

Docs

• docs/memory/architecture.md — Task Completion Events cross-cutting block + EVT-001 / service / events.ts / DB-schema entries
• docs/memory/feature-flows/task-completion-events.md (new) + index Recent-Updates row + catalog entry + back-links
• docs/memory/requirements/roadmap.md §17.2a
• docs/planning/TARGET_ARCHITECTURE.md §Async-First + Epic Epic: Agent Infrastructure #1045 table
• src/mcp-server/src/tools/events.ts — reserved-namespace note on both tools

---

🤖 Generated with Claude Code

[vybe]

Validated via /validate-pr. Well-shaped first system-emitted event producer: emit strictly on CAS-won branches (exactly-once, replay-safe), every terminal writer covered (apply_result ×2, _write_terminal_and_gate, lease-reaper, pull sink), recursion-break authenticated with the C-003 internal secret (constant-time) so an external caller can't spoof suppression, reserved-namespace guards on emit + self-sub (create AND update), credential-sanitized summary over a 2×cap window, fail-open throughout. Dispatch primitives extracted verbatim to the service layer (Invariant #1); events.ts descriptions updated (Invariant #13). 37 tests incl. spoof + boundary-straddle. Conflict with dev (feature-flows index) resolved by merge keeping both rows; 52 tests re-run green on the merged tree. All checks green.