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

package/packages/shared/src/__tests__/bootstrap/families/a-electron.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Family A — Electron-packaged dashboard scenarios.
+ *
+ * A1: electron-fresh   — bundled dashboard, no pi, no settings.
+ * A2: electron-prewarmed — bundled dashboard, managed pi+openspec, valid settings.
+ *
+ * Full family (A3, A4) lands as cells are activated in tasks.md §6.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv, layer } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+// Register the cells this file covers. Overrides the bulk-skip from
+// scenarios-skipped.ts. Runs at module import.
+const A1: Parameters<typeof register>[0][] = [
+  { platform: "linux", dash: "electron", pi: "absent", settings: "missing", env: "normal" },
+  { platform: "darwin", dash: "electron", pi: "absent", settings: "missing", env: "normal" },
+  { platform: "win32", dash: "electron", pi: "absent", settings: "missing", env: "normal" },
+];
+const A2: Parameters<typeof register>[0][] = [
+  { platform: "linux", dash: "electron", pi: "present-valid", settings: "valid", env: "normal" },
+  { platform: "darwin", dash: "electron", pi: "present-valid", settings: "valid", env: "normal" },
+  { platform: "win32", dash: "electron", pi: "present-valid", settings: "valid", env: "normal" },
+];
+// A3: electron bundled + global pi (user had pi before installing dashboard).
+const A3: Parameters<typeof register>[0][] = [
+  { platform: "linux", dash: "electron", pi: "present-no-ext", settings: "valid", env: "normal" },
+];
+// A4: linux AppImage first run (temp mount; bridge registration skipped).
+const A4: Parameters<typeof register>[0][] = [
+  { platform: "linux", dash: "electron", pi: "appimage-tmp", settings: "missing", env: "normal" },
+];
+for (const cell of [...A1, ...A2, ...A3, ...A4]) {
+  register(cell, "families/a-electron.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family A — electron-packaged", () => {
+  describe("A1 — electron-fresh (bundled dashboard, no pi)", () => {
+    it.each(["linux", "darwin", "win32"] as const)(
+      "resolves nothing for pi (%s)",
+      async (platform) => {
+        const homedir = platform === "win32" ? "C:\\Users\\R" : "/home/r";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            env: { PATH: platform === "win32" ? "C:\\Windows\\System32" : "/usr/bin" },
+            fs: layer(fixtures.electronPackaged({ platform })),
+          },
+          (ctx) => {
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            expect(res.ok).toBe(false);
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+  });
+
+  describe("A2 — electron-prewarmed (bundled + managed pi)", () => {
+    it.each(["linux", "darwin", "win32"] as const)(
+      "resolves pi via managed (%s)",
+      async (platform) => {
+        const homedir = platform === "win32" ? "C:\\Users\\R" : "/home/r";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            env: { PATH: platform === "win32" ? "C:\\Windows\\System32" : "/usr/bin" },
+            fs: layer(
+              fixtures.electronPackaged({ platform }),
+              fixtures.managedInstall({ homedir, platform }),
+              fixtures.settingsJson({
+                homedir,
+                platform,
+                packages: [
+                  platform === "win32"
+                    ? "C:\\Program Files\\PI Dashboard\\resources\\server\\packages\\extension"
+                    : "/usr/lib/pi-dashboard/resources/server/packages/extension",
+                ],
+              }),
+            ),
+          },
+          (ctx) => {
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            expect(res.ok).toBe(true);
+            expect(res.source).toBe("managed");
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+  });
+
+  describe("A3 — electron + pre-existing global pi", () => {
+    it("global npm pi takes precedence over managed-bin fallback (linux)", async () => {
+      const homedir = "/home/r";
+      await withFakeEnv(
+        {
+          platform: "linux",
+          homedir,
+          env: { PATH: "/usr/local/bin" },
+          fs: layer(
+            fixtures.electronPackaged({ platform: "linux" }),
+            fixtures.npmGlobalUnix({}),
+            fixtures.settingsJson({ homedir, platform: "linux", packages: [] }),
+          ),
+        },
+        (ctx) => {
+          const registry = ctx.createRegistry();
+          registerDefaultTools(registry, ctx.createStrategyDeps());
+          const res = registry.resolve("pi");
+          // pi chain on posix: override → managed-bin → where.
+          // No managed install present; `where` finds /usr/local/bin/pi.
+          expect(res.ok).toBe(true);
+          expect(res.source).toBe("system");
+          expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+        },
+      );
+    });
+  });
+
+  describe("A4 — AppImage first run (temp mount)", () => {
+    it("findBundledExtension rejects /tmp/.mount_* paths", async () => {
+      const homedir = "/home/r";
+      await withFakeEnv(
+        {
+          platform: "linux",
+          homedir,
+          fs: fixtures.electronPackaged({ platform: "linux", appimage: true }),
+        },
+        (ctx) => {
+          // The bundled extension resolved by findBundledExtension when
+          // running from an AppImage temp mount would be under
+          // `/tmp/.mount_*/...`. The real implementation rejects those
+          // paths explicitly (bridge-register.ts). Here we just verify
+          // the fixture places files where the temp-mount detection
+          // would fire.
+          const paths = fixtures.electronPaths({ platform: "linux", appimage: true });
+          expect(paths.extensionDir).toContain("/tmp/.mount_");
+          expect(ctx.fs.existsSync(paths.extensionDir + "/package.json")).toBe(true);
+          // Full round-trip rejection lives in bridge-register unit
+          // tests; this family cell confirms only the fixture shape.
+        },
+      );
+    });
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/b-npm-global.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Family B — npm-global install scenarios.
+ *
+ * B1: npm-g dash only (⚠ Windows bug) — pi UNRESOLVED.
+ * B2: npm-g full — pi + openspec via global npm.
+ * B3: npm-g pi-installed-first — pi present, settings lacks bridge;
+ *     dashboard registers on boot (delta assertion).
+ *
+ * B1 is the key scenario: current behavior when a Windows user runs
+ * `npm i -g pi-dashboard` without first installing pi. This snapshot
+ * captures the broken state; `unified-bootstrap-install` will flip it.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv, layer } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail, snapshotSettingsDelta } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const B1 = [
+  { platform: "linux", dash: "npm-g", pi: "absent", settings: "missing", env: "normal" },
+  { platform: "darwin", dash: "npm-g", pi: "absent", settings: "missing", env: "normal" },
+  { platform: "win32", dash: "npm-g", pi: "absent", settings: "missing", env: "normal" },
+] as const;
+const B2 = [
+  { platform: "linux", dash: "npm-g", pi: "present-valid", settings: "valid", env: "normal" },
+  { platform: "darwin", dash: "npm-g", pi: "present-valid", settings: "valid", env: "normal" },
+  { platform: "win32", dash: "npm-g", pi: "present-valid", settings: "valid", env: "normal" },
+] as const;
+const B3 = [
+  { platform: "linux", dash: "npm-g", pi: "present-no-ext", settings: "empty", env: "normal" },
+] as const;
+for (const cell of [...B1, ...B2, ...B3]) {
+  register(cell, "families/b-npm-global.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family B — npm-global", () => {
+  describe("B1 — npm-g dash-only (⚠ captures current Windows bug)", () => {
+    it.each(["linux", "darwin", "win32"] as const)(
+      "pi unresolved on %s",
+      async (platform) => {
+        const homedir = platform === "win32" ? "C:\\Users\\R" : "/home/r";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            env: platform === "win32"
+              ? { PATH: "C:\\Users\\R\\AppData\\Roaming\\npm" }
+              : { PATH: "/usr/local/bin" },
+            fs: platform === "win32"
+              // On Windows we ship dash only — no pi, no openspec.
+              ? fixtures.npmGlobalWindowsAppData(homedir, {
+                  dashboard: true,
+                  pi: false,
+                  openspec: false,
+                })
+              : fixtures.npmGlobalUnix({ pi: false, openspec: false }),
+          },
+          (ctx) => {
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            expect(res.ok).toBe(false);
+            // FIXED-BY: unified-bootstrap-install.
+            // When that proposal lands, update the snapshot: pi should
+            // resolve via managed after first-run bootstrap.
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+  });
+
+  describe("B2 — npm-g full (pi + openspec via global npm)", () => {
+    it.each(["linux", "darwin"] as const)(
+      "pi resolves via npm-global on %s",
+      async (platform) => {
+        const homedir = "/home/r";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            env: { PATH: "/usr/local/bin" },
+            fs: fixtures.npmGlobalUnix({}),
+          },
+          (ctx) => {
+            // On Unix, the pi strategy chain only has override → managed-bin
+            // → where. `where` finds /usr/local/bin/pi. So source === "system"
+            // not "npm-global" — the current strategy chain doesn't know
+            // about npm-g on Unix at the executor level.
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            expect(res.ok).toBe(true);
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+
+    it("pi resolves via npm-global on win32 (with node.exe toArgv)", async () => {
+      const homedir = "C:\\Users\\R";
+      await withFakeEnv(
+        {
+          platform: "win32",
+          homedir,
+          env: {
+            PATH: "C:\\Users\\R\\AppData\\Roaming\\npm;C:\\Program Files\\nodejs",
+          },
+          fs: layer(
+            fixtures.npmGlobalWindowsAppData(homedir, { dashboard: true }),
+            { "C:\\Program Files\\nodejs\\node.exe": "\x7fELF" },
+          ),
+        },
+        (ctx) => {
+          const registry = ctx.createRegistry();
+          registerDefaultTools(registry, ctx.createStrategyDeps());
+          const executor = registry.resolveExecutor("pi");
+          expect(executor.ok).toBe(true);
+          expect(executor.source).toBe("npm-global");
+          // No-cmd-flash invariant for npm-g on Windows: argv[0] is
+          // node.exe, argv[1] is cli.js. The snapshot locks this in.
+          expect(executor.argv[0]).toBe("C:\\Program Files\\nodejs\\node.exe");
+          expect(snapshotTrail(executor, ctx)).toMatchSnapshot();
+        },
+      );
+    });
+  });
+
+  describe("B3 — npm-g pi-installed-first (bridge needs registration)", () => {
+    it("settings.json present but lacks bridge entry (linux)", async () => {
+      const homedir = "/home/r";
+      await withFakeEnv(
+        {
+          platform: "linux",
+          homedir,
+          fs: layer(
+            fixtures.npmGlobalUnix({}),
+            fixtures.settingsJson({ homedir, platform: "linux", packages: [] }),
+          ),
+        },
+        (ctx) => {
+          // Input-side assertion: the fixture correctly produces a
+          // settings.json without the bridge entry. Full round-trip
+          // (calling `registerBridgeExtension` and observing the
+          // mutation) requires `bridge-register` to accept an
+          // injectable fs — future task, cross-proposal.
+          const before = ctx.readSettings() as { packages?: string[] } | null;
+          expect(before).toEqual({ packages: [] });
+          const after = before; // no mutation via harness
+          expect(snapshotSettingsDelta(before, after, ctx)).toMatchSnapshot();
+        },
+      );
+    });
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/c-dev-monorepo.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Family C — dev monorepo scenarios.
+ *
+ * C1: mac/linux — bare-import resolves pi via workspace node_modules.
+ * C2: win32 — same, plus node.exe toArgv invariant.
+ *
+ * The bare-import strategy only runs for pi on win32 (see pi's
+ * winStrategies in definitions.ts). On Unix, pi on Unix still resolves
+ * via managed-bin → where. So the interesting "dev monorepo resolves
+ * via bare-import" path is Windows-only today. C1 asserts what Unix
+ * actually does (no bare-import in its chain).
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv, layer } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+// C1 posix — dev dash, pi present via workspace; settings typically empty
+// at dev time.
+const C1 = [
+  { platform: "linux", dash: "dev", pi: "present-valid", settings: "empty", env: "normal" },
+  { platform: "darwin", dash: "dev", pi: "present-valid", settings: "empty", env: "normal" },
+] as const;
+
+// C2 — Windows dev layout is already skipped in scenarios-skipped.ts
+// with reason "rare; capture if reported". We still add a test case
+// that registers the cell so the bare-import + toArgv invariant is
+// locked in — developers on Windows do exist.
+const C2 = [
+  { platform: "win32", dash: "dev", pi: "present-valid", settings: "empty", env: "normal" },
+] as const;
+
+for (const cell of [...C1, ...C2]) {
+  register(cell, "families/c-dev-monorepo.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family C — dev monorepo", () => {
+  describe("C1 — posix (managed/where chain, no bare-import for pi)", () => {
+    it.each(["linux", "darwin"] as const)(
+      "pi chain runs on %s",
+      async (platform) => {
+        const root = "/home/dev/pi-agent-dashboard";
+        const homedir = "/home/dev";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            cwd: root,
+            env: { PATH: "/usr/bin" },
+            fs: fixtures.devMonorepo({ root, platform }),
+          },
+          (ctx) => {
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            // Nothing on PATH, nothing in ~/.pi-dashboard — unresolved.
+            // The workspace node_modules is only reachable via
+            // bare-import, which isn't in pi's Unix chain.
+            expect(res.ok).toBe(false);
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+  });
+
+  describe("C2 — win32 (bare-import from workspace)", () => {
+    it("resolves pi via workspace bare-import", async () => {
+      const root = "C:\\dev\\pi-agent-dashboard";
+      const homedir = "C:\\Users\\Dev";
+      await withFakeEnv(
+        {
+          platform: "win32",
+          homedir,
+          cwd: root,
+          env: { PATH: "C:\\Windows\\System32" },
+          fs: layer(fixtures.devMonorepo({ root, platform: "win32" })),
+        },
+        (ctx) => {
+          // Build deps with a resolveModule anchor at the workspace
+          // root so bareImportCliStrategy finds pi-coding-agent.
+          const baseDeps = ctx.createStrategyDeps();
+          const rootAnchor = `${root}\\packages\\shared\\src\\index.ts`;
+          const deps = {
+            ...baseDeps,
+            resolveModule: (id: string, _from: string) =>
+              baseDeps.resolveModule(id, rootAnchor),
+          };
+          const registry = ctx.createRegistry();
+          registerDefaultTools(registry, deps);
+          const res = registry.resolve("pi");
+          expect(res.ok).toBe(true);
+          expect(res.source).toBe("bare-import");
+          expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+        },
+      );
+    });
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/d-overrides.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Family D — overrides.
+ *
+ * D1: override-valid   — pi resolves via override, source = "override".
+ * D2: override-invalid — broken path; falls through to next strategy.
+ *
+ * Overrides override platform. We test on linux; Windows is covered
+ * structurally because overrideStrategy is first in every chain.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+// Overrides are orthogonal to the cube's pi-state axis — treat as
+// "present-valid" scenarios for taxonomy purposes.
+const D = [
+  { platform: "linux", dash: "managed", pi: "present-valid", settings: "empty", env: "normal" },
+  { platform: "darwin", dash: "managed", pi: "present-valid", settings: "empty", env: "normal" },
+] as const;
+for (const cell of D) {
+  register(cell, "families/d-overrides.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family D — overrides", () => {
+  it("D1 — override-valid: pi resolves via override", async () => {
+    const homedir = "/home/r";
+    const overridePath = "/opt/custom/bin/pi";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        fs: {
+          [overridePath]: "#!/bin/sh\nexec custom-pi",
+          // Also managed, to prove override wins.
+          ...fixtures.managedInstall({ homedir, platform: "linux" }),
+        },
+        overrides: { pi: overridePath },
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("override");
+        expect(res.path).toBe(overridePath);
+        expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+      },
+    );
+  });
+
+  it("D2 — override-invalid: path doesn't exist, chain falls through", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        fs: fixtures.managedInstall({ homedir, platform: "linux" }),
+        overrides: { pi: "/nonexistent/broken/pi" },
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        // Override strategy returns `invalid: ...` as reason; next
+        // strategy (managed-bin) succeeds.
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("managed");
+        expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+      },
+    );
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/e-stale-partial.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Family E — stale / partial managed installs.
+ *
+ * E1: stale-managed   — managed pi version 0.0.1. TODAY the strategies
+ *     don't do version gating; resolution succeeds. Snapshot locks in
+ *     current behavior so version-skew detection (from proposal 2)
+ *     will force a snapshot update.
+ * E2: managed-partial — only package.json, no dist/cli.js. Strategy
+ *     returns not-found; next strategy runs.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const E1 = [
+  // present-stale-ext as cube axis for "installed but bridge registration is stale"
+  { platform: "linux", dash: "electron", pi: "present-stale-ext", settings: "valid", env: "normal" },
+  { platform: "darwin", dash: "electron", pi: "present-stale-ext", settings: "valid", env: "normal" },
+  { platform: "win32", dash: "electron", pi: "present-stale-ext", settings: "valid", env: "normal" },
+] as const;
+// E2 maps to "malformed" pi-state — the managed install is present but
+// broken (incomplete).
+const E2 = [
+  { platform: "linux", dash: "electron", pi: "malformed", settings: "empty", env: "normal" },
+  { platform: "win32", dash: "electron", pi: "malformed", settings: "empty", env: "normal" },
+] as const;
+for (const cell of [...E1, ...E2]) {
+  register(cell, "families/e-stale-partial.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family E — stale / partial", () => {
+  describe("E1 — stale managed pi (old version)", () => {
+    it.each(["linux", "darwin", "win32"] as const)(
+      "current strategies resolve without version gating (%s)",
+      async (platform) => {
+        const homedir = platform === "win32" ? "C:\\Users\\R" : "/home/r";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            fs: fixtures.managedInstall({
+              homedir,
+              platform,
+              pi: { version: "0.0.1" }, // very old
+            }),
+          },
+          (ctx) => {
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            expect(res.ok).toBe(true);
+            // NOTE: version-skew detection lands in
+            // `unified-bootstrap-install` — resolution still
+            // succeeds; the detection happens downstream in
+            // dependency-detector. Snapshot will shift when that
+            // detection is added to trail.
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+  });
+
+  describe("E2 — partial managed install (package.json, no dist)", () => {
+    it.each(["linux", "win32"] as const)(
+      "strategy skips when entry file absent (%s)",
+      async (platform) => {
+        const homedir = platform === "win32" ? "C:\\Users\\R" : "/home/r";
+        await withFakeEnv(
+          {
+            platform,
+            homedir,
+            fs: fixtures.managedInstall({
+              homedir,
+              platform,
+              piPartial: true, // package.json only, no dist/cli.js, no .bin shim
+            }),
+          },
+          (ctx) => {
+            const registry = ctx.createRegistry();
+            registerDefaultTools(registry, ctx.createStrategyDeps());
+            const res = registry.resolve("pi");
+            expect(res.ok).toBe(false);
+            expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+          },
+        );
+      },
+    );
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/f-cwd-variants.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Family F — cwd variants.
+ *
+ * F1: cwd-with-spaces  — cwd contains spaces. Resolution unaffected.
+ * F2: cwd-unicode      — cwd contains non-ASCII. Resolution unaffected.
+ *
+ * Today, cwd is NOT used by any strategy in the chain. Asserting that
+ * invariant via snapshots means if someone later adds cwd-sensitive
+ * resolution (e.g. workspace-local binaries), the change surfaces
+ * loudly in these snapshots.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const F = [
+  { platform: "linux", dash: "managed", pi: "present-valid", settings: "empty", env: "spaces-unicode" },
+  { platform: "win32", dash: "managed", pi: "present-valid", settings: "empty", env: "spaces-unicode" },
+] as const;
+for (const cell of F) {
+  register(cell, "families/f-cwd-variants.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family F — cwd variants", () => {
+  it("F1 — resolves normally with spaces in cwd (linux)", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        cwd: "/home/r/My Project With Spaces",
+        fs: fixtures.managedInstall({ homedir, platform: "linux" }),
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("managed");
+        expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+      },
+    );
+  });
+
+  it("F1 — resolves normally with Program Files (x86) cwd (win32)", async () => {
+    const homedir = "C:\\Users\\R";
+    await withFakeEnv(
+      {
+        platform: "win32",
+        homedir,
+        cwd: "C:\\Program Files (x86)\\Pi Dashboard",
+        fs: fixtures.managedInstall({ homedir, platform: "win32" }),
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("managed");
+        expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+      },
+    );
+  });
+
+  it("F2 — resolves with Greek/Cyrillic/emoji in cwd", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        cwd: "/home/r/πρότζεκτ_тест_🚀",
+        fs: fixtures.managedInstall({ homedir, platform: "linux" }),
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+      },
+    );
+  });
+});