@gajae-code/coding-agent 0.11.7 → 0.11.9

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

@@ -11,6 +11,7 @@ import {
 	type WorkflowStateMutationOwner,
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
+import { validateDeepInterviewV1Envelope } from "./deep-interview-state";
 import {
 	activeEntryPath as layoutActiveEntryPath,
 	activeSnapshotPath as layoutActiveSnapshotPath,
@@ -77,6 +78,47 @@ export interface WorkflowEnvelopeIntegrityMismatch {
 	expected: string;
 	actual: string;
 }
+export type WorkflowReceiptVerification =
+	| "legacy"
+	| "native-valid"
+	| "receipt-malformed"
+	| "receipt-missing"
+	| "checksum-mismatch";
+
+export interface GuardedWorkflowEnvelopeTransformOptions extends StateWriterOptions {
+	expectedRevision: number;
+	/** Additional native schema validation applied to both current and candidate envelopes. */
+	validate?: (value: Record<string, unknown>, legacy: boolean) => void;
+	transform: (
+		current: Record<string, unknown>,
+		context: { revision: number; legacy: boolean },
+	) =>
+		| { kind: "noop" }
+		| { kind: "write"; value: Record<string, unknown> }
+		| Promise<{ kind: "noop" } | { kind: "write"; value: Record<string, unknown> }>;
+}
+
+export interface GuardedWorkflowEnvelopeWarning {
+	code: "DI_POST_COMMIT_AUDIT_FAILED";
+	message: string;
+}
+
+export type GuardedWorkflowEnvelopeTransformResult =
+	| { path: string; written: false; reason: "noop"; revision: number; warnings: [] }
+	| {
+			path: string;
+			written: true;
+			revision: number;
+			stamped: Record<string, unknown>;
+			warnings: GuardedWorkflowEnvelopeWarning[];
+	  };
+
+export class GuardedWorkflowEnvelopeError extends Error {
+	constructor(public readonly code: string) {
+		super(code);
+		this.name = "GuardedWorkflowEnvelopeError";
+	}
+}
 
 export interface WorkflowTransactionJournal {
 	version: 1;
@@ -108,6 +150,7 @@ export interface StateWriterOptions {
 	receipt?: StateWriterReceiptContext;
 	audit?: StateWriterAuditContext;
 	sourceRevision?: number;
+	orderingRevision?: number;
 	/**
 	 * Cross-process lock tuning for read-modify-write paths that route through
 	 * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
@@ -255,6 +298,49 @@ export function workflowEnvelopeContentSha256(value: unknown): string {
 		.update(JSON.stringify(canonicalizeJson(withoutReceiptChecksum(value))))
 		.digest("hex");
 }
+function isNativeDeepInterviewV1(value: Record<string, unknown>): boolean {
+	if (value.skill !== "deep-interview") return false;
+	return value.schema_version === 1 || (isPlainObject(value.state) && value.state.schema_version === 1);
+}
+
+export function verifyWorkflowEnvelopeReceiptValue(value: unknown, filePath: string): WorkflowReceiptVerification {
+	if (!isPlainObject(value)) return "receipt-malformed";
+	const native = isNativeDeepInterviewV1(value);
+	if (!Object.hasOwn(value, "receipt")) return native ? "receipt-missing" : "legacy";
+	if (!isPlainObject(value.receipt) || !isPlainObject(value.receipt.content_sha256)) return "receipt-malformed";
+
+	const receipt = value.receipt as Record<string, unknown>;
+	const checksum = receipt.content_sha256 as Record<string, unknown>;
+	if (
+		typeof value.skill !== "string" ||
+		receipt.version !== 1 ||
+		receipt.skill !== value.skill ||
+		(receipt.skill !== "deep-interview" &&
+			receipt.skill !== "ralplan" &&
+			receipt.skill !== "ultragoal" &&
+			receipt.skill !== "team") ||
+		(receipt.owner !== "gjc-state-cli" && receipt.owner !== "gjc-runtime" && receipt.owner !== "gjc-hook") ||
+		typeof receipt.command !== "string" ||
+		typeof receipt.state_path !== "string" ||
+		typeof receipt.storage_path !== "string" ||
+		typeof receipt.mutated_at !== "string" ||
+		!Number.isFinite(Date.parse(receipt.mutated_at)) ||
+		typeof receipt.fresh_until !== "string" ||
+		!Number.isFinite(Date.parse(receipt.fresh_until)) ||
+		(receipt.status !== "fresh" && receipt.status !== "stale") ||
+		typeof receipt.mutation_id !== "string" ||
+		checksum.algorithm !== "sha256" ||
+		typeof checksum.value !== "string" ||
+		!/^[0-9a-f]{64}$/.test(checksum.value) ||
+		typeof checksum.covered_path !== "string" ||
+		path.resolve(checksum.covered_path) !== path.resolve(filePath) ||
+		typeof checksum.computed_at !== "string" ||
+		!Number.isFinite(Date.parse(checksum.computed_at))
+	) {
+		return "receipt-malformed";
+	}
+	return workflowEnvelopeContentSha256(value) === checksum.value ? "native-valid" : "checksum-mismatch";
+}
 
 export function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, computedAt = new Date().toISOString()): T {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
@@ -421,6 +507,11 @@ function persistedSourceRevision(value: unknown): number {
 	const revision = value.source_state_revision;
 	return typeof revision === "number" && Number.isFinite(revision) ? revision : persistedStateRevision(value);
 }
+function persistedCommittedModeRevision(value: unknown): number {
+	if (!isPlainObject(value)) return 0;
+	const revision = value.committed_mode_state_revision;
+	return typeof revision === "number" && Number.isFinite(revision) ? revision : 0;
+}
 
 function withoutCandidateRevision(value: unknown): unknown {
 	if (!isPlainObject(value)) return value;
@@ -529,7 +620,12 @@ async function writeGuardedResolvedJsonAtomic(
 
 			const incomingSourceRevision =
 				options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
-			if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
+			if (
+				current !== undefined &&
+				(options.orderingRevision !== undefined
+					? options.orderingRevision <= persistedCommittedModeRevision(current)
+					: incomingSourceRevision <= persistedSourceRevision(current))
+			) {
 				return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
 			}
 			const next = stampStateRevision(
@@ -563,6 +659,7 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 	const write = async (): Promise<GuardedWriteResult> => {
 		const current = await readJsonIfPresentTolerant(filePath);
 		const currentRevision = persistedStateRevision(current);
+
 		if (options.policy === "source") {
 			if (options.expectedRevision !== undefined && options.expectedRevision !== currentRevision) {
 				throw new StateWriteConflictError(filePath, options.expectedRevision, currentRevision);
@@ -586,9 +683,15 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 			await maybeAudit(filePath, options);
 			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 		}
+
 		const incomingSourceRevision =
 			options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
-		if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
+		if (
+			current !== undefined &&
+			(options.orderingRevision !== undefined
+				? options.orderingRevision <= persistedCommittedModeRevision(current)
+				: incomingSourceRevision <= persistedSourceRevision(current))
+		) {
 			return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
 		}
 		const next = stampWorkflowEnvelopeRevisionAndChecksum(
@@ -612,6 +715,67 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 	};
 	return options.lockHeld ? write() : lockResolvedWorkflowTarget(filePath, write, options.lock);
 }
+export async function transformGuardedWorkflowEnvelopeAtomic(
+	targetPath: string,
+	options: GuardedWorkflowEnvelopeTransformOptions,
+): Promise<GuardedWorkflowEnvelopeTransformResult> {
+	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
+	return lockResolvedWorkflowTarget(
+		filePath,
+		async () => {
+			const read = await readExistingStateForMutation(filePath);
+			if (read.kind === "absent") throw new GuardedWorkflowEnvelopeError("DI_STATE_ABSENT");
+			if (read.kind === "corrupt") throw new GuardedWorkflowEnvelopeError("DI_STATE_CORRUPT");
+			const receipt = verifyWorkflowEnvelopeReceiptValue(read.value, filePath);
+			if (receipt === "receipt-malformed") throw new GuardedWorkflowEnvelopeError("DI_RECEIPT_MALFORMED");
+			if (receipt === "receipt-missing") throw new GuardedWorkflowEnvelopeError("DI_RECEIPT_MISSING");
+			if (receipt === "checksum-mismatch") throw new GuardedWorkflowEnvelopeError("DI_RECEIPT_CHECKSUM_MISMATCH");
+			const legacy = receipt === "legacy";
+			try {
+				if (isNativeDeepInterviewV1(read.value)) validateDeepInterviewV1Envelope(read.value);
+				options.validate?.(read.value, legacy);
+			} catch {
+				throw new GuardedWorkflowEnvelopeError("DI_STATE_SCHEMA_INVALID");
+			}
+			const phase = read.value.current_phase;
+			if (phase === "complete" || phase === "handoff" || read.value.active === false) {
+				throw new GuardedWorkflowEnvelopeError("DI_PHASE_NOT_REPAIRABLE");
+			}
+			const revision = persistedStateRevision(read.value);
+			if (revision !== options.expectedRevision) throw new GuardedWorkflowEnvelopeError("DI_REVISION_CONFLICT");
+			const transformed = await options.transform(read.value, { revision, legacy });
+			if (transformed.kind === "noop")
+				return { path: filePath, written: false, reason: "noop", revision, warnings: [] };
+			try {
+				if (isNativeDeepInterviewV1(transformed.value)) validateDeepInterviewV1Envelope(transformed.value);
+				options.validate?.(transformed.value, false);
+			} catch {
+				throw new GuardedWorkflowEnvelopeError("DI_STATE_SCHEMA_INVALID");
+			}
+			const stamped = stampWorkflowEnvelopeRevisionAndChecksum(
+				transformed.value,
+				filePath,
+				revision + 1,
+				undefined,
+				options,
+			) as Record<string, unknown>;
+			const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
+			if (!parsed.success) throw new GuardedWorkflowEnvelopeError("DI_STATE_SCHEMA_INVALID");
+			await atomicWrite(filePath, jsonText(stamped));
+			const warnings: GuardedWorkflowEnvelopeWarning[] = [];
+			try {
+				await maybeAudit(filePath, options);
+			} catch (error) {
+				warnings.push({
+					code: "DI_POST_COMMIT_AUDIT_FAILED",
+					message: error instanceof Error ? error.message : String(error),
+				});
+			}
+			return { path: filePath, written: true, revision: revision + 1, stamped, warnings };
+		},
+		options.lock,
+	);
+}
 
 export async function writeJsonAtomic(
 	targetPath: string,

package/src/gjc-runtime/tmux-owner-isolation.ts

@@ -1646,7 +1646,8 @@ export function isValidOwnerIntent(intent: unknown, request?: ObserveTerminalReq
 		intent.generation === request.owner_generation &&
 		intent.session_id === request.session_id &&
 		intent.server_key === request.socket_key &&
-		(request.operator_dispatch_id === undefined || intent.dispatch_id === request.operator_dispatch_id) &&
+		request.operator_dispatch_id !== undefined &&
+		intent.dispatch_id === request.operator_dispatch_id &&
 		request.signal === "SIGTERM"
 	);
 }

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

@@ -3,6 +3,7 @@ import * as crypto from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { Process } from "@gajae-code/natives";
 import { readLinuxProcStartTime, readLinuxProcStartTimeSync } from "./linux-proc";
 import { resolveGjcTmuxBinary } from "./psmux-detect";
 import { tmuxRuntimeSessionPath } from "./session-layout";
@@ -43,6 +44,7 @@ import {
 	lifecyclePaths,
 	type OwnerIsolationProbeSync,
 	type OwnerVerdict,
+	observeOwnerTerminal,
 	type PlanResponse,
 	planTmuxOwnerIsolationSync,
 	replaceOwnerGenerationSync,
@@ -963,6 +965,14 @@ async function readProcessStartTime(pid: number): Promise<string | null> {
 	return readLinuxProcStartTime(pid);
 }
 
+function exactManagedOwnerSupervisor(supervisorPid: number, supervisorStartTime: string): Process {
+	const supervisor = Process.fromPid(supervisorPid);
+	if (!supervisor) throw new Error("managed_owner_supervisor_unverifiable");
+	if (process.platform === "linux" && supervisor.incarnation !== `linux:${supervisorStartTime}`)
+		throw new Error("managed_owner_supervisor_incarnation_mismatch");
+	return supervisor;
+}
+
 async function readCurrentGeneration(stateDir: string, sessionId: string): Promise<string | null> {
 	try {
 		const value: unknown = JSON.parse(
@@ -1016,12 +1026,12 @@ async function requireUnchangedOwnerForCompatibilityCleanup(
 	initialServer: { pid: number; startTime: string },
 	listPanePids: (sessionName: string, env: NodeJS.ProcessEnv) => number[],
 	readStartTime: (pid: number) => Promise<string | null>,
-): Promise<void> {
+): Promise<boolean> {
 	try {
 		const currentNativeSessionId = readNativeTmuxSessionId(nativeSessionId, env);
 		if (!currentNativeSessionId) {
 			if (readNativeTmuxSessionId(sessionName, env)) throw new Error(`gjc_tmux_owner_changed:${sessionName}`);
-			return;
+			return false;
 		}
 		const currentServer = requireSafeTmuxServerForMutation(resolveGjcTmuxCommand(env), env);
 		const panePids = listPanePids(nativeSessionId, env);
@@ -1054,10 +1064,11 @@ async function requireUnchangedOwnerForCompatibilityCleanup(
 				: null,
 		].filter((value): value is string => value !== null);
 		if (mismatches.length > 0) throw new Error(`gjc_tmux_owner_changed:${sessionName}:${mismatches.join(",")}`);
+		return true;
 	} catch (error) {
 		if (!readNativeTmuxSessionId(nativeSessionId, env)) {
 			if (readNativeTmuxSessionId(sessionName, env)) throw new Error(`gjc_tmux_owner_changed:${sessionName}`);
-			return;
+			return false;
 		}
 		if (error instanceof Error && error.message.startsWith(`gjc_tmux_owner_changed:${sessionName}`))
 			throw new Error(`gjc_tmux_owner_changed:${sessionName}`);
@@ -1152,6 +1163,7 @@ export async function forceCloseGjcTmuxSession(
 	const now = deps.now ?? (() => new Date());
 	const sleep = deps.sleep ?? (ms => Bun.sleep(ms));
 	const dispatchId = crypto.randomUUID();
+	let operatorVerdict: Promise<OwnerVerdict> | null = null;
 	await closeExactTmuxOwner(
 		{
 			stateDir: identity.stateDir,
@@ -1169,12 +1181,37 @@ export async function forceCloseGjcTmuxSession(
 			sendSigterm: async pid => {
 				if ((await (deps.readProcessStartTime ?? readProcessStartTime)(pid)) !== identity.startTime)
 					throw new Error("owner_pid_identity_mismatch");
-				(deps.signalTerm ?? (target => process.kill(target, "SIGTERM")))(pid);
+				if (deps.signalTerm) {
+					deps.signalTerm(pid);
+				} else {
+					const supervisor = exactManagedOwnerSupervisor(pid, identity.startTime);
+					if (!supervisor.signalRoot(15)) throw new Error("managed_owner_supervisor_signal_failed");
+					operatorVerdict = supervisor
+						.waitForExit({ timeoutMs: FORCE_CLOSE_VERDICT_TIMEOUT_MS - 500 })
+						.then(async exited => {
+							if (!exited) throw new Error("managed_owner_supervisor_exit_timeout");
+							return await observeOwnerTerminal({
+								schema_version: 1,
+								op: "observe_terminal",
+								session_id: identity.sessionId,
+								owner_generation: identity.generation,
+								state_dir: identity.stateDir,
+								socket_key: identity.socketKey,
+								observer: "raw_monitor",
+								observed_at: now().toISOString(),
+								signal: "SIGTERM",
+								exit_code: null,
+								exit_kind: "exact_owner_exit_observed",
+								reason: "operator_observed_owner_exit",
+								operator_dispatch_id: dispatchId,
+							});
+						});
+				}
 			},
 
-			waitForVerdict: () => waitForExpectedVerdict(identity, sleep, now),
+			waitForVerdict: () => operatorVerdict ?? waitForExpectedVerdict(identity, sleep, now),
 			cleanupSession: async () => {
-				await requireUnchangedOwnerForCompatibilityCleanup(
+				const cleanupRequired = await requireUnchangedOwnerForCompatibilityCleanup(
 					session.name,
 					nativeSessionId,
 					env,
@@ -1184,6 +1221,7 @@ export async function forceCloseGjcTmuxSession(
 					deps.listPanePids ?? readExactSessionPanePids,
 					deps.readProcessStartTime ?? readProcessStartTime,
 				);
+				if (!cleanupRequired) return;
 				if (deps.cleanupSession) deps.cleanupSession(nativeSessionId, env);
 				else
 					runGuardedTmuxSessionCommand(
@@ -1192,6 +1230,7 @@ export async function forceCloseGjcTmuxSession(
 						initialServer.pid,
 						env,
 						`kill-session -t '${nativeSessionId}'`,
+						identity.generation,
 					);
 			},
 		},

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

@@ -76,12 +76,12 @@ function objectiveMatches(currentGoal: CurrentGoalLike, plan: UltragoalPlan, ses
 	return plan.goals.some(goal => goal.objective === normalized);
 }
 
-function isKnownUltragoalObjective(currentObjective: string): boolean {
+export function isKnownUltragoalObjective(currentObjective: string): boolean {
 	const normalized = currentObjective.trim();
-	return (
-		normalized === DEFAULT_ULTRAGOAL_OBJECTIVE ||
-		(normalized.includes(".gjc/ultragoal/goals.json") && normalized.includes(".gjc/ultragoal/ledger.jsonl"))
-	);
+	// Exact default aggregate objective only. Substring path sniffing previously
+	// treated arbitrary objectives that merely mentioned goals.json/ledger paths
+	// as Ultragoal-owned, which could mis-arm guards. Prefer fail-closed.
+	return normalized === DEFAULT_ULTRAGOAL_OBJECTIVE;
 }
 
 async function ultragoalReadPaths(

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

@@ -5,6 +5,12 @@ import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
+import {
+	assertCwdMatchesRepositoryBinding,
+	captureRepositoryBinding,
+	parseRepositoryBinding,
+	type RepositoryBinding,
+} from "./repository-binding";
 import {
 	CRITIC_GATE_HARD_STOP_EVENT,
 	CRITIC_GATE_OVERRIDE_EVENT,
@@ -192,6 +198,8 @@ export interface UltragoalPlan {
 	gjcObjective: string;
 	gjcObjectiveAliases?: string[];
 	goals: UltragoalGoal[];
+	/** Authoritative repository identity for multi-repo fail-closed spawn (#2901). */
+	repositoryBinding?: RepositoryBinding;
 	createdAt: string;
 	updatedAt: string;
 	[key: string]: unknown;
@@ -1349,6 +1357,10 @@ function normalizePlan(raw: unknown): UltragoalPlan {
 				(value): value is string => typeof value === "string" && value.trim().length > 0,
 			)
 		: undefined;
+	let repositoryBinding: RepositoryBinding | undefined;
+	if (record.repositoryBinding !== undefined) {
+		repositoryBinding = parseRepositoryBinding(record.repositoryBinding);
+	}
 	return {
 		version: 1,
 		brief,
@@ -1358,6 +1370,7 @@ function normalizePlan(raw: unknown): UltragoalPlan {
 		goals,
 		createdAt,
 		updatedAt,
+		...(repositoryBinding ? { repositoryBinding } : {}),
 		...(typeof record.state_revision === "number" && Number.isFinite(record.state_revision)
 			? { state_revision: record.state_revision }
 			: {}),
@@ -1558,12 +1571,16 @@ export async function createUltragoalPlan(input: {
 		goal.validationBatch = validationBatchByGoalId.get(goal.id);
 		validateValidationBatchPipelineExclusion(goal);
 	}
+	const repositoryBinding = await captureRepositoryBinding(input.cwd, {
+		displayPath: input.cwd,
+	});
 	const plan: UltragoalPlan = {
 		version: 1,
 		brief,
 		gjcGoalMode: input.gjcGoalMode ?? "aggregate",
 		gjcObjective: DEFAULT_ULTRAGOAL_OBJECTIVE,
 		goals,
+		repositoryBinding,
 		createdAt: now,
 		updatedAt: now,
 	};
@@ -1639,6 +1656,50 @@ export function getUltragoalRunCompletionState(
 	};
 }
 
+/**
+ * Discriminated next-action for `complete-goals` handoff (#2903).
+ * `none` is reserved for genuine completion; `execute-goal` always carries a goal.
+ */
+export type UltragoalCompleteNextActionKind =
+	| "none"
+	| "execute-goal"
+	| "retry-failed"
+	| "resolve-blockers"
+	| "final-aggregate-receipt";
+
+export type UltragoalCompleteNextAction = {
+	kind: UltragoalCompleteNextActionKind;
+	goal?: UltragoalGoal;
+	blockedGoals?: UltragoalGoal[];
+	failedGoals?: UltragoalGoal[];
+};
+
+/**
+ * Resolve the actionable next step after scheduling / complete-goals.
+ * Blocked and review_blocked goals remain unschedulable; they surface as
+ * `resolve-blockers` instead of a contradictory `execute-goal` without goal_id.
+ */
+export function resolveUltragoalCompleteNextAction(
+	plan: UltragoalPlan,
+	options: { retryFailed?: boolean; selectedGoal?: UltragoalGoal } = {},
+): UltragoalCompleteNextAction {
+	const state = getUltragoalRunCompletionState(plan, { retryFailed: options.retryFailed });
+	// Genuine completion keeps next_action=`none` (historical complete-goals contract).
+	// final-aggregate-receipt is reserved for a future dedicated handoff; do not remap
+	// allComplete here so aggregate runs still finish with `none` / complete text.
+	if (state.allComplete) return { kind: "none" };
+	const goal = options.selectedGoal ?? state.nextGoal;
+	if (goal) return { kind: "execute-goal", goal };
+	const blockedGoals = state.incompleteGoals.filter(
+		item => item.status === "blocked" || item.status === "review_blocked",
+	);
+	if (blockedGoals.length > 0) return { kind: "resolve-blockers", blockedGoals };
+	const failedGoals = state.incompleteGoals.filter(item => item.status === "failed");
+	if (failedGoals.length > 0) return { kind: "retry-failed", failedGoals };
+	// Incomplete but not schedulable (unexpected statuses): still actionable, not "none".
+	return { kind: "resolve-blockers", blockedGoals: state.incompleteGoals };
+}
+
 export async function startNextUltragoalGoal(input: {
 	cwd: string;
 	retryFailed?: boolean;
@@ -1647,11 +1708,27 @@ export async function startNextUltragoalGoal(input: {
 	plan: UltragoalPlan;
 	goal?: UltragoalGoal;
 	allComplete: boolean;
+	nextAction: UltragoalCompleteNextAction;
 }> {
 	const plan = await readUltragoalPlan(input.cwd, input.sessionId);
 	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const goal = chooseNextGoal(plan, input.retryFailed === true);
-	if (!goal) return { plan, allComplete: getUltragoalRunCompletionState(plan).allComplete };
+	// Fail closed: delegated execution requires stamped repository authority (#2901).
+	if (!plan.repositoryBinding) {
+		throw new Error(
+			"Ultragoal plan is missing repositoryBinding; recreate goals so the plan is bound to an authoritative repository identity.",
+		);
+	}
+	await assertCwdMatchesRepositoryBinding(input.cwd, plan.repositoryBinding);
+	const retryFailed = input.retryFailed === true;
+	const goal = chooseNextGoal(plan, retryFailed);
+	if (!goal) {
+		const state = getUltragoalRunCompletionState(plan, { retryFailed });
+		return {
+			plan,
+			allComplete: state.allComplete,
+			nextAction: resolveUltragoalCompleteNextAction(plan, { retryFailed }),
+		};
+	}
 	if (goal.status !== "active") {
 		const now = new Date().toISOString();
 		goal.status = "active";
@@ -1661,7 +1738,12 @@ export async function startNextUltragoalGoal(input: {
 		await writePlan(input.cwd, plan, input.sessionId);
 		await appendLedger(input.cwd, { event: "goal_started", goalId: goal.id }, input.sessionId);
 	}
-	return { plan, goal, allComplete: false };
+	return {
+		plan,
+		goal,
+		allComplete: false,
+		nextAction: { kind: "execute-goal", goal },
+	};
 }
 
 async function readStructuredValue(cwd: string, value: string): Promise<unknown> {
@@ -4237,31 +4319,111 @@ function renderStatus(summary: UltragoalStatusSummary, json: boolean): string {
 	return renderUltragoalStatusMarkdown(summary);
 }
 
+function summarizeBlockedGoalForHandoff(goal: UltragoalGoal): {
+	id: string;
+	status: UltragoalGoalStatus;
+	evidence?: string;
+} {
+	const evidence = typeof goal.evidence === "string" && goal.evidence.trim() ? goal.evidence.trim() : undefined;
+	return {
+		id: goal.id,
+		status: goal.status,
+		...(evidence ? { evidence } : {}),
+	};
+}
+
 function renderCompleteHandoff(
-	result: { plan: UltragoalPlan; goal?: UltragoalGoal; allComplete: boolean },
+	result: {
+		plan: UltragoalPlan;
+		goal?: UltragoalGoal;
+		allComplete: boolean;
+		nextAction?: UltragoalCompleteNextAction;
+	},
 	json: boolean,
 	cwd: string,
 ): string {
+	const nextAction =
+		result.nextAction ??
+		resolveUltragoalCompleteNextAction(result.plan, {
+			selectedGoal: result.goal,
+		});
+	const goalsPath = getUltragoalPaths(cwd, currentUltragoalSessionId(cwd)).goalsPath;
+
 	if (json) {
-		return renderCliWriteReceipt({
+		const receipt: Record<string, unknown> = {
 			ok: true,
 			all_complete: result.allComplete,
-			next_action: result.allComplete ? "none" : "execute-goal",
-			goal_id: result.goal?.id,
-			goal_status: result.goal?.status,
+			next_action: nextAction.kind,
 			gjc_objective: result.plan.gjcObjective,
-			goals_path: getUltragoalPaths(cwd, currentUltragoalSessionId(cwd)).goalsPath,
-		});
+			goals_path: goalsPath,
+		};
+		if (nextAction.kind === "execute-goal" && nextAction.goal) {
+			receipt.goal_id = nextAction.goal.id;
+			receipt.goal_status = nextAction.goal.status;
+		}
+		if (nextAction.kind === "resolve-blockers" && nextAction.blockedGoals) {
+			receipt.blocked_goals = nextAction.blockedGoals.map(summarizeBlockedGoalForHandoff);
+			receipt.blocked_goal_ids = nextAction.blockedGoals.map(goal => goal.id);
+			receipt.recovery_hints = [
+				"gjc ultragoal classify-blocker --help",
+				"gjc ultragoal record-review-blockers --help",
+				"gjc ultragoal steer --kind add_subgoal --help",
+				"gjc ultragoal steer --kind mark_blocked_superseded --help",
+			];
+		}
+		if (nextAction.kind === "retry-failed" && nextAction.failedGoals) {
+			receipt.failed_goal_ids = nextAction.failedGoals.map(goal => goal.id);
+			receipt.recovery_hints = ["gjc ultragoal complete-goals --retry-failed"];
+		}
+		if (nextAction.kind === "final-aggregate-receipt") {
+			receipt.recovery_hints = [
+				"Finalize the aggregate completion receipt before treating the ultragoal run as closed.",
+			];
+		}
+		return renderCliWriteReceipt(receipt);
 	}
-	if (result.allComplete) return "ultragoal complete all=true\n";
-	if (!result.goal) return "ultragoal next-action=none\n";
-	return [
-		`ultragoal next-action=execute-goal goal-id=${result.goal.id}`,
-		`objective=${result.goal.objective}`,
-		`gjc-objective=${result.plan.gjcObjective}`,
-		"checkpoint requires=architectReview:CLEAR+APPROVE,executorQa:passed",
-		"",
-	].join("\n");
+
+	if (nextAction.kind === "none" || (result.allComplete && nextAction.kind !== "final-aggregate-receipt")) {
+		return "ultragoal complete all=true\n";
+	}
+	if (nextAction.kind === "final-aggregate-receipt") {
+		return [
+			"ultragoal next-action=final-aggregate-receipt",
+			"hint=finalize the aggregate completion receipt before treating the run as closed",
+			"",
+		].join("\n");
+	}
+	if (nextAction.kind === "execute-goal" && nextAction.goal) {
+		return [
+			`ultragoal next-action=execute-goal goal-id=${nextAction.goal.id}`,
+			`objective=${nextAction.goal.objective}`,
+			`gjc-objective=${result.plan.gjcObjective}`,
+			"checkpoint requires=architectReview:CLEAR+APPROVE,executorQa:passed",
+			"",
+		].join("\n");
+	}
+	if (nextAction.kind === "resolve-blockers" && nextAction.blockedGoals && nextAction.blockedGoals.length > 0) {
+		const ids = nextAction.blockedGoals.map(goal => goal.id).join(",");
+		const statuses = nextAction.blockedGoals.map(goal => `${goal.id}:${goal.status}`).join(",");
+		return [
+			"ultragoal next-action=resolve-blockers",
+			`blocked-goal-ids=${ids}`,
+			`blocked-statuses=${statuses}`,
+			"hint=resolve blockers via classify-blocker / record-review-blockers / steer --kind add_subgoal (or audited mark_blocked_superseded); blocked goals stay unschedulable",
+			"",
+		].join("\n");
+	}
+	if (nextAction.kind === "retry-failed" && nextAction.failedGoals && nextAction.failedGoals.length > 0) {
+		const ids = nextAction.failedGoals.map(goal => goal.id).join(",");
+		return [
+			"ultragoal next-action=retry-failed",
+			`failed-goal-ids=${ids}`,
+			"hint=run `gjc ultragoal complete-goals --retry-failed` after the failure is addressed",
+			"",
+		].join("\n");
+	}
+	// Fail closed: never claim complete or execute-goal without a goal id.
+	return "ultragoal next-action=resolve-blockers\nhint=no schedulable goal; inspect goals.json and ledger\n";
 }
 function renderCheckpointContinuation(
 	result: UltragoalCheckpointContinuation,