@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/shared/src/__tests__/bootstrap/families/l-instance-coordination.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Family L — Instance coordination (per-HOME advisory lock).
+ *
+ * Covers the scenarios enumerated in
+ * `openspec/changes/single-dashboard-per-home/design.md §10`:
+ *
+ *   L1  no prior dashboard              → acquire
+ *   L2  healthy dashboard same port     → attach
+ *   L3  healthy dashboard diff port     → attach via metadata URL
+ *   L4  stale lock (PID dead)           → steal + start
+ *   L5  stale PID + port free           → steal + clean + start
+ *   L6  stale PID + port taken by       → identity mismatch error
+ *       unrelated process
+ *   L7  mDNS disabled                   → lock still works (same as L2)
+ *   L9  multi-user                      → separate HOMEs, separate locks
+ *   L10 HOME symlink                    → realpath canonicalization
+ *   L11 identity mismatch               → error, no attach, no start
+ *   L12 corrupt metadata                → treat as stale, steal
+ *
+ * L8 (concurrent launch) and L13 (permission denied) live in integration
+ * tests (`concurrent-launch.test.ts`, `crash-recovery.test.ts`) because
+ * they require real processes / real filesystems.
+ *
+ * Note: this family does NOT use the cube enumeration. The 5-axis cube
+ * does not model lock state; adding it would 4x the cell count. Family L
+ * is registered as a separate enumeration here (design decision: the
+ * simpler option from design §Precondition item 2b).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  acquireOrAttach,
+  readMetadata,
+  writeMetadataAtomic,
+  canonicalHomedir,
+  getLockPath,
+  InstanceLockMismatchError,
+  type LockMetadata,
+} from "../../../../../server/src/home-lock.js";
+
+let tmpHome: string;
+let lockPath: string;
+let metaPath: string;
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-family-l-"));
+  lockPath = path.join(tmpHome, ".pi", "dashboard", "server.lock");
+  metaPath = `${lockPath}.meta.json`;
+});
+
+afterEach(() => {
+  try { fs.rmSync(tmpHome, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+const baseCfg = (over: Partial<Parameters<typeof acquireOrAttach>[0]> = {}) => ({
+  httpPort: 8000,
+  piPort: 9999,
+  version: "0.0.0-test",
+  hooks: {
+    lockPath, metaPath, staleMs: 500,
+    probeHealth: async () => ({ running: false }),
+    isProcessAlive: () => false,
+    ...(over.hooks ?? {}),
+  },
+  ...over,
+});
+
+describe("Family L — instance coordination", () => {
+  it("L1 — no prior dashboard: acquires cleanly", async () => {
+    const r = await acquireOrAttach(baseCfg());
+    expect(r.mode).toBe("acquired");
+    if (r.mode === "acquired") await r.release();
+  });
+
+  it("L2 — healthy dashboard same port: attaches", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "live-1" }));
+    expect(first.mode).toBe("acquired");
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 500,
+        isProcessAlive: () => true,
+        probeHealth: async () => ({ running: true, identity: "live-1", pid: process.pid }),
+      },
+    }));
+    expect(second.mode).toBe("attach");
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L3 — healthy dashboard on different port: attaches via metadata URL", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "live-3", httpPort: 8765 }));
+    expect(first.mode).toBe("acquired");
+
+    // New caller asks for port 9001, but lock meta says live on 8765.
+    const second = await acquireOrAttach(baseCfg({
+      httpPort: 9001,
+      hooks: {
+        lockPath, metaPath, staleMs: 500,
+        isProcessAlive: () => true,
+        // Probe only returns alive for the correct port (8765).
+        probeHealth: async (port) =>
+          port === 8765
+            ? { running: true, identity: "live-3", pid: process.pid }
+            : { running: false },
+      },
+    }));
+    expect(second.mode).toBe("attach");
+    if (second.mode === "attach") {
+      expect(second.meta.httpPort).toBe(8765);
+      expect(second.meta.url).toContain("8765");
+    }
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L4 — stale lock, PID dead: steals + starts", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "dead-holder" }));
+    expect(first.mode).toBe("acquired");
+    // Don't release — simulate crash.
+    await new Promise(r => setTimeout(r, 50));
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 1,
+        isProcessAlive: () => false,
+        probeHealth: async () => ({ running: false }),
+      },
+    }));
+    expect(second.mode).toBe("acquired");
+    if (second.mode === "acquired") await second.release();
+  });
+
+  it("L5 — stale PID + port free: clean steal", async () => {
+    // Write stale metadata manually, with no active lockfile yet.
+    fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+    const staleMeta: LockMetadata = {
+      pid: 1, ppid: 0, httpPort: 8000, piPort: 9999,
+      startedAt: 0, identity: "ghost", version: "0", url: "http://localhost:8000", hostname: "h",
+    };
+    writeMetadataAtomic(staleMeta, metaPath);
+
+    const r = await acquireOrAttach(baseCfg());
+    expect(r.mode).toBe("acquired");
+    if (r.mode === "acquired") {
+      expect(r.meta.identity).not.toBe("ghost");
+      await r.release();
+    }
+  });
+
+  it("L6 — stale PID + port taken by unrelated process: identity mismatch", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "legit" }));
+    expect(first.mode).toBe("acquired");
+
+    // Simulate: lock is alive-ish, but health returns a different identity
+    // (port commandeered by something else with same pid reuse).
+    await expect(
+      acquireOrAttach(baseCfg({
+        hooks: {
+          lockPath, metaPath, staleMs: 500,
+          isProcessAlive: () => true,
+          probeHealth: async () => ({ running: true, identity: "hostile-squatter" }),
+        },
+      })),
+    ).rejects.toBeInstanceOf(InstanceLockMismatchError);
+
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L7 — mDNS disabled: lock path unaffected (parity with L2)", async () => {
+    // mDNS is orthogonal to the lock; exercise the same L2 flow to document
+    // that lock acquisition does NOT depend on mDNS discovery.
+    const first = await acquireOrAttach(baseCfg({ identity: "no-mdns" }));
+    expect(first.mode).toBe("acquired");
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 500,
+        isProcessAlive: () => true,
+        probeHealth: async () => ({ running: true, identity: "no-mdns", pid: process.pid }),
+      },
+    }));
+    expect(second.mode).toBe("attach");
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L9 — multi-user: two HOMEs, two locks, no interference", async () => {
+    const homeA = fs.mkdtempSync(path.join(os.tmpdir(), "pi-user-a-"));
+    const homeB = fs.mkdtempSync(path.join(os.tmpdir(), "pi-user-b-"));
+    try {
+      const lockA = path.join(homeA, ".pi", "dashboard", "server.lock");
+      const metaA = `${lockA}.meta.json`;
+      const lockB = path.join(homeB, ".pi", "dashboard", "server.lock");
+      const metaB = `${lockB}.meta.json`;
+
+      const a = await acquireOrAttach({
+        httpPort: 8000, piPort: 9999, version: "t",
+        hooks: { lockPath: lockA, metaPath: metaA, staleMs: 500 },
+      });
+      const b = await acquireOrAttach({
+        httpPort: 8001, piPort: 9998, version: "t",
+        hooks: { lockPath: lockB, metaPath: metaB, staleMs: 500 },
+      });
+      expect(a.mode).toBe("acquired");
+      expect(b.mode).toBe("acquired");
+      if (a.mode === "acquired") await a.release();
+      if (b.mode === "acquired") await b.release();
+    } finally {
+      fs.rmSync(homeA, { recursive: true, force: true });
+      fs.rmSync(homeB, { recursive: true, force: true });
+    }
+  });
+
+  it("L10 — HOME symlink: realpath canonicalizes to the same lock", async () => {
+    const real = fs.mkdtempSync(path.join(os.tmpdir(), "pi-real-home-"));
+    const link = path.join(os.tmpdir(), `pi-link-home-${Date.now()}-${Math.random()}`);
+    fs.symlinkSync(real, link);
+    try {
+      // Both paths resolve via realpath → same canonical HOME.
+      expect(fs.realpathSync(link)).toBe(fs.realpathSync(real));
+      // canonicalHomedir() uses os.homedir() so we can't mock without
+      // globals; the invariant is tested via fs.realpathSync equivalence.
+      expect(typeof canonicalHomedir()).toBe("string");
+    } finally {
+      try { fs.unlinkSync(link); } catch { /* ignore */ }
+      fs.rmSync(real, { recursive: true, force: true });
+    }
+  });
+
+  it("L11 — identity mismatch: throws, no attach, no start", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "me" }));
+    expect(first.mode).toBe("acquired");
+
+    await expect(
+      acquireOrAttach(baseCfg({
+        hooks: {
+          lockPath, metaPath, staleMs: 500,
+          isProcessAlive: () => true,
+          probeHealth: async () => ({ running: true, identity: "not-me", pid: 99999 }),
+        },
+      })),
+    ).rejects.toBeInstanceOf(InstanceLockMismatchError);
+
+    // Verify no new metadata has been written with a different identity
+    const meta = readMetadata(metaPath);
+    expect(meta?.identity).toBe("me");
+
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L12 — corrupt metadata: treated as stale, steal", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "intact" }));
+    expect(first.mode).toBe("acquired");
+
+    // Corrupt the metadata file.
+    fs.writeFileSync(metaPath, "{broken json");
+    await new Promise(r => setTimeout(r, 50));
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 1,
+        isProcessAlive: () => false,
+        probeHealth: async () => ({ running: false }),
+      },
+    }));
+    expect(second.mode).toBe("acquired");
+    if (second.mode === "acquired") {
+      expect(second.meta.identity).not.toBe("intact");
+      await second.release();
+    }
+  });
+});

