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

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

@@ -46,22 +46,45 @@ describe("shared bridge-register", () => {
     });
 
     it("returns null when extension dir does not exist", () => {
-      expect(findBundledExtension(tmpDir)).toBeNull();
+      // Disable Strategy 2 (node-resolver fallback) so we test Strategy 1 in isolation.
+      expect(findBundledExtension(tmpDir, { resolvePackage: () => null })).toBeNull();
     });
 
     it("returns null when no package.json in extension dir", () => {
       const extDir = path.join(tmpDir, "packages", "extension");
       fs.mkdirSync(extDir, { recursive: true });
       // No package.json
-      expect(findBundledExtension(tmpDir)).toBeNull();
+      expect(findBundledExtension(tmpDir, { resolvePackage: () => null })).toBeNull();
     });
 
     it("returns null for AppImage temp mount paths", () => {
-      // We can't easily create a /tmp/.mount_ path, but we can verify
-      // the function handles it via the string check
       const mockBase = "/tmp/.mount_PI1234/resources/server";
-      // findBundledExtension will check existsSync which returns false for this
-      expect(findBundledExtension(mockBase)).toBeNull();
+      // Even with a resolvable node-modules extension, if that resolved path is
+      // itself under /tmp/.mount_* it must be rejected (tested separately below).
+      expect(findBundledExtension(mockBase, { resolvePackage: () => null })).toBeNull();
+    });
+
+    it("Strategy 2 — falls back to require.resolve when baseDir has no packages/extension", () => {
+      // Simulate `npm i -g pi-dashboard` layout: baseDir is the server
+      // package root and contains no `packages/extension/`, but the
+      // extension is resolvable as a runtime dep via node_modules.
+      const fakeExtDir = path.join(tmpDir, "fake-node_modules", "pi-dashboard-extension");
+      fs.mkdirSync(fakeExtDir, { recursive: true });
+      fs.writeFileSync(path.join(fakeExtDir, "package.json"), '{"name":"fake"}');
+      const resolved = findBundledExtension(tmpDir, {
+        resolvePackage: () => path.join(fakeExtDir, "package.json"),
+      });
+      expect(resolved).toBe(fakeExtDir);
+    });
+
+    it("Strategy 2 — rejects AppImage-mount paths even when resolvable", () => {
+      // A /tmp/.mount_* path must be rejected regardless of which strategy
+      // surfaced it.
+      const appImageExtDir = "/tmp/.mount_PI1234/node_modules/@blackbelt-technology/pi-dashboard-extension";
+      const resolved = findBundledExtension(tmpDir, {
+        resolvePackage: () => path.join(appImageExtDir, "package.json"),
+      });
+      expect(resolved).toBeNull();
     });
   });
 

