@pi-unipi/unipi 2.13.0 → 2.14.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.14.1] — 2026-08-28
+
+### Added
+
+- `utility`: **skill startup discovery toggle** (`/unipi:skills-settings`, default on) — controls whether Unipi's built-in skills are cataloged in the agent's system prompt at startup. When off (`unipi.skills.discovery: false` in pi settings.json), Unipi's bundled skills are removed from the `<available_skills>` section every turn while user-owned skills (global, project, settings-mounted, third-party packages) stay cataloged; `/skill:name` invocation keeps working since pi expands those commands by reading SKILL.md directly from disk. Filtering is anchor-based (agentskills.io tags) and applied consistently per turn, preserving provider prefix cache.
+- `autocomplete`: registered `/unipi:skills-settings` in COMMAND_REGISTRY + COMMAND_DESCRIPTIONS so the command autosuggests.
+
+### Fixed
+
+- `info-screen`: **boot splash no longer eats keystrokes or strands the session** — the auto-close boot dashboard was a capturing overlay during its 2s window: typing during boot was swallowed (worse, its vim-style keys interpreted command text as tab switches), the first-keypress-cancels-auto-close rule left it on screen forever as an unclosable input-eating zombie, and prompts appeared to never send (the agent actually responded behind the overlay). The splash is now non-capturing (typing always reaches the editor) and dismisses itself via a stack-safe `handle.hide()` that only fires while it is the topmost visible overlay entry — if the user opens any dialog during the splash window (e.g. `/unipi:skills-settings`), dismissal defers until it closes, so the overlay can no longer be orphaned with a pending interaction (previously the covered overlay vanished while its `ctx.ui.select` promise hung forever). Interactive (`bootMode: "on"`) dashboards are unchanged; splash footer now reads "auto-dismissing…" instead of keyboard hints that could never reach it.
+
+## [2.14.0] — 2026-08-29
+
+### Changed
+
+- `image`: **`image_recognize` is now hidden while the session model has vision** — a model that accepts image input reads images natively through pi's own read tool, so the separate recognition round-trip only duplicated the ability and burned system-prompt context. The extension drops the tool from the active set on `session_start` and `model_select` when the session model declares image input (`input` includes `"image"`), and restores it automatically when a text-only model takes over mid-session. Models that do not declare input modalities are treated as non-vision and keep the tool, matching the package's existing convention. The info screen shows "Hidden (model has vision)" for the Recognize stat while suppressed.
+
 ## [2.13.0] — 2026-08-28
 
 ### Added

package/README.md

@@ -110,7 +110,7 @@ Coexists triggers enhance behavior when packages are installed together. Workflo
 | `spawn_helper` / `get_helper_result` | subagents | Parallel agents |
 | `memory_store` / `memory_search` / `memory_delete` | memory | Memory CRUD |
 | `web_search` / `multi_web_content_read` / `web_llm_summarize` | web-api | Web research |
-| `image_generate` / `image_recognize` | image | Image generation and vision |
+| `image_generate` / `image_recognize` | image | Image generation and vision (recognize auto-hides while the session model has vision) |
 | `notify_user` | notify | Push notifications |
 | `ask_user` | ask-user | User input |
 | `compact` / `session_recall` / `sandbox` | compactor | Context management |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.13.0",
