@nimbus-sh/worker 0.1.0

package/dist/runtime/repl-session.d.ts

@@ -0,0 +1,160 @@
+/**
+ * repl-session.ts — substrate for interactive REPL sessions.
+ *
+ * Per /workspace/.seal-internal/2026-05-11-repl-plan/plan.md §§2-4:
+ *   Layer 1: long-lived runtime via repeated execute() into a cached
+ *            child-facet isolate (state persists on globalThis).
+ *   Layer 2: stdin routing via WebSocketTerminal.attachRepl().
+ *   Layer 3: prompt detection per-runtime — Pyodide uses sentinel-
+ *            controlled sys.ps1; Bun/Node/Ruby use per-runtime regex.
+ *
+ * This file owns the runtime-agnostic plumbing. Per-runtime adapters
+ * live in src/runtime/<name>-repl.ts and implement the ReplAdapter
+ * interface declared below.
+ */
+import type { WebSocketTerminal } from '../facets/ws-terminal.js';
+/**
+ * Per-runtime adapter contract. The shell-side ReplSession orchestrates
+ * input handling; the adapter wraps the actual runtime invocation.
+ */
+export interface ReplAdapter {
+    /** Called once when the session starts. Returns the banner to print
+     *  before the first prompt. */
+    banner(): string;
+    /** Send a complete line of user input. Returns:
+     *    - kind === 'output': normal eval result; resume reading at prompt.
+     *    - kind === 'incomplete': need more input (multi-line block).
+     *    - kind === 'exit': REPL should close with the given exit code.
+     *    - kind === 'error': error message to display; resume at prompt.
+     */
+    push(line: string): Promise<ReplPushResult>;
+    /** Called once on session close (exit() / Ctrl-D / shell teardown).
+     *  Should free any cached pool / isolate. Idempotent. */
+    close(): Promise<void>;
+    /** Primary prompt (typically '>>> '). */
+    ps1: string;
+    /** Continuation prompt (typically '... '). */
+    ps2: string;
+}
+export type ReplPushResult = {
+    kind: 'output';
+    stdout: string;
+    stderr: string;
+} | {
+    kind: 'incomplete';
+} | {
+    kind: 'exit';
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+} | {
+    kind: 'error';
+    stderr: string;
+};
+/**
+ * Manages an interactive REPL session: stdin buffering with minimal
+ * readline UX (line-mode), output routing to the WS terminal, prompt
+ * rendering, and adapter dispatch.
+ *
+ * The shell creates a ReplSession when a runtime's `startRepl` hook
+ * fires; the session installs a `replCallback` on the WebSocketTerminal
+ * (via attachRepl()) and runs until the adapter signals 'exit' or the
+ * user presses Ctrl-D on an empty line.
+ *
+ * No setTimeout in the read loop — the session is driven entirely by
+ * keystroke arrival on the WS, with awaits gating the adapter's push().
+ */
+export declare class ReplSession {
+    private adapter;
+    private terminal;
+    private detachReplCb;
+    /**
+     * REPL-R7-1 (2026-05-12): optional reference to the lifo-sh Shell.
+     *
+     * Required when the REPL is launched from a multi-line WS frame
+     * (e.g. user pastes `python\nexit(7)`). lifo-sh's input handler
+     * (node_modules/@lifo-sh/core/dist/index-Djm2onjx.js:5855
+     * `handleInput`) splits the frame on \r\n and pushes lines AFTER
+     * the first into `shell.pasteQueue`, which is drained ONLY when
+     * the shell becomes idle (after executeLine returns). While our
+     * REPL is running, those pasteQueue lines sit there waiting and
+     * the REPL itself receives no input → user sees a hung `>>> `
+     * prompt that never responds.
+     *
+     * If `shell` is provided, ReplSession will, immediately after
+     * attaching its replCallback, drain shell.pasteQueue and feed the
+     * lines into the callback (suffixed with \r each — matches what
+     * the WS frame originally would have looked like). This makes the
+     * paste path work transparently for REPL launches.
+     *
+     * The shell reference is optional so existing adapters (bun, node,
+     * ruby) that haven't been updated keep working with their
+     * pre-fix behavior.
+     */
+    private shellRef;
+    /** Current line buffer (chars typed since the last enter). */
+    private lineBuf;
+    /** Cursor position within lineBuf (0 = beginning). */
+    private cursorPos;
+    /** Accumulated lines for a multi-line block (e.g. inside def/class). */
+    private blockBuf;
+    /** True while the adapter is processing a push (block subsequent submits). */
+    private busy;
+    /** Per-session history ring (most recent first). Capped at 100. */
+    private history;
+    private historyIdx;
+    /** Resolves when close() has been called and the session ended. */
+    private closedResolve;
+    private closedPromise;
+    /** Exit code captured from adapter's last 'exit' return. */
+    private exitCode;
+    /**
+     * REPL-A1b (master plan §1 + user-evidence 2026-05-11): handleInput
+     * is invoked fire-and-forget per WS frame. Multiple WS frames arrive
+     * in quick succession during real REPL use (and during probes that
+     * send multiple lines without waiting for prompt). Without
+     * serialization, two concurrent handleInput coroutines both hit `\r`
+     * and call submitLine(); blockBuf accumulates wrong source; PyodideConsole
+     * gets `print("hi")\\nexit()` as a single 'single'-mode compile →
+     * "multiple statements found while compiling a single statement"
+     * SyntaxError.
+     *
+     * Fix: chain handleInput invocations through inputQueue. Each WS
+     * frame appends to queue; a single drain task processes the queue
+     * sequentially. submitLine's await is properly ordered relative to
+     * the next frame's chars.
+     */
+    private inputQueue;
+    private draining;
+    constructor(adapter: ReplAdapter, terminal: WebSocketTerminal, shell?: any);
+    /** Run the session: prints banner, installs the input hook, returns
+     *  a promise that resolves with the exit code when the session ends. */
+    run(): Promise<number>;
+    /**
+     * REPL-A1b: drain the input queue serially. Pulls data off
+     * inputQueue, runs handleInput, and reads any data that arrived
+     * during the await. Exits when queue is empty. Only ONE drainInput
+     * runs at a time (guarded by draining flag set in attachRepl
+     * callback).
+     */
+    private drainInput;
+    /** Process an input chunk. May contain multiple characters (paste
+     *  or rapid typing) — we iterate char-by-char to handle each
+     *  control byte individually. */
+    private handleInput;
+    /** Submit the current line buffer to the adapter. */
+    private submitLine;
+    /** Map up-arrow → previous history entry. */
+    private historyUp;
+    /** Map down-arrow → next (newer) history entry. */
+    private historyDown;
+    /** Erase the current displayed line and replace with `text`. */
+    private replaceCurrentLine;
+    /** Normalize LF → CRLF for terminal display. The WS terminal does not
+     *  do this automatically; raw \n leaves the cursor at column-0 of a
+     *  new row WITHOUT carriage return (xterm convention). */
+    private normalizeNewlines;
+    /** Close the session: detach input hook, free adapter, resolve. */
+    private endSession;
+}
+//# sourceMappingURL=repl-session.d.ts.map