package/packages/shared/src/__tests__/config-openspec.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { loadConfig, DEFAULT_OPENSPEC_POLL } from "../config.js";
+
+describe("loadConfig — openspec poll block", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-config-openspec-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("applies all defaults when openspec block is missing", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+    const cfg = loadConfig();
+    expect(cfg.openspec).toEqual(DEFAULT_OPENSPEC_POLL);
+    expect(cfg.openspec.pollIntervalSeconds).toBe(30);
+    expect(cfg.openspec.maxConcurrentSpawns).toBe(3);
+    expect(cfg.openspec.changeDetection).toBe("mtime");
+    expect(cfg.openspec.jitterSeconds).toBe(5);
+  });
+
+  it("accepts valid values", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "always", jitterSeconds: 10 },
+    }));
+    const cfg = loadConfig();
+    expect(cfg.openspec.pollIntervalSeconds).toBe(60);
+    expect(cfg.openspec.maxConcurrentSpawns).toBe(5);
+    expect(cfg.openspec.changeDetection).toBe("always");
+    expect(cfg.openspec.jitterSeconds).toBe(10);
+  });
+
+  it("clamps pollIntervalSeconds below the minimum (5)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { pollIntervalSeconds: 1 } }));
+    expect(loadConfig().openspec.pollIntervalSeconds).toBe(5);
+  });
+
+  it("clamps pollIntervalSeconds above the maximum (3600)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { pollIntervalSeconds: 999_999 } }));
+    expect(loadConfig().openspec.pollIntervalSeconds).toBe(3600);
+  });
+
+  it("clamps maxConcurrentSpawns to [1, 16]", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { maxConcurrentSpawns: 0 } }));
+    expect(loadConfig().openspec.maxConcurrentSpawns).toBe(1);
+
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { maxConcurrentSpawns: 100 } }));
+    expect(loadConfig().openspec.maxConcurrentSpawns).toBe(16);
+  });
+
+  it("clamps jitterSeconds to [0, 60]", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { jitterSeconds: -5 } }));
+    expect(loadConfig().openspec.jitterSeconds).toBe(0);
+
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { jitterSeconds: 120 } }));
+    expect(loadConfig().openspec.jitterSeconds).toBe(60);
+  });
+
+  it("falls back to 'mtime' when changeDetection is unknown", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ openspec: { changeDetection: "bogus" } }));
+    expect(loadConfig().openspec.changeDetection).toBe("mtime");
+  });
+
+  it("coerces non-number values to defaults", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: "thirty", maxConcurrentSpawns: null, jitterSeconds: undefined },
+    }));
+    const cfg = loadConfig();
+    expect(cfg.openspec.pollIntervalSeconds).toBe(30);
+    expect(cfg.openspec.maxConcurrentSpawns).toBe(3);
+    expect(cfg.openspec.jitterSeconds).toBe(5);
+  });
+
+  it("ignores unknown keys in the openspec block", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: 45, nonsenseField: "ignored", another: 42 },
+    }));
+    const cfg = loadConfig();
+    expect(cfg.openspec.pollIntervalSeconds).toBe(45);
+    expect((cfg.openspec as any).nonsenseField).toBeUndefined();
+    expect((cfg.openspec as any).another).toBeUndefined();
+  });
+
+  it("is stable through round-trip (load → stringify → load)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      openspec: { pollIntervalSeconds: 90, maxConcurrentSpawns: 4, changeDetection: "always", jitterSeconds: 12 },
+    }));
+    const first = loadConfig();
+    fs.writeFileSync(configFile, JSON.stringify(first));
+    const second = loadConfig();
+    expect(second.openspec).toEqual(first.openspec);
+  });
+});

package/packages/shared/src/__tests__/config.test.ts

@@ -304,6 +304,62 @@ describe("loadConfig", () => {
     const config = loadConfig();
     expect(config.electronMode).toBe(false);
   });
