comisai 1.0.45 → 1.0.46

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-spend-verdict.js

@@ -1,35 +1,34 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * WR-4 (177-obs-loop): the NAMED terminal SPEND root-cause verdict spliced into
+ * The NAMED terminal SPEND root-cause verdict spliced into
  * the `obs-explain-heuristics` registry — `spend_exceeded`.
  *
  * Extracted into this sibling (the `obs-explain-learning-verdicts.ts` discipline)
  * to keep `obs-explain-heuristics.ts` under the 500-line `obs-handlers/*` subdir
  * cap. PURE: no LLM, no I/O, no globals — same signals ⇒ same verdict forever
- * (the Glass Box determinism invariant).
+ * (the report-determinism invariant).
  *
- * Ordering contract (registry position #2 — LIVE v2.28 260621): the dollars
+ * Ordering contract (registry position #2): the dollars
  * kill-switch is an ADMINISTRATIVE pre-emption that aborts at admission, causally
  * INDEPENDENT of tool failures (a failed tool returns ~0 bytes / ~$0 and cannot
  * drive cumulative spend). It is therefore NOT a downstream terminal label like
  * context_exhausted / output_starved / prompt_timeout (which a runaway tool CAN
  * cause) — it out-ranks the breaker/dependency/timeout/degradation heuristics and
- * sits directly below the single X3-frozen content_heuristic_misclassification
- * verdict (the one specific Comis-defect indicator). It was originally spliced
- * into the terminal band below every tool-failure cause; a live VPS incident
- * proved that masked the kill-switch behind chronic breaker noise — a spend-killed
- * session root-caused to breaker_opened_repeated_failure while the operator's
- * turns were all blocked by the ceiling. Before the verdict existed at all a
- * spend-killed session root-caused to NOTHING (the security-review WR-4 finding);
- * both gaps directly violated this milestone's thesis + CLAUDE.md's troubleshooting
- * feedback loop ("verdict ranked chronic noise over the acute event").
+ * sits directly below the single fixture-frozen content_heuristic_misclassification
+ * verdict (the one specific Comis-defect indicator). Splicing it any lower —
+ * into the terminal band below the tool-failure causes — masks the kill-switch
+ * behind chronic breaker noise: a spend-killed
+ * session would root-cause to breaker_opened_repeated_failure while the operator's
+ * turns were all blocked by the ceiling (and without the verdict at all a
+ * spend-killed session root-causes to NOTHING). The acute administrative event
+ * must out-rank the chronic noise.
  *
  * Keys on the metadata-derived endReason (END_REASON_MAP spend_exceeded →
- * "spend_exceeded", WR-2). The frozen 678/503 fixtures carry no endReason
+ * "spend_exceeded"). The frozen 678/503 fixtures carry no endReason
  * "spend_exceeded" ⇒ cannot regress them. The detail NAMES the config key family
- * the operator turns (the §2.7 "name the knob" doctrine); the exact breached
+ * the operator turns (the "name the exact knob" doctrine); the exact breached
  * scope + per-scope $ amounts live on the content-free spend.exceeded trajectory
- * record (WR-4), pointed to by the suggested step. The return type is structurally
+ * record, pointed to by the suggested step. The return type is structurally
  * identical to the registry's `RootCause` (no cross-module type import ⇒ no cycle).
  *
  * @module
@@ -42,11 +41,11 @@
 export const spendExceededVerdict = (s) => {
     if (s.endReason !== "spend_exceeded")
         return null;
-    // OBS-3 (openclaw-usecases 2026-06-25): a per-ROOT `autonomy.budget` abort (the
+    // A per-ROOT `autonomy.budget` abort (the
     // token / wall-clock / aggregateUsd limb) is a DIFFERENT knob tree than the priced
     // `observability.spend` ceiling — pointing the operator at observability.spend.*
-    // misdirects them (the SPEND-ABORT-OBS class — already fixed in the WARN; this is
-    // the same fix at the `explain` VERDICT layer). When the terminal abort carried the
+    // misdirects them (the WARN log line already draws this distinction; the
+    // `explain` VERDICT layer must match it). When the terminal abort carried the
     // per-root limb, name `autonomy.budget.<limb>` + the numbers in their own unit so
     // the verdict answers "which limb, by how much, which knob" in one call.
     const prb = s.perRootBudget;
@@ -58,7 +57,7 @@ export const spendExceededVerdict = (s) => {
                 `per-ROOT autonomy.budget meter, NOT the observability.spend $-ceiling.`,
             suggestedNextSteps: [
                 `raise this agent's autonomy.budget.${prb.limb} (currently ${prb.cap} ${prb.unit}) for heavier/longer turns — NOT observability.spend.*`,
-                "note the token limb counts cache-read tokens, so a cache-heavy multi-tool turn hits it fast at trivial actual $ (BUDGET-02); the wall-clock limb is the stuck-tree backstop",
+                "note the token limb counts cache-read tokens, so a cache-heavy multi-tool turn hits it fast at trivial actual $; the wall-clock limb is the stuck-tree backstop",
             ],
         };
     }

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-terminal-drive-evicted-verdict.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `terminal_drive_evicted` — the reaper-killed-drive root-cause verdict spliced into
+ * the `obs-explain-heuristics` registry.
+ *
+ * Extracted into this sibling (the `obs-explain-terminal-drive-verdict.ts` /
+ * `obs-explain-spend-verdict.ts` discipline) to keep `obs-explain-heuristics.ts` under
+ * the 500-line `obs-handlers/*` subdir cap. PURE: no LLM, no I/O, no globals — same
+ * signals ⇒ same verdict forever.
+ *
+ * The failure mode this verdict makes visible: an autonomous webhook-driven drive
+ * doing real work is idle-evicted by the terminal reaper — the `worker.idleTtlMs`
+ * cap fires because a backgrounded drive's `lastActivity` does not advance on a
+ * quiet compile, and the producing keep-alive did not hold. The drive dies mid-task
+ * while `comis explain` reports `endReason:success` (the turn that OPENED the drive
+ * returned fine) → a NULL verdict, so the reaper kill stays INVISIBLE without
+ * hand-correlating the daemon WARN `terminal session evicted` timestamp against the
+ * last activity. The keep-alive keeps a *producing* drive alive; THIS verdict is
+ * that mechanism's observability completion — if the keep-alive ever regresses (a
+ * producing drive idle-reaped again), `explain` names it in one call.
+ *
+ * Keyed on the bridged `terminalDriveEvicted` signal (folded from the
+ * `terminal.session_evicted` trajectory record). Fires ONLY on the two "cut-short" caps:
+ *   - `idle`      — the idle-TTL reap (the acute autonomous-drive-stranding case). Only
+ *                   fires when the reaper's `!isBusy` gate passed, i.e. the drive was
+ *                   genuinely quiet — but a drive that HAD been producing (derived
+ *                   `wasProducing`) going quiet-then-reaped is the keep-alive
+ *                   regression canary.
+ *   - `wall_clock`— the total-lifetime cap (a long build hit its ceiling mid-work).
+ * It deliberately does NOT fire on `max_sessions` (LRU eviction of the IDLEST session to
+ * make room — incidental resource pressure, not a drive-cut-short cause) or
+ * `max_interactions` (a deliberate per-session turn-budget cap, its own distinct limit) —
+ * surfacing those as a scary root cause would cry wolf (the BENIGN_DAG_DEGRADED_REASONS
+ * discipline: do not rank a routine cap-trip over the acute event).
+ *
+ * Registered AFTER `terminalDriveNoTaskVerdict` (a drive opened, never tasked, THEN
+ * idle-reaped is rooted in the no-task stall — the eviction is its consequence) and ABOVE
+ * the `completed_with_tool_errors` catch-all (a reaper kill is a specific terminal-
+ * lifecycle cause, more root than "some tools failed"). It keys only on
+ * `terminalDriveEvicted` (absent on the frozen 678/503 fixtures), so it cannot regress a
+ * non-terminal session. The return type is structurally identical to the registry's
+ * `RootCause` (no cross-module type import ⇒ no cycle).
+ *
+ * @module
+ */
+import type { IncidentSignals } from "@comis/core";
+/** Structural twin of `obs-explain-heuristics.RootCause` (kept local — no import cycle). */
+type TerminalDriveVerdict = {
+    code: string;
+    detail: string;
+    suggestedNextSteps: string[];
+};
+/**
+ * `terminal_drive_evicted` — fires when a durable terminal drive was reaped by an
+ * idle-TTL or wall-clock cap, cutting the (possibly still-working) drive short.
+ */
+export declare const terminalDriveEvictedVerdict: (s: IncidentSignals) => TerminalDriveVerdict | null;
+export {};

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-terminal-drive-evicted-verdict.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `terminal_drive_evicted` — the reaper-killed-drive root-cause verdict spliced into
+ * the `obs-explain-heuristics` registry.
+ *
+ * Extracted into this sibling (the `obs-explain-terminal-drive-verdict.ts` /
+ * `obs-explain-spend-verdict.ts` discipline) to keep `obs-explain-heuristics.ts` under
+ * the 500-line `obs-handlers/*` subdir cap. PURE: no LLM, no I/O, no globals — same
+ * signals ⇒ same verdict forever.
+ *
+ * The failure mode this verdict makes visible: an autonomous webhook-driven drive
+ * doing real work is idle-evicted by the terminal reaper — the `worker.idleTtlMs`
+ * cap fires because a backgrounded drive's `lastActivity` does not advance on a
+ * quiet compile, and the producing keep-alive did not hold. The drive dies mid-task
+ * while `comis explain` reports `endReason:success` (the turn that OPENED the drive
+ * returned fine) → a NULL verdict, so the reaper kill stays INVISIBLE without
+ * hand-correlating the daemon WARN `terminal session evicted` timestamp against the
+ * last activity. The keep-alive keeps a *producing* drive alive; THIS verdict is
+ * that mechanism's observability completion — if the keep-alive ever regresses (a
+ * producing drive idle-reaped again), `explain` names it in one call.
+ *
+ * Keyed on the bridged `terminalDriveEvicted` signal (folded from the
+ * `terminal.session_evicted` trajectory record). Fires ONLY on the two "cut-short" caps:
+ *   - `idle`      — the idle-TTL reap (the acute autonomous-drive-stranding case). Only
+ *                   fires when the reaper's `!isBusy` gate passed, i.e. the drive was
+ *                   genuinely quiet — but a drive that HAD been producing (derived
+ *                   `wasProducing`) going quiet-then-reaped is the keep-alive
+ *                   regression canary.
+ *   - `wall_clock`— the total-lifetime cap (a long build hit its ceiling mid-work).
+ * It deliberately does NOT fire on `max_sessions` (LRU eviction of the IDLEST session to
+ * make room — incidental resource pressure, not a drive-cut-short cause) or
+ * `max_interactions` (a deliberate per-session turn-budget cap, its own distinct limit) —
+ * surfacing those as a scary root cause would cry wolf (the BENIGN_DAG_DEGRADED_REASONS
+ * discipline: do not rank a routine cap-trip over the acute event).
+ *
+ * Registered AFTER `terminalDriveNoTaskVerdict` (a drive opened, never tasked, THEN
+ * idle-reaped is rooted in the no-task stall — the eviction is its consequence) and ABOVE
+ * the `completed_with_tool_errors` catch-all (a reaper kill is a specific terminal-
+ * lifecycle cause, more root than "some tools failed"). It keys only on
+ * `terminalDriveEvicted` (absent on the frozen 678/503 fixtures), so it cannot regress a
+ * non-terminal session. The return type is structurally identical to the registry's
+ * `RootCause` (no cross-module type import ⇒ no cycle).
+ *
+ * @module
+ */
+/** The idle-TTL / wall-clock caps that mean "the drive was cut short" (vs the incidental
+ *  max_sessions LRU or the deliberate max_interactions turn budget). */
+const CUT_SHORT_REASONS = new Set(["idle", "wall_clock"]);
+/** The exact config knob each cut-short cap is bound to — named in the verdict so the
+ *  reader sees WHICH knob to inspect (the "name the knob, not just the symptom" rule). */
+const CAP_KNOB = {
+    idle: "worker.idleTtlMs",
+    wall_clock: "the terminal entry's limits.wallClockMs",
+};
+/**
+ * `terminal_drive_evicted` — fires when a durable terminal drive was reaped by an
+ * idle-TTL or wall-clock cap, cutting the (possibly still-working) drive short.
+ */
+export const terminalDriveEvictedVerdict = (s) => {
+    const ev = s.terminalDriveEvicted;
+    if (ev === undefined)
+        return null; // no eviction record → not this cause.
+    if (!CUT_SHORT_REASONS.has(ev.reason))
+        return null; // max_sessions / max_interactions → not a cut-short cause.
+    const lifetimeMin = Math.round(ev.idleMs / 60_000);
+    const knob = CAP_KNOB[ev.reason] ?? "the reaper cap";
+    const producingClause = ev.wasProducing
+        ? "The drive HAD been producing (a `producing` drive_promoted preceded the eviction) — so it was cut short WHILE working. " +
+            "The producing keep-alive (checkLiveness freezes a producing drive's idle clock) is exactly what should have held it alive; " +
+            "an idle-reap here is its regression canary."
+        : "The drive never crossed the producing boundary (no `producing` promotion) — so this is the expected TTL/lifetime cleanup of a quiet, unattended drive that never got going.";
+    return {
+        code: "terminal_drive_evicted",
+        detail: `a durable terminal drive was evicted by the reaper's '${ev.reason}' cap ` +
+            `(${knob}) after ~${lifetimeMin}min of lifetime. ${producingClause} ` +
+            "In an UNATTENDED (webhook/cron) drive this ends the autonomous session with no human to resume it.",
+        suggestedNextSteps: [
+            ev.wasProducing
+                ? `confirm the producing keep-alive held for this drive (checkLiveness must NOT freeze — and thus must keep alive — a producing drive); if it was idle-reaped while producing, that is a regression`
+                : `if the drive still had work, raise ${knob} or deliver the task so the drive stays busy (the reaper's !isBusy idle-gate spares an actively-busy drive)`,
+            `inspect ${knob} against the drive's real work cadence — a backgrounded drive's lastActivity does not advance on a quiet compile`,
+            "obs.explain depth=full for the terminal_session_* + terminal.drive_promoted + terminal.session_evicted sequence",
+        ],
+    };
+};

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-terminal-drive-verdict.d.ts

