@sayknow-cli/coding-agent 0.5.10 → 0.5.13

package/src/cli/telegram-cli.ts

@@ -148,7 +148,7 @@ export async function runTelegramCommand(cmd: TelegramCommandArgs): Promise<void
 		case "__gateway": {
 			// Hidden entrypoint: run the Telegram Remote gateway in-process. Reached
 			// only via the self-spawn from runStart()/autostart, never by users.
-			const { loadConfigFromEnv, runService } = await import("../../../telegram-remote/src/index");
+			const { loadConfigFromEnv, runService } = await import("@sayknow-cli/telegram-remote");
 			await runService(loadConfigFromEnv(process.env));
 			return;
 		}

package/src/config/file-lock-gc.ts

@@ -58,9 +58,33 @@ function keptMalformedRecord(lockDir: string): GcRecord {
 	};
 }
 
+function emptyLockDirRecord(lockDir: string): GcRecord {
+	return {
+		store: "file_locks",
+		id: lockDir,
+		path: lockDir,
+		pid_status: "none",
+		status: "stale",
+		stale: true,
+		removable: true,
+		action: "none",
+		reason: "empty_file_lock_dir",
+	};
+}
+
 async function collectLockRecord(lockDir: string, ctx: GcContext): Promise<GcRecord> {
 	const info = await readFileLockInfoForGc(lockDir);
-	if (!info) return keptMalformedRecord(lockDir);
+	if (!info) {
+		// mkdir-before-info crash leftover: an empty `.lock` dir has no owner token
+		// and is safe to reclaim. Any other info-less shape stays fail-closed.
+		try {
+			const entries = await fs.readdir(lockDir);
+			if (entries.length === 0) return emptyLockDirRecord(lockDir);
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
+		return keptMalformedRecord(lockDir);
+	}
 
 	const probeResult = ctx.probe(info.pid);
 	const pidStatus = gcPidStatusLabel(probeResult);
@@ -165,7 +189,20 @@ export const fileLocksGcAdapter: GcStoreAdapter = {
 	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
 		const lockDir = record.path ?? record.id;
 		const info = await readFileLockInfoForGc(lockDir);
-		if (!info) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+		if (!info) {
+			if (record.reason !== "empty_file_lock_dir") {
+				return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+			}
+			try {
+				const entries = await fs.readdir(lockDir);
+				if (entries.length !== 0) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+				await fs.rmdir(lockDir);
+				return { removed: true };
+			} catch (error) {
+				if (isEnoent(error)) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+				return { removed: false, error: errorMessage(error) };
+			}
+		}
 
 		const probeResult = ctx.probe(info.pid);
 		if (probeResult.status !== "dead") {

package/src/config/file-lock.ts

@@ -14,6 +14,21 @@ const DEFAULT_OPTIONS: Required<FileLockOptions> = {
 	retries: 50,
 	retryDelayMs: 100,
 };
+export class FileLockAcquireError extends Error {
+	readonly code = "acquire_timeout";
+
+	constructor(
+		readonly filePath: string,
+		readonly lockPath: string,
+		readonly attempts: number,
+		readonly holder: string,
+	) {
+		super(
+			`Failed to acquire lock for ${filePath} after ${attempts} attempts: ${holder} (${lockPath}); a live owner is never displaced`,
+		);
+		this.name = "FileLockAcquireError";
+	}
+}
 
 type LockInfo = FileLockOwnerToken;
 
@@ -243,6 +258,12 @@ async function releaseLock(lockPath: string, owner: FileLockOwnerToken): Promise
 	const outcome = await removeFileLockDirForGc(lockPath, owner);
 	if (outcome !== "removed") throw new Error(`Failed to release file lock: ${outcome}.`);
 }
+async function lockHolderDescription(lockPath: string): Promise<string> {
+	const info = await readLockInfo(lockPath);
+	if (!info) return "unknown holder";
+	return `pid ${info.pid}`;
+}
+
 async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
 	const lockPath = getLockPath(filePath);
@@ -255,7 +276,7 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 		if (await removeStaleLockForAcquire(lockPath, stale)) continue;
 		await Bun.sleep(opts.retryDelayMs);
 	}
-	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
+	throw new FileLockAcquireError(filePath, lockPath, opts.retries, await lockHolderDescription(lockPath));
 }
 
 /**

package/src/config/model-profile-activation.ts

@@ -2,11 +2,8 @@ import { ThinkingLevel } from "@sayknow-cli/agent-core";
 import type { Api, Model } from "@sayknow-cli/ai";
 import type { AgentSession } from "../session/agent-session";
 import { formatClampedModelSelector } from "../thinking";
-import {
-	aggregateModelProfileRequiredProviders,
-	formatAvailableProfileNames,
-	resolveProfileBindings,
-} from "./model-profiles";
+import { UnknownModelProfileError, validateModelProfileName } from "./model-profile-contract";
+import { aggregateModelProfileRequiredProviders, resolveProfileBindings } from "./model-profiles";
 import {
 	isAuthenticated,
 	kNoAuth,
@@ -49,7 +46,7 @@ export interface PrepareModelProfileActivationOptions {
 		| "resolveCanonicalModel"
 		| "getCanonicalVariants"
 		| "getCanonicalId"
-	>;
+	> & { getError?: ModelRegistry["getError"] };
 	settings: Pick<Settings, "get">;
 	profileName: string;
 }
@@ -347,12 +344,11 @@ export async function prepareModelProfileActivation(
 	options: PrepareModelProfileActivationOptions,
 ): Promise<PreparedModelProfileActivation> {
 	const profiles = options.modelRegistry.getModelProfiles();
-	const profileName = resolveModelProfileName(options.profileName, profiles);
+	// Typed contract errors (`unknown_model_profile` / `model_profile_registry_error`)
+	// so SDK lifecycle readiness and BrokerResponse preserve the code and details.
+	const profileName = validateModelProfileName(options.profileName, profiles, options.modelRegistry.getError?.());
 	const profile = profiles.get(profileName) ?? options.modelRegistry.getModelProfile(profileName);
-	if (!profile) {
-		const available = formatAvailableProfileNames(profiles);
-		throw new Error(`Unknown model profile "${options.profileName}". Available profiles: ${available}`);
-	}
+	if (!profile) throw new UnknownModelProfileError(options.profileName, profiles);
 	const profileLabel = options.profileName;
 
 	const requiredProviders = aggregateModelProfileRequiredProviders(profile.requiredProviders, profile);

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.
@@ -69,6 +70,36 @@ import { type Settings, settings } from "./settings";
 
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 
+/**
+ * Strip userinfo and query strings from a discovery URL before it is surfaced
+ * in an error message, so credentials embedded in the URL never reach logs or UI.
+ */
+function redactDiscoveryUrl(value: string | URL): string {
+	try {
+		const url = typeof value === "string" ? new URL(value) : value;
+		return `${url.origin}${url.pathname}`;
+	} catch {
+		return "(invalid URL)";
+	}
+}
+
+/**
+ * Fingerprint of the environment variables that can change provider
+ * availability without touching AuthStorage. Keys the `getAvailable()` cache
+ * so a process.env mutation invalidates it.
+ */
+function envAvailabilityFingerprint(): string {
+	return Object.entries(process.env)
+		.filter(
+			([name]) =>
+				/(?:_API_KEY|_OAUTH_TOKEN|_ACCESS_TOKEN)$/.test(name) ||
+				/^(?:GH_TOKEN|GITHUB_TOKEN|HF_TOKEN|COPILOT_GITHUB_TOKEN)$/.test(name),
+		)
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([name, value]) => `${name}=${value ?? ""}`)
+		.join("\u0000");
+}
+
 export const kNoAuth = "N/A";
 
 export function isAuthenticated(apiKey: string | undefined | null): apiKey is string {
@@ -182,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])) {
@@ -544,6 +605,8 @@ export interface ProviderDiscoveryState {
 export interface CanonicalModelQueryOptions {
 	availableOnly?: boolean;
 	candidates?: readonly Model<Api>[];
+	/** Session whose canonical stickiness should scope the lookup, when the caller has one. */
+	sessionId?: string;
 }
 
 /** Result of loading custom models from models.json */
@@ -1021,6 +1084,9 @@ export class ModelRegistry {
 	#providerWebSearchModes: Map<string, WebSearchMode> = new Map();
 	#keylessProviders: Set<string> = new Set();
 	#discoverableProviders: DiscoveryProviderConfig[] = [];
+	#availableModelsCache: Model<Api>[] | undefined;
+	#availableModelsDisabledProviders: string | undefined;
+	#availableModelsEnvFingerprint: string | undefined;
 	#customModelOverlays: CustomModelOverlay[] = [];
 	#providerOverrides: Map<string, ProviderOverride> = new Map();
 	#modelOverrides: Map<string, Map<string, ModelOverride>> = new Map();
@@ -1074,6 +1140,8 @@ export class ModelRegistry {
 			const keyConfig = this.#customProviderApiKeys.get(provider);
 			return keyConfig;
 		});
+		// Any credential mutation (runtime/config keys, OAuth refresh) changes availability.
+		this.authStorage.onGenerationChanged(() => this.#invalidateAvailableModels());
 		// Load models synchronously in constructor
 		this.#loadModels();
 	}
@@ -1526,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,
 				});
 			}
 
