@nimbus-sh/worker 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * index.ts — Workers entrypoint.
+ *
+ * Two responsibilities, kept here because both must execute on every
+ * request before any DO dispatch:
+ *
+ *   1. Re-export the DO classes + RPC service bindings so wrangler
+ *      bundles them and `enable_ctx_exports` (compat date 2026-04-01+)
+ *      auto-populates them under ctx.exports. NimbusSession
+ *      (the Durable Object) and SupervisorRPC + the inner-Worker
+ *      binding shims (NimbusAssetsRPC, NimbusLoaderRPC,
+ *      NimbusLoadedWorker, NimbusLoadedEntrypoint,
+ *      NimbusDurableObjectNamespace, NimbusDOStub) all need to be
+ *      reachable as exports of the entrypoint module.
+ *
+ *   2. Route HTTP/WS requests to the right session via the session
+ *      ID embedded in /s/<id>/* paths. URL → DO mapping is a stable
+ *      contract delegated to {@link createNimbusHandler}.
+ *
+ * The fetch handler delegates to `createNimbusHandler({ auth: { mode:
+ * 'auto' } })` — same shape an external embedder uses via
+ * `@nimbus-sh/worker`. This file's only deploy-specific logic is the
+ * W6.5 registry-event sink installed at module-load time.
+ */
+import { NimbusSession, NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub } from './session/nimbus-session.js';
+import { SupervisorRPC } from './session/supervisor-rpc.js';
+import { CirrusHmrRPC } from './facets/real-vite-hmr.js';
+export { createNimbusHandler } from './router/index.js';
+export type { NimbusHandler, NimbusHooks, NimbusHookContext, CustomRoutes, CreateNimbusHandlerOptions, AuthMode, NimbusAuthConfig, } from './router/index.js';
+export { issueNimbusToken, verifyNimbusToken, NimbusAuthError, } from './auth/index.js';
+export type { NimbusAuthEnv, NimbusTokenClaims, VerifiedNimbusToken, } from './auth/index.js';
+export { NimbusSession, SupervisorRPC, NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, CirrusHmrRPC, };
+/**
+ * Module-level reference to ctx.exports from the fetch handler.
+ * Used by NimbusSession to create loopback bindings for facets.
+ * Set once on the first fetch() call by createNimbusHandler.
+ */
+export declare function getCtxExports(): any;
+declare const _default: import("./index.js").NimbusHandler;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,4BAA4B,EAC5B,YAAY,EACb,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAUzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,0BAA0B,EAC1B,QAAQ,EACR,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAmBzB,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,4BAA4B,EAC5B,YAAY,EACZ,YAAY,GACb,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAEnC;;AAOD,wBAAqC"}

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * index.ts — Workers entrypoint.
+ *
+ * Two responsibilities, kept here because both must execute on every
+ * request before any DO dispatch:
+ *
+ *   1. Re-export the DO classes + RPC service bindings so wrangler
+ *      bundles them and `enable_ctx_exports` (compat date 2026-04-01+)
+ *      auto-populates them under ctx.exports. NimbusSession
+ *      (the Durable Object) and SupervisorRPC + the inner-Worker
+ *      binding shims (NimbusAssetsRPC, NimbusLoaderRPC,
+ *      NimbusLoadedWorker, NimbusLoadedEntrypoint,
+ *      NimbusDurableObjectNamespace, NimbusDOStub) all need to be
+ *      reachable as exports of the entrypoint module.
+ *
+ *   2. Route HTTP/WS requests to the right session via the session
+ *      ID embedded in /s/<id>/* paths. URL → DO mapping is a stable
+ *      contract delegated to {@link createNimbusHandler}.
+ *
+ * The fetch handler delegates to `createNimbusHandler({ auth: { mode:
+ * 'auto' } })` — same shape an external embedder uses via
+ * `@nimbus-sh/worker`. This file's only deploy-specific logic is the
+ * W6.5 registry-event sink installed at module-load time.
+ */
+import { NimbusSession, NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, } from './session/nimbus-session.js';
+import { SupervisorRPC } from './session/supervisor-rpc.js';
+import { CirrusHmrRPC } from './facets/real-vite-hmr.js';
+import { createNimbusHandler } from './router/index.js';
+import { getCtxExports as _getCtxExports } from './session/ctx-exports.js';
+import { setRegistryEventSink } from './facets/wasm-swap-registry.js';
+// Re-export the composable factory + companion types so embedders can
+// build their own default-export handlers. The thin path:
+//   import { createNimbusHandler, NimbusSession } from '@nimbus-sh/worker';
+//   export { NimbusSession };
+//   export default createNimbusHandler();
+export { createNimbusHandler } from './router/index.js';
+// Auth surface — embedders need `issueNimbusToken` / `verifyNimbusToken`
+// to mint tokens from custom routes. Re-exported here for the canonical
+// `@nimbus-sh/worker` entry; `@nimbus-sh/sdk/token` re-re-exports from
+// the dedicated auth subpath for non-Worker callers.
+export { issueNimbusToken, verifyNimbusToken, NimbusAuthError, } from './auth/index.js';
+// W6.5: install the default registry-event sink at module top so events
+// emitted from any code path (supervisor BFS, facet drain, applyW6Registry)
+// land in `wrangler tail` as one JSON line per event. When F-observability
+// lands, replace this with `env.INSTALL_METRICS.writeDataPoint(...)`.
+//
+// Format: `[w6.5/registry] {"type":"swap","from":"...","to":"...","ctx":"top"}`
+setRegistryEventSink((e) => {
+    try {
+        console.log(`[w6.5/registry] ${JSON.stringify(e)}`);
+    }
+    catch {
+        // Defensive — never break the install path on telemetry serialization.
+    }
+});
+// Re-export inner-Worker binding shims so wrangler bundles them AND
+// ctx.exports auto-populates Service Bindings for them (via
+// enable_ctx_exports; default at compat date 2026-04-01+).
+export { NimbusSession, SupervisorRPC, NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, CirrusHmrRPC, };
+/**
+ * Module-level reference to ctx.exports from the fetch handler.
+ * Used by NimbusSession to create loopback bindings for facets.
+ * Set once on the first fetch() call by createNimbusHandler.
+ */
+export function getCtxExports() {
+    return _getCtxExports();
+}
+// Worker default export — a `createNimbusHandler()` instance running in
+// auto auth mode. The live demo and dogfood embedder are bit-identical
+// from here on; the only difference is `NIMBUS_LEGACY_PUBLIC=1` env var
+// (set on the live demo, unset for the dogfood) flipping auth.mode to
+// 'legacy' inside the auto-resolver.
+export default createNimbusHandler();

