comisai 1.0.44 → 1.0.46

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

@@ -1,13 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * `obs-explain-heuristics` — the deterministic root-cause heuristic registry
- * (Phase 153 centerpiece, X3).
+ * `obs-explain-heuristics` — the deterministic root-cause heuristic registry.
  *
  * An ordered, first-match-wins `ReadonlyArray<(IncidentSignals) => RootCause |
  * null>`. PURE: no LLM, no I/O, no globals — a post-mortem reproduces the same
  * `likelyRootCause` from the same log evidence forever. The registry keys ONLY
  * on the derived booleans/strings `toIncidentSignals` already computed from log
- * evidence (the 678 fixture has ZERO Phase-150 provenance fields, so the
+ * evidence (the 678 fixture has ZERO provenance fields, so the
  * misclassification signal is derived from `success:true` + repeated
  * `"Tool execution failed"` + a status/200/403 token in a failure body — never
  * from `classifiedFailureBy`).
@@ -17,35 +16,35 @@
  *      tripped on the MISCLASSIFIED successes ("DO NOT retry" is present too),
  *      so the misclassification must out-rank the breaker: it is upstream, the
  *      breaker is the downstream symptom.
- *   2. spend_exceeded (LIVE v2.28 260621) — the dollars kill-switch is an
+ *   2. spend_exceeded — the dollars kill-switch is an
  *      ADMINISTRATIVE pre-emption that aborts at admission, causally INDEPENDENT
  *      of tool failures (tool FAILURES return ~0 bytes / ~$0 and cannot drive
  *      cumulative spend). A live VPS incident showed a spend-killed session
  *      root-causing to the chronic breaker below — masking the acute kill that
  *      now blocks every new turn. So it sits ABOVE the breaker/degradation
- *      heuristics but BELOW #1 (the X3-frozen misclassification). Keyed on
+ *      heuristics but BELOW #1 (the frozen misclassification). Keyed on
  *      endReason "spend_exceeded" (frozen fixtures carry it not).
  *   3. breaker_opened_repeated_failure — the 503 root cause: a real transport
  *      failure (HTTP 503 → "overloaded") repeated until the per-tool breaker
  *      opened. The 503 has NO misclassification signal, so it falls through to
  *      here.
- *   3. tool_schema_unsupported (GBNF-02, Phase 175) — an acute, deterministic
+ *   3. tool_schema_unsupported — an acute, deterministic
  *      provider-schema rejection: upstream of any terminal state (out-ranks
- *      context_exhausted/output_starved) but downstream of the two X3-mandated
- *      codes, whose frozen fixtures carry no schema-rejection records (cannot
+ *      context_exhausted/output_starved) but downstream of the two frozen-fixture
+ *      codes, whose fixtures carry no schema-rejection records (cannot
  *      regress them). Fires only when the one-shot strip-retry did NOT
  *      recover — a recovered repair is evidence, not a verdict.
  *   4. context_bloat / exec_dependency / provider_timeout — three low-risk
- *      "insurance" codes that broaden 156/G1 corpus coverage. They never fire on
- *      the two X3 fixtures (the two above match first), so they cannot regress
- *      the phase-done gate.
- *   5. context_exhausted / output_starved (QT2/QT3 — the Glass Box degradation
- *      detectors) — the two NAMED terminal-state causes. They key on the
+ *      "insurance" codes that broaden corpus coverage. They never fire on
+ *      the two frozen fixtures (the two above match first), so they cannot
+ *      regress them.
+ *   5. context_exhausted / output_starved — the two NAMED terminal-state
+ *      degradation causes. They key on the
  *      metadata-derived `endReason` (threaded onto the signals by the handler),
  *      NOT a tool failure, so they sit LAST: a tool-failure cause is upstream of
  *      the terminal state and out-ranks them. They fire only when the run's
  *      mapped endReason IS the cause, and never on a clean session.
- *   6. prompt_timeout (LAT-04, Phase 177) / spend_exceeded (WR-4, 177-obs-loop) —
+ *   6. prompt_timeout / spend_exceeded —
  *      the NAMED terminal latency + SPEND causes, keyed on endReason "timeout" /
  *      "spend_exceeded". Same terminal band as #5 (the endReason keys are mutually
  *      exclusive); every tool-failure cause out-ranks them. prompt_timeout is