package/dist/runtime/repl-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl-session.d.ts","sourceRoot":"","sources":["../../src/runtime/repl-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;mCAC+B;IAC/B,MAAM,IAAI,MAAM,CAAC;IACjB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5C;6DACyD;IACzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,YAAY,CAA6B;IACjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B,8DAA8D;IAC9D,OAAO,CAAC,OAAO,CAAc;IAC7B,sDAAsD;IACtD,OAAO,CAAC,SAAS,CAAa;IAC9B,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAgB;IAChC,8EAA8E;IAC9E,OAAO,CAAC,IAAI,CAAkB;IAC9B,mEAAmE;IACnE,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAc;IAChC,mEAAmE;IACnE,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,aAAa,CAAgB;IACrC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAa;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,GAAG;IAU1E;4EACwE;IAClE,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC;IAyD5B;;;;;;OAMG;YACW,UAAU;IASxB;;qCAEiC;YACnB,WAAW;IA6EzB,qDAAqD;YACvC,UAAU;IA8ExB,6CAA6C;IAC7C,OAAO,CAAC,SAAS;IAMjB,mDAAmD;IACnD,OAAO,CAAC,WAAW;IAUnB,gEAAgE;IAChE,OAAO,CAAC,kBAAkB;IAW1B;;8DAE0D;IAC1D,OAAO,CAAC,iBAAiB;IAIzB,mEAAmE;YACrD,UAAU;CAYzB"}

