@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/setup-epic.js

@@ -78,7 +78,8 @@
 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
@@ -209,10 +210,11 @@ 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 one-time repository prerequisites, refused by name",
-        "before any run is created: repository consent (unattended_epic_implementer_allowed) and",
-        "a verified notify webhook default. `drive-epic` readiness lists both with their",
-        "current state.",
+        "Unattended runs have TWO 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.",
         "",
         "Required:",
         "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
@@ -261,7 +263,8 @@ export function getSetupEpicUsage() {
         "  --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; there is no production default with it.",
+        "                         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.",
         "  -h, --help             Show this help",
         "",
@@ -1115,6 +1118,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}`;
@@ -1235,10 +1256,10 @@ export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPol
     if (!unattended.conductor_allowed) {
         return {
             reason: "target_not_allowed",
-            message: "this repository has not consented to unattended conductor runs. Set " +
-                "`unattended_epic_implementer_allowed` for it (see " +
-                "docs/claude/account-settings-operator-runbook.md), or pass --attended to " +
-                "create an attended run. No run was created.",
+            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.",
         };
     }
     // Two independent sources satisfy the escalation channel, and the check has to
@@ -1253,13 +1274,21 @@ export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPol
     // Presence, not verification: the server probes the URL at activation and is
     // the authority on whether it is reachable. This gate exists to spare the
     // operator a created-and-refused run, not to duplicate the probe.
+    //
+    // BAPI-1274 — a third source: when no webhook is declared anywhere, the
+    // account's email address is the escalation channel, and the server reports
+    // its presence (never the address). A declared webhook stays authoritative;
+    // email only fills the gap when none is declared. `notify.local_sink` still
+    // satisfies nothing.
     if (!unattended.notify_webhook_default_declared &&
-        !policyDeclaresNotifyWebhook(requestedPolicy)) {
+        !policyDeclaresNotifyWebhook(requestedPolicy) &&
+        unattended.escalation_email_available !== true) {
         return {
             reason: "webhook_unverified",
-            message: "an unattended run must have a verified escalation channel, and neither this " +
-                "repository nor this run declares one. Supply a --policy-file declaring " +
-                "notify.webhook_url (notify.local_sink does not satisfy this), or pass " +
+            message: "an unattended run must have an escalation channel, and this repository, this " +
+                "run, and the account provide none. Supply a --policy-file declaring " +
+                "notify.webhook_url (notify.local_sink does not satisfy this), or add an email " +
+                "address to the account so escalation alerts can be emailed, or pass " +
                 "--attended to create an attended run. No run was created.",
         };
     }
@@ -1551,12 +1580,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
@@ -1578,11 +1602,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` +
@@ -1595,10 +1621,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);
@@ -1850,12 +1878,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 } : {}),
     };
 }
 /**
@@ -1865,7 +1894,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") {
@@ -1881,6 +1910,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 {
@@ -1912,18 +1949,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);
@@ -1953,7 +2109,7 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
     const policyGate = preflightSetupEpicPolicy({
         intoBase: opts.intoBase,
         attended: opts.attended,
-        policyFile: opts.policyFile,
+        policyFile: selectedPolicyPath,
         filePolicy,
         policyDeclaresBranch,
         featureBranch,
@@ -1991,42 +2147,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
@@ -2083,6 +2211,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
@@ -2118,59 +2251,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
@@ -2498,6 +2578,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,
@@ -2569,6 +2650,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
@@ -2946,10 +3028,11 @@ async function executeSetupEpic(argv, overrides, runIdSink) {
             deps.errorLog(`The plan was NOT approved: this repository is no longer authorized for ` +
                 `unattended runs. The run WAS created and is left in 'planning' with no ` +
                 `activation and no executor dispatch — nothing was half-applied.\n` +
-                `Restore \`unattended_epic_implementer_allowed\` for this repository (see ` +
-                `docs/claude/account-settings-operator-runbook.md) and re-run setup-epic, ` +
-                `or deliberately convert this run to an attended posture through the ` +
-                `supported operator flow.\nDetail: ${errorDetail(err)}`);
+                `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.` +
+                `\nDetail: ${errorDetail(err)}`);
         }
         else {
             deps.errorLog(`Failed to approve the plan: ${errorDetail(err)}`);
@@ -3117,14 +3200,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/setup-status.js

@@ -6,6 +6,7 @@
  * prevent the others from running.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
+import { publishSfccVersion } from "./tools-configured.js";
 import { getAmToken } from "./client.js";
 // ---------------------------------------------------------------------------
 // Implementation
@@ -38,6 +39,7 @@ export async function sfccSetupStatusTool(deps) {
     if (apiKeyOk && repoOk) {
         try {
             resolvedVersion = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
+            publishSfccVersion(resolvedVersion);
             if (resolvedVersion === null) {
                 versionStatus = "✗ Not set (configure the 'version' field in Bridge API project settings)";
             }

package/build/sfcc/tool-wrapper.js

@@ -62,6 +62,7 @@
  * no per-tool opt-in and no exemption flag.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
+import { publishSfccVersion } from "./tools-configured.js";
 import { resolveSfccCredentials } from "./credentials.js";
 import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
@@ -385,6 +386,7 @@ export function withSfccGate(deps, handler) {
         }
         // (a) Read /config-field/version
         const version = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
+        publishSfccVersion(version);
         if (version === null) {
             return notConfigured("bridge-auth", "Could not read the SFCC version from Bridge API (/config-field/version). " +
                 "Ensure your Bridge API key is set and the repo is configured. " +

package/build/sfcc/tools-configured.js

@@ -0,0 +1,96 @@
+/** Process-local, secret-free SFCC setup verdict for authenticated Bridge requests. */
+import { access } from "fs/promises";
+import { constants } from "fs";
+import path from "path";
+import { resolveSfccCredentials } from "./credentials.js";
+import { getSfccVersionConfig, SFCC_VERSIONS } from "./config.js";
+const DIAGNOSTIC = "SFCC tools header omitted: version lookup did not establish SFCC setup; check setup status.";
+/** Existence and readability are enough to establish the local gate. */
+export async function hasRootDwJson() {
+    try {
+        await access(path.join(process.cwd(), "dw.json"), constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Isolated state is injectable for offline tests; the MCP uses one instance. */
+export function createSfccToolsHeaderState(deps) {
+    let credentialVerdict;
+    let knownVersion;
+    let lookupStarted = false;
+    let diagnosticPrinted = false;
+    function getCredentialVerdict() {
+        credentialVerdict ??= Promise.resolve().then(() => deps.resolveCredentials(deps.env, {
+            ...deps.credentialDeps,
+            writeFile: async () => { },
+            mkdir: async () => { },
+        })).then((result) => result.ok ? "yes" : "no")
+            .catch(() => "no");
+        return credentialVerdict;
+    }
+    function publishVersion(version) {
+        if (version !== null && knownVersion === undefined)
+            knownVersion = version;
+        if (version !== null && SFCC_VERSIONS.includes(version))
+            knownVersion = version;
+    }
+    function reportUnresolved() {
+        if (diagnosticPrinted)
+            return;
+        diagnosticPrinted = true;
+        deps.diagnostic(DIAGNOSTIC);
+    }
+    async function withHeader(headers, options) {
+        if (options.skipSfccToolsHeader)
+            return headers;
+        try {
+            const localFile = await deps.hasDwJson();
+            if (knownVersion === undefined && !lookupStarted && options.repoName) {
+                lookupStarted = true;
+                void deps.getVersion(options.buildGetUrl, options.getLookupHeaders, options.repoName)
+                    .then((version) => {
+                    if (version !== null)
+                        publishVersion(version);
+                    if (knownVersion === undefined) {
+                        knownVersion = null;
+                        if (!localFile)
+                            reportUnresolved();
+                    }
+                })
+                    .catch(() => {
+                    if (knownVersion === undefined) {
+                        knownVersion = null;
+                        if (!localFile)
+                            reportUnresolved();
+                    }
+                });
+            }
+            const isSfcc = knownVersion !== undefined && knownVersion !== null
+                && SFCC_VERSIONS.includes(knownVersion);
+            if (!localFile && !isSfcc) {
+                if (!options.repoName)
+                    reportUnresolved();
+                return headers;
+            }
+            headers["X-Bridge-SFCC-Tools"] = await getCredentialVerdict();
+        }
+        catch {
+            // Optional enrichment cannot interrupt authenticated requests.
+        }
+        return headers;
+    }
+    return { getCredentialVerdict, publishVersion, withHeader };
+}
+const processState = createSfccToolsHeaderState({
+    hasDwJson: hasRootDwJson,
+    resolveCredentials: (env, credentialDeps) => resolveSfccCredentials(undefined, env, credentialDeps),
+    credentialDeps: {},
+    env: process.env,
+    getVersion: getSfccVersionConfig,
+    diagnostic: (message) => console.error(message),
+});
+export const getSfccCredentialVerdict = processState.getCredentialVerdict;
+export const publishSfccVersion = processState.publishVersion;
+export const withSfccToolsHeader = processState.withHeader;