@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/hub-upgrade-helper.ts

@@ -0,0 +1,306 @@
+#!/usr/bin/env bun
+/**
+ * The detached one-shot hub-upgrade helper (design 2026-06-01 §5.3 / D4).
+ *
+ * ── WHY A SEPARATE, DETACHED PROCESS ───────────────────────────────────────
+ *
+ * `POST /api/hub/upgrade` can't rewrite + restart the hub from inside the
+ * request handler: restarting the hub kills the very process serving the
+ * request, so the response would die with the old binary before it could
+ * report success. The resolution (§5.3): the endpoint spawns THIS helper with
+ * `detached: true` + `proc.unref()` — the ONE legitimate detached process in
+ * the unified model, *because it must outlive the hub it's upgrading*. The
+ * helper owns the restart; the request handler returns 202 immediately.
+ *
+ * Detached + unref'd means: no controlling terminal tie, its own process
+ * group, and the parent (hub) exiting does NOT deliver SIGHUP/SIGTERM to it.
+ * So when the helper later tears the hub down, it keeps running to completion.
+ *
+ * ── WHAT IT DOES ───────────────────────────────────────────────────────────
+ *
+ *   1. Mark the on-disk status file `running` (the SPA polls it — it's a FILE,
+ *      not the in-memory ops registry, precisely because the hub goes down
+ *      mid-upgrade; see hub-upgrade-status.ts).
+ *   2. Rewrite the hub binary — REUSES `upgrade("hub", …)` from commands/
+ *      upgrade.ts (the channel-aware `bun add -g @openparachute/hub@<channel>`
+ *      / linked git-pull + downgrade guard). No duplicated rewrite logic.
+ *   3. Trigger the platform-appropriate restart:
+ *      - **unit-managed (VM/Mac)** → `restartHubUnit` (systemctl restart /
+ *        launchctl kickstart -k). The manager tears the old hub down, starts
+ *        the new binary, which re-boots every module from services.json.
+ *      - **container (no unit manager)** → the runtime re-runs CMD on the
+ *        hub's exit, so the helper sends the old hub a graceful SIGTERM (the
+ *        `serve` loop's SIGTERM handler stops children + the server cleanly,
+ *        then the process exits → the runtime brings it back on the rewritten
+ *        binary). The hub PID is passed in via `--hub-pid`.
+ *
+ * The `upgrade("hub", …)` call ALSO does the unit restart itself on a
+ * unit-managed box (its Phase-4 dual-dispatch — `supervisor: {}` opts into the
+ * `restartHubUnit` arm). So on VM/Mac the helper's rewrite step already
+ * restarts the unit; the helper does NOT double-restart. On a container,
+ * `upgrade` finds no unit (its restart arm degrades to the no-unit fallback,
+ * which is a detached lifecycle restart we DON'T want here) — so the helper
+ * passes `restartFn: noop` to upgrade and owns the container restart itself
+ * via the SIGTERM path. This keeps the restart authority unambiguous per
+ * platform.
+ *
+ * ── TESTABILITY ────────────────────────────────────────────────────────────
+ *
+ * `runHubUpgradeHelper` is the pure, injectable core. Every side effect — the
+ * status writes, the `upgrade()` call, the unit restart, the container exit
+ * signal — is a seam, so the rewrite-then-restart sequence + the container
+ * graceful-exit path are unit-tested with NO real `bun add -g`, NO real
+ * systemctl, and NO real process signal. Only the thin argv-parsing `main()`
+ * at the bottom touches the real OS, and it's only reached when this file is
+ * the entrypoint (`import.meta.main`).
+ */
+
+import { type UpgradeOpts, upgrade as realUpgrade } from "./commands/upgrade.ts";
+import { CONFIG_DIR } from "./config.ts";
+import {
+  type HubUnitDeps,
+  type HubUnitManagerOpResult,
+  defaultHubUnitDeps,
+  isHubUnitInstalled,
+  restartHubUnit as realRestartHubUnit,
+} from "./hub-unit.ts";
+import {
+  type HubUpgradeStatus,
+  appendHubUpgradeStatus,
+  readHubUpgradeStatus,
+} from "./hub-upgrade-status.ts";
+
+export interface HubUpgradeHelperArgs {
+  /** Operation id (matches the status file's `operation_id`). */
+  operationId: string;
+  /** Closed-enum channel (validated by the endpoint before spawn). */
+  channel: "rc" | "latest";
+  /** PARACHUTE_HOME (where the status file + services.json live). */
+  configDir: string;
+  /**
+   * The PID of the hub process to gracefully terminate on the container path.
+   * Undefined on the unit-managed path (the manager owns the restart there).
+   */
+  hubPid?: number;
+}
+
+/** Injectable side-effect seams (production wires the real impls). */
+export interface HubUpgradeHelperDeps {
+  /** Rewrite the hub binary. Production proxies to `commands/upgrade.ts`. */
+  upgrade?: (svc: string, opts: UpgradeOpts) => Promise<number>;
+  /** Is a hub unit installed? (Decides unit-managed vs container restart.) */
+  isHubUnitInstalled?: (deps: HubUnitDeps) => boolean;
+  /** Restart the hub unit (unit-managed path). */
+  restartHubUnit?: (deps: HubUnitDeps) => HubUnitManagerOpResult;
+  /** Deps for the unit probes/ops. */
+  hubUnitDeps?: HubUnitDeps;
+  /**
+   * Send the graceful-exit signal to the hub (container path). Production
+   * `process.kill(pid, "SIGTERM")`; tests record the call.
+   */
+  signalHub?: (pid: number, signal: NodeJS.Signals) => void;
+  /** Append to the on-disk status file (test seam). */
+  appendStatus?: (
+    configDir: string,
+    operationId: string,
+    patch: Partial<Pick<HubUpgradeStatus, "phase" | "error">>,
+    logLine?: string,
+  ) => void;
+}
+
+/**
+ * The pure helper core: rewrite the hub binary, then trigger the platform
+ * restart. Returns a terminal exit code (0 = restart dispatched / success).
+ * Records progress to the status file throughout.
+ */
+export async function runHubUpgradeHelper(
+  args: HubUpgradeHelperArgs,
+  deps: HubUpgradeHelperDeps = {},
+): Promise<number> {
+  const upgrade = deps.upgrade ?? realUpgrade;
+  const unitInstalledFn = deps.isHubUnitInstalled ?? isHubUnitInstalled;
+  const restartUnit = deps.restartHubUnit ?? realRestartHubUnit;
+  const hubUnitDeps = deps.hubUnitDeps ?? defaultHubUnitDeps;
+  const signalHub = deps.signalHub ?? ((pid, signal) => process.kill(pid, signal));
+  const append = deps.appendStatus ?? appendHubUpgradeStatus;
+  const { configDir, operationId } = args;
+
+  append(
+    configDir,
+    operationId,
+    { phase: "running" },
+    `hub-upgrade helper started (op ${operationId})`,
+  );
+
+  const unitManaged = unitInstalledFn(hubUnitDeps);
+
+  // ── Rewrite the binary ───────────────────────────────────────────────────
+  // REUSE commands/upgrade.ts for the channel-aware rewrite (bun add -g
+  // @openparachute/hub@<channel> / linked git-pull + downgrade guard) — but
+  // REWRITE ONLY: suppress upgrade's own restart with a no-op `restartFn`. The
+  // HELPER owns the restart explicitly below (the spec's "the helper owns the
+  // restart"), so the restart authority is unambiguous per platform rather than
+  // buried in upgrade.ts's dual-dispatch. `supervisor` is intentionally omitted
+  // so upgrade takes its detached arm with our no-op restartFn (a pure rewrite,
+  // no lifecycle restart fired).
+  const upgradeOpts: UpgradeOpts = {
+    channel: args.channel,
+    configDir,
+    restartFn: async () => 0,
+    log: (line) => append(configDir, operationId, {}, line),
+  };
+
+  let code: number;
+  try {
+    code = await upgrade("hub", upgradeOpts);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    append(configDir, operationId, { phase: "failed", error: msg }, `hub-upgrade failed: ${msg}`);
+    return 1;
+  }
+
+  if (code !== 0) {
+    append(
+      configDir,
+      operationId,
+      { phase: "failed", error: `upgrade exited ${code}` },
+      `hub-upgrade rewrite failed (exit ${code}) — binary NOT restarted`,
+    );
+    return code;
+  }
+
+  // ── Restart (helper-owned) ───────────────────────────────────────────────
+  if (unitManaged) {
+    // VM/Mac: restart the hub UNIT via the platform manager (systemctl restart
+    // / launchctl kickstart -k). The manager tears the old hub down (children
+    // die), starts the new binary, which re-boots every module from
+    // services.json. NEVER a PID signal — launchd KeepAlive / systemd
+    // Restart=always would fight it (R17). We mark `restarting`; we canNOT
+    // reliably write `succeeded` — the new hub's version is the SPA's success
+    // signal (it polls /health + /api/hub), not our file.
+    const res = restartUnit(hubUnitDeps);
+    for (const m of res.messages) append(configDir, operationId, {}, m);
+    if (res.outcome !== "ok") {
+      append(
+        configDir,
+        operationId,
+        { phase: "failed", error: `hub unit restart ${res.outcome}` },
+        `hub binary rewritten but the unit restart ${res.outcome} — restart it manually`,
+      );
+      return 1;
+    }
+    append(
+      configDir,
+      operationId,
+      { phase: "restarting" },
+      "hub unit restarted via the service manager — the SPA polls /health + version for the new binary",
+    );
+    return 0;
+  }
+
+  // Container path: the rewrite landed on the persistent disk (the endpoint
+  // already gated on mode === "in-place"; an image-pinned hub never spawns a
+  // helper). Now signal the hub to exit gracefully so the container runtime
+  // re-runs CMD (`serve`) on the rewritten binary. The hub's SIGTERM handler
+  // (cli.ts serve case) stops supervised children + the server cleanly, then
+  // the process exits and the runtime brings it back.
+  append(
+    configDir,
+    operationId,
+    { phase: "restarting" },
+    "container: signalling the hub to exit gracefully so the runtime restarts it on the new binary",
+  );
+  if (args.hubPid !== undefined && Number.isFinite(args.hubPid) && args.hubPid > 0) {
+    try {
+      signalHub(args.hubPid, "SIGTERM");
+    } catch (err) {
+      // The hub may have already exited (a racing restart). Not fatal — the
+      // rewrite is done; the runtime will bring it back on the new binary
+      // regardless. Record + succeed.
+      const msg = err instanceof Error ? err.message : String(err);
+      append(configDir, operationId, {}, `hub graceful-exit signal noted as already-gone (${msg})`);
+    }
+  } else {
+    append(
+      configDir,
+      operationId,
+      {},
+      "no hub pid provided — relying on the platform runtime's own restart to pick up the new binary",
+    );
+  }
+  return 0;
+}
+
+// ── Entrypoint (only runs when invoked directly as `bun hub-upgrade-helper.ts`) ──
+
+function parseArgs(argv: string[]): HubUpgradeHelperArgs | { error: string } {
+  let operationId: string | undefined;
+  let channel: string | undefined;
+  let configDir: string | undefined;
+  let hubPid: number | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    switch (arg) {
+      // Each value-bearing flag guards `next !== undefined` so a truncated argv
+      // (flag last in argv, no value) leaves the value unset — surfaced as a
+      // clear "required" error below — rather than silently consuming the next
+      // flag as its value.
+      case "--op":
+        if (next !== undefined) operationId = next;
+        i++;
+        break;
+      case "--channel":
+        if (next !== undefined) channel = next;
+        i++;
+        break;
+      case "--config-dir":
+        if (next !== undefined) configDir = next;
+        i++;
+        break;
+      case "--hub-pid":
+        if (next !== undefined) hubPid = Number(next);
+        i++;
+        break;
+      default:
+        return { error: `unexpected argument "${arg}"` };
+    }
+  }
+  if (!operationId) return { error: "--op <id> is required" };
+  if (channel !== "rc" && channel !== "latest") {
+    return { error: `--channel must be "rc" or "latest" (got "${channel ?? ""}")` };
+  }
+  const resolved: HubUpgradeHelperArgs = {
+    operationId,
+    channel,
+    configDir: configDir ?? CONFIG_DIR,
+  };
+  if (hubPid !== undefined && Number.isFinite(hubPid)) resolved.hubPid = hubPid;
+  return resolved;
+}
+
+async function main(): Promise<number> {
+  const parsed = parseArgs(process.argv.slice(2));
+  if ("error" in parsed) {
+    console.error(`hub-upgrade-helper: ${parsed.error}`);
+    return 2;
+  }
+  // If the endpoint never seeded the status file (it always should), bail
+  // visibly rather than silently no-op'ing.
+  if (!readHubUpgradeStatus(parsed.configDir)) {
+    console.error(
+      `hub-upgrade-helper: no status file for op ${parsed.operationId} under ${parsed.configDir}`,
+    );
+    return 2;
+  }
+  return await runHubUpgradeHelper(parsed);
+}
+
+if (import.meta.main) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error("hub-upgrade-helper: fatal", err);
+      process.exit(1);
+    });
+}

