@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/launchctl-guard.ts

@@ -0,0 +1,131 @@
+/**
+ * Test-isolation boundary guard for destructive service-manager verbs (hub#535).
+ *
+ * THE OUTAGE (2026-06-03): a hub test running on a LIVE operator machine reached
+ * the production default Runner — `Bun.spawnSync(["launchctl", "bootout", …])` —
+ * with the real hub label, and `launchctl bootout computer.parachute.hub`'d the
+ * running `computer.parachute.hub` launchd daemon, taking hub + vault + scribe
+ * down under the operator's feet. Every daemon-op helper (`removeManagedUnit`,
+ * `installManagedUnit`, `stopHubUnit`/`restartHubUnit`, `disableStaleModuleUnits`,
+ * `teardownHubUnit`) shells launchctl through an injectable `deps.run([...])`
+ * whose PRODUCTION DEFAULT is a real spawn. A test that forgets to inject a fake
+ * `run` (or whose fake gets removed in a refactor) silently falls back to that
+ * real spawn → it drives the operator's actual service manager.
+ *
+ * THE GUARD: when running under a test runner (`NODE_ENV === "test"`, which Bun
+ * sets automatically for `bun test`), the production default Runner REFUSES the
+ * destructive launchd verbs — `bootout`, `bootstrap`, `load`, `kickstart` (and
+ * their systemd analogues `enable`/`disable`/`start`/`stop`/`restart` against a
+ * real systemctl) — and THROWS loudly instead of spawning. A test is thereby
+ * FORCED to inject a fake `run`; it can never reach the operator's live daemon by
+ * omission. Read-only verbs (`launchctl print`, `systemctl is-active`/
+ * `is-enabled`, `journalctl`, `loginctl`, `which`-style probes) are left alone —
+ * they're harmless and some tests intentionally exercise the default deps for
+ * them.
+ *
+ * PRODUCTION BEHAVIOR IS IDENTICAL: outside a test runner (`NODE_ENV !== "test"`)
+ * the guard is a no-op and the spawn proceeds exactly as before. There is also an
+ * explicit escape hatch — `PARACHUTE_ALLOW_REAL_LAUNCHCTL=1` — for the rare
+ * deliberate integration test that genuinely wants to drive a real (sandboxed)
+ * manager; it must opt IN, loudly, rather than reaching the daemon by accident.
+ *
+ * This is layer (a) of the hub#535 fix (the durable boundary guard). Layer (b) is
+ * the targeted fake-injection in the offending tests; layer (c) is the regression
+ * test that asserts the default deps throw here rather than spawn.
+ */
+
+/** Destructive launchd subcommands that mutate / tear down a loaded unit. */
+const DESTRUCTIVE_LAUNCHCTL_VERBS = new Set([
+  "bootout",
+  "bootstrap",
+  "load",
+  "unload",
+  "kickstart",
+]);
+
+/**
+ * Destructive systemd subcommands that mutate a unit's run/enable state. `enable`
+ * / `disable` may carry `--now` (which also starts/stops); `start`/`stop`/
+ * `restart` mutate run-state directly. Read-only `is-active` / `is-enabled` /
+ * `show` / `status` / `cat` are NOT here — tests use the default deps for those.
+ */
+const DESTRUCTIVE_SYSTEMCTL_VERBS = new Set([
+  "start",
+  "stop",
+  "restart",
+  "reload",
+  "enable",
+  "disable",
+  "daemon-reload",
+  "mask",
+  "unmask",
+]);
+
+/** True when we're executing under a test runner. Bun sets NODE_ENV=test for `bun test`. */
+function underTestRunner(): boolean {
+  return process.env.NODE_ENV === "test";
+}
+
+/** True when an operator has explicitly opted in to real service-manager calls under test. */
+function realCallsExplicitlyAllowed(): boolean {
+  const v = process.env.PARACHUTE_ALLOW_REAL_LAUNCHCTL;
+  return v === "1" || v === "true";
+}
+
+/**
+ * Find the first meaningful subcommand token after the tool name, skipping
+ * scope/option flags (`--user`, `-k`, `--now`, etc.) so we classify the VERB,
+ * not a flag. Returns undefined when there's nothing past the flags.
+ */
+function firstSubcommand(rest: readonly string[]): string | undefined {
+  for (const tok of rest) {
+    if (tok.startsWith("-")) continue;
+    return tok;
+  }
+  return undefined;
+}
+
+/**
+ * Decide whether a command (as the argv the default Runner is about to spawn) is
+ * a DESTRUCTIVE service-manager mutation that must be blocked under a test runner.
+ *
+ *   - `launchctl <verb> …` where verb ∈ {bootout, bootstrap, load, unload, kickstart}
+ *   - `systemctl [--user] <verb> …` where verb ∈ {start, stop, restart, reload,
+ *     enable, disable, daemon-reload, mask, unmask}
+ *
+ * The tool name is matched on the basename so an absolute path (`/bin/launchctl`)
+ * is classified too — though in this codebase every invocation is bare (the PATH
+ * shim's safety relies on that), this keeps the guard correct regardless.
+ */
+export function isDestructiveServiceManagerCommand(cmd: readonly string[]): boolean {
+  if (cmd.length === 0) return false;
+  const tool = (cmd[0] ?? "").split("/").pop() ?? "";
+  const rest = cmd.slice(1);
+  const verb = firstSubcommand(rest);
+  if (verb === undefined) return false;
+  if (tool === "launchctl") return DESTRUCTIVE_LAUNCHCTL_VERBS.has(verb);
+  if (tool === "systemctl") return DESTRUCTIVE_SYSTEMCTL_VERBS.has(verb);
+  return false;
+}
+
+/**
+ * The boundary guard the production default Runner calls before spawning. When
+ * running under a test runner and NOT explicitly opted in, a destructive
+ * service-manager command THROWS — forcing the test to inject a fake `run`
+ * instead of driving the operator's live daemon. A no-op everywhere else
+ * (production, or a non-destructive/read-only command, or explicit opt-in).
+ *
+ * The thrown error names the exact command and tells the author how to fix it,
+ * so a regressed test fails with an actionable message rather than a silent
+ * daemon teardown.
+ */
+export function guardServiceManagerCommand(cmd: readonly string[]): void {
+  if (!underTestRunner()) return; // production — spawn proceeds unchanged.
+  if (realCallsExplicitlyAllowed()) return; // deliberate integration test opted in.
+  if (!isDestructiveServiceManagerCommand(cmd)) return; // read-only / unrelated — fine.
+  throw new Error(
+    `[launchctl-guard] Refusing to run a destructive service-manager command under a test runner: \`${cmd.join(
+      " ",
+    )}\`. The default (production) Runner shells out to the REAL launchctl/systemctl — on a live machine this would tear down the operator's running daemon (this is the hub#535 outage class). Inject a fake \`run\` into this code path's deps so the test never touches the real service manager. (If you GENUINELY need a real, sandboxed manager call in this test, set PARACHUTE_ALLOW_REAL_LAUNCHCTL=1 to opt in.)`,
+  );
+}

