@openparachute/vault 0.1.0 → 0.2.1

package/src/daemon.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared daemon-wrapper plumbing used by the macOS launchd and Linux
+ * systemd install paths.
+ *
+ * Rationale: both platforms historically hardcoded the absolute path to
+ * `src/server.ts` into their respective service/wrapper files at init
+ * time. When the repo moved, the service kept respawning bun on a missing
+ * file and crash-looped silently into `~/.parachute/vault.err`.
+ *
+ * The fix: a small bash wrapper (`~/.parachute/start.sh`) and a pointer
+ * file (`~/.parachute/server-path`) that the wrapper reads at every boot.
+ * Moving the repo now only requires re-running `parachute vault init` —
+ * no plist/unit re-registration needed. Callers can override the path for
+ * a single boot via `PARACHUTE_VAULT_SERVER_PATH` in `~/.parachute/.env`.
+ */
+
+import { homedir } from "os";
+import { join, resolve, dirname } from "path";
+import { writeFile, unlink } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { CONFIG_DIR, ENV_PATH } from "./config.ts";
+
+/** Start-up script sourced by launchd and systemd alike. */
+export const WRAPPER_PATH = join(CONFIG_DIR, "start.sh");
+/** Pointer file. Contents: absolute path to `server.ts`, one line. */
+export const SERVER_PATH_FILE = join(CONFIG_DIR, "server-path");
+
+/**
+ * Build the start.sh contents. Pure string builder — easy to assert on.
+ *
+ * The generated script:
+ *   1. Sources the user's login shell profiles to pick up PATH (needed
+ *      when the daemon shells out to tools like ffmpeg, parakeet-mlx).
+ *   2. Sources ~/.parachute/.env.
+ *   3. Resolves the server path: env override first, then pointer file.
+ *   4. Fails loudly with an actionable message if the path is missing or
+ *      the target file doesn't exist — instead of silently respawning
+ *      into a crash loop the way a bare `bun /missing/path` would.
+ *   5. Execs bun against the resolved server path.
+ */
+export function generateWrapper(opts: {
+  bunPath: string;
+  envPath?: string;
+  serverPathFile?: string;
+}): string {
+  const envPath = opts.envPath ?? ENV_PATH;
+  const pointer = opts.serverPathFile ?? SERVER_PATH_FILE;
+  return `#!/bin/bash
+# Auto-generated by \`parachute vault init\`. Do not edit by hand — edits
+# are clobbered on the next init. To override the server path for a
+# single boot, set PARACHUTE_VAULT_SERVER_PATH in ~/.parachute/.env.
+# To point at a different repo permanently, re-run \`parachute vault init\`
+# from that repo.
+
+set -u
+
+# Source user shell profile for PATH (needed for parakeet-mlx, ffmpeg, etc.)
+[ -f "$HOME/.zprofile" ] && source "$HOME/.zprofile" 2>/dev/null
+[ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc" 2>/dev/null
+
+if [ -f "${envPath}" ]; then
+  set -a
+  source "${envPath}"
+  set +a
+fi
+
+# Resolve server path: env override wins, then pointer file written by init.
+SERVER_PATH="\${PARACHUTE_VAULT_SERVER_PATH:-}"
+if [ -z "$SERVER_PATH" ] && [ -f "${pointer}" ]; then
+  SERVER_PATH=$(cat "${pointer}")
+fi
+
+if [ -z "$SERVER_PATH" ]; then
+  echo "parachute-vault: server path not configured (no ${pointer} and PARACHUTE_VAULT_SERVER_PATH is unset)." >&2
+  echo "parachute-vault: run \\\`parachute vault init\\\` to configure it." >&2
+  exit 1
+fi
+
+if [ ! -f "$SERVER_PATH" ]; then
+  echo "parachute-vault: server.ts not found at $SERVER_PATH" >&2
+  echo "parachute-vault: the repo may have moved. Run \\\`parachute vault init\\\` from the current repo location." >&2
+  exit 1
+fi
+
+exec "${opts.bunPath}" "$SERVER_PATH"
+`;
+}
+
+/**
+ * Resolve the absolute path to server.ts for the currently-running CLI.
+ * Works for both `bun src/cli.ts` (dev) and `bun x @openparachute/vault`
+ * (published) — whichever path the CLI loaded from, server.ts sits next to it.
+ *
+ * NOTE: this relies on `server.ts` shipping next to `cli.ts` in the
+ * published package. If a `"files"` allowlist is ever added to
+ * package.json, `src/server.ts` must be included explicitly.
+ */
+export function resolveServerPath(): string {
+  return resolve(dirname(import.meta.path), "server.ts");
+}
+
+/** Write the wrapper script and pointer file together. Idempotent. */
+export async function writeDaemonWrapper(): Promise<{ serverPath: string; bunPath: string }> {
+  const serverPath = resolveServerPath();
+  const bunPath = Bun.which("bun") || join(homedir(), ".bun", "bin", "bun");
+
+  await writeFile(SERVER_PATH_FILE, serverPath + "\n");
+  await writeFile(WRAPPER_PATH, generateWrapper({ bunPath }), { mode: 0o755 });
+
+  return { serverPath, bunPath };
+}
+
+/** Remove the wrapper and pointer. Leaves .env, DB, logs alone. */
+export async function removeDaemonWrapper(): Promise<void> {
+  for (const p of [WRAPPER_PATH, SERVER_PATH_FILE]) {
+    try {
+      await unlink(p);
+    } catch {
+      // Not there — fine.
+    }
+  }
+}
+
+/**
+ * Read the pointer file, returning null if it's missing or unreadable.
+ * Used by the `vault doctor` / `vault uninstall` commands in PR 3 to tell
+ * whether the daemon is pointing at a real file.
+ */
+export function readServerPathPointer(): string | null {
+  try {
+    if (!existsSync(SERVER_PATH_FILE)) return null;
+    return readFileSync(SERVER_PATH_FILE, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}

package/src/doctor.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Integration tests for `parachute vault doctor` and `parachute vault url`.
+ *
+ * We spawn the CLI as a subprocess with `PARACHUTE_HOME` pointed at a
+ * fresh tempdir — so each test exercises the real code path (config +
+ * daemon path resolution + exit codes) against a known filesystem state.
+ * This catches wiring bugs that pure-function tests can't (e.g., a
+ * missing import or a broken switch case).
+ *
+ * We deliberately avoid asserting on daemon-manager check output — that
+ * depends on the host machine's live launchctl/systemd state and isn't
+ * part of the PR's contract.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+import { join, resolve } from "path";
+import { tmpdir } from "os";
+
+const CLI = resolve(import.meta.dir, "cli.ts");
+
+/**
+ * Run the CLI as a subprocess. `parachuteHome` is always passed as the
+ * isolated config dir; `extraEnv` is merged last so tests can override
+ * `HOME` (for the `~/.claude.json` MCP-entry checks) or unset `PATH`
+ * (for the bun-on-PATH check) without affecting unrelated tests.
+ */
+function runCli(
+  args: string[],
+  parachuteHome: string,
+  extraEnv: Record<string, string | undefined> = {},
+): { exitCode: number; stdout: string; stderr: string } {
+  const proc = Bun.spawnSync({
+    cmd: ["bun", CLI, ...args],
+    env: { ...process.env, PARACHUTE_HOME: parachuteHome, ...extraEnv },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    exitCode: proc.exitCode ?? -1,
+    stdout: new TextDecoder().decode(proc.stdout),
+    stderr: new TextDecoder().decode(proc.stderr),
+  };
+}
+
+/**
+ * Write a minimal ~/.claude.json with the given vault MCP URL. Returns the
+ * full path. Used by the MCP-entry-present tests.
+ */
+function writeClaudeJson(home: string, url: string): string {
+  const path = join(home, ".claude.json");
+  writeFileSync(
+    path,
+    JSON.stringify(
+      { mcpServers: { "parachute-vault": { type: "http", url } } },
+      null,
+      2,
+    ),
+  );
+  return path;
+}
+
+describe("vault doctor", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "vault-doctor-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("fails with a clear message when the pointer file is missing", () => {
+    const res = runCli(["doctor"], dir);
+    expect(res.exitCode).toBe(1);
+    expect(res.stdout).toMatch(/server-path pointer/);
+    expect(res.stdout).toMatch(/missing/);
+    expect(res.stdout).toMatch(/parachute vault init/);
+  });
+
+  test("fails when the pointer targets a non-existent file (moved repo)", () => {
+    writeFileSync(join(dir, "server-path"), "/does/not/exist/server.ts\n");
+    writeFileSync(join(dir, "start.sh"), "#!/bin/bash\n");
+    const res = runCli(["doctor"], dir);
+    expect(res.exitCode).toBe(1);
+    expect(res.stdout).toMatch(/points to/);
+    expect(res.stdout).toMatch(/repo location|init/i);
+  });
+
+  test("passes the pointer check when the target exists", () => {
+    // Use the CLI file itself as a stand-in existing target — it is
+    // guaranteed to exist since we just spawned bun with it.
+    writeFileSync(join(dir, "server-path"), CLI + "\n");
+    writeFileSync(join(dir, "start.sh"), "#!/bin/bash\n");
+    const res = runCli(["doctor"], dir);
+    expect(res.stdout).toMatch(/✓ server-path pointer/);
+    expect(res.stdout).toMatch(/✓ wrapper script/);
+  });
+});
+
+/**
+ * Extended doctor checks: bun-on-PATH, MCP entry presence + port match +
+ * reachability, and port-collision detection. All tests use an isolated
+ * HOME (so the user's real ~/.claude.json isn't consulted) and an isolated
+ * PARACHUTE_HOME, so they're reproducible on any machine.
+ *
+ * We intentionally do NOT test the "held by our daemon" (ours) branch of
+ * the port-collision check: it requires running a process whose cmdline
+ * contains our server.ts path, and we have no hook to fake that without
+ * spawning the real server. The foreign branch exercises the collision
+ * detection path end-to-end, which is what actually matters for warning
+ * OSS users; the ours branch is covered by the unit-level fact that
+ * `describeProcess` runs `ps` against the PID lsof returns.
+ */
+describe("vault doctor — extended checks", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "vault-doctor-ext-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("reports bun on PATH when `bun` is resolvable", () => {
+    // The test harness itself runs under bun, so bun is guaranteed to be
+    // on PATH here. This confirms the happy path renders correctly.
+    const res = runCli(["doctor"], dir, { HOME: dir });
+    expect(res.stdout).toMatch(/✓ bun on PATH/);
+  });
+
+  test("warns when `bun` is not on PATH", () => {
+    // We need two things at once:
+    //   a) the child's PATH must NOT resolve `bun` (so the doctor check fails)
+    //   b) we still need to launch the child under bun (so the test runs)
+    // Solution: launch the child via bun's absolute path directly, and set
+    // its PATH to an empty tempdir. `Bun.spawnSync`'s cmd[0] with an
+    // absolute path bypasses PATH lookup entirely.
+    const bunAbs = process.execPath; // the bun executable running this test
+    const emptyPathDir = mkdtempSync(join(tmpdir(), "empty-path-"));
+    try {
+      const proc = Bun.spawnSync({
+        cmd: [bunAbs, CLI, "doctor"],
+        env: { ...process.env, PARACHUTE_HOME: dir, HOME: dir, PATH: emptyPathDir },
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const stdout = new TextDecoder().decode(proc.stdout);
+      expect(stdout).toMatch(/! bun on PATH/);
+      expect(stdout).toMatch(/not resolvable/);
+      expect(stdout).toMatch(/bun\.sh\/install/);
+    } finally {
+      rmSync(emptyPathDir, { recursive: true, force: true });
+    }
+  });
+
+  test("warns when ~/.claude.json has no parachute-vault MCP entry", () => {
+    // Isolated HOME with no ~/.claude.json at all — the most common
+    // pre-`mcp-install` state for new users.
+    const res = runCli(["doctor"], dir, { HOME: dir });
+    expect(res.stdout).toMatch(/! MCP entry in ~\/\.claude\.json/);
+    expect(res.stdout).toMatch(/does not exist|no mcpServers/);
+    expect(res.stdout).toMatch(/mcp-install/);
+  });
+
+  test("warns when ~/.claude.json exists but has no parachute-vault entry", () => {
+    writeFileSync(join(dir, ".claude.json"), JSON.stringify({ mcpServers: {} }));
+    const res = runCli(["doctor"], dir, { HOME: dir });
+    expect(res.stdout).toMatch(/! MCP entry in ~\/\.claude\.json/);
+    expect(res.stdout).toMatch(/no mcpServers\["parachute-vault"\] entry/);
+  });
+
+  test("passes MCP entry + port-match checks when URL points at the configured port", () => {
+    // Use a non-default port to prove we're actually reading config.yaml,
+    // not just matching against DEFAULT_PORT.
+    writeFileSync(join(dir, "config.yaml"), "port: 4321\n");
+    writeClaudeJson(dir, "http://127.0.0.1:4321/vaults/default/mcp");
+    const res = runCli(["doctor"], dir, { HOME: dir });
+    expect(res.stdout).toMatch(/✓ MCP entry in ~\/\.claude\.json/);
+    expect(res.stdout).toMatch(/✓ MCP URL port matches vault\s+\(port 4321\)/);
+    // Reachability will warn because nothing is bound to 4321 in the test
+    // env — this is the "entry present, port matches, daemon unreachable"
+    // state the handoff explicitly called out as useful to surface.
+    expect(res.stdout).toMatch(/! MCP URL reachable/);
+  });
+
+  test("warns when MCP URL port does not match the vault's configured port", () => {
+    writeFileSync(join(dir, "config.yaml"), "port: 4321\n");
+    writeClaudeJson(dir, "http://127.0.0.1:9999/vaults/default/mcp");
+    const res = runCli(["doctor"], dir, { HOME: dir });
+    expect(res.stdout).toMatch(/✓ MCP entry in ~\/\.claude\.json/);
+    expect(res.stdout).toMatch(/! MCP URL port matches vault/);
+    expect(res.stdout).toMatch(/MCP URL port 9999 ≠ vault port 4321/);
+  });
+
+  test("warns when the configured port is held by an unrelated process", async () => {
+    // Find a free port, bind to it with a plain Bun.serve that has nothing
+    // to do with our server.ts — so the collision check will classify it
+    // as foreign. Using port 0 gets the OS to pick; we then write that
+    // port into config.yaml and let doctor discover the clash.
+    const server = Bun.serve({ port: 0, fetch: () => new Response("other") });
+    try {
+      const port = server.port;
+      writeFileSync(join(dir, "config.yaml"), `port: ${port}\n`);
+      const res = runCli(["doctor"], dir, { HOME: dir });
+      // The rendered name includes the port number, so match loosely.
+      expect(res.stdout).toMatch(new RegExp(`! port ${port} availability`));
+      expect(res.stdout).toMatch(/port in use by non-vault process/);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("reports port as free when nothing is bound to it", () => {
+    // Hardcoded ports are a portability trap — e.g. OrbStack grabs 54321
+    // on macOS, which would spuriously trip the foreign branch. Instead,
+    // ask the OS for a free port (bind to 0, then release) and point
+    // doctor at that port. The race window between stop() and doctor's
+    // lsof is tiny; for the stability of this test we accept it as the
+    // best available cross-platform "free-ish port" signal.
+    const probe = Bun.serve({ port: 0, fetch: () => new Response("ok") });
+    const port = probe.port;
+    probe.stop(true);
+    writeFileSync(join(dir, "config.yaml"), `port: ${port}\n`);
+    const res = runCli(["doctor"], dir, { HOME: dir });
+    expect(res.stdout).toMatch(new RegExp(`✓ port ${port} availability`));
+    expect(res.stdout).toMatch(/no listener \(ready to bind\)/);
+  });
+});
+
+describe("vault uninstall", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "vault-uninstall-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("--yes --wipe removes user data non-interactively", async () => {
+    // Scripted uninstall contract. --yes is an explicit opt-in to the
+    // destructive path — skipping the interactive guard is the whole
+    // point. We keep this behavior, but the help text warns.
+    // Note: this test exercises filesystem wipe only. It still invokes
+    // uninstallAgent(), which is safe because launchd.ts wraps each
+    // step in try/catch and we're on a tempdir that was never registered.
+    const vaultsDir = join(dir, "vaults");
+    const envFile = join(dir, ".env");
+    mkdirSync(vaultsDir, { recursive: true });
+    writeFileSync(join(vaultsDir, "marker"), "doomed");
+    writeFileSync(envFile, "PORT=1940\n");
+
+    const res = runCli(["uninstall", "--yes", "--wipe"], dir);
+    expect(res.exitCode).toBe(0);
+
+    const { existsSync } = await import("fs");
+    expect(existsSync(vaultsDir)).toBe(false);
+    expect(existsSync(envFile)).toBe(false);
+  });
+
+  test("--yes --wipe removes config.yaml and daemon logs alongside vaults + .env", async () => {
+    // Regression: the help text advertised "vaults + .env" but config.yaml,
+    // vault.log, and vault.err were being left behind. `uninstall --wipe`
+    // should fully reset ~/.parachute, or the next `init` picks up stale
+    // state (in particular a stale config.yaml port). Keep this test in
+    // sync with the path list in cmdUninstall and the usage help.
+    const vaultsDir = join(dir, "vaults");
+    const envFile = join(dir, ".env");
+    const configYaml = join(dir, "config.yaml");
+    const logFile = join(dir, "vault.log");
+    const errFile = join(dir, "vault.err");
+    mkdirSync(vaultsDir, { recursive: true });
+    writeFileSync(join(vaultsDir, "marker"), "doomed");
+    writeFileSync(envFile, "PORT=1940\n");
+    writeFileSync(configYaml, "port: 1940\n");
+    writeFileSync(logFile, "some log\n");
+    writeFileSync(errFile, "some err\n");
+
+    const res = runCli(["uninstall", "--yes", "--wipe"], dir);
+    expect(res.exitCode).toBe(0);
+
+    const { existsSync } = await import("fs");
+    expect(existsSync(vaultsDir)).toBe(false);
+    expect(existsSync(envFile)).toBe(false);
+    expect(existsSync(configYaml)).toBe(false);
+    expect(existsSync(logFile)).toBe(false);
+    expect(existsSync(errFile)).toBe(false);
+  });
+
+  test("--yes --wipe prints a destructive-wipe audit line before acting", async () => {
+    // `--yes --wipe` bypasses both interactive confirms. It must not be
+    // silent: a scripted uninstaller should leave one grep-able line in
+    // stdout documenting the destructive run (ISO timestamp + target paths).
+    writeFileSync(join(dir, ".env"), "PORT=1940\n");
+
+    const res = runCli(["uninstall", "--yes", "--wipe"], dir);
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toMatch(/scripted destructive wipe/);
+    // ISO-8601 timestamp shape (year-month-dayTtime). Loose enough to
+    // avoid flaking on sub-second precision differences.
+    expect(res.stdout).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    // Targets should be enumerated by path.
+    expect(res.stdout).toMatch(/vaults/);
+    expect(res.stdout).toMatch(/\.env/);
+    expect(res.stdout).toMatch(/config\.yaml/);
+  });
+
+  test("answering 'no' at the prompt does not touch daemon/filesystem", async () => {
+    // Set up a fake install: wrapper + pointer in the temp PARACHUTE_HOME.
+    const wrapper = join(dir, "start.sh");
+    const pointer = join(dir, "server-path");
+    writeFileSync(wrapper, "#!/bin/bash\n");
+    writeFileSync(pointer, "/tmp/fake.ts\n");
+
+    const proc = Bun.spawn({
+      cmd: ["bun", CLI, "uninstall"],
+      env: { ...process.env, PARACHUTE_HOME: dir },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    proc.stdin.write("n\n");
+    await proc.stdin.end();
+    const exitCode = await proc.exited;
+    const out = await new Response(proc.stdout).text();
+
+    expect(exitCode).toBe(0);
+    expect(out).toMatch(/Cancelled/);
+    // Files should still exist — the bail-out must happen before any
+    // destructive op.
+    const { existsSync } = await import("fs");
+    expect(existsSync(wrapper)).toBe(true);
+    expect(existsSync(pointer)).toBe(true);
+  });
+});
+
+describe("vault url", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "vault-url-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("prints the default URL when no port is configured", () => {
+    const res = runCli(["url"], dir);
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout.trim()).toBe("http://127.0.0.1:1940");
+  });
+
+  test("reflects a custom port from config.yaml", () => {
+    writeFileSync(join(dir, "config.yaml"), "port: 9999\n");
+    const res = runCli(["url"], dir);
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout.trim()).toBe("http://127.0.0.1:9999");
+  });
+});

