@arnilo/prism 0.7.0 → 0.9.0

package/dist/testing/prefix-stability-conformance.js

@@ -0,0 +1,104 @@
+// ponytail: dependency-free conformance runner for prompt-cache prefix stability.
+// The runner owns the fixture provider (network-free, deterministic) and fixture
+// skills; everything else in `host` is the caller's production assembly — system
+// prompt, context providers, prompt builder, middleware, disclosure settings.
+// Throws plain Error; no test runner, no network, no credentials.
+import assert from "node:assert/strict";
+import { createAgent } from "../agent-session/create-agent.js";
+import { providerDone, toolCallContent } from "../provider-events.js";
+import { createLoadSkillTool } from "../skill-load.js";
+import { createSkillRegistry } from "../skills.js";
+/**
+ * Drive a real session through two staggered skill loads and assert that each
+ * provider request keeps a byte-identical leading prefix (messages **and** tool
+ * schemas) with its predecessor. Progressive disclosure appends a loaded body
+ * after the stable prefix, so the shared prefix stays intact; a host that
+ * rewrites the context block, the skill catalog, or any leading message per
+ * request fails with the offending request pair and the measured fraction.
+ */
+export async function runPrefixStabilityConformance(options) {
+    const { host, skills } = options;
+    const minContinuity = options.minContinuity ?? 0.95;
+    const [first, second] = skills;
+    assert.notEqual(first.name, second.name, "prefix stability conformance needs two distinct skills");
+    const bodies = [];
+    for (const skill of skills) {
+        const instructions = skill.instructions;
+        assert.ok(typeof instructions === "string" && instructions.length > 0, `prefix stability conformance skill ${skill.name} needs non-empty instructions`);
+        bodies.push(instructions);
+    }
+    const requests = [];
+    const registry = createSkillRegistry([...skills]);
+    const hostTools = host.tools && "list" in host.tools ? host.tools.list() : (host.tools ?? []);
+    const agent = createAgent({
+        ...host,
+        skills: registry,
+        tools: [...hostTools, createLoadSkillTool({ registry })],
+        provider: fixtureProvider(requests, [first.name, second.name]),
+    });
+    const session = agent.createSession();
+    const [firstInput, secondInput] = options.inputs ?? ["Prefix stability turn one", "Prefix stability turn two"];
+    const runOptions = { activeSkills: [first.name, second.name], limits: { maxToolRounds: 1 } };
+    await session.run(firstInput, runOptions);
+    await session.run(secondInput, runOptions);
+    assert.equal(requests.length, 4, `prefix stability conformance expected 4 provider requests (2 per staggered turn), captured ${requests.length}`);
+    const serialized = requests.map(serializeRequest);
+    // Guard against a vacuous pass: both bodies must have been disclosed by the end.
+    const last = serialized.at(-1) ?? "";
+    for (const [index, skill] of skills.entries()) {
+        assert.ok(last.includes(bodies[index] ?? ""), `prefix stability conformance: skill ${skill.name} body never reached the provider request — progressive disclosure did not expand it`);
+    }
+    let observed = 1;
+    let previous = serialized.at(0) ?? "";
+    for (let index = 1; index < serialized.length; index += 1) {
+        const next = serialized[index] ?? "";
+        const fraction = sharedPrefixFraction(previous, next);
+        observed = Math.min(observed, fraction);
+        assert.ok(fraction >= minContinuity, `prefix stability conformance: request ${index} → ${index + 1} kept ${(fraction * 100).toFixed(1)}% of the previous provider prefix ` +
+            `(minimum ${(minContinuity * 100).toFixed(1)}%). Late skill bodies must append after the stable prefix; ` +
+            "recomposed context, an in-place skill-catalog rewrite, or any leading-message mutation invalidates it.");
+        previous = next;
+    }
+    return { requests: serialized.length, minContinuity: observed };
+}
+/** Fixture provider: turn 1 loads `skillNames[0]`, turn 2 loads `skillNames[1]`, everything else completes. */
+function fixtureProvider(requests, skillNames) {
+    let call = 0;
+    return {
+        id: "prefix-stability-fixture",
+        async *generate(request) {
+            requests.push(request);
+            const index = call;
+            call += 1;
+            const skillName = skillNames[index >> 1];
+            if (index % 2 === 0 && skillName !== undefined) {
+                yield { type: "tool_call", call: toolCallContent(`prefix-stability-${index}`, "load_skill", { name: skillName }) };
+                return;
+            }
+            yield providerDone();
+        },
+    };
+}
+/** Provider-visible payload only: messages plus the tool schema fields sent on the wire. */
+function serializeRequest(request) {
+    // One JSON fragment per message/tool so a structural array boundary never reads as a byte
+    // divergence: an appended message list stays an exact prefix of the next request.
+    const parts = [
+        ...(request.tools ?? []).map((tool) => JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters })),
+        ...request.messages.map((message) => JSON.stringify(message)),
+    ];
+    return parts.join("\n");
+}
+/** Byte-shared prefix as a fraction of the previous request, so a shrink is a cache miss. */
+function sharedPrefixFraction(previous, next) {
+    const before = Buffer.from(previous, "utf8");
+    const after = Buffer.from(next, "utf8");
+    if (before.length === 0)
+        return 1;
+    const limit = Math.min(before.length, after.length);
+    let shared = 0;
+    while (shared < limit && before[shared] === after[shared])
+        shared += 1;
+    return shared / before.length;
+}
+//# sourceMappingURL=prefix-stability-conformance.js.map

package/dist/testing/session-store-conformance.d.ts