package/src/managed-unit.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { guardServiceManagerCommand } from "./launchctl-guard.ts";
 
 /**
  * Platform-agnostic "managed unit" machinery — the reusable launchd/systemd
@@ -86,6 +87,12 @@ export const defaultManagedUnitDeps: ManagedUnitDeps = {
   userName: () => process.env.USER ?? process.env.LOGNAME ?? process.env.USERNAME ?? "",
   which: (binary) => Bun.which(binary),
   run: (cmd) => {
+    // hub#535 boundary guard: under a test runner, REFUSE destructive
+    // launchctl/systemctl verbs (bootout/bootstrap/load/kickstart, etc.) instead
+    // of spawning the REAL service manager — a test that forgot to inject a fake
+    // `run` must not be able to tear down the operator's live daemon by omission.
+    // No-op in production (NODE_ENV !== "test"); see src/launchctl-guard.ts.
+    guardServiceManagerCommand(cmd);
     const proc = Bun.spawnSync([...cmd], { env: process.env });
     return {
       code: proc.exitCode ?? 1,
@@ -659,9 +666,12 @@ export interface BuildHubManagedUnitOpts {
  * the bind host to `0.0.0.0` (serve.ts), which is correct for the container
  * shape (the platform's HTTP forwarder must reach the hub) but WRONG for a
  * self-hosted box — bare `serve` would expose the admin/OAuth surfaces on every
- * interface, contradicting the pre-supervisor detached behavior and the trust
- * model `layerOf` (hub-server.ts) assumes (header-absent ⇒ "loopback"). The
- * container path never calls this builder (the Dockerfile pins
+ * interface, contradicting the pre-supervisor detached behavior. Forcing a
+ * loopback bind also keeps `layerOf` (hub-server.ts) precise: post-#526 it
+ * derives trust from the peer address (`server.requestIP`), failing closed to
+ * "public" for any non-loopback peer — so a 127.0.0.1-only listener is what
+ * lets a header-absent on-box CLI caller classify as "loopback". The container
+ * path never calls this builder (the Dockerfile pins
  * `ENV PARACHUTE_BIND_HOST=0.0.0.0` + runs `serve` directly), so it stays
  * 0.0.0.0. The canonical expose path is unaffected: cloudflared/tailscale dial
  * `127.0.0.1:<port>` from the same host, and the hub's own proxy targets

package/src/migrate-offer.ts

@@ -22,11 +22,15 @@
  */
 
 import { existsSync } from "node:fs";
