@openparachute/vault 0.5.2-rc.4 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.2-rc.4",
+  "version": "0.5.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

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

@@ -104,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,
@@ -275,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");
 
@@ -417,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());
@@ -3657,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/mcp-install.ts

@@ -271,8 +271,15 @@ export async function detectHubPresence(opts: {
   //    signal — no need to probe. We pass `hubPort` purely as the loopback
   //    fallback arg; its only role here is the source discriminator.
   const configured = chooseHubOrigin(hubPort, env);
-  // A stale expose-state can false-positive here — acceptable: this only
-  // selects guidance copy, never gates behavior.
+  // A stale expose-state (or a leftover PARACHUTE_HUB_ORIGIN) can
+  // false-positive here. Originally this only selected guidance copy, but as
+  // of hub#580 it ALSO gates `vault init`'s daemon registration default
+  // (hub present → skip autostart). The false-positive failure mode is
+  // therefore: a genuinely hubless box with stale hub-origin state runs init
+  // without a flag and silently skips registering a daemon. Narrow + accepted
+  // — the operator can re-run with `--autostart`, and any explicit flag or a
+  // persisted `config.autostart` short-circuits the probe entirely. See the
+  // call site in cli.ts for the persisted-value guard.
   if (configured.source !== "loopback") return true;
 
   // 2. Live health probe against the hub's fixed loopback port.