@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/src/sdk/bus/operator-runtime.ts

@@ -74,7 +74,7 @@ export class NotificationOperatorRuntime {
 	#stopRequested = false;
 	#activeAbort: AbortController | undefined;
 	#intervals = new Map<string, OperatorIntervalHandle>();
-	#exclusive = new Set<string>();
+	#exclusive = new Map<string, Promise<void>>();
 
 	#deps: NotificationOperatorTimerDeps;
 
@@ -130,7 +130,7 @@ export class NotificationOperatorRuntime {
 
 	stopInterval(name: string): void {
 		const timer = this.#intervals.get(name);
-		if (!timer) return;
+		if (timer === undefined) return;
 		const clearIntervalImpl = this.#deps.clearIntervalImpl ?? clearInterval;
 		clearIntervalImpl(timer);
 		this.#intervals.delete(name);
@@ -142,14 +142,40 @@ export class NotificationOperatorRuntime {
 
 	async runExclusive(name: string, fn: () => Promise<void>): Promise<void> {
 		if (this.#exclusive.has(name)) return;
-		this.#exclusive.add(name);
+		const completion = Promise.withResolvers<void>();
+		this.#exclusive.set(name, completion.promise);
 		try {
-			await fn();
+			try {
+				void fn().then(completion.resolve, completion.reject);
+			} catch (error) {
+				completion.reject(error);
+			}
+			await completion.promise;
 		} finally {
-			this.#exclusive.delete(name);
+			if (this.#exclusive.get(name) === completion.promise) this.#exclusive.delete(name);
 		}
 	}
 
+	async joinExclusive(name: string, timeoutMs: number): Promise<boolean> {
+		const completion = this.#exclusive.get(name);
+		if (!completion) return true;
+		const setTimeoutImpl = this.#deps.setTimeoutImpl ?? setTimeout;
+		const clearTimeoutImpl = this.#deps.clearTimeoutImpl ?? clearTimeout;
+		const { promise, resolve } = Promise.withResolvers<boolean>();
+		const timer = setTimeoutImpl(() => resolve(false), timeoutMs);
+		void completion.then(
+			() => {
+				clearTimeoutImpl(timer);
+				resolve(true);
+			},
+			() => {
+				clearTimeoutImpl(timer);
+				resolve(true);
+			},
+		);
+		return await promise;
+	}
+
 	sleep(ms: number, signal?: AbortSignal): Promise<void> {
 		return new Promise<void>(resolve => {
 			if (signal?.aborted) return resolve();

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

@@ -0,0 +1,240 @@
+/**
+ * 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`.
+ * - Process-local durability floor is the live session process: restart means `unknown`.
+ *   Session-scoped durable retention (kind-aware store) is provided by reconciliation-store.ts (#3032).
+ * - 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 };
+}

package/src/sdk/bus/rate-limit-pool.ts

@@ -116,6 +116,14 @@ export class RateLimitPool<T = unknown> {
 		return total;
 	}
 
+	/** Whether any queued item currently matches the predicate. */
+	someQueued(predicate: (item: RateLimitItem<T>) => boolean): boolean {
+		for (const queue of this.lanes.values()) {
+			if (queue.some(entry => predicate(entry.item))) return true;
+		}
+		return false;
+	}
+
 	/** Current available token count (after refill at `now`). */
 	availableTokens(nowMs: number = this.now()): number {
 		this.refill(nowMs);

package/src/sdk/bus/recent-activity.ts

@@ -11,7 +11,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { verifyOwnerOnlyPathSecurity } from "@sayknow-cli/natives";
 import { getAgentDir, getSessionsDir } from "@sayknow-cli/utils";
-import { FileSessionStorage } from "../../session/session-storage";
+import { FileSessionStorage, type SessionStorageSnapshot } from "../../session/session-storage";
 import {
 	type LogicalSessionCandidate,
 	listManagedSessionCandidates,
@@ -58,25 +58,52 @@ export interface RecentActivityDeps {
 	readInitialLines?: (file: string, maxLines: number) => string[];
 }
 
+class ManagedCandidateChangedError extends Error {}
+class ManagedCandidateUnavailableError extends Error {}
+
+const CHANGED_CANDIDATE_WARNING = "Ignored managed session candidate that changed during inspection.";
+
+function isAppendExtension(bytes: Uint8Array, candidate: LogicalSessionCandidate): boolean {
+	return (
+		bytes.byteLength >= candidate.identity.size &&
+		createHash("sha256").update(bytes.subarray(0, candidate.identity.size)).digest("hex") ===
+			candidate.identity.sha256
+	);
+}
+
 function readCandidateInitialLines(
 	candidate: LogicalSessionCandidate,
 	readInitialLines: ((file: string, maxLines: number) => string[]) | undefined,
+	appendBase?: LogicalSessionCandidate,
 ): string[] {
 	if (readInitialLines) return readInitialLines(candidate.path, 8);
 	if (candidate.provenance !== "legacy") {
 		const security = verifyOwnerOnlyPathSecurity(candidate.path, "file");
-		if (!security.ok) throw new Error(`Managed session metadata path is unsafe: ${security.code}`);
+		if (!security.ok) throw new ManagedCandidateUnavailableError("Managed session metadata path is unsafe.");
 	}
-	const snapshot = new FileSessionStorage().readSnapshotSync(candidate.path);
+	let snapshot: SessionStorageSnapshot;
+	try {
+		snapshot = new FileSessionStorage().readSnapshotSync(candidate.path);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR")
+			throw new ManagedCandidateUnavailableError("Managed session metadata is unavailable.");
+		throw error;
+	}
+	const sameFile = snapshot.stat.dev === candidate.identity.dev && snapshot.stat.ino === candidate.identity.ino;
 	const digest = createHash("sha256").update(snapshot.bytes).digest("hex");
-	if (
-		snapshot.stat.dev !== candidate.identity.dev ||
-		snapshot.stat.ino !== candidate.identity.ino ||
-		snapshot.stat.size !== candidate.identity.size ||
-		snapshot.stat.mtimeNs !== candidate.identity.mtimeNs ||
-		digest !== candidate.identity.sha256
-	)
-		throw new Error("Managed session changed after ownership was verified.");
+	const exactIdentity =
+		sameFile &&
+		snapshot.stat.size === candidate.identity.size &&
+		snapshot.stat.mtimeNs === candidate.identity.mtimeNs &&
+		digest === candidate.identity.sha256;
+	if (appendBase && (!sameFile || !isAppendExtension(snapshot.bytes, appendBase)))
+		throw new ManagedCandidateUnavailableError("Managed session no longer extends the verified transcript.");
+	if (!exactIdentity) {
+		if (sameFile && isAppendExtension(snapshot.bytes, candidate))
+			throw new ManagedCandidateChangedError("Managed session was appended after ownership was verified.");
+		throw new ManagedCandidateUnavailableError("Managed session changed without an append-only extension.");
+	}
 	return Buffer.from(snapshot.bytes).toString("utf8").split("\n").slice(0, 8);
 }
 
@@ -227,13 +254,13 @@ export async function listRecentSessions(deps: RecentActivityDeps): Promise<List
 	const resolved = await resolveRecentScopes(deps);
 	if (resolved.kind === "error") return resolved;
 	const warnings = [...resolved.warnings];
-	const candidates: LogicalSessionCandidate[] = [];
+	const candidates: Array<{ scope: ManagedSessionScope; candidate: LogicalSessionCandidate }> = [];
 	for (const scope of resolved.scopes) {
 		const listed = await listManagedSessionCandidates({ scope });
 		if (listed.kind !== "complete") {
 			return { kind: "error", code: "managed_scan_failed", message: listed.message };
 		}
-		candidates.push(...listed.owned);
+		candidates.push(...listed.owned.map(candidate => ({ scope, candidate })));
 		warnings.push(
 			...listed.invalid
 				.filter(
@@ -245,28 +272,65 @@ export async function listRecentSessions(deps: RecentActivityDeps): Promise<List
 	}
 
 	const entries: RecentSessionEntry[] = [];
-	for (const candidate of candidates) {
-		let initialLines: string[];
+	for (const { scope, candidate } of candidates) {
+		let selected = candidate;
+		let initialLines: string[] | undefined;
 		try {
-			initialLines = readCandidateInitialLines(candidate, readInitialLines);
+			initialLines = readCandidateInitialLines(selected, readInitialLines);
 		} catch (error) {
-			return {
-				kind: "error",
-				code: "managed_scan_failed",
-				message: `Could not read managed session metadata: ${error instanceof Error ? error.message : String(error)}`,
-			};
+			if (error instanceof ManagedCandidateChangedError) {
+				const refreshed = await listManagedSessionCandidates({ scope });
+				if (refreshed.kind !== "complete")
+					return { kind: "error", code: "managed_scan_failed", message: refreshed.message };
+				const sameFile = refreshed.owned.find(
+					current =>
+						path.resolve(current.path) === path.resolve(candidate.path) &&
+						current.identity.dev === candidate.identity.dev &&
+						current.identity.ino === candidate.identity.ino,
+				);
+				if (sameFile) {
+					try {
+						initialLines = readCandidateInitialLines(sameFile, readInitialLines, candidate);
+						selected = sameFile;
+					} catch (retryError) {
+						if (
+							!(retryError instanceof ManagedCandidateChangedError) &&
+							!(retryError instanceof ManagedCandidateUnavailableError)
+						)
+							return {
+								kind: "error",
+								code: "managed_scan_failed",
+								message: `Could not read managed session metadata: ${
+									retryError instanceof Error ? retryError.message : String(retryError)
+								}`,
+							};
+					}
+				}
+			} else if (!(error instanceof ManagedCandidateUnavailableError)) {
+				return {
+					kind: "error",
+					code: "managed_scan_failed",
+					message: `Could not read managed session metadata: ${
+						error instanceof Error ? error.message : String(error)
+					}`,
+				};
+			}
+			if (!initialLines) {
+				warnings.push(CHANGED_CANDIDATE_WARNING);
+				continue;
+			}
 		}
 		const meta = headerMeta(initialLines[0]);
 		const internal = isInternalSession(initialLines);
 		if (internal && !includeInternal) continue;
 		entries.push({
-			sessionId: candidate.sessionId,
-			path: candidate.cwd,
+			sessionId: selected.sessionId,
+			path: selected.cwd,
 			branch: meta.branch,
 			title: meta.title,
-			sessionStateFile: candidate.path,
-			mtimeMs: candidate.identity.mtimeMs,
-			currentTerminal: breadcrumbs.has(path.resolve(candidate.path)) || undefined,
+			sessionStateFile: selected.path,
+			mtimeMs: selected.identity.mtimeMs,
+			currentTerminal: breadcrumbs.has(path.resolve(selected.path)) || undefined,
 			internal: internal || undefined,
 		});
 	}