-import {
-  type CutoverOpts,
-  type CutoverResult,
-  cutoverToSupervised,
-} from "./commands/migrate-cutover.ts";
+// `migrate-cutover.ts` is imported as a TYPE only (erased at compile time, no
+// module evaluation) and loaded LAZILY at the call site below. This breaks the
+// transitive eager-load chain `cli.ts` → `lifecycle.ts` → `migrate-offer.ts` →
+// `migrate-cutover.ts`: a broken `migrate-cutover` (e.g. the 0.6.2 eval-time
+// ReferenceError) must not crash the start/stop/restart/logs lifecycle commands
+// that pull in this module purely for the §7.5 detect-and-offer machinery. The
+// cutover is only ever evaluated when an operator interactively accepts the
+// offer, so deferring its import to that moment keeps the whole chain robust.
+import type { CutoverOpts, CutoverResult } from "./commands/migrate-cutover.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
 import { HUB_SVC } from "./hub-control.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "./hub-unit.ts";
@@ -149,7 +153,6 @@ export async function offerMigrateToSupervised(
   const unitInstalledFn = opts.isHubUnitInstalled ?? isHubUnitInstalled;
   const hubUnitDeps = opts.hubUnitDeps ?? defaultHubUnitDeps;
   const hasPriorDetached = opts.hasPriorDetached ?? hasPriorDetachedInstall;
-  const cutover = opts.cutover ?? cutoverToSupervised;
   const prompt = opts.prompt ?? defaultOfferPrompt;
   const isTty = opts.isTty ?? Boolean(process.stdin.isTTY);
 
@@ -179,6 +182,12 @@ export async function offerMigrateToSupervised(
     return { outcome: "declined" };
   }
 
+  // Resolve the cutover lazily: only import `migrate-cutover.ts` now that the
+  // operator has accepted, so the offer's mere availability never drags the
+  // cutover module into the lifecycle-command load graph (see the `import type`
+  // note at the top). Tests inject `opts.cutover` and never hit the import.
+  const cutover =
+    opts.cutover ?? (await import("./commands/migrate-cutover.ts")).cutoverToSupervised;
   const result = await cutover({ configDir, manifestPath, log });
   for (const line of result.messages) log(line);
   const ok = result.outcome === "migrated" || result.outcome === "already-migrated";

package/src/module-ops-client.ts

@@ -183,7 +183,7 @@ export async function driveModuleOp(
   const body = await parseJsonSafe(res);
 
   if (res.status < 200 || res.status >= 300) {
-    const { error, error_description } = asErrorBody(body);
+    const { error, error_description } = asErrorBody(body, res.status);
     throw new ModuleOpHttpError(res.status, error, error_description);
   }
 
@@ -231,7 +231,7 @@ async function pollOperation(
     });
     const body = await parseJsonSafe(res);
     if (res.status < 200 || res.status >= 300) {
-      const { error, error_description } = asErrorBody(body);
+      const { error, error_description } = asErrorBody(body, res.status);
       throw new ModuleOpHttpError(res.status, error, error_description);
     }
     const status = extractOpStatus(body);
@@ -288,7 +288,7 @@ export async function fetchModuleLogs(
   });
   const body = await parseJsonSafe(res);
   if (res.status < 200 || res.status >= 300) {
-    const { error, error_description } = asErrorBody(body);
+    const { error, error_description } = asErrorBody(body, res.status);
     throw new ModuleOpHttpError(res.status, error, error_description);
   }
   const b = (body ?? {}) as { lines?: unknown; text?: unknown };
