1tube 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1tube",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",

package/src/backends/workerd/backend.ts

@@ -31,7 +31,7 @@
  * braces guarantee.
  */
 
-import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { isAbsolute, join, relative, resolve as resolvePath } from "node:path";
 import { ensureDir } from "jsr:@std/fs@^1/ensure-dir";
 import { type AuthContext } from "../../registry.ts";
 import { type FunctionManifest, loadManifest } from "../../manifest.ts";
@@ -47,6 +47,14 @@ import {
   parsePrebuiltManifest,
   type PrebuiltManifest,
 } from "./prebuilt.ts";
+import {
+  copyPrebuiltRuntimeFiles,
+  defaultRuntimeOverrideRoot,
+  RuntimeOverrideStore,
+  type EditableSourceResponse,
+  type EditableFunctionSummary,
+  type SaveEditableSourceInput,
+} from "./runtime-overrides.ts";
 import { type CapnpRoute, generateCapnp } from "./capnp.ts";
 import {
   SHARED_RUNTIME_TOKEN_ENV,
@@ -76,6 +84,8 @@ export interface WorkerdBackendOptions {
    * `node_modules/` exists, else `.1tube-cache/workerd/`.
    */
   cacheDir?: string;
+  /** Writable runtime source/bundle overlay used by the admin edge editor. */
+  runtimeOverrideDir?: string;
   /** Loopback address for workerd sockets. Defaults to `"127.0.0.1"`. */
   bindAddress?: string;
   /** First port to assign to a function. Defaults to `8800`. */
@@ -84,6 +94,8 @@ export interface WorkerdBackendOptions {
   compatibilityDate?: string;
   /** Compatibility flags applied to every service. */
   compatibilityFlags?: readonly string[];
+  /** Pass `--experimental` to the workerd process. */
+  experimental?: boolean;
   /** Sourcemap mode passed to the bundler. */
   sourcemap?: boolean | "linked" | "inline";
   /** Sink for workerd's [workerd]-prefixed log lines. Defaults to stderr. */
@@ -135,8 +147,8 @@ export interface WorkerdBackendOptions {
    *
    * In this mode `functionsDir` is ignored, no bundler is created (so
    * the operator does not need esbuild's worker subprocess on the box),
-   * and `reload()` is unsupported — the artifact is sealed. HMR must
-   * not be enabled by the gateway when this is set.
+   * and runtime reloads compose the sealed artifact with admin
+   * overlays. HMR must not be enabled by the gateway when this is set.
    *
    * Bundle integrity is verified against the manifest's recorded
    * sha-256 at boot, so a tampered bundle fails fast with a clear
@@ -329,6 +341,12 @@ export interface WorkerdBackend {
    * exactly what the e2e tests assert on.
    */
   readonly lastReloadDurationMs: number | null;
+  listEditableFunctions(): Promise<EditableFunctionSummary[]>;
+  readEditableSource(name: string): Promise<EditableSourceResponse>;
+  saveEditableSource(name: string, input: SaveEditableSourceInput): Promise<WorkerdReloadResult>;
+  createEditableFunction(name: string): Promise<EditableSourceResponse>;
+  deleteEditableFunction(name: string): Promise<WorkerdReloadResult>;
+  revertEditableFunction(name: string): Promise<WorkerdReloadResult>;
   /** Tear down workerd and dispose esbuild's worker. Idempotent. */
   stop(): Promise<void>;
 }
@@ -639,6 +657,15 @@ export function resolveEnvAllowlist(
   return { resolved, missing, mode: "restricted" };
 }
 
+function runtimeSecretNames(envSource: EnvSource = Deno.env): string[] {
+  const raw = envSource.get("1TUBE_SECRET_NAMES") ?? "";
+  const names = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s));
+  return [...new Set(names)].sort();
+}
+
 /**
  * Compute the env vars exposed to a single function as workerd
  * `fromEnvironment` bindings.
@@ -815,6 +842,7 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
   // Mutable state set during start(). Kept in closure scope so dispatch()
   // can reach it without an extra indirection layer.
   let bundler: Bundler | null = null;
+  let overlayBundler: Bundler | null = null;
   let process: WorkerdProcess | null = null;
   let routesByName = new Map<string, CapnpRoute>();
   let workerdVersion: string | null = null;
@@ -858,8 +886,19 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
       ? opts.prebuiltDir
       : resolvePath(cwd, opts.prebuiltDir))
     : null;
+  const runtimeEditorEnabled = prebuiltDir !== null;
   let prebuiltManifest: PrebuiltManifest | null = null;
   let sharedRuntime: WorkerdSharedRuntime | null = null;
+  const runtimeOverrides = new RuntimeOverrideStore({
+    rootDir: opts.runtimeOverrideDir
+      ? (isAbsolute(opts.runtimeOverrideDir) ? opts.runtimeOverrideDir : resolvePath(cwd, opts.runtimeOverrideDir))
+      : defaultRuntimeOverrideRoot(cwd),
+    sourceFunctionsDir: resolvedFunctionsDir,
+    prebuiltDir,
+    getPrebuiltManifest: () => prebuiltManifest,
+    getLiveManifests: () => manifests,
+    getBundleBytes: () => bundleBytes,
+  });
 
   /**
    * Shared boot pipeline used by both `start()` and `reload()`.
@@ -907,7 +946,11 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
     // while live mode allocates the usual node_modules/.cache slot.
     if (cacheDir === null) {
       if (prebuiltDir !== null) {
-        cacheDir = prebuiltDir;
+        cacheDir = opts.cacheDir
+          ? (isAbsolute(opts.cacheDir) ? opts.cacheDir : resolvePath(cwd, opts.cacheDir))
+          : join(await defaultCacheDir(cwd), "prebuilt-runtime");
+        await ensureDir(cacheDir);
+        await writeGitignore(cacheDir);
       } else {
         cacheDir = opts.cacheDir
           ? (isAbsolute(opts.cacheDir) ? opts.cacheDir : resolvePath(cwd, opts.cacheDir))
@@ -924,6 +967,7 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
     // to the caller for the WorkerdReloadResult; prebuilt mode never
     // rebuilds anything so this stays empty there.
     let rebundledNames: string[] = [];
+    const overlayManifests = new Map<string, FunctionManifest>();
     if (prebuiltDir !== null) {
       // Prebuilt mode — every "bundle" already exists on disk. We
       // synthesise BundleResults from the manifest so the rest of
@@ -936,7 +980,14 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
         // with a null manifest. Raising hard makes the bug obvious.
         throw new Error("prebuilt manifest not loaded");
       }
-      let entries = prebuiltManifest.functions;
+      await copyPrebuiltRuntimeFiles(prebuiltManifest, prebuiltDir, cacheDir!);
+      const baseNames = new Set(prebuiltManifest.functions.map((e) => e.name));
+      const overlays = runtimeEditorEnabled
+        ? await runtimeOverrides.compose(baseNames)
+        : [];
+      for (const overlay of overlays) overlayManifests.set(overlay.name, overlay.manifest);
+      const patchedNames = new Set(overlays.filter((e) => e.origin === "patched").map((e) => e.name));
+      let entries = prebuiltManifest.functions.filter((e) => !patchedNames.has(e.name));
       if (opts.only && opts.only.length > 0) {
         const allow = new Set(opts.only);
         entries = entries.filter((e) => allow.has(e.name));
@@ -958,6 +1009,22 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
         byteLength: e.bundleBytes,
         durationMs: 0,
       }));
+      if (overlays.length > 0) {
+        if (!overlayBundler) {
+          overlayBundler = createBundler({
+            outDir: join(cacheDir!, "runtime-overrides"),
+            configPath,
+            sourcemap: "linked",
+            minify: true,
+          });
+        }
+        const overlayResults = await overlayBundler.bundleAll(
+          overlays.map((entry) => ({ name: entry.name, entrypoint: entry.entrypoint })),
+          { concurrency: opts.bundleConcurrency ?? 4 },
+        );
+        bundleResults.push(...overlayResults);
+        rebundledNames = overlayResults.map((r) => r.name);
+      }
       for (const shared of prebuiltManifest.sharedModules) {
         sharedModules.push({
           id: shared.id,
@@ -976,6 +1043,18 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
           );
         }
       }
+      const baseNames = new Set(inputs.map((i) => i.name));
+      const overlays = runtimeEditorEnabled
+        ? await runtimeOverrides.compose(baseNames)
+        : [];
+      for (const overlay of overlays) overlayManifests.set(overlay.name, overlay.manifest);
+      if (overlays.length > 0) {
+        const overlayNames = new Set(overlays.map((entry) => entry.name));
+        inputs = [
+          ...inputs.filter((input) => !overlayNames.has(input.name)),
+          ...overlays.map((entry) => ({ name: entry.name, entrypoint: entry.entrypoint })),
+        ].sort((a, b) => a.name.localeCompare(b.name));
+      }
       if (inputs.length === 0) {
         // Empty functions dir is a legitimate state — typically a
         // fresh deployment that hasn't received its first firmware
@@ -1121,16 +1200,22 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
         }
       }
 
-      // Resolve the gateway-wide env allowlist. This is the *maximum*
-      // surface any single function can ask for; per-function manifests
-      // narrow it further via `permissions.env`. Most-restrictive wins
-      // — operator declares what's available, the function declares
-      // what it actually uses, and we hand workerd the intersection.
+      // Resolve the gateway-wide env policy. Workerd gets live secrets
+      // plus the operator's explicit allowlist. We deliberately do not
+      // infer source usage here: dynamic access is common, and secrets
+      // are runtime configuration.
+      const hasConfiguredEnvPolicy = (opts.envAllowlist?.length ?? 0) > 0 ||
+        ((Deno.env.get("1TUBE_WORKERD_ENV") ?? "").trim().length > 0);
+      const secretNames = runtimeSecretNames();
       const {
-        resolved: envBindings,
+        resolved: configuredEnvBindings,
         missing: missingEnv,
-        mode: envMode,
+        mode: configuredEnvMode,
       } = resolveEnvAllowlist(opts.envAllowlist);
+      const gatewayEnvBindings = [...new Set([
+        ...secretNames,
+        ...(hasConfiguredEnvPolicy ? configuredEnvBindings : []),
+      ])].sort();
       if (missingEnv.length > 0) {
         console.warn(
           `[1tube] workerd env allowlist references vars not present in the gateway env: ` +
@@ -1138,17 +1223,20 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
             `Set them before starting the gateway, or remove them from the allowlist.`,
         );
       }
-      if (envBindings.length > 0) {
-        if (envMode === "all") {
+      if (hasConfiguredEnvPolicy && configuredEnvBindings.length > 0) {
+        if (configuredEnvMode === "all") {
           console.log(
-            `[1tube] forwarding all ${envBindings.length} env var(s) to workerd ` +
-              `(default; pass --workerd-env=A,B,C or set 1TUBE_WORKERD_ENV to restrict)`,
+            `[1tube] forwarding all ${configuredEnvBindings.length} env var(s) to workerd ` +
+              `plus ${secretNames.length} runtime secret name(s) (explicit '*')`,
           );
         } else {
           console.log(
-            `[1tube] forwarding ${envBindings.length} env var(s) to workerd: ${envBindings.join(", ")}`,
+            `[1tube] forwarding ${gatewayEnvBindings.length} env var(s) to workerd ` +
+              `(${secretNames.length} secret(s), ${configuredEnvBindings.length} explicit): ${gatewayEnvBindings.join(", ")}`,
           );
         }
+      } else if (secretNames.length > 0) {
+        console.log(`[1tube] forwarding ${secretNames.length} runtime secret env var(s) to workerd: ${secretNames.join(", ")}`);
       }
 
       // Load each function's 1tube.json. Missing files yield
@@ -1165,16 +1253,19 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
       const newManifests = new Map<string, FunctionManifest>();
       if (prebuiltDir !== null && prebuiltManifest) {
         for (const e of prebuiltManifest.functions) {
-          newManifests.set(e.name, e.manifest);
+          if (!overlayManifests.has(e.name)) newManifests.set(e.name, e.manifest);
         }
       } else {
         await Promise.all(
           bundleResults.map(async (r) => {
-            const m = await loadManifest(resolvedFunctionsDir, r.name);
+            const m = overlayManifests.get(r.name) ?? await loadManifest(resolvedFunctionsDir, r.name);
             newManifests.set(r.name, m);
           }),
         );
       }
+      for (const [name, manifest] of overlayManifests) {
+        newManifests.set(name, manifest);
+      }
 
       // Mirror the Deno backend's two-mode env story:
       //   - Default: every function sees the full gateway allowlist.
@@ -1200,9 +1291,11 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
         : [];
       const capnpInputs = bundleResults.map((r) => {
         const m = newManifests.get(r.name)!;
-        const bundleEmbedPath = prebuiltBundleFiles?.get(r.name) ??
-          r.bundlePath.split(/[\\/]/).pop()!;
-        const fnEnvBindings = intersectEnvForFunction(envBindings, m.permissions.env, enforceManifest);
+        const bundleEmbedPath = overlayManifests.has(r.name)
+          ? relative(cacheDir!, r.bundlePath).replaceAll("\\", "/")
+          : prebuiltBundleFiles?.get(r.name) ??
+            relative(cacheDir!, r.bundlePath).replaceAll("\\", "/");
+        const fnEnvBindings = intersectEnvForFunction(gatewayEnvBindings, m.permissions.env, enforceManifest);
         for (const internalName of internalEnvBindings) {
           if (!fnEnvBindings.includes(internalName)) fnEnvBindings.push(internalName);
         }
@@ -1213,7 +1306,7 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
           // and capnp is written at dist/, so use the manifest-relative
           // path ("functions/<fn>.js") or workerd cannot resolve embeds.
           bundleBasename: bundleEmbedPath,
-          moduleFiles: prebuiltModuleFiles?.get(r.name),
+          moduleFiles: overlayManifests.has(r.name) ? undefined : prebuiltModuleFiles?.get(r.name),
           envBindings: fnEnvBindings,
         };
       });
@@ -1241,6 +1334,21 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
 
       const newRoutesByName = new Map(capnp.routes.map((r) => [r.name, r]));
       const newNames = capnp.routes.map((r) => r.name).sort();
+      if (args.gen === 0) {
+        const ports = capnp.routes.map((r) => r.port);
+        const minPort = Math.min(...ports);
+        const maxPort = Math.max(...ports);
+        const totalEnvBindings = capnpInputs.reduce((sum, input) => sum + (input.envBindings?.length ?? 0), 0);
+        const maxEnvBindings = capnpInputs.reduce((max, input) => Math.max(max, input.envBindings?.length ?? 0), 0);
+        console.log(
+          `[1tube] workerd config: path=${capnpPath} services=${capnp.routes.length} ` +
+            `ports=${minPort}${minPort === maxPort ? "" : `-${maxPort}`} ` +
+            `compat=${effectiveCompatDate ?? "default"} ` +
+            `flags=${(opts.compatibilityFlags ?? ["default"]).join(",")} ` +
+            `envMode=${hasConfiguredEnvPolicy ? configuredEnvMode : "secrets"} ` +
+            `envBindingsTotal=${totalEnvBindings} envBindingsMaxPerFn=${maxEnvBindings}`,
+        );
+      }
 
       // Preflight: refuse to spawn workerd against ports that are
       // already in use. Without this, a leftover workerd from a
@@ -1341,11 +1449,20 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
 
       const maxHeapArgs = buildMaxHeapExtraArgs(opts.maxHeapMB);
       const extraArgs = [...inspectorArgs, ...maxHeapArgs];
+      const verboseWorkerd = (Deno.env.get("1TUBE_WORKERD_VERBOSE") ?? "") === "1";
+      if (verboseWorkerd) {
+        console.log(`[1tube] workerd verbose logging enabled (1TUBE_WORKERD_VERBOSE=1)`);
+      }
+      const globalArgs = [
+        ...(verboseWorkerd ? ["-v"] : []),
+        ...(opts.experimental ? ["--experimental"] : []),
+      ];
 
       const newProcess = createWorkerdProcess({
         binary: workerdBin,
         capnpPath,
         routes: capnp.routes,
+        ...(globalArgs.length > 0 ? { globalArgs } : {}),
         extraArgs,
         env: sharedRuntime
           ? {
@@ -1560,6 +1677,15 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
     return reloadInFlight;
   }
 
+  function requireRuntimeEditor(): void {
+    if (!runtimeEditorEnabled) {
+      throw new Error(
+        "edge function runtime editor is disabled outside prebuilt workerd mode; " +
+          "use HMR/source files for local development",
+      );
+    }
+  }
+
   return {
     get pid() {
       return process?.pid ?? null;
@@ -1586,6 +1712,7 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
     async start() {
       if (started) throw new Error("workerd backend already started");
       started = true;
+      if (runtimeEditorEnabled) await runtimeOverrides.load();
 
       // Load + verify the prebuilt manifest BEFORE probing workerd, so
       // a stale / tampered artifact fails with a clear error before we
@@ -1745,16 +1872,14 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
     },
 
     reload(changed) {
-      // Prebuilt artifacts are sealed — block every public reload
-      // request. Crash-recovery still works because the internal
-      // crash handler calls `doReload` directly (re-spawning workerd
-      // against the same on-disk bundles is legitimate; only
-      // re-bundling is forbidden).
+      // Keep the public API contract: prebuilt firmware is immutable
+      // from HMR/test callers. Runtime editor admin methods below use
+      // doReload() directly after mutating the overlay store.
       if (prebuiltDir !== null) {
         return Promise.reject(
           new Error(
-            "workerd backend is in prebuilt mode; reload is not supported. " +
-              "Re-run `1tube build` and restart the gateway to pick up changes.",
+            "workerd backend is in prebuilt mode; public reload is not supported. " +
+              "Use the runtime editor APIs for overlay hot-swaps, or promote new firmware.",
           ),
         );
       }
@@ -1802,6 +1927,44 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
       }
     },
 
+    async listEditableFunctions() {
+      requireRuntimeEditor();
+      return await runtimeOverrides.list(new Set(names));
+    },
+
+    async readEditableSource(name) {
+      requireRuntimeEditor();
+      return await runtimeOverrides.read(name, new Set(names));
+    },
+
+    async createEditableFunction(name) {
+      requireRuntimeEditor();
+      if (names.includes(name.trim())) {
+        throw new Error(`function "${name}" exists in firmware; open Code and save a patch instead`);
+      }
+      const source = await runtimeOverrides.create(name);
+      await doReload(new Set([name]));
+      return source;
+    },
+
+    async saveEditableSource(name, input) {
+      requireRuntimeEditor();
+      await runtimeOverrides.save(name, input, new Set(names));
+      return await doReload(new Set([name]));
+    },
+
+    async deleteEditableFunction(name) {
+      requireRuntimeEditor();
+      await runtimeOverrides.deleteAdded(name);
+      return await doReload("all");
+    },
+
+    async revertEditableFunction(name) {
+      requireRuntimeEditor();
+      await runtimeOverrides.revert(name);
+      return await doReload(new Set([name]));
+    },
+
     async stop() {
       if (stopping) return;
       stopping = true;
@@ -1814,8 +1977,12 @@ export function createWorkerdBackend(opts: WorkerdBackendOptions): WorkerdBacken
         if (bundler) {
           await bundler.dispose().catch(() => {});
         }
+        if (overlayBundler && overlayBundler !== bundler) {
+          await overlayBundler.dispose().catch(() => {});
+        }
         sharedRuntime = null;
         bundler = null;
+        overlayBundler = null;
         process = null;
         manifests.clear();
       }

package/src/backends/workerd/prebuilt.ts

@@ -39,6 +39,8 @@ export interface PrebuiltFunctionEntry {
   moduleFiles: string[];
   /** Per-function `1tube.json` parsed at build time. */
   manifest: FunctionManifest;
+  /** Optional inspectable authored source files under `sources/<name>/`. */
+  sourceFiles?: string[];
 }
 
 export interface PrebuiltChunkEntry {
@@ -128,6 +130,9 @@ export function parsePrebuiltManifest(raw: unknown): PrebuiltManifest {
       bundleSha256,
       moduleFiles: moduleFiles.length > 0 ? moduleFiles : [bundleFile],
       manifest: parseManifest(e.manifest, /* fromFile */ true),
+      sourceFiles: Array.isArray(e.sourceFiles)
+        ? e.sourceFiles.filter((n): n is string => typeof n === "string")
+        : undefined,
     };
   });
   const chunks: PrebuiltChunkEntry[] = Array.isArray(obj.chunks)

package/src/backends/workerd/process.ts

@@ -44,6 +44,8 @@ const DEFAULT_READY_TIMEOUT_MS = 15_000;
 const DEFAULT_PROBE_INTERVAL_MS = 50;
 /** Default grace period before escalating from SIGTERM to SIGKILL. */
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
+/** Bounded child-output tail attached to startup failures. */
+const OUTPUT_TAIL_LINES = 800;
 
 export interface WorkerdProcessOptions {
   /** Absolute or PATH-resolvable path to the `workerd` binary. */
@@ -362,6 +364,46 @@ function bestEffortKill(child: Deno.ChildProcess, signal: Deno.Signal): boolean
   }
 }
 
