sproutboat 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -10,6 +10,47 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.45.0] - 2026-10-29
+
+### Added
+
+- **`sproutboat tail` is a live tail.** It streams the app's request events, `console.*` output and uncaught
+  exceptions from the control plane (`GET /api/projects/<name>/tail`, Server-Sent Events) in the shape of a
+  Workers tail event. Pretty colored lines by default, one JSON event per line with `--format json`. Server-side
+  filters: `--status ok|error|<code>|5xx`, `--method GET,POST`, `--sampling-rate 0.1`, `--search <text>`,
+  `--outcome <name>`. It reconnects when the server's ten minute cap closes the stream, reports dropped events on
+  stderr, and exits 0 on Ctrl-C. Console lines are separate events, not attached to a request (the runtime does not
+  tag them with a request id).
+
+### Changed
+
+- **`sproutboat tail` with no flags no longer prints and exits.** The old dump of the last 100 request records is
+  `sproutboat tail --recent`; `--sprout` is unchanged. Live tail needs a control plane newer than v0.12.0; against
+  an older one the command says so and points at `--recent`.
+
+## [0.44.0] - 2026-10-29
+
+Built on `@sproutboat/runtime` 0.36.0, `@sproutboat/toolchain` 0.21.0 and
+`@sproutboat/wire` 0.20.4.
+
+### Added
+
+- **`AsyncLocalStorage`** from `node:async_hooks`, as Workers has it: `run`, `exit`, `getStore` and the static
+  `snapshot`. `enterWith` and `disable` throw, as there. The store follows a request across awaits,
+  microtasks, timers, intervals, async `fetch`, WebSocket callbacks and `ctx.waitUntil`, and requests
+  interleaved in one process never see each other's. The static `bind` is not provided: Porffor compiles a
+  `.bind(` call on a function value to `Function.prototype.bind`, so use `snapshot()`. The import used to
+  build and then throw "not a constructor" when the app ran, so there is no compatibility date for it. Cost: a
+  promise reaction is 56 bytes instead of 40.
+
+### Changed
+
+- **`x-sb-cpu-ms` is per request when requests interleave in one process.** A request is charged the thread
+  CPU time of the slices in which it ran, not the process delta across its handler, so a request is no longer
+  charged for its neighbours' work. From compatibility date `2026-11-02` an async handler is stamped too
+  (logs show it as `cpuMs`); earlier dates still send no stamp for an async handler. A synchronous
+  handler's stamp is thread time, which leaves out the egress threads.
+
 ## [0.43.0] - 2026-10-29
 
 Built on `@sproutboat/runtime` 0.35.0, `@sproutboat/toolchain` 0.20.1 and

package/README.md

@@ -70,7 +70,7 @@ The everyday loop:
 | `init [name]` | Scaffold `sproutboat.jsonc` + `src/index.js` |
 | `dev [--port <n>]` | Run it here against a real broker, rebuilding on save |
 | `deploy` | Build, provision bindings, upload, wait until the URL serves |
-| `tail [--sprout]` | Recent request logs, or the running sprout's output |
+| `tail [filters]` | Live request events, console output and exceptions, like `wrangler tail` |
 | `rollback <id>` | Re-activate a previous version |
 
 Then `check`, `build`, `versions`, `delete`, `login` / `logout` / `whoami`, and
@@ -78,6 +78,45 @@ one command per storage product — `kv`, `d1`, `r2`, `queues`, `secrets`,
 `domains` — each with the same five verbs.
 
 Run `sproutboat` with no arguments for the grouped list.
