@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/packages/shared/src/__tests__/node-spawn-jiti-contract.test.ts

@@ -1,42 +1,42 @@
 /**
- * Pin the jiti version contract for `shouldUrlWrapEntry()`.
+ * Pin the jiti behavioural contract for `shouldUrlWrapEntry()`.
  *
- * The Windows-non-tsx arm in `platform/node-spawn.ts::shouldUrlWrapEntry`
- * relies on jiti's file:/// URL handling. This was VERIFIED on:
- *   - `@mariozechner/pi-coding-agent@0.70.x` shipping `jiti@2.x` (original baseline)
- *   - `@earendil-works/pi-coding-agent@0.74.x` shipping `jiti@^2.7.0` (current baseline)
- * It was BROKEN on `pi-coding-agent@0.71.x` shipping `jiti@2.6.5`, which
- * misnormalised triple-slash file:/// URLs on Windows. Keep that data
- * point in the contract so a contributor recognises the regression
- * pattern if it recurs.
+ * History
+ * -------
+ * Earlier versions of this contract attempted to pin a "verified-good"
+ * jiti version that correctly normalised `file:///` triple-slash URL
+ * entries on Windows. Live testing on Windows 11 + Node 22.18.0 + jiti
+ * 2.7.0 (shipped under `@earendil-works/pi-coding-agent@0.74.x`) showed
+ * that jiti still misnormalises those URLs:
+ *
+ *     Error: Cannot find module
+ *       'file:///C:/pi-dash-app/file:/C:/pi-dash-app/.../cli.ts'
+ *
+ * The triple-slash entry is rewritten to single-slash and then resolved
+ * against cwd as if it were a relative specifier. Rather than chase
+ * jiti versions, the contract now requires raw entry paths whenever
+ * the loader is jiti, on every OS. Node's drive-letter heuristic
+ * accepts raw `C:\…` argv entries directly, which covers the common
+ * standalone-install layout where pi + the dashboard sit under
+ * `C:\Users\<u>\.pi-dashboard\…`.
  *
  * This test ensures:
- *   1. The offline-cacache pin in `packages/electron/offline-packages.json`
- *      stays on a supported pi version under one of the two supported
- *      forks. A bump outside the verified set fires this test and
- *      forces the contributor to either:
- *        - re-verify the contract on Windows
- *        - add a per-jiti-version branch
- *        - switch the bundled loader to tsx
- *   2. The `shouldUrlWrapEntry` header comment documents the contract
- *      so future contributors discover the constraint at the call site.
+ *   1. `shouldUrlWrapEntry` returns `false` for jiti loaders on every
+ *      platform (POSIX + win32). Locks the behavioural rule against
+ *      regression.
+ *   2. The `shouldUrlWrapEntry` source comment still documents the
+ *      Windows breakage so future contributors discover the constraint.
  *
- * See changes: fix-electron-windows-installer-and-server-bootstrap (Defect 2),
- *              migrate-pi-fork-to-earendil (E.6).
+ * See change: fix-windows-standalone-spawn.
  */
 import { describe, it, expect } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import url from "node:url";
+import { shouldUrlWrapEntry, isJitiLoader } from "../platform/node-spawn.js";
 
 const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