@@ -7,7 +7,7 @@
  * under the 500-line `obs-handlers/*` subdir cap. PURE: no LLM, no I/O, no globals —
  * same signals ⇒ same verdict forever.
  *
- * Live r3tdd/r3terse (webhook-claude-cli-tdd 2026-06-30): an agent driven by a
+ * The failure mode this verdict makes visible (seen live): an agent driven by a
  * webhook opened a coding-CLI terminal drive (`terminal_session_create`, e.g.
  * `claude`), cleared the launch gate, then `terminal_session_wait`'d — and the
  * durable terminal backgrounded the drive at the post-gate idle BEFORE the agent

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-terminal-drive-verdict.js

@@ -8,7 +8,7 @@
  * under the 500-line `obs-handlers/*` subdir cap. PURE: no LLM, no I/O, no globals —
  * same signals ⇒ same verdict forever.
  *
- * Live r3tdd/r3terse (webhook-claude-cli-tdd 2026-06-30): an agent driven by a
+ * The failure mode this verdict makes visible (seen live): an agent driven by a
  * webhook opened a coding-CLI terminal drive (`terminal_session_create`, e.g.
  * `claude`), cleared the launch gate, then `terminal_session_wait`'d — and the
  * durable terminal backgrounded the drive at the post-gate idle BEFORE the agent