+
+### Live tail
+
+`sproutboat tail` streams one app's events as they happen. Each request prints
+its time, method, URL, status, outcome and CPU and wall milliseconds; the app's
+`console.*` output and uncaught exceptions print as their own lines.
+
+```sh
+sproutboat tail                                  # pretty, colored
+sproutboat tail --status 5xx --search checkout   # server-side filters
+sproutboat tail --format json | jq 'select(.outcome != "ok")'
+sproutboat tail --recent                         # the last 100 request records (the old behaviour)
+sproutboat tail --sprout                         # the sprout's raw stdout/stderr
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--format pretty\|json` | Colored lines (default), or one JSON event per line |
+| `--status` | `ok` (below 400), `error` (5xx or a platform failure), a code like `404`, or a class like `5xx`; repeat or comma-separate |
+| `--method` | `GET,POST`; repeat or comma-separate. Console-only events have no method, so this hides them |
+| `--sampling-rate` | Keep this fraction of events, 0 to 1 |
+| `--search` | Case-insensitive substring over the URL, console messages and exception text |
+| `--outcome` | `ok`, `exception`, `exceededWallTime`, `canceled`, `unavailable`, `noRoute`, `proxyError`, ... |
+
+Things to know:
+
+- **Console lines are not tied to a request.** Concurrent requests share one
+  process and the runtime does not tag a line with a request id, so console
+  output is printed on its own, flush left, and never indented under a request.
+  Lines carry the time the control plane saw them (about one second of
+  resolution). The runtime sends `console.log`, `warn` and `error` to the same
+  stream without a level, so they all show as `log`; uncaught exceptions are
+  recognised and shown as errors with their stack.
+- The server caps the stream at ten minutes and the CLI reconnects; events in
+  the gap are not replayed. It also caps events per second and reports the
+  count it dropped on stderr, which keeps stdout clean for `--format json`.
+- Needs a control plane with `GET /api/projects/<name>/tail` (Sproutboat
+  platform after v0.12.0). Against an older one, use `--recent`.
+- Ctrl-C stops the stream and exits 0.
 [`SURFACE.md`](SURFACE.md) is the generated inventory: every command, every
 argument, every env var, kept honest by a drift test.
 

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.43.0
+**Package:** `sproutboat` 0.45.0
 
 ## Commands
 
@@ -18,7 +18,7 @@
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores. |
 | `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
-| `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
+| `tail` | `[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout]` | Stream live request events, console output and exceptions (like wrangler tail); --recent prints the last 100 request records, --sprout the running sprout + broker stdout/stderr. |
 | `kv` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ...` | KV namespaces. `create` prints the id to bind from sproutboat.jsonc; key and bulk operations manage contents, and export writes a restorable JSON dump. |
 | `d1` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | D1 databases. `create` prints the id to bind from sproutboat.jsonc. |
 | `r2` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | R2 buckets. `create` prints the id to bind from sproutboat.jsonc. |
@@ -32,7 +32,7 @@
 | `complete` | `[bash | zsh | fish]` | Print a shell completion script for the top-level commands (defaults to $SHELL). |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
+usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
 ```
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -64,9 +64,9 @@
     "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.6.0",
