@bridge_gpt/mcp-server 0.2.54 → 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 { 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_SERVER_PORT_ENV_VAR } from "./plane/types.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"];
@@ -131,7 +142,7 @@ 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_conductor_allowed` for this repository " +
+            : "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,
     },
@@ -147,6 +158,10 @@ export const V2_READINESS_REQUIREMENTS = [
         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,
     },
@@ -261,13 +276,23 @@ export function getDriveEpicUsage() {
         "GitHub App credentials, or an unattended prerequisite is NOT started: those are",
         "operator-owned, and drive-epic exits with that one named reason instead.",
         "",
-        "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.`,
+        "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",
@@ -537,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.",
                 "",
@@ -706,18 +731,89 @@ 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),
@@ -739,6 +835,30 @@ export function createDefaultDriveEpicDeps() {
         }),
         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),
@@ -771,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. -------------------------------
@@ -787,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.
@@ -852,22 +981,44 @@ 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;
             }
+            if (attachManifest !== null) {
+                return attachToPlane({ deps, epicKey, options: parsed.options, access: accessResult.access }, attachManifest, readiness);
+            }
             // ---- PHASE ONE: the control plane, and NOTHING that claims jobs --------
             //
             // BAPI-1102 reordered this whole block. It used to be `plane up` (which
@@ -903,91 +1054,12 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             // 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.
-            // ---- PHASE TWO, part one: create the run ------------------------------
-            const setup = await deps.runSetupEpic(setupArgv);
-            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([
-                    "",
-                    `${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.",
-                ].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;
-            }
-            // ---- PHASE TWO, part two: scoped lanes, then the observer -------------
-            const laneRequest = await deps.requestScopedLanes({
+            return createRunAndRequestLanes({ deps, epicKey, options: parsed.options, access: accessResult.access }, {
+                origin: "launched",
                 repoRoot,
                 planeId: controlPlane.planeId,
-                epicRunId: setup.epicRunId,
-                claimScope: { kind: "epic-runs", epicRunIds: [setup.epicRunId] },
+                awaitPlaneReady: controlPlane.awaitPlaneReady,
             });
-            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;
-            }
-            const planeReady = await controlPlane.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;
         }
         const handoff = renderConductorHandoff(selection, epicKey);
         const text = handoff.lines.join("\n");
@@ -1003,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
@@ -1021,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;
+}