@gajae-code/coding-agent 0.10.1 → 0.11.0

package/dist/types/config/model-resolver.d.ts

@@ -4,9 +4,16 @@
 import { ThinkingLevel } from "@gajae-code/agent-core";
 import { type Api, type KnownProvider, type Model } from "@gajae-code/ai";
 import { type ModelRegistry, type ModelRole } from "./model-registry";
+import { type ModelSelectorValue } from "./model-selector-value";
 import type { Settings } from "./settings";
 /** Default model IDs for each known provider */
 export declare const defaultModelPerProvider: Record<KnownProvider, string>;
+/**
+ * Cursor's current RPC transport executes its exec protocol while streaming and
+ * has no client-side tool-call mode. Managed fallback attempts must not enable
+ * that irreversible path.
+ */
+export declare function managedCursorFallbackUnavailableReason(model: Model<Api>, selector: string): string | undefined;
 export interface ScopedModelSelection {
     model: Model<Api>;
     thinkingLevel?: ThinkingLevel;
@@ -61,10 +68,10 @@ export declare function parseModelPattern(pattern: string, availableModels: Mode
  * Expand a role alias like "pi/default" to the configured model string.
  */
 export declare function expandRoleAlias(value: string, settings?: Settings): string;
-export declare function resolveConfiguredModelPatterns(value: string | string[] | undefined, settings?: Settings): string[];
+export declare function resolveConfiguredModelPatterns(value: ModelSelectorValue | undefined, settings?: Settings): string[];
 export interface AgentModelPatternResolutionOptions {
-    settingsOverride?: string | string[];
-    agentModel?: string | string[];
+    settingsOverride?: ModelSelectorValue;
+    agentModel?: ModelSelectorValue;
     settings?: Settings;
     activeModelPattern?: string;
     fallbackModelPattern?: string;
@@ -79,12 +86,12 @@ export interface ResolvedModelRoleValue {
     explicitThinkingLevel: boolean;
     warning: string | undefined;
 }
-export declare function resolveModelRoleValue(roleValue: string | undefined, availableModels: Model<Api>[], options?: {
+export declare function resolveModelRoleValue(roleValue: ModelSelectorValue | undefined, availableModels: Model<Api>[], options?: {
     settings?: Settings;
     matchPreferences?: ModelMatchPreferences;
     modelRegistry?: CanonicalModelRegistry;
 }): ResolvedModelRoleValue;
-export declare function extractExplicitThinkingSelector(value: string | undefined, settings?: Settings): ThinkingLevel | undefined;
+export declare function extractExplicitThinkingSelector(value: ModelSelectorValue | undefined, settings?: Settings): ThinkingLevel | undefined;
 /**
  * Resolve a model identifier or pattern to a Model instance.
  */
@@ -107,6 +114,26 @@ export declare function resolveModelOverride(modelPatterns: string[], modelRegis
     thinkingLevel?: ThinkingLevel;
     explicitThinkingLevel: boolean;
 };
+/**
+ * Resolve a configured fallback chain to its first callable entry without
+ * charging requests. For retryable chains, consumers MUST pass
+ * `{ managedFallback: true }` so unsuitable entries (including Cursor's
+ * provider-side tool mode) fail closed during resolution before any request
+ * is attempted. Single-entry chains remain non-managed selections.
+ */
+export interface ModelChainResolutionOptions {
+    managedFallback?: boolean;
+}
+export declare function resolveModelChainWithAuth(modelPatterns: readonly string[], modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings, sessionId?: string, options?: ModelChainResolutionOptions): Promise<{
+    model?: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+    explicitThinkingLevel: boolean;
+    activeIndex: number;
+    skips: Array<{
+        selector: string;
+        reason: string;
+    }>;
+}>;
 /**
  * Resolve a list of override patterns to the first matching model, with an
  * auth-aware fallback to the parent session's active model.
@@ -128,13 +155,19 @@ export declare function resolveModelOverride(modelPatterns: string[], modelRegis
  * primary resolution unchanged so the existing error path still surfaces
  * a meaningful failure downstream.
  */
-export declare function resolveModelOverrideWithAuthFallback(modelPatterns: string[], parentActiveModelPattern: string | undefined, modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings, sessionId?: string): Promise<{
+export declare function resolveModelOverrideWithAuthFallback(modelPatterns: string[], parentActiveModelPattern: string | undefined, modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings, sessionId?: string, options?: ModelChainResolutionOptions): Promise<{
     model?: Model<Api>;
     thinkingLevel?: ThinkingLevel;
     explicitThinkingLevel: boolean;
     authFallbackUsed: boolean;
     requestedModel?: Model<Api>;
     fallbackReason?: "auth_unavailable";
+    activeIndex?: number;
+    parentFallbackSelector?: string;
+    skips: Array<{
+        selector: string;
+        reason: string;
+    }>;
 }>;
 /**
  * Resolve a list of role patterns to the first matching model.

package/dist/types/config/model-selector-value.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod/v4";
+/** A model selector or an ordered fallback chain of selectors. */
+export type ModelSelectorValue = string | readonly string[];
+/**
+ * Accept one validated selector or a non-empty ordered chain of validated selectors.
+ * Element schemas own each configuration surface's selector grammar.
+ */
+export declare function stringOrNonEmptyArray<T extends z.ZodType<string>>(elementSchema: T): z.ZodUnion<readonly [T, z.ZodArray<T>]>;
+/** Return whether a value is a non-blank selector or a non-empty selector chain. */
+export declare function isModelSelectorValue(value: unknown): value is ModelSelectorValue;
+/**
+ * Preserve compatibility with comma-delimited selector strings while flattening
+ * configured chains in their declared order.
+ */
+export declare function normalizeModelSelectorValue(value: ModelSelectorValue | undefined): string[];
+/** Return the first configured selector for consumers that need one selector. */
+export declare function selectorHead(value: ModelSelectorValue | undefined): string | undefined;

package/dist/types/config/models-config-schema.d.ts

@@ -62,6 +62,10 @@ export declare const OpenAICompatSchema: z.ZodObject<{
         none: "none";
     }>>;
 }, z.core.$strip>;
+export declare const ModelBindingsSchema: z.ZodObject<{
+    modelRoles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    agentModelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+}, z.core.$strip>;
 export declare const ProfileRoleSchema: z.ZodEnum<{
     architect: "architect";
     critic: "critic";
@@ -76,7 +80,7 @@ export declare const ProfileModelMappingSchema: z.ZodRecord<z.ZodEnum<{
     default: "default";
     executor: "executor";
     planner: "planner";
-}> & z.core.$partial, z.ZodString>;
+}> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 export declare const ProfileDefinitionSchema: z.ZodObject<{
     required_providers: z.ZodArray<z.ZodString>;
     display_name: z.ZodOptional<z.ZodString>;
@@ -86,7 +90,7 @@ export declare const ProfileDefinitionSchema: z.ZodObject<{
         default: "default";
         executor: "executor";
         planner: "planner";
-    }> & z.core.$partial, z.ZodString>;
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
 export declare const ProfilesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     required_providers: z.ZodArray<z.ZodString>;
@@ -97,7 +101,7 @@ export declare const ProfilesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         default: "default";
         executor: "executor";
         planner: "planner";
-    }> & z.core.$partial, z.ZodString>;
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>>;
 export declare const ModelOverrideSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
@@ -676,8 +680,8 @@ export declare const ModelsConfigSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
     modelBindings: z.ZodOptional<z.ZodObject<{
-        modelRoles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-        agentModelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        modelRoles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+        agentModelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
     }, z.core.$strip>>;
     equivalence: z.ZodOptional<z.ZodObject<{
         overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -692,7 +696,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
             default: "default";
             executor: "executor";
             planner: "planner";
-        }> & z.core.$partial, z.ZodString>;
+        }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type ModelsConfig = z.infer<typeof ModelsConfigSchema>;

package/dist/types/config/settings-schema.d.ts

@@ -1,4 +1,5 @@
 import type { Effort } from "@gajae-code/ai/model-thinking";
+import type { ModelSelectorValue } from "./model-selector-value";
 import { type SkillDiscoverySettings } from "./skill-settings-defaults";
 /** Unified settings schema - single source of truth for all settings.
  *
@@ -10,7 +11,7 @@ import { type SkillDiscoverySettings } from "./skill-settings-defaults";
  *   settings.get("compaction.enabled")  // => boolean
  *   settings.set("theme.dark", "red-claw")  // sync, saves in background
  */
-export type SettingTab = "appearance" | "model" | "interaction" | "context" | "memory" | "editing" | "tools" | "tasks" | "providers";
+export type SettingTab = "appearance" | "model" | "interaction" | "context" | "memory" | "editing" | "tools" | "tasks" | "providers" | "notifications";
 /** Tab display metadata - icon is resolved via theme.symbol() */
 export type TabMetadata = {
     label: string;
@@ -37,6 +38,11 @@ interface UiBase {
     description: string;
     /** Condition function name - setting only shown when true */
     condition?: string;
+    /**
+     * Persistence owner for settings which must not use the generic immediate
+     * settings-list write path.
+     */
+    editing?: "notification-atomic";
 }
 interface UiBoolean extends UiBase {
 }
@@ -91,9 +97,13 @@ interface ArrayDef<T> {
     };
     ui?: UiBase;
 }
+interface RecordValueDef {
+    type: "model-selector-value";
+}
 interface RecordDef<T> {
     type: "record";
     default: Record<string, T>;
+    valueSchema?: RecordValueDef;
     ui?: UiBase;
 }
 type SettingDef = BooleanDef | StringDef | NumberDef | EnumDef<readonly string[]> | ArrayDef<unknown> | RecordDef<unknown>;
@@ -130,13 +140,29 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "string";
         readonly default: undefined;
     };
+    readonly "notifications.telegram.activation": {
+        readonly type: "record";
+        readonly default: Record<string, unknown>;
+    };
     readonly "notifications.telegram.rich.enabled": {
         readonly type: "boolean";
         readonly default: true;
+        readonly ui: {
+            readonly tab: "notifications";
+            readonly label: "Telegram Rich Messages";
+            readonly description: "Format Telegram notifications with rich message content.";
+            readonly editing: "notification-atomic";
+        };
     };
     readonly "notifications.telegram.richDraft.enabled": {
         readonly type: "boolean";
         readonly default: false;
+        readonly ui: {
+            readonly tab: "notifications";
+            readonly label: "Telegram Rich Drafts";
+            readonly description: "Include rich draft updates in Telegram notifications.";
+            readonly editing: "notification-atomic";
+        };
     };
     readonly "notifications.telegram.topics.nameTemplate": {
         readonly type: "string";
@@ -146,7 +172,15 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "string";
         readonly default: undefined;
     };
-    readonly "notifications.discord.channelId": {
+    readonly "notifications.discord.applicationId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.discord.guildId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.discord.parentChannelId": {
         readonly type: "string";
         readonly default: undefined;
     };
@@ -154,23 +188,71 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "string";
         readonly default: undefined;
     };
+    readonly "notifications.slack.appToken": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
+    readonly "notifications.slack.workspaceId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
     readonly "notifications.slack.channelId": {
         readonly type: "string";
         readonly default: undefined;
     };
+    readonly "notifications.slack.authorizedUserId": {
+        readonly type: "string";
+        readonly default: undefined;
+    };
     readonly "notifications.redact": {
         readonly type: "boolean";
         readonly default: false;
+        readonly ui: {
+            readonly tab: "notifications";
+            readonly label: "Redact Notification Content";
+            readonly description: "Redact sensitive content before notifications are delivered.";
+            readonly editing: "notification-atomic";
+        };
     };
     readonly "notifications.verbosity": {
         readonly type: "string";
         readonly default: "lean";
         readonly validate: (value: string) => value is "lean" | "verbose";
+        readonly ui: {
+            readonly tab: "notifications";
+            readonly label: "Notification Verbosity";
+            readonly description: "Choose concise or detailed notification messages.";
+            readonly options: readonly [{
+                readonly value: "lean";
+                readonly label: "Lean";
+                readonly description: "Send concise notification messages";
+            }, {
+                readonly value: "verbose";
+                readonly label: "Verbose";
+                readonly description: "Send detailed notification messages";
+            }];
+            readonly editing: "notification-atomic";
+        };
     };
     readonly "notifications.sessionScope": {
         readonly type: "string";
         readonly default: "all";
         readonly validate: (value: string) => value is "all" | "primary";
+        readonly ui: {
+            readonly tab: "notifications";
+            readonly label: "Notification Session Scope";
+            readonly description: "Send notifications from all sessions or only the primary session.";
+            readonly options: readonly [{
+                readonly value: "all";
+                readonly label: "All Sessions";
+                readonly description: "Allow eligible sessions";
+            }, {
+                readonly value: "primary";
+                readonly label: "Primary Session";
+                readonly description: "Limit automatic notifications to the primary session";
+            }];
+            readonly editing: "notification-atomic";
+        };
     };
     readonly "notifications.daemon.idleTimeoutMs": {
         readonly type: "number";
@@ -285,7 +367,10 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly modelRoles: {
         readonly type: "record";
-        readonly default: Record<string, string>;
+        readonly default: Record<string, ModelSelectorValue>;
+        readonly valueSchema: {
+            readonly type: "model-selector-value";
+        };
     };
     readonly "modelProfile.default": {
         readonly type: "string";
@@ -1240,6 +1325,11 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "fallback.maxAttempts": {
+        readonly type: "number";
+        readonly default: 3;
+        readonly validate: (value: number) => boolean;
+    };
     readonly "retry.enabled": {
         readonly type: "boolean";
         readonly default: true;
@@ -2802,6 +2892,34 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Directory to save screenshots. If unset, screenshots go to a temp file. Supports ~. Examples: ~/Downloads, ~/Desktop, /sdcard/Download (Android)";
         };
     };
+    readonly "browser.profileReuse": {
+        readonly type: "string";
+        readonly default: "auto";
+        readonly validate: (value: string) => value is "auto" | "opt-in";
+        readonly ui: {
+            readonly tab: "tools";
+            readonly label: "Profile reuse posture";
+            readonly description: "'auto' (default): when a usable real Chrome profile is available, the browser tool uses an isolated copy of it (cookies/session/cache) for stronger stealth, warns, and falls back to synthetic. 'opt-in': stay synthetic unless a real profile is explicitly requested.";
+        };
+    };
+    readonly "browser.geo.timezone": {
+        readonly type: "string";
+        readonly default: undefined;
+        readonly ui: {
+            readonly tab: "tools";
+            readonly label: "Geo timezone override";
+            readonly description: "Optional IANA timezone (e.g. 'America/New_York') for headless sessions. Default unset preserves the real timezone. Only set this to a value coherent with your egress (e.g. a proxy region); an incoherent timezone increases bot detection.";
+        };
+    };
+    readonly "browser.geo.locale": {
+        readonly type: "string";
+        readonly default: undefined;
+        readonly ui: {
+            readonly tab: "tools";
+            readonly label: "Geo locale override";
+            readonly description: "Optional UI locale (e.g. 'en-US') for headless sessions. Default unset preserves the real locale. Only set this coherently with your egress region.";
+        };
+    };
     readonly "browser.gc.enabled": {
         readonly type: "boolean";
         readonly default: true;
@@ -3337,7 +3455,10 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "task.agentModelOverrides": {
         readonly type: "record";
-        readonly default: Record<string, string>;
+        readonly default: Record<string, ModelSelectorValue>;
+        readonly valueSchema: {
+            readonly type: "model-selector-value";
+        };
     };
     readonly "tasks.todoClearDelay": {
         readonly type: "number";
@@ -3909,13 +4030,19 @@ export interface NotificationsSettings {
     };
     discord: {
         botToken: string | undefined;
-        channelId: string | undefined;
+        applicationId: string | undefined;
+        guildId: string | undefined;
+        parentChannelId: string | undefined;
     };
     slack: {
         botToken: string | undefined;
+        appToken: string | undefined;
+        workspaceId: string | undefined;
         channelId: string | undefined;
     };
     redact: boolean;
+    verbosity: "lean" | "verbose";
+    sessionScope: "all" | "primary";
     daemon: {
         idleTimeoutMs: number;
     };
@@ -3934,7 +4061,7 @@ export interface GroupTypeMap {
     statusLine: StatusLineSettings;
     thinkingBudgets: ThinkingBudgetsSettings;
     stt: SttSettings;
-    modelRoles: Record<string, string>;
+    modelRoles: Record<string, ModelSelectorValue>;
     modelTags: ModelTagsSettings;
     cycleOrder: string[];
     shellMinimizer: ShellMinimizerSettings;

package/dist/types/config/settings.d.ts

@@ -1,19 +1,10 @@
-/**
- * Settings singleton with sync get/set and background persistence.
- *
- * Usage:
- *   import { settings } from "./settings";
- *
- *   const enabled = settings.get("compaction.enabled");  // sync read
- *   settings.set("theme.dark", "red-claw");              // sync write, saves in background
- *
- * For tests:
- *   const isolated = Settings.isolated({ "compaction.enabled": false });
- */
 import { procmgr } from "@gajae-code/utils";
 import type { ModelRole } from "../config/model-registry";
+import type { NotificationSettingsReader, NotificationSettingsSnapshot } from "../sdk/bus/config";
 import { AgentStorage } from "../session/agent-storage";
 import { type EditMode } from "../utils/edit-mode";
+import { type CasReceipt } from "./atomic-yaml-patch";
+import { type ModelSelectorValue } from "./model-selector-value";
 import { type BashInterceptorRule, type GroupPrefix, type GroupTypeMap, type SettingPath, type SettingValue } from "./settings-schema";
 export type * from "./settings-schema";
 export * from "./settings-schema";
@@ -21,6 +12,22 @@ export * from "./settings-schema";
 export interface RawSettings {
     [key: string]: unknown;
 }
+export type SettingsAtomicPatch = {
+    path: SettingPath;
+    op: "set";
+    value: unknown;
+} | {
+    path: SettingPath;
+    op: "unset";
+};
+export type SettingsAtomicReceipt = CasReceipt;
+export interface GlobalDefaultModelRoleCommit {
+    readonly previousDefault: ModelSelectorValue | undefined;
+    readonly previousModelRolesExisted: boolean;
+    readonly committedDefault: ModelSelectorValue | undefined;
+    readonly committedConfigVersion?: string;
+    readonly defaultRevision: number;
+}
 export interface SettingsOptions {
     /** Current working directory for project settings discovery */
     cwd?: string;
@@ -31,7 +38,17 @@ export interface SettingsOptions {
     /** Initial overrides */
     overrides?: Partial<Record<SettingPath, unknown>>;
 }
-export declare class Settings {
+/** Additional layer setup for {@link Settings.isolated}. */
+export interface IsolatedSettingsOptions {
+    /** Initial runtime overrides. Notification paths are rejected. */
+    overrides?: Partial<Record<SettingPath, unknown>>;
+}
+/** Raised when an ephemeral override attempts to change global-only notification settings. */
+export declare class NotificationSettingsOverrideError extends Error {
+    readonly path: SettingPath;
+    constructor(path: SettingPath);
+}
+export declare class Settings implements NotificationSettingsReader {
     #private;
     private constructor();
     /**
@@ -40,10 +57,10 @@ export declare class Settings {
      */
     static init(options?: SettingsOptions): Promise<Settings>;
     /**
-     * Create an isolated instance for testing.
+     * Create an isolated instance for testing with explicit user/global settings.
      * Does not affect the global singleton.
      */
-    static isolated(overrides?: Partial<Record<SettingPath, unknown>>): Settings;
+    static isolated(globalSettings?: Partial<Record<SettingPath, unknown>>, options?: IsolatedSettingsOptions): Settings;
     /**
      * Get the global singleton.
      * Throws if not initialized.
@@ -61,14 +78,32 @@ export declare class Settings {
      * activated by project-scoped config files.
      */
     getGlobal<P extends SettingPath>(path: P): SettingValue<P> | undefined;
+    /**
+     * Read the remote-notification settings from the user/global layer only.
+     * Schema defaults are applied per path; project settings and runtime overrides
+     * are deliberately excluded from this trust boundary.
+     */
+    getNotificationSettingsSnapshot(): NotificationSettingsSnapshot;
     /** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
     has(path: SettingPath): boolean;
     /**
      * Set a setting value (sync).
-     * Updates global settings and queues a background save.
-     * Triggers hooks for settings that have side effects.
+     * Updates global settings and reserves its background persistence slot before
+     * returning, so later durable batches cannot overtake this mutation.
      */
-    set<P extends SettingPath>(path: P, value: SettingValue<P>): void;
+    set<P extends SettingPath>(path: P, value: SettingValue<P> | undefined): void;
+    /**
+     * Delete a global setting (sync), rather than serializing an ambiguous YAML
+     * `undefined` value. Defaults/project settings become visible immediately.
+     */
+    unset<P extends SettingPath>(path: P): void;
+    /**
+     * Persist a tagged batch as one atomic YAML replacement. Unlike ordinary
+     * {@link set}, canonical state and hooks change only after the rename succeeds.
+     */
+    commitAtomicBatch(patches: readonly SettingsAtomicPatch[]): Promise<CasReceipt>;
+    /** Build a durable batch from the current on-disk YAML under the shared queue and file lock. */
+    commitAtomicBatchWithCurrent(buildPatches: (current: Readonly<RawSettings>) => Promise<readonly SettingsAtomicPatch[]> | readonly SettingsAtomicPatch[]): Promise<CasReceipt>;
     /**
      * Apply runtime overrides (not persisted).
      */
@@ -77,17 +112,9 @@ export declare class Settings {
      * Clear a runtime override.
      */
     clearOverride(path: SettingPath): void;
-    /**
-     * Flush any pending saves to disk.
-     * Call before exit to ensure all changes are persisted.
-     */
+    /** Flush a reserved debounced save without allowing it to be overtaken. */
     flush(): Promise<void>;
-    /**
-     * Like {@link flush}, but rejects if the durable save fails instead of
-     * swallowing the error. Use where the caller must confirm persistence before
-     * reporting success (e.g. the Telegram `/rich` toggle). In-memory instances
-     * ({@link isolated}) short-circuit in {@link #saveNow} and never throw.
-     */
+    /** Like {@link flush}, but reports a durable save failure to the caller. */
     flushOrThrow(): Promise<void>;
     cloneForCwd(cwd: string): Promise<Settings>;
     getStorage(): AgentStorage | null;
@@ -114,9 +141,10 @@ export declare class Settings {
     /**
      * Set a model role (helper for modelRoles record).
      */
-    setModelRole(role: ModelRole | string, modelId: string): void;
-    setGlobalModelRole(role: ModelRole | string, modelId: string | undefined): void;
-    setGlobalModelRoleAndFlush(role: ModelRole | string, modelId: string | undefined): Promise<void>;
+    setModelRole(role: ModelRole | string, modelId: ModelSelectorValue): void;
+    setGlobalModelRole(role: ModelRole | string, modelId: ModelSelectorValue | undefined): void;
+    setGlobalModelRoleAndFlush(role: ModelRole | string, modelId: ModelSelectorValue | undefined): Promise<GlobalDefaultModelRoleCommit>;
+    restoreGlobalDefaultModelRoleIfCurrent(commit: GlobalDefaultModelRoleCommit): Promise<boolean>;
     /**
      * Set an agent model override while keeping any live runtime override aligned.
      *
@@ -124,16 +152,16 @@ export declare class Settings {
      * session. A user-selected role assignment must win immediately in that same
      * session, but only the explicit agent change should be persisted.
      */
-    setAgentModelOverride(agentName: string, modelId: string): void;
+    setAgentModelOverride(agentName: string, modelId: ModelSelectorValue): void;
     /**
      * Get a model role (helper for modelRoles record).
      */
-    getModelRole(role: ModelRole | string): string | undefined;
+    getModelRole(role: ModelRole | string): ModelSelectorValue | undefined;
     /**
      * Get all model roles (helper for modelRoles record).
      */
-    getModelRoles(): ReadOnlyDict<string>;
-    overrideModelRoles(roles: ReadOnlyDict<string>): void;
+    getModelRoles(): Readonly<Record<string, ModelSelectorValue>>;
+    overrideModelRoles(roles: Readonly<Record<string, ModelSelectorValue>>): void;
     /**
      * Set disabled providers (for compatibility with discovery system).
      */

package/dist/types/coordinator-mcp/model-preset.d.ts

@@ -1,11 +1,12 @@
-import { type ModelProfileDefinition } from "../config/model-profiles";
+export interface CoordinatorModelProfile {
+    name: string;
+}
 /**
- * Loads the merged built-in + custom model-profile registry the way the `gjc`
- * 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.
+ * Loads the merged built-in + custom model-profile names from `models.yml`
+ * without loading the session-host model registry. The child still owns
+ * profile activation; this validates the selection before session creation.
  */
-export type CoordinatorModelProfileLoader = () => Map<string, ModelProfileDefinition> | Promise<Map<string, ModelProfileDefinition>>;
+export type CoordinatorModelProfileLoader = () => Map<string, CoordinatorModelProfile> | Promise<Map<string, CoordinatorModelProfile>>;
 /**
  * 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