@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/drive-epic.js

@@ -53,13 +53,15 @@
  * ratcheted down, and a tool would be useless in a bare-chat session anyway,
  * where the model has no tool call to make.
  */
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { ConductorBridgeApiError, resolveEpicLaunchBridgeApiAccess, fetchConductorReadiness, fetchEpicRunState, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
+import { readdir, readFile } from "node:fs/promises";
+import path, { dirname, join } from "node:path";
+import { CONDUCTOR_DEFAULT_BASE_URL, ConductorBridgeApiError, resolveEpicLaunchBridgeApiAccess, fetchConductorReadiness, fetchEpicRunState, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
 import { EPIC_LAUNCH_PROFILE_NAME_PATTERN, renderEpicLaunchCommand, shellQuote, } from "./epic-launch-profile.js";
 import { validateHttpBaseUrl, describeBaseUrlRejection } from "./base-url.js";
 import { BRING_UP_REFUSAL_MESSAGES, BRING_UP_RUNBOOK, firstBringUpRefusal, } from "./conductor/bring-up-facts.js";
-import { runSetupEpicWorkflow, } from "./setup-epic.js";
+import { policyDeclaresNotifyWebhook, readSetupEpicPolicyFile, runSetupEpicWorkflow, } from "./setup-epic.js";
+import { EPIC_KEY_PATTERN } from "./drive-epic-key.js";
+import { discoverEpicPlan, } from "./plan-discovery.js";
 import { formatPlaneDiagnostic, launchPlaneControlPlane, requestPlaneScopedLanes, runDefaultPlanePreflight, runPlaneCli, } from "./plane/cli.js";
 import { PLANE_PORT_PROBE_TIMEOUT_MS, describePlanePortOccupant, } from "./plane/preflight.js";
 import { createPlaneFsDeps, probeAutomationHealth, probeTcpPort, resolveHostname, } from "./plane/defaults.js";
@@ -68,11 +70,11 @@ import { resolvePlaneServerEndpoint, } from "./plane/member-roster.js";
 import { resolveMemberInstanceId } from "./plane/supervisor.js";
 import { PLANE_SERVER_PORT_ENV_VAR, } from "./plane/types.js";
 import { validateBranchName } from "./base-ref.js";
+import { createDefaultRunExecutorLaunchDeps, ensureRunExecutor as ensureRunExecutorDefault, prepareRunExecutor as prepareRunExecutorDefault, } from "./executor-launch.js";
+import { isTerminalEpicRunStatus } from "./epic-run-status.js";
 // BAPI-806: mcp-identity.ts is the SOLE source of the package-name literal, so
 // the printed invocation interpolates it rather than repeating it.
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
-/** Jira epic key shape. Matches the epic-key positional rule exactly. */
-const EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
 /** The conductor paths. Derived types below come from this constant. */
 export const DRIVE_EPIC_CONDUCTORS = ["v2"];
 /**
@@ -112,11 +114,22 @@ export const V2_READINESS_REQUIREMENTS = [
     {
         id: "reconciler_live",
         describe: "a reconciler that is ticking and not stale",
-        satisfied: (r) => r.reconciler.liveness_readable && !r.reconciler.stale,
+        // BAPI-1279 — launch liveness is a DEPLOYMENT fact. The `bring_up` block
+        // reads the reconciler's process heartbeat deployment-wide, so a repository
+        // that has never run an epic still reads live when the worker is healthy.
+        // The repository-scoped `reconciler` section ("is this repository's work
+        // moving?", from `epic_runs.last_tick_at`) is only the fallback for a server
+        // too old to report `bring_up`.
+        satisfied: (r) => r.bring_up !== null && r.bring_up !== undefined
+            ? r.bring_up.heartbeat_readable && r.bring_up.worker_present
+            : r.reconciler.liveness_readable && !r.reconciler.stale,
     },
     {
         id: "executor_live",
         describe: "an executor provisioned and reporting ready",
+        // BAPI-1279 — diagnostic only. drive-epic starts (or, for a durable profile,
+        // verifies) the run's executor itself once the run exists.
+        advisoryOnly: true,
         satisfied: (r) => r.executor.liveness_readable && r.executor.ready === true,
     },
     // BAPI-1102 — the three unattended prerequisites, in the order `setup-epic`
@@ -140,17 +153,22 @@ export const V2_READINESS_REQUIREMENTS = [
             ? "This Bridge API deploy does not report a repository's unattended " +
                 "prerequisites at all, so none of them could be confirmed. Upgrade the " +
                 "deploy, or pass --attended."
-            : "Set `unattended_epic_implementer_allowed` for this repository " +
-                "(docs/claude/account-settings-operator-runbook.md), or pass --attended.",
+            : "Unattended runs are off for this repository. Turn on 'Allow unattended " +
+                "Epic Implementer runs' on the repository's Setup page in the Bridge " +
+                "admin panel, or pass --attended. If it is already on, contact Bridge support.",
         satisfied: (r) => r.unattended?.conductor_allowed === true,
     },
     {
         id: "unattended_notify_default",
         describe: "a verified notify webhook default for escalation",
         unattendedOnly: true,
-        remedy: "Supply a --policy-file declaring notify.webhook_url, or pass --attended. " +
+        remedy: "Supply a --policy-file declaring notify.webhook_url, or add an email address " +
+            "to the account so escalation alerts can be emailed, or pass --attended. " +
             "notify.local_sink does not satisfy this.",
-        satisfied: (r) => r.unattended?.notify_webhook_default_declared === true,
+        // BAPI-1274 — the account's email address is an escalation channel when no
+        // webhook is declared; the server reports its presence, never the address.
+        satisfied: (r) => r.unattended?.notify_webhook_default_declared === true ||
+            r.unattended?.escalation_email_available === true,
     },
     {
         id: "repository_readiness",
@@ -190,7 +208,10 @@ export const V2_READINESS_REQUIREMENTS = [
 /**
  * The readiness facts a `plane up` can actually repair (BAPI-1054).
  *
- * Both are liveness of a process this machine starts. Everything else —
+ * BAPI-1279 narrowed this to the reconciler. `executor_live` is advisory now
+ * (see `advisoryOnly`): drive-epic ensures the run's executor itself after the
+ * run is created, so its absence before then is never unmet. What remains is
+ * liveness of a process this machine starts. Everything else —
  * `supervisor_setup`, `supervisor_config`, `github_credentials`, and (BAPI-1102)
  * `unattended_consent`, `unattended_notify_default`, `repository_readiness` — is
  * stored server-side state, credentials, or repository configuration, and no
@@ -203,7 +224,7 @@ export const V2_READINESS_REQUIREMENTS = [
  * running plane behind and change nothing — which is the precise failure the
  * classification exists to prevent.
  */
-export const V2_RUNTIME_READINESS_IDS = ["reconciler_live", "executor_live"];
+export const V2_RUNTIME_READINESS_IDS = ["reconciler_live"];
 /**
  * Classify the SERVER's readiness report into the composition's three cases.
  *
@@ -243,9 +264,11 @@ export function classifyV2Readiness(readiness, options = {}) {
     // to say about — the same reasoning `--attended` rests on, reached by a
     // different route. See `composeDefaultSetupEpicPolicy`.
     const optedOut = options.attended === true || options.intoBase === true;
+    // BAPI-1279 — advisory rows are reported, never unmet.
+    const gating = deferred.filter((req) => req.advisoryOnly !== true);
     const applicable = optedOut
-        ? deferred.filter((req) => req.unattendedOnly !== true)
-        : deferred;
+        ? gating.filter((req) => req.unattendedOnly !== true)
+        : gating;
     const unmet = applicable.filter((req) => !req.satisfied(readiness));
     if (unmet.length === 0)
         return { kind: "green" };
@@ -284,18 +307,34 @@ export function getDriveEpicUsage() {
         "UNATTENDED by default — it authorizes automatic merge into the epic branch, and",
         "the server stamps its CI gate at first approval. The INTEGRATION PR into the",
         "repository base branch stays human-gated. Pass --attended to opt out. An",
-        "unattended run has two one-time repository prerequisites (consent, and a",
-        "verified notify webhook default) that readiness lists with their state and that",
-        "are refused BY NAME before any run is created.",
+        "unattended run has two repository prerequisites (consent, which is ON by",
+        "default and switched on the Bridge admin panel's Setup page, and a verified",
+        "notify webhook default) that readiness lists with their state and that are",
+        "refused BY NAME before any run is created.",
+        "",
+        "Every run gets an executor (BAPI-1279): with --plan-file, once the run is",
+        "created drive-epic starts a RUN-SCOPED EXECUTOR for it in the background, from",
+        "this checkout's Git top level. It claims only that run's jobs, logs to",
+        ".bridge/executors/<run>.log, and exits on its own when the run is done or",
+        "abandoned. Re-running for the same live run starts no second one. A durable",
+        "launch profile starts none: it requires a fresh --repo-wide executor instead.",
+        "Checks that need no run happen FIRST, so a refusal before the run is created",
+        "creates nothing; an executor that fails to start after it leaves the run intact",
+        "and prints the log path and the exact command to start it by hand.",
+        "",
+        "Reconciler liveness is read from the deployment's heartbeat. Against a target",
+        "that is not this machine's plane (production, say), drive-epic never touches a",
+        "local plane: a target with no live reconciler is refused by name.",
         "",
         "One command (BAPI-1054, reordered by BAPI-1102): with --plan-file, drive-epic",
-        "starts the conductor runtime for you when readiness is missing ONLY the",
-        "reconciler/executor facts. It brings up the CONTROL PLANE first (server and",
-        "reconciler), creates and approves the run, then starts executor lanes SCOPED to",
-        "that run, and starts the dead-man observer last — one invocation, no manual",
-        "`plane up` first. A report missing supervisor setup, supervisor configuration,",
-        "GitHub App credentials, or an unattended prerequisite is NOT started: those are",
-        "operator-owned, and drive-epic exits with that one named reason instead.",
+        "starts the conductor runtime for you against the local plane endpoint, when",
+        "readiness is missing ONLY the reconciler. It brings up the CONTROL PLANE first",
+        "(server and reconciler), creates and approves the run, then starts executor lanes",
+        "SCOPED to that run, and starts the dead-man observer last — one invocation, no",
+        "manual `plane up` first. A report missing supervisor setup,",
+        "supervisor configuration, GitHub App credentials, or an unattended prerequisite",
+        "is NOT started: those are operator-owned, and drive-epic exits with that one",
+        "named reason instead.",
         "",
         "The plane port (BAPI-1153): with --plan-file and BAPI_BASE_URL naming the",
         `local plane endpoint (127.0.0.1, port ${PLANE_SERVER_PORT_ENV_VAR} or the default),`,
@@ -307,18 +346,42 @@ export function getDriveEpicUsage() {
         "  - refusal: anything else holds the port (another listener, a manifest for a",
         "    different repository, an unreadable manifest, a plane that cannot take a",
         "    run) — one named reason, and nothing is started.",
-        "One epic per plane: a plane already bound to a different or finished run is",
-        "refused as plane-already-bound. Executor lanes are always scoped to the one",
-        "run with --epic-run-id, on every path.",
+        "One epic per plane — for its LANES: a plane's lanes serve the one run it is",
+        "bound to. A second run attaches to the same plane's reconciler and gets its own",
+        "run-scoped executor instead. A plane whose bound run cannot be read is refused",
+        "as plane-already-bound. Concurrent planes on one database are not supported.",
+        "Executor lanes and run-scoped executors are always scoped to the one run with",
+        "--epic-run-id, on every path.",
+        "",
+        "Finding the plan (BAPI-1285): without --plan-file, drive-epic searches",
+        "{docs_dir}/epic-plans/*/epic-plan.meta.json for a file naming this epic",
+        "({\"epic_key\": \"<KEY>\"}), where docs_dir is BAPI_DOCS_DIR or docs/tmp",
+        "resolved against the Git top level. Exactly one match with a sibling",
+        "epic-plan.dag.json is used as if you had passed --plan-file, and its path is",
+        "printed before anything is created. It never guesses: no match, two or more",
+        "matches, or an unusable meta file stops with the paths it found and creates",
+        "nothing. It never matches by folder name, child ticket key, or manifest. A",
+        "supplied --plan-file always wins, and discovery does not run. The meta file is",
+        "written by `emit-epic-implementer-bundle finalize`; a plan finalized before",
+        "that has none, so pass its DAG with --plan-file.",
+        "",
+        "A live run with no plan: when the epic already has a live run and no plan was",
+        "supplied or found, drive-epic does not create anything. It makes sure that run",
+        "has an executor (reusing a live one, never starting a second) and reports it. A",
+        "durable launch profile starts none and relies on its host's confirmed repo-wide",
+        "executor; a plane already bound to the run needs none. An epic with several active runs, or",
+        "a run that cannot be read, is refused by name.",
         "",
         "Preconditions are validated, never repaired: the current directory must be a Git",
-        "work tree. No worktree is created for you and no replacement port is chosen for",
-        "you — each failure names the fix. Fix it and rerun.",
+        "work tree inside the target repository, because the run's executor starts there.",
+        "No worktree is created for you and no replacement port is chosen for you — each",
+        "failure names the fix. Fix it and rerun.",
         "",
         "Options:",
-        "  --plan-file <path>     Plan DAG sidecar. When supplied and the v2 path is",
-        "                         selected, drive-epic runs that bootstrap directly",
-        "                         instead of printing the command to run.",
+        "  --plan-file <path>     Plan DAG sidecar. Optional: without it, drive-epic finds",
+        "                         the plan by epic key (see above). A supplied path always",
+        "                         wins, and when the v2 path is selected drive-epic runs",
+        "                         the bootstrap directly with it.",
         "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
         "  --feature-branch <name>  Override the derived epic/<KEY> name. Forwarded",
         "                         verbatim, never interpreted here.",
@@ -339,13 +402,27 @@ export function getDriveEpicUsage() {
         "  --launch-profile <name>  Select the host-local launch profile guided setup",
         "                         approved (`install conductor --launch-profile <name>`):",
         "                         target, repository, mode, runtime, and policy and",
-        "                         credential references. The command setup prints",
-        "                         already selects it and runs in a fresh shell.",
+        "                         credential references. Useful for a local or other",
+        "                         non-production server and for durable hosts.",
         "  --base-url <url>       Explicit Bridge API target. With a profile it must",
         "                         agree with it — an override never rebinds a profile.",
-        "Without either, BAPI_BASE_URL is used; with none of the three, drive-epic",
-        "refuses. Nothing defaults to production — select it deliberately. A stored",
-        "credential is sent only to the endpoint setup approved it for.",
+        "Without either, BAPI_BASE_URL is used. With none of the three, drive-epic",
+        `targets production (${CONDUCTOR_DEFAULT_BASE_URL}) and uses the`,
+        "stored bapi:<repo> key when one is available. A stored key approved for a",
+        "different endpoint is never sent; an unapproved key is sent only to",
+        "production.",
+        "",
+        "Preview (BAPI-1285):",
+        "  --dry-run              Read-only launch preview. Resolves the target, reads",
+        "                         readiness and the epic's live run, discovers the plan,",
+        "                         and runs the bootstrap's own dry-run validation. It",
+        "                         reports what a real run WOULD do (create, attach,",
+        "                         refuse, or stop) and never creates a run, cuts a",
+        "                         branch, starts a plane, requests a lane, or starts or",
+        "                         signals an executor. Exit 0 for create or attach, 1 for",
+        "                         refuse or stop.",
+        "  --json                 With --dry-run only: print exactly one JSON document on",
+        "                         stdout and nothing else. Alone, it is a parse error.",
         "",
         "  -h, --help             Show this help",
     ].join("\n");
@@ -390,8 +467,19 @@ export function parseDriveEpicArgs(argv) {
         return trimmed;
     };
     let attended = false;
+    // BAPI-1285 preview flags. Valueless; `--json` is meaningless without `--dry-run`.
+    let dryRun = false;
+    let json = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
         if (arg === "--into-base") {
             intoBase = true;
             continue;
@@ -473,6 +561,15 @@ export function parseDriveEpicArgs(argv) {
         }
         positionals.push(arg);
     }
+    // BAPI-1285 — same style as setup-epic's `--local-only` needs `--dry-run` rule,
+    // refused before any dependency is touched.
+    if (json && !dryRun) {
+        return {
+            status: "error",
+            message: "--json is only valid together with --dry-run. It selects the machine-readable " +
+                "form of the read-only launch preview, and a real launch has no JSON output.",
+        };
+    }
     // BAPI-1009: refused HERE — before access resolution, before the readiness
     // request, and before any delegation — with the same corrective wording
     // setup-epic uses, so the two entry points explain one mistake one way.
@@ -530,6 +627,8 @@ export function parseDriveEpicArgs(argv) {
         ...(replacePolicy ? { replacePolicy: true } : {}),
         ...(launchProfile ? { launchProfile } : {}),
         ...(baseUrl ? { baseUrl } : {}),
+        ...(dryRun ? { dryRun: true } : {}),
+        ...(json ? { json: true } : {}),
     };
     return { status: "ok", options };
 }
@@ -556,7 +655,7 @@ export function parseDriveEpicArgs(argv) {
  * about to be created.
  */
 export function selectConductor(readiness) {
-    const missing = V2_READINESS_REQUIREMENTS.filter((req) => req.unattendedOnly !== true && !req.satisfied(readiness));
+    const missing = V2_READINESS_REQUIREMENTS.filter((req) => req.unattendedOnly !== true && req.advisoryOnly !== true && !req.satisfied(readiness));
     if (missing.length === 0) {
         return {
             kind: "selected",
@@ -598,18 +697,24 @@ export function buildSetupEpicArgv(options) {
         ...(replacePolicy ? ["--replace-policy"] : []),
         // BAPI-1260 — the SAME launch selection, so setup-epic resolves the same
         // target and bound credential drive-epic just did. Appended only when
-        // supplied, so every pre-existing argv stays byte-identical.
+        // supplied, so every pre-existing argv stays byte-identical. A flag-less
+        // (production-default, BAPI-1272) run forwards neither: setup-epic reads
+        // the adopted BAPI_BASE_URL instead.
         ...(launchProfile ? ["--launch-profile", launchProfile] : []),
         ...(baseUrl ? ["--base-url", baseUrl] : []),
     ];
 }
 /**
- * Render the selected v2 path and only that path.
+ * Render the no-plan stop: what discovery found, how to make a plan, and how to
+ * re-run with one.
  *
- * Precondition: the caller has already ruled out delegation and a not-ready
- * result. The `v2` branch reads as "green, but no plan file was supplied", which
- * is only true once {@link runDriveEpicCli} has declined to delegate — so route
- * first, render second.
+ * Precondition: the caller has already ruled out delegation, a not-ready result,
+ * AND a live run. This runs only after plan discovery came back empty or
+ * ambiguous (BAPI-1285), so it never claims "nothing derives a plan from an epic
+ * key" — something does, and it names exactly what it found.
+ *
+ * It offers two ways to re-run and only one of them is a runnable `drive-epic`
+ * command: `/drive-epic-run` is a session slash command, not a second conductor.
  */
 export function renderConductorHandoff(selection, epicKey, 
 /**
@@ -619,7 +724,12 @@ export function renderConductorHandoff(selection, epicKey,
  * shell. The plan file is the one thing that cannot be filled in yet, and it
  * is the only placeholder left.
  */
-launch = { profile: null }) {
+launch = { profile: null }, 
+/**
+ * BAPI-1285 — what discovery found. Absent reads as "no metadata named this
+ * epic", with the searched directory left as its placeholder.
+ */
+discovery) {
     const invocation = launch.profile !== null
         ? renderEpicLaunchCommand(launch.profile, {
             epicKey,
@@ -630,25 +740,49 @@ launch = { profile: null }) {
             ...(launch.options?.featureBranch ? { featureBranch: launch.options.featureBranch } : {}),
         }).replace(`${shellQuote("<path>")}`, "<path>")
         : `npx -y ${MCP_PACKAGE_NAME} drive-epic ${epicKey} --plan-file <path>`;
+    const plansDir = discovery?.epic_plans_dir ?? "{docs_dir}/epic-plans";
+    const outcome = discovery?.status === "plan_ambiguous"
+        ? [
+            `More than one plan names ${epicKey} under ${plansDir}, and drive-epic does not guess`,
+            "between them. Candidates:",
+            ...discovery.candidates.map((candidate) => `  - ${candidate}`),
+        ]
+        : [`No epic-plan.meta.json under ${plansDir} names ${epicKey}.`];
+    const skipped = discovery !== undefined && discovery.skipped.length > 0
+        ? [
+            "",
+            "These metadata files could not be used, so they were not counted:",
+            ...discovery.skipped.map((entry) => `  - ${entry.path} (${entry.reason})`),
+        ]
+        : [];
     return {
         conductor: "v2",
         invocation,
         lines: [
-            `${epicKey}: ${selection.reason}, but no plan file was supplied.`,
+            `${epicKey}: ${selection.reason}, but no plan was supplied and none could be selected.`,
+            "",
+            ...outcome,
+            ...skipped,
+            "",
+            "Discovery reads only epic-plan.meta.json ({\"epic_key\": ...}). It never matches a",
+            "folder name, a child ticket key, or a manifest. A plan finalized before that file",
+            "existed has none; find an older plan's DAG with:",
+            `  ${plansDir}/*/epic-plan.dag.json`,
             "",
-            "The engine path needs a plan DAG, and nothing derives one from an epic key:",
-            "the dependency edges and per-ticket touched_files it carries do not exist",
-            "anywhere else. Produce one, then re-run this command with it.",
+            "The engine path needs a plan DAG: the dependency edges and per-ticket",
+            "touched_files it carries do not exist anywhere else.",
             "",
-            `  1. Run /plan-epic ${epicKey} in an interactive session. It writes the`,
+            `  1. To make one, run /plan-epic ${epicKey} in an interactive session. It writes the`,
             "     sidecar to {docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json.",
             "     If the epic's tickets already exist, run emit-epic-implementer-bundle",
             "     finalize instead — it resolves the placeholder keys in an existing",
-            "     sidecar and attaches touched_files.",
+            "     sidecar, attaches touched_files, and writes epic-plan.meta.json so the",
+            "     plan is found next time.",
             "",
-            `  2. ${invocation}`,
+            `  2. Re-run with the plan, in a session: /drive-epic-run ${epicKey} <plan path>`,
+            `     or from a shell: ${invocation}`,
             "",
-            `That second command bootstraps the run for you; ${SETUP_EPIC_SUBCOMMAND} is not`,
+            `That shell command bootstraps the run for you; ${SETUP_EPIC_SUBCOMMAND} is not`,
             "something you invoke directly.",
         ],
     };
@@ -884,8 +1018,6 @@ export function resolvePlaneReconcilerInstanceId(manifest, env, hostname) {
         memberEnv.DYNO = env.DYNO;
     return resolveMemberInstanceId(memberEnv, worker.pid, hostname);
 }
-/** Terminal `epic_runs.status` values; every other status is a live run. */
-const TERMINAL_EPIC_RUN_STATUSES = ["abandoned", "done"];
 /** The BAPI-1260 launch selection carried by parsed options. */
 function launchSelectionOf(options) {
     return {
@@ -893,11 +1025,80 @@ function launchSelectionOf(options) {
         ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
     };
 }
+/**
+ * BAPI-1285 — resolve the docs directory discovery searches, through two seams.
+ *
+ * `BAPI_DOCS_DIR` is read once. An absolute value is used as given and needs no
+ * Git call. Otherwise the value — or `docs/tmp` — is resolved against the Git top
+ * level. When Git cannot name a top level this REFUSES rather than substituting
+ * `cwd`: silently searching the wrong directory would report "no plan" for a plan
+ * that exists.
+ *
+ * `index.ts` (project root) and the bundle CLI (`cwd`) resolve the same default
+ * slightly differently today; in the normal case all three equal the Git top
+ * level, and neither of those is changed here.
+ */
+export async function resolveDriveEpicDocsDir(seams) {
+    const raw = seams.env.BAPI_DOCS_DIR;
+    const configured = raw !== undefined && raw.trim() !== "" ? raw : undefined;
+    if (configured !== undefined && path.isAbsolute(configured)) {
+        return { ok: true, docsDir: configured };
+    }
+    let top;
+    try {
+        top = await seams.gitTopLevel();
+    }
+    catch {
+        return { ok: false };
+    }
+    if (top === null || top.trim() === "")
+        return { ok: false };
+    return { ok: true, docsDir: path.resolve(top, configured ?? path.join("docs", "tmp")) };
+}
+/** The real filesystem behind plan discovery. */
+function createDefaultPlanDiscoveryFs() {
+    return {
+        readdir: (dirPath) => readdir(dirPath, { withFileTypes: true }),
+        readFile: (filePath) => readFile(filePath, "utf8"),
+    };
+}
+/**
+ * BAPI-1285 — map the by-epic-key run read the way `setup-epic`'s Step 0 does:
+ * 404 is no run, 409 is a wedged epic, and every other failure is unknown.
+ * Nothing but a status and an error kind is ever kept from a failure.
+ */
+export async function readLiveEpicRunByKey(access, epicKey, fetchImpl = globalThis.fetch) {
+    try {
+        const state = await fetchEpicRunState(access, epicKey, fetchImpl);
+        const run = state
+            ?.epic_run;
+        if (typeof run?.epic_run_id !== "string" ||
+            run.epic_run_id === "" ||
+            typeof run.status !== "string") {
+            return { kind: "unknown", reason: "the run state response was malformed" };
+        }
+        return { kind: "live", epicRunId: run.epic_run_id, status: run.status };
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError) {
+            if (err.status === 404)
+                return { kind: "none" };
+            if (err.status === 409)
+                return { kind: "conflict" };
+            return {
+                kind: "unknown",
+                reason: `kind=${err.kind}${typeof err.status === "number" ? ` status=${err.status}` : ""}`,
+            };
+        }
+        return { kind: "unknown", reason: "the run state read failed unexpectedly" };
+    }
+}
 export function createDefaultDriveEpicDeps() {
     return {
         resolveAccess: async (repo, cwd, launch) => {
-            // BAPI-1260: the target-first launch contract. The generic resolver's
-            // production default does not apply to an epic launch.
+            // BAPI-1260: the target-first launch contract. BAPI-1272: with no target
+            // selected it defaults to production, and a stored key is sent there only
+            // when it is unbound or bound to production — never one bound elsewhere.
             const result = await resolveEpicLaunchBridgeApiAccess(launch ?? {}, {
                 ...(repo ? { repoName: repo } : {}),
                 ...(cwd ? { cwd } : {}),
@@ -955,6 +1156,39 @@ export function createDefaultDriveEpicDeps() {
             return observation.result.kind === "state" ? observation.result.state : observation.result.kind;
         },
         readPlaneManifest: (repoRoot) => readPlaneManifest(repoRoot, createPlaneFsDeps()),
+        resolveDocsDir: () => resolveDriveEpicDocsDir({
+            env: process.env,
+            gitTopLevel: async () => {
+                const top = await createDefaultRunExecutorLaunchDeps().execFile("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() });
+                return top.ok ? top.stdout.trim() : null;
+            },
+        }),
+        discoveryFs: createDefaultPlanDiscoveryFs(),
+        readPlanDag: (filePath) => readFile(filePath, "utf8"),
+        readPolicyFile: (filePath) => readFile(filePath, "utf8"),
+        readLiveEpicRun: (access, epicKey) => readLiveEpicRunByKey(access, epicKey),
+        previewSetupEpic: async ({ argv, baseUrl }) => {
+            const stdout = [];
+            const stderr = [];
+            const result = await runSetupEpicWorkflow(argv, {
+                // A COPY carrying the resolved target: the preview never mutates
+                // `process.env`, so a dry run leaves the process exactly as it found it.
+                env: { ...process.env, BAPI_BASE_URL: baseUrl },
+                log: (message) => stdout.push(message),
+                errorLog: (message) => stderr.push(message),
+            });
+            return { exitCode: result.exitCode, stdout, stderr };
+        },
+        // Read-only by construction: `prepareRunExecutor` runs `git rev-parse` and
+        // locates the package entrypoint, and starts nothing. It is reached through
+        // its module function here, never through the `prepareRunExecutor` dep the
+        // preview must not call.
+        inspectRunExecutorPrecondition: async (cwd) => {
+            const result = await prepareRunExecutorDefault(cwd, createDefaultRunExecutorLaunchDeps());
+            return result.ok ? { ok: true } : { ok: false, message: result.message };
+        },
+        prepareRunExecutor: (cwd) => prepareRunExecutorDefault(cwd, createDefaultRunExecutorLaunchDeps()),
+        ensureRunExecutor: (args) => ensureRunExecutorDefault(args, createDefaultRunExecutorLaunchDeps()),
         // stdout is safe here: `drive-epic` is dispatched BEFORE MCP server
         // construction, so nothing has claimed stdout for the protocol transport.
         log: (message) => console.log(message),
@@ -982,18 +1216,73 @@ export async function runDriveEpicCli(argv, overrides = {}) {
     }
     const { epicKey, planFile, repo, featureBranch, intoBase } = parsed.options;
     const launch = launchSelectionOf(parsed.options);
+    // BAPI-1285 — the read-only preview is its own path from here. It shares the
+    // classification and refusal builders below and none of the launch code.
+    if (parsed.options.dryRun === true) {
+        return await runDriveEpicPreview(deps, parsed.options);
+    }
     try {
+        // Every async branch below is `return await`ed. A bare `return promise`
+        // inside this `try` would let a rejection skip the sanitizing `catch` at the
+        // bottom and escape with its raw message (BAPI-1279).
         // --- Resolve access. A missing credential is UNKNOWN, not not-ready. -----
         // BAPI-1260: the TARGET is decided first — from --launch-profile,
-        // --base-url, and BAPI_BASE_URL — and only then is a credential bound to
-        // that target read. A missing or conflicting target refuses here, before
-        // any authenticated request; nothing defaults to production.
+        // --base-url, and BAPI_BASE_URL, else production (BAPI-1272) — and only
+        // then is a credential bound to that target read. A conflicting target or
+        // an unusable credential refuses here, before any authenticated request;
+        // there is no fallback to another endpoint. The adopted target becomes the
+        // child processes' BAPI_BASE_URL.
         const accessResult = await deps.resolveAccess(repo, undefined, launch);
         if (!accessResult.ok) {
             return escalate(deps, epicKey, `conductor readiness could not be read: ${accessResult.error}`);
         }
         const launchProfile = accessResult.profile ?? null;
         deps.adoptLaunchTarget?.(accessResult.access.baseUrl);
+        // BAPI-1279 — decided ONCE, right here. A target that is not this machine's
+        // plane endpoint never reaches a local-plane operation: no preflight, no
+        // launch, no lane request, no manifest read, no port probe. Every branch
+        // below reads this one value rather than re-deriving it.
+        const planeTarget = planeEndpointForBaseUrl(deps, accessResult.access.baseUrl) !== null;
+        // `let`: a plan found by epic key (BAPI-1285) is folded into the options, after
+        // which it is indistinguishable from a supplied `--plan-file`.
+        let ctx = {
+            deps,
+            epicKey,
+            options: parsed.options,
+            access: accessResult.access,
+            profile: launchProfile,
+        };
+        // BAPI-1285 — with no `--plan-file`, look for the plan BEFORE readiness. A
+        // discovered plan must count as a supplied one for the BAPI-1153 cold-start
+        // case below (a local plane that is not running yet is the commonest first
+        // launch), and discovery is local, read-only, and free. What it may NOT do is
+        // decide anything before readiness: an unresolvable docs root is only
+        // remembered here and refused after readiness, so unknown readiness still
+        // escalates exactly as before, and the live-run read stays after readiness.
+        let discovered = null;
+        let docsRootUnresolved = false;
+        if (planFile === undefined) {
+            const docs = await deps.resolveDocsDir();
+            if (docs.ok) {
+                discovered = await discoverEpicPlan(epicKey, docs.docsDir, deps.discoveryFs);
+                if (discovered.status === "found") {
+                    ctx = { ...ctx, options: { ...ctx.options, planFile: discovered.path } };
+                }
+            }
+            else {
+                docsRootUnresolved = true;
+            }
+        }
+        let foundPlanAnnounced = false;
+        /** Names the found plan once, BEFORE anything is created, and surfaces its advisory. */
+        const announceFoundPlan = async (surfaceAdvisory = true) => {
+            if (foundPlanAnnounced || discovered?.status !== "found")
+                return;
+            foundPlanAnnounced = true;
+            deps.log(`${epicKey}: using the plan found by epic key: ${discovered.path}`);
+            if (surfaceAdvisory)
+                await surfaceContainmentAdvisory(deps, discovered.path);
+        };
         // --- Read readiness. Any failure here is UNKNOWN — with ONE exception. ---
         let readiness;
         try {
@@ -1006,7 +1295,10 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             // Everything else — a non-plane base URL, an HTTP or auth or shape error, a
             // timeout, any other probe result — keeps today's escalation byte for byte,
             // because there unknown is still fatal (R14).
-            if (planFile !== undefined && err instanceof ConductorBridgeApiError && err.kind === "network") {
+            if (ctx.options.planFile !== undefined &&
+                planeTarget &&
+                err instanceof ConductorBridgeApiError &&
+                err.kind === "network") {
                 const endpoint = planeEndpointForBaseUrl(deps, accessResult.access.baseUrl);
                 // BAPI-1260 — only a SELECTED LOCAL plane is ever started here. A
                 // profile approved for durable execution names an authority this
@@ -1019,12 +1311,9 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                 if (endpoint !== null) {
                     const probe = await deps.probePlanePort(endpoint.host, endpoint.port);
                     if (probe.kind === "refused") {
-                        return coldStartPlane({
-                            deps,
-                            epicKey,
-                            options: parsed.options,
-                            access: accessResult.access,
-                        });
+                        // `coldStartPlane` surfaces the containment advisory itself.
+                        await announceFoundPlan(false);
+                        return await coldStartPlane(ctx);
                     }
                 }
             }
@@ -1040,6 +1329,36 @@ export async function runDriveEpicCli(argv, overrides = {}) {
         // delegated argv, or the exit code.
         if (planFile)
             await surfaceContainmentAdvisory(deps, planFile);
+        // BAPI-1285 — no `--plan-file`: find the plan from the epic key, and read the
+        // epic's live run. Readiness has already been resolved (unknown escalated
+        // above), so nothing here can be a discovery-driven create on unknown.
+        //
+        // A supplied plan always wins and skips ALL of this, including the extra
+        // live-run read: setup-epic does its own Step 0 read and owns reuse.
+        let discoveryStop;
+        if (planFile === undefined) {
+            if (docsRootUnresolved || discovered === null) {
+                return refuse(deps, docsRootRefusal(epicKey).lines);
+            }
+            const live = await deps.readLiveEpicRun(accessResult.access, epicKey);
+            // Wedged or unreadable: never a create and never an attach, whatever
+            // discovery found. Guessing here is how a duplicate run gets minted.
+            if (live.kind === "conflict")
+                return refuse(deps, liveRunAmbiguousRefusal(epicKey).lines);
+            if (live.kind === "unknown")
+                return refuse(deps, liveRunUnknownRefusal(epicKey, live.reason).lines);
+            if (discovered.status === "found") {
+                // The plan was folded into `ctx.options` before readiness; from here it is
+                // indistinguishable from a supplied `--plan-file`.
+                await announceFoundPlan();
+            }
+            else if (live.kind === "live") {
+                return await attachToLiveRun(ctx, readiness, live);
+            }
+            else {
+                discoveryStop = discovered;
+            }
+        }
         // Decide delegation BEFORE rendering. The v2 branch's text is specifically
         // about a missing plan file, and rendering it on the path that has one
         // would produce a message contradicting what is about to happen.
@@ -1049,7 +1368,7 @@ export async function runDriveEpicCli(argv, overrides = {}) {
         // not-ready result can be rendered, because a report that is non-green only on
         // the runtime facts is not a "v2 cannot run" situation — it is a plane that
         // has not been started yet.
-        if (planFile) {
+        if (ctx.options.planFile !== undefined) {
             // BAPI-1102 — the explicit `--attended` opt-out makes the unattended
             // prerequisites inapplicable. Both inputs are FLAG checks, not policy
             // reads: whatever a `--policy-file` says stays opaque here, exactly as it
@@ -1060,12 +1379,24 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                 intoBase: parsed.options.intoBase === true,
                 hasPolicyFile: parsed.options.policyFile !== undefined,
             });
-            const setupArgv = buildSetupEpicArgv(parsed.options);
-            // Green: delegate exactly as before. No plane invocation, no preflight,
-            // and byte-identical argv for the no-flag case. Only the structured
-            // result's exit code is returned, so the public contract is unchanged.
+            // Green: create the run, then make sure something will claim its jobs
+            // (BAPI-1279). Before this, green delegated to setup-epic and nothing
+            // else, so a production launch — or any second run — created a run no
+            // executor would ever claim. setup-epic's argv is unchanged.
             if (classification.kind === "green") {
-                return (await deps.runSetupEpic(setupArgv)).exitCode;
+                if (!planeTarget) {
+                    return await createRunWithRunExecutor(ctx, readiness);
+                }
+                // A plane target: attach to THIS checkout's plane when it is the one
+                // listening (its lanes, or a dedicated executor for a second run).
+                // Otherwise — no plane here, or one owned by a sibling worktree — the
+                // run gets a run-scoped executor. The preflight runs only when a
+                // manifest says there is a plane in this checkout to attach to.
+                const attachable = await findAttachablePlane(ctx);
+                if (attachable !== null) {
+                    return await attachToPlane(ctx, attachable, readiness);
+                }
+                return await createRunWithRunExecutor(ctx, readiness);
             }
             // Operator-blocked: ONE named reason, and nothing is started. `plane up`
             // cannot create stored supervisor state or resolve GitHub App credentials,
@@ -1079,8 +1410,7 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                     // The requirement's OWN remedy when it has one. Telling an operator to
                     // run `install-bridge conductor` for a missing consent flag sends them
                     // to a command that cannot set it.
-                    classification.remedy ??
-                        "Resolve it with `install-bridge conductor`, then run drive-epic again.",
+                    operatorBlockedRemedy(classification),
                 ].join("\n");
                 // Named as a fixed reason and nothing else: no conductor is offered here,
                 // because handing an operator a second authority is the hazard this
@@ -1089,6 +1419,13 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                 deps.errorLog(refusal);
                 return 1;
             }
+            // BAPI-1279 — runtime-only against a target that is NOT this machine's
+            // plane: starting anything here could not help, because the missing
+            // reconciler belongs to that deployment. One named reason, and nothing
+            // local is touched.
+            if (!planeTarget) {
+                return refuseRemoteRuntime(ctx, readiness);
+            }
             // Runtime-only: this invocation composes bring-up with run creation.
             const repoRoot = deps.cwd();
             const preflight = await deps.runPlanePreflight(repoRoot);
@@ -1099,8 +1436,7 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             // preflight made from its single manifest read; nothing is re-read here.
             const existingPlane = preflight.observations?.existingPlane;
             const attachManifest = existingPlane?.kind === "attachable" &&
-                preflight.observations?.serverPort === "connected" &&
-                planeEndpointForBaseUrl(deps, accessResult.access.baseUrl) !== null
+                preflight.observations?.serverPort === "connected"
                 ? existingPlane.manifest
                 : null;
             // Composition preconditions FIRST, and only these two. Preflight is
@@ -1128,7 +1464,7 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                 return 1;
             }
             if (attachManifest !== null) {
-                return attachToPlane({ deps, epicKey, options: parsed.options, access: accessResult.access }, attachManifest, readiness);
+                return await attachToPlane(ctx, attachManifest, readiness);
             }
             // ---- PHASE ONE: the control plane, and NOTHING that claims jobs --------
             //
@@ -1149,23 +1485,21 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             const controlPlane = await deps.launchControlPlane({ preflight, executors: 1 });
             if (!controlPlane.ok) {
                 // The launch already reported why, in its own words, and it rolls its own
-                // startup back. Nothing to add, and no run was created here.
-                for (const line of controlPlane.lines)
-                    deps.errorLog(line);
-                return 1;
+                // startup back. No run was created here.
+                return reportControlPlaneLaunchFailure(ctx, controlPlane);
             }
             // Held so the launcher's lifetime promise is never unobserved. It settles
             // when the PLANE comes down, which is long after this command returns —
             // the detached runtime is its own process-group leader and outlives us by
             // design, which is what "the plane is left running" means.
             void controlPlane.lifetime.catch(() => undefined);
-            // Readiness is NOT re-read as a gate here, and that has not changed:
-            // `reconciler_live` / `executor_live` derive from `epic_runs.last_tick_at`
-            // and `executor_jobs` rows — tables that are EMPTY on a repository that has
-            // never run an epic — so gating on a re-read would hang the one-command
-            // flow permanently on exactly the first-time-operator case it exists to
-            // serve. A successful bring-up IS the runtime fact.
-            return createRunAndRequestLanes({ deps, epicKey, options: parsed.options, access: accessResult.access }, {
+            // Readiness is NOT re-read as a gate here. A successful bring-up IS the
+            // runtime fact: the launch already waited for this plane's own reconciler
+            // heartbeat. (`reconciler_live` now reads the deployment heartbeat, but the
+            // server's repository-progress diagnostics — `epic_runs.last_tick_at`,
+            // `executor_jobs` — stay empty on a first run, and nothing here waits on
+            // them.)
+            return await createRunAndRequestLanes(ctx, {
                 origin: "launched",
                 repoRoot,
                 planeId: controlPlane.planeId,
@@ -1187,14 +1521,13 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             deps.errorLog(refusal);
             return 1;
         }
-        const handoff = renderConductorHandoff(selection, epicKey, {
-            profile: launchProfile,
-            options: parsed.options,
-        });
+        // BAPI-1285 — reached only after discovery came back empty or ambiguous and no
+        // live run exists. Nothing was created, so this is a stop, not a success.
+        const handoff = renderConductorHandoff(selection, epicKey, { profile: launchProfile, options: parsed.options }, discoveryStop);
         const text = handoff.lines.join("\n");
         assertSingleConductorInvocation(text);
-        deps.log(text);
-        return 0;
+        deps.errorLog(text);
+        return 1;
     }
     catch (err) {
         // Last resort. Sanitized, on stderr, converted to an exit code — a
@@ -1226,6 +1559,23 @@ async function surfaceContainmentAdvisory(deps, planFile) {
         // Fail open — a containment advisory is never allowed to block dispatch.
     }
 }
+/**
+ * BAPI-1285 — the one remedy sentence an unknown-readiness escalation ends with.
+ * A constant so the preview's `readiness.remedy` is the very line the real
+ * refusal prints, not a second copy that can drift.
+ */
+const ESCALATE_REMEDY = "Restore Bridge API access and run drive-epic again, or ask an operator to resolve conductor readiness.";
+/** The reason id the preview reports for an unknown readiness read. */
+const READINESS_UNKNOWN_REASON_ID = "readiness-unknown";
+/**
+ * The remedy an operator-blocked refusal names: the requirement's own, else the
+ * general install remedy. One function so the refusal, the cold-start refusal, and
+ * the preview cannot disagree.
+ */
+function operatorBlockedRemedy(classification) {
+    return (classification.remedy ??
+        "Resolve it with `install-bridge conductor`, then run drive-epic again.");
+}
 /**
  * The escalation branch. Prints NO conductor invocation at all — naming a
  * fallback here is the dual-authority hazard, and an operator who does not know
@@ -1236,8 +1586,8 @@ function escalate(deps, epicKey, reason) {
         `Cannot determine which conductor owns ${epicKey}: ${reason}`,
         "",
         "This is not a not-ready result — it is an unknown one, and starting the wrong",
-        "conductor on an epic wedges it permanently. Restore Bridge API access and run",
-        "drive-epic again, or ask an operator to resolve conductor readiness.",
+        "conductor on an epic wedges it permanently.",
+        ESCALATE_REMEDY,
     ];
     const text = lines.join("\n");
     assertSingleConductorInvocation(text);
@@ -1339,9 +1689,7 @@ async function coldStartPlane(ctx) {
     }
     const controlPlane = await deps.launchControlPlane({ preflight, executors: 1 });
     if (!controlPlane.ok) {
-        for (const line of controlPlane.lines)
-            deps.errorLog(line);
-        return 1;
+        return reportControlPlaneLaunchFailure(ctx, controlPlane);
     }
     void controlPlane.lifetime.catch(() => undefined);
     // Read ONCE, for route selection only — the pre-launch read had no server to
@@ -1366,8 +1714,7 @@ async function coldStartPlane(ctx) {
     if (classification.kind === "operator_blocked") {
         return refuse(deps, [
             `${epicKey}: the engine path still needs ${classification.describe} (${classification.id}).`,
-            classification.remedy ??
-                "Resolve it with `install-bridge conductor`, then run drive-epic again.",
+            operatorBlockedRemedy(classification),
             ...LAUNCHED_PLANE_LEFT_RUNNING,
         ]);
     }
@@ -1409,7 +1756,10 @@ async function attachToPlane(ctx, manifest, readiness) {
         ]);
     }
     const attachCtx = { ...ctx, access: rooted.access };
-    // R-7, decided BEFORE any create request.
+    // R-7, decided BEFORE any create request. It binds the LANES only
+    // (BAPI-1279): a plane whose lanes serve another run still has a reconciler
+    // that can drive this one, and gets a dedicated executor for it.
+    let dedicatedExecutorReason = null;
     if (manifest.epicRunId !== undefined) {
         let bound = null;
         try {
@@ -1418,28 +1768,33 @@ async function attachToPlane(ctx, manifest, readiness) {
         catch {
             bound = null;
         }
-        const why = bound === null
-            ? "its bound run could not be read"
-            : TERMINAL_EPIC_RUN_STATUSES.includes(bound.status)
-                ? `its bound run is ${bound.status}`
-                : bound.epicKey !== epicKey
-                    ? `its bound run belongs to ${bound.epicKey}`
-                    : null;
-        if (why !== null) {
+        if (bound === null) {
             return refuse(deps, [
                 `${epicKey}: REFUSED (plane-already-bound) — this repository's plane is bound to run ` +
-                    `${manifest.epicRunId}, and ${why}.`,
-                "A plane serves exactly one epic run (one epic per plane). Finish or stop that run, wind the",
-                "plane down with `plane down`, and run drive-epic again.",
+                    `${manifest.epicRunId}, and its bound run could not be read, so it is unknown whether ` +
+                    "the plane is healthy.",
+                "Restore Bridge API access, or inspect `plane status` and that run's own status, then run",
+                "drive-epic again.",
                 "",
                 "Nothing was started.",
             ]);
         }
+        if (isTerminalEpicRunStatus(bound.status)) {
+            dedicatedExecutorReason = `its lanes' run ${manifest.epicRunId} is ${bound.status}`;
+        }
+        else if (bound.epicKey !== epicKey) {
+            dedicatedExecutorReason = `its lanes serve run ${manifest.epicRunId} of ${bound.epicKey}`;
+        }
     }
     const admission = await checkPlaneAdmission(attachCtx, readiness, manifest);
     if (admission !== null) {
         return refuse(deps, [...admission, "", "Nothing was started."]);
     }
+    if (dedicatedExecutorReason !== null) {
+        deps.log(`${epicKey}: attaching to this repository's running plane (${dedicatedExecutorReason}); ` +
+            "its reconciler will drive this run too, and a dedicated executor will be started for it.");
+        return createRunWithRunExecutor(attachCtx, readiness);
+    }
     deps.log(`${epicKey}: attaching to this repository's running plane — no second server or reconciler will start.`);
     return createRunAndRequestLanes(attachCtx, {
         origin: "attached",
@@ -1523,7 +1878,8 @@ async function createRunAndRequestLanes(ctx, plane) {
             `${epicKey}: the run was created and approved, but executor lanes could not be`,
             `requested from the live plane (${laneRequest.reason}): ${laneRequest.message}.`,
             laneRequest.reason === "run-conflict"
-                ? "A composed plane serves exactly ONE run. Start a second plane for a second epic."
+                ? "This plane's lanes already serve another run. Run drive-epic again: it will attach " +
+                    "to this plane's reconciler and start a dedicated run-scoped executor for this run."
                 : "Inspect it with `plane status`, and wind it down with `plane down`.",
             "The run itself is untouched and still committed server-side.",
         ].join("\n"));
@@ -1576,3 +1932,742 @@ async function createRunAndRequestLanes(ctx, plane) {
     ].join("\n"));
     return 0;
 }
+// ---------------------------------------------------------------------------
+// BAPI-1279 — every launch ensures an executor; remote targets touch no plane
+// ---------------------------------------------------------------------------
+/**
+ * The refusals BAPI-1279 adds. Like {@link DRIVE_EPIC_PLANE_REFUSALS}, these
+ * exist nowhere else; the bring-up facts keep refusing under their own names.
+ */
+export const DRIVE_EPIC_LAUNCH_REFUSALS = [
+    /** A remote target reports no live reconciler and no bring-up fact says why. */
+    "remote-reconciler-not-live",
+    /** A durable launch profile, but no fresh repo-wide executor is confirmed. */
+    "durable-executor-not-live",
+    /** The run-scoped executor could never be started from this checkout. */
+    "executor-precondition",
+];
+/** Said on every remote refusal, because operators expect a local fallback. */
+const REMOTE_NO_PLANE_LINE = "No local plane was started, because the target is not this machine's plane.";
+/**
+ * `worker-not-present` against a remote target. The shared remediation offers
+ * "bring up a local plane", which cannot help a deployment on another machine
+ * and would contradict {@link REMOTE_NO_PLANE_LINE}.
+ */
+function remoteWorkerNotPresentMessage(baseUrl) {
+    return (`the Bridge API at ${baseUrl} reports no worker running its reconciler, so nothing would ` +
+        "drive this run. Start that deployment's worker process — exactly one (for example one " +
+        "Heroku `worker` dyno) — then run drive-epic again.");
+}
+/**
+ * Is THIS checkout's plane the one listening on the plane endpoint, and able to
+ * take a run? Returns its manifest, or `null`.
+ *
+ * Reads the manifest first and runs the plane preflight only when there is one:
+ * with no manifest here there is nothing to attach to, and a green plane target
+ * served by a sibling worktree's plane needs no preflight at all.
+ */
+async function findAttachablePlane(ctx) {
+    const repoRoot = ctx.deps.cwd();
+    const manifestRead = await ctx.deps.readPlaneManifest(repoRoot);
+    if (manifestRead.kind !== "valid")
+        return null;
+    const preflight = await ctx.deps.runPlanePreflight(repoRoot);
+    const existingPlane = preflight.observations?.existingPlane;
+    return existingPlane?.kind === "attachable" && preflight.observations?.serverPort === "connected"
+        ? existingPlane.manifest
+        : null;
+}
+/**
+ * Runtime-only readiness against a target that is NOT this machine's plane.
+ *
+ * The missing reconciler belongs to that deployment, so nothing started here
+ * could help. One named reason: the first bring-up refusal, whose message
+ * already names its remedy, else `remote-reconciler-not-live`. No run is
+ * created and nothing local is touched.
+ */
+function refuseRemoteRuntime(ctx, readiness) {
+    return refuse(ctx.deps, remoteRuntimeRefusal(ctx.epicKey, ctx.access, readiness).lines);
+}
+/** The runtime-only refusal for a target that is not this machine's plane. */
+function remoteRuntimeRefusal(epicKey, access, readiness) {
+    const bringUp = readiness.bring_up ?? null;
+    const reason = firstBringUpRefusal(bringUp);
+    const reasonId = reason ?? "remote-reconciler-not-live";
+    const remedy = reason !== null
+        ? reason === "worker-not-present"
+            ? remoteWorkerNotPresentMessage(access.baseUrl)
+            : BRING_UP_REFUSAL_MESSAGES[reason]
+        : `the Bridge API at ${access.baseUrl} reports no live reconciler, so nothing would drive ` +
+            "this run. Check that its worker process is running, then run drive-epic again.";
+    const lines = [`${epicKey}: REFUSED (${reasonId}) — ${remedy}`];
+    if (bringUp === null) {
+        lines.push("This Bridge API version cannot report deployment liveness, so a launch against it cannot " +
+            "be confirmed. Upgrade the Bridge API deploy.");
+    }
+    lines.push("", "No run was created.", REMOTE_NO_PLANE_LINE);
+    return { reasonId, remedy, lines };
+}
+/**
+ * BAPI-1285 — a durable launch profile with no confirmed fresh repo-wide
+ * executor. `created` says what state the refusal leaves: before a create nothing
+ * exists; on a live-run attach the run is simply untouched.
+ */
+function durableCoverageRefusal(epicKey, access, profile, coverage, outcome) {
+    const remedy = [
+        "Start the durable host's executor with --repo-wide",
+        "  (`install conductor --execution-mode durable --executor-id <id> --repo-wide`),",
+        "or launch without the durable profile.",
+    ].join("\n");
+    return {
+        reasonId: "durable-executor-not-live",
+        remedy,
+        lines: [
+            `${epicKey}: REFUSED (durable-executor-not-live) — launch profile '${profile.name}' selects ` +
+                `durable execution, but a fresh repo-wide executor for ${access.repoName} could not be ` +
+                "confirmed" +
+                (coverage === undefined
+                    ? " (this Bridge API version does not report executor coverage)."
+                    : "."),
+            remedy,
+            "",
+            `${outcome}, and no local executor was started.`,
+        ],
+    };
+}
+/** The pre-create refusal when no executor could ever be started from this checkout. */
+function executorPreconditionRefusal(epicKey, message, outcome) {
+    return {
+        reasonId: "executor-precondition",
+        remedy: message,
+        lines: [`${epicKey}: REFUSED (executor-precondition) — ${message}`, "", outcome],
+    };
+}
+/** BAPI-1285 — `--plan-file` absent, and the checkout cannot say where plans live. */
+function docsRootRefusal(epicKey) {
+    const remedy = "Run drive-epic from inside the target repository's Git checkout, set BAPI_DOCS_DIR to an " +
+        "absolute path, or pass --plan-file.";
+    return {
+        reasonId: "docs-root-unresolvable",
+        remedy,
+        lines: [
+            `${epicKey}: REFUSED (docs-root-unresolvable) — this directory is not inside a Git work tree ` +
+                "and BAPI_DOCS_DIR is not an absolute path, so the directory holding epic plans could not " +
+                "be located.",
+            remedy,
+            "",
+            "Nothing was created and nothing was started.",
+        ],
+    };
+}
+/** BAPI-1285 — several active runs for one epic: it is wedged. */
+function liveRunAmbiguousRefusal(epicKey) {
+    const remedy = "Abandon the duplicate run with `epic-implementer abandon-run --epic-run-id " +
+        "<duplicate_epic_run_id>`, then run drive-epic again.";
+    return {
+        reasonId: "live-run-ambiguous",
+        remedy,
+        lines: [
+            `${epicKey}: REFUSED (live-run-ambiguous) — this epic has more than one active run, so it is ` +
+                "wedged and drive-epic cannot tell which run to drive.",
+            remedy,
+            "",
+            "Nothing was created and nothing was started.",
+        ],
+    };
+}
+/** BAPI-1285 — the epic's run state could not be read, so nothing may be assumed. */
+function liveRunUnknownRefusal(epicKey, reason) {
+    const remedy = "Restore Bridge API access, then run drive-epic again. Creating a run without knowing " +
+        "whether one exists could mint a duplicate, which wedges the epic permanently.";
+    return {
+        reasonId: "live-run-unknown",
+        remedy,
+        lines: [
+            `${epicKey}: REFUSED (live-run-unknown) — the epic's run state could not be read (${reason}).`,
+            remedy,
+            "",
+            "Nothing was created and nothing was started.",
+        ],
+    };
+}
+/**
+ * Create the run, then make sure an executor will claim its jobs — the path for
+ * every launch that does not request a plane lane.
+ *
+ *   - Durable launch profile: confirm a fresh REPO-WIDE executor covers the
+ *     repository BEFORE creating anything, and start nothing locally.
+ *   - Otherwise: resolve the checkout and build BEFORE creating anything, then
+ *     create the run, then start (or reuse) a run-scoped executor for it.
+ *
+ * The order is the whole design: every refusal that can happen before a run
+ * exists does, so a refusal never leaves a run behind. After the run exists,
+ * nothing here stops or retries it.
+ */
+async function createRunWithRunExecutor(ctx, readiness) {
+    const { deps, epicKey, access, profile } = ctx;
+    if (profile !== null && profile.executionMode === "durable") {
+        const coverage = readiness.executor.repo_wide_executor_live;
+        if (coverage !== true) {
+            return refuse(deps, durableCoverageRefusal(epicKey, access, profile, coverage, "No run was created").lines);
+        }
+        const setup = await deps.runSetupEpic(buildSetupEpicArgv(ctx.options));
+        if (setup.exitCode === 0) {
+            deps.log([
+                "",
+                `${epicKey}: run ${setup.epicRunId ?? "(id not reported)"} created on ${access.baseUrl}.`,
+                "The durable host's repo-wide executor claims its jobs; no local executor was started.",
+            ].join("\n"));
+        }
+        return setup.exitCode;
+    }
+    // PRE-CREATE: a launch that could never start an executor refuses here.
+    const prepared = await deps.prepareRunExecutor(deps.cwd());
+    if (!prepared.ok) {
+        return refuse(deps, executorPreconditionRefusal(epicKey, prepared.message, "No run was created.").lines);
+    }
+    const setup = await deps.runSetupEpic(buildSetupEpicArgv(ctx.options));
+    if (setup.exitCode !== 0) {
+        // setup-epic already said why. Nothing was started for a run that may not exist.
+        deps.errorLog(`\n${epicKey}: no executor was started.`);
+        return setup.exitCode;
+    }
+    if (setup.epicRunId === undefined) {
+        // Exit zero with no run id: there is no authoritative identity to scope an
+        // executor to, and guessing could attach it to a DIFFERENT run.
+        return refuse(deps, [
+            "",
+            `${epicKey}: setup reported success but returned no epic run id, so no executor could be`,
+            "attached to the run. NO EXECUTOR WAS STARTED. Inspect this repository's epic runs",
+            "server-side before retrying; retrying blindly could create a second run.",
+        ]);
+    }
+    // POST-CREATE: start or reuse exactly one executor scoped to this run.
+    const ensured = await deps.ensureRunExecutor({
+        prepared: prepared.prepared,
+        repoName: access.repoName,
+        epicRunId: setup.epicRunId,
+        access,
+        profile,
+    });
+    return reportExecutorOutcome(ctx, ensured, setup.epicRunId, "created");
+}
+/**
+ * Print an executor outcome — started, reused, or failed — and return the exit
+ * code. Shared by the create path and the live-run attach path (BAPI-1285) so the
+ * two print identical text rather than two copies that drift. Only the framing
+ * differs: whether the run was just CREATED or was already live.
+ *
+ * The readiness, durable, and plane gates stay with the callers; this is only the
+ * report. A failure never stops or changes the run.
+ */
+function reportExecutorOutcome(ctx, ensured, epicRunId, framing) {
+    const { deps, epicKey, access } = ctx;
+    if (!ensured.ok) {
+        return refuse(deps, [
+            "",
+            framing === "created"
+                ? `${epicKey}: Run created but executor unavailable — run ${epicRunId} on ${access.baseUrl}.`
+                : `${epicKey}: Run ${epicRunId} executor unavailable — the run is already live on ${access.baseUrl}.`,
+            `No executor heartbeat was confirmed (${ensured.reason}): ${ensured.message}.`,
+            `  Log: ${ensured.logPath}`,
+            ...(ensured.executorMayBeRunning
+                ? [
+                    "An executor for this run may still be running, so do not start a second one beside",
+                    "it. Check the log and the process first; only once none is running, start it by hand",
+                    "from this checkout:",
+                ]
+                : ["Start it by hand from this checkout:"]),
+            `  ${ensured.manualCommand}`,
+            "The run was NOT stopped. It stays server-side and recoverable, and resumes as soon as an",
+            "executor claims its jobs.",
+        ]);
+    }
+    const started = ensured.outcome === "started"
+        ? `A run-scoped executor was started for it in the background (pid ${ensured.pid}).`
+        : `A run-scoped executor for it was already running (pid ${ensured.pid}); no second one was started.`;
+    deps.log([
+        "",
+        framing === "created"
+            ? `${epicKey}: run ${epicRunId} is created on ${access.baseUrl}.`
+            : `${epicKey}: run ${epicRunId} is already live on ${access.baseUrl}; nothing was created.`,
+        started,
+        "It claims only this run's jobs, and exits on its own once the run is done or abandoned.",
+        `  Log:    ${ensured.logPath}`,
+        `  Record: ${ensured.recordPath}`,
+        "It runs on THIS machine: sleep is held off while it runs, but a closed lid, a logout, or a",
+        "shutdown stops it. The run stays server-side either way; restart the executor, or use a",
+        "durable launch profile for long runs.",
+    ].join("\n"));
+    return 0;
+}
+/**
+ * Is this checkout's plane serving the live run? True only when BOTH binding
+ * facts agree: the plane manifest's `epicRunId` equals the live run's id, and the
+ * bound run reads back live and of this epic. Anything unreadable or mismatched is
+ * false, and the caller takes the ordinary run-scoped executor path — a plane is
+ * never presumed to be covering a run it cannot be shown to cover.
+ */
+async function planeServesLiveRun(ctx, live) {
+    try {
+        const manifest = await findAttachablePlane(ctx);
+        if (manifest === null || manifest.epicRunId !== live.epicRunId)
+            return false;
+        const bound = await ctx.deps.readRunState(ctx.access, manifest.epicRunId);
+        return bound.epicKey === ctx.epicKey && !isTerminalEpicRunStatus(bound.status);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * BAPI-1285 — a live run and no usable plan: make sure the run has an executor.
+ *
+ * It creates nothing and never calls `setup-epic`, which hard-requires a plan
+ * file. Readiness gates it exactly as it gates a create (only green proceeds),
+ * because starting an executor for a run nothing can drive is not attaching to it.
+ *
+ *   - durable profile: confirm a fresh repo-wide executor and start nothing local;
+ *   - this checkout's plane bound to THIS run: its lanes serve it, start nothing;
+ *   - otherwise: prepare, then ensure a run-scoped executor for the LIVE run's id.
+ */
+async function attachToLiveRun(ctx, readiness, live) {
+    const { deps, epicKey, access, profile } = ctx;
+    const classification = classifyV2Readiness(readiness, {
+        attended: ctx.options.attended === true,
+        intoBase: ctx.options.intoBase === true,
+        hasPolicyFile: ctx.options.policyFile !== undefined,
+    });
+    if (classification.kind === "operator_blocked") {
+        return refuse(deps, [
+            `${epicKey}: the engine path still needs ${classification.describe} (${classification.id}).`,
+            "",
+            "This is not something starting the runtime can fix, so nothing was started.",
+            operatorBlockedRemedy(classification),
+        ]);
+    }
+    const planeTarget = planeEndpointForBaseUrl(deps, access.baseUrl) !== null;
+    if (classification.kind === "runtime_only") {
+        if (!planeTarget)
+            return refuseRemoteRuntime(ctx, readiness);
+        return refuse(deps, localReconcilerRefusal(epicKey, readiness).lines);
+    }
+    deps.log(`${epicKey}: run ${live.epicRunId} is already live (${live.status}) and no plan was supplied or ` +
+        "found, so nothing will be created; making sure it has an executor.");
+    if (profile !== null && profile.executionMode === "durable") {
+        const coverage = readiness.executor.repo_wide_executor_live;
+        if (coverage !== true) {
+            return refuse(deps, durableCoverageRefusal(epicKey, access, profile, coverage, "No run was changed").lines);
+        }
+        deps.log([
+            "",
+            `${epicKey}: run ${live.epicRunId} is served by the durable host's confirmed repo-wide executor.`,
+            "No local executor was started.",
+        ].join("\n"));
+        return 0;
+    }
+    if (planeTarget && (await planeServesLiveRun(ctx, live))) {
+        deps.log([
+            "",
+            `${epicKey}: this checkout's plane is bound to run ${live.epicRunId}; its executor lanes serve it.`,
+            "No run-scoped executor was started beside them.",
+        ].join("\n"));
+        return 0;
+    }
+    const prepared = await deps.prepareRunExecutor(deps.cwd());
+    if (!prepared.ok) {
+        return refuse(deps, executorPreconditionRefusal(epicKey, prepared.message, "No run was changed.").lines);
+    }
+    const ensured = await deps.ensureRunExecutor({
+        prepared: prepared.prepared,
+        repoName: access.repoName,
+        epicRunId: live.epicRunId,
+        access,
+        profile,
+    });
+    return reportExecutorOutcome(ctx, ensured, live.epicRunId, "attached");
+}
+/**
+ * BAPI-1285 — a live run, a local plane target, and a reconciler that is not
+ * live. Without a plan drive-epic cannot compose the bring-up (that happens only
+ * while creating a run), so this is one named refusal rather than an executor for
+ * a run nothing is driving.
+ */
+function localReconcilerRefusal(epicKey, readiness) {
+    const reason = firstBringUpRefusal(readiness.bring_up ?? null);
+    const reasonId = reason ?? "local-reconciler-not-live";
+    const remedy = reason !== null
+        ? BRING_UP_REFUSAL_MESSAGES[reason]
+        : "the local conductor plane reports no live reconciler, so nothing would drive this run. " +
+            "Start it with `plane up`, or pass --plan-file so drive-epic can bring the runtime up.";
+    return {
+        reasonId,
+        remedy,
+        lines: [`${epicKey}: REFUSED (${reasonId}) — ${remedy}`, "", "No run was changed."],
+    };
+}
+/**
+ * Render a failed control-plane launch.
+ *
+ * The launch already printed its own reason. The one case this adds to is the
+ * pre-worker guard finding another reconciler live (BAPI-1279): name it as
+ * `second-reconciler-detected` and give the attach remedy. "Nothing was left
+ * running" is said only after a CONFIRMED rollback.
+ */
+function reportControlPlaneLaunchFailure(ctx, controlPlane) {
+    const { deps, epicKey } = ctx;
+    for (const line of controlPlane.lines)
+        deps.errorLog(line);
+    if (controlPlane.foreignReconciler === undefined)
+        return 1;
+    // The live plane is on ANOTHER port — a cold start happens only when this
+    // plane's own port is free — so the port is named by that plane, not here.
+    return refuse(deps, [
+        "",
+        `${epicKey}: REFUSED (second-reconciler-detected) — ` +
+            BRING_UP_REFUSAL_MESSAGES["second-reconciler-detected"],
+        controlPlane.foreignReconciler.rolledBack
+            ? "The server this invocation started was rolled back; nothing was left running."
+            : "The rollback of the server this invocation started could NOT be confirmed. Check " +
+                "`plane status` and stop anything it still lists.",
+        "Concurrent planes on one database are not supported. To run this epic next to the live one,",
+        "point this launch at the plane that owns that reconciler (pass --base-url",
+        "http://127.0.0.1:<port>, with the port that plane's `plane status` reports, and change or",
+        "unset BAPI_BASE_URL if it names a different endpoint). drive-epic will create the run",
+        "against that plane and start a run-scoped executor in this checkout.",
+        "",
+        "No run was created.",
+    ]);
+}
+/** The readiness reason a preview reports for a generic not-ready engine. */
+const ENGINE_NOT_READY_REASON_ID = "engine-not-ready";
+const ENGINE_NOT_READY_REMEDY = "Resolve conductor readiness (`install-bridge conductor`, then `doctor`) and run drive-epic again.";
+/**
+ * Read exactly one well-shaped setup-epic dry-run JSON document out of captured
+ * `log` output. Anything else — none, several, or one with the wrong shape — is
+ * `null`. Human text that is not JSON is ignored, never parsed for meaning.
+ */
+function readSetupPreviewPayload(stdout) {
+    const documents = [];
+    for (const message of stdout) {
+        let value;
+        try {
+            value = JSON.parse(message);
+        }
+        catch {
+            continue;
+        }
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            documents.push(value);
+        }
+    }
+    if (documents.length !== 1)
+        return null;
+    const doc = documents[0];
+    if (doc.dry_run !== true || typeof doc.server_validated !== "boolean")
+        return null;
+    const existing = doc.existing_run_id;
+    if (existing !== null && existing !== undefined && typeof existing !== "string")
+        return null;
+    const branch = doc.feature_branch;
+    if (branch !== undefined && typeof branch !== "string")
+        return null;
+    return {
+        existingRunId: typeof existing === "string" && existing !== "" ? existing : null,
+        featureBranch: typeof branch === "string" && branch !== "" ? branch : null,
+        serverValidated: doc.server_validated,
+    };
+}
+/** The plan DAG's node count, or `null` unless it parses to `{ nodes: [...] }`. */
+async function readPlanChildCount(deps, planPath) {
+    try {
+        const parsed = JSON.parse(await deps.readPlanDag(planPath));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const nodes = parsed.nodes;
+        return Array.isArray(nodes) ? nodes.length : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the read-only preview. Returns `0` for a `create` or `attach` decision and
+ * `1` for `refuse` or `stop`. Never throws: an unexpected failure becomes one
+ * named refusal in the same document.
+ */
+async function runDriveEpicPreview(deps, options) {
+    const { epicKey } = options;
+    const posture = options.attended === true || options.intoBase === true ? "attended" : "unattended";
+    const preview = {
+        epic_key: epicKey,
+        target: { base_url: null, kind: null },
+        readiness: { kind: "unknown" },
+        live_run: null,
+        plan: { status: "not_found" },
+        summary: {
+            child_count: null,
+            branch: null,
+            posture,
+            auto_merge_scope: null,
+            escalation_channel: null,
+            server_validation: "not_run",
+        },
+        decision: "refuse",
+        refusal: null,
+    };
+    /** A refusal carried by the readiness block (and mirrored where the ticket needs it). */
+    const refuseWithReadiness = (kind, named, alsoTopLevel = false) => {
+        preview.readiness = { kind, reason_id: named.reasonId, remedy: named.remedy };
+        if (alsoTopLevel)
+            preview.refusal = { reason_id: named.reasonId, remedy: named.remedy };
+        preview.decision = "refuse";
+    };
+    /** A refusal that is not about readiness: only the top-level block carries it. */
+    const refuseTopLevel = (named) => {
+        preview.refusal = { reason_id: named.reasonId, remedy: named.remedy };
+        preview.decision = "refuse";
+    };
+    try {
+        await previewDecision(deps, options, preview, refuseWithReadiness, refuseTopLevel);
+    }
+    catch {
+        // Sanitized on purpose: nothing from the thrown value reaches the document.
+        preview.summary.server_validation =
+            preview.summary.server_validation === "passed" ? "passed" : "not_run";
+        refuseTopLevel({
+            reasonId: "preview-failed",
+            remedy: "The preview could not complete. Run it again; nothing was created or started.",
+        });
+    }
+    emitPreview(deps, options, preview);
+    return preview.decision === "create" || preview.decision === "attach" ? 0 : 1;
+}
+/** Fill in `preview` by walking the same decisions a real launch makes, read-only. */
+async function previewDecision(deps, options, preview, refuseWithReadiness, refuseTopLevel) {
+    const { epicKey } = options;
+    const unknownReadiness = () => refuseWithReadiness("unknown", {
+        reasonId: READINESS_UNKNOWN_REASON_ID,
+        remedy: ESCALATE_REMEDY,
+    });
+    // --- Target: resolved, never adopted. -------------------------------------
+    const accessResult = await deps.resolveAccess(options.repo, undefined, launchSelectionOf(options));
+    if (!accessResult.ok)
+        return unknownReadiness();
+    const access = accessResult.access;
+    const profile = accessResult.profile ?? null;
+    const planeTarget = planeEndpointForBaseUrl(deps, access.baseUrl) !== null;
+    preview.target = { base_url: access.baseUrl, kind: planeTarget ? "local_plane" : "remote" };
+    const ctx = { deps, epicKey, options, access, profile };
+    // --- Readiness. -----------------------------------------------------------
+    let readiness;
+    try {
+        readiness = await deps.readReadiness(access);
+    }
+    catch {
+        return unknownReadiness();
+    }
+    const classification = classifyV2Readiness(readiness, {
+        attended: options.attended === true,
+        intoBase: options.intoBase === true,
+        hasPolicyFile: options.policyFile !== undefined,
+    });
+    preview.readiness = { kind: classification.kind };
+    const selection = selectConductor(readiness);
+    // --- The plan: supplied, or discovered. -----------------------------------
+    let planPath = options.planFile;
+    if (planPath !== undefined) {
+        preview.plan = { status: "supplied", path: planPath };
+    }
+    else {
+        const docs = await deps.resolveDocsDir();
+        if (!docs.ok)
+            return refuseTopLevel(docsRootRefusal(epicKey));
+        const discovered = await discoverEpicPlan(epicKey, docs.docsDir, deps.discoveryFs);
+        preview.plan = {
+            status: discovered.status === "found"
+                ? "found"
+                : discovered.status === "plan_ambiguous"
+                    ? "ambiguous"
+                    : "not_found",
+            ...(discovered.status === "found" ? { path: discovered.path } : {}),
+            ...(discovered.status === "plan_ambiguous" ? { candidates: [...discovered.candidates] } : {}),
+            ...(discovered.skipped.length > 0
+                ? { skipped: discovered.skipped.map((entry) => ({ path: entry.path, reason: entry.reason })) }
+                : {}),
+            epic_plans_dir: discovered.epic_plans_dir,
+        };
+        if (discovered.status === "found")
+            planPath = discovered.path;
+    }
+    // --- The live run. Conflict and unknown refuse whatever the plan says. ------
+    const live = await deps.readLiveEpicRun(access, epicKey);
+    if (live.kind === "conflict")
+        return refuseTopLevel(liveRunAmbiguousRefusal(epicKey));
+    if (live.kind === "unknown")
+        return refuseTopLevel(liveRunUnknownRefusal(epicKey, live.reason));
+    if (live.kind === "live") {
+        preview.live_run = { epic_run_id: live.epicRunId, status: live.status };
+    }
+    // --- No plan: attach to a live run, or stop. --------------------------------
+    if (planPath === undefined) {
+        if (live.kind !== "live") {
+            if (selection.kind === "not_ready") {
+                return refuseWithReadiness(classification.kind, {
+                    reasonId: ENGINE_NOT_READY_REASON_ID,
+                    remedy: ENGINE_NOT_READY_REMEDY,
+                });
+            }
+            preview.decision = "stop";
+            return;
+        }
+        const blocked = previewReadinessRefusal(ctx, classification, readiness, planeTarget, "attach");
+        if (blocked !== null)
+            return refuseWithReadiness(classification.kind, blocked);
+        const facts = await previewExecutorFacts(ctx, readiness, planeTarget, live, "No run was changed");
+        if (facts !== null)
+            return refuseWithReadiness(classification.kind, facts, true);
+        preview.decision = "attach";
+        return;
+    }
+    // --- A plan is available: the create path's gates, then setup's own dry run. --
+    const blocked = previewReadinessRefusal(ctx, classification, readiness, planeTarget, "create");
+    if (blocked !== null)
+        return refuseWithReadiness(classification.kind, blocked);
+    const facts = await previewExecutorFacts(ctx, readiness, planeTarget, null, "No run was created");
+    if (facts !== null)
+        return refuseWithReadiness(classification.kind, facts, true);
+    // Escalation channel, decided with setup-epic's own exported policy helpers. A
+    // policy that cannot be read is one fixed refusal; its path, contents, and any
+    // webhook URL never leave this function.
+    if (preview.summary.posture === "unattended") {
+        if (options.policyFile !== undefined) {
+            const policy = await readSetupEpicPolicyFile(options.policyFile, deps.readPolicyFile);
+            if (!policy.ok) {
+                return refuseTopLevel({
+                    reasonId: "policy-file-unreadable",
+                    remedy: "The --policy-file could not be read as a JSON object. Fix it or pass a different " +
+                        "file, then run the preview again.",
+                });
+            }
+            preview.summary.escalation_channel = policyDeclaresNotifyWebhook(policy.policy)
+                ? "webhook"
+                : "email";
+        }
+        else {
+            preview.summary.escalation_channel = "email";
+        }
+    }
+    preview.summary.child_count = await readPlanChildCount(deps, planPath);
+    const setup = await deps.previewSetupEpic({
+        argv: [...buildSetupEpicArgv({ ...options, planFile: planPath }), "--dry-run", "--json"],
+        baseUrl: access.baseUrl,
+    });
+    if (setup.exitCode !== 0) {
+        preview.summary.server_validation = "failed";
+        return refuseTopLevel({
+            reasonId: "setup-preview-failed",
+            remedy: "The plan did not pass validation, or the epic could not be prepared. Fix the plan or " +
+                "the condition it reports, then run the preview again. Nothing was created.",
+        });
+    }
+    const payload = readSetupPreviewPayload(setup.stdout);
+    if (payload === null) {
+        preview.summary.server_validation = "not_run";
+        return refuseTopLevel({
+            reasonId: "setup-preview-malformed",
+            remedy: "Plan validation returned no usable result, so the launch could not be predicted. Run " +
+                "the preview again. Nothing was created.",
+        });
+    }
+    preview.summary.server_validation = payload.serverValidated ? "passed" : "partial";
+    preview.summary.branch = payload.featureBranch;
+    preview.summary.auto_merge_scope =
+        preview.summary.posture === "unattended" ? payload.featureBranch : null;
+    // The bootstrap reusing a run IS an attach: it reports the run's id.
+    if (payload.existingRunId !== null) {
+        preview.live_run = {
+            epic_run_id: payload.existingRunId,
+            status: preview.live_run?.epic_run_id === payload.existingRunId ? preview.live_run.status : null,
+        };
+        preview.decision = "attach";
+        return;
+    }
+    preview.decision = live.kind === "live" ? "attach" : "create";
+}
+/**
+ * The readiness refusal a real launch would print, as a reason id and remedy, or
+ * `null` when readiness lets the launch proceed. Built from the SAME functions the
+ * real refusals use, so the strings agree byte for byte.
+ */
+function previewReadinessRefusal(ctx, classification, readiness, planeTarget, path) {
+    if (classification.kind === "operator_blocked") {
+        return { reasonId: classification.id, remedy: operatorBlockedRemedy(classification) };
+    }
+    if (classification.kind === "runtime_only") {
+        if (!planeTarget)
+            return remoteRuntimeRefusal(ctx.epicKey, ctx.access, readiness);
+        // A local plane with only the reconciler missing: a real launch WITH a plan
+        // brings the runtime up. Without one (attach) it is refused by name.
+        if (path === "attach")
+            return localReconcilerRefusal(ctx.epicKey, readiness);
+    }
+    return null;
+}
+/**
+ * The executor-side refusals a real launch would hit, decided read-only: the
+ * durable profile's coverage check, else whether an executor could be started
+ * from this checkout at all. Returns `null` when neither refuses, including when
+ * this checkout's plane already serves the live run and needs no executor.
+ */
+async function previewExecutorFacts(ctx, readiness, planeTarget, live, outcome) {
+    const { deps, epicKey, access, profile } = ctx;
+    if (profile !== null && profile.executionMode === "durable") {
+        const coverage = readiness.executor.repo_wide_executor_live;
+        return coverage === true
+            ? null
+            : durableCoverageRefusal(epicKey, access, profile, coverage, outcome);
+    }
+    if (planeTarget) {
+        if (live !== null) {
+            if (await planeServesLiveRun(ctx, live))
+                return null;
+        }
+        else if ((await findAttachablePlane(ctx).catch(() => null)) !== null) {
+            return null;
+        }
+    }
+    const inspected = await deps.inspectRunExecutorPrecondition(deps.cwd());
+    return inspected.ok
+        ? null
+        : executorPreconditionRefusal(epicKey, inspected.message, outcome === "No run was created" ? "No run was created." : "No run was changed.");
+}
+/** Print the preview: one JSON line with `--json`, short readable lines otherwise. */
+function emitPreview(deps, options, preview) {
+    if (options.json === true) {
+        deps.log(JSON.stringify(preview));
+        return;
+    }
+    const lines = [
+        `${preview.epic_key}: launch preview (read-only; nothing was created or started)`,
+        `  Target:     ${preview.target.base_url ?? "unresolved"}${preview.target.kind ? ` (${preview.target.kind})` : ""}`,
+        `  Readiness:  ${preview.readiness.kind}${preview.readiness.reason_id ? ` (${preview.readiness.reason_id})` : ""}`,
+        `  Live run:   ${preview.live_run
+            ? `${preview.live_run.epic_run_id}${preview.live_run.status ? ` (${preview.live_run.status})` : ""}`
+            : "none"}`,
+        `  Plan:       ${preview.plan.status}${preview.plan.path ? ` — ${preview.plan.path}` : ""}`,
+    ];
+    for (const candidate of preview.plan.candidates ?? [])
+        lines.push(`              candidate: ${candidate}`);
+    for (const skipped of preview.plan.skipped ?? []) {
+        lines.push(`              skipped:   ${skipped.path} (${skipped.reason})`);
+    }
+    const s = preview.summary;
+    lines.push(`  Posture:    ${s.posture ?? "n/a"}`, `  Children:   ${s.child_count ?? "n/a"}`, `  Branch:     ${s.branch ?? "n/a"}`, `  Auto-merge: ${s.auto_merge_scope ?? "n/a"}`, `  Escalation: ${s.escalation_channel ?? "n/a"}`, `  Validation: ${s.server_validation ?? "n/a"}`, `  Decision:   ${preview.decision}`);
+    if (preview.readiness.remedy)
+        lines.push(`  Remedy:     ${preview.readiness.remedy}`);
+    if (preview.refusal) {
+        lines.push(`  Refusal:    ${preview.refusal.reason_id} — ${preview.refusal.remedy}`);
+    }
+    deps.log(lines.join("\n"));
+}