@arnilo/prism 0.10.0 → 0.11.0

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

@@ -8,6 +8,43 @@ import { createAgent } from "../agent-session/create-agent.js";
 import { providerDone, providerThinkingDelta, toolCallContent } from "../provider-events.js";
 import { createLoadSkillTool } from "../skill-load.js";
 import { createSkillRegistry } from "../skills.js";
+/**
+ * Score an already-captured request list. One pass, no session, no provider call.
+ * A wrong `tailSegments` map yields a wrong number, not a throw.
+ */
+export function scorePrefixStability(requests, options) {
+    const first = requests[0];
+    if (requests.length < 2 || first === undefined) {
+        throw new Error(`scorePrefixStability needs at least 2 captured requests, got ${requests.length}`);
+    }
+    const minContinuity = options?.minContinuity ?? 0.95;
+    const assertOn = options?.assertOn ?? "providerPrefix";
+    const isTail = tailClassifier(options?.tailSegments ?? new Map());
+    let observed = 1;
+    let cacheableObserved = 1;
+    const resetDetails = [];
+    let previous = measureRequest(first, isTail);
+    for (let index = 1; index < requests.length; index += 1) {
+        const current = requests[index];
+        if (current === undefined)
+            continue;
+        const next = measureRequest(current, isTail);
+        const fraction = sharedPrefixFraction(previous.providerPrefix, next.providerPrefix);
+        const cacheableFraction = sharedPrefixFraction(previous.cacheablePrefix, next.cacheablePrefix);
+        observed = Math.min(observed, fraction);
+        cacheableObserved = Math.min(cacheableObserved, cacheableFraction);
+        const measured = assertOn === "cacheablePrefix" ? cacheableFraction : fraction;
+        if (measured < minContinuity)
+            resetDetails.push(projectResetDetail(index + 1, fraction, cacheableFraction, assertOn));
+        previous = next;
+    }
+    return {
+        minContinuity: observed,
+        cacheableContinuity: cacheableObserved,
+        resets: resetDetails.map((gap) => gap.request),
+        resetDetails,
+    };
+}
 /**
  * Drive a real session through two staggered skill loads and assert that each
  * provider request keeps a byte-identical leading prefix (messages **and** tool
@@ -32,13 +69,19 @@ export async function runPrefixStabilityConformance(options) {
         bodies.push(instructions);
     }
     const requests = [];
+    const foldableBytes = options.foldableToolResultBytes;
+    assert.ok(foldableBytes === undefined || (Number.isSafeInteger(foldableBytes) && foldableBytes > 0), "prefix stability conformance foldableToolResultBytes must be a positive safe integer");
     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], host.attentionCompiler === true || typeof host.attentionCompiler === "object"),
+        tools: [
+            ...hostTools,
+            createLoadSkillTool({ registry }),
+            ...(foldableBytes === undefined ? [] : [createFoldableToolResultTool(foldableBytes)]),
+        ],
+        provider: fixtureProvider(requests, [first.name, second.name], host.attentionCompiler === true || typeof host.attentionCompiler === "object", foldableBytes !== undefined),
     });
     const session = agent.createSession();
     const [firstInput, secondInput] = options.inputs ?? ["Prefix stability turn one", "Prefix stability turn two"];
@@ -49,40 +92,26 @@ export async function runPrefixStabilityConformance(options) {
     // The session's own map holds the exact `Message` objects `appendTailSegment` allocated, so the
     // classification is exact rather than a heuristic over host-authored content. (`tailSegments` is
     // runtime-session state, not part of the public `AgentSession` contract, hence the narrow above.)
-    const isTail = tailClassifier(session.tailSegments);
-    const captured = requests.map((request) => measureRequest(request, isTail));
+    const assertOn = options.assertOn ?? "providerPrefix";
+    // One measurement. The assertion below reads the sample; it does not serialize again.
+    const sample = scorePrefixStability(requests, { tailSegments: session.tailSegments, minContinuity, assertOn });
     // Guard against a vacuous pass: both bodies must have been disclosed by the end.
-    const last = captured.at(-1)?.providerPrefix ?? "";
+    const last = (requests.at(-1)?.messages ?? []).map((message) => JSON.stringify(message)).join("\n");
     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`);
     }
-    const assertOn = options.assertOn ?? "providerPrefix";
     const allowedResets = options.allowedResets ?? 0;
     assert.ok(Number.isSafeInteger(allowedResets) && allowedResets >= 0, "prefix stability conformance allowedResets must be a non-negative safe integer");
-    let observed = 1;
-    let cacheableObserved = 1;
-    let previous = captured.at(0) ?? { providerPrefix: "", cacheablePrefix: "" };
-    // Collect every gap first: an allowed reset must not be hidden by a later assert, and the
-    // vacuity check needs the whole list to prove the fixture folded exactly as declared.
-    const gaps = [];
-    for (let index = 1; index < captured.length; index += 1) {
-        const next = captured[index] ?? previous;
-        const fraction = sharedPrefixFraction(previous.providerPrefix, next.providerPrefix);
-        const cacheableFraction = sharedPrefixFraction(previous.cacheablePrefix, next.cacheablePrefix);
-        observed = Math.min(observed, fraction);
-        cacheableObserved = Math.min(cacheableObserved, cacheableFraction);
-        const measured = assertOn === "cacheablePrefix" ? cacheableFraction : fraction;
-        if (measured < minContinuity)
-            gaps.push({ request: index + 1, fraction, cacheableFraction });
-        previous = next;
-    }
-    const resets = gaps.map((gap) => gap.request);
+    const observed = sample.minContinuity;
+    const cacheableObserved = sample.cacheableContinuity;
+    const gaps = sample.resetDetails;
+    const resets = sample.resets;
     const measuredLabel = assertOn === "cacheablePrefix" ? "previous cacheable prefix (tail segments excluded)" : "previous provider prefix";
     const minimum = (minContinuity * 100).toFixed(1);
-    const observedResets = `resets ${formatResets(resets)} of ${captured.length - 1} request pairs`;
+    const observedResets = `resets ${formatResets(resets)} of ${requests.length - 1} request pairs`;
     const firstGap = gaps[0];
     if (firstGap !== undefined && gaps.length > allowedResets) {
-        const measured = assertOn === "cacheablePrefix" ? firstGap.cacheableFraction : firstGap.fraction;
+        const measured = firstGap.fraction;
         assert.fail(`prefix stability conformance: request ${firstGap.request - 1} → ${firstGap.request} kept ${(measured * 100).toFixed(1)}% of the ${measuredLabel} ` +
             `(minimum ${minimum}%), and ${gaps.length} pair(s) broke below it (${observedResets}, allowedResets ${allowedResets}). ` +
             "Late skill bodies must append after the stable prefix; recomposed context, an in-place skill-catalog rewrite, or any leading-message mutation invalidates it. " +
@@ -92,7 +121,21 @@ export async function runPrefixStabilityConformance(options) {
         assert.fail(`prefix stability conformance: allowedResets is ${allowedResets} but only ${gaps.length} pair(s) broke below the minimum (${minimum}% of the ${measuredLabel}); ${observedResets}. ` +
             "The fixture was supposed to invalidate the prefix at those boundaries — drop allowedResets for an append-only assembly, or check the fold trigger or eviction condition actually fired.");
     }
-    return { requests: captured.length, minContinuity: observed, cacheableContinuity: cacheableObserved, resets };
+    return {
+        requests: requests.length,
+        minContinuity: observed,
+        cacheableContinuity: cacheableObserved,
+        resets,
+        resetDetails: sample.resetDetails,
+    };
+}
+/** One gap row. `fraction` is the metric the caller selected; `cacheableFraction` stays the tail-excluded pair. */
+function projectResetDetail(request, providerFraction, cacheableFraction, assertOn) {
+    return {
+        request,
+        fraction: assertOn === "cacheablePrefix" ? cacheableFraction : providerFraction,
+        cacheableFraction,
+    };
 }
 /**
  * Deterministic reasoning block the fixture provider emits before each skill load when the host
@@ -101,12 +144,26 @@ export async function runPrefixStabilityConformance(options) {
  * in the measured prefix.
  */
 const FIXTURE_THINKING = "Prefix-stability fixture reasoning: the harness measures a byte-shared provider prefix, so this block exists only to give the attention-compiler thinking stage deterministic content to strip. ".repeat(17);
