@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/commands/status.ts

@@ -1,5 +1,15 @@
+import type { Database } from "bun:sqlite";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
-import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import { readHubPort } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  HUB_UNIT_DEFAULT_PORT,
+  type HubUnitDeps,
+  type HubUnitState,
+  type HubUnitStateResult,
+  defaultHubUnitDeps,
+  queryHubUnitState as queryHubUnitStateImpl,
+} from "../hub-unit.ts";
 import {
   type DetectInstallSourceDeps,
   detectHubInstallSource,
@@ -7,20 +17,20 @@ import {
   formatInstallSourceLabel,
   isStale,
 } from "../install-source.ts";
-import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
+import {
+  type DriveModuleOpDeps,
+  type ModuleStatesResult,
+  NoOperatorTokenError,
+  OperatorTokenExpiredError,
+  fetchModuleStates as fetchModuleStatesImpl,
+} from "../module-ops-client.ts";
 import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
 
-export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
-
 export interface StatusOpts {
   manifestPath?: string;
-  fetchImpl?: FetchFn;
   print?: (line: string) => void;
-  timeoutMs?: number;
   configDir?: string;
-  alive?: AliveFn;
-  now?: () => Date;
   /**
    * Test seam for install-source detection. Production reads the filesystem
    * + shells out to git; tests inject stubs so each case (npm / bun-linked /
@@ -34,54 +44,41 @@ export interface StatusOpts {
    * source classification doesn't depend on the test runner's location.
    */
   hubSrcDir?: string;
-}
-
-export interface ProbeResult {
-  entry: ServiceEntry;
-  healthy: boolean;
-  statusCode?: number;
-  error?: string;
-  latencyMs: number;
-}
-
-export async function probe(
-  entry: ServiceEntry,
-  fetchImpl: FetchFn,
-  timeoutMs: number,
-): Promise<ProbeResult> {
-  const url = `http://localhost:${entry.port}${entry.health}`;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  const start = performance.now();
-  try {
-    const res = await fetchImpl(url, { signal: controller.signal });
-    const latencyMs = Math.round(performance.now() - start);
-    // A 401 is the service replying "I'm up but this endpoint requires auth"
-    // — that's strictly healthy from a liveness perspective. Vault's
-    // canonical health path `/vault/<name>/health` is auth-gated; without
-    // this carve-out, `parachute status` shows vault as "failing" on every
-    // fresh install (first impression UX disaster despite vault being fine).
-    // 5xx → unhealthy; 200-class → healthy; 401 → healthy + auth-gated.
-    // Other 4xx (404 / 400 / etc.) still count as unhealthy — those mean
-    // the configured health path doesn't exist or is shaped wrong.
-    const healthy = res.ok || res.status === 401;
-    return {
-      entry,
-      healthy,
-      statusCode: res.status,
-      latencyMs,
-    };
-  } catch (err) {
-    const latencyMs = Math.round(performance.now() - start);
-    return {
-      entry,
-      healthy: false,
-      error: err instanceof Error ? err.message : String(err),
-      latencyMs,
-    };
-  } finally {
-    clearTimeout(timer);
-  }
+  /**
+   * Supervisor-path seams (design §6.4) — the ONLY runtime as of Phase 5b.
+   * `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). The detached
+   * pidfile/`processState` arm was retired in Phase 5b.
+   *
+   * Everything here is injectable so tests drive it 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?: {
+    /** Deps for `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;
+  };
 }
 
 function formatRow(cells: string[], widths: number[]): string {
@@ -154,6 +151,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,190 +177,103 @@ function urlForEntry(entry: ServiceEntry, short: string | undefined): string | u
   return `http://127.0.0.1:${entry.port}${first}`;
 }
 
-function hubRow(
-  configDir: string,
-  alive: AliveFn,
-  nowDate: Date,
-  hubSrcDir: string,
+/**
+ * The MANIFEST-derived portion of a module row — port/version/URL/drift/source/
+ * stale and the persisted `lastStartError` note. The supervisor read fills in
+ * the run-state fields (STATE / PID / UPTIME) on top.
+ *
+ * Pure over the manifest entry + install-source deps; no process / network read.
+ */
+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,
-): StatusRow | undefined {
-  const proc = processState(HUB_SVC, configDir, alive);
-  if (proc.status === "unknown") return undefined;
-  const port = readHubPort(configDir);
-  const portLabel = port !== undefined ? String(port) : "-";
-  // Hub doesn't self-probe (it'd be probing itself over loopback). Treat
-  // "running pidfile" as `active` and "stopped" as `inactive` — the same
-  // STATE rollup every other row uses, just without the probe input.
-  const stateLabel: StateLabel = proc.status === "running" ? "active" : "inactive";
-  const pidLabel = proc.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
-  const uptimeLabel =
-    proc.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
-  const source = detectHubInstallSource(hubSrcDir, installSourceDeps);
-  return {
-    service: "parachute-hub (internal)",
-    port: portLabel,
-    version: source.livePackageVersion ?? "-",
-    stateLabel,
-    pidLabel,
-    uptimeLabel,
-    healthDetail: "-",
-    latencyLabel: "-",
-    sourceLabel: formatInstallSourceLabel(source),
-    url: port !== undefined ? `http://127.0.0.1:${port}` : undefined,
-    healthy: true,
-    skipped: true,
-  };
+): 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 };
 }
 
 export async function status(opts: StatusOpts = {}): Promise<number> {
   const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
-  const fetchImpl = opts.fetchImpl ?? fetch;
   const print = opts.print ?? ((line) => console.log(line));
-  const timeoutMs = opts.timeoutMs ?? 1500;
   const configDir = opts.configDir ?? CONFIG_DIR;
-  const alive = opts.alive ?? defaultAlive;
-  const now = opts.now ?? (() => new Date());
   const installSourceDeps = opts.installSourceDeps ?? {};
   const hubSrcDir = opts.hubSrcDir ?? import.meta.dir;
 
   const manifest = readManifest(manifestPath);
-  if (manifest.services.length === 0) {
-    print("No services installed yet.");
-    print("Try: parachute install vault");
-    return 0;
-  }
-
-  const nowDate = now();
-
-  /**
-   * Per-row resolution: look up the short name so we can read PID state,
-   * skip the health probe when the process is known-stopped (ECONNREFUSED
-   * noise isn't informative), and report it as running/stopped + uptime.
-   *
-   * Third-party services we don't know about fall back to probing and show
-   * "-" for process columns.
-   */
-  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);
-      const proc = short ? processState(short, configDir, alive) : undefined;
-
-      const pidLabel =
-        proc?.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
-      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.
-      if (proc?.status === "stopped") {
-        return {
-          service: entry.name,
-          port: String(entry.port),
-          version: entry.version,
-          // Operator deliberately stopped (or pidfile-but-dead) maps to
-          // `inactive` per design-system.md §6 — same surface as "never
-          // started." No probe is informative when we know the process
-          // is dead.
-          stateLabel: "inactive",
-          pidLabel,
-          uptimeLabel,
-          healthDetail: "-",
-          latencyLabel: "-",
-          sourceLabel,
-          url,
-          healthy: false,
-          skipped: true,
-          driftWarning,
-          staleNote,
-          startErrorNote,
-        };
-      }
 
