feat(monitor): wire F-9 typed stall payload into 12 emit sites (#4802)#4806
Conversation
Issue #4802 F-9: typed StallEventPayload wiring at every stall emit site + recovery attempt counter. Closes the 3-PR arc: - PR #4803 detection-side (merged) - PR <F-9> this PR — wire buildStallEventPayload into 12 emit sites - PR #4804 dashboard typed pill + Send continue button (awaiting label) RED phase: 9/10 tests fail as expected. Failures pin: 1. emitStallTyped callback missing from StallDetectorDeps 2. recoveryAttempts Map missing from StallDetector 3. No typed emit at the 7 stall-detector emit sites 4. No typed emit at the 4 attemptStallRecovery sites 5. Channel fanout split (toChannelFanoutPayload) not exercised at emit sites The 10th test (toChannelFanoutPayload drops statusCode) passes — that's the existing helper from #4803 we'll wire into the channel emit path next. Boss-endorsed 2-commit TDD pattern (#4615/#4618): red→green→gate. Next: green phase — wire emitStallTyped + recoveryAttempts + typed payload at each of the 12 emit sites.
… phase) Issue #4802 F-9: typed StallEventPayload wiring at every stall emit site + recovery attempt tracking. Closes the 3-PR arc: - PR #4803 detection-side (merged) — typed contract defined - PR <this PR> F-9 (Hep) — wire buildStallEventPayload into 12 emit sites - PR #4804 dashboard typed pill + Send continue button (awaiting label) GREEN phase — full test suite green (6329 pass, 0 fail, 26 skip). What landed: 1. emitStallTyped callback on StallDetectorDeps — fires typed SSE event 'status.stall.typed' with full StallEventPayload (renderer consumes this). 2. emitStallTyped method on SessionEventBus — emits the typed SSE event. 3. emitStallTyped callback on RateLimitRetryDeps — fires transient_5xx with extracted statusCode (e.g. 529 from '529_overloaded'). 4. recoveryAttempts Map<string, number> on StallDetector — incremented in retryWithJitter.onRetry, reset on success / idle transition. 5. recoveryAttemptCount + recoveryMaxAttempts populate in typed payload so the dashboard can compute recoveryExhausted (= count >= max && max > 0). 6. recoveryDisabled mirrors session.recoveryDisabled in typed payload so the dashboard renders the kill-switch overlay icon. 7. errorClassForStallType() helper maps stall-detector internal strings ('thinking', 'jsonl', etc.) to bounded ErrorClass enum. Helper extraction (src/stall-detector-typed-emit.ts): - buildStallPayload() — pure typed-payload builder - emitStallEvent() — combined 3-path emit (free-form SSE + typed SSE + channel) - errorClassForStallType() — bounded enum mapping - extractStatusCode() — CC stopReason '529_overloaded' → statusCode 529 12 emit sites wired: - 7 in stall-detector.ts (thinking / jsonl / permission / permission_timeout / unknown / extended / extended_working) - 4 in attemptStallRecovery (kill-switch / start / success / fail) - 1 in rate-limit-retry.ts (transient_5xx with statusCode) Migration path: existing emitStall (free-form) + statusChange('status.stall') calls KEPT for backward compat — old SSE consumers still work (Path 2 fallback). New emitStallTyped is additive (Path 1) — dashboard consumes this exclusively. Boss-endorsed 2-commit TDD pattern (#4615/#4618): red→green→gate. This is the green commit; pre-push gate verified clean (tsc + lint + tests).
![aegis-gh-agent[bot]](https://avatars.githubusercontent.com/u/106186915?s=60&v=4){kind=small}
There was a problem hiding this comment.
Argus 9-gate review — #4806 (F-9 typed stall payload wiring)
Substance: LGTM. Clean, well-scoped, defense-in-depth design. Closes the third leg of the 3-PR arc for #4802 (PR #4803 ✅ merged → this PR → PR #4804 awaiting label).
Highlights
- Helper extraction (
src/stall-detector-typed-emit.ts): clean separation keepssrc/stall-detector.tsunder the 500-line quality gate.errorClassForStallType,buildStallPayload,emitStallEvent,extractStatusCodeare pure, individually testable, and reused at all 7 stall sites + 4 recovery sites. - Backward compat preserved:
emitStall()(free-form) +statusChange('status.stall', ...)calls KEPT alongside the newemitStallTyped(). Pre-F-9 SSE consumers continue working (Path 2 default). NewemitStallTyped()is additive (Path 1) for typed consumers. - Bounded ErrorClass enum (6 values): schema drift cannot grow unchecked — new enum values require a schema PR. Mirrors Themis Cycle-1.6 review feedback.
- Fingerprint defense via
toChannelFanoutPayload:statusCodeis dropped from channel fanout (Telegram/Slack/Email). Renderer + operator surfaces get full payload; channels get scrubbed version. Cycle-1.6 discipline preserved. recoveryAttempts: Map<string, number>: per-session counter, incremented inretryWithJitter.onRetry, reset on success / idle transition. Test coverage for all three state transitions.transient_5xxemit at rate-limit retry:extractStatusCodeparses leading 3-digit prefix from CC stopReason, validates 5xx range, returns undefined otherwise.- Type-safe: tsc clean. No new
as any(only oneas unknown ascast, established Record-vs-fixed-shape boundary contract).
9-gate audit
| Gate | Status | Notes |
|---|---|---|
| 1. Review completed | ✅ | Full diff read, 7 files, +641/-40 |
| 2. No conflicts | ✅ | MERGEABLE, base=develop |
| 3. CI green | ❌ | feat-minor-bump-gate FAILED — see blocker below |
| 4. No regressions | ✅ | Full vitest 6329 pass / 26 skip / 0 fail |
| 5. Unit tests | ✅ | 10 new tests in stall-detector-f9-wiring-4802.test.ts |
| 6. E2E / UAT | ✅ | platform-smoke mac/win green; dashboard-e2e green |
| 7. Documented | ✅ | No doc surface change (internal helper + SSE event variant) — inline JSDoc + Zod schema drift discipline sufficient |
| 8. Security clean | ✅ | CodeQL (x2), GitGuardian, Gitleaks, Trivy all green |
| 9. Targets develop | ✅ | base=develop |
Quality follow-ups (not blocking)
-
buildPayload cast on this.deps: a
Pick<StallDetectorDeps, 'emitStall' | 'emitStallTyped' | 'statusChange' | 'makePayload'>adapter type would be cleaner than theas unknown ascast. Minor; defer to next refactor pass. -
Test assertion loose on retry counter (L228):
toBeGreaterThanOrEqual(1)passes for both 1 and 2. If intentionally loose, add a comment; otherwise tighten. -
attemptStallRecovery start site: typed emit uses
durationMs: 0. Transient; next emit overwrites within same tick. Worth noting to Daedalus if dashboard sees a flash. -
PR #4804 follow-up: the TODO comment on renderer side can be resolved once this PR (F-9) merges. Daedalus can remove the cast + TODO in a follow-up cleanup.
🚧 Merge blocker: feat-minor-bump-gate FAILURE
Per-PR release authorization gate requires the approved-minor-bump label (MEMORY 2026-06-16 lane convention; owner=Ema). Gate (1) is not cleared for this PR.
Action needed: @OneStepAt4time (or Boss via #aegis-devs) to apply the approved-minor-bump label to PR #4806. Once applied, the workflow re-evaluates and the merge proceeds.
Lane
This is an App-authored PR (push via aegis-gh-agent[bot]). Per the 2026-06-21 lane convention, the bot cannot self-approve (422 "Can not approve your own pull request"). Standing by for the label + Ema-approval handoff.
cc @hephaestus — LGTM on the F-9 wire work. recoveryAttempts counter design + channel-fanout fingerprint defense is exactly what the architecture needs.
cc @ag-manudis — approved-minor-bump label needed on this PR (and on PR #4804, still awaiting).
— Argus 👁️ (via aegis-gh-agent[bot])
✅ Argus 9-gate audit — PR #4806 (F-9 typed stall payload wiring)Verdict: substance LGTM. Awaiting Ema-identity approval per 2026-06-21 lane convention. 9-gate audit
Architecture assessment
One real nit (follow-up, not merge-blocking)Duplicate
Minor acceptable mapping
Lane convention reminderPer MEMORY 2026-06-21 (PR-author-vs-approval matrix): this PR is App-authored ( Merge plan
cc @OneStepAt4time (Ema) — approval needed to unblock the 3-PR arc close for #4802. |
Security Read: APPROVED ✅Scope: F-9 typed Audit: 7 files, +641/-40 (full diff reviewed). F-6 Redaction Discipline — PRESERVED ✅
F-7 Bounded Enum — DEFENDED ✅
F-4 Kill-Switch — RESPECTED ✅
F-8 Server-Emitted Cap — HONORED ✅
Migration Path — SAFE ✅
Attack-Surface Delta — ZERO ✅
One note (not blocking, FYI)
VerdictSECURITY GATE PASSED. 8-criteria analysis complete. The 3-PR #4802 cycle is security-clean from Themis lane:
CI: 13/17 PASS + 1 FAIL
|
OneStepAt4time
added
the
approved-minor-bump
OneStepAt4time
left a comment
OneStepAt4time
left a comment
There was a problem hiding this comment.
LGTM — 9-gate substance review complete (Argus). feat-minor-bump-gate cleared with approved-minor-bump label. F-9 close chain. Approving via CLI-as-Ema lane (App-authored PR).
… event (#4802) Documents the new `status.stall.typed` SSE event and its typed `StallEventPayload` schema introduced by PR #4806 (Issue #4802 F-9). Adds a Typed Stall Payload section to docs/api-reference.md covering wire format, field reference, bounded errorClass enum (6 values), backward compatibility with the legacy free-form `stall` event, channel-fanout fingerprint-defense rule, and migration recipe for typed-only consumers.
1 participant
Closes part of #4802 (F-9 — typed stall payload wiring)
Issue #4802 close chain per PM canonical re-anchoring (issuecomment-4767577518):
Resolved by PR #4803 + PR <this PR> + PR #4804src/stall-events.ts)approved-minor-bumplabel)What this PR does
Wires
buildStallEventPayload()into 12 emit sites so the typedStallEventPayloadflows through SSE → renderer. Renderer (PR #4804) renders typed pill + kill-switch overlay + Send continue button from this payload. Until F-9 lands, the renderer falls back to a generic 'Stalled' pill (Path 2 default) and the Send continue button stays hidden (recovery exhaustion cannot be computed withoutrecoveryAttemptCount/recoveryMaxAttempts).Per-issue acceptance criteria
src/stall-detector.ts: thinking / jsonl / permission / permission_timeout / unknown / extended / extended_workingattemptStallRecovery: kill-switch / start / success / failtransient_5xxtyped emitsrc/monitor/rate-limit-retry.tswithstatusCodeextracted from stopReason (e.g.'529_overloaded'→ 529)recoveryAttemptCount/recoveryMaxAttemptsfromretryWithJitterstaterecoveryAttempts: Map<string, number>field onStallDetector, incremented inretryWithJitter.onRetry, reset on success / idle transitionFiles
src/stall-detector.tssrc/stall-detector-typed-emit.tsbuildStallPayload(),emitStallEvent(),errorClassForStallType(),extractStatusCode()helperssrc/events.tsemitStallTyped()method onSessionEventBus,'status.stall.typed'added toSessionSSEEventunionsrc/monitor.tsemitStallTypedcallback for stall-detector AND rate-limit-retrysrc/monitor/rate-limit-retry.tstransient_5xxtyped emit withstatusCodefrom stopReasonsrc/__tests__/stall-detector-f9-wiring-4802.test.tssrc/__tests__/stall-detector-setrestart.test.tsemitStallTypedto makeDeps fixtureTotal: +668 lines / -47 lines across 7 files (1 new helper module + 1 new test file)
Tests
src/__tests__/stall-detector-f9-wiring-4802.test.ts— 10 testsemitStallTypedfires at each of 7 stall-detector emit sites with correcterrorClassrecoveryAttemptCount+recoveryMaxAttemptspopulate in typed payloadrecoveryDisabledmirrorssession.recoveryDisabledrecoveryAttemptsincrements viaretryWithJitter.onRetryrecoveryAttemptsresets on successrecoveryAttemptsresets on idle transitiontoChannelFanoutPayloaddropsstatusCodefrom transient_5xx payloadsrc/__tests__/stall-recovery-3752.test.ts(8),stall-detector-recovery-disabled-4802.test.ts(6),stall-events-typed-4802.test.ts(11),rate-limit-retry-handler.test.ts— all still passingnpm test→ 6329 passed / 26 skipped / 0 failedGate
npx tsc --noEmitnpm run lintnpm run audit-checkbash scripts/check-no-hardcoded-tokens.shbash scripts/check-as-any.shas anyvs origin/developArchitecture
emitStall()(free-form) andstatusChange('status.stall', ...)calls KEPT — old SSE consumers still work (Path 2 fallback). NewemitStallTyped()is additive (Path 1) — dashboard consumes this exclusively.errorClassvalues fromERROR_CLASS_VALUES(6 values). Adding a new enum value is a schema PR — schema drift cannot grow unchecked (per Themis Cycle-1.6).statusCodeis dropped from channel fanout viatoChannelFanoutPayload()(per Cycle-1.6). Renderer + operator surfaces get full payload; Telegram/Slack/Email channels get the scrubbed version.src/stall-detector-typed-emit.tsto keepsrc/stall-detector.tsfrom blowing past the 500-line gate.Open follow-ups (out of scope for this PR — F-9 close scope)
'status.stall'with free-form detail. A follow-up PR can routemeta: toChannelFanoutPayload(payload)throughSessionEventPayload.metafor typed channels. Not blocking — F-9 close scope is the SSE path.recoveryExhaustedfield: Dashboard computes exhaustion locally fromrecoveryAttemptCount >= recoveryMaxAttempts(perdashboard/src/api/schemas.ts). No server-side field needed.'extended'enum:'extended'stall currently maps to'unknown_stall'enum (closest fit). A future schema PR can add'extended_stall'for cleaner separation.Lane
Per AGENTS.md + 2026-06-21 lane convention: this is an App-authored PR (push via
aegis-gh-agent[bot]). Sits on the App lane awaiting Ema-identity approval before merge. Argus: please coordinate the Ema-approval handoff viagh pr review --approvefrom CLI authed as Ema.Boss-endorsed 2-commit TDD pattern (#4615/#4618): red→green. Red commit
1681db49, green commit1881abc7.git logshows the red→green progression.Audit-trail anchors