@nimbus-sh/worker 0.5.0 → 0.7.0

package/dist/facets/manager.d.ts

@@ -19,11 +19,13 @@ import type { ProcessEntry } from '@nimbus-sh/core/runtime/process-table.js';
 import { SessionProcessSupervisor } from '@nimbus-sh/core/runtime/session-process-supervisor.js';
 import type { CredentialedVfs, SqliteVFS, VfsStat } from '@nimbus-sh/core/vfs/sqlite-vfs.js';
 import type { PortRegistry } from '@nimbus-sh/core/runtime/port-registry.js';
+import { type PortVisibility } from '../session/port-capability.js';
 import { TurnBudget } from '@nimbus-sh/fabric/turn-budget.js';
 import { EsbuildService, type TransformResult } from '@nimbus-sh/core/runtime/esbuild-service.js';
 import { type ProcessHostFactory, type ResidentCodeSpec } from '@nimbus-sh/fabric/process-fabric.js';
 import { type OpencodeRunnerOptions } from '../runtime/opencode-facet-runner.js';
 import { type FacetBundleProfile } from '@nimbus-sh/core/runtime/bundle-profile.js';
+import { type WasmImageRecord } from './wasm-image-digest.js';
 type EsbuildTransformOptions = NonNullable<Parameters<EsbuildService['transform']>[1]>;
 type LargeEsmTransform = (code: string, options: EsbuildTransformOptions) => Promise<TransformResult>;
 /** Result returned from a facet execution */
@@ -74,34 +76,6 @@ export interface StagedArtifactExecResult extends FacetExecResult {
     /** For the resident server path: the loopback port the facet is bound to. */
     port?: number;
 }
-/**
- * Reserve held back from a one-shot facet's lifetime so a program that runs
- * out of time is still alive to say so.
- *
- * A one-shot exec is ALREADY bounded: `_execWithTimeout` kills it at
- * FACET_TIMEOUT_MS with exit 124 and "[process killed: timeout after 30s]".
- * The entry drain must therefore not be a second, tighter, independent
- * timeout. Measured against a deployed Worker, floating async work of 5s /
- * 15s / 25s completes and 40s is killed by that outer bound at exactly 30s —
- * so the fixed 8s budget this used to carry was abandoning programs 22
- * seconds before anything actually required it.
- *
- * The drain therefore runs to the outer bound MINUS this reserve, which is
- * what buys the facet time to flush and report the honest "still in flight"
- * reason instead of the supervisor's generic kill. The reserve has to cover
- * the longest tail a facet can have after the drain: settling pending RPC,
- * writing back __vfsWrites (bounded by MAX_RPC_SAFE_PAYLOAD_BYTES; a 20 MiB
- * write-back measures ~1.5s), draining children, then reportExit.
- */
-export declare const ONE_SHOT_EXIT_RESERVE_MS = 3000;
-/**
- * Budget used when the supervisor did not stamp an absolute deadline on the
- * payload. The deadline is the real bound — see `entryDeadlineAt` — because
- * it is measured from the supervisor's own timer rather than restarted when
- * the drain begins, so a slow module init cannot push the drain past the kill
- * and lose the honest message.
- */
-export declare const ONE_SHOT_ENTRY_DEADLINE_MS: number;
 /**
  * How long a RESIDENT facet settles its startup before answering its boot
  * call. It keeps running afterwards, so this is not a lifetime decision: the
@@ -117,8 +91,11 @@ export declare const RESIDENT_BOOT_SETTLE_MS = 1000;
  * servers, requests in flight. A promise is not a handle: a program whose
  * last act leaves `new Promise(() => {})` unsettled prints its output and
  * exits 0. Counting unsettled promises as work was a real divergence from
- * that — such a program burned the whole facet lifetime and was then
- * reported as having not finished.
+ * that — such a program's drain used to end early and it was
+ * reported as having not finished. A user-invoked program runs this loop
+ * with NO deadline — Node itself has no wall-clock kill; the only endings
+ * are the program's exit and a signal. Callers that still pass a finite
+ * deadline (the resident boot settle) arm the expiry timer.
  *
  * Three kinds of handle, each owned by the shim that creates them:
  *
@@ -131,19 +108,12 @@ export declare const RESIDENT_BOOT_SETTLE_MS = 1000;
  *   - listening SERVERS (`__portRegistry`), open until the program closes
  *     them.
  *
- * The bound is a REAL wall-clock deadline, armed as a timer rather than
- * compared against `Date.now()`: a `setTimeout(0)` turn in workerd costs
- * ~5µs, so the pass budget this loop used to carry (50k) expired after
- * ~150ms and silently overrode every longer deadline the callers declared —
- * anything slower than that, including an ordinary network fetch, was
- * abandoned mid-flight and reported as a clean exit.
- *
  * The loop subscribes to the exit promise ONCE — a per-pass
  * `exitPromise.then()` allocates a promise every iteration — and yields
  * through the raw setTimeout so its own ticks don't inflate the timer count
  * it watches.
  */
