@bridge_gpt/mcp-server 0.2.34 → 0.2.36

package/build/run-unit-tests-launcher.js

@@ -0,0 +1,257 @@
+/**
+ * BAPI-683 — bounded, cross-platform launcher for the MCP server's compiled
+ * `node:test` suite.
+ *
+ * The previous `scripts.test` invocation enumerated every compiled test file
+ * as an explicit `node --test` command-line argument. Windows' CreateProcess
+ * command-line length limit (~8191 chars) made that argv too long once the
+ * suite grew past ~200 files (`The command line is too long.`, exit 1, before
+ * any test ran) — Linux/macOS have a much larger limit, so the same script
+ * kept passing there. This module discovers compiled test files at runtime
+ * and spawns them in size-bounded batches instead of expanding them ahead of
+ * time in package.json, so no single child invocation can approach the
+ * Windows ceiling regardless of how many test files exist.
+ *
+ * `scripts/run-unit-tests.js` is the thin CLI entrypoint that imports this
+ * compiled module; the logic lives here (under src/, built by tsc) so it can
+ * be unit-tested with node:test like every other module in this package.
+ */
+import { readdirSync } from "fs";
+import { spawnSync } from "child_process";
+import path from "path";
+const DEFAULT_BUILD_DIR = "build";
+// The Windows CreateProcess command-line limit is ~8191 characters. This
+// budget stays well under it (accounting for execPath + node options +
+// separators) so a single batch can never approach the real ceiling even on a
+// longer install path. Kept OS-independent so batching is deterministic and
+// stable across every CI runner and locally.
+export const MAX_COMMAND_LENGTH = 6000;
+// Explicit manifest: only tests that call node:test's `mock.module()` API
+// need --experimental-test-module-mocks. Everything else discovered under
+// build/ is eligible for the "normal" group automatically — new tests do NOT
+// need to be registered anywhere else. Add an entry here only when a new test
+// needs module mocking.
+export const MODULE_MOCK_MANIFEST = [
+    "build/attachment-download.test.js",
+    "build/attachment-upload.test.js",
+    "build/automation-progress.test.js",
+    "build/conductor/cli-git-hooks.test.js",
+    "build/conductor/cli.test.js",
+    "build/conductor/git-inspection.test.js",
+    "build/conductor/paths.test.js",
+    "build/conductor/pr-ci-producer-emit-seam.test.js",
+    "build/conductor/security-regressions.test.js",
+    "build/conductor/store-lifecycle.test.js",
+    "build/conductor/store-queries.test.js",
+    "build/conductor/tools-done-gate.test.js",
+    "build/conductor/tools.test.js",
+    "build/connect-github-api.test.js",
+    "build/connect-github-dispatch.static.test.js",
+    "build/connect-github-handoff.test.js",
+    "build/connect-github.test.js",
+    "build/council-wait-recovery.test.js",
+    "build/index-artifacts.test.js",
+    "build/index-brainstorm-filenames.test.js",
+    "build/index-generate-decision-page.integration.test.js",
+    "build/index-generate-decision-page.test.js",
+    "build/index-heavy-read-truncation.test.js",
+    "build/index-output-path.test.js",
+    "build/index.review-rounds.test.js",
+    "build/recovery-formatting.test.js",
+    "build/sfcc/client.test.js",
+    "build/sfcc/permissions.test.js",
+    "build/sfcc/reads-custom-object-def.test.js",
+    "build/sfcc/reads-site-preference.test.js",
+    "build/sfcc/reads-system-object.test.js",
+    "build/sfcc/register.test.js",
+    "build/sfcc/setup-status.test.js",
+    "build/sfcc/tool-wrapper.test.js",
+    "build/sfcc/writes-custom-object-def.test.js",
+    "build/sfcc/writes-site-preference.test.js",
+    "build/sfcc/writes-system-object.test.js",
+    "build/ticket-wait-recovery.test.js",
+    "build/visual-diff.attachment-adapter.test.js",
+    "build/visual-diff.registration.test.js",
+    "build/wait-for-result.test.js",
+];
+// Files that must run as their own single-file `node --test --test-force-exit`
+// invocation instead of joining a multi-file batch. --test-force-exit makes
+// the runner exit before it finishes aggregating per-subprocess summaries, so
+// a multi-file batch run with it reports a nondeterministic (undercounted)
+// test tally — failures still surface and still set exit 1, but the count
+// cannot be trusted as a completeness signal. Batched invocations therefore
+// run WITHOUT the flag; only the files listed here get it, each alone, where
+// the tally stays exact. build/secret-safety.test.js is quarantined because it
+// leaks a handle that holds the event loop ~60s after its tests finish (they
+// run in ~147ms). Do NOT add --test-force-exit to batched invocations, and do
+// NOT remove a file from this quarantine, until its underlying handle leak is
+// fixed.
+export const FORCE_EXIT_QUARANTINE = ["build/secret-safety.test.js"];
+// build/integration/** is the separately-invoked MCP_INTEGRATION=1 suite (run
+// via `npm run test:integration`) plus the packaged-CLI smoke test (`npm run
+// test:smoke`) — neither runs as part of `npm test`. `measure-tools.test.js`
+// is the one file under that directory that has always run as part of the
+// normal unit suite.
+const INTEGRATION_DIR_PREFIX = "build/integration/";
+const INTEGRATION_DIR_ALLOWLIST = new Set(["build/integration/measure-tools.test.js"]);
+// Pre-existing compiled test files that were not wired into ANY script before
+// this launcher existed (discovered while building it). BAPI-683 preserves
+// the exact current running test set rather than silently picking these up —
+// see docs/BAPI-683-mcp-ci-windows-npm-test-launcher.md for the follow-up.
+const KNOWN_UNREGISTERED_ORPHANS = new Set([
+    "build/conductor/conductor-runtime.integration.test.js",
+    "build/sfcc/register-site-preference.integration.test.js",
+]);
+/** Recursively lists compiled `*.test.js` files under `<root>/<buildDir>`, sorted and package-relative. */
+export function discoverTestFiles(options) {
+    const { root, buildDir = DEFAULT_BUILD_DIR, fsImpl = { readdirSync } } = options;
+    const absoluteBuildDir = path.join(root, buildDir);
+    const results = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fsImpl.readdirSync(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.name.endsWith(".test.js")) {
+                results.push(path.relative(root, full).split(path.sep).join("/"));
+            }
+        }
+    };
+    walk(absoluteBuildDir);
+    results.sort();
+    return results;
+}
+/** Throws if the module-mock or force-exit-quarantine manifest has drifted from the discovered build output. */
+export function validateManifest(discovered) {
+    const discoveredSet = new Set(discovered);
+    const seen = new Set();
+    for (const entry of MODULE_MOCK_MANIFEST) {
+        if (seen.has(entry)) {
+            throw new Error(`run-unit-tests: duplicate module-mock manifest entry: ${entry}`);
+        }
+        seen.add(entry);
+        if (!discoveredSet.has(entry)) {
+            throw new Error(`run-unit-tests: module-mock manifest entry not found in build output: ${entry} ` +
+                `(rebuild with 'npm run build', or remove it from MODULE_MOCK_MANIFEST if the file was deleted/renamed)`);
+        }
+    }
+    for (const entry of FORCE_EXIT_QUARANTINE) {
+        if (seen.has(entry)) {
+            throw new Error(`run-unit-tests: quarantine entry duplicated or also present in the module-mock manifest: ${entry}`);
+        }
+        seen.add(entry);
+        if (!discoveredSet.has(entry)) {
+            throw new Error(`run-unit-tests: force-exit quarantine entry not found in build output: ${entry} ` +
+                `(rebuild with 'npm run build', or remove it from FORCE_EXIT_QUARANTINE if the file was deleted/renamed)`);
+        }
+    }
+}
+/** Selects and validates the requested group's file list from the discovered inventory. */
+export function selectTestGroup(mode, discovered) {
+    if (mode !== "normal" && mode !== "module-mocks") {
+        throw new Error(`run-unit-tests: unknown group "${mode}" (expected "normal" or "module-mocks")`);
+    }
+    validateManifest(discovered);
+    const moduleMockSet = new Set(MODULE_MOCK_MANIFEST);
+    const normal = discovered.filter((file) => {
+        if (moduleMockSet.has(file))
+            return false;
+        if (file.startsWith(INTEGRATION_DIR_PREFIX) && !INTEGRATION_DIR_ALLOWLIST.has(file))
+            return false;
+        if (KNOWN_UNREGISTERED_ORPHANS.has(file))
+            return false;
+        return true;
+    });
+    const overlap = normal.filter((file) => moduleMockSet.has(file));
+    if (overlap.length > 0) {
+        throw new Error(`run-unit-tests: file(s) present in both normal and module-mock groups: ${overlap.join(", ")}`);
+    }
+    const selected = mode === "normal" ? normal : [...MODULE_MOCK_MANIFEST];
+    if (selected.length === 0) {
+        throw new Error(`run-unit-tests: selected group "${mode}" is empty — refusing to run zero tests`);
+    }
+    return selected;
+}
+/**
+ * Greedily packs sorted file paths into batches whose serialized
+ * `execPath ...nodeOptions ...files` command length stays within `maxLength`.
+ * A single file that cannot fit even alone is rejected rather than spawned.
+ */
+export function partitionTestBatches(files, options = {}) {
+    const { execPath = process.execPath, nodeOptions = [], maxLength = MAX_COMMAND_LENGTH } = options;
+    const prefixLength = [execPath, ...nodeOptions].join(" ").length;
+    const batches = [];
+    let current = [];
+    let currentLength = prefixLength;
+    for (const file of files) {
+        const addition = 1 + file.length; // separating space + path
+        if (prefixLength + addition > maxLength) {
+            throw new Error(`run-unit-tests: "${file}" alone exceeds the command-length budget ` +
+                `(${prefixLength + addition} > ${maxLength} chars) — cannot batch it safely`);
+        }
+        if (current.length > 0 && currentLength + addition > maxLength) {
+            batches.push(current);
+            current = [];
+            currentLength = prefixLength;
+        }
+        current.push(file);
+        currentLength += addition;
+    }
+    if (current.length > 0) {
+        batches.push(current);
+    }
+    return batches;
+}
+/** Discovers, selects, batches, and spawns the requested test group; returns an aggregate exit code. */
+export function runSelectedGroup(mode, options) {
+    // Validate the mode before touching the filesystem or spawning anything —
+    // an unknown group must fail fast with no discovery/spawn side effects.
+    if (mode !== "normal" && mode !== "module-mocks") {
+        throw new Error(`run-unit-tests: unknown group "${mode}" (expected "normal" or "module-mocks")`);
+    }
+    const { root, execPath = process.execPath, spawnFn = spawnSync, discoverFn = (opts) => discoverTestFiles(opts), log = console.log, } = options;
+    const discovered = discoverFn({ root });
+    const selected = selectTestGroup(mode, discovered);
+    // Split out the force-exit quarantine: those files run last, each as its own
+    // single-file spawn WITH --test-force-exit (exact tally, prompt exit despite
+    // the leaked handle). Every batched spawn runs WITHOUT the flag so its test
+    // tally stays deterministic — see FORCE_EXIT_QUARANTINE above.
+    const quarantineSet = new Set(FORCE_EXIT_QUARANTINE);
+    const batchable = selected.filter((file) => !quarantineSet.has(file));
+    const quarantined = selected.filter((file) => quarantineSet.has(file));
+    const extraFlags = mode === "module-mocks" ? ["--experimental-test-module-mocks"] : [];
+    const nodeOptions = [...extraFlags, "--test"];
+    const batches = partitionTestBatches(batchable, { execPath, nodeOptions });
+    log(`run-unit-tests: group="${mode}" files=${selected.length} batches=${batches.length}` +
+        (quarantined.length > 0 ? ` quarantined=${quarantined.length}` : ""));
+    let aggregateExit = 0;
+    const spawn = (args) => {
+        const result = spawnFn(execPath, args, {
+            cwd: root,
+            stdio: "inherit",
+            shell: false,
+        });
+        if ((result.status ?? 1) !== 0) {
+            aggregateExit = 1;
+        }
+    };
+    batches.forEach((batch, index) => {
+        log(`run-unit-tests: batch ${index + 1}/${batches.length} (${batch.length} file(s))`);
+        spawn([...nodeOptions, ...batch]);
+    });
+    quarantined.forEach((file, index) => {
+        log(`run-unit-tests: quarantined ${index + 1}/${quarantined.length} ${file} (single-file, --test-force-exit)`);
+        spawn([...nodeOptions, "--test-force-exit", file]);
+    });
+    return aggregateExit;
+}