@@ -11,8 +11,9 @@ export interface SessionStoreConformanceOptions {
      */
     readonly exerciseReadBranchPath?: boolean;
     /**
-     * When true, exercises optional `searchSessions` (empty page, limit cap,
-     * invalid limit/query rejection via `resolveSessionSearchQuery` semantics).
+     * When true, exercises optional `searchSessions`: invalid limit/query/kind rejection via
+     * `resolveSessionSearchQuery` semantics, empty page, limit cap, a written-message query
+     * round-trip (`entryId`/`runId`/`turn`/`snippet`), the `kind` filter, and ownership bounds.
      * Skipped when the store does not implement `searchSessions`.
      */
     readonly exerciseSearchSessions?: boolean;

package/dist/testing/session-store-conformance.js

@@ -113,6 +113,54 @@ async function assertSessionStoreSearchSessions(store) {
     await reject(() => search({ limit: Number.NaN }), (error) => error instanceof TypeError, "searchSessions must reject NaN limit");
     await reject(() => search({ limit: HARD_MAX_SESSION_SEARCH_LIMIT + 1 }), (error) => error instanceof TypeError, "searchSessions must reject oversize limit");
     await reject(() => search({ query: "x".repeat(HARD_MAX_SESSION_SEARCH_QUERY_BYTES + 1) }), (error) => error instanceof TypeError, "searchSessions must reject oversize query string");
+    await reject(() => search({ kind: "not-an-entry-kind" }), (error) => error instanceof TypeError, "searchSessions must reject an unknown kind");
+    // Query round-trip: a written message must be findable and the hit must point at it.
+    const searchSessionId = "conformance-search";
+    const token = "zzconformancesearchtoken";
+    const matchedEntry = {
+        id: "conformance-search-entry",
+        sessionId: searchSessionId,
+        timestamp: "2026-01-01T00:00:05.000Z",
+        kind: "message",
+        runId: "conformance-run",
+        message: { role: "user", content: [{ type: "text", text: `${token} body text` }] },
+    };
+    await store.append(matchedEntry);
+    const found = await search({ query: token, limit: 5 });
+    const hit = found.items.find((item) => item.sessionId === searchSessionId);
+    if (!hit) {
+        throw new Error("searchSessions must find a session by matching message text");
+    }
+    if (hit.entryId !== matchedEntry.id) {
+        throw new Error(`searchSessions must point at the matched entry; got ${String(hit.entryId)}`);
+    }
+    if (hit.runId !== matchedEntry.runId) {
+        throw new Error("searchSessions must carry the matched entry runId");
+    }
+    if (typeof hit.snippet !== "string" || !hit.snippet.includes(token)) {
+        throw new Error("searchSessions snippet must contain the matched text");
+    }
+    if (!Number.isSafeInteger(hit.turn) || hit.turn < 1) {
+        throw new Error("searchSessions must carry a 1-based matched-entry turn index");
+    }
+    const annotationOnly = await search({ query: token, kind: "summary", limit: 5 });
+    if (annotationOnly.items.some((item) => item.sessionId === searchSessionId)) {
+        throw new Error("searchSessions kind filter must exclude non-matching entry kinds");
+    }
+    // One hit per session: a second matching entry must not add a second row for the same session.
+    await store.append({
+        id: "conformance-search-entry-2",
+        parentId: matchedEntry.id,
+        sessionId: searchSessionId,
+        timestamp: "2026-01-01T00:00:06.000Z",
+        kind: "summary",
+        summary: `${token} recap`,
+    });
+    const deduped = await search({ query: token, limit: 5 });
+    const sessionHits = deduped.items.filter((item) => item.sessionId === searchSessionId);
+    if (sessionHits.length !== 1) {
+        throw new Error(`searchSessions must return one hit per session; got ${sessionHits.length}`);
+    }
     const empty = await search(resolveSessionSearchQuery({
         workspaceRoot: "__prism_conformance_empty__",
         limit: 5,

package/dist/testing/state-concurrency-conformance.js

@@ -68,7 +68,11 @@ async function checkpointCasProbe(checkpoints) {
     const loaded = await checkpoints.loadCheckpoint(key);
     assert.equal(loaded?.version, 4, "winning version must persist");
     assert.equal(loaded?.fencingToken, 6, "winning fence must persist");
-    await assertRejects(() => checkpoints.loadCheckpoint({ ...key, tenantId: "tenant-b" }), /ownership|tenant/i, "foreign checkpoint access must fail closed");
+    const foreign = await checkpoints.loadCheckpoint({ ...key, tenantId: "tenant-b" });
+    assert.equal(foreign, null, "a foreign checkpoint lands as a miss, not an ownership-shaped existence oracle");
+    await assertRejectsCode(() => checkpoints.saveCheckpoint({ ...key, tenantId: "tenant-b", version: 99, expectedVersion: 0, value: { evil: true } }), "ERR_PRISM_CHECKPOINT_CONFLICT", "a foreign checkpoint save must fail closed as a CAS conflict");
+    const intact = await checkpoints.loadCheckpoint(key);
+    assert.equal(intact?.version, 4, "a foreign writer must not disturb the owner's record");
 }
 /**
  * Approval determinism: concurrent approve/deny of the same pending decision
@@ -334,15 +338,4 @@ async function assertRejectsCode(action, code, message) {
     }
     throw new Error(`${message}; expected a rejection with code ${code}`);
 }
-async function assertRejects(action, pattern, message) {
-    try {
-        await action();
-    }
-    catch (error) {
-        if (pattern.test(String(error)))
-            return;
-        throw new Error(`${message}; rejection did not match ${pattern}: ${String(error)}`);
-    }
-    throw new Error(`${message}; expected a rejection matching ${pattern}`);
-}
 //# sourceMappingURL=state-concurrency-conformance.js.map

package/dist/tools.d.ts

@@ -58,6 +58,11 @@ export declare function createToolRegistry(tools?: readonly ToolDefinition[], op
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 /** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
 export declare const HARD_RUN_TOOL_NAMES = 1024;
+/** Restrictive clamp: keep listed order; names outside the grant are dropped (not thrown). */
+export declare function clampTurnToolNames(listed: readonly ToolDefinition[], requested: readonly string[]): {
+    readonly tools: readonly ToolDefinition[];
+    readonly dropped: readonly string[];
+};
 /**
  * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
  * Fresh unknown names fail closed; resume drops names the current registry no longer has.

package/dist/tools.js

@@ -61,15 +61,15 @@ export function filterTools(tools, filter) {
 /** Cap matches tool-search index; run allow-lists never exceed the disclosed set. */
 export const HARD_RUN_TOOL_NAMES = 1024;
 const MAX_RUN_TOOL_NAME_CHARS = 256;
-function assertRunToolNames(names) {
+function assertRunToolNames(names, label = "RunOptions.toolNames") {
     if (names.length > HARD_RUN_TOOL_NAMES) {
-        throw new TypeError(`RunOptions.toolNames exceeds ${HARD_RUN_TOOL_NAMES} entries`);
+        throw new TypeError(`${label} exceeds ${HARD_RUN_TOOL_NAMES} entries`);
     }
     const out = [];
     const seen = new Set();
     for (const name of names) {
         if (typeof name !== "string" || name.length === 0 || name.length > MAX_RUN_TOOL_NAME_CHARS) {
-            throw new TypeError(`RunOptions.toolNames entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
+            throw new TypeError(`${label} entries must be non-empty strings of at most ${MAX_RUN_TOOL_NAME_CHARS} characters`);
         }
         if (!seen.has(name)) {
             seen.add(name);
@@ -78,6 +78,14 @@ function assertRunToolNames(names) {
     }
     return out;
 }
+/** Restrictive clamp: keep listed order; names outside the grant are dropped (not thrown). */
+export function clampTurnToolNames(listed, requested) {
+    const names = assertRunToolNames(requested, "toolNarrowing");
+    const grant = new Set(listed.map((tool) => tool.name));
+    const dropped = names.filter((name) => !grant.has(name));
+    const allow = names.filter((name) => grant.has(name));
+    return { tools: allow.length === 0 ? [] : filterTools(listed, { allow }), dropped };
+}
 /**
  * Per-run allow-list. Omitted grant → unchanged list. Checkpointed grant cannot widen.
  * Fresh unknown names fail closed; resume drops names the current registry no longer has.

package/dist/usage-estimation.d.ts

@@ -0,0 +1,29 @@
+/** Model-family chars/token tables and the family text estimator (plan 091 Task 1).
+ *
+ * Pure and O(text length): no network, no I/O, no content retention. These are
+ * heuristics, not tokenizers — harnesses universally approximate. Reported usage
+ * always wins; estimates exist so missing usage is never shown as zero.
+ *
+ * Ratio provenance: `openai` is calibrated against `o200k_base` counts on the
+ * in-repo fixtures (`src/__tests__/usage-estimation.test.ts`); the other families
+ * use their published tokenizer guidance ranges and are intentionally rounded
+ * toward over-counting, because an overestimated context meter is safe while an
+ * underestimated one under-compacts. `unknown` is the most conservative table so
+ * an unidentified model can never look smaller than a known one.
+ */
+import type { ModelFamily, TokenEstimateConfidence } from "./contracts-core/usage.js";
+/** Row of {@link MODEL_FAMILY_TOKENS}: prose chars per token, chat-template
+ *  tokens added once per message, and the confidence label for the table. */
+export interface ModelFamilyTokens {
+    readonly charsPerToken: number;
+    readonly perMessageOverhead: number;
+    readonly confidence: TokenEstimateConfidence;
+}
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+export declare const MODEL_FAMILY_TOKENS: Readonly<Record<ModelFamily, ModelFamilyTokens>>;
+/** Resolve a model id (e.g. `"claude-sonnet-4.5"`), provider id, or family name
+ *  to a table key. Unmatched input is `"unknown"` — never a throw. */
+export declare function resolveModelFamily(model?: string): ModelFamily;
+/** Estimate tokens for one flattened text under a family's ratios. The message
+ *  level (`estimateMessageTokens`) owns per-message overhead; this is text-only. */
+export declare function estimateTextTokensForFamily(text: string, modelFamily?: string): number;

package/dist/usage-estimation.js

@@ -0,0 +1,79 @@
+/** CJK ideographs/kana/hangul tokenize near 1.5 chars/token in modern family tokenizers. */
+const CJK_CHARS_PER_TOKEN = 1.5;
+/** Fenced code tokenizes worse than prose: code ratio = prose ratio * this factor. */
+const CODE_RATIO_FACTOR = 0.88;
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+export const MODEL_FAMILY_TOKENS = {
+    anthropic: { charsPerToken: 3.7, perMessageOverhead: 4, confidence: "medium" },
+    openai: { charsPerToken: 5.0, perMessageOverhead: 3, confidence: "medium" },
+    google: { charsPerToken: 3.9, perMessageOverhead: 4, confidence: "medium" },
+    deepseek: { charsPerToken: 3.8, perMessageOverhead: 4, confidence: "medium" },
+    "openrouter-generic": { charsPerToken: 4.4, perMessageOverhead: 4, confidence: "medium" },
+    mistral: { charsPerToken: 3.9, perMessageOverhead: 3, confidence: "medium" },
+    unknown: { charsPerToken: 3.5, perMessageOverhead: 6, confidence: "low" },
+};
+/** Model-id patterns per family. Family names themselves also resolve (see `resolveModelFamily`). */
+const FAMILY_PATTERNS = [
+    ["anthropic", /claude|anthropic/i],
+    ["openai", /gpt-|openai|chatgpt|codex|^o[1-9]/i],
+    ["google", /gemini|gemma|palm|google/i],
+    ["deepseek", /deepseek/i],
+    ["mistral", /mistral|mixtral|codestral|magistral|devstral|pixtral|ministral/i],
+    ["openrouter-generic", /openrouter/i],
+];
+/** Resolve a model id (e.g. `"claude-sonnet-4.5"`), provider id, or family name
+ *  to a table key. Unmatched input is `"unknown"` — never a throw. */
+export function resolveModelFamily(model) {
+    if (typeof model !== "string")
+        return "unknown";
+    const id = model.trim();
+    if (id in MODEL_FAMILY_TOKENS)
+        return id;
+    for (const [family, pattern] of FAMILY_PATTERNS) {
+        if (pattern.test(id))
+            return family;
+    }
+    return "unknown";
+}
+/** Estimate tokens for one flattened text under a family's ratios. The message
+ *  level (`estimateMessageTokens`) owns per-message overhead; this is text-only. */
+export function estimateTextTokensForFamily(text, modelFamily) {
+    const { charsPerToken } = MODEL_FAMILY_TOKENS[resolveModelFamily(modelFamily)];
+    let cjk = 0;
+    for (let index = 0; index < text.length;) {
+        const codePoint = text.codePointAt(index) ?? 0; // unreachable 0: index < length; avoids a non-null assertion
+        if (isCjkCodePoint(codePoint))
+            cjk += 1;
+        index += codePoint > 0xffff ? 2 : 1;
+    }
+    const code = fencedChars(text);
+    const other = Math.max(0, text.length - cjk - code);
+    return Math.ceil(cjk / CJK_CHARS_PER_TOKEN + code / (charsPerToken * CODE_RATIO_FACTOR) + other / charsPerToken);
+}
+/** Length of the characters enclosed by ``` fence pairs (unclosed fence runs to the end). */
+function fencedChars(text) {
+    let total = 0;
+    let index = text.indexOf("```");
+    while (index !== -1) {
+        const end = text.indexOf("```", index + 3);
+        if (end === -1) {
+            total += text.length - index;
+            break;
+        }
+        total += end + 3 - index;
+        index = text.indexOf("```", end + 3);
+    }
+    return total;
+}
+/** Han, kana, hangul, CJK punctuation/fullwidth, and ext-B+ ideograph ranges. */
+function isCjkCodePoint(codePoint) {
+    return ((codePoint >= 0x3000 && codePoint <= 0x303f) ||
+        (codePoint >= 0x3040 && codePoint <= 0x30ff) ||
+        (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7af) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xff00 && codePoint <= 0xffef) ||
+        (codePoint >= 0x20000 && codePoint <= 0x2fa1f));
+}
+//# sourceMappingURL=usage-estimation.js.map

package/docs/ag-ui.md

@@ -31,6 +31,7 @@ npm install @arnilo/prism @arnilo/prism-ag-ui
 | `authorize` | Rebinds untrusted AG-UI thread/run selectors to host ownership on every request. `false` returns 403. |
 | `sessionFactory` | Returns an authorized Prism `AgentSession`; it receives only host-approved `AgUiPreparedInput`, never raw client tools/state. |
 | `input.project` | Opts into full `RunAgentInput`; turns bounded, still-untrusted history, state, context, forwarded props, media, and lineage into host-selected Prism `Message` values. Omit for legacy final-text mode. |
+| `inputPolicy.clientState` (`AgUiInputPolicyOptions`) | `"honor"` (default) passes validated client `state`/`tools` to `input.project`. `"ignore"` validates the same envelope for shape and bounds, then discards both fields, so input comes only from the server session and projector; an unknown value fails at construction with `ERR_PRISM_AG_UI_INPUT` instead of silently honoring the client. |
 | `input.frontendTools` | Explicitly selects client-side handoffs. Returned names must be request-tool subset; adapter never turns JSON tool declarations into Prism `ToolDefinition`s. |
 | `mcp` | Optional `createAgUiMcpAdapter({ bridge, select })`; host selects reviewed `bridge.tools`, then `sessionFactory` receives them as `input.serverTools`. Normal Prism dispatch/loop remains sole executor. |
 | `a2a` | Optional `createAgUiA2AAdapter({ client, select, correlate })`; verified remote A2A task stream replaces this handler's local session only. Host selection/correlation binds each remote task to ownership. |
@@ -44,6 +45,10 @@ npm install @arnilo/prism @arnilo/prism-ag-ui
 
 The handler accepts only `POST` JSON validated with official AG-UI `RunAgentInputSchema`. Every aggregate is bounded before a callback runs. With no `input.project`, it preserves compatibility: final text user message only; non-empty state or frontend tools fail before authorization/session lookup. With a projector, all current roles/history, context, state, forwarded props, multimodal parts, parent lineage, and tool-result continuations are available as untrusted input. The projector must apply Prism media URL/SSRF/MIME policy before forwarding media. Start a run with no `resume` and no `?cursor=`; replay supplies `?cursor=`.
 
+### Server-authoritative input (`inputPolicy.clientState: "ignore"`)
+
+An official browser client posts its own projection: `initialState` becomes the request `state` and `runAgent({ tools })` supplies a tool list. Hosts that keep projection and tools on the server had two options — relay/rewrite every request, or reject state posts and break every browser run. `inputPolicy: { clientState: "ignore" }` is the third: the posted envelope is still schema-validated and bounded (so malformed, oversized, and poisonous payloads fail exactly as before, `400`/`413`), and then client `state` and `tools` are dropped before authorization, `coWorkContext`, `mcp.prepare`, `input.project`, and `defaultAgUiInput` see the input. Input is derived solely from the server session and the host projector, so a browser posting full state gets a normal run whose projection and tool list are the server's own. `AgUiPreparedInput.clientState` reports which policy produced the payload, `frontendTools` stays empty, and `capabilities.tools.clientProvided` is refused under `"ignore"` because the handler never hands client tools to a session. `state`, `context`, and `forwardedProps` reaching the projector under `"honor"` remain untrusted: the projector is still the only authority.
+
 ## Outputs / response / events
 
 The handler returns `text/event-stream`, one `data: <AG-UI event>\n\n` frame per output. Mapper lifecycle is ordered: `RUN_*`, `STEP_*`, `TEXT_MESSAGE_*`, and `TOOL_CALL_*` are deterministic Prism mappings. Host projectors may additionally prove and emit `STATE_SNAPSHOT`/`STATE_DELTA`, `MESSAGES_SNAPSHOT`, `ACTIVITY_*`, current `REASONING_*`, `RAW`, and named `CUSTOM` values.

package/docs/agent-events.md

@@ -24,6 +24,8 @@ Event records preserve emission order within a run because the runtime drains pe
 
 `AgentEventSource` (`createMemoryAgentEventSource` / `persistence.events` on PostgreSQL) appends, pages, and subscribes with opaque ownership-bound cursors. `subscribe` registers wake interest before replaying history so replay-to-live handoff has no gap. Delivery is at-least-once; consumers dedupe `record.id`. PostgreSQL uses transactional sequence allocation plus `LISTEN`/`NOTIFY` wakeups with polling fallback. Transport adapters (server SSE `Last-Event-ID`, AG-UI, A2A `afterEventId`) map source envelopes only — they do not invent private replay loops. This is not exactly-once.
 
+Exactly three event types are terminal — `agent_finished`, `agent_denied`, and `error` — and one exported predicate answers the question for every consumer: `isTerminalAgentEventType(type)`. The memory, NATS, and Postgres sources, AG-UI replay, the A2A stream break, AG-UI `filterRun`, and conversation replay all route through it, so pages, subscriptions, and replays end on the same set. Attribution records such as `run_limit_exceeded` and `budget_exhausted` are not terminal (see [run limit events](#run-limit-events)).
+
 ### Placement (FR-7 answer, 0.0.26)
 
 The durable `AgentEventSource` **stays in `@arnilo/prism-core/sessions/postgres`** for the 0.0.26 line and is importable from the package root (FR-6):
@@ -72,12 +74,15 @@ The `AgentEvent` union (grouped by concern):
 | --- | --- |
 | Agent lifecycle | `agent_started`, `agent_suspended`, `agent_resumed`, `agent_denied`, `agent_finished` |
 | Turns | `turn_started`, `turn_finished` |
+| Deterministic turns | `deterministic_turn` |
 | Provider turns | `provider_turn_started`, `provider_turn_finished` |
 | Assistant messages | `message_started`, `message_delta`, `message_finished` |
 | Delegated agents | `delegated_agent_step` |
 | Tool execution | `tool_execution_started`, `tool_execution_progress`, `tool_execution_finished`, `tool_execution_error`, `tool_execution_blocked` |
+| Tool narrowing | `tool_narrowing_clamped` |
 | Guardrails | `guardrail_decision` |
 | Queue/subscribers | `queue_updated`, `event_subscriber_overflow`, `steer_rejected` |
+| Run limits | `run_limit_exceeded`, `budget_exhausted` |
 | Compaction | `compaction_started`, `compaction_finished` |
 | Retry | `retry_scheduled` |
 | Artifacts | `artifact_validation_started`, `artifact_validation_finished`, `artifact_revision_started`, `artifact_finished`, `artifact_failed` |
@@ -107,6 +112,8 @@ Adapters should call `createDelegatedAgentStep({ sessionId, runId, adapterId, ex
 
 Coding hosts call `observeSupervisorLifecycle(supervisor, { onEvent, delegatedAgentStep })` to turn supervisor milestones into `subagent_started` / `subagent_stopped` coding lifecycle events. Both carry only redacted `childId`, `delegationId`, and `depth`; stopped events add terminal `AgentRunStatus`. Supplying `delegatedAgentStep` emits the bounded `delegated_agent_step` records AG-UI already maps. Child inputs, outputs, paths, and delegation error text never cross either bridge.
 
+Supervisor child reporting is opt-in per child (`SupervisorChild.policy.report` ceiling; a request can only lower it). With `report: "milestones"` the supervisor publishes `child_milestone` (`childId`, `delegationId`, `depth`, `turn`, redacted `childEvent`) at the configured `milestone.everyTurns` cadence or host predicate; with `report: "stream"` it publishes `delegation_child_event` for every per-turn provider/tool/turn child event (never per-token `message_delta`). Both are redacted, count/byte-capped, and rate-coalesced (`delegation_child_events_coalesced` reports dropped events); the cap marker is `delegation_child_events_capped`. `child_failed` carries failure attribution for any child that died on an error or a limit: the redacted `reason`, the terminal `status`/`stopReason`, and the plan-086/087 `RunLimitBreach` in `limit` when a configured ceiling fired. Host cancels, policy denials, and hook rejections are not failures and never emit it. Hosts that want recovery counters rather than events read `supervisor.summary()` (`attempts`, `retries`, `failures`, `failureRadius`, `outcome` per child). Child events stay on the supervisor stream unless the host passes `childEventSink`, which receives the identical payload tagged with `child: { childId, delegationId, depth }` (`ChildEventOrigin`) for routing onto a parent session stream; they are not native `AgentEvent`s of the parent session, and hosts that surface them there re-attach the parent `sessionId`/`runId` themselves if needed.
+
 `message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools. Deltas missing `id`/`name` at stream end fail the provider turn with `ErrorInfo.code: "incomplete_delta"` (typed `ProviderTransportError`); they never throw a bare `Error`. Malformed JSON with id+name present recovers as a blocked tool result (`invalid_json_arguments`) instead.
 
 Tool execution events:
@@ -118,6 +125,7 @@ Tool execution events:
 | `tool_execution_finished` | `sessionId`, `runId`, `result: ToolResult`, `metadata: ToolExecutionMetadata` |
 | `tool_execution_error` | `sessionId`, `runId`, `call: ToolCallContent`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 | `tool_execution_blocked` | `sessionId`, `runId`, `toolCallId`, `name`, `reason: string`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
+| `tool_narrowing_clamped` | `sessionId`, `runId`, `turn`, `dropped: readonly string[]` (names the host returned outside the run grant; no tool args) |
 
 Guardrail events:
 
@@ -139,12 +147,71 @@ Queue / subscriber / compaction / retry / provider events:
 | `attention_compiled` | `sessionId`, `runId?`, `used: number`, `usedAfter: number`, `inputCap: number`, `triggerRatio: number`, `droppedThinkingTurns: number`, `stubbedToolResults: number`, `stubbedBytes: number`, `truncated: boolean` — one per mutated turn of the opt-in [attention compiler](attention-compiler.md); counts only, never message text |
 | `retry_scheduled` | `sessionId`, `runId`, `attempt: number`, `delayMs: number`, `error: ErrorInfo` |
 
+### Run limit events
+
+Terminal attribution — see [Runs and usage § Run limits](runs-and-usage.md#run-limits).
+
+| Variant | Fields |
+| --- | --- |
+| `run_limit_exceeded` | `sessionId`, `runId`, `breach: RunLimitBreach` (`limit`, `maximum`, `observed`, optional `currency`) — emitted once, when an axis first exceeds its cap |
+| `budget_exhausted` | `sessionId`, `runId`, `limit: RunLimitName`, `consumed: { turns, inputTokens, providerAttempts, requestBytes }`, `closestOtherAxes: [{ axis, usedRatio }]`, `recentToolCalls: [{ id, name, argHash }]` |
+
+`budget_exhausted` is the terminal attribution for a run that died on a limit: it is emitted once per
+limit death, before the terminal `error` event and the finish `RunRecord`. A limit death therefore
+delivers three records in order — `run_limit_exceeded` (breach), `budget_exhausted` (attribution),
+then the terminal `error` — and a page, subscription, or replay stays open across the first two:
+keep reading until the stream ends rather than stopping at the first breach record. `limit` names the axis that fired
+(`maxTurns`, `maxInputTokens`, `maxCost`, …). `closestOtherAxes` is the three other finite product
+axes with the highest `used / cap` ratio, so a host can answer "how close was everything else";
+request/response byte axes stay out because their caps are per-frame, and `usedRatio` is clamped to
+`[0, 1]`. `recentToolCalls` holds the last ten host tool calls dispatched in this run (in dispatch
+order, reset at run start and after a durable resume) as id, name, and `argHash` —
+`sha256:<64 hex>` over the canonicalized arguments, never the arguments themselves. `consumed`
+counters are the run-lifetime tracker snapshot at exhaustion. Events stay counts and hashes only, so
+no new redaction class is introduced. Both events project onto the [execution timeline](execution-timeline.md)
+as `timeline.exhaustion` plus the `turns[i].stopReason` badges, with a one-line summary on
+`summarizeTimeline().exhaustion`.
+
 Provider turn events (metadata only — see [Observability](observability.md)):
 
 | Variant | Fields |
 | --- | --- |
+| `deterministic_turn` | `sessionId`, `runId`, `turn`, `middleware` — host middleware answered this turn without a provider request ([Middleware hooks](middleware-hooks.md#no-model-turns-beforeproviderturn)). Carries no `usage` key: provider accounting stays absent, never zero-filled. The same provenance reaches the persisted transcript as `message.metadata.deterministic = { middleware }` on the assistant `message_finished` message. |
 | `provider_turn_started` | `sessionId`, `runId`, `turn`, `metadata: ProviderTurnMetadata` |
-| `provider_turn_finished` | `sessionId`, `runId`, `turn`, `metadata` (includes `latencyMs` on finish), `usage?`, `error?` |
+| `provider_turn_finished` | `sessionId`, `runId`, `turn`, `metadata` (includes `latencyMs`, `stopReason`, `budgets`, `tools`, and provider-reported `cache` metrics on finish), `usage?`, `error?` |
+
+`provider_turn_finished.metadata.stopReason` names why that provider turn stopped, from one closed
+taxonomy. Adapters map native wire values (`finish_reason`, `stop_reason`, `finishReason`, Converse
+`stopReason`) through the shared `mapProviderStopReason` table, so a new provider value degrades to
+`unknown` instead of failing a run; the normalized `done` provider event carries the same mapped
+value when the adapter saw a native reason.
+
+| `stopReason` | Meaning |
+| --- | --- |
+| `end_turn` | Model finished its answer (native `stop`, `end_turn`, `stop_sequence`, `STOP`, `completed`) |
+| `tool_calls` | Turn requested host tools; also what a generic `end_turn` becomes when the turn produced tool calls |
+| `max_output_tokens` | Output truncated at the provider's token cap (native `length`, `max_tokens`, `MAX_TOKENS`) |
+| `content_filter` | Provider safety/refusal path (native `content_filter`, `refusal`, `SAFETY`, `guardrail_intervened`) |
+| `abort` | The run or turn was aborted (host abort, steer soft interrupt) |
+| `provider_error` | The turn failed with a provider error |
+| `unknown` | Unmapped or absent native reason |
+
+`provider_turn_finished.metadata.budgets` is an O(1) snapshot from the run limit tracker:
+`{ inputTokens?, inputCap?, runInputBudget?, runInputUsed, turns, maxTurns }` — current-turn
+provider-reported input tokens against the resolved per-request input cap, cumulative run input
+against `limits.maxInputTokens`, and provider turns against `limits.maxTurns` (`null` when
+disabled). Optional fields are absent when the provider reported no usage or no input cap can be
+derived; hosts that ignore the fields are unaffected.
+
+`provider_turn_started` / `provider_turn_finished` metadata includes `tools: { count, idsHash }` for the
+effective menu sent on that request (after run scoping, per-turn `toolNarrowing`, and disclosure).
+`idsHash` is `sha256:` plus 64 lowercase hex over `JSON.stringify(names)` in request order. Count and
+hash only — never tool args, schemas, or descriptions. Identical consecutive subsets keep the same hash.
+
+`provider_turn_finished.metadata.cache` is present only when the provider reported
+`cacheReadTokens` or `cacheWriteTokens`: `{ cacheReadTokens?, cacheWriteTokens?, hitRate? }`.
+`hitRate` is cache reads divided by reported input tokens. Unknown cache usage is absent, never
+zero-filled; it contains counts only, never cache keys or prompt content.
 
 Artifact validation/refinement events (emitted only by `generateValidateReviseLoop`; `singleShotLoop` emits zero artifact events):
 

package/docs/agent-loops.md

@@ -130,6 +130,39 @@ The snapshot is stored as `loopState: { name, revision, snapshot }` on the durab
 
 A strategy returned by `generateValidateReviseLoop()` is safe to reuse across sequential runs. Its built-in state is scoped to `(sessionId, runId)`; a new non-restored run resets attempts, artifact phase, saved schema, and pending repair messages, while a restored run keeps the checkpointed state. Arbitrary custom strategies are not cloned or reset automatically.
 
+## Turn policy
+
+`RunOptions.turnPolicy` (`TurnPolicyOptions`) lets a host end a run **cleanly** at a provider-turn boundary — after the previous turn's tool results are persisted, before the next provider request (the same point `checkpointPolicy: "every-turn"` checkpoints at). This is the "stop when the agent has done enough" seam: an investigation that should stop at the first plan paint, a desk that stops after N turns, a policy that stops once a tool budget is spent.
+
+```ts
+await session.run("Investigate the churn spike", {
+  turnPolicy: {
+    // Clean turn cap: reaching it stops the run instead of failing it.
+    maxTurns: 4,
+    // Consulted once per boundary; a stop ends the run as `succeeded`.
+    stop: (ctx) =>
+      ctx.turns >= 1 && ctx.toolCalls >= 1
+        ? { action: "stop", reason: "l1-first-plan-paint" }
+        : { action: "continue" },
+  },
+});
+```
+
+| `TurnBoundaryContext` field | Meaning |
+| --- | --- |
+| `sessionId`, `runId` | Run correlation. |
+| `turn` | 1-based index of the provider turn this boundary precedes. |
+| `turns` | Provider turns already completed (`turn - 1`; `0` at the first boundary). |
+| `toolCalls` | Host tool calls dispatched so far in this run. |
+| `usage` | Run-total usage so far, when the provider reported any. |
+| `metadata` | Run metadata (never prompt text, tool arguments, or results). |
+
+A `stop` decision is a **clean terminal outcome**, not an error or a limit breach: the run returns `status: "succeeded"` with `stopReason: "host_policy"` and `stopDetail` (the host's `reason`, ≤256 UTF-8 bytes, redacted). The same pair rides `agent_finished.finishReason`/`stopDetail`, the finish `RunRecord`, and the projected `ExecutionTimeline`. `turnPolicy.maxTurns` is a *clean* cap: it reports `stopReason: "turn_limit"` and, unlike a `limits.maxTurns` breach, never throws `AgentRunLimitError`. A run overlay may only narrow `limits.maxTurns` — widening throws before the first provider turn.
+
+A policy stop stays **resumable**: with `runState: { checkpointPolicy: "every-turn" }` the terminal state keeps the run frontier, so `resumeAgentRun(..., { decision: "continue" })` continues from the boundary. Steers queued before the stop are already in the session history and reach the resumed leg exactly once. A `turnPolicy.maxTurns` stop is the exception — resuming it would re-stop on the first boundary. Resumed runs carry no `turnPolicy` (resume options are not run options), so a continued leg runs to its natural end unless the host stops it again.
+
+The callback is synchronous and bounded, and is never called when `turnPolicy` is omitted: a run without a policy keeps its exact request stream. A callback that throws or returns a malformed decision fails the run closed with `ERR_PRISM_TURN_POLICY` (the boundary makes no provider call and the checkpoint stays fail-closed); a stopped run is never recorded as failed.
+
 ## Outputs / response / events
 
 `AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` as a fallback for custom loops. Core runtime independently accumulates every usage-bearing provider turn in O(turns), persists scoped turn/run rows, and emits `agent_finished` with the aggregate.

package/docs/agent-session-runtime.md

@@ -12,6 +12,7 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `session.prompt(input, options)` → `AgentRunResult`
 - `session.stream(input, options)` → owned-run `AsyncIterable<AgentEvent>`
 - `session.compact(options?)`
+- `session.contextMeter()` → `ContextMeter` (latest provider-turn input tokens, reported or labeled estimate, with cap/budget/ratio)
 - `session.subscribe(options?)`
 - `session.abort()`
 - `session.entries()`
@@ -61,7 +62,7 @@ string | Message | readonly Message[]
 
 `session.stream(input, options?)` subscribes first, starts exactly one run, yields only that run's events, and terminates when the run succeeds, fails, or aborts. Early consumer return aborts the owned run and releases the session. `SubscribeOptions.maxQueuedEvents` / `overflow` may be passed alongside `RunOptions`.
 
-`resumeAgentRunStream(agent, ref, resume, options?)` does the same for one existing suspended durable run. It validates checkpoint ownership, revision/fingerprint, and `expectedVersion`, then subscribes before emitting `agent_started` / `agent_resumed` and resumed message/tool/terminal events. `AgentRunResumeStreamOptions` combines `AgentRunResumeOptions` (including the optional `onSession` observer seam a supervisor uses to attach a child event pump to the rebuilt session) with `signal`, `maxQueuedEvents`, and `overflow`; early return aborts only resumed execution. It does not replay a claimed/dispatched tool, poll a ledger, or retain a worker. `createAgentRunLifecycle().resumeStream(ref, resume, request?)` adds the same behavior after host agent-capability resolution.
+`resumeAgentRunStream(agent, ref, resume, options?)` does the same for one existing suspended durable run. It validates checkpoint ownership, revision/fingerprint, and `expectedVersion`, then subscribes before emitting `agent_started` / `agent_resumed` and resumed message/tool/terminal events. `AgentRunResumeStreamOptions` combines `AgentRunResumeOptions` (including the optional `onSession` observer seam a supervisor uses to attach a child event pump to the rebuilt session) with `maxQueuedEvents` and `overflow`; early return aborts only resumed execution. Since 0.8.0 (plan 080 Task 3), `AgentRunResumeOptions.signal` is inherited by both entrypoints, so `resumeAgentRun()` aborts a live resumed provider/tool turn the same way `resumeAgentRunStream()` does — checked before each preparation step and threaded into the resumed execution. It does not replay a claimed/dispatched tool, poll a ledger, or retain a worker. `createAgentRunLifecycle().resumeStream(ref, resume, request?)` adds the same behavior after host agent-capability resolution.
 
 `session.subscribe(options?)` remains available for hosts that want a long-lived subscriber across runs. Subscribe before `run()` to observe that run's events. The consumer loop and `session.run()` must run concurrently (e.g. start the `for await` consumer, then `await Promise.all([consumer, session.run("Hi")])`): events are only emitted during a live run, so awaiting the subscribe loop before calling `run()` deadlocks. Prefer `session.stream()` when you only need one run's events. `SubscribeOptions.maxQueuedEvents` defaults to `1024` (minimum `1`) and caps events queued while the consumer is not awaiting `next()`. `SubscribeOptions.overflow` defaults to `"close"`; it clears queued payload events, delivers one `event_subscriber_overflow` notice to that subscriber, then closes it. `"drop_oldest"` keeps newest events; `"drop_newest"` ignores new events while full.
 
@@ -186,11 +187,12 @@ Set `runState` with a host-owned `CheckpointStore`, stable `definitionRevision`,
 `resumeAgentRun` accepts exactly one of:
 
 - `decision: "approve" | "deny"` — legacy single-approval path. `approve` allows every pending decision once; `deny` terminates the run as `denied`.
+- `decision: "continue"` — crash recovery for a running-state checkpoint written by [`checkpointPolicy: "every-turn"`](durable-runs.md): resumes from the last provider-turn boundary without re-dispatching tools. It requires a running state and never bypasses a gate — a suspended run still needs `approve`/`deny` or a decision batch.
 - `decisions: readonly RunDecision[]` — one atomic batch. Every entry validates against the recorded pending set (unknown/foreign `approvalId`, duplicates, stale `expectedVersion`, invalid outcomes fail the whole batch closed with `AgentDecisionError` and leave state and version untouched). Outcomes: `allow_once`, `allow_for_run`, `reject_once`, `reject_for_run`. `reject_*` continues the run with a blocked tool result carrying the bounded (2 KB) `reason`. `modifiedArguments` are revalidated (schema, then input guardrails; permission/trust re-run at dispatch) and produce a new arguments hash. `elicitation` payloads are validated against the pending decision's `elicitationSchema` (required keys plus the configured host validator) and resolve the suspended call without executing it. A batch deciding a strict subset persists the decided entries and re-suspends with the remainder pending at the bumped version.
 
 `*_for_run` outcomes append a `StickyDecision` to the durable run state: later calls in the same run matching the scope exactly (all recorded fields) proceed or are blocked without a new suspension, policy still enforced at dispatch. Sticky decisions expire when the run reaches any terminal status. Caps: 32 pending decisions per run (hard 128), 64 sticky decisions (hard 256), 2 KB decision reasons, 16 KB elicitation payloads. Frontend adapters (such as AG-UI with `capabilities.humanInTheLoop.approveWithEdits`) and the server resume endpoint (`POST .../resume` with `modifiedArguments`) map human edits directly to `RunDecision` entries with `modifiedArguments` under single atomic CAS, revalidating tool parameter schemas and invalidating stale draft approvals.
 
-**Runtime input validation (0.2.0, plan 020 Task 2).** Every public resume entrypoint (`resumeAgentRun`, `resumeAgentRunStream`, `AgentRunLifecycle.resume()`/`resumeStream()`) validates the complete resume input in core before any checkpoint read/write, agent resolution, subscription, or tool execution: a non-null object, positive safe-integer `expectedVersion`, exactly one of `decision`/`decisions`, legacy `decision` exactly `approve`/`deny`, and a non-empty batch ≤ 128 entries whose entries are objects with a bounded non-empty `approvalId`, a whitelisted outcome, an optional string `reason` within the 2 KB limit, and JSON-object `modifiedArguments`/`elicitation` within the 16 KB limit. Unknown legacy decisions (e.g. `"sideways"`) and malformed untyped batches fail closed with `AgentDecisionError` (`ERR_PRISM_DECISION_INVALID`/`..._LIMIT`/`..._DUPLICATE`) under a **no-side-effect guarantee**: zero checkpoint writes/CAS changes, zero tool calls, zero resumed events. This holds for plain-JavaScript and `as any` callers; the server's transport parser is defense in depth, not the security boundary. State-dependent checks (foreign/stale approval ids, scope, schema, policy) still run in the atomic batch resolver.
+**Runtime input validation (0.2.0, plan 020 Task 2).** Every public resume entrypoint (`resumeAgentRun`, `resumeAgentRunStream`, `AgentRunLifecycle.resume()`/`resumeStream()`) validates the complete resume input in core before any checkpoint read/write, agent resolution, subscription, or tool execution: a non-null object, positive safe-integer `expectedVersion`, exactly one of `decision`/`decisions`, legacy `decision` exactly `approve`/`deny`/`continue`, and a non-empty batch ≤ 128 entries whose entries are objects with a bounded non-empty `approvalId`, a whitelisted outcome, an optional string `reason` within the 2 KB limit, and JSON-object `modifiedArguments`/`elicitation` within the 16 KB limit. Unknown legacy decisions (e.g. `"sideways"`) and malformed untyped batches fail closed with `AgentDecisionError` (`ERR_PRISM_DECISION_INVALID`/`..._LIMIT`/`..._DUPLICATE`) under a **no-side-effect guarantee**: zero checkpoint writes/CAS changes, zero tool calls, zero resumed events. This holds for plain-JavaScript and `as any` callers; the server's transport parser is defense in depth, not the security boundary. State-dependent checks (foreign/stale approval ids, scope, schema, policy) still run in the atomic batch resolver.
 
 ```ts
 const result = await session.run("Publish draft", {
@@ -203,7 +205,7 @@ if (result.status === "suspended") {
 }
 ```
 
-Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. The fingerprint hashes the agent id/name, `definitionRevision`, model, instructions, system-prompt contributions, skills (name/instructions/tool names), tool definitions (name/parameters/exclusive), guardrail definitions (name/stage/revision), and loop strategy — changing any of them without bumping `definitionRevision` fails resume closed instead of silently continuing with different agent semantics. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. State is bounded at save by `runState.maxStateBytes` (default 256 KB, at most the 1 MB hard cap); load bounds against the 1 MB hard cap only, so state saved with a raised limit stays resumable while oversized records are still rejected. Since 0.1.3 (plan 015 Task 4), durable runs may opt in to session-state persistence with `persistSessionState: true` on both the run and resume options: the loaded-skill **name catalog** (≤64 names, ≤256 chars each) rides the checkpoint and is restored into the resumed session's `LoadedSkillSet`; skill **bodies are never persisted** and re-resolve from the live registry via `load_skill`. Since 0.1.6 (plan 018 closeout `checkpoint-bodies`), `includeSkillBodies: true` on BOTH the run and resume options additionally persists the exact loaded-skill **instructions** (`{name, instructions}` pairs, redacted at the checkpoint boundary like all state, ≤64 bodies / ≤256-char names / ≤262144-byte bodies / ≤1 MiB total) so resume re-renders them registry-independently — no `load_skill` round-trip and no dependence on the registry still serving the same text; `maxStateBytes` (default 256 KB) refuses oversize bodies with a recorded error, never silently truncates. Default off keeps the checkpoint shape byte-identical to 0.1.3. Since 0.7.0 (plan 074 P3), `persistSessionState: true` also carries the opt-in [attention compiler](attention-compiler.md)'s sticky frontier (`sessionState.attentionSticky`: 32-hex thinking keys plus tool-call ids, newest 256 of each, redacted like all state) so a resumed run keeps its thinking strips and tool stubs instead of re-deciding its first turn from the ratio; a malformed frontier is dropped entry by entry and never blocks a resume. Since 0.7.0, `onSession` hands the reconstructed session to a caller-supplied observer before the resumed run starts, so an observer (the supervisor's child-event pump) can subscribe while the run is still live; it is called for every resume outcome, a throw fails closed before any event or tool work, and the session is valid only for the duration of that resume. Built-in loop options are durable; custom `AgentLoopStrategy` instances are durable when they declare `snapshot`/`restore` hooks (see [Agent loops § Durable runs](agent-loops.md#durable-runs)) and reject before provider work otherwise.
+Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. A checkpoint load or delete under a non-matching ownership scope reads as absent (`null`), and a save against a foreign-owned record fails as a generic `ERR_PRISM_CHECKPOINT_CONFLICT` (plan 080 Task 3) — a tenant cannot distinguish “another tenant owns this key” from “missing”, and callers that relied on the old `Checkpoint ownership mismatch` throw now see the same miss they would for an unknown key. The fingerprint hashes the agent id/name, `definitionRevision`, model, instructions, system-prompt contributions, skills (name/instructions/tool names), tool definitions (name/parameters/exclusive), guardrail definitions (name/stage/revision), and loop strategy — changing any of them without bumping `definitionRevision` fails resume closed instead of silently continuing with different agent semantics. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. State is bounded at save by `runState.maxStateBytes` (default 256 KB, at most the 1 MB hard cap); load bounds against the 1 MB hard cap only, so state saved with a raised limit stays resumable while oversized records are still rejected. Since 0.1.3 (plan 015 Task 4), durable runs may opt in to session-state persistence with `persistSessionState: true` on both the run and resume options: the loaded-skill **name catalog** (≤64 names, ≤256 chars each) rides the checkpoint and is restored into the resumed session's `LoadedSkillSet`; skill **bodies are never persisted** and re-resolve from the live registry via `load_skill`. Since 0.1.6 (plan 018 closeout `checkpoint-bodies`), `includeSkillBodies: true` on BOTH the run and resume options additionally persists the exact loaded-skill **instructions** (`{name, instructions}` pairs, redacted at the checkpoint boundary like all state, ≤64 bodies / ≤256-char names / ≤262144-byte bodies / ≤1 MiB total) so resume re-renders them registry-independently — no `load_skill` round-trip and no dependence on the registry still serving the same text; `maxStateBytes` (default 256 KB) refuses oversize bodies with a recorded error, never silently truncates. Default off keeps the checkpoint shape byte-identical to 0.1.3. Since 0.7.0 (plan 074 P3), `persistSessionState: true` also carries the opt-in [attention compiler](attention-compiler.md)'s sticky frontier (`sessionState.attentionSticky`: 32-hex thinking keys plus tool-call ids, newest 256 of each, redacted like all state) so a resumed run keeps its thinking strips and tool stubs instead of re-deciding its first turn from the ratio; a malformed frontier is dropped entry by entry and never blocks a resume. Since 0.7.0, `onSession` hands the reconstructed session to a caller-supplied observer before the resumed run starts, so an observer (the supervisor's child-event pump) can subscribe while the run is still live; it is called for every resume outcome, a throw fails closed before any event or tool work, and the session is valid only for the duration of that resume. Built-in loop options are durable; custom `AgentLoopStrategy` instances are durable when they declare `snapshot`/`restore` hooks (see [Agent loops § Durable runs](agent-loops.md#durable-runs)) and reject before provider work otherwise. For mid-run crash recovery (`checkpointPolicy: "every-turn"` plus `decision: "continue"`), see [Durable runs](durable-runs.md).
 
 ## Secure composition