@sayknow-cli/coding-agent 0.3.16 → 0.4.1

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

@@ -102,7 +102,9 @@ export function questionHash(questionText: string): string {
 }
 
 export function answerHash(selectedOptions: string[] | undefined, customInput: string | undefined): string {
-	return hashContent(JSON.stringify({ selected: selectedOptions ?? [], custom: customInput ?? null }));
+	return createHash("sha256")
+		.update(JSON.stringify({ selected: selectedOptions ?? [], custom: customInput ?? null }))
+		.digest("hex");
 }
 
 /**
@@ -335,9 +337,30 @@ export function mergeDeepInterviewEnvelope(
 	const incomingHasEstablishedFacts =
 		Object.hasOwn(incomingNestedState, "established_facts") || Object.hasOwn(incomingEnvelope, "established_facts");
 	const normalizedIncoming = normalizeDeepInterviewEnvelope(incoming);
-	if (options.replace) return normalizedIncoming;
-
 	const normalizedExisting = normalizeDeepInterviewEnvelope(existing);
+	const existingState = isPlainObject(normalizedExisting.state) ? normalizedExisting.state : {};
+	const incomingState = isPlainObject(normalizedIncoming.state) ? { ...normalizedIncoming.state } : {};
+	if (existingState.intent_contract !== undefined) {
+		assertDeepInterviewIntentManifest(existingState.intent_contract);
+		if (Object.hasOwn(incomingState, "intent_contract")) {
+			if (incomingState.intent_contract === null) throw new Error("locked intent contract cannot be deleted");
+			assertDeepInterviewIntentManifest(incomingState.intent_contract);
+			if (
+				incomingState.intent_contract.digest !== existingState.intent_contract.digest ||
+				incomingState.intent_contract.confirmation_answer_hash !==
+					existingState.intent_contract.confirmation_answer_hash
+			)
+				throw new Error("locked intent contract cannot be replaced");
+		} else {
+			incomingState.intent_contract = existingState.intent_contract;
+		}
+	}
+	if (existingState.intent_contract_required === true) incomingState.intent_contract_required = true;
+	if (options.replace) {
+		normalizedIncoming.state = incomingState;
+		return normalizedIncoming;
+	}
+
 	const merged: Record<string, unknown> = {};
 	for (const [key, value] of Object.entries(normalizedExisting)) {
 		if (key !== "state") merged[key] = value;
@@ -348,8 +371,6 @@ export function mergeDeepInterviewEnvelope(
 		else merged[key] = value;
 	}
 
-	const existingState = isPlainObject(normalizedExisting.state) ? normalizedExisting.state : {};
-	const incomingState = isPlainObject(normalizedIncoming.state) ? normalizedIncoming.state : {};
 	const mergedState: Record<string, unknown> = { ...existingState };
 	for (const [key, value] of Object.entries(incomingState)) {
 		if (key === "rounds") continue;
@@ -364,3 +385,418 @@ export function mergeDeepInterviewEnvelope(
 	merged.state = mergedState;
 	return merged as DeepInterviewStateEnvelope;
 }
+
+export const DEEP_INTERVIEW_INTENT_CATEGORIES = ["artifact", "surface", "integration", "constraint"] as const;
+export type DeepInterviewIntentCategory = (typeof DEEP_INTERVIEW_INTENT_CATEGORIES)[number];
+
+const INTENT_ID_RE = /^(artifact|surface|integration|constraint):[a-z0-9][a-z0-9._/-]{0,127}$/;
+const ANSWER_HASH_RE = /^[a-f0-9]{64}$/;
+const INTENT_RATIONALE_REF_RE = /^sha256:[a-f0-9]{64}$/;
+const MAX_INTENT_ITEMS = 64;
+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;
+	statement: string;
+}
+
+export interface DeepInterviewIntentManifest {
+	version: 1;
+	items: DeepInterviewIntentItem[];
+	digest: string;
+	confirmation_round: 0;
+	confirmation_answer_hash: string;
+	confirmation_evidence: string;
+}
+
+export interface DeepInterviewIntentSubstitution {
+	removed_id: string;
+	replacement_ids: string[];
+	rationale: string;
+}
+
+export interface DeepInterviewIntentReview {
+	version: 1;
+	status: "not_required" | "pending" | "approved";
+	locked_digest: string;
+	observed_digest: string;
+	removed_locked_ids: string[];
+	supporting_substitutions: DeepInterviewIntentSubstitution[];
+	approval_round?: number;
+	answer_hash?: string;
+	user_answer_evidence?: string;
+}
+
+export function isCanonicalDeepInterviewAnswerHash(value: unknown): value is string {
+	return typeof value === "string" && ANSWER_HASH_RE.test(value);
+}
+
+function isEvidenceReference(value: unknown, answerHashValue: string): value is string {
+	return (
+		typeof value === "string" &&
+		deepInterviewCharacterCount(value) <= MAX_INTENT_EVIDENCE_LENGTH &&
+		value === `answer_hash:${answerHashValue}`
+	);
+}
+
+function assertIntentItem(value: unknown): asserts value is DeepInterviewIntentItem {
+	if (!isPlainObject(value) || Object.keys(value).length !== 3) throw new Error("invalid intent item");
+	const { id, category, statement } = value;
+	if (typeof id !== "string" || !INTENT_ID_RE.test(id)) throw new Error("invalid intent id");
+	if (
+		!DEEP_INTERVIEW_INTENT_CATEGORIES.includes(category as DeepInterviewIntentCategory) ||
+		!id.startsWith(`${category}:`)
+	)
+		throw new Error("invalid intent category");
+	if (
+		typeof statement !== "string" ||
+		!statement.trim() ||
+		deepInterviewCharacterCount(statement) > MAX_INTENT_STATEMENT_LENGTH
+	)
+		throw new Error(`intent item ${id} requires a bounded statement`);
+}
+
+function canonicalIntentItems(items: readonly DeepInterviewIntentItem[]): DeepInterviewIntentItem[] {
+	return [...items]
+		.map(item => ({ id: item.id.trim(), category: item.category, statement: item.statement.trim() }))
+		.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function deepInterviewIntentManifestDigest(items: readonly DeepInterviewIntentItem[]): string {
+	return createHash("sha256")
+		.update(JSON.stringify(canonicalIntentItems(items)))
+		.digest("hex");
+}
+
+export function deepInterviewObservedIntentDigest(ids: readonly string[]): string {
+	return createHash("sha256")
+		.update(JSON.stringify([...new Set(ids)].sort()))
+		.digest("hex");
+}
+
+export function createDeepInterviewIntentManifest(
+	items: readonly DeepInterviewIntentItem[],
+	confirmation: { round: 0; answer_hash: string },
+): DeepInterviewIntentManifest {
+	if (!Array.isArray(items) || items.length === 0 || items.length > MAX_INTENT_ITEMS)
+		throw new Error("intent manifest requires bounded items");
+	if (confirmation.round !== 0 || !isCanonicalDeepInterviewAnswerHash(confirmation.answer_hash))
+		throw new Error("intent confirmation requires Round 0 canonical answer hash");
+	const canonical = canonicalIntentItems(items);
+	const ids = new Set<string>();
+	for (const item of canonical) {
+		assertIntentItem(item);
+		if (ids.has(item.id)) throw new Error(`duplicate intent id: ${item.id}`);
+		ids.add(item.id);
+	}
+	return {
+		version: 1,
+		items: canonical,
+		digest: deepInterviewIntentManifestDigest(canonical),
+		confirmation_round: 0,
+		confirmation_answer_hash: confirmation.answer_hash,
+		confirmation_evidence: `answer_hash:${confirmation.answer_hash}`,
+	};
+}
+
+export function assertDeepInterviewIntentManifest(value: unknown): asserts value is DeepInterviewIntentManifest {
+	if (!isPlainObject(value) || Object.keys(value).length !== 6 || value.version !== 1 || !Array.isArray(value.items))
+		throw new Error("invalid intent contract");
+	const manifest = createDeepInterviewIntentManifest(value.items as DeepInterviewIntentItem[], {
+		round: value.confirmation_round as 0,
+		answer_hash: value.confirmation_answer_hash as string,
+	});
+	if (
+		value.digest !== manifest.digest ||
+		value.confirmation_round !== 0 ||
+		!isEvidenceReference(value.confirmation_evidence, manifest.confirmation_answer_hash)
+	)
+		throw new Error("intent contract integrity mismatch");
+}
+
+export function reviewDeepInterviewIntent(
+	locked: DeepInterviewIntentManifest,
+	observedItems: readonly DeepInterviewIntentItem[],
+	input: Omit<DeepInterviewIntentReview, "version" | "locked_digest" | "observed_digest" | "removed_locked_ids">,
+): DeepInterviewIntentReview {
+	assertDeepInterviewIntentManifest(locked);
+	const observed = createDeepInterviewIntentManifest(observedItems, {
+		round: 0,
+		answer_hash: locked.confirmation_answer_hash,
+	});
+	const observedIds = new Set(observed.items.map(item => item.id));
+	const removed = locked.items
+		.map(item => item.id)
+		.filter(id => !observedIds.has(id))
+		.sort();
+	const substitutions = input.supporting_substitutions;
+	if (!Array.isArray(substitutions)) throw new Error("invalid intent substitutions");
+	const substitutionIds = new Set(substitutions.map(item => item.removed_id));
+	if (substitutionIds.size !== substitutions.length) throw new Error("duplicate intent substitution");
+	for (const substitution of substitutions) {
+		if (!isPlainObject(substitution) || !removed.includes(substitution.removed_id))
+			throw new Error("substitution does not bind removed intent");
+		if (
+			!Array.isArray(substitution.replacement_ids) ||
+			substitution.replacement_ids.length === 0 ||
+			substitution.replacement_ids.some(id => typeof id !== "string" || !observedIds.has(id)) ||
+			typeof substitution.rationale !== "string" ||
+			!substitution.rationale.trim() ||
+			deepInterviewCharacterCount(substitution.rationale) > MAX_INTENT_RATIONALE_LENGTH
+		)
+			throw new Error("invalid intent substitution");
+	}
+	const redactedSubstitutions = substitutions.map(substitution => ({
+		removed_id: substitution.removed_id,
+		replacement_ids: [...new Set(substitution.replacement_ids)].sort(),
+		rationale: `sha256:${createHash("sha256").update(substitution.rationale.trim()).digest("hex")}`,
+	}));
+	if (input.status !== "not_required" && input.status !== "pending" && input.status !== "approved")
+		throw new Error("invalid intent review status");
+	if (input.status === "not_required") {
+		if (
+			removed.length > 0 ||
+			substitutions.length > 0 ||
+			input.approval_round !== undefined ||
+			input.answer_hash !== undefined ||
+			input.user_answer_evidence !== undefined
+		)
+			throw new Error("not_required intent review cannot carry reduction evidence");
+	}
+	if (
+		input.status === "pending" &&
+		(input.approval_round !== undefined ||
+			input.answer_hash !== undefined ||
+			input.user_answer_evidence !== undefined)
+	)
+		throw new Error("pending intent review cannot carry approval evidence");
+	if (input.status === "approved") {
+		if (removed.some(id => !substitutionIds.has(id)))
+			throw new Error("approved intent reduction requires every substitution");
+		if (
+			typeof input.approval_round !== "number" ||
+			!Number.isFinite(input.approval_round) ||
+			!Number.isInteger(input.approval_round) ||
+			input.approval_round <= 0 ||
+			!isCanonicalDeepInterviewAnswerHash(input.answer_hash) ||
+			!isEvidenceReference(input.user_answer_evidence, input.answer_hash)
+		)
+			throw new Error("approved intent reduction requires durable redacted answer evidence");
+	}
+	return {
+		...input,
+		supporting_substitutions: redactedSubstitutions,
+		version: 1,
+		locked_digest: locked.digest,
+		observed_digest: deepInterviewObservedIntentDigest([...observedIds]),
+		removed_locked_ids: removed,
+	};
+}
+
+export function assertDeepInterviewIntentReview(
+	value: unknown,
+	locked: DeepInterviewIntentManifest,
+	observedIds: readonly string[],
+	recordedAnswers: readonly { round: unknown; answer_hash: unknown }[],
+): asserts value is DeepInterviewIntentReview {
+	assertDeepInterviewIntentManifest(locked);
+	if (!isPlainObject(value)) throw new Error("missing or invalid intent review");
+	const allowedKeys = new Set([
+		"version",
+		"status",
+		"locked_digest",
+		"observed_digest",
+		"removed_locked_ids",
+		"supporting_substitutions",
+		"approval_round",
+		"answer_hash",
+		"user_answer_evidence",
+	]);
+	if (Object.keys(value).some(key => !allowedKeys.has(key)) || value.version !== 1)
+		throw new Error("invalid intent review");
+	if (
+		value.locked_digest !== locked.digest ||
+		value.observed_digest !== deepInterviewObservedIntentDigest(observedIds)
+	)
+		throw new Error("stale intent review");
+	const observed = new Set(observedIds);
+	const removed = locked.items
+		.map(item => item.id)
+		.filter(id => !observed.has(id))
+		.sort();
+	if (
+		!Array.isArray(value.removed_locked_ids) ||
+		JSON.stringify([...value.removed_locked_ids].sort()) !== JSON.stringify(removed)
+	)
+		throw new Error("intent review removed IDs mismatch");
+	if (!Array.isArray(value.supporting_substitutions)) throw new Error("invalid intent substitutions");
+	const substitutions = value.supporting_substitutions;
+	const substitutionIds = new Set<string>();
+	for (const substitution of substitutions) {
+		if (!isPlainObject(substitution) || Object.keys(substitution).length !== 3)
+			throw new Error("invalid intent substitution");
+		const { removed_id, replacement_ids, rationale } = substitution;
+		if (
+			typeof removed_id !== "string" ||
+			!removed.includes(removed_id) ||
+			substitutionIds.has(removed_id) ||
+			!Array.isArray(replacement_ids) ||
+			replacement_ids.length === 0 ||
+			replacement_ids.some(id => typeof id !== "string" || !INTENT_ID_RE.test(id) || !observed.has(id)) ||
+			typeof rationale !== "string" ||
+			!INTENT_RATIONALE_REF_RE.test(rationale)
+		)
+			throw new Error("invalid intent substitution");
+		substitutionIds.add(removed_id);
+	}
+	if (value.status === "not_required") {
+		if (
+			removed.length > 0 ||
+			substitutions.length > 0 ||
+			value.approval_round !== undefined ||
+			value.answer_hash !== undefined ||
+			value.user_answer_evidence !== undefined
+		)
+			throw new Error("not_required intent review cannot carry reduction evidence");
+		return;
+	}
+	if (value.status !== "approved") {
+		if (value.status === "pending") throw new Error("intent reduction is pending or unapproved");
+		throw new Error("invalid intent review status");
+	}
+	if (removed.some(id => !substitutionIds.has(id)))
+		throw new Error("approved intent reduction requires every substitution");
+	if (
+		typeof value.approval_round !== "number" ||
+		!Number.isFinite(value.approval_round) ||
+		!Number.isInteger(value.approval_round) ||
+		value.approval_round <= 0 ||
+		!isCanonicalDeepInterviewAnswerHash(value.answer_hash) ||
+		!isEvidenceReference(value.user_answer_evidence, value.answer_hash) ||
+		!recordedAnswers.some(answer => answer.round === value.approval_round && answer.answer_hash === value.answer_hash)
+	)
+		throw new Error("intent review approval evidence is invalid");
+}

package/src/skc-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 ? "skc gc — dry run (no changes made; pass --prune to remove)" : "skc gc — prune");
+	if (report.operation === "repair_session_index") {
+		lines.push("skc gc — session-index repair (other stores are report-only)");
+	} else {
+		lines.push(report.dry_run ? "skc gc — dry run (no changes made; pass --prune to remove)" : "skc 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 `skc gc --repair-session-index` to quarantine the corrupt suffix.");
+		if (index.status === "unsupported")
+			lines.push("  Upgrade SKC 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/skc-runtime/gc-runtime.ts

@@ -13,6 +13,10 @@
  * - Dry-run by default: nothing is deleted unless `--prune`/`--force`.
  */
 
+import { getAgentDir } from "@sayknow-cli/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.SKC_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 runSkcGcCommand(
 	argv: string[],
 	cwd: string = process.cwd(),
@@ -357,7 +414,13 @@ export async function runSkcGcCommand(
 	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 {
 		"skc gc - garbage-collect stale SKC session/PID records",
 		"",
 		"USAGE",
-		"  $ skc gc [--prune|--force] [--json]",
+		"  $ skc 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.",