@nimbus-sh/worker 0.5.0 → 0.7.0

package/dist/session/programmatic.js

@@ -11,15 +11,17 @@ import { PID_GEN_STRIDE } from '@nimbus-sh/core/runtime/process-table.js';
 import { notifyTerminalEvent } from '../runtime/process-logs-api.js';
 import { SessionProcessSupervisor } from '@nimbus-sh/core/runtime/session-process-supervisor.js';
 import { PortRegistry, createPortCapability } from '@nimbus-sh/core/runtime/port-registry.js';
-import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
+import { CRED_KERNEL, requireVfsCred } from '@nimbus-sh/core/runtime/os-contracts.js';
 import { endProcessInput, resizeProcess, signalProcess, writeProcessInput, } from '@nimbus-sh/core/runtime/process-input-routing.js';
 import { z } from 'zod/v4';
 import { SESSION_DESTROYED_KEY, SHELL_STATE_KEY_PREFIX, VITE_CONFIG_KEY } from './keys.js';
-import { clearPortCapability, persistPortCapability, PortRecordSchema, portRecordKey, readPortReservation, reservePort, restorePortCapability, } from './port-capability.js';
-import { PORT_CAPABILITY_KEY_PREFIX } from './keys.js';
+import { clearPortCapability, isValidAppName, persistPortCapability, portRecordKey, readPortReservation, readPortReservationByName, readPortReservationByOwner, reservePort, restorePortCapability, rotatePortCapability, } from './port-capability.js';
 import { bindPublicPortCapability, unbindPublicPortCapability } from '../router/public-directory.js';
+import { buildPreviewHost, buildPublicPreviewHost, isPreviewHostSafeSid, readPreviewHostSuffix, } from '../_shared/preview-host.js';
+import { RESTART_POLICY_ENV } from '../facets/manager.js';
 import { GENERATION_KEY, assumeGeneration, generation } from '@nimbus-sh/fabric/generation.js';
 import { HeadlessTerminal, Shell } from '@nimbus-sh/core/substrate/lifo/index.js';
+import { textSink } from '@nimbus-sh/core/_shared/bytes.js';
 const ShellIdSchema = z.string().min(1).max(160).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
 const ShellStateSchema = z.object({
     cwd: z.string().startsWith('/'),
@@ -216,14 +218,13 @@ function startShellJob(self, command, options, job, scoped) {
         catch { /* already settled */ }
     });
     const emit = (stream, sink) => (data) => {
-        const text = String(data);
         if (job.background) {
             try {
-                self.processes.appendOutput(pid, stream, text);
+                self.processes.appendOutputBytes(pid, stream, data);
             }
             catch { /* ring gone */ }
         }
-        sink?.(text);
+        sink?.(data);
     };
     const run = shell.execute(line, {
         // A named shell already holds its own cwd and env; passing them again
@@ -259,7 +260,20 @@ function startShellJob(self, command, options, job, scoped) {
         }
         catch { } } };
 }
+/**
+ * The shell, process table and VFS all key on absolute POSIX paths. A
+ * relative `cwd` arriving here means a caller skipped its own boundary
+ * normalization (the SDK resolves it); handed to the shell it degrades to
+ * silently wrong cwd semantics and ENOENT writes. Name the field and fail.
+ */
+function assertAbsoluteExecCwd(options) {
+    const cwd = options.cwd;
+    if (cwd !== undefined && (typeof cwd !== 'string' || !cwd.startsWith('/'))) {
+        throw new Error(`cwd must be an absolute POSIX path starting with '/', got ${JSON.stringify(cwd)}`);
+    }
+}
 export async function rpcExec(self, command, options = {}) {
+    assertAbsoluteExecCwd(options);
     await ensureProgrammaticReady(self, options);
     return withShellState(self, options, false, (scoped) => execOnShell(self, command, options, scoped));
 }
