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

package/packages/shared/src/__tests__/no-flow-references-in-shell.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Repo-level invariant: the dashboard shell SHALL NOT carry flow-
+ * specific RENDERING or STATE code. This lint scans a curated set of
+ * "shell-rendering" files for forbidden identifiers (component names,
+ * deleted state fields, deleted scalars) and fails CI if any reappear.
+ *
+ * What this lint catches:
+ *
+ *   - Imports from `pi-dashboard-flows-plugin/client` in shell files.
+ *   - Identifiers like `FlowDashboard`, `FlowArchitect`, `FlowAgentDetail`,
+ *     `FlowArchitectDetail`, `FlowSummary`, `FlowActivityBadge`,
+ *     `SessionFlowActions`, `FlowLaunchDialog` — a reintroduction of
+ *     any indicates the shell rendering them again.
+ *   - Identifiers `flowState`, `flowStates`, `architectState` — deleted
+ *     `SessionState` fields.
+ *   - Identifiers `activeFlowName`, `flowAgentsDone`, `flowAgentsTotal`,
+ *     `flowStatus` — deleted `DashboardSession` scalars.
+ *   - `hasActiveFlow` — deleted predicate (replaced by component self-gate).
+ *
+ * What this lint does NOT catch (intentional):
+ *
+ *   - `flow_*` / `architect_*` event/message TYPE STRINGS in the wire
+ *     protocol (the shell still receives & forwards them; the plugin
+ *     is the consumer).
+ *   - `overflow`, `workflow`, etc. (CSS / unrelated words).
+ *   - Comments / breadcrumb strings referencing the change name.
+ *   - References inside `flows-plugin/`, `tests/`, or wire-protocol
+ *     files (`protocol.ts`, `browser-protocol.ts`).
+ *
+ * If this test fails, the suggested replacement depends on what the
+ * shell file is trying to do:
+ *
+ *   - Render flow content       → use a slot consumer
+ *                                  (`<ContentHeaderStickySlot>` etc.)
+ *   - Read flow state           → it can't. Move the consumer into a
+ *                                  plugin and call `useSessionEvents`.
+ *
+ * See change: pluginize-flows-via-registry.
+ */
+import { describe, expect, it } 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 REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
+
+/**
+ * Specific shell-rendering / shell-state files this lint scans. The
+ * scope is curated rather than "all of packages/{shared,server,client}"
+ * because the wire protocol legitimately references plugin message
+ * names by string, OAuth-flow comments are unrelated, and CSS class
+ * names contain "overflow". Curating to the rendering surface gives
+ * a high-signal regression test.
+ */
+const SHELL_FILES_TO_SCAN = [
+  // Top-level shell rendering
+  path.join(REPO_ROOT, "packages", "client", "src", "App.tsx"),
+  path.join(REPO_ROOT, "packages", "client", "src", "components", "SessionCard.tsx"),
+  path.join(REPO_ROOT, "packages", "client", "src", "components", "SessionHeader.tsx"),
+  path.join(REPO_ROOT, "packages", "client", "src", "components", "MobileShell.tsx"),
+  path.join(REPO_ROOT, "packages", "client", "src", "components", "SessionList.tsx"),
+  // Shell state machines + back-nav helpers
+  path.join(REPO_ROOT, "packages", "client", "src", "lib", "event-reducer.ts"),
+  path.join(REPO_ROOT, "packages", "client", "src", "lib", "desktop-back.ts"),
+  path.join(REPO_ROOT, "packages", "client", "src", "hooks", "useDesktopBack.ts"),
+  path.join(REPO_ROOT, "packages", "client", "src", "hooks", "useMessageHandler.ts"),
+  // Server-side session-update extractor
+  path.join(REPO_ROOT, "packages", "server", "src", "event-status-extraction.ts"),
+];
+
+/**
+ * Forbidden identifier patterns. Each is a regex that matches the
+ * identifier as a standalone word.
+ */
+const FORBIDDEN_IDENTIFIERS = [
+  // Flow component names from flows-plugin
+  /\bFlowDashboard\b/,
+  /\bFlowArchitect\b/,
+  /\bFlowArchitectDetail\b/,
+  /\bFlowAgentDetail\b/,
+  /\bFlowSummary\b/,
+  /\bFlowActivityBadge\b/,
+  /\bSessionFlowActions\b/,
+  /\bFlowLaunchDialog\b/,
+  /\bFlowAgentCard\b/,
+  /\bFlowGraph\b/,
+  // Flow / architect plugin-internal state field names
+  /\bflowState\b/,
+  /\bflowStates\b/,
+  /\barchitectState\b/,
+  /\bflowDetailAgent\b/,
+  /\barchitectDetailOpen\b/,
+  /\bsourceOpenAgent\b/,
+  /\bflowYamlPreview\b/,
+  // Removed DashboardSession scalars
+  /\bactiveFlowName\b/,
+  /\bflowAgentsDone\b/,
+  /\bflowAgentsTotal\b/,
+  /\bflowStatus\b/,
+  // Removed predicate
+  /\bhasActiveFlow\b/,
+  // Imports from the plugin's client subpath — the shell SHALL NOT
+  // import any React component from flows-plugin.
+  /pi-dashboard-flows-plugin\/client/,
+];
+
+/** Regex for full-line comments (single-line // or block-comment continuation *). */
+const COMMENT_LINE_RE = /^\s*(\/\/|\*|\/\*)/;
+
+interface Violation {
+  file: string;
+  line: number;
+  source: string;
+  match: string;
+}
+
+/**
+ * Scan a source file for forbidden identifiers outside of comment
+ * lines. Returns each violation with file:line + the matching token.
+ */
+function scanFile(filePath: string): Violation[] {
+  if (!fs.existsSync(filePath)) return [];
+  const source = fs.readFileSync(filePath, "utf-8");
+  const violations: Violation[] = [];
+  const lines = source.split("\n");
+  let inBlockComment = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (inBlockComment) {
+      const closeIdx = line.indexOf("*/");
+      if (closeIdx >= 0) inBlockComment = false;
+      continue;
+    }
+    if (COMMENT_LINE_RE.test(line)) continue;
+    const blockOpenIdx = line.indexOf("/*");
+    if (blockOpenIdx >= 0 && line.indexOf("*/", blockOpenIdx + 2) < 0) {
+      inBlockComment = true;
+    }
+
+    for (const re of FORBIDDEN_IDENTIFIERS) {
+      const match = line.match(re);
+      if (!match) continue;
+      violations.push({
+        file: path.relative(REPO_ROOT, filePath),
+        line: i + 1,
+        source: line.trim(),
+        match: match[0],
+      });
+      break; // one violation per line is enough
+    }
+  }
+  return violations;
+}
+
+describe("no-flow-references-in-shell (repo-lint)", () => {
+  it("dashboard shell source SHALL NOT contain any reference to flows", () => {
+    const allViolations: Violation[] = [];
+    for (const file of SHELL_FILES_TO_SCAN) {
+      allViolations.push(...scanFile(file));
+    }
+
+    if (allViolations.length > 0) {
+      const lines = allViolations.map(
+        (v) => `  ${v.file}:${v.line}  [matched "${v.match}"]\n    ${v.source}`,
+      );
+      throw new Error(
+        `Found ${allViolations.length} flow reference(s) in shell source.\n` +
+          "The dashboard shell SHALL contain zero references to flows. Move the\n" +
+          "code into flows-plugin instead. See change: pluginize-flows-via-registry.\n\n" +
+          lines.join("\n\n"),
+      );
+    }
+  });
+
+  it("self-test: detects a planted bad fixture", () => {
+    const fixture = `import { FlowDashboard } from "@blackbelt-technology/pi-dashboard-flows-plugin/client";\nconst x = 1;\n`;
+    const tmp = path.join(REPO_ROOT, ".tmp-no-flow-refs-fixture.tsx");
+    fs.writeFileSync(tmp, fixture);
+    try {
+      const violations = scanFile(tmp);
+      // Both the FlowDashboard identifier AND the import path match;
+      // the scanner returns one violation per line, so we expect 1.
+      expect(violations).toHaveLength(1);
+    } finally {
+      fs.unlinkSync(tmp);
+    }
+  });
+
+  it("self-test: comment-only references are not flagged", () => {
+    const fixture = [
+      `// FlowDashboard moved to flows-plugin per pluginize-flows-via-registry`,
+      `/* hasActiveFlow predicate removed */`,
+      `const x = 1;`,
+    ].join("\n");
+    const tmp = path.join(REPO_ROOT, ".tmp-no-flow-refs-fixture-comments.tsx");
+    fs.writeFileSync(tmp, fixture);
+    try {
+      const violations = scanFile(tmp);
+      expect(violations).toHaveLength(0);
+    } finally {
+      fs.unlinkSync(tmp);
+    }
+  });
+
+  it("self-test: CSS overflow / workflow / unrelated 'flow' words not flagged", () => {
+    const fixture = [
+      `<div className="overflow-hidden flow-root">`,
+      `const oauthFlow = "codex_cli_simplified_flow";`,
+      `// publish workflow contract test`,
+    ].join("\n");
+    const tmp = path.join(REPO_ROOT, ".tmp-no-flow-refs-fixture-css.tsx");
+    fs.writeFileSync(tmp, fixture);
+    try {
+      const violations = scanFile(tmp);
+      expect(violations).toHaveLength(0);
+    } finally {
+      fs.unlinkSync(tmp);
+    }
+  });
+});

