Summary

The doctor's supervisor health check and gbrain jobs supervisor status both counted every worker_exited audit event as a crash regardless of cause. After v0.34.3.0's RSS-watchdog added more code=0 worker drains, the count inflated to 120+/day on a healthy brain — surfacing as the "Supervisor crashes: 120x/24h (was 62x — nearly doubled)" alarm.

The classifier upstream in child-worker-supervisor.ts:309-321 was already stamping a five-value likely_cause field on every exit (clean_exit, graceful_shutdown, runtime_error, oom_or_external_kill, unknown); neither read site looked at it. v0.35.5.0 ships a shared classifier so both surfaces agree.

Helper foundation (d9975af4)

• New isCrashExit(event) + summarizeCrashes(events) + CrashSummary type + CLEAN_EXIT_CAUSES constant in src/core/minions/handlers/supervisor-audit.ts
• Denylist semantics — only clean_exit and graceful_shutdown are non-crashes; future unrecognized causes surface by default
• 14-case unit test pinning every branch (9 isCrashExit cases + 5 summarizeCrashes aggregator cases)

Consumer wiring (1d9a902d)

• gbrain doctor: replaces ad-hoc filter with summarizeCrashes; warn threshold dropped from >3 to >=1 (calibrated counter); ok + warn messages include per-cause breakdown (runtime=N oom=M unknown=K legacy=L) and clean_exits_24h=N
• gbrain jobs supervisor status: same wiring; JSON output adds crashes_by_cause + clean_exits_24h; human output adds per-cause line + Clean exits (24h) line
• 4 source-grep wiring assertions in test/doctor.test.ts guard both call sites against drift

Metadata (059b60df + cfc2a765)

• VERSION + package.json bumped to v0.35.5.0
• CHANGELOG entry with usage instructions
• CLAUDE.md "Key files" entries extended for supervisor-audit.ts, doctor.ts, jobs.ts; llms-full.txt regenerated

Test Coverage

src/core/minions/handlers/supervisor-audit.ts (NEW)
├── isCrashExit(event)              9 branches, all covered
│   ├── event !== 'worker_exited' → false            ✓ Case 9
│   ├── likely_cause = 'clean_exit' → false          ✓ Case 1
│   ├── likely_cause = 'graceful_shutdown' → false   ✓ Case 2
│   ├── likely_cause = 'runtime_error' → true        ✓ Case 3
│   ├── likely_cause = 'oom_or_external_kill' → true ✓ Case 4
│   ├── likely_cause = 'unknown' → true              ✓ Case 5
│   ├── likely_cause = <future unrecognized> → true  ✓ Case 6 (denylist guard)
│   ├── no cause + code=0 → false                    ✓ Case 7
│   └── no cause + code!=0 → true                    ✓ Case 8 + null-code case
└── summarizeCrashes(events)        9 branches, all covered
    ├── non-exit event skipped                       ✓ mixed + only-non-exit
    ├── clean_exit / graceful_shutdown → clean_exits ✓ mixed (4)
    ├── runtime_error / oom / unknown buckets        ✓ mixed (2/1/1)
    ├── legacy (no cause, code!=0) → legacy++        ✓ mixed (1)
    ├── unrecognized cause → legacy++                ✓ future-cause case
    └── empty input                                  ✓ empty-summary case

src/commands/doctor.ts + src/commands/jobs.ts (MODIFIED)
└── summarizeCrashes wiring + threshold + message    ✓ 4 source-grep assertions

COVERAGE: 22/22 paths tested (100%)
QUALITY: 14 unit tests, 4 wiring assertions, 1 docstring-truth test

Tests: ~3650 → 3664 (+14 new in supervisor-audit.test.ts, +4 wiring in doctor.test.ts)

Pre-Landing Review

Pre-Landing Review: 3 issues — 1 auto-fixed (stale docstring on summarizeCrashes updated to reflect that legacy bucket catches both pre-v0.34 entries AND future unrecognized causes), 2 skipped as scope creep (DRY format-string helper, type-union refactor — captured for future cleanup).

