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

package/packages/shared/src/__tests__/recommended-extensions.test.ts

@@ -14,10 +14,10 @@ describe("RECOMMENDED_EXTENSIONS manifest", () => {
 			[
 				"pi-anthropic-messages",
 				"pi-agent-browser",
+				"pi-dashboard-subagents",
 				"pi-flows",
 				"pi-memory-honcho",
 				"pi-web-access",
-				"tintinweb-pi-subagents",
 			].sort(),
 		);
 	});
@@ -34,9 +34,21 @@ describe("RECOMMENDED_EXTENSIONS manifest", () => {
 			expect(["required", "strongly-suggested", "optional"]).toContain(entry.status);
 			expect(Array.isArray(entry.unlocks)).toBe(true);
 			expect(entry.unlocks.length).toBeGreaterThan(0);
+			// dashboardPlugin is optional; when present, must be a non-empty string.
+			// See change: add-plugin-activation-ui.
+			if (entry.dashboardPlugin !== undefined) {
+				expect(typeof entry.dashboardPlugin).toBe("string");
+				expect(entry.dashboardPlugin.length).toBeGreaterThan(0);
+			}
 		}
 	});
 
+	it("pi-memory-honcho declares its companion dashboard plugin id", () => {
+		// See change: add-plugin-activation-ui (Layer 1.5).
+		const entry = getRecommendedExtension("pi-memory-honcho");
+		expect(entry?.dashboardPlugin).toBe("honcho");
+	});
+
 	it("pi-anthropic-messages is marked required and uses HTTPS git URL", () => {
 		const entry = getRecommendedExtension("pi-anthropic-messages");
 		expect(entry).toBeDefined();
@@ -53,11 +65,16 @@ describe("RECOMMENDED_EXTENSIONS manifest", () => {
 		expect(entry?.toolsRegistered).toContain("flow_write");
 	});
 
-	it("tintinweb-pi-subagents registers Agent under its canonical capitalization", () => {
-		const entry = getRecommendedExtension("tintinweb-pi-subagents");
+	it("pi-dashboard-subagents registers Agent and pairs with the subagents plugin", () => {
+		// See change: add-subagent-inspector.
+		const entry = getRecommendedExtension("pi-dashboard-subagents");
 		expect(entry).toBeDefined();
-		expect(entry?.source).toBe("npm:@tintinweb/pi-subagents");
-		expect(entry?.toolsRegistered).toContain("Agent");
+		expect(entry?.source).toBe(
+			"https://github.com/BlackBeltTechnology/pi-dashboard-subagents.git",
+		);
+		expect(entry?.toolsRegistered).toEqual(["Agent"]);
+		expect(entry?.dashboardPlugin).toBe("subagents");
+		expect(entry?.autowired).toBe(true);
 	});
 
 	it("npm-sourced entries use the npm: prefix", () => {
@@ -67,7 +84,6 @@ describe("RECOMMENDED_EXTENSIONS manifest", () => {
 				"pi-agent-browser",
 				"pi-memory-honcho",
 				"pi-web-access",
-				"tintinweb-pi-subagents",
 			].sort(),
 		);
 	});
@@ -80,7 +96,7 @@ describe("RECOMMENDED_EXTENSIONS manifest", () => {
 			expect(entry.source).toMatch(/^https:\/\/github\.com\/[^/]+\/[^/]+\.git$/);
 		}
 		expect(gitEntries.map((e) => e.id).sort()).toEqual(
-			["pi-anthropic-messages", "pi-flows"].sort(),
+			["pi-anthropic-messages", "pi-dashboard-subagents", "pi-flows"].sort(),
 		);
 	});
 });
@@ -105,14 +121,14 @@ describe("getRecommendedByStatus", () => {
 	it("filters by strongly-suggested", () => {
 		const suggested = getRecommendedByStatus("strongly-suggested");
 		expect(suggested.map((e) => e.id).sort()).toEqual(
-			["pi-flows", "pi-web-access", "tintinweb-pi-subagents"].sort(),
+			["pi-flows", "pi-web-access"].sort(),
 		);
 	});
 
 	it("filters by optional", () => {
 		const optional = getRecommendedByStatus("optional");
 		expect(optional.map((e) => e.id).sort()).toEqual(
-			["pi-agent-browser", "pi-memory-honcho"].sort(),
+			["pi-agent-browser", "pi-dashboard-subagents", "pi-memory-honcho"].sort(),
 		);
 	});
 });
@@ -139,8 +155,10 @@ describe("BUNDLED_EXTENSION_IDS manifest", () => {
 		// blocking the bundle-recommended-extensions.mjs license check.
 		// Re-add when https://github.com/BlackBeltTechnology/pi-flows has
 		// a license declared.
+		// pi-dashboard-subagents added in add-subagent-inspector §13.6
+		// (git source + MIT license, both gates pass).
 		expect([...BUNDLED_EXTENSION_IDS].sort()).toEqual(
-			["pi-anthropic-messages"].sort(),
+			["pi-anthropic-messages", "pi-dashboard-subagents"].sort(),
 		);
 	});
 

package/packages/shared/src/__tests__/resolver-parity-with-scanner.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Cross-helper parity: `packages/shared/src/pi-package-resolver.ts`
+ * duplicates source-kind parsing + install-path computation from
+ * `packages/server/src/pi-resource-scanner.ts` (the older server-only
+ * helper). If a future maintainer updates one without the other,
+ * package resolution diverges silently between the dashboard plugin
+ * bridges (shared) and the server-side resources scanner.
+ *
+ * This test is a structural pin: it asserts the scanner source still
+ * contains the same source-kind prefixes the shared resolver handles
+ * AND the same install-path layout strings (`.pi/git`, `.pi/agent/git`,
+ * `node_modules`). The cross-package file is read via fs only — no
+ * import statement so the shared package's tsconfig rootDir is
+ * respected.
+ *
+ * If this fails, sync the two helpers by hand (the resolver here in
+ * shared, the scanner in server). A follow-up cleanup that has the
+ * scanner consume the shared helper would retire this test.
+ *
+ * See change: add-shared-pi-package-resolver (Decision D3).
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const scannerPath = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "server",
+  "src",
+  "pi-resource-scanner.ts",
+);
+const resolverPath = path.resolve(__dirname, "..", "pi-package-resolver.ts");
+
+describe("pi-package-resolver / pi-resource-scanner parity (structural)", () => {
+  it("scanner source recognizes all source-kind prefixes the resolver handles", () => {
+    const scannerSrc = fs.readFileSync(scannerPath, "utf-8");
+    // The shared resolver parses these prefixes; the scanner must too.
+    for (const prefix of ['"npm:"', '"git:"', '"https://"', '"http://"', '"ssh://"']) {
+      expect(scannerSrc.includes(`.startsWith(${prefix})`)).toBe(true);
+    }
+  });
+
+  it("both helpers reference identical install-path layout markers", () => {
+    const scannerSrc = fs.readFileSync(scannerPath, "utf-8");
+    const resolverSrc = fs.readFileSync(resolverPath, "utf-8");
+    // Both helpers must layer git installs under a "git" subdir of either
+    // the agentDir (user scope) or `<cwd>/.pi/` (project scope). If one
+    // ever switches to e.g. `"repos"` while the other stays on `"git"`,
+    // resolutions diverge silently. Marker assertion accepts both spellings.
+    for (const [label, src] of [["scanner", scannerSrc], ["resolver", resolverSrc]] as const) {
+      const hasGitMarker =
+        src.includes('"agent", "git"') ||
+        src.includes('".pi", "agent", "git"') ||
+        src.includes('"git"');
+      expect(hasGitMarker, `${label} must reference a "git" subdir marker`).toBe(true);
+    }
+    // project-scope <cwd>/.pi/<arm> marker is identical in both.
+    for (const [label, src] of [["scanner", scannerSrc], ["resolver", resolverSrc]] as const) {
+      expect(src.includes('".pi"'), `${label} must reference the ".pi" config dir`).toBe(true);
+    }
+  });
+
+  it("resolver and scanner both consume npm.rootGlobalOr for npm: arm", () => {
+    const scannerSrc = fs.readFileSync(scannerPath, "utf-8");
+    const resolverSrc = fs.readFileSync(resolverPath, "utf-8");
+    // Both must obtain the npm global root the same way; if one stops
+    // using this helper the other will go stale.
+    expect(scannerSrc.includes("rootGlobalOr")).toBe(true);
+    expect(resolverSrc.includes("rootGlobalOr")).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/server-identity.test.ts

@@ -70,4 +70,131 @@ describe("isDashboardRunning", () => {
       expect.any(Object),
     );
   });
+
+  it("returns version from health response when present", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ ok: true, pid: 12345, version: "1.2.3" }),
+    });
+    const result = await isDashboardRunning(8000);
+    expect(result).toEqual({ running: true, pid: 12345, version: "1.2.3" });
+  });
+});
+
+describe("isDashboardRunning retry semantics (cherry-pick 2)", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("single-shot is the default (retries=0, 1 attempt)", async () => {
+    const sleep = vi.fn().mockResolvedValue(undefined);
+    globalThis.fetch = vi.fn().mockRejectedValue(
+      Object.assign(new Error("timeout"), { name: "AbortError" }),
+    );
+    const result = await isDashboardRunning(8000, "localhost", { _sleep: sleep });
+    expect(result).toEqual({ running: false });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+
+  it("retries=2 with two transient failures then success returns running:true", async () => {
+    const sleep = vi.fn().mockResolvedValue(undefined);
+    const abort = Object.assign(new Error("timeout"), { name: "AbortError" });
+    let call = 0;
+    globalThis.fetch = vi.fn().mockImplementation(() => {
+      call++;
+      if (call < 3) return Promise.reject(abort);
+      return Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve({ ok: true, pid: 999 }),
+      } as Response);
+    });
+
+    const result = await isDashboardRunning(8000, "localhost", {
+      retries: 2,
+      retryDelayMs: 100,
+      _sleep: sleep,
+    });
+    expect(result).toEqual({ running: true, pid: 999 });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenNthCalledWith(1, 100);
+    expect(sleep).toHaveBeenNthCalledWith(2, 100);
+  });
+
+  it("portConflict:true short-circuits retries", async () => {
+    const sleep = vi.fn().mockResolvedValue(undefined);
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ status: "ok", service: "nginx" }),
+    } as Response);
+
+    const result = await isDashboardRunning(8000, "localhost", {
+      retries: 5,
+      _sleep: sleep,
+    });
+    expect(result).toEqual({ running: false, portConflict: true });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+
+  it("ECONNREFUSED with default retries=0 returns running:false without retry", async () => {
+    const sleep = vi.fn().mockResolvedValue(undefined);
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+
+    const result = await isDashboardRunning(8000, "localhost", { _sleep: sleep });
+    expect(result).toEqual({ running: false });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+
+  it("exhausted retries return the last non-success result", async () => {
+    const sleep = vi.fn().mockResolvedValue(undefined);
+    globalThis.fetch = vi.fn().mockRejectedValue(
+      Object.assign(new Error("timeout"), { name: "AbortError" }),
+    );
+    const result = await isDashboardRunning(8000, "localhost", {
+      retries: 3,
+      _sleep: sleep,
+    });
+    expect(result).toEqual({ running: false });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(4); // 1 + 3 retries
+    expect(sleep).toHaveBeenCalledTimes(3);
+  });
+
+  it("custom timeoutMs is passed to AbortController", async () => {
+    // Indirect assertion: with timeoutMs=10 and a fetch that takes 50ms,
+    // the abort fires and we get running:false. With timeoutMs=200, the
+    // same fetch succeeds.
+    const makeSlowFetch = (delayMs: number) =>
+      vi.fn().mockImplementation(
+        (_url: string, init: RequestInit) =>
+          new Promise((resolve, reject) => {
+            const timer = setTimeout(
+              () =>
+                resolve({
+                  ok: true,
+                  json: () => Promise.resolve({ ok: true, pid: 1 }),
+                } as Response),
+              delayMs,
+            );
+            init.signal?.addEventListener("abort", () => {
+              clearTimeout(timer);
+              const err = new Error("aborted");
+              err.name = "AbortError";
+              reject(err);
+            });
+          }),
+      );
+
+    globalThis.fetch = makeSlowFetch(50);
+    const tight = await isDashboardRunning(8000, "localhost", { timeoutMs: 10 });
+    expect(tight).toEqual({ running: false });
+
+    globalThis.fetch = makeSlowFetch(10);
+    const loose = await isDashboardRunning(8000, "localhost", { timeoutMs: 200 });
+    expect(loose).toEqual({ running: true, pid: 1 });
+  });
 });