-export declare const ENTRYPOINT_EVENT_LOOP = "\nfunction __nimbusHandleCount(__name) {\n  const __value = globalThis[__name];\n  return typeof __value === \"number\" ? __value : 0;\n}\n\n// Work an entrypoint's STARTUP has to settle before it can be called booted.\nfunction __nimbusPendingStartupWork() {\n  return __nimbusHandleCount(\"__nimbusPendingTimers\") + __nimbusHandleCount(\"__nimbusPendingOps\");\n}\n\n// The above, plus the handles a program holds open on purpose. A bound port\n// keeps a Node process alive, and it keeps a one-shot facet alive too.\nfunction __nimbusLiveHandles() {\n  const __servers = globalThis.__portRegistry;\n  const __bound = __servers && typeof __servers.size === \"number\" ? __servers.size : 0;\n  return __nimbusPendingStartupWork() + __bound;\n}\n\nasync function __nimbusRunEventLoop(__countHandles, __exitPromise, __deadlineMs, __minPasses) {\n  let __exited = false;\n  if (__exitPromise && typeof __exitPromise.then === \"function\") {\n    __exitPromise.then(() => { __exited = true; }, () => { __exited = true; });\n  }\n  const __rawSetTimeout = (typeof globalThis.__nimbusRawSetTimeout === \"function\")\n    ? globalThis.__nimbusRawSetTimeout\n    : globalThis.setTimeout;\n  const __rawClearTimeout = (typeof globalThis.__nimbusRawClearTimeout === \"function\")\n    ? globalThis.__nimbusRawClearTimeout\n    : globalThis.clearTimeout;\n  let __expired = false;\n  const __deadline = __rawSetTimeout(() => { __expired = true; }, __deadlineMs);\n  let __pass = 0;\n  while (!__exited && !__expired && (__pass < __minPasses || __countHandles() > 0)) {\n    // The warm-up passes give a settling microtask chain its turns and cost\n    // ~5\u00B5s each; past them the loop is waiting on wall-clock work, where\n    // spinning at 0ms would burn the isolate's CPU for the whole deadline.\n    await new Promise((resolve) => __rawSetTimeout(resolve, __pass < __minPasses ? 0 : 1));\n    __pass++;\n  }\n  try { __rawClearTimeout(__deadline); } catch {}\n  // `pending` is what the caller reports when it gives up: a one-shot program\n  // still holding a handle did NOT finish, and exiting 0 would claim it did.\n  return { passes: __pass, pending: __exited ? 0 : __countHandles() };\n}\n\n// An ESM entry's own evaluation promise (top-level await) is the one promise\n// that IS a handle \u2014 the module has not finished loading until it settles.\n// Answers true when process.exit won the race instead.\nasync function __nimbusAwaitEntryEvaluation(__entryResult) {\n  if (!__entryResult || typeof __entryResult.then !== \"function\") return false;\n  const __exit = {};\n  const __raced = await Promise.race([\n    __entryResult.then(() => null),\n    __nimbusProcessExitPromise.then(() => __exit, () => __exit),\n  ]);\n  return __raced === __exit;\n}\n\n// A one-shot facet's lifetime IS the loop: it runs the program until Node\n// would exit, or until the lifetime budget runs out.\nasync function __nimbusRunEntrypointToExit(__entryResult, __deadlineMs) {\n  if (await __nimbusAwaitEntryEvaluation(__entryResult)) return { passes: 0, pending: 0 };\n  return await __nimbusRunEventLoop(__nimbusLiveHandles, __nimbusProcessExitPromise, __deadlineMs, 4);\n}\n\n// A resident facet keeps running after the call that boots it returns, so it\n// settles startup and nothing more. The handles it holds open deliberately \u2014\n// its listening port \u2014 are the point of it, not a reason to make the shell's\n// prompt wait.\nasync function __nimbusSettleEntrypointStartup(__entryResult, __deadlineMs) {\n  if (await __nimbusAwaitEntryEvaluation(__entryResult)) return { passes: 0, pending: 0 };\n  return await __nimbusRunEventLoop(\n    __nimbusPendingStartupWork, __nimbusProcessExitPromise, __deadlineMs, 4,\n  );\n}\n";
+export declare const ENTRYPOINT_EVENT_LOOP = "\nfunction __nimbusHandleCount(__name) {\n  const __value = globalThis[__name];\n  return typeof __value === \"number\" ? __value : 0;\n}\n\n// Work an entrypoint's STARTUP has to settle before it can be called booted.\nfunction __nimbusPendingStartupWork() {\n  return __nimbusHandleCount(\"__nimbusPendingTimers\") + __nimbusHandleCount(\"__nimbusPendingOps\");\n}\n\n// The above, plus the handles a program holds open on purpose. A bound port\n// keeps a Node process alive, and it keeps a one-shot facet alive too.\nfunction __nimbusLiveHandles() {\n  const __servers = globalThis.__portRegistry;\n  const __bound = __servers && typeof __servers.size === \"number\" ? __servers.size : 0;\n  return __nimbusPendingStartupWork() + __bound;\n}\n\nasync function __nimbusRunEventLoop(__countHandles, __exitPromise, __deadlineMs, __minPasses) {\n  let __exited = false;\n  if (__exitPromise && typeof __exitPromise.then === \"function\") {\n    __exitPromise.then(() => { __exited = true; }, () => { __exited = true; });\n  }\n  const __rawSetTimeout = (typeof globalThis.__nimbusRawSetTimeout === \"function\")\n    ? globalThis.__nimbusRawSetTimeout\n    : globalThis.setTimeout;\n  const __rawClearTimeout = (typeof globalThis.__nimbusRawClearTimeout === \"function\")\n    ? globalThis.__nimbusRawClearTimeout\n    : globalThis.clearTimeout;\n  let __expired = false;\n  let __pass = 0;\n  // A user-invoked program runs until it exits or is killed \u2014 there is no\n  // wall-clock deadline, so no expiry timer is armed at all. (Callers that\n  // still pass a finite deadline get the timer for compatibility.)\n  const __deadline = Number.isFinite(__deadlineMs)\n    ? __rawSetTimeout(() => { __expired = true; }, __deadlineMs)\n    : null;\n  while (!__exited && !__expired && (__pass < __minPasses || __countHandles() > 0)) {\n    // The warm-up passes give a settling microtask chain its turns and cost\n    // ~5\u00B5s each; past them the loop is waiting on wall-clock work, where\n    // spinning at 0ms would burn the isolate's CPU indefinitely.\n    await new Promise((resolve) => __rawSetTimeout(resolve, __pass < __minPasses ? 0 : 1));\n    __pass++;\n  }\n  if (__deadline !== null) { try { __rawClearTimeout(__deadline); } catch {} }\n  // `pending` is what the caller reports when it gives up: a one-shot program\n  // still holding a handle did NOT finish, and exiting 0 would claim it did.\n  return { passes: __pass, pending: __exited ? 0 : __countHandles() };\n}\n\n// An ESM entry's own evaluation promise (top-level await) is the one promise\n// that IS a handle \u2014 the module has not finished loading until it settles.\n// Answers true when process.exit won the race instead.\nasync function __nimbusAwaitEntryEvaluation(__entryResult) {\n  if (!__entryResult || typeof __entryResult.then !== \"function\") return false;\n  const __exit = {};\n  const __raced = await Promise.race([\n    __entryResult.then(() => null),\n    __nimbusProcessExitPromise.then(() => __exit, () => __exit),\n  ]);\n  return __raced === __exit;\n}\n\n// A one-shot facet's lifetime IS the loop: it runs the program until Node\n// would exit, or until the lifetime budget runs out.\nasync function __nimbusRunEntrypointToExit(__entryResult, __deadlineMs) {\n  if (await __nimbusAwaitEntryEvaluation(__entryResult)) return { passes: 0, pending: 0 };\n  return await __nimbusRunEventLoop(__nimbusLiveHandles, __nimbusProcessExitPromise, __deadlineMs, 4);\n}\n\n// A resident facet keeps running after the call that boots it returns, so it\n// settles startup and nothing more. The handles it holds open deliberately \u2014\n// its listening port \u2014 are the point of it, not a reason to make the shell's\n// prompt wait.\nasync function __nimbusSettleEntrypointStartup(__entryResult, __deadlineMs) {\n  if (await __nimbusAwaitEntryEvaluation(__entryResult)) return { passes: 0, pending: 0 };\n  return await __nimbusRunEventLoop(\n    __nimbusPendingStartupWork, __nimbusProcessExitPromise, __deadlineMs, 4,\n  );\n}\n";
 /**
  * A generated facet's module map: its main module plus whatever side modules
  * the VFS bundle had to be partitioned across.
@@ -155,14 +125,32 @@ interface GeneratedNodeFacetCode {
 /**
  * Generate one-shot runtime code with a plain fetch handler.
  */
