@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/setup-epic.js

@@ -8,26 +8,43 @@
  *
  * Ordering is load-bearing:
  *
- *   0. GET the run state FIRST. `POST /epic-runs/runs` cannot be probed with a
- *      "create and tolerate 409" — it never returned 409, so a blind repeat
- *      create used to mint a SECOND active run, wedging the epic permanently
- *      (every later plan call 409s on "Multiple active runs") and double-charging
- *      billing. The server is idempotent now, but the pre-check is still what
- *      lets us report honestly and skip work.
- *   1. Create only when no live run exists.
- *   2. Hash locally — ADVISORY ONLY. The server re-hashes after applying
+ *   0. Local sidecar checks. Cheap, offline, and they produce a legible message
+ *      naming the offending node instead of a bare HTTP 400.
+ *   1. GET the run state. `POST /epic-runs/runs` cannot be probed with a "create
+ *      and tolerate 409" — it never returned 409, so a blind repeat create used to
+ *      mint a SECOND active run, wedging the epic permanently (every later plan
+ *      call 409s on "Multiple active runs") and double-charging billing. The
+ *      server is idempotent now, but the pre-check is still what lets us report
+ *      honestly and skip work.
+ *   2. SERVER validation (BAPI-754). The local checks in step 0 are a mirror of
+ *      the server's rules, and a mirror drifts — it had already lost
+ *      `nodes[].status`. Creating first meant a plan the server would refuse
+ *      still cost a run row and an automation-start debit before anything
+ *      noticed. So the authoritative validator runs BEFORE any create, and the
+ *      only sanctioned exception is an older server that lacks the lane (404),
+ *      which warns and falls back to the legacy order.
+ *   3. Create only when no live run exists, carrying the complete policy from
+ *      `--policy-file` so no post-create PATCH is needed. A create that returns
+ *      200 reused a live run and IGNORED that policy — reconcile, do not assume.
+ *   4. Hash locally — ADVISORY ONLY. The server re-hashes after applying
  *      file-overlap serialization, so a divergence is legitimate, not corruption.
- *   3. Store, then approve.
+ *   5. Store, then approve.
  *
- * Read-only against the local filesystem: it reads the plan sidecar and writes
- * nothing.
+ * Read-only against the local filesystem: it reads the plan sidecar and the
+ * optional policy file, and writes nothing.
  */
 import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
 import os from "node:os";
 import readline from "node:readline";
