@nimbus-sh/worker 0.9.0 → 0.11.0

package/dist/session/supervisor-rpc.js

@@ -4,10 +4,15 @@
  * Exported from index.ts. Facets receive `env.SUPERVISOR` service binding
  * pointing to this class via ctx.exports loopback binding.
  *
- * Props: { doId: string, pid: number, writerId: string }
+ * Props: { doId: string, pid: number, writerId: string, route: HostRoute, hostIncarnation?: string }
  *   doId — the supervisor DO's durable object ID (for routing)
  *   pid  — the process ID (for stdout/stderr routing)
  *   writerId — the active append-writer incarnation for this process
+ *   route — the host namespace and dispatch method, minted with the binding
+ *           in the host's isolate; this entrypoint may answer from another
+ *   hostIncarnation — the host instance that minted the binding, present
+ *           when that host applies delivered mutations once
+ *           (@nimbus-sh/core/workspace/supervisor-delivery.js)
  *
  * Methods callable by facets via RPC:
  *   readFile(path) → string | null
@@ -20,16 +25,29 @@
  *   fsOpen/fsRead/fsWrite/fsClose/readlink/symlink/rename/rmdir/fsRevision
  *   fsReadRange/fsWriteRange/fsAppend/fsAppendAck/fsTruncate
  *     → shared RuntimeFsBridge operations