@@ -53,23 +52,25 @@
  *      in the sibling obs-explain-spend-verdict.ts. The frozen 678/503 fixtures
  *      carry neither endReason — cannot regress them.
  *
- * The two X3-mandated codes are #1 and #2; phase-done gates ONLY on X1/X2/X3.
+ * The frozen 678/503 fixtures pin codes #1 and #2; every later rule must leave
+ * their verdicts unchanged.
  *
  * @module
  */
 import { BREAKER_N, CONTEXT_BLOAT_MIN_OFFLOADS, TOKEN_SPIKE_CHARS, MODULE_NOT_FOUND_MARKERS, breakerTool, hasModuleNotFound, } from "./obs-explain-heuristics-helpers.js";
-// OBS-02 (Phase 201): the two BENIGN learning verdicts (sibling — subdir cap).
-// userModelRevisedVerdict was deleted in Phase 226 (its 0-emit signal was removed).
+// The two BENIGN learning verdicts (sibling — subdir cap).
 import { learnedSkillFailingVerdict, synthesisAbstainedVerdict } from "./obs-explain-learning-verdicts.js";
-import { spendExceededVerdict } from "./obs-explain-spend-verdict.js"; // WR-4: NAMED spend verdict (sibling — subdir cap)
-import { recallMissVerdict } from "./obs-explain-recall-verdict.js"; // RECALL-01 (sibling — subdir cap)
+import { spendExceededVerdict } from "./obs-explain-spend-verdict.js"; // NAMED spend verdict (sibling — subdir cap)
+import { recallMissVerdict } from "./obs-explain-recall-verdict.js"; // recall_miss verdict (sibling — subdir cap)
 import { terminalDriveNoTaskVerdict } from "./obs-explain-terminal-drive-verdict.js"; // unattended abandoned-drive (sibling — subdir cap)
+import { terminalDriveEvictedVerdict } from "./obs-explain-terminal-drive-evicted-verdict.js"; // reaper-killed drive (sibling — subdir cap)
+import { orchestrateFailedVerdict } from "./obs-explain-orchestrate-verdict.js"; // failed orchestrate run (sibling — subdir cap)
 // ---------------------------------------------------------------------------
 // The ordered registry (first non-null wins).
 // ---------------------------------------------------------------------------
 /**
  * The ordered root-cause registry. First predicate to return a non-null
- * `RootCause` wins. Order is the X3 contract — see the module doc.
+ * `RootCause` wins. Order is a load-bearing contract — see the module doc.
  */
 export const HEURISTICS = [
     // 1) content_heuristic_misclassification (678 — ROOT over the breaker symptom).
@@ -93,7 +94,7 @@ export const HEURISTICS = [
             ],
         };
     },
-    // 2) spend_exceeded (LIVE v2.28 260621 — the dollars kill-switch is an
+    // 2) spend_exceeded (the dollars kill-switch is an
     //    ADMINISTRATIVE pre-emption at admission, NOT a downstream symptom of tool
     //    failures. Tool FAILURES return ~0 bytes / ~$0 and cannot drive cumulative
     //    spend, so the ceiling is causally INDEPENDENT of them. A live VPS incident
@@ -101,7 +102,7 @@ export const HEURISTICS = [
     //    ceiling, but the verdict reported breaker_opened_repeated_failure — chronic
     //    noise masking the acute kill that now blocks EVERY new turn. So it
     //    out-ranks the breaker/dependency/timeout/degradation heuristics below, but
-    //    stays BELOW #1, the X3-frozen misclassification verdict. Keyed strictly on
+    //    stays BELOW #1, the frozen misclassification verdict. Keyed strictly on
     //    endReason "spend_exceeded" (frozen 678/503 fixtures carry it not).
     spendExceededVerdict,
     // 3) breaker_opened_repeated_failure (503 — real transport failure cascade).
@@ -128,17 +129,17 @@ export const HEURISTICS = [
             ],
         };
     },
