@sayknow-cli/coding-agent 0.5.11 → 0.5.13

package/src/config/model-registry.ts

@@ -29,6 +29,7 @@ import {
 	UNK_MAX_TOKENS,
 	unregisterCustomApis,
 } from "@sayknow-cli/ai";
+import { detectDiscoveredApiFamily } from "@sayknow-cli/ai/utils/discovery/openai-compatible";
 
 // Sentinel for local-only OAuth token (LM Studio, vLLM) — declared inline to avoid loading
 // any provider module at startup. Must match `DEFAULT_LOCAL_TOKEN` in oauth/lm-studio.ts.
@@ -212,6 +213,36 @@ type ProviderValidationMode = "models-config" | "runtime-register";
 
 const OPENAI_REQUEST_TRANSFORM_APIS = new Set<Api>(["openai-completions", "openai-responses"]);
 
+const OPENAI_FAMILY_APIS = new Set<Api>([
+	"openai-completions",
+	"openai-responses",
+	"openai-codex-responses",
+	"azure-openai-responses",
+]);
+
+function isOpenAIFamilyApi(api: Api): boolean {
+	return OPENAI_FAMILY_APIS.has(api);
+}
+
+function dominantOpenAIFamilyModelApi(models: readonly { api?: string }[] | undefined): Api | undefined {
+	if (!models || models.length === 0) return undefined;
+	const counts = new Map<Api, number>();
+	for (const model of models) {
+		const api = model.api as Api | undefined;
+		if (api === undefined || !isOpenAIFamilyApi(api)) continue;
+		counts.set(api, (counts.get(api) ?? 0) + 1);
+	}
+	let best: Api | undefined;
+	let bestCount = 0;
+	for (const [api, count] of counts) {
+		if (count > bestCount) {
+			best = api;
+			bestCount = count;
+		}
+	}
+	return best;
+}
+
 function getKnownProviderApis(providerName: string): Set<Api> {
 	const apis = new Set<Api>();
 	for (const model of getBundledModels(providerName as Parameters<typeof getBundledModels>[0])) {
@@ -1563,17 +1594,30 @@ export class ModelRegistry {
 				keylessProviders.add(providerName);
 			}
 
-			if (providerConfig.discovery && providerConfig.api) {
+			const effectiveDiscoveryBaseUrl = providerConfig.baseUrl ?? resolveProviderBaseUrlFromEnv(providerName);
+			const providerApi =
+				(providerConfig.api as Api | undefined) ??
+				dominantOpenAIFamilyModelApi(providerConfig.models as { api?: string }[] | undefined);
+			const autoDiscovery: ProviderDiscovery | undefined =
+				!providerConfig.discovery &&
+				!localOpenAICompat &&
+				providerApi !== undefined &&
+				isOpenAIFamilyApi(providerApi) &&
+				effectiveDiscoveryBaseUrl !== undefined
+					? { type: "openai-models-list" }
+					: undefined;
+			const effectiveDiscovery = providerConfig.discovery ?? autoDiscovery;
+			if (effectiveDiscovery && providerApi) {
 				discoverableProviders.push({
 					provider: providerName,
-					api: providerConfig.api as Api,
-					baseUrl: providerConfig.baseUrl ?? resolveProviderBaseUrlFromEnv(providerName),
+					api: providerApi,
+					baseUrl: effectiveDiscoveryBaseUrl,
 					headers: providerConfig.headers,
 					compat: providerConfig.compat,
 					requestTransform: providerConfig.requestTransform,
 					cacheRetention: providerConfig.cacheRetention,
-					discovery: providerConfig.discovery,
-					optional: false,
+					discovery: effectiveDiscovery,
+					optional: !providerConfig.discovery,
 				});
 			}
 
@@ -2280,50 +2324,82 @@ export class ModelRegistry {
 				}
 				return new Error(`HTTP ${response.status} from ${modelsUrl}`);
 			},
-			mapModel: (item, defaults) => ({
-				...defaults,
-				reasoning: isOmlx,
-				...(isOmlx
-					? {
-							thinking: {
-								mode: "effort" as const,
-								minLevel: Effort.Low,
-								maxLevel: Effort.High,
-								defaultLevel: Effort.Medium,
-								levels: [Effort.Low, Effort.Medium, Effort.High],
-							},
-						}
-					: {}),
-				contextWindow:
-					parseDiscoveryLimit(item.max_model_len) ??
-					parseDiscoveryLimit(item.context_length) ??
-					parseDiscoveryLimit(item.context_window) ??
-					parseDiscoveryLimit(item.max_context_length) ??
-					UNK_CONTEXT_WINDOW,
-				maxTokens:
-					parseDiscoveryLimit(item.max_completion_tokens) ??
-					parseDiscoveryLimit(item.max_tokens) ??
-					parseDiscoveryLimit(item.max_output_tokens) ??
-					UNK_MAX_TOKENS,
-				headers,
-				compat: {
-					...(providerConfig.compat ?? {}),
-					supportsStore: false,
-					supportsDeveloperRole: false,
-					supportsReasoningEffort: isOmlx,
+			mapModel: (item, defaults) => {
+				const api = this.#resolveDiscoveredModelApi(
+					providerConfig,
+					typeof item.id === "string" ? item.id : "",
+					item,
+				);
+				return {
+					...defaults,
+					api,
+					reasoning: isOmlx,
 					...(isOmlx
 						? {
-								thinkingFormat: "qwen-chat-template" as const,
-								reasoningContentField: "reasoning_content" as const,
+								thinking: {
+									mode: "effort" as const,
+									minLevel: Effort.Low,
+									maxLevel: Effort.High,
+									defaultLevel: Effort.Medium,
+									levels: [Effort.Low, Effort.Medium, Effort.High],
+								},
 							}
 						: {}),
-				},
-			}),
+					contextWindow:
+						parseDiscoveryLimit(item.max_model_len) ??
+						parseDiscoveryLimit(item.context_length) ??
+						parseDiscoveryLimit(item.context_window) ??
+						parseDiscoveryLimit(item.max_context_length) ??
+						UNK_CONTEXT_WINDOW,
+					maxTokens:
+						parseDiscoveryLimit(item.max_completion_tokens) ??
+						parseDiscoveryLimit(item.max_tokens) ??
+						parseDiscoveryLimit(item.max_output_tokens) ??
+						UNK_MAX_TOKENS,
+					headers,
+					compat: {
+						...(providerConfig.compat ?? {}),
+						supportsStore: false,
+						supportsDeveloperRole: false,
+						supportsReasoningEffort: isOmlx,
+						...(isOmlx
+							? {
+									thinkingFormat: "qwen-chat-template" as const,
+									reasoningContentField: "reasoning_content" as const,
+								}
+							: {}),
+					},
+				};
+			},
 		});
 		if (discovered === null) throw new Error(`Invalid OpenAI-compatible model catalog from ${baseUrl}`);
 		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
 	}
 
