@sayknow-cli/coding-agent 0.3.11 → 0.3.13

package/src/commands/launch.ts

@@ -15,17 +15,22 @@ import { prepareLaunchWorktree } from "../skc-runtime/launch-worktree";
 import {
 	SKC_COORDINATOR_SESSION_ID_ENV,
 	SKC_COORDINATOR_SESSION_STATE_FILE_ENV,
+	SKC_TMUX_OWNER_GENERATION_ENV,
 } from "../skc-runtime/session-state-sidecar";
 
-async function persistCoordinatorLaunchFailure(error: unknown, cwd: string): Promise<void> {
-	const stateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+export async function persistCoordinatorLaunchFailure(
+	error: unknown,
+	cwd: string,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+	const stateFile = env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
 	if (!stateFile) return;
 	const message = error instanceof Error ? error.message : String(error);
 	const code = message.split(":", 1)[0] || "launch_failed";
 	const now = new Date().toISOString();
 	const payload = {
 		schema_version: 1,
-		session_id: process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || null,
+		session_id: env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || null,
 		state: "errored",
 		ready_for_input: false,
 		updated_at: now,
@@ -45,6 +50,9 @@ async function persistCoordinatorLaunchFailure(error: unknown, cwd: string): Pro
 			truncated: false,
 		},
 		error: { code, message, recoverable: true },
+		...(env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim()
+			? { owner_generation: env[SKC_TMUX_OWNER_GENERATION_ENV] ?? null }
+			: {}),
 	};
 	await fs.mkdir(path.dirname(stateFile), { recursive: true });
 	await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);

package/src/commands/mcp.ts

@@ -1,5 +1,5 @@
 /**
- * Direct MCP server registration for standalone SKC.
+ * Explicit MCP server config storage for standalone SKC.
  */
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
 import { type MCPAction, type MCPCommandArgs, runMCPCommand } from "../cli/mcp-cli";
