comisai 1.0.34 → 1.0.36

package/node_modules/@comis/agent/dist/background/completion-runner.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Background completion runner: subscribes to background_task:completed and
+ * background_task:failed events from the TypedEventBus and re-enters the
+ * originating agent session with a formatted completion announcement.
+ *
+ * Per-session lock serialization is delegated to the existing session
+ * manager (ComisSessionManager.withSession in packages/agent/src/session/).
+ * The runner does NOT introduce its own queueing -- one turn per completion
+ * event, ordering follows the existing per-session lock.
+ *
+ * Recursion bound: per-task incoming hop count + 1 must stay below
+ * `maxBackgroundHops` (default 3). When the cap is hit, the runner emits
+ * the fallback notification instead of triggering executor.execute().
+ * The hop count is read from `task.origin.backgroundHopCount`
+ * (populated by the originResolver).
+ *
+ * Latency-instrumentation hook: emits `background_task:reentered`
+ * immediately before executor.execute(). Integration tests compute the delta
+ * from `background_task:completed.timestamp` to this event for SLO tracking.
+ *
+ * Failure isolation: each handler is wrapped in suppressError so a single
+ * completion's failure does not tear down the subscription (AGENTS §2.1).
+ *
+ * @module
+ */
+import { randomUUID } from "node:crypto";
+import { suppressError } from "@comis/shared";
+import { parseFormattedSessionKey } from "@comis/core";
+import { formatCompletionAnnouncement } from "./completion-formatter.js";
+/**
+ * Wire the completion runner against an event bus + executor + session store.
+ * Subscriptions are installed synchronously; call shutdown() to remove them.
+ */
+export function createBackgroundCompletionRunner(deps) {
+    const log = deps.logger.child({ submodule: "background-completion-runner" });
+    let stopped = false;
+    let inflight = Promise.resolve();
+    const onCompleted = (data) => {
+        if (stopped)
+            return;
+        const promise = handleEvent(data.taskId, "completed");
+        inflight = inflight.then(() => promise).catch(() => undefined);
+        suppressError(promise, "background completion handler (completed)");
+    };
+    const onFailed = (data) => {
+        if (stopped)
+            return;
+        const promise = handleEvent(data.taskId, "failed");
+        inflight = inflight.then(() => promise).catch(() => undefined);
+        suppressError(promise, "background completion handler (failed)");
+    };
+    deps.eventBus.on("background_task:completed", onCompleted);
+    deps.eventBus.on("background_task:failed", onFailed);
+    async function handleEvent(taskId, kind) {
+        const task = deps.taskManager.getTask(taskId);
+        if (!task) {
+            log.warn({ taskId, kind, hint: "Task disappeared from manager before runner could resolve it; no announcement injected", errorKind: "internal" }, "Background completion: task not in manager");
+            return;
+        }
+        // Legacy task without origin -- emit fallback, keep file for audit.
+        const origin = task.origin;
+        if (!origin || !origin.sessionKey || !origin.agentId) {
+            await fallbackForTask(task.toolName, task.origin?.agentId ?? "default", `Background task "${task.toolName}" completed.`);
+            return;
+        }
+        // Hop cap. Read incoming hop count from origin (schema field populated
+        // by the originResolver).
+        const nextHopCount = (origin.backgroundHopCount ?? 0) + 1;
+        if (nextHopCount >= deps.maxBackgroundHops) {
+            log.info({ taskId, toolName: task.toolName, agentId: origin.agentId, hopCount: nextHopCount, max: deps.maxBackgroundHops }, "Background completion: hop cap reached, falling back to user notification");
+            await fallbackForTask(task.toolName, origin.agentId, `Background task "${task.toolName}" completed but follow-up was skipped — recursion limit reached. Run again or check the result manually.`);
+            return;
+        }
+        // Missing session -- session expired while the task ran. No channel to deliver
+        // to, so skip fallback (which would only produce a WARN from notification-service).
+        const sessionExists = deps.sessionStore.loadByFormattedKey(origin.sessionKey) !== undefined;
+        if (!sessionExists) {
+            log.info({ taskId, sessionKey: origin.sessionKey }, "Background completion: session expired, skipping re-entry");
+            return;
+        }
+        // Reconstruct the SessionKey object for executor.execute().
+        const parsedKey = parseFormattedSessionKey(origin.sessionKey);
+        if (!parsedKey) {
+            log.warn({ taskId, sessionKey: origin.sessionKey, hint: "Persisted sessionKey is malformed; cannot route announcement", errorKind: "internal" }, "Background completion: invalid sessionKey");
+            await fallbackForTask(task.toolName, origin.agentId, `Background task "${task.toolName}" completed (routing failed).`);
+            return;
+        }
+        // Format the announcement (byte-identical trailing instruction).
+        const announcement = formatCompletionAnnouncement(task);
+        // Construct the synthetic NormalizedMessage (hop counter in metadata).
+        const syntheticMsg = {
+            id: randomUUID(),
+            channelId: origin.channelId,
+            channelType: "background_task",
+            senderId: "background-task-runner",
+            text: announcement,
+            timestamp: Date.now(),
+            attachments: [],
+            metadata: {
+                backgroundHopCount: nextHopCount,
+                backgroundTaskId: task.id,
+                toolName: task.toolName,
+                agentId: origin.agentId,
+                traceId: origin.traceId ?? undefined,
+            },
+        };
+        log.debug({ taskId, sessionKey: origin.sessionKey, agentId: origin.agentId, toolName: task.toolName, hopCount: nextHopCount }, "Background completion runner: invoking executor");
+        // Emit background_task:reentered immediately before executor.execute().
+        // Integration tests compute p95 latency from
+        // background_task:completed.timestamp to this event's timestamp.
+        deps.eventBus.emit("background_task:reentered", {
+            taskId: task.id,
+            agentId: origin.agentId,
+            sessionKey: origin.sessionKey,
+            hopCount: nextHopCount,
+            timestamp: Date.now(),
+        });
+        // One turn per event. Existing session lock orders concurrent calls.
+        try {
+            await deps.getExecutor(origin.agentId).execute(syntheticMsg, parsedKey, undefined, undefined, origin.agentId);
+        }
+        catch (err) {
+            log.warn({ taskId, err, hint: "Executor failed mid-completion turn; subscription remains active", errorKind: "internal" }, "Background completion: executor.execute() rejected");
+        }
+    }
+    async function fallbackForTask(toolName, agentId, message) {
+        try {
+            await deps.fallbackNotifyFn({
+                agentId,
+                message,
+                priority: "normal",
+                origin: "background_task",
+            });
+        }
+        catch (err) {
+            log.warn({ toolName, agentId, err, hint: "fallbackNotifyFn rejected; user will not see the completion notification for this task", errorKind: "internal" }, "Background completion: fallbackNotifyFn rejected");
+        }
+    }
+    return {
+        async shutdown() {
+            if (stopped)
+                return;
+            stopped = true;
+            deps.eventBus.off("background_task:completed", onCompleted);
+            deps.eventBus.off("background_task:failed", onFailed);
+            // Wait for any in-flight handler to settle before returning.
+            await inflight;
+        },
+    };
+}

