@aragon-agent/cli 0.6.24 → 0.6.25

package/dist/commands/clear-command.js

@@ -0,0 +1,107 @@
+/**
+ * `/clear` - start a new conversation - plus its `/reset` alias and the
+ * `/clear screen` form that keeps the old "just wipe the screen" meaning
+ * (clear-command-context-reset §3.5 / D-1 / D-2 / D-3).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. The one
+ * localized string below is written with `\u` escapes for that reason, exactly
+ * as the `/reset` body it replaces did.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/compact` and `/context` do (D-8). `builtins.ts` is 1511 lines against
+ * `CLAUDE.md`'s 1000-line cap, and this command is no longer a two-line
+ * projection reset - it interrupts a run, waits for it, archives a conversation
+ * and then clears. A two-line edit belongs inline; this does not.
+ *
+ * THE COMMAND'S ONLY JOB IS SEQUENCING AND SPEAKING. Every state change happens
+ * on the controller port (`AgentController.resetConversation`, which delegates
+ * the ORDER to `agent/conversation-reset.ts`), and every word the user reads is
+ * decided here, in one place, in the exact order they will read it.
+ */
+import { getLogger } from '../logging/logger.js';
+/** The toast a successful clear shows. Pinned verbatim by an existing test. */
+const CLEARED_TOAST = 'Started a new conversation.';
+/**
+ * Run `/clear` or `/reset`. Both registry entries point HERE (D-2), which is
+ * what stops the two from drifting back into "one clears the screen, one clears
+ * the session" - the drift that produced the defect this feature fixes.
+ */
+export async function runClearCommand(ctx) {
+    const verb = ctx.args.trim().toLowerCase();
+    if (verb === 'screen') {
+        // The old behaviour, byte for byte (I-3): silent, transcript plus the todo
+        // panel, history untouched.
+        clearScreenOnly(ctx);
+        return;
+    }
+    if (verb !== '') {
+        // Rejected rather than ignored. A command that silently accepts and
+        // discards an argument is a surface that lies about what it understood.
+        ctx.notify('warn', `Unknown argument "${ctx.args.trim()}" - use /clear [screen].`);
+        return;
+    }
+    // READ BEFORE CLEARING (P1-2 / I-9). `clearAllQueues()` empties
+    // `pendingUserSteering`, so a count taken afterwards is always zero - and a
+    // notice that says "0 messages cancelled" is worse than no notice at all.
+    const cancelled = ctx.state.pendingSteering.length;
+    const result = await ctx.controller.resetConversation({
+        interrupt: true,
+        // A THUNK, NOT A VALUE (P0-1 / §3.3). `ctx.state` is the view as of command
+        // entry, and the archive happens AFTER the interrupted engine unwinds - so
+        // the last tool cards of the abandoned run are written to the transcript in
+        // between. A value captured here would archive everything except the part
+        // the user was looking at when they typed the command.
+        readTranscript: () => ctx.transcriptEntries?.() ?? ctx.state.entries,
+    });
+    if (!result.ok) {
+        // ZERO SIDE EFFECTS (I-4), and a trace (P1-5). The user gets one sentence
+        // naming the next action; the log gets the reason, because "my /clear did
+        // nothing" is otherwise unanswerable after the fact.
+        getLogger().warn('agent', 'clear_still_running', { reason: result.reason });
+        ctx.notify('warn', result.message);
+        return;
+    }
+    // THE VIEW GOES LAST (B-5 / §3.3). `App`'s dispatch wrapper zeroes the run
+    // metrics, the interaction phase and the scroll anchor on this action, so
+    // dispatching it after the engine has settled is what makes "cleared" mean
+    // "nothing is still writing into it".
+    ctx.dispatch({ type: 'resetConversation' });
+    // THE ONE CONSUMER OF `messagesCleared` (P2-1). It cannot join the toast:
+    // `clear-command-todo.test.ts` pins that string verbatim, and a count nobody
+    // asked for is noise in the one place the user reads confirmations.
+    getLogger().info('agent', 'conversation_cleared', {
+        messagesCleared: result.messagesCleared,
+        interrupted: result.interrupted,
+    });
+    ctx.toast('info', CLEARED_TOAST);
+    // REINSTATED FROM THE OLD `/reset` (P1-1 / C-3). Dropping it would silently
+    // delete a user-visible acknowledgement that already existed and was already
+    // pinned by test.
+    if (cancelled) {
+        ctx.notify('warn', `\u5df2\u53d6\u6d88 ${cancelled} \u6761\u672a\u63a5\u6536\u6d88\u606f`);
+    }
+    if (result.archivedPath) {
+        // A PATH RATHER THAN A PROMISE: the user can copy it, and `/resume` accepts
+        // an absolute path. "Archived" with no way to find the file is a reassurance,
+        // not a recovery.
+        ctx.notify('info', `Previous conversation archived: ${result.archivedPath} (/resume <path> to restore)`);
+    }
+}
+/**
+ * Today's `/clear`, unchanged and silent (D-3 / I-3).
+ *
+ * Kept as a real form rather than as a separate command because "clear the
+ * screen" and "clear the conversation" are two different intentions, and a user
+ * who wants the first must not have to risk the second. It also gives
+ * `clearTranscript` a live dispatcher: `CLAUDE.md` forbids orphaned actions, and
+ * this was the last one that would have had none.
+ */
+function clearScreenOnly(ctx) {
+    // A USER OVERRIDE OF A PROJECTION, the same class as `/todo clear`, so it
+    // reuses reason `'user'`; the distinction against `clearMessages()`'s `'reset'`
+    // is recorded on `TodoStore`. Clearing the STORE and not merely the view
+    // mirror is what keeps `/save`, `/todo status|continue` and follow-through
+    // agreeing with the screen - they read the store directly.
+    ctx.controller.clearTodos();
+    ctx.dispatch({ type: 'clearTranscript' });
+}

