@sayknow-cli/coding-agent 0.5.10 → 0.5.13

package/src/modes/components/settings-selector.ts

@@ -204,6 +204,10 @@ const TIME_FORMAT_OPTIONS: SelectItem[] = [
 	{ value: "24h", label: "24h" },
 	{ value: "12h", label: "12h" },
 ];
+const USAGE_MODE_OPTIONS: SelectItem[] = [
+	{ value: "used", label: "Used" },
+	{ value: "remaining", label: "Remaining" },
+];
 const USAGE_MODE_VALUES = ["used", "remaining"] as const;
 type UsageMode = (typeof USAGE_MODE_VALUES)[number];
 
@@ -220,6 +224,7 @@ function mergeSegmentOptions(
 		path: base?.path || overrides?.path ? { ...(base?.path ?? {}), ...(overrides?.path ?? {}) } : undefined,
 		git: base?.git || overrides?.git ? { ...(base?.git ?? {}), ...(overrides?.git ?? {}) } : undefined,
 		time: base?.time || overrides?.time ? { ...(base?.time ?? {}), ...(overrides?.time ?? {}) } : undefined,
+		usage: base?.usage || overrides?.usage ? { ...(base?.usage ?? {}), ...(overrides?.usage ?? {}) } : undefined,
 	};
 }
 
@@ -279,8 +284,6 @@ function segmentPlacement(
 class StatusLineCustomEditor extends Container {
 	#list!: SettingsList;
 	#draft: StatusLineDraft;
-	#currentWidthPreviewText!: Text;
-	#narrowWidthPreviewText!: Text;
 	#previewHighlightSegment: StatusLineSegmentId | undefined;
 
 	constructor(
@@ -312,13 +315,6 @@ class StatusLineCustomEditor extends Container {
 		this.clear();
 		this.addChild(new Text(theme.bold(theme.fg("accent", "Status Line Custom Editor")), 0, 0));
 		this.addChild(new Spacer(1));
-		this.addChild(new Text(theme.fg("muted", "Current width preview:"), 0, 0));
-		this.#currentWidthPreviewText = new Text(this.#statusLinePreview(), 0, 0);
-		this.addChild(this.#currentWidthPreviewText);
-		this.addChild(new Text(theme.fg("muted", "Narrow width preview:"), 0, 0));
-		this.#narrowWidthPreviewText = new Text(this.#statusLinePreview(40), 0, 0);
-		this.addChild(this.#narrowWidthPreviewText);
-		this.addChild(new Spacer(1));
 		this.#list = new SettingsList(
 			this.#items(),
 			14,
@@ -326,27 +322,17 @@ class StatusLineCustomEditor extends Container {
 			(id, value) => this.#handleChange(id, value),
 			() => this.#cancel(),
 			item => this.#setSelectedItem(item),
+			2,
 		);
 		this.addChild(this.#list);
 	}
 
 	#refresh(): void {
-		this.#refreshPreview();
 		this.#list.setItems(this.#items());
 	}
-
-	#refreshPreview(): void {
-		this.#currentWidthPreviewText.setText(this.#statusLinePreview());
-		this.#narrowWidthPreviewText.setText(this.#statusLinePreview(40));
-	}
-
-	#statusLinePreview(width?: number): string {
-		return this.callbacks.getStatusLinePreview?.(width) ?? theme.fg("dim", "(preview not available)");
-	}
 	#setSelectedItem(item: SettingItem | undefined): void {
 		this.#previewHighlightSegment = this.#highlightSegmentForItem(item);
 		this.#preview();
-		this.#refreshPreview();
 	}
 
 	#highlightSegmentForItem(item: SettingItem | undefined): StatusLineSegmentId | undefined {
@@ -432,6 +418,22 @@ class StatusLineCustomEditor extends Container {
 					},
 				);
 			}
