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

package/packages/shared/src/__tests__/plugin-bridge-classify-source.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure tests for classifyBridgeSource — see change fix-pi-flows-end-to-end
+ * (Group 2, task 2.5).
+ */
+import { describe, it, expect } from "vitest";
+import { classifyBridgeSource } from "../plugin-bridge-register.js";
+
+describe("classifyBridgeSource", () => {
+  it("returns 'packages[]' when bridge path is in packages array (string form)", () => {
+    expect(
+      classifyBridgeSource({ packages: ["/abs/bridge.js"] }, "/abs/bridge.js"),
+    ).toBe("packages[]");
+  });
+
+  it("returns 'packages[]' for object-form package source", () => {
+    expect(
+      classifyBridgeSource(
+        { packages: [{ source: "/abs/bridge.js", extensions: ["foo"] }] },
+        "/abs/bridge.js",
+      ),
+    ).toBe("packages[]");
+  });
+
+  it("returns 'dashboardPluginBridges' when only the legacy key references it", () => {
+    expect(
+      classifyBridgeSource(
+        { dashboardPluginBridges: { "dashboard-demo": "/abs/bridge.js" } },
+        "/abs/bridge.js",
+      ),
+    ).toBe("dashboardPluginBridges");
+  });
+
+  it("packages[] wins over dashboardPluginBridges when both reference the same path", () => {
+    expect(
+      classifyBridgeSource(
+        {
+          packages: ["/abs/bridge.js"],
+          dashboardPluginBridges: { "dashboard-demo": "/abs/bridge.js" },
+        },
+        "/abs/bridge.js",
+      ),
+    ).toBe("packages[]");
+  });
+
+  it("returns 'none' when neither registry references the path", () => {
+    expect(
+      classifyBridgeSource(
+        { packages: ["/other"], dashboardPluginBridges: { "dashboard-other": "/y" } },
+        "/abs/bridge.js",
+      ),
+    ).toBe("none");
+  });
+
+  it("returns 'none' for empty settings", () => {
+    expect(classifyBridgeSource({}, "/abs/bridge.js")).toBe("none");
+  });
+
+  it("tolerates malformed settings (null / array / primitive)", () => {
+    expect(classifyBridgeSource(null, "/abs/bridge.js")).toBe("none");
+    expect(classifyBridgeSource([], "/abs/bridge.js")).toBe("none");
+    expect(classifyBridgeSource(42, "/abs/bridge.js")).toBe("none");
+    expect(classifyBridgeSource("string", "/abs/bridge.js")).toBe("none");
+  });
+
+  it("ignores non-matching packages entries", () => {
+    expect(
+      classifyBridgeSource(
+        { packages: ["/a", { source: "/b" }, { not_source: "/abs/bridge.js" }] },
+        "/abs/bridge.js",
+      ),
+    ).toBe("none");
+  });
+});

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

@@ -48,7 +48,10 @@ describe("bridge auto-register boot + disable lifecycle", () => {
     expect(Object.keys(managed)).toHaveLength(0);
   });
 
