@aragon-agent/cli 0.6.33 → 0.6.35

package/README.md

@@ -480,6 +480,68 @@ displayed. `aragon --resume` of such a file inherits the full context and shows
 empty screen until the next turn - the alternative, inventing entries, would put
 a conversation the user never saw onto their screen.
 
+## Agent kits
+
+A **kit** is a named preset that pins the three model roles at once: which
+profile runs the main model, which runs the fast tier (or none), and which model
+subagents use. It is a set of *references* to the profiles you already have, so
+editing a profile changes every kit that names it — which is what "preset"
+should mean.
+
+Kits exist in three layers, and only one of them writes a file:
+
+| Layer | Where | Lives until |
+| --- | --- | --- |
+| **Saved** | `/settings` → `Kit pack` → `New kit` / `e` | you delete it |
+| **Default** | `Kit pack` → `s` (*Set default*), then `Ctrl+S` | you change it |
+| **Session** | `Ctrl+K`, or `/kit use <name>` | this process exits |
+
+The first row of the `Ctrl+K` overlay is always `Current setup` — the bindings in
+`config.json` — and choosing it releases a session kit, so the feature has an exit
+as well as an entrance.
+
+```
+Agent kits                     Session only; set a default in /settings
+  [In use] Deep work                                    [Default]
+  Current setup
+  ────────────────────────────────────────────────────────
+  main      anthropic:claude-opus-4-6        default URL
+  subagent  anthropic:claude-haiku-4-5       profile Haiku
+  fast      anthropic:claude-haiku-4-5       tier on
+  ────────────────────────────────────────────────────────
+  Enter use for this session | Esc close
+```
+
+- **`Ctrl+K` never writes the config file.** That is a promise with a test
+  behind it: the session path runs the same prepare chain as a save and skips
+  only the commit, so a failed switch leaves both the file and the session
+  exactly as they were, and a successful one produces no bytes on disk.
+- **A save decides slots, not the whole kit.** Change the subagent model while a
+  session kit is in effect and only the subagent slot leaves the kit; main and
+  fast keep the kit's choices. Rebinding main releases main, and so on.
+- **The status bar names what is running** with a `kit <name>` chip, and appends
+  `~` when the live connections no longer match the preset (for example after
+  `/model`). With no kit in effect the chip is not rendered at all.
+- **`Ctrl+G` reveals `^K switch kit`** in the header row; on terminals narrower
+  than 79 columns it gives way to `^L` and `^I`, and `/help` plus `/kit` are the
+  fallback. (`Alt+K` is where `Ctrl+K`'s old "kill to end of line" went.)
+- **Setting a default applies its three slots**, because "the default" *is* the
+  binding in the config file. A pointer alone would not be in effect at the next
+  launch.
+- **Deleting a profile deletes the kits that name it**, in the same
+  confirmation, and says so: a preset pointing at a deleted profile can neither
+  be applied nor repaired from any screen. Kits that a hand-edited file leaves
+  dangling degrade to `Profile missing` and are refused with a stable message.
+
+Config keys (all inside the existing `modelProfiles` section, so an older build
+ignores them rather than rejecting the library):
+
+| Key | Meaning |
+| --- | --- |
+| `modelProfiles.kits` | The library: id, name, main profile, fast profile (`null` = off), subagent mode + profile |
+| `modelProfiles.defaultKitId` | The default kit, or `null`. A dangling value heals to `null` |
+| `modelProfiles.kitsVersion` | Migration marker, always `1`. **Downgrading drops kits** (the older build's whitelist does not know the keys); profiles and bindings are unaffected, and `New kit` prefills from your current setup so rebuilding is one Save |
+
 ## Slash commands (interactive)
 
 | Command | Action |
@@ -505,6 +567,7 @@ a conversation the user never saw onto their screen.
 | `/context` | What the context gauge is showing: occupancy split into measured and estimated, the window and **where it came from**, how stale the measurement is, compaction's actual state, and what the session-spend readout includes |
 | `/bg [list\|logs <id> [n]\|stop <id\|all>\|status]` | Background jobs (services and tasks): what is running, its log tail, and how to stop it. `list` is the default |
 | `/update [status\|now\|skip\|off]` | Auto-update: what is running, what is available, where it came from, when it looks again. `now` forces a check past the throttle; `skip` declines the offered version until a newer one appears |
+| `/kit [list\|use <name\|current>]` | Agent kits: what is in effect and where it came from, the whole library with each preset's three connections, or apply one for **this session**. `/kit use current` releases it. Never writes the config file |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
 | `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
 | `/copy` | Copy the last answer to the clipboard |
@@ -528,6 +591,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `Ctrl+I` | **Build the project index** (bundled `project-indexer` skill). Asks for confirmation, then runs as a normal agent turn that writes `.claude-index/` and updates `CLAUDE.md`. On terminals without keyboard enhancement `Ctrl+I` is the Tab byte and completes input instead |
+| `Ctrl+K` | **Agent kits**: pick a model preset — main / subagent / fast profile in one choice — for **this session only**. Nothing is written to the config file. `Current setup` (the first row) releases the preset and returns to the file's bindings. See [Agent kits](#agent-kits) |
 | `Esc` | Close an overlay or popup; otherwise ask for interruption confirmation. While idle, cancel pending auto-continuation |
 | `Esc` ×2 | Interrupt the run when pressed within 1.5 seconds. Other keys or closing a menu cancel the first press |
 | `Esc` again after interruption | **Force-stop** a run that is still stopping, kill foreground shell commands and return to `idle`; background services remain running |
@@ -536,7 +600,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+L` | **Branch this session into a new terminal**: opens a PowerShell (Windows) or bash (macOS/Linux) window at the current `/cwd` and runs `aragon --resume <id>` there, so the branch gets its own id and the session you branched from is untouched. Works while the agent is running - the child inherits the last settled turn. Same code path as `/branch` |
 | `Ctrl+R` | Redraw the frame (moved here from `Ctrl+L`, which is now the branch key) |
 | `Ctrl+T` | Show / hide thinking (**off by default**) for the entire session |
-| `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail. In native scroll mode printed rows cannot change, so it **prints an expanded copy** below instead |
+| `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail. In native scroll mode printed rows cannot change, so it **prints an expanded copy** below instead. When no card is asking for the key it re-prints the **last finished answer** in full — the same escape hatch for a reply taller than the region |
 | Terminal scrolling (native mode, the default) | The wheel, the scrollbar, `Shift+PgUp` / `Shift+PgDn`, text selection and in-terminal search are all your terminal's own — see [Scrolling](#scrolling) |
 | `PgUp` / `PgDn` | Page through an open overlay; in full-screen mode also scroll the transcript a page |
 | `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode only) |
@@ -545,7 +609,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Cursor to line start / end |
 | `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
 | `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
-| `Ctrl+U` / `Ctrl+K` | Kill to line start / end |
+| `Ctrl+U` / `Alt+K` | Kill to line start / end (`Alt+K` was `Ctrl+K`, which now opens the kit picker) |
 | `Up` / `Down` | 按视觉行移动；空草稿或正在浏览历史时，才在边界召回历史，避免覆盖新草稿 |
 | Paste | Inserted up to 6 lines / 400 chars; larger collapses to `[Pasted text #1 +15 lines]`, which deletes as one unit and expands in full when you send. Escape sequences are removed as sequences (so a coloured log arrives as its text, not as `[38;2;18;52;86m`), and a TAB is kept in the payload but laid out at the terminal's 8-column tab stops, so the draft and the echoed message line up. `--no-paste` restores the pre-0.6.3 behaviour |
 | `?` | Open help (empty input) |
@@ -810,24 +874,56 @@ gnome-terminal and friends.
   same paragraph twice. Scrolling up to read earlier output while a reply streams is
   safe; how the viewport behaves when new output arrives is your terminal's own
   "scroll on output" setting. A message you have just sent is therefore on the screen
-  only: it reaches the scrollback when ten newer entries push it out, or when you exit.
+  only while the region can still show it: it reaches the scrollback when the region
+  cannot show it any more, when ten newer entries push it out, or when you exit.
+- **A reply taller than the region is complete, not clipped.** The conversation only has
+  `rows - 6` rows of the screen (24 of them in a 30-row terminal: one header row, the
+  three-row composer slot and the status line are not conversation), so a long answer cannot
+  fit. The rows the region hides above its own top edge are printed into your scrollback as
+  they become hidden, so **`scrollback + screen` covers the whole answer exactly once and in
+  order** - scroll up and the beginning is there, the way it would be for `cat`. Three
+  consequences worth knowing:
+  - **A finished answer is complete immediately.** The rows are given back the moment the
+    answer stops streaming, not after five more turns and not only after you exit. While it
+    is still streaming the head keeps being clipped, because a printed row can never be
+    rewritten and a streaming line can still re-wrap (a code fence closing, a heading
+    gaining its rule); the rest is printed the instant it settles.
+  - **Nothing on the screen moves.** The rows leave through the top of the box exactly as
+    they did before, so the visible frame is unchanged - the head simply exists one wheel
+    turn up instead of nowhere.
+  - **`Ctrl+O` gives you a second copy on demand.** With no expandable card in the
+    conversation it re-prints the last finished answer in full below, which is also the way
+    to re-read one that has a window resize behind it.
 - **Printed rows are final once they leave the screen.** A row that has scrolled into
   your scrollback is never rewritten, and it is wrapped to the width at which it was
   printed, so a later window resize does not re-wrap it. The rows still *on* the screen
   are redrawn in place when the layout has to move them (a reply landing, a draft
-  getting taller), at the same width, without duplicating anything. So `Ctrl+T`
-  (thinking) and `/theme` affect only *new* messages, and `Ctrl+O` prints an
-  expanded copy of a tool card instead of expanding the old one. `/clear` prints a
-  `---- conversation cleared ----` separator; it cannot erase scrollback.
+  getting taller, the conversation outgrowing the region), at the same width, without
+  duplicating anything. So `Ctrl+T` (thinking) and `/theme` affect only *new* messages,
+  and `Ctrl+O` prints an expanded copy of a tool card instead of expanding the old one.
+  `/clear` prints a `---- conversation cleared ----` separator; it cannot erase
+  scrollback. Resizing in the middle of a long answer is the one case where rows can be
+  printed twice: the rows above the seam keep the width they were measured at and the rest
+  are printed again at the new width behind a `[-- reflowed to N columns ... --]` marker,
+  because row numbers do not survive a re-flow. Nothing is lost in that case, which is the
+  property that matters.
 - **The interface fills the terminal.** The header is the first row of the screen, the
   input box and status line are the last two, and everything between them belongs to
-  the conversation: the newest line always touches the input box, so the blank space of
-  a conversation that has not filled the screen sits at the *top of the region* - never
-  between the reply and the composer, and never as a band above the app itself. Three
-  things are still true. A terminal that cannot be measured (`/perf` shows `anchor
-  bottom via fill`, or `none` when the probe is unavailable) is filled to the bottom
-  once at startup, which scrolls your screen up by a page — that one-off flip is the
-  price of pinning without a cursor query. Making the window narrower or shorter drops
+  the conversation. A reply is written **downward from under the header**, the way a
+  terminal prints: while the conversation is shorter than the region the unused rows
+  stay *below* it, and once it is taller the newest line takes the row above the input
+  box and the block moves up one row per new line. The hand-over between those two
+  layouts is a one-off downward move, not a smooth blend while an answer is streaming:
+  the height the switch is decided from is then an estimate, so the block changes over a
+  few rows before it would really have filled the region (three rows on a 30-row
+  terminal), and only then starts scrolling. It happens once per crossing, never
+  repeatedly. A settled conversation is measured instead (the same measurement the rows
+  above are printed from), so the switch lands exactly where the content stops fitting.
+  Three things are still
+  true. A terminal that cannot be measured (`/perf` shows `anchor bottom via fill`, or
+  `none` when the probe is unavailable) is filled to the bottom once at startup, which
+  scrolls your screen up by a page — that one-off flip is the price of pinning without a
+  cursor query. Making the window narrower or shorter drops
   the geometry until the next measurement (a couple of hundred milliseconds) instead of
   guessing: new output parks under the last printed line until the composer pins itself
   again, and old content is neither re-wrapped nor redrawn. `Ctrl+G`, `/help` and the
@@ -840,8 +936,10 @@ gnome-terminal and friends.
   elapsed time. The tail underneath them is drawn with the same cards the full-screen
   mode uses, so a running tool or team card looks identical in both modes. The band
   takes **every row between the header and the composer**: the rail spans the full
-  height above the input box instead of stopping partway down, the tail column ends
-  against the composer, and the printed conversation above always keeps the full width.
+  height above the input box instead of stopping partway down, the tail column owns
+  every row between the roster and the composer (a tail that fits is drawn from its top
+  row down, a taller one keeps its newest row against the input box), and the printed
+  conversation above always keeps the full width.
   Below 76 columns there is no room for the rail and the status line's `todo` chip
   takes over; `/perf`'s `band:` line says which of the six reasons applied.
 - **If something looks wrong**, `/perf` has a `scrollback` line (`guardHits`,
@@ -850,14 +948,17 @@ gnome-terminal and friends.
   The `mode native` line carries `top <n>`, the canvas's first screen row. A `band:`
   line reports the panel band - `rail=<rows>x<cols> team=<rows> tail=<rows>
   pool=<rows> cols=<contentCols>/<previewCols> reason=<visible|empty|disabled|`
-  `narrow|short|overlay> held=<rail>/<team> window=<start>/<n>` - which is the only
-  place that says why a panel is not on screen.
+  `narrow|short|overlay> held=<rail>/<team> window=<start>/<n> head=<rows>` - which is the
+  only place that says why a panel is not on screen.
   `gap` is the blank space above the content and is **always 0** now (the region is the
   whole screen), `canvas` is the canvas height including the live region, `pool` is the
   band's height (the rows between the header and the composer) and `window=<start>/<n>`
   is the tail window: the first entry on screen and how many entries it holds. That
   number is the honest answer to "why is a message I can see not in my scrollback yet"
   - the region shows ten entries, and an entry is printed when it leaves them.
+  `head=<rows>` counts the rows the region could not show and handed back to your
+  scrollback instead, so a wide `window=` with a rising `head=` is the healthy state of a
+  long answer and not a leak.
   `scrolled` counts the rows that have moved into your scrollback.
   The one-step escape hatch is `aragon config set scrollMode app`, or `--scroll-mode
   app` for a single run.

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;