@arnilo/prism 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-20 (attention budget axes, turn traces, cache-stable disclosure, tool narrowing, guardrail packs, background agents, session search, deterministic turns, shared scopes)
+
+> **Eleven publishable packages.** All 086–098 features ship behind their documented options, joined by the live-stream terminal fix (plan 100). Predecessor published line is **0.8.0**. Registry/tag writes stay operator-authorized.
+
+### Added
+- **Attention budget axes and durable folding.** `attentionCompiler.trigger` accepts `input_ratio` (the legacy axis), `run_input_ratio` (fires against `RunLimits.maxInputTokens` instead of the model window), `token_floor`, and a host predicate, alone or as an any-of array; `attentionCompiler.durable: true` writes the fold ledger and sticky frontier into the checkpoint so a resumed run keeps its stubs. See [docs/attention-compiler.md](docs/attention-compiler.md).
+- **Turn traces and exhaustion attribution.** `provider_turn_finished` carries a closed `stopReason` taxonomy, a `budgets` snapshot, the effective tool menu (`tools.count` / `tools.idsHash`), and provider-reported cache counts with a per-turn `hitRate`; `agent_finished` carries `finishReason` / `stopDetail`, `AgentRunResult.stopReason` names host-policy and loop-ceiling stops, and the execution timeline adds `turns[i].stopReason` plus `timeline.exhaustion`. See [docs/agent-events.md](docs/agent-events.md), [docs/execution-timeline.md](docs/execution-timeline.md).
+- **Cache-stable progressive disclosure and cache metrics.** Skill bodies, deferred tool schemas, and loaded references land at cache-stable positions (append-only tail or explicit invalidation); cache read/write tokens and per-turn hit rate are recorded on usage records and turn events. See [docs/provider-caching.md](docs/provider-caching.md), [docs/prefix-stability-conformance.md](docs/prefix-stability-conformance.md).
+- **Per-turn tool narrowing.** `AgentConfig.toolNarrowing` / `RunOptions.toolNarrowing` returns the effective tool subset before each provider turn; out-of-grant names are dropped and reported on `tool_narrowing_clamped`. See [docs/tools.md](docs/tools.md).
+- **Usage estimation and the context meter.** `estimateMessageTokens` / `MODEL_FAMILY_TOKENS` / `resolveModelFamily` produce labeled `TokenEstimate`s, `AgentConfig.usageEstimation: "fallback"` (default) charges one labeled estimate for usage-less providers, and `session.contextMeter()` exposes `{ inputTokens, source, inputCap?, runInputBudget?, usedRatio? }`. See [docs/runs-and-usage.md](docs/runs-and-usage.md).
+- **Execution guardrail packs.** `guardrailPacks` compiles four built-in restrictive rule sets (`coding-standard`, `destructive-commands`, `validation-respect`, `secrets-hygiene`) onto existing tool stages, each with a trajectory scorer (`createGuardrailPackScorer`). See [docs/guardrails.md](docs/guardrails.md).
+- **Background child agents and child-event passthrough.** `lifetime: "session"`, `report: "on-complete" | "milestones" | "stream"`, `milestone`, and `budgetShare` on `delegate` / `delegateAsync` / `spawn_agent`, with `child_milestone`, `child_failed`, and rate-coalesced child events. See [docs/supervisors.md](docs/supervisors.md), [docs/multi-agent-patterns.md](docs/multi-agent-patterns.md).
+- **Checkpoint sidecar metadata and restore hooks.** A redacted ≤4 KB `checkpointMetadata` map rides every checkpoint record without charging `maxStateBytes`, and `restoreHooks` revert external layers before a resume claims the run. See [docs/durable-runs.md](docs/durable-runs.md).
+- **Bounded workspace session search.** `SessionStore.searchSessions?(query)` over workspace/time/provider/label/kind/ownership filters with an indexed full-text path (SQLite FTS5, Postgres `tsvector`, migration 004) and a shared linear matcher for memory and JSONL stores. See [docs/session-stores.md](docs/session-stores.md).
+- **Deterministic no-model turns.** The `beforeProviderTurn` middleware hook answers a turn from host data (`BeforeProviderTurnPayload` → `DeterministicTurnAnswer`) with no provider request, recorded as `deterministic` on the timeline and graded by `createDeterministicTurnScorer`. See [docs/middleware-hooks.md](docs/middleware-hooks.md).
+- **Shared work scopes for observational memory.** `sharedScopes` at attach time plus owner-branch grants (`grant` / `revoke`) let granted sessions contribute to and read one scope, with deny-by-default rechecks, `onScopeAccess` auditing, and revocation at the next read. See [docs/compaction-observational-memory.md](docs/compaction-observational-memory.md).
+- **Retrieval revocation and a zero-service default reranker.** `createDeletionPropagator` (+ `collectInvalidationIds` / `listInvalidatedIds`, `repointSource`, `retireWikiSources`, RAG/wiki handlers) propagates deletion and revocation through derived artifacts, `createAccessRecheck` rechecks governed sources per query, and `resolveReranker({ kind: "local" })` / `createLocalReranker()` run an in-process cross-encoder behind the `LocalRerankRuntime` seam with no declared inference dependency. See [docs/rag.md](docs/rag.md), [docs/embeddings.md](docs/embeddings.md).
+- **Examples.** `examples/attention-budget-axes.ts`, `examples/tool-narrowing-planes.ts`, `examples/session-search.ts`.
+
+### Changed
+- **Lockstep `0.8.0` → `0.9.0`.** All eleven publishable manifests move together with `^0.9.0` internal ranges; the lockfile, the `src/index.ts` version constant, the docs index banner, the release-workflow tag lists, and the generated package-truth artifact agree (enforced by `scripts/version-literal-gate.test.mjs`).
+- **A limit death no longer ends a stream early.** The terminal set is exactly `agent_finished` / `agent_denied` / `error`, decided by one exported `isTerminalAgentEventType` predicate shared by the memory, NATS, and Postgres sources, AG-UI replay, the A2A stream break, AG-UI `filterRun`, and conversation replay; `run_limit_exceeded` → `budget_exhausted` → `error` now reaches page, subscribe, and replay consumers in order. See [docs/migrate-to-0.9.md](docs/migrate-to-0.9.md).
+- **Usage-less providers are charged a labeled estimate by default.** `AgentConfig.usageEstimation: "fallback"` records one `TokenEstimate` (`estimated: true` + `confidence`) at the existing usage seam; reported usage always wins, and `"off"` keeps the previous zero-for-no-usage behavior.
+- **Compat baselines regenerated at 0.9.0**: `+119` public names with **zero removals** and zero renames (`@arnilo/prism` +49, `@arnilo/prism-memory` +60, `@arnilo/prism-core` +10). One type-level consumer change: the `recordUsage` callback of `generateProviderTurn` / `generateWithRetry` returns `Promise<Usage | undefined>` instead of `Promise<void>`.
+- **Budgets rebaselined with recorded reasons**: root packed/unpacked/file count, per-package export ceilings, and the non-null assertion ratchet carry the measured 0.9.0 values and the plans that moved them.
+- **Migration guide for 0.8.0 hosts**: [docs/migrate-to-0.9.md](docs/migrate-to-0.9.md) — four behavior changes inside existing surfaces, every new option with defaults and sizing lines, upgrade steps, and rollback — indexed from [docs/migration.md](docs/migration.md) and [docs/index.md](docs/index.md).
+
+### Fixed
+- **Streams ended one record early on a run-limit death.** In-memory, NATS, Postgres, and AG-UI replay consumers treated `run_limit_exceeded` as terminal, so a subscriber that stopped at the first breach record never saw the `budget_exhausted` attribution or the terminal `error` (`assertAgentEventSourceConforms` now asserts the delivery order against every source implementation).
+- **Attention folding was inert when the run input cap sat below the model window.** The new `run_input_ratio` axis evaluates cumulative run spend plus the assembled request, so a 500k run cap under a 1M-window model folds instead of dying at the cap.
+- **Unindexed session search could scan an unbounded store.** Memory and JSONL stores share `searchLinearSessions` with contract linear caps, overridable only within their hard bounds.
+
+### Security
+- **Guardrail packs fail closed on secrets and destructive commands.** `secrets-hygiene` scans tool arguments for credential shapes, `destructive-commands` matches shell commands, and `coding-standard` keeps edits inside `options.roots`; every pack is restrictive-only, so a pack can never widen a host policy. Cap: 8 packs, 64 rules per pack.
+- **Shared-scope access is deny-by-default and audited.** Absent, unknown, revoked, unreachable, or not-opened-locally scope state denies the read, every decision reaches `onScopeAccess`, revocation lands on the next read, and the host `entries(sessionId)` callback stays inside one `OwnershipScope`.
+- **Checkpoint metadata and restore hooks are redacted and bounded.** The sidecar map is redacted unconditionally (no public-key exemption) and capped at 4 KiB; a failing or timed-out restore hook aborts the restore rather than claiming the run.
+- **Estimates can never masquerade as provider truth.** Every estimated token count carries `estimated: true` (and `confidence`), reported usage is never overwritten, and estimates never produce a price — a configured `maxCost` stays the fail-closed envelope.
+
 ## [0.8.0] - 2026-09-18 (messaging channels, connected apps, work family, durable runs, honesty gates)
 
 > **Eleven publishable packages.** `@arnilo/prism-channels` is new; `@arnilo/prism-work` replaces `@arnilo/prism-office`. Predecessor published line is **0.7.0**. Registry/tag writes stay operator-authorized.

