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

package/packages/shared/src/openspec-poller.ts

@@ -23,12 +23,47 @@
 import { listOr, statusOr, OPENSPEC_LIST, OPENSPEC_STATUS } from "./platform/openspec.js";
 import { runAsync, unwrap } from "./platform/runner.js";
 import type { OpenSpecData, OpenSpecChange, OpenSpecArtifact } from "./types.js";
+import {
+  evaluateLocalDesignSatisfaction,
+  createFsDesignEvidenceProbe,
+  type DesignEvidenceProbe,
+} from "./openspec-design-evidence.js";
+import {
+  evaluateLocalSpecsSatisfaction,
+  createFsSpecsEvidenceProbe,
+  type SpecsEvidenceProbe,
+} from "./openspec-specs-evidence.js";
+import path from "node:path";
 
 const EMPTY_DATA: OpenSpecData = { initialized: false, changes: [] };
 
+/**
+ * Factory that returns a probe for a given change name. Production callers
+ * pass a closure rooted at `<cwd>/openspec/changes/<name>`. Tests pass an
+ * in-memory factory. When omitted, the design override does NOT fire and
+ * `buildOpenSpecData` matches today's behavior verbatim.
+ *
+ * See change: fix-openspec-design-detection.
+ */
+export type DesignProbeFactory = (changeName: string) => DesignEvidenceProbe;
+
+/**
+ * Factory that returns a specs-evidence probe for a given change name.
+ * Parallel to `DesignProbeFactory` — production callers pass a closure
+ * rooted at `<cwd>/openspec/changes/<name>`; tests pass an in-memory
+ * factory. When omitted, the specs override does NOT fire and
+ * `buildOpenSpecData` matches today's behavior verbatim for the specs
+ * artifact.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+export type SpecsProbeFactory = (changeName: string) => SpecsEvidenceProbe;
+
 export function buildOpenSpecData(
   listResult: { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> } | null,
   statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>,
+  probeFactory?: DesignProbeFactory,
+  specsProbeFactory?: SpecsProbeFactory,
 ): OpenSpecData {
   if (!listResult || !Array.isArray(listResult.changes)) {
     return EMPTY_DATA;
@@ -41,9 +76,40 @@ export function buildOpenSpecData(
       status: (a.status === "done" ? "done" : a.status === "ready" ? "ready" : "blocked") as OpenSpecArtifact["status"],
     }));
 
-    const isComplete =
+    // Design-artifact override: promote-only, design-only. See change:
+    // fix-openspec-design-detection.
+    if (probeFactory) {
+      const designIdx = artifacts.findIndex((a) => a.id === "design");
+      if (designIdx !== -1 && artifacts[designIdx].status === "ready") {
+        const probe = probeFactory(c.name);
+        if (evaluateLocalDesignSatisfaction("", probe)) {
+          artifacts[designIdx] = { ...artifacts[designIdx], status: "done" };
+        }
+      }
+    }
+
+    // Specs-artifact override: promote-only, specs-only. See change:
+    // fix-openspec-specs-mtime-gate-blind-spot.
+    if (specsProbeFactory) {
+      const specsIdx = artifacts.findIndex((a) => a.id === "specs");
+      if (specsIdx !== -1 && artifacts[specsIdx].status === "ready") {
+        const probe = specsProbeFactory(c.name);
+        if (evaluateLocalSpecsSatisfaction("", probe)) {
+          artifacts[specsIdx] = { ...artifacts[specsIdx], status: "done" };
+        }
+      }
+    }
+
+    const cliIsComplete =
       typeof statusResult?.isComplete === "boolean" ? statusResult.isComplete : undefined;
 
+    // Re-derive isComplete from post-override artifacts. Promote false→true
+    // only when every artifact is done; never demote CLI true.
+    let isComplete = cliIsComplete;
+    if (artifacts.length > 0 && artifacts.every((a) => a.status === "done")) {
+      isComplete = true;
+    }
+
     const change: OpenSpecChange = {
       name: c.name,
       status: (c.status === "complete" ? "complete" : c.status === "in-progress" ? "in-progress" : "no-tasks") as OpenSpecChange["status"],
@@ -58,6 +124,44 @@ export function buildOpenSpecData(
   return { initialized: true, changes };
 }
 
+/**
+ * Build a real-fs probe factory rooted at `<cwd>/openspec/changes/<name>`.
+ * Production callers (`pollOpenSpec`, `pollOpenSpecAsync`,
+ * `directory-service.ts`) use this to wire the override. Tests inject
+ * their own factory.
+ */
+export function createFsProbeFactory(cwd: string): DesignProbeFactory {
+  const probe = createFsDesignEvidenceProbe();
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  return (changeName) => {
+    const changeDir = path.join(changesRoot, changeName);
+    return {
+      hasDesignFile: () => probe.hasDesignFile(changeDir),
+      hasDesignDirWithMd: () => probe.hasDesignDirWithMd(changeDir),
+      tasksHasCheckboxes: () => probe.tasksHasCheckboxes(changeDir),
+    };
+  };
+}
+
+/**
+ * Build a real-fs specs-probe factory rooted at `<cwd>/openspec/changes/<name>`.
+ * Parallel to `createFsProbeFactory` — production callers (`pollOpenSpec`,
+ * `pollOpenSpecAsync`, `directory-service.ts`) use this to wire the specs
+ * override. Tests inject their own factory.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+export function createFsSpecsProbeFactory(cwd: string): SpecsProbeFactory {
+  const probe = createFsSpecsEvidenceProbe();
+  const changesRoot = path.join(cwd, "openspec", "changes");
+  return (changeName) => {
+    const changeDir = path.join(changesRoot, changeName);
+    return {
+      hasAnySpecFile: () => probe.hasAnySpecFile(changeDir),
+    };
+  };
+}
+
 /**
  * Synchronous poll — blocks the event loop. Used by the bridge extension
  * where async isn't practical (some pi extension hooks are sync).
@@ -70,7 +174,12 @@ export function pollOpenSpec(cwd: string): OpenSpecData {
   for (const c of listResult.changes) {
     statusResults.set(c.name, statusOr({ cwd, change: c.name }));
   }
-  return buildOpenSpecData(listResult, statusResults);
+  return buildOpenSpecData(
+    listResult,
+    statusResults,
+    createFsProbeFactory(cwd),
+    createFsSpecsProbeFactory(cwd),
+  );
 }
 
 /**
@@ -114,5 +223,10 @@ export async function pollOpenSpecAsync(cwd: string): Promise<OpenSpecData> {
     }),
   );
   const statusResults = new Map<string, any>(statusEntries);
-  return buildOpenSpecData(listResult, statusResults);
+  return buildOpenSpecData(
+    listResult,
+    statusResults,
+    createFsProbeFactory(cwd),
+    createFsSpecsProbeFactory(cwd),
+  );
 }

package/packages/shared/src/openspec-specs-evidence.ts

@@ -0,0 +1,79 @@
+/**
+ * Local-evidence override for the OpenSpec `specs` artifact.
+ *
+ * The `spec-driven` schema declares `specs/**\/*.md` as the `generates`
+ * pattern for the `specs` artifact, and the openspec CLI marks the
+ * artifact `done` whenever that glob matches anything. The dashboard's
+ * mtime-gated cache, however, can momentarily stale on `specs: ready`
+ * for multi-spec changes (see change:
+ * fix-openspec-specs-mtime-gate-blind-spot — the watch set is now
+ * extended to cover `specs/**`, but this override is the second line
+ * of defence).
+ *
+ * This module computes a boolean "is specs satisfied locally?" from
+ * file-system evidence the dashboard's cache might miss between polls.
+ * It is consumed by:
+ *
+ *   1. `buildOpenSpecData` in `openspec-poller.ts` — promotes
+ *      `artifacts[specs].status` from "ready" to "done" when at least
+ *      one `specs/**\/*.md` file exists. Promote-only; specs-only;
+ *      never demotes; never touches other artifacts.
+ *
+ * One rule:
+ *
+ *   any file matching `specs/**\/*.md` exists in the change folder
+ *
+ * The probe walks the `specs/` subtree once and short-circuits on the
+ * first `*.md` it finds. Defensive: every fs call is wrapped in
+ * try/catch and treated as "no match" on error.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+
+import { readdirSync } from "node:fs";
+import path from "node:path";
+
+/** Probe surface — kept tiny so unit tests can pass an in-memory stub. */
+export interface SpecsEvidenceProbe {
+  /** Returns true iff at least one `*.md` file exists under `<changeDir>/specs/`. */
+  hasAnySpecFile(changeDir: string): boolean;
+}
+
+/** Pure rule evaluator. Single rule; short-circuits on first match. */
+export function evaluateLocalSpecsSatisfaction(
+  changeDir: string,
+  probe: SpecsEvidenceProbe,
+): boolean {
+  return probe.hasAnySpecFile(changeDir);
+}
+
+/**
+ * Production probe — backed by the real filesystem. Walks `<changeDir>/specs/`
+ * iteratively, short-circuits on the first `*.md` file encountered. Every
+ * `readdirSync` is wrapped in try/catch (handles ENOENT, permission errors,
+ * symlink loops, and any unexpected fs error) and treated as "no match".
+ */
+export function createFsSpecsEvidenceProbe(): SpecsEvidenceProbe {
+  return {
+    hasAnySpecFile(changeDir: string): boolean {
+      const root = path.join(changeDir, "specs");
+      // Iterative DFS — no recursion to avoid stack overflow on pathological trees.
+      const stack: string[] = [root];
+      while (stack.length > 0) {
+        const dir = stack.pop()!;
+        let entries: import("node:fs").Dirent[];
+        try {
+          entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+          // Missing dir, permission denied, or any other fs error — skip.
+          continue;
+        }
+        for (const e of entries) {
+          if (e.isFile() && e.name.endsWith(".md")) return true;
+          if (e.isDirectory()) stack.push(path.join(dir, e.name));
+        }
+      }
+      return false;
+    },
+  };
+}

