@gajae-code/coding-agent 0.15.4 → 0.15.6

package/src/gjc-runtime/gc-runtime.ts

@@ -31,7 +31,12 @@ import {
 	removeCanonicalBlob,
 } from "../session/blob-store";
 import { FileSessionStorage, probeSessionRetirement, retireSessionTranscript } from "../session/session-storage";
-
+import {
+	collectEmptyDeleteReceipts,
+	type EmptyDeleteGcRecord,
+	type EmptyDeleteGcReport,
+	runEmptyDeleteGc,
+} from "./empty-delete-gc";
 import { buildGcReportText } from "./gc-render";
 import { collectSessionScopeUsage, type GcSessionScopeUsage, shouldReportSessionScope } from "./gc-session-scope";
 
@@ -168,6 +173,7 @@ export interface GcReport {
 	 * PID-liveness axis above is unchanged by its absence or presence.
 	 */
 	disk?: GcDiskReport;
+	empty_delete_receipts?: EmptyDeleteGcReport;
 }
 
 export interface GcRunResult {
@@ -274,9 +280,11 @@ interface ParsedGcArgs {
 	json: boolean;
 	prune: boolean;
 	repairSessionIndex: boolean;
-	/** Opt-in second axis: report (and with `--prune`, reclaim) on-disk retention. */
 	disk: boolean;
 	help: boolean;
+	emptyDeleteReceipts: boolean;
+	emptyDeleteRoots: string[];
+	emptyDeleteManifests: string[];
 }
 
 class GcUsageError extends Error {}
@@ -286,10 +294,13 @@ function parseGcArgs(argv: string[]): ParsedGcArgs {
 	let prune = false;
 	let repairSessionIndex = false;
 	let disk = false;
-
 	let dryRun = false;
 	let help = false;
-	for (const arg of argv) {
+	let emptyDeleteReceipts = false;
+	const emptyDeleteRoots: string[] = [];
+	const emptyDeleteManifests: string[] = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]!;
 		switch (arg) {
 			case "--json":
 			case "-j":
@@ -305,7 +316,6 @@ function parseGcArgs(argv: string[]): ParsedGcArgs {
 			case "--disk":
 				disk = true;
 				break;
-
 			case "--dry-run":
 				dryRun = true;
 				break;
@@ -313,15 +323,34 @@ function parseGcArgs(argv: string[]): ParsedGcArgs {
 			case "-h":
 				help = true;
 				break;
+			case "--empty-delete-receipts":
+				emptyDeleteReceipts = true;
+				break;
+			case "--root": {
+				const value = argv[++i];
+				// A following option token is a missing operand, not a root path. Any
+				// dash-prefixed value is rejected (short flags like -j included); spell a
+				// genuinely dash-prefixed path as ./-name so it is unambiguous.
+				if (!value || value.startsWith("-")) throw new GcUsageError("missing_root");
+				emptyDeleteRoots.push(value);
+				break;
+			}
+			case "--manifest": {
+				const value = argv[++i];
+				if (!value || value.startsWith("-")) throw new GcUsageError("missing_manifest");
+				emptyDeleteManifests.push(value);
+				break;
+			}
 			default:
 				throw new GcUsageError(`unknown_flag:${arg}`);
 		}
 	}
 	if (repairSessionIndex && prune) throw new GcUsageError("repair_session_index_cannot_combine_with_prune");
+	if (!emptyDeleteReceipts && (emptyDeleteRoots.length > 0 || emptyDeleteManifests.length > 0))
+		throw new GcUsageError("empty_delete_operands_require_feature_flag");
 	if (repairSessionIndex && dryRun) throw new GcUsageError("repair_session_index_cannot_combine_with_dry_run");
-	// Explicit --dry-run always wins over --prune/--force.
 	if (dryRun) prune = false;
-	return { json, prune, repairSessionIndex, disk, help };
+	return { json, prune, repairSessionIndex, disk, help, emptyDeleteReceipts, emptyDeleteRoots, emptyDeleteManifests };
 }
 
 /**
@@ -404,6 +433,7 @@ export async function collectGcReport(adapters: GcStoreAdapter[], ctx: GcContext
 export function computeExitCode(report: GcReport): number {
 	if (report.errors.length > 0) return 1;
 	if (!report.dry_run && report.counts.failed > 0) return 1;
+	if (report.empty_delete_receipts?.errors.length) return 1;
 	if (report.disk) {
 		if (report.disk.errors.length > 0) return 1;
 		if (!report.disk.dry_run && report.disk.totals.failed > 0) return 1;
@@ -415,6 +445,63 @@ function resolveGcAgentDir(env: NodeJS.ProcessEnv): string {
 	return env.GJC_CODING_AGENT_DIR?.trim() || env.PI_CODING_AGENT_DIR?.trim() || getAgentDir();
 }
 
+/**
+ * Validate operator-supplied empty-delete roots before any ordinary GC mutation.
+ *
+ * These roots are explicit operands, so a missing, symlink, non-directory, or
+ * unreadable root is a usage failure rather than a partial GC report. The
+ * collector repeats its own race-safe checks after this preflight.
+ */
+async function preflightEmptyDeleteRoot(root: string): Promise<void> {
+	const resolvedRoot = path.resolve(root);
+	let stat: Stats;
+	try {
+		stat = await fsp.lstat(resolvedRoot);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new GcUsageError(`${root}: missing_root`);
+		}
+		throw new GcUsageError(`${root}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (stat.isSymbolicLink()) throw new GcUsageError(`${root}: symlink_root`);
+	if (!stat.isDirectory()) throw new GcUsageError(`${root}: not_directory`);
+	try {
+		await fsp.readdir(resolvedRoot);
+	} catch (error) {
+		throw new GcUsageError(`${root}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * Collect every explicit empty-delete root once before starting any destructive
+ * operation. The second pass reuses those identities so a later root race cannot
+ * leave an earlier root pruned before the race is discovered.
+ */
+async function collectEmptyDeleteReceiptsForGc(
+	roots: string[],
+): Promise<{ report: EmptyDeleteGcReport; records: Map<string, EmptyDeleteGcRecord[]> }> {
+	const collected = new Map<string, EmptyDeleteGcRecord[]>();
+	const collect = async (root: string): Promise<EmptyDeleteGcRecord[]> => {
+		const records = await collectEmptyDeleteReceipts(root);
+		collected.set(root, records);
+		return records.map(record => ({
+			...record,
+			identity: record.identity ? { ...record.identity } : undefined,
+			retainedPaths: record.retainedPaths ? { ...record.retainedPaths } : undefined,
+		}));
+	};
+	const report = await runEmptyDeleteGc({ roots, prune: false }, { collect });
+	return { report, records: collected };
+}
+
+function cloneEmptyDeleteRecords(records: EmptyDeleteGcRecord[]): EmptyDeleteGcRecord[] {
+	return records.map(record => ({
+		...record,
+		identity: record.identity ? { ...record.identity } : undefined,
+		retainedPaths: record.retainedPaths ? { ...record.retainedPaths } : undefined,
+	}));
+}
+
 /**
  * Locate and measure the managed scope for `cwd`.
  *
@@ -482,9 +569,77 @@ export async function runGjcGcCommand(
 		return { stdout: gcHelpText(), stderr: "", status: 0 };
 	}
 
+	// Resolve and validate every empty-delete operand BEFORE any store collection or
+	// prune can mutate: a malformed manifest or missing operand must fail with status 2
+	// while every candidate is still untouched.
+	let emptyDeleteRoots: string[] = [];
+	if (parsed.emptyDeleteReceipts) {
+		emptyDeleteRoots = [...parsed.emptyDeleteRoots];
+		if (emptyDeleteRoots.some(root => root.includes("\0"))) {
+			return { stdout: "", stderr: "gjc gc: root_invalid\n", status: 2 };
+		}
+		// Every supplied manifest is validated, not just the last: a malformed earlier
+		// manifest must fail the run before any store collection or prune can mutate.
+		for (const manifestPath of parsed.emptyDeleteManifests) {
+			let parsedManifest: unknown;
+			try {
+				const raw = await fsp.readFile(manifestPath, "utf8");
+				parsedManifest = JSON.parse(raw);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { stdout: "", stderr: `gjc gc: manifest_invalid: ${message}\n`, status: 2 };
+			}
+			if (typeof parsedManifest !== "object" || parsedManifest === null || Array.isArray(parsedManifest)) {
+				return { stdout: "", stderr: "gjc gc: manifest_shape_invalid\n", status: 2 };
+			}
+			const manifestRoots = (parsedManifest as { roots?: unknown }).roots;
+			if (!Array.isArray(manifestRoots)) {
+				return { stdout: "", stderr: "gjc gc: manifest_roots_required\n", status: 2 };
+			}
+			for (const root of manifestRoots) {
+				if (typeof root !== "string" || root.length === 0 || root.includes("\0")) {
+					return { stdout: "", stderr: "gjc gc: manifest_root_invalid\n", status: 2 };
+				}
+				emptyDeleteRoots.push(root);
+			}
+		}
+		if (emptyDeleteRoots.length === 0) {
+			return { stdout: "", stderr: "gjc gc: empty_delete_receipts_requires_root_or_manifest\n", status: 2 };
+		}
+		try {
+			for (const root of emptyDeleteRoots) await preflightEmptyDeleteRoot(root);
+		} catch (error) {
+			const message = error instanceof GcUsageError ? error.message : String(error);
+			return { stdout: "", stderr: `gjc gc: ${message}\n`, status: 2 };
+		}
+	}
+	let emptyDeleteReceipts: EmptyDeleteGcReport | undefined;
+	let emptyDeleteRecords: Map<string, EmptyDeleteGcRecord[]> | undefined;
+	if (parsed.emptyDeleteReceipts) {
+		// Discovery is deliberately read-only and covers every root before either the
+		// empty-delete unlink or an ordinary --prune adapter can mutate anything.
+		const collected = await collectEmptyDeleteReceiptsForGc(emptyDeleteRoots);
+		emptyDeleteReceipts = collected.report;
+		emptyDeleteRecords = collected.records;
+		if (parsed.prune && emptyDeleteReceipts.errors.length === 0) {
+			emptyDeleteReceipts = await runEmptyDeleteGc(
+				{ roots: emptyDeleteRoots, prune: true },
+				{
+					collect: async root => {
+						const records = emptyDeleteRecords?.get(root);
+						if (!records) throw new Error(`${root}: empty_delete_collection_missing`);
+						return cloneEmptyDeleteRecords(records);
+					},
+				},
+			);
+		}
+	}
 	const resolvedAdapters = adapters ?? (await defaultGcAdapters());
 	const ctx: GcContext = { probe: gcPidProbe, force: parsed.prune, env, cwd };
-	const report = await collectGcReport(resolvedAdapters, ctx, parsed.prune);
+	// A failed explicit empty-delete discovery or cleanup is a safety gate: report
+	// ordinary candidates, but never perform their destructive prune in that run.
+	const ordinaryPrune = parsed.prune && (emptyDeleteReceipts?.errors.length ?? 0) === 0;
+	const report = await collectGcReport(resolvedAdapters, ctx, ordinaryPrune);
 	report.operation = parsed.repairSessionIndex ? "repair_session_index" : parsed.prune ? "prune" : "dry_run";
 	report.session_index = await collectSessionIndexHealth(parsed.repairSessionIndex, resolveGcAgentDir(env));
 	if (parsed.disk) {
@@ -492,9 +647,10 @@ export async function runGjcGcCommand(
 			agentDir: resolveGcAgentDir(env),
 			env,
 			policy: resolveGcDiskPolicy(diskPolicy),
-			prune: parsed.prune,
+			prune: ordinaryPrune,
 		});
 	}
+	if (emptyDeleteReceipts) report.empty_delete_receipts = emptyDeleteReceipts;
 	const scopeUsage = await collectGcSessionScope(cwd, resolveGcAgentDir(env));
 	if (scopeUsage && shouldReportSessionScope(scopeUsage)) report.session_scope = scopeUsage;
 	const sessionIndexFailed =
@@ -503,7 +659,7 @@ export async function runGjcGcCommand(
 		report.session_index?.status === "repair_failed";
 	const status = sessionIndexFailed ? 1 : computeExitCode(report);
 	const stdout = parsed.json
-		? `${JSON.stringify(report, null, 2)}\n`
+		? `${JSON.stringify(report, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2)}\n`
 		: `${buildGcReportText(report)}${report.disk ? buildGcDiskReportText(report.disk) : ""}`;
 	return { stdout, stderr: "", status };
 }
@@ -513,7 +669,7 @@ export function gcHelpText(): string {
 		"gjc gc - garbage-collect stale GJC session/PID records",
 		"",
 		"USAGE",
-		"  $ gjc gc [--prune|--force] [--disk] [--repair-session-index] [--json]",
+		"  $ gjc gc [--prune|--force] [--disk] [--repair-session-index] [--empty-delete-receipts --root <dir>] [--json]",
 
 		"",
 		"FLAGS",
@@ -522,6 +678,13 @@ export function gcHelpText(): string {
 		"  -j, --json        Emit machine-readable JSON",
 		"  --repair-session-index  Explicitly quarantine a corrupt session-index suffix and retain its valid prefix",
 		"  --disk            Also report on-disk retention (sessions, blobs, artifacts, natives, backups)",
+		"  --empty-delete-receipts  Report/prune empty .gjc-delete-* under --root / --manifest",
+		"  --root <dir>      Operand root for --empty-delete-receipts (repeatable)",
+		'  --manifest <file> JSON {"roots":[...]} for --empty-delete-receipts (repeatable)',
+		"",
+		"  Operand values starting with '-' are rejected as missing operands; spell a",
+		"  dash-prefixed path as ./-name. --root/--manifest without --empty-delete-receipts",
+		"  is a usage error, and every supplied manifest is validated before any prune.",
 		"",
 		"Liveness-only: a record is removed only when its owning process is dead",
 		"(ESRCH). Live / permission-denied / unknown processes are always kept.",

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

@@ -78,7 +78,7 @@ const WORKTREE_BUCKET_ENV = "GJC_WORKTREE_DIR";
  * what keeps two repositories that share a branch name from resolving to one worktree.
  */
 const REPO_NAME_PLACEHOLDER = "{repo}";
-const DEFAULT_WORKTREE_BUCKET = `${REPO_NAME_PLACEHOLDER}.gajae-code-worktrees`;
+const DEFAULT_WORKTREE_BUCKET = `${REPO_NAME_PLACEHOLDER}/.worktrees`;
 
 function expandHomePrefix(value: string, home: string, pathApi: typeof path.posix): string {
 	if (value === "~") return home;
@@ -108,14 +108,36 @@ export function resolveWorktreeBucketForPath(
 /**
  * Directory that holds this repository's launch worktrees.
  *
- * A relative override resolves against the repository's PARENT directory, matching the
- * default's own shape, so `{repo}.worktrees` adopts an existing sibling bucket and
- * `.worktrees` parks a hidden bucket beside the repository. An absolute override is used verbatim.
+ * A relative override resolves against the repository's parent directory. The default
+ * `{repo}/.worktrees` template places managed worktrees inside the repository, while
+ * `{repo}.worktrees` adopts an existing sibling bucket. An absolute override is used verbatim.
  */
 function resolveWorktreeBucket(repoRoot: string): string {
 	return resolveWorktreeBucketForPath(repoRoot, process.env[WORKTREE_BUCKET_ENV], os.homedir(), path);
 }
 
+function ensureRepositoryBucketIgnored(repoRoot: string, bucketPath: string): void {
+	const relativeBucket = path.relative(repoRoot, bucketPath);
+	if (relativeBucket.startsWith(`..${path.sep}`) || relativeBucket === ".." || path.isAbsolute(relativeBucket)) return;
+	const ignoreProbe = path.join(relativeBucket, ".gjc-worktree-probe");
+	for (const candidate of [relativeBucket, ignoreProbe]) {
+		const result = Bun.spawnSync(["git", "check-ignore", "--quiet", "--", candidate], {
+			cwd: repoRoot,
+			stdout: "ignore",
+			stderr: "pipe",
+		});
+		if (result.exitCode === 0) return;
+	}
+	throw new Error(
+		[
+			"worktree_bucket_not_ignored",
+			"The GJC launch worktree bucket is inside the repository but is not ignored by Git.",
+			`Path: ${formatBucketPath(bucketPath)}`,
+			`Safe remediation: add /${relativeBucket.replaceAll(path.sep, "/")} to ${path.join(repoRoot, ".gitignore")}, then relaunch.`,
+		].join("\n"),
+	);
+}
+
 function resolveSourceBranchSlug(repoRoot: string, baseRef: string): string {
 	const branch = tryRunGit(repoRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
 	if (branch) return sanitizePathToken(branch);
@@ -301,6 +323,7 @@ function pruneStaleWorktreePath(repoRoot: string): void {
 
 function readWorktreeEntryFromPath(repoRoot: string, worktreePath: string): GitWorktreeEntry | null {
 	if (!fs.existsSync(worktreePath)) return null;
+	if (!fs.existsSync(path.join(worktreePath, ".git"))) return null;
 	const repoCommonDir = tryRunGit(repoRoot, ["rev-parse", "--git-common-dir"]);
 	const worktreeCommonDir = tryRunGit(worktreePath, ["rev-parse", "--git-common-dir"]);
 	if (!repoCommonDir || !worktreeCommonDir) return null;
@@ -379,6 +402,7 @@ export function planLaunchWorktree(
 	if (branchName) validateBranchName(repoRoot, branchName);
 	const worktreeSlug = mode.detached ? resolveSourceBranchSlug(repoRoot, baseRef) : sanitizePathToken(mode.name);
 	const worktreePath = path.join(resolveWorktreeBucket(repoRoot), worktreeSlug);
+	if (path.resolve(worktreePath) === path.resolve(repoRoot)) throw new Error(`worktree_path_conflict:${worktreePath}`);
 	return { enabled: true, repoRoot, worktreePath, detached: mode.detached, baseRef, branchName };
 }
 
@@ -386,6 +410,9 @@ export function ensureLaunchWorktree(
 	plan: GjcLaunchWorktreePlan | { enabled: false },
 ): GjcLaunchWorktreeResult | { enabled: false } {
 	if (!plan.enabled) return { enabled: false };
+	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)) {
@@ -393,9 +420,19 @@ export function ensureLaunchWorktree(
 		allWorktrees = listWorktrees(plan.repoRoot);
 	}
 
-	const existingAtPath =
-		findWorktreeByPath(allWorktrees, plan.worktreePath) ??
-		readWorktreeEntryFromPath(plan.repoRoot, plan.worktreePath);
+	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) {

package/src/gjc-runtime/ralplan-runtime.ts

@@ -756,9 +756,22 @@ export async function resolveRalplanTargetRoot(
 		stdout: "pipe",
 		stderr: "pipe",
 	});
-	if ((await verified.exited) !== 0) {
+	const [verifiedStatus, verifiedOutput] = await Promise.all([verified.exited, new Response(verified.stdout).text()]);
+	const headObject = verifiedOutput.trim();
+	if (verifiedStatus !== 0 || !/^[0-9a-f]{40,64}$/u.test(headObject)) {
 		throw new RalplanCommandError(2, `ralplan --worktree-root is not a valid git worktree: ${canonical}`);
 	}
+	const objectType = Bun.spawn(["git", "-C", canonical, "cat-file", "-t", headObject], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [objectTypeStatus, objectTypeOutput] = await Promise.all([
+		objectType.exited,
+		new Response(objectType.stdout).text(),
+	]);
+	if (objectTypeStatus !== 0 || objectTypeOutput.trim() !== "commit") {
+		throw new RalplanCommandError(2, `ralplan --worktree-root is not a commit worktree: ${canonical}`);
+	}
 	let worktreeRoot: string;
 	try {
 		worktreeRoot = await fs.realpath(repository.repoRoot);