+function quoteArg(arg: string): string {
+  return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+
+function summarizeRoutes(routes: readonly CapnpRoute[]): string {
+  if (routes.length === 0) return "routes=0";
+  const ports = routes.map((r) => r.port);
+  const min = Math.min(...ports);
+  const max = Math.max(...ports);
+  const hosts = [...new Set(routes.map((r) => r.address))].join(",");
+  return `routes=${routes.length} hosts=${hosts} ports=${min}${min === max ? "" : `-${max}`}`;
+}
+
+function formatStartupFailure(opts: {
+  command: readonly string[];
+  cwd: string;
+  capnpPath: string;
+  routes: readonly CapnpRoute[];
+  exitCode: number | null | undefined;
+  outputTail: readonly string[];
+  cause: unknown;
+}): string {
+  const lines = [
+    "workerd exited before sockets became ready",
+    `  exitCode=${opts.exitCode ?? "<unknown>"}`,
+    `  command=${opts.command.map(quoteArg).join(" ")}`,
+    `  cwd=${opts.cwd}`,
+    `  capnp=${opts.capnpPath}`,
+    `  ${summarizeRoutes(opts.routes)}`,
+  ];
+  if (opts.cause instanceof Error) {
+    lines.push(`  readiness=${opts.cause.message}`);
+  }
+  if (opts.outputTail.length > 0) {
+    lines.push(`  -- last ${opts.outputTail.length} workerd output line(s) --`);
+    for (const line of opts.outputTail) lines.push(`  | ${line}`);
+  }
+  return lines.join("\n");
+}
+
 /** Build the manager. Stateful — caller owns lifecycle. */
 export function createWorkerdProcess(opts: WorkerdProcessOptions): WorkerdProcess {
   const sink = opts.logLineSink ?? defaultLogLineSink;
@@ -402,14 +444,23 @@ export function createWorkerdProcess(opts: WorkerdProcessOptions): WorkerdProces
       // a transitive node-path dependency on this module; the inline
       // separator-aware split is enough for our purposes.
       const cwd = opts.cwd ?? opts.capnpPath.replace(/[\\/][^\\/]+$/, "");
+      const args = [
+        ...(opts.globalArgs ?? []),
+        "serve",
+        opts.capnpPath,
+        ...(opts.extraArgs ?? []),
+      ];
+      const command = [opts.binary, ...args];
+      const outputTail: string[] = [];
+      let exitCode: number | null | undefined;
+      const captureLine = (line: string) => {
+        outputTail.push(line);
+        while (outputTail.length > OUTPUT_TAIL_LINES) outputTail.shift();
+        sink(line);
+      };
 
       const cmd = new Deno.Command(opts.binary, {
-        args: [
-          ...(opts.globalArgs ?? []),
-          "serve",
-          opts.capnpPath,
-          ...(opts.extraArgs ?? []),
-        ],
+        args,
         cwd,
         env: opts.env,
         stdout: "piped",
@@ -421,8 +472,8 @@ export function createWorkerdProcess(opts: WorkerdProcessOptions): WorkerdProces
       // Pump stdout + stderr into the sink. Both pumps are awaited at
       // shutdown so the consumer can be sure no lines are lost.
       pumpsDone = Promise.all([
-        pumpLines(child.stdout, sink),
-        pumpLines(child.stderr, sink),
+        pumpLines(child.stdout, captureLine),
+        pumpLines(child.stderr, captureLine),
       ]).then(() => {});
 
       // Watch for early exit so a workerd that crashes during boot
@@ -430,6 +481,7 @@ export function createWorkerdProcess(opts: WorkerdProcessOptions): WorkerdProces
       // the readiness wait instead of hanging until the timeout.
       const exitAbort = new AbortController();
       const exitWatch = child.status.then((status) => {
+        exitCode = status.code;
         const expected = stopRequested;
         if (!expected) {
           // Crash before ready or during runtime. Abort the readiness
@@ -455,11 +507,17 @@ export function createWorkerdProcess(opts: WorkerdProcessOptions): WorkerdProces
         // (extremely rare with workerd, but defence in depth).
         if (child) bestEffortKill(child, "SIGKILL");
         await exitWatch.catch(() => {}); // swallow — already in failure path
+        if (pumpsDone) await pumpsDone.catch(() => {});
         if (exitAbort.signal.aborted) {
-          throw new Error(
-            `workerd exited before sockets became ready` +
-              (err instanceof Error ? `: ${err.message}` : ""),
-          );
+          throw new Error(formatStartupFailure({
+            command,
+            cwd,
+            capnpPath: opts.capnpPath,
+            routes: opts.routes,
+            exitCode,
+            outputTail,
+            cause: err,
+          }));
         }
         throw err;
       }