@openparachute/hub 0.7.3 → 0.7.4-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3",
+  "version": "0.7.4-rc.1",
   "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/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/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
 `;
 }