@@ -330,6 +330,14 @@ export interface ModuleStatesResult {
   readonly supervisorAvailable: boolean;
   /** Per-module supervisor snapshots, keyed by short name in array order. */
   readonly modules: ModuleStateSnapshot[];
+  /**
+   * Run-state for ALL supervised modules — including non-curated ones the
+   * `modules` catalog omits (e.g. the `surface` UI host). `status` falls back
+   * to this so a running-but-non-curated module reads `active`, not `inactive`
+   * (hub#539). The live `fetchModuleStates` always populates it (`[]` against an
+   * older hub that predates the field); optional so test stubs may omit it.
+   */
+  readonly supervised?: ModuleStateSnapshot[];
 }
 
 /**
@@ -388,25 +396,37 @@ export async function fetchModuleStates(deps: DriveModuleOpDeps): Promise<Module
   }
   const body = await parseJsonSafe(res);
   if (res.status < 200 || res.status >= 300) {
-    const { error, error_description } = asErrorBody(body);
+    const { error, error_description } = asErrorBody(body, res.status);
     throw new ModuleOpHttpError(res.status, error, error_description);
   }
-  const b = (body ?? {}) as { modules?: unknown; supervisor_available?: unknown };
+  const b = (body ?? {}) as {
+    modules?: unknown;
+    supervised?: unknown;
+    supervisor_available?: unknown;
+  };
   const supervisorAvailable = b.supervisor_available === true;
-  const modules: ModuleStateSnapshot[] = Array.isArray(b.modules)
-    ? b.modules
-        .filter((m): m is Record<string, unknown> => !!m && typeof m === "object")
-        .map((m) => ({
-          short: typeof m.short === "string" ? m.short : "",
-          installed: m.installed === true,
-          installed_version: typeof m.installed_version === "string" ? m.installed_version : null,
-          supervisor_status: typeof m.supervisor_status === "string" ? m.supervisor_status : null,
-          pid: typeof m.pid === "number" ? m.pid : null,
-          supervisor_start_error:
-            m.supervisor_start_error !== undefined ? (m.supervisor_start_error ?? null) : null,
-        }))
-    : [];
-  return { supervisorAvailable, modules };
+  const modules = parseSnapshots(b.modules);
+  // `supervised` (hub#539) carries run-state for ALL supervised modules,
+  // including non-curated ones absent from `modules` (e.g. the surface host).
+  // Older hubs without the field yield []; consumers tolerate that.
+  const supervised = parseSnapshots(b.supervised);
+  return { supervisorAvailable, modules, supervised };
+}
+
+/** Parse a `modules`/`supervised` array into validated snapshots (hub#539). */
+function parseSnapshots(raw: unknown): ModuleStateSnapshot[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((m): m is Record<string, unknown> => !!m && typeof m === "object")
+    .map((m) => ({
+      short: typeof m.short === "string" ? m.short : "",
+      installed: m.installed === true,
+      installed_version: typeof m.installed_version === "string" ? m.installed_version : null,
+      supervisor_status: typeof m.supervisor_status === "string" ? m.supervisor_status : null,
+      pid: typeof m.pid === "number" ? m.pid : null,
+      supervisor_start_error:
+        m.supervisor_start_error !== undefined ? (m.supervisor_start_error ?? null) : null,
+    }));
 }
 
 async function parseJsonSafe(res: Response): Promise<unknown> {
@@ -417,15 +437,20 @@ async function parseJsonSafe(res: Response): Promise<unknown> {
   }
 }
 
