@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/sdk/broker/lifecycle.ts

@@ -741,6 +741,10 @@ async function reconcileReadyScope(broker: Broker, id: string, scope: string | u
 		locator: { ...record.locator, repo: scope },
 		endpointGeneration: record.endpointGeneration,
 		pid: record.pid,
+		// Reconciliation only re-scopes the locator, so every identity fact the host
+		// published about its own process has to survive it: dropping the incarnation
+		// here would silently disarm the teardown fence for every lifecycle session.
+		...(record.processIncarnation === undefined ? {} : { processIncarnation: record.processIncarnation }),
 		endpointMtimeMs: record.endpointMtimeMs,
 	});
 }
@@ -1947,15 +1951,35 @@ export async function readSessionLifecycleFailureForTest(
 		: undefined;
 }
 
-async function hasDurableProcessIdentity(
-	root: string,
-	id: string,
-	pid: number,
-	expected?: EffectMarker,
-): Promise<boolean> {
-	const marker = await readEffectMarker(lifecycleMarkerPath(root, id));
-	if (!marker || marker.pid !== pid || (expected && !sameEffectMarker(marker, expected))) return false;
-	return marker.incarnation === processIncarnation(pid);
+/** Everything a signal target must prove about itself before it can be signalled. */
+type SignalTarget = {
+	locator: { stateRoot: string };
+	pid: number;
+	lifecycleRequestId?: string;
+	processIncarnation?: string;
+};
+
+/**
+ * The spawn-time marker is the strongest evidence — the broker itself wrote it for
+ * exactly this pid — but it lives in the session's own workspace state root. A
+ * workspace deleted while its host keeps running takes that evidence with it, and
+ * the host then survives every later `session.close` as an orphan still serving the
+ * source it started with. The registration its host published into the broker-owned
+ * index carries the same pid-to-incarnation binding, outlives the workspace, and is
+ * therefore consulted when the marker is absent. A marker naming a different process
+ * is contradiction rather than absence and still refuses the signal, and either
+ * source is only accepted while the pid's current OS incarnation still matches it.
+ */
+async function hasDurableProcessIdentity(target: SignalTarget, id: string, expected?: EffectMarker): Promise<boolean> {
+	const marker = await readEffectMarker(lifecycleMarkerPath(target.locator.stateRoot, id));
+	if (marker)
+		return (
+			marker.pid === target.pid &&
+			(!expected || sameEffectMarker(marker, expected)) &&
+			marker.incarnation === processIncarnation(target.pid)
+		);
+	if (expected && (expected.pid !== target.pid || target.lifecycleRequestId !== expected.effectMarker)) return false;
+	return target.processIncarnation !== undefined && target.processIncarnation === processIncarnation(target.pid);
 }
 
 async function hasOwnedReadinessEvidence(
@@ -2229,14 +2253,14 @@ async function terminateSpawnedChild(
 }
 
 async function signalVerifiedSession(
-	record: { locator: { stateRoot: string }; pid: number },
+	record: SignalTarget,
 	id: string,
 	signal: NodeJS.Signals,
 	expected?: EffectMarker,
 ): Promise<boolean> {
-	if (!(await hasDurableProcessIdentity(record.locator.stateRoot, id, record.pid, expected))) return false;
+	if (!(await hasDurableProcessIdentity(record, id, expected))) return false;
 	try {
-		if (!(await hasDurableProcessIdentity(record.locator.stateRoot, id, record.pid, expected))) return false;
+		if (!(await hasDurableProcessIdentity(record, id, expected))) return false;
 		process.kill(record.pid, signal);
 		return true;
 	} catch {
@@ -2276,6 +2300,24 @@ async function waitForClose(
 			hasObservedProcessExit(record.pid)
 		)
 			return true;
+		// A host that dies before it can withdraw its own registration — killed
+		// mid-teardown, or unable to finish one because its workspace is gone —
+		// leaves the index advertising a session whose process is provably absent.
+		// That is exactly the evidence the dead-registration sweep retires records
+		// on, so retire it here too instead of escalating signals at a pid that no
+		// longer exists and then reporting the teardown as unfinished.
+		if (registration && hasObservedProcessExit(record.pid)) {
+			await broker.index.append({
+				type: "host_unregistered",
+				sessionId: id,
+				locator: registration.locator,
+				endpointGeneration: registration.endpointGeneration,
+				pid: registration.pid,
+				...(registration.endpointMtimeMs === undefined ? {} : { endpointMtimeMs: registration.endpointMtimeMs }),
+				...(registration.lifecycleRequestId ? { lifecycleRequestId: registration.lifecycleRequestId } : {}),
+			});
+			return true;
+		}
 		await timing.sleep(POLL_MS);
 	}
 	return false;
@@ -2996,27 +3038,22 @@ function sameCloseProcessIdentity(expected: CloseRecord, current: CloseRecord &
 	);
 }
 
-function sameCloseGeneration(expected: CloseRecord, current: CloseRecord & { live: boolean }): boolean {
-	return (
-		current.live &&
-		current.endpointGeneration === expected.endpointGeneration &&
-		current.pid === expected.pid &&
-		current.endpointMtimeMs === expected.endpointMtimeMs &&
-		path.resolve(current.locator.repo) === path.resolve(expected.locator.repo) &&
-		path.resolve(current.locator.stateRoot) === path.resolve(expected.locator.stateRoot)
-	);
-}
-
 async function revalidateCloseGeneration(
 	broker: Broker,
 	id: string,
 	expected: CloseRecord,
 	authority: CloseAuthority | undefined,
+	allowUnreachable = false,
 ): Promise<BrokerResponse | undefined> {
 	await broker.index.refresh();
 	const current = broker.index.listSessions().sessions.find(session => session.sessionId === id);
 	return current &&
-		sameCloseGeneration(expected, current) &&
+		(allowUnreachable || current.live) &&
+		current.endpointGeneration === expected.endpointGeneration &&
+		current.pid === expected.pid &&
+		current.endpointMtimeMs === expected.endpointMtimeMs &&
+		path.resolve(current.locator.repo) === path.resolve(expected.locator.repo) &&
+		path.resolve(current.locator.stateRoot) === path.resolve(expected.locator.stateRoot) &&
 		(!authority || sameCloseAuthority(authority, current, id))
 		? undefined
 		: fail("endpoint_stale", "session endpoint is stale");
@@ -3427,9 +3464,13 @@ async function executeLifecycleResponse(
 			}
 		}
 		if (!endpointResult.ok) {
-			if (endpointResult.error.code === "endpoint_stale") return endpointResult;
-			if (endpointResult.error.code !== "resource_gone") return endpointResult;
-			usedSignalFallback = true;
+			if (endpointResult.error.code === "endpoint_stale") {
+				if (requestedAuthority.authority) return endpointResult;
+				usedSignalFallback = true;
+			} else {
+				if (endpointResult.error.code !== "resource_gone") return endpointResult;
+				usedSignalFallback = true;
+			}
 		} else {
 			const endpoint = closeEndpoint(endpointResult.result);
 			if (!endpoint) return fail("close_refused", "Session endpoint is malformed.");
@@ -3470,7 +3511,7 @@ async function executeLifecycleResponse(
 		}
 
 		if (usedSignalFallback) {
-			const stale = await revalidateCloseGeneration(broker, id, record, requestedAuthority.authority);
+			const stale = await revalidateCloseGeneration(broker, id, record, requestedAuthority.authority, true);
 			if (stale) return stale;
 			if (!(await signalVerifiedSession(record, id, "SIGTERM")))
 				return fail(
@@ -4403,7 +4444,7 @@ export async function executeLifecycle(
 									}
 								: {
 										code: "spawn_failed",
-										message: "No ready SDK endpoint remains available.",
+										message: startupFailure.message,
 										endpoint: "unavailable" as const,
 									},
 							...(durableEffects ? { durableEffects } : {}),

package/src/sdk/broker/operation-receipt-ledger.ts

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { canonicalElevationJson } from "../elevation/digest";
+import type { BrokerResponse } from "./broker";
+
+interface PendingReceipt {
+	version: 1;
+	clientRef: string;
+	digest: string;
+	state: "pending";
+	ts: number;
+}
+
+interface CompletedReceipt {
+	version: 1;
+	clientRef: string;
+	digest: string;
+	state: "completed";
+	response: BrokerResponse;
+	ts: number;
+}
+
+type OperationReceipt = PendingReceipt | CompletedReceipt;
+
+export type OperationReserveResult =
+	| { status: "reserved" }
+	| { status: "replay"; response: BrokerResponse }
+	| { status: "in_progress" }
+	| { status: "conflict" };
+
+function isReceipt(value: unknown): value is OperationReceipt {
+	if (!value || typeof value !== "object") return false;
+	const row = value as Partial<OperationReceipt>;
+	return (
+		row.version === 1 &&
+		typeof row.clientRef === "string" &&
+		row.clientRef.length > 0 &&
+		typeof row.digest === "string" &&
+		/^[0-9a-f]{64}$/.test(row.digest) &&
+		(row.state === "pending" || (row.state === "completed" && typeof row.response === "object")) &&
+		typeof row.ts === "number"
+	);
+}
+
+/**
+ * Target-session-scoped idempotency key for a clientRef. Identical refs on
+ * different sessions are independent, so a receipt can never replay or
+ * conflict across sessions.
+ */
+export function operationReceiptKey(sessionId: string, clientRef: string): string {
+	return `${sessionId}\u0000${clientRef}`;
+}
+
+export function operationReceiptDigest(operation: string, input: Record<string, unknown>, sessionId?: string): string {
+	return createHash("sha256")
+		.update(canonicalElevationJson({ operation, input, ...(sessionId === undefined ? {} : { sessionId }) }))
+		.digest("hex");
+}
+
+export class OperationReceiptLedger {
+	readonly #file: string;
+	readonly #latest = new Map<string, OperationReceipt>();
+	#chain: Promise<void> = Promise.resolve();
+
+	constructor(agentDir: string) {
+		this.#file = path.join(agentDir, "sdk", "operation-receipts.jsonl");
+	}
+
+	async open(): Promise<void> {
+		await fs.mkdir(path.dirname(this.#file), { recursive: true, mode: 0o700 });
+		let source = "";
+		try {
+			source = await fs.readFile(this.#file, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+		for (const line of source.split("\n")) {
+			if (!line) continue;
+			try {
+				const row: unknown = JSON.parse(line);
+				if (isReceipt(row)) this.#latest.set(row.clientRef, row);
+			} catch {
+				// A torn final append is fail-closed: any earlier pending row remains authoritative.
+			}
+		}
+	}
+
+	async reserve(clientRef: string, digest: string): Promise<OperationReserveResult> {
+		return this.#serial(async () => {
+			const current = this.#latest.get(clientRef);
+			if (current) {
+				if (current.digest !== digest) return { status: "conflict" };
+				if (current.state === "completed") return { status: "replay", response: current.response };
+				return { status: "in_progress" };
+			}
+			const pending: PendingReceipt = { version: 1, clientRef, digest, state: "pending", ts: Date.now() };
+			await this.#append(pending);
+			this.#latest.set(clientRef, pending);
+			return { status: "reserved" };
+		});
+	}
+
+	async complete(clientRef: string, digest: string, response: BrokerResponse): Promise<void> {
+		await this.#serial(async () => {
+			const current = this.#latest.get(clientRef);
+			if (!current || current.digest !== digest)
+				throw new Error("Operation receipt reservation is missing or mismatched");
+			if (current.state === "completed") return;
+			const completed: CompletedReceipt = {
+				version: 1,
+				clientRef,
+				digest,
+				state: "completed",
+				response,
+				ts: Date.now(),
+			};
+			await this.#append(completed);
+			this.#latest.set(clientRef, completed);
+		});
+	}
+
+	async #append(row: OperationReceipt): Promise<void> {
+		const handle = await fs.open(this.#file, "a", 0o600);
+		try {
+			await handle.writeFile(`${JSON.stringify(row)}\n`);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	}
+
+	async #serial<T>(operation: () => Promise<T>): Promise<T> {
+		const previous = this.#chain;
+		const next = Promise.withResolvers<void>();
+		this.#chain = next.promise;
+		await previous;
+		try {
+			return await operation();
+		} finally {
+			next.resolve();
+		}
+	}
+}