@bridge_gpt/mcp-server 0.2.65 → 0.2.67

package/build/setup-epic.js

@@ -1,10 +1,14 @@
 /**
- * `setup-epic` — one-command bootstrap for an Epic Conductor v2 run.
+ * `setup-epic` — one-command bootstrap for an Epic Implementer run.
  *
  * Creates the epic run, stores the plan DAG, and approves it. Before this
- * existed the only path was hand-rolled HTTP with a hand-computed plan hash,
- * which is why the shipped `store-and-approve-epic-plan` pipeline step told the
- * agent to "make a direct API call" — there was no tool to call.
+ * existed the only path was hand-rolled HTTP with a hand-computed plan hash —
+ * there was no tool to call.
+ *
+ * This is a separate run-creation workflow, not a `/plan-epic` pipeline step:
+ * `/plan-epic` authors the local sidecar and stops. An operator creates the child
+ * tickets, finalizes the plan, and then launches through the gated `drive-epic`
+ * entry point, which is what reaches this command.
  *
  * Ordering is load-bearing:
  *
@@ -78,14 +82,16 @@
 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, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
+import { approveEpicPlan, buildConductorJiraUrl, conductorGetHeaders, createEpicRunWithDisposition, decodeCanonicalProvenance, fetchConductorReadiness, 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:
 // that module never imports from `setup-epic.ts`). Reused here rather than
 // reimplemented so the mapping stays single-defined.
 import { mapLegacyMergeExecutionModeToPolicyMode, resolveMergeExecutionMode, } from "./merge-pull-request.js";
-import { MERGE_EXECUTION_INELIGIBLE, MERGE_EXECUTION_MODE_GITHUB_ACTIONS, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
+import { MERGE_EXECUTION_INELIGIBLE, MERGE_EXECUTION_MODE_GITHUB_ACTIONS, MERGE_WORKFLOW_CODEOWNER_INSTRUCTION, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
 import { classifyMergeExecutionEligibility } from "./conductor/merge-execution-eligibility.js";
+import { repositoryWorkflowRemedy } from "./conductor/repository-workflow-remedy.js";
 import { resolveTrackedPaths } from "./git-reachability.js";
 import { validateBranchName } from "./base-ref.js";
 // Reused from the implement-epic client on purpose: adding a second wrapper under
@@ -99,6 +105,7 @@ import { validateBranchName } from "./base-ref.js";
 import { getConfigFieldBaseBranch, getIndexScopeLifecycle, getParseStatus, } from "./epic-shared/bridge-client.js";
 import { boundScopeLifecycleLabel, createExecFileRunCommand, ensureCommitResolvableLocally, performExactIndexScopeCut, pollIndexScopeLifecycle, readRemoteBranchHead, runGit, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_LIFECYCLE_LABELS, } from "./epic-shared/cut-protocol.js";
 import { hashPlan } from "./conductor/plan.js";
+import { PLACEHOLDER_NODE_KEY_RE } from "./conductor-bundle-artifacts.js";
 import { BRING_UP_REFUSAL_MESSAGES, firstBringUpRefusal, } from "./conductor/bring-up-facts.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // BAPI-872: local plane-manifest binding, so `plane down` can later stop the
@@ -189,7 +196,7 @@ export function getSetupEpicUsage() {
     return [
         "Usage: mcp-server setup-epic --epic-key <KEY> --plan-file <path> [options]",
         "",
-        "Bootstraps an Epic Conductor v2 run: creates the run, stores the plan DAG,",
+        "Bootstraps an Epic Implementer run: creates the run, stores the plan DAG,",
         "and approves it. Idempotent — re-running reuses an existing live run.",
         "",
         "Branch strategy (default): a plan with TWO OR MORE nodes runs on a dedicated",
@@ -209,11 +216,12 @@ export function getSetupEpicUsage() {
         "that selects no epic branch (--into-base, or a single-node plan) is unchanged",
         "and composes no posture at all.",
         "",
-        "Unattended runs have TWO repository prerequisites, refused by name before any",
-        "run is created: repository consent (ON by default; the repository owner can",
+        "Unattended runs have THREE repository prerequisites, refused by name before",
+        "any run is created: repository consent (ON by default; the repository owner can",
         "switch 'Allow unattended Epic Implementer runs' off and on in the Bridge admin",
-        "panel's Setup page) and a verified notify webhook default. `drive-epic`",
-        "readiness lists both with their current state.",
+        "panel's Setup page); an escalation channel, either a verified notify webhook or",
+        "the account's email address; and confirmed review and CI workflows on the",
+        "default branch. `drive-epic` readiness lists all three with their current state.",
         "",
         "Required:",
         "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
@@ -278,7 +286,7 @@ export function getSetupEpicUsage() {
         "                         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/claude/epic-implementer-v2-operator-runbook.md §4.",
+        "                         docs/epic-implementer/operator-runbook.md §4.",
         "  --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",
@@ -296,8 +304,8 @@ export function getSetupEpicUsage() {
         "                         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 ${MCP_PACKAGE_NAME} executor --repo <name>`,
+        "To execute this run's claimed jobs on this machine, run:",
+        `  npx -y ${MCP_PACKAGE_NAME} executor --repo <name> --epic-run-id <run-id>`,
     ].join("\n");
 }
 function takeValue(argv, i, flag) {
@@ -987,6 +995,20 @@ export function validateEpicPlanSidecar(parsed) {
                 `to get that scheduling protection (use [] when no files are predicted).`);
         }
     }
+    // BAPI-1366: refuse unfinalized `TBD-N` node keys before any graph, access, or
+    // network work. `/plan-epic` authors placeholders; finalization replaces them.
+    // This runs here, not in the server lane, so an updated client refuses even
+    // against an older server and in `--dry-run --local-only`.
+    const placeholders = [...keys].filter((key) => PLACEHOLDER_NODE_KEY_RE.test(key)).sort();
+    if (placeholders.length > 0) {
+        return {
+            ok: false,
+            error: `Plan node keys ${placeholders.join(", ")} are placeholders, not tickets. ` +
+                `Create the child tickets and run \`emit-epic-implementer-bundle finalize\` ` +
+                `to replace every placeholder, then run this again (this invocation created ` +
+                `no run, cut no branch, and incurred no charge).`,
+        };
+    }
     // Build one adjacency in a consistent predecessor -> successor direction, the
     // same way the server does. `depends_on` points at the predecessor; an edge's
     // `from` IS the predecessor.
@@ -1117,6 +1139,24 @@ function findCycle(keys, adjacency) {
     }
     return null;
 }
+export function effectivePolicyFacts(policy, source) {
+    const object = policy && typeof policy === "object" && !Array.isArray(policy)
+        ? policy : {};
+    const numbers = (value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return null;
+        const entries = Object.entries(value).filter(([key, item]) => /^[a-z][a-z0-9_]{0,63}$/.test(key) && typeof item === "number" && Number.isFinite(item));
+        return entries.length ? Object.fromEntries(entries) : null;
+    };
+    return {
+        source,
+        serial_execution: "serial",
+        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"),
+    };
+}
 /** Propose a conductor epic feature branch name for an epic key (BAPI-655). */
 export function proposeFeatureBranchName(epicKey) {
     return `epic/${epicKey}`;
@@ -1274,12 +1314,13 @@ export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPol
         };
     }
     if (!unattended.repository_readiness_confirmed) {
+        // BAPI-1359: the shared formatter names the specific missing item; the reason
+        // code and the trailing sentence are unchanged.
         return {
             reason: "repository_readiness_unconfirmed",
             message: "the unattended default authorizes automatic merge, which requires the review and " +
-                "conductor-CI workflows to be CONFIRMED on the default branch, and they are not. " +
-                "Run `install-bridge conductor` to install them, or pass --attended to create an " +
-                "attended run. No run was created.",
+                "epic-implementer-ci workflows to be CONFIRMED on the default branch, and they are not. " +
+                `${repositoryWorkflowRemedy(readiness)} No run was created.`,
         };
     }
     return null;
