@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/tui/repl-render.js

@@ -1,29 +1,38 @@
 /**
- * Production REPL mount + transport - Sprint α5.7.
+ * Production REPL mount + transport - Sprint .
  *
  * Owns the Ink mount lifecycle for `<Repl />` and wires the real
  * fetch + SSE transport. The CLI dispatcher in `runtime/cli.ts` calls
  * `renderRepl` on the bare-`pugi` path when stdin / stdout are TTYs.
  *
  * The transport speaks to admin-api:
- *   POST /api/pugi/sessions             → { sessionId }
- *   POST /api/pugi/sessions/:id/brief   → { dispatchId }
- *   POST /api/pugi/sessions/:id/stop    → { stopped }
- *   GET  /api/pugi/sessions/:id/stream  → text/event-stream
+ *  POST /api/pugi/sessions            → { sessionId }
+ *  POST /api/pugi/sessions/:id/brief  → { dispatchId }
+ *  POST /api/pugi/sessions/:id/stop   → { stopped }
+ *  GET /api/pugi/sessions/:id/stream → text/event-stream
  *
  * SSE is parsed client-side from a streaming fetch response - Node 22
  * native fetch returns a WHATWG `ReadableStream` which we feed through
  * a tiny `event:`/`data:`/`id:` parser. This keeps the dependency
  * graph at zero new packages.
  */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
 import React from 'react';
 import { render } from 'ink';
 import { Repl } from './repl.js';
 import { printPugMascotPreInk } from './repl-splash-mascot.js';
+import { collectWelcomeData } from './welcome-data.js';
+import { ThemeProvider } from '../core/theme/context.js';
+import { resolveTheme } from '../core/theme/state.js';
 import { ReplSession, } from '../core/repl/session.js';
 import { resolveWorkspaceContext } from '../core/repl/workspace-context.js';
+import { createEngineBridge } from '../core/repl/engine-bridge.js';
+import { profileFor, resolveIntensity } from '../core/engine/intensity.js';
 import { SqliteSessionStore } from '../core/repl/store/index.js';
 import { slugForCwd } from '../core/repl/history.js';
