@bridge_gpt/mcp-server 0.2.51 → 0.2.52

package/build/setup-epic.js

@@ -30,9 +30,15 @@
  *      file-overlap serialization, so a divergence is legitimate, not corruption.
  *   5. Store, then approve.
  *
+ * BAPI-1009 — the epic branch is the DEFAULT for a multi-ticket epic. A plan
+ * with two or more nodes and no branch flag derives `epic/<KEY>` on EVERY path
+ * (piped, CI, and `--json` included), so the scope-bearing sequence below is now
+ * the ordinary path rather than an opt-in one. A single-node plan stays on the
+ * repository base branch, and `--into-base` forces base for any node count.
+ *
  * 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:
+ * the BAPI-1009 default, `--feature-branch`, or `--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";
@@ -47,13 +53,18 @@
  *   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.
+ *   e. Poll the scope's lifecycle with a SHORT bounded wait (BAPI-1054:
+ *      {@link SETUP_EPIC_SCOPE_DEFERRED_MAX_POLLS} polls, ~30s), reporting
+ *      `Provisioning → Seeding → Verifying → Ready`. A scope still preparing at
+ *      that deadline is acknowledged as `created, cut deferred` and exits 0 —
+ *      the run is created and approved, and preparation continues server-side.
+ *      Only `failed` and `ready_mismatch` are terminal and exit 1. The
+ *      reconciler's dispatch-freshness hold keeps an un-ready scope from
+ *      dispatching in every case, which is what makes the deferred return safe.
  *
- * A run with no feature branch is byte-identical to before: no parse read, no
- * `git`, no scope, no polling, no extra JSON keys.
+ * A run with no feature branch — a single-node plan, or `--into-base` — is
+ * byte-identical to before: no parse read, no `git`, no scope, no polling, no
+ * extra JSON keys.
  *
  * Reads the plan sidecar and the optional policy file from the local
  * filesystem. As of BAPI-872 it can also WRITE the local filesystem in one
@@ -66,9 +77,9 @@
  */
 import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
 import os from "node:os";
-import readline from "node:readline";
 import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, } from "./epic-integration-pr.js";
 import { approveEpicPlan, createEpicRunWithDisposition, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
+import { resolveTrackedPaths } from "./git-reachability.js";
 import { validateBranchName } from "./base-ref.js";
 // 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.
@@ -79,7 +90,7 @@ import { validateBranchName } from "./base-ref.js";
 // 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 { boundScopeLifecycleLabel, createExecFileRunCommand, ensureCommitResolvableLocally, normalizeCommitSha, performExactIndexScopeCut, pollIndexScopeLifecycle, readRemoteBranchHead, runGit, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_LIFECYCLE_LABELS, } from "./conduct-epic/cut-protocol.js";
 import { hashPlan } from "./conductor/plan.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // BAPI-872: local plane-manifest binding, so `plane down` can later stop the
@@ -93,25 +104,6 @@ export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
     "native_review_decision",
     "none",
 ];
-/** Echoed single-line prompt on stderr (mirrors connect-github's helper). */
-function defaultPromptLine(promptText) {
-    return new Promise((resolve) => {
-        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-        // `rl.close()` emits `close` SYNCHRONOUSLY, so without this guard the close
-        // handler would settle the promise empty and discard a real answer. EOF must
-        // also resolve rather than deadlock a top-level await.
-        let answered = false;
-        rl.on("close", () => {
-            if (!answered)
-                resolve("");
-        });
-        rl.question(promptText, (answer) => {
-            answered = true;
-            rl.close();
-            resolve(answer.trim());
-        });
-    });
-}
 export function createDefaultSetupEpicDeps() {
     return {
         env: process.env,
@@ -123,8 +115,6 @@ export function createDefaultSetupEpicDeps() {
         fetch: globalThis.fetch,
         log: (m) => console.log(m),
         errorLog: (m) => console.error(m),
-        isTTY: Boolean(process.stdin.isTTY),
-        promptLine: defaultPromptLine,
         runCommand: createExecFileRunCommand(),
         epicIntegrationGh: createProductionEpicIntegrationGhRunner(),
         planeBinding: {
@@ -142,6 +132,12 @@ export function getSetupEpicUsage() {
         "Bootstraps an Epic Conductor v2 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",
+        "epic branch named epic/<KEY>, derived automatically on every path (piped, CI,",
+        "and --json included). Every child-ticket PR targets epic/<KEY>, and one DRAFT",
+        "integration PR targets the repository base branch. A single-node plan keeps the",
+        "repository base branch, matching plain start-tickets semantics.",
+        "",
         "Required:",
         "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
         "  --plan-file <path>     Path to epic-plan.dag.json (from decompose-epic)",
@@ -149,15 +145,26 @@ export function getSetupEpicUsage() {
         "Options:",
         "  --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.",
+        "  --feature-branch <name>  OVERRIDE the derived epic/<KEY> name with your own.",
         "                         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.",
+        "                         setup-epic then waits BRIEFLY (about " +
+            `${SETUP_EPIC_SCOPE_DEFERRED_WINDOW_SECONDS}s) for the run's index scope to`,
+        "                         become ready. If it is still preparing at that point the",
+        `                         command exits 0 with a '${SETUP_EPIC_CUT_DEFERRED_PHRASE}'`,
+        "                         acknowledgement naming the run and scope: the run IS",
+        "                         created and approved, preparation continues server-side,",
+        "                         and the reconciler holds ticket dispatch until it is",
+        "                         ready. Only a recorded scope failure exits non-zero.",
+        "                         Also forces an epic branch for a SINGLE-node plan, which",
+        "                         the default would leave on base.",
+        "  --into-base            OPT OUT of the epic-branch default: cut no branch and",
+        "                         target every child PR at the repository base branch",
+        "                         (the pre-BAPI-1009 behavior). Use this if automation",
+        "                         depended on \"no flag = direct to base\". Contradictory",
+        "                         with --feature-branch; passing both is a parse error.",
         "  --review-policy <src>  PER-RUN review policy source, one of:",
         `                         ${SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", ")}.`,
         "                         Composed into policy_json.review_policy on create.",
