@nimbus-sh/worker 0.1.0

package/dist/session/hibernation.js

@@ -0,0 +1,385 @@
+/**
+ * session/hibernation.ts — W9 hibernation persistence + alarm dispatch.
+ *
+ * Workerd hibernates Durable Objects between requests to free memory.
+ * On wake, the new isolate must rebuild its in-memory state from
+ * SQL — but it also needs to know "is this the same lifecycle as
+ * before, or did workerd recycle me?" That distinction matters for
+ * recovery (warmJoin vs cold init) and is captured by isolateGen,
+ * a counter persisted across hibernations.
+ *
+ * Surfaces:
+ *   - wireHibernationOnConstruct(ctx) — runs configureWsHibernation in
+ *     the DO ctor; graceful-degrades on throw.
+ *   - wireProcessLogPersist(host, ctx) — installs the SQL-backed
+ *     PersistAdapter on host.processLogs; patches append/markExit to
+ *     schedule debounced flushes.
+ *   - ensureHibSchema(host, ctx) — idempotent CREATE TABLE for
+ *     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.
+ *   - flushOnClose(host) — synchronous flush on ws close.
+ *
+ * **`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
+ * (DEFECT-D1 found at S3; documented in session-refactor-build-progress.md).
+ *
+ * Per plan §VI.7 F.2 invariant: `_w9PersistWired` must be reset
+ * between `processLogs` replacement and re-wire on
+ * `/api/_test/hib/simulate`. The class-side handler is responsible for
+ * setting `host._w9PersistWired = false` BEFORE calling
+ * wireProcessLogPersist again.
+ */
+import { configureWsHibernation } from './ws-hibernation-config.js';
+import { W9_ISOLATE_GEN_KEY, W9_FLUSH_DEBOUNCE_MS, W1_NEXT_ALARM_REASONS_KEY } 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
+ * the API; the result lands in /api/_diag/memory.hib for verification.
+ */
+export function wireHibernationOnConstruct(ctx) {
+    try {
+        return configureWsHibernation(ctx);
+    }
+    catch (e) {
+        console.warn('[nimbus/W9] configureWsHibernation threw:', e?.message);
+        return {
+            autoResponseConfigured: false,
+            timeoutSetMs: null,
+            autoResponseError: e?.message,
+            timeoutError: e?.message,
+        };
+    }
+}
+/**
+ * W9: install the SQL-backed PersistAdapter on host.processLogs.
+ *
+ * NOTE: any future alarm-driven subsystem MUST coordinate via a single
+ * `alarm()` dispatcher (e.g., a `nextAlarmReason` storage key checked
+ * inside the dispatcher). Today W9 is the only consumer; the dispatcher
+ * lives in `dispatchAlarm()` below, invoked from the class's `alarm()`
+ * handler.
+ *
+ * Idempotent: gated by host._w9PersistWired. Caller MUST reset that
+ * flag to false before re-invoking after a host.processLogs replacement
+ * (per /api/_test/hib/simulate flow; plan §VI.7 F.2 invariant).
+ */
+export function wireProcessLogPersist(host, ctx) {
+    if (host._w9PersistWired)
+        return;
+    host._w9PersistWired = true;
+    const adapter = {
+        load(pid) {
+            try {
+                ensureHibSchema(host, ctx);
+                const sql = ctx.storage.sql;
+                const chunkRows = [...sql.exec('SELECT pid, seq, ts, stream, data, binary FROM w9_proc_logs WHERE pid = ? ORDER BY seq ASC', pid)];
+                const exitRows = [...sql.exec('SELECT code, at, reason FROM w9_proc_exits WHERE pid = ?', pid)];
+                const chunks = chunkRows.map((r) => ({
+                    ts: Number(r.ts),
+                    stream: r.stream === 'stderr' ? 'stderr' : 'stdout',
+                    data: String(r.data),
+                    binary: !!r.binary,
+                    ...(r.seq !== undefined ? { seq: Number(r.seq) } : {}),
+                }));
+                const exit = exitRows.length > 0
+                    ? {
+                        code: Number(exitRows[0].code),
+                        at: Number(exitRows[0].at),
+                        reason: exitRows[0].reason ?? undefined,
+                    }
+                    : null;
+                return { chunks, exit };
+            }
+            catch {
+                return null;
+            }
+        },
+        persistChunks(pid, rows) {
+            if (rows.length === 0)
+                return;
+            try {
+                ensureHibSchema(host, ctx);
+                const sql = ctx.storage.sql;
+                // Use a single transactionSync wrapping the per-row INSERTs so
+                // a partial write either fully lands or fully rolls back. Real
+                // multi-row VALUES (?,?,?), (?,?,?), … is faster but requires
+                // dynamic-arity SQL building — clarity wins here; flushes
+                // happen at most once per debounce window so the volume is low.
+                ctx.storage.transactionSync(() => {
+                    for (const r of rows) {
+                        const c = r.chunk;
+                        sql.exec('INSERT OR REPLACE INTO w9_proc_logs (pid, seq, ts, stream, data, binary) VALUES (?, ?, ?, ?, ?, ?)', pid, r.seq, c.ts, c.stream, c.data, c.binary ? 1 : 0);
+                    }
+                });
+            }
+            catch (e) {
+                console.warn('[nimbus/W9] persistChunks failed:', e?.message);
+            }
+        },
+        persistExit(pid, info) {
+            try {
+                ensureHibSchema(host, ctx);
+                const sql = ctx.storage.sql;
+                sql.exec('INSERT OR REPLACE INTO w9_proc_exits (pid, code, at, reason) VALUES (?, ?, ?, ?)', pid, info.code, info.at, info.reason ?? null);
+            }
+            catch (e) {
+                console.warn('[nimbus/W9] persistExit failed:', e?.message);
+            }
+        },
+        dropPid(pid) {
+            try {
+                ensureHibSchema(host, ctx);
+                const sql = ctx.storage.sql;
+                ctx.storage.transactionSync(() => {
+                    sql.exec('DELETE FROM w9_proc_logs WHERE pid = ?', pid);
+                    sql.exec('DELETE FROM w9_proc_exits WHERE pid = ?', pid);
+                });
+            }
+            catch (e) {
+                console.warn('[nimbus/W9] dropPid failed:', e?.message);
+            }
+        },
+        pruneBeforeSeq(pid, seq) {
+            try {
+                ensureHibSchema(host, ctx);
+                const sql = ctx.storage.sql;
+                sql.exec('DELETE FROM w9_proc_logs WHERE pid = ? AND seq < ?', pid, seq);
+            }
+            catch (e) {
+                console.warn('[nimbus/W9] pruneBeforeSeq failed:', e?.message);
+            }
+        },
+    };
+    host.processLogs.setPersist(adapter);
+    // Wrap append/markExit on the store to schedule a debounced flush.
+    // We patch via method override rather than monkey-patching because
+    // the store doesn't (and shouldn't) know about timers — flush
+    // scheduling is the host's responsibility.
+    const origAppend = host.processLogs.append.bind(host.processLogs);
+    const origMarkExit = host.processLogs.markExit.bind(host.processLogs);
+    host.processLogs.append = (pid, stream, data) => {
+        origAppend(pid, stream, data);
+        scheduleHibFlush(host, ctx);
+    };
+    host.processLogs.markExit = (pid, code, reason) => {
+        origMarkExit(pid, code, reason);
+        // Exit-on-process-end is a strong "flush soon" signal — if the
+        // process crashed we want the dump persisted before the actor
+        // can hibernate. Schedule but don't bypass debounce, so a fast
+        // exit-after-spawn doesn't double-fire.
+        scheduleHibFlush(host, ctx);
+    };
+}
+/** W9: idempotent SQL schema bootstrap. */
+export function ensureHibSchema(host, ctx) {
+    if (host._w9SchemaInit)
+        return;
+    host._w9SchemaInit = true;
+    try {
+        const sql = ctx.storage.sql;
+        sql.exec('CREATE TABLE IF NOT EXISTS w9_proc_logs (' +
+            'pid INTEGER NOT NULL, seq INTEGER NOT NULL, ts INTEGER NOT NULL, ' +
+            'stream TEXT NOT NULL, data TEXT NOT NULL, binary INTEGER NOT NULL, ' +
+            'PRIMARY KEY (pid, seq))');
+        sql.exec('CREATE INDEX IF NOT EXISTS w9_proc_logs_ts ON w9_proc_logs(ts)');
+        sql.exec('CREATE TABLE IF NOT EXISTS w9_proc_exits (' +
+            'pid INTEGER PRIMARY KEY, code INTEGER NOT NULL, at INTEGER NOT NULL, ' +
+            'reason TEXT)');
+    }
+    catch (e) {
+        console.warn('[nimbus/W9] schema init failed:', e?.message);
+        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 async function scheduleAlarm(ctx, reason, whenMs) {
+    try {
+        const setAlarmFn = ctx?.storage?.setAlarm;
+        if (typeof setAlarmFn !== 'function')
+            return;
+        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);
+    }
+    catch (e) {
+        console.warn('[nimbus/W1] scheduleAlarm threw:', e?.message);
+    }
+}
+/**
+ * W9: ensure the alarm is set for the next flush window. Cheap to
+ * call repeatedly — we only schedule the in-isolate flush timer if
+ * it isn't already set. The persistent alarm goes through scheduleAlarm
+ * so it coordinates with W1's log-janitor sweep.
+ */
+export function scheduleHibFlush(host, ctx) {
+    if (host._w9FlushTimer)
+        return;
+    // Local timer for fast in-isolate flush. SHORT-LIVED (250 ms); the
+    // callback nulls itself so this timer does not persistently prevent
+    // hibernation — once it fires, the DO is timer-free again.
+    // Per CF docs, transient setTimeout during an active request is the
+    // expected pattern; what blocks hibernation is a RECURRING timer.
+    host._w9FlushTimer = setTimeout(() => {
+        host._w9FlushTimer = null;
+        try {
+            host.processLogs.flush();
+        }
+        catch (e) {
+            console.warn('[nimbus/W9] flush threw:', e?.message);
+        }
+    }, W9_FLUSH_DEBOUNCE_MS);
+    // Persistent alarm: fires post-hibernation if the in-isolate timer
+    // didn't get a chance to run (DO evicted under memory pressure
+    // before the 250ms debounce expired). Coordinated via scheduleAlarm
+    // so W1's log-janitor doesn't clobber it (or vice-versa).
+    // Fire-and-forget — scheduleAlarm is fail-soft.
+    void scheduleAlarm(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:
+ *   - `'w9-flush'` → processLogs.flush()
+ *   - `'log-janitor'` → processLogs.dropOlderThan(orphanCheck); re-arm
+ *     for next 60s cycle.
+ *
+ * `janitorOrphanCheck` is the orphan-pid predicate provided by the
+ * caller (typically `(pid) => !host.processTable.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 async function dispatchAlarm(host, ctx, janitorOrphanCheck) {
+    try {
+        const now = Date.now();
+        const existing = (await ctx?.storage?.get?.(W1_NEXT_ALARM_REASONS_KEY));
+        // Legacy path: pre-W1 deploys had no map. dispatchAlarm was called
+        // with no map and unconditionally ran processLogs.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.processLogs.flush();
+            }
+            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.processLogs.flush();
+                }
+                else if (reason === 'log-janitor') {
+                    host.processLogs.dropOlderThan(undefined, janitorOrphanCheck);
+                    // Self-renew: schedule next sweep 60s out.
+                    map['log-janitor'] = now + 60_000;
+                }
+                // 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);
+            }
+        }
+        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/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));
+        const next = (typeof prev === 'number' ? prev : 0) + 1;
+        host._w9IsolateGen = next;
+        await ctx.storage.put(W9_ISOLATE_GEN_KEY, next);
+    }
+    catch (e) {
+        console.warn('[nimbus/W9] isolate-gen bump failed:', e?.message);
+    }
+}
+/**
+ * W9: synchronous flush of the process-log ring on session close.
+ * Wraps `processLogs.flush()` in a try/catch so a flush failure
+ * doesn't take down the close handler. Cheap when there's nothing
+ * dirty (idempotent inside the store).
+ */
+export function flushOnClose(host) {
+    try {
+        host.processLogs.flush();
+    }
+    catch (e) {
+        console.warn('[nimbus/W9] flush-on-close failed:', e?.message);
+    }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * src/session/init-phases.ts — B'.4 R/B/W/O state machine for initSession.
+ *
+ * Track B' goal: make the implicit phases of initSession explicit and
+ * observable. Each phase boundary calls `setPhase(self, phase, trigger)`
+ * which:
+ *   1. Updates `self._b4Phase` so /api/_diag/session.phase reflects it.
+ *   2. Records a recovery_event entry capturing the transition. The
+ *      ring is bounded to 50 events and is the C'.2 surface — phase
+ *      transitions are SUPPLEMENTAL to the existing high-level
+ *      cold/hydrated/active/drained markers, not a replacement.
+ *
+ * The phases:
+ *   - rehydrate: Phase R — loading persisted values from DO SQLite
+ *                (cwd, env, mounts, scrollback). Pure SQL reads;
+ *                sets up locals consumed by later phases.
+ *   - build:     Phase B — constructing Kernel + Shell + registry +
+ *                installing 60+ commands + wiring SqliteVFSProvider
+ *                mounts. Most CPU-intensive phase.
+ *   - wire:      Phase W — attaching the WebSocketTerminal to the
+ *                Shell, replaying persisted scrollback into the WS.
+ *                This is the phase B'.5 will be able to re-run on
+ *                an already-built session ("join existing").
+ *   - online:    Phase O — cold-start UI: MOTD, starter-app hint,
+ *                framework-detect line. ONLY runs on cold start
+ *                (when persisted.hasPersistedState=false). On warm
+ *                re-init this phase is skipped and initSession ends
+ *                with the 'hydrated' marker instead of 'online'.
+ *
+ * The legacy single recordRecoveryEvent({fromState, toState:
+ * 'hydrated', trigger:'init-session'}) call at end of initSession is
+ * preserved — old probes still see it. New phase entries are
+ * additional ring entries, not replacements.
+ */
+import { type SessionState } from '../observability/oom-discriminator.js';
+/**
+ * Set the current phase + record a transition. Fail-soft on the
+ * observability call; the phase update on `self` is direct and
+ * cheap.
+ */
+export declare function setPhase(self: {
+    _b4Phase: SessionState | null;
+    _w9IsolateGen?: number;
+}, toState: SessionState, trigger: string): void;
+/**
+ * [B'.5] Determine whether the next /ws upgrade should run the warm-
+ * rejoin path (Phase R + Phase W only) or the full cold-init path
+ * (R + B + W + O + hydrated).
+ *
+ * Conditions for warm rejoin:
+ *   1. Phase = 'drained' (a wsClose / wsError fired since last init).
+ *   2. Kernel + Shell + Terminal are still alive in-memory (the
+ *      [B'.5] change to wsClose stopped nulling them).
+ *   3. Same isolate (no DO eviction since the close).
+ *
+ * If ANY condition fails, the full cold-init path is the safe choice.
+ */
+export declare function isWarmRejoin(self: {
+    _b4Phase: SessionState | null;
+    shell: any;
+    terminal: any;
+    kernel: any;
+}): boolean;
+/**
+ * [B'.5] Run the warm-rejoin path. Skips Phase B (kernel + shell are
+ * already built and alive in-memory). Phase R loads any state that
+ * may have changed since drained (none today — Phase R is no-op on
+ * warm rejoin); Phase W swaps the WebSocketTerminal's underlying ws
+ * to the new socket and replays scrollback so the user sees their
+ * pre-close terminal contents above the live prompt.
+ *
+ * The `self` argument is intentionally minimal — only the fields
+ * this function actually touches. The full SessionInternal isn't
+ * needed here; init-phases.ts shouldn't grow a circular dep on
+ * nimbus-session-internal.
+ */
+export declare function joinExistingSession(self: {
+    ctx: any;
+    terminal: {
+        attach(ws: WebSocket, onFlush?: (data: string) => void): void;
+        write(s: string): void;
+    };
+    _b4Phase: SessionState | null;
+    _w9IsolateGen?: number;
+    _b4WarmJoinCount: number;
+}, ws: WebSocket, appendScrollback: (ctx: any, data: string, atMs: number) => void, loadScrollback: (ctx: any) => string): void;
+//# sourceMappingURL=init-phases.d.ts.map

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

@@ -0,0 +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,uCAAuC,CAAC;AAE/F;;;;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;;;;;;;;;;;;GAYG;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;;;;;;;;;;;;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"}

package/dist/session/init-phases.js

@@ -0,0 +1,137 @@
+/**
+ * src/session/init-phases.ts — B'.4 R/B/W/O state machine for initSession.
+ *
+ * Track B' goal: make the implicit phases of initSession explicit and
+ * observable. Each phase boundary calls `setPhase(self, phase, trigger)`
+ * which:
+ *   1. Updates `self._b4Phase` so /api/_diag/session.phase reflects it.
+ *   2. Records a recovery_event entry capturing the transition. The
+ *      ring is bounded to 50 events and is the C'.2 surface — phase
+ *      transitions are SUPPLEMENTAL to the existing high-level
+ *      cold/hydrated/active/drained markers, not a replacement.
+ *
+ * The phases:
+ *   - rehydrate: Phase R — loading persisted values from DO SQLite
+ *                (cwd, env, mounts, scrollback). Pure SQL reads;
+ *                sets up locals consumed by later phases.
+ *   - build:     Phase B — constructing Kernel + Shell + registry +
+ *                installing 60+ commands + wiring SqliteVFSProvider
+ *                mounts. Most CPU-intensive phase.
+ *   - wire:      Phase W — attaching the WebSocketTerminal to the
+ *                Shell, replaying persisted scrollback into the WS.
+ *                This is the phase B'.5 will be able to re-run on
+ *                an already-built session ("join existing").
+ *   - online:    Phase O — cold-start UI: MOTD, starter-app hint,
+ *                framework-detect line. ONLY runs on cold start
+ *                (when persisted.hasPersistedState=false). On warm
+ *                re-init this phase is skipped and initSession ends
+ *                with the 'hydrated' marker instead of 'online'.
+ *
+ * The legacy single recordRecoveryEvent({fromState, toState:
+ * 'hydrated', trigger:'init-session'}) call at end of initSession is
+ * preserved — old probes still see it. New phase entries are
+ * additional ring entries, not replacements.
+ */
+import { recordRecoveryEvent } from '../observability/oom-discriminator.js';
+/**
+ * Set the current phase + record a transition. Fail-soft on the
+ * observability call; the phase update on `self` is direct and
+ * cheap.
+ */
+export function setPhase(self, toState, trigger) {
+    const fromState = self._b4Phase ?? 'cold';
+    self._b4Phase = toState;
+    try {
+        recordRecoveryEvent({
+            at: Date.now(),
+            fromState,
+            toState,
+            trigger,
+            isolateGen: self._w9IsolateGen ?? 0,
+            dataLoss: false,
+            snapshotKeysRehydrated: 0,
+        });
+    }
+    catch { /* observability is non-critical */ }
+}
+/**
+ * [B'.5] Determine whether the next /ws upgrade should run the warm-
+ * rejoin path (Phase R + Phase W only) or the full cold-init path
+ * (R + B + W + O + hydrated).
+ *
+ * Conditions for warm rejoin:
+ *   1. Phase = 'drained' (a wsClose / wsError fired since last init).
+ *   2. Kernel + Shell + Terminal are still alive in-memory (the
+ *      [B'.5] change to wsClose stopped nulling them).
+ *   3. Same isolate (no DO eviction since the close).
+ *
+ * If ANY condition fails, the full cold-init path is the safe choice.
+ */
+export function isWarmRejoin(self) {
+    return self._b4Phase === 'drained'
+        && self.shell != null
+        && self.terminal != null
+        && self.kernel != null;
+}
+/**
+ * [B'.5] Run the warm-rejoin path. Skips Phase B (kernel + shell are
+ * already built and alive in-memory). Phase R loads any state that
+ * may have changed since drained (none today — Phase R is no-op on
+ * warm rejoin); Phase W swaps the WebSocketTerminal's underlying ws
+ * to the new socket and replays scrollback so the user sees their
+ * pre-close terminal contents above the live prompt.
+ *
+ * The `self` argument is intentionally minimal — only the fields
+ * this function actually touches. The full SessionInternal isn't
+ * needed here; init-phases.ts shouldn't grow a circular dep on
+ * nimbus-session-internal.
+ */
+export function joinExistingSession(self, ws, appendScrollback, loadScrollback) {
+    // Phase R — pure SQL reads. No-op on warm rejoin (live state is
+    // already correct in self.shell / self.terminal). Recorded in the
+    // ring for symmetry with cold init.
+    setPhase(self, 'rehydrate', 'warm-rejoin');
+    // Phase W — re-attach the existing WebSocketTerminal to the new
+    // ws and replay persisted scrollback. The Shell's reference to
+    // the same WebSocketTerminal instance is preserved (we mutate
+    // its internal ws ref via attach()).
+    setPhase(self, 'wire', 'warm-rejoin');
+    self.terminal.attach(ws, (frame) => {
+        try {
+            appendScrollback(self.ctx, frame, Date.now());
+        }
+        catch (e) {
+            try {
+                console.warn("[B'.3] appendScrollback failed:", e?.message || e);
+            }
+            catch { }
+        }
+    });
+    // Replay scrollback to the new ws so the user sees the prior
+    // session's terminal contents. Same shape as cold-init's replay
+    // when persisted state exists.
+    try {
+        const replay = loadScrollback(self.ctx);
+        if (replay.length > 0)
+            self.terminal.write(replay);
+    }
+    catch (e) {
+        try {
+            console.warn("[B'.3] scrollback replay failed:", e?.message || e);
+        }
+        catch { }
+    }
+    // Phase O is SKIPPED on warm rejoin (just like warm path of
+    // initSession). The original cold-start banner is in the replay.
+    // Settle to 'hydrated' as the terminal phase via setPhase so the
+    // ring records the wire→hydrated transition for forensics.
+    setPhase(self, 'hydrated', 'warm-rejoin');
+    // Bump the warm-join counter; surfaced via /api/_diag/session.
+    self._b4WarmJoinCount += 1;
+    // ws.send({type:'ready'}) — the client expects this to know the
+    // shell is live. Same as initSession's last line.
+    try {
+        ws.send(JSON.stringify({ type: 'ready' }));
+    }
+    catch { }
+}

package/dist/session/init.d.ts

@@ -0,0 +1,46 @@
+/**
+ * session/init.ts — initSession boot + shell-command registrations.
+ *
+ * Why this is one big function and not a class:
+ * initSession runs once per /ws upgrade and walks the session
+ * through Phase R (rehydrate from SQL), Phase B (build kernel +
+ * shell + register commands), Phase W (attach terminal), and
+ * (cold-only) Phase O (MOTD + framework hint). The phases share
+ * lots of locals (vfs, kernel, registry, shell) and ordering
+ * matters strictly — there's no interesting reuse boundary that a
+ * class decomposition would expose.
+ *
+ * The function is intentionally written so that a reader sees:
+ *   1. setPhase('rehydrate') ...
+ *   2. setPhase('build')    ... (~95% of the LOC)
+ *   3. setPhase('online')   if (cold)
+ *   4. self._b4Phase = 'hydrated'
+ *
+ * Extracted from src/nimbus-session.ts during the SESSION-REFACTOR
+ * (audit/sections/SESSION-REFACTOR-PLAN.md §B.3.8 + S6) so the DO
+ * class itself stays small. Imports `self: InitHost` (a narrow view
+ * of SessionInternal + readonly ctx/env) which gives the compiler
+ * enough type info without the surface area of the full DO class.
+ *
+ * Imports and class delegators on NimbusSession preserve back-compat:
+ *   - acceptShellWebSocket → self.initSession(ws)  (S7 will extract).
+ *   - The class still has `initSession(ws)` as a delegator method.
+ */
+import type { SessionInternal } from './internal.js';
+/**
+ * `initSession` reads `this.ctx` and `this.env` extensively (~14 sites).
+ * Both are `protected` on the parent `CloudflareDurableObject` class
+ * (DEFECT-D1, see audit/sessions/session-refactor-build-progress.md).
+ * The pragmatic shape for THIS module: extend SessionInternal with
+ * `ctx`/`env` as `any` and have the class delegator cast `this as
+ * unknown as InitHost`. Other sibling modules (-rpc, -ws, -hib,
+ * -replica) DO take ctx as a separate explicit arg per D1 — initSession
+ * can't because the body has too many call sites to thread through.
+ */
+type InitHost = SessionInternal & {
+    readonly ctx: any;
+    readonly env: any;
+};
+export declare function initSession(self: InitHost, ws: WebSocket): void;
+export {};
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/session/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA8DH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;GASG;AACH,KAAK,QAAQ,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;CAAE,CAAC;AAG3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI,CAk8G/D"}