+	#resolveDiscoveredModelApi(
+		providerConfig: DiscoveryProviderConfig,
+		modelId: string,
+		entry?: { id?: unknown; owned_by?: unknown },
+	): Api {
+		let matchedPrefixLength = -1;
+		let prefixApi: Api | undefined;
+		for (const [prefix, routedApi] of Object.entries(providerConfig.discovery.apiByModelPrefix ?? {})) {
+			if (modelId.startsWith(prefix) && prefix.length > matchedPrefixLength) {
+				prefixApi = routedApi as Api;
+				matchedPrefixLength = prefix.length;
+			}
+		}
+		if (prefixApi !== undefined) return prefixApi;
+		if (providerConfig.discovery.type === "openai-models-list") {
+			const detected = detectDiscoveredApiFamily(entry ?? { id: modelId });
+			if (detected === "anthropic-messages") return "anthropic-messages";
+			if (detected === "openai-completions") {
+				return isOpenAIFamilyApi(providerConfig.api) ? providerConfig.api : "openai-completions";
+			}
+		}
+		return providerConfig.api;
+	}
+
 	#normalizeLlamaCppBaseUrl(baseUrl?: string): string {
 		const defaultBaseUrl = "http://127.0.0.1:8080";
 		const raw = baseUrl || defaultBaseUrl;

package/src/config/models-config-schema.ts

@@ -185,6 +185,7 @@ export type ModelOverride = z.infer<typeof ModelOverrideSchema>;
 
 export const ProviderDiscoverySchema = z.object({
 	type: z.enum(["ollama", "llama.cpp", "lm-studio", "omlx", "sglang", "openai-models-list"]),
+	apiByModelPrefix: z.record(z.string().min(1), z.string().min(1)).optional(),
 });
 
 const LocalOpenAICompatSchema = z

package/src/defaults/skc/skills/ultragoal/SKILL.md

@@ -37,6 +37,9 @@ skc ultragoal complete-goals --retry-failed
 skc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --quality-gate-json <quality-gate-json-or-path>
 skc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"
 skc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>"
+skc ultragoal succession offer --target-repo <path> --goal-id <id> --authorize "<statement>" --authorized-by <identity>
+skc ultragoal succession adopt --offer <path>
+skc ultragoal succession status --json
 ```
 
 Use these exact goal-tool calls for the inline goal state:

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` };
 		}