package/packages/shared/src/__tests__/server-launcher.test.ts

@@ -202,6 +202,41 @@ describe("launchDashboardServer — env merge", () => {
   });
 });
 
+describe("launchDashboardServer — onChildExit (cherry-pick 6a)", () => {
+  it("invokes onChildExit when child emits exit after readiness", async () => {
+    const child = makeFakeChild();
+    const onChildExit = vi.fn();
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawnSpy(() => child),
+      onChildExit,
+    }));
+    // Simulate post-readiness crash
+    (child as unknown as EventEmitter).emit("exit", 1, null);
+    expect(onChildExit).toHaveBeenCalledOnce();
+    expect(onChildExit).toHaveBeenCalledWith(1, null);
+  });
+
+  it("fires only once even if exit emitted twice", async () => {
+    const child = makeFakeChild();
+    const onChildExit = vi.fn();
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawnSpy(() => child),
+      onChildExit,
+    }));
+    (child as unknown as EventEmitter).emit("exit", 0, null);
+    (child as unknown as EventEmitter).emit("exit", 0, null);
+    expect(onChildExit).toHaveBeenCalledOnce(); // child.once not child.on
+  });
+
+  it("does NOT attach any listener when onChildExit omitted", async () => {
+    const child = makeFakeChild();
+    const listenersBefore = (child as unknown as EventEmitter).listenerCount("exit");
+    await launchDashboardServer(baseOpts({ _spawnNodeScript: spawnSpy(() => child) }));
+    const listenersAfter = (child as unknown as EventEmitter).listenerCount("exit");
+    expect(listenersAfter).toBe(listenersBefore);
+  });
+});
+
 describe("launchDashboardServer — entry URL-wrapping", () => {
   // The launcher delegates to spawnNodeScript, which uses
   // `shouldUrlWrapEntry(loader, platform)`. We verify the launcher

package/packages/shared/src/__tests__/source-matching.test.ts

@@ -14,16 +14,16 @@ describe("parseSourceKey", () => {
 	});
 
 	it("parses scoped npm name without version", () => {
-		expect(parseSourceKey("npm:@tintinweb/pi-subagents")).toEqual({
+		expect(parseSourceKey("npm:@scope/example-pkg")).toEqual({
 			kind: "npm",
-			name: "@tintinweb/pi-subagents",
+			name: "@scope/example-pkg",
 		});
 	});
 
 	it("parses scoped npm name with version", () => {
-		expect(parseSourceKey("npm:@tintinweb/pi-subagents@0.5.2")).toEqual({
+		expect(parseSourceKey("npm:@scope/example-pkg@0.5.2")).toEqual({
 			kind: "npm",
-			name: "@tintinweb/pi-subagents",
+			name: "@scope/example-pkg",
 		});
 	});
 
@@ -67,7 +67,7 @@ describe("sourcesMatch", () => {
 
 	it("matches scoped npm names", () => {
 		expect(
-			sourcesMatch("npm:@tintinweb/pi-subagents@0.5.2", "npm:@tintinweb/pi-subagents"),
+			sourcesMatch("npm:@scope/example-pkg@0.5.2", "npm:@scope/example-pkg"),
 		).toBe(true);
 	});
 

package/packages/shared/src/__tests__/sync-versions-spec.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Unit tests for `scripts/sync-versions-spec.js::isRewritableSemverSpec`.
+ *
+ * Lives in `packages/shared/__tests__/` because the repo's vitest projects all
+ * scope to `packages/`; the helper itself stays in `scripts/` (pure JS, no
+ * runtime deps) so the release script can `import` it without crossing into
+ * a workspace package boundary.
+ *
+ * The classifier decides which dependency specifiers are eligible for the
+ * release bump's `^<version>` rewrite. False values are deliberate human
+ * overrides and MUST be preserved (the bug this guards: a future hotfix
+ * pin like `"*"` being silently rewritten on the next release).
+ */
+import { describe, it, expect } from "vitest";
+// @ts-expect-error — pure JS helper one level above the package; no .d.ts
+import { isRewritableSemverSpec } from "../../../../scripts/sync-versions-spec.js";
+
+describe("isRewritableSemverSpec", () => {
+  describe("rewritable forms (returns true)", () => {
+    it.each([
+      ["plain", "0.5.0"],
+      ["caret", "^0.5.0"],
+      ["tilde", "~0.5.0"],
+      ["caret + prerelease", "^0.5.0-alpha.1"],
+      ["plain + prerelease", "0.5.0-rc.0"],
+      ["caret + build", "^0.5.0+sha.abc"],
+      ["caret + prerelease + build", "^0.5.0-alpha.1+sha.abc"],
+      ["multi-digit", "10.20.30"],
+    ])("returns true for %s (%s)", (_label, spec) => {
+      expect(isRewritableSemverSpec(spec)).toBe(true);
+    });
+  });
+
+  describe("preserved forms (returns false)", () => {
+    it.each([
+      ["wildcard", "*"],
+      ["latest tag", "latest"],
+      ["dist-tag", "next"],
+      ["workspace protocol", "workspace:*"],
+      ["workspace caret", "workspace:^0.5.0"],
+      ["github URL", "github:owner/repo#sha"],
+      ["github tarball URL", "https://github.com/o/r/tarball/main"],
+      ["git+ssh URL", "git+ssh://git@github.com/o/r.git"],
+      ["file path", "file:../foo"],
+      ["plain http tarball", "http://example.com/x.tgz"],
+      ["range gte", ">=1.0.0"],
+      ["range or-union", "1.0.0 || 2.0.0"],
+      ["range hyphen", "1.0.0 - 2.0.0"],
+      ["range x", "1.x"],
+      ["range x-dotted", "1.x.x"],
+      ["empty", ""],
+      ["whitespace only", "   "],
+      ["partial caret", "^"],
+    ])("returns false for %s (%s)", (_label, spec) => {
+      expect(isRewritableSemverSpec(spec)).toBe(false);
+    });
+  });
+
+  describe("non-string inputs", () => {
+    it("returns false for undefined", () => {
+      expect(isRewritableSemverSpec(undefined)).toBe(false);
+    });
+
+    it("returns false for null", () => {
+      expect(isRewritableSemverSpec(null)).toBe(false);
+    });
+
+    it("returns false for number", () => {
+      expect(isRewritableSemverSpec(0.5)).toBe(false);
+    });
+
+    it("returns false for object", () => {
+      expect(isRewritableSemverSpec({ version: "1.0.0" })).toBe(false);
+    });
+  });
+});

package/packages/shared/src/__tests__/tool-registry-definitions.test.ts

@@ -40,11 +40,24 @@ function freshRegistry(opts: {
 }
 
 describe("pi binary definition", () => {
-  it("chain order: override → managed → where", () => {
-    const r = freshRegistry({ which: (n) => (n === "pi" ? "/usr/bin/pi" : null) });
+  it("chain order: override → bare-import ×2 → managed → where", () => {
+    // bare-import strategies probe both pi-coding-agent aliases
+    // (@earendil-works + @mariozechner) before falling through to
+    // managed-bin and PATH. They fail in this fixture because the
+    // injected `exists` returns false for all paths.
+    // See change: eliminate-electron-runtime-install F9.
+    const r = freshRegistry({
+      which: (n) => (n === "pi" ? "/usr/bin/pi" : null),
+      // No resolveModule injection — real resolver runs against the
+      // repo's node_modules. The bare-import strategy returns a
+      // path, but `exists: () => false` invalidates it, so the chain
+      // falls through to `where`.
+    });
     const res = r.resolve("pi");
     expect(res.tried.map((t) => t.strategy)).toEqual([
       "override",
+      "bare-import",
+      "bare-import",
       "managed",
       "where",
     ]);
@@ -53,6 +66,41 @@ describe("pi binary definition", () => {
     expect(res.source).toBe("system");
   });
 
+  it("bare-import wins over PATH when bundled cli.js exists (F9)", () => {
+    // Simulates the Electron immutable-bundle architecture: a
+    // bundled @earendil-works/pi-coding-agent ships inside the
+    // server's own node_modules. With no PATH, no managed dir,
+    // bare-import must resolve the bundled cli.js — otherwise the
+    // server falls into bootstrapInstall() and writes to
+    // ~/.pi-dashboard/ (the failure mode F9 documents).
+    const bundledPkgJson =
+      "/Volumes/PI Dashboard/PI-Dashboard.app/Contents/Resources/server/node_modules/@earendil-works/pi-coding-agent/package.json";
+    const bundledCli =
+      "/Volumes/PI Dashboard/PI-Dashboard.app/Contents/Resources/server/node_modules/@earendil-works/pi-coding-agent/dist/cli.js";
+    const r = new ToolRegistry({
+      overrides: new OverridesStore({
+        filePath: path.join(os.tmpdir(), `f9-test-${Math.random()}.json`),
+        warn: () => {},
+      }),
+      platform: "linux",
+    });
+    registerDefaultTools(r, {
+      exists: (p) => p === bundledCli, // only the bundled cli.js exists
+      which: () => null, // no PATH
+      npmRootGlobal: () => "", // no npm-global
+      resolveModule: (id, _from) =>
+        id === "@earendil-works/pi-coding-agent/package.json"
+          ? bundledPkgJson
+          : null,
+    });
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(bundledCli);
+    expect(res.tried.find((t) => t.strategy === "bare-import")?.result).toBe(
+      "ok",
+    );
+  });
+
   it("managed wins over system when MANAGED_BIN/pi exists", () => {
     const managed = path.join(os.homedir(), ".pi-dashboard", "node_modules", ".bin", "pi");
     const r = freshRegistry({

package/packages/shared/src/bridge-register.ts

@@ -43,6 +43,23 @@ export interface FindExtensionDeps {
   resolvePackage?: () => string | null;
 }
 
+/**
+ * Read `name` from `<dir>/package.json`. Returns null on any error
+ * (missing file, unreadable, invalid JSON, missing name field).
+ * Used for identity-based dedup in `registerBridgeExtension`.
+ */
+function readPackageName(dir: string): string | null {
+  try {
+    const pkgPath = path.join(dir, "package.json");
+    if (!fs.existsSync(pkgPath)) return null;
+    const raw = fs.readFileSync(pkgPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.name === "string" ? parsed.name : null;
+  } catch {
+    return null;
+  }
+}
+
 function defaultResolvePackage(): string | null {
   try {
     const req = createRequire(import.meta.url);
@@ -133,12 +150,28 @@ export function registerBridgeExtension(
   // Already registered?
   if (packages.includes(extensionPath)) return;
 
-  // Non-destructive cleanup: only remove broken dashboard paths
+  // Compute the identity (package.json#name) of the new entry. We use it
+  // to dedupe across install layouts (dev / .app / npm-global / legacy
+  // managed dir) that all register the same extension under different
+  // absolute paths.
+  const newIdentity = readPackageName(extensionPath);
+
+  // Non-destructive cleanup: drop stale dashboard paths AND drop any
+  // local entry with the same package.json#name as the new one
+  // (most-recently-asserted path wins). npm:-scheme entries pass through
+  // untouched.
   const cleaned = packages.filter((p) => {
     if (typeof p !== "string") return true;
     const isLocalPath = p.startsWith("/") || /^[a-zA-Z]:[/\\]/.test(p);
     if (!isLocalPath) return true;
-    // Only consider dashboard-related paths for cleanup
+
+    // Identity dedup: same package name as the incoming entry?
+    if (newIdentity) {
+      const existingIdentity = readPackageName(p);
+      if (existingIdentity && existingIdentity === newIdentity) return false;
+    }
+
+    // Only consider dashboard-related paths for path-based cleanup
     // Normalize: lowercase + collapse spaces/hyphens so "PI Dashboard" matches "pi-dashboard"
     const normalized = p.toLowerCase().replace(/[\s_-]/g, "");
     if (!normalized.includes("pidashboard") && !normalized.includes("piagentdashboard")) return true;