package/dist/loaders/child-process/spawn-facet.d.ts

@@ -0,0 +1,90 @@
+/**
+ * spawn-facet.ts — Per-spawn task body run inside a fresh Worker Loader
+ * isolate via NimbusFanoutPool.
+ *
+ * Why this exists (gap #1 from arch-gaps wave)
+ * ────────────────────────────────────────────
+ * Pre-arch-gaps, child_process.spawn from inside a node facet RPCs back
+ * to the supervisor's FacetProcessManager._dispatch, which directly
+ * invokes either commandRegistry.runPureBuiltin or facetMgr.execStream.
+ * Both paths execute IN THE SUPERVISOR'S V8 CONTEXT. The supervisor's
+ * heap thus accumulates per-spawn allocation pressure.
+ *
+ * arch-gaps target: every cp.spawn / spawnSync / exec / execFile call
+ * runs inside a fresh Worker Loader isolate. NimbusFanoutPool (proven
+ * by F-1 install-batch and F-2 resolver fan-out) provides the auto-
+ * routing primitive (in-DO POC C for <5, peer-DO POC B for ≥5).
+ *
+ * What this task does
+ * ───────────────────
+ *   1. Mints a per-isolate token (`globalThis.__nimbus_g3_token__`).
+ *      The first call into a fresh isolate creates the token; warm
+ *      slots reuse it. Distinct tokens across calls = distinct
+ *      isolates. Probe surface: audit/probes/arch-gaps/g3-e2e/
+ *      child-spawn-isolation.mjs.
+ *   2. Delegates the actual command execution to
+ *      `env.SUPERVISOR.cpDispatchInline(req, kind)`. This RPC reuses
+ *      the existing pure-builtin / facet-direct execution paths
+ *      (preserves correctness) but the dispatch envelope itself ran
+ *      in a fresh isolate.
+ *   3. Returns `{ exitCode, marker, stdout, stderr }`. The supervisor-
+ *      side ChildProcessSpawnPool wraps the marker into a per-spawn
+ *      stderr line and forwards stdout/stderr to the parent's WS.
+ *
+ * Single-ownership invariant (carried over from git-freeze Q-fix):
+ * stdin (if any) is passed by-value as a string in `req.stdin`; no
+ * shared ArrayBuffer/Uint8Array refs. The result envelope returns
+ * stdout/stderr as strings (already copied by the structured-clone
+ * boundary).
+ *
+ * Stability invariants (cloudflare-parallel serialises via fn.toString):
+ *   - No `this` references.
+ *   - No closure capture other than args + (optional) preamble.
+ *   - The function is the only export's body; helpers inlined.
+ */
+export interface SpawnInIsolateSpec {
+    /** The original cp.spawn payload from node-shims.ts. */
+    req: {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+        cwd: string;
+        stdio?: any;
+        detached?: boolean;
+        shell?: boolean | string;
+        stdin?: string;
+    };
+    /** Pre-resolved kind from FacetProcessManager._dispatch. */
+    kind: 'pure-builtin' | 'facet-direct' | 'unknown';
+    /** Stable id the parent captured for the spawn (for hooks-routing). */
+    parentChildId: number | string;
+}
+export interface SpawnInIsolateResult {
+    exitCode: number;
+    /** Per-isolate token line: `[g3-spawn-isolate] tok=<TOKEN>\n`.
+     *  Pre-pended to stderr by the supervisor-side spawn-pool when the
+     *  result is forwarded to the cp.spawn parent. Distinct values across
+     *  results = distinct isolates ran the dispatch. */
+    marker: string;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Per-spawn task body. Serialised via fn.toString() and dispatched
+ * by NimbusFanoutPool.submitMany. Signature must be (spec, env) so
+ * NimbusFanoutPool's internal `fn(item, env)` lines up.
+ *
+ * `env.SUPERVISOR` is the supervisor-rpc binding wired automatically
+ * by NimbusLoaderPool (see src/loaders/loader-pool.ts:288 — bindings
+ * default to `{ SUPERVISOR }`).
+ */
+export declare const runSpawnInIsolate: (spec: SpawnInIsolateSpec, env: {
+    SUPERVISOR: {
+        cpDispatchInline(req: any, kind: string): Promise<{
+            exitCode: number;
+            stdout: string;
+            stderr: string;
+        }>;
+    };
+}) => Promise<SpawnInIsolateResult>;
+//# sourceMappingURL=spawn-facet.d.ts.map

package/dist/loaders/child-process/spawn-facet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-facet.d.ts","sourceRoot":"","sources":["../../../src/loaders/child-process/spawn-facet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,GAAG,EAAE;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,GAAG,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,4DAA4D;IAC5D,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;IAClD,uEAAuE;IACvE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;wDAGoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,kBAAkB,EACxB,KAAK;IACH,UAAU,EAAE;QACV,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;YAChD,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;SAClD,CAAC,CAAC;KACJ,CAAC;CACH,KACA,OAAO,CAAC,oBAAoB,CAoD9B,CAAC"}

package/dist/loaders/child-process/spawn-facet.js

@@ -0,0 +1,103 @@
+/**
+ * spawn-facet.ts — Per-spawn task body run inside a fresh Worker Loader
+ * isolate via NimbusFanoutPool.
+ *
+ * Why this exists (gap #1 from arch-gaps wave)
+ * ────────────────────────────────────────────
+ * Pre-arch-gaps, child_process.spawn from inside a node facet RPCs back
+ * to the supervisor's FacetProcessManager._dispatch, which directly
+ * invokes either commandRegistry.runPureBuiltin or facetMgr.execStream.
+ * Both paths execute IN THE SUPERVISOR'S V8 CONTEXT. The supervisor's
+ * heap thus accumulates per-spawn allocation pressure.
+ *
+ * arch-gaps target: every cp.spawn / spawnSync / exec / execFile call
+ * runs inside a fresh Worker Loader isolate. NimbusFanoutPool (proven
+ * by F-1 install-batch and F-2 resolver fan-out) provides the auto-
+ * routing primitive (in-DO POC C for <5, peer-DO POC B for ≥5).
+ *
+ * What this task does
+ * ───────────────────
+ *   1. Mints a per-isolate token (`globalThis.__nimbus_g3_token__`).
+ *      The first call into a fresh isolate creates the token; warm
+ *      slots reuse it. Distinct tokens across calls = distinct
+ *      isolates. Probe surface: audit/probes/arch-gaps/g3-e2e/
+ *      child-spawn-isolation.mjs.
+ *   2. Delegates the actual command execution to
+ *      `env.SUPERVISOR.cpDispatchInline(req, kind)`. This RPC reuses
+ *      the existing pure-builtin / facet-direct execution paths
+ *      (preserves correctness) but the dispatch envelope itself ran
+ *      in a fresh isolate.
+ *   3. Returns `{ exitCode, marker, stdout, stderr }`. The supervisor-
+ *      side ChildProcessSpawnPool wraps the marker into a per-spawn
+ *      stderr line and forwards stdout/stderr to the parent's WS.
+ *
+ * Single-ownership invariant (carried over from git-freeze Q-fix):
+ * stdin (if any) is passed by-value as a string in `req.stdin`; no
+ * shared ArrayBuffer/Uint8Array refs. The result envelope returns
+ * stdout/stderr as strings (already copied by the structured-clone
+ * boundary).
+ *
+ * Stability invariants (cloudflare-parallel serialises via fn.toString):
+ *   - No `this` references.
+ *   - No closure capture other than args + (optional) preamble.
+ *   - The function is the only export's body; helpers inlined.
+ */
+/**
+ * Per-spawn task body. Serialised via fn.toString() and dispatched
+ * by NimbusFanoutPool.submitMany. Signature must be (spec, env) so
+ * NimbusFanoutPool's internal `fn(item, env)` lines up.
+ *
+ * `env.SUPERVISOR` is the supervisor-rpc binding wired automatically
+ * by NimbusLoaderPool (see src/loaders/loader-pool.ts:288 — bindings
+ * default to `{ SUPERVISOR }`).
+ */
+export const runSpawnInIsolate = async function runSpawnInIsolate(spec, env) {
+    // Mint or reuse the per-isolate token.
+    const g = globalThis;
+    if (typeof g.__nimbus_g3_token__ !== 'string') {
+        g.__nimbus_g3_token__ = Math.random().toString(36).slice(2, 10) +
+            Math.random().toString(36).slice(2, 6);
+    }
+    const marker = '[g3-spawn-isolate] tok=' + g.__nimbus_g3_token__ + '\n';
+    if (!spec || !spec.req) {
+        return { exitCode: 1, marker, stdout: '', stderr: 'spawn-facet: missing spec.req\n' };
+    }
+    if (spec.kind === 'unknown') {
+        return {
+            exitCode: 127,
+            marker,
+            stdout: '',
+            stderr: spec.req.command + ': command not found\n',
+        };
+    }
+    // env.SUPERVISOR is auto-injected by NimbusLoaderPool and pinned to
+    // THIS DO's id (props.doId = ctx.id.toString()). With the in-DO
+    // POC C route, "this DO" IS the user-session DO whose _cpRegistry
+    // is populated; cpDispatchInline therefore reaches the right
+    // dispatcher.
+    if (!env || !env.SUPERVISOR || typeof env.SUPERVISOR.cpDispatchInline !== 'function') {
+        return {
+            exitCode: 1,
+            marker,
+            stdout: '',
+            stderr: 'spawn-facet: env.SUPERVISOR.cpDispatchInline missing\n',
+        };
+    }
+    try {
+        const r = await env.SUPERVISOR.cpDispatchInline(spec.req, spec.kind);
+        return {
+            exitCode: typeof r.exitCode === 'number' ? r.exitCode : 1,
+            marker,
+            stdout: typeof r.stdout === 'string' ? r.stdout : '',
+            stderr: typeof r.stderr === 'string' ? r.stderr : '',
+        };
+    }
+    catch (e) {
+        return {
+            exitCode: 1,
+            marker,
+            stdout: '',
+            stderr: 'spawn-facet error: ' + (e && e.message ? e.message : String(e)) + '\n',
+        };
+    }
+};

package/dist/loaders/child-process/spawn-pool.d.ts

@@ -0,0 +1,110 @@
+/**
+ * spawn-pool.ts — Supervisor-side wrapper that runs each cp.spawn
+ * dispatch in a fresh Worker Loader isolate via NimbusFanoutPool.
+ *
+ * Why this exists (gap #1 from arch-gaps wave)
+ * ────────────────────────────────────────────
+ * Closes the architectural gap surfaced by G1 S6: pre-arch-gaps,
+ * cp.spawn / spawnSync / exec / execFile from inside a node facet
+ * RPCs back to the supervisor's FacetProcessManager._dispatch, which
+ * directly invokes commandRegistry.runPureBuiltin / facetMgr.execStream
+ * IN-SUPERVISOR. The supervisor accumulates per-spawn allocation
+ * pressure.
+ *
+ * Post-arch-gaps, FacetProcessManager._dispatch routes through this
+ * pool, which submits ONE NimbusFanoutPool.submitMany task per spawn.
+ * NimbusFanoutPool auto-routes:
+ *   < IN_DO_THRESHOLD (5) → POC C in-DO (concurrency = task count, capped at 4)
+ *   ≥ IN_DO_THRESHOLD     → POC B peer-DO with stable-id router
+ *                            (key = command name, so re-installs of
+ *                            the same toolchain cluster on warm peers).
+ *
+ * The per-spawn task body (`runSpawnInIsolate`) emits a per-isolate
+ * marker token and delegates the actual command execution back to the
+ * supervisor via `env.SUPERVISOR.cpDispatchInline(req, kind)` — that
+ * RPC reuses the existing pure-builtin / facet-direct paths (no
+ * correctness regression). The architectural win is the dispatch
+ * envelope itself running in a fresh isolate.
+ *
+ * Why one-task-per-spawn (not batched)
+ * ────────────────────────────────────
+ * cp.spawn is asynchronous from the parent's perspective: each spawn
+ * call returns an emitter immediately, with output streaming as data
+ * arrives. Batching multiple unrelated spawns into one submitMany
+ * call would couple their lifetimes (any failure aborts the batch).
+ * Per-spawn submit gives each call its own isolate-lifecycle envelope,
+ * matching the cp.spawn contract.
+ *
+ * Anti-requirements observed
+ * ──────────────────────────
+ *   - NO setTimeout / sleep on hot paths.
+ *   - NO fallback to in-supervisor dispatch when env.LOADER missing —
+ *     NimbusFanoutPool throws BindingError at construction. Caller
+ *     (FacetProcessManager._dispatch) propagates the error to the
+ *     parent's stderr.
+ *   - Single-ownership: stdin/stdout/stderr crossing the loader RPC
+ *     boundary are strings (structured-clone boundary copies them).
+ */
+export interface SpawnPoolHooks {
+    onStdout(data: string): void;
+    onStderr(data: string): void;
+}
+export interface SpawnPoolReq {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    stdio?: any;
+    detached?: boolean;
+    shell?: boolean | string;
+    stdin?: string;
+}
+export declare class ChildProcessSpawnPool {
+    private readonly env;
+    private readonly ctx;
+    /**
+     * Shared NimbusLoaderPool with concurrency=4 (the workerd
+     * dynamic-worker cap). `submit` lands on slot 0 — 8 concurrent
+     * submits all share slot 0 sequentially via the slot's ownership
+     * (one in-flight LOADER.get per slot). Re-using the same pool
+     * across runOne calls avoids the 4-cap entirely: only ONE
+     * LOADER.get ref is held at a time per slot, and there are at
+     * most 4 slots = 4 concurrent LOADER.get refs from this pool.
+     *
+     * The map() variant distributes items across slots (concurrency=4
+     * items at a time). For per-spawn isolation we use submit() so
+     * each spawn runs serially through one slot; that gives the
+     * architectural win (spawn dispatch runs in a Worker Loader
+     * isolate, NOT in the supervisor's V8 context) without tripping
+     * the workerd cap.
+     *
+     * Trade-off: 8 concurrent cp.spawn calls become serial through
+     * slot 0. Wall-clock cost: ~50ms per spawn dispatch (warm-isolate
+     * RPC round-trip). For typical interactive shell usage (1-3
+     * spawns) this is invisible. Heavy parallel patterns (npm test
+     * launching N jest workers) sequentialise — accepted trade-off
+     * vs the prod-failure-mode of "Too many concurrent dynamic
+     * workers." Future improvement: distribute via map() when batch
+     * shape is known.
+     */
+    private readonly pool;
+    /**
+     * Promise chain for serializing submits. Each new submit awaits
+     * the previous one's completion BEFORE invoking pool.submit.
+     * This gives us strict 1-in-flight-at-a-time on slot 0; 4-cap
+     * never trips even with 8 concurrent cp.spawn invocations.
+     */
+    private chain;
+    constructor(env: any, ctx: DurableObjectState);
+    /**
+     * Dispatch a single cp.spawn request through a fresh Worker Loader
+     * isolate. Streams stdout/stderr to the parent via `hooks` once the
+     * task completes (we don't have incremental streaming yet — the
+     * supervisor-side cpDispatchInline returns final strings; future
+     * improvement: pull-RPC streaming from the loader isolate).
+     *
+     * Returns the exit code.
+     */
+    runOne(req: SpawnPoolReq, kind: 'pure-builtin' | 'facet-direct' | 'unknown', hooks: SpawnPoolHooks, childId: number | string): Promise<number>;
+}
+//# sourceMappingURL=spawn-pool.d.ts.map

package/dist/loaders/child-process/spawn-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-pool.d.ts","sourceRoot":"","sources":["../../../src/loaders/child-process/spawn-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAuC;gBAExC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,kBAAkB;IAW7C;;;;;;;;OAQG;IACG,MAAM,CACV,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,EACjD,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC;CAyDnB"}

package/dist/loaders/child-process/spawn-pool.js

@@ -0,0 +1,161 @@
+/**
+ * spawn-pool.ts — Supervisor-side wrapper that runs each cp.spawn
+ * dispatch in a fresh Worker Loader isolate via NimbusFanoutPool.
+ *
+ * Why this exists (gap #1 from arch-gaps wave)
+ * ────────────────────────────────────────────
+ * Closes the architectural gap surfaced by G1 S6: pre-arch-gaps,
+ * cp.spawn / spawnSync / exec / execFile from inside a node facet
+ * RPCs back to the supervisor's FacetProcessManager._dispatch, which
+ * directly invokes commandRegistry.runPureBuiltin / facetMgr.execStream
+ * IN-SUPERVISOR. The supervisor accumulates per-spawn allocation
+ * pressure.
+ *
+ * Post-arch-gaps, FacetProcessManager._dispatch routes through this
+ * pool, which submits ONE NimbusFanoutPool.submitMany task per spawn.
+ * NimbusFanoutPool auto-routes:
+ *   < IN_DO_THRESHOLD (5) → POC C in-DO (concurrency = task count, capped at 4)
+ *   ≥ IN_DO_THRESHOLD     → POC B peer-DO with stable-id router
+ *                            (key = command name, so re-installs of
+ *                            the same toolchain cluster on warm peers).
+ *
+ * The per-spawn task body (`runSpawnInIsolate`) emits a per-isolate
+ * marker token and delegates the actual command execution back to the
+ * supervisor via `env.SUPERVISOR.cpDispatchInline(req, kind)` — that
+ * RPC reuses the existing pure-builtin / facet-direct paths (no
+ * correctness regression). The architectural win is the dispatch
+ * envelope itself running in a fresh isolate.
+ *
+ * Why one-task-per-spawn (not batched)
+ * ────────────────────────────────────
+ * cp.spawn is asynchronous from the parent's perspective: each spawn
+ * call returns an emitter immediately, with output streaming as data
+ * arrives. Batching multiple unrelated spawns into one submitMany
+ * call would couple their lifetimes (any failure aborts the batch).
+ * Per-spawn submit gives each call its own isolate-lifecycle envelope,
+ * matching the cp.spawn contract.
+ *
+ * Anti-requirements observed
+ * ──────────────────────────
+ *   - NO setTimeout / sleep on hot paths.
+ *   - NO fallback to in-supervisor dispatch when env.LOADER missing —
+ *     NimbusFanoutPool throws BindingError at construction. Caller
+ *     (FacetProcessManager._dispatch) propagates the error to the
+ *     parent's stderr.
+ *   - Single-ownership: stdin/stdout/stderr crossing the loader RPC
+ *     boundary are strings (structured-clone boundary copies them).
+ */
+import { NimbusLoaderPool } from '../loader-pool.js';
+import { runSpawnInIsolate } from './spawn-facet.js';
+export class ChildProcessSpawnPool {
+    env;
+    ctx;
+    /**
+     * Shared NimbusLoaderPool with concurrency=4 (the workerd
+     * dynamic-worker cap). `submit` lands on slot 0 — 8 concurrent
+     * submits all share slot 0 sequentially via the slot's ownership
+     * (one in-flight LOADER.get per slot). Re-using the same pool
+     * across runOne calls avoids the 4-cap entirely: only ONE
+     * LOADER.get ref is held at a time per slot, and there are at
+     * most 4 slots = 4 concurrent LOADER.get refs from this pool.
+     *
+     * The map() variant distributes items across slots (concurrency=4
+     * items at a time). For per-spawn isolation we use submit() so
+     * each spawn runs serially through one slot; that gives the
+     * architectural win (spawn dispatch runs in a Worker Loader
+     * isolate, NOT in the supervisor's V8 context) without tripping
+     * the workerd cap.
+     *
+     * Trade-off: 8 concurrent cp.spawn calls become serial through
+     * slot 0. Wall-clock cost: ~50ms per spawn dispatch (warm-isolate
+     * RPC round-trip). For typical interactive shell usage (1-3
+     * spawns) this is invisible. Heavy parallel patterns (npm test
+     * launching N jest workers) sequentialise — accepted trade-off
+     * vs the prod-failure-mode of "Too many concurrent dynamic
+     * workers." Future improvement: distribute via map() when batch
+     * shape is known.
+     */
+    pool;
+    /**
+     * Promise chain for serializing submits. Each new submit awaits
+     * the previous one's completion BEFORE invoking pool.submit.
+     * This gives us strict 1-in-flight-at-a-time on slot 0; 4-cap
+     * never trips even with 8 concurrent cp.spawn invocations.
+     */
+    chain = Promise.resolve();
+    constructor(env, ctx) {
+        this.env = env;
+        this.ctx = ctx;
+        this.pool = new NimbusLoaderPool(env, ctx, {
+            tag: 'cp-spawn',
+            concurrency: 1,
+            timeoutMs: 2 * 60_000,
+            retries: 0,
+        });
+    }
+    /**
+     * Dispatch a single cp.spawn request through a fresh Worker Loader
+     * isolate. Streams stdout/stderr to the parent via `hooks` once the
+     * task completes (we don't have incremental streaming yet — the
+     * supervisor-side cpDispatchInline returns final strings; future
+     * improvement: pull-RPC streaming from the loader isolate).
+     *
+     * Returns the exit code.
+     */
+    async runOne(req, kind, hooks, childId) {
+        const spec = {
+            req: {
+                // Single-ownership: defensive copy of the request fields that
+                // cross the RPC boundary. Strings are copied by structured-clone;
+                // we explicitly copy `args` and `env` arrays/objects so a
+                // post-call mutation in the caller doesn't affect the task body.
+                command: String(req.command || ''),
+                args: Array.isArray(req.args) ? req.args.map(String) : [],
+                env: { ...(req.env || {}) },
+                cwd: String(req.cwd || '/home/user'),
+                stdio: req.stdio,
+                detached: !!req.detached,
+                shell: req.shell ?? false,
+                stdin: typeof req.stdin === 'string' ? req.stdin : '',
+            },
+            kind,
+            parentChildId: childId,
+        };
+        // Serialize through slot 0 of the shared pool so workerd's per-
+        // method-context dynamic-worker cap (4) is never tripped. The
+        // chain promise links each spawn to wait for the previous one to
+        // settle BEFORE issuing pool.submit. Slot 0 has at most one
+        // in-flight LOADER.get ref at any moment.
+        let result;
+        const myTurn = this.chain.then(async () => {
+            try {
+                return await this.pool.submit(runSpawnInIsolate, spec);
+            }
+            catch (e) {
+                const msg = (e && e.message) ? String(e.message) : String(e);
+                return { exitCode: 1, marker: '', stdout: '', stderr: 'spawn-pool: ' + msg + '\n' };
+            }
+        });
+        // Update the chain BEFORE awaiting so the next caller serializes
+        // behind us. .catch consumed so a runOne failure doesn't break
+        // the chain for subsequent calls.
+        this.chain = myTurn.catch(() => undefined);
+        result = await myTurn;
+        const results = [result];
+        if (!results || results.length === 0) {
+            hooks.onStderr('spawn-pool: no result returned\n');
+            return 1;
+        }
+        const r = results[0];
+        // Emit the per-isolate marker FIRST so the probe sees it ahead of
+        // any user-command stderr. The probe's regex `[g3-spawn-isolate]
+        // tok=…` matches this exact line.
+        if (r.marker)
+            hooks.onStderr(r.marker);
+        if (r.stdout)
+            hooks.onStdout(r.stdout);
+        if (r.stderr)
+            hooks.onStderr(r.stderr);
+        return typeof r.exitCode === 'number' ? r.exitCode : 1;
+    }
+}