@gajae-code/coding-agent 0.15.5 → 0.16.0

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

@@ -0,0 +1,301 @@
+/**
+ * Official GC of already-quarantined empty `.gjc-delete-*` receipts.
+ * Roots are operator operands — never hardcoded host paths.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { BigIntStats } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { exactUnlinkDirect, type NativeExactUnlinkResult } from "@gajae-code/natives";
+
+export const EMPTY_DELETE_PREFIX = ".gjc-delete-";
+const EMPTY_DELETE_RECEIPT_PATTERN =
+	/^\.gjc-delete-session-state-lock-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/u;
+const EMPTY_FILE_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+export interface EmptyDeleteIdentity {
+	dev: bigint;
+	ino: bigint;
+	nlink: bigint;
+	size: bigint;
+	mtimeNs: bigint;
+	parentDev: bigint;
+	parentIno: bigint;
+	sha256: string;
+}
+
+export interface EmptyDeleteGcRecord {
+	root: string;
+	path: string;
+	action: "would_remove" | "removed" | "kept" | "skipped";
+	reason: string;
+	identity?: EmptyDeleteIdentity;
+	/** A dry-run candidate is an observation, never deletion authority. */
+	observationOnly?: boolean;
+	/** Retained-object paths a native direct unlink left behind; operator-recoverable only there. */
+	retainedPaths?: { detached?: string; successor?: string; placeholder?: string; unknown?: string };
+}
+
+export interface EmptyDeleteGcReport {
+	dry_run: boolean;
+	roots: string[];
+	records: EmptyDeleteGcRecord[];
+	would_remove: number;
+	removed: number;
+	kept: number;
+	skipped: number;
+	errors: string[];
+}
+
+export interface EmptyDeleteGcOptions {
+	roots: string[];
+	prune: boolean;
+}
+
+export interface EmptyDeleteGcDependencies {
+	/** Internal seam for deterministic collect-to-prune race tests. */
+	collect?: (root: string) => Promise<EmptyDeleteGcRecord[]>;
+	exactUnlinkDirect?: typeof exactUnlinkDirect;
+}
+
+function isUnsafeName(name: string): boolean {
+	return name.includes("/") || name.includes("\0") || name === "." || name === "..";
+}
+
+function identityOf(stat: BigIntStats): Omit<EmptyDeleteIdentity, "parentDev" | "parentIno" | "sha256"> {
+	return {
+		dev: stat.dev,
+		ino: stat.ino,
+		nlink: stat.nlink,
+		size: stat.size,
+		mtimeNs: stat.mtimeNs,
+	};
+}
+
+/**
+ * Extract the operator-recoverable retained paths a native direct unlink can leave behind.
+ * Any of them means debris still exists outside the receipt namespace, so the caller
+ * records them and fails the run instead of reporting a clean prune.
+ */
+function retainedPathsOf(
+	result: NativeExactUnlinkResult,
+): { detached?: string; successor?: string; placeholder?: string; unknown?: string } | undefined {
+	if (
+		result.detachedPath === undefined &&
+		result.retainedSuccessorPath === undefined &&
+		result.retainedPlaceholderPath === undefined &&
+		result.retainedUnknownPath === undefined
+	)
+		return undefined;
+	return {
+		detached: result.detachedPath,
+		successor: result.retainedSuccessorPath,
+		placeholder: result.retainedPlaceholderPath,
+		unknown: result.retainedUnknownPath,
+	};
+}
+
+function isEmptyDeleteReceiptName(name: string): boolean {
+	return EMPTY_DELETE_RECEIPT_PATTERN.test(name);
+}
+
+function sameRootIdentity(left: BigIntStats, right: BigIntStats): boolean {
+	return left.isDirectory() && right.isDirectory() && left.dev === right.dev && left.ino === right.ino;
+}
+
+function rootRaceRecord(root: string): EmptyDeleteGcRecord[] {
+	return [{ root, path: root, action: "skipped", reason: "root_race" }];
+}
+
+export async function collectEmptyDeleteReceipts(
+	root: string,
+	deps: { lstat?: (file: string, options: { bigint: true }) => Promise<BigIntStats> } = {},
+): Promise<EmptyDeleteGcRecord[]> {
+	const lstatFile = deps.lstat ?? ((file: string) => fs.lstat(file, { bigint: true }));
+	const records: EmptyDeleteGcRecord[] = [];
+	const resolvedRoot = path.resolve(root);
+	let rootStat: BigIntStats;
+	try {
+		rootStat = await lstatFile(resolvedRoot, { bigint: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return [{ root, path: root, action: "skipped", reason: "missing_root" }];
+		}
+		throw error;
+	}
+	if (rootStat.isSymbolicLink()) {
+		return [{ root, path: root, action: "skipped", reason: "symlink_root" }];
+	}
+	if (!rootStat.isDirectory()) {
+		return [{ root, path: root, action: "skipped", reason: "not_directory" }];
+	}
+	let names: string[];
+	try {
+		names = await fs.readdir(resolvedRoot);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return rootRaceRecord(root);
+		}
+		throw error;
+	}
+	// Enumeration is the first operation that can observe a replacement root. Do not
+	// attribute any names from that enumeration until the original root identity is
+	// proved to still own the pathname.
+	try {
+		const enumeratedRoot = await lstatFile(resolvedRoot, { bigint: true });
+		if (!sameRootIdentity(rootStat, enumeratedRoot)) return rootRaceRecord(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return rootRaceRecord(root);
+		throw error;
+	}
+	for (const name of names) {
+		if (isUnsafeName(name) || !isEmptyDeleteReceiptName(name)) continue;
+		const file = path.join(resolvedRoot, name);
+		let stat: BigIntStats;
+		try {
+			stat = await lstatFile(file, { bigint: true });
+		} catch (error) {
+			// ENOENT is an ordinary race with concurrent cleanup, but silently dropping the
+			// entry would shrink the report without trace; record it as a raced candidate so
+			// discovery stays fail-closed. Any other stat failure is a hard discovery error.
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				records.push({ root, path: file, action: "skipped", reason: "raced" });
+				continue;
+			}
+			throw error;
+		}
+		if (stat.isSymbolicLink()) {
+			records.push({ root, path: file, action: "kept", reason: "symlink" });
+			continue;
+		}
+		if (!stat.isFile()) {
+			records.push({ root, path: file, action: "kept", reason: "not_regular" });
+			continue;
+		}
+		if (stat.size !== 0n) {
+			records.push({ root, path: file, action: "kept", reason: "non_empty" });
+			continue;
+		}
+		if (stat.nlink !== 1n) {
+			records.push({ root, path: file, action: "kept", reason: "nlink" });
+			continue;
+		}
+		records.push({
+			root,
+			path: file,
+			action: "would_remove",
+			reason: "empty_delete_receipt",
+			identity: {
+				...identityOf(stat),
+				parentDev: rootStat.dev,
+				parentIno: rootStat.ino,
+				sha256: EMPTY_FILE_SHA256,
+			},
+		});
+	}
+	// The candidate lstat calls above are pathname operations. Revalidate once more
+	// before returning so a replaced root can never leak its external candidate paths
+	// (or their identities) into a GC report.
+	try {
+		const finalRoot = await lstatFile(resolvedRoot, { bigint: true });
+		if (!sameRootIdentity(rootStat, finalRoot)) return rootRaceRecord(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return rootRaceRecord(root);
+		throw error;
+	}
+	return records;
+}
+
+export async function runEmptyDeleteGc(
+	options: EmptyDeleteGcOptions,
+	deps: EmptyDeleteGcDependencies = {},
+): Promise<EmptyDeleteGcReport> {
+	const report: EmptyDeleteGcReport = {
+		dry_run: !options.prune,
+		roots: options.roots,
+		records: [],
+		would_remove: 0,
+		removed: 0,
+		kept: 0,
+		skipped: 0,
+		errors: [],
+	};
+	const collect = deps.collect ?? collectEmptyDeleteReceipts;
+	const unlink = deps.exactUnlinkDirect ?? exactUnlinkDirect;
+	for (const root of options.roots) {
+		let records: EmptyDeleteGcRecord[];
+		try {
+			records = await collect(root);
+		} catch (error) {
+			report.errors.push(`${root}: ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		for (const record of records) {
+			if (record.action === "would_remove" && !options.prune) record.observationOnly = true;
+			if (
+				record.action === "skipped" &&
+				(record.reason === "raced" ||
+					record.reason === "root_race" ||
+					(record.path === root &&
+						(record.reason === "missing_root" ||
+							record.reason === "symlink_root" ||
+							record.reason === "not_directory")))
+			) {
+				report.errors.push(`${record.path}: ${record.reason}`);
+			}
+			if (record.action === "would_remove" && options.prune) {
+				try {
+					if (!record.identity) {
+						record.action = "kept";
+						record.reason = "identity_missing";
+					} else {
+						const result = unlink(record.path, {
+							...record.identity,
+							quarantineName: `.gjc-delete-gc-${randomUUID()}.json`,
+						});
+						const retainedPaths = retainedPathsOf(result);
+						if (result.ok) {
+							record.action = "removed";
+						} else if (result.code === "not_found") {
+							record.action = "skipped";
+							record.reason = "gone";
+						} else if (result.code === "identity_mismatch") {
+							record.action = "kept";
+							record.reason = "identity_drift";
+						} else {
+							record.action = "kept";
+							record.reason = `unlink_failed:${result.code ?? "unknown"}`;
+							report.errors.push(`${record.path}: ${record.reason}`);
+						}
+						// Objects the native layer retained (post-detach failure or a successor at
+						// the private quarantine name) are recoverable only at those paths; surface
+						// them and fail the run instead of silently stranding debris.
+						if (retainedPaths !== undefined) {
+							record.retainedPaths = retainedPaths;
+							record.reason = result.ok ? `retained:${result.code ?? "cleanup_pending"}` : record.reason;
+							report.errors.push(
+								`${record.path}: retained debris requires operator recovery: ${JSON.stringify(retainedPaths)}`,
+							);
+						}
+					}
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+						record.action = "skipped";
+						record.reason = "gone";
+					} else {
+						record.action = "kept";
+						record.reason = `unlink_failed:${error instanceof Error ? error.message : String(error)}`;
+						report.errors.push(`${record.path}: ${record.reason}`);
+					}
+				}
+			}
+			report.records.push(record);
+			if (record.action === "would_remove") report.would_remove += 1;
+			else if (record.action === "removed") report.removed += 1;
+			else if (record.action === "skipped") report.skipped += 1;
+			else report.kept += 1;
+		}
+	}
+	return report;
+}

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

@@ -88,6 +88,35 @@ export function buildGcReportText(report: GcReport): string {
 		lines.push("");
 	}
 
+	if (report.empty_delete_receipts) {
+		const empty = report.empty_delete_receipts;
+		lines.push(`Empty .gjc-delete receipts (${empty.records.length})`);
+		if (empty.records.length === 0) {
+			lines.push("  (none)");
+		} else {
+			for (const record of empty.records) {
+				const action = record.action === "would_remove" ? "would remove" : record.action;
+				lines.push(`  [${action}] ${record.path} :: ${record.reason}`);
+				if (record.retainedPaths) {
+					const retained = [
+						["detached", record.retainedPaths.detached],
+						["successor", record.retainedPaths.successor],
+						["placeholder", record.retainedPaths.placeholder],
+						["unknown", record.retainedPaths.unknown],
+					].filter((entry): entry is [string, string] => entry[1] !== undefined);
+					if (retained.length > 0)
+						lines.push(`    retained: ${retained.map(([kind, p]) => `${kind}=${p}`).join(" ")}`);
+				}
+			}
+		}
+		for (const error of empty.errors) lines.push(`  [error] ${error}`);
+		lines.push(
+			`  Summary: roots=${empty.roots.length} would_remove=${empty.would_remove} removed=${empty.removed} ` +
+				`kept=${empty.kept} skipped=${empty.skipped} errors=${empty.errors.length}`,
+		);
+		lines.push("");
+	}
+
 	if (report.warnings.length > 0) {
 		lines.push(`Warnings (${report.warnings.length})`);
 		for (const warning of report.warnings) lines.push(`  [${warning.store}/${warning.scope}] ${warning.message}`);

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.",