@sayknow-cli/coding-agent 0.3.1 → 0.3.4

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

@@ -1,3 +1,6 @@
+import type { ResolvedTmuxBinary } from "./psmux-detect";
+import { resolveSkcTmuxBinary } from "./psmux-detect";
+
 export const SKC_DEFAULT_TMUX_SESSION = "sayknow_cli";
 export const SKC_TMUX_SESSION_PREFIX = `${SKC_DEFAULT_TMUX_SESSION}_`;
 export const SKC_TMUX_COMMAND_ENV = "SKC_TMUX_COMMAND";
@@ -11,6 +14,7 @@ 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 const SKC_PSMUX_PROFILE_FORCE_ENV = "SKC_PSMUX_PROFILE_FORCE";
 
 export interface SkcTmuxProfileCommand {
 	description: string;
@@ -31,10 +35,33 @@ export function envDisabled(value: string | undefined): boolean {
 	return normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no";
 }
 
-export function resolveSkcTmuxCommand(env: NodeJS.ProcessEnv = process.env): string {
-	return env[SKC_TMUX_COMMAND_ENV]?.trim() || env.SKC_TEAM_TMUX_COMMAND?.trim() || "tmux";
+/**
+ * Resolve the tmux (or tmux-compatible multiplexer) command SKC should invoke.
+ *
+ * This is the shared entry point used by every SKC code path that needs to talk
+ * to a multiplexer: `skc --tmux` planning, `skc session ...`, `skc team ...`,
+ * the lifecycle controller, and the harness resident owner. Routing all of
+ * them through the same resolver means a single `SKC_TMUX_COMMAND` override or
+ * a single Windows psmux / pmux detection wins for the whole process — the
+ * failure mode where `skc --tmux` creates a psmux-backed session and then
+ * `skc session status` fails because it queries literal `tmux` is closed off.
+ *
+ * Explicit `SKC_TMUX_COMMAND` / `SKC_TEAM_TMUX_COMMAND` overrides are honored on
+ * every platform. On native Windows without an override the resolver walks
+ * `psmux`, then `pmux`, then `tmux` and uses the first binary present on PATH.
+ * On POSIX the resolver returns `tmux` (the historical default) and only
+ * falls through to the platform-aware walker if the caller opts in.
+ */
+export function resolveSkcTmuxCommand(
+	env: NodeJS.ProcessEnv = process.env,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	return resolveSkcTmuxBinary({ env, platform }).command;
 }
 
+export type { PsmuxProbe, ResolvedTmuxBinary, ResolveSkcTmuxBinaryOptions } from "./psmux-detect";
+export { clearPsmuxDetectionCache, detectPsmux, probePsmux, resolveSkcTmuxBinary } from "./psmux-detect";
+
 /**
  * Build the exact-session target for tmux *option* commands
  * (`show-options` / `set-option`) and `display-message -t`.
@@ -45,7 +72,17 @@ export function resolveSkcTmuxCommand(env: NodeJS.ProcessEnv = process.env): str
  * keeps the exact-session match while giving tmux the window-qualified target
  * those commands require. See sayknow-cli#580.
  */
-export function buildSkcTmuxExactOptionTarget(sessionName: string): string {
+export function buildSkcTmuxExactOptionTarget(
+	sessionName: string,
+	opts: { env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform; binary?: ResolvedTmuxBinary } = {},
+): string {
+	const binary = opts.binary ?? resolveSkcTmuxBinary({ env: opts.env, platform: opts.platform });
+	// psmux 3.3.0 rejects the tmux `=NAME` exact-session prefix for option
+	// commands ("no server running on session '=NAME'"); bare `NAME` and
+	// window-qualified `NAME:` both work. tmux 3.6a needs the
+	// window-qualified `=NAME:` to resolve the session for option
+	// commands (sayknow-cli#580).
+	if (binary.isPsmux) return sessionName;
 	return `=${sessionName}:`;
 }
 
@@ -55,7 +92,9 @@ export function buildSkcTmuxUntaggedSessionHint(tmuxCommand: string): string {
 	return (
 		`the active multiplexer "${tmuxCommand}" lists this session but did not return SKC's ${SKC_TMUX_PROFILE_OPTION} ownership tag; ` +
 		"SKC-managed sessions and `skc team` require a tmux provider that round-trips tmux user options. " +
-		"Alternative multiplexers such as psmux on Windows do not persist user options yet, so the Windows-native psmux path is not fully supported; " +
+		"For psmux on Windows, cwd/start-directory flags such as `-c` do not isolate the server namespace; psmux uses the tmux-compatible global `-L <namespace>` flag for that. " +
+		"SKC_TMUX_COMMAND and SKC_TEAM_TMUX_COMMAND are binary overrides, not shell command lines, so `psmux -L name` is not a supported value. " +
+		"Alternative multiplexers such as psmux on Windows do not reliably persist user options yet, so the Windows-native psmux path is not fully supported; " +
 		"use real tmux for SKC-managed session and team flows."
 	);
 }
@@ -144,6 +183,16 @@ export function buildSkcTmuxRequiredProfileCommands(
 	return commands;
 }
 
+/**
+ * Keys whose set-option / set-window-option round-trip is unreliable on psmux
+ * 3.3.0. psmux does not support the tmux `set-window-option` command at all
+ * (it reports "unknown command: set-window-option") and silently drops several
+ * `set-option` keys. The list lives here so every code path that tags a tmux
+ * session (skc --tmux planning, skc session create, skc team bootstrap)
+ * applies the same filter.
+ */
+const PSMUX_UNSUPPORTED_PROFILE_KEYS = new Set(["mouse", "set-clipboard", "mode-style"]);
+
 export function buildSkcTmuxProfileCommands(
 	target: string,
 	env: NodeJS.ProcessEnv = process.env,
@@ -155,6 +204,7 @@ export function buildSkcTmuxProfileCommands(
 		sessionStateFile?: string | null;
 		version?: string | null;
 	} = {},
+	opts: { platform?: NodeJS.Platform; tmuxCommand?: string } = {},
 ): SkcTmuxProfileCommand[] {
 	const commands = buildSkcTmuxRequiredProfileCommands(target, metadata);
 	if (envDisabled(env[SKC_TMUX_PROFILE_ENV])) return commands;
@@ -170,6 +220,40 @@ export function buildSkcTmuxProfileCommands(
 			description: "enable tmux mouse scrolling",
 			args: ["set-option", "-t", target, "mouse", "on"],
 		});
+	// psmux does not implement set-window-option and historically drops
+	// mouse / set-clipboard / mode-style. Filter the UX profile commands
+	// centrally so every code path that tags a session (skc --tmux planning,
+	// skc session create, skc team bootstrap) drops the same set. The
+	// SKC_PSMUX_PROFILE_FORCE override lets the operator opt back in when
+	// running on a psmux build that has caught up. The ownership-tag
+	// round-trip (set-option @skc-*) is never filtered, since skc session /
+	// skc team rely on it.
+	// The filter is opt-in: callers that explicitly pass `opts.tmuxCommand`
+	// name a psmux-class multiplexer (psmux / pmux) when they want the UX
+	// profile filtered. Auto-detect on Windows hosts where psmux happens
+	// to be on PATH would silently change the test output for every caller
+	// that does not pin the multiplexer, so we require the caller to opt
+	// in by naming the multiplexer. SKC_PSMUX_PROFILE_FORCE re-enables
+	// the UX profile commands when a psmux build catches up.
+	const tmuxName = (opts.tmuxCommand ?? "").toLowerCase();
+	const isPsmuxClass =
+		tmuxName === "psmux" ||
+		tmuxName === "pmux" ||
+		tmuxName.endsWith("/psmux") ||
+		tmuxName.endsWith("/pmux") ||
+		tmuxName.endsWith("\\psmux") ||
+		tmuxName.endsWith("\\pmux");
+	const dropUx = isPsmuxClass && !envDisabled(env[SKC_PSMUX_PROFILE_FORCE_ENV]);
+	if (dropUx) {
+		return commands.filter(command => {
+			const flag = command.args[0];
+			const key = command.args[command.args.length - 2];
+			return !(
+				PSMUX_UNSUPPORTED_PROFILE_KEYS.has(String(key)) &&
+				(flag === "set-option" || flag === "set-window-option")
+			);
+		});
+	}
 	return commands;
 }
 

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

@@ -1,3 +1,4 @@
+import { resolveSkcTmuxBinary } from "./psmux-detect";
 import {
 	buildSkcTmuxExactOptionTarget,
 	buildSkcTmuxProfileCommands,
@@ -128,10 +129,29 @@ function runListSessions(format: string, env: NodeJS.ProcessEnv = process.env):
 		}
 		throw error;
 	}
-	return output
+	const lines = output
 		.split("\n")
 		.map(line => line.trim())
 		.filter(Boolean);
+	// psmux 3.3.0 silently ignores the tmux `-F` format flag and returns its
+	// default `name: N windows (created ...)` shape. Detect that case and
+	// synthesize a tab-separated row so downstream parseSessionLine /
+	// hydrateSessionFromExactOptions can recover the @skc-* ownership tags
+	// via follow-up show-options calls. Without this fallback skc session
+	// list / status return an empty list on psmux even when sessions exist.
+	if (lines.length > 0 && !lines[0].includes("\t")) {
+		const binary = resolveSkcTmuxBinary({ env });
+		if (binary.isPsmux) {
+			return lines.map(line => {
+				const match = line.match(/^([^:]+):\s*(\d+)\s+windows?\s+\(created\s+([^)]+)\)/);
+				if (!match) return line;
+				const [, name, windows, created] = match;
+				const createdEpoch = String(Math.floor(new Date(`${created} UTC`).getTime() / 1000) || 0);
+				return [name, windows, "0", createdEpoch, "", "", "0", "", "", "", "", "", "", ""].join("\t");
+			});
+		}
+	}
+	return lines;
 }
 
 function listSessionLines(env: NodeJS.ProcessEnv = process.env): string[] {
@@ -221,7 +241,13 @@ export function statusSkcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv
 export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcTmuxSessionStatus {
 	const tmuxCommand = resolveSkcTmuxCommand(env);
 	const sessionName = buildSkcTmuxSessionName(env);
-	const command = "exec env SKC_TMUX_LAUNCHED=1 skc";
+	// Build a shell-bootstrap command appropriate for the host shell. Psmux on
+	// Windows runs the new-session command through PowerShell, so we use the
+	// $env:VAR = ... assignment form there. POSIX keeps the historical exec
+	// env form so the launched skc inherits SKC_TMUX_LAUNCHED without leaking
+	// into the parent tmux server.
+	const platform = process.platform;
+	const command = platform === "win32" ? "$env:SKC_TMUX_LAUNCHED = '1'; skc" : "exec env SKC_TMUX_LAUNCHED=1 skc";
 	const created = Bun.spawnSync([tmuxCommand, "new-session", "-d", "-s", sessionName, command], {
 		stdout: "pipe",
 		stderr: "pipe",
@@ -229,7 +255,14 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 	});
 	if (created.exitCode !== 0) throw new Error(created.stderr.toString().trim() || "skc_tmux_session_create_failed");
 	try {
-		for (const profileCommand of buildSkcTmuxProfileCommands(sessionName, env)) {
+		// psmux 3.3.0 rejects the tmux `=NAME` exact-session prefix for option
+		// commands, so the target is the bare session name on psmux and the
+		// window-qualified `=NAME:` on tmux. The ownership-tag round-trip
+		// (set-option @skc-*) is preserved on both; only the UX profile commands
+		// (mouse / set-clipboard / mode-style / set-window-option) get filtered
+		// by buildSkcTmuxProfileCommands when the active binary is psmux.
+		const target = buildSkcTmuxExactOptionTarget(sessionName, { env });
+		for (const profileCommand of buildSkcTmuxProfileCommands(target, env, {}, { tmuxCommand })) {
 			runTmux(profileCommand.args, env);
 		}
 	} catch (error) {
@@ -240,18 +273,43 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 }
 
 function readProfileForExactTarget(sessionName: string, env: NodeJS.ProcessEnv): string {
-	return runTmux(
-		["show-options", "-qv", "-t", buildSkcTmuxExactOptionTarget(sessionName), SKC_TMUX_PROFILE_OPTION],
+	const raw = runTmux(
+		["show-options", "-qv", "-t", buildSkcTmuxExactOptionTarget(sessionName, { env }), SKC_TMUX_PROFILE_OPTION],
 		env,
 	).trim();
+	// tmux returns just the value; psmux returns `key value`. Strip the
+	// leading key on psmux so the SKC_TMUX_PROFILE_VALUE equality check
+	// against "1" works the same on both.
+	if (raw && resolveSkcTmuxBinary({ env }).isPsmux) {
+		const tokens = raw.split(/\s+/).filter(Boolean);
+		return tokens[tokens.length - 1] ?? raw;
+	}
+	return raw;
 }
 
 function readExactOptionForGc(sessionName: string, option: string, env: NodeJS.ProcessEnv): string | undefined {
 	try {
-		return (
-			runTmux(["show-options", "-qv", "-t", buildSkcTmuxExactOptionTarget(sessionName), option], env).trim() ||
-			undefined
-		);
+		const raw = runTmux(
+			["show-options", "-qv", "-t", buildSkcTmuxExactOptionTarget(sessionName, { env }), option],
+			env,
+		).trim();
+		if (!raw) return undefined;
+		// tmux returns just the option value (e.g. `1` for @skc-profile).
+		// psmux 3.3.0 returns `key value` (or `key "value with space"` for
+		// @skc-branch etc.). On psmux, parse the last token and strip any
+		// surrounding double quotes so both shapes resolve to the same value.
+		if (resolveSkcTmuxBinary({ env }).isPsmux) {
+			// Prefer the last whitespace-separated token. If the value is
+			// quoted, find the matching close-quote and slice.
+			const lastQuote = raw.lastIndexOf('"');
+			if (lastQuote > 0 && raw[lastQuote - 1] !== "\\") {
+				const firstQuote = raw.lastIndexOf('"', lastQuote - 1);
+				if (firstQuote > 0) return raw.slice(firstQuote + 1, lastQuote);
+			}
+			const tokens = raw.split(/\s+/).filter(Boolean);
+			return tokens[tokens.length - 1];
+		}
+		return raw;
 	} catch {
 		return undefined;
 	}
@@ -306,6 +364,50 @@ export function removeSkcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv
 	return session;
 }
 
+/**
+ * Force-close a SKC-managed tmux session, even if a live pane is attached.
+ *
+ * This is the lifecycle-control counterpart to {@link removeSkcTmuxSession}: it
+ * intentionally does NOT refuse live/attached panes (hard-kill is the contract),
+ * but it keeps every safety check so it can only ever kill a genuinely
+ * SKC-managed session:
+ * - re-reads the exact tmux profile immediately before kill (never a non-SKC
+ *   session, even one that collides by name);
+ * - when `expectedSessionId` is given, requires the `@skc-session-id` tag match;
+ * - when `expectedStateFile` is given, requires the `@skc-session-state-file`
+ *   tag match.
+ *
+ * Returns the prior status (for audit). Throws a tagged error otherwise:
+ * `skc_tmux_session_not_found`, `skc_tmux_session_not_managed`,
+ * `skc_tmux_session_id_mismatch`, or `skc_tmux_session_state_file_mismatch`.
+ */
+export function forceCloseSkcTmuxSession(
+	sessionName: string,
+	env: NodeJS.ProcessEnv = process.env,
+	expectedSessionId?: string,
+	expectedStateFile?: string,
+): SkcTmuxSessionStatus {
+	const session = statusSkcTmuxSession(sessionName, env);
+	if (readProfileForExactTarget(session.name, env) !== SKC_TMUX_PROFILE_VALUE) {
+		throw new Error(`skc_tmux_session_not_managed:${sessionName}`);
+	}
+	if (expectedSessionId !== undefined) {
+		const actual = readExactOptionForGc(session.name, SKC_TMUX_SESSION_ID_OPTION, env);
+		if (actual !== expectedSessionId) {
+			throw new Error(`skc_tmux_session_id_mismatch:${sessionName}`);
+		}
+	}
+	if (expectedStateFile !== undefined) {
+		const actual = readExactOptionForGc(session.name, SKC_TMUX_SESSION_STATE_FILE_OPTION, env);
+		if (actual !== expectedStateFile) {
+			throw new Error(`skc_tmux_session_state_file_mismatch:${sessionName}`);
+		}
+	}
+	// Intentionally NOT refusing live/attached panes — force-close is hard-kill.
+	runTmux(["kill-session", "-t", `=${session.name}`], env);
+	return session;
+}
+
 export function attachSkcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv = process.env): never {
 	const session = statusSkcTmuxSession(sessionName, env);
 	const tmuxCommand = resolveSkcTmuxCommand(env);

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

@@ -8,9 +8,13 @@ import {
 	hashStructuredValue,
 	readUltragoalLedger,
 	readUltragoalPlan,
+	recordUltragoalNudgeIfBudgetRemaining,
+	resolveUltragoalNudgeBudget,
+	selectUltragoalNudgeTarget,
 	type UltragoalCompletionVerification,
 	type UltragoalGoal,
 	type UltragoalLedgerEvent,
+	type UltragoalNudgeSurface,
 	type UltragoalPaths,
 	type UltragoalPlan,
 	type UltragoalReceiptKind,
@@ -65,15 +69,17 @@ function isKnownUltragoalObjective(currentObjective: string): boolean {
 	);
 }
 
-async function ultragoalReadPaths(cwd: string): Promise<UltragoalPaths> {
+async function ultragoalReadPaths(cwd: string): Promise<{ paths: UltragoalPaths; sessionId: string | null }> {
 	const envSessionId = process.env.SKC_SESSION_ID?.trim();
-	if (envSessionId) return getUltragoalPaths(cwd, envSessionId);
+	if (envSessionId) return { paths: getUltragoalPaths(cwd, envSessionId), sessionId: envSessionId };
 	try {
 		const session = await resolveSkcSessionForRead(cwd, { envSessionId: process.env.SKC_SESSION_ID });
-		return getUltragoalPaths(cwd, session.skcSessionId);
+		return { paths: getUltragoalPaths(cwd, session.skcSessionId), sessionId: session.skcSessionId };
 	} catch (error) {
 		if (error instanceof SessionResolutionError && error.code === "no_session") {
-			return getUltragoalPaths(cwd, null);
+			// No session could be resolved (no env, no auto-detectable active session).
+			// Surface the null session id so callers can decide; ask-guard treats it as inactive.
+			return { paths: getUltragoalPaths(cwd, null), sessionId: null };
 		}
 		throw error;
 	}
@@ -82,7 +88,7 @@ async function ultragoalReadPaths(cwd: string): Promise<UltragoalPaths> {
 async function hasDurableUltragoalState(cwd: string): Promise<boolean> {
 	let paths: UltragoalPaths;
 	try {
-		paths = await ultragoalReadPaths(cwd);
+		({ paths } = await ultragoalReadPaths(cwd));
 	} catch (error) {
 		if (error instanceof SessionResolutionError) return true;
 		throw error;
@@ -368,14 +374,26 @@ export async function readUltragoalVerificationState(input: {
 
 export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBlockDiagnostic> {
 	let paths: UltragoalPaths;
+	let sessionId: string | null;
 	try {
-		paths = await ultragoalReadPaths(cwd);
+		({ paths, sessionId } = 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",
 		});
 	}
+	// Ultragoal state is session-scoped. When no session can be resolved (no env,
+	// no auto-detectable active session) there is no active run to protect, so the
+	// ask guard must fall open rather than block on legacy/global durable state.
+	if (sessionId === null) {
+		return inactiveAskDiagnostic({
+			reason: "No active SKC session resolved; ultragoal is inactive.",
+			source: "absent",
+			goalsPath: paths.goalsPath,
+			ledgerPath: paths.ledgerPath,
+		});
+	}
 	try {
 		await fs.stat(paths.dir);
 	} catch (error) {
@@ -398,8 +416,8 @@ export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBl
 	let plan: UltragoalPlan | null;
 	let ledger: UltragoalLedgerEvent[];
 	try {
-		plan = await readUltragoalPlan(cwd);
-		ledger = await readUltragoalLedger(cwd);
+		plan = await readUltragoalPlan(cwd, sessionId);
+		ledger = await readUltragoalLedger(cwd, sessionId);
 	} catch (error) {
 		return activeAskDiagnostic({
 			reason: `Unable to read durable Ultragoal state: ${error instanceof Error ? error.message : String(error)}`,
@@ -409,6 +427,9 @@ export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBl
 		});
 	}
 	if (!plan) {
+		// goals.json absent or empty while the state dir exists is an inconsistent
+		// durable state, not a clean "no run". Fail closed so the pause guard (which
+		// relies on this `durable_state_unreadable` signal) keeps blocking give-ups.
 		return activeAskDiagnostic({
 			reason: "Durable .skc/ultragoal state exists but goals.json is missing or empty.",
 			source: "durable_state_unreadable",
@@ -477,6 +498,96 @@ export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBl
 	});
 }
 
+const NUDGE_SURFACE_LABEL: Record<UltragoalNudgeSurface, string> = {
+	pause: "pausing the goal",
+	drop: "dropping the run",
+	ask: "asking the user",
+	premature_complete: "finishing the story early",
+};
+
+const NUDGE_SURFACE_REASON: Record<UltragoalNudgeSurface, string> = {
+	pause: "an active story still has resolvable work",
+	drop: "the aggregate run still has unfinished stories",
+	ask: "the decision can be resolved as durable story work",
+	premature_complete: "story verification is not yet satisfied",
+};
+
+/**
+ * Escalating per-attempt refusal text. Deliberately avoids every
+ * `isUltragoalBypassPrompt` trigger: no `update_goal(`, no "skip/weaken verification",
+ * no "mark ... complete", no "--status complete", and the word "complete" never
+ * appears (so the `goal` ... `complete` proximity rule cannot match).
+ */
+export function formatUltragoalNudgeMessage(input: {
+	surface: UltragoalNudgeSurface;
+	attempt: number;
+	budget: number;
+	goalId: string;
+}): string {
+	const label = NUDGE_SURFACE_LABEL[input.surface];
+	const reason = NUDGE_SURFACE_REASON[input.surface];
+	return [
+		`Ultragoal try-harder nudge (${input.attempt}/${input.budget}) for ${input.goalId}: ${label} was refused before the normal gate.`,
+		`Resolving this is part of the goal, not a reason to stop. Try a different approach first: inspect the failure, run a focused test or replay, find local credentials/config if access is the blocker, split the obstacle with \`skc ultragoal steer --kind add_subgoal\`, delegate an executor, or record concrete review blockers.`,
+		`Reason: ${reason}.`,
+	].join("\n");
+}
+
+/**
+ * Consume one nudge for a guarded give-up attempt. MUST only be called from assert/
+ * consume paths, never from read-style `is...Blocked` diagnostics. Returns a nudge
+ * message while the per-story budget remains; otherwise reports not-nudged so the
+ * caller falls through to today's gate.
+ */
+async function consumeUltragoalNudge(input: {
+	cwd: string;
+	surface: UltragoalNudgeSurface;
+	currentGoal?: CurrentGoalLike | null;
+	sessionId?: string | null;
+}): Promise<{ nudged: true; message: string } | { nudged: false }> {
+	const sessionId = input.sessionId?.trim() || (await ultragoalReadPaths(input.cwd)).sessionId;
+	if (!sessionId) return { nudged: false };
+	const plan = await readUltragoalPlan(input.cwd, sessionId);
+	if (!plan) return { nudged: false };
+	const target = selectUltragoalNudgeTarget(plan, { currentGoalObjective: input.currentGoal?.objective });
+	if (!target) return { nudged: false };
+	const { budget } = await resolveUltragoalNudgeBudget(input.cwd);
+	const outcome = await recordUltragoalNudgeIfBudgetRemaining({
+		cwd: input.cwd,
+		sessionId,
+		target,
+		surface: input.surface,
+		budget,
+		reason: NUDGE_SURFACE_REASON[input.surface],
+		...(input.currentGoal?.objective ? { currentGoalObjective: input.currentGoal.objective } : {}),
+	});
+	if (outcome.nudged) {
+		return {
+			nudged: true,
+			message: formatUltragoalNudgeMessage({
+				surface: input.surface,
+				attempt: outcome.attempt,
+				budget: outcome.budget,
+				goalId: outcome.goalId,
+			}),
+		};
+	}
+	return { nudged: false };
+}
+
+/**
+ * Assert-path entry for the `ask` surface (the ask guard lives in another module).
+ * Resolves the active (leader) Ultragoal session so subagent/headless asks consume
+ * the leader run's budget rather than a fresh child ledger.
+ */
+export async function consumeUltragoalAskNudge(
+	cwd: string,
+	sessionId?: string | null,
+): Promise<{ nudged: true; message: string } | { nudged: false }> {
+	if (!cwd) return { nudged: false };
+	return consumeUltragoalNudge({ cwd, surface: "ask", sessionId });
+}
+
 export async function assertCanCompleteCurrentGoal(input: {
 	cwd: string;
 	currentGoal?: CurrentGoalLike | null;
@@ -485,6 +596,13 @@ export async function assertCanCompleteCurrentGoal(input: {
 	if (!input.cwd) return;
 	const diagnostic = await readUltragoalVerificationState(input);
 	if (["inactive", "unrelated_goal", "active_verified_complete"].includes(diagnostic.state)) return;
+	const nudge = await consumeUltragoalNudge({
+		cwd: input.cwd,
+		surface: "premature_complete",
+		currentGoal: input.currentGoal,
+		sessionId: input.sessionId,
+	});
+	if (nudge.nudged) throw new Error(nudge.message);
 	throw new Error(
 		`${diagnostic.message} Run strict \`skc ultragoal checkpoint --status complete --quality-gate-json <file> --skc-goal-json <file>\` first, or record review blockers and rerun verification.`,
 	);
@@ -541,6 +659,10 @@ export async function isUltragoalPauseBlocked(cwd: string): Promise<UltragoalPau
 }
 
 export async function assertUltragoalPauseAllowed(cwd: string): Promise<void> {
+	if (cwd) {
+		const nudge = await consumeUltragoalNudge({ cwd, surface: "pause" });
+		if (nudge.nudged) throw new Error(nudge.message);
+	}
 	const diagnostic = await isUltragoalPauseBlocked(cwd);
 	if (!diagnostic.blocked) return;
 	throw new Error(
@@ -551,3 +673,65 @@ export async function assertUltragoalPauseAllowed(cwd: string): Promise<void> {
 		].join("\n"),
 	);
 }
+/**
+ * Guard `goal({"op":"drop"})` during an active Ultragoal run. A *real give-up* (an
+ * aggregate run still mid-flight with incomplete required stories) is nudged while
+ * budget remains; once exhausted it falls through to today's drop behavior. Legitimate
+ * aggregate-reset drops — no durable run, unrelated goal, an already dropped/stale
+ * aggregate, or an all-stories-complete run — are never nudged. If durable state
+ * exists but cannot be read to classify the drop, fail closed.
+ */
+export async function assertUltragoalDropAllowed(input: {
+	cwd: string;
+	currentGoal?: CurrentGoalLike | null;
+	sessionId?: string | null;
+}): Promise<void> {
+	if (!input.cwd) return;
+	let paths: UltragoalPaths;
+	let sessionId: string | null;
+	try {
+		({ paths, sessionId } = await ultragoalReadPaths(input.cwd));
+	} catch (error) {
+		throw new Error(
+			`Unable to classify Ultragoal drop (durable state unreadable): ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (sessionId === null) return;
+	try {
+		await fs.stat(paths.dir);
+	} catch (error) {
+		if (isEnoent(error)) return;
+		throw new Error(
+			`Unable to classify Ultragoal drop (durable state present but unreadable): ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	let plan: UltragoalPlan | null;
+	try {
+		plan = await readUltragoalPlan(input.cwd, sessionId);
+	} catch (error) {
+		throw new Error(
+			`Unable to classify Ultragoal drop (goals.json unreadable): ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (!plan) {
+		throw new Error("Unable to classify Ultragoal drop: durable state exists but goals.json is missing or empty.");
+	}
+	// Out of scope: per-story mode drops keep today's behavior.
+	if (plan.skcGoalMode !== "aggregate") return;
+	// A real give-up requires an active aggregate goal to actually be abandoned. With no
+	// current goal-mode goal (or a non-active one), `drop` is a no-op/reset before a fresh
+	// `create`, never a give-up — so it is left un-nudged.
+	if (!input.currentGoal) return;
+	if (input.currentGoal.status !== "active") return;
+	// Unrelated active goal: not this aggregate run.
+	if (!objectiveMatches(input.currentGoal.objective, plan)) return;
+	// All required stories complete: a legitimate reset, not a give-up.
+	if (getUltragoalRunCompletionState(plan).allComplete) return;
+	const nudge = await consumeUltragoalNudge({
+		cwd: input.cwd,
+		surface: "drop",
+		currentGoal: input.currentGoal,
+		sessionId,
+	});
+	if (nudge.nudged) throw new Error(nudge.message);
+}