-    // 3) tool_schema_unsupported (GBNF-02 — acute provider-schema rejection at
+    // 3) tool_schema_unsupported (acute provider-schema rejection at
     //    grammar-compile/unmarshal time). Fires ONLY on an UNRECOVERED one-shot
-    //    strip-retry: a recovered repair is evidence, not a verdict (T-175-19).
+    //    strip-retry: a recovered repair is evidence, not a verdict.
     //    Detail is assembled solely from Comis-registry tool names + the closed
-    //    keyword names — the signal carries no body fields by construction
-    //    (T-175-17). The WR-05 reason discriminator branches the wording: the
-    //    gate-closed terminal previously emitted the same payload as
+    //    keyword names — the signal carries no body fields by construction.
+    //    The reason discriminator branches the wording: the
+    //    gate-closed terminal would otherwise emit the same payload as
     //    nothing-to-strip, so a session that healed once and then hit the gate
-    //    produced a verdict claiming "nothing strippable" when stripping WAS
+    //    would produce a verdict claiming "nothing strippable" when stripping WAS
     //    performed earlier — the exact wrong-way pointer the troubleshooting
-    //    doctrine forbids. Absent reason (pre-WR-05 records) falls back to the
+    //    doctrine forbids. An absent reason falls back to the
     //    retried-based wording.
     (s) => {
         if (!s.toolSchemaUnsupported || s.toolSchemaUnsupported.succeeded)
@@ -220,21 +221,21 @@ export const HEURISTICS = [
             ],
         };
     },
-    // 7) context_exhausted (QT2 — the NAMED terminal degradation cause). Keyed on
+    // 7) context_exhausted (the NAMED terminal degradation cause). Keyed on
     //    the metadata-derived endReason, NOT a tool failure — so it sits BELOW the
     //    tool-failure rules above (a misclassification/breaker/dependency/timeout
     //    cause is upstream of, and out-ranks, the terminal state). Fires only when
     //    the run's mapped endReason IS the context-exhaustion cause.
     //
-    //    W3 (obs-llm-troubleshooting): when the trajectory carries the per-call
-    //    budget equation (`signals.contextBudget`, from the W2 context.budget
+    //    When the trajectory carries the per-call
+    //    budget equation (`signals.contextBudget`, from the context.budget
     //    event), the verdict is NUMBERS-BACKED — assembled vs window, the exact
     //    contextEngine.budget.* knob that clamped the window, the system+tools
-    //    share, and the kept-history count. The old static text speculated about
-    //    the summarizer/compaction and pointed at summarizerSpend, which actively
-    //    misdirected the live qwen3.6 incident (the real cause was the small-class
+    //    share, and the kept-history count. A generic static text that speculated
+    //    about the summarizer/compaction and pointed at summarizerSpend actively
+    //    misdirected a live qwen3.6 incident (the real cause was the small-class
     //    32K cap + 83 tool schemas at 80% of the window). The generic text remains
-    //    ONLY as the fallback for pre-W2 sessions with no budget evidence.
+    //    ONLY as the fallback for sessions with no budget evidence.
     (s) => {
         if (s.endReason !== "context_exhausted")
             return null;
@@ -242,17 +243,17 @@ export const HEURISTICS = [
         if (b !== undefined) {
             const capped = b.windowCapSource !== "none";
             const systemSharePct = b.windowTokens > 0 ? Math.round((b.systemTokens / b.windowTokens) * 100) : 0;
-            // KNOB-02 (Phase 176): "served" is NOT a contextEngine.budget.* knob —
+            // "served" is NOT a contextEngine.budget.* knob —
             // templating it would render a nonsense config key (the union member name
             // suffixed onto the knob prefix) and misdirect the operator. The served
             // branch names the failure class (Ollama served a smaller window than
             // configured); the real knobs are in the suggested step below.
-            // WR-01: "capabilityClass" is ALSO not a budget knob — the executor-side
+            // "capabilityClass" is ALSO not a budget knob — the executor-side
             // DEFAULT_EFFECTIVE_CAP_BY_CLASS cap reads only the operator's
             // providers.entries.<id>.capabilities.capabilityClass pin, so the verdict
             // must name the PIN ("raise contextEngine.budget.effectiveContextCapSmall"
-            // changes nothing on that branch — the dead-knob misdirection this phase
-            // exists to kill). The genuine budget-knob branch stays byte-identical.
+            // changes nothing on that branch — the dead-knob misdirection this branch
+            // exists to prevent). The genuine budget-knob branch stays byte-identical.
             const capClause = capped
                 ? (b.windowCapSource === "served"
                     ? ` (model contextWindow ${String(b.rawContextWindowTokens)} but Ollama served a smaller window)`
@@ -294,7 +295,7 @@ export const HEURISTICS = [
             ],
         };
     },
-    // 8) output_starved (QT3 — the NAMED terminal output-truncation cause). Same
+    // 8) output_starved (the NAMED terminal output-truncation cause). Same
     //    lowest-priority placement as context_exhausted: it explains the terminal
     //    state, so any tool-failure cause out-ranks it. Fires only when the mapped
     //    endReason IS the output-starvation cause (a terminal output-cap truncation
@@ -312,15 +313,16 @@ export const HEURISTICS = [
             ],
         };
     },
