@aragon-agent/cli 0.6.34 → 0.6.35

package/dist/agent/controller.d.ts

@@ -1,4 +1,6 @@
 import { type ModelSettingsSnapshot } from './model-profile-settings.js';
+import { type ActiveKit } from '../config/kit-resolution.js';
+import type { KitApplyResult } from '../config/model-kits.js';
 import type { ModelSettingsDraft, ModelSettingsPatch, ModelSettingsSaveResult } from '../config/model-profile-store.js';
 import { type CompactionIdentity } from '../compaction/memory-identity.js';
 /**
@@ -629,6 +631,33 @@ export declare class AgentController {
     saveModelSettingsPatch(patch: ModelSettingsPatch): ModelSettingsSaveResult;
     /** Refresh both role connections and credentials while retaining conversation state. */
     reloadModelSettings(): ModelSettingsSaveResult;
+    /**
+     * The narrow port `agent/kit-apply.ts` runs against (agent-model-kits §6.3).
+     *
+     * A LITERAL ADAPTER RATHER THAN `this`: the port's member names (`isBusy`,
+     * `hasKey`, `preview`) are deliberately NOT the controller's names, because a
+     * port that shadows a public method is one signature change away from silently
+     * calling itself. Three of the five members are one-liners onto existing
+     * methods; nothing here is new state.
+     */
+    private kitApplyPort;
+    /**
+     * Apply a kit for THIS SESSION ONLY (D-7 / I-5): no commit, ever.
+     *
+     * Failed applies leave the live config and the file untouched (I-10), because
+     * the whole operation is one prepare-and-apply with no commit in between.
+     */
+    applySessionKit(kitId: string): KitApplyResult;
+    /** Release the session kit and return to the config file's bindings (RV-P1-6). */
+    clearSessionKit(): KitApplyResult;
+    /**
+     * Which kit is in effect right now (session > default > disk bindings).
+     *
+     * DERIVED, never stored (D-5): the header chip, the settings root row and
+     * `/kit` all read this, so there is exactly one answer to "which preset am I
+     * running" and no copy of it that can drift.
+     */
+    getActiveKit(): ActiveKit;
     /** Prebuild all potentially failing model/prompt work before committing the file. */
     prepareModelSettingsSnapshot(config: CliConfig): ModelSettingsSnapshot;
     /** Apply prepared state synchronously, without rebuilding the controller or its history. */

package/dist/agent/controller.js

@@ -1,4 +1,6 @@
-import { createModelSettingsDraft, saveModelSettings, reloadModelSettings, } from './model-profile-settings.js';
+import { createModelSettingsDraft, previewModelSettings, saveModelSettings, reloadModelSettings, } from './model-profile-settings.js';
+import { applySessionKit as applySessionKitPort, clearSessionKit as clearSessionKitPort } from './kit-apply.js';
+import { resolveActiveKit } from '../config/kit-resolution.js';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { verifyCompactionIdentity } from '../compaction/memory-identity.js';
@@ -1680,6 +1682,45 @@ export class AgentController {
     }
     /** Refresh both role connections and credentials while retaining conversation state. */
     reloadModelSettings() { return reloadModelSettings(this); }
