@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/setup-epic.js

@@ -1,3 +1,5 @@
+import { ticketReviewSummary } from "./ticket-review-summary.js";
+import { previewLaunchReadiness } from "./conductor/bridge-api-client.js";
 /**
  * `setup-epic` — one-command bootstrap for an Epic Implementer run.
  *
@@ -82,7 +84,7 @@
 import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
 import os from "node:os";
 import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, } from "./epic-integration-pr.js";
-import { approveEpicPlan, buildConductorJiraUrl, conductorGetHeaders, createEpicRunWithDisposition, decodeCanonicalProvenance, fetchConductorReadiness, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, resolveEpicLaunchBridgeApiAccess, safeDiagnosticMessage, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
+import { approveEpicPlan, buildConductorJiraUrl, conductorGetHeaders, createEpicRunWithDisposition, decodeCanonicalProvenance, fetchConductorReadiness, formatSchemaIncompatibleRefusal, isSchemaIncompatibleError, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, resolveEpicLaunchBridgeApiAccess, safeDiagnosticMessage, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
 import { formatEpicLaunchChannelIdentity, getPinnedEpicLaunchPolicy, readEpicLaunchProfile, } from "./epic-launch-profile.js";
 // BAPI-1133 (A2) — the single legacy-to-typed merge-execution-mode mapping and
 // its total legacy resolver live in `merge-pull-request.ts` (no import cycle:
@@ -94,6 +96,7 @@ import { classifyMergeExecutionEligibility } from "./conductor/merge-execution-e
 import { repositoryWorkflowRemedy } from "./conductor/repository-workflow-remedy.js";
 import { resolveTrackedPaths } from "./git-reachability.js";
 import { validateBranchName } from "./base-ref.js";
+import { TICKET_KEY_PATTERN } from "./ticket-key-utils.js";
 // Reused from the implement-epic client on purpose: adding a second wrapper under
 // `conductor/` would give the v2 path its own copy to drift from.
 //
@@ -113,6 +116,134 @@ import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // state. See `planeBinding` on `SetupEpicDeps` below.
 import { createPlaneFsDeps, createPlaneProcessDeps } from "./plane/defaults.js";
 import { bindPlaneManifestEpicRun, manifestHasLiveProcess, readPlaneManifest, } from "./plane/manifest.js";
+// ---------------------------------------------------------------------------
+// Verification hand-off choice (BAPI-1496)
+// ---------------------------------------------------------------------------
+/** The policy keys child 1 (BAPI-1492) declares on the server's `RunPolicy`. */
+export const SETUP_EPIC_VERIFICATION_HANDOFF_ENABLED_KEY = "verification_handoff_enabled";
+export const SETUP_EPIC_VERIFICATION_HANDOFF_EXCEPTIONS_KEY = "verification_handoff_exceptions";
+/**
+ * The closed step-class vocabulary. Mirrors the server's
+ * `VERIFICATION_HANDOFF_STEP_CLASSES` in `api/models/epic_run.py`; a client
+ * cannot import a Python constant, so a test pins the two together.
+ */
+export const SETUP_EPIC_VERIFICATION_HANDOFF_STEP_CLASSES = ["e2e_tests", "rendered_ui_review"];
+/** Mirrors the server's `MAX_VERIFICATION_HANDOFF_EXCEPTIONS`. */
+export const SETUP_EPIC_MAX_VERIFICATION_HANDOFF_EXCEPTIONS = 200;
+/**
+ * Deduplicate and order exception pairs deterministically, by ticket key and
+ * then class, so the same set always composes the same bytes.
+ */
+export function normalizeVerificationHandoffExceptions(entries) {
+    const seen = new Map();
+    for (const entry of entries) {
+        seen.set(`${entry.ticket_key}\u0000${entry.step_class}`, {
+            ticket_key: entry.ticket_key,
+            step_class: entry.step_class,
+        });
+    }
+    return [...seen.values()].sort((a, b) => a.ticket_key === b.ticket_key
+        ? a.step_class.localeCompare(b.step_class)
+        : a.ticket_key.localeCompare(b.ticket_key));
+}
+/**
+ * Validate the raw flag values. Every refusal names the offending flag and
+ * repeats only CLI-supplied text, before any file read or request.
+ */
+export function parseVerificationHandoffFlags(args) {
+    if (args.choice === undefined && args.exceptions.length === 0)
+        return { ok: true, value: undefined };
+    if (args.choice === undefined) {
+        return {
+            ok: false,
+            error: "--verification-handoff-exception requires --verification-handoff block. An exception " +
+                "only narrows a hand-off choice, so without one there is nothing to narrow.",
+        };
+    }
+    if (args.choice !== "proceed" && args.choice !== "block") {
+        return {
+            ok: false,
+            error: `--verification-handoff must be one of: proceed, block. Got '${args.choice}'.`,
+        };
+    }
+    if (args.attended || args.intoBase) {
+        const flag = args.attended ? "--attended" : "--into-base";
+        return {
+            ok: false,
+            error: `--verification-handoff cannot be combined with ${flag}: a verification hand-off ` +
+                "needs an unattended epic-branch run, and this launch has no such authority. " +
+                "Drop --verification-handoff; verification stays a blocker.",
+        };
+    }
+    const parsed = [];
+    for (const raw of args.exceptions) {
+        const separator = raw.lastIndexOf(":");
+        const ticketKey = separator > 0 ? raw.slice(0, separator) : "";
+        const stepClass = separator > 0 ? raw.slice(separator + 1) : "";
+        if (!TICKET_KEY_PATTERN.test(ticketKey)) {
+            return {
+                ok: false,
+                error: `--verification-handoff-exception '${raw}' must be <TICKET>:<class> with a ticket key such as PROJ-12.`,
+            };
+        }
+        if (!SETUP_EPIC_VERIFICATION_HANDOFF_STEP_CLASSES.includes(stepClass)) {
+            return {
+                ok: false,
+                error: `--verification-handoff-exception '${raw}' names an unsupported class. Use one of: ` +
+                    `${SETUP_EPIC_VERIFICATION_HANDOFF_STEP_CLASSES.join(", ")}.`,
+            };
+        }
+        parsed.push({ ticket_key: ticketKey, step_class: stepClass });
+    }
+    if (args.choice === "proceed" && parsed.length > 0) {
+        return {
+            ok: false,
+            error: "--verification-handoff-exception cannot be combined with --verification-handoff proceed. " +
+                "Use --verification-handoff block to keep verification a blocker for named work.",
+        };
+    }
+    if (args.choice === "block" && parsed.length === 0) {
+        return {
+            ok: false,
+            error: "--verification-handoff block needs at least one --verification-handoff-exception " +
+                "<TICKET>:<class> naming the work whose verification stays a blocker.",
+        };
+    }
+    const exceptions = normalizeVerificationHandoffExceptions(parsed);
+    if (exceptions.length > SETUP_EPIC_MAX_VERIFICATION_HANDOFF_EXCEPTIONS) {
+        return {
+            ok: false,
+            error: `--verification-handoff-exception names ${exceptions.length} distinct entries; the run ` +
+                `policy holds at most ${SETUP_EPIC_MAX_VERIFICATION_HANDOFF_EXCEPTIONS}. Nothing was created.`,
+        };
+    }
+    return { ok: true, value: { choice: args.choice, exceptions } };
+}
+/** The two policy keys a validated choice composes. */
+export function verificationHandoffPolicyKeys(choice) {
+    return {
+        [SETUP_EPIC_VERIFICATION_HANDOFF_ENABLED_KEY]: true,
+        [SETUP_EPIC_VERIFICATION_HANDOFF_EXCEPTIONS_KEY]: choice.exceptions.map((entry) => ({ ...entry })),
+    };
+}
+/**
+ * Read a policy file's declared exception list as a normalized pair set, or
+ * `null` when it is not a well-shaped list. Never returns or echoes a value.
+ */
+function readDeclaredHandoffExceptions(value) {
+    if (!Array.isArray(value))
+        return null;
+    const entries = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return null;
+        const { ticket_key: ticketKey, step_class: stepClass } = entry;
+        if (typeof ticketKey !== "string" || typeof stepClass !== "string")
+            return null;
+        entries.push({ ticket_key: ticketKey, step_class: stepClass });
+    }
+    return normalizeVerificationHandoffExceptions(entries);
+}
 /**
  * The one `policy_json.posture` value that means "unattended" (BAPI-1102).
  *
@@ -225,7 +356,7 @@ export function getSetupEpicUsage() {
         "default branch. `drive-epic` readiness lists all three with their current state.",
         "",
         "Required:",
-        "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
+        "  --epic-key <KEY>       Epic key (e.g. PROJ-123)",
         "  --plan-file <path>     Path to epic-plan.dag.json (from decompose-epic)",
         "",
         "Options:",
@@ -248,14 +379,13 @@ export function getSetupEpicUsage() {
         "                         the default would leave on base.",
         "  --into-base            OPT OUT of the epic-branch default: cut no branch and",
         "                         target every child PR at the repository base branch",
-        "                         (the pre-BAPI-1009 behavior). Use this if automation",
+        "                         (children target the base branch). Use this if automation",
         "                         depended on \"no flag = direct to base\". Contradictory",
         "                         with --feature-branch; passing both is a parse error.",
         "  --attended             OPT OUT of the unattended default: compose only",
         "                         base_branch (plus --review-policy when supplied), with",
         "                         no posture and no auto-merge authorization, and skip the",
-        "                         unattended repository prerequisites entirely. The create",
-        "                         request is byte-for-byte the pre-BAPI-1102 one.",
+        "                         unattended repository prerequisites entirely.",
         "                         Contradictory with a --policy-file that declares",
         "                         posture: unattended; that pair is refused by name.",
         "  --review-policy <src>  PER-RUN review policy source, one of:",
@@ -272,12 +402,22 @@ export function getSetupEpicUsage() {
         "                         default is stamped into a new run only when the run",
         "                         sets no review policy of its own, so a value supplied",
         "                         here always wins.",
+        "  --verification-handoff proceed|block",
+        "                         The owner's answer to the setup gap question,",
+        "                         for a NEW unattended epic-branch run. proceed composes",
+        "                         verification_handoff_enabled: true with no exceptions;",
+        "                         block composes it with the named exceptions. Refused with",
+        "                         --attended, --into-base, a launch with no epic branch, or",
+        "                         a live run (use patch-policy). Omitted, no key is sent.",
+        "  --verification-handoff-exception <TICKET>:<class>",
+        `                         Repeatable; class is one of ${SETUP_EPIC_VERIFICATION_HANDOFF_STEP_CLASSES.join(", ")}.`,
+        "                         Required with block, refused with proceed. At most",
+        `                         ${SETUP_EPIC_MAX_VERIFICATION_HANDOFF_EXCEPTIONS} distinct entries.`,
         "  --json                 Emit a single JSON result object on stdout",
-        "  --launch-profile <name>  (BAPI-1260) Resolve the target, repository, and bound",
-        "                         credential from this host-local launch profile. Passed",
-        "                         by drive-epic. The profile names its own target; it",
-        "                         never falls back to production by itself.",
-        "  --base-url <url>       (BAPI-1260) Explicit target; must agree with the profile.",
+        "  --launch-profile <name>  Passed by drive-epic: resolve the target, repository, and",
+        "                         credential from a host-local launch profile (see",
+        "                         `drive-epic --help-advanced`).",
+        "  --base-url <url>       Explicit target; must agree with the profile.",
         "  -h, --help             Show this help",
         "",
         "Policy controls:",
@@ -290,8 +430,7 @@ export function getSetupEpicUsage() {
         "                         type's gate ceiling (implement / spec_review / resume",
         "                         10799; remediate / ci_fix 3599; rebase / smoke 2699;",
         "                         merge 1799); the server rejects a higher value with a",
-        "                         422 naming the offending field. Full table:",
-        "                         docs/epic-implementer/operator-runbook.md §4.",
+        "                         422 naming the offending field.",
         "  --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",
@@ -380,8 +519,26 @@ export function parseSetupEpicArgs(argv) {
     let json = false;
     let launchProfile;
     let baseUrl;
+    // BAPI-1496 — raw hand-off values; validated together after the loop.
+    let verificationHandoffChoice;
+    const verificationHandoffExceptions = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        // BAPI-1496 — inline forms of the hand-off flags.
+        if (arg.startsWith("--verification-handoff=")) {
+            verificationHandoffChoice = arg.slice("--verification-handoff=".length).trim();
+            if (verificationHandoffChoice === "") {
+                return { status: "error", message: "--verification-handoff requires a value." };
+            }
+            continue;
+        }
+        if (arg.startsWith("--verification-handoff-exception=")) {
+            const raw = arg.slice("--verification-handoff-exception=".length).trim();
+            if (raw === "")
+                return { status: "error", message: "--verification-handoff-exception requires a value." };
+            verificationHandoffExceptions.push(raw);
+            continue;
+        }
         // `--policy-file=<path>` inline form (BAPI-754).
         if (arg.startsWith("--policy-file=")) {
             const raw = arg.slice("--policy-file=".length).trim();
@@ -494,6 +651,18 @@ export function parseSetupEpicArgs(argv) {
                 i++;
                 break;
             }
+            case "--verification-handoff":
+            case "--verification-handoff-exception": {
+                const v = takeValue(argv, i, arg);
+                if (v === null || v.trim() === "")
+                    return { status: "error", message: `${arg} requires a value.` };
+                if (arg === "--verification-handoff")
+                    verificationHandoffChoice = v.trim();
+                else
+                    verificationHandoffExceptions.push(v.trim());
+                i++;
+                break;
+            }
             case "--into-base":
                 intoBase = true;
                 break;
@@ -551,6 +720,16 @@ export function parseSetupEpicArgs(argv) {
                 "may be selected — remove whichever one you did not mean.",
         };
     }
+    // BAPI-1496 — the hand-off choice, its pairing rules, and its topology rule,
+    // refused here before any file read, credential resolution, or request.
+    const handoff = parseVerificationHandoffFlags({
+        choice: verificationHandoffChoice,
+        exceptions: verificationHandoffExceptions,
+        attended,
+        intoBase,
+    });
+    if (!handoff.ok)
+        return { status: "error", message: handoff.error };
     if (replacePolicy && policyFile === undefined) {
         return {
             status: "error",
@@ -578,6 +757,8 @@ export function parseSetupEpicArgs(argv) {
             // BAPI-1260 — only when supplied, so a legacy options object is unchanged.
             ...(launchProfile ? { launchProfile } : {}),
             ...(baseUrl ? { baseUrl } : {}),
+            // BAPI-1496 — only when supplied, so a legacy options object is unchanged.
+            ...(handoff.value !== undefined ? { verificationHandoff: handoff.value } : {}),
         },
     };
 }
@@ -715,6 +896,39 @@ export function composeSetupEpicPolicy(filePolicy, selections) {
                     : { source: selections.reviewPolicy };
         }
     }
+    // BAPI-1496 — the hand-off keys under the same "no silent winner" rule. No
+    // choice leaves the file's values exactly as written; a choice fills only an
+    // absent key and refuses any declared disagreement. Exception lists compare as
+    // (ticket_key, step_class) sets. Neither value is echoed.
+    if (selections.verificationHandoff !== undefined) {
+        const wanted = verificationHandoffPolicyKeys(selections.verificationHandoff);
+        const enabledKey = SETUP_EPIC_VERIFICATION_HANDOFF_ENABLED_KEY;
+        const exceptionsKey = SETUP_EPIC_VERIFICATION_HANDOFF_EXCEPTIONS_KEY;
+        const flag = `--verification-handoff ${selections.verificationHandoff.choice}`;
+        if (enabledKey in composed && composed[enabledKey] !== wanted[enabledKey]) {
+            return {
+                ok: false,
+                error: `${flag} turns the verification hand-off on, but --policy-file declares a different ` +
+                    `${enabledKey}. setup-epic will not pick a winner between them: drop the flag, or fix ` +
+                    `the policy file so both agree.`,
+            };
+        }
+        if (exceptionsKey in composed) {
+            const declared = readDeclaredHandoffExceptions(composed[exceptionsKey]);
+            if (declared === null || JSON.stringify(declared) !== JSON.stringify(wanted[exceptionsKey])) {
+                return {
+                    ok: false,
+                    error: `${flag} selects a set of verification exceptions, but --policy-file declares a ` +
+                        `different ${exceptionsKey}. setup-epic will not pick a winner between them: drop ` +
+                        `the flag, or fix the policy file so both agree.`,
+                };
+            }
+        }
+        for (const key of [enabledKey, exceptionsKey]) {
+            if (!(key in composed))
+                composed[key] = wanted[key];
+        }
+    }
     return { ok: true, policy: composed };
 }
 /**
@@ -773,7 +987,27 @@ export function preflightSetupEpicPolicy(args) {
                 `declaration from the policy file.`,
         };
     }
-    // 3. Policy-source contradictions between the file and the CLI selections.
+    // 3. BAPI-1496 — a hand-off choice needs an unattended epic-branch launch.
+    //    `--attended` and `--into-base` are already parse errors; this covers the
+    //    topology resolved from the plan and the file: no epic branch at all, or a
+    //    file whose declared posture is not the unattended one.
+    if (args.verificationHandoff !== undefined) {
+        const declaresOtherPosture = args.filePolicy !== undefined &&
+            "posture" in args.filePolicy &&
+            args.filePolicy.posture !== SETUP_EPIC_UNATTENDED_POSTURE;
+        if ((args.featureBranch === undefined && !args.policyDeclaresBranch) || declaresOtherPosture) {
+            return {
+                ok: false,
+                reason: "verification_handoff_without_authority",
+                message: "--verification-handoff needs an unattended run on an epic branch, and this launch " +
+                    (declaresOtherPosture
+                        ? `is not unattended: --policy-file '${args.policyFile}' declares another posture. `
+                        : "selects no epic branch. ") +
+                    "Drop --verification-handoff; verification stays a blocker.",
+            };
+        }
+    }
+    // 4. Policy-source contradictions between the file and the CLI selections.
     //    Delegated to the composer, which owns the "no silent winner" rule; the
     //    gate only gives the outcome a stable name.
     if (args.filePolicy === undefined)
@@ -781,6 +1015,7 @@ export function preflightSetupEpicPolicy(args) {
     const composed = composeSetupEpicPolicy(args.filePolicy, {
         featureBranch: args.featureBranch,
         reviewPolicy: args.reviewPolicy,
+        ...(args.verificationHandoff !== undefined ? { verificationHandoff: args.verificationHandoff } : {}),
     });
     if (!composed.ok) {
         return { ok: false, reason: "policy_source_contradiction", message: composed.error };
@@ -1144,7 +1379,48 @@ function findCycle(keys, adjacency) {
     }
     return null;
 }
-export function effectivePolicyFacts(policy, source) {
+/**
+ * Count the distinct ordering relationships a validated plan declares, through
+ * either supported representation: top-level `edges` and per-node `depends_on`.
+ * One pair is counted once however many places declare it. Empty IDs and
+ * self-loops are ignored; node existence is validated elsewhere, not here.
+ */
+function countDeclaredOrderingPairs(plan) {
+    const pairs = new Set();
+    const add = (from, to) => {
+        if (typeof from !== "string" || typeof to !== "string")
+            return;
+        if (from === "" || to === "" || from === to)
+            return;
+        pairs.add(`${from}->${to}`);
+    };
+    for (const edge of Array.isArray(plan.edges) ? plan.edges : [])
+        add(edge?.from, edge?.to);
+    for (const node of Array.isArray(plan.nodes) ? plan.nodes : []) {
+        for (const dependency of Array.isArray(node?.depends_on) ? node.depends_on : []) {
+            add(dependency, node.ticket_key);
+        }
+    }
+    return pairs.size;
+}
+/**
+ * The channel a STORED policy resolves to, from the engine's own
+ * `notification_sink` facts. The stored policy is server-redacted, so its
+ * `notify` block cannot answer this. Strict `=== true` comparisons: a truthy
+ * non-boolean is unavailable, never a guess.
+ */
+function storedEscalationChannel(notificationSink) {
+    if (!notificationSink || typeof notificationSink !== "object" || Array.isArray(notificationSink)) {
+        return "unavailable";
+    }
+    const sink = notificationSink;
+    if (sink.webhook_configured === true)
+        return "configured webhook";
+    if (sink.email_channel_selected === true)
+        return "account email";
+    return "unavailable";
+}
+export function effectivePolicyFacts(policy, source, notificationSink) {
     const object = policy && typeof policy === "object" && !Array.isArray(policy)
         ? policy : {};
     const numbers = (value) => {
@@ -1159,7 +1435,9 @@ export function effectivePolicyFacts(policy, source) {
         posture: object.posture === "unattended" ? "unattended" : "attended",
         caps: numbers(object.caps),
         job_timeouts: numbers(object.job_timeouts),
-        escalation_channel: formatEpicLaunchChannelIdentity(source === "stored" ? "unavailable" : policyDeclaresNotifyWebhook(object) ? "configured webhook" : "account email"),
+        escalation_channel: formatEpicLaunchChannelIdentity(source === "stored"
+            ? storedEscalationChannel(notificationSink)
+            : policyDeclaresNotifyWebhook(object) ? "configured webhook" : "account email"),
     };
 }
 /** Propose a conductor epic feature branch name for an epic key (BAPI-655). */
@@ -1351,7 +1629,7 @@ export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPol
             message: "unattended runs are off for this repository. Turn on 'Allow unattended " +
                 "Epic Implementer runs' on the repository's Setup page in the Bridge admin " +
                 "panel, or pass --attended to create an attended run. If it is already on, " +
-                "contact Bridge support. No run was created.",
+                "email info@bridgegpt.ai. No run was created.",
         };
     }
     // Two independent sources satisfy the escalation channel, and the check has to