-    // 9) prompt_timeout (LAT-04, Phase 177 — the NAMED terminal latency cause).
+    // 9) prompt_timeout (the NAMED terminal latency cause).
     //    Keyed on the metadata-derived endReason (END_REASON_MAP prompt_timeout →
-    //    "timeout", 177-04), NOT a tool failure — sits BELOW the tool-failure
-    //    rules: a session that died on a prompt timeout with CLEAN tools used to
-    //    fall through to NO verdict (rule 6 provider_timeout requires a tool
-    //    failure — research Critical Finding 7 point 6). Numbers-backed from the
+    //    "timeout"), NOT a tool failure — sits BELOW the tool-failure
+    //    rules: a session that died on a prompt timeout with CLEAN tools would
+    //    otherwise fall through to NO verdict (rule 6 provider_timeout requires a
+    //    tool failure). Numbers-backed from the
     //    enriched execution.prompt_timeout signal when present; bindingKnob is
     //    the PRE-RENDERED config-key string from the agent-side source→knob
-    //    table (never re-templated here — the KNOB-02 discipline; the only local
+    //    table (never re-templated here — templating a non-key source name would
+    //    render a nonsense knob; the only local
     //    templating is the agents.<id>.promptTimeout.* fallback, a REAL key
     //    family). Cannot regress the frozen 678/503 fixtures (no prompt_timeout
     //    records, no endReason "timeout" in them).
@@ -345,11 +347,11 @@ export const HEURISTICS = [
             if (t.limit === undefined) {
                 // Whole-turn retry kill (`limit` ABSENT): rotation/fallback/short-
                 // retry prompts race the NON-resettable retryPromptTimeoutMs — never
-                // framed as a stall kill, and the lever is the RETRY knob (177-REVIEW
-                // WR-01; the same branch the agent-side classify hint takes). The
+                // framed as a stall kill, and the lever is the RETRY knob (the same
+                // branch the agent-side classify hint takes). The
                 // retry knob is a REAL agents.* key family, so local templating is
-                // sanctioned (the KNOB-02 fallback discipline) — deliberately NOT
-                // t.bindingKnob: pre-WR-01 rows on disk carry the wrong
+                // sanctioned — deliberately NOT
+                // t.bindingKnob: rows on disk can carry the wrong
                 // promptTimeoutMs knob for exactly this class.
                 return {
                     code: "prompt_timeout",
@@ -374,8 +376,8 @@ export const HEURISTICS = [
                 ],
             };
         }
-        // Pre-extension session (endReason "timeout" but no enriched record on the
-        // trajectory): still name the cause, suggest the knob FAMILY, invent no numbers.
+        // No enriched record on the trajectory (endReason "timeout" only): still
+        // name the cause, suggest the knob FAMILY, invent no numbers.
         return {
             code: "prompt_timeout",
             detail: "prompt timed out (no enriched timeout record — pre-extension session)",
@@ -385,7 +387,7 @@ export const HEURISTICS = [
             ],
         };
     },
