@nimbus-sh/worker 0.5.0 → 0.7.0

package/dist/session/nimbus-session.js

@@ -8,17 +8,15 @@
 import { staticStdinReader } from '@nimbus-sh/core/shell/stdin-adapter.js';
 import { DurableObject as CloudflareDurableObject } from 'cloudflare:workers';
 import { SqliteVFS } from '@nimbus-sh/core/vfs/sqlite-vfs.js';
-import { FacetManager } from '../facets/manager.js';
-import { resolveDurableWorkerImage } from '../facets/durable-images.js';
-import { FacetProcessManager } from '../facets/process.js';
+import { composeFacetManager } from '../facets/compose.js';
+import { FacetProcessManager, textBytes } from '../facets/process.js';
 import { ChildProcessSpawnPool } from '../loaders/child-process/spawn-pool.js';
 import { SessionProcessSupervisor } from '@nimbus-sh/core/runtime/session-process-supervisor.js';
 import { PID_GEN_STRIDE } from '@nimbus-sh/core/runtime/process-table.js';
 import { CRED_KERNEL, CRED_SESSION_USER, } from '@nimbus-sh/core/runtime/os-contracts.js';
 import { PortRegistry } from '@nimbus-sh/core/runtime/port-registry.js';
+import { EsbuildBundlePool } from '../facets/esbuild-bundle-pool.js';
 import { EsbuildService } from '@nimbus-sh/core/runtime/esbuild-service.js';
-import { ESBUILD_TRANSFORM_WORKER_ID, esbuildTransformWorkerCode, } from '../facets/esbuild-transform.js';
-import { fetchEsbuildWasmBytes } from '../runtime/esbuild-wasm-bytes.js';
 import { registerAllocObserver } from '@nimbus-sh/platform/heavy-alloc-coord.js';
 // S10: oom-discriminator helpers (recordFailure, getFailures,
 // getLastRpcFrame, getLastFacetId, snapshotForStorage, rehydrateFromStorage)
@@ -35,7 +33,7 @@ import { registerAllocObserver } from '@nimbus-sh/platform/heavy-alloc-coord.js'
 import { adoptCtxExports } from '@nimbus-sh/fabric/composition.js';
 import { NIMBUS_VERSION, DEFAULT_MOUNT_POINTS, CF_COMPAT_DATE } from '@nimbus-sh/core/constants.js';
 import { seedBaseFilesystem } from '@nimbus-sh/core/workspace';
-import { seedProject } from '@nimbus-sh/core/vfs/seed-project.js';
+import { seedProject, SEED_PROJECT_NAME } from '@nimbus-sh/core/vfs/seed-project.js';
 import { BASE_PATH_HEADER } from '../_shared/session-router.js';
 import { ATTACH_BOOTSTRAP_JTI_KEY_PREFIX, SESSION_DESTROYED_KEY } from './keys.js';
 import { appendScrollback } from './state-store.js';
@@ -56,13 +54,13 @@ import { initSession as _w11InitSession } from './init.js';
 import { wsMessage as _wsDoMessage, wsClose as _wsDoClose, wsError as _wsDoError, safePersistRing as _wsDoSafePersistRing, } from './ws.js';
 // S8: Supervisor RPC + W8 cp* + legacy VFS impls extracted.
 import * as _rpc from './rpc.js';
-import { sessionSupervisorOp } from './supervisor-op.js';
-import { processHostFor } from '../loaders/process-host.js';
+import { buildSessionSupervisorOps } from './supervisor-op.js';
 // The supervisor terminates a facet's outbound sockets so inbound frames
 // arrive as supervisor replies (VFS coherence witness 3).
 import { WebSocketRelay } from './ws-relay.js';
 // S9: HTTP fetch routing extracted (combined S9a + S9b).
 import * as _routes from './routes.js';
+import * as _portCapability from './port-capability.js';
 // Programmatic SDK RPC surface.
 import * as _programmatic from './programmatic.js';
 // S10: heap probe + W5 OOM-ring persistence extracted.
