wotann 0.5.88 → 0.5.90

package/dist/index.js

@@ -416,26 +416,21 @@ program
         import("./ui/alt-buffer.js"),
     ]);
     const { isAltBufferRequested, enterAltBuffer, exitAltBuffer } = altBufferModule;
-    // Switch to the alternate screen buffer NOW that the heavy modules
-    // are loaded. Crash-safe — alt-buffer.ts wires SIGINT/SIGTERM/
-    // uncaughtException to always restore the main buffer. Default ON;
-    // disable with `--no-fullscreen` or `WOTANN_FULLSCREEN=0`.
-    if (isAltBufferRequested(options.fullscreen !== false)) {
-        enterAltBuffer();
-    }
+    const wantsAltBuffer = isAltBufferRequested(options.fullscreen !== false);
     // Mount the single V3 shell through the ONE guarded gate every
-    // interactive Ink mount must use: viewport repair (Ink reads
-    // stdout.columns directly — undefined under npx collapses the
-    // root box to width 0), raw-mode-capable stdin resolution
-    // (process.stdin → /dev/tty → none), and refuse-cleanly-with-
-    // guidance instead of mounting Ink into the error-render-loop
-    // hang ("npx wotann just hangs"). See ui/mount-interactive-ink.ts.
+    // interactive Ink mount must use: viewport repair, raw-mode-
+    // capable stdin resolution, refuse-cleanly-with-guidance.
+    // See src/ui/mount-interactive-ink.ts for the full contract.
     //
-    // The try/catch + exitAltBuffer pair is the recovery contract:
-    // if Ink throws (e.g. setRawMode passes the guard probe but
-    // fails on Ink's first useInput commit on some terminal combos),
-    // we ALWAYS restore the main buffer first so the user sees the
-    // diagnostic instead of a frozen black screen.
+    // v0.5.89 hotfix: alt-buffer entry is now gated through
+    // `onResolved`, which fires AFTER the guard probe succeeds and
+    // BEFORE Ink's first paint. Entering eagerly (v0.5.85 → v0.5.88
+    // behavior) meant any guard refusal would write the diagnostic
+    // INTO the alt-buffer, then exitAltBuffer would tear it down,
+    // leaving the user with no visible error message ("npx wotann
+    // exits silently" — user-reported 2026-05-24). Now: refusal
+    // path NEVER enters alt-buffer, so the diagnostic stays visible
+    // in the main buffer.
     let mountResult;
     try {
         mountResult = await mountInteractiveInk(React.createElement(AppV3, {
@@ -444,17 +439,26 @@ program
             initialModel: interactive.initialModel,
             initialProvider: interactive.initialProvider,
             runtime: interactive.runtime,
-        }));
+        }), {
+            onResolved: () => {
+                if (wantsAltBuffer)
+                    enterAltBuffer();
+            },
+        });
     }
     catch (error) {
+        // If onResolved fired, alt-buffer is up; restore main buffer
+        // so the error message is visible. Idempotent — no-op if
+        // alt-buffer was never entered.
         exitAltBuffer();
         process.stderr.write(`[wotann] Interactive TUI failed to mount: ${error instanceof Error ? error.message : String(error)}\n`);
         return;
     }
     if (mountResult.refused) {
-        // mountInteractiveInk already wrote actionable guidance to
-        // stderr. Restore main buffer so guidance is visible instead
-        // of trapped behind an alt-buffer Ink never painted into.
+        // onResolved did NOT fire (guard refused or Ink threw before
+        // commit). Alt-buffer was never entered. exitAltBuffer is
+        // still safe (idempotent), but the diagnostic mountInteractiveInk
+        // wrote to stderr is already visible in the main buffer.
         exitAltBuffer();
         return;
     }
@@ -1946,15 +1950,10 @@ program
         import("./ui/alt-buffer.js"),
     ]);
     const { isAltBufferRequested, enterAltBuffer, exitAltBuffer } = altBufferModule;
-    if (isAltBufferRequested(true)) {
-        enterAltBuffer();
-    }
-    // Single V3 shell — initialMessages seeds the transcript so the
-    // resumed session continues where it left off (AppV3 wires it via
-    // useState([...initialMessages])). Same guarded gate as the start
-    // path: viewport repair + raw-mode stdin + refuse-instead-of-hang.
-    // try/catch + exitAltBuffer pair ensures the user always sees the
-    // diagnostic on Ink-mount failure instead of a frozen black screen.
+    const wantsAltBuffer = isAltBufferRequested(true);
+    // v0.5.89 hotfix: alt-buffer entry is now gated through `onResolved`
+    // so a guard refusal never swallows the diagnostic. See start
+    // command for the full discussion.
     let mountResult;
     try {
         mountResult = await mountInteractiveInk(React.createElement(AppV3, {
@@ -1964,7 +1963,12 @@ program
             initialProvider: session.provider,
             initialMessages: session.messages,
             runtime: interactive.runtime,
-        }));
+        }), {
+            onResolved: () => {
+                if (wantsAltBuffer)
+                    enterAltBuffer();
+            },
+        });
     }
     catch (error) {
         exitAltBuffer();

package/dist/ui/mount-interactive-ink.d.ts

@@ -39,6 +39,20 @@ export interface MountInteractiveOptions {
     };
     /** Replace the default refusal guidance text. */
     readonly refusalMessage?: string;
+    /**
+     * Fires AFTER stdin resolution succeeds and BEFORE Ink's `render`
+     * commits its first frame. Lets the caller enter the alt-buffer
+     * ONLY when we're committed to mounting — avoiding the
+     * "enter-alt-buffer, write refusal in alt-buffer, exit-alt-buffer,
+     * refusal swallowed" bug fixed in v0.5.89 (user-reported regression
+     * in v0.5.88 where `npx wotann` exited silently because the
+     * diagnostic was lost in the alt-buffer tear-down).
+     *
+     * When the guard refuses or Ink throws, this callback DOES NOT fire,
+     * so any caller-side side effects (alt-buffer entry) are skipped and
+     * the stderr diagnostic stays visible in the main buffer.
+     */
+    readonly onResolved?: () => void;
 }
 export interface MountInteractiveResult {
     /**

package/dist/ui/mount-interactive-ink.js

@@ -55,6 +55,10 @@ export async function mountInteractiveInk(element, opts = {}) {
         return { instance: null, refused: true };
     }
     const inkRender = opts.inkRender ?? (await import("ink")).render;
+    // We are committed to mounting — fire the caller's pre-mount hook so
+    // it can enter alt-buffer (or any other render-time setup) NOW, after
+    // the guard passed and before Ink's first frame paints.
+    opts.onResolved?.();
     try {
         const instance = inkRender(element, { stdin: inputStdin });
         return { instance, refused: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wotann",
-  "version": "0.5.88",
+  "version": "0.5.90",
   "description": "WOTANN — The All-Father of AI Agent Harnesses",
   "type": "module",
   "main": "dist/index.js",