@aragon-agent/cli 0.6.34 → 0.6.36

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';
@@ -344,7 +346,9 @@ export class AgentController {
         this.todoRegistered = config.todo.enabled;
         this.todoEnabled = config.todo.enabled;
         this.todoPanelCapable = deps.todoPanelCapable === true;
-        this.todos = this.todoRegistered ? new TodoStore() : null;
+        this.todos = this.todoRegistered
+            ? new TodoStore(Date.now, () => this.isTodoAcceptanceEnabled())
+            : null;
         // --- Fast model tier ---------------------------------------------------
         //
         // RESOLVED BEFORE THE AGENT, because `fastRegistered` decides whether the
@@ -556,6 +560,12 @@ export class AgentController {
                         store: this.todos,
                         // Read LIVE: `/todo off` flips the flag, it cannot unregister.
                         isEnabled: () => this.todoEnabled,
+                        // LIVE for the same reason (D-11): `/todo acceptance off` must take
+                        // effect in a session already running, because the tool array
+                        // itself cannot change. THE SAME PREDICATE the store was given, on
+                        // purpose: two switches for one capability that could disagree is
+                        // the shape of a session that cannot exist (IF-7).
+                        hasAcceptance: () => this.isTodoAcceptanceEnabled(),
                     }),
                 ]
                 : [],
