@gajae-code/coding-agent 0.5.0 → 0.5.2

package/src/gjc-runtime/workflow-manifest.generated.json

@@ -1523,11 +1523,51 @@
         "name": "order-json",
         "type": "string"
       },
+      {
+        "appliesToVerbs": [
+          "review"
+        ],
+        "name": "pr",
+        "type": "string"
+      },
+      {
+        "appliesToVerbs": [
+          "review"
+        ],
+        "name": "branch",
+        "type": "string"
+      },
+      {
+        "appliesToVerbs": [
+          "review"
+        ],
+        "name": "spec",
+        "type": "string"
+      },
+      {
+        "appliesToVerbs": [
+          "review"
+        ],
+        "name": "executor-qa-json",
+        "type": "string"
+      },
+      {
+        "appliesToVerbs": [
+          "review"
+        ],
+        "enumValues": [
+          "review-only",
+          "review-start"
+        ],
+        "name": "mode",
+        "type": "enum"
+      },
       {
         "appliesToVerbs": [
           "status",
           "create-goals",
           "complete-goals",
+          "review",
           "checkpoint",
           "record-review-blockers",
           "steer"
@@ -1599,6 +1639,10 @@
         "name": "checkpoint",
         "surface": "command-positional"
       },
+      {
+        "name": "review",
+        "surface": "command-positional"
+      },
       {
         "name": "record-review-blockers",
         "surface": "command-positional"

package/src/gjc-runtime/workflow-manifest.ts

@@ -235,6 +235,7 @@ export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>
 				"create-goals",
 				"complete-goals",
 				"checkpoint",
+				"review",
 				"record-review-blockers",
 				"steer",
 			]),
@@ -286,6 +287,16 @@ export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>
 			{ name: "rationale", type: "string", appliesToVerbs: ["steer"] },
 			{ name: "replacements-json", type: "string", appliesToVerbs: ["steer"] },
 			{ name: "order-json", type: "string", appliesToVerbs: ["steer"] },
