Observability: code execution timeout awareness + subagent lifecycle ledger

[Number531]

Context

Raw SSE logs from session 2026-03-02-1772489470 revealed two observability gaps:

1. 3 code execution timeouts — run_python_analysis hit the 300s wall-clock limit because neither the system prompt nor tool description told the model about the time budget. The model wrote expensive Monte Carlo simulations that exceeded it.
2. Subagent start/stop mismatch (33 starts vs 40 stops) — the agentRegistry in hookSSEBridge.js was fire-and-forget (deleted entries on stop), so there was no session-end audit. Stops without matching starts (compaction recovery, gate re-invocations) went undetected.

Both were observability/guidance gaps, not functional bugs — the session completed successfully.

Changes (v3.10.3, commit 8f1f2cf)

Issue 1: Code Execution Timeout Awareness

• System prompt: Execution budget paragraph added (interpolates OVERALL_TIMEOUT_MS / 1000 = 300s)
• Tool description: EXECUTION BUDGET block with iteration limits and vectorization guidance
• Structured error: Timeout path now sets timeout: true + retry_hint on the result object

Issue 2: Subagent Lifecycle Ledger

• createSSEBridge(): New factory replacing wrapHooksForSSE() as server's bridge entry point
• agentLedger (Map): Persistent ledger tracking all start/stop events (never deletes entries)
• Orphan detection: Stops without matching starts logged to console + flagged in summary
• getAgentSummary(): Returns { total_starts, total_stops, orphan_stops[], unmatched_starts[], has_mismatch }
• SSE event: agent_lifecycle_summary emitted before manifest.finalize() when mismatches exist

Backward Compat

• wrapHooksForSSE() remains exported and functional (passes null for ledger — all guards are no-ops)
• Zero behavioral change to any existing code path

Test Results

• test/sdk/code-execution-bridge.test.js: 337/337 pass
• Inline hookSSEBridge verification: 8/8 scenarios pass (normal, orphan, unmatched, bail-out)

Files Changed

File	Lines
src/tools/codeExecutionBridge.js	+18 -6
src/utils/hookSSEBridge.js	+108 -2
src/server/claude-sdk-server.js	+13 -2
CHANGELOG.md	+29

Future Work

• Frontend: render agent_lifecycle_summary SSE event in the dashboard (e.g., warning badge on mismatch)
• Metrics: track timeout frequency and retry success rate in hookDBBridge
• Consider adjusting OVERALL_TIMEOUT_MS if Anthropic changes the ~4.5 min container idle expiry
• Evaluate whether retry_hint should trigger automatic retry with simplified constraints

[Number531]

Update (2026-03-31): Subagent lifecycle ledger shipped

Shipped across v4.10.0–v5.2.0:

Subagent Lifecycle Ledger

• hookSSEBridge.js maintains request-scoped agentTypeMap (SubagentStart → agent_type registry)
• Agent panes render full lifecycle: start time, duration (live-updating), gate checks, tool usage chips
• getAgentSummary() computes start/stop mismatch detection (has_mismatch)
• Synthetic P0 events (emitP0Start/emitP0Stop) provide visibility for document processing agent
• Agent observability replay: GET /api/db/sessions/:key/agent-progress with full history

Code Execution Timeout

• CODE_EXECUTION_TIMEOUT_MS=300000 (5 min wall-clock, v3.10.2)
• pause_turn handling: inner while loop (MAX_PAUSE_CONTINUATIONS=5) for sandbox continuations
• refusal detection: stop_reason: 'refusal' returns { success: false }, breaks turn loop
• Code execution results tracked in code_executions + code_execution_charts tables

The core tracking infrastructure requested in this issue is now live. Remaining: Grafana dashboard visualization of these metrics (low priority, data is queryable via /api/db/* endpoints).

[Number531]

Cross-reference: spec at docs/pending-updates/excel-workbook-issues.md (issue #144)

The xlsx renderer architectural review captured in issue #144 + spec doc (merged 2026-05-16) intersects with this issue's scope.

What's related: the proposed unified architecture would partially retire the code-execution observability surface this issue tracked, specifically:

• 6 envelope-counter Prometheus alerts (PR ops(runbook): STRUCTURED_OUTPUT_ENFORCEMENT pre-flip readiness — alerts + playbook + cohort plan + truth-doc registration + dashboard (PR #140) #140) — proposed for retirement
• STRUCTURED_OUTPUT_ENFORCEMENT flag (feat: SSE hardening — deploy-week-4 (v4.8.0) #42) — proposed for retirement
• envelope_decision Cloud Logging events for xlsx renders — narrower scope (still useful for subagent bridge calls)
• Most of the operator runbook (envelope-decision-debug-playbook.md) — proposed for archive

What stays useful regardless:

• claude_code_bridge_envelope_outcome_total counter (still emitted by subagent invocations)
• code_executions.envelope_source column (still useful for subagent forensics)
• Code-execution timeout awareness + subagent lifecycle ledger (this issue's core ask) — unaffected by the spec proposal

Decision dependency: this issue can proceed independently — the bridge observability work it tracks remains valuable whether the xlsx renderer is LLM-driven or unified-deterministic. The spec's retirement list is xlsx-specific, not bridge-wide.

Just flagging for awareness in case the architectural decision on #144 affects what observability surfaces remain canonical.