package/packages/shared/src/__tests__/no-managed-dir-reference.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Repo-lint — guards the immutable-bundle invariant from change:
+ * eliminate-electron-runtime-install (Phase 7.4).
+ *
+ * Under R3, the Electron arm MUST NOT install, materialize, or otherwise
+ * write into `~/.pi-dashboard/`. The only places that may still reference
+ * the literal `.pi-dashboard` string are:
+ *
+ *   1. `packages/shared/src/legacy-managed-dir.ts` — the dedicated
+ *      detection helper used by Doctor + server CLI to surface an
+ *      advisory row pointing at the leftover directory.
+ *   2. `packages/shared/src/managed-paths.ts` and the Electron mirror
+ *      `packages/electron/src/lib/managed-paths.ts` — kept ONLY so the
+ *      shared-doctor MANAGED_DIR check + standalone pi-core update path
+ *      can probe the legacy install when a user previously installed pi
+ *      there manually. Read-only / pi-core-update only; NOT used by any
+ *      Electron startup or install code path.
+ *   3. `packages/shared/src/platform/binary-lookup.ts`,
+ *      `packages/shared/src/platform/managed-node-path.ts`,
+ *      `packages/shared/src/tool-registry/strategies.ts` — fallback
+ *      probes that READ `~/.pi-dashboard/node_modules/` for a managed pi
+ *      install. Read-only.
+ *   4. `packages/server/src/pi-core-updater.ts`,
+ *      `packages/server/src/pi-core-checker.ts` — the `/api/pi-core/`
+ *      endpoint (standalone arm only) writes managed pi here. Hidden in
+ *      the Electron client UI per task 3.3.
+ *   5. `packages/electron/src/lib/doctor.ts` — advisory `rm -rf` hint
+ *      strings rendered from the detector output.
+ *
+ * Any NEW reference outside this allowlist must be questioned: it likely
+ * means runtime install is creeping back into the Electron arm.
+ *
+ * The lint walks `packages/electron/src/lib/`, `packages/server/src/`,
+ * and `packages/shared/src/` looking for the literal `.pi-dashboard`,
+ * then asserts every match maps to an allowlisted file.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..", "..", "..");
+
+// Paths are relative to REPO_ROOT, forward-slash normalized.
+// Each entry MUST be accompanied by a one-line rationale.
+const ALLOWLIST: ReadonlySet<string> = new Set([
+  // New module — only intentional consumer of the literal.
+  "packages/shared/src/legacy-managed-dir.ts",
+  // Read-only fallback probes for managed pi (standalone arm).
+  "packages/shared/src/managed-paths.ts",
+  "packages/shared/src/platform/binary-lookup.ts",
+  "packages/shared/src/platform/managed-node-path.ts",
+  "packages/shared/src/tool-registry/strategies.ts",
+  "packages/shared/src/tool-registry/definitions.ts",
+  "packages/shared/src/dashboard-paths.ts",
+  // Shared doctor advisory text and section keys.
+  "packages/shared/src/doctor-core.ts",
+  // Comment-only ref (Windows-path example).
+  "packages/shared/src/platform/node-spawn.ts",
+  // pi-core update path (standalone arm only; client UI hidden on Electron).
+  "packages/server/src/pi-core-updater.ts",
+  "packages/server/src/pi-core-checker.ts",
+  "packages/server/src/changelog-fs.ts",
+  // Server CLI: advisory log line wired to legacy-managed-dir detector.
+  "packages/server/src/cli.ts",
+  // Doctor route: shared-doctor MANAGED_DIR forwarder.
+  "packages/server/src/routes/doctor-routes.ts",
+  // Electron Doctor: advisory row text + MANAGED_DIR consumer for shared checks.
+  "packages/electron/src/lib/doctor.ts",
+  "packages/electron/src/lib/doctor-bridge-contract.ts",
+  "packages/electron/src/lib/managed-paths.ts",
+  // pi-core update checker — standalone arm only; Electron UI hidden.
+  "packages/electron/src/lib/update-checker.ts",
+  // Wizard mode marker — collapsed under Phase 6.1 (one-step welcome).
+  // Allowlisted pending the 6.1 collapse which migrates to ~/.pi/dashboard/.
+  "packages/electron/src/lib/wizard-state.ts",
+]);
+
+const SCAN_ROOTS = [
+  "packages/electron/src/lib",
+  "packages/server/src",
+  "packages/shared/src",
+];
+
+const SKIP_DIRS = new Set(["__tests__", "node_modules", "dist", "build", "test-support"]);
+
+function* walk(dir: string): Generator<string> {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      yield* walk(path.join(dir, e.name));
+    } else if (e.isFile() && /\.(ts|tsx|mts|cts|mjs|cjs|js)$/.test(e.name)) {
+      yield path.join(dir, e.name);
+    }
+  }
+}
+
+describe("no-managed-dir-reference lint", () => {
+  it("only allowlisted files reference `.pi-dashboard`", () => {
+    const offenders: string[] = [];
+
+    for (const root of SCAN_ROOTS) {
+      const absRoot = path.join(REPO_ROOT, root);
+      if (!fs.existsSync(absRoot)) continue;
+      for (const filePath of walk(absRoot)) {
+        const rel = path.relative(REPO_ROOT, filePath).split(path.sep).join("/");
+        if (ALLOWLIST.has(rel)) continue;
+
+        let content: string;
+        try {
+          content = fs.readFileSync(filePath, "utf-8");
+        } catch {
+          continue;
+        }
+        // Match the bare literal `.pi-dashboard`. The legacy-managed-dir
+        // module splits the literal across a `+` so this regex won't hit
+        // legitimate code there — but legacy-managed-dir is allowlisted
+        // anyway.
+        if (/\.pi-dashboard\b/.test(content)) {
+          offenders.push(rel);
+        }
+      }
+    }
+
+    expect(offenders, `Non-allowlisted files reference ".pi-dashboard":\n  ${offenders.join("\n  ")}\n\nUnder change: eliminate-electron-runtime-install (R3), no NEW code paths may read or write ~/.pi-dashboard/. If this reference is legitimate (e.g. a standalone-arm read), add the file to the ALLOWLIST in this test with a comment explaining why.`).toEqual([]);
+  });
+});

