@nimbus-sh/core 0.1.0

package/dist/runtime/process-table.d.ts

@@ -0,0 +1,101 @@
+import { type VfsCred } from './os-contracts.js';
+/**
+ * ProcessTable — PID allocation and process lifecycle state.
+ *
+ * Each `node script.js` invocation gets a PID. The supervisor uses this
+ * to route signals (kill) and track running processes. Owned by
+ * SessionProcessSupervisor; callers go through that facade.
+ */
+export type ProcessState = 'running' | 'exited' | 'killed';
+export interface ProcessEntry {
+    pid: number;
+    command: string;
+    argv: string[];
+    cwd: string;
+    state: ProcessState;
+    exitCode: number | null;
+    startTime: number;
+    endTime: number | null;
+    cred: VfsCred;
+    /** Spawning process, when the spawn declared one. Roots have none. */
+    parentPid?: number;
+    /** Explicit long-running flag set when a command is handed to a
+     *  long-lived Worker Loader or shell execution path. */
+    longRunning?: boolean;
+    /** Output is owned by a process-terminal attachment, not the parent shell. */
+    attachedTty?: boolean;
+}
+export interface ProcessTableSpawnOptions {
+    cred?: VfsCred;
+    parentPid?: number;
+}
+/**
+ * Pid-space stride per DO instance generation. Pids are allocated as
+ * `generation * PID_GEN_STRIDE + seq`, so pid-keyed state that OUTLIVES an
+ * instance reset — hibernatable process-terminal WebSocket attachments,
+ * persisted w9_proc_logs rows, named Worker Loader isolate keys, and
+ * still-running facets from the previous instance — can never collide with
+ * (or bleed into) a pid allocated by the next instance. A pid at or below
+ * the current base is by construction from a PREVIOUS generation.
+ */
+export declare const PID_GEN_STRIDE = 1000000;
+export declare class ProcessTable {
+    private nextPid;
+    private base;
+    private processes;
+    /**
+     * Move the pid space onto this instance generation's range. Called once at
+     * DO boot (before any event runs) with `isolateGen * PID_GEN_STRIDE`.
+     * Monotonic and idempotent — never moves pids backwards.
+     */
+    setPidBase(base: number): void;
+    /** The current generation's pid floor: pids <= base are prior-generation. */
+    get pidBase(): number;
+    /** Allocate a PID and register a new process. */
+    spawn(command: string, argv: string[], cwd: string, options?: ProcessTableSpawnOptions): ProcessEntry;
+    credOf(pid: number): VfsCred;
+    cred(pid: number): VfsCred;
+    setUmask(pid: number, umask: number): number;
+    /** child-process isolation: mark an existing entry as long-running. Idempotent. */
+    setLongRunning(pid: number): void;
+    /** Mark an existing entry as an attached terminal process. Idempotent. */
+    setAttachedTty(pid: number): void;
+    /**
+     * Mark a process as exited.
+     *
+     * Once a process reaches a terminal state (`killed` or `exited`),
+     * subsequent exit() calls
+     * are no-ops — the first terminal state wins.
+     *
+     * Without this guard, a `kill <pid>` (which sets state='killed',
+     * exitCode=137) followed by the facet's own crash-catch (which calls
+     * exit(pid, 1)) clobbers the kill signal with an exited/1 reading.
+     * `ps` then disagrees with the ring-buffer footer that still says
+     * "[process killed: killed]".
+     */
+    exit(pid: number, exitCode: number): void;
+    /** Mark a process as killed. */
+    kill(pid: number): boolean;
+    get(pid: number): ProcessEntry | undefined;
+    getRunning(): ProcessEntry[];
+    getAll(): ProcessEntry[];
+    /**
+     * Every process spawned under `pid`, transitively, oldest first.
+     *
+     * Output attribution needs this: a command's console output can land in a
+     * child's log ring (an npm bin, a facet-backed runtime) rather than on the
+     * caller's streams, and a start-time window is not a safe substitute when
+     * several commands run concurrently in one session.
+     */
+    descendantsOf(pid: number): ProcessEntry[];
+    /** Clean up exited processes older than maxAge ms. */
+    reap(maxAge?: number): number;
+    get stats(): {
+        total: number;
+        running: number;
+        exited: number;
+        killed: number;
+        nextPid: number;
+    };
+}
+//# sourceMappingURL=process-table.d.ts.map

