mixdog 1.4.0 → 1.4.2

package/src/tui/app/provider-setup/api-key-actions.mjs

@@ -6,9 +6,13 @@ import { openInBrowser } from '../../../runtime/shared/open-url.mjs';
 import { providerDetailText } from '../app-format.mjs';
 import { forgetProviderAuth, keyConsoleUrl, providerStatusFooter } from './provider-items.mjs';
 
-const setApiKeyPrompt = (flow, providerItem) => {
+const VERTEX_EXPRESS_HINT =
+  'Express mode API keys serve Gemini models on the global location only. Claude and MaaS models need a service-account key or the gcloud login.';
+
+const setApiKeyPrompt = (flow, providerItem, extra = {}) => {
   if (!flow.ownsSurface()) return;
   flow.setProviderPrompt({
+    ...extra,
     kind: 'api-key',
     providerId: providerItem._providerId,
     label: providerItem._providerName,
@@ -51,6 +55,28 @@ function apiKeyActions(providerItem, provider) {
   return { apiActions, keyUrl };
 }
 
+// Vertex AI takes either a service-account key or an express-mode API key.
+function openVertexModePicker(flow, providerItem) {
+  flow.paint({
+    title: `Provider · ${providerItem._providerName}`,
+    description: 'Choose the Vertex AI key type.',
+    help: '↑/↓ Select · Enter Choose · Esc Back',
+    indexMode: 'always',
+    labelWidth: 22,
+    pickerKey: `providers-vertex-mode:${providerItem.value}`,
+    initialIndex: 0,
+    items: [
+      { value: 'service-account', label: 'Service account key', description: 'service-account JSON' },
+      { value: 'api-key', label: 'API key (express mode)', description: 'Gemini only · global location' },
+    ],
+    onSelect: (mode) => {
+      flow.releaseSurface();
+      setApiKeyPrompt(flow, providerItem, mode === 'api-key' ? { authMode: 'api-key', hint: VERTEX_EXPRESS_HINT } : {});
+    },
+    onCancel: () => openApiProviderActions(flow, providerItem),
+  });
+}
+
 export function openApiProviderActions(flow, providerItem) {
   // Reached from acks (a failed forget-key) as well as key presses: prove
   // ownership at the sink so every caller is covered.
@@ -69,6 +95,10 @@ export function openApiProviderActions(flow, providerItem) {
     initialIndex: 0,
     items: apiActions,
     onSelect: (_detailValue, detail) => {
+      if (detail._action === 'set-key' && providerItem._providerId === 'vertex-ai') {
+        openVertexModePicker(flow, providerItem);
+        return;
+      }
       flow.releaseSurface();
       if (detail._action === 'set-key') {
         setApiKeyPrompt(flow, providerItem);

package/src/tui/app/provider-setup/oauth-actions.mjs

@@ -3,6 +3,7 @@
 // progress and result panels, the interactive (code prompt) login through
 // store.beginOAuthProviderLogin, and the legacy store.loginOAuthProvider
 // path. `flow` is the per-open picker state built by provider-setup-picker.mjs.
+import { canOpenBrowser } from '../../../runtime/shared/open-url.mjs';
 import { providerDetailText } from '../app-format.mjs';
 import { forgetProviderAuth, providerStatusFooter } from './provider-items.mjs';
 
@@ -15,11 +16,21 @@ const panelFrame = (providerItem, provider, pickerKey) => ({
   initialIndex: 0,
 });
 
-function showOAuthProgress(flow, providerItem, message, onBack) {
+// Shown with every device code: a code someone else hands you signs THEM in to your account.
+// One row that fits 80 columns: it takes the row the status footer did, so the URL
+// keeps its copy-hint row and the "Enter code" line is never replaced by the copy note.
+const DEVICE_CODE_WARNING = [
+  { glyph: '!', text: 'Continue only if you started this. Never enter a code someone sent you.' },
+];
+
+function showOAuthProgress(flow, providerItem, message, onBack, detail = '', footer = null) {
   const provider = providerItem._provider || {};
+  const frame = panelFrame(providerItem, provider, `providers-oauth-progress:${providerItem.value}`);
   flow.paint({
-    ...panelFrame(providerItem, provider, `providers-oauth-progress:${providerItem.value}`),
+    ...frame,
+    ...(footer ? { footer } : {}),
     description: message,
+    detail,
     help: '↑/↓ Select · Enter Choose · Esc Providers',
     indexMode: 'never',
     items: [
@@ -27,7 +38,7 @@ function showOAuthProgress(flow, providerItem, message, onBack) {
         value: 'waiting',
         label: 'Waiting for login',
         meta: 'Running',
-        description: 'finish the browser/OAuth prompt',
+        description: 'finish the sign-in shown above',
         _action: 'waiting',
       },
       {
@@ -71,6 +82,21 @@ function showOAuthResult(flow, providerItem, ok, message = '') {
   });
 }
 
+function oauthCodeHint(manualUrl, loginUrl, providerName) {
+  if (manualUrl) return 'If the browser callback does not finish, open the URL below manually and paste code#state.';
+  if (loginUrl) {
+    return `Open the URL below to sign in, then paste the authorization code or full redirect URL for ${providerName}.`;
+  }
+  return `Paste the authorization code or full redirect URL for ${providerName}.`;
+}
+
+// The URL goes in the picker's wrapped `detail` block, never the one-line description.
+function pollingLoginMessage(userCode, loginUrl, opened) {
+  if (userCode) return { message: `Enter code ${userCode} at${opened}:`, detail: loginUrl };
+  if (loginUrl) return { message: `Open this URL to sign in${opened}:`, detail: loginUrl };
+  return { message: 'Finish signing in for this provider.', detail: '' };
+}
+
 /** Login through store.beginOAuthProviderLogin: a code-completing login hands
  *  the surface to the OAuth code prompt; the callback (or the prompt) finishes. */
 function beginInteractiveOAuthLogin(flow, providerItem, login) {
@@ -91,26 +117,26 @@ function beginInteractiveOAuthLogin(flow, providerItem, login) {
       message || (ok ? `${providerName} login complete.` : `${providerName} login failed.`)
     );
   };
+  // Headless machines never try a browser; the URL is shown in the panel either way.
+  const openBrowser = canOpenBrowser();
   void flow.store
-    .beginOAuthProviderLogin(providerItem._providerId)
+    .beginOAuthProviderLogin(providerItem._providerId, { openBrowser })
     .then((started) => {
+      const loginUrl = started?.manualUrl || started?.url || '';
       if (typeof started?.completeCode === 'function') {
         // Post-await handover to the OAuth code prompt: only if this flow
         // still owns the surface (Esc during beginOAuthProviderLogin).
         if (!flow.ownsSurface()) return;
         flow.releaseSurface();
-        const manualUrl = started?.manualUrl || '';
         flow.setProviderPrompt({
           kind: 'oauth-code',
           providerId: providerItem._providerId,
           providerName,
           label: `${providerName} OAuth code`,
-          hint: manualUrl
-            ? 'If the browser callback does not finish, open the URL below manually and paste code#state.'
-            : `Paste the authorization code or full redirect URL for ${providerName}.`,
+          hint: oauthCodeHint(started?.manualUrl, loginUrl, providerName),
           // Shown inside the live panel only — never written to the
           // transcript, so it cannot linger in scrollback after the flow.
-          detail: manualUrl,
+          detail: loginUrl,
           login: started,
           afterSave: flow.returnTo,
           successReturn: () => {
@@ -124,16 +150,24 @@ function beginInteractiveOAuthLogin(flow, providerItem, login) {
           },
         });
         flow.store.pushNotice(
-          `browser opened for ${providerName}; paste code/redirect here if callback does not finish`,
+          openBrowser
+            ? `browser opened for ${providerName}; paste code/redirect here if callback does not finish`
+            : `open the URL shown to sign in to ${providerName}, then paste the code/redirect here`,
           'info'
         );
-      } else if (started?.userCode) {
-        flow.store.pushNotice(
-          `${providerName}: enter code ${started.userCode} in the browser to finish signing in`,
-          'info'
+      } else if (!login.backedOut && flow.ownsSurface()) {
+        // Device-code and URL-only polling logins stay in the progress panel,
+        // with the code and URL, until the result panel replaces it or Back.
+        const opened = openBrowser ? ' (browser opened)' : '';
+        const { message, detail } = pollingLoginMessage(started?.userCode, loginUrl, opened);
+        showOAuthProgress(
+          flow,
+          providerItem,
+          message,
+          login.onBack,
+          detail,
+          started?.userCode ? () => DEVICE_CODE_WARNING : null
         );
-      } else {
-        flow.store.pushNotice(`browser opened for ${providerName}; finish signing in there`, 'info');
       }
       started.waitForCallback
         ?.then((result) => {
@@ -171,11 +205,14 @@ function runLegacyOAuthLogin(flow, providerItem, login) {
 function startOAuthLogin(flow, providerItem) {
   // Back on the progress panel returns to the actions; a login that settles
   // afterwards becomes a notice instead of a result panel.
-  const login = { backedOut: false };
-  showOAuthProgress(flow, providerItem, 'Opening login flow. Complete it in the browser if prompted.', () => {
-    login.backedOut = true;
-    openOAuthProviderActions(flow, providerItem);
-  });
+  const login = {
+    backedOut: false,
+    onBack: () => {
+      login.backedOut = true;
+      openOAuthProviderActions(flow, providerItem);
+    },
+  };
+  showOAuthProgress(flow, providerItem, 'Starting login flow…', login.onBack);
   if (typeof flow.store.beginOAuthProviderLogin === 'function') {
     beginInteractiveOAuthLogin(flow, providerItem, login);
     return;

package/src/tui/app/provider-setup/provider-items.mjs

@@ -80,8 +80,14 @@ export function buildProviderItems(setup) {
   if (setup.managedByClient === true) {
     for (const p of setup.local || []) {
       providerItems.push({
-        value: `local:${p.id}`, label: p.name, meta: providerStatusLabel(p), description: '',
-        _type: 'local', _providerId: p.id, _providerName: p.name, _provider: p,
+        value: `local:${p.id}`,
+        label: p.name,
+        meta: providerStatusLabel(p),
+        description: '',
+        _type: 'local',
+        _providerId: p.id,
+        _providerName: p.name,
+        _provider: p,
       });
     }
   }

package/src/tui/app/provider-setup-picker.mjs

@@ -18,6 +18,25 @@ import {
 
 const providerFooter = (item) => providerStatusFooter(item?._provider);
 
+/** The rows of the main provider list: the continue row, one row per provider,
+ *  and the client refresh row. */
+function mainListItems(setup, options, canContinue) {
+  const items = [];
+  if (canContinue && !options.confirmBar) {
+    items.push({
+      value: 'continue-setup',
+      label: options.continueLabel || 'Continue setup',
+      description: options.continueDescription || 'return to setup',
+      _type: 'continue',
+    });
+  }
+  items.push(...buildProviderItems(setup));
+  if (setup.managedByClient === true) {
+    items.push({ value: 'refresh-client-providers', label: 'Refresh', _type: 'refresh-client-providers' });
+  }
+  return items;
+}
+
 export function createProviderSetupPicker({
   store,
   surface,
@@ -87,19 +106,7 @@ export function createProviderSetupPicker({
       if (!setup) return;
     }
 
-    const items = [];
-    if ((returnTo || onContinue) && !options.confirmBar) {
-      items.push({
-        value: 'continue-setup',
-        label: options.continueLabel || 'Continue setup',
-        description: options.continueDescription || 'return to setup',
-        _type: 'continue',
-      });
-    }
-    items.push(...buildProviderItems(setup));
-    if (setup.managedByClient === true) {
-      items.push({ value: 'refresh-client-providers', label: 'Refresh', _type: 'refresh-client-providers' });
-    }
+    const items = mainListItems(setup, options, Boolean(returnTo || onContinue));
 
     const flow = {
       store,
@@ -129,13 +136,17 @@ export function createProviderSetupPicker({
 
     flow.paint({
       title: options.title || 'Providers',
-      description: setup.managedByClient === true
-        ? 'Manage provider sign-ins and accounts in the local desktop window. Refresh to update availability.'
-        : options.description || 'Choose a provider. Enter opens provider actions.',
+      description:
+        setup.managedByClient === true
+          ? 'Manage provider sign-ins and accounts in the local desktop window. Refresh to update availability.'
+          : options.description || 'Choose a provider. Enter opens provider actions.',
       footer: providerFooter,
       footerGapRows: 1,
-      help: options.confirmBar ? undefined : setup.managedByClient === true
-        ? '↑/↓ Select · Enter Refresh · Esc Back' : '↑/↓ Select · Enter Open · Esc Back',
+      help: options.confirmBar
+        ? undefined
+        : setup.managedByClient === true
+          ? '↑/↓ Select · Enter Refresh · Esc Back'
+          : '↑/↓ Select · Enter Open · Esc Back',
       indexMode: 'always',
       labelWidth: 18,
       metaWidth: 12,

package/src/tui/app/shell-layout/row-budgets.mjs

@@ -4,8 +4,9 @@
  * welcome banner, floating panel, and the layout signature that names them.
  */
 import { isLiveSpinnerMetaVisible } from '../live-spinner-visibility.mjs';
-import { promptContentRows, wrappedDetailRows, queuedBandRows } from '../text-layout.mjs';
+import { promptContentRows, queuedBandRows } from '../text-layout.mjs';
 import { questionPanelRows, questionsOf } from '../../components/question-panel-model.mjs';
+import { signInUrlLayout } from '../../components/sign-in-url-layout.mjs';
 import { CORE_MULTILINE_TEXT_ENTRY_KINDS } from '../panel-signature.mjs';
 import { btwPanelRows } from '../btw-controller.mjs';
 
@@ -49,24 +50,25 @@ function promptBoxBudget(inputBoxHidden, promptLayoutValueRef, promptContentColu
 
 // TextEntryPanel content is one prompt line (chrome + 1) for single-line
 // prompts, or up to PANEL_MAX_VISIBLE wrapped rows for core memory add/edit.
-// PLUS an optional wrapped detail block (blank spacer + N wrapped rows — e.g.
-// the manual OAuth URL). The floating container clips from the TOP (flex-end +
+// PLUS an optional borderless sign-in URL block under the panel (the manual
+// OAuth URL). The floating container clips from the TOP (flex-end +
 // overflow hidden), so under-reserving here pushed the bordered title off
-// the top of the panel. Width matches the panel interior: frame − 2 border
-// − 2 paddingX, same wrap-ansi math ink uses for wrap="wrap".
-function textEntryBudget(textEntryPrompt, textEntryLayoutRows, frameColumns) {
+// the top of the panel. The block gets only the rows the terminal leaves
+// (maxFloatingPanelRows minus chrome and content) and TextEntryPanel degrades
+// it to fit, using the same sign-in-url-layout math.
+function textEntryBudget(textEntryPrompt, textEntryLayoutRows, frameColumns, maxFloatingPanelRows) {
   const textEntryKind = String(textEntryPrompt?.kind || '');
   const textEntryMultiline = CORE_MULTILINE_TEXT_ENTRY_KINDS.has(textEntryKind);
   const textEntryDetailText = String(textEntryPrompt?.detail || '').trim();
-  const textEntryDetailRows = textEntryDetailText
-    ? 1 + wrappedDetailRows(textEntryDetailText, Math.max(1, frameColumns - 4))
-    : 0;
   const textEntryContentRows = textEntryMultiline ? textEntryLayoutRows : 1;
+  const textEntryUrlMaxRows = Math.max(0, maxFloatingPanelRows - PANEL_CHROME_ROWS - textEntryContentRows);
+  const textEntryDetailRows = signInUrlLayout(textEntryDetailText, frameColumns, textEntryUrlMaxRows).rows;
   return {
     textEntryKind,
     textEntryMultiline,
     textEntryDetailText,
     textEntryDetailRows,
+    textEntryUrlMaxRows,
     textEntryContentRows,
     TEXT_ENTRY_ROWS: PANEL_CHROME_ROWS + textEntryContentRows + textEntryDetailRows,
   };
@@ -187,7 +189,6 @@ export function computeRowBudgets({
   const { textEntryPrompt, hasTextEntryPrompt, hasFloatingPanel, expandedOptionPanel, inputBoxHidden } = surfaces;
   const { liveSpinner, liveSpinnerIsCommand, latestTranscriptItem, inputHint } = hints;
   const prompt = promptBoxBudget(inputBoxHidden, promptLayoutValueRef, promptContentColumns);
-  const textEntry = textEntryBudget(textEntryPrompt, textEntryLayoutRows, frameColumns);
   const OPTION_PANEL_EXTRA_ROWS = expandedOptionPanel ? 3 : 0;
   const queuedVisible = !hasFloatingPanel && !inputBoxHidden && state.queued?.length > 0;
   // While the slash palette is open it owns the area above the prompt, so the
@@ -214,6 +215,7 @@ export function computeRowBudgets({
   const baseReserve =
     welcome.WELCOME_ROWS + SCROLL_HINT_ROWS + LIVE_STATUS_ROWS + INPUT_BOX_ROWS + STATUSLINE_ROWS + queued.queuedRows;
   const maxFloatingPanelRows = Math.max(0, resizeState.rows - baseReserve - 1);
+  const textEntry = textEntryBudget(textEntryPrompt, textEntryLayoutRows, frameColumns, maxFloatingPanelRows);
   const panel = floatingPanelBudget({
     toolApproval,
     picker,

package/src/tui/app/slash-commands.mjs

@@ -41,6 +41,7 @@ export const SLASH_COMMANDS = [
     params: '[release <task_id> [--confirm]]',
     description: 'List shells; release one whose termination is unconfirmed',
   },
+  { name: 'stop', usage: '/stop', description: 'Stop every background shell of this session' },
   {
     name: 'fork',
     usage: '/fork',

package/src/tui/app/slash-dispatch/session-commands.mjs

@@ -4,6 +4,7 @@
 // while a turn or session command is running.
 import { presentErrorText } from '../../../runtime/shared/err-text.mjs';
 import { BTW_USAGE_HINT } from '../btw-controller.mjs';
+import { theme } from '../../theme.mjs';
 
 function compactFailureNotice(error) {
   if (error == null || String(error).trim() === '') return 'Compact failed.';
@@ -168,6 +169,51 @@ export const sessionCommands = {
     return true;
   },
 
+  // /stop — stop every background shell of this session (never the running
+  // foreground command, agents or other sessions) after one confirmation.
+  stop(ctx) {
+    const { store, surface } = ctx;
+    const stopAll = () =>
+      Promise.resolve(store.stopShellJobs?.())
+        .then((result) => {
+          const stopped = result?.stopped || 0;
+          const stopping = result?.stopping || 0;
+          store.pushNotice(
+            stopping
+              ? `Stopped background shells: ${stopped} · still stopping: ${stopping}`
+              : `Stopped background shells: ${stopped}`,
+            stopping ? 'warn' : 'info'
+          );
+        })
+        .catch((error) => store.pushNotice(String(error?.message || error), 'error'));
+    void Promise.resolve(store.listStoppableShellJobs?.())
+      .then((result) => {
+        const jobs = Array.isArray(result?.jobs) ? result.jobs : [];
+        if (!jobs.length) {
+          store.pushNotice('No background shells are running.', 'info');
+          return;
+        }
+        const own = surface.claim();
+        own.paint({
+          title: `Stop background shells (${jobs.length})?`,
+          indexMode: 'always',
+          labelWidth: 12,
+          items: [
+            { value: 'cancel', label: 'Cancel' },
+            { value: 'stop', label: 'Stop' },
+          ],
+          footer: jobs.map((job) => ({ glyph: '·', color: theme.warning, text: job.command })),
+          onSelect: (value) => {
+            own.close();
+            if (value === 'stop') void stopAll();
+          },
+          onCancel: () => own.close(),
+        });
+      })
+      .catch((error) => store.pushNotice(String(error?.message || error), 'error'));
+    return true;
+  },
+
   doctor(ctx) {
     const { state, store, deps } = ctx;
     if (state.commandBusy) {

package/src/tui/app/slash-dispatch.mjs

@@ -17,7 +17,7 @@ import { createSlashPanelOpener } from './slash-dispatch/slash-panel.mjs';
 const commands = { ...routeCommands, ...sessionCommands, ...panelCommands };
 
 export function createSlashDispatch({ state, store, normalizeSlashCommandName, surface, closeUsagePanel, ...deps }) {
-  const ctx = { state, store, deps, openSlashPanel: createSlashPanelOpener({ surface, store }) };
+  const ctx = { state, store, deps, surface, openSlashPanel: createSlashPanelOpener({ surface, store }) };
   const runSlashCommand = (cmd, arg = '') => {
     const rawName = String(cmd || '').toLowerCase();
     cmd = normalizeSlashCommandName(cmd);

package/src/tui/app/use-btw-panel.mjs

@@ -0,0 +1,29 @@
+/*
+ * app/use-btw-panel.mjs — the /btw side-question panel: its state, the
+ * controller that fills it, and the controller's session/unmount lifecycle.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { createBtwController } from './btw-controller.mjs';
+
+export function useBtwPanel({ store, sessionId }) {
+  const [btwPanel, setBtwPanel] = useState(null);
+  const btwRef = useRef(null);
+  const sessionIdRef = useRef('');
+  sessionIdRef.current = sessionId || '';
+  if (!btwRef.current) {
+    btwRef.current = createBtwController({
+      getStore: () => store,
+      setPanel: setBtwPanel,
+      getSessionId: () => sessionIdRef.current,
+    });
+  }
+  const btw = btwRef.current;
+  // A side answer belongs to the conversation it was asked in: drop it on a
+  // session change (new/resume/clear/switch) and cancel it on unmount.
+  // biome-ignore lint/correctness/useExhaustiveDependencies(sessionId): session-change trigger; the controller reads the id through its getter
+  useEffect(() => {
+    btw.sync();
+  }, [btw, sessionId]);
+  useEffect(() => () => btw.dispose(), [btw]);
+  return { btwPanel, btw };
+}

package/src/tui/app/use-context-panel-refresh.mjs

@@ -0,0 +1,31 @@
+/*
+ * app/use-context-panel-refresh.mjs — keeps an open /context breakdown panel
+ * current: it is rebuilt whenever one of the session fields it summarizes
+ * changes.
+ */
+import { useEffect } from 'react';
+
+export function useContextPanelRefresh({ contextPanelKind, state, openContextPicker }) {
+  // The deps are the refresh triggers (the fields the breakdown summarizes),
+  // not the reads; openContextPicker is rebuilt by its factory every render
+  // and must not re-trigger the rebuild.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: trigger-keyed refresh over the summarized session fields
+  useEffect(() => {
+    if (contextPanelKind === 'context') openContextPicker();
+  }, [
+    contextPanelKind,
+    state.stats,
+    state.contextWindow,
+    state.rawContextWindow,
+    state.sessionId,
+    state.toolMode,
+    state.agentWorkers,
+    state.agentJobs,
+    state.provider,
+    state.model,
+    state.effort,
+    state.fast,
+    state.cwd,
+    state.clientHostPid,
+  ]);
+}

package/src/tui/app/use-model-catalog-cache.mjs

@@ -20,16 +20,19 @@ export function useModelCatalogCache({ store, onboardingRef }) {
   // provider-scope cache clear (e.g. after auth) so a stale in-flight
   // listProviderModels() cannot repopulate the ref after invalidation.
   const onboardingPrefetchSeqRef = useRef(0);
-  const clearModelCaches = useCallback((scope = 'all') => {
-    if (scope === 'all' || scope === 'provider') {
-      providerModelsCacheRef.current = { models: null, at: 0 };
-      onboardingRef.current.providerModels = [];
-      onboardingPrefetchSeqRef.current += 1;
-    }
-    if (scope === 'all' || scope === 'webSearch') {
-      webSearchModelsCacheRef.current = { models: null, at: 0 };
-    }
-  }, []);
+  const clearModelCaches = useCallback(
+    (scope = 'all') => {
+      if (scope === 'all' || scope === 'provider') {
+        providerModelsCacheRef.current = { models: null, at: 0 };
+        onboardingRef.current.providerModels = [];
+        onboardingPrefetchSeqRef.current += 1;
+      }
+      if (scope === 'all' || scope === 'webSearch') {
+        webSearchModelsCacheRef.current = { models: null, at: 0 };
+      }
+    },
+    [onboardingRef]
+  );
   // Boot-time catalog prefetch: warm the /model & /agents provider catalog and
   // the /websearch catalog once at startup so those pickers open instantly from
   // cache (openModelPicker still TTL-refreshes stale rows in the background).

package/src/tui/app/use-mouse-input.mjs

@@ -316,6 +316,17 @@ export function useMouseInput({
     isRawModeSupported,
     store,
     stdout,
+    dragRef,
+    lastClickRef,
+    slashPaletteRef,
+    scrollFocusRef,
+    promptMouseSelectionRef,
+    frameRowsRef,
+    promptBoxRectRef,
+    transcriptViewportRef,
+    scrollTargetRef,
+    setSlashIndex,
+    setMeasuredRowsVersion,
     passthroughCtrlWheelZoom,
     frameColumns,
     statuslineBandRows,

package/src/tui/app/use-onboarding-start.mjs

@@ -1,7 +1,7 @@
 /*
  * app/use-onboarding-start.mjs — first-run onboarding gate + wizard launch.
  */
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 
 // First-run gate. The daemon-backed engine store answers any method it does
 // not implement locally with an async remote call, so a synchronous
@@ -25,10 +25,15 @@ export function useOnboardingStart({
   store,
   forceOnboarding,
   onboardingCompleted,
-  onboardingStartedRef,
   setOnboardingActive,
   openOnboardingAuthStep,
 }) {
+  // Latches the launch so the wizard opens at most once per mount.
+  const onboardingStartedRef = useRef(false);
+  // openOnboardingAuthStep is rebuilt by the picker factory every render;
+  // depending on it would re-run this launch (and cancel its deferred open)
+  // on every commit. The launch keys on the gate inputs only.
+  // biome-ignore lint/correctness/useExhaustiveDependencies(openOnboardingAuthStep): per-render factory callback; launch keys on gate inputs
   useEffect(() => {
     if (onboardingStartedRef.current) return undefined;
     if (resolveOnboardingCompleted(store, onboardingCompleted) && !forceOnboarding) return undefined;
@@ -41,5 +46,5 @@ export function useOnboardingStart({
     return () => {
       canceled = true;
     };
-  }, [store, forceOnboarding, onboardingCompleted]);
+  }, [store, forceOnboarding, onboardingCompleted, setOnboardingActive]);
 }

package/src/tui/app/use-panel-transition.mjs

@@ -30,7 +30,16 @@ export function usePanelTransition({
     if (!hadTransitionClearance) return undefined;
     const timer = setTimeout(() => setPanelTransitionEpoch((epoch) => epoch + 1), 0);
     return () => clearTimeout(timer);
-  }, [panelLayoutSignature, bottomClusterRows, panelTransitionClearRows, panelTransitionGuardRows]);
+  }, [
+    panelTransitionRef,
+    panelCloseInkMaskRowsRef,
+    panelLayoutSignature,
+    bottomClusterRows,
+    panelTransitionClearRows,
+    panelTransitionGuardRows,
+    setPanelInkMaskEpoch,
+    setPanelTransitionEpoch,
+  ]);
   // Record the transcript tail id AFTER every commit so the next render's
   // spinner-meta-collapse gate (doneTailAppendedThisCommit) can tell a freshly
   // appended done row from a stale one that was already at the tail.

package/src/tui/app/use-pasted-buffers.mjs

@@ -48,31 +48,39 @@ function usePastedBufferSlice({ toEntry, formatRef }) {
     setBuffers(next);
   }, []);
 
-  const register = useCallback((input) => {
-    const id = nextIdRef.current;
-    const entry = toEntry(input, id);
-    if (!entry) return '';
-    nextIdRef.current = id + 1;
-    buffersRef.current = { ...buffersRef.current, [id]: entry };
-    setBuffers(buffersRef.current);
-    return formatRef(entry);
-  }, []);
+  const register = useCallback(
+    (input) => {
+      const id = nextIdRef.current;
+      const entry = toEntry(input, id);
+      if (!entry) return '';
+      nextIdRef.current = id + 1;
+      buffersRef.current = { ...buffersRef.current, [id]: entry };
+      setBuffers(buffersRef.current);
+      return formatRef(entry);
+    },
+    [toEntry, formatRef]
+  );
 
   return { buffersRef, nextIdRef, install, clearSnapshot, register };
 }
 
+// Module-level slice specs keep toEntry/formatRef identities stable, so
+// `register` is created once per mount.
+const IMAGE_SLICE = {
+  toEntry: (image, id) => (image?.type === 'image' && image.content ? { ...image, id } : null),
+  formatRef: (entry) => formatImageRef(entry.id),
+};
+const TEXT_SLICE = {
+  toEntry: (text, id) => {
+    const value = String(text ?? '');
+    return value ? { id, text: value } : null;
+  },
+  formatRef: (entry) => formatPastedTextRef(entry.id, entry.text),
+};
+
 export function usePastedBuffers() {
-  const images = usePastedBufferSlice({
-    toEntry: (image, id) => (image?.type === 'image' && image.content ? { ...image, id } : null),
-    formatRef: (entry) => formatImageRef(entry.id),
-  });
-  const texts = usePastedBufferSlice({
-    toEntry: (text, id) => {
-      const value = String(text ?? '');
-      return value ? { id, text: value } : null;
-    },
-    formatRef: (entry) => formatPastedTextRef(entry.id, entry.text),
-  });
+  const images = usePastedBufferSlice(IMAGE_SLICE);
+  const texts = usePastedBufferSlice(TEXT_SLICE);
 
   return {
     pastedImagesRef: images.buffersRef,