@@ -910,6 +920,9 @@ export class AgentController {
             todoBlock: this.todoRegistered && this.todoEnabled
                 ? buildTodoBlock({
                     panelVisible: this.todoPanelCapable && config.todo.panel,
+                    // LIVE, never snapshotted (D-11): the paragraph is part of the
+                    // block, and `/todo acceptance off` rebuilds the prompt.
+                    acceptance: config.todo.acceptance,
                 })
                 : '',
             // The SAME two flags one more time, plus the live resolution — all three
@@ -1592,6 +1605,51 @@ export class AgentController {
     getTodoSnapshot() {
         return this.todos?.snapshot() ?? null;
     }
+    /**
+     * Whether the acceptance table is live for this session: the config key AND the
+     * session switch. Two flags, exactly as `isTodoEnabled` needs `isTodoRegistered`
+     * first - a capability that is on while `todo_write` refuses is not a
+     * capability.
+     */
+    isTodoAcceptanceEnabled() {
+        return this.config.todo.acceptance && this.todoEnabled;
+    }
+    /**
+     * Flip the acceptance capability and RE-RENDER THE PROMPT, byte for byte the
+     * contract `setTodoEnabled` records above: the paragraph is part of
+     * `<todo_planning>`, and the tool reads the same live value through its
+     * `hasAcceptance` closure (D-11).
+     */
+    setTodoAcceptanceEnabled(enabled) {
+        this.setTodoConfig({ acceptance: enabled });
+        // THE RAIL READS THE PROJECTION, NOT THE FLAG, so the flip has to re-project or
+        // `/todo acceptance off` would leave the second section on screen until the
+        // model's next write (P0-2's complaint, one path further in). The verdicts
+        // themselves are kept: `getAcceptanceItems()` still returns them for `/save`,
+        // the checkpoint and `exec`.
+        this.todos?.refreshAcceptanceProjection();
+    }
+    /**
+     * The acceptance table as DATA, independent of whether it is being drawn.
+     *
+     * The persistence surfaces must use this and not `getTodoSnapshot()?.acceptance`:
+     * the projection is `null` whenever the capability is off, and a checkpoint or a
+     * `/save` that silently dropped the user's verdicts because a display switch was
+     * off would be a data loss dressed as a setting.
+     */
+    getAcceptanceItems() {
+        return this.todos?.acceptanceItems() ?? [];
+    }
+    /**
+     * `/todo acceptance reset`: every verdict back to `pending`, evidence dropped.
+     *
+     * The count comes BACK from the store rather than being recomputed by the
+     * command, so the notice and the state cannot disagree about how many criteria
+     * moved.
+     */
+    reopenAcceptance() {
+        return this.todos?.reopenAll() ?? 0;
+    }
     /**
      * Subscribe to the CLI-local todo event stream.
      *
@@ -1603,9 +1661,13 @@ export class AgentController {
             return () => { };
         return this.todos.subscribe(listener);
     }
-    /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
-    restoreTodos(items) {
-        this.todos?.restore(items);
+    /**
+     * `/resume`. An absent or empty todo list CLEARS both tables — see
+     * `TodoStore.restore` (P0-2). `acceptance` is optional so every existing caller
+     * keeps compiling, and an omitted table reads as "this file has none".
+     */
+    restoreTodos(items, acceptance = undefined) {
+        this.todos?.restore(items, acceptance);
     }
     /**
      * `/todo clear` and `/clear screen`. A user override of a projection (I-2's
@@ -1680,6 +1742,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/headless.js

@@ -6,6 +6,7 @@
  */
 import { formatCost, formatTokens, formatDuration, computeCost } from './usage.js';
 import { formatStreamError } from './reducer.js';
+import { derivePlanPhase } from '../todo/acceptance.js';
 import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
 /** Run a single prompt headlessly and resolve with the process exit code. */
 export async function runHeadless(controller, prompt, options = {}) {
@@ -139,6 +140,11 @@ export async function runHeadless(controller, prompt, options = {}) {
     // stream that is already `--quiet`-able in full.
     let announcedTotal = 0;
     let lastActive = -1;
+    // THE ACCEPTANCE SECTION'S DEDUPE KEY (todo-acceptance-criteria §6.13.1 / P2-9).
+    // `phase` is DERIVED, never cached (I-3), so the key carries a freshly computed
+    // phase plus the two counters that can only move when a verdict lands: a
+    // constant-size string is cheaper than a field that could drift from the truth.
+    let lastAcceptance = '';
     const unsubscribeTodos = controller.subscribeTodos?.((event) => {
         if (quiet || event.type !== 'updated')
             return;
@@ -147,6 +153,20 @@ export async function runHeadless(controller, prompt, options = {}) {
             announcedTotal = total;
             err.write(`\n[todo] ${total} ${total === 1 ? 'step' : 'steps'} planned\n`);
             lastActive = -1;
+            // A NEW PLAN GETS ITS OWN FIRST `[accept]` LINE, for the reason `lastActive`
+            // is reset one line up: the key below is (phase, checked, failed) and two
+            // different plans can share all three. Without this reset the second plan's
+            // 0/3 in a `-p` run that already printed 0/3 would go unreported.
+            lastAcceptance = '';
+        }
+        const acceptance = event.snapshot.acceptance;
+        if (acceptance && acceptance.total > 0) {
+            const key = `${derivePlanPhase(items, acceptance.items)}|` +
+                `${acceptance.checkedCount}|${acceptance.failedCount}`;
+            if (key !== lastAcceptance) {
+                lastAcceptance = key;
+                err.write(`[accept] ${acceptanceLine(acceptance)}\n`);
+            }
         }
         if (activeIndex < 0) {
             if (lastActive !== -2) {
@@ -220,6 +240,17 @@ export async function runHeadless(controller, prompt, options = {}) {
                 `(${formatTokens(r.tailRelief.charsRemoved)} chars)\n`);
         }
     });
+    /**
+     * `[accept] <n>/<total> checked`, plus the failure count when there is one.
+     *
+     * ONE LINE PER TRANSITION, and the transitions are the ones a `-p` reader can
+     * act on: a verdict landed, or a criterion failed. `evidence` is NEVER printed
+     * (I-8): it belongs to the human-facing surfaces, and a machine log is not one.
+     */
+    function acceptanceLine(acceptance) {
+        const base = `${acceptance.checkedCount}/${acceptance.total} checked`;
+        return acceptance.failedCount > 0 ? `${base}, ${acceptance.failedCount} failed` : base;
+    }
     // --- The bounded continuation loop (todo-plan-followthrough §3.6). --------
     //
     // THE THREE `unsubscribe` CALLS STAY OUTSIDE IT (rule 4). The loop wraps the

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;