Specialist review: 4 specialists dispatched (testing, maintainability, security, performance). 0 critical, 3 informational — all in maintainability and triaged. PR Quality Score: 9.0/10.

Adversarial Review

Claude adversarial subagent surfaced 13 informational observations. All triaged as pre-existing surfaces, accepted plan trade-offs from /plan-eng-review, or future-data-tuning concerns. None in-scope for this PR. Notable follow-ups identified:

• Clean-exit rate threshold: the new doctor surface shows clean_exits_24h=N so operators see drain rate at a glance. A warn threshold on that count is the natural follow-up once we have post-fix data (D5 from plan-eng-review intentionally deferred this).
• ISO-week rotation boundary in readSupervisorEvents: pre-existing 24h-window visibility hole at week boundaries. Separate fix.

Codex ran during /plan-eng-review and surfaced 4 substantive findings, all incorporated: the duplicate bug at jobs.ts:805, denylist semantics, shared helper extraction, and threshold rebaseline.

Scope Drift

Scope Check: CLEAN. Intent matches delivery (fix the doctor's miscounting). No drift, no missing requirements.

Plan Completion

• T1 — src/core/minions/handlers/supervisor-audit.ts exports isCrashExit, summarizeCrashes, CrashSummary with denylist semantics + legacy fallback + per-cause aggregation
• [~] T2 — Tests landed but doctor-integration approach changed from plan: 9-case isCrashExit matrix + 5 summarizeCrashes aggregation cases in supervisor-audit.test.ts plus 4 source-grep wiring assertions in doctor.test.ts (vs. the plan's single runtime-fixture integration test). Same drift-prevention guarantee via different mechanism.
• T3 — doctor.ts wired to summarizeCrashes; warn threshold dropped >3 → >=1; messages widened with per-cause breakdown + clean_exits_24h
• T4 — jobs.ts supervisor status wired to summarizeCrashes; JSON adds crashes_by_cause + clean_exits_24h; human output expanded

4 plan items: 3 DONE, 1 CHANGED. No NOT DONE. No UNVERIFIABLE.

Verification Results

Plan verification skipped — fix has no UI/URL surface, only CLI output. Local end-to-end smoke ran against a synthesized supervisor audit JSONL fixture: 6 worker_exited events (3 clean_exit + 1 graceful_shutdown + 1 runtime_error + 1 oom_or_external_kill) → doctor reports Worker crashed 2x in last 24h (runtime=1 oom=1 unknown=0 legacy=0). Pre-fix would have reported "crashed 6x" with no qualitative signal.

TODOS

No items completed by this fix. TODOS.md unchanged.

Documentation

• CLAUDE.md: added new entry for src/core/minions/handlers/supervisor-audit.ts covering the v0.35.5.0 exports (isCrashExit, summarizeCrashes, CrashSummary, CLEAN_EXIT_CAUSES); extended src/commands/doctor.ts entry with the v0.35.5.0 wire-up (shared summarizeCrashes consumer, >=1 warn threshold, runtime=A oom=B unknown=C legacy=D per-cause breakdown, clean_exits_24h=N in ok message); extended src/commands/jobs.ts entry with the v0.35.5.0 crashes_by_cause + clean_exits_24h JSON fields and cross-surface parity contract.
• llms-full.txt: regenerated via bun run build:llms to match the CLAUDE.md edit.
• CHANGELOG.md: v0.35.5.0 entry shipped with the fix; "## To take advantage of v0.35.5.0" block included.

Test plan

• bun run typecheck clean
• bun run test — 6604 pass / 0 fail / 0 skip (full parallel suite, 231s)
• bun test test/supervisor-audit.test.ts — 14/14 pass (21 expects, 35ms)
• bun test test/doctor.test.ts — 43/43 pass (124 expects, ~3.3s in isolation)
• End-to-end smoke against synthesized audit JSONL — message shape verified
• On affected machine post-merge: gbrain doctor 2>&1 | grep -i supervisor shows real crash count (not 120x clean-exit count)
• On affected machine post-merge: gbrain jobs supervisor status --json | jq '{crashes_24h, clean_exits_24h}' matches doctor's count

🤖 Generated with Claude Code