package/packages/shared/src/__tests__/no-pi-dashboard-version-jiti-gate.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Repo-lint: `packages/server/bin/pi-dashboard.mjs` MUST check
+ * `process.argv` for `--version` / `-v` / `version` BEFORE invoking any
+ * jiti resolution helper. Guards against regression of Bug B.
+ *
+ * See change: fix-electron-cold-launch-probe-cascade.
+ */
+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 wrapperPath = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "server",
+  "bin",
+  "pi-dashboard.mjs",
+);
+
+describe("pi-dashboard.mjs — --version short-circuit before jiti (Bug B regression guard)", () => {
+  it("checks argv for --version/-v/version BEFORE calling resolveJitiUrl()", () => {
+    const src = fs.readFileSync(wrapperPath, "utf-8");
+
+    const versionRegex = /process\.argv\[2\]|--version|"version"|"-v"/;
+    const jitiRegex = /resolveJitiUrl\(|resolveJiti\(/;
+
+    const versionIdx = src.search(versionRegex);
+    const jitiIdx = src.search(jitiRegex);
+
+    expect(versionIdx).toBeGreaterThan(-1);
+    expect(jitiIdx).toBeGreaterThan(-1);
+    expect(versionIdx).toBeLessThan(jitiIdx);
+
+    expect(src).toMatch(/pkg\.version|\.version/);
+    expect(src).toMatch(/package\.json/);
+  });
+});

package/packages/shared/src/__tests__/no-primitive-direct-import.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Repo-level invariant: plugin source files MUST NOT directly import the
+ * UI primitive COMPONENTS / HELPERS that are registered in the dashboard's
+ * UI primitive registry. They SHALL look those up via
+ * `useUiPrimitive(UI_PRIMITIVE_KEYS.<key>)` from
+ * `@blackbelt-technology/dashboard-plugin-runtime` instead.
+ *
+ * Hooks (`useMobile`, `useZoomPan`, `useMediaQuery`) and Phase-2 extension-ui
+ * slot consumers (`AgentMetricSlot`, `BreadcrumbSlot`, `GateSlot`, the
+ * `decorator-utils` helpers) are EXPLICITLY ALLOWED — hooks can't go through
+ * a registry (Rules of Hooks) and slot consumers are a different layer.
+ *
+ * This invariant exists because:
+ *
+ *   1. Without it, plugin authors will keep importing primitives directly
+ *      because it works in dev. The CI hazard (deep imports breaking when
+ *      tarballs are installed from npm) returns the next time a release
+ *      ships with broken plugins.
+ *
+ *   2. The registry pattern only delivers benefit when EVERY plugin uses it.
+ *      One plugin importing `MarkdownContent` directly drags the markdown
+ *      stack into its tarball; tree-shaking can't help across a published
+ *      package boundary.
+ *
+ * If this test fails, the suggested replacement is in the failure message:
+ *
+ *   import { useUiPrimitive } from "@blackbelt-technology/dashboard-plugin-runtime";
+ *   import { UI_PRIMITIVE_KEYS } from "@blackbelt-technology/pi-dashboard-shared/dashboard-plugin/ui-primitives.js";
+ *   ...
+ *   const MarkdownContent = useUiPrimitive(UI_PRIMITIVE_KEYS.markdownContent);
+ *
+ * See change: add-plugin-ui-primitive-registry.
+ */
+import { describe, expect, it } 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 REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
+
+/**
+ * Symbol names whose direct import from `pi-dashboard-client-utils/<X>` is
+ * forbidden in plugin source. Each maps to its registry key for the
+ * remediation message.
+ */
+const FORBIDDEN_PRIMITIVES: Record<string, { subpath: string; registryKey: string }> = {
+  AgentCardShell: { subpath: "AgentCardShell", registryKey: "UI_PRIMITIVE_KEYS.agentCard" },
+  MarkdownContent: { subpath: "MarkdownContent", registryKey: "UI_PRIMITIVE_KEYS.markdownContent" },
+  ConfirmDialog: { subpath: "ConfirmDialog", registryKey: "UI_PRIMITIVE_KEYS.confirmDialog" },
+  DialogPortal: { subpath: "DialogPortal", registryKey: "UI_PRIMITIVE_KEYS.dialogPortal" },
+  SearchableSelectDialog: {
+    subpath: "SearchableSelectDialog",
+    registryKey: "UI_PRIMITIVE_KEYS.searchableSelectDialog",
+  },
+  ZoomControls: { subpath: "ZoomControls", registryKey: "UI_PRIMITIVE_KEYS.zoomControls" },
+  formatTokens: { subpath: "agent-card-utils", registryKey: "UI_PRIMITIVE_KEYS.formatTokens" },
+  formatDuration: {
+    subpath: "agent-card-utils",
+    registryKey: "UI_PRIMITIVE_KEYS.formatDuration",
+  },
+};
+
+/**
+ * Recursively collect TypeScript source files under `dir`, skipping
+ * node_modules / dist / build artifacts and `__tests__` directories
+ * (test fixtures often reference primitives directly).
+ */
+function collectSourceFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const out: string[] = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "build") continue;
+      if (entry.name === "__tests__") continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!/\.(ts|tsx)$/.test(entry.name)) continue;
+      // Skip type-declaration-only files — they don't ship runtime code.
+      if (entry.name.endsWith(".d.ts")) continue;
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Scan a source file for forbidden primitive-import lines.
+ * Returns each violation with the symbol name, the imported subpath, and
+ * the line number for the failure message.
+ */
+interface Violation {
+  file: string;
+  line: number;
+  source: string;
+  symbol: string;
+  registryKey: string;
+}
+
+function scanFile(filePath: string): Violation[] {
+  const source = fs.readFileSync(filePath, "utf-8");
+  const violations: Violation[] = [];
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Match `import { ... } from "@blackbelt-technology/pi-dashboard-client-utils/<subpath>"`
+    // capturing the imported names list and the subpath.
+    const match = line.match(
+      /import\s+(?:type\s+)?\{\s*([^}]+)\s*\}\s+from\s+["']@blackbelt-technology\/pi-dashboard-client-utils\/([^"']+)["']/,
+    );
+    if (!match) continue;
+    const [, importNamesRaw, subpath] = match;
+    // Allow imports from extension-ui/* and useMobile/useZoomPan/useMediaQuery
+    // subpaths — these are not registered primitives.
+    if (subpath.startsWith("extension-ui/")) continue;
+    if (subpath === "useMobile" || subpath === "useZoomPan" || subpath === "useMediaQuery") continue;
+
+    // Parse the imported symbol names. Strip `type` modifiers, aliases, whitespace.
+    const importedNames = importNamesRaw
+      .split(",")
+      .map((n) => n.replace(/^\s*type\s+/, "").trim())
+      .map((n) => n.split(/\s+as\s+/)[0]!.trim())
+      .filter((n) => n.length > 0);
+
+    for (const name of importedNames) {
+      const banned = FORBIDDEN_PRIMITIVES[name];
+      if (!banned) continue;
+      violations.push({
+        file: path.relative(REPO_ROOT, filePath),
+        line: i + 1,
+        source: line.trim(),
+        symbol: name,
+        registryKey: banned.registryKey,
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Walk every plugin package source tree.
+ * Plugin packages are workspaces under `packages/` whose name ends in
+ * `-plugin`, plus `demo-plugin` (a fixture).
+ */
+function findPluginPackages(): string[] {
+  const packagesDir = path.join(REPO_ROOT, "packages");
+  if (!fs.existsSync(packagesDir)) return [];
+  return fs
+    .readdirSync(packagesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .filter((name) => name.endsWith("-plugin") || name === "demo-plugin")
+    .map((name) => path.join(packagesDir, name, "src"));
+}
+
+describe("no-primitive-direct-import (repo-lint)", () => {
+  it("plugin source files SHALL NOT directly import registered UI primitives", () => {
+    const pluginSrcDirs = findPluginPackages();
+    expect(pluginSrcDirs.length).toBeGreaterThan(0); // sanity: we found plugin packages
+
+    const allViolations: Violation[] = [];
+    for (const srcDir of pluginSrcDirs) {
+      for (const file of collectSourceFiles(srcDir)) {
+        allViolations.push(...scanFile(file));
+      }
+    }
+
+    if (allViolations.length > 0) {
+      const lines = allViolations.map(
+        (v) =>
+          `  ${v.file}:${v.line}\n    ${v.source}\n` +
+          `    Replace with: const ${v.symbol} = useUiPrimitive(${v.registryKey});`,
+      );
+      // SOFTENED to a warning during the intent-rendering migration window.
+      // Once flows-plugin (and similar) finishes migrating to server-side
+      // intent broadcasts, this should be re-tightened to forbid both
+      // direct primitive imports AND useUiPrimitive calls from plugin code.
+      // See change: adopt-server-driven-intent-rendering (section 25).
+      console.warn(
+        `[no-primitive-direct-import] WARN: ${allViolations.length} direct primitive import(s) in plugin source. (Lint softened during migration.)\n` +
+          lines.join("\n\n"),
+      );
+    }
+  });
+
+  // Self-test: assert the lint does what it says by scanning a synthetic violation.
+  it("flags a planted bad import in a fixture string", () => {
+    const fixtureSource = [
+      'import { MarkdownContent } from "@blackbelt-technology/pi-dashboard-client-utils/MarkdownContent";',
+      'import { useMobile } from "@blackbelt-technology/pi-dashboard-client-utils/useMobile";',
+    ].join("\n");
+    const tmp = path.join(REPO_ROOT, ".tmp-no-primitive-direct-import-fixture.tsx");
+    fs.writeFileSync(tmp, fixtureSource);
+    try {
+      const violations = scanFile(tmp);
+      expect(violations).toHaveLength(1);
+      expect(violations[0].symbol).toBe("MarkdownContent");
+      expect(violations[0].registryKey).toBe("UI_PRIMITIVE_KEYS.markdownContent");
+    } finally {
+      fs.unlinkSync(tmp);
+    }
+  });
+
+  // Self-test: hook imports + extension-ui imports + non-primitive symbols are allowed.
+  it("does NOT flag allowed imports", () => {
+    const fixtureSource = [
+      'import { useMobile } from "@blackbelt-technology/pi-dashboard-client-utils/useMobile";',
+      'import { useZoomPan } from "@blackbelt-technology/pi-dashboard-client-utils/useZoomPan";',
+      'import { useMediaQuery } from "@blackbelt-technology/pi-dashboard-client-utils/useMediaQuery";',
+      'import { GateSlot, aggregateGateState } from "@blackbelt-technology/pi-dashboard-client-utils/extension-ui/GateSlot";',
+      'import { BreadcrumbSlot } from "@blackbelt-technology/pi-dashboard-client-utils/extension-ui/BreadcrumbSlot";',
+      'import { AgentMetricSlot } from "@blackbelt-technology/pi-dashboard-client-utils/extension-ui/AgentMetricSlot";',
+    ].join("\n");
+    const tmp = path.join(REPO_ROOT, ".tmp-no-primitive-direct-import-allow-fixture.tsx");
+    fs.writeFileSync(tmp, fixtureSource);
+    try {
+      const violations = scanFile(tmp);
+      expect(violations).toHaveLength(0);
+    } finally {
+      fs.unlinkSync(tmp);
+    }
+  });
+});

package/packages/shared/src/__tests__/no-server-imports-in-resolver.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Repo-lint: `packages/shared/src/pi-package-resolver.ts` MUST only
+ * import from Node built-ins, relative paths inside `packages/shared/`,
+ * or the package's own self-reference (`@blackbelt-technology/pi-dashboard-shared`).
+ *
+ * Plugin bridges consume this resolver and can only depend on the
+ * shared package; any leak to `packages/server/`, `packages/client/`,
+ * `packages/electron/`, or another workspace package would silently
+ * break every non-server consumer.
+ *
+ * See change: add-shared-pi-package-resolver.
+ */
+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 resolverPath = path.resolve(__dirname, "..", "pi-package-resolver.ts");
+
+const IMPORT_RE = /^\s*import[^"']+["']([^"']+)["']/gm;
+
+function isAllowed(spec: string): boolean {
+  if (spec.startsWith("node:")) return true;
+  if (spec.startsWith("./") || spec.startsWith("../")) return true;
+  if (spec === "@blackbelt-technology/pi-dashboard-shared") return true;
+  if (spec.startsWith("@blackbelt-technology/pi-dashboard-shared/")) return true;
+  return false;
+}
+
+describe("pi-package-resolver — shared-only imports", () => {
+  it("only imports Node built-ins or shared-local paths", () => {
+    const src = fs.readFileSync(resolverPath, "utf-8");
+    const offenders: string[] = [];
+    let m: RegExpExecArray | null;
+    while ((m = IMPORT_RE.exec(src)) !== null) {
+      const spec = m[1];
+      if (!isAllowed(spec)) {
+        offenders.push(spec);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it("rejects an injected disallowed import in a synthetic source", () => {
+    // Sanity: verify the matcher actually catches violations. Build a
+    // synthetic source line and run the same check inline.
+    const synthetic = `import { foo } from "@blackbelt-technology/pi-dashboard-server/bar";\n`;
+    const matches = Array.from(synthetic.matchAll(IMPORT_RE)).map((m) => m[1]);
+    expect(matches).toEqual(["@blackbelt-technology/pi-dashboard-server/bar"]);
+    expect(matches.every(isAllowed)).toBe(false);
+  });
+});