@@ -256,6 +263,12 @@ export function parseSetupEpicArgs(argv) {
     let repo;
     let planVersion;
     let featureBranch;
+    // BAPI-1009: tracked SEPARATELY from `featureBranch`, because an explicitly
+    // blank `--feature-branch=` normalizes the value to `undefined` while still
+    // being a supplied branch-strategy intent. The contradiction guard below must
+    // fire on the INTENT, not on whether a name survived normalization.
+    let featureBranchSupplied = false;
+    let intoBase = false;
     let reviewPolicy;
     let policyFile;
     let replacePolicy = false;
@@ -278,6 +291,7 @@ export function parseSetupEpicArgs(argv) {
             if (!parsedFb.ok)
                 return { status: "error", message: parsedFb.error };
             featureBranch = parsedFb.value;
+            featureBranchSupplied = true;
             continue;
         }
         // `--review-policy=<source>` inline form (BAPI-679).
@@ -298,6 +312,7 @@ export function parseSetupEpicArgs(argv) {
                 if (!parsedFb.ok)
                     return { status: "error", message: parsedFb.error };
                 featureBranch = parsedFb.value;
+                featureBranchSupplied = true;
                 i++;
                 break;
             }
@@ -361,6 +376,9 @@ export function parseSetupEpicArgs(argv) {
                 i++;
                 break;
             }
+            case "--into-base":
+                intoBase = true;
+                break;
             case "--replace-policy":
                 replacePolicy = true;
                 break;
@@ -395,6 +413,18 @@ export function parseSetupEpicArgs(argv) {
                 "on a real setup.",
         };
     }