-import { approveEpicPlan, createEpicRun, fetchEpicRunState, resolveConductorBridgeApiAccess, storeEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
+import { approveEpicPlan, createEpicRunWithDisposition, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, storeEpicPlan, validateEpicPlan, 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,10 +99,37 @@ 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.",
-        "  --dry-run              Validate and preview; make no mutating calls",
+        "  --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.",
         "  --json                 Emit a single JSON result object on stdout",
         "  -h, --help             Show this help",
         "",
+        "Policy controls:",
+        "  --policy-file <path>   JSON file holding the COMPLETE run policy. Applied in",
+        "                         the same invocation that creates the run, so no",
+        "                         post-create PATCH is needed. Contradicts nothing",
+        "                         silently: if the file and --feature-branch or",
+        "                         --review-policy disagree, setup-epic errors naming both.",
+        "  --replace-policy       Authorize replacing a LIVE run's stored policy with the",
+        "                         policy file, as a complete replacement. Without it, a",
+        "                         divergent policy on a reused run is refused with a",
+        "                         redacted diff rather than applied. Requires",
+        "                         --policy-file.",
+        "",
+        "Validation controls:",
+        "  --dry-run              Run the SERVER's real plan validator (including",
+        "                         file-overlap serialization) and stop. Creates no run,",
+        "                         stores no plan, and incurs no automation-start charge.",
+        "  --local-only           Skip server validation and run only the local sidecar",
+        "                         checks. Valid ONLY with --dry-run, and the result is",
+        "                         labeled 'partial (local checks only)': the local checks",
+        "                         do not cover everything the server enforces, so this is",
+        "                         never a substitute for authoritative validation.",
+        "",
         "After setup, the server-side reconciler picks the run up within ~30s.",
         "To execute claimed jobs on this machine, run:",
         "  npx -y @bridge_gpt/mcp-server executor --repo <name>",
@@ -115,6 +159,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,10 +187,22 @@ export function parseSetupEpicArgs(argv) {
     let repo;
     let planVersion;
     let featureBranch;
+    let reviewPolicy;
+    let policyFile;
+    let replacePolicy = false;
+    let localOnly = false;
     let dryRun = false;
     let json = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        // `--policy-file=<path>` inline form (BAPI-754).
+        if (arg.startsWith("--policy-file=")) {
+            const raw = arg.slice("--policy-file=".length).trim();
+            if (raw === "")
+                return { status: "error", message: "--policy-file requires a value." };
+            policyFile = raw;
+            continue;
+        }
         // `--feature-branch=<name>` inline form (handled before the exact-match switch).
         if (arg.startsWith("--feature-branch=")) {
             const parsedFb = parseFeatureBranchValue(arg.slice("--feature-branch=".length));
@@ -136,6 +211,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 +232,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)
@@ -187,6 +281,23 @@ export function parseSetupEpicArgs(argv) {
                 i++;
                 break;
             }
+            case "--policy-file": {
+                const v = takeValue(argv, i, arg);
+                if (v === null)
+                    return { status: "error", message: "--policy-file requires a value." };
+                policyFile = v.trim();
+                if (policyFile === "") {
+                    return { status: "error", message: "--policy-file requires a value." };
+                }
+                i++;
+                break;
+            }
+            case "--replace-policy":
+                replacePolicy = true;
+                break;
+            case "--local-only":
+                localOnly = true;
+                break;
             case "--dry-run":
                 dryRun = true;
                 break;
@@ -204,10 +315,305 @@ export function parseSetupEpicArgs(argv) {
         return { status: "error", message: "setup-epic requires --epic-key <KEY>." };
     if (!planFile)
         return { status: "error", message: "setup-epic requires --plan-file <path>." };
+    // BAPI-754 — reject contradictory combinations HERE, before any file read,
+    // credential resolution, or network call, so a mistyped invocation cannot reach
+    // a mutating request.
+    if (localOnly && !dryRun) {
+        return {
+            status: "error",
+            message: "--local-only is only valid together with --dry-run. It downgrades the run to " +
+                "local checks only, which is never a substitute for the server's validation " +
+                "on a real setup.",
+        };
+    }
+    if (replacePolicy && policyFile === undefined) {
+        return {
+            status: "error",
+            message: "--replace-policy requires --policy-file. It authorizes replacing a live run's " +
+                "stored policy with the file's contents, so without a file there is nothing to " +
+                "replace it with.",
+        };
+    }
     return {
         status: "ok",
-        options: { epicKey, planFile, repo, planVersion, featureBranch, dryRun, json },
+        options: {
+            epicKey,
+            planFile,
+            repo,
+            planVersion,
+            featureBranch,
+            reviewPolicy,
+            policyFile,
+            replacePolicy,
+            localOnly,
+            dryRun,
+            json,
+        },
+    };
+}
+/**
+ * Read and parse the `--policy-file` JSON.
+ *
+ * Every failure names the PATH and the failing action and nothing else. The file
+ * can carry `notify.webhook_url`, so echoing its contents — or even a JSON parse
+ * error's excerpt of them — into a terminal or a CI log would defeat the whole
+ * redaction discipline downstream. A caller who needs to see the file can open it.
+ */
+export async function readSetupEpicPolicyFile(filePath, readFile) {
+    let raw;
+    try {
+        raw = await readFile(filePath);
+    }
+    catch {
+        return { ok: false, error: `Could not read policy file '${filePath}'.` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            error: `Policy file '${filePath}' is not valid JSON.`,
+        };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            error: `Policy file '${filePath}' must contain a JSON object (the run policy).`,
+        };
+    }
+    return { ok: true, policy: parsed };
+}
+/** Read `review_policy.source` from a policy object, or a structural verdict. */
+function readReviewPolicySource(policy) {
+    if (!("review_policy" in policy))
+        return { kind: "absent" };
+    const block = policy["review_policy"];
+    if (block === undefined || block === null)
+        return { kind: "absent" };
+    if (typeof block !== "object" || Array.isArray(block))
+        return { kind: "ambiguous" };
+    const source = block["source"];
+    if (source === undefined || source === null)
+        return { kind: "absent" };
+    if (typeof source !== "string" || source.trim() === "")
+        return { kind: "ambiguous" };
+    return { kind: "source", value: source };
+}
+/**
+ * Compose the `--feature-branch` and `--review-policy` selections onto the policy
+ * file's object.
+ *
+ * The rule is "no silent winner". Where the file is silent, the CLI selection
+ * fills the gap. Where both speak and AGREE, the file's existing spelling is kept
+ * untouched — adding a second spelling of the same setting would leave the server
+ * with two keys claiming one truth. Where both speak and DISAGREE, this fails with
+ * an error naming both sources, because either choice would mean running an epic
+ * under a policy the operator did not pick and could not see us pick.
+ *
+ * Unknown keys and wrong-typed values are passed through EXACTLY as written. The
+ * authoritative `RunPolicy` schema lives on the server, and re-implementing it here
+ * is how the two drift; the server's field-named `422` is the better error anyway.
+ */
+export function composeSetupEpicPolicy(filePolicy, selections) {
+    const composed = { ...filePolicy };
+    // `baseBranch` is not a key the server accepts — it is the camelCase slip an
+    // author makes when hand-writing the file. Treat it as a DECLARATION for
+    // contradiction purposes so a conflicting value is reported rather than
+    // silently ignored, but never invent it and never rewrite it into snake_case:
+    // the server's strict boundary should be the one to reject it.
+    const declaredBranches = [];
+    for (const key of ["base_branch", "baseBranch"]) {
+        if (key in composed && composed[key] !== undefined && composed[key] !== null) {
+            declaredBranches.push({ key, value: composed[key] });
+        }
+    }
+    if (selections.featureBranch !== undefined) {
+        const conflicting = declaredBranches.filter((entry) => entry.value !== selections.featureBranch);
+        if (conflicting.length > 0) {
+            const names = conflicting.map((entry) => entry.key).join(" and ");
+            return {
+                ok: false,
+                error: `--feature-branch selected '${selections.featureBranch}', but --policy-file ` +
+                    `declares a different branch under ${names}. setup-epic will not pick a ` +
+                    `winner between them: drop the flag, or fix the policy file so both agree.`,
+            };
+        }
+        if (declaredBranches.length === 0)
+            composed.base_branch = selections.featureBranch;
+    }
+    const fileReview = readReviewPolicySource(composed);
+    if (selections.reviewPolicy !== undefined) {
+        if (fileReview.kind === "ambiguous") {
+            return {
+                ok: false,
+                error: `--review-policy selected '${selections.reviewPolicy}', but --policy-file's ` +
+                    `review_policy is not an object with a non-empty string 'source'. setup-epic ` +
+                    `will not guess which one you meant: drop the flag, or fix review_policy in ` +
+                    `the policy file.`,
+            };
+        }
+        if (fileReview.kind === "source" && fileReview.value !== selections.reviewPolicy) {
+            return {
+                ok: false,
+                error: `--review-policy selected '${selections.reviewPolicy}', but --policy-file ` +
+                    `declares review_policy.source '${fileReview.value}'. setup-epic will not pick ` +
+                    `a winner between them: drop the flag, or fix the policy file so both agree.`,
+            };
+        }
+        if (fileReview.kind === "absent") {
+            const existing = composed["review_policy"];
+            composed.review_policy =
+                existing && typeof existing === "object" && !Array.isArray(existing)
+                    ? { ...existing, source: selections.reviewPolicy }
+                    : { source: selections.reviewPolicy };
+        }
+    }
+    return { ok: true, policy: composed };
+}
+/**
+ * Does this policy object explicitly supply the `notify.webhook_url` leaf?
+ *
+ * Explicit `null` counts — that is the documented way to CLEAR a stored URL, so it
+ * is a real change even though it looks like an absence.
+ */
+export function policySuppliesWebhookUrl(policy) {
+    const notify = policy["notify"];
+    if (!notify || typeof notify !== "object" || Array.isArray(notify))
+        return false;
+    return "webhook_url" in notify;
+}
+/**
+ * Project a policy into the shape both sides of a comparison can actually see.
+ *
+ * Two keys are removed from every operand:
+ *
+ * - `notify.webhook_url` — never present in a server response, so comparing it
+ *   would report a difference on every run that has one. The empty `notify` object
+ *   is KEPT after removal, mirroring the server's `_redacted_policy_json`, so a
+ *   policy that declares an empty notify block still compares equal to itself.
+ * - `feature_branch_provisioning` — server-minted provenance. It appears on the
+ *   stored side and never on the requested side, and re-sending it is a conflict
+ *   the server rejects outright.
+ *
+ * Returns a deep copy; both operands are left unmodified.
+ */
+export function projectPolicyForComparison(policy) {
+    if (Array.isArray(policy))
+        return policy.map((item) => projectPolicyForComparison(item));
+    if (!policy || typeof policy !== "object")
+        return policy;
+    const out = {};
+    for (const [key, value] of Object.entries(policy)) {
+        if (key === "feature_branch_provisioning")
+            continue;
+        if (key === "notify" && value && typeof value === "object" && !Array.isArray(value)) {
+            const notify = {};
+            for (const [nKey, nValue] of Object.entries(value)) {
+                if (nKey === "webhook_url")
+                    continue;
+                notify[nKey] = projectPolicyForComparison(nValue);
+            }
+            out.notify = notify;
+            continue;
+        }
+        out[key] = projectPolicyForComparison(value);
+    }
+    return out;
+}
+/** Render a value for a diff line, bounded so a large nested block stays readable. */
+function renderDiffValue(value) {
+    const text = JSON.stringify(value ?? null);
+    return text.length > 120 ? `${text.slice(0, 120)}…` : text;
+}
+/**
+ * Compare two PROJECTED policies and return a deterministic structural diff.
+ *
+ * Ordering is by sorted path, not by insertion order, so two files that differ
+ * only in key order produce an identical (empty) diff and a real difference always
+ * renders in the same place.
+ *
+ * This function must only ever be handed projected operands — `webhook_url` has
+ * already been removed by then, so no diff line can carry it. That ordering is the
+ * safety property: the URL is never rendered and then masked, it is never present.
+ */
+export function diffProjectedPolicies(stored, requested, basePath = "") {
+    const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+    if (isPlainObject(stored) && isPlainObject(requested)) {
+        const keys = [...new Set([...Object.keys(stored), ...Object.keys(requested)])].sort();
+        const entries = [];
+        for (const key of keys) {
+            const path = basePath ? `${basePath}.${key}` : key;
+            const inStored = key in stored;
+            const inRequested = key in requested;
+            if (inStored && !inRequested) {
+                entries.push({ path, kind: "removed" });
+            }
+            else if (!inStored && inRequested) {
+                entries.push({ path, kind: "added" });
+            }
+            else {
+                entries.push(...diffProjectedPolicies(stored[key], requested[key], path));
+            }
+        }
+        return entries;
+    }
+    if (JSON.stringify(stored ?? null) === JSON.stringify(requested ?? null))
+        return [];
+    return [{ path: basePath || "(policy)", kind: "changed" }];
+}
+/** Render a diff as operator-readable lines. Never receives a webhook URL. */
+export function renderPolicyDiff(entries, stored, requested) {
+    const read = (source, path) => {
+        let cursor = source;
+        for (const part of path.split(".")) {
+            if (!cursor || typeof cursor !== "object")
+                return undefined;
+            cursor = cursor[part];
+        }
+        return cursor;
     };
+    return entries.map((entry) => {
+        if (entry.kind === "added") {
+            return `  + ${entry.path}: ${renderDiffValue(read(requested, entry.path))} (not in the stored policy)`;
+        }
+        if (entry.kind === "removed") {
+            return `  - ${entry.path}: ${renderDiffValue(read(stored, entry.path))} (absent from the policy file)`;
+        }
+        return (`  ~ ${entry.path}: stored ${renderDiffValue(read(stored, entry.path))} ` +
+            `→ file ${renderDiffValue(read(requested, entry.path))}`);
+    });
+}
+/**
+ * The one permitted rendering of a supplied webhook URL. The value NEVER appears.
+ *
+ * The stored URL is invisible to a client by design, so a file that supplies one
+ * cannot be compared against it. Rather than report "no change" on a policy we
+ * cannot see, this is counted as divergence and described in words.
+ */
+export const WEBHOOK_SUPPLIED_DIFF_LINE = "  ~ notify.webhook_url: (supplied — will replace stored value on apply)";
+/**
+ * Decide what to do with a policy file when create returned an EXISTING run.
+ *
+ * Create is idempotent: a `200` means the server kept the live run and ignored the
+ * policy we sent. Silently continuing would leave the operator believing their
+ * file is in force when it is not — so the divergence is surfaced, and applying it
+ * requires `--replace-policy` because a mid-run policy change is a real decision
+ * about a run that is already executing tickets.
+ */
+export function reconcileReusedRunPolicy(args) {
+    const storedProjected = projectPolicyForComparison(args.storedPolicy ?? {});
+    const requestedProjected = projectPolicyForComparison(args.requestedPolicy);
+    const diffLines = renderPolicyDiff(diffProjectedPolicies(storedProjected, requestedProjected), storedProjected, requestedProjected);
+    if (policySuppliesWebhookUrl(args.requestedPolicy)) {
+        diffLines.push(WEBHOOK_SUPPLIED_DIFF_LINE);
+    }
+    if (diffLines.length === 0)
+        return { kind: "noop" };
+    return args.replacePolicy
+        ? { kind: "replace", diffLines }
+        : { kind: "refused_divergent", diffLines };
 }
 /**
  * Validate the plan DAG locally, mirroring the server's `validate_epic_plan_dag`.
@@ -246,11 +652,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
@@ -339,15 +753,20 @@ function proposeFeatureBranchName(epicKey) {
  *     parse time and is returned unchanged (no prompt).
  *   - A non-interactive (piped/CI) run or a `--json` run never prompts and never
  *     blocks — it retains the absent-branch behavior.
+ *   - A `--policy-file` that already declares a branch has ALREADY answered this
+ *     question (BAPI-754). Prompting anyway would invite an operator to type a
+ *     competing value that composition would then have to refuse.
  *   - An interactive run is shown the proposal (branch name, "create from the
  *     repository base branch" strategy, and the child-PR-targeting consequence)
  *     and may accept it, type a custom name, or decline to use the base branch.
  *     An edited nonblank value is re-validated; an invalid value is redisplayed
  *     for correction rather than silently rewritten.
  */
-async function resolveFeatureBranchSelection(opts, repoName, deps) {
+async function resolveFeatureBranchSelection(opts, repoName, deps, policyDeclaresBranch = false) {
     if (opts.featureBranch !== undefined)
         return opts.featureBranch;
+    if (policyDeclaresBranch)
+        return undefined;
     if (!deps.isTTY || opts.json)
         return undefined;
     const proposed = proposeFeatureBranchName(opts.epicKey);
@@ -382,6 +801,64 @@ function errorDetail(err) {
     }
     return err instanceof Error ? err.message : String(err);
 }
+/**
+ * Reconcile a policy file against a REUSED run's stored policy, applying it only
+ * under `--replace-policy`.
+ *
+ * Returns `true` to continue the workflow (`noop` or a successful `replaced`) and
+ * `false` when the run's policy diverges and was left alone — the caller then
+ * stops, because storing and approving a plan under a policy the operator did not
+ * choose is worse than doing nothing.
+ *
+ * Mutates `result.policy_applied` so the JSON summary reports the same
+ * disposition the human output describes.
+ */
+async function applyReusedRunPolicy(args) {
+    const outcome = reconcileReusedRunPolicy({
+        storedPolicy: args.storedPolicy,
+        requestedPolicy: args.requestedPolicy,
+        replacePolicy: args.replacePolicy,
+    });
+    if (outcome.kind === "noop") {
+        args.result.policy_applied = "noop";
+        args.say("Policy:     policy unchanged");
+        return true;
+    }
+    if (outcome.kind === "refused_divergent") {
+        args.result.policy_applied = "refused_divergent";
+        args.deps.errorLog(`Epic run ${args.epicRunId} is live and its stored policy differs from the ` +
+            `policy file. setup-epic will not silently change a running epic's policy.\n` +
+            `${outcome.diffLines.join("\n")}\n` +
+            `Re-run with --replace-policy to apply the file as the complete replacement, ` +
+            `or drop --policy-file to reuse the run unchanged.`);
+        return false;
+    }
+    try {
+        await replaceEpicRunPolicy(args.access, { epicRunId: args.epicRunId, policyJson: args.requestedPolicy }, args.deps.fetch);
+    }
+    catch (err) {
+        args.result.policy_applied = "refused_divergent";
+        args.deps.errorLog(`Failed to replace the run policy: ${errorDetail(err)}`);
+        return false;
+    }
+    args.result.policy_applied = "replaced";
+    args.say("Policy:     policy applied: replaced");
+    for (const line of outcome.diffLines)
+        args.say(line);
+    return true;
+}
+/**
+ * Emit the post-access refusal summary and the non-zero exit status.
+ *
+ * A refusal happens after the run state is known, so `--json` consumers still get
+ * the canonical result object — `policy_applied: "refused_divergent"` is a real
+ * outcome to record, not an absence of one.
+ */
+function emitRefusal(deps, opts, result) {
+    if (opts.json)
+        deps.log(JSON.stringify(result, null, 2));
+    return 1;
+}
 export async function runSetupEpicCli(argv, overrides = {}) {
     const deps = { ...createDefaultSetupEpicDeps(), ...overrides };
     const parsed = parseSetupEpicArgs(argv);
@@ -429,6 +906,60 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         return 1;
     }
     const localHash = hashPlan(plan);
+    // --- Read the policy file (still no network) ------------------------------
+    // BAPI-754: parsed here so a malformed file, or a contradiction between the
+    // file and the CLI flags, fails before credentials are resolved or any request
+    // is dispatched.
+    let filePolicy;
+    if (opts.policyFile !== undefined) {
+        const policyRead = await readSetupEpicPolicyFile(opts.policyFile, deps.readFile);
+        if (!policyRead.ok) {
+            deps.errorLog(policyRead.error);
+            return 1;
+        }
+        filePolicy = policyRead.policy;
+    }
+    const policyDeclaresBranch = filePolicy !== undefined &&
+        ["base_branch", "baseBranch"].some((key) => key in filePolicy && filePolicy[key] !== undefined && filePolicy[key] !== null);
+    // --- --local-only --dry-run: stop here, offline and explicitly partial ----
+    // Nothing below this point is reachable without the network, and the whole
+    // point of the flag is to not touch it — not even to resolve a credential.
+    if (opts.localOnly) {
+        if (filePolicy !== undefined) {
+            const composed = composeSetupEpicPolicy(filePolicy, {
+                featureBranch: opts.featureBranch,
+                reviewPolicy: opts.reviewPolicy,
+            });
+            if (!composed.ok) {
+                deps.errorLog(composed.error);
+                return 1;
+            }
+        }
+        say(`Epic:       ${opts.epicKey}`);
+        say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${plan.edges.length} edge(s)`);
+        say(`Local hash: ${localHash}`);
+        for (const w of warnings)
+            say(`  [warn] ${w}`);
+        say("");
+        say("Result:     partial (local checks only)");
+        say("            The server's plan validator did NOT run, so this says nothing " +
+            "about whether the server would accept this plan. Re-run without " +
+            "--local-only for authoritative validation.");
+        if (opts.json) {
+            deps.log(JSON.stringify({
+                dry_run: true,
+                local_only: true,
+                result: "partial (local checks only)",
+                epic_key: opts.epicKey,
+                plan_version: plan.plan_version,
+                local_plan_hash: localHash,
+                server_validated: false,
+                policy_applied: "absent",
+                warnings,
+            }, null, 2));
+        }
+        return 0;
+    }
     // --- Resolve access ------------------------------------------------------
     const accessResult = await resolveConductorBridgeApiAccess({
         env: deps.env,
@@ -454,8 +985,8 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // Resolved AFTER local/access context is known but BEFORE any run-state read
     // or mutating request, so malformed interactive input fails before network
     // dispatch. Returns undefined to continue on the repository base branch.
-    const promptedInteractively = opts.featureBranch === undefined && deps.isTTY && !opts.json;
-    const featureBranch = await resolveFeatureBranchSelection(opts, access.repoName, deps);
+    const promptedInteractively = opts.featureBranch === undefined && !policyDeclaresBranch && deps.isTTY && !opts.json;
+    const featureBranch = await resolveFeatureBranchSelection(opts, access.repoName, deps, policyDeclaresBranch);
     if (featureBranch !== undefined) {
         say(`Feature:    ${featureBranch} (create from repository base branch on origin)`);
     }
@@ -463,22 +994,57 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         // Ordinary, non-warning notice — only when an interactive operator declined.
         say("Feature:    none — continue using the repository base branch");
     }
+    // --- Compose the requested run policy (BAPI-754) -------------------------
+    // A contradiction between the file and the flags is refused here, before the
+    // pre-check and long before any create, so no request is dispatched under a
+    // policy nobody chose.
+    let requestedPolicy;
+    if (filePolicy !== undefined) {
+        const composed = composeSetupEpicPolicy(filePolicy, {
+            featureBranch,
+            reviewPolicy: opts.reviewPolicy,
+        });
+        if (!composed.ok) {
+            deps.errorLog(composed.error);
+            return 1;
+        }
+        requestedPolicy = composed.policy;
+        say(`Policy:     ${opts.policyFile} (complete run policy, applied at creation)`);
+    }
     // --- Step 0: pre-check ---------------------------------------------------
     // Never create on an ambiguous read. A wrong answer here mints a duplicate run.
     let existingRunId = null;
     let existingStatus = null;
     let existingBaseBranch = null;
+    let existingReviewPolicy = null;
+    // BAPI-754: the live run's SERVER-REDACTED stored policy, kept for the reuse
+    // comparison. Redacted is the only form a client can ever see.
+    let existingPolicyJson = null;
     try {
         const state = await fetchEpicRunState(access, opts.epicKey, deps.fetch);
         existingRunId = state.epic_run?.epic_run_id ?? null;
         existingStatus = state.epic_run?.status ?? null;
         const existingPolicy = state.epic_run?.policy_json;
+        existingPolicyJson = existingPolicy ?? null;
         const existingBase = existingPolicy && typeof existingPolicy === "object"
             ? existingPolicy.base_branch
             : undefined;
         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,9 +1077,90 @@ 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)`);
+    }
+    // --- Authoritative server validation (BAPI-754) --------------------------
+    // Runs BEFORE any create. A plan the server would refuse must not cost a run
+    // row and an automation-start debit on the way to finding that out.
+    let validated = null;
+    let validateLaneMissing = false;
+    try {
+        validated = await validateEpicPlan(access, {
+            planVersion: plan.plan_version,
+            planBlob: plan,
+            epicKey: opts.epicKey,
+        }, deps.fetch);
+    }
+    catch (err) {
+        const status = err instanceof ConductorBridgeApiError ? err.status : undefined;
+        if (status === 404) {
+            // The ONE sanctioned fallback: an older deployment without the lane. Warn
+            // loudly (a wrong BAPI_BASE_URL looks exactly like this) and continue on
+            // the legacy create-then-store order.
+            validateLaneMissing = true;
+            const msg = `This server has no POST /jira/epic-runs/plan/validate, so the plan could NOT ` +
+                `be validated before creating the run. Either the deployment predates that ` +
+                `capability, or BAPI_BASE_URL is pointing at an older one. Falling back to the ` +
+                `legacy create-then-store order: an invalid plan may create a run and incur an ` +
+                `automation-start charge before failing.`;
+            warnings.push(msg);
+            say(`Validation: [warn] ${msg}`);
+        }
+        else if (status === undefined) {
+            deps.errorLog(`server unreachable, cannot fully validate — the plan was not checked against ` +
+                `the server's validator.\nNo run was created and no automation-start charge ` +
+                `occurred.\nDetail: ${errorDetail(err)}`);
+            return 1;
+        }
+        else if (status === 409) {
+            // The epic is WEDGED (multiple active runs), which says nothing about the
+            // plan. Reporting this as "server validation: failed" would send the
+            // operator to fix a sidecar that is perfectly fine. The pre-check above
+            // normally catches this first; this branch covers the race where a
+            // duplicate run appears between the pre-check and the validate call.
+            deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — the plan could not be ` +
+                `validated because the epic itself is wedged, and every plan call will ` +
+                `keep failing. This is NOT a problem with your plan. Abandon the ` +
+                `duplicate before retrying:\n` +
+                `  PATCH /jira/epic-runs/runs/<epic_run_id> {"status": "abandoned"}\n` +
+                `No run was created and no automation-start charge occurred.\n` +
+                `Detail: ${errorDetail(err)}`);
+            return 1;
+        }
+        else {
+            deps.errorLog(`server validation: failed\n${errorDetail(err)}\n` +
+                `No run was created and no automation-start charge occurred.`);
+            return 1;
+        }
+    }
+    if (validated) {
+        say("Validation: server validation: passed");
+        say(`            plan hash ${validated.planHash}`);
+        say(`            serialization ${validated.serializationEnabled ? "enabled" : "disabled"}, ` +
+            `${validated.insertedEdges} edge(s) inserted`);
+    }
     if (opts.dryRun) {
         say("");
-        say("[dry-run] No changes made. Would:");
+        say(validated
+            ? "[dry-run] Server validation passed. No changes made. Would:"
+            : "[dry-run] partial (local checks only) — the server's validator did not run. Would:");
         if (existingRunId) {
             say(`  - reuse existing run ${existingRunId} (status: ${existingStatus})`);
         }
@@ -523,6 +1170,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 +1185,22 @@ 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" }
+                    : {}),
+                // BAPI-754 — a dry run applies nothing, so the disposition is always
+                // "absent"; server_validated says whether the check was authoritative.
+                server_validated: validated !== null,
+                policy_applied: "absent",
+                ...(validated
+                    ? {
+                        server_plan_hash: validated.planHash,
+                        serialization_enabled: validated.serializationEnabled,
+                        inserted_edges: validated.insertedEdges,
+                    }
+                    : { result: "partial (local checks only)" }),
                 warnings,
             }, null, 2));
         }
@@ -551,6 +1217,8 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         run_created: false,
         plan_stored: false,
         plan_approved: false,
+        server_validated: validated !== null,
+        policy_applied: "absent",
         warnings,
     };
     if (featureBranch !== undefined)
@@ -558,21 +1226,89 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // --- Step 1: create (only when there is no live run) ---------------------
     if (existingRunId) {
         say(`Run:        reusing ${existingRunId} (status: ${existingStatus})`);
+        // A pre-check that already found a live run means create would answer 200
+        // anyway; reconcile the file against that run's stored policy directly.
+        if (requestedPolicy !== undefined) {
+            const outcome = await applyReusedRunPolicy({
+                access,
+                deps,
+                say,
+                result,
+                epicRunId: existingRunId,
+                storedPolicy: existingPolicyJson,
+                requestedPolicy,
+                replacePolicy: opts.replacePolicy,
+            });
+            if (!outcome)
+                return emitRefusal(deps, opts, result);
+        }
     }
     else {
         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.
+            //
+            // BAPI-754: a --policy-file supersedes that ad-hoc composition entirely —
+            // `requestedPolicy` IS the composed result, flags included — so the whole
+            // policy reaches the server in the create that mints the run.
+            let policyJson;
+            if (requestedPolicy !== undefined) {
+                policyJson = requestedPolicy;
+            }
+            else {
+                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 || requestedPolicy !== undefined
+                ? { epicKey: opts.epicKey, policyJson }
                 : { epicKey: opts.epicKey };
-            const run = await createEpicRun(access, createRequest, deps.fetch);
+            const { run, created } = await createEpicRunWithDisposition(access, createRequest, deps.fetch);
             result.epic_run_id = run.epic_run_id;
             result.status = run.status;
-            result.run_created = true;
-            say(`Run:        created ${run.epic_run_id}`);
+            result.run_created = created;
+            if (created) {
+                say(`Run:        created ${run.epic_run_id}`);
+                if (requestedPolicy !== undefined) {
+                    result.policy_applied = "created";
+                    say("Policy:     policy applied: created");
+                }
+            }
+            else {
+                // The pre-check said there was no live run, but create found one — a
+                // concurrent setup won the race. Treat it exactly like the reuse path.
+                say(`Run:        reusing ${run.epic_run_id} (status: ${run.status})`);
+                if (requestedPolicy !== undefined) {
+                    const outcome = await applyReusedRunPolicy({
+                        access,
+                        deps,
+                        say,
+                        result,
+                        epicRunId: run.epic_run_id,
+                        storedPolicy: run.policy_json,
+                        requestedPolicy,
+                        replacePolicy: opts.replacePolicy,
+                    });
+                    if (!outcome)
+                        return emitRefusal(deps, opts, result);
+                }
+            }
         }
         catch (err) {
+            const status = err instanceof ConductorBridgeApiError ? err.status : undefined;
+            if (status === 422 && requestedPolicy !== undefined) {
+                deps.errorLog(`The run policy from '${opts.policyFile}' was rejected by the server.\n` +
+                    `${errorDetail(err)}\n` +
+                    `No run was created and no automation-start charge occurred. Fix the ` +
+                    `named field in the policy file and re-run.`);
+                return 1;
+            }
             deps.errorLog(`Failed to create the epic run: ${errorDetail(err)}`);
             return 1;
         }
@@ -668,6 +1404,14 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     }
     else {
         say("");
+        // BAPI-754: repeat the capability warning in the summary. An operator who
+        // scrolled past it at detection time would otherwise finish the run believing
+        // the plan had been validated.
+        if (validateLaneMissing) {
+            say("[warn] This server has no POST /jira/epic-runs/plan/validate — the plan was " +
+                "NOT validated before the run was created, and the legacy create-then-store " +
+                "order was used. Check that BAPI_BASE_URL points at the intended deployment.");
+        }
         say(`Epic run ${result.epic_run_id} is ${result.status ?? "unknown"}.`);
         say("The server-side reconciler will pick it up within ~30s.");
         say("To execute claimed jobs on this machine, run:");