@nimbus-sh/core 0.4.0 → 0.6.0

package/src/constants.ts

@@ -1,7 +1,32 @@
 /**
  * constants.ts — Single source of truth for all Nimbus configuration.
+ *
+ * Nimbus POLICY only. The measured platform limits these policies are
+ * derived from (tx bounds, the RPC envelope, supervisor budgets) live in
+ * `@nimbus-sh/platform/limits.js`.
  */
 
+import { MAX_RPC_SAFE_PAYLOAD_BYTES } from '@nimbus-sh/platform/limits.js';
+
+// Published-surface forwarding: @nimbus-sh/core@0.5.0 exports these from
+// this module and real consumers import them here (Proteus merge-back.ts
+// pulls CHUNK_SIZE and the MAX_TX_* set). The platform split moved the
+// definitions to @nimbus-sh/platform/limits.js, which stays the single
+// source of truth; core's own modules import platform directly.
+export {
+  CHUNK_SIZE,
+  MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES,
+  MAX_RPC_SAFE_PAYLOAD_BYTES,
+  MAX_TX_BLOB_BYTES,
+  MAX_TX_LOGICAL_ROWS,
+  MAX_TX_SQL_EXECS,
+  PRE_BUNDLE_CONCURRENCY,
+  PRE_BUNDLE_SLICE_CAP_BYTES,
+  SUPERVISOR_HEAP_CEILING_BYTES,
+  SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES,
+  SUPERVISOR_READ_RESERVE_BYTES,
+} from '@nimbus-sh/platform/limits.js';
+
 // ── Versions ────────────────────────────────────────────────────────────
 export const NIMBUS_VERSION = '2.0.0';
 //
@@ -55,19 +80,11 @@ export const SQLJS_VERSION = '1.14.1';
 export const OPENCODE_VERSION = '1.16.2';
 
 // ── VFS Constants ───────────────────────────────────────────────────────
-export const CHUNK_SIZE = 65_536;        // 64KB per content chunk
+// The chunk size itself (CHUNK_SIZE) and the transaction bounds are
+// platform limits — see @nimbus-sh/platform/limits.js.
 export const LRU_MAX_ENTRIES = 512;      // 512 × 64KB = 32MB hot cache
 export const BATCH_SIZE = 64;            // rows per batch INSERT
 export const VFS_CAPACITY = 10 * 1024 * 1024 * 1024; // 10 GB
-export const MAX_TX_BLOB_BYTES = 1 * 1024 * 1024;
-export const MAX_TX_LOGICAL_ROWS = 256;
-export const MAX_TX_SQL_EXECS = 64;
-export const MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES = 8 * 1024 * 1024;
-
-// Largest byte payload Nimbus sends through an ordinary Workers RPC value.
-// The platform limit is 32 MiB; 28 MiB leaves room for structured-clone
-// metadata and matches the proven on-demand facet transfer envelope.
-export const MAX_RPC_SAFE_PAYLOAD_BYTES = 28 * 1024 * 1024;
 
 // ── Batched filesystem reads ────────────────────────────────────────────
 // A round trip costs an order of magnitude more than the SQLite lookup
@@ -142,10 +159,13 @@ export const FACET_TIMEOUT_MS = 30_000;  // 30s execution timeout
 // JavaScript, so workerd's per-module text-size limit applies to the
 // JSON-escaped form (each `\n` / `\"` / `\u` adds bytes, plus the
 // per-key string-quote overhead).
-// raw → boots, 8 MiB raw → fails. Encoded as JSON that's roughly 18-25 MiB
-// of module text. We target 22 MiB encoded as the hard ceiling, leaving
-// ~2-3 MiB of headroom for the rest of the worker module (shims, runner
-// boot code) and any minor drift in the eviction loop's accounting.
+// Measured: 8 MiB raw failed to boot; the passing raw bound was measured
+// too, but the number was lost to comment truncation before it ever
+// reached git, so only the failing side is known. Encoded as JSON that's
+// roughly 18-25 MiB of module text. We target 22 MiB encoded as the hard
+// ceiling, leaving ~2-3 MiB of headroom for the rest of the worker module
+// (shims, runner boot code) and any minor drift in the eviction loop's
+// accounting.
 //
 // facet-manager.ts:buildPrefetchBundle uses TextEncoder().encode().length
 // to measure exact UTF-8 bytes (not JS string .length, which counts UTF-16
