@gajae-code/coding-agent 0.5.0 → 0.5.2

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

@@ -0,0 +1,177 @@
+/**
+ * GC adapter for gjc-tagged tmux sessions. Stale iff `@gjc-project` path is gone
+ * OR `@gjc-branch` has no live git worktree. Removal is a spec-authorized
+ * destructive `kill-session`, gated by exact-target re-read + revalidation.
+ */
+
+import * as fs from "node:fs";
+
+import { worktree } from "../utils/git";
+import type { GcCollectResult, GcContext, GcPruneOutcome, GcRecord, GcStoreAdapter } from "./gc-runtime";
+import { GJC_TMUX_PROFILE_VALUE } from "./tmux-common";
+import {
+	type GjcTmuxSessionStatus,
+	type GjcTmuxSessionsForGc,
+	listTmuxSessionsForGc,
+	readTmuxSessionTagsForGc,
+	removeGjcTmuxSession,
+} from "./tmux-sessions";
+
+const STORE = "tmux_sessions" as const;
+const TOCTOU_SKIP = "tmux_revalidation_failed_or_became_live";
+
+function pathExists(path: string): boolean {
+	try {
+		return fs.existsSync(path);
+	} catch {
+		return false;
+	}
+}
+
+function detail(project?: string, branch?: string): string | undefined {
+	const parts = [];
+	if (project) parts.push(`project=${project}`);
+	if (branch) parts.push(`branch=${branch}`);
+	return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+function unclassifiedRecord(id: string, reason: string, project?: string, branch?: string): GcRecord {
+	return {
+		store: STORE,
+		id,
+		path: project,
+		root: project,
+		pid_status: "none",
+		status: "unclassified",
+		stale: false,
+		removable: false,
+		action: "none",
+		reason,
+		detail: detail(project, branch),
+	};
+}
+
+function branchMatches(candidate: string | undefined, branch: string): boolean {
+	if (!candidate) return false;
+	const branchNames = new Set([
+		branch,
+		branch.startsWith("refs/heads/") ? branch.slice("refs/heads/".length) : `refs/heads/${branch}`,
+	]);
+	return branchNames.has(candidate);
+}
+
+async function hasLiveWorktreeForBranch(project: string, branch: string): Promise<boolean> {
+	const entries = await worktree.list(project);
+	return entries.some(entry => branchMatches(entry.branch, branch));
+}
+
+async function classifyTaggedSession(session: GjcTmuxSessionStatus): Promise<GcRecord> {
+	const { name, project, branch } = session;
+	if (!project || !branch) return unclassifiedRecord(name, "missing_project_or_branch_tag", project, branch);
+	if (!pathExists(project)) {
+		return {
+			store: STORE,
+			id: name,
+			path: project,
+			root: project,
+			pid_status: "none",
+			status: "stale",
+			stale: true,
+			removable: true,
+			action: "none",
+			reason: "project_missing",
+			detail: detail(project, branch),
+		};
+	}
+	if (!(await hasLiveWorktreeForBranch(project, branch))) {
+		return {
+			store: STORE,
+			id: name,
+			path: project,
+			root: project,
+			pid_status: "none",
+			status: "stale",
+			stale: true,
+			removable: true,
+			action: "none",
+			reason: "branch_no_worktree",
+			detail: detail(project, branch),
+		};
+	}
+	return {
+		store: STORE,
+		id: name,
+		path: project,
+		root: project,
+		pid_status: "none",
+		status: "live",
+		stale: false,
+		removable: false,
+		action: "none",
+		reason: "project_and_branch_worktree_present",
+		detail: detail(project, branch),
+	};
+}
+
+async function revalidateRemovable(name: string, env: NodeJS.ProcessEnv): Promise<boolean> {
+	const tags = readTmuxSessionTagsForGc(name, env);
+	if (tags.profile !== GJC_TMUX_PROFILE_VALUE || !tags.project || !tags.branch) return false;
+	if (!pathExists(tags.project)) return true;
+	return !(await hasLiveWorktreeForBranch(tags.project, tags.branch));
+}
+
+export const tmuxSessionsGcAdapter: GcStoreAdapter = {
+	store: STORE,
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcCollectResult["errors"] = [];
+		let sessions: GjcTmuxSessionsForGc;
+		try {
+			sessions = listTmuxSessionsForGc(ctx.env);
+		} catch (error) {
+			return {
+				records,
+				errors: [
+					{
+						store: STORE,
+						scope: "list_sessions",
+						message: error instanceof Error ? error.message : String(error),
+					},
+				],
+			};
+		}
+
+		for (const session of sessions.tagged) {
+			try {
+				records.push(await classifyTaggedSession(session));
+			} catch (error) {
+				errors.push({
+					store: STORE,
+					scope: session.name,
+					message: error instanceof Error ? error.message : String(error),
+				});
+				records.push(unclassifiedRecord(session.name, "worktree_list_failed", session.project, session.branch));
+			}
+		}
+
+		for (const name of sessions.untagged) {
+			records.push(unclassifiedRecord(name, "untagged_tmux_session"));
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		if (record.store !== STORE || record.status !== "stale" || !record.removable) {
+			return { removed: false, skipped: "not_removable_tmux_session" };
+		}
+		try {
+			if (!(await revalidateRemovable(record.id, ctx.env))) {
+				return { removed: false, skipped: TOCTOU_SKIP };
+			}
+			removeGjcTmuxSession(record.id, ctx.env);
+			return { removed: true };
+		} catch (error) {
+			return { removed: false, error: error instanceof Error ? error.message : String(error) };
+		}
+	},
+};

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

@@ -1,4 +1,5 @@
 import {
+	buildGjcTmuxExactOptionTarget,
 	buildGjcTmuxProfileCommands,
 	buildGjcTmuxSessionName,
 	buildGjcTmuxUntaggedSessionError,
@@ -23,6 +24,17 @@ export interface GjcTmuxSessionStatus {
 	project?: string;
 }
 
+export interface GjcTmuxSessionTagsForGc {
+	profile?: string;
+	project?: string;
+	branch?: string;
+}
+
+export interface GjcTmuxSessionsForGc {
+	tagged: GjcTmuxSessionStatus[];
+	untagged: string[];
+}
+
 function runTmux(args: string[], env: NodeJS.ProcessEnv = process.env): string {
 	const tmuxCommand = resolveGjcTmuxCommand(env);
 	const result = Bun.spawnSync([tmuxCommand, ...args], { stdout: "pipe", stderr: "pipe", env });
@@ -107,6 +119,16 @@ export function listGjcTmuxSessions(env: NodeJS.ProcessEnv = process.env): GjcTm
 		.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/** @internal */
+export function listTmuxSessionsForGc(env: NodeJS.ProcessEnv = process.env): GjcTmuxSessionsForGc {
+	const tagged = listGjcTmuxSessions(env);
+	const taggedNames = new Set(tagged.map(session => session.name));
+	const untagged = listRawTmuxSessionNames(env)
+		.filter(name => !taggedNames.has(name))
+		.sort((a, b) => a.localeCompare(b));
+	return { tagged, untagged };
+}
+
 export function findGjcTmuxSessionByBranch(
 	branch: string,
 	env: NodeJS.ProcessEnv = process.env,
@@ -148,7 +170,33 @@ export function createGjcTmuxSession(env: NodeJS.ProcessEnv = process.env): GjcT
 }
 
 function readProfileForExactTarget(sessionName: string, env: NodeJS.ProcessEnv): string {
-	return runTmux(["show-options", "-qv", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION], env).trim();
+	return runTmux(
+		["show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName), GJC_TMUX_PROFILE_OPTION],
+		env,
+	).trim();
+}
+
+function readExactOptionForGc(sessionName: string, option: string, env: NodeJS.ProcessEnv): string | undefined {
+	try {
+		return (
+			runTmux(["show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName), option], env).trim() ||
+			undefined
+		);
+	} catch {
+		return undefined;
+	}
+}
+
+/** @internal */
+export function readTmuxSessionTagsForGc(
+	sessionName: string,
+	env: NodeJS.ProcessEnv = process.env,
+): GjcTmuxSessionTagsForGc {
+	return {
+		profile: readExactOptionForGc(sessionName, GJC_TMUX_PROFILE_OPTION, env),
+		project: readExactOptionForGc(sessionName, GJC_TMUX_PROJECT_OPTION, env),
+		branch: readExactOptionForGc(sessionName, GJC_TMUX_BRANCH_OPTION, env),
+	};
 }
 
 export function removeGjcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv = process.env): GjcTmuxSessionStatus {

package/src/gjc-runtime/ultragoal-guard.ts

@@ -32,6 +32,16 @@ export interface UltragoalGuardDiagnostic {
 	goalId?: string;
 }
 
+export interface UltragoalAskBlockDiagnostic {
+	active: boolean;
+	reason: string;
+	source: "absent" | "durable_state" | "durable_state_unreadable" | "ledger" | "goals_json";
+	goalsPath?: string;
+	ledgerPath?: string;
+	goalIds?: string[];
+	message: string;
+}
+
 export interface CurrentGoalLike {
 	objective: string;
 	status?: string;
@@ -70,6 +80,48 @@ async function hasDurableUltragoalState(cwd: string): Promise<boolean> {
 	}
 }
 
+function isEnoent(error: unknown): boolean {
+	return (
+		typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT"
+	);
+}
+
+function activeAskDiagnostic(input: {
+	reason: string;
+	source: UltragoalAskBlockDiagnostic["source"];
+	goalsPath?: string;
+	ledgerPath?: string;
+	goalIds?: string[];
+}): UltragoalAskBlockDiagnostic {
+	return {
+		active: true,
+		reason: input.reason,
+		source: input.source,
+		goalsPath: input.goalsPath,
+		ledgerPath: input.ledgerPath,
+		goalIds: input.goalIds,
+		message: `${input.reason} Use \`gjc ultragoal record-review-blockers\` instead of asking the user.`,
+	};
+}
+
+function inactiveAskDiagnostic(input: {
+	reason: string;
+	source: UltragoalAskBlockDiagnostic["source"];
+	goalsPath?: string;
+	ledgerPath?: string;
+	goalIds?: string[];
+}): UltragoalAskBlockDiagnostic {
+	return {
+		active: false,
+		reason: input.reason,
+		source: input.source,
+		goalsPath: input.goalsPath,
+		ledgerPath: input.ledgerPath,
+		goalIds: input.goalIds,
+		message: input.reason,
+	};
+}
+
 function requiredGoals(plan: UltragoalPlan): UltragoalGoal[] {
 	return plan.goals.filter(goal => goal.status !== "superseded");
 }
@@ -278,6 +330,109 @@ export async function readUltragoalVerificationState(input: {
 	return receiptDiagnostic;
 }
 
+export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic> {
+	const paths = getUltragoalPaths(cwd);
+	try {
+		await fs.stat(paths.dir);
+	} catch (error) {
+		if (isEnoent(error)) {
+			return inactiveAskDiagnostic({
+				reason: "No durable .gjc/ultragoal state exists.",
+				source: "absent",
+				goalsPath: paths.goalsPath,
+				ledgerPath: paths.ledgerPath,
+			});
+		}
+		return activeAskDiagnostic({
+			reason: `Durable .gjc/ultragoal state is present but unreadable: ${error instanceof Error ? error.message : String(error)}`,
+			source: "durable_state_unreadable",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
+
+	let plan: UltragoalPlan | null;
+	let ledger: UltragoalLedgerEvent[];
+	try {
+		plan = await readUltragoalPlan(cwd);
+		ledger = await readUltragoalLedger(cwd);
+	} catch (error) {
+		return activeAskDiagnostic({
+			reason: `Unable to read durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
+			source: "durable_state_unreadable",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
+	if (!plan) {
+		return activeAskDiagnostic({
+			reason: "Durable .gjc/ultragoal state exists but goals.json is missing or empty.",
+			source: "durable_state_unreadable",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
+
+	if (plan.goals.some(goal => goal.status === "review_blocked")) {
+		const goalIds = plan.goals.filter(goal => goal.status === "review_blocked").map(goal => goal.id);
+		return activeAskDiagnostic({
+			reason: `Ultragoal has recorded review blockers: ${goalIds.join(", ")}.`,
+			source: "goals_json",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds,
+		});
+	}
+
+	const runState = getUltragoalRunCompletionState(plan);
+	if (runState.incompleteGoals.length > 0) {
+		const goalIds = runState.incompleteGoals.map(goal => goal.id);
+		return activeAskDiagnostic({
+			reason: `Ultragoal has incomplete required goals: ${goalIds.join(", ")}.`,
+			source: "goals_json",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds,
+		});
+	}
+
+	const finalReceiptGoal = [...requiredGoals(plan)]
+		.reverse()
+		.find(goal => goal.completionVerification?.receiptKind === "final-aggregate");
+	if (!finalReceiptGoal) {
+		return activeAskDiagnostic({
+			reason: "Ultragoal aggregate completion is missing a final aggregate receipt.",
+			source: "durable_state",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds: requiredGoals(plan).map(goal => goal.id),
+		});
+	}
+
+	const diagnostic = validateCompletionReceipt({
+		plan,
+		ledger,
+		goal: finalReceiptGoal,
+		receiptKind: "final-aggregate",
+	});
+	if (diagnostic.state !== "active_verified_complete") {
+		return activeAskDiagnostic({
+			reason: diagnostic.message,
+			source: diagnostic.state === "active_dirty_quality_gate" ? "ledger" : "durable_state",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+			goalIds: diagnostic.goalId ? [diagnostic.goalId] : undefined,
+		});
+	}
+	return inactiveAskDiagnostic({
+		reason: "Ultragoal run is verified complete.",
+		source: "durable_state",
+		goalsPath: paths.goalsPath,
+		ledgerPath: paths.ledgerPath,
+		goalIds: [finalReceiptGoal.id],
+	});
+}
+
 export async function assertCanCompleteCurrentGoal(input: {
 	cwd: string;
 	currentGoal?: CurrentGoalLike | null;