@@ -170,7 +168,7 @@ Cloud-native development environment on Cloudflare Workers.
 | --- | --- |
 | Run JavaScript | \`node hello.js\` |
 | Install npm packages | \`npm install <pkg>\` |
-| Start the starter app | \`cd app && npm install && npm run dev\` |
+| Start the starter app | \`cd ${SEED_PROJECT_NAME} && npm install && npm run dev\` |
 | Run a Cloudflare Worker locally | \`nimbus-wrangler dev\` |
 
 ## AI Models
@@ -245,12 +243,15 @@ The editor opens this file in Markdown preview mode by default. Use
 export class NimbusSession extends CloudflareDurableObject {
     // this.ctx and this.env are provided by the DurableObject base class
     sqliteFs = null;
-    runtimeFsBridges = null;
     kernel = null;
     shell = null;
     shellProcessPid = null;
     terminal = null;
-    facetManager = null;
+    /** The composed manager is the one field; `.manager` is derived. */
+    facetManagerComposed = null;
+    get facetManager() {
+        return this.facetManagerComposed?.manager ?? null;
+    }
     /** W8: child_process broker. Lazy — only constructed when first cp* RPC arrives. */
     facetProcessManager = null;
     /**
@@ -260,6 +261,12 @@ export class NimbusSession extends CloudflareDurableObject {
      */
     webSocketRelay = null;
     esbuildService = null;
+    /**
+     * The session's single esbuild facet pool, shared by the npm installer's
+     * pre-bundler and the dev server's on-demand /@modules/ path. Lazy; see
+     * ensureBundlePool. Disposed with the installer and dev server.
+     */
+    bundlePool = null;
     viteDevServer = null;
     /**
      * runtime primitive support (P5): PID + port the default-Cirrus vite shim is
@@ -393,6 +400,13 @@ export class NimbusSession extends CloudflareDurableObject {
     sessionBasePath = '';
     /** Have we attempted to hydrate sessionBasePath from storage yet? */
     sessionBasePathHydrated = false;
+    /**
+     * The origin this session was last reached at (`https://host`), remembered
+     * beside the base path so the session can spell a path-form URL for one
+     * of its own applications — `nimbus expose` printing one, `apps.list`
+     * carrying one — on a deployment with no preview-host suffix.
+     */
+    sessionOrigin = '';
     /**
      * Has the "wrangler is aliased to nimbus-wrangler" banner been shown
      * this session? Reset on WebSocket close/reopen so a reconnecting user
@@ -545,8 +559,8 @@ export class NimbusSession extends CloudflareDurableObject {
      * it arrives as a new invocation, so the chunk runs against a fresh CPU
      * budget rather than the one the launch has already been spending.
      */
-    _scheduleLaunchTurn() {
-        return timers(this, this.ctx).schedule('resident-launch', Date.now());
+    _scheduleLaunchTurn(notBefore = 0) {
+        return timers(this, this.ctx).schedule('resident-launch', Math.max(Date.now(), notBefore));
     }
     /**
      * Convenience: the full URL prefix for the Vite dev server inside this
@@ -572,6 +586,9 @@ export class NimbusSession extends CloudflareDurableObject {
                 const saved = await this.ctx.storage.get('session-base-path');
                 if (typeof saved === 'string')
                     this.sessionBasePath = saved;
+                const origin = await this.ctx.storage.get('session-origin');
+                if (typeof origin === 'string')
+                    this.sessionOrigin = origin;
             }
             catch { /* storage unavailable — stay empty */ }
             this.sessionBasePathHydrated = true;
@@ -584,6 +601,23 @@ export class NimbusSession extends CloudflareDurableObject {
             }
             catch { }
         }
+        // The router forwards the request under its own origin; a preview host
+        // is not this session's control-plane origin, so only a request that
+        // carried the base path (a /s/<sid>/… door) teaches it.
+        if (fromHeader) {
+            let origin = '';
+            try {
+                origin = new URL(request.url).origin;
+            }
+            catch { /* not an absolute URL — nothing to learn */ }
+            if (origin && origin !== this.sessionOrigin) {
+                this.sessionOrigin = origin;
+                try {
+                    await this.ctx.storage.put('session-origin', origin);
+                }
+                catch { }
+            }
+        }
     }
     /**
      * Consume a single-use attach bootstrap token id (`jti`) — set-if-absent.
@@ -605,27 +639,48 @@ export class NimbusSession extends CloudflareDurableObject {
     // dispatches by name from the stub) keeps working. Method bodies are
     // 1-line delegators that pass `this as any` (per plan §IX rec 1 +
     // DEFECT-D1: ctx is protected and not on a public interface).
+    /**
+     * The one supervisor-op handler this session's bindings, loopback stubs and
+     * `_rpc*` delegates all dispatch through — native filesystem ops against
+     * the shared bridge store, session overrides for the accounting-carrying
+     * reads and the output stream, and the canonical route table for the rest.
+     * Lazy: sqliteFs exists only after ensureSqliteFs().
+     */
+    _supervisorOps = null;
+    supervisorOps() {
+        if (!this._supervisorOps)
+            this._supervisorOps = buildSessionSupervisorOps(this);
+        return this._supervisorOps;
+    }
+    /** The pid-keyed filesystem bridge behind the supervisor ops. */
+    supervisorBridge(pid) {
+        return this.supervisorOps().bridge(pid);
+    }
+    /** Drop a dead pid's supervisor bridge — its credential stops being valid. */
+    supervisorForgetBridge(pid) {
+        this._supervisorOps?.forget(pid);
+    }
     // Supervisor RPC (file/log/HMR/batch)
     supervisorOp(envelope) {
-        return sessionSupervisorOp(this, envelope);
+        return this.supervisorOps().dispatch(envelope);
     }