package/dist/commands/registry.d.ts

@@ -6,7 +6,7 @@ import type { SubmitMessageOptions } from '../agent/prompt-options.js';
 import type { CopyRequest, CopyRequestResult } from '../ui/clipboard-task.js';
 import type { AgentController } from '../agent/controller.js';
 import type { AgentMode } from '../agent/agent-mode.js';
-import type { NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
+import type { Entry, NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
 import type { FollowThroughBudget } from '../todo/follow-through.js';
 import type { UpdateCommandPort } from '../update/types.js';
@@ -108,6 +108,25 @@ export interface CommandContext {
      * stream is handed over directly.
      */
     writeForeign?: (text: string) => void;
+    /**
+     * The LIVE transcript rows, for `/clear`'s archive (clear-command-context-reset
+     * P0-1 / §3.5).
+     *
+     * A THUNK, AND THAT IS THE WHOLE POINT. The `state` field above is a snapshot
+     * of `ViewState` taken when the command started; `/clear` interrupts a run and
+     * then waits for the engine to unwind, so the last tool cards of that run are
+     * written to the transcript AFTER `state` was captured. Reading `state.entries`
+     * would archive everything except the part the user was just looking at.
+     *
+     * OPTIONAL, like `followBudget` / `update` / `mouse`: every existing
+     * `CommandContext` fixture in this package builds the object by literal, and a
+     * required field would break all of them at compile time for a feature none of
+     * them are about. Absent means the archive degrades to history-only.
+     *
+     * `Entry` arrives as a TYPE-ONLY import so this module keeps its runtime shape
+     * (the same rule the `update/types.js` import above follows).
+     */
+    transcriptEntries?: () => Entry[];
 }
 /** What `/mouse` can see and do. Read at command time, never captured. */
 export interface MouseCommandPort {

package/dist/config/model-profiles.d.ts

@@ -34,6 +34,14 @@ export interface ProfileValidationIssue {
 export declare function emptyModelProfiles(): ModelProfilesConfig;
 /** Return independently mutable role state. */
 export declare function emptyModelProfileState(invalid?: boolean): ModelProfilesRuntime;
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export declare function isValidEndpointUrl(value: string | null | undefined): boolean;
 /** Validate untrusted input; diagnostics never include supplied values. */
 export declare function validateModelProfiles(value: unknown): ProfileValidationIssue[];
 /**

package/dist/config/model-profiles.js

@@ -32,6 +32,16 @@ function validUrl(value) {
         return false;
     }
 }
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export function isValidEndpointUrl(value) {
+    return validUrl(value);
+}
 function validateEntry(value, index) {
     const path = `modelProfiles.entries[${index}]`;
     const invalid = (field, message) => ({

package/dist/session/clear-archive.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Archive the conversation a `/clear` is about to destroy
+ * (clear-command-context-reset §3.8 / D-5 / I-5).
+ *
+ * ASCII ONLY: `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS EXISTS AT ALL: a command whose whole job is to destroy context is a
+ * command a user will eventually fire by accident, one keystroke from `/cwd`. The
+ * difference between "I lost an hour of work" and "I resumed it" is one file, and
+ * `saveSession()` already knows how to write it.
+ *
+ * WHY THIS IS NOT `session/store.ts::writeSession()`: that function MOVES THE
+ * `--continue` POINTER and writes `meta`. An archive is not a session you continue;
+ * it is a record you resume BY PATH. Writing `meta` would also make the file look
+ * `aragon exec`-managed to `sessions list` / `prune`, which is the scoping rule
+ * `persist.ts` records at the top of `SessionMeta` - so a maintenance command would
+ * start deleting the user's cleared conversations.
+ *
+ * ISOLATION IS TWO DEEP (I-6 / P2-4). The directory is the first fence:
+ * `listSessions` / `pruneSessions` / `latestSessionForCwd` read `sessionsDir()`
+ * non-recursively and skip anything not ending in `.json` (`store.ts`), so a
+ * SUBDIRECTORY name is invisible to all three by construction. Omitting `meta` is
+ * the second fence, for the day someone makes that listing recursive or gives
+ * `--all` a wider meaning.
+ */
+import type { Message, ModelRef } from '@aragon-agent/core';
+import type { Entry } from '../agent/reducer.js';
+import type { TodoItem } from '../todo/types.js';
+import type { CompactionIdentity } from '../compaction/memory-identity.js';
+/** Everything the archive writes. `entries` is supplied by the command layer. */
+export interface ClearedArchiveInput {
+    model: ModelRef;
+    messages: Message[];
+    compactionIdentity?: CompactionIdentity;
+    /** The screen transcript, which lives only in `ViewState` (P0-1). */
+    entries: Entry[];
+    todos: TodoItem[];
+}
+/** Bounded retention: the newest N cleared conversations survive. */
+export declare const CLEAR_ARCHIVE_LIMITS: {
+    readonly maxArchives: 20;
+};
+/**
+ * Best-effort archive of the conversation being cleared.
+ *
+ * @returns the absolute path of the written file, or `null` when there was
+ * nothing to save (an empty conversation) or the write failed. NEVER THROWS:
+ * a full disk must not be able to stop a user from starting a new conversation
+ * (I-5), and a caller that had to wrap this in `try` would eventually forget.
+ */
+export declare function archiveClearedConversation(input: ClearedArchiveInput): string | null;

package/dist/session/clear-archive.js

@@ -0,0 +1,160 @@
+/**
+ * Archive the conversation a `/clear` is about to destroy
+ * (clear-command-context-reset §3.8 / D-5 / I-5).
+ *
+ * ASCII ONLY: `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS EXISTS AT ALL: a command whose whole job is to destroy context is a
+ * command a user will eventually fire by accident, one keystroke from `/cwd`. The
+ * difference between "I lost an hour of work" and "I resumed it" is one file, and
+ * `saveSession()` already knows how to write it.
+ *
+ * WHY THIS IS NOT `session/store.ts::writeSession()`: that function MOVES THE
+ * `--continue` POINTER and writes `meta`. An archive is not a session you continue;
+ * it is a record you resume BY PATH. Writing `meta` would also make the file look
+ * `aragon exec`-managed to `sessions list` / `prune`, which is the scoping rule
+ * `persist.ts` records at the top of `SessionMeta` - so a maintenance command would
+ * start deleting the user's cleared conversations.
+ *
+ * ISOLATION IS TWO DEEP (I-6 / P2-4). The directory is the first fence:
+ * `listSessions` / `pruneSessions` / `latestSessionForCwd` read `sessionsDir()`
+ * non-recursively and skip anything not ending in `.json` (`store.ts`), so a
+ * SUBDIRECTORY name is invisible to all three by construction. Omitting `meta` is
+ * the second fence, for the day someone makes that listing recursive or gives
+ * `--all` a wider meaning.
+ */
+import { mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { getLogger } from '../logging/logger.js';
+import { saveSession } from './persist.js';
+import { sessionsDir } from './store.js';
+/** Bounded retention: the newest N cleared conversations survive. */
+export const CLEAR_ARCHIVE_LIMITS = { maxArchives: 20 };
+/** `<sessions>/cleared` - a subdirectory, which is the first isolation fence. */
+const CLEARED_DIR_NAME = 'cleared';
+/** Every archive's filename starts with this, which is what `prune` selects on. */
+const ARCHIVE_PREFIX = 'cleared-';
+/**
+ * Best-effort archive of the conversation being cleared.
+ *
+ * @returns the absolute path of the written file, or `null` when there was
+ * nothing to save (an empty conversation) or the write failed. NEVER THROWS:
+ * a full disk must not be able to stop a user from starting a new conversation
+ * (I-5), and a caller that had to wrap this in `try` would eventually forget.
+ */
+export function archiveClearedConversation(input) {
+    // Clearing an empty conversation produces no file. Without this, every
+    // `/clear` on a fresh session would litter the directory with empty archives
+    // and push a real one out of the retention window.
+    if (input.messages.length === 0)
+        return null;
+    const dir = join(sessionsDir(), CLEARED_DIR_NAME);
+    const path = join(dir, `${archiveId(new Date())}.json`);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        getLogger().debug('agent', 'clear_archive_failed', { reason: reasonOf(err) });
+        return null;
+    }
+    // DEGRADE AND RETRY (P1-6 / C-8). `saveSession` VALIDATES the compaction
+    // identity and THROWS on a damaged or stale one, and an interrupted
+    // conversation - the one a user most wants back - is exactly the one most
+    // likely to carry a stale identity. Losing a whole conversation to an
+    // accessory field would break the only promise this module makes, so the
+    // second attempt drops it: `messages` is what makes the archive recoverable,
+    // the identity only lets the NEXT compaction reuse a prefix.
+    //
+    // The retry runs ONLY when there is an identity to drop. A disk that refused
+    // the first write will refuse an identical second one, so retrying without one
+    // would just double the log line and the wait without changing the outcome.
+    const wrote = writeArchive(path, input, true)
+        || (input.compactionIdentity !== undefined && writeArchive(path, input, false));
+    if (!wrote)
+        return null;
+    pruneArchives(dir);
+    return path;
+}
+/**
+ * One write attempt. `withIdentity` is the only difference between the first and
+ * the degraded second attempt, which is why it is a parameter rather than a
+ * duplicated body.
+ */
+function writeArchive(path, input, withIdentity) {
+    const identity = withIdentity ? input.compactionIdentity : undefined;
+    try {
+        saveSession(path, {
+            model: input.model,
+            messages: input.messages,
+            ...(identity ? { compactionIdentity: identity } : {}),
+            entries: input.entries,
+            todos: input.todos,
+        });
+        return true;
+    }
+    catch (err) {
+        getLogger().debug('agent', 'clear_archive_write_failed', {
+            withIdentity, reason: reasonOf(err),
+        });
+        return false;
+    }
+}
+/**
+ * Deterministic, collision-free id (P2-3).
+ *
+ * `cleared-<yyyyMMdd>-<HHmmss>-<pid>` is ASCII, matches `isValidSessionId`
+ * (`[A-Za-z0-9][A-Za-z0-9._-]*`), and is legible enough to type after
+ * `/resume `. The pid removes cross-process collisions; within one process a
+ * second `cleared-` file in the same second is unreachable because the FIRST
+ * clear leaves an empty conversation and `archiveClearedConversation` returns
+ * early on that. So no `-2`/`-3` suffix ladder is needed, and none is here.
+ */
+function archiveId(at) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const day = `${at.getFullYear()}${pad(at.getMonth() + 1)}${pad(at.getDate())}`;
+    const clock = `${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+    return `${ARCHIVE_PREFIX}${day}-${clock}-${process.pid}`;
+}
+/**
+ * Keep the newest `maxArchives` files; delete the rest.
+ *
+ * A sweep, not a scheduled job: retention that runs on the write path cannot be
+ * forgotten, and the failure mode of a missed sweep is bounded disk usage rather
+ * than unbounded. Every error here is swallowed on purpose - pruning is
+ * housekeeping and must never be able to fail a clear that already succeeded.
+ */
+function pruneArchives(dir) {
+    const survivors = [];
+    for (const name of safeReaddir(dir)) {
+        if (!name.startsWith(ARCHIVE_PREFIX) || !name.endsWith('.json'))
+            continue;
+        const path = join(dir, name);
+        try {
+            survivors.push({ path, modified: statSync(path).mtimeMs });
+        }
+        catch {
+            // A file that vanished between listing and stat is already deleted.
+        }
+    }
+    survivors.sort((a, b) => b.modified - a.modified);
+    for (const doomed of survivors.slice(CLEAR_ARCHIVE_LIMITS.maxArchives)) {
+        try {
+            unlinkSync(doomed.path);
+        }
+        catch (err) {
+            getLogger().debug('agent', 'clear_archive_prune_failed', { reason: reasonOf(err) });
+        }
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function reasonOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/todo/types.d.ts

@@ -42,9 +42,11 @@ export interface TodoSnapshot {
 /**
  * Why a list went away.
  *
- *   `user`  - `/todo clear`, or `/clear`. Both are an explicit user instruction,
- *             which is I-2's standing exception; neither touches `messages`.
- *   `reset` - `/reset`, or a `/resume` whose file carried no list (§3.13).
+ *   `user`  - `/todo clear`, or `/clear screen` (the screen-only form). Both are
+ *             an explicit user instruction, which is I-2's standing exception;
+ *             neither touches `messages`.
+ *   `reset` - `/clear` (or its alias `/reset`) through `clearMessages()`, or a
+ *             `/resume` whose file carried no list (§3.13).
  *   `turn`  - a new TUI task started, or a legacy caller began a turn after
  *             every item was completed.
  *   `stale` - unfinished, and unwritten for more than `TODO_LIMITS.staleTurns`

package/dist/ui/App.js

@@ -55,6 +55,7 @@ import { publishExitSnapshot } from './exit-snapshot.js';
 import { OverlayFrame } from './layout/OverlayFrame.js';
 import { helpRows } from './overlays/HelpOverlay.js';
 import { ModelPicker } from './overlays/ModelPicker.js';
+import { createModelProbe } from '../agent/model-probe.js';
 import { SettingsScreen, compactionSettingsFrom, fastSettingsFrom, } from './overlays/SettingsScreen.js';
 import { ConfirmDialog } from './overlays/ConfirmDialog.js';
 import { QuestionOverlay } from './overlays/QuestionOverlay.js';
@@ -1388,6 +1389,12 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         requestCopy: copyCoordinator.requestCopy,
         controller,
         state: stateRef.current,
+        // THE ARCHIVE'S ONLY WAY TO SEE THE SCREEN (P0-1 / §3.7), and a thunk for a
+        // reason `state` above illustrates: `state` is a snapshot of this render,
+        // while `/clear` interrupts a run and then waits for it to unwind, so the last
+        // tool cards of the abandoned run are appended AFTER the command starts. A
+        // value here would archive the screen minus the part the user was watching.
+        transcriptEntries: () => stateRef.current.entries,
         dispatch: (action) => {
             if (action.type === 'resetConversation' || action.type === 'restoreEntries') {
                 metrics.current = createRunMetrics();
@@ -1535,12 +1542,25 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     };
     submitRef.current = submitMessage;
     const executeSlashInput = async (raw) => {
-        const switchWhileBusy = controller.isCompactionBusy?.()
-            && /^\s*\/(clear|reset|resume)(?:\s|$)/.test(raw);
-        if (switchWhileBusy) {
+        // A CONVERSATION SWITCH OWNS THE QUEUE FOR THE WHOLE COMMAND (B-6 / §3.7).
+        //
+        // The guard used to be raised only when a compaction happened to be busy,
+        // which left the one window this feature is about unwatched: `/clear` on an
+        // IDLE session took the flag nowhere, and `drainCompactionQueue` was still
+        // free to `continue()` a message queued in the previous conversation into
+        // the one the user had just started. Whether there is work to cancel is a
+        // separate question, so the two are now separate values: `switching` decides
+        // the lock, `switchWhileBusy` decides the cancellation.
+        //
+        // `/resume` is still refused mid-run by `handleSubmit` below, so for it the
+        // lock only ever matters while idle - that is the minimum this invariant
+        // asks for, not a contradiction.
+        const switching = /^\s*\/(clear|reset|resume)(?:\s|$)/.test(raw);
+        const switchWhileBusy = switching && Boolean(controller.isCompactionBusy?.());
+        if (switching)
             switchingConversation.current = true;
+        if (switchWhileBusy)
             await controller.cancelCompaction();
-        }
         // Retain a recoverable command before any asynchronous handler can fail.
         const safe = redactText(raw, getSecrets());
         recordPrompt(safe);
@@ -1553,7 +1573,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             notify('error', `Command failed: ${redactText(reason, getSecrets())}\nInput: ${safe}`);
         }
         finally {
-            if (switchWhileBusy) {
+            if (switching) {
                 switchingConversation.current = false;
                 drainCompactionQueue.current();
             }
@@ -1563,7 +1583,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         const trimmed = raw.trimStart();
         const slash = trimmed.startsWith('/') && !trimmed.startsWith('//');
         if (slash && (interactionPhase.current === 'running' || controller.isRunning()) &&
-            /^\/(reset|resume)(?:\s|$)/.test(trimmed)) {
+            /^\/resume(?:\s|$)/.test(trimmed)) {
             return { accepted: false,
                 reason: 'Interrupt the current run before switching conversations.' };
         }
@@ -2050,6 +2070,18 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     const overlay = state.overlay;
     const settingsDraft = useMemo(() => overlay === 'settings'
         ? controller.createModelSettingsDraft() : undefined, [controller, overlay]);
+    // ONE PROBE PER APP (model-profile-connection-test 5 row 9): the port needs the
+    // controller's provider registry, which the overlay has no business owning.
+    // Built only while the settings overlay is open, so no other screen pays for it.
+    const probe = useMemo(() => {
+        if (overlay !== 'settings')
+            return undefined;
+        // A test double or an embedded host may predate this port; absent means the
+        // two probe rows read `(unavailable)` rather than the screen crashing.
+        if (typeof controller.getProviderRegistry !== 'function')
+            return undefined;
+        return createModelProbe({ registry: controller.getProviderRegistry() });
+    }, [controller, overlay]);
     const hasKey = controller.hasApiKey();
     const empty = state.entries.length === 0;
     // RENDER SCOPE, so the chip and the composer hint agree with what the Ctrl+C
@@ -2155,7 +2187,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             // the save handler cannot disagree about what `(inherit)` means.
             ...fastSettingsFrom(cfg.fast),
             ...compactionSettingsFrom(cfg.compaction),
-        }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, draft: settingsDraft, onProfileSave: handleProfileSave, onReload: () => controller.createModelSettingsDraft(), onClose: () => dispatch({ type: 'setOverlay', overlay: null }), 
+        }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, draft: settingsDraft, probe: probe, onProfileSave: handleProfileSave, onReload: () => controller.createModelSettingsDraft(), onClose: () => dispatch({ type: 'setOverlay', overlay: null }), 
         // Read from `cfg` (render scope, re-read every frame), so `/retry off`
         // while the screen is open shows the new value on the next paint.
         retrySummary: cfg.retry.enabled && cfg.retry.maxRetries > 0 ? String(cfg.retry.maxRetries) : 'off' })) : overlay === 'confirm' && confirmState ? (_jsx(ConfirmDialog, { isActive: !tooSmall, state: confirmState, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onClose: closeConfirm })) : overlay === 'question' && humanRequest?.kind === 'questions' ? (_jsx(QuestionOverlay, { isActive: !tooSmall, questions: humanRequest.questions, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onSubmit: (answers) => resolveHuman({ kind: 'answers', answers, cancelled: false }) })) : overlay === 'plan' && humanRequest?.kind === 'plan' ? (_jsx(PlanReviewOverlay, { isActive: !tooSmall, plan: humanRequest.plan, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onVerdict: handlePlanVerdict })) : null;

package/dist/ui/entries/CompactionCard.d.ts

@@ -14,10 +14,11 @@
  * kind — without it the card renders a hint that does nothing and expands an
  * older tool card instead (C-15 / P1-8 / AC-21).
  *
- * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9). `/clear`
- * empties the transcript view but not `messages`, so this card can legitimately
- * report "112 -> 9 messages" with nine visible rows above it. Nothing here says
- * "above" or "earlier in this transcript".
+ * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9).
+ * `/clear screen` empties the transcript view but not `messages`, so this card
+ * can legitimately report a message count the visible rows do not add up to.
+ * Nothing here says "above" or "earlier in this transcript". `/clear` itself is
+ * the conversation boundary now: it drops the history and this card with it.
  */
 import React from 'react';
 import type { Theme } from '../theme.js';

package/dist/ui/entries/CompactionCard.js

@@ -15,10 +15,11 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * kind — without it the card renders a hint that does nothing and expands an
  * older tool card instead (C-15 / P1-8 / AC-21).
  *
- * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9). `/clear`
- * empties the transcript view but not `messages`, so this card can legitimately
- * report "112 -> 9 messages" with nine visible rows above it. Nothing here says
- * "above" or "earlier in this transcript".
+ * EVERY STRING DESCRIBES THE HISTORY, NEVER THE SCREEN (§6.4 / P2-9).
+ * `/clear screen` empties the transcript view but not `messages`, so this card
+ * can legitimately report a message count the visible rows do not add up to.
+ * Nothing here says "above" or "earlier in this transcript". `/clear` itself is
+ * the conversation boundary now: it drops the history and this card with it.
  */
 import React from 'react';
 import { Box, Text } from 'ink';

package/dist/ui/overlays/HelpOverlay.js

@@ -68,8 +68,14 @@ const COMMANDS = [
         'Todo planning: status, switches, the rail, follow-through',
     ],
     ['/tools', 'List active tools'],
-    ['/clear', 'Clear the visible transcript and the todo panel'],
-    ['/reset', 'New conversation'],
+    // `/clear` IS NOT "CLEAR THE SCREEN" ANY MORE (clear-command-context-reset D-1).
+    // Two rows, not one, because the intentions differ: `/clear` starts a NEW
+    // CONVERSATION (interrupt the run, archive the old one, drop the history), while
+    // `/clear screen` only wipes what is on screen. A user who wants the second has
+    // to be able to see that it exists before reaching for the first.
+    ['/clear', 'Start a new conversation: archive, then clear context and transcript'],
+    ['/clear screen', 'Clear the visible transcript only; keeps the conversation'],
+    ['/reset', 'Alias of /clear'],
     ['/cwd [dir]', 'Show or change the tool working directory'],
     ['/save [file]', 'Save the session to JSON'],
     ['/resume [file]', 'Load a saved session'],

package/dist/ui/overlays/ModelDiscoveryList.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { type ProfileFrameProps } from './ModelProfilePicker.js';
+import { type DiscoveryView } from './model-probe-view.js';
+interface ModelDiscoveryListProps extends ProfileFrameProps {
+    provider: string;
+    /** The draft's current model: the cursor starts on it when the list has it. */
+    currentModel: string;
+    view: DiscoveryView;
+    busy: boolean;
+    onChoose: (model: string) => void;
+    onRetry: () => void;
+    onBack: () => void;
+    onCancelProbe?: () => void;
+}
+/**
+ * The discovered-model page (model-profile-connection-test §3.5).
+ *
+ * Pure display plus input: it receives the discovery outcome and three intents and
+ * issues no request itself. No spinner - the census of animated sites is a closed
+ * list, and this overlay can be open while a run is in flight.
+ */
+export declare function ModelDiscoveryList(props: ModelDiscoveryListProps): React.ReactElement;
+export {};