package/node_modules/@comis/agent/dist/background/index.d.ts

@@ -4,8 +4,12 @@
  * @module
  */
 export type { BackgroundTask, BackgroundTaskStatus, PersistedTaskState } from "./background-task-types.js";
+export type { BackgroundTaskOrigin } from "@comis/core";
 export { persistTaskSync, loadTask, recoverTasks, removeTaskFile, TASK_DIR_NAME, } from "./background-task-persistence.js";
 export { createBackgroundTaskManager, } from "./background-task-manager.js";
 export type { BackgroundTaskManager, BackgroundTaskManagerOpts, NotifyFn, } from "./background-task-manager.js";
 export { wrapToolForAutoBackground, } from "./auto-background-middleware.js";
 export type { ToolDefinition, } from "./auto-background-middleware.js";
+export { formatCompletionAnnouncement, TRAILING_INSTRUCTION } from "./completion-formatter.js";
+export { createBackgroundCompletionRunner } from "./completion-runner.js";
+export type { BackgroundCompletionRunner, BackgroundCompletionRunnerDeps, RunnerSessionStore, } from "./completion-runner.js";

package/node_modules/@comis/agent/dist/background/index.js

@@ -7,3 +7,5 @@
 export { persistTaskSync, loadTask, recoverTasks, removeTaskFile, TASK_DIR_NAME, } from "./background-task-persistence.js";
 export { createBackgroundTaskManager, } from "./background-task-manager.js";
 export { wrapToolForAutoBackground, } from "./auto-background-middleware.js";
+export { formatCompletionAnnouncement, TRAILING_INSTRUCTION } from "./completion-formatter.js";
+export { createBackgroundCompletionRunner } from "./completion-runner.js";

package/node_modules/@comis/agent/dist/bridge/bridge-metrics.d.ts