-    // 9c) recall_miss (RECALL-01). A DEGRADED session whose memory recalls ALL
+    // 9c) recall_miss. A DEGRADED session whose memory recalls ALL
     //     returned zero injected memories AND that matched no tool/context/breaker
     //     cause above — the agent ran with no memory context. Low-noise by
     //     construction: requires EVERY recall to have missed (zeroHits === recalls),
@@ -400,13 +402,30 @@ export const HEURISTICS = [
     //     incidental — the no-task diagnosis is the root. Keys only on toolStats, so it
     //     never fires on a non-terminal session (no 678/503 regression). Sibling file.
     terminalDriveNoTaskVerdict,
+    // 9e) terminal_drive_evicted — a durable drive was reaped by the idle-TTL or
+    //     wall-clock cap, cutting a (possibly still-working) autonomous drive short. AFTER
+    //     9d: a drive opened-but-never-tasked THEN idle-reaped is rooted in the no-task
+    //     stall (the eviction is its consequence); ABOVE the catch-all: a reaper kill is a
+    //     specific terminal-lifecycle cause. Fires ONLY on idle/wall_clock (not the
+    //     incidental max_sessions LRU or the deliberate max_interactions budget — no wolf).
+    //     Keys only on terminalDriveEvicted (absent on 678/503), so no regression. Sibling.
+    terminalDriveEvictedVerdict,
+    // 9f) orchestrate_failed — an orchestrate run (a jailed child script driving tools
+    //     through the capability socket) exited non-zero, or a tool.invoke inside the
+    //     jail was denied by the run's attenuated lease. ABOVE the
+    //     completed_with_tool_errors catch-all: a failed run is a specific terminal
+    //     cause, more root than "some tools errored" (a stray failure during the run is
+    //     incidental). Keys only on s.orchestrate (absent on the frozen 678/503
+    //     fixtures — they carry no orchestrate records), so it cannot regress them.
+    //     Sibling file.
+    orchestrateFailedVerdict,
     // 10) completed_with_tool_errors (the CATCH-ALL ACUTE cause — last of the acute
     //     tier, above the BENIGN learning verdicts #11-13 below). A
     //     degraded session whose tool failures matched none of the named rules
     //     above (not misclassification, breaker, schema-strip, context-bloat,
     //     module-not-found, or timeout) used to fall through to a NULL verdict —
     //     comis explain captured the per-tool {ok,failed} but root-caused nothing
-    //     (live C13 finding, 2026-06-12: memory_get + image_analyze both failed
+    //     (a live finding: memory_get + image_analyze both failed
     //     with errorKind=dependency on bad input). Keys on ACTUAL failures, never
     //     the endReason label alone, so a `completed_with_tool_errors` end state
     //     with no failure records (a degenerate/contradictory signal) still names
@@ -429,10 +448,9 @@ export const HEURISTICS = [
     },
     // 11/12) the BENIGN learning verdicts (sibling): after the acute tier, before #13
     // (specific-over-generic, yet Defer ≠ Retry — never masks an acute error).
-    // (userModelRevisedVerdict was deleted in Phase 226 with its 0-emit signal.)
     learnedSkillFailingVerdict,
     synthesisAbstainedVerdict,
-    // 13) outcome_unresolved (OBS-02, Phase 198 — LOWEST-priority, BENIGN, the
+    // 13) outcome_unresolved (LOWEST-priority, BENIGN, the
     //     generic learning catch-all). A finished trajectory the learning shadow saw
     //     but where NO signal tier resolved an outcome AND neither skill verdict
     //     fired. Defer ≠ Retry: dead-last (every acute cause + the two skill verdicts

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

@@ -1,5 +1,5 @@
 /**
- * OBS-02 (Phase 201, P2 skills shadow): the two BENIGN procedural-learning
+ * The two BENIGN procedural-learning
  * verdict predicates spliced into the `obs-explain-heuristics` registry —
  * `learned_skill_failing` + `synthesis_abstained_low_capability`.
  *

package/node_modules/@comis/daemon/dist/api/obs-handlers/obs-explain-learning-verdicts.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * OBS-02 (Phase 201, P2 skills shadow): the two BENIGN procedural-learning
+ * The two BENIGN procedural-learning
  * verdict predicates spliced into the `obs-explain-heuristics` registry —
  * `learned_skill_failing` + `synthesis_abstained_low_capability`.
  *
@@ -34,7 +34,7 @@ export const learnedSkillFailingVerdict = (s) => {
         detail: `a learned procedure was used in failed/corrected trajectories ` +
             `(${s.learning.skillFailures.length} skill(s): ${s.learning.skillFailures.join(", ")})`,
         suggestedNextSteps: [
-            "inspect via comis memory skills; the procedure will demote on continued failure (Phase 202)",
+            "inspect via comis memory skills; the procedure will demote on continued failure",
             "obs.explain depth=full",
         ],
     };
@@ -60,7 +60,3 @@ export const synthesisAbstainedVerdict = (s) => {
         ],
     };
 };
-// Phase 226 SIMPLIFY-04: userModelRevisedVerdict was DELETED — the user-rep-revision
-// signal it keyed on was removed with its 0-emit event (the user-rep revision path
-// folded into the reflection engine in Phase 225). Its registration in
-// obs-explain-heuristics.ts was removed in the same lockstep.

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

@@ -0,0 +1,45 @@
+/**
+ * `orchestrate_failed` — the failed-run root-cause verdict spliced into the
+ * `obs-explain-heuristics` registry.
+ *
+ * A sibling file (the `obs-explain-terminal-drive-verdict.ts` discipline) so
+ * `obs-explain-heuristics.ts` stays 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 `orchestrate` PTC run (a jailed
+ * child script driving tools through the capability socket) exited non-zero, OR a
+ * `tool.invoke` inside the jail was DENIED for exceeding the run's attenuated
+ * capability lease — while the surrounding turn returned fine, so `comis explain`
+ * reported a clean `endReason` and root-caused NOTHING. This verdict turns a
+ * failed run into a one-call diagnosis.
+ *
+ * Keyed PURELY on the folded, content-free `s.orchestrate` section (one entry per
+ * run): fires when ANY run has `outcome:"failure"` (a non-zero exit) OR a
+ * `toolCalls` entry with `decision:"deny"`. Returns null when the section is
+ * absent/empty or every run succeeded with no denial. Because the section is
+ * ABSENT on any non-orchestrate session (and on the frozen 678/503 fixtures,
+ * which carry no orchestrate records), the verdict cannot regress them — it is
+ * registered in the acute tier, BELOW the two frozen codes and ABOVE the
+ * `completed_with_tool_errors` catch-all (a failed run is a specific cause, more
+ * root than "some tools errored"). The return type is structurally identical to
+ * the registry's `RootCause` (no cross-module type import ⇒ no cycle).
+ *
+ * Content-free (INV-5): the detail names only ids + closed enums + counts (run
+ * count, `failureClass`, `exitCode`, capability id) — never the script, the
+ * stderr tail, tool args, or a secret.
+ *
+ * @module
+ */
+import type { IncidentSignals } from "@comis/core";
+/** Structural twin of `obs-explain-heuristics.RootCause` (kept local — no import cycle). */
+type OrchestrateVerdict = {
+    code: string;
+    detail: string;
+    suggestedNextSteps: string[];
+};
+/**
+ * `orchestrate_failed` — fires when an `orchestrate` run exited non-zero or
+ * carried an in-jail capability denial.
+ */
+export declare const orchestrateFailedVerdict: (s: IncidentSignals) => OrchestrateVerdict | null;
+export {};

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

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `orchestrate_failed` — the failed-run root-cause verdict spliced into the
+ * `obs-explain-heuristics` registry.
+ *
+ * A sibling file (the `obs-explain-terminal-drive-verdict.ts` discipline) so
+ * `obs-explain-heuristics.ts` stays 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 `orchestrate` PTC run (a jailed
+ * child script driving tools through the capability socket) exited non-zero, OR a
+ * `tool.invoke` inside the jail was DENIED for exceeding the run's attenuated
+ * capability lease — while the surrounding turn returned fine, so `comis explain`
+ * reported a clean `endReason` and root-caused NOTHING. This verdict turns a
+ * failed run into a one-call diagnosis.
+ *
+ * Keyed PURELY on the folded, content-free `s.orchestrate` section (one entry per
+ * run): fires when ANY run has `outcome:"failure"` (a non-zero exit) OR a
+ * `toolCalls` entry with `decision:"deny"`. Returns null when the section is
+ * absent/empty or every run succeeded with no denial. Because the section is
+ * ABSENT on any non-orchestrate session (and on the frozen 678/503 fixtures,
+ * which carry no orchestrate records), the verdict cannot regress them — it is
+ * registered in the acute tier, BELOW the two frozen codes and ABOVE the
+ * `completed_with_tool_errors` catch-all (a failed run is a specific cause, more
+ * root than "some tools errored"). The return type is structurally identical to
+ * the registry's `RootCause` (no cross-module type import ⇒ no cycle).
+ *
+ * Content-free (INV-5): the detail names only ids + closed enums + counts (run
+ * count, `failureClass`, `exitCode`, capability id) — never the script, the
+ * stderr tail, tool args, or a secret.
+ *
+ * @module
+ */
+/**
+ * `orchestrate_failed` — fires when an `orchestrate` run exited non-zero or
+ * carried an in-jail capability denial.
+ */
+export const orchestrateFailedVerdict = (s) => {
+    const runs = s.orchestrate;
+    // No orchestrate section (any non-orchestrate session, incl. the frozen
+    // 678/503 fixtures) → not this cause.
+    if (runs === undefined || runs.length === 0)
+        return null;
+    // A run FAILED if it exited non-zero OR a jailed tool.invoke was denied by its
+    // attenuated lease (a denial is a failure signal even on an exit-0 run).
+    const failedRuns = runs.filter((r) => r.outcome === "failure" || r.toolCalls.some((t) => t.decision === "deny"));
+    if (failedRuns.length === 0)
+        return null; // every run succeeded with no denial → clean.
+    // Exit-failed runs: name the closed failureClass + numeric exitCode (content-free).
+    const exitFailed = failedRuns.filter((r) => r.outcome === "failure");
+    const failureClasses = [
+        ...new Set(exitFailed
+            .map((r) => r.failureClass)
+            .filter((c) => c !== undefined)),
+    ];
+    const exitCodes = [...new Set(exitFailed.map((r) => r.exitCode))];
+    // Denied capability ids across the failed runs (ids — content-free, never a body).
+    const deniedCaps = [
+        ...new Set(failedRuns.flatMap((r) => r.toolCalls.filter((t) => t.decision === "deny").map((t) => t.capability))),
+    ];
+    const clauses = [];
+    if (exitFailed.length > 0) {
+        const fcClause = failureClasses.length > 0 ? `failureClass: ${failureClasses.join(", ")}; ` : "";
+        clauses.push(`${exitFailed.length} exited non-zero (${fcClause}exitCode: ${exitCodes.join(", ")})`);
+    }
+    if (deniedCaps.length > 0) {
+        clauses.push(`in-jail capability denial(s) (capability: ${deniedCaps.join(", ")})`);
+    }
+    return {
+        code: "orchestrate_failed",
+        detail: `${failedRuns.length} of ${runs.length} orchestrate run(s) failed — ${clauses.join("; ")}. ` +
+            "A run exits non-zero on a script/jail/resource failure, or records a deny when a tool.invoke " +
+            "exceeded the run's attenuated capability lease.",
+        suggestedNextSteps: [
+            "obs.explain depth=full for the failed run's per-run failureClass, exitCode, and tool-call/denial sequence",
+            deniedCaps.length > 0
+                ? "for a denial: widen the agent's autonomy-profile capability grant (orch:*) or narrow the script to the capabilities the run holds"
+                : "for a non-zero exit: inspect the script's failure class (timeout / stdout_cap / spawn_fail / lease_absent) against the jail and resource limits",
+        ],
+    };
+};

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

@@ -3,7 +3,7 @@
  *
  * `obs.explain` assembles an IncidentReport from four telemetry sources. They
  * sit behind ONE interface so production reads real files while tests inject
- * fixture records (the X3 fixture-injection seam):
+ * fixture records (the fixture-injection seam):
  *
  *   1. readSessionRecords    — the per-session trajectory JSONL. The session
  *      lives in the REAL production layout the pi-agent session manager writes:
@@ -15,7 +15,7 @@
  *      same resolution `bundle-exporter.ts:readRuntimeTrajectory` performs).
  *      Returns ALL parsed lines — log shape AND event shape — WITHOUT the
  *      production bundle reader's `traceSchema === "comis-trajectory"` envelope