+
+  // ── fix-trusted-networks-no-oauth regression tests ──────────────────
+  // These assert that auth.bypassHosts and auth.bypassUrls are honored
+  // at load time EVEN WHEN auth.providers is empty or absent. Before the
+  // fix, parseAuthConfig returned undefined whenever providers was empty,
+  // nuking bypassHosts before the resolvedTrustedNetworks merge could
+  // read it. See openspec/changes/fix-trusted-networks-no-oauth/.
+
+  it("should honor auth.bypassHosts when providers is {} (task 1.1)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { providers: {}, bypassHosts: ["192.168.1.0/24"] },
+    }));
+    const config = loadConfig();
+    expect(config.auth).toBeDefined();
+    expect(config.auth!.bypassHosts).toEqual(["192.168.1.0/24"]);
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+  });
+
+  it("should honor auth.bypassHosts when no providers key at all (task 1.2)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { bypassHosts: ["10.0.0.0/8"] },
+    }));
+    const config = loadConfig();
+    expect(config.auth).toBeDefined();
+    expect(config.auth!.bypassHosts).toEqual(["10.0.0.0/8"]);
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
+  it("should honor auth.bypassUrls when providers is {} (task 1.3)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { providers: {}, bypassUrls: ["/webhooks/"] },
+    }));
+    const config = loadConfig();
+    expect(config.auth).toBeDefined();
+    expect(config.auth!.bypassUrls).toEqual(["/webhooks/"]);
+  });
+
+  it("should return auth undefined when providers={} and all bypass arrays are empty (task 1.4 boundary)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      auth: { providers: {}, bypassHosts: [], bypassUrls: [] },
+    }));
+    const config = loadConfig();
+    // Truly empty auth → still undefined (boundary preserved)
+    expect(config.auth).toBeUndefined();
+    expect(config.resolvedTrustedNetworks).toEqual([]);
+  });
+
+  it("should merge top-level trustedNetworks with bypassHosts when no providers", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24"],
+      auth: { providers: {}, bypassHosts: ["10.0.0.0/8"] },
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
 });
 
 describe("ensureConfig", () => {

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

@@ -0,0 +1,243 @@
+/**
+ * Tests for platform/detached-spawn.ts primitives.
+ *
+ * Uses real `node -e` subprocess fixtures (no mocking) so we can exercise
+ * the actual Node spawn path with libuv's detached semantics on whatever
+ * OS the test runs on.
+ *
+ * All platform-dependent helpers take an explicit `platform` argument so
+ * tests can exercise both branches. We never mutate `process.platform`
+ * and never `vi.mock`.
+ */
+import { describe, it, expect } from "vitest";
+import { openSync, closeSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnDetached, waitForNoCrash, waitForReady } from "../platform/detached-spawn.js";
+
+function tmpLog(): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "dspawn-"));
+  return path.join(dir, "out.log");
+}
+
+describe("spawnDetached", () => {
+  it("spawns a real detached child with correct defaults", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 300)"],
+    });
+    expect(r.ok).toBe(true);
+    expect(r.pid).toBeTypeOf("number");
+    expect(r.process).toBeDefined();
+    // clean up
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("returns ok:false with error when cmd does not exist", async () => {
+    const r = await spawnDetached({
+      cmd: "/definitely/not/a/real/binary/nope.exe",
+      args: [],
+    });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBeTruthy();
+  });
+
+  it("redirects stderr to logFd when provided", async () => {
+    const logPath = tmpLog();
+    const fd = openSync(logPath, "a");
+    try {
+      const r = await spawnDetached({
+        cmd: process.execPath,
+        args: ["-e", "process.stderr.write('BOOM'); setTimeout(() => process.exit(0), 100)"],
+        logFd: fd,
+      });
+      expect(r.ok).toBe(true);
+      await new Promise((res) => r.process!.once("exit", res));
+    } finally {
+      try { closeSync(fd); } catch { /* ignore */ }
+    }
+    const content = readFileSync(logPath, "utf-8");
+    expect(content).toContain("BOOM");
+    rmSync(path.dirname(logPath), { recursive: true, force: true });
+  });
+
+  it("does not keep parent event loop alive (unref)", async () => {
+    // Can only check behaviour indirectly: the returned pid/process exist
+    // and the child is running detached. Lifecycle survival is covered by
+    // Node's own libuv tests; we assert we didn't throw.
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  // ── detach option ────────────────────────────────────────────────────────
+  //
+  // Behaviour of `detach` can't be directly observed at the Node level
+  // (libuv's UV_PROCESS_DETACHED flag + setpgid/JobObject are internal).
+  // These tests verify the OPTION is accepted and does not break spawn;
+  // lifecycle semantics are exercised in the integration smoke tests
+  // (phase 2.10 manual Windows check).
+
+  it("accepts detach: true (default behaviour, unchanged)", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+      detach: true,
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("accepts detach: false without breaking spawn", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+      detach: false,
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("accepts detach: undefined (implicit default)", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 100)"],
+      // detach is deliberately omitted
+    });
+    expect(r.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+});
+
+describe("waitForNoCrash", () => {
+  it("returns ok:true when child outlives the window", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 1000)"],
+    });
+    expect(r.ok).toBe(true);
+    const gate = await waitForNoCrash({ child: r.process!, windowMs: 150 });
+    expect(gate.ok).toBe(true);
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+
+  it("returns ok:false with exitCode when child exits early", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "process.exit(7)"],
+    });
+    expect(r.ok).toBe(true);
+    const gate = await waitForNoCrash({ child: r.process!, windowMs: 1000 });
+    expect(gate.ok).toBe(false);
+    expect(gate.exitCode).toBe(7);
+  });
+
+  it("respects a small windowMs and does not hang on live children", async () => {
+    const r = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(0), 5000)"],
+    });
+    expect(r.ok).toBe(true);
+    const start = Date.now();
+    const gate = await waitForNoCrash({ child: r.process!, windowMs: 100 });
+    const elapsed = Date.now() - start;
+    expect(gate.ok).toBe(true);
+    expect(elapsed).toBeLessThan(500);
+    r.process!.kill();
+    await new Promise((res) => r.process!.once("exit", res));
+  });
+});
+
+describe("waitForReady", () => {
+  it("returns ok:true when probe succeeds", async () => {
+    const r = await waitForReady({
+      probe: async () => true,
+      deadlineMs: 1000,
+      pollIntervalMs: 50,
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  it("returns ok:false with 'timeout' when probe never succeeds", async () => {
+    const r = await waitForReady({
+      probe: async () => false,
+      deadlineMs: 200,
+      pollIntervalMs: 50,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("timeout");
+  });
+
+  it("short-circuits on child error event", async () => {
+    // Spawn a nonexistent path via spawnDetached — triggers error event.
+    const bad = await spawnDetached({
+      cmd: "/does/not/exist/XYZQQ",
+      args: [],
+    });
+    // bad.process may or may not exist depending on how Node surfaced the
+    // error. If it does, we can observe the short-circuit; if not, skip
+    // this specific assertion. Either way, waitForReady must not hang.
+    if (bad.process) {
+      const start = Date.now();
+      const r = await waitForReady({
+        probe: async () => false,
+        deadlineMs: 5000,
+        pollIntervalMs: 500,
+        child: bad.process,
+      });
+      const elapsed = Date.now() - start;
+      expect(r.ok).toBe(false);
+      expect(elapsed).toBeLessThan(5000);
+    }
+  });
+
+  it("waits indefinitely when deadlineMs is undefined (succeeds eventually)", async () => {
+    let calls = 0;
+    const start = Date.now();
+    const r = await waitForReady({
+      probe: async () => ++calls >= 5,
+      // deadlineMs intentionally omitted
+      pollIntervalMs: 30,
+    });
+    const elapsed = Date.now() - start;
+    expect(r.ok).toBe(true);
+    expect(calls).toBeGreaterThanOrEqual(5);
+    // ~5 polls at 30ms interval ≈ 120–180ms. Just ensure we're not
+    // short-circuiting suspiciously fast or hanging absurdly long.
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  it("waits indefinitely until child crashes (no deadline, child-exit wins)", async () => {
+    // Spawn a short-lived child that exits non-zero after ~200ms.
+    const bad = await spawnDetached({
+      cmd: process.execPath,
+      args: ["-e", "setTimeout(() => process.exit(1), 200)"],
+    });
+    expect(bad.ok).toBe(true);
+    const start = Date.now();
+    const r = await waitForReady({
+      probe: async () => false, // never ready
+      // deadlineMs intentionally omitted — relies on child-exit
+      pollIntervalMs: 50,
+      child: bad.process!,
+    });
+    const elapsed = Date.now() - start;
+    expect(r.ok).toBe(false);
+    expect(r.error).toMatch(/child exited/);
+    expect(elapsed).toBeLessThan(2000); // short-circuited, not stuck
+  });
+
+  it("polls at pollIntervalMs until probe flips", async () => {
+    let calls = 0;
+    const r = await waitForReady({
+      probe: async () => ++calls >= 3,
+      deadlineMs: 2000,
+      pollIntervalMs: 50,
+    });
+    expect(r.ok).toBe(true);
+    expect(calls).toBeGreaterThanOrEqual(3);
+  });
+});

package/packages/shared/src/__tests__/managed-paths.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for `managed-paths.ts` getters.
+ *
+ * The constants (MANAGED_DIR, MANAGED_BIN, PI_SETTINGS_PATH) reflect
+ * the live environment at module-load time — those are covered by
+ * implicit use throughout the codebase. These tests pin the
+ * getter-with-override path used by the bootstrap harness and by
+ * future tests/proposals that need HOME injection.
+ */
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  MANAGED_BIN,
+  MANAGED_DIR,
+  PI_SETTINGS_PATH,
+  getManagedBin,
+  getManagedDir,
+  getPiSettingsPath,
+} from "../managed-paths.js";
+
+describe("managed-paths getters", () => {
+  it("getManagedDir() with no arg matches live MANAGED_DIR", () => {
+    expect(getManagedDir()).toBe(MANAGED_DIR);
+    expect(getManagedDir()).toBe(path.join(os.homedir(), ".pi-dashboard"));
+  });
+
+  it("getManagedBin() with no arg matches live MANAGED_BIN", () => {
+    expect(getManagedBin()).toBe(MANAGED_BIN);
+  });
+
+  it("getPiSettingsPath() with no arg matches live PI_SETTINGS_PATH", () => {
+    expect(getPiSettingsPath()).toBe(PI_SETTINGS_PATH);
+  });
+
+  it("getManagedDir({ homedir }) uses the override", () => {
+    expect(getManagedDir({ homedir: "/fake/home" })).toBe(
+      path.join("/fake/home", ".pi-dashboard"),
+    );
+  });
+
+  it("getManagedBin({ homedir }) composes from override", () => {
+    expect(getManagedBin({ homedir: "/fake/home" })).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node_modules", ".bin"),
+    );
+  });
+
+  it("getPiSettingsPath({ homedir }) uses the override", () => {
+    expect(getPiSettingsPath({ homedir: "/fake/home" })).toBe(
+      path.join("/fake/home", ".pi", "agent", "settings.json"),
+    );
+  });
+
+  it("override-less getManagedDir and live MANAGED_DIR constant are in sync", () => {
+    // Sanity: if someone accidentally drifts the constant from the
+    // getter default, this catches it.
+    expect(getManagedDir()).toEqual(MANAGED_DIR);
+    expect(getManagedBin()).toEqual(MANAGED_BIN);
+  });
+});

package/packages/shared/src/__tests__/no-direct-child-process.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Repo-level invariant: `node:child_process` MUST NOT be imported directly
+ * outside `packages/shared/src/platform/exec.ts` (and, once added,
+ * `packages/shared/src/platform/runner.ts`). All subprocess execution goes
+ * through the safe wrappers so `windowsHide: true` and other defaults are
+ * uniform.
+ *
+ * If this test fails, migrate the offending file's import to:
+ *   import { ... } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/** Files allowed to import from node:child_process directly. */
+const ALLOWLIST: readonly string[] = [
+  "packages/shared/src/platform/exec.ts",
+  "packages/shared/src/platform/runner.ts",
+  // Platform primitives that legitimately own the raw child_process
+  // APIs (Windows detached-spawn + cross-platform subprocess adapter).
+  // See change: consolidate-windows-spawn-and-platform-handlers.
+  "packages/shared/src/platform/detached-spawn.ts",
+  "packages/shared/src/platform/subprocess-adapter.ts",
+];
+
+/**
+ * Regex catches any textual reference to the `node:child_process` module:
+ *   - import X from "node:child_process"
+ *   - import { X } from 'node:child_process'
+ *   - require("node:child_process")
+ *   - const X = await import("node:child_process")
+ *
+ * We intentionally match the `node:` prefix strictly — this codebase uses
+ * ESM node-protocol imports everywhere, and the bare `child_process`
+ * alias is already absent.
+ */
+const CHILD_PROCESS_IMPORT_RE = /(?:from\s+|require\s*\(\s*|import\s*\(\s*)["']node:child_process["']/;
+
+/**
+ * Per-line opt-out marker. Use for embedded scripts (e.g. `node -e` orchestrators
+ * or Electron renderer bootstrap strings) where the `require("node:child_process")`
+ * is source text that runs in a separate Node process, not an import by the
+ * host module. Add this comment on the same line as the allowed usage:
+ *   const { spawn } = require("node:child_process"); // ban:child_process-ok
+ */
+const OPT_OUT_MARKER = "ban:child_process-ok";
+
+/** Recursively walk a directory, yielding all .ts / .tsx files. */
+async function* walk(dir: string): AsyncGenerator<string> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip nested node_modules, dist, and test directories
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "__tests__") continue;
+      yield* walk(full);
+    } else if (entry.isFile() && /\.(ts|tsx|mts|cts)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+describe("no direct node:child_process imports outside platform/exec.ts", () => {
+  it("only allowlisted files import node:child_process", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const packagesDir = path.resolve(repoRoot, "packages");
+
+    const violations: Array<{ file: string; line: number; text: string }> = [];
+    const allowSet = new Set(
+      ALLOWLIST.map((p) => path.resolve(repoRoot, p).replace(/\\/g, "/")),
+    );
+
+    for (const pkg of await fs.readdir(packagesDir, { withFileTypes: true })) {
+      if (!pkg.isDirectory()) continue;
+      const srcDir = path.join(packagesDir, pkg.name, "src");
+      try {
+        await fs.access(srcDir);
+      } catch {
+        continue; // package has no src/
+      }
+      for await (const file of walk(srcDir)) {
+        const normalized = file.replace(/\\/g, "/");
+        if (allowSet.has(normalized)) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, idx) => {
+          if (!CHILD_PROCESS_IMPORT_RE.test(line)) return;
+          if (line.includes(OPT_OUT_MARKER)) return;
+          violations.push({ file: path.relative(repoRoot, file), line: idx + 1, text: line.trim() });
+        });
+      }
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Direct node:child_process imports found outside the allowlist.\n` +
+        `Migrate each to:\n` +
+        `  import { ... } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations
+          .map((v) => `  ${v.file}:${v.line}  ${v.text}`)
+          .join("\n");
+      // Use a plain expect to surface the full diff in the test output.
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});