@@ -198,11 +218,12 @@ export const PREFETCH_CACHE_MAX_BYTES = 16 * 1024 * 1024;
 export const CWD_SNAPSHOT_MAX_FILE_BYTES = 2 * 1024 * 1024;
 
 // ── npm Constants ───────────────────────────────────────────────────────
+// The pre-bundle admission envelope (PRE_BUNDLE_SLICE_CAP_BYTES,
+// PRE_BUNDLE_CONCURRENCY) is a measured platform envelope — see
+// @nimbus-sh/platform/limits.js.
 export const NPM_REGISTRY = 'https://registry.npmjs.org';
 export const NPM_CONCURRENCY = 12;
 export const NPM_DECOMPRESS_TIMEOUT = 15_000;
-export const PRE_BUNDLE_SLICE_CAP_BYTES = MAX_RPC_SAFE_PAYLOAD_BYTES;
-export const PRE_BUNDLE_CONCURRENCY = 1;
 
 // ── Dev Server Constants ────────────────────────────────────────────────
 export const DEFAULT_VITE_PORT = 5173;
@@ -222,43 +243,6 @@ export const NIMBUS_AI_GATEWAY_PORT = 8790;
 // ── Compatibility ───────────────────────────────────────────────────────
 export const CF_COMPAT_DATE = '2026-04-01';
 
-// ── Supervisor heap budget [C'.1] ───────────────────────────────────────
-//
-// The supervisor isolate's 128 MiB workerd cap is a HARD platform ceiling
-// (per docs/research/cf-primitives-dossier.md §6 invariant I1 — 128 MiB
-// per V8 isolate, may be shared across same-class peer DOs co-tenanting in
-// one process). Nimbus targets HALF of that as a self-imposed soft ceiling
-// so the supervisor always has runway when workerd LRU-evicts neighbours
-// or AIR (Asynchronous Isolate Recreation) folds growing isolates.
-//
-// 64 MiB is a budget, not a measurement, and nothing enforces it.
-// src/observability/heap-estimate.ts sums the INSTRUMENTED contributors —
-// the supervisor baseline, VFS LRU and in-flight writes, pre-bundle slices,
-// and streaming RPC buffers — which is a lower bound, not full coverage.
-// The prefetch-bundle path in facets/manager.ts allocates against this
-// budget without accounting for it; see HEAP_BLIND_SPOTS for the current
-// gap. Read a low percentOfCeiling accordingly.
-export const SUPERVISOR_HEAP_CEILING_BYTES = 64 * 1024 * 1024;
-
-// Shared allowance for transient allocations in the supervisor DO. With the
-// VFS LRU shrunk to 8 MiB during an active reservation, 40 MiB of admitted
-// payload plus the 9 MiB bundle baseline stays below the 64 MiB soft ceiling
-// with 7 MiB left for metadata, structured-clone overhead, and runtime state.
-// This is 31.25% of the platform's 128 MiB hard isolate ceiling.
-export const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES = 40 * 1024 * 1024;
-
-// Reserved slice of that allowance for chunk-sized filesystem reads, so a
-// read is never queued behind a multi-megabyte owner for a wait that has
-// nothing to do with its own cost. A read only draws on this when the shared
-// budget is already contended — which is exactly when the VFS LRU is shrunk
-// to 8 MiB — so peak accounting is 40 + 1 admitted, 8 LRU, 9 bundle baseline:
-// 58 MiB, still under the 64 MiB soft ceiling.
-//
-// 1 MiB is 16 concurrent READ_STREAM_CHUNK_BYTES reads. The point is not
-// depth, it is that a read loop keeps moving while a heavy owner works
-// instead of stopping dead for the duration.
-export const SUPERVISOR_READ_RESERVE_BYTES = 1024 * 1024;
-
 // ── OS Defaults ─────────────────────────────────────────────────────────
 export const DEFAULT_HOSTNAME = 'nimbus';
 export const DEFAULT_HOME = '/home/user';

