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

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

@@ -82,7 +82,7 @@ export interface EnrichedRecommendedExtension extends RecommendedExtension {
 export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 	{
 		id: "pi-anthropic-messages",
-		source: "git@github.com:BlackBeltTechnology/pi-anthropic-messages.git",
+		source: "https://github.com/BlackBeltTechnology/pi-anthropic-messages.git",
 		displayName: "pi-anthropic-messages",
 		fallbackDescription:
 			"Protocol bridge that makes pi's custom tools work with any " +
@@ -114,7 +114,7 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 	},
 	{
 		id: "pi-flows",
-		source: "git@github.com:BlackBeltTechnology/pi-flows.git",
+		source: "https://github.com/BlackBeltTechnology/pi-flows.git",
 		displayName: "pi-flows",
 		fallbackDescription:
 			"Flow engine, dashboard, and orchestration extensions for pi. " +
@@ -167,6 +167,22 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 	},
 ];
 
+/**
+ * Ids of recommended extensions that ship inside the Electron installer
+ * as a pre-bundled source tree. See
+ * `packages/electron/scripts/bundle-recommended-extensions.sh` and
+ * `installBundledExtensions()` in `dependency-installer.ts`. Every id
+ * MUST also appear in `RECOMMENDED_EXTENSIONS` and MUST have a git-based
+ * `source` (enforced by a test).
+ *
+ * Kept deliberately short — only first-party, source-only, native-dep-free
+ * extensions belong here.
+ */
+export const BUNDLED_EXTENSION_IDS: readonly string[] = [
+	"pi-anthropic-messages",
+	"pi-flows",
+];
+
 /** Retrieve a recommended entry by id, or `undefined`. */
 export function getRecommendedExtension(id: string): RecommendedExtension | undefined {
 	return RECOMMENDED_EXTENSIONS.find((e) => e.id === id);

package/packages/shared/src/resolve-jiti.ts

@@ -8,8 +8,9 @@
  */
 
 import { createRequire } from "node:module";
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const JITI_PACKAGES = [
   "@mariozechner/jiti",
@@ -17,8 +18,38 @@ const JITI_PACKAGES = [
 ];
 
 /**
- * Returns the absolute path to jiti's register hook (lib/jiti-register.mjs).
+ * Pure helper: given a jiti package.json path, return the file:// URL of
+ * its register hook. Exported for testing — no I/O.
+ *
+ * Returns a file:// URL (not a raw path) because Node >= 20 on Windows
+ * rejects raw absolute paths with a drive letter for --import (parses
+ * "C:" / "B:" as a URL scheme → ERR_UNSUPPORTED_ESM_URL_SCHEME). file://
+ * URLs are accepted on every OS.
+ * See change: fix-windows-server-parity.
+ */
+export function buildJitiRegisterUrl(pkgJsonPath: string): string {
+  // Detect Windows-style input (drive letter + backslash) regardless of
+  // host OS, so unit tests can exercise the Windows path contract on macOS/Linux.
+  // Production behaviour is unchanged because the host-OS `path`/`pathToFileURL`
+  // match the input style automatically.
+  const isWindowsStyle = /^[A-Za-z]:[\\/]/.test(pkgJsonPath);
+  if (isWindowsStyle) {
+    // Manually build file:///C:/path/lib/jiti-register.mjs — pathToFileURL on
+    // POSIX hosts URL-encodes backslashes rather than treating them as
+    // separators. Do the join with path.win32 and format the URL ourselves.
+    const registerPath = path.win32.join(path.win32.dirname(pkgJsonPath), "lib", "jiti-register.mjs");
+    return `file:///${registerPath.replace(/\\/g, "/")}`;
+  }
+  const registerPath = path.join(path.dirname(pkgJsonPath), "lib", "jiti-register.mjs");
+  return pathToFileURL(registerPath).href;
+}
+
+/**
+ * Returns jiti's register hook as a file:// URL suitable for `node --import`.
  * Uses process.argv[1] (pi's entry point) to anchor module resolution.
+ *
+ * The return value is ALWAYS a file:// URL (never a raw path). See
+ * buildJitiRegisterUrl for the URL contract rationale.
  */
 export function resolveJitiImport(): string {
   const anchor = process.argv[1];
@@ -30,7 +61,7 @@ export function resolveJitiImport(): string {
       for (const jiti of JITI_PACKAGES) {
         try {
           const pkgJson = req.resolve(`${jiti}/package.json`);
-          return path.join(path.dirname(pkgJson), "lib", "jiti-register.mjs");
+          return buildJitiRegisterUrl(pkgJson);
         } catch { /* next */ }
       }
     } catch { /* fall through */ }
@@ -41,3 +72,31 @@ export function resolveJitiImport(): string {
     "Is @mariozechner/pi-coding-agent or @oh-my-pi/pi-coding-agent installed?"
   );
 }
+
+/**
+ * Resolve jiti's register hook from an arbitrary anchor path (e.g. a
+ * pi-coding-agent package.json in a managed install, or a pi binary on
+ * the system PATH). Returns a file:// URL or null if jiti cannot be
+ * resolved from the anchor.
+ *
+ * This is the Electron/managed-install variant of `resolveJitiImport`
+ * — the difference is the caller supplies the anchor explicitly
+ * instead of using `process.argv[1]`. Consolidates what used to be a
+ * duplicate `resolveJitiFromAnchor` in
+ * `packages/electron/src/lib/server-lifecycle.ts`.
+ * See change: consolidate-platform-handlers.
+ */
+export function resolveJitiFromAnchor(anchorPath: string): string | null {
+  if (!existsSync(anchorPath)) return null;
+  try {
+    const req = createRequire(anchorPath);
+    for (const jiti of JITI_PACKAGES) {
+      try {
+        const pkgJson = req.resolve(`${jiti}/package.json`);
+        const registerPath = path.join(path.dirname(pkgJson), "lib", "jiti-register.mjs");
+        if (existsSync(registerPath)) return pathToFileURL(registerPath).href;
+      } catch { /* next */ }
+    }
+  } catch { /* ignore */ }
+  return null;
+}

package/packages/shared/src/rest-api.ts

@@ -80,6 +80,16 @@ export interface BrowseResult {
   entries: BrowseEntry[];
   parent: string | null;
   current: string;
+  /**
+   * The server's `process.platform` — lets the client use OS-correct path
+   * handling (separator, case-sensitivity, drive-letter rules) without
+   * having to sniff `navigator.userAgent`. Optional for backward
+   * compatibility; consumers fall back to inferring from the `current`
+   * path shape when absent.
+   *
+   * See change: platform-path-normalization.
+   */
+  platform?: NodeJS.Platform;
 }
 
 export type BrowseResponse = ApiResponse<BrowseResult>;
@@ -352,3 +362,19 @@ export interface NetworkInterface {
 export type ListRecommendedExtensionsResponse = ApiResponse<{
   recommended: EnrichedRecommendedExtension[];
 }>;
+
+// ── Tool registry ────────────────────
+
+import type { Resolution } from "./tool-registry/types.js";
+export type { Resolution, Source, TriedEntry } from "./tool-registry/types.js";
+
+export type ListToolsResponse = ApiResponse<{ tools: Resolution[] }>;
+export type GetToolResponse = ApiResponse<Resolution>;
+
+export interface RescanToolsRequest {
+  name?: string;
+}
+
+export interface SetToolOverrideRequest {
+  path: string;
+}

package/packages/shared/src/semaphore.ts

@@ -0,0 +1,83 @@
+/**
+ * Tiny FIFO semaphore for throttling concurrent async operations.
+ *
+ * Used by the server's openspec polling scheduler to cap how many
+ * `openspec` CLI spawns may be running at once. Rolled in-repo instead
+ * of pulling `p-limit` because we need `setMax()` for live reconfig
+ * (when the user edits `openspec.maxConcurrentSpawns` in settings).
+ *
+ * Contract:
+ *   - `run(fn)` runs `fn` through the gate. At most `max` tasks are
+ *     in-flight; excess tasks queue FIFO.
+ *   - `setMax(n)` resizes. Growing drains the queue up to the new cap
+ *     on the next microtask. Shrinking does not interrupt in-flight
+ *     tasks; it only affects newly queued ones.
+ *   - `size()` = active + queued.
+ *   - If the task throws/rejects, the slot is released and queued
+ *     tasks proceed.
+ */
+export interface Semaphore {
+  run<T>(fn: () => Promise<T>): Promise<T>;
+  setMax(n: number): void;
+  size(): number;
+}
+
+export function createSemaphore(max: number): Semaphore {
+  if (!Number.isFinite(max) || max < 1) {
+    throw new Error(`Semaphore max must be a positive integer, got ${max}`);
+  }
+  let limit = Math.floor(max);
+  let active = 0;
+  const queue: Array<() => void> = [];
+
+  function drain() {
+    while (active < limit && queue.length > 0) {
+      const next = queue.shift()!;
+      active++;
+      next();
+    }
+  }
+
+  function release() {
+    active--;
+    // Schedule drain on microtask so `run()` callers see a stable state first.
+    queueMicrotask(drain);
+  }
+
+  return {
+    run<T>(fn: () => Promise<T>): Promise<T> {
+      return new Promise<T>((resolve, reject) => {
+        const start = () => {
+          let settled = false;
+          try {
+            Promise.resolve()
+              .then(fn)
+              .then(
+                (value) => { if (!settled) { settled = true; release(); resolve(value); } },
+                (err) => { if (!settled) { settled = true; release(); reject(err); } },
+              );
+          } catch (err) {
+            if (!settled) { settled = true; release(); reject(err); }
+          }
+        };
+        if (active < limit) {
+          active++;
+          start();
+        } else {
+          queue.push(start);
+        }
+      });
+    },
+    setMax(n: number): void {
+      if (!Number.isFinite(n) || n < 1) {
+        throw new Error(`Semaphore max must be a positive integer, got ${n}`);
+      }
+      limit = Math.floor(n);
+      // Drain synchronously so callers that do `setMax(n); await tick` see queued tasks started.
+      drain();
+    },
+    size(): number {
+      return active + queue.length;
+    },
+  };
+}

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

@@ -0,0 +1,342 @@
+/**
+ * Registered tool definitions.
+ *
+ * Each definition declares an ordered strategy chain. Individual
+ * strategies are responsible for validating their own resolved paths
+ * (they use the injected `exists` from StrategyDeps), so tests can
+ * inject fakes without triggering real `fs.existsSync` lookups.
+ *
+ * See change: consolidate-tool-resolution.
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { ToolDefinition, Source } from "./types.js";
+import type { ToolRegistry } from "./registry.js";
+import {
+  type StrategyDeps,
+  bareImportStrategy,
+  managedBinStrategy,
+  managedModuleStrategy,
+  npmGlobalStrategy,
+  overrideStrategy,
+  whereStrategy,
+} from "./strategies.js";
+
+// ── Classifier ──────────────────────────────────────────────────────────────
+
+/** Classifier: strategies → Source. Shared across binary and module tools. */
+function classify(strategyName: string): Source {
+  if (strategyName === "override") return "override";
+  if (strategyName === "managed") return "managed";
+  if (strategyName === "npm-global") return "npm-global";
+  if (strategyName === "bare-import") return "bare-import";
+  // `where` and anything else — resolved via PATH — classifies as system.
+  return "system";
+}
+
+// ── Binary definitions ──────────────────────────────────────────────────────
+
+function binaryDef(binaryName: string, deps?: StrategyDeps): ToolDefinition {
+  return {
+    name: binaryName,
+    kind: "binary",
+    strategies: [
+      overrideStrategy(binaryName, deps),
+      managedBinStrategy(binaryName, deps),
+      whereStrategy(binaryName, deps),
+    ],
+    classify,
+  };
+}
+
+// ── Module definitions ──────────────────────────────────────────────────────
+
+/** Sibling probe for an aliased package name (pi: `@mariozechner/*` + `@oh-my-pi/*`). */
+function moduleDefWithAliases(
+  canonicalName: string,
+  pkgNames: readonly string[],
+  entry: string,
+  deps?: StrategyDeps,
+): ToolDefinition {
+  const strategies = [overrideStrategy(canonicalName, deps)];
+  for (const pkg of pkgNames) strategies.push(bareImportStrategy(pkg));
+  for (const pkg of pkgNames) strategies.push(managedModuleStrategy(pkg, entry, deps));
+  for (const pkg of pkgNames) strategies.push(npmGlobalStrategy(pkg, entry, deps));
+  return { name: canonicalName, kind: "module", strategies, classify };
+}
+
+// ── Registration ─────────────────────────────────────────────────
+
+// Tools intentionally NOT registered:
+//   - `tsx` — a TypeScript *loader* used via `node --import tsx`,
+//     not a tool the dashboard spawns. When pi is installed, pi ships
+//     jiti which the server prefers; otherwise tsx is co-installed
+//     as a dev dep of the server package.
+//   - `pi-dashboard` — that's the package this code is part of.
+//     "Is it installed" is a bootstrap concern handled directly in
+//     `packages/electron/src/lib/dependency-detector.ts`.
+// See change: consolidate-tool-resolution (follow-up).
+
+/**
+ * Shared `toArgv` for Node-script executors (pi, openspec, npm).
+ *
+ * On Windows + `.js` resolved path → prepend node.exe to bypass the
+ * `.cmd` shim entirely (no cmd.exe in the spawn chain → no console
+ * flash). Elsewhere → direct invocation.
+ *
+ * This is the heart of the "no cmd flash" story: every CLI that ships
+ * as `.cmd` on Windows and is actually a Node script should be
+ * registered with this `toArgv` so the spawn becomes
+ * `node.exe <script.js>` (pure console-subsystem inherit, no new
+ * window ever).
+ */
+const nodeScriptToArgv: ToolDefinition["toArgv"] = (resolvedPath, { platform, registry }) => {
+  if (platform === "win32" && /\.js$/i.test(resolvedPath)) {
+    const node = registry.resolve("node");
+    if (node.ok && node.path) return [node.path, resolvedPath];
+  }
+  return [resolvedPath];
+};
+
+/**
+ * Executor definition for `pi` — ONE tool, OS dispatch inside.
+ *
+ * On Windows, the strategy chain finds pi-coding-agent's `dist/cli.js`
+ * (managed → bare-import → npm-global), and `toArgv` wraps it with
+ * `node.exe` to produce `[node.exe, cli.js]`. Falls back to `pi.cmd`
+ * on PATH when the cli.js is nowhere to be found.
+ *
+ * On Unix, the chain finds `pi` on PATH; argv = [pi].
+ */
+function piExecutorDef(deps?: StrategyDeps): ToolDefinition {
+  const piPkgAliases = ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"];
+  const cliEntry = path.join("dist", "cli.js");
+
+  const winStrategies = [
+    overrideStrategy("pi", deps),
+    ...piPkgAliases.map((pkg) => bareImportCliStrategy(pkg, cliEntry, deps)),
+    ...piPkgAliases.map((pkg) => managedModuleStrategy(pkg, cliEntry, deps)),
+    ...piPkgAliases.map((pkg) => npmGlobalStrategy(pkg, cliEntry, deps)),
+    managedBinStrategy("pi", deps),
+    whereStrategy("pi", deps),
+  ];
+
+  const unixStrategies = [
+    overrideStrategy("pi", deps),
+    managedBinStrategy("pi", deps),
+    whereStrategy("pi", deps),
+  ];
+
+  return {
+    name: "pi",
+    kind: "executor",
+    strategies: unixStrategies,
+    platformStrategies: { win32: winStrategies },
+    toArgv: nodeScriptToArgv,
+    classify,
+  };
+}
+
+/**
+ * Executor definition for `openspec`.
+ *
+ * On Windows: finds `@fission-ai/openspec/bin/openspec.js` via managed
+ * → bare-import → npm-global. `toArgv` wraps with node.exe.
+ * On Unix: finds `openspec` binary on PATH.
+ */
+function openspecExecutorDef(deps?: StrategyDeps): ToolDefinition {
+  const pkgName = "@fission-ai/openspec";
+  const cliEntry = path.join("bin", "openspec.js");
+
+  const winStrategies = [
+    overrideStrategy("openspec", deps),
+    bareImportCliStrategy(pkgName, cliEntry),
+    managedModuleStrategy(pkgName, cliEntry, deps),
+    npmGlobalStrategy(pkgName, cliEntry, deps),
+    managedBinStrategy("openspec", deps),
+    whereStrategy("openspec", deps),
+  ];
+
+  const unixStrategies = [
+    overrideStrategy("openspec", deps),
+    managedBinStrategy("openspec", deps),
+    whereStrategy("openspec", deps),
+  ];
+
+  return {
+    name: "openspec",
+    kind: "executor",
+    strategies: unixStrategies,
+    platformStrategies: { win32: winStrategies },
+    toArgv: nodeScriptToArgv,
+    classify,
+  };
+}
+
+/**
+ * Executor definition for `npm`.
+ *
+ * npm is bundled with Node itself, not a standalone npm install. On
+ * Windows: find `<node-dir>/node_modules/npm/bin/npm-cli.js` by
+ * looking beside the resolved `node.exe`. Fallback: PATH lookup
+ * (which returns npm.cmd).
+ * On Unix: find `npm` on PATH.
+ *
+ * Motivation: npm.cmd internally runs `node.exe npm-cli.js`, and the
+ * inner node.exe can allocate a new console (Node issue #21825). By
+ * resolving to npm-cli.js directly + spawning via node.exe ourselves,
+ * we bypass cmd.exe + npm.cmd entirely.
+ */
+function npmExecutorDef(deps?: StrategyDeps): ToolDefinition {
+  const npmRelativeToNode = path.join("node_modules", "npm", "bin", "npm-cli.js");
+
+  // Custom strategy: find npm-cli.js beside the resolved node.exe.
+  // We can't pre-compute the node path at definition time (the registry
+  // isn't fully constructed yet), so the strategy resolves node
+  // lazily at run time via the global registry hook.
+  const npmCliBesideNodeStrategy = {
+    name: "managed", // classified as managed because it ships with node
+    run(): { ok: true; path: string } | { ok: false; reason: string } {
+      // Find node.exe from process.execPath or environment.
+      const nodeExe = process.execPath;
+      if (!nodeExe) return { ok: false, reason: "process.execPath unset" };
+      const nodeDir = path.dirname(nodeExe);
+      const candidate = path.join(nodeDir, npmRelativeToNode);
+      try {
+        if (existsSync(candidate)) return { ok: true, path: candidate };
+        return { ok: false, reason: `missing: ${candidate}` };
+      } catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+
+  const winStrategies = [
+    overrideStrategy("npm", deps),
+    npmCliBesideNodeStrategy,
+    whereStrategy("npm", deps),
+  ];
+
+  const unixStrategies = [
+    overrideStrategy("npm", deps),
+    whereStrategy("npm", deps),
+  ];
+
+  return {
+    name: "npm",
+    kind: "executor",
+    strategies: unixStrategies,
+    platformStrategies: { win32: winStrategies },
+    toArgv: nodeScriptToArgv,
+    classify,
+  };
+}
+
+/**
+ * Helper: bare-import strategy that, on success, transforms the
+ * resolved `package.json` into the sibling `<entry>` path. Used by
+ * the pi executor to find pi-coding-agent's cli.js via the same
+ * module-resolution algorithm as `import()`.
+ */
+function bareImportCliStrategy(
+  pkgName: string,
+  entryRelative: string,
+  deps?: StrategyDeps,
+) {
+  // Default uses the real module resolver anchored to this file;
+  // tests inject a fake via deps.resolveModule.
+  const resolveModule: NonNullable<StrategyDeps["resolveModule"]> =
+    deps?.resolveModule
+    ?? ((id, from) => {
+      try {
+        return createRequire(from).resolve(id);
+      } catch {
+        return null;
+      }
+    });
+  return {
+    name: "bare-import",
+    run(): { ok: true; path: string } | { ok: false; reason: string } {
+      const pkgJson = resolveModule(`${pkgName}/package.json`, import.meta.url);
+      if (!pkgJson) {
+        return { ok: false, reason: `cannot resolve ${pkgName}/package.json` };
+      }
+      const entry = path.join(path.dirname(pkgJson), entryRelative);
+      return { ok: true, path: entry };
+    },
+  };
+}
+
+/**
+ * Register the standard set of dashboard tools. Idempotent — callers
+ * may re-register to supply custom strategy deps (e.g. tests).
+ */
+export function registerDefaultTools(registry: ToolRegistry, deps?: StrategyDeps): void {
+  // Executor-kind tools — Node scripts shipped as .cmd shims on
+  // Windows. Each registers as [node.exe, <script>.js] to bypass
+  // cmd.exe and the console-flash chain (Node issue #21825).
+  registry.register(piExecutorDef(deps));
+  registry.register(openspecExecutorDef(deps));
+  registry.register(npmExecutorDef(deps));
+
+  // Native binaries — no interpreter needed.
+  registry.register(binaryDef("node", deps));
+  registry.register(binaryDef("git", deps));
+  registry.register(binaryDef("zrok", deps));
+
+  // Platform-conditional process-inspection utilities. These are only
+  // called by `packages/shared/src/platform/process.ts` on their native
+  // platform — registering the non-native tools would surface as red
+  // "not found" rows in the Settings → Tools UI even though the code
+  // never calls them there.
+  //
+  // Honours the registry's `platform` so tests that inject `platform:
+  // "win32"` from a Linux host still exercise the Windows tool set.
+  //
+  // Windows system utilities used by the bridge's process scanner.
+  // Registered so callers resolve to full `.exe` paths (e.g.
+  // `C:\Windows\System32\wbem\wmic.exe`) and spawn directly — no
+  // PATHEXT resolution, no cmd.exe wrapping, windowsHide:true honored
+  // all the way down. See change: consolidate-windows-spawn-and-platform-handlers.
+  if (registry.getPlatform() === "win32") {
+    registry.register(binaryDef("wmic", deps));
+    registry.register(binaryDef("powershell", deps));
+    registry.register(binaryDef("tasklist", deps));
+    registry.register(binaryDef("taskkill", deps));
+  } else {
+    // POSIX process-inspection utilities. Used by `isProcessRunning`,
+    // `findPidByMarker`, `isProcessLikePi` in platform/process.ts.
+    registry.register(binaryDef("ps", deps));
+    registry.register(binaryDef("pgrep", deps));
+  }
+  // Windows Terminal — optional, override + where only (not part of
+  // managed install, not on Unix).
+  registry.register({
+    name: "wt",
+    kind: "binary",
+    strategies: [
+      overrideStrategy("wt", deps),
+      whereStrategy("wt", deps),
+    ],
+    classify,
+  });
+
+  // Node module entry for pi-coding-agent — used by DefaultPackageManager
+  // to IMPORT pi as a library (not spawn it as a process). Distinct from
+  // the `pi` executor above.
+  registry.register(
+    moduleDefWithAliases(
+      "pi-coding-agent",
+      ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"],
+      path.join("dist", "index.js"),
+      deps,
+    ),
+  );
+}
+
+/** Handy re-exports for callers that want raw definitions for testing. */
+export const _internals = {
+  binaryDef,
+  moduleDefWithAliases,
+};

package/packages/shared/src/tool-registry/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Tool registry — single-source resolver for every external binary/module
+ * the dashboard depends on. See change: consolidate-tool-resolution.
+ *
+ * Quick start:
+ *
+ *   import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry";
+ *   const r = getDefaultRegistry().resolve("pi");
+ *   if (r.ok) spawn(r.path!, args);
+ */
+export * from "./types.js";
+export { OverridesStore, defaultOverridesPath } from "./overrides.js";
+export { ToolRegistry } from "./registry.js";
+export { registerDefaultTools } from "./definitions.js";
+export * from "./strategies.js";
+
+import { ToolRegistry } from "./registry.js";
+import { registerDefaultTools } from "./definitions.js";
+
+/**
+ * Lazily-constructed process-wide registry. Most callers should use this
+ * instead of constructing their own. Tests should pass a fresh
+ * `new ToolRegistry({...})` with injected deps.
+ *
+ * The registry is also published on `globalThis` under a symbol so that
+ * `platform/runner.ts` can pick it up synchronously without a module
+ * import (which would create a load-order cycle through `platform/npm.ts`).
+ */
+const GLOBAL_KEY = Symbol.for("pi-dashboard.tool-registry");
+type GlobalSlot = { [GLOBAL_KEY]?: ToolRegistry };
+
+let defaultRegistry: ToolRegistry | null = null;
+export function getDefaultRegistry(): ToolRegistry {
+  if (!defaultRegistry) {
+    defaultRegistry = new ToolRegistry();
+    registerDefaultTools(defaultRegistry);
+    (globalThis as unknown as GlobalSlot)[GLOBAL_KEY] = defaultRegistry;
+  }
+  return defaultRegistry;
+}
+
+/**
+ * Global accessor for consumers that cannot import this module at the
+ * top level (i.e. `platform/runner.ts`, which is part of a load-order
+ * cycle). Returns `null` if `getDefaultRegistry()` hasn't been called
+ * yet anywhere in the process.
+ */
+export function peekGlobalRegistry(): ToolRegistry | null {
+  return (globalThis as unknown as GlobalSlot)[GLOBAL_KEY] ?? null;
+}
+
+/** Test-only: drop the process-wide registry so the next call rebuilds. */
+export function _resetDefaultRegistry(): void {
+  defaultRegistry = null;
+  (globalThis as unknown as GlobalSlot)[GLOBAL_KEY] = undefined;
+}