@@ -58,12 +58,23 @@ export interface BridgeMetricsState {
     totalThinkingTokens: number;
     budgetWarningEmitted: boolean;
     thinkingBlockHashes: Map<string, ThinkingBlockHash[]>;
-    /** 260428-hoy: Canonical (pre-mutation) snapshot of each assistant message's
-     *  full content array, captured at stream close in lockstep with thinkingBlockHashes.
+    /** Canonical (pre-mutation) snapshot of each assistant message's full
+     *  content array, captured at stream close in lockstep with thinkingBlockHashes.
      *  Keyed by responseId; capped at 32 with FIFO eviction in lockstep with the
      *  hash store. Used by the pre-LLM-call restoration pass to heal cross-turn
      *  mutation of signed thinking blocks before pi-ai serializes the next request. */
     thinkingBlockCanonical: Map<string, ReadonlyArray<unknown>>;
+    /** Number of pre-LLM-call hash-assertion walks performed (one per turn_start). */
+    hashAssertionsRan: number;
+    /** Total cross-turn thinking-block hash mismatches surfaced across all walks. */
+    hashAssertionMismatches: number;
+    /** Number of signature-replay scrubber invocations that scrubbed at least one
+     *  assistant message in this execute(). Populated via ceSetup.getSignatureScrubCounters
+     *  in executor-post-execution; surfaced here for symmetry / future bridge-side use. */
+    signatureScrubs: number;
+    /** Total tool calls across all signature-replay scrubs whose thoughtSignature
+     *  was stripped (post-incident-visibility metric). */
+    signatureScrubsToolCallsAffected: number;
 }
 /**
  * Create a fresh metrics state with all counters zeroed.
@@ -100,4 +111,8 @@ export declare function buildBridgeResult(metrics: BridgeMetricsState, stepCount
     sessionCacheSavedUsd?: number;
     thinkingTokens?: number;
     budgetWarningEmitted?: boolean;
+    hashAssertionsRan?: number;
+    hashAssertionMismatches?: number;
+    signatureScrubs?: number;
+    signatureScrubsToolCallsAffected?: number;
 };

package/node_modules/@comis/agent/dist/bridge/bridge-metrics.js

@@ -53,6 +53,11 @@ export function createBridgeMetrics() {
         budgetWarningEmitted: false,
         thinkingBlockHashes: new Map(),
         thinkingBlockCanonical: new Map(),
+        // per-execute diagnostic counters
+        hashAssertionsRan: 0,
+        hashAssertionMismatches: 0,
+        signatureScrubs: 0,
+        signatureScrubsToolCallsAffected: 0,
     };
 }
 /**
@@ -95,12 +100,19 @@ export function buildBridgeResult(metrics, stepCount) {
         lastStopReason: metrics.lastStopReason,
         cacheWrite5mTokens: metrics.totalCacheWrite5mTokens,
         cacheWrite1hTokens: metrics.totalCacheWrite1hTokens,
-        // 1.3: Session-cumulative cost fields
+        // Session-cumulative cost fields
         sessionCostUsd: metrics.sessionCumulativeCostUsd,
         sessionCacheSavedUsd: metrics.sessionCumulativeCacheSavedUsd,
-        // 1.5: Thinking tokens (omitted when 0 to avoid log noise)
+        // Thinking tokens (omitted when 0 to avoid log noise)
         thinkingTokens: metrics.totalThinkingTokens > 0 ? metrics.totalThinkingTokens : undefined,
         // Budget trajectory warning flag
         budgetWarningEmitted: metrics.budgetWarningEmitted || undefined,
+        // Per-execute diagnostic counters. Always populated (no `> 0` gate) — a
+        // `0` in the bookend log is itself meaningful ("no scrubs/assertions
+        // this execute") and gating would lose that signal.
+        hashAssertionsRan: metrics.hashAssertionsRan,
+        hashAssertionMismatches: metrics.hashAssertionMismatches,
+        signatureScrubs: metrics.signatureScrubs,
+        signatureScrubsToolCallsAffected: metrics.signatureScrubsToolCallsAffected,
     };
 }

package/node_modules/@comis/agent/dist/bridge/pi-event-bridge.d.ts

@@ -54,7 +54,7 @@ export interface PiEventBridgeDeps {
      *  internal retry. Rate-limit windows are per-minute (longer than the SDK's
      *  ~30s retry budget), so retrying within the window cannot succeed.
      *  Non-`rate_limited` retryable errors (overloaded, network, 5xx) bypass this
-     *  hook -- the SDK's normal retry-with-backoff proceeds. (260501-dkl) */
+     *  hook -- the SDK's normal retry-with-backoff proceeds. */
     onAbortRetry?: () => void;
     /** SDK context usage accessor -- returns live context metrics from AgentSession. */
     getContextUsage?: () => ContextUsageData | undefined;