- *      filter, so the frozen pre-150 log fixtures pass through to
+ *      filter, so the frozen log-shape fixtures pass through to
  *      `toIncidentSignals`.
  *   2. readCacheTraceRecords — `<dataDir>/logs/cache-trace.jsonl`, filtered to
  *      the resolved session.
@@ -26,7 +26,7 @@
  *      then a SESSION-SCOPED filter by `row.sessionKey` (the F2 fallback).
  *      `DiagnosticQueryParams` has NO sessionKey filter, so `{limit:1}` would
  *      return the most-recent row across ALL sessions — the reader queries a
- *      window and filters AFTER. The window is a recency horizon (WR-01): see
+ *      window and filters AFTER. The window is a recency horizon: see
  *      `DIAGNOSTICS_QUERY_LIMIT` for why 1000 and the residual bound.
  *
  * Why the workspace base (not `<dataDir>/sessions`): the writer's source of
@@ -52,8 +52,8 @@ export interface IncidentSourceReader {
     readSessionMetadata(sessionKey: string): Promise<Record<string, unknown> | null>;
     readDiagnosticsRollup(sessionKey: string): Promise<Record<string, unknown> | null>;
     /**
-     * AUDIT-05 (176-05): the `obs_audit_events` rows for this session's tenant
-     * (the audit persists via SQLite, NOT a trajectory record — Plan 03 — so the
+     * The `obs_audit_events` rows for this session's tenant
+     * (the audit persists via SQLite, NOT a trajectory record — so the
      * `audit?` IncidentReport section is sourced HERE, not from the trajectory
      * stream). Tenant-scoped via `AuditQueryParams.tenant` + a bounded window; the
      * caller (`assembleIncidentReportFromSources`) filters by the resolved
@@ -63,10 +63,35 @@ export interface IncidentSourceReader {
      * OPTIONAL: the production `makeRealReader` always implements it; a fixture
      * reader that omits it simply produces no `audit?` section (the section is
      * additive + presence-conditional — the same posture as a session with no
-     * audit events). Pre-176-05 fixture readers therefore need no change.
+     * audit events). Existing audit-less fixture readers therefore need no change.
      */
     readAuditEvents?(sessionKey: string): Promise<Array<Record<string, unknown>>>;
 }