package/dist/runtime/process-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-table.d.ts","sourceRoot":"","sources":["../../src/runtime/process-table.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;4DACwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,UAAY,CAAC;AAExC,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,SAAS,CAAmC;IAEpD;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM9B,6EAA6E;IAC7E,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,iDAAiD;IACjD,KAAK,CACH,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,wBAA6B,GACrC,YAAY;IAqBf,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI1B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAW5C,mFAAmF;IACnF,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKjC,0EAA0E;IAC1E,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKjC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IASzC,gCAAgC;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAS1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI1C,UAAU,IAAI,YAAY,EAAE;IAI5B,MAAM,IAAI,YAAY,EAAE;IAIxB;;;;;;;OAOG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE;IAY1C,sDAAsD;IACtD,IAAI,CAAC,MAAM,SAAS,GAAG,MAAM;IAY7B,IAAI,KAAK;;;;;;MASR;CACF"}

package/dist/runtime/process-table.js

@@ -0,0 +1,175 @@
+import { CRED_SESSION_USER } from './os-contracts.js';
+function immutableCred(cred) {
+    return Object.freeze({
+        uid: cred.uid,
+        gid: cred.gid,
+        groups: Object.freeze([...cred.groups]),
+        umask: cred.umask,
+    });
+}
+/**
+ * Pid-space stride per DO instance generation. Pids are allocated as
+ * `generation * PID_GEN_STRIDE + seq`, so pid-keyed state that OUTLIVES an
+ * instance reset — hibernatable process-terminal WebSocket attachments,
+ * persisted w9_proc_logs rows, named Worker Loader isolate keys, and
+ * still-running facets from the previous instance — can never collide with
+ * (or bleed into) a pid allocated by the next instance. A pid at or below
+ * the current base is by construction from a PREVIOUS generation.
+ */
+export const PID_GEN_STRIDE = 1_000_000;
+export class ProcessTable {
+    nextPid = 1;
+    base = 0;
+    processes = new Map();
+    /**
+     * Move the pid space onto this instance generation's range. Called once at
+     * DO boot (before any event runs) with `isolateGen * PID_GEN_STRIDE`.
+     * Monotonic and idempotent — never moves pids backwards.
+     */
+    setPidBase(base) {
+        if (!Number.isFinite(base) || base <= this.base)
+            return;
+        this.base = base;
+        this.nextPid = Math.max(this.nextPid, base + 1);
+    }
+    /** The current generation's pid floor: pids <= base are prior-generation. */
+    get pidBase() {
+        return this.base;
+    }
+    /** Allocate a PID and register a new process. */
+    spawn(command, argv, cwd, options = {}) {
+        const inheritedCred = options.parentPid === undefined
+            ? CRED_SESSION_USER
+            : this.credOf(options.parentPid);
+        const pid = this.nextPid++;
+        const entry = {
+            pid,
+            command,
+            argv,
+            cwd,
+            state: 'running',
+            exitCode: null,
+            startTime: Date.now(),
+            endTime: null,
+            cred: immutableCred(options.cred ?? inheritedCred),
+            parentPid: options.parentPid,
+        };
+        this.processes.set(pid, entry);
+        return entry;
+    }
+    credOf(pid) {
+        const entry = this.processes.get(pid);
+        if (!entry)
+            throw new Error(`process pid ${pid} does not exist`);
+        return immutableCred(entry.cred);
+    }
+    cred(pid) {
+        return this.credOf(pid);
+    }
+    setUmask(pid, umask) {
+        const entry = this.processes.get(pid);
+        if (!entry)
+            throw new Error(`process pid ${pid} does not exist`);
+        if (!Number.isInteger(umask) || umask < 0 || umask > 0o777) {
+            throw new Error(`invalid umask ${umask}`);
+        }
+        const previous = entry.cred.umask;
+        entry.cred = immutableCred({ ...entry.cred, umask });
+        return previous;
+    }
+    /** child-process isolation: mark an existing entry as long-running. Idempotent. */
+    setLongRunning(pid) {
+        const entry = this.processes.get(pid);
+        if (entry)
+            entry.longRunning = true;
+    }
+    /** Mark an existing entry as an attached terminal process. Idempotent. */
+    setAttachedTty(pid) {
+        const entry = this.processes.get(pid);
+        if (entry)
+            entry.attachedTty = true;
+    }
+    /**
+     * Mark a process as exited.
+     *
+     * Once a process reaches a terminal state (`killed` or `exited`),
+     * subsequent exit() calls
+     * are no-ops — the first terminal state wins.
+     *
+     * Without this guard, a `kill <pid>` (which sets state='killed',
+     * exitCode=137) followed by the facet's own crash-catch (which calls
+     * exit(pid, 1)) clobbers the kill signal with an exited/1 reading.
+     * `ps` then disagrees with the ring-buffer footer that still says
+     * "[process killed: killed]".
+     */
+    exit(pid, exitCode) {
+        const entry = this.processes.get(pid);
+        if (!entry)
+            return;
+        if (entry.state !== 'running')
+            return; // first terminal state wins
+        entry.state = 'exited';
+        entry.exitCode = exitCode;
+        entry.endTime = Date.now();
+    }
+    /** Mark a process as killed. */
+    kill(pid) {
+        const entry = this.processes.get(pid);
+        if (!entry || entry.state !== 'running')
+            return false;
+        entry.state = 'killed';
+        entry.exitCode = 137; // SIGKILL
+        entry.endTime = Date.now();
+        return true;
+    }
+    get(pid) {
+        return this.processes.get(pid);
+    }
+    getRunning() {
+        return [...this.processes.values()].filter(p => p.state === 'running');
+    }
+    getAll() {
+        return [...this.processes.values()];
+    }
+    /**
+     * Every process spawned under `pid`, transitively, oldest first.
+     *
+     * Output attribution needs this: a command's console output can land in a
+     * child's log ring (an npm bin, a facet-backed runtime) rather than on the
+     * caller's streams, and a start-time window is not a safe substitute when
+     * several commands run concurrently in one session.
+     */
+    descendantsOf(pid) {
+        const found = [];
+        const frontier = new Set([pid]);
+        for (const entry of [...this.processes.values()].sort((a, b) => a.startTime - b.startTime)) {
+            if (entry.parentPid !== undefined && frontier.has(entry.parentPid)) {
+                frontier.add(entry.pid);
+                found.push(entry);
+            }
+        }
+        return found;
+    }
+    /** Clean up exited processes older than maxAge ms. */
+    reap(maxAge = 60_000) {
+        const now = Date.now();
+        let reaped = 0;
+        for (const [pid, entry] of this.processes) {
+            if (entry.state !== 'running' && entry.endTime && now - entry.endTime > maxAge) {
+                this.processes.delete(pid);
+                reaped++;
+            }
+        }
+        return reaped;
+    }
+    get stats() {
+        const all = [...this.processes.values()];
+        return {
+            total: all.length,
+            running: all.filter(p => p.state === 'running').length,
+            exited: all.filter(p => p.state === 'exited').length,
+            killed: all.filter(p => p.state === 'killed').length,
+            nextPid: this.nextPid,
+        };
+    }
+}

