@arnilo/prism 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,6 +1,33 @@
+## [0.11.1] - 2026-09-24 (System One decision models)
+
+### Added
+- **`@arnilo/prism-providers/typesafe` and `@arnilo/prism-providers/laya`.** Structured-output decision models on `POST /v1/systemone`. Jev is hosted (`https://api.typesafe.ai`, env `TYPESAFE_API_KEY`). Laya is self-hosted `laya-serve` (default `http://localhost:8000`, optional `LAYA_API_KEY`). A request without `options.structuredOutput`, or with tools, fails before any network call. See [docs/providers/typesafe.md](docs/providers/typesafe.md) and [docs/providers/laya.md](docs/providers/laya.md).
+
+## [0.11.0] - 2026-09-24 (store bounds, lease fence reset, subpath removals)
+
+> **Twelve publishable packages.** Lockstep minor. No new public exports from the review remediation. Two host-visible store contracts change, and three subpaths that the published 0.10.0 tarball still shipped are removed. Predecessor published line is **0.10.0**. Registry/tag writes stay operator-authorized.
+
+### Changed
+- **Lockstep `0.10.0` → `0.11.0`.** All twelve publishable manifests move together with `^0.11.0` internal ranges. The lockfile, the `src/index.ts` version constant, the docs index banner, the release-workflow tag list, and the generated package-truth artifact agree (`scripts/version-literal-gate.test.mjs`).
+- **Compat baseline regenerated.** The only declaration this cut changed is `version` (`"0.10.0"` → `"0.11.0"`). The same regen records the already-landed persona/graft removals (58 `@arnilo/prism-memory`, 48 `@arnilo/prism-coding-tools`) and the signature widenings already named in [docs/migration.md](docs/migration.md). No plan-120 public name was added.
+- **Memory session store implements `readBranchPath`.** A snapshot walks the branch once and clones each kept entry once. JSONL and the durable adapters already had the method.
+- **JSONL parse cache.** Reads after an in-process append reuse the parsed file when `(size, mtimeMs)` match. A same-size write inside one filesystem timestamp tick can still look unchanged; the upgrade path is hashing the file.
+- **Idempotency window is 4,096 keys** on the memory store and the JSONL store. A replay of a key still inside the window is rejected. A replay of an evicted key appends a new entry. See [docs/migrate-to-0.11.md](docs/migrate-to-0.11.md).
+- **In-memory lease sweep.** Expired rows are deleted once the map reaches 1,024. A released key that is still in the map inherits `fencingToken + 1`. A key that was swept starts its next fence at 1 (`docs/operations.md`). SQLite and Postgres adapters still keep the counter on the expired row.
+- **Plain-text token estimates share one helper** (`ceil(length/4)`). Message and entry estimates are unchanged and are not billing numbers. Golden vectors live in `scripts/token-estimate-fixtures.json` (not shipped).
+- **`npm test` gains two stages:** examples execution (spawns examples not already executed; `docker-process-session.ts` is `known-broken:placeholder-image`) and a Node branch-coverage audit (floor 83.49, `dist/**` only). Bun's coverage gate still records `branches: null`. Offline test budget pin is `< 110s`.
+- **Freeze-test package presence** comes from `workspacePackageCounts()` in `scripts/package-truth.mjs`. Frozen count deltas stay in each suite.
+
+### Removed
+- **Behavior persona subpaths (`@arnilo/prism-coding-tools/caveman`, `/ponytail`).** Both subpaths, their vendored upstream fixtures, and the `@dietrichgebert/ponytail` optional peer are gone. Load the upstream tree with `loadSkillDirectory` and register skills from a host extension. `@arnilo/prism-coding-tools/impeccable` is unchanged. See [docs/migrate-to-0.11.md](docs/migrate-to-0.11.md).
+- **Graft bridge subpath (`@arnilo/prism-memory/graft`).** The subpath, its `@nanonets/graft` optional peer, the fixture CLI, and the graft commands are gone. Integrate graft as a host MCP server, or author tools against `registerTool` / `registerCommand`. `/rag`, `/compaction/*`, `/fabric`, `/wiki`, and `/scoped` stay.
+
+### Security
+- No new credential surface. The lease sweep does not delete a live lease. Idempotency eviction cannot be used to skip the in-window duplicate check.
+
 ## [0.10.0] - 2026-09-21 (hook lifecycle completion, scoped agent memory)
 
