@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/orchestration/sdk.ts

@@ -5,6 +5,7 @@
  * exact same surface as future user-authored strategy files.
  */
 
+import type { ThinkingLevel } from "../core/types.ts";
 import type { RunLimits } from "../core/capabilities.ts";
 import { type ChildUsage, emptyUsage, type ToolEvent } from "../engine/stream.ts";
 import { type JudgePrep, prepareJudge } from "./judge.ts";
@@ -12,6 +13,7 @@ import { planModelRecovery } from "./model-retry.ts";
 import { mapWithConcurrency, Semaphore } from "./parallel.ts";
 import { aggregateResults, sumUsage } from "./reducers.ts";
 import { roleHint, type RosterMember } from "./roster.ts";
+import { agentAttemptIdentity, type AgentAttemptIdentity } from "./agent-attempt.ts";
 import type { AgentResult, ModelRecovery } from "./types.ts";
 import { type ReducerResult, type VoteOpts, voteReduce } from "./voting.ts";
 
@@ -22,6 +24,8 @@ export interface AgentRunSpec {
 	name?: string;
 	task: string;
 	model?: string;
+	/** Requested per-leg effort, before Pi applies the selected model's capability clamp. */
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	/** Skills the sub-agent must load first (dynamic specialisation). */
 	skills?: string[];
@@ -49,6 +53,22 @@ export interface AgentRunSpec {
 	peers?: boolean;
 	/** Declared ownership (from delegate `writeSet`), used only to annotate the files-changed report. */
 	writeSet?: string[];
+	/** INTERNAL (flow reference handoff): the archived `result:<UUID>` refs granted to THIS leg
+	 *  — exactly its phase's DIRECT upstream needs, nothing more. Not a public delegate
+	 *  argument: the SDK strips any strategy-supplied value (strategies cannot enlarge a
+	 *  grant); only the trusted engine-seam wrapper (`withResultRefs`, set by the flow wiring)
+	 *  or an equivalently trusted host path may set it. Both engines preflight + scope the
+	 *  `read_result` tool on it. */
+	resultRefs?: readonly string[];
+}
+
+/** Pin a leg's granted result refs at the ENGINE seam — the trusted wiring path for flow
+ *  reference mode. Overrides (never unions) whatever the caller passed, so a strategy cannot
+ *  smuggle extra refs past the SDK's strip. An empty array is an explicit "none". */
+export function withResultRefs(engine: StrategyEngine, resultRefs: readonly string[]): StrategyEngine {
+	return {
+		run: (spec, onProgress, signal, onSteer) => engine.run({ ...spec, resultRefs }, onProgress, signal, onSteer),
+	};
 }
 
 /** Is `x` a genuine positive, finite `timeoutMs` override — vs. absent/junk (undefined, NaN,
@@ -180,15 +200,17 @@ export interface SDKDeps {
 	/** Per-agent lifecycle, for live UI. The result is passed on done/failed so the
 	 *  UI can capture each agent's output/usage. `key` is a run-unique display id (the
 	 *  `agent` name for a solo member, disambiguated by role/occurrence when the same agent
-	 *  runs several times in one roster) — key the UI node by it, not by `agent`, or three
-	 *  same-agent roster-role members collapse into one node. Falls back to `agent`. */
-	onAgentStatus?: (agent: string, status: AgentStatus, result?: AgentResult, key?: string) => void;
+	 *  runs several times in one roster). The frozen `attempt` carries exact full-role/model/effort
+	 *  identity: never recover those fields by parsing this shortened display key. */
+	onAgentStatus?: (agent: string, status: AgentStatus, result: AgentResult | undefined, key: string, attempt: AgentAttemptIdentity) => void;
+	/** One final logical leg after model recovery, never intermediate attempts. Storage is non-fatal. */
+	onAgentResult?: (result: AgentResult, key: string, attempt: AgentAttemptIdentity) => void;
 	/** Per-agent streaming progress (rolling output), for live UI. See `onAgentStatus.key`. */
-	onAgentProgress?: (agent: string, progress: AgentProgress, key?: string) => void;
+	onAgentProgress?: (agent: string, progress: AgentProgress, key: string, attempt: AgentAttemptIdentity) => void;
 	/** Called as each agent starts with a handle to abort just that agent (for UI stop). */
