@nimbus-sh/worker 0.2.3 → 0.4.0

package/dist/session/programmatic.js

@@ -14,7 +14,96 @@ import { PortRegistry } from '@nimbus-sh/core/runtime/port-registry.js';
 import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
 import { endProcessInput, resizeProcess, signalProcess, writeProcessInput, } from '@nimbus-sh/core/runtime/process-input-routing.js';
 import { z } from 'zod/v4';
-import { SESSION_DESTROYED_KEY, VITE_CONFIG_KEY, W9_ISOLATE_GEN_KEY } from './keys.js';
+import { SESSION_DESTROYED_KEY, SHELL_STATE_KEY_PREFIX, VITE_CONFIG_KEY } from './keys.js';
+import { clearPortCapability, persistPortCapability, restorePortCapability, } from './port-capability.js';
+import { GENERATION_KEY, assumeGeneration, generation } from '@nimbus-sh/fabric/generation.js';
+import { HeadlessTerminal, Shell } from '@nimbus-sh/core/substrate/lifo/index.js';
+const ShellIdSchema = z.string().min(1).max(160).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const ShellStateSchema = z.object({
+    cwd: z.string().startsWith('/'),
+    env: z.record(z.string(), z.string()),
+}).strict();
+/**
+ * A second Shell over the session's own kernel, filesystem and command
+ * registry — the same objects the interactive shell uses, so a named shell is
+ * not a second filesystem or a second process table. Only cwd and environment
+ * are its own, which is exactly what makes `cd` stick between calls.
+ */
+export function createProgrammaticShell(self, pid, state) {
+    const parent = self.shell;
+    if (!parent)
+        throw new Error('Nimbus shell did not initialize');
+    const shell = new Shell(new HeadlessTerminal(), parent.getVfs(), parent.getRegistry(), { ...parent.getEnv(), ...state.env, $: String(pid) }, parent.getProcessRegistry(), {
+        pid,
+        get cred() { return self.processes.cred(pid); },
+        setUmask: (mask) => self.processes.setUmask(pid, mask),
+        runAs: parent.getRunAsHost(),
+    });
+    shell.setCwd(state.cwd);
+    return shell;
+}
+/**
+ * Run `body` against a named shell's durable state, or against nothing when no
+ * `shellId` was given.
+ *
+ * Serialized per id: two concurrent calls naming one shell would otherwise
+ * read the same cwd and race to write it back, and the loser's `cd` would
+ * vanish. A background job reads the state but does not write it back — its
+ * shell outlives the call, so what it would persist is a snapshot of a moment
+ * nobody asked about.
+ */
+async function withShellState(self, options, background, run) {
+    if (options.shellId === undefined)
+        return run(null);
+    const id = ShellIdSchema.parse(options.shellId);
+    self._programmaticShellQueues ??= new Map();
+    const queues = self._programmaticShellQueues;
+    const previous = queues.get(id) ?? Promise.resolve();
+    let release = () => { };
+    const gate = new Promise((resolve) => { release = resolve; });
+    const tail = previous.catch(() => undefined).then(() => gate);
+    queues.set(id, tail);
+    await previous.catch(() => undefined);
+    try {
+        const key = `${SHELL_STATE_KEY_PREFIX}${id}`;
+        const stored = await self.ctx.storage.get(key);
+        const root = typeof options.shellRoot === 'string' && options.shellRoot.startsWith('/')
+            ? options.shellRoot
+            : getHome(self);
+        const state = stored === undefined
+            ? { cwd: root, env: {} }
+            : ShellStateSchema.parse(stored);
+        let shell = null;
+        try {
+            return await run({
+                cwd: state.cwd,
+                create: (pid) => {
+                    shell = createProgrammaticShell(self, pid, state);
+                    return shell;
+                },
+            });
+        }
+        finally {
+            const captured = background || shell === null ? state : capturedShellState(shell);
+            await self.ctx.storage.put(key, captured);
+        }
+    }
+    finally {
+        release();
+        if (queues.get(id) === tail)
+            queues.delete(id);
+    }
+}
+function capturedShellState(shell) {
+    const env = { ...shell.getEnv() };
+    // `$` is the pid of the call that just ended, not state of the shell.
+    delete env.$;
+    return { cwd: shell.getCwd(), env };
+}
+/**
+ * The durable half of the port capability lives in `./port-capability.js`, so
+ * the facet manager can retire a stale one without importing this module.
+ */
 const ProcessLogsOptionsSchema = z.object({
     cursor: z.number().int().nonnegative().optional(),
     lines: z.number().int().nonnegative().optional(),
@@ -101,13 +190,19 @@ export async function ensureProgrammaticReady(self, options = {}) {
     }
     return { ok: true, preinstalled: preinstall };
 }
-function startShellJob(self, command, options, job) {
-    const shell = self.shell;
-    if (!shell)
+function startShellJob(self, command, options, job, scoped) {
+    const parentShell = self.shell;
+    if (!parentShell)
         throw new Error('Nimbus shell did not initialize');
     const line = String(command);
-    const cwd = options.cwd ?? shell.getCwd?.() ?? '/home/user';
-    const entry = self.processes.spawn(line, [line], cwd, { longRunning: job.background });
+    const cwd = options.cwd ?? scoped?.cwd ?? parentShell.getCwd?.() ?? '/home/user';
+    const entry = self.processes.spawn(line, [line], cwd, {
+        longRunning: job.background,
+        cred: options.cred,
+    });
+    // The scoped shell is built around the pid, so its `$` and its credential
+    // are the ones this command actually runs under.
+    const shell = scoped?.create(entry.pid) ?? parentShell;
     const pid = entry.pid;
     if (job.background)
         self.processes.openInput(pid);
@@ -129,8 +224,11 @@ function startShellJob(self, command, options, job) {
         sink?.(text);
     };
     const run = shell.execute(line, {
-        cwd,
-        env: { ...(shell.getEnv?.() ?? {}), ...(options.env ?? {}) },
+        // A named shell already holds its own cwd and env; passing them again
+        // would pin it to the values this call started with and `cd` would not
+        // survive the call, which is the whole point of naming one.
+        cwd: scoped ? options.cwd : cwd,
+        env: scoped ? options.env : { ...(shell.getEnv?.() ?? {}), ...(options.env ?? {}) },
         onStdout: emit('stdout', job.onStdout),
         onStderr: emit('stderr', job.onStderr),
         signal: controller.signal,
@@ -161,6 +259,9 @@ function startShellJob(self, command, options, job) {
 }
 export async function rpcExec(self, command, options = {}) {
     await ensureProgrammaticReady(self, options);
+    return withShellState(self, options, false, (scoped) => execOnShell(self, command, options, scoped));
+}
+async function execOnShell(self, command, options, scoped) {
     const stdout = [];
     const stderr = [];
     const started = Date.now();
@@ -170,7 +271,7 @@ export async function rpcExec(self, command, options = {}) {
         background: false,
         onStdout: (d) => stdout.push(d),
         onStderr: (d) => stderr.push(d),
-    });
+    }, scoped);
     let result;
     try {
         result = options.timeoutMs && options.timeoutMs > 0
@@ -249,7 +350,10 @@ function collectJobOutput(self, pid) {
  */
 export async function rpcStartProcess(self, command, options = {}) {
     await ensureProgrammaticReady(self, options);
-    const job = startShellJob(self, command, options, { background: true });
+    return withShellState(self, options, true, (scoped) => startOnShell(self, command, options, scoped));
+}
+async function startOnShell(self, command, options, scoped) {
+    const job = startShellJob(self, command, options, { background: true }, scoped);
     const line = String(command);
     notifyTerminalEvent(self.terminal ?? null, {
         type: 'spawn', pid: job.pid, command: line, longRunning: true, attachedTty: false,
@@ -411,24 +515,51 @@ export async function rpcProcessLogs(self, pid, options = {}) {
 }
 export async function rpcListPorts(self) {
     await ensureProgrammaticReady(self);
-    return self.portRegistry.getAll().map(serializePort);
+    const entries = self.portRegistry.getAll();
+    // Persisted at the moment the embedder is told the value, not at
+    // registration: a capability nobody has been handed does not need to
+    // survive anything.
+    await Promise.all(entries.map((entry) => persistPortCapability(self, entry.port, entry.capability)));
+    return entries.map(serializePort);
 }
 export async function rpcExposePort(self, port) {
     await ensureProgrammaticReady(self);
     const n = Number(port);
     const entry = self.portRegistry.get(n);
+    if (entry)
+        await persistPortCapability(self, n, entry.capability);
     return {
         port: n,
         listening: !!entry,
         pid: entry?.pid ?? null,
         registeredAt: entry?.registeredAt ?? null,
+        capability: entry?.capability ?? null,
     };
 }
 export async function rpcUnexposePort(self, port) {
     await ensureProgrammaticReady(self);
     const n = Number(port);
+    // Before the unregister, so a crash between the two leaves a dead token
+    // rather than a live one.
+    await clearPortCapability(self, n);
     return { port: n, ok: self.portRegistry.unregister(n) };
 }
+/**
+ * Route an embedder request that carries a port capability. The embedder has
+ * authenticated the capability at its edge and stripped its own credentials,
+ * so the guest's `Authorization` is preserved through this path and no other.
+ */
+export async function rpcRouteCapabilityPort(self, port, capability, request, pathname) {
+    await ensureProgrammaticReady(self);
+    await restorePortCapability(self, port);
+    if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+        // A 101 cannot cross the DO RPC boundary this entrypoint is reached
+        // through; the session fetch route is the one that keeps fetch semantics.
+        return new Response('WebSocket upgrades must use the session fetch route', { status: 409 });
+    }
+    const routed = await self.portRegistry.routeCapabilityRequest(Number(port), String(capability), request, pathname);
+    return routed ?? new Response('Not found', { status: 404 });
+}
 export async function rpcDeleteFile(self, path, options = {}) {
     await ensureProgrammaticReady(self);
     const p = String(path).replace(/^\/+/, '');
@@ -546,7 +677,7 @@ export async function rpcDestroy(self, options = {}) {
         // current-generation (pid > pidBase) — landing its output on the
         // destroyed/recreated session. Keep {tombstone, isolateGen} consistent.
         try {
-            await self.ctx.storage.put(W9_ISOLATE_GEN_KEY, self._w9IsolateGen ?? 0);
+            await self.ctx.storage.put(GENERATION_KEY, generation(self.ctx));
         }
         catch { /* best-effort */ }
         resetInMemorySessionState(self);
@@ -582,10 +713,10 @@ async function quiesceInMemorySessionState(self) {
  * The generation the NEXT boot of this session will run as.
  *
  * rpcDestroy re-persists the pre-destroy generation after wiping storage,
- * so `maybeBumpIsolateGen` reads it back and bumps once — landing here.
+ * so `adoptGeneration` reads it back and bumps once — landing here.
  */
 function successorGeneration(self) {
-    return (self._w9IsolateGen ?? 0) + 1;
+    return generation(self.ctx) + 1;
 }
 /**
  * Install the empty process/port state a destroyed session leaves behind.
@@ -679,12 +810,11 @@ function resetInMemorySessionState(self) {
     // Adopt the generation the next boot will derive from the counter
     // rpcDestroy just re-persisted, so the in-memory pid floor and the
     // persisted one agree. Deliberately left unpersisted: storage keeps the
-    // pre-destroy value, and maybeBumpIsolateGen re-derives this one from it.
-    const generation = successorGeneration(self);
-    installEmptyProcessState(self, generation);
+    // pre-destroy value, and adoptGeneration re-derives this one from it.
+    const successor = successorGeneration(self);
+    installEmptyProcessState(self, successor);
     self._w9SchemaInit = false;
-    self._w9IsolateGen = generation;
-    self._w9IsolateGenPersisted = false;
+    assumeGeneration(self.ctx, successor);
     try {
         self._w9WireProcessLogPersist?.();
     }
@@ -714,6 +844,7 @@ function serializePort(p) {
         port: Number(p.port),
         pid: Number(p.pid),
         registeredAt: Number(p.registeredAt),
+        capability: String(p.capability),
     };
 }
 function shellQuote(s) {

package/dist/session/routes.d.ts

@@ -24,6 +24,8 @@
  * (~30 sites). RoutesHost = any pragmatic deviation, like InitHost in S6.
  */
 type RoutesHost = any;
+/** Route a capability-authenticated embedder request to a guest HTTP server. */
+export declare function routeCapabilityPort(self: RoutesHost, port: number, capability: string, request: Request, innerPath: string): Promise<Response>;
 export declare function handleFetch(self: RoutesHost, request: Request): Promise<Response>;
 export {};
 //# sourceMappingURL=routes.d.ts.map

package/dist/session/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/session/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAsCH,KAAK,UAAU,GAAG,GAAG,CAAC;AAkQtB,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAi8BvF"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/session/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAqDH,KAAK,UAAU,GAAG,GAAG,CAAC;AA6LtB,gFAAgF;AAChF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAyGD,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8+BvF"}

package/dist/session/routes.js

@@ -27,12 +27,12 @@ import { handleReplicaPreflight as _w12HandleReplicaPreflight } from '../replica
 import { replicasSuspended as _w12ReplicasSuspended } from '../replica/suspension.js';
 import { sanitizeUntrustedRequest } from '@nimbus-sh/core/_shared/untrusted-request.js';
 import { matchLogsPath, handleLogsWebSocketRequest, handleProcessesListRequest, } from '../runtime/process-logs-api.js';
-import { readDiagCounters } from '@nimbus-sh/core/observability/diag-counters.js';
-import { getFailures, getLastRpcFrame, getLastFacetId, getRecoveryEvents, recordRecoveryEvent, resetRecoveryEvents, } from '@nimbus-sh/core/observability/oom-discriminator.js';
+import { readDiagCounters } from '@nimbus-sh/platform/diag-counters.js';
+import { getFailures, getLastRpcFrame, getLastFacetId, getRecoveryEvents, recordRecoveryEvent, resetRecoveryEvents, } from '@nimbus-sh/platform/oom-discriminator.js';
 import { DEFAULT_VITE_PORT, LRU_MAX_ENTRIES } from '@nimbus-sh/core/constants.js';
 import { BASE_PATH_HEADER } from '../_shared/session-router.js';
 import { VITE_CONFIG_KEY } from './keys.js';
-import { estimateSupervisorHeap, WORKERD_EVICTION_LABELS } from '@nimbus-sh/core/observability/heap-estimate.js';
+import { estimateSupervisorHeap, WORKERD_EVICTION_LABELS } from '@nimbus-sh/platform/heap-estimate.js';
 import { loadShellState, loadKernelMounts, getScrollbackStats, clearSessionState, appendScrollback, loadScrollback } from './state-store.js';
 import { classifyWsUpgrade, joinExistingSession } from './init-phases.js';
 import { EsbuildService } from '@nimbus-sh/core/runtime/esbuild-service.js';
@@ -40,7 +40,14 @@ import { ViteDevServer } from '../facets/vite-dev-server.js';
 import { notifyTerminalEvent, wireProcessLogSocketBroadcast } from '../runtime/process-logs-api.js';
 import { makeLongRunningPortStub } from '@nimbus-sh/core/runtime/long-running-handle.js';
 import { startRealVite } from './start-real-vite.js';
-import { getLoadedCodesStats } from './bindings.js';
+import { getLoadedCodesStats } from '@nimbus-sh/fabric/bindings.js';
+import { generation } from '@nimbus-sh/fabric/generation.js';
+import { facetIdBudget } from '@nimbus-sh/fabric/budgets.js';
+import { loaderLedgerStats } from '@nimbus-sh/fabric/budgets.js';
+import { HOSTED_WEBSOCKET_CAPABILITY_HEADER, HOSTED_WEBSOCKET_KEY_HEADER, } from '@nimbus-sh/fabric/process-host.js';
+import { routeHostedWebSocket } from './rpc.js';
+import { clearPortCapability, persistPortCapability, readPortCapability, restorePortCapability, } from './port-capability.js';
+import { PREVIEW_CAPABILITY_HEADER } from '../_shared/session-router.js';
 import { renderNoDevServerHtml } from './helpers.js';
 import { handleAgentRequest } from './agent.js';
 import { captureSessionAiCredential } from './ai.js';
@@ -50,7 +57,7 @@ import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
 // uses (they did: the packument purge used a stale `/p/` segment).
 import { R2CacheClient, packumentL2Url, tarballL2Url, parseTarballAddress } from '../npm/r2-cache.js';
 import { fetchEsbuildWasmBytes, ESBUILD_WASM_L2_KEY } from '../runtime/esbuild-wasm-bytes.js';
-import { NimbusFanoutPool, IN_DO_THRESHOLD, MAX_PEER_FANOUT } from '../loaders/fanout-pool.js';
+import { Fanout, IN_DO_THRESHOLD, MAX_PEER_FANOUT } from '@nimbus-sh/fabric/fanout.js';
 import { z } from 'zod/v4';
 const TestSpawnEmitterBodySchema = z.object({
     lines: z.coerce.number().optional(),
@@ -105,6 +112,9 @@ async function restorePersistedDevServer(self, onlyPort) {
         const port = (config.port && Number.isFinite(config.port)) ? config.port : DEFAULT_VITE_PORT;
         if (onlyPort != null && onlyPort !== port)
             return;
+        // Read BEFORE the restore: bringing the server back re-registers the port,
+        // and a fresh registration mints a capability nobody was ever handed.
+        const persistedCapability = await readPortCapability(self, port);
         // A cirrus-real session rebuilds the real-vite facet, not the Cirrus shim —
         // same key, same starter the `vite` builtin uses, so a woken real-vite
         // session comes back as real-vite rather than degrading to the shim.
@@ -125,6 +135,7 @@ async function restorePersistedDevServer(self, onlyPort) {
                 configDir: config.configDir || config.root,
             }).finally(() => { self._realViteRestore = null; });
             await self._realViteRestore;
+            await readoptCapability(self, port, persistedCapability);
             return;
         }
         self.ensureSqliteFs();
@@ -155,7 +166,9 @@ async function restorePersistedDevServer(self, onlyPort) {
         // restored server across hibernation cycles.
         try {
             self.portRegistry.bindFacetStub(entry.pid, makeLongRunningPortStub(self.viteDevServer));
+            await clearPortCapability(self, port);
             self.portRegistry.register(port, entry.pid);
+            await readoptCapability(self, port, persistedCapability);
             self._viteShimPid = entry.pid;
             self._viteShimPort = port;
         }
@@ -179,8 +192,18 @@ async function restorePersistedDevServer(self, onlyPort) {
  * the untrusted-code boundary and cannot carry it, and a plain user server on
  * any other port is mounted at root and needs no rewriting.
  */
-async function routeToSessionPort(self, port, request, innerPath, mountBase) {
+async function routeToSessionPort(self, port, request, innerPath, mountBase, capability) {
     await restorePersistedDevServer(self, port);
+    if (capability !== undefined) {
+        // A rebuilt supervisor holds a capability nobody was handed; the durable
+        // one is the value in circulation, so it wins before the check.
+        await restorePortCapability(self, port);
+        if (!self.portRegistry.hasCapability(port, capability)) {
+            // 404, not 403: a wrong capability must not confirm that the port is
+            // listening at all.
+            return new Response('Not found', { status: 404 });
+        }
+    }
     if (port === self._viteShimPort) {
         // The preview HMR WebSocket can't cross the port-registry RPC, so it is
         // accepted in-DO for both dev servers — the same handling `/preview/` uses.
@@ -193,11 +216,28 @@ async function routeToSessionPort(self, port, request, innerPath, mountBase) {
             return self.viteDevServer.handleRequest(request, innerPath, mountBase);
         }
     }
-    const proxied = await self.portRegistry.routeRequest(port, request, innerPath);
+    const proxied = capability === undefined
+        ? await self.portRegistry.routeRequest(port, request, innerPath)
+        : await self.portRegistry.routeCapabilityRequest(port, capability, request, innerPath);
     if (proxied)
         return proxied;
     return new Response(`No process listening on port ${port}`, { status: 502 });
 }
+/**
+ * Re-adopt a preview capability the embedder already holds, after a restore
+ * re-registered the port under a freshly minted one.
+ */
+async function readoptCapability(self, port, capability) {
+    if (!capability)
+        return;
+    if (self.portRegistry.restoreCapability(port, capability)) {
+        await persistPortCapability(self, port, capability);
+    }
+}
+/** Route a capability-authenticated embedder request to a guest HTTP server. */
+export function routeCapabilityPort(self, port, capability, request, innerPath) {
+    return routeToSessionPort(self, port, request, normalizeForwardedHttpPath(innerPath), '', capability);
+}
 /**
  * The public URL prefix a port-routed request is mounted at. `<port>--<sid>`
  * hosts arrive with an empty base header (mounted at the origin root); the
@@ -294,6 +334,23 @@ async function parseJsonBody(request, schema) {
 }
 export async function handleFetch(self, request) {
     const url = new URL(request.url);
+    // The peer end of the fetch-semantic WebSocket hop, before anything else:
+    // this request is a sibling coordinator's, not a browser's, and it names
+    // the hosted process rather than a route on this session. Both headers are
+    // stripped so the process never sees the transport that carried it.
+    const hostedWebSocket = request.headers.get(HOSTED_WEBSOCKET_KEY_HEADER);
+    if (hostedWebSocket) {
+        if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+            return new Response('Expected WebSocket', { status: 426 });
+        }
+        const capability = request.headers.get(HOSTED_WEBSOCKET_CAPABILITY_HEADER);
+        if (!capability)
+            return new Response('Not found', { status: 404 });
+        const headers = new Headers(request.headers);
+        headers.delete(HOSTED_WEBSOCKET_KEY_HEADER);
+        headers.delete(HOSTED_WEBSOCKET_CAPABILITY_HEADER);
+        return routeHostedWebSocket(self, hostedWebSocket, capability, new Request(request.url, { method: request.method, headers }));
+    }
     // Capture session basePath from the routing header (if forwarded by the
     // Worker's session-router). Threaded through to ViteDevServer so the
     // served app's module URLs, HMR paths, <base href>, and router basename
@@ -584,7 +641,7 @@ export async function handleFetch(self, request) {
     // process.memoryUsage() and they were always zero — useless.
     //
     // C'.1 replaces the zero-everywhere readout with a deterministic
-    // estimator (src/observability/heap-estimate.ts) that sums known
+    // estimator (src/@nimbus-sh/platform/heap-estimate.js) that sums known
     // supervisor allocations from runtime counters. Every byte has a
     // named contributor.
     //
@@ -666,11 +723,19 @@ export async function handleFetch(self, request) {
             // (32 entries) with FIFO eviction. The counters here let
             // ops dashboards visualise the bound + the eviction rate.
             loadedCodes: getLoadedCodesStats(),
+            // Per-DO Worker Loader accounting: distinct loader ids ever gotten
+            // (each permanently holds one of the ~5-6 dynamic-worker slots) and
+            // live/peak concurrent Loader fetches.
+            loader: loaderLedgerStats(self.ctx),
             rpc: {
                 lastFrame: getLastRpcFrame(),
             },
             facet: {
                 lastDispatch: getLastFacetId(),
+                // Facet IDs consumed over this DO's LIFETIME against the 65,536 the
+                // platform will ever grant it. Append-only and never reclaimed;
+                // crossing the wall is unrecoverable for the object.
+                idBudget: await facetIdBudget(self.ctx),
             },
             // ── v3 / C' observability foundation ──────────────────────
             heap,
@@ -685,7 +750,7 @@ export async function handleFetch(self, request) {
             // `autoResponseConfigured` reports the runtime's actual
             // capability (older workerd builds report false).
             hib: {
-                isolateGen: self._w9IsolateGen,
+                isolateGen: generation(self.ctx),
                 autoResponseConfigured: self._w9WsConfig?.autoResponseConfigured ?? false,
                 autoResponseError: self._w9WsConfig?.autoResponseError ?? null,
                 hibernationEventTimeoutMs: self._w9WsConfig?.timeoutSetMs ?? null,
@@ -852,7 +917,7 @@ export async function handleFetch(self, request) {
                 fromState: body.fromState,
                 toState: body.toState,
                 trigger: body.trigger,
-                isolateGen: body.isolateGen || self._w9IsolateGen,
+                isolateGen: body.isolateGen || generation(self.ctx),
                 dataLoss: body.dataLoss === true,
                 snapshotKeysRehydrated: body.snapshotKeysRehydrated || 0,
                 notes: body.notes,
@@ -890,7 +955,7 @@ export async function handleFetch(self, request) {
         }
         // ── two-tier-fanout primitive probe ──────────────────────────────
         // in-DO fanout in-DO and peer-DO fanout peer-DO speedups via the
-        // NimbusFanoutPool primitive. Independent of any specific
+        // Fanout primitive. Independent of any specific
         // production site (install-batch, pre-bundle, etc.) so the
         // primitive's behavior can be measured cleanly without
         // confounders.
@@ -1016,6 +1081,7 @@ export async function handleFetch(self, request) {
             try {
                 const apiViteStub = makeLongRunningPortStub(self.viteDevServer);
                 self.portRegistry.bindFacetStub(apiViteEntry.pid, apiViteStub);
+                await clearPortCapability(self, apiVitePort);
                 self.portRegistry.register(apiVitePort, apiViteEntry.pid);
                 self._viteShimPid = apiViteEntry.pid;
                 self._viteShimPort = apiVitePort;
@@ -1220,7 +1286,10 @@ export async function handleFetch(self, request) {
     if (portMatch) {
         const port = parseInt(portMatch[1]);
         const path = normalizeForwardedHttpPath(portMatch[2] || '/');
-        return routeToSessionPort(self, port, request, path, portRouteMountBase(request, port));
+        // An embedder that authenticated a preview capability at its own edge
+        // forwards it here; the guest's Authorization then survives the hop.
+        const capability = request.headers.get(PREVIEW_CAPABILITY_HEADER);
+        return routeToSessionPort(self, port, request, path, portRouteMountBase(request, port), capability ?? undefined);
     }
     // ── /api/_diag/cache — per-tier cache observability ───────────────
     //
@@ -1240,7 +1309,12 @@ export async function handleFetch(self, request) {
         const { readExecTelemetry } = await import('../facets/exec-telemetry.js');
         return Response.json({ records: readExecTelemetry() });
     }
+    // Write surfaces gated like /api/_test/*: zeroing telemetry from prod
+    // would erase the evidence an investigation is standing on, so without
+    // NIMBUS_DEBUG these 404 rather than being a free reset vector.
     if (url.pathname === '/api/_diag/exec/reset' && request.method === 'POST') {
+        if (!self.nimbusDebug)
+            return new Response('not found', { status: 404 });
         const { resetExecTelemetry } = await import('../facets/exec-telemetry.js');
         resetExecTelemetry();
         return new Response(null, { status: 204 });
@@ -1251,6 +1325,8 @@ export async function handleFetch(self, request) {
         return Response.json(snap);
     }
     if (url.pathname === '/api/_diag/cache/reset' && request.method === 'POST') {
+        if (!self.nimbusDebug)
+            return new Response('not found', { status: 404 });
         const { reset } = await import('@nimbus-sh/core/_shared/cache-stats.js');
         reset();
         return new Response(null, { status: 204 });
@@ -1396,7 +1472,7 @@ async function handleCacheTestEndpoint(self, url, request) {
 }
 // ── two-tier-fanout primitive benchmark endpoint ────────────────────────
 //
-// Routes under /api/_test/fanout/* exercise NimbusFanoutPool's two
+// Routes under /api/_test/fanout/* exercise Fanout's two
 // topologies (in-DO fanout in-DO + peer-DO fanout peer-DO) via a synthetic workload
 // that's independent of the production install-batch / pre-bundle
 // sites. The probe measures speedup, peer-DO routing determinism,
@@ -1425,7 +1501,7 @@ async function handleFanoutTestEndpoint(self, url, request) {
     const path = url.pathname;
     if (path === '/api/_test/fanout/topology' && request.method === 'GET') {
         const n = Math.max(0, parseInt(url.searchParams.get('n') || '0', 10));
-        const pool = new NimbusFanoutPool(env, self.ctx, {
+        const pool = new Fanout(env, self.ctx, {
             tag: 'fanout-bench',
             timeoutMs: 60_000,
         });
@@ -1440,7 +1516,7 @@ async function handleFanoutTestEndpoint(self, url, request) {
         const keysRaw = url.searchParams.get('keys') || '';
         const keys = keysRaw.split(',').map((k) => k.trim()).filter(Boolean);
         const peerCount = Math.max(1, Math.min(parseInt(url.searchParams.get('n') || String(keys.length), 10), MAX_PEER_FANOUT));
-        const pool = new NimbusFanoutPool(env, self.ctx, {
+        const pool = new Fanout(env, self.ctx, {
             tag: 'fanout-bench',
             timeoutMs: 60_000,
         });
@@ -1454,7 +1530,7 @@ async function handleFanoutTestEndpoint(self, url, request) {
         const body = await parseJsonBody(request, FanoutBenchBodySchema);
         const n = Math.max(1, Math.min(64, body.n || 8));
         const sleepMs = Math.max(0, Math.min(2000, body.sleepMs || 100));
-        const pool = new NimbusFanoutPool(env, self.ctx, {
+        const pool = new Fanout(env, self.ctx, {
             tag: 'fanout-bench',
             timeoutMs: 60_000,
         });
@@ -1470,7 +1546,7 @@ async function handleFanoutTestEndpoint(self, url, request) {
         const results = await pool.submitMany(tasks, async (item, env) => {
             const startMs = Date.now();
             // Identify which env we're running in. SUPERVISOR is the
-            // RPC stub auto-injected by NimbusLoaderPool; its presence
+            // RPC stub auto-injected by IsolatePool; its presence
             // tells us we're inside a loader isolate (not the supervisor).
             const loaderEnvKeys = Object.keys(env || {}).sort();
             // Sleep entirely inside the isolate — no external network.
@@ -1510,11 +1586,11 @@ async function handleFanoutTestEndpoint(self, url, request) {
         const n = Math.max(1, Math.min(64, body.n || 8));
         const sleepMs = Math.max(0, Math.min(2000, body.sleepMs || 100));
         // Same workload, but FORCE serial dispatch by using a single
-        // NimbusLoaderPool with concurrency=1 and submitting one task
+        // IsolatePool with concurrency=1 and submitting one task
         // at a time. This is the T_serial reference for the 5× speedup
         // assertion.
-        const { NimbusLoaderPool } = await import('../loaders/loader-pool.js');
-        const pool = new NimbusLoaderPool(env, self.ctx, {
+        const { IsolatePool } = await import('@nimbus-sh/fabric/isolate-pool.js');
+        const pool = new IsolatePool(env, self.ctx, {
             concurrency: 1,
             timeoutMs: 60_000,
             tag: 'fanout-serial',