- *   fsReadBatch(requests) → per-range results  (many reads, one round trip)
+ *   fsReadBatch(requests) → per-request results  (many reads and lstats, one round trip)
  *   fsList(after, limit) → one page of what EXISTS, with per-path revisions
  *   writeBatch(payload) → { inodes, chunks }  (bulk atomic write)
  *   stdout(data) → void  (pushed to WebSocket + ring buffer)
  *   stderr(data) → void
  *   reportExit(code, tail?) → void  (called from facet's finally block)
  *   prefetch(cwd, entryCode) → Record<string, string>
+ *
+ * Delivery: every call reaches the session over a Durable Object stub the
+ * platform can drop ("Network connection lost.", `retryable`). Reads are
+ * re-sent on a fresh stub, and hedged: one unanswered after
+ * SUPERVISOR_READ_HEDGE_AFTER_MS is sent again while it stays in flight.
+ * Filesystem mutations, on a binding that names its
+ * host's incarnation, are re-sent under one delivery id that host applies at
+ * most once (`_fsMutation`); on any other binding they are sent once.
+ * Appends are re-sent under the append ledger's identity. Everything else is
+ * sent once and a drop surfaces.
  */
 import { WorkerEntrypoint } from 'cloudflare:workers';
-import { hostNamespace, hostDispatchMethod } from '@nimbus-sh/platform/composition.js';
+import { hostNamespaceBinding, hostOpDispatch } from '@nimbus-sh/fabric/host-dispatch.js';
+import { idempotent } from '@nimbus-sh/fabric/do-calls.js';
+import { SUPERVISOR_DELIVER_OP, } from '@nimbus-sh/core/workspace/supervisor-delivery.js';
+import { VFS_DELIVERY_RETRY_WINDOW_MS } from '@nimbus-sh/core/constants.js';
 // W5: OOM discriminator — record last-known RPC frame on writeBatch entry
 import { setLastRpcFrame } from '@nimbus-sh/platform/oom-discriminator.js';
 // Phase 2 A'.2 — supervisor in-flight RPC payload byte tracking.
@@ -37,6 +55,7 @@ import { rpcPayloadStart, rpcPayloadEnd } from '@nimbus-sh/platform/diag-counter
 // W4: R2 cross-tenant npm cache (tarballs + packuments)
 import { R2CacheClient, MAX_R2_TARBALL_BYTES } from '../npm/r2-cache.js';
 import { useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { fsReadBatchRequestBytes } from './rpc.js';
 import { W7_MAX_RECORD_BYTES } from '@nimbus-sh/platform/w7-frame.js';
 /**
  * Drain the per-call event list captured by R2CacheClient during this
@@ -78,39 +97,104 @@ function _estimateWriteBatchBytes(payload) {
 // The fabric mints `env.SUPERVISOR` bindings for the programs it hosts; the
 // worker's composition root (src/index.ts) names this class to the fabric
 // with composeFabric.
+// A process's filesystem read (SupervisorRPC → session) still unanswered
+// after this long is sent again on a fresh stub, the first left running and
+// the first answer taken (fabric do-calls `hedgeAfterMs`). Measured on a
+// throwaway under three concurrent sessions, 2026-09-28: none of the 521
+// read batches that answered took more than 5 s at the facet's side, the
+// session served each read it received without waiting on I/O, and the 11
+// attempts that stalled — none of which reached the session — were still
+// pending 110–560 s later. So an attempt past 5 s is one that is not coming
+// back, and a hedge then costs a duplicate read only when that measurement
+// was wrong.
+export const SUPERVISOR_READ_HEDGE_AFTER_MS = 5_000;
 export class SupervisorRPC extends WorkerEntrypoint {
-    /** Resolve the composed host anew for each WorkerEntrypoint invocation. */
-    _dispatch() {
+    /**
+     * A fresh stub for the host, by the route the binding carries, per call.
+     * The platform serves this entrypoint from whichever isolate it likes; the
+     * props were minted in the host's.
+     */
+    _host() {
         const doId = this.ctx.props?.doId;
         if (typeof doId !== 'string' || doId.length === 0) {
             throw new Error('SupervisorRPC: missing doId in props');
         }
-        const binding = hostNamespace();
-        const namespace = Reflect.get(this.env, binding);
-        if (!namespace || typeof namespace.idFromString !== 'function') {
-            throw new Error(`SupervisorRPC: env.${binding} is not a Durable Object namespace; `
-                + "a workspace host names its own with composeFabric({ hostNamespace: '<binding>' })");
-        }
-        const stub = namespace.get(namespace.idFromString(doId));
-        const method = hostDispatchMethod();
-        const dispatch = Reflect.get(stub, method);
-        if (typeof dispatch !== 'function') {
-            throw new Error(`SupervisorRPC: the workspace host mounts no ${method}(); `
-                + 'a host forwards one method to workspace.supervisorOp(op)');
-        }
-        // Never `.call(stub, …)` on an RpcStub: the proxy treats `call` as a
-        // property get, which becomes an RPC to a method literally named "call".
-        // `Reflect.apply` reaches the proxied member's apply trap instead, and on
-        // a plain-object host it still invokes the method with the stub as `this`.
-        return (envelope) => Reflect.apply(dispatch, stub, [envelope]);
+        const namespace = hostNamespaceBinding(this.env, 'SupervisorRPC', this._route());
+        return namespace.get(namespace.idFromString(doId));
+    }
+    _route() {
+        return this.ctx.props?.route;
     }
     _op(op, args = [], extra = {}) {
-        return this._dispatch()({ op, args, ...extra });
+        return hostOpDispatch(this._host(), 'SupervisorRPC', this._route())({ op, args, ...extra });
     }
     /** Stamp filesystem credentials from the binding, not the supplied arguments. */
     _fsOp(op, args = []) {
         return this._op(op, args, { pid: this._pid() });
     }
+    /**
+     * A filesystem read changes nothing on the host, so a call the platform
+     * dropped on the way to it is repeated on a fresh stub. Measured: the
+     * host's `stat` failing with "Network connection lost." (`retryable`) is
+     * what failed CPython's start in about one fresh session in twenty.
+     *
+     * A read can also never answer: under concurrent sessions a burst of reads
+     * from one facet left some attempts pending for minutes without reaching
+     * the host, and the program waiting on them never exited
+     * (preview/new/lucide-barrel-cache-widens). So a read still unanswered
+     * after SUPERVISOR_READ_HEDGE_AFTER_MS is hedged: sent again on a fresh
+     * stub, the first attempt left running, the first answer taken.
+     *
+     * A read can equally be slow at the session — queued behind the read
+     * budget, a lazy import, a busy input gate — and a hedge must not make it
+     * read again there. So every attempt carries the one read id minted here,
+     * and the session joins a repeat to the read it is still serving
+     * (`SupervisorDeliveries.joinRead`): a hedge that did arrive costs the
+     * session nothing but a second copy of the answer. Mutations are not
+     * hedged: their repeats stay bounded by the delivery retry window.
+     */
+    _fsRead(op, args = []) {
+        return this._resent({ op, args, pid: this._pid(), readId: crypto.randomUUID() }, { hedgeAfterMs: SUPERVISOR_READ_HEDGE_AFTER_MS });
+    }
+    /**
+     * A filesystem mutation, delivered exactly once. The platform drops this
+     * hop too — measured: pip's `fsWrite` of a wheel member and a FileHandle
+     * write loop, each failing "Network connection lost." (`retryable`) as
+     * EIO — and a dropped mutation may or may not have run.
+     *
+     * So on a binding whose host names its incarnation, every attempt carries
+     * the one delivery id minted here, under SUPERVISOR_DELIVER_OP, and that
+     * host instance applies the id at most once: a repeat of a mutation that
+     * ran is answered from its receipt and never applied again, even over
+     * another writer's newer write; one that never arrived applies on the
+     * repeat. Any other instance, and any host that predates delivery, refuses
+     * the envelope outright, and that refusal is never repeated. Repeats stop
+     * VFS_DELIVERY_RETRY_WINDOW_MS after the first attempt, inside the host's
+     * receipt retention.
+     *
+     * A binding minted by a host that dedupes nothing names no incarnation,
+     * and its mutations are sent once.
+     *
+     * The id is random because this entrypoint keeps nothing between calls and
+     * may answer from any isolate; the pid still comes from the binding.
+     */
+    _fsMutation(op, args) {
+        const hostIncarnation = this._hostIncarnation();
+        if (hostIncarnation === undefined)
+            return this._fsOp(op, args);
+        return this._resent({ op: SUPERVISOR_DELIVER_OP, args, pid: this._pid(), delivery: { op, id: crypto.randomUUID(), hostIncarnation } }, { retryWindowMs: VFS_DELIVERY_RETRY_WINDOW_MS });
+    }
+    /** `envelope`, re-sent as it is on a fresh stub while the platform drops it retryably. */
+    _resent(envelope, policy) {
+        return idempotent(envelope.delivery?.op ?? envelope.op, () => this._host(), (host) => hostOpDispatch(host, 'SupervisorRPC', this._route())(envelope), policy);
+    }
+    _hostIncarnation() {
+        const props = this.ctx.props;
+        if (typeof props !== 'object' || props === null || !('hostIncarnation' in props))
+            return undefined;
+        const incarnation = props.hostIncarnation;
+        return typeof incarnation === 'string' && incarnation.length > 0 ? incarnation : undefined;
+    }
     _reportingPid() {
         const pid = this.ctx.props?.pid;
         return typeof pid === 'number' && Number.isInteger(pid) && pid > 0 ? pid : 0;
@@ -134,14 +218,14 @@ export class SupervisorRPC extends WorkerEntrypoint {
     }
     // ── Filesystem RPC ────────────────────────────────────────────────────
     async readFile(path) {
-        return this._call(this._fsOp('readFile', [path]));
+        return this._call(this._fsRead('readFile', [path]));
     }
     /**
      * Read a file as raw bytes. Used by the git network facet for binary
      * object/pack files where the text readFile would corrupt content.
      */
     async readFileBytes(path) {
-        return this._call(this._fsOp('readFileBytes', [path]));
+        return this._call(this._fsRead('readFileBytes', [path]));
     }
     async writeFile(path, content) {
         // binary-fs wave: accept Uint8Array natively. Pre-fix this RPC was
@@ -149,55 +233,55 @@ export class SupervisorRPC extends WorkerEntrypoint {
         // decode every Uint8Array write — mangling bytes ≥ 0x80 to U+FFFD
         // and corrupting binary content. RPC structured-clone handles
         // Uint8Array transparently; downstream _rpcWriteFile also accepts
-        return this._call(this._fsOp('writeFile', [path, content]));
+        return this._call(this._fsMutation('writeFile', [path, content]));
     }
     async stat(path, options) {
-        return this._call(this._fsOp('stat', [path, options]));
+        return this._call(this._fsRead('stat', [path, options]));
     }
     async lstat(path) {
-        return this._call(this._fsOp('lstat', [path]));
+        return this._call(this._fsRead('lstat', [path]));
     }
     async hasLegacySymlinkUnder(path) {
-        return this._call(this._fsOp('hasLegacySymlinkUnder', [path]));
+        return this._call(this._fsRead('hasLegacySymlinkUnder', [path]));
     }
     async utimes(path, atimeMs, mtimeMs) {
-        return this._call(this._fsOp('utimes', [path, atimeMs, mtimeMs]));
+        return this._call(this._fsMutation('utimes', [path, atimeMs, mtimeMs]));
     }
     async chmod(path, mode) {
-        return this._call(this._fsOp('chmod', [path, mode]));
+        return this._call(this._fsMutation('chmod', [path, mode]));
     }
     async access(path, mode) {
-        return this._call(this._fsOp('access', [path, mode]));
+        return this._call(this._fsRead('access', [path, mode]));
     }
     async chown(path, uid, gid, options) {
-        return this._call(this._fsOp('chown', [path, uid, gid, options]));
+        return this._call(this._fsMutation('chown', [path, uid, gid, options]));
     }
     async setUmask(mask) {
         return this._call(this._fsOp('setUmask', [mask]));
     }
     async readdir(path) {
-        return this._call(this._fsOp('readdir', [path]));
+        return this._call(this._fsRead('readdir', [path]));
     }
     async exists(path) {
-        return this._call(this._fsOp('exists', [path]));
+        return this._call(this._fsRead('exists', [path]));
     }
     async mkdir(path, options) {
-        return this._call(this._fsOp('mkdir', [path, options]));
+        return this._call(this._fsMutation('mkdir', [path, options]));
     }
     async rmdir(path) {
-        return this._call(this._fsOp('rmdir', [path]));
+        return this._call(this._fsMutation('rmdir', [path]));
     }
     async rename(from, to) {
-        return this._call(this._fsOp('rename', [from, to]));
+        return this._call(this._fsMutation('rename', [from, to]));
     }
     async unlink(path) {
-        return this._call(this._fsOp('unlink', [path]));
+        return this._call(this._fsMutation('unlink', [path]));
     }
     async readlink(path) {
-        return this._call(this._fsOp('readlink', [path]));
+        return this._call(this._fsRead('readlink', [path]));
     }
     async symlink(target, path) {
-        return this._call(this._fsOp('symlink', [target, path]));
+        return this._call(this._fsMutation('symlink', [target, path]));
     }
     /**
      * ACQUIRE: the paths mutated since the facet's cursor, plus a fresh
@@ -208,13 +292,14 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * SupervisorRPC runs in a different isolate from the DO that owns the
      * revision clock, so stamping here would cost its own round trip anyway,
      * and enveloping the existing returns would break `useRpcResource`
-     * disposal, which targets the returned value.
+     * disposal, which targets the returned value. It only reads the
+     * invalidation log, so a dropped call is repeated like any other read.
      */
-    async fsAcquire(epoch, cursor) {
-        return this._call(this._fsOp('fsAcquire', [epoch, cursor]));
+    async fsAcquire(epoch, cursor, options) {
+        return this._call(this._fsRead('fsAcquire', options === undefined ? [epoch, cursor] : [epoch, cursor, options]));
     }
     async fsRevision(path) {
-        return this._call(this._fsOp('fsRevision', [path]));
+        return this._call(this._fsRead('fsRevision', [path]));
     }
     /**
      * Enumerate the session filesystem, one bounded page at a time.
@@ -233,8 +318,12 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * enumerating. `next === null` marks the final page, so a short page is
      * never mistaken for a complete listing.
      */
+    /** N18: `bytes` more for this process's facet store, reporting what it measures. */
+    async fsStorageGrant(facet, bytes, databaseSize) {
+        return this._call(this._fsOp('fsStorageGrant', [facet, bytes, databaseSize]));
+    }
     async fsList(after, limit) {
-        return this._call(this._fsOp('fsList', [after ?? null, limit ?? null]));
+        return this._call(this._fsRead('fsList', [after ?? null, limit ?? null]));
     }
     /**
      * WebSocket relay. A facet does not open its own sockets: the supervisor
@@ -257,61 +346,65 @@ export class SupervisorRPC extends WorkerEntrypoint {
         return this._call(this._fsOp('wsClose', [id, code, reason]));
     }
     async fsOpen(path, flags) {
-        return this._call(this._fsOp('fsOpen', [path, flags]));
+        return this._call(this._fsMutation('fsOpen', [path, flags]));
     }
     async fsRead(handleId, offset, length) {
         return this._call(this._fsOp('fsRead', [handleId, offset, length]));
     }
     async fsWrite(handleId, offset, bytes) {
-        return this._call(this._fsOp('fsWrite', [handleId, offset, bytes]));
+        return this._call(this._fsMutation('fsWrite', [handleId, offset, bytes]));
     }
+    /** A descriptor's stat and its directory listing move nothing: re-sent like any read. */
     async fsFstat(...args) {
-        return this._call(this._fsOp('fsFstat', args));
+        return this._call(this._fsRead('fsFstat', args));
     }
     async fsDup(...args) {
-        return this._call(this._fsOp('fsDup', args));
+        return this._call(this._fsMutation('fsDup', args));
     }
     async fsSeek(...args) {
-        return this._call(this._fsOp('fsSeek', args));
+        return this._call(this._fsMutation('fsSeek', args));
     }
     async fsSetStatus(...args) {
-        return this._call(this._fsOp('fsSetStatus', args));
+        return this._call(this._fsMutation('fsSetStatus', args));
     }
     async fsReaddirHandle(...args) {
-        return this._call(this._fsOp('fsReaddirHandle', args));
+        return this._call(this._fsRead('fsReaddirHandle', args));
     }
     async fsFtruncate(...args) {
-        return this._call(this._fsOp('fsFtruncate', args));
+        return this._call(this._fsMutation('fsFtruncate', args));
     }
     async fsFchmod(...args) {
-        return this._call(this._fsOp('fsFchmod', args));
+        return this._call(this._fsMutation('fsFchmod', args));
     }
     async fsFchown(...args) {
-        return this._call(this._fsOp('fsFchown', args));
+        return this._call(this._fsMutation('fsFchown', args));
     }
     async fsFutimes(...args) {
-        return this._call(this._fsOp('fsFutimes', args));
+        return this._call(this._fsMutation('fsFutimes', args));
     }
     async fsSync(...args) {
-        return this._call(this._fsOp('fsSync', args));
+        return this._call(this._fsMutation('fsSync', args));
     }
     async fsRealpath(...args) {
-        return this._call(this._fsOp('fsRealpath', args));
+        return this._call(this._fsRead('fsRealpath', args));
     }
     async fsRemove(...args) {
-        return this._call(this._fsOp('fsRemove', args));
+        return this._call(this._fsMutation('fsRemove', args));
     }
     async fsCopyFile(...args) {
-        return this._call(this._fsOp('fsCopyFile', args));
+        return this._call(this._fsMutation('fsCopyFile', args));
+    }
+    async fsCopyTree(...args) {
+        return this._call(this._fsMutation('fsCopyTree', args));
     }
     async fsAcquireExclusiveMutation(...args) {
-        return this._call(this._fsOp('fsAcquireExclusiveMutation', args));
+        return this._call(this._fsMutation('fsAcquireExclusiveMutation', args));
     }
     async fsReleaseExclusiveMutation(...args) {
-        return this._call(this._fsOp('fsReleaseExclusiveMutation', args));
+        return this._call(this._fsMutation('fsReleaseExclusiveMutation', args));
     }
     async fsClose(handleId) {
-        return this._call(this._fsOp('fsClose', [handleId]));
+        return this._call(this._fsMutation('fsClose', [handleId]));
     }
     /**
      * Stateless ranged ops. Unlike fsOpen/fsRead/fsWrite they carry no
@@ -319,7 +412,7 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * hibernation and never rewrite whole files for partial updates.
      */
     async fsReadRange(path, offset, length) {
-        return this._call(this._fsOp('fsReadRange', [path, offset, length]));
+        return this._call(this._fsRead('fsReadRange', [path, offset, length]));
     }
     /**
      * The same read with the session's content cache bypassed, for a boot spec's
@@ -328,7 +421,7 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * session's heap for the rest of its life.
      */
     async fsReadRangeUncached(path, offset, length) {
-        return this._call(this._fsOp('fsReadRangeUncached', [path, offset, length]));
+        return this._call(this._fsRead('fsReadRangeUncached', [path, offset, length]));
     }
     /**
      * Read many ranges in ONE round trip — the read-side counterpart to
@@ -337,8 +430,11 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * A file the caller knows is small is one entry; a large one is a run of
      * entries over the same path.
      *
+     * A request may instead ask for a path's lstat, so a process learning the
+     * metadata of many paths pays one round trip, not one per path.
+     *
      * Entries come back positionally, each carrying exactly what the
-     * equivalent fsReadRange would have returned. The batch is bounded by
+     * equivalent fsReadRange or lstat would have returned. The batch is bounded by
      * FS_READ_BATCH_PATH_LIMIT paths and FS_READ_BATCH_REQUEST_BYTES of
      * requested range, and the supervisor rejects anything past either — never
      * a short result, which a caller could mistake for a short file.
@@ -348,27 +444,33 @@ export class SupervisorRPC extends WorkerEntrypoint {
         // returns at most the range asked for. Counting it keeps the
         // supervisor's heap estimate honest for the duration of the await, the
         // same accounting writeBatch does for its inbound payload.
-        const payloadBytes = requests.reduce((total, request) => total + request.length, 0);
+        const payloadBytes = requests.reduce((total, request) => total + fsReadBatchRequestBytes(request), 0);
         setLastRpcFrame('fsReadBatch', payloadBytes);
         rpcPayloadStart(payloadBytes);
         try {
-            return await this._call(this._fsOp('fsReadBatch', [requests]));
+            return await this._call(this._fsRead('fsReadBatch', [requests]));
         }
         finally {
             rpcPayloadEnd(payloadBytes);
         }
     }
     async fsWriteRange(path, offset, bytes) {
-        return this._call(this._fsOp('fsWriteRange', [path, offset, bytes]));
+        return this._call(this._fsMutation('fsWriteRange', [path, offset, bytes]));
     }
+    /**
+     * An append and its acknowledgement carry the append ledger's own identity
+     * (writer, module incarnation, operation sequence), whose receipt the host
+     * keeps until the acknowledgement: a repeat of either applies nothing twice,
+     * so a dropped one is simply re-sent.
+     */
     async fsAppend(path, moduleId, operationId, bytes) {
-        return this._call(this._op('fsAppend', [path, moduleId, operationId, bytes], { pid: this._pid(), writerId: this._writerId() }));
+        return this._call(this._resent({ op: 'fsAppend', args: [path, moduleId, operationId, bytes], pid: this._pid(), writerId: this._writerId() }));
     }
     async fsAppendAck(moduleId, operationId) {
-        return this._call(this._op('fsAppendAck', [moduleId, operationId], { pid: this._pid(), writerId: this._writerId() }));
+        return this._call(this._resent({ op: 'fsAppendAck', args: [moduleId, operationId], pid: this._pid(), writerId: this._writerId() }));
     }
     async fsTruncate(path, size) {
-        return this._call(this._fsOp('fsTruncate', [path, size]));
+        return this._call(this._fsMutation('fsTruncate', [path, size]));
     }
     /**
      * Bulk-write all inodes + chunks in ONE transactionSync on the supervisor.
@@ -391,7 +493,7 @@ export class SupervisorRPC extends WorkerEntrypoint {
         setLastRpcFrame('writeBatch', payloadBytes);
         rpcPayloadStart(payloadBytes);
         try {
-            return await this._call(this._fsOp('writeBatch', [payload]));
+            return await this._call(this._fsMutation('writeBatch', [payload]));
         }
         finally {
             rpcPayloadEnd(payloadBytes);
@@ -534,7 +636,8 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * it, so a caller-supplied `put` would be a cross-tenant
      * code-execution primitive for anyone holding a supervisor stub. No
      * such RPC exists: the only bytes that reach `pc/<name>.json` are the
-     * ones registry.npmjs.org served for that exact name.
+     * ones registry.npmjs.org served for that exact name; another registry
+     * (`options.registry`, the install's `NPM_REGISTRY`) has its own keys.
      */
     async getPackument(name, options) {
         const r2 = this._r2();
@@ -561,8 +664,8 @@ export class SupervisorRPC extends WorkerEntrypoint {
      * has error state it couldn't stream in-band (rare; main path drains
      * via __pendingIO first).
      */
-    async reportExit(code, tail) {
-        return this._call(this._op('reportExit', [code, tail || ''], { pid: this._reportingPid() }));
+    async reportExit(code, tail, residencyMisses, profileUnread) {
+        return this._call(this._op('reportExit', [code, tail || '', residencyMisses ?? [], profileUnread ?? null], { pid: this._reportingPid() }));
     }
     // ── Prefetch ──────────────────────────────────────────────────────────
     async prefetch(cwd, entryCode) {
@@ -609,11 +712,18 @@ export class SupervisorRPC extends WorkerEntrypoint {
     async cpStdinEnd(childPid) {
         return this._call(this._op('cpStdinEnd', [childPid]));
     }
-    async cpReadStdin(childPid, waitMs) {
-        return this._call(this._op('cpReadStdin', [childPid, waitMs]));
+    /**
+     * The three long polls that deliver to a process — its stdin, and a
+     * child's output and exit — carry the process's ACQUIRE arguments, and a
+     * reply that delivers anything carries the answer for them (`acquired`,
+     * session/rpc.ts `_acquireOnDelivery`), so the process applies it without
+     * asking. The caller's pid names whose credential answers it.
+     */
+    async cpReadStdin(childPid, waitMs, acquire) {
+        return this._call(this._op('cpReadStdin', [childPid, waitMs, acquire ?? null], { pid: this._reportingPid() }));
     }
-    async cpReadOutput(childPid, fd, sinceSeq, waitMs) {
-        return this._call(this._op('cpReadOutput', [childPid, fd, sinceSeq, waitMs]));
+    async cpReadOutput(childPid, fd, sinceSeq, waitMs, acquire) {
+        return this._call(this._op('cpReadOutput', [childPid, fd, sinceSeq, waitMs, acquire ?? null], { pid: this._reportingPid() }));
     }
     async cpDrainOutput(childPid) {
         return this._call(this._op('cpDrainOutput', [childPid]));
@@ -621,8 +731,8 @@ export class SupervisorRPC extends WorkerEntrypoint {
     async cpKill(childPid, signal) {
         return this._call(this._op('cpKill', [childPid, signal]));
     }
-    async cpWait(childPid, waitMs) {
-        return this._call(this._op('cpWait', [childPid, waitMs]));
+    async cpWait(childPid, waitMs, acquire) {
+        return this._call(this._op('cpWait', [childPid, waitMs, acquire ?? null], { pid: this._reportingPid() }));
     }
     /**
      * child-process isolation gap #1: dispatch a single cp.spawn request inline using

package/dist/session/vite-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-command.d.ts","sourceRoot":"","sources":["../../src/session/vite-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyBH,KAAK,QAAQ,GAAG,GAAG,CAAC;AAEpB,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,IAChC,KAAK,GAAG,KAAG,OAAO,CAAC,MAAM,CAAC,CAmlBzC"}
+{"version":3,"file":"vite-command.d.ts","sourceRoot":"","sources":["../../src/session/vite-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyBH,KAAK,QAAQ,GAAG,GAAG,CAAC;AAEpB,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,IAChC,KAAK,GAAG,KAAG,OAAO,CAAC,MAAM,CAAC,CAslBzC"}

package/dist/session/vite-command.js

@@ -15,9 +15,9 @@
 import { normalizeVfsPath, parentVfsPath, resolveVfsPath, stripLeadingSlashes } from '@nimbus-sh/core/vfs/path.js';
 import { errorText } from '@nimbus-sh/core/_shared/error-text.js';
 import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
-import { parseViteConfigSource, viteBuildBlockingPlugins, unhandledVitePlugins } from '@nimbus-sh/core/runtime/vite-config-parser.js';
+import { parseViteConfigSource, parseViteConfigTypeScript, viteBuildBlockingPlugins, unhandledVitePlugins } from '@nimbus-sh/core/runtime/vite-config-parser.js';
 import { findHtmlScriptEntrypoint, rewriteViteBuildHtml } from '../runtime/html-entrypoint.js';
-import { EsbuildService } from '@nimbus-sh/core/runtime/esbuild-service.js';
+import { supervisorEsbuildService } from '../facets/esbuild-transform.js';
 import { ViteDevServer } from '../facets/vite-dev-server.js';
 import { shouldUseRealVite } from '../facets/cirrus-real.js';
 import { makeLongRunningPortStub, resolveLongRunningPort, expandArgvShellDefaults, } from '@nimbus-sh/core/runtime/long-running-handle.js';
@@ -49,15 +49,18 @@ export function createViteCommand(self) {
             const cfgPath = cwd + '/' + cfgName;
             if (kernelFs.exists(cfgPath)) {
                 try {
-                    let cfgCode = kernelFs.readFileString(cfgPath);
-                    // Transform TS to JS
-                    if (cfgName.endsWith('.ts')) {
-                        if (!self.esbuildService)
-                            self.esbuildService = new EsbuildService(kernelFs);
-                        const t = await self.esbuildService.transform(cfgCode, { loader: 'ts', format: 'esm' });
-                        cfgCode = t.code;
-                    }
-                    Object.assign(viteConfig, parseViteConfigSource(cfgCode));
+                    const cfgCode = kernelFs.readFileString(cfgPath);
+                    // A .ts config needs esbuild only when it holds type syntax
+                    // (parseViteConfigTypeScript); a plain one is read as is, so a
+                    // fresh session's `vite` does not wait on the esbuild facet.
+                    const parsed = cfgName.endsWith('.ts')
+                        ? await parseViteConfigTypeScript(cfgCode, async (source) => {
+                            if (!self.esbuildService)
+                                self.esbuildService = supervisorEsbuildService(self.ctx, self.env, self.getFilesystemAuthority().namespaceFs(CRED_KERNEL));
+                            return (await self.esbuildService.transform(source, { loader: 'ts', format: 'esm' })).code;
+                        })
+                        : parseViteConfigSource(cfgCode);
+                    Object.assign(viteConfig, parsed);
                 }
                 catch (e) {
                     ctx.stderr.write(`Warning: could not parse ${cfgName}: ${e?.message}\n`);
@@ -89,7 +92,7 @@ export function createViteCommand(self) {
                     ' (' + buildSkippedPlugins.join(', ') + '); output is the plain-Vite bundle.\n');
             }
             if (!self.esbuildService)
-                self.esbuildService = new EsbuildService(kernelFs);
+                self.esbuildService = supervisorEsbuildService(self.ctx, self.env, self.getFilesystemAuthority().namespaceFs(CRED_KERNEL));
             const htmlPath = cwd + '/index.html';
             let entryPoint = cwd + '/src/main.tsx';
             let origHtml = '';
@@ -295,7 +298,7 @@ export function createViteCommand(self) {
             }
             // Start vite on the dist directory
             if (!self.esbuildService)
-                self.esbuildService = new EsbuildService(kernelFs);
+                self.esbuildService = supervisorEsbuildService(self.ctx, self.env, self.getFilesystemAuthority().namespaceFs(CRED_KERNEL));
             if (self.viteDevServer?.isRunning)
                 self.viteDevServer.stop();
             const previewBasePath = self.viteBasePath;
@@ -502,7 +505,7 @@ export function createViteCommand(self) {
                 ' (' + devSkipped.join(', ') + '); serving the plain-Vite app.\n');
         }
         if (!self.esbuildService)
-            self.esbuildService = new EsbuildService(kernelFs);
+            self.esbuildService = supervisorEsbuildService(self.ctx, self.env, self.getFilesystemAuthority().namespaceFs(CRED_KERNEL));
         const previewBasePath = self.viteBasePath;
         const viteDefine = viteConfig.define;
         // Vite dev servers are represented as long-running process-table

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

@@ -1 +1 @@
-{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/session/ws.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/session/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAQH,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uDAAuD,CAAC;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAG7E;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,mBAAmB,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACnD;;;;8DAI0D;IAC1D,YAAY,CAAC,EAAE,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5C,SAAS,EAAE,wBAAwB,CAAC;IACpC,wBAAwB,EAAE,OAAO,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,GAAG,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,GAAG,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,EAAE,OAAO,0CAA0C,EAAE,YAAY,GAAG,IAAI,CAAC;IACjF,+EAA+E;IAC/E,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvC,eAAe,IAAI,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBnF;AAsDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAStE;AAED;;;;;;;GAOG;AACH,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA6CD,wBAAgB,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,YAAY,CAElD;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA4FzG;AA+CD,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,SAAS,EACb,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,IAAI,CAAC,CAiGf;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CA4EtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAUlD"}

package/dist/session/ws.js

@@ -316,15 +316,27 @@ export async function wsMessage(self, ws, message) {
             return;
         }
         const terminalMessage = TerminalMessageSchema.safeParse(value);
-        if (self.terminal && terminalMessage.success)
-            self.terminal.handleMessage(terminalMessage.data);
+        if (self.terminal && terminalMessage.success) {
+            const terminal = self.terminal;
+            const completion = terminal.handleMessage(terminalMessage.data);
+            if (completion) {
+                const task = completion.catch((error) => {
+                    console.error('[nimbus] terminal input failed:', errorText(error));
+                    terminal.writeln(`terminal input failed: ${errorText(error)}`);
+                }).finally(() => snapshotShellState(self));
+                const ctx = self.ctx;
+                // Hand the command's completion to waitUntil so its failure is observed and
+                // the final snapshot runs, without holding the WebSocket event open or
+                // serializing later input. DurableObjectState.waitUntil does not extend the
+                // object's lifetime (Cloudflare docs, api/state/#waituntil).
+                if (ctx?.waitUntil)
+                    ctx.waitUntil(task);
+                else
+                    await task;
+            }
+        }
         // ── B'.1 snapshot ───────────────────────────────────────────────
-        // Persist Shell state to DO SQLite after the terminal has handled
-        // the user's keystroke. The Shell builtin `cd` mutates this.cwd
-        // synchronously inside executeLine, so by the time we reach this
-        // line a `cd example-app\r` has already taken effect and we capture the
-        // new cwd. Cheap when nothing has changed; SESSION_ENV_MAX_BYTES
-        // is the only failure mode and is logged, not thrown.
+        // Capture immediate keystroke changes; async input completion takes a final snapshot above.
         snapshotShellState(self);
     }
     catch (e) {