@arnilo/prism 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,76 @@
+## [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.
+
+### Added
+- **Messaging channels.** `@arnilo/prism-channels` ships the transport-neutral runtime (deny-by-default sender authorization, owned session binding, serialized turns, current-run replies, one-use durable approvals, bounded attachment refs), official Telegram (private DMs, opt-in granted groups/topics, private-chat drafts, bounded media, optional voice transcription/synthesis, opt-in notices to one already-bound pair), and experimental pinned signal-cli Signal. See [docs/messaging-channels.md](docs/messaging-channels.md), [docs/telegram-channel.md](docs/telegram-channel.md), [docs/signal-channel.md](docs/signal-channel.md), [docs/messaging-channel-operations.md](docs/messaging-channel-operations.md).
+- **Connected apps and work HTTP.** Identity-bound MCP connected-app sessions admit host-selected transports and register prefixed tools. Google Workspace and Microsoft 365 HTTP adapters live under `@arnilo/prism-work/connectors`. Slack MCP wrap and Open Connector sidecar stay examples. See [docs/connected-apps.md](docs/connected-apps.md), [docs/work-connectors.md](docs/work-connectors.md).
+- **Durable runs, turn-boundary stops, and run-bundle snapshots.** `AgentRunStateOptions.checkpointPolicy: "every-turn"` checkpoints a run at the provider-turn boundary so a crashed worker resumes with the host-only `decision: "continue"` action (never reachable from AG-UI or the server boundary, and rejected while any approval or ready tool call is pending). `RunOptions.turnPolicy` (`TurnPolicyOptions`) stops a run synchronously at a turn boundary and reports `stopReason: "host_policy"` with a redacted, bounded `stopDetail` on the result, the ledger row, the `agent_finished` event, and the execution timeline; a host-policy stop stays resumable. `snapshotRunBundle` returns a `RunBundleSnapshot` — a frozen, redacted digest projection of the effective run bundle with zero store or network reads. `createClaimGroundingGuardrail` (stage `"output"`) blocks or flags numeric claims that no tool result or host evidence supports. `ErrorInfo.failureClass` (`ProviderFailureClass`) types provider failures as `quota` / `rate_limited` / `auth` / `transient` / `permanent` / `unknown`; `ModelCapabilities.toolCallStrictness` adds advisory tool-call reliability. See [docs/durable-runs.md](docs/durable-runs.md), [docs/run-bundle.md](docs/run-bundle.md), [docs/guardrails.md](docs/guardrails.md).
+- **Work sandbox and vendored skills.** `@arnilo/prism-work/sandbox` plus `createWorkComposition` run office/exec in an injected Docker sandbox; connectors stay on the host. The package ships `docx`, `xlsx`, `powerpoint`, `pdf` skills.
+
+### Changed
+- **Lockstep `0.7.0` → `0.8.0`.** All eleven publishable manifests move together with `^0.8.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`).
+- **Work family rename.** `@arnilo/prism-office` is replaced by `@arnilo/prism-work` (connectors, documents, sheets, diagrams, document-reader, sandbox, skills, tools). No pre-1.0 shim. See [docs/migrate-to-0.8.md](docs/migrate-to-0.8.md).
+- **AG-UI input authority is opt-in server-side.** `CreateAgUiHandlerOptions.inputPolicy.clientState: "ignore"` validates then discards client-supplied AG-UI state and tools before projection, and stops advertising client-provided tools; the default `"honor"` path is byte-identical to 0.7.0.
+- **Observational-memory workers are tool-only.** Text/thinking/done-only turns are successful no-ops. Limit and unknown-tool failures throw `MemoryError` / `MemoryLimitError` rather than matching an English message prefix.
+- **Channel lease release is fail-closed.** In-memory `route.lease` clears only after the store acknowledges; a failed release retries on idle/`stop`. TTL remains the cross-process backstop.
+- **This-tree Postgres evidence.** `release:gate` reports `test:postgres` as pass only when `scripts/postgres-evidence.json` matches current `git rev-parse HEAD`. A stale phase baseline is blocked.
+- **Compat baselines regenerated** at 0.8.0. Inherited 083 `@arnilo/prism-office` → `@arnilo/prism-work` removals (and `prism-core` / `prism-coding-tools` moves) are listed separately from 085 additions. This cut's own Tasks 1–6 add no public removals.
+- **Migration guide for 0.7.0 hosts**: [docs/migrate-to-0.8.md](docs/migrate-to-0.8.md), indexed from [docs/migration.md](docs/migration.md) and [docs/index.md](docs/index.md).
+
+### Fixed
+- **Portable work-idempotency error codes survived the work-family move.** The enterprise PostgreSQL `IdempotencyStore` adapter keeps `ERR_PRISM_WORK_IDEMPOTENCY` / `ERR_PRISM_WORK_IDEMPOTENCY_CONFLICT`; only the error class changed (`EnterprisePostgresError`).
+- **Stale ownership assertions in the protected PostgreSQL leg:** a foreign checkpoint scope is a miss plus a generic CAS conflict, and a foreign agent-run status read is indistinguishable from a missing run (`ERR_PRISM_AGENT_RUN_STATE`).
+- **Wiki isolation nested-runner flake.** The wiki scratch gate spawns `node --test --test-isolation=none` (still strips `NODE_TEST_CONTEXT` / `NODE_TEST_WORKER_ID`) so worker IPC deserialization cannot fail the gate under `npm test` load.
+- **Coverage artifact names.** Package keys in `scripts/coverage-summary.json` must equal live workspace manifests (`@arnilo/prism-work`, not `@arnilo/prism-office`).
+- **Alibaba video `fetchUrl`.** Declared `fetchUrl` now downloads generated video bytes; unused OpenAI speech `_bearerHeaders` deleted.
+
+### Security
+- **Numeric claims must be grounded or they fail closed.** The claim-grounding guardrail blocks by default, bounds every reported span, caps evidence collection (4,096 figures, 16 levels, 128 KiB), and treats a missing evidence set as ungrounded rather than passing silently.
+- **Crash recovery cannot bypass approval gates.** `"continue"` resumes only a running checkpoint with no pending decision or ready call, and keeps the recorded fingerprint, revision, ownership/fencing, and CAS-version gates.
+- **Failed channel lease release is not success.** This process does not treat the binding as free until the store acknowledges; TTL is the other-process backstop.
+- **Postgres release pass cannot be inherited.** Missing or stale this-tree evidence is blocked, never a pass from a previous commit's counts.
+
 ## [0.7.0] - 2026-09-15 (extended line: plans 072, 073, 074, 075, 077, 078)
 
 > **Channels are not in this cut.** Plan 079 (Telegram/Signal adapters) was reassigned to **0.8.0** so the 0.7.0 cut stops waiting on it; nothing in this release mentions or ships a channel adapter.

