@gajae-code/coding-agent 0.6.5 → 0.7.1

package/src/extensibility/extensions/types.ts

@@ -32,6 +32,7 @@ import type { PythonResult } from "../../eval/py/executor";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
 import type { Theme } from "../../modes/theme/theme";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
@@ -310,6 +311,11 @@ export interface ExtensionContext {
 	getSystemPrompt(): string[];
 	/** @deprecated Use hasPendingMessages() instead */
 	hasQueuedMessages(): boolean;
+	/**
+	 * Unattended workflow-gate bridge. Present only when the session runs in
+	 * unattended/RPC mode; `undefined` in interactive/TUI mode (notify-only).
+	 */
+	workflowGate?: WorkflowGateEmitter;
 }
 
 /**
@@ -1234,6 +1240,8 @@ export interface ExtensionContextActions {
 	getContextUsage: () => ContextUsage | undefined;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 	getSystemPrompt: () => string[];
+	/** Unattended workflow-gate bridge (present only in unattended/RPC mode). */
+	getWorkflowGate?: () => WorkflowGateEmitter | undefined;
 }
 
 /** Actions for ExtensionCommandContext (ctx.* in command handlers). */

package/src/gjc-runtime/deep-interview-recorder.ts

@@ -326,13 +326,21 @@ async function persistEnvelope(
 	payload.version ??= WORKFLOW_STATE_VERSION;
 	payload.active ??= true;
 	payload.current_phase ??= "interviewing";
-	await writeGuardedWorkflowEnvelopeAtomic(statePath, payload, {
+	const expectedRevision = existingStateRevision(envelope);
+	const writeResult = await writeGuardedWorkflowEnvelopeAtomic(statePath, payload, {
 		cwd,
 		policy: "source",
-		expectedRevision: existingStateRevision(envelope),
+		expectedRevision,
 		receipt: { cwd, skill: "deep-interview", owner: "gjc-runtime", command, sessionId, nowIso: now },
 		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "deep-interview", sessionId },
 	});
+	// Reflect the freshly written revision back onto the in-memory envelope so a
+	// follow-up HUD sync derives its `sourceRevision` from the persisted revision
+	// (not the stale pre-write value), otherwise the active-state writer treats the
+	// newer HUD as stale and skips it (e.g. dropping the ambiguity chip after scoring).
+	if (writeResult.written && typeof expectedRevision === "number") {
+		(envelope as Record<string, unknown>).state_revision = expectedRevision + 1;
+	}
 	await writeSessionActivityMarker(cwd, sessionId, { writer: "deep-interview-recorder", path: statePath });
 }
 
@@ -354,8 +362,8 @@ async function syncRecorderHud(
 		phase,
 		sessionId,
 		source: "gjc-runtime-deep-interview-recorder",
-		hud: deriveDeepInterviewHud(envelope as Record<string, unknown>, { phase }),
-		sourceRevision: existingStateRevision(envelope),
+		hud: deriveDeepInterviewHud(normalizeDeepInterviewEnvelope(envelope) as Record<string, unknown>, { phase }),
+		sourceRevision: (existingStateRevision(envelope) ?? 0) + 1,
 	});
 }
 

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

@@ -1,6 +1,7 @@
 import { Buffer } from "node:buffer";
 import * as path from "node:path";
 import { safeStderrWrite } from "@gajae-code/utils";
+import { VERSION } from "@gajae-code/utils/dirs";
 import type { Args } from "../cli/args";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import { GJC_COORDINATOR_SESSION_ID_ENV, GJC_COORDINATOR_SESSION_STATE_FILE_ENV } from "./session-state-sidecar";
@@ -16,7 +17,7 @@ import {
 	type GjcTmuxProfileCommand,
 	resolveGjcTmuxCommand,
 } from "./tmux-common";