package/src/health.test.ts

@@ -0,0 +1,201 @@
+import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach } from "bun:test";
+import { writeFileSync, mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { checkHealth, waitForHealthy, tailFile } from "./health.ts";
+
+// ---------------------------------------------------------------------------
+// checkHealth — uses a real Bun.serve on a free port so we exercise the
+// fetch + abort plumbing rather than mocking it. The three reachable status
+// codes (200, non-200, closed) are what the CLI needs to distinguish.
+// ---------------------------------------------------------------------------
+
+describe("checkHealth", () => {
+  test("returns healthy when /health returns 200", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch: () => new Response(JSON.stringify({ status: "ok" })),
+    });
+    try {
+      const res = await checkHealth(server.port);
+      expect(res.status).toBe("healthy");
+      expect(res.statusCode).toBe(200);
+      expect(res.latencyMs).toBeGreaterThanOrEqual(0);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns unhealthy when /health returns non-2xx", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch: () => new Response("bad", { status: 503 }),
+    });
+    try {
+      const res = await checkHealth(server.port);
+      expect(res.status).toBe("unhealthy");
+      expect(res.statusCode).toBe(503);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns not-listening when no server is bound", async () => {
+    // Bind, capture port, stop — then probe. The OS won't hand the port to
+    // another process instantly, so this reliably produces ECONNREFUSED.
+    const server = Bun.serve({ port: 0, fetch: () => new Response("ok") });
+    const port = server.port;
+    server.stop(true);
+    const res = await checkHealth(port, 500);
+    expect(res.status).toBe("not-listening");
+  });
+
+  test("returns error with timeout message when the server hangs longer than timeoutMs", async () => {
+    const server = Bun.serve({
+      port: 0,
+      // Never respond — force the probe to abort.
+      fetch: () => new Promise<Response>(() => {}),
+    });
+    try {
+      const res = await checkHealth(server.port, 150);
+      expect(res.status).toBe("error");
+      expect(res.error).toMatch(/timeout/i);
+    } finally {
+      server.stop(true);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// waitForHealthy — the thing the CLI's `restart` polling depends on.
+// ---------------------------------------------------------------------------
+
+describe("waitForHealthy", () => {
+  test("resolves on first-try healthy response", async () => {
+    const server = Bun.serve({ port: 0, fetch: () => new Response("ok") });
+    try {
+      const res = await waitForHealthy(server.port, { totalMs: 500, intervalMs: 50 });
+      expect(res.status).toBe("healthy");
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("gives up after totalMs budget when nothing listens", async () => {
+    // Grab a port, close it, then wait — should return not-listening promptly
+    // after the budget expires.
+    const s = Bun.serve({ port: 0, fetch: () => new Response("ok") });
+    const port = s.port;
+    s.stop(true);
+
+    const start = Date.now();
+    const res = await waitForHealthy(port, { totalMs: 400, intervalMs: 100, perProbeTimeoutMs: 100 });
+    const elapsed = Date.now() - start;
+    expect(res.status).not.toBe("healthy");
+    // Polling should respect the total budget — allow slack for scheduling.
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  test("eventually succeeds when server comes up mid-poll", async () => {
+    // Pick an OS-assigned port, free it so probes start as ECONNREFUSED,
+    // then bring a server up on the SAME port partway through the budget.
+    // That's the scenario cmdRestart depends on: launchctl has bounced the
+    // daemon, early probes hit a closed port, a later probe succeeds.
+    const first = Bun.serve({ port: 0, fetch: () => new Response("ok") });
+    const port = first.port;
+    first.stop(true);
+
+    let second: ReturnType<typeof Bun.serve> | null = null;
+    const serverPromise = new Promise<void>((resolve) => {
+      setTimeout(() => {
+        // Small retry loop — OSes sometimes need a beat to release the port.
+        for (let i = 0; i < 10; i++) {
+          try {
+            second = Bun.serve({ port, fetch: () => new Response("ok") });
+            break;
+          } catch {
+            Bun.sleepSync(20);
+          }
+        }
+        resolve();
+      }, 250);
+    });
+
+    try {
+      const pollPromise = waitForHealthy(port, {
+        totalMs: 2000,
+        intervalMs: 100,
+        perProbeTimeoutMs: 200,
+      });
+      await serverPromise;
+      const res = await pollPromise;
+      expect(res.status).toBe("healthy");
+    } finally {
+      (second as any)?.stop?.(true);
+    }
+  });
+
+  test("caps per-probe timeout at remaining budget (total wait stays under totalMs + slack)", async () => {
+    // Probe against a closed port with an intentionally oversized per-probe
+    // timeout. Without the cap, the loop could blow past totalMs waiting
+    // for one probe's timeout to fire. With the cap, the total wall time
+    // stays close to totalMs.
+    const s = Bun.serve({ port: 0, fetch: () => new Response("ok") });
+    const port = s.port;
+    s.stop(true);
+
+    const start = Date.now();
+    const res = await waitForHealthy(port, {
+      totalMs: 300,
+      intervalMs: 1000,
+      perProbeTimeoutMs: 5000,
+    });
+    const elapsed = Date.now() - start;
+    expect(res.status).not.toBe("healthy");
+    expect(elapsed).toBeLessThan(1500);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// tailFile
+// ---------------------------------------------------------------------------
+
+describe("tailFile", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "vault-tail-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns last n lines of a multi-line file", () => {
+    const p = join(dir, "err.log");
+    const lines = Array.from({ length: 50 }, (_, i) => `line ${i + 1}`);
+    writeFileSync(p, lines.join("\n") + "\n");
+    const tail = tailFile(p, 5);
+    expect(tail).toBe("line 46\nline 47\nline 48\nline 49\nline 50");
+  });
+
+  test("returns all lines when n exceeds file length", () => {
+    const p = join(dir, "err.log");
+    writeFileSync(p, "one\ntwo\nthree\n");
+    expect(tailFile(p, 100)).toBe("one\ntwo\nthree");
+  });
+
+  test("returns null when file doesn't exist", () => {
+    expect(tailFile(join(dir, "nope.log"), 10)).toBeNull();
+  });
+
+  test("returns empty string for empty file", () => {
+    const p = join(dir, "empty.log");
+    writeFileSync(p, "");
+    expect(tailFile(p, 10)).toBe("");
+  });
+
+  test("handles file without trailing newline", () => {
+    const p = join(dir, "no-trailing.log");
+    writeFileSync(p, "a\nb\nc");
+    expect(tailFile(p, 2)).toBe("b\nc");
+  });
+});