@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/gjc-runtime/managed-owner-supervisor.ts

@@ -15,6 +15,8 @@ export const MANAGED_OWNER_GENERATION_ENV = "GJC_TMUX_OWNER_GENERATION";
 export const MANAGED_OWNER_STATE_DIR_ENV = "GJC_TMUX_OWNER_STATE_DIR";
 export const MANAGED_OWNER_RUN_ID_ENV = "GJC_MANAGED_OWNER_RUN_ID";
 export const MANAGED_OWNER_INCARNATION_ENV = "GJC_MANAGED_OWNER_INCARNATION";
+/** Suppresses command-derived durable artifacts for Broker-owned opaque spawn children. */
+export const MANAGED_OWNER_REDACT_COMMAND_ENV = "GJC_MANAGED_OWNER_REDACT_COMMAND";
 
 let bootstrapSigtermPending = false;
 const captureBootstrapSigterm = () => {
@@ -140,26 +142,32 @@ export async function runManagedOwnerSupervisor(): Promise<void> {
 	if (!supervisorStartTime) throw new Error("managed_owner_supervisor_start_time_unavailable");
 	await fs.mkdir(root, { recursive: true, mode: 0o700 });
 	const childToken = crypto.randomUUID();
-	const binding: ManagedOwnerBinding = {
-		schema_version: 2,
-		generation,
-		session_id: sessionId,
-		run_id: runId,
-		endpoint_incarnation: incarnation,
-		child_token: childToken,
-		command,
-		command_sha256: commandDigest(command),
-		supervisor_pid: process.pid,
-		supervisor_start_time: supervisorStartTime,
-		created_at: new Date().toISOString(),
-	};
-	await writeDurableExclusive(path.join(root, `child-${childToken}.binding.json`), binding);
+	const redactCommand = process.env[MANAGED_OWNER_REDACT_COMMAND_ENV] === "1";
+	const binding: ManagedOwnerBinding | null = redactCommand
+		? null
+		: {
+				schema_version: 2,
+				generation,
+				session_id: sessionId,
+				run_id: runId,
+				endpoint_incarnation: incarnation,
+				child_token: childToken,
+				command,
+				command_sha256: commandDigest(command),
+				supervisor_pid: process.pid,
+				supervisor_start_time: supervisorStartTime,
+				created_at: new Date().toISOString(),
+			};
+	if (binding) await writeDurableExclusive(path.join(root, `child-${childToken}.binding.json`), binding);
+	const childEnvironment: NodeJS.ProcessEnv = { ...process.env, [MANAGED_OWNER_CHILD_TOKEN_ENV]: childToken };
+	delete childEnvironment[MANAGED_OWNER_COMMAND_ENV];
+	delete childEnvironment[MANAGED_OWNER_REDACT_COMMAND_ENV];
 	const child = Bun.spawn({
 		cmd: command,
 		stdin: "inherit",
 		stdout: "inherit",
 		stderr: "inherit",
-		env: { ...process.env, [MANAGED_OWNER_CHILD_TOKEN_ENV]: childToken },
+		env: childEnvironment,
 	});
 	const childStartTime = await managedOwnerProcessProvenance(child.pid);
 	if (!childStartTime) throw new Error("managed_owner_child_start_time_unavailable");
@@ -167,24 +175,26 @@ export async function runManagedOwnerSupervisor(): Promise<void> {
 	if (!childProcess) {
 		const exitCode = await child.exited;
 		if (child.signalCode === "SIGABRT") {
-			const receipt: ManagedOwnerSigabrtReceipt = {
-				schema_version: 2,
-				generation,
-				session_id: sessionId,
-				run_id: runId,
-				endpoint_incarnation: incarnation,
-				child_token: childToken,
-				command_sha256: binding.command_sha256,
-				supervisor_pid: process.pid,
-				supervisor_start_time: supervisorStartTime,
-				child_pid: child.pid,
-				child_start_time: childStartTime,
-				signal: "SIGABRT",
-				signal_number: 6,
-				exit_code: exitCode,
-				received_at: new Date().toISOString(),
-			};
-			await writeDurableExclusive(path.join(root, `sigabrt-${childToken}.receipt.json`), receipt);
+			if (binding) {
+				const receipt: ManagedOwnerSigabrtReceipt = {
+					schema_version: 2,
+					generation,
+					session_id: sessionId,
+					run_id: runId,
+					endpoint_incarnation: incarnation,
+					child_token: childToken,
+					command_sha256: binding.command_sha256,
+					supervisor_pid: process.pid,
+					supervisor_start_time: supervisorStartTime,
+					child_pid: child.pid,
+					child_start_time: childStartTime,
+					signal: "SIGABRT",
+					signal_number: 6,
+					exit_code: exitCode,
+					received_at: new Date().toISOString(),
+				};
+				await writeDurableExclusive(path.join(root, `sigabrt-${childToken}.receipt.json`), receipt);
+			}
 			process.exitCode = 134;
 			return;
 		}
@@ -246,24 +256,26 @@ export async function runManagedOwnerSupervisor(): Promise<void> {
 		});
 	}
 	if (child.signalCode === "SIGABRT") {
-		const receipt: ManagedOwnerSigabrtReceipt = {
-			schema_version: 2,
-			generation,
-			session_id: sessionId,
-			run_id: runId,
-			endpoint_incarnation: incarnation,
-			child_token: childToken,
-			command_sha256: binding.command_sha256,
-			supervisor_pid: process.pid,
-			supervisor_start_time: supervisorStartTime,
-			child_pid: child.pid,
-			child_start_time: childStartTime,
-			signal: "SIGABRT",
-			signal_number: 6,
-			exit_code: exitCode,
-			received_at: new Date().toISOString(),
-		};
-		await writeDurableExclusive(path.join(root, `sigabrt-${childToken}.receipt.json`), receipt);
+		if (binding) {
+			const receipt: ManagedOwnerSigabrtReceipt = {
+				schema_version: 2,
+				generation,
+				session_id: sessionId,
+				run_id: runId,
+				endpoint_incarnation: incarnation,
+				child_token: childToken,
+				command_sha256: binding.command_sha256,
+				supervisor_pid: process.pid,
+				supervisor_start_time: supervisorStartTime,
+				child_pid: child.pid,
+				child_start_time: childStartTime,
+				signal: "SIGABRT",
+				signal_number: 6,
+				exit_code: exitCode,
+				received_at: new Date().toISOString(),
+			};
+			await writeDurableExclusive(path.join(root, `sigabrt-${childToken}.receipt.json`), receipt);
+		}
 		process.exitCode = 134;
 		return;
 	}

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

@@ -39,6 +39,7 @@ const LOCK_ACQUIRE_RETRY_MS = 5;
 const LOCK_ACQUIRE_MAX_RETRY_MS = 100;
 const LOCK_ACQUIRE_TIMEOUT_MS = 2_000;
 const LOCK_STALE_MS = 30_000;
+const RELEASED_TRANSITION_GRACE_MS = 1_000;
 
 interface LockRetryBudget {
 	startedAt: number;
@@ -54,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);
@@ -77,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`
@@ -409,6 +414,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. */
@@ -464,6 +471,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,
@@ -1308,7 +1421,13 @@ async function acquireOwnerLock(
 		} catch {
 			throw error;
 		}
-		if (!validLockOwner(observed) || observed.released !== true) throw error;
+		if (!validLockOwner(observed)) throw error;
+		if (observed.released !== true) {
+			if (await lockOwnerIsAlive(observed)) throw error;
+			const removed = exactUnlinkOwnerRecord(file, current, quarantineName);
+			if (removed !== "removed" && removed !== "absent") throw error;
+			return await createOwnerLock(file, owner, quarantineName);
+		}
 		try {
 			return await rewriteHeldOwnerRecord(file, current, owner);
 		} catch (error) {
@@ -1330,7 +1449,10 @@ async function acquireOwnerLock(
  *
  * Stale-owner reclaim still uses the native identity-bound detach protocol because no live
  * owner or transition claim can vouch for that pathname. A mismatch here likewise leaves a
- * successor strictly alone.
+ * successor strictly alone. A released tombstone is reclaimable on every platform when its
+ * owner host is this installation and the transition directory is proven empty and unchanged:
+ * the tombstone is the release marker, while the directory generation binds that marker to
+ * the exact claim that release failed to remove.
  */
 async function releaseOwnerLock(file: string, held: LockOwnerSnapshot): Promise<void> {
 	let owner: unknown;
@@ -1378,6 +1500,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"
@@ -1416,7 +1539,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";
 }
 
 /**
@@ -1548,14 +1672,18 @@ async function releaseTransitionClaim(
 	}
 }
 
-async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName: string): Promise<void> {
-	const stat = await fs.lstat(transitionDir).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,
@@ -1563,12 +1691,78 @@ async function reclaimStaleTransitionClaim(transitionDir: string, quarantineName
 			},
 			quarantineName,
 		);
-		return;
+		return reclaimed === "owner_removed";
 	}
 	if (!stat.isDirectory()) throw new SessionStateLockUnavailableError();
-	// No portable operation can atomically prove that this directory + sibling
-	// sidecar are still the dead claim two concurrent reclaimers inspected. A
-	// crashed atomic claim therefore stays fail-closed for explicit recovery.
+	const ownerSnapshot = await captureRegularLockOwner(`${transitionDir}.owner`);
+	if (!ownerSnapshot) return false;
+	let owner: unknown;
+	try {
+		owner = JSON.parse(ownerSnapshot.bytes);
+	} catch {
+		return false;
+	}
+	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 false;
+		const currentHost = await currentOwnerHostId();
+		const legacyHost = await currentLegacyOwnerHostId();
+		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 false;
+	const captured = nativeSessionStateLock().snapshotDirectoryTree(nativePath);
+	if (!captured.ok || !captured.snapshot) return false;
+	const root = captured.snapshot.entries.find(entry => entry.relativePath === "");
+	if (
+		!root ||
+		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 false;
+	if (captured.snapshot.entries.length !== 1) return false;
+	const removed = nativeSessionStateLock().exactRemoveDirectoryTree(nativePath, captured.snapshot);
+	if (removed.ok || removed.code === "not_found") {
+		exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
+		return removed.ok;
+	}
+	if (
+		removed.code === "cleanup_pending" &&
+		removed.payloadDurable === true &&
+		removed.detachedPath === `${nativePath}.removing` &&
+		removed.retainedSuccessorPath === undefined &&
+		removed.retainedUnknownPath === undefined &&
+		removed.retainedPlaceholderPath === undefined
+	) {
+		// The captured claim is proven empty, so the native detach receipt leaves an
+		// empty directory at detachedPath. Remove that exact directory directly: calling
+		// the detach primitive again would deterministically create a second `.removing`
+		// collision on POSIX. rmdir never follows a directory's contents and refuses if a
+		// successor populated the detached path.
+		await removeTransitionDir(removed.detachedPath);
+		exactUnlinkOwnerRecord(`${transitionDir}.owner`, ownerSnapshot, quarantineName);
+		return true;
+	}
+	throw new SessionStateLockUnavailableError(
+		new Error(`Stale transition claim could not be reclaimed (${removed.code ?? "unknown"}).`),
+	);
 }
 
 /** Run one pathname transition under an atomic `mkdir`/`rmdir` claim. */
@@ -1828,7 +2022,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;