@gajae-code/coding-agent 0.5.0 → 0.5.2

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

@@ -0,0 +1,403 @@
+/**
+ * `gjc gc` runtime — a global, liveness-only, dry-run-by-default garbage
+ * collector for stale GJC session/PID records.
+ *
+ * Design (see .gjc/plans/ralplan/2026-06-13-1347-954f/pending-approval.md):
+ * - This module is an ORCHESTRATOR only. It owns the shared PID probe, the
+ *   report/exit-code policy, and text/JSON rendering. It must NOT parse private
+ *   store layouts directly; every store is reached through an injectable
+ *   `GcStoreAdapter` that lives next to its store owner.
+ * - Liveness-only and fail-closed: only `ESRCH` (no such process) is `dead`
+ *   (removable). `process.kill(pid, 0)` success, `EPERM`, and any unknown probe
+ *   error all mean KEEP — a live process is never signalled or killed.
+ * - Dry-run by default: nothing is deleted unless `--prune`/`--force`.
+ */
+
+import { buildGcReportText } from "./gc-render";
+
+export type GcStore = "harness_leases" | "team_workers" | "file_locks" | "tmux_sessions" | "registry_entries";
+
+export const GC_STORES: readonly GcStore[] = [
+	"harness_leases",
+	"team_workers",
+	"file_locks",
+	"tmux_sessions",
+	"registry_entries",
+] as const;
+
+/** Why a probed pid is kept instead of treated as dead. */
+export type GcPidKeepReason = "alive" | "eperm" | "unknown";
+
+export interface GcPidProbeResult {
+	/** `dead` only on ESRCH; `keep` for alive/eperm/unknown (fail-closed). */
+	status: "dead" | "keep";
+	reason?: GcPidKeepReason;
+	error?: string;
+}
+
+/** Single shared liveness contract threaded through every classifier + prune path. */
+export type GcPidProbe = (pid: number) => GcPidProbeResult;
+
+export type GcPidStatus = "dead" | "alive" | "eperm" | "unknown" | "none";
+
+export type GcAction = "none" | "would_remove" | "removed" | "remove_failed" | "skipped";
+
+export interface GcRecord {
+	store: GcStore;
+	/** Stable identifier: session id, lock dir path, worker id, tmux name, registry session id. */
+	id: string;
+	path?: string;
+	root?: string;
+	pid?: number;
+	pid_status?: GcPidStatus;
+	/** Store-specific classification label (e.g. "dead", "live", "unclassified", "terminal_lifecycle"). */
+	status: string;
+	stale: boolean;
+	removable: boolean;
+	action: GcAction;
+	reason: string;
+	detail?: string;
+	error?: string;
+	removed?: boolean;
+}
+
+export interface GcError {
+	store: GcStore;
+	scope: string;
+	message: string;
+}
+
+export interface GcCollectResult {
+	records: GcRecord[];
+	errors: GcError[];
+}
+
+export interface GcPruneOutcome {
+	removed: boolean;
+	error?: string;
+	/** Set when a removable record was skipped at prune time (e.g. TOCTOU became live). */
+	skipped?: string;
+}
+
+export interface GcContext {
+	probe: GcPidProbe;
+	force: boolean;
+	env: NodeJS.ProcessEnv;
+	cwd: string;
+}
+
+/**
+ * A store-owned GC adapter. `collect` discovers + classifies (using the shared
+ * probe) without mutating anything. `prune` removes a single record, and MUST
+ * re-validate / re-probe immediately before any destructive action.
+ */
+export interface GcStoreAdapter {
+	store: GcStore;
+	collect(ctx: GcContext): Promise<GcCollectResult>;
+	prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome>;
+}
+
+export interface GcCounts {
+	discovered: number;
+	stale: number;
+	alive: number;
+	eperm: number;
+	unknown: number;
+	terminal_lifecycle: number;
+	unclassified: number;
+	would_remove: number;
+	removed: number;
+	failed: number;
+	errors: number;
+	by_store: Record<
+		GcStore,
+		{ discovered: number; stale: number; would_remove: number; removed: number; failed: number }
+	>;
+}
+
+export interface GcReport {
+	dry_run: boolean;
+	stores: Record<GcStore, GcRecord[]>;
+	counts: GcCounts;
+	errors: GcError[];
+}
+
+export interface GcRunResult {
+	stdout: string;
+	stderr: string;
+	status: number;
+}
+
+/**
+ * The shared, fail-closed PID probe. ESRCH => dead/removable; success => alive;
+ * EPERM => kept (owned by another user); any other error => kept as unknown.
+ */
+export const gcPidProbe: GcPidProbe = (pid: number): GcPidProbeResult => {
+	if (!Number.isInteger(pid) || pid <= 0) {
+		return { status: "keep", reason: "unknown", error: `invalid_pid:${pid}` };
+	}
+	try {
+		process.kill(pid, 0);
+		return { status: "keep", reason: "alive" };
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ESRCH") return { status: "dead" };
+		if (code === "EPERM") return { status: "keep", reason: "eperm" };
+		return { status: "keep", reason: "unknown", error: code ?? String(error) };
+	}
+};
+
+/** Map a `GcPidProbe` onto the harness lease probe shape (`"alive"|"dead"|"eperm"`). */
+export function gcProbeToLeasePidStatus(probe: GcPidProbe): (pid: number) => "alive" | "dead" | "eperm" {
+	return (pid: number) => {
+		const result = probe(pid);
+		if (result.status === "dead") return "dead";
+		// EPERM stays eperm; unknown maps to alive so classifyLeaseStatus keeps it.
+		return result.reason === "eperm" ? "eperm" : "alive";
+	};
+}
+
+/** Translate a probe result into a record-friendly pid status label. */
+export function gcPidStatusLabel(result: GcPidProbeResult): Exclude<GcPidStatus, "none"> {
+	if (result.status === "dead") return "dead";
+	return result.reason ?? "alive";
+}
+
+function emptyByStore(): GcCounts["by_store"] {
+	const by = {} as GcCounts["by_store"];
+	for (const store of GC_STORES) {
+		by[store] = { discovered: 0, stale: 0, would_remove: 0, removed: 0, failed: 0 };
+	}
+	return by;
+}
+
+function emptyStores(): Record<GcStore, GcRecord[]> {
+	const stores = {} as Record<GcStore, GcRecord[]>;
+	for (const store of GC_STORES) stores[store] = [];
+	return stores;
+}
+
+function computeCounts(stores: Record<GcStore, GcRecord[]>, errors: GcError[]): GcCounts {
+	const counts: GcCounts = {
+		discovered: 0,
+		stale: 0,
+		alive: 0,
+		eperm: 0,
+		unknown: 0,
+		terminal_lifecycle: 0,
+		unclassified: 0,
+		would_remove: 0,
+		removed: 0,
+		failed: 0,
+		errors: errors.length,
+		by_store: emptyByStore(),
+	};
+	for (const store of GC_STORES) {
+		for (const record of stores[store]) {
+			counts.discovered++;
+			counts.by_store[store].discovered++;
+			if (record.stale) {
+				counts.stale++;
+				counts.by_store[store].stale++;
+			}
+			if (record.pid_status === "alive") counts.alive++;
+			else if (record.pid_status === "eperm") counts.eperm++;
+			else if (record.pid_status === "unknown") counts.unknown++;
+			if (record.status === "terminal_lifecycle") counts.terminal_lifecycle++;
+			if (record.status === "unclassified") counts.unclassified++;
+			if (record.action === "would_remove") {
+				counts.would_remove++;
+				counts.by_store[store].would_remove++;
+			}
+			if (record.action === "removed") {
+				counts.removed++;
+				counts.by_store[store].removed++;
+			}
+			if (record.action === "remove_failed") {
+				counts.failed++;
+				counts.by_store[store].failed++;
+			}
+		}
+	}
+	return counts;
+}
+
+interface ParsedGcArgs {
+	json: boolean;
+	prune: boolean;
+	help: boolean;
+}
+
+class GcUsageError extends Error {}
+
+function parseGcArgs(argv: string[]): ParsedGcArgs {
+	let json = false;
+	let prune = false;
+	let dryRun = false;
+	let help = false;
+	for (const arg of argv) {
+		switch (arg) {
+			case "--json":
+			case "-j":
+				json = true;
+				break;
+			case "--prune":
+			case "--force":
+				prune = true;
+				break;
+			case "--dry-run":
+				dryRun = true;
+				break;
+			case "--help":
+			case "-h":
+				help = true;
+				break;
+			default:
+				throw new GcUsageError(`unknown_flag:${arg}`);
+		}
+	}
+	// Explicit --dry-run always wins over --prune/--force.
+	if (dryRun) prune = false;
+	return { json, prune, help };
+}
+
+/**
+ * Collect every store's records (catching hard discovery errors per adapter),
+ * then optionally prune removable records with per-record revalidation.
+ */
+export async function collectGcReport(adapters: GcStoreAdapter[], ctx: GcContext, prune: boolean): Promise<GcReport> {
+	const stores = emptyStores();
+	const errors: GcError[] = [];
+
+	for (const adapter of adapters) {
+		try {
+			const result = await adapter.collect(ctx);
+			stores[adapter.store].push(...result.records);
+			errors.push(...result.errors);
+		} catch (error) {
+			errors.push({
+				store: adapter.store,
+				scope: "collect",
+				message: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	// Mark dry-run intent on every removable record before pruning.
+	for (const store of GC_STORES) {
+		for (const record of stores[store]) {
+			if (record.removable) record.action = "would_remove";
+		}
+	}
+
+	if (prune) {
+		const adapterByStore = new Map(adapters.map(a => [a.store, a] as const));
+		for (const store of GC_STORES) {
+			const adapter = adapterByStore.get(store);
+			if (!adapter) continue;
+			for (const record of stores[store]) {
+				if (!record.removable) continue;
+				try {
+					const outcome = await adapter.prune(record, ctx);
+					if (outcome.removed) {
+						record.action = "removed";
+						record.removed = true;
+					} else if (outcome.skipped) {
+						record.action = "skipped";
+						record.reason = outcome.skipped;
+						record.removed = false;
+					} else {
+						record.action = "remove_failed";
+						record.removed = false;
+						record.error = outcome.error ?? "remove_failed";
+					}
+				} catch (error) {
+					record.action = "remove_failed";
+					record.removed = false;
+					record.error = error instanceof Error ? error.message : String(error);
+				}
+			}
+		}
+	}
+
+	return { dry_run: !prune, stores, counts: computeCounts(stores, errors), errors };
+}
+
+/**
+ * Exit-code policy:
+ * - usage/parse error => 2
+ * - hard discovery errors => 1 (both modes)
+ * - prune mode with a failed intended removal => 1
+ * - otherwise => 0
+ */
+export function computeExitCode(report: GcReport): number {
+	if (report.errors.length > 0) return 1;
+	if (!report.dry_run && report.counts.failed > 0) return 1;
+	return 0;
+}
+
+export async function runGjcGcCommand(
+	argv: string[],
+	cwd: string = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+	adapters?: GcStoreAdapter[],
+): Promise<GcRunResult> {
+	let parsed: ParsedGcArgs;
+	try {
+		parsed = parseGcArgs(argv);
+	} catch (error) {
+		const message = error instanceof GcUsageError ? error.message : String(error);
+		return { stdout: "", stderr: `gjc gc: ${message}\n`, status: 2 };
+	}
+
+	if (parsed.help) {
+		return { stdout: gcHelpText(), stderr: "", status: 0 };
+	}
+
+	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);
+	const stdout = parsed.json ? `${JSON.stringify(report, null, 2)}\n` : buildGcReportText(report);
+	return { stdout, stderr: "", status };
+}
+
+export function gcHelpText(): string {
+	return [
+		"gjc gc - garbage-collect stale GJC session/PID records",
+		"",
+		"USAGE",
+		"  $ gjc gc [--prune|--force] [--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",
+		"",
+		"Liveness-only: a record is removed only when its owning process is dead",
+		"(ESRCH). Live / permission-denied / unknown processes are always kept.",
+		"",
+	].join("\n");
+}
+
+/** Lazily assemble the real store adapters (kept lazy to avoid import cycles). */
+export async function defaultGcAdapters(): Promise<GcStoreAdapter[]> {
+	const [
+		{ harnessLeasesGcAdapter, registryEntriesGcAdapter },
+		{ fileLocksGcAdapter },
+		{ teamWorkersGcAdapter },
+		{ tmuxSessionsGcAdapter },
+	] = await Promise.all([
+		import("../harness-control-plane/gc-adapter"),
+		import("../config/file-lock-gc"),
+		import("./team-gc"),
+		import("./tmux-gc"),
+	]);
+	return [
+		harnessLeasesGcAdapter,
+		teamWorkersGcAdapter,
+		fileLocksGcAdapter,
+		tmuxSessionsGcAdapter,
+		registryEntriesGcAdapter,
+	];
+}

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

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { safeStderrWrite } from "@gajae-code/utils";
 import type { Args } from "../cli/args";
 import {
 	buildGjcTmuxProfileCommands,
@@ -280,7 +281,7 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			cleanupCreatedTmuxSession(plan, spawnSync, options);
 			const failure =
 				profile.failures.find(item => item.command.args.includes("@gjc-profile")) ?? profile.failures[0];
-			(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
+			(context.diagnosticWriter ?? safeStderrWrite)(
 				formatTmuxLaunchDiagnostic("profile tagging failed", failure?.stderr),
 			);
 			return true;
@@ -289,8 +290,6 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 	if (created.exitCode !== 0) return false;
 	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", plan.sessionName], options);
 	if (attached.exitCode === 0) return true;
-	(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
-		formatTmuxLaunchDiagnostic("attach failed", attached.stderr),
-	);
+	(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach failed", attached.stderr));
 	return true;
 }

package/src/gjc-runtime/ledger-event-renderer.ts

@@ -0,0 +1,164 @@
+/**
+ * Pure parse + summarize for ledger-backed skill observability.
+ *
+ * Workflow progress for ultragoal/ralplan cannot be observed via subagent tool
+ * events (those skills persist through `bash`-backed `gjc` CLI calls whose tool
+ * `details` carry no structured payload). The durable source of truth is the
+ * append-only ledgers:
+ *   - ultragoal: `.gjc/ultragoal/ledger.jsonl`
+ *   - ralplan:   `.gjc/plans/ralplan/<run-id>/index.jsonl`
+ *
+ * This module is I/O-free: callers read the files and pass lines or already-parsed
+ * rows. It feeds the compact HUD chip builders in `skill-state/workflow-hud.ts`
+ * via the runtime sync paths. Display-string helpers stay theme-free.
+ */
+
+/* ------------------------------- ultragoal ------------------------------- */
+
+/** Minimal projection of an ultragoal ledger row used for the HUD chip. */
+export interface UltragoalLedgerEventLite {
+	/** Normalized from the row's `event` field, or `type` for reconcile rows. */
+	event: string;
+	goalId?: string;
+	status?: string;
+	timestamp?: string;
+}
+
+/**
+ * Coerce an already-parsed ledger row into the lite shape. Accepts both the
+ * `event`-keyed vocabulary (plan_created, goal_started, goal_checkpointed,
+ * steering_accepted/rejected, review_blockers_recorded) and the `type`-keyed
+ * reconcile-failure row (`type: "reconcile_failed"`). Returns undefined when no
+ * event/type discriminator is present.
+ */
+export function coerceUltragoalLedgerEvent(row: Record<string, unknown>): UltragoalLedgerEventLite | undefined {
+	const event = typeof row.event === "string" ? row.event : typeof row.type === "string" ? row.type : undefined;
+	if (!event) return undefined;
+	const lite: UltragoalLedgerEventLite = { event };
+	if (typeof row.goalId === "string") lite.goalId = row.goalId;
+	if (typeof row.status === "string") lite.status = row.status;
+	if (typeof row.timestamp === "string") lite.timestamp = row.timestamp;
+	return lite;
+}
+
+/** Parse a single ultragoal ledger JSONL line; undefined for blank/malformed lines. */
+export function parseUltragoalLedgerLine(line: string): UltragoalLedgerEventLite | undefined {
+	const trimmed = line.trim();
+	if (!trimmed) return undefined;
+	let row: unknown;
+	try {
+		row = JSON.parse(trimmed);
+	} catch {
+		return undefined;
+	}
+	if (!row || typeof row !== "object" || Array.isArray(row)) return undefined;
+	return coerceUltragoalLedgerEvent(row as Record<string, unknown>);
+}
+
+/** The most recent event, or undefined when the ledger is empty. */
+export function latestUltragoalLedgerEvent(
+	events: readonly UltragoalLedgerEventLite[],
+): UltragoalLedgerEventLite | undefined {
+	return events.length > 0 ? events[events.length - 1] : undefined;
+}
+
+/**
+ * Best-effort latest event from raw ledger text: parses line-by-line and skips
+ * blank/malformed rows so a torn or hand-edited ledger never throws on the HUD
+ * path. Strict receipt consumers should keep using the validating reader.
+ */
+export function latestUltragoalLedgerEventFromText(text: string): UltragoalLedgerEventLite | undefined {
+	const events: UltragoalLedgerEventLite[] = [];
+	for (const line of text.split(/\r?\n/)) {
+		const event = parseUltragoalLedgerLine(line);
+		if (event) events.push(event);
+	}
+	return latestUltragoalLedgerEvent(events);
+}
+
+/* -------------------------------- ralplan -------------------------------- */
+
+/** Minimal projection of a ralplan `index.jsonl` row. */
+export interface RalplanIndexRow {
+	stage: string;
+	stageN?: number;
+}
+
+/** Stages that open a new consensus iteration when they appear in append order. */
+const RALPLAN_ITERATION_OPENERS = new Set(["planner", "revision"]);
+
+const RALPLAN_STAGE_CODES: Record<string, string> = {
+	planner: "P",
+	revision: "R",
+	architect: "A",
+	critic: "C",
+	adr: "D",
+	final: "F",
+};
+
+const DEFAULT_STAGE_PRESENCE_CAP = 6;
+
+/** Parse a single ralplan index JSONL line; undefined for blank/malformed lines. */
+export function parseRalplanIndexLine(line: string): RalplanIndexRow | undefined {
+	const trimmed = line.trim();
+	if (!trimmed) return undefined;
+	let row: unknown;
+	try {
+		row = JSON.parse(trimmed);
+	} catch {
+		return undefined;
+	}
+	if (!row || typeof row !== "object" || Array.isArray(row)) return undefined;
+	const record = row as Record<string, unknown>;
+	if (typeof record.stage !== "string") return undefined;
+	const out: RalplanIndexRow = { stage: record.stage };
+	if (typeof record.stage_n === "number") out.stageN = record.stage_n;
+	return out;
+}
+
+export interface RalplanIndexSummary {
+	/** Number of consensus iterations (planner/revision boundaries), >= 0. */
+	iteration: number;
+	/** Stage names present in the current (latest) iteration, in append order. */
+	currentStages: string[];
+}
+
+/**
+ * Derive iteration count and current-iteration stage presence from index rows.
+ *
+ * `stage_n` is NOT used as the iteration key: it is stored verbatim per row and a
+ * single planner/architect/critic pass can span multiple stage_n values. Instead,
+ * a `planner` or `revision` row opens a new iteration and subsequent rows attach
+ * to it. No verdict is derived here (index rows carry none).
+ */
+export function summarizeRalplanIndex(rows: readonly RalplanIndexRow[]): RalplanIndexSummary {
+	let iteration = 0;
+	let currentStages: string[] = [];
+	for (const row of rows) {
+		if (RALPLAN_ITERATION_OPENERS.has(row.stage)) {
+			iteration += 1;
+			currentStages = [row.stage];
+		} else {
+			if (iteration === 0) iteration = 1;
+			currentStages.push(row.stage);
+		}
+	}
+	return { iteration, currentStages };
+}
+
+/**
+ * Compact, theme-free presence string for the ralplan `stages` chip, e.g.
+ * `P·A·C`. Collapses past `cap` with a "… N more" suffix. Returns undefined when
+ * there are no stages.
+ */
+export function formatRalplanStagePresence(
+	stages: readonly string[],
+	cap = DEFAULT_STAGE_PRESENCE_CAP,
+): string | undefined {
+	if (stages.length === 0) return undefined;
+	const codes = stages.map(stage => RALPLAN_STAGE_CODES[stage] ?? stage.charAt(0).toUpperCase());
+	if (codes.length <= cap) return codes.join("·");
+	const shown = codes.slice(0, cap).join("·");
+	const remaining = codes.length - cap;
+	return `${shown} … ${remaining} more ${remaining === 1 ? "stage" : "stages"}`;
+}