package/README.md

@@ -158,20 +158,21 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 ## Packages
 
 <!-- generated:package-truth:inventory begin -->
-**10 publishable manifests** — root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
+**11 publishable manifests** — root `@arnilo/prism` plus 10 workspace packages (4 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.7.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.7.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.7.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.7.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.7.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.7.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.7.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.7.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.7.0 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.7.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura 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;
@@ -10,6 +11,10 @@ export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly
  * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
  * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
  * elicitation payloads, credentials, or foreign approval details.
+ *
+ * The legacy `decision` accepts `continue` (plan 084 Task 1) in addition to `approve`/`deny`;
+ * it is a crash-recovery action for running-state checkpoints and is resolved in
+ * `prepareAgentRunResume`, never as an approval outcome.
  */
 export declare function assertValidAgentRunResume(resume: AgentRunResume): void;
 interface ResolvedRunDecisions {
@@ -46,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-approval.js

@@ -28,6 +28,10 @@ export function pendingDecisionsOf(state) {
  * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
  * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
  * elicitation payloads, credentials, or foreign approval details.
+ *
+ * The legacy `decision` accepts `continue` (plan 084 Task 1) in addition to `approve`/`deny`;
+ * it is a crash-recovery action for running-state checkpoints and is resolved in
+ * `prepareAgentRunResume`, never as an approval outcome.
  */
 export function assertValidAgentRunResume(resume) {
     const invalid = (message) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message);
@@ -45,7 +49,7 @@ export function assertValidAgentRunResume(resume) {
     if (!hasDecision && !hasDecisions)
         throw invalid("Resume requires a decision or decisions");
     if (hasDecision) {
-        if (resume.decision !== "approve" && resume.decision !== "deny") {
+        if (resume.decision !== "approve" && resume.decision !== "deny" && resume.decision !== "continue") {
             throw invalid("Unknown legacy decision");
         }
         return;

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 { parseAttentionStickyFrontier } from "./attention-compiler.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, 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();
@@ -28,8 +38,11 @@ export function createAgentRunLifecycle(options) {
                 ownership: request.ownership,
                 fencingToken: options.fencingToken,
                 definitionRevision: resolved.definitionRevision,
+                signal: request.signal,
                 persistSessionState: request.persistSessionState,
                 includeSkillBodies: request.includeSkillBodies,
+                ...(request.checkpointMetadata === undefined ? {} : { checkpointMetadata: request.checkpointMetadata }),
+                ...restoreHookOptions(options, request),
             });
         },
         async *resumeStream(ref, resume, request = {}) {
@@ -48,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),
             });
         },
     };
