@openparachute/hub 0.7.6 → 0.7.7-rc.13

package/src/__tests__/install.test.ts

@@ -1,8 +1,17 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { defaultStartLifecycleOpts, install } from "../commands/install.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  PARACHUTE_HUB_ROOT_MODE_ENV,
+  PARACHUTE_HUB_ROOT_REDIRECT_ENV,
+  getRootMode,
+  getRootRedirect,
+  setRootMode,
+  setRootRedirect,
+} from "../hub-settings.ts";
 import { findService, upsertService } from "../services-manifest.ts";
 
 function makeTempPath(): { path: string; configDir: string; cleanup: () => void } {
@@ -62,6 +71,71 @@ describe("install", () => {
     }
   });
 
+  test("refuses `install agent` without invoking bun or the deprecated binary", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install("agent", {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        manifestPath: path,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: (line) => logs.push(line),
+      });
+      expect(code).toBe(1);
+      expect(calls).toEqual([]);
+      expect(logs.join("\n")).toMatch(/parachute-agent was retired/);
+      expect(logs.join("\n")).toMatch(/Vault and Surface/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("refuses explicit retired Agent npm package names before invoking bun", async () => {
+    for (const packageName of [
+      "@openparachute/agent",
+      "@openparachute/agent@0.9.0",
+      "@openparachute/channel",
+    ]) {
+      const calls: string[][] = [];
+      const logs: string[] = [];
+      const code = await install(packageName, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        log: (line) => logs.push(line),
+      });
+      expect(code).toBe(1);
+      expect(calls).toEqual([]);
+      expect(logs.join("\n")).toMatch(/parachute-agent was retired/);
+    }
+  });
+
+  test("refuses a local checkout whose package metadata is a retired Agent package", async () => {
+    const pkgDir = mkdtempSync(join(tmpdir(), "pcli-retired-agent-"));
+    try {
+      const calls: string[][] = [];
+      const code = await install(pkgDir, {
+        runner: async (cmd) => {
+          calls.push([...cmd]);
+          return 0;
+        },
+        readPackageName: () => "@openparachute/agent",
+        log: () => {},
+      });
+      expect(code).toBe(1);
+      expect(calls).toEqual([]);
+    } finally {
+      rmSync(pkgDir, { recursive: true, force: true });
+    }
+  });
+
   test("runs bun add -g then init; seeds manifest when service didn't write one", async () => {
     const { path, cleanup } = makeTempPath();
     try {
@@ -408,7 +482,7 @@ describe("install", () => {
   test("ADOPT-KILLS an attributable same-module orphan on the canonical port + reclaims it (#609)", async () => {
     // Wipe-recovery: `rm -rf ~/.parachute` + re-`init` leaves the supervised
     // vault child running on :1940. The fresh install must reclaim the canonical
-    // port (adopt-kill the attributable orphan) rather than port-walk to 1944.
+    // port (adopt-kill the attributable orphan) rather than port-walk to 1945.
     const { path, configDir, cleanup } = makeTempPath();
     try {
       const logs: string[] = [];
@@ -1636,9 +1710,10 @@ describe("install", () => {
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
-      // First reservation slot is 1944.
+      // Agent retirement released 1941, so it is now the first unassigned
+      // canonical slot available to the fallback walker.
       const entry = findService("parachute-vault", path);
-      expect(entry?.port).toBe(1944);
+      expect(entry?.port).toBe(1941);
       expect(logs.join("\n")).toMatch(/canonical port 1940 is in use/);
       // .env is not touched.
       const envPath = join(configDir, "vault", ".env");
@@ -1865,6 +1940,33 @@ describe("install", () => {
     }
   });
 
+  test("refuses third-party metadata that declares a retired Agent manifest identity", async () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const logs: string[] = [];
+      const code = await install("@vendor/agent-wrapper", {
+        runner: async () => 0,
+        manifestPath: path,
+        isLinked: () => false,
+        log: (line) => logs.push(line),
+        readManifest: async () => ({
+          name: "claw",
+          manifestName: "@vendor/agent-wrapper",
+          port: 1952,
+          paths: ["/claw"],
+          health: "/claw/health",
+        }),
+        findGlobalInstall: () =>
+          "/fake/bun-globals/node_modules/@vendor/agent-wrapper/package.json",
+      });
+      expect(code).toBe(1);
+      expect(findService("claw", path)).toBeUndefined();
+      expect(logs.join("\n")).toMatch(/parachute-agent was retired/);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("npm-installed third-party module persists installDir from bun globals", async () => {
     // hub#83: for `parachute install <npm-pkg>`, installDir is dirname of
     // the package.json that findGlobalInstall returns. Without this,
@@ -1940,7 +2042,8 @@ describe("install", () => {
       expect(startCalls).toEqual(["someapp"]);
       // Log lines speak in the canonical short name too. Port comes from
       // assignServicePort (third-party gets the first unassigned canonical
-      // slot, currently 1944), not the manifest's port hint.
+      // slot, currently 1945 — 1944 is parachute-app's canonical assigned
+      // slot as of hub-parity P5), not the manifest's port hint.
       const joined = logs.join("\n");
       expect(joined).toMatch(/Seeded services\.json entry for someapp/);
       expect(joined).toMatch(/someapp registered on port \d+/);
@@ -2316,3 +2419,254 @@ describe("hub#573 — install auto-start converges on supervised detection", ()
     expect(opts.log).toBe(log);
   });
 });
+
+// `parachute install app` defaults the hub's origin root to SERVE the app
+// (root_mode = serve-app) on first install — SET-IF-UNSET ONLY, and only when
+// the root behavior is entirely pristine default (no mode row/env AND no
+// redirect row/env). Supersedes the prior hub-parity P5 behavior (which wrote
+// root_redirect = /app/). Every test here injects `rootRedirectDb` (a hub.db
+// opened in the same disposable tempdir `makeTempPath()` already isolates) so no
+// real `~/.parachute/hub.db` is ever touched — never drive this against the
+// operator's live install.
+describe("app-only serve-app set-if-unset default", () => {
+  // The write gates on the RESOLVED mode + redirect being `default` (no DB row,
+  // no env). Neutralize any ambient PARACHUTE_HUB_ROOT_MODE / _REDIRECT (Aaron's
+  // box, CI) so the default-tier tests are deterministic; the env-set tests
+  // below manage their own values inside their own bodies.
+  let savedRedirectEnv: string | undefined;
+  let savedModeEnv: string | undefined;
+  beforeEach(() => {
+    savedRedirectEnv = process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    savedModeEnv = process.env[PARACHUTE_HUB_ROOT_MODE_ENV];
+    delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    delete process.env[PARACHUTE_HUB_ROOT_MODE_ENV];
+  });
+  afterEach(() => {
+    for (const [name, saved] of [
+      [PARACHUTE_HUB_ROOT_REDIRECT_ENV, savedRedirectEnv],
+      [PARACHUTE_HUB_ROOT_MODE_ENV, savedModeEnv],
+    ] as const) {
+      if (saved === undefined) delete process.env[name];
+      else process.env[name] = saved;
+    }
+  });
+
+  test("fresh install (pristine root) flips root_mode to serve-app", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        expect(getRootMode(db)).toBe("serve-app");
+        // The redirect row is NOT written — serve-app takes over `/` directly.
+        expect(getRootRedirect(db)).toBeNull();
+        expect(logs.join("\n")).toMatch(/front page.*now serves the Parachute app/);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a pre-set root_redirect is left alone — mode NOT flipped", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        setRootRedirect(db, "/surface/reading-room");
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        // The operator's prior choice survives byte-for-byte; no mode flip.
+        expect(getRootRedirect(db)).toBe("/surface/reading-room");
+        expect(getRootMode(db)).toBeNull();
+        expect(logs.join("\n")).not.toMatch(/now serves the Parachute app/);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("an existing install with the old /app/ redirect keeps redirecting (back-compat)", async () => {
+    // A hub that ran the PRIOR app-install code has root_redirect = /app/ in its
+    // DB (source = db → not default). Re-running `install app` must NOT flip it
+    // to serve-app — it keeps 302-ing to /app/, exactly as before. This is the
+    // "existing installs unchanged" guarantee.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        setRootRedirect(db, "/app/");
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        expect(getRootMode(db)).toBeNull();
+        expect(getRootRedirect(db)).toBe("/app/");
+        expect(logs.join("\n")).not.toMatch(/now serves the Parachute app/);
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("installing a different module never touches the root settings", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const db = openHubDb(hubDbPath(configDir));
+      try {
+        const code = await install("notes", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: () => {},
+        });
+        expect(code).toBe(0);
+        expect(getRootRedirect(db)).toBeNull();
+        expect(getRootMode(db)).toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("an ENV-configured redirect (no DB row) is left alone — no mode flip (N1)", async () => {
+    // Container deploys pin the landing page via PARACHUTE_HUB_ROOT_REDIRECT,
+    // not a DB row. Flipping to serve-app would silently override their
+    // configured landing (serve-app wins over redirect at `/`). The gate reads
+    // the RESOLVED redirect source; with the env set that's `env`, not
+    // `default`, so we leave it alone.
+    const { path, configDir, cleanup } = makeTempPath();
+    const prevEnv = process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+    try {
+      process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = "/surface/team-room";
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        // No mode row written — the env-configured landing survives.
+        expect(getRootMode(db)).toBeNull();
+        expect(getRootRedirect(db)).toBeNull();
+        expect(logs.join("\n")).not.toMatch(/now serves the Parachute app/);
+      } finally {
+        db.close();
+      }
+    } finally {
+      if (prevEnv === undefined) {
+        delete process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+      } else {
+        process.env[PARACHUTE_HUB_ROOT_REDIRECT_ENV] = prevEnv;
+      }
+      cleanup();
+    }
+  });
+
+  test("an ENV-configured mode (no DB row) is left alone — no clobber", async () => {
+    // PARACHUTE_HUB_ROOT_MODE=redirect on a container that deliberately wants
+    // the redirect front door. The gate sees the resolved mode source as `env`,
+    // not `default`, so it does NOT write a serve-app row.
+    const { path, configDir, cleanup } = makeTempPath();
+    const prevEnv = process.env[PARACHUTE_HUB_ROOT_MODE_ENV];
+    try {
+      process.env[PARACHUTE_HUB_ROOT_MODE_ENV] = "redirect";
+      const db = openHubDb(hubDbPath(configDir));
+      const logs: string[] = [];
+      try {
+        const code = await install("app", {
+          runner: async () => 0,
+          manifestPath: path,
+          configDir,
+          startService: async () => 0,
+          isLinked: () => false,
+          portProbe: async () => false,
+          rootRedirectDb: db,
+          log: (l) => logs.push(l),
+        });
+        expect(code).toBe(0);
+        expect(getRootMode(db)).toBeNull();
+        expect(logs.join("\n")).not.toMatch(/now serves the Parachute app/);
+      } finally {
+        db.close();
+      }
+    } finally {
+      if (prevEnv === undefined) {
+        delete process.env[PARACHUTE_HUB_ROOT_MODE_ENV];
+      } else {
+        process.env[PARACHUTE_HUB_ROOT_MODE_ENV] = prevEnv;
+      }
+      cleanup();
+    }
+  });
+
+  test("production gate: without rootRedirectDb + a tempdir manifestPath, the write is skipped (not attempted)", async () => {
+    // Mirrors the existing `guidanceProbeAllowed` discriminant elsewhere in
+    // install.ts: a test with a tempdir manifestPath and no explicit opt-in
+    // must never open the real ~/.parachute/hub.db. There's nothing to open
+    // here at all — the assertion is simply that install still completes
+    // cleanly with the DB-touching branch skipped.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      const code = await install("app", {
+        runner: async () => 0,
+        manifestPath: path,
+        configDir,
+        startService: async () => 0,
+        isLinked: () => false,
+        portProbe: async () => false,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/migrate.test.ts

@@ -56,7 +56,9 @@ describe("safelistEntries", () => {
     expect(s.has("vault")).toBe(true);
     expect(s.has("notes")).toBe(true);
     expect(s.has("scribe")).toBe(true);
-    expect(s.has("agent")).toBe(true);
+    expect(s.has("agent")).toBe(false);
+    expect(KNOWN_ARCHIVABLE_DIRS.has("agent")).toBe(true);
+    expect(KNOWN_ARCHIVABLE_DIRS.has("channel")).toBe(true);
     // Internal
     expect(s.has("hub")).toBe(true);
     // CLI state

package/src/__tests__/notes-serve.test.ts

@@ -149,6 +149,124 @@ describe("notesFetch with empty mount (root deployment)", () => {
   });
 });
 
+describe("notesFetch /health (2026-07-11, hub-parity P5)", () => {
+  test("GET /notes/health answers 2xx explicitly, not the SPA shell", async () => {
+    const h = makeHarness();
+    try {
+      const res = notesFetch(h.dir, "/notes")(req("/notes/health"));
+      expect(res.status).toBe(200);
+      // Explicit JSON, not the index.html SPA-shell fallback — proves the
+      // health path is a real handler, not an accident of the catch-all.
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(await res.text()).not.toContain("notes spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /health answers 2xx at the mount root too (empty mount)", async () => {
+    const h = makeHarness();
+    try {
+      const res = notesFetch(h.dir, "")(req("/health"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/json");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("survives a missing dist/index.html — health doesn't depend on the SPA shell existing", async () => {
+    // A harness with NO index.html written — the SPA-shell fallback would
+    // throw/404 on this dist, but /health is answered before that code path
+    // is ever reached.
+    const dir = mkdtempSync(join(tmpdir(), "pcli-notes-serve-empty-"));
+    try {
+      const res = notesFetch(dir, "/app")(req("/app/health"));
+      expect(res.status).toBe(200);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// hub-parity P5 (2026-07-11): the shim generalized beyond notes to serve
+// @openparachute/parachute-app (mount `/app`, port 1944) via the same
+// FIRST_PARTY_FALLBACKS startCmd shape (`--package @openparachute/parachute-app`).
+// These tests re-run the load-bearing PWA regression (sw.js / manifest
+// content-type, SPA fallback, mount-strip) for a NON-notes package/mount to
+// prove the generalization didn't accidentally hardcode "notes" anywhere in
+// the serving path (only `resolveNotesDistFrom`'s package resolution is
+// notes-specific, and that's parameterized separately below).
+describe("notesFetch generalized for a non-notes package (hub-parity P5 — the app mount)", () => {
+  function makeAppHarness(): Harness {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-app-serve-"));
+    writeFileSync(join(dir, "index.html"), "<html><body>app spa</body></html>");
+    writeFileSync(join(dir, "sw.js"), "self.addEventListener('install', () => {});");
+    writeFileSync(join(dir, "manifest.webmanifest"), '{"name":"Parachute","start_url":"/app/"}');
+    return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+  }
+
+  test("GET /app/sw.js serves the SW with JS content-type, not text/html", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/sw.js"));
+      expect(res.status).toBe(200);
+      const ct = res.headers.get("content-type") ?? "";
+      expect(ct).not.toContain("text/html");
+      expect(ct).toMatch(/javascript/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /app/manifest.webmanifest serves application/manifest+json", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/manifest.webmanifest"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/manifest+json");
+      expect(await res.text()).toContain('"name":"Parachute"');
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /app/ serves the SPA shell", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("app spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /app/some/deep/route falls back to the SPA shell (client-side routing)", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/app/some/deep/route"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      expect(await res.text()).toContain("app spa");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET /appendix/foo (mount-prefix collision) is not stripped", async () => {
+    const h = makeAppHarness();
+    try {
+      const res = notesFetch(h.dir, "/app")(req("/appendix/foo"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("notesDistCandidates", () => {
   test("returns cwd, then global node_modules, then global root", () => {
     const cands = notesDistCandidates("/some/cwd", "/home/user");
@@ -295,3 +413,101 @@ describe("resolveNotesDistFrom (hub#194)", () => {
     ).toThrow(/has no dist\/ directory/);
   });
 });
+
+/**
+ * `--package` generalization (hub-parity P5, 2026-07-11). `resolveNotesDistFrom`
+ * defaults `pkg` to `@openparachute/notes` (every test above omits it and
+ * still resolves notes — back-compat), but a caller like the `app`
+ * FIRST_PARTY_FALLBACKS entry passes a different package name. These tests
+ * pin the resolver against a real on-disk fixture for a NON-notes package,
+ * proving the specifier passed to `Bun.resolveSync` (and every error message)
+ * is the caller's `pkg`, not a hardcoded "notes" string.
+ */
+describe("resolveNotesDistFrom --package (hub-parity P5)", () => {
+  const APP_PKG = "@openparachute/parachute-app";
+
+  function makeAppFixture(): { home: string; cleanup: () => void; dist: string } {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "pcli-app-resolve-")));
+    const home = join(root, "home");
+    const pkgRoot = join(home, ".bun/install/global/node_modules", APP_PKG);
+    mkdirSync(pkgRoot, { recursive: true });
+    const dist = join(pkgRoot, "dist");
+    mkdirSync(dist, { recursive: true });
+    writeFileSync(join(pkgRoot, "package.json"), JSON.stringify({ name: APP_PKG }));
+    return { home, dist, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+  }
+
+  test("resolves a non-notes package's dist/ via the global node_modules fallback", () => {
+    const f = makeAppFixture();
+    try {
+      const out = resolveNotesDistFrom({
+        cwd: "/hub-repo-cwd-without-app",
+        home: f.home,
+        pkg: APP_PKG,
+        resolveSync: (specifier, base) => {
+          if (base === "/hub-repo-cwd-without-app") {
+            throw new Error(`Cannot find module '${specifier}' from '${base}'`);
+          }
+          return Bun.resolveSync(specifier, base);
+        },
+      });
+      expect(out).toBe(f.dist);
+    } finally {
+      f.cleanup();
+    }
+  });
+
+  test("default pkg (no --package) still resolves @openparachute/notes — back-compat", () => {
+    // Every earlier describe block already exercises this implicitly (none
+    // pass `pkg`); this test pins it explicitly against the specifier the
+    // resolver hands to `resolveSync`.
+    const specifiers: string[] = [];
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd",
+        home: "/h",
+        resolveSync: (specifier) => {
+          specifiers.push(specifier);
+          throw new Error("not found");
+        },
+      }),
+    ).toThrow();
+    expect(specifiers).toEqual([
+      "@openparachute/notes/package.json",
+      "@openparachute/notes/package.json",
+      "@openparachute/notes/package.json",
+    ]);
+  });
+
+  test("error message names the caller's package, not a hardcoded 'notes'", () => {
+    let caught: unknown;
+    try {
+      resolveNotesDistFrom({
+        cwd: "/probe-cwd",
+        home: "/probe-home",
+        pkg: APP_PKG,
+        resolveSync: () => {
+          throw new Error("nope");
+        },
+      });
+    } catch (err) {
+      caught = err;
+    }
+    const msg = (caught as Error).message;
+    expect(msg).toContain(`Could not resolve ${APP_PKG}`);
+    expect(msg).toContain(`bun add -g ${APP_PKG}`);
+    expect(msg).not.toContain("@openparachute/notes");
+  });
+
+  test("no-dist/ hard error names the caller's package", () => {
+    expect(() =>
+      resolveNotesDistFrom({
+        cwd: "/cwd-with-app",
+        home: "/h",
+        pkg: APP_PKG,
+        resolveSync: () => "/cwd-with-app/node_modules/@openparachute/parachute-app/package.json",
+        existsSync: () => false,
+      }),
+    ).toThrow(new RegExp(`${APP_PKG.replace("/", "\\/")} resolved at .* has no dist/ directory`));
+  });
+});