comisai 1.0.44 → 1.0.46

package/node_modules/@comis/core/dist/api-contracts/incident-report.js

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The `obs.explain` contract: the §6.3 `IncidentReport` wire schema + shape
- * types + the `ObsExplainContract` itself (Phase 153 centerpiece). Extracted
- * from `observability.ts` to keep that module under the file-size cap.
+ * The `obs.explain` contract: the `IncidentReport` wire schema + shape
+ * types + the `ObsExplainContract` itself. Extracted from `observability.ts`
+ * to keep that module under the file-size cap.
  *
  * Barrel-only: external consumers import these from `"@comis/core"`. The
  * `observability.ts` barrel re-exports them (and the `OBSERVABILITY_CONTRACTS`
@@ -16,21 +16,21 @@
 import { z } from "zod";
 import { defineContract } from "./types.js";
 // The section sub-schemas live in a sibling module (file-size cap). Imported
-// locally for use in IncidentReportSchema/IncidentSignals AND re-exported below
-// so the public barrel surface is unchanged.
-import { IncidentContextBudgetSchema, IncidentContextBudgetHistoryEntrySchema, IncidentPromptTimeoutSchema, SpawnTreeNodeSchema, } from "./incident-report-sections.js";
+// locally for use in IncidentReportSchema AND re-exported below so the public
+// barrel surface is unchanged.
+import { IncidentContextBudgetSchema, IncidentContextBudgetHistoryEntrySchema, IncidentCronWakeGateSchema, IncidentPromptTimeoutSchema, SpawnTreeNodeSchema, OrchestrateRunSchema, } from "./incident-report-sections.js";
 /**
- * The §6.3 `IncidentReport` wire shape (the `obs.explain` response).
+ * The `IncidentReport` wire shape (the `obs.explain` response).
  *
  * A self-contained, redaction-safe post-mortem for a single agent session:
  * outcome, cost, timing, per-tool stats, normalized failures (newest-first),
  * the circuit-breaker timeline, large-result offloads, a one-paragraph
- * summary, a deterministic `likelyRootCause` (heuristic registry, Plan 05),
- * report-level next steps, and an honest `truncations[]` ledger (Plan 04
+ * summary, a deterministic `likelyRootCause` (heuristic registry),
+ * report-level next steps, and an honest `truncations[]` ledger (the
  * bounding pass records what it dropped).
  *
  * Field bounding (≤200-char `errorPreview`, digest-only `resultDigest`, the
- * 6 KB summary budget) is ENFORCED by the Plan-04 bounding pass — this schema
+ * 6 KB summary budget) is ENFORCED by the bounding pass — this schema
  * only declares the shape. `suggestedNextSteps` appears BOTH inside
  * `likelyRootCause` (matching the heuristic `RootCause` 1:1) and at the report
  * root (report-level guidance); both are required-or-default.
@@ -38,7 +38,7 @@ import { IncidentContextBudgetSchema, IncidentContextBudgetHistoryEntrySchema, I
 // Re-export the section sub-schemas + types (imported above) so the public
 // barrel (observability.ts → @comis/core) and all consumers are unchanged after
 // the file-size split.
-export { IncidentContextBudgetSchema, IncidentPromptTimeoutSchema, SpawnTreeNodeSchema, };
+export { IncidentContextBudgetSchema, IncidentCronWakeGateSchema, IncidentPromptTimeoutSchema, SpawnTreeNodeSchema, OrchestrateRunSchema, };
 export const IncidentReportSchema = z.object({
     schemaVersion: z.literal(1),
     sessionKey: z.string(),
@@ -72,9 +72,9 @@ export const IncidentReportSchema = z.object({
         httpStatus: z.number().optional(),
         errorKind: z.string(),
         matchedToken: z.string().optional(),
-        /** #4: the failure-detector sub-rule that flipped the call — "self_grade" (a
-         *  clean DOMAIN task-failure via the #1 {graded:true,outcome} envelope) vs an
-         *  error-token rule. Distinguishes an honest task-failure from a transport error. */
+        /** The failure-detector sub-rule that flipped the call — "self_grade" (a
+         *  clean DOMAIN task-failure via the {graded:true,outcome} self-grade envelope)
+         *  vs an error-token rule. Distinguishes an honest task-failure from a transport error. */
         matchedRule: z.string().optional(),
         resultDigest: z.string(),
         // The size of the ORIGINAL, pre-bound tool body (a "how big was the thing
@@ -96,13 +96,13 @@ export const IncidentReportSchema = z.object({
         originalChars: z.number(),
         pointer: z.string(),
     })),