-export declare function generateEntrypointCode(userCode: string, vfsState: FacetVfsState, usesSqlite: boolean, shims: string): Promise<GeneratedNodeFacetCode>;
+export declare function generateEntrypointCode(userCode: string, vfsState: FacetVfsState, usesSqlite: boolean, shims: string, wasmImports?: readonly FacetWasmImport[]): Promise<GeneratedNodeFacetCode>;
+/** One wasm image the generated main module imports from the module map. */
+export interface FacetWasmImport {
+    /** The module-map name the boot spec carries the image under. */
+    moduleName: string;
+    /** The absolute VFS path the program reads the same bytes from. */
+    vfsPath: string;
+    /**
+     * A content key for the same bytes, for an image the program never reads
+     * from the filesystem — one inlined in a package's own source as base64.
+     * The seam recognises the bytes instead of the path.
+     */
+    digest?: string;
+}
+/** The module-map name a precompiled wasm image travels under. */
+export declare function facetWasmModuleName(index: number): string;
 /**
- * Generate a long-running Node entrypoint.
- *
- * Same core shim/VFS machinery as foreground node execution, but the
- * compiled user entry is booted once and the exported entrypoint keeps
- * serving HTTP requests from the shimmed http.Server registry.
+ * The wasm imports one launch stages: the images its options name, then
+ * every image the closure walk recorded (FacetVfsState.wasmImages) that the
+ * options did not already name by path. One member per path; the closure's
+ * record supplies the digest an option without one lacks.
  */