package/build/setup-epic.js

@@ -28,6 +28,12 @@ import readline from "node:readline";
 import { approveEpicPlan, createEpicRun, fetchEpicRunState, resolveConductorBridgeApiAccess, storeEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
 import { validateBranchName } from "./base-ref.js";
 import { hashPlan } from "./conductor/plan.js";
+/** Accepted `policy_json.review_policy.source` values (the `ReviewPolicy` surface). */
+export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
+    "verdict_protocol",
+    "native_review_decision",
+    "none",
+];
 /** Echoed single-line prompt on stderr (mirrors connect-github's helper). */
 function defaultPromptLine(promptText) {
     return new Promise((resolve) => {
@@ -82,6 +88,12 @@ export function getSetupEpicUsage() {
         "                         on origin, and every child-ticket PR targets it.",
         "                         Omit (the default) to continue on the repository base",
         "                         branch. Interactive runs are offered a proposal.",
+        "  --review-policy <src>  PER-RUN review policy source, one of:",
+        `                         ${SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", ")}.`,
+        "                         Composed into policy_json.review_policy on create.",
+        "                         This setting is per-run: repository-level review-policy",
+        "                         defaults are NOT persisted in supervisor project",
+        "                         defaults yet — that is BAPI-694.",
         "  --dry-run              Validate and preview; make no mutating calls",
         "  --json                 Emit a single JSON result object on stdout",
         "  -h, --help             Show this help",
@@ -115,6 +127,25 @@ function parseFeatureBranchValue(raw) {
         return { ok: false, error: `Invalid --feature-branch value: ${reason}` };
     return { ok: true, value: trimmed };
 }
+/**
+ * Validate a `--review-policy` value against the existing `ReviewPolicy`
+ * vocabulary. Rejects BEFORE any network access so an unknown source can never
+ * reach a create request (BAPI-679). An explicitly blank value normalizes to
+ * absent, matching `--feature-branch`.
+ */
+function parseReviewPolicyValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return { ok: true, value: undefined };
+    if (!SETUP_EPIC_REVIEW_POLICY_SOURCES.includes(trimmed)) {
+        return {
+            ok: false,
+            error: `Invalid --review-policy value '${trimmed}'. Expected one of: ` +
+                SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", "),
+        };
+    }
+    return { ok: true, value: trimmed };
+}
 export function parseSetupEpicArgs(argv) {
     if (argv.includes("-h") || argv.includes("--help")) {
         return { status: "help", usage: getSetupEpicUsage() };
@@ -124,6 +155,7 @@ export function parseSetupEpicArgs(argv) {
     let repo;
     let planVersion;
     let featureBranch;
+    let reviewPolicy;
     let dryRun = false;
     let json = false;
     for (let i = 0; i < argv.length; i++) {
@@ -136,6 +168,14 @@ export function parseSetupEpicArgs(argv) {
             featureBranch = parsedFb.value;
             continue;
         }
+        // `--review-policy=<source>` inline form (BAPI-679).
+        if (arg.startsWith("--review-policy=")) {
+            const parsedRp = parseReviewPolicyValue(arg.slice("--review-policy=".length));
+            if (!parsedRp.ok)
+                return { status: "error", message: parsedRp.error };
+            reviewPolicy = parsedRp.value;
+            continue;
+        }
         switch (arg) {
             case "--feature-branch": {
                 // Do not consume a following flag as the value (Step 2.5).
@@ -149,6 +189,17 @@ export function parseSetupEpicArgs(argv) {
                 i++;
                 break;
             }
+            case "--review-policy": {
+                const v = takeValue(argv, i, arg);
+                if (v === null)
+                    return { status: "error", message: "--review-policy requires a value." };
+                const parsedRp = parseReviewPolicyValue(v);
+                if (!parsedRp.ok)
+                    return { status: "error", message: parsedRp.error };
+                reviewPolicy = parsedRp.value;
+                i++;
+                break;
+            }
             case "--epic-key": {
                 const v = takeValue(argv, i, arg);
                 if (v === null)
@@ -206,7 +257,7 @@ export function parseSetupEpicArgs(argv) {
         return { status: "error", message: "setup-epic requires --plan-file <path>." };
     return {
         status: "ok",
-        options: { epicKey, planFile, repo, planVersion, featureBranch, dryRun, json },
+        options: { epicKey, planFile, repo, planVersion, featureBranch, reviewPolicy, dryRun, json },
     };
 }
 /**
@@ -246,11 +297,19 @@ export function validateEpicPlanSidecar(parsed) {
             return { ok: false, error: `Duplicate ticket_key in plan: ${key}.` };
         keys.add(key);
         if (node.touched_files === undefined) {
-            // Only fatal when the repo has file-overlap serialization enabled, in
-            // which case the server 400s. Warn either way — it is the difference
-            // between siblings serializing and colliding.
-            warnings.push(`Node ${key} has no touched_files. File-overlap serialization cannot ` +
-                `protect it; if the repo has that flag on, the server will reject this plan.`);
+            // BAPI-722: the server ACCEPTS an omitted touched_files — it is an explicit
+            // opt-out of preemptive overlap serialization, not a rejection. This stays a
+            // warning because it is a genuine planning-QUALITY signal (an undeclared node
+            // is never pre-serialized against its siblings, so it relies entirely on the
+            // reactive merge-conflict/rebase lane), but it must not claim a hard failure
+            // the server will not produce — a false hard-rejection warning trains authors
+            // to distrust the whole validator. Reported for EVERY offending node in one
+            // pass rather than stopping at the first.
+            warnings.push(`Node ${key} has no touched_files, so it opts out of preemptive ` +
+                `file-overlap serialization: the server accepts the plan but will not ` +
+                `pre-serialize ${key} against overlapping siblings (a conflict would ` +
+                `instead be caught reactively and rebased). Add touched_files to ${key} ` +
+                `to get that scheduling protection (use [] when no files are predicted).`);
         }
     }
     // Build one adjacency in a consistent predecessor -> successor direction, the
@@ -468,6 +527,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     let existingRunId = null;
     let existingStatus = null;
     let existingBaseBranch = null;
+    let existingReviewPolicy = null;
     try {
         const state = await fetchEpicRunState(access, opts.epicKey, deps.fetch);
         existingRunId = state.epic_run?.epic_run_id ?? null;
@@ -479,6 +539,19 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         existingBaseBranch = typeof existingBase === "string" && existingBase.trim() !== ""
             ? existingBase
             : null;
+        // BAPI-679: read the existing run's review policy for the conflict guard
+        // below. Absent/malformed reads as null — "the resolver's default applies" —
+        // which is deliberately NOT the same as an explicitly selected source.
+        const existingReview = existingPolicy && typeof existingPolicy === "object"
+            ? existingPolicy.review_policy
+            : undefined;
+        const existingReviewSource = existingReview && typeof existingReview === "object"
+            ? existingReview.source
+            : undefined;
+        existingReviewPolicy =
+            typeof existingReviewSource === "string" && existingReviewSource.trim() !== ""
+                ? existingReviewSource
+                : null;
     }
     catch (err) {
         if (err instanceof ConductorBridgeApiError && err.status === 404) {
@@ -511,6 +584,25 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             `it unchanged, or abandon the run to start over on a new branch.`);
         return 1;
     }
+    // --- Review-policy conflict guard against an existing live run ----------
+    // BAPI-679, analogous to the feature-branch guard above. An explicitly selected
+    // policy that disagrees with a live run's effective policy must fail closed:
+    // setup-epic never retargets an existing run, and silently proceeding would let
+    // an operator believe the run is being reviewed under a policy it is not.
+    // Selecting nothing preserves the existing run's policy untouched.
+    if (existingRunId &&
+        opts.reviewPolicy !== undefined &&
+        existingReviewPolicy !== opts.reviewPolicy) {
+        deps.errorLog(`Epic ${opts.epicKey} already has a live run (${existingRunId}) whose review ` +
+            `policy is ${existingReviewPolicy ? `'${existingReviewPolicy}'` : "unset (resolver default)"}, ` +
+            `which conflicts with the requested '${opts.reviewPolicy}'. setup-epic will not ` +
+            `retarget an existing run. Re-run without --review-policy to reuse it unchanged, ` +
+            `or abandon the run to start over.`);
+        return 1;
+    }
+    if (opts.reviewPolicy !== undefined) {
+        say(`Review:     ${opts.reviewPolicy} (per-run; repository defaults pending BAPI-694)`);
+    }
     if (opts.dryRun) {
         say("");
         say("[dry-run] No changes made. Would:");
@@ -523,6 +615,9 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         if (featureBranch !== undefined) {
             say(`  - feature branch: ${featureBranch} (create from repository base branch; no request made in dry-run)`);
         }
+        if (opts.reviewPolicy !== undefined) {
+            say(`  - review policy: ${opts.reviewPolicy} (per-run policy_json.review_policy; not persisted as a repository default until BAPI-694)`);
+        }
         say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/plan          (v${plan.plan_version})`);
         say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/approve-plan  (v${plan.plan_version})`);
         if (opts.json) {
@@ -535,6 +630,11 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 existing_run_id: existingRunId,
                 // Only present for a feature-branch run — no-feature JSON is unchanged.
                 ...(featureBranch !== undefined ? { feature_branch: featureBranch } : {}),
+                // Only present when a policy was explicitly selected — the
+                // no-policy JSON shape is unchanged.
+                ...(opts.reviewPolicy !== undefined
+                    ? { review_policy: { source: opts.reviewPolicy }, review_policy_scope: "per-run" }
+                    : {}),
                 warnings,
             }, null, 2));
         }
@@ -563,8 +663,17 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         try {
             // Persist the confirmed feature branch as policy_json.base_branch ONLY when
             // one was selected; otherwise keep the exact legacy create request shape.
-            const createRequest = featureBranch !== undefined
-                ? { epicKey: opts.epicKey, policyJson: { base_branch: featureBranch } }
+            // BAPI-679: base_branch and review_policy COMPOSE — neither replaces the
+            // other, and when neither is selected the legacy create request shape is
+            // preserved byte-for-byte so the pre-feature contract is unchanged.
+            const policyJson = {};
+            if (featureBranch !== undefined)
+                policyJson.base_branch = featureBranch;
+            if (opts.reviewPolicy !== undefined) {
+                policyJson.review_policy = { source: opts.reviewPolicy };
+            }
+            const createRequest = Object.keys(policyJson).length > 0
+                ? { epicKey: opts.epicKey, policyJson }
                 : { epicKey: opts.epicKey };
             const run = await createEpicRun(access, createRequest, deps.fetch);
             result.epic_run_id = run.epic_run_id;

package/build/upgrade-cli.js

@@ -20,23 +20,9 @@ import path from "path";
 import { VERSION } from "./version.generated.js";
 import { runInit } from "./init.js";
 import { isNewerVersion } from "./update-check.js";
+import { fetchLatestVersion } from "./cli-release.js";
 import { buildGenericAgentShellCommand, detectTerminal, getDefaultSpawnTerminalTabForPlatform, createDefaultStartTicketsDeps, } from "./start-tickets.js";
 import { AGENT_REGISTRY } from "./agent-registry.js";
-async function fetchLatestVersion() {
-    try {
-        const res = await fetch("https://registry.npmjs.org/@bridge_gpt/mcp-server/latest", {
-            signal: AbortSignal.timeout(3000),
-        });
-        if (res.ok) {
-            const data = (await res.json());
-            return data.version || null;
-        }
-    }
-    catch {
-        return null;
-    }
-    return null;
-}
 export async function runUpgradeCli(argv) {
     const cwd = process.cwd();
     const isDryRun = argv.includes("--dry-run");

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.34";
+export const VERSION = "0.2.36";

package/docs/CONDUCTOR.md

@@ -25,6 +25,23 @@ v2 splits the old local tick into two halves:
 | **Reconciler** | **Server-side**, on the Bridge API worker dyno, every 30s | Selects every epic run whose status is `active`, evaluates gates, and enqueues executor jobs. Nothing to install or schedule. |
 | **Executor** | **Locally**, on your machine | Polls for jobs, claims them, spawns worker agents, heartbeats. This is the only piece you run. |
 
+> **⚠️ For a run against a LOCAL server, do NOT use `npx`.** The npm-published
+> package routinely lags `main` — that is the normal steady state right after any
+> conductor ticket merges. When the server is built from a newer `main` it mints
+> `prompt_spec` placeholders the older published executor rejects, and the job dies
+> instantly with `ContractError.Prompt` (`prompt_spec for job N declares unsupported
+> placeholder '…'`). Confirmed on the BAPI-716 run: published `0.2.34` vs. local
+> `0.2.35`, over BAPI-699's `RELATED_CONTEXT`. Build and run the local tree so the
+> executor and server come from the same commit:
+>
+> ```
+> cd mcp_server && npm run build
+> node mcp_server/build/index.js executor --repo <name>
+> ```
+
+For a run against a deployed server whose version you match, the published CLI is
+fine:
+
 ```
 npx -y @bridge_gpt/mcp-server executor --repo <name>
 ```
@@ -54,10 +71,104 @@ preview the calls without mutating anything.
 Once the plan is approved the run becomes `active`, the server-side reconciler
 picks it up within ~30s, and your local `executor` starts claiming jobs.
 
-> **A caveat worth knowing before you plan an epic.** Conductor has no
-> merge-conflict handling, and plan-time file-overlap serialization is currently
-> dark (the planner does not yet emit the `touched_files` metadata it needs). If
-> two sibling tickets touch the same files, do not let them dispatch in parallel.
+### `touched_files` — optional, but declare it anyway
+
+**Plan-time file-overlap serialization is live and on by default.**
+`planner_file_overlap_serialization_enabled` (BAPI-495, defaulted on by BAPI-677 /
+migration 0126, on `config_code_repositories`) makes overlapping siblings gain a
+`depends_on`/edge on each other *before* the DAG is validated, hashed, and stored,
+while siblings with disjoint files stay parallel.
+
+`touched_files` is the plan-time metadata that pass reads. It is a **best-effort
+prediction, never reconciled against the real diff**, so BAPI-722 made it optional.
+Three outcomes, and the difference between the first two is the point
+(`_extract_predicted_touched_files`, `api/library/db/epic_runs.py:3195`):
+
+| In the node | Meaning | Result |
+|---|---|---|
+| Field **absent** | The node **opts out** of preemptive serialization | **Accepted.** Every pair involving it is skipped (`undeclared_pairs_skipped`); no edge is added in either direction |
+| `"touched_files": []` | A deliberate "this ticket predicts no file overlap" | Accepted as a *declared* node with an empty set |
+| Field present but **malformed** | A non-list, or a list holding a blank, absolute, or non-string path | **400** — `EpicRunConflictError(code="VALIDATION")` |
+
+Only omission is relaxed. Data you *did* supply must be well-formed. Paths are
+repo-root-relative.
+
+```json
+{
+  "plan_version": 1,
+  "nodes": [
+    { "ticket_key": "BAPI-405", "status": "planned", "depends_on": [],
+      "touched_files": ["api/routes/jira_api.py"] }
+  ],
+  "edges": []
+}
+```
+
+> **`setup-epic --dry-run` warns on a missing `touched_files`, and that warning is
+> a planning-quality signal, not a predicted failure.** The server accepts the
+> plan. What you lose is scheduling protection: an undeclared node is never
+> pre-serialized against its siblings.
+
+Declare it anyway. Serialization only ever **adds** edges — it never removes an
+authored one — so hand-authored `depends_on` and `touched_files` compose safely.
+Author both: the edges as your reviewable statement of intent, `touched_files` so
+the scheduler can catch overlaps you did not anticipate.
+
+> **Serialization is a scheduling optimization, not a safety mechanism.** It avoids
+> *dispatching* file-overlapping siblings in parallel; it does not resolve a
+> conflict once one exists. The safety net is reactive and independent of any
+> prediction: a PR that a sibling's merge turns `CONFLICTING` is observed live and
+> routed to `JOB_TYPE_REBASE` (`_merge_entry_failure_requires_rebase` in the
+> reconciler). That backstop covers declared and undeclared nodes alike — which is
+> exactly why omitting `touched_files` is safe to accept.
+
+## The conductor CI gate — `conductor-ci / gate` (BAPI-695)
+
+**Before driving a run you want CI-gated, wire its policy.** The reconciler's
+per-ticket `ci` gate reads **`policy_json.required_checks`** (a declared
+`RunPolicy` key) and observes those check-run conclusions at the ticket PR's
+**current head SHA**. If that list is empty, the observer short-circuits to
+`PASSED` with `{"no_required_checks": true}` and **runs no CI at all** — the loop
+merges on hand-verification only. `.github/workflows/conductor-ci.yml` publishes
+the real, always-reporting required context **`conductor-ci / gate`**; set
+
+```json
+"policy_json": { "required_checks": ["conductor-ci / gate"] }
+```
+
+on every run you want gated. The workflow existing is not enough — the context has
+to be in the run policy.
+
+> **`setup-epic` has no flag for this.** There is no `--required-checks` option, so a
+> run created by `setup-epic` starts with an **empty** `required_checks` and its `ci`
+> gate short-circuits to `PASSED` until you wire it. Because `setup-epic` also
+> approves the plan — making the run `active` and visible to the reconciler within
+> ~30s — wire the policy by PATCH **immediately** after setup, before any ticket can
+> reach its `ci` gate.
+
+> **This is NOT `done_gate_config`.** The per-run `policy_json.required_checks`
+> read by the reconciler `ci` gate is a *different* surface from the supervisor
+> `done_gate_config.required_ci_checks_green` documented under "Supervisor config"
+> below. BAPI-695 wires only the former, per run; it does **not** change
+> `done_gate_config` defaults, repo-default policy, or GitHub branch protection.
+
+**Once gated, expect this behavior:**
+
+- The `ci` gate now waits for `conductor-ci / gate` on the ticket PR's current head.
+  A complete **red** aggregator enters the bounded `ci_fix` remediation path; a
+  **missing or still-running** current-head context stays pending (never a hard
+  fail).
+- A **green from an older head** can never satisfy the gate after a rebase or
+  force-push — the poll is bound to the current head SHA, and the workflow's per-PR
+  concurrency cancels the superseded run so the new head publishes a fresh context.
+- Out-of-scope PRs (forks, `dependabot/*`, non-`feature/BAPI-*`) get an intentional
+  fast green — cost control, **not** proof the suites ran.
+
+For the exact new-run/PATCH procedure (and the **whole-object `policy_json`
+replacement** caution — GET, merge `required_checks` locally, PATCH the whole
+object), and the immutable case-sensitive matching of the context string, see the
+operator runbook, **§4a "Wire the conductor CI required check"**
+([`docs/claude/epic-conductor-v2-operator-runbook.md`](../../docs/claude/epic-conductor-v2-operator-runbook.md)).
 
 ## Conductor observability (opt-in via `--conductor`, BAPI-394)