+			if (id === "usage") {
+				items.push({
+					id: "option.usage.mode",
+					label: "Usage: mode",
+					currentValue: this.#draft.segmentOptions.usage?.mode ?? "used",
+					submenu: (currentValue, done) =>
+						new SelectSubmenu(
+							"Usage mode",
+							"Show used quota or remaining quota in the usage segment.",
+							USAGE_MODE_OPTIONS,
+							currentValue,
+							done,
+							() => done(),
+						),
+				});
+			}
 		}
 
 		items.push(
@@ -596,6 +598,12 @@ class StatusLineCustomEditor extends Container {
 			case "time.showSeconds":
 				this.#draft.segmentOptions.time = { ...(this.#draft.segmentOptions.time ?? {}), showSeconds: bool };
 				break;
+			case "usage.mode":
+				this.#draft.segmentOptions.usage = {
+					...(this.#draft.segmentOptions.usage ?? {}),
+					mode: value === "remaining" ? "remaining" : "used",
+				};
+				break;
 		}
 	}
 
@@ -606,6 +614,8 @@ class StatusLineCustomEditor extends Container {
 			rightSegments: [...this.#draft.rightSegments],
 			separator: this.#draft.separator,
 			segmentOptions: cloneSegmentOptions(this.#draft.segmentOptions),
+			sessionAccent: settings.get("statusLine.sessionAccent"),
+			maxRows: settings.get("statusLine.maxRows"),
 			previewHighlightSegment: this.#previewHighlightSegment,
 		});
 	}
@@ -618,6 +628,7 @@ class StatusLineCustomEditor extends Container {
 			separator: settings.get("statusLine.separator"),
 			segmentOptions: cloneSegmentOptions(settings.get("statusLine.segmentOptions") as StatusLineSegmentOptions),
 			sessionAccent: settings.get("statusLine.sessionAccent"),
+			maxRows: settings.get("statusLine.maxRows"),
 			previewHighlightSegment: undefined,
 		});
 	}
