@openparachute/vault 0.5.2-rc.3 → 0.5.2-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.2-rc.3",
+  "version": "0.5.2-rc.5",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -22,7 +22,6 @@
     "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run",
     "typecheck": "tsc --noEmit",
     "build:spa": "cd web/ui && bun install --frozen-lockfile && bun run build",
-    "postinstall": "if [ -d web/ui ]; then bun run build:spa; fi",
     "prepack": "bun run build:spa"
   },
   "dependencies": {

package/src/autostart.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect } from "bun:test";
+import { decideAutostart } from "./autostart.ts";
+
+/**
+ * Pure matrix for the autostart decision (ParachuteComputer/parachute-hub#580
+ * item 2). No launchd/systemd is touched — `decideAutostart` is side-effect
+ * free; the CLI consumes its result to register or skip.
+ */
+describe("decideAutostart", () => {
+  test("hub present, no flag, no persisted → default OFF (#580)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: undefined, hubPresent: true });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("hub-default-off");
+    // Per-run inference — not persisted, so a later standalone re-run registers.
+    expect(d.persist).toBe(false);
+    expect(d.overrodeHub).toBe(false);
+  });
+
+  test("hub absent, no flag, no persisted → default ON (standalone)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: undefined, hubPresent: false });
+    expect(d.enabled).toBe(true);
+    expect(d.reason).toBe("default-on");
+    expect(d.persist).toBe(false);
+  });
+
+  test("explicit --autostart forces ON even under a hub (operator override + warn flag)", () => {
+    const d = decideAutostart({ flagOn: true, flagOff: false, persisted: undefined, hubPresent: true });
+    expect(d.enabled).toBe(true);
+    expect(d.reason).toBe("flag-on");
+    expect(d.persist).toBe(true);
+    expect(d.overrodeHub).toBe(true);
+  });
+
+  test("explicit --autostart with no hub does not set overrodeHub", () => {
+    const d = decideAutostart({ flagOn: true, flagOff: false, persisted: undefined, hubPresent: false });
+    expect(d.enabled).toBe(true);
+    expect(d.overrodeHub).toBe(false);
+    expect(d.persist).toBe(true);
+  });
+
+  test("explicit --no-autostart forces OFF and persists (even under a hub)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: true, persisted: undefined, hubPresent: true });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("flag-off");
+    expect(d.persist).toBe(true);
+    expect(d.overrodeHub).toBe(false);
+  });
+
+  test("--no-autostart wins over --autostart on the same line (safer default)", () => {
+    const d = decideAutostart({ flagOn: true, flagOff: true, persisted: undefined, hubPresent: false });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("flag-off");
+  });
+
+  test("persisted=false honored over hub-present default", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: false, hubPresent: true });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("persisted");
+    expect(d.persist).toBe(false);
+  });
+
+  test("persisted=true honored even when a hub is present (prior explicit choice)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: true, hubPresent: true });
+    expect(d.enabled).toBe(true);
+    expect(d.reason).toBe("persisted");
+    expect(d.persist).toBe(false);
+  });
+
+  test("flag beats persisted: --no-autostart over persisted=true", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: true, persisted: true, hubPresent: false });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("flag-off");
+    expect(d.persist).toBe(true);
+  });
+});

package/src/autostart.ts