+    /**
+     * The narrow port `agent/kit-apply.ts` runs against (agent-model-kits §6.3).
+     *
+     * A LITERAL ADAPTER RATHER THAN `this`: the port's member names (`isBusy`,
+     * `hasKey`, `preview`) are deliberately NOT the controller's names, because a
+     * port that shadows a public method is one signature change away from silently
+     * calling itself. Three of the five members are one-liners onto existing
+     * methods; nothing here is new state.
+     */
+    kitApplyPort() {
+        return {
+            getConfig: () => this.config,
+            isBusy: () => this.isModelSettingsBusy(),
+            hasKey: (providerId, role) => this.hasApiKey(providerId, role),
+            createDraft: () => this.createModelSettingsDraft(),
+            preview: (draft) => previewModelSettings(draft, this),
+        };
+    }
+    /**
+     * Apply a kit for THIS SESSION ONLY (D-7 / I-5): no commit, ever.
+     *
+     * Failed applies leave the live config and the file untouched (I-10), because
+     * the whole operation is one prepare-and-apply with no commit in between.
+     */
+    applySessionKit(kitId) {
+        return applySessionKitPort({ kitId, port: this.kitApplyPort() });
+    }
+    /** Release the session kit and return to the config file's bindings (RV-P1-6). */
+    clearSessionKit() {
+        return clearSessionKitPort(this.kitApplyPort());
+    }
+    /**
+     * Which kit is in effect right now (session > default > disk bindings).
+     *
+     * DERIVED, never stored (D-5): the header chip, the settings root row and
+     * `/kit` all read this, so there is exactly one answer to "which preset am I
+     * running" and no copy of it that can drift.
+     */
+    getActiveKit() { return resolveActiveKit(this.config); }
     /** Prebuild all potentially failing model/prompt work before committing the file. */
     prepareModelSettingsSnapshot(config) {
         return { config, model: { providerId: config.provider, modelId: config.model,

package/dist/agent/kit-apply.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The session exit: apply a kit WITHOUT writing the config file (§4.2 exit B).
+ *
+ * ASCII ONLY - `src/agent/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A NARROW PORT AND NOT THE CONTROLLER: the same reason
+ * `ModelSettingsController` exists next door - a five-method port can be stubbed
+ * by one object literal in a test, so every refusal code is reachable without a
+ * controller, a provider, or a disk. The controller supplies the real one.
+ *
+ * EVERY PATH EITHER APPLIES OR CHANGES NOTHING (I-10). There is no partial state
+ * to clean up, because the whole thing is one `preview` call: the reused prepare
+ * chain builds the snapshot before it touches the live config, exactly as a save
+ * does - only the commit is missing.
+ */
+import type { CliConfig } from '../config/schema.js';
+import type { ModelSettingsDraft, ModelSettingsSaveResult } from '../config/model-profile-store.js';
+import type { HasApiKey } from '../team/model.js';
+import { type KitApplyResult, type KitNote } from '../config/model-kits.js';
+export interface KitApplyPort {
+    getConfig(): CliConfig;
+    /** `controller.isModelSettingsBusy` - a run, a team, a review, a compaction. */
+    isBusy(): boolean;
+    /** `controller.hasApiKey`: two-parameter form, so a role-scoped key is seen. */
+    hasKey: HasApiKey;
+    /** `controller.createModelSettingsDraft`: already seeded with `sessionKit`. */
+    createDraft(): ModelSettingsDraft;
+    /** `previewModelSettings`: validate + prepare + apply, never commit. */
+    preview(draft: ModelSettingsDraft): ModelSettingsSaveResult;
+}
+/** One note, as the sentence the toast shows. Exhaustive by construction. */
+export declare function kitNoteMessage(note: KitNote): string;
+/** Every note for a result, in the order the estimator emitted it. */
+export declare function kitNoteMessages(notes: readonly KitNote[]): string[];
+/** A non-empty sentence for EVERY code, including the two kit-only ones. */
+export declare function kitApplyMessage(result: KitApplyResult): string;
+/**
+ * Apply a kit for THIS SESSION ONLY.
+ *
+ * `kitId` is a resolved id: the `/kit use` command and the picker may accept a
+ * name or an `#id` prefix, but resolving those is the command layer's job, so
+ * an ambiguous name is reported once, at the surface that accepted it.
+ */
+export declare function applySessionKit(input: {
+    kitId: string;
+    port: KitApplyPort;
+}): KitApplyResult;
+/**
+ * Release the session kit: back to the bindings in the config file (RV-P1-6).
+ *
+ * WITHOUT THIS the feature is one-way: `ctrl+K` could enter a session kit and
+ * nothing could leave it except restarting the process. It shares the session
+ * exit's prepare chain, so it inherits every refusal code rather than defining
+ * a second set of failure semantics.
+ */
+export declare function clearSessionKit(port: KitApplyPort): KitApplyResult;

package/dist/agent/kit-apply.js

@@ -0,0 +1,209 @@
+/**
+ * The session exit: apply a kit WITHOUT writing the config file (§4.2 exit B).
+ *
+ * ASCII ONLY - `src/agent/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A NARROW PORT AND NOT THE CONTROLLER: the same reason
+ * `ModelSettingsController` exists next door - a five-method port can be stubbed
+ * by one object literal in a test, so every refusal code is reachable without a
+ * controller, a provider, or a disk. The controller supplies the real one.
+ *
+ * EVERY PATH EITHER APPLIES OR CHANGES NOTHING (I-10). There is no partial state
+ * to clean up, because the whole thing is one `preview` call: the reused prepare
+ * chain builds the snapshot before it touches the live config, exactly as a save
+ * does - only the commit is missing.
+ */
+import { emptyModelProfiles } from '../config/model-profiles.js';
+import { findKit, kitCandidate, kitSlotConnections } from '../config/model-kits.js';
+import { ALL_SLOTS } from '../config/kit-resolution.js';
+import { modelSettingsResultMessage } from './model-profile-settings.js';
+/**
+ * Kit-specific wording, layered over `modelSettingsResultMessage` (RV-P1-3).
+ *
+ * ONLY the codes whose save-screen text would send the user to the wrong screen
+ * are overridden. Everything else keeps the wording the settings screen already
+ * uses, so a `read_failed` reads the same wherever it appears.
+ */
+const KIT_CODE_MESSAGES = {
+    busy: 'Wait for the current run to finish before switching kit.',
+    conflict: 'Settings changed elsewhere. Reload before switching kit.',
+    write_failed: 'Could not write config. Your settings are unchanged.',
+    apply_failed: 'Could not apply the kit to this session. Nothing changed.',
+    kit_missing: 'That kit is not in your library. Create it in /settings (Settings > Kit pack).',
+    kit_references_missing_profile: 'That kit points at a profile that no longer exists.'
+        + ' Fix it in /settings (Settings > Kit pack).',
+};
+/**
+ * The `KitNote` sentences, verbatim (agent-model-kits §4.2).
+ *
+ * ONE TABLE, THREE CALLERS: the picker, `/kit use`, and any future surface must
+ * say the same thing about the same consequence. `fast_review_enabled` is the
+ * one that matters most - it is a recurring charge the user did not ask for by
+ * name, only by applying a kit that switches the tier on.
+ */
+const KIT_NOTE_MESSAGES = {
+    fast_tier_enabled: 'Fast tier enabled by this kit.',
+    fast_review_enabled: 'Periodic review is on for this tier (/fast review off to stop it).',
+    fast_tier_off: 'Fast tier turned off by this kit.',
+    restart_required: 'Fast tier needs a restart to take effect.',
+    main_key_missing: 'Main profile has no API key; set one in /settings.',
+    subagent_key_missing: 'Subagent profile has no API key; children fall back to main.',
+    subagent_fast_unavailable: 'Subagent uses the fast tier, which this kit leaves off; children fall back to main.',
+};
+/** One note, as the sentence the toast shows. Exhaustive by construction. */
+export function kitNoteMessage(note) { return KIT_NOTE_MESSAGES[note]; }
+/** Every note for a result, in the order the estimator emitted it. */
+export function kitNoteMessages(notes) {
+    return notes.map(kitNoteMessage);
+}
+/** A non-empty sentence for EVERY code, including the two kit-only ones. */
+export function kitApplyMessage(result) {
+    if (result.ok) {
+        return result.released
+            ? 'Kit released; using the config file\'s settings.'
+            : 'Kit applied for this session.';
+    }
+    const code = result.code ?? 'invalid';
+    const specific = KIT_CODE_MESSAGES[code];
+    if (specific)
+        return specific;
+    // NO `apply_failed` BRANCH ABOVE: it is in the table, because a stopped apply
+    // must say "nothing changed" rather than repeat the save screen's wording.
+    // Every remaining code falls through to the shared table, which is what makes
+    // "there is a code with no sentence" unrepresentable instead of merely unlikely.
+    return modelSettingsResultMessage({ ok: false, persisted: false, status: 'rejected',
+        code: code });
+}
+/** Slots whose referenced profile is gone (I-8 / AC-39). */
+function missingSlots(kit, draft) {
+    const connections = kitSlotConnections(draft.profiles, kit);
+    const missing = [];
+    if (!connections.main)
+        missing.push('main');
+    if (kit.fastProfileId !== null && !connections.fast)
+        missing.push('fast');
+    if (kit.subagent.model === 'profile' && !connections.subagent.name)
+        missing.push('subagent');
+    return missing;
+}
+function missingIssue(slot, kit) {
+    const field = slot === 'subagent' ? 'subagent.modelProfileId' : `${slot}ProfileId`;
+    return { path: `modelProfiles.kits[${kit.id}].${field}`,
+        code: 'missing_reference',
+        message: `Kit "${kit.name}" references a profile that no longer exists (${slot}).` };
+}
+function keyMissing(port, draft, id, role) {
+    const entry = id ? draft.profiles?.entries.find((candidate) => candidate.id === id) : undefined;
+    if (!entry)
+        return false;
+    return !entry.apiKey && !port.hasKey(entry.provider, role);
+}
+/**
+ * Everything the user is entitled to know about the apply (§4.2 `KitNote`).
+ *
+ * Computed from the config AS IT WAS BEFORE, because half of these are about
+ * transitions ("the tier just came ON") and the other half are still true after.
+ */
+function kitNotes(input) {
+    const { before, draft, kit, port } = input;
+    const notes = [];
+    const wasEnabled = before.fast.enabled;
+    if (kit.fastProfileId !== null && !wasEnabled)
+        notes.push('fast_tier_enabled');
+    // The honest disclosure of a real cost (F-23): a fast tier with review on
+    // spends money on its own, every N turns, without being asked.
+    if (kit.fastProfileId !== null && !wasEnabled && before.fast.review) {
+        notes.push('fast_review_enabled');
+    }
+    if (kit.fastProfileId === null && wasEnabled)
+        notes.push('fast_tier_off');
+    if (input.restartRequired)
+        notes.push('restart_required');
+    if (keyMissing(port, draft, kit.mainProfileId, 'main'))
+        notes.push('main_key_missing');
+    if (kit.subagent.model === 'profile'
+        && keyMissing(port, draft, kit.subagent.modelProfileId, 'main')) {
+        notes.push('subagent_key_missing');
+    }
+    if (kit.subagent.model === 'fast' && kit.fastProfileId === null) {
+        notes.push('subagent_fast_unavailable');
+    }
+    return notes;
+}
+/**
+ * Apply a kit for THIS SESSION ONLY.
+ *
+ * `kitId` is a resolved id: the `/kit use` command and the picker may accept a
+ * name or an `#id` prefix, but resolving those is the command layer's job, so
+ * an ambiguous name is reported once, at the surface that accepted it.
+ */
+export function applySessionKit(input) {
+    const { kitId, port } = input;
+    if (port.isBusy())
+        return { ok: false, code: 'busy', notes: [] };
+    const before = port.getConfig();
+    const draft = port.createDraft();
+    const library = draft.profiles ?? emptyModelProfiles();
+    const kit = findKit(library, kitId);
+    if (!kit)
+        return { ok: false, code: 'kit_missing', notes: [] };
+    const missing = missingSlots(kit, draft);
+    if (missing.length) {
+        return { ok: false, code: 'kit_references_missing_profile', notes: [],
+            issues: missing.map((slot) => missingIssue(slot, kit)) };
+    }
+    const patch = kitCandidate({ library, kit });
+    draft.profiles = patch.modelProfiles;
+    draft.patch = { ...draft.patch, team: patch.team, fast: patch.fast };
+    // I-13: a kit that turns the tier OFF must NOT project the fast role, or
+    // `projectModelProfiles`'s `continue` would copy the DISK fast endpoint into
+    // the live config and the kit would read as "restore, then switch off".
+    draft.activateRoles = kit.fastProfileId === null ? ['main'] : ['main', 'fast'];
+    draft.sessionKit = { id: kit.id, held: [...ALL_SLOTS] };
+    // THE MARKER, not a heuristic: this draft IS the kit, so `releasedSlots` must
+    // not read the apply's own writes as user decisions (§4.2 exit B).
+    draft.sessionKitFresh = true;
+    const result = port.preview(draft);
+    if (!result.ok) {
+        return { ok: false, code: result.code ?? 'invalid', notes: [],
+            ...(result.issues ? { issues: result.issues } : {}) };
+    }
+    const notes = kitNotes({ before, draft, kit, port,
+        ...(result.restartRequired ? { restartRequired: true } : {}) });
+    return { ok: true, notes };
+}
+/**
+ * Release the session kit: back to the bindings in the config file (RV-P1-6).
+ *
+ * WITHOUT THIS the feature is one-way: `ctrl+K` could enter a session kit and
+ * nothing could leave it except restarting the process. It shares the session
+ * exit's prepare chain, so it inherits every refusal code rather than defining
+ * a second set of failure semantics.
+ */
+export function clearSessionKit(port) {
+    if (port.isBusy())
+        return { ok: false, code: 'busy', notes: [] };
+    const before = port.getConfig();
+    const draft = port.createDraft();
+    const file = draft.baseline;
+    draft.sessionKit = null;
+    draft.patch = {
+        ...draft.patch,
+        team: { model: file.team.model, modelProfileId: file.team.modelProfileId },
+        // The disk fast section, KEY BY KEY: `enabled` restores the tier state and
+        // the other three restore the endpoints the file names, so no trace of the
+        // kit's fast choice survives in the live config.
+        fast: { enabled: file.fast.enabled, provider: file.fast.provider,
+            model: file.fast.model, baseUrl: file.fast.baseUrl },
+    };
+    draft.activateRoles = ['main', 'fast'];
+    const result = port.preview(draft);
+    if (!result.ok)
+        return { ok: false, code: result.code ?? 'invalid', notes: [] };
+    const notes = [];
+    if (result.restartRequired)
+        notes.push('restart_required');
+    if (before.fast.enabled && !file.fast.enabled)
+        notes.push('fast_tier_off');
+    return { ok: true, released: true, notes };
+}

package/dist/agent/model-profile-settings.d.ts

@@ -1,6 +1,7 @@
 import type { ModelRef } from '@aragon-agent/core';
 import { type CliConfig } from '../config/schema.js';
 import { type ModelSettingsDraft, type ModelSettingsSaveResult } from '../config/model-profile-store.js';
+import { type KitSlot } from '../config/model-kits.js';
 /** Fully prepared live state; applying it performs no input parsing or disk access. */
 export interface ModelSettingsSnapshot {
     config: CliConfig;
@@ -22,10 +23,37 @@ export interface ModelSettingsController {
 export declare function createModelSettingsDraft(live: CliConfig, liveRevision: number): ModelSettingsDraft;
 /** Map stable failure codes to safe UI text; never include parser or SDK error messages. */
 export declare function modelSettingsResultMessage(result: ModelSettingsSaveResult): string;
+/**
+ * The slots THIS transaction explicitly decided, and that therefore leave the
+ * session kit (§4.3 / D-6).
+ *
+ * Released BY SLOT, never wholesale: a user who only retargeted the subagent
+ * must not lose the main and fast choices the kit made for this session, and a
+ * user who retargeted main must not have it silently ignored. Per-slot is the
+ * only rule shaped like the data (three independent slots).
+ */
+export declare function releasedSlots(draft: ModelSettingsDraft): KitSlot[];
 /** Validate and prepare everything before the one synchronous, atomic disk commit. */
 export declare function saveModelSettings(input: {
     draft: ModelSettingsDraft;
     controller: ModelSettingsController;
 }): ModelSettingsSaveResult;
+/**
+ * The SAME prepare chain, without the commit: a session kit (§4.2 exit B).
+ *
+ * NO `diskRevision` GATE: nothing is written, so a save that landed elsewhere is
+ * not this operation's business. It still refuses while work is in flight
+ * (`busy`) and still refuses a draft whose disk could not be read, so "nothing
+ * changed" is guaranteed for every other failure too (I-10).
+ */
+export declare function previewModelSettings(draft: ModelSettingsDraft, controller: ModelSettingsController): ModelSettingsSaveResult;
+/**
+ * Apply a prepared snapshot.
+ *
+ * `persisted` HAS NO DEFAULT (RV-P1-4): the one attribute that distinguishes
+ * "the file now says this" from "only this process says this" is not something
+ * a call site should be able to forget.
+ */
+export declare function applyPreparedSnapshot(controller: ModelSettingsController, snapshot: ModelSettingsSnapshot, persisted: boolean): ModelSettingsSaveResult;
 /** Reload the complete model snapshot; invalid disk content never replaces a live session. */
 export declare function reloadModelSettings(controller: ModelSettingsController): ModelSettingsSaveResult;

package/dist/agent/model-profile-settings.js

@@ -4,7 +4,10 @@ import { mergePersistedConfig } from '../config/store.js';
 import { adaptLegacyConnectionPatch, assertLegacyFastTarget, commitModelSettings, readModelSettingsDisk, } from '../config/model-profile-store.js';
 import { projectModelProfiles, resolveModelProfileState } from '../config/model-profile-resolution.js';
 import { validateModelProfiles } from '../config/model-profiles.js';
+import { applyHeldToLive, carrySessionKit } from '../config/kit-resolution.js';
+import { findKit } from '../config/model-kits.js';
 import { registerProfileSecrets } from '../logging/secret-registry.js';
+import { getLogger } from '../logging/logger.js';
 /** Capture both baselines when the editor opens, without migrating or writing anything. */
 export function createModelSettingsDraft(live, liveRevision) {
     const disk = readModelSettingsDisk();
@@ -15,6 +18,11 @@ export function createModelSettingsDraft(live, liveRevision) {
         profiles: disk.config?.modelProfiles
             ? structuredClone(disk.config.modelProfiles) : undefined,
         activateRoles: [], patch: {},
+        // SEEDED FROM THE LIVE CONFIG (RV-P0-2). Without this line `draft.sessionKit`
+        // is always `undefined`, the `undefined` case below means "release", and any
+        // save made from the settings screen would silently drop a session kit the
+        // user just applied - the exact opposite of "this session only".
+        sessionKit: live.sessionKit ? structuredClone(live.sessionKit) : undefined,
         ...(!disk.ok ? { readError: 'Cannot read config. Repair it with aragon config edit.' } : {}),
     };
 }
@@ -61,6 +69,47 @@ function hasConnectionPatch(patch, role) {
     const section = role === 'main' ? patch : patch.fast;
     return !!section && ['provider', 'model', 'baseUrl'].some((key) => key in section);
 }
+/**
+ * The slots THIS transaction explicitly decided, and that therefore leave the
+ * session kit (§4.3 / D-6).
+ *
+ * Released BY SLOT, never wholesale: a user who only retargeted the subagent
+ * must not lose the main and fast choices the kit made for this session, and a
+ * user who retargeted main must not have it silently ignored. Per-slot is the
+ * only rule shaped like the data (three independent slots).
+ */
+export function releasedSlots(draft) {
+    const held = draft.sessionKit?.held ?? [];
+    if (!held.length)
+        return [];
+    // THE APPLY ITSELF RELEASES NOTHING (`kit-apply.ts` sets this marker). Without
+    // it the apply's own writes - `activateRoles`, `patch.team`, the re-bound
+    // library - read as "the user decided every slot", and the save would drop the
+    // three slots it was just handed.
+    if (draft.sessionKitFresh)
+        return [];
+    const kit = findKit(draft.profiles ?? draft.baseline.modelProfiles, draft.sessionKit?.id);
+    if (!kit)
+        return [...held];
+    const released = new Set();
+    for (const role of ['main', 'fast']) {
+        if (draft.activateRoles.includes(role) || connectionChanged(draft, role)
+            || hasConnectionPatch(draft.patch, role))
+            released.add(role);
+    }
+    if (draft.patch.team !== undefined)
+        released.add('subagent');
+    return [...released].filter((slot) => held.includes(slot));
+}
+/** The session kit as it stands AFTER this transaction's explicit decisions. */
+function narrowedSessionKit(draft) {
+    const current = draft.sessionKit;
+    if (!current)
+        return null;
+    const released = releasedSlots(draft);
+    const held = current.held.filter((slot) => !released.includes(slot));
+    return held.length ? { id: current.id, held } : null;
+}
 function liveCandidate(live, candidate, draft) {
     const patch = draft.patch;
     const normalizedPatch = {};
@@ -128,8 +177,16 @@ function liveCandidate(live, candidate, draft) {
             next.apiKeyOverrideTarget = undefined;
         }
         else {
-            next.fast = { ...next.fast, provider: projected.fast.provider,
-                model: projected.fast.model, baseUrl: projected.fast.baseUrl };
+            // I-13 (RV-P1-7): `projectModelProfiles` projects fast ONLY when the
+            // library binds one. With `fastId: null` the projection's `fast` is just the
+            // file's untouched section (`projected` starts as `{...file}`), so copying it
+            // here would resurrect the disk's fast endpoint underneath a kit that
+            // deliberately turned the tier off - the live config would then say "off"
+            // while naming a model nobody chose.
+            if (projected.modelProfiles?.fastId) {
+                next.fast = { ...next.fast, provider: projected.fast.provider,
+                    model: projected.fast.model, baseUrl: projected.fast.baseUrl };
+            }
         }
     }
     if (next.apiKeyOverride && !next.apiKeyOverrideTarget
@@ -139,49 +196,100 @@ function liveCandidate(live, candidate, draft) {
     next.modelProfileState = resolveModelProfileState(next);
     return next;
 }
-/** Validate and prepare everything before the one synchronous, atomic disk commit. */
-export function saveModelSettings(input) {
-    const { draft, controller } = input;
-    if (controller.isModelSettingsBusy())
-        return rejected('busy');
-    if (draft.liveRevision !== controller.getSettingsRevision())
-        return rejected('conflict');
-    const disk = readModelSettingsDisk();
-    if (!disk.ok || draft.readError)
-        return rejected('read_failed');
-    if (disk.revision !== draft.diskRevision)
-        return rejected('conflict');
-    const issues = validateModelProfiles(draft.profiles ?? disk.config?.modelProfiles);
+/**
+ * Build both candidates and the snapshot.
+ *
+ * TWO CANDIDATES, NAMED DIFFERENTLY ON PURPOSE (RV-P0-1 / I-14). `diskCandidate`
+ * is the commit side and never learns about a held slot; `liveCandidateInput`
+ * is what the session sees and is never committed. Collapsing them into one
+ * variable is the defect this split exists to prevent: one unrelated save would
+ * then write the session's kit into the user's permanent defaults, and nothing
+ * visible would change.
+ */
+function prepareModelSettings(input) {
+    const { draft, controller, current } = input;
+    const issues = validateModelProfiles(draft.profiles ?? current.modelProfiles);
     if (issues.length)
-        return { ...rejected('invalid'), issues };
-    let snapshot;
-    let candidate;
+        return { failure: { ...rejected('invalid'), issues } };
     try {
-        const current = disk.config ?? structuredClone(DEFAULT_CONFIG);
         const profilesChanged = draft.activateRoles.length > 0
             || JSON.stringify(draft.profiles) !== JSON.stringify(draft.baseline.modelProfiles);
         const implicitLegacy = draft.profiles === undefined || !profilesChanged;
         const patch = adaptLegacyConnectionPatch({ current, patch: implicitLegacy
                 ? draft.patch : { ...draft.patch, modelProfiles: draft.profiles } });
-        candidate = mergePersistedConfig(current, patch);
-        registerProfileSecrets(candidate);
-        const next = liveCandidate(controller.getConfig(), candidate, draft);
+        const diskCandidate = mergePersistedConfig(current, patch);
+        registerProfileSecrets(diskCandidate);
+        const sessionKit = narrowedSessionKit(draft);
+        const applied = applyHeldToLive(diskCandidate, sessionKit);
+        if (applied.dropped.length) {
+            getLogger().warn('agent', 'session_kit_slots_dropped', { slots: applied.dropped });
+        }
+        const next = liveCandidate(controller.getConfig(), applied.candidate, draft);
+        next.sessionKit = sessionKit ?? undefined;
         // Disk preferences cannot reveal startup/session gateways retained by the live main role.
         if (implicitLegacy && current.modelProfiles?.fastId && hasConnectionPatch(draft.patch, 'fast')) {
             assertLegacyFastTarget(next.fast, next);
         }
-        snapshot = controller.prepareModelSettingsSnapshot(next);
+        const snapshot = controller.prepareModelSettingsSnapshot(next);
+        return { prepared: { diskCandidate, liveCandidateInput: applied.candidate, snapshot } };
     }
     catch (error) {
         const code = error.code ?? 'invalid';
-        return rejected(code);
+        return { failure: rejected(code) };
     }
-    const commit = commitModelSettings({ candidate, diskRevision: draft.diskRevision });
+}
+/** Validate and prepare everything before the one synchronous, atomic disk commit. */
+export function saveModelSettings(input) {
+    const { draft, controller } = input;
+    if (controller.isModelSettingsBusy())
+        return rejected('busy');
+    if (draft.liveRevision !== controller.getSettingsRevision())
+        return rejected('conflict');
+    const disk = readModelSettingsDisk();
+    if (!disk.ok || draft.readError)
+        return rejected('read_failed');
+    if (disk.revision !== draft.diskRevision)
+        return rejected('conflict');
+    const prepared = prepareModelSettings({ draft, controller,
+        current: disk.config ?? structuredClone(DEFAULT_CONFIG) });
+    if (!prepared.prepared)
+        return prepared.failure;
+    const commit = commitModelSettings({ candidate: prepared.prepared.diskCandidate,
+        diskRevision: draft.diskRevision });
     if (!commit.ok)
         return rejected(commit.code ?? 'write_failed');
-    return applyPreparedSnapshot(controller, snapshot, true);
+    return applyPreparedSnapshot(controller, prepared.prepared.snapshot, true);
+}
+/**
+ * The SAME prepare chain, without the commit: a session kit (§4.2 exit B).
+ *
+ * NO `diskRevision` GATE: nothing is written, so a save that landed elsewhere is
+ * not this operation's business. It still refuses while work is in flight
+ * (`busy`) and still refuses a draft whose disk could not be read, so "nothing
+ * changed" is guaranteed for every other failure too (I-10).
+ */
+export function previewModelSettings(draft, controller) {
+    if (controller.isModelSettingsBusy())
+        return rejected('busy');
+    if (draft.readError)
+        return rejected('read_failed');
+    const disk = readModelSettingsDisk();
+    if (!disk.ok)
+        return rejected('read_failed');
+    const prepared = prepareModelSettings({ draft, controller,
+        current: disk.config ?? structuredClone(DEFAULT_CONFIG) });
+    if (!prepared.prepared)
+        return prepared.failure;
+    return applyPreparedSnapshot(controller, prepared.prepared.snapshot, false);
 }
-function applyPreparedSnapshot(controller, snapshot, persisted) {
+/**
+ * Apply a prepared snapshot.
+ *
+ * `persisted` HAS NO DEFAULT (RV-P1-4): the one attribute that distinguishes
+ * "the file now says this" from "only this process says this" is not something
+ * a call site should be able to forget.
+ */
+export function applyPreparedSnapshot(controller, snapshot, persisted) {
     try {
         controller.applyModelSettingsSnapshot(snapshot);
     }
@@ -220,14 +328,19 @@ export function reloadModelSettings(controller) {
         if (live.unicode !== undefined)
             resolved.unicode = live.unicode;
         resolved.reducedMotion ||= !live.color;
+        // THE SESSION KIT SURVIVES A RELOAD (D-6): the three connections it holds
+        // must come from the kit, not from the file we just re-read, and the
+        // projection has to be recomputed so the live config stays equivalent to
+        // what its own bindings say (I-3).
+        const carried = carrySessionKit({ resolved, previous: live });
         const after = readModelSettingsDisk();
         if (!after.ok)
             return rejected('read_failed');
         if (after.revision !== disk.revision)
             return rejected('conflict');
-        if (resolved.modelProfileState?.main.invalid)
+        if (carried.modelProfileState?.main.invalid)
             return rejected('invalid');
-        return applyPreparedSnapshot(controller, controller.prepareModelSettingsSnapshot(resolved), false);
+        return applyPreparedSnapshot(controller, controller.prepareModelSettingsSnapshot(carried), false);
     }
     catch {
         return rejected('invalid');

package/dist/agent/reducer.d.ts

@@ -22,7 +22,7 @@ import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
-export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan';
+export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit';
 export type ToolStatus = 'pending' | 'running' | 'done' | 'error';
 /** Ephemeral, auto-dismissed acknowledgement (spec §3.9). */
 export interface Toast {