@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/hub-unit.ts

@@ -53,6 +53,7 @@ import {
   systemdUnitPathForName,
 } from "./managed-unit.ts";
 import { type PortListeningFn, defaultPortListening } from "./port-probe.ts";
+import { enrichedUnitPath } from "./spawn-path.ts";
 
 /** Default canonical hub port (the 1939 pin). */
 export const HUB_UNIT_DEFAULT_PORT = 1939;
@@ -623,14 +624,8 @@ export function hubUnitMessages(): ManagedUnitMessages {
   };
 }
 
-/**
- * Sane default PATH for the hub unit when the caller doesn't supply one: bun's
- * global bin first (so supervised children resolve a bun-linked binary on cold
- * boot, R20), then the usual system dirs.
- */
-function defaultUnitPath(bunInstall: string): string {
-  return `${bunInstall}/bin:/usr/local/bin:/usr/bin:/bin`;
-}
+// The hub-unit PATH is built by `enrichedUnitPath` (src/spawn-path.ts) so this
+// init-bringup path and the `migrate --to-supervised` cutover path can't drift.
 
 /**
  * Build + install + start the hub unit, then wait for hub readiness (design
@@ -652,7 +647,7 @@ export async function installAndStartHubUnit(
   const deps = opts.deps ?? defaultHubUnitDeps;
   const port = opts.port ?? HUB_UNIT_DEFAULT_PORT;
   const bunInstall = opts.bunInstall ?? `${deps.homeDir()}/.bun`;
-  const path = opts.path ?? defaultUnitPath(bunInstall);
+  const path = opts.path ?? enrichedUnitPath(bunInstall, deps.homeDir(), deps.platform);
   const logPath = opts.logPath ?? `${opts.parachuteHome}/hub/logs/hub.log`;
   const log = opts.log ?? (() => {});
 

package/src/invites.ts

@@ -0,0 +1,291 @@
+/**
+ * One-time, expiring invite links (design
+ * 2026-06-04-individual-users-and-vault-operations.md §7). An admin issues
+ * a link; the recipient opens `/account/setup/<token>`, picks a username +
+ * password, and gets their OWN freshly-provisioned vault as owner.
+ *
+ * Token model — mirrors `auth-codes.ts` (single-use + expiring + sha256-at-
+ * rest), with the key difference that invites are LONGER-LIVED (default 7
+ * days vs the 60s auth-code TTL), so the row stores **sha256(token)**, never
+ * the raw value. The raw token is returned exactly ONCE from `issueInvite`
+ * and never persisted — a DB read alone can't replay the link (the same
+ * posture as the bootstrap token). Lookup hashes the URL token and selects
+ * by the hash.
+ *
+ * What an invite pre-authorizes: creating exactly ONE account + the one
+ * named/created vault at the baked-in role — NEVER host:admin, NEVER another
+ * vault. The redeemed user inherits only the `user_vaults` row's authority.
+ * The redemption flow (`/account/setup/<token>` in hub-server.ts) enforces
+ * the createUser-then-stamp ordering so a createUser failure leaves the
+ * invite re-usable.
+ *
+ * Single-use is enforced by stamping `used_at` on redemption — a replay
+ * attempt sees the row with `used_at` set and `redeemInvite` throws
+ * `InviteUsedError`. Revocation is a separate `revoked_at` stamp the admin
+ * sets before redemption. Expiry is enforced at redeem-time.
+ */
+import type { Database } from "bun:sqlite";
+import { createHash, randomBytes } from "node:crypto";
+
+/** Default invite lifetime — long enough to deliver out-of-band (no email), short enough to bound a leaked link. */
+export const DEFAULT_INVITE_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+/** Token entropy in bytes — 256 bits, matching the bootstrap / auth-code token. */
+const INVITE_TOKEN_BYTES = 32;
+
+export type InviteStatus = "pending" | "redeemed" | "expired" | "revoked";
+
+export interface Invite {
+  /** sha256(raw token), hex. The raw token is never stored. */
+  tokenHash: string;
+  createdBy: string | null;
+  /** Pinned vault name, or null when the redeemer names their own vault. */
+  vaultName: string | null;
+  /** `user_vaults.role` granted on redemption (`'write'` = owner). */
+  role: string;
+  /** Whether redemption provisions a NEW vault for the redeemer. */
+  provisionVault: boolean;
+  /** `'internal' | 'off'` mirror knob for the provisioned vault, or null. */
+  defaultMirror: string | null;
+  expiresAt: string;
+  usedAt: string | null;
+  redeemedUserId: string | null;
+  revokedAt: string | null;
+  createdAt: string;
+}
+
+export class InviteNotFoundError extends Error {
+  constructor() {
+    super("invite not found");
+    this.name = "InviteNotFoundError";
+  }
+}
+
+export class InviteExpiredError extends Error {
+  constructor() {
+    super("invite has expired");
+    this.name = "InviteExpiredError";
+  }
+}
+
+export class InviteUsedError extends Error {
+  constructor() {
+    super("invite has already been redeemed");
+    this.name = "InviteUsedError";
+  }
+}
+
+export class InviteRevokedError extends Error {
+  constructor() {
+    super("invite has been revoked");
+    this.name = "InviteRevokedError";
+  }
+}
+
+interface Row {
+  token: string;
+  created_by: string | null;
+  vault_name: string | null;
+  role: string;
+  provision_vault: number;
+  default_mirror: string | null;
+  expires_at: string;
+  used_at: string | null;
+  redeemed_user_id: string | null;
+  revoked_at: string | null;
+  created_at: string;
+}
+
+function rowToInvite(r: Row): Invite {
+  return {
+    tokenHash: r.token,
+    createdBy: r.created_by,
+    vaultName: r.vault_name,
+    role: r.role,
+    provisionVault: r.provision_vault === 1,
+    defaultMirror: r.default_mirror,
+    expiresAt: r.expires_at,
+    usedAt: r.used_at,
+    redeemedUserId: r.redeemed_user_id,
+    revokedAt: r.revoked_at,
+    createdAt: r.created_at,
+  };
+}
+
+/** sha256 of the raw token, hex — the at-rest representation + PK. */
+export function hashInviteToken(rawToken: string): string {
+  return createHash("sha256").update(rawToken).digest("hex");
+}
+
+/** Derive an invite's status from its stamps + the current time. */
+export function inviteStatus(invite: Invite, now: Date = new Date()): InviteStatus {
+  if (invite.revokedAt) return "revoked";
+  if (invite.usedAt) return "redeemed";
+  if (now.getTime() > new Date(invite.expiresAt).getTime()) return "expired";
+  return "pending";
+}
+
+export interface IssueInviteOpts {
+  /** Admin user id issuing the invite (audit). */
+  createdBy: string;
+  /** Pinned vault name; omit/null to let the redeemer name their own. */
+  vaultName?: string | null;
+  /** `user_vaults` role granted on redemption. Default `'write'` (owner). */
+  role?: string;
+  /** Provision a new vault on redemption. Default `true` (the primary flow). */
+  provisionVault?: boolean;
+  /** `'internal' | 'off'` mirror knob for the provisioned vault. */
+  defaultMirror?: string | null;
+  /** Lifetime in seconds. Default {@link DEFAULT_INVITE_TTL_SECONDS} (7 days). */
+  expiresInSeconds?: number;
+  now?: () => Date;
+}
+
+export interface IssuedInvite {
+  /**
+   * The raw token — returned EXACTLY ONCE here and never persisted. The
+   * caller builds the redemption URL from it (`/account/setup/<rawToken>`)
+   * and shows it once; the hub keeps only `sha256(rawToken)`.
+   */
+  rawToken: string;
+  invite: Invite;
+}
+
+/**
+ * Mint an invite: generate a 256-bit raw token, store its sha256, return the
+ * raw token once. The row's PK is the hash, so a DB compromise can't replay
+ * the link.
+ */
+export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
+  const rawToken = randomBytes(INVITE_TOKEN_BYTES).toString("base64url");
+  const tokenHash = hashInviteToken(rawToken);
+  const now = opts.now?.() ?? new Date();
+  const createdAt = now.toISOString();
+  const ttl = opts.expiresInSeconds ?? DEFAULT_INVITE_TTL_SECONDS;
+  const expiresAt = new Date(now.getTime() + ttl * 1000).toISOString();
+  const role = opts.role ?? "write";
+  const vaultName = opts.vaultName ?? null;
+  const provisionVault = opts.provisionVault ?? true;
+  const defaultMirror = opts.defaultMirror ?? null;
+
+  db.prepare(
+    `INSERT INTO invites
+       (token, created_by, vault_name, role, provision_vault, default_mirror,
+        expires_at, used_at, redeemed_user_id, revoked_at, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?)`,
+  ).run(
+    tokenHash,
+    opts.createdBy,
+    vaultName,
+    role,
+    provisionVault ? 1 : 0,
+    defaultMirror,
+    expiresAt,
+    createdAt,
+  );
+
+  return {
+    rawToken,
+    invite: {
+      tokenHash,
+      createdBy: opts.createdBy,
+      vaultName,
+      role,
+      provisionVault,
+      defaultMirror,
+      expiresAt,
+      usedAt: null,
+      redeemedUserId: null,
+      revokedAt: null,
+      createdAt,
+    },
+  };
+}
+
+/** Look up an invite by its raw (URL) token. Hashes then selects. */
+export function findInviteByRawToken(db: Database, rawToken: string): Invite | null {
+  const hash = hashInviteToken(rawToken);
+  const row = db.query<Row, [string]>("SELECT * FROM invites WHERE token = ?").get(hash);
+  return row ? rowToInvite(row) : null;
+}
+
+/** Look up an invite by its sha256 hash (admin DELETE/revoke by id). */
+export function findInviteByHash(db: Database, tokenHash: string): Invite | null {
+  const row = db.query<Row, [string]>("SELECT * FROM invites WHERE token = ?").get(tokenHash);
+  return row ? rowToInvite(row) : null;
+}
+
+/** List every invite, newest first, with derived status. */
+export function listInvites(
+  db: Database,
+  now: Date = new Date(),
+): (Invite & { status: InviteStatus })[] {
+  const rows = db.query<Row, []>("SELECT * FROM invites ORDER BY created_at DESC").all();
+  return rows.map((r) => {
+    const invite = rowToInvite(r);
+    return { ...invite, status: inviteStatus(invite, now) };
+  });
+}
+
+/**
+ * Validate an invite for redemption WITHOUT consuming it. Throws on every
+ * not-redeemable branch (not-found / expired / used / revoked). Returns the
+ * invite when it's redeemable. The redemption handler calls this FIRST (so a
+ * bad token is rejected before any account/vault work), then does
+ * createUser, then `consumeInvite` AFTER the user row commits.
+ */
+export function assertInviteRedeemable(
+  db: Database,
+  rawToken: string,
+  now: Date = new Date(),
+): Invite {
+  const invite = findInviteByRawToken(db, rawToken);
+  if (!invite) throw new InviteNotFoundError();
+  // Revoked + used are terminal regardless of clock; check them before expiry
+  // so a revoked-then-expired invite reports the more specific reason.
+  if (invite.revokedAt) throw new InviteRevokedError();
+  if (invite.usedAt) throw new InviteUsedError();
+  if (now.getTime() > new Date(invite.expiresAt).getTime()) {
+    throw new InviteExpiredError();
+  }
+  return invite;
+}
+
+/**
+ * Mark an invite consumed — stamp `used_at` + `redeemed_user_id`. Called
+ * Called within the account-creation transaction (or after a committed user
+ * row). Single-use + not-revoked is enforced by the
+ * `used_at IS NULL AND revoked_at IS NULL` guard in the UPDATE: a racing
+ * second redeem — or a concurrent revoke — updates zero rows and the caller
+ * treats that as already-consumed/revoked. Race-safe because sqlite
+ * serializes writes.
+ *
+ * Returns `true` if THIS call consumed the invite, `false` otherwise.
+ */
+export function consumeInvite(
+  db: Database,
+  tokenHash: string,
+  redeemedUserId: string,
+  now: Date = new Date(),
+): boolean {
+  const res = db
+    .prepare(
+      "UPDATE invites SET used_at = ?, redeemed_user_id = ? WHERE token = ? AND used_at IS NULL AND revoked_at IS NULL",
+    )
+    .run(now.toISOString(), redeemedUserId, tokenHash);
+  return res.changes > 0;
+}
+
+/**
+ * Revoke a pending invite (admin DELETE). Stamps `revoked_at` only when the
+ * invite isn't already used or revoked. Returns `true` if this call revoked
+ * it, `false` if it was already consumed/revoked or not found.
+ */
+export function revokeInvite(db: Database, tokenHash: string, now: Date = new Date()): boolean {
+  const res = db
+    .prepare(
+      "UPDATE invites SET revoked_at = ? WHERE token = ? AND used_at IS NULL AND revoked_at IS NULL",
+    )
+    .run(now.toISOString(), tokenHash);
+  return res.changes > 0;
+}

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 {