@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/drive-epic.js

@@ -34,6 +34,11 @@
  * response means we do not know which authority owns this epic, and guessing is
  * the failure mode.
  *
+ * One narrow exception (BAPI-1153): with `--plan-file`, when `BAPI_BASE_URL`
+ * names the local plane's own endpoint and a TCP probe of that endpoint is
+ * actively REFUSED, the failed read is not unknown — it is "no server yet", and
+ * drive-epic cold-starts the plane. Every other failed read still escalates.
+ *
  * ## Consolidation day
  *
  * Two conductors is a transitional state; one is to be eliminated at the end of
@@ -53,15 +58,21 @@
  */
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { resolveConductorBridgeApiAccess, fetchConductorReadiness, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
-import { runSetupEpicCli } from "./setup-epic.js";
-import { formatPlaneDiagnostic, runDefaultPlanePreflight, runPlaneCli, } from "./plane/cli.js";
-import { PLANE_SERVER_PORT_ENV_VAR } from "./plane/types.js";
+import { ConductorBridgeApiError, resolveConductorBridgeApiAccess, fetchConductorReadiness, fetchEpicRunState, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
+import { BRING_UP_REFUSAL_MESSAGES, BRING_UP_RUNBOOK, firstBringUpRefusal, } from "./conductor/bring-up-facts.js";
+import { runSetupEpicWorkflow, } from "./setup-epic.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";
+import { readPlaneManifest } from "./plane/manifest.js";
+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";
 // 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 `conduct-epic`'s positional rule exactly. */
+/** Jira epic key shape. Matches `implement-epic`'s positional rule exactly. */
 const EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
 /** The two conductor paths. Derived types below come from this constant. */
 export const DRIVE_EPIC_CONDUCTORS = ["v2", "pilot"];
@@ -110,15 +121,66 @@ export const V2_READINESS_REQUIREMENTS = [
         describe: "an executor provisioned and reporting ready",
         satisfied: (r) => r.executor.liveness_readable && r.executor.ready === true,
     },
+    // BAPI-1102 — the three unattended prerequisites, in the order `setup-epic`
+    // refuses them, so readiness and the refusal name the same first blocker.
+    //
+    // Each reads the SERVER's `unattended` block and re-derives nothing. A server
+    // that does not report the block (older than BAPI-1102) leaves every one of
+    // them UNSATISFIED: "could not be read" is not "holds", and these authorize an
+    // unattended merge.
+    //
+    // The FIRST of them therefore carries the older-server remedy too, because it
+    // is the one an unreported block always blocks on, and telling that operator
+    // to set a consent flag would send them to fix something that may already be
+    // set — the server simply never said (BAPI-1102 review).
+    {
+        id: "unattended_consent",
+        describe: "repository consent to unattended conductor runs",
+        unattendedOnly: true,
+        // No fixed `remedy`: this requirement's action always depends on WHY.
+        remedyFor: (r) => r.unattended === null || r.unattended === undefined
+            ? "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.",
+        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. " +
+            "notify.local_sink does not satisfy this.",
+        satisfied: (r) => r.unattended?.notify_webhook_default_declared === true,
+    },
+    {
+        id: "repository_readiness",
+        describe: "confirmed review and conductor-CI workflows on the default branch",
+        unattendedOnly: true,
+        // S5 seam: `install-bridge conductor` is the NESTED install-time surface
+        // (BAPI-679), a different command from the top-level `conductor` ->
+        // `epic-implementer` rename in S4/BAPI-1080. It is intentionally outside
+        // S4 and every remedy string below that names it is left unchanged.
+        remedy: "Run `install-bridge conductor` to install them, or pass --attended.",
+        satisfied: (r) => r.unattended?.repository_readiness_confirmed === true,
+    },
 ];
 /**
  * The readiness facts a `plane up` can actually repair (BAPI-1054).
  *
- * Both are liveness of a process this machine starts. The other three —
- * `supervisor_setup`, `supervisor_config`, `github_credentials` — are stored
- * server-side state or credentials, and no amount of starting processes creates
- * them. Naming the repairable set here, once, is what keeps the composition
- * from ever attempting a bring-up that could not have helped.
+ * Both are 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
+ * amount of starting processes creates any of it. Naming the repairable set
+ * here, once, is what keeps the composition from ever attempting a bring-up that
+ * could not have helped.
+ *
+ * This list must NOT grow for the BAPI-1102 prerequisites. A repository that has
+ * not consented is `operator_blocked`, and starting a plane for it would leave a
+ * 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"];
 /**
@@ -133,13 +195,51 @@ export const V2_RUNTIME_READINESS_IDS = ["reconciler_live", "executor_live"];
  * three competing actions has to work out which to do first, and the order here
  * already encodes that (setup, then config, then credentials).
  */
-export function classifyV2Readiness(readiness) {
-    const unmet = V2_READINESS_REQUIREMENTS.filter((req) => !req.satisfied(readiness));
+export function classifyV2Readiness(readiness, options = {}) {
+    // BAPI-1102 — the explicit `--attended` opt-out makes the unattended-only
+    // requirements INAPPLICABLE, not merely tolerated. They authorize unattended
+    // operation and automatic merge behavior; an attended run asks for neither, so
+    // refusing it for a missing consent flag would block a configuration that is
+    // entirely safe (clar-004).
+    // BAPI-1102 — the escalation channel is satisfiable per RUN as well as per
+    // repository, and no column supplies a repository default today. A
+    // `--policy-file` may therefore declare `notify.webhook_url` and satisfy the
+    // prerequisite outright, which this layer cannot see: the file stays opaque
+    // here and is composed and read by `setup-epic`. Refusing on the repository
+    // field alone would refuse every run supplying its own channel — the very form
+    // the remedy names — so the requirement is DEFERRED to the composing step,
+    // which reads the policy and refuses if it declares none. Nothing is weakened:
+    // `setup-epic` gates before the create, and the server re-checks the predicate
+    // at approval and probes the URL there.
+    const deferred = options.hasPolicyFile
+        ? V2_READINESS_REQUIREMENTS.filter((req) => req.id !== "unattended_notify_default")
+        : V2_READINESS_REQUIREMENTS;
+    // `--into-base` is the second opt-out, and it is structural rather than
+    // declared: it selects the branch-silent composition, whose policy carries no
+    // posture and no auto-merge authorization at all. Such a run is not unattended
+    // and never becomes so, so holding it to prerequisites that authorize
+    // unattended operation would block a configuration these checks have nothing
+    // to say about — the same reasoning `--attended` rests on, reached by a
+    // different route. See `composeDefaultSetupEpicPolicy`.
+    const optedOut = options.attended === true || options.intoBase === true;
+    const applicable = optedOut
+        ? deferred.filter((req) => req.unattendedOnly !== true)
+        : deferred;
+    const unmet = applicable.filter((req) => !req.satisfied(readiness));
     if (unmet.length === 0)
         return { kind: "green" };
     const blocker = unmet.find((req) => !V2_RUNTIME_READINESS_IDS.includes(req.id));
-    if (blocker)
-        return { kind: "operator_blocked", id: blocker.id, describe: blocker.describe };
+    if (blocker) {
+        return {
+            kind: "operator_blocked",
+            id: blocker.id,
+            describe: blocker.describe,
+            ...(() => {
+                const remedy = blocker.remedyFor?.(readiness) ?? blocker.remedy;
+                return remedy ? { remedy } : {};
+            })(),
+        };
+    }
     return { kind: "runtime_only", unmetIds: unmet.map((req) => req.id) };
 }
 export function getDriveEpicUsage() {
@@ -159,20 +259,40 @@ export function getDriveEpicUsage() {
         "strategy itself is decided by the bootstrap this command delegates to, never",
         "here.",
         "",
-        "One command (BAPI-1054): with --plan-file, drive-epic starts the conductor",
-        "runtime for you when readiness is missing ONLY the reconciler/executor facts,",
-        "then creates and approves the run — one invocation, no manual `plane up` first.",
-        "A report missing supervisor setup, supervisor configuration, or GitHub App",
-        "credentials is NOT started: those are operator-owned, and drive-epic exits with",
-        "that one named reason instead.",
+        "Posture (v2, BAPI-1102): a run that selects an epic branch is created",
+        "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.",
         "",
-        "Preconditions are validated, never repaired: the current directory must be a Git",
-        "work tree, and the local server port must be free. No worktree is created for",
-        "you and no replacement port is chosen for you — each failure names the fix (for",
-        `the port, set ${PLANE_SERVER_PORT_ENV_VAR} to a free one). Fix it and rerun.`,
+        "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.",
+        "",
+        "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),`,
+        "drive-epic handles the port one of three ways, and never asks you to choose:",
+        "  - cold start: nothing listens there — it brings the plane up, then creates",
+        "    the run;",
+        "  - attach: this repository's own healthy plane is there — it creates the run",
+        "    against that plane and starts NO second server or reconciler;",
+        "  - 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.",
         "",
-        "Manual fallback (still supported): run `plane up` yourself, then rerun this",
-        "command with the same --plan-file against the now-live plane.",
+        "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.",
         "",
         "Options:",
         "  --plan-file <path>     Plan DAG sidecar. When supplied and the v2 path is",
@@ -185,6 +305,9 @@ export function getDriveEpicUsage() {
         "                         repository base branch (the pre-BAPI-1009 behavior).",
         "                         Contradictory with --feature-branch; passing both is a",
         "                         parse error.",
+        "  --attended             OPT OUT of the unattended default. Forwarded verbatim to",
+        "                         the bootstrap, which owns what it composes; drive-epic",
+        "                         reads it only to skip the unattended prerequisites.",
         "",
         "Policy (forwarded verbatim; drive-epic interprets none of it):",
         "  --policy-file <path>   JSON file holding the COMPLETE run policy.",
@@ -230,12 +353,20 @@ export function parseDriveEpicArgs(argv) {
         featureBranch = trimmed;
         return trimmed;
     };
+    let attended = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--into-base") {
             intoBase = true;
             continue;
         }
+        // BAPI-1102 — valueless, forwarded verbatim, and interpreted here for
+        // exactly one thing: making the unattended readiness prerequisites
+        // inapplicable. drive-epic reads no policy.
+        if (arg === "--attended") {
+            attended = true;
+            continue;
+        }
         if (arg === "--replace-policy") {
             replacePolicy = true;
             continue;
@@ -330,6 +461,8 @@ export function parseDriveEpicArgs(argv) {
         ...(repo ? { repo } : {}),
         ...(featureBranch ? { featureBranch } : {}),
         ...(intoBase ? { intoBase: true } : {}),
+        // Added only when supplied, so the no-flag options object stays byte-identical.
+        ...(attended ? { attended: true } : {}),
         ...(policyFile ? { policyFile } : {}),
         ...(reviewPolicy ? { reviewPolicy } : {}),
         ...(replacePolicy ? { replacePolicy: true } : {}),
@@ -343,9 +476,23 @@ export function parseDriveEpicArgs(argv) {
  * decision. The unknown case is produced by the caller, which is the only place
  * that can observe a failed read — selection itself never happens by exception
  * handling, and so never needs to report that it could not decide.
+ *
+ * BAPI-1102 — the `unattendedOnly` requirements are EXCLUDED from routing, and
+ * the exclusion is load-bearing rather than tidy. This function answers "can the
+ * v2 engine drive an epic at all?", and the answer does not depend on whether
+ * the repository has consented to UNATTENDED operation: an attended v2 run on a
+ * non-consenting repository is a perfectly ordinary, fully supported run.
+ * Including them would route every such repository to the pilot conductor the
+ * moment this ticket deployed — a silent, repository-wide change of conductor for
+ * a reason that has nothing to do with the choice, and the exact opposite of
+ * AC-3's "nothing changes for an existing run".
+ *
+ * They still gate the COMPOSED bring-up, through
+ * {@link classifyV2Readiness}, which is where an unattended run is actually
+ * about to be created.
  */
 export function selectConductor(readiness) {
-    const missing = V2_READINESS_REQUIREMENTS.filter((req) => !req.satisfied(readiness));
+    const missing = V2_READINESS_REQUIREMENTS.filter((req) => req.unattendedOnly !== true && !req.satisfied(readiness));
     if (missing.length === 0) {
         return {
             kind: "selected",
@@ -372,7 +519,7 @@ export function selectConductor(readiness) {
  * no quoting to get wrong.
  */
 export function buildSetupEpicArgv(options) {
-    const { epicKey, planFile, repo, featureBranch, intoBase, policyFile, reviewPolicy, replacePolicy } = options;
+    const { epicKey, planFile, repo, featureBranch, intoBase, attended, policyFile, reviewPolicy, replacePolicy, } = options;
     return [
         "--epic-key",
         epicKey,
@@ -380,6 +527,9 @@ export function buildSetupEpicArgv(options) {
         ...(repo ? ["--repo", repo] : []),
         ...(featureBranch ? ["--feature-branch", featureBranch] : []),
         ...(intoBase ? ["--into-base"] : []),
+        // Appended beside the other branch/posture pass-throughs, and after
+        // `--into-base` so the forwarded order matches the declaration order above.
+        ...(attended ? ["--attended"] : []),
         ...(policyFile ? ["--policy-file", policyFile] : []),
         ...(reviewPolicy ? ["--review-policy", reviewPolicy] : []),
         ...(replacePolicy ? ["--replace-policy"] : []),
@@ -412,7 +562,7 @@ export function renderConductorHandoff(selection, epicKey) {
                 "",
                 `  1. 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-conductor-bundle",
+                "     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.",
                 "",
@@ -581,26 +731,134 @@ export const DRIVE_EPIC_PRECONDITION_CHECKS = [
  * preflight happened to append them, so the reason an operator sees for a given
  * pair of failures is stable.
  */
-export function firstPreconditionRefusal(preflight) {
+export function firstPreconditionRefusal(preflight, options = {}) {
     for (const check of DRIVE_EPIC_PRECONDITION_CHECKS) {
+        // BAPI-1153: an occupied port is not a blocker when the occupant is this
+        // repository's own attachable plane — attaching is exactly how the port gets
+        // used. Every other occupant still blocks, and `plane up`'s own diagnostic is
+        // unchanged (a live plane still refuses a second `plane up`).
+        if (check === "server-port" && options.attachable === true)
+            continue;
         const found = preflight.diagnostics.find((d) => d.check === check && d.severity === "blocking");
         if (found)
             return found;
     }
     return null;
 }
+// ---------------------------------------------------------------------------
+// BAPI-1153 — cold start, attach, or one named refusal
+// ---------------------------------------------------------------------------
+/**
+ * The refusals drive-epic itself names on the cold-start and attach paths.
+ *
+ * The bring-up facts refuse under their OWN names (`second-reconciler-detected`
+ * and the rest, from `conductor/bring-up-facts.ts`), and an occupied port keeps
+ * the existing `server-port` refusal; these two are the only reasons that exist
+ * nowhere else.
+ */
+export const DRIVE_EPIC_PLANE_REFUSALS = [
+    /** The plane is bound to a run that is not a live run of this epic (R-7). */
+    "plane-already-bound",
+    /** The plane's own reconciler is not confirmed as the fresh one. */
+    "plane-reconciler-unconfirmed",
+];
+/** Loopback spellings that name the plane's `127.0.0.1` host. */
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+/**
+ * Does `baseUrl` name the plane's own loopback endpoint? Pure.
+ *
+ * Cold start and attach are decisions about THE PLANE, so they only make sense
+ * when the Bridge API the command talks to IS the plane's server. The conductor
+ * default base URL is production; a readiness failure against it says nothing
+ * about a local port, and must keep escalating exactly as before. Loopback
+ * spellings are equivalent (`localhost` and `127.0.0.1` reach the same socket);
+ * the port must match exactly.
+ */
+export function baseUrlNamesPlaneEndpoint(baseUrl, endpoint) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:")
+        return false;
+    const port = url.port === "" ? 80 : Number(url.port);
+    return LOOPBACK_HOSTNAMES.has(url.hostname) && port === endpoint.port;
+}
+/**
+ * Rebuild the identity the plane's reconciler publishes its heartbeat under. Pure.
+ *
+ * The reconciler is the manifest's `worker` member; its identity is
+ * `<hostname>:<pid>` (or `DYNO`), rebuilt by the supervisor's own
+ * `resolveMemberInstanceId` so the string cannot drift from the one the
+ * readiness gate used at bring-up. `undefined` when the manifest records no live
+ * worker pid — an unidentifiable member is never guessed at.
+ */
+export function resolvePlaneReconcilerInstanceId(manifest, env, hostname) {
+    const worker = manifest.members.find((member) => member.name === "worker");
+    if (worker === undefined || worker.pid === null)
+        return undefined;
+    const memberEnv = {};
+    if (typeof env.DYNO === "string")
+        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"];
 export function createDefaultDriveEpicDeps() {
     return {
-        resolveAccess: async (repo) => {
-            const result = await resolveConductorBridgeApiAccess(repo ? { repoName: repo } : {});
+        resolveAccess: async (repo, cwd) => {
+            const result = await resolveConductorBridgeApiAccess({
+                ...(repo ? { repoName: repo } : {}),
+                ...(cwd ? { cwd } : {}),
+            });
             return result.ok ? { ok: true, access: result.access } : { ok: false, error: result.error };
         },
         readReadiness: (access) => fetchConductorReadiness(access, globalThis.fetch),
-        runSetupEpic: (argv) => runSetupEpicCli(argv),
+        runSetupEpic: (argv) => runSetupEpicWorkflow(argv),
         readEligibilityArtifact: (path) => readFile(path, "utf8"),
         runPlanePreflight: (repoRoot) => runDefaultPlanePreflight(repoRoot),
         runPlane: (argv, overrides) => runPlaneCli(argv, overrides ?? {}),
+        launchControlPlane: ({ preflight, executors }) => launchPlaneControlPlane({
+            preflight,
+            executors,
+            // stdout/stderr, not the injected log seams: the plane streams its own
+            // member events through these for the plane's whole lifetime, and
+            // drive-epic's `log` is a per-message reporter, not a stream sink.
+            sinks: {
+                stdout: (line) => console.log(line),
+                stderr: (line) => console.error(line),
+            },
+            env: process.env,
+        }),
+        requestScopedLanes: (args) => requestPlaneScopedLanes(args),
         cwd: () => process.cwd(),
+        resolvePlaneEndpoint: () => resolvePlaneServerEndpoint(process.env),
+        probePlanePort: (host, port) => probeTcpPort(host, port, PLANE_PORT_PROBE_TIMEOUT_MS),
+        readRunState: async (access, epicRunId) => {
+            const state = await fetchEpicRunState(access, epicRunId, globalThis.fetch);
+            const run = state.epic_run;
+            if (typeof run?.status !== "string" || typeof run?.epic_key !== "string") {
+                throw new ConductorBridgeApiError("invalid-input");
+            }
+            return { status: run.status, epicKey: run.epic_key };
+        },
+        readPlaneReconcilerState: async ({ access, manifest }) => {
+            const instanceId = resolvePlaneReconcilerInstanceId(manifest, process.env, resolveHostname);
+            if (instanceId === undefined)
+                return "unidentifiable";
+            const observation = await probeAutomationHealth({
+                baseUrl: access.baseUrl,
+                repoName: access.repoName,
+                apiKey: access.apiKey,
+                component: "reconciler",
+                instanceId,
+            });
+            return observation.result.kind === "state" ? observation.result.state : observation.result.kind;
+        },
+        readPlaneManifest: (repoRoot) => readPlaneManifest(repoRoot, createPlaneFsDeps()),
         // 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),
@@ -633,12 +891,32 @@ export async function runDriveEpicCli(argv, overrides = {}) {
         if (!accessResult.ok) {
             return escalate(deps, epicKey, `conductor readiness could not be read: ${accessResult.error}`);
         }
-        // --- Read readiness. Any failure here is UNKNOWN. ------------------------
+        // --- Read readiness. Any failure here is UNKNOWN — with ONE exception. ---
         let readiness;
         try {
             readiness = await deps.readReadiness(accessResult.access);
         }
         catch (err) {
+            // BAPI-1153 — the cold-start case. With a plan file, a readiness read that
+            // failed at the TRANSPORT against the plane's own endpoint, on a port that
+            // actively refuses connections, is not "unknown": it is "no server yet".
+            // 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") {
+                const endpoint = planeEndpointForBaseUrl(deps, accessResult.access.baseUrl);
+                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,
+                        });
+                    }
+                }
+            }
             return escalate(deps, epicKey, `conductor readiness could not be read: ${safeDiagnosticMessage(err, "readiness request failed")}`);
         }
         // --- Route. Exactly one path from here on. -------------------------------
@@ -649,19 +927,8 @@ export async function runDriveEpicCli(argv, overrides = {}) {
         // artifact, bad JSON, malformed/inconsistent shape, an unsafe rendered
         // value — silently yields no advisory and never affects routing, the
         // delegated argv, or the exit code.
-        if (planFile) {
-            try {
-                const advisory = await readContainmentEligibilityAdvisory(planFile, deps.readEligibilityArtifact);
-                if (advisory) {
-                    const rendered = renderContainmentEligibilityAdvisory(advisory);
-                    if (rendered)
-                        deps.log(rendered);
-                }
-            }
-            catch {
-                // Fail open — a containment advisory is never allowed to block dispatch.
-            }
-        }
+        if (planFile)
+            await surfaceContainmentAdvisory(deps, planFile);
         // 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.
@@ -672,12 +939,22 @@ export async function runDriveEpicCli(argv, overrides = {}) {
         // the runtime facts is not a "use the other conductor" situation — it is a
         // plane that has not been started yet.
         if (planFile) {
-            const classification = classifyV2Readiness(readiness);
+            // 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
+            // always has. Its mere PRESENCE defers the escalation-channel requirement
+            // to `setup-epic`, which composes the policy and can actually read it.
+            const classification = classifyV2Readiness(readiness, {
+                attended: parsed.options.attended === true,
+                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.
+            // and byte-identical argv for the no-flag case. Only the structured
+            // result's exit code is returned, so the public contract is unchanged.
             if (classification.kind === "green") {
-                return await deps.runSetupEpic(setupArgv);
+                return (await deps.runSetupEpic(setupArgv)).exitCode;
             }
             // Operator-blocked: ONE named reason, and nothing is started. `plane up`
             // cannot create stored supervisor state or resolve GitHub App credentials,
@@ -688,7 +965,11 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                         `(${classification.id}).`,
                     "",
                     "This is not something starting the runtime can fix, so nothing was started.",
-                    "Resolve it with `install-bridge conductor`, then run drive-epic again.",
+                    // 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.",
                 ].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
@@ -700,58 +981,85 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             // Runtime-only: this invocation composes bring-up with run creation.
             const repoRoot = deps.cwd();
             const preflight = await deps.runPlanePreflight(repoRoot);
+            // BAPI-1153 — ATTACH. A port serving this repository's own live, healthy
+            // plane is not a blocker when the Bridge API this command talks to IS that
+            // plane: create/approve/cut against it and request a run-scoped lane — no
+            // second server, no second reconciler. The classification is the one the
+            // 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
+                ? existingPlane.manifest
+                : null;
             // Composition preconditions FIRST, and only these two. Preflight is
             // read-only, so a refusal here provably created no manifest, spawned no
             // process, and issued no run-creating request — AC-1's "no partial run"
             // holds structurally rather than by cleanup.
-            const precondition = firstPreconditionRefusal(preflight);
+            const precondition = firstPreconditionRefusal(preflight, {
+                attachable: attachManifest !== null,
+            });
             if (precondition) {
-                const refusal = [
+                const lines = [
                     `${epicKey}: cannot start the conductor runtime — ${precondition.check} failed.`,
                     formatPlaneDiagnostic(precondition),
-                    "",
-                    "Nothing was started. Fix the item above and run drive-epic again.",
-                ].join("\n");
+                ];
+                // BAPI-1153: an occupied port names WHICH kind of occupant it is and its
+                // one fix, still inside this single refusal.
+                if (precondition.check === "server-port") {
+                    const occupant = describePlanePortOccupant(existingPlane);
+                    lines.push(`  Occupant: ${occupant.classification} — ${occupant.remediation}`);
+                }
+                lines.push("", "Nothing was started. Fix the item above and run drive-epic again.");
+                const refusal = lines.join("\n");
                 assertSingleConductorInvocation(refusal);
                 deps.errorLog(refusal);
                 return 1;
             }
-            deps.log(`${epicKey}: the conductor runtime is not live; starting it before creating the run.`);
-            // The SAME preflight result is handed to `plane up` through its existing
-            // override seam, so the port that was probed is the port that gets launched
-            // and the two cannot disagree. Every blocking failure `plane up` finds
-            // beyond the two preconditions above is rendered by its own aggregate
-            // refusal, unchanged.
-            const planeExit = await deps.runPlane(["up"], { preflight: async () => preflight });
-            if (planeExit !== 0) {
-                // `plane up` already reported why, in its own words, and it rolls its own
-                // startup back. Nothing to add, and nothing was created here.
-                return 1;
+            if (attachManifest !== null) {
+                return attachToPlane({ deps, epicKey, options: parsed.options, access: accessResult.access }, attachManifest, readiness);
             }
-            // Delegate immediately. The readiness report is NOT re-read as a gate:
-            // `plane up` completes only after each member's durable heartbeat is fresh,
-            // whereas the readiness report derives reconciler/executor liveness from
-            // `epic_runs.last_tick_at` and `executor_jobs` rows — tables that are empty
-            // on a repository that has never run an epic. Gating on a re-read would
-            // therefore 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 here; re-sourcing that predicate belongs to A1b.4.
-            const setupExit = await deps.runSetupEpic(setupArgv);
-            if (setupExit !== 0) {
-                // The plane is deliberately LEFT RUNNING. `plane down` stops the
-                // manifest-bound run before terminating processes, so winding down now
-                // would stop the very run setup-epic may have just created, bound, or
-                // approved. The live plane is reported rather than abandoned — the
-                // operator owns the decision, which is the documented two-step state.
-                deps.errorLog([
-                    "",
-                    `${epicKey}: the conductor runtime was started by this invocation and is STILL RUNNING.`,
-                    "It was not wound down automatically, because doing so would stop a run that may",
-                    "already have been created and approved. Inspect it with `plane status`, and wind it",
-                    "down with `plane down` once you have decided what to do with the run.",
-                ].join("\n"));
+            // ---- PHASE ONE: the control plane, and NOTHING that claims jobs --------
+            //
+            // BAPI-1102 reordered this whole block. It used to be `plane up` (which
+            // spawned executor lanes) and THEN `setup-epic`, which cannot work in two
+            // independent ways: the lanes were spawned with no claim scope, so since
+            // BAPI-1026 they exit at startup; and `plane up` stays attached for the
+            // plane's lifetime, so the composed flow could never reach `setup-epic` at
+            // all. Both are why the BAPI-1061 and BAPI-1085 drivers fell back to
+            // hand-written helpers.
+            //
+            // The new order is the only one that can work: the server has to be up
+            // before a run can be created, and the run has to exist before a lane can
+            // be scoped to it.
+            deps.log(`${epicKey}: the conductor runtime is not live; starting its control plane before creating the run.`);
+            // The SAME preflight result is handed to the launch, so the port that was
+            // probed is the port that gets launched and the two cannot disagree.
+            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;
             }
-            return setupExit;
+            // 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 }, {
+                origin: "launched",
+                repoRoot,
+                planeId: controlPlane.planeId,
+                awaitPlaneReady: controlPlane.awaitPlaneReady,
+            });
         }
         const handoff = renderConductorHandoff(selection, epicKey);
         const text = handoff.lines.join("\n");
@@ -767,6 +1075,28 @@ export async function runDriveEpicCli(argv, overrides = {}) {
         return 1;
     }
 }
+/**
+ * BAPI-1022: surface any containment-hazard advisory before dispatch or handoff.
+ *
+ * Read only when a plan file was supplied (the sidecar has no other resolvable
+ * location). Fail-open: any failure — missing artifact, bad JSON,
+ * malformed/inconsistent shape, an unsafe rendered value — silently yields no
+ * advisory and never affects routing, the delegated argv, or the exit code.
+ * One helper, so the cold-start path (BAPI-1153) cannot drift from the rest.
+ */
+async function surfaceContainmentAdvisory(deps, planFile) {
+    try {
+        const advisory = await readContainmentEligibilityAdvisory(planFile, deps.readEligibilityArtifact);
+        if (advisory) {
+            const rendered = renderContainmentEligibilityAdvisory(advisory);
+            if (rendered)
+                deps.log(rendered);
+        }
+    }
+    catch {
+        // Fail open — a containment advisory is never allowed to block dispatch.
+    }
+}
 /**
  * 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
@@ -785,3 +1115,335 @@ function escalate(deps, epicKey, reason) {
     deps.errorLog(text);
     return 1;
 }
+/** Emit one refusal, guarded so it can never name a second conductor. */
+function refuse(deps, lines) {
+    const text = lines.join("\n");
+    assertSingleConductorInvocation(text);
+    deps.errorLog(text);
+    return 1;
+}
+/**
+ * The plane endpoint, when `baseUrl` names it; otherwise `null`.
+ *
+ * `null` for an unresolvable `BAPI_PLANE_PORT` too: with no endpoint there is
+ * no plane to cold-start or attach to, and the caller's existing behavior
+ * applies.
+ */
+function planeEndpointForBaseUrl(deps, baseUrl) {
+    const resolution = deps.resolvePlaneEndpoint();
+    if (!resolution.ok)
+        return null;
+    return baseUrlNamesPlaneEndpoint(baseUrl, resolution.endpoint) ? resolution.endpoint : null;
+}
+/** What to tell the operator about a plane THIS invocation started and left up. */
+const LAUNCHED_PLANE_LEFT_RUNNING = [
+    "",
+    "The conductor CONTROL PLANE was started by this invocation and is STILL RUNNING.",
+    "No run was created and no executor lane was spawned. Inspect it with `plane status`,",
+    "and wind it down with `plane down` once the item above is fixed.",
+];
+/**
+ * The bring-up facts and the plane-membership check, before any create.
+ *
+ * Returns the refusal lines, or `null` when admitted. Two questions:
+ *
+ *   1. The deployment-wide facts (`bring_up`), under their own refusal names —
+ *      a behind database, no worker, or two reconcilers refuse here exactly as
+ *      `setup-epic` would, and they must refuse here too because an attach to a
+ *      run that already exists never reaches setup-epic's create-path gate.
+ *   2. Is THE PLANE'S OWN reconciler the fresh one? The deployment count cannot
+ *      say whose heartbeat it is; this instance-scoped read can. Combined with a
+ *      fresh count of exactly one, it proves the single live transition
+ *      authority is the reconciler of the plane being used. The identity is
+ *      rebuilt from the manifest, sent as a query parameter, and never rendered.
+ */
+async function checkPlaneAdmission(ctx, readiness, manifest) {
+    const bringUpRefusal = firstBringUpRefusal(readiness.bring_up ?? null);
+    if (bringUpRefusal !== null) {
+        return [
+            `${ctx.epicKey}: REFUSED (${bringUpRefusal}) — ${BRING_UP_REFUSAL_MESSAGES[bringUpRefusal]}`,
+        ];
+    }
+    let state;
+    try {
+        state = await ctx.deps.readPlaneReconcilerState({ access: ctx.access, manifest });
+    }
+    catch {
+        state = "unavailable";
+    }
+    if (state === "fresh")
+        return null;
+    return [
+        `${ctx.epicKey}: REFUSED (plane-reconciler-unconfirmed) — the plane's own reconciler could ` +
+            `not be confirmed as the live transition authority (its heartbeat reads: ${state}).`,
+        "Another reconciler may be standing in for this plane — often a reparented worker.py from an",
+        `earlier plane. Check \`ps aux | grep worker.py\` (${BRING_UP_RUNBOOK} §6), stop any`,
+        "survivor, and run drive-epic again.",
+    ];
+}
+/**
+ * COLD START: nothing is listening on the plane endpoint, so bring the control
+ * plane up and compose the run against it.
+ *
+ * Reuses the BAPI-1102 two-phase launch unchanged — `executors: 1`, whose phase
+ * one spawns the server and reconciler and no claiming lane — so there is one
+ * bring-up ordering, not two.
+ */
+async function coldStartPlane(ctx) {
+    const { deps, epicKey } = ctx;
+    // The cold start leaves the readiness `catch` before the ordinary advisory
+    // read is reached, so it surfaces the BAPI-1022 containment advisory itself —
+    // before anything is started, exactly as every other plan-file route does.
+    if (ctx.options.planFile)
+        await surfaceContainmentAdvisory(deps, ctx.options.planFile);
+    deps.log(`${epicKey}: nothing is listening on the plane endpoint; cold-starting the conductor plane.`);
+    const repoRoot = deps.cwd();
+    const preflight = await deps.runPlanePreflight(repoRoot);
+    const precondition = firstPreconditionRefusal(preflight);
+    if (precondition) {
+        return refuse(deps, [
+            `${epicKey}: cannot start the conductor runtime — ${precondition.check} failed.`,
+            formatPlaneDiagnostic(precondition),
+            "",
+            "Nothing was started. Fix the item above and run drive-epic again.",
+        ]);
+    }
+    const controlPlane = await deps.launchControlPlane({ preflight, executors: 1 });
+    if (!controlPlane.ok) {
+        for (const line of controlPlane.lines)
+            deps.errorLog(line);
+        return 1;
+    }
+    void controlPlane.lifetime.catch(() => undefined);
+    // Read ONCE, for route selection only — the pre-launch read had no server to
+    // answer it. Not a runtime gate: runtime facts are not consulted here beyond
+    // the classification, which treats them as repairable.
+    let readiness;
+    try {
+        readiness = await deps.readReadiness(ctx.access);
+    }
+    catch (err) {
+        return refuse(deps, [
+            `${epicKey}: the plane came up, but its conductor readiness could not be read: ` +
+                safeDiagnosticMessage(err, "readiness request failed"),
+            ...LAUNCHED_PLANE_LEFT_RUNNING,
+        ]);
+    }
+    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}).`,
+            classification.remedy ??
+                "Resolve it with `install-bridge conductor`, then run drive-epic again.",
+            ...LAUNCHED_PLANE_LEFT_RUNNING,
+        ]);
+    }
+    const manifestRead = await deps.readPlaneManifest(repoRoot);
+    if (manifestRead.kind !== "valid" || manifestRead.manifest.planeId !== controlPlane.planeId) {
+        return refuse(deps, [
+            `${epicKey}: REFUSED (plane-reconciler-unconfirmed) — the plane manifest this invocation ` +
+                "just wrote could not be read back, so its reconciler cannot be identified.",
+            ...LAUNCHED_PLANE_LEFT_RUNNING,
+        ]);
+    }
+    const admission = await checkPlaneAdmission(ctx, readiness, manifestRead.manifest);
+    if (admission !== null) {
+        return refuse(deps, [...admission, ...LAUNCHED_PLANE_LEFT_RUNNING]);
+    }
+    return createRunAndRequestLanes(ctx, {
+        origin: "launched",
+        repoRoot,
+        planeId: controlPlane.planeId,
+        awaitPlaneReady: controlPlane.awaitPlaneReady,
+    });
+}
+/**
+ * ATTACH: the plane endpoint already serves this repository's live plane.
+ *
+ * Starts no server and no reconciler — `launchControlPlane` is never called on
+ * this path. Credentials resolve against the MANIFEST's repository root through
+ * the shared resolver, as `plane down` does for a bound run.
+ */
+async function attachToPlane(ctx, manifest, readiness) {
+    const { deps, epicKey } = ctx;
+    const rooted = await deps.resolveAccess(ctx.options.repo, manifest.repoRoot);
+    if (!rooted.ok) {
+        return refuse(deps, [
+            `${epicKey}: cannot attach to the running plane — Bridge API credentials could not be ` +
+                `resolved for its repository: ${rooted.error}`,
+            "",
+            "Nothing was started. Fix the credential and run drive-epic again.",
+        ]);
+    }
+    const attachCtx = { ...ctx, access: rooted.access };
+    // R-7, decided BEFORE any create request.
+    if (manifest.epicRunId !== undefined) {
+        let bound = null;
+        try {
+            bound = await deps.readRunState(rooted.access, manifest.epicRunId);
+        }
+        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) {
+            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.",
+                "",
+                "Nothing was started.",
+            ]);
+        }
+    }
+    const admission = await checkPlaneAdmission(attachCtx, readiness, manifest);
+    if (admission !== null) {
+        return refuse(deps, [...admission, "", "Nothing was started."]);
+    }
+    deps.log(`${epicKey}: attaching to this repository's running plane — no second server or reconciler will start.`);
+    return createRunAndRequestLanes(attachCtx, {
+        origin: "attached",
+        repoRoot: manifest.repoRoot,
+        planeId: manifest.planeId,
+        ...(manifest.epicRunId !== undefined ? { boundRunId: manifest.epicRunId } : {}),
+    });
+}
+/**
+ * The shared tail: create/approve/cut through `setup-epic`, then request lanes
+ * scoped to exactly that run.
+ *
+ * The `launched` wording is the BAPI-1102 wording, unchanged. The lane scope is
+ * always `epic-runs` naming the one run setup returned — it renders through
+ * `executorClaimScopeArgs` as `--epic-run-id`, and `--repo-wide` is not
+ * constructible here.
+ */
+async function createRunAndRequestLanes(ctx, plane) {
+    const { deps, epicKey } = ctx;
+    const launched = plane.origin === "launched";
+    // ---- PHASE TWO, part one: create the run ------------------------------
+    const setup = await deps.runSetupEpic(buildSetupEpicArgv(ctx.options));
+    if (setup.exitCode !== 0) {
+        // The control plane is deliberately LEFT RUNNING, and NO EXECUTOR LANE
+        // was spawned — there is nothing to claim a job that may not exist.
+        // Winding down automatically would stop the very run `setup-epic` may
+        // have just created, because `plane down` stops the manifest-bound run
+        // before terminating processes.
+        deps.errorLog((launched
+            ? [
+                "",
+                `${epicKey}: the conductor CONTROL PLANE was started by this invocation and is STILL RUNNING.`,
+                "No executor lane was spawned, so nothing is claiming jobs.",
+                "It was not wound down automatically, because doing so would stop a run that may",
+                "already have been created and approved. Inspect it with `plane status`, and wind it",
+                "down with `plane down` once you have decided what to do with the run.",
+            ]
+            : [
+                "",
+                `${epicKey}: the plane this invocation attached to was left running exactly as it was.`,
+                "No executor lane was requested. Inspect it with `plane status`.",
+            ]).join("\n"));
+        return setup.exitCode;
+    }
+    if (setup.epicRunId === undefined) {
+        // Exit zero with no run id is an ORCHESTRATION failure, not a success:
+        // there is no authoritative identity to scope lanes to, and the one thing
+        // this reordering exists to prevent is a lane started against a run
+        // nobody named. Guessing — a repository-wide lookup, say — could scope
+        // lanes to a DIFFERENT run on the same repository.
+        deps.errorLog([
+            "",
+            `${epicKey}: setup reported success but returned no epic run id, so no executor lane`,
+            "could be scoped to this run. NO LANE WAS SPAWNED. The control plane is still",
+            "running: inspect it with `plane status` and wind it down with `plane down`.",
+        ].join("\n"));
+        return 1;
+    }
+    if (plane.boundRunId !== undefined && setup.epicRunId !== plane.boundRunId) {
+        // The bound run was checked live and of this epic, so setup should have
+        // reused it. A different id means the world moved between the check and the
+        // create; requesting lanes now would point a single-run plane at a second run.
+        deps.errorLog([
+            "",
+            `${epicKey}: setup resolved run ${setup.epicRunId}, but the attached plane is bound to run`,
+            `${plane.boundRunId}. NO LANE WAS REQUESTED. Inspect both with \`plane status\` and the run's`,
+            "own status before retrying.",
+        ].join("\n"));
+        return 1;
+    }
+    // ---- PHASE TWO, part two: scoped lanes, then the observer -------------
+    const laneRequest = await deps.requestScopedLanes({
+        repoRoot: plane.repoRoot,
+        planeId: plane.planeId,
+        epicRunId: setup.epicRunId,
+        claimScope: { kind: "epic-runs", epicRunIds: [setup.epicRunId] },
+    });
+    if (!laneRequest.ok) {
+        deps.errorLog([
+            "",
+            `${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."
+                : "Inspect it with `plane status`, and wind it down with `plane down`.",
+            "The run itself is untouched and still committed server-side.",
+        ].join("\n"));
+        return 1;
+    }
+    if (plane.awaitPlaneReady === undefined) {
+        // Attached: the plane's own detached runtime performs the spawn and the
+        // per-lane readiness gating, and this process may exit first. Its progress
+        // is the plane's to report.
+        deps.log([
+            "",
+            `${epicKey}: attached — executor lane(s) scoped to run ${setup.epicRunId} were requested`,
+            "from the running plane, whose runtime starts them and then the dead-man observer.",
+            "`plane status` reports their progress; the run's own status reports dispatch.",
+        ].join("\n"));
+        return 0;
+    }
+    const planeReady = await plane.awaitPlaneReady();
+    if (!planeReady.ok) {
+        // No rollback of the RUN, deliberately. A lane that failed to start says
+        // nothing about whether the run is valid, and stopping a committed,
+        // approved run because a local process died would destroy state the
+        // operator may well want to retry into.
+        for (const line of planeReady.lines)
+            deps.errorLog(line);
+        deps.errorLog([
+            "",
+            `${epicKey}: no executor lane became ready, and the dead-man observer was NOT started.`,
+            "The control plane and the committed run are both intact and were not rolled back:",
+            "the runtime stops the lane cohort it started and keeps supervising the server and",
+            "reconciler, so nothing is claiming jobs and the run keeps its server-side state.",
+            "Read the per-lane logs under .bridge/plane/, then wind the plane down with",
+            "`plane down` and re-run this command once the cause is fixed. A plane cannot be",
+            "asked for lanes a second time: the runtime waits for that request exactly once.",
+        ].join("\n"));
+        return 1;
+    }
+    // Plane readiness is reported SEPARATELY from run dispatchability, and the
+    // separation is the point: every process is up, but the reconciler still
+    // holds dispatch while a feature branch's index scope finishes preparing.
+    // An operator told "ready" who then sees no work start would go looking for
+    // a broken plane that is working perfectly.
+    deps.log([
+        "",
+        `${epicKey}: the plane is READY — control plane, scoped executor lane(s) for run ` +
+            `${setup.epicRunId}, and the dead-man observer are all up.`,
+        "That reports PROCESSES. If this run cuts an epic branch, the reconciler holds ticket",
+        "dispatch until its index scope finishes preparing; `plane status` and the run's own",
+        "status report that separately.",
+    ].join("\n"));
+    return 0;
+}