package/dist/runtime/repl-session.js

@@ -0,0 +1,393 @@
+/**
+ * repl-session.ts — substrate for interactive REPL sessions.
+ *
+ * Per /workspace/.seal-internal/2026-05-11-repl-plan/plan.md §§2-4:
+ *   Layer 1: long-lived runtime via repeated execute() into a cached
+ *            child-facet isolate (state persists on globalThis).
+ *   Layer 2: stdin routing via WebSocketTerminal.attachRepl().
+ *   Layer 3: prompt detection per-runtime — Pyodide uses sentinel-
+ *            controlled sys.ps1; Bun/Node/Ruby use per-runtime regex.
+ *
+ * This file owns the runtime-agnostic plumbing. Per-runtime adapters
+ * live in src/runtime/<name>-repl.ts and implement the ReplAdapter
+ * interface declared below.
+ */
+/**
+ * Manages an interactive REPL session: stdin buffering with minimal
+ * readline UX (line-mode), output routing to the WS terminal, prompt
+ * rendering, and adapter dispatch.
+ *
+ * The shell creates a ReplSession when a runtime's `startRepl` hook
+ * fires; the session installs a `replCallback` on the WebSocketTerminal
+ * (via attachRepl()) and runs until the adapter signals 'exit' or the
+ * user presses Ctrl-D on an empty line.
+ *
+ * No setTimeout in the read loop — the session is driven entirely by
+ * keystroke arrival on the WS, with awaits gating the adapter's push().
+ */
+export class ReplSession {
+    adapter;
+    terminal;
+    detachReplCb = null;
+    /**
+     * REPL-R7-1 (2026-05-12): optional reference to the lifo-sh Shell.
+     *
+     * Required when the REPL is launched from a multi-line WS frame
+     * (e.g. user pastes `python\nexit(7)`). lifo-sh's input handler
+     * (node_modules/@lifo-sh/core/dist/index-Djm2onjx.js:5855
+     * `handleInput`) splits the frame on \r\n and pushes lines AFTER
+     * the first into `shell.pasteQueue`, which is drained ONLY when
+     * the shell becomes idle (after executeLine returns). While our
+     * REPL is running, those pasteQueue lines sit there waiting and
+     * the REPL itself receives no input → user sees a hung `>>> `
+     * prompt that never responds.
+     *
+     * If `shell` is provided, ReplSession will, immediately after
+     * attaching its replCallback, drain shell.pasteQueue and feed the
+     * lines into the callback (suffixed with \r each — matches what
+     * the WS frame originally would have looked like). This makes the
+     * paste path work transparently for REPL launches.
+     *
+     * The shell reference is optional so existing adapters (bun, node,
+     * ruby) that haven't been updated keep working with their
+     * pre-fix behavior.
+     */
+    shellRef = null;
+    /** Current line buffer (chars typed since the last enter). */
+    lineBuf = '';
+    /** Cursor position within lineBuf (0 = beginning). */
+    cursorPos = 0;
+    /** Accumulated lines for a multi-line block (e.g. inside def/class). */
+    blockBuf = [];
+    /** True while the adapter is processing a push (block subsequent submits). */
+    busy = false;
+    /** Per-session history ring (most recent first). Capped at 100. */
+    history = [];
+    historyIdx = -1;
+    /** Resolves when close() has been called and the session ended. */
+    closedResolve = null;
+    closedPromise;
+    /** Exit code captured from adapter's last 'exit' return. */
+    exitCode = 0;
+    /**
+     * REPL-A1b (master plan §1 + user-evidence 2026-05-11): handleInput
+     * is invoked fire-and-forget per WS frame. Multiple WS frames arrive
+     * in quick succession during real REPL use (and during probes that
+     * send multiple lines without waiting for prompt). Without
+     * serialization, two concurrent handleInput coroutines both hit `\r`
+     * and call submitLine(); blockBuf accumulates wrong source; PyodideConsole
+     * gets `print("hi")\\nexit()` as a single 'single'-mode compile →
+     * "multiple statements found while compiling a single statement"
+     * SyntaxError.
+     *
+     * Fix: chain handleInput invocations through inputQueue. Each WS
+     * frame appends to queue; a single drain task processes the queue
+     * sequentially. submitLine's await is properly ordered relative to
+     * the next frame's chars.
+     */
+    inputQueue = '';
+    draining = false;
+    constructor(adapter, terminal, shell) {
+        this.adapter = adapter;
+        this.terminal = terminal;
+        // REPL-R7-1: optional shell reference for pasteQueue drain.
+        this.shellRef = shell ?? null;
+        this.closedPromise = new Promise((resolve) => {
+            this.closedResolve = resolve;
+        });
+    }
+    /** Run the session: prints banner, installs the input hook, returns
+     *  a promise that resolves with the exit code when the session ends. */
+    async run() {
+        // 1. Print banner from adapter.
+        const banner = this.adapter.banner();
+        if (banner)
+            this.terminal.write(banner);
+        if (banner && !banner.endsWith('\n'))
+            this.terminal.write('\r\n');
+        // 2. Print primary prompt.
+        this.terminal.write(this.adapter.ps1);
+        // 3. Install the input handler.
+        // REPL-A1b: per-frame data appended to inputQueue; single drain
+        // task ensures serial processing across multiple WS frames.
+        this.detachReplCb = this.terminal.attachRepl((data) => {
+            this.inputQueue += data;
+            if (!this.draining) {
+                this.draining = true;
+                void this.drainInput();
+            }
+        });
+        // REPL-R7-1: drain any input that the shell received in the SAME
+        // WS frame as the REPL-launching command (`python\nexit(7)` style
+        // pastes). Without this drain, those lines sit forever in
+        // shell.pasteQueue while the REPL hangs at `>>> `.
+        //
+        // Each pasteQueue entry is a single line (no \r/\n). We re-frame
+        // each into the replCallback as `line + \r` so handleInput
+        // processes it through the normal Enter-triggered submitLine
+        // path — same behavior as if the user had typed and pressed
+        // Enter for each line.
+        //
+        // Best-effort: if shellRef is null or pasteQueue is missing,
+        // skip silently. Mutate the queue (shift) so the shell doesn't
+        // try to re-process the same items when it drains its own queue
+        // after this REPL exits.
+        if (this.shellRef && Array.isArray(this.shellRef.pasteQueue)) {
+            const pq = this.shellRef.pasteQueue;
+            if (pq.length > 0) {
+                const drained = pq.splice(0).filter(line => line !== undefined && line !== null);
+                if (drained.length > 0) {
+                    // Feed via inputQueue + draining (same path as a real WS
+                    // frame). Each line ends with \r so handleInput's
+                    // submitLine fires per line.
+                    this.inputQueue += drained.join('\r') + '\r';
+                    if (!this.draining) {
+                        this.draining = true;
+                        void this.drainInput();
+                    }
+                }
+            }
+        }
+        // 4. Wait until close() is called.
+        await this.closedPromise;
+        return this.exitCode;
+    }
+    /**
+     * REPL-A1b: drain the input queue serially. Pulls data off
+     * inputQueue, runs handleInput, and reads any data that arrived
+     * during the await. Exits when queue is empty. Only ONE drainInput
+     * runs at a time (guarded by draining flag set in attachRepl
+     * callback).
+     */
+    async drainInput() {
+        while (this.inputQueue.length > 0) {
+            const chunk = this.inputQueue;
+            this.inputQueue = '';
+            await this.handleInput(chunk);
+        }
+        this.draining = false;
+    }
+    /** Process an input chunk. May contain multiple characters (paste
+     *  or rapid typing) — we iterate char-by-char to handle each
+     *  control byte individually. */
+    async handleInput(data) {
+        for (let i = 0; i < data.length; i++) {
+            const ch = data[i];
+            // CTRL-D (0x04): on empty line, close cleanly.
+            if (ch === '\x04') {
+                if (this.lineBuf.length === 0 && this.blockBuf.length === 0 && !this.busy) {
+                    this.terminal.write('\r\n');
+                    await this.endSession(0);
+                    return;
+                }
+                // Non-empty line: ignore (matches CPython REPL behavior).
+                continue;
+            }
+            // CTRL-C (0x03): cancel current line / block.
+            if (ch === '\x03') {
+                if (this.busy) {
+                    // Mid-execution: we can't actually interrupt the wasm runtime
+                    // in v1 (no SIGINT plumbing). Buffer the cancel for after.
+                    // For now: just display ^C and let the runtime finish.
+                    this.terminal.write('^C\r\n');
+                    continue;
+                }
+                // Idle: discard current buffer, reset, fresh prompt.
+                this.lineBuf = '';
+                this.cursorPos = 0;
+                this.blockBuf = [];
+                this.terminal.write('\r\nKeyboardInterrupt\r\n' + this.adapter.ps1);
+                continue;
+            }
+            // Enter (\r or \n): submit the line.
+            if (ch === '\r' || ch === '\n') {
+                await this.submitLine();
+                continue;
+            }
+            // Backspace (0x7f) or DEL (\b 0x08): delete char before cursor.
+            if (ch === '\x7f' || ch === '\b') {
+                if (this.cursorPos > 0) {
+                    this.lineBuf =
+                        this.lineBuf.slice(0, this.cursorPos - 1) +
+                            this.lineBuf.slice(this.cursorPos);
+                    this.cursorPos--;
+                    // Repaint: move cursor back, write rest, clear trailing, restore.
+                    this.terminal.write('\b' + this.lineBuf.slice(this.cursorPos) + ' \b');
+                    // Cursor sits one past the rewritten chars; pull it back to position.
+                    const tail = this.lineBuf.slice(this.cursorPos).length;
+                    for (let k = 0; k < tail; k++)
+                        this.terminal.write('\b');
+                }
+                continue;
+            }
+            // ANSI escape sequence (arrow keys, etc.). Buffer the full sequence
+            // by reading ahead. v1: only handle up/down arrows for history;
+            // left/right are deferred (minimal readline = no in-line editing).
+            if (ch === '\x1b' && i + 2 < data.length && data[i + 1] === '[') {
+                const code = data[i + 2];
+                if (code === 'A') {
+                    this.historyUp();
+                    i += 2;
+                    continue;
+                }
+                if (code === 'B') {
+                    this.historyDown();
+                    i += 2;
+                    continue;
+                }
+                // C/D (left/right) and others: ignore.
+                i += 2;
+                continue;
+            }
+            // Printable char: append + echo.
+            if (ch >= ' ' && ch !== '\x7f') {
+                if (this.cursorPos === this.lineBuf.length) {
+                    this.lineBuf += ch;
+                    this.cursorPos++;
+                    this.terminal.write(ch);
+                }
+                else {
+                    // Mid-line insert (rare without left-arrow editing in v1).
+                    this.lineBuf =
+                        this.lineBuf.slice(0, this.cursorPos) + ch + this.lineBuf.slice(this.cursorPos);
+                    this.cursorPos++;
+                    this.terminal.write(ch);
+                }
+            }
+        }
+    }
+    /** Submit the current line buffer to the adapter. */
+    async submitLine() {
+        this.terminal.write('\r\n');
+        const line = this.lineBuf;
+        this.lineBuf = '';
+        this.cursorPos = 0;
+        // Record in history (skip blank and duplicate-of-most-recent).
+        if (line.length > 0 && this.history[0] !== line) {
+            this.history.unshift(line);
+            if (this.history.length > 100)
+                this.history.length = 100;
+        }
+        this.historyIdx = -1;
+        // Accumulate block lines.
+        this.blockBuf.push(line);
+        const fullSource = this.blockBuf.join('\n');
+        this.busy = true;
+        let result;
+        try {
+            result = await this.adapter.push(fullSource);
+        }
+        catch (e) {
+            result = {
+                kind: 'error',
+                stderr: `[repl] adapter threw: ${e?.message || e}\n`,
+            };
+        }
+        this.busy = false;
+        // REPL-A1 (master plan §1): emit stdout, stderr, and the next-prompt
+        // as three discrete WS frames in deterministic order. Without
+        // flushNow() between them, the 5 ms coalescer in WebSocketTerminal
+        // joins them into one `{type:'output'}` payload — probes asserting
+        // frame ordering see false-RED, and xterm renders correctly only
+        // because string-order is preserved. flushNow() guarantees both
+        // are true: bytes-in-order AND frame-boundary-after-each-stream.
+        if (result.kind === 'output') {
+            if (result.stdout) {
+                this.terminal.write(this.normalizeNewlines(result.stdout));
+                this.terminal.flushNow();
+            }
+            if (result.stderr) {
+                this.terminal.write(this.normalizeNewlines(result.stderr));
+                this.terminal.flushNow();
+            }
+            this.blockBuf = [];
+            this.terminal.write(this.adapter.ps1);
+            this.terminal.flushNow();
+            return;
+        }
+        if (result.kind === 'incomplete') {
+            this.terminal.write(this.adapter.ps2);
+            this.terminal.flushNow();
+            return;
+        }
+        if (result.kind === 'error') {
+            if (result.stderr) {
+                this.terminal.write(this.normalizeNewlines(result.stderr));
+                this.terminal.flushNow();
+            }
+            this.blockBuf = [];
+            this.terminal.write(this.adapter.ps1);
+            this.terminal.flushNow();
+            return;
+        }
+        if (result.kind === 'exit') {
+            if (result.stdout) {
+                this.terminal.write(this.normalizeNewlines(result.stdout));
+                this.terminal.flushNow();
+            }
+            if (result.stderr) {
+                this.terminal.write(this.normalizeNewlines(result.stderr));
+                this.terminal.flushNow();
+            }
+            await this.endSession(result.exitCode);
+            return;
+        }
+    }
+    /** Map up-arrow → previous history entry. */
+    historyUp() {
+        if (this.history.length === 0)
+            return;
+        if (this.historyIdx < this.history.length - 1)
+            this.historyIdx++;
+        this.replaceCurrentLine(this.history[this.historyIdx]);
+    }
+    /** Map down-arrow → next (newer) history entry. */
+    historyDown() {
+        if (this.historyIdx <= 0) {
+            this.historyIdx = -1;
+            this.replaceCurrentLine('');
+            return;
+        }
+        this.historyIdx--;
+        this.replaceCurrentLine(this.history[this.historyIdx]);
+    }
+    /** Erase the current displayed line and replace with `text`. */
+    replaceCurrentLine(text) {
+        // Erase current chars: backspace + space + backspace per char.
+        const oldLen = this.lineBuf.length;
+        for (let i = 0; i < this.cursorPos; i++)
+            this.terminal.write('\b');
+        for (let i = 0; i < oldLen; i++)
+            this.terminal.write(' ');
+        for (let i = 0; i < oldLen; i++)
+            this.terminal.write('\b');
+        this.lineBuf = text;
+        this.cursorPos = text.length;
+        this.terminal.write(text);
+    }
+    /** Normalize LF → CRLF for terminal display. The WS terminal does not
+     *  do this automatically; raw \n leaves the cursor at column-0 of a
+     *  new row WITHOUT carriage return (xterm convention). */
+    normalizeNewlines(s) {
+        return s.replace(/\r?\n/g, '\r\n');
+    }
+    /** Close the session: detach input hook, free adapter, resolve. */
+    async endSession(code) {
+        this.exitCode = code;
+        if (this.detachReplCb) {
+            try {
+                this.detachReplCb();
+            }
+            catch { /* fail-soft */ }
+            this.detachReplCb = null;
+        }
+        try {
+            await this.adapter.close();
+        }
+        catch { /* fail-soft */ }
+        if (this.closedResolve) {
+            this.closedResolve();
+            this.closedResolve = null;
+        }
+    }
+}