@@ -47,7 +47,7 @@ export const terminalDriveNoTaskVerdict = (s) => {
     const sentText = s.toolStats["terminal_session_send_text"];
     if (sentText !== undefined && sentText.ok > 0)
         return null;
-    // DRIVE-02: when the bridged terminal.drive_promoted signal is present, name the
+    // When the bridged terminal.drive_promoted signal is present, name the
     // backgrounding reason + count explicitly (else a generic clause). Makes the
     // log-only mode_detached promotion visible in the one-call `explain` verdict.
     const backgrounding = s.terminalDrivePromoted !== undefined

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-voice-fold.d.ts

@@ -1,5 +1,5 @@
 /**
- * OBS-02 (Phase 196): the seq-aware voice (STT/TTS) cost/outcome fold.
+ * The seq-aware voice (STT/TTS) cost/outcome fold.
  *
  * Extracted from `obs-explain-signals-fields.ts` (which holds the image/vision/
  * video folds) to keep BOTH that file AND `obs-explain-signals.ts` under the
@@ -9,17 +9,17 @@
  * `delivered`/`jobId`/background-completion — voice is wholly in-turn like image/
  * vision). Pure + content-free: reads only ids/labels/numbers/booleans/closed-enum
  * source via `asString`/`asNumber` — never an audio byte, transcript, or a
- * provider message (T-196-09).
+ * provider message.
  *
  * @module
  */
 import type { IncidentSignals } from "@comis/core";
-/** OBS-02 (196): the reconstructed voice (STT/TTS) turn (the non-optional shape
+/** The reconstructed voice (STT/TTS) turn (the non-optional shape
  *  of `IncidentSignals["voice"]`). */
 export type IncidentVoiceSignal = NonNullable<IncidentSignals["voice"]>;
-/** OBS-02 (196): the seq-aware fold state for the reconstructed voice turn + the
+/** The seq-aware fold state for the reconstructed voice turn + the
  *  `seq` of the record that last SET `outcome` (the terminal record). Mirrors
- *  `VideoFoldState`/`VisionFoldState`/`ImageFoldState` (IN-04): the fold is driven
+ *  `VideoFoldState`/`VisionFoldState`/`ImageFoldState`: the fold is driven
  *  by the record stream's `seq`, NOT array order, so only a record with a `seq` ≥
  *  the last outcome-setting record can overwrite `outcome`. */
 export interface VoiceFoldState {
@@ -28,20 +28,20 @@ export interface VoiceFoldState {
     outcomeSeq: number;
 }
 /**
- * OBS-02 (196): fold one `media.stt.*` / `media.tts.*` trajectory record into the
+ * Fold one `media.stt.*` / `media.tts.*` trajectory record into the
  * reconstructed voice turn (the analog of `accumulateVisionRecord`). Pure: takes
  * the prior fold state + the record's `type`/`data`/`seq` and returns the new
  * state. The voice fold is SIMPLER than video — no `delivered`/`jobId`/background-
  * completion; voice is wholly in-turn like image/vision. The terminal
  * `media.*.completed` / `media.*.failed` record sets `outcome` (+ keyless/model/
- * durationMs/costUsd on success — the cost rides completed, Route a; keyless `0`
- * lands here, OBS-05; errorKind on failure). `media.*.requested` seeds a
+ * durationMs/costUsd on success — the cost rides completed; keyless `0`
+ * lands here; errorKind on failure). `media.*.requested` seeds a
  * conservative `outcome:"failed"` block (so a turn aborting before a terminal still
  * surfaces — the `video.requested` seed precedent), carrying `source` if present;
  * it does NOT set `outcomeSeq`. Returns `prev` unchanged for a non-voice type.
  * Content-free reads (asString/asNumber + the boolean reader).
  *
- * SEQ-AWARE (IN-04): a terminal completed/failed only overwrites `outcome` when its
+ * SEQ-AWARE: a terminal completed/failed only overwrites `outcome` when its
  * `seq` is ≥ the seq of the last outcome-setting record — a stale lower-seq record
  * arriving after a higher-seq terminal no longer flips the outcome. The
  * `media.*.requested` seed does not set `outcomeSeq`, so the first real terminal

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-voice-fold.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * OBS-02 (Phase 196): the seq-aware voice (STT/TTS) cost/outcome fold.
+ * The seq-aware voice (STT/TTS) cost/outcome fold.
  *
  * Extracted from `obs-explain-signals-fields.ts` (which holds the image/vision/
  * video folds) to keep BOTH that file AND `obs-explain-signals.ts` under the
@@ -10,7 +10,7 @@
  * `delivered`/`jobId`/background-completion — voice is wholly in-turn like image/
  * vision). Pure + content-free: reads only ids/labels/numbers/booleans/closed-enum
  * source via `asString`/`asNumber` — never an audio byte, transcript, or a
- * provider message (T-196-09).
+ * provider message.
  *
  * @module
  */
@@ -24,20 +24,20 @@ function asNumber(v) {
     return typeof v === "number" && Number.isFinite(v) ? v : undefined;
 }
 /**
- * OBS-02 (196): fold one `media.stt.*` / `media.tts.*` trajectory record into the
+ * Fold one `media.stt.*` / `media.tts.*` trajectory record into the
  * reconstructed voice turn (the analog of `accumulateVisionRecord`). Pure: takes
  * the prior fold state + the record's `type`/`data`/`seq` and returns the new
  * state. The voice fold is SIMPLER than video — no `delivered`/`jobId`/background-
  * completion; voice is wholly in-turn like image/vision. The terminal
  * `media.*.completed` / `media.*.failed` record sets `outcome` (+ keyless/model/
- * durationMs/costUsd on success — the cost rides completed, Route a; keyless `0`
- * lands here, OBS-05; errorKind on failure). `media.*.requested` seeds a
+ * durationMs/costUsd on success — the cost rides completed; keyless `0`
+ * lands here; errorKind on failure). `media.*.requested` seeds a
  * conservative `outcome:"failed"` block (so a turn aborting before a terminal still
  * surfaces — the `video.requested` seed precedent), carrying `source` if present;
  * it does NOT set `outcomeSeq`. Returns `prev` unchanged for a non-voice type.
  * Content-free reads (asString/asNumber + the boolean reader).
  *
- * SEQ-AWARE (IN-04): a terminal completed/failed only overwrites `outcome` when its
+ * SEQ-AWARE: a terminal completed/failed only overwrites `outcome` when its
  * `seq` is ≥ the seq of the last outcome-setting record — a stale lower-seq record
  * arriving after a higher-seq terminal no longer flips the outcome. The
  * `media.*.requested` seed does not set `outcomeSeq`, so the first real terminal
@@ -66,9 +66,9 @@ export function accumulateVoiceRecord(prev, type, data, seq) {
             const model = asString(data.model);
             const durationMs = asNumber(data.durationMs);
             const costUsd = asNumber(data.costUsd);
-            // WR-01 (196 review): fall back to the carried (requested-seeded) source when
+            // Fall back to the carried (requested-seeded) source when
             // the terminal record omits it — mirrors the provider/keyless fallback so the
-            // OBS-03 selection rung survives a partial/reordered terminal record (the fold
+            // provider-selection rung survives a partial/reordered terminal record (the fold
             // is the offline oracle for non-live records; the live emitter always passes it).
             const source = asString(data.source) ?? signal?.source;
             return {
@@ -78,7 +78,7 @@ export function accumulateVoiceRecord(prev, type, data, seq) {
                     outcome: "ok",
                     ...(model !== undefined ? { model } : {}),
                     ...(durationMs !== undefined ? { durationMs } : {}),
-                    ...(costUsd !== undefined ? { costUsd } : {}), // keyless 0 lands here (OBS-05)
+                    ...(costUsd !== undefined ? { costUsd } : {}), // keyless 0 lands here
                     ...(source !== undefined ? { source } : {}),
                 },
                 outcomeSeq: seq,
@@ -89,7 +89,7 @@ export function accumulateVoiceRecord(prev, type, data, seq) {
             if (signal !== undefined && seq < prev.outcomeSeq)
                 return prev;
             const errorKind = asString(data.errorKind);
-            // WR-01 (196 review): fall back to the carried (requested-seeded) source when
+            // Fall back to the carried (requested-seeded) source when
             // the terminal record omits it — mirrors provider/keyless (see the completed arm).
             const source = asString(data.source) ?? signal?.source;
             return {

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain.d.ts

@@ -1,27 +1,26 @@
 /**
- * `obs.explain` RPC handler — the IncidentReport assembler (Phase 153
- * centerpiece, D6).
+ * `obs.explain` RPC handler — the IncidentReport assembler.
  *
- * Wires the full pipeline the Wave-1..4 plans built, in five linear steps:
+ * Wires the full pipeline in five linear steps:
  *
  *   1. admin check (defense-in-depth; gateway-router is the primary gate)
  *   2. `stripInternalFields` THEN `ObsExplainContract.request.parse`
  *      (so `_trustLevel` can never be smuggled into the parsed params)
  *   3. resolve — a `traceId` is canonicalized to its `sessionKey` FIRST
  *      ({@link resolveTraceToSession}), so by-trace and by-session share ONE
- *      assembler path (X1 structural identity)
+ *      assembler path (structural identity)
  *   4. read → normalize → assemble → heuristics → bound:
  *        - {@link IncidentSourceReader} reads the four bounded sources
  *        - {@link toIncidentSignals} collapses log + event shapes
- *        - {@link assembleIncidentReport} merges signals + rollup → §6.3 report
- *        - {@link rootCause} stamps the deterministic `likelyRootCause` (X3)
- *        - {@link boundIncidentReport} enforces the depth budget (X2)
+ *        - {@link assembleIncidentReport} merges signals + rollup → the report
+ *        - {@link rootCause} stamps the deterministic `likelyRootCause`
+ *        - {@link boundIncidentReport} enforces the depth budget
  *   5. dev-mode `response.parse` (catches field regressions in dev only)
  *
  * The `incidentReader` dep is an OPTIONAL test seam: production builds
  * {@link makeRealReader} over the real (safePath-guarded) data dir; tests inject
  * a fixture reader. It does NOT enable arbitrary-file reads in production
- * (T-153-17) — the dataDir override convention only, like obs-trace.
+ * — the dataDir override convention only, like obs-trace.
  *
  * @module
  */
@@ -41,17 +40,17 @@ export interface AssembleIncidentReportParams {
     readonly sessionKey?: string;
     readonly traceId?: string;
     /**
-     * FLEET-05: an autonomy run's rootRunId (the 3rd ref). Canonicalized to the
+     * An autonomy run's rootRunId (the 3rd ref). Canonicalized to the
      * run's sessionKey FIRST via {@link resolveRootRunToSession} — the synthetic
      * in-process root by a pure prefix-strip, a real socket/spawned root by the
-     * session-index scan. An unresolvable rootRunId soft-fails to "" → the WR-04
+     * session-index scan. An unresolvable rootRunId soft-fails to "" → the
      * not-found marker (it never masquerades as a clean session). Lets the
      * fleet→explain drill-down paste the worst run's rootRunId straight in.
      */
     readonly rootRunId?: string;
     readonly depth?: "summary" | "full";
     /**
-     * D9 admin opt-in: when `true`, a `traceId` that resolves only through a
+     * Admin opt-in: when `true`, a `traceId` that resolves only through a
      * synthetic (test/harness) session-index row is still canonicalized. Default
      * (absent/`false`) excludes synthetic rows from the by-traceId resolution.
      */
@@ -67,16 +66,15 @@ export interface AssembleIncidentReportParams {
  * This function contains NEITHER an admin check NOR a `request.parse`: it takes
  * ALREADY-VALIDATED params and runs the deterministic pipeline:
  *
- *   3 (X1). canonicalize a `traceId` to its `sessionKey` FIRST, so by-trace and
+ *   3.      canonicalize a `traceId` to its `sessionKey` FIRST, so by-trace and
  *           by-session collapse to one assembler path.
  *   4.      read the four bounded sources → `toIncidentSignals` → assemble the
- *           §6.3 report → stamp `likelyRootCause` (X3, with the WR-04
- *           `session_not_found` not-found marker) → bound to the depth budget
- *           (X2).
+ *           report → stamp `likelyRootCause` (with the
+ *           `session_not_found` not-found marker) → bound to the depth budget.
  *   5.      dev-mode `response.parse` (catches field regressions in dev only).
  *
- * The body is byte-identical to the former inline handler body; moving it here
- * changes NO behavior (the obs-explain.test.ts parity case pins this).
+ * The RPC handler delegates here with no added behavior — the
+ * obs-explain.test.ts parity case pins that both paths yield identical reports.
  *
  * @param reader - the four-source DI reader (production `makeRealReader` over a
  *   safePath-guarded `dataDir`; tests inject a fixture reader). Read-only.