-> **Twelve publishable packages.** All 105–106 features ship behind their documented options and defaults: `@arnilo/prism-hooks` is the new twelfth package, and scoped memory is an opt-in subpath that does nothing until a host constructs it. Predecessor published line is **0.9.0**. Plans 097 (trajectory export) and 107 (behavior/graft removals) were not implemented for this line and are deferred rather than held unstarted against the cut. Registry/tag writes stay operator-authorized.
+> **Twelve publishable packages.** All 105–106 features ship behind their documented options and defaults: `@arnilo/prism-hooks` is the new twelfth package, and scoped memory is an opt-in subpath that does nothing until a host constructs it. Predecessor published line is **0.9.0**. Plan 097 (trajectory export) was not implemented for this line and is deferred rather than held unstarted against the cut. Registry/tag writes stay operator-authorized.
 
 ### Added
 - **Scoped persistent memory (`@arnilo/prism-memory/scoped`).** New opt-in subpath: `createScopedMemoryPolicy({ memory, fabric, scopeRoot, policy })` is a policy and lifecycle layer over stores the host already configured (no fifth store). Create is inert and fails closed unless `scope.resourceId` equals the resolved `scopeRoot` and a `threadId` is set; the read path oversamples `fabric.recall`, applies an abstain floor (`activation.minSimilarity` 0.35) and activation budget (`topK` 3), ranks by `fabricScore × exp(−ageDays/tauDays) × (1 + ln(1 + uses))` (`tauDays` 30), and returns `{ hits: [], abstained: true }` rather than a weak hit. Writes go through a conservative post-run reviewer (`reviewSession`, strict JSON, garbage → zero writes), land as `candidate` records, and flip to `verified` after `promotion.reuseThreshold` (2) successful recalls — ledger status only, no fabric rewrite. `gcPass()` proposes archives onto `pending()` and never deletes (`legal_hold` skipped), `rememberFact` keeps a bounded working block (`maxChars` 2200, overflow throws `MemoryLimitError` with `consolidate first`), an injection scan plus an optional staged approval gate (`approval.default: "off"`) guard content, and a deterministic git audit mirror renders notes. State lives in one JSON ledger at `<scopeRoot>/.memory/state.json` (ids, counters, timestamps — never note content). Sizing: one reviewer call per run, one ledger read plus one write per recall, no model calls on the read path. See [docs/scoped-memory.md](docs/scoped-memory.md).
@@ -10,6 +37,7 @@
 - **Pre-compaction rewrite seam.** The `compaction_request` middleware hook runs after `compaction_started` and before the strategy, so a handler returns the `CompactionContext` the strategy actually compacts (entries and budget) and the following `compaction` hook plus `compaction_finished` event report that result. See [docs/middleware-hooks.md](docs/middleware-hooks.md).
 - **`@arnilo/prism-hooks`, the hooks-file adapter.** New twelfth publishable package: `parseHooksConfig(text | object)` accepts the Claude flat and Codex `{ "hooks": { … } }` shapes, and `createHooksExtension(config, options)` compiles them onto public seams — `SessionStart` / `UserPromptSubmit` `additionalContext` through an instruction injector, `UserPromptSubmit` / `PreToolUse` / `PostToolUse` guardrails for denies, `tool_call` / `tool_result` middleware for `updatedInput` and post-tool context, and `Stop` onto stop hooks. Handlers are `command` (spawned shell-free, hash-pinned with `hookCommandHash()`) or `mcp_tool` (host-provided client, `${field.path}` templates), with seconds-based `timeout`, per-handler `additionalContextLimit` (default 2500 tokens, spilling to `<tempdir>/hook_outputs/`), and Codex's `continue: false` read as the stop signal. See [docs/hooks.md](docs/hooks.md).
 - **Unified hook map.** [docs/hooks.md](docs/hooks.md) is the owning page for the hook model: the five families (transform, decide, inject, run-end control, observe), one row per Claude Code / Codex event mapped to its Prism surface or a documented non-goal with rationale (`PermissionRequest` stays host policy), the adapter reference, and migration steps from an existing `hooks.json` config.
+- **Host skill-directory loader.** `loadSkillDirectory(directory, { maxSkillBytes? })` on `@arnilo/prism/node/contribution-discovery` loads a host-supplied `<dir>/<name>/SKILL.md` tree into inert `Skill[]`: one level, sorted, symlink-contained, per-file cap 262 144 bytes by default. It replaces the bounded reader the deleted persona subpaths carried. See [docs/contribution-discovery.md](docs/contribution-discovery.md).
 - **Examples.** `examples/scoped-memory.ts` (scope guard → facts overflow → reviewer → abstain/hit recall → promotion → GC approval → mirror), `examples/hooks-json.ts` (a declarative `hooks.json` compiled onto guardrails, injectors, and stop hooks), and `examples/hooks-audit-command.mjs` (an audit-trail command handler).
 
 ### Changed