+			{ name: "pr", type: "string", appliesToVerbs: ["review"] },
+			{ name: "branch", type: "string", appliesToVerbs: ["review"] },
+			{ name: "spec", type: "string", appliesToVerbs: ["review"] },
+			{ name: "executor-qa-json", type: "string", appliesToVerbs: ["review"] },
+			{
+				name: "mode",
+				type: "enum",
+				enumValues: ["review-only", "review-start"],
+				appliesToVerbs: ["review"],
+			},
 			{
 				name: "json",
 				type: "boolean",
@@ -293,6 +304,7 @@ export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>
 					"status",
 					"create-goals",
 					"complete-goals",
+					"review",
 					"checkpoint",
 					"record-review-blockers",
 					"steer",

package/src/harness-control-plane/gc-adapter.ts

@@ -0,0 +1,184 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+	type GcCollectResult,
+	type GcContext,
+	type GcError,
+	type GcPruneOutcome,
+	type GcRecord,
+	type GcStoreAdapter,
+	gcPidStatusLabel,
+	gcProbeToLeasePidStatus,
+} from "../gjc-runtime/gc-runtime";
+import { classifyLeaseStatus, readLease, reapDeadOwnerArtifacts } from "./session-lease";
+import {
+	type HarnessRootRegistryForGc,
+	type HarnessRootRegistryListingForGc,
+	listHarnessRootRegistriesForGc,
+	removeHarnessRootRegistryFileForGc,
+	rewriteHarnessRootRegistryForGc,
+	sessionPaths,
+} from "./storage";
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function exists(file: string): Promise<boolean> {
+	try {
+		await fs.access(file);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function registryErrors(registries: HarnessRootRegistryListingForGc[]): GcError[] {
+	return registries
+		.filter(registry => registry.error)
+		.map(registry => ({
+			store: "registry_entries",
+			scope: registry.file,
+			message: registry.error ?? "registry_error",
+		}));
+}
+
+async function collectRegistries(ctx: GcContext): Promise<HarnessRootRegistryListingForGc[]> {
+	return listHarnessRootRegistriesForGc(ctx.env);
+}
+
+export const harnessLeasesGcAdapter: GcStoreAdapter = {
+	store: "harness_leases",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcError[] = [];
+		const registries = await collectRegistries(ctx);
+		errors.push(...registryErrors(registries).map(error => ({ ...error, store: "harness_leases" as const })));
+
+		const roots = new Set<string>();
+		for (const registry of registries) {
+			if (registry.error) continue;
+			for (const entry of registry.roots) roots.add(path.resolve(entry.root));
+		}
+
+		for (const root of roots) {
+			const sessionsDir = path.join(root, "sessions");
+			let sessionEntries: string[];
+			try {
+				sessionEntries = await fs.readdir(sessionsDir);
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code === "ENOENT") continue;
+				errors.push({ store: "harness_leases", scope: sessionsDir, message: errorMessage(error) });
+				continue;
+			}
+
+			for (const sessionId of sessionEntries) {
+				const sessionDir = sessionPaths(root, sessionId).dir;
+				try {
+					const stat = await fs.stat(sessionDir);
+					if (!stat.isDirectory()) continue;
+					const lease = await readLease(root, sessionId);
+					if (!lease) continue;
+					const status = classifyLeaseStatus(lease, { probe: gcProbeToLeasePidStatus(ctx.probe) });
+					const pidProbe = ctx.probe(lease.pid);
+					const pidStatus = gcPidStatusLabel(pidProbe);
+					const removable = status === "dead" && pidProbe.status === "dead";
+					records.push({
+						store: "harness_leases",
+						id: sessionId,
+						root,
+						path: sessionPaths(root, sessionId).lease,
+						pid: lease.pid,
+						pid_status: pidStatus,
+						status,
+						stale: status === "dead",
+						removable,
+						action: "none",
+						reason: removable
+							? `lease owner pid ${lease.pid} is dead`
+							: `lease owner pid ${lease.pid} is ${pidStatus}; keeping`,
+					});
+				} catch (error) {
+					errors.push({ store: "harness_leases", scope: sessionDir, message: errorMessage(error) });
+				}
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		if (!record.root) return { removed: false, skipped: "missing_root" };
+		const lease = await readLease(record.root, record.id);
+		if (!lease) return { removed: false, skipped: "lease_not_dead_or_missing" };
+		const status = classifyLeaseStatus(lease, { probe: gcProbeToLeasePidStatus(ctx.probe) });
+		if (status !== "dead") return { removed: false, skipped: "lease_not_dead_or_missing" };
+		const removed = await reapDeadOwnerArtifacts(record.root, record.id, lease.ownerId, lease.leaseEpoch, {
+			probe: gcProbeToLeasePidStatus(ctx.probe),
+		});
+		return removed ? { removed: true } : { removed: false, skipped: "reaper_guard_rejected" };
+	},
+};
+
+async function splitRegistryRoots(registry: HarnessRootRegistryForGc): Promise<{
+	liveRoots: HarnessRootRegistryForGc["roots"];
+	danglingRoots: HarnessRootRegistryForGc["roots"];
+}> {
+	const liveRoots: HarnessRootRegistryForGc["roots"] = [];
+	const danglingRoots: HarnessRootRegistryForGc["roots"] = [];
+	for (const entry of registry.roots) {
+		const sessionDir = sessionPaths(entry.root, registry.sessionId).dir;
+		if (await exists(sessionDir)) liveRoots.push(entry);
+		else danglingRoots.push(entry);
+	}
+	return { liveRoots, danglingRoots };
+}
+
+export const registryEntriesGcAdapter: GcStoreAdapter = {
+	store: "registry_entries",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcError[] = [];
+		const registries = await collectRegistries(ctx);
+		errors.push(...registryErrors(registries));
+
+		for (const registry of registries) {
+			if (registry.error) continue;
+			try {
+				const { liveRoots, danglingRoots } = await splitRegistryRoots(registry);
+				if (danglingRoots.length === 0) continue;
+				records.push({
+					store: "registry_entries",
+					id: registry.sessionId,
+					path: registry.file,
+					pid_status: "none",
+					status: "dangling",
+					stale: true,
+					removable: true,
+					action: "none",
+					reason: `dangling roots: ${danglingRoots.map(entry => entry.root).join(", ")}`,
+					detail: `${danglingRoots.length} dangling, ${liveRoots.length} live`,
+				});
+			} catch (error) {
+				errors.push({ store: "registry_entries", scope: registry.file, message: errorMessage(error) });
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		if (!record.path) return { removed: false, skipped: "missing_registry_path" };
+		const registries = await collectRegistries(ctx);
+		const registry = registries.find(entry => entry.file === record.path);
+		if (!registry || registry.error) return { removed: false, skipped: "registry_not_readable" };
+		const { liveRoots, danglingRoots } = await splitRegistryRoots(registry);
+		if (danglingRoots.length === 0) return { removed: false, skipped: "no_dangling_roots" };
+		if (liveRoots.length === 0) {
+			await removeHarnessRootRegistryFileForGc(record.path);
+		} else {
+			await rewriteHarnessRootRegistryForGc(record.path, { sessionId: registry.sessionId, roots: liveRoots });
+		}
+		return { removed: true };
+	},
+};

package/src/harness-control-plane/owner.ts

@@ -14,6 +14,7 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
+import type { AgentWireOwnerObservation } from "../modes/shared/agent-wire/event-contract";
 import { observeRpcOutboundFrame } from "../modes/shared/agent-wire/event-observation";
 import { classifyRecovery } from "./classifier";
 import { ControlServer, type EndpointRequest } from "./control-endpoint";
@@ -106,7 +107,7 @@ export class RuntimeOwner {
 	#server: ControlServer;
 	#cursor = 0;
 	#leaseEpoch = 0;
-	#heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+	#heartbeatTimer: NodeJS.Timeout | null = null;
 	#socketPath: string;
 	#finalizeChecks?: FinalizeChecks;
 	#validationCommands?: ValidationCommandSpec[];
@@ -199,7 +200,7 @@ export class RuntimeOwner {
 		await this.#emit("info", "rpc_activity", { coalescedFrames });
 	}
 
-	async #emitMapped(mapped: NonNullable<ReturnType<typeof observeRpcOutboundFrame>>): Promise<void> {
+	async #emitMapped(mapped: AgentWireOwnerObservation): Promise<void> {
 		if (mapped.kind === "rpc_agent_completed") {
 			const state = await readSessionState(this.#opts.root, this.#opts.sessionId);
 			if (
@@ -670,3 +671,14 @@ export async function resolveOwner(root: string, sessionId: string): Promise<Res
 	const live = status === "live" || status === "expiredAlive" || status === "epermAlive";
 	return { live, socketPath: lease.endpoint?.path ?? null, lease };
 }
+
+/**
+ * Owner liveness for verbs that do not route to the owner (e.g. `classify`): a routable owner
+ * has a live lease and a socket endpoint. This is the same lease/socket probe `observe` uses to
+ * decide routing, so non-routing verbs derive `ownerLive` consistently instead of assuming the
+ * owner is gone (which would misclassify a live owner as vanished/restart-clean).
+ */
+export async function resolveOwnerLive(root: string, sessionId: string): Promise<boolean> {
+	const owner = await resolveOwner(root, sessionId);
+	return owner.live && owner.socketPath !== null;
+}

package/src/harness-control-plane/rpc-adapter.ts

@@ -120,7 +120,7 @@ export class GajaeCodeRpc implements HarnessRpc {
 	#waiters: {
 		afterCursor: number;
 		resolve: (v: { cursor: number } | null) => void;
-		timer: ReturnType<typeof setTimeout>;
+		timer: NodeJS.Timeout;
 	}[] = [];
 	#frameListeners: ((frame: Record<string, unknown>) => void)[] = [];
 	#lastFrameAt: string | null = null;

package/src/harness-control-plane/storage.ts

@@ -32,6 +32,18 @@ interface HarnessRootRegistry {
 	roots: HarnessRootRegistryEntry[];
 }
 
+export interface HarnessRootRegistryForGc {
+	sessionId: string;
+	roots: HarnessRootRegistryEntry[];
+}
+
+export interface HarnessRootRegistryListingForGc {
+	sessionId: string;
+	file: string;
+	roots: HarnessRootRegistryEntry[];
+	error?: string;
+}
+
 interface ResolveHarnessSessionRootOptions {
 	expectedWorkspace?: string;
 }
@@ -101,6 +113,64 @@ async function writeHarnessRootRegistry(
 	const file = harnessRootRegistryPath(registry.sessionId, env);
 	await writeJsonAtomicPrivate(file, registry);
 }
+
+function parseHarnessRootRegistryForGc(value: unknown, fallbackSessionId: string): HarnessRootRegistryForGc | null {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const registry = value as Record<string, unknown>;
+	if (typeof registry.sessionId !== "string" || !Array.isArray(registry.roots)) return null;
+	const roots: HarnessRootRegistryEntry[] = [];
+	for (const entry of registry.roots) {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+		const rootEntry = entry as Record<string, unknown>;
+		if (typeof rootEntry.root !== "string" || typeof rootEntry.updatedAt !== "string") return null;
+		roots.push({ root: rootEntry.root, updatedAt: rootEntry.updatedAt });
+	}
+	return { sessionId: registry.sessionId || fallbackSessionId, roots };
+}
+
+/** @internal */
+export async function listHarnessRootRegistriesForGc(
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<HarnessRootRegistryListingForGc[]> {
+	const dir = harnessRootRegistryDir(env);
+	let entries: string[];
+	try {
+		entries = await fs.readdir(dir);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return [];
+		return [{ sessionId: "", file: dir, roots: [], error: (error as Error).message }];
+	}
+
+	const registries: HarnessRootRegistryListingForGc[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".json")) continue;
+		const file = path.join(dir, entry);
+		const fallbackSessionId = entry.slice(0, -".json".length);
+		try {
+			const raw = await fs.readFile(file, "utf8");
+			const parsed = parseHarnessRootRegistryForGc(JSON.parse(raw), fallbackSessionId);
+			if (!parsed) {
+				registries.push({ sessionId: fallbackSessionId, file, roots: [], error: "malformed_registry" });
+				continue;
+			}
+			registries.push({ sessionId: parsed.sessionId, file, roots: parsed.roots });
+		} catch (error) {
+			registries.push({ sessionId: fallbackSessionId, file, roots: [], error: (error as Error).message });
+		}
+	}
+	return registries;
+}
+
+/** @internal */
+export async function rewriteHarnessRootRegistryForGc(file: string, registry: HarnessRootRegistryForGc): Promise<void> {
+	await writeJsonAtomicPrivate(file, registry);
+}
+
+/** @internal */
+export async function removeHarnessRootRegistryFileForGc(file: string): Promise<void> {
+	await fs.rm(file, { force: true });
+}
 const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export const MAX_UNIX_SOCKET_PATH_BYTES = 100;
 

package/src/hooks/skill-state.ts

@@ -1,8 +1,10 @@
 import * as path from "node:path";
+import { logger } from "@gajae-code/utils";
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
 import { ModeStateSchema, SkillActiveStateSchema } from "../gjc-runtime/state-schema";
 import { writeJsonAtomic, writeWorkflowEnvelopeAtomic } from "../gjc-runtime/state-writer";
 import { isUltragoalBypassPrompt, readUltragoalVerificationState } from "../gjc-runtime/ultragoal-guard";
+import { getUltragoalRunCompletionState, readUltragoalPlan } from "../gjc-runtime/ultragoal-runtime";
 import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
 import {
 	readVisibleSkillActiveState as readCanonicalVisibleSkillActiveState,
@@ -221,7 +223,7 @@ function skillStatePath(stateDir: string, sessionId?: string): string {
 }
 
 function warnInvalidState(kind: string, filePath: string, error: string): void {
-	console.warn(`gjc skill-state: invalid ${kind} at ${filePath}: ${error}`);
+	logger.warn(`gjc skill-state: invalid ${kind} at ${filePath}: ${error}`);
 }
 
 async function readValidatedJsonFile<T>(
@@ -480,6 +482,85 @@ function modeStateReleasesStop(state: ModeState | null, handoffRequired: boolean
 	return false;
 }
 
+/**
+ * Cross-file coherence guard for a mode-state that claims it releases the Stop
+ * block. `modeStateReleasesStop` trusts a single mode-state file; if any writer
+ * leaves that file stale or incoherent (e.g. `active:false` / a terminal phase
+ * after a `clear` while a new run's goals are still pending), trusting it alone
+ * silently defeats the Stop protection.
+ *
+ * This consults the authoritative durable state the Stop hook can already read
+ * and returns a block reason when that state contradicts the release. It stays
+ * cheap and read-only — ultragoal reads the durable plan; skills without an
+ * independent durable source release as before.
+ */
+async function detectStaleModeStateRelease(skill: GjcWorkflowSkill, cwd: string): Promise<string | null> {
+	if (skill === "ultragoal") {
+		const plan = await readUltragoalPlan(cwd);
+		if (!plan) return null;
+		const runState = getUltragoalRunCompletionState(plan);
+		if (runState.incompleteGoals.length > 0) {
+			return `the durable Ultragoal plan still has incomplete required goals (${runState.incompleteGoals
+				.map(goal => goal.id)
+				.join(", ")}); run \`gjc ultragoal complete-goals\` to continue`;
+		}
+	}
+	return null;
+}
+
+/**
+ * Deep-interview terminal phases that represent an explicit abort/cancel rather
+ * than an ordinary stop. These are legitimate terminals even without a
+ * crystallized spec, so they must NOT be forced through crystallization.
+ */
+const DEEP_INTERVIEW_ABORT_PHASES = new Set(["failed", "cancelled", "canceled"]);
+
+/**
+ * A deep-interview run is "crystallized" once it has persisted a final spec.
+ * `persistDeepInterviewSpec` records the spec path in the mode-state and writes
+ * the artifact under `.gjc/specs/`, so a crystallized state carries a
+ * `spec_path` that still resolves to a real file. A bare `spec_path` with no
+ * backing file (deleted/stale/fabricated) does not count as crystallized.
+ */
+async function deepInterviewSpecCrystallized(state: ModeState, cwd: string): Promise<boolean> {
+	const raw = state.spec_path;
+	const specPath = typeof raw === "string" ? raw.trim() : "";
+	if (!specPath) return false;
+	const resolved = path.isAbsolute(specPath) ? specPath : path.resolve(cwd, specPath);
+	try {
+		return await Bun.file(resolved).exists();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Deep-interview-scoped terminalization guard (#674). An ordinary stop must not
+ * let a deep-interview run disappear as a generic stopped task while the user
+ * still needs the distilled interview state: when its mode-state would release
+ * the Stop block it must have actually crystallized the interview into a
+ * persisted spec/handoff. Explicit abort/cancel phases and the `active:false`
+ * demotion/clear outcome (the handoff/chain result) remain legitimate terminals.
+ * Returns a public-safe diagnostic that forces crystallization, or null to
+ * release. Scoped to deep-interview only — other workflows are untouched.
+ */
+async function detectUncrystallizedDeepInterviewStop(
+	skill: GjcWorkflowSkill,
+	state: ModeState | null,
+	cwd: string,
+): Promise<string | null> {
+	if (skill !== "deep-interview") return null;
+	// active:false is the demotion/clear outcome (chain handoff or explicit
+	// clear already terminalized the run); a missing state blocks upstream.
+	if (state?.active !== true) return null;
+	const phase = String(state.current_phase ?? "")
+		.trim()
+		.toLowerCase();
+	if (DEEP_INTERVIEW_ABORT_PHASES.has(phase)) return null;
+	if (await deepInterviewSpecCrystallized(state, cwd)) return null;
+	return `the deep-interview run reached a terminal phase ("${phase || "unknown"}") without crystallizing a usable spec/handoff. Run \`gjc deep-interview --write --stage final\` (optionally \`--handoff ralplan\`) to persist the distilled interview spec, hand off through the deep-interview policy, or explicitly cancel/clear the interview before stopping`;
+}
+
 async function readVisibleModeState(
 	cwd: string,
 	skill: GjcWorkflowSkill,
@@ -572,7 +653,45 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 			ModeStateSchema,
 		);
 		const handoffRequired = isHandoffRequiredSkill(entry.skill);
-		if (modeStateReleasesStop(modeState, handoffRequired)) continue;
+		if (modeStateReleasesStop(modeState, handoffRequired)) {
+			// A mode-state that claims it releases the Stop block must agree with
+			// authoritative durable state. If a stale/incoherent mode-state would
+			// release while the plan/ledger still shows pending work, block instead
+			// of trusting the single file (see #659).
+			const staleRelease = await detectStaleModeStateRelease(entry.skill, input.cwd);
+			if (staleRelease) {
+				const coherenceMessage = `GJC skill "${entry.skill}" mode-state reports it released the Stop block (${modeStatePath(
+					resolvedStateDir,
+					entry.skill,
+					input.sessionId,
+				)}), but ${staleRelease}. The mode-state is incoherent with authoritative durable state; finish or explicitly clear the pending work before stopping.`;
+				return {
+					decision: "block",
+					reason: coherenceMessage,
+					stopReason: `gjc_skill_${entry.skill.replace(/-/g, "_")}_stale_mode_state`,
+					systemMessage: coherenceMessage,
+				};
+			}
+			// Deep-interview must not terminalize through an ordinary stop without
+			// crystallizing its distilled interview state into a spec/handoff
+			// (explicit abort/cancel and the active:false demotion are preserved
+			// as legitimate terminals). See #674.
+			const uncrystallized = await detectUncrystallizedDeepInterviewStop(entry.skill, modeState, input.cwd);
+			if (uncrystallized) {
+				const crystallizeMessage = `GJC deep-interview must crystallize before stopping (${modeStatePath(
+					resolvedStateDir,
+					entry.skill,
+					input.sessionId,
+				)}): ${uncrystallized}.`;
+				return {
+					decision: "block",
+					reason: crystallizeMessage,
+					stopReason: "gjc_skill_deep_interview_uncrystallized",
+					systemMessage: crystallizeMessage,
+				};
+			}
+			continue;
+		}
 		const phase = String(modeState?.current_phase ?? entry.phase ?? skillState.phase ?? "active");
 		const statePath = modeStatePath(resolvedStateDir, entry.skill, input.sessionId);
 		if (entry.skill === "ultragoal") {