package/dist/runtime/project-detect.d.ts

@@ -0,0 +1,21 @@
+/**
+ * project-detect.ts — small, dependency-free project-type detectors.
+ *
+ * Lives in its own module so unit tests + diag endpoints can import the
+ * detection helpers without pulling in nimbus-session.ts (which depends
+ * on `cloudflare:workers` and won't load under Bun).
+ *
+ * Currently exports detectCloudflareWorkersProject — added in W10 as the
+ * canonical "is this a Cloudflare Workers project?" check. Future waves
+ * can add detectVite, detectNext, etc. here.
+ */
+/**
+ * W10: detect whether the project at `<root>` is a Cloudflare Workers
+ * project. Returns true if any of the standard markers are present:
+ *   - <root>/wrangler.jsonc
+ *   - <root>/wrangler.json
+ *   - <root>/wrangler.toml
+ *   - <root>/package.json with `wrangler` in deps or devDeps
+ */
+export declare function detectCloudflareWorkersProject(vfs: any, root: string): boolean;
+//# sourceMappingURL=project-detect.d.ts.map

package/dist/runtime/project-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-detect.d.ts","sourceRoot":"","sources":["../../src/runtime/project-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAqB9E"}

package/dist/runtime/project-detect.js

@@ -0,0 +1,46 @@
+/**
+ * project-detect.ts — small, dependency-free project-type detectors.
+ *
+ * Lives in its own module so unit tests + diag endpoints can import the
+ * detection helpers without pulling in nimbus-session.ts (which depends
+ * on `cloudflare:workers` and won't load under Bun).
+ *
+ * Currently exports detectCloudflareWorkersProject — added in W10 as the
+ * canonical "is this a Cloudflare Workers project?" check. Future waves
+ * can add detectVite, detectNext, etc. here.
+ */
+/**
+ * W10: detect whether the project at `<root>` is a Cloudflare Workers
+ * project. Returns true if any of the standard markers are present:
+ *   - <root>/wrangler.jsonc
+ *   - <root>/wrangler.json
+ *   - <root>/wrangler.toml
+ *   - <root>/package.json with `wrangler` in deps or devDeps
+ */
+export function detectCloudflareWorkersProject(vfs, root) {
+    const r = String(root).replace(/^\/+/, '').replace(/\/+$/, '');
+    for (const f of ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml']) {
+        try {
+            if (vfs.exists((r ? r + '/' : '') + f))
+                return true;
+        }
+        catch { }
+    }
+    try {
+        const pkgPath = (r ? r + '/' : '') + 'package.json';
+        if (vfs.exists(pkgPath)) {
+            const text = vfs.readFileString(pkgPath);
+            const pkg = JSON.parse(text);
+            if (pkg && typeof pkg === 'object') {
+                if (pkg.devDependencies && typeof pkg.devDependencies === 'object' && 'wrangler' in pkg.devDependencies)
+                    return true;
+                if (pkg.dependencies && typeof pkg.dependencies === 'object' && 'wrangler' in pkg.dependencies)
+                    return true;
+            }
+        }
+    }
+    catch {
+        // Malformed package.json or any other read error: not a CF Workers project per this signal.
+    }
+    return false;
+}

