@gajae-code/coding-agent 0.5.0 → 0.5.1

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

@@ -11,10 +11,10 @@ import {
 } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
 import {
-	buildDeepInterviewHudSummary,
 	buildRalplanHudSummary,
 	buildTeamHudSummary,
 	buildUltragoalHudSummary,
+	deriveDeepInterviewHud,
 } from "../skill-state/workflow-hud";
 import {
 	type AuditEntry,
@@ -26,6 +26,7 @@ import {
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
+import { mergeDeepInterviewEnvelope, normalizeDeepInterviewEnvelope } from "./deep-interview-state";
 import { renderStateGraph, type StateGraphFormat } from "./state-graph";
 import { migrateAndPersistLegacyState, migrateWorkflowState } from "./state-migrations";
 import {
@@ -833,31 +834,9 @@ function buildHudForMode(
 ): WorkflowHudSummary | undefined {
 	const updatedAt = new Date().toISOString();
 	const phase = typeof payload.current_phase === "string" ? payload.current_phase : undefined;
-	const stateField = isPlainObject(payload.state) ? (payload.state as Record<string, unknown>) : {};
 	switch (mode) {
-		case "deep-interview": {
-			const pick = <T>(key: string, guard: (value: unknown) => value is T): T | undefined => {
-				const v = (stateField as Record<string, unknown>)[key] ?? (payload as Record<string, unknown>)[key];
-				return guard(v) ? v : undefined;
-			};
-			const isNumber = (v: unknown): v is number => typeof v === "number";
-			const isString = (v: unknown): v is string => typeof v === "string";
-			const isArray = (v: unknown): v is unknown[] => Array.isArray(v);
-			const ambiguity = pick("current_ambiguity", isNumber);
-			const threshold = pick("threshold", isNumber);
-			const rounds = pick("rounds", isArray);
-			const targetComponent = pick("last_targeted_component_id", isString);
-			const weakestDimension = pick("weakest_dimension", isString);
-			return buildDeepInterviewHudSummary({
-				phase,
-				ambiguity,
-				threshold,
-				roundCount: rounds?.length,
-				targetComponent,
-				weakestDimension,
-				updatedAt,
-			});
-		}
+		case "deep-interview":
+			return deriveDeepInterviewHud(payload, { updatedAt });
 		case "ralplan": {
 			const stage =
 				typeof payload.current_phase === "string"
@@ -888,6 +867,24 @@ function buildHudForMode(
 				counts[status] = (counts[status] ?? 0) + 1;
 			}
 			const currentGoalRaw = goals.find(g => g.status === "active") ?? goals.find(g => g.status === "pending");
+			const rawLedger = payload.latestLedgerEvent;
+			const latestLedgerEvent =
+				rawLedger && typeof rawLedger === "object" && !Array.isArray(rawLedger)
+					? {
+							event:
+								typeof (rawLedger as Record<string, unknown>).event === "string"
+									? ((rawLedger as Record<string, unknown>).event as string)
+									: undefined,
+							goalId:
+								typeof (rawLedger as Record<string, unknown>).goalId === "string"
+									? ((rawLedger as Record<string, unknown>).goalId as string)
+									: undefined,
+							timestamp:
+								typeof (rawLedger as Record<string, unknown>).timestamp === "string"
+									? ((rawLedger as Record<string, unknown>).timestamp as string)
+									: undefined,
+						}
+					: undefined;
 			const status = typeof payload.status === "string" ? (payload.status as string) : (phase ?? "pending");
 			return buildUltragoalHudSummary({
 				status,
@@ -900,6 +897,7 @@ function buildHudForMode(
 					: undefined,
 				counts,
 				goals: goals.map(g => ({ id: g.id as string, title: g.title as string, status: g.status as string })),
+				latestLedgerEvent,
 				updatedAt,
 			});
 		}
@@ -1009,7 +1007,10 @@ export async function reconcileWorkflowSkillState(options: {
 	receipt.from_phase = fromPhase;
 	receipt.to_phase = trimmedPhase;
 
-	const merged = mergeWithNullDelete(existingPayload, payload);
+	const merged =
+		mode === "deep-interview"
+			? (mergeDeepInterviewEnvelope(existingPayload, payload) as Record<string, unknown>)
+			: mergeWithNullDelete(existingPayload, payload);
 	merged.skill = mode;
 	merged.current_phase = trimmedPhase;
 	merged.active = active;
@@ -1173,7 +1174,11 @@ async function handleWrite(
 					? (innerState.current_phase as string).trim()
 					: undefined;
 	let merged: Record<string, unknown>;
-	if (hasFlag(args, "--replace")) {
+	if (mode === "deep-interview") {
+		// Deep-interview keeps interview data nested under `state` and merges rounds
+		// losslessly by durable key; never flatten or delete `state` (that drops recorder history).
+		merged = mergeDeepInterviewEnvelope(existingPayload, payload, { replace: hasFlag(args, "--replace") });
+	} else if (hasFlag(args, "--replace")) {
 		merged = { ...payload };
 	} else {
 		merged = mergeWithNullDelete(existingPayload, payload);
@@ -1423,8 +1428,20 @@ async function handleHandoff(
 	});
 
 	const calleeInitial = initialPhaseForSkill(callee);
-	const normalizedCaller = migrateWorkflowState(existingCaller, caller).state;
-	const normalizedCallee = migrateWorkflowState(existingCallee, callee).state;
+	const normalizedCaller =
+		caller === "deep-interview"
+			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
+					string,
+					unknown
+				>)
+			: migrateWorkflowState(existingCaller, caller).state;
+	const normalizedCallee =
+		callee === "deep-interview"
+			? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCallee, callee).state) as Record<
+					string,
+					unknown
+				>)
+			: migrateWorkflowState(existingCallee, callee).state;
 	const mergedCalleeState: Record<string, unknown> = {
 		...normalizedCallee,
 		skill: callee,

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

@@ -0,0 +1,49 @@
+/**
+ * GC adapter for team workers (`.gjc/state/team/<name>/workers/<id>/` heartbeat
+ * + lifecycle). Liveness-only: numeric PID status dominates lifecycle/heartbeat
+ * signals.
+ */
+
+import * as path from "node:path";
+import { listHarnessRootRegistriesForGc } from "../harness-control-plane/storage";
+import type { GcCollectResult, GcContext, GcPruneOutcome, GcRecord, GcStoreAdapter } from "./gc-runtime";
+import { listTeamWorkerGcRecords, pruneTeamWorkerGcRecord } from "./team-runtime";
+
+function uniqueTeamRootsFromHarnessRoots(roots: string[]): string[] {
+	return [...new Set(roots.map(root => path.join(path.dirname(root), "team")))].sort();
+}
+
+export const teamWorkersGcAdapter: GcStoreAdapter = {
+	store: "team_workers",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcCollectResult["errors"] = [];
+		const registries = await listHarnessRootRegistriesForGc(ctx.env);
+		for (const registry of registries) {
+			if (registry.error) errors.push({ store: "team_workers", scope: registry.file, message: registry.error });
+		}
+
+		const teamRoots = uniqueTeamRootsFromHarnessRoots(
+			registries.flatMap(registry => registry.roots.map(entry => entry.root)),
+		);
+		for (const teamRoot of teamRoots) {
+			try {
+				records.push(...(await listTeamWorkerGcRecords(teamRoot, ctx.probe)));
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code === "ENOENT") continue;
+				errors.push({ store: "team_workers", scope: teamRoot, message: (error as Error).message });
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		try {
+			const removed = await pruneTeamWorkerGcRecord(record, ctx.probe);
+			return removed ? { removed: true } : { removed: false, skipped: "worker_no_longer_dead" };
+		} catch (error) {
+			return { removed: false, error: (error as Error).message };
+		}
+	},
+};

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

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildTeamHudSummary as buildWorkflowTeamHudSummary } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
+import type { GcPidProbe, GcRecord } from "./gc-runtime";
 
 import { applyGjcTmuxProfile, GJC_TMUX_LAUNCHED_ENV } from "./launch-tmux";
 import {
@@ -18,6 +19,7 @@ import {
 	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
 import {
+	buildGjcTmuxExactOptionTarget,
 	buildGjcTmuxUntaggedSessionHint,
 	GJC_TMUX_PROFILE_OPTION,
 	GJC_TMUX_PROFILE_VALUE,
@@ -677,6 +679,174 @@ async function readJsonFile<T>(filePath: string): Promise<T | null> {
 		throw error;
 	}
 }
+function isPositivePid(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function collectTeamGcWorkerPids(
+	heartbeat: WorkerHeartbeatFile | null,
+	lifecycle: GjcTeamWorkerLifecycle | null,
+): number[] {
+	const pids: number[] = [];
+	if (isPositivePid(heartbeat?.pid)) pids.push(heartbeat.pid);
+	if (isPositivePid(lifecycle?.pid) && !pids.includes(lifecycle.pid)) pids.push(lifecycle.pid);
+	return pids;
+}
+
+interface TeamGcPidClassification {
+	removable: boolean;
+	pidStatus: "dead" | "alive" | "eperm" | "unknown" | "none";
+	pid?: number;
+}
+
+/**
+ * Liveness-only, fail-closed: a worker is removable ONLY when it has at least
+ * one authoritative pid and EVERY candidate pid probes dead (ESRCH). Any alive,
+ * EPERM, or unknown candidate (heartbeat OR lifecycle) keeps the worker, so a
+ * dead heartbeat pid can never override a live lifecycle pid.
+ */
+function classifyTeamGcWorkerPids(pids: number[], probe: GcPidProbe): TeamGcPidClassification {
+	if (pids.length === 0) return { removable: false, pidStatus: "none" };
+	const statuses = pids.map(pid => ({ pid, status: gcProbeStatus(probe, pid) }));
+	const kept = statuses.find(entry => entry.status !== "dead");
+	if (kept) return { removable: false, pidStatus: kept.status, pid: kept.pid };
+	return { removable: true, pidStatus: "dead", pid: statuses[0]?.pid };
+}
+
+function gcProbeStatus(probe: GcPidProbe, pid: number): "dead" | "alive" | "eperm" | "unknown" {
+	const result = probe(pid);
+	if (result.status === "dead") return "dead";
+	return result.reason ?? "unknown";
+}
+
+function teamGcRecordDetail(heartbeat: WorkerHeartbeatFile | null, lifecycle: GjcTeamWorkerLifecycle | null): string {
+	return [
+		`heartbeat=${heartbeat ? "present" : "missing"}`,
+		...(heartbeat ? [`heartbeat_alive=${heartbeat.alive}`, `last_turn_at=${heartbeat.last_turn_at}`] : []),
+		`lifecycle=${lifecycle?.lifecycle_state ?? "missing"}`,
+		...(lifecycle?.pane_id ? [`pane_id=${lifecycle.pane_id}`] : []),
+		...(lifecycle?.stop_reason ? [`stop_reason=${lifecycle.stop_reason}`] : []),
+	].join(" ");
+}
+
+/** @internal */
+export async function listTeamWorkerGcRecords(teamRoot: string, probe: GcPidProbe): Promise<GcRecord[]> {
+	const teamEntries = await fs.readdir(teamRoot, { withFileTypes: true });
+	const records: GcRecord[] = [];
+	for (const teamEntry of teamEntries) {
+		if (!teamEntry.isDirectory()) continue;
+		const teamName = teamEntry.name;
+		const teamDirPath = path.join(teamRoot, teamName);
+		let workerEntries: import("node:fs").Dirent[];
+		try {
+			workerEntries = await fs.readdir(path.join(teamDirPath, "workers"), { withFileTypes: true });
+		} catch (error) {
+			if (isEnoent(error)) continue;
+			throw error;
+		}
+
+		for (const workerEntry of workerEntries) {
+			if (!workerEntry.isDirectory()) continue;
+			const workerId = workerEntry.name;
+			const dir = path.join(teamDirPath, "workers", workerId);
+			let heartbeat: WorkerHeartbeatFile | null = null;
+			let lifecycle: GjcTeamWorkerLifecycle | null = null;
+			try {
+				heartbeat = await readJsonFile<WorkerHeartbeatFile>(path.join(dir, "heartbeat.json"));
+				lifecycle = await readJsonFile<GjcTeamWorkerLifecycle>(path.join(dir, "lifecycle.json"));
+			} catch (error) {
+				records.push({
+					store: "team_workers",
+					id: `${teamName}/${workerId}`,
+					root: teamRoot,
+					path: dir,
+					pid_status: "none",
+					status: "malformed",
+					stale: false,
+					removable: false,
+					action: "none",
+					reason: "worker_state_malformed_kept",
+					error: error instanceof Error ? error.message : String(error),
+				});
+				continue;
+			}
+			const pids = collectTeamGcWorkerPids(heartbeat, lifecycle);
+			const { removable, pidStatus, pid } = classifyTeamGcWorkerPids(pids, probe);
+			const terminalLifecycle = lifecycle?.lifecycle_state === "failed" || lifecycle?.lifecycle_state === "stopped";
+			const status = removable
+				? "dead"
+				: pidStatus === "none" && terminalLifecycle
+					? "terminal_lifecycle"
+					: pidStatus === "none"
+						? "no_pid"
+						: pidStatus;
+			records.push({
+				store: "team_workers",
+				id: `${teamName}/${workerId}`,
+				root: teamRoot,
+				path: dir,
+				pid,
+				pid_status: pidStatus,
+				status,
+				stale: removable,
+				removable,
+				action: "none",
+				reason: removable
+					? "worker_all_pids_dead"
+					: pidStatus === "none" && terminalLifecycle
+						? "terminal_lifecycle_without_pid_kept"
+						: pidStatus === "none"
+							? "worker_pid_missing_kept"
+							: `worker_pid_${pidStatus}_kept`,
+				detail: teamGcRecordDetail(heartbeat, lifecycle),
+			});
+		}
+	}
+	return records;
+}
+
+/** @internal */
+export async function pruneTeamWorkerGcRecord(record: GcRecord, probe: GcPidProbe): Promise<boolean> {
+	if (!record.path || !record.id.includes("/")) return false;
+	const [teamName, workerId] = record.id.split("/", 2);
+	if (!teamName || !workerId) return false;
+	const teamDirPath = path.dirname(path.dirname(record.path));
+	const heartbeat = await readJsonFile<WorkerHeartbeatFile>(path.join(record.path, "heartbeat.json"));
+	const lifecycle = await readJsonFile<GjcTeamWorkerLifecycle>(path.join(record.path, "lifecycle.json"));
+	const pids = collectTeamGcWorkerPids(heartbeat, lifecycle);
+	if (!classifyTeamGcWorkerPids(pids, probe).removable) return false;
+
+	const claimDir = path.join(teamDirPath, "claims");
+	try {
+		for (const entry of await fs.readdir(claimDir, { withFileTypes: true })) {
+			if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+			const claimPath = path.join(claimDir, entry.name);
+			const claim = readClaimRecord(await readJsonFile<unknown>(claimPath));
+			if (claim?.owner !== workerId) continue;
+			await removeFileAudited(claimPath, stateWriterOptions(claimPath, "prune", "gc-team-worker"));
+		}
+	} catch (error) {
+		if (!isEnoent(error)) throw error;
+	}
+
+	for (const task of await readTasks(teamDirPath)) {
+		if (task.claim?.owner !== workerId && task.assignee !== workerId) continue;
+		if (task.status === "completed" || task.status === "failed") continue;
+		await writeTask(teamDirPath, {
+			...task,
+			status: "pending",
+			assignee: undefined,
+			claim: undefined,
+			version: task.version + 1,
+			updated_at: now(),
+		});
+	}
+
+	// Remove the stale worker record dir itself so a removable record always
+	// results in an observable removal, even when it owns no claims/tasks.
+	await fs.rm(record.path, { recursive: true, force: true });
+	return true;
+}
 function stateCategoryForJsonPath(filePath: string): "state" | "ledger" {
 	return filePath.endsWith(".jsonl") || filePath.includes(`${path.sep}telemetry${path.sep}`) ? "ledger" : "state";
 }
@@ -1633,7 +1803,7 @@ function buildTeamTmuxLeaderRequirementMessage(detail?: string): string {
 }
 function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): string {
 	const result = Bun.spawnSync(
-		[tmuxCommand, "show-options", "-qv", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION],
+		[tmuxCommand, "show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName), GJC_TMUX_PROFILE_OPTION],
 		{
 			stdout: "pipe",
 			stderr: "pipe",
@@ -1645,7 +1815,14 @@ function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): stri
 
 function retagGjcLaunchedTmuxSession(tmuxCommand: string, sessionName: string): boolean {
 	const result = Bun.spawnSync(
-		[tmuxCommand, "set-option", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION, GJC_TMUX_PROFILE_VALUE],
+		[
+			tmuxCommand,
+			"set-option",
+			"-t",
+			buildGjcTmuxExactOptionTarget(sessionName),
+			GJC_TMUX_PROFILE_OPTION,
+			GJC_TMUX_PROFILE_VALUE,
+		],
 		{
 			stdout: "pipe",
 			stderr: "pipe",

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

@@ -32,6 +32,20 @@ export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): str
 	return env[GJC_TMUX_COMMAND_ENV]?.trim() || env.GJC_TEAM_TMUX_COMMAND?.trim() || "tmux";
 }
 
+/**
+ * Build the exact-session target for tmux *option* commands
+ * (`show-options` / `set-option`) and `display-message -t`.
+ *
+ * Session-scoped commands such as `kill-session` / `attach-session` resolve a
+ * bare exact target (`=NAME`), but tmux 3.6a refuses to resolve a bare `=NAME`
+ * for option/display commands. Appending the empty window separator (`=NAME:`)
+ * keeps the exact-session match while giving tmux the window-qualified target
+ * those commands require. See gajae-code#580.
+ */
+export function buildGjcTmuxExactOptionTarget(sessionName: string): string {
+	return `=${sessionName}:`;
+}
+
 export const GJC_TMUX_UNTAGGED_REASON = "gjc_tmux_session_untagged";
 
 export function buildGjcTmuxUntaggedSessionHint(tmuxCommand: string): string {

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

@@ -0,0 +1,176 @@
+/**
+ * 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,
+	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: ReturnType<typeof listTmuxSessionsForGc>;
+		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 {