package/src/runtime/assets-loader.ts

@@ -35,7 +35,7 @@
  * same content.
  */
 
-import { disposeRpcResource } from '../_shared/rpc-dispose.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 
 /**
  * Per-isolate cache. Keys are asset paths (e.g. `/_assets/foo.js`).

package/src/runtime/esbuild-service.ts

@@ -19,8 +19,9 @@
 
 import type { CredentialedVfs, SqliteVFS } from '../vfs/sqlite-vfs.js';
 import { CRED_KERNEL } from './os-contracts.js';
-import { resolvePackageEntry, resolveExports } from '../_shared/exports-resolver.js';
+import { resolvePackageEntry, resolveExports, type ResolvablePackageJson } from '../_shared/exports-resolver.js';
 import { normalizeVfsPath, stripLeadingSlashes } from '../vfs/path.js';
+import { errorText } from '../_shared/error-text.js';
 
 /**
  * Bundler version tag. BUMP THIS whenever bundling semantics change —
@@ -175,7 +176,6 @@ export function hasTopLevelAwait(src: string): boolean {
   // inside `(...)`; a `{` only opens a function body when a `function`/
   // `=>` is pending AND we're at parenDepth 0 (past the param list).
   const re = /\b(await|function|class)\b|=>|\{|\}|\(|\)/g;
-  let m: RegExpExecArray | null;
   const fnEntryDepths: number[] = [];
   let depth = 0;
   let parenDepth = 0;
@@ -189,7 +189,7 @@ export function hasTopLevelAwait(src: string): boolean {
   // `x => ({ ... })` (object-returning expression body, `{` at parenDepth
   // 1) does not leak a body slot onto a later top-level block.
   let arrowPending = false;
-  while ((m = re.exec(stripped)) !== null) {
+  for (let m = re.exec(stripped); m !== null; m = re.exec(stripped)) {
     const tok = m[0];
     if (arrowPending && tok !== '{') arrowPending = false;
     if (tok === '(') { parenDepth++; }
@@ -803,7 +803,7 @@ async function loadEsbuild(): Promise<typeof esbuild> {
 export interface TransformResult {
   code: string;
   map: string;
-  warnings: { text: string; location?: any }[];
+  warnings: { text: string; location?: esbuild.Location | null }[];
 }
 
 export interface BuildOutputFile {
@@ -813,8 +813,8 @@ export interface BuildOutputFile {
 
 export interface BuildResult {
   outputFiles: BuildOutputFile[];
-  errors: { text: string; location?: any }[];
-  warnings: { text: string; location?: any }[];
+  errors: { text: string; location?: esbuild.Location | null }[];
+  warnings: { text: string; location?: esbuild.Location | null }[];
 }
 
 // ── EsbuildService ──────────────────────────────────────────────────────
@@ -876,7 +876,11 @@ export class EsbuildService {
         let initTimeout: ReturnType<typeof setTimeout> | null = null;
         await Promise.race([
           esb.initialize({
-            wasmModule: esbuildWasmUrl as any,
+            // wrangler resolves this static `.wasm` import to a compiled
+            // module at bundle time; the asset stub for a `.wasm` module can
+            // only declare its default export as a string, and the guard
+            // above is what checks the resolution actually happened.
+            wasmModule: esbuildWasmUrl as unknown as WebAssembly.Module,
             worker: false,
           }),
           new Promise<never>((_, reject) => {
@@ -890,14 +894,15 @@ export class EsbuildService {
           }),
         ]).finally(() => { if (initTimeout) clearTimeout(initTimeout); });
         this.initialized = true;
-      } catch (e: any) {
+      } catch (e) {
+        const message = errorText(e);
         // "Cannot call initialize more than once" means it's already ready
-        if (e?.message?.includes('more than once')) {
+        if (message.includes('more than once')) {
           this.initialized = true;
           return;
         }
         this.initPromise = null;
-        throw new Error('esbuild init failed: ' + (e?.message || e));
+        throw new Error('esbuild init failed: ' + message);
       }
     })();
 
@@ -1315,7 +1320,7 @@ export class EsbuildService {
         if (vfs.exists(strip(nmDir)) && vfs.isDirectory(strip(nmDir))) {
           // Read package.json so we can consult the exports field.
           const pkgJsonPath = nmDir + '/package.json';
-          let pkgJson: any = null;
+          let pkgJson: ResolvablePackageJson | null = null;
           if (vfs.exists(strip(pkgJsonPath))) {
             try { pkgJson = JSON.parse(vfs.readFileString(strip(pkgJsonPath))); } catch {}
           }

package/src/runtime/installed-runtimes.ts

@@ -17,6 +17,7 @@
  */
 
 import type { CredentialedVfs, SqliteVFS } from '../vfs/sqlite-vfs.js';
