wotann 0.5.84 → 0.5.85

package/dist/index.js

@@ -260,7 +260,9 @@ program
         try {
             const { createRuntime } = await import("./core/runtime.js");
             const { runRuntimeQuery } = await import("./cli/runtime-query.js");
-            const jsonSchema = options.jsonSchema !== undefined ? parseJsonSchemaOption(options.jsonSchema) : undefined;
+            const jsonSchema = options.jsonSchema !== undefined
+                ? parseJsonSchemaOption(options.jsonSchema)
+                : undefined;
             const prContext = options.fromPr !== undefined ? loadPullRequestContext(options.fromPr) : undefined;
             const runtime = await createRuntime(process.cwd(), undefined, {
                 ...(options.bare
@@ -402,13 +404,22 @@ program
         process.stderr.write("[wotann] Unknown renderer. Use --renderer ink or --renderer opentui.\n");
         return;
     }
-    // Switch to the alternate screen buffer before Ink takes over
-    // so the TUI gets the entire viewport and the user's scrollback
-    // is preserved untouched. 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`.
-    const { isAltBufferRequested, enterAltBuffer } = await import("./ui/alt-buffer.js");
+    // Pre-load the heavy UI modules BEFORE entering alt-buffer so the
+    // window between alt-buffer entry and first Ink frame is near-zero.
+    // Otherwise the user stares at a pitch-black alt-buffer while
+    // AppV3 + Ink + react-reconciler hydrate, which is exactly the
+    // "npx wotann hangs and shows a black screen" symptom users have
+    // reported (2026-05-23 P0). Parallel imports cut the wait further.
+    const [{ AppV3 }, { mountInteractiveInk }, altBufferModule] = await Promise.all([
+        import("./ui/components/v3/index.js"),
+        import("./ui/mount-interactive-ink.js"),
+        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();
     }
@@ -419,17 +430,34 @@ program
     // (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.
-    const { AppV3 } = await import("./ui/components/v3/index.js");
-    const { mountInteractiveInk } = await import("./ui/mount-interactive-ink.js");
-    const { refused } = await mountInteractiveInk(React.createElement(AppV3, {
-        version: VERSION,
-        providers: interactive.providers,
-        initialModel: interactive.initialModel,
-        initialProvider: interactive.initialProvider,
-        runtime: interactive.runtime,
-    }));
-    if (refused)
+    //
+    // 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.
+    let mountResult;
+    try {
+        mountResult = await mountInteractiveInk(React.createElement(AppV3, {
+            version: VERSION,
+            providers: interactive.providers,
+            initialModel: interactive.initialModel,
+            initialProvider: interactive.initialProvider,
+            runtime: interactive.runtime,
+        }));
+    }
+    catch (error) {
+        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.
+        exitAltBuffer();
         return;
+    }
 });
 // ── wotann cli-generate (CLI-Anything 7-phase generator) ─────────
 program
@@ -1908,10 +1936,16 @@ program
     console.log(chalk.green("  Session context restored. Continue where you left off.\n"));
     const ReactModule = await import("react");
     const React = ReactModule.default;
-    // Same fullscreen-mode hook as `wotann start` — env var only here
-    // (no CLI flag on `wotann resume`). Default ON; disable via
-    // `WOTANN_FULLSCREEN=0`.
-    const { isAltBufferRequested, enterAltBuffer } = await import("./ui/alt-buffer.js");
+    // Pre-load heavy UI modules in parallel BEFORE entering alt-buffer
+    // (npx pitch-black fix 2026-05-23). Same fullscreen-mode hook as
+    // `wotann start` — env var only here (no CLI flag on `wotann
+    // resume`). Default ON; disable via `WOTANN_FULLSCREEN=0`.
+    const [{ AppV3 }, { mountInteractiveInk }, altBufferModule] = await Promise.all([
+        import("./ui/components/v3/index.js"),
+        import("./ui/mount-interactive-ink.js"),
+        import("./ui/alt-buffer.js"),
+    ]);
+    const { isAltBufferRequested, enterAltBuffer, exitAltBuffer } = altBufferModule;
     if (isAltBufferRequested(true)) {
         enterAltBuffer();
     }
@@ -1919,18 +1953,28 @@ program
     // 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.
-    const { AppV3 } = await import("./ui/components/v3/index.js");
-    const { mountInteractiveInk } = await import("./ui/mount-interactive-ink.js");
-    const { refused } = await mountInteractiveInk(React.createElement(AppV3, {
-        version: VERSION,
-        providers: interactive.providers,
-        initialModel: session.model,
-        initialProvider: session.provider,
-        initialMessages: session.messages,
-        runtime: interactive.runtime,
-    }));
-    if (refused)
+    // try/catch + exitAltBuffer pair ensures the user always sees the
+    // diagnostic on Ink-mount failure instead of a frozen black screen.
+    let mountResult;
+    try {
+        mountResult = await mountInteractiveInk(React.createElement(AppV3, {
+            version: VERSION,
+            providers: interactive.providers,
+            initialModel: session.model,
+            initialProvider: session.provider,
+            initialMessages: session.messages,
+            runtime: interactive.runtime,
+        }));
+    }
+    catch (error) {
+        exitAltBuffer();
+        process.stderr.write(`[wotann] Interactive TUI failed to mount: ${error instanceof Error ? error.message : String(error)}\n`);
         return;
+    }
+    if (mountResult.refused) {
+        exitAltBuffer();
+        return;
+    }
 });
 // ── wotann rewind ───────────────────────────────────────────
 //

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

