@gajae-code/coding-agent 0.6.4 → 0.7.0

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

@@ -1,5 +1,6 @@
 import * as fs from "node:fs/promises";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
+import { resolveGjcSessionForRead, SessionResolutionError } from "./session-resolution";
 import {
 	computeUltragoalPlanGeneration,
 	getUltragoalPaths,
@@ -10,6 +11,7 @@ import {
 	type UltragoalCompletionVerification,
 	type UltragoalGoal,
 	type UltragoalLedgerEvent,
+	type UltragoalPaths,
 	type UltragoalPlan,
 	type UltragoalReceiptKind,
 } from "./ultragoal-runtime";
@@ -63,9 +65,30 @@ function isKnownUltragoalObjective(currentObjective: string): boolean {
 	);
 }
 
+async function ultragoalReadPaths(cwd: string): Promise<UltragoalPaths> {
+	const envSessionId = process.env.GJC_SESSION_ID?.trim();
+	if (envSessionId) return getUltragoalPaths(cwd, envSessionId);
+	try {
+		const session = await resolveGjcSessionForRead(cwd, { envSessionId: process.env.GJC_SESSION_ID });
+		return getUltragoalPaths(cwd, session.gjcSessionId);
+	} catch (error) {
+		if (error instanceof SessionResolutionError && error.code === "no_session") {
+			return getUltragoalPaths(cwd, null);
+		}
+		throw error;
+	}
+}
+
 async function hasDurableUltragoalState(cwd: string): Promise<boolean> {
+	let paths: UltragoalPaths;
+	try {
+		paths = await ultragoalReadPaths(cwd);
+	} catch (error) {
+		if (error instanceof SessionResolutionError) return true;
+		throw error;
+	}
 	try {
-		await fs.stat(getUltragoalPaths(cwd).dir);
+		await fs.stat(paths.dir);
 		return true;
 	} catch (error) {
 		if (
@@ -265,14 +288,15 @@ export function validateCompletionReceipt(input: {
 export async function readUltragoalVerificationState(input: {
 	cwd: string;
 	currentGoal?: CurrentGoalLike | null;
+	sessionId?: string | null;
 }): Promise<UltragoalGuardDiagnostic> {
 	const currentObjective = input.currentGoal?.objective?.trim() ?? "";
 	if (!currentObjective) return { state: "inactive", message: "No current goal objective is active." };
 	let plan: UltragoalPlan | null;
 	let ledger: UltragoalLedgerEvent[];
 	try {
-		plan = await readUltragoalPlan(input.cwd);
-		ledger = await readUltragoalLedger(input.cwd);
+		plan = await readUltragoalPlan(input.cwd, input.sessionId ?? undefined);
+		ledger = await readUltragoalLedger(input.cwd, input.sessionId ?? undefined);
 	} catch (error) {
 		if (currentObjective === DEFAULT_ULTRAGOAL_OBJECTIVE) {
 			return {
@@ -308,6 +332,18 @@ export async function readUltragoalVerificationState(input: {
 	}
 	const receiptTarget = findReceiptGoal(plan, currentObjective);
 	if (!receiptTarget) {
+		// When earlier required goals are already complete but later ones remain, name the
+		// specific blocking goals (a final-aggregate receipt cannot exist yet anyway). Only
+		// fall back to the generic missing-receipt message when no progress has been verified.
+		const completedRequired = requiredGoals(plan).filter(goal => goal.status === "complete");
+		if (completedRequired.length > 0 && runState.incompleteGoals.length > 0) {
+			return {
+				state: "active_missing_final_receipt",
+				message: `Ultragoal still has incomplete required goals: ${runState.incompleteGoals
+					.map(goal => goal.id)
+					.join(", ")}. Run \`gjc ultragoal complete-goals\` to continue.`,
+			};
+		}
 		return {
 			state: "active_missing_final_receipt",
 			message: "Ultragoal aggregate completion requires a fresh final aggregate receipt.",
@@ -331,7 +367,15 @@ export async function readUltragoalVerificationState(input: {
 }
 
 export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic> {
-	const paths = getUltragoalPaths(cwd);
+	let paths: UltragoalPaths;
+	try {
+		paths = await ultragoalReadPaths(cwd);
+	} catch (error) {
+		return activeAskDiagnostic({
+			reason: `Unable to resolve durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
+			source: "durable_state_unreadable",
+		});
+	}
 	try {
 		await fs.stat(paths.dir);
 	} catch (error) {
@@ -436,6 +480,7 @@ export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBl
 export async function assertCanCompleteCurrentGoal(input: {
 	cwd: string;
 	currentGoal?: CurrentGoalLike | null;
+	sessionId?: string | null;
 }): Promise<void> {
 	if (!input.cwd) return;
 	const diagnostic = await readUltragoalVerificationState(input);
@@ -453,3 +498,56 @@ export function isUltragoalBypassPrompt(prompt: string): boolean {
 		) || /goal[\s\S]{0,80}complete/i.test(normalized)
 	);
 }
+export interface UltragoalPauseBlockDiagnostic {
+	blocked: boolean;
+	reason: string;
+}
+
+/**
+ * While an Ultragoal run is active, `goal({"op":"pause"})` is only allowed when the
+ * current durable Ultragoal state is readable and the latest durable ledger event
+ * classifies the current blocker as `human_blocked`. Resolvable blockers must be
+ * worked, not parked. Reads fail closed so unreadable durable state or ledger data
+ * blocks pause rather than silently allowing a give-up.
+ */
+export async function isUltragoalPauseBlocked(cwd: string): Promise<UltragoalPauseBlockDiagnostic> {
+	if (!cwd) return { blocked: false, reason: "No cwd to resolve durable Ultragoal state." };
+	const ask = await isUltragoalAskBlocked(cwd);
+	if (ask.source === "durable_state_unreadable") {
+		return {
+			blocked: true,
+			reason: `Unable to verify current durable Ultragoal state for pause: ${ask.reason}`,
+		};
+	}
+	if (!ask.active) return { blocked: false, reason: "No active Ultragoal run." };
+	let ledger: UltragoalLedgerEvent[];
+	try {
+		ledger = await readUltragoalLedger(cwd);
+	} catch (error) {
+		return {
+			blocked: true,
+			reason: `Unable to read durable Ultragoal ledger: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	const latest = ledger.at(-1);
+	if (latest?.event === "blocker_classified" && latest.classification === "human_blocked") {
+		return { blocked: false, reason: "Latest Ultragoal ledger event classifies the blocker as human_blocked." };
+	}
+	return {
+		blocked: true,
+		reason:
+			"An Ultragoal run is active. Pausing requires the current blocker to be classified human_blocked as the latest ledger event.",
+	};
+}
+
+export async function assertUltragoalPauseAllowed(cwd: string): Promise<void> {
+	const diagnostic = await isUltragoalPauseBlocked(cwd);
+	if (!diagnostic.blocked) return;
+	throw new Error(
+		[
+			diagnostic.reason,
+			"Resolvable blockers must be worked, not paused: investigate, `gjc ultragoal steer --kind add_subgoal`, delegate an executor, or `gjc ultragoal record-review-blockers`.",
+			'If the blocker is genuinely human-only, record `gjc ultragoal classify-blocker --classification human_blocked --evidence "<human-only dependency>"` immediately before pausing.',
+		].join("\n"),
+	);
+}