@nimbus-sh/worker 0.1.0

package/dist/runtime/long-running-handle.js

@@ -0,0 +1,192 @@
+/**
+ * long-running-handle.ts — generic adapter (primitive #3 + #4).
+ *
+ * Goal: any long-running thing in a Nimbus session that *behaves* like
+ * an HTTP server should plug into the supervisor's port registry the
+ * same way, so:
+ *
+ *   - `ps` shows it (via `processTable.spawn` + `setLongRunning`)
+ *   - `/preview/?port=N` routes to it
+ *   - `/preview/` routes to the default-target one
+ *   - `vite stop` / `kill <pid>` tears it down
+ *
+ * Today, two "long-running things" exist in-process:
+ *
+ *   1. ViteDevServer (the built-in Cirrus shim)
+ *   2. CirrusReal (the experimental real-vite facet)
+ *
+ * Both already expose a `handleRequest(request, pathname)` method.
+ * `PortRegistry` expects facets exposing `handleHttpRequest(request)`
+ * (single-arg, full request, with the inner path baked into the URL).
+ *
+ * `makeLongRunningPortStub` adapts the (request, pathname) shape into
+ * the (request) shape, by stripping a configurable `basePath` prefix
+ * from `request.url.pathname` and forwarding the rest. It is the ONE
+ * hook every future long-running thing will use; we do not write a new
+ * adapter per framework.
+ *
+ * NOTE: this is a SUPERVISOR-LOCAL stub, NOT a `WorkerEntrypoint`
+ * RPC stub. The port-registry handler at `routeRequest` happily
+ * accepts any object exposing `handleHttpRequest`, including in-DO
+ * wrappers. That is by design — a long-running facet is NOT required
+ * to live in a separate isolate; the routing primitive is the same
+ * either way.
+ */
+/**
+ * Build a port-registry-compatible stub that forwards into the given
+ * handler.
+ *
+ * The supervisor calls `stub.handleHttpRequest(request)` with a request
+ * whose URL pathname is the path relative to the port (`PortRegistry`
+ * already strips the `/port/<n>` prefix). We pass that pathname to the
+ * underlying handler unchanged.
+ *
+ * Concretely: `GET /port/3000/api/users?id=42`
+ *   → port-registry rewrites url to `/api/users?id=42`
+ *   → stub.handleHttpRequest(req)  // req.url has /api/users?id=42
+ *   → handler.handleRequest(req, "/api/users?id=42")
+ */
+export function makeLongRunningPortStub(handler) {
+    return {
+        async handleHttpRequest(request) {
+            const url = new URL(request.url);
+            const innerPath = (url.pathname || '/') + url.search;
+            return handler.handleRequest(request, innerPath);
+        },
+    };
+}
+/**
+ * Parse `--port N`, `--port=N`, `-p N`, `-p=N` from argv. Returns the
+ * parsed integer, or null. Last-wins (so `--port 3000 --port 4000` →
+ * 4000), matching POSIX convention.
+ *
+ * Out-of-range or non-numeric values are returned as null without
+ * throwing — callers fall back to the next source (env, config, default).
+ */
+export function parsePortFromArgv(argv) {
+    let result = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        let candidate;
+        if (a === '--port' || a === '-p') {
+            candidate = argv[i + 1];
+            i++;
+        }
+        else if (a.startsWith('--port=')) {
+            candidate = a.slice('--port='.length);
+        }
+        else if (a.startsWith('-p=')) {
+            candidate = a.slice('-p='.length);
+        }
+        if (!candidate)
+            continue;
+        const n = parseInt(candidate, 10);
+        if (Number.isFinite(n) && n > 0 && n < 65536)
+            result = n;
+    }
+    return result;
+}
+/**
+ * Resolve a final port to bind to, given the various sources in
+ * priority order. Returns the first finite source.
+ *
+ *   1. argv flags (--port / -p)
+ *   2. env.PORT (post-shell-expansion; Markflow's `${PORT:-3000}` → 3000)
+ *   3. viteConfig.port (explicit `port: NNNN` in vite.config.ts)
+ *   4. fallback (caller-provided default, e.g. 5173 for vite, 3000 for express)
+ */
+export function resolveLongRunningPort(opts) {
+    const argvPort = opts.argv ? parsePortFromArgv(opts.argv) : null;
+    if (argvPort)
+        return argvPort;
+    const envPortStr = opts.env?.PORT;
+    if (envPortStr !== undefined && envPortStr !== null && envPortStr !== '') {
+        const n = parseInt(String(envPortStr), 10);
+        if (Number.isFinite(n) && n > 0 && n < 65536)
+            return n;
+    }
+    if (opts.configPort && opts.configPort > 0 && opts.configPort < 65536) {
+        return opts.configPort;
+    }
+    return opts.fallback;
+}
+/**
+ * Expand shell-style `${VAR}` and `${VAR:-default}` references in a
+ * single argv token, against the supplied env map.
+ *
+ * Nimbus's shell does not expand parameter substitution, so a
+ * package.json script line like
+ *
+ *     "dev": "vite --host 0.0.0.0 --port ${PORT:-3000}"
+ *
+ * arrives at the vite handler as the literal token `${PORT:-3000}`.
+ * Without expansion, `--port ${PORT:-3000}` is parsed as a non-numeric
+ * port and discarded. With expansion (against `env.PORT` falling back
+ * to `3000`), the user gets the port they asked for.
+ *
+ * Supports the two forms commonly seen in `package.json` scripts:
+ *
+ *   - ${VAR}             → env[VAR] || ''
+ *   - ${VAR:-default}    → env[VAR] || default
+ *   - ${VAR:-other_var}  → recursive (one level), so the default may
+ *                          itself reference an env var
+ *
+ * Does NOT support: command substitution, arithmetic substitution,
+ * pattern operators (`${VAR##pat}` etc.), positional params, glob.
+ * That is intentional — full shell semantics belong in the shell, not
+ * the argv expander; this helper covers ~95% of dev-script usage.
+ */
+export function expandShellDefaults(token, env) {
+    if (!token || token.indexOf('${') < 0)
+        return token;
+    const lookup = (name) => {
+        const v = env?.[name];
+        if (v === undefined || v === null || v === '')
+            return undefined;
+        return String(v);
+    };
+    // ${VAR:-default}, ${VAR}. One pass; default value is itself
+    // recursively expanded once.
+    return token.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, def) => {
+        const v = lookup(name);
+        if (v !== undefined)
+            return v;
+        if (def === undefined)
+            return '';
+        // One recursion level so `${PORT:-${PORT_FALLBACK:-3000}}` works.
+        if (def.indexOf('${') >= 0)
+            return expandShellDefaults(def, env);
+        return def;
+    });
+}
+/**
+ * Apply `expandShellDefaults` to every argv token. Used at the top of
+ * a long-running handler before argv parsing so flag values are
+ * fully resolved.
+ */
+export function expandArgvShellDefaults(argv, env) {
+    return argv.map((t) => expandShellDefaults(t, env));
+}
+/**
+ * Pick the default `/preview/` target when no `?port=N` is supplied
+ * AND no in-process `viteDevServer` is currently running. The strategy
+ * is "first PortRegistry entry, ordered by registration time" — so if
+ * a session has only one long-running thing (Markflow's vite on :3000),
+ * `/preview/` lands on it without the user supplying a port.
+ *
+ * Returns null if the registry is empty, in which case the caller
+ * surfaces the existing "no dev server running" placeholder.
+ */
+export function pickDefaultPreviewPort(ports) {
+    if (ports.length === 0)
+        return null;
+    // Stable order: oldest registration first. A session that legitimately
+    // runs two servers (e.g. vite + express API) should put the FRONTEND
+    // (registered first) on the default `/preview/` route; the API is
+    // accessed via `/preview/?port=8000`.
+    let oldest = ports[0];
+    for (const p of ports)
+        if (p.registeredAt < oldest.registeredAt)
+            oldest = p;
+    return oldest.port;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * node-repl.ts — Node REPL adapter.
+ *
+ * Node is native (workerd nodejs_compat). Pattern mirrors bun-repl.ts:
+ * a long-lived child-facet holds a vm.Context across submits.
+ *
+ * We do NOT use `node:repl` directly. Although workerd's nodejs_compat
+ * exposes node:repl, it expects a terminal stream interface (stdin/
+ * stdout) that the facet doesn't have — and trying to attach a
+ * Duplex stream to a Worker isolate is a bigger surgery than worth.
+ * Instead we replicate the core repl behaviours:
+ *   - `> ` primary prompt, `... ` continuation
+ *   - util.inspect of expression values (displayhook)
+ *   - SyntaxError recoverable-detection for multi-line input
+ *   - process.exit(code) propagation
+ *   - .exit / .help / .clear dotted commands
+ *
+ * NOT supported in v1 (deferred):
+ *   - REPL_MODE_STRICT switch
+ *   - Top-level await at the prompt
+ *   - Tab-completion
+ *   - History pickling
+ */
+import type { FacetManager } from '../facets/manager.js';
+import type { WebSocketTerminal } from '../facets/ws-terminal.js';
+export interface NodeReplDeps {
+    facetMgr: FacetManager;
+    terminal: WebSocketTerminal;
+}
+/**
+ * Top-level wrapper: builds a Node REPL adapter, drives a ReplSession
+ * to completion, returns the exit code. Called from the node factory's
+ * wrapper in init.ts when `node` is invoked with no args.
+ */
+export declare function runNodeRepl(deps: NodeReplDeps): Promise<number>;
+//# sourceMappingURL=node-repl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"node-repl.d.ts","sourceRoot":"","sources":["../../src/runtime/node-repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKlE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AA2RD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAIrE"}

package/dist/runtime/node-repl.js

@@ -0,0 +1,293 @@
+/**
+ * node-repl.ts — Node REPL adapter.
+ *
+ * Node is native (workerd nodejs_compat). Pattern mirrors bun-repl.ts:
+ * a long-lived child-facet holds a vm.Context across submits.
+ *
+ * We do NOT use `node:repl` directly. Although workerd's nodejs_compat
+ * exposes node:repl, it expects a terminal stream interface (stdin/
+ * stdout) that the facet doesn't have — and trying to attach a
+ * Duplex stream to a Worker isolate is a bigger surgery than worth.
+ * Instead we replicate the core repl behaviours:
+ *   - `> ` primary prompt, `... ` continuation
+ *   - util.inspect of expression values (displayhook)
+ *   - SyntaxError recoverable-detection for multi-line input
+ *   - process.exit(code) propagation
+ *   - .exit / .help / .clear dotted commands
+ *
+ * NOT supported in v1 (deferred):
+ *   - REPL_MODE_STRICT switch
+ *   - Top-level await at the prompt
+ *   - Tab-completion
+ *   - History pickling
+ */
+import { ReplSession } from './repl-session.js';
+import { NODE_VERSION } from '../constants.js';
+class NodeReplAdapter {
+    pool = null;
+    initDone = false;
+    deps;
+    ps1 = '> ';
+    ps2 = '... ';
+    constructor(deps) {
+        this.deps = deps;
+    }
+    banner() {
+        return (`Node.js ${NODE_VERSION} compatibility layer (Nimbus, over Cloudflare workerd)\r\n` +
+            'This is not Node.js itself. It is the workerd `nodejs_compat` API\r\n' +
+            "surface on top of V8. workerd's CSP blocks runtime eval/new-Function,\r\n" +
+            'so the REPL cannot persist `var`/`let`/`const` across lines.\r\n' +
+            '`console.log` and side-effect calls work per line. For stateful work,\r\n' +
+            'run a script:  `node -e "<code>"`   or   `node script.js`\r\n' +
+            'Type ".help" for more information.\r\n');
+    }
+    async push(source) {
+        const trimmed = source.trim();
+        if (trimmed === '.exit') {
+            return { kind: 'exit', exitCode: 0 };
+        }
+        if (trimmed === '.help') {
+            return {
+                kind: 'output',
+                stdout: '.exit    Exit the REPL\r\n' +
+                    '.help    Print this help\r\n' +
+                    '.clear   Reset context\r\n',
+                stderr: '',
+            };
+        }
+        if (trimmed === '.clear') {
+            this.initDone = false;
+            return { kind: 'output', stdout: 'Clearing context...\r\n', stderr: '' };
+        }
+        try {
+            await this.ensurePool();
+        }
+        catch (e) {
+            return { kind: 'error', stderr: `[node-repl] bootstrap failed: ${e?.message || e}\n` };
+        }
+        if (!this.initDone) {
+            try {
+                const initResult = await this.submitFacetFn({ mode: 'init' });
+                if (initResult.error) {
+                    return { kind: 'error', stderr: `[node-repl] init failed: ${initResult.error}\n` };
+                }
+                this.initDone = true;
+            }
+            catch (e) {
+                return { kind: 'error', stderr: `[node-repl] init dispatch failed: ${e?.message || e}\n` };
+            }
+        }
+        let result;
+        try {
+            result = await this.submitFacetFn({ mode: 'push', source });
+        }
+        catch (e) {
+            return { kind: 'error', stderr: `[node-repl] push dispatch failed: ${e?.message || e}\n` };
+        }
+        if (result.exit) {
+            return {
+                kind: 'exit',
+                exitCode: result.exitCode || 0,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            };
+        }
+        if (result.incomplete) {
+            return { kind: 'incomplete' };
+        }
+        return { kind: 'output', stdout: result.stdout || '', stderr: result.stderr || '' };
+    }
+    async close() {
+        if (this.pool) {
+            try {
+                this.pool.dispose?.();
+            }
+            catch { /* fail-soft */ }
+            this.pool = null;
+        }
+        this.initDone = false;
+    }
+    async ensurePool() {
+        if (this.pool)
+            return;
+        const { facetMgr } = this.deps;
+        const env = facetMgr.env;
+        const ctx = facetMgr.ctx;
+        const { NimbusLoaderPool } = await import('../loaders/loader-pool.js');
+        this.pool = new NimbusLoaderPool(env, ctx, {
+            tag: 'node-repl',
+            concurrency: 1,
+            omitSupervisor: true,
+            preamble: '', // node is native — no preamble shim needed
+        });
+    }
+    async submitFacetFn(args) {
+        return await this.pool.submit(nodeReplStepFacetFn, args, {
+            timeoutMs: 60_000,
+        });
+    }
+}
+/**
+ * Facet-side function. Self-contained — serialized via fn.toString()
+ * across the LOADER boundary; no closure captures, no class refs,
+ * no bare 'this' word (the serializer rejects /\bthis\b/).
+ *
+ * Modes:
+ *   - 'init': create vm.createContext(), expose curated globals,
+ *     stash on globalThis.__nimbus_node_ctx.
+ *   - 'push': try expression-mode eval; fall back to statement-mode;
+ *     util.inspect non-undefined result; surface process.exit sentinel.
+ */
+function nodeReplStepFacetFn(args) {
+    const g = globalThis;
+    return (async function () {
+        if (args.mode === 'init') {
+            // workerd's node:vm is a stub (non-functional in nodejs_compat).
+            // Use direct eval against the facet's globalThis with console
+            // overrides for output capture + process.exit sentinel.
+            // @ts-ignore — node:util via workerd nodejs_compat at runtime.
+            const utilMod = await import('node:util');
+            g.__nimbus_node_util = utilMod;
+            g.__nimbus_node_stdout = [];
+            g.__nimbus_node_stderr = [];
+            const stdoutPush = (xs) => g.__nimbus_node_stdout.push(xs.map((x) => typeof x === 'string' ? x : utilMod.inspect(x, { colors: false })).join(' ') + '\n');
+            const stderrPush = (xs) => g.__nimbus_node_stderr.push(xs.map((x) => typeof x === 'string' ? x : utilMod.inspect(x, { colors: false })).join(' ') + '\n');
+            g.__nimbus_node_orig_console = g.console;
+            g.console = {
+                log: (...xs) => stdoutPush(xs),
+                error: (...xs) => stderrPush(xs),
+                warn: (...xs) => stderrPush(xs),
+                info: (...xs) => stdoutPush(xs),
+                debug: (...xs) => stdoutPush(xs),
+            };
+            if (g.process && typeof g.process === 'object') {
+                g.__nimbus_node_orig_exit = g.process.exit;
+                g.process.exit = function (code) {
+                    const err = new Error('__nimbus_node_exit__');
+                    err.__nimbus_exit_code = typeof code === 'number' ? code : 0;
+                    throw err;
+                };
+            }
+            return { stdout: '', stderr: '' };
+        }
+        const source = args.source || '';
+        const utilMod = g.__nimbus_node_util;
+        if (!utilMod) {
+            return { stdout: '', stderr: '', error: 'node repl not initialised' };
+        }
+        const stdoutStart = g.__nimbus_node_stdout.length;
+        const stderrStart = g.__nimbus_node_stderr.length;
+        try {
+            new Function('(function(){\n' + source + '\n})');
+        }
+        catch (parseErr) {
+            const msg = parseErr?.message || '';
+            const incompletePatterns = [
+                /Unexpected end of input/i,
+                /Unterminated template literal/i,
+                /Unterminated string constant/i,
+                /missing \) after argument list/i,
+                /Unexpected token \}/i,
+            ];
+            if (incompletePatterns.some((re) => re.test(msg))) {
+                return {
+                    stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+                    stderr: g.__nimbus_node_stderr.slice(stderrStart).join(''),
+                    incomplete: true,
+                };
+            }
+        }
+        // workerd's CSP blocks eval() at request-time. `new Function` is
+        // permitted. var/let/const bindings inside the Function body don't
+        // persist on globalThis, so we use accumulate-and-replay: each push
+        // re-runs the full session history with the new line appended,
+        // returning the value of the current line's expression for
+        // displayhook.
+        if (!g.__nimbus_node_history)
+            g.__nimbus_node_history = [];
+        let result;
+        let evaluatedAs = 'stmt';
+        try {
+            const histBody = g.__nimbus_node_history.join('\n');
+            const exprFn = new Function(histBody + '\nreturn (' + source + '\n);');
+            result = exprFn.call(globalThis);
+            evaluatedAs = 'expr';
+            g.__nimbus_node_history.push(source);
+        }
+        catch (exprErr) {
+            if (exprErr && exprErr.__nimbus_exit_code !== undefined) {
+                return {
+                    stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+                    stderr: g.__nimbus_node_stderr.slice(stderrStart).join(''),
+                    exit: true,
+                    exitCode: exprErr.__nimbus_exit_code,
+                };
+            }
+            if (exprErr && /EvalError|Code generation from strings disallowed/i.test(exprErr.message || '')) {
+                return {
+                    stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+                    stderr: g.__nimbus_node_stderr.slice(stderrStart).join('') +
+                        'workerd CSP: cannot evaluate JS at request time. Use `node -e "<code>"` instead.\n',
+                };
+            }
+            try {
+                const histBody = g.__nimbus_node_history.join('\n');
+                const stmtFn = new Function(histBody + '\n' + source);
+                result = stmtFn.call(globalThis);
+                evaluatedAs = 'stmt';
+                g.__nimbus_node_history.push(source);
+            }
+            catch (stmtErr) {
+                if (stmtErr && stmtErr.__nimbus_exit_code !== undefined) {
+                    return {
+                        stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+                        stderr: g.__nimbus_node_stderr.slice(stderrStart).join(''),
+                        exit: true,
+                        exitCode: stmtErr.__nimbus_exit_code,
+                    };
+                }
+                const errStr = (stmtErr && stmtErr.stack) || String(stmtErr);
+                return {
+                    stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+                    stderr: g.__nimbus_node_stderr.slice(stderrStart).join('') + errStr + '\n',
+                };
+            }
+        }
+        if (result && typeof result.then === 'function') {
+            try {
+                result = await result;
+            }
+            catch (awaitErr) {
+                const errStr = (awaitErr && awaitErr.stack) || String(awaitErr);
+                return {
+                    stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+                    stderr: g.__nimbus_node_stderr.slice(stderrStart).join('') + errStr + '\n',
+                };
+            }
+        }
+        if (evaluatedAs === 'expr' && result !== undefined) {
+            let rendered;
+            try {
+                rendered = utilMod.inspect(result, { colors: false, depth: 4 });
+            }
+            catch (_e) {
+                rendered = '<inspect failed>';
+            }
+            g.__nimbus_node_stdout.push(rendered + '\n');
+        }
+        return {
+            stdout: g.__nimbus_node_stdout.slice(stdoutStart).join(''),
+            stderr: g.__nimbus_node_stderr.slice(stderrStart).join(''),
+        };
+    })();
+}
+/**
+ * Top-level wrapper: builds a Node REPL adapter, drives a ReplSession
+ * to completion, returns the exit code. Called from the node factory's
+ * wrapper in init.ts when `node` is invoked with no args.
+ */
+export async function runNodeRepl(deps) {
+    const adapter = new NodeReplAdapter(deps);
+    const session = new ReplSession(adapter, deps.terminal);
+    return await session.run();
+}