@@ -19,6 +47,9 @@
 - **Coverage thresholds gained the new package's row** (`@arnilo/prism-hooks` 84.7 / 78.67 / 90), so the coverage summary fails closed on a new package instead of passing silently.
 - **Migration notes for 0.9.0 hosts**: [docs/migration.md](docs/migration.md) — the `AgentSession.close()` addition, `session_start` / `session_shutdown` now being emitted, the new `hook_limit` finish reason, the `maxStopContinuations` default, and the opt-in scoped-memory subpath.
 
+### Removed
+- None in the published 0.10.0 tarball. A post-publish amendment recorded the persona and graft subpath removals here; they ship in 0.11.0 (see the section above).
+
 ### Security
 - **Stop hooks and the hooks-file adapter fail closed.** `StopHook` entries are validated at run start (`name` plus `decide`), a malformed decision or a throwing handler is a non-blocking error that never silently allows a stop, `maxStopContinuations` (default 3) bounds continuation loops, and the adapter's `command` handlers spawn shell-free with tokenized argv and a `hookCommandHash()` trust pin. Codex's `continue: false` reads as the stop signal, not a continuation.
 - **Scoped memory never widens access and never deletes.** Create fails closed on a scope mismatch, unknown policy fields are ignored and invalid values fail closed, recall abstains below the floor, GC only proposes, `legal_hold` is skipped, the ledger stores no note content, and the mirror is deterministic.

package/README.md

@@ -162,28 +162,30 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.10.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-channels` | 0.10.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.10.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.10.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
-| `@arnilo/prism-providers` | 0.10.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.10.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.10.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-hooks` | 0.10.0 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams |
-| `@arnilo/prism-mcp` | 0.10.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.10.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-web-tools` | 0.10.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
-| `@arnilo/prism-work` | 0.10.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
+| `@arnilo/prism` | 0.11.1 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-channels` | 0.11.1 | 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.11.1 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.11.1 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
+| `@arnilo/prism-providers` | 0.11.1 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.11.1 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.11.1 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-hooks` | 0.11.1 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams |
+| `@arnilo/prism-mcp` | 0.11.1 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.11.1 | capability — memory plus /rag, /compaction/*, /fabric, /wiki subpaths |
+| `@arnilo/prism-web-tools` | 0.11.1 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism-work` | 0.11.1 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts
 
 | command | action |
 |---------|--------|
-| `npm run build` | Compile TypeScript to `dist/` (core + workspaces) |
-| `npm run typecheck` | Type-check without emitting |
-| `npm test` | Build + run network-free tests |
-| `npm run test:live` | Run live suites whose credentials are present (skip the rest) |
+| `bun ci` | Install dependencies from the committed `bun.lock` (frozen) |
+| `bun run build` | Compile TypeScript to `dist/` (core + workspaces) |
+| `bun run typecheck` | Type-check without emitting |
+| `bun run test` | Build + run network-free tests (`npm test` still works) |
+| `bun run test:coverage` | Coverage gate: `bun test --coverage` over the core suite and every gated workspace, with Bun-measured floors (`scripts/coverage-thresholds.json`) |
+| `bun run test:live` | Run live suites whose credentials are present (skip the rest) |
 | `prism --help` | CLI help |
 
 ## Non-goals (v1)

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