+import { loadSettings } from '../core/settings.js';
+import { buildRuntimeConfig } from '@pugi/sdk';
 import { WorkingSet, buildRepoSkeleton, loadPugiIgnore, PugiWatcher, } from '../core/context/index.js';
 /**
  * Mount the REPL and resolve when the user exits via Ctrl+C × 2 or
@@ -31,13 +40,86 @@ import { WorkingSet, buildRepoSkeleton, loadPugiIgnore, PugiWatcher, } from '../
  * `pugi resume <sessionId>` once that command exists).
  */
 export async function renderRepl(options) {
+    // beta.9 CEO dogfood: claim stdin raw mode + alt-screen
+    // BEFORE any async bootstrap step so keystrokes typed during the
+    // [launch -> Ink mount] window cannot echo into the terminal in
+    // cooked mode. Previously openLocalStore (SQLite open) +
+    // bootstrapContext (chokidar start) could take hundreds of ms to
+    // multiple seconds on a fresh install / large repo; during that
+    // window stdin stayed in cooked mode and the terminal echoed
+    // every typed character literally onto the screen below the
+    // pre-printed mascot/header. The visible result was the operator's
+    // "ssssss" landing on the rendered status-bar bottom row (CEO
+    // screenshot: beta.8 REPL bug 2).
+    //
+    // The claim is idempotent with Ink's own raw-mode enable: Ink
+    // ref-counts setRawMode calls, and Node's stdin.setRawMode is
+    // safe to call twice with the same value. The pre-Ink claim acts
+    // as a "raw-mode floor" - whatever Ink does after mount layers on
+    // top, and our finally{} restore drops the floor only after Ink
+    // has cleanly torn down (or never mounted on a bootstrap crash).
+    const bootstrap = claimTerminalForRepl();
+    // beta.13 auto-init wire (CEO dogfood): scaffold the
+    // `.pugi/` workspace silently on REPL boot so launching `pugi` in a
+    // fresh cwd no longer demands an explicit `pugi init` round-trip.
+    // Idempotent — every helper inside scaffoldPugiWorkspace is a
+    // `*_IfMissing` write, so re-running over an existing workspace is
+    // a no-op. Fail-safe: any FS / perms error never blocks REPL launch.
+    // Operator escape hatch: PUGI_NO_AUTO_INIT=1.
+    //
+    // Beta.13 P2 fix: gate the scaffold on project-root markers
+    // so launching `pugi` from `$HOME` / `/tmp` / arbitrary dirs does NOT
+    // sprinkle `.pugi/` directories all over the filesystem. The gate
+    // mirrors `isBoundWorkspace` from workspace-context.ts but also
+    // accepts non-JS roots (Cargo / pyproject / go.mod) because the CLI
+    // is language-agnostic and an operator working in a Rust repo deserves
+    // the same auto-init UX as a Node operator. Already-bound `.pugi/`
+    // dirs also opt back in so the scaffold can fill any missing
+    // sub-artifacts the operator deleted.
+    // `--bare` (PUGI_BARE=1) ALSO suppresses the
+    // auto-init scaffold. Bare mode is the deterministic "fresh install
+    // anywhere" path — no `.pugi/` writes, no PUGI.md scaffold, no
+    // settings.json seed. The pre-existing PUGI_NO_AUTO_INIT escape
+    // hatch stays — bare mode just unions with it.
+    const { isBareMode } = await import('../core/bare-mode/index.js');
+    if (process.env.PUGI_NO_AUTO_INIT !== '1' &&
+        !isBareMode() &&
+        isProjectRoot(process.cwd())) {
+        try {
+            const { scaffoldPugiWorkspace } = await import('../runtime/cli.js');
+            await scaffoldPugiWorkspace({
+                cwd: process.cwd(),
+                noDefaults: true,
+                log: () => {
+                    /* silent — never leak scaffold progress into the REPL alt-screen */
+                },
+            });
+        }
+        catch (err) {
+            // Fail-safe: read-only FS or perms error never blocks REPL launch.
+            // Beta.13 P2 fix: bare-catch swallowed the diagnostic;
+            // surface it on stderr under PUGI_DEBUG=1 so operator-triage on
+            // "why isn't .pugi/ being created?" has a starting point without
+            // having to re-instrument the bootstrap.
+            if (process.env.PUGI_DEBUG === '1') {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[pugi-debug] auto-init failed: ${msg}\n`);
+            }
+        }
+    }
     const transport = createProductionTransport();
-    // Auto-bind the workspace context from process.cwd() so Mira knows
+    // Auto-bind the workspace context from process.cwd() so Pugi knows
     // which repo the operator launched the CLI in. The resolver is
     // best-effort — any FS error falls back to a basename-only summary,
-    // never blocks REPL launch. Wave 4 fix 2026-05-25.
+    // never blocks REPL launch. fix.
     const workspace = options.workspace ?? resolveWorkspaceContext(process.cwd());
-    // α6.4: open the local SessionStore for `/resume` persistence. The
+    // Beta.13 P1 fix: read `ui.cyberZoo` from
+    // `.pugi/settings.json` so the operator's splash posture flows to
+    // admin-api on session open. Without this, the renderer's `cyberZoo`
+    // parameter (added beta.13) was always defaulted to 'on' regardless
+    // of the operator's actual setting.
+    const cyberZoo = readCyberZooSetting(process.cwd());
+    // : open the local SessionStore for `/resume` persistence. The
     // store lives under `~/.pugi/projects/<slug>/`; failure is fail-safe
     // — we log a one-line warning to stderr and continue with the REPL
     // in memory-only mode. Lock-busy errors get the friendliest message
@@ -49,7 +131,7 @@ export async function renderRepl(options) {
         workspaceRoot: process.cwd(),
         resumeLocalSessionId: options.resumeLocalSessionId,
     });
-    // α6.5 three-tier context bootstrap. The skeleton + working set
+    // three-tier context bootstrap. The skeleton + working set
     // + watcher are local-first and best-effort: every step is wrapped
     // in try/catch so an unreadable workspace never blocks REPL launch.
     // Opt-out via PUGI_DISABLE_CONTEXT=1 for hermetic test runs.
@@ -57,13 +139,63 @@ export async function renderRepl(options) {
         cwd: process.cwd(),
         env: process.env,
     });
+    // PUGI-538c () -- wire the production engine bridge so
+    // `<pugi-tool-route>` envelopes emitted by Pugi's coordinator
+    // actually drive a local `NativePugiEngineAdapter` run instead of
+    // surfacing "Engine bridge not configured" on the system line. The
+    // factory closure resolves `cwd` per invocation so an operator who
+    // `cd`-ed mid-session writes files into the new directory (matches
+    // `pugi code` direct-path behaviour).
+    //
+    // The bridge runtime config reuses the REPL transport credentials so
+    // a single token authenticates both the coordinator brief (via
+    // admin-api /api/pugi/sessions) AND the bridged engine call (via
+    // /api/pugi/engine). No new credential surface, no double login.
+    //
+    // Fail-safe construction: `buildRuntimeConfig` validates apiUrl via
+    // `z.string().url()` and throws on a malformed value. We must not
+    // crash REPL launch on that path -- every other bootstrap step in
+    // this file (auto-init, openLocalStore, bootstrapContext, watcher)
+    // is fail-safe. On construction failure we surface a one-line stderr
+    // diagnostic under PUGI_DEBUG=1 and pass `engineBridge: undefined`
+    // so the REPL launches; the operator sees the legacy "Engine bridge
+    // not configured" system line on the first routed brief, which is
+    // the same UX as a pre-PUGI-538c CLI build.
+    let engineBridge;
+    try {
+        // PR A (2026-06-05): resolve intensity profile once at bridge
+        // construction time. The bridge stays pure and re-uses the resolved
+        // profile across every routed brief. `resolveIntensity` reads env
+        // (`PUGI_INTENSITY`) и settings.json; the REPL launch lifecycle is
+        // the natural binding point. A future `/intensity` REPL command
+        // will rebuild the bridge to swap the profile mid-session.
+        const intensityLevel = resolveIntensity({});
+        const intensityProfile = profileFor(intensityLevel);
+        engineBridge = createEngineBridge({
+            config: buildRuntimeConfig({
+                apiUrl: options.apiUrl,
+                apiKey: options.apiKey,
+            }),
+            cwd: () => process.cwd(),
+            intensityProfile,
+        });
+    }
+    catch (err) {
+        if (process.env.PUGI_DEBUG === '1') {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[pugi-debug] engine bridge bootstrap failed: ${msg}\n`);
+        }
+        engineBridge = undefined;
+    }
     const session = new ReplSession({
         apiUrl: options.apiUrl,
         apiKey: options.apiKey,
         workspaceLabel: options.workspaceLabel,
         cliVersion: options.cliVersion,
         transport,
+        ...(engineBridge !== undefined ? { engineBridge } : {}),
         workspace,
+        cyberZoo,
         store,
         localSessionId: openedSessionId,
         repoSkeleton: skeleton,
@@ -86,26 +218,84 @@ export async function renderRepl(options) {
     // Kick off the connect; the Repl renders the connecting state until
     // the session pushes `connection: 'on_watch'` from the SSE onOpen.
     void session.start();
-    // α6.14.2 wave 5: paint the chafa-baked brand-pug ANSI render to
-    // stdout BEFORE Ink mounts. Ink's layout engine would mis-measure
-    // the truecolor escape sequences, so the pug must land verbatim.
-    // The flag is passed into <Repl /> so the splash component knows to
-    // skip its own hand-crafted PUG_MASCOT column — otherwise the
-    // operator sees both the chafa pug AND the ASCII fallback stacked.
-    // When skipSplash is true (operator opted out via --no-splash), we
-    // suppress the pre-print too so the boot stays silent.
+    // beta.9: drain any keystrokes that landed in stdin between the
+    // pre-Ink raw-mode claim and now. Without this, the queued bytes
+    // would feed Ink's first useInput tick as a flood of "stale"
+    // characters once the InputBox mounts - the operator would see
+    // their pre-typed input materialise in the prompt as if they had
+    // typed it after the REPL became interactive. Idempotent: no-op
+    // when stdin is not a TTY or no bytes were buffered.
+    drainBufferedStdin(process.stdin);
+    // wave 5: paint the chafa-baked brand-pug ANSI render to
+    // stdout BEFORE Ink mounts (but AFTER alt-screen enter). Ink's
+    // layout engine would mis-measure the truecolor escape sequences,
+    // so the pug must land verbatim. The flag is passed into <Repl />
+    // so the splash component knows to skip its own hand-crafted
+    // PUG_MASCOT column - otherwise the operator sees both the chafa
+    // pug AND the ASCII fallback stacked. When skipSplash is true
+    // (operator opted out via --no-splash), we suppress the pre-print
+    // too so the boot stays silent.
     const mascotPrePrinted = options.skipSplash === true ? false : printPugMascotPreInk(process.stdout);
-    const instance = render(React.createElement(Repl, {
+    // resolve the active theme ONCE at mount
+    // and wrap `<Repl />` in `<ThemeProvider>` so every Ink consumer
+    // (`<Header>`, `<DoctorTable>`, `<StyleTable>`, `<ThemeTable>`,
+    // …) picks up the same color tokens. The provider is stable for
+    // the lifetime of the REPL — operator `/theme <name>` writes to
+    // disk + appends a system line, and the next `pugi` launch re-
+    // mounts with the new slug. Re-mounting mid-session would race
+    // against Ink's raw-mode handler so we deliberately keep the
+    // session-lifetime contract instead of polling the config file.
+    const resolvedTheme = resolveTheme({
+        workspaceRoot: process.cwd(),
+        env: process.env,
+    });
+    // CEO P0 #2 : collect welcome banner data BEFORE Ink
+    // mounts so the banner paints on the first frame instead of swapping
+    // in mid-render. The collector swallows every IO error so а missing
+    // CHANGELOG / unreadable credential / malformed settings never
+    // blocks the boot.
+    let welcomeData;
+    if (options.skipSplash !== true) {
+        try {
+            welcomeData = collectWelcomeData({
+                cliVersion: options.cliVersion,
+                cwd: process.cwd(),
+            });
+        }
+        catch {
+            welcomeData = undefined;
+        }
+    }
+    const instance = render(React.createElement(ThemeProvider, { slug: resolvedTheme.slug }, React.createElement(Repl, {
         session,
         updateBanner: options.updateBanner ?? null,
         skipSplash: options.skipSplash === true,
         hideToolStream: options.hideToolStream === true,
         mascotPrePrinted,
-    }));
+        welcomeData,
+        autoInitStatus: options.autoInitStatus ?? null,
+    })), {
+        // PUGI-534 — Ink kills the process on the first raw Ctrl+C by
+        // default, which beat the InputBox useInput double-tap timer to
+        // the punch (operator reported single ^C exits the REPL). Disable
+        // Ink's built-in handler so the InputBox `lastCtrlCAt` window owns
+        // the exit gesture: first press → cancel + toast, second press
+        // within 1s → `handleExit()` → `useApp().exit()`. SIGINT handlers
+        // on the process object (sigint-guard + per-engine-task in
+        // runtime/cli.ts) still fire as defence-in-depth on the rare
+        // non-raw fallback path.
+        exitOnCtrlC: false,
+    });
+    // Make sure we leave the alt screen on abrupt exits too. Without
+    // this the operator's shell stays "frozen" on the Pugi splash.
+    process.once('exit', bootstrap.restore);
+    process.once('SIGINT', bootstrap.restore);
+    process.once('SIGTERM', bootstrap.restore);
     try {
         await instance.waitUntilExit();
     }
     finally {
+        bootstrap.restore();
         session.close();
         if (store) {
             try {
@@ -125,6 +315,138 @@ export async function renderRepl(options) {
         }
     }
 }
+export function claimTerminalForRepl(stdin = process.stdin, stdout = process.stdout) {
+    const isStdoutTty = stdout.isTTY === true;
+    const isStdinTty = stdin.isTTY === true && typeof stdin.setRawMode === 'function';
+    let altScreenEntered = false;
+    if (isStdoutTty) {
+        try {
+            stdout.write('\x1b[?1049h');
+            stdout.write('\x1b[H');
+            altScreenEntered = true;
+        }
+        catch {
+            /* terminal already detached */
+        }
+    }
+    let rawModeClaimed = false;
+    if (isStdinTty) {
+        try {
+            stdin.setEncoding('utf8');
+            stdin.setRawMode(true);
+            // Resume so the kernel actually delivers bytes to Node's event
+            // loop. Without resume, raw mode is set but data does not flow
+            // until something else (e.g. Ink) attaches a 'data' listener.
+            stdin.resume();
+            rawModeClaimed = true;
+        }
+        catch {
+            /* raw mode unsupported - the operator's shell still works */
+        }
+    }
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        if (rawModeClaimed && isStdinTty) {
+            try {
+                stdin.setRawMode(false);
+            }
+            catch {
+                /* terminal already detached */
+            }
+        }
+        if (altScreenEntered) {
+            try {
+                stdout.write('\x1b[?1049l');
+            }
+            catch {
+                /* shutdown race - terminal already detached */
+            }
+        }
+    };
+    return { altScreenEntered, rawModeClaimed, restore };
+}
+/**
+ * Read and discard any bytes buffered in stdin between
+ * `claimTerminalForRepl()` and the Ink mount. Returns the number of
+ * bytes drained so tests can assert the behaviour without intercepting
+ * the side effect.
+ *
+ * `stdin.read()` is a no-op when no data is buffered, so this is safe
+ * to call whether or not the operator actually typed during bootstrap.
+ * Wrapped in try/catch because a closed / piped stdin will throw on
+ * read in some Node versions.
+ */
+export function drainBufferedStdin(stdin = process.stdin) {
+    if (stdin.isTTY !== true)
+        return 0;
+    try {
+        let bytesDrained = 0;
+        // Loop until read() returns null - readable streams may chunk
+        // buffered bytes across multiple read() calls when the operator
+        // typed faster than the kernel could deliver to Node's loop.
+        for (;;) {
+            const chunk = stdin.read();
+            if (chunk === null)
+                return bytesDrained;
+            bytesDrained += typeof chunk === 'string' ? chunk.length : chunk.byteLength;
+        }
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Project-root probe — beta.13 P2 fix.
+ *
+ * Beta.13 auto-init was unconditional and silently created `.pugi/` in
+ * every cwd the REPL was launched from, including `$HOME` and `/tmp`.
+ * Operators who ran `pugi` to ask a quick question outside of any
+ * project ended up with stray `.pugi/` directories polluting their
+ * filesystem. The gate looks for any of six project-root markers
+ * before scaffolding:
+ *
+ *  - `package.json`    — JS / TS workspaces
+ *  - `.git`            — any cloned repo regardless of language
+ *  - `.pugi`           — already-bound Pugi workspace (re-scaffold
+ *                         fills any missing artifacts the operator
+ *                         deleted, idempotent over existing files)
+ *  - `Cargo.toml`      — Rust crates
+ *  - `pyproject.toml`  — Python projects (PEP 518)
+ *  - `go.mod`          — Go modules
+ *
+ * The probe is six cheap `existsSync` calls; the cost is negligible
+ * compared with the alt-screen + Ink mount that follows. Exported so a
+ * future unit spec can lock the contract.
+ */
+export function isProjectRoot(cwd) {
+    // ESM static imports — `require()` is not defined in a `"type": "module"`
+    // bundle and would throw `ReferenceError: require is not defined` the
+    // moment the REPL bootstrap calls this gate. Beta.16 P0 fix.
+    return (existsSync(resolve(cwd, 'package.json')) ||
+        existsSync(resolve(cwd, '.git')) ||
+        existsSync(resolve(cwd, '.pugi')) ||
+        existsSync(resolve(cwd, 'Cargo.toml')) ||
+        existsSync(resolve(cwd, 'pyproject.toml')) ||
+        existsSync(resolve(cwd, 'go.mod')));
+}
+/**
+ * Read the operator's cyber-zoo posture from `.pugi/settings.json`.
+ * Best-effort: when the file is missing / malformed, fall through to
+ * the historical 'on' default so the REPL never refuses to launch on
+ * a settings error. Beta.13 P1 fix.
+ */
+function readCyberZooSetting(cwd) {
+    try {
+        const settings = loadSettings(cwd);
+        return settings.ui?.cyberZoo ?? 'on';
+    }
+    catch {
+        return 'on';
+    }
+}
 /**
  * Open the local SessionStore for the REPL bootstrap. Returns
  * `{ store: null, openedSessionId: undefined }` on any error so the
@@ -162,11 +484,11 @@ async function openLocalStore(input) {
     }
 }
 /**
- * Bootstrap the α6.5 three-tier context primitives:
+ * Bootstrap the three-tier context primitives:
  *
- *   - Tier 0: `RepoSkeleton` (~5KB ASCII tree + meta) for prompt injection.
- *   - Tier 1: `WorkingSet` LRU bounded at 50 entries.
- *   - Filewatch: chokidar started against cwd, ignore-filtered.
+ *  - Tier 0: `RepoSkeleton` (~5KB ASCII tree + meta) for prompt injection.
+ *  - Tier 1: `WorkingSet` LRU bounded at 50 entries.
+ *  - Filewatch: chokidar started against cwd, ignore-filtered.
  *
  * The bootstrap is fail-safe: every primitive is wrapped so the REPL
  * still launches when (e.g.) chokidar refuses to start on a
@@ -214,15 +536,22 @@ async function bootstrapContext(input) {
     return { skeleton, workingSet, watcher };
 }
 /* ------------------------------------------------------------------ */
-/* Production transport                                               */
+/* Production transport                                              */
 /* ------------------------------------------------------------------ */
-function createProductionTransport() {
+export function createProductionTransport() {
     return {
-        async createSession({ apiUrl, apiKey, workspace }) {
+        async createSession({ apiUrl, apiKey, workspace, cyberZoo }) {
             // Forward the workspace bundle in the POST body so admin-api can
-            // surface `<workspace-context>` in Mira's prompt. Older admin-api
+            // surface `<workspace-context>` in Pugi's prompt. Older admin-api
             // builds ignore unknown fields, so this stays forward-compatible.
-            // Wave 4 fix 2026-05-25.
+            // fix.
+            //
+            // Beta.13 P1 fix: also forward `cyberZoo` so admin-api
+            // can render Pugi's `<cyber-zoo>` marker matching the operator's
+            // `.pugi/settings.json::ui.cyberZoo` toggle instead of the
+            // historical 'on' default. Only included on the wire when set
+            // explicitly so a missing setting still survives older admin-api
+            // builds that do not declare the DTO field.
             const body = {};
             if (workspace?.workspaceCwd)
                 body.workspaceCwd = workspace.workspaceCwd;
@@ -230,6 +559,8 @@ function createProductionTransport() {
                 body.workspaceSlug = workspace.workspaceSlug;
             if (workspace?.workspaceSummary)
                 body.workspaceSummary = workspace.workspaceSummary;
+            if (cyberZoo === 'on' || cyberZoo === 'off')
+                body.cyberZoo = cyberZoo;
             const response = await fetch(joinUrl(apiUrl, '/api/pugi/sessions'), {
                 method: 'POST',
                 headers: jsonHeaders(apiKey),
@@ -275,6 +606,31 @@ function createProductionTransport() {
             if (lastEventId) {
                 headers['Last-Event-ID'] = lastEventId;
             }
+            // beta.9 CEO dogfood: hard timeout on the SSE
+            // handshake so a CDN/proxy that buffers the response (or an
+            // admin-api that accepted the route but never flushed headers)
+            // cannot freeze the REPL in `connecting` forever. The 5s budget
+            // is generous - admin-api routinely responds in <500ms when
+            // healthy - but tight enough that an operator who launched
+            // `pugi` and is staring at the screen will see the status flip
+            // to `reconnecting` instead of an indefinite hang. The
+            // AbortController bound to the fetch aborts the in-flight
+            // request when the timer fires, which surfaces as an
+            // `AbortError` and routes through the existing onError handler
+            // (which calls scheduleReconnect via the session). The timer
+            // is cleared the moment onOpen fires so a slow-but-eventually-
+            // successful handshake still works.
+            const handshakeDeadlineMs = 5_000;
+            const handshakeTimer = setTimeout(() => {
+                controller.abort();
+                // onError is called from the catch block below (the abort
+                // synthesises an AbortError that consumeSseStream / fetch
+                // will throw). No explicit onError call here - we let the
+                // catch path normalise the error message so the operator
+                // sees the consistent "SSE handshake timed out (5s)" prose
+                // through the same plumbing that surfaces every other
+                // transport failure.
+            }, handshakeDeadlineMs);
             void (async () => {
                 try {
                     const response = await fetch(url, {
@@ -288,6 +644,9 @@ function createProductionTransport() {
                     if (!response.body) {
                         throw new Error('SSE response has no body');
                     }
+                    // Handshake survived; cancel the deadline so a slow
+                    // first-event stream does not get aborted later.
+                    clearTimeout(handshakeTimer);
                     onOpen();
                     await consumeSseStream(response.body, onEvent);
                     // Server closed the stream cleanly. Treat as an error so
@@ -297,19 +656,33 @@ function createProductionTransport() {
                     onError(new Error('SSE stream ended'));
                 }
                 catch (error) {
-                    if (controller.signal.aborted)
+                    clearTimeout(handshakeTimer);
+                    if (controller.signal.aborted) {
+                        // Distinguish operator-driven close (session.close())
+                        // from the handshake-deadline abort. The session sets a
+                        // `closed` flag before calling controller.abort(); the
+                        // handshake-deadline abort fires while the session is
+                        // still expecting onOpen. We cannot read session state
+                        // from here, so we surface a single error class with a
+                        // clear message - the session-side onError handler
+                        // already short-circuits when `closed=true`.
+                        onError(new Error(`SSE handshake timed out after ${handshakeDeadlineMs}ms`));
                         return;
+                    }
                     onError(error instanceof Error ? error : new Error(String(error)));
                 }
             })();
             return {
-                close: () => controller.abort(),
+                close: () => {
+                    clearTimeout(handshakeTimer);
+                    controller.abort();
+                },
             };
         },
     };
 }
 /* ------------------------------------------------------------------ */
-/* SSE parser                                                         */
+/* SSE parser                                                        */
 /* ------------------------------------------------------------------ */
 /**
  * Minimal SSE parser. Reads a UTF-8 stream of `id:` / `event:` / `data:`
@@ -373,7 +746,7 @@ async function consumeSseStream(body, onEvent) {
     }
 }
 /* ------------------------------------------------------------------ */
-/* Small helpers                                                      */
+/* Small helpers                                                     */
 /* ------------------------------------------------------------------ */
 function jsonHeaders(apiKey) {
     return {

package/dist/tui/repl-splash-art.js

@@ -1,9 +1,9 @@
 /**
- * ASCII pug mascot for the REPL boot splash (α6.14 wave 3).
+ * ASCII pug mascot for the REPL boot splash .
  *
  * Hand-crafted at 9 rows × 20 columns to read as a pug at a single
  * glance — references the cyber-zoo hero glyph in
- * `apps/clawhost-web/public/brand/hero-pug.png`: blocky pug face with
+ * `apps/console-web/public/brand/hero-pug.png`: blocky pug face with
  * angular ear flaps on either side of the head, forehead crease,
  * angular cyan eyes (`◉`), smushed snout, undershot jaw, and a small
  * cyan circuit chip (`▐■▌`) on the lower-right cheek.
@@ -15,30 +15,30 @@
  * columns cyan (#3DA9FC, brandbook §05).
  *
  * Convention:
- *   - PUG_MASCOT[i]            = one row of the silhouette
- *   - PUG_MASCOT_CYAN_MASK[i]  = parallel boolean array, true => that
- *                                column renders cyan instead of gray
+ *  - PUG_MASCOT[i]           = one row of the silhouette
+ *  - PUG_MASCOT_CYAN_MASK[i] = parallel boolean array, true => that
+ *                               column renders cyan instead of gray
  *
  * Both arrays MUST stay the same length and each mask row MUST be the
  * same length as the corresponding art row. A unit test enforces this.
  */
 /* eslint-disable no-irregular-whitespace */
 export const PUG_MASCOT = [
-    '   ▄▀▀▀▄▄▄▀▀▀▄    ',
-    '  █▄▄       ▄▄█   ',
-    '  █  ▀▄▄▄▄▄▀  █   ',
-    '  █  ◉     ◉  █   ',
-    '   ▀▄  ▀█▀  ▄▀    ',
-    '     █▀▀▀▀▀█      ',
-    '     █▒▒▒▒▒█ ▐■▌  ',
-    '      ▀▄▄▄▀       ',
-    '        ▀         ',
+    '  ▄▀▀▀▄▄▄▀▀▀▄   ',
+    ' █▄▄      ▄▄█  ',
+    ' █ ▀▄▄▄▄▄▀ █  ',
+    ' █ ◉    ◉ █  ',
+    '  ▀▄ ▀█▀ ▄▀   ',
+    '    █▀▀▀▀▀█     ',
+    '    █▒▒▒▒▒█ ▐■▌ ',
+    '     ▀▄▄▄▀      ',
+    '       ▀        ',
 ];
 /**
  * Cyan accents are derived from the source characters so the art file
  * stays the single source of truth. Two glyph classes get colored:
- *   - `◉`     -> the two cyan eyes on row 3
- *   - `▐■▌`   -> the cyan chip cluster on row 6 (right cheek)
+ *  - `◉`    -> the two cyan eyes on row 3
+ *  - `▐■▌`  -> the cyan chip cluster on row 6 (right cheek)
  *
  * Everything else renders gray. The derivation runs at module load,
  * which keeps the mask trivially auditable from the source array.