@pellux/goodvibes-tui 1.20.1 → 1.21.1

package/src/daemon/handlers/inbox/cursor-store.ts

@@ -13,11 +13,80 @@
 // = max(receivedAt) ever seen. Triage metadata is NOT persisted here: it is
 // applied downstream at the triage overlay layer (triage/integration.ts) over a
 // separate store, so this feed store carries only the raw inbound fields.
+//
+// RETENTION. The items table is bounded by BOTH an age TTL and a count cap, and
+// the sweep runs at init() — the recovery point, right after the database file
+// is opened — and then on a timer for the life of the store, so a daemon that
+// stays up for weeks keeps reclaiming. `pruneOlderThan` used to exist with no
+// production caller at all, which meant the table grew without bound in
+// practice. Reclaimed counts are handed to the `onSweep` hook (counts only —
+// message previews and sender ids never reach a log line).
+//
+// Cursors are deliberately NOT reaped: they are monotonic watermarks, so
+// dropping one would re-deliver everything a provider ever sent.
+//
+// Idempotence/concurrency: a sweep re-run immediately reclaims nothing (the
+// DELETEs are set-based over the current contents). Two processes opening the
+// same file each hold their own sql.js snapshot and `save()` writes the whole
+// file via temp+rename, so the last writer wins — that whole-file model is
+// HandlerSqliteStore's, and deletion converging on the same surviving set is
+// what makes concurrent sweeps safe rather than corrupting.
 // ---------------------------------------------------------------------------
 
 import { HandlerSqliteStore } from '../sqlite-store.ts';
 import type { InboundChannelItem } from './provider-adapter.ts';
 