-    /** ORCH-OBS (orchestration-observability): per-node token-budget breaches
-     *  (BUDGET-03) reconstructed from the session's `subagent.budget_exceeded`
-     *  trajectory records. `capSource` names WHICH knob bound each node (node /
-     *  operator-default / inherit-share) so a breach is diagnosable from the report
-     *  alone — not just "a node failed". Counts/ids/closed-enum ONLY (§2.7); never a
-     *  task or output. Optional + additive (present only when the trajectory carries
-     *  breach records; schemaVersion stays 1). */
+    /** Per-node token-budget breaches reconstructed from the session's
+     *  `subagent.budget_exceeded` trajectory records. `capSource` names WHICH knob
+     *  bound each node (node / operator-default / inherit-share) so a breach is
+     *  diagnosable from the report alone — not just "a node failed".
+     *  Counts/ids/closed-enum ONLY; never a task or output. Optional + additive
+     *  (present only when the trajectory carries breach records; schemaVersion
+     *  stays 1). */
     nodeBudgetBreaches: z
         .array(z.object({
         seq: z.number(),
@@ -112,27 +112,41 @@ export const IncidentReportSchema = z.object({
         tokensUsed: z.number(),
     }))
         .optional(),
-    /** TREE-01/02 (215): the root→children SPAWN TREE reconstructed from the
+    /** The root→children SPAWN TREE reconstructed from the
      *  session's `capability.audited` records — the unattended-run authorization
      *  topology ("one call to root-cause an unattended run"). Node shape +
      *  rationale: {@link SpawnTreeNodeSchema}. Optional + additive (present only
      *  when the trajectory carried `capability.audited` records; schemaVersion stays
      *  1 — the `nodeBudgetBreaches` presence-conditional precedent). */
     spawnTree: SpawnTreeNodeSchema.array().optional(),
-    /** W3: the terminal per-call budget equation (optional — present only when the
+    /** The per-run `orchestrate` PTC section reconstructed from the
+     *  session's `orchestrate.run_summary` records — one entry per run (a session may
+     *  hold several). Each carries its `failureClass`, the per-run `toolCalls`/denials
+     *  attributed by the child leaseId (a `decision:"deny"` groups under THAT run), and
+     *  the labeled `savings` estimate. Run shape + rationale: {@link OrchestrateRunSchema}.
+     *  Optional + additive (present only when the trajectory carried run_summary records;
+     *  schemaVersion stays 1 — the `spawnTree` presence-conditional precedent). */
+    orchestrate: OrchestrateRunSchema.array().optional(),
+    /** The terminal per-call budget equation (optional — present only when the
      *  session's trajectory carries `context.budget` records; additive, schemaVersion
      *  stays 1). */
     contextBudget: IncidentContextBudgetSchema.optional(),
-    /** E2 (obs-sweep): the per-turn context-budget CASCADE — the progression of budget checks toward
+    /** The woke-fire wake-gate fact (optional — present ONLY when the session's
+     *  trajectory carries a `scheduler.wake_gate` record, i.e. a gate that woke the
+     *  model). A skipped fire opens no session, so it never reaches here. Content-free;
+     *  additive, schemaVersion stays 1. MUST stay declared — the non-strict `.parse()`
+     *  strips any undeclared key. {@link IncidentCronWakeGateSchema}. */
+    cronWakeGate: IncidentCronWakeGateSchema.optional(),
+    /** The per-turn context-budget CASCADE — the progression of budget checks toward
      *  the terminal `contextBudget`. Present only when ≥2 distinct budget states occurred (a single
      *  check adds nothing over `contextBudget`). Dedup'd on transition + capped to the most recent 40,
      *  so a `context_exhausted` abort shows the tightening (assembled-input growth + eviction) in one
      *  `explain` field instead of the terminal fit-check alone. Optional + additive (schemaVersion 1). */
     contextBudgetHistory: z.array(IncidentContextBudgetHistoryEntrySchema).optional(),
-    /** RECALL-01 (observability-excellence): memory-recall outcome aggregated over the
-     *  session's `memory.recalled` trajectory records (the #1 blind spot — recall was
-     *  invisible to obs.explain). Counts/booleans ONLY — never query text or memory bodies
-     *  (§2.7). Optional + additive (present only when the trajectory carries recall records). */
+    /** Memory-recall outcome aggregated over the session's `memory.recalled`
+     *  trajectory records, so recall behavior is diagnosable from the report alone.
+     *  Counts/booleans ONLY — never query text or memory bodies.
+     *  Optional + additive (present only when the trajectory carries recall records). */
     recall: z
         .object({
         /** Number of recall queries the session issued. */
@@ -145,12 +159,12 @@ export const IncidentReportSchema = z.object({
         rerankerAvailable: z.boolean(),
     })
         .optional(),
-    /** OBS-03/OBS-04 (Phase 186): the image-generation turn reconstructed from the
+    /** The image-generation turn reconstructed from the
      *  session's `image.*` trajectory records (the terminal image record wins).
      *  The image cost (`costUsd`) rides HERE — `comis explain` shows it from the
-     *  trajectory (Route a) — NOT `cost.costUsd`, which reads the executor-emitted
+     *  trajectory — NOT `cost.costUsd`, which reads the executor-emitted
      *  `sessionEnd` rollup (a different code path; the image RPC runs in the daemon
-     *  context — Pitfall 2). Content-free: ids/labels/costUsd/outcome ONLY (never
+     *  context, not the executor). Content-free: ids/labels/costUsd/outcome ONLY (never
      *  the prompt, image bytes, or a raw provider message). Optional + additive
      *  (present only when the trajectory carries image records; schemaVersion stays
      *  1) — pre-existing constructors omit it (the `recall` precedent). */
@@ -160,7 +174,7 @@ export const IncidentReportSchema = z.object({
         provider: z.string(),
         /** The image model the provider used (e.g. "gpt-image-1"). Absent on a failed/early turn. */
         model: z.string().optional(),
-        /** The generation cost in USD — the OBS-03 reconstruction (Route a). Absent on a failed turn. */
+        /** The generation cost in USD, reconstructed from the trajectory. Absent on a failed turn. */
         costUsd: z.number().optional(),
         /** The terminal outcome of the image turn. */
         outcome: z.enum(["ok", "failed"]),
@@ -168,18 +182,18 @@ export const IncidentReportSchema = z.object({
         errorKind: z.string().optional(),
         /** Whether the image was delivered to a channel (image.delivered fired). */
         delivered: z.boolean(),
-        /** WR-02 (186): false when the generation SUCCEEDED + was delivered (base64)
+        /** False when the generation SUCCEEDED + was delivered (base64)
          *  but the durable persist FAILED — a degraded delivery, still outcome:"ok"
-         *  and still charged. Absent ⇒ persisted (or pre-WR-02 record). */
+         *  and still charged. Absent ⇒ persisted (or the record omits the field). */
         persisted: z.boolean().optional(),
     })
         .optional(),
-    /** VIS-04 (Phase 187): the VISION turn reconstructed from the session's
+    /** The VISION turn reconstructed from the session's
      *  `media.vision.*` trajectory records (the terminal record wins). The vision
      *  cost (`costUsd`) rides HERE — `comis explain` shows it from the trajectory
-     *  (Route a) — NOT `cost.costUsd`, which reads the executor-emitted `sessionEnd`
-     *  rollup (a different code path; the vision RPC runs in the daemon context —
-     *  Pitfall 2). The `path` is VIS-03's "which tier served" signal. Content-free:
+     *  — NOT `cost.costUsd`, which reads the executor-emitted `sessionEnd`
+     *  rollup (a different code path; the vision RPC runs in the daemon context,
+     *  not the executor). The `path` is the "which tier served" signal. Content-free:
      *  ids/labels/path/costUsd/outcome ONLY (never the image bytes, the analysis
      *  prompt, or the model's answer). Optional + additive (present only when the
      *  trajectory carries media.vision.* records; schemaVersion stays 1) —
@@ -188,13 +202,13 @@ export const IncidentReportSchema = z.object({
         .object({
         /** The executing vision provider id (e.g. "anthropic" on main-vision, "gemini" on the registry tier). */
         provider: z.string(),
-        /** The caller agent's resolved main provider id (the lockstep label). Absent on a pre-VIS-04 / partial record. */
+        /** The caller agent's resolved main provider id (the lockstep label). Absent on a partial record. */
         mainProvider: z.string().optional(),
         /** The vision model used (e.g. "claude-sonnet-4-5"). Absent on a failed/early turn or an adapter that omits it. */
         model: z.string().optional(),
-        /** The analysis cost in USD — the VIS-04 reconstruction (Route a). Absent on a failed turn OR the registry/gemini-video tiers (Pitfall 4). */
+        /** The analysis cost in USD, reconstructed from the trajectory. Absent on a failed turn OR the registry/gemini-video tiers (which carry no per-call cost). */
         costUsd: z.number().optional(),
-        /** Which ladder tier served (VIS-03's "which path" signal). Absent on a partial record. */
+        /** Which ladder tier served (the "which path" signal). Absent on a partial record. */
         path: z.enum(["main-vision", "registry", "gemini-video", "unavailable"]).optional(),
         /** The terminal outcome of the vision turn. */
         outcome: z.enum(["ok", "failed"]),
@@ -202,22 +216,23 @@ export const IncidentReportSchema = z.object({
         errorKind: z.string().optional(),
     })
         .optional(),
-    /** OBS-03/OBS-04 (Phase 192): the VIDEO-generation turn reconstructed from the
+    /** The VIDEO-generation turn reconstructed from the
      *  session's `video.*` trajectory records (the terminal `video.generated` /
      *  `video.failed` record wins; `delivered` set when `video.delivered` fired).
      *  Unlike image/vision (wholly in-turn), a video job completes in the off-turn
      *  background poller — the `video.requested`/`video.submitted` records reach the
      *  persisted trajectory in-turn (recorder alive) and the offline assembler
      *  stitches the later completion via `traceId`/`jobId` on one `sessionKey`. The
-     *  reconciled cost (`costUsd ?? estimatedCostUsd`) rides HERE (Route a — NOT
-     *  `cost.costUsd`, the executor `sessionEnd`; Pitfall 2). Per-backend cost
+     *  reconciled cost (`costUsd ?? estimatedCostUsd`) rides HERE (from the trajectory
+     *  — NOT `cost.costUsd`, the executor `sessionEnd` rollup, a different code
+     *  path). Per-backend cost
      *  provenance: FAL/Veo=estimate, Grok=actual. Content-free: ids/labels/cost/
      *  outcome ONLY (never the prompt, the video bytes, the Veo keyed-download-URL,
      *  or a raw provider message). Optional + additive (present only when the
      *  trajectory carries `video.*` records; schemaVersion stays 1) — pre-existing
      *  constructors omit it (the `image`/`vision`/`recall` precedent).
      *
-     *  WR-04 (Phase 192) — SINGLE-TURN by design: this is ONE signal per session
+     *  SINGLE-TURN by design: this is ONE signal per session
      *  (the LAST/terminal video turn — the highest-seq `video.generated`/`video.failed`
      *  wins, not keyed by `jobId`), exactly matching the `image`/`vision` single-signal
      *  convention. A session that renders MULTIPLE videos reconstructs only the terminal
@@ -233,13 +248,13 @@ export const IncidentReportSchema = z.object({
         provider: z.string(),
         /** The video model the provider used. Absent on a failed/early turn or a backend that omits it. */
         model: z.string().optional(),
-        /** The async job handle — ties the off-turn completion back to its originating turn (OBS-04). */
+        /** The async job handle — ties the off-turn completion back to its originating turn. */
         jobId: z.string().optional(),
         /** The reconciled actual cost in USD (Grok actual; absent for FAL/Veo, which estimate). */
         costUsd: z.number().optional(),
-        /** The pre-submit worst-case estimate (the SEC-02 ceiling input; the FAL/Veo cost provenance). */
+        /** The pre-submit worst-case estimate (the per-hour cost-ceiling input; the FAL/Veo cost provenance). */
         estimatedCostUsd: z.number().optional(),
-        /** The rendered clip duration in seconds (DEL/OBS field). */
+        /** The rendered clip duration in seconds. */
         durationSecs: z.number().optional(),
         /** The terminal outcome of the video turn. */
         outcome: z.enum(["ok", "failed"]),
@@ -249,16 +264,16 @@ export const IncidentReportSchema = z.object({
         delivered: z.boolean(),
     })
         .optional(),
-    /** OBS-02/OBS-05 (Phase 196): the VOICE turn reconstructed from the session's
+    /** The VOICE turn reconstructed from the session's
      *  `media.stt.*` / `media.tts.*` trajectory records (the terminal
      *  `media.*.completed` / `media.*.failed` record wins). Voice is wholly IN-TURN
      *  (unlike video's off-turn poller) — the daemon `media.transcribe` /
      *  `tts.synthesize` RPC handlers direct-emit the lifecycle records in one turn.
-     *  The cost rides HERE (Route a — NOT `cost.costUsd`, the executor `sessionEnd`,
-     *  a different path: the voice RPC runs in the daemon context, Pitfall 2). OBS-05
-     *  honest limit (FLAG 4): a keyless turn records `costUsd:0` EXPLICITLY (so "free"
+     *  The cost rides HERE, from the trajectory — NOT `cost.costUsd`, the executor
+     *  `sessionEnd`, a different path: the voice RPC runs in the daemon context.
+     *  Honest limit: a keyless turn records `costUsd:0` EXPLICITLY (so "free"
      *  is VISIBLE, not absent); a keyed turn OMITS cost (no port carries a per-call
-     *  source today — NOT a fabricated number). The `source` is the OBS-03 resolved
+     *  source today — NOT a fabricated number). The `source` is the resolved
      *  selection rung (WHY `auto` picked it). Content-free: provider/keyless/model/
      *  durationMs/costUsd/source/outcome/errorKind ONLY — never a transcript, audio
      *  bytes, or a credential (the `videoGenerated` content-free discipline). Optional
@@ -276,9 +291,9 @@ export const IncidentReportSchema = z.object({
         model: z.string().optional(),
         /** The wall-clock transcription/synthesis duration in ms. Absent on a failed/early turn. */
         durationMs: z.number().optional(),
-        /** The turn cost in USD (Route a). `0` (explicit) on a keyless turn; ABSENT on a keyed turn (no per-call source today — FLAG 4). */
+        /** The turn cost in USD, from the trajectory. `0` (explicit) on a keyless turn; ABSENT on a keyed turn (no per-call source today). */
         costUsd: z.number().optional(),
-        /** The OBS-03 resolved selection rung — WHY `auto` chose this provider. Absent on a partial record. */
+        /** The resolved selection rung — WHY `auto` chose this provider. Absent on a partial record. */
         source: z.enum(["explicit", "keyless-local", "follow-main-key", "fallback"]).optional(),
         /** The terminal outcome of the voice turn. */
         outcome: z.enum(["ok", "failed"]),
@@ -286,13 +301,14 @@ export const IncidentReportSchema = z.object({
         errorKind: z.string().optional(),
     })
         .optional(),
-    /** OBS-02 (Phase 198): the Verified-Learning outcome signal reconstructed from
+    /** The Verified-Learning outcome signal reconstructed from
      *  the session's `learning.outcome_observed` trajectory records (the fused
      *  terminal verdict wins). Counts/ids/closed-enums ONLY — no body/alpha/recalled
-     *  ids (SEC-01). `outcomeResolved` is false ⇒ a finished trajectory with no
+     *  ids. `outcomeResolved` is false ⇒ a finished trajectory with no
      *  resolvable outcome (the `outcome_unresolved` verdict's trigger; distinct from
-     *  an explicit `unknown` resolution). `skillsUsed`/`skillFailures` empty +
-     *  `synthesisAbstained` false in P0 (attribution/synthesis → Phase 201).
+     *  an explicit `unknown` resolution). `skillsUsed`/`skillFailures` are currently
+     *  always empty and `synthesisAbstained` always false (skill-use attribution and
+     *  synthesis are not implemented).
      *  Optional + additive (present only when the trajectory carries learning
      *  records; schemaVersion stays 1) — the `recall`/`voice` precedent. */
     learning: z
@@ -303,25 +319,25 @@ export const IncidentReportSchema = z.object({
         skillsUsed: z.array(z.string()),
         skillFailures: z.array(z.string()),
         synthesisAbstained: z.boolean(),
-        // OBS-4 (hindsight-reflection-20260626): the reuse→promote chain on this session, COUNTS only.
+        // The reuse→promote chain on this session, COUNTS only.
         // `skillsPromoted`/`skillsDemoted` fold the `learning.skill_promoted`/`learning.skill_demoted`
         // trajectory records so `comis explain <session>` shows "used skill X → promoted N" in ONE call
         // instead of a trajectory + outcome_events + mental_models hand-join. Optional + additive
         // (present only when a promote/demote fired this session; schemaVersion stays 1).
         skillsPromoted: z.number().optional(),
         skillsDemoted: z.number().optional(),
-        // Finding C (obs-sweep package-delivery-20260628): the NAMES of skills demoted this session,
-        // folded from `learning.skill_demoted.demotedSkillNames`. Answers "WHICH skill demoted" (was
-        // count-only → "2 demoted" forced a daemon.log + mental_models hand-join). With the session's
+        // The NAMES of skills demoted this session,
+        // folded from `learning.skill_demoted.demotedSkillNames`. Answers "WHICH skill
+        // demoted" without a daemon.log + mental_models hand-join. With the session's
         // outcome (failure/corrected) this gives "this session's failure demoted skill X" in one call.
         // Optional + additive (present only when ≥1 named demote; schemaVersion stays 1). Ids only.
         skillsDemotedNames: z.array(z.string()).optional(),
-        // OBS-4b (reflect-obs-20260627): memories that accrued a CORROBORATED failure this session
+        // Memories that accrued a CORROBORATED failure this session
         // (count only) — the eviction-causation precursor (`learning.memory_failure_attributed`), so
         // "is this session pushing a memory toward eviction" is one `explain` field. Optional + additive
         // (present only when >0; schemaVersion stays 1).
         failuresAttributed: z.number().optional(),
-        // Finding A (obs-sweep package-delivery-20260628): learned skills that SURFACED for
+        // Learned skills that SURFACED for
         // topic-match reuse and overlapped the turn but missed the credit bar — the reuse NEAR-MISSES,
         // folded from the `memory.skill_surfaced` census. Answers "why wasn't my skill reused?" (it
         // surfaced at coverage 0.45, just under 0.5) in ONE `explain` call instead of a debugger.
@@ -330,14 +346,12 @@ export const IncidentReportSchema = z.object({
         skillsSurfacedButUncredited: z
             .array(z.object({ name: z.string(), coverage: z.number() }))
             .optional(),
-        // Phase 226 SIMPLIFY-04: the Phase-203 userModelRevised / memoriesGeneralized counts
-        // were DELETED with their 0-emit events (the user-rep revision + generalization paths
-        // folded into the reflection engine in Phase 225). The block stays counts/ids-only.
+        // The block stays counts/ids-only — no user-model or generalization fields belong here.
     })
         .optional(),
-    /** PERSIST-01 (observability-excellence, Phase 176): the prompt-cache breaks the
+    /** The prompt-cache breaks the
      *  session incurred, aggregated per-reason from its `cache.break` trajectory
-     *  records (Plan 04). `estCostUsd` is the directly-lost cache-read saving summed
+     *  records. `estCostUsd` is the directly-lost cache-read saving summed
      *  per reason (`tokenDrop × resolveModelPricing.cacheRead`; 0 for an unknown
      *  model — honest). Counts + a closed reason label + a number ONLY — never the
      *  changed tool NAMES (the trajectory carries only the changed-dims digest). The
@@ -355,9 +369,9 @@ export const IncidentReportSchema = z.object({
         estCostUsd: z.number(),
     }))
         .optional(),
-    /** AUDIT-05 (observability-excellence, Phase 176): the security-decision audit
+    /** The security-decision audit
      *  events the session produced, aggregated counts-by-kind from the durable
-     *  `obs_audit_events` (Plan 03) scoped to the session's (tenant, agent, traceId).
+     *  `obs_audit_events` table scoped to the session's (tenant, agent, traceId).
      *  Content-free: a total + a `{kind → count}` record ONLY — NO actor names beyond
      *  ids, NO secret value, NO `refs` blob (the rows are already scrubbed at write).
      *  The `audit?` section answers "what security-relevant actions ran in this
@@ -372,12 +386,12 @@ export const IncidentReportSchema = z.object({
         byKind: z.record(z.string(), z.number()),
     })
         .optional(),
-    /** SPEND (observability-excellence, WEBUI-04 / 179-04 — locked A2): the spend
+    /** The spend
      *  kill-switch breach reconstructed from the session's terminal `spend.exceeded`
-     *  trajectory record (177-obs-loop WR-4). Content-free: the breached `scope` enum
+     *  trajectory record. Content-free: the breached `scope` enum
      *  + the two dollar NUMBERS (`totalUsd` = the breaching scope's spent total;
-     *  `capUsd` = its ceiling) — NO message/query/body. The verdict stays amount-free
-     *  (177 decision); this section carries the numbers the Incident view renders.
+     *  `capUsd` = its ceiling) — NO message/query/body. The verdict stays amount-free;
+     *  this section carries the numbers the Incident view renders.
      *  Optional + additive (present only when the session was spend-killed — undefined,
      *  never {}, when none; schemaVersion stays 1). The `cacheBreaks?`/`audit?` mold. */
     spend: z
@@ -390,13 +404,13 @@ export const IncidentReportSchema = z.object({
         capUsd: z.number(),
     })
         .optional(),
-    /** OBS-3 (openclaw-usecases 2026-06-25): the per-ROOT `autonomy.budget` limb that
+    /** The per-ROOT `autonomy.budget` limb that
      *  tripped (token / wall-clock / aggregateUsd), with its numbers in their own unit.
      *  DISTINCT from `spend` (the priced `observability.spend` $-ceiling): a token or
      *  wall-clock breach carries tokens / ms in `spent`/`cap` (NOT dollars), and the
      *  knob to raise is `autonomy.budget.<limb>` — surfacing it lets `explain` name the
      *  exact limb + numbers in ONE call instead of an operator grepping the
-     *  "Per-root … budget exceeded" daemon-log line (the limb used to be log-only).
+     *  "Per-root … budget exceeded" daemon-log line.
      *  Optional + additive (present only on a per-root spend-abort; schemaVersion 1). */
     perRootBudget: z
         .object({
@@ -410,7 +424,51 @@ export const IncidentReportSchema = z.object({
         unit: z.string(),
     })
         .optional(),
-    /** OBS-4 (openclaw-usecases 2026-06-25): distinct turns (envelope traceId) the
+    /** The terminal user-surface state: which outcome the activity renderer's
+     *  finalize painted (the kept "❌ {errorKind}" pill / deleted scaffold /
+     *  no-op — deterministic per strategy), and whether an observed failed
+     *  event RECLASSIFIED a success outcome to failure. Answers "what did the
+     *  user's chat show this turn" from the trajectory alone. From the LAST
+     *  `activity.turn_finalized` record; absent when none. */
+    activityFinalize: z
+        .object({
+        /** The renderer strategy that painted the surface (EditPlace / AppendOnly / …). */
+        strategy: z.string(),
+        /** The EFFECTIVE outcome kind dispatched to the renderer. */
+        outcome: z.string(),
+        /** The failure errorKind, when the outcome is a failure. */
+        errorKind: z.string().optional(),
+        /** The fixed one-line resource-abort reason, when present. */
+        reason: z.string().optional(),
+        /** True when a failed event flipped a non-failure outcome to failure. */
+        reclassified: z.boolean(),
+    })
+        .optional(),
+    /** Silent-failure recovery attempts folded from the session's
+     *  `execution.recovery_attempted` records — the model re-entries
+     *  (silent_retry / lkw_fallback / continuation_nudge) that were previously
+     *  log-only. `total` attempts, `succeeded` count, and per-reason counts.
+     *  Absent ⇒ no recovery attempts this session. */
+    recoveries: z
+        .object({
+        total: z.number(),
+        succeeded: z.number(),
+        byReason: z.record(z.string(), z.number()),
+    })
+        .optional(),
+    /** Reply blocks an aborted execution left UNSENT — the pacer's hard stop
+     *  never reaches the delivery service, so no `delivery.dispatched` fires
+     *  and the user silently receives nothing. Σ over the session's
+     *  `delivery.aborted` records; absent when none. */
+    deliverySkipped: z
+        .object({
+        /** How many aborted-delivery events the session recorded. */
+        events: z.number(),
+        /** Total blocks that were never sent across those events. */
+        chunksNotSent: z.number(),
+    })
+        .optional(),
+    /** Distinct turns (envelope traceId) the
      *  trajectory spans. Present only when >1 — it flags the whole-session toolStats as
      *  cumulative-across-N-turns (the trajectory JSONL is append-only across severs), so
      *  a reader does not misread a multi-turn count as this-turn. Additive (schemaVersion 1). */
@@ -432,7 +490,7 @@ export const IncidentReportSchema = z.object({
     /**
      * READ-coverage breadcrumb (meta-observability): did the assembler actually
      * locate + read each source, and did every offload pointer resolve? DISTINCT
-     * from `truncations[]` (which records SIZE-drops from the Plan-04 bounding
+     * from `truncations[]` (which records SIZE-drops from the bounding
      * pass): `coverage` records whether the INPUTS were read, so a silently-empty
      * report ("0 trajectory records / 0 of N pointers resolved") is self-evident
      * instead of masquerading as a clean zero-activity session. Optional
@@ -444,7 +502,7 @@ export const IncidentReportSchema = z.object({
         rollup: z.object({ present: z.boolean() }),
         offloads: z.object({ pointersResolved: z.number(), pointersTotal: z.number() }),
         /**
-         * QT1 — toolStats reconciliation between THIS report (the whole-session
+         * The toolStats reconciliation between THIS report (the whole-session
          * trajectory union, the headline `toolStats`) and the persisted per-session
          * rollup that `obs.fleet.health` reads (latest-execution-wins). The two
          * lenses read structurally-different sources, so they CAN legitimately
@@ -479,7 +537,7 @@ export const IncidentReportSchema = z.object({
 /**
  * Assemble a redaction-safe post-mortem for a single agent session.
  *
- * Accepts ONE of `sessionKey`, `traceId`, or `rootRunId` (FLEET-05; the
+ * Accepts ONE of `sessionKey`, `traceId`, or `rootRunId` (the
  * `.refine` rejects none-of-three). A `traceId` is canonicalized to its
  * sessionKey, and a `rootRunId` (an autonomy run) is canonicalized to the
  * run's sessionKey, so there is one assembler path. `depth` selects the
@@ -492,26 +550,26 @@ export const ObsExplainContract = defineContract({
         .object({
         sessionKey: z.string().min(1).optional(),
         traceId: z.string().min(1).optional(),
-        // FLEET-05: the 3rd ref shape — an autonomy run's rootRunId (the synthetic
+        // The 3rd ref shape — an autonomy run's rootRunId (the synthetic
         // `root-session-<key>` or a real spawned/socket root). The daemon
         // canonicalizes it to its sessionKey FIRST (resolveRootRunToSession), so the
         // fleet→explain drill-down can paste the worst run's rootRunId straight in.
         rootRunId: z.string().min(1).optional(),
         depth: z.enum(["summary", "full"]).optional(),
-        // D9: admin opt-in to include synthetic/test sessions (excluded by default).
+        // Admin opt-in to include synthetic/test sessions (excluded by default).
         includeSynthetic: z.boolean().optional(),
     })
         .refine((r) => r.sessionKey != null || r.traceId != null || r.rootRunId != null, {
         message: "sessionKey, traceId, or rootRunId required",
     }),
     response: IncidentReportSchema,
-    // OBS-SELF-DEAD (30uc-20260624 UC-14): rpc, NOT admin. The obs_query agent tool's
+    // rpc, NOT admin. The obs_query agent tool's
     // explain/session_report action calls obs.explain for SELF-observability ("why did my
-    // session degrade?") — a documented agent capability (CLAUDE.md). As scopes:["admin"] it
-    // was in ADMIN_METHODS → assertNotAgentOrigin denied the agent-origin call before the
-    // handler ran ("Control-plane method obs.explain is not reachable from an agent origin").
-    // The report is READ-ONLY + scrubbed/digest-only (no secrets — 30uc UC-27 residency sweep
-    // confirmed zero secret residency in the trajectory it reads), and the daemon is
-    // single-tenant (reads its own data dir). Same MD-02 re-scope class as memory.store.
+    // session degrade?") — a documented agent capability. As scopes:["admin"] it
+    // would sit in ADMIN_METHODS → assertNotAgentOrigin would deny the agent-origin call
+    // before the handler ran ("Control-plane method obs.explain is not reachable from an
+    // agent origin"). The report is READ-ONLY + scrubbed/digest-only (no secrets — the
+    // trajectory it reads carries no secret residency), and the daemon is
+    // single-tenant (reads its own data dir). `memory.store` is rpc-scoped for the same reason.
     scopes: ["rpc"],
 });

package/node_modules/@comis/core/dist/api-contracts/index.d.ts

@@ -2,14 +2,14 @@
  * `@comis/core/api-contracts` aggregator (barrel-only public surface).
  * External consumers always import from `"@comis/core"`.
  *
- * One contract file per logical domain; this file aggregates the 16
+ * One contract file per logical domain; this file aggregates the 17
  * domain registries into a single deterministic registry. Imports are
  * alphabetically sorted so future contract authors get deterministic
  * git diffs (alphabetical position of the domain).
  *
- * Domain order: agents → auth → capabilities → channels → config → daemon →
- * mcp → mcp-oauth → media → memory → observability → orchestrator → secrets →
- * sessions → tokens → workspace. Note: `mcp` < `mcp-oauth` < `media`
+ * Domain order: agents → auth → capabilities → channels → config → context →
+ * daemon → mcp → mcp-oauth → media → memory → observability → orchestrator →
+ * secrets → sessions → tokens → workspace. Note: `mcp` < `mcp-oauth` < `media`
  * alphabetically.
  *
  * The bidirectional 1:1 test in

package/node_modules/@comis/core/dist/api-contracts/index.js

@@ -1,4 +1,4 @@
-// 16 domain imports — alphabetical order for deterministic git diffs.
+// 17 domain imports — alphabetical order for deterministic git diffs.
 import { AGENTS_CONTRACTS } from "./agents.js";
 import { AUTH_CONTRACTS } from "./auth.js";
 import { CAPABILITIES_CONTRACTS } from "./capabilities.js";

package/node_modules/@comis/core/dist/api-contracts/internals.js

@@ -19,13 +19,13 @@
 /** The 18 dispatcher-injected internal-field names (sorted alphabetically). */
 export const INTERNAL_FIELD_NAMES = [
     "_agentId",
-    // The trusted autonomy mode signal (Phase 217). Injected by createAgentRpcCall
+    // The trusted autonomy mode signal. Injected by createAgentRpcCall
     // on the in-process leg from resolveAutonomy(...).mode; listed here so
     // stripInternalFields STRIPS a forged inbound value BEFORE the chokepoint reads
     // it — the exact strip-then-inject pattern `_agentId`/`_outwardStepIndex` use, so
     // a jailed/external caller cannot forge mode:"max" to perturb the deny-vs-escalate
     // decision. Agent-origin-only by construction; absent ⇒ the chokepoint fail-closes
-    // to "default" (EVICT-02). Sorted position: after `_agentId` — JS `.sort()` (and
+    // to "default". Sorted position: after `_agentId` — JS `.sort()` (and
     // localeCompare) order "_agentId" < "_autonomyMode" (the 2nd char 'g' < 'u'), the
     // canonical order the colocated self-check test enforces.
     "_autonomyMode",
@@ -33,8 +33,8 @@ export const INTERNAL_FIELD_NAMES = [
     "_callerChannelType",
     "_callerMetadata",
     "_callerSessionKey",
-    // The trusted in-process caller's resolved orchestration capabilities
-    // (Phase 210). Injected by createAgentRpcCall / the 211 lease endpoint;
+    // The trusted in-process caller's resolved orchestration capabilities.
+    // Injected by createAgentRpcCall / the capability lease endpoint;
     // stripped from external WS/REST callers so caps cannot be forged.
     "_capabilities",
     "_channelType",
@@ -42,15 +42,16 @@ export const INTERNAL_FIELD_NAMES = [
     "_context",
     "_deliveryTarget",
     "_originChannelId",
-    // The monotonic outward-send index (Phase 216, NEW-3/HIGH-1). Allocated by
+    // The monotonic outward-send index. Allocated by
     // durableRuns.allocateOutwardStep at the TRUSTED cap chokepoint (the jail leg
     // in setup-capability-endpoint.ts + the in-process leg in
     // setup-tools-capabilities.ts) and injected as `_outwardStepIndex` for the
     // outward message methods. Listed here so stripInternalFields STRIPS a forged
     // inbound value BEFORE the chokepoint re-injects the trusted allocated one —
     // the exact strip-then-inject pattern `_agentId` uses, so a jailed script
-    // cannot forge the index to self-collide its own send (inverting ONCE-02) or
-    // perturb outward ordering. Agent-origin-only by construction.
+    // cannot forge the index to self-collide its own send (defeating the outward-
+    // send ledger's idempotency-key dedup) or perturb outward ordering.
+    // Agent-origin-only by construction.
     "_outwardStepIndex",
     "_sessionKey",
     "_tenantId",

package/node_modules/@comis/core/dist/api-contracts/mcp.js

@@ -295,11 +295,11 @@ export const McpConnectContract = defineContract({
         // Auth scheme for remote transports. When "oauth", the daemon promotes
         // the new entry to auth:"oauth" and `mcp.oauth_login` can drive the PKCE
         // flow via `mcp_login`. When "headers" (or absent), credential injection
-        // via the `headers` field is used (legacy/default behaviour). Accepted on
+        // via the `headers` field is used (the default behaviour). Accepted on
         // `mcp.connect` and PERSISTED so the auth requirement survives a daemon
-        // restart (R11-01 first-install OAuth promotion). The field MUST be
+        // restart (first-install OAuth promotion). The field MUST be
         // included in the contract schema or z.object strict-parsing strips it
-        // before it reaches the handler (RESEARCH.md Common Pitfall 1).
+        // before it reaches the handler.
         auth: z.enum(["headers", "oauth"]).optional(),
     }),
     response: z.object({