@@ -56,6 +56,14 @@ export interface MountInteractiveResult {
  * degraded-terminal case — it returns `{ instance: null, refused: true }`
  * after writing actionable guidance, so the caller exits cleanly
  * instead of hanging.
+ *
+ * Ink-render-throws backstop (added 2026-05-23, npx pitch-black fix):
+ * even with the raw-mode-guard probe in front, Ink's reconciler can
+ * still throw during its first `useInput` commit on terminal combos
+ * where `setRawMode` exists, passes the probe, then fails on the
+ * *specific* `(true)` call Ink makes. Catching here and returning
+ * `refused: true` lets the caller exit the alt-buffer + show the
+ * user the actual failure instead of a frozen black screen.
  */
 export declare function mountInteractiveInk(element: ReactElement, opts?: MountInteractiveOptions): Promise<MountInteractiveResult>;
 export {};

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

@@ -33,6 +33,14 @@ export const DEFAULT_REFUSAL_MESSAGE = "[wotann] No raw-mode-capable terminal av
  * degraded-terminal case — it returns `{ instance: null, refused: true }`
  * after writing actionable guidance, so the caller exits cleanly
  * instead of hanging.
+ *
+ * Ink-render-throws backstop (added 2026-05-23, npx pitch-black fix):
+ * even with the raw-mode-guard probe in front, Ink's reconciler can
+ * still throw during its first `useInput` commit on terminal combos
+ * where `setRawMode` exists, passes the probe, then fails on the
+ * *specific* `(true)` call Ink makes. Catching here and returning
+ * `refused: true` lets the caller exit the alt-buffer + show the
+ * user the actual failure instead of a frozen black screen.
  */
 export async function mountInteractiveInk(element, opts = {}) {
     const ensureViewport = opts.ensureViewport ?? ensureRenderableViewport;
@@ -47,6 +55,18 @@ export async function mountInteractiveInk(element, opts = {}) {
         return { instance: null, refused: true };
     }
     const inkRender = opts.inkRender ?? (await import("ink")).render;
-    const instance = inkRender(element, { stdin: inputStdin });
-    return { instance, refused: false };
+    try {
+        const instance = inkRender(element, { stdin: inputStdin });
+        return { instance, refused: false };
+    }
+    catch (error) {
+        const sink = opts.stderr ?? process.stderr;
+        const message = error instanceof Error ? error.message : String(error);
+        sink.write(`[wotann] Interactive TUI failed to mount: ${message}\n` +
+            "  This usually means the terminal accepted setRawMode but Ink's\n" +
+            "  first input commit threw under this launcher. Options:\n" +
+            "    • `npm i -g wotann` then run `wotann` in a fresh terminal\n" +
+            '    • non-interactive: `wotann -p "your prompt"`\n');
+        return { instance: null, refused: true };
+    }
 }

package/dist/ui/raw-mode-guard.d.ts

@@ -18,11 +18,26 @@
  */
 export interface RawModeStream {
     readonly isTTY?: unknown;
+    readonly isRaw?: unknown;
     setRawMode?: unknown;
 }
 /**
- * True iff `stream` is a TTY that exposes a `setRawMode` function —
- * exactly Ink's precondition for `useInput()`. Never throws.
+ * True iff `stream` is a TTY that exposes a `setRawMode` function AND
+ * that function works when invoked — exactly Ink's runtime precondition
+ * for `useInput()`. Never throws.
+ *
+ * The shape check (`isTTY === true` + `typeof setRawMode === "function"`)
+ * caught one silent-failure class — degraded stdin — but missed a
+ * second one: some `npx`/terminal combinations expose `setRawMode` as
+ * a function that THROWS the moment Ink invokes it during the first
+ * `useInput` hook. The property-only check passed, Ink mounted into
+ * an alt-buffer, Ink's reconciler error-looped on the rejected raw
+ * mode call, and the user saw the reported "pitch-black screen, TUI
+ * never paints" symptom. The probe below catches that case: call
+ * `setRawMode` with the CURRENT raw-state (idempotent — terminal
+ * state is preserved when it works) inside a try/catch. If it throws
+ * here, the resolver falls through to `/dev/tty` or refuses cleanly
+ * instead of mounting Ink into the silent loop.
  */
 export declare function isRawModeCapable(stream: unknown): boolean;
 export interface ResolveStdinOptions {

package/dist/ui/raw-mode-guard.js

@@ -19,14 +19,38 @@
 import { openSync } from "node:fs";
 import { ReadStream } from "node:tty";
 /**
- * True iff `stream` is a TTY that exposes a `setRawMode` function —
- * exactly Ink's precondition for `useInput()`. Never throws.
+ * True iff `stream` is a TTY that exposes a `setRawMode` function AND
+ * that function works when invoked — exactly Ink's runtime precondition
+ * for `useInput()`. Never throws.
+ *
+ * The shape check (`isTTY === true` + `typeof setRawMode === "function"`)
+ * caught one silent-failure class — degraded stdin — but missed a
+ * second one: some `npx`/terminal combinations expose `setRawMode` as
+ * a function that THROWS the moment Ink invokes it during the first
+ * `useInput` hook. The property-only check passed, Ink mounted into
+ * an alt-buffer, Ink's reconciler error-looped on the rejected raw
+ * mode call, and the user saw the reported "pitch-black screen, TUI
+ * never paints" symptom. The probe below catches that case: call
+ * `setRawMode` with the CURRENT raw-state (idempotent — terminal
+ * state is preserved when it works) inside a try/catch. If it throws
+ * here, the resolver falls through to `/dev/tty` or refuses cleanly
+ * instead of mounting Ink into the silent loop.
  */
 export function isRawModeCapable(stream) {
     if (stream === null || typeof stream !== "object")
         return false;
     const s = stream;
-    return s.isTTY === true && typeof s.setRawMode === "function";
+    if (s.isTTY !== true || typeof s.setRawMode !== "function")
+        return false;
+    try {
+        const setRawMode = s.setRawMode;
+        const currentIsRaw = s.isRaw === true;
+        setRawMode(currentIsRaw);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Open the controlling terminal as a raw-capable input stream, or

package/package.json

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