feat(custom-model): ask which model on launch when an endpoint has more than one, and re-discover models every 5 minutes

Two enhancements requested after live-validating PR #430 against a real
llama.cpp server:

1. Model picker dialog. Picking a Run-menu Custom Endpoints entry used to
   apply the endpoint's defaultModelId (or the first discovered model)
   silently. Now, via the new selectCustomModelEntry() (session-ui.js):
   - exactly one discovered model launches straight away, same as before
   - two or more open a new #customModelPickModal listing every discovered
     model; defaultModelId (if set) is marked but never auto-chosen, since
     the point of asking is letting ONE launch deliberately differ from
     the saved default, not just confirming it
   The endpoint is re-fetched at click time rather than trusting anything
   cached from the dropdown's own render, since the model list can have
   changed (the sweep below, or a settings-panel edit) since it opened.
   runCustomModelEntry() itself — the actual launch, routed through run()
   for the in-flight lock, snapshot-guarded against applying to the wrong
   session — is unchanged; it now just always receives an explicit model
   id from one of these two paths instead of computing one itself.

2. Periodic re-discovery. Every saved endpoint's models now refresh
   automatically every 5 minutes in the background
   (CUSTOM_MODEL_REDISCOVER_INTERVAL_MS, server.ts, registered the same way
   as the Codex plan-usage poll it sits beside — this.cleanup.setInterval,
   off under testMode), so a model the server starts or stops serving shows
   up without another manual "Discover" click. The manual POST
   .../discover-models route and the new refreshAllCustomModelHosts()
   sweep (custom-model-routes.ts) now share one pure merge step
   (applyDiscoveredModels: stamps lastDiscoveredAt, drops a defaultModelId
   that no longer appears) rather than two copies that could drift. The
   sweep is best-effort per host — one endpoint being unreachable on a
   cycle never blocks the others — and re-reads the store before each
   host's write, keyed by id, so a concurrent edit or delete from the
   settings panel always wins over a sweep that started before it.

Tests: test/custom-model-endpoint-rediscovery.test.ts is a new, dedicated
file for the sweep (kept separate from custom-model-routes.test.ts because
that file's data dir is shared across every test in it — one temp HOME per
FILE, not per test — which would make a sweep-touches-every-host assertion
meaningless there). test/custom-model-run-menu-ui.test.ts gained a new
describe block driving the real picker modal through JSDOM: single-model
bypass, multi-model dialog with the default marked-not-chosen, picking a
row closes the modal and launches with that exact model, the endpoint
re-fetch, and the two "vanished by click time" toast paths.

Docs: docs/custom-model-endpoints.md, docs/wiki/Custom-Model-Endpoints.md,
docs/api-reference.md and CLAUDE.md's dense feature paragraph all updated
— the last of these also caught up two sentences that had gone stale after
the draft-review fixes landed (the picker routes through run() now, not a
raw run*() call).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RqZeHrRS6DYcGcGX2p9EwG

src/web/public/i18n.js

@@ -311,6 +311,9 @@
     'What the Run-menu picker applies for this endpoint. Discover models first.':
       '运行菜单选择器会为此端点应用该模型。请先发现可用模型。',
     'Custom Endpoints': '自定义端点',
+    'Choose a model': '选择模型',
+    'That endpoint no longer exists': '该端点已不存在',
+    'No models discovered for this endpoint yet': '此端点尚未发现任何模型',
     'Subagent Options': '子智能体选项',
     'Enable Tracking': '启用跟踪',
     'Active Tab Only': '仅活动标签页',

src/web/public/index.html

@@ -910,6 +910,23 @@
       </div>
     </div>
 