-  it("preserves user-owned packages array", () => {
+  it("preserves user-owned packages array and appends managed bridge", () => {
+    // Per change fix-pi-flows-end-to-end Group 1: dual-write appends the
+    // managed bridge to packages[] (with ownership marker) while leaving
+    // user entries untouched in original order.
     fs.mkdirSync(path.join(homedir, ".pi", "agent"), { recursive: true });
     fs.writeFileSync(
       settingsPath(),
@@ -58,15 +61,24 @@ describe("bridge auto-register boot + disable lifecycle", () => {
     );
     registerPluginBridge("demo", "/demo/bridge.js", { homedir });
     const settings = readSettings();
-    expect(settings.packages).toEqual(["/user/my-extension", "/user/another"]);
+    expect(settings.packages).toEqual([
+      "/user/my-extension",
+      "/user/another",
+      "/demo/bridge.js",
+    ]);
   });
 
   it("surfaces path-mismatch conflict without overwriting", () => {
-    registerPluginBridge("openspec", "/old/bridge.js", { homedir });
-    const result = registerPluginBridge("openspec", "/new/bridge.js", { homedir });
+    // On-disk path must exist for a real conflict (self-heal would otherwise
+    // silently replace — see add-plugin-activation-ui).
+    const oldPath = path.join(tmpDir, "old-bridge.js");
+    const newPath = path.join(tmpDir, "new-bridge.js");
+    fs.writeFileSync(oldPath, "// existing bridge");
+    registerPluginBridge("openspec", oldPath, { homedir });
+    const result = registerPluginBridge("openspec", newPath, { homedir });
     expect(result.type).toBe("conflict");
     // Original path preserved
     const managed = listManagedBridges({ homedir });
-    expect(managed["dashboard-openspec"]).toBe("/old/bridge.js");
+    expect(managed["dashboard-openspec"]).toBe(oldPath);
   });
 });

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

@@ -0,0 +1,233 @@
+/**
+ * Tests for the dual-write (packages[] + dashboardPluginBridges) and
+ * reconciliation behaviour added by change `fix-pi-flows-end-to-end`
+ * Group 1.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  registerPluginBridge,
+  deregisterPluginBridge,
+  reconcilePluginBridgePackages,
+  ensurePackageEntry,
+  removePackageEntry,
+  listManagedPackageOwnership,
+} from "../plugin-bridge-register.js";
+
+let tmpDir: string;
+let homedir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-bridge-pkg-test-"));
+  homedir = tmpDir;
+  delete process.env.PI_DASHBOARD_DISABLE_PLUGIN_BRIDGE_PACKAGES_WRITE;
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+  delete process.env.PI_DASHBOARD_DISABLE_PLUGIN_BRIDGE_PACKAGES_WRITE;
+});
+
+function settingsPath() {
+  return path.join(homedir, ".pi", "agent", "settings.json");
+}
+
+function readSettings(): Record<string, unknown> {
+  return JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+}
+
+function writeSettings(s: Record<string, unknown>) {
+  fs.mkdirSync(path.dirname(settingsPath()), { recursive: true });
+  fs.writeFileSync(settingsPath(), JSON.stringify(s, null, 2) + "\n");
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Pure helpers
+// ─────────────────────────────────────────────────────────────────────────
+
+describe("ensurePackageEntry / removePackageEntry (pure)", () => {
+  it("adds new entry and records ownership", () => {
+    const packages: unknown[] = [];
+    const ownership: Record<string, string> = {};
+    const added = ensurePackageEntry(packages, ownership, "/a", "dashboard-x");
+    expect(added).toBe(true);
+    expect(packages).toEqual(["/a"]);
+    expect(ownership).toEqual({ "/a": "dashboard-x" });
+  });
+
+  it("is idempotent (no-op when present)", () => {
+    const packages: unknown[] = ["/a"];
+    const ownership: Record<string, string> = { "/a": "dashboard-x" };
+    const added = ensurePackageEntry(packages, ownership, "/a", "dashboard-x");
+    expect(added).toBe(false);
+    expect(packages).toEqual(["/a"]);
+  });
+
+  it("records ownership for pre-existing user entry without duplicating", () => {
+    const packages: unknown[] = ["/a"]; // user added
+    const ownership: Record<string, string> = {};
+    const added = ensurePackageEntry(packages, ownership, "/a", "dashboard-x");
+    expect(added).toBe(false);
+    expect(packages).toEqual(["/a"]);
+    expect(ownership).toEqual({ "/a": "dashboard-x" });
+  });
+
+  it("removes only owned entries; leaves user entries", () => {
+    const packages: unknown[] = ["/user", "/a"];
+    const ownership: Record<string, string> = { "/a": "dashboard-x" };
+    const removed = removePackageEntry(packages, ownership, "dashboard-x");
+    expect(removed).toBe(true);
+    expect(packages).toEqual(["/user"]);
+    expect(ownership).toEqual({});
+  });
+
+  it("multi-owner round trip", () => {
+    const packages: unknown[] = [];
+    const ownership: Record<string, string> = {};
+    ensurePackageEntry(packages, ownership, "/a", "dashboard-x");
+    ensurePackageEntry(packages, ownership, "/b", "dashboard-y");
+    expect(packages).toEqual(["/a", "/b"]);
+    removePackageEntry(packages, ownership, "dashboard-x");
+    expect(packages).toEqual(["/b"]);
+    expect(ownership).toEqual({ "/b": "dashboard-y" });
+  });
+
+  it("handles object-form PackageSource entries", () => {
+    const packages: unknown[] = [{ source: "/a" }];
+    const ownership: Record<string, string> = {};
+    const added = ensurePackageEntry(packages, ownership, "/a", "dashboard-x");
+    expect(added).toBe(false);
+    expect(packages).toEqual([{ source: "/a" }]);
+    expect(ownership).toEqual({ "/a": "dashboard-x" });
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Dual-write end-to-end
+// ─────────────────────────────────────────────────────────────────────────
+
+describe("registerPluginBridge dual-write", () => {
+  it("writes both dashboardPluginBridges AND packages[] entries", () => {
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    const s = readSettings();
+    expect((s.dashboardPluginBridges as Record<string, string>)["dashboard-demo"]).toBe(
+      "/abs/bridge.js",
+    );
+    expect(s.packages).toContain("/abs/bridge.js");
+    expect(
+      (s._dashboardManagedPackages as Record<string, string>)["/abs/bridge.js"],
+    ).toBe("dashboard-demo");
+  });
+
+  it("env escape hatch skips packages[] write", () => {
+    process.env.PI_DASHBOARD_DISABLE_PLUGIN_BRIDGE_PACKAGES_WRITE = "1";
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    const s = readSettings();
+    expect((s.dashboardPluginBridges as Record<string, string>)["dashboard-demo"]).toBe(
+      "/abs/bridge.js",
+    );
+    expect(s.packages ?? []).not.toContain("/abs/bridge.js");
+  });
+
+  it("idempotent across repeated registration", () => {
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    const s = readSettings();
+    const pkgs = s.packages as unknown[];
+    expect(pkgs.filter((e) => e === "/abs/bridge.js")).toHaveLength(1);
+  });
+
+  it("preserves user-added packages entry on conflict-free re-register", () => {
+    writeSettings({ packages: ["/user/pkg"] });
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    const s = readSettings();
+    expect(s.packages).toEqual(["/user/pkg", "/abs/bridge.js"]);
+  });
+});
+
+describe("deregisterPluginBridge dual-remove", () => {
+  it("removes both dashboardPluginBridges AND packages[] entries; keeps user entries", () => {
+    writeSettings({ packages: ["/user/pkg"] });
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    deregisterPluginBridge("demo", { homedir });
+    const s = readSettings();
+    expect((s.dashboardPluginBridges as Record<string, string>)["dashboard-demo"]).toBeUndefined();
+    expect(s.packages).toEqual(["/user/pkg"]);
+    expect((s._dashboardManagedPackages as Record<string, string>)["/abs/bridge.js"]).toBeUndefined();
+  });
+
+  it("no-op when plugin never registered", () => {
+    writeSettings({ packages: ["/user/pkg"] });
+    deregisterPluginBridge("ghost", { homedir });
+    const s = readSettings();
+    expect(s.packages).toEqual(["/user/pkg"]);
+  });
+});
+
+describe("reconcilePluginBridgePackages", () => {
+  it("adds missing packages[] entry for pre-existing dashboardPluginBridges key", () => {
+    writeSettings({
+      dashboardPluginBridges: { "dashboard-demo": "/abs/bridge.js" },
+      packages: ["/user/pkg"],
+    });
+    const summary = reconcilePluginBridgePackages({ homedir });
+    expect(summary).toEqual([
+      { pluginId: "demo", bridgePath: "/abs/bridge.js", action: "added" },
+    ]);
+    const s = readSettings();
+    expect(s.packages).toContain("/abs/bridge.js");
+    expect(
+      (s._dashboardManagedPackages as Record<string, string>)["/abs/bridge.js"],
+    ).toBe("dashboard-demo");
+  });
+
+  it("is idempotent — second run produces no mutation", () => {
+    writeSettings({
+      dashboardPluginBridges: { "dashboard-demo": "/abs/bridge.js" },
+    });
+    reconcilePluginBridgePackages({ homedir });
+    const summary = reconcilePluginBridgePackages({ homedir });
+    expect(summary).toEqual([
+      { pluginId: "demo", bridgePath: "/abs/bridge.js", action: "already" },
+    ]);
+  });
+
+  it("env escape hatch produces empty summary and no writes", () => {
+    process.env.PI_DASHBOARD_DISABLE_PLUGIN_BRIDGE_PACKAGES_WRITE = "1";
+    writeSettings({
+      dashboardPluginBridges: { "dashboard-demo": "/abs/bridge.js" },
+    });
+    const summary = reconcilePluginBridgePackages({ homedir });
+    expect(summary).toEqual([]);
+    const s = readSettings();
+    expect(s.packages ?? []).not.toContain("/abs/bridge.js");
+  });
+
+  it("preserves user packages while reconciling multiple managed bridges", () => {
+    writeSettings({
+      dashboardPluginBridges: {
+        "dashboard-x": "/abs/x.js",
+        "dashboard-y": "/abs/y.js",
+      },
+      packages: ["/user/a", { source: "/user/b" }],
+    });
+    reconcilePluginBridgePackages({ homedir });
+    const s = readSettings();
+    expect(s.packages).toEqual(["/user/a", { source: "/user/b" }, "/abs/x.js", "/abs/y.js"]);
+  });
+});
+
+describe("listManagedPackageOwnership", () => {
+  it("returns empty map when nothing registered", () => {
+    expect(listManagedPackageOwnership({ homedir })).toEqual({});
+  });
+
+  it("returns ownership map after dual-write registration", () => {
+    registerPluginBridge("demo", "/abs/bridge.js", { homedir });
+    expect(listManagedPackageOwnership({ homedir })).toEqual({
+      "/abs/bridge.js": "dashboard-demo",
+    });
+  });
+});

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

@@ -44,21 +44,29 @@ describe("registerPluginBridge", () => {
   });
 
   it("returns conflict when entry exists with different path", () => {
-    registerPluginBridge("demo", "/old/bridge.js", { homedir });
-    const result = registerPluginBridge("demo", "/new/bridge.js", { homedir });
+    // The on-disk path must exist for a real conflict (otherwise the
+    // self-heal path silently replaces — see add-plugin-activation-ui).
+    const oldPath = path.join(tmpDir, "old-bridge.js");
+    const newPath = path.join(tmpDir, "new-bridge.js");
+    fs.writeFileSync(oldPath, "// existing bridge");
+    registerPluginBridge("demo", oldPath, { homedir });
+    const result = registerPluginBridge("demo", newPath, { homedir });
     expect(result.type).toBe("conflict");
     if (result.type === "conflict") {
-      expect(result.existingPath).toBe("/old/bridge.js");
-      expect(result.newPath).toBe("/new/bridge.js");
+      expect(result.existingPath).toBe(oldPath);
+      expect(result.newPath).toBe(newPath);
     }
     // Should not overwrite
     const s = readSettings();
     const managed = s.dashboardPluginBridges as Record<string, string>;
-    expect(managed["dashboard-demo"]).toBe("/old/bridge.js");
+    expect(managed["dashboard-demo"]).toBe(oldPath);
   });
 
-  it("never touches user-owned packages array", () => {
-    // Pre-populate settings with user packages
+  it("appends managed bridge to packages[] while preserving user-owned entries", () => {
+    // Per change fix-pi-flows-end-to-end Group 1: dual-write into packages[]
+    // is required (pi-coding-agent reads packages[], not dashboardPluginBridges).
+    // User entries MUST be preserved in original order; the managed bridge
+    // path MUST be appended and recorded in the ownership map.
     fs.mkdirSync(path.join(homedir, ".pi", "agent"), { recursive: true });
     fs.writeFileSync(
       settingsPath(),
@@ -67,8 +75,10 @@ describe("registerPluginBridge", () => {
 
     registerPluginBridge("demo", "/demo/bridge.js", { homedir });
     const s = readSettings();
-    const pkgs = s.packages as string[];
-    expect(pkgs).toEqual(["/user/extension1", "/user/extension2"]);
+    expect(s.packages).toEqual(["/user/extension1", "/user/extension2", "/demo/bridge.js"]);
+    expect((s._dashboardManagedPackages as Record<string, string>)["/demo/bridge.js"]).toBe(
+      "dashboard-demo",
+    );
   });
 });
 

package/packages/shared/src/__tests__/publish-workflow-contract.test.ts

@@ -1,6 +1,8 @@
 /**
  * Repo-level invariant: `.github/workflows/publish.yml`'s `electron` job
- * MUST `needs: [prepare, publish]` and MUST set `strategy.fail-fast: false`.
+ * MUST `needs: [prepare, publish]` AND MUST delegate to the reusable
+ * workflow `.github/workflows/_electron-build.yml`, which MUST itself set
+ * `strategy.fail-fast: false`.
  *
  * Why: the bundled-server step in the electron matrix runs `npm install`
  * against the live npm registry, which depends on `@blackbelt-technology/*`
@@ -12,14 +14,18 @@
  * other four matrix variants — losing diagnostic output and wasting runner
  * minutes.
  *
- * If this test fails, restore the two lines in `publish.yml`:
- *   electron:
- *     needs: [prepare, publish]
- *     strategy:
- *       fail-fast: false
- *       matrix: ...
+ * If this test fails, restore the contract in `publish.yml` + `_electron-build.yml`:
+ *   publish.yml:
+ *     electron:
+ *       needs: [prepare, publish]
+ *       uses: ./.github/workflows/_electron-build.yml
+ *   _electron-build.yml:
+ *     jobs:
+ *       build:
+ *         strategy:
+ *           fail-fast: false
  *
- * See change: publish-fix-macos.
+ * See changes: publish-fix-macos, add-ci-electron-on-demand-build.
  */
 import { describe, it, expect } from "vitest";
 import fs from "node:fs";
@@ -29,6 +35,18 @@ import url from "node:url";
 const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
 const WORKFLOW_PATH = path.join(REPO_ROOT, ".github", "workflows", "publish.yml");
+const REUSABLE_WORKFLOW_PATH = path.join(
+  REPO_ROOT,
+  ".github",
+  "workflows",
+  "_electron-build.yml",
+);
+const CI_ELECTRON_WORKFLOW_PATH = path.join(
+  REPO_ROOT,
+  ".github",
+  "workflows",
+  "ci-electron.yml",
+);
 
 /**
  * Extract the YAML body of a top-level job by name. Returns the lines
@@ -105,21 +123,108 @@ describe("publish.yml — electron job dependency-graph contract", () => {
     expect(names).toContain("publish");
   });
 
-  it("electron job's `strategy.fail-fast` is `false`", () => {
-    // Match `fail-fast: false` (any whitespace after the colon, but the
-    // value must be the literal `false` — not `False`, not absent).
-    const m = electronBlock.match(/^\s{6}fail-fast:\s*(\S+)\s*$/m);
+  it("electron job delegates to the reusable workflow via `uses:`", () => {
+    // After change add-ci-electron-on-demand-build, the electron job is a
+    // thin consumer of the shared workflow. The same definition serves
+    // both publish.yml and ci-electron.yml.
+    const m = electronBlock.match(
+      /^\s{4}uses:\s*\.\/\.github\/workflows\/_electron-build\.yml\s*$/m,
+    );
     if (!m) {
       throw new Error(
-        "electron job's `strategy.fail-fast` is absent — the GitHub Actions " +
-          "default of `true` would re-introduce the run-#34 cascade. " +
-          "Set `fail-fast: false`. See change: publish-fix-macos.\n" +
+        "electron job MUST be `uses: ./.github/workflows/_electron-build.yml`. " +
+          "The reusable workflow is the sole definition of the build matrix. " +
+          "See change: add-ci-electron-on-demand-build.\n" +
           "Job block was:\n" +
           electronBlock,
       );
     }
+  });
+});
+
+describe("_electron-build.yml — reusable workflow contract", () => {
+  const reusableYaml = fs.readFileSync(REUSABLE_WORKFLOW_PATH, "utf8");
+
+  it("sets `fail-fast: false` on the build job", () => {
+    // Without `fail-fast: false`, a single OS failure cascades and cancels the
+    // other matrix variants — losing diagnostic output and wasting runner
+    // minutes. Locked here because the assertion moved out of publish.yml
+    // in change add-ci-electron-on-demand-build (electron job is now a thin
+    // `uses:` shim). See change: publish-fix-macos.
+    const m = reusableYaml.match(/^\s+fail-fast:\s*(\S+)\s*$/m);
+    if (!m) {
+      throw new Error(
+        "_electron-build.yml `strategy.fail-fast` is absent — the GitHub Actions " +
+          "default of `true` would re-introduce the run-#34 cascade. " +
+          "Set `fail-fast: false` on jobs.build.strategy. See change: publish-fix-macos.",
+      );
+    }
     expect(m[1]).toBe("false");
   });
+
+  it("declares the input contract documented in design.md", () => {
+    // Inputs locked: version, ref, legs, source_only_bundle,
+    // artifact_retention_days, artifact_name_suffix. Adding inputs is
+    // safe; removing or renaming requires updating both callers
+    // (publish.yml + ci-electron.yml) plus the spec.
+    for (const key of [
+      "version",
+      "ref",
+      "legs",
+      "source_only_bundle",
+      "artifact_retention_days",
+    ]) {
+      const re = new RegExp(`^\\s+${key}:\\s*$`, "m");
+      if (!re.test(reusableYaml)) {
+        throw new Error(
+          `_electron-build.yml is missing required input '${key}'. ` +
+            "See change: add-ci-electron-on-demand-build (design.md Decision 2).",
+        );
+      }
+    }
+  });
+
+  it("contains a runnable-bundle assertion step (fix-ci-electron-runnable-bundles)", () => {
+    // Defence-in-depth gate: when `inputs.source_only_bundle == false`, the
+    // reusable workflow MUST verify that bundle-server.mjs produced a
+    // complete `resources/server/node_modules/@blackbelt-technology/
+    // pi-dashboard-server/src/cli.ts`. Without this, a regression in
+    // sync-versions.js or the bundle layout could silently ship a
+    // non-runnable artefact — the exact failure mode that motivated
+    // change fix-ci-electron-runnable-bundles. Match a permissive name
+    // regex so the step can be renamed without breaking the contract, as
+    // long as intent is preserved.
+    const stepNameRe = /^\s+-\s+name:\s*.*(runnable[-\s]bundle|cli\.ts.*exists).*/im;
+    if (!stepNameRe.test(reusableYaml)) {
+      throw new Error(
+        "_electron-build.yml is missing the runnable-bundle assertion step. " +
+          "Expected a step whose `name:` matches /runnable[- ]bundle|cli\\.ts.*exists/i. " +
+          "See change: fix-ci-electron-runnable-bundles.",
+      );
+    }
+  });
+
+  it("contains no forbidden side-effect actions (npm publish, gh-release, tag push)", () => {
+    // The reusable workflow MUST be a pure artifact producer. Publishing
+    // remains the sole responsibility of publish.yml's `publish` +
+    // `github-release` jobs. See change: add-ci-electron-on-demand-build
+    // (proposal.md "Safety lints" + spec ci-electron-on-demand-build).
+    const forbidden = [
+      /softprops\/action-gh-release/,
+      /actions\/create-release/,
+      /npm\s+publish/,
+      /git\s+push\s+origin\s+v/,
+    ];
+    for (const re of forbidden) {
+      if (re.test(reusableYaml)) {
+        throw new Error(
+          `_electron-build.yml contains forbidden action matching ${re}. ` +
+            "The reusable workflow MUST NOT publish or release. See change: " +
+            "add-ci-electron-on-demand-build.",
+        );
+      }
+    }
+  });
 });
 
 // ── Prerelease safety contract ───────────────────────────────────────────────────────