package/dist/runtime/require-resolver.d.ts

@@ -0,0 +1,52 @@
+/**
+ * require-resolver.ts — Server-side dependency graph resolver for Nimbus.
+ *
+ * Runs on the supervisor (which has synchronous VFS access) to trace
+ * all require() calls and build a complete file bundle reachable from
+ * the entry point. The output is consumed by `facet-manager.ts`'s
+ * `buildPrefetchBundle` (W2.6a) to ship ONLY the reachable set into
+ * the dynamic-worker module (rather than every file in node_modules
+ * up to the legacy cap).
+ *
+ * Algorithm:
+ *   1. Parse `require('xxx')` / `require("xxx")` / ``require(`xxx`)``
+ *      and `require.resolve('xxx')` calls from entry code via regex.
+ *   2. Resolve each via the SHARED `resolvePackageEntry` helper from
+ *      src/_shared/exports-resolver.ts — same impl that node-shims
+ *      and npm-resolver use, so prefetch and runtime always agree on
+ *      which file `require('xyz')` means (W2.6a D6: no dual impls).
+ *   3. Read the resolved file, recursively parse ITS requires.
+ *   4. Return Record<string, string> of path → content.
+ *
+ * Limits (sub-agent §Q1 caveats — extended regex still misses dynamic
+ * requires like `require(variable)` and ESM `import` statements; greedy
+ * oversampling in facet-manager.ts:buildPrefetchBundle compensates).
+ *
+ * History: this file was ARC-A-P1 quarantined after W2 because the
+ * legacy `buildVfsBundle` walked every file in node_modules. W2.6a
+ * de-quarantines it as the primary content-bundle source.
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/**
+ * Result of a prefetch walk.
+ *   - bundle:  path → content for every reachable file.
+ *   - visited: set of pkgDirs (e.g. 'home/user/app/node_modules/fastify')
+ *              encountered during the walk. Caller uses this to drive
+ *              greedy oversampling — every visited package gets its
+ *              package.json + main file forced into the bundle, even
+ *              if the dynamic-require they're behind wasn't caught by
+ *              the regex.
+ *   - truncated: true if MAX_FILES or MAX_BYTES fired.
+ */
+export interface PrefetchResult {
+    bundle: Record<string, string>;
+    visitedPkgDirs: Set<string>;
+    truncated: boolean;
+}
+/**
+ * Resolve the complete dependency graph starting from entry code.
+ * Returns Record<path, content> + the set of package directories
+ * referenced (for greedy oversampling).
+ */
+export declare function prefetchForRequire(vfs: SqliteVFS, entryCode: string, cwd: string, entryFile?: string): PrefetchResult;
+//# sourceMappingURL=require-resolver.d.ts.map

package/dist/runtime/require-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-resolver.d.ts","sourceRoot":"","sources":["../../src/runtime/require-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAsbtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAoOhB"}