-function asErrorBody(body: unknown): { error: string; error_description: string } {
+function asErrorBody(body: unknown, status: number): { error: string; error_description: string } {
+  // A bare/unparseable error response used to collapse to "request failed",
+  // which gave the operator nothing to act on (hub#536 — a spawn-throw
+  // escaping a handler produced exactly this). Carry the HTTP status so even
+  // the worst case names the failure class.
+  const fallback = `hub returned HTTP ${status} with no error detail`;
   if (body && typeof body === "object") {
     const b = body as Record<string, unknown>;
     const error = typeof b.error === "string" ? b.error : "error";
     const error_description =
-      typeof b.error_description === "string" ? b.error_description : "request failed";
+      typeof b.error_description === "string" ? b.error_description : fallback;
     return { error, error_description };
   }
-  return { error: "error", error_description: "request failed" };
+  return { error: "error", error_description: fallback };
 }
 
 function extractOperationId(body: unknown): string | undefined {

package/src/scope-attenuation.ts

@@ -83,3 +83,22 @@ export function hasMintingAuthority(bearerScopes: string[]): boolean {
     bearerScopes.some((s) => isVaultAdminScope(s))
   );
 }
+
+/**
+ * Is this an *operator* bearer — i.e. does it hold host-level minting authority
+ * (`parachute:host:auth` or `parachute:host:admin`)?
+ *
+ * The distinction matters for the `subject` override on the mint endpoint: an
+ * operator bearer is the on-box host administrator (or a service account it
+ * delegated to), so it may legitimately mint a token whose `sub` names a
+ * service account other than its own — the documented service-account override.
+ * A merely vault-scoped bearer (`vault:<N>:admin` only) has NO host authority,
+ * so letting it set an arbitrary `sub` is audit-attribution forgery: it could
+ * mint a token that the registry + revocation list attribute to a foreign
+ * subject. Non-operator bearers are therefore pinned to their own `sub`.
+ */
+export function isOperatorBearer(bearerScopes: string[]): boolean {
+  return (
+    bearerScopes.includes(MINT_HOST_AUTH_SCOPE) || bearerScopes.includes(MINT_HOST_ADMIN_SCOPE)
+  );
+}

package/src/scope-explanations.ts

@@ -270,7 +270,15 @@ export function isNonRequestableScope(scope: string): boolean {
   // consent path and through `canGrant` rule 1, capped to the consenting
   // user's held authority at the `issueAuthCodeRedirect` choke-point. Only
   // the host-level operator scopes stay non-requestable here.
-  return NON_REQUESTABLE_SCOPES.has(scope);
+  //
+  // Item C — case-insensitive guard. The membership check is exact-string,
+  // but Parachute scope tokens are canonically lowercase. A casing variant
+  // like `PARACHUTE:HOST:AUTH` would slip past a raw `Set.has` and be treated
+  // as requestable — minting a junk-but-harmless token today (consumers are
+  // case-sensitive + anchored, so it grants nothing), but a backstop against
+  // a future consumer that case-folds. Normalize to lowercase before the
+  // membership check so every casing of a host-level scope is refused.
+  return NON_REQUESTABLE_SCOPES.has(scope.toLowerCase());
 }
 
 /** True when the scope can appear in a public `/oauth/authorize` request. */

package/src/service-spec.ts

@@ -39,9 +39,14 @@ import type { ServiceEntry } from "./services-manifest.ts";
  *
  * Operator override is now "edit services.json" (or `parachute config`
  * once that lands), not "edit `.env`". Pre-#206 stale `.env` PORT lines on
- * existing operator machines stay where they are — harmless, since the
- * boot-time ladder reads services.json before falling through to the bare
- * PORT env tier — and future installs no longer touch them.
+ * existing operator machines stay where they are — harmless to the module's
+ * own resolvePort ladder, which reads services.json before falling through to
+ * the bare PORT env tier — and future installs no longer touch them. (Caveat,
+ * hub#537: the supervisor's spawn-env builder used to echo a stale `.env` PORT
+ * into the injected `PORT`, and its readiness probe trusted that — so a `.env`
+ * PORT disagreeing with services.json yielded a false `started_but_unbound`.
+ * Fixed by making `entry.port` authoritative: `buildModuleSpawnRequest` drops a
+ * `.env` PORT.)
  *
  * **No speculative reservations.** Future first-party modules claim a slot
  * the moment they ship, not before — pre-reservation for unbuilt things has
@@ -177,7 +182,15 @@ const NOTES_SERVE_PATH = fileURLToPath(new URL("./notes-serve.ts", import.meta.u
  * telegraphs the state: the row is a stopgap, and the service's first boot
  * will overwrite with its own authoritative write.
  */
-const SEED_VERSION = "0.0.0-linked";
+/**
+ * Version string stamped on a CLI-seeded services.json entry — the
+ * "module installed, but its own daemon hasn't booted and registered a real
+ * row yet" placeholder. A real service boot overwrites this with the package's
+ * actual version (see "Services own their write side of services.json" in
+ * CLAUDE.md). Exported so consumers (e.g. well-known generation, hub#577) can
+ * tell a placeholder entry apart from a live one.
+ */
+export const SEED_VERSION = "0.0.0-linked";
 
 function pathBasedUrl(entry: ServiceEntry): string {
   const first = entry.paths[0] ?? "";

package/src/setup-wizard.ts

@@ -399,6 +399,18 @@ export interface SetupWizardDeps {
     userId: string,
     opts: MintOperatorTokenOpts & { dir?: string },
   ) => Promise<IssueOperatorTokenResult>;
+  /**
+   * Whether the in-flight request arrived over loopback (peer `127.0.0.1` /
+   * `::1`). Set by `hub-server.ts` from `layerOf(req, peerAddr)`. hub#576: a
+   * loopback caller already proves on-box access (it's the operator's own
+   * shell — `parachute init` driving the CLI wizard), so the GET `/admin/setup`
+   * JSON probe reveals the actual bootstrap token VALUE to it, not just the
+   * `requireBootstrapToken` boolean. Public / tailnet callers (any browser
+   * that found the FQDN) get only the boolean and must paste the token the
+   * operator copied from their terminal. Absent (undefined) is treated as
+   * NON-loopback — fail closed, never leak the token to a header-less caller.
+   */
+  requestIsLoopback?: boolean;
 }
 
 /**
@@ -1601,8 +1613,17 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
   // the HTML rendering branches means the CLI gets the answer it needs
   // without the wizard having to render a 30KB HTML page per poll.
   if (wantsJson) {
-    const requireToken = getBootstrapToken() !== undefined;
-    const envelope = {
+    const activeToken = getBootstrapToken();
+    const requireToken = activeToken !== undefined;
+    const envelope: {
+      step: typeof state.step;
+      hasAdmin: boolean;
+      hasVault: boolean;
+      hasExposeMode: boolean;
+      requireBootstrapToken: boolean;
+      csrfToken: string;
+      bootstrapToken?: string;
+    } = {
       step: state.step,
       hasAdmin: state.hasAdmin,
       hasVault: state.hasVault,
@@ -1610,6 +1631,17 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
       requireBootstrapToken: requireToken,
       csrfToken: csrf.token,
     };
+    // hub#576: hand the actual token to a LOOPBACK caller only. The on-box
+    // operator (`parachute init` → CLI wizard, or a curl from their own shell)
+    // already proves box access by reaching loopback — same trust level as
+    // reading the token off the startup banner in the hub log. This lets init
+    // surface the token in the operator's terminal and feed it to the CLI
+    // wizard transparently, instead of making them dig through `parachute logs
+    // hub`. A public / tailnet browser never gets the value — it stays gated on
+    // the operator pasting what they copied from their terminal.
+    if (requireToken && deps.requestIsLoopback === true && activeToken !== undefined) {
+      envelope.bootstrapToken = activeToken;
+    }
     const jsonHeaders: Record<string, string> = {
       "content-type": "application/json; charset=utf-8",
       "cache-control": "no-store",

package/src/spawn-path.ts

@@ -0,0 +1,148 @@
+/**
+ * PATH enrichment for spawned modules + the hub's own boot env.
+ *
+ * The hub-as-supervisor unit bakes a hardcoded base PATH (see
+ * `enrichedUnitPath` below), and `Bun.spawn` defaults to an empty env, so
+ * supervised children only ever see the PATH the unit handed the hub. On a
+ * launchd-managed Mac that PATH omits the two dirs operator tools actually live
+ * in — `$HOME/.local/bin` (scribe's `parakeet-mlx`) and the Homebrew bin
+ * (`ffmpeg`, `/opt/homebrew/bin` on Apple Silicon). The result: scribe's
+ * `Bun.which("ffmpeg")` / `Bun.which("parakeet-mlx")` probes come up empty and
+ * transcription is dead on canonical installs.
+ *
+ * `enrichedPath` is the shared fix. It takes a base env (defaults to
+ * `process.env`), keeps whatever PATH was inherited, and APPENDS the operator-
+ * tool dirs that exist on disk and aren't already present. Inherited PATH wins
+ * (append, not prepend) so an operator's explicit PATH ordering is never
+ * reordered out from under them. `PARACHUTE_EXTRA_PATH` (colon-joined) is
+ * PREPENDED so an operator can intentionally shadow a system binary.
+ *
+ * Two consumers:
+ *   1. The spawn side (`buildModuleSpawnRequest` in `commands/serve-boot.ts` +
+ *      `spawnSupervised` in `api-modules-ops.ts`) injects `enrichedPath()` into
+ *      every supervised child's env. This is the PRIMARY fix — it self-heals
+ *      every existing install at the next hub restart, no re-init needed.
+ *   2. The hub's own `serve` startup enriches `process.env.PATH` so the hub's
+ *      own `Bun.which` probes (cloudflared / tailscale detection, etc.) also
+ *      see brew + `.local`.
+ *
+ * The unit generator (`enrichedUnitPath`, used by `hub-unit.ts` +
+ * `commands/migrate-cutover.ts`) bakes the same dirs into the launchd/systemd
+ * unit PATH as belt-and-suspenders for fresh installs.
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+
+/** Injectable seams so tests don't touch the real fs / os / platform. */
+export interface EnrichedPathDeps {
+  /** Operator home dir. */
+  homeDir: () => string;
+  /** True when `path` exists on disk. */
+  exists: (path: string) => boolean;
+  /** `process.platform` value (e.g. "darwin", "linux"). */
+  platform: NodeJS.Platform;
+  /** `process.arch` value (e.g. "arm64", "x64"). */
+  arch: string;
+}
+
+export const defaultEnrichedPathDeps: EnrichedPathDeps = {
+  homeDir: () => homedir(),
+  exists: (path) => existsSync(path),
+  platform: process.platform,
+  arch: process.arch,
+};
+
+/**
+ * The Homebrew bin dir for the current platform/arch, or null when there
+ * isn't a canonical one (non-darwin — Linux brew is opt-in + non-canonical, so
+ * we only contribute `$HOME/.local/bin` there).
+ *
+ * Apple Silicon brew installs under `/opt/homebrew`; Intel macOS brew under
+ * `/usr/local`.
+ */
+function brewBinDir(platform: NodeJS.Platform, arch: string): string | null {
+  if (platform !== "darwin") return null;
+  return arch === "arm64" ? "/opt/homebrew/bin" : "/usr/local/bin";
+}
+
+/**
+ * Operator-tool dirs to APPEND (in this order): `$HOME/.local/bin` (pipx /
+ * `pip install --user` — scribe's `parakeet-mlx`), the platform brew bin
+ * (`ffmpeg`), and `$HOME/.bun/bin` (bun-linked binaries on a cold boot). Order
+ * is deterministic and stable. Pure of fs — the runtime enrichment filters by
+ * existence, the unit generator includes them unconditionally.
+ */
+export function operatorToolDirs(home: string, platform: NodeJS.Platform, arch: string): string[] {
+  const dirs = [`${home}/.local/bin`];
+  const brew = brewBinDir(platform, arch);
+  if (brew) dirs.push(brew);
+  dirs.push(`${home}/.bun/bin`);
+  return dirs;
+}
+
+function candidateDirs(deps: EnrichedPathDeps): string[] {
+  return operatorToolDirs(deps.homeDir(), deps.platform, deps.arch);
+}
+
+function dedupe(entries: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of entries) {
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * The PATH baked into the launchd/systemd hub unit at generation time.
+ *
+ * `${bunInstall}/bin` first (so supervised children resolve a bun-linked binary
+ * on cold boot, R20), then the usual system dirs, then the operator-tool dirs
+ * (`$HOME/.local/bin`, the platform brew bin) so a managed hub — and the modules
+ * it spawns — can find scribe's `parakeet-mlx` + `ffmpeg`. `PARACHUTE_EXTRA_PATH`
+ * (if set at generation time) is PREPENDED for intentional operator shadowing.
+ * Deduped end-to-end.
+ *
+ * Unlike `enrichedPath`, the unit-side dirs are included UNCONDITIONALLY (no
+ * existence check): the unit is generated once at install/migrate time but
+ * brew/tools may be installed afterward, and a non-existent PATH entry is simply
+ * skipped by the OS — so baking them in is the robust choice for fresh installs.
+ *
+ * Shared by `hub-unit.ts` (init bringup) + `commands/migrate-cutover.ts`
+ * (`--to-supervised` cutover) so the two unit-generation paths can't drift.
+ */
+export function enrichedUnitPath(
+  bunInstall: string,
+  home: string,
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+  extraPath: string | undefined = process.env.PARACHUTE_EXTRA_PATH,
+): string {
+  const extra = (extraPath ?? "").split(":").filter((e) => e.length > 0);
+  const base = [`${bunInstall}/bin`, "/usr/local/bin", "/usr/bin", "/bin"];
+  return dedupe([...extra, ...base, ...operatorToolDirs(home, platform, arch)]).join(":");
+}
+
+/**
+ * Build a PATH that enriches `env.PATH` with operator-tool dirs.
+ *
+ * Ordering: `PARACHUTE_EXTRA_PATH` (prepended) : inherited PATH : appended
+ * operator-tool dirs that exist and aren't already present. Deduped end-to-end
+ * (first occurrence wins, so an inherited entry is never reordered).
+ */
+export function enrichedPath(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: EnrichedPathDeps = defaultEnrichedPathDeps,
+): string {
+  const inherited = (env.PATH ?? "").split(":").filter((e) => e.length > 0);
+  const extra = (env.PARACHUTE_EXTRA_PATH ?? "").split(":").filter((e) => e.length > 0);
+  const appended = candidateDirs(deps).filter((d) => deps.exists(d));
+
+  // PARACHUTE_EXTRA_PATH first (intentional operator shadow), then the
+  // inherited PATH (inherited wins over our appended defaults), then our
+  // appended operator-tool dirs.
+  return dedupe([...extra, ...inherited, ...appended]).join(":");
+}