@vib-rato/agent-core 0.16.0

package/src/append-only-context.ts

@@ -0,0 +1,496 @@
+/**
+ * Append-only context mode — stabilizes the byte prefix sent to the LLM
+ * across turns so provider prefix caches (DeepSeek, Anthropic, etc.)
+ * hit at the maximum possible rate.
+ *
+ * Two mechanisms:
+ *
+ * 1. **StablePrefix** — system prompt + tool specs are computed once
+ *    and frozen. Subsequent turns reuse the exact same byte sequence
+ *    unless `invalidate()` is called (e.g. after MCP reconnect).
+ *
+ * 2. **AppendOnlyLog** — messages only grow; prior turns are never
+ *    re-serialized. Combined with a stable prefix, only the user's new
+ *    message delta is a cache miss each turn.
+ */
+
+import type { Context, Message, Tool } from "@vib-rato/ai";
+import { normalizeTools } from "./agent-loop";
+import type { AgentContext } from "./types";
+
+// ---------------------------------------------------------------------------
+// StablePrefix (formerly ImmutablePrefix)
+// ---------------------------------------------------------------------------
+
+/** Frozen system prompt + tool spec snapshot. */
+export interface StablePrefixSnapshot {
+	systemPrompt: string[];
+	tools: Tool[];
+	fingerprint: string;
+}
+
+/** Options threaded through `build()` so the snapshot reflects loop-time settings. */
+export interface BuildOptions {
+	/** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
+	intentTracing: boolean;
+}
+
+/**
+ * A frozen prefix (system prompt + tools) that produces stable byte
+ * sequences across `build()` calls.
+ *
+ * The first `build()` snapshots the live state. Subsequent calls reuse
+ * the cached copy until `invalidate()` is called or the live state's
+ * fingerprint changes.
+ */
+export class StablePrefix {
+	#snapshot: StablePrefixSnapshot | null = null;
+	#version = 0;
+	#sourceSystemPrompt: readonly string[] | null = null;
+	#sourceTools: AgentContext["tools"] | null = null;
+	#sourceIntentTracing: boolean | null = null;
+
+	get fingerprint(): string {
+		return this.#snapshot?.fingerprint ?? "<unbuilt>";
+	}
+	get version(): number {
+		return this.#version;
+	}
+	get built(): boolean {
+		return this.#snapshot !== null;
+	}
+
+	exportSnapshot(): StablePrefixSnapshot | null {
+		return this.#snapshot ? cloneJson(this.#snapshot) : null;
+	}
+
+	importSnapshot(snapshot: StablePrefixSnapshot, options: BuildOptions): void {
+		// The snapshot tools were already normalized by `takeSnapshot()` at export
+		// time. Re-normalizing the cloned JSON would apply `normalizeTools` a
+		// second time, which is not idempotent: a tool whose `intent` policy is a
+		// function resolves as "omit" at export (no `_i` injected), but the
+		// function value is dropped by `cloneJson`, so a second pass resolves the
+		// missing field as "optional" and injects `_i` — changing `parameters` and
+		// diverging the recomputed fingerprint from the stored one. Verify against
+		// the stored tools as-is; the deep clone still keeps `toContext()` results
+		// isolated from later mutation.
+		const systemPrompt = cloneJson(snapshot.systemPrompt);
+		const tools = cloneJson(snapshot.tools);
+		const fingerprint = computeFingerprint(systemPrompt, tools, options);
+		this.#sourceSystemPrompt = null;
+		this.#sourceTools = null;
+		this.#sourceIntentTracing = null;
+		if (fingerprint !== snapshot.fingerprint) {
+			throw new Error(
+				`StablePrefix.importSnapshot() fingerprint mismatch: expected ${fingerprint}, received ${snapshot.fingerprint}`,
+			);
+		}
+		this.#snapshot = { systemPrompt, tools, fingerprint };
+		this.#version++;
+	}
+
+	/**
+	 * Build or rebuild from live context.
+	 * Returns `true` if the prefix actually changed (cache miss imminent).
+	 */
+	build(context: AgentContext, options: BuildOptions): boolean {
+		if (
+			this.#snapshot &&
+			this.#sourceSystemPrompt === context.systemPrompt &&
+			this.#sourceTools === context.tools &&
+			this.#sourceIntentTracing === options.intentTracing
+		) {
+			const sourceFingerprint = takeSnapshot(context, options).fingerprint;
+			if (this.#snapshot.fingerprint === sourceFingerprint) return false;
+		}
+		const snapshot = takeSnapshot(context, options);
+		if (this.#snapshot && this.#snapshot.fingerprint === snapshot.fingerprint) {
+			this.#sourceSystemPrompt = context.systemPrompt;
+			this.#sourceTools = context.tools;
+			this.#sourceIntentTracing = options.intentTracing;
+			return false;
+		}
+		this.#snapshot = snapshot;
+		this.#sourceSystemPrompt = context.systemPrompt;
+		this.#sourceTools = context.tools;
+		this.#sourceIntentTracing = options.intentTracing;
+		this.#version++;
+		return true;
+	}
+
+	/** Force rebuild on the next `build()` call. */
+	invalidate(): void {
+		this.#snapshot = null;
+		this.#sourceSystemPrompt = null;
+		this.#sourceTools = null;
+		this.#sourceIntentTracing = null;
+	}
+
+	/**
+	 * Returns the cached prefix.
+	 * @throws if `build()` was never called.
+	 */
+	toContext(): { systemPrompt: string[]; tools: Tool[] } {
+		const s = this.#snapshot;
+		if (!s) throw new Error("StablePrefix.toContext() called before build()");
+		return { systemPrompt: cloneJson(s.systemPrompt), tools: cloneJson(s.tools) };
+	}
+}
+
+// ---------------------------------------------------------------------------
+// AppendOnlyLog
+// ---------------------------------------------------------------------------
+
+/**
+ * Append-only message log at the `Message[]` (provider-level) layer.
+ *
+ * The only mutation path is `replaceTail()`, reserved for compaction.
+ * Every other operation is append-only.
+ */
+export class AppendOnlyLog {
+	#entries: Message[] = [];
+
+	get length(): number {
+		return this.#entries.length;
+	}
+
+	append(message: any): void {
+		this.#entries.push(message);
+	}
+
+	extend(messages: any[]): void {
+		for (const m of messages) this.#entries.push(m);
+	}
+
+	/** Replace the last entry — only legal for compaction. */
+	replaceTail(replacement: any): void {
+		const idx = this.#entries.length - 1;
+		if (idx >= 0) this.#entries[idx] = replacement;
+	}
+
+	/** Returns a shallow copy of all entries. */
+	toMessages(): Message[] {
+		return this.#entries.slice();
+	}
+
+	/** Direct readonly access for in-place inspection. */
+	entries(): readonly Message[] {
+		return this.#entries;
+	}
+
+	clear(): void {
+		this.#entries = [];
+	}
+}
+
+// ---------------------------------------------------------------------------
+// AppendOnlyContextManager
+// ---------------------------------------------------------------------------
+
+/**
+ * Manages a stable prefix + append-only log for the agent loop.
+ *
+ * Call `build(context)` each turn to get a `Context` with stable
+ * `systemPrompt` and `tools` and append-only messages. Call
+ * `syncMessages(normalizedMessages)` after `convertToLlm` each
+ * turn to keep the log in sync.
+ *
+ * Example:
+ * ```
+ * const mgr = new AppendOnlyContextManager();
+ * const ctx = mgr.build(context);  // first call snapshots prefix
+ * mgr.syncMessages(normalized);    // grow the log
+ * ctx = mgr.build(context);        // subsequent calls use cache
+ * ```
+ */
+export interface AppendOnlyContextManagerOptions {
+	/**
+	 * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+	 * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+	 * not throw. `from` is `<unbuilt>` on the first build.
+	 */
+	readonly onPrefixChange?: (info: { from: string; to: string; version: number }) => void;
+}
+
+export class AppendOnlyContextManager {
+	readonly prefix = new StablePrefix();
+	readonly log = new AppendOnlyLog();
+	/** How many normalized messages were synced into the log as of the last sync. */
+	#lastSyncCount = 0;
+	/** Per-synced-message content hashes (rolling digest). Detects in-place rewrites without retaining a full serialized-history string. */
+	#syncedHashes: (number | bigint)[] = [];
+	/** Number of provider-normalized messages that were seeded before child-local messages. */
+	#seededPrefixCount = 0;
+	readonly #onPrefixChange: AppendOnlyContextManagerOptions["onPrefixChange"];
+
+	constructor(options: AppendOnlyContextManagerOptions = {}) {
+		this.#onPrefixChange = options.onPrefixChange;
+	}
+
+	static forkFromSeed(args: {
+		prefixSnapshot?: StablePrefixSnapshot;
+		messages?: readonly Message[];
+		options: BuildOptions;
+	}): AppendOnlyContextManager {
+		const manager = new AppendOnlyContextManager();
+		if (args.prefixSnapshot) {
+			manager.prefix.importSnapshot(args.prefixSnapshot, args.options);
+		}
+		if (args.messages) {
+			manager.seedNormalizedMessages(args.messages);
+		}
+		return manager;
+	}
+
+	build(context: AgentContext, options: BuildOptions): Context {
+		const previousFingerprint = this.prefix.fingerprint;
+		const changed = this.prefix.build(context, options);
+		if (changed && this.#onPrefixChange) {
+			this.#onPrefixChange({
+				from: previousFingerprint,
+				to: this.prefix.fingerprint,
+				version: this.prefix.version,
+			});
+		}
+		const { systemPrompt, tools } = this.prefix.toContext();
+		return { systemPrompt, messages: this.log.toMessages(), tools };
+	}
+
+	/**
+	 * Sync normalized (provider-level) messages into the append-only log.
+	 *
+	 * Detects both compaction (shorter array) and in-place rewrites
+	 * (same length, changed content via a rolling digest).
+	 */
+	syncMessages(normalizedMessages: any[]): void {
+		const seededPrefixLength = this.#seededPrefixCount;
+		const includesSeedPrefix =
+			seededPrefixLength > 0 &&
+			normalizedMessages.length >= seededPrefixLength &&
+			this.#rangeHashesEqual(normalizedMessages, this.log.entries(), seededPrefixLength);
+		const messagesToSync =
+			seededPrefixLength > 0 && !includesSeedPrefix
+				? [...this.log.entries().slice(0, seededPrefixLength), ...normalizedMessages]
+				: normalizedMessages;
+
+		// Detect in-place rewrites of already-synced messages via per-message content
+		// hashes (no retained full serialized-history string; F5).
+		if (
+			this.#lastSyncCount > 0 &&
+			this.#lastSyncCount <= messagesToSync.length &&
+			this.#prefixChanged(messagesToSync, this.#lastSyncCount)
+		) {
+			if (this.#seededPrefixCount > 0) {
+				// F9: a seeded fork whose inherited prefix changed (e.g. after compaction)
+				// rebases onto the new provider context instead of throwing.
+				this.#rebaseToBaseline(messagesToSync, seededPrefixLength);
+				return;
+			}
+			this.log.clear();
+			this.#lastSyncCount = 0;
+			this.#syncedHashes = [];
+		}
+
+		// Compaction — array shrunk. Seeded forks preserve the inherited prefix and
+		// append child-local deltas, so a shorter child array is not a compaction signal
+		// while a seed prefix is active; a genuine seeded compaction rebases (F9).
+		if (messagesToSync.length < this.#lastSyncCount) {
+			if (this.#seededPrefixCount > 0) {
+				this.#rebaseToBaseline(messagesToSync, seededPrefixLength);
+				return;
+			}
+			this.log.clear();
+			this.#lastSyncCount = 0;
+			this.#syncedHashes = [];
+		}
+
+		const newMsgs = messagesToSync.slice(this.#lastSyncCount);
+		for (const msg of newMsgs) {
+			this.log.append(cloneJson(msg));
+		}
+
+		this.#lastSyncCount = messagesToSync.length;
+		this.#syncedHashes = this.#hashRange(messagesToSync, 0, messagesToSync.length);
+	}
+
+	seedNormalizedMessages(messages: readonly Message[], options?: { reset?: boolean }): void {
+		if (this.log.length > 0 && options?.reset !== true) {
+			throw new Error("AppendOnlyContextManager.seedNormalizedMessages() cannot seed a non-empty log without reset");
+		}
+		const clonedMessages = cloneJson([...messages]);
+		this.log.clear();
+		this.log.extend(clonedMessages);
+		this.#lastSyncCount = clonedMessages.length;
+		this.#syncedHashes = this.#hashRange(clonedMessages, 0, clonedMessages.length);
+		this.#seededPrefixCount = clonedMessages.length;
+	}
+
+	/** Reset prefix + log for a model/provider switch while mode stays active. */
+	invalidateForModelChange(): void {
+		this.prefix.invalidate();
+		this.log.clear();
+		this.#lastSyncCount = 0;
+		this.#syncedHashes = [];
+		this.#seededPrefixCount = 0;
+	}
+
+	/** Reset the sync cursor AND clear the log. */
+	resetSyncCursor(): void {
+		this.log.clear();
+		this.#lastSyncCount = 0;
+		this.#syncedHashes = [];
+		this.#seededPrefixCount = 0;
+	}
+
+	appendMessage(message: any): void {
+		this.log.append(message);
+	}
+
+	replaceTailMessage(message: any): void {
+		this.log.replaceTail(message);
+	}
+
+	/** Release provider-normalized retainers as one history-rewrite transaction. */
+	releaseAfterHistoryRewrite(options: { preserveSeededPrefix?: boolean } = {}): void {
+		const seeded = options.preserveSeededPrefix === true ? this.#seededPrefixCount : 0;
+		const prefix = seeded > 0 ? this.log.entries().slice(0, seeded) : [];
+		this.log.clear();
+		if (prefix.length > 0) this.log.extend(prefix);
+		this.#lastSyncCount = prefix.length;
+		this.#seededPrefixCount = prefix.length;
+		this.#syncedHashes = this.#hashRange(prefix, 0, prefix.length);
+		this.invalidate();
+	}
+	invalidate(): void {
+		this.prefix.invalidate();
+	}
+
+	reset(context: AgentContext, options: BuildOptions): void {
+		this.prefix.invalidate();
+		this.log.clear();
+		this.#lastSyncCount = 0;
+		this.#syncedHashes = [];
+		this.#seededPrefixCount = 0;
+		this.prefix.build(context, options);
+	}
+
+	#hashMessage(message: unknown): number | bigint {
+		return hashSource(JSON.stringify(message) ?? "null");
+	}
+
+	#hashRange(messages: readonly unknown[], start: number, end: number): (number | bigint)[] {
+		const out: (number | bigint)[] = [];
+		for (let i = start; i < end; i++) out.push(this.#hashMessage(messages[i]));
+		return out;
+	}
+
+	/** True when the first `count` messages of `a` and `b` are content-equal by per-message hash. */
+	#rangeHashesEqual(a: readonly unknown[], b: readonly unknown[], count: number): boolean {
+		for (let i = 0; i < count; i++) {
+			if (this.#hashMessage(a[i]) !== this.#hashMessage(b[i])) return false;
+		}
+		return true;
+	}
+
+	/** True when any of the first `count` already-synced messages changed content (in-place rewrite). */
+	#prefixChanged(messages: readonly unknown[], count: number): boolean {
+		if (count > this.#syncedHashes.length) return false;
+		for (let i = 0; i < count; i++) {
+			if (this.#hashMessage(messages[i]) !== this.#syncedHashes[i]) return true;
+		}
+		return false;
+	}
+
+	/** F9: reset the log to a new provider-visible baseline after seeded compaction/rebase. */
+	#rebaseToBaseline(messages: readonly unknown[], seededPrefixCount = 0): void {
+		this.log.clear();
+		this.log.extend(messages.map(message => cloneJson(message)));
+		this.#lastSyncCount = messages.length;
+		this.#seededPrefixCount = seededPrefixCount;
+		this.#syncedHashes = this.#hashRange(messages, 0, messages.length);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot helpers
+// ---------------------------------------------------------------------------
+
+function hashSource(source: string): number | bigint {
+	return typeof Bun !== "undefined" ? Bun.hash(source) : hashString32(source);
+}
+
+function hashString32(value: string): number {
+	let hash = 0;
+	for (let i = 0; i < value.length; i++) {
+		hash = ((hash << 5) - hash + value.charCodeAt(i)) | 0;
+	}
+	return hash >>> 0;
+}
+
+function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
+	const systemPrompt = [...context.systemPrompt];
+	const tools = normalizeTools(context.tools, options.intentTracing) ?? [];
+	return {
+		systemPrompt,
+		tools,
+		fingerprint: computeFingerprint(systemPrompt, tools, options),
+	};
+}
+
+export function cloneJson<T>(value: T): T {
+	return cloneJsonValue(value) as T;
+}
+
+function cloneJsonValue(value: unknown, key = "", applyToJson = true): unknown {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "number") return Number.isFinite(value) ? value : null;
+	// JSON.stringify drops function/symbol/undefined values (object props
+	// omitted, array elements become null via the array walk below).
+	if (type === "undefined" || type === "function" || type === "symbol") return undefined;
+	if (type !== "object") return value;
+	if (applyToJson) {
+		// JSON.stringify performs a single Get of `toJSON` per holder/key and
+		// serializes the returned replacement WITHOUT re-dispatching the
+		// replacement's own toJSON at the same level (nested properties still
+		// dispatch normally). Mirror that exactly to keep byte parity.
+		const toJSON = (value as { toJSON?: unknown }).toJSON;
+		if (typeof toJSON === "function") {
+			return cloneJsonValue(toJSON.call(value, key), key, false);
+		}
+	}
+	if (Array.isArray(value)) {
+		const cloned: unknown[] = new Array(value.length);
+		for (let i = 0; i < value.length; i++) {
+			const item = Object.hasOwn(value, i) ? cloneJsonValue(value[i], String(i)) : undefined;
+			cloned[i] = item === undefined ? null : item;
+		}
+		return cloned;
+	}
+	const cloned: Record<string, unknown> = {};
+	for (const key of Object.keys(value as object)) {
+		const clonedValue = cloneJsonValue((value as Record<string, unknown>)[key], key);
+		if (clonedValue !== undefined) cloned[key] = clonedValue;
+	}
+	return cloned;
+}
+
+function computeFingerprint(systemPrompt: string[], tools: Tool[], options: BuildOptions): string {
+	const payload = JSON.stringify({
+		s: systemPrompt,
+		t: tools.map(t => ({
+			n: t.name,
+			d: t.description,
+			p: t.parameters,
+			s: t.strict,
+			cf: t.customFormat,
+			cw: t.customWireName,
+		})),
+		i: options.intentTracing,
+	});
+	let hash = 0;
+	for (let i = 0; i < payload.length; i++) {
+		hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;
+	}
+	return (hash >>> 0).toString(36);
+}

