comisai 1.0.42 → 1.0.44

package/node_modules/@comis/agent/dist/executor/executor-input-guard.js

@@ -12,6 +12,18 @@
  * @module
  */
 import { formatSessionKey, } from "@comis/core";
+/**
+ * GIANT-INPUT-WEDGE guard (30uc-20260624 UC-09): the default maximum inbound user-message
+ * size, in characters, processed by a single turn. A message larger than this is rejected
+ * honestly BEFORE the jailbreak scan + the downstream tokenize / LCD-ingest / embed path —
+ * a multi-MB message otherwise drives O(words) synchronous work (the scan's typoglycemia
+ * split+loop) plus multi-MB tokenization/ingest that BLOCKS the Node event loop for minutes,
+ * freezing the entire daemon (gateway unresponsive, all sessions hung; live: a 4.5MB message
+ * wedged the daemon 8.5+ min). 1,000,000 chars (~250K tokens) is the largest input empirically
+ * confirmed to process WITHOUT wedging; the context engine still handles large-but-within-cap
+ * inputs (and the multi-turn `context_exhausted` path is unaffected — this is a per-message cap).
+ */
+export const DEFAULT_MAX_INPUT_CHARS = 1_000_000;
 /**
  * Run validation, jailbreak scoring, and
  * progressive cooldown. Returns an InputGuardResult
@@ -21,7 +33,28 @@ import { formatSessionKey, } from "@comis/core";
  */
 export function validateInput(params) {
     const { msg, sessionKey, agentId, inputValidator, inputGuard, rateLimiter, eventBus, logger, clock } = params;
+    const maxInputChars = params.maxInputChars ?? DEFAULT_MAX_INPUT_CHARS;
     let safetyReinforcement;
+    // GIANT-INPUT-WEDGE (30uc UC-09): reject an over-cap message BEFORE the jailbreak scan AND the
+    // downstream tokenize/LCD-ingest/embed. A multi-MB message drives O(words) sync work that blocks
+    // the Node event loop for minutes (the whole daemon freezes). This early-return keeps the gateway
+    // responsive and the failure HONEST + reason-coded; the context engine handles within-cap inputs.
+    // `msg.text` is optional (a media-only message / some internal paths carry no text) — guard the
+    // length read so the size cap never NPEs a text-less message (the `?? 0` short-circuits to a no-op).
+    const inputChars = msg.text?.length ?? 0;
+    if (inputChars > maxInputChars) {
+        logger.warn({
+            chars: inputChars,
+            limit: maxInputChars,
+            hint: `Inbound message exceeds the ${maxInputChars}-char cap; rejected before processing to keep the daemon responsive (GIANT-INPUT-WEDGE)`,
+            errorKind: "validation",
+        }, "Inbound message exceeds size cap — rejected before processing");
+        return {
+            passed: false,
+            earlyResponse: `Your message is too large (${inputChars.toLocaleString()} characters; the limit is ${maxInputChars.toLocaleString()}). Please send a shorter message or split it into parts.`,
+            earlyFinishReason: "input_too_large",
+        };
+    }
     // Structural validation
     if (inputValidator) {
         const validation = inputValidator(msg.text);
@@ -127,7 +160,7 @@ export function validateInput(params) {
                         agentId: agentId ?? "unknown",
                         tenantId: sessionKey.tenantId,
                         actionType: "injection_rate_exceeded",
-                        classification: "security",
+                        kind: "injection_rate_exceeded",
                         outcome: "failure",
                         metadata: {
                             userId: sessionKey.userId,

package/node_modules/@comis/agent/dist/executor/executor-post-execution.d.ts

@@ -14,15 +14,18 @@
  */
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { CacheRetention } from "@earendil-works/pi-ai";
-import { type SessionKey, type NormalizedMessage, type PerAgentConfig, type TypedEventBus, type MemoryPort, type ClockPort } from "@comis/core";
-import type { ComisLogger } from "@comis/core";
+import { type SessionKey, type NormalizedMessage, type PerAgentConfig, type TypedEventBus, type MemoryPort, type ClockPort, type ContextStorePort } from "@comis/core";
+import type { ComisLogger, ErrorKind } from "@comis/core";
 import { drainAt, markRead, markConsumed, formatDrainKey, type DrainKey, type DrainInflightState } from "./drain-helper.js";
 import type { ActiveRunRegistry } from "./active-run-registry.js";
 import type { ComisSessionManager, SessionMetadata } from "../session/comis-session-manager.js";
+import { type SessionHealthRollup } from "./session-health-rollup.js";
+import type { LeafSummarizerDeps, CompactionModelSnapshot } from "../context-engine/lcd-leaf-summarizer.js";
 import type { ExecutionResult, ExecutionOverrides } from "./types.js";
 import type { ExecutionPlan } from "../planner/types.js";
 import type { ContextEngine } from "../context-engine/index.js";
 import type { DiscoveryTracker } from "./discovery-tracker.js";
+import type { CapabilityClass } from "./model-profile.js";
 /** Bridge result interface used by post-execution. */
 export interface PostExecutionBridgeResult {
     tokensUsed?: {
@@ -43,6 +46,9 @@ export interface PostExecutionBridgeResult {
     toolCallHistory?: string[];
     finishReason?: ExecutionResult["finishReason"];
     lastActiveToolName?: string;
+    /** The last LLM error message the bridge captured (HR-01 mid-turn path) —
+     *  Issue-6 reads the `[cause: …]` tag from it when errorContext is absent. */
+    lastLlmErrorMessage?: string;
     failedToolCalls?: number;
     failedTools?: string[];
     cumulativeLlmDurationMs?: number;
@@ -56,6 +62,30 @@ export interface PostExecutionBridgeResult {
     cacheWrite1hTokens?: number;
     /** Session-cumulative total cost across all turns (USD). */
     sessionCostUsd?: number;
+    /** Per-tool execution results carrying the classified errorKind (Plan 01) —
+     *  the rollup's failure source for toolStats + topErrorKinds (D5/F1). */
+    toolExecResults?: Array<{
+        toolName: string;
+        success: boolean;
+        durationMs: number;
+        errorText?: string;
+        errorKind?: ErrorKind;
+    }>;
+    /** How many times a tool circuit breaker opened this session (Plan 01). */
+    breakerTripCount?: number;
+    /** Turn count for the session:summary event (Plan 02/F2). */
+    turnCount?: number;
+    /**
+     * The SDK-normalized stop reason of the session's FINAL turn (QT3). The bridge
+     * captures `AssistantMessage.stopReason` at EVERY `turn_end`
+     * (pi-event-bridge.ts), so the value carried here is the TERMINAL one. Its
+     * union is `"stop" | "length" | "toolUse" | "error" | "aborted"` (pi-ai) — a
+     * terminal `"length"` is the output-cap truncation the chokepoint promotes to
+     * `finishReason:"output_starved"` (see {@link promoteOutputStarved}). Already
+     * returned by `buildBridgeResult`; surfaced on this interface so the chokepoint
+     * can read it without a second source.
+     */
+    lastStopReason?: string;
     /** Session-cumulative cache savings across all turns (USD). */
     sessionCacheSavedUsd?: number;
     /** Thinking tokens from SDK reasoningTokens field. */
@@ -71,6 +101,20 @@ export interface PostExecutionBridgeResult {
      *  bridge-result shape get a coherent type). */
     signatureScrubs?: number;
     signatureScrubsToolCallsAffected?: number;
+    /** Number of turns flagged as `warmupTurn` (cacheReadTokens === 0 && cacheWriteTokens > 0). */
+    warmupTurnCount?: number;
+    /** Positive-signed sum of pending cache investment across warmup turns (USD). */
+    totalPendingCacheInvestmentUsd?: number;
+    /** Cumulative SDK→corrected cost delta across all turns (USD).
+     *  Conditionally emitted on the Execution-complete log when > 0 — mirrors
+     *  the per-event `costCorrection` breadcrumb gate in pi-event-bridge.ts. */
+    totalCostCorrectionDeltaUsd?: number;
+    /** R2 (Phase 153): abort-redirect message set at bridge abort sites
+     *  (max_steps, budget_exceeded, loop_detected, …). When present and the
+     *  turn did not finish with "stop", post-execution replaces the response
+     *  so a weak executive never free-associates after an abort. Mirrors
+     *  bridge-metrics.ts BridgeResult.abortResponse. */
+    abortResponse?: string;
 }
 /** Bridge interface used by post-execution. */
 export interface PostExecutionBridge {
@@ -98,6 +142,9 @@ export interface PostExecutionParams {
     };
     config: PerAgentConfig;
     msg: NormalizedMessage;
+    /** USER.md preferred language (DET-02 tier-2), threaded from prompt assembly.
+     *  Consumed by the degraded-reply resolver (GEN-02, wired in 181-03). */
+    userMdLanguage?: string;
     sessionKey: SessionKey;
     formattedKey: string;
     /** Resolver-aligned key for activeRunRegistry.deregister. Must match the
@@ -107,6 +154,19 @@ export interface PostExecutionParams {
     executionStartMs: number;
     executionId: string;
     executionOverrides: ExecutionOverrides | undefined;
+    /** Recalled memories (id + content) for turn-end attribution. Consumed
+     *  IN-PROCESS by the overlap heuristic here; content NEVER logged/emitted (only
+     *  ids/counts cross the bus). Absent ⇒ no attribution (default-off / no recall). */
+    recalledMemories?: ReadonlyArray<{
+        id: string;
+        content: string;
+    }>;
+    /** ATTR-02: the per-turn skill ids attributed by ATTR-01 (skillNames whose
+     *  frozen `<location>` a `read` matched), read back from the bridge's named
+     *  carrier. When non-empty, postExecution emits the counts/ids-only
+     *  `memory:skill_used` write-back (the daemon Plan 07 consumes it). Absent /
+     *  empty ⇒ no emit (byte-identical to pre-patch). Ids only — never bodies. */
+    usedSkillIds?: ReadonlyArray<string>;
     bridge: PostExecutionBridge;
     unsubscribe: () => void;
     contextEngineRef: {
@@ -135,11 +195,20 @@ export interface PostExecutionParams {
     executionPlanRef: {
         current: ExecutionPlan | undefined;
     };
-    sepEnabled: boolean;
     isOnboarding: boolean;
     geminiCacheHit: boolean;
     geminiCachedTokens: number;
-    modelTier: string | undefined;
+    capabilityClass: CapabilityClass | undefined;
+    /**
+     * SUMW-02: the turn's budget window — computeTokenBudgetForProfile().windowTokens
+     * = min(reconciled contextWindow, capability class cap). MUST be computed
+     * UPSTREAM (pi-executor threads it off the tool-assembly result): this module
+     * has no real ModelProfile (only a synthetic scaffold profile), so it can never
+     * re-derive the value. Threaded into BOTH LCD after-turn triggers as the
+     * REQUIRED utilization denominator — a captured number, dispose-safe on the
+     * deferred (C4) path by construction.
+     */
+    budgetWindowTokens: number;
     /**
      * Provider used for this execution. Sourced from `resolvedModel.provider` in
      * pi-executor when available; falls back to `config.provider` when the
@@ -167,6 +236,23 @@ export interface PostExecutionParams {
         eventBus: TypedEventBus;
         logger: ComisLogger;
         memoryPort?: MemoryPort;
+        /** Optional LCD context store (Phase 128 dag-mode write-path, A1). Present
+         *  ⇒ the turn's NEW messages are ingested at afterTurn; absent ⇒ skipped
+         *  cleanly. TYPE-only core port (the agent↛memory cut). */
+        contextStore?: ContextStorePort;
+        /** Tenant id for the LCD ingest scope. Threaded from PiExecutorDeps.tenantId
+         *  at the call site so the scope's SECURITY column is never empty
+         *  (T-128-08). Falls back to the session key tenant when absent. */
+        tenantId?: string;
+        /** Getter for the leaf-summarizer deps (Phase 129, C1). Present ⇒ the
+         *  afterTurn leaf pass is wired live (over threshold ⇒ a leaf summary is
+         *  persisted); absent ⇒ the pass is gated off cleanly. Sourced from the
+         *  context-engine setup's getCompactionDeps-style getters; TYPE-only (the
+         *  agent↛memory cut — the LLM call lives behind the injected summarizer).
+         *  Accepts an optional `modelSnapshot`: the DEFERRED (C4) path passes a model
+         *  identity captured BEFORE `session.dispose()` so a detached pass never
+         *  re-reads a torn-down `session.agent.state` (WR-04). */
+        getSummarizerDeps?: (modelSnapshot?: CompactionModelSnapshot) => LeafSummarizerDeps;
         activeRunRegistry?: ActiveRunRegistry;
         embeddingEnqueue?: (entryId: string, content: string) => void;
         workspaceDir: string;
@@ -201,6 +287,171 @@ export declare function shouldStorePairedMemory(userText: string, agentResponse:
 export declare function isDuplicatePairedMemory(content: string, agentId: string, clock: ClockPort): boolean;
 /** Reset the paired-memory dedup cache. Exported for unit tests. */
 export declare function resetPairedMemoryDedupForTests(): void;
+/** Minimal logger surface the paired-store helper needs (debug/warn only). */
+interface PairedStoreLogger {
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+}
+/** Args for {@link storePairedConversationMemory}. */
+export interface StorePairedConversationMemoryArgs {
+    memoryPort: MemoryPort;
+    /** The built "[user] …\n[agent] …" paired content (already quality-gated + deduped). */
+    pairedContent: string;
+    effectiveAgentId: string;
+    sessionKey: {
+        tenantId: string;
+        userId: string;
+    };
+    channelType: string | undefined;
+    formattedKey: string;
+    now: number;
+    logger: PairedStoreLogger;
+    /** Embedding enqueue (vector-index recall path). Omitted ⇒ no embedding. */
+    embeddingEnqueue?: (entryId: string, content: string) => void;
+}
+/**
+ * Persist a paired-conversation memory through the secret-egress firewall.
+ *
+ * SECURITY (FIX 1): the paired-conversation write is the highest-volume memory
+ * path (every qualifying turn) and was the ONLY agent-visible memory write that
+ * bypassed `validateMemoryWrite`. A user who pasted a secret into chat had it
+ * written VERBATIM to the `memories` table AND embedded into the vector index —
+ * recallable across sessions — even though the explicit `memory_store` tool
+ * refuses it (cosmetic for data-at-rest). The DERIVED-memory writes
+ * (user-representation, consolidation) all run `validateMemoryWrite`
+ * FIRST; this helper applies the SAME guard to the paired write for parity.
+ *
+ * `validateMemoryWrite` REJECTS (returns severity `critical`) when the secret-
+ * egress scan finds a redaction — it does NOT scrub-and-return content. So a
+ * non-`clean` verdict SKIPS the write (no row, no embedding) with a CONTENT-FREE
+ * WARN, byte-identical to the user-representation path
+ * (memory-user-representation-job.ts:390-406): the high-trust `learned` floor has
+ * no reduced-weight tier to down-store a `warn` into, so both `warn` AND
+ * `critical` are skipped, not downgraded. Non-secret content stores unchanged.
+ *
+ * The skip log is CONTENT-FREE (Pino redaction / AGENTS.md §2.7): the planted
+ * secret value never appears in any field — only `severity` + `patterns` (the
+ * verdict's pattern-source tags, e.g. `secret-egress-guard`, never the matched
+ * text) + an actionable hint.
+ *
+ * Non-fatal: a store error is logged (dependency) and swallowed — execution never
+ * fails due to a memory write. Exported for unit tests (the secret-egress gate is
+ * unit-tested with a mock memoryPort capturing `.store` inputs; scaffolding all
+ * 30+ postExecution deps is impractical).
+ */
+export declare function storePairedConversationMemory(args: StorePairedConversationMemoryArgs): Promise<void>;
+/**
+ * Decide whether the LCD afterTurn store passes (ingest + leaf + condense) run
+ * for this turn, based on the agent's effective context-engine version.
+ *
+ * The daemon injects the LCD ContextStorePort UNCONDITIONALLY
+ * (setup-agents-runtime.ts), but ONLY the dag engine READS the store: the
+ * assembler's dag branch (context-engine.ts — gated `version === "dag"`) and the
+ * ctx_* expansion tools (setup-tools.ts — gated `version === "dag" && lcdStore`).
+ * A pipeline agent therefore must NOT write `lcd_messages` or fire leaf/condense
+ * LLM summarization — that work is pure wasted cost + latency because nothing
+ * reads it.
+ *
+ * Symmetry with the read side: the executor resolves an ABSENT
+ * `config.contextEngine` via `ContextEngineConfigSchema.parse({})`, whose
+ * `version` defaults to "dag" (executor-context-engine-setup.ts). So an absent
+ * contextEngine (and an absent `version` within a present contextEngine) is
+ * treated as dag — exactly what the assembler does — and only an EXPLICIT
+ * `version: "pipeline"` skips the passes. This keeps write and read in agreement
+ * and makes the dag default flip non-breaking. The gate reads per-turn config,
+ * so flipping an agent pipeline→dag later takes effect on the very next turn (the
+ * first dag turn catches up via the ingest delta from an empty store).
+ *
+ * Pure: no I/O, no side effects. Exported for unit tests.
+ */
+export declare function shouldRunLcdStorePasses(config: {
+    contextEngine?: {
+        version?: "pipeline" | "dag";
+    };
+}): boolean;
+/**
+ * Map an SDK finishReason to the SessionMetadata.sessionEnd.endReason enum.
+ *
+ * SINGLE SOURCE OF TRUTH for the run's terminal classification: the rollup's
+ * `degraded` flag (session-health-rollup.ts) is derived from the value this map
+ * yields (degraded := mapped endReason !== "success"), so `endReason` and
+ * `degraded` are computed from the SAME table and cannot diverge (Phase 152
+ * CR-01/WR-01). Exported so the chokepoint maps once and the unit tests can
+ * enumerate the finishReason union against it.
+ *
+ * Every KNOWN, in-union `ExecutionResult.finishReason` is listed EXPLICITLY —
+ * including `loop_detected` (turn-loop-detector abort) and `session_reset`,
+ * which reach the rollup verbatim and previously relied on the `?? "error"`
+ * fallthrough (WR-02). The fallthrough is now reserved for its stated purpose:
+ * a defensive bucket for UNKNOWN provider strings we haven't classified yet,
+ * not a silent home for classified in-union reasons. Module-level so the
+ * post-execution path doesn't reallocate it on every turn.
+ *
+ * NOTE: the endReason union's "timeout" literal — dead since the union was
+ * written — is ALIVE as of LAT-04 (Phase 177): the `prompt_timeout` entry
+ * below is its ONLY source. The WR-02 test that pinned its unreachability
+ * became a positive pin (prompt_timeout → "timeout", sole source): the
+ * negative pin existed to prevent ACCIDENTAL re-introduction; this mapping
+ * is the deliberate one.
+ *
+ * QT2/QT3 — NAMED degradation causes (Glass Box degradation detectors). The
+ * taxonomy used to FLATTEN context-exhaustion into the generic "error" bucket,
+ * so obs.explain / obs.fleet.health could not tell a context-exhausted session
+ * from a tool crash. The two related context-exhaustion finish reasons —
+ * `context_exhausted` (the bridge's hard context-window-guard abort,
+ * bridge-safety-controls.ts) and `context_loop` (the loop-on-exhaustion abort) —
+ * now FOLD into ONE named cause `"context_exhausted"`. `output_starved` (the
+ * chokepoint promotes a terminal output-cap truncation, QT3) is its own named
+ * cause `"output_starved"`. Both are degraded by construction (≠ "success", so
+ * session-health-rollup's CLEAN_END_REASONS derives degraded:true unchanged).
+ */
+export declare const END_REASON_MAP: Record<string, NonNullable<SessionMetadata["sessionEnd"]>["endReason"]>;
+/**
+ * QT3 — promote a PATHOLOGICAL terminal output truncation to the named cause.
+ *
+ * Returns `"output_starved"` IFF the run would OTHERWISE end clean
+ * (`stop`/`end_turn` → `success`) AND the session's FINAL turn stopped at the
+ * model output cap (`lastStopReason ∈ {length, max_tokens}`). Otherwise it
+ * returns `effectiveFinishReason` UNCHANGED.
+ *
+ * This is deliberately conservative — the hard rule is "do not flag healthy
+ * sessions" (the spike's load-bearing guard):
+ *   - It fires ONLY on a CLEAN would-be terminal. A run that already settled on
+ *     a non-clean cause (tool errors, budget, breaker, context_exhausted, error)
+ *     keeps that upstream cause — the truncation is not the headline there.
+ *   - It keys on the TERMINAL stop reason. `m.lastStopReason` is overwritten at
+ *     every `turn_end` (pi-event-bridge.ts), so a mid-run length-stop the agent
+ *     CONTINUED past (output escalation re-ran, or another turn followed) carries
+ *     a NON-length terminal value (`stop`/`end`/`toolUse`) by the time it reaches
+ *     here and is correctly NOT flagged. Only a run whose LAST turn was cut off
+ *     at the cap — with nothing after it — qualifies.
+ *
+ * Pure: no I/O, no side effects. Exported for unit tests (both directions pinned).
+ *
+ * @param effectiveFinishReason - the settled finish reason at the chokepoint
+ *   (already reconciled for tool failures → completed_with_tool_errors).
+ * @param lastStopReason - the bridge's terminal `AssistantMessage.stopReason`.
+ */
+export declare function promoteOutputStarved(effectiveFinishReason: string, lastStopReason: string | undefined): string;
+/**
+ * Issue-4 (small-model e2e 2026-06-12) — promote a narrate-without-emit
+ * terminal to the named cause `narration_stall`.
+ *
+ * Fires IFF the run would OTHERWISE end clean (`stop`/`end_turn`) AND the
+ * narrate-nudge FIRED for this turn but did NOT recover a real answer — the
+ * delivered response is still mid-task narration ("Now let me run the
+ * tool:") with no tool call behind it. Such a turn was previously recorded
+ * `degraded:false, endReason:success` (the soft false-clean: live session
+ * uc4-uc5-35). Mirrors {@link promoteOutputStarved}'s conservative shape:
+ * an already-non-clean cause always wins, and a recovered (or never-fired)
+ * nudge changes nothing.
+ *
+ * Pure. Exported for unit tests (both directions pinned).
+ */
+export declare function promoteNarrationStall(effectiveFinishReason: string, narrateNudge: {
+    fired: boolean;
+    recovered: boolean;
+} | undefined): string;
 /**
  * Build the SessionMetadata payload written to `_session-metadata.json` at the
  * end of an execution.
@@ -226,8 +477,114 @@ export declare function buildSessionEndMetadata(args: {
     totalTokens: number;
     executionId: string;
     traceId: string | undefined;
+    /** T1.4 (F5): the formatted session key, stored so the metadata can drive `comis explain`. */
+    sessionKey: string;
     clock: ClockPort;
+    /** F1 health rollup (D5) — the 5 fields spread onto sessionEnd. Computed once
+     *  at the chokepoint via buildSessionHealthRollup so this builder stays pure. */
+    rollup: SessionHealthRollup;
 }): SessionMetadata;
+/**
+ * F2 emit: announce `session:summary` on the eventBus once per execution.
+ *
+ * The payload carries ids + counts + typed flags PLUS `topErrorKinds` and
+ * `source` (Phase 159 A1/A2 — OQ1 reversed): both are threaded into the
+ * persisted `obs_diagnostics` row so the fleet aggregate
+ * (`aggregateSessionsInWindow`) can read them without opening per-session
+ * `_session-metadata.json`. Production emits the constant `source: "runtime"`;
+ * a synthetic/test row is produced by a caller injecting `source: "test"`.
+ * Fire-and-forget by contract: the eventBus is SYNCHRONOUS, so a throwing
+ * in-process listener would otherwise abort the caller's teardown (OQ3). The
+ * try/catch here is the sanctioned telemetry guard (mirrors the `:983`
+ * `writeSessionMetadata` guard) — a telemetry failure must never break execution.
+ */
+export declare function emitSessionSummary(deps: {
+    eventBus?: TypedEventBus;
+    logger?: ComisLogger;
+}, args: {
+    sessionKey: string;
+    agentId: string;
+    traceId: string;
+    turnCount: number;
+    rollup: SessionHealthRollup;
+    /** The mapped endReason (named degradation cause) — the SAME value derived
+     *  once at the chokepoint via END_REASON_MAP and co-persisted on sessionEnd.
+     *  Carried so the row feeds the fleet `degradedByCause` aggregate (QT2/QT3). */
+    endReason: string;
+    clock: ClockPort;
+}): void;
+/**
+ * WR-04 lifetime guard for the DEFERRED (C4) compaction path.
+ *
+ * The deferred leaf/condense passes are enqueued DETACHED onto the per-conversation
+ * serializer and can run AFTER `postExecution` returns + `session.dispose()` tears
+ * the session down. Each pass resolves its summarizer deps WHEN IT RUNS, and the
+ * model getter (and the `buildLeafSummarizeFn`-internal model read) re-read
+ * `session.agent.state.model` (executor-context-engine-setup.ts) — a use-after-
+ * dispose if the SDK dispose nulls that state.
+ *
+ * This helper SNAPSHOTS the model identity ONCE, NOW (while the session is still
+ * alive — called from `postExecution` BEFORE it returns/disposes), then re-binds
+ * the getter so every later resolution passes that snapshot into `getSummarizerDeps`.
+ * Because the snapshot threads into `resolveCompactionModelChain`, BOTH the top-level
+ * `getModel` AND the summarizer's internal model read use the captured value — the
+ * detached pass NEVER re-reads `session.agent.state`. The captured model is the
+ * turn's own model (the correct one for compacting that turn's history), and the
+ * lifetime contract is now explicit: the deferred path depends ONLY on this
+ * snapshot + the daemon-owned store/auth/clock (all of which outlive the session),
+ * never on `session.agent.state`.
+ *
+ * Resolving the snapshot is itself wrapped defensively: if reading the live model
+ * throws (an already-disposed/edge session at call time), the helper falls back to
+ * the original getter unchanged (the pass then degrades non-fatally via the
+ * trigger's own try/catch — never a crash). Returns `undefined` when the input is
+ * `undefined` (the leaf pass stays cleanly gated off).
+ *
+ * @param getSummarizerDeps - the live, session-coupled deps getter (or undefined).
+ * @returns a model-snapshot-bound getter safe to call post-dispose (or undefined).
+ */
+export declare function snapshotSummarizerDepsForDefer(getSummarizerDeps: ((modelSnapshot?: CompactionModelSnapshot) => LeafSummarizerDeps) | undefined): ((modelSnapshot?: CompactionModelSnapshot) => LeafSummarizerDeps) | undefined;
+/**
+ * Classify failed tools into the subset that was NOT recovered this turn (HR-01).
+ *
+ * A tool failure is "recovered" when the SAME tool name also has a successful
+ * execution in `toolExecResults` for this turn — e.g. the model retried after a
+ * transient error and the retry succeeded. The user-facing `[tool failure]`
+ * notice must surface only UNRECOVERED failures: a tool that failed and never
+ * succeeded. The live case is the NVDA pipeline — attempt-1 (validation) failed,
+ * attempt-2 launched the graph, yet the user saw "[tool failure] pipeline reported
+ * an error" because the notice keyed off raw failedTools.
+ *
+ * Safe fallback: when `toolExecResults` is absent/empty (success record not
+ * plumbed on some path) every failed tool is reported as unrecovered — i.e. the
+ * pre-HR-01 behavior, so this never HIDES a genuine unrecovered failure.
+ *
+ * Observability is unaffected: effectiveFinishReason / logs / fleet rollup still
+ * record the failure. Only the user-facing reply is gated.
+ *
+ * Pure: no I/O, no side effects. Returns deduped failed names with no same-name success.
+ */
+export declare function unrecoveredFailedToolNames(failedTools: string[], toolExecResults?: Array<{
+    toolName: string;
+    success: boolean;
+}>): string[];
+/**
+ * The COMPLEMENT of {@link unrecoveredFailedToolNames}: failed tools that LATER
+ * succeeded in the same turn — a self-heal (the live case: a `write` rejected on
+ * an absolute /tmp path, then re-run to the workspace and succeeded).
+ *
+ * Surfaced on the execution bookend (`recoveredTools`) so an operator reading
+ * `failedTools:["write"]` + `completed_with_tool_errors` can tell a SELF-HEALED
+ * turn from a terminally-degraded one without diffing the raw per-call
+ * `toolExecResults`. This does NOT change the degraded classification: by the
+ * HR-01 design effectiveFinishReason / the rollup STILL record the failure (the
+ * tool DID error); this only makes the recovery VISIBLE. (hermes-usecases
+ * obs-loop 2026-06-25.) Pure; deduped; empty when nothing was recovered.
+ */
+export declare function recoveredFailedToolNames(failedTools: string[], toolExecResults?: Array<{
+    toolName: string;
+    success: boolean;
+}>): string[];
 export { drainAt, markRead, markConsumed, formatDrainKey, type DrainKey, type DrainInflightState, };
 /**
  * Run post-execution cleanup for a PiExecutor turn.