@@ -202,6 +307,40 @@ function parseJobSteps(jobBlock: string): Array<{ run: string }> {
   return steps;
 }
 
+describe("ci-electron.yml — runnable-bundle contract", () => {
+  // Pin the post-fix-ci-electron-runnable-bundles invariant: CI-dispatched
+  // Electron artefacts MUST ship with a complete `resources/server/
+  // node_modules/` tree so the unzipped installer is runnable on a user's
+  // desktop. The earlier value (`true`, from add-ci-electron-on-demand-build
+  // Decision 3) was invalidated by eliminate-electron-runtime-install's
+  // removal of every runtime install path. See change:
+  // fix-ci-electron-runnable-bundles.
+  const ciYaml = fs.readFileSync(CI_ELECTRON_WORKFLOW_PATH, "utf8");
+
+  it("build job passes `source_only_bundle: false` to the reusable workflow", () => {
+    // Match the key in any whitespace alignment, but the value MUST be
+    // the literal `false`. `true` would re-introduce the broken-on-unzip
+    // failure mode (BundledServerMissingError on cli.ts).
+    const m = ciYaml.match(/^\s+source_only_bundle:\s*(\S+)\s*$/m);
+    if (!m) {
+      throw new Error(
+        "ci-electron.yml does not pass `source_only_bundle:` to the reusable " +
+          "workflow. Expected `source_only_bundle: false`. See change: " +
+          "fix-ci-electron-runnable-bundles.",
+      );
+    }
+    if (m[1] !== "false") {
+      throw new Error(
+        `ci-electron.yml passes \`source_only_bundle: ${m[1]}\` — ` +
+          "expected `false`. Source-only bundles ship without " +
+          "`resources/server/node_modules/` and fail at launch with " +
+          "BundledServerMissingError. See change: fix-ci-electron-runnable-bundles.",
+      );
+    }
+    expect(m[1]).toBe("false");
+  });
+});
+
 describe("publish.yml — prepare job lockfile-regen contract", () => {
   const yaml = fs.readFileSync(WORKFLOW_PATH, "utf8");
   const prepareBlock = extractJobBlock(yaml, "prepare");