@@ -106,7 +106,7 @@ export interface PiEventBridgeDeps {
     sepMessageText?: string;
     /** Execution start timestamp for SEP timing metrics. */
     sepExecutionStartMs?: number;
-    /** Cache break detection Phase 2 callback. Returns CacheBreakEvent if break detected. */
+    /** Cache break detection callback. Returns CacheBreakEvent if break detected. */
     checkCacheBreak?: (input: {
         sessionKey: string;
         provider: string;
@@ -130,27 +130,27 @@ export interface PiEventBridgeDeps {
     graphId?: string;
     /** Graph node ID for cache write signal emission. Set only for graph subagents. */
     nodeId?: string;
-    /** + 49-01: Shared mutable TTL split estimate. Populated by request-body-injector
+    /** Shared mutable TTL split estimate. Populated by request-body-injector
      *  on each API call, read by the bridge on turn_end for per-TTL cost calculation.
      *  The bridge normalizes these estimates against the actual SDK-reported cacheWriteTokens. */
     ttlSplit?: TtlSplitEstimate;
-    /** 260428-hoy pre-call hook: invoked once per `turn_start` event, BEFORE
-     *  pi-ai serializes the next request. The closure (defined in pi-executor)
-     *  walks `session.agent.state.messages`, asserts the cross-turn
-     *  hash-invariant per assistant message with a stored hash entry (logs
-     *  ERROR on mutation), then runs the canonical-restore helper against the
-     *  canonical store (heals any mutation in-place by writing the result
-     *  back to `session.agent.state.messages`). The return value is unused by
-     *  the bridge -- the side effect is the heal write-back. Optional: when
+    /** Pre-call hook: invoked once per `turn_start` event, BEFORE pi-ai
+     *  serializes the next request. The closure (defined in pi-executor) walks
+     *  `session.agent.state.messages`, asserts the cross-turn hash-invariant
+     *  per assistant message with a stored hash entry (logs ERROR on mutation),
+     *  then runs the canonical-restore helper against the canonical store
+     *  (heals any mutation in-place by writing the result back to
+     *  `session.agent.state.messages`). The return value is unused by the
+     *  bridge -- the side effect is the heal write-back. Optional: when
      *  omitted, both the diagnostic and the heal are silently disabled
      *  (e.g., unit tests that don't drive a full agent session). */
     getSessionMessages?: () => ReadonlyArray<unknown> | undefined;
-    /** 260428-iag wire-edge diagnostic: returns the absolute path to the
-     *  per-session JSONL on disk. The bridge invokes this only when the LLM
-     *  error path detects the signed-replay rejection signature, then
-     *  diff'd against the persisted canonical to surface mutation that
-     *  occurred AFTER the bridge's restoration hook. Optional — when
-     *  omitted, the wire-edge diagnostic is a silent no-op. */
+    /** Wire-edge diagnostic: returns the absolute path to the per-session JSONL
+     *  on disk. The bridge invokes this only when the LLM error path detects
+     *  the signed-replay rejection signature, then diff'd against the persisted
+     *  canonical to surface mutation that occurred AFTER the bridge's
+     *  restoration hook. Optional — when omitted, the wire-edge diagnostic is
+     *  a silent no-op. */
     getSessionJsonlPath?: () => string | null;
 }
 /** Estimated cost payload for a timed-out API request. */
@@ -193,12 +193,12 @@ export interface PiEventBridgeResult {
     };
     /** Accumulate estimated cost from a timed-out API request. */
     addGhostCost: (estimated: GhostCostEstimate) => void;
-    /** 260428-hoy: ReadonlyMap views of the per-responseId hash store and
-     *  canonical-snapshot store, both populated at stream-close in lockstep.
-     *  The executor's pre-LLM-call closure reads both stores to drive the
-     *  hash-invariant assertion plus the canonical restore helper. Returns
-     *  ReadonlyMap views to preserve internal-state encapsulation -- the
-     *  underlying `m` object is never exported. */
+    /** ReadonlyMap views of the per-responseId hash store and canonical-snapshot
+     *  store, both populated at stream-close in lockstep. The executor's
+     *  pre-LLM-call closure reads both stores to drive the hash-invariant
+     *  assertion plus the canonical restore helper. Returns ReadonlyMap views
+     *  to preserve internal-state encapsulation -- the underlying `m` object is
+     *  never exported. */
     getThinkingBlockStores: () => {
         hashes: ReadonlyMap<string, ReadonlyArray<ThinkingBlockHash>>;
         canonical: ReadonlyMap<string, ReadonlyArray<unknown>>;

package/node_modules/@comis/agent/dist/bridge/pi-event-bridge.js

@@ -186,7 +186,7 @@ export function createPiEventBridge(deps) {
                         ...(truncMeta && { truncated: truncMeta.truncated, fullChars: truncMeta.fullChars, returnedChars: truncMeta.returnedChars }),
                     });
                     // Reset prompt timeout after each tool completion so slow tools
-                    // do not starve subsequent LLM turns (Quick 215).
+                    // do not starve subsequent LLM turns.
                     deps.onToolExecutionEnd?.();
                     // Safety: check step limit (delegated to bridge-safety-controls)
                     {
@@ -222,20 +222,20 @@ export function createPiEventBridge(deps) {
                 // LLM turn about to start (pre-serialize hook for assert+restore)
                 // -----------------------------------------------------------------
                 case "turn_start": {
-                    // 260428-hoy: Run the executor-supplied pre-call closure once per
-                    // turn, before pi-ai reads `session.agent.state.messages` to
-                    // serialize the next API request. The closure performs the
-                    // assert-then-restore pass over the live transcript and writes the
-                    // healed array back into session state when at least one swap
-                    // happens, so the bytes Anthropic sees match the canonical
-                    // stream-close snapshot. The closure swallows its own throws; the
-                    // wrapper here is belt-and-braces.
+                    // Run the executor-supplied pre-call closure once per turn, before
+                    // pi-ai reads `session.agent.state.messages` to serialize the next
+                    // API request. The closure performs the assert-then-restore pass
+                    // over the live transcript and writes the healed array back into
+                    // session state when at least one swap happens, so the bytes
+                    // Anthropic sees match the canonical stream-close snapshot. The
+                    // closure swallows its own throws; the wrapper here is
+                    // belt-and-braces.
                     //
-                    // 260428-j0v: ALWAYS emit ONE INFO log carrying the counters the
-                    // bridge can derive — even when the closure is unwired or returns
-                    // undefined / no candidates. This closes the silent-success
-                    // ambiguity observed on trace c5680133 where ZERO agent.bridge.*
-                    // events appeared despite the helpers having shipped.
+                    // ALWAYS emit ONE INFO log carrying the counters the bridge can
+                    // derive — even when the closure is unwired or returns undefined /
+                    // no candidates. This closes the silent-success ambiguity where
+                    // ZERO agent.bridge.* events appeared despite the helpers having
+                    // shipped.
                     //
                     // Counters are computed by the bridge's own walk of the messages
                     // returned by the closure (or empty when unwired) so the executor
@@ -289,15 +289,27 @@ export function createPiEventBridge(deps) {
                     // implementation; surfaced as a separate field so future asymmetric
                     // assert/restore semantics are observable.
                     const restoredCount = mismatchesLogged;
-                    deps.logger.info({
-                        module: "agent.bridge.hash-invariant",
+                    m.hashAssertionsRan++;
+                    m.hashAssertionMismatches += mismatchesLogged;
+                    const hashAssertionPayload = {
+                        submodule: "bridge.hash-invariant",
                         candidatesChecked,
                         mismatchesLogged,
                         restoredCount,
                         anyResponseIdMatched,
                         hashStoreSize,
                         canonicalStoreSize,
-                    }, "Pre-call assertion ran");
+                    };
+                    if (mismatchesLogged > 0) {
+                        deps.logger.warn({
+                            ...hashAssertionPayload,
+                            hint: "Cross-turn thinking-block mutation detected; pre-call restore pass will heal before next API serialize. Investigate if this fires repeatedly without the heal succeeding (canonicalStoreSize === 0).",
+                            errorKind: "internal",
+                        }, "Pre-call assertion ran");
+                    }
+                    else {
+                        deps.logger.debug(hashAssertionPayload, "Pre-call assertion ran");
+                    }
                     break;
                 }
                 // -----------------------------------------------------------------
@@ -337,14 +349,14 @@ export function createPiEventBridge(deps) {
                                     thinkingLen: typeof b.thinking === "string" ? b.thinking.length : 0,
                                 })),
                             }, "Assistant message block accounting at stream close");
-                            // Bug A diagnostic + 260428-hoy heal: capture hashes AND a
-                            // canonical (pre-mutation) snapshot of the full content array,
-                            // keyed by responseId, in lockstep across both stores. The
-                            // hash store powers the assertion ERROR log (mutation
-                            // diagnostic); the canonical store powers the pre-call
-                            // restore pass that heals cross-turn mutation before the next
-                            // API serialize. Both stores are FIFO-evicted at 32 entries
-                            // in lockstep so they always share the same keyset.
+                            // Diagnostic + heal: capture hashes AND a canonical (pre-mutation)
+                            // snapshot of the full content array, keyed by responseId, in
+                            // lockstep across both stores. The hash store powers the
+                            // assertion ERROR log (mutation diagnostic); the canonical
+                            // store powers the pre-call restore pass that heals cross-turn
+                            // mutation before the next API serialize. Both stores are
+                            // FIFO-evicted at 32 entries in lockstep so they always share
+                            // the same keyset.
                             if (typeof responseIdForLog === "string") {
                                 const hashes = computeThinkingBlockHashes(blocks);
                                 if (hashes.length > 0) {
@@ -356,11 +368,11 @@ export function createPiEventBridge(deps) {
                                         m.thinkingBlockCanonical.delete(oldestKey);
                                     }
                                     m.thinkingBlockHashes.set(responseIdForLog, hashes);
-                                    // 260428-hoy: capture canonical (pre-mutation) full
-                                    // content array so the pre-LLM-call restore pass can heal
-                                    // any cross-turn mutation before pi-ai serializes the
-                                    // next request. structuredClone is a Node 22 global; the
-                                    // try/catch is defensive against rare exotic input shapes.
+                                    // Capture canonical (pre-mutation) full content array so
+                                    // the pre-LLM-call restore pass can heal any cross-turn
+                                    // mutation before pi-ai serializes the next request.
+                                    // structuredClone is a Node 22 global; the try/catch is
+                                    // defensive against rare exotic input shapes.
                                     try {
                                         const canonical = Object.freeze(structuredClone(blocks));
                                         m.thinkingBlockCanonical.set(responseIdForLog, canonical);
@@ -382,7 +394,7 @@ export function createPiEventBridge(deps) {
                     const llmLatencyMs = turnWallclockMs - effectiveTurnToolMs;
                     m.cumulativeLlmDurationMs += llmLatencyMs;
                     m.turnToolDurationMs = 0;
-                    // R-04: Extract responseId from assistant message (optional -- not all providers supply it)
+                    // Extract responseId from assistant message (optional -- not all providers supply it)
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary
                     const responseId = assistantMsg?.responseId;
                     if (assistantMsg && "usage" in assistantMsg && assistantMsg.usage) {
@@ -421,7 +433,7 @@ export function createPiEventBridge(deps) {
                         if (deps.onTurnWithCacheWrite) {
                             deps.onTurnWithCacheWrite(cacheWriteTokens);
                         }
-                        // Cache break detection Phase 2 (all providers, unconditional)
+                        // Cache break detection (all providers, unconditional)
                         // MUST NOT guard with cacheReadTokens > 0 -- complete cache misses (drop to 0) must be detected
                         if (deps.checkCacheBreak) {
                             // Detect API errors -- zero usage with error stop reason
@@ -451,7 +463,7 @@ export function createPiEventBridge(deps) {
                                 }
                             }
                         }
-                        // R-08: Extract cacheCreation breakdown (future upstream -- runtime check)
+                        // Extract cacheCreation breakdown (future upstream -- runtime check)
                         const rawUsage = usage;
                         const cacheCreation = rawUsage.cacheCreation && typeof rawUsage.cacheCreation === "object"
                             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary
@@ -472,7 +484,7 @@ export function createPiEventBridge(deps) {
                         }
                         // Record usage in budget guard (token-based, not cost-based -- stays before correction)
                         deps.budgetGuard.recordUsage(usage.totalTokens);
-                        // 49-01 + COST-FIX ordering: Normalize TTL split estimates BEFORE cost correction.
+                        // COST-FIX ordering: Normalize TTL split estimates BEFORE cost correction.
                         // The injector provides raw per-TTL estimates; normalize so they sum to the
                         // SDK-reported total (eliminates the 28% estimation error).
                         // Mutate in-place so per-TTL cost and accumulation use normalized values.
@@ -551,10 +563,10 @@ export function createPiEventBridge(deps) {
                         if (deps.onTurnCacheSavings) {
                             deps.onTurnCacheSavings(savedVsUncached);
                         }
-                        // 1.3: Accumulate session-cumulative costs alongside per-turn values
+                        // Accumulate session-cumulative costs alongside per-turn values
                         m.sessionCumulativeCostUsd += cost.total;
                         m.sessionCumulativeCacheSavedUsd += savedVsUncached;
-                        // 1.5: Track thinking tokens from SDK usage object.
+                        // Track thinking tokens from SDK usage object.
                         // The pi-ai SDK Usage type does not have a dedicated thinking/reasoning field,
                         // but future versions or raw API responses may include `reasoningTokens`.
                         // Runtime-check the raw usage object for this field.
@@ -567,9 +579,9 @@ export function createPiEventBridge(deps) {
                                 m.totalThinkingTokens += sdkThinkingTokens;
                             }
                         }
-                        // 49-01: Populate cacheCreation from bridge metrics TTL split when SDK doesn't provide it.
-                        // SDK-sourced cacheCreation (from R-08 extraction) takes priority; bridge metrics
-                        // provide the fallback when pi-ai doesn't surface per-TTL breakdown.
+                        // Populate cacheCreation from bridge metrics TTL split when SDK doesn't provide it.
+                        // SDK-sourced cacheCreation takes priority; bridge metrics provide the fallback
+                        // when pi-ai doesn't surface per-TTL breakdown.
                         const effectiveCacheCreation = cacheCreation ?? ((m.totalCacheWrite5mTokens > 0 || m.totalCacheWrite1hTokens > 0)
                             ? { shortTtl: m.totalCacheWrite5mTokens, longTtl: m.totalCacheWrite1hTokens }
                             : undefined);
@@ -844,7 +856,7 @@ export function createPiEventBridge(deps) {
                     break;
                 }
                 // -----------------------------------------------------------------
-                // SDK auto-retry loop: abort on rate_limited (260501-dkl)
+                // SDK auto-retry loop: abort on rate_limited
                 // -----------------------------------------------------------------
                 case "auto_retry_start": {
                     const errorMessage = event.errorMessage ?? "";
@@ -854,7 +866,7 @@ export function createPiEventBridge(deps) {
                     const classification = classifyError(new Error(errorMessage));
                     if (classification.category === "rate_limited") {
                         deps.logger.info({
-                            module: "agent.bridge.auto-retry-abort",
+                            submodule: "bridge.auto-retry-abort",
                             attempt,
                             maxAttempts,
                             delayMs,
@@ -884,20 +896,20 @@ export function createPiEventBridge(deps) {
                         hint: "Check LLM provider status",
                         errorKind: "dependency",
                     }, "LLM call returned error");
-                    // 260428-iag wire-edge diagnostic: when the LLM error matches the
-                    // Anthropic signed-replay rejection signature ("thinking blocks ...
-                    // cannot be modified"), diff the in-memory content against the
-                    // persisted JSONL canonical and emit one ERROR per divergent block.
-                    // Fully async / fire-and-forget — never blocks the existing error
-                    // path. Silent no-op when the signature doesn't match or when
-                    // either getSessionMessages / getSessionJsonlPath is unwired.
+                    // Wire-edge diagnostic: when the LLM error matches the Anthropic
+                    // signed-replay rejection signature ("thinking blocks ... cannot
+                    // be modified"), diff the in-memory content against the persisted
+                    // JSONL canonical and emit one ERROR per divergent block. Fully
+                    // async / fire-and-forget — never blocks the existing error path.
+                    // Silent no-op when the signature doesn't match or when either
+                    // getSessionMessages / getSessionJsonlPath is unwired.
                     //
-                    // 260428-j0v: ALWAYS emit ONE dispatch-decision INFO log carrying
-                    // boolean flags that explain WHY the wire-diff dispatch was or was
-                    // not entered (regex match, candidate count, callback presence) —
-                    // even when regexMatched is false or callbacks are unwired. When
-                    // the dispatch IS entered, emit a second dispatch-completion INFO
-                    // after the async candidates loop completes.
+                    // ALWAYS emit ONE dispatch-decision INFO log carrying boolean flags
+                    // that explain WHY the wire-diff dispatch was or was not entered
+                    // (regex match, candidate count, callback presence) — even when
+                    // regexMatched is false or callbacks are unwired. When the dispatch
+                    // IS entered, emit a second dispatch-completion INFO after the
+                    // async candidates loop completes.
                     //
                     // The signature regex matches Anthropic's actual 400 message:
                     // "messages.N.content.M: thinking blocks cannot be modified"
@@ -936,7 +948,7 @@ export function createPiEventBridge(deps) {
                         }
                         const jsonlPathPresent = typeof jsonlPathForDecision === "string" && jsonlPathForDecision.length > 0;
                         deps.logger.info({
-                            module: "agent.bridge.wire-diff",
+                            submodule: "bridge.wire-diff",
                             regexMatched,
                             candidatesFound: candidates.length,
                             jsonlPathPresent,
@@ -969,7 +981,7 @@ export function createPiEventBridge(deps) {
                                         totalDivergences += entries.length;
                                         for (const entry of entries) {
                                             deps.logger.error({
-                                                module: "agent.bridge.wire-diff",
+                                                submodule: "bridge.wire-diff",
                                                 responseId: c.responseId,
                                                 blockIndex: entry.blockIndex,
                                                 persistedHash: entry.persistedHash,
@@ -991,7 +1003,7 @@ export function createPiEventBridge(deps) {
                                 // ALWAYS emit the completion INFO, even on totalDivergences=0
                                 // or when every helper call hit a read error.
                                 deps.logger.info({
-                                    module: "agent.bridge.wire-diff",
+                                    submodule: "bridge.wire-diff",
                                     candidatesProcessed,
                                     totalDivergences,
                                     persistedNotFound,
@@ -1031,9 +1043,9 @@ export function createPiEventBridge(deps) {
         m.ghostCostUsd += estimated.costUsd;
         m.timedOutRequests += 1;
     };
-    // 260428-hoy: typed ReadonlyMap accessor for the executor's pre-call
-    // closure. Returns views over the live maps -- the executor never receives
-    // the mutable `m` object itself.
+    // Typed ReadonlyMap accessor for the executor's pre-call closure.
+    // Returns views over the live maps -- the executor never receives the
+    // mutable `m` object itself.
     const getThinkingBlockStores = () => ({
         hashes: m.thinkingBlockHashes,
         canonical: m.thinkingBlockCanonical,

package/node_modules/@comis/agent/dist/bridge/thinking-block-hash-invariant.d.ts

@@ -3,9 +3,8 @@
  *
  * Observed problem: Anthropic 400 `messages.N.content.M: thinking/redacted_thinking
  * blocks cannot be modified` errors keep firing in production even after the
- * surrogate-guard, drift-scrubber, and signed-replay-detector layers shipped
- * (260425-rvm), and even after the immutable-section redirect (260425-t40).
- * Trace `c7b91328-9dc5-4618-9ae8-ca207b4b93df` on 2026-04-28 hit a 400 ~2.2s
+ * surrogate-guard, drift-scrubber, and signed-replay-detector layers shipped,
+ * and even after the immutable-section redirect. A trace hit a 400 ~2.2s
  * after `turn_end` -- meaning *some other layer* mutates a signed thinking
  * block between the assistant turn and the next replay. We don't know which.
  *
@@ -23,12 +22,12 @@
  * - NEVER mutates inputs. Pure read; only output is the structured log.
  * - NEVER alters request flow. The mismatch is observable signal only --
  *   Anthropic's 400 still surfaces through the existing error path
- *   (signed-replay-detector -> executor-prompt-runner). Bug A behavior fix
- *   is a separate quick task gated on what this diagnostic reveals.
+ *   (signed-replay-detector -> executor-prompt-runner). The behavior fix
+ *   for the underlying bug is gated on what this diagnostic reveals.
  *
  * Logging surface follows CLAUDE.md canonical Pino fields:
  * - object-first signature: `error({...fields}, "msg")`
- * - `module: "agent.bridge.hash-invariant"`
+ * - `submodule: "bridge.hash-invariant"` (parent logger binds `module: "agent"`)
  * - `errorKind: "internal"` (classification per AGENTS.md §2.1)
  * - `hint`: actionable next step for the on-call diagnoser
  * - `responseId`, `blockIndex`, `oldHash`, `newHash`,
@@ -137,7 +136,7 @@ export interface RestoreResult {
  * Never throws. On any unexpected error during the walk (e.g. malformed
  * canonical entry whose getter throws), the entire result is `{ messages:
  * <input ref>, restoredCount: 0, affectedResponseIds: [] }` and ONE WARN log
- * fires with `module: RESTORE_MODULE_FIELD, errorKind: "internal"`.
+ * fires with `submodule: RESTORE_SUBMODULE_FIELD, errorKind: "internal"`.
  */
 export declare function restoreCanonicalThinkingBlocks(messages: ReadonlyArray<unknown> | undefined | null, canonicalStore: ReadonlyMap<string, ReadonlyArray<unknown>>, deps?: RestoreDeps): RestoreResult;
 export declare const WIRE_DIFF_HINT_FILE_MISSING: string;