@openparachute/hub 0.6.4-rc.8 → 0.6.4

package/src/__tests__/install.test.ts

@@ -341,6 +341,96 @@ describe("install", () => {
     }
   });
 
+  test("names the squatter holding the canonical port when the walk assigns a fallback (#590)", async () => {
+    // Field bug #590 item 2: a stale pre-supervisor vault zombie squats 1940;
+    // the install-time port walk silently routed to a fallback. Now it names the
+    // holder (pid + command line) + hints it may be a stale daemon. Detection
+    // only — never kills. Reuses the #581 pidOnPort / ownerOfPid seams.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        // Only vault's canonical 1940 is held → the walk picks a fallback in-range.
+        portProbe: async (p) => p === 1940,
+        // Inject the #581 seams: a foreign pid squats 1940.
+        pidOnPort: (p) => (p === 1940 ? 1234 : undefined),
+        ownerOfPid: (pid) => (pid === 1234 ? "bun /opt/vault/src/server.ts" : undefined),
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      // The fallback warning still fires…
+      expect(joined).toMatch(/canonical port 1940 is in use; assigned/);
+      // …and now it NAMES the squatter + hints at a stale daemon.
+      expect(joined).toContain("pid 1234 (bun /opt/vault/src/server.ts)");
+      expect(joined).toMatch(/stale pre-supervisor daemon/);
+      expect(joined).toContain("kill 1234");
+      const entry = findService("parachute-vault", path);
+      expect(entry?.port).not.toBe(1940);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("squatter pid present but command line unreadable → names the pid alone (#590)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async (p) => p === 1940,
+        pidOnPort: (p) => (p === 1940 ? 4321 : undefined),
+        ownerOfPid: () => undefined, // ps failed / pid gone
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("held by pid 4321.");
+      expect(joined).not.toContain("(undefined)");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no squatter naming when the canonical port is free (#590 — no false positive)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      let pidProbed = false;
+      const code = await install("vault", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false, // canonical 1940 is free
+        pidOnPort: () => {
+          pidProbed = true;
+          return 9999;
+        },
+        ownerOfPid: () => "should-not-appear",
+        log: (l) => logs.push(l),
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      // Canonical assigned → no fallback warning, no squatter probe at all.
+      expect(joined).not.toMatch(/is in use; assigned/);
+      expect(joined).not.toContain("should-not-appear");
+      expect(pidProbed).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("`install lens` aliases to notes with a rename notice", async () => {
     // Transition alias for the brief Notes→Lens rename (Apr 19) that was
     // reverted on launch eve (Apr 22). Accepted for one release cycle so

package/src/__tests__/migrate-cutover.test.ts

@@ -67,6 +67,7 @@ function fakeHubUnitDeps(): HubUnitDeps {
     readFile: () => undefined,
     exists: () => false,
     probeHealth: async () => false,
+    probeHealthVersion: async () => null,
     portListening: async () => false,
     sleep: async () => {},
   };

package/src/commands/expose-cloudflare.ts

@@ -53,6 +53,7 @@ import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
 import { type AliveFn, defaultAlive } from "../process-state.ts";
 import { readManifestLenient } from "../services-manifest.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
+import { clearVaultHubOrigin } from "../vault-hub-origin-env.ts";
 import type { VaultAuthStatus } from "../vault/auth-status.ts";
 import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
 import {
@@ -1137,8 +1138,35 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   // downstream consumers stop resolving the now-dead public URL (mirrors the
   // up-path write above + the Tailscale off-path's expose-state teardown). When
   // other tunnels survive we leave it — a later off for the last one clears it.
+  //
+  // TODO(multi-tunnel) #588: with TWO CF tunnels up, tearing down the
+  // last-written-up one (whose hostname is what's in vault's `.env`) while the
+  // other survives leaves `.env` carrying the dead tunnel's origin while the
+  // surviving tunnel serves a different one → stale-iss on the next vault
+  // restart. Retention is still the only SAFE choice here: a single
+  // `PARACHUTE_HUB_ORIGIN` field can't represent "which surviving tunnel wins,"
+  // and clearing it would break the survivor's iss check. Properly fixing it
+  // needs re-resolving the effective origin from the survivor (or multi-origin
+  // issuer acceptance vault-side) — larger than the #503 single-tunnel fix, and
+  // multi-CF-tunnel-on-one-box is rare. See #588.
   if (!state) {
     clearExposeState(r.exposeStatePath);
+    // Drop the persisted PARACHUTE_HUB_ORIGIN from vault's `.env` (#503). With
+    // the last Cloudflare tunnel gone, the hub is loopback-only and mints
+    // loopback-`iss` tokens; a stale public origin left in `vault/.env` would
+    // pin a public expected issuer and 401 every request on the next vault
+    // daemon restart ("not signed in to the hub" — the inverse of the bug
+    // selfHealVaultHubOrigin closed). This mirrors exactly what the Tailscale
+    // off-path does (`exposeOff` in expose.ts) — the Cloudflare path had been
+    // the asymmetric gap. expose-state's own `hubOrigin` is cleared above via
+    // clearExposeState, so hub's per-request `resolveIssuer`/`exposeIssuerOrigin`
+    // (which read expose-state) also stop minting the public iss after teardown.
+    // No restart needed for the gap this closes — the next vault restart picks
+    // up the cleared `.env` — but tell the operator so an already-running vault
+    // doesn't keep validating against the now-dead public origin.
+    if (clearVaultHubOrigin(r.configDir, r.log)) {
+      r.log("  Restart vault to apply the loopback issuer now: `parachute restart vault`.");
+    }
   }
   return failed ? 1 : 0;
 }

package/src/commands/expose-supervisor.ts

@@ -16,15 +16,18 @@
  * `expose-cloudflare.ts` (cloudflared) use so the two paths can't drift.
  */
 
+import pkg from "../../package.json" with { type: "json" };
 import { readHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import {
   type EnsureHubUnitOpts,
   type EnsureHubUnitResult,
+  type EnsureHubVersionMatchesResult,
   HUB_UNIT_DEFAULT_PORT,
   type HubUnitDeps,
   defaultHubUnitDeps,
   ensureHubUnit as ensureHubUnitImpl,
+  ensureHubVersionMatches as ensureHubVersionMatchesImpl,
 } from "../hub-unit.ts";
 import {
   type DriveModuleOpDeps,
@@ -54,6 +57,17 @@ export interface ExposeSupervisorOpts {
   hubUnitDeps?: HubUnitDeps;
   /** Ensure the hub unit is up before / during expose (§3.2 / §4.3a). */
   ensureHubUnit?: (opts: EnsureHubUnitOpts) => Promise<EnsureHubUnitResult>;
+  /**
+   * Version-check-and-restart at the expose adoption point (#590). After the
+   * hub unit is confirmed up, compare the RUNNING hub's `/health` version to the
+   * installed package version; restart the managed unit on mismatch so an expose
+   * never wires a tunnel to a stale zombie. Production wires
+   * `ensureHubVersionMatches`; tests inject a stub.
+   */
+  ensureHubVersion?: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   /** Drive a per-module op against the running hub (reads operator.token). */
   driveModuleOp?: (short: string, op: ModuleOp, deps: DriveModuleOpDeps) => Promise<ModuleOpResult>;
   /**
@@ -83,6 +97,10 @@ export interface ExposeSupervisorOpts {
 export interface ResolvedExposeSupervisor {
   hubUnitDeps: HubUnitDeps;
   ensureHubUnit: (opts: EnsureHubUnitOpts) => Promise<EnsureHubUnitResult>;
+  ensureHubVersion: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   driveModuleOp: (short: string, op: ModuleOp, deps: DriveModuleOpDeps) => Promise<ModuleOpResult>;
   openDb: (configDir: string) => import("bun:sqlite").Database;
   selfHealOperatorTokenIssuer: (
@@ -105,6 +123,15 @@ export function resolveExposeSupervisor(
   return {
     hubUnitDeps,
     ensureHubUnit: opts?.ensureHubUnit ?? ensureHubUnitImpl,
+    ensureHubVersion:
+      opts?.ensureHubVersion ??
+      ((ctx) =>
+        ensureHubVersionMatchesImpl({
+          installedVersion: pkg.version,
+          port: ctx.port,
+          deps: hubUnitDeps,
+          log: ctx.log,
+        })),
     driveModuleOp: opts?.driveModuleOp ?? driveModuleOpImpl,
     openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
     selfHealOperatorTokenIssuer:
@@ -145,6 +172,24 @@ export async function ensureHubUnitForExpose(
 ): Promise<{ ok: boolean; port: number }> {
   const ensured = await sup.ensureHubUnit({ port, deps: sup.hubUnitDeps, log });
   if (ensured.outcome === "already-up" || ensured.outcome === "started") {
+    // #590: the hub is up — but is it the version we installed? A zombie that
+    // merely answers /health must not become the target of a fresh tunnel.
+    // Compare + restart-on-mismatch (once). A non-unit-managed mismatch is NOT
+    // killed: surface it + fail the expose so the operator resolves it; a
+    // still-mismatched-after-restart (bun-linked branch) warns + continues.
+    try {
+      const versionResult = await sup.ensureHubVersion({ port: ensured.port, log });
+      for (const m of versionResult.messages) log(m);
+      if (
+        versionResult.outcome === "not-unit-managed" ||
+        versionResult.outcome === "restart-failed"
+      ) {
+        return { ok: false, port: ensured.port };
+      }
+    } catch (err) {
+      // A version-check failure must never block expose — degrade to a note.
+      log(`note: hub version check skipped (${err instanceof Error ? err.message : String(err)})`);
+    }
     return { ok: true, port: ensured.port };
   }
   for (const m of ensured.messages) log(m);

package/src/commands/init.ts

@@ -35,12 +35,18 @@
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import pkg from "../../package.json" with { type: "json" };
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
 import { type EnsureHubOpts, HUB_DEFAULT_PORT, HUB_SVC, readHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { ensureHubUnit, installAndStartHubUnit } from "../hub-unit.ts";
+import {
+  type EnsureHubVersionMatchesResult,
+  ensureHubUnit,
+  ensureHubVersionMatches,
+  installAndStartHubUnit,
+} from "../hub-unit.ts";
 import { issueOperatorToken, readOperatorTokenFile } from "../operator-token.ts";
 import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { findService, readManifestLenient } from "../services-manifest.ts";
@@ -81,6 +87,18 @@ export interface InitOpts {
    * Design §3.3 (init row), §4.1/§4.2, appendix (c).
    */
   ensureHub?: (opts: EnsureHubOpts) => Promise<{ pid: number; port: number; started: boolean }>;
+  /**
+   * Test seam: version-check-and-restart at the hub adoption point (#590).
+   * After init confirms a hub is answering on the canonical port, it compares
+   * the RUNNING hub's `/health` version against this installed package version;
+   * on mismatch it restarts the managed unit (once) so a freshly-installed hub
+   * never adopts a stale zombie. Production wires `ensureHubVersionMatches`;
+   * tests stub it to assert the call without touching launchctl / the live hub.
+   */
+  ensureHubVersion?: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   /**
    * Test seam: guarantee an operator token exists once the hub is up (design
    * §3.1 / §3.3). Production reads `operator.token`; if absent AND a hub user
@@ -582,6 +600,18 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // spawn). The `ensureHub` seam is preserved for tests (and the return shape is
   // unchanged); only the production default flipped.
   const ensureHub = opts.ensureHub ?? defaultEnsureHubViaUnit;
+  // #590: after the hub is confirmed up, compare its RUNNING version to the
+  // installed package version and restart the managed unit on mismatch, so a
+  // freshly-installed hub never adopts a stale zombie that merely answers
+  // /health. Injectable for tests.
+  const ensureHubVersion =
+    opts.ensureHubVersion ??
+    ((ctx) =>
+      ensureHubVersionMatches({
+        installedVersion: pkg.version,
+        port: ctx.port,
+        log: ctx.log,
+      }));
   const guaranteeOperatorToken = opts.guaranteeOperatorToken ?? defaultGuaranteeOperatorToken;
   const readExposeStateFn = opts.readExposeStateFn ?? (() => readExposeState());
   const isTty = opts.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -640,6 +670,38 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // overridden, so the fallback is almost always correct.
   if (hubPort === undefined) hubPort = HUB_DEFAULT_PORT;
 
+  // Step 1.25 (#590): the hub answered /health, but is it the version we just
+  // installed? A zombie LaunchAgent survives `rm -rf ~/.parachute`, so a brand-
+  // new install can adopt month-old code that merely keeps the port. Compare the
+  // RUNNING version to the installed package version; on mismatch, restart the
+  // managed unit (once) so the tunnel/wizard/vault-install downstream bind to the
+  // NEW code. A non-unit-managed hub (legacy detached pid / dev `bun run serve`)
+  // is NOT killed — we surface the mismatch + an actionable message and bail so
+  // the operator decides. A still-mismatched-after-restart (bun-linked branch)
+  // warns + continues rather than looping.
+  try {
+    const versionResult = await ensureHubVersion({ port: hubPort, log });
+    for (const m of versionResult.messages) log(m);
+    if (versionResult.outcome === "not-unit-managed") {
+      // We can't safely take over a hub we don't own. Stop here so init doesn't
+      // wire a fresh tunnel + credentials to a stale runtime (the #590 field bug).
+      log("");
+      log("Resolve the version mismatch above, then re-run `parachute init`.");
+      return 1;
+    }
+    if (versionResult.outcome === "restart-failed") {
+      log("");
+      log("The hub service manager rejected the restart command.");
+      log("Try checking the logs:");
+      log("  parachute logs hub");
+      return 1;
+    }
+    // `match` / `not-running` / `restarted` / `still-mismatched` → continue.
+  } catch (err) {
+    // A version-check failure must never block init — degrade to a note.
+    log(`note: hub version check skipped (${err instanceof Error ? err.message : String(err)})`);
+  }
+
   // Step 1.5: guarantee an operator token exists (design §3.1 / §3.3). Under
   // the unified model every per-module verb is an authenticated module-ops
   // call, so the steady-state operator needs an `operator.token` on disk — the

package/src/commands/install.ts

@@ -5,7 +5,12 @@ import { autoWireScribeAuth } from "../auto-wire.ts";
 import { bunGlobalPrefixes, isLinked as defaultIsLinkedShared } from "../bun-link.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
-import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
+import {
+  HUB_DEFAULT_PORT,
+  type PidOnPortFn,
+  defaultPidOnPort,
+  readHubPort,
+} from "../hub-control.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
@@ -34,6 +39,7 @@ import {
   type DisableStaleModuleUnitsResult,
   disableStaleModuleUnits as defaultDisableStaleModuleUnits,
 } from "../stale-module-units.ts";
+import { type OwnerProbeFn, defaultOwnerOfPid } from "../supervisor.ts";
 import { WELL_KNOWN_PATH } from "../well-known.ts";
 import { type LifecycleOpts, start as lifecycleStart } from "./lifecycle.ts";
 import { migrateNotice } from "./migrate.ts";
@@ -301,6 +307,22 @@ export interface InstallOpts {
    * unless the test populates services.json directly.
    */
   portProbe?: (port: number) => Promise<boolean>;
+  /**
+   * Test seam for the install-time port-squatter naming (#590 item 2). When the
+   * canonical port walk has to assign a fallback port because the canonical one
+   * is held, this looks up the pid LISTENing on the canonical port so the
+   * warning can name the holder (`pid 1234 (bun .../vault/src/server.ts)`) — the
+   * same #581 `pidOnPort` / `ownerOfPid` seams the supervisor start-path uses,
+   * reused (not duplicated). Detection-only — never kills. Production wires
+   * `defaultPidOnPort` (`lsof -ti :<port>`); tests inject a deterministic stub.
+   */
+  pidOnPort?: PidOnPortFn;
+  /**
+   * Test seam for the install-time port-squatter naming (#590 item 2): the
+   * best-effort command line of the squatting pid. Production wires
+   * `defaultOwnerOfPid` (`ps -o command= -p <pid>`); tests inject a stub.
+   */
+  ownerOfPid?: OwnerProbeFn;
   /**
    * Test seam for reading `<packageDir>/.parachute/module.json`. Production
    * uses the real file reader; tests inject a map from package-dir → manifest
@@ -974,6 +996,25 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   });
   if (portResult.warning) {
     log(`⚠ ${portResult.warning}`);
+    // #590 item 2: the canonical port was held, so we walked to a fallback. Name
+    // the squatter — the supervisor start-path does this post-#581; do it here at
+    // install-time too. Reuse the #581 pidOnPort / ownerOfPid seams (detection
+    // only; never kill). When the holder is a foreign pid (not one of OUR rows —
+    // which is the common case when a stale pre-supervisor daemon is squatting),
+    // surface its pid + command line + a hint.
+    if (canonicalPort !== undefined && portResult.source !== "canonical") {
+      const pidOnPort = opts.pidOnPort ?? defaultPidOnPort;
+      const ownerOfPid = opts.ownerOfPid ?? defaultOwnerOfPid;
+      const holder = pidOnPort(canonicalPort);
+      if (holder !== undefined) {
+        const cmdline = ownerOfPid(holder);
+        const who = cmdline ? `pid ${holder} (${cmdline})` : `pid ${holder}`;
+        log(`  canonical port ${canonicalPort} is held by ${who}.`);
+        log(
+          `  This may be a stale pre-supervisor daemon. If so, stop it (kill ${holder}) and re-run \`parachute install ${entryName}\` to reclaim the canonical port.`,
+        );
+      }
+    }
   }
 
   // Find-or-seed the manifest entry. Re-read after the seed write so a silent

package/src/help.ts

@@ -104,7 +104,7 @@ Examples:
   parachute install vault                                   # light: installs + starts vault, points you at the admin UI
   parachute install vault --interactive                     # full interactive vault init (name / MCP / token prompts)
   parachute install surface                                 # installs surface (auto-bootstraps Notes)
-  parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
+  parachute install notes                                   # legacy notes-daemon — deprecated; use \`parachute install surface\` instead
   parachute install scribe                                  # installs, prompts for provider, starts scribe
   parachute install scribe --scribe-provider groq --scribe-key gsk_…
                                                             # non-interactive scribe setup

package/src/hub-server.ts

@@ -643,6 +643,40 @@ async function proxyToVault(
   ) {
     return new Response("not found", { status: 404 });
   }
+  // Bare `/vault/<name>` POST → point at `/vault/<name>/mcp` (#525). Operators
+  // paste the bare vault URL (no `/mcp` suffix) into MCP clients; OAuth completes
+  // against the bare path (so the client looks "connected") but the JSON-RPC POST
+  // then hits a path vault has no MCP handler for and 405s — a confusing
+  // "connected but erroring" half-state. We catch the bare-path POST here, BEFORE
+  // proxying, and 308-redirect to the canonical `<mount>/mcp`. 308 (vs 307)
+  // signals the redirect is permanent/cacheable, and like 307 it preserves the
+  // method + body, so a spec-compliant MCP client re-POSTs the JSON-RPC payload
+  // to the right endpoint and connects cleanly. Clients that DON'T follow
+  // redirects still get an actionable signal: the Location header + JSON body name
+  // the correct URL (vs the old opaque 405). Only the EXACT bare mount is caught —
+  // any sub-path (`<mount>/mcp`, `<mount>/api/...`, the Notes PWA) proxies through
+  // untouched, and only POST (the MCP transport verb) is redirected so a stray
+  // browser GET to the bare path keeps its existing proxy behavior.
+  if (req.method === "POST" && url.pathname === match.mount) {
+    const mcpUrl = `${match.mount}/mcp`;
+    const body = {
+      error: "missing_mcp_suffix",
+      message: `This is a Parachute vault path, not an MCP endpoint. Use ${mcpUrl} as your MCP server URL.`,
+      mcp_url: mcpUrl,
+    };
+    return new Response(JSON.stringify(body), {
+      status: 308,
+      headers: {
+        location: mcpUrl,
+        "content-type": "application/json",
+        // 308 is permanently cacheable by default; without no-store a client
+        // (or an intermediary) could cache the redirect and keep bouncing the
+        // bare path to `/mcp` even after a remount changes the routing. Same
+        // guard as the force-change-password redirect below.
+        "cache-control": "no-store",
+      },
+    });
+  }
   // Symmetry with proxyToService (#196): honor `stripPrefix` with FIRST_-
   // PARTY_FALLBACKS as a fallback source. No first-party vault fallback
   // declares stripPrefix today (vault expects the full `/vault/<name>/*`

package/src/hub-settings.ts

@@ -13,9 +13,9 @@
  *     client to hit `/oauth/register` *within* that window is auto-approved
  *     (single-use, the value is cleared on consume). Past-due or absent
  *     means the standard pending-approval flow applies. Motivator: a
- *     canonical onboarding (install hub → wizard → install Notes →
- *     authorize) shouldn't bounce the operator through a manual approve
- *     step they just set up the hub for.
+ *     canonical onboarding (install hub → expose → wizard installs
+ *     vault/surface → authorize) shouldn't bounce the operator through a
+ *     manual approve step they just set up the hub for.
  *
  * Schema lives in `hub-db.ts` migration v7. This module is just the typed
  * accessor — single-row reads/writes per key, no joins, no caching. The