@openparachute/hub 0.6.5-rc.8 → 0.7.1

package/src/api-tokens.ts

@@ -23,7 +23,7 @@
  *         "expires_at": "ISO-8601",
  *         "revoked_at": "ISO-8601" | null,
  *         "created_at": "ISO-8601",
- *         "created_via": "oauth_refresh" | "cli_mint" | "operator_mint",
+ *         "created_via": "oauth_refresh" | "cli_mint" | "operator_mint" | "connection_provision",
  *         "permissions": "<json-string>" | null
  *       }
  *     ],
@@ -45,8 +45,10 @@
  *   - `created_via=<value>` — narrow by mint provenance. One of
  *     `oauth_refresh` (OAuth refresh-token rotation), `operator_mint`
  *     (operator-token rotation via `parachute auth rotate-operator`),
- *     or `cli_mint` (CLI / `POST /api/auth/mint-token`). Powers the
- *     admin UI's "by source" filter pills (hub#212 Phase F).
+ *     `cli_mint` (CLI / `POST /api/auth/mint-token`), or
+ *     `connection_provision` (long-lived tokens the Connections engine
+ *     mints — see admin-connections.ts). Powers the admin UI's
+ *     "by source" filter pills (hub#212 Phase F).
  *
  * Why bearer-gated rather than session-cookie-gated: matches the rest
  * of `/api/auth/*` (mint-token, revoke-token), so an automation client
@@ -149,14 +151,15 @@ export async function handleApiTokens(req: Request, deps: ApiTokensDeps): Promis
   if (
     createdViaParam === "oauth_refresh" ||
     createdViaParam === "operator_mint" ||
-    createdViaParam === "cli_mint"
+    createdViaParam === "cli_mint" ||
+    createdViaParam === "connection_provision"
   ) {
     createdVia = createdViaParam;
   } else if (createdViaParam !== null) {
     return jsonError(
       400,
       "invalid_request",
-      "created_via must be one of: oauth_refresh | operator_mint | cli_mint",
+      "created_via must be one of: oauth_refresh | operator_mint | cli_mint | connection_provision",
     );
   }
   const cursor = url.searchParams.get("cursor");

package/src/audience-gate.ts

@@ -0,0 +1,268 @@
+/**
+ * Per-UI audience gate (H3, surface-runtime design §12 — fixes
+ * parachute-surface#88: the `public` flag existed but nothing enforced it).
+ *
+ * A module's services.json row may carry a `uis{}` map of hosted UI
+ * sub-units; each sub-unit now declares an `audience`
+ * (`public | hub-users | operator | surface`, default `hub-users`). The HUB
+ * PROXY enforces it BEFORE forwarding — surface-host serves whatever the
+ * proxy lets through, exactly like the publicExposure cloak.
+ *
+ * Scope discipline: the gate covers the SURFACE UI MOUNTS specifically (the
+ * uis sub-unit paths), not every module path — a module's own APIs keep
+ * their own auth (vault validates Bearers, scribe validates its token, …).
+ * The gate also runs before WebSocket upgrades on a gated mount (threaded
+ * into `maybeUpgradeWebSocket`).
+ *
+ * The four audiences:
+ *
+ *   public    — pass (and the chrome strip is disabled — H5: public readers
+ *               aren't hub users).
+ *   hub-users — a valid hub session cookie OR a valid hub-issued Bearer
+ *               whose scopes satisfy the sub-unit's `scopes_required`. The
+ *               OR keeps installed PWAs working: a standalone PWA holds
+ *               OAuth tokens, not a hub session. Bearer validation reuses
+ *               the hub#516 seam (signature/expiry/revocation via the JWKS,
+ *               `iss` ∈ the hub's bound-origin set — a PWA token carries the
+ *               public origin while the proxied request may resolve the
+ *               loopback issuer).
+ *   operator  — the first-admin session only. A Bearer never satisfies this
+ *               tier (operator surfaces are interactive; the session is the
+ *               operator's presence).
+ *   surface   — pass: the surface backend owns admission END-TO-END
+ *               (backed surfaces — parachute-surface runtime, surfaces with
+ *               their own server entry, kit-authenticated via
+ *               @openparachute/surface-server: hub JWTs / capability links /
+ *               anon, deny-by-default with a public conformance suite). The
+ *               hub gating these would add a SECOND auth layer that BLOCKS
+ *               the surface's own audience plane — e.g. the docs-editor's
+ *               capability-link invitees are NOT hub users by design, so a
+ *               hub-users gate would 302 them to /login before the surface's
+ *               own auth ever ran. Chrome strip follows the `public`
+ *               precedent (disabled — the visitors are mostly capability
+ *               invitees, not hub users), and WS upgrades pass through too
+ *               (the gate threads into `maybeUpgradeWebSocket`; null = no
+ *               deny = the upgrade proceeds to the capability check).
+ *
+ * Deny shape: document requests (GET + Accept: text/html, no session) get a
+ * 302 to `/login?next=<path>`; everything else gets 401/403 JSON. A
+ * signed-in-but-insufficient caller (non-admin on an operator surface, or a
+ * Bearer missing the required scopes) gets 403, not a login redirect.
+ *
+ * Exposure layers are ORTHOGONAL to the audience: the `publicExposure`
+ * cloak runs at the service-row level BEFORE this gate (dispatch skips the
+ * gate entirely on a cloaked row so the 404 stays indistinguishable from
+ * not-installed). A `surface`-audience mount on a loopback-only row is
+ * therefore still unreachable from tailnet/funnel — exactly like `public`.
+ *
+ * Fail-closed posture: malformed `audience` metadata never reaches this
+ * module — `services-manifest.ts` validation rejects the row and the lenient
+ * read drops it (the mount 404s). An absent DB (hub booted stateless) denies
+ * every audience that needs an identity store: `hub-users` and `operator`.
+ * `public` and `surface` still pass — neither consults hub identity
+ * (`surface` self-auths every request; denying it on absent DB would break
+ * the surface for zero security gain). Version skew: a surface declaring
+ * `audience: "surface"` registered against an OLDER hub (pre-dating the
+ * value) gets its row rejected by manifest validation — the mount 404s
+ * until the hub upgrades; the surface-side meta-schema ships the value
+ * separately with a hub-version requirement note.
+ */
+
+import type { Database } from "bun:sqlite";
+import { validateHostAdminToken } from "./host-admin-token-validation.ts";
+import type { ServiceEntry, UiAudience, UiSubUnit } from "./services-manifest.ts";
+import { findActiveSession } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
+
+/** A pathname resolved to the UI sub-unit that hosts it. */
+export interface UiMountMatch {
+  readonly entry: ServiceEntry;
+  readonly uiKey: string;
+  readonly ui: UiSubUnit;
+  /** The normalized mount path (no trailing slash) the match keyed on. */
+  readonly mount: string;
+  /** The effective audience (default applied). */
+  readonly audience: UiAudience;
+}
+
+/** The effective audience for a sub-unit — absent means `hub-users`. */
+export function effectiveUiAudience(ui: UiSubUnit): UiAudience {
+  return ui.audience ?? "hub-users";
+}
+
+/**
+ * Resolve which UI sub-unit (across every service's `uis{}` map) a pathname
+ * falls under. Longest-prefix match, same comparison shape as
+ * `findServiceUpstream` (trailing slashes normalized; `pathname === mount`
+ * or `pathname.startsWith(mount + "/")`). Returns undefined when the path is
+ * not under any declared UI — module API paths, undeclared mounts, and
+ * legacy flat rows are NOT gated here.
+ */
+export function resolveUiMount(
+  services: readonly ServiceEntry[],
+  pathname: string,
+): UiMountMatch | undefined {
+  let best: UiMountMatch | undefined;
+  for (const entry of services) {
+    if (!entry.uis) continue;
+    for (const [uiKey, ui] of Object.entries(entry.uis)) {
+      const norm = ui.path.replace(/\/+$/, "") || "/";
+      if (pathname === norm || pathname.startsWith(`${norm}/`)) {
+        if (!best || norm.length > best.mount.length) {
+          best = { entry, uiKey, ui, mount: norm, audience: effectiveUiAudience(ui) };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Does one bearer scope satisfy one required-scope pattern?
+ *
+ * Patterns are colon-segmented with `*` as a single-segment wildcard —
+ * `vault:*:read` matches `vault:default:read`. One asymmetry is deliberate:
+ * the broad UNNAMED form (`vault:read`) satisfies `vault:*:<verb>` — a token
+ * carrying any-vault read authority is strictly wider than one pinned vault,
+ * so refusing it would deny a caller that holds MORE than required.
+ */
+export function scopeMatchesPattern(pattern: string, scope: string): boolean {
+  const p = pattern.split(":");
+  const s = scope.split(":");
+  if (p.length === s.length) {
+    return p.every((seg, i) => seg === "*" || seg === s[i]);
+  }
+  // Broad unnamed form: vault:<verb> ⊇ vault:*:<verb>.
+  if (p.length === 3 && s.length === 2 && p[1] === "*") {
+    return p[0] === s[0] && p[2] === s[1];
+  }
+  return false;
+}
+
+/**
+ * Do the bearer's scopes satisfy the sub-unit's requirement? EVERY pattern
+ * in `scopes_required` must be matched by at least one bearer scope ("a
+ * Bearer whose scopes include the surface's scopes"). An empty/absent
+ * requirement means any valid hub-issued Bearer passes — the surface
+ * declared no scope shape, so hub identity alone is the bar.
+ */
+export function scopesSatisfyRequirement(
+  required: readonly string[] | undefined,
+  bearerScopes: readonly string[],
+): boolean {
+  if (!required || required.length === 0) return true;
+  return required.every((pattern) => bearerScopes.some((s) => scopeMatchesPattern(pattern, s)));
+}
+
+export interface AudienceGateDeps {
+  /** Hub DB — absent (stateless boot) denies every hub-gated audience
+   *  (`hub-users` / `operator`); `public` and `surface` pass without it. */
+  db: Database | undefined;
+  /**
+   * The hub's bound-origin set for Bearer `iss` validation (the hub#516
+   * seam — PWA tokens carry the public origin while the request may resolve
+   * loopback). Lazy: only consulted on the Bearer branch.
+   */
+  knownIssuers: () => readonly string[];
+}
+
+function wantsDocument(req: Request): boolean {
+  return req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html");
+}
+
+function loginRedirect(req: Request): Response {
+  const url = new URL(req.url);
+  const next = encodeURIComponent(url.pathname + url.search);
+  return new Response(null, {
+    status: 302,
+    headers: { location: `/login?next=${next}`, "cache-control": "no-store" },
+  });
+}
+
+function denyJson(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/**
+ * Enforce a sub-unit's audience for a request. Returns `null` when the
+ * request may proceed to the proxy, or the deny Response (302 login for
+ * anonymous document requests; 401/403 JSON otherwise).
+ */
+export async function gateUiAudience(
+  req: Request,
+  audience: UiAudience,
+  ui: UiSubUnit,
+  deps: AudienceGateDeps,
+): Promise<Response | null> {
+  if (audience === "public") return null;
+
+  // `surface` — pass through unconditionally (incl. on an absent DB, below):
+  // the surface backend authenticates EVERY request itself (deny-by-default
+  // kit auth: hub JWTs / capability links / anon). A hub-side deny here
+  // would block the surface's own audience plane — its capability-link
+  // invitees are not hub users by design.
+  if (audience === "surface") return null;
+
+  // Fail closed without a DB: no identity store, no way to admit anyone to
+  // a hub-gated (`hub-users` / `operator`) surface.
+  if (!deps.db) {
+    return wantsDocument(req)
+      ? loginRedirect(req)
+      : denyJson(401, "unauthenticated", "this surface requires a hub identity");
+  }
+  const db = deps.db;
+
+  const session = findActiveSession(db, req);
+
+  if (audience === "operator") {
+    if (session && isFirstAdmin(db, session.userId)) return null;
+    if (session) {
+      return denyJson(
+        403,
+        "not_admin",
+        "this surface is restricted to the hub operator — your account home is at /account/",
+      );
+    }
+    return wantsDocument(req)
+      ? loginRedirect(req)
+      : denyJson(401, "unauthenticated", "this surface requires the hub operator's session");
+  }
+
+  // audience === "hub-users"
+  if (session) return null;
+
+  const auth = req.headers.get("authorization");
+  if (auth?.startsWith("Bearer ")) {
+    const token = auth.slice("Bearer ".length).trim();
+    try {
+      const validated = await validateHostAdminToken(db, token, [...deps.knownIssuers()]);
+      const bearerScopes =
+        typeof validated.payload.scope === "string"
+          ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+          : [];
+      if (scopesSatisfyRequirement(ui.scopes_required, bearerScopes)) return null;
+      return denyJson(
+        403,
+        "insufficient_scope",
+        `this surface requires scopes: ${(ui.scopes_required ?? []).join(", ")}`,
+      );
+    } catch (err) {
+      return denyJson(
+        401,
+        "unauthenticated",
+        `bearer token invalid — ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return wantsDocument(req)
+    ? loginRedirect(req)
+    : denyJson(
+        401,
+        "unauthenticated",
+        "this surface requires a hub session or a hub-issued bearer token",
+      );
+}

package/src/chrome-strip.ts

@@ -19,6 +19,13 @@
  * application, looks distinctively Notes, reads as Parachute because the
  * tokens are continuous").
  *
+ * H5 (surface-runtime design): the opt-out generalized — when a UI
+ * sub-unit's declared `audience` resolves `public` at the proxy's audience
+ * gate (H3), the dispatch passes that mount as an extra opt-out prefix
+ * (hub-server `decorateWithChrome`). Public readers aren't hub users; the
+ * identity chrome never rides their pages. The static list below remains
+ * for hub-users surfaces that own their own chrome (Notes).
+ *
  * Why path-based and not module-declared:
  *   - Notes is a `uis[]` sub-unit of parachute-app, not its own module —
  *     adding `chrome: "off"` to parachute-app's module.json would suppress
@@ -38,7 +45,7 @@
  * defense is cheap and protects future refactors).
  */
 
-import { brandMarkSvg, WORDMARK_TEXT } from "./brand.ts";
+import { WORDMARK_TEXT, brandMarkSvg } from "./brand.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken } from "./csrf.ts";
 
 /**

package/src/commands/lifecycle.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { rethrowIfMissing } from "@openparachute/depcheck";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
@@ -609,6 +609,74 @@ export interface LogsOpts {
    * Defaults to the group-aware `defaultAlive` (hub#88).
    */
   alive?: AliveFn;
+  /**
+   * Filtered-follow source seam (hub#652) — the byte stream of lines appended
+   * to the hub log from attach onward. The production default spawns
+   * `tail -n 0 -f <hub.log>` with piped stdout so the `[<svc>] ` filter runs
+   * in-process; tests inject a deterministic stream.
+   */
+  followStream?: (path: string) => ReadableStream<Uint8Array>;
+}
+
+/** Default `followStream`: tail the file from its end, stdout piped to us. */
+function defaultFollowStream(path: string): ReadableStream<Uint8Array> {
+  try {
+    // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+    // env — see api-modules-ops.ts:defaultRun.
+    const proc = Bun.spawn(["tail", "-n", "0", "-f", path], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "inherit",
+      env: process.env,
+    });
+    return proc.stdout;
+  } catch (err) {
+    // A missing `tail` (minimal container without coreutils) surfaces the
+    // friendly install UX instead of a raw spawn throw (cli.ts top-level
+    // catch renders the MissingDependencyError).
+    rethrowIfMissing(err, "tail");
+    throw err;
+  }
+}
+
+/**
+ * Pump a byte stream line-by-line, emitting only lines that carry `prefix`
+ * (stripped). Line-buffered the same way the supervisor's `pumpLines` is, so
+ * chunk boundaries inside a line don't drop or split matches.
+ */
+async function pumpFilteredLines(
+  stream: ReadableStream<Uint8Array>,
+  prefix: string,
+  output: (line: string) => void,
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  const emit = (line: string): void => {
+    if (line.startsWith(prefix)) output(line.slice(prefix.length));
+  };
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let nl = buf.indexOf("\n");
+      while (nl !== -1) {
+        emit(buf.slice(0, nl));
+        buf = buf.slice(nl + 1);
+        nl = buf.indexOf("\n");
+      }
+    }
+    if (buf.length > 0) emit(buf);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Split a log file's content into lines, dropping the trailing newline. */
+function splitLogLines(content: string): string[] {
+  const trimmed = content.replace(/\n$/, "");
+  return trimmed === "" ? [] : trimmed.split("\n");
 }
 
 export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
@@ -620,11 +688,12 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
   const alive = opts.alive ?? defaultAlive;
 
   // logs only needs a valid short name to find the log file. First-party
-  // wins via the spec lookup; third-party rows match by `entry.name`; the
-  // internal hub is a known short outside of services.json. installDir is
-  // irrelevant here — the log file is keyed by short name and exists once
-  // the service has run, regardless of how it was registered. We just need
-  // to confirm the name maps to something the CLI manages.
+  // wins via the spec lookup; third-party rows match by `entry.name` (the
+  // same token the supervisor uses as its log prefix); the internal hub is
+  // a known short outside of services.json. installDir is irrelevant here —
+  // the log file is keyed by short name and exists once the service has
+  // run, regardless of how it was registered. We just need to confirm the
+  // name maps to something the CLI manages.
   const isFirstParty = getSpec(svc) !== undefined;
   if (!isFirstParty && svc !== HUB_SVC) {
     const entry = readManifest(manifestPath).services.find((s) => s.name === svc);
@@ -634,19 +703,111 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
     }
   }
 
-  const path = logPathFor(svc, configDir);
-  if (!existsSync(path)) {
-    // Distinguish "daemon never started" from "daemon is running but the
-    // log file is missing" (hub#335). The latter shape surfaces when a
-    // module self-registers + spawns its own logger without going through
-    // `parachute start <svc>` (no hub-managed log file), or when an
-    // operator deletes the log mid-run. Previously both shapes printed the
-    // same `parachute start ${svc}` hint, leading operators to think their
-    // running daemon hadn't started.
+  // Per-file plain reader (the pre-#652 behavior): tail/print one log file.
+  const readPlain = async (path: string): Promise<number> => {
+    if (follow) {
+      const spawner = opts.tailSpawner ?? {
+        spawn(cmd) {
+          // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+          // env — see api-modules-ops.ts:defaultRun.
+          try {
+            const proc = Bun.spawn([...cmd], {
+              stdio: ["ignore", "inherit", "inherit"],
+              env: process.env,
+            });
+            return proc.pid;
+          } catch (err) {
+            // A missing `tail` (minimal container without coreutils) surfaces
+            // the friendly install UX instead of a raw spawn throw. The CLI
+            // top-level catch in cli.ts renders the MissingDependencyError.
+            rethrowIfMissing(err, "tail");
+            throw err;
+          }
+        },
+      };
+      spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
+      // tail runs until user Ctrl-C; block this process until it exits.
+      // When called from the real CLI, process.exit wraps us; in tests a
+      // stub spawner returns immediately and we fall through.
+      return 0;
+    }
+    // Non-follow path: read last N lines synchronously for a clean one-shot.
+    const tail = splitLogLines(await Bun.file(path).text()).slice(-lines);
+    for (const line of tail) log(line);
+    return 0;
+  };
+
+  const legacyPath = logPathFor(svc, configDir);
+  const hubLogPath = logPathFor(HUB_SVC, configDir);
+  const legacyExists = svc !== HUB_SVC && existsSync(legacyPath);
+  const hubLogExists = existsSync(hubLogPath);
+
+  // Source selection (hub#652): under hub-as-supervisor (Phase 5b) a module's
+  // stdout/stderr is multiplexed into the HUB log with a `[<svc>] ` line
+  // prefix (supervisor.ts pipeOutput) — the per-service file stops advancing
+  // at the cutover. Prefer whichever file is fresher: a pre-supervised
+  // install is still actively writing the per-service file (it wins); on a
+  // supervised box the hub log is the live stream and the per-service file
+  // is a stale remnant (it loses). `logs hub` always reads the hub log
+  // unfiltered — the interleaved prefixed stream IS the hub's own log.
+  const useHubStream =
+    svc !== HUB_SVC &&
+    hubLogExists &&
+    (!legacyExists || statSync(hubLogPath).mtimeMs >= statSync(legacyPath).mtimeMs);
+
+  if (!useHubStream) {
+    if (!existsSync(legacyPath)) {
+      // Distinguish "daemon never started" from "daemon is running but the
+      // log file is missing" (hub#335). The latter shape surfaces when a
+      // module self-registers + spawns its own logger without going through
+      // the hub (no hub-managed log file), or when an operator deletes the
+      // log mid-run. Previously both shapes printed the same
+      // `parachute start ${svc}` hint, leading operators to think their
+      // running daemon hadn't started.
+      const state = processState(svc, configDir, alive);
+      if (state.status === "running") {
+        const whereabouts =
+          svc === HUB_SVC
+            ? `no log file at ${legacyPath}`
+            : `no log file at ${legacyPath} and no hub log at ${hubLogPath}`;
+        log(
+          `${svc} is running (pid ${state.pid}) but ${whereabouts}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+        );
+        return 0;
+      }
+      log(`no logs yet for ${svc}. \`parachute start ${svc}\` to begin.`);
+      return 0;
+    }
+    return readPlain(legacyPath);
+  }
+
+  // Supervised path (hub#652): the service's lines in the hub log, prefix
+  // stripped. Stripped rather than kept: every line would otherwise repeat
+  // the name the operator just typed, while the module's own output shape
+  // (e.g. surface's `[app-dcr]` sub-prefixes) stays intact — the same shape
+  // its per-service file had pre-cutover.
+  const prefix = `[${svc}] `;
+  const matched = splitLogLines(await Bun.file(hubLogPath).text())
+    .filter((l) => l.startsWith(prefix))
+    .map((l) => l.slice(prefix.length));
+
+  if (matched.length === 0 && !follow) {
+    if (legacyExists) {
+      // Transitional shape: nothing for this service in the hub log, but a
+      // (staler) per-service file exists — e.g. the module last ran detached,
+      // pre-cutover. Show it, with a note so a stale file isn't mistaken for
+      // the live stream (the exact hub#652 trap).
+      log(
+        `note: no ${svc} lines in the hub log (${hubLogPath}); showing the per-service log at ${legacyPath}.`,
+      );
+      return readPlain(legacyPath);
+    }
+    // Keep the hub#335 shapes coherent with the hub-stream source: a live
+    // pidfile here means a daemon the hub isn't logging for.
     const state = processState(svc, configDir, alive);
     if (state.status === "running") {
       log(
-        `${svc} is running (pid ${state.pid}) but no log file at ${path}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+        `${svc} is running (pid ${state.pid}) but has no lines in the hub log (${hubLogPath}) and no log file at ${legacyPath}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
       );
       return 0;
     }
@@ -654,38 +815,17 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
     return 0;
   }
 
+  for (const line of matched.slice(-lines)) log(line);
+
   if (follow) {
-    const spawner = opts.tailSpawner ?? {
-      spawn(cmd) {
-        // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
-        // env — see api-modules-ops.ts:defaultRun.
-        try {
-          const proc = Bun.spawn([...cmd], {
-            stdio: ["ignore", "inherit", "inherit"],
-            env: process.env,
-          });
-          return proc.pid;
-        } catch (err) {
-          // A missing `tail` (minimal container without coreutils) surfaces
-          // the friendly install UX instead of a raw spawn throw. The CLI
-          // top-level catch in cli.ts renders the MissingDependencyError.
-          rethrowIfMissing(err, "tail");
-          throw err;
-        }
-      },
-    };
-    spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
-    // tail runs until user Ctrl-C; block this process until it exits.
-    // When called from the real CLI, process.exit wraps us; in tests a
-    // stub spawner returns immediately and we fall through.
-    return 0;
+    // Print the filtered backlog above, then follow new hub-log lines through
+    // the same filter. Runs until the tail is killed (Ctrl-C takes down the
+    // whole foreground process group); in tests the injected stream closes.
+    if (matched.length === 0) {
+      log(`(no prior ${svc} lines — waiting for new output…)`);
+    }
+    const source = opts.followStream ?? defaultFollowStream;
+    await pumpFilteredLines(source(hubLogPath), prefix, log);
   }
-
-  // Non-follow path: read last N lines synchronously for a clean one-shot.
-  const content = await Bun.file(path).text();
-  const trimmed = content.replace(/\n$/, "");
-  const allLines = trimmed === "" ? [] : trimmed.split("\n");
-  const tail = allLines.slice(-lines);
-  for (const line of tail) log(line);
   return 0;
 }