@@ -1352,8 +1393,10 @@ export function evaluateSetupEpicMergeExecutionPrerequisites(readiness, requeste
             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 " +
-                "capability could not be confirmed. Retry once the server is reachable, or " +
-                `resolve it with \`${MERGE_WORKFLOW_REMEDY_COMMAND}\`. ${NO_RUN_WAS_CREATED}`,
+                "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} ` +
+                NO_RUN_WAS_CREATED,
         };
     }
     const verdict = classifyMergeExecutionEligibility(readiness);
@@ -1366,7 +1409,8 @@ export function evaluateSetupEpicMergeExecutionPrerequisites(readiness, requeste
         reason: MERGE_EXECUTION_INELIGIBLE,
         message: "this run declares merge_execution_mode: github_actions, and this repository's " +
             `merge capability ${category}: ${verdict.detail}. Resolve it with ` +
-            `\`${MERGE_WORKFLOW_REMEDY_COMMAND}\`, then re-run. ${NO_RUN_WAS_CREATED}`,
+            `\`${MERGE_WORKFLOW_REMEDY_COMMAND}\`, then re-run. ` +
+            `${MERGE_WORKFLOW_CODEOWNER_INSTRUCTION} ${NO_RUN_WAS_CREATED}`,
     };
 }
 /**
@@ -1561,12 +1605,7 @@ composesDefaultPolicy = true) {
         `(pass --feature-branch to force ${proposeFeatureBranchName(opts.epicKey)} anyway)`);
 }
 function errorDetail(err) {
-    if (err instanceof ConductorBridgeApiError) {
-        const status = err.status !== undefined ? ` (HTTP ${err.status})` : "";
-        const preview = err.bodyPreview ? `: ${err.bodyPreview}` : "";
-        return `${err.message}${status}${preview}`;
-    }
-    return err instanceof Error ? err.message : String(err);
+    return safeDiagnosticMessage(err, "operation failed");
 }
 /**
  * Reconcile a policy file against a REUSED run's stored policy, applying it only
@@ -1588,11 +1627,13 @@ async function applyReusedRunPolicy(args) {
     });
     if (outcome.kind === "noop") {
         args.result.policy_applied = "noop";
+        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored");
         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.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` +
@@ -1605,10 +1646,12 @@ async function applyReusedRunPolicy(args) {
     }
     catch (err) {
         args.result.policy_applied = "refused_divergent";
+        args.result.effective_policy = effectivePolicyFacts(args.storedPolicy, "stored");
         args.deps.errorLog(`Failed to replace the run policy: ${errorDetail(err)}`);
         return false;
     }
     args.result.policy_applied = "replaced";
+    args.result.effective_policy = effectivePolicyFacts(args.requestedPolicy, "explicit");
     args.say("Policy:     policy applied: replaced");
     for (const line of outcome.diffLines)
         args.say(line);
@@ -1860,12 +1903,13 @@ function describeScopeTransition(state, status) {
  * {@link runSetupEpicCli} in every observable way — same output, same refusals,
  * same exit codes — and differs only in what it hands back.
  */