-    async _rpcReadFile(path, pid) { return _rpc._rpcReadFile(this, path, pid); }
-    async _rpcReadFileBytes(path, pid) { return _rpc._rpcReadFileBytes(this, path, pid); }
+    async _rpcReadFile(path, pid, cred) { return _rpc._rpcReadFile(this, path, pid, cred); }
+    async _rpcReadFileBytes(path, pid, cred) { return _rpc._rpcReadFileBytes(this, path, pid, cred); }
     async _rpcInnerDoFetch(req) { return _rpc._rpcInnerDoFetch(this, req); }
-    async _rpcWriteFile(path, content, pid) { return _rpc._rpcWriteFile(this, path, content, pid); }
+    async _rpcWriteFile(path, content, pid, cred) { return _rpc._rpcWriteFile(this, path, content, pid, cred); }
     async _rpcWriteProtectedRootFile(rootPath, path, content) {
         return _rpc._rpcWriteProtectedRootFile(this, rootPath, path, content);
     }
-    async _rpcStat(path, pid) { return _rpc._rpcStat(this, path, pid); }
-    async _rpcLstat(path, pid) { return _rpc._rpcLstat(this, path, pid); }
+    async _rpcStat(path, pid, cred) { return _rpc._rpcStat(this, path, pid, cred); }
+    async _rpcLstat(path, pid, cred) { return _rpc._rpcLstat(this, path, pid, cred); }
     async _rpcHasLegacySymlinkUnder(path, pid) {
         return _rpc._rpcHasLegacySymlinkUnder(this, path, pid);
     }
     async _rpcUtimes(path, atimeMs, mtimeMs, pid) {
         return _rpc._rpcUtimes(this, path, atimeMs, mtimeMs, pid);
     }
