@sayknow-cli/coding-agent 0.2.6 → 0.3.0

package/src/setup/host-plugin-setup.ts

@@ -0,0 +1,142 @@
+/**
+ * Host plugin setup for `skc setup claude` and `skc setup codex`.
+ *
+ * Renders install guidance and a fail-closed coordinator MCP config preview for
+ * the canonical generated plugin bundle under `plugins/`. This is intentionally
+ * render-only and fail-closed: the workdir allowlist is scoped to the project
+ * root and no mutation class is enabled until the user opts in.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getProjectDir } from "@sayknow-cli/utils";
+
+export type HostPluginKind = "claude" | "codex";
+
+export interface HostPluginSetupFlags {
+	json?: boolean;
+	check?: boolean;
+	root?: string[];
+	repo?: string;
+}
+
+export interface HostPluginSetupResult {
+	ok: true;
+	host: HostPluginKind;
+	mode: "render";
+	gated: boolean;
+	pluginPath: string;
+	manifestPath: string;
+	marketplacePath: string;
+	installGuidance: string[];
+	coordinatorConfigPreview: {
+		command: string;
+		args: string[];
+		env: Record<string, string>;
+	};
+	mutationPolicy: string;
+	notes: string[];
+	check?: { ok: boolean; checked: string[]; missing: string[] };
+}
+
+const NAMESPACE_LABEL = "sayknow-cli-plugin";
+
+function resolveProjectRoot(flags: HostPluginSetupFlags): string {
+	const explicit = flags.root?.find(root => root.trim().length > 0);
+	return explicit ? path.resolve(explicit) : getProjectDir();
+}
+
+function verifyBundleFiles(files: string[]): { ok: boolean; checked: string[]; missing: string[] } {
+	const missing = files.filter(file => !fs.existsSync(file));
+	return { ok: missing.length === 0, checked: files, missing };
+}
+
+export function buildHostPluginSetup(host: HostPluginKind, flags: HostPluginSetupFlags = {}): HostPluginSetupResult {
+	const projectRoot = resolveProjectRoot(flags);
+	const marketplaceRoot = path.join(projectRoot, "plugins");
+	const pluginDir = path.join(marketplaceRoot, "sayknow-cli");
+	const repo = flags.repo && flags.repo.trim().length > 0 ? flags.repo.trim() : NAMESPACE_LABEL;
+
+	// Concrete, fail-closed env: workdir allowlist is the project root, no mutations.
+	const env: Record<string, string> = {
+		SKC_COORDINATOR_MCP_WORKDIR_ROOTS: projectRoot,
+		SKC_COORDINATOR_MCP_REPO: repo,
+		SKC_COORDINATOR_MCP_SESSION_COMMAND: "skc --worktree",
+	};
+
+	if (host === "claude") {
+		const manifestPath = path.join(pluginDir, ".claude-plugin", "plugin.json");
+		const marketplacePath = path.join(marketplaceRoot, ".claude-plugin", "marketplace.json");
+		return {
+			ok: true,
+			host,
+			mode: "render",
+			gated: false,
+			pluginPath: marketplaceRoot,
+			manifestPath,
+			marketplacePath,
+			installGuidance: [
+				`Add the local marketplace: /plugin marketplace add ${marketplaceRoot}`,
+				"Install the plugin: /plugin install sayknow-cli",
+				"Then call skc_delegate_plan / skc_delegate_execute / skc_delegate_team from Claude Code.",
+			],
+			coordinatorConfigPreview: { command: "skc", args: ["mcp-serve", "coordinator"], env },
+			mutationPolicy:
+				"Fail-closed: delegation is read-only until you set SKC_COORDINATOR_MCP_MUTATIONS=sessions and pass allow_mutation:true per call.",
+			notes: [],
+			...(flags.check
+				? { check: verifyBundleFiles([manifestPath, marketplacePath, path.join(pluginDir, ".mcp.json")]) }
+				: {}),
+		};
+	}
+
+	// Codex: verified installable on Codex CLI 0.139.0 via the local marketplace smoke.
+	const manifestPath = path.join(pluginDir, ".codex-plugin", "plugin.json");
+	const marketplacePath = path.join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
+	return {
+		ok: true,
+		host,
+		mode: "render",
+		gated: false,
+		pluginPath: marketplaceRoot,
+		manifestPath,
+		marketplacePath,
+		installGuidance: [
+			`Add the local marketplace: codex plugin marketplace add ${marketplaceRoot}`,
+			"Install the plugin: codex plugin add sayknow-cli@sayknow-cli-local",
+			"Then call skc_delegate_plan / skc_delegate_execute / skc_delegate_team from Codex.",
+		],
+		coordinatorConfigPreview: { command: "skc", args: ["mcp-serve", "coordinator"], env },
+		mutationPolicy:
+			"Fail-closed: delegation is read-only until you set SKC_COORDINATOR_MCP_MUTATIONS=sessions and pass allow_mutation:true per call.",
+		notes: [
+			"Verified on Codex CLI 0.139.0: marketplace add + plugin add install the plugin (enabled) and `codex mcp list` registers skc-coordinator with the fail-closed env.",
+			"The bundled .codex.mcp.json workdir root is host-neutral; `skc setup codex` renders a concrete root, and operators should re-run the local marketplace smoke on their target Codex version.",
+		],
+		...(flags.check
+			? {
+					check: verifyBundleFiles([
+						manifestPath,
+						marketplacePath,
+						path.join(pluginDir, ".codex.mcp.json"),
+						path.join(pluginDir, "skills", "skc-delegation", "SKILL.md"),
+					]),
+				}
+			: {}),
+	};
+}
+
+export function formatHostPluginSetup(result: HostPluginSetupResult): string {
+	const lines: string[] = [];
+	lines.push(`host: ${result.host}${result.gated ? " (gated on versioned smoke)" : ""}`);
+	lines.push(`plugin: ${result.pluginPath}`);
+	lines.push("install:");
+	for (const step of result.installGuidance) lines.push(`  - ${step}`);
+	lines.push(`mcp: ${result.coordinatorConfigPreview.command} ${result.coordinatorConfigPreview.args.join(" ")}`);
+	lines.push(
+		`  SKC_COORDINATOR_MCP_WORKDIR_ROOTS=${result.coordinatorConfigPreview.env.SKC_COORDINATOR_MCP_WORKDIR_ROOTS}`,
+	);
+	lines.push(result.mutationPolicy);
+	for (const note of result.notes) lines.push(`note: ${note}`);
+	return lines.join("\n");
+}

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

@@ -362,8 +362,8 @@ async function syncRecorderHud(
 		phase,
 		sessionId,
 		source: "skc-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/skc-runtime/launch-tmux.ts

@@ -1,6 +1,7 @@
 import { Buffer } from "node:buffer";
 import * as path from "node:path";
 import { safeStderrWrite } from "@sayknow-cli/utils";
+import { VERSION } from "@sayknow-cli/utils/dirs";
 import type { Args } from "../cli/args";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import { SKC_COORDINATOR_SESSION_ID_ENV, SKC_COORDINATOR_SESSION_STATE_FILE_ENV } from "./session-state-sidecar";
@@ -16,7 +17,7 @@ import {
 	SKC_TMUX_SESSION_PREFIX,
 	type SkcTmuxProfileCommand,
 } from "./tmux-common";
-import { findSkcTmuxSessionByName, findSkcTmuxSessionByScope } from "./tmux-sessions";
+import { findSkcTmuxSessionByName, findSkcTmuxSessionByScope, type SkcTmuxSessionStatus } from "./tmux-sessions";
 
 export {
 	buildSkcTmuxProfileCommands,
@@ -88,6 +89,9 @@ export interface TmuxLaunchPlan {
 function explicitTmuxSessionName(env: NodeJS.ProcessEnv): string | undefined {
 	return env.SKC_TMUX_SESSION?.trim() || undefined;
 }
+function hasCurrentSkcVersion(session: SkcTmuxSessionStatus | 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 findSkcTmuxSessionByName(explicit, context.env)?.name;
-	return findSkcTmuxSessionByScope(context.project, context.branch, context.env)?.name;
+	const scoped = findSkcTmuxSessionByScope(context.project, context.branch, context.env);
+	return hasCurrentSkcVersion(scoped) ? scoped?.name : undefined;
 }
 
 export interface SkcTmuxProfileResult {
@@ -116,6 +121,7 @@ export interface SkcTmuxProfileContext {
 	project?: string | null;
 	sessionId?: string | null;
 	sessionStateFile?: string | null;
+	version?: string | null;
 }
 
 interface CommandResolutionContext {
@@ -195,6 +201,7 @@ export function applySkcTmuxProfile(context: SkcTmuxProfileContext): SkcTmuxProf
 		project: context.project ?? null,
 		sessionId: context.sessionId ?? env[SKC_COORDINATOR_SESSION_ID_ENV] ?? null,
 		sessionStateFile: context.sessionStateFile ?? env[SKC_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("@skc-profile"));
 		if (ownershipFailure) {

package/src/skc-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,12 +1419,12 @@ async function handleWrite(
 
 	const phase = typeof merged.current_phase === "string" ? merged.current_phase : undefined;
 	const active = merged.active !== false;
-	// Reflect the freshly stamped mode-state revision onto the in-memory payload so the
-	// active-state/HUD sync derives a `sourceRevision` from the persisted revision, not the
-	// stale pre-write value; otherwise the active-state writer stale-skips the update and the
-	// mirror keeps the prior phase (e.g. staying "interviewing" after a "handoff" write).
-	const stampedRevision = existingStateRevision(stamped);
-	if (typeof stampedRevision === "number") merged.state_revision = stampedRevision;
+	// 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/skc-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/skc-runtime/tmux-common.ts

@@ -10,6 +10,7 @@ export const SKC_TMUX_BRANCH_SLUG_OPTION = "@skc-branch-slug";
 export const SKC_TMUX_PROJECT_OPTION = "@skc-project";
 export const SKC_TMUX_SESSION_ID_OPTION = "@skc-session-id";
 export const SKC_TMUX_SESSION_STATE_FILE_OPTION = "@skc-session-state-file";
+export const SKC_TMUX_VERSION_OPTION = "@skc-version";
 
 export interface SkcTmuxProfileCommand {
 	description: string;
@@ -101,6 +102,7 @@ export function buildSkcTmuxRequiredProfileCommands(
 		project?: string | null;
 		sessionId?: string | null;
 		sessionStateFile?: string | null;
+		version?: string | null;
 	} = {},
 ): SkcTmuxProfileCommand[] {
 	const commands: SkcTmuxProfileCommand[] = [
@@ -134,6 +136,11 @@ export function buildSkcTmuxRequiredProfileCommands(
 			description: "record SKC session state marker",
 			args: ["set-option", "-t", target, SKC_TMUX_SESSION_STATE_FILE_OPTION, metadata.sessionStateFile],
 		});
+	if (metadata.version)
+		commands.push({
+			description: "record SKC version identity",
+			args: ["set-option", "-t", target, SKC_TMUX_VERSION_OPTION, metadata.version],
+		});
 	return commands;
 }
 
@@ -146,6 +153,7 @@ export function buildSkcTmuxProfileCommands(
 		project?: string | null;
 		sessionId?: string | null;
 		sessionStateFile?: string | null;
+		version?: string | null;
 	} = {},
 ): SkcTmuxProfileCommand[] {
 	const commands = buildSkcTmuxRequiredProfileCommands(target, metadata);

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

@@ -12,6 +12,7 @@ import {
 	SKC_TMUX_PROJECT_OPTION,
 	SKC_TMUX_SESSION_ID_OPTION,
 	SKC_TMUX_SESSION_STATE_FILE_OPTION,
+	SKC_TMUX_VERSION_OPTION,
 } from "./tmux-common";
 
 export interface SkcTmuxSessionStatus {
@@ -26,6 +27,7 @@ export interface SkcTmuxSessionStatus {
 	project?: string;
 	sessionId?: string;
 	sessionStateFile?: string;
+	version?: string;
 	panePids: number[];
 	profile?: string;
 }
@@ -37,6 +39,7 @@ export interface SkcTmuxSessionTagsForGc {
 	branchSlug?: string;
 	sessionId?: string;
 	sessionStateFile?: string;
+	version?: string;
 	createdAt?: string;
 	attached?: boolean;
 	panePids?: number[];
@@ -86,6 +89,7 @@ function parseSessionLine(line: string): SkcTmuxSessionStatus | null {
 		project = "",
 		sessionId = "",
 		sessionStateFile = "",
+		version = "",
 	] = line.split("\t");
 	if (!name) return null;
 	return {
@@ -105,6 +109,7 @@ function parseSessionLine(line: string): SkcTmuxSessionStatus | 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#{${SKC_TMUX_PROFILE_OPTION}}\t#{session_key_table}\t#{session_panes}\t#{pane_pid}\t#{${SKC_TMUX_BRANCH_OPTION}}\t#{${SKC_TMUX_BRANCH_SLUG_OPTION}}\t#{${SKC_TMUX_PROJECT_OPTION}}\t#{${SKC_TMUX_SESSION_ID_OPTION}}\t#{${SKC_TMUX_SESSION_STATE_FILE_OPTION}}`,
+		`#{session_name}\t#{session_windows}\t#{session_attached}\t#{session_created}\t#{${SKC_TMUX_PROFILE_OPTION}}\t#{session_key_table}\t#{session_panes}\t#{pane_pid}\t#{${SKC_TMUX_BRANCH_OPTION}}\t#{${SKC_TMUX_BRANCH_SLUG_OPTION}}\t#{${SKC_TMUX_PROJECT_OPTION}}\t#{${SKC_TMUX_SESSION_ID_OPTION}}\t#{${SKC_TMUX_SESSION_STATE_FILE_OPTION}}\t#{${SKC_TMUX_VERSION_OPTION}}`,
 		env,
 	);
 }
@@ -265,6 +270,7 @@ function hydrateSessionFromExactOptions(session: SkcTmuxSessionStatus, env: Node
 		sessionId: session.sessionId ?? readExactOptionForGc(session.name, SKC_TMUX_SESSION_ID_OPTION, env),
 		sessionStateFile:
 			session.sessionStateFile ?? readExactOptionForGc(session.name, SKC_TMUX_SESSION_STATE_FILE_OPTION, env),
+		version: session.version ?? readExactOptionForGc(session.name, SKC_TMUX_VERSION_OPTION, env),
 	};
 }
 
@@ -281,6 +287,7 @@ export function readTmuxSessionTagsForGc(
 		branchSlug: readExactOptionForGc(sessionName, SKC_TMUX_BRANCH_SLUG_OPTION, env),
 		sessionId: readExactOptionForGc(sessionName, SKC_TMUX_SESSION_ID_OPTION, env),
 		sessionStateFile: readExactOptionForGc(sessionName, SKC_TMUX_SESSION_STATE_FILE_OPTION, env),
+		version: readExactOptionForGc(sessionName, SKC_TMUX_VERSION_OPTION, env),
 		createdAt: session?.createdAt,
 		attached: session?.attached,
 		panePids: session?.panePids,

package/src/skc-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, `skc ultragoal steer --kind add_subgoal`, delegate an executor, or `skc ultragoal record-review-blockers`.",
+			'If the blocker is genuinely human-only, record `skc ultragoal classify-blocker --classification human_blocked --evidence "<human-only dependency>"` immediately before pausing.',
+		].join("\n"),
+	);
+}