package/src/attempt-scope.ts

@@ -0,0 +1,195 @@
+/**
+ * Per-attempt scope identity for request-scoped execution attribution.
+ *
+ * An AttemptScope is an immutable, frozen value allocated before every
+ * observable lifecycle emission for a single provider/agent attempt.
+ * It carries a stable `attemptId`, a monotonic `generation` (per-lineage),
+ * and a `lineage` discriminator that distinguishes the main attempt from
+ * concurrent side attempts (IRC background, ephemeral/btw turns).
+ *
+ * The `attemptId` + `generation` + `lineage` form the comparable identity.
+ * AttemptScope is structurally assignable to AttemptScopeRef in
+ * `packages/ai` so it can be carried through `SimpleStreamOptions` and
+ * provider hook signatures without a reverse dependency.
+ */
+export type AttemptLineage = "main" | `side:${string}`;
+
+export interface AttemptScope {
+	readonly attemptId: string;
+	readonly generation: number;
+	readonly lineage: AttemptLineage;
+}
+
+export function attemptScopesEqual(a: AttemptScope, b: AttemptScope): boolean {
+	return a.attemptId === b.attemptId && a.generation === b.generation && a.lineage === b.lineage;
+}
+
+/**
+ * Per-lineage currentness authority. Main and side attempts have separate
+ * instances so a side attempt never invalidates the main scope, and
+ * `forceAbort` advances only the main lineage.
+ */
+export interface LineageCurrentness {
+	readonly lineage: AttemptLineage;
+	/** True iff no successor scope with a greater generation was allocated in this lineage. */
+	isCurrent(scope: AttemptScope): boolean;
+	/** Allocate the next generation for the given attempt identity in this lineage. */
+	advance(attemptId: string): number;
+	/** Allocate the next generation in this lineage. */
+	/** Current generation value for this lineage. */
+	readonly current: number;
+}
+
+export function createLineageCurrentness(lineage: AttemptLineage): LineageCurrentness {
+	let current = 0;
+	let currentAttemptId: string | undefined;
+	return {
+		lineage,
+		get current() {
+			return current;
+		},
+		isCurrent(scope: AttemptScope): boolean {
+			return scope.lineage === lineage && scope.generation === current && scope.attemptId === currentAttemptId;
+		},
+		advance(attemptId: string): number {
+			currentAttemptId = attemptId;
+			return ++current;
+		},
+	};
+}
+
+/**
+ * Agent-owned authority over all attempt lineages. Owns the main lineage;
+ * side lineages are registered/removed with bounded lifecycle.
+ *
+ * This is the SINGLE source of currentness truth injected into
+ * AttemptRecordStore (packages/coding-agent). Every store operation
+ * calls `authority.isCurrent(scope)` and fails closed when the authority
+ * is missing or the scope is superseded.
+ */
+export interface AttemptScopeAuthority {
+	/** Register a side-lineage authority. Returns an unregister function. */
+	registerSide(lineage: AttemptLineage, auth: LineageCurrentness): () => void;
+	/** True iff the scope's lineage is known and its generation is current. */
+	isCurrent(scope: AttemptScope): boolean;
+	/** Advance the main lineage (called by forceAbort). Returns the new generation. */
+	advanceMain(): number;
+	/** Mint the next main-lineage scope. */
+	mintMain(): AttemptScope;
+	/**
+	 * Atomically register a fresh side lineage, mint a side scope, and return
+	 * both the scope and a dispose function. The authority knows the lineage
+	 * BEFORE the scope is returned, so `isCurrent` succeeds immediately.
+	 */
+	mintSide(): { scope: AttemptScope; dispose: () => void };
+}
+
+export interface AttemptMinter {
+	mint(lineage: AttemptLineage): AttemptScope;
+}
+
+export function createAttemptMinter(): AttemptMinter {
+	const generations = new Map<AttemptLineage, number>();
+	return {
+		mint(lineage: AttemptLineage): AttemptScope {
+			const gen = (generations.get(lineage) ?? 0) + 1;
+			generations.set(lineage, gen);
+			return Object.freeze({
+				attemptId: crypto.randomUUID(),
+				generation: gen,
+				lineage,
+			});
+		},
+	};
+}
+
+const SIDE_LRU_CAP = 1024;
+
+/**
+ * Create the Agent-owned authority. Owns the main lineage and a bounded
+ * (LRU-capped) map of side lineages. Only RETIRED side authorities are
+ * eligible for LRU eviction; a live side attempt is never silently
+ * invalidated by a newer side registration.
+ */
+export function createAttemptScopeAuthority(): AttemptScopeAuthority {
+	const mainAuth = createLineageCurrentness("main");
+	const sideAuths = new Map<AttemptLineage, LineageCurrentness>();
+	const sideOrder: AttemptLineage[] = [];
+	const retiredSet = new Set<AttemptLineage>();
+
+	function evictRetiredIfNeeded(): void {
+		// Only evict RETIRED side authorities. A live side attempt is never
+		// evicted by a newer registration.
+		while (sideOrder.length > SIDE_LRU_CAP) {
+			const retiredIdx = sideOrder.findIndex(l => retiredSet.has(l));
+			if (retiredIdx < 0) break;
+			const [removed] = sideOrder.splice(retiredIdx, 1);
+			if (removed) {
+				sideAuths.delete(removed);
+				retiredSet.delete(removed);
+			}
+		}
+	}
+
+	function mintFor(lineage: AttemptLineage, auth: LineageCurrentness): AttemptScope {
+		const attemptId = crypto.randomUUID();
+		return Object.freeze({
+			attemptId,
+			generation: auth.advance(attemptId),
+			lineage,
+		});
+	}
+
+	return {
+		registerSide(lineage: AttemptLineage, auth: LineageCurrentness): () => void {
+			if (sideAuths.has(lineage)) {
+				const idx = sideOrder.indexOf(lineage);
+				if (idx >= 0) sideOrder.splice(idx, 1);
+			}
+			sideAuths.set(lineage, auth);
+			sideOrder.push(lineage);
+			evictRetiredIfNeeded();
+			return () => {
+				if (sideAuths.get(lineage) === auth) {
+					// Mark as retired but keep in maps until eviction.
+					// isCurrent returns false for retired lineages because
+					// the auth is still present but the scope is superseded
+					// by disposal (generation stays at its last value).
+					retiredSet.add(lineage);
+					evictRetiredIfNeeded();
+				}
+			};
+		},
+		isCurrent(scope: AttemptScope): boolean {
+			if (scope.lineage === "main") return mainAuth.isCurrent(scope);
+			if (retiredSet.has(scope.lineage)) return false;
+			const auth = sideAuths.get(scope.lineage);
+			return auth ? auth.isCurrent(scope) : false;
+		},
+		advanceMain(): number {
+			// Advance main lineage to a fresh attemptId so any previously-minted
+			// main scope becomes non-current. The next mintMain() will set the
+			// real attemptId for the new attempt.
+			return mainAuth.advance(crypto.randomUUID());
+		},
+		mintMain(): AttemptScope {
+			return mintFor("main", mainAuth);
+		},
+		mintSide(): { scope: AttemptScope; dispose: () => void } {
+			const lineage = `side:${crypto.randomUUID()}` as AttemptLineage;
+			const auth = createLineageCurrentness(lineage);
+			const unregister = this.registerSide(lineage, auth);
+			const scope = mintFor(lineage, auth);
+			return { scope, dispose: unregister };
+		},
+	};
+}
+
+/**
+ * Immutable per-run attempt handle, carried through terminal/finalizer paths.
+ * Keyed by logicalRunId in the Agent's `#runHandles` map.
+ */
+export interface AttemptRunHandle {
+	readonly logicalRunId: number | import("./types.js").ManagedLogicalRunId;
+	readonly scope: AttemptScope;
+}