@@ -2232,51 +2313,93 @@ export class ModelRegistry {
 			headers,
 			signal: AbortSignal.timeout(providerConfig.provider === "sglang" ? 500 : 250),
 			fetch: (input, init) => fetch(input, { ...init, redirect: "error" }),
-			throwOnStatus: response => new Error(`HTTP ${response.status} from ${baseUrl}/models`),
-			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,
+			throwOnStatus: response => {
+				const modelsUrl = redactDiscoveryUrl(`${baseUrl}/models`);
+				if (response.status === 401 || response.status === 403) {
+					// Redacted by construction: name the provider, endpoint, and the
+					// config surface to fix, never the resolved key.
+					return new Error(
+						`HTTP ${response.status} from ${modelsUrl}: provider "${providerConfig.provider}" credential was rejected for OpenAI models-list discovery; check providers.${providerConfig.provider}.apiKey/apiKeyEnv.`,
+					);
+				}
+				return new Error(`HTTP ${response.status} from ${modelsUrl}`);
+			},
+			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;
@@ -2434,6 +2557,9 @@ export class ModelRegistry {
 	}
 
 	#rebuildCanonicalIndex(): void {
+		// #models has already changed by the time a rebuild is requested; drop the
+		// availability cache even when the index rebuild itself is deferred.
+		this.#invalidateAvailableModels();
 		if (this.#rebuildSuspended > 0) {
 			this.#rebuildPending = true;
 			return;
@@ -2442,6 +2568,12 @@ export class ModelRegistry {
 		this.#rebuildPending = false;
 	}
 
+	#invalidateAvailableModels(): void {
+		this.#availableModelsCache = undefined;
+		this.#availableModelsDisabledProviders = undefined;
+		this.#availableModelsEnvFingerprint = undefined;
+	}
+
 	#suspendRebuild(): void {
 		this.#rebuildSuspended += 1;
 	}