-    async _rpcChmod(path, mode, pid) {
-        return _rpc._rpcChmod(this, path, mode, pid);
+    async _rpcChmod(path, mode, pid, cred) {
+        return _rpc._rpcChmod(this, path, mode, pid, cred);
     }
     async _rpcAccess(path, mode, pid) {
         return _rpc._rpcAccess(this, path, mode, pid);
@@ -636,11 +691,11 @@ export class NimbusSession extends CloudflareDurableObject {
     async _rpcSetUmask(mask, pid) {
         return _rpc._rpcSetUmask(this, mask, pid);
     }
-    async _rpcReaddir(path, pid) { return _rpc._rpcReaddir(this, path, pid); }
-    async _rpcExists(path, pid) { return _rpc._rpcExists(this, path, pid); }
-    async _rpcMkdir(path, pid) { return _rpc._rpcMkdir(this, path, pid); }
+    async _rpcReaddir(path, pid, cred) { return _rpc._rpcReaddir(this, path, pid, cred); }
+    async _rpcExists(path, pid, cred) { return _rpc._rpcExists(this, path, pid, cred); }
+    async _rpcMkdir(path, pid, cred) { return _rpc._rpcMkdir(this, path, pid, cred); }
     async _rpcRmdir(path, pid) { return _rpc._rpcRmdir(this, path, pid); }
-    async _rpcRename(from, to, pid) { return _rpc._rpcRename(this, from, to, pid); }
+    async _rpcRename(from, to, pid, cred) { return _rpc._rpcRename(this, from, to, pid, cred); }
     async _rpcReadlink(path, pid) { return _rpc._rpcReadlink(this, path, pid); }
     async _rpcSymlink(target, path, pid) { return _rpc._rpcSymlink(this, target, path, pid); }
     async _rpcFsRevision(path, pid) { return _rpc._rpcFsRevision(this, path, pid); }
@@ -670,8 +725,8 @@ export class NimbusSession extends CloudflareDurableObject {
         return _rpc._rpcFsWrite(this, handleId, offset, bytes, pid);
     }
     async _rpcFsClose(handleId, pid) { return _rpc._rpcFsClose(this, handleId, pid); }
-    async _rpcFsReadRange(path, offset, length, pid) {
-        return _rpc._rpcFsReadRange(this, path, offset, length, pid);
+    async _rpcFsReadRange(path, offset, length, pid, cred) {
+        return _rpc._rpcFsReadRange(this, path, offset, length, pid, cred);
     }
     async _rpcFsReadRangeUncached(path, offset, length, pid) {
         return _rpc._rpcFsReadRangeUncached(this, path, offset, length, pid);
@@ -774,6 +829,14 @@ export class NimbusSession extends CloudflareDurableObject {
     async _rpcExposePort(port, options) {
         return _programmatic.rpcExposePort(this, port, options);
     }
+    // The identity-centric application surface: one implementation each in
+    // programmatic.ts, addressed by port, pid, name or owner.
+    async _rpcExposeApp(target, options) {
+        return _programmatic.rpcExposeApp(this, target, options);
+    }
+    async _rpcListApps() { return _programmatic.rpcListApps(this); }
+    async _rpcRotateLink(target) { return _programmatic.rpcRotateLink(this, target); }
+    async _rpcRemoveApp(target) { return _programmatic.rpcRemoveApp(this, target); }
     async _rpcEnsureDurableApp(input) {
         return _programmatic.rpcEnsureDurableApp(this, input);
     }
@@ -783,7 +846,15 @@ export class NimbusSession extends CloudflareDurableObject {
     async _rpcUnexposePort(port) { return _programmatic.rpcUnexposePort(this, port); }
     /** Capability-authenticated port route, for an embedder holding the token. */
     async _rpcRouteCapabilityPort(port, capability, request, innerPath) {
-        return _routes.routeCapabilityPort(this, port, capability, request, innerPath);
+        return _portCapability.routeCapabilityPort(this, port, capability, request, innerPath);
+    }
+    /** The port route's dev-server restore, delegated — lives in routes.ts where the other session routes do. */
+    restorePersistedDevServer(onlyPort) {
+        return _routes.restorePersistedDevServer(this, onlyPort);
+    }
+    /** The port route's in-DO HMR accept, delegated — same reason. */
+    acceptCirrusHmrWs(request) {
+        return _routes.acceptCirrusHmrWs(this, request);
     }
     /**
      * The port route's recovery seam: a durable application journalled but
@@ -791,10 +862,20 @@ export class NimbusSession extends CloudflareDurableObject {
      * manager decides 'started' | 'absent' | 'failed'; the route maps them.
      */
     async ensureDurableAppOnPort(port) {
+        // Stood up the same way the alarm pump stands itself up: a port request
+        // is the first thing to reach a replacement instance as often as an
+        // alarm is, and the launch it re-drives needs a filesystem to be
+        // re-driven onto — measured live (staging 2026-09-14): without it the
+        // re-drive failed with "a resident process needs a session filesystem".
+        this.ensureSqliteFs();
         this.ensureFacetManager();
         return this.facetManager.ensureDurableAppOnPort(port);
     }
-    async _rpcDeleteFile(path, options) { return _programmatic.rpcDeleteFile(this, path, options); }
+    async _rpcDeleteFile(path, options, cred) { return _programmatic.rpcDeleteFile(this, path, options, cred); }
+    /** Colocated embedders only (DO stub); not on the remote dispatcher. See `rpcSpawnWorker`. */
+    async _rpcSpawnWorker(workerCode, command, cwd, opts) {
+        return _programmatic.rpcSpawnWorker(this, workerCode, command, cwd, opts);
+    }
     async _rpcDestroy(options) { return _programmatic.rpcDestroy(this, options); }
     // Legacy VFS (direct method calls)
     vfsReadFile(path) { return _rpc.vfsReadFile(this, path); }
@@ -883,6 +964,7 @@ export class NimbusSession extends CloudflareDurableObject {
                 console.warn('[nimbus/W5] ring rehydrate failed:', e?.message);
             });
         }
+        return this.sqliteFs;
     }
     // ── W5 Lever 5: ring buffer persistence on DO storage ─────────────────
     // Storage key W5_RING_STORAGE_KEY lives in ./nimbus-session-keys.ts (S5).
@@ -906,72 +988,72 @@ export class NimbusSession extends CloudflareDurableObject {
     _w5PersistRing() {
         return _diag.persistRing(this, this.ctx);
     }
+    /** The session's esbuild facet pool provider; constructing it does no work. */
+    ensureBundlePool() {
+        if (!this.bundlePool)
+            this.bundlePool = new EsbuildBundlePool(this.env, this.ctx);
+        return this.bundlePool;
+    }
+    /**
+     * The session's FacetManager, composed through the one factory every host
+     * uses (`facets/compose.ts`). What is wired here is only what is the
+     * session's: the terminal a spawn is announced on, the scrollback a notice
+     * survives in, the alarm that grants a launch its next turn, and the exit
+     * report that keeps the process table honest. The isolated esbuild
+     * transform and the durable image-store fallback are the factory's.
+     */
     ensureFacetManager() {
-        if (!this.facetManager) {
-            this.facetManager = new FacetManager(this.ctx, this.env, this.processes, this.portRegistry, processHostFor, {
-                onExternalExit: (pid, code, reason) => this._reportExternalExit(pid, code, reason),
-                requestLaunchTurn: () => { void this._scheduleLaunchTurn(); },
-                notify: (line) => this._notifySession(line),
-                transformLargeEsm: async (code, options) => {
-                    const loader = Reflect.get(this.env, 'LOADER');
-                    if (!loader || typeof loader.get !== 'function') {
-                        throw new Error('Nimbus: env.LOADER unavailable for isolated esbuild transform');
-                    }
-                    const assets = Reflect.get(this.env, 'ASSETS');
-                    if (!assets || typeof assets.fetch !== 'function') {
-                        throw new Error('Nimbus: env.ASSETS unavailable for isolated esbuild transform');
-                    }
-                    const worker = await loader.get(ESBUILD_TRANSFORM_WORKER_ID, async () => esbuildTransformWorkerCode(await fetchEsbuildWasmBytes({ ASSETS: assets })));
-                    const transformClass = worker.getDurableObjectClass('EsbuildTransformFacet');
-                    const facet = this.ctx.facets.get(`esbuild-transform-${ESBUILD_TRANSFORM_WORKER_ID}`, async () => ({ class: transformClass }));
-                    return facet.transform(code, options);
-                },
-                onSpawn: (pid, command, longRunning) => {
-                    const attachedTty = this.processes.get(pid)?.attachedTty === true;
-                    if (longRunning) {
-                        try {
-                            this.processes.openInput(pid);
+        if (!this.facetManagerComposed) {
+            // The manager is composed over the filesystem, so the filesystem comes
+            // first. Cheap and idempotent; every caller already stood it up or is
+            // about to.
+            this.ensureSqliteFs();
+            this.facetManagerComposed = composeFacetManager({
+                ctx: this.ctx,
+                env: this.env,
+                processes: this.processes,
+                portRegistry: this.portRegistry,
+                vfs: this.sqliteFs,
+                ...(this.esbuildService ? { esbuild: this.esbuildService } : {}),
+                hooks: {
+                    onExternalExit: (pid, code, reason) => this._reportExternalExit(pid, code, reason),
+                    requestLaunchTurn: (notBefore) => { void this._scheduleLaunchTurn(notBefore); },
+                    notify: (line) => this._notifySession(line),
+                    onSpawn: (pid, command, longRunning) => {
+                        const attachedTty = this.processes.get(pid)?.attachedTty === true;
+                        if (longRunning) {
+                            try {
+                                this.processes.openInput(pid);
+                            }
+                            catch { }
                         }
-                        catch { }
-                    }
-                    // Only surface long-running / user-visible spawns to keep
-                    // the terminal uncluttered. Short `node <file>` evals also
-                    // get a line because users want the pid for `logs`/`kill`.
-                    if (!this.terminal)
-                        return;
-                    const label = longRunning ? 'started (long-running)' : 'started';
-                    this.terminal.write(`\x1b[2m[facet ${label}: pid=${pid} cmd="${command}"]\x1b[0m\r\n`);
-                    // Structured event so the tabs UI can auto-open a log tab
-                    // for long-running processes (vite, wrangler dev, etc.).
-                    notifyTerminalEvent(this.terminal, {
-                        type: 'spawn', pid, command, longRunning, attachedTty,
-                    });
-                },
-                // The fallback resolver a self-owned durable spawn re-drives
-                // through: read the image blobs the spawn persisted under
-                // `.nimbus/images/<sha256>` and restore the launch's env and
-                // modules from them. An embedder-owned launch answers its own
-                // bookkeeping through resolveWorkerLaunch instead — this hook is
-                // only the fallback for applications nobody else is keeping, and
-                // because it cannot re-mint a live globalOutbound binding the
-                // spawn path refuses such a launch under it.
-                resolveWorkerLaunchFallback: async (recipe) => {
-                    this.ensureSqliteFs();
-                    return resolveDurableWorkerImage(this.sqliteFs, recipe);
+                        // Only surface long-running / user-visible spawns to keep
+                        // the terminal uncluttered. Short `node <file>` evals also
+                        // get a line because users want the pid for `logs`/`kill`.
+                        if (!this.terminal)
+                            return;
+                        const label = longRunning ? 'started (long-running)' : 'started';
+                        this.terminal.write(`\x1b[2m[facet ${label}: pid=${pid} cmd="${command}"]\x1b[0m\r\n`);
+                        // Structured event so the tabs UI can auto-open a log tab
+                        // for long-running processes (vite, wrangler dev, etc.).
+                        notifyTerminalEvent(this.terminal, {
+                            type: 'spawn', pid, command, longRunning, attachedTty,
+                        });
+                    },
                 },
             });
         }
-        if (this.facetManager && this.sqliteFs) {
-            this.facetManager.setVfs(this.sqliteFs);
-            // W3.5 Fix B: share the session's lazy esbuildService with the
-            // FacetManager so the bundle's ESM→CJS pre-pass doesn't pay
-            // wasm-init twice. If the session hasn't constructed one yet,
-            // FacetManager will lazy-create its own on first exec — same
-            // wasm bytes, same ~10ms init cost, just paid once per surface.
-            if (this.esbuildService) {
-                this.facetManager.setEsbuildService(this.esbuildService);
-            }
+        const composed = this.facetManagerComposed;
+        // W3.5 Fix B: share the session's lazy esbuildService with the
+        // FacetManager so the bundle's ESM→CJS pre-pass doesn't pay
+        // wasm-init twice. The session may construct it after the manager
+        // exists, so the share is re-offered on every call; FacetManager
+        // otherwise lazy-creates its own on first exec — same wasm bytes,
+        // same ~10ms init cost, just paid once per surface.
+        if (this.esbuildService) {
+            composed.manager.setEsbuildService(this.esbuildService);
         }
+        return composed;
     }
     /**
      * The supervisor-owned WebSocket relay. Lazy, because most sessions never
@@ -1013,29 +1095,29 @@ export class NimbusSession extends CloudflareDurableObject {
                 try {
                     const parsed = CpFacetDirectPayloadSchema.safeParse(JSON.parse(codeJson));
                     if (!parsed.success) {
-                        hooks.onStderr('child_process: facet dispatch requires a broker-assigned process pid\n');
+                        hooks.onStderr(textBytes('child_process: facet dispatch requires a broker-assigned process pid\n'));
                         return 1;
                     }
                     payload = parsed.data;
                 }
                 catch {
-                    hooks.onStderr('child_process: invalid facet dispatch payload\n');
+                    hooks.onStderr(textBytes('child_process: invalid facet dispatch payload\n'));
                     return 1;
                 }
                 const registry = this._cpRegistry;
                 if (!registry) {
-                    hooks.onStderr('child_process: command registry unavailable\n');
+                    hooks.onStderr(textBytes('child_process: command registry unavailable\n'));
                     return 127;
                 }
                 const commandName = normalizeCpCommandName(payload.command);
                 const cmd = await registry.resolve(commandName);
                 if (!cmd) {
-                    hooks.onStderr(`${payload.command}: command not found\n`);
+                    hooks.onStderr(textBytes(`${payload.command}: command not found\n`));
                     return 127;
                 }
                 // Synthesize a CommandContext for the internal shell substrate.
-                const stdoutStream = { write: (d) => hooks.onStdout(String(d)) };
-                const stderrStream = { write: (d) => hooks.onStderr(String(d)) };
+                const stdoutStream = { write: (d) => hooks.onStdout(textBytes(String(d))) };
+                const stderrStream = { write: (d) => hooks.onStderr(textBytes(String(d))) };
                 const ac = new AbortController();
                 const cred = this.processes.cred(payload.processPid);
                 const ctx = {
@@ -1071,7 +1153,7 @@ export class NimbusSession extends CloudflareDurableObject {
                     return typeof code === 'number' ? code : 0;
                 }
                 catch (e) {
-                    hooks.onStderr(`${payload.command}: ${e?.message || String(e)}\n`);
+                    hooks.onStderr(textBytes(`${payload.command}: ${e?.message || String(e)}\n`));
                     return 1;
                 }
             },
@@ -1089,10 +1171,10 @@ export class NimbusSession extends CloudflareDurableObject {
         // construction near line 2058 — registry passed as ctor arg there).
         const cmdRegistryAdapter = {
             // Consult the live shell registry FIRST so dynamically-registered
-            // commands (registerUnixCommands / registerGitCommands / npm /
-            // wrangler etc.) are seen even if they're not in the static
-            // _CP_PURE_BUILTIN allow-list. Falls back to the static
-            // facet-direct table for known facet-only commands. Returns null
+            // commands (registerUnixCommands / git / npm / wrangler etc.) are seen
+            // even if they're not in the static _CP_PURE_BUILTIN allow-list. Falls
+            // back to the static facet-direct table for known facet-only commands.
+            // Returns null
             // (→ exit 127) for everything unknown.
             resolve: (name) => {
                 const commandName = normalizeCpCommandName(name);
@@ -1108,13 +1190,13 @@ export class NimbusSession extends CloudflareDurableObject {
             runPureBuiltin: async (pid, name, args, env, cwd, stdin, hooks) => {
                 const registry = this._cpRegistry;
                 if (!registry) {
-                    hooks.onStderr('cp: registry unavailable\n');
+                    hooks.onStderr(textBytes('cp: registry unavailable\n'));
                     return 127;
                 }
                 const commandName = normalizeCpCommandName(name);
                 const cmd = await registry.resolve(commandName);
                 if (!cmd) {
-                    hooks.onStderr(`${name}: command not found\n`);
+                    hooks.onStderr(textBytes(`${name}: command not found\n`));
                     return 127;
                 }
                 const cred = this.processes.cred(pid);
@@ -1124,8 +1206,8 @@ export class NimbusSession extends CloudflareDurableObject {
                     cred,
                     args, env, cwd,
                     vfs: this.sqliteFs.as(cred),
-                    stdout: { write: (d) => hooks.onStdout(String(d)) },
-                    stderr: { write: (d) => hooks.onStderr(String(d)) },
+                    stdout: { write: (d) => hooks.onStdout(textBytes(String(d))) },
+                    stderr: { write: (d) => hooks.onStderr(textBytes(String(d))) },
                     signal: ac.signal,
                     stdin: staticStdinReader(stdin),
                     setUmask: (mask) => { this.processes.setUmask(pid, mask); },
@@ -1148,7 +1230,7 @@ export class NimbusSession extends CloudflareDurableObject {
                     return typeof code === 'number' ? code : 0;
                 }
                 catch (e) {
-                    hooks.onStderr(`${name}: ${e?.message || String(e)}\n`);
+                    hooks.onStderr(textBytes(`${name}: ${e?.message || String(e)}\n`));
                     return 1;
                 }
             },
@@ -1173,7 +1255,7 @@ export class NimbusSession extends CloudflareDurableObject {
             shellExecutor: {
                 execute: async (pid, commandLine, env, cwd, stdin, hooks) => {
                     if (!this.shell) {
-                        hooks.onStderr('sh: shell unavailable\n');
+                        hooks.onStderr(textBytes('sh: shell unavailable\n'));
                         return 127;
                     }
                     const cred = this.processes.cred(pid);
@@ -1194,8 +1276,8 @@ export class NimbusSession extends CloudflareDurableObject {
                     const result = await this.shell.execute(String(commandLine), {
                         cwd: cwd || '/home/user',
                         env: { ...this.shell.env, ...(env || {}) },
-                        onStdout: (d) => hooks.onStdout(String(d)),
-                        onStderr: (d) => hooks.onStderr(String(d)),
+                        onStdout: hooks.onStdout,
+                        onStderr: hooks.onStderr,
                         stdin,
                         isolateShellState: true,
                         commandContext: { pid, cred, setUmask },
@@ -1356,11 +1438,13 @@ export class NimbusSession extends CloudflareDurableObject {
         }
         this.npmInstaller = new NpmInstaller(this.sqliteFs, this.ctx.storage.sql, {
             esbuild: this.esbuildService,
+            bundlePool: this.ensureBundlePool(),
             ctx: this.ctx,
             env: this.env,
             onProgress,
             fetchFn,
         });
+        return this.npmInstaller;
     }
     /**
      * Read an environment flag with default-on semantics. Mirrors the
@@ -1385,7 +1469,7 @@ export class NimbusSession extends CloudflareDurableObject {
     // command registrations + boot wiring). The class retains `initSession`
     // as a delegator per plan §IX.4 R1. Visibility relaxed (was `private`)
     // so the SessionInternal interface declares it.
-    initSession(ws) {
+    initSession(ws, options) {
         // A destroyed session id being legitimately re-initialized (shell WS
         // attach, or SDK ready via ensureProgrammaticReady which routes here)
         // lifts the tombstone so the recreated session's log-janitor can arm
@@ -1394,8 +1478,14 @@ export class NimbusSession extends CloudflareDurableObject {
         // Cast pattern (per plan §IX recommendation 1, used here only because
         // initSession reads this.ctx + this.env extensively; siblings that need
         // ctx/env take them as separate explicit args per DEFECT-D1).
-        return _w11InitSession(this, ws);
+        return _w11InitSession(this, ws, options);
     }
+    /**
+     * The rebuild in flight for a shell socket that woke this instance from
+     * hibernation, so every frame that arrives while it runs awaits the one
+     * build instead of starting its own. See session/ws.ts bindShellSocket.
+     */
+    _wakeRebuild = null;
     // ── Filesystem seeding ────────────────────────────────────────────────
     ensureGlobalPrefixDirs(prefix) {
         const fs = this.sqliteFs.as(CRED_SESSION_USER);

package/dist/session/npm-install-port.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The worker's half of `npm install`: core's `npm` command parses the
+ * invocation, owns the pre-checks and the summary text, and hands the
+ * install itself to this port. What the port owns is everything the
+ * command must not know: the NpmInstaller, the global prefix's directory
+ * shape, and the materialisation of bin shims into <prefix>/bin.
+ *
+ * `projectDir` is always the shell's cwd; `globalPrefix` (absolute VFS
+ * path, e.g. `/usr/local`) is present only for `npm install -g` and says
+ * where `<prefix>/lib/node_modules` and `<prefix>/bin` land. `pid` is the
+ * running command's pid — it authorizes the batch-facet writes.
+ */
+import type { NpmInstallPort } from '@nimbus-sh/core/substrate/lifo/commands/system/npm.js';
+import type { SessionInternal } from './internal.js';
+export declare function createNpmInstallPort(self: SessionInternal): NpmInstallPort;
+//# sourceMappingURL=npm-install-port.d.ts.map

package/dist/session/npm-install-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-install-port.d.ts","sourceRoot":"","sources":["../../src/session/npm-install-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uDAAuD,CAAC;AAI5F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAyC1E"}

package/dist/session/npm-install-port.js

@@ -0,0 +1,37 @@
+import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
+import { materializeNpmBinShims } from '../npm/bin-links.js';
+export function createNpmInstallPort(self) {
+    return {
+        async install(spec) {
+            const globalPrefix = spec.global ? spec.globalPrefix : undefined;
+            const globalBinDir = globalPrefix ? `${globalPrefix}/bin` : undefined;
+            const sqliteFs = self.ensureSqliteFs();
+            const installer = await self.ensureNpmInstaller();
+            if (globalPrefix)
+                self.ensureGlobalPrefixDirs(globalPrefix);
+            const installCwd = globalPrefix ? `${globalPrefix}/lib` : spec.projectDir;
+            const result = await installer.install(installCwd, {
+                packages: spec.packages.length > 0 ? [...spec.packages] : undefined,
+                production: spec.production,
+                pid: spec.pid,
+                npmLog: spec.npmLog ?? undefined,
+                onProgress: spec.onProgress,
+            });
+            let linkedBins = 0;
+            if (globalPrefix && globalBinDir) {
+                // Materialise on-PATH bin shims even for partial installs — the
+                // bin linker already skips entries whose target never landed, so
+                // a partial tree safely exposes exactly the bins that installed.
+                const vfs = sqliteFs.as(CRED_KERNEL);
+                linkedBins = materializeNpmBinShims(vfs, `${installCwd}/node_modules`, globalBinDir);
+            }
+            return {
+                installed: result.installed,
+                failed: result.failed,
+                totalFiles: result.totalFiles,
+                fromCacheHits: result.cachedHits,
+                linkedBins,
+            };
+        },
+    };
+}