@gajae-code/coding-agent 0.16.0 → 0.16.3

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.
+		}
+	}
+}

package/src/gjc-runtime/session-state-lock.ts

@@ -55,6 +55,10 @@ function lockRetryElapsedMs(budget: LockRetryBudget): number {
 	return Math.max(0, performance.now() - budget.startedAt);
 }
 
+function lockRetryExhausted(budget: LockRetryBudget): boolean {
+	return lockRetryElapsedMs(budget) >= LOCK_ACQUIRE_TIMEOUT_MS;
+}
+
 async function waitForLockRetry(budget: LockRetryBudget): Promise<boolean> {
 	budget.attempts++;
 	const remainingMs = LOCK_ACQUIRE_TIMEOUT_MS - lockRetryElapsedMs(budget);
@@ -78,8 +82,8 @@ async function waitForLockRetry(budget: LockRetryBudget): Promise<boolean> {
  * owner record is the sibling `<file>.lock.transition.owner`. `mkdir` admits exactly one
  * contender, while the held directory prevents a successor until release unlinks the
  * validated sidecar and atomically `rmdir`s the claim. A crash before either step leaves a
- * fail-closed directory for explicit recovery; concurrent automatic reclaim cannot prove
- * that a directory + sibling sidecar still name the claim it inspected.
+ * directory that a successor may reclaim only with proof: a host-qualified owner whose pid
+ * is proven dead, plus an exact directory-generation and tree match at removal time.
  *
  * The separate sidecar keeps the claim directory empty, which is what makes `rmdir` the
  * identity-safe portable release primitive. The path stays distinct from `<file>.lock`
@@ -237,8 +241,7 @@ function removeOwnedTransitionClaim(nativePath: string, generation: TransitionDi
 	if (!captured.ok || !captured.snapshot) return captured.code === "not_found";
 	const root = captured.snapshot.entries.find(entry => entry.relativePath === "");
 	if (
-		!root ||
-		root.kind !== "directory" ||
+		root?.kind !== "directory" ||
 		root.dev !== String(generation.dev) ||
 		root.ino !== String(generation.ino) ||
 		root.nlink !== String(generation.nlink) ||
@@ -410,6 +413,8 @@ export const SessionStateLockTestHooks: {
 	forcedQuarantineName?: string;
 	/** @internal Observes bounded acquisition retries without changing their timing. */
 	afterAcquireContention?: (lockFile: string, attempt: number, elapsedMs: number) => void;
+	/** @internal Runs after transition mkdir contention and before stale-claim inspection. */
+	afterTransitionClaimContention?: (transitionDir: string) => void | Promise<void>;
 } = {};
 
 /** Raised when the lock could not be acquired; callers map it to their own refusal. */
@@ -465,6 +470,112 @@ export class SessionStateLockUnavailableError extends Error {
 	}
 }
 
+/**
+ * Log fields describing a persist failure: the error text plus, when a session state
+ * lock refusal sits anywhere in the cause chain, its typed `reason` and `lockPath`.
+ * Wrapping errors (`PreviousRuntimeStateReadError`, `AggregateError`) are searched
+ * so the actionable detail is never buried behind a generic message.
+ */
+export function sessionStateLockFailureFields(error: unknown): {
+	error: string;
+	reason?: SessionStateLockUnavailableReason;
+	lockPath?: string;
+} {
+	const fields: { error: string; reason?: SessionStateLockUnavailableReason; lockPath?: string } = {
+		error: String(error),
+	};
+	const seen = new Set<unknown>();
+	const queue: unknown[] = [error];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === null || typeof current !== "object" || seen.has(current)) continue;
+		seen.add(current);
+		if (current instanceof SessionStateLockUnavailableError) {
+			if (current.reason !== undefined) fields.reason = current.reason;
+			if (current.lockPath !== undefined) fields.lockPath = current.lockPath;
+			if (fields.reason !== undefined && fields.lockPath !== undefined) return fields;
+		}
+		if (current instanceof AggregateError) queue.push(...current.errors);
+		if ("cause" in current) queue.push((current as { cause?: unknown }).cause);
+	}
+	return fields;
+}
+
+function boundedPersistFailureClassPart(value: unknown, fallback: string): string {
+	if (typeof value !== "string" && typeof value !== "number") return fallback;
+	const normalized = String(value)
+		.replace(/[^A-Za-z0-9_.-]/gu, "_")
+		.slice(0, 64);
+	return normalized || fallback;
+}
+
+function persistFailureProperty(value: unknown, name: string): unknown {
+	if (value === null || (typeof value !== "object" && typeof value !== "function")) return undefined;
+	try {
+		return Reflect.get(value, name);
+	} catch {
+		return undefined;
+	}
+}
+
+function persistFailureConstructorName(error: unknown): string {
+	if (error === null) return "null";
+	if (typeof error !== "object" && typeof error !== "function") return typeof error;
+	const ctor = persistFailureProperty(error, "constructor");
+	const name = persistFailureProperty(ctor, "name");
+	return typeof name === "string" && name.length > 0 ? name : "Object";
+}
+
+/**
+ * Build a bounded warn-window partition without including arbitrary error text. Typed lock
+ * refusals use their stable reason; all other failures use the root constructor and the
+ * first structured `code`/`errno` found in the error/cause chain.
+ */
+function persistFailureClass(error: unknown): string {
+	const lockFields = sessionStateLockFailureFields(error);
+	if (lockFields.reason !== undefined) return `reason:${lockFields.reason}`;
+	const seen = new Set<unknown>();
+	const queue: unknown[] = [error];
+	let code: unknown;
+	let errno: unknown;
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === null || typeof current !== "object" || seen.has(current)) continue;
+		seen.add(current);
+		code ??= persistFailureProperty(current, "code");
+		errno ??= persistFailureProperty(current, "errno");
+		if (code !== undefined && errno !== undefined) break;
+		if (current instanceof AggregateError) queue.push(...current.errors);
+		const cause = persistFailureProperty(current, "cause");
+		if (cause !== undefined) queue.push(cause);
+	}
+	return `error:${boundedPersistFailureClassPart(persistFailureConstructorName(error), "Object")}:code=${boundedPersistFailureClassPart(code, "none")}:errno=${boundedPersistFailureClassPart(errno, "none")}`;
+}
+
+export const PERSIST_FAILURE_WARN_WINDOW_MS = 30_000;
+const persistFailureLastWarnedAt = new Map<string, number>();
+
+/**
+ * Whether a persist failure should be logged at warn level. The first failure for each
+ * document and stable failure class in a 30s window warns; repeats are the caller's cue
+ * to log at debug instead.
+ */
+export function shouldWarnPersistFailure(key: string, error: unknown, now = Date.now()): boolean {
+	for (const [otherKey, warnedAt] of persistFailureLastWarnedAt) {
+		if (now - warnedAt >= PERSIST_FAILURE_WARN_WINDOW_MS) persistFailureLastWarnedAt.delete(otherKey);
+	}
+	const scopedKey = `${key}\u0000${persistFailureClass(error)}`;
+	const last = persistFailureLastWarnedAt.get(scopedKey);
+	if (last !== undefined && now - last < PERSIST_FAILURE_WARN_WINDOW_MS) return false;
+	persistFailureLastWarnedAt.set(scopedKey, now);
+	return true;
+}
+
+/** @internal Test seam: forget every persist-failure warn window. */
+export function resetPersistFailureWarnWindows(): void {
+	persistFailureLastWarnedAt.clear();
+}
+
 function lockUnavailable(
 	lockPath: string,
 	reason: SessionStateLockUnavailableReason,
@@ -1388,6 +1499,7 @@ async function releaseOwnerLock(file: string, held: LockOwnerSnapshot): Promise<
 type SessionStateLockReclaimResult =
 	| "absent_or_changed"
 	| "legacy_directory_unprovenanced"
+	| "owner_removed"
 	| "owner_live_or_unverifiable"
 	| "owner_record_fresh"
 	| "owner_unprovenanced"
@@ -1426,7 +1538,8 @@ async function reclaimStaleOwnerRecord(
 	// A successor that took the path in the final window keeps it; this call just loses.
 	if (outcome === "refused")
 		throw new SessionStateLockUnavailableError(new Error("Stale owner record could not be reclaimed."));
-	return outcome === "removed" || outcome === "absent" ? "reclaimed" : "absent_or_changed";
+	if (outcome === "removed") return "owner_removed";
+	return "absent_or_changed";
 }
 
 /**
@@ -1558,14 +1671,18 @@ async function releaseTransitionClaim(
 	}
 }
 
-async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName: string): Promise<void> {
-	const stat = await fs.lstat(transitionDir, { bigint: true }).catch(() => null);
-	if (!stat) return;
+async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName: string): Promise<boolean> {
+	let stat: fsSync.BigIntStats;
+	try {
+		stat = await fs.lstat(transitionDir, { bigint: true });
+	} catch {
+		return false;
+	}
 	// Regular-file claims belong to the superseded protocol. They retain the old
 	// exact-identity stale path; released PID-1 tombstones deliberately require
 	// explicit cleanup before this atomic-directory protocol can take over.
 	if (stat.isFile()) {
-		await reclaimStaleOwnerRecord(
+		const reclaimed = await reclaimStaleOwnerRecord(
 			transitionDir,
 			{
 				afterInspection: SessionStateLockTestHooks.afterTransitionStaleInspection,
@@ -1573,53 +1690,56 @@ async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName
 			},
 			quarantineName,
 		);
-		return;
+		return reclaimed === "owner_removed";
 	}
 	if (!stat.isDirectory()) throw new SessionStateLockUnavailableError();
 	const ownerSnapshot = await captureRegularLockOwner(`${transitionDir}.owner`);
-	if (!ownerSnapshot) return;
+	if (!ownerSnapshot) return false;
 	let owner: unknown;
 	try {
 		owner = JSON.parse(ownerSnapshot.bytes);
 	} catch {
-		return;
+		return false;
 	}
-	if (!validLockOwner(owner)) return;
+	if (!validLockOwner(owner)) return false;
+	await SessionStateLockTestHooks.afterTransitionStaleInspection?.(transitionDir);
 	if (owner.released === true) {
 		// A released record is safe only when it is qualified by this installation.
 		// Never let a shared-volume tombstone, an absent identity, or a legacy foreign
 		// identity authorize removal of a claim this process cannot own.
-		if (owner.owner_host_id === undefined) return;
+		if (owner.owner_host_id === undefined) return false;
 		const currentHost = await currentOwnerHostId();
 		const legacyHost = await currentLegacyOwnerHostId();
-		if (owner.owner_host_id !== currentHost && owner.owner_host_id !== legacyHost) return;
-		if (Date.now() - Number(ownerSnapshot.mtimeNs / 1_000_000n) < RELEASED_TRANSITION_GRACE_MS) return;
-	} else {
-		if (process.platform !== "win32") return;
-		if (await lockOwnerIsAlive(owner)) return;
+		if (owner.owner_host_id !== currentHost && owner.owner_host_id !== legacyHost) return false;
+		if (Date.now() - Number(ownerSnapshot.mtimeNs / 1_000_000n) < RELEASED_TRANSITION_GRACE_MS) return false;
+	} else if (await lockOwnerIsAlive(owner)) {
+		// Only a host-qualified owner whose pid is PROVEN dead (ESRCH, or a live pid
+		// with a provably different incarnation) authorizes reclaim. The generation
+		// + exact-tree checks below then bind the removal to the very directory
+		// inspected here, on every platform; a claim stranded by a force-quit
+		// (`postmortem.quit`) would otherwise wall the session directory forever.
+		return false;
 	}
 	const generation = transitionGenerationFromStat(stat);
 	const nativePath = await canonicalOwnedTransitionPath(transitionDir).catch(() => null);
-	if (!nativePath) return;
+	if (!nativePath) return false;
 	const captured = nativeSessionStateLock().snapshotDirectoryTree(nativePath);
-	if (!captured.ok || !captured.snapshot) return;
+	if (!captured.ok || !captured.snapshot) return false;
 	const root = captured.snapshot.entries.find(entry => entry.relativePath === "");
 	if (
-		!root ||
-		root.kind !== "directory" ||
+		root?.kind !== "directory" ||
 		root.dev !== String(generation.dev) ||
 		root.ino !== String(generation.ino) ||
 		root.nlink !== String(generation.nlink) ||
 		root.mtimeNs !== String(generation.mtimeNs) ||
 		root.ctimeNs !== String(generation.ctimeNs)
 	)
-		return;
-	if (captured.snapshot.entries.length !== 1) return;
+		return false;
+	if (captured.snapshot.entries.length !== 1) return false;
 	const removed = nativeSessionStateLock().exactRemoveDirectoryTree(nativePath, captured.snapshot);
 	if (removed.ok || removed.code === "not_found") {
-		const ownerRemoval = exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
-		if (ownerRemoval !== "removed" && ownerRemoval !== "absent") return;
-		return;
+		exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
+		return removed.ok;
 	}
 	if (
 		removed.code === "cleanup_pending" &&
@@ -1635,9 +1755,8 @@ async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName
 		// collision on POSIX. rmdir never follows a directory's contents and refuses if a
 		// successor populated the detached path.
 		await removeTransitionDir(removed.detachedPath);
-		const ownerRemoval = exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
-		if (ownerRemoval !== "removed" && ownerRemoval !== "absent") return;
-		return;
+		exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
+		return true;
 	}
 	throw new SessionStateLockUnavailableError(
 		new Error(`Stale transition claim could not be reclaimed (${removed.code ?? "unknown"}).`),
@@ -1901,7 +2020,12 @@ async function withLockPathTransition<T>(
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
 			if (code !== "EEXIST" && !isTransientLockError(error)) throw new SessionStateLockUnavailableError(error);
-			await reclaimStaleTransitionClaim(transitionDir, quarantineName);
+			await SessionStateLockTestHooks.afterTransitionClaimContention?.(transitionDir);
+			if (await reclaimStaleTransitionClaim(transitionDir, quarantineName)) {
+				if (lockRetryExhausted(budget))
+					throw lockUnavailable(transitionDir, "transition_claim_timeout", budget, error);
+				continue;
+			}
 			if (!(await waitForLockRetry(budget)))
 				throw lockUnavailable(transitionDir, "transition_claim_timeout", budget, error);
 			continue;

package/src/gjc-runtime/session-state-sidecar.ts

@@ -1632,12 +1632,9 @@ async function writeStateFileSyncConditional(
  * than faulting forever.
  */
 async function withStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T> {
-	try {
-		return await withSessionStateFileLock(stateFile, operation);
-	} catch (error) {
-		if (error instanceof SessionStateLockUnavailableError) throw new PreviousRuntimeStateReadError(error);
-		throw error;
-	}
+	// Preserve the lock's typed path/reason diagnostics. A transition timeout means the
+	// state file was never entered, not that its existing JSON marker was unreadable.
+	return await withSessionStateFileLock(stateFile, operation);
 }
 
 function coordinatorTransactionLockFile(stateFile: string): string {
@@ -1650,17 +1647,13 @@ function coordinatorTransactionLockFile(stateFile: string): string {
  * protocol.
  */
 async function withCoordinatorTransactionLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T> {
-	try {
-		return await withFileLock(coordinatorTransactionLockFile(stateFile), operation, {
-			staleMs: 30_000,
-			retries: 12_000,
-			retryDelayMs: 5,
-		});
-	} catch (error) {
-		if (error instanceof Error && error.message.startsWith("Failed to acquire lock"))
-			throw new PreviousRuntimeStateReadError();
-		throw error;
-	}
+	// Namespace-lock failures are contention or filesystem failures, not evidence that
+	// runtime-state.json is malformed. Let the original diagnostic reach the caller.
+	return await withFileLock(coordinatorTransactionLockFile(stateFile), operation, {
+		staleMs: 30_000,
+		retries: 12_000,
+		retryDelayMs: 5,
+	});
 }
 
 function orderedDistinctStateFiles(stateFiles: readonly string[], platform: NodeJS.Platform): string[] {