+/** Runner-owned fixture tool (plan 110 Task 4): the tool-result stage needs a row worth stubbing. */
+const PREFIX_STABILITY_BULK_TOOL_NAME = "prefix_stability_bulk";
+function createFoldableToolResultTool(bytes) {
+    return {
+        name: PREFIX_STABILITY_BULK_TOOL_NAME,
+        description: "Deterministic bulk payload for the tool-result fold fixture.",
+        parameters: { type: "object", properties: {} },
+        execute(_args, context) {
+            const text = "x".repeat(bytes);
+            return { toolCallId: context.toolCallId, name: PREFIX_STABILITY_BULK_TOOL_NAME, value: text, content: [{ type: "text", text }] };
+        },
+    };
+}
 /**
  * Fixture provider: turn 1 loads `skillNames[0]`, turn 2 loads `skillNames[1]`, everything else
  * completes. With `reasoning` (the host runs an attention compiler) each skill-load round also
- * carries a thinking block, so the compiler's thinking stage has real content to fold.
+ * carries a thinking block, so the compiler's thinking stage has real content to fold. With `bulk`
+ * the same round also calls the runner-owned bulk tool, so the tool-result stage has a foldable row.
  */
-function fixtureProvider(requests, skillNames, reasoning) {
+function fixtureProvider(requests, skillNames, reasoning, bulk) {
     let call = 0;
     return {
         id: "prefix-stability-fixture",
@@ -119,6 +176,12 @@ function fixtureProvider(requests, skillNames, reasoning) {
                 if (reasoning)
                     yield providerThinkingDelta(FIXTURE_THINKING);
                 yield { type: "tool_call", call: toolCallContent(`prefix-stability-${index}`, "load_skill", { name: skillName }) };
+                if (bulk) {
+                    yield {
+                        type: "tool_call",
+                        call: toolCallContent(`prefix-stability-bulk-${index}`, PREFIX_STABILITY_BULK_TOOL_NAME, {}),
+                    };
+                }
                 return;
             }
             yield providerDone();

package/dist/usage-estimation.d.ts

@@ -19,7 +19,13 @@ export interface ModelFamilyTokens {
     readonly perMessageOverhead: number;
     readonly confidence: TokenEstimateConfidence;
 }
-/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing. */
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing.
+ *
+ * Deep-frozen — each row, then the table. `Readonly<Record<…>>` is compile-time only, and a
+ * runtime write to a nested row silently changes token accounting: an under-counted input
+ * estimate is what `maxInputTokens`/`maxCost` are checked against, and a replaced row makes the
+ * estimate `NaN`, which compares false. Recalibration is a source change plus the live calibration
+ * leg (`scripts/usage-calibration-live.test.mjs`), never a runtime override. */
 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. */

package/dist/usage-estimation.js

@@ -2,16 +2,22 @@
 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" },
-};
+/** Per-family chars/token tables (plan 091 Task 1). Estimates only, never billing.
+ *
+ * Deep-frozen — each row, then the table. `Readonly<Record<…>>` is compile-time only, and a
+ * runtime write to a nested row silently changes token accounting: an under-counted input
+ * estimate is what `maxInputTokens`/`maxCost` are checked against, and a replaced row makes the
+ * estimate `NaN`, which compares false. Recalibration is a source change plus the live calibration
+ * leg (`scripts/usage-calibration-live.test.mjs`), never a runtime override. */
+export const MODEL_FAMILY_TOKENS = Object.freeze({
+    anthropic: Object.freeze({ charsPerToken: 3.7, perMessageOverhead: 4, confidence: "medium" }),
+    openai: Object.freeze({ charsPerToken: 5.0, perMessageOverhead: 3, confidence: "medium" }),
+    google: Object.freeze({ charsPerToken: 3.9, perMessageOverhead: 4, confidence: "medium" }),
+    deepseek: Object.freeze({ charsPerToken: 3.8, perMessageOverhead: 4, confidence: "medium" }),
+    "openrouter-generic": Object.freeze({ charsPerToken: 4.4, perMessageOverhead: 4, confidence: "medium" }),
+    mistral: Object.freeze({ charsPerToken: 3.9, perMessageOverhead: 3, confidence: "medium" }),
+    unknown: Object.freeze({ 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],

package/docs/acp.md

@@ -57,7 +57,7 @@ In-stream `SessionUpdate`s:
 | `permission_denied` lifecycle | `tool_call_update` status `failed` (never raw args; synthesized id `prism:denied:<approvalId>` when no `toolCallId`) |
 | `configuration_changed` lifecycle | `config_option_update` with the full current set, per streaming session |
 | Plan lifecycle (F5, UNSTABLE-gated) | `plan_changed` → `plan_update` with `plan: { type: "items", planId = planPath, entries: [{ content, priority: "medium", status }] }` — the complete entry list per update (client replaces its plan wholesale); `plan_removed` → `plan_removed` with `planId = planPath`. Emitted only when the client advertised `ClientCapabilities.plan`; mapper stays capability-agnostic (gate in the agent wiring). Entries come from `writeCodingPlanFile`'s `onEvent` (parsed via `parseCodingPlanTodos`) or host-emitted through their `CodingLifecycleEmitter`; text passes the shared redactor and byte caps. |
-| Subagent lifecycle | `subagent_started` / `subagent_stopped` → `agent_message_chunk` with only redacted child/delegation ids and terminal status. Wire `observeSupervisorLifecycle()` to emit them; child inputs, outputs, paths, and error text stay absent. |
+| Subagent lifecycle | `subagent_started` / `subagent_stopped` → `agent_message_chunk` with only redacted child/delegation ids and terminal status. Wire `observeSupervisorLifecycle()` to emit them; child inputs, outputs, paths, and error text stay absent. The coding event's opt-in `failure` / `recovery` fields are host-side only — this mapping reads ids, depth, and status. |
 | Session title (F6) | `sessions.title({ sessionId, prompt, signal })` resolves on `session/prompt`; a defined value differing from the last emitted title produces `session_info_update` with `{ sessionUpdate: "session_info_update", title }`. Best-effort: `undefined` or a throw means no title and no update (requests never fail on titles); the host owns title storage. Titles pass the shared redactor and are truncated at `maxTextBytes`/`maxEventBytes`. |
 | Slash commands (F9) | `commands.list({ sessionId, signal })` on `session/new`/`load`/`resume` produces `available_commands_update` with `{ name, description, input?: { hint } }` (SDK `AvailableCommand`; description is required). Names/descriptions/hints pass the shared redactor and `maxTextBytes`; the list is sliced at `acpCommandsPerUpdate`. Best-effort: a throw or non-array omits the update (session start never fails on commands). |
 | Session mode/config switch | `current_mode_update` / `config_option_update` |
@@ -121,7 +121,7 @@ const agent = createPrismAcpAgent({
 
 ### Persistence and ownership
 
-- **Active-run recovery (0.2.6, plan 026 Task 5).** When `sessionStore` and the `recovery` seam (checkpoints + leases + ownerId, all three together) are wired, the agent records a bounded `activeRun` reference on `PersistedAcpSession` while a durable run is live (first run event → `running`, suspension → `suspended` + version, finish/deny/error → `terminal`; frozen 512-byte cap; advisory only — the authoritative status is re-queried from `AgentRunLifecycle.status`). After a restart, `restore` re-attaches the ref to the live session and hosts re-resolve it with `createAcpRunRecovery` (exported from `@arnilo/prism-ag-ui/acp`): suspended runs report their pending approval ids and durable version, terminal runs report terminal, and unprovable in-flight streams report `unknown` — the prompt is never restarted automatically. Durable cancellation (`recovery.cancel`) is ownership/version/fence checked, terminal/idempotent, aborts no unrelated run, and never replays a pending/dispatched tool: a cancelled run reports `cancelled` and must not be resumed. `session/cancel` on a live agent aborts the controller (0.2.5 parity) and, for restored runs, writes the durable marker under the session's ownership. Cancel markers live in `prism.coding-agent.cancel.v1` (schemaVersion 1, CAS + lease fenced). A host-side terminal whose managed process is unattestable after restart reports `unknown` (exitCode null); the agent never fabricates an exit or replays input (`terminal-client`).
+- **Active-run recovery (0.2.6, plan 026 Task 5).** When `sessionStore` and the `recovery` seam (checkpoints + leases + ownerId, all three together) are wired, the agent records a bounded `activeRun` reference on `PersistedAcpSession` while a durable run is live (first run event → `running`, suspension → `suspended` + version, finish/deny/error → `terminal`; frozen 512-byte cap; advisory only — the authoritative status is re-queried from `AgentRunLifecycle.status`). After a restart, `restore` re-attaches the ref to the live session and hosts re-resolve it with `createAcpRunRecovery` (exported from `@arnilo/prism-ag-ui/acp`): suspended runs report their pending approval ids and durable version, terminal runs report terminal, and unprovable in-flight streams report `unknown` — the prompt is never restarted automatically. Durable cancellation (`recovery.cancel`) is ownership/version/fence checked, terminal/idempotent, aborts no unrelated run, and never replays a pending/dispatched tool: a cancelled run reports `cancelled` and must not be resumed. `session/cancel` on a live agent aborts the controller (0.2.5 parity) and, for restored runs, writes the durable marker under the session's ownership; that write is not tied to the connection, so it lands even when the client disconnects immediately after `session/cancel`; `session/close` likewise does not abort a durable cancel write already in flight — it stays bounded by the cancel-lease TTL. Cancel markers live in `prism.coding-agent.cancel.v1` (schemaVersion 1, CAS + lease fenced). A host-side terminal whose managed process is unattestable after restart reports `unknown` (exitCode null); the agent never fabricates an exit or replays input (`terminal-client`).
 
 - **Without the durability seam the agent never persists `modeId`/`configValues`.** Defaults are recomputed per session from the `modes`/`configOptions` seams — a fresh `session/new`, `load`, or `resume` always starts from `defaultModeId` / option `defaultValue`, and the agent's per-session registry is in-memory only. Persisting mode/config across sessions is a **host** decision, and host-side persistence MUST be ownership-scoped.
 - **Host persistence MUST key by `sessions.ownership`.** `authorize` binds transport identity to ownership; a host store that persists `modeId`/`configValues` must refuse any restore whose stored ownership differs from the current session's ownership — a `sessionId` alone is never a sufficient key (session ids may collide across tenants). A cross-tenant restore rejects with `ERR_PRISM_ACP_INPUT` and never returns the other tenant's mode/config.

package/docs/agent-events.md

@@ -110,9 +110,9 @@ Agent / turn / message events:
 
 Adapters should call `createDelegatedAgentStep({ sessionId, runId, adapterId, externalConversationId, stepIndex, state, kind, usage })` rather than forwarding external JSON. The constructor allow-lists fields and fails closed on malformed or oversized identifiers/counters.
 
-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.
+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`. Two independent opt-ins extend the stopped event without changing the default: `includeFailure: true` attaches `failure: { reason, limit?, stopReason? }` to the stop a `child_failed` produced — the supervisor-redacted reason truncated to `DEFAULT_LIFECYCLE_MAX_REASON_BYTES`, the fired `RunLimitName`, and the child's stop reason (`delegation_finished` and `delegation_rejected` never carry it) — and `includeRecovery: true` attaches the child's `summary()` row as `recovery: { attempts, retries, failures, failureRadius, outcome }`, omitted when the source exposes no `summary()`. 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: with both options off the stopped event is byte-identical to before, and the opt-in failure fields are counts, enums, and the already-redacted reason.
 
-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.
+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, plus that death's exhaustion attribution (`consumed`, `closestOtherAxes`, `recentToolCalls`, the payload the child's own `budget_exhausted` event and `AgentRunResult.attribution` carry). 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), or pass `includeRecovery` to the lifecycle bridge, which attaches that row to each stopped event. 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.
 
@@ -198,10 +198,11 @@ value when the adapter saw a native reason.
 
 `provider_turn_finished.metadata.budgets` is an O(1) snapshot from the run limit tracker:
 `{ inputTokens?, inputTokensSource?, inputCap?, runInputBudget?, runInputUsed, turns, maxTurns }` —
-current-turn charged input tokens (provider-reported, or the labeled fallback estimate when the
-provider reported none) against the resolved per-request input cap, cumulative run input against
-`limits.maxInputTokens`, and provider turns against `limits.maxTurns` (`null` when disabled).
-`inputTokensSource` is `"reported"` or `"estimated"` and is absent together with `inputTokens`.
+current-turn charged input tokens against the resolved per-request input cap, cumulative run input
+against `limits.maxInputTokens`, and provider turns against `limits.maxTurns` (`null` when disabled).
+`inputTokensSource` is `"reported"` or `"estimated"` and is absent together with `inputTokens`; what
+produces each is documented in
+[Runs and usage § Automatic fallback](runs-and-usage.md#automatic-fallback-agentconfigusageestimation).
 Optional fields are absent when the provider reported no usage or no input cap can be derived; hosts
 that ignore the fields are unaffected.
 

package/docs/agent-session-runtime.md

@@ -61,7 +61,7 @@ string | Message | readonly Message[]
 
 `session.close()` is the session teardown seam: it dispatches `session_shutdown` middleware exactly once (idempotent — a second `close()` dispatches nothing) and then closes every subscriber, run-scoped and `acrossRuns` alike. It does not abort an active run, so call it after the run settles. `session_start` middleware, the mirror dispatch, runs once at the session's first run start (the two hooks are the only per-session middleware calls — every other hook is per turn or per boundary). See [Middleware hooks](middleware-hooks.md).
 
-`session.run()` / `session.prompt()` resolve to an `AgentRunResult` with `sessionId`, `runId`, `status`, `text`, `content`, optional `message`/`usage`/`leafId`, and terminal `error`/`abortReason` when applicable. Callers may ignore the return value. Failed and aborted runs still emit their terminal events, then reject with `AgentRunError` whose `.result` carries the same shape.
+`session.run()` / `session.prompt()` resolve to an `AgentRunResult` with `sessionId`, `runId`, `status`, `text`, `content`, optional `message`/`usage`/`leafId`, `limit`/`attribution` when the run died on a configured ceiling, and terminal `error`/`abortReason` when applicable. Callers may ignore the return value. Failed and aborted runs still emit their terminal events, then reject with `AgentRunError` whose `.result` carries the same shape.
 
 `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. The subscription belongs to `stream()`: it closes it when the owned run settles, so even a run that fails before its first event (a pre-flight validation rejection returns before run-end cleanup) ends the consumer instead of parking it, and no run-end close is required for `stream()` to be correct. Early consumer return aborts the owned run and releases the session. `SubscribeOptions.maxQueuedEvents` / `overflow` may be passed alongside `RunOptions`.
 

package/docs/coding-agent-tools.md

@@ -614,5 +614,5 @@ Every configurable value is a positive safe integer (context may be zero); Prism
 - [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
 - [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
 - [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.
-- [ACP coding-host interop](acp.md): host editors drive these tools through stable ACP v1 — client fs/terminal adapters, `CodingLifecycleEvent` emission (`file_changed` etc. via the `onEvent` options; `plan_changed` also fires from `writeCodingPlanFile`'s `onEvent`, F5), redacted supervisor `subagent_started` / `subagent_stopped` via `observeSupervisorLifecycle`, and permission/elicitation through the shared four-outcome decision model.
+- [ACP coding-host interop](acp.md): host editors drive these tools through stable ACP v1 — client fs/terminal adapters, `CodingLifecycleEvent` emission (`file_changed` etc. via the `onEvent` options; `plan_changed` also fires from `writeCodingPlanFile`'s `onEvent`, F5), redacted supervisor `subagent_started` / `subagent_stopped` via `observeSupervisorLifecycle` (the opt-in `includeFailure` / `includeRecovery` options add the redacted reason/limit/stop reason and the child's `summary()` counters to stopped events), and permission/elicitation through the shared four-outcome decision model.
 - [LLM compaction package](compaction-llm.md): optional `createCodingCompactionStrategy()` retains bounded paths, patch intent, checks, plan/todo state, blockers, and next verification—not complete diffs or raw command output.

package/docs/coding-tools.md

@@ -8,14 +8,11 @@ The `@arnilo/prism-coding-tools` family package unifies Prism's coding agent too
 npm install @arnilo/prism @arnilo/prism-coding-tools
 ```
 
-For document reading or specialized persona integrations, install the optional peer dependencies as needed:
+For document reading or specialized integrations, install the optional peer dependencies as needed:
 
 ```bash
 # PDF and DOCX document extraction
 npm install pdf-parse mammoth
-
-# Ponytail upstream integration
-npm install @dietrichgebert/ponytail
 ```
 
 ## Subpaths Map
@@ -28,8 +25,6 @@ npm install @dietrichgebert/ponytail
 | `@arnilo/prism-coding-tools/computer-use-linux` | Linux desktop observation and targeting tool bridge | — |
 | `@arnilo/prism-coding-tools/dev` | Loopback-only developer inspector, event timeline visualizer, and local replay server | — |
 | `@arnilo/prism-coding-tools/dev/cli` | Command-line entrypoint for `prism dev` | — |
-| `@arnilo/prism-coding-tools/caveman` | Caveman ultra-terse engineering persona extension | — |
-| `@arnilo/prism-coding-tools/ponytail` | Ponytail multi-agent planning and delegation persona extension | `@dietrichgebert/ponytail` |
 | `@arnilo/prism-coding-tools/impeccable` | Impeccable high-precision frontend engineering persona extension | — |
 
 ## CLI
@@ -65,17 +60,18 @@ const composition = createSandboxCodingComposition({
 
 ### Persona Extensions
 ```ts
-import { createCavemanExtension } from "@arnilo/prism-coding-tools/caveman";
-import { createPonytailExtension } from "@arnilo/prism-coding-tools/ponytail";
 import { createImpeccableExtension } from "@arnilo/prism-coding-tools/impeccable";
 
-const caveman = createCavemanExtension();
-const ponytail = createPonytailExtension();
 const impeccable = createImpeccableExtension();
 ```
 
+Host-owned personas (any upstream `SKILL.md` tree) need no package subpath: load it with
+`loadSkillDirectory` from `@arnilo/prism/node/contribution-discovery`, register the skills and an
+instruction injector from a host extension, and persist the active mode in session entries — see
+[`examples/caveman-ponytail.ts`](../examples/caveman-ponytail.ts).
+
 ## Security & Import Isolation
 
 - Importing `@arnilo/prism-coding-tools/agent` never loads Docker sandbox adapters, desktop MCP bridges, document parser peers, or Dev inspector modules.
-- Document parser peers (`pdf-parse`, `mammoth`) and Ponytail optional peer fail closed when absent.
+- Document parser peers (`pdf-parse`, `mammoth`) fail closed when absent.
 - Persona extensions are pure prompt and behavior modifiers and never gain implicit host privileges.

package/docs/context-and-skills.md

@@ -198,16 +198,15 @@ await agent.createSession().run("…", { activeSkills: ["ponytail"] });
 // Turn 1: catalog only. After load_skill({ name: "ponytail" }), later turns include instructions.
 ```
 
-### Third-party behavior packages (Caveman, Ponytail, Impeccable)
+### Third-party behavior packages (Impeccable, host-owned personas)
 
-`@arnilo/prism-coding-tools/caveman` and `@arnilo/prism-coding-tools/ponytail` register upstream skills into the extension kernel skill registry. Hosts should:
+`@arnilo/prism-coding-tools/impeccable` registers its upstream skill into the extension kernel skill registry from a host-supplied `upstreamPath`. For any other upstream persona, the host keeps the same shape with public APIs only:
 
-1. `kernel.load([createCavemanExtension(...), createPonytailExtension(...)])` with session `appendEntry` / `getEntries` callbacks.
-2. Build `createSkillRegistry(kernel.registries.skills.list())` and pass `activeSkills` / `resolveActiveSkills` names.
-3. Keep `skillsDisclosure: "progressive"` and register `createLoadSkillTool` — full `SKILL.md` bodies stay catalog-only until `load_skill`.
-4. Select `instructionInjectors: ["caveman-mode", "ponytail-mode"]` (or subset) for mode/level slices **without** forcing `skillsDisclosure: "eager"`.
+1. Load the `SKILL.md` tree with `loadSkillDirectory` from `@arnilo/prism/node/contribution-discovery` (bounded reads, symlink-contained), and register each skill from an extension `setup()`; log the skills registry with `createSkillRegistry(kernel.registries.skills.list())` and pass `activeSkills` / `resolveActiveSkills` names.
+2. Keep `skillsDisclosure: "progressive"` and register `createLoadSkillTool` — full `SKILL.md` bodies stay catalog-only until `load_skill`.
+3. Register an instruction injector (`api.registerInstructionInjector`) for the mode/level slice and a command that persists the mode as a session `custom` entry, restoring it on the next load — **without** forcing `skillsDisclosure: "eager"`.
 
-Mode slices and skill bodies are independent: the injector can add `PONYTAIL MODE ACTIVE` while `ponytail-audit` remains catalog-only until loaded. See [Caveman](caveman.md), [Ponytail](ponytail.md), [Impeccable](impeccable.md), and `examples/caveman-ponytail.ts`.
+Mode slices and skill bodies are independent: the injector can add `PONYTAIL MODE ACTIVE` while `ponytail-audit` remains catalog-only until loaded. See [Impeccable](impeccable.md), [Contribution discovery](contribution-discovery.md), and `examples/caveman-ponytail.ts`.
 
 Pure validation without the tool: `resolveSkillLoad({ registry, name, tools, loaded, activeSkillNames })`.
 

package/docs/contribution-discovery.md

@@ -64,6 +64,18 @@ The markdown body below the front fence becomes `Skill.instructions`. Unknown fr
 | `--discover-kinds <csv>` | Kinds to scan. Defaults to `skill`. Accepts `skill,tool,context,instructions`. |
 | `--no-discovery` | Hard-disable discovery even if `--discover` is set. |
 
+### `loadSkillDirectory` (third-party skill trees)
+
+`discoverContributions` scans only `<workspaceRoot>/.agents/<kind>s/<name>/`. To load a tree you already own — an upstream persona checkout, a provider's compiled skills, a vendored `SKILL.md` set — use `loadSkillDirectory(directory, options?)` from `@arnilo/prism/node/contribution-discovery`:
+
+```ts
+import { loadSkillDirectory } from "@arnilo/prism/node/contribution-discovery";
+
+const skills = await loadSkillDirectory("/opt/upstream/skills", { maxSkillBytes: 64 * 1024 });
+```
+
+It reads `<directory>/<name>/SKILL.md` and returns inert `Skill[]` sorted by directory name. Subdirectories without `SKILL.md`, plain files, and symlinks that escape `directory` are skipped; an unreadable `directory` or a file over `options.maxSkillBytes` (default `HARD_MAX_SKILL_INSTRUCTION_BYTES`, 262 144) throws. No trust policy, no permission callback, and no `import()`: the host naming the directory is the authority, exactly as with the deleted persona subpaths (see `examples/caveman-ponytail.ts`).
+
 ## Outputs / response / events
 
 `discoverContributions()` returns `readonly DiscoveredContribution[]`. Each envelope has `kind`, `name`, `origin` (`"global"` | `"workspace"`), `path`, and either `skill` (for the `skill` kind) or `declaration` (a `ManifestContributionDeclaration` for other kinds), plus optional `metadata`. The envelope is inert: it contains no executable code, no credential, and no resolved provider/model/tool reference.
@@ -131,6 +143,7 @@ A complete runnable example lives at `examples/discover-skills.ts`.
 - **Workspace gating**: workspace roots are checked through `createPathTrustPolicy` + `isPathInsideReal`, which resolve symlinks and fail closed (return false) if either root or target cannot be resolved. Untrusted workspace roots are skipped silently, never thrown over. Permission is asserted per directory read via `assertPermission`.
 - **Symlink handling**: symlinked entries that escape the kind root after realpath resolution are excluded. `SKILL.md` and `manifest.json` are also realpath-checked against their contribution directory before read, so an entry-file symlink cannot escape to another path.
 - **Opt-in**: discovery is opt-in — it runs only when the host passes `--discover` or calls `discoverContributions()` explicitly. Default runs perform no filesystem I/O.
+- **Bounded third-party trees**: `loadSkillDirectory` reads one level (`<dir>/<name>/SKILL.md`), realpath-checks each directory and entry file against the supplied root, and fails closed on a missing directory or an over-cap file; the host names the root, so no workspace trust decision is implied.
 - **No auto-execute**: discovery reads text. It does not `import()`, `require()`, or run contribution code. `registerDiscoveredContributions` registers descriptor stubs whose execution methods throw — the host lifts them into live tools/providers itself.
 - **No auto-activate**: discovery registers skills; it does not select them. Activation requires explicit `RunOptions.activeSkills`, and `toolNames` is still validated against the resolved tool set. Discovery grants no tools, permissions, or provider slots.
 - **No provider scanning**: provider/model discovery stays config/package-driven (Phase 24). See [Provider packages](provider-packages.md).

package/docs/durable-runs.md

@@ -49,20 +49,26 @@ head = "commit-2"; // the next checkpoint records the new commit
 ```ts
 await lifecycle.resume(ref, { decision: "approve", expectedVersion }, {
   restoreHooks: [
+    {
+      id: "docs",
+      restore: (cp) => docs.restoreVersion(cp.metadata?.docVersion),
+      compensate: () => docs.restoreVersion(previousVersion),
+    },
     async function restoreGit(cp) {
       await git.reset(cp.metadata?.gitCommit);
     },
-    async function restoreDocs(cp) {
-      await docs.restoreVersion(cp.metadata?.docVersion);
-    },
   ],
   restoreHookTimeoutMs: 10_000, // default, per hook
 });
 ```
 
+A bare function is the plan 094 form: the audit names it by `fn.name`, and it has no undo. The object
+form `{ id?, restore, compensate? }` adds a stable audit name and the layer's own undo handler.
+
 All-or-nothing:
 
 - The first hook that throws or overruns `restoreHookTimeoutMs` (default 10 s, `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`) aborts the resume with `CheckpointRestoreError` — `code: "ERR_PRISM_CHECKPOINT_RESTORE"`, `hook` naming the layer, `cause` the original error. Later hooks do not run.
+- A failing restore compensates the applied layers in reverse order, starting with the failing hook itself — a half-applied layer is put back by its own `compensate` — each under the same `restoreHookTimeoutMs`. The error carries `compensation: { ran: [<hook names, most recent first>], failed?: { hook, reason } }`; the first compensation failure is recorded (reason redacted and capped at 1 KiB) and never replaces the original `cause`, and the pass continues with the remaining layers. A caller abort stops the pass and rethrows the abort. Compensation is best-effort: the checkpoint stays unclaimed and resumable either way, so a host fixes the failing layer and retries the whole resume.
 - The claim write and the conversation replay happen only after every hook succeeds, so a failed restore leaves the checkpoint byte-for-byte as it was — still resumable — instead of claiming a half-restored world. The server maps the failure to `409`/`ERR_PRISM_CHECKPOINT_RESTORE`.
 - Hooks run on claiming resumes only; `deny` and resuspend paths never call them.
 - The claim's `agent_resumed` event carries the audit: `restore: { hooks: [{ hook, durationMs }], durationMs }`.
@@ -125,6 +131,7 @@ The complete network-free demo — one tool execution across the crash, resumed
 
 - `"continue"` is a host-API action only. Prism's AG-UI interrupt resolution accepts `approve`/`deny` only, channel adapters resume with `deny`, and there is no server route that forwards an untrusted `continue`; adding one would create an approval-bypass path.
 - Restore hooks are trusted host code running outside the sandbox: they see the checkpoint's (already redacted) sidecar map and are bounded only by their timeout. Because they run before the claim write, a timeout cannot leave a claimed checkpoint pointing at un-restored external state.
+- Compensation reports only hook names and `compensation.failed.reason`: the failing handler's message, redacted by the configured agent/lifecycle redactor and capped at 1 KiB. Hook arguments and the sidecar map are never copied into the report; the original error stays in `cause` and crosses the server boundary as before.
 - Every gate that protects a suspension protects a continue resume: exact ownership, fencing token, fingerprint, revision, CAS version, and the absence of unresolved work. A running checkpoint is a recovery point, never an authorization.
 - Cost is one bounded checkpoint write per provider turn (same redaction and `maxStateBytes` ceiling as suspension writes). A 40-turn investigation under `"every-turn"` therefore writes 40 checkpoint rows plus the terminal save, while the default `"decision"` policy writes at most one row per approval or suspension. Each row carries the run frontier, counters, run limits, and loop snapshot — not the message history, which stays in the session store and is pointed at by `leafId` — so the store grows with turns, not with turns × transcript; a state that would exceed `maxStateBytes` (default 256 KiB, `DEFAULT_MAX_AGENT_RUN_STATE_BYTES`) fails closed rather than truncating. Pick `"every-turn"` when a worker restart must cost at most one turn of thinking, and leave the default for runs with many cheap turns.
 - Checkpoints never contain provider objects, callbacks, signals, credentials, or raw secrets; the payload is bounded and redacted like any other durable state.

package/docs/embeddings.md

@@ -95,7 +95,9 @@ await runEmbeddingsConformance({
   and the reranker through the same runtime should point them at one weight cache:
   one `cacheDir` per host (e.g. `~/.cache/prism/models`), one subdirectory per
   model id, so each model is downloaded once and shared by every process on that
-  host; a cache miss downloads into that directory and later runs stay on disk.
+  host; a cache miss downloads into that directory and later runs stay on disk. The live reranker
+  leg runs exactly that pair — a semantic embedder and the cross-encoder into one cache dir — and
+  records both subdirectories ([semantic reranker evidence](_evidence/phase111-reranker-semantic-recall.md)).
 - Adapters never auto-chunk: a batch over the provider cap rejects with
   `batch_too_large`, so `embedBatched`-style callers own batching and preserve
   per-item error attribution.

package/docs/execution-timeline.md

@@ -70,6 +70,8 @@ interface ExecutionTimeline {
   readonly workflowRevision?: string;
   /** Workflow checkpoint sidecar metadata (`WorkflowCheckpointValue.metadata`); present only when projected with a checkpoint. */
   readonly workflowMetadata?: Readonly<Record<string, unknown>>;
+  /** Restore-hook audit from the claiming `agent_resumed` / `workflow_resumed` event (plan 094 Task 3); hook names and durations only, absent when the run never resumed or resumed without hooks. */
+  readonly restore?: CheckpointRestoreAudit;
   readonly traceId?: string;
   readonly status: string;
   readonly stopReason?: AgentFinishReason;
@@ -88,6 +90,10 @@ interface ExecutionTimeline {
 }
 ```
 
+`restore` is the same `{ hooks: [{ hook, durationMs }], durationMs }` the claiming resume event published, in
+run order — a metadata-only audit (hook names are host-chosen identifiers), so it projects under every
+content policy and never carries prompts, tool arguments, or node payloads.
+
 ### `ExecutionStep`
 
 ```ts

package/docs/extensions.md

@@ -169,9 +169,8 @@ const stop = forwardAgentEvents(session.subscribe(), kernel.events, { onError: (
 - [Compaction and retry policies](compaction-and-retry.md): compaction strategy/retry policy contributions and `compaction`/`retry` middleware runtime behavior.
 - [LLM compaction package](compaction-llm.md): optional extension helper that registers a provider-backed compaction strategy.
 - [Observational memory compaction package](compaction-observational-memory.md): optional extension helper that registers an inert fast memory compaction strategy.
-- [Caveman behavior integration](caveman.md): optional `@arnilo/prism-coding-tools/caveman` upstream Caveman skills, commands, level injector, and session `caveman-level` persistence.
-- [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-coding-tools/ponytail` upstream Ponytail skills, commands, mode injector, and session `ponytail-mode` persistence.
 - [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-coding-tools/impeccable` upstream Impeccable skill and `load_skill` command.
+- [Contribution discovery](contribution-discovery.md): `loadSkillDirectory` loads a host-supplied `<dir>/<name>/SKILL.md` tree for host-owned personas (`examples/caveman-ponytail.ts`).
 - [Public contracts](public-contracts.md): `Extension`, `ExtensionAPI`, and contribution contract types.
 - [Credentials and redaction](credentials-and-redaction.md): secret-redaction behavior used for extension errors.
 

package/docs/impeccable.md

@@ -98,7 +98,6 @@ Keep `skillsDisclosure: "progressive"` so the full `SKILL.md` stays catalog-only
 
 ## Related APIs
 
-- [Caveman behavior integration](caveman.md)
-- [Ponytail behavior integration](ponytail.md)
 - [Extension kernel and event bus](extensions.md)
 - [Context and skills](context-and-skills.md)
+- [Contribution discovery](contribution-discovery.md): `loadSkillDirectory` for host-owned upstream skill trees (the removed Caveman/Ponytail pattern).