@gajae-code/coding-agent 0.11.3 → 0.11.5

package/src/extensibility/plugins/marketplace/manager.ts

@@ -12,12 +12,11 @@ import * as path from "node:path";
 
 import { isEnoent, logger, pathIsWithin } from "@gajae-code/utils";
 
-import { cachePlugin } from "./cache";
+import { cachePlugin, getCachedPluginPath } from "./cache";
 import { classifySource, fetchMarketplace, parseMarketplaceCatalog, promoteCloneToCache } from "./fetcher";
 import {
 	addInstalledPlugin,
 	addMarketplaceEntry,
-	collectReferencedPaths,
 	getInstalledPlugin,
 	getMarketplaceEntry,
 	readInstalledPluginsRegistry,
@@ -255,6 +254,7 @@ export class MarketplaceManager {
 		if (existing && existing.length > 0 && !force) {
 			throw new Error(`Plugin "${pluginId}" is already installed. Use force option to reinstall.`);
 		}
+		const existingCachePaths = existing ? await this.#validateCacheDeletionTargets(pluginId, existing) : [];
 
 		// 4. Resolve source path.
 		// marketplaceClonePath is the marketplace root — the directory containing .Anthropic model-plugin/
@@ -289,6 +289,9 @@ export class MarketplaceManager {
 		let cachePath!: string;
 		try {
 			version = await this.#resolvePluginVersion(pluginEntry, sourcePath);
+			if ([marketplace, name, version].some(component => /[. ]$/.test(component))) {
+				throw new Error(`Invalid cache identity for plugin "${pluginId}"`);
+			}
 			cachePath = await cachePlugin(sourcePath, this.#opts.pluginsCacheDir, marketplace, name, version);
 			await this.#writeEmbeddedLspConfig(pluginEntry, cachePath);
 		} finally {
@@ -311,11 +314,13 @@ export class MarketplaceManager {
 					? readInstalledPluginsRegistry(this.#opts.projectInstalledRegistryPath)
 					: Promise.resolve({ version: 2 as const, plugins: {} as Record<string, InstalledPluginEntry[]> }),
 			]);
-			const referenced = collectReferencedPaths(userReg, projectReg);
+			const referenced = this.#collectReferencedCacheIdentities(userReg, projectReg);
+			const cachePathIdentity = this.#cacheDeletionIdentity(cachePath);
 
-			for (const entry of existing) {
-				if (entry.installPath !== cachePath && !referenced.has(entry.installPath)) {
-					await fs.rm(entry.installPath, { recursive: true, force: true });
+			for (const existingCachePath of existingCachePaths) {
+				const existingIdentity = this.#cacheDeletionIdentity(existingCachePath);
+				if (existingIdentity !== cachePathIdentity && !referenced.has(existingIdentity)) {
+					await fs.rm(existingCachePath, { recursive: true, force: true });
 				}
 			}
 		}
@@ -395,6 +400,84 @@ export class MarketplaceManager {
 		return "0.0.0";
 	}
 
+	async #validateCacheDeletionTargets(pluginId: string, entries: readonly InstalledPluginEntry[]): Promise<string[]> {
+		const parsed = parsePluginId(pluginId);
+		if (!parsed) {
+			throw new Error(`Invalid plugin ID format: "${pluginId}". Expected "name@marketplace".`);
+		}
+
+		const targets: string[] = [];
+		for (const entry of entries) {
+			if ([parsed.marketplace, parsed.name, entry.version].some(component => /[. ]$/.test(component))) {
+				throw new Error(`Refusing to remove plugin "${pluginId}": invalid recorded cache identity`);
+			}
+
+			let targetPath: string;
+			try {
+				targetPath = getCachedPluginPath(
+					this.#opts.pluginsCacheDir,
+					parsed.marketplace,
+					parsed.name,
+					entry.version,
+				);
+			} catch (error) {
+				throw new Error(`Refusing to remove plugin "${pluginId}": invalid recorded cache identity`, {
+					cause: error,
+				});
+			}
+
+			if (entry.installPath !== targetPath) {
+				throw new Error(`Refusing to remove plugin "${pluginId}": recorded install path is not its cache path`);
+			}
+
+			try {
+				const stat = await fs.lstat(targetPath);
+				if (stat.isSymbolicLink()) {
+					throw new Error(`Refusing to remove plugin "${pluginId}": cache path is a symbolic link or junction`);
+				}
+			} catch (error) {
+				if (!isEnoent(error)) throw error;
+			}
+
+			targets.push(targetPath);
+		}
+		return targets;
+	}
+
+	#cacheDeletionIdentity(cachePath: string): string {
+		// Model Windows path identity on every host so reference protection is
+		// deterministic: case is ignored and trailing dots/spaces are discarded.
+		return path
+			.resolve(cachePath)
+			.split(path.sep)
+			.map(component => component.replace(/[. ]+$/, "").toLowerCase())
+			.join(path.sep);
+	}
+
+	#collectReferencedCacheIdentities(...registries: InstalledPluginsRegistry[]): Set<string> {
+		const identities = new Set<string>();
+		for (const registry of registries) {
+			for (const [pluginId, entries] of Object.entries(registry.plugins)) {
+				const parsed = parsePluginId(pluginId);
+				if (!parsed) continue;
+				for (const entry of entries) {
+					try {
+						const cachePath = getCachedPluginPath(
+							this.#opts.pluginsCacheDir,
+							parsed.marketplace,
+							parsed.name,
+							entry.version,
+						);
+						identities.add(this.#cacheDeletionIdentity(cachePath));
+					} catch {
+						// Invalid registry entries cannot identify a permitted cache target.
+					}
+				}
+			}
+		}
+		return identities;
+	}
+
 	async uninstallPlugin(pluginId: string, scope?: "user" | "project"): Promise<void> {
 		const parsed = parsePluginId(pluginId);
 		if (!parsed) {
@@ -434,6 +517,7 @@ export class MarketplaceManager {
 		const targetEntries = targetScope === "project" ? projectEntries! : userEntries!;
 		const targetReg = targetScope === "project" ? projectReg : userReg;
 		const registryPath = this.#registryPath(targetScope);
+		const targetCachePaths = await this.#validateCacheDeletionTargets(pluginId, targetEntries);
 
 		const updatedReg = removeInstalledPlugin(targetReg, pluginId);
 		await writeInstalledPluginsRegistry(registryPath, updatedReg);
@@ -445,11 +529,11 @@ export class MarketplaceManager {
 				? readInstalledPluginsRegistry(this.#opts.projectInstalledRegistryPath)
 				: Promise.resolve({ version: 2 as const, plugins: {} as Record<string, InstalledPluginEntry[]> }),
 		]);
-		const referenced = collectReferencedPaths(freshUserReg, freshProjectReg);
+		const referenced = this.#collectReferencedCacheIdentities(freshUserReg, freshProjectReg);
 
-		for (const entry of targetEntries) {
-			if (!referenced.has(entry.installPath)) {
-				await fs.rm(entry.installPath, { recursive: true, force: true });
+		for (const targetCachePath of targetCachePaths) {
+			if (!referenced.has(this.#cacheDeletionIdentity(targetCachePath))) {
+				await fs.rm(targetCachePath, { recursive: true, force: true });
 			}
 		}
 

package/src/gjc-runtime/deep-interview-recorder.ts

@@ -8,7 +8,9 @@ import {
 } from "./deep-interview-ambiguity";
 import {
 	answerHash,
+	assertDeepInterviewInputWithinLimit,
 	assertDeepInterviewIntentManifest,
+	assertDeepInterviewStructuredResponseWithinLimit,
 	createDeepInterviewIntentManifest,
 	type DeepInterviewEstablishedFact,
 	type DeepInterviewIntentItem,
@@ -17,6 +19,7 @@ import {
 	type DeepInterviewStateEnvelope,
 	type DeepInterviewTriggerMetadata,
 	deriveRoundKey,
+	MAX_USER_RESPONSE_LENGTH,
 	normalizeDeepInterviewEnvelope,
 	questionHash,
 	reviewDeepInterviewIntent,
@@ -426,6 +429,9 @@ export async function appendOrMergeDeepInterviewRound(
 	input: DeepInterviewAnswerInput,
 	options: { sessionId?: string } = {},
 ): Promise<{ action: AppendOrMergeAction; record: DeepInterviewRoundRecord; disputedFactIds?: string[] }> {
+	assertDeepInterviewStructuredResponseWithinLimit(input);
+	if (input.customInput !== undefined)
+		assertDeepInterviewInputWithinLimit(input.customInput, MAX_USER_RESPONSE_LENGTH, "user_response");
 	const envelope = await readEnvelope(statePath);
 	const interviewId = input.interviewId ?? interviewIdOf(envelope);
 	const shell = buildAnswerShell({
@@ -547,6 +553,7 @@ export async function enrichDeepInterviewRoundScoring(
 	input: DeepInterviewScoringInput,
 	options: { sessionId?: string } = {},
 ): Promise<{ record: DeepInterviewRoundRecord }> {
+	assertDeepInterviewStructuredResponseWithinLimit(input);
 	const envelope = await readEnvelope(statePath);
 	const interviewId = input.interviewId ?? interviewIdOf(envelope);
 	const rounds = readRounds(envelope);

package/src/gjc-runtime/deep-interview-runtime.ts

@@ -7,11 +7,14 @@ import { syncSkillActiveState } from "../skill-state/active-state";
 import { deriveDeepInterviewHud } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 import {
+	assertDeepInterviewInputWithinLimit,
 	assertDeepInterviewIntentReview,
 	type DeepInterviewIntentCategory,
 	type DeepInterviewIntentItem,
 	type DeepInterviewIntentManifest,
 	type DeepInterviewIntentReview,
+	MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH,
+	MAX_INITIAL_CONTEXT_LENGTH,
 	normalizeDeepInterviewEnvelope,
 	reviewDeepInterviewIntent,
 } from "./deep-interview-state";
@@ -559,6 +562,7 @@ async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): P
 		ideaParts.push(arg);
 	}
 	const idea = ideaParts.join(" ").trim();
+	assertDeepInterviewInputWithinLimit(idea, MAX_INITIAL_CONTEXT_LENGTH, "initial_idea");
 	const effectiveResolution: DeepInterviewResolution = resolution ?? "standard";
 	const trace = hasFlag(args, "--trace") && idea ? await buildDeepInterviewTraceSummary(cwd, idea) : undefined;
 	return {
@@ -632,6 +636,11 @@ export async function persistDeepInterviewSpec(
 	cwd: string,
 	resolved: ResolvedDeepInterviewSpecWriteArgs,
 ): Promise<PersistedDeepInterviewSpec> {
+	assertDeepInterviewInputWithinLimit(
+		resolved.spec,
+		MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH,
+		"structured deep-interview response",
+	);
 	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "corrupt" && !resolved.force) {
@@ -731,6 +740,7 @@ export async function persistDeepInterviewSpec(
 
 async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepInterviewArgs): Promise<string> {
 	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
+	assertDeepInterviewInputWithinLimit(resolved.idea, MAX_INITIAL_CONTEXT_LENGTH, "initial_idea");
 	const now = new Date().toISOString();
 	const payload: Record<string, unknown> = {
 		active: true,

package/src/gjc-runtime/deep-interview-state.ts

@@ -397,6 +397,126 @@ const MAX_INTENT_STATEMENT_LENGTH = 1_000;
 const MAX_INTENT_RATIONALE_LENGTH = 500;
 const MAX_INTENT_EVIDENCE_LENGTH = 80;
 
+// =============================================================================
+// Input validation: free-text field allowlist + size limits (ouroboros parity)
+// =============================================================================
+
+/**
+ * User-input fields that legitimately carry prose (goals, prompts, descriptions,
+ * answers). Shell metacharacters (`;`, `|`, `&`, backticks, `$()`) are valid prose
+ * here and must NOT be rejected as structural injection. Structural fields (ids,
+ * categories, hashes) stay strictly validated by their own guards.
+ */
+export const DEEP_INTERVIEW_FREETEXT_FIELDS: ReadonlySet<string> = new Set([
+	"initial_context",
+	"initial_idea",
+	"initial_context_summary",
+	"user_response",
+	"answer",
+	"goal",
+	"objective",
+	"prompt",
+	"description",
+	"statement",
+	"restated_goal",
+	"evidence",
+	"excerpt",
+]);
+
+/** DoS-prevention character-count caps, matching ask-schema string-length semantics. */
+export const MAX_INITIAL_CONTEXT_LENGTH = 50_000;
+export const MAX_USER_RESPONSE_LENGTH = 10_000;
+/** Maximum serialized JavaScript-string length for one LLM-produced structured response. */
+export const MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH = 100_000;
+
+/** Count Unicode code points without allocating an intermediate character array. */
+export function deepInterviewCharacterCount(value: string): number {
+	let count = 0;
+	for (const _character of value) count++;
+	return count;
+}
+
+export function isDeepInterviewFreeTextField(name: string): boolean {
+	return DEEP_INTERVIEW_FREETEXT_FIELDS.has(name);
+}
+
+/**
+ * Assert that one structured deep-interview response is JSON-serializable and
+ * bounded by JavaScript string length. This deliberately does not measure or
+ * cap accumulated persisted interview state.
+ */
+export function assertDeepInterviewStructuredResponseWithinLimit(value: unknown): void {
+	let serialized: string | undefined;
+	try {
+		serialized = JSON.stringify(value, (_key, nestedValue: unknown) => {
+			if (
+				typeof nestedValue === "bigint" ||
+				typeof nestedValue === "function" ||
+				typeof nestedValue === "symbol" ||
+				(typeof nestedValue === "number" && !Number.isFinite(nestedValue))
+			)
+				throw new Error("invalid structured deep-interview response");
+			return nestedValue;
+		});
+	} catch {
+		throw new Error("invalid structured deep-interview response");
+	}
+	if (typeof serialized !== "string") throw new Error("invalid structured deep-interview response");
+	if (deepInterviewCharacterCount(serialized) > MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH)
+		throw new Error(
+			`structured deep-interview response exceeds max length ${MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH}`,
+		);
+}
+
+/**
+ * Assert a free-text input is within its size cap. Never inspects content for shell
+ * metacharacters — free-text fields accept prose verbatim; this only bounds length.
+ */
+export function assertDeepInterviewInputWithinLimit(value: string, max: number, fieldName = "input"): void {
+	if (typeof value !== "string") throw new Error(`${fieldName} must be a string`);
+	if (deepInterviewCharacterCount(value) > max) throw new Error(`${fieldName} exceeds max length ${max}`);
+}
+
+/** Validate user-supplied deep-interview prose before an envelope is persisted. */
+export function assertDeepInterviewEnvelopeInputLimits(envelope: Record<string, unknown>): void {
+	const state =
+		typeof envelope.state === "object" && envelope.state !== null && !Array.isArray(envelope.state)
+			? (envelope.state as Record<string, unknown>)
+			: {};
+	for (const field of ["initial_idea", "initial_context", "initial_context_summary"] as const) {
+		const nestedValue = state[field];
+		if (nestedValue !== undefined)
+			assertDeepInterviewInputWithinLimit(nestedValue as string, MAX_INITIAL_CONTEXT_LENGTH, `state.${field}`);
+		const topLevelValue = envelope[field];
+		if (topLevelValue !== undefined)
+			assertDeepInterviewInputWithinLimit(topLevelValue as string, MAX_INITIAL_CONTEXT_LENGTH, field);
+	}
+	for (const field of ["user_response", "answer"] as const) {
+		const nestedValue = state[field];
+		if (nestedValue !== undefined)
+			assertDeepInterviewInputWithinLimit(nestedValue as string, MAX_USER_RESPONSE_LENGTH, `state.${field}`);
+		const topLevelValue = envelope[field];
+		if (topLevelValue !== undefined)
+			assertDeepInterviewInputWithinLimit(topLevelValue as string, MAX_USER_RESPONSE_LENGTH, field);
+	}
+	if (!Array.isArray(state.rounds)) return;
+	for (const [index, round] of state.rounds.entries()) {
+		if (typeof round !== "object" || round === null || Array.isArray(round)) continue;
+		const record = round as Record<string, unknown>;
+		for (const field of ["custom_input", "customInput", "user_response", "answer"] as const) {
+			const value = record[field];
+			// A structured scorer may use an unrelated object-valued `answer`; only prose
+			// values in a legacy answer slot are user input subject to this cap.
+			if (value === undefined || (field === "answer" && typeof value !== "string")) continue;
+			assertDeepInterviewInputWithinLimit(
+				value as string,
+				MAX_USER_RESPONSE_LENGTH,
+				`state.rounds[${index}].${field}`,
+			);
+		}
+	}
+}
+
 export interface DeepInterviewIntentItem {
 	id: string;
 	category: DeepInterviewIntentCategory;
@@ -437,7 +557,7 @@ export function isCanonicalDeepInterviewAnswerHash(value: unknown): value is str
 function isEvidenceReference(value: unknown, answerHashValue: string): value is string {
 	return (
 		typeof value === "string" &&
-		value.length <= MAX_INTENT_EVIDENCE_LENGTH &&
+		deepInterviewCharacterCount(value) <= MAX_INTENT_EVIDENCE_LENGTH &&
 		value === `answer_hash:${answerHashValue}`
 	);
 }
@@ -451,7 +571,11 @@ function assertIntentItem(value: unknown): asserts value is DeepInterviewIntentI
 		!id.startsWith(`${category}:`)
 	)
 		throw new Error("invalid intent category");
-	if (typeof statement !== "string" || !statement.trim() || statement.length > MAX_INTENT_STATEMENT_LENGTH)
+	if (
+		typeof statement !== "string" ||
+		!statement.trim() ||
+		deepInterviewCharacterCount(statement) > MAX_INTENT_STATEMENT_LENGTH
+	)
 		throw new Error(`intent item ${id} requires a bounded statement`);
 }
 
@@ -541,7 +665,7 @@ export function reviewDeepInterviewIntent(
 			substitution.replacement_ids.some(id => typeof id !== "string" || !observedIds.has(id)) ||
 			typeof substitution.rationale !== "string" ||
 			!substitution.rationale.trim() ||
-			substitution.rationale.length > MAX_INTENT_RATIONALE_LENGTH
+			deepInterviewCharacterCount(substitution.rationale) > MAX_INTENT_RATIONALE_LENGTH
 		)
 			throw new Error("invalid intent substitution");
 	}

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

@@ -39,7 +39,11 @@ function renderRecord(record: GcRecord): string {
 
 export function buildGcReportText(report: GcReport): string {
 	const lines: string[] = [];
-	lines.push(report.dry_run ? "gjc gc — dry run (no changes made; pass --prune to remove)" : "gjc gc — prune");
+	if (report.operation === "repair_session_index") {
+		lines.push("gjc gc — session-index repair (other stores are report-only)");
+	} else {
+		lines.push(report.dry_run ? "gjc gc — dry run (no changes made; pass --prune to remove)" : "gjc gc — prune");
+	}
 	lines.push("");
 
 	for (const store of GC_STORES) {
@@ -53,6 +57,20 @@ export function buildGcReportText(report: GcReport): string {
 		lines.push("");
 	}
 
+	if (report.session_index) {
+		const index = report.session_index;
+		lines.push(`Session index: ${index.status}; valid prefix sequence=${index.valid_prefix_seq}`);
+		if (index.quarantine_path) lines.push(`  Quarantined suffix: ${index.quarantine_path}`);
+		if (index.reason) lines.push(`  ${index.reason}`);
+		if (index.status === "corrupt")
+			lines.push("  Run `gjc gc --repair-session-index` to quarantine the corrupt suffix.");
+		if (index.status === "unsupported")
+			lines.push("  Upgrade GJC before attempting a repair; no index data was changed.");
+		if (index.status === "repaired")
+			lines.push("  Restart or re-register hosts whose only registration was in the quarantined suffix.");
+		lines.push("");
+	}
+
 	if (report.errors.length > 0) {
 		lines.push(`Errors (${report.errors.length})`);
 		for (const err of report.errors) lines.push(`  [${err.store}/${err.scope}] ${err.message}`);

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

@@ -13,6 +13,10 @@
  * - Dry-run by default: nothing is deleted unless `--prune`/`--force`.
  */
 
+import { getAgentDir } from "@gajae-code/utils";
+import { SessionIndex } from "../sdk/broker/session-index";
+import { UnsupportedStateVersionError } from "../sdk/broker/state-version";
+
 import { buildGcReportText } from "./gc-render";
 
 export type GcStore = "harness_leases" | "team_workers" | "file_locks" | "tmux_sessions" | "registry_entries";
@@ -115,11 +119,21 @@ export interface GcCounts {
 	>;
 }
 
+export interface GcSessionIndexHealth {
+	status: "healthy" | "corrupt" | "repaired" | "unsupported" | "repair_failed";
+	valid_prefix_seq: number;
+	snapshot_seq?: number;
+	reason?: string;
+	quarantine_path?: string;
+}
+
 export interface GcReport {
 	dry_run: boolean;
+	operation?: "dry_run" | "prune" | "repair_session_index";
 	stores: Record<GcStore, GcRecord[]>;
 	counts: GcCounts;
 	errors: GcError[];
+	session_index?: GcSessionIndexHealth;
 }
 
 export interface GcRunResult {
@@ -225,6 +239,7 @@ function computeCounts(stores: Record<GcStore, GcRecord[]>, errors: GcError[]):
 interface ParsedGcArgs {
 	json: boolean;
 	prune: boolean;
+	repairSessionIndex: boolean;
 	help: boolean;
 }
 
@@ -233,6 +248,8 @@ class GcUsageError extends Error {}
 function parseGcArgs(argv: string[]): ParsedGcArgs {
 	let json = false;
 	let prune = false;
+	let repairSessionIndex = false;
+
 	let dryRun = false;
 	let help = false;
 	for (const arg of argv) {
@@ -245,6 +262,10 @@ function parseGcArgs(argv: string[]): ParsedGcArgs {
 			case "--force":
 				prune = true;
 				break;
+			case "--repair-session-index":
+				repairSessionIndex = true;
+				break;
+
 			case "--dry-run":
 				dryRun = true;
 				break;
@@ -256,9 +277,11 @@ function parseGcArgs(argv: string[]): ParsedGcArgs {
 				throw new GcUsageError(`unknown_flag:${arg}`);
 		}
 	}
+	if (repairSessionIndex && prune) throw new GcUsageError("repair_session_index_cannot_combine_with_prune");
+	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, help };
+	return { json, prune, repairSessionIndex, help };
 }
 
 /**
@@ -336,6 +359,40 @@ export function computeExitCode(report: GcReport): number {
 	return 0;
 }
 
+function resolveGcAgentDir(env: NodeJS.ProcessEnv): string {
+	return env.GJC_CODING_AGENT_DIR?.trim() || env.PI_CODING_AGENT_DIR?.trim() || getAgentDir();
+}
+
+async function collectSessionIndexHealth(repair: boolean, agentDir: string): Promise<GcSessionIndexHealth> {
+	const index = new SessionIndex(agentDir);
+	try {
+		if (repair) {
+			const result = await index.repair();
+			return {
+				status: result.status === "unsupported" ? "unsupported" : result.repaired ? "repaired" : "healthy",
+				valid_prefix_seq: result.validPrefixSeq,
+				snapshot_seq: result.snapshotSeq,
+				...(result.reason ? { reason: result.reason } : {}),
+				...(result.quarantinePath ? { quarantine_path: result.quarantinePath } : {}),
+			};
+		}
+		const diagnosis = await index.diagnose();
+		return {
+			status: diagnosis.status,
+			valid_prefix_seq: diagnosis.validPrefixSeq,
+			snapshot_seq: diagnosis.snapshotSeq,
+			...(diagnosis.reason ? { reason: diagnosis.reason } : {}),
+		};
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return {
+			status: error instanceof UnsupportedStateVersionError ? "unsupported" : "repair_failed",
+			valid_prefix_seq: 0,
+			reason,
+		};
+	}
+}
+
 export async function runGjcGcCommand(
 	argv: string[],
 	cwd: string = process.cwd(),
@@ -357,7 +414,13 @@ export async function runGjcGcCommand(
 	const resolvedAdapters = adapters ?? (await defaultGcAdapters());
 	const ctx: GcContext = { probe: gcPidProbe, force: parsed.prune, env, cwd };
 	const report = await collectGcReport(resolvedAdapters, ctx, parsed.prune);
-	const status = computeExitCode(report);
+	report.operation = parsed.repairSessionIndex ? "repair_session_index" : parsed.prune ? "prune" : "dry_run";
+	report.session_index = await collectSessionIndexHealth(parsed.repairSessionIndex, resolveGcAgentDir(env));
+	const sessionIndexFailed =
+		report.session_index?.status === "corrupt" ||
+		report.session_index?.status === "unsupported" ||
+		report.session_index?.status === "repair_failed";
+	const status = sessionIndexFailed ? 1 : computeExitCode(report);
 	const stdout = parsed.json ? `${JSON.stringify(report, null, 2)}\n` : buildGcReportText(report);
 	return { stdout, stderr: "", status };
 }
@@ -367,12 +430,14 @@ export function gcHelpText(): string {
 		"gjc gc - garbage-collect stale GJC session/PID records",
 		"",
 		"USAGE",
-		"  $ gjc gc [--prune|--force] [--json]",
+		"  $ gjc gc [--prune|--force] [--repair-session-index] [--json]",
+
 		"",
 		"FLAGS",
 		"  --prune, --force  Actually remove stale records (default: dry-run report only)",
 		"  --dry-run         Force report-only mode (overrides --prune/--force)",
 		"  -j, --json        Emit machine-readable JSON",
+		"  --repair-session-index  Explicitly quarantine a corrupt session-index suffix and retain its valid prefix",
 		"",
 		"Liveness-only: a record is removed only when its owning process is dead",
 		"(ESRCH). Live / permission-denied / unknown processes are always kept.",