@gajae-code/coding-agent 0.5.1 → 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/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 (

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/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") {