+    <!-- Custom Model Endpoint Profiles: "which model" picker (docs/custom-model-endpoints-plan.md).
+         Shown only when the chosen endpoint has more than one discovered model — see
+         selectCustomModelEntry() in session-ui.js, which skips straight to launch otherwise. -->
+    <div class="modal" id="customModelPickModal">
+      <div class="modal-backdrop" onclick="app.closeCustomModelPickModal()"></div>
+      <div class="modal-content" style="max-width: 380px;">
+        <div class="modal-header">
+          <h3 id="customModelPickTitle">Choose a model</h3>
+          <button class="modal-close" onclick="app.closeCustomModelPickModal()" aria-label="Close model picker">&times;</button>
+        </div>
+        <div class="modal-body">
+          <p class="form-hint" id="customModelPickHint"></p>
+          <div id="customModelPickList" class="run-mode-custom-models"></div>
+        </div>
+      </div>
+    </div>
+
     <!-- Cron Jobs Modal -->
     <div class="modal" id="cronModal">
       <div class="modal-backdrop" onclick="app.closeCron()"></div>

src/web/public/session-ui.js

@@ -579,8 +579,9 @@ Object.assign(CodemanApp.prototype, {
 
     const rows = [];
     for (const host of hosts) {
-      const modelId = host.defaultModelId || (host.models || [])[0];
-      if (!modelId) continue; // nothing discovered yet — the settings panel explains why
+      const models = host.models || [];
+      if (models.length === 0) continue; // nothing discovered yet — the settings panel explains why
+      const modelId = host.defaultModelId || models[0];
       for (const cli of capableClis) {
         // escapeHtml(JSON.stringify(...)) on EVERY arg, not just the untrusted
         // one: JSON.stringify's own double quotes would otherwise terminate this
@@ -589,11 +590,11 @@ Object.assign(CodemanApp.prototype, {
         // modelId (server-controlled, from the endpoint's own /v1/models reply,
         // not this box's) into markup instead of inert data. Same idiom as
         // deleteCase's onclick a few hundred lines down.
-        const args = [cli.id, host.id, modelId].map((v) => escapeHtml(JSON.stringify(v))).join(', ');
+        const args = [cli.id, host.id].map((v) => escapeHtml(JSON.stringify(v))).join(', ');
         rows.push(`
           <button class="run-mode-option" data-mode="${escapeHtml(cli.id)}" data-endpoint="${escapeHtml(host.id)}"
-                  onclick="app.runCustomModelEntry(${args})"
-                  title="${escapeHtml(cli.label)} → ${escapeHtml(host.baseUrl)} (${escapeHtml(modelId)})">
+                  onclick="app.selectCustomModelEntry(${args})"
+                  title="${escapeHtml(cli.label)} → ${escapeHtml(host.baseUrl)} (${escapeHtml(modelId)}${models.length > 1 ? `, +${models.length - 1} more` : ''})">
             <span class="run-mode-dot ${escapeHtml(cli.id)}"></span>${escapeHtml(cli.label)} (${escapeHtml(host.label)})
           </button>`);
       }
@@ -604,6 +605,76 @@ Object.assign(CodemanApp.prototype, {
     container.innerHTML = rows.join('');
   },
 
+  /**
+   * Decides whether picking a Run-menu Custom Endpoint entry can launch
+   * straight away or needs to ask which model first. Re-fetches the endpoint
+   * rather than trusting anything cached from the menu render: the models
+   * list (or the default) could have changed — a re-discovery cycle running
+   * every 5 minutes in the background, or an edit in the settings panel —
+   * between opening the dropdown and clicking a row.
+   */
+  async selectCustomModelEntry(mode, endpointId) {
+    document.getElementById('runModeMenu')?.classList.remove('active');
+    const hosts = await this._apiJson('/api/model-endpoints');
+    const host = (hosts || []).find((h) => h.id === endpointId);
+    if (!host) {
+      this.showToast('That endpoint no longer exists', 'error');
+      return;
+    }
+    const models = host.models || [];
+    if (models.length === 0) {
+      this.showToast('No models discovered for this endpoint yet', 'warning');
+      return;
+    }
+    // Exactly one model: nothing to choose, so asking would just be an extra
+    // click for the same answer every time. Two or more: always ask, even
+    // with a defaultModelId set — the point of asking is letting THIS launch
+    // differ from the default, not just confirming it.
+    if (models.length === 1) {
+      return this.runCustomModelEntry(mode, endpointId, models[0]);
+    }
+    this._openCustomModelPickModal(mode, host);
+  },
+
+  /** Renders the "which model" picker for a (harness, endpoint) pair with more than one discovered model. */
+  _openCustomModelPickModal(mode, host) {
+    const modal = document.getElementById('customModelPickModal');
+    const list = document.getElementById('customModelPickList');
+    if (!modal || !list) return;
+    this._pendingCustomModelPick = { mode, endpointId: host.id };
+    const cliLabel = (window.__codemanCustomModelClis || []).find((c) => c.id === mode)?.label || mode;
+    // A static title (translatable by i18n.js's exact-string walker) plus a
+    // dynamic hint carrying the specifics — same split webviewModalTitle uses,
+    // since the walker cannot i18n a string a variable is already spliced into.
+    document.getElementById('customModelPickTitle').textContent = 'Choose a model';
+    document.getElementById('customModelPickHint').textContent =
+      `${cliLabel} → ${host.label} — ${(host.models || []).length} models discovered.`;
+    list.innerHTML = (host.models || [])
+      .map((m) => {
+        const isDefault = m === host.defaultModelId;
+        const arg = escapeHtml(JSON.stringify(m));
+        return `
+          <button class="run-mode-option" onclick="app.chooseCustomModelAndRun(${arg})">
+            <span class="run-mode-dot ${escapeHtml(mode)}"></span>${escapeHtml(m)}${isDefault ? ' <span class="set-scope">Default</span>' : ''}
+          </button>`;
+      })
+      .join('');
+    modal.classList.add('active');
+  },
+
+  closeCustomModelPickModal() {
+    document.getElementById('customModelPickModal')?.classList.remove('active');
+    this._pendingCustomModelPick = null;
+  },
+
+  /** A model row in the picker modal was clicked: close it and launch with that choice. */
+  chooseCustomModelAndRun(modelId) {
+    const pending = this._pendingCustomModelPick;
+    this.closeCustomModelPickModal();
+    if (!pending) return; // modal reopened/closed from elsewhere between render and click
+    void this.runCustomModelEntry(pending.mode, pending.endpointId, modelId);
+  },
+
   /**
    * Runs a session on `mode` and immediately applies `endpointId`/`modelId` to it
    * via POST /api/sessions/:id/custom-model (see session-routes.ts) — the same

src/web/routes/custom-model-routes.ts

@@ -107,6 +107,51 @@ function describeFetchError(err: unknown): string {
 
 type RedactedHost = ReturnType<typeof redactApiKey>;
 
+/**
+ * Merges a fresh `GET /v1/models` result into a host record: stamps
+ * `lastDiscoveredAt`, and drops `defaultModelId` if it no longer appears in
+ * the fresh list (it would otherwise leave the Run-menu picker applying a
+ * model id the endpoint just told us it doesn't serve). Pure — no IO, so the
+ * manual route (which reports a fetch failure's *reason* to the caller) and
+ * the periodic sweep below (which only cares whether it can move on) can
+ * each do their own `discoverModels()` + error handling around one shared
+ * "how to apply a successful result" step.
+ */
+function applyDiscoveredModels(host: CustomModelHost, models: string[]): CustomModelHost {
+  const defaultModelId = host.defaultModelId && models.includes(host.defaultModelId) ? host.defaultModelId : undefined;
+  return { ...host, models, defaultModelId, lastDiscoveredAt: new Date().toISOString() };
+}
+
+/**
+ * Re-discovers every saved endpoint's models, best-effort. One endpoint being
+ * unreachable (powered off, wrong network) must not stop the others from
+ * refreshing, and a read-modify-write per host (rather than one batch write
+ * at the end) means a crash or restart mid-sweep loses at most the endpoints
+ * not yet reached, never a write already applied. Exported so both the
+ * periodic timer (server.ts) and a test can drive it directly.
+ */
+export async function refreshAllCustomModelHosts(): Promise<void> {
+  const dataDir = getDataDir();
+  const hosts = await readCustomModelHosts(dataDir);
+  for (const host of hosts) {
+    if (isBlockedWebviewUrl(host.baseUrl)) continue;
+    let models: string[];
+    try {
+      models = await discoverModels(host);
+    } catch {
+      continue; // unreachable this cycle — try again next tick, not fatal to the sweep
+    }
+    // Re-read + splice by id rather than reusing the array captured above: an
+    // admin editing or deleting an endpoint via the API mid-sweep must win,
+    // not be silently overwritten by a refresh that started before their change.
+    const current = await readCustomModelHosts(dataDir);
+    const index = current.findIndex((item) => item.id === host.id);
+    if (index === -1) continue; // deleted mid-sweep
+    current[index] = applyDiscoveredModels(current[index], models);
+    await writeCustomModelHosts(dataDir, current);
+  }
+}
+
 export function registerCustomModelRoutes(app: FastifyInstance): void {
   app.get('/api/model-endpoints', async (req): Promise<RedactedHost[]> => {
     if (isMultiUserMode() && !isAdmin(req)) return [];
@@ -179,12 +224,7 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
       try {
         const models = await discoverModels(host);
         const next = [...hosts];
-        // A default that no longer appears in the fresh list would leave the Run-menu
-        // picker applying a model id the endpoint just told us it doesn't serve; drop
-        // it rather than carry it forward silently invalid.
-        const defaultModelId =
-          host.defaultModelId && models.includes(host.defaultModelId) ? host.defaultModelId : undefined;
-        next[index] = { ...host, models, defaultModelId, lastDiscoveredAt: new Date().toISOString() };
+        next[index] = applyDiscoveredModels(host, models);
         await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
         return { success: true, data: { models } };
       } catch (err) {

src/web/routes/index.ts

@@ -27,4 +27,4 @@ export { registerWsRoutes } from './ws-routes.js';
 export { registerVoiceRoutes } from './voice-routes.js';
 export { registerWebviewRoutes, tryWebviewRefererFallback } from './webview-routes.js';
 export { registerTabLayoutRoutes } from './tab-layout-routes.js';
-export { registerCustomModelRoutes } from './custom-model-routes.js';
+export { registerCustomModelRoutes, refreshAllCustomModelHosts } from './custom-model-routes.js';

src/web/server.ts

@@ -190,6 +190,7 @@ import {
   registerWebviewRoutes,
   registerTabLayoutRoutes,
   registerCustomModelRoutes,
+  refreshAllCustomModelHosts,
   tryWebviewRefererFallback,
 } from './routes/index.js';
 import { isLostWebviewFrameNavigation } from './webview-proxy.js';
@@ -202,6 +203,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // while capping growth of `sseClientsById` and blocking pathological inputs.
 const SSE_CLIENT_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
 const CODEX_USAGE_POLL_INTERVAL_MS = 5 * 60_000;
+const CUSTOM_MODEL_REDISCOVER_INTERVAL_MS = 5 * 60_000;
 
 function escapeHtmlText(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
@@ -2734,6 +2736,25 @@ export class WebServer extends EventEmitter {
       });
     }
 
+    // Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md): keeps
+    // each saved endpoint's discovered model list current with no manual
+    // "Discover" click, so a model added on the server side (or one that drops
+    // off) shows up in the Run-menu picker within one cycle. Best-effort per
+    // endpoint (refreshAllCustomModelHosts skips one that's unreachable rather
+    // than failing the sweep) and off in tests for the same reason the Codex
+    // poll above is — no real network to hit, no server instance to keep alive.
+    if (!this.testMode) {
+      this.cleanup.setInterval(
+        () => {
+          refreshAllCustomModelHosts().catch((err) => {
+            console.error('[custom-model] periodic re-discovery failed:', getErrorMessage(err));
+          });
+        },
+        CUSTOM_MODEL_REDISCOVER_INTERVAL_MS,
+        { description: 'custom model endpoint re-discovery' }
+      );
+    }
+
     // Start scheduled runs cleanup timer
     this.cleanup.setInterval(
       () => {