@@ -1411,7 +1689,7 @@ export function evaluateSetupEpicBringUpPrerequisites(readiness) {
     if (readiness === null) {
         return {
             reason: "readiness_unreadable",
-            message: "the Bridge API conductor readiness report could not be read, so the database " +
+            message: "the Epic Implementer readiness report could not be read, so the database " +
                 "migration, worker presence, and single-reconciler facts could not be confirmed. " +
                 `Retry once the server is reachable. ${NO_RUN_WAS_CREATED}`,
         };
@@ -1462,8 +1740,8 @@ export function evaluateSetupEpicMergeExecutionPrerequisites(readiness, requeste
     if (readiness === null) {
         return {
             reason: MERGE_EXECUTION_INELIGIBLE,
-            message: "this run declares merge_execution_mode: github_actions, and the Bridge API " +
-                "conductor readiness report could not be read, so the repository's merge " +
+            message: "this run declares merge_execution_mode: github_actions, and the Epic " +
+                "Implementer readiness report could not be read, so the repository's merge " +
                 "capability could not be confirmed. Retry once the server is reachable. If " +
                 "readiness then reports the merge workflow missing or out of date, resolve it " +
                 `with \`${MERGE_WORKFLOW_REMEDY_COMMAND}\`. ${MERGE_WORKFLOW_CODEOWNER_INSTRUCTION} ` +
@@ -1555,6 +1833,9 @@ export function composeDefaultSetupEpicPolicy(args) {
             policy[SETUP_EPIC_INTEGRATION_PREPARATION_POLICY_KEY] = {
                 ...SETUP_EPIC_INTEGRATION_PREPARATION_DEFAULT,
             };
+            if (args.verificationHandoff !== undefined) {
+                Object.assign(policy, verificationHandoffPolicyKeys(args.verificationHandoff));
+            }
         }
     }
     if (args.reviewPolicy !== undefined) {
@@ -1698,13 +1979,13 @@ async function applyReusedRunPolicy(args) {
     });
     if (outcome.kind === "noop") {
         args.result.policy_applied = "noop";
-        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored");
+        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored", args.notificationSink);
         args.say("Policy:     policy unchanged");
         return true;
     }
     if (outcome.kind === "refused_divergent") {
         args.result.policy_applied = "refused_divergent";
-        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored");
+        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored", args.notificationSink);
         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` +
@@ -1717,7 +1998,7 @@ async function applyReusedRunPolicy(args) {
     }
     catch (err) {
         args.result.policy_applied = "refused_divergent";
-        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored");
+        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored", args.notificationSink);
         args.deps.errorLog(`Failed to replace the run policy: ${errorDetail(err)}`);
         return false;
     }
@@ -1981,6 +2262,9 @@ export async function runSetupEpicWorkflow(argv, overrides = {}, handoff) {
         exitCode,
         ...(sink.epicRunId !== undefined ? { epicRunId: sink.epicRunId } : {}),
         ...(sink.epicRunId !== undefined ? { runExists: true } : {}),
+        ...(sink.runCreated !== undefined ? { runCreated: sink.runCreated } : {}),
+        ...(sink.planStored !== undefined ? { planStored: sink.planStored } : {}),
+        ...(sink.reusedExistingRun !== undefined ? { reusedExistingRun: sink.reusedExistingRun } : {}),
     };
 }
 /**
@@ -2081,12 +2365,16 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         }
     }
     let existingRunId = null;
+    let existingTicketReview;
     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;
+    // The same response's engine-reported notification facts (never the redacted
+    // policy's `notify`), for the stored-policy channel label.
+    let existingNotificationSink = null;
     if (!opts.localOnly) {
         // --- Resolve access ------------------------------------------------------
         // BAPI-1260: a caller that selected the epic-launch contract (drive-epic
@@ -2116,7 +2404,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         access = accessResult.access;
         say(`Epic:       ${opts.epicKey}`);
         say(`Repo:       ${access.repoName}`);
-        say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${plan.edges.length} edge(s)`);
+        say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${countDeclaredOrderingPairs(plan)} edge(s)`);
         say(`Local hash: ${localHash}`);
         for (const w of warnings)
             say(`  [warn] ${w}`);
@@ -2128,9 +2416,11 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         try {
             const state = await fetchEpicRunState(access, opts.epicKey, deps.fetch);
             existingRunId = state.epic_run?.epic_run_id ?? null;
+            existingTicketReview = state.epic_run?.ticket_review;
             existingStatus = state.epic_run?.status ?? null;
             const existingPolicy = state.epic_run?.policy_json;
             existingPolicyJson = existingPolicy ?? null;
+            existingNotificationSink = state.notification_sink ?? null;
             const existingBase = existingPolicy && typeof existingPolicy === "object"
                 ? existingPolicy.base_branch
                 : undefined;
@@ -2170,6 +2460,22 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             }
         }
     }
+    // BAPI-1510 — attach-only reuse. A caller that trimmed the plan must never apply
+    // it to a run that already exists, so a pre-check that found a live run returns
+    // here, before the policy file, any cut, plan store, approval, or other mutation.
+    // A dry run keeps its ordinary reporting. Direct setup-epic never sets the option.
+    //
+    // Only an ACTIVATED run is attach-only. A run still in `planning` or
+    // `pending_approval` was created by an earlier setup that failed a later step
+    // (cut, plan store, approval); re-running setup is how it gets finished, so it
+    // takes the ordinary reuse path with the trimmed plan, guarded by the pinned cut.
+    const reusedRunIsActivated = existingStatus !== null && existingStatus !== "planning" && existingStatus !== "pending_approval";
+    if (existingRunId && reusedRunIsActivated && handoff?.attachOnlyOnReuse === true && !opts.dryRun) {
+        runIdSink.epicRunId = existingRunId;
+        runIdSink.reusedExistingRun = true;
+        say(`Run:        reusing ${existingRunId} (status: ${existingStatus}); existing runs are unchanged`);
+        return 0;
+    }
     // --- 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
@@ -2240,6 +2546,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         policyDeclaresBranch,
         featureBranch,
         reviewPolicy: opts.reviewPolicy,
+        ...(opts.verificationHandoff !== undefined ? { verificationHandoff: opts.verificationHandoff } : {}),
     });
     if (!policyGate.ok) {
         deps.errorLog(policyGate.message);
@@ -2252,7 +2559,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         // The policy gate above already composed and validated; nothing is repeated
         // here, so the offline path and the real path refuse the same set.
         say(`Epic:       ${opts.epicKey}`);
-        say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${plan.edges.length} edge(s)`);
+        say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${countDeclaredOrderingPairs(plan)} edge(s)`);
         // BAPI-1009: the same node-count-derived strategy an ordinary run would take,
         // stated without cutting a branch, reading the network, or touching git.
         say(`Branch:     ${branchStrategyLine}`);
@@ -2336,8 +2643,21 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             attended: opts.attended,
             reviewPolicy: opts.reviewPolicy,
             mergeExecutionMode: declaredMergeExecutionMode,
+            ...(opts.verificationHandoff !== undefined ? { verificationHandoff: opts.verificationHandoff } : {}),
         });
-    const selectedEffectivePolicyFacts = effectivePolicyFacts(existingRunId !== null ? existingPolicyJson : composedForCreate, selectedPolicySource);
+    // Reuse the actual composition result; drive-epic never interprets policy files.
+    let launchReadiness = null;
+    if (!opts.localOnly) {
+        try {
+            launchReadiness = await previewLaunchReadiness(access, existingRunId !== null ? existingPolicyJson ?? {} : composedForCreate, deps.fetch);
+        }
+        catch {
+            // An unavailable preview is not a proven launch deficiency. Create is authoritative.
+            launchReadiness = null;
+        }
+    }
+    const selectedTicketReview = ticketReviewSummary(existingTicketReview, existingRunId !== null ? existingPolicyJson ?? {} : composedForCreate);
+    const selectedEffectivePolicyFacts = effectivePolicyFacts(existingRunId !== null ? existingPolicyJson : composedForCreate, selectedPolicySource, existingRunId !== null ? existingNotificationSink : undefined);
     say(`Policy:     effective ${selectedEffectivePolicyFacts.source}; serial execution; ` +
         `caps ${selectedEffectivePolicyFacts.caps ? JSON.stringify(selectedEffectivePolicyFacts.caps) : "unavailable"}; ` +
         `timeouts ${selectedEffectivePolicyFacts.job_timeouts ? JSON.stringify(selectedEffectivePolicyFacts.job_timeouts) : "unavailable"}; ` +
@@ -2393,6 +2713,15 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
     // dropping `--feature-branch` reuses the run only when the flag is what asked
     // for the branch; when the DEFAULT asked, `--into-base` is the way to say
     // "keep this run on base".
+    // BAPI-1496 — the hand-off flags compose a NEW run's policy only. A live run's
+    // policy changes through `patch-policy`; reusing it here would either drop the
+    // owner's answer silently or patch a live run behind the operator's back.
+    if (existingRunId && opts.verificationHandoff !== undefined) {
+        deps.errorLog(`Epic ${opts.epicKey} already has a live run (${existingRunId}). --verification-handoff ` +
+            "sets the policy of a NEW run only. Change a live run's verification hand-off with " +
+            "`epic-implementer patch-policy`, or re-run without --verification-handoff to reuse it.");
+        return 1;
+    }
     if (existingRunId && featureBranch !== undefined && existingBaseBranch !== featureBranch) {
         const reuseAdvice = opts.featureBranch !== undefined
             ? "Re-run without --feature-branch to reuse it unchanged"
@@ -2449,7 +2778,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         return 1;
     }
     if (opts.reviewPolicy !== undefined) {
-        say(`Review:     ${opts.reviewPolicy} (per-run; repository defaults pending BAPI-694)`);
+        say(`Review:     ${opts.reviewPolicy} (per-run only; no repository default is stored)`);
     }
     // --- Authoritative server validation (BAPI-754) --------------------------
     // Runs BEFORE any create. A plan the server would refuse must not cost a run
@@ -2607,7 +2936,9 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             say("            serialization disabled — no ordering was derived from file overlap");
         }
         else if (validated.insertedEdges === 0) {
-            say("            serialization enabled — no declared file overlaps produced edges");
+            say(validated.overlappingPairsFound > 0
+                ? `            serialization enabled — ${validated.overlappingPairsFound} overlapping pair(s) already ordered by declared dependencies`
+                : "            serialization enabled — no declared file overlaps produced edges");
         }
         else {
             say(`            serialization enabled — ${validated.insertedEdges} edge(s) inserted from ` +
@@ -2658,6 +2989,23 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         cutCommitSha = truth.cutCommitSha;
         say(`Cut:        ${cutCommitSha} (canonical indexed commit; origin/${effectiveFeatureBranch} will be cut here)`);
     }
+    // BAPI-1510 — pinned cut. A trimmed launch classified children against ONE
+    // indexed commit; refuse unless setup's own canonical read names that same commit.
+    // This runs even when trimming left a base-branch or single-node launch that
+    // would not otherwise read canonical parse truth, and before any create-side
+    // effect (including on a dry run).
+    if (handoff?.expectedCutCommitSha !== undefined) {
+        let observedCut = cutCommitSha;
+        if (observedCut === null) {
+            const pinTruth = await readCanonicalParseTruth(access, deps.fetch);
+            observedCut = pinTruth.ok ? pinTruth.cutCommitSha : null;
+        }
+        if (observedCut === null || observedCut !== handoff.expectedCutCommitSha) {
+            deps.errorLog("The indexed commit could not be confirmed or changed since the already-merged check. " +
+                "Re-run drive-epic. No run was created and no branch was changed.");
+            return 1;
+        }
+    }
     if (opts.dryRun) {
         say("");
         say(validated
@@ -2675,7 +3023,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 : `  - feature branch: ${effectiveFeatureBranch} (validated server-side at approval; no request made in dry-run)`);
             if (needsCut && cutCommitSha !== null && scopeBaseBranch !== null) {
                 say(`  - would open a draft pull request ${effectiveFeatureBranch} → ${scopeBaseBranch} ` +
-                    "for epic-implementer-ci / gate (BAPI-951; nothing opened in dry-run)");
+                    "for epic-implementer-ci / gate (nothing opened in dry-run)");
             }
         }
         if (opts.reviewPolicy !== undefined) {
@@ -2698,6 +3046,11 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 // BAPI-850: the exact commit the cut WOULD use, reported without
                 // cutting. Present only when the dry run validated canonical parse truth.
                 ...(cutCommitSha !== null ? { cut_commit_sha: cutCommitSha } : {}),
+                // BAPI-1506: the repository base branch the epic branch is cut from
+                // (the configured base, else "main"). Only present for a
+                // feature-branch run; the launch preview compares the epic branch
+                // against it, information only.
+                ...(scopeBaseBranch !== null ? { scope_base_branch: scopeBaseBranch } : {}),
                 // Only present when a policy was explicitly selected — the
                 // no-policy JSON shape is unchanged.
                 ...(opts.reviewPolicy !== undefined
@@ -2708,6 +3061,8 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 server_validated: validated !== null,
                 policy_applied: "absent",
                 effective_policy: selectedEffectivePolicyFacts,
+                launch_readiness: launchReadiness,
+                ticket_review: selectedTicketReview,
                 ...(validated
                     ? {
                         server_plan_hash: validated.planHash,
@@ -2791,6 +3146,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
         // BAPI-1102 — the reuse path's authoritative id, taken from the pre-check's
         // server response rather than from anything local.
         runIdSink.epicRunId = existingRunId;
+        runIdSink.reusedExistingRun = true;
         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.
@@ -2802,6 +3158,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 result,
                 epicRunId: existingRunId,
                 storedPolicy: existingPolicyJson,
+                notificationSink: existingNotificationSink,
                 requestedPolicy,
                 replacePolicy: opts.replacePolicy,
             });
@@ -2837,7 +3194,13 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             try {
                 readiness = await fetchConductorReadiness(access, deps.fetch);
             }
-            catch {
+            catch (err) {
+                // BAPI-1455 — the one readable refusal: a proven-incompatible local
+                // schema. Its explanation is server-authored from a maintained list.
+                if (isSchemaIncompatibleError(err)) {
+                    deps.errorLog(formatSchemaIncompatibleRefusal("setup-epic", err).join("\n"));
+                    return 1;
+                }
                 // Fail CLOSED, and silently as to WHY: the thrown value can carry a URL
                 // or a response excerpt, and this refusal is rendered to a terminal. The
                 // generic `readiness_unreadable` message says what to do about it.
@@ -2908,6 +3271,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             // returns the server's run for a fresh creation AND for a create-race
             // adoption (`created: false`), so both are captured by this one assignment.
             runIdSink.epicRunId = run.epic_run_id;
+            runIdSink.runCreated = created;
             result.status = run.status;
             result.run_created = created;
             if (created) {
@@ -2927,10 +3291,15 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 // index is the race backstop that keeps it so. Naming the adopted run and
                 // its status, rather than reporting a bare reuse, is what lets an operator
                 // decide between continuing on it and closing it.
+                runIdSink.reusedExistingRun = true;
                 say(`Run:        adopting existing active run ${run.epic_run_id} (status: ${run.status})`);
                 say(`            No second run was created — one epic has at most one active ` +
                     `run. Continue on this one, or abandon it first with ` +
                     `\`epic-implementer abandon-run --epic-run-id ${run.epic_run_id}\` to start over.`);
+                // BAPI-1510 — attach-only: a race-adopted run is never touched by a
+                // trimmed launch (no policy replacement, cut, plan store, or approval).
+                if (handoff?.attachOnlyOnReuse === true)
+                    return 0;
                 if (requestedPolicy !== undefined) {
                     const outcome = await applyReusedRunPolicy({
                         access,
@@ -3108,6 +3477,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
             ...(trackedPathEvidence !== undefined ? { trackedPaths: trackedPathEvidence } : {}),
         }, deps.fetch);
         result.plan_stored = true;
+        runIdSink.planStored = true;
         const serverHash = stored?.plan_hash;
         if (typeof serverHash === "string")
             result.plan_hash = serverHash;
@@ -3161,7 +3531,7 @@ async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
                 `Turn 'Allow unattended Epic Implementer runs' back on in the repository's ` +
                 `Setup page in the Bridge admin panel and re-run setup-epic, or ` +
                 `deliberately convert this run to an attended posture through the ` +
-                `supported operator flow. If it is already on, contact Bridge support.` +
+                `supported operator flow. If it is already on, email info@bridgegpt.ai.` +
                 `\nDetail: ${errorDetail(err)}`);
         }
         else {