package/packages/shared/src/__tests__/bootstrap/fixtures/dev-monorepo.ts

@@ -0,0 +1,58 @@
+/**
+ * Fixture: dev monorepo layout (what developers see running from source).
+ *
+ * <root>/
+ *   node_modules/
+ *     @mariozechner/pi-coding-agent/dist/cli.js
+ *     openspec/dist/cli.js
+ *     tsx/dist/cli.mjs
+ *   packages/
+ *     shared/    server/    extension/    electron/
+ *
+ * Used for Family C scenarios (bare-import resolves pi via workspace
+ * node_modules).
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+import { openspecPackageJson, piPackageJson, type PiVersionSpec } from "./pi-versions.js";
+
+export interface DevMonorepoSpec {
+  root: string;
+  platform: NodeJS.Platform;
+  pi?: PiVersionSpec;
+  openspec?: string;
+}
+
+export function devMonorepo(spec: DevMonorepoSpec): FsRecord {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const nodeModules = p.join(spec.root, "node_modules");
+  const out: Record<string, string> = {};
+
+  // Root package.json (workspace)
+  out[p.join(spec.root, "package.json")] = JSON.stringify({
+    name: "pi-agent-dashboard-root",
+    private: true,
+    workspaces: ["packages/*"],
+  });
+
+  // Workspace packages
+  for (const pkg of ["shared", "server", "extension", "electron", "client"]) {
+    out[p.join(spec.root, "packages", pkg, "package.json")] = JSON.stringify({
+      name: `@blackbelt-technology/pi-dashboard-${pkg}`,
+      version: "0.4.0",
+    });
+  }
+
+  // Hoisted deps
+  const piDir = p.join(nodeModules, "@mariozechner", "pi-coding-agent");
+  out[p.join(piDir, "package.json")] = piPackageJson(spec.pi);
+  out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+
+  const osDir = p.join(nodeModules, "openspec");
+  out[p.join(osDir, "package.json")] = openspecPackageJson(spec.openspec ?? "0.4.1");
+  out[p.join(osDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+  out[p.join(osDir, "dist", "index.js")] = "module.exports = {};";
+
+  return out;
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/electron-layout.ts

@@ -0,0 +1,84 @@
+/**
+ * Fixture: Electron packaged resources layout.
+ *
+ * macOS:   /Applications/PI Dashboard.app/Contents/Resources/server/...
+ * Linux:   /usr/lib/pi-dashboard/resources/server/...
+ * Windows: C:\Program Files\PI Dashboard\resources\server\...
+ * AppImage: /tmp/.mount_PIxxxx/resources/server/... (temp, unstable)
+ *
+ * The bundled extension lives alongside at
+ * `<resourcesPath>/server/packages/extension/`.
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+
+export interface ElectronLayoutSpec {
+  platform: NodeJS.Platform;
+  /** If true, simulate AppImage temp-mount path. */
+  appimage?: boolean;
+}
+
+function resourcesRoot(spec: ElectronLayoutSpec): string {
+  if (spec.appimage) {
+    return "/tmp/.mount_PIxxxx/resources";
+  }
+  switch (spec.platform) {
+    case "darwin":
+      return "/Applications/PI Dashboard.app/Contents/Resources";
+    case "win32":
+      return "C:\\Program Files\\PI Dashboard\\resources";
+    default:
+      return "/usr/lib/pi-dashboard/resources";
+  }
+}
+
+export function electronPackaged(spec: ElectronLayoutSpec): FsRecord {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const resources = resourcesRoot(spec);
+  const serverDir = p.join(resources, "server");
+  const extensionDir = p.join(serverDir, "packages", "extension");
+  const out: Record<string, string> = {};
+
+  // Bundled server package.json
+  out[p.join(serverDir, "package.json")] = JSON.stringify({
+    name: "@blackbelt-technology/pi-agent-dashboard-root",
+    version: "0.4.0",
+    private: true,
+  });
+
+  // Bundled server CLI source
+  out[p.join(serverDir, "packages", "server", "package.json")] = JSON.stringify({
+    name: "@blackbelt-technology/pi-dashboard-server",
+    version: "0.4.0",
+  });
+  out[p.join(serverDir, "packages", "server", "src", "cli.ts")] = "// cli";
+
+  // Bundled bridge extension
+  out[p.join(extensionDir, "package.json")] = JSON.stringify({
+    name: "@blackbelt-technology/pi-dashboard-extension",
+    version: "0.4.0",
+  });
+  out[p.join(extensionDir, "src", "bridge.ts")] = "// bridge";
+
+  // Bundled Node.js (minimal)
+  const nodeBin = spec.platform === "win32"
+    ? p.join(resources, "node", "bin", "node.exe")
+    : p.join(resources, "node", "bin", "node");
+  out[nodeBin] = "\x7fELF"; // binary-ish marker
+
+  return out;
+}
+
+/** Returns the resolved `resourcesPath` + extension path for assertions. */
+export function electronPaths(spec: ElectronLayoutSpec): {
+  resources: string;
+  serverDir: string;
+  extensionDir: string;
+} {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const resources = resourcesRoot(spec);
+  const serverDir = p.join(resources, "server");
+  const extensionDir = p.join(serverDir, "packages", "extension");
+  return { resources, serverDir, extensionDir };
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Barrel export for bootstrap fixtures. Import as `import * as fixtures`.
+ */
+export * from "./pi-versions.js";
+export * from "./managed-install.js";
+export * from "./npm-global-layout.js";
+export * from "./electron-layout.js";
+export * from "./dev-monorepo.js";
+export * from "./settings-json.js";

package/packages/shared/src/__tests__/bootstrap/fixtures/managed-install.ts

@@ -0,0 +1,85 @@
+/**
+ * Fixture: managed install at `<homedir>/.pi-dashboard/`.
+ *
+ * Produces the fs layout a user gets after running the Electron wizard
+ * or proposal-2's CLI first-run bootstrap: node_modules/@mariozechner/
+ * pi-coding-agent + node_modules/.bin shims.
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+import { openspecPackageJson, piPackageJson, type PiVersionSpec } from "./pi-versions.js";
+
+export interface ManagedInstallSpec {
+  homedir: string;
+  platform: NodeJS.Platform;
+  pi?: PiVersionSpec | false;
+  openspec?: string | false;
+  tsx?: string | false;
+  /**
+   * If `true`, write just the package.json for pi — no `dist/cli.js`.
+   * Simulates an install that was interrupted mid-extract (scenario E2).
+   */
+  piPartial?: boolean;
+}
+
+export function managedInstall(spec: ManagedInstallSpec): FsRecord {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const out: Record<string, string> = {};
+  const managedDir = p.join(spec.homedir, ".pi-dashboard");
+  const nodeModules = p.join(managedDir, "node_modules");
+  const binDir = p.join(nodeModules, ".bin");
+
+  out[p.join(managedDir, "package.json")] = JSON.stringify({
+    name: "pi-dashboard-managed",
+    private: true,
+    type: "module",
+  });
+
+  if (spec.pi !== false) {
+    const piSpec = spec.pi ?? {};
+    const piDir = p.join(nodeModules, "@mariozechner", "pi-coding-agent");
+    out[p.join(piDir, "package.json")] = piPackageJson(piSpec);
+    if (!spec.piPartial) {
+      out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node\n// pi cli stub";
+      // bin shim
+      if (spec.platform === "win32") {
+        out[p.join(binDir, "pi.cmd")] = "@node %~dp0\\..\\@mariozechner\\pi-coding-agent\\dist\\cli.js %*";
+      } else {
+        out[p.join(binDir, "pi")] = "#!/bin/sh\nexec node ../@mariozechner/pi-coding-agent/dist/cli.js \"$@\"";
+      }
+    }
+  }
+
+  if (spec.openspec !== false) {
+    const v = spec.openspec ?? "0.4.1";
+    const dir = p.join(nodeModules, "openspec");
+    out[p.join(dir, "package.json")] = openspecPackageJson(v);
+    out[p.join(dir, "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(dir, "dist", "index.js")] = "module.exports = {};";
+    if (spec.platform === "win32") {
+      out[p.join(binDir, "openspec.cmd")] = "@node %~dp0\\..\\openspec\\dist\\cli.js %*";
+    } else {
+      out[p.join(binDir, "openspec")] = "#!/bin/sh\nexec node ../openspec/dist/cli.js \"$@\"";
+    }
+  }
+
+  if (spec.tsx !== false) {
+    const v = spec.tsx ?? "4.20.0";
+    const dir = p.join(nodeModules, "tsx");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "tsx",
+      version: v,
+      main: "dist/cli.mjs",
+      bin: { tsx: "dist/cli.mjs" },
+    });
+    out[p.join(dir, "dist", "cli.mjs")] = "#!/usr/bin/env node";
+    if (spec.platform === "win32") {
+      out[p.join(binDir, "tsx.cmd")] = "@node %~dp0\\..\\tsx\\dist\\cli.mjs %*";
+    } else {
+      out[p.join(binDir, "tsx")] = "#!/bin/sh\nexec node ../tsx/dist/cli.mjs \"$@\"";
+    }
+  }
+
+  return out;
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/npm-global-layout.ts

@@ -0,0 +1,122 @@
+/**
+ * Fixture: global npm install layout.
+ *
+ * Posix:   /usr/lib/node_modules/<pkg>/...
+ * Windows: %APPDATA%\Roaming\npm\node_modules\<pkg>\...
+ *          with pi.cmd / openspec.cmd shims in %APPDATA%\Roaming\npm\
+ *
+ * For the "%ProgramFiles%\nodejs" variant on Windows, see
+ * `npmGlobalWindowsProgramFiles` — npm is installed there when users pick
+ * "Add to PATH" during Node.js installer.
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+import { openspecPackageJson, piPackageJson, type PiVersionSpec } from "./pi-versions.js";
+
+interface PosixSpec {
+  pi?: PiVersionSpec | false;
+  openspec?: string | false;
+  /** Install root; defaults to `/usr/lib/node_modules`. */
+  root?: string;
+  binDir?: string;
+}
+
+interface WindowsSpec {
+  pi?: PiVersionSpec | false;
+  openspec?: string | false;
+  dashboard?: boolean;
+  /** Where %APPDATA%\Roaming\npm lives. */
+  npmDir?: string;
+}
+
+/**
+ * Unix global npm install. Root defaults to `/usr/lib/node_modules`,
+ * binaries at `/usr/local/bin`.
+ */
+export function npmGlobalUnix(spec: PosixSpec = {}): FsRecord {
+  const p = posix;
+  const root = spec.root ?? "/usr/lib/node_modules";
+  const binDir = spec.binDir ?? "/usr/local/bin";
+  const out: Record<string, string> = {};
+
+  if (spec.pi !== false) {
+    const piSpec = spec.pi ?? {};
+    const piDir = p.join(root, "@mariozechner", "pi-coding-agent");
+    out[p.join(piDir, "package.json")] = piPackageJson(piSpec);
+    out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(binDir, "pi")] = "#!/bin/sh\nexec node ...";
+  }
+
+  if (spec.openspec !== false) {
+    // openspec tool definition uses package `@fission-ai/openspec`
+    // with entry `bin/openspec.js` (see definitions.ts).
+    const dir = p.join(root, "@fission-ai", "openspec");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "@fission-ai/openspec",
+      version: spec.openspec ?? "0.4.1",
+      bin: { openspec: "bin/openspec.js" },
+    });
+    out[p.join(dir, "bin", "openspec.js")] = "#!/usr/bin/env node";
+    out[p.join(binDir, "openspec")] = "#!/bin/sh\nexec node ...";
+  }
+
+  return out;
+}
+
+/**
+ * Windows AppData\Roaming\npm layout — the default for MSI installs of
+ * Node.js. `npmDir` overrides the location.
+ */
+export function npmGlobalWindowsAppData(
+  homedir: string,
+  spec: WindowsSpec = {},
+): FsRecord {
+  const p = win32;
+  const npmDir = spec.npmDir ?? p.join(homedir, "AppData", "Roaming", "npm");
+  const nodeModules = p.join(npmDir, "node_modules");
+  const out: Record<string, string> = {};
+
+  if (spec.pi !== false) {
+    const piSpec = spec.pi ?? {};
+    const piDir = p.join(nodeModules, "@mariozechner", "pi-coding-agent");
+    out[p.join(piDir, "package.json")] = piPackageJson(piSpec);
+    out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(npmDir, "pi.cmd")] = "@node %~dp0\\node_modules\\@mariozechner\\pi-coding-agent\\dist\\cli.js %*";
+  }
+
+  if (spec.openspec !== false) {
+    const dir = p.join(nodeModules, "@fission-ai", "openspec");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "@fission-ai/openspec",
+      version: spec.openspec ?? "0.4.1",
+      bin: { openspec: "bin/openspec.js" },
+    });
+    out[p.join(dir, "bin", "openspec.js")] = "#!/usr/bin/env node";
+    out[p.join(npmDir, "openspec.cmd")] = "@node %~dp0\\node_modules\\@fission-ai\\openspec\\bin\\openspec.js %*";
+  }
+
+  if (spec.dashboard) {
+    const dir = p.join(nodeModules, "@blackbelt-technology", "pi-agent-dashboard");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "@blackbelt-technology/pi-agent-dashboard",
+      version: "0.4.0",
+      bin: { "pi-dashboard": "packages/server/dist/cli.js" },
+    });
+    out[p.join(dir, "packages", "server", "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(npmDir, "pi-dashboard.cmd")] = "@node %~dp0\\node_modules\\@blackbelt-technology\\pi-agent-dashboard\\packages\\server\\dist\\cli.js %*";
+  }
+
+  return out;
+}
+
+/**
+ * Windows %ProgramFiles%\nodejs\node_modules layout — picked when Node
+ * installer chose "install as system tool."
+ */
+export function npmGlobalWindowsProgramFiles(spec: WindowsSpec = {}): FsRecord {
+  return npmGlobalWindowsAppData("C:\\Program Files\\nodejs_", {
+    ...spec,
+    npmDir: "C:\\Program Files\\nodejs",
+  });
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/pi-versions.ts

@@ -0,0 +1,36 @@
+/**
+ * Fixture: stamp a specific version into a pi-coding-agent package.json.
+ * Returns the package.json JSON string ready for FsRecord insertion.
+ */
+export interface PiVersionSpec {
+  name?: string;
+  version?: string;
+  bin?: Record<string, string>;
+  main?: string;
+}
+
+export function piPackageJson(spec: PiVersionSpec = {}): string {
+  return JSON.stringify(
+    {
+      name: spec.name ?? "@mariozechner/pi-coding-agent",
+      version: spec.version ?? "0.6.3",
+      main: spec.main ?? "dist/cli.js",
+      bin: spec.bin ?? { pi: "dist/cli.js" },
+    },
+    null,
+    2,
+  );
+}
+
+export function openspecPackageJson(version = "0.4.1"): string {
+  return JSON.stringify(
+    {
+      name: "openspec",
+      version,
+      main: "dist/index.js",
+      bin: { openspec: "dist/cli.js" },
+    },
+    null,
+    2,
+  );
+}