@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/setup-epic.js

@@ -30,6 +30,31 @@
  *      file-overlap serialization, so a divergence is legitimate, not corruption.
  *   5. Store, then approve.
  *
+ * BAPI-850 — a FEATURE-BRANCH run (`policy_json.base_branch` set, whether by
+ * `--feature-branch` or by `--policy-file`) performs the full scope-bearing
+ * start sequence in this one invocation, in this order:
+ *
+ *   a. Read canonical parse truth (`GET /jira/parse-status`). No succeeded
+ *      parse or no indexed commit → exit 1 with "parse the repository first";
+ *      no run is created and no branch is changed.
+ *   b. Create the run as today (step 3) — FIRST, because a scope's run
+ *      association is immutable server-side and can never be attached later.
+ *   c. Cut or validate `origin/<feature>` at EXACTLY the canonical indexed SHA
+ *      with the operator's LOCAL `git`, through the shared cut protocol
+ *      `conduct-epic init` also drives, with the run id so the scope is minted
+ *      owned by the run. An existing branch at a different commit fails closed.
+ *      The GitHub App never pushes — it is `contents: read`.
+ *   d. Store and approve (unchanged requests). The server now READ-validates the
+ *      ref against the scope's recorded cut and schedules the seed + verifying
+ *      parse in the background; the run goes `active` immediately.
+ *   e. Poll the scope's lifecycle with a bounded wait, reporting
+ *      `Provisioning → Seeding → Verifying → Ready`. `failed` and a timeout
+ *      both exit 1; the reconciler's dispatch-freshness hold keeps an
+ *      un-ready scope from dispatching either way.
+ *
+ * A run with no feature branch is byte-identical to before: no parse read, no
+ * `git`, no scope, no polling, no extra JSON keys.
+ *
  * Read-only against the local filesystem: it reads the plan sidecar and the
  * optional policy file, and writes nothing.
  */
@@ -38,47 +63,24 @@ import os from "node:os";
 import readline from "node:readline";
 import { approveEpicPlan, createEpicRunWithDisposition, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
 import { validateBranchName } from "./base-ref.js";
-// BAPI-814/E1a: reused from the conduct-epic client on purpose. The override is
-// ONE repository-wide row with ONE reader; adding a second wrapper under
+// Reused from the conduct-epic client on purpose: adding a second wrapper under
 // `conductor/` would give the v2 path its own copy to drift from.
-import { getIndexBranch } from "./conduct-epic/bridge-client.js";
+//
+// BAPI-850 extends that reuse to the canonical parse read, the repository base
+// branch, the per-scope status/lifecycle reads, and the exact-cut protocol: the
+// typed clients the pilot already has are the v2 path's clients too, so neither
+// conductor can drift on a field name or an endpoint shape. No MCP tool, no
+// input-schema field, and no description changes.
+import { getConfigFieldBaseBranch, getIndexScopeLifecycle, getParseStatus, } from "./conduct-epic/bridge-client.js";
+import { createExecFileRunCommand, ensureCommitResolvableLocally, normalizeCommitSha, performExactIndexScopeCut, pollIndexScopeLifecycle, readRemoteBranchHead, runGit, SCOPE_LIFECYCLE_LABELS, } from "./conduct-epic/cut-protocol.js";
 import { hashPlan } from "./conductor/plan.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 /** Accepted `policy_json.review_policy.source` values (the `ReviewPolicy` surface). */
 export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
     "verdict_protocol",
     "native_review_decision",
     "none",
 ];