package/dist/runtime/node-runner.d.ts

@@ -0,0 +1,111 @@
+/**
+ * node-runner.ts — Always-fresh-isolate dispatch for `node` and `bun`.
+ *
+ * Architectural promise (post fresh-isolate-bun-behavioral wave)
+ * ─────────────────────────────────────────────────────────────
+ * Every external runtime invocation (`node script`, `node -e`,
+ * `node --version`, `bun X`, `npx X`) is dispatched into a FRESH
+ * Worker Loader isolate. There is NO content-sniffing heuristic; the
+ * only routing signal is argv flags that explicitly mean "this is
+ * supposed to be long-lived" (`--watch`, `--inspect`, `--inspect-brk`).
+ *
+ * Two execution modes
+ * ───────────────────
+ *   short — `facetMgr.exec(code, opts)`. Per-call LOADER.get(codeId)
+ *           creates a fresh isolate keyed on hash(code+bundle+manifest).
+ *           Output is streamed back via per-pid child DO Facet's
+ *           supervisor RPC (`_rpcStdout` / `_rpcStderr`); supervisor
+ *           awaits and returns the consolidated {exitCode, stdout,
+ *           stderr}. The facet is deleted at completion.
+ *
+ *   long  — `facetMgr.spawn(workerCode, command, cwd)`. Fire-and-
+ *           forget LOADER.load(). Returns {pid, facetStub} immediately;
+ *           the shell prints a `[started (long-running): pid=N
+ *           cmd=...]` notice and returns. The facet outlives the
+ *           supervisor RPC until killed or evicted.
+ *
+ * Routing
+ * ───────
+ *   args.includes('--watch' | '--inspect' | '--inspect-brk')  → long
+ *   default                                                    → short
+ *
+ * The previous `detectLongRunning(code, args)` content-regex sniff
+ * (deprecated) is removed. False-positives (a script that *imports*
+ * http but exits quickly) used to fork unnecessarily; with
+ * argv-only routing, the user gets the inline behaviour they expect
+ * unless they explicitly opted into long-running with a flag.
+ *
+ * For scripts that don't terminate but also don't carry one of the
+ * argv flags (e.g. an http.listen with no --watch), `facetMgr.exec`'s
+ * 5-minute timeout caps the worst case. The supervisor returns the
+ * timeout exit code; the facet is torn down. Documented trade-off.
+ *
+ * Anti-requirements observed
+ * ──────────────────────────
+ *   - NO setTimeout / sleep on hot paths.
+ *   - NO fallback to in-supervisor execution. facetMgr.exec /
+ *     facetMgr.spawn throw if env.LOADER is missing.
+ *   - NO content-sniffing heuristic. argv-only routing.
+ *
+ * Cold-start (measured against prod 9d30dc95):
+ *   first-run `node -e`     : 152–608 ms (warm-isolate cold case)
+ *   warm `node -e` (median) : 102 ms
+ *   warm `node script.js`   : ~50–100 ms
+ * All under the 250ms warm-pool gate; no warm-pool needed.
+ */
+import type { FacetManager } from '../facets/manager.js';
+/**
+ * Argv-only long-running detection. The ONLY signals we honour:
+ *   --watch       (node --watch / bun --watch)
+ *   --inspect     (node --inspect)
+ *   --inspect-brk (node --inspect-brk)
+ *
+ * No content sniff; no heuristic over the script source. False-positive
+ * class is gone. False-negative class is "user runs a server without
+ * --watch and the supervisor RPC blocks for 5 min" — accepted; users
+ * are guided in docs to add `--watch` for keep-alive servers OR rely
+ * on the 5-min timeout to recover.
+ */
+export declare function isLongRunningInvocation(args: string[]): boolean;
+/** Result of a `runFresh` call. */
+export interface RunFreshResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    spawnedPid?: number;
+    longRunning: boolean;
+}
+export interface RunFreshOpts {
+    argv?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    filename?: string;
+    dirname?: string;
+    /** Display label for the long-running spawn. Defaults to the
+     *  command + filename. Surfaced in the [started (long-running)]
+     *  notice + /api/processes listing. */
+    command?: string;
+    /**
+     * G4 (runtime-pkg wave): caller has already allocated a
+     * processTable PID for this invocation; runFresh / facetMgr.exec
+     * should reuse it instead of spawning a duplicate. Used by the
+     * .bin handler in src/session/init.ts to keep `ps` showing ONE
+     * row per bin invocation instead of two (the wrapper + the inner
+     * node script).
+     */
+    skipSpawn?: boolean;
+    callerPid?: number;
+}
+/**
+ * Always-fresh-isolate dispatcher. Replaces the previous
+ * `runNodeScript` content-sniff variant. Used by both `node` and
+ * `bun` shell handlers.
+ */
+export declare function runFresh(facetMgr: FacetManager, code: string, opts: RunFreshOpts): Promise<RunFreshResult>;
+/**
+ * BACKWARD-COMPAT shim. The arch-gaps wave's `runNodeScript` is now an
+ * alias for `runFresh` so the call sites in src/session/init.ts don't
+ * need to change in this commit.
+ */
+export declare const runNodeScript: typeof runFresh;
+//# sourceMappingURL=node-runner.d.ts.map

package/dist/runtime/node-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/node-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,sBAAsB,CAAC;AAG1E;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAO/D;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;2CAEuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6CD;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,CA8DzB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,iBAAW,CAAC"}