package/src/hub-upgrade-mode.ts

@@ -0,0 +1,209 @@
+/**
+ * In-place-vs-redeploy detection for `POST /api/hub/upgrade` (design
+ * 2026-06-01 §5.3 — the OPEN implementation detail flagged for D4).
+ *
+ * The hub-upgrade endpoint must decide, BEFORE it spawns the detached helper,
+ * whether an on-disk binary rewrite (`bun add -g @openparachute/hub@<channel>`
+ * / a linked git-pull) will actually PERSIST across the next restart:
+ *
+ *   - **in-place** — the hub binary lives on a writable, persistent location
+ *     (a bun-linked checkout, or a `bun add -g` install under a $BUN_INSTALL
+ *     that survives restart). A rewrite + restart genuinely upgrades the hub.
+ *
+ *   - **redeploy-required** — the hub binary is baked into a container image
+ *     (Render/Fly image-pinned). `bun add -g` would write to the image's
+ *     ephemeral layer and be LOST on the next container restart, so the rewrite
+ *     is a misleading no-op. The honest path is a platform redeploy from the
+ *     operator's dashboard, NOT a false "upgraded."
+ *
+ * ── THE HEURISTIC (conservative; flagged for review) ───────────────────────
+ *
+ * Signals, in priority order:
+ *
+ *   1. **bun-linked** (`detectHubInstallSource` → `bun-linked`): the hub runs
+ *      from a git checkout on disk. A `git pull` in that checkout is always
+ *      persistent (the checkout is the operator's own filesystem, not an image
+ *      layer). → **in-place**. This is Aaron's dev box + every VM/Mac that
+ *      bun-linked the hub.
+ *
+ *   2. **container, BUN_INSTALL on the persistent disk**: a container (the
+ *      Render Blueprint pins `PARACHUTE_HOME=/parachute`) whose `$BUN_INSTALL`
+ *      points INSIDE the persistent mount (`/parachute/...` — the same place
+ *      runtime module installs land via `/api/modules/:short/install`). A
+ *      `bun add -g` there writes to the mounted volume, which survives a
+ *      container restart. → **in-place**. This is the "hub installed to the
+ *      persistent disk" arm §5.3 calls out.
+ *
+ *   3. **container, BUN_INSTALL NOT on the persistent disk** (or unset): the
+ *      hub is image-pinned — `bun add -g` writes to the ephemeral image layer
+ *      and is lost on restart. → **redeploy-required**. This is the default
+ *      Render/Fly image shape today (the Dockerfile `bun add`s the hub into the
+ *      image; $BUN_INSTALL defaults to `/root/.bun`, not the mount).
+ *
+ *   4. **npm, non-container**: a `bun add -g` install on a VM/Mac (not a
+ *      container). The global bun prefix is on the operator's own writable
+ *      filesystem → persistent. → **in-place**.
+ *
+ *   5. **unknown / anything else**: we couldn't classify the install source.
+ *      → **redeploy-required** (the honest fallback — §5.3: "When uncertain,
+ *      prefer redeploy-required over a silent no-op"). The SPA then tells the
+ *      operator to redeploy rather than promising an upgrade that may evaporate.
+ *
+ * ── FALSE-POSITIVE / FALSE-NEGATIVE RISK (for the reviewer) ─────────────────
+ *
+ *   - **False "in-place" (the dangerous direction)** would tell the operator
+ *     "upgraded" while the rewrite silently evaporates on the next restart.
+ *     The only path that risks this is signal #2: a container whose
+ *     `$BUN_INSTALL` is under the persistent mount but where the operator
+ *     mounted the disk read-only, or where the bun cache (not the install) is
+ *     what's on the mount. We mitigate by requiring `$BUN_INSTALL` to be a
+ *     descendant of the persistent-home prefix — the strictest signal available
+ *     without probing writability (which we can't do reliably from the request
+ *     handler before spawning the helper). A residual risk remains; see the
+ *     note in `detectHubUpgradeMode` on tightening this with a write-probe in
+ *     the helper if it proves wrong in the field.
+ *
+ *   - **False "redeploy-required" (the safe direction)** merely tells the
+ *     operator to redeploy when an in-place upgrade would have worked — annoying
+ *     but never destructive. Signals #3/#5 deliberately err here.
+ *
+ * Pure + injectable: no I/O beyond the (already-injectable) install-source
+ * detection. The env + srcDir are passed in so tests drive every branch.
+ */
+
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTAINER_HOME } from "./hub-control.ts";
+import {
+  type DetectInstallSourceDeps,
+  type InstallSource,
+  detectHubInstallSource,
+} from "./install-source.ts";
+
+/** The two upgrade modes the SPA branches on. */
+export type HubUpgradeMode = "in-place" | "redeploy-required";
+
+export interface DetectHubUpgradeModeArgs {
+  /** Override `process.env` lookups (test seam). */
+  env?: Record<string, string | undefined>;
+  /**
+   * Directory used to locate the hub's package.json + classify install source.
+   * Defaults to the running source dir. Test seam.
+   */
+  hubSrcDir?: string;
+  /** Pass-through deps for `detectHubInstallSource` (test seam). */
+  installSourceDeps?: DetectInstallSourceDeps;
+  /**
+   * Pre-classified install source — lets a caller that already ran
+   * `detectHubInstallSource` (e.g. the `/api/hub` handler) avoid a second
+   * filesystem walk. When set, `hubSrcDir`/`installSourceDeps` are ignored.
+   */
+  source?: InstallSource;
+}
+
+export interface HubUpgradeModeResult {
+  mode: HubUpgradeMode;
+  /** The classified install source (surfaced for diagnostics + the SPA copy). */
+  source: InstallSource["kind"] | "container";
+  /** Short human-readable reason — surfaced in the 202 body + SPA + tests. */
+  reason: string;
+}
+
+/**
+ * The Render Blueprint pins `PARACHUTE_HOME=/parachute` — the single most
+ * reliable container-mode signal the hub has (mirrors `api-hub.ts`'s
+ * container override; both use the shared `CONTAINER_HOME` constant). Fly uses
+ * the same pin via the shared image.
+ */
+function isContainer(env: Record<string, string | undefined>): boolean {
+  return env.PARACHUTE_HOME === CONTAINER_HOME;
+}
+
+/**
+ * True when `$BUN_INSTALL` is a descendant of the persistent-home prefix —
+ * i.e. `bun add -g` writes land on the mounted volume that survives a
+ * container restart. The persistent home on the Render Blueprint is
+ * `/parachute`; we treat any `$BUN_INSTALL` under it as persistent.
+ *
+ * Strict (descendant-of), not a substring match, so a stray `/parachute` in
+ * an unrelated path component can't false-positive.
+ */
+function bunInstallOnPersistentDisk(env: Record<string, string | undefined>): boolean {
+  const bunInstall = env.BUN_INSTALL;
+  const home = env.PARACHUTE_HOME;
+  if (!bunInstall || !home) return false;
+  if (bunInstall === home) return true;
+  const prefix = home.endsWith("/") ? home : `${home}/`;
+  return bunInstall.startsWith(prefix);
+}
+
+/**
+ * Decide whether the hub is in-place-upgradable (rewrite + restart works) or
+ * image-pinned (redeploy-only). See the module docstring for the full
+ * heuristic + risk analysis.
+ */
+export function detectHubUpgradeMode(args: DetectHubUpgradeModeArgs = {}): HubUpgradeModeResult {
+  const env = args.env ?? process.env;
+  const hubSrcDir = args.hubSrcDir ?? dirname(fileURLToPath(import.meta.url));
+  const source = args.source ?? detectHubInstallSource(hubSrcDir, args.installSourceDeps);
+
+  const container = isContainer(env);
+
+  // Signal 1: bun-linked checkout. A `git pull` in the operator's own checkout
+  // is always persistent — even inside a container the checkout dir is on the
+  // operator's filesystem, not the ephemeral image layer. (In practice a
+  // container runs from /app/src image-pinned, not a checkout — but if it IS a
+  // checkout, in-place is correct.)
+  if (source.kind === "bun-linked") {
+    return {
+      mode: "in-place",
+      source: container ? "container" : "bun-linked",
+      reason: "bun-linked checkout — git pull + restart persists on disk",
+    };
+  }
+
+  if (container) {
+    // Signal 2: container with $BUN_INSTALL on the persistent mount → the
+    // `bun add -g` write survives a container restart.
+    if (bunInstallOnPersistentDisk(env)) {
+      return {
+        mode: "in-place",
+        source: "container",
+        reason:
+          "container with $BUN_INSTALL on the persistent disk — bun add -g persists across restart",
+      };
+    }
+    // Signal 3: container, image-pinned. `bun add -g` writes to the ephemeral
+    // image layer → lost on restart. The honest path is a platform redeploy.
+    //
+    // NOTE (reviewer): we could tighten signal-2 confidence by having the
+    // helper write-probe `$BUN_INSTALL` before committing to the rewrite. We
+    // deliberately do the cheaper env-based classification here and accept
+    // erring toward redeploy-required (the safe direction) when uncertain.
+    return {
+      mode: "redeploy-required",
+      source: "container",
+      reason:
+        "container image-pinned ($BUN_INSTALL not on the persistent disk) — bun add -g would be lost on the next container restart; redeploy from your platform dashboard instead",
+    };
+  }
+
+  // Signal 4: npm install on a VM/Mac (non-container). The global bun prefix is
+  // on the operator's own writable filesystem → persistent.
+  if (source.kind === "npm") {
+    return {
+      mode: "in-place",
+      source: "npm",
+      reason: "npm-installed on a persistent filesystem — bun add -g persists",
+    };
+  }
+
+  // Signal 5: unknown. Honest fallback — prefer redeploy-required over a silent
+  // no-op (§5.3).
+  return {
+    mode: "redeploy-required",
+    source: "unknown",
+    reason:
+      "could not classify the hub install source — redeploy from your platform dashboard to be safe",
+  };
+}

