@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/migrate-offer.ts

@@ -0,0 +1,186 @@
+/**
+ * §7.5 auto-detect-and-offer — the safety net that keeps a box that landed the
+ * cutover code (via `bun add -g @openparachute/hub@<new>` / auto-upgrade) WITHOUT
+ * running `parachute migrate --to-supervised` from silently going dead.
+ *
+ * Design `parachute.computer/design/2026-06-01-hub-as-supervisor-unification.md`
+ * §7.5: the first time a lifecycle verb (start/stop/restart) runs and finds
+ *   (a) NO hub unit installed, AND
+ *   (b) evidence of a prior detached install (pidfiles / services.json),
+ * it OFFERS to run the cutover (interactive prompt) or, in a non-interactive
+ * context, PRINTS the exact command. It does NOT silently auto-migrate —
+ * archiving / stopping services is destructive-adjacent, so this is
+ * detect-and-offer only.
+ *
+ * This is the bridge's companion: Phase 5a keeps the detached spawners intact
+ * (un-migrated boxes still work), and keeps the pidfile READERS so this detector
+ * can see the old state. Phase 5b retires the spawners; the readers stay one
+ * release longer precisely so this detector keeps working.
+ *
+ * EVERYTHING is behind injectable seams so tests drive the offer without a real
+ * prompt, a real cutover, or touching the operator's `~/.parachute`.
+ */
+
+import { existsSync } from "node:fs";
+import {
+  type CutoverOpts,
+  type CutoverResult,
+  cutoverToSupervised,
+} 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";
+import { readPid } from "./process-state.ts";
+import { shortNameForManifest } from "./service-spec.ts";
+import { readManifestLenient } from "./services-manifest.ts";
+
+/**
+ * Detect evidence of a prior DETACHED install — the §7.5 (b) condition. True
+ * when EITHER:
+ *   - a hub pidfile exists (`~/.parachute/hub/run/hub.pid`) — the clearest
+ *     detached-era fingerprint, written only by the detached `ensureHubRunning`
+ *     spawn; OR
+ *   - any services.json module has a pidfile (a module was `parachute start`-ed
+ *     the detached way).
+ *
+ * services.json EXISTING alone is NOT enough — a freshly `init`-ed supervised
+ * box also has a services.json. The discriminant is a PIDFILE, which only the
+ * detached path writes (the supervised path tracks children in-process, no
+ * pidfile). So this detects "a box that ran the detached daemons," not merely
+ * "a box that has been configured."
+ *
+ * Pure read; never mutates. Uses `readPid` (a reader the bridge keeps).
+ */
+export function hasPriorDetachedInstall(
+  configDir: string = CONFIG_DIR,
+  manifestPath: string = SERVICES_MANIFEST_PATH,
+): boolean {
+  // Hub pidfile — the detached-era fingerprint.
+  if (readPid(HUB_SVC, configDir) !== undefined) return true;
+  // Any module pidfile.
+  if (!existsSync(manifestPath)) return false;
+  let services: ReturnType<typeof readManifestLenient>["services"];
+  try {
+    services = readManifestLenient(manifestPath).services;
+  } catch {
+    return false;
+  }
+  for (const entry of services) {
+    const short = shortNameForManifest(entry.name) ?? entry.name;
+    if (readPid(short, configDir) !== undefined) return true;
+  }
+  return false;
+}
+
+/**
+ * The interactive-prompt seam (mirrors `migrate.ts`'s `defaultPrompt`). Tests
+ * inject a stub; production reads a line from stdin.
+ */
+export type OfferPrompt = (question: string) => Promise<string>;
+
+export async function defaultOfferPrompt(question: string): Promise<string> {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(question);
+  rl.close();
+  return answer;
+}
+
+export interface MigrateOfferOpts {
+  configDir?: string;
+  manifestPath?: string;
+  log?: (line: string) => void;
+  /** Injectable: is a hub unit installed? (default real probe). */
+  isHubUnitInstalled?: (deps: HubUnitDeps) => boolean;
+  hubUnitDeps?: HubUnitDeps;
+  /** Injectable: prior-detached-install detector (default `hasPriorDetachedInstall`). */
+  hasPriorDetached?: (configDir: string, manifestPath: string) => boolean;
+  /** Injectable: the cutover itself (default `cutoverToSupervised`). */
+  cutover?: (opts: CutoverOpts) => Promise<CutoverResult>;
+  /** Injectable interactive prompt (default reads stdin). */
+  prompt?: OfferPrompt;
+  /**
+   * TTY override. Production reads `process.stdin.isTTY`; tests pass true/false
+   * to drive the interactive-vs-print branch without manipulating real fds.
+   */
+  isTty?: boolean;
+}
+
+export type MigrateOfferOutcome =
+  /** No offer was made (a unit is installed, or no prior-detached evidence). */
+  | "no-offer"
+  /** Interactive: the operator declined the offer. */
+  | "declined"
+  /** Non-interactive: we printed the exact command (didn't run it). */
+  | "printed"
+  /** Interactive: the operator accepted and the cutover succeeded. */
+  | "migrated"
+  /** Interactive: the operator accepted but the cutover failed (recoverable). */
+  | "migrate-failed";
+
+export interface MigrateOfferResult {
+  outcome: MigrateOfferOutcome;
+  /** The cutover result, when one ran. */
+  cutover?: CutoverResult;
+}
+
+/**
+ * §7.5 detect-and-offer. Call this from a lifecycle verb's detached arm (before
+ * doing the detached work). Returns a structured outcome:
+ *
+ *   - `no-offer` — a hub unit IS installed (the supervised box; nothing to
+ *     offer), or there's no prior-detached evidence (a clean box). The caller
+ *     proceeds with whatever it was going to do.
+ *   - interactive (TTY) — prompt; on yes, RUN the cutover and return `migrated`
+ *     / `migrate-failed`; on no, return `declined`.
+ *   - non-interactive (no TTY) — PRINT the exact command and return `printed`.
+ *     NEVER auto-run in a non-TTY context (a cron/CI pipe must not stop services
+ *     unprompted).
+ *
+ * It NEVER silently migrates: the only path that runs the cutover is an explicit
+ * interactive "yes."
+ */
+export async function offerMigrateToSupervised(
+  opts: MigrateOfferOpts = {},
+): Promise<MigrateOfferResult> {
+  const configDir = opts.configDir ?? CONFIG_DIR;
+  const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
+  const log = opts.log ?? ((line) => console.log(line));
+  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);
+
+  // (a) no hub unit installed — only offer on the detached box.
+  if (unitInstalledFn(hubUnitDeps)) return { outcome: "no-offer" };
+  // (b) prior-detached evidence — don't pester a clean box.
+  if (!hasPriorDetached(configDir, manifestPath)) return { outcome: "no-offer" };
+
+  log("");
+  log("This box is running the legacy detached model (independent daemons, no");
+  log("process manager). The current Parachute hub runs supervised — `parachute");
+  log("serve` under launchd/systemd, with reboot survival + UI module management.");
+
+  if (!isTty) {
+    // Non-interactive: print the exact command, never run it.
+    log("");
+    log("To migrate, run:");
+    log("  parachute migrate --to-supervised");
+    log("");
+    return { outcome: "printed" };
+  }
+
+  // Interactive: offer to run it now.
+  const answer = (await prompt("Migrate to the supervised model now? [y/N] ")).trim().toLowerCase();
+  if (answer !== "y" && answer !== "yes") {
+    log("Skipped. Run `parachute migrate --to-supervised` when you're ready.");
+    return { outcome: "declined" };
+  }
+
+  const result = await cutover({ configDir, manifestPath, log });
+  for (const line of result.messages) log(line);
+  const ok = result.outcome === "migrated" || result.outcome === "already-migrated";
+  return { outcome: ok ? "migrated" : "migrate-failed", cutover: result };
+}