@@ -1197,13 +1208,20 @@ export class SettingsSelectorComponent extends Container {
 	#buildItemsForTab(defs: SettingDef[], tabId: SettingTab): SettingItem[] {
 		const items = this.#buildItemsForDefs(defs);
 		if (tabId === "appearance") {
+			const customEditorCallbacks: SettingsCallbacks = {
+				...this.callbacks,
+				onStatusLinePreview: previewSettings => {
+					this.callbacks.onStatusLinePreview?.(previewSettings);
+					this.#updateStatusPreview();
+				},
+			};
 			const customEditorItem: SettingItem = {
 				id: STATUS_LINE_CUSTOM_EDITOR_ID,
 				label: "Status Line Custom Editor",
 				description:
 					"Edit custom status line segments, placement, separator, and typed segment options with live previews.",
 				currentValue: "open",
-				submenu: (_currentValue, done) => new StatusLineCustomEditor(this.callbacks, done),
+				submenu: (_currentValue, done) => new StatusLineCustomEditor(customEditorCallbacks, done),
 			};
 			const presetIndex = items.findIndex(item => item.id === "statusLine.preset");
 			if (presetIndex >= 0) {

package/src/modes/controllers/selector-controller.ts

@@ -5,7 +5,7 @@ import type { OAuthProvider } from "@sayknow-cli/ai/utils/oauth/types";
 import type { Component, OverlayHandle, SlashCommand } from "@sayknow-cli/tui";
 import { Input, isPetMode, Loader, Spacer, Text } from "@sayknow-cli/tui";
 import { getAgentDbPath, getProjectDir, logger, VERSION } from "@sayknow-cli/utils";
-import { type AppKeybinding, formatKeyHints } from "../../config/keybindings";
+import type { AppKeybinding } from "../../config/keybindings";
 import {
 	activateModelProfile,
 	materializeActiveModelProfileAssignment,
@@ -27,6 +27,7 @@ import {
 	getPluginsCacheDir,
 	MarketplaceManager,
 } from "../../extensibility/plugins/marketplace";
+import { INTERACTIVE_SELECTOR_RESUME_ORIGIN } from "../../extensibility/shared-events";
 import {
 	getAvailableThemes,
 	getCurrentThemeName,
@@ -832,7 +833,7 @@ export class SelectorController {
 				id: `action:${action.id}`,
 				label: action.label,
 				description: action.id,
-				keybinding: formatKeyHints(this.ctx.keybindings.getKeys(action.id as AppKeybinding)) || undefined,
+				keybinding: this.ctx.keybindings.getDisplayString(action.id as AppKeybinding) || undefined,
 				searchText: action.id,
 				handler: action.handler,
 			})),
@@ -1042,13 +1043,18 @@ export class SelectorController {
 			const selector = new ThinkingSelectorComponent(
 				this.ctx.session.thinkingLevel,
 				availableLevels,
-				selection => {
-					done();
-
+				async selection => {
 					const { level, persistDefault } = selection;
 					const configuredDefault = this.ctx.settings.get("defaultThinkingLevel");
 					const levelToApply = level === ThinkingLevel.Inherit ? configuredDefault : level;
-					this.ctx.session.setThinkingLevel(levelToApply, persistDefault);
+					try {
+						await this.ctx.session.setThinkingLevelForControl(level, persistDefault);
+					} catch (error) {
+						this.ctx.showError(error instanceof Error ? error.message : String(error));
+						return;
+					}
+					done();
+
 					const effectiveLevel = this.ctx.session.thinkingLevel ?? ThinkingLevel.Off;
 					const requestedLabel =
 						level === ThinkingLevel.Inherit ? `${level} (configured default: ${configuredDefault})` : level;
@@ -1959,10 +1965,7 @@ export class SelectorController {
 	}
 
 	async showSessionSelector(): Promise<void> {
-		const sessions = await SessionManager.listForResumePickerReadOnly(
-			this.ctx.sessionManager.getCwd(),
-			this.ctx.sessionManager.getSessionDir(),
-		);
+		const sessions = await this.ctx.sessionManager.listForResumePickerReadOnly();
 		this.showSelector(done => {
 			const selector = new SessionSelectorComponent(
 				sessions,
@@ -2064,13 +2067,30 @@ export class SelectorController {
 			const previousSessionId = this.ctx.sessionManager.getSessionId();
 			const migrationPolicy =
 				this.ctx.settings?.get("session.directoryMigration") === "disabled" ? "disabled" : "copy-retain";
-			const writableSessionPath = await this.ctx.sessionManager.prepareManagedCandidateForWrite(
-				sessionPath,
-				migrationPolicy,
-			);
+			let writableSessionPath = sessionPath;
+			if (this.ctx.sessionManager.isManagedDestination()) {
+				// Managed candidates are prepared against their inspected identity so a
+				// replacement race fails closed before adoption. Explicit `--session-dir`
+				// selections never enter the managed migration fence (preparation would
+				// reject a non-managed destination authority outright).
+				const inspection = await SessionManager.inspectSessionTailReadOnly(sessionPath);
+				if (inspection.kind === "error")
+					throw new Error(`Could not inspect selected session: ${inspection.reason}`);
+				writableSessionPath = await this.ctx.sessionManager.prepareManagedCandidateForStrictAdoption(
+					sessionPath,
+					migrationPolicy,
+					inspection.identity,
+				);
+			}
 
 			// Switch session via AgentSession (emits hook and tool session events)
-			if (!(await this.ctx.session.switchSession(writableSessionPath, options))) return false;
+			if (
+				!(await this.ctx.session.switchSession(writableSessionPath, {
+					...options,
+					transition: { origin: INTERACTIVE_SELECTOR_RESUME_ORIGIN },
+				}))
+			)
+				return false;
 			onSwitched?.();
 			this.#clearTransientSessionUi();
 			const switchingToDifferentSession = previousSessionId !== this.ctx.sessionManager.getSessionId();

package/src/modes/rpc/rpc-client.ts

@@ -288,11 +288,27 @@ class StdioRpcTransport implements RpcTransport {
 			} else {
 				onClose(new Error("RPC stdio transport closed"));
 			}
-		})().catch((err: Error) => {
-			if (!readySettled) {
-				readySettled = true;
+		})().catch(async (err: Error) => {
+			if (readySettled) {
+				onClose(err);
+				return;
+			}
+			// Non-JSONL stdout before `ready` usually means the CLI refused to start
+			// (for example a usage error such as the removed `--mode rpc`). When the
+			// child is already gone, report its exit code and stderr instead of the
+			// parse noise so callers see the actual refusal.
+			const proc = this.#process;
+			const exitCode = proc
+				? await Promise.race([proc.exited.catch(() => proc.exitCode ?? -1), Bun.sleep(1_000).then(() => undefined)])
+				: undefined;
+			if (readySettled) return;
+			readySettled = true;
+			if (exitCode === undefined) {
 				readyReject(err);
-			} else onClose(err);
+				return;
+			}
+			const stderr = await getStartupStderr();
+			readyReject(new Error(`Agent process exited with code ${exitCode} before ready. Stderr: ${stderr}`));
 		});
 		void this.#process.exited.then(async (exitCode: number) => {
 			if (!readySettled) {

package/src/sdk/bus/index.ts

@@ -3217,9 +3217,7 @@ export function createNotificationsExtension(
 		let serverStopped = rt.serverStopped;
 		if (!serverStopped) {
 			try {
-				// fork's NotificationServer.stop() is synchronous; stopAndWait is upstream v0.11.x's
-				// async variant. TODO(port): add stop_and_wait to pi-natives/src/notifications.rs.
-				rt.server.stop();
+				await rt.server.stopAndWait();
 				serverStopped = true;
 				rt.serverStopped = true;
 			} catch (e) {

package/src/session-import/redact.ts

@@ -9,8 +9,7 @@
 
 export const IMPORT_REDACTED_PLACEHOLDER = "[REDACTED]";
 /** Bumped when patterns change; persisted in import provenance. */
-export const IMPORT_SANITIZER_VERSION = 3;
-
+export const IMPORT_SANITIZER_VERSION = 4;
 interface RedactionRule {
 	readonly id: string;
 	readonly pattern: RegExp;
@@ -68,7 +67,11 @@ const REDACTION_RULES: readonly RedactionRule[] = [
 	// Long hex secrets (64+ hex chars: webhook secrets, signing keys).
 	{ id: "hex-secret", pattern: new RegExp(`\\b${HEX}{64,}\\b`, "g") },
 	// Basic-auth credentials embedded in URLs (https://user:pass@host).
-	{ id: "url-credential", pattern: /([a-z][a-z0-9+.-]*:\/\/)[^/\s:@]{1,256}:[^/\s@]{1,256}@/gi },
+	// The scheme repetition is bounded. Unbounded `[a-z0-9+.-]*` in front of the
+	// literal `://` re-tries every prefix of a long alphabetic run before failing,
+	// which is quadratic in the input length: 200 KB of ordinary prose costs ~10s.
+	// IANA's longest registered scheme is well under 16 characters.
+	{ id: "url-credential", pattern: /([a-z][a-z0-9+.-]{0,15}:\/\/)[^/\s:@]{1,256}:[^/\s@]{1,256}@/gi },
 	// Sensitive env/KEY assignments: OPENAI_API_KEY=..., token: ..., password = ...
 	// The name prefix is optional so a bare sensitive name (`password: …`) also matches.
 	{

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

@@ -515,38 +515,35 @@ async function writeGuardedResolvedJsonAtomic(
 	value: unknown,
 	options: GuardedStateWriterOptions,
 ): Promise<GuardedWriteResult> {
-	return lockResolvedWorkflowTarget(
-		filePath,
-		async () => {
-			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);
-				}
-				const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
-				await atomicWrite(filePath, jsonText(next));
-				await maybeAudit(filePath, options);
-				return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
-			}
+	const write = async (): Promise<GuardedWriteResult> => {
+		const current = await readJsonIfPresentTolerant(filePath);
+		const currentRevision = persistedStateRevision(current);
 
-			const incomingSourceRevision =
-				options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
-			if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
-				return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
+		if (options.policy === "source") {
+			if (options.expectedRevision !== undefined && options.expectedRevision !== currentRevision) {
+				throw new StateWriteConflictError(filePath, options.expectedRevision, currentRevision);
 			}
-			const next = stampStateRevision(
-				withWorkflowReceipt(value, buildReceipt(options)),
-				currentRevision + 1,
-				incomingSourceRevision,
-			);
+			const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
 			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
-		},
-		options.lock,
-	);
+		}
+
+		const incomingSourceRevision =
+			options.sourceRevision ?? (isPlainObject(value) ? persistedStateRevision(value) : 0);
+		if (current !== undefined && incomingSourceRevision <= persistedSourceRevision(current)) {
+			return { path: filePath, written: false, reason: "stale-skip", revision: currentRevision };
+		}
+		const next = stampStateRevision(
+			withWorkflowReceipt(value, buildReceipt(options)),
+			currentRevision + 1,
+			incomingSourceRevision,
+		);
+		await atomicWrite(filePath, jsonText(next));
+		await maybeAudit(filePath, options);
+		return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
+	};
+	return options.lockHeld ? write() : lockResolvedWorkflowTarget(filePath, write, options.lock);
 }
 
 export async function writeGuardedJsonAtomic(

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

@@ -31,6 +31,11 @@ import {
 	validateDeferredMemberReceiptFresh,
 	validateReceiptFreshBase,
 } from "./ultragoal-receipt-freshness";
+import {
+	assertUltragoalAdoptionPublished,
+	assertUltragoalGoalNotFenced,
+	runUltragoalSuccessionCommand,
+} from "./ultragoal-succession";
 
 export {
 	CRITIC_GATE_HARD_STOP_EVENT,
@@ -600,7 +605,12 @@ export async function recordUltragoalNudgeIfBudgetRemaining(input: {
 	);
 }
 
-export async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void> {
+export async function writePlan(
+	cwd: string,
+	plan: UltragoalPlan,
+	sessionId?: string | null,
+	options: { lockHeld?: boolean } = {},
+): Promise<void> {
 	const resolvedSessionId =
 		sessionId?.trim() || resolveSkcSessionForWrite(cwd, { envSessionId: process.env.SKC_SESSION_ID }).skcSessionId;
 	const paths = getUltragoalPaths(cwd, resolvedSessionId);
@@ -611,12 +621,32 @@ export async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: st
 	await writeGuardedJsonAtomic(paths.goalsPath, plan, {
 		cwd,
 		policy: "source",
+		lockHeld: options.lockHeld === true,
 		expectedRevision: typeof plan.state_revision === "number" ? persistedStateRevision(plan) : undefined,
 		audit: { category: "state", verb: "write", owner: "skc-runtime", sessionId: resolvedSessionId },
 	});
 	await writeSessionActivityMarker(cwd, resolvedSessionId, { writer: "ultragoal-runtime", path: paths.goalsPath });
 }
 
+/**
+ * The single exclusion that decides who owns an Ultragoal run.
+ *
+ * Establishing ownership is a read-decide-write sequence: a start reads the plan,
+ * checks the outgoing succession fence, then commits `active`. Every caller that
+ * decides ownership — source admission, succession offer, and successor
+ * publication — runs that decision inside this lock, keyed on the plan.
+ */
+export async function withUltragoalPlanOwnership<T>(cwd: string, sessionId: string, fn: () => Promise<T>): Promise<T> {
+	return withWorkflowStateLock(getUltragoalPaths(cwd, sessionId).goalsPath, fn, { cwd });
+}
+
+export async function resolveUltragoalOwnershipSession(cwd: string, sessionId?: string | null): Promise<string> {
+	return (
+		sessionId?.trim() ||
+		(await resolveSkcSessionForRead(cwd, { envSessionId: process.env.SKC_SESSION_ID })).skcSessionId
+	);
+}
+
 function chooseReceiptKind(
 	plan: UltragoalPlan,
 	ledger: readonly UltragoalLedgerEvent[],
@@ -1710,40 +1740,44 @@ export async function startNextUltragoalGoal(input: {
 	allComplete: boolean;
 	nextAction: UltragoalCompleteNextAction;
 }> {
-	const plan = await readUltragoalPlan(input.cwd, input.sessionId);
-	if (!plan) throw new Error("No ultragoal plan found. Run `skc ultragoal create-goals --brief ...` first.");
-	// 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 });
+	const sessionId = await resolveUltragoalOwnershipSession(input.cwd, input.sessionId);
+	return withUltragoalPlanOwnership(input.cwd, sessionId, async () => {
+		const plan = await readUltragoalPlan(input.cwd, sessionId);
+		if (!plan) throw new Error("No ultragoal plan found. Run `skc ultragoal create-goals --brief ...` first.");
+		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);
+		await assertUltragoalAdoptionPublished(input.cwd, sessionId);
+		const retryFailed = input.retryFailed === true;
+		const goal = chooseNextGoal(plan, retryFailed);
+		if (goal) await assertUltragoalGoalNotFenced(input.cwd, sessionId, goal.id);
+		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";
+			goal.startedAt = goal.startedAt ?? now;
+			goal.updatedAt = now;
+			plan.updatedAt = now;
+			await writePlan(input.cwd, plan, sessionId, { lockHeld: true });
+			await appendLedger(input.cwd, { event: "goal_started", goalId: goal.id }, sessionId);
+		}
 		return {
 			plan,
-			allComplete: state.allComplete,
-			nextAction: resolveUltragoalCompleteNextAction(plan, { retryFailed }),
+			goal,
+			allComplete: false,
+			nextAction: { kind: "execute-goal", goal },
 		};
-	}
-	if (goal.status !== "active") {
-		const now = new Date().toISOString();
-		goal.status = "active";
-		goal.startedAt = goal.startedAt ?? now;
-		goal.updatedAt = now;
-		plan.updatedAt = now;
-		await writePlan(input.cwd, plan, input.sessionId);
-		await appendLedger(input.cwd, { event: "goal_started", goalId: goal.id }, input.sessionId);
-	}
-	return {
-		plan,
-		goal,
-		allComplete: false,
-		nextAction: { kind: "execute-goal", goal },
-	};
+	});
 }
 
 async function readStructuredValue(cwd: string, value: string): Promise<unknown> {
@@ -3046,10 +3080,13 @@ export async function checkpointUltragoalGoal(input: {
 	evidence: string;
 	qualityGateJson?: string;
 }): Promise<UltragoalPlan> {
-	const plan = await readUltragoalPlan(input.cwd);
+	const sessionId = await resolveUltragoalOwnershipSession(input.cwd, null);
+	const plan = await readUltragoalPlan(input.cwd, sessionId);
 	if (!plan) throw new Error("No ultragoal plan found. Run `skc ultragoal create-goals --brief ...` first.");
 	const goal = plan.goals.find(item => item.id === input.goalId);
 	if (!goal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
+	await assertUltragoalAdoptionPublished(input.cwd, sessionId);
+	await assertUltragoalGoalNotFenced(input.cwd, sessionId, goal.id);
 	const evidence = input.evidence.trim();
 	if (!evidence) throw new Error("checkpoint evidence is required");
 	const ledgerBefore = await readUltragoalLedger(input.cwd);
@@ -3209,17 +3246,21 @@ export async function checkpointUltragoalGoal(input: {
 	goal.updatedAt = now;
 	if (input.status === "complete") goal.completedAt = now;
 	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	const persistedPlan = await readUltragoalPlan(input.cwd);
-	if (persistedPlan?.state_revision !== undefined) plan.state_revision = persistedPlan.state_revision;
-	await appendLedger(input.cwd, {
-		eventId: pendingCheckpointEventId,
-		event: "goal_checkpointed",
-		goalId: goal.id,
-		status: input.status,
-		evidence,
-		qualityGateJson,
-		completionVerification: goal.completionVerification,
+	await withUltragoalPlanOwnership(input.cwd, sessionId, async () => {
+		await assertUltragoalAdoptionPublished(input.cwd, sessionId);
+		await assertUltragoalGoalNotFenced(input.cwd, sessionId, goal.id);
+		await writePlan(input.cwd, plan, sessionId, { lockHeld: true });
+		const persistedPlan = await readUltragoalPlan(input.cwd, sessionId);
+		if (persistedPlan?.state_revision !== undefined) plan.state_revision = persistedPlan.state_revision;
+		await appendLedger(input.cwd, {
+			eventId: pendingCheckpointEventId,
+			event: "goal_checkpointed",
+			goalId: goal.id,
+			status: input.status,
+			evidence,
+			qualityGateJson,
+			completionVerification: goal.completionVerification,
+		});
 	});
 	return plan;
 }
@@ -4155,6 +4196,10 @@ const FLAGS_WITH_VALUES = new Set([
 	"--review-result-json",
 	"--qa-result-json",
 	"--target-state-json",
+	"--target-repo",
+	"--authorize",
+	"--authorized-by",
+	"--offer",
 ]);
 
 function isHelpArg(arg: string): boolean {
@@ -4283,6 +4328,36 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 			"",
 		].join("\n");
 	}
+	if (subject === "succession") {
+		return [
+			"Run native SKC Ultragoal workflow commands",
+			"",
+			"USAGE",
+			"  $ skc ultragoal succession offer --target-repo <path> --goal-id <id> [--goal-id <id> ...] --authorize <statement> --authorized-by <identity> [--json]",
+			"  $ skc ultragoal succession adopt --offer <path> [--skc-goal-mode aggregate|per-story] [--json]",
+			"  $ skc ultragoal succession status [--json]",
+			"",
+			"FLAGS",
+			"      --target-repo=<value>        Destination repository for the successor run; never the source repository",
+			"      --goal-id=<value>            Unfinished source goal to hand off (repeatable; no implicit or wildcard selection)",
+			"      --authorize=<value>          Required. Explicit bounded authorization statement for this source/target/selection",
+			"      --authorized-by=<value>      Required. Identity that authorized the handoff",
+			"      --offer=<value>              Offer document recorded by `succession offer`, read from inside the source worktree",
+			"      --skc-goal-mode=<value>      Successor validation mode (default aggregate); the source mode is provenance only",
+			"      --json                       Output a machine-readable receipt",
+			"",
+			"OWNERSHIP",
+			"  `offer` records a durable outgoing ownership fence, so the source run stops scheduling and checkpointing the",
+			"  selected goals immediately — not when the target happens to adopt. Between offer and adoption no run owns them.",
+			"  The source brief, goals and ledger are never written. Goals the offer did not select stay schedulable.",
+			"  There is deliberately no `revoke` verb: an unadopted offer keeps its goals fenced.",
+			"",
+			"EXAMPLES",
+			'  $ skc ultragoal succession offer --target-repo ../payments-api --goal-id G002 --goal-id G003 --authorize "leader approved moving the refund stories" --authorized-by human:release-lead --json',
+			"  $ skc ultragoal succession adopt --offer ../plan-repo/.skc/_session-abc/ultragoal/succession/offer-<id>.json --json",
+			"",
+		].join("\n");
+	}
 
 	return [
 		"Run native SKC Ultragoal workflow commands",
@@ -4305,8 +4380,11 @@ function renderUltragoalHelp(args: readonly string[]): string | null {
 		"  start-pipeline-overlap",
 		"  join-pipeline-overlap",
 		"  rebaseline-pipeline-overlap",
+		"  succession offer",
+		"  succession adopt",
+		"  succession status",
 		"",
-		"Run `skc ultragoal checkpoint --help`, `skc ultragoal review --help`, `skc ultragoal classify-blocker --help`, `skc ultragoal record-critic-verdict --help`, or `skc ultragoal record-critic-gate-override --help` for command-specific requirements.",
+		"Run `skc ultragoal checkpoint --help`, `skc ultragoal review --help`, `skc ultragoal classify-blocker --help`, `skc ultragoal record-critic-verdict --help`, `skc ultragoal record-critic-gate-override --help`, or `skc ultragoal succession --help` for command-specific requirements.",
 		"",
 	].join("\n");
 }
@@ -4846,6 +4924,8 @@ async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<Ul
 					stdout: json ? renderCliWriteReceipt(receipt) : `Rebaselined pipeline overlap ${receipt.overlap_id}.\n`,
 				};
 			}
+			case "succession":
+				return await runUltragoalSuccessionCommand(args, cwd);
 			default:
 				return { status: 1, stderr: `Unknown skc ultragoal command: ${command}\n` };
 		}