package/src/hub-upgrade-status.ts

@@ -0,0 +1,150 @@
+/**
+ * The on-disk status file for an in-flight `POST /api/hub/upgrade` operation
+ * (design 2026-06-01 §5.3 / D4).
+ *
+ * WHY A FILE, NOT THE IN-MEMORY OPERATIONS REGISTRY: a hub-upgrade tears the
+ * hub DOWN mid-operation (the whole point — the new binary has to take over).
+ * The module-ops `InMemoryOperationsRegistry` is process-local and evaporates
+ * when the hub restarts, so it CANNOT carry hub-upgrade progress across the
+ * restart the SPA is polling through. A JSON file under `PARACHUTE_HOME`
+ * survives the hub bounce: the detached helper writes progress to it while the
+ * old hub is dying, and the NEW hub reads it back to answer
+ * `GET /api/hub/upgrade/status`. (On a container the file lives on the
+ * persistent disk — same place the DB + module installs live.)
+ *
+ * The file is single-slot (one upgrade at a time — there is only one hub). A
+ * stale file from a prior upgrade is simply overwritten when a new one starts.
+ *
+ * Wire shape mirrors the module-ops `Operation` enough that the SPA's polling
+ * code reads familiarly: `status` + `log` + `error` + timestamps, plus the
+ * hub-specific `mode` / `target_version` / `channel` the SPA branches on.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { HubUpgradeMode } from "./hub-upgrade-mode.ts";
+
+/** Phases of a hub-upgrade, polled by the SPA. */
+export type HubUpgradeStatusPhase =
+  /** The endpoint accepted the request + spawned the helper; not started yet. */
+  | "pending"
+  /** The helper is rewriting the binary / about to restart. */
+  | "running"
+  /**
+   * The rewrite + restart were dispatched. The SPA now switches to polling
+   * `/health` + the reported version directly — the helper may not get to
+   * write a terminal state (the hub it would report to is being torn down).
+   */
+  | "restarting"
+  /**
+   * Terminal success. RESERVED / SPA-INFERRED: the helper does NOT write this —
+   * it can't reliably record `succeeded` before the hub bounce tears down the
+   * process. The SPA infers success from `/health` + the reported version
+   * (HubUpgradeCard), not from this phase. Kept in the enum so the SPA success
+   * detection + the 409 in-flight guard's terminal-phase check can reference it.
+   */
+  | "succeeded"
+  /** Terminal failure (rewrite failed, downgrade refused, etc.). */
+  | "failed"
+  /**
+   * The endpoint determined the hub is image-pinned (redeploy-required) and did
+   * NOT spawn a helper — there's no in-place upgrade to run. The SPA shows
+   * "redeploy from your platform dashboard" instead of a progress spinner.
+   */
+  | "redeploy-required";
+
+export interface HubUpgradeStatus {
+  /** Opaque id minted by the endpoint; echoed in the 202 body for polling. */
+  operation_id: string;
+  phase: HubUpgradeStatusPhase;
+  /** In-place vs redeploy-required (the §5.3 detection result). */
+  mode: HubUpgradeMode;
+  /** The version the operator is currently on (read at request time). */
+  current_version: string;
+  /** Best-effort resolved target version (`npm view`), or null if unknown. */
+  target_version: string | null;
+  /** Closed-enum channel the rewrite targets. */
+  channel: "rc" | "latest";
+  /** Sparse progress log, appended by the helper. */
+  log: string[];
+  /** Error message when `phase === "failed"`. */
+  error?: string;
+  started_at: string;
+  finished_at?: string;
+}
+
+/** Path of the single-slot hub-upgrade status file under `configDir`. */
+export function hubUpgradeStatusPath(configDir: string): string {
+  return join(configDir, "hub-upgrade-status.json");
+}
+
+/**
+ * Atomically write the status file (write-temp + rename) so a poll that lands
+ * mid-write never sees a half-serialized JSON. Creates the parent dir if
+ * absent (a never-initialized PARACHUTE_HOME).
+ */
+export function writeHubUpgradeStatus(configDir: string, status: HubUpgradeStatus): void {
+  const path = hubUpgradeStatusPath(configDir);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(status, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/**
+ * Read the current status file, or null when none exists / is unreadable.
+ * Lenient: a malformed file reads as null (the SPA falls back to polling
+ * `/health` directly), never throws.
+ */
+export function readHubUpgradeStatus(configDir: string): HubUpgradeStatus | null {
+  const path = hubUpgradeStatusPath(configDir);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object" && "operation_id" in parsed) {
+      return parsed as HubUpgradeStatus;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append a log line + (optionally) advance the phase, persisting atomically.
+ * Used by the helper to record progress the SPA polls. A missing file (the
+ * endpoint should always seed it first) is a no-op rather than a throw — the
+ * helper's job is the upgrade, not bookkeeping.
+ *
+ * OPERATION GUARD: `operationId` is the op the caller (helper) was spawned
+ * with. The status file is single-slot — a newer `POST /api/hub/upgrade` will
+ * overwrite it with a fresh `operation_id`. A still-running helper from the
+ * SUPERSEDED operation must not clobber the newer operation's status with its
+ * stale progress. So we only write when the on-disk `operation_id` still
+ * matches `operationId`; otherwise the append is a NO-OP (the newer operation
+ * owns the slot now). This makes concurrent-upgrade status-file corruption
+ * impossible from the helper side.
+ */
+export function appendHubUpgradeStatus(
+  configDir: string,
+  operationId: string,
+  patch: Partial<Pick<HubUpgradeStatus, "phase" | "error">>,
+  logLine?: string,
+): void {
+  const current = readHubUpgradeStatus(configDir);
+  if (!current) return;
+  // A newer operation superseded this one — do NOT clobber its status.
+  if (current.operation_id !== operationId) return;
+  const next: HubUpgradeStatus = { ...current };
+  if (patch.phase) next.phase = patch.phase;
+  if (patch.error !== undefined) next.error = patch.error;
+  if (logLine) next.log = [...current.log, logLine];
+  // `succeeded` is reserved/SPA-inferred (see HubUpgradeStatusPhase) — the
+  // helper can't reliably write it before the hub bounce, so in practice only
+  // `failed` reaches this branch. Both terminal phases stamp `finished_at`.
+  if (patch.phase === "succeeded" || patch.phase === "failed") {
+    next.finished_at = new Date().toISOString();
+  }
+  writeHubUpgradeStatus(configDir, next);
+}