+    // BAPI-1009: the two branch-strategy flags are contradictory intents, refused
+    // HERE alongside the other pre-flight contradictions — before any file read,
+    // credential resolution, git command, or network request.
+    if (featureBranchSupplied && intoBase) {
+        return {
+            status: "error",
+            message: "--feature-branch and --into-base select contradictory branch strategies: " +
+                "--feature-branch runs the epic on a named epic branch, --into-base runs " +
+                "children directly into the repository base branch. Only one branch strategy " +
+                "may be selected — remove whichever one you did not mean.",
+        };
+    }
     if (replacePolicy && policyFile === undefined) {
         return {
             status: "error",
@@ -411,6 +441,7 @@ export function parseSetupEpicArgs(argv) {
             repo,
             planVersion,
             featureBranch,
+            intoBase,
             reviewPolicy,
             policyFile,
             replacePolicy,
@@ -524,10 +555,16 @@ export function composeSetupEpicPolicy(filePolicy, selections) {
             };
         }
         if (fileReview.kind === "source" && fileReview.value !== selections.reviewPolicy) {
+            // BAPI-1054: the file's value is NOT echoed. `review_policy.source` is an
+            // arbitrary string on the wire, read straight out of an operator-authored
+            // file that can also carry `notify.webhook_url` — so interpolating it put
+            // unbounded file-derived text into stderr and CI logs. Naming the field and
+            // the CLI selection (which came from a closed vocabulary and is therefore
+            // safe) says everything the operator needs to fix it.
             return {
                 ok: false,
                 error: `--review-policy selected '${selections.reviewPolicy}', but --policy-file ` +
-                    `declares review_policy.source '${fileReview.value}'. setup-epic will not pick ` +
+                    `declares a different review_policy.source. setup-epic will not pick ` +
                     `a winner between them: drop the flag, or fix the policy file so both agree.`,
             };
         }
@@ -541,6 +578,53 @@ export function composeSetupEpicPolicy(filePolicy, selections) {
     }
     return { ok: true, policy: composed };
 }
+/**
+ * The single named policy gate, run before any credential resolution or request.
+ *
+ * Pure, and deterministic in its refusal order: it reports the FIRST violation
+ * and stops, so one invocation yields one named reason. It consolidates checks
+ * that already existed but were scattered across two call sites, which is what
+ * let `--local-only --dry-run` and an ordinary run evaluate slightly different
+ * sets — a dry run is worth nothing if it does not refuse what the real run will.
+ *
+ * It is READ-ONLY with respect to policy content: nothing here normalizes,
+ * coerces, deletes, or reconstructs a policy file's keys.
+ * {@link composeSetupEpicPolicy} remains the only function that adds validated
+ * CLI selections, and it is called from here so the object that passes the gate
+ * is exactly the object the request later carries.
+ *
+ * Every message is secret-free by construction: fixed prose, the flag names, the
+ * file PATH, and CLI-supplied values that came from a closed vocabulary. No
+ * message interpolates a value read out of the policy file.
+ */
+export function preflightSetupEpicPolicy(args) {
+    // 1. Branch strategy. `--feature-branch` versus `--into-base` is already a
+    //    parse error, refused before a file is even read; this is the same
+    //    contradiction spelled across two sources instead of two flags.
+    if (args.intoBase && args.policyDeclaresBranch) {
+        return {
+            ok: false,
+            reason: "branch_strategy_contradiction",
+            message: `--into-base runs children directly into the repository base branch, but ` +
+                `--policy-file '${args.policyFile}' declares a base_branch, which asks for an ` +
+                `epic branch. setup-epic will not pick a winner between them: remove the ` +
+                `branch declaration from the policy file, or drop --into-base.`,
+        };
+    }
+    // 2. Policy-source contradictions between the file and the CLI selections.
+    //    Delegated to the composer, which owns the "no silent winner" rule; the
+    //    gate only gives the outcome a stable name.
+    if (args.filePolicy === undefined)
+        return { ok: true, policy: undefined };
+    const composed = composeSetupEpicPolicy(args.filePolicy, {
+        featureBranch: args.featureBranch,
+        reviewPolicy: args.reviewPolicy,
+    });
+    if (!composed.ok) {
+        return { ok: false, reason: "policy_source_contradiction", message: composed.error };
+    }
+    return { ok: true, policy: composed.policy };
+}
 /**
  * Does this policy object explicitly supply the `notify.webhook_url` leaf?
  *
@@ -775,6 +859,64 @@ export function validateEpicPlanSidecar(parsed) {
     }
     return { ok: true, plan: parsed, warnings };
 }
+/**
+ * The cited-document paths the server reported it could NOT resolve (BAPI-1027).
+ *
+ * Read off the server's own notice rather than re-derived from the plan: the
+ * server decides which citations matter and which it still needs evidence for,
+ * so the CLI resolves exactly what it was asked for and nothing more. That is
+ * what keeps the rule un-mirrored — the CLI reads a field, it does not reimplement
+ * a check.
+ */
+export function unresolvedCitedDocPaths(result) {
+    const paths = [];
+    const seen = new Set();
+    for (const notice of result.notices) {
+        if (notice.noticeCode !== CITED_DOCUMENT_REACHABILITY_NOT_EVALUATED)
+            continue;
+        for (const path of notice.paths) {
+            if (seen.has(path))
+                continue;
+            seen.add(path);
+            paths.push(path);
+        }
+    }
+    return paths;
+}
+/** The server-side notice code naming citations that still need evidence. */
+const CITED_DOCUMENT_REACHABILITY_NOT_EVALUATED = "CITED_DOCUMENT_REACHABILITY_NOT_EVALUATED";
+/** The server-side TERMINAL duplicate-active-run code (BAPI-1027). */
+export const ACTIVE_EPIC_RUN_EXISTS_CODE = "ACTIVE_EPIC_RUN_EXISTS";
+/**
+ * True for a RETRYABLE optimistic-concurrency conflict (BAPI-1016 / BAPI-1027).
+ *
+ * Two conflict families reach this CLI and they call for opposite advice. A
+ * stale-CAS `row_version` means "re-read and retry"; a duplicate active run means
+ * "close or adopt, retrying is futile". They are told apart by the server's own
+ * `error_code`, never by HTTP status — the terminal one is a 409 and the
+ * retryable one is a 400 on these routes, which is precisely the sort of
+ * incidental detail that must not be what a renderer depends on.
+ */
+export function isRetryableConflict(err) {
+    return err instanceof ConductorBridgeApiError && err.errorCode === "CONFLICT";
+}
+/**
+ * Render the ` (BAPI-1, BAPI-2 · docs/x.md)` subject of one rejection line.
+ *
+ * Kept to identifiers the operator needs to act — node keys, a path, a revision
+ * identifier. Specification content, credentials, and raw HTTP bodies never
+ * appear here.
+ */
+export function renderRejectionSubject(rejection) {
+    const parts = [];
+    if (rejection.ticketKeys.length > 0)
+        parts.push(rejection.ticketKeys.join(", "));
+    if (rejection.migrationId)
+        parts.push(`revision ${rejection.migrationId}`);
+    else if (rejection.path)
+        parts.push(rejection.path);
+    return parts.length > 0 ? ` (${parts.join(" · ")})` : "";
+}
 /** Iterative DFS cycle detection; returns the offending path or null. */
 function findCycle(keys, adjacency) {
     const WHITE = 0;
@@ -809,58 +951,85 @@ function findCycle(keys, adjacency) {
     return null;
 }
 /** Propose a conductor epic feature branch name for an epic key (BAPI-655). */
-function proposeFeatureBranchName(epicKey) {
+export function proposeFeatureBranchName(epicKey) {
     return `epic/${epicKey}`;
 }
+/**
+ * The plan-node count at or above which a no-flag run derives its own epic
+ * branch (BAPI-1009, R-4).
+ *
+ * A single-node plan is not an epic in any meaningful sense — it is one ticket,
+ * and plain `start-tickets` puts one ticket's PR straight onto the repository
+ * base branch. Cutting an `epic/<KEY>` branch, seeding a per-epic index scope,
+ * and opening an integration PR for it would add a whole provisioning sequence
+ * (and a second PR to merge) for no isolation benefit. Two or more nodes is
+ * where children can depend on one another, which is exactly the case the epic
+ * branch exists to serve.
+ */
+export const EPIC_BRANCH_MIN_PLAN_NODES = 2;
 /**
  * Resolve the epic feature branch selection for this invocation.
  *
- * Returns a validated branch name, or `undefined` to continue on the repository
- * base branch. Precedence:
+ * Returns a branch name, or `undefined` to continue on the repository base
+ * branch. Pure and synchronous: BAPI-1009 removed the interactive proposal, so
+ * this asks nothing and reads no I/O.
  *
- *   - An explicit `--feature-branch <name>` is already confirmed + validated at
- *     parse time and is returned unchanged (no prompt).
- *   - A non-interactive (piped/CI) run or a `--json` run never prompts and never
- *     blocks — it retains the absent-branch behavior.
- *   - A `--policy-file` that already declares a branch has ALREADY answered this
- *     question (BAPI-754). Prompting anyway would invite an operator to type a
- *     competing value that composition would then have to refuse.
- *   - An interactive run is shown the proposal (branch name, "create from the
- *     repository base branch" strategy, and the child-PR-targeting consequence)
- *     and may accept it, type a custom name, or decline to use the base branch.
- *     An edited nonblank value is re-validated; an invalid value is redisplayed
- *     for correction rather than silently rewritten.
+ * Precedence, in order:
+ *
+ *   1. `--into-base` returns `undefined` unconditionally. It is the explicit
+ *      opt-out, and it wins over the derived default for every node count.
+ *   2. An explicit `--feature-branch <name>` is already confirmed + validated at
+ *      parse time and is returned unchanged. It also forces an epic branch for a
+ *      SINGLE-node plan, which rule 4 would otherwise leave on base.
+ *   3. A `--policy-file` that already declares a branch has ALREADY answered this
+ *      question (BAPI-754), so no CLI branch is added — composition would then
+ *      have to arbitrate between two answers.
+ *   4. A plan with fewer than {@link EPIC_BRANCH_MIN_PLAN_NODES} nodes returns
+ *      `undefined` (R-4).
+ *   5. Otherwise the deterministic {@link proposeFeatureBranchName} value.
+ *
+ * BAPI-1009 deliberately removed the TTY/`--json` early return that used to
+ * produce `undefined` here. Branch strategy that depended on whether stdout was
+ * a terminal meant a CI run and an operator's run of the SAME command bootstrapped
+ * two different topologies — and the CI one was the one the shadow-index bootstrap
+ * was never exercised against.
  */
-async function resolveFeatureBranchSelection(opts, repoName, deps, policyDeclaresBranch = false) {
+export function resolveFeatureBranchSelection(opts, planNodeCount, policyDeclaresBranch = false) {
+    if (opts.intoBase)
+        return undefined;
     if (opts.featureBranch !== undefined)
         return opts.featureBranch;
     if (policyDeclaresBranch)
         return undefined;
-    if (!deps.isTTY || opts.json)
+    if (planNodeCount < EPIC_BRANCH_MIN_PLAN_NODES)
         return undefined;
-    const proposed = proposeFeatureBranchName(opts.epicKey);
-    deps.errorLog("");
-    deps.errorLog(`Feature branch (optional) for epic ${opts.epicKey} on ${repoName}:`);
-    deps.errorLog(`  Proposed:  ${proposed}`);
-    deps.errorLog(`  Strategy:  create a new branch from the repository base branch`);
-    deps.errorLog(`  Effect:    every child-ticket PR will target this branch`);
-    for (;;) {
-        const answer = (await deps.promptLine(`Use feature branch? 'y' = ${proposed}, a name = custom, Enter = base branch: `)).trim();
-        if (answer === "")
-            return undefined; // decline → repository base branch
-        const lowered = answer.toLowerCase();
-        if (lowered === "n" || lowered === "no")
-            return undefined;
-        if (lowered === "y" || lowered === "yes")
-            return proposed;
-        // Otherwise the answer is an edited branch name.
-        const reason = validateBranchName(answer);
-        if (reason) {
-            deps.errorLog(`  Invalid branch name: ${reason} Try again, or press Enter for the base branch.`);
-            continue; // redisplay for correction; never silently rewrite the value
-        }
-        return answer;
+    return proposeFeatureBranchName(opts.epicKey);
+}
+/**
+ * One line naming the selected branch strategy AND why it was selected.
+ *
+ * BAPI-1009: the "why" is the load-bearing half. The default changed, so an
+ * operator reading `epic/BAPI-1009` needs to know whether they asked for it,
+ * their policy file asked for it, or the multi-node default derived it — those
+ * three have different recovery steps when the name is not the one they wanted.
+ */
+function describeBranchStrategy(opts, featureBranch, policyDeclaresBranch) {
+    const cutNote = "cut on origin with local git at the canonical indexed commit; " +
+        "validated server-side at approval";
+    if (featureBranch !== undefined) {
+        if (opts.featureBranch !== undefined) {
+            return `${featureBranch} (explicit --feature-branch override; ${cutNote})`;
+        }
+        return `${featureBranch} (derived epic branch for this multi-ticket plan; ${cutNote})`;
     }
+    if (opts.intoBase) {
+        return "repository base branch — epic branch disabled by --into-base; every child PR targets base";
+    }
+    if (policyDeclaresBranch) {
+        return "from the policy file's base_branch (the file already answered this)";
+    }
+    return (`repository base branch — a single-node plan keeps base, matching start-tickets ` +
+        `(pass --feature-branch to force ${proposeFeatureBranchName(opts.epicKey)} anyway)`);
 }
 function errorDetail(err) {
     if (err instanceof ConductorBridgeApiError) {
@@ -941,6 +1110,36 @@ function emitRefusal(deps, opts, result) {
  * 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 canonical one-line recovery for a scope collision (BAPI-1009).
+ *
+ * Repeated VERBATIM as the epic-run gate snapshot's shadow-hold recovery hint
+ * (``api/library/epic_conductor/gate_snapshot_service.py``), so an operator who
+ * reads the diagnosis on the status surface and an operator who reads it from
+ * the CLI are told to do the same thing in the same words.
+ */
+export const SETUP_EPIC_SCOPE_REDRIVE_RECOVERY = "Re-drive the cut at the newer commit.";
+/**
+ * How long `setup-epic` waits for a scope cut before acknowledging it as
+ * DEFERRED (BAPI-1054).
+ *
+ * Six polls at the shared 5-second interval — roughly 30 seconds. It is a fixed
+ * value, injectable for tests but deliberately NOT operator-configurable, so
+ * "returns promptly" is one testable number rather than a range that depends on
+ * how the operator invoked the command.
+ *
+ * It bounds THIS caller only. {@link SCOPE_BOOTSTRAP_MAX_POLLS} is untouched, so
+ * anything else that drives the shared poll keeps the generous default a real
+ * seed needs. Waiting the full ~20 minutes was never buying information: the run
+ * is already created and approved, the reconciler holds dispatch until the scope
+ * is ready either way, and the only thing the long block changed was whether the
+ * operator's terminal was occupied while it happened.
+ */
+export const SETUP_EPIC_SCOPE_DEFERRED_MAX_POLLS = 6;
+/** The deferred window in seconds, derived so prose cannot drift from the bound. */
+export const SETUP_EPIC_SCOPE_DEFERRED_WINDOW_SECONDS = Math.round((SETUP_EPIC_SCOPE_DEFERRED_MAX_POLLS * SCOPE_BOOTSTRAP_POLL_INTERVAL_MS) / 1000);
+/** The exact phrase the deferred acknowledgement leads with. Named so tests pin it. */
+export const SETUP_EPIC_CUT_DEFERRED_PHRASE = "created, cut deferred";
 /** The lead sentence of every fail-closed canonical-parse refusal (BAPI-850). */
 export const SETUP_EPIC_PARSE_FIRST_MESSAGE = "parse the repository first";
 /**
@@ -1049,9 +1248,20 @@ async function resolveScopeIdForRun(access, fetchImpl, epicRunId) {
  * ONE run), so it is always named explicitly rather than left as a placeholder.
  */
 function scopeFailureGuidance(reason, featureBranch, epicRunId) {
+    // BAPI-1009: both collision categories lead with the SAME canonical sentence the
+    // run snapshot's recovery hint repeats, then keep their own remediation detail.
+    // The default now cuts a branch where it previously did not, so a collision is
+    // reachable by operators who never chose a branch strategy at all — the recovery
+    // has to read identically wherever they happen to encounter it.
     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 ` +
+        return (`${SETUP_EPIC_SCOPE_REDRIVE_RECOVERY} The canonical index advanced before the ` +
+            `scope could be seeded: delete origin/${featureBranch}, abandon this run ` +
+            `(conductor abandon-run --epic-run-id ${epicRunId}), and re-run setup-epic.`);
+    }
+    if (reason === "head_mismatch") {
+        return (`${SETUP_EPIC_SCOPE_REDRIVE_RECOVERY} origin/${featureBranch} does not sit at the ` +
+            `commit this scope was cut at, and setup-epic never force-updates an existing ` +
+            `ref: delete origin/${featureBranch}, abandon this run ` +
             `(conductor abandon-run --epic-run-id ${epicRunId}), and re-run setup-epic.`);
     }
     return `Recovery: ${SETUP_EPIC_SCOPE_RECOVERY_COMMAND}.`;
@@ -1064,11 +1274,20 @@ function scopeFailureGuidance(reason, featureBranch, epicRunId) {
  * detail: the label leads, the scope id never does, and no credential appears.
  */
 function describeScopeTransition(state, status) {
-    const label = SCOPE_LIFECYCLE_LABELS[state] ?? state;
+    // BAPI-1054: bounded on the way in, so an unrecognized server state renders as
+    // `unknown` rather than as itself. `SCOPE_LIFECYCLE_LABELS[state] ?? state`
+    // fell through to the raw value for anything outside the known set.
+    const bounded = boundScopeLifecycleLabel(state);
+    const label = SCOPE_LIFECYCLE_LABELS[bounded] ?? bounded;
     if (state === "ready") {
         return `Scope:      ${label} — indexed at ${status.indexed_commit_sha ?? "unknown"} (scope ${status.scope_id})`;
     }
     if (state === "failed") {
+        // `last_error` is the bounded failure CATEGORY, not free text: the terminal
+        // branch already surfaces the same value as `index_scope.failure_reason` and
+        // switches on it in `scopeFailureGuidance`. Dropping it here would lose the
+        // one fact that distinguishes a recoverable collision from a seed failure,
+        // while removing nothing that is not already reported.
         return `Scope:      ${label} — ${status.last_error ?? "unknown"} (scope ${status.scope_id})`;
     }
     return `Scope:      ${label}…`;
@@ -1135,22 +1354,47 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     }
     const policyDeclaresBranch = filePolicy !== undefined &&
         ["base_branch", "baseBranch"].some((key) => key in filePolicy && filePolicy[key] !== undefined && filePolicy[key] !== null);
+    // --- Feature branch selection (BAPI-655, defaulted by BAPI-1009) ---------
+    // Resolved from the VALIDATED plan's node count, the flags, and the policy
+    // file — all of which are already in hand — and deliberately BEFORE the
+    // `--local-only` return and before credential resolution. Selection reads no
+    // network and asks no question, so running it here is what makes `--local-only`
+    // and an ordinary invocation report the same strategy for the same plan.
+    const featureBranch = resolveFeatureBranchSelection(opts, plan.nodes.length, policyDeclaresBranch);
+    const branchStrategyLine = describeBranchStrategy(opts, featureBranch, policyDeclaresBranch);
+    // --- Consolidated policy preflight (BAPI-1054) ---------------------------
+    // ONE gate, run BEFORE credential resolution and before any request, over the
+    // whole flag-backed choice-set. It sits above the `--local-only` return
+    // deliberately: a dry run that refuses a different set from the real run is
+    // worth very little, and this branch previously composed the policy without
+    // evaluating the `--into-base` contradiction alongside it.
+    //
+    // The server's `RunPolicy` schema stays authoritative. This validates the
+    // choices the CLI itself surfaces and nothing else — a field-named `422` is
+    // still the better error for everything inside the policy file.
+    const policyGate = preflightSetupEpicPolicy({
+        intoBase: opts.intoBase,
+        policyFile: opts.policyFile,
+        filePolicy,
+        policyDeclaresBranch,
+        featureBranch,
+        reviewPolicy: opts.reviewPolicy,
+    });
+    if (!policyGate.ok) {
+        deps.errorLog(policyGate.message);
+        return 1;
+    }
     // --- --local-only --dry-run: stop here, offline and explicitly partial ----
     // Nothing below this point is reachable without the network, and the whole
     // point of the flag is to not touch it — not even to resolve a credential.
     if (opts.localOnly) {
-        if (filePolicy !== undefined) {
-            const composed = composeSetupEpicPolicy(filePolicy, {
-                featureBranch: opts.featureBranch,
-                reviewPolicy: opts.reviewPolicy,
-            });
-            if (!composed.ok) {
-                deps.errorLog(composed.error);
-                return 1;
-            }
-        }
+        // The policy gate above already composed and validated; nothing is repeated
+        // here, so the offline path and the real path refuse the same set.
         say(`Epic:       ${opts.epicKey}`);
         say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${plan.edges.length} edge(s)`);
+        // BAPI-1009: the same node-count-derived strategy an ordinary run would take,
+        // stated without cutting a branch, reading the network, or touching git.
+        say(`Branch:     ${branchStrategyLine}`);
         say(`Local hash: ${localHash}`);
         for (const w of warnings)
             say(`  [warn] ${w}`);
@@ -1195,35 +1439,19 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     say(`Local hash: ${localHash}`);
     for (const w of warnings)
         say(`  [warn] ${w}`);
-    // --- 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
-    // dispatch. Returns undefined to continue on the repository base branch.
-    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} (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.
-        say("Feature:    none — continue using the repository base branch");
-    }
-    // --- Compose the requested run policy (BAPI-754) -------------------------
-    // A contradiction between the file and the flags is refused here, before the
-    // pre-check and long before any create, so no request is dispatched under a
-    // policy nobody chose.
-    let requestedPolicy;
-    if (filePolicy !== undefined) {
-        const composed = composeSetupEpicPolicy(filePolicy, {
-            featureBranch,
-            reviewPolicy: opts.reviewPolicy,
-        });
-        if (!composed.ok) {
-            deps.errorLog(composed.error);
-            return 1;
-        }
-        requestedPolicy = composed.policy;
+    // --- 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
+    // where every child PR lands — an operator who reads nothing else must still
+    // see which topology this run is about to bootstrap.
+    say(`Branch:     ${branchStrategyLine}`);
+    // --- The requested run policy (BAPI-754; gated by BAPI-1054) -------------
+    // Composition and every contradiction refusal already happened in the policy
+    // preflight above, before credentials were resolved. This is the SAME object
+    // that passed the gate — not a second composition — so the payload the create
+    // request carries is exactly what was validated.
+    const requestedPolicy = policyGate.policy;
+    if (requestedPolicy !== undefined) {
         say(`Policy:     ${opts.policyFile} (complete run policy, applied at creation)`);
     }
     // --- Effective feature branch (BAPI-850) ----------------------------------
@@ -1291,16 +1519,55 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // --- 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
-    // branch is allowed (the rerun re-validates remote provisioning at approval);
-    // supplying no branch preserves the existing run's policy untouched.
+    // branch is allowed (the rerun re-validates remote provisioning at approval).
+    //
+    // BAPI-1009: `featureBranch` can now be DERIVED, so this guard also catches the
+    // new case — a live run created under the old direct-to-base default, re-run
+    // after the default flipped. Continuing would dispatch children at base while
+    // every message on screen named an epic branch. The remedy differs by how the
+    // branch was chosen, so the guidance names the flag that actually applies:
+    // dropping `--feature-branch` reuses the run only when the flag is what asked
+    // for the branch; when the DEFAULT asked, `--into-base` is the way to say
+    // "keep this run on base".
     if (existingRunId && featureBranch !== undefined && existingBaseBranch !== featureBranch) {
+        const reuseAdvice = opts.featureBranch !== undefined
+            ? "Re-run without --feature-branch to reuse it unchanged"
+            : `Re-run with --into-base to reuse it on the base branch it was created with`;
         deps.errorLog(`Epic ${opts.epicKey} already has a live run (${existingRunId}) whose feature ` +
             `branch is ${existingBaseBranch ? `'${existingBaseBranch}'` : "unset (base branch)"}, ` +
-            `which conflicts with the requested '${featureBranch}'. setup-epic will not ` +
-            `retarget or rebuild an existing run. Re-run without --feature-branch to reuse ` +
-            `it unchanged, or abandon the run to start over on a new branch.`);
+            `which conflicts with the selected '${featureBranch}'. setup-epic will not ` +
+            `retarget or rebuild an existing run. ${reuseAdvice}, or abandon the run to ` +
+            `start over on a new branch.`);
         return 1;
     }
+    // BAPI-1009: the mirror image — `--into-base` against a run that already lives
+    // on an epic branch. The guard above cannot see this one, because `--into-base`
+    // resolves to NO selected branch and so never disagrees with a stored value.
+    // Reusing silently would report base mode for a run whose scope, cut, and
+    // integration PR all belong to the epic branch.
+    //
+    // A stored `base_branch` is NOT by itself an epic branch: a run created with
+    // `base_branch: "main"` is ALREADY on base, and refusing it would be a false
+    // refusal. So the comparison is made against the repository's configured base,
+    // resolved exactly the way the cut path below resolves it — same client, same
+    // `"main"` fallback for an unreadable config — because "a branch equal to the
+    // configured base is not scope-bearing" is an existing rule here, and a second
+    // rule that disagreed with it would be worse than the extra read.
+    if (existingRunId && opts.intoBase && existingBaseBranch !== null) {
+        const configuredBase = await getConfigFieldBaseBranch(access, deps.fetch);
+        const repositoryBase = configuredBase.ok && configuredBase.value.base_branch !== null
+            ? configuredBase.value.base_branch
+            : "main";
+        if (existingBaseBranch !== repositoryBase) {
+            deps.errorLog(`Epic ${opts.epicKey} already has a live run (${existingRunId}) on feature branch ` +
+                `'${existingBaseBranch}', not the repository base '${repositoryBase}', and ` +
+                `--into-base asks for the repository base branch. setup-epic will not retarget ` +
+                `an existing run. Re-run without --into-base to reuse it unchanged, or abandon ` +
+                `the run (conductor abandon-run --epic-run-id ${existingRunId}) and recreate ` +
+                `it on base.`);
+            return 1;
+        }
+    }
     // --- Review-policy conflict guard against an existing live run ----------
     // BAPI-679, analogous to the feature-branch guard above. An explicitly selected
     // policy that disagrees with a live run's effective policy must fail closed:
@@ -1325,12 +1592,55 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // row and an automation-start debit on the way to finding that out.
     let validated = null;
     let validateLaneMissing = false;
+    // BAPI-1027 — the evidence the successful validation was given, carried onto
+    // the later store call so both lanes judge the plan against the same facts.
+    let trackedPathEvidence;
     try {
         validated = await validateEpicPlan(access, {
             planVersion: plan.plan_version,
             planBlob: plan,
             epicKey: opts.epicKey,
         }, deps.fetch);
+        // BAPI-1027 — phase two of the two-phase exchange. The server names the
+        // cited-document paths it could not resolve; only THEN does the CLI touch
+        // git, and only for those exact paths. The rules stay server-side: the CLI
+        // supplies facts and never decides whether a plan passes.
+        //
+        // Skipped entirely when the first response already carries blocking
+        // rejections. Those are unrelated to trackedness, the plan is going to be
+        // refused either way, and running git plus a second billable-free round trip
+        // to enrich a verdict that will not change is pure latency.
+        const unresolved = unresolvedCitedDocPaths(validated);
+        if (validated.rejections.length === 0 && unresolved.length > 0) {
+            const oracleRun = deps.runCommand;
+            if (!oracleRun) {
+                deps.errorLog(`Validation could not be completed: ${unresolved.length} cited document ` +
+                    `path(s) need a git trackedness check, but no local command runner is ` +
+                    `available in this environment. No run was created and no ` +
+                    `automation-start charge occurred.`);
+                return 1;
+            }
+            const resolution = await resolveTrackedPaths(deps.cwd, unresolved, {
+                runCommand: oracleRun,
+            });
+            if (!resolution.ok) {
+                // An unresolved oracle is "validation could not be completed", NEVER
+                // "these documents are missing". Continuing would store a plan whose
+                // citations were never checked while reporting a clean preflight.
+                deps.errorLog(`Validation could not be completed: the cited documents in this plan ` +
+                    `could not be checked against version control.\n${resolution.error}\n` +
+                    `No run was created and no automation-start charge occurred. Re-run ` +
+                    `from inside the repository working tree once git is available.`);
+                return 1;
+            }
+            trackedPathEvidence = resolution.facts;
+            validated = await validateEpicPlan(access, {
+                planVersion: plan.plan_version,
+                planBlob: plan,
+                epicKey: opts.epicKey,
+                trackedPaths: trackedPathEvidence,
+            }, deps.fetch);
+        }
     }
     catch (err) {
         const status = err instanceof ConductorBridgeApiError ? err.status : undefined;
@@ -1353,16 +1663,36 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 `occurred.\nDetail: ${errorDetail(err)}`);
             return 1;
         }
+        else if (isRetryableConflict(err)) {
+            // BAPI-1027 — a RETRYABLE stale-CAS conflict (post-BAPI-1016). The plan is
+            // fine and so is the epic; someone else wrote concurrently between the read
+            // and this call. Rendered with retry language and deliberately WITHOUT any
+            // close/adopt/abandon wording: telling an operator to abandon a run over a
+            // conflict they should simply retry is the exact confusion the distinct
+            // codes exist to prevent.
+            deps.errorLog(`Plan changed concurrently; re-read and retry validation.\n` +
+                `Nothing was created, stored, or charged — this is a transient ` +
+                `concurrency conflict, not a problem with your plan or your epic.\n` +
+                `Detail: ${errorDetail(err)}`);
+            return 1;
+        }
         else if (status === 409) {
             // The epic is WEDGED (multiple active runs), which says nothing about the
             // plan. Reporting this as "server validation: failed" would send the
             // operator to fix a sidecar that is perfectly fine. The pre-check above
             // normally catches this first; this branch covers the race where a
             // duplicate run appears between the pre-check and the validate call.
+            //
+            // BAPI-1027 — TERMINAL, and said so plainly: the server now names this
+            // `ACTIVE_EPIC_RUN_EXISTS`, distinct from the retryable conflict handled
+            // above. Retrying never clears it. The branch still fires on a bare 409
+            // from a server that predates the code, so an older deployment keeps the
+            // behavior it always had.
             deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — the plan could not be ` +
                 `validated because the epic itself is wedged, and every plan call will ` +
-                `keep failing. This is NOT a problem with your plan. Abandon the ` +
-                `duplicate before retrying:\n` +
+                `keep failing. This is TERMINAL: it will not clear on retry, and it is ` +
+                `NOT a problem with your plan. Adopt the run you want to keep, or ` +
+                `abandon the duplicate:\n` +
                 `  conductor abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
                 `No run was created and no automation-start charge occurred.\n` +
                 `Detail: ${errorDetail(err)}`);
@@ -1374,9 +1704,37 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             return 1;
         }
     }
+    if (validated && validated.rejections.length > 0) {
+        // BAPI-1027 — a lint rejection is the plan's own fault and is terminal here:
+        // no run is created, nothing is stored, and no charge occurs. Rendered to
+        // STDERR (never stdout, which under --json carries the single result object
+        // and which in MCP server mode is the stdio transport), one compact line per
+        // rejection so an operator can fix every fault in one pass instead of
+        // rediscovering them one round trip at a time.
+        deps.errorLog(`Plan needs attention: ${validated.rejections.length} lint rejection(s).`);
+        for (const rejection of validated.rejections) {
+            deps.errorLog(`  ${rejection.reasonCode}${renderRejectionSubject(rejection)}: ${rejection.explanation}`);
+        }
+        deps.errorLog("The plan was NOT stored and no run was created; no automation-start charge " +
+            "occurred. Fix the plan file and re-run — setup-epic never rewrites a plan, " +
+            "because that would change its hash.");
+        return 1;
+    }
     if (validated) {
         say("Validation: server validation: passed");
+        say("            Plan ready to store");
+        say("            No lint rejections found");
         say(`            plan hash ${validated.planHash}`);
+        // BAPI-1027 — "nothing was found" and "everything was checked" are different
+        // statements, and reporting the first as the second is the false assurance
+        // this lane exists to remove. An incomplete evaluation is a WARNING on
+        // stderr: the plan is storable, and the operator is told what went unchecked.
+        if (!validated.evaluationComplete) {
+            for (const notice of validated.notices) {
+                deps.errorLog(`WARNING: ${notice.noticeCode}: ${notice.explanation}` +
+                    (notice.paths.length > 0 ? `\n         Unchecked: ${notice.paths.join(", ")}` : ""));
+            }
+        }
         // 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
@@ -1622,7 +1980,17 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             else {
                 // The pre-check said there was no live run, but create found one — a
                 // concurrent setup won the race. Treat it exactly like the reuse path.
-                say(`Run:        reusing ${run.epic_run_id} (status: ${run.status})`);
+                //
+                // BAPI-1027 — this ADOPTION is the normal answer to "a second setup for
+                // one epic", not an error: `create_epic_run` returns the existing
+                // non-terminal run untouched, and the `uq_epic_runs_active_repo_epic_key`
+                // index is the race backstop that keeps it so. Naming the adopted run and
+                // its status, rather than reporting a bare reuse, is what lets an operator
+                // decide between continuing on it and closing it.
+                say(`Run:        adopting existing active run ${run.epic_run_id} (status: ${run.status})`);
+                say(`            No second run was created — one epic has at most one active ` +
+                    `run. Continue on this one, or abandon it first with ` +
+                    `\`conductor abandon-run --epic-run-id ${run.epic_run_id}\` to start over.`);
                 if (requestedPolicy !== undefined) {
                     const outcome = await applyReusedRunPolicy({
                         access,
@@ -1642,6 +2010,18 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         catch (err) {
             const status = err instanceof ConductorBridgeApiError ? err.status : undefined;
             if (status === 422 && requestedPolicy !== undefined) {
+                // BAPI-1054 investigated whether `errorDetail`'s `bodyPreview` could echo
+                // policy content here — a run policy can carry `notify.webhook_url`, and
+                // a FastAPI validation detail routinely repeats the submitted `input`.
+                //
+                // It cannot, and the guard is one layer down where it belongs:
+                // `formatValidationDetailItem` (conductor/bridge-api-client.ts) reduces a
+                // 422 detail to `<loc path>: <msg>` — field NAMES and the validator's own
+                // message, with `input` never read and the transport-only `body` prefix
+                // dropped — and `redactDiagnosticValues` then scrubs known secrets.
+                // Re-sanitizing here would only destroy the field name that makes the
+                // server's field-named 422 actionable. The property is pinned by the
+                // regression test below rather than left to this comment.
                 deps.errorLog(`The run policy from '${opts.policyFile}' was rejected by the server.\n` +
                     `${errorDetail(err)}\n` +
                     `No run was created and no automation-start charge occurred. Fix the ` +
@@ -1685,7 +2065,22 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 // and replace a stale record on its own, and there is nothing running to
                 // hand this binding to yet.
             }
-            // A missing or unvalidated manifest is normal — no attempt, no warning.
+            else if (manifestRead.kind !== "missing") {
+                // NOT normal, and previously silent (BAPI-1029). `missing` genuinely
+                // means "no local plane" — remote runs, CI, any non-plane workflow — and
+                // stays quiet. `malformed` and `unreadable` mean a manifest EXISTS and
+                // this build could not validate it, which is exactly what happens when
+                // it was written by a newer build. A plane may well be running, and the
+                // binding it needed just did not happen; saying nothing left the
+                // operator to discover that at `plane down` time.
+                const msg = `A local plane manifest exists but could not be validated (${manifestRead.error}), so ` +
+                    `run ${result.epic_run_id} was NOT bound to it. If a plane is running, \`plane down\` ` +
+                    "will not stop this run automatically — use " +
+                    `\`conductor stop-run --epic-run-id ${result.epic_run_id}\`. A manifest written by a ` +
+                    "NEWER build must be wound down with that build's `plane down`.";
+                warnings.push(msg);
+                say(`Plane:      [warn] ${msg}`);
+            }
         }
         catch (err) {
             // The binding capability itself must never fail setup-epic as a whole;
@@ -1764,6 +2159,12 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             planVersion: plan.plan_version,
             planBlob: plan,
             planHash: localHash,
+            // BAPI-1027 — the same working-tree facts the dry run was validated
+            // against. Without them the store lane would re-evaluate this plan with
+            // NO evidence, report cited-document reachability as "not evaluated",
+            // and quietly reach a different verdict than the preflight the operator
+            // was just shown.
+            ...(trackedPathEvidence !== undefined ? { trackedPaths: trackedPathEvidence } : {}),
         }, deps.fetch);
         result.plan_stored = true;
         const serverHash = stored?.plan_hash;
@@ -1870,8 +2271,14 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             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)) });
+            say(`Scope:      waiting up to ~${SETUP_EPIC_SCOPE_DEFERRED_WINDOW_SECONDS}s for index scope ` +
+                `readiness; if it is still preparing, this returns and preparation continues server-side.`);
+            const verdict = await pollIndexScopeLifecycle(cutProtocolDeps(deps, cutRunCommand ?? deps.runCommand ?? createExecFileRunCommand()), access, scopeId, {
+                onTransition: (state, status) => say(describeScopeTransition(state, status)),
+                // BAPI-1054: THIS caller's bound only. The shared default is untouched,
+                // so nothing else that drives this poll waits any less than it did.
+                maxPolls: SETUP_EPIC_SCOPE_DEFERRED_MAX_POLLS,
+            });
             if (verdict.kind === "ready") {
                 result.index_scope = {
                     scope_id: scopeId,
@@ -1916,20 +2323,25 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 exitCode = 1;
             }
             else {
+                // BAPI-1054 (AC-2): NOT a failure. The run is created and approved, and
+                // the reconciler holds dispatch until the scope is ready — a safe hold.
+                // Reporting it as exit 1 after a ~20-minute block made a perfectly good
+                // run read as a failed command, which is the whole defect this closes.
+                //
+                // Every rendered value is bounded: the run id, the scope id, and a
+                // lifecycle label the poll already collapsed to a known label,
+                // `unreadable`, or `unknown`. No raw status, no server error text, no URL.
+                const lastState = boundScopeLifecycleLabel(verdict.lastState);
                 result.index_scope = {
                     scope_id: scopeId,
                     cut_commit_sha: verdict.lastStatus?.cut_commit_sha ?? cutCommitSha,
-                    lifecycle_state: verdict.lastStatus?.lifecycle_state ?? null,
+                    lifecycle_state: lastState,
                     ready: false,
-                    disposition: "timeout",
+                    disposition: "created_cut_deferred",
                 };
-                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;
+                say(`Scope:      ${SETUP_EPIC_CUT_DEFERRED_PHRASE} — run ${result.epic_run_id}, ` +
+                    `scope ${scopeId}, last observed state '${lastState}'. Scope preparation ` +
+                    `continues server-side; the reconciler holds dispatch until it is ready.`);
             }
         }
     }
@@ -1947,7 +2359,16 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 "order was used. Check that BAPI_BASE_URL points at the intended deployment.");
         }
         say(`Epic run ${result.epic_run_id} is ${result.status ?? "unknown"}.`);
-        say("The server-side reconciler will pick it up within ~30s.");
+        // BAPI-1054: a deferred cut means the reconciler picks the run up but HOLDS
+        // dispatch, so the unqualified "~30s" line would contradict the
+        // acknowledgement printed moments earlier.
+        if (result.index_scope?.disposition === "created_cut_deferred") {
+            say("The server-side reconciler will pick it up within ~30s, but holds ticket " +
+                "dispatch until the index scope finishes preparing.");
+        }
+        else {
+            say("The server-side reconciler will pick it up within ~30s.");
+        }
         say("To execute claimed jobs on this machine, run:");
         say(`  npx -y ${MCP_PACKAGE_NAME} executor --repo ${access.repoName}`);
     }