+  "version": "2.14.1",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -82,28 +82,28 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "2.12.0",
-    "@pi-unipi/background-tasks": "2.13.0",
-    "@pi-unipi/btw": "2.12.0",
-    "@pi-unipi/command-enchantment": "2.12.0",
-    "@pi-unipi/compactor": "2.12.0",
-    "@pi-unipi/core": "2.12.0",
-    "@pi-unipi/footer": "2.13.0",
-    "@pi-unipi/image": "2.12.0",
-    "@pi-unipi/info-screen": "2.12.0",
-    "@pi-unipi/input-shortcuts": "2.12.0",
-    "@pi-unipi/kanboard": "2.12.0",
-    "@pi-unipi/mcp": "2.12.0",
-    "@pi-unipi/memory": "2.12.0",
-    "@pi-unipi/milestone": "2.12.0",
-    "@pi-unipi/notify": "2.12.0",
-    "@pi-unipi/ralph": "2.12.0",
-    "@pi-unipi/subagents": "2.12.0",
-    "@pi-unipi/trajectory": "2.12.0",
-    "@pi-unipi/updater": "2.12.0",
-    "@pi-unipi/utility": "2.12.0",
-    "@pi-unipi/web-api": "2.12.0",
-    "@pi-unipi/workflow": "2.12.0"
+    "@pi-unipi/ask-user": "2.14.1",
+    "@pi-unipi/background-tasks": "2.14.1",
+    "@pi-unipi/btw": "2.14.1",
+    "@pi-unipi/command-enchantment": "2.14.1",
+    "@pi-unipi/compactor": "2.14.1",
+    "@pi-unipi/core": "2.14.1",
+    "@pi-unipi/footer": "2.14.1",
+    "@pi-unipi/image": "2.14.1",
+    "@pi-unipi/info-screen": "2.14.1",
+    "@pi-unipi/input-shortcuts": "2.14.1",
+    "@pi-unipi/kanboard": "2.14.1",
+    "@pi-unipi/mcp": "2.14.1",
+    "@pi-unipi/memory": "2.14.1",
+    "@pi-unipi/milestone": "2.14.1",
+    "@pi-unipi/notify": "2.14.1",
+    "@pi-unipi/ralph": "2.14.1",
+    "@pi-unipi/subagents": "2.14.1",
+    "@pi-unipi/trajectory": "2.14.1",
+    "@pi-unipi/updater": "2.14.1",
+    "@pi-unipi/utility": "2.14.1",
+    "@pi-unipi/web-api": "2.14.1",
+    "@pi-unipi/workflow": "2.14.1"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.84.0",

package/packages/ask-user/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "2.12.0",
-  "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
+  "version": "2.14.1",
+  "description": "Structured user input tool for Pi coding agent \u2014 single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.12.0"
+    "@pi-unipi/core": "2.14.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "2.12.0",
+  "version": "2.14.1",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/autocomplete/src/constants.ts

@@ -131,6 +131,7 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:badge-toggle": "utility",
   "unipi:badge-settings": "utility",
   "unipi:util-settings": "utility",
+  "unipi:skills-settings": "utility",
 
   // ask-user (1 command)
   "unipi:ask-user-settings": "ask-user",
@@ -270,6 +271,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:badge-toggle": "Configure badge settings (autoGen, badgeEnabled, agentTool)",
   "unipi:badge-settings": "Configure badge settings via TUI overlay",
   "unipi:util-settings": "Unified settings — badge + diff rendering config",
+  "unipi:skills-settings": "Toggle skill startup discovery (skills catalog in system prompt)",
   "unipi:kanboard":        "Start the kanboard visualization server",
   "unipi:kanboard-doctor": "Diagnose and fix kanboard parser issues",
   "unipi:trajectory":      "Open/reuse trajectory; add stop/off or toggle to close it",

