@openparachute/hub 0.6.2 → 0.6.3-rc.1

package/src/commands/status.ts

@@ -1,5 +1,16 @@
+import type { Database } from "bun:sqlite";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  HUB_UNIT_DEFAULT_PORT,
+  type HubUnitDeps,
+  type HubUnitState,
+  type HubUnitStateResult,
+  defaultHubUnitDeps,
+  isHubUnitInstalled,
+  queryHubUnitState as queryHubUnitStateImpl,
+} from "../hub-unit.ts";
 import {
   type DetectInstallSourceDeps,
   detectHubInstallSource,
@@ -7,6 +18,13 @@ import {
   formatInstallSourceLabel,
   isStale,
 } from "../install-source.ts";
+import {
+  type DriveModuleOpDeps,
+  type ModuleStatesResult,
+  NoOperatorTokenError,
+  OperatorTokenExpiredError,
+  fetchModuleStates as fetchModuleStatesImpl,
+} from "../module-ops-client.ts";
 import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
 import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
@@ -34,6 +52,54 @@ export interface StatusOpts {
    * source classification doesn't depend on the test runner's location.
    */
   hubSrcDir?: string;
+  /**
+   * Phase 3c supervisor-path seams (design §6.4). When a hub UNIT is installed
+   * (launchd/systemd/container — detected via {@link isHubUnitInstalled}),
+   * `status` reads the hub row from the PLATFORM MANAGER (`queryHubUnitState`)
+   * + `/health`, and the module rows from the RUNNING supervisor (`GET
+   * /api/modules` via the operator-token→Bearer path). On a legacy detached box
+   * (no hub unit) it keeps the EXACT pidfile/`processState` behavior, unchanged
+   * until Phase 5 retires it.
+   *
+   * Everything here is injectable so tests force either arm without a real
+   * launchd/systemd/socket/HTTP call. Production wires the real machinery; the
+   * read paths are bounded + degrade gracefully on every failure (no manager,
+   * hub down, no token, API error) so `status` never hangs or crashes.
+   */
+  supervisor?: {
+    /**
+     * Is a hub unit installed (the dual-dispatch discriminant)? Production uses
+     * `isHubUnitInstalled(hubUnitDeps)`. Tests set this `true`/`false` directly
+     * to pick the branch deterministically. When set, it wins over the
+     * `hubUnitDeps`-derived detection.
+     *
+     * Defaulting: when the caller OMITS the `supervisor` block entirely (every
+     * existing status test), the arm defaults to detached — so those tests stay
+     * deterministic regardless of whether the test host has a real hub unit.
+     */
+    unitInstalled?: boolean;
+    /** Deps for `isHubUnitInstalled` + `queryHubUnitState` + the `/health` probe. */
+    hubUnitDeps?: HubUnitDeps;
+    /** Query the platform manager for the hub unit's run-state (§6.4 hub row). */
+    queryHubUnitState?: (deps: HubUnitDeps) => HubUnitStateResult;
+    /**
+     * Probe whether the loopback hub answers `/health`. The liveness signal for
+     * the hub row (§6.4) AND the gate for reading module states: if the hub is
+     * down, skip the API read and show modules degraded. Production reuses the
+     * hub-unit deps' bounded `probeHealth`.
+     */
+    probeHubHealth?: (port: number) => Promise<boolean>;
+    /** Read the running supervisor's module states (§6.4 module rows). */
+    fetchModuleStates?: (deps: DriveModuleOpDeps) => Promise<ModuleStatesResult>;
+    /**
+     * Open the hub DB used to validate/auto-rotate the operator token in
+     * `fetchModuleStates`. Production opens `<configDir>/hub.db`; tests inject a
+     * seeded db. Returns a handle the caller closes.
+     */
+    openDb?: (configDir: string) => Database;
+    /** Loopback hub base URL override (default derives from the hub port). */
+    baseUrl?: string;
+  };
 }
 
 export interface ProbeResult {
@@ -154,6 +220,16 @@ interface StatusRow {
    * just showing it inactive. Cleared on the next successful start.
    */
   startErrorNote?: string;
+  /**
+   * Hub-row-only manager-context note (Phase 3c, §6.4). Surfaces the platform
+   * manager's view when it adds signal the STATE column can't carry:
+   *   - "container runtime (managed)" on Render/Fly (no on-box manager).
+   *   - "service manager reports active; /health not answering yet (starting or
+   *     unhealthy)" when the unit is up but the hub isn't serving.
+   *   - the manager's failed-unit detail / last-exit code.
+   * Printed on a continuation line like the other notes.
+   */
+  managerNote?: string;
 }
 
 /**
@@ -170,6 +246,70 @@ function urlForEntry(entry: ServiceEntry, short: string | undefined): string | u
   return `http://127.0.0.1:${entry.port}${first}`;
 }
 
+/**
+ * The MANIFEST-derived portion of a module row — identical regardless of
+ * whether the row's run-state comes from a pidfile (detached arm) or the
+ * supervisor (Phase 3c). Extracting it keeps the two arms in lockstep on
+ * port/version/URL/drift/source/stale and the persisted `lastStartError` note,
+ * so the only per-arm difference is the run-state fields (STATE / PID / UPTIME).
+ *
+ * Pure over the manifest entry + install-source deps; no process / network
+ * read. Shared so the detached arm stays behavior-identical (existing tests
+ * guard it) while the supervisor arm reuses the exact same derivation.
+ */
+interface ManifestRowBase {
+  short: string | undefined;
+  url: string | undefined;
+  driftWarning?: string;
+  sourceLabel: string;
+  staleNote?: string;
+  /** The persisted `lastStartError` note (detached preflight wrote it). */
+  manifestStartErrorNote?: string;
+}
+
+function manifestRowBase(
+  entry: ServiceEntry,
+  installSourceDeps: DetectInstallSourceDeps,
+): ManifestRowBase {
+  // Third-party rows (with `installDir`) live under `~/.parachute/<entry.name>/`,
+  // matching what `parachute start` uses as the short. First-party rows still
+  // map manifestName → short via the canonical fallback.
+  const short = shortNameForManifest(entry.name) ?? (entry.installDir ? entry.name : undefined);
+  const url = urlForEntry(entry, short);
+
+  // Canonical-port drift detection (hub#195). Only fires for known first-party
+  // services where we have a canonical assignment. Third-party rows have no
+  // canonical to compare against. Informational — operators may have moved a
+  // service off canonical deliberately.
+  const canonical = canonicalPortForManifest(entry.name);
+  const driftWarning =
+    canonical !== undefined && canonical !== entry.port
+      ? `canonical port is ${canonical}`
+      : undefined;
+
+  // Install-source detection (hub#243). One filesystem walk + maybe one
+  // `git rev-parse` per row. Failures degrade silently to `unknown`.
+  const detectArgs: { entryName: string; installDir?: string } = { entryName: entry.name };
+  if (entry.installDir !== undefined) detectArgs.installDir = entry.installDir;
+  const source = detectInstallSource(detectArgs, installSourceDeps);
+  const sourceLabel = formatInstallSourceLabel(source);
+  const staleNote = isStale(entry.version, source)
+    ? `STALE: services.json cached ${entry.version}; live package.json ${source.livePackageVersion}`
+    : undefined;
+
+  // Persisted last-start failure (lifecycle preflight wrote a missing-dependency
+  // wire onto services.json). Surface a one-line summary; the full install
+  // recipe lives in services.json + the admin SPA card.
+  const manifestStartErrorNote =
+    entry.lastStartError !== undefined
+      ? entry.lastStartError.binary !== undefined
+        ? `failed to start: ${entry.lastStartError.binary} not installed — run \`parachute status\` detail or see /admin/modules for install steps`
+        : `failed to start: ${entry.lastStartError.error_description.split("\n")[0]}`
+      : undefined;
+
+  return { short, url, driftWarning, sourceLabel, staleNote, manifestStartErrorNote };
+}
+
 function hubRow(
   configDir: string,
   alive: AliveFn,
@@ -217,6 +357,36 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
   const hubSrcDir = opts.hubSrcDir ?? import.meta.dir;
 
   const manifest = readManifest(manifestPath);
+
+  // Phase 3c dual-dispatch (design §6.4). On a box with a hub unit installed
+  // (launchd/systemd/container), read the hub row from the platform manager +
+  // `/health` and the module rows from the RUNNING supervisor; otherwise fall
+  // through to the unchanged detached arm below. Phase 5 deletes the else-arm —
+  // keep this a clean top-level branch so that deletion is a one-liner.
+  //
+  // Branched BEFORE the detached arm's empty-manifest early return: on a
+  // unit-managed box the hub row is meaningful even with zero modules installed
+  // (the hub IS running under a unit), so the supervisor arm renders the hub row
+  // + a "no modules" table rather than the detached "No services installed yet."
+  const sup = resolveStatusSupervisor(opts.supervisor);
+  if (sup.unitInstalled) {
+    const rows = await buildSupervisorRows({
+      manifest,
+      configDir,
+      installSourceDeps,
+      hubSrcDir,
+      sup,
+    });
+    renderRows(rows, print);
+    // The supervisor arm marks a row `healthy: false` + `!skipped` only when the
+    // supervisor (or the hub-row manager/health composition) says so (crashed /
+    // failing) — same exit contract as the detached arm: a stopped/inactive row
+    // is expected (skipped, exit 0), a `failing` one exits 1.
+    const anyUnhealthy = rows.some((r) => !r.skipped && !r.healthy);
+    return anyUnhealthy ? 1 : 0;
+  }
+  // --- no-unit detached fallback (unchanged; preserved until Phase 5) ---
+
   if (manifest.services.length === 0) {
     print("No services installed yet.");
     print("Try: parachute install vault");
@@ -235,10 +405,16 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
    */
   const rows: StatusRow[] = await Promise.all(
     manifest.services.map(async (entry) => {
-      // Third-party rows (with `installDir`) live under `~/.parachute/<entry.name>/`,
-      // matching what `parachute start` uses as the short. First-party rows still
-      // map manifestName → short via the canonical fallback.
-      const short = shortNameForManifest(entry.name) ?? (entry.installDir ? entry.name : undefined);
+      // MANIFEST-derived fields shared with the supervisor arm (port/version/
+      // URL/drift/source/stale + the persisted lastStartError note).
+      const {
+        short,
+        url,
+        driftWarning,
+        sourceLabel,
+        staleNote,
+        manifestStartErrorNote: startErrorNote,
+      } = manifestRowBase(entry, installSourceDeps);
       const proc = short ? processState(short, configDir, alive) : undefined;
 
       const pidLabel =
@@ -246,43 +422,6 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
       const uptimeLabel =
         proc?.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
 
-      const url = urlForEntry(entry, short);
-
-      // Canonical-port drift detection (hub#195). Only fires for known
-      // first-party services where we have a canonical assignment. Third-party
-      // rows have no canonical to compare against. Warning is informational —
-      // operators may have moved a service off canonical deliberately.
-      // Note: multi-vault instance rows (`parachute-vault-<instance>`) don't
-      // match a canonical manifest name, so drift warnings don't fire for
-      // them. Intentional — see `canonicalPortForManifest` for the rationale.
-      const canonical = canonicalPortForManifest(entry.name);
-      const driftWarning =
-        canonical !== undefined && canonical !== entry.port
-          ? `canonical port is ${canonical}`
-          : undefined;
-
-      // Install-source detection (hub#243). One filesystem walk + maybe one
-      // `git rev-parse` per row. Failures degrade silently to `unknown` —
-      // status output should never error out on a missing checkout dir.
-      const detectArgs: { entryName: string; installDir?: string } = { entryName: entry.name };
-      if (entry.installDir !== undefined) detectArgs.installDir = entry.installDir;
-      const source = detectInstallSource(detectArgs, installSourceDeps);
-      const sourceLabel = formatInstallSourceLabel(source);
-      const staleNote = isStale(entry.version, source)
-        ? `STALE: services.json cached ${entry.version}; live package.json ${source.livePackageVersion}`
-        : undefined;
-
-      // Persisted last-start failure (lifecycle preflight wrote a missing-
-      // dependency wire). Surface a one-line summary; the full install recipe
-      // lives in services.json + the admin SPA card. Keeps `parachute status`
-      // scannable while still telling the operator "this is why it's down."
-      const startErrorNote =
-        entry.lastStartError !== undefined
-          ? entry.lastStartError.binary !== undefined
-            ? `failed to start: ${entry.lastStartError.binary} not installed — run \`parachute status\` detail or see /admin/modules for install steps`
-            : `failed to start: ${entry.lastStartError.error_description.split("\n")[0]}`
-          : undefined;
-
       // Only skip probe when we know the process is dead (PID file was
       // present but kill(pid, 0) failed). "unknown" status (no PID file)
       // still probes — externally-managed services should report health.
@@ -354,6 +493,25 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
   const hub = hubRow(configDir, alive, nowDate, hubSrcDir, installSourceDeps);
   if (hub) rows.push(hub);
 
+  renderRows(rows, print);
+
+  /**
+   * Overall exit: non-zero if any *probed* service is unhealthy. A stopped
+   * service is expected ("I haven't started it yet"), not a failure — users
+   * want `parachute status` to return 0 after a fresh install before they
+   * `parachute start`. Health regressions among running services still 1.
+   */
+  const anyUnhealthy = rows.some((r) => !r.skipped && !r.healthy);
+  return anyUnhealthy ? 1 : 0;
+}
+
+/**
+ * Render the status table + continuation lines. Shared by the detached arm and
+ * the Phase 3c supervisor arm so the table shape (design-system.md §6 columns +
+ * the `→`/`!` continuation prefixes) is identical regardless of where each
+ * row's run-state was sourced. Pure over `rows` + the `print` sink.
+ */
+function renderRows(rows: StatusRow[], print: (line: string) => void): void {
   // Header per design-system.md §6 "CLI status column shape":
   //   SERVICE  PORT  VERSION  STATE   PID  UPTIME  LATENCY  SOURCE
   // Pre-F shape was SERVICE PORT VERSION PROCESS PID UPTIME HEALTH LATENCY
@@ -397,17 +555,406 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     if (row.stateLabel === "failing" && row.healthDetail !== "-" && row.healthDetail.length > 0) {
       print(`  ! probe: ${row.healthDetail}`);
     }
+    if (row.managerNote) print(`  ! ${row.managerNote}`);
     if (row.driftWarning) print(`  ! ${row.driftWarning}`);
     if (row.staleNote) print(`  ! ${row.staleNote}`);
     if (row.startErrorNote) print(`  ! ${row.startErrorNote}`);
   }
+}
 
-  /**
-   * Overall exit: non-zero if any *probed* service is unhealthy. A stopped
-   * service is expected ("I haven't started it yet"), not a failure — users
-   * want `parachute status` to return 0 after a fresh install before they
-   * `parachute start`. Health regressions among running services still 1.
-   */
-  const anyUnhealthy = rows.some((r) => !r.skipped && !r.healthy);
-  return anyUnhealthy ? 1 : 0;
+// ---------------------------------------------------------------------------
+// Phase 3c supervisor-path status (design §6.4).
+//
+// When a hub unit is installed, `status` reads the hub row from the PLATFORM
+// MANAGER (`queryHubUnitState`) + a `/health` probe, and the module rows from
+// the RUNNING supervisor (`GET /api/modules` via the operator-token→Bearer
+// path). Every read is bounded + degrades gracefully — `status` is a
+// diagnostic and must NEVER hang or crash regardless of hub/manager/token
+// state. The detached arm above is untouched; Phase 5 deletes it.
+// ---------------------------------------------------------------------------
+
+/** Resolved Phase 3c supervisor-path seams (see `StatusOpts.supervisor`). */
+interface ResolvedStatusSupervisor {
+  /** Whether a hub unit is installed — the dual-dispatch discriminant. */
+  unitInstalled: boolean;
+  hubUnitDeps: HubUnitDeps;
+  queryHubUnitState: (deps: HubUnitDeps) => HubUnitStateResult;
+  probeHubHealth: (port: number) => Promise<boolean>;
+  fetchModuleStates: (deps: DriveModuleOpDeps) => Promise<ModuleStatesResult>;
+  openDb: (configDir: string) => Database;
+  baseUrl: string | undefined;
+}
+
+/**
+ * Resolve the Phase 3c supervisor-path seams. Mirrors lifecycle.ts's
+ * `resolveSupervisor` discriminant policy:
+ *   - No `supervisor` block at all (every existing status test) → detached arm,
+ *     deterministically (no real-filesystem probe).
+ *   - A `supervisor` block present → explicit `unitInstalled` override if set,
+ *     else the real `isHubUnitInstalled` probe over the hub-unit deps.
+ */
+function resolveStatusSupervisor(opts: StatusOpts["supervisor"]): ResolvedStatusSupervisor {
+  const hubUnitDeps = opts?.hubUnitDeps ?? defaultHubUnitDeps;
+  const unitInstalled =
+    opts === undefined ? false : (opts.unitInstalled ?? isHubUnitInstalled(hubUnitDeps));
+  return {
+    unitInstalled,
+    hubUnitDeps,
+    queryHubUnitState: opts?.queryHubUnitState ?? queryHubUnitStateImpl,
+    probeHubHealth: opts?.probeHubHealth ?? hubUnitDeps.probeHealth,
+    fetchModuleStates: opts?.fetchModuleStates ?? fetchModuleStatesImpl,
+    openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
+    baseUrl: opts?.baseUrl,
+  };
+}
+
+/**
+ * Resolve the issuer the operator token is validated against — the hub's
+ * current loopback origin. Mirrors lifecycle.ts's `resolveOperatorTokenIssuer`
+ * fallback (`readHubPort ?? HUB_UNIT_DEFAULT_PORT`); both resolve to 1939 under
+ * canonical-ports, so they agree with what `auth rotate-operator` minted under.
+ */
+function statusOperatorTokenIssuer(configDir: string): string {
+  return `http://127.0.0.1:${readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT}`;
+}
+
+/**
+ * Map a supervisor `ModuleState.status` to the canonical STATE rollup
+ * (design-system.md §6). `running` is `active`; `crashed` is `failing`;
+ * `starting` / `restarting` are `pending` (in-flight operator-visible
+ * transition); `stopped` is `inactive`. An unknown/absent status (module not
+ * tracked by the supervisor — never booted, skipped at boot) is `inactive`.
+ */
+function mapSupervisorStatus(status: string | null): {
+  stateLabel: StateLabel;
+  healthy: boolean;
+  skipped: boolean;
+} {
+  switch (status) {
+    case "running":
+      return { stateLabel: "active", healthy: true, skipped: false };
+    case "crashed":
+      return { stateLabel: "failing", healthy: false, skipped: false };
+    case "starting":
+    case "restarting":
+      // In-flight transition — supervised, mid-operation. `pending` is the
+      // canonical "needs-attention transient" rollup; treat as not-a-failure
+      // (skipped) so a mid-restart module doesn't flip `status` to exit 1.
+      return { stateLabel: "pending", healthy: true, skipped: true };
+    default:
+      // stopped / null / unknown — operator-stopped or never started. The
+      // `skipped: true` + `healthy: false` pairing is DELIBERATE, not a mismatch:
+      //   - `healthy: false` is honest — an inactive module is genuinely not
+      //     serving (so a detail renderer can style it as down, not green).
+      //   - `skipped: true` keeps the exit-code check (`rows.some(r => !r.skipped
+      //     && !r.healthy)` at the call site, ~:385) from counting an
+      //     operator-stopped module as a FAILURE — `parachute stop vault` then
+      //     `status` must still exit 0.
+      // This is the same combination + exit semantics the detached arm uses for
+      // its `inactive` (operator-stopped) rows.
+      return { stateLabel: "inactive", healthy: false, skipped: true };
+  }
+}
+
+/**
+ * Format a supervisor `startError` (the structured missing-dependency /
+ * started-but-unbound wire, §6.5) into the same one-line note the detached arm
+ * shows from `services.json.lastStartError` (#188). Returns undefined when
+ * there's no usable detail.
+ */
+function supervisorStartErrorNote(startError: unknown): string | undefined {
+  if (!startError || typeof startError !== "object") return undefined;
+  const e = startError as { binary?: unknown; error_description?: unknown };
+  if (typeof e.binary === "string" && e.binary.length > 0) {
+    return `failed to start: ${e.binary} not installed — see /admin/modules for install steps`;
+  }
+  if (typeof e.error_description === "string" && e.error_description.length > 0) {
+    return `failed to start: ${e.error_description.split("\n")[0]}`;
+  }
+  return undefined;
+}
+
+interface BuildSupervisorRowsArgs {
+  manifest: ReturnType<typeof readManifest>;
+  configDir: string;
+  installSourceDeps: DetectInstallSourceDeps;
+  hubSrcDir: string;
+  sup: ResolvedStatusSupervisor;
+}
+
+/**
+ * Build the full status rows on a UNIT-MANAGED box (design §6.4): module rows
+ * from the running supervisor, the hub row from the platform manager + /health.
+ * Never throws — every read is wrapped + degrades to a sensible readout.
+ */
+async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<StatusRow[]> {
+  const { manifest, configDir, installSourceDeps, hubSrcDir, sup } = args;
+  const port = readHubPort(configDir) ?? HUB_UNIT_DEFAULT_PORT;
+
+  // Probe the hub once: it's both the hub row's liveness signal AND the gate for
+  // whether the supervisor (module states) is reachable. Bounded; never throws.
+  let hubHealthy = false;
+  try {
+    hubHealthy = await sup.probeHubHealth(port);
+  } catch {
+    hubHealthy = false;
+  }
+
+  // Read the running supervisor's module states — ONLY when the hub answers
+  // (children die with the hub, so a down hub means every module is down; no
+  // point calling, and the call would just connection-refuse). Degrade on every
+  // failure path: no token, expired token, HTTP error, anything — `status`
+  // shows what it can rather than crashing.
+  let states: ModuleStatesResult | undefined;
+  let moduleReadNote: string | undefined;
+  if (hubHealthy) {
+    const db = sup.openDb(configDir);
+    try {
+      states = await sup.fetchModuleStates({
+        db,
+        issuer: statusOperatorTokenIssuer(configDir),
+        configDir,
+        ...(sup.baseUrl !== undefined ? { baseUrl: sup.baseUrl } : {}),
+      });
+    } catch (err) {
+      if (err instanceof NoOperatorTokenError || err instanceof OperatorTokenExpiredError) {
+        // No / expired operator token: we can't read module run-state, but the
+        // hub is up. Show the manifest-derived rows with an actionable note —
+        // do NOT 401-crash status (§6.4 graceful degradation).
+        moduleReadNote =
+          "couldn't read live module state — run `parachute auth rotate-operator` to mint an operator token";
+      } else {
+        // HTTP error / parse / anything else — degrade with the message.
+        moduleReadNote = `couldn't read live module state (${
+          err instanceof Error ? err.message : String(err)
+        })`;
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  const stateByShort = new Map<string, ModuleStatesResult["modules"][number]>();
+  for (const m of states?.modules ?? []) {
+    if (m.short) stateByShort.set(m.short, m);
+  }
+
+  const rows: StatusRow[] = manifest.services.map((entry) => {
+    const base = manifestRowBase(entry, installSourceDeps);
+    const snap = base.short ? stateByShort.get(base.short) : undefined;
+
+    if (!hubHealthy) {
+      // Hub is down → every supervised module is down with it. Show `inactive`
+      // (expected, not a failure) with a note rather than a probe failure.
+      return {
+        service: entry.name,
+        port: String(entry.port),
+        version: entry.version,
+        stateLabel: "inactive",
+        pidLabel: "-",
+        uptimeLabel: "-",
+        healthDetail: "-",
+        latencyLabel: "-",
+        sourceLabel: base.sourceLabel,
+        url: base.url,
+        healthy: false,
+        skipped: true,
+        ...(base.driftWarning ? { driftWarning: base.driftWarning } : {}),
+        ...(base.staleNote ? { staleNote: base.staleNote } : {}),
+        managerNote: "hub is down — its modules are stopped",
+      };
+    }
+
+    const { stateLabel, healthy, skipped } = mapSupervisorStatus(snap?.supervisor_status ?? null);
+    // Prefer the supervisor's structured start-error (live), else the persisted
+    // services.json note — same friendly surface either way (#188).
+    const startErrorNote =
+      supervisorStartErrorNote(snap?.supervisor_start_error) ?? base.manifestStartErrorNote;
+    const healthDetail =
+      stateLabel === "failing" ? `supervisor: ${snap?.supervisor_status ?? "crashed"}` : "-";
+
+    const row: StatusRow = {
+      service: entry.name,
+      port: String(entry.port),
+      version: entry.version,
+      stateLabel,
+      pidLabel: snap?.pid !== undefined && snap?.pid !== null ? String(snap.pid) : "-",
+      uptimeLabel: "-",
+      healthDetail,
+      latencyLabel: "-",
+      sourceLabel: base.sourceLabel,
+      url: base.url,
+      healthy,
+      skipped,
+    };
+    if (base.driftWarning) row.driftWarning = base.driftWarning;
+    if (base.staleNote) row.staleNote = base.staleNote;
+    if (startErrorNote) row.startErrorNote = startErrorNote;
+    // Surface the degraded-read note ONCE — on the first module row so the
+    // operator sees why run-state is missing, without repeating it on every row.
+    if (moduleReadNote) {
+      row.managerNote = moduleReadNote;
+      moduleReadNote = undefined;
+    }
+    return row;
+  });
+
+  const hub = buildSupervisorHubRow({
+    configDir,
+    hubSrcDir,
+    installSourceDeps,
+    sup,
+    port,
+    hubHealthy,
+  });
+  // If the degraded-read note never landed on a module row (empty manifest),
+  // surface it on the hub row so the operator still sees the actionable hint.
+  if (moduleReadNote && !hub.managerNote) hub.managerNote = moduleReadNote;
+  rows.push(hub);
+  return rows;
+}
+
+interface BuildSupervisorHubRowArgs {
+  configDir: string;
+  hubSrcDir: string;
+  installSourceDeps: DetectInstallSourceDeps;
+  sup: ResolvedStatusSupervisor;
+  port: number;
+  hubHealthy: boolean;
+}
+
+/**
+ * Build the hub row from the platform manager + /health (design §6.4). The
+ * manager's `queryHubUnitState` is the run-state; `/health` is the liveness
+ * signal. Composition:
+ *   - manager `active` + /health OK → `active` (running).
+ *   - manager `active` + /health down → `failing` with a "starting/unhealthy"
+ *     note (the unit is up but not serving yet).
+ *   - manager `failed` → `failing` (surface the last-exit code).
+ *   - manager `inactive` → `inactive`.
+ *   - no on-box manager (container/Render/Fly) → lean on /health for liveness;
+ *     report "container runtime (managed)".
+ * Never throws — a manager-query failure degrades to the /health verdict.
+ */
+function buildSupervisorHubRow(args: BuildSupervisorHubRowArgs): StatusRow {
+  const { configDir, hubSrcDir, installSourceDeps, sup, port, hubHealthy } = args;
+  const source = detectHubInstallSource(hubSrcDir, installSourceDeps);
+  const base: Omit<StatusRow, "stateLabel" | "pidLabel" | "uptimeLabel" | "healthy" | "skipped"> & {
+    healthDetail: string;
+  } = {
+    service: "parachute-hub (internal)",
+    port: String(port),
+    version: source.livePackageVersion ?? "-",
+    healthDetail: "-",
+    latencyLabel: "-",
+    sourceLabel: formatInstallSourceLabel(source),
+    url: `http://127.0.0.1:${port}`,
+  };
+
+  let managerState: HubUnitState;
+  let lastExitCode: number | undefined;
+  try {
+    const q = sup.queryHubUnitState(sup.hubUnitDeps);
+    managerState = q.state;
+    lastExitCode = q.lastExitCode;
+  } catch {
+    // The manager query must never crash status — fall back to /health only.
+    managerState = "unknown";
+  }
+
+  // No on-box manager (container / Render / Fly): there's nothing to query —
+  // `/health` is the sole liveness signal. Report the managed-runtime nuance.
+  if (managerState === "no-manager") {
+    return {
+      ...base,
+      stateLabel: hubHealthy ? "active" : "failing",
+      pidLabel: "-",
+      uptimeLabel: "-",
+      healthDetail: hubHealthy ? "-" : "down",
+      healthy: hubHealthy,
+      skipped: hubHealthy,
+      managerNote: "container runtime (managed)",
+    };
+  }
+
+  // Manager says failed: surface it as `failing` with the last-exit code even if
+  // a respawn happens to be answering /health right now.
+  if (managerState === "failed") {
+    return {
+      ...base,
+      stateLabel: "failing",
+      pidLabel: "-",
+      uptimeLabel: "-",
+      healthDetail: hubHealthy ? "service manager reports failed" : "down",
+      healthy: false,
+      skipped: false,
+      managerNote:
+        lastExitCode !== undefined
+          ? `service manager reports the hub unit failed (last exit code ${lastExitCode})`
+          : "service manager reports the hub unit failed",
+    };
+  }
+
+  // Manager says active.
+  if (managerState === "active") {
+    if (hubHealthy) {
+      return {
+        ...base,
+        stateLabel: "active",
+        pidLabel: "-",
+        uptimeLabel: "-",
+        healthy: true,
+        skipped: true,
+      };
+    }
+    // Active per the manager but not answering /health: starting up or wedged.
+    return {
+      ...base,
+      stateLabel: "failing",
+      pidLabel: "-",
+      uptimeLabel: "-",
+      healthDetail: "manager active, /health not answering",
+      healthy: false,
+      skipped: false,
+      managerNote:
+        "service manager reports active; /health not answering yet (starting or unhealthy)",
+    };
+  }
+
+  // Manager says activating: transient bring-up. If /health already answers,
+  // call it active; else show it as pending (in-flight).
+  if (managerState === "activating") {
+    return {
+      ...base,
+      stateLabel: hubHealthy ? "active" : "pending",
+      pidLabel: "-",
+      uptimeLabel: "-",
+      healthy: true,
+      skipped: true,
+      ...(hubHealthy ? {} : { managerNote: "service manager reports the hub unit is starting" }),
+    };
+  }
+
+  // Manager says inactive / unknown / no-unit (defensive — no-unit shouldn't
+  // reach here under the dual-dispatch). Trust /health as the tiebreaker: if the
+  // hub somehow answers, show active; else inactive.
+  if (hubHealthy) {
+    return {
+      ...base,
+      stateLabel: "active",
+      pidLabel: "-",
+      uptimeLabel: "-",
+      healthy: true,
+      skipped: true,
+    };
+  }
+  return {
+    ...base,
+    stateLabel: "inactive",
+    pidLabel: "-",
+    uptimeLabel: "-",
+    healthy: false,
+    skipped: true,
+    ...(managerState === "unknown" ? { managerNote: "service manager state unknown" } : {}),
+  };
 }