package/dist/runtime/python-server-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * python-server-adapter.ts — the bridge between a blocking-server API and a
+ * request-driven host.
+ *
+ * THIS IS NOT A WORKAROUND, AND DELETING IT BREAKS EVERY PYTHON SERVER.
+ *
+ * `socketserver.BaseServer.serve_forever()` does not return. That is fine on a
+ * machine where the process owns its own lifetime, and impossible here: a
+ * request context is torn down when its response is sent, so a program still
+ * sitting inside serve_forever when the invocation ends is a program that
+ * stops existing. The server has to be reachable AFTER the call that started
+ * it returned.
+ *
+ * Every language needs an answer to this and each one looks different enough
+ * to be mistaken for a language-specific hack. Ruby's answer is a Fiber that
+ * parks in accept and is resumed per request (ruby-runner.ts). Python's is
+ * here: serve_forever registers the server and returns immediately, the program
+ * runs to completion, and each inbound request re-enters the interpreter and
+ * dispatches one request into the registered object. The server's state lives
+ * on the Python heap between entries, which is exactly what a reactor build
+ * gives us — no suspended stack is involved, and none is needed.
+ *
+ * It is worth being explicit about what this file is NOT, because its
+ * predecessor bundled both and was deleted for it. The old python-socket-shim
+ * also reimplemented `socket` itself, because Pyodide had no working socket
+ * layer and could not block on a host promise. That half is gone for good: this
+ * interpreter has real sockets over nimbus-net.c and real OpenSSL, so
+ * connect/send/recv are the standard library's. A proof that one half is
+ * obsolete says nothing about the other.
+ */
+/** Injected into __main__ before the user's program runs. */
+export declare const PYTHON_SERVER_ADAPTER: string;
+//# sourceMappingURL=python-server-adapter.d.ts.map

package/dist/runtime/python-server-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-server-adapter.d.ts","sourceRoot":"","sources":["../../src/runtime/python-server-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,QAoGjC,CAAC"}

package/dist/runtime/python-server-adapter.js