-export async function runSetupEpicWorkflow(argv, overrides = {}) {
+export async function runSetupEpicWorkflow(argv, overrides = {}, handoff) {
     const sink = {};
-    const exitCode = await executeSetupEpic(argv, overrides, sink);
+    const exitCode = await executeSetupEpic(argv, overrides, sink, handoff);
     return {
         exitCode,
         ...(sink.epicRunId !== undefined ? { epicRunId: sink.epicRunId } : {}),
+        ...(sink.epicRunId !== undefined ? { runExists: true } : {}),
     };
 }
 /**
@@ -1875,7 +1919,7 @@ export async function runSetupEpicWorkflow(argv, overrides = {}) {
 export async function runSetupEpicCli(argv, overrides = {}) {
     return (await runSetupEpicWorkflow(argv, overrides)).exitCode;
 }
-async function executeSetupEpic(argv, overrides, runIdSink) {
+async function executeSetupEpic(argv, overrides, runIdSink, handoff) {
     const deps = { ...createDefaultSetupEpicDeps(), ...overrides };
     const parsed = parseSetupEpicArgs(argv);
     if (parsed.status === "help") {
@@ -1891,6 +1935,14 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
     const opts = parsed.options;
     // With --json, stdout carries the single result object and nothing else.
     const say = opts.json ? deps.errorLog : deps.log;
+    if (handoff && (handoff.access.baseUrl !== handoff.selection.baseUrl ||
+        handoff.access.repoName !== handoff.selection.repoName ||
+        (opts.baseUrl !== undefined && opts.baseUrl !== handoff.selection.baseUrl) ||
+        (opts.repo !== undefined && opts.repo !== handoff.selection.repoName) ||
+        (opts.launchProfile !== undefined && opts.launchProfile !== handoff.selection.profileName))) {
+        deps.errorLog("setup-epic REFUSED (selection-conflict): delegated target or repository disagrees with the pinned launch selection.");
+        return 1;
+    }
     // --- Read + validate the plan sidecar (no network yet) -------------------
     let raw;
     try {
@@ -1922,18 +1974,137 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
         return 1;
     }
     const localHash = hashPlan(plan);
+    // Resolve the selected target and live-run identity before choosing a policy.
+    // The offline local-only path keeps its no-network contract.
+    let access;
+    let selectedProfilePolicyPath = handoff?.profile?.policyRef?.path;
+    if (opts.localOnly && !handoff) {
+        const profileName = opts.launchProfile ?? deps.env.BAPI_EPIC_LAUNCH_PROFILE?.trim();
+        if (profileName) {
+            const profileRead = await readEpicLaunchProfile(profileName, {
+                env: deps.env,
+                homedir: deps.homedir,
+                readFile: deps.readFile,
+                host: os.hostname(),
+            });
+            if (!profileRead.ok) {
+                deps.errorLog(profileRead.message);
+                return 1;
+            }
+            selectedProfilePolicyPath = profileRead.profile.policyRef?.path;
+        }
+    }
+    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;
+    if (!opts.localOnly) {
+        // --- Resolve access ------------------------------------------------------
+        // BAPI-1260: a caller that selected the epic-launch contract (drive-epic
+        // forwards --launch-profile / --base-url) gets the target-first resolver and
+        // the bound credential; the legacy resolver is kept byte-for-byte otherwise.
+        const accessDeps = {
+            env: deps.env,
+            cwd: deps.cwd,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+            repoName: opts.repo,
+        };
+        const accessResult = handoff
+            ? { ok: true, access: handoff.access, profile: handoff.profile }
+            : opts.launchProfile !== undefined || opts.baseUrl !== undefined || Boolean(deps.env.BAPI_EPIC_LAUNCH_PROFILE?.trim())
+                ? await resolveEpicLaunchBridgeApiAccess({
+                    ...(opts.launchProfile ? { profileName: opts.launchProfile } : {}),
+                    ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
+                }, accessDeps)
+                : await resolveConductorBridgeApiAccess(accessDeps);
+        if (!accessResult.ok) {
+            deps.errorLog(`Cannot reach the Bridge API: ${accessResult.error}`);
+            return 1;
+        }
+        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(`Local hash: ${localHash}`);
+        for (const w of warnings)
+            say(`  [warn] ${w}`);
+        selectedProfilePolicyPath = "profile" in accessResult
+            ? accessResult.profile?.policyRef?.path
+            : undefined;
+        // --- Step 0: pre-check ---------------------------------------------------
+        // Never create on an ambiguous read. A wrong answer here mints a duplicate run.
+        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) {
+                existingRunId = null; // No live run — the normal first-run path.
+            }
+            else if (err instanceof ConductorBridgeApiError && err.status === 409) {
+                deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — it is wedged, and every ` +
+                    `plan call will keep failing. Abandon the duplicate before retrying:\n` +
+                    `  epic-implementer abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
+                    `Detail: ${errorDetail(err)}`);
+                return 1;
+            }
+            else {
+                deps.errorLog(`Could not read the epic run state, so creating one would risk a duplicate ` +
+                    `(which wedges the epic permanently). Refusing to continue.\n` +
+                    `Detail: ${errorDetail(err)}`);
+                return 1;
+            }
+        }
+    }
     // --- 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;
+    const selectedPolicyPath = opts.policyFile ?? (existingRunId === null ? selectedProfilePolicyPath : undefined);
+    const selectedPolicySource = existingRunId !== null
+        ? "stored" : opts.policyFile !== undefined ? "explicit" : selectedProfilePolicyPath !== undefined ? "profile" : "default";
+    if (selectedPolicyPath !== undefined) {
+        const pinned = handoff ? getPinnedEpicLaunchPolicy(handoff.selection) : undefined;
+        if (pinned !== undefined) {
+            filePolicy = pinned;
+        }
+        else {
+            const policyRead = await readSetupEpicPolicyFile(selectedPolicyPath, deps.readFile);
+            if (!policyRead.ok) {
+                deps.errorLog(policyRead.error);
+                return 1;
+            }
+            filePolicy = policyRead.policy;
         }
-        filePolicy = policyRead.policy;
     }
     const policyDeclaresBranch = filePolicy !== undefined &&
         ["base_branch", "baseBranch"].some((key) => key in filePolicy && filePolicy[key] !== undefined && filePolicy[key] !== null);
@@ -1963,7 +2134,7 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
     const policyGate = preflightSetupEpicPolicy({
         intoBase: opts.intoBase,
         attended: opts.attended,
-        policyFile: opts.policyFile,
+        policyFile: selectedPolicyPath,
         filePolicy,
         policyDeclaresBranch,
         featureBranch,
@@ -2001,42 +2172,14 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
                 plan_version: plan.plan_version,
                 local_plan_hash: localHash,
                 server_validated: false,
+                feature_branch: opts.intoBase ? null : resolveEffectiveFeatureBranch(featureBranch, policyGate.policy) ?? null,
                 policy_applied: "absent",
+                effective_policy: effectivePolicyFacts(policyGate.policy, selectedPolicySource),
                 warnings,
             }, null, 2));
         }
         return 0;
     }
-    // --- Resolve access ------------------------------------------------------
-    // BAPI-1260: a caller that selected the epic-launch contract (drive-epic
-    // forwards --launch-profile / --base-url) gets the target-first resolver and
-    // the bound credential; the legacy resolver is kept byte-for-byte otherwise.
-    const accessDeps = {
-        env: deps.env,
-        cwd: deps.cwd,
-        homedir: deps.homedir,
-        platform: deps.platform,
-        readFile: deps.readFile,
-        stat: deps.stat,
-        repoName: opts.repo,
-    };
-    const accessResult = opts.launchProfile !== undefined || opts.baseUrl !== undefined
-        ? await resolveEpicLaunchBridgeApiAccess({
-            ...(opts.launchProfile ? { profileName: opts.launchProfile } : {}),
-            ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
-        }, accessDeps)
-        : await resolveConductorBridgeApiAccess(accessDeps);
-    if (!accessResult.ok) {
-        deps.errorLog(`Cannot reach the Bridge API: ${accessResult.error}`);
-        return 1;
-    }
-    const 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(`Local hash: ${localHash}`);
-    for (const w of warnings)
-        say(`  [warn] ${w}`);
     // --- Branch strategy (BAPI-1009) ----------------------------------------
     // Already resolved above, before the network was touched. Reported HERE, ahead
     // of any secondary policy detail, because it is the one decision that changes
@@ -2093,6 +2236,11 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
             reviewPolicy: opts.reviewPolicy,
             mergeExecutionMode: declaredMergeExecutionMode,
         });
+    const selectedEffectivePolicyFacts = effectivePolicyFacts(existingRunId !== null ? existingPolicyJson : composedForCreate, selectedPolicySource);
+    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"}; ` +
+        `channel ${selectedEffectivePolicyFacts.escalation_channel}`);
     // BAPI-1133 (A2). Reported only when THIS command stamped the key — i.e. it
     // is present in the composed policy and was absent from whatever the
     // operator supplied — as low-emphasis policy metadata, mirroring the
@@ -2128,59 +2276,6 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
         say(`Feature:    ${effectiveFeatureBranch} (from the policy file; cut on origin with local ` +
             `git at the canonical indexed commit; validated server-side at approval)`);
     }
-    // --- 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) {
-            existingRunId = null; // No live run — the normal first-run path.
-        }
-        else if (err instanceof ConductorBridgeApiError && err.status === 409) {
-            deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — it is wedged, and every ` +
-                `plan call will keep failing. Abandon the duplicate before retrying:\n` +
-                `  epic-implementer abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
-                `Detail: ${errorDetail(err)}`);
-            return 1;
-        }
-        else {
-            deps.errorLog(`Could not read the epic run state, so creating one would risk a duplicate ` +
-                `(which wedges the epic permanently). Refusing to continue.\n` +
-                `Detail: ${errorDetail(err)}`);
-            return 1;
-        }
-    }
     // --- Feature-branch conflict guard against an existing live run ----------
     // A selected branch that disagrees with the existing run's stored base branch
     // must fail closed rather than patch or silently change that run. A matching
@@ -2508,6 +2603,7 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
                 // "absent"; server_validated says whether the check was authoritative.
                 server_validated: validated !== null,
                 policy_applied: "absent",
+                effective_policy: selectedEffectivePolicyFacts,
                 ...(validated
                     ? {
                         server_plan_hash: validated.planHash,
@@ -2579,6 +2675,7 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
         plan_approved: false,
         server_validated: validated !== null,
         policy_applied: "absent",
+        effective_policy: selectedEffectivePolicyFacts,
         warnings,
     };
     // BAPI-850: the EFFECTIVE feature branch (flag or policy file), so a
@@ -3128,14 +3225,14 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
         else {
             say("The server-side reconciler will pick it up within ~30s.");
         }
-        // BAPI-1102 — the executor command is printed WITH a claim scope. Since
-        // BAPI-1026 an executor started with no scope REFUSES TO START, so the
-        // unscoped form printed here was guidance that could not work: an operator
-        // who copied it got a startup error, and the natural reading of that error is
-        // that the run is broken rather than that the instruction was.
-        say("To execute this run's claimed jobs on this machine, run:");
-        say(`  npx -y ${MCP_PACKAGE_NAME} executor --repo ${access.repoName} ` +
-            `--epic-run-id ${result.epic_run_id}`);
+        if (handoff) {
+            say("The launcher starts or reuses the executor appropriate for this run.");
+        }
+        else {
+            say("To execute this run's claimed jobs on this machine, run:");
+            say(`  npx -y ${MCP_PACKAGE_NAME} executor --repo ${access.repoName} ` +
+                `--epic-run-id ${result.epic_run_id}`);
+        }
     }
     return exitCode;
 }

package/build/sfcc/config.js

@@ -9,6 +9,15 @@
 export const SFCC_VERSIONS = ["sfra", "pwakit", "sitegenesis", "storefrontnext", "hybrid"];
 /** Pinned OCAPI Data API version used for all requests (configurable at call-time). */
 export const DEFAULT_OCAPI_VERSION = "v25_6";
+/**
+ * The `_v` value of the OCAPI Settings JSON an operator pastes in Business
+ * Manager. This is the settings-STRUCTURE version, not the OCAPI API version
+ * above; Business Manager rejects an API version here.
+ *
+ * UNVERIFIED: "23.2" is provisional until owner check OR-1 saves the emitted
+ * grant in Business Manager. If OR-1 shows a different value, change it here.
+ */
+export const OCAPI_SETTINGS_STRUCTURE_VERSION = "23.2";
 /** Account Manager OAuth2 token endpoint host. */
 export const AM_HOST = "account.demandware.com";
 /** AM OAuth2 token endpoint URL. */