package/packages/background-tasks/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "2.13.0",
-  "description": "Background tasks for UniPi — durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
+  "version": "2.14.1",
+  "description": "Background tasks for UniPi \u2014 durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.84.0",
-    "@pi-unipi/core": "2.12.0",
+    "@pi-unipi/core": "2.14.1",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/btw/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "2.12.0",
-  "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
+  "version": "2.14.1",
+  "description": "A pi extension for parallel side conversations with /unipi:btw \u2014 part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.84.0"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.12.0"
+    "@pi-unipi/core": "2.14.1"
   },
   "pi": {
     "extensions": [

package/packages/compactor/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.12.0",
-  "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
+  "version": "2.14.1",
+  "description": "Context engine for Pi \u2014 zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -34,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.12.0",
-    "@pi-unipi/info-screen": "2.12.0",
+    "@pi-unipi/core": "2.14.1",
+    "@pi-unipi/info-screen": "2.14.1",
     "@earendil-works/pi-agent-core": "^0.84.0"
   },
   "peerDependencies": {

package/packages/core/constants.ts

@@ -161,6 +161,7 @@ export const UTILITY_COMMANDS = {
   BADGE_SETTINGS: "badge-settings",
   UTIL_SETTINGS: "util-settings",
   PREFIX_CACHE: "prefix-cache",
+  SKILLS_SETTINGS: "skills-settings",
 } as const;
 
 /** Utility tool names */

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "2.12.0",
+  "version": "2.14.1",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/footer/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "2.13.0",
-  "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
+  "version": "2.14.1",
+  "description": "Persistent status bar for Unipi \u2014 subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.12.0",
-    "@pi-unipi/background-tasks": "2.13.0"
+    "@pi-unipi/core": "2.14.1",
+    "@pi-unipi/background-tasks": "2.14.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/image/README.md

@@ -7,7 +7,7 @@ Image generation and image recognition tools for the agent.
 | Tool | Description |
 |------|-------------|
 | `image_generate` | Generate an image from a text prompt. Returned inline and saved to disk. |
-| `image_recognize` | Analyze an image with a vision model. Accepts a file path, `data:` URL, or base64. |
+| `image_recognize` | Analyze an image with a vision model. Accepts a file path, `data:` URL, or base64. Automatically hidden while the session model itself has vision. |
 
 ## Commands
 
@@ -63,6 +63,13 @@ works. Supported: PNG, JPEG, GIF, WebP. Remote URLs are not fetched.
 Prefer file paths — inlining base64 into the conversation is far more
 expensive in tokens.
 
+**Vision models don't get this tool.** When the session's current model already
+accepts image input, `image_recognize` is dropped from the active tool set —
+the model reads images natively through pi's own tools, so a separate
+recognition round-trip through another model would only duplicate that ability
+and burn context. Switch to a text-only model (via `/model`) and the tool comes
+back automatically.
+
 ## Configuration
 
 `~/.unipi/config/image/config.json`:

package/packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.12.0",
+  "version": "2.14.1",
   "description": "Image generation and image recognition tools for the Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.12.0"
+    "@pi-unipi/core": "2.14.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/packages/image/src/index.ts

@@ -20,7 +20,13 @@ import {
 
 import { registerImageCommands } from "./commands.js";
 import { registerImageTools } from "./tools.js";
-import { listImageGenModels, listVisionModels, type ChatModelRegistry } from "./models.js";
+import {
+  applyRecognizeGating,
+  isVisionModel,
+  listImageGenModels,
+  listVisionModels,
+  type ChatModelRegistry,
+} from "./models.js";
 import { registerRegistryImageProviders } from "./register-providers.js";
 import { loadConfig } from "./settings.js";
 
@@ -37,10 +43,27 @@ function getInfoRegistry() {
   ).__unipi_info_registry;
 }
 
+/**
+ * Hide image_recognize when the session model can natively see images, and
+ * restore it when a text-only model takes over. Returns whether the tool is
+ * provided after gating.
+ */
+function applyVisionGating(pi: ExtensionAPI, model: unknown): boolean {
+  const active = pi.getActiveTools();
+  const next = applyRecognizeGating(active, model, IMAGE_TOOLS.RECOGNIZE);
+  if (next !== active) pi.setActiveTools(next);
+  return next.includes(IMAGE_TOOLS.RECOGNIZE);
+}
+
 export default function (pi: ExtensionAPI) {
   registerImageTools(pi);
   registerImageCommands(pi);
 
+  pi.on("model_select", (event) => {
+    if (!loadConfig().recognize.enabled) return;
+    applyVisionGating(pi, event.model);
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const config = loadConfig();
 
@@ -51,9 +74,16 @@ export default function (pi: ExtensionAPI) {
       (ctx as unknown as { modelRegistry?: ChatModelRegistry }).modelRegistry,
     ).catch(() => undefined);
 
+    // A vision-capable session model reads images itself, so image_recognize
+    // would only duplicate that ability. Drop it from the active tool set;
+    // the model_select handler above restores it when a text-only model is
+    // chosen later in the same session.
+    const recognizeProvided =
+      config.recognize.enabled && applyVisionGating(pi, ctx.model);
+
     const tools: string[] = [];
     if (config.generate.enabled) tools.push(IMAGE_TOOLS.GENERATE);
-    if (config.recognize.enabled) tools.push(IMAGE_TOOLS.RECOGNIZE);
+    if (recognizeProvided) tools.push(IMAGE_TOOLS.RECOGNIZE);
 
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.IMAGE,
@@ -92,9 +122,11 @@ export default function (pi: ExtensionAPI) {
           .modelRegistry;
         const vision = chatRegistry ? listVisionModels(chatRegistry) : [];
 
-        const recognize = current.recognize.enabled
-          ? current.recognize.model || "Session model"
-          : "Disabled";
+        const recognize = !current.recognize.enabled
+          ? "Disabled"
+          : isVisionModel(ctx.model)
+            ? "Hidden (model has vision)"
+            : current.recognize.model || "Session model";
 
         return {
           generate: { value: generate },

package/packages/image/src/models.ts

@@ -383,7 +383,7 @@ export function listVisionModels(registry: ChatModelRegistry): VisionModel[] {
   return models.filter(isVisionModel);
 }
 
-function isVisionModel(model: unknown): model is VisionModel {
+export function isVisionModel(model: unknown): model is VisionModel {
   if (model === null || typeof model !== "object") return false;
   const candidate = model as Partial<VisionModel>;
   if (typeof candidate.id !== "string" || typeof candidate.provider !== "string") {
@@ -392,6 +392,29 @@ function isVisionModel(model: unknown): model is VisionModel {
   return Array.isArray(candidate.input) && candidate.input.includes("image");
 }
 
+/**
+ * Active tool names after hiding `recognizeTool` for a vision-capable model.
+ *
+ * A model that accepts image input can read images natively (pi's own read
+ * tool hands it the pixels), so a separate image_recognize round-trip through
+ * another model only duplicates the ability and burns system-prompt context.
+ * Text-only models get the tool back. Models that do not declare their input
+ * modalities are treated as non-vision, matching `isVisionModel`.
+ */
+export function applyRecognizeGating(
+  active: string[],
+  model: unknown,
+  recognizeTool: string,
+): string[] {
+  const vision = isVisionModel(model);
+  const present = active.includes(recognizeTool);
+  // Already correct: hidden for a vision model, or provided for a text-only one.
+  if (vision !== present) return active;
+  return vision
+    ? active.filter((name) => name !== recognizeTool)
+    : [...active, recognizeTool];
+}
+
 /**
  * Resolve a vision-model reference, restricted to image-capable models.
  *

package/packages/info-screen/index.ts

@@ -113,10 +113,19 @@ export default function (pi: ExtensionAPI) {
    */
   function showOverlay(ctx: ExtensionContext, autoCloseMs?: number): void {
     let overlay: InfoOverlay;
+    // Splash mode (auto-close): the overlay must NEVER take keyboard focus —
+    // it lives exactly during the window where the user starts typing their
+    // first prompt. A capturing overlay here eats those keystrokes (worse: its
+    // vim-style keys "work", so command text vanishes into tab switches), and
+    // its first-keypress-cancels-auto-close rule strands it on screen forever
+    // as an unclosable, input-eating zombie. Non-capturing + stack-safe
+    // self-dismiss (see startBootTimer) makes it pure eye-candy.
+    const splashMode = autoCloseMs !== undefined && autoCloseMs > 0;
     ctx.ui.custom<void>(
       (tui, theme, _keybindings, done) => {
         overlay = new InfoOverlay();
         overlay.setTheme(theme);
+        overlay.interactive = !splashMode;
         overlayVisible = true;
         overlay.onClose = () => {
           overlayVisible = false;
@@ -127,14 +136,37 @@ export default function (pi: ExtensionAPI) {
         const component = {
           render: (w: number) => overlay.render(w),
           invalidate: () => overlay.invalidate(),
+          // In splash mode the overlay is non-capturing and never receives
+          // input; keep handleInput wired for interactive ("on") mode.
           handleInput: (data: string) => {
             overlay.handleInput(data);
             tui.requestRender();
           },
         };
-        // Boot dashboard dismisses itself; any keypress cancels the timer.
+        // Splash self-dismiss may only run while this overlay is the topmost
+        // VISIBLE entry of the TUI overlay stack. If the user opens anything
+        // during the splash window (a /unipi:… settings dialog, the updater's
+        // update prompt, …), dismissal must wait — removing a covered entry
+        // breaks the covering overlay (pi retargets focus and orphans its
+        // pending interaction, e.g. a hung ctx.ui.select promise). Re-check
+        // on every timer tick; once the stack clears we dismiss as usual.
+        const isTopmostVisible = (): boolean => {
+          try {
+            const stack = (tui as unknown as { overlayStack?: Array<{ component?: unknown; hidden?: boolean }> }).overlayStack;
+            if (!stack || stack.length === 0) return true;
+            for (let i = stack.length - 1; i >= 0; i--) {
+              const entry = stack[i];
+              if (entry?.hidden) continue;
+              return entry?.component === component;
+            }
+            return true;
+          } catch {
+            return true; // Stack unreadable — assume topmost (legacy behavior).
+          }
+        };
+        // Boot dashboard dismisses itself (splash mode).
         if (autoCloseMs && autoCloseMs > 0) {
-          overlay.startBootTimer(autoCloseMs);
+          overlay.startBootTimer(autoCloseMs, isTopmostVisible);
         }
         return component;
       },
@@ -145,17 +177,24 @@ export default function (pi: ExtensionAPI) {
           minWidth: 60,
           anchor: "center" as const,
           margin: 2,
+          nonCapturing: splashMode,
         },
-        // `done()` (the extension UI's close callback) pops the *topmost* overlay
-        // in the TUI stack, not this one specifically. When another overlay (e.g.
-        // the updater's "Update Available" prompt) is stacked on top, the boot
-        // auto-close timer must not fire `done()` — that would pop the covering
-        // overlay and strand this dashboard with a spent one-shot close the user
-        // can no longer dismiss. `isTopmostOverlay` lets the boot timer defer
-        // until we are the focused (topmost) entry; the user can still press
-        // q/Esc to close once the covering overlay is gone.
+        // In splash mode the timer uses `selfHide` (handle.hide() splices this
+        // entry out by identity) guarded by the topmost-visible check above —
+        // never `done()`, which pops whatever is TOPMOST. `isTopmostOverlay`
+        // remains as the focused-done() fallback for interactive ("on") mode,
+        // where the user drives the dashboard directly: it is topmost while
+        // being driven, so the q/Esc → done() path is correct there.
         onHandle: (handle) => {
           overlay.isTopmostOverlay = () => handle.isFocused();
+          overlay.selfHide = () => {
+            overlayVisible = false;
+            if (typeof handle.hide === "function") {
+              handle.hide();
+            } else if (typeof (handle as { setHidden?: (v: boolean) => void }).setHidden === "function") {
+              (handle as { setHidden: (v: boolean) => void }).setHidden(true);
+            }
+          };
         },
       }
     );

package/packages/info-screen/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/info-screen",
-  "version": "2.12.0",
-  "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
+  "version": "2.14.1",
+  "description": "Dashboard and module registry for Unipi \u2014 configurable info overlay with tabbed groups",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.12.0"
+    "@pi-unipi/core": "2.14.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/info-screen/tui/info-overlay.ts

@@ -69,6 +69,21 @@ export class InfoOverlay implements Component {
    * `startBootTimer` for why.
    */
   isTopmostOverlay?: () => boolean;
+  /**
+   * Stack-safe self-removal via the overlay handle (`handle.hide()` splices
+   * this entry out of the TUI stack by identity, unlike `done()` which pops
+   * whatever is TOPMOST). Set from `onHandle` in index.ts. When available,
+   * the boot auto-close timer prefers this over `done()` so a splash that
+   * lingers while another overlay opens can never dismiss that overlay
+   * instead of itself.
+   */
+  selfHide?: () => void;
+  /**
+   * False when running as a non-capturing boot splash (auto-close): the
+   * overlay never receives keyboard input, so interactive hints like
+   * "q/Esc close" would be misleading and are replaced accordingly.
+   */
+  interactive = true;
 
   private overlay = new OverlayTheme();
 
@@ -232,31 +247,46 @@ export class InfoOverlay implements Component {
   }
 
   /**
-   * Auto-close the overlay after `ms`, unless the user interacts first.
+   * Auto-close the overlay after `ms`.
    *
-   * Used when the overlay is shown on boot: the dashboard is informational, so
-   * it should get out of the way on its own rather than requiring a keypress.
+   * Used when the overlay is shown as a boot splash: the dashboard is
+   * informational, so it should get out of the way on its own rather than
+   * requiring a keypress.
    *
-   * The close callback (`onClose` → `done`) pops the *topmost* overlay in the
-   * TUI stack, not this one specifically. When another overlay (e.g. the
-   * updater's "Update Available" prompt) is stacked on top, firing `done()`
-   * here would remove the covering overlay and strand this dashboard with a
-   * spent one-shot close the user can no longer trigger — leaving the starting
-   * screen stuck. So we defer the auto-close until we are actually the
-   * focused/topmost overlay; the user can still press q/Esc to dismiss it once
-   * the covering overlay is gone.
+   * Dismissal uses `selfHide` (handle.hide() — removes THIS entry from the
+   * TUI overlay stack by identity) and only fires while `isTopmostVisible`
+   * confirms nothing is stacked above: dismissing a covered overlay breaks
+   * the covering one (pi retargets focus and orphans its pending
+   * interaction, e.g. a ctx.ui.select promise that never resolves while its
+   * overlay vanishes). If covered, the timer re-arms and retries.
+   *
+   * If `selfHide` is unavailable (older host), falls back to the guarded
+   * `onClose` (`done()`) path, which requires focus (topmost) for the same
+   * reason.
    */
-  startBootTimer(ms: number): void {
+  startBootTimer(ms: number, isTopmostVisible?: () => boolean): void {
     this.cancelBootTimer();
     if (!Number.isFinite(ms) || ms <= 0) return;
     const arm = (): void => {
       this.bootTimer = setTimeout(() => {
         this.bootTimer = null;
         if (this._destroyed) return;
+        if (this.selfHide) {
+          if (isTopmostVisible && !isTopmostVisible()) {
+            // Something is stacked on top of us — dismissing now would break
+            // it (orphaned select promise, focus retarget). Retry shortly;
+            // once the stack clears we dismiss as usual.
+            arm();
+            return;
+          }
+          this.selfHide();
+          this.destroy();
+          return;
+        }
         if (this.isTopmostOverlay && !this.isTopmostOverlay()) {
-          // Something is stacked on top of us — closing now would pop it
-          // instead of this dashboard. Retry shortly; once the covering
-          // overlay closes we'll be topmost and can auto-close safely.
+          // Fallback (no selfHide available): closing now would pop the
+          // covering overlay instead of this dashboard. Retry shortly; once
+          // we are topmost the close is safe.
           arm();
           return;
         }
@@ -346,7 +376,7 @@ export class InfoOverlay implements Component {
     lines.push(this.overlay.frameLine(this.overlay.fg("dim", "Modules will register groups on startup."), innerWidth));
     for (let i = 0; i < 4; i++) lines.push(this.overlay.frameLine("", innerWidth));
     lines.push(this.overlay.ruleLine(innerWidth));
-    lines.push(this.overlay.frameLine(this.overlay.fg("dim", "q/Esc close · r refresh"), innerWidth));
+    lines.push(this.overlay.frameLine(this.overlay.fg("dim", this.interactive ? "q/Esc close · r refresh" : "auto-dismissing…"), innerWidth));
     lines.push(this.overlay.borderLine(innerWidth, "bottom"));
     return lines;
   }
@@ -529,12 +559,14 @@ export class InfoOverlay implements Component {
     const lastUp = infoRegistry.getLastUpdated(group?.id ?? "");
     const age = lastUp > 0 ? humanizeAge(Date.now() - lastUp) : "loading…";
 
-    const hints = [
-      `${this.overlay.fg("accent", "←/→")} tabs`,
-      `${this.overlay.fg("success", "↑/↓")} scroll`,
-      `${this.overlay.fg("warning", "r")} refresh`,
-      `${this.overlay.fg("error", "q/Esc")} close`,
-    ];
+    const hints = this.interactive
+      ? [
+          `${this.overlay.fg("accent", "←/→")} tabs`,
+          `${this.overlay.fg("success", "↑/↓")} scroll`,
+          `${this.overlay.fg("warning", "r")} refresh`,
+          `${this.overlay.fg("error", "q/Esc")} close`,
+        ]
+      : [`${this.overlay.fg("dim", "auto-dismissing…")}`];
 
     const hintStr = hints.join(`  ${this.overlay.fg("borderMuted", "•")}  `);