package/README.md

@@ -162,17 +162,17 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.8.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-channels` | 0.8.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
-| `@arnilo/prism-coding-tools` | 0.8.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.8.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
-| `@arnilo/prism-providers` | 0.8.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.8.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.8.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.8.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.8.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-web-tools` | 0.8.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
-| `@arnilo/prism-work` | 0.8.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
+| `@arnilo/prism` | 0.9.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-channels` | 0.9.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
+| `@arnilo/prism-coding-tools` | 0.9.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.9.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
+| `@arnilo/prism-providers` | 0.9.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.9.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.9.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.9.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.9.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
+| `@arnilo/prism-web-tools` | 0.9.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism-work` | 0.9.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts

package/dist/agent-approval.d.ts

@@ -1,5 +1,6 @@
+import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
 import type { StoredAgentRunState } from "./agent-run-state.js";
-import { Agent, AgentRunResume, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
+import { Agent, AgentRunCheckpointMetadata, AgentRunResume, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
 import type { AgentIdentity } from "./identity.js";
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
 export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly PendingDecision[] | undefined;
@@ -50,7 +51,15 @@ export declare function decisionScopesEqual(a: DecisionScope, b: DecisionScope):
 export declare function nestedOutcomeToolResult(outcome: Exclude<NestedRunOutcome, {
     status: "suspended";
 }>, toolCallId: string, name: string): ToolResult;
-export interface ActiveDurableRun {
+/**
+ * Non-state extras carried into a resumed run: the sidecar metadata seed (so later checkpoint
+ * writes preserve the record's map) and the restore audit emitted on `agent_resumed`.
+ */
+export interface ActiveDurableRunExtras {
+    readonly checkpointMetadata?: AgentRunCheckpointMetadata;
+    readonly restore?: CheckpointRestoreAudit;
+}
+export interface ActiveDurableRun extends ActiveDurableRunExtras {
     readonly options: AgentRunStateOptions;
     state?: StoredAgentRunState;
     version: number;

package/dist/agent-event-source.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEventSource, AgentEventSourceOptions } from "./contracts.js";
+import type { AgentEvent, AgentEventSource, AgentEventSourceOptions } from "./contracts.js";
 export type AgentEventSourceErrorCode = "ERR_PRISM_AGENT_EVENT_SOURCE_INPUT" | "ERR_PRISM_AGENT_EVENT_SOURCE_CURSOR" | "ERR_PRISM_AGENT_EVENT_SOURCE_RETENTION" | "ERR_PRISM_AGENT_EVENT_SOURCE_OVERFLOW" | "ERR_PRISM_AGENT_EVENT_SOURCE_CLOSED";
 export declare class AgentEventSourceError extends Error {
     readonly code: AgentEventSourceErrorCode;
@@ -9,3 +9,11 @@ export declare class AgentEventSourceError extends Error {
  * wakeup or persistence; use a database-backed source for distributed delivery.
  */
 export declare function createMemoryAgentEventSource(options?: AgentEventSourceOptions): AgentEventSource;
+/**
+ * Terminal-set membership for agent event streams: a run's stream ends on its outcome record.
+ *
+ * Attribution records — `run_limit_exceeded` and `budget_exhausted` — are delivered *before* that
+ * outcome (the `error` that follows a run-limit death), so a page, subscription, or replay must
+ * keep reading past them. Every stream-ending site routes through this one predicate.
+ */
+export declare function isTerminalAgentEventType(type: AgentEvent["type"]): boolean;

package/dist/agent-event-source.js

@@ -439,12 +439,19 @@ function positionAfter(records, cursor, stream) {
 }
 function terminalAt(records, after) {
     const last = records.at(-1);
-    if (!last || !isTerminal(last))
+    if (!last || !isTerminalAgentEventType(last.type))
         return false;
     return after === undefined || after.sequence <= last.sequence;
 }
-function isTerminal(record) {
-    return (record.type === "agent_finished" || record.type === "agent_denied" || record.type === "run_limit_exceeded" || record.type === "error");
+/**
+ * Terminal-set membership for agent event streams: a run's stream ends on its outcome record.
+ *
+ * Attribution records — `run_limit_exceeded` and `budget_exhausted` — are delivered *before* that
+ * outcome (the `error` that follows a run-limit death), so a page, subscription, or replay must
+ * keep reading past them. Every stream-ending site routes through this one predicate.
+ */
+export function isTerminalAgentEventType(type) {
+    return type === "agent_finished" || type === "agent_denied" || type === "error";
 }
 function sameRecord(existing, input) {
     const { sequence: _existingSequence, ...existingWithoutSequence } = existing;

package/dist/agent-loops.js

@@ -25,12 +25,14 @@ export const singleShotLoop = {
             ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
             const request = await ctx.assemble(nextInput, undefined, turn);
             throwIfAborted(ctx.signal);
-            const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
+            const { content, calls, messageId, started, usage: turnUsage, metadata: turnMetadata } = await ctx.generate(request);
             usage = turnUsage ?? usage;
             if (turn === 1)
                 ctx.history.push(...ctx.inputMessages);
             if (started) {
-                const message = { id: messageId, role: "assistant", content };
+                // Turn provenance (plan 096): a deterministic answer carries `{ deterministic: { middleware } }`
+                // so the persisted transcript proves the turn had no model behind it.
+                const message = { id: messageId, role: "assistant", content, ...(turnMetadata ? { metadata: turnMetadata } : {}) };
                 ctx.history.push(message);
                 await ctx.appendMessage(message);
                 ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
@@ -140,7 +142,7 @@ export function generateValidateReviseLoop(opts) {
                     }
                 }
                 throwIfAborted(ctx.signal);
-                const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
+                const { content, calls, messageId, started, usage: turnUsage, metadata: turnMetadata } = await ctx.generate(request);
                 usage = turnUsage ?? usage;
                 if (pendingHistory.length > 0) {
                     ctx.history.push(...pendingHistory);
@@ -149,7 +151,8 @@ export function generateValidateReviseLoop(opts) {
                 if (turn === 1)
                     ctx.history.push(...ctx.inputMessages);
                 if (started) {
-                    const message = { id: messageId, role: "assistant", content };
+                    // Same provenance contract as singleShotLoop (plan 096).
+                    const message = { id: messageId, role: "assistant", content, ...(turnMetadata ? { metadata: turnMetadata } : {}) };
                     ctx.history.push(message);
                     await ctx.appendMessage(message);
                     ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });

package/dist/agent-run-lifecycle.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentEvent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunResumeStreamOptions, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
+import type { Agent, AgentCheckpointRestoreHook, AgentEvent, AgentRunCheckpointMetadataSource, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunResumeStreamOptions, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
 export interface AgentRunLifecycleAgent {
     readonly agent: Agent;
     /** Current host-authored revision; it must match the stored revision. */
@@ -12,6 +12,14 @@ export interface AgentRunLifecycleOptions {
         readonly signal?: AbortSignal;
     }) => AgentRunLifecycleAgent | Promise<AgentRunLifecycleAgent>;
     readonly fencingToken?: number;
+    /**
+     * Plan 094 Task 3: external-state restore hooks, run on every claiming resume before the
+     * checkpoint is claimed. Registered once here because a resume builds its session from the
+     * stored state (there is no live session to register against beforehand).
+     */
+    readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
+    /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly restoreHookTimeoutMs?: number;
 }
 export interface AgentRunLifecycleRequest {
     readonly ownership?: OwnershipScope;
@@ -22,6 +30,12 @@ export interface AgentRunLifecycleRequest {
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies on resume (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
+    /** Checkpoint sidecar metadata applied on resume (and to the resumed run's later checkpoints). */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
+    /** Plan 094 Task 3: restore hooks for this resume; the lifecycle's own hooks are used when omitted. */
+    readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
+    /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly restoreHookTimeoutMs?: number;
 }
 /** Bounded live-event options for a durable lifecycle resume. */
 export interface AgentRunLifecycleStreamRequest extends AgentRunLifecycleRequest, SubscribeOptions {

package/dist/agent-run-lifecycle.js

@@ -1,21 +1,31 @@
 import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
-import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
+import { agentFingerprint, loadAgentRunState, publicState, resolveCheckpointMetadata, saveAgentRunState } from "./agent-run-state.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
-import { parseAttentionStickyFrontier } from "./attention-compiler.js";
+import { parseAttentionStickyFrontier, restoreAttentionFoldLedger } from "./attention-compiler.js";
+import { runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 import { AgentRunStateError } from "./contracts.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
         throw new AgentRunStateError("Agent run capability mismatch");
 }
+/** Lifecycle-registered hooks run first, then per-request ones; either timeout setting wins for both. */
+function restoreHookOptions(lifecycle, request) {
+    const hooks = [...(lifecycle.restoreHooks ?? []), ...(request.restoreHooks ?? [])];
+    const timeoutMs = request.restoreHookTimeoutMs ?? lifecycle.restoreHookTimeoutMs;
+    return {
+        ...(hooks.length > 0 ? { restoreHooks: hooks } : {}),
+        ...(timeoutMs === undefined ? {} : { restoreHookTimeoutMs: timeoutMs }),
+    };
+}
 /** Host capability for durable agent status/resume. Adapters supply authorized ownership only. */
 export function createAgentRunLifecycle(options) {
     return {
         async status(ref, request = {}) {
             request.signal?.throwIfAborted();
-            const { state, record } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
+            const { state, record, metadata } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
             assertAgentId(state.agentId, request.agentId);
             request.signal?.throwIfAborted();
-            return { state: publicState({ ...state, version: record.version }), version: record.version };
+            return { state: publicState({ ...state, version: record.version }), version: record.version, ...(metadata ? { metadata } : {}) };
         },
         async resume(ref, resume, request = {}) {
             request.signal?.throwIfAborted();
@@ -31,6 +41,8 @@ export function createAgentRunLifecycle(options) {
                 signal: request.signal,
                 persistSessionState: request.persistSessionState,
                 includeSkillBodies: request.includeSkillBodies,
+                ...(request.checkpointMetadata === undefined ? {} : { checkpointMetadata: request.checkpointMetadata }),
+                ...restoreHookOptions(options, request),
             });
         },
         async *resumeStream(ref, resume, request = {}) {
@@ -49,6 +61,8 @@ export function createAgentRunLifecycle(options) {
                 overflow: request.overflow,
                 persistSessionState: request.persistSessionState,
                 includeSkillBodies: request.includeSkillBodies,
+                ...(request.checkpointMetadata === undefined ? {} : { checkpointMetadata: request.checkpointMetadata }),
+                ...restoreHookOptions(options, request),
             });
         },
     };
@@ -99,7 +113,10 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     // and malformed untyped batches fail closed here instead of falling through to approval.
     assertValidAgentRunResume(resume);
     const continuing = resume.decision === "continue";
-    const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
+    const { record, state, metadata: recordMetadata } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
+    // Sidecar metadata: a resume-time source wins; otherwise the record's existing map is
+    // preserved on every write below, so a non-durable resume cannot wipe it.
+    const checkpointMetadata = resolveCheckpointMetadata(options.checkpointMetadata) ?? recordMetadata;
     if (state.definitionRevision !== options.definitionRevision ||
         state.agentId !== (agent.config.id ?? agent.config.name) ||
         state.fingerprint !== agentFingerprint(agent, options.definitionRevision)) {
@@ -137,6 +154,21 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         if (frontier)
             session.restoreAttentionSticky(frontier);
     }
+    // Plan 086 T3: durable folding writes its own ledger (with the frontier it belongs to), so it
+    // is restored whenever the checkpoint carries one — the `durable` opt-in was the host's
+    // consent, and a run without it never has this key. Without the frontier the ledger's rows
+    // would not be re-applied on an under-ratio turn, so the two ride together.
+    if (state.sessionState?.attentionFold) {
+        const ledger = restoreAttentionFoldLedger(state.sessionState.attentionFold);
+        if (ledger) {
+            session.restoreAttentionFold(ledger);
+            if (!options.persistSessionState && state.sessionState.attentionSticky) {
+                const frontier = parseAttentionStickyFrontier(state.sessionState.attentionSticky);
+                if (frontier)
+                    session.restoreAttentionSticky(frontier);
+            }
+        }
+    }
     // Plan 018 Task 6 (closeout `checkpoint-bodies`): restore exact instructions so the
     // resumed session renders them registry-independently (no load_skill round-trip).
     if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {
@@ -231,6 +263,7 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
             expectedVersion: record.version,
             ownership: options.ownership,
             fencingToken: options.fencingToken,
+            ...(checkpointMetadata ? { metadata: checkpointMetadata } : {}),
         });
         return {
             kind: "deny",
@@ -258,6 +291,21 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         throw new AgentRunStateError("Agent durable run-state configuration mismatch on resume");
     }
     throwIfAbortedSignal(signal);
+    // Plan 094 Task 3: restore external state (git commit, document versions) before the claim
+    // write. Every hook must succeed — a throw here leaves the checkpoint exactly as it was, and
+    // the conversation restore below never runs, so no half-restored world is claimed as resumed.
+    const restoreHooks = options.restoreHooks ?? [];
+    const restore = restoreHooks.length
+        ? await runCheckpointRestoreHooks(restoreHooks, {
+            runId: state.runId,
+            sessionId: state.sessionId,
+            version: record.version,
+            status: state.status,
+            ...(recordMetadata ? { metadata: recordMetadata } : {}),
+            checkpoint: record,
+        }, { timeoutMs: options.restoreHookTimeoutMs, signal })
+        : undefined;
+    throwIfAbortedSignal(signal);
     const claimed = await saveAgentRunState({
         checkpoints: options.checkpoints,
         state: {
@@ -269,6 +317,7 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         expectedVersion: record.version,
         ownership: options.ownership,
         fencingToken: options.fencingToken,
+        ...(checkpointMetadata ? { metadata: checkpointMetadata } : {}),
     });
     return {
         kind: "claim",
@@ -276,6 +325,9 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         state: claimed.state,
         decisions: resolved?.decisionsById,
         ownership: options.ownership,
+        // The configured object must be passed by identity (agent-session assemble rejects a
+        // replaced config); its own `checkpointMetadata` provider wins, and the resolved map rides
+        // the session as a seed so later writes preserve a record's existing sidecar.
         runState: configured ?? {
             checkpoints: options.checkpoints,
             definitionRevision: options.definitionRevision,
@@ -286,6 +338,8 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
             // turn checkpoints without the host repeating the option on resume.
             ...(state.checkpointPolicy ? { checkpointPolicy: state.checkpointPolicy } : {}),
         },
+        ...(checkpointMetadata ? { checkpointMetadata } : {}),
+        ...(restore ? { restore } : {}),
     };
 }
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
@@ -298,6 +352,9 @@ async function executePreparedAgentRunResume(prepared, signal) {
         await prepared.session.recordDurableResumption(prepared.result.runId, prepared.interruption, prepared.version, prepared.ownership);
         return prepared.result;
     }
-    return prepared.session.resumeDurable(prepared.state, prepared.runState, prepared.ownership, signal, prepared.decisions);
+    return prepared.session.resumeDurable(prepared.state, prepared.runState, prepared.ownership, signal, prepared.decisions, {
+        ...(prepared.checkpointMetadata ? { checkpointMetadata: prepared.checkpointMetadata } : {}),
+        ...(prepared.restore ? { restore: prepared.restore } : {}),
+    });
 }
 //# sourceMappingURL=agent-run-lifecycle.js.map

package/dist/agent-run-state.d.ts

@@ -1,11 +1,13 @@
-import { type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
-import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
+import { type PersistedAttentionFoldLedger, type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
+import type { Agent, AgentRunCheckpointMetadata, AgentRunCheckpointMetadataSource, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export declare const AGENT_RUN_STATE_SCHEMA_VERSION: 1;
 export declare const DEFAULT_MAX_AGENT_RUN_STATE_BYTES: number;
 export declare const HARD_MAX_AGENT_RUN_STATE_BYTES: number;
+/** Sidecar metadata ceiling per checkpoint record (not the run-state value). */
+export declare const MAX_AGENT_RUN_METADATA_BYTES: number;
 /** One gated tool call awaiting or holding a decision inside a suspended durable run. */
 export interface PendingToolCall {
     readonly call: ToolCallContent;
@@ -50,6 +52,10 @@ export interface StoredAgentRunState extends AgentRunState {
         /** Plan 074 P3: sticky attention mutations (thinking hashes + tool-call ids), so a durable
          *  resume keeps its stubs instead of re-deciding on the first turn. Validated on load. */
         readonly attentionSticky?: PersistedAttentionStickyFrontier;
+        /** Plan 086 T3: folded bodies (`attention.compiler.durable`), so a resumed fold re-applies
+         *  the same stub bytes instead of re-summarizing. Written and restored independently of
+         *  `persistSessionState`. Validated on load. */
+        readonly attentionFold?: PersistedAttentionFoldLedger;
     };
     /** Per-run allow-list (Task 21). Absent = full registered set (legacy checkpoints). */
     readonly toolNames?: readonly string[];
@@ -81,7 +87,20 @@ export declare function validateRunStateOptions(options: AgentRunStateOptions):
 export declare function loadAgentRunState(checkpoints: CheckpointStore, ref: AgentRunRef, ownership?: OwnershipScope): Promise<{
     readonly record: CheckpointRecord;
     readonly state: StoredAgentRunState;
+    readonly metadata?: AgentRunCheckpointMetadata;
 }>;
+/** Resolve a host metadata source. A throwing provider fails the checkpoint write (fail closed). */
+export declare function resolveCheckpointMetadata(source: AgentRunCheckpointMetadataSource | undefined): AgentRunCheckpointMetadata | undefined;
+/**
+ * Redact + bound a sidecar metadata map for a checkpoint write. Values must be strings;
+ * redaction runs first so a replacement marker is still charged against the 4 KiB ceiling.
+ */
+export declare function boundCheckpointMetadata(metadata: AgentRunCheckpointMetadata, redactor?: SecretRedactor): AgentRunCheckpointMetadata;
+/**
+ * Read-side normalization (legacy tolerance): absent, oversize, or non-string entries are
+ * dropped, never thrown — a malformed sidecar must not block a resume.
+ */
+export declare function readCheckpointMetadata(metadata: unknown): AgentRunCheckpointMetadata | undefined;
 export declare function saveAgentRunState(input: {
     readonly checkpoints: CheckpointStore;
     readonly state: StoredAgentRunState;
@@ -90,6 +109,7 @@ export declare function saveAgentRunState(input: {
     readonly fencingToken?: number;
     readonly redactor?: SecretRedactor;
     readonly maxStateBytes?: number;
+    readonly metadata?: AgentRunCheckpointMetadata;
 }): Promise<{
     readonly record: CheckpointRecord;
     readonly state: StoredAgentRunState;

package/dist/agent-run-state.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { parseAttentionStickyFrontier } from "./attention-compiler.js";
+import { parseAttentionStickyFrontier, restoreAttentionFoldLedger, } from "./attention-compiler.js";
 import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
 import { validateLoadedSkillBodies } from "./skill-load.js";
 import { HARD_RUN_TOOL_NAMES } from "./tools.js";
@@ -7,6 +7,8 @@ export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
 export const AGENT_RUN_STATE_SCHEMA_VERSION = 1;
 export const DEFAULT_MAX_AGENT_RUN_STATE_BYTES = 256 * 1024;
 export const HARD_MAX_AGENT_RUN_STATE_BYTES = 1024 * 1024;
+/** Sidecar metadata ceiling per checkpoint record (not the run-state value). */
+export const MAX_AGENT_RUN_METADATA_BYTES = 4 * 1024;
 const MAX_DEPTH = 32;
 const MAX_PROPERTIES = 256;
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
@@ -116,10 +118,55 @@ export async function loadAgentRunState(checkpoints, ref, ownership) {
         record.value.sessionId !== ref.sessionId) {
         throw new AgentRunStateError("Agent run session mismatch");
     }
-    return { record, state: parseAgentRunState(record.value, record.version) };
+    const metadata = readCheckpointMetadata(record.metadata);
+    return { record, state: parseAgentRunState(record.value, record.version), ...(metadata ? { metadata } : {}) };
+}
+/** Resolve a host metadata source. A throwing provider fails the checkpoint write (fail closed). */
+export function resolveCheckpointMetadata(source) {
+    return typeof source === "function" ? source() : source;
+}
+function checkpointMetadataBytes(metadata) {
+    return Buffer.byteLength(JSON.stringify(metadata), "utf8");
+}
+/**
+ * Redact + bound a sidecar metadata map for a checkpoint write. Values must be strings;
+ * redaction runs first so a replacement marker is still charged against the 4 KiB ceiling.
+ */
+export function boundCheckpointMetadata(metadata, redactor) {
+    const redacted = redactor?.redact(metadata) ?? metadata;
+    if (!redacted || typeof redacted !== "object" || Array.isArray(redacted)) {
+        throw new AgentRunStateError("Checkpoint metadata must be an object");
+    }
+    const bounded = {};
+    for (const [key, value] of Object.entries(redacted)) {
+        if (typeof value !== "string")
+            throw new AgentRunStateError(`Checkpoint metadata value for ${key} must be a string`);
+        bounded[key] = value;
+    }
+    if (checkpointMetadataBytes(bounded) > MAX_AGENT_RUN_METADATA_BYTES) {
+        throw new AgentRunStateError(`Checkpoint metadata exceeds ${MAX_AGENT_RUN_METADATA_BYTES} bytes`);
+    }
+    return Object.freeze(bounded);
+}
+/**
+ * Read-side normalization (legacy tolerance): absent, oversize, or non-string entries are
+ * dropped, never thrown — a malformed sidecar must not block a resume.
+ */
+export function readCheckpointMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return undefined;
+    const bounded = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (typeof value === "string")
+            bounded[key] = value;
+    }
+    if (Object.keys(bounded).length === 0 || checkpointMetadataBytes(bounded) > MAX_AGENT_RUN_METADATA_BYTES)
+        return undefined;
+    return Object.freeze(bounded);
 }
 export async function saveAgentRunState(input) {
     const bounded = boundState(input.redactor?.redact(input.state) ?? input.state, input.maxStateBytes ?? DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+    const metadata = input.metadata === undefined ? undefined : boundCheckpointMetadata(input.metadata, input.redactor);
     const record = await input.checkpoints.saveCheckpoint({
         namespace: AGENT_RUN_STATE_NAMESPACE,
         key: bounded.runId,
@@ -128,6 +175,7 @@ export async function saveAgentRunState(input) {
         fencingToken: input.fencingToken,
         value: bounded,
         category: "agent-run",
+        ...(metadata ? { metadata } : {}),
         ...input.ownership,
     });
     return { record, state: { ...bounded, version: record.version } };
@@ -294,12 +342,16 @@ function validateSessionState(sessionState) {
         }
     }
     const attention = sessionState.attentionSticky;
-    if (attention === undefined)
-        return;
     // Both arrays are capped by the parser, and a malformed frontier is dropped rather than
     // failing the resume: re-deciding a mutation is safe, refusing to resume is not.
-    if (parseAttentionStickyFrontier(attention) === undefined) {
+    if (attention !== undefined && parseAttentionStickyFrontier(attention) === undefined) {
         throw new AgentRunStateError("Malformed agent run attention frontier");
     }
+    // Plan 086 T3: the fold ledger gets the same treatment — malformed entries are dropped by the
+    // parser, a malformed shape fails the load rather than the first provider turn.
+    const fold = sessionState.attentionFold;
+    if (fold !== undefined && restoreAttentionFoldLedger(fold) === undefined) {
+        throw new AgentRunStateError("Malformed agent run attention fold ledger");
+    }
 }
 //# sourceMappingURL=agent-run-state.js.map

package/dist/agent-session/helpers.js

@@ -160,6 +160,8 @@ export function createUsageAccumulator() {
     const sums = new Map();
     let costCurrency;
     let costCompatible = true;
+    let estimated = false;
+    let confidence;
     return {
         add(usage) {
             for (const key of ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]) {
@@ -181,6 +183,13 @@ export function createUsageAccumulator() {
                 if (costCompatible)
                     sums.set("cost", (sums.get("cost") ?? 0) + usage.cost);
             }
+            // Run totals keep estimate provenance (plan 091 T2): one estimated turn
+            // labels the total, and the weakest confidence wins.
+            if (usage.estimated === true) {
+                estimated = true;
+                if (usage.confidence !== undefined && (confidence === undefined || usage.confidence === "low"))
+                    confidence = usage.confidence;
+            }
         },
         value() {
             if (sums.size === 0)
@@ -192,6 +201,11 @@ export function createUsageAccumulator() {
             }
             if (costCompatible && sums.has("cost") && costCurrency !== undefined)
                 usage.currency = costCurrency;
+            if (estimated) {
+                usage.estimated = true;
+                if (confidence !== undefined)
+                    usage.confidence = confidence;
+            }
             return Object.keys(usage).length > 0 ? usage : undefined;
         },
     };