-/**
- * The warning lines for an active repository-wide index-branch override, or an
- * empty array when there is nothing to say (BAPI-814/E1a).
- *
- * Fail-open by construction. This is optional enrichment layered onto a command
- * whose real job is creating an epic run, so an unreadable override must not
- * become a preflight failure: an unavailable lookup produces one bounded,
- * sanitized diagnostic and `setup-epic` continues. The client already returns a
- * sanitized `error` string and never the raw service body, so nothing further
- * needs stripping here.
- */
-async function describeActiveIndexOverride(access, deps) {
-    const result = await getIndexBranch(access, deps.fetch);
-    if (!result.ok) {
-        return [
-            `  [warn] The repository's indexed-branch override could not be read: ${result.error}. ` +
-                `Continuing — this is optional context, not a prerequisite.`,
-        ];
-    }
-    const override = result.value.override;
-    if (override === null)
-        return [];
-    return [
-        `  [warn] ${access.repoName} has an ACTIVE index-branch override: ` +
-            `'${override.override_branch}'. Repository parses currently index that branch, ` +
-            `and the base-branch config field this run may fall back on resolves through the ` +
-            `same override.`,
-        `         Setup is CONTINUING — this is a warning, not a refusal.`,
-    ];
-}
 /** Echoed single-line prompt on stderr (mirrors connect-github's helper). */
 function defaultPromptLine(promptText) {
     return new Promise((resolve) => {
@@ -111,6 +113,7 @@ export function createDefaultSetupEpicDeps() {
         errorLog: (m) => console.error(m),
         isTTY: Boolean(process.stdin.isTTY),
         promptLine: defaultPromptLine,
+        runCommand: createExecFileRunCommand(),
     };
 }
 /** User-facing usage text. */
@@ -129,10 +132,14 @@ export function getSetupEpicUsage() {
         "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
         "  --plan-version <n>     Assert the sidecar's plan_version equals <n>",
         "  --feature-branch <name>  Run the epic on a dedicated feature branch.",
-        "                         The branch is created from the repository base branch",
-        "                         on origin, and every child-ticket PR targets it.",
-        "                         Omit (the default) to continue on the repository base",
-        "                         branch. Interactive runs are offered a proposal.",
+        "                         setup-epic cuts the branch on origin with your LOCAL git",
+        "                         at exactly the repository's canonical indexed commit",
+        "                         (the repository must be parsed first), the server",
+        "                         validates it, and every child-ticket PR targets it.",
+        "                         setup-epic then waits (bounded) for the run's index",
+        "                         scope to become ready. Omit (the default) to continue",
+        "                         on the repository base branch. Interactive runs are",
+        "                         offered a proposal.",
         "  --review-policy <src>  PER-RUN review policy source, one of:",
         `                         ${SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", ")}.`,
         "                         Composed into policy_json.review_policy on create.",
@@ -170,7 +177,7 @@ export function getSetupEpicUsage() {
         "",
         "After setup, the server-side reconciler picks the run up within ~30s.",
         "To execute claimed jobs on this machine, run:",
-        "  npx -y @bridge_gpt/mcp-server executor --repo <name>",
+        `  npx -y ${MCP_PACKAGE_NAME} executor --repo <name>`,
     ].join("\n");
 }
 function takeValue(argv, i, flag) {
@@ -897,6 +904,144 @@ function emitRefusal(deps, opts, result) {
         deps.log(JSON.stringify(result, null, 2));
     return 1;
 }
+// ---------------------------------------------------------------------------
+// Feature-branch start sequence helpers (BAPI-850)
+// ---------------------------------------------------------------------------
+/**
+ * The one recovery action for a scope that the server recorded as `failed`.
+ *
+ * Approval is idempotent and the server re-drives a `failed` scope's seed and
+ * verification when it is re-approved, so re-running the SAME `setup-epic`
+ * invocation is the canonical fix. The `canonical_index_advanced` category is
+ * the exception the pilot also calls out: the cut itself must be re-driven at
+ * the newer commit.
+ */
+export const SETUP_EPIC_SCOPE_RECOVERY_COMMAND = "re-run this same setup-epic command (approval is idempotent and re-drives the scope's seed and verification)";
+/** The lead sentence of every fail-closed canonical-parse refusal (BAPI-850). */
+export const SETUP_EPIC_PARSE_FIRST_MESSAGE = "parse the repository first";
+/**
+ * Resolve the EFFECTIVE feature branch after policy composition.
+ *
+ * `--feature-branch` wins when given. Otherwise a valid `policy_json.base_branch`
+ * supplied by `--policy-file` names the branch — the file ALREADY answered the
+ * question, and the run will be created with that branch whether or not this
+ * CLI noticed. A malformed or unknown policy field (including the camelCase
+ * `baseBranch` slip) is deliberately NOT interpreted here: the server's strict
+ * `RunPolicy` validation owns rejecting it, so this returns `undefined` and the
+ * request proceeds to that 422 unchanged.
+ */
+export function resolveEffectiveFeatureBranch(featureBranch, requestedPolicy) {
+    if (featureBranch !== undefined)
+        return featureBranch;
+    const raw = requestedPolicy?.["base_branch"];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "" || validateBranchName(trimmed) !== null)
+        return undefined;
+    return trimmed;
+}
+/**
+ * Read canonical parse truth and require a `succeeded` parse with a full
+ * indexed commit — the commit `origin/<feature>` will be cut at.
+ *
+ * Fails CLOSED (ratified R-2). The first line of every refusal is the exact
+ * operator instruction; the closing lines state what did NOT happen. An
+ * UNREADABLE status is kept distinct from an unsuccessful one — "could not read"
+ * is not evidence the repository is unindexed, and telling that operator to
+ * re-index would send them to re-parse a repository that may be fine.
+ */
+export async function readCanonicalParseTruth(access, fetchImpl) {
+    const notCreated = [
+        "No run was created and no branch was changed.",
+    ];
+    const parse = await getParseStatus(access, fetchImpl);
+    if (!parse.ok) {
+        return {
+            ok: false,
+            lines: [
+                `The canonical parse status for ${access.repoName} could not be read: ${parse.error}. ` +
+                    `Retry; if the repository has never been parsed, ${SETUP_EPIC_PARSE_FIRST_MESSAGE}.`,
+                ...notCreated,
+            ],
+        };
+    }
+    if (parse.value.status !== "succeeded") {
+        return {
+            ok: false,
+            lines: [
+                `${SETUP_EPIC_PARSE_FIRST_MESSAGE}: the canonical index for ${access.repoName} has no ` +
+                    `successful parse (status: ${String(parse.value.status)}), so there is no commit to ` +
+                    `cut the feature branch at.`,
+                ...notCreated,
+            ],
+        };
+    }
+    const indexed = normalizeCommitSha(parse.value.indexed_commit_sha);
+    if (indexed === null) {
+        return {
+            ok: false,
+            lines: [
+                `${SETUP_EPIC_PARSE_FIRST_MESSAGE}: the canonical index for ${access.repoName} published ` +
+                    `no commit for its last successful parse, so there is no commit to cut the feature ` +
+                    `branch at.`,
+                ...notCreated,
+            ],
+        };
+    }
+    return { ok: true, cutCommitSha: indexed };
+}
+/** The strict subset of `SetupEpicDeps` the shared cut protocol consumes. */
+function cutProtocolDeps(deps, runCommand) {
+    return {
+        runCommand,
+        cwd: deps.cwd,
+        fetchImpl: deps.fetch,
+        errorLog: deps.errorLog,
+        sleep: deps.sleep,
+    };
+}
+/**
+ * Resolve the run's scope id for a REUSED, already-activated run, whose cut was
+ * recorded by an earlier invocation and must not be re-driven.
+ *
+ * Reads the repository's lifecycle listing (an existing read) and matches on the
+ * server-recorded `epic_run_id`. Returns `null` when no scope is associated —
+ * the server's approval reports that case itself.
+ */
+async function resolveScopeIdForRun(access, fetchImpl, epicRunId) {
+    const listing = await getIndexScopeLifecycle(access, fetchImpl);
+    if (!listing.ok)
+        return null;
+    const match = listing.value.scopes.find((scope) => scope.epic_run_id === epicRunId);
+    return match?.scope_id ?? null;
+}
+/** Operator-facing guidance for a bounded scope failure category. */
+function scopeFailureGuidance(reason, featureBranch) {
+    if (reason === "canonical_index_advanced") {
+        return (`The canonical index advanced before the scope could be seeded. The cut must be ` +
+            `re-driven at the newer commit: delete origin/${featureBranch}, abandon this run ` +
+            `(PATCH /jira/epic-runs/runs/<epic_run_id> {"status": "abandoned"}), and re-run setup-epic.`);
+    }
+    return `Recovery: ${SETUP_EPIC_SCOPE_RECOVERY_COMMAND}.`;
+}
+/**
+ * Report one newly observed lifecycle transition, once, in order.
+ *
+ * Prior lines stay on screen as confirmation — no spinner rewrite, no
+ * percentages. Branch, SHA, and scope identifiers are secondary technical
+ * detail: the label leads, the scope id never does, and no credential appears.
+ */
+function describeScopeTransition(state, status) {
+    const label = SCOPE_LIFECYCLE_LABELS[state] ?? state;
+    if (state === "ready") {
+        return `Scope:      ${label} — indexed at ${status.indexed_commit_sha ?? "unknown"} (scope ${status.scope_id})`;
+    }
+    if (state === "failed") {
+        return `Scope:      ${label} — ${status.last_error ?? "unknown"} (scope ${status.scope_id})`;
+    }
+    return `Scope:      ${label}…`;
+}
 export async function runSetupEpicCli(argv, overrides = {}) {
     const deps = { ...createDefaultSetupEpicDeps(), ...overrides };
     const parsed = parseSetupEpicArgs(argv);
@@ -1019,21 +1164,6 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     say(`Local hash: ${localHash}`);
     for (const w of warnings)
         say(`  [warn] ${w}`);
-    // --- Active index-branch override (BAPI-814/E1a) -------------------------
-    // Non-mutating enrichment, placed once credentials and repository identity are
-    // both known and before any run-state read or mutating request.
-    //
-    // WARNING ONLY, never a refusal. The override is repository-wide: while it is
-    // active every parse indexes that branch, and the create-PR config-field
-    // fallback and feature-branch provisioning read the same overridden
-    // `config_code_repositories.base_branch`. A v2 operator setting up an epic in
-    // that repository needs to know, but the condition is legitimate — it is
-    // usually another epic mid-flight — so setup continues.
-    //
-    // Emitted in `--dry-run` too: the condition already exists in the repository
-    // and is independent of whether this invocation writes anything.
-    for (const line of await describeActiveIndexOverride(access, deps))
-        say(line);
     // --- Feature branch selection (BAPI-655) --------------------------------
     // Resolved AFTER local/access context is known but BEFORE any run-state read
     // or mutating request, so malformed interactive input fails before network
@@ -1041,7 +1171,8 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     const promptedInteractively = opts.featureBranch === undefined && !policyDeclaresBranch && deps.isTTY && !opts.json;
     const featureBranch = await resolveFeatureBranchSelection(opts, access.repoName, deps, policyDeclaresBranch);
     if (featureBranch !== undefined) {
-        say(`Feature:    ${featureBranch} (create from repository base branch on origin)`);
+        say(`Feature:    ${featureBranch} (cut on origin with local git at the canonical indexed ` +
+            `commit; validated server-side at approval)`);
     }
     else if (promptedInteractively) {
         // Ordinary, non-warning notice — only when an interactive operator declined.
@@ -1064,6 +1195,15 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         requestedPolicy = composed.policy;
         say(`Policy:     ${opts.policyFile} (complete run policy, applied at creation)`);
     }
+    // --- Effective feature branch (BAPI-850) ----------------------------------
+    // Derived AFTER policy composition so a branch the policy file declares under
+    // `base_branch` is honored exactly as `--feature-branch` would be. A malformed
+    // or unknown policy field is left for the server's strict validation.
+    const effectiveFeatureBranch = resolveEffectiveFeatureBranch(featureBranch, requestedPolicy);
+    if (effectiveFeatureBranch !== undefined && featureBranch === undefined) {
+        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;
@@ -1206,8 +1346,64 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     if (validated) {
         say("Validation: server validation: passed");
         say(`            plan hash ${validated.planHash}`);
-        say(`            serialization ${validated.serializationEnabled ? "enabled" : "disabled"}, ` +
-            `${validated.insertedEdges} edge(s) inserted`);
+        // BAPI-848 — three distinct outcomes, never collapsed into success language.
+        // "0 edges inserted" used to read as proof the siblings could not conflict.
+        // It never was: serialization only sees paths BOTH nodes declared, and the
+        // repo's worst conflict hotspot was one nobody declared.
+        if (!validated.serializationEnabled) {
+            say("            serialization disabled — no ordering was derived from file overlap");
+        }
+        else if (validated.insertedEdges === 0) {
+            say("            serialization enabled — no declared file overlaps produced edges");
+        }
+        else {
+            say(`            serialization enabled — ${validated.insertedEdges} edge(s) inserted from ` +
+                `${validated.overlappingPairsFound} overlapping pair(s)`);
+        }
+        if (validated.serializationEnabled) {
+            say(`            coverage: ${validated.coverageScope}`);
+            if (validated.undeclaredNodes > 0 || validated.undeclaredPairsSkipped > 0) {
+                deps.errorLog(`WARNING: ${validated.undeclaredNodes} node(s) declared no touched_files, so ` +
+                    `${validated.undeclaredPairsSkipped} pair(s) were never evaluated. Serialization ` +
+                    `proves ordering only for paths BOTH nodes declared — it cannot show that these ` +
+                    `tickets will avoid each other.`);
+            }
+        }
+    }
+    // --- Scope-bearing preflight (BAPI-850) ----------------------------------
+    // A FEATURE-BRANCH run that has not yet activated must prove canonical parse
+    // truth BEFORE any ref is changed or any run is created. A reused run that is
+    // already active/blocked carries merged child work on its branch and a
+    // recorded cut; it is never re-cut (its persisted run/scope association is
+    // used for status instead). A no-feature run performs none of this.
+    //
+    // The scope's BASE is the repository's configured base branch (the same
+    // resolution `conduct-epic init` uses), NOT `policy_json.base_branch` — that
+    // key names the FEATURE branch. A feature branch equal to the configured base
+    // needs no scope (dispatch already cuts from it) and matches the server's
+    // long-standing no-op for that case.
+    const existingRunActivated = existingStatus !== null &&
+        existingStatus !== "planning" &&
+        existingStatus !== "pending_approval";
+    let scopeBaseBranch = null;
+    let scopeBearing = false;
+    let cutCommitSha = null;
+    if (effectiveFeatureBranch !== undefined) {
+        const configured = await getConfigFieldBaseBranch(access, deps.fetch);
+        scopeBaseBranch =
+            configured.ok && configured.value.base_branch !== null ? configured.value.base_branch : "main";
+        scopeBearing = effectiveFeatureBranch !== scopeBaseBranch;
+    }
+    const needsCut = scopeBearing && !existingRunActivated;
+    if (needsCut) {
+        const truth = await readCanonicalParseTruth(access, deps.fetch);
+        if (!truth.ok) {
+            for (const line of truth.lines)
+                deps.errorLog(line);
+            return 1;
+        }
+        cutCommitSha = truth.cutCommitSha;
+        say(`Cut:        ${cutCommitSha} (canonical indexed commit; origin/${effectiveFeatureBranch} will be cut here)`);
     }
     if (opts.dryRun) {
         say("");
@@ -1220,8 +1416,10 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         else {
             say(`  - POST /jira/epic-runs/runs  (create run for ${opts.epicKey})`);
         }
-        if (featureBranch !== undefined) {
-            say(`  - feature branch: ${featureBranch} (create from repository base branch; no request made in dry-run)`);
+        if (effectiveFeatureBranch !== undefined) {
+            say(needsCut && cutCommitSha !== null
+                ? `  - feature branch: ${effectiveFeatureBranch} (cut origin/${effectiveFeatureBranch} at canonical indexed commit ${cutCommitSha} with local git, then validate server-side; nothing cut, created, or seeded in dry-run)`
+                : `  - feature branch: ${effectiveFeatureBranch} (validated server-side at approval; no request made in dry-run)`);
         }
         if (opts.reviewPolicy !== undefined) {
             say(`  - review policy: ${opts.reviewPolicy} (per-run policy_json.review_policy; sets no repository default — use \`install-bridge conductor --review-policy\` for that)`);
@@ -1237,7 +1435,12 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 local_plan_hash: localHash,
                 existing_run_id: existingRunId,
                 // Only present for a feature-branch run — no-feature JSON is unchanged.
-                ...(featureBranch !== undefined ? { feature_branch: featureBranch } : {}),
+                // BAPI-850: the EFFECTIVE branch, so a policy-file-declared feature run
+                // reports the same key a --feature-branch run does.
+                ...(effectiveFeatureBranch !== undefined ? { feature_branch: effectiveFeatureBranch } : {}),
+                // 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 } : {}),
                 // Only present when a policy was explicitly selected — the
                 // no-policy JSON shape is unchanged.
                 ...(opts.reviewPolicy !== undefined
@@ -1252,6 +1455,12 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                         server_plan_hash: validated.planHash,
                         serialization_enabled: validated.serializationEnabled,
                         inserted_edges: validated.insertedEdges,
+                        // BAPI-848 — machine consumers get the same coverage the human
+                        // output carries, so neither can read 0 edges as a verdict.
+                        overlapping_pairs_found: validated.overlappingPairsFound,
+                        undeclared_nodes: validated.undeclaredNodes,
+                        undeclared_pairs_skipped: validated.undeclaredPairsSkipped,
+                        coverage_scope: validated.coverageScope,
                     }
                     : { result: "partial (local checks only)" }),
                 warnings,
@@ -1259,6 +1468,46 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         }
         return 0;
     }
+    // --- Local git preflight for the cut (BAPI-850) --------------------------
+    // Still BEFORE any mutating request: the operator's checkout must be able to
+    // reach origin, hold the exact cut object, and origin/<feature> must be absent
+    // or already at the cut. A failure here creates nothing and changes nothing.
+    let cutRunCommand;
+    if (needsCut && cutCommitSha !== null && scopeBaseBranch !== null) {
+        cutRunCommand = deps.runCommand;
+        if (cutRunCommand === undefined) {
+            deps.errorLog(`A feature-branch run cuts origin/${effectiveFeatureBranch} with your local git, but no ` +
+                `command runner is available in this environment. No run was created and no branch was changed.`);
+            return 1;
+        }
+        const gitDeps = cutProtocolDeps(deps, cutRunCommand);
+        const fetched = await runGit(gitDeps, ["fetch", "origin", scopeBaseBranch]);
+        if (fetched.exitCode !== 0) {
+            deps.errorLog(`git fetch origin ${scopeBaseBranch} failed in ${deps.cwd}. Run setup-epic from a clone ` +
+                `of ${access.repoName} with an 'origin' remote. No run was created and no branch was changed.`);
+            return 1;
+        }
+        if (!(await ensureCommitResolvableLocally(gitDeps, cutCommitSha))) {
+            deps.errorLog(`The canonical indexed commit ${cutCommitSha} could not be resolved locally even after ` +
+                `fetching it from origin. Fetch it manually, or re-parse ${access.repoName}. No run was ` +
+                `created and no branch was changed.`);
+            return 1;
+        }
+        const remoteHead = await readRemoteBranchHead(gitDeps, effectiveFeatureBranch);
+        if (!remoteHead.ok) {
+            deps.errorLog(`${remoteHead.error} No run was created and no branch was changed.`);
+            return 1;
+        }
+        if (remoteHead.sha !== null && remoteHead.sha !== cutCommitSha) {
+            deps.errorLog(`origin/${effectiveFeatureBranch} already exists at ${remoteHead.sha}, which is not the ` +
+                `canonical indexed commit ${cutCommitSha}. setup-epic never force-updates an existing ` +
+                `branch: delete it, or finish the previous run first. No run was created and no branch was changed.`);
+            return 1;
+        }
+        say(remoteHead.sha === null
+            ? `Branch:     origin/${effectiveFeatureBranch} is absent; it will be cut at ${cutCommitSha}`
+            : `Branch:     origin/${effectiveFeatureBranch} already sits at the cut commit ${cutCommitSha}`);
+    }
     const result = {
         epic_run_id: existingRunId ?? "",
         epic_key: opts.epicKey,
@@ -1274,8 +1523,10 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         policy_applied: "absent",
         warnings,
     };
-    if (featureBranch !== undefined)
-        result.feature_branch = featureBranch;
+    // BAPI-850: the EFFECTIVE feature branch (flag or policy file), so a
+    // policy-file-declared feature run reports the same key a flag run does.
+    if (effectiveFeatureBranch !== undefined)
+        result.feature_branch = effectiveFeatureBranch;
     // --- Step 1: create (only when there is no live run) ---------------------
     if (existingRunId) {
         say(`Run:        reusing ${existingRunId} (status: ${existingStatus})`);
@@ -1366,6 +1617,40 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             return 1;
         }
     }
+    // --- The exact cut (BAPI-850) --------------------------------------------
+    // AFTER the run exists and BEFORE the plan is stored/approved: the scope's run
+    // association is immutable server-side, so the cut is driven with this run's
+    // id and the scope is minted owned by it. Everything from `cut/begin` to the
+    // hold's release is the SHARED protocol `conduct-epic init` drives — local git
+    // only, an exact-SHA create-only push, never the GitHub App, never a force
+    // update. A failure leaves the run non-active (never discoverable by the
+    // reconciler) and re-running setup-epic reuses it and re-drives the cut.
+    let cutScopeId = null;
+    if (needsCut && cutCommitSha !== null && scopeBaseBranch !== null && cutRunCommand !== undefined) {
+        const cut = await performExactIndexScopeCut(cutProtocolDeps(deps, cutRunCommand), access, {
+            featureBranch: effectiveFeatureBranch,
+            baseBranch: scopeBaseBranch,
+            candidateCommitSha: cutCommitSha,
+            epicRunId: result.epic_run_id,
+        });
+        if (!cut.ok) {
+            for (const line of cut.failures)
+                deps.errorLog(line);
+            if (cut.kind === "existing_ref_mismatch" || cut.kind === "confirm_failed") {
+                deps.errorLog(`Expected origin/${effectiveFeatureBranch} at the canonical indexed commit ` +
+                    `${cut.expectedSha ?? cutCommitSha}` +
+                    (cut.observedSha ? `, found ${cut.observedSha}.` : ".") +
+                    ` setup-epic never force-pushes: correct the local/origin branch, then re-run setup-epic.`);
+            }
+            deps.errorLog(`Epic run ${result.epic_run_id} exists but was NOT approved and will not dispatch; ` +
+                `re-running setup-epic reuses it and re-drives the cut.`);
+            return emitRefusal(deps, opts, result);
+        }
+        cutScopeId = cut.lease.scope_id;
+        say(cut.branchCreated
+            ? `Branch:     cut origin/${effectiveFeatureBranch} at ${cut.lease.cut_commit_sha} with local git (scope ${cutScopeId})`
+            : `Branch:     origin/${effectiveFeatureBranch} confirmed at ${cut.lease.cut_commit_sha} (scope ${cutScopeId}, cut already recorded)`);
+    }
     // --- Step 2/3: store the plan -------------------------------------------
     try {
         const stored = await storeEpicPlan(access, {
@@ -1390,23 +1675,24 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         deps.errorLog(`Failed to store the plan: ${errorDetail(err)}`);
         return 1;
     }
-    // --- Step 4: approve (also provisions the feature branch server-side) -----
-    // For a feature-branch run the backend creates/validates the branch on origin
-    // as an approval prerequisite. Provisioning runs and completes BEFORE the
-    // approval (ticket-seeding + CAS activation) step server-side, so only a
-    // failure the backend tags with the structured FEATURE_BRANCH_PROVISIONING
-    // error_code is actually a branch/credentials problem — key the distinct
-    // message off that code, not merely off whether --feature-branch was passed,
-    // so an unrelated approval failure (e.g. ticket-seeding, a masked 500) is not
-    // misattributed to provisioning.
-    if (featureBranch !== undefined) {
-        say(`Branch:     creating or validating ${featureBranch} on origin…`);
+    // --- Step 4: approve (also validates the feature branch server-side) ------
+    // For a feature-branch run the backend READ-validates the branch on origin
+    // against the scope's recorded cut as an approval prerequisite (BAPI-850: the
+    // local cut above created it; the App never creates refs). Validation runs
+    // and completes BEFORE the approval (ticket-seeding + CAS activation) step
+    // server-side, so only a failure the backend tags with the structured
+    // FEATURE_BRANCH_PROVISIONING error_code is actually a branch/scope/credentials
+    // problem — key the distinct message off that code, not merely off whether a
+    // feature branch is set, so an unrelated approval failure (e.g.
+    // ticket-seeding, a masked 500) is not misattributed to provisioning.
+    if (effectiveFeatureBranch !== undefined) {
+        say(`Branch:     validating origin/${effectiveFeatureBranch} server-side (App read) and preparing the index scope…`);
     }
     const approval = await approveEpicPlan(access, { epicKey: opts.epicKey, planVersion: plan.plan_version }, deps.fetch).catch((err) => {
-        if (featureBranch !== undefined &&
+        if (effectiveFeatureBranch !== undefined &&
             err instanceof ConductorBridgeApiError &&
             err.errorCode === "FEATURE_BRANCH_PROVISIONING") {
-            deps.errorLog(`Failed to provision the feature branch '${featureBranch}' — child-ticket ` +
+            deps.errorLog(`Failed to provision the feature branch '${effectiveFeatureBranch}' — child-ticket ` +
                 `dispatch has NOT started. Correct repository access or the branch ` +
                 `configuration, then re-run setup-epic.\nDetail: ${errorDetail(err)}`);
         }
@@ -1426,12 +1712,14 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         if (prov) {
             result.feature_branch_provisioning = prov;
             if (prov.status === "created") {
+                // Legacy servers only: a BAPI-850 server never creates a ref.
                 say(`Branch:     ready on origin — created '${prov.feature_branch}' from ` +
                     `'${prov.source_branch}' at ${prov.source_sha}`);
             }
             else {
-                say(`Branch:     '${prov.feature_branch}' already exists — validated, unchanged ` +
-                    `(the remote ref was not moved or reset); head ${prov.remote_head_sha}`);
+                say(`Branch:     '${prov.feature_branch}' validated on origin at head ` +
+                    `${prov.remote_head_sha} (cut ${prov.source_sha} from '${prov.source_branch}'; ` +
+                    `the remote ref was not moved or reset)`);
             }
         }
     }
@@ -1452,6 +1740,93 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         result.warnings.push(`Server plan hash differs from the local hash (the server re-hashes after ` +
             `applying file-overlap serialization). The server hash is authoritative.`);
     }
+    // --- Bounded scope lifecycle feedback (BAPI-850) --------------------------
+    // Only after a feature-bearing approval succeeded (or an idempotent approval
+    // confirmed an already-active run). The scope id comes from THIS invocation's
+    // cut, or — for a reused run whose cut an earlier invocation recorded — from
+    // the run's persisted scope association. Transition prose goes to `say`
+    // (stderr under --json) so stdout stays the single result document. The poll
+    // reuses the pilot's interval, cap, and status vocabulary; `ready` is accepted
+    // only when the server proves indexed == cut.
+    let exitCode = 0;
+    if (scopeBearing) {
+        const scopeId = cutScopeId ?? (await resolveScopeIdForRun(access, deps.fetch, result.epic_run_id));
+        if (scopeId === null) {
+            result.index_scope = {
+                scope_id: null,
+                cut_commit_sha: cutCommitSha,
+                lifecycle_state: null,
+                ready: false,
+                disposition: "not_polled",
+            };
+            say(`Scope:      no index scope is associated with run ${result.epic_run_id}; ` +
+                `the reconciler will not dispatch until one is ready. Re-run setup-epic.`);
+            exitCode = 1;
+        }
+        else {
+            say(`Scope:      waiting for index scope readiness (bounded)…`);
+            const verdict = await pollIndexScopeLifecycle(cutProtocolDeps(deps, cutRunCommand ?? deps.runCommand ?? createExecFileRunCommand()), access, scopeId, { onTransition: (state, status) => say(describeScopeTransition(state, status)) });
+            if (verdict.kind === "ready") {
+                result.index_scope = {
+                    scope_id: scopeId,
+                    cut_commit_sha: verdict.status.cut_commit_sha,
+                    lifecycle_state: verdict.status.lifecycle_state,
+                    ready: true,
+                    disposition: "ready",
+                };
+                say(`Scope:      ready — the reconciler may dispatch against the epic branch index.`);
+            }
+            else if (verdict.kind === "ready_mismatch") {
+                result.index_scope = {
+                    scope_id: scopeId,
+                    cut_commit_sha: verdict.status.cut_commit_sha,
+                    lifecycle_state: verdict.status.lifecycle_state,
+                    ready: false,
+                    disposition: "failed",
+                    failure_reason: "ready_watermark_mismatch",
+                    recovery_command: SETUP_EPIC_SCOPE_RECOVERY_COMMAND,
+                };
+                deps.errorLog(`Index scope ${scopeId} reports ready but its indexed commit ` +
+                    `(${verdict.status.indexed_commit_sha ?? "none"}) is not the cut commit ` +
+                    `(${verdict.status.cut_commit_sha ?? "none"}). Treating the scope as NOT ready; ` +
+                    `ticket dispatch remains blocked by the reconciler's freshness hold. ` +
+                    `Recovery: ${SETUP_EPIC_SCOPE_RECOVERY_COMMAND}.`);
+                exitCode = 1;
+            }
+            else if (verdict.kind === "failed") {
+                result.index_scope = {
+                    scope_id: scopeId,
+                    cut_commit_sha: verdict.status.cut_commit_sha,
+                    lifecycle_state: verdict.status.lifecycle_state,
+                    ready: false,
+                    disposition: "failed",
+                    failure_reason: verdict.reason,
+                    recovery_command: SETUP_EPIC_SCOPE_RECOVERY_COMMAND,
+                };
+                deps.errorLog(`Index scope ${scopeId} FAILED (reason: ${verdict.reason}) — this is a recorded ` +
+                    `failure, not an in-progress state. Ticket dispatch remains blocked: the reconciler ` +
+                    `will not dispatch against a failed scope.`);
+                deps.errorLog(scopeFailureGuidance(verdict.reason, effectiveFeatureBranch ?? ""));
+                exitCode = 1;
+            }
+            else {
+                result.index_scope = {
+                    scope_id: scopeId,
+                    cut_commit_sha: verdict.lastStatus?.cut_commit_sha ?? cutCommitSha,
+                    lifecycle_state: verdict.lastStatus?.lifecycle_state ?? null,
+                    ready: false,
+                    disposition: "timeout",
+                };
+                deps.errorLog(`Index scope ${scopeId} did not become ready within the bounded wait ` +
+                    `(last observed state: ${verdict.lastState}). The run ${result.epic_run_id} is ` +
+                    `created and scope preparation continues asynchronously on the server; the ` +
+                    `reconciler will NOT dispatch tickets until the scope becomes ready. Check ` +
+                    `GET /jira/index-scope/status?repo_name=${access.repoName}&scope_id=${scopeId}, ` +
+                    `or re-run setup-epic to wait again.`);
+                exitCode = 1;
+            }
+        }
+    }
     if (opts.json) {
         deps.log(JSON.stringify(result, null, 2));
     }
@@ -1468,7 +1843,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         say(`Epic run ${result.epic_run_id} is ${result.status ?? "unknown"}.`);
         say("The server-side reconciler will pick it up within ~30s.");
         say("To execute claimed jobs on this machine, run:");
-        say(`  npx -y @bridge_gpt/mcp-server executor --repo ${access.repoName}`);
+        say(`  npx -y ${MCP_PACKAGE_NAME} executor --repo ${access.repoName}`);
     }
-    return 0;
+    return exitCode;
 }