@openparachute/hub 0.7.3 → 0.7.4-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3",
+  "version": "0.7.4-rc.2",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/cli.test.ts

@@ -103,6 +103,28 @@ describe("cli", () => {
     expect(code).toBe(1);
     expect(stderr).toMatch(/invalid --hub-origin/);
   });
+
+  // hub#694 bug 2: `init --channel` mirrors `install --channel` — rejected at
+  // the arg layer (exit 1) before any daemon work, so these are hermetic.
+  test("init --channel without a value exits 1 (hub#694)", async () => {
+    const { code, stderr } = await runCli(["init", "--channel"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--channel requires a value/);
+  });
+
+  test("init --channel with an invalid value exits 1 (hub#694)", async () => {
+    const { code, stderr } = await runCli(["init", "--channel", "banana"]);
+    expect(code).toBe(1);
+    expect(stderr).toMatch(/--channel must be "rc" or "latest"/);
+    expect(stderr).toMatch(/banana/);
+  });
+
+  test("init --help documents --channel (hub#694)", async () => {
+    const { code, stdout } = await runCli(["init", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/--channel/);
+    expect(stdout).toMatch(/rc\|latest/);
+  });
 });
 
 describe("cli per-subcommand help", () => {

package/src/__tests__/init.test.ts

@@ -2,7 +2,13 @@ import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { hasNoDisplay, init, looksLikeServer, resolveAdminUrl } from "../commands/init.ts";
+import {
+  hasNoDisplay,
+  init,
+  looksLikeServer,
+  resolveAdminUrl,
+  resolveInitChannel,
+} from "../commands/init.ts";
 import type { ExposeState } from "../expose-state.ts";
 import { writeHubPort } from "../hub-control.ts";
 import { writePid } from "../process-state.ts";
@@ -1865,5 +1871,352 @@ describe("init exposure chain", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// hub#694 — first-run robustness.
+//
+// Bug 1 (the spawn race): the supervisor scans services.json EXACTLY ONCE at
+// hub-unit boot. So the vault module MUST be seeded into services.json BEFORE
+// the hub unit starts (ensureHub) — otherwise the boot scan finds no vault row
+// and vault never spawns until a manual `parachute restart`. These tests pin the
+// ordering: vault-install precedes ensureHub on both the laptop (no --hub-origin)
+// and the DO (--hub-origin) path, and Step-0 origin-persist stays first.
+//
+// Bug 2 (channel): init must install the vault module from the chosen channel
+// (`--channel rc` / PARACHUTE_CHANNEL=rc), not always @latest — otherwise an rc
+// box downgrades vault below the rc-tracking hub.
+// ---------------------------------------------------------------------------
+
+describe("init hub#694 — vault seeded before the supervisor boot scan (bug 1)", () => {
+  test("laptop (no --hub-origin): installs+seeds vault BEFORE ensureHub", async () => {
+    const h = makeHarness();
+    try {
+      const order: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        // The load-bearing assertion: the vault module install (which seeds the
+        // services.json row) MUST happen before the hub unit boots, so the
+        // supervisor's one-time boot scan finds + spawns vault on the first pass.
+        installVaultModuleImpl: async () => {
+          order.push("install-vault");
+          return 0;
+        },
+        ensureHub: async () => {
+          order.push("ensureHub");
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(order).toEqual(["install-vault", "ensureHub"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--hub-origin (DO path): order is set-origin → install vault → ensureHub", async () => {
+    const h = makeHarness();
+    try {
+      const order: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        // hub#693 Step-0 origin persist must remain FIRST (boot issuer + child
+        // env read it); the hub#694 vault seed slots in AFTER it but BEFORE the
+        // hub unit boots, so the freshly-spawned vault comes up with the public
+        // origin in its accepted-iss set AND is present in the boot scan — in one
+        // pass, no restart.
+        setHubOriginImpl: (_dir, origin) => {
+          order.push(`set-origin:${origin}`);
+        },
+        installVaultModuleImpl: async () => {
+          order.push("install-vault");
+          return 0;
+        },
+        ensureHub: async () => {
+          order.push("ensureHub");
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(order).toEqual(["set-origin:https://box.sslip.io", "install-vault", "ensureHub"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("real seed: vault row is in services.json by the time ensureHub runs", async () => {
+    // End-to-end-ish: drive the REAL defaultInstallVaultModule (bun-linked vault
+    // short-circuits the bun-add) and assert the services.json row exists when
+    // ensureHub is invoked — i.e. the boot scan would find it.
+    const h = makeHarness();
+    try {
+      let vaultRowAtEnsure: boolean | undefined;
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        ensureHub: async () => {
+          // At hub-unit-boot time the services.json must already carry vault.
+          const { findService } = await import("../services-manifest.ts");
+          vaultRowAtEnsure = findService("parachute-vault", h.manifestPath) !== undefined;
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        // NOTE: no installVaultModuleImpl override — exercise the real install
+        // so we prove the seed write lands before ensureHub, not just the stub.
+      });
+      expect(code).toBe(0);
+      expect(vaultRowAtEnsure).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("already-seeded vault: install is skipped, ensureHub still runs", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const order: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        installVaultModuleImpl: async () => {
+          order.push("install-vault");
+          return 0;
+        },
+        ensureHub: async () => {
+          order.push("ensureHub");
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      // Vault already present → install short-circuits; only ensureHub fires.
+      expect(order).toEqual(["ensureHub"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("init hub#694 — install channel (bug 2)", () => {
+  test("--channel rc propagates to the vault module install", async () => {
+    const h = makeHarness();
+    try {
+      const channels: (string | undefined)[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        channel: "rc",
+        installVaultModuleImpl: async (_d, _m, channel) => {
+          channels.push(channel);
+          return 0;
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(channels).toEqual(["rc"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("PARACHUTE_CHANNEL=rc env propagates when no --channel flag", async () => {
+    const h = makeHarness();
+    try {
+      const channels: (string | undefined)[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        // No `channel` opt — exercise the env fallback the DO cloud-init script
+        // relies on (it exports PARACHUTE_CHANNEL but passes no --channel flag).
+        env: { PARACHUTE_CHANNEL: "rc" } as NodeJS.ProcessEnv,
+        installVaultModuleImpl: async (_d, _m, channel) => {
+          channels.push(channel);
+          return 0;
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(channels).toEqual(["rc"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("default (no flag, no env): vault install gets undefined → install resolves latest", async () => {
+    const h = makeHarness();
+    try {
+      const channels: (string | undefined)[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        env: {} as NodeJS.ProcessEnv,
+        installVaultModuleImpl: async (_d, _m, channel) => {
+          channels.push(channel);
+          return 0;
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(channels).toEqual([undefined]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--channel flag overrides PARACHUTE_CHANNEL env", async () => {
+    const h = makeHarness();
+    try {
+      const channels: (string | undefined)[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        channel: "latest",
+        env: { PARACHUTE_CHANNEL: "rc" } as NodeJS.ProcessEnv,
+        installVaultModuleImpl: async (_d, _m, channel) => {
+          channels.push(channel);
+          return 0;
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 0, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(channels).toEqual(["latest"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("resolveInitChannel (hub#694 bug 2)", () => {
+  const empty = {} as NodeJS.ProcessEnv;
+  test("explicit rc/latest wins", () => {
+    expect(resolveInitChannel("rc", empty)).toBe("rc");
+    expect(resolveInitChannel("latest", { PARACHUTE_CHANNEL: "rc" } as NodeJS.ProcessEnv)).toBe(
+      "latest",
+    );
+  });
+  test("PARACHUTE_CHANNEL env when no explicit", () => {
+    expect(resolveInitChannel(undefined, { PARACHUTE_CHANNEL: "rc" } as NodeJS.ProcessEnv)).toBe(
+      "rc",
+    );
+  });
+  test("PARACHUTE_INSTALL_CHANNEL env when no explicit + no PARACHUTE_CHANNEL", () => {
+    expect(
+      resolveInitChannel(undefined, { PARACHUTE_INSTALL_CHANNEL: "rc" } as NodeJS.ProcessEnv),
+    ).toBe("rc");
+  });
+  test("PARACHUTE_CHANNEL wins over PARACHUTE_INSTALL_CHANNEL", () => {
+    expect(
+      resolveInitChannel(undefined, {
+        PARACHUTE_CHANNEL: "latest",
+        PARACHUTE_INSTALL_CHANNEL: "rc",
+      } as NodeJS.ProcessEnv),
+    ).toBe("latest");
+  });
+  test("garbage env → undefined (install falls back to latest)", () => {
+    expect(
+      resolveInitChannel(undefined, { PARACHUTE_CHANNEL: "banana" } as NodeJS.ProcessEnv),
+    ).toBe(undefined);
+  });
+  test("nothing set → undefined", () => {
+    expect(resolveInitChannel(undefined, empty)).toBe(undefined);
+  });
+});
+
 // Type alias used only inside this test file for the heuristic test.
 type ExposeChoice = "none" | "tailnet" | "cloudflare";

package/src/__tests__/status-supervisor.test.ts

@@ -80,6 +80,12 @@ interface SupervisorArmOpts {
   hubHealthy: boolean;
   moduleStates?: ModuleStatesResult;
   fetchModuleStatesImpl?: () => Promise<ModuleStatesResult>;
+  /**
+   * Inject the unauthenticated module-liveness probe (#700). Defaults to "every
+   * module is down" so the degraded-read tests don't accidentally hit the
+   * network; specific tests override to mark a module live.
+   */
+  probeModuleHealth?: (port: number, health: string) => Promise<boolean>;
 }
 
 /** Drive `status` through the supervisor arm with fully stubbed seams. */
@@ -96,6 +102,7 @@ function supervisorOpts(configDir: string, path: string, o: SupervisorArmOpts) {
       fetchModuleStates:
         o.fetchModuleStatesImpl ??
         (async () => o.moduleStates ?? { supervisorAvailable: true, modules: [] }),
+      probeModuleHealth: o.probeModuleHealth ?? (async () => false),
       openDb: fakeOpenDb as unknown as (configDir: string) => import("bun:sqlite").Database,
     },
   };
@@ -377,7 +384,7 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
     }
   });
 
-  test("no operator token → graceful degrade (manifest rows + actionable hint), no 401 crash", async () => {
+  test("no operator token (fresh box, no admin) → note targets set-password, NOT rotate-operator (#700)", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {
       upsertService(
@@ -392,15 +399,121 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
           fetchModuleStatesImpl: async () => {
             throw new NoOperatorTokenError();
           },
+          // No probe-live module here → row stays inactive (exit 0).
+          probeModuleHealth: async () => false,
         }),
         print: (l) => lines.push(l),
       });
       // We could not read run-state, but didn't crash. The module row falls back
-      // to `inactive` (no supervisor snapshot) — a stopped row is exit 0.
+      // to `inactive` (no supervisor snapshot, probe down) — a stopped row is exit 0.
       expect(code).toBe(0);
       const out = lines.join("\n");
       expect(out).toMatch(/parachute-vault/);
-      expect(out).toMatch(/run `parachute auth rotate-operator`/);
+      // #700: a fresh box has no admin, so rotate-operator would itself error.
+      // The note must point at set-password and must NOT be the bare
+      // rotate-operator guidance.
+      expect(out).toMatch(/parachute auth set-password/);
+      expect(out).not.toMatch(/run `parachute auth rotate-operator` to mint an operator token/);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no operator token + module answers /health probe → LIVE (active), not inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const probed: Array<{ port: number; health: string }> = [];
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          // vault is genuinely up — its /health answers (2xx or 401 → live).
+          probeModuleHealth: async (port, health) => {
+            probed.push({ port, health });
+            return true;
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      // The probe targeted the module's own port + health path from the manifest.
+      expect(probed).toEqual([{ port: 1940, health: "/health" }]);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\bactive\b/);
+      expect(vaultLine).not.toMatch(/\binactive\b/);
+      const out = lines.join("\n");
+      // The row is labelled as probe-derived so the operator knows it's thin.
+      expect(out).toMatch(/live via unauthenticated health probe/);
+      // The degraded-read hint still appears (why PID/uptime are absent).
+      expect(out).toMatch(/parachute auth set-password/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("degraded read + module probe FAILS → row stays inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          probeModuleHealth: async () => false,
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
+      const out = lines.join("\n");
+      expect(out).not.toMatch(/live via unauthenticated health probe/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a throwing module probe never crashes status — row degrades to inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          probeModuleHealth: async () => {
+            throw new Error("probe exploded");
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
     } finally {
       cleanup();
     }
@@ -433,6 +546,42 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
     }
   });
 
+  test("expired operator token + module answers /health probe → LIVE (active) (#700)", async () => {
+    // Symmetry with the no-token case: the unauthenticated probe fallback fires
+    // on ANY degraded read where the hub is up + run-state is missing, so an
+    // expired-token box still shows a genuinely-serving module as `active`.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new OperatorTokenExpiredError(
+              "token expired — run `parachute auth rotate-operator`",
+            );
+          },
+          probeModuleHealth: async () => true,
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\bactive\b/);
+      const out = lines.join("\n");
+      expect(out).toMatch(/live via unauthenticated health probe/);
+      // The expired-token degraded-read hint still points at rotate-operator.
+      expect(out).toMatch(/rotate-operator/);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("API error reading module states → degrade with the message, no crash", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {

package/src/cli.ts

@@ -402,22 +402,41 @@ async function main(argv: string[]): Promise<number> {
         );
         return 1;
       }
-      const noBrowser = exposeExtract.rest.includes("--no-browser");
-      const noExposePrompt = exposeExtract.rest.includes("--no-expose-prompt");
-      const cliWizard = exposeExtract.rest.includes("--cli-wizard");
-      const browserWizard = exposeExtract.rest.includes("--browser-wizard");
+      // hub#694 bug 2: `--channel rc|latest` picks the dist-tag init installs the
+      // vault module from. Without it, init always resolved @latest — DOWNGRADING
+      // vault below an rc-tracking hub. Mirrors `parachute install --channel`.
+      const channelExtract = extractNamedFlag(exposeExtract.rest, "--channel");
+      if (channelExtract.error) {
+        console.error(`parachute init: ${channelExtract.error}`);
+        return 1;
+      }
+      if (
+        channelExtract.value !== undefined &&
+        channelExtract.value !== "rc" &&
+        channelExtract.value !== "latest"
+      ) {
+        console.error(
+          `parachute init: --channel must be "rc" or "latest" (got "${channelExtract.value}")`,
+        );
+        return 1;
+      }
+      const noBrowser = channelExtract.rest.includes("--no-browser");
+      const noExposePrompt = channelExtract.rest.includes("--no-expose-prompt");
+      const cliWizard = channelExtract.rest.includes("--cli-wizard");
+      const browserWizard = channelExtract.rest.includes("--browser-wizard");
       const known = new Set([
         "--no-browser",
         "--no-expose-prompt",
         "--cli-wizard",
         "--browser-wizard",
       ]);
-      const unknown = exposeExtract.rest.find((a) => !known.has(a));
+      const unknown = channelExtract.rest.find((a) => !known.has(a));
       if (unknown !== undefined) {
         console.error(`parachute init: unknown argument "${unknown}"`);
         console.error(
           "usage: parachute init [--no-browser] [--no-expose-prompt]\n" +
             "                     [--expose none|tailnet|cloudflare]\n" +
+            "                     [--channel rc|latest]\n" +
             "                     [--hub-origin <url>]\n" +
             "                     [--cli-wizard | --browser-wizard]",
         );
@@ -434,6 +453,9 @@ async function main(argv: string[]): Promise<number> {
       if (exposeExtract.value) {
         initOpts.exposeChoice = exposeExtract.value as "none" | "tailnet" | "cloudflare";
       }
+      if (channelExtract.value === "rc" || channelExtract.value === "latest") {
+        initOpts.channel = channelExtract.value;
+      }
       if (cliWizard) initOpts.wizardChoice = "cli";
       else if (browserWizard) initOpts.wizardChoice = "browser";
       const mod = await loadCommand("init", () => import("./commands/init.ts"));

package/src/commands/init.ts

@@ -154,14 +154,31 @@ export interface InitOpts {
    * stub to record the call without shelling out to `cloudflared`.
    */
   exposeCloudflareImpl?: () => Promise<number>;
+  /**
+   * Install channel for the vault module (hub#694 bug 2). `"rc"` makes init's
+   * vault install resolve `@openparachute/vault@rc` instead of `@latest`, so an
+   * rc-channel box (hub installed from `@rc`) doesn't DOWNGRADE vault below the
+   * hub on `parachute init`. Default `"latest"` (npm default; back-compat for
+   * every existing operator). Precedence in the CLI: `--channel <v>` flag >
+   * `PARACHUTE_CHANNEL` / `PARACHUTE_INSTALL_CHANNEL` env > `"latest"`. Threaded
+   * verbatim into `install()`'s existing `channel` plumbing
+   * (`resolveInstallChannel`).
+   */
+  channel?: "latest" | "rc";
   /**
    * Test seam: shim for the vault-module install step (hub#168 Cut 1).
    * Production calls `install("vault", { noCreate: true, noStart: true, …})`
    * to put `@openparachute/vault` on PATH without creating a first-vault
    * instance — the wizard's vault step decides Create/Import/Skip. Tests
-   * pass a stub to record the call without shelling out.
+   * pass a stub to record the call without shelling out. The `channel` arg
+   * (hub#694) forwards into `install()`'s `channel` option so an rc box installs
+   * vault from `@rc`.
    */
-  installVaultModuleImpl?: (configDir: string, manifestPath: string) => Promise<number>;
+  installVaultModuleImpl?: (
+    configDir: string,
+    manifestPath: string,
+    channel?: "latest" | "rc",
+  ) => Promise<number>;
   /**
    * Override the wizard-choice prompt (hub#168 Cut 4). When set, the
    * "Continue setup in the browser or CLI?" question is answered without
@@ -509,8 +526,18 @@ async function defaultGuaranteeOperatorToken(ctx: {
  * shim that re-emits each line under an `[install vault] ` prefix so the
  * init log stays grep-able. Idempotent — `install` short-circuits the
  * bun-add when vault is already linked / installed.
+ *
+ * The `channel` arg (hub#694) forwards into `install()`'s `channel` option so
+ * an rc-channel box installs `@openparachute/vault@rc` instead of `@latest` —
+ * otherwise init silently DOWNGRADES vault below the rc-tracking hub. Undefined
+ * → install's own resolution (`--tag` > `channel` > `PARACHUTE_INSTALL_CHANNEL`
+ * env > `"latest"`) applies, preserving today's behavior.
  */
-async function defaultInstallVaultModule(configDir: string, manifestPath: string): Promise<number> {
+async function defaultInstallVaultModule(
+  configDir: string,
+  manifestPath: string,
+  channel?: "latest" | "rc",
+): Promise<number> {
   const installOpts: InstallOpts = {
     configDir,
     manifestPath,
@@ -518,6 +545,7 @@ async function defaultInstallVaultModule(configDir: string, manifestPath: string
     noStart: true,
     log: (line) => console.log(`[install vault] ${line}`),
   };
+  if (channel) installOpts.channel = channel;
   return await defaultInstall("vault", installOpts);
 }
 
@@ -637,6 +665,32 @@ async function promptExposeChoice(
   return defaultChoice;
 }
 
+/**
+ * Resolve the install channel for init's vault module step (hub#694 bug 2).
+ *
+ * Precedence (highest → lowest):
+ *   1. explicit `--channel rc|latest` (parsed in cli.ts → `opts.channel`)
+ *   2. `PARACHUTE_CHANNEL` env (the DigitalOcean cloud-init script's var)
+ *   3. `PARACHUTE_INSTALL_CHANNEL` env (the install layer's own platform cascade)
+ *   4. `undefined` → `install()` falls back to its own "latest" default
+ *
+ * Returns `"latest"` / `"rc"` when one is resolved, or `undefined` to defer to
+ * `install()`'s resolution. A non-`rc`/`latest` env value is ignored (returns
+ * undefined) so a typo degrades to "latest" rather than crashing init — the
+ * same forgiving posture `resolveInstallChannel` takes for the install command.
+ */
+export function resolveInitChannel(
+  explicit: "latest" | "rc" | undefined,
+  env: NodeJS.ProcessEnv,
+): "latest" | "rc" | undefined {
+  if (explicit === "rc" || explicit === "latest") return explicit;
+  for (const key of ["PARACHUTE_CHANNEL", "PARACHUTE_INSTALL_CHANNEL"]) {
+    const v = env[key];
+    if (v === "rc" || v === "latest") return v;
+  }
+  return undefined;
+}
+
 export async function init(opts: InitOpts = {}): Promise<number> {
   const configDir = opts.configDir ?? CONFIG_DIR;
   const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
@@ -668,6 +722,16 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const exposeTailnetImpl = opts.exposeTailnetImpl ?? defaultExposeTailnet;
   const exposeCloudflareImpl = opts.exposeCloudflareImpl ?? defaultExposeCloudflare;
   const installVaultModuleImpl = opts.installVaultModuleImpl ?? defaultInstallVaultModule;
+  // hub#694 bug 2: resolve the channel for the vault module install. Precedence:
+  // explicit `--channel <v>` (opts.channel) > `PARACHUTE_CHANNEL` /
+  // `PARACHUTE_INSTALL_CHANNEL` env > undefined (install's own "latest"
+  // fallback). The env fallback is what makes the DigitalOcean cloud-init
+  // script's `PARACHUTE_CHANNEL=rc` cascade into init's vault install with zero
+  // extra flags — init never received a `--channel` from that script, but it
+  // reads the env the script already exports. A garbage env value falls through
+  // to undefined → install resolves "latest" (matching resolveInstallChannel's
+  // own garbage-handling), so an operator typo can't break init.
+  const installChannel: "latest" | "rc" | undefined = resolveInitChannel(opts.channel, env);
   const runCliWizardImpl = opts.runCliWizardImpl ?? defaultRunCliWizard;
   const fetchBootstrapTokenImpl = opts.fetchBootstrapTokenImpl ?? defaultFetchBootstrapToken;
   const setHubOriginImpl = opts.setHubOriginImpl ?? defaultSetHubOrigin;
@@ -696,6 +760,48 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     }
   }
 
+  // Step 0.5 (hub#694 bug 1 — the spawn race): install + seed the vault module
+  // into services.json BEFORE the hub unit starts (Step 1 below). The hub unit's
+  // `serve` runs the in-process Supervisor, which scans services.json EXACTLY
+  // ONCE at boot (`bootSupervisedModules`) and never rescans. If we seed vault
+  // AFTER the unit boots (the old Step 2.5 ordering), that single scan reads a
+  // services.json with no vault row → vault is registered-but-never-spawned, so
+  // `/vault/*` 502s until a manual `parachute restart` re-triggers a per-module
+  // start. On a slow box (1GB droplet) the scan reliably wins that race. Seeding
+  // first means the boot scan finds vault and spawns it on the first pass — no
+  // restart needed.
+  //
+  // `install("vault", { noCreate: true, noStart: true, … })` only does the
+  // on-disk work — `bun add -g` (idempotent; short-circuits when vault is
+  // bun-linked / already installed) + an `upsertService` seed write. It does NOT
+  // need a running hub: the start path, the stale-unit sweep, and the
+  // supervised-hub guidance probe are all gated off under `noCreate`/`noStart`,
+  // so running it before the unit exists is safe. The wizard's vault step still
+  // owns Create / Import / Skip (noCreate defers first-vault creation); the
+  // supervisor (not install.ts) owns spawning (noStart).
+  //
+  // Idempotent: if a vault row already exists (re-run, or a prior install), this
+  // short-circuits past the bun-add and the row is left intact. We don't block
+  // init on a non-zero exit — the wizard can retry from /admin/setup.
+  const findVaultEntry = (): boolean => {
+    try {
+      return findService("parachute-vault", manifestPath) !== undefined;
+    } catch {
+      return false;
+    }
+  };
+  const vaultAlreadyInstalled = findVaultEntry();
+  if (!vaultAlreadyInstalled) {
+    log("Installing the vault module so the wizard can offer create / import / skip…");
+    const installCode = await installVaultModuleImpl(configDir, manifestPath, installChannel);
+    if (installCode !== 0) {
+      log(
+        `⚠ vault module install returned ${installCode}; the wizard can retry from /admin/setup.`,
+      );
+    }
+    log("");
+  }
+
   // Step 1: hub running?
   // NB: under the Phase 3a unit-managed hub there is no pidfile, so
   // `processState(HUB_SVC)` reports not-running on EVERY init re-run even when
@@ -831,41 +937,14 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     }
   }
 
-  // Step 2.5: always install the vault module (hub#168 Cut 1). Aaron's
-  // 2026-05-28 directive: "it should always install the vault module"
-  // even though "creating a vault should be optional." We split the
-  // module install (always) from the first-vault create (deferred to
-  // the wizard) by passing `noCreate: true` to install — bun add -g
-  // runs, services.json gets seeded, but `parachute-vault init` (which
-  // would auto-create a `default` vault) is skipped. The wizard's
-  // vault step then either Creates / Imports / Skips.
-  //
-  // Idempotent: install short-circuits the bun-add when vault is
-  // already linked (`bun link`) or already globally installed. If the
-  // operator already has a vault row, this is a no-op past the
-  // already-installed log line. We don't block init on this step;
-  // a non-zero exit code is logged but treated as a warning, since the
-  // wizard can re-attempt the install itself from /admin/setup.
-  const findVaultEntry = (): boolean => {
-    try {
-      return findService("parachute-vault", manifestPath) !== undefined;
-    } catch {
-      return false;
-    }
-  };
-  const vaultAlreadyInstalled = findVaultEntry();
-  if (!vaultAlreadyInstalled) {
-    log("");
-    log("Installing the vault module so the wizard can offer create / import / skip…");
-    const installCode = await installVaultModuleImpl(configDir, manifestPath);
-    if (installCode !== 0) {
-      log(
-        `⚠ vault module install returned ${installCode}; the wizard can retry from /admin/setup.`,
-      );
-    }
-  }
+  // (The vault module install + seed now runs at Step 0.5, BEFORE the hub unit
+  // starts — see hub#694 bug 1. It used to live here, after exposure; moving it
+  // ahead of Step 1's hub bringup is what lets the supervisor's one-time boot
+  // scan find + spawn vault instead of registering it after the scan already
+  // ran. The "always install the vault module" directive — Aaron 2026-05-28,
+  // hub#168 Cut 1 — and the noCreate/noStart split are unchanged.)
 
-  // Step 3: vault configured? (After the module install above, this may
+  // Step 3: vault configured? (After the Step 0.5 module install above, this may
   // have flipped from false to true on a fresh box. The wizard reads
   // services.json on every request, so the "configured" answer here is
   // best-effort — it only shapes the next-step log message below.)

package/src/commands/status.ts

@@ -19,8 +19,8 @@ import {
 } from "../install-source.ts";
 import {
   type DriveModuleOpDeps,
-  type ModuleStatesResult,
   type ModuleStateSnapshot,
+  type ModuleStatesResult,
   NoOperatorTokenError,
   OperatorTokenExpiredError,
   fetchModuleStates as fetchModuleStatesImpl,
@@ -71,6 +71,17 @@ export interface StatusOpts {
     probeHubHealth?: (port: number) => Promise<boolean>;
     /** Read the running supervisor's module states (§6.4 module rows). */
     fetchModuleStates?: (deps: DriveModuleOpDeps) => Promise<ModuleStatesResult>;
+    /**
+     * Unauthenticated module-liveness probe (#700). Used ONLY on the degraded
+     * path where the supervisor run-state read couldn't run (no/expired/invalid
+     * operator token, or any API error) but the hub itself is up: probes a
+     * module's own `/health` directly on its loopback port. Treats 2xx AND 401
+     * as live (mirrors the "auth-gated health = healthy" rule, #423: a module
+     * that answers 401 is authenticated-but-alive, not down). Bounded; never
+     * throws. Production reuses the same bounded fetch shape as the hub probe;
+     * tests inject so they don't hit the network.
+     */
+    probeModuleHealth?: (port: number, health: string) => Promise<boolean>;
     /**
      * Open the hub DB used to validate/auto-rotate the operator token in
      * `fetchModuleStates`. Production opens `<configDir>/hub.db`; tests inject a
@@ -162,6 +173,15 @@ interface StatusRow {
    * Printed on a continuation line like the other notes.
    */
   managerNote?: string;
+  /**
+   * Set on a module row whose STATE was derived from an unauthenticated
+   * `/health` probe rather than the supervisor's run-state (#700) — the
+   * degraded-read fallback (no/expired operator token, or an API error) where
+   * the module is genuinely serving. Tells the operator the row is live-but-
+   * thin: no PID/uptime/structured run-state until they sign in. Printed on a
+   * continuation line like the other notes.
+   */
+  probeNote?: string;
 }
 
 /**
@@ -319,6 +339,7 @@ function renderRows(rows: StatusRow[], print: (line: string) => void): void {
       print(`  ! probe: ${row.healthDetail}`);
     }
     if (row.managerNote) print(`  ! ${row.managerNote}`);
+    if (row.probeNote) print(`  → ${row.probeNote}`);
     if (row.driftWarning) print(`  ! ${row.driftWarning}`);
     if (row.staleNote) print(`  ! ${row.staleNote}`);
     if (row.startErrorNote) print(`  ! ${row.startErrorNote}`);
@@ -336,12 +357,33 @@ function renderRows(rows: StatusRow[], print: (line: string) => void): void {
 // in Phase 5b.
 // ---------------------------------------------------------------------------
 
+/**
+ * Default unauthenticated module-liveness probe (#700). A bounded `fetch` to the
+ * module's own `http://127.0.0.1:<port><health>`. Treats 2xx AND 401 as live —
+ * an auth-gated `/health` that answers 401 is authenticated-but-alive, not down
+ * (the "auth-gated health = healthy" rule, #423). Any other status / network
+ * error / timeout → false. 1.5s timeout, mirroring hub-unit's `defaultProbeHealth`.
+ */
+async function defaultProbeModuleHealth(port: number, health: string): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}${health}`, {
+      signal: AbortSignal.timeout(1500),
+      // Loopback-only target, but never chase a redirect off-box (defensive).
+      redirect: "manual",
+    });
+    return res.ok || res.status === 401;
+  } catch {
+    return false;
+  }
+}
+
 /** 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>;
+  probeModuleHealth: (port: number, health: string) => Promise<boolean>;
   openDb: (configDir: string) => Database;
   baseUrl: string | undefined;
 }
@@ -357,6 +399,7 @@ function resolveStatusSupervisor(opts: StatusOpts["supervisor"]): ResolvedStatus
     queryHubUnitState: opts?.queryHubUnitState ?? queryHubUnitStateImpl,
     probeHubHealth: opts?.probeHubHealth ?? hubUnitDeps.probeHealth,
     fetchModuleStates: opts?.fetchModuleStates ?? fetchModuleStatesImpl,
+    probeModuleHealth: opts?.probeModuleHealth ?? defaultProbeModuleHealth,
     openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
     baseUrl: opts?.baseUrl,
   };
@@ -471,10 +514,17 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
         ...(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).
+      if (err instanceof NoOperatorTokenError) {
+        // No operator token AND none can be minted yet — on a fresh box the
+        // first admin doesn't exist, so `rotate-operator` would itself hard-error
+        // ("no hub users yet"). Point at `set-password` (create the first admin),
+        // the actual unblocking step. We still can't read run-state, but the hub
+        // is up — degrade gracefully (§6.4), do NOT 401-crash status (#700).
+        moduleReadNote =
+          "couldn't read live module state — run `parachute auth set-password` to create the first admin (then `parachute auth rotate-operator`)";
+      } else if (err instanceof OperatorTokenExpiredError) {
+        // Token exists but is stale: an admin already exists, so re-minting works.
+        // Keep the rotate-operator guidance.
         moduleReadNote =
           "couldn't read live module state — run `parachute auth rotate-operator` to mint an operator token";
       } else {
@@ -500,6 +550,26 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
     if (m.short && !stateByShort.has(m.short)) stateByShort.set(m.short, m);
   }
 
+  // Unauthenticated-liveness fallback (#700). On the degraded path — the hub is
+  // up but we couldn't read supervisor run-state (no/expired operator token, or
+  // an API error) — probe each module's own `/health` directly so a module that
+  // is genuinely serving reads LIVE instead of being mapped null→`inactive`
+  // (which falsely told fresh-box operators a working install was broken). Keyed
+  // by the unique `entry.name`; probed concurrently, bounded, never throws.
+  const probeAlive = new Map<string, boolean>();
+  if (hubHealthy && !states) {
+    await Promise.all(
+      manifest.services.map(async (entry) => {
+        try {
+          const alive = await sup.probeModuleHealth(entry.port, entry.health);
+          if (alive) probeAlive.set(entry.name, true);
+        } catch {
+          // Probe must never crash status — absent from the map = treated as down.
+        }
+      }),
+    );
+  }
+
   const rows: StatusRow[] = manifest.services.map((entry) => {
     const base = manifestRowBase(entry, installSourceDeps);
     const snap = base.short ? stateByShort.get(base.short) : undefined;
@@ -526,6 +596,39 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
       };
     }
 
+    // Degraded read, but the module answered an unauthenticated `/health` probe
+    // (#700): show it LIVE instead of null→`inactive`. We can't surface PID/
+    // uptime/structured run-state (those need the operator token), so keep the
+    // degraded `moduleReadNote` AND add a probe-derived continuation note so the
+    // operator understands the row is from a liveness probe, not full supervisor
+    // state. `skipped: true` keeps a working install at exit 0.
+    if (!snap && probeAlive.get(entry.name)) {
+      const row: StatusRow = {
+        service: entry.name,
+        port: String(entry.port),
+        version: entry.version,
+        stateLabel: "active",
+        pidLabel: "-",
+        uptimeLabel: "-",
+        healthDetail: "-",
+        latencyLabel: "-",
+        sourceLabel: base.sourceLabel,
+        url: base.url,
+        healthy: true,
+        skipped: true,
+      };
+      row.probeNote = "live via unauthenticated health probe — sign in for full supervisor state";
+      if (base.driftWarning) row.driftWarning = base.driftWarning;
+      if (base.staleNote) row.staleNote = base.staleNote;
+      if (base.manifestStartErrorNote) row.startErrorNote = base.manifestStartErrorNote;
+      // Surface the degraded-read note ONCE (first module row), same as below.
+      if (moduleReadNote) {
+        row.managerNote = moduleReadNote;
+        moduleReadNote = undefined;
+      }
+      return row;
+    }
+
     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).

package/src/help.ts

@@ -132,6 +132,7 @@ export function initHelp(): string {
 Usage:
   parachute init [--no-browser] [--no-expose-prompt]
                  [--expose none|tailnet|cloudflare]
+                 [--channel rc|latest]
                  [--hub-origin <url>]
                  [--cli-wizard | --browser-wizard]
 
@@ -168,6 +169,10 @@ Flags:
                               none       — stay loopback-only
                               tailnet    — set up Tailscale serve (private to your tailnet)
                               cloudflare — set up Cloudflare Tunnel (your own domain)
+  --channel <rc|latest>     npm dist-tag for the vault module install (default: latest).
+                            Use \`rc\` on an rc-channel box so init doesn't downgrade
+                            vault below the hub. Also honors PARACHUTE_CHANNEL /
+                            PARACHUTE_INSTALL_CHANNEL env when the flag is absent.
   --hub-origin <url>        set the canonical public origin (OAuth issuer) BEFORE
                             the hub + modules start, so vault/scribe come up
                             accepting it in one pass. For reverse-proxy /
@@ -185,6 +190,7 @@ Examples:
   parachute init --expose tailnet             # CI/scripted: chain straight into Tailscale
   parachute init --no-browser                 # don't shell out to open / xdg-open
   parachute init --cli-wizard                 # walk the wizard in this terminal (hub#168)
+  parachute init --channel rc                  # rc box: install the vault module from @rc
 `;
 }