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

package/packages/shared/src/__tests__/bootstrap/README.md

@@ -0,0 +1,133 @@
+# Bootstrap Resolution Harness
+
+In-memory test harness for the dashboard's bootstrap resolution —
+`ToolRegistry` + bridge-extension registration — across install
+mechanics, platforms, and HOME/path drift.
+
+**See** `openspec/changes/bootstrap-resolution-harness/{proposal,design}.md`
+for the full design rationale.
+
+## Why
+
+The dashboard resolves pi, node, openspec, tsx across 5 strategies on
+3 platforms. It writes bridge registration into pi's `settings.json` at
+a HOME-dependent path. Small changes in these code paths can silently
+break a specific install mechanic (`npm i -g pi-dashboard` on Windows,
+Electron AppImage, GUI-launched PATH, etc.). This harness captures the
+full state space in a memfs-backed cube so regressions surface in ms.
+
+## File layout
+
+```
+bootstrap/
+├── harness.ts               ← withFakeEnv(), layer(), memfs wiring
+├── assertions.ts            ← snapshotTrail, snapshotSettingsDelta
+├── scenarios.ts             ← register(), skip(), cellKey(), enumerateCube()
+├── scenarios-skipped.ts     ← bulk-skip manifest (everything defaults to skipped)
+├── cube.ts                  ← sweepCube() + formatUnclassifiedError()
+├── cube.test.ts             ← fail-closed sweep (breaks CI on unclassified cells)
+├── fixtures/
+│   ├── managed-install.ts    ← ~/.pi-dashboard/ layout
+│   ├── npm-global-layout.ts  ← /usr/lib/node_modules + %APPDATA%\Roaming\npm
+│   ├── electron-layout.ts    ← packaged Electron resources
+│   ├── dev-monorepo.ts       ← workspace + hoisted deps
+│   ├── settings-json.ts      ← pi's settings.json variants
+│   └── pi-versions.ts        ← package.json stampers
+└── families/
+    ├── index.ts              ← barrel — imports every family file
+    ├── a-electron.test.ts    ← Family A
+    ├── b-npm-global.test.ts  ← Family B (contains ⚠ Windows bug capture)
+    ├── ... c through k
+    └── __snapshots__/        ← trail + settings-delta snapshots
+```
+
+## Running
+
+```
+npm run test:bootstrap          # one-shot
+npm run test:bootstrap:watch    # iteration mode
+```
+
+Runs in ~2 seconds. Produces 80+ tests, 40+ trail snapshots.
+
+## Adding a scenario
+
+1. Identify the cell-key: `<platform>/<dash>/<pi>/<settings>/<env>`
+   (see `scenarios.ts` for axis values).
+
+2. Write a family test (or extend an existing one):
+
+   ```ts
+   const MY_CELLS = [
+     { platform: "win32", dash: "managed", pi: "present-valid",
+       settings: "valid", env: "normal" },
+   ] as const;
+   for (const cell of MY_CELLS) {
+     register(cell, "families/my-family.test.ts");
+     SKIPPED_SCENARIOS.delete(cellKey(cell));
+   }
+
+   describe("My family", () => {
+     it("demonstrates something", async () => {
+       await withFakeEnv(
+         { platform: "win32", homedir: "C:\\Users\\R",
+           fs: fixtures.managedInstall({ homedir: "C:\\Users\\R", platform: "win32" }) },
+         (ctx) => {
+           const registry = ctx.createRegistry();
+           registerDefaultTools(registry, ctx.createStrategyDeps());
+           const res = registry.resolve("pi");
+           expect(res.ok).toBe(true);
+           expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+         },
+       );
+     });
+   });
+   ```
+
+3. Add the file to `families/index.ts` so the cube sweep picks up
+   its registrations.
+
+4. Run `npm run test:bootstrap -- -u` to write the snapshot.
+
+## Adding a skip
+
+Pure skip (no test):
+
+```ts
+// in scenarios-skipped.ts, extend skipReasonFor()
+if (cell.platform === "win32" && cell.env === "spaces-unicode") {
+  return "win32 + spaces-unicode: add when a bug reports here";
+}
+```
+
+Skips MUST have a non-empty reason — enforced by `skip()` at runtime.
+
+## Fail-closed invariant
+
+`cube.test.ts` fails if any cell is neither registered nor explicitly
+skipped. Adding a new axis value (e.g. a new platform or install
+location) breaks the test until each resulting cell is categorized.
+
+Cube shape: 3 platforms × 5 dash-locations × 6 pi-states × 4 settings
+× 3 env = **1080 cells**.
+
+Current state: ~30 registered, ~1050 skipped with documented reasons.
+
+## Snapshot stability
+
+`normalizePath` rewrites `<HOME>`, `<NPM_ROOT>`, flips separators. This
+makes snapshots stable across macOS/Linux CI. Windows CI snapshots may
+shift marginally when run natively (path-join behavior); if that
+surfaces, add platform-specific snapshot files.
+
+## Downstream handoff
+
+- **B1 snapshot** (Windows `npm i -g pi-dashboard` → pi unresolved)
+  is the input for `unified-bootstrap-install` (proposal 2). When (2)
+  lands, the expected outcome flips from "unresolved" to "resolves
+  via managed after bootstrap." Update the snapshot as part of (2)'s
+  task list.
+
+- **Family L cells** (lock-file scenarios) will be added by
+  `single-dashboard-per-home` (proposal 3). That proposal introduces
+  a new axis (lock state) not modelled in the current cube.

