@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/sdk/broker/broker.ts

@@ -1,7 +1,12 @@
 import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import path from "node:path";
-import { resolveResumableSession, SessionManager } from "../../session/session-manager";
+import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
+import {
+	type DirectoryMigrationPolicy,
+	listManagedSessionCandidates,
+	resolveManagedSessionScope,
+} from "../session-directory";
 import {
 	BROKER_HEARTBEAT_TTL_MS,
 	type BrokerDiscovery,
@@ -9,6 +14,7 @@ import {
 	brokerProcessIncarnation,
 	isPidAlive,
 	newBrokerToken,
+	type RedactedBrokerDiscovery,
 	readBrokerDiscovery,
 	redactBrokerDiscovery,
 	writeBrokerDiscovery,
@@ -20,6 +26,7 @@ import {
 	type LifecycleDurableEffectsReceipt,
 	LifecycleLedger,
 	type LifecycleStartupFailureReceipt,
+	type LifecycleState,
 } from "./lifecycle-ledger";
 import { type IndexedSession, SessionIndex } from "./session-index";
 import { BrokerTransport } from "./transport";
@@ -29,7 +36,18 @@ export interface BrokerSettings {
 	packageGeneration?: string;
 	port?: number;
 	heartbeatTtlMs?: number;
+	/** Broker-owned migration policy. Client lifecycle frames cannot select it. */
+	resolveDirectoryMigration?: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 }
+
+type ResolvedBrokerSettings = {
+	agentDir: string;
+	packageGeneration: string;
+	port: number;
+	heartbeatTtlMs: number;
+	resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
+};
+
 export type BrokerErrorCode =
 	| "idempotency_conflict"
 	| "terminal_uncertain"
@@ -46,10 +64,73 @@ export type BrokerErrorCode =
 	| "cleanup_pending"
 	| (string & {});
 
+export type BrokerCleanupIdentity = {
+	dev: string;
+	ino: string;
+	size: number;
+	mtimeNs: string;
+	sha256: string;
+};
+
+/** Exact retry evidence; detached paths are managed-receipt references, never caller authority. */
+export type BrokerLifecycleCleanupFile = {
+	/** Original lifecycle-owned path, retained only for exact identity validation. */
+	path: string;
+	identity: BrokerCleanupIdentity;
+	/** Monotonic append-only cleanup attempt. */
+	attempt?: number;
+	/** Immutable no-replace quarantine destination persisted before native detach. */
+	plannedPath: string;
+	/** Native-returned detached path, persisted after a failed post-detach cleanup. */
+	detachedPath?: string;
+	/** Append-only terminal proof for this exact artifact; completed entries are never retried. */
+	completed?: true;
+};
+
+/** Durable root-tree authority for broker artifact cleanup. */
+export type BrokerArtifactTree = {
+	identity: BrokerCleanupIdentity;
+	snapshot: NativeDirectoryTreeSnapshot;
+	plannedPath: string;
+	detachedPath?: string;
+	completed?: true;
+};
+
 export type BrokerCleanupEvidence = {
-	phase: "artifacts" | "transcript" | "metadata";
-	artifactsIdentity?: { dev: string; ino: string };
-	transcriptIdentity?: { dev: string; ino: string };
+	phase: "artifacts" | "transcript" | "metadata" | "lifecycle";
+	/** Ledger-bound deletion target; never reconstructed from a retry request. */
+	sessionsRoot?: string;
+	transcriptPath?: string;
+	cwd?: string;
+	metadataRoot?: string;
+	sessionId?: string;
+	artifactsIdentity?: BrokerCleanupIdentity;
+	transcriptIdentity?: BrokerCleanupIdentity;
+	/** Identity-bound lifecycle metadata marker retained when exact cleanup is deferred. */
+	metadataIdentity?: BrokerCleanupIdentity;
+	metadataPath?: string;
+	/** Monotonic append-only cleanup attempt. */
+	metadataAttempt?: number;
+	/** No-replace quarantine destination persisted before lifecycle metadata detach. */
+	plannedMetadataPath?: string;
+	/** Native-returned metadata quarantine path retained until identity-bound reconciliation succeeds. */
+	detachedMetadataPath?: string;
+	/** Append-only terminal proof for lifecycle metadata cleanup. */
+	metadataCompleted?: true;
+	detachedArtifactsPath?: string;
+	detachedTranscriptPath?: string;
+	/** Durable proof that artifact cleanup completed before transcript mutation. */
+	artifactsRemoved?: boolean;
+	/** Preauthorized no-replace artifact quarantine path persisted before detach. */
+	plannedArtifactsPath?: string;
+	/** Identity-bound artifact tree authority persisted before broker detach and replayed exactly. */
+	artifactTree?: BrokerArtifactTree;
+	/** Preauthorized no-replace transcript quarantine path persisted before detach. */
+	plannedTranscriptPath?: string;
+	/** Fully identity-bound startup-failure cleanup plan, persisted before any detach. */
+	lifecycleFiles?: BrokerLifecycleCleanupFile[];
+	/** Delete metadata receipts authorize only the canonical marker/ready sibling pair. */
+	lifecycleDeleteMetadata?: true;
 };
 export type BrokerResponse =
 	| { ok: true; result?: unknown; indexSeq?: number }
@@ -67,6 +148,16 @@ export type BrokerResponse =
 	  };
 const error = (code: BrokerErrorCode, message: string): BrokerResponse => ({ ok: false, error: { code, message } });
 
+function isCleanupPending(response: BrokerResponse): boolean {
+	return !response.ok && response.error.code === "cleanup_pending" && response.error.cleanup !== undefined;
+}
+
+function lifecycleResponseState(response: BrokerResponse): LifecycleState {
+	if (response.ok) return "terminal_ok";
+	if (isCleanupPending(response)) return "effect_started";
+	return response.error.code === "terminal_uncertain" ? "terminal_uncertain" : "terminal_error";
+}
+
 type InputNormalization = { input: Record<string, unknown> } | BrokerResponse;
 
 function isBrokerResponse(value: InputNormalization): value is BrokerResponse {
@@ -106,6 +197,8 @@ function normalizeBrokerInput(operation: string, input: Record<string, unknown>)
 		normalized.sourceSessionId = source.value;
 		delete normalized.sourceId;
 	}
+	if (input.directoryMigration !== undefined)
+		return error("invalid_input", "directoryMigration is broker-managed and cannot be selected by clients.");
 
 	if (operation === "session.list") {
 		const resolved = input.resolveSessionId;
@@ -272,7 +365,7 @@ type BrokerLockSnapshot = {
 const terminalPersistenceHooksForTest = new WeakMap<Broker, () => void>();
 
 export class Broker {
-	readonly settings: Required<BrokerSettings>;
+	readonly settings: ResolvedBrokerSettings;
 	readonly index: SessionIndex;
 	readonly ledger: LifecycleLedger;
 	discovery: BrokerDiscovery | null = null;
@@ -281,10 +374,16 @@ export class Broker {
 	#chains = new Map<string, Promise<void>>();
 	#stopping = false;
 	#transport: BrokerTransport | null = null;
-	#heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+	#heartbeatTimer: NodeJS.Timeout | null = null;
 	#heartbeatWrite: Promise<void> = Promise.resolve();
 	constructor(settings: BrokerSettings) {
-		this.settings = { packageGeneration: "unknown", port: 0, heartbeatTtlMs: BROKER_HEARTBEAT_TTL_MS, ...settings };
+		this.settings = {
+			agentDir: settings.agentDir,
+			packageGeneration: settings.packageGeneration ?? "unknown",
+			port: settings.port ?? 0,
+			heartbeatTtlMs: settings.heartbeatTtlMs ?? BROKER_HEARTBEAT_TTL_MS,
+			resolveDirectoryMigration: settings.resolveDirectoryMigration ?? (async () => "copy-retain"),
+		};
 		this.index = new SessionIndex(settings.agentDir);
 		this.ledger = new LifecycleLedger(settings.agentDir);
 		this.#lock = path.join(settings.agentDir, "sdk", "broker.lock");
@@ -379,13 +478,20 @@ export class Broker {
 			throw e;
 		}
 	}
+	async #releaseOwnedLock(): Promise<void> {
+		try {
+			const lock = await this.#readLock();
+			if (lock?.ownerId !== this.#owner) return;
+			await fs.unlink(this.#lockRecordPath());
+			await fs.rmdir(this.#lock);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+
 	async start(): Promise<BrokerDiscovery> {
 		this.#stopping = false;
-		await Promise.all([
-			this.index.assertSupportedStateVersions(),
-			this.ledger.assertSupportedStateVersions(),
-			readBrokerDiscovery(this.settings.agentDir),
-		]);
+		await Promise.all([this.ledger.assertSupportedStateVersions(), readBrokerDiscovery(this.settings.agentDir)]);
 		await fs.mkdir(path.dirname(this.#lock), { recursive: true, mode: 0o700 });
 		for (;;) {
 			try {
@@ -415,39 +521,47 @@ export class Broker {
 			}
 			await this.#reclaimStaleLock(snapshot);
 		}
-		await this.index.open();
-		await this.ledger.open();
-		const now = Date.now();
-		const incarnation = brokerProcessIncarnation(process.pid);
-		if (!incarnation) throw new Error("Broker process incarnation is unavailable.");
-		const token = newBrokerToken();
-		this.#transport = new BrokerTransport(this, token, this.settings.port);
-		const port = await this.#transport.start();
-		this.discovery = {
-			version: 1,
-			protocolVersion: 3,
-			packageGeneration: this.settings.packageGeneration,
-			ownerId: this.#owner,
-			pid: process.pid,
-			incarnation,
-			host: "127.0.0.1",
-			port,
-			url: `ws://127.0.0.1:${port}`,
-			token,
-			startedAt: now,
-			heartbeatAt: now,
-		};
-		await writeBrokerDiscovery(this.settings.agentDir, this.discovery);
-		this.#heartbeatTimer = setInterval(
-			() => void this.heartbeat(),
-			Math.max(1, Math.floor(this.settings.heartbeatTtlMs / 3)),
-		);
-		return this.discovery;
+		try {
+			await this.index.open();
+			await this.ledger.open();
+			const now = Date.now();
+			const incarnation = brokerProcessIncarnation(process.pid);
+			if (!incarnation) throw new Error("Broker process incarnation is unavailable.");
+			const token = newBrokerToken();
+			this.#transport = new BrokerTransport(this, token, this.settings.port);
+			const port = await this.#transport.start();
+			this.discovery = {
+				version: 1,
+				protocolVersion: 3,
+				packageGeneration: this.settings.packageGeneration,
+				ownerId: this.#owner,
+				pid: process.pid,
+				incarnation,
+				host: "127.0.0.1",
+				port,
+				url: `ws://127.0.0.1:${port}`,
+				token,
+				startedAt: now,
+				heartbeatAt: now,
+			};
+			await writeBrokerDiscovery(this.settings.agentDir, this.discovery);
+			this.#heartbeatTimer = setInterval(
+				() => void this.heartbeat(),
+				Math.max(1, Math.floor(this.settings.heartbeatTtlMs / 3)),
+			);
+			return this.discovery;
+		} catch (error) {
+			await this.#transport?.stop();
+			this.#transport = null;
+			this.discovery = null;
+			await this.#releaseOwnedLock();
+			throw error;
+		}
 	}
 	get ownsDiscovery(): boolean {
 		return this.discovery?.ownerId === this.#owner;
 	}
-	status(): ReturnType<typeof redactBrokerDiscovery> | null {
+	status(): RedactedBrokerDiscovery | null {
 		return this.discovery ? redactBrokerDiscovery(this.discovery) : null;
 	}
 	async heartbeat(): Promise<void> {
@@ -476,15 +590,7 @@ export class Broker {
 			} catch (e) {
 				if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
 			}
-			try {
-				const lock = await this.#readLock();
-				if (lock?.ownerId === this.#owner) {
-					await fs.unlink(this.#lockRecordPath());
-					await fs.rmdir(this.#lock);
-				}
-			} catch (e) {
-				if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
-			}
+			await this.#releaseOwnedLock();
 		}
 		this.discovery = null;
 	}
@@ -543,15 +649,21 @@ export class Broker {
 			const resolveSessionId = typeof input.resolveSessionId === "string" ? input.resolveSessionId : undefined;
 			const cwd = typeof input.cwd === "string" ? input.cwd : undefined;
 			if (resolveSessionId && cwd) {
-				const sessionDir = SessionManager.getDefaultSessionDir(cwd, this.settings.agentDir);
-				const match = await resolveResumableSession(resolveSessionId, cwd, sessionDir);
+				const scope = await resolveManagedSessionScope({ cwd, agentDir: this.settings.agentDir });
+				const listed =
+					scope.kind === "resolved" ? await listManagedSessionCandidates({ scope: scope.scope }) : undefined;
+				const matches =
+					listed?.kind === "complete"
+						? listed.owned.filter(candidate => candidate.sessionId === resolveSessionId)
+						: [];
+				const match = matches.length === 1 ? matches[0] : undefined;
 				return {
 					ok: true,
 					result: {
 						...result,
 						savedSession:
-							match && match.session.id === resolveSessionId
-								? { id: match.session.id, path: match.session.path }
+							match && match.sessionId === resolveSessionId
+								? { id: match.sessionId, path: match.path }
 								: undefined,
 					},
 					indexSeq: result.indexSeq,
@@ -575,37 +687,53 @@ export class Broker {
 		);
 		await prev;
 		try {
+			const beforeBegin = this.ledger.get(identity);
 			const begun = await this.ledger.begin(identity, requestHash);
-			if (begun.kind === "replay") return begun.entry.response as BrokerResponse;
+			if (begun.kind === "replay") {
+				const replay = begun.entry.response as BrokerResponse;
+				if (!(!replay.ok && replay.error.cleanup)) return replay;
+				const cleanup = replay.error.cleanup;
+				const outcome = await executeLifecycle(this, operation, input, identity, cleanup);
+				const response = outcome.response;
+				await this.ledger.transition(identity, lifecycleResponseState(response), {
+					response,
+					responseDigest: createHash("sha256").update(canonicalJson(response)).digest("hex"),
+					...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
+					...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
+				});
+				return response;
+			}
 			if (begun.kind === "idempotency_conflict")
 				return error("idempotency_conflict", "idempotency key was used with a different request");
-			if (begun.kind === "terminal_uncertain")
-				return begun.entry.response
-					? (begun.entry.response as BrokerResponse)
-					: error("terminal_uncertain", "prior lifecycle operation outcome is uncertain");
-			if (begun.kind === "in_progress") return error("broker_restarting", "lifecycle operation is in progress");
-			const outcome = await executeLifecycle(this, operation, input, identity);
-			const response = outcome.response;
-			await this.ledger.transition(
-				identity,
-				response.ok
-					? "terminal_ok"
-					: response.error.code === "terminal_uncertain"
-						? "terminal_uncertain"
-						: "terminal_error",
-				{
-					resultSessionId:
-						response.ok && typeof (response.result as { sessionId?: unknown } | undefined)?.sessionId === "string"
-							? (response.result as { sessionId: string }).sessionId
-							: undefined,
+			if (begun.kind === "terminal_uncertain") {
+				const replay = (begun.entry.response ?? beforeBegin?.response) as BrokerResponse | undefined;
+				if (!replay || replay.ok || !replay.error.cleanup)
+					return replay ?? error("terminal_uncertain", "prior lifecycle operation outcome is uncertain");
+				const outcome = await executeLifecycle(this, operation, input, identity, replay.error.cleanup);
+				const response = outcome.response;
+				await this.ledger.transition(identity, lifecycleResponseState(response), {
 					response,
 					responseDigest: createHash("sha256").update(canonicalJson(response)).digest("hex"),
 					...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
 					...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
-				},
-			);
-			const reopenedLedger = await new LifecycleLedger(this.settings.agentDir).open();
-			const persisted = reopenedLedger.get(identity);
+				});
+				return response;
+			}
+			if (begun.kind === "in_progress") return error("broker_restarting", "lifecycle operation is in progress");
+			const outcome = await executeLifecycle(this, operation, input, identity);
+			const response = outcome.response;
+			await this.ledger.transition(identity, lifecycleResponseState(response), {
+				resultSessionId:
+					response.ok && typeof (response.result as { sessionId?: unknown } | undefined)?.sessionId === "string"
+						? (response.result as { sessionId: string }).sessionId
+						: undefined,
+				response,
+				responseDigest: createHash("sha256").update(canonicalJson(response)).digest("hex"),
+				...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
+				...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
+			});
+			if (isCleanupPending(response)) return response;
+			const persisted = await this.ledger.readTerminal(identity, requestHash);
 			const expectedResponseDigest = createHash("sha256").update(canonicalJson(response)).digest("hex");
 			const persistenceVerified =
 				persisted?.responseDigest === expectedResponseDigest &&

package/src/sdk/broker/discovery.ts

@@ -33,7 +33,7 @@ export function isPidAlive(pid: number): boolean {
 	}
 }
 async function syncFile(file: string): Promise<void> {
-	const handle = await fs.open(file, "r");
+	const handle = await fs.open(file, "r+");
 	try {
 		await handle.sync();
 	} finally {

package/src/sdk/broker/ensure.ts

@@ -13,6 +13,7 @@ export interface EnsureBrokerSettings {
 }
 
 const DISCOVERY_TIMEOUT_MS = 10_000;
+const FIXTURE_DISCOVERY_TIMEOUT_MS = 30_000;
 // Bounded grace windows for reaping a spawned broker on failure, mirroring the
 // owned-process teardown convention (SIGTERM -> grace -> SIGKILL -> hard cap).
 const REAP_GRACEFUL_MS = 2_000;
@@ -215,7 +216,8 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		spawnError = error;
 	});
 	const owner = registerBrokerOwner(settings.agentDir, child);
-	const deadline = Date.now() + DISCOVERY_TIMEOUT_MS;
+	const discoveryTimeoutMs = initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS;
+	const deadline = Date.now() + discoveryTimeoutMs;
 	let discoveryError: unknown;
 	while (Date.now() < deadline) {
 		if (spawnError || child.exitCode !== null || child.signalCode !== null) break;

package/src/sdk/broker/lifecycle-codec.ts

@@ -0,0 +1,11 @@
+const lifecycleUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Decodes persisted lifecycle bytes without replacement characters before JSON parsing. */
+export function decodeLifecycleUtf8(bytes: Uint8Array): string {
+	return lifecycleUtf8Decoder.decode(bytes);
+}
+
+/** Parses persisted lifecycle JSON only after fatal UTF-8 decoding. */
+export function parseLifecycleJson(bytes: Uint8Array): unknown {
+	return JSON.parse(decodeLifecycleUtf8(bytes));
+}