@@ -0,0 +1,132 @@
+/**
+ * python-server-adapter.ts — the bridge between a blocking-server API and a
+ * request-driven host.
+ *
+ * THIS IS NOT A WORKAROUND, AND DELETING IT BREAKS EVERY PYTHON SERVER.
+ *
+ * `socketserver.BaseServer.serve_forever()` does not return. That is fine on a
+ * machine where the process owns its own lifetime, and impossible here: a
+ * request context is torn down when its response is sent, so a program still
+ * sitting inside serve_forever when the invocation ends is a program that
+ * stops existing. The server has to be reachable AFTER the call that started
+ * it returned.
+ *
+ * Every language needs an answer to this and each one looks different enough
+ * to be mistaken for a language-specific hack. Ruby's answer is a Fiber that
+ * parks in accept and is resumed per request (ruby-runner.ts). Python's is
+ * here: serve_forever registers the server and returns immediately, the program
+ * runs to completion, and each inbound request re-enters the interpreter and
+ * dispatches one request into the registered object. The server's state lives
+ * on the Python heap between entries, which is exactly what a reactor build
+ * gives us — no suspended stack is involved, and none is needed.
+ *
+ * It is worth being explicit about what this file is NOT, because its
+ * predecessor bundled both and was deleted for it. The old python-socket-shim
+ * also reimplemented `socket` itself, because Pyodide had no working socket
+ * layer and could not block on a host promise. That half is gone for good: this
+ * interpreter has real sockets over nimbus-net.c and real OpenSSL, so
+ * connect/send/recv are the standard library's. A proof that one half is
+ * obsolete says nothing about the other.
+ */
+/** Injected into __main__ before the user's program runs. */
+export const PYTHON_SERVER_ADAPTER = String.raw `
+import sys
+
+_nimbus_servers = {}
+
+
+def _nimbus_patch_socketserver():
+    """Make serve_forever() return, and remember the server so the host can
+    drive it. Idempotent: the marker keeps a second injection from stacking
+    another wrapper on the first."""
+    try:
+        import socketserver as _socketserver
+    except Exception:
+        return
+    if getattr(_socketserver.BaseServer.serve_forever, "_nimbus_request_driven", False):
+        return
+
+    _orig_shutdown = _socketserver.BaseServer.shutdown
+
+    def _serve_forever(self, poll_interval=0.5):
+        sock = getattr(self, "socket", None)
+        if sock is not None:
+            try:
+                _nimbus_servers[int(sock.getsockname()[1])] = self
+                # The loop did not end, so the host owns this server's lifetime
+                # from here. Anything the program does on the way out of the
+                # block it started the server in is cleanup after a loop it
+                # believes returned, and must not take the listener down.
+                self._nimbus_adopted = True
+            except Exception:
+                pass
+        # Callers block on this event to know the loop has stopped. It never
+        # ran, so it is already true.
+        shut_down = getattr(self, "_BaseServer__is_shut_down", None)
+        if shut_down is not None:
+            shut_down.set()
+        return None
+
+    def _shutdown(self):
+        # The explicit "stop serving" call, and the only thing that hands the
+        # server back to the program. A later server_close() then really closes.
+        self._nimbus_adopted = False
+        return _orig_shutdown(self)
+
+    def _wrap_server_close(original):
+        def _server_close(self):
+            # python -m http.server runs its server inside a with-block, so the
+            # close arrives the instant serve_forever returns. Honouring it shut
+            # the listening socket before the first request could reach it.
+            if getattr(self, "_nimbus_adopted", False):
+                return None
+            sock = getattr(self, "socket", None)
+            if sock is not None:
+                try:
+                    _nimbus_servers.pop(int(sock.getsockname()[1]), None)
+                except Exception:
+                    pass
+            return original(self)
+        return _server_close
+
+    def _process_request_sync(self, request, client_address):
+        # ThreadingMixIn would hand the request to a thread that will never be
+        # scheduled. One request per host entry, inline.
+        try:
+            self.finish_request(request, client_address)
+            self.shutdown_request(request)
+        except Exception:
+            self.handle_error(request, client_address)
+            self.shutdown_request(request)
+
+    _serve_forever._nimbus_request_driven = True
+    _socketserver.BaseServer.serve_forever = _serve_forever
+    _socketserver.BaseServer.shutdown = _shutdown
+    # Both, because TCPServer defines its own server_close and every server
+    # anyone runs here derives from it — patching only the base class left the
+    # one that actually closes the socket untouched.
+    for _cls in (_socketserver.BaseServer, _socketserver.TCPServer):
+        _cls.server_close = _wrap_server_close(_cls.__dict__["server_close"])
+    try:
+        _socketserver.ThreadingMixIn.process_request = _process_request_sync
+    except Exception:
+        pass
+
+
+def _nimbus_serve_one(port):
+    """Handle exactly one queued connection. The host calls this per inbound
+    request, after the kernel has already queued the connection — so the
+    accept() inside never waits on anything."""
+    server = _nimbus_servers.get(int(port))
+    if server is None:
+        return False
+    server._handle_request_noblock()
+    return True
+
+
+def _nimbus_listening_ports():
+    return sorted(_nimbus_servers.keys())
+
+
+_nimbus_patch_socketserver()
+`;

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

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ *
+ * Static analysis still misses dynamic requires like `require(variable)`;
+ * bounded greedy oversampling in facet-manager.ts:buildPrefetchBundle
+ * compensates without limiting the statically-proven require closure.
+ *
+ * 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 { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+/**
+ * Result of a prefetch walk: path → content for every reachable file.
+ *
+ * The walk is deliberately unbounded. A facet has no synchronous I/O
+ * primitive, so `require()` cannot fetch a file it was not shipped — a
+ * budget applied here is not backpressure, it is an unrecoverable hole
+ * in the module graph. Bounds belong to the optional enrichment passes
+ * in facet-manager.ts, which have a live async read path behind them.
+ */
+export interface PrefetchResult {
+    bundle: Record<string, string>;
+}
+/** Resolve the complete dependency graph starting from entry code. */
+export declare function prefetchForRequire(vfs: CredentialedVfs, 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,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA6d5D;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAkNhB"}