@@ -0,0 +1,84 @@
+/**
+ * Decide whether `parachute-vault init` should register a boot/restart daemon
+ * (launchd on macOS, systemd on Linux).
+ *
+ * Pure: extracted so the flag × persisted-config × hub-presence matrix can be
+ * unit-tested without spawning the CLI or touching launchd/systemd. The caller
+ * passes in the resolved `hubPresent` signal (from `detectHubPresence`) so this
+ * function stays side-effect-free.
+ *
+ * Why hub-presence flips the default (ParachuteComputer/parachute-hub#580):
+ * under hub-as-supervisor the hub owns the vault lifecycle — it spawns vault as
+ * a supervised child. If init *also* registers a launchd/systemd unit with
+ * `KeepAlive`/`RunAtLoad`, two lifecycles race for :1940: the supervisor's
+ * child and the platform manager's respawn. `parachute stop` kills the
+ * supervised one, launchd resurrects the other (EADDRINUSE crash-loop, pidfile
+ * records the loser, the rogue holds the port with no injected
+ * PARACHUTE_HUB_ORIGIN → iss mismatch). Defaulting autostart OFF when a hub is
+ * present makes the standalone daemon an explicit opt-in.
+ *
+ * Precedence (first match wins):
+ *   1. `--no-autostart` on this run            → off  (persisted; safer-default
+ *                                                 precedence beats --autostart)
+ *   2. `--autostart` on this run               → on   (persisted; operator
+ *                                                 override — caller warns if a
+ *                                                 supervised hub was detected)
+ *   3. Existing `config.autostart` (boolean)   → that value (honor prior choice)
+ *   4. Hub present, no flag, no persisted value → off  (the hub supervisor owns
+ *                                                 the lifecycle — #580)
+ *   5. Default                                 → on   (standalone deploys
+ *                                                 genuinely need a daemon)
+ *
+ * `persist` is true only when the choice came from an explicit flag (cases 1+2)
+ * — matching the prior behavior where a flagless re-run never rewrote the
+ * persisted value. The hub-present default (case 4) is intentionally NOT
+ * persisted: it's a per-run inference, so a later standalone re-run (no hub)
+ * falls back to the register default rather than being stuck off.
+ *
+ * `overrodeHub` is true only for case 2 when a hub was detected — the signal the
+ * caller uses to log the "supervised hub detected, registering anyway" warning.
+ */
+export interface AutostartDecisionInput {
+  /** `--autostart` present on this invocation. */
+  flagOn: boolean;
+  /** `--no-autostart` present on this invocation. */
+  flagOff: boolean;
+  /** Persisted `config.autostart` from a prior run, if a boolean. */
+  persisted?: boolean | undefined;
+  /** Whether a hub supervisor was detected (from `detectHubPresence`). */
+  hubPresent: boolean;
+}
+
+export interface AutostartDecision {
+  /** Final resolved value. */
+  enabled: boolean;
+  /** Whether the caller should write `config.autostart` to disk. */
+  persist: boolean;
+  /** True when `--autostart` forced registration despite a detected hub. */
+  overrodeHub: boolean;
+  /** Which precedence rule decided the outcome (for testing + copy). */
+  reason: "flag-off" | "flag-on" | "persisted" | "hub-default-off" | "default-on";
+}
+
+export function decideAutostart(input: AutostartDecisionInput): AutostartDecision {
+  const { flagOn, flagOff, persisted, hubPresent } = input;
+
+  if (flagOff) {
+    return { enabled: false, persist: true, overrodeHub: false, reason: "flag-off" };
+  }
+  if (flagOn) {
+    return {
+      enabled: true,
+      persist: true,
+      overrodeHub: hubPresent,
+      reason: "flag-on",
+    };
+  }
+  if (typeof persisted === "boolean") {
+    return { enabled: persisted, persist: false, overrodeHub: false, reason: "persisted" };
+  }
+  if (hubPresent) {
+    return { enabled: false, persist: false, overrodeHub: false, reason: "hub-default-off" };
+  }
+  return { enabled: true, persist: false, overrodeHub: false, reason: "default-on" };
+}

package/src/cli.ts

