mixdog 0.9.147 → 0.9.149

package/src/tui/app/maintenance-pickers.mjs

@@ -2,25 +2,33 @@
  * maintenance-pickers.mjs — Update / Auto-clear / Profile picker cluster.
  *
  * Extracted from App.jsx behavior-preservingly as a dependency-injection
- * factory. These openers drive setPicker + setSettingsPrompt and read live
- * store state, so they can't be pure. Every function body is the original App
- * logic verbatim, with closure identifiers threaded through the factory
+ * factory. These openers drive the panel surface + setSettingsPrompt and read
+ * live store state, so they can't be pure. Every function body is the original
+ * App logic verbatim, with closure identifiers threaded through the factory
  * argument.
  */
 export function createMaintenancePickers({
   store,
   theme,
   formatDuration,
-  setPicker,
+  surface,
   setProviderPrompt,
-  setChannelPrompt,
-  setHookPrompt,
   setSettingsPrompt,
-  setContextPanel,
   closeUsagePanel,
 }) {
   const openUpdatePicker = (options = {}) => {
     const returnTo = typeof options.returnTo === 'function' ? options.returnTo : null;
+    // Surface claim for this panel, taken at the user's open action — BEFORE
+    // the first daemon read. Every paint through it re-validates and re-arms,
+    // so a re-check or install settling after Esc cannot paint over whatever
+    // the user is looking at now.
+    const own = surface.claim();
+    const paintPanel = (panel) => {
+      if (!own.owns()) return false;
+      setProviderPrompt(null);
+      setSettingsPrompt(null);
+      return own.paint(panel);
+    };
     // Async: both reads are remote calls on a daemon-backed store, so the sync
     // versions rendered every row from an unresolved promise.
     const readSettings = async () => {
@@ -64,11 +72,7 @@ export function createMaintenancePickers({
           _action: 'auto-update',
         },
       ];
-      setProviderPrompt(null);
-      setChannelPrompt(null);
-      setHookPrompt(null);
-      setSettingsPrompt(null);
-      setPicker({
+      return paintPanel({
         title: 'Update',
         description: 'Check version and update mixdog.',
         help: '↑/↓ Select · Enter Open/Toggle · Esc Close',
@@ -101,31 +105,40 @@ export function createMaintenancePickers({
           }
         },
         onCancel: () => {
-          setPicker(null);
+          own.close();
           if (returnTo) returnTo();
         },
       });
     };
+    // Every render() is an async daemon read; a detached call would surface a
+    // failed read as an unhandled rejection (fatal for the TUI process).
+    const rerender = (opts = {}) => {
+      void Promise.resolve(render(opts))
+        .catch((e) => store.pushNotice(`update panel failed: ${e?.message || e}`, 'error'));
+    };
+    // Deferred repaint bound to the claim AT ACTION TIME: a check/install that
+    // settles after Esc must not re-open the Update panel.
+    const deferredRerender = (opts = {}) => own.defer(() => rerender(opts));
     const toggleAutoUpdate = (enabled) => {
-      try {
-        void Promise.resolve(store.setAutoUpdate?.(enabled)).finally(() => render());
-        store.pushNotice(`Auto-update ${enabled ? 'on' : 'off'}`, 'info');
-      } catch (e) {
-        store.pushNotice(`auto-update failed: ${e?.message || e}`, 'error');
-      }
-      render();
+      // Persisted by the daemon: only claim the new value once it is written.
+      void Promise.resolve(store.setAutoUpdate?.(enabled))
+        .then(() => store.pushNotice(`Auto-update ${enabled ? 'on' : 'off'}`, 'info'))
+        .catch((e) => store.pushNotice(`auto-update failed: ${e?.message || e}`, 'error'))
+        .finally(deferredRerender());
     };
     const recheck = () => {
-      render({ checking: true });
+      rerender({ checking: true });
+      const settled = deferredRerender();
       void Promise.resolve(store.checkForUpdate?.({ force: true }))
-        .then(() => render())
+        .then(() => settled())
         .catch((e) => {
           store.pushNotice(`update check failed: ${e?.message || e}`, 'error');
-          render();
+          settled();
         });
     };
     const runUpdate = () => {
       store.pushNotice('Updating…', 'info');
+      const settled = deferredRerender();
       void Promise.resolve(store.runUpdateNow?.())
         .then((result) => {
           if (result?.ok) {
@@ -133,21 +146,42 @@ export function createMaintenancePickers({
           } else {
             store.pushNotice(`Update failed: ${result?.error || 'unknown error'}`, 'error');
           }
-          render();
+          settled();
         })
         .catch((e) => {
           store.pushNotice(`Update failed: ${e?.message || e}`, 'error');
-          render();
+          settled();
         });
     };
-    render({ checking: true });
-    void Promise.resolve(store.checkForUpdate?.({}))
-      .then(() => render())
-      .catch(() => render());
+    // First paint, THEN the initial check. The repaint epoch is captured after
+    // this panel has taken the surface: capturing it before the first paint
+    // binds it to the previous owner's epoch, which the open transition (a
+    // panel identity change) supersedes — leaving "Latest version" stuck on
+    // "checking…". Esc after the paint still closes the panel for good.
+    void Promise.resolve(render({ checking: true }))
+      .catch((e) => {
+        store.pushNotice(`update panel failed: ${e?.message || e}`, 'error');
+        return false;
+      })
+      .then((painted) => {
+        // Open abandoned (Esc while the first read was pending): the panel
+        // never took the surface, so the check result must not paint it either.
+        if (!painted) return;
+        const initialChecked = deferredRerender();
+        void Promise.resolve(store.checkForUpdate?.({}))
+          .then(() => initialChecked())
+          .catch(() => initialChecked());
+      });
   };
 
   const openAutoClearPicker = (options = {}) => {
     const returnTo = typeof options.returnTo === 'function' ? options.returnTo : null;
+    // Surface claim, same rule as openUpdatePicker: every paint (render() and
+    // renderAdvanced()) re-validates and re-arms, so a readCurrent() settling
+    // after Esc — on open or on any later toggle — can never paint over the
+    // user's surface.
+    const own = surface.claim();
+    const paintPanel = (panel) => own.paint(panel);
     // Lead BP4 messages cache TTL follows autoClear (cache-strategy.mjs
     // resolveLeadMessagesTtl): off or idle>=1h -> 1h, shorter idle -> 5m.
     const HOUR_MS = 60 * 60 * 1000;
@@ -162,6 +196,12 @@ export function createMaintenancePickers({
       try { return (await store.getAutoClear?.()) || null; } catch { return null; }
     };
     const applyAutoClear = (patch = {}) => {
+      // Bound to the claim on this keypress: a write acking after Esc must not
+      // re-open the Auto-clear panel.
+      const settled = own.defer(() => {
+        void Promise.resolve(render())
+          .catch((e) => store.pushNotice(`auto-clear panel failed: ${e?.message || e}`, 'error'));
+      });
       void Promise.resolve(store.setAutoClear?.(patch))
         .then((next) => {
           if (!next) {
@@ -171,11 +211,11 @@ export function createMaintenancePickers({
           store.pushNotice(next.enabled ? `autoclear on · idle ${formatDuration(next.idleMs)}` : 'autoclear off', 'info');
         })
         .catch((e) => store.pushNotice(`autoclear failed: ${e?.message || e}`, 'error'))
-        .finally(() => { void render(); });
+        .finally(settled);
     };
     const openProviderDurationEditor = (entry) => {
       if (!entry?.provider) return;
-      setPicker(null);
+      own.close();
       setSettingsPrompt({
         kind: 'autoclear-provider',
         label: `Auto-clear · ${entry.provider}`,
@@ -200,7 +240,7 @@ export function createMaintenancePickers({
         _action: 'provider-default',
         _entry: entry,
       }));
-      setPicker({
+      paintPanel({
         title: 'Auto-clear · Advanced',
         description: 'Provider default idle windows. Enter edits the duration text.',
         help: '↑/↓ Select · Enter Edit · Esc Back',
@@ -238,7 +278,7 @@ export function createMaintenancePickers({
           _action: 'advanced',
         },
       ];
-      setPicker({
+      paintPanel({
         title: 'Auto-clear',
         description: `Clear idle context after ${enabled ? formatDuration(idleMs) : 'never'} · lead cache TTL ${cacheTtlLabel}.`,
         help: '↑/↓ Select · ←/→ Toggle On/Off · Enter Open/Toggle · Esc Close',
@@ -259,16 +299,14 @@ export function createMaintenancePickers({
           }
         },
         onCancel: () => {
-          setPicker(null);
+          own.close();
           if (returnTo) returnTo();
         },
       });
     };
     setProviderPrompt(null);
-    setChannelPrompt(null);
-    setHookPrompt(null);
     setSettingsPrompt(null);
-    setContextPanel(null);
+    own.context(null);
     closeUsagePanel();
     if (options.advanced === true) renderAdvanced();
     else render();
@@ -276,6 +314,9 @@ export function createMaintenancePickers({
 
   const openProfilePicker = async (options = {}) => {
     const returnTo = typeof options.returnTo === 'function' ? options.returnTo : null;
+    // Surface claim (panel-surface.mjs): getProfile() is a daemon read, so Esc
+    // can land before the first paint.
+    const own = surface.claim();
     let profile = null;
     try {
       profile = (await store.getProfile?.()) || null;
@@ -298,16 +339,22 @@ export function createMaintenancePickers({
     const currentExperienceLevelId = profile?.experienceLevel || '';
     const currentExperienceLevel = experienceLevels.find((level) => level.id === currentExperienceLevelId) || null;
     const titleValue = String(profile?.title || '').trim();
+    // setProfile is a daemon write: rebuild the panel only after it settles so
+    // the row cannot show a value the daemon rejected (and so a rejected write
+    // cannot escape as an unhandled rejection).
+    // Bound to the claim when the cycle keypress builds its chain: a setProfile
+    // that acks after Esc must not re-open the Profile panel.
+    const reopenProfile = () => own.defer(() => {
+      void Promise.resolve(openProfilePicker({ returnTo }))
+        .catch((e) => store.pushNotice(`profile panel failed: ${e?.message || e}`, 'error'));
+    });
     const cycleLanguage = (direction = 1) => {
       const idx = Math.max(0, languages.findIndex((lang) => lang.id === currentLangId));
       const next = languages[(idx + direction + languages.length) % languages.length];
-      try {
-        store.setProfile?.({ language: next.id });
-        store.pushNotice(`Language set to ${next.label}`, 'info');
-      } catch (e) {
-        store.pushNotice(`profile update failed: ${e?.message || e}`, 'error');
-      }
-      openProfilePicker({ returnTo });
+      void Promise.resolve(store.setProfile?.({ language: next.id }))
+        .then(() => store.pushNotice(`Language set to ${next.label}`, 'info'))
+        .catch((e) => store.pushNotice(`profile update failed: ${e?.message || e}`, 'error'))
+        .finally(reopenProfile());
     };
     const cycleExperienceLevel = (direction = 1) => {
       const idx = experienceLevels.findIndex((level) => level.id === currentExperienceLevelId);
@@ -315,21 +362,17 @@ export function createMaintenancePickers({
         ? (direction < 0 ? experienceLevels.length - 1 : 0)
         : (idx + direction + experienceLevels.length) % experienceLevels.length;
       const next = experienceLevels[nextIdx];
-      try {
-        store.setProfile?.({ experienceLevel: next.id });
-        store.pushNotice(`Experience level set to ${next.label}`, 'info');
-      } catch (e) {
-        store.pushNotice(`profile update failed: ${e?.message || e}`, 'error');
-      }
-      openProfilePicker({ returnTo });
+      void Promise.resolve(store.setProfile?.({ experienceLevel: next.id }))
+        .then(() => store.pushNotice(`Experience level set to ${next.label}`, 'info'))
+        .catch((e) => store.pushNotice(`profile update failed: ${e?.message || e}`, 'error'))
+        .finally(reopenProfile());
     };
+    if (!own.owns()) return;
     setProviderPrompt(null);
-    setChannelPrompt(null);
-    setHookPrompt(null);
     setSettingsPrompt(null);
-    setContextPanel(null);
+    own.context(null);
     closeUsagePanel();
-    setPicker({
+    own.paint({
       title: 'Profile',
       description: 'How the assistant addresses you, adapts terminology, and chooses its response language.',
       help: '↑/↓ Select · ←/→ Change · Enter Edit · Esc Close',
@@ -369,7 +412,7 @@ export function createMaintenancePickers({
       },
       onSelect: (_value, item) => {
         if (item?._action === 'title') {
-          setPicker(null);
+          own.close();
           setSettingsPrompt({
             kind: 'profile-title',
             label: 'Profile · Title',
@@ -382,7 +425,7 @@ export function createMaintenancePickers({
         }
       },
       onCancel: () => {
-        setPicker(null);
+        own.close();
         if (returnTo) returnTo();
       },
     });

package/src/tui/app/message-selector.mjs

@@ -35,7 +35,7 @@ export function messageSelectorLabel(text, width = 56) {
 export function useMessageSelector({
   store,
   state,
-  setPicker,
+  surface,
   setPromptDraftOverride,
   syncPromptLayoutRows,
   showPromptHint,
@@ -69,14 +69,15 @@ export function useMessageSelector({
       showPromptHint('No message to jump back to.', 'info');
       return false;
     }
-    setPicker({
+    const own = surface.claim();
+    own.paint({
       _kind: 'message-selector',
       title: 'Jump back to a message',
       description: 'Rewind the conversation to a previous prompt and edit it.',
       initialIndex: rows.length - 1,
       items: rows.map((row) => ({ value: row.id, label: messageSelectorLabel(row.text) })),
       onSelect: (value) => {
-        setPicker(null);
+        own.close();
         let restored;
         try {
           restored = store.rewindToItem?.(value);
@@ -94,10 +95,10 @@ export function useMessageSelector({
         }
         applyRewind(restored);
       },
-      onCancel: () => setPicker(null),
+      onCancel: () => own.close(),
     });
     return true;
-  }, [store, state.items, setPicker, applyRewind, showPromptHint]);
+  }, [store, state.items, surface, applyRewind, showPromptHint]);
 
   return { hasUserMessages, openMessageSelector };
 }

package/src/tui/app/model-picker.mjs

@@ -31,10 +31,8 @@ const MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
 export function createModelPicker({
   store,
   getState,
-  setPicker,
+  surface,
   setProviderPrompt,
-  setChannelPrompt,
-  setHookPrompt,
   setSettingsPrompt,
   providerModelsCacheRef,
   webSearchModelsCacheRef,
@@ -46,9 +44,14 @@ export function createModelPicker({
   let providerModelsTtlRefreshPromise = null;
   const openModelPicker = async (options = {}) => {
     const state = getState();
+    // Surface claim for this picker (panel-surface.mjs): every paint — the
+    // loading frame, the provider list, the per-provider model list — proves
+    // ownership through it, and each paint re-arms it because a paint can
+    // itself be the handover. modelPickerRequestRef only orders concurrent
+    // OPENS; it cannot see an Esc that closed this one, so a model load
+    // settling afterwards used to repaint the dismissed picker.
+    const own = surface.claim();
     setProviderPrompt(null);
-    setChannelPrompt(null);
-    setHookPrompt(null);
     setSettingsPrompt(null);
     modelPickerRequestRef.current += 1;
     let modelPickerClosed = false;
@@ -59,8 +62,9 @@ export function createModelPicker({
     const cancelModelPicker = () => {
       modelPickerClosed = true;
       if (returnTo) returnTo();
-      else setPicker(null);
+      else own.close();
     };
+    const paintModelPicker = (panel) => own.paint(panel);
     const cacheRef = options.cacheRef === 'webSearch' ? webSearchModelsCacheRef : providerModelsCacheRef;
     const loadModels = typeof options.loadModels === 'function' ? options.loadModels : store.listProviderModels;
     let providerModels = Array.isArray(cacheRef.current.models)
@@ -69,7 +73,7 @@ export function createModelPicker({
     let refreshModelsPromise = null;
     let renderedQuickModels = false;
     if (!providerModels.length || options.refreshModels === true) {
-      setPicker({
+      paintModelPicker({
         title: options.title || 'Model',
         description: options.loadingDescription || 'Loading models...',
         help: returnTo ? `↑/↓ Select · Enter Open · Esc ${returnLabel}` : '↑/↓ Select · Enter Open · Esc Back',
@@ -108,6 +112,9 @@ export function createModelPicker({
 
     if (!providerModels || providerModels.length === 0) {
       store.pushNotice(options.emptyNotice || 'no provider models available; open /providers to sign in', 'warn');
+      // Delegation is a paint by proxy: the empty-catalog fallback opens
+      // Providers, so it must prove ownership exactly like paintModelPicker.
+      if (!own.owns()) return;
       void openProviderSetupPicker({
         title: 'Providers',
         continueLabel: 'Back to model setup',
@@ -375,18 +382,28 @@ export function createModelPicker({
             if (typeof options.onImmediateSelect === 'function') {
               options.onImmediateSelect(routeInput, selected, effort);
             } else {
-              setPicker(null);
+              own.paint(null);
             }
+            // Post-ack delegation (return to the caller's panel), bound to the
+            // claim AFTER this keypress's own navigation: an Esc between the
+            // save and its ack must cancel the hop, not paint over the surface
+            // the user moved to.
+            const afterSelect = own.defer(() => {
+              if (typeof options.onAfterSelect === 'function') options.onAfterSelect();
+            });
             void savePromise
               .then((result) => {
                 if (result) clearModelCaches('all');
-                if (typeof options.onAfterSelect === 'function') options.onAfterSelect();
+                afterSelect();
                 return result;
               })
               .catch((e) => store.pushNotice(`Couldn’t save model: ${e?.message || e}`, 'error'));
             return;
           }
-          setPicker(null);
+          own.paint(null);
+          const afterSelect = own.defer(() => {
+            if (typeof options.onAfterSelect === 'function') options.onAfterSelect();
+          });
           void store.setRoute(routeInput)
             .then((ok) => {
               if (ok) clearModelCaches('provider');
@@ -396,7 +413,7 @@ export function createModelPicker({
                   : 'Model switch is already running',
                 ok ? 'info' : 'warn',
               );
-              if (ok && typeof options.onAfterSelect === 'function') options.onAfterSelect();
+              if (ok) afterSelect();
             })
             .catch((e) => store.pushNotice(`Couldn’t switch model: ${e?.message || e}`, 'error'));
         };
@@ -408,7 +425,7 @@ export function createModelPicker({
               (item) => item._provider === activeRoute?.provider && item._modelId === activeRoute?.model,
             ),
           );
-          setPicker({
+          paintModelPicker({
             title: providerDisplayName(provider),
             description: options.modelDescription || 'Select a model. Adjust Effort with ←/→.',
             footer: (item) => modelFooter(item?._model),
@@ -460,7 +477,7 @@ export function createModelPicker({
         0,
         providerItems.findIndex((item) => item._provider === providerHighlight),
       );
-      setPicker({
+      paintModelPicker({
         title: options.title || 'Model',
         description: options.providerDescription || 'Choose a provider.',
         help: returnTo ? `↑/↓ Select · Enter Open · Esc ${returnLabel}` : '↑/↓ Select · Enter Open · Esc Back',

package/src/tui/app/onboarding-steps.mjs

@@ -19,10 +19,8 @@ import {
 
 export function createOnboardingSteps({
   store,
-  setPicker,
+  surface,
   setProviderPrompt,
-  setChannelPrompt,
-  setHookPrompt,
   setSettingsPrompt,
   setOnboardingActive,
   onboardingRef,
@@ -85,6 +83,11 @@ export function createOnboardingSteps({
 
   const openOnboardingAuthStep = async () => {
     prefetchOnboardingStep2();
+    // Surface claim (panel-surface.mjs): the provider-setup read below runs
+    // before anything paints, and the wizard is reachable while a normal
+    // surface is on screen (/onboarding, Step-1 re-entry), so Esc during the
+    // wait must leave that surface alone instead of dropping Step 1 on it.
+    const own = surface.claim();
     // Load the provider setup BEFORE opening the picker so Step 1 renders the
     // real list in one frame instead of flashing the "Checking Providers"
     // placeholder (that swap is what looked like a jump on entry). On failure,
@@ -93,6 +96,7 @@ export function createOnboardingSteps({
     try {
       preloadedSetup = await store.getProviderSetup?.();
     } catch { /* openProviderSetupPicker will show its loading frame + error. */ }
+    if (!own.owns()) return;
     void openProviderSetupPicker({
       title: 'First Run · Step 1/4 · Provider Auth',
       returnTo: () => openOnboardingAuthStep(),
@@ -133,7 +137,7 @@ export function createOnboardingSteps({
     const webSearchRoute = onboardingRef.current.webSearchRoute || null;
     const overrides = onboardingRef.current.agentRoutes || {};
     const hasOverrides = Object.keys(overrides).length > 0;
-    setPicker(null);
+    surface.claim().close();
     setOnboardingActive(false);
     const done = () => store.pushNotice('First-run setup complete.', 'info');
     const failed = (e) => store.pushNotice(`Couldn’t save setup: ${e?.message || e}`, 'error');
@@ -172,6 +176,7 @@ export function createOnboardingSteps({
   // the plain model list is shown. Selecting Main Model updates defaultRoute;
   // agents that have no explicit override keep inheriting it.
   const openOnboardingRoleModelPicker = async (target) => {
+    const own = surface.claim();
     const isLead = target === 'lead';
     const isWebSearch = target === 'webSearch';
     // Web Search uses the web-search-capable model list; lead/agent use provider models.
@@ -186,14 +191,15 @@ export function createOnboardingSteps({
       models = normalizeModelOptions(webSearchModels || []);
       if (models.length === 0) {
         store.pushNotice('no native web-search models available; connect OpenAI, Grok, Gemini, or Anthropic', 'warn');
-        void openOnboardingWorkflowStep();
+        // Fallback delegation is a paint by proxy: prove ownership first.
+        if (own.owns()) void openOnboardingWorkflowStep();
         return;
       }
     } else {
       models = normalizeModelOptions(onboardingRef.current.providerModels || []);
       if (models.length === 0) {
         store.pushNotice('no provider models available; open /providers to sign in', 'warn');
-        openOnboardingAuthStep();
+        if (own.owns()) openOnboardingAuthStep();
         return;
       }
     }
@@ -245,7 +251,8 @@ export function createOnboardingSteps({
       : isWebSearch
         ? 'Web Search'
         : (onboardingRef.current.agents || []).find((a) => a.id === target)?.label || target;
-    setPicker({
+    if (!own.owns()) return;
+    own.paint({
       title: `First Run · ${label}`,
       description: isLead
         ? 'Pick the main model. Agents inherit this unless individually changed.'
@@ -294,6 +301,7 @@ export function createOnboardingSteps({
   };
 
   const openOnboardingWorkflowStep = async () => {
+    const own = surface.claim();
     if (!Array.isArray(onboardingRef.current.providerModels) || onboardingRef.current.providerModels.length === 0) {
       try {
         onboardingRef.current.providerModels = await store.listProviderModels();
@@ -308,7 +316,9 @@ export function createOnboardingSteps({
       onboardingRef.current.defaultRoute = null;
       onboardingRef.current.agentRoutes = {};
       store.pushNotice('no provider models available; open /providers to sign in', 'warn');
-      openOnboardingAuthStep();
+      // Step 2's empty-model fallback hands the surface to Step 1 after an
+      // await: same ownership rule as its own paint below.
+      if (own.owns()) openOnboardingAuthStep();
       return;
     }
     // Main Model stays unset until the user picks one; no auto-recommendation.
@@ -326,11 +336,10 @@ export function createOnboardingSteps({
     const webSearchRoute = onboardingRef.current.webSearchRoute || null;
     const overrides = onboardingRef.current.agentRoutes || {};
     const agents = onboardingRef.current.agents || [];
+    if (!own.owns()) return;
     setProviderPrompt(null);
-    setChannelPrompt(null);
-    setHookPrompt(null);
     setSettingsPrompt(null);
-    setPicker({
+    own.paint({
       title: 'First Run · Step 2/4 · Models',
       description: 'Set the Main Model; each agent inherits it unless changed.',
       indexMode: 'always',
@@ -384,7 +393,7 @@ export function createOnboardingSteps({
         }
       },
       onCancel: () => {
-        setPicker(null);
+        own.close();
         onboardingWarnReopen();
       },
     });

package/src/tui/app/panel-epoch.mjs

@@ -0,0 +1,56 @@
+// Panel/prompt supersession epoch.
+//
+// Module-global on purpose: the TUI runs ONE App tree and every picker/prompt
+// factory is re-created on each render, so this ownership marker cannot live in
+// a factory closure.
+//
+// Anything that hands surface ownership back to the user — closing a picker
+// (Esc/cancel), cancelling a text-entry prompt, or issuing a NEWER submit of
+// the same prompt — supersedes every deferred paint issued before it. Async
+// work captures currentPanelEpoch() when the USER ACTION starts and re-checks
+// isPanelEpochCurrent(token) immediately before it opens, refreshes, or closes
+// a surface. That single check kills both failure modes:
+//   - a daemon write settling after Esc re-opening the dismissed panel, and
+//   - an older ACK closing (or claiming success for) a panel that meanwhile
+//     holds newer user input.
+let panelEpoch = 0;
+
+export function currentPanelEpoch() {
+  return panelEpoch;
+}
+
+// Marks every in-flight deferred paint as superseded and returns the new token
+// for the action performing the supersession.
+export function supersedePanelEpoch() {
+  panelEpoch += 1;
+  return panelEpoch;
+}
+
+export function isPanelEpochCurrent(token) {
+  return token === panelEpoch;
+}
+
+// Identity of the SURFACE a panel object stands for. A rebuild of the same
+// surface (light Settings refresh, toggle-driven MCP re-render) keeps this
+// value stable; a different panel reports a different identity.
+export function panelIdentity(panel) {
+  if (!panel || typeof panel !== 'object') return null;
+  return panel._kind || panel.title || null;
+}
+
+// True when `next` takes the surface away from a DIFFERENT panel that was open:
+// a close (open → null) or a replacement by another panel. Both hand the
+// surface to something the user is looking at now, so deferred paints issued
+// before it are stale. Not a handover:
+//   - null → anything: nothing owned the surface, and the in-flight write of a
+//     text-entry prompt currently on screen must stay valid, and
+//   - a rebuild of the same panel: its own deferred refresh must still land.
+export function shouldSupersedePanelEpoch(previous, next) {
+  if (!previous || typeof previous !== 'object') return false;
+  if (!next || typeof next !== 'object') return true;
+  if (previous === next) return false;
+  return panelIdentity(previous) !== panelIdentity(next);
+}
+
+// Ownership is CLAIMED, never asserted by hand: panel-surface.mjs owns the
+// sinks and hands out claims that carry these tokens (see that module's header).