+/**
+ * Public sessionKey → real session `.jsonl` resolver — the authoritative
+ * pointer-discipline mapping, shared by the daemon `/export-trajectory` closure
+ * and the CLI support-bundle seam.
+ *
+ * Mirrors `makeRealReader`'s workspace base
+ * (`<dataDir>/workspace/sessions`, NOT a flat `<dataDir>/sessions`) and
+ * delegates to the private `resolveSessionFile` (fast path via
+ * `sessionKeyToPath`, then the on-disk pointer-`sessionId` fallback for
+ * lossy keys). Every path component runs through `safePath`, so a
+ * traversal-bearing key cannot escape the sessions base.
+ *
+ * The private resolver soft-fails to the fast path even on a miss (so
+ * `makeRealReader` can read an empty `[]`); this wrapper converts that into an
+ * HONEST `undefined` — it returns a path ONLY when the session artifacts (the
+ * `.jsonl`, its pointer, or its `_session-metadata.json`) exist on disk. A
+ * caller (the export closure) can then warn instead of stat-failing on a
+ * fabricated path.
+ *
+ * @param dataDir - the `~/.comis` root (empty → the default `~/.comis`).
+ * @param sessionKey - a formatted SessionKey (`tenant:user:channel[:peer:...]`).
+ * @returns the absolute session `.jsonl` path, or `undefined` on a genuine miss
+ *   (no artifacts) or an unparseable key.
+ */
+export declare function resolveSessionFilePath(dataDir: string, sessionKey: string): string | undefined;
 /**
  * Build the production reader. `dataDir` is the file-system root (defaults to
  * `~/.comis`); `obsStore` (optional) backs the diagnostics-rollup fallback.