-    "@sproutboat/runtime": "^0.35.0",
-    "@sproutboat/toolchain": "^0.20.1",
-    "@sproutboat/wire": "^0.20.3"
+    "@sproutboat/runtime": "^0.36.0",
+    "@sproutboat/toolchain": "^0.21.0",
+    "@sproutboat/wire": "^0.20.4"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.43.0",
-    "@sproutboat/cli-darwin-x64": "0.43.0",
-    "@sproutboat/cli-linux-arm64": "0.43.0",
-    "@sproutboat/cli-linux-x64": "0.43.0"
+    "@sproutboat/cli-darwin-arm64": "0.45.0",
+    "@sproutboat/cli-darwin-x64": "0.45.0",
+    "@sproutboat/cli-linux-arm64": "0.45.0",
+    "@sproutboat/cli-linux-x64": "0.45.0"
   },
   "engines": {
     "node": ">=18"

package/src/main.ts

@@ -20,6 +20,7 @@ import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
 import { pathToFileURL } from "node:url";
 import { inspectToolchain } from "./toolchain";
+import { parseTailArgs, runTail, TAIL_USAGE, tailQuery } from "./tail";
 
 // A compiled Bun executable is not a general-purpose `bun` command. Porffor
 // is acquired after installation, so run its external ESM launcher through an
@@ -607,7 +608,7 @@ async function deploy(args: string[]) {
   if (!args.includes("--no-wait") && !(await waitForHealthy(deployed.url, 90_000))) {
     console.warn(
       amber(
-        "  ! not serving after 90s — Caddy may still be issuing the cert, or the sprout is crashing (`sproutboat tail`)",
+        "  ! not serving after 90s — Caddy may still be issuing the cert, or the sprout is crashing (`sproutboat tail`, `tail --sprout`)",
       ),
     );
   }
@@ -781,14 +782,33 @@ async function rollback(args: string[]) {
 }
 
 async function tail(args: string[]) {
-  const sproutLog = args.includes("--sprout");
-  const dir = args.find((arg) => !arg.startsWith("-"));
-  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(dir), apiCredentials()]);
-  const path = sproutLog ? "logs/sprout" : "logs/recent";
-  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/${path}`, {
-    headers: { "x-api-key": token },
-  });
-  process.stdout.write(await responseText(response, "could not read logs"));
+  const result = parseTailArgs(args);
+  if ("error" in result) usageError(result.error, TAIL_USAGE);
+  const parsed = result.args;
+  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(parsed.dir), apiCredentials()]);
+  const base = `${apiUrl}/api/projects/${project.config.name}`;
+  if (parsed.recent || parsed.sprout) {
+    const response = await fetch(`${base}/logs/${parsed.sprout ? "sprout" : "recent"}`, {
+      headers: { "x-api-key": token },
+    });
+    process.stdout.write(await responseText(response, "could not read logs"));
+    return;
+  }
+  // Ctrl-C (or a terminated pipe reader) ends the stream and exits 0.
+  const controller = new AbortController();
+  for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => controller.abort());
+  process.stdout.on("error", () => controller.abort());
+  const query = tailQuery(parsed);
+  try {
+    await runTail({
+      url: `${base}/tail${query ? `?${query}` : ""}`,
+      headers: { "x-api-key": token },
+      format: parsed.format,
+      signal: controller.signal,
+    });
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
 }
 
 type DomainView = {

package/src/node-shims.ts

@@ -371,7 +371,17 @@ export { NodeURL as URL, NodeURLSearchParams as URLSearchParams, urlFormat as fo
 export default { URL: NodeURL, URLSearchParams: NodeURLSearchParams, format: urlFormat, parse: urlParse, resolve: urlResolve };
 `;
 
+// AsyncLocalStorage comes from the runtime (sproutboat-packages: the prelude defines it on globalThis,
+// over an async context kept by the patched Porffor). Bun's own node:async_hooks polyfill builds but
+// its AsyncLocalStorage is not a constructor in a compiled handler. Aliased, like the node:url shim.
+const NODE_ASYNC_HOOKS_SHIM = `
+const SbAsyncLocalStorage = globalThis.AsyncLocalStorage;
+export { SbAsyncLocalStorage as AsyncLocalStorage };
+export default { AsyncLocalStorage: SbAsyncLocalStorage };
+`;
+
 export const NODE_SHIMS = {
+  "node:async_hooks": NODE_ASYNC_HOOKS_SHIM,
   "node:path": NODE_PATH_SHIM,
   "node:querystring": NODE_QUERYSTRING_SHIM,
   "node:url": NODE_URL_SHIM,

package/src/surface.ts

@@ -141,8 +141,10 @@ export const COMMANDS: readonly Command[] = [
     name: "tail",
     group: "Ship",
     emoji: "📡",
-    args: "[project-dir] [--sprout]",
-    summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead.",
+    args: "[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout]",
+    brief: "[--status 5xx] [--search <text>]",
+    summary:
+      "Stream live request events, console output and exceptions (like wrangler tail); --recent prints the last 100 request records, --sprout the running sprout + broker stdout/stderr.",
   },
 
   ...storageCommands,

package/src/tail.ts

@@ -0,0 +1,409 @@
+/**
+ * `sproutboat tail`: stream one app's live events from the control plane
+ * (`GET /api/projects/<name>/tail`, Server-Sent Events) the way `wrangler tail`
+ * does. Request events come from the edge log; console output and uncaught
+ * exceptions come from the sprout's own output and arrive as their own events,
+ * never attached to a request (the runtime does not tag a console line with a
+ * request id). The server enforces the filters, a per-second event cap and a
+ * ten minute connection cap; this side reconnects when that cap closes the stream.
+ */
+import { isString, jsonObject, parseJsonValue, type JsonObject, type JsonValue } from "./json";
+import { amber, bold, dim, leaf, rose } from "./style";
+
+export type TailFormat = "pretty" | "json";
+
+export type TailArgs = {
+  dir: string | undefined;
+  format: TailFormat;
+  recent: boolean;
+  sprout: boolean;
+  status: string[];
+  method: string[];
+  samplingRate: string | undefined;
+  search: string | undefined;
+  outcome: string[];
+};
+
+export type TailLog = { level: string; message: JsonValue[]; timestamp: number };
+export type TailException = { name: string; message: string; timestamp: number; stack?: string };
+export type TailEvent = {
+  scriptName: string;
+  outcome: string;
+  eventTimestamp: number;
+  event: {
+    request: { url: string; method: string; headers?: Record<string, string> };
+    response: { status: number };
+  } | null;
+  cpuTime: number | null;
+  wallTime: number;
+  logs: TailLog[];
+  exceptions: TailException[];
+};
+
+export type TailFrame =
+  | { type: "ready" }
+  | { type: "event"; event: TailEvent }
+  | { type: "dropped"; count: number; bytes?: number; reason: string }
+  | { type: "closed"; reason: string };
+
+export const TAIL_USAGE =
+  "tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate 0.1] [--search <text>] [--outcome <name>] | tail --recent | tail --sprout";
+
+const VALUE_FLAGS = ["--format", "--status", "--method", "--sampling-rate", "--search", "--outcome"] as const;
+
+/** Parse `tail` arguments; `error` is a usage error message. */
+export function parseTailArgs(args: string[]): { args: TailArgs } | { error: string } {
+  const parsed: TailArgs = {
+    dir: undefined,
+    format: "pretty",
+    recent: false,
+    sprout: false,
+    status: [],
+    method: [],
+    samplingRate: undefined,
+    search: undefined,
+    outcome: [],
+  };
+  const split = (value: string) =>
+    value
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--recent") parsed.recent = true;
+    else if (arg === "--sprout") parsed.sprout = true;
+    else if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      const flag = eq < 0 ? arg : arg.slice(0, eq);
+      if (!VALUE_FLAGS.some((known) => known === flag)) return { error: `tail: unknown flag "${flag}"` };
+      const value = eq < 0 ? args[++index] : arg.slice(eq + 1);
+      if (value === undefined || (eq < 0 && value.startsWith("--"))) return { error: `tail: ${flag} needs a value` };
+      if (flag === "--format") {
+        if (value !== "pretty" && value !== "json")
+          return { error: `tail: --format must be pretty or json (got "${value}")` };
+        parsed.format = value;
+      } else if (flag === "--status") parsed.status.push(...split(value));
+      else if (flag === "--method") parsed.method.push(...split(value).map((method) => method.toUpperCase()));
+      else if (flag === "--outcome") parsed.outcome.push(...split(value));
+      else if (flag === "--sampling-rate") parsed.samplingRate = value;
+      else parsed.search = value;
+    } else if (parsed.dir === undefined) parsed.dir = arg;
+    else return { error: `tail: unexpected argument "${arg}"` };
+  }
+  const filtered =
+    parsed.status.length || parsed.method.length || parsed.outcome.length || parsed.samplingRate || parsed.search;
+  if (parsed.recent && parsed.sprout) return { error: "tail: --recent and --sprout are alternatives" };
+  if ((parsed.recent || parsed.sprout) && filtered)
+    return { error: "tail: filters apply to the live stream, not --recent or --sprout" };
+  for (const status of parsed.status) {
+    if (!/^(ok|error|[1-5]xx|[1-5]\d\d)$/i.test(status))
+      return {
+        error: `tail: --status must be ok, error, a code such as 404, or a class such as 5xx (got "${status}")`,
+      };
+  }
+  if (parsed.samplingRate !== undefined) {
+    const rate = Number(parsed.samplingRate);
+    if (parsed.samplingRate.trim() === "" || !Number.isFinite(rate) || rate < 0 || rate > 1)
+      return { error: "tail: --sampling-rate must be a number from 0 to 1" };
+  }
+  return { args: parsed };
+}
+
+/** Query string for the live endpoint. Repeatable filters repeat the parameter. */
+export function tailQuery(args: TailArgs): string {
+  const params = new URLSearchParams();
+  for (const status of args.status) params.append("status", status);
+  for (const method of args.method) params.append("method", method);
+  for (const outcome of args.outcome) params.append("outcome", outcome);
+  if (args.samplingRate !== undefined) params.set("sampling-rate", args.samplingRate);
+  if (args.search) params.set("search", args.search);
+  return params.toString();
+}
+
+/** Decode an SSE body into frames; comments (keepalives) and malformed data are skipped. */
+export async function* readFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<TailFrame> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      buffer += decoder.decode(next.value, { stream: true });
+      for (let cut = buffer.indexOf("\n\n"); cut >= 0; cut = buffer.indexOf("\n\n")) {
+        const block = buffer.slice(0, cut);
+        buffer = buffer.slice(cut + 2);
+        const data = block
+          .split("\n")
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).replace(/^ /, ""))
+          .join("\n");
+        if (!data) continue;
+        const frame = toFrame(data);
+        if (frame) yield frame;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function toFrame(data: string): TailFrame | undefined {
+  let value: JsonObject | undefined;
+  try {
+    value = jsonObject(parseJsonValue(data));
+  } catch {
+    return undefined;
+  }
+  if (!value) return undefined;
+  switch (value.type) {
+    case "ready":
+      return { type: "ready" };
+    case "closed":
+      return { type: "closed", reason: isString(value.reason) ? value.reason : "" };
+    case "dropped":
+      return {
+        type: "dropped",
+        count: num(value.count) ?? 0,
+        bytes: num(value.bytes),
+        reason: isString(value.reason) ? value.reason : "",
+      };
+    case "event": {
+      const event = toEvent(value.event);
+      return event ? { type: "event", event } : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function num(value: JsonValue | undefined): number | undefined {
+  return value !== undefined && Object(value) !== value && value === Number(value) && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function objects(value: JsonValue | undefined): JsonObject[] {
+  const found: JsonObject[] = [];
+  for (const entry of Array.isArray(value) ? value : []) {
+    const object = jsonObject(entry);
+    if (object) found.push(object);
+  }
+  return found;
+}
+
+function toEvent(value: JsonValue | undefined): TailEvent | undefined {
+  const event = value === undefined ? undefined : jsonObject(value);
+  if (!event || !isString(event.outcome)) return undefined;
+  const eventTimestamp = num(event.eventTimestamp);
+  if (eventTimestamp === undefined) return undefined;
+  const inner = jsonObject(event.event ?? null);
+  const request = jsonObject(inner?.request ?? null);
+  const response = jsonObject(inner?.response ?? null);
+  return {
+    scriptName: isString(event.scriptName) ? event.scriptName : "",
+    outcome: event.outcome,
+    eventTimestamp,
+    event:
+      request && response
+        ? {
+            request: {
+              url: isString(request.url) ? request.url : "",
+              method: isString(request.method) ? request.method : "",
+            },
+            response: { status: num(response.status) ?? 0 },
+          }
+        : null,
+    cpuTime: num(event.cpuTime) ?? null,
+    wallTime: num(event.wallTime) ?? 0,
+    logs: objects(event.logs).map((log) => ({
+      level: isString(log.level) ? log.level : "log",
+      message: Array.isArray(log.message) ? log.message : [],
+      timestamp: num(log.timestamp) ?? 0,
+    })),
+    exceptions: objects(event.exceptions).map((exception) => ({
+      name: isString(exception.name) ? exception.name : "Error",
+      message: isString(exception.message) ? exception.message : "",
+      timestamp: num(exception.timestamp) ?? 0,
+      stack: isString(exception.stack) ? exception.stack : undefined,
+    })),
+  };
+}
+
+const CROSS = "\u2717";
+
+const clock = (ms: number): string => {
+  const date = new Date(ms);
+  const pad = (n: number, width = 2) => String(n).padStart(width, "0");
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+};
+
+function statusColor(status: number, text: string): string {
+  if (status >= 500) return rose(text);
+  if (status >= 400) return amber(text);
+  if (status >= 300) return dim(text);
+  return leaf(text);
+}
+
+const message = (parts: JsonValue[]): string =>
+  parts.map((part) => (isString(part) ? part : JSON.stringify(part))).join(" ");
+
+/**
+ * Pretty lines for one event: the request line (time, method, url, status,
+ * outcome, cpu and wall ms), then its console lines and exceptions indented. A
+ * console-only event (the usual case, see the module comment) prints flush left
+ * so it does not read as belonging to the request printed above it.
+ */
+export function formatEvent(event: TailEvent): string[] {
+  const lines: string[] = [];
+  const time = dim(clock(event.eventTimestamp));
+  const indent = event.event ? "  " : "";
+  if (event.event) {
+    const { request, response } = event.event;
+    const cpu = event.cpuTime === null ? "cpu -" : `cpu ${Number(event.cpuTime.toFixed(2))}ms`;
+    const outcome = event.outcome === "ok" ? dim("ok") : rose(event.outcome);
+    lines.push(
+      `${time}  ${bold(request.method.padEnd(6))} ${request.url}  ${statusColor(response.status, String(response.status))}  ${outcome}  ${dim(`${cpu}, wall ${event.wallTime}ms`)}`,
+    );
+  }
+  for (const log of event.logs) {
+    const level = log.level === "error" ? rose(log.level) : log.level === "warn" ? amber(log.level) : dim(log.level);
+    for (const [index, text] of message(log.message).split("\n").entries()) {
+      lines.push(event.event || index > 0 ? `${indent}${dim("|")} ${text}` : `${time}  ${level}  ${text}`);
+    }
+  }
+  for (const exception of event.exceptions) {
+    lines.push(`${event.event ? indent : `${time}  `}${rose(`${CROSS} ${exception.name}: ${exception.message}`)}`);
+    for (const frame of (exception.stack ?? "").split("\n").slice(1)) lines.push(`${indent}${dim(frame.trimEnd())}`);
+  }
+  return lines;
+}
+
+export type RunTailOptions = {
+  url: string;
+  headers: Record<string, string>;
+  format: TailFormat;
+  signal: AbortSignal;
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+  /** First delay after a failed connection; doubles up to 8 seconds. */
+  retryMs?: number;
+  /** Give up after this many failed connections in a row. */
+  maxFailures?: number;
+  /** Reconnect if the server sends nothing (not even a keepalive) for this long. */
+  idleMs?: number;
+  fetchFn?: typeof fetch;
+};
+
+/** How a stream attempt ended, so the caller can decide to retry or stop. */
+export class TailError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+  }
+}
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+
+/**
+ * Stream until `signal` aborts. Reconnects when the server closes the stream
+ * (its time cap) or the link drops; a 4xx answer (bad filter, no auth, no such
+ * project) is final.
+ */
+export async function runTail(options: RunTailOptions): Promise<void> {
+  const out = options.stdout ?? ((text: string) => void process.stdout.write(text));
+  const err = options.stderr ?? ((text: string) => void process.stderr.write(text));
+  const fetchFn = options.fetchFn ?? fetch;
+  const idleMs = options.idleMs ?? 45_000;
+  const maxFailures = options.maxFailures ?? 5;
+  let delay = options.retryMs ?? 500;
+  let failures = 0;
+  let announced = false;
+
+  while (!options.signal.aborted) {
+    const attempt = new AbortController();
+    const stop = () => attempt.abort();
+    options.signal.addEventListener("abort", stop, { once: true });
+    let idle: ReturnType<typeof setTimeout> | undefined;
+    const arm = () => {
+      clearTimeout(idle);
+      idle = setTimeout(() => attempt.abort(), idleMs);
+    };
+    try {
+      arm();
+      const response = await fetchFn(options.url, {
+        headers: { ...options.headers, accept: "text/event-stream" },
+        signal: attempt.signal,
+      });
+      if (!response.ok || !response.body) {
+        const detail = await response.text().catch(() => "");
+        if (response.status >= 400 && response.status < 500 && response.status !== 408 && response.status !== 429)
+          throw new TailError(
+            response.status === 404
+              ? "live tail is not available here: the project was not found, or this control plane predates `tail` streaming (use `sproutboat tail --recent`)"
+              : `could not start the tail (${response.status}): ${errorText(detail)}`,
+            response.status,
+          );
+        throw new Error(`control plane answered ${response.status}`);
+      }
+      let sawFrame = false;
+      for await (const frame of readFrames(response.body)) {
+        arm();
+        sawFrame = true;
+        failures = 0;
+        delay = options.retryMs ?? 500;
+        if (frame.type === "ready") {
+          if (options.format === "pretty" && !announced) err(`${dim("tailing live, Ctrl-C to stop")}\n`);
+          announced = true;
+        } else if (frame.type === "event") {
+          if (options.format === "json") out(`${JSON.stringify(frame.event)}\n`);
+          else for (const line of formatEvent(frame.event)) out(`${line}\n`);
+        } else if (frame.type === "dropped") {
+          const what = frame.count > 0 ? `${frame.count} events` : `${frame.bytes ?? 0} bytes of output`;
+          err(`${amber(`! ${what} dropped (${frame.reason === "rate" ? "event rate limit" : "output backlog"})`)}\n`);
+        }
+        // "closed" is the server's time cap: fall out of the loop and reconnect.
+      }
+      if (!sawFrame) throw new Error("stream ended before it started");
+    } catch (error) {
+      if (options.signal.aborted) break;
+      if (error instanceof TailError) throw error;
+      failures += 1;
+      if (failures >= maxFailures)
+        throw new TailError(
+          `lost the connection ${failures} times in a row: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      if (options.format === "pretty") err(`${amber("! connection lost, retrying")}\n`);
+      await sleep(delay, options.signal);
+      delay = Math.min(delay * 2, 8000);
+    } finally {
+      clearTimeout(idle);
+      options.signal.removeEventListener("abort", stop);
+      attempt.abort();
+    }
+  }
+}
+
+function errorText(body: string): string {
+  try {
+    const error = jsonObject(parseJsonValue(body))?.error;
+    if (error !== undefined && isString(error)) return error;
+  } catch {
+    /* plain text */
+  }
+  return body.trim() || "no detail";
+}