@gajae-code/coding-agent 0.4.5 → 0.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.4.5",
+	"version": "0.5.1",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.4.5",
-		"@gajae-code/agent-core": "0.4.5",
-		"@gajae-code/ai": "0.4.5",
-		"@gajae-code/natives": "0.4.5",
-		"@gajae-code/tui": "0.4.5",
-		"@gajae-code/utils": "0.4.5",
+		"@gajae-code/stats": "0.5.1",
+		"@gajae-code/agent-core": "0.5.1",
+		"@gajae-code/ai": "0.5.1",
+		"@gajae-code/natives": "0.5.1",
+		"@gajae-code/tui": "0.5.1",
+		"@gajae-code/utils": "0.5.1",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/async/job-manager.ts

@@ -13,6 +13,14 @@ export interface AsyncJob {
 	type: "bash" | "task";
 	status: "running" | "completed" | "failed" | "cancelled" | "paused";
 	startTime: number;
+
+	/**
+	 * Wall-clock ms when the job left the `running` state (completed, failed,
+	 * cancelled, or paused). Undefined while running. Frozen on the first
+	 * terminal/pause transition so elapsed-time renderers stop counting once a
+	 * job is no longer active instead of growing forever against `Date.now()`.
+	 */
+	endTime?: number;
 	label: string;
 	abortController: AbortController;
 	promise: Promise<void>;
@@ -28,6 +36,16 @@ export interface AsyncJob {
 	ownerId?: string;
 }
 
+/**
+ * Elapsed wall-clock ms for a job, frozen once it stops running. While the job
+ * is active (`endTime` undefined) this counts against `now`; after it stops it
+ * returns the fixed `endTime - startTime` span so status renderers do not keep
+ * incrementing a completed job's timer.
+ */
+export function jobElapsedMs(job: Pick<AsyncJob, "startTime" | "endTime">, now: number = Date.now()): number {
+	return Math.max(0, (job.endTime ?? now) - job.startTime);
+}
+
 export interface AsyncJobMetadata {
 	subagent?: {
 		id: string;
@@ -80,6 +98,12 @@ export interface SubagentRecord {
 	/** False for ephemeral sessions (no persistent artifacts dir). */
 	resumable: boolean;
 	queued?: { ownerId?: string; seq: number; message?: string; createdAt: number };
+	/** Resolved model the subagent was asked to use, e.g. "openai-codex/gpt-5.5". */
+	requestedModel?: string;
+	/** Model actually used after auth fallback (#985); equals requestedModel when no fallback. */
+	effectiveModel?: string;
+	/** True when the requested model lacked credentials and the subagent fell back to the parent model. */
+	modelFellBack?: boolean;
 }
 
 /** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
@@ -368,6 +392,7 @@ export class AsyncJobManager {
 					// delivery and no eviction scheduling: a paused subagent stays
 					// listed and resumable from its sessionFile.
 					job.status = "paused";
+					this.#freezeEndTime(job);
 					if (outcome.note) job.resultText = outcome.note;
 					this.#markRecordPaused(id);
 					this.#drainResumeQueue();
@@ -375,6 +400,7 @@ export class AsyncJobManager {
 				}
 
 				job.status = "completed";
+				this.#freezeEndTime(job);
 				job.resultText = outcome.text;
 				this.#enqueueDelivery(id, outcome.text);
 				this.#runLifecycle(id, "terminal");
@@ -393,6 +419,7 @@ export class AsyncJobManager {
 				this.#runLifecycle(id, "terminal");
 				const errorText = error instanceof Error ? error.message : String(error);
 				job.status = "failed";
+				this.#freezeEndTime(job);
 				job.errorText = errorText;
 				this.#enqueueDelivery(id, errorText);
 				this.#scheduleEviction(id);
@@ -428,10 +455,22 @@ export class AsyncJobManager {
 		if (job.status !== "running") return false;
 		this.#runLifecycle(id, "cancel");
 		job.status = "cancelled";
+		this.#freezeEndTime(job);
 		job.abortController.abort();
 		return true;
 	}
 
+	/**
+	 * Freeze the wall-clock instant a job stopped running. Idempotent: the
+	 * first stop (completed/failed/cancelled/paused) wins so elapsed-time
+	 * renderers report a stable duration instead of counting against
+	 * `Date.now()` forever. A resumed subagent registers a brand-new job with
+	 * its own `startTime`, so a paused job's frozen `endTime` is never reused.
+	 */
+	#freezeEndTime(job: AsyncJob): void {
+		job.endTime ??= Date.now();
+	}
+
 	#runLifecycle(jobId: string, phase: "cancel" | "terminal" | "evict"): void {
 		const fired = this.#lifecyclePhases.get(jobId) ?? new Set<"cancel" | "terminal" | "evict">();
 		if (fired.has(phase)) return;
@@ -503,6 +542,18 @@ export class AsyncJobManager {
 		this.#subagentRecords.set(record.subagentId, record);
 	}
 
+	/** Patch model metadata onto an existing subagent record (best-effort; no-op if unknown). */
+	updateSubagentModel(
+		subagentId: string,
+		model: { requestedModel?: string; effectiveModel?: string; modelFellBack?: boolean },
+	): void {
+		const record = this.#subagentRecords.get(subagentId);
+		if (!record) return;
+		record.requestedModel = model.requestedModel;
+		record.effectiveModel = model.effectiveModel;
+		record.modelFellBack = model.modelFellBack;
+	}
+
 	getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined {
 		const rec = this.#subagentRecords.get(subagentId.trim());
 		if (!rec) return undefined;
@@ -978,6 +1029,7 @@ export class AsyncJobManager {
 		for (const job of this.getRunningJobs(filter)) {
 			this.#runLifecycle(job.id, "cancel");
 			job.status = "cancelled";
+			this.#freezeEndTime(job);
 			job.abortController.abort();
 			this.#scheduleEviction(job.id);
 		}

package/src/cli/args.ts

@@ -30,6 +30,7 @@ export interface Args {
 	mode?: Mode;
 	noSession?: boolean;
 	sessionDir?: string;
+	rpcListen?: string;
 	providerSessionId?: string;
 	fork?: string;
 	models?: string[];
@@ -145,6 +146,8 @@ export function parseArgs(args: string[]): Args {
 			result.noSession = true;
 		} else if (arg === "--session-dir" && i + 1 < args.length) {
 			result.sessionDir = args[++i];
+		} else if (arg === "--listen" && i + 1 < args.length) {
+			result.rpcListen = args[++i];
 		} else if (arg === "--models" && i + 1 < args.length) {
 			result.models = args[++i].split(",").map(s => s.trim());
 		} else if (arg === "--no-tools") {

package/src/cli/auth-broker-cli.ts

@@ -70,6 +70,7 @@ const CALLBACK_PORTS: Record<string, number> = {
 	"google-antigravity": 51121,
 	"gitlab-duo": 8080,
 	xai: 56121,
+	"grok-build": 56121,
 };
 
 function getTokenFilePath(): string {

package/src/cli/list-models.ts

@@ -5,7 +5,12 @@ import { type Api, getSupportedEfforts, type Model } from "@gajae-code/ai";
 import { fuzzyFilter } from "@gajae-code/tui";
 import { formatNumber } from "@gajae-code/utils";
 import type { ModelRegistry } from "../config/model-registry";
-import { discoverAndLoadExtensions, loadExtensions } from "../extensibility/extensions";
+import {
+	discoverAndLoadExtensions,
+	type ExtensionFactory,
+	loadExtensionFromFactory,
+	loadExtensions,
+} from "../extensibility/extensions";
 import { EventBus } from "../utils/event-bus";
 
 interface ProviderRow {
@@ -137,6 +142,8 @@ export interface RunListModelsOptions {
 	cwd: string;
 	/** CLI-supplied extension paths (e.g. from `-e <path>`). */
 	additionalExtensionPaths?: string[];
+	/** In-process extension factories to load without filesystem discovery. */
+	extensionFactories?: Array<{ factory: ExtensionFactory; name: string }>;
 	/** Extension paths configured under `extensions:` in user settings. */
 	settingsExtensions?: string[];
 	/** Disabled extension ids from settings (`disabledExtensions`). */
@@ -159,6 +166,7 @@ export async function runListModelsCommand(options: RunListModelsOptions): Promi
 		modelRegistry,
 		cwd,
 		additionalExtensionPaths = [],
+		extensionFactories = [],
 		settingsExtensions = [],
 		disabledExtensionIds = [],
 		disableExtensionDiscovery = false,
@@ -174,6 +182,10 @@ export async function runListModelsCommand(options: RunListModelsOptions): Promi
 				eventBus,
 				disabledExtensionIds,
 			);
+	for (const { factory, name } of extensionFactories) {
+		const extension = await loadExtensionFromFactory(factory, cwd, eventBus, extensionsResult.runtime, name);
+		extensionsResult.extensions.push(extension);
+	}
 
 	for (const { path: extPath, error } of extensionsResult.errors) {
 		process.stderr.write(`Failed to load extension: ${extPath}: ${error}\n`);

package/src/cli.ts

@@ -5,11 +5,15 @@
  * lightweight CLI runner from pi-utils.
  */
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@gajae-code/utils/cli";
-import { APP_NAME, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
+import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
-		`error: Bun runtime must be >= ${MIN_BUN_VERSION} (found v${Bun.version}). Please upgrade: bun upgrade\n`,
+		formatBunRuntimeError({
+			currentVersion: Bun.version,
+			minVersion: MIN_BUN_VERSION,
+			execPath: process.execPath,
+		}),
 	);
 	process.exit(1);
 }
@@ -28,6 +32,7 @@ const commands: CommandEntry[] = [
 	{ name: "coordinator", load: () => import("./commands/coordinator").then(m => m.default) },
 	{ name: "team", load: () => import("./commands/team").then(m => m.default) },
 	{ name: "ultragoal", load: () => import("./commands/ultragoal").then(m => m.default) },
+	{ name: "gc", load: () => import("./commands/gc").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
 	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
@@ -130,8 +135,8 @@ class RootHelpCommand extends Command {
 		`# Launch in a sibling git worktree\n  ${APP_NAME} --worktree`,
 		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
 		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
-		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-standard`,
-		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencode-go-pro --default`,
+		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-medium`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --default`,
 		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
 	];
 	static strict = false;

package/src/commands/gc.ts

@@ -0,0 +1,22 @@
+import { Command, Flags } from "@gajae-code/utils/cli";
+import { runGjcGcCommand } from "../gjc-runtime/gc-runtime";
+
+export default class Gc extends Command {
+	static description = "Garbage-collect stale GJC session/PID records (dry-run by default)";
+	static strict = false;
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+		prune: Flags.boolean({ description: "Remove stale records (default: report only)", default: false }),
+		force: Flags.boolean({ description: "Alias for --prune (eligible records only)", default: false }),
+		"dry-run": Flags.boolean({ description: "Force report-only mode", default: false }),
+	};
+
+	static examples = ["gjc gc", "gjc gc --json", "gjc gc --prune", "gjc gc --prune --json"];
+
+	async run(): Promise<void> {
+		const result = await runGjcGcCommand(this.argv, process.cwd(), process.env);
+		if (result.stdout) process.stdout.write(result.stdout);
+		if (result.stderr) process.stderr.write(result.stderr);
+		process.exitCode = result.status;
+	}
+}

package/src/commands/harness.ts

@@ -11,16 +11,18 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { resolveGjcTmuxCommand, sanitizeTmuxToken } from "../gjc-runtime/tmux-common";
 import { classifyRecovery } from "../harness-control-plane/classifier";
 import { callEndpoint, EndpointUnreachableError } from "../harness-control-plane/control-endpoint";
-import { type ResolvedOwner, RuntimeOwner, resolveOwner } from "../harness-control-plane/owner";
+import { type ResolvedOwner, RuntimeOwner, resolveOwner, resolveOwnerLive } from "../harness-control-plane/owner";
 import { preserveDirtyWorktree } from "../harness-control-plane/preserve";
+import { RECEIPT_SPOOL_DIR_ENV } from "../harness-control-plane/receipt-spool";
 import { buildReceipt, requiresVanishBeforeAction, type VanishEvidence } from "../harness-control-plane/receipts";
 import { GajaeCodeRpc } from "../harness-control-plane/rpc-adapter";
 import { classifyLeaseStatus, readLease } from "../harness-control-plane/session-lease";
-import { buildResponse, buildStateView } from "../harness-control-plane/state-machine";
+import { buildResponse, buildStateView, submitUnavailableReason } from "../harness-control-plane/state-machine";
 import {
 	canonicalWorkspacePath,
 	generateSessionId,
@@ -513,6 +515,9 @@ export default class Harness extends Command {
 		cursor: Flags.string({ description: "Event cursor for events --follow (exclusive)", default: "0" }),
 		follow: Flags.boolean({ description: "Tail the owner-written event log", default: false }),
 		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: true }),
+		"receipt-spool-dir": Flags.string({
+			description: "Append persisted ReceiptEnvelope records to spool.jsonl under this directory",
+		}),
 	};
 
 	static examples = [
@@ -527,6 +532,11 @@ export default class Harness extends Command {
 		const verb = String(args.verb);
 		let root = resolveHarnessRoot();
 		try {
+			const receiptSpoolDir = flags["receipt-spool-dir"];
+			if (receiptSpoolDir !== undefined) {
+				if (!receiptSpoolDir.trim()) throw new Error("receipt_spool_dir_empty");
+				process.env[RECEIPT_SPOOL_DIR_ENV] = path.resolve(receiptSpoolDir.trim());
+			}
 			const input = parseInput(flags.input);
 			const promptFile = flags["prompt-file"];
 			if (promptFile !== undefined) {
@@ -676,6 +686,9 @@ export default class Harness extends Command {
 		}
 		const sessionName = deterministicHarnessTmuxSessionName(sessionId);
 		const envAssignments = [`GJC_HARNESS_STATE_ROOT=${shellQuote(root)}`];
+		if (process.env[RECEIPT_SPOOL_DIR_ENV]) {
+			envAssignments.push(`${RECEIPT_SPOOL_DIR_ENV}=${shellQuote(process.env[RECEIPT_SPOOL_DIR_ENV])}`);
+		}
 		if (process.env.GJC_HARNESS_RPC_COMMAND) {
 			envAssignments.push(`GJC_HARNESS_RPC_COMMAND=${shellQuote(process.env.GJC_HARNESS_RPC_COMMAND)}`);
 		}
@@ -715,6 +728,9 @@ export default class Harness extends Command {
 			env: {
 				...process.env,
 				GJC_HARNESS_STATE_ROOT: root,
+				...(process.env[RECEIPT_SPOOL_DIR_ENV]
+					? { [RECEIPT_SPOOL_DIR_ENV]: process.env[RECEIPT_SPOOL_DIR_ENV] }
+					: {}),
 				...(process.env.GJC_HARNESS_TEST_NODE_MODULES
 					? { GJC_HARNESS_TEST_NODE_MODULES: process.env.GJC_HARNESS_TEST_NODE_MODULES }
 					: {}),
@@ -878,7 +894,9 @@ export default class Harness extends Command {
 	): Promise<boolean> {
 		const owner = await resolveOwner(root, sessionId);
 		if (!owner.live || !owner.socketPath) return false;
+		const priorSpoolDir = input[RECEIPT_SPOOL_DIR_ENV];
 		try {
+			if (process.env[RECEIPT_SPOOL_DIR_ENV]) input[RECEIPT_SPOOL_DIR_ENV] = process.env[RECEIPT_SPOOL_DIR_ENV];
 			const res = (await callEndpoint(owner.socketPath, { verb, input })) as { ok?: boolean };
 			writeJson(res);
 			if (res?.ok === false) process.exitCode = 1;
@@ -886,6 +904,9 @@ export default class Harness extends Command {
 		} catch (error) {
 			if (error instanceof EndpointUnreachableError) return false;
 			throw error;
+		} finally {
+			if (priorSpoolDir === undefined) delete input[RECEIPT_SPOOL_DIR_ENV];
+			else input[RECEIPT_SPOOL_DIR_ENV] = priorSpoolDir;
 		}
 	}
 
@@ -927,10 +948,14 @@ export default class Harness extends Command {
 		let observation = input.observation as Partial<Observation> | undefined;
 		let stateView: SessionState | null = null;
 		const sessionId = flagSession ?? (typeof input.sessionId === "string" ? input.sessionId : undefined);
+		// Session-backed classify derives owner liveness from the same lease/socket probe observe
+		// uses for routing, so a live (e.g. manual) owner is never misread as vanished/restart-clean.
+		let ownerLive = false;
 		if (sessionId) {
 			stateView = await loadState(root, sessionId);
+			ownerLive = await resolveOwnerLive(root, sessionId);
 			if (!observation) {
-				const built = await buildObservation(root, stateView, ownerLiveFor(stateView));
+				const built = await buildObservation(root, stateView, ownerLive);
 				observation = built.observation;
 				stateView = await markVanishedOwnerBlocked(
 					root,
@@ -954,7 +979,7 @@ export default class Harness extends Command {
 		const decision = classifyRecovery({ observation: full, retryBudget: budget });
 		if (stateView) {
 			writeJson(
-				buildResponse(stateView, ownerLiveFor(stateView), {
+				buildResponse(stateView, ownerLive, {
 					decision,
 					observation: { ...full, lifecycle: stateView.lifecycle },
 				}),
@@ -978,8 +1003,21 @@ export default class Harness extends Command {
 
 	async #submit(root: string, input: Record<string, unknown>, flagSession: string | undefined): Promise<void> {
 		const sessionId = requireSessionId(input, flagSession);
-		if (await this.#tryOwnerRoute(root, sessionId, "submit", { ...input, sessionId })) return;
 		let state = await loadState(root, sessionId);
+		const noOwnerGate = submitUnavailableReason(state.lifecycle, false);
+		if (!noOwnerGate || noOwnerGate === "owner-not-live") {
+			if (await this.#tryOwnerRoute(root, sessionId, "submit", { ...input, sessionId })) return;
+			state = await loadState(root, sessionId);
+		}
+		const blockedByOwnerLiveness = state.blockers.some(
+			blocker => isOwnerLivenessBlocker(blocker) || blocker === OWNER_STARTUP_BLOCKER,
+		);
+		const lifecycleGate = submitUnavailableReason(state.lifecycle, false);
+		if (lifecycleGate && lifecycleGate !== "owner-not-live" && !blockedByOwnerLiveness) {
+			writeJson(buildResponse(state, false, { accepted: false, submitted: false, reason: lifecycleGate }, false));
+			process.exitCode = 1;
+			return;
+		}
 		// No live owner: submission is blocked (never echoed-as-accepted). Surface owner exit
 		// evidence + explicit recovery guidance so the caller is not left with a bare gate.
 		const ownerExit = await buildOwnerExitEvidence(root, state);

package/src/commands/launch.ts

@@ -142,8 +142,8 @@ export default class Index extends Command {
 		`# Launch in a sibling git worktree\n  ${APP_NAME} --worktree`,
 		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
 		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
-		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-standard`,
-		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencode-go-pro --default`,
+		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-medium`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --default`,
 		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
 	];
 

package/src/commands/session.ts

@@ -18,7 +18,9 @@ function writeText(lines: string[]): void {
 function writeJsonFailure(error: unknown): void {
 	const message = error instanceof Error ? error.message : String(error);
 	const [reason = "session_error"] = message.split(":");
-	writeJson({ ok: false, reason });
+	const hintIndex = message.indexOf(" — ");
+	const detail = hintIndex >= 0 ? message.slice(hintIndex + " — ".length).trim() : "";
+	writeJson(detail ? { ok: false, reason, detail } : { ok: false, reason });
 }
 
 interface SessionJsonDto {

package/src/config/file-lock-gc.ts

@@ -0,0 +1,181 @@
+/**
+ * GC adapter for config file-locks (`<file>.lock` dirs holding `{pid, timestamp}`).
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getAgentDir, getConfigRootDir, isEnoent } from "@gajae-code/utils";
+import type {
+	GcCollectResult,
+	GcContext,
+	GcError,
+	GcPruneOutcome,
+	GcRecord,
+	GcStoreAdapter,
+} from "../gjc-runtime/gc-runtime";
+import { gcPidStatusLabel } from "../gjc-runtime/gc-runtime";
+import { resolveReceiptSpoolDir } from "../harness-control-plane/receipt-spool";
+import { readFileLockInfoForGc, removeFileLockDirForGc } from "./file-lock";
+
+const MAX_WALK_DEPTH = 6;
+const MAX_WALK_ENTRIES = 20_000;
+
+// High-cardinality, lock-free subtrees we never descend into. `.lock` dirs are
+// created next to config files, never inside these.
+const PRUNED_DIR_NAMES = new Set(["sessions", "node_modules", ".git", "blobs", "artifacts", "receipts", "events"]);
+
+interface WalkState {
+	entries: number;
+	truncated: boolean;
+}
+
+// Global, env-aware GJC lock roots. Per the approved scope this covers the
+// user config root, the agent dir (honors GJC_CODING_AGENT_DIR), and the
+// configured receipt-spool dir — NOT the invocation cwd's project `.gjc`.
+function knownFileLockRoots(ctx: GcContext): string[] {
+	const roots = [getConfigRootDir(), getAgentDir()];
+	const spoolDir = resolveReceiptSpoolDir(ctx.env);
+	if (spoolDir) roots.push(spoolDir);
+	return Array.from(new Set(roots.map(root => path.resolve(root))));
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function keptMalformedRecord(lockDir: string): GcRecord {
+	return {
+		store: "file_locks",
+		id: lockDir,
+		path: lockDir,
+		pid_status: "none",
+		status: "malformed",
+		stale: false,
+		removable: false,
+		action: "none",
+		reason: "missing_or_malformed_file_lock_info",
+	};
+}
+
+async function collectLockRecord(lockDir: string, ctx: GcContext): Promise<GcRecord> {
+	const info = await readFileLockInfoForGc(lockDir);
+	if (!info) return keptMalformedRecord(lockDir);
+
+	const probeResult = ctx.probe(info.pid);
+	const pidStatus = gcPidStatusLabel(probeResult);
+	const removable = probeResult.status === "dead";
+
+	return {
+		store: "file_locks",
+		id: lockDir,
+		path: lockDir,
+		pid: info.pid,
+		pid_status: pidStatus,
+		status: pidStatus,
+		stale: removable,
+		removable,
+		action: "none",
+		reason: removable ? "file_lock_owner_pid_dead" : `file_lock_owner_pid_${pidStatus}`,
+		detail: `timestamp=${info.timestamp}`,
+	};
+}
+
+async function walkForLockDirs(
+	dir: string,
+	depth: number,
+	state: WalkState,
+	lockDirs: Set<string>,
+	errors: GcError[],
+): Promise<void> {
+	if (state.entries >= MAX_WALK_ENTRIES) {
+		state.truncated = true;
+		return;
+	}
+
+	let stat: Awaited<ReturnType<typeof fs.lstat>>;
+	try {
+		stat = await fs.lstat(dir);
+	} catch (error) {
+		if (isEnoent(error)) return;
+		errors.push({ store: "file_locks", scope: dir, message: errorMessage(error) });
+		return;
+	}
+
+	state.entries++;
+	if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+
+	if (path.basename(dir).endsWith(".lock")) {
+		lockDirs.add(dir);
+		return;
+	}
+
+	if (depth >= MAX_WALK_DEPTH) return;
+
+	let entries: string[];
+	try {
+		entries = await fs.readdir(dir);
+	} catch (error) {
+		if (isEnoent(error)) return;
+		errors.push({ store: "file_locks", scope: dir, message: errorMessage(error) });
+		return;
+	}
+
+	for (const entry of entries) {
+		if (state.entries >= MAX_WALK_ENTRIES) {
+			state.truncated = true;
+			return;
+		}
+		if (PRUNED_DIR_NAMES.has(entry)) continue;
+		await walkForLockDirs(path.join(dir, entry), depth + 1, state, lockDirs, errors);
+	}
+}
+
+export const fileLocksGcAdapter: GcStoreAdapter = {
+	store: "file_locks",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcError[] = [];
+		const lockDirs = new Set<string>();
+		const state: WalkState = { entries: 0, truncated: false };
+
+		for (const root of knownFileLockRoots(ctx)) {
+			await walkForLockDirs(root, 0, state, lockDirs, errors);
+			if (state.truncated) break;
+		}
+
+		if (state.truncated) {
+			errors.push({
+				store: "file_locks",
+				scope: "discovery",
+				message: `file lock discovery capped at ${MAX_WALK_ENTRIES} entries`,
+			});
+		}
+
+		for (const lockDir of lockDirs) {
+			try {
+				records.push(await collectLockRecord(lockDir, ctx));
+			} catch (error) {
+				errors.push({ store: "file_locks", scope: lockDir, message: errorMessage(error) });
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		const lockDir = record.path ?? record.id;
+		const info = await readFileLockInfoForGc(lockDir);
+		if (!info) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+
+		const probeResult = ctx.probe(info.pid);
+		if (probeResult.status !== "dead") {
+			return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+		}
+
+		try {
+			await removeFileLockDirForGc(lockDir);
+			return { removed: true };
+		} catch (error) {
+			return { removed: false, error: errorMessage(error) };
+		}
+	},
+};

package/src/config/file-lock.ts

@@ -36,6 +36,20 @@ async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
 	}
 }
 
+/** @internal */
+export async function readFileLockInfoForGc(lockDir: string): Promise<{ pid: number; timestamp: number } | null> {
+	const info = await readLockInfo(lockDir);
+	if (!info) return null;
+	if (!Number.isFinite(info.pid) || info.pid <= 0) return null;
+	if (!Number.isFinite(info.timestamp)) return null;
+	return info;
+}
+
+/** @internal */
+export async function removeFileLockDirForGc(lockDir: string): Promise<void> {
+	await fs.rm(lockDir, { recursive: true, force: true });
+}
+
 function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);