@openparachute/hub 0.5.14-rc.13 → 0.5.14-rc.14

package/package.json

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

package/src/__tests__/expose-cloudflare.test.ts

@@ -551,6 +551,191 @@ describe("exposeCloudflareUp", () => {
     }
   });
 
+  test("hub#487: kills orphan connectors found by pgrep before spawning, not just the state pid", async () => {
+    // The orphan-accumulation bug: each re-expose spawned a fresh connector
+    // without killing prior ones, and state only tracked the most-recent pid.
+    // Orphans the state file lost track of (crashed mid-rewrite, started by
+    // hand) must still be swept — `connectorPids` finds them by UUID/config
+    // path. Here state knows pid 99999, but pgrep also surfaces 88888 + 77777
+    // serving the same tunnel; all three get SIGTERM before the new spawn.
+    const env = makeEnv();
+    try {
+      const uuid = "cccccccc-0000-0000-0000-000000000003";
+      const priorRecord: CloudflaredTunnelRecord = {
+        pid: 99999,
+        tunnelUuid: uuid,
+        tunnelName: "parachute",
+        hostname: "vault.example.com",
+        startedAt: "2026-04-21T00:00:00.000Z",
+        configPath: env.configPath,
+      };
+      writeCloudflaredState({ version: 2, tunnels: { parachute: priorRecord } }, env.statePath);
+
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" }, // route dns
+      ]);
+      const { spawner, seen } = fakeSpawner(42010);
+      const killed: number[] = [];
+
+      const code = await exposeCloudflareUp("vault.example.com", {
+        runner,
+        spawner,
+        alive: () => true, // all candidate pids report alive
+        kill: (pid) => killed.push(pid),
+        // pgrep surfaces two orphans the state record didn't track.
+        connectorPids: () => [88888, 77777],
+        resolveHost: async () => ["104.16.0.1"], // Cloudflare — no DNS warning
+        log: () => {},
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      // Every prior connector (state pid + both pgrep orphans) is stopped
+      // before the new one spawns.
+      expect(killed.sort()).toEqual([77777, 88888, 99999]);
+      // Exactly one fresh connector spawned, and it's the one recorded.
+      expect(seen).toHaveLength(1);
+      expect(findTunnelRecord(readCloudflaredState(env.statePath), "parachute")?.pid).toBe(42010);
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: warns when DNS doesn't resolve yet (pending zone)", async () => {
+    // route dns succeeded but the hostname doesn't resolve — the "pending"
+    // zone shape (NS not switched at the registrar). Non-fatal: still exit 0,
+    // still print the URLs, but add the nameserver-switch nudge.
+    const env = makeEnv();
+    try {
+      const uuid = "dddddddd-0000-0000-0000-000000000004";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42020);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("vault.newzone.com", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => [], // NXDOMAIN / not live yet
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0); // non-fatal — the expose still completes
+      const joined = logs.join("\n");
+      expect(joined).toContain("DNS isn't live yet for vault.newzone.com");
+      expect(joined).toContain("dig +short newzone.com NS");
+      expect(joined).toContain("ns.cloudflare.com");
+      // The success URLs still print.
+      expect(joined).toContain("https://vault.newzone.com/admin/");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: warns when hostname resolves but not to Cloudflare (shadowed)", async () => {
+    // route dns succeeded but the hostname resolves to a non-Cloudflare IP —
+    // a Pages project / grey-cloud A record shadowing the tunnel → edge 404.
+    const env = makeEnv();
+    try {
+      const uuid = "eeeeeeee-0000-0000-0000-000000000006";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42021);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("docs.parachute.computer", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => ["203.0.113.10"], // not a Cloudflare range
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("not to Cloudflare's edge");
+      expect(joined).toContain("shadowed");
+      expect(joined).toContain("Pages project");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: no DNS warning when hostname resolves at Cloudflare's edge", async () => {
+    const env = makeEnv();
+    try {
+      const uuid = "ffffffff-0000-0000-0000-000000000007";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42022);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("vault.example.com", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => ["104.18.32.7"], // 104.16.0.0/13 — Cloudflare
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).not.toContain("DNS isn't live yet");
+      expect(joined).not.toContain("not to Cloudflare's edge");
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("two tunnels with different --tunnel-name coexist in state", async () => {
     const env = makeEnv();
     try {
@@ -929,6 +1114,46 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
+  test("hub#487: off sweeps orphan connectors the state record didn't track", async () => {
+    const env = makeEnv();
+    try {
+      const uuid = "abababab-0000-0000-0000-000000000009";
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            parachute: {
+              pid: 55555,
+              tunnelUuid: uuid,
+              tunnelName: "parachute",
+              hostname: "vault.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+      const killed: number[] = [];
+      const code = await exposeCloudflareOff({
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => true,
+        kill: (pid) => killed.push(pid),
+        // pgrep finds the tracked pid (skipped — already signalled) plus an
+        // untracked orphan 66666 serving the same tunnel.
+        connectorPids: () => [55555, 66666],
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      // Tracked pid stopped once, orphan also stopped — no double-kill of 55555.
+      expect(killed.sort()).toEqual([55555, 66666]);
+      expect(existsSync(env.statePath)).toBe(false);
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("targets the named tunnel and leaves siblings intact", async () => {
     const env = makeEnv();
     try {

package/src/__tests__/lifecycle.test.ts

@@ -783,6 +783,159 @@ describe("parachute start", () => {
       h.cleanup();
     }
   });
+
+  // hub#487 — readiness gating beyond the bare liveness settle. Aaron hit this
+  // on a fresh EC2 box: `parachute start vault` printed "✓ vault started" while
+  // the process died ~instantly on EADDRINUSE (an orphan held 1940), and
+  // `parachute status` then showed it inactive.
+
+  /**
+   * A stub spawner that also seeds the service's log file with `content`, so
+   * the readiness-failure path's log-tail + EADDRINUSE detection can read a
+   * realistic boot error. Mirrors how the real spawner appends stdout/stderr
+   * to the logfile.
+   */
+  function makeSpawnerWithLog(pid: number, content: string): SpawnerStub {
+    const calls: SpawnerStub["calls"] = [];
+    return {
+      calls,
+      spawn(cmd, logFile, opts) {
+        calls.push({ cmd: [...cmd], logFile, env: opts?.env, cwd: opts?.cwd });
+        // The start path calls ensureLogPath() before spawn, so logFile's
+        // parent dir already exists — just write the simulated boot output.
+        writeFileSync(logFile, content);
+        return pid;
+      },
+    };
+  }
+
+  test("hub#487: EADDRINUSE in the log → port-in-use message + log tail, not ✓", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawnerWithLog(
+        4242,
+        "booting vault…\nerror: listen EADDRINUSE: address already in use 0.0.0.0:1940\n",
+      );
+      const lines: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => false, // process died right after the EADDRINUSE throw
+        sleep: async () => {},
+        startSettleMs: 1,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(readPid("vault", h.configDir)).toBeUndefined();
+      const out = lines.join("\n");
+      expect(out).toMatch(/port 1940 is already in use/);
+      expect(out).toMatch(/lsof -ti:1940/);
+      // The real boot error is surfaced inline so the operator doesn't have to
+      // go tail the log themselves.
+      expect(out).toMatch(/EADDRINUSE/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#487: process survives settle but never binds its port → failure with log tail", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawnerWithLog(4242, "vault crashed mid-boot\n");
+      const lines: string[] = [];
+      let aliveCalls = 0;
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        // Alive through the settle + first readiness poll, then dies — the
+        // slow-EADDRINUSE / crash-after-boot shape.
+        alive: () => {
+          aliveCalls++;
+          return aliveCalls <= 1;
+        },
+        sleep: async () => {},
+        startSettleMs: 1,
+        startReadyMs: 50,
+        startReadyPollMs: 1,
+        portListening: async () => false, // never binds
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(readPid("vault", h.configDir)).toBeUndefined();
+      const out = lines.join("\n");
+      expect(out).toMatch(/✗ vault failed to start/);
+      expect(out).toMatch(/exited during startup/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#487: alive but port silent past the window → non-fatal warning, exit 0", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const lines: string[] = [];
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => true, // stays up the whole time
+        sleep: async () => {},
+        startSettleMs: 1,
+        startReadyMs: 10,
+        startReadyPollMs: 1,
+        portListening: async () => false, // slow boot — not listening yet
+        log: (l) => lines.push(l),
+      });
+      // A slow-but-alive daemon isn't a hard failure — we warn rather than fail.
+      expect(code).toBe(0);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+      const out = lines.join("\n");
+      expect(out).toMatch(/port 1940 isn't accepting connections yet/);
+      expect(out).not.toMatch(/✓ vault started/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("hub#487: alive + port listening → success", async () => {
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const spawner = makeSpawner([4242]);
+      const lines: string[] = [];
+      let probeCalls = 0;
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        alive: () => true,
+        sleep: async () => {},
+        startSettleMs: 1,
+        startReadyMs: 50,
+        startReadyPollMs: 1,
+        // Not listening on the first poll, bound on the second — exercises the
+        // poll loop rather than an instant true.
+        portListening: async () => {
+          probeCalls++;
+          return probeCalls >= 2;
+        },
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(readPid("vault", h.configDir)).toBe(4242);
+      expect(lines.join("\n")).toMatch(/✓ vault started \(pid 4242\)/);
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 describe("parachute stop", () => {

package/src/commands/expose-cloudflare.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";
 import { DEFAULT_TUNNEL_NAME, cloudflaredPathsFor, writeConfig } from "../cloudflare/config.ts";
@@ -100,11 +101,159 @@ const defaultKill: KillFn = (pid, signal) => {
   process.kill(pid, signal);
 };
 
+/**
+ * Find the PIDs of every running `cloudflared` connector serving THIS tunnel.
+ * "This tunnel" is identified by either the tunnel UUID or the config.yml path
+ * appearing on the process command line — both are unique to Parachute's
+ * connector for this tunnel, so we never touch an unrelated cloudflared the
+ * operator may be running for a different tunnel.
+ *
+ * The motivating bug (hub#487): each `parachute expose public --cloudflare`
+ * "reused the tunnel" but spawned a fresh connector (new pid) without killing
+ * the prior ones, and the state file only tracked the most-recent pid. Orphan
+ * connectors accumulated — multiple `cloudflared tunnel run` processes all
+ * serving stale `config.yml` snapshots, so edge routing became nondeterministic
+ * ("silent fails"). Sweeping by UUID/config-path catches the orphans that the
+ * single-pid state record misses (prior runs that crashed mid-rewrite, or a
+ * connector the operator started by hand for this tunnel).
+ *
+ * Injectable so tests assert the sweep without a live `pgrep`.
+ */
+export type ConnectorPidsFn = (tunnelUuid: string, configPath: string) => number[];
+
+export const defaultConnectorPids: ConnectorPidsFn = (tunnelUuid, configPath) => {
+  try {
+    // `pgrep -fl cloudflared` lists "<pid> <full command line>" for every
+    // process whose command line matches "cloudflared". We then filter to the
+    // ones that name THIS tunnel (uuid or config path) so the kill is surgical.
+    // macOS + Linux ship pgrep; Windows is out of scope (mirrors hub#287's lsof
+    // assumption). Any failure → [] (caller falls back to state-tracked pid).
+    const result = spawnSync("pgrep", ["-fl", "cloudflared"], {
+      encoding: "utf8",
+      timeout: 2000,
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") return [];
+    const selfPid = process.pid;
+    const pids: number[] = [];
+    for (const line of result.stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      const match = trimmed.match(/^(\d+)\s+(.*)$/);
+      if (!match) continue;
+      const pid = Number.parseInt(match[1]!, 10);
+      const cmdline = match[2]!;
+      if (!Number.isInteger(pid) || pid <= 0 || pid === selfPid) continue;
+      // Surgical match: only connectors that name this tunnel's UUID or its
+      // config path. A bare `cloudflared` (e.g. `--version`, `tunnel list`)
+      // or a connector for a *different* tunnel won't match either token.
+      if (cmdline.includes(tunnelUuid) || cmdline.includes(configPath)) {
+        pids.push(pid);
+      }
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Resolve a hostname to its A/AAAA addresses. Returns [] when the name doesn't
+ * resolve (NXDOMAIN, SERVFAIL, no records yet) — the signal the DNS
+ * self-diagnosis keys on. Injectable so tests drive each case (unresolved /
+ * Cloudflare / non-Cloudflare) deterministically.
+ */
+export type ResolveHostFn = (hostname: string) => Promise<string[]>;
+
+export const defaultResolveHost: ResolveHostFn = async (hostname) => {
+  try {
+    // Bun.dns ships with the runtime; `node:dns/promises` is equally fine but
+    // Bun.dns.lookup returns both families in one call. `all: true` gives every
+    // record so a partially-propagated name still surfaces an address.
+    const records = await Bun.dns.lookup(hostname, { family: 0 });
+    return records.map((r) => r.address).filter((a) => typeof a === "string" && a.length > 0);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Cloudflare's published anycast IPv4 ranges (the proxy edge). A proxied
+ * (orange-cloud) record — which is what `cloudflared tunnel route dns` creates
+ * — resolves to one of these. If the hostname resolves to something *outside*
+ * these ranges, it's almost certainly shadowed: a Pages project, an A record,
+ * or a grey-cloud CNAME pointing elsewhere. We keep the list to the v4 ranges
+ * (the common case) and treat any IPv6 in Cloudflare's 2606:4700::/32 block as
+ * Cloudflare too. Source: https://www.cloudflare.com/ips/ (stable for years).
+ */
+const CLOUDFLARE_V4_RANGES: ReadonlyArray<readonly [string, number]> = [
+  ["173.245.48.0", 20],
+  ["103.21.244.0", 22],
+  ["103.22.200.0", 22],
+  ["103.31.4.0", 22],
+  ["141.101.64.0", 18],
+  ["108.162.192.0", 18],
+  ["190.93.240.0", 20],
+  ["188.114.96.0", 20],
+  ["197.234.240.0", 22],
+  ["198.41.128.0", 17],
+  ["162.158.0.0", 15],
+  ["104.16.0.0", 13],
+  ["104.24.0.0", 14],
+  ["172.64.0.0", 13],
+  ["131.0.72.0", 22],
+];
+
+function ipv4ToInt(ip: string): number | undefined {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return undefined;
+  let n = 0;
+  for (const part of parts) {
+    const octet = Number.parseInt(part, 10);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) return undefined;
+    n = n * 256 + octet;
+  }
+  return n >>> 0;
+}
+
+/** True if any resolved address belongs to Cloudflare's edge. */
+export function looksLikeCloudflare(addresses: readonly string[]): boolean {
+  for (const addr of addresses) {
+    // IPv6: Cloudflare's edge lives in 2606:4700::/32.
+    if (addr.includes(":")) {
+      if (addr.toLowerCase().startsWith("2606:4700")) return true;
+      continue;
+    }
+    const ipInt = ipv4ToInt(addr);
+    if (ipInt === undefined) continue;
+    for (const [base, bits] of CLOUDFLARE_V4_RANGES) {
+      const baseInt = ipv4ToInt(base);
+      if (baseInt === undefined) continue;
+      const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+      if ((ipInt & mask) === (baseInt & mask)) return true;
+    }
+  }
+  return false;
+}
+
 export interface ExposeCloudflareOpts {
   runner?: Runner;
   spawner?: CloudflaredSpawner;
   alive?: AliveFn;
   kill?: KillFn;
+  /**
+   * Find every running cloudflared connector PID serving this tunnel (by UUID
+   * or config-path match). Used to sweep orphan connectors before spawning a
+   * fresh one (hub#487). Tests inject a stub; production uses
+   * `defaultConnectorPids` (a filtered `pgrep -fl cloudflared`).
+   */
+  connectorPids?: ConnectorPidsFn;
+  /**
+   * Resolve a hostname to its addresses, for the post-route DNS self-diagnosis
+   * (hub#487). Returns the resolved IPs (empty when NXDOMAIN / not yet live).
+   * Best-effort and non-fatal — a failure to resolve never blocks the expose.
+   * Tests inject a stub; production uses `defaultResolveHost` (Bun DNS).
+   */
+  resolveHost?: ResolveHostFn;
   log?: (line: string) => void;
   manifestPath?: string;
   statePath?: string;
@@ -186,6 +335,8 @@ interface Resolved {
   spawner: CloudflaredSpawner;
   alive: AliveFn;
   kill: KillFn;
+  connectorPids: ConnectorPidsFn;
+  resolveHost: ResolveHostFn;
   log: (line: string) => void;
   manifestPath: string;
   statePath: string;
@@ -217,6 +368,17 @@ function resolve(opts: ExposeCloudflareOpts): Resolved {
     spawner: opts.spawner ?? defaultCloudflaredSpawner,
     alive: opts.alive ?? defaultAlive,
     kill: opts.kill ?? defaultKill,
+    // Defaulting policy mirrors lifecycle's startReadyMs (hub#487): the real
+    // implementations shell out (`pgrep`) / hit the network (DNS). When a test
+    // injects a fake `spawner` but no explicit seam, fall back to inert stubs
+    // (no orphans found; "resolves at Cloudflare" → no DNS warning) so suites
+    // stay deterministic and offline. Production (no spawner override) always
+    // gets the real `pgrep` sweep + DNS diagnosis.
+    connectorPids:
+      opts.connectorPids ?? (opts.spawner === undefined ? defaultConnectorPids : () => []),
+    resolveHost:
+      opts.resolveHost ??
+      (opts.spawner === undefined ? defaultResolveHost : async () => ["104.16.0.1"]),
     log: opts.log ?? ((line) => console.log(line)),
     manifestPath: opts.manifestPath ?? SERVICES_MANIFEST_PATH,
     statePath: opts.statePath ?? CLOUDFLARED_STATE_PATH,
@@ -261,6 +423,49 @@ function printAuthGuidance(log: (line: string) => void, vaultUrl: string): void
   log(`  ${AUTH_DOC_URL}`);
 }
 
+/**
+ * Best-effort registrable-zone guess: the last two labels of the hostname
+ * (`vault.example.com` → `example.com`, `gitcoin.parachute.computer` →
+ * `parachute.computer`). This is a heuristic — multi-label public suffixes
+ * (`foo.co.uk`) would guess `co.uk` — but it's only used to phrase the
+ * `dig +short <zone> NS` remedy, where being off by a label is a harmless
+ * nudge. We don't ship a full public-suffix list for one warning string.
+ */
+function guessZone(hostname: string): string {
+  const labels = hostname.split(".").filter((l) => l.length > 0);
+  if (labels.length <= 2) return hostname;
+  return labels.slice(-2).join(".");
+}
+
+/**
+ * Non-fatal post-route DNS diagnosis. Resolves `hostname` and warns when the
+ * result looks wrong — see the call site for the two symptoms this addresses.
+ * Never throws (resolveHost swallows its own errors) and never changes the
+ * exit code; the worst case is no output.
+ */
+async function diagnoseDns(hostname: string, r: Resolved): Promise<void> {
+  const zone = guessZone(hostname);
+  const addresses = await r.resolveHost(hostname);
+  if (addresses.length === 0) {
+    r.log("");
+    r.log(`⚠ DNS isn't live yet for ${hostname}.`);
+    r.log(`  If ${zone} is a new Cloudflare zone, its nameservers may not be switched at your`);
+    r.log("  registrar yet. Check with:");
+    r.log(`    dig +short ${zone} NS          # should list *.ns.cloudflare.com`);
+    r.log("  Propagation can take minutes to hours. The tunnel itself is up — the URLs below");
+    r.log("  will start working once DNS resolves.");
+    return;
+  }
+  if (!looksLikeCloudflare(addresses)) {
+    r.log("");
+    r.log(`⚠ ${hostname} resolves (${addresses.join(", ")}) but not to Cloudflare's edge.`);
+    r.log(`  It may be shadowed by another DNS record or a Cloudflare Pages project on ${zone}.`);
+    r.log("  Ensure it's a proxied (orange-cloud) CNAME to the tunnel — check");
+    r.log(`  https://dash.cloudflare.com → DNS for ${zone}. A grey-cloud / A record / Pages`);
+    r.log("  binding on this hostname will 404 the tunnel at the edge.");
+  }
+}
+
 export async function exposeCloudflareUp(
   hostname: string,
   opts: ExposeCloudflareOpts = {},
@@ -390,6 +595,19 @@ export async function exposeCloudflareUp(
   }
   r.log("✓ DNS routed.");
 
+  // Post-route DNS self-diagnosis (hub#487). `cloudflared tunnel route dns`
+  // can succeed (the CNAME is written in Cloudflare's API) while the hostname
+  // is still NOT actually serving the tunnel — two shapes Aaron hit:
+  //   (a) a "pending" zone whose nameservers aren't switched at the registrar
+  //       yet, so the record exists in Cloudflare but nothing resolves; and
+  //   (b) a subdomain shadowed by a Cloudflare Pages project on the same zone,
+  //       so the edge 404s the tunnel.
+  // Both previously printed "✓ DNS routed" + the URLs as if fine. This check
+  // is best-effort and strictly NON-FATAL — it only adds a warning; it never
+  // changes the exit code or blocks the expose. Fast: one DNS lookup with a
+  // built-in timeout in `resolveHost`.
+  await diagnoseDns(hostname, r);
+
   const credsFile = credentialsPath(tunnel.id, r.cloudflaredHome);
   writeConfig(
     {
@@ -408,12 +626,28 @@ export async function exposeCloudflareUp(
   );
   r.log(`✓ Wrote ${r.configPath}`);
 
+  // Orphan-connector sweep (hub#487). Before spawning a fresh connector, kill
+  // EVERY cloudflared connector currently serving this tunnel so exactly one
+  // process serves the config.yml we just wrote. Pre-fix, each re-expose
+  // spawned a new connector without killing the prior ones (state tracked only
+  // the most-recent pid), so orphans accumulated and edge routing became
+  // nondeterministic. We union two sources:
+  //   - the pid recorded in cloudflared-state.json (the prior `parachute`-
+  //     spawned connector for this tunnel name), and
+  //   - any pid found by scanning running processes for this tunnel's UUID or
+  //     config path (catches orphans the state file lost track of — crashed
+  //     mid-rewrite, or started by hand for this tunnel).
   const stateBefore = readCloudflaredState(r.statePath);
   const prior = findTunnelRecord(stateBefore, r.tunnelName);
-  if (prior && r.alive(prior.pid)) {
+  const toKill = new Set<number>();
+  if (prior && r.alive(prior.pid)) toKill.add(prior.pid);
+  for (const pid of r.connectorPids(tunnel.id, r.configPath)) {
+    if (r.alive(pid)) toKill.add(pid);
+  }
+  for (const deadPid of toKill) {
     try {
-      r.kill(prior.pid, "SIGTERM");
-      r.log(`Stopped prior cloudflared (pid ${prior.pid}).`);
+      r.kill(deadPid, "SIGTERM");
+      r.log(`Stopped prior cloudflared connector (pid ${deadPid}).`);
     } catch {
       // Process is already gone — safe to ignore; we replace the record below.
     }
@@ -530,6 +764,18 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   } else {
     r.log(`cloudflared (pid ${record.pid}) wasn't running; clearing stale state.`);
   }
+  // Sweep any orphan connectors for this tunnel that the state record didn't
+  // track (hub#487) so `off` leaves exactly zero connectors serving it. Match
+  // by UUID/config-path; skip the record pid we already signalled above.
+  for (const orphanPid of r.connectorPids(record.tunnelUuid, record.configPath)) {
+    if (orphanPid === record.pid || !r.alive(orphanPid)) continue;
+    try {
+      r.kill(orphanPid, "SIGTERM");
+      r.log(`✓ Stopped orphan cloudflared connector (pid ${orphanPid}).`);
+    } catch {
+      // Already gone between probe and kill — fine.
+    }
+  }
   const stateAfter = withoutTunnelRecord(stateBefore, r.tunnelName);
   if (stateAfter) {
     writeCloudflaredState(stateAfter, r.statePath);

package/src/commands/lifecycle.ts

@@ -1,4 +1,5 @@
-import { existsSync, openSync } from "node:fs";
+import { existsSync, openSync, readFileSync } from "node:fs";
+import { Socket } from "node:net";
 import { join } from "node:path";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { readEnvFileValues } from "../env-file.ts";
@@ -84,6 +85,44 @@ export const defaultSpawner: Spawner = {
 export type KillFn = (pid: number, signal: NodeJS.Signals | number) => void;
 export type SleepFn = (ms: number) => Promise<void>;
 
+/**
+ * "Is something listening on this TCP port on loopback?" seam. Pairs with the
+ * spawn-then-die settle (hub#194) to catch the *other* silent-start failure
+ * shape (hub#487): a service that lives long enough to clear the liveness
+ * check but never binds its port because the port is already held (EADDRINUSE
+ * from an orphan). The recorded pid stays alive (vault's process supervisor
+ * retries / lingers) so `alive(pid)` says "running" while `parachute status`
+ * shows it inactive because nothing answers on the port.
+ *
+ * Tests inject a deterministic stub; production uses `defaultPortListening`.
+ */
+export type PortListeningFn = (port: number) => Promise<boolean>;
+
+/**
+ * Connect-probe: open a TCP socket to 127.0.0.1:<port> and see if it's
+ * accepted. A successful connect means *something* is listening; we close
+ * immediately. Connection refused / timeout means nothing is bound yet.
+ * `node:net` rather than `Bun.connect` because the latter has no clean
+ * "connection refused → false" without a custom socket handler, and the net
+ * Socket's `error`/`connect` events map directly onto the boolean we want.
+ */
+export const defaultPortListening: PortListeningFn = (port) =>
+  new Promise((resolve) => {
+    const socket = new Socket();
+    let settled = false;
+    const done = (listening: boolean) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(listening);
+    };
+    socket.setTimeout(1000);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+    socket.connect(port, "127.0.0.1");
+  });
+
 /**
  * Group-aware liveness: returns true if the process group (pgid == pid)
  * still has any member. Pairs with `defaultSpawner`'s `detached: true` —
@@ -130,6 +169,35 @@ export const defaultKill: KillFn = (pid, signal) => {
 
 export const defaultSleep: SleepFn = (ms) => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * Read the trailing `n` lines of a logfile, best-effort. Used to surface the
+ * real boot error when a start fails — operators shouldn't have to manually
+ * `tail` the log to learn *why* the daemon died. Returns [] on any read
+ * error (missing file, permissions) so the caller falls back to the generic
+ * "tail the log" hint without throwing.
+ */
+function readLogTail(logFile: string, n: number): string[] {
+  try {
+    const content = readFileSync(logFile, "utf8");
+    const trimmed = content.replace(/\n$/, "");
+    if (trimmed === "") return [];
+    return trimmed.split("\n").slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Heuristic EADDRINUSE detector over a logfile tail. cloudflared, Bun, and
+ * Node all surface port collisions with recognizable phrases; we match the
+ * common ones rather than parse a structured error (there isn't one across
+ * runtimes). False positives are harmless — the worst case is we *also* print
+ * the port-in-use remedy on an unrelated failure, which is still actionable.
+ */
+function detectAddrInUse(logTail: readonly string[]): boolean {
+  return logTail.some((line) => /EADDRINUSE|address already in use|port .* in use/i.test(line));
+}
+
 export interface LifecycleOpts {
   spawner?: Spawner;
   kill?: KillFn;
@@ -161,6 +229,30 @@ export interface LifecycleOpts {
    * settle.
    */
   startSettleMs?: number;
+  /**
+   * Probe whether the service's port is listening, post-spawn. Pairs with the
+   * settle (hub#194) to catch the EADDRINUSE-orphan shape (hub#487): the
+   * process survives the liveness window (vault lingers / retries) but never
+   * binds because the port is already held, so `start` would otherwise report
+   * "✓ started" while `status` shows it inactive. Tests inject a stub;
+   * production uses `defaultPortListening` (a loopback TCP connect probe).
+   */
+  portListening?: PortListeningFn;
+  /**
+   * How long `start` polls for the service to bind its port after the
+   * liveness settle passes. Default 4000ms in production — long enough to
+   * cover vault/scribe cold-boot (DB open, route registration) without making
+   * a healthy start feel laggy. Polled at `startReadyPollMs` intervals; the
+   * first time the port answers we declare success. If the window elapses
+   * with the process still alive but the port silent, we print a non-fatal
+   * warning (the daemon may still be coming up) rather than failing — only a
+   * *dead* process is a hard failure. Defaulting policy mirrors
+   * `startSettleMs`: 0 (skipped) unless `portListening` is injected or the
+   * production path (no spawner override) is active.
+   */
+  startReadyMs?: number;
+  /** Poll interval while waiting for the port to come up. Default 200ms. */
+  startReadyPollMs?: number;
   /**
    * Override the hub origin passed to services as PARACHUTE_HUB_ORIGIN. If
    * unset, `start` derives it from `expose-state.json` (when exposed) or
@@ -194,6 +286,9 @@ interface Resolved {
   killWaitMs: number;
   pollIntervalMs: number;
   startSettleMs: number;
+  portListening: PortListeningFn;
+  startReadyMs: number;
+  startReadyPollMs: number;
   hubOrigin: string | undefined;
   ensureHub: (opts: EnsureHubOpts) => Promise<EnsureHubResult>;
   stopHubFn: (opts: StopHubOpts) => Promise<boolean>;
@@ -220,6 +315,16 @@ function resolve(opts: LifecycleOpts): Resolved {
     // override `alive`, which re-enables the default 250ms.
     startSettleMs:
       opts.startSettleMs ?? (opts.spawner === undefined || opts.alive !== undefined ? 250 : 0),
+    portListening: opts.portListening ?? defaultPortListening,
+    // Same defaulting policy as startSettleMs: production (no spawner
+    // override) gets the real 4s readiness window; tests that inject a stub
+    // spawner get 0 (skipped) unless they explicitly opt in via
+    // `portListening` or `startReadyMs`, so existing stub-spawner tests don't
+    // start probing a fake port.
+    startReadyMs:
+      opts.startReadyMs ??
+      (opts.spawner === undefined || opts.portListening !== undefined ? 4000 : 0),
+    startReadyPollMs: opts.startReadyPollMs ?? 200,
     hubOrigin: resolveHubOrigin(opts.hubOrigin, configDir),
     ensureHub: opts.hub?.ensureRunning ?? ensureHubRunning,
     stopHubFn: opts.hub?.stop ?? stopHub,
@@ -464,21 +569,97 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
     }
     writePid(short, pid, r.configDir);
 
-    // Settle-poll for spawn-then-immediately-die (hub#194). A spawn returning
-    // a pid only proves the kernel forked the process; the child may exit
-    // microseconds later if its main code path throws before listening
-    // (e.g. notes-serve's Bun.resolveSync failing for bun-linked installs).
-    // Without this poll, we'd report success and the operator would chase
-    // a phantom 502.
+    // Boot-readiness gating (hub#194 + hub#487). A spawn returning a pid only
+    // proves the kernel forked the process — it says nothing about whether the
+    // service survived its boot or bound its port. Two silent-start shapes:
+    //
+    //   (1) spawn-then-immediately-die (hub#194): the child throws before
+    //       listening (notes-serve's Bun.resolveSync failing for bun-linked
+    //       installs) and exits microseconds later. Caught by the settle below.
+    //
+    //   (2) alive-but-never-bound (hub#487): the port is already held by an
+    //       orphan, the child hits EADDRINUSE, but its process *lingers* (or a
+    //       supervisor retries) long enough to clear the liveness check. `start`
+    //       would report "✓ started" while `parachute status` shows it inactive
+    //       because nothing answers on the port. Aaron hit exactly this with an
+    //       orphan holding vault's 1940 on a fresh EC2 box. Caught by the
+    //       port-readiness poll below.
+    //
+    // On any failure we surface the tail of the logfile so the operator sees
+    // the real boot error inline, and we specifically call out EADDRINUSE with
+    // the `lsof -ti:<port>` remedy.
+    const reportStartFailure = (reason: string): void => {
+      clearPid(short, r.configDir);
+      failures++;
+      const tail = readLogTail(logFile, 20);
+      if (detectAddrInUse(tail)) {
+        r.log(
+          `✗ ${short} failed to start: port ${entry.port} is already in use. Stop the existing process first — find it with \`lsof -ti:${entry.port}\` (then \`kill <pid>\`), or run \`parachute restart ${short}\`.`,
+        );
+      } else {
+        r.log(`✗ ${short} failed to start: ${reason}`);
+      }
+      if (tail.length > 0) {
+        r.log(`  ── last ${tail.length} log line(s) (${logFile}) ──`);
+        for (const line of tail) r.log(`  │ ${line}`);
+      } else {
+        r.log(`  Tail the log for details: tail -50 ${logFile}`);
+      }
+    };
+
     if (r.startSettleMs > 0) {
       await r.sleep(r.startSettleMs);
       if (!r.alive(pid)) {
-        clearPid(short, r.configDir);
-        failures++;
+        reportStartFailure(
+          `spawned pid ${pid} but the process exited within ${r.startSettleMs}ms.`,
+        );
+        continue;
+      }
+    }
+
+    // Port-readiness poll (hub#487). The process is alive; now confirm it
+    // actually bound its port before claiming success. Poll up to
+    // `startReadyMs`, re-checking liveness each iteration so a *later* death
+    // (e.g. a slow EADDRINUSE crash) is still reported as a failure. A process
+    // that stays alive but never binds within the window gets a non-fatal
+    // warning rather than a hard failure — some daemons legitimately do slow
+    // boot work, and we'd rather not flip a healthy-but-slow start to red.
+    if (r.startReadyMs > 0) {
+      const deadline = r.now() + r.startReadyMs;
+      let listening = false;
+      let died = false;
+      while (r.now() < deadline) {
+        if (!r.alive(pid)) {
+          died = true;
+          break;
+        }
+        if (await r.portListening(entry.port)) {
+          listening = true;
+          break;
+        }
+        await r.sleep(r.startReadyPollMs);
+      }
+      if (died) {
+        reportStartFailure(`spawned pid ${pid} but the process exited during startup.`);
+        continue;
+      }
+      if (!listening) {
+        // Last-chance liveness check — the loop may have exited on the
+        // deadline right as the process died.
+        if (!r.alive(pid)) {
+          reportStartFailure(`spawned pid ${pid} but the process exited during startup.`);
+          continue;
+        }
         r.log(
-          `✗ ${short} failed to start: spawned pid ${pid} but the process exited within ${r.startSettleMs}ms.`,
+          `⚠ ${short} started (pid ${pid}) but port ${entry.port} isn't accepting connections yet after ${r.startReadyMs}ms.`,
         );
-        r.log(`  Tail the log for details: tail -50 ${logFile}`);
+        r.log(
+          `  It may still be coming up — check \`parachute status\` and \`parachute logs ${short}\`.`,
+        );
+        if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
+        if (short === "vault" && r.hubOrigin) {
+          persistVaultHubOrigin(r.configDir, r.hubOrigin, r.log);
+        }
         continue;
       }
     }