@gajae-code/coding-agent 0.11.6 → 0.11.8

package/src/sdk/bus/lifecycle-commands.ts

@@ -49,6 +49,49 @@ const USAGE = [
 	"/session_recent [create|resume]",
 ].join("\n");
 
+function tokenizeLifecycleCommand(value: string): string[] | undefined {
+	const tokens: string[] = [];
+	let token = "";
+	let quote: '"' | "'" | undefined;
+	let started = false;
+	for (let index = 0; index < value.length; index++) {
+		const character = value[index]!;
+		if (character === "\\") {
+			const next = value[index + 1];
+			if (next !== undefined && (next === "\\" || next === '"' || next === "'" || /\s/u.test(next))) {
+				token += next;
+				index++;
+			} else token += character;
+			started = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			else token += character;
+			started = true;
+			continue;
+		}
+		if (character === '"' || character === "'") {
+			quote = character;
+			started = true;
+			continue;
+		}
+		if (/\s/u.test(character)) {
+			if (started) {
+				tokens.push(token);
+				token = "";
+				started = false;
+			}
+			continue;
+		}
+		token += character;
+		started = true;
+	}
+	if (quote) return undefined;
+	if (started) tokens.push(token);
+	return tokens;
+}
+
 /** True when the text begins with any /session_* token, regardless of addressability. */
 export function isLifecycleCommandLikeText(text: string | undefined): boolean {
 	if (!text) return false;
@@ -98,8 +141,10 @@ export function parseLifecycleCommand(
 	text: string | undefined,
 	ctx: { chatType?: string; botUsername?: string } = {},
 ): ParsedLifecycleCommand {
+	const tokens = tokenizeLifecycleCommand((text ?? "").trim());
+	if (!tokens) return { kind: "usage", message: USAGE };
+	const [rawCommand, ...args] = tokens;
 	const raw = (text ?? "").trim();
-	const [rawCommand, ...args] = raw.split(/\s+/);
 	const command = normalizeLifecycleCommandToken(rawCommand ?? "", ctx);
 	if (command === undefined) return { kind: "none" };
 
@@ -140,9 +185,8 @@ export function parseLifecycleCommand(
 
 	// /session_create <kind> ... [--mpreset <profile>]
 	const { positional, modelPreset } = extractModelPreset(args);
-	if (modelPreset !== undefined && !isSafeIdentifier(modelPreset)) {
+	if (modelPreset !== undefined && modelPreset.length === 0)
 		return { kind: "reject", reason: "invalid_target", message: `Invalid model preset name.\n\n${USAGE}` };
-	}
 	const kind = positional[0];
 	if (kind === "path") {
 		if (positional.length !== 2) return { kind: "usage", message: USAGE };
@@ -238,11 +282,12 @@ function isSafeBranch(value: string): boolean {
 /**
  * Map a lifecycle response/error to a user-facing Telegram message (G010).
  *
- * Only derives text from sessionId, mode, reason, a safe message, and candidate
- * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
- * actionable copy; an "in progress" pending response is surfaced distinctly.
+ * Only derives text from sessionId, mode, reason, a safe message, the originating
+ * lifecycle verb, and candidate {sessionId,path} — never a token or prompt. Each
+ * error reason gets tailored, actionable copy; an "in progress" pending response
+ * is surfaced distinctly.
  */
-export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
+export function formatLifecycleOutcome(r: SessionLifecycleResponse, verb?: LifecycleCommandVerb): string {
 	switch (r.type) {
 		case "session_create_response":
 			return `\u{1f680} Launching session ${r.sessionId} in tmux. It will appear once ready \u2014 check /session_recent.`;
@@ -282,9 +327,17 @@ export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
 		case "unsupported_platform":
 			return "Remote session lifecycle is unavailable on this psmux host because GJC cannot prove immutable session identity. No lifecycle action was performed. Use a local GJC terminal with a supported tmux provider.";
 		case "terminal_uncertain":
-			return /in progress/i.test(r.message)
-				? "\u23f3 That request is already in progress \u2014 hold on."
-				: "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying so you don't double-spawn.";
+			if (/in progress/i.test(r.message)) return "\u23f3 That request is already in progress \u2014 hold on.";
+			switch (verb) {
+				case "session_create":
+					return "\u26a0\ufe0f Create outcome uncertain. The session may already be starting \u2014 check /session_recent before retrying to avoid starting it twice.";
+				case "session_close":
+					return "\u26a0\ufe0f Close outcome uncertain. The session may already be closed \u2014 check /session_recent before retrying.";
+				case "session_resume":
+					return "\u26a0\ufe0f Resume outcome uncertain. The session may already be reattached or restarting \u2014 check /session_recent before retrying.";
+				default:
+					return "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying.";
+			}
 		default:
 			return `\u26a0\ufe0f ${r.reason}: ${r.message}`;
 	}

package/src/sdk/bus/lifecycle-control-runtime.ts

@@ -1178,16 +1178,25 @@ export function outcomeToResponse(frame: SessionLifecycleRequest, outcome: Lifec
 	if (frame.type === "session_close") {
 		if (typeof e.sessionId !== "string" || typeof e.processGone !== "boolean")
 			throw new Error("invalid close success ledger entry");
+		if (!e.processGone) {
+			return {
+				type: "session_lifecycle_error",
+				requestId: frame.requestId,
+				status: "error",
+				reason: "terminal_uncertain",
+				message: "close did not confirm process termination",
+			};
+		}
 		return {
 			type: "session_close_response",
 			requestId: frame.requestId,
 			status: "ok",
 			sessionId: e.sessionId,
-			processGone: e.processGone,
+			processGone: true,
 			historyPreserved: true,
 			// The killed session's per-session endpoint record is reaped by the
 			// daemon's dead-PID scan (scanRoots), so it is effectively stale.
-			endpointStale: e.processGone,
+			endpointStale: true,
 		};
 	}
 	if (

package/src/sdk/bus/lifecycle-orchestrator.ts

@@ -309,6 +309,21 @@ export async function handleLifecycleRequest(
 
 	// 4. Durable idempotency.
 	const doc = await deps.store.read();
+	const existing = doc.entries[key];
+	if (
+		frame.type === "session_close" &&
+		existing?.verb === "session_close" &&
+		existing.requestHash === hash &&
+		existing.state === "success" &&
+		typeof existing.sessionId === "string" &&
+		existing.processGone === false
+	) {
+		existing.state = "terminal_uncertain";
+		existing.reason = "terminal_uncertain";
+		existing.updatedAt = deps.now();
+		delete existing.processGone;
+		await deps.store.write(doc);
+	}
 	const dup = classifyDuplicate(doc.entries[key], hash);
 	switch (dup.kind) {
 		case "conflict":
@@ -394,12 +409,28 @@ export async function handleLifecycleRequest(
 
 		if (frame.type === "session_close") {
 			const closed = await deps.closeSession(frame.target);
+			if (!closed.processGone) {
+				Object.assign(entry, {
+					state: "terminal_uncertain",
+					updatedAt: deps.now(),
+					reason: "terminal_uncertain",
+					sessionId: frame.target.sessionId,
+					tmuxSession: frame.target.tmuxSession,
+				});
+				await deps.store.write(doc);
+				await deps.audit({ ...baseAudit, event: "terminal_uncertain", reason: "terminal_uncertain" });
+				return {
+					status: "error",
+					reason: "terminal_uncertain",
+					message: "session_close could not confirm process disappearance; manual check",
+				};
+			}
 			Object.assign(entry, {
 				state: "success",
 				updatedAt: deps.now(),
 				sessionId: frame.target.sessionId,
 				tmuxSession: frame.target.tmuxSession,
-				processGone: closed.processGone,
+				processGone: true,
 			});
 			await deps.store.write(doc);
 			await deps.audit({ ...baseAudit, event: "success" });

package/src/sdk/bus/notification-orchestration.ts

@@ -1,5 +1,6 @@
 import type { CasRestoreResult } from "../../config/atomic-yaml-patch";
 import type { RawSettings, SettingsAtomicPatch, SettingsAtomicReceipt } from "../../config/settings";
+import { isProcessIncarnation, processIncarnation } from "../broker/process-incarnation";
 import {
 	getNotificationConfig,
 	hasNonBlankValue,
@@ -53,6 +54,7 @@ export interface ProposedTelegramIdentityPreflightInput {
 	deps?: {
 		fs?: TelegramDaemonFs;
 		pidAlive?: (pid: number) => boolean;
+		pidIncarnation?: (pid: number) => string | undefined;
 	};
 }
 
@@ -109,6 +111,16 @@ export async function proposedTelegramIdentity(
 
 		const pidAlive = input.deps?.pidAlive ?? defaultPidAlive;
 		if (!pidAlive(metadata.pid)) return { status: "absent" };
+		const pidIncarnation = input.deps?.pidIncarnation ?? processIncarnation;
+		const persistedIncarnation = state.incarnation;
+		const currentIncarnation = pidIncarnation(metadata.pid);
+		if (
+			!isProcessIncarnation(persistedIncarnation) ||
+			!isProcessIncarnation(currentIncarnation) ||
+			persistedIncarnation !== currentIncarnation
+		) {
+			return { status: "absent" };
+		}
 
 		if (state.tokenFingerprint === tokenFingerprint(input.botToken) && state.chatId === input.chatId) {
 			return {

package/src/sdk/bus/notification-service.ts

@@ -251,19 +251,29 @@ export function formatNotificationStatusReport(report: NotificationStatusReport)
 
 // --- endpoint / daemon file readers -------------------------------------
 
-interface EndpointView {
+export interface NotificationEndpointView {
 	sessionId: string;
 	pid: number | undefined;
 	stale: boolean;
 }
 
-type EndpointFileRead =
-	| { kind: "endpoint"; view: EndpointView; identity: NotificationEndpointFileIdentity }
+export type NotificationEndpointLiveness = "live" | "dead" | "unknown";
+
+/**
+ * Classification used by recovery and startup takeover. A file is an endpoint
+ * only when it has endpoint authority fields; lifecycle/audit records are never
+ * candidates for endpoint cleanup.
+ */
+export type NotificationEndpointClassification =
+	| {
+			kind: "endpoint";
+			view: NotificationEndpointView;
+			liveness: NotificationEndpointLiveness;
+			identity: NotificationEndpointFileIdentity;
+	  }
 	| { kind: "non-endpoint" }
 	| { kind: "unreadable" };
 
-type EndpointLiveness = "live" | "dead" | "unknown";
-
 /**
  * Classify an endpoint using owner-proof semantics. An endpoint is only `dead`
  * with positive proof: an explicit `stale` tombstone, or a recorded pid that is
@@ -271,7 +281,10 @@ type EndpointLiveness = "live" | "dead" | "unknown";
  * must never be treated as dead — removing it could delete a live session's
  * discovery file that simply omitted a pid.
  */
-function endpointLiveness(view: EndpointView, pidAlive: (pid: number) => boolean): EndpointLiveness {
+export function notificationEndpointLiveness(
+	view: NotificationEndpointView,
+	pidAlive: (pid: number) => boolean,
+): NotificationEndpointLiveness {
 	if (view.stale) return "dead";
 	if (view.pid === undefined) return "unknown";
 	return pidAlive(view.pid) ? "live" : "dead";
@@ -314,11 +327,19 @@ function isCanonicalLifecycleArtifactName(name: string): boolean {
 	);
 }
 
-function unreadableEndpointResult(file: string): EndpointFileRead {
+function unreadableEndpointResult(file: string): NotificationEndpointClassification {
 	return isCanonicalLifecycleArtifactName(path.basename(file)) ? { kind: "non-endpoint" } : { kind: "unreadable" };
 }
 
-async function readEndpointView(fs: NotificationServiceFs, file: string): Promise<EndpointFileRead> {
+/**
+ * Read and classify one endpoint candidate. The returned identity belongs to
+ * exactly the bytes inspected and is required for any later deletion.
+ */
+export async function classifyNotificationEndpoint(
+	fs: Pick<NotificationServiceFs, "readEndpointFile">,
+	file: string,
+	pidAlive: (pid: number) => boolean,
+): Promise<NotificationEndpointClassification> {
 	let endpoint: NotificationEndpointFile;
 	let raw: string;
 	try {
@@ -334,16 +355,19 @@ async function readEndpointView(fs: NotificationServiceFs, file: string): Promis
 		return unreadableEndpointResult(file);
 	}
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "non-endpoint" };
+	if (path.basename(file) === "broker.json") return { kind: "non-endpoint" };
 	const rec = parsed as Record<string, unknown>;
 	if (isLifecycleArtifact(rec) || typeof rec.url !== "string" || typeof rec.token !== "string")
 		return { kind: "non-endpoint" };
+	const view: NotificationEndpointView = {
+		sessionId: typeof rec.sessionId === "string" ? rec.sessionId : path.basename(file, ".json"),
+		pid: safePositiveInteger(rec.pid),
+		stale: rec.stale === true,
+	};
 	return {
 		kind: "endpoint",
-		view: {
-			sessionId: typeof rec.sessionId === "string" ? rec.sessionId : path.basename(file, ".json"),
-			pid: safePositiveInteger(rec.pid),
-			stale: rec.stale === true,
-		},
+		view,
+		liveness: notificationEndpointLiveness(view, pidAlive),
 		identity: endpoint.identity,
 	};
 }
@@ -604,14 +628,13 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 	let unknownEndpoints = 0;
 	let unreadable = 0;
 	for (const name of files) {
-		const record = await readEndpointView(fs, path.join(dir, name));
+		const record = await classifyNotificationEndpoint(fs, path.join(dir, name), pidAlive);
 		if (record.kind === "non-endpoint") continue;
 		if (record.kind === "unreadable") {
 			unreadable += 1;
 			continue;
 		}
-		const view = record.view;
-		switch (endpointLiveness(view, pidAlive)) {
+		switch (record.liveness) {
 			case "live":
 				live += 1;
 				break;
@@ -877,7 +900,16 @@ async function detachTransitionMarker(
 ): Promise<boolean> {
 	if (!snapshot.identity || !fs.exactUnlink) return false;
 	try {
-		return (await fs.exactUnlink(path, snapshot.identity)).ok;
+		const removed = await fs.exactUnlink(path, snapshot.identity);
+		if (removed.ok) return true;
+		// Accept only typed retained authority: a concrete detached quarantine plus
+		// a proven-absent canonical marker pathname. Anything else stays fail-closed.
+		return (
+			removed.code === "cleanup_pending" &&
+			typeof removed.detachedPath === "string" &&
+			removed.detachedPath.length > 0 &&
+			(await fs.readFile(path, "utf8").catch(() => undefined)) === undefined
+		);
 	} catch {
 		return false;
 	}
@@ -1040,7 +1072,7 @@ export async function recoverNotifications(opts: RecoveryOptions): Promise<Notif
 	let unreadable = 0;
 	for (const name of files) {
 		const file = path.join(dir, name);
-		const record = await readEndpointView(fs, file);
+		const record = await classifyNotificationEndpoint(fs, file, pidAlive);
 		if (record.kind === "non-endpoint") continue;
 		if (record.kind === "unreadable") {
 			// Leave unparseable files untouched: they may be mid-write by a live server.
@@ -1048,7 +1080,7 @@ export async function recoverNotifications(opts: RecoveryOptions): Promise<Notif
 			continue;
 		}
 		const view = record.view;
-		if (endpointLiveness(view, pidAlive) !== "dead") {
+		if (record.liveness !== "dead") {
 			// Keep live AND unknown (PID-less) endpoints: only positive proof of
 			// death (a stale tombstone or a dead pid) authorizes removal.
 			kept += 1;
@@ -1057,11 +1089,27 @@ export async function recoverNotifications(opts: RecoveryOptions): Promise<Notif
 		try {
 			const result = await fs.exactUnlink(file, record.identity);
 			if (!result.ok) {
-				recoveryFailures += 1;
 				if (result.detachedPath) detached.push(result.detachedPath);
 				if (result.retainedSuccessorPath) retainedSuccessors.push(result.retainedSuccessorPath);
 				if (result.retainedPlaceholderPath) retainedPlaceholders.push(result.retainedPlaceholderPath);
 				if (result.retainedUnknownPath) retainedUnknown.push(result.retainedUnknownPath);
+				// Typed retained authority with a concrete quarantine and a proven-absent
+				// canonical endpoint counts as removed; the detached path above is the
+				// durable evidence. Anything else is a genuine recovery failure.
+				const retainedRemoved =
+					result.code === "cleanup_pending" &&
+					typeof result.detachedPath === "string" &&
+					result.detachedPath.length > 0 &&
+					(await fs.readFile(file, "utf8").catch(() => undefined)) === undefined;
+				if (retainedRemoved) {
+					removed.push({
+						sessionId: view.sessionId,
+						pid: view.pid,
+						reason: view.stale ? "stale-flag" : "dead-pid",
+					});
+					continue;
+				}
+				recoveryFailures += 1;
 				if (
 					!result.detachedPath &&
 					!result.retainedSuccessorPath &&

package/src/sdk/bus/prompt-reconciliation.ts

@@ -0,0 +1,239 @@
+/**
+ * Bounded authoritative reconciliation state for Q26 `turn.prompt_status`.
+ *
+ * Separate from the lifecycle delivery buffers (promptSubmissions /
+ * promptTerminalTombstones), which exist to deliver frames and intentionally
+ * forget outcomes. This record preserves accepted/in_flight/terminal_ok/failed
+ * plus bounded sanitized failure metadata so a caller can reconcile a prior
+ * `turn.prompt` after disconnect/reconnect.
+ *
+ * Semantics (public contract, mirrored in sdk/prompt-status.ts):
+ * - Active records are NEVER converted to terminal by age or capacity.
+ * - Terminal records are retained for TERMINAL_TTL_MS and bounded to
+ *   TERMINAL_CAPACITY, evicted oldest-terminal-first by terminalAt; only then
+ *   does a lookup honestly report `unknown`.
+ * - The durability floor is the live session process: restart means `unknown`.
+ * - The clientRef index is session-runtime scoped; a ref conflicts only while
+ *   retained and must never be reused as a retry mechanism.
+ * - Terminal transitions settle once: the first terminal outcome wins.
+ */
+
+export const PROMPT_RECONCILIATION_ACTIVE_CAPACITY = 128;
+export const PROMPT_RECONCILIATION_TERMINAL_CAPACITY = 256;
+export const PROMPT_RECONCILIATION_TERMINAL_TTL_MS = 15 * 60_000;
+export const PROMPT_FAILURE_CODE_MAX = 64;
+
+export type PromptReconciliationStatus = "accepted" | "in_flight" | "terminal_ok" | "failed";
+
+export interface PromptCorrelation {
+	commandId: string;
+	turnId: string;
+}
+
+export interface PromptReconciliationRecord extends PromptCorrelation {
+	clientRef?: string;
+	status: PromptReconciliationStatus;
+	error?: { code: string; message: string };
+	acceptedAt: number;
+	startedAt?: number;
+	terminalAt?: number;
+}
+
+export type TurnPromptReconciliation =
+	| {
+			status: "accepted";
+			commandId: string;
+			turnId: string;
+			clientRef?: string;
+			acceptedAt: number;
+	  }
+	| {
+			status: "in_flight";
+			commandId: string;
+			turnId: string;
+			clientRef?: string;
+			acceptedAt: number;
+			startedAt: number;
+	  }
+	| {
+			status: "terminal_ok";
+			commandId: string;
+			turnId: string;
+			clientRef?: string;
+			acceptedAt: number;
+			startedAt?: number;
+			terminalAt: number;
+	  }
+	| {
+			status: "failed";
+			commandId: string;
+			turnId: string;
+			clientRef?: string;
+			acceptedAt: number;
+			startedAt?: number;
+			terminalAt: number;
+			error: { code: string; message: string };
+	  }
+	| { status: "unknown" };
+
+export interface PromptReconciliation {
+	/** Fail-closed admission BEFORE any execution; holds an identity-bound reservation. */
+	admit(clientRef?: string): void;
+	/** Discard one admission reservation without creating a record (rejection/cancellation). */
+	releaseAdmission(clientRef?: string): void;
+	/** Transition a reservation into the accepted record at preflight acceptance. */
+	noteAccepted(correlation: PromptCorrelation, clientRef?: string): void;
+	/** Lifecycle transition; terminal outcomes settle exactly once. */
+	noteTransition(
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	): void;
+	lookup(selector: { commandId?: string; turnId?: string; clientRef?: string }): TurnPromptReconciliation;
+	cleanup(): void;
+	activeCount(): number;
+}
+
+/** Safe-token code capped at 64; arbitrary failure text is never retained. */
+export function sanitizePromptFailure(error: unknown): { code: string; message: string } {
+	const candidate = error as { code?: unknown } | undefined;
+	const rawCode = typeof candidate?.code === "string" ? candidate.code : "";
+	const code = rawCode.length <= PROMPT_FAILURE_CODE_MAX && /^[A-Za-z0-9._-]+$/.test(rawCode) ? rawCode : "internal";
+	return { code, message: "Prompt submission failed." };
+}
+
+export function createPromptReconciliation(options: { now?: () => number } = {}): PromptReconciliation {
+	const now = options.now ?? Date.now;
+	const records = new Map<string, PromptReconciliationRecord>();
+	const clientRefIndex = new Map<string, string>();
+	const reservedClientRefs = new Set<string>();
+	// One identity-bound entry per admission. Transitions consume exactly one
+	// matching entry and stale/duplicate transitions are no-ops, so reservation
+	// accounting is exactly-once even under repeated calls.
+	const reservations: Array<string | undefined> = [];
+	const keyOf = (correlation: PromptCorrelation) => `${correlation.commandId}:${correlation.turnId}`;
+
+	const remove = (key: string) => {
+		const record = records.get(key);
+		if (!record) return;
+		records.delete(key);
+		if (record.clientRef !== undefined && clientRefIndex.get(record.clientRef) === key)
+			clientRefIndex.delete(record.clientRef);
+	};
+
+	const cleanup = () => {
+		const at = now();
+		for (const [key, record] of records)
+			if (record.terminalAt !== undefined && record.terminalAt + PROMPT_RECONCILIATION_TERMINAL_TTL_MS <= at)
+				remove(key);
+		const terminalEntries = [...records.entries()].filter(([, record]) => record.terminalAt !== undefined);
+		if (terminalEntries.length <= PROMPT_RECONCILIATION_TERMINAL_CAPACITY) return;
+		// Evict oldest-terminal-first by terminalAt, not acceptance/insertion
+		// order; the stable sort keeps acceptance order for exact ties.
+		terminalEntries.sort((a, b) => (a[1].terminalAt as number) - (b[1].terminalAt as number));
+		for (const [key] of terminalEntries.slice(0, terminalEntries.length - PROMPT_RECONCILIATION_TERMINAL_CAPACITY))
+			remove(key);
+	};
+
+	const activeCount = () => {
+		let count = 0;
+		for (const record of records.values()) if (record.terminalAt === undefined) count++;
+		return count;
+	};
+
+	/** Consume one reservation matching clientRef; no-op when none is outstanding. */
+	const consumeReservation = (clientRef?: string) => {
+		const index = reservations.indexOf(clientRef);
+		if (index === -1) return;
+		reservations.splice(index, 1);
+		if (clientRef !== undefined && !reservations.includes(clientRef)) reservedClientRefs.delete(clientRef);
+	};
+
+	const admit = (clientRef?: string) => {
+		cleanup();
+		if (clientRef !== undefined && (clientRefIndex.has(clientRef) || reservedClientRefs.has(clientRef)))
+			throw Object.assign(
+				new Error("A prompt with this clientRef is already retained; never reuse a clientRef for retry."),
+				{ code: "client_ref_conflict" },
+			);
+		if (activeCount() + reservations.length >= PROMPT_RECONCILIATION_ACTIVE_CAPACITY)
+			throw Object.assign(new Error("Too many active prompt submissions; reconcile or await terminal state."), {
+				code: "reconciliation_capacity",
+			});
+		reservations.push(clientRef);
+		if (clientRef !== undefined) reservedClientRefs.add(clientRef);
+	};
+
+	const releaseAdmission = (clientRef?: string) => {
+		consumeReservation(clientRef);
+	};
+
+	const noteAccepted = (correlation: PromptCorrelation, clientRef?: string) => {
+		cleanup();
+		consumeReservation(clientRef);
+		const at = now();
+		const key = keyOf(correlation);
+		records.set(key, {
+			commandId: correlation.commandId,
+			turnId: correlation.turnId,
+			...(clientRef !== undefined ? { clientRef } : {}),
+			status: "accepted",
+			acceptedAt: at,
+		});
+		if (clientRef !== undefined) clientRefIndex.set(clientRef, key);
+	};
+
+	const noteTransition = (
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	) => {
+		if (!correlation) return;
+		const record = records.get(keyOf(correlation));
+		if (!record || record.terminalAt !== undefined) return;
+		if (frame.type === "agent_start") {
+			if (record.status === "accepted") {
+				record.status = "in_flight";
+				record.startedAt = now();
+			}
+			return;
+		}
+		record.terminalAt = now();
+		if (frame.type === "agent_failed") {
+			record.status = "failed";
+			record.error = sanitizePromptFailure(frame.error);
+		} else {
+			record.status = "terminal_ok";
+		}
+		// Enforce terminal retention immediately at settlement, not lazily.
+		cleanup();
+	};
+
+	const lookup = (selector: { commandId?: string; turnId?: string; clientRef?: string }): TurnPromptReconciliation => {
+		cleanup();
+		const key =
+			selector.clientRef !== undefined
+				? clientRefIndex.get(selector.clientRef)
+				: selector.commandId !== undefined && selector.turnId !== undefined
+					? keyOf({ commandId: selector.commandId, turnId: selector.turnId })
+					: undefined;
+		const record = key === undefined ? undefined : records.get(key);
+		if (!record) return { status: "unknown" };
+		const identity = {
+			commandId: record.commandId,
+			turnId: record.turnId,
+			...(record.clientRef !== undefined ? { clientRef: record.clientRef } : {}),
+			acceptedAt: record.acceptedAt,
+		};
+		if (record.status === "accepted") return { status: "accepted", ...identity };
+		if (record.status === "in_flight")
+			return { status: "in_flight", ...identity, startedAt: record.startedAt as number };
+		const terminal = {
+			...identity,
+			...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+			terminalAt: record.terminalAt as number,
+		};
+		if (record.status === "terminal_ok") return { status: "terminal_ok", ...terminal };
+		return { status: "failed", ...terminal, error: record.error ?? sanitizePromptFailure(undefined) };
+	};
+
+	return { admit, releaseAdmission, noteAccepted, noteTransition, lookup, cleanup, activeCount };
+}