@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/gjc-runtime/launch-worktree-reservation.ts

@@ -0,0 +1,242 @@
+/**
+ * Cross-process reservation for a deterministic launch-worktree path.
+ *
+ * The durable session index is the long-lived ownership record, but a newly
+ * planned worktree has no index row yet. This reservation closes that interval:
+ * it is acquired before preparation and removed after `host_registered` is
+ * durably appended to the index.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import type { Dirent } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { resolveEquivalentPath } from "@gajae-code/utils";
+import {
+	type FileLockGcObservation,
+	processStartTime,
+	readFileLockObservationForGc,
+	removeFileLockDirForGc,
+} from "../config/file-lock";
+import { processIncarnation } from "../sdk/broker/process-incarnation";
+
+const RESERVATION_VERSION = 1;
+const RESERVATION_DIRECTORY = "launch-worktree-reservations";
+
+interface LaunchWorktreeReservationRecord {
+	version: typeof RESERVATION_VERSION;
+	worktreePath: string;
+	pid: number;
+	start_time?: string;
+	processIncarnation: string | null;
+	timestamp: number;
+	reservationId: string;
+}
+
+export interface LaunchWorktreeReservation {
+	release(): Promise<void>;
+}
+
+function canonicalWorktreePath(worktreePath: string): string {
+	return resolveEquivalentPath(path.resolve(worktreePath));
+}
+
+function reservationRoot(agentDir: string): string {
+	return path.join(agentDir, "sdk", "sessions", RESERVATION_DIRECTORY);
+}
+
+function launchWorktreeReservationDirectory(agentDir: string, worktreePath: string): string {
+	const digest = createHash("sha256").update(canonicalWorktreePath(worktreePath)).digest("hex");
+	return path.join(reservationRoot(agentDir), `${digest}.lock`);
+}
+
+/** Test seam for seeding a dead-owner reservation at the exact production path. */
+export function launchWorktreeReservationDirectoryForTest(agentDir: string, worktreePath: string): string {
+	return launchWorktreeReservationDirectory(agentDir, worktreePath);
+}
+
+function isErrno(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function isReservationRecord(value: unknown): value is LaunchWorktreeReservationRecord {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Partial<LaunchWorktreeReservationRecord>;
+	return (
+		record.version === RESERVATION_VERSION &&
+		typeof record.worktreePath === "string" &&
+		record.worktreePath.length > 0 &&
+		typeof record.pid === "number" &&
+		Number.isSafeInteger(record.pid) &&
+		record.pid > 0 &&
+		(record.start_time === undefined || (typeof record.start_time === "string" && record.start_time.length > 0)) &&
+		(record.processIncarnation === null ||
+			(typeof record.processIncarnation === "string" && record.processIncarnation.length > 0)) &&
+		typeof record.timestamp === "number" &&
+		Number.isFinite(record.timestamp) &&
+		typeof record.reservationId === "string" &&
+		record.reservationId.length > 0
+	);
+}
+
+async function readReservation(lockDir: string): Promise<LaunchWorktreeReservationRecord | null> {
+	let value: unknown;
+	try {
+		value = await Bun.file(path.join(lockDir, "info")).json();
+	} catch (error) {
+		if (isErrno(error, "ENOENT") || error instanceof SyntaxError) return null;
+		throw error;
+	}
+	return isReservationRecord(value) ? value : null;
+}
+
+function ownerDefinitelyExited(record: LaunchWorktreeReservationRecord): boolean {
+	try {
+		process.kill(record.pid, 0);
+	} catch (error) {
+		return isErrno(error, "ESRCH");
+	}
+	if (record.processIncarnation !== null) {
+		const actualIncarnation = processIncarnation(record.pid);
+		if (actualIncarnation !== undefined) return actualIncarnation !== record.processIncarnation;
+	}
+	if (record.start_time) {
+		const actualStartTime = processStartTime(record.pid);
+		if (actualStartTime !== null) return actualStartTime !== record.start_time;
+	}
+	return false;
+}
+
+async function removeReservation(
+	lockDir: string,
+	record: LaunchWorktreeReservationRecord,
+): Promise<"removed" | "kept"> {
+	// Capture the exact on-disk identity BEFORE authorizing removal: the generic
+	// GC remover only deletes a tree whose pre-verdict identity it was handed,
+	// so a successor reservation published at the same path is never reaped.
+	let observation: FileLockGcObservation | null;
+	try {
+		observation = await readFileLockObservationForGc(lockDir);
+	} catch {
+		return "kept";
+	}
+	if (!observation) return "kept";
+	let onDisk: unknown;
+	try {
+		onDisk = JSON.parse(observation.bytes);
+	} catch {
+		return "kept";
+	}
+	if (
+		!isReservationRecord(onDisk) ||
+		onDisk.reservationId !== record.reservationId ||
+		onDisk.pid !== record.pid ||
+		onDisk.timestamp !== record.timestamp ||
+		canonicalWorktreePath(onDisk.worktreePath) !== canonicalWorktreePath(record.worktreePath)
+	)
+		return "kept";
+	const result = await removeFileLockDirForGc(lockDir, observation.info, observation.identity);
+	return result === "removed" ? "removed" : "kept";
+}
+
+async function writeReservation(lockDir: string, record: LaunchWorktreeReservationRecord): Promise<void> {
+	try {
+		await Bun.write(path.join(lockDir, "info"), JSON.stringify(record));
+	} catch (error) {
+		await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function tryPublishReservation(lockDir: string, record: LaunchWorktreeReservationRecord): Promise<boolean> {
+	const pendingDir = `${lockDir}.pending.${process.pid}.${randomUUID()}`;
+	await fs.mkdir(pendingDir, { mode: 0o700 });
+	try {
+		await writeReservation(pendingDir, record);
+		try {
+			await fs.rename(pendingDir, lockDir);
+			return true;
+		} catch (error) {
+			if (isErrno(error, "EEXIST") || isErrno(error, "ENOTEMPTY")) return false;
+			if (isErrno(error, "EPERM")) {
+				try {
+					await fs.stat(lockDir);
+					return false;
+				} catch (statError) {
+					if (!isErrno(statError, "ENOENT")) throw statError;
+				}
+			}
+			throw error;
+		}
+	} finally {
+		await fs.rm(pendingDir, { recursive: true, force: true }).catch(() => undefined);
+	}
+}
+
+/**
+ * Atomically claim `worktreePath`, returning `null` only when another live or
+ * unverified launch already owns the same deterministic target. A dead or
+ * PID-reused owner is reclaimed before retrying the exclusive directory create.
+ */
+export async function reserveLaunchWorktree(
+	agentDir: string,
+	worktreePath: string,
+): Promise<LaunchWorktreeReservation | null> {
+	const canonicalPath = canonicalWorktreePath(worktreePath);
+	const lockDir = launchWorktreeReservationDirectory(agentDir, canonicalPath);
+	await fs.mkdir(path.dirname(lockDir), { recursive: true, mode: 0o700 });
+	const ownStartTime = processStartTime(process.pid) ?? undefined;
+	const ownIncarnation = processIncarnation(process.pid) ?? null;
+
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		const record: LaunchWorktreeReservationRecord = {
+			version: RESERVATION_VERSION,
+			worktreePath: canonicalPath,
+			pid: process.pid,
+			...(ownStartTime ? { start_time: ownStartTime } : {}),
+			processIncarnation: ownIncarnation,
+			timestamp: Date.now(),
+			reservationId: randomUUID(),
+		};
+		if (await tryPublishReservation(lockDir, record)) {
+			return {
+				async release(): Promise<void> {
+					await removeReservation(lockDir, record);
+				},
+			};
+		}
+
+		const existing = await readReservation(lockDir);
+		if (
+			!existing ||
+			canonicalWorktreePath(existing.worktreePath) !== canonicalPath ||
+			!ownerDefinitelyExited(existing)
+		)
+			return null;
+		if ((await removeReservation(lockDir, existing)) !== "removed") return null;
+	}
+
+	return null;
+}
+
+/** Remove the transient reservation only after the matching worktree is indexed. */
+export async function releaseLaunchWorktreeReservationAfterRegistration(
+	agentDir: string,
+	worktreePath: string,
+): Promise<void> {
+	const canonicalPath = canonicalWorktreePath(worktreePath);
+	let entries: Dirent[];
+	try {
+		entries = await fs.readdir(reservationRoot(agentDir), { withFileTypes: true });
+	} catch (error) {
+		if (isErrno(error, "ENOENT")) return;
+		throw error;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !entry.name.endsWith(".lock")) continue;
+		const lockDir = path.join(reservationRoot(agentDir), entry.name);
+		const record = await readReservation(lockDir);
+		if (!record || canonicalWorktreePath(record.worktreePath) !== canonicalPath) continue;
+		await removeReservation(lockDir, record);
+	}
+}

package/src/gjc-runtime/launch-worktree.ts

@@ -29,6 +29,27 @@ export interface GjcLaunchWorktreeResult extends GjcLaunchWorktreePlan {
 	createdBranch: boolean;
 	dirty?: boolean;
 }
+export interface LaunchWorktreeAbortOptions {
+	signal?: AbortSignal;
+	deadlineAt?: number;
+	now?: () => number;
+}
+
+export class WorktreePreparationTimeoutError extends Error {
+	readonly code = "worktree_preparation_timeout";
+	constructor(message = "Worktree preparation exceeded its deadline before the session host was spawned.") {
+		super(message);
+		this.name = "WorktreePreparationTimeoutError";
+	}
+}
+
+export class DependencyPreparationTimeoutError extends Error {
+	readonly code = "dependency_preparation_timeout";
+	constructor(message = "Dependency preparation exceeded its deadline before the session host was spawned.") {
+		super(message);
+		this.name = "DependencyPreparationTimeoutError";
+	}
+}
 
 interface GitWorktreeEntry {
 	path: string;
@@ -39,10 +60,93 @@ interface GitWorktreeEntry {
 
 const BRANCH_IN_USE_PATTERN = /already checked out|already used by worktree|is already checked out/i;
 
+function throwIfAborted(options: LaunchWorktreeAbortOptions | undefined, timeout: Error): void {
+	if (options?.signal?.aborted) throw timeout;
+	if (options?.deadlineAt !== undefined && (options.now ?? Date.now)() >= options.deadlineAt) throw timeout;
+}
+
+function sanitizeWorktreeDiagnostic(value: string): string {
+	return value
+		.replace(/([?&](?:token|secret|password|key|api[_-]?key)=[^\s&]*)/giu, "[redacted-query]")
+		.replace(
+			/(^|[^\p{L}\p{N}_-])[\p{L}\p{N}_-]*(?:token|secret|password|api[_-]?key|key|credential|auth)\s*[=:]\s*[^\s,;]+/giu,
+			"$1[redacted-secret]",
+		)
+		.replace(/\b(?:https?|wss?):\/\/[^\s]+/giu, "[redacted-url]")
+		.slice(0, 512);
+}
+
+async function spawnProcessGroup(
+	command: string[],
+	cwd: string,
+	options: LaunchWorktreeAbortOptions | undefined,
+	timeout: Error,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	throwIfAborted(options, timeout);
+	const [file, ...args] = command;
+	if (!file) throw timeout;
+	const proc = Bun.spawn([file, ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+		stdin: "ignore",
+		// Windows has no POSIX process-group kill: parent-only proc.kill() is the
+		// documented seam. Leftover classify still runs after wait on both OS.
+		detached: process.platform !== "win32",
+		...(process.platform === "win32" ? { windowsHide: true } : {}),
+	});
+	const killGroup = (): void => {
+		try {
+			if (process.platform === "win32") proc.kill();
+			else if (proc.pid) process.kill(-proc.pid, "SIGKILL");
+			else proc.kill();
+		} catch {
+			try {
+				proc.kill();
+			} catch {
+				// already gone
+			}
+		}
+	};
+	const onAbort = (): void => {
+		killGroup();
+	};
+	options?.signal?.addEventListener("abort", onAbort, { once: true });
+	let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+	if (options?.deadlineAt !== undefined) {
+		const remaining = options.deadlineAt - (options.now ?? Date.now)();
+		if (remaining <= 0) {
+			killGroup();
+			options?.signal?.removeEventListener("abort", onAbort);
+			await proc.exited.catch(() => undefined);
+			throw timeout;
+		}
+		deadlineTimer = setTimeout(() => {
+			killGroup();
+		}, remaining);
+	}
+	try {
+		const [stdoutBytes, stderrBytes, exitCode] = await Promise.all([
+			new Response(proc.stdout).arrayBuffer(),
+			new Response(proc.stderr).arrayBuffer(),
+			proc.exited,
+		]);
+		throwIfAborted(options, timeout);
+		return {
+			stdout: new TextDecoder().decode(stdoutBytes),
+			stderr: new TextDecoder().decode(stderrBytes),
+			exitCode: exitCode ?? 1,
+		};
+	} finally {
+		if (deadlineTimer) clearTimeout(deadlineTimer);
+		options?.signal?.removeEventListener("abort", onAbort);
+	}
+}
+
 function runGit(cwd: string, args: string[]): string {
 	const result = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
 	if (result.exitCode === 0) return result.stdout.toString().trim();
-	const stderr = result.stderr.toString().trim();
+	const stderr = sanitizeWorktreeDiagnostic(result.stderr.toString().trim());
 	throw new Error(stderr || `git ${args.join(" ")} failed`);
 }
 
@@ -408,6 +512,16 @@ export function planLaunchWorktree(
 
 export function ensureLaunchWorktree(
 	plan: GjcLaunchWorktreePlan | { enabled: false },
+	options?: LaunchWorktreeAbortOptions,
+): GjcLaunchWorktreeResult | { enabled: false } {
+	if (options?.signal || options?.deadlineAt !== undefined) {
+		throw new Error("ensureLaunchWorktree is synchronous; use ensureLaunchWorktreeCancellable for abortable prep.");
+	}
+	return ensureLaunchWorktreeSync(plan);
+}
+
+function ensureLaunchWorktreeSync(
+	plan: GjcLaunchWorktreePlan | { enabled: false },
 ): GjcLaunchWorktreeResult | { enabled: false } {
 	if (!plan.enabled) return { enabled: false };
 	const bucketPath = path.dirname(plan.worktreePath);
@@ -473,7 +587,93 @@ export function ensureLaunchWorktree(
 
 	const result = Bun.spawnSync(["git", ...args], { cwd: plan.repoRoot, stdout: "pipe", stderr: "pipe" });
 	if (result.exitCode !== 0) {
-		const stderr = result.stderr.toString().trim();
+		const stderr = sanitizeWorktreeDiagnostic(result.stderr.toString().trim());
+		if (plan.branchName && BRANCH_IN_USE_PATTERN.test(stderr)) throw new Error(`branch_in_use:${plan.branchName}`);
+		throw new Error(stderr || `worktree_add_failed:${args.join(" ")}`);
+	}
+
+	return {
+		...plan,
+		worktreePath: path.resolve(plan.worktreePath),
+		created: true,
+		reused: false,
+		createdBranch: Boolean(plan.branchName && !branchAlreadyExisted),
+	};
+}
+
+export async function ensureLaunchWorktreeCancellable(
+	plan: GjcLaunchWorktreePlan | { enabled: false },
+	options: LaunchWorktreeAbortOptions = {},
+): Promise<GjcLaunchWorktreeResult | { enabled: false }> {
+	if (!plan.enabled) return { enabled: false };
+	const timeout = new WorktreePreparationTimeoutError();
+	throwIfAborted(options, timeout);
+	const bucketPath = path.dirname(plan.worktreePath);
+	inspectBucketDir(bucketPath);
+	ensureRepositoryBucketIgnored(plan.repoRoot, bucketPath);
+	let allWorktrees = listWorktrees(plan.repoRoot);
+	const staleAtPath = findWorktreeByPath(allWorktrees, plan.worktreePath);
+	if (staleAtPath && !fs.existsSync(staleAtPath.path)) {
+		pruneStaleWorktreePath(plan.repoRoot);
+		allWorktrees = listWorktrees(plan.repoRoot);
+	}
+	throwIfAborted(options, timeout);
+
+	const listedAtPath = findWorktreeByPath(allWorktrees, plan.worktreePath);
+	const existingAtPath = readWorktreeEntryFromPath(plan.repoRoot, plan.worktreePath);
+	if (listedAtPath && !existingAtPath) {
+		if (fs.existsSync(plan.worktreePath)) throw new Error(`worktree_path_conflict:${plan.worktreePath}`);
+		throw new Error(
+			[
+				"worktree_path_unavailable",
+				"The requested launch worktree is still registered by Git but its directory is unavailable or locked.",
+				`Path: ${formatBucketPath(plan.worktreePath)}`,
+				"Safe remediation: inspect the worktree lock and remove or repair it with git worktree remove/prune when it is no longer needed, then relaunch. GJC did not delete or replace the entry.",
+			].join("\n"),
+		);
+	}
+	const expectedBranchRef = plan.branchName ? `refs/heads/${plan.branchName}` : null;
+
+	if (existingAtPath) {
+		let dirty = isWorktreeDirty(plan.worktreePath);
+		if (plan.detached) {
+			if (!existingAtPath.detached) {
+				throw new Error(formatWorktreeTargetMismatch(plan, existingAtPath));
+			}
+			if (existingAtPath.head !== plan.baseRef) {
+				if (dirty) throw new Error(`worktree_dirty:${plan.worktreePath}`);
+				runGit(plan.worktreePath, ["checkout", "--detach", plan.baseRef]);
+				dirty = false;
+			}
+		} else if (existingAtPath.branchRef !== expectedBranchRef) {
+			throw new Error(formatWorktreeTargetMismatch(plan, existingAtPath));
+		}
+		return {
+			...plan,
+			worktreePath: path.resolve(plan.worktreePath),
+			created: false,
+			reused: true,
+			createdBranch: false,
+			...(dirty ? { dirty: true } : {}),
+		};
+	}
+
+	if (fs.existsSync(plan.worktreePath)) throw new Error(`worktree_path_conflict:${plan.worktreePath}`);
+	if (plan.branchName && hasBranchInUse(allWorktrees, plan.branchName, plan.worktreePath)) {
+		throw new Error(`branch_in_use:${plan.branchName}`);
+	}
+
+	ensureBucketDirUsable(path.dirname(plan.worktreePath));
+	throwIfAborted(options, timeout);
+	const branchAlreadyExisted = plan.branchName ? branchExists(plan.repoRoot, plan.branchName) : false;
+	const args = ["worktree", "add"];
+	if (plan.detached) args.push("--detach", plan.worktreePath, plan.baseRef);
+	else if (branchAlreadyExisted) args.push(plan.worktreePath, plan.branchName ?? "");
+	else args.push("-b", plan.branchName ?? "", plan.worktreePath, plan.baseRef);
+
+	const result = await spawnProcessGroup(["git", ...args], plan.repoRoot, options, timeout);
+	if (result.exitCode !== 0) {
+		const stderr = sanitizeWorktreeDiagnostic(result.stderr.trim());
 		if (plan.branchName && BRANCH_IN_USE_PATTERN.test(stderr)) throw new Error(`branch_in_use:${plan.branchName}`);
 		throw new Error(stderr || `worktree_add_failed:${args.join(" ")}`);
 	}
@@ -598,10 +798,49 @@ function installWorkspaceDependencies(
 			stderr: "pipe",
 		});
 	} catch (error) {
-		throw new Error(`worktree_dependency_install_failed:${manager.name}:${String(error)}`);
+		throw new Error(
+			`worktree_dependency_install_failed:${manager.name}:${sanitizeWorktreeDiagnostic(String(error))}`,
+		);
+	}
+	if (result.exitCode !== 0) {
+		throw new Error(
+			`worktree_dependency_install_failed:${manager.name}:${sanitizeWorktreeDiagnostic(result.stderr.toString().trim())}`,
+		);
+	}
+	let installed: fs.Stats;
+	try {
+		installed = fs.lstatSync(path.join(worktreePath, "node_modules"));
+	} catch (error) {
+		if (fileSystemErrorCode(error) === "ENOENT") return;
+		throw error;
+	}
+	if (!installed.isDirectory() || installed.isSymbolicLink()) throw new Error("worktree_dependency_install_not_local");
+}
+
+async function installWorkspaceDependenciesCancellable(
+	sourceRoot: string,
+	worktreePath: string,
+	manifest: WorkspacePackageManifest | null,
+	options: LaunchWorktreeAbortOptions = {},
+): Promise<void> {
+	const timeout = new DependencyPreparationTimeoutError();
+	throwIfAborted(options, timeout);
+	removeLegacySourceNodeModulesLink(sourceRoot, worktreePath);
+	const manager = resolveWorkspacePackageManager(worktreePath, manifest);
+	const command = workspaceInstallCommand(manager);
+	let result: { stdout: string; stderr: string; exitCode: number };
+	try {
+		result = await spawnProcessGroup(command, worktreePath, options, timeout);
+	} catch (error) {
+		if (error instanceof DependencyPreparationTimeoutError) throw error;
+		throw new Error(
+			`worktree_dependency_install_failed:${manager.name}:${sanitizeWorktreeDiagnostic(String(error))}`,
+		);
 	}
 	if (result.exitCode !== 0) {
-		throw new Error(`worktree_dependency_install_failed:${manager.name}:${result.stderr.toString().trim()}`);
+		throw new Error(
+			`worktree_dependency_install_failed:${manager.name}:${sanitizeWorktreeDiagnostic(result.stderr.trim())}`,
+		);
 	}
 	let installed: fs.Stats;
 	try {
@@ -628,6 +867,26 @@ export function ensureReusableNodeModules(sourceRoot: string, worktreePath: stri
 	return "symlink";
 }
 
+export async function ensureReusableNodeModulesCancellable(
+	sourceRoot: string,
+	worktreePath: string,
+	options: LaunchWorktreeAbortOptions = {},
+): Promise<"symlink" | "present" | "missing"> {
+	const timeout = new DependencyPreparationTimeoutError();
+	throwIfAborted(options, timeout);
+	const target = path.join(worktreePath, "node_modules");
+	const manifest = readWorkspacePackageManifest(worktreePath);
+	if (isWorkspaceRoot(worktreePath, manifest)) {
+		await installWorkspaceDependenciesCancellable(sourceRoot, worktreePath, manifest, options);
+		return "present";
+	}
+	if (fs.existsSync(target)) return "present";
+	const source = path.join(sourceRoot, "node_modules");
+	if (!fs.existsSync(source)) return "missing";
+	fs.symlinkSync(source, target, "junction");
+	return "symlink";
+}
+
 /** Result of {@link prepareLaunchWorktree}: the effective working directory, remaining args, and resolved worktree plan. */
 export interface PreparedLaunchWorktree {
 	cwd: string;
@@ -643,3 +902,25 @@ export function prepareLaunchWorktree(cwd: string, args: string[]): PreparedLaun
 	ensureReusableNodeModules(ensured.repoRoot, ensured.worktreePath);
 	return { cwd: ensured.worktreePath, args: parsed.remainingArgs, worktree: ensured };
 }
+export function removeOwnedLaunchWorktree(
+	plan: GjcLaunchWorktreePlan,
+	receipt: { created: boolean; reused: boolean; createdBranch: boolean },
+): void {
+	if (!receipt.created || receipt.reused) return;
+	try {
+		runGit(plan.repoRoot, ["worktree", "remove", "--force", plan.worktreePath]);
+	} catch {
+		try {
+			runGit(plan.repoRoot, ["worktree", "prune"]);
+		} catch {
+			// Proof stays on the ledger; leftover classify is best-effort after abort.
+		}
+	}
+	if (receipt.createdBranch && plan.branchName) {
+		try {
+			runGit(plan.repoRoot, ["branch", "-D", plan.branchName]);
+		} catch {
+			// Owned-branch delete is best-effort; collisions keep the pre-existing branch.
+		}
+	}
+}