@@ -7,7 +7,7 @@ import { type MCPAction, type MCPCommandArgs, runMCPCommand } from "../cli/mcp-c
 const ACTIONS: MCPAction[] = ["add", "list", "remove"];
 
 export default class MCP extends Command {
-	static description = "Register standalone MCP servers explicitly in SKC config";
+	static description = "Store standalone MCP server definitions without loading them at runtime";
 	static delegateHelp = true;
 
 	static examples = [
@@ -81,15 +81,15 @@ export default class MCP extends Command {
 	}
 
 	private printHelp(): void {
-		process.stdout.write(`Register standalone MCP servers explicitly in SKC config
+		process.stdout.write(`Store standalone MCP server definitions in SKC config without loading them at runtime
 
 USAGE
   $ skc mcp [add|list|remove] [NAME] [COMMAND_OR_URL] [ARGS...] [FLAGS]
 
 COMMANDS
-  add     Add an explicit user-provided MCP server definition
-  list    List registered servers with env/header/auth values redacted
-  remove  Remove a registered server and print the removed definition redacted
+  add     Store an explicit user-provided MCP server definition
+  list    List stored servers with env/header/auth values redacted
+  remove  Remove a stored server and print the removed definition redacted
 
 FLAGS
       --project          Use project scope (./.skc/mcp.json) instead of user scope
@@ -110,8 +110,8 @@ EXAMPLES
   $ skc mcp list --json
   $ skc mcp remove context7
 
-SECURITY
-  This command writes only the server definition supplied on this invocation. It does not import or inherit Claude Code, Codex, OpenCode, or other live MCP configs. Public output redacts env, header, auth, and OAuth credential values.
+STORAGE/RUNTIME
+  This command stores only the server definition supplied on this invocation. It does not import or inherit Claude Code, Codex, OpenCode, or other live MCP configs. Normal standalone skc sessions do not load stored MCP registrations today. Public output redacts env, header, auth, and OAuth credential values.
 `);
 	}
 }

package/src/commands/notify.ts

@@ -5,7 +5,7 @@ import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
 import { type NotifyAction, type NotifyCommandArgs, runNotifyCliCommand } from "../cli/notify-cli";
 import { initTheme } from "../modes/theme/theme";
 
-const ACTIONS: NotifyAction[] = ["setup", "status", "daemon-internal"];
+const ACTIONS: NotifyAction[] = ["setup", "status", "health", "test", "recovery", "daemon-internal"];
 
 export default class Notify extends Command {
 	static description = "Configure Telegram notifications";
@@ -28,6 +28,8 @@ export default class Notify extends Command {
 		token: Flags.string({ description: "Telegram bot token (non-interactive setup)" }),
 		"chat-id": Flags.string({ description: "Telegram chat id to pair (non-interactive setup)" }),
 		redact: Flags.boolean({ description: "Enable redaction of remote notification content" }),
+		probe: Flags.boolean({ description: "notify health: probe Telegram reachability (getMe)" }),
+		message: Flags.string({ description: "notify test: custom message body" }),
 		"owner-id": Flags.string({ description: "Internal: daemon owner id" }),
 		"agent-dir": Flags.string({ description: "Internal: agent dir for the daemon" }),
 	};
@@ -53,6 +55,8 @@ export default class Notify extends Command {
 			token: flags.token as string | undefined,
 			chatId: (flags as Record<string, unknown>)["chat-id"] as string | undefined,
 			redact: Boolean(flags.redact),
+			probe: Boolean(flags.probe),
+			message: flags.message as string | undefined,
 		};
 
 		if (action !== "daemon-internal") await initTheme();

package/src/commands/session.ts

@@ -145,7 +145,12 @@ export default class Session extends Command {
 			}
 
 			if (action === "force-close" || action === "force-remove") {
-				const closed = forceCloseSkcTmuxSession(sessionName, process.env, flags["session-id"], flags["state-file"]);
+				const closed = await forceCloseSkcTmuxSession(
+					sessionName,
+					process.env,
+					flags["session-id"],
+					flags["state-file"],
+				);
 				if (json) {
 					writeJson({ ok: true, session: sessionJson(closed) });
 					return;

package/src/commands/stats.ts

@@ -2,8 +2,7 @@
  * View usage statistics dashboard.
  */
 import { Command, Flags } from "@sayknow-cli/utils/cli";
-import { runStatsCommand, type StatsCommandArgs } from "../cli/stats-cli";
-import { initTheme } from "../modes/theme/theme";
+import type { StatsCommandArgs } from "../cli/stats-cli";
 
 export default class Stats extends Command {
 	static description = "View usage statistics";
@@ -23,6 +22,11 @@ export default class Stats extends Command {
 			summary: flags.summary,
 		};
 
+		const [{ initTheme }, { runStatsCommand }] = await Promise.all([
+			import("../modes/theme/theme"),
+			import("../cli/stats-cli"),
+		]);
+
 		await initTheme();
 		await runStatsCommand(cmd);
 	}

package/src/config/keybindings.ts

@@ -52,6 +52,7 @@ interface AppKeybindings {
 	"app.plan.toggle": true;
 	"app.history.search": true;
 	"app.stt.toggle": true;
+	"app.irc.sidebar.toggle": true;
 }
 
 export type AppKeybinding = keyof AppKeybindings;
@@ -188,11 +189,11 @@ export const KEYBINDINGS = {
 	},
 	"app.session.delete": {
 		defaultKeys: "ctrl+d",
-		description: "Delete session",
+		description: "Delete current session transcript/artifacts",
 	},
 	"app.session.deleteNoninvasive": {
 		defaultKeys: "ctrl+backspace",
-		description: "Delete session (non-invasive)",
+		description: "Delete selected session transcript/artifacts (non-invasive)",
 	},
 	"app.tree.foldOrUp": {
 		defaultKeys: ["ctrl+left", "alt+left"],
@@ -214,6 +215,10 @@ export const KEYBINDINGS = {
 		defaultKeys: "alt+h",
 		description: "Toggle speech-to-text",
 	},
+	"app.irc.sidebar.toggle": {
+		defaultKeys: "alt+i",
+		description: "Toggle IRC sidebar",
+	},
 } as const satisfies KeybindingDefinitions;
 
 /**

package/src/config/mcp-schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/jaybeyond/Sayknow_CLI/main/packages/coding-agent/src/config/mcp-schema.json",
   "title": "SKC MCP configuration",
-  "description": "Schema for mcp.json, .mcp.json, .skc/mcp.json, and ~/.skc/agent/mcp.json used by the SKC coding agent.",
+  "description": "Schema for stored MCP server definitions in mcp.json, .mcp.json, .skc/mcp.json, and ~/.skc/agent/mcp.json. Normal standalone skc sessions do not consume skc mcp registrations as runtime tools today.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -12,7 +12,7 @@
     },
     "mcpServers": {
       "type": "object",
-      "description": "Map of MCP server name to server configuration.",
+      "description": "Map of MCP server name to stored server configuration.",
       "propertyNames": {
         "pattern": "^[a-zA-Z0-9_.-]{1,100}$"
       },
@@ -22,7 +22,7 @@
     },
     "disabledServers": {
       "type": "array",
-      "description": "User-level denylist for disabling discovered servers by name.",
+      "description": "Denylist for explicit runtime MCP consumers that load discovered or stored servers by name.",
       "items": {
         "type": "string",
         "minLength": 1
@@ -94,11 +94,11 @@
       "properties": {
         "enabled": {
           "type": "boolean",
-          "description": "Whether SKC should try to connect this server."
+          "description": "Whether explicit runtime MCP consumers should try to connect this server."
         },
         "autoload": {
           "type": "boolean",
-          "description": "Whether to connect this server automatically at session startup (default: true). When false the server stays configured until connected explicitly (e.g. /mcp connect <name>)."
+          "description": "Whether an explicit runtime MCP consumer should connect this server automatically when that consumer starts (default: true). Normal standalone skc, skc --tmux, and print-mode sessions do not consume skc mcp registrations today; false keeps the server configured for consumers that support explicit connection."
         },
         "timeout": {
           "type": "number",
@@ -114,13 +114,13 @@
       }
     },
     "stdioServer": {
+      "type": "object",
+      "unevaluatedProperties": false,
       "allOf": [
         {
           "$ref": "#/$defs/serverBase"
         },
         {
-          "type": "object",
-          "additionalProperties": false,
           "required": ["command"],
           "properties": {
             "type": {
@@ -138,11 +138,15 @@
               "items": {
                 "type": "string"
               },
-              "description": "Arguments passed to the stdio server process."
+              "description": "Arguments passed to the stdio server process. Public CLI output redacts sensitive-looking argument values."
             },
             "env": {
               "$ref": "#/$defs/stringMap",
-              "description": "Environment variables passed to the stdio process."
+              "description": "Environment variables passed to the stdio process. Public CLI output redacts values."
+            },
+            "noInheritEnv": {
+              "type": "boolean",
+              "description": "When true, explicit runtime consumers should avoid inheriting the host environment and pass only a minimal allowlist plus explicit env keys."
             },
             "cwd": {
               "type": "string",
@@ -156,13 +160,13 @@
       ]
     },
     "httpServer": {
+      "type": "object",
+      "unevaluatedProperties": false,
       "allOf": [
         {
           "$ref": "#/$defs/serverBase"
         },
         {
-          "type": "object",
-          "additionalProperties": false,
           "required": ["type", "url"],
           "properties": {
             "type": {
@@ -173,11 +177,11 @@
             "url": {
               "type": "string",
               "minLength": 1,
-              "description": "MCP endpoint URL."
+              "description": "MCP endpoint URL. Public CLI output redacts userinfo, query values, and fragments."
             },
             "headers": {
               "$ref": "#/$defs/stringMap",
-              "description": "HTTP headers sent with MCP requests."
+              "description": "HTTP headers sent with MCP requests. Public CLI output redacts values."
             }
           },
           "not": {
@@ -187,13 +191,13 @@
       ]
     },
     "sseServer": {
+      "type": "object",
+      "unevaluatedProperties": false,
       "allOf": [
         {
           "$ref": "#/$defs/serverBase"
         },
         {
-          "type": "object",
-          "additionalProperties": false,
           "required": ["type", "url"],
           "properties": {
             "type": {
@@ -204,11 +208,11 @@
             "url": {
               "type": "string",
               "minLength": 1,
-              "description": "Legacy SSE endpoint URL."
+              "description": "Legacy SSE endpoint URL. Public CLI output redacts userinfo, query values, and fragments."
             },
             "headers": {
               "$ref": "#/$defs/stringMap",
-              "description": "HTTP headers sent with the SSE transport."
+              "description": "HTTP headers sent with the SSE transport. Public CLI output redacts values."
             }
           },
           "not": {

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

@@ -181,7 +181,7 @@ export function formatModelProfileCredentialError(profileName: string, providers
 	return `Model profile "${profileName}" requires credentials for: ${providers.join(", ")}. Run /login and configure the missing provider(s), then retry.`;
 }
 
-function resolveModelProfileName(profileName: string, profiles: ReadonlyMap<string, unknown>): string {
+export function resolveModelProfileName(profileName: string, profiles: ReadonlyMap<string, unknown>): string {
 	// A retired-name alias is fallback-only: never shadow a profile that actually
 	// exists under the requested name (e.g. a user-defined `codex-standard`).
 	if (profiles.has(profileName)) return profileName;

package/src/config/model-profiles.ts

@@ -70,25 +70,25 @@ const profile = (
 
 export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 	profile("codex-eco", ["openai-codex"], {
-		default: "openai-codex/gpt-5.5:low",
-		executor: "openai-codex/gpt-5.5:minimal",
-		planner: "openai-codex/gpt-5.5:low",
-		critic: "openai-codex/gpt-5.5:medium",
-		architect: "openai-codex/gpt-5.5:high",
+		default: "openai-codex/gpt-5.6-terra:high",
+		executor: "openai-codex/gpt-5.6-luna:high",
+		planner: "openai-codex/gpt-5.6-terra:medium",
+		critic: "openai-codex/gpt-5.6-terra:high",
+		architect: "openai-codex/gpt-5.6-sol:medium",
 	}),
 	profile("codex-medium", ["openai-codex"], {
-		default: "openai-codex/gpt-5.5:medium",
-		executor: "openai-codex/gpt-5.5:low",
-		planner: "openai-codex/gpt-5.5:medium",
-		critic: "openai-codex/gpt-5.5:high",
-		architect: "openai-codex/gpt-5.5:xhigh",
+		default: "openai-codex/gpt-5.6-sol:medium",
+		executor: "openai-codex/gpt-5.6-terra:xhigh",
+		planner: "openai-codex/gpt-5.6-terra:high",
+		critic: "openai-codex/gpt-5.6-terra:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:high",
 	}),
 	profile("codex-pro", ["openai-codex"], {
-		default: "openai-codex/gpt-5.5:xhigh",
-		executor: "openai-codex/gpt-5.5:medium",
-		planner: "openai-codex/gpt-5.5:high",
-		critic: "openai-codex/gpt-5.5:xhigh",
-		architect: "openai-codex/gpt-5.5:xhigh",
+		default: "openai-codex/gpt-5.6-sol:xhigh",
+		executor: "openai-codex/gpt-5.6-terra:xhigh",
+		planner: "openai-codex/gpt-5.6-sol:high",
+		critic: "openai-codex/gpt-5.6-sol:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:max",
 	}),
 	profile("opencodego", ["opencode-go"], {
 		default: "opencode-go/kimi-k2.6",
@@ -256,24 +256,24 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 	}),
 	profile("opus-codex", ["anthropic", "openai-codex"], {
 		default: "anthropic/claude-opus-4-8:xhigh",
-		executor: "openai-codex/gpt-5.5:low",
-		planner: "openai-codex/gpt-5.5:medium",
-		critic: "openai-codex/gpt-5.5:high",
-		architect: "openai-codex/gpt-5.5:xhigh",
+		executor: "openai-codex/gpt-5.6-terra:xhigh",
+		planner: "openai-codex/gpt-5.6-terra:high",
+		critic: "openai-codex/gpt-5.6-terra:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:xhigh",
 	}),
 	profile("codex-opencodego", ["openai-codex", "opencode-go"], {
-		default: "openai-codex/gpt-5.5:medium",
+		default: "openai-codex/gpt-5.6-terra:xhigh",
 		executor: "opencode-go/deepseek-v4-pro",
 		planner: "opencode-go/kimi-k2.6",
 		critic: "opencode-go/mimo-v2.5-pro",
-		architect: "openai-codex/gpt-5.5:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:xhigh",
 	}),
 	profile("fable-opus-codex", ["anthropic", "openai-codex"], {
 		default: "anthropic/claude-fable-5:high",
-		executor: "openai-codex/gpt-5.5:high",
+		executor: "openai-codex/gpt-5.6-terra:xhigh",
 		planner: "anthropic/claude-opus-4-8:medium",
 		critic: "anthropic/claude-opus-4-8:high",
-		architect: "openai-codex/gpt-5.5:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:xhigh",
 	}),
 ];
 

package/src/config/settings-schema.ts

@@ -1,4 +1,5 @@
 import type { Effort } from "@sayknow-cli/ai/model-thinking";
+import { PET_MODE_IDS, PET_SKIN_IDS, PET_SKINS } from "@sayknow-cli/tui/components/sayknow-pet";
 import { TASK_SIMPLE_MODES } from "../task/simple-mode";
 import { getThinkingLevelMetadata } from "../thinking-metadata";
 import { EDIT_MODES } from "../utils/edit-mode";
@@ -265,6 +266,7 @@ export const SETTINGS_SCHEMA = {
 	"notifications.telegram.chatId": { type: "string", default: undefined },
 	"notifications.telegram.rich.enabled": { type: "boolean", default: true },
 	"notifications.telegram.richDraft.enabled": { type: "boolean", default: false },
+	"notifications.telegram.topics.nameTemplate": { type: "string", default: undefined },
 	"notifications.discord.botToken": { type: "string", default: undefined },
 	"notifications.discord.channelId": { type: "string", default: undefined },
 	"notifications.slack.botToken": { type: "string", default: undefined },
@@ -275,6 +277,11 @@ export const SETTINGS_SCHEMA = {
 		default: "lean",
 		validate: (value: string) => value === "lean" || value === "verbose",
 	},
+	"notifications.sessionScope": {
+		type: "string",
+		default: "all",
+		validate: (value: string) => value === "all" || value === "primary",
+	},
 	"notifications.daemon.idleTimeoutMs": {
 		type: "number",
 		default: 60000,
@@ -535,6 +542,25 @@ export const SETTINGS_SCHEMA = {
 			description: "Use the session name color for the editor border and status line gap",
 		},
 	},
+
+	"pet.mode": {
+		type: "enum",
+		values: PET_MODE_IDS,
+		default: "off",
+		ui: {
+			tab: "appearance",
+			label: "Sayknow Pet",
+			description: "16x16 real-pixel sayknow living beside the composer (sixel/kitty terminals)",
+			options: [
+				{ value: "off", label: "Off", description: "No pet" },
+				...PET_SKIN_IDS.map(id => ({
+					value: id,
+					label: PET_SKINS[id].label,
+					description: PET_SKINS[id].description,
+				})),
+			],
+		},
+	},
 	"statusLine.maxRows": {
 		type: "number",
 		default: 1,
@@ -1249,7 +1275,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "interaction",
 			label: "Check for Updates",
-			description: "If false, skip update check",
+			description:
+				"At interactive startup, notify of newer versions; never install. Use `skc update` only for recognized Bun global, Windows npm, or bundled-installer binaries; source, linked, and unrecognized installs use their original method.",
 		},
 	},
 
@@ -2189,6 +2216,16 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"irc.sidebar.enabled": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "tools",
+			label: "IRC Sidebar",
+			description: "Enable the IRC message sidebar (opens with the toggle key; starts closed)",
+		},
+	},
+
 	// Optional tools
 
 	"renderMermaid.enabled": {
@@ -3619,6 +3656,9 @@ export interface NotificationsSettings {
 		richDraft: {
 			enabled: boolean;
 		};
+		topics: {
+			nameTemplate: string | undefined;
+		};
 	};
 	discord: {
 		botToken: string | undefined;

package/src/coordinator-mcp/model-preset.ts

@@ -0,0 +1,100 @@
+import * as path from "node:path";
+import { getAgentDir } from "@sayknow-cli/utils";
+import { resolveModelProfileName } from "../config/model-profile-activation";
+import { type ModelProfileDefinition, mergeModelProfiles } from "../config/model-profiles";
+import { ModelsConfigFile } from "../config/model-registry";
+
+/**
+ * Loads the merged built-in + custom model-profile registry the way the `skc`
+ * CLI resolves `--mpreset`, so coordinator MCP launches select the same
+ * authoritative profile the spawned child will activate. Custom profiles live
+ * in the shared models config, which the child inherits, so both sides agree.
+ */
+export type CoordinatorModelProfileLoader = () =>
+	| Map<string, ModelProfileDefinition>
+	| Promise<Map<string, ModelProfileDefinition>>;
+
+const MAX_ECHOED_MPRESET_LENGTH = 128;
+
+/**
+ * Thrown by the default loader when `models.yml` exists but is invalid or
+ * unreadable. This lets the resolver fail closed with a distinct, stable reason
+ * instead of silently collapsing a broken registry to the built-ins-only set
+ * (which would misreport a caller's valid custom profile as unknown).
+ */
+export class CoordinatorModelProfileRegistryError extends Error {
+	constructor(cause?: unknown) {
+		super("coordinator_model_profile_registry_error");
+		this.name = "CoordinatorModelProfileRegistryError";
+		if (cause !== undefined) (this as { cause?: unknown }).cause = cause;
+	}
+}
+
+export const loadCoordinatorModelProfiles: CoordinatorModelProfileLoader = () => {
+	const configFile = ModelsConfigFile.relocate(path.join(getAgentDir(), "models.yml"));
+	configFile.invalidate();
+	const loaded = configFile.tryLoad();
+	// A present-but-invalid config must fail closed; absence (`value` undefined
+	// with a non-error status) is fine and yields the built-in profiles only.
+	if (loaded.status === "error") throw new CoordinatorModelProfileRegistryError(loaded.error);
+	return mergeModelProfiles(loaded.value?.profiles);
+};
+
+function sortedProfileNames(profiles: ReadonlyMap<string, ModelProfileDefinition>): string[] {
+	return [...profiles.keys()].sort((left, right) => left.localeCompare(right));
+}
+
+export type CoordinatorMpresetResolution =
+	| { ok: true; mpreset: string | null }
+	| { ok: false; reason: "unknown_model_profile"; mpreset: string; available_profiles: string[] }
+	| { ok: false; reason: "model_profile_registry_error"; mpreset: string; available_profiles: string[] };
+
+/**
+ * Resolve a coordinator `mpreset` argument against the merged profile registry.
+ *
+ * Only an absent (`undefined`/`null`) value is a no-op (`mpreset: null`); an
+ * explicit empty/whitespace string is a caller error and is rejected rather
+ * than silently launching at the default tier. Legacy aliases are canonicalized
+ * exactly like the CLI (e.g. `codex-standard` -> `codex-medium`) so coordinator
+ * selection stays in parity with `skc --mpreset <profile>`; the resolved value
+ * is the canonical profile name. Unknown names are rejected with the
+ * available-profile listing and never reach a spawned child command, and a
+ * broken registry fails closed with `model_profile_registry_error`.
+ */
+export async function resolveCoordinatorMpreset(
+	raw: unknown,
+	loadProfiles: CoordinatorModelProfileLoader,
+): Promise<CoordinatorMpresetResolution> {
+	if (raw === undefined || raw === null) return { ok: true, mpreset: null };
+	const requested = typeof raw === "string" ? raw.trim() : "";
+	const echoed = requested.slice(0, MAX_ECHOED_MPRESET_LENGTH);
+	let profiles: Map<string, ModelProfileDefinition>;
+	try {
+		profiles = await loadProfiles();
+	} catch (error) {
+		if (error instanceof CoordinatorModelProfileRegistryError) {
+			return { ok: false, reason: "model_profile_registry_error", mpreset: echoed, available_profiles: [] };
+		}
+		throw error;
+	}
+	// Non-string input and explicit blank/whitespace strings can never name a
+	// profile; only absent/null (handled above) means "no selection".
+	if (typeof raw !== "string" || requested.length === 0) {
+		return {
+			ok: false,
+			reason: "unknown_model_profile",
+			mpreset: echoed,
+			available_profiles: sortedProfileNames(profiles),
+		};
+	}
+	const canonical = resolveModelProfileName(requested, profiles);
+	if (!profiles.has(canonical)) {
+		return {
+			ok: false,
+			reason: "unknown_model_profile",
+			mpreset: echoed,
+			available_profiles: sortedProfileNames(profiles),
+		};
+	}
+	return { ok: true, mpreset: canonical };
+}