-	onAgentStart?: (agent: string, abort: () => void, key?: string) => void;
+	onAgentStart?: (agent: string, abort: () => void, key: string, attempt: AgentAttemptIdentity) => void;
 	/** Called once an agent is live with a handle to steer it (in-process engine only). */
-	onAgentSteerable?: (agent: string, steer: SteerFn, key?: string) => void;
+	onAgentSteerable?: (agent: string, steer: SteerFn, key: string, attempt: AgentAttemptIdentity) => void;
 	/** Emitted immediately BEFORE a leg is re-run on the main model after a model-caused failure,
 	 *  so live UI can say so while it happens (`key` is the same logical node as the attempt it
 	 *  replaces). Purely cosmetic: a throw here is contained and can never discard the billed
@@ -241,6 +263,13 @@ function abortedLeg(agent: string): AgentResult {
 	return { agent, output: "", usage: emptyUsage(), ok: false, error: "agent aborted", failureKind: "abort" };
 }
 
+/** Copy of a spec with its `resultRefs` removed — the SDK's one strip point, so a strategy's
+ *  own value never reaches an engine (only `withResultRefs`-style trusted wiring sets it). */
+function stripResultRefs(spec: AgentRunSpec): AgentRunSpec {
+	const { resultRefs: _untrusted, ...rest } = spec;
+	return rest;
+}
+
 export function makeSDK(deps: SDKDeps): StrategySDK {
 	// Run-scoped enforcement of the declared limits — applied here so NO strategy can
 	// exceed them, however it calls agent() (I2: safety from runtime limits, not isolation).
@@ -269,18 +298,27 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 	};
 
 	return {
-		agent: async (spec, options) => {
+		agent: async (requested, options) => {
+			// Reference-handoff grants are trusted wiring, never strategy input: drop any
+			// strategy-supplied `resultRefs` here (the flow path re-pins them at the engine
+			// seam via `withResultRefs`, which runs BELOW this layer).
+			const spec = requested.resultRefs === undefined ? requested : stripResultRefs(requested);
+			const key = uiKeyFor(spec);
+			let currentAttempt = agentAttemptIdentity(spec);
+			const finish = (result: AgentResult): AgentResult => {
+				try { deps.onAgentResult?.(result, key, currentAttempt); } catch { /* storage must not discard a completed leg */ }
+				return result;
+			};
 			if (deps.canSpawn && !deps.canSpawn(spec.agent)) {
-				return {
+				return finish({
 					agent: spec.agent,
 					output: "",
 					usage: emptyUsage(),
 					ok: false,
 					error: `persona may not spawn "${spec.agent}"`,
 					failureKind: "contract",
-				};
+				});
 			}
-			const key = uiKeyFor(spec);
 			const pending = Symbol();
 			pendingAgents.add(pending);
 			let started = false;
@@ -302,6 +340,8 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 				const detachRoot: Array<() => void> = [];
 				let announcedStart = false;
 				const attempt = async (aSpec: AgentRunSpec): Promise<AgentResult> => {
+					const identity = agentAttemptIdentity(aSpec);
+					currentAttempt = identity;
 					const ac = current ?? new AbortController();
 					current = ac;
 					if (deps.signal) {
@@ -312,9 +352,9 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 					}
 					if (!announcedStart) {
 						announcedStart = true;
-						deps.onAgentStart?.(aSpec.agent, () => current?.abort(), key);
+						deps.onAgentStart?.(aSpec.agent, () => current?.abort(), key, identity);
 					}
-					deps.onAgentStatus?.(aSpec.agent, "running", undefined, key);
+					deps.onAgentStatus?.(aSpec.agent, "running", undefined, key, identity);
 					// A slot grant is not an engine start. Root or local cancellation in a lifecycle
 					// callback must prevent the engine invocation, not merely hand it an aborted signal.
 					if (ac.signal.aborted) {
@@ -330,9 +370,9 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 					try {
 						result = await deps.engine.run(
 							aSpec,
-							onProgress ? (p) => onProgress(aSpec.agent, p, key) : undefined,
+							onProgress ? (p) => onProgress(aSpec.agent, p, key, identity) : undefined,
 							ac.signal,
-							deps.onAgentSteerable ? (steer) => deps.onAgentSteerable?.(aSpec.agent, steer, key) : undefined,
+							deps.onAgentSteerable ? (steer) => deps.onAgentSteerable?.(aSpec.agent, steer, key, identity) : undefined,
 						);
 					} catch (err) {
 						// PER-LEG failure — contained, never rethrown: one blown engine call must not discard
@@ -349,7 +389,7 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 				};
 				try {
 					const first = await attempt(spec);
-					deps.onAgentStatus?.(spec.agent, first.ok ? "done" : "failed", first, key);
+					deps.onAgentStatus?.(spec.agent, first.ok ? "done" : "failed", first, key, currentAttempt);
 
 					// ── Main-only model recovery ──────────────────────────────────────────────
 					// A model-caused failure (`provider`/`unknown-model`) gets exactly ONE re-run on the
@@ -391,7 +431,7 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 					// a fresh controller or spend another child slot after it has been stopped.
 					if (deps.signal?.aborted || current?.signal.aborted) {
 						const stopped = { ...abortedLeg(spec.agent), usage: first.usage };
-						deps.onAgentStatus?.(spec.agent, "failed", stopped, key);
+						deps.onAgentStatus?.(spec.agent, "failed", stopped, key, currentAttempt);
 						return stopped;
 					}
 					// The retry is a REAL attempt: admitted and charged like any other child, but inside
@@ -408,18 +448,20 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 						modelRecovery: recovery,
 						...(!second.ok ? { error: `Initial model ${plan.from ?? "(unresolved)"} failed: ${first.error ?? first.failureKind ?? "unknown cause"}; main model ${plan.to} failed: ${second.error ?? second.failureKind ?? "unknown cause"}` } : {}),
 					};
-					deps.onAgentStatus?.(spec.agent, settled.ok ? "done" : "failed", settled, key);
+					deps.onAgentStatus?.(spec.agent, settled.ok ? "done" : "failed", settled, key, currentAttempt);
 					return settled;
 				} finally {
 					for (const detach of detachRoot) detach();
 				}
 			};
 			try {
-				return await agentSlots.with(run, deps.signal);
+				return finish(await agentSlots.with(run, deps.signal));
 			} catch (error) {
 				// A queued leg has no engine result to report. Settle it as an abort when the
 				// run signal removed its waiter; all other errors retain their terminal semantics.
-				if (!started && deps.signal?.aborted) return abortedLeg(spec.agent);
+				if (!started && deps.signal?.aborted) {
+					return finish(abortedLeg(spec.agent));
+				}
 				throw error;
 			} finally {
 				pendingAgents.delete(pending);

package/src/orchestration/types.ts

@@ -2,7 +2,9 @@
  * Orchestration-layer types shared by the SDK, strategies, and reducers.
  */
 
+import type { ThinkingLevel } from "../core/types.ts";
 import type { ChildUsage } from "../engine/stream.ts";
+import type { ResultReceipt } from "../results/retrieval.ts";
 
 export type { ChildUsage };
 
@@ -33,11 +35,19 @@ export interface AgentResult {
 	output: string;
 	/** Validated structured fields (when the agent ran against a contract). */
 	structured?: Record<string, unknown>;
+	/** Terminal archive observation; memory-only is not a durable receipt. */
+	resultReceipt?: ResultReceipt;
 	usage: ChildUsage;
 	ok: boolean;
 	error?: string;
 	/** The canonical `provider/id` the run actually used (drives provider fallback + UI). */
 	modelUsed?: string;
+	/** Selected effort before Pi's model-capability clamp, when a selection is known. */
+	thinkingRequested?: ThinkingLevel;
+	/** Observed Pi effort (session readback or final assistant-message thinkingLevel).
+	 * This is Pi's requested effort, NOT evidence of the provider's actual cognition.
+	 * Absent when the host exposes no validated observation; never inferred from the request. */
+	thinkingEffective?: ThinkingLevel;
 	/** Why it failed (set only when `ok` is false) — drives the model-fallback decision. */
 	failureKind?: FailureKind;
 	/** Set when this result comes from a recovered retry (see {@link ModelRecovery}). Its `usage`

package/src/persona/model-participants.ts

@@ -29,6 +29,7 @@ import { createHash } from "node:crypto";
 
 import { memberBaseLabel, parseRosterMember, type RosterMember, type RosterSpec } from "../orchestration/roster.ts";
 import { knownParams } from "../orchestration/strategy.ts";
+import type { ThinkingLevel } from "../core/types.ts";
 import type { StrategyParam } from "../orchestration/sdk.ts";
 
 /** Where a participant's effective model came from — in precedence order. */
@@ -58,6 +59,12 @@ export interface ModelParticipant {
 	model?: string;
 	/** Which step of the precedence supplied `model`. */
 	source: ModelSource;
+	/** The member's SPEC-level effort — exactly the value that lands in `AgentRunSpec.thinking`
+	 *  when a strategy spreads `rosterSpec(member)`. Never resolved against agent defaults or the
+	 *  configured child effort (the engines own that precedence): the row shows what the launch
+	 *  spec carried, the same rule the delegate launch rows follow. Absent when none was declared
+	 *  (absence renders nothing); an explicit `off` is a declared value and is kept. */
+	thinking?: ThinkingLevel;
 	/** Someone already chose this participant's model (inline, a saved assignment, or the agent's own
 	 *  frontmatter) ⇒ never a picker candidate. The session default is deliberately NOT counted. */
 	assigned: boolean;
@@ -135,6 +142,7 @@ function fromSpec(spec: RosterSpec, origin: "roster" | "param", param: string |
 		...(param ? { param } : {}),
 		...(model ? { model } : {}),
 		source,
+		...(spec.thinking ? { thinking: spec.thinking } : {}),
 		assigned: source === "inline" || source === "assignment" || source === "agent",
 	};
 }
@@ -191,16 +199,13 @@ function isAgentName(value: unknown): boolean {
 	return typeof value === "string" && value.trim().length > 0 && !/\s/.test(value.trim());
 }
 
-/** Every participant a run really spawns: the roster first (in run order), then auxiliary actors. */
-export function collectModelParticipants(input: ParticipantInput): ModelParticipant[] {
+/** Every declared execution occurrence, including repeated assignment keys with different pins. */
+export function collectModelParticipantOccurrences(input: ParticipantInput): ModelParticipant[] {
 	const out: ModelParticipant[] = [];
-	const seen = new Set<string>();
 	for (const raw of input.members ?? []) {
 		const spec = toSpec(raw);
 		if (!spec) continue;
 		const p = fromSpec(spec, "roster", undefined, input);
-		if (seen.has(p.key)) continue;
-		seen.add(p.key);
 		out.push(p);
 	}
 	const schema = input.schema ?? (input.strategy ? knownParams(input.strategy) : undefined);
@@ -210,14 +215,22 @@ export function collectModelParticipants(input: ParticipantInput): ModelParticip
 			const spec = auxActorSpec(input, paramName, param);
 			if (!spec) continue;
 			const p = fromSpec(spec, "param", paramName, input);
-			if (seen.has(p.key)) continue;
-			seen.add(p.key);
 			out.push(p);
 		}
 	}
 	return out;
 }
 
+/** One row per assignment key for model setup. Repeated execution occurrences share that choice. */
+export function collectModelParticipants(input: ParticipantInput): ModelParticipant[] {
+	const seen = new Set<string>();
+	return collectModelParticipantOccurrences(input).filter((p) => {
+		if (seen.has(p.key)) return false;
+		seen.add(p.key);
+		return true;
+	});
+}
+
 /** The participants a picker may still ask about: nobody has chosen a model for them, and this
  *  session has not already asked (and been dismissed) for that key. The caller records the keys it
  *  asks about BEFORE asking, so a dismissal is remembered too. */

package/src/persona/orchestrate.ts

@@ -7,11 +7,8 @@
 import type { RunLimits } from "../core/capabilities.ts";
 import { makeRoster, type RosterMember } from "../orchestration/roster.ts";
 import {
-	type AgentProgress,
-	type AgentStatus,
 	makeSDK,
 	type SDKDeps,
-	type SteerFn,
 	type StrategyEngine,
 	type StrategyInput,
 } from "../orchestration/sdk.ts";
@@ -72,13 +69,14 @@ export interface RunStrategyDeps {
 	log?: (message: string) => void;
 	/** Per-agent lifecycle, for live UI (which roster agent is running/done + its result).
 	 *  `key` is a run-unique display id (disambiguates same-agent roster-role members). */
-	onAgentStatus?: (agent: string, status: AgentStatus, result?: AgentResult, key?: string) => void;
+	onAgentStatus?: SDKDeps["onAgentStatus"];
+	onAgentResult?: SDKDeps["onAgentResult"];
 	/** Per-agent streaming progress (rolling output), for live UI. */
-	onAgentProgress?: (agent: string, progress: AgentProgress, key?: string) => void;
+	onAgentProgress?: SDKDeps["onAgentProgress"];
 	/** Called as each agent starts with a handle to abort just that agent (UI stop). */
-	onAgentStart?: (agent: string, abort: () => void, key?: string) => void;
+	onAgentStart?: SDKDeps["onAgentStart"];
 	/** Called once an agent is live with a handle to steer it (in-process engine only). */
-	onAgentSteerable?: (agent: string, steer: SteerFn, key?: string) => void;
+	onAgentSteerable?: SDKDeps["onAgentSteerable"];
 	/** See `SDKDeps.canSpawn` — every strategy spawn, not only `delegate`. */
 	canSpawn?: (agent: string) => boolean;
 }
@@ -110,6 +108,7 @@ export async function runPersonaStrategy(
 	if (deps.onModelFallback) sdkDeps.onModelFallback = deps.onModelFallback;
 	if (deps.log) sdkDeps.log = deps.log;
 	if (deps.onAgentStatus) sdkDeps.onAgentStatus = deps.onAgentStatus;
+	if (deps.onAgentResult) sdkDeps.onAgentResult = deps.onAgentResult;
 	if (deps.onAgentProgress) sdkDeps.onAgentProgress = deps.onAgentProgress;
 	if (deps.onAgentStart) sdkDeps.onAgentStart = deps.onAgentStart;
 	if (deps.onAgentSteerable) sdkDeps.onAgentSteerable = deps.onAgentSteerable;

package/src/persona/persona.ts

@@ -244,7 +244,7 @@ export function expandCouncilPreset(draft: CouncilDraft, presets: Record<string,
 /** Per-call council selection. `persona` borrows only that persona's expanded
  * council declaration; it never activates the persona or imports its prompt,
  * model, tools, or permissions. Explicit strategy/roster/params remain local
- * overrides for backward compatibility. */
+ * overrides of those defaults. */
 export interface CouncilInvocation {
 	persona?: string | undefined;
 	strategy?: string | undefined;

package/src/results/archive.ts

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import {
+	createTerminalResultRecord, isResultRef, pageStoredBody, parseTerminalResultInput,
+	parseTerminalResultRecord, payloadBytes,
+} from "./record.ts";
+import {
+	TERMINAL_RESULT_ENTRY, RESULT_MAX_ENTRIES, RESULT_MAX_PAYLOAD_BYTES, RESULT_LIST_DEFAULT, RESULT_LIST_MAX,
+	type ArchiveEvidence, type ArchiveFailure, type ResultListRequest, type ResultPage, type ResultReadRequest,
+	type ResultStorage, type ResultSummary, type ResultSummaryPage, type ResultWarning, type SaveOutcome,
+	type TerminalResultArchiveDeps, type TerminalResultInput, type TerminalResultRecord,
+} from "./types.ts";
+
+interface RetainedResult {
+	record: TerminalResultRecord;
+	storage: ResultStorage;
+	storageError?: string;
+}
+interface SourceResult { data: unknown; index: number; retained?: RetainedResult }
+type Lookup = { kind: "missing" } | { kind: "ambiguous" | "corrupt" } | {
+	kind: "found"; record: TerminalResultRecord; index: number; retained?: RetainedResult;
+};
+
+function identity(data: unknown): { ref?: string; originKey?: string } {
+	try {
+		if (data === null || typeof data !== "object") return {};
+		const value = data as Record<string, unknown>;
+		return {
+			...(isResultRef(value.ref) ? { ref: value.ref } : {}),
+			...(typeof value.originKey === "string" && value.originKey.length <= 1024 ? { originKey: value.originKey } : {}),
+		};
+	} catch { return {}; }
+}
+
+function summary(record: TerminalResultRecord, storage: ResultStorage): ResultSummary {
+	// Parse again to detach optional usage too; callers never receive our mutable state.
+	const copy = parseTerminalResultRecord(record)!;
+	const { body: _body, payloadHash: _hash, ...metadata } = copy;
+	return { ...metadata, storage };
+}
+
+function validQuery(value: unknown, keys: readonly string[]): boolean {
+	try {
+		if (value === null || typeof value !== "object") return false;
+		const proto: unknown = Object.getPrototypeOf(value);
+		if (proto !== Object.prototype && proto !== null) return false;
+		return Reflect.ownKeys(value).every((key) => {
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			return typeof key === "string" && keys.includes(key) && descriptor?.enumerable === true && "value" in descriptor;
+		});
+	} catch { return false; }
+}
+
+function errorDetail(error: unknown): string {
+	try {
+		const text = error instanceof Error ? error.message : String(error);
+		return text.slice(0, 2048);
+	} catch { return "Storage callback threw an unreadable error"; }
+}
+
+/** One session-file owner, fixed at construction by the adapter. No filesystem, Pi imports,
+ * replay, wake or worker lifecycle. Native history is scanned without caching report bodies;
+ * even over-quota/corrupt histories leave valid unrelated reports queryable. Local accepted
+ * records and uncertain append reservations are bounded by the SAME count/byte ceilings.
+ * The native entry array is a host-owned immutable snapshot: its initial length is pinned so
+ * a host that appends to that same array cannot double-charge our own reserved writes.
+ */
+export class TerminalResultArchive {
+	private readonly deps: TerminalResultArchiveDeps;
+	private hydrated = false;
+	private hydrating = false;
+	private history: readonly unknown[] = [];
+	private historyLength = 0;
+	private historyCount = 0;
+	private chargedEntries = 0;
+	private chargedPayloadBytes: number | null = 0;
+	private localBytes = 0;
+	private readonly retained: RetainedResult[] = [];
+	private readonly warnings = new Set<ResultWarning>();
+	private saving = false;
+
+	constructor(deps: TerminalResultArchiveDeps) {
+		// Copy callbacks/flags: mutating a caller's dependency object cannot retarget this owner.
+		this.deps = { ...deps };
+	}
+
+	save(input: TerminalResultInput): SaveOutcome {
+		if (this.saving || this.hydrating) return this.failure("busy", "A terminal result save or history accounting is already in progress");
+		this.saving = true;
+		try { this.hydrate(); return this.saveInput(input); }
+		finally { this.saving = false; }
+	}
+
+	read(request: ResultReadRequest): ResultPage {
+		if (this.hydrating) return this.failure("busy", "Terminal result history accounting is in progress");
+		this.hydrate();
+		if (!validQuery(request, ["ref", "offset", "limit"]) || !isResultRef(request.ref)) {
+			return this.failure("invalid", "Expected result:<UUID> and an optional stored-body offset/limit");
+		}
+		const found = this.lookup("ref", request.ref);
+		if (found.kind === "missing") return this.failure("unavailable", "Result reference is unavailable in this owning session");
+		if (found.kind !== "found") return this.failure(found.kind, "Result identity is ambiguous or corrupt in this owning session");
+		const page = pageStoredBody(found.record, request.offset, request.limit);
+		if (!page) return this.failure("invalid", "Invalid stored-body UTF-16 offset or read limit (2..16000); surrogate pairs cannot be split");
+		return {
+			ok: true, summary: summary(found.record, this.storage(found.retained)), ...page,
+			...this.evidence(found.record, found.retained),
+		};
+	}
+
+	list(request: ResultListRequest = {}): ResultSummaryPage {
+		if (this.hydrating) return this.failure("busy", "Terminal result history accounting is in progress");
+		this.hydrate();
+		if (!validQuery(request, ["cursor", "limit"])) return this.failure("invalid", "Expected a result-list query");
+		const cursor = request.cursor === undefined ? 0 : request.cursor;
+		const limit = request.limit === undefined ? RESULT_LIST_DEFAULT : request.limit;
+		if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > this.historyCount + this.retained.length
+			|| !Number.isInteger(limit) || limit < 1 || limit > RESULT_LIST_MAX) {
+			return this.failure("invalid", "Invalid result list cursor or limit (1..50)");
+		}
+		const results: ResultSummary[] = [];
+		let nextCursor: number | undefined;
+		for (const source of this.sources()) {
+			if (source.index < cursor) continue;
+			const record = parseTerminalResultRecord(source.data);
+			if (!record) continue;
+			const found = this.lookup("ref", record.ref);
+			if (found.kind !== "found" || found.index !== source.index) continue;
+			if (results.length === limit) { nextCursor = source.index; break; }
+			results.push(summary(record, this.storage(found.retained)));
+		}
+		return { ok: true, results, ...(nextCursor === undefined ? {} : { nextCursor }), ...this.evidence() };
+	}
+
+	private saveInput(value: unknown): SaveOutcome {
+		const input = parseTerminalResultInput(value);
+		if (!input) return this.failure("invalid", "Invalid terminal result projection or metadata limits");
+		const existing = this.lookup("originKey", input.originKey);
+		if (existing.kind === "ambiguous" || existing.kind === "corrupt") {
+			return this.failure(existing.kind, "The origin already has an ambiguous or corrupt result");
+		}
+		if (existing.kind === "found") {
+			const candidate = createTerminalResultRecord(input, existing.record.ref, input.createdAt ?? existing.record.createdAt);
+			if (JSON.stringify(parseTerminalResultRecord(candidate)) !== JSON.stringify(existing.record)) {
+				return this.failure("conflict", "The immutable origin already belongs to a different terminal payload");
+			}
+			return this.receipt(existing.record, existing.retained, true);
+		}
+		let record: TerminalResultRecord;
+		try {
+			const ref = this.deps.makeRef === undefined ? `result:${randomUUID()}` : this.deps.makeRef();
+			if (!isResultRef(ref)) return this.failure("invalid", "Reference factory must return result:<UUID>");
+			const collision = this.lookup("ref", ref);
+			if (collision.kind !== "missing") return this.failure(collision.kind === "found" ? "conflict" : collision.kind, "Generated result reference is already occupied");
+			record = createTerminalResultRecord(input, ref, input.createdAt ?? (this.deps.clock === undefined ? Date.now() : this.deps.clock()));
+		} catch (error) { return this.failure("invalid", errorDetail(error)); }
+		const cost = payloadBytes(record);
+		if (this.chargedEntries >= RESULT_MAX_ENTRIES || this.localBytes + cost > RESULT_MAX_PAYLOAD_BYTES
+			|| (this.chargedPayloadBytes !== null && this.chargedPayloadBytes + cost > RESULT_MAX_PAYLOAD_BYTES)) {
+			return this.failure("quota", "Terminal result lifetime payload/count quota exhausted; append-only storage is not reclaimed");
+		}
+		// Reserve before invoking host code. A throw may occur AFTER a physical/session commit.
+		// Never retry this origin into another entry or treat memory retention as proof of durability.
+		this.chargedEntries++;
+		if (this.chargedPayloadBytes !== null) this.chargedPayloadBytes += cost;
+		this.localBytes += cost;
+		const retained: RetainedResult = { record, storage: "memory-only" };
+		this.retained.push(retained);
+		if (this.deps.persistent && this.chargedPayloadBytes !== null) {
+			try {
+				this.deps.append(TERMINAL_RESULT_ENTRY, parseTerminalResultRecord(record)!);
+				retained.storage = "session-entry";
+			} catch (error) { retained.storageError = errorDetail(error); }
+		}
+		return this.receipt(record, retained, false);
+	}
+
+	private storage(retained: RetainedResult | undefined): ResultStorage {
+		return retained?.storage ?? (this.deps.persistent ? "session-entry" : "memory-only");
+	}
+
+	private receipt(record: TerminalResultRecord, retained: RetainedResult | undefined, idempotent: boolean): SaveOutcome {
+		const storage = this.storage(retained);
+		return {
+			ok: true, ref: record.ref, storage, summary: summary(record, storage), idempotent,
+			...(retained?.storageError === undefined ? {} : { storageError: retained.storageError }),
+			...this.evidence(record, retained),
+		};
+	}
+
+	private hydrate(): void {
+		if (this.hydrated) return;
+		this.hydrated = true;
+		this.hydrating = true;
+		if (!this.deps.persistent) this.warnings.add("no-session-storage");
+		try {
+			const entries = this.deps.entries();
+			if (!Array.isArray(entries)) throw new Error("Invalid owning-session entry list");
+			this.history = entries;
+			this.historyLength = entries.length;
+			for (const source of this.sources()) {
+				this.chargedEntries++;
+				try {
+					const cost = payloadBytes(source.data);
+					if (this.chargedPayloadBytes !== null) this.chargedPayloadBytes += cost;
+					if (!Number.isSafeInteger(this.chargedPayloadBytes)) this.disablePersistence();
+				} catch { this.disablePersistence(); }
+				if (!parseTerminalResultRecord(source.data)) this.warnings.add("invalid-history");
+			}
+			this.historyCount = this.chargedEntries;
+		} catch { this.disablePersistence(); }
+		finally { this.hydrating = false; }
+	}
+
+	private *sources(): Generator<SourceResult> {
+		let index = 0;
+		for (let i = 0; i < this.historyLength; i++) {
+			try {
+				const raw = this.history[i];
+				if (raw === null || typeof raw !== "object") continue;
+				const entry = raw as Record<string, unknown>;
+				if (entry.type !== "custom" || entry.customType !== TERMINAL_RESULT_ENTRY) continue;
+				// Count the entry even when reading its data throws.
+				let data: unknown;
+				try { data = entry.data; } catch { this.disablePersistence(); }
+				yield { data, index: index++ };
+			} catch { this.disablePersistence(); }
+		}
+		for (const retained of this.retained) yield { data: retained.record, index: index++, retained };
+	}
+
+	/** Two bounded-memory scans, not a report cache or an unbounded identity index. */
+	private lookup(key: "ref" | "originKey", value: string): Lookup {
+		let first: { record: TerminalResultRecord; source: SourceResult } | undefined;
+		for (const source of this.sources()) {
+			if (identity(source.data)[key] !== value) continue;
+			const record = parseTerminalResultRecord(source.data);
+			if (!record) return { kind: "corrupt" };
+			first = { record, source };
+			break;
+		}
+		if (!first) return { kind: "missing" };
+		const canonical = JSON.stringify(first.record);
+		for (const source of this.sources()) {
+			if (source.index === first.source.index) continue;
+			const id = identity(source.data);
+			if (id.ref !== first.record.ref && id.originKey !== first.record.originKey) continue;
+			const record = parseTerminalResultRecord(source.data);
+			if (!record) return { kind: "corrupt" };
+			if (JSON.stringify(record) !== canonical) {
+				this.warnings.add("ambiguous-history");
+				return { kind: "ambiguous" };
+			}
+			this.warnings.add("duplicate-history");
+		}
+		return {
+			kind: "found", record: first.record, index: first.source.index,
+			...(first.source.retained === undefined ? {} : { retained: first.source.retained }),
+		};
+	}
+
+	private disablePersistence(): void {
+		this.chargedPayloadBytes = null;
+		this.warnings.add("accounting-unavailable");
+	}
+
+	private evidence(record?: TerminalResultRecord, retained?: RetainedResult): ArchiveEvidence {
+		const warnings = new Set(this.warnings);
+		if (record?.truncated) warnings.add("body-truncated");
+		if (retained?.storageError !== undefined) warnings.add("append-failed");
+		return {
+			accounting: {
+				chargedEntries: this.chargedEntries, chargedPayloadBytes: this.chargedPayloadBytes,
+				persistenceDisabled: !this.deps.persistent || this.chargedPayloadBytes === null,
+			}, warnings: [...warnings],
+		};
+	}
+
+	private failure(reason: ArchiveFailure["reason"], message: string): ArchiveFailure {
+		return { ok: false, reason, message, ...this.evidence() };
+	}
+}