@gajae-code/coding-agent 0.5.0 → 0.5.2

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") {
@@ -266,6 +269,8 @@ export function getExtraHelpText(): string {
   gjc session                  - List, inspect, create, remove, or attach tagged GJC-managed tmux sessions
   GJC_LAUNCH_POLICY           - Launch policy for --tmux startup: tmux or direct
   GJC_TMUX_SESSION            - Explicit tmux session name override for --tmux startup
+  GJC_TMUX_PROFILE            - Apply GJC tmux scroll/mouse/clipboard profile to --tmux sessions (set 0/off to skip)
+  GJC_MOUSE                   - Mouse-wheel scroll in --tmux sessions (set 0/off to let the host terminal scroll)
 
   For complete environment variable reference, see:
   ${chalk.dim("docs/environment-variables.md")}

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/fast-help.ts

@@ -54,6 +54,8 @@ export function getExtraHelpText(): string {
   gjc session                  - List, inspect, create, remove, or attach tagged GJC-managed tmux sessions
   GJC_LAUNCH_POLICY           - Launch policy for --tmux startup: tmux or direct
   GJC_TMUX_SESSION            - Explicit tmux session name override for --tmux startup
+  GJC_TMUX_PROFILE            - Apply GJC tmux scroll/mouse/clipboard profile to --tmux sessions (set 0/off to skip)
+  GJC_MOUSE                   - Mouse-wheel scroll in --tmux sessions (set 0/off to let the host terminal scroll)
 
   For complete environment variable reference, see:
   docs/environment-variables.md

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/setup-cli.ts

@@ -3,8 +3,11 @@
  *
  * Handles `gjc setup [component]` to install the normal defaults or optional feature dependencies.
  */
+
 import * as path from "node:path";
-import { $which, APP_NAME, getPythonEnvDir } from "@gajae-code/utils";
+import { createInterface } from "node:readline/promises";
+import { SqliteAuthCredentialStore } from "@gajae-code/ai";
+import { $which, APP_NAME, getAgentDbPath, getPythonEnvDir } from "@gajae-code/utils";
 import { $ } from "bun";
 import chalk from "chalk";
 import { installDefaultGjcDefinitions } from "../defaults/gjc-defaults";
@@ -14,6 +17,7 @@ import {
 	readGjcManagedCodexHooksStatus,
 } from "../hooks/codex-native-hooks-config";
 import { theme } from "../modes/theme/theme";
+import { discoverExternalCredentials, formatDiscoverySummary, importCredentials } from "../setup/credential-import";
 import {
 	formatHermesSetupResult,
 	type HermesSetupFlags,
@@ -27,7 +31,7 @@ import {
 	parseProviderCompatibility,
 } from "../setup/provider-onboarding";
 
-export type SetupComponent = "defaults" | "hermes" | "hooks" | "provider" | "python" | "stt";
+export type SetupComponent = "credentials" | "defaults" | "hermes" | "hooks" | "provider" | "python" | "stt";
 
 export interface SetupCommandArgs {
 	component: SetupComponent;
@@ -57,10 +61,12 @@ export interface SetupCommandArgs {
 		gjcCommand?: string;
 		target?: string;
 		profileDir?: string;
+		yes?: boolean;
+		dryRun?: boolean;
 	};
 }
 
-const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
+const VALID_COMPONENTS: SetupComponent[] = ["credentials", "defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
 	return (
@@ -113,6 +119,10 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.smoke = true;
 		} else if (arg === "--install") {
 			flags.install = true;
+		} else if (arg === "--yes" || arg === "-y") {
+			flags.yes = true;
+		} else if (arg === "--dry-run") {
+			flags.dryRun = true;
 		} else if (arg === "--root") {
 			flags.root = [...(flags.root ?? []), args[++i] ?? ""];
 		} else if (arg === "--repo") {
@@ -243,6 +253,9 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "stt":
 			await handleSttSetup(cmd.flags);
 			break;
+		case "credentials":
+			await handleCredentialsSetup(cmd.flags);
+			break;
 	}
 }
 
@@ -472,6 +485,122 @@ async function handleSttSetup(flags: { json?: boolean; check?: boolean }): Promi
 		process.exit(1);
 	}
 }
+async function confirmImport(count: number): Promise<boolean> {
+	if (!process.stdin.isTTY) return false;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const answer = (await rl.question(`Import ${count} credential(s) into ${getAgentDbPath()}? [y/N] `))
+			.trim()
+			.toLowerCase();
+		return answer === "y" || answer === "yes";
+	} finally {
+		rl.close();
+	}
+}
+
+/**
+ * Discover existing Claude Code / Codex CLI credentials and import them into the
+ * gjc credential store after a redacted preview + confirmation. Falls back to
+ * manual-setup guidance when nothing importable is found.
+ */
+async function handleCredentialsSetup(flags: { json?: boolean; yes?: boolean; dryRun?: boolean }): Promise<void> {
+	const result = await discoverExternalCredentials();
+	const redactedPlan = {
+		importable: result.importable.map(c => ({
+			provider: c.provider,
+			kind: c.kind,
+			source: c.source,
+			identity: c.identity,
+			expiresAt: c.expiresAt,
+			redactedToken: c.redactedToken,
+		})),
+		skipped: result.skipped,
+		environment: result.environment,
+	};
+
+	if (result.importable.length === 0) {
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify({ ...redactedPlan, imported: [] })}\n`);
+			return;
+		}
+		for (const line of formatDiscoverySummary(result)) process.stdout.write(`  ${line}\n`);
+		process.stdout.write(
+			chalk.yellow(
+				`\nNo importable Claude/Codex credentials found. Continue with manual setup:\n` +
+					`  ${APP_NAME} setup provider   (add an API-compatible provider)\n` +
+					`  ${APP_NAME} (then /login)     (interactive OAuth/subscription login)\n`,
+			),
+		);
+		return;
+	}
+
+	if (!flags.json) {
+		process.stdout.write(chalk.bold("Discovered credentials (redacted):\n"));
+		for (const line of formatDiscoverySummary(result)) process.stdout.write(`  ${line}\n`);
+	}
+
+	if (flags.dryRun) {
+		if (flags.json) process.stdout.write(`${JSON.stringify({ ...redactedPlan, dryRun: true, imported: [] })}\n`);
+		else process.stdout.write(chalk.dim(`\nDry run — no credentials imported.\n`));
+		return;
+	}
+
+	const confirmed = flags.yes || (await confirmImport(result.importable.length));
+	if (!confirmed) {
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify({ ...redactedPlan, imported: [] })}\n`);
+			return;
+		}
+		process.stdout.write(chalk.dim(`\nImport cancelled. Re-run with --yes to import non-interactively.\n`));
+		return;
+	}
+
+	const store = await SqliteAuthCredentialStore.open(getAgentDbPath());
+	let summary: Awaited<ReturnType<typeof importCredentials>>;
+	try {
+		summary = await importCredentials(result.importable, (provider, credential) =>
+			store.upsertAuthCredentialForProvider(provider, credential),
+		);
+	} finally {
+		store.close();
+	}
+
+	if (flags.json) {
+		process.stdout.write(
+			`${JSON.stringify({
+				...redactedPlan,
+				imported: summary.imported.map(c => ({ provider: c.provider, kind: c.kind, source: c.source })),
+				failed: summary.failed.map(f => ({
+					provider: f.credential.provider,
+					source: f.credential.source,
+					error: f.error,
+				})),
+			})}\n`,
+		);
+		if (summary.failed.length > 0) process.exitCode = 1;
+		return;
+	}
+
+	for (const credential of summary.imported) {
+		process.stdout.write(
+			`${chalk.green(`${theme.status.success} imported`)} ${formatCredentialSummaryLine(credential)}\n`,
+		);
+	}
+	for (const failure of summary.failed) {
+		process.stdout.write(
+			`${chalk.red(`${theme.status.error} failed`)} ${failure.credential.provider} (${failure.credential.source}): ${failure.error}\n`,
+		);
+	}
+	if (summary.failed.length > 0) {
+		process.exitCode = 1;
+		return;
+	}
+	process.stdout.write(chalk.dim(`\nCredentials saved to ${getAgentDbPath()}\n`));
+}
+
+function formatCredentialSummaryLine(credential: { provider: string; kind: string; source: string }): string {
+	return `${credential.provider} · ${credential.kind} (from ${credential.source})`;
+}
 
 /**
  * Print setup command help.
@@ -489,6 +618,7 @@ ${chalk.bold("Components:")}
   provider  Optional: add a preset, OpenAI-compatible, or Anthropic-compatible API provider
   python    Optional: verify a Python 3 interpreter is reachable for code execution
   stt       Optional: install speech-to-text dependencies (openai-whisper, recording tools)
+  credentials Optional: import existing Claude Code / Codex CLI credentials
 
 
 ${chalk.bold("Provider example:")}
@@ -524,6 +654,8 @@ ${chalk.bold("Options:")}
   --mutation        Hermes MCP mutation classes: sessions,questions,reports,all
   --target          Hermes config file target for config-only install
   --profile-dir     Hermes profile directory for full setup install
+  --dry-run         Preview discovered credentials without importing (credentials)
+  -y, --yes         Import discovered credentials without an interactive prompt (credentials)
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} setup                  Install bundled GJC default workflow skills
@@ -536,5 +668,8 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup stt              Install speech-to-text dependencies
   ${APP_NAME} setup stt --check      Check if STT dependencies are available
   ${APP_NAME} setup python --check   Check if Python execution is available
+  ${APP_NAME} setup credentials      Discover & import existing Claude/Codex credentials
+  ${APP_NAME} setup credentials --dry-run  Preview importable credentials (redacted)
+  ${APP_NAME} setup credentials --yes      Import without an interactive prompt
 `);
 }

package/src/cli.ts

@@ -32,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) },

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

@@ -16,7 +16,7 @@ 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";
@@ -948,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,
@@ -975,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 },
 				}),

package/src/commands/setup.ts

@@ -5,7 +5,7 @@ import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { runSetupCommand, type SetupCommandArgs, type SetupComponent } from "../cli/setup-cli";
 import { initTheme } from "../modes/theme/theme";
 
-const COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
+const COMPONENTS: SetupComponent[] = ["credentials", "defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 export default class Setup extends Command {
 	static description = "Install GJC defaults or optional feature dependencies";
@@ -47,6 +47,8 @@ export default class Setup extends Command {
 		"api-key-env": Flags.string({ description: "Read provider API key from this environment variable" }),
 		model: Flags.string({ description: "Model id to add (repeat or comma-separate)", multiple: true }),
 		"models-path": Flags.string({ description: "Override models config path" }),
+		yes: Flags.boolean({ char: "y", description: "Import discovered credentials without an interactive prompt" }),
+		"dry-run": Flags.boolean({ description: "Preview discovered credentials without importing" }),
 	};
 
 	async run(): Promise<void> {
@@ -79,6 +81,8 @@ export default class Setup extends Command {
 				gjcCommand: flags["gjc-command"],
 				target: flags.target,
 				profileDir: flags["profile-dir"],
+				yes: flags.yes,
+				dryRun: flags["dry-run"],
 			},
 		};
 		await initTheme();

package/src/commands/ultragoal.ts

@@ -16,12 +16,14 @@ export default class Ultragoal extends Command {
 	static delegateHelp = true;
 
 	async run(): Promise<void> {
+		const isReviewStart = this.argv.includes("review") && this.argv.includes("review-start");
 		const shouldActivateGoalMode = isUltragoalCreateGoalsInvocation(this.argv);
 		const result = await runNativeUltragoalCommand(this.argv);
 		if (result.stdout) process.stdout.write(result.stdout);
 		if (result.stderr) process.stderr.write(result.stderr);
 		process.exitCode = result.status;
-		if (result.status !== 0 || !shouldActivateGoalMode) return;
+		if (result.status !== 0 || (!shouldActivateGoalMode && !isReviewStart)) return;
+		if (isReviewStart && !result.createdReviewPlan && (result.reviewBlockerGoalIds?.length ?? 0) === 0) return;
 
 		const cwd = process.cwd();
 		const { objective, goalsPath } = await readUltragoalGjcObjective(cwd);

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

@@ -0,0 +1,193 @@
+/**
+ * GC adapter for config file-locks (`<file>.lock` dirs holding `{pid, timestamp}`).
+ */
+
+import type { Stats } from "node:fs";
+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: Stats;
+	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" };
+		}
+
+		// Fail-closed owner-token guard (#606): we observed `info` (pid+timestamp)
+		// dead, but a fresh owner can reclaim a stale lock dir at this same path
+		// between the probe above and the unlink below. Pass the exact owner token
+		// so removal re-verifies the on-disk identity under the unlink and refuses
+		// to delete a recreated LIVE lock (TOCTOU).
+		try {
+			const removal = await removeFileLockDirForGc(lockDir, info);
+			if (removal === "owner_changed") {
+				return { removed: false, skipped: "file_lock_owner_changed_before_delete" };
+			}
+			if (removal === "missing") {
+				return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+			}
+			return { removed: true };
+		} catch (error) {
+			return { removed: false, error: errorMessage(error) };
+		}
+	},
+};