+import type { Command } from '../substrate/lifo/commands/types.js';
 import {
   CRED_KERNEL,
   NIMBUS_ABI_TARGET,
@@ -32,9 +33,9 @@ import {
 
 /** Minimal shell-registry shape we depend on. */
 export interface MinShellRegistry {
-  register(name: string, handler: (ctx: any) => Promise<number>): void;
+  register(name: string, handler: Command): void;
   unregister?(name: string): void;
-  resolve?(name: string): any;
+  resolve?(name: string): Promise<Command | null | undefined> | Command | null | undefined;
 }
 
 /** Runner-factory contract. Each registered runner produces a shell-
@@ -46,7 +47,7 @@ export type RunnerFactory = (
   installRoot: string,
   binName: string,
   binKind: string | undefined,
-) => (ctx: any) => Promise<number>;
+) => Command;
 
 /**
  * How a manifest entrypoint's `runner` key is resolved to code.

package/src/runtime/long-running-handle.ts

@@ -107,7 +107,7 @@ export function parsePortFromArgv(argv: string[]): number | null {
  */
 export function resolveLongRunningPort(opts: {
   argv?: string[];
-  env?: Record<string, any> | undefined;
+  env?: Record<string, string> | undefined;
   configPort?: number | undefined;
   fallback: number;
 }): number {
@@ -152,7 +152,7 @@ export function resolveLongRunningPort(opts: {
  */
 export function expandShellDefaults(
   token: string,
-  env: Record<string, any> | undefined,
+  env: Record<string, string> | undefined,
 ): string {
   if (!token || token.indexOf('${') < 0) return token;
   const lookup = (name: string): string | undefined => {
@@ -179,7 +179,7 @@ export function expandShellDefaults(
  */
 export function expandArgvShellDefaults(
   argv: ReadonlyArray<string>,
-  env: Record<string, any> | undefined,
+  env: Record<string, string> | undefined,
 ): string[] {
   return argv.map((t) => expandShellDefaults(t, env));
 }

package/src/runtime/os-contracts.ts

@@ -312,11 +312,12 @@ export interface RuntimeTtyOptions {
 /**
  * Where a registered port's traffic goes: one process, reached by HTTP.
  *
- * The whole of what a listening process exposes, deliberately. A resident
- * process never receives a WebSocket — every inbound socket Nimbus serves
- * terminates on the session and reaches the process, if at all, as events on a
- * poll — so a target that could return a 101 would describe a case no runner
- * produces.
+ * Ordinary HTTP may cross Workers RPC as Request/Response values. A WebSocket
+ * upgrade may not: its 101 Response owns a live socket, and RPC's
+ * Request/Response transport reconstructs the value rather than handing over
+ * the socket. So a target that can serve an upgrade exposes a separate
+ * fetch-semantic entrypoint, and every hop of an upgrade stays on the HTTP
+ * service-binding path. A target that omits it serves HTTP only.
  *
  * Lives here rather than beside the registry because both ends need it and
  * neither owns it: the port registry stores these, and the process fabric
@@ -325,6 +326,7 @@ export interface RuntimeTtyOptions {
  */
 export interface RouteableFacetTarget {
   handleHttpRequest(request: Request): Promise<Response>;
+  handleWebSocketRequest?(request: Request): Promise<Response>;
 }
 
 export interface RuntimePortBridge {

package/src/runtime/port-registry.ts

@@ -40,6 +40,17 @@ export interface PortEntry {
    */
   facetStub: RouteableFacetTarget | null;
   registeredAt: number;
+  /**
+   * Unguessable token for the lifetime of THIS registration, so an embedder
+   * can hand out one port's traffic without handing out the session. A fresh
+   * one per `register`, which is what makes an unexposed port stay unexposed.
+   */
+  capability: string;
+}
+
+function createPortCapability(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
 }
 
 export class PortRegistry {
@@ -64,7 +75,13 @@ export class PortRegistry {
    */
   register(port: number, pid: number): void {
     const target = this.facetStubsByPid.get(pid) ?? null;
-    this.ports.set(port, { port, pid, facetStub: target, registeredAt: Date.now() });
+    this.ports.set(port, {
+      port,
+      pid,
+      facetStub: target,
+      registeredAt: Date.now(),
+      capability: createPortCapability(),
+    });
     this.notifyPortWaiters(pid);
   }
 
@@ -126,6 +143,24 @@ export class PortRegistry {
     return [...this.ports.values()];
   }
 
+  /** Answer only whether this capability matches, never what is registered. */
+  hasCapability(port: number, capability: string): boolean {
+    return this.ports.get(port)?.capability === capability;
+  }
+
+  /**
+   * Re-adopt a capability the embedder was already handed, after the supervisor
+   * was rebuilt. A restored dev server is a NEW registration with a new token,
+   * which would silently invalidate every preview URL already in circulation
+   * across an eviction — so the durable value wins over the fresh one.
+   */
+  restoreCapability(port: number, capability: string): boolean {
+    const entry = this.ports.get(port);
+    if (!entry || !/^[a-f0-9]{24}$/.test(capability)) return false;
+    entry.capability = capability;
+    return true;
+  }
+
   /**
    * Forward an HTTP request to the facet owning a port.
    *
@@ -148,6 +183,36 @@ export class PortRegistry {
    * client receives.
    */
   async routeRequest(port: number, request: Request, pathname: string): Promise<Response | null> {
+    return this.routeRequestInternal(port, request, pathname, false);
+  }
+
+  /**
+   * Route a request a trusted embedder has already authenticated against the
+   * port's capability and stripped its own credentials from.
+   *
+   * Unlike the generic route, this one PRESERVES `Authorization`. The generic
+   * route strips it because the header it sees is Nimbus's own, and handing a
+   * session credential to untrusted code is the thing that must never happen.
+   * Here the embedder has removed that credential already and what remains
+   * belongs to the guest application, which needs it to authenticate its own
+   * users.
+   */
+  async routeCapabilityRequest(
+    port: number,
+    capability: string,
+    request: Request,
+    pathname: string,
+  ): Promise<Response | null> {
+    if (!this.hasCapability(port, capability)) return null;
+    return this.routeRequestInternal(port, request, pathname, true);
+  }
+
+  private async routeRequestInternal(
+    port: number,
+    request: Request,
+    pathname: string,
+    preserveAuthorization: boolean,
+  ): Promise<Response | null> {
     const entry = this.ports.get(port);
     // Honour the documented contract: no entry at all → null, so callers
     // report "no process listening". (Pre-fix this fell into the 501 below,
@@ -189,7 +254,12 @@ export class PortRegistry {
       // if a body is supplied on those methods.
       const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
       const headers = new Headers(request.headers);
+      // The strip below removes Nimbus's own credentials. On a capability
+      // route the embedder has already removed those, so what is left belongs
+      // to the guest application and has to survive the hop.
+      const authorization = preserveAuthorization ? headers.get('authorization') : null;
       sanitizeUntrustedHeaders(headers);
+      if (authorization) headers.set('authorization', authorization);
 
       headers.set('X-Nimbus-Port', String(port));
       // `duplex: 'half'` is required by workerd when body is a
@@ -205,11 +275,19 @@ export class PortRegistry {
       if (hasBody) init.duplex = 'half';
       const forwarded = new Request(innerUrl.toString(), init);
 
-      // RPC: the facet receives the Request and returns a Response.
-      // Both cross the isolate boundary via Workers RPC's native
-      // Request/Response transport — bytes are streamed with
-      // flow-control, never materialised.
-      const response: Response = await entry.facetStub.handleHttpRequest(forwarded);
+      // HTTP crosses Workers RPC as Request/Response values, streamed with
+      // flow control and never materialised. A WebSocket upgrade cannot: its
+      // 101 owns a live socket, so it takes the fetch-semantic entrypoint,
+      // which every hop preserves. A target with no such entrypoint serves
+      // HTTP only, and says so rather than dropping the socket.
+      const isWebSocket = request.headers.get('upgrade')?.toLowerCase() === 'websocket';
+      const handler = isWebSocket
+        ? entry.facetStub.handleWebSocketRequest
+        : entry.facetStub.handleHttpRequest;
+      if (!handler) {
+        return new Response('Port target does not expose a WebSocket fetch route', { status: 501 });
+      }
+      const response: Response = await handler(forwarded);
 
       if (!(response instanceof Response)) {
         // Defensive: if a facet ever returns something else (JSON
@@ -286,10 +364,20 @@ export class PortRegistry {
 
 function routeableFacetTarget(value: unknown): RouteableFacetTarget | null {
   if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return null;
-  const method = Reflect.get(value, 'fetch') || Reflect.get(value, 'handleHttpRequest');
-  if (typeof method !== 'function') return null;
+  // A `fetch` target already has fetch semantics, so it serves both.
+  const fetchMethod = Reflect.get(value, 'fetch');
+  if (typeof fetchMethod === 'function') {
+    const fetch = fetchMethod.bind(value) as (request: Request) => Promise<Response>;
+    return { handleHttpRequest: fetch, handleWebSocketRequest: fetch };
+  }
+  const httpMethod = Reflect.get(value, 'handleHttpRequest');
+  if (typeof httpMethod !== 'function') return null;
+  const webSocketMethod = Reflect.get(value, 'handleWebSocketRequest');
   return {
-    handleHttpRequest: method.bind(value),
+    handleHttpRequest: httpMethod.bind(value),
+    ...(typeof webSocketMethod === 'function'
+      ? { handleWebSocketRequest: webSocketMethod.bind(value) }
+      : {}),
   };
 }
 

package/src/runtime/process-logs.ts

@@ -61,6 +61,15 @@ export interface SequencedLogChunk extends LogChunk {
   seq: number;
 }
 
+/**
+ * A chunk as a persist adapter hands it back on load. `seq` is the sequence
+ * number the adapter stored alongside it; hydration falls back to array
+ * position for a row that carries none.
+ */
+export interface PersistedLogChunk extends LogChunk {
+  seq?: number;
+}
+
 export interface ProcessLogReadOptions {
   cursor?: number;
   lines?: number;
@@ -130,7 +139,7 @@ interface PidState {
  *     against the SQLite engine); KV is not used by W9.
  */
 export interface PersistAdapter {
-  load(pid: number): { chunks: LogChunk[]; exit: ProcessExitInfo | null } | null;
+  load(pid: number): { chunks: PersistedLogChunk[]; exit: ProcessExitInfo | null } | null;
   persistChunks(pid: number, rows: { seq: number; chunk: LogChunk }[]): void;
   persistExit(pid: number, info: ProcessExitInfo): void;
   dropPid(pid: number): void;
@@ -710,7 +719,7 @@ export class ProcessLogStore {
     if (state.hydrated) return;
     state.hydrated = true;
     if (!this._persist) return;
-    let loaded: { chunks: LogChunk[]; exit: ProcessExitInfo | null } | null;
+    let loaded: { chunks: PersistedLogChunk[]; exit: ProcessExitInfo | null } | null;
     try {
       loaded = this._persist.load(pid);
     } catch {
@@ -736,7 +745,7 @@ export class ProcessLogStore {
     let highestSeq = -1;
     for (let i = loaded.chunks.length - 1; i >= 0; i--) {
       const c = loaded.chunks[i];
-      const seq = (c as any).seq ?? i;
+      const seq = c.seq ?? i;
       if (seq > highestSeq) highestSeq = seq;
       const size = c.data.length;
       if (bytes + size > this.perPidBytes && newest.length > 0) {

package/src/runtime/project-detect.ts

@@ -10,6 +10,12 @@
  * can add detectVite, detectNext, etc. here.
  */
 
+/** The filesystem reads a project probe needs. */
+export interface ProjectProbeFs {
+  exists(path: string): boolean;
+  readFileString(path: string): string;
+}
+
 /**
  * W10: detect whether the project at `<root>` is a Cloudflare Workers
  * project. Returns true if any of the standard markers are present:
@@ -18,7 +24,7 @@
  *   - <root>/wrangler.toml
  *   - <root>/package.json with `wrangler` in deps or devDeps
  */
-export function detectCloudflareWorkersProject(vfs: any, root: string): boolean {
+export function detectCloudflareWorkersProject(vfs: ProjectProbeFs, root: string): boolean {
   const r = String(root).replace(/^\/+/, '').replace(/\/+$/, '');
   for (const f of ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml']) {
     try {

package/src/runtime/require-resolver.ts

@@ -33,6 +33,7 @@ import {
   resolveExports as sharedResolveExports,
   DEFAULT_CJS_CONDITIONS,
   DEFAULT_ESM_CONDITIONS,
+  type ResolvablePackageJson,
 } from '../_shared/exports-resolver.js';
 import {
   TYPESCRIPT_INDEX_CANDIDATES,
@@ -146,7 +147,7 @@ function resolveFile(vfs: CredentialedVfs, base: string, sink?: PkgJsonSink): st
   const baseTrim = base.replace(/\/+$/, '');
   const pkgJsonPath = normalizePath(baseTrim + '/package.json');
   if (vfs.exists(pkgJsonPath) && !vfs.isDirectory(pkgJsonPath)) {
-    let pkg: any = null;
+    let pkg: ResolvablePackageJson | null = null;
     try { pkg = JSON.parse(vfs.readFileString(pkgJsonPath)); } catch { /* fall through */ }
     if (pkg && typeof pkg.main === 'string' && pkg.main.length > 0) {
       // Record this package.json so the bundle carries the content the
@@ -257,7 +258,7 @@ function resolvePkgSubpathEx(vfs: CredentialedVfs, pkgDir: string, subpath: stri
     // fallback (consistent behaviour across the no-pkgjson branch).
     return tryLegacyDirectorySubpath(vfs, pkgDir, subpath, sink);
   }
-  let pkg: { exports?: any; module?: string; main?: string };
+  let pkg: ResolvablePackageJson;
   try { pkg = JSON.parse(vfs.readFileString(pkgJsonPath)); }
   catch {
     const r = resolveFile(vfs, pkgDir + '/index', sink);
@@ -477,7 +478,7 @@ function resolveImportsField(
   while (true) {
     const pkgJsonPath = (dir ? dir + '/' : '') + 'package.json';
     if (vfs.exists(pkgJsonPath) && !vfs.isDirectory(pkgJsonPath)) {
-      let pkg: any = null;
+      let pkg: ResolvablePackageJson | null = null;
       try { pkg = JSON.parse(vfs.readFileString(pkgJsonPath)); } catch { /* malformed */ }
       // First package.json wins (Node spec), even if no imports field.
       if (pkg && pkg.imports) {
@@ -618,8 +619,7 @@ export function prefetchForRequire(
     const stripped = stripCommentsForImports(code);
 
     REQUIRE_RE.lastIndex = 0;
-    let match;
-    while ((match = REQUIRE_RE.exec(stripped)) !== null) {
+    for (let match = REQUIRE_RE.exec(stripped); match !== null; match = REQUIRE_RE.exec(stripped)) {
       const specifier = match[2];
       if (isFacetProvided(specifier)) continue;
       const r = resolveRequireEx(vfs, specifier, fromDir, addPkgJson);
@@ -635,7 +635,7 @@ export function prefetchForRequire(
     // runtime W3.5 Fix B's CJS rewrite calls require('./x') which then
     // fails because `x` was never added.
     IMPORT_RE.lastIndex = 0;
-    while ((match = IMPORT_RE.exec(stripped)) !== null) {
+    for (let match = IMPORT_RE.exec(stripped); match !== null; match = IMPORT_RE.exec(stripped)) {
       const specifier = match[2];
       if (isFacetProvided(specifier)) continue;
       const r = resolveRequireEx(vfs, specifier, fromDir, addPkgJson);
@@ -647,7 +647,7 @@ export function prefetchForRequire(
     // Follow static-string dynamic imports so a CLI entry that defers to
     // import('./dist/index.js') has that subtree's content prefetched.
     DYNIMPORT_RE.lastIndex = 0;
-    while ((match = DYNIMPORT_RE.exec(stripped)) !== null) {
+    for (let match = DYNIMPORT_RE.exec(stripped); match !== null; match = DYNIMPORT_RE.exec(stripped)) {
       const specifier = match[2];
       if (isFacetProvided(specifier)) continue;
       const r = resolveRequireEx(vfs, specifier, fromDir, addPkgJson);

package/src/runtime/runtime-registry.ts

@@ -43,6 +43,8 @@ import { CRED_KERNEL, type VfsCred } from './os-contracts.js';
 import type { EsbuildService } from './esbuild-service.js';
 import { parseFacetBundleProfile, type FacetBundleProfile } from './bundle-profile.js';
 import { bindImportMetaResolve, importMetaDefines } from './import-meta-transform.js';
+import type { Command, CommandContext } from '../substrate/lifo/commands/types.js';
+import { errorText } from '../_shared/error-text.js';
 
 /**
  * Result shape that runtime-registry expects from a runner. Mirrors
@@ -130,7 +132,7 @@ export function resolveRuntimeScriptPath(
  * a second one.
  */
 export type RuntimeSubcommand = (
-  ctx: any,
+  ctx: CommandContext,
   registry: ShellRegistry,
   runAsRuntime: (args: string[]) => Promise<number>,
 ) => Promise<number>;
@@ -181,7 +183,7 @@ export interface RuntimeSpec {
  * shell registry type tree when the runtime path only needs resolve().
  */
 export interface ShellRegistry {
-  resolve(name: string): Promise<any> | any;
+  resolve(name: string): Promise<Command | null | undefined> | Command | null | undefined;
 }
 
 /**
@@ -201,7 +203,7 @@ export function buildRuntimeHandler(
     getEsbuild(): EsbuildService | Promise<EsbuildService>;
     registry: ShellRegistry;
   },
-): (ctx: any) => Promise<number> {
+): Command {
   const { vfs, getEsbuild, registry } = ctx0;
   const fs = vfs.as(CRED_KERNEL);
 
@@ -211,7 +213,7 @@ export function buildRuntimeHandler(
    * caller has already consumed them — so a verb handler can delegate
    * back in with a rewritten argv without re-triggering itself.
    */
-  async function runtimeInvocation(ctx: any, args: string[]): Promise<number> {
+  async function runtimeInvocation(ctx: CommandContext, args: string[]): Promise<number> {
     const name = spec.name;
     const nimbusCtx = ctx as {
       __nimbusCaptureOutput?: unknown;
@@ -449,8 +451,8 @@ export function buildRuntimeHandler(
           define: importMetaDefines(absUrl),
         });
         code = bindImportMetaResolve(transformed.code, absUrl);
-      } catch (e: any) {
-        ctx.stderr.write(`${name}: transform error for ${scriptPath}: ${e?.message}\n`);
+      } catch (e) {
+        ctx.stderr.write(`${name}: transform error for ${scriptPath}: ${errorText(e)}\n`);
         return 1;
       }
     }
@@ -488,7 +490,7 @@ export function buildRuntimeHandler(
     return result.exitCode;
   }
 
-  return async function runtimeHandler(ctx: any): Promise<number> {
+  return async function runtimeHandler(ctx: CommandContext): Promise<number> {
     const args: string[] = ctx.args || [];
 
     // ── Subcommand dispatch ──