@gajae-code/coding-agent 0.11.2 → 0.11.4

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

package/src/gjc-runtime/state-argv.ts

@@ -0,0 +1,292 @@
+import { CANONICAL_GJC_WORKFLOW_SKILLS, type CanonicalGjcWorkflowSkill } from "../skill-state/canonical-skills";
+import { typedArgsFor } from "./workflow-manifest";
+
+export type StateAction =
+	| "read"
+	| "write"
+	| "clear"
+	| "contract"
+	| "handoff"
+	| "graph"
+	| "prune"
+	| "gc"
+	| "migrate"
+	| "status"
+	| "doctor";
+
+export const STATE_ACTION_NAMES: ReadonlySet<StateAction> = new Set([
+	"read",
+	"write",
+	"clear",
+	"contract",
+	"handoff",
+	"graph",
+	"prune",
+	"gc",
+	"migrate",
+	"status",
+	"doctor",
+]);
+
+export const STATE_FLAGS_WITH_VALUES: ReadonlySet<string> = new Set([
+	"--input",
+	"--mode",
+	"--session-id",
+	"--thread-id",
+	"--turn-id",
+	"--to",
+	"--skill",
+	"--format",
+	"--older-than",
+	"--status",
+	"--fields",
+	"--since",
+	"--limit",
+]);
+
+export const STATE_BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
+	"--json",
+	"--replace",
+	"--hard",
+	"--dry-run",
+	"--migrate",
+	"--compact",
+	"--history",
+	"--force",
+]);
+
+export interface StateFlagOccurrence {
+	name: string;
+	index: number;
+	value?: string;
+	arity: "boolean" | "value";
+	form: "separate" | "attached";
+	malformed: boolean;
+}
+
+export interface StateSelectorCandidate {
+	source: "mode" | "positional" | "input.mode" | "input.skill";
+	value: string | undefined;
+	index: number;
+}
+
+export type StateInputKind = "empty" | "inline" | "file" | "invalid";
+
+export interface StateInputClassification {
+	index: number;
+	raw: string;
+	kind: StateInputKind;
+	selectors: StateSelectorCandidate[];
+}
+
+export interface StateArgvClassification {
+	argv: readonly string[];
+	action: StateAction;
+	effectiveAction: StateAction;
+	positionalSkill?: string;
+	positionals: readonly string[];
+	flags: readonly StateFlagOccurrence[];
+	unknownFlags: readonly string[];
+	inputs: readonly StateInputClassification[];
+	runtimeSelectorCandidates: readonly StateSelectorCandidate[];
+	selectorCandidates: readonly StateSelectorCandidate[];
+}
+
+function normalizedFlagName(arg: string): string | undefined {
+	if (!arg.startsWith("--")) return undefined;
+	const equalsIndex = arg.indexOf("=");
+	return equalsIndex < 0 ? arg : arg.slice(0, equalsIndex);
+}
+
+function normalizedSelector(value: unknown): string | undefined {
+	return typeof value === "string" ? value.trim() || undefined : undefined;
+}
+
+interface StatePositional {
+	value: string;
+	index: number;
+}
+
+function parseRuntimePositionals(argv: readonly string[]): StatePositional[] {
+	const positionals: StatePositional[] = [];
+	let skipNext = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index]!;
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (STATE_FLAGS_WITH_VALUES.has(arg)) {
+			skipNext = true;
+			continue;
+		}
+		if (!arg.startsWith("-")) positionals.push({ value: arg, index });
+	}
+	return positionals;
+}
+
+function parseAction(positionals: readonly StatePositional[]): {
+	action: StateAction;
+	positionalSkill?: string;
+	positionalSkillIndex: number;
+} {
+	const [first, second] = positionals;
+	if (first?.value && STATE_ACTION_NAMES.has(first.value as StateAction)) {
+		return {
+			action: first.value as StateAction,
+			...(second?.value ? { positionalSkill: second.value } : {}),
+			positionalSkillIndex: second?.value ? second.index : -1,
+		};
+	}
+	if (first?.value && second?.value && STATE_ACTION_NAMES.has(second.value as StateAction)) {
+		return { action: second.value as StateAction, positionalSkill: first.value, positionalSkillIndex: first.index };
+	}
+	if (first?.value && !second?.value) {
+		return { action: "read", positionalSkill: first.value, positionalSkillIndex: first.index };
+	}
+	return { action: "read", positionalSkillIndex: -1 };
+}
+
+function stateFlagArities(
+	action: StateAction,
+	positionalSkill: string | undefined,
+): ReadonlyMap<string, "boolean" | "value"> {
+	const arities = new Map<string, "boolean" | "value">();
+	for (const flag of STATE_FLAGS_WITH_VALUES) arities.set(flag, "value");
+	for (const flag of STATE_BOOLEAN_FLAGS) arities.set(flag, "boolean");
+
+	const skills =
+		positionalSkill && CANONICAL_GJC_WORKFLOW_SKILLS.includes(positionalSkill as CanonicalGjcWorkflowSkill)
+			? [positionalSkill as CanonicalGjcWorkflowSkill]
+			: CANONICAL_GJC_WORKFLOW_SKILLS;
+	for (const skill of skills) {
+		for (const arg of typedArgsFor(skill, action)) {
+			const name = `--${arg.name}`;
+			if (!arities.has(name)) arities.set(name, arg.type === "boolean" ? "boolean" : "value");
+		}
+	}
+	return arities;
+}
+
+function classifyInput(occurrence: StateFlagOccurrence): StateInputClassification {
+	const raw = occurrence.value ?? "";
+	const trimmed = raw.trim();
+	if (!trimmed) return { index: occurrence.index, raw, kind: "empty", selectors: [] };
+	if (trimmed.startsWith("@")) return { index: occurrence.index, raw, kind: "file", selectors: [] };
+	try {
+		const payload = JSON.parse(trimmed) as unknown;
+		if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+			return { index: occurrence.index, raw, kind: "invalid", selectors: [] };
+		}
+		const record = payload as Record<string, unknown>;
+		return {
+			index: occurrence.index,
+			raw,
+			kind: "inline",
+			selectors: [
+				{ source: "input.mode", value: normalizedSelector(record.mode), index: occurrence.index },
+				{ source: "input.skill", value: normalizedSelector(record.skill), index: occurrence.index },
+			],
+		};
+	} catch {
+		return { index: occurrence.index, raw, kind: "invalid", selectors: [] };
+	}
+}
+
+export function firstStateFlagValue(classification: StateArgvClassification, name: string): string | undefined {
+	const index = classification.argv.indexOf(name);
+	return index < 0 ? undefined : classification.argv[index + 1];
+}
+
+export function classifyStateArgv(argv: readonly string[]): StateArgvClassification {
+	const preservedArgv = [...argv];
+	const positionalEntries = parseRuntimePositionals(preservedArgv);
+	const positionals = positionalEntries.map(positional => positional.value);
+	const { action, positionalSkill, positionalSkillIndex } = parseAction(positionalEntries);
+	const flagArities = stateFlagArities(action, positionalSkill);
+	const flags: StateFlagOccurrence[] = [];
+	const unknownFlags: string[] = [];
+
+	for (let index = 0; index < preservedArgv.length; index += 1) {
+		const arg = preservedArgv[index]!;
+		const name = normalizedFlagName(arg);
+		if (!name) continue;
+		const arity = flagArities.get(name);
+		if (!arity) {
+			unknownFlags.push(name);
+			continue;
+		}
+		if (arg !== name) {
+			flags.push({
+				name,
+				index,
+				value: arg.slice(name.length + 1),
+				arity,
+				form: "attached",
+				malformed: true,
+			});
+			continue;
+		}
+		if (arity === "boolean") {
+			flags.push({ name, index, arity, form: "separate", malformed: false });
+			continue;
+		}
+		const value = preservedArgv[index + 1];
+		flags.push({
+			name,
+			index,
+			...(value === undefined ? {} : { value }),
+			arity,
+			form: "separate",
+			malformed: value === undefined || value.startsWith("--"),
+		});
+	}
+	const effectiveAction = action === "read" && preservedArgv.includes("--migrate") ? "migrate" : action;
+
+	const modeFlags = flags.filter(flag => flag.name === "--mode" && flag.form === "separate");
+	const inputFlags = flags.filter(flag => flag.name === "--input" && flag.form === "separate");
+	const inputs = inputFlags.map(classifyInput);
+	const positionalCandidate: StateSelectorCandidate = {
+		source: "positional",
+		value: normalizedSelector(positionalSkill),
+		index: positionalSkillIndex,
+	};
+	const modeCandidates = modeFlags.map(flag => ({
+		source: "mode" as const,
+		value: normalizedSelector(flag.value),
+		index: flag.index,
+	}));
+	const selectorCandidates = [positionalCandidate, ...modeCandidates, ...inputs.flatMap(input => input.selectors)];
+	const firstModeIndex = preservedArgv.indexOf("--mode");
+	const firstModeCandidate: StateSelectorCandidate = {
+		source: "mode",
+		value: normalizedSelector(firstModeIndex < 0 ? undefined : preservedArgv[firstModeIndex + 1]),
+		index: firstModeIndex,
+	};
+	const firstInputIndex = preservedArgv.indexOf("--input");
+	const firstInput =
+		firstInputIndex < 0
+			? undefined
+			: classifyInput({
+					name: "--input",
+					index: firstInputIndex,
+					value: preservedArgv[firstInputIndex + 1],
+					arity: "value",
+					form: "separate",
+					malformed: false,
+				});
+	const runtimeSelectorCandidates = [firstModeCandidate, positionalCandidate, ...(firstInput?.selectors ?? [])];
+
+	return {
+		argv: preservedArgv,
+		action,
+		effectiveAction,
+		...(positionalSkill === undefined ? {} : { positionalSkill }),
+		positionals,
+		flags,
+		unknownFlags,
+		inputs,
+		runtimeSelectorCandidates,
+		selectorCandidates,
+	};
+}