+export declare function facetWasmImports(named: readonly {
+    vfsPath: string;
+    digest: string | undefined;
+}[], closure: readonly WasmImageRecord[]): FacetWasmImport[];
 export declare function generateLongRunningNodeCode(userCode: string, vfsState: FacetVfsState, opts: {
     argv?: string[];
     env?: Record<string, string>;
@@ -172,6 +160,8 @@ export declare function generateLongRunningNodeCode(userCode: string, vfsState:
     stdin?: string;
     attachedTty?: boolean;
     cred: ProcessEntry['cred'];
+    /** Wasm images the generated main module imports and parks in the seam. */
+    wasmImports?: readonly FacetWasmImport[];
 }, usesSqlite: boolean, shims: string, pacer?: TurnBudget): Promise<GeneratedNodeFacetCode>;
 /**
  * Result of preparing facet VFS state.
@@ -237,6 +227,11 @@ interface FacetVfsState {
     serializedMetadata?: string;
     /** Move the bundle out of the main module when combined state exceeds its ceiling. */
     bundleSideModulesRequired?: boolean;
+    /**
+     * The wasm images the closure holds, by path and content digest — see
+     * `collectClosureWasmImages`. A launch stages each as a wasm map entry.
+     */
+    wasmImages?: readonly WasmImageRecord[];
     /**
      * Memoized `bundleUsesNodeSqlite(entryCode, bundle)`. Answered while the raw
      * cells are still in hand so `releaseSerializedSources` can drop them — it is
@@ -262,38 +257,37 @@ interface FacetVfsState {
  * `bundleSource`, `serializedManifest` and `serializedMetadata` are total
  * encodings of `bundle`, `manifest` and `metadata` — no caller can distinguish
  * a state carrying both from one carrying only the serialized halves, because
- * `generateEntrypointCode` reads the serialized halves and nothing else does.
+ * both facet generators read the serialized halves and nothing else does.
  * Holding both doubles the cost of a cached entry for its whole lifetime, and
  * that lifetime spans execs.
  *
- * Only for states on the one-shot cached path, and applied there whether or
- * not the entry turns out small enough to retain: the invocation being served
- * reads the serialized forms too. `spawnNode` and `_stageOpencodeFacet` build
- * their own uncached states and genuinely re-read the raw cells
- * (`_serializeBundleForFacet`, `assertStagedBundleFitsRpcPayload`); neither
- * goes through here.
+ * Applied by `_buildProcessBundle` to every state it builds, whether or not
+ * the entry turns out small enough to retain: the launch being served reads
+ * the serialized forms too. `_stageOpencodeFacet` builds its own uncached
+ * state and genuinely re-reads the raw cells
+ * (`assertStagedBundleFitsRpcPayload`); it does not go through here.
  */
 export declare function releaseSerializedSources(vfsState: FacetVfsState): void;
 /**
- * Drop everything a resident launch has finished reading, in place.
- *
- * The one-shot path releases its map at LOADER.load; this is the same policy
- * for the path `spawnNode` takes, which is the path every attached-TTY npm bin
- * takes — how a real agentic CLI starts. The generated source is a total
- * encoding of the cells, the manifest and the metadata, and the only thing the
- * rest of a launch reads off the state is `cursor`. Everything else is a second
- * copy of the largest thing this DO builds — 22.9 MB for pi — held for exactly
- * as long as the facet takes to boot on it.
+ * Drop the serialized forms once a module map has been generated from them.
  *
- * Holding it reset the session isolate with exceededMemory, and an isolate
- * reset tears the terminal WebSocket down with no exit frame: the dead screen
- * reading "[process terminal closed]".
+ * The generated source is a total encoding of all three: every byte of the
+ * bundle expression, the manifest and the metadata is inside it. Holding them
+ * afterwards keeps a second copy of the largest thing this DO builds alive for
+ * as long as the facet runs — for pi, 22.7 MB across the ~20 s window in which
+ * the isolate was being reset. For the one-shot path that window is the run;
+ * for a resident launch — the path every attached-TTY npm bin takes, how a
+ * real agentic CLI starts — it is the boot, and holding the copy across it
+ * reset the session isolate with exceededMemory, which tears the terminal
+ * WebSocket down with no exit frame: the dead screen reading "[process
+ * terminal closed]".
  *
- * An emptied state can still generate a map — it would just generate one with
- * no program in it — so this marks the state instead of trusting callers to
- * stop.
+ * Only for a state the prefetch cache refused. A retained entry's serialized
+ * forms ARE the entry, and a later launch is served from them. An emptied
+ * state could still generate a map — one with no program in it — so this
+ * marks the state instead of trusting callers to stop.
  */
-export declare function releaseResidentLaunchSources(vfsState: FacetVfsState): void;
+export declare function releaseGeneratedSources(vfsState: FacetVfsState): void;
 interface FacetVfsBundleSource {
     expression: string;
     imports: string;
@@ -350,13 +344,35 @@ export declare function assertStagedBundleFitsRpcPayload(serialized: string, bun
  * computed-path requires). Bounded to package.json + 1 main-entry file
  * per package — sub-agent §Q3 quantified the worst-case cumulative
  * budget impact (~322 KiB for fastify, ~1.7 MiB for ts-jest).
+ *
+ * `requiredPaths` is the static require closure. A package the closure
+ * already reached — but reached only through a SUBPATH — has its main entry
+ * skipped; see `mainIsSpeculative`.
  */
 export declare function greedyAddMainEntries(vfs: CredentialedVfs, cwd: string, bundle: Record<string, string | Uint8Array>, budgetState: {
     totalBytes: number;
     fileCount: number;
-}): {
+}, requiredPaths?: ReadonlySet<string>): {
     added: number;
 };
+/**
+ * The packages a computed `require(name)` inside the program can plausibly
+ * name: the project root's own runtime `dependencies`, plus every package
+ * ONE `dependencies` hop from a package that already owns a file in the
+ * static closure. Never devDependencies, never a second hop.
+ *
+ * Unbounded, the greedy oversample read every installed package's main:
+ * for `node -e "import('got')"` in got's repo — a one-file static closure —
+ * that was 1,526 files / 10.9 MB from 706 packages, which every later pass
+ * re-scanned and esbuild-wasm transformed, and the exec path's 20 s bundle
+ * deadline fired on a program that reads none of it. A bound that followed
+ * dependency edges from the project's devDependencies reached all 772 of
+ * them (measured), because a library repo's dev toolchain reaches the whole
+ * tree. Computed requires almost always target a declared runtime
+ * dependency of the package doing the requiring, so the bound is one hop
+ * over `dependencies` only. Directories, sorted for a stable bundle.
+ */
+export declare function speculativePackageDirs(vfs: CredentialedVfs, cwdStripped: string, bundle: Record<string, string | Uint8Array>): string[];
 /**
  * X.5-Z3: scan every JS source already in `bundle` for static
  * `fs.readFileSync(path.resolve(__dirname, "<rel>"))` shapes and pull
@@ -488,7 +504,21 @@ export declare function addBinTargetSiblings(vfs: CredentialedVfs, scriptPath: s
     fileCount: number;
 }, bundleProfile: FacetBundleProfile): {
     added: number;
+    wasmPaths: string[];
 };
+/**
+ * The wasm images a program's closure holds, by path and content digest.
+ *
+ * Two sources, one record: a `.wasm` cell the walk already staged (digested
+ * from the cell, no second read), and a `.wasm` file the bin-package pass
+ * saw but did not stage because it is over the bundle's per-file cap —
+ * esbuild-wasm's 11.9 MiB image is the motivating one. A launch stages each
+ * as a module-map member the loader compiles, registered under both keys,
+ * so the program's own `new WebAssembly.Module(bytes)` is answered from the
+ * map whether it read the bytes by path or carried them inline. A file that
+ * cannot be read is left out; the seam's refusal names the module later.
+ */
+export declare function collectClosureWasmImages(vfs: Pick<CredentialedVfs, 'readFile'>, bundle: Record<string, string | Uint8Array | FacetVfsDenial>, unstagedPaths: readonly string[]): WasmImageRecord[];
 /**
  * Stage the paths an earlier run of the same entry read synchronously and did
  * not have.
@@ -576,7 +606,7 @@ export declare const BUNDLE_PRECOMPILE_LOOP: string;
  * behaviour for code paths that don't have esbuild handy).
  *
  */
-export declare function buildPrefetchBundle(vfs: CredentialedVfs, scriptPath: string | undefined, cwd: string, entryCode: string, esbuild?: EsbuildService, bundleProfile?: FacetBundleProfile, observedReads?: ReadonlySet<string>, pacer?: TurnBudget, isolatedTransform?: LargeEsmTransform): Promise<FacetVfsState>;
+export declare function buildPrefetchBundle(vfs: CredentialedVfs, scriptPath: string | undefined, cwd: string, entryCode: string, esbuild?: EsbuildService, bundleProfile?: FacetBundleProfile, observedReads?: ReadonlySet<string>, pacer?: TurnBudget, isolatedTransform?: LargeEsmTransform, maxBundleBytes?: number): Promise<FacetVfsState>;
 /**
  * Optional hooks wired in by NimbusSession. Kept as callbacks so
  * FacetManager stays unaware of the session / log-store types.
@@ -598,7 +628,7 @@ export interface FacetManagerHooks {
      * genuinely re-enters the object: a fresh turn is both a released thread and
      * a fresh CPU budget, and a launch needs each for a different reason.
      */
-    requestLaunchTurn?: () => void;
+    requestLaunchTurn?: (notBefore?: number) => void;
     /**
      * Put a line in front of the user, whether or not a terminal is attached.
      *
@@ -628,6 +658,12 @@ export interface FacetManagerHooks {
     resolveWorkerLaunchFallback?: (recipe: WorkerRecipe) => Promise<ResolvedWorkerLaunch | null>;
 }
 export interface LongRunningWorkerSpawnOptions {
+    /** Interpreter residents share Node's atomic derived-owner claim. */
+    resident?: {
+        runtime: 'ruby' | 'python';
+        argv: string[];
+    };
+    restart?: ResidentRestartPolicy;
     port?: number;
     /** Inline modules: source text, or small wasm carried by value. */
     modules?: Record<string, string | {
@@ -639,6 +675,20 @@ export interface LongRunningWorkerSpawnOptions {
      * 34.3 MiB, past what any single RPC value may carry.
      */
     vfsWasmModules?: Record<string, string>;
+    /**
+     * Module name → VFS path of a content-addressed module SOURCE, read as
+     * UTF-8 when the facet loads — the same by-path posture as
+     * `vfsWasmModules`, through the same kernel image reader, for module text
+     * an embedder keeps in its own content store rather than carrying by value.
+     * Each path must name its own digest (`…/<sha256>.js`, see fabric's
+     * `facetImagePath`); the loader verifies it on read.
+     */
+    vfsTextModules?: Record<string, string>;
+    /**
+     * The module the isolate boots from; `workerCode` is placed under this name
+     * in the module map. Default `'worker.js'`.
+     */
+    mainModule?: string;
     compatibilityFlags?: string[];
     compatibilityDate?: string;
     env?: ResidentCodeSpec['env'];
@@ -658,6 +708,29 @@ export interface LongRunningWorkerSpawnOptions {
         };
     };
 }
+/** The main module name a worker launch boots from unless told otherwise. */
+export declare const DEFAULT_WORKER_MAIN_MODULE = "worker.js";
+/**
+ * The narrow handle `spawnWorker` returns beside the pid: the process's own
+ * inbound surface, bound to the resident handle's route target, for an
+ * embedder that invokes the worker directly rather than through a registered
+ * port. It carries NO release — `kill(pid)` remains the one lifecycle owner,
+ * and this handle is dead once that pid is; nothing here can end, restart or
+ * detach the process.
+ */
+export interface WorkerFacet {
+    /** Inbound HTTP, on the facet's `handleHttpRequest`. */
+    fetch(request: Request): Promise<Response>;
+    /** Inbound WebSocket upgrade, on the facet's `handleWebSocketRequest`. */
+    connect(request: Request): Promise<Response>;
+}
+/** What `spawnWorker` answers with. */
+export interface SpawnedWorker {
+    pid: number;
+    /** The runner's startProcess payload. */
+    boot: unknown;
+    facet: WorkerFacet;
+}
 /** What `spawnNode` needs to build and boot one resident Node process. */
 export interface ResidentSpawnOptions {
     argv?: string[];
@@ -675,6 +748,19 @@ export interface ResidentSpawnOptions {
 /** The launch inputs a re-drive rebuilds a worker from: content digests and
  *  transport, never env or credentials — the embedder resolves those. */
 export interface WorkerRecipe {
+    /**
+     * Set only for an interpreter resident the SESSION launched itself — a
+     * `python`/`ruby` socket server whose image is the runtime the session
+     * installed. It is the runtime and argv of that interpreter, never a
+     * boolean, and it is what routes the recipe's re-drive to the session's own
+     * image-store fallback (`resolveWorkerLaunchFallback`) rather than the
+     * embedder's `resolveWorkerLaunch`: the session owns that image and its
+     * bookkeeping, and no embedder was asked about the launch. A worker recipe
+     * WITHOUT it — every embedder-driven `spawnWorker` — re-drives through the
+     * embedder's resolver, with the fallback consulted only when no embedder
+     * hook is composed.
+     */
+    resident?: LongRunningWorkerSpawnOptions['resident'];
     kind: 'worker';
     /** The durable application this process belongs to, keyed by the embedder. */
     owner: string;
@@ -687,17 +773,53 @@ export interface WorkerRecipe {
     cwd: string;
     compatibilityDate: string;
     compatibilityFlags: string[];
-    startArgs: unknown;
+    startArgs?: unknown;
+    /**
+     * The main module the launch booted from, when it was not the default —
+     * so a re-drive whose resolver answers modules alone still boots the same
+     * one. Rows written before the field existed booted `worker.js`.
+     */
+    mainModule?: string;
+}
+export type ResidentRestartPolicy = 'never' | 'on-failure';
+/** The env var a launch reads its restart policy from — set by startProcess({ restart }) and `nimbus start --restart`. */
+export declare const RESTART_POLICY_ENV = "NIMBUS_RESTART";
+/** One application as `apps.list` reports it — every stamped identity, live or not. */
+export interface ResidentAppSummary {
+    owner: string;
+    name: string | null;
+    port: number | null;
+    pid: number | null;
+    status: 'running' | 'starting' | 'stopped' | 'failed';
+    visibility: PortVisibility;
+    capability: string | null;
+    restart: ResidentRestartPolicy;
+    /** Set with status 'failed': what went wrong, in the user's terms. */
+    diagnostic: string | null;
+}
+/** What a pid's journal row says about who it is. */
+export interface ResidentIdentity {
+    owner: string | undefined;
+    ephemeral: boolean;
+    port: number | undefined;
 }
 /** What the embedder supplies for a re-driven worker launch. */
 export interface ResolvedWorkerLaunch {
+    startArgs?: unknown;
     /** Null is the absent answer — the same JSON the image blob carries. */
     env: ResidentCodeSpec['env'] | null;
     globalOutbound: ResidentCodeSpec['globalOutbound'];
-    /** Module name → source text, including the `worker.js` main module. */
+    /** Module name → source text, including the main module under its name. */
     modules: Record<string, string>;
     /** Module name → VFS path of a wasm image, restored with the launch. */
     vfsWasmModules?: Record<string, string>;
+    /** Module name → VFS path of a content-addressed module source, restored with the launch. */
+    vfsTextModules?: Record<string, string>;
+    /**
+     * The name in `modules` the launch boots from. Absent, the recipe's own
+     * `mainModule` decides, then `'worker.js'`.
+     */
+    mainModule?: string;
 }
 export declare class FacetManager {
     private ctx;
@@ -741,7 +863,6 @@ export declare class FacetManager {
      * journal recovery rides the first pump.
      */
     private readonly launchPump;
-    private timedOutProcessIds;
     private _pairedServeFacet;
     /**
      * W3.5 Fix B: lazily-created EsbuildService for the ESM→CJS pre-pass
@@ -783,6 +904,15 @@ export declare class FacetManager {
     private residencyProfiles;
     /** In-flight request-driven durable-app ensures, single-flight per port. */
     private ensureInflight;
+    /** Per-pid chain of journal-row amendments; see `_amendRow`. */
+    private rowAmendments;
+    /**
+     * pid → the derived owner it duplicates: the second live instance of an
+     * identity. Not journalled (nothing re-drives it), so this is the only
+     * record of why `expose(pid)` refuses it.
+     */
+    private ephemeralPids;
+    private residentClaims;
     private static readonly RESIDENCY_PROFILE_MAX_ENTRIES;
     /**
      * A program that reads a directory of data files misses once per file, so
@@ -792,6 +922,23 @@ export declare class FacetManager {
      */
     private static readonly RESIDENCY_PROFILE_MAX_PATHS;
     constructor(ctx: DurableObjectState, env: unknown, processes: SessionProcessSupervisor, portRegistry: PortRegistry, host: ProcessHostFactory, hooks?: FacetManagerHooks);
+    /**
+     * The process is over. Every end-of-life passes through here: a clean
+     * exit, a kill, a timeout, a crash. Only one of them owes anything more
+     * than the journal row's release — a crash under 'on-failure' is re-driven
+     * from the row, after a backoff, while the row is still in storage so a
+     * reset inside the backoff window recovers it like any other resident.
+     */
+    private _onResidentTerminal;
+    /** Claim identity AND write its recovery row in one serializable storage transaction. */
+    private _claimResident;
+    private _releaseResidentClaim;
+    /**
+     * Amend one journal row in place — port stamp, owner adoption, settle —
+     * serialized per pid so two amendments in flight on the same row cannot
+     * interleave their read and write and lose one another's fields.
+     */
+    private _amendRow;
     setVfs(vfs: SqliteVFS): void;
     /**
      * The env/ctx pair every loader-backed runtime builds its facet pools
@@ -823,39 +970,56 @@ export declare class FacetManager {
      */
     setEsbuildService(esbuild: EsbuildService): void;
     /**
-     * buildPrefetchBundle wrapped in a global-revision-keyed cache. On a hit
-     * (same key AND the VFS hasn't been mutated since) it returns the memoized
-     * bundle + pre-built facet source, skipping the full VFS walk + esbuild
-     * pass + source construction. See `prefetchBundleCache` for the
-     * correctness argument behind the conservative global-revision watermark.
-     *
-     * The bundle source and manifest are computed once on the miss path and
-     * stored so subsequent hits skip rebuilding them too.
+     * The pacer every launch is built under: the session's alarm-driven turn
+     * pump, the deployment's chunk bound, and the one check a suspended launch
+     * makes when it resumes — that the process it is building for still exists.
      */
+    private _launchPacer;
     /**
-     * Bound the prefetch build, so a cache miss cannot be a silent hang.
+     * Assemble the filesystem bundle a process boots on, across as many
+     * Durable Object turns as it takes.
+     *
+     * The one builder for every Node process this manager starts. A one-shot
+     * exec and a resident launch used to own two copies of this: exec's was
+     * memoized behind the prefetch cache and raced a wall-clock deadline in a
+     * single turn; the resident's was paged with a TurnBudget and never cached.
+     * Two paths, one job — and a tree large enough to page on one path hit the
+     * deadline on the other, failing every `node -e` in it with "assembling the
+     * filesystem bundle … exceeded". What the two callers genuinely differ in is
+     * the entry, the working directory and the process they build for; that is
+     * all they supply. Everything else — the revision-keyed cache and its stale
+     * eviction, the residency profile a previous miss learned, the reachable-set
+     * walk and its enrichment passes, the ESM→CJS transform, the manifest and
+     * metadata, the module-map serialization with its side-module split, the
+     * `node:sqlite` answer, and the release of the raw cells once they are
+     * serialized — happens here, once, and yields the turn whenever a chunk's
+     * worth of it has been done.
      *
-     * The build was awaited entirely OUTSIDE `_execWithTimeout`, which wraps
-     * only `_execViaLoader`. So every timeout in the system — the 30 s facet
-     * bound, the 60 s bin-dispatch bound — sat downstream of a step that could
-     * take arbitrarily long, and a heavy build wedged the Durable Object with
-     * nothing able to report it. Observed as a terminal that goes quiet and
-     * never returns, with no exit record for the process.
+     * There is no deadline. A launch that spans turns costs turns, not a held
+     * thread, so a large tree is not a defect to be reported at N seconds; the
+     * pacer's `stillWanted` check is what ends a build nothing will use — a
+     * process killed while its build was suspended throws from the next resume,
+     * and the caller reports that as it reports any other launch failure.
      *
-     * WHAT THIS CAN AND CANNOT CATCH, stated plainly because the difference
-     * decides whether a given hang is fixed by it. The build is asynchronous —
-     * it awaits the VFS walk and the esbuild ESM→CJS pass — so a stall at any
-     * of those points is caught and reported here. A stall inside ONE
-     * synchronous stretch is not: a JS stack that never yields cannot be raced
-     * by anything in the same isolate, so serializing a multi-megabyte bundle
-     * in a single pass still wedges, and the deadline fires only once the stack
-     * finally unwinds. That class needs the work bounded at its INPUT rather
-     * than timed at its edge, which is a separate change; this one converts
-     * every interruptible stall from a silent wedge into a loud failure, and
-     * makes the remaining class the only one left to explain.
-     */
-    private _withBundleBuildDeadline;
-    private _buildPrefetchBundleCached;
+     * The returned state carries its serialized forms (`bundleSource`,
+     * `serializedManifest`, `serializedMetadata`) and has already released the
+     * raw ones: `generateEntrypointCode` and `generateLongRunningNodeCode` read
+     * the serialized forms and nothing else. A state the cache retained belongs
+     * to the cache — a caller must not release its serialized forms either
+     * (`cacheRetained` says which); one the cache refused belongs to the caller
+     * alone, and `releaseGeneratedSources` drops it once a map is generated.
+     *
+     * A session without a filesystem gets an empty state: there is nothing to
+     * stage and nothing to yield for.
+     */
+    /**
+     * The closure's wasm images as module-map members for a one-shot facet,
+     * read by path under the process's own credential. An image that cannot
+     * be read is left out; the program's compile then meets the seam's own
+     * refusal, which names the module.
+     */
+    private _wasmModulesByValue;
+    private _buildProcessBundle;
     /**
      * Admit an entry and evict, oldest first, until the LRU is inside BOTH its
      * entry count and its byte bound.
@@ -932,6 +1096,8 @@ export declare class FacetManager {
         /** Return stdout/stderr in the result while keeping supervisor RPC
          *  available for VFS and child_process operations. */
         captureOutput?: boolean;
+        /** Shell abort (Ctrl+C): aborting this aborts the in-flight run. */
+        signal?: AbortSignal;
     }): Promise<FacetExecResult>;
     /**
      * W5 Lever 5: push a DiagFailure into the OOM ring for every facet
@@ -1074,10 +1240,16 @@ export declare class FacetManager {
     private _warmOpencodeServer;
     /** Recent stderr/stdout tail for a pid, for fail-loud diagnostics. */
     private _processLogTail;
+    /**
+     * A launch that fails before its process is running reports the same way
+     * regardless of which phase failed: the pid is exited, the terminal event
+     * recorded, and the session notified. Callers do their phase-specific
+     * cleanup (ports, tracked RPC resources) first and pass a reason that names
+     * the phase.
+     */
+    private _failLaunch;
     /** Flush files written by the script back to the supervisor's VFS. */
     private _flushVfsWrites;
-    /** Execution timeout. */
-    private _execWithTimeout;
     /**
      * Re-drive a journalled launch after an instance reset. What the journal
      * row carries is the recipe and nothing else: env and credentials are never
@@ -1118,10 +1290,21 @@ export declare class FacetManager {
     private _runResidentLaunch;
     private _residentLaunchBody;
     /**
-     * Spawn a long-running dynamic Worker, boot it, and return its boot payload.
+     * The exit code of a launched process that has already ended, or null
+     * while it runs. What a caller that started a resident reads to tell a
+     * server that is up from a program that finished during its boot.
+     */
+    processExitCode(pid: number): number | null;
+    /**
+     * Spawn a long-running dynamic Worker, boot it, and return its boot payload
+     * beside the pid and the process's own inbound facet.
      *
      * The shared primitive for any runtime that serves over
-     * handleHttpRequest(Request) — the python and ruby socket servers today.
+     * handleHttpRequest(Request) — the python and ruby socket servers today —
+     * and for an embedder's own Worker-class program: `workerCode` boots as
+     * `opts.mainModule` (default `worker.js`), `opts.modules` ride inline,
+     * `opts.vfsTextModules` and `opts.vfsWasmModules` are read by path when the
+     * facet loads.
      *
      * The interpreter image it carries is the memory that should not sit in the
      * session's own isolate — ruby's interpreter+stdlib alone is 34.3 MiB — and
@@ -1129,30 +1312,61 @@ export declare class FacetManager {
      * no readiness coupling back into the session: the runner answers
      * startProcess with its boot payload and the caller waits on that one
      * promise, so nothing polls the port to decide the process is up.
+     *
+     * The returned `facet` is bound to the resident handle's route target — the
+     * same target a registered port routes to — so a port-less process can be
+     * invoked directly. It has no release: `kill(pid)` is the one lifecycle
+     * owner, and the facet is dead once the pid is.
      */
-    spawnWorker(workerCode: string, command: string, cwd: string, opts?: LongRunningWorkerSpawnOptions): Promise<{
-        pid: number;
-        boot: unknown;
-    }>;
+    spawnWorker(workerCode: string, command: string, cwd: string, opts?: LongRunningWorkerSpawnOptions): Promise<SpawnedWorker>;
     /** `attempt` is the journal's re-drive budget, as `_spawnResident` carries it. */
     private _spawnWorker;
     /**
-     * A resident process announcing it bound `port`. When the port is reserved,
-     * the reservation's owner is stamped onto this pid's journal row — the
-     * reservation is what declares which application the port serves, and a
-     * resident that binds it inherits the whole durable contract: the row names
-     * the port `ensureDurableAppOnPort` looks up, the minted capability is
-     * re-adopted rather than retired, and `removeDurableApp` can find the launch
-     * by owner.
+     * A resident process announcing it bound `port`.
+     *
+     * The stamp is unconditional: the pid's journal row gets `{ port }`
+     * whether or not anything reserved it, which is what lets
+     * `ensureDurableAppOnPort` re-drive ANY resident a reset killed — the
+     * scoped URLs need no capability, so this alone makes every server's
+     * preview survive a reset on demand.
+     *
+     * The capability is bound to identity, not to the port. The stored
+     * capability is re-adopted only when the row's owner IS the reservation's
+     * owner; any other occupant — an unrelated server, a pid outside the
+     * resident lifecycle, the ephemeral second instance of an identity —
+     * retires it and mints fresh, so a shared link 404s rather than reaching
+     * a program it was never handed out for. An EXPLICIT reservation (an
+     * embedder's `ensureDurableApp`) is the one exception, and it is the
+     * landed contract: the embedder declared the port, so the row adopts the
+     * reservation's owner and the capability with it.
      *
-     * A pid with no journal row — a process outside the resident lifecycle —
-     * registering on a reserved port takes it as today: the stored capability
-     * is retired and a fresh one is minted, the reservation stays with the
-     * owner. An accidental port reuse inside one session therefore cannot
-     * inherit the public capability; same-session processes are one trust
-     * domain, so this is hygiene, not a security boundary.
+     * Under an injected `$PORT`, a resident that binds a different port is
+     * registered anyway — the server must not break — but the row records
+     * the mismatch, so `apps.list` reports it as failed and the user is told.
      */
     private _registerResidentPort;
+    /**
+     * Who a pid is. One resolver, in precedence order: the ephemeral-duplicate
+     * mark, the journal row (the owner a launch this manager made was stamped
+     * with — derived from the launch's own cwd+argv, or adopted from an
+     * explicit reservation), and finally the process table. The table knows
+     * cwd and argv for every pid, so a serving process nothing journalled — the
+     * in-process Vite dev server, real-vite, a staged artifact, any wrapper pid
+     * a builtin adopted — has the same derived identity shape as a resident
+     * and answers to the same app verbs. It just cannot be re-driven after a
+     * reset: only a journal row carries a recipe. Null only for a pid that is
+     * neither journalled nor running.
+     */
+    residentIdentity(pid: number): Promise<ResidentIdentity | null>;
+    /**
+     * Every stamped identity — the reservations, and the journal rows that
+     * carry an owner — folded one row per owner. A live pid in THIS instance
+     * makes it running (or starting, until its launch settles and its port
+     * is registered); a mismatch diagnostic makes it failed; everything else
+     * is stopped, which for a row a reset left behind means re-drivable on
+     * request.
+     */
+    listResidentApps(): Promise<ResidentAppSummary[]>;
     registerPort(pid: number, port: number): Promise<void>;
     waitForRouteablePorts(pid: number, timeoutMs?: number): Promise<number[]>;
     finishProcess(pid: number, exitCode: number, reason?: string): void;