package/packages/shared/src/platform/binary-lookup.ts

@@ -4,11 +4,106 @@
  * with a single configurable resolver.
  */
 import { execSync, spawnSync, buildSafeArgv } from "./exec.js";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { MANAGED_BIN, MANAGED_DIR } from "../managed-paths.js";
 
+// ── AppImage self-hit guard (Linux power-user mode safety) ────────────────
+
+/**
+ * Optional environment overrides for {@link isAppImageSelfHit}. Tests
+ * inject explicit values so the helper can exercise both branches
+ * without mutating `process.env` or `process.execPath`. Production
+ * callers omit `opts` and the helper reads from the live process.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+export interface AppImageSelfHitOpts {
+  /** Override `process.execPath`. Default: `process.execPath`. */
+  execPath?: string;
+  /** Override `process.env.APPDIR`. Default: `process.env.APPDIR`. */
+  appDir?: string | undefined;
+  /** Override `process.env.APPIMAGE`. Default: `process.env.APPIMAGE`. */
+  appImage?: string | undefined;
+}
+
+/** Defensive realpath — returns the input on any error (broken symlink / ENOENT). */
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Returns `true` when `candidatePath` is the running process's own
+ * Electron launcher binary — the bug class that motivates this helper:
+ * AppImage's runtime prepends its squashfs mount (`/tmp/.mount_*`) to
+ * `PATH` of the Electron child, and `packagerConfig.executableName =
+ * "pi-dashboard"` makes the launcher a name-collision with the dashboard
+ * CLI. Trusting the first `which pi-dashboard` hit therefore spawns the
+ * Electron app recursively as if it were the CLI.
+ *
+ * A path is considered a self-hit when ANY of the following is true:
+ *   - `realpath(candidatePath) === realpath(execPath)`, OR
+ *   - `candidatePath` lives under the directory named by `appDir`, OR
+ *   - `realpath(candidatePath) === realpath(appImage)`.
+ *
+ * `realpath` calls are wrapped in try/catch so broken symlinks / ENOENT
+ * fall back to literal string comparisons. The helper never throws.
+ *
+ * Production callers (`whereStrategy`, `detectPiDashboardCli`,
+ * `detectPi`, `detectSystemNode`) omit `opts`. Tests pass explicit
+ * overrides via `opts`.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+export function isAppImageSelfHit(
+  candidatePath: string,
+  opts?: AppImageSelfHitOpts,
+): boolean {
+  if (!candidatePath) return false;
+
+  const execPath = opts && "execPath" in opts ? opts.execPath : process.execPath;
+  const appDir = opts && "appDir" in opts ? opts.appDir : process.env.APPDIR;
+  const appImage = opts && "appImage" in opts ? opts.appImage : process.env.APPIMAGE;
+
+  const realCandidate = safeRealpath(candidatePath);
+
+  // Rule 1: realpath equals process.execPath
+  if (execPath) {
+    const realExec = safeRealpath(execPath);
+    if (realCandidate === realExec) return true;
+    if (candidatePath === execPath) return true;
+  }
+
+  // Rule 2: candidate lives under APPDIR (the AppImage squashfs mount).
+  // We compare the candidate's realpath against APPDIR's realpath so a
+  // symlink under the mount is still recognized as a self-hit.
+  if (appDir) {
+    const realAppDir = safeRealpath(appDir);
+    const sep = path.sep;
+    // Append separator so /tmp/.mount_PI doesn't accidentally match
+    // /tmp/.mount_PIxx-elsewhere via prefix.
+    const prefix = realAppDir.endsWith(sep) ? realAppDir : realAppDir + sep;
+    if (realCandidate === realAppDir || realCandidate.startsWith(prefix)) return true;
+    // Literal fallback (broken symlinks / ENOENT keep a useful answer).
+    const litPrefix = appDir.endsWith(sep) ? appDir : appDir + sep;
+    if (candidatePath === appDir || candidatePath.startsWith(litPrefix)) return true;
+  }
+
+  // Rule 3: realpath equals APPIMAGE (the .AppImage file the user clicked).
+  if (appImage) {
+    const realAppImage = safeRealpath(appImage);
+    if (realCandidate === realAppImage) return true;
+    if (candidatePath === appImage) return true;
+  }
+
+  return false;
+}
+
 /**
  * Well-known globalThis symbol for the default `ToolRegistry`.
  *

package/packages/shared/src/platform/index.ts

@@ -9,6 +9,7 @@ export * from "./detached-spawn.js";
 export * from "./spawn-mechanism.js";
 export * from "./process-identify.js";
 export * from "./subprocess-adapter.js";
+export * from "./node-spawn.js";
 export * as git from "./git.js";
 export * as openspec from "./openspec.js";
 export * as npm from "./npm.js";

package/packages/shared/src/platform/node-spawn.ts

@@ -0,0 +1,154 @@
+/**
+ * Canonical helper for spawning `node --import <loader> <entry>` argv.
+ *
+ * Node ≥ 20's ESM loader parses BOTH the `--import` loader position AND
+ * the entry-script position as URLs. Raw Windows paths like
+ * `B:\Dev\foo.ts` URL-parse to scheme `b:`, which is not in the ESM
+ * loader's allowlist (file, data, node) → the process crashes with
+ * `ERR_UNSUPPORTED_ESM_URL_SCHEME` before any filesystem access.
+ *
+ * Node's internal drive-letter heuristic catches the common cases
+ * (`C:\`, `D:\`) but has known gaps for `A:`, `B:`, and other letters.
+ * Rather than relying on the heuristic, we wrap the loader position
+ * with `file://` unconditionally.
+ *
+ * The entry-script position needs a more nuanced rule. Node's default
+ * resolver AND jiti's ESM hook both accept `file://` URL entries. But
+ * **tsx's ESM hook rejects `file://` URLs as entries** — tsx's resolver
+ * treats the entry as a user-typed specifier and attempts bare-import
+ * / relative-path resolution, producing `<cwd>/file:/...` errors.
+ * Since tsx is used as the jiti fallback on dev machines without pi
+ * installed (the most common Linux dev path), we must NOT URL-wrap
+ * the entry when the loader is tsx. Detection: the loader path
+ * contains `/tsx/` (every tsx install ships its hook under a `tsx/`
+ * directory; jiti's hook is under `jiti/`).
+ *
+ * This module is the canonical chokepoint. The repo-level lint test
+ * `no-raw-node-import.test.ts` refuses any other call site that
+ * passes a raw path to `--import` / `--loader`.
+ *
+ * See change: fix-windows-entry-script-url.
+ */
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { SpawnOptions, ChildProcess } from "node:child_process"; // ban:child_process-ok — types only
+import { spawn as execSpawn } from "./exec.js";
+
+export interface SpawnNodeScriptOptions {
+  /** Path to node.exe / node (raw OS path — binary, not ESM-loaded). */
+  nodeBin?: string;
+
+  /** Path to the script Node will run. Raw path OR file:// URL. */
+  entry: string;
+
+  /** Optional ESM loader for --import. Raw path OR file:// URL. */
+  loader?: string;
+
+  /** Arguments passed to the script (after entry). */
+  args?: string[];
+
+  /** Standard spawn options (cwd, env, stdio, detached, etc.). */
+  spawnOptions?: SpawnOptions;
+}
+
+/**
+ * Detect whether a loader (file:// URL or raw path) is tsx.
+ *
+ * tsx's ESM hook rejects `file://` URLs at the entry-script position,
+ * so the caller must pass a raw OS path for the entry when this
+ * returns true. jiti and Node's default resolver both accept URL
+ * entries.
+ *
+ * Heuristic: every tsx install places its hook under a `tsx/` package
+ * directory (e.g. `.../node_modules/tsx/dist/esm/index.mjs`). The
+ * check is tolerant of `file://` URLs, raw POSIX paths, and raw
+ * Windows paths with either slash direction.
+ */
+export function isTsxLoader(loader: string | null | undefined): boolean {
+  if (!loader) return false;
+  // Normalize backslashes so the `/tsx/` probe works on Windows paths.
+  const normalized = loader.replace(/\\/g, "/");
+  return /\/tsx\//i.test(normalized);
+}
+
+/**
+ * Convert a path-or-url string to a file:// URL.
+ *
+ * Pure and idempotent. Safe to call on strings that are already
+ * file:// URLs — returns them unchanged.
+ *
+ * Handles Windows-style input (drive letter + backslash) regardless of
+ * host OS, so unit tests on Linux/macOS can exercise the Windows path
+ * contract. Mirrors the pattern in
+ * `packages/shared/src/resolve-jiti.ts::buildJitiRegisterUrl`.
+ */
+export function toFileUrl(pathOrUrl: string): string {
+  if (pathOrUrl.startsWith("file:")) return pathOrUrl;
+
+  const isWindowsStyle = /^[A-Za-z]:[\\/]/.test(pathOrUrl);
+  if (isWindowsStyle) {
+    // pathToFileURL on POSIX hosts URL-encodes backslashes rather than
+    // treating them as separators. Build the URL manually so tests on
+    // Linux produce the same result a Windows host would.
+    return `file:///${pathOrUrl.replace(/\\/g, "/")}`;
+  }
+
+  // Use path.resolve to ensure absolute path on the host OS, then
+  // let Node's pathToFileURL handle any host-specific quirks.
+  const absolute = path.isAbsolute(pathOrUrl) ? pathOrUrl : path.resolve(pathOrUrl);
+  return pathToFileURL(absolute).href;
+}
+
+/**
+ * Decide whether the entry-script position needs `file://` URL wrapping.
+ *
+ * Rule:
+ *   - tsx loader: always raw path (tsx rejects file:// entries on every OS)
+ *   - non-tsx (jiti / Node default) on POSIX: raw path
+ *     (POSIX has no drive-letter / URL-scheme collision; jiti's resolver
+ *      actively MISBEHAVES when handed `file://` URL entries — it
+ *      normalises away the triple-slash and then treats `file:/...` as
+ *      a relative specifier, producing `<cwd>/file:/...` ENOENT errors.)
+ *   - non-tsx on Windows: file:// URL
+ *     (Node parses drive letters like `B:` / `A:` as URL schemes in argv
+ *      before loaders run, throwing ERR_UNSUPPORTED_ESM_URL_SCHEME.
+ *      Wrapping with `file://` sidesteps the parse.)
+ *
+ * Keeps a `platform` parameter for testability so unit tests on a POSIX
+ * host can exercise the Windows branch without mutating `process.platform`.
+ */
+export function shouldUrlWrapEntry(
+  loader: string | null | undefined,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (isTsxLoader(loader)) return false;
+  return platform === "win32";
+}
+
+/**
+ * Spawn `node` with an optional `--import` loader and a script entry.
+ *
+ * The loader position is always URL-wrapped (Node's ESM loader
+ * requires `file://` on Windows drive letters outside the heuristic).
+ *
+ * The entry position follows `shouldUrlWrapEntry(loader, platform)` —
+ * URL on Windows + non-tsx, raw everywhere else.
+ *
+ * Delegates actual spawning to `platform/exec.ts::spawn` so the
+ * `windowsHide: true` default and other safe-spawn invariants are
+ * preserved. Does not import `node:child_process` directly (the type
+ * imports above are annotated with the opt-out marker).
+ */
+export function spawnNodeScript(opts: SpawnNodeScriptOptions): ChildProcess {
+  const nodeBin = opts.nodeBin ?? process.execPath;
+  const wrapEntry = shouldUrlWrapEntry(opts.loader);
+
+  const argv: string[] = [];
+  if (opts.loader) {
+    argv.push("--import", toFileUrl(opts.loader));
+  }
+  argv.push(wrapEntry ? toFileUrl(opts.entry) : opts.entry);
+  if (opts.args) argv.push(...opts.args);
+
+  return execSpawn(nodeBin, argv, opts.spawnOptions ?? {});
+}

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