package/packages/shared/src/__tests__/bootstrap/__snapshots__/cube.test.ts.snap

@@ -0,0 +1,370 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Family A — electron-packaged > A1 — electron-fresh (bundled dashboard, no pi) > resolves nothing for pi (darwin) 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family A — electron-packaged > A1 — electron-fresh (bundled dashboard, no pi) > resolves nothing for pi (linux) 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family A — electron-packaged > A1 — electron-fresh (bundled dashboard, no pi) > resolves nothing for pi (win32) 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js
+  npm-global   missing: <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js
+  npm-global   missing: <NPM_ROOT>/@oh-my-pi/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi.cmd
+  where        not found on PATH"
+`;
+
+exports[`Family A — electron-packaged > A2 — electron-prewarmed (bundled + managed pi) > resolves pi via managed (darwin) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     no override set
+  managed      ok"
+`;
+
+exports[`Family A — electron-packaged > A2 — electron-prewarmed (bundled + managed pi) > resolves pi via managed (linux) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     no override set
+  managed      ok"
+`;
+
+exports[`Family A — electron-packaged > A2 — electron-prewarmed (bundled + managed pi) > resolves pi via managed (win32) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      ok"
+`;
+
+exports[`Family A — electron-packaged > A3 — electron + pre-existing global pi > global npm pi takes precedence over managed-bin fallback (linux) 1`] = `
+"name:   pi
+ok:     true
+source: system
+path:   /usr/local/bin/pi
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        ok"
+`;
+
+exports[`Family B — npm-global > B1 — npm-g dash-only (⚠ captures current Windows bug) > pi unresolved on darwin 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family B — npm-global > B1 — npm-g dash-only (⚠ captures current Windows bug) > pi unresolved on linux 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family B — npm-global > B1 — npm-g dash-only (⚠ captures current Windows bug) > pi unresolved on win32 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js
+  npm-global   missing: <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js
+  npm-global   missing: <NPM_ROOT>/@oh-my-pi/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi.cmd
+  where        not found on PATH"
+`;
+
+exports[`Family B — npm-global > B2 — npm-g full (pi + openspec via global npm) > pi resolves via npm-global on darwin 1`] = `
+"name:   pi
+ok:     true
+source: system
+path:   /usr/local/bin/pi
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        ok"
+`;
+
+exports[`Family B — npm-global > B2 — npm-g full (pi + openspec via global npm) > pi resolves via npm-global on linux 1`] = `
+"name:   pi
+ok:     true
+source: system
+path:   /usr/local/bin/pi
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        ok"
+`;
+
+exports[`Family B — npm-global > B2 — npm-g full (pi + openspec via global npm) > pi resolves via npm-global on win32 (with node.exe toArgv) 1`] = `
+"name:   pi
+ok:     true
+source: npm-global
+path:   <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js
+  npm-global   ok
+argv:
+  - C:/Program Files/nodejs/node.exe
+  - <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js"
+`;
+
+exports[`Family B — npm-global > B3 — npm-g pi-installed-first (bridge needs registration) > settings.json present but lacks bridge entry (linux) 1`] = `
+"settings-delta:
+  added:
+    (none)
+  removed:
+    (none)
+  preserved:
+    (none)"
+`;
+
+exports[`Family C — dev monorepo > C1 — posix (managed/where chain, no bare-import for pi) > pi chain runs on darwin 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family C — dev monorepo > C1 — posix (managed/where chain, no bare-import for pi) > pi chain runs on linux 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family C — dev monorepo > C2 — win32 (bare-import from workspace) > resolves pi via workspace bare-import 1`] = `
+"name:   pi
+ok:     true
+source: bare-import
+path:   dist/cli.js
+tried:
+  override     no override set
+  bare-import  ok"
+`;
+
+exports[`Family D — overrides > D1 — override-valid: pi resolves via override 1`] = `
+"name:   pi
+ok:     true
+source: override
+path:   /opt/custom/bin/pi
+tried:
+  override     ok"
+`;
+
+exports[`Family D — overrides > D2 — override-invalid: path doesn't exist, chain falls through 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     invalid: path does not exist: /nonexistent/broken/pi
+  managed      ok"
+`;
+
+exports[`Family E — stale / partial > E1 — stale managed pi (old version) > current strategies resolve without version gating (darwin) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     no override set
+  managed      ok"
+`;
+
+exports[`Family E — stale / partial > E1 — stale managed pi (old version) > current strategies resolve without version gating (linux) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     no override set
+  managed      ok"
+`;
+
+exports[`Family E — stale / partial > E1 — stale managed pi (old version) > current strategies resolve without version gating (win32) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      ok"
+`;
+
+exports[`Family E — stale / partial > E2 — partial managed install (package.json, no dist) > strategy skips when entry file absent (linux) 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;
+
+exports[`Family E — stale / partial > E2 — partial managed install (package.json, no dist) > strategy skips when entry file absent (win32) 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js
+  npm-global   missing: <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js
+  npm-global   missing: <NPM_ROOT>/@oh-my-pi/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi.cmd
+  where        not found on PATH"
+`;
+
+exports[`Family F — cwd variants > F1 — resolves normally with Program Files (x86) cwd (win32) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      ok"
+`;
+
+exports[`Family F — cwd variants > F1 — resolves normally with spaces in cwd (linux) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     no override set
+  managed      ok"
+`;
+
+exports[`Family F — cwd variants > F2 — resolves with Greek/Cyrillic/emoji in cwd 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/.bin/pi
+tried:
+  override     no override set
+  managed      ok"
+`;
+
+exports[`Family G — Windows specifics > G1 — pi.cmd resolved + toArgv prepends node.exe (no-cmd-flash) 1`] = `
+"name:   pi
+ok:     true
+source: managed
+path:   <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      ok
+argv:
+  - C:/Program Files/nodejs/node.exe
+  - <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js"
+`;
+
+exports[`Family G — Windows specifics > G2 — npm-g at %APPDATA%\\Roaming\\npm (argv prepends node.exe) 1`] = `
+"name:   pi
+ok:     true
+source: npm-global
+path:   <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js
+tried:
+  override     no override set
+  bare-import  cannot resolve @mariozechner/pi-coding-agent/package.json
+  bare-import  cannot resolve @oh-my-pi/pi-coding-agent/package.json
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+  managed      missing: <HOME>/.pi-dashboard/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js
+  npm-global   ok
+argv:
+  - C:/Program Files/nodejs/node.exe
+  - <NPM_ROOT>/@mariozechner/pi-coding-agent/dist/cli.js"
+`;
+
+exports[`Family G — Windows specifics > G4 — node.exe at C:\\Program Files\\nodejs\\node.exe 1`] = `
+"name:   node
+ok:     true
+source: system
+path:   C:/Program Files/nodejs/node.exe
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/node.cmd
+  where        ok
+argv:
+  - C:/Program Files/nodejs/node.exe"
+`;
+
+exports[`Family J — minimal PATH > J1 — GUI-launched minimal PATH: pi does NOT resolve on posix (limitation) 1`] = `
+"name:   pi
+ok:     false
+source: —
+path:   —
+tried:
+  override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/pi
+  where        not found on PATH"
+`;

package/packages/shared/src/__tests__/bootstrap/assertions.ts

@@ -0,0 +1,136 @@
+/**
+ * Snapshot helpers — normalize environment-specific paths so snapshots
+ * are stable across OS/CI runs.
+ *
+ * See openspec/changes/bootstrap-resolution-harness/design.md §8, §9.
+ */
+import type { ExecutorResolution, Resolution } from "../../tool-registry/types.js";
+import type { HarnessContext } from "./harness.js";
+
+/**
+ * A resolution that may carry executor argv. Trail snapshots accept
+ * both plain `Resolution` (from `registry.resolve()`) and
+ * `ExecutorResolution` (from `registry.resolveExecutor()`) — when argv
+ * is present, it's rendered in the snapshot to lock in the
+ * no-cmd-flash / node-prepend invariant on Windows.
+ */
+type MaybeExecutor = Resolution | ExecutorResolution;
+
+/**
+ * Normalize a path for snapshot stability:
+ *   - replace homedir with `<HOME>`
+ *   - replace npm-root with `<NPM_ROOT>`
+ *   - flip backslashes to forward slashes
+ *   - collapse duplicate slashes
+ */
+export function normalizePath(
+  p: string | null | undefined,
+  ctx: Pick<HarnessContext, "homedir" | "npmRootGlobal">,
+): string | null {
+  if (p == null) return null;
+  let out = p;
+  // Order matters: replace longer prefixes first.
+  const homeVariants = [ctx.homedir, ctx.homedir.replace(/\\/g, "/")];
+  const npmVariants = [ctx.npmRootGlobal, ctx.npmRootGlobal.replace(/\\/g, "/")];
+  for (const v of npmVariants) {
+    if (v) out = out.split(v).join("<NPM_ROOT>");
+  }
+  for (const v of homeVariants) {
+    if (v) out = out.split(v).join("<HOME>");
+  }
+  out = out.replace(/\\/g, "/");
+  return out;
+}
+
+/**
+ * Trail snapshot. Primary assertion for ToolRegistry resolution tests.
+ * Output is a multiline string ready for `toMatchSnapshot()`.
+ *
+ * When passed an `ExecutorResolution` (from `registry.resolveExecutor`),
+ * renders an `argv:` section proving the `toArgv` transform. On
+ * Windows this locks in the no-cmd-flash invariant — argv for a
+ * resolved `.js` target MUST be `[<node.exe>, <cli.js>]`, not the
+ * `.cmd` shim that would allocate a console.
+ */
+export function snapshotTrail(
+  resolution: MaybeExecutor,
+  ctx: Pick<HarnessContext, "homedir" | "npmRootGlobal">,
+): string {
+  const lines: string[] = [];
+  lines.push(`name:   ${resolution.name}`);
+  lines.push(`ok:     ${resolution.ok}`);
+  lines.push(`source: ${resolution.source ?? "—"}`);
+  lines.push(`path:   ${normalizePath(resolution.path, ctx) ?? "—"}`);
+  lines.push("tried:");
+  for (const entry of resolution.tried) {
+    // Normalize paths embedded in the reason string too (e.g.
+    // "missing: <HOME>/.pi-dashboard/...") so snapshots are
+    // stable across OS CI runners.
+    const result = normalizePath(entry.result, ctx) ?? entry.result;
+    lines.push(`  ${entry.strategy.padEnd(12)} ${result}`);
+  }
+  // argv section — present only when the caller invoked
+  // registry.resolveExecutor() (ExecutorResolution has `argv`).
+  const argv = (resolution as ExecutorResolution).argv;
+  if (Array.isArray(argv) && argv.length > 0) {
+    lines.push("argv:");
+    for (const a of argv) {
+      lines.push(`  - ${normalizePath(a, ctx) ?? a}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Diff two settings-json snapshots: which entries were added, removed,
+ * or preserved.
+ */
+export function snapshotSettingsDelta(
+  before: { packages?: readonly string[] } | null,
+  after: { packages?: readonly string[] } | null,
+  ctx: Pick<HarnessContext, "homedir" | "npmRootGlobal">,
+): string {
+  const beforeSet = new Set(before?.packages ?? []);
+  const afterSet = new Set(after?.packages ?? []);
+  const added = [...afterSet].filter((p) => !beforeSet.has(p));
+  const removed = [...beforeSet].filter((p) => !afterSet.has(p));
+  const preserved = [...beforeSet].filter((p) => afterSet.has(p));
+
+  const norm = (arr: string[]) =>
+    arr
+      .map((p) => normalizePath(p, ctx))
+      .filter((p): p is string => p !== null)
+      .sort();
+
+  const lines: string[] = [];
+  lines.push("settings-delta:");
+  lines.push(`  added:`);
+  for (const p of norm(added)) lines.push(`    + ${p}`);
+  if (added.length === 0) lines.push("    (none)");
+  lines.push(`  removed:`);
+  for (const p of norm(removed)) lines.push(`    - ${p}`);
+  if (removed.length === 0) lines.push("    (none)");
+  lines.push(`  preserved:`);
+  for (const p of norm(preserved)) lines.push(`    = ${p}`);
+  if (preserved.length === 0) lines.push("    (none)");
+  return lines.join("\n");
+}
+
+/**
+ * Simple snapshot of a settings.json object as a sorted list. Used when
+ * only the "after" state matters.
+ */
+export function snapshotSettings(
+  settings: { packages?: readonly string[] } | null,
+  ctx: Pick<HarnessContext, "homedir" | "npmRootGlobal">,
+): string {
+  if (!settings) return "settings.json: (absent)";
+  const packages = (settings.packages ?? [])
+    .map((p) => normalizePath(p, ctx))
+    .filter((p): p is string => p !== null)
+    .sort();
+  const lines: string[] = ["settings.json:", "  packages:"];
+  for (const p of packages) lines.push(`    - ${p}`);
+  if (packages.length === 0) lines.push("    (empty)");
+  return lines.join("\n");
+}

package/packages/shared/src/__tests__/bootstrap/cube.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Cube sweep — the fail-closed invariant. Every cell must be either
+ * registered (by a family-test file) or explicitly skipped (in
+ * `scenarios-skipped.ts`).
+ *
+ * New cells added to the enumeration — by extending PLATFORMS,
+ * DASH_LOCATIONS, PI_STATES, SETTINGS_STATES, or ENV_STATES in
+ * `scenarios.ts` — will break this test until a decision is made.
+ * This is intentional: the test forces every install mechanic to
+ * be categorized.
+ */
+import { describe, expect, it } from "vitest";
+import { sweepCube, formatUnclassifiedError } from "./cube.js";
+// IMPORTANT: import the skip manifest BEFORE any family-test file, so
+// the bulk skips are applied first and families override them via
+// `register()`.
+import "./scenarios-skipped.js";
+// Then import family files so their top-level `register(cell, tag)`
+// calls execute. Each family file clears the corresponding skip entry.
+import "./families/index.js";
+
+describe("bootstrap scenario cube", () => {
+  it("every cell is either registered or skipped (fail-closed)", () => {
+    const report = sweepCube();
+    if (report.unclassified.length > 0) {
+      throw new Error(formatUnclassifiedError(report));
+    }
+    expect(report.unclassified.length).toBe(0);
+  });
+
+  it("cube has the expected shape (3 × 5 × 6 × 4 × 3 = 1080 cells)", () => {
+    const report = sweepCube();
+    expect(report.total).toBe(1080);
+    expect(report.registered + report.skipped).toBe(report.total);
+  });
+
+  it("at least one family registered a cell (smoke)", () => {
+    const report = sweepCube();
+    expect(report.registered).toBeGreaterThan(0);
+    // Visible in test output so cube growth is trackable without
+    // digging into internals.
+    // eslint-disable-next-line no-console
+    console.log(
+      `[cube] registered=${report.registered} skipped=${report.skipped} total=${report.total}`,
+    );
+  });
+});