@@ -271,8 +285,8 @@ async function execOnShell(self, command, options, scoped) {
     let timedOut = false;
     const job = startShellJob(self, command, options, {
         background: false,
-        onStdout: (d) => stdout.push(d),
-        onStderr: (d) => stderr.push(d),
+        onStdout: textSink((d) => stdout.push(d)),
+        onStderr: textSink((d) => stderr.push(d)),
     }, scoped);
     let result;
     try {
@@ -351,8 +365,18 @@ function collectJobOutput(self, pid) {
  * process surface (`listProcesses`, `processLogs`, `killProcess`).
  */
 export async function rpcStartProcess(self, command, options = {}) {
+    assertAbsoluteExecCwd(options);
     await ensureProgrammaticReady(self, options);
-    return withShellState(self, options, true, (scoped) => startOnShell(self, command, options, scoped));
+    if (options.restart !== undefined && options.restart !== 'never' && options.restart !== 'on-failure') {
+        throw new Error(`startProcess: restart must be 'never' or 'on-failure', got ${String(options.restart)}`);
+    }
+    // The policy rides the command's environment: the resident the command
+    // starts reads it off its env at launch and journals it, so the shell,
+    // the SDK and a child_process spawn all carry it the same way.
+    const withPolicy = options.restart === 'on-failure'
+        ? { ...options, env: { ...(options.env ?? {}), [RESTART_POLICY_ENV]: 'on-failure' } }
+        : options;
+    return withShellState(self, withPolicy, true, (scoped) => startOnShell(self, command, withPolicy, scoped));
 }
 async function startOnShell(self, command, options, scoped) {
     const job = startShellJob(self, command, options, { background: true }, scoped);
@@ -397,7 +421,15 @@ async function startOnShell(self, command, options, scoped) {
  * the handoff, the facet is the live process, and it reports its own exit.
  */
 function finishBackgroundJob(self, pid, command, exitCode) {
-    if (exitCode === 0 && self.facetManager?.hasResidentProcess(pid))
+    // The shell line returned, but the pid may still be serving: a resident
+    // facet the node runner handed off under this pid, or an in-process dev
+    // server a builtin (`vite`) adopted this pid for and registered a port
+    // under. Either way the process is alive — marking it exited would put a
+    // dead pid on a live port, and the app verbs identify a server by the pid
+    // serving its port.
+    const stillServing = self.facetManager?.hasResidentProcess(pid) === true
+        || self.portRegistry.getAll().some((live) => live.pid === pid);
+    if (exitCode === 0 && stillServing)
         return;
     self.processes.exit(pid, exitCode);
     if (!self.processes.getExit(pid))
@@ -517,52 +549,380 @@ export async function rpcProcessLogs(self, pid, options = {}) {
 }
 export async function rpcListPorts(self) {
     await ensureProgrammaticReady(self);
-    const entries = self.portRegistry.getAll();
-    // Persisted at the moment the embedder is told the value, not at
-    // registration: a capability nobody has been handed does not need to
-    // survive anything.
-    await Promise.all(entries.map((entry) => persistPortCapability(self, entry.port, entry.capability)));
-    return entries.map(serializePort);
+    // The composed manager's copy is the one implementation — persistence
+    // at tell-time included.
+    return self.ensureFacetManager().apps.listPorts();
 }
+/**
+ * Browser-facing URL for an application, built inside the session: the
+ * host form when the deployment carries a preview suffix (name first, port
+ * otherwise; the public bearer form when public and a capability exists),
+ * else the path form on the origin the session was last reached at. Null
+ * when the session has never been reached over HTTP and has no suffix —
+ * an embedder builds its own from the port and capability in that case.
+ */
+export function appUrl(self, app) {
+    const sid = sessionIdOf(self);
+    const suffix = readPreviewHostSuffix(self.env);
+    if (suffix !== null && sid !== null && isPreviewHostSafeSid(sid)) {
+        const label = app.name ?? app.port;
+        if (app.visibility === 'public' && typeof app.capability === 'string') {
+            return `https://${buildPublicPreviewHost(sid, label, app.capability, suffix)}/`;
+        }
+        return `https://${buildPreviewHost(sid, label, suffix)}/`;
+    }
+    const origin = self.sessionOrigin;
+    if (!origin || sid === null)
+        return null;
+    const base = self.sessionBasePath || `/s/${sid}`;
+    return app.name ? `${origin}${base}/app/${app.name}/` : `${origin}${base}/port/${app.port}/`;
+}
+/** The sid this DO serves: the last segment of its name, `tn:sub:sid`. */
+function sessionIdOf(self) {
+    const name = self.ctx.id?.name;
+    if (typeof name === 'string' && name.length > 0) {
+        const cut = name.lastIndexOf(':');
+        if (cut > 0)
+            return name.slice(cut + 1);
+    }
+    const fromBase = (self.sessionBasePath || '').replace(/^\/s\//, '');
+    return fromBase.length > 0 ? fromBase : null;
+}
+/**
+ * The port-centric surface, kept for every caller that has a port and
+ * nothing else — a dev server or a process outside the
+ * resident lifecycle. When the port's occupant carries an identity the
+ * exposure is the same lazy reservation `apps.expose` makes; when it does
+ * not, this compatibility path writes the row port-only, as before. One implementation:
+ * `applyExposure` below.
+ */
 export async function rpcExposePort(self, port, options) {
     await ensureProgrammaticReady(self);
     const n = Number(port);
     const entry = self.portRegistry.get(n);
-    if (entry)
-        await persistPortCapability(self, n, entry.capability);
-    // The stored record decides visibility: a reservation's mark is sticky,
-    // so 'public' survives persists of unrelated fields — and the caller's
-    // explicit choice, when given, lands on the row the same way.
-    if (options?.visibility !== undefined) {
-        // A visibility choice is a write on the stored row, not a reservation
-        // claim: owner and capability stay exactly as they were.
-        await self.ctx.storage.transaction(async (txn) => {
-            const stored = await readPortReservation({ storage: txn }, n);
-            if (stored !== null && stored.visibility !== options.visibility) {
-                await txn.put(portRecordKey(n), {
+    const identity = entry === undefined ? null : await self.facetManager.residentIdentity(entry.pid);
+    if (identity?.ephemeral) {
+        throw new Error(`port ${n} is served by the second instance of its program, which is not the durable one`);
+    }
+    const exposed = await applyExposure(self, n, identity?.owner ?? null, options ?? {});
+    return {
+        port: n,
+        listening: !!entry,
+        pid: entry?.pid ?? null,
+        registeredAt: entry?.registeredAt ?? null,
+        capability: exposed.capability,
+        visibility: exposed.visibility,
+        owner: exposed.owner,
+        name: exposed.name,
+    };
+}
+/**
+ * The identity-centric surface: the target names a running application —
+ * by port, by pid, or by name — and the exposure is what makes it durable
+ * under its identity: the port is reserved for the owner lazily, the
+ * capability minted when public and bound in the directory, the name
+ * stored on the reservation. Returns the address the caller can reach.
+ */
+export async function rpcExposeApp(self, target, options = {}) {
+    await ensureProgrammaticReady(self);
+    const resolved = await resolveAppTarget(self, target);
+    if (resolved.port === null) {
+        throw new Error(`${describeTarget(target)} has not bound a port yet — expose it once it is listening`);
+    }
+    if (resolved.owner === null) {
+        // Every running process has an identity, so this is only a port nothing
+        // serves and no reservation names.
+        throw new Error(`nothing is serving ${describeTarget(target)} — start the server, then expose it`);
+    }
+    const exposed = await applyExposure(self, resolved.port, resolved.owner, options);
+    const live = self.portRegistry.get(resolved.port);
+    return {
+        owner: resolved.owner,
+        name: exposed.name,
+        port: resolved.port,
+        pid: live?.pid ?? null,
+        capability: exposed.capability,
+        visibility: exposed.visibility,
+        url: appUrl(self, { port: resolved.port, ...exposed }),
+    };
+}
+/**
+ * The one exposure implementation. With an owner: reserve the port for it
+ * (a conflict if another owner holds it), carrying the name and visibility
+ * onto the reservation and adopting the live capability so the URL in
+ * circulation is the one the reservation re-adopts after a reset; public
+ * exposures mint a capability if none is live yet and bind the directory.
+ * Without an owner: the row is written port-only, exactly as `exposePort`
+ * always did.
+ */
+async function applyExposure(self, port, owner, options) {
+    if (options.name !== undefined && !isValidAppName(options.name)) {
+        throw new Error(`'${options.name}' is not a valid app name: one DNS label, not all digits, not 24 hex`);
+    }
+    const entry = self.portRegistry.get(port);
+    if (owner !== null) {
+        await assertServingOwner(self, port, owner);
+        const occupied = new Set(self.portRegistry.getAll().map((live) => live.port));
+        occupied.delete(port);
+        await reservePort(self.ctx, {
+            owner,
+            kind: 'derived',
+            preferredPort: port,
+            occupiedPorts: occupied,
+            ...(entry !== undefined ? { capability: entry.capability } : {}),
+            ...(options.visibility !== undefined ? { visibility: options.visibility } : {}),
+            ...(options.name !== undefined ? { name: options.name } : {}),
+        });
+    }
+    else {
+        if (entry)
+            await persistPortCapability(self, port, entry.capability);
+        // A visibility or name choice is a write on the stored row, not a
+        // reservation claim: owner and capability stay exactly as they were.
+        if (options.visibility !== undefined || options.name !== undefined) {
+            await self.ctx.storage.transaction(async (txn) => {
+                const stored = await readPortReservation({ storage: txn }, port);
+                if (stored === null)
+                    return;
+                const visibility = options.visibility ?? stored.visibility;
+                const name = options.name ?? stored.name;
+                if (visibility === stored.visibility && name === stored.name)
+                    return;
+                await txn.put(portRecordKey(port), {
                     owner: stored.owner,
+                    kind: stored.kind,
                     capability: stored.capability,
-                    visibility: options.visibility,
+                    visibility,
+                    ...(name !== undefined ? { name } : {}),
                 });
-            }
+            });
+        }
+    }
+    let record = await readPortReservation(self.ctx, port);
+    if (record?.visibility === 'public' && record.capability === null && owner !== null) {
+        // Public before the application has bound: mint now, so the URL exists
+        // and the binding re-adopts it, exactly as ensureDurableApp does.
+        await reservePort(self.ctx, {
+            owner, preferredPort: port, occupiedPorts: new Set(), capability: createPortCapability(),
         });
+        record = await readPortReservation(self.ctx, port);
     }
-    const record = await readPortReservation(self.ctx, n);
-    if (record?.visibility === 'public' && entry) {
+    // The live registration must answer the stored capability, or a URL
+    // minted before the bind 404s until the next restore.
+    if (record?.capability !== null && record?.capability !== undefined) {
+        const capability = record.capability;
+        if (record.owner !== null) {
+            await assertServingOwner(self, port, record.owner, () => self.portRegistry.restoreCapability(port, capability));
+        }
+        else {
+            self.portRegistry.restoreCapability(port, capability);
+        }
+    }
+    if (record?.visibility === 'public' && record.capability !== null) {
         // A port that goes public must be resolvable: the capability the URL
         // carries has to name this session in the directory, and a non-legacy
         // deployment without the binding is refused loudly — never half-public.
-        await bindPublicPortCapability(self, entry.capability, n);
+        await bindPublicPortCapability(self, record.capability, port, record.name);
     }
     return {
-        port: n,
-        listening: !!entry,
-        pid: entry?.pid ?? null,
-        registeredAt: entry?.registeredAt ?? null,
-        capability: entry?.capability ?? null,
+        owner: record?.owner ?? owner,
+        name: record?.name ?? null,
+        capability: record?.capability ?? entry?.capability ?? null,
         visibility: record?.visibility ?? 'scoped',
     };
 }
+/**
+ * Mint a new capability for the application and rebind the directory:
+ * every URL built on the old one stops resolving. The registry adopts the
+ * new value at once if the port is live, so the new URL answers without
+ * waiting for a restore.
+ */
+export async function rpcRotateLink(self, target) {
+    await ensureProgrammaticReady(self);
+    const resolved = await resolveAppTarget(self, target);
+    if (resolved.port === null || resolved.reservation === null) {
+        throw new Error(`${describeTarget(target)} is not exposed — nothing to rotate`);
+    }
+    const previous = resolved.reservation;
+    if (previous.owner !== null)
+        await assertServingOwner(self, resolved.port, previous.owner);
+    if (previous.visibility === 'public' && previous.capability !== null) {
+        await unbindPublicPortCapability(self, previous.capability);
+    }
+    if (previous.owner !== null)
+        await assertServingOwner(self, resolved.port, previous.owner);
+    const capability = await rotatePortCapability(self, resolved.port, createPortCapability());
+    if (capability === null)
+        throw new Error(`${describeTarget(target)} is not exposed — nothing to rotate`);
+    if (previous.owner !== null) {
+        await assertServingOwner(self, resolved.port, previous.owner, () => self.portRegistry.restoreCapability(resolved.port, capability));
+    }
+    else {
+        self.portRegistry.restoreCapability(resolved.port, capability);
+    }
+    if (previous.visibility === 'public') {
+        await bindPublicPortCapability(self, capability, resolved.port, previous.name);
+    }
+    const live = self.portRegistry.get(resolved.port);
+    return {
+        owner: resolved.owner ?? previous.owner ?? '',
+        name: previous.name ?? null,
+        port: resolved.port,
+        pid: live?.pid ?? null,
+        capability,
+        visibility: previous.visibility,
+        url: appUrl(self, { port: resolved.port, name: previous.name, capability, visibility: previous.visibility }),
+    };
+}
+/** A name or owner identifies a reservation, never whoever happens to occupy its port. */
+async function assertServingOwner(self, port, owner, adopt) {
+    for (;;) {
+        const live = self.portRegistry.get(port);
+        if (live === undefined)
+            return;
+        const identity = await self.facetManager.residentIdentity(live.pid);
+        if (self.portRegistry.get(port)?.pid !== live.pid)
+            continue;
+        if (identity?.owner !== owner || identity.ephemeral) {
+            throw new Error(`port ${port} is served by a different process (owner ${identity?.owner ?? 'none'})`);
+        }
+        adopt?.();
+        return;
+    }
+}
+/** Every stamped identity, with the URL each is reachable at. */
+export async function rpcListApps(self) {
+    await ensureProgrammaticReady(self);
+    const apps = await self.facetManager.listResidentApps();
+    return apps.map((app) => ({
+        ...app,
+        url: app.port === null ? null : appUrl(self, { ...app, port: app.port }),
+    }));
+}
+/**
+ * End an application: kill its live pids, release the reservation, purge
+ * its journal rows, free the durable slot and its storage, unbind the
+ * directory — `removeDurableApp`, addressed by any target.
+ */
+export async function rpcRemoveApp(self, target) {
+    await ensureProgrammaticReady(self);
+    const resolved = await resolveAppTarget(self, target);
+    if (resolved.owner === null) {
+        throw new Error(`${describeTarget(target)} names no application — nothing to remove`);
+    }
+    const owner = resolved.owner;
+    // The manager's removal kills what the journal knows. A server nothing
+    // journalled — the dev servers above all — is found the way every verb
+    // finds it, by the identity of the pid serving a port, and ended through
+    // the session's own kill, which is the one that also stops an in-process
+    // dev server rather than only marking its pid dead.
+    const fm = self.facetManager;
+    let killed = 0;
+    for (const live of self.portRegistry.getAll()) {
+        const identity = await fm.residentIdentity(live.pid);
+        if (identity === null || identity.ephemeral || identity.owner !== owner)
+            continue;
+        if ((await rpcKillProcess(self, live.pid)).ok)
+            killed += 1;
+    }
+    const durable = await rpcRemoveDurableApp(self, owner);
+    return { ...durable, removed: durable.removed || killed > 0 };
+}
+function describeTarget(target) {
+    if (typeof target === 'number')
+        return `target ${target}`;
+    if (typeof target === 'string')
+        return `'${target}'`;
+    if ('port' in target)
+        return `port ${target.port}`;
+    if ('pid' in target)
+        return `pid ${target.pid}`;
+    if ('name' in target)
+        return `app '${target.name}'`;
+    return `owner '${target.owner}'`;
+}
+/**
+ * Resolve an app target to what the verbs need: the owner (from the
+ * serving pid's journal row, or the reservation), the port, and the
+ * reservation if one exists. A bare number is a port when something
+ * listens on it or a reservation names it, else a pid; a string is a name
+ * first, then an owner.
+ */
+async function resolveAppTarget(self, target) {
+    const fm = self.facetManager;
+    const byPort = async (port) => {
+        const live = self.portRegistry.get(port);
+        const reservation = await readPortReservation(self.ctx, port);
+        const identity = live === undefined ? null : await fm.residentIdentity(live.pid);
+        if (identity?.ephemeral) {
+            throw new Error(`port ${port} is served by the second instance of its program, which is not the durable one`);
+        }
+        return { owner: identity?.owner ?? reservation?.owner ?? null, port, reservation };
+    };
+    const byPid = async (pid) => {
+        const identity = await fm.residentIdentity(pid);
+        if (identity === null)
+            return null;
+        if (identity.ephemeral) {
+            throw new Error(`pid ${pid} is the second instance of its program, which is not the durable one`);
+        }
+        const port = self.portRegistry.getAll().find((live) => live.pid === pid)?.port ?? identity.port ?? null;
+        const reservation = port === null ? null : await readPortReservation(self.ctx, port);
+        return { owner: identity.owner ?? null, port, reservation };
+    };
+    const byOwner = async (owner) => {
+        const held = await readPortReservationByOwner(self.ctx, owner);
+        if (held !== null)
+            return { owner, port: held.port, reservation: held.reservation };
+        const app = (await fm.listResidentApps()).find((candidate) => candidate.owner === owner);
+        return app === undefined ? null : { owner, port: app.port, reservation: null };
+    };
+    const byName = async (name) => {
+        const held = await readPortReservationByName(self.ctx, name);
+        return held === null ? null : { owner: held.reservation.owner, port: held.port, reservation: held.reservation };
+    };
+    if (typeof target === 'number') {
+        if (!Number.isInteger(target) || target <= 0)
+            throw new Error(`target ${target} is not a port or a pid`);
+        if (self.portRegistry.has(target) || (await readPortReservation(self.ctx, target)) !== null) {
+            return byPort(target);
+        }
+        const asPid = await byPid(target);
+        if (asPid !== null)
+            return asPid;
+        if (target <= 65535)
+            return byPort(target);
+        throw new Error(`nothing listens on port ${target} and no process ${target} exists`);
+    }
+    if (typeof target === 'string') {
+        const asName = await byName(target);
+        if (asName !== null)
+            return asName;
+        const asOwner = await byOwner(target);
+        if (asOwner !== null)
+            return asOwner;
+        throw new Error(`no application is named or owned '${target}'`);
+    }
+    if ('port' in target)
+        return byPort(Number(target.port));
+    if ('pid' in target) {
+        const asPid = await byPid(Number(target.pid));
+        if (asPid === null) {
+            throw new Error(`pid ${target.pid} is not running and has no launch record`);
+        }
+        return asPid;
+    }
+    if ('name' in target) {
+        const asName = await byName(target.name);
+        if (asName === null)
+            throw new Error(`no application is named '${target.name}'`);
+        return asName;
+    }
+    const asOwner = await byOwner(target.owner);
+    if (asOwner === null)
+        throw new Error(`no application is owned by '${target.owner}'`);
+    return asOwner;
+}
 /**
  * The embedder's durable-application seam: reserve (or re-answer) the port
  * `owner` holds, minting the capability the application's public URL is
@@ -573,32 +933,10 @@ export async function rpcExposePort(self, port, options) {
  */
 export async function rpcEnsureDurableApp(self, input) {
     await ensureProgrammaticReady(self);
-    const owner = input.owner;
-    if (typeof owner !== 'string' || owner.length === 0) {
-        throw new Error('ensureDurableApp: owner must be a non-empty string');
-    }
-    const occupied = new Set(self.portRegistry.getAll().map((entry) => entry.port));
-    const port = await reservePort(self.ctx, {
-        owner,
-        preferredPort: input.preferredPort,
-        occupiedPorts: occupied,
-        // Minted here, not at boot: the URL is built from this capability, and
-        // re-drive re-adopts it out of the same row.
-        capability: createPortCapability(),
-        ...(input.visibility !== undefined ? { visibility: input.visibility } : {}),
-    });
-    const record = await readPortReservation(self.ctx, port);
-    if (record?.visibility === 'public' && record.capability !== null) {
-        // The URL is built on this capability before the app has ever run:
-        // publish it to the directory now, loudly refusing a deployment whose
-        // binding is missing rather than minting an unroutable URL.
-        await bindPublicPortCapability(self, record.capability, port);
-    }
-    return {
-        port,
-        capability: record?.capability ?? null,
-        visibility: record?.visibility ?? 'scoped',
-    };
+    // The composed manager owns the durable-app verbs — one implementation,
+    // capability minted there so a URL handed out before boot is the one the
+    // eventual binding re-adopts.
+    return self.ensureFacetManager().apps.ensureDurableApp(input);
 }
 export async function rpcUnexposePort(self, port) {
     await ensureProgrammaticReady(self);
@@ -621,26 +959,8 @@ export async function rpcUnexposePort(self, port) {
  */
 export async function rpcRemoveDurableApp(self, owner) {
     await ensureProgrammaticReady(self);
-    if (typeof owner !== 'string' || owner.length === 0) {
-        throw new Error('removeDurableApp: owner must be a non-empty string');
-    }
-    // Which durable address is being released — the reservation's row names it
-    // before the manager retires it.
-    const rows = await self.ctx.storage.list({ prefix: PORT_CAPABILITY_KEY_PREFIX });
-    let port = null;
-    for (const [key, record] of rows) {
-        const parsed = PortRecordSchema.safeParse(record);
-        if (!parsed.success || parsed.data.owner !== owner)
-            continue;
-        const n = Number(key.slice(PORT_CAPABILITY_KEY_PREFIX.length));
-        if (Number.isInteger(n) && n > 0) {
-            port = n;
-            break;
-        }
-    }
-    self.ensureFacetManager();
-    const removed = await self.facetManager.removeDurableApp(owner);
-    return { owner, removed, port };
+    // The composed manager owns the durable-app verbs — validation included.
+    return self.ensureFacetManager().apps.removeDurableApp(owner);
 }
 /**
  * Route an embedder request that carries a port capability. The embedder has
@@ -658,10 +978,34 @@ export async function rpcRouteCapabilityPort(self, port, capability, request, pa
     const routed = await self.portRegistry.routeCapabilityRequest(Number(port), String(capability), request, pathname);
     return routed ?? new Response('Not found', { status: 404 });
 }
-export async function rpcDeleteFile(self, path, options = {}) {
+/**
+ * `spawnWorker` for a colocated embedder holding the DO stub: boot the
+ * embedder's own Worker-class program — its main module, inline modules and
+ * content-addressed text/wasm modules — as one of this session's resident
+ * processes, and answer with the pid, the runner's boot payload and the
+ * process's facet (`fetch`/`connect`, bound to the resident handle; no
+ * release — `killProcess(pid)` ends it). Deliberately absent from the remote
+ * HTTP dispatcher: the facet is a live handle, and a remote token holder is
+ * not the embedder.
+ */
+export async function rpcSpawnWorker(self, workerCode, command, cwd, opts = {}) {
+    await ensureProgrammaticReady(self);
+    if (typeof workerCode !== 'string' || workerCode.length === 0) {
+        throw new Error('spawnWorker: workerCode must be a non-empty string');
+    }
+    self.ensureFacetManager();
+    return self.facetManager.spawnWorker(workerCode, String(command), String(cwd), opts);
+}
+/**
+ * `files.delete`. Absent a `cred` this acts as CRED_KERNEL — what it has
+ * always done, and the embedder's trusted surface: only a caller holding the
+ * DO binding reaches it. A `cred` binds the removal to that identity instead,
+ * the same view `SqliteVFS.as(cred)` gives in-process.
+ */
+export async function rpcDeleteFile(self, path, options = {}, cred) {
     await ensureProgrammaticReady(self);
     const p = String(path).replace(/^\/+/, '');
-    const vfs = self.sqliteFs.as(CRED_KERNEL);
+    const vfs = self.sqliteFs.as(cred === undefined ? CRED_KERNEL : requireVfsCred(cred, 'files.delete'));
     if (!vfs.exists(p))
         return;
     if (vfs.isDirectory(p)) {
@@ -887,17 +1231,23 @@ function resetInMemorySessionState(self) {
     self.shell = null;
     self.shellProcessPid = null;
     self.terminal = null;
-    self.facetManager = null;
+    self.facetManagerComposed = null;
     self.facetProcessManager = null;
     self.esbuildService = null;
     self.viteDevServer = null;
+    // The installer's pre-bundler and the dev server's on-demand path share
+    // this pool; it goes when both of them go.
+    try {
+        self.bundlePool?.dispose();
+    }
+    catch { }
+    self.bundlePool = null;
     self.cirrusReal = null;
     self._cirrusHmrWsClients = null;
     self.nimbusWrangler = null;
     self.npmInstaller = null;
     self.fetchProxyEntrypoint = null;
-    self.runtimeFsBridges?.clear();
-    self.runtimeFsBridges = null;
+    self._supervisorOps = null;
     self._cpRegistry = null;
     self._viteShimPid = null;
     self._viteShimPort = null;