@@ -2453,6 +2585,7 @@ export class ModelRegistry {
 		if (this.#rebuildSuspended === 0 && this.#rebuildPending) {
 			this.#rebuildPending = false;
 			this.#canonicalIndex = buildCanonicalModelIndex(this.#models, this.#equivalenceConfig);
+			this.#invalidateAvailableModels();
 		}
 	}
 
@@ -2503,8 +2636,10 @@ export class ModelRegistry {
 		return this.#models;
 	}
 
-	#isModelAvailable(model: Model<Api>): boolean {
-		const disabledProviders = getDisabledProviderIdsFromSettings();
+	#isModelAvailable(
+		model: Model<Api>,
+		disabledProviders: ReadonlySet<string> = getDisabledProviderIdsFromSettings(),
+	): boolean {
 		return (
 			!disabledProviders.has(model.provider) &&
 			(this.#keylessProviders.has(model.provider) || this.authStorage.hasAuth(model.provider))
@@ -2643,7 +2778,20 @@ export class ModelRegistry {
 	 * This is a fast check that doesn't refresh OAuth tokens.
 	 */
 	getAvailable(): Model<Api>[] {
-		return this.#models.filter(model => this.#isModelAvailable(model));
+		const disabledProviders = getDisabledProviderIdsFromSettings();
+		const disabledProviderKey = [...disabledProviders].sort().join("\u0000");
+		const envFingerprint = envAvailabilityFingerprint();
+		if (
+			this.#availableModelsCache &&
+			this.#availableModelsDisabledProviders === disabledProviderKey &&
+			this.#availableModelsEnvFingerprint === envFingerprint
+		) {
+			return this.#availableModelsCache;
+		}
+		this.#availableModelsCache = this.#models.filter(model => this.#isModelAvailable(model, disabledProviders));
+		this.#availableModelsDisabledProviders = disabledProviderKey;
+		this.#availableModelsEnvFingerprint = envFingerprint;
+		return this.#availableModelsCache;
 	}
 
 	/**

package/src/config/model-resolver.ts

@@ -355,7 +355,7 @@ function findExactCanonicalModelMatch(
 	modelReference: string,
 	availableModels: Model<Api>[],
 	modelRegistry: CanonicalModelRegistry | undefined,
-	_sessionId?: string,
+	sessionId?: string,
 ): Model<Api> | undefined {
 	if (!modelRegistry) {
 		return undefined;
@@ -367,6 +367,7 @@ function findExactCanonicalModelMatch(
 	return modelRegistry.resolveCanonicalModel?.(trimmedReference, {
 		availableOnly: false,
 		candidates: availableModels,
+		sessionId,
 	});
 }
 
@@ -378,7 +379,7 @@ function findExactEquivalentModelMatch(
 	modelReference: string,
 	availableModels: Model<Api>[],
 	modelRegistry: CanonicalModelRegistry | undefined,
-	_sessionId?: string,
+	sessionId?: string,
 ): Model<Api> | undefined {
 	if (!modelRegistry?.getCanonicalId || !modelRegistry.resolveCanonicalModel) return undefined;
 	const trimmedReference = modelReference.trim();
@@ -394,6 +395,7 @@ function findExactEquivalentModelMatch(
 	return modelRegistry.resolveCanonicalModel([...canonicalIds][0]!, {
 		availableOnly: false,
 		candidates: availableModels,
+		sessionId,
 	});
 }
 

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/deep-interview/SKILL.md

@@ -635,6 +635,18 @@ A transition occurs whenever the band changes versus the prior scored round —
 
 **Bookkeeping:** record each convened panel in `state.lateral_reviews` (round, milestone transition or pre-answer trigger, personas dispatched, findings folded). On panel spawn or validation failure, fall back silently to the normal generated question and increment `lateral_panel_failures`; do not expose tool noise unless it changes the next user-facing question. The panel is a prompt-budgeted assist layer — summarize oversized context before dispatch.
 
+### Per-question advisory fanout lanes (distinct from the milestone panel)
+
+Separate from the milestone-triggered lateral panel above, a lightweight **advisory fanout** may assist any single question the main session is about to synthesize or route — especially when the user is terse, uncertain, or would benefit from selectable options instead of another open-ended prompt. Adopted from ouroboros's ooo interview, the standard lanes are:
+
+- `code_context` — inspect repo-local facts and reuse existing exploration before asking the user.
+- `web_context` — browse/search only when current external facts genuinely affect the answer.
+- `ambiguity_contrarian` — find hidden assumptions, vague terms, missing decisions, and risky defaults.
+- `answer_simplifier` — turn the question into 2-3 easy choices or one concise draft answer.
+- `architecture_implications` — check whether the answer changes ownership, interfaces, rollout, or system shape.
+
+Advisory fanout is an assist layer, not a decision maker: it never replaces or delays the single user-facing question, never adds a second question, and never forwards a synthesized answer without the user's approval, edit, or explicit auto-confirm request. It differs from the milestone panel in trigger (per-question, not band-transition) and intent (help the human answer this one question). When both would fire on the same round, run the milestone panel and fold advisory lanes into the same single question. Runtimes without a parallel subagent primitive process lanes sequentially; on lane failure, fall back silently to the normal generated question.
+
 ## Phase 4: Crystallize Spec
 
 When ambiguity ≤ threshold (or hard cap / early exit):

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: