@nimbus-sh/worker 0.2.2 → 0.3.0

package/dist/session/hibernation.js

@@ -18,11 +18,15 @@
  *     w9_proc_logs + w9_proc_exits.
  *   - scheduleHibFlush(host, ctx) — debounced setTimeout + best-effort
  *     setAlarm for post-hibernation drain.
- *   - dispatchAlarm(host) — alarm() handler body.
- *   - maybeBumpIsolateGen(host, ctx) — increment + persist isolate-gen
- *     counter once per fresh isolate.
+ *   - dispatchAlarm(host) — alarm() handler body: the fabric's generic
+ *     reason dispatcher with this session's handlers registered.
  *   - flushOnClose(host) — synchronous flush on ws close.
  *
+ * The alarm multiplexer itself (reason map, scheduleAlarm, the per-instance
+ * chain) and maybeBumpIsolateGen are fabric machinery —
+ * `@nimbus-sh/fabric/alarms.js`; this module registers the session's reasons
+ * ('w9-flush' | 'log-janitor' | 'resident-launch') on top of it.
+ *
  * **`ctx` taken as a separate arg from `host`** because the parent
  * `CloudflareDurableObject` class declares `ctx` as `protected`, which
  * is nominal-typed in TS and cannot appear on a public interface
@@ -34,8 +38,9 @@
  * responsible for setting `host._w9PersistWired = false` BEFORE calling
  * wireProcessLogPersist again.
  */
-import { configureWsHibernation } from './ws-hibernation-config.js';
-import { SESSION_DESTROYED_KEY, W9_ISOLATE_GEN_KEY, W9_FLUSH_DEBOUNCE_MS, W1_NEXT_ALARM_REASONS_KEY } from './keys.js';
+import { configureWsHibernation } from '@nimbus-sh/fabric/ws-hibernation-config.js';
+import { dispatchAlarm as dispatchAlarmReasons, scheduleAlarm, } from '@nimbus-sh/fabric/alarms.js';
+import { SESSION_DESTROYED_KEY, W9_FLUSH_DEBOUNCE_MS } from './keys.js';
 /**
  * Run at DO ctor time. Returns the result for the class to assign to
  * `_w9WsConfig`. Failures are non-fatal — older workerd builds may lack
@@ -241,59 +246,6 @@ export function ensureHibSchema(host, ctx) {
         host._w9SchemaInit = false; // retry next time
     }
 }
-/**
- * W1: schedule (or re-schedule) an alarm reason. Coordinated via a
- * single map in DO storage so multiple subsystems (W9 debounced flush +
- * W1 log-janitor sweep) don't clobber each other's `setAlarm()` calls.
- *
- * Semantics:
- *   - Reads the existing reasons map.
- *   - Sets `map[reason] = whenMs` IF `whenMs` is sooner than the
- *     currently-pending deadline for that reason (or no entry exists).
- *     Later-than-pending requests are silently ignored — the existing
- *     alarm will fire and re-arm anyway.
- *   - Writes the map back and calls `ctx.storage.setAlarm(min(deadlines))`.
- *
- * Cost: 1 storage read + 1 storage write + 1 setAlarm per call. setAlarm
- * itself is billed as 1 row written per DO pricing. At W1's 60s
- * cadence, this is ~$0.05/mo/session at scale — dwarfed by the
- * hibernation duration savings.
- *
- * Fail-soft: any throw is swallowed with a warn. On older runtimes /
- * wrangler-dev where setAlarm is unavailable, this is a no-op (the
- * subsystem's in-isolate setTimeout fallback continues to work).
- */
-export function scheduleAlarm(host, ctx, reason, whenMs) {
-    // Serialize every read-modify-write of the reasons map through one
-    // per-instance chain: scheduleHibFlush and ensureLogJanitor fire
-    // back-to-back from the same log-activity hook, and two interleaved
-    // get→put cycles would silently drop whichever reason wrote first.
-    const run = async () => {
-        try {
-            const setAlarmFn = ctx?.storage?.setAlarm;
-            if (typeof setAlarmFn !== 'function')
-                return false;
-            const existing = (await ctx.storage.get(W1_NEXT_ALARM_REASONS_KEY));
-            const map = { ...(existing || {}) };
-            // Earliest-deadline-first: only update if new request is sooner or
-            // this reason has no pending entry.
-            if (!(reason in map) || whenMs < map[reason]) {
-                map[reason] = whenMs;
-                await ctx.storage.put(W1_NEXT_ALARM_REASONS_KEY, map);
-            }
-            const earliest = Math.min(...Object.values(map));
-            setAlarmFn.call(ctx.storage, earliest);
-            return true;
-        }
-        catch (e) {
-            console.warn('[nimbus/W1] scheduleAlarm threw:', e?.message);
-            return false;
-        }
-    };
-    const chained = (host._w1AlarmChain ?? Promise.resolve()).then(run, run);
-    host._w1AlarmChain = chained;
-    return chained;
-}
 /**
  * W9: ensure the alarm is set for the next flush window. Cheap to
  * call repeatedly — we only schedule the in-isolate flush timer if
@@ -325,148 +277,59 @@ export function scheduleHibFlush(host, ctx) {
     void scheduleAlarm(host, ctx, 'w9-flush', Date.now() + W9_FLUSH_DEBOUNCE_MS * 4);
 }
 /**
- * W1: multi-reason alarm dispatcher. Called from the DO's `alarm()`
- * handler.
- *
- * For each pending reason whose deadline has passed, run its handler.
- * Reasons supported today:
+ * W1: this session's alarm() handler body — the fabric's multi-reason
+ * dispatcher with this session's handlers registered:
  *   - `'w9-flush'` → processes.flushLogs()
+ *   - `'resident-launch'` → pumpResidentLaunches()
  *   - `'log-janitor'` → processes.dropLogsOlderThan(orphanCheck); re-arm
- *     for next 60s cycle.
+ *     for next 60s cycle while the session still has anything to sweep.
  *
  * `janitorOrphanCheck` is the orphan-pid predicate provided by the
  * caller (typically `(pid) => !host.processes.get(pid)`). Decoupled
  * so HibHost doesn't need to import ProcessTable.
- *
- * After running fireable reasons, re-arms `ctx.storage.setAlarm` at the
- * earliest remaining deadline. If no reasons remain, deletes the map
- * key and does NOT call setAlarm — the DO becomes hibernation-eligible
- * after the 10s idle window.
- *
- * Forward/back-compat: unknown reasons silently dropped.
  */
 export function dispatchAlarm(host, ctx, janitorOrphanCheck, pumpResidentLaunches) {
-    // Same serialization as scheduleAlarm: the dispatcher's read→handlers→write
-    // cycle must not interleave with a log-activity scheduleAlarm.
-    const chained = (host._w1AlarmChain ?? Promise.resolve()).then(() => dispatchAlarmBody(host, ctx, janitorOrphanCheck, pumpResidentLaunches), () => dispatchAlarmBody(host, ctx, janitorOrphanCheck, pumpResidentLaunches));
-    host._w1AlarmChain = chained;
-    return chained;
-}
-async function dispatchAlarmBody(host, ctx, janitorOrphanCheck, pumpResidentLaunches) {
-    try {
-        const now = Date.now();
-        const existing = (await ctx?.storage?.get?.(W1_NEXT_ALARM_REASONS_KEY));
+    return dispatchAlarmReasons(host, ctx, {
+        'w9-flush': () => {
+            host.processes.flushLogs();
+        },
+        'resident-launch': async () => {
+            // Awaited, not fired and forgotten: this invocation is the fresh
+            // turn the launch asked for, and it has to stay the one paying for
+            // the chunk it just released.
+            await pumpResidentLaunches?.();
+        },
+        'log-janitor': (now) => {
+            host.processes.dropLogsOlderThan(undefined, janitorOrphanCheck);
+            // Re-arm only while the session still has running processes or
+            // buffered logs to sweep. An idle, abandoned, or destroyed
+            // session must NOT keep an eternal 60s alarm loop alive: the
+            // janitor used to self-renew unconditionally (and the DO
+            // constructor re-armed it on every alarm-triggered boot), so
+            // every session ever created kept booting its DO every ~60s
+            // forever. The accumulated fleet of deleted probe sessions
+            // produced continuous DO-storage churn (measured ~24 zombie
+            // boots/s on 2026-07-13) that intermittently reset LIVE
+            // session DOs mid-run ("Internal error in Durable Object
+            // storage caused object to be reset"). The next log append
+            // re-arms the cycle via ensureLogJanitor.
+            if (host.processes.stats.running > 0 || host.processes.logStats.totalPids > 0) {
+                return { rearmAt: now + 60_000 };
+            }
+            host._w1JanitorArmed = false;
+        },
+    }, () => {
         // Legacy path: pre-W1 deploys had no map. dispatchAlarm was called
         // with no map and unconditionally ran the log flush. Preserve
         // that on a missing map (one-time post-deploy, then the map is
         // populated by the next scheduleHibFlush / scheduleAlarm call).
-        if (!existing || Object.keys(existing).length === 0) {
-            try {
-                host.processes.flushLogs();
-            }
-            catch (e) {
-                console.warn('[nimbus/W9] legacy flush threw:', e?.message);
-            }
-            return;
-        }
-        const map = { ...existing };
-        // Snapshot fireable reasons BEFORE running any of them, so a
-        // handler that schedules itself for the next cycle doesn't get
-        // immediately re-fired in the same dispatch.
-        const fired = [];
-        for (const [reason, when] of Object.entries(map)) {
-            if (when <= now)
-                fired.push(reason);
-        }
-        for (const reason of fired) {
-            delete map[reason];
-            try {
-                if (reason === 'w9-flush') {
-                    host.processes.flushLogs();
-                }
-                else if (reason === 'resident-launch') {
-                    // Awaited, not fired and forgotten: this invocation is the fresh
-                    // turn the launch asked for, and it has to stay the one paying for
-                    // the chunk it just released.
-                    await pumpResidentLaunches?.();
-                }
-                else if (reason === 'log-janitor') {
-                    host.processes.dropLogsOlderThan(undefined, janitorOrphanCheck);
-                    // Re-arm only while the session still has running processes or
-                    // buffered logs to sweep. An idle, abandoned, or destroyed
-                    // session must NOT keep an eternal 60s alarm loop alive: the
-                    // janitor used to self-renew unconditionally (and the DO
-                    // constructor re-armed it on every alarm-triggered boot), so
-                    // every session ever created kept booting its DO every ~60s
-                    // forever. The accumulated fleet of deleted probe sessions
-                    // produced continuous DO-storage churn (measured ~24 zombie
-                    // boots/s on 2026-07-13) that intermittently reset LIVE
-                    // session DOs mid-run ("Internal error in Durable Object
-                    // storage caused object to be reset"). The next log append
-                    // re-arms the cycle via ensureLogJanitor.
-                    if (host.processes.stats.running > 0 || host.processes.logStats.totalPids > 0) {
-                        map['log-janitor'] = now + 60_000;
-                    }
-                    else {
-                        host._w1JanitorArmed = false;
-                    }
-                }
-                // Unknown reasons silently dropped (forward-compat).
-            }
-            catch (e) {
-                console.warn(`[nimbus/W1] dispatch ${reason} threw:`, e?.message);
-            }
-        }
-        // Re-arm or clear.
-        const setAlarmFn = ctx?.storage?.setAlarm;
-        if (Object.keys(map).length > 0) {
-            await ctx.storage.put(W1_NEXT_ALARM_REASONS_KEY, map);
-            const earliest = Math.min(...Object.values(map));
-            if (typeof setAlarmFn === 'function') {
-                setAlarmFn.call(ctx.storage, earliest);
-            }
+        try {
+            host.processes.flushLogs();
         }
-        else {
-            try {
-                await ctx.storage.delete(W1_NEXT_ALARM_REASONS_KEY);
-            }
-            catch { }
-            // No remaining reasons → no setAlarm call → DO becomes
-            // hibernation-eligible after the 10s idle window.
+        catch (e) {
+            console.warn('[nimbus/W9] legacy flush threw:', e?.message);
         }
-    }
-    catch (e) {
-        console.warn('[nimbus/W1] dispatchAlarm threw:', e?.message);
-    }
-}
-/** W9: increment + persist isolate-gen counter once per fresh isolate. */
-export async function maybeBumpIsolateGen(host, ctx) {
-    if (host._w9IsolateGenPersisted)
-        return;
-    host._w9IsolateGenPersisted = true;
-    try {
-        const prev = (await ctx.storage.get(W9_ISOLATE_GEN_KEY));
-        // Adopt the persisted truth first, and adopt the bump only after the
-        // put resolves. An unpersisted `next` would be re-read as `prev` by the
-        // NEXT boot and re-issued — two instances sharing one generation is
-        // exactly the pid-aliasing this counter exists to prevent. Running on
-        // the previous persisted generation is the lesser lapse, and the
-        // put-failure case is replica-only in practice (replicas never spawn).
-        //
-        // What holds the guarantee is the output gate, not this await: measured,
-        // the block body resolves in 0 ms even with a confirmed put, because
-        // `await storage.put()` returns before durability. The gate is what
-        // keeps a pid from generation N from escaping before N is durable, which
-        // is why marking this put `allowUnconfirmed` is not a free speedup — see
-        // scratchpad/coldstart-s1.md.
-        host._w9IsolateGen = typeof prev === 'number' ? prev : 0;
-        const next = host._w9IsolateGen + 1;
-        await ctx.storage.put(W9_ISOLATE_GEN_KEY, next);
-        host._w9IsolateGen = next;
-    }
-    catch (e) {
-        console.warn('[nimbus/W9] isolate-gen bump failed:', e?.message);
-    }
+    });
 }
 /**
  * W9: synchronous flush of the process-log ring on session close.

package/dist/session/init-phases.d.ts

@@ -40,7 +40,7 @@ import { type SessionState } from '@nimbus-sh/core/observability/oom-discriminat
  */
 export declare function setPhase(self: {
     _b4Phase: SessionState | null;
-    _w9IsolateGen?: number;
+    _isolateGen?: number;
 }, toState: SessionState, trigger: string): void;
 /**
  * [B'.5] Identify the original phase-based warm-rejoin case. The /ws
@@ -93,7 +93,7 @@ export declare function joinExistingSession(self: {
         write(s: string): void;
     };
     _b4Phase: SessionState | null;
-    _w9IsolateGen?: number;
+    _isolateGen?: number;
     _b4WarmJoinCount: number;
 }, ws: WebSocket, appendScrollback: (ctx: any, data: string, atMs: number) => void, loadScrollback: (ctx: any) => string): void;
 export {};

package/dist/session/init-phases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-phases.d.ts","sourceRoot":"","sources":["../../src/session/init-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,oDAAoD,CAAC;AAE5G;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE;IAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/D,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,GACd,IAAI,CAcN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;CACxC,GAAG,OAAO,CAKV;AAED,KAAK,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,EAAE,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,iBAAiB,CAmBnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE;IACJ,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE;QAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpG,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,EACD,EAAE,EAAE,SAAS,EACb,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,EAChE,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GACnC,IAAI,CAsCN"}
+{"version":3,"file":"init-phases.d.ts","sourceRoot":"","sources":["../../src/session/init-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,oDAAoD,CAAC;AAE5G;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE;IAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7D,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,GACd,IAAI,CAcN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;CACxC,GAAG,OAAO,CAKV;AAED,KAAK,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,EAAE,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,iBAAiB,CAmBnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE;IACJ,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE;QAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpG,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,EACD,EAAE,EAAE,SAAS,EACb,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,EAChE,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GACnC,IAAI,CAsCN"}

package/dist/session/init-phases.js

@@ -47,7 +47,7 @@ export function setPhase(self, toState, trigger) {
             fromState,
             toState,
             trigger,
-            isolateGen: self._w9IsolateGen ?? 0,
+            isolateGen: self._isolateGen ?? 0,
             dataLoss: false,
             snapshotKeysRehydrated: 0,
         });

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/session/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA6EH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,KAAK,QAAQ,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;CAAE,CAAC;AAa3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAsrF9E"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/session/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA8EH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,KAAK,QAAQ,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;CAAE,CAAC;AAa3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAosF9E"}

package/dist/session/init.js

@@ -76,6 +76,7 @@ import { sessionAiEnv } from './ai.js';
 import { routeSessionLoopback } from './loopback.js';
 import { setPhase } from './init-phases.js';
 import { VITE_CONFIG_KEY } from './keys.js';
+import { clearPortCapability } from './port-capability.js';
 function resolveNpmPrefix(prefix, cwd) {
     return prefix.startsWith('/')
         ? normalizeVfsPath(prefix)
@@ -164,6 +165,17 @@ export async function initSession(self, ws) {
         self.terminal.write('\x1b[33m[nimbus] this session resumed on a new instance. Anything still '
             + 'running was lost with the old one — re-run it if it had not finished.\x1b[0m\r\n');
     }
+    // A reset that killed a resident launch left its journal row behind
+    // (fabric's ResidentLaunchJournal.recoverInterrupted). The alarm the dying
+    // instance was using for launch turns is NOT a trigger recovery can rely
+    // on — measured live, a launch killed early in its first chunks rolls the
+    // alarm-map put back with the rest of the dying turn, so the replacement
+    // instance never fires an alarm at all. What always follows a dead session
+    // is this reconnect, so recovery runs here: after the terminal exists (the
+    // report lands in front of the user, live) and after the constructor's
+    // pidBase gate (the journal predicate needs this instance's generation).
+    // Idempotent per instance; a no-op whenever no launch was interrupted.
+    await self.facetManager.pumpResidentLaunches();
     // [B'.4] Phase B — Build. Compose the workspace (kernel + mounts +
     // shell + the OS command set), then install the session's own
     // commands and wiring on top. CPU-intensive phase. Spans from here
@@ -469,7 +481,7 @@ export async function initSession(self, ws) {
     registerRunnerFactory('cpython-runner', (manifest, installRoot, binName, binKind) => async function pythonReplOrOneShot(ctx) {
         const argv = ctx.args || [];
         // No args at all → REPL session. Hand off to runPythonRepl
-        // which builds its own NimbusLoaderPool (separate from the
+        // which builds its own LoaderPool (separate from the
         // one-shot dispatch's pool) and drives a ReplSession.
         if (argv.length === 0 && self.terminal) {
             const { runPythonRepl } = await import('../runtime/python-repl.js');
@@ -1232,6 +1244,7 @@ export async function initSession(self, ws) {
             try {
                 const previewStub = makeLongRunningPortStub(self.viteDevServer);
                 self.portRegistry.bindFacetStub(previewProcEntry.pid, previewStub);
+                await clearPortCapability(self, previewPort);
                 self.portRegistry.register(previewPort, previewProcEntry.pid);
                 self._viteShimPid = previewProcEntry.pid;
                 self._viteShimPort = previewPort;
@@ -1446,6 +1459,7 @@ export async function initSession(self, ws) {
         // facet uses (Express, Bun.serve, http.createServer().listen()).
         const viteStub = makeLongRunningPortStub(self.viteDevServer);
         self.portRegistry.bindFacetStub(viteProcEntry.pid, viteStub);
+        await clearPortCapability(self, resolvedPort);
         self.portRegistry.register(resolvedPort, viteProcEntry.pid);
         // Track the wiring so `vite stop` and crash-handlers can tear it
         // down without searching the registry.
@@ -2691,7 +2705,7 @@ export async function initSession(self, ws) {
                 fromState: fromState,
                 toState: 'hydrated',
                 trigger: 'init-session',
-                isolateGen: self._w9IsolateGen,
+                isolateGen: self._isolateGen,
                 dataLoss: false,
                 snapshotKeysRehydrated: snapshotKeys,
             });

package/dist/session/keys.d.ts

@@ -17,9 +17,6 @@
  *   These keys persist DO state across deploys. Renaming any key is a
  *   storage migration — never do it without an explicit migration plan.
  */
-/** W9: storage key for the isolate-generation counter (cold-start +
- *  post-hibernation wake; one increment per fresh isolate). */
-export declare const W9_ISOLATE_GEN_KEY = "w9_isolate_gen";
 /** W9: debounce window in ms before flushing pending process-log writes
  *  to SQL. Hot path (every append schedules a flush via this debounce). */
 export declare const W9_FLUSH_DEBOUNCE_MS = 250;
@@ -34,25 +31,6 @@ export declare const SESSION_BASE_PATH_KEY = "session-base-path";
  *  hibernation so vite resumes serving after wake without re-running
  *  /api/start-vite. */
 export declare const VITE_CONFIG_KEY = "vite-config";
-/** W1: multi-reason alarm coordination map.
- *
- *  JSON-serialised `Record<reason, deadlineMsEpoch>` where keys are
- *  canonical reason strings (e.g. 'w9-flush', 'log-janitor'). The
- *  alarm() dispatcher reads this on fire, dispatches every reason
- *  whose deadline has passed, and re-arms `ctx.storage.setAlarm` at
- *  the earliest remaining deadline.
- *
- *  Why a map (not a single nextAlarmAt + reason): two subsystems
- *  (W9 debounced flush + W1 log-janitor sweep) can have distinct
- *  deadlines. Without the map, the later setAlarm() call would
- *  overwrite the earlier reason silently, breaking whichever
- *  subsystem expected its deadline.
- *
- *  Forward-compat: dispatcher silently drops unknown reasons so a
- *  rollback from a future deploy that added new reasons doesn't
- *  leave the alarm stuck.
- */
-export declare const W1_NEXT_ALARM_REASONS_KEY = "w1_next_alarm_reasons";
 /**
  * Destroyed-session tombstone. Written AFTER `storage.deleteAll()` in the
  * destroy flow so a straggler facet RPC that wakes the dead DO cannot re-arm
@@ -60,22 +38,23 @@ export declare const W1_NEXT_ALARM_REASONS_KEY = "w1_next_alarm_reasons";
  * metadata is the deliberate cost of keeping destroyed sessions inert.
  */
 export declare const SESSION_DESTROYED_KEY = "session_destroyed";
-/**
- * Prefix for the resident-launch journal: one row per launch in flight, keyed
- * by the pid it is building for.
- *
- * A launch spans many turns and holds its state in memory, so an instance
- * reset destroys it silently — the process, the terminal and the work all go
- * with the object. The row is what a LATER instance reads to know a launch
- * ended that way rather than by finishing: a pid at or below the reader's own
- * pid base was allocated by a previous generation (see PID_GEN_STRIDE).
- * Written before the launch's first byte of work and removed when it settles,
- * so a row that outlives its instance is exactly an interrupted launch.
- */
-export declare const RESIDENT_LAUNCH_KEY_PREFIX = "resident-launch:";
 /** Prefix for consumed single-use attach bootstrap token ids (`jti`).
  *  Written set-if-absent by `_rpcConsumeAttachBootstrap` on the attach
  *  exchange; an existing row means the bootstrap URL was replayed.
  *  Bounded: at most one row per `POST /new` bootstrap actually attached. */
 export declare const ATTACH_BOOTSTRAP_JTI_KEY_PREFIX = "attach-bootstrap-jti:";
+/**
+ * Prefix for a port's durable preview capability, keyed by port number. The
+ * registry mints the value in memory per registration; this is what lets a
+ * preview URL the embedder was already handed survive a rebuild. Owned by
+ * `session/port-capability.ts`, which is the only module that reads or writes
+ * these rows.
+ */
+export declare const PORT_CAPABILITY_KEY_PREFIX = "nimbus_preview_capability:";
+/**
+ * Prefix for a named programmatic shell's durable cwd+env, keyed by shell id.
+ * One row per id the embedder has actually used; bounded by the embedder's own
+ * naming, the way a terminal tab is.
+ */
+export declare const SHELL_STATE_KEY_PREFIX = "nimbus_programmatic_shell:";
 //# sourceMappingURL=keys.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/session/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;+DAC+D;AAC/D,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;2EAC2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;yDAEyD;AACzD,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD;0DAC0D;AAC1D,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;uBAEuB;AACvB,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAE7D;;;4EAG4E;AAC5E,eAAO,MAAM,+BAA+B,0BAA0B,CAAC"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/session/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;2EAC2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;yDAEyD;AACzD,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD;0DAC0D;AAC1D,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;uBAEuB;AACvB,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;;4EAG4E;AAC5E,eAAO,MAAM,+BAA+B,0BAA0B,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC"}

package/dist/session/keys.js

@@ -17,9 +17,9 @@
  *   These keys persist DO state across deploys. Renaming any key is a
  *   storage migration — never do it without an explicit migration plan.
  */
-/** W9: storage key for the isolate-generation counter (cold-start +
- *  post-hibernation wake; one increment per fresh isolate). */
-export const W9_ISOLATE_GEN_KEY = 'w9_isolate_gen';
+// The isolate-generation counter key (ISOLATE_GEN_KEY) and the multi-reason
+// alarm map key (ALARM_REASONS_KEY) live with their machinery in
+// @nimbus-sh/fabric/alarms.js; their persisted VALUES are unchanged.
 /** W9: debounce window in ms before flushing pending process-log writes
  *  to SQL. Hot path (every append schedules a flush via this debounce). */
 export const W9_FLUSH_DEBOUNCE_MS = 250;
@@ -34,25 +34,6 @@ export const SESSION_BASE_PATH_KEY = 'session-base-path';
  *  hibernation so vite resumes serving after wake without re-running
  *  /api/start-vite. */
 export const VITE_CONFIG_KEY = 'vite-config';
-/** W1: multi-reason alarm coordination map.
- *
- *  JSON-serialised `Record<reason, deadlineMsEpoch>` where keys are
- *  canonical reason strings (e.g. 'w9-flush', 'log-janitor'). The
- *  alarm() dispatcher reads this on fire, dispatches every reason
- *  whose deadline has passed, and re-arms `ctx.storage.setAlarm` at
- *  the earliest remaining deadline.
- *
- *  Why a map (not a single nextAlarmAt + reason): two subsystems
- *  (W9 debounced flush + W1 log-janitor sweep) can have distinct
- *  deadlines. Without the map, the later setAlarm() call would
- *  overwrite the earlier reason silently, breaking whichever
- *  subsystem expected its deadline.
- *
- *  Forward-compat: dispatcher silently drops unknown reasons so a
- *  rollback from a future deploy that added new reasons doesn't
- *  leave the alarm stuck.
- */
-export const W1_NEXT_ALARM_REASONS_KEY = 'w1_next_alarm_reasons';
 /**
  * Destroyed-session tombstone. Written AFTER `storage.deleteAll()` in the
  * destroy flow so a straggler facet RPC that wakes the dead DO cannot re-arm
@@ -60,21 +41,22 @@ export const W1_NEXT_ALARM_REASONS_KEY = 'w1_next_alarm_reasons';
  * metadata is the deliberate cost of keeping destroyed sessions inert.
  */
 export const SESSION_DESTROYED_KEY = 'session_destroyed';
-/**
- * Prefix for the resident-launch journal: one row per launch in flight, keyed
- * by the pid it is building for.
- *
- * A launch spans many turns and holds its state in memory, so an instance
- * reset destroys it silently — the process, the terminal and the work all go
- * with the object. The row is what a LATER instance reads to know a launch
- * ended that way rather than by finishing: a pid at or below the reader's own
- * pid base was allocated by a previous generation (see PID_GEN_STRIDE).
- * Written before the launch's first byte of work and removed when it settles,
- * so a row that outlives its instance is exactly an interrupted launch.
- */
-export const RESIDENT_LAUNCH_KEY_PREFIX = 'resident-launch:';
 /** Prefix for consumed single-use attach bootstrap token ids (`jti`).
  *  Written set-if-absent by `_rpcConsumeAttachBootstrap` on the attach
  *  exchange; an existing row means the bootstrap URL was replayed.
  *  Bounded: at most one row per `POST /new` bootstrap actually attached. */
 export const ATTACH_BOOTSTRAP_JTI_KEY_PREFIX = 'attach-bootstrap-jti:';
+/**
+ * Prefix for a port's durable preview capability, keyed by port number. The
+ * registry mints the value in memory per registration; this is what lets a
+ * preview URL the embedder was already handed survive a rebuild. Owned by
+ * `session/port-capability.ts`, which is the only module that reads or writes
+ * these rows.
+ */
+export const PORT_CAPABILITY_KEY_PREFIX = 'nimbus_preview_capability:';
+/**
+ * Prefix for a named programmatic shell's durable cwd+env, keyed by shell id.
+ * One row per id the embedder has actually used; bounded by the embedder's own
+ * naming, the way a terminal tab is.
+ */
+export const SHELL_STATE_KEY_PREFIX = 'nimbus_programmatic_shell:';

package/dist/session/nimbus-session.d.ts

@@ -22,7 +22,7 @@ import { NimbusWrangler } from '../wrangler/nimbus-wrangler.js';
 import { NpmInstaller } from '../npm/installer.js';
 import { type TryEnableReplicasResult as _W12EnableResult } from '../replica/routing.js';
 import * as _rpc from './rpc.js';
-import { type HostedHttpRequest, type HostedHttpResponse } from '../loaders/process-host.js';
+import type { HostedHttpRequest, HostedHttpResponse } from '@nimbus-sh/fabric/process-host.js';
 import { WebSocketRelay } from './ws-relay.js';
 import * as _programmatic from './programmatic.js';
 export { filterWranglerFlags, detectBundlerBin, checkNodeModulesGuard, detectUnsupportedWranglerConfig, renderNoDevServerHtml, BUNDLER_BIN_PREFIXES, NIMBUS_UNSUPPORTED_BINS, WRANGLER_IGNORED_FLAGS, WRANGLER_IGNORED_FLAGS_WITH_VALUE, WRANGLER_UNSUPPORTED_CONFIG_FIELDS, } from './helpers.js';
@@ -126,9 +126,11 @@ export declare class NimbusSession extends CloudflareDurableObject {
      * Lets `/api/_diag/memory` confirm whether a wake actually happened
      * between two probe calls.
      */
-    _w9IsolateGen: number;
+    _isolateGen: number;
     /** True once we've persisted the bumped gen counter to storage. */
-    _w9IsolateGenPersisted: boolean;
+    _isolateGenPersisted: boolean;
+    /** W1: serializes every alarm-map read-modify-write (fabric alarms.ts). */
+    _alarmChain?: Promise<unknown>;
     /** SQL DDL — idempotent; run on first fetch. */
     _w9SchemaInit: boolean;
     /** Have we wired the persist adapter into ProcessLogStore yet? */
@@ -262,6 +264,7 @@ export declare class NimbusSession extends CloudflareDurableObject {
     _rpcReadFileBytes(path: string, pid?: number): Promise<Uint8Array | null>;
     _rpcInnerDoFetch(req: any): Promise<any>;
     _rpcWriteFile(path: string, content: string | Uint8Array, pid?: number): Promise<number>;
+    _rpcWriteProtectedRootFile(rootPath: string, path: string, content: string | Uint8Array): Promise<void>;
     _rpcStat(path: string, pid?: number): Promise<any>;
     _rpcLstat(path: string, pid?: number): Promise<any>;
     _rpcHasLegacySymlinkUnder(path: string, pid?: number): Promise<boolean>;
@@ -450,11 +453,14 @@ export declare class NimbusSession extends CloudflareDurableObject {
         listening: boolean;
         pid: number | null;
         registeredAt: number | null;
+        capability: string | null;
     }>;
     _rpcUnexposePort(port: number): Promise<{
         port: number;
         ok: boolean;
     }>;
+    /** Capability-authenticated port route, for an embedder holding the token. */
+    _rpcRouteCapabilityPort(port: number, capability: string, request: Request, innerPath: string): Promise<Response>;
     _rpcDeleteFile(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
@@ -581,5 +587,5 @@ export declare class NimbusSession extends CloudflareDurableObject {
     /** W5: bridge _w5PersistRing → ctx.waitUntil. Delegator → ./nimbus-session-ws.ts (S7). */
     _w5SafePersistRing(): void;
 }
-export { NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, } from './bindings.js';
+export { NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, } from '@nimbus-sh/fabric/bindings.js';
 //# sourceMappingURL=nimbus-session.d.ts.map