-import { findGjcTmuxSessionByName, findGjcTmuxSessionByScope } from "./tmux-sessions";
+import { findGjcTmuxSessionByName, findGjcTmuxSessionByScope, type GjcTmuxSessionStatus } from "./tmux-sessions";
 
 export {
 	buildGjcTmuxProfileCommands,
@@ -88,6 +89,9 @@ export interface TmuxLaunchPlan {
 function explicitTmuxSessionName(env: NodeJS.ProcessEnv): string | undefined {
 	return env.GJC_TMUX_SESSION?.trim() || undefined;
 }
+function hasCurrentGjcVersion(session: GjcTmuxSessionStatus | undefined): boolean {
+	return session?.version === VERSION;
+}
 
 function findExistingSessionForLaunch(context: {
 	env: NodeJS.ProcessEnv;
@@ -96,7 +100,8 @@ function findExistingSessionForLaunch(context: {
 }): string | undefined {
 	const explicit = explicitTmuxSessionName(context.env);
 	if (explicit) return findGjcTmuxSessionByName(explicit, context.env)?.name;
-	return findGjcTmuxSessionByScope(context.project, context.branch, context.env)?.name;
+	const scoped = findGjcTmuxSessionByScope(context.project, context.branch, context.env);
+	return hasCurrentGjcVersion(scoped) ? scoped?.name : undefined;
 }
 
 export interface GjcTmuxProfileResult {
@@ -116,6 +121,7 @@ export interface GjcTmuxProfileContext {
 	project?: string | null;
 	sessionId?: string | null;
 	sessionStateFile?: string | null;
+	version?: string | null;
 }
 
 interface CommandResolutionContext {
@@ -195,6 +201,7 @@ export function applyGjcTmuxProfile(context: GjcTmuxProfileContext): GjcTmuxProf
 		project: context.project ?? null,
 		sessionId: context.sessionId ?? env[GJC_COORDINATOR_SESSION_ID_ENV] ?? null,
 		sessionStateFile: context.sessionStateFile ?? env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV] ?? null,
+		version: context.version ?? null,
 	});
 	if (commands.length === 0) return { skipped: true, commands: [], failures: [] };
 	const spawnSync = context.spawnSync ?? defaultSpawnSync;
@@ -457,6 +464,7 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			project: plan.project,
 			sessionId: plan.sessionId ?? null,
 			sessionStateFile: plan.sessionStateFile ?? null,
+			version: VERSION,
 		});
 		const ownershipFailure = profile.failures.find(item => item.command.args.includes("@gjc-profile"));
 		if (ownershipFailure) {

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

@@ -818,7 +818,7 @@ async function writeJsonAtomic(
 		toPhase?: string;
 		owner?: WorkflowStateMutationOwner;
 	},
-): Promise<{ warning?: string; stamped: Record<string, unknown> }> {
+): Promise<{ warning?: string; stamped: Record<string, unknown>; revision: number }> {
 	const warning = options?.skill
 		? await warnAndAuditOutOfBandIfNeeded(cwd, options.sessionId, filePath, options.skill, {
 				mutationId: options.mutationId,
@@ -832,7 +832,7 @@ async function writeJsonAtomic(
 	// writer lock; do not enforce an optimistic `expectedRevision` here (tamper
 	// detection is handled by warnAndAuditOutOfBandIfNeeded above, and a forced
 	// write must succeed over corrupt/missing prior state).
-	await writeGuardedWorkflowEnvelopeAtomic(filePath, value, {
+	const writeResult = await writeGuardedWorkflowEnvelopeAtomic(filePath, value, {
 		cwd,
 		policy: "source",
 		audit: {
@@ -847,7 +847,11 @@ async function writeJsonAtomic(
 			forced: options?.force ?? false,
 		},
 	});
-	return { warning, stamped: (await readJsonFile(filePath)) ?? {} };
+	// `writeResult.revision` is computed inside the writer lock, so it is the revision this
+	// write actually owns. Prefer it over a post-lock file re-read, which a concurrent writer
+	// could have advanced before the read — that race could otherwise let this payload be
+	// published with another writer's newer revision.
+	return { warning, stamped: (await readJsonFile(filePath)) ?? {}, revision: writeResult.revision };
 }
 
 function parseFieldsFlag(args: readonly string[]): StateProjectionField[] | undefined {
@@ -1399,7 +1403,11 @@ async function handleWrite(
 	const validation = validateWorkflowStateEnvelope(mode, merged);
 	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
 
-	const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, merged, "write", {
+	const {
+		warning: outOfBandWarning,
+		stamped,
+		revision: stampedRevision,
+	} = await writeJsonAtomic(cwd, filePath, merged, "write", {
 		sessionId,
 		skill: mode,
 		mutationId,
@@ -1411,6 +1419,12 @@ async function handleWrite(
 
 	const phase = typeof merged.current_phase === "string" ? merged.current_phase : undefined;
 	const active = merged.active !== false;
+	// Reflect the lock-owned mode-state revision onto the in-memory payload so the active-state/HUD
+	// sync derives a `sourceRevision` from the revision this write actually owns (computed inside the
+	// writer lock), not the stale pre-write value or a post-lock re-read a concurrent writer could
+	// have advanced; otherwise the active-state writer stale-skips the update and the mirror keeps the
+	// prior phase (e.g. staying "interviewing" after a "handoff" write).
+	merged.state_revision = stampedRevision;
 	await syncWorkflowSkillState({ cwd, mode, sessionId, threadId, turnId, active, phase, payload: merged, receipt });
 	await touchStateActivityMarker(cwd, sessionId, filePath);
 

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

@@ -99,8 +99,8 @@ export interface GuardedStateWriterOptions extends StateWriterOptions {
 }
 
 export type GuardedWriteResult =
-	| { path: string; written: true }
-	| { path: string; written: false; reason: "stale-skip" };
+	| { path: string; written: true; revision: number }
+	| { path: string; written: false; reason: "stale-skip"; revision: number };
 
 export interface StateWriterOptions {
 	cwd?: string;
@@ -511,13 +511,13 @@ async function writeGuardedResolvedJsonAtomic(
 				const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
 				await atomicWrite(filePath, jsonText(next));
 				await maybeAudit(filePath, options);
-				return { path: filePath, written: true };
+				return { path: filePath, written: true, revision: currentRevision + 1 };
 			}
 
 			const incomingSourceRevision =
 				options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
 			if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
-				return { path: filePath, written: false, reason: "stale-skip" };
+				return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
 			}
 			const next = stampStateRevision(
 				withWorkflowReceipt(value, buildReceipt(options)),
@@ -526,7 +526,7 @@ async function writeGuardedResolvedJsonAtomic(
 			);
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
-			return { path: filePath, written: true };
+			return { path: filePath, written: true, revision: currentRevision + 1 };
 		},
 		options.lock,
 	);
@@ -574,13 +574,13 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 				}
 				await atomicWrite(filePath, jsonText(next));
 				await maybeAudit(filePath, options);
-				return { path: filePath, written: true };
+				return { path: filePath, written: true, revision: currentRevision + 1 };
 			}
 
 			const incomingSourceRevision =
 				options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
 			if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
-				return { path: filePath, written: false, reason: "stale-skip" };
+				return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
 			}
 			const next = stampWorkflowEnvelopeRevisionAndChecksum(
 				value,
@@ -599,7 +599,7 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 			}
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
-			return { path: filePath, written: true };
+			return { path: filePath, written: true, revision: currentRevision + 1 };
 		},
 		options.lock,
 	);

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

@@ -10,6 +10,7 @@ export const GJC_TMUX_BRANCH_SLUG_OPTION = "@gjc-branch-slug";
 export const GJC_TMUX_PROJECT_OPTION = "@gjc-project";
 export const GJC_TMUX_SESSION_ID_OPTION = "@gjc-session-id";
 export const GJC_TMUX_SESSION_STATE_FILE_OPTION = "@gjc-session-state-file";
+export const GJC_TMUX_VERSION_OPTION = "@gjc-version";
 
 export interface GjcTmuxProfileCommand {
 	description: string;
@@ -101,6 +102,7 @@ export function buildGjcTmuxRequiredProfileCommands(
 		project?: string | null;
 		sessionId?: string | null;
 		sessionStateFile?: string | null;
+		version?: string | null;
 	} = {},
 ): GjcTmuxProfileCommand[] {
 	const commands: GjcTmuxProfileCommand[] = [
@@ -134,6 +136,11 @@ export function buildGjcTmuxRequiredProfileCommands(
 			description: "record GJC session state marker",
 			args: ["set-option", "-t", target, GJC_TMUX_SESSION_STATE_FILE_OPTION, metadata.sessionStateFile],
 		});
+	if (metadata.version)
+		commands.push({
+			description: "record GJC version identity",
+			args: ["set-option", "-t", target, GJC_TMUX_VERSION_OPTION, metadata.version],
+		});
 	return commands;
 }
 
@@ -146,6 +153,7 @@ export function buildGjcTmuxProfileCommands(
 		project?: string | null;
 		sessionId?: string | null;
 		sessionStateFile?: string | null;
+		version?: string | null;
 	} = {},
 ): GjcTmuxProfileCommand[] {
 	const commands = buildGjcTmuxRequiredProfileCommands(target, metadata);

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

@@ -10,6 +10,7 @@ import {
 	GJC_TMUX_PROJECT_OPTION,
 	GJC_TMUX_SESSION_ID_OPTION,
 	GJC_TMUX_SESSION_STATE_FILE_OPTION,
+	GJC_TMUX_VERSION_OPTION,
 	normalizeTmuxCreatedAt,
 	resolveGjcTmuxCommand,
 } from "./tmux-common";
@@ -26,6 +27,7 @@ export interface GjcTmuxSessionStatus {
 	project?: string;
 	sessionId?: string;
 	sessionStateFile?: string;
+	version?: string;
 	panePids: number[];
 	profile?: string;
 }
@@ -37,6 +39,7 @@ export interface GjcTmuxSessionTagsForGc {
 	branchSlug?: string;
 	sessionId?: string;
 	sessionStateFile?: string;
+	version?: string;
 	createdAt?: string;
 	attached?: boolean;
 	panePids?: number[];
@@ -86,6 +89,7 @@ function parseSessionLine(line: string): GjcTmuxSessionStatus | null {
 		project = "",
 		sessionId = "",
 		sessionStateFile = "",
+		version = "",
 	] = line.split("\t");
 	if (!name) return null;
 	return {
@@ -105,6 +109,7 @@ function parseSessionLine(line: string): GjcTmuxSessionStatus | null {
 		profile: profile || undefined,
 		sessionId: sessionId || undefined,
 		sessionStateFile: sessionStateFile || undefined,
+		version: version || undefined,
 	};
 }
 
@@ -131,7 +136,7 @@ function runListSessions(format: string, env: NodeJS.ProcessEnv = process.env):
 
 function listSessionLines(env: NodeJS.ProcessEnv = process.env): string[] {
 	return runListSessions(
-		`#{session_name}\t#{session_windows}\t#{session_attached}\t#{session_created}\t#{${GJC_TMUX_PROFILE_OPTION}}\t#{session_key_table}\t#{session_panes}\t#{pane_pid}\t#{${GJC_TMUX_BRANCH_OPTION}}\t#{${GJC_TMUX_BRANCH_SLUG_OPTION}}\t#{${GJC_TMUX_PROJECT_OPTION}}\t#{${GJC_TMUX_SESSION_ID_OPTION}}\t#{${GJC_TMUX_SESSION_STATE_FILE_OPTION}}`,
+		`#{session_name}\t#{session_windows}\t#{session_attached}\t#{session_created}\t#{${GJC_TMUX_PROFILE_OPTION}}\t#{session_key_table}\t#{session_panes}\t#{pane_pid}\t#{${GJC_TMUX_BRANCH_OPTION}}\t#{${GJC_TMUX_BRANCH_SLUG_OPTION}}\t#{${GJC_TMUX_PROJECT_OPTION}}\t#{${GJC_TMUX_SESSION_ID_OPTION}}\t#{${GJC_TMUX_SESSION_STATE_FILE_OPTION}}\t#{${GJC_TMUX_VERSION_OPTION}}`,
 		env,
 	);
 }
@@ -265,6 +270,7 @@ function hydrateSessionFromExactOptions(session: GjcTmuxSessionStatus, env: Node
 		sessionId: session.sessionId ?? readExactOptionForGc(session.name, GJC_TMUX_SESSION_ID_OPTION, env),
 		sessionStateFile:
 			session.sessionStateFile ?? readExactOptionForGc(session.name, GJC_TMUX_SESSION_STATE_FILE_OPTION, env),
+		version: session.version ?? readExactOptionForGc(session.name, GJC_TMUX_VERSION_OPTION, env),
 	};
 }
 
@@ -281,6 +287,7 @@ export function readTmuxSessionTagsForGc(
 		branchSlug: readExactOptionForGc(sessionName, GJC_TMUX_BRANCH_SLUG_OPTION, env),
 		sessionId: readExactOptionForGc(sessionName, GJC_TMUX_SESSION_ID_OPTION, env),
 		sessionStateFile: readExactOptionForGc(sessionName, GJC_TMUX_SESSION_STATE_FILE_OPTION, env),
+		version: readExactOptionForGc(sessionName, GJC_TMUX_VERSION_OPTION, env),
 		createdAt: session?.createdAt,
 		attached: session?.attached,
 		panePids: session?.panePids,

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

@@ -288,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 {
@@ -479,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);
@@ -496,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"),
+	);
+}

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

@@ -898,32 +898,29 @@ function categorizeComputerChangePath(value: string): UltragoalChangeCategory {
 	return "other";
 }
 
-function isComputerChangePath(row: UltragoalChangeSetPath): boolean {
+function isComputerControlSurfaceCategory(category: UltragoalChangeCategory): boolean {
 	return (
-		categorizeComputerChangePath(row.path) !== "other" ||
-		(row.oldPath ? categorizeComputerChangePath(row.oldPath) !== "other" : false)
+		category === "code" || category === "generated-binding" || category === "tool" || category === "settings-registry"
 	);
 }
 
-function isDocsOnlyStaticComputerChangeSet(changeSet: UltragoalChangeSet | undefined): boolean {
-	if (!changeSet || changeSet.paths.length === 0) return false;
-	return changeSet.paths.every(row => {
-		const category = row.category ?? categorizeComputerChangePath(row.path);
-		const oldCategory = row.oldPath ? categorizeComputerChangePath(row.oldPath) : category;
-		return category === "docs-static" && oldCategory === "docs-static";
-	});
+function isComputerControlSurfaceChangePath(row: UltragoalChangeSetPath): boolean {
+	const category = row.category ?? categorizeComputerChangePath(row.path);
+	const oldCategory = row.oldPath ? categorizeComputerChangePath(row.oldPath) : category;
+	return isComputerControlSurfaceCategory(category) || isComputerControlSurfaceCategory(oldCategory);
 }
 
 function trustedChangeSetRequiresComputerSuite(changeSet: UltragoalChangeSet | undefined): boolean {
 	if (!changeSet?.trusted) return false;
-	if (isDocsOnlyStaticComputerChangeSet(changeSet)) return false;
-	return changeSet.paths.some(isComputerChangePath);
+	return changeSet.paths.some(isComputerControlSurfaceChangePath);
 }
 
 function requiresComputerRedTeamSuite(executorQa: JsonObject, changeSet: UltragoalChangeSet | undefined): boolean {
 	if (trustedChangeSetRequiresComputerSuite(changeSet)) return true;
 	const declaredPaths = Array.isArray(executorQa.changedPaths) ? executorQa.changedPaths : [];
-	return declaredPaths.some(value => typeof value === "string" && categorizeComputerChangePath(value) !== "other");
+	return declaredPaths.some(
+		value => typeof value === "string" && isComputerControlSurfaceCategory(categorizeComputerChangePath(value)),
+	);
 }
 
 function normalizeAdversarialCaseId(value: string): string {
@@ -2853,6 +2850,33 @@ export async function recordUltragoalReviewBlockers(input: {
 	return plan;
 }
 
+export type UltragoalBlockerClassification = "human_blocked" | "resolvable";
+
+/**
+ * Record an audited blocker triage classification in the durable ledger. A
+ * `human_blocked` classification is the only thing that authorizes
+ * `goal({"op":"pause"})` while an Ultragoal run is active; `resolvable` is an
+ * audit note and never unblocks pause.
+ */
+export async function recordUltragoalBlockerClassification(input: {
+	cwd: string;
+	classification: UltragoalBlockerClassification;
+	evidence: string;
+	goalId?: string;
+}): Promise<UltragoalLedgerEvent> {
+	const evidence = input.evidence.trim();
+	if (!evidence) throw new Error("classify-blocker --evidence is required");
+	if (input.classification !== "human_blocked" && input.classification !== "resolvable") {
+		throw new Error('classify-blocker --classification must be "human_blocked" or "resolvable"');
+	}
+	return appendLedger(input.cwd, {
+		event: "blocker_classified",
+		classification: input.classification,
+		...(input.goalId?.trim() ? { goalId: input.goalId.trim() } : {}),
+		evidence,
+	});
+}
+
 type UltragoalReviewMode = "review-only" | "review-start";
 type UltragoalReviewContractStrength = "strong" | "thin-derived";
 
@@ -2920,11 +2944,33 @@ async function spawnText(
 	}
 }
 
-async function resolveGitBase(cwd: string, branch?: string): Promise<string> {
-	const candidates = branch ? [branch] : ["origin/main", "origin/master", "main", "master"];
-	for (const candidate of candidates) {
-		const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
-		if (exists.ok) return candidate;
+export async function resolveGitBase(cwd: string, branch?: string): Promise<string> {
+	if (branch) {
+		const exists = await spawnText(["git", "rev-parse", "--verify", branch], { cwd, timeoutMs: 3000 });
+		if (exists.ok) return branch;
+	} else {
+		// Prefer the NEAREST integration base (the branch this work actually forks
+		// from) rather than always `main`. A branch opened against `dev` must be
+		// scoped to `dev`; using a stale `main` sweeps in unrelated trunk history
+		// and mis-attributes other people's changes to this story (e.g. falsely
+		// tripping change-scoped gates). Among existing candidates, pick the one
+		// whose merge-base with HEAD is closest to HEAD (fewest commits ahead).
+		const candidates = ["origin/dev", "dev", "origin/main", "origin/master", "main", "master"];
+		let best: { ref: string; ahead: number } | undefined;
+		for (const candidate of candidates) {
+			const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
+			if (!exists.ok) continue;
+			const mergeBase = await spawnText(["git", "merge-base", "HEAD", candidate], { cwd, timeoutMs: 3000 });
+			if (!mergeBase.ok || !mergeBase.stdout.trim()) continue;
+			const count = await spawnText(["git", "rev-list", "--count", `${mergeBase.stdout.trim()}..HEAD`], {
+				cwd,
+				timeoutMs: 3000,
+			});
+			const ahead = Number.parseInt(count.stdout.trim(), 10);
+			if (!Number.isFinite(ahead)) continue;
+			if (!best || ahead < best.ahead) best = { ref: candidate, ahead };
+		}
+		if (best) return best.ref;
 	}
 	const mergeBase = await spawnText(["git", "merge-base", "HEAD", "origin/main"], { cwd, timeoutMs: 3000 });
 	if (mergeBase.ok && mergeBase.stdout.trim()) return mergeBase.stdout.trim();
@@ -3245,6 +3291,7 @@ const FLAGS_WITH_VALUES = new Set([
 	"--rationale",
 	"--replacements-json",
 	"--order-json",
+	"--classification",
 ]);
 
 function isHelpArg(arg: string): boolean {
@@ -3319,6 +3366,25 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 			"",
 		].join("\n");
 	}
+	if (subject === "classify-blocker") {
+		return [
+			"Run native GJC Ultragoal workflow commands",
+			"",
+			"USAGE",
+			"  $ gjc ultragoal classify-blocker --classification <human_blocked|resolvable> --evidence <text> [FLAGS]",
+			"",
+			"FLAGS",
+			"      --classification=<value>     Required. human_blocked authorizes pause only as the latest ledger event; resolvable never authorizes pause",
+			"      --evidence=<value>           Required. Specific blocker evidence; must name the human-only dependency for human_blocked",
+			"      --goal-id=<value>            Optional durable .gjc/ultragoal goal id, e.g. G001",
+			"      --json                       Output a machine-readable receipt",
+			"",
+			"EXAMPLES",
+			'  $ gjc ultragoal classify-blocker --classification resolvable --evidence "failing test can be fixed autonomously"',
+			'  $ gjc ultragoal classify-blocker --classification human_blocked --evidence "user must provide production API credentials" --goal-id G001',
+			"",
+		].join("\n");
+	}
 	return [
 		"Run native GJC Ultragoal workflow commands",
 		"",
@@ -3333,8 +3399,9 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 		"  review",
 		"  steer",
 		"  record-review-blockers",
+		"  classify-blocker",
 		"",
-		"Run `gjc ultragoal checkpoint --help` or `gjc ultragoal review --help` for command-specific requirements.",
+		"Run `gjc ultragoal checkpoint --help`, `gjc ultragoal review --help`, or `gjc ultragoal classify-blocker --help` for command-specific requirements.",
 		"",
 	].join("\n");
 }
@@ -3653,6 +3720,24 @@ async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<Ul
 						: "Recorded review blockers.\n",
 				};
 			}
+			case "classify-blocker": {
+				const event = await recordUltragoalBlockerClassification({
+					cwd,
+					classification: (flagValue(args, "--classification") ?? "") as UltragoalBlockerClassification,
+					evidence: flagValue(args, "--evidence") ?? "",
+					goalId: flagValue(args, "--goal-id"),
+				});
+				return {
+					status: 0,
+					stdout: json
+						? renderCliWriteReceipt({
+								ok: true,
+								event: "blocker_classified",
+								classification: event.classification,
+							})
+						: `Recorded blocker classification: ${String(event.classification)}.\n`,
+				};
+			}
 			default:
 				return { status: 1, stderr: `Unknown gjc ultragoal command: ${command}\n` };
 		}
@@ -3670,6 +3755,7 @@ const RECONCILE_COMMANDS = new Set([
 	"steer",
 	"record-review-blockers",
 	"review",
+	"classify-blocker",
 ]);
 
 /**

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

@@ -1443,7 +1443,8 @@
         "appliesToVerbs": [
           "checkpoint",
           "record-review-blockers",
-          "steer"
+          "steer",
+          "classify-blocker"
         ],
         "name": "evidence",
         "required": true,
@@ -1471,6 +1472,25 @@
         "name": "goal-id",
         "type": "string"
       },
+      {
+        "appliesToVerbs": [
+          "classify-blocker"
+        ],
+        "name": "goal-id",
+        "type": "string"
+      },
+      {
+        "appliesToVerbs": [
+          "classify-blocker"
+        ],
+        "enumValues": [
+          "human_blocked",
+          "resolvable"
+        ],
+        "name": "classification",
+        "required": true,
+        "type": "enum"
+      },
       {
         "appliesToVerbs": [
           "steer"
@@ -1570,7 +1590,8 @@
           "review",
           "checkpoint",
           "record-review-blockers",
-          "steer"
+          "steer",
+          "classify-blocker"
         ],
         "name": "json",
         "type": "boolean"
@@ -1651,6 +1672,10 @@
         "name": "steer",
         "surface": "command-positional"
       },
+      {
+        "name": "classify-blocker",
+        "surface": "command-positional"
+      },
       {
         "name": "graph",
         "planned": true,