@@ -15,7 +15,8 @@ export interface AgentRunLifecycleOptions {
     /**
      * 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).
+     * stored state (there is no live session to register against beforehand). Plan 109 Task 2: an
+     * entry may be `{ id?, restore, compensate? }` so a failed resume rolls the applied layers back.
      */
     readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
     /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */

package/dist/agent-run-lifecycle.js

@@ -317,7 +317,7 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
             status: state.status,
             ...(recordMetadata ? { metadata: recordMetadata } : {}),
             checkpoint: record,
-        }, { timeoutMs: options.restoreHookTimeoutMs, signal })
+        }, { timeoutMs: options.restoreHookTimeoutMs, signal, redactor: agent.config.redactor })
         : undefined;
     throwIfAbortedSignal(signal);
     const claimed = await saveAgentRunState({

package/dist/agent-session/session/assemble.js

@@ -753,15 +753,12 @@ export async function executeRun(session, input, options, runId, resumed) {
         }
         runError = errorToErrorInfo(error);
         const breach = error instanceof RunLimitError ? error.breach : limits.breach;
+        // Built once: the event and the terminal result carry the same attribution payload (plan 108 T5).
+        const exhaustion = breach ? describeBudgetExhaustion(limits, breach, session.activeRecentToolCalls ?? []) : undefined;
         // Terminal attribution before the terminal `error`/finish records, so a subscriber that stops
         // at the first terminal event still sees why the run died (plan 087 T2).
-        if (breach) {
-            session.emit({
-                type: "budget_exhausted",
-                sessionId: session.id,
-                runId,
-                ...describeBudgetExhaustion(limits, breach, session.activeRecentToolCalls ?? []),
-            });
+        if (exhaustion) {
+            session.emit({ type: "budget_exhausted", sessionId: session.id, runId, ...exhaustion });
         }
         session.emit({ type: "error", sessionId: session.id, runId, error: runError });
         runStatus = breach ? "failed" : controller.signal.aborted ? "aborted" : "failed";
@@ -781,6 +778,11 @@ export async function executeRun(session, input, options, runId, resumed) {
             status: runStatus,
             usage: runUsage.value() ?? usage,
             limit: breach,
+            attribution: exhaustion && {
+                consumed: exhaustion.consumed,
+                closestOtherAxes: exhaustion.closestOtherAxes,
+                recentToolCalls: exhaustion.recentToolCalls,
+            },
             error: runError,
             abortReason: !breach && controller.signal.aborted ? String(controller.signal.reason) : undefined,
             runState,

package/dist/agent-session/session/tool-round.js

@@ -2,8 +2,8 @@
 import { AgentRunSuspended, decisionIdentityRef, decisionScopesEqual, nestedApprovalId, nestedOutcomeToolResult, pathsEqual, } from "../../agent-approval.js";
 import { toolElicitationRequest } from "../../agent-tool-dispatch.js";
 import { AgentDecisionError, AgentDelegationSuspendedError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_DECISIONS, MAX_ATTRIBUTION_DEPTH, } from "../../contracts.js";
-import { toToolResultMessage } from "../../input.js";
 import { runGuardrails } from "../../guardrails.js";
+import { toToolResultMessage } from "../../input.js";
 import { canonicalToolEffectJson, toolEffectArgumentsHash } from "../../tool-effects.js";
 import { dispatchToolCall, resolveToolEffectDeclaration } from "../../tools.js";
 import { randomId } from "../helpers.js";
@@ -148,6 +148,16 @@ export async function applyNestedRun(session, input) {
         return { toolResult: nestedOutcomeToolResult(outcome, input.toolCall.id, input.toolCall.name) };
     }
 }
+function buildRunInterruption(input) {
+    return {
+        kind: input.kind,
+        reason: input.reason,
+        ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
+        ...(input.toolName ? { toolName: input.toolName } : {}),
+        ...(input.guardrail ? { guardrail: input.guardrail } : {}),
+        pendingDecisions: input.decisions,
+    };
+}
 export async function suspendGatedRound(ctx) {
     const gated = ctx.session.activeGatedRound;
     if (!gated?.size)
@@ -155,14 +165,14 @@ export async function suspendGatedRound(ctx) {
     const entries = [...gated.values()];
     const decisions = entries.map((gatedCall) => gatedCall.decision);
     const single = decisions.length === 1 ? decisions[0] : undefined;
-    const interruption = {
+    const interruption = buildRunInterruption({
+        decisions,
         kind: single?.kind === "elicitation" ? "elicitation" : "tool_approval",
         reason: single ? single.reason : `${decisions.length} tool side effects require approval`,
-        ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
-        ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
-        ...(single?.guardrail ? { guardrail: single.guardrail } : {}),
-        pendingDecisions: decisions,
-    };
+        toolCallId: single?.toolCallId,
+        toolName: single?.scope.toolName,
+        guardrail: single?.guardrail,
+    });
     throw new AgentRunSuspended(await suspendDurable(ctx.session, {
         runId: ctx.runId,
         model: ctx.model,
@@ -195,13 +205,13 @@ export async function suspendNested(ctx, nested) {
         throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Pending decisions exceed ${HARD_MAX_PENDING_DECISIONS} per run`);
     }
     const single = decisions.length === 1 ? decisions[0] : undefined;
-    const interruption = {
+    const interruption = buildRunInterruption({
+        decisions,
         kind: single?.kind ?? "tool_approval",
         reason: single ? single.reason : `${decisions.length} approval request(s) need a decision`,
-        ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
-        ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
-        pendingDecisions: decisions,
-    };
+        toolCallId: single?.toolCallId,
+        toolName: single?.scope.toolName,
+    });
     throw new AgentRunSuspended(await suspendDurable(ctx.session, {
         runId: ctx.runId,
         model: ctx.model,
@@ -384,13 +394,13 @@ export function bindDispatchToolCall(ctx) {
                         return;
                     const approvalId = randomId("approval");
                     const decision = buildPendingDecision(ctx.session, mediatedCall, approvalId, ctx.registry, ctx.runId, ctx.metadata, ctx.controller.signal);
-                    const interruption = {
+                    const interruption = buildRunInterruption({
+                        decisions: [decision],
                         kind: "tool_approval",
                         reason: decision.reason,
                         toolCallId: mediatedCall.id,
                         toolName: mediatedCall.name,
-                        pendingDecisions: [decision],
-                    };
+                    });
                     throw new AgentRunSuspended(await suspendDurable(ctx.session, {
                         runId: ctx.runId,
                         model: ctx.model,
@@ -477,13 +487,13 @@ export async function replayDurableNestedAndPending(ctx) {
         if (remainingOwn.length > 0 || surfacedPending.length > 0) {
             const pendingDecisions = [...remainingOwn, ...surfacedPending];
             const single = pendingDecisions.length === 1 ? pendingDecisions[0] : undefined;
-            const interruption = {
+            const interruption = buildRunInterruption({
+                decisions: pendingDecisions,
                 kind: single?.kind ?? "tool_approval",
                 reason: `${pendingDecisions.length} approval request(s) remain`,
-                ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
-                ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
-                pendingDecisions,
-            };
+                toolCallId: single?.toolCallId,
+                toolName: single?.scope.toolName,
+            });
             throw new AgentRunSuspended(await suspendDurable(session, {
                 runId: ctx.runId,
                 model: ctx.model,

package/dist/agent-session/session/types.d.ts

@@ -107,6 +107,7 @@ export type SessionHost = {
         readonly status: AgentRunResult["status"];
         readonly usage?: Usage;
         readonly limit?: import("../../contracts.js").RunLimitBreach;
+        readonly attribution?: import("../../run-limits.js").BudgetExhaustionAttribution;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
         readonly runState?: import("../../contracts.js").AgentRunState;

package/dist/agent-session/session.d.ts

@@ -183,6 +183,7 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly status: AgentRunResult["status"];
         readonly usage?: Usage;
         readonly limit?: import("../contracts.js").RunLimitBreach;
+        readonly attribution?: import("../run-limits.js").BudgetExhaustionAttribution;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
         readonly stopReason?: import("../contracts.js").AgentFinishReason;

package/dist/agent-session/session.js

@@ -422,6 +422,7 @@ export class RuntimeAgentSession {
             message: final.message,
             usage: input.usage,
             limit: input.limit,
+            attribution: input.attribution,
             error: input.error,
             abortReason: input.abortReason,
             stopReason: input.stopReason,
@@ -486,8 +487,8 @@ export class RuntimeAgentSession {
         });
     }
     branchReader() {
-        // ponytail: prefer the store's readBranchPath (one ancestor-chain query) when present so a
-        // DB-backed store never loads the full session; else fall back to list() + in-memory walk.
+        // ponytail: prefer readBranchPath when present (memory, SQLite, Postgres) so snapshot does
+        // not list() the whole session. JSONL and other omitters fall back to list() + in-memory walk.
         const read = this.store.readBranchPath;
         return read ? (query) => read.call(this.store, query) : undefined;
     }

package/dist/checkpoint-restore.d.ts

@@ -1,12 +1,17 @@
 /**
- * Checkpoint restore hooks (plan 094 Task 3). A hook restores one external layer (git commit,
- * document version, workspace fingerprint) recorded in a checkpoint's sidecar metadata.
+ * Checkpoint restore hooks (plan 094 Task 3; reverse compensation plan 109 Task 2). A hook restores
+ * one external layer (git commit, document version, workspace fingerprint) recorded in a
+ * checkpoint's sidecar metadata.
  *
- * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails
- * or times out aborts the resume with `CheckpointRestoreError` naming that hook, so the
- * conversation restore never applies on top of a half-restored external world. Hosts that need
- * every layer back where they were re-run the whole restore after fixing the failing layer.
+ * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails or
+ * times out aborts the resume with `CheckpointRestoreError` naming that hook, so the conversation
+ * restore never applies on top of a half-restored external world. A handler may also declare a
+ * `compensate` direction: on failure the applied layers — including the failing one, which may be
+ * half-applied — are undone in reverse order and the error carries a best-effort
+ * `CheckpointRestoreCompensation` report. Compensation never runs after the caller aborted, never
+ * masks the original failure, and the checkpoint stays resumable either way.
  */
+import type { SecretRedactor } from "./redaction.js";
 /** Per-hook ceiling for a restore (plan 094 Task 3 default). */
 export declare const DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS = 10000;
 /** One hook that completed during a restore. */
@@ -20,26 +25,57 @@ export interface CheckpointRestoreAudit {
     readonly durationMs: number;
 }
 /**
- * Host code restoring one external layer. `signal` aborts on the per-hook timeout and on the
- * caller's abort, so a hook that talks to a remote system can cancel instead of dangling.
+ * Host code restoring or compensating one external layer. `signal` aborts on the per-hook timeout
+ * and on the caller's abort, so a hook that talks to a remote system can cancel instead of dangling.
  */
 export type CheckpointRestoreHook<Context> = (checkpoint: Context, signal: AbortSignal) => void | Promise<void>;
+/** Object form of a restore handler: an identity plus the layer's undo direction (plan 109 Task 2). */
+interface CheckpointRestoreHandlerObject<Context> {
+    /** Stable name reported in the audit and in `CheckpointRestoreError.compensation`; defaults to the restore hook's name, then `hook[i]`. */
+    readonly id?: string;
+    readonly restore: CheckpointRestoreHook<Context>;
+    /** Undo for this layer, run when a later hook — or this one — fails. Absent = the layer has no undo. */
+    readonly compensate?: CheckpointRestoreHook<Context>;
+}
+/**
+ * A restore handler: today's bare function, or `{ id?, restore, compensate? }` to declare an undo
+ * direction. Bare functions behave exactly as in plan 094 and are never compensated.
+ */
+export type CheckpointRestoreHandler<Context> = CheckpointRestoreHook<Context> | CheckpointRestoreHandlerObject<Context>;
+/** Best-effort record of the reverse compensation pass after a failed restore (plan 109 Task 2). */
+export interface CheckpointRestoreCompensation {
+    /** Names of the hooks whose `compensate` ran, most recently applied layer first. */
+    readonly ran: readonly string[];
+    /** First compensation that failed; the pass still continues with the remaining layers. */
+    readonly failed?: {
+        readonly hook: string;
+        readonly reason: string;
+    };
+}
 /** Thrown when a restore hook fails or times out; the checkpoint and conversation are untouched. */
 export declare class CheckpointRestoreError extends Error {
     readonly code = "ERR_PRISM_CHECKPOINT_RESTORE";
-    /** Name of the failing hook (`fn.name` or `hook[i]`). */
+    /** Name of the failing hook (`id`, `hook.name`, or `hook[i]`). */
     readonly hook: string;
-    constructor(hook: string, cause: unknown);
+    /** Present only when at least one `compensate` ran; omitted otherwise, as in plan 094. */
+    readonly compensation?: CheckpointRestoreCompensation;
+    constructor(hook: string, cause: unknown, compensation?: CheckpointRestoreCompensation);
 }
 export interface RunCheckpointRestoreHooksOptions {
     /** Per-hook timeout; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
     readonly timeoutMs?: number;
     /** Caller abort: checked between hooks and combined into each hook's signal. */
     readonly signal?: AbortSignal;
+    /** Applied to the bounded compensation reason; absent = the message is reported as-is (still capped). */
+    readonly redactor?: SecretRedactor;
 }
 /**
- * Run restore hooks sequentially and report the audit. A hook failure throws
- * `CheckpointRestoreError` immediately (later hooks do not run); an already-aborted caller signal
- * throws its own abort reason so the resume reads as cancelled rather than as a restore failure.
+ * Run restore handlers sequentially and report the audit. A handler failure throws
+ * `CheckpointRestoreError` immediately (later handlers do not run) after a best-effort reverse
+ * compensation pass over the applied layers; with no `compensate` declared anywhere, the failure
+ * shape is exactly plan 094's. An already-aborted caller signal throws its own abort reason so the
+ * resume reads as cancelled rather than as a restore failure, and a caller abort during the pass
+ * stops it before the next handler runs.
  */
-export declare function runCheckpointRestoreHooks<Context>(hooks: readonly CheckpointRestoreHook<Context>[], context: Context, options?: RunCheckpointRestoreHooksOptions): Promise<CheckpointRestoreAudit>;
+export declare function runCheckpointRestoreHooks<Context>(hooks: readonly CheckpointRestoreHandler<Context>[], context: Context, options?: RunCheckpointRestoreHooksOptions): Promise<CheckpointRestoreAudit>;
+export {};

package/dist/checkpoint-restore.js

@@ -1,53 +1,129 @@
 /**
- * Checkpoint restore hooks (plan 094 Task 3). A hook restores one external layer (git commit,
- * document version, workspace fingerprint) recorded in a checkpoint's sidecar metadata.
+ * Checkpoint restore hooks (plan 094 Task 3; reverse compensation plan 109 Task 2). A hook restores
+ * one external layer (git commit, document version, workspace fingerprint) recorded in a
+ * checkpoint's sidecar metadata.
  *
- * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails
- * or times out aborts the resume with `CheckpointRestoreError` naming that hook, so the
- * conversation restore never applies on top of a half-restored external world. Hosts that need
- * every layer back where they were re-run the whole restore after fixing the failing layer.
+ * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails or
+ * times out aborts the resume with `CheckpointRestoreError` naming that hook, so the conversation
+ * restore never applies on top of a half-restored external world. A handler may also declare a
+ * `compensate` direction: on failure the applied layers — including the failing one, which may be
+ * half-applied — are undone in reverse order and the error carries a best-effort
+ * `CheckpointRestoreCompensation` report. Compensation never runs after the caller aborted, never
+ * masks the original failure, and the checkpoint stays resumable either way.
  */
 /** Per-hook ceiling for a restore (plan 094 Task 3 default). */
 export const DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS = 10_000;
 /** Thrown when a restore hook fails or times out; the checkpoint and conversation are untouched. */
 export class CheckpointRestoreError extends Error {
     code = "ERR_PRISM_CHECKPOINT_RESTORE";
-    /** Name of the failing hook (`fn.name` or `hook[i]`). */
+    /** Name of the failing hook (`id`, `hook.name`, or `hook[i]`). */
     hook;
-    constructor(hook, cause) {
+    constructor(hook, cause, compensation) {
         super(`Checkpoint restore hook ${hook} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
         this.name = "CheckpointRestoreError";
         this.hook = hook;
+        if (compensation)
+            this.compensation = compensation;
     }
 }
+/** Compensation reasons are operator hints, not log lines: capped at this many UTF-8 bytes. */
+const MAX_COMPENSATION_REASON_BYTES = 1_024;
+/** One handler identity per restore, resolved once at the executor boundary (plan 109 Task 2). */
+function normalizeRestoreHandler(handler, index) {
+    if (typeof handler === "function")
+        return { id: handler.name || `hook[${index}]`, restore: handler };
+    return {
+        id: handler.id ?? handler.restore.name ?? `hook[${index}]`,
+        restore: handler.restore,
+        ...(handler.compensate ? { compensate: handler.compensate } : {}),
+    };
+}
+/** Run one direction of one handler under the per-hook timeout, reporting failure instead of throwing. */
+async function invokeRestoreHandler(handler, context, timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    const started = Date.now();
+    try {
+        await handler(context, signal);
+        return { ok: true, durationMs: Date.now() - started };
+    }
+    catch (error) {
+        // Our own abort means the hook either ignored the signal or lost the race; name the timeout.
+        const timedOut = controller.signal.aborted && !callerSignal?.aborted;
+        return { ok: false, cause: timedOut ? controller.signal.reason : error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** UTF-8-safe truncation; no suffix, so the cap is exact. */
+function truncateUtf8Bytes(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    let bytes = 0;
+    let end = 0;
+    for (const char of text) {
+        const size = Buffer.byteLength(char, "utf8");
+        if (bytes + size > maxBytes)
+            break;
+        bytes += size;
+        end += char.length;
+    }
+    return text.slice(0, end);
+}
+/** Redacted, byte-bounded operator hint; hook arguments are never copied into it. */
+function compensationReason(error, redactor) {
+    const message = error instanceof Error ? error.message : String(error);
+    return truncateUtf8Bytes(redactor ? redactor.redact(message) : message, MAX_COMPENSATION_REASON_BYTES);
+}
 /**
- * Run restore hooks sequentially and report the audit. A hook failure throws
- * `CheckpointRestoreError` immediately (later hooks do not run); an already-aborted caller signal
- * throws its own abort reason so the resume reads as cancelled rather than as a restore failure.
+ * Reverse pass over the applied layers (`failedIndex`…0, failing hook first). Best-effort: a
+ * failing compensation is recorded once and the pass continues; a caller abort stops the pass and
+ * rethrows the abort reason unchanged, so a cancel still reads as cancelled.
+ */
+async function compensateRestoreHandlers(handlers, failedIndex, context, timeoutMs, options) {
+    const ran = [];
+    let failed;
+    for (let index = failedIndex; index >= 0; index -= 1) {
+        const handler = handlers[index];
+        if (!handler?.compensate)
+            continue;
+        options.signal?.throwIfAborted();
+        const outcome = await invokeRestoreHandler(handler.compensate, context, timeoutMs, options.signal);
+        options.signal?.throwIfAborted();
+        ran.push(handler.id);
+        if (!outcome.ok && failed === undefined)
+            failed = { hook: handler.id, reason: compensationReason(outcome.cause, options.redactor) };
+    }
+    if (ran.length === 0)
+        return undefined;
+    return { ran, ...(failed ? { failed } : {}) };
+}
+/**
+ * Run restore handlers sequentially and report the audit. A handler failure throws
+ * `CheckpointRestoreError` immediately (later handlers do not run) after a best-effort reverse
+ * compensation pass over the applied layers; with no `compensate` declared anywhere, the failure
+ * shape is exactly plan 094's. An already-aborted caller signal throws its own abort reason so the
+ * resume reads as cancelled rather than as a restore failure, and a caller abort during the pass
+ * stops it before the next handler runs.
  */
 export async function runCheckpointRestoreHooks(hooks, context, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS;
     const started = Date.now();
     const entries = [];
-    for (const [index, hook] of hooks.entries()) {
+    const handlers = hooks.map((handler, index) => normalizeRestoreHandler(handler, index));
+    for (const [index, handler] of handlers.entries()) {
         options.signal?.throwIfAborted();
-        const name = hook.name || `hook[${index}]`;
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
-        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-        const hookStarted = Date.now();
-        try {
-            await hook(context, signal);
-        }
-        catch (error) {
-            // Our own abort means the hook either ignored the signal or lost the race; name the timeout.
-            const timedOut = controller.signal.aborted && !options.signal?.aborted;
-            throw new CheckpointRestoreError(name, timedOut ? controller.signal.reason : error);
-        }
-        finally {
-            clearTimeout(timer);
+        const outcome = await invokeRestoreHandler(handler.restore, context, timeoutMs, options.signal);
+        if (!outcome.ok) {
+            // Security: never run host compensation code once the caller has aborted.
+            const compensation = options.signal?.aborted
+                ? undefined
+                : await compensateRestoreHandlers(handlers, index, context, timeoutMs, options);
+            throw new CheckpointRestoreError(handler.id, outcome.cause, compensation);
         }
-        entries.push({ hook: name, durationMs: Date.now() - hookStarted });
+        entries.push({ hook: handler.id, durationMs: outcome.durationMs });
     }
     return { hooks: entries, durationMs: Date.now() - started };
 }

package/dist/contracts-core/session.d.ts

@@ -30,7 +30,8 @@ export interface SessionStore {
     get?(id: string): Promise<SessionEntry | undefined>;
     /** DB-friendly branch read: return one branch's ancestor chain as a page so adapters
      *  avoid `list(sessionId)` (full-session scan) + in-memory rebuild. Optional — the
-     *  built-in memory/JSONL stores omit it and the runtime falls back to `list()`. */
+     *  built-in JSONL store omits it and the runtime falls back to `list()`. The memory
+     *  store implements it. */
     readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;
     /**
      * Optional bounded session search. Prefer implementing this **or** returning a companion

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

@@ -1,6 +1,7 @@
-import type { CheckpointRestoreHook } from "./checkpoint-restore.js";
+import type { CheckpointRestoreHandler } from "./checkpoint-restore.js";
 import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, GuardrailPackRef, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
 import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
+import type { BudgetExhaustionAttribution } from "./run-limits.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
 export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
@@ -247,8 +248,8 @@ export interface AgentCheckpointRestoreContext {
     readonly metadata?: AgentRunCheckpointMetadata;
     readonly checkpoint: CheckpointRecord;
 }
-/** Host code restoring one external layer before a durable resume applies. */
-export type AgentCheckpointRestoreHook = CheckpointRestoreHook<AgentCheckpointRestoreContext>;
+/** Host code restoring or compensating one external layer before a durable resume applies. */
+export type AgentCheckpointRestoreHook = CheckpointRestoreHandler<AgentCheckpointRestoreContext>;
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
     /** Current host-authored revision; must exactly match the checkpoint. */
@@ -278,7 +279,9 @@ export interface AgentRunResumeOptions {
      * Plan 094 Task 3: external-state restore hooks. Every hook must succeed (sequentially, each
      * within `restoreHookTimeoutMs`) before the claim write and the conversation restore apply;
      * the first failure throws `CheckpointRestoreError` naming the hook and leaves the checkpoint
-     * suspended. Hosts that register hooks on the lifecycle instead pass them once there.
+     * suspended. Plan 109 Task 2: an entry may be `{ id?, restore, compensate? }`, and on failure the
+     * applied layers are compensated in reverse order (best-effort) before the throw. Hosts that
+     * register hooks on the lifecycle instead pass them once there.
      */
     readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
     /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
@@ -325,6 +328,11 @@ export interface AgentRunResult {
     readonly usage?: Usage;
     /** Present when the run hit a configured resource ceiling. */
     readonly limit?: RunLimitBreach;
+    /**
+     * Present with `limit` when the run died on a ceiling: the same plan-087 attribution payload the
+     * `budget_exhausted` event carries (`limit` stays on {@link AgentRunResult.limit}).
+     */
+    readonly attribution?: BudgetExhaustionAttribution;
     /** Present when `status` is `"failed"` or when a failed attempt still produced partial output. */
     readonly error?: ErrorInfo;
     /** String form of the abort reason when `status` is `"aborted"`. */