-const OFFLINE_PACKAGES_PATH = path.join(
-  REPO_ROOT,
-  "packages",
-  "electron",
-  "offline-packages.json",
-);
 const NODE_SPAWN_PATH = path.join(
   REPO_ROOT,
   "packages",
@@ -46,97 +46,50 @@ const NODE_SPAWN_PATH = path.join(
   "node-spawn.ts",
 );
 
-/** Versions verified against the Windows file:/// jiti contract. */
-const VERIFIED_PI_PINS: ReadonlyArray<{ name: string; versionPrefix: string }> = [
-  { name: "@earendil-works/pi-coding-agent", versionPrefix: "0.74." },
-  { name: "@mariozechner/pi-coding-agent", versionPrefix: "0.70." },
-];
-
-describe("jiti version contract for shouldUrlWrapEntry", () => {
-  it("offline-packages.json pins pi-coding-agent at a verified version under a supported fork", () => {
-    const raw = fs.readFileSync(OFFLINE_PACKAGES_PATH, "utf8");
-    const manifest = JSON.parse(raw) as {
-      packages: { name: string; version: string }[];
-    };
-
-    const supportedNames = VERIFIED_PI_PINS.map((p) => p.name);
-    const piEntry = manifest.packages.find((p) =>
-      supportedNames.includes(p.name),
-    );
-    if (!piEntry) {
-      throw new Error(
-        `No supported pi-coding-agent fork found in offline-packages.json. ` +
-          `Expected one of: ${supportedNames.join(", ")}. ` +
-          `The offline cacache must include pi-coding-agent. ` +
-          `See changes: fix-electron-windows-installer-and-server-bootstrap (Defect 2), ` +
-          `migrate-pi-fork-to-earendil (E.6).`,
-      );
-    }
-
-    const verifiedPin = VERIFIED_PI_PINS.find(
-      (p) => p.name === piEntry.name && piEntry.version.startsWith(p.versionPrefix),
-    );
-    if (!verifiedPin) {
-      const allowedRanges = VERIFIED_PI_PINS
-        .map((p) => `${p.name}@${p.versionPrefix}x`)
-        .join(", ");
-      throw new Error(
-        `pi-coding-agent pinned at ${piEntry.name}@${piEntry.version}, but ` +
-          `shouldUrlWrapEntry()'s Windows-non-tsx arm only supports verified pins: ` +
-          `${allowedRanges}. ` +
-          `Newer jiti versions (e.g. 2.6.5 in pi 0.71.x) misnormalize ` +
-          `file:/// URL entries on Windows. Either re-verify the contract, ` +
-          `add a per-jiti-version branch in shouldUrlWrapEntry(), or switch ` +
-          `the bundled loader to tsx. See changes: ` +
-          `fix-electron-windows-installer-and-server-bootstrap (Defect 2), ` +
-          `migrate-pi-fork-to-earendil (E.6).`,
-      );
-    }
+describe("jiti behavioural contract for shouldUrlWrapEntry", () => {
+  it("jiti loader → entry passed RAW on every platform", () => {
+    const jitiLoader =
+      "file:///C:/Users/x/.pi-dashboard/node_modules/@earendil-works/pi-coding-agent/node_modules/jiti/lib/jiti-register.mjs";
+    expect(isJitiLoader(jitiLoader)).toBe(true);
+    expect(shouldUrlWrapEntry(jitiLoader, "win32")).toBe(false);
+    expect(shouldUrlWrapEntry(jitiLoader, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(jitiLoader, "darwin")).toBe(false);
+  });
 
-    expect(piEntry.version.startsWith(verifiedPin.versionPrefix)).toBe(true);
+  it("tsx loader → entry passed RAW on every platform (unchanged)", () => {
+    const tsxLoader = "file:///home/u/node_modules/tsx/dist/esm/index.mjs";
+    expect(shouldUrlWrapEntry(tsxLoader, "win32")).toBe(false);
+    expect(shouldUrlWrapEntry(tsxLoader, "linux")).toBe(false);
   });
 
-  it("node-spawn.ts source contains the documented JITI VERSION CONTRACT block", () => {
+  it("node-spawn.ts source documents the Windows jiti breakage", () => {
     const source = fs.readFileSync(NODE_SPAWN_PATH, "utf8");
 
-    // Contract block markers
     expect(source).toContain("JITI VERSION CONTRACT");
-    // Documented baseline references (at least one of the verified version markers).
-    const hasBaselineMarker =
-      source.includes("0.74.") || source.includes("0.70.x");
-    if (!hasBaselineMarker) {
-      throw new Error(
-        "shouldUrlWrapEntry() docstring is missing the verified-baseline marker. " +
-          "It must mention at least one of: '0.74.' (current earendil baseline) " +
-          "or '0.70.x' (legacy mariozechner baseline). See change: " +
-          "migrate-pi-fork-to-earendil (E.7).",
-      );
-    }
-
-    // Version drift markers (at least one of these identifies the broken jiti)
-    const hasVersionDriftMarker =
-      source.includes("0.71") || source.includes("2.6.5");
-    if (!hasVersionDriftMarker) {
+    // Documented Windows-breakage marker. The original error signature
+    // (single-slash file:/<cwd>/file:/…) is the cheapest fingerprint
+    // for a contributor matching a new repro to this contract.
+    const hasBreakageMarker =
+      /file:\/{1,3}.*file:\//.test(source) ||
+      /misnormali[sz]e/i.test(source);
+    if (!hasBreakageMarker) {
       throw new Error(
-        "shouldUrlWrapEntry() docstring is missing the version-drift marker. " +
-          "It must mention either '0.71' or '2.6.5' so contributors can " +
-          "identify the known-broken jiti versions. See change: " +
-          "fix-electron-windows-installer-and-server-bootstrap (Defect 2).",
+        "shouldUrlWrapEntry() docstring is missing the Windows-breakage marker. " +
+          "It must mention either the `file:/<cwd>/file:/…` error signature " +
+          "or the word 'misnormalise'. See change: fix-windows-standalone-spawn.",
       );
     }
 
-    // Remediation guidance markers (at least one)
+    // Remediation guidance markers (at least one).
     const hasRemediationGuidance =
       /re-verify/i.test(source) ||
       /per-version branch/i.test(source) ||
-      /per-jiti-version/i.test(source) ||
-      /switch.*to tsx/i.test(source);
+      /per-jiti-version/i.test(source);
     if (!hasRemediationGuidance) {
       throw new Error(
         "shouldUrlWrapEntry() docstring is missing remediation guidance. " +
-          "It must mention at least one of: re-verify, per-version branch, " +
-          "or switch to tsx. See change: " +
-          "fix-electron-windows-installer-and-server-bootstrap (Defect 2).",
+          "It must mention at least one of: re-verify, per-version branch. " +
+          "See change: fix-windows-standalone-spawn.",
       );
     }
   });

package/packages/shared/src/__tests__/node-spawn.test.ts

@@ -62,14 +62,14 @@ describe("isTsxLoader", () => {
 });
 
 describe("spawnNodeScript", () => {
-  it("URL-wraps both loader and entry when loader is NOT tsx (jiti/default)", () => {
+  it("URL-wraps loader but passes RAW entry when loader is jiti (any platform)", () => {
     const spawnSpy = vi
       .spyOn(execModule, "spawn")
       .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
 
     spawnNodeScript({
       nodeBin: "C:\\Program Files\\nodejs\\node.exe",
-      loader: "B:\\jiti\\register.mjs",
+      loader: "B:\\jiti\\lib\\jiti-register.mjs",
       entry: "B:\\Dev\\cli.ts",
       args: ["start", "--dev"],
     });
@@ -77,12 +77,11 @@ describe("spawnNodeScript", () => {
     expect(spawnSpy).toHaveBeenCalledTimes(1);
     const [bin, argv] = spawnSpy.mock.calls[0]!;
     expect(bin).toBe("C:\\Program Files\\nodejs\\node.exe");
-    // On Linux host: entry stays raw even with a Windows-styled path
-    // (shouldUrlWrapEntry consults process.platform, which is Linux).
-    // The Windows-wrapped branch is exercised separately via shouldUrlWrapEntry.
+    // jiti loader → entry RAW everywhere (jiti misnormalises file:///
+    // URL entries on Windows; POSIX never needed the wrap).
     expect(argv).toEqual([
       "--import",
-      "file:///B:/jiti/register.mjs",
+      "file:///B:/jiti/lib/jiti-register.mjs",
       "B:\\Dev\\cli.ts",
       "start",
       "--dev",
@@ -197,16 +196,25 @@ describe("buildNodeImportArgvParts", () => {
     expect(parts.slice(3)).toEqual(["start", "--port", "8000"]);
   });
 
-  it("Windows + jiti: entry URL-wrapped", async () => {
+  it("Windows + jiti: entry passed RAW (jiti misnormalises file:/// URLs on Windows)", async () => {
+    // See change: fix-windows-standalone-spawn. Live repro on
+    // Win11 + Node 22.18.0 + jiti 2.7.0 showed the URL-wrapped entry
+    // re-resolved against cwd; Node's drive-letter heuristic accepts
+    // raw `C:\…` argv entries so the wrap is no longer needed.
     const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
     const parts = buildNodeImportArgvParts({
-      loader: "B:\\Dev\\jiti\\lib\\jiti-register.mjs",
-      entry: "B:\\srv\\cli.ts",
+      loader: "C:\\Users\\u\\.pi-dashboard\\node_modules\\jiti\\lib\\jiti-register.mjs",
+      entry: "C:\\Users\\u\\.pi-dashboard\\node_modules\\@earendil-works\\pi-agent-dashboard\\packages\\server\\src\\cli.ts",
       args: ["start"],
       platform: "win32",
     });
-    expect(parts[1]).toBe("file:///B:/Dev/jiti/lib/jiti-register.mjs");
-    expect(parts[2]).toBe("file:///B:/srv/cli.ts");
+    expect(parts[1]).toBe(
+      "file:///C:/Users/u/.pi-dashboard/node_modules/jiti/lib/jiti-register.mjs",
+    );
+    // Entry is RAW — NOT URL-wrapped — because the loader is jiti.
+    expect(parts[2]).toBe(
+      "C:\\Users\\u\\.pi-dashboard\\node_modules\\@earendil-works\\pi-agent-dashboard\\packages\\server\\src\\cli.ts",
+    );
   });
 
   it("tsx loader: entry RAW on any platform", async () => {
@@ -245,9 +253,17 @@ describe("shouldUrlWrapEntry", () => {
     expect(shouldUrlWrapEntry(jiti, "darwin")).toBe(false);
   });
 
-  it("returns true for non-tsx loader on Windows (drive letters need file://)", () => {
+  it("returns false for jiti loader on Windows (jiti misnormalises file:/// entries)", () => {
+    // See change: fix-windows-standalone-spawn.
     const jiti = "file:///C:/node_modules/@mariozechner/jiti/lib/jiti-register.mjs";
-    expect(shouldUrlWrapEntry(jiti, "win32")).toBe(true);
+    expect(shouldUrlWrapEntry(jiti, "win32")).toBe(false);
+  });
+
+  it("returns true for an unknown loader on Windows (drive-letter URL-scheme protection)", () => {
+    // A hypothetical non-tsx, non-jiti loader (or a future Node default
+    // resolver) still needs the wrap for edge-case drives like `B:`/`A:`.
+    const unknown = "file:///C:/node_modules/some-other-loader/index.mjs";
+    expect(shouldUrlWrapEntry(unknown, "win32")).toBe(true);
   });
 
   it("returns false when no loader is provided, regardless of platform", () => {

package/packages/shared/src/__tests__/pi-package-resolver.test.ts

@@ -0,0 +1,300 @@
+/**
+ * pi-package-resolver tests — real-fs tmp dirs, no mocking.
+ *
+ * Each test builds a virtual `~/.pi/agent/` (via `agentDir` injection)
+ * and optionally a virtual `<cwd>/.pi/` for project-scope cases. The
+ * resolver's three deps (`agentDir`, `cwd`, `npmRoot`) are all injected
+ * so tests are hermetic and never read the developer's real settings.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { resolvePiPackage, resolvePiPackageEntry } from "../pi-package-resolver.js";
+
+let root: string;
+let agentDir: string;
+let cwd: string;
+let npmRoot: string;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-resolver-test-"));
+  agentDir = path.join(root, ".pi", "agent");
+  cwd = path.join(root, "project");
+  npmRoot = path.join(root, "global-npm", "node_modules");
+  fs.mkdirSync(agentDir, { recursive: true });
+  fs.mkdirSync(cwd, { recursive: true });
+  fs.mkdirSync(npmRoot, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+// ── helpers ─────────────────────────────────────────────────────────
+
+function writeSettings(scope: "user" | "project", body: Record<string, unknown>): void {
+  const settingsPath =
+    scope === "user"
+      ? path.join(agentDir, "settings.json")
+      : path.join(cwd, ".pi", "settings.json");
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(body, null, 2));
+}
+
+function writePackage(pkgDir: string, pkgJson: Record<string, unknown>, files: Record<string, string> = {}): void {
+  fs.mkdirSync(pkgDir, { recursive: true });
+  fs.writeFileSync(path.join(pkgDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(pkgDir, rel);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+  }
+}
+
+// ── 2.2: npm scope (global) ─────────────────────────────────────────
+
+describe("npm: install resolution", () => {
+  it("resolves an npm: peer in global scope via npmRoot", () => {
+    writeSettings("user", { packages: ["npm:@pi/anthropic-messages"] });
+    const pkgDir = path.join(npmRoot, "@pi", "anthropic-messages");
+    writePackage(pkgDir, {
+      name: "@pi/anthropic-messages",
+      exports: { ".": "./extensions/index.js" },
+    }, {
+      "extensions/index.js": "export default function() {}",
+    });
+
+    const result = resolvePiPackage("@pi/anthropic-messages", { agentDir, npmRoot });
+    expect(result).not.toBeNull();
+    expect(result!.packageDir).toBe(pkgDir);
+    expect(result!.entryPath).toBe(path.join(pkgDir, "extensions", "index.js"));
+    expect(result!.scope).toBe("user");
+    expect(result!.source).toBe("npm:@pi/anthropic-messages");
+    expect(result!.packageJsonName).toBe("@pi/anthropic-messages");
+  });
+
+  it("ignores @version suffix in npm: spec when resolving", () => {
+    // Use a single-segment version to avoid email-obfuscation in source files.
+    writeSettings("user", { packages: ["npm:foo@latest"] });
+    const pkgDir = path.join(npmRoot, "foo");
+    writePackage(pkgDir, { name: "foo", main: "index.js" }, { "index.js": "" });
+
+    const result = resolvePiPackage("foo", { agentDir, npmRoot });
+    expect(result?.packageDir).toBe(pkgDir);
+  });
+});
+
+// ── 2.3: git scope ──────────────────────────────────────────────────
+
+describe("git: install resolution", () => {
+  it("resolves https github URL to ~/.pi/agent/git/<host>/<path>", () => {
+    writeSettings("user", {
+      packages: ["https://github.com/BlackBeltTechnology/pi-anthropic-messages.git"],
+    });
+    const pkgDir = path.join(agentDir, "git", "github.com", "BlackBeltTechnology", "pi-anthropic-messages");
+    writePackage(pkgDir, {
+      name: "@pi/anthropic-messages",
+      main: "./extensions/index.ts",
+    }, {
+      "extensions/index.ts": "export default function() {}",
+    });
+
+    const result = resolvePiPackage("@pi/anthropic-messages", { agentDir, npmRoot });
+    expect(result?.packageDir).toBe(pkgDir);
+    expect(result?.entryPath).toBe(path.join(pkgDir, "extensions", "index.ts"));
+    expect(result?.scope).toBe("user");
+  });
+
+  it("handles git+https:// and git@ shorthand forms", () => {
+    writeSettings("user", { packages: ["git@github.com:owner/repo.git"] });
+    const pkgDir = path.join(agentDir, "git", "github.com", "owner", "repo");
+    writePackage(pkgDir, { name: "thing", main: "x.js" }, { "x.js": "" });
+
+    expect(resolvePiPackage("thing", { agentDir, npmRoot })?.packageDir).toBe(pkgDir);
+  });
+});
+
+// ── 2.4: absolute local path ────────────────────────────────────────
+
+describe("absolute path resolution", () => {
+  it("resolves an absolute path entry to itself", () => {
+    const pkgDir = path.join(root, "elsewhere", "my-pkg");
+    writePackage(pkgDir, { name: "my-pkg", main: "entry.js" }, { "entry.js": "" });
+    writeSettings("user", { packages: [pkgDir] });
+
+    const result = resolvePiPackage("my-pkg", { agentDir, npmRoot });
+    expect(result?.packageDir).toBe(pkgDir);
+    expect(result?.entryPath).toBe(path.join(pkgDir, "entry.js"));
+  });
+});
+
+// ── 2.5: relative path in project-scope ─────────────────────────────
+
+describe("relative path resolution under project scope", () => {
+  it("resolves a relative entry against <cwd>/.pi/", () => {
+    const pkgDir = path.join(cwd, "..", "sibling");
+    writePackage(pkgDir, { name: "sibling-pkg", main: "ok.ts" }, { "ok.ts": "" });
+    writeSettings("project", { packages: ["../../sibling"] }); // relative to <cwd>/.pi/
+
+    const result = resolvePiPackage("sibling-pkg", { agentDir, cwd, npmRoot });
+    expect(result?.scope).toBe("project");
+    expect(path.resolve(result!.packageDir)).toBe(path.resolve(pkgDir));
+  });
+});
+
+// ── 2.6: scope precedence ───────────────────────────────────────────
+
+describe("scope precedence", () => {
+  it("project wins over user by default when both define the same name", () => {
+    const projPkg = path.join(root, "proj-impl");
+    const userPkg = path.join(root, "user-impl");
+    writePackage(projPkg, { name: "shared", main: "proj.js" }, { "proj.js": "" });
+    writePackage(userPkg, { name: "shared", main: "user.js" }, { "user.js": "" });
+    writeSettings("project", { packages: [projPkg] });
+    writeSettings("user", { packages: [userPkg] });
+
+    const result = resolvePiPackage("shared", { agentDir, cwd, npmRoot });
+    expect(result?.scope).toBe("project");
+    expect(result?.packageDir).toBe(projPkg);
+  });
+
+  it("scope:'user' skips project even when both have a match", () => {
+    const projPkg = path.join(root, "proj-impl");
+    const userPkg = path.join(root, "user-impl");
+    writePackage(projPkg, { name: "shared", main: "proj.js" }, { "proj.js": "" });
+    writePackage(userPkg, { name: "shared", main: "user.js" }, { "user.js": "" });
+    writeSettings("project", { packages: [projPkg] });
+    writeSettings("user", { packages: [userPkg] });
+
+    expect(resolvePiPackage("shared", { agentDir, cwd, npmRoot, scope: "user" })?.packageDir).toBe(userPkg);
+  });
+
+  it("scope:'project' returns null without cwd", () => {
+    expect(resolvePiPackage("anything", { agentDir, npmRoot, scope: "project" })).toBeNull();
+  });
+});
+
+// ── 2.7: entry-point priority chain ─────────────────────────────────
+
+describe("entry-point resolution priority", () => {
+  function setupPkg(pkgJson: Record<string, unknown>, files: Record<string, string>): string {
+    const pkgDir = path.join(root, "ep-test");
+    writePackage(pkgDir, { name: "ep-test", ...pkgJson }, files);
+    writeSettings("user", { packages: [pkgDir] });
+    return pkgDir;
+  }
+
+  it("exports['.'] wins over main and pi.extensions", () => {
+    const dir = setupPkg(
+      {
+        exports: { ".": "./from-exports.js" },
+        main: "./from-main.js",
+        pi: { extensions: ["./from-pi.js"] },
+      },
+      { "from-exports.js": "", "from-main.js": "", "from-pi.js": "" },
+    );
+    expect(resolvePiPackageEntry("ep-test", { agentDir, npmRoot })).toBe(path.join(dir, "from-exports.js"));
+  });
+
+  it("exports conditional import/default/node fields resolve to the first present string", () => {
+    const dir = setupPkg(
+      { exports: { ".": { default: "./d.js", import: "./i.js" } } },
+      { "d.js": "", "i.js": "" },
+    );
+    // import takes priority per design D4
+    expect(resolvePiPackageEntry("ep-test", { agentDir, npmRoot })).toBe(path.join(dir, "i.js"));
+  });
+
+  it("main wins when exports absent", () => {
+    const dir = setupPkg(
+      { main: "./from-main.js", pi: { extensions: ["./from-pi.js"] } },
+      { "from-main.js": "", "from-pi.js": "" },
+    );
+    expect(resolvePiPackageEntry("ep-test", { agentDir, npmRoot })).toBe(path.join(dir, "from-main.js"));
+  });
+
+  it("pi.extensions[0] wins when neither exports nor main", () => {
+    const dir = setupPkg(
+      { pi: { extensions: ["./from-pi.ts"] } },
+      { "from-pi.ts": "" },
+    );
+    expect(resolvePiPackageEntry("ep-test", { agentDir, npmRoot })).toBe(path.join(dir, "from-pi.ts"));
+  });
+
+  it("index.js fallback wins when no entry fields", () => {
+    const dir = setupPkg({}, { "index.js": "" });
+    expect(resolvePiPackageEntry("ep-test", { agentDir, npmRoot })).toBe(path.join(dir, "index.js"));
+  });
+
+  it("index.ts fallback wins when no index.js", () => {
+    const dir = setupPkg({}, { "index.ts": "" });
+    expect(resolvePiPackageEntry("ep-test", { agentDir, npmRoot })).toBe(path.join(dir, "index.ts"));
+  });
+
+  it("returns entryPath:null when package matched but no candidate exists", () => {
+    const dir = setupPkg({ main: "./missing.js" }, {});
+    const result = resolvePiPackage("ep-test", { agentDir, npmRoot });
+    expect(result?.packageDir).toBe(dir);
+    expect(result?.entryPath).toBeNull();
+  });
+});
+
+// ── 2.8: not in any settings → null ─────────────────────────────────
+
+describe("misses return null", () => {
+  it("returns null when no settings entry matches the spec", () => {
+    writeSettings("user", { packages: [] });
+    expect(resolvePiPackage("@some/missing", { agentDir, npmRoot })).toBeNull();
+    expect(resolvePiPackageEntry("@some/missing", { agentDir, npmRoot })).toBeNull();
+  });
+
+  it("returns null when a candidate package's package.json#name differs", () => {
+    const pkgDir = path.join(root, "wrong-name");
+    writePackage(pkgDir, { name: "actually-foo", main: "x.js" }, { "x.js": "" });
+    writeSettings("user", { packages: [pkgDir] });
+
+    expect(resolvePiPackage("requested-bar", { agentDir, npmRoot })).toBeNull();
+  });
+});
+
+// ── 2.9: corrupt package.json — keep walking ────────────────────────
+
+describe("graceful degradation", () => {
+  it("skips a package with malformed package.json and continues", () => {
+    const badDir = path.join(root, "bad-pkg");
+    fs.mkdirSync(badDir, { recursive: true });
+    fs.writeFileSync(path.join(badDir, "package.json"), "{ this is not json");
+
+    const goodDir = path.join(root, "good-pkg");
+    writePackage(goodDir, { name: "target", main: "ok.js" }, { "ok.js": "" });
+
+    writeSettings("user", { packages: [badDir, goodDir] });
+
+    const result = resolvePiPackage("target", { agentDir, npmRoot });
+    expect(result?.packageDir).toBe(goodDir);
+  });
+});
+
+// ── 2.10: missing settings.json → null ──────────────────────────────
+
+describe("missing settings.json", () => {
+  it("returns null without throwing when ~/.pi/agent/settings.json is absent", () => {
+    // beforeEach creates the agentDir but no settings.json inside it.
+    expect(resolvePiPackage("anything", { agentDir, npmRoot })).toBeNull();
+  });
+
+  it("returns null when the global settings.json contains invalid JSON", () => {
+    fs.writeFileSync(path.join(agentDir, "settings.json"), "not json at all");
+    expect(resolvePiPackage("anything", { agentDir, npmRoot })).toBeNull();
+  });
+
+  it("handles {source: '...'} object-form entries", () => {
+    const pkgDir = path.join(root, "obj-form");
+    writePackage(pkgDir, { name: "obj-pkg", main: "e.js" }, { "e.js": "" });
+    writeSettings("user", { packages: [{ source: pkgDir, extensions: [] }] });
+
+    expect(resolvePiPackage("obj-pkg", { agentDir, npmRoot })?.packageDir).toBe(pkgDir);
+  });
+});

package/packages/shared/src/__tests__/plugin-activation-contracts.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Repo-lint contracts for change: add-plugin-activation-ui.
+ *
+ *  - SettingsPanel STILL calls <SettingsSectionSlot tab="..."> for every
+ *    legacy tab value, preserving backward compatibility for plugins that
+ *    target a specific tab via `claim.tab`.
+ *  - browser-protocol introduces NO new message types in this change
+ *    (toggles ride on existing plugin_config_update; requirement installs
+ *    ride on existing package_progress / package_operation_complete).
+ *  - /api/health payload always carries a `startedAt: ISO` field.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+
+const REPO_ROOT = path.resolve(__dirname, "../../../..");
+
+describe("add-plugin-activation-ui repo-lint", () => {
+  it("SettingsPanel does NOT render plugin-contributed settings in legacy tabs", () => {
+    // Plugin-contributed `settings-section` claims render ONLY under the
+    // owning plugin's row in Settings ▸ Plugins. The legacy
+    // <SettingsSectionSlot tab="..." /> consumers have been removed; the
+    // `claim.tab` manifest field is now an inert hint.
+    // See change: add-plugin-activation-ui (settings-consolidation).
+    const panel = fs.readFileSync(
+      path.join(REPO_ROOT, "packages/client/src/components/SettingsPanel.tsx"),
+      "utf-8",
+    );
+    expect(panel.includes("<SettingsSectionSlot")).toBe(false);
+    expect(panel.includes("SettingsSectionSlot")).toBe(false);
+  });
+
+  it("browser-protocol introduces no new message types in this change", () => {
+    // This change adds zero new variants to ServerToBrowserMessage. Toggles
+    // reuse `plugin_config_update`; requirement installs reuse the existing
+    // package_progress / package_operation_complete pair.
+    const proto = fs.readFileSync(
+      path.join(REPO_ROOT, "packages/shared/src/browser-protocol.ts"),
+      "utf-8",
+    );
+    // Sentinel: the existing fields are intact.
+    expect(proto.includes('"plugin_config_update"')).toBe(true);
+    expect(proto.includes('"package_progress"')).toBe(true);
+    expect(proto.includes('"package_operation_complete"')).toBe(true);
+    // Forbidden: anything that smells like a new plugin-specific message
+    // type added by THIS change.
+    const forbidden = [
+      '"plugin_install_progress"',
+      '"plugin_install_complete"',
+      '"plugin_uninstall_progress"',
+      '"plugin_uninstall_complete"',
+      '"plugin_toggle_complete"',
+    ];
+    for (const f of forbidden) {
+      expect(
+        proto.includes(f),
+        `browser-protocol.ts must NOT define ${f}; plugin operations ride ` +
+          "on existing package_progress / package_operation_complete / " +
+          "plugin_config_update.",
+      ).toBe(false);
+    }
+  });
+
+  it("system-routes /api/health payload includes startedAt (ISO 8601 timestamp)", () => {
+    const sys = fs.readFileSync(
+      path.join(REPO_ROOT, "packages/server/src/routes/system-routes.ts"),
+      "utf-8",
+    );
+    expect(sys.includes("startedAt:")).toBe(true);
+    // ISO format produced by Date.prototype.toISOString().
+    expect(/serverStartTime.*toISOString\(\)|new Date\(serverStartTime\)\.toISOString\(\)/.test(sys))
+      .toBe(true);
+  });
+});