+/**
+ * Age TTL for feed items: rows whose receivedAt is older than this are dropped
+ * on every sweep. Long enough that "what did that person say last month" still
+ * works, short enough that the table cannot grow indefinitely.
+ */
+export const INBOX_ITEM_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+/**
+ * Count cap for feed items: the newest this many rows survive a sweep, older
+ * ones are dropped. Guards the case the TTL cannot — a very chatty month.
+ */
+export const INBOX_ITEM_CAP = 5_000;
+
+/**
+ * Cadence of the background retention sweep. The first sweep happens at init();
+ * this timer is what keeps it from being a startup-only reap.
+ */
+export const INBOX_SWEEP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+
+const DEFAULT_STORE_FILE_NAME = 'inbox.sqlite';
+
+/** Result of one retention sweep. Counts only — never item content. */
+export interface InboxSweepSummary {
+  /** Unix ms of the sweep. */
+  readonly at: number;
+  /** Rows removed by the age TTL. */
+  readonly expired: number;
+  /** Rows removed by the count cap. */
+  readonly capped: number;
+  /** Rows left in the items table afterwards. */
+  readonly remaining: number;
+}
+
+export interface InboxCursorStoreOptions {
+  /** Override the age TTL (tests / embedders). Defaults to INBOX_ITEM_TTL_MS. */
+  readonly itemTtlMs?: number;
+  /** Override the count cap (tests / embedders). Defaults to INBOX_ITEM_CAP. */
+  readonly itemCap?: number;
+  /** Sweep cadence; 0 or less disables the timer (the init sweep still runs). */
+  readonly sweepIntervalMs?: number;
+  /** Called after a sweep that reclaimed at least one row. Counts only. */
+  readonly onSweep?: (summary: InboxSweepSummary) => void;
+  /** Called when a sweep failed, so retention problems are visible rather than swallowed. */
+  readonly onSweepError?: (message: string) => void;
+  /** Clock seam (tests). Defaults to Date.now. */
+  readonly now?: () => number;
+  /** Timer seams (tests). Default to the globals. */
+  readonly setIntervalImpl?: typeof setInterval;
+  readonly clearIntervalImpl?: typeof clearInterval;
+}
+
 const SCHEMA: string[] = [
   `CREATE TABLE IF NOT EXISTS items (
      id TEXT PRIMARY KEY,
@@ -62,21 +131,107 @@ export interface InboxQuery {
 export class InboxCursorStore {
   private readonly store: HandlerSqliteStore;
   private dirty = false;
+  private readonly itemTtlMs: number;
+  private readonly itemCap: number;
+  private readonly sweepIntervalMs: number;
+  private readonly onSweep: ((summary: InboxSweepSummary) => void) | undefined;
+  private readonly onSweepError: ((message: string) => void) | undefined;
+  private readonly now: () => number;
+  private readonly setIntervalImpl: typeof setInterval;
+  private readonly clearIntervalImpl: typeof clearInterval;
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
 
-  constructor(workingDirectory: string, fileName = 'inbox.sqlite') {
+  constructor(
+    workingDirectory: string,
+    fileName: string = DEFAULT_STORE_FILE_NAME,
+    options: InboxCursorStoreOptions = {},
+  ) {
     this.store = new HandlerSqliteStore({
       workingDirectory,
-      fileName,
+      fileName: fileName || DEFAULT_STORE_FILE_NAME,
       schema: SCHEMA,
     });
+    this.itemTtlMs = options.itemTtlMs ?? INBOX_ITEM_TTL_MS;
+    this.itemCap = options.itemCap ?? INBOX_ITEM_CAP;
+    this.sweepIntervalMs = options.sweepIntervalMs ?? INBOX_SWEEP_INTERVAL_MS;
+    this.onSweep = options.onSweep;
+    this.onSweepError = options.onSweepError;
+    this.now = options.now ?? Date.now;
+    this.setIntervalImpl = options.setIntervalImpl ?? setInterval;
+    this.clearIntervalImpl = options.clearIntervalImpl ?? clearInterval;
   }
 
   get dbPath(): string {
     return this.store.dbPath;
   }
 
+  /**
+   * Open the database, then immediately reap: recovery is exactly when stale
+   * rows from previous runs must go. The periodic timer starts afterwards so
+   * retention is not a startup-only event.
+   */
   async init(): Promise<void> {
     await this.store.init();
+    await this.runSweep();
+    this.startSweepTimer();
+  }
+
+  /**
+   * One retention pass: age TTL first, then the count cap over what is left.
+   * Returns counts only. Running it twice in a row reclaims nothing the second
+   * time — the pass is a function of the table's current contents.
+   */
+  sweepRetention(): InboxSweepSummary {
+    const at = this.now();
+    const expired = this.pruneOlderThan(at - this.itemTtlMs);
+    const capped = this.enforceItemCap();
+    return { at, expired, capped, remaining: this.countItems() };
+  }
+
+  /** Sweep, persist if anything was reclaimed, and disclose the counts. Never throws. */
+  private async runSweep(): Promise<void> {
+    try {
+      const summary = this.sweepRetention();
+      if (summary.expired + summary.capped === 0) return;
+      await this.flush();
+      this.onSweep?.(summary);
+    } catch (error) {
+      this.onSweepError?.(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  private startSweepTimer(): void {
+    if (this.sweepTimer !== null || this.sweepIntervalMs <= 0) return;
+    const handle = this.setIntervalImpl(() => {
+      void this.runSweep();
+    }, this.sweepIntervalMs);
+    // Retention must never be the reason the process stays alive (Bun/Node unref).
+    (handle as unknown as { unref?: () => void }).unref?.();
+    this.sweepTimer = handle;
+  }
+
+  private stopSweepTimer(): void {
+    if (this.sweepTimer === null) return;
+    this.clearIntervalImpl(this.sweepTimer);
+    this.sweepTimer = null;
+  }
+
+  /**
+   * Count cap: keep the newest `itemCap` rows (receivedAt DESC, id ASC — the
+   * same order listItems() uses), delete the rest. Returns rows removed.
+   */
+  private enforceItemCap(): number {
+    const before = this.countItems();
+    if (before <= this.itemCap) return 0;
+    this.store.run(
+      `DELETE FROM items WHERE id NOT IN (
+         SELECT id FROM items ORDER BY receivedAt DESC, id ASC LIMIT ?
+       )`,
+      [this.itemCap],
+    );
+    const removed = before - this.countItems();
+    if (removed > 0) this.dirty = true;
+    return removed;
   }
 
   /**
@@ -258,8 +413,9 @@ export class InboxCursorStore {
     this.dirty = false;
   }
 
-  /** Flush (best-effort) then close the underlying database. */
+  /** Stop the retention timer, flush (best-effort), then close the database. */
   async close(): Promise<void> {
+    this.stopSweepTimer();
     try {
       await this.flush();
     } finally {

package/src/daemon/handlers/inbox/index.ts

@@ -160,7 +160,20 @@ export function registerInboxMethods(
     ...(routing ? { resolveRouteId: routeResolverFromRouting(routing) } : {}),
   };
   const adapters = buildAdapters(adapterContext);
-  const store = new InboxCursorStore(ctx.workingDirectory, options.storeFileName);
+  // Retention runs inside the store (age TTL + count cap, at init and then on a
+  // timer). Both hooks carry COUNTS ONLY — no sender ids, subjects or bodies.
+  const store = new InboxCursorStore(ctx.workingDirectory, options.storeFileName, {
+    onSweep: (summary) => {
+      ctx.logger.info('inbox retention sweep reclaimed items', {
+        expired: summary.expired,
+        capped: summary.capped,
+        remaining: summary.remaining,
+      });
+    },
+    onSweepError: (message) => {
+      ctx.logger.warn('inbox retention sweep failed', { error: message });
+    },
+  });
   const poller = new InboundPoller({ adapters, store, logger: ctx.logger });
 
   // Async bootstrap: init store, seed one poll, start loops. Failures are

package/src/daemon/handlers/sqlite-store.ts

@@ -1,7 +1,8 @@
 import { mkdir, rename, writeFile } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import initSqlJs from 'sql.js';
 
 type SqlJsStatic = Awaited<ReturnType<typeof initSqlJs>>;
@@ -15,6 +16,26 @@ export interface SqliteStoreOptions {
   schema: string[];
 }
 
+/**
+ * The 16 bytes every SQLite file begins with ("SQLite format 3" + NUL). A file
+ * that does not start with these is not a database, whatever its extension —
+ * which is exactly what a crash mid-create, a zero-fill, or a partially
+ * restored backup leaves behind.
+ */
+const SQLITE_HEADER = Buffer.from('SQLite format 3\0', 'latin1');
+
+/**
+ * How long a quarantined `.corrupt-<timestamp>` database is kept before it is
+ * reclaimed. These files exist so an operator can try to salvage a damaged
+ * store by hand; 14 days is long enough for someone to notice a broken daemon
+ * and come looking, and short enough that a store that goes bad repeatedly
+ * cannot fill the disk with copies of itself. Reaped on the next init.
+ */
+const CORRUPT_QUARANTINE_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+
+/** At most this many quarantined copies of one store are kept, newest first. */
+const MAX_CORRUPT_QUARANTINES = 3;
+
 let sqlJsStaticPromise: Promise<SqlJsStatic> | null = null;
 
 async function loadSqlJs(): Promise<SqlJsStatic> {
@@ -56,14 +77,147 @@ export class HandlerSqliteStore {
     return this.db;
   }
 
+  /**
+   * Move a database file that cannot be opened aside instead of deleting it, so
+   * an operator still has something to salvage, and return the quarantine path.
+   * Returns null when the move itself failed — in which case the caller starts
+   * fresh in memory and the bad file is left exactly where it was rather than
+   * being overwritten on the next save.
+   */
+  private quarantineUnreadable(): string | null {
+    const target = `${this.resolvedPath}.corrupt-${Date.now()}`;
+    try {
+      renameSync(this.resolvedPath, target);
+      return target;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Bound the quarantine directory: drop `.corrupt-*` copies of THIS store that
+   * are past the TTL or beyond the keep-newest count. Best-effort and
+   * idempotent — a file another process already removed is success, not an
+   * error — so two daemons opening the same store at once cannot fight.
+   * Returns how many were reclaimed.
+   */
+  private reapCorruptQuarantines(nowMs: number): number {
+    const dir = dirname(this.resolvedPath);
+    const prefix = `${basename(this.resolvedPath)}.corrupt-`;
+    let candidates: Array<{ path: string; mtimeMs: number }>;
+    try {
+      candidates = readdirSync(dir)
+        .filter((name) => name.startsWith(prefix))
+        .map((name) => join(dir, name))
+        .flatMap((path) => {
+          try {
+            return [{ path, mtimeMs: statSync(path).mtimeMs }];
+          } catch {
+            return [];
+          }
+        });
+    } catch {
+      return 0;
+    }
+    if (candidates.length === 0) return 0;
+    // Newest first: the newest MAX_CORRUPT_QUARANTINES survive the count cap,
+    // and everything past the TTL goes regardless of rank.
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    let reclaimed = 0;
+    for (const [index, candidate] of candidates.entries()) {
+      const tooOld = nowMs - candidate.mtimeMs > CORRUPT_QUARANTINE_TTL_MS;
+      const overCap = index >= MAX_CORRUPT_QUARANTINES;
+      if (!tooOld && !overCap) continue;
+      try {
+        rmSync(candidate.path, { force: true });
+        reclaimed += 1;
+      } catch {
+        // Another process may have taken it first; that is the outcome we wanted.
+      }
+    }
+    return reclaimed;
+  }
+
   async init(): Promise<void> {
     if (this.db) return;
     await mkdir(dirname(this.resolvedPath), { recursive: true });
     const SQL = await loadSqlJs();
-    const existing = existsSync(this.resolvedPath) ? readFileSync(this.resolvedPath) : undefined;
-    this.db = existing ? new SQL.Database(existing) : new SQL.Database();
-    for (const statement of this.options.schema) {
-      this.db.run(statement);
+
+    // Validate the file by its CONTENT, not by existsSync. `save()` writes
+    // through a pid-and-timestamp temp file and an atomic rename, so it cannot
+    // itself leave a half-written database — but a zero-filled file recovered
+    // by a filesystem, a truncated restore, or a copy interrupted by something
+    // outside this process all produce a path that exists and holds no usable
+    // database. Handing those bytes to `new SQL.Database(...)` throws out of
+    // init and takes the whole daemon store down with no way back.
+    let existing: Buffer | undefined;
+    let quarantined: string | null = null;
+    let quarantineReason = '';
+    if (existsSync(this.resolvedPath)) {
+      let raw: Buffer | null = null;
+      try {
+        raw = readFileSync(this.resolvedPath);
+      } catch {
+        raw = null;
+      }
+      if (!raw || raw.length === 0) {
+        quarantineReason = raw ? 'zero-byte file (interrupted write)' : 'unreadable file';
+        quarantined = this.quarantineUnreadable();
+      } else if (raw.length < SQLITE_HEADER.length || !raw.subarray(0, SQLITE_HEADER.length).equals(SQLITE_HEADER)) {
+        quarantineReason = 'missing the SQLite file header (not a database)';
+        quarantined = this.quarantineUnreadable();
+      } else {
+        existing = raw;
+      }
+    }
+
+    if (existing) {
+      // The constructor is NOT where a damaged image surfaces: sql.js accepts
+      // the bytes and only reports "database disk image is malformed" when the
+      // first statement touches a bad page. So the open is not proved until the
+      // schema has actually run against it, and both steps share one catch.
+      try {
+        const candidate = new SQL.Database(existing);
+        try {
+          for (const statement of this.options.schema) candidate.run(statement);
+          this.db = candidate;
+        } catch (error) {
+          candidate.close();
+          throw error;
+        }
+      } catch (error) {
+        // Header present but the body does not hold up: a truncated or damaged
+        // database. Same treatment — set aside, disclose, start clean.
+        quarantineReason = `database would not open: ${error instanceof Error ? error.message : String(error)}`;
+        this.db = null;
+        quarantined = this.quarantineUnreadable();
+      }
+    }
+
+    if (!this.db) {
+      this.db = new SQL.Database();
+      for (const statement of this.options.schema) this.db.run(statement);
+    }
+
+    // Disclosure: starting a store from scratch is data loss from the user's
+    // point of view, so it is never allowed to happen quietly.
+    if (quarantineReason) {
+      logger.warn('daemon store could not be opened — starting a fresh one', {
+        store: this.options.fileName,
+        path: this.resolvedPath,
+        reason: quarantineReason,
+        quarantinedTo: quarantined ?? '(could not be moved aside; left in place)',
+      });
+    }
+
+    const reclaimed = this.reapCorruptQuarantines(Date.now());
+    if (reclaimed > 0) {
+      logger.info('daemon store reclaimed quarantined copies', {
+        store: this.options.fileName,
+        reclaimedFiles: reclaimed,
+        ttlDays: Math.round(CORRUPT_QUARANTINE_TTL_MS / (24 * 60 * 60 * 1000)),
+        keptNewest: MAX_CORRUPT_QUARANTINES,
+      });
     }
   }
 

package/src/input/command-registry.ts

@@ -121,6 +121,14 @@ export interface CommandUiActions {
     contextCap?: number | null;
     /** Which config target to write the selected model to. Defaults to 'main'. */
     target?: import('./model-picker.ts').ModelPickerTarget;
+    /**
+     * True only when `effort` came from the picker's effort STEP — an explicit
+     * user choice, which is the only thing allowed to update the stored
+     * preference `provider.reasoningEffort`. The model-only and context-cap
+     * commit routes pass a level merely carried over from the previous model;
+     * storing that is how a one-time snap down used to become permanent.
+     */
+    effortChosenByUser?: boolean;
   }) => void;
   /**
    * Commit an embedding-provider selection from the model picker's

package/src/input/commands/local-runtime.ts

@@ -56,7 +56,12 @@ function toggleBlocks(typeFilter: string, collapsed: boolean, ctx: CommandContex
       // every member regardless of its own key.
       if (!collapsed && block.type === 'tool_group' && block.groupMemberIndexes) {
         for (const memberIdx of block.groupMemberIndexes) {
-          ctx.session.conversationManager.setCollapsed(`msg_${memberIdx}`, false);
+          const memberKey = `msg_${memberIdx}`;
+          ctx.session.conversationManager.setCollapsed(memberKey, false);
+          // An explicit /expand is a deliberate user action on this key, same
+          // as Tab/Ctrl+Y/Ctrl+B — exempts it from search's close-time
+          // auto-re-collapse (see ConversationManager.noteUserTouch).
+          ctx.session.conversationManager.searchExpansion.noteUserTouch(memberKey);
         }
       }
       count++;

package/src/input/commands/schedule-runtime.ts

@@ -10,6 +10,7 @@ import type { AutomationManager } from '@pellux/goodvibes-sdk/platform/automatio
 import type { AutomationJob } from '@pellux/goodvibes-sdk/platform/automation';
 import type { AutomationScheduleDefinition } from '@pellux/goodvibes-sdk/platform/automation';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { REASONING_EFFORT_SEVERITY, reasoningEffortRank } from '@pellux/goodvibes-sdk/platform/providers';
 import { buildAutomationEmptyState } from '@pellux/goodvibes-sdk/platform/runtime/feature-announcements';
 import { parseNaturalLanguageSchedule } from './schedule-nl.ts';
 import type {
@@ -50,10 +51,22 @@ function parseAutomationTarget(raw: string | undefined): AutomationSessionTarget
   return { kind: 'session', sessionId: value, createIfMissing: true };
 }
 
+/**
+ * Validate a `--effort` argument.
+ *
+ * Not a fixed four-value list: which levels exist is per-model, so this checks
+ * the SDK's severity ladder, narrowed to the current model's own resolved
+ * levels whenever the runtime has published them. A scheduled job may well run
+ * on a different model than the one in use now, so a level this model does not
+ * offer is still accepted when it is a real level — it is re-resolved against
+ * whichever model actually serves the run.
+ */
 function parseReasoningEffort(raw: string | undefined): AutomationExecutionPolicy['reasoningEffort'] | undefined {
   if (!raw) return undefined;
-  if (raw === 'instant' || raw === 'low' || raw === 'medium' || raw === 'high') return raw;
-  throw new Error(`Invalid reasoning effort: "${raw}". Use instant, low, medium, or high.`);
+  if (reasoningEffortRank(raw) !== -1) return raw;
+  throw new Error(
+    `Invalid reasoning effort: "${raw}". Known levels: ${REASONING_EFFORT_SEVERITY.join(', ')}.`,
+  );
 }
 
 function parseWakeMode(raw: string | undefined): AutomationWakeMode | undefined {

package/src/input/commands/shell-core.ts

@@ -1,7 +1,16 @@
 import type { CommandRegistry } from '../command-registry.ts';
 import type { SelectionItem } from '../selection-modal.ts';
-import { EFFORT_DESCRIPTIONS } from '@pellux/goodvibes-sdk/platform/providers';
-import { REASONING_BUDGET_MAP } from '@pellux/goodvibes-sdk/platform/providers';
+import {
+  describeEffortForModel,
+  describeServingEffort,
+  effortPresentationForModel,
+  publishActiveEffortOptions,
+  requestedEffortLevel,
+  resolveEffortForModelSurface,
+  resolveRequestedEffortForServingModel,
+  servingEffortForLevel,
+  toEffortModel,
+} from '../../providers/reasoning-effort-surface.ts';
 import { executeWriteQuit } from './quit-shared.ts';
 import { compactConversation, requireKeybindingsManager, requireProviderApi, requireSessionMemoryStore } from './runtime-services.ts';
 import { buildCompactionPreview, buildCompactionAfterNotice, buildPinUsageText, buildPinSuccessText } from '../../renderer/compaction-preview.ts';
@@ -40,6 +49,22 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
             ctx.session.runtime.provider = selected.providerId;
             ctx.platform.configManager.set('provider.model', selected.registryKey);
             ctx.print(`Switched to model: ${selected.displayName} (${selected.providerId})`);
+            // The REQUESTED level may not exist on the model just selected.
+            // Re-resolve it here, exactly as the picker's commit path does, so
+            // `/model x` and picking x from the picker cannot disagree about
+            // what is actually being sent.
+            //
+            // The resolution reads config (the requested preference) and writes
+            // only the session's effective level. Writing the snapped value back
+            // over the preference is what used to make the downgrade permanent.
+            const switchedTo = toEffortModel(ctx.provider.providerRegistry.getCurrentModel());
+            publishActiveEffortOptions(switchedTo);
+            const serving = resolveRequestedEffortForServingModel(ctx.platform.configManager, switchedTo);
+            ctx.session.runtime.reasoningEffort = serving.effective ?? '';
+            if (serving.requested !== '') {
+              ctx.print(`Reasoning effort: ${describeServingEffort(serving, switchedTo)}`);
+              if (serving.note) ctx.print(serving.note);
+            }
             void providerApi.recordModelUsage(selected.registryKey).catch((err) => { logger.debug('model usage record failed', { err }); });
           });
         } catch (e) {
@@ -343,61 +368,85 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
     aliases: ['e'],
     description: 'Show or set reasoning effort level',
     usage: '[level]',
-    argsHint: '[instant|low|medium|high]',
+    // No fixed list here. The accepted levels belong to the serving model, so
+    // the old '[instant|low|medium|high]' hint was wrong for every model that
+    // offers 'none', 'minimal', 'xhigh' or 'max' — and for every model that
+    // rejects 'instant'. Running `/effort` with no argument prints the real
+    // ones for the model currently in use.
+    argsHint: '[level]',
     async handler(args, ctx) {
-      const currentModel = await requireProviderApi(ctx).getCurrentModel();
-      const validLevels = currentModel.reasoningEffort ?? [];
+      // The ModelDefinition (not the provider-api record) is what carries the
+      // structured ReasoningEffortSpec the honest wording is generated from.
+      const definition = ctx.provider.providerRegistry.getCurrentModel();
+      const model = toEffortModel(definition);
+      const presentation = effortPresentationForModel(model);
+      // Validation of provider.reasoningEffort now happens against these real
+      // levels rather than a fixed four-value list.
+      publishActiveEffortOptions(model);
 
-      if (validLevels.length === 0) {
-        ctx.print(`Current model (${currentModel.displayName}) does not support configurable reasoning effort.`);
+      if (!presentation.configurable) {
+        ctx.print(presentation.headline);
+        if (presentation.caveat) ctx.print(presentation.caveat);
         return;
       }
 
+      // The user's REQUESTED level, not the session's effective one: this
+      // command is where the preference is read back and re-chosen, so it must
+      // show what was asked for even while a capped model is serving.
+      const current = requestedEffortLevel(ctx.platform.configManager);
+      // What the list should open on, though, is the level in EFFECT — the
+      // requested level snapped to this model. The requested level may not be
+      // in the list at all when the model caps lower, and preselecting a
+      // missing id lands the cursor on the lowest level instead of on what is
+      // actually running.
+      const inEffect = servingEffortForLevel(current, model).effective ?? current;
+
+      const applyLevel = (level: string): void => {
+        // An explicit user choice — the one kind of write that is allowed to
+        // change the stored preference.
+        ctx.platform.configManager.set('provider.reasoningEffort', level);
+        const serving = servingEffortForLevel(level, model);
+        ctx.session.runtime.reasoningEffort = serving.effective ?? '';
+        ctx.print(`Reasoning effort set to: ${describeServingEffort(serving, model)}`);
+        if (serving.note) ctx.print(serving.note);
+      };
+
       if (args.length === 0) {
-        const current = (ctx.session.runtime.reasoningEffort || ctx.platform.configManager.get('provider.reasoningEffort') || 'medium') as string;
         if (ctx.openSelection) {
-          const descriptions: Record<string, string> = {
-            ...EFFORT_DESCRIPTIONS,
-            medium: 'Balanced speed and quality (default)',
-          };
-          const items: SelectionItem[] = validLevels.map((level) => ({
-            id: level,
-            label: level,
-            detail: level === current ? `◉ ${descriptions[level] ?? level}` : (descriptions[level] ?? level),
+          const items: SelectionItem[] = presentation.choices.map((choice) => ({
+            id: choice.level,
+            label: choice.level,
+            detail: choice.level === inEffect ? `\u25c9 ${choice.description}` : choice.description,
           }));
-          ctx.openSelection('Reasoning Effort', items, { preSelectId: current, allowSearch: false }, (result) => {
+          const options = { preSelectId: inEffect, allowSearch: false };
+          ctx.openSelection('Reasoning Effort', items, options, (result) => {
             if (!result) return;
-            const level = result.item.id as 'instant' | 'low' | 'medium' | 'high';
-            ctx.session.runtime.reasoningEffort = level;
-            ctx.platform.configManager.set('provider.reasoningEffort', level);
-            ctx.print(`Reasoning effort set to: ${level}`);
+            applyLevel(result.item.id);
             ctx.renderRequest();
           });
           return;
         }
-        const budget = REASONING_BUDGET_MAP[current];
-        const lines = [
-          `Reasoning effort: ${current}`,
-          `  Mercury-2:  reasoning_effort = '${current}'`,
-          `  Claude:     thinking.budget_tokens = ${budget}`,
-          `  Gemini:     thinking_config.thinking_budget = ${budget}`,
-          `  GPT-5:      (no-op)`,
-          '',
-          `Levels: ${validLevels.join(', ')}`,
-        ];
-        ctx.print(lines.join('\n'));
+        ctx.print(describeEffortForModel(model, current || undefined).join('\n'));
         return;
       }
 
-      const level = args[0] as 'instant' | 'low' | 'medium' | 'high';
-      if (!validLevels.includes(level)) {
-        ctx.print(`Invalid effort level: ${level}\nValid levels: ${validLevels.join(', ')}`);
+      const requested = args[0]!;
+      if (!presentation.choices.some((choice) => choice.level === requested)) {
+        const offered = presentation.choices.map((choice) => choice.level).join(', ');
+        // Name the model: "invalid" alone reads as a typo when the real reason
+        // is that this particular model does not offer the level.
+        const lines = [
+          `${definition.displayName} does not offer reasoning effort '${requested}'.`,
+          `Levels it offers: ${offered}`,
+        ];
+        const resolved = resolveEffortForModelSurface(requested, model);
+        if (resolved.note) lines.push(resolved.note);
+        if (presentation.caveat) lines.push(presentation.caveat);
+        ctx.print(lines.join('\n'));
         return;
       }
 
-      ctx.session.runtime.reasoningEffort = level;
-      ctx.platform.configManager.set('provider.reasoningEffort', level);
-      ctx.print(`Reasoning effort set to: ${level}`);
+      applyLevel(requested);
     },
   });