-      const p = await probe(entry, fetchImpl, timeoutMs);
-      const healthDetail = p.healthy
-        ? "ok"
-        : p.statusCode !== undefined
-          ? `http ${p.statusCode}`
-          : (p.error ?? "down");
-      // STATE rollup per design-system.md §6:
-      //   - probe ok                  → `active`
-      //   - probe failed              → `failing` (the probe ran, so the
-      //                                 process is up enough to answer or
-      //                                 refuse — it's failing, not stopped)
-      //   - no PID file + probe fails → `failing` too (externally-managed
-      //                                 row that's down is still "failing"
-      //                                 from the operator's view)
-      // The `pending` state isn't reachable from `parachute status` today
-      // — pending-OAuth surfaces in the admin SPA, not the CLI. If a
-      // future surface adds it (e.g. supervisor reports `pending-config`
-      // for unconfigured modules), wire it here.
-      const stateLabel: StateLabel = p.healthy ? "active" : "failing";
-      return {
-        service: entry.name,
-        port: String(entry.port),
-        version: entry.version,
-        stateLabel,
-        pidLabel,
-        uptimeLabel,
-        healthDetail,
-        latencyLabel: `${p.latencyMs}ms`,
-        sourceLabel,
-        url,
-        healthy: p.healthy,
-        skipped: false,
-        driftWarning,
-        staleNote,
-        startErrorNote,
-      };
-    }),
-  );
-
-  // Hub is an internal service — not in services.json, but users notice
-  // when it's dead. Only show it if we've seen it run.
-  const hub = hubRow(configDir, alive, nowDate, hubSrcDir, installSourceDeps);
-  if (hub) rows.push(hub);
+  // Supervised path only (Phase 5b — the detached pidfile arm is retired). Read
+  // the hub row from the platform manager + `/health` and the module rows from
+  // the RUNNING supervisor (§6.4). The hub row is meaningful even with zero
+  // modules installed (the hub runs under a unit), so a "no modules" table is
+  // rendered rather than the old "No services installed yet." early return.
+  const sup = resolveStatusSupervisor(opts.supervisor);
+  const rows = await buildSupervisorRows({
+    manifest,
+    configDir,
+    installSourceDeps,
+    hubSrcDir,
+    sup,
+  });
+  renderRows(rows, print);
+  // A row is `healthy: false` + `!skipped` only when the supervisor (or the
+  // hub-row manager/health composition) says so (crashed / failing). 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;
+}
 
+/**
+ * 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 +317,397 @@ 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;
+// ---------------------------------------------------------------------------
+// Supervisor-path status (design §6.4) — the ONLY runtime as of Phase 5b.
+//
+// `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 pidfile arm was retired
+// in Phase 5b.
+// ---------------------------------------------------------------------------
+
+/** Resolved supervisor-path seams (see `StatusOpts.supervisor`). */
+interface ResolvedStatusSupervisor {
+  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 supervisor-path seams. Production passes `supervisor: {}` (or
+ * omits it) and gets the real impls; tests inject the seams they want to assert.
+ */
+function resolveStatusSupervisor(opts: StatusOpts["supervisor"]): ResolvedStatusSupervisor {
+  const hubUnitDeps = opts?.hubUnitDeps ?? defaultHubUnitDeps;
+  return {
+    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" } : {}),
+  };
 }