package/src/module-ops-client.ts

@@ -0,0 +1,457 @@
+/**
+ * CLI client for the module-ops HTTP API (`POST /api/modules/:short/<op>`).
+ *
+ * This is the credential + transport seam that Phase 3 of the
+ * hub-as-supervisor unification (design 2026-06-01 §3.1) will repoint
+ * `parachute start/stop/restart <svc>` onto: instead of touching pidfiles
+ * directly (`commands/lifecycle.ts`), those verbs become authenticated calls
+ * to the running hub's in-process Supervisor over loopback.
+ *
+ * **Phase 1 is additive.** This file ADDS the client + its tests; it does NOT
+ * repoint any existing CLI command. `parachute start/stop/restart/install/
+ * upgrade` stay on the detached `lifecycle.ts` path until the Phase 3 cutover.
+ *
+ * ## The credential (§3.1)
+ *
+ * The on-box caller's proof of operator authority is `~/.parachute/operator.token`
+ * — a hub-issued JWT carrying `parachute:host:admin` under the default `admin`
+ * scope-set, which is exactly the scope `api-modules-ops.ts` gates on. We READ
+ * it via `useOperatorTokenWithAutoRotate` (which validates against the hub DB +
+ * issuer and opportunistically re-mints a within-7d-of-expiry token in place);
+ * we never mint a parallel token, so there is no second SQLite writer racing
+ * the running hub. The token is presented as `Authorization: Bearer` to the
+ * loopback hub.
+ *
+ * No operator token on disk → an actionable error ("no operator token — run
+ * `parachute auth rotate-operator`"), never a raw 401.
+ *
+ * ## Sync vs async ops
+ *
+ * `start` / `stop` / `restart` / `uninstall` are synchronous: the handler does
+ * the work inline and returns the new state in the body. `install` / `upgrade`
+ * return `202 { operation_id }` and the client polls
+ * `GET /api/modules/operations/:id` to a terminal state. This client handles
+ * both: a 202-with-operation_id response is polled to completion; any other
+ * 2xx body is returned as-is.
+ */
+
+import type { Database } from "bun:sqlite";
+import { OperatorTokenExpiredError, useOperatorTokenWithAutoRotate } from "./operator-token.ts";
+
+/** Loopback hub base URL when none is injected. The hub pins 1939 (canonical-ports). */
+export const DEFAULT_HUB_BASE_URL = "http://127.0.0.1:1939";
+
+/** Default poll interval + ceiling for async operations. */
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_POLL_TIMEOUT_MS = 120_000;
+
+/**
+ * Default ceiling for the single `GET /api/modules` read in {@link fetchModuleStates}.
+ * `status` is a read-only health snapshot — a hub whose request handler is wedged
+ * (accepts the TCP connection but never answers) must not hang it. Bounded so the
+ * caller degrades to a "couldn't read live module state" note instead of stalling.
+ */
+const DEFAULT_STATES_FETCH_TIMEOUT_MS = 3_000;
+
+/** Module-op verbs the client can drive against `POST /api/modules/:short/<op>`. */
+export type ModuleOp = "start" | "stop" | "restart" | "install" | "upgrade" | "uninstall";
+
+/**
+ * Thrown when no `operator.token` exists on disk. The CLI surfaces
+ * `.message` directly — it's already actionable. Distinct error class so a
+ * caller can branch on "needs bootstrap" vs "hub said no."
+ */
+export class NoOperatorTokenError extends Error {
+  override name = "NoOperatorTokenError";
+  constructor() {
+    super(
+      "no operator token — run `parachute auth rotate-operator` to mint one (looked for ~/.parachute/operator.token)",
+    );
+  }
+}
+
+/**
+ * Thrown when the hub answers a module-op with a non-2xx status. Carries the
+ * HTTP status + the parsed `{ error, error_description }` body so the CLI can
+ * render the hub's own message (e.g. `not_installed`, `insufficient_scope`).
+ */
+export class ModuleOpHttpError extends Error {
+  override name = "ModuleOpHttpError";
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string, description: string) {
+    super(`${code}: ${description}`);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Thrown when an async operation reaches `failed`, or polling times out. */
+export class ModuleOpFailedError extends Error {
+  override name = "ModuleOpFailedError";
+}
+
+/** Terminal shape returned to the caller — the hub's response body. */
+export interface ModuleOpResult {
+  /** HTTP status of the initiating POST (200 sync, 202 async). */
+  readonly status: number;
+  /** Parsed JSON body. For async ops, the terminal operation record. */
+  readonly body: unknown;
+  /** Operation id when the op was async (202); undefined for sync ops. */
+  readonly operationId?: string;
+}
+
+export interface DriveModuleOpDeps {
+  /** Open hub DB handle — used to validate / auto-rotate the operator token. */
+  readonly db: Database;
+  /** Hub issuer (origin) the operator token's `iss` is validated against. */
+  readonly issuer: string;
+  /** Loopback hub base URL. Defaults to {@link DEFAULT_HUB_BASE_URL}. */
+  readonly baseUrl?: string;
+  /** configDir override (where operator.token lives). Defaults to `configDir()`. */
+  readonly configDir?: string;
+  /** Optional JSON body for the POST (e.g. `{ channel }` on install/upgrade). */
+  readonly body?: unknown;
+  /**
+   * fetch seam. Production passes the global `fetch`; tests inject a fake that
+   * asserts the Authorization header + returns canned responses without a
+   * real socket.
+   */
+  readonly fetch?: typeof fetch;
+  /** Clock seam for the operator-token rotation check. */
+  readonly now?: () => Date;
+  /** Sleep seam for the async-op poll loop. Tests stub to advance instantly. */
+  readonly sleep?: (ms: number) => Promise<void>;
+  /** Poll interval for async ops, ms. Default 1000. */
+  readonly pollIntervalMs?: number;
+  /** Poll ceiling for async ops, ms. Default 120000. */
+  readonly pollTimeoutMs?: number;
+  /**
+   * Per-request ceiling for the {@link fetchModuleStates} `GET /api/modules` read,
+   * ms. Default {@link DEFAULT_STATES_FETCH_TIMEOUT_MS} (3000). Bounds `status`
+   * against a wedged hub handler; tests inject a short value to exercise the
+   * timeout-degrade path without a real wall-clock wait.
+   */
+  readonly statesFetchTimeoutMs?: number;
+}
+
+/**
+ * Read the operator token (auto-rotating if near expiry) and return the bearer
+ * to present onward. Throws {@link NoOperatorTokenError} when none is on disk,
+ * and re-throws {@link OperatorTokenExpiredError} unchanged (its message is
+ * already the actionable "run rotate-operator" shape).
+ */
+export async function resolveOperatorBearer(deps: DriveModuleOpDeps): Promise<string> {
+  const used = await useOperatorTokenWithAutoRotate(deps.db, {
+    issuer: deps.issuer,
+    ...(deps.configDir !== undefined ? { configDir: deps.configDir } : {}),
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+  if (!used) throw new NoOperatorTokenError();
+  return used.token;
+}
+
+/**
+ * Drive a module-op end-to-end: read the operator token, POST it as Bearer to
+ * the loopback hub, and (for async ops that return 202 + operation_id) poll
+ * `GET /api/modules/operations/:id` to a terminal state.
+ *
+ * Throws:
+ *   - {@link NoOperatorTokenError} — no operator.token on disk.
+ *   - {@link OperatorTokenExpiredError} — token fully expired (actionable msg).
+ *   - {@link ModuleOpHttpError} — hub answered non-2xx (carries status + code).
+ *   - {@link ModuleOpFailedError} — async op reached `failed`, or poll timed out.
+ */
+export async function driveModuleOp(
+  short: string,
+  op: ModuleOp,
+  deps: DriveModuleOpDeps,
+): Promise<ModuleOpResult> {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+
+  const bearer = await resolveOperatorBearer(deps);
+
+  const headers: Record<string, string> = { authorization: `Bearer ${bearer}` };
+  const init: RequestInit = { method: "POST", headers };
+  if (deps.body !== undefined) {
+    headers["content-type"] = "application/json";
+    init.body = JSON.stringify(deps.body);
+  }
+
+  const res = await doFetch(`${baseUrl}/api/modules/${short}/${op}`, init);
+  const body = await parseJsonSafe(res);
+
+  if (res.status < 200 || res.status >= 300) {
+    const { error, error_description } = asErrorBody(body);
+    throw new ModuleOpHttpError(res.status, error, error_description);
+  }
+
+  // Async op (install / upgrade): 202 + { operation_id } → poll to terminal.
+  if (res.status === 202) {
+    const operationId = extractOperationId(body);
+    if (!operationId) {
+      // 202 means "accepted, poll for completion" — but with no operation_id
+      // there's nothing to poll. Silently returning the 202 would strand the
+      // caller on an incomplete op; surface it as a hard failure instead.
+      throw new ModuleOpFailedError("hub returned 202 but no operation_id in body");
+    }
+    const terminal = await pollOperation(operationId, bearer, baseUrl, doFetch, deps);
+    return { status: res.status, body: terminal, operationId };
+  }
+
+  // Sync op (start / stop / restart / uninstall) — body is the final state.
+  return { status: res.status, body };
+}
+
+/**
+ * Poll `GET /api/modules/operations/:id` until `succeeded` / `failed` or the
+ * timeout elapses. Returns the terminal operation record on success; throws
+ * {@link ModuleOpFailedError} on `failed` or timeout, {@link ModuleOpHttpError}
+ * on a non-2xx poll response.
+ */
+async function pollOperation(
+  operationId: string,
+  bearer: string,
+  baseUrl: string,
+  doFetch: typeof fetch,
+  deps: DriveModuleOpDeps,
+): Promise<unknown> {
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const intervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = deps.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+  const now = deps.now ?? (() => new Date());
+  const deadline = now().getTime() + timeoutMs;
+  const url = `${baseUrl}/api/modules/operations/${operationId}`;
+
+  while (true) {
+    const res = await doFetch(url, {
+      method: "GET",
+      headers: { authorization: `Bearer ${bearer}` },
+    });
+    const body = await parseJsonSafe(res);
+    if (res.status < 200 || res.status >= 300) {
+      const { error, error_description } = asErrorBody(body);
+      throw new ModuleOpHttpError(res.status, error, error_description);
+    }
+    const status = extractOpStatus(body);
+    if (status === "succeeded") return body;
+    if (status === "failed") {
+      const errMsg = extractOpError(body) ?? "operation failed";
+      throw new ModuleOpFailedError(errMsg);
+    }
+    if (now().getTime() >= deadline) {
+      throw new ModuleOpFailedError(
+        `operation ${operationId} did not complete within ${timeoutMs}ms (last status: ${status ?? "unknown"})`,
+      );
+    }
+    await sleep(intervalMs);
+  }
+}
+
+/** Terminal shape returned by {@link fetchModuleLogs}. */
+export interface ModuleLogsResult {
+  /** The short name the logs belong to. */
+  readonly short: string;
+  /** Buffered lines, oldest-first (each includes its trailing newline). */
+  readonly lines: string[];
+  /** The same lines joined — the tail-blob shape `parachute logs` will print. */
+  readonly text: string;
+}
+
+/**
+ * Read a supervised module's recent output from the hub's per-module ring
+ * buffer (`GET /api/modules/:short/logs`, §6.5). Additive — this does NOT wire
+ * into the `parachute logs` CLI command (that cutover is Phase 3); it's the
+ * transport+credential seam Phase 3 will call.
+ *
+ * Reuses the same operator.token→Bearer path as {@link driveModuleOp} (read,
+ * never mint). The buffer replay includes the boot/crash lines that preceded
+ * the call — the must-have that a connect-time stream would miss.
+ *
+ * Throws:
+ *   - {@link NoOperatorTokenError} — no operator.token on disk.
+ *   - {@link OperatorTokenExpiredError} — token fully expired (actionable msg).
+ *   - {@link ModuleOpHttpError} — hub answered non-2xx (e.g. `not_supervised`).
+ */
+export async function fetchModuleLogs(
+  short: string,
+  deps: DriveModuleOpDeps,
+): Promise<ModuleLogsResult> {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+  const bearer = await resolveOperatorBearer(deps);
+
+  const res = await doFetch(`${baseUrl}/api/modules/${short}/logs`, {
+    method: "GET",
+    headers: { authorization: `Bearer ${bearer}` },
+  });
+  const body = await parseJsonSafe(res);
+  if (res.status < 200 || res.status >= 300) {
+    const { error, error_description } = asErrorBody(body);
+    throw new ModuleOpHttpError(res.status, error, error_description);
+  }
+  const b = (body ?? {}) as { lines?: unknown; text?: unknown };
+  const lines = Array.isArray(b.lines)
+    ? b.lines.filter((l): l is string => typeof l === "string")
+    : [];
+  const text = typeof b.text === "string" ? b.text : lines.join("");
+  return { short, lines, text };
+}
+
+/**
+ * One module's run-state as read from `GET /api/modules` — the subset
+ * `parachute status` needs to render a module row from the RUNNING supervisor
+ * (design §6.4 module rows). Snake-case mirrors the wire shape (`api-modules.ts`
+ * `ModuleWireShape`); we keep only the supervisor-derived fields here.
+ */
+export interface ModuleStateSnapshot {
+  readonly short: string;
+  readonly installed: boolean;
+  readonly installed_version: string | null;
+  /**
+   * Supervisor run-status (`running` / `stopped` / `crashed` / `starting` /
+   * `restarting`), or null when the module isn't tracked by the supervisor
+   * (e.g. never booted, skipped at boot, or no supervisor on this hub).
+   */
+  readonly supervisor_status: string | null;
+  readonly pid: number | null;
+  /**
+   * Structured start-error the supervisor recorded (missing-dependency /
+   * started-but-unbound). Passed through verbatim so `status` can render the
+   * SAME friendly missing-dependency note the detached path shows (#188).
+   */
+  readonly supervisor_start_error: unknown | null;
+}
+
+/** Terminal shape returned by {@link fetchModuleStates}. */
+export interface ModuleStatesResult {
+  /** Whether the running hub has a supervisor wired in (`supervisor_available`). */
+  readonly supervisorAvailable: boolean;
+  /** Per-module supervisor snapshots, keyed by short name in array order. */
+  readonly modules: ModuleStateSnapshot[];
+}
+
+/**
+ * Read the RUNNING hub's per-module supervisor states via `GET /api/modules`
+ * (design §6.4 module rows). The operator token's `admin` scope-set carries
+ * `parachute:host:auth` (the scope `/api/modules` gates on), so the same
+ * read-never-mint operator-token→Bearer path {@link driveModuleOp} uses
+ * authenticates this read.
+ *
+ * Used by `parachute status` on a UNIT-MANAGED box to source module rows from
+ * the live supervisor instead of pidfiles. It is read-only and BOUNDED: the
+ * single `GET /api/modules` carries an `AbortSignal.timeout` (default
+ * {@link DEFAULT_STATES_FETCH_TIMEOUT_MS}) so a hub that accepts the TCP
+ * connection but never answers (wedged request handler) can't hang `status` —
+ * the preceding `/health` probe is bounded too, but this read needs its own
+ * ceiling. The CALLER is responsible for degrading gracefully (hub down → don't
+ * call this; no token → catch {@link NoOperatorTokenError}) so `status` never
+ * hangs/crashes.
+ *
+ * Throws (all caught + degraded to a "couldn't read live module state" note by
+ * the `status` caller — see `buildSupervisorRows`):
+ *   - {@link NoOperatorTokenError} — no operator.token on disk.
+ *   - {@link OperatorTokenExpiredError} — token fully expired (actionable msg).
+ *   - {@link ModuleOpHttpError} — hub answered non-2xx, OR the bounded fetch
+ *     timed out / aborted (surfaced as a synthetic `request_timeout` so the
+ *     caller degrades with a message via its existing non-2xx catch, exactly as
+ *     it does for a real HTTP error — never a hang).
+ */
+export async function fetchModuleStates(deps: DriveModuleOpDeps): Promise<ModuleStatesResult> {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+  const timeoutMs = deps.statesFetchTimeoutMs ?? DEFAULT_STATES_FETCH_TIMEOUT_MS;
+  const bearer = await resolveOperatorBearer(deps);
+
+  let res: Response;
+  try {
+    res = await doFetch(`${baseUrl}/api/modules`, {
+      method: "GET",
+      // `/api/modules` parses the scheme-cased `Bearer ` prefix; match it exactly.
+      headers: { authorization: `Bearer ${bearer}` },
+      // Bound the read so a wedged hub handler degrades `status` rather than
+      // hanging it. AbortSignal.timeout fires `AbortError` once the ceiling
+      // elapses (or the fetch errors for another transport reason).
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    // Timeout/abort or transport failure → re-shape as a ModuleOpHttpError so the
+    // `status` caller degrades through the SAME non-2xx catch it uses for an HTTP
+    // error (a "couldn't read live module state" note + exit 0), never hangs.
+    const aborted =
+      err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+    const description = aborted
+      ? `module-states read timed out after ${timeoutMs}ms`
+      : `module-states read failed (${err instanceof Error ? err.message : String(err)})`;
+    throw new ModuleOpHttpError(0, "request_timeout", description);
+  }
+  const body = await parseJsonSafe(res);
+  if (res.status < 200 || res.status >= 300) {
+    const { error, error_description } = asErrorBody(body);
+    throw new ModuleOpHttpError(res.status, error, error_description);
+  }
+  const b = (body ?? {}) as { modules?: 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 };
+}
+
+async function parseJsonSafe(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function asErrorBody(body: unknown): { error: string; error_description: string } {
+  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";
+    return { error, error_description };
+  }
+  return { error: "error", error_description: "request failed" };
+}
+
+function extractOperationId(body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const id = (body as Record<string, unknown>).operation_id;
+    if (typeof id === "string" && id.length > 0) return id;
+  }
+  return undefined;
+}
+
+function extractOpStatus(body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const s = (body as Record<string, unknown>).status;
+    if (typeof s === "string") return s;
+  }
+  return undefined;
+}
+
+function extractOpError(body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const e = (body as Record<string, unknown>).error;
+    if (typeof e === "string" && e.length > 0) return e;
+  }
+  return undefined;
+}
+
+// Re-export so CLI callers can catch the expired-token case without a second
+// import from operator-token.ts.
+export { OperatorTokenExpiredError };