@@ -0,0 +1,139 @@
+/**
+ * Plugin bridge entry management in pi's settings.json.
+ *
+ * Manages `dashboard-<plugin-id>` keys in a dedicated
+ * `dashboardPluginBridges` object inside settings.json.
+ *
+ * Rules:
+ * - Only touches entries under the `dashboardPluginBridges` key.
+ * - NEVER modifies user-owned `packages[]` entries.
+ * - Uses atomic write (tmp + rename) for all updates.
+ * - Detects path conflicts (existing entry with mismatched path).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export interface PluginBridgeRegisterOptions {
+  homedir?: string;
+}
+
+export type PluginBridgeConflict =
+  | { type: "ok" }
+  | { type: "conflict"; existingPath: string; newPath: string };
+
+function getSettingsPath(homedir?: string): string {
+  const home = homedir ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+  return path.join(home, ".pi", "agent", "settings.json");
+}
+
+function readSettings(settingsPath: string): Record<string, unknown> {
+  try {
+    if (!fs.existsSync(settingsPath)) return {};
+    const raw = fs.readFileSync(settingsPath, "utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settingsPath: string, settings: Record<string, unknown>): void {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + ".tmp." + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+  fs.renameSync(tmp, settingsPath);
+}
+
+function getManagedBridges(
+  settings: Record<string, unknown>,
+): Record<string, string> {
+  const val = settings.dashboardPluginBridges;
+  if (val && typeof val === "object" && !Array.isArray(val)) {
+    return val as Record<string, string>;
+  }
+  return {};
+}
+
+const MANAGED_PREFIX = "dashboard-";
+
+/**
+ * Register a plugin's bridge entry in pi's settings.json.
+ *
+ * Returns { type: "conflict", existingPath, newPath } if a
+ * `dashboard-<pluginId>` key already exists but points to a different path.
+ * In that case the settings.json is NOT modified.
+ *
+ * Returns { type: "ok" } on success (including when the entry already matches).
+ */
+export function registerPluginBridge(
+  pluginId: string,
+  bridgePath: string,
+  opts: PluginBridgeRegisterOptions = {},
+): PluginBridgeConflict {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  const managed = getManagedBridges(settings);
+  const key = MANAGED_PREFIX + pluginId;
+
+  const existing = managed[key];
+  if (existing) {
+    if (existing === bridgePath) return { type: "ok" }; // already registered
+    return { type: "conflict", existingPath: existing, newPath: bridgePath };
+  }
+
+  managed[key] = bridgePath;
+  settings.dashboardPluginBridges = managed;
+  writeSettings(settingsPath, settings);
+  console.info(`[plugin-bridge] Registered bridge for plugin "${pluginId}": ${bridgePath}`);
+  return { type: "ok" };
+}
+
+/**
+ * Remove a plugin's bridge entry from pi's settings.json.
+ * No-op if the entry does not exist.
+ * NEVER touches entries without the `dashboard-` prefix.
+ */
+export function deregisterPluginBridge(
+  pluginId: string,
+  opts: PluginBridgeRegisterOptions = {},
+): void {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  const managed = getManagedBridges(settings);
+  const key = MANAGED_PREFIX + pluginId;
+
+  if (!(key in managed)) return; // nothing to remove
+
+  delete managed[key];
+  settings.dashboardPluginBridges = managed;
+  writeSettings(settingsPath, settings);
+  console.info(`[plugin-bridge] Deregistered bridge for plugin "${pluginId}"`);
+}
+
+/**
+ * Register all plugins with bridge entries from the discovery list.
+ * Returns a map of pluginId → conflict/ok result.
+ * Plugins with conflicts are NOT registered; caller should surface via /api/health.
+ */
+export function registerAllPluginBridges(
+  plugins: Array<{ pluginId: string; bridgePath: string }>,
+  opts: PluginBridgeRegisterOptions = {},
+): Record<string, PluginBridgeConflict> {
+  const results: Record<string, PluginBridgeConflict> = {};
+  for (const { pluginId, bridgePath } of plugins) {
+    results[pluginId] = registerPluginBridge(pluginId, bridgePath, opts);
+  }
+  return results;
+}
+
+/**
+ * List all currently managed plugin bridge entries.
+ */
+export function listManagedBridges(
+  opts: PluginBridgeRegisterOptions = {},
+): Record<string, string> {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  return getManagedBridges(settings);
+}