@@ -57,8 +57,10 @@ import {
   buildMcpEntryPlan,
   chooseHubOrigin,
   chooseMcpUrl,
+  detectHubPresence,
   detectInstallContext,
   mintHubJwt,
+  noOperatorTokenGuidance,
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
@@ -102,6 +104,7 @@ import { resolveBindHostname } from "./bind.ts";
 import { listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import { VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
+import { decideAutostart } from "./autostart.ts";
 import { getVaultStore } from "./vault-store.ts";
 import {
   defaultMirrorConfig,
@@ -273,12 +276,16 @@ async function cmdInit(args: string[] = []) {
   const flagMcpOff = args.includes("--no-mcp");
   const flagTokenOn = args.includes("--token");
   const flagTokenOff = args.includes("--no-token");
-  // --autostart / --no-autostart toggle daemon registration. Default is on
-  // (preserves historical behavior). When --no-autostart is passed, init
-  // skips registering with launchd / systemd AND removes any prior
-  // registration — for CI, dev sandboxes, Docker, or any environment where
-  // another supervisor manages the process. --no-autostart wins over
-  // --autostart on the same command line (safer-default precedence).
+  // --autostart / --no-autostart toggle daemon registration. The default is
+  // context-aware (resolved by decideAutostart below): ON for standalone
+  // deploys, but OFF when a hub supervisor is detected, since the hub owns
+  // vault's lifecycle and a launchd/systemd unit would race it for :1940
+  // (ParachuteComputer/parachute-hub#580). --no-autostart always skips
+  // registering AND removes any prior registration — for CI, dev sandboxes,
+  // Docker, or any environment where another supervisor manages the process.
+  // --autostart forces registration even under a hub (logged with a warning).
+  // --no-autostart wins over --autostart on the same command line
+  // (safer-default precedence).
   const flagAutostartOn = args.includes("--autostart");
   const flagAutostartOff = args.includes("--no-autostart");
 
@@ -415,37 +422,73 @@ async function cmdInit(args: string[] = []) {
   // a folder move; this refreshes ~/.parachute/server-path and bounces the
   // daemon so the new location takes effect immediately.
   //
-  // Autostart precedence (resolved here so the user's prior config is
-  // honored on re-runs that don't pass a flag):
-  //   1. --no-autostart on this run → false (and persisted)
-  //   2. --autostart on this run    → true  (and persisted)
-  //   3. Existing config.autostart  → that value
-  //   4. Default                    → true (historical behavior)
+  // Autostart precedence is resolved by `decideAutostart` (pure, unit-tested):
+  //   1. --no-autostart on this run             → false (and persisted)
+  //   2. --autostart on this run                → true  (and persisted; warns
+  //                                                if a supervised hub was seen)
+  //   3. Existing config.autostart              → that value
+  //   4. Hub present, no flag, no persisted val → false (the hub supervisor
+  //                                                owns the lifecycle — #580)
+  //   5. Default                                → true  (standalone deploys
+  //                                                genuinely need a daemon)
   // When false: skip register AND uninstall any prior registration so the
-  // flag's intent ("don't auto-start / don't auto-restart") matches reality
+  // decision's intent ("don't auto-start / don't auto-restart") matches reality
   // even if a previous run had registered a daemon.
-  let autostartEnabled: boolean;
-  if (flagAutostartOff) autostartEnabled = false;
-  else if (flagAutostartOn) autostartEnabled = true;
-  else if (typeof globalConfig.autostart === "boolean") autostartEnabled = globalConfig.autostart;
-  else autostartEnabled = true;
+  //
+  // The hub probe runs only when neither flag was passed AND no value is
+  // persisted — i.e. only when the hub signal can actually change the outcome.
+  // It targets the hub's fixed loopback port (1939 / $PARACHUTE_HUB_PORT) and
+  // never throws (see detectHubPresence). We skip it when a flag/persisted
+  // value already decides, to avoid an 800ms wait on a flagged run.
+  //
+  // False-positive risk: a stale expose-state / leftover PARACHUTE_HUB_ORIGIN
+  // makes detectHubPresence return true on a genuinely hubless box, so init
+  // silently skips registering a daemon. Narrow + accepted — recover with
+  // `parachute-vault init --autostart`. The pre-decided guard below means any
+  // explicit flag or persisted value never even reaches the probe.
+  const autostartPreDecided =
+    flagAutostartOff || flagAutostartOn || typeof globalConfig.autostart === "boolean";
+  const hubPresentForAutostart = autostartPreDecided ? false : await detectHubPresence();
+  const autostartDecision = decideAutostart({
+    flagOn: flagAutostartOn,
+    flagOff: flagAutostartOff,
+    persisted: globalConfig.autostart,
+    hubPresent: hubPresentForAutostart,
+  });
+  const autostartEnabled = autostartDecision.enabled;
 
-  if (flagAutostartOff || flagAutostartOn) {
+  if (autostartDecision.persist) {
     globalConfig.autostart = autostartEnabled;
     writeGlobalConfig(globalConfig);
   }
 
   let serverPath: string | null = null;
   if (!autostartEnabled) {
-    console.log("Autostart disabled — skipping daemon registration.");
+    if (autostartDecision.reason === "hub-default-off") {
+      console.log(
+        "Hub supervisor detected — not registering a separate daemon. The hub manages vault's lifecycle.",
+      );
+      console.log("  To force a standalone daemon anyway: parachute-vault init --autostart");
+    } else {
+      console.log("Autostart disabled — skipping daemon registration.");
+    }
     if (isMac) {
       await uninstallAgent();
     } else if (isLinux && isSystemdAvailable()) {
       await uninstallSystemdService();
     }
     console.log("  To run vault: parachute-vault serve   (or use your own supervisor)");
-    console.log("  To re-enable: parachute-vault init --autostart");
+    if (autostartDecision.reason !== "hub-default-off") {
+      console.log("  To re-enable: parachute-vault init --autostart");
+    }
   } else {
+    if (autostartDecision.overrodeHub) {
+      console.log(
+        "Warning: a supervised hub was detected, but --autostart was passed — registering a "
+          + "standalone daemon anyway. This can race the hub supervisor for the vault port; "
+          + "prefer letting the hub manage vault unless you know you need both.",
+      );
+    }
     console.log("Installing daemon...");
     if (isMac) {
       ({ serverPath } = await installAgent());
@@ -548,6 +591,11 @@ async function cmdInit(args: string[] = []) {
   // 8. Summary
   const port = globalConfig.port || DEFAULT_PORT;
   const mcpUrl = `http://127.0.0.1:${port}/vault/${defaultVault}/mcp`;
+  // Probe whether a hub is present so the summary's "opted into a token but
+  // none minted" copy reflects reality: under a hub the vault is reachable via
+  // browser OAuth even with no header-auth token (#445). Only matters for the
+  // !apiKey branches; cheap + best-effort (never throws).
+  const hubPresent = !apiKey ? await detectHubPresence() : true;
   const lines = buildInitSummaryLines({
     addMcp,
     addToken,
@@ -558,6 +606,7 @@ async function cmdInit(args: string[] = []) {
     mcpUrl,
     vaultName: defaultVault,
     noTokenGuidance: credentialGuidance,
+    hubPresent,
   });
   for (const line of lines) console.log(line);
 }
@@ -3369,15 +3418,25 @@ interface VaultCredential {
 async function mintBootstrapCredential(
   name: string,
   verb: "read" | "write" = "read",
+  /**
+   * Test seam — injectable hub-presence probe. Defaults to the live
+   * `detectHubPresence` (loopback `/health` + configured-origin check). Lets
+   * tests drive both branches of the no-operator-token copy without a real hub.
+   */
+  detectHub: typeof detectHubPresence = detectHubPresence,
 ): Promise<VaultCredential> {
   const operatorToken = readOperatorToken();
   if (!operatorToken) {
+    // No operator.token. Two very different worlds, identical symptom:
+    //   (a) Hub running on a fresh box — the token isn't minted until the
+    //       admin wizard creates the first admin user (hub init Step 1.5 is a
+    //       no-op until then). NOTHING to do here; the old "install the hub …"
+    //       copy is circular (this very flow was spawned *by* the hub). #445.
+    //   (b) Genuinely standalone — no hub at all. The original guidance holds.
+    const hubPresent = await detectHub();
     return {
       token: null,
-      guidance:
-        "No token issued — no hub operator token at ~/.parachute/operator.token. " +
-        "Install the hub (`bun add -g @openparachute/hub` + `parachute init`) and re-run, " +
-        "or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+      guidance: noOperatorTokenGuidance(hubPresent),
     };
   }
   const port = readGlobalConfig().port || DEFAULT_PORT;
@@ -3639,13 +3698,20 @@ Setup:
                                            --vault-name skips the prompt and names the vault
                                            (lowercase alphanumeric, hyphens, underscores;
                                            omit to be prompted interactively, default "default").
-                                           --autostart (default) registers vault with launchd /
-                                           systemd so it starts on boot AND auto-restarts on
-                                           crash. --no-autostart skips daemon registration AND
-                                           uninstalls any prior registration — for CI, dev
-                                           sandboxes, Docker, or environments where another
-                                           supervisor manages the process. Persists in
-                                           config.yaml as 'autostart: true|false'.
+                                           --autostart registers vault with launchd / systemd so
+                                           it starts on boot AND auto-restarts on crash; it forces
+                                           registration even when a hub supervisor is detected
+                                           (logged with a warning). --no-autostart skips daemon
+                                           registration AND uninstalls any prior registration — for
+                                           CI, dev sandboxes, Docker, or environments where another
+                                           supervisor manages the process. Default: register when
+                                           standalone, but skip when a hub is detected (the hub
+                                           supervisor owns vault's lifecycle). An explicit flag
+                                           persists in config.yaml as 'autostart: true|false'.
+                                           Upgrade note: a box with a persisted 'autostart: true'
+                                           (from an earlier explicit --autostart) keeps registering
+                                           even under a hub — run init --no-autostart once to clear
+                                           it and let the hub manage vault.
   parachute-vault doctor                   Diagnose install/config issues
   parachute-vault uninstall [--wipe] [--yes]
                                            Remove daemon + MCP entry; --wipe also removes vaults, .env,

package/src/init-summary.test.ts

@@ -175,19 +175,62 @@ describe("buildInitSummaryLines", () => {
 
   // Explicit opt-in but no hub reachable to mint (vault#282 Stage 2 path,
   // reached only when the operator passes --token without a hub).
-  describe("MCP=N + token=Y but no hub (opt-in mint failed)", () => {
+  describe("MCP=N + token=Y but no hub (opt-in mint failed, standalone)", () => {
     const out = buildInitSummaryLines({
       ...baseInput,
       addMcp: false,
       addToken: true,
       apiKey: undefined,
       noTokenGuidance: "No token issued — hub unreachable.",
+      hubPresent: false,
     }).join("\n");
 
     test("surfaces the no-token-issued guidance + recovery", () => {
       expect(out).toContain("No token issued");
       expect(out).toContain("parachute-vault mcp-install");
     });
+
+    test("standalone framing — points at bringing a hub up / VAULT_AUTH_TOKEN", () => {
+      expect(out).toContain("Once a hub is running");
+      expect(out).toContain("VAULT_AUTH_TOKEN");
+    });
+
+    test("does NOT claim the vault is reachable (no hub present)", () => {
+      expect(out).not.toContain("Your vault is still reachable");
+    });
+  });
+
+  // #445: opted into a token, none minted, but a HUB IS PRESENT. The vault is
+  // reachable via the hub's browser OAuth flow even with no header-auth token,
+  // so the standalone "isn't reachable" framing would be false here.
+  describe("MCP=N + token=Y, no token minted, but hub present (#445)", () => {
+    const out = buildInitSummaryLines({
+      ...baseInput,
+      addMcp: false,
+      addToken: true,
+      apiKey: undefined,
+      noTokenGuidance: "No token yet — the hub's admin wizard mints it.",
+      hubPresent: true,
+    }).join("\n");
+
+    test("affirms the vault is still reachable via the hub's OAuth flow", () => {
+      expect(out).toContain("Your vault is still reachable");
+      expect(out).toContain("sign-in (OAuth)");
+    });
+
+    test("frames a header-auth token as optional (scripts / non-OAuth clients)", () => {
+      expect(out).toContain("only needed for scripts");
+      expect(out).toContain("parachute-vault mcp-install");
+    });
+
+    test("does NOT print the standalone 'Once a hub is running' / VAULT_AUTH_TOKEN copy", () => {
+      expect(out).not.toContain("Once a hub is running");
+      expect(out).not.toContain("VAULT_AUTH_TOKEN");
+    });
+
+    test("never claims the vault isn't reachable by any client", () => {
+      expect(out).not.toContain("isn't reachable by any client");
+    });
   });
 
   test("always prints Config: and Server: lines", () => {

package/src/init-summary.ts

@@ -26,6 +26,15 @@ export type InitSummaryInput = {
    * undefined, so they know why and how to make the vault reachable.
    */
   noTokenGuidance?: string | undefined;
+  /**
+   * Whether a hub is present on this host (live `/health` probe or a
+   * configured hub origin — see `detectHubPresence`). Branches the
+   * opted-into-a-token-but-none-minted copy: under a hub the vault is reachable
+   * via the hub's browser OAuth flow even with no header-auth token, so the
+   * old "your vault isn't reachable by any client" framing is false. #445.
+   * Undefined → treat as the conservative standalone case.
+   */
+  hubPresent?: boolean | undefined;
 };
 
 /**
@@ -45,7 +54,7 @@ export type InitSummaryInput = {
  *   !addMcp, !addToken          → OAuth-first: add Claude Code later
  */
 export function buildInitSummaryLines(input: InitSummaryInput): string[] {
-  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance } = input;
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance, hubPresent } = input;
   const lines: string[] = [];
   lines.push("");
   lines.push("---");
@@ -75,20 +84,35 @@ export function buildInitSummaryLines(input: InitSummaryInput): string[] {
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
   } else if (!addMcp && addToken && !apiKey) {
-    // Explicitly opted into a token but no hub was reachable to mint one
-    // (vault#282 Stage 2 — vault no longer mints local pvt_* tokens). Surface
-    // why and the recovery paths.
+    // Explicitly opted into a token but none was minted (vault#282 Stage 2 —
+    // vault no longer mints local pvt_* tokens). Surface why + recovery.
     lines.push("");
     lines.push(
       noTokenGuidance ??
         "No token issued — no hub was reachable to mint a hub JWT.",
     );
-    lines.push(
-      "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
-    );
-    lines.push(
-      "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
-    );
+    if (hubPresent) {
+      // A hub IS present — the vault is already reachable via the hub's
+      // browser OAuth flow / web UI. A header-auth token is optional, only for
+      // non-OAuth clients + scripts. The "isn't reachable" framing is false
+      // here (#445).
+      lines.push(
+        "  Your vault is still reachable — clients connect through the hub's browser",
+      );
+      lines.push(
+        "  sign-in (OAuth); a header-auth token is only needed for scripts / non-OAuth",
+      );
+      lines.push(
+        "  clients. Run `parachute-vault mcp-install` to mint + wire one when you want it.",
+      );
+    } else {
+      lines.push(
+        "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
+      );
+      lines.push(
+        "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+      );
+    }
   } else if (!addMcp && !addToken) {
     // OAuth-first, but the operator skipped wiring Claude Code too.
     lines.push("");

package/src/mcp-install.test.ts

@@ -23,7 +23,9 @@ import {
   buildMcpEntryPlan,
   chooseHubOrigin,
   chooseMcpUrl,
+  detectHubPresence,
   mintHubJwt,
+  noOperatorTokenGuidance,
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
@@ -315,6 +317,97 @@ describe("readOperatorToken", () => {
   });
 });
 
+describe("detectHubPresence", () => {
+  let origHome: string | undefined;
+  let tmpHome: string;
+
+  beforeEach(() => {
+    origHome = process.env.PARACHUTE_HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "vault-hub-presence-"));
+    process.env.PARACHUTE_HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (origHome === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  test("a configured non-loopback hub origin counts as present (no probe)", async () => {
+    let probed = false;
+    const mockFetch: typeof fetch = async () => {
+      probed = true;
+      return new Response(null, { status: 500 });
+    };
+    const present = await detectHubPresence({
+      env: { PARACHUTE_HUB_ORIGIN: "https://hub.example" },
+      fetchImpl: mockFetch,
+    });
+    expect(present).toBe(true);
+    expect(probed).toBe(false); // configured origin short-circuits the probe
+  });
+
+  test("loopback + healthy hub (2xx /health) → present", async () => {
+    const calls: string[] = [];
+    const mockFetch: typeof fetch = async (url) => {
+      calls.push(String(url));
+      return new Response("ok", { status: 200 });
+    };
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(true);
+    expect(calls).toHaveLength(1);
+    // Probes the hub's fixed loopback port (1939), not vault's listen port.
+    expect(calls[0]).toBe("http://127.0.0.1:1939/health");
+  });
+
+  test("loopback + no hub answering (fetch throws) → absent", async () => {
+    const mockFetch: typeof fetch = async () => {
+      throw new Error("ECONNREFUSED");
+    };
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(false);
+  });
+
+  test("loopback + hub answers non-2xx → absent", async () => {
+    const mockFetch: typeof fetch = async () => new Response("nope", { status: 503 });
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(false);
+  });
+
+  test("$PARACHUTE_HUB_PORT overrides the probed port (deterministic for tests)", async () => {
+    const calls: string[] = [];
+    const mockFetch: typeof fetch = async (url) => {
+      calls.push(String(url));
+      return new Response("ok", { status: 200 });
+    };
+    const present = await detectHubPresence({
+      env: { PARACHUTE_HUB_PORT: "59399" },
+      fetchImpl: mockFetch,
+    });
+    expect(present).toBe(true);
+    expect(calls[0]).toBe("http://127.0.0.1:59399/health");
+  });
+});
+
+describe("noOperatorTokenGuidance (#445)", () => {
+  test("hub present → non-circular 'finish in the wizard' copy", () => {
+    const msg = noOperatorTokenGuidance(true);
+    // Does NOT tell the operator to install the hub (circular — this flow ran
+    // *under* the hub).
+    expect(msg).not.toContain("Install the hub");
+    expect(msg).not.toContain("bun add -g @openparachute/hub");
+    expect(msg).toContain("admin wizard mints");
+    expect(msg).toContain("Nothing to do here");
+  });
+
+  test("hub absent → keeps the standalone install-the-hub advice", () => {
+    const msg = noOperatorTokenGuidance(false);
+    expect(msg).toContain("Install the hub");
+    expect(msg).toContain("bun add -g @openparachute/hub");
+    expect(msg).toContain("VAULT_AUTH_TOKEN");
+  });
+});
+
 describe("resolveInstallTarget", () => {
   test("user scope → ~/.claude.json", () => {
     const res = resolveInstallTarget("user");