@@ -55,7 +70,8 @@ export function createAgentRunLifecycle(options) {
 // Resume free functions moved from agents.ts at 0.1.4 (verbatim; the barrel re-exports the two public ones).
 /** Resume a persisted built-in run. A claimed/dispatched tool is never replayed automatically. */
 export async function resumeAgentRun(agent, ref, resume, options) {
-    return executePreparedAgentRunResume(await prepareAgentRunResume(agent, ref, resume, options));
+    throwIfAbortedSignal(options.signal);
+    return executePreparedAgentRunResume(await prepareAgentRunResume(agent, ref, resume, options, options.signal), options.signal);
 }
 /** Subscribe before resuming one durable run. Early consumer return aborts that resumed execution. */
 export async function* resumeAgentRunStream(agent, ref, resume, options) {
@@ -81,20 +97,42 @@ export async function* resumeAgentRunStream(agent, ref, resume, options) {
         }
     }
 }
+/**
+ * A `continue` resume needs a run whose frontier is intact: a crash-recovery checkpoint
+ * (`status: "running"`) or a turn-policy stop, which writes a terminal state that still carries
+ * the frontier (plan 084 Task 2). Every other terminal state is final — a naturally finished run
+ * must never be resurrected.
+ */
+function isContinuableState(state) {
+    return state.status === "running" || (state.status === "succeeded" && state.stopReason === "host_policy");
+}
 async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     throwIfAbortedSignal(signal);
     // Plan 020 Task 2: one shared shape assertion before any checkpoint read/write, agent
     // resolution, subscription, or tool execution. Unknown legacy decisions (e.g. "sideways")
     // and malformed untyped batches fail closed here instead of falling through to approval.
     assertValidAgentRunResume(resume);
-    const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
+    const continuing = resume.decision === "continue";
+    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)) {
         throw new AgentRunStateError("Agent definition revision or fingerprint mismatch on resume");
     }
-    if (record.version !== resume.expectedVersion || state.status !== "suspended") {
-        throw new AgentRunStateError("Stale or non-suspended agent run resume");
+    if (record.version !== resume.expectedVersion || !(continuing ? isContinuableState(state) : state.status === "suspended")) {
+        throw new AgentRunStateError(continuing ? "Stale or non-running agent run resume" : "Stale or non-suspended agent run resume");
+    }
+    // Crash recovery never bypasses a gate: only a running checkpoint with no unresolved work may
+    // continue. A suspended state (tool approval, elicitation, input guardrail) requires a decision.
+    if (continuing) {
+        const pending = pendingDecisionsOf(state);
+        const awaitingDispatch = state.pending?.status === "ready" || state.pendingCalls?.some((entry) => entry.status === "ready") === true;
+        if (state.interruption !== undefined || (pending?.length ?? 0) > 0 || awaitingDispatch) {
+            throw new AgentRunStateError("Continue resume requires a running checkpoint with no pending decisions");
+        }
     }
     const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
     // Plan 078 Task 7: hand the reconstructed session to an observer (supervisor child-event pump)
@@ -116,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) {
@@ -210,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",
@@ -237,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: {
@@ -248,20 +317,29 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         expectedVersion: record.version,
         ownership: options.ownership,
         fencingToken: options.fencingToken,
+        ...(checkpointMetadata ? { metadata: checkpointMetadata } : {}),
     });
     return {
-        kind: "approve",
+        kind: "claim",
         session,
         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,
             interruptBeforeTool: state.interruptBeforeTool,
             fencingToken: options.fencingToken,
             resumeNestedRun: options.resumeNestedRun,
+            // The checkpoint records its own cadence (plan 084 Task 1), so a continued run keeps writing
+            // 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. */
@@ -274,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 { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
-import { type PersistedAttentionStickyFrontier } from "./attention-compiler.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,9 +52,25 @@ 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[];
+    /**
+     * Recorded checkpoint cadence (plan 084 Task 1). Present only for `"every-turn"` runs, so
+     * default checkpoints stay byte-identical. A resume of such a state keeps checkpointing each
+     * turn without the host repeating the option.
+     */
+    readonly checkpointPolicy?: "every-turn";
+    /**
+     * Set when a terminal state was written by a `RunOptions.turnPolicy` stop (plan 084 Task 2):
+     * the run succeeded cleanly but its frontier is intact, so `decision: "continue"` may resume
+     * it. Absent on every other state — a naturally finished run is never continuable.
+     */
+    readonly stopReason?: "host_policy";
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export declare const MAX_PERSISTED_SKILL_NAMES = 64;
@@ -69,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;
@@ -78,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;