@bridge_gpt/mcp-server 0.2.53 → 0.2.54

package/build/doctor.js

@@ -161,6 +161,13 @@ export function getDoctorUsage() {
         "deletes a branch, or repairs any git state, and never changes the exit code.",
         "Without --stale-branch it runs no git probe at all and prints no section.",
         "",
+        "The 'operational advisories' section also reports RETIRED local drive helpers",
+        "(~/.local/bin/bapi-runtime-up, ~/.local/bin/bapi-drive) when they are still on",
+        "this machine (BAPI-1102). That is a PATH-PRESENCE check only: doctor does not",
+        "run, read, source, chmod, or delete either file, and cannot remove them for you",
+        "— they are outside this repository, so their removal is an operator step. The",
+        "row is advisory and never changes the exit code.",
+        "",
         "Exit code: 0 when all required prerequisites are present, non-zero otherwise.",
     ].join("\n");
 }
@@ -1413,6 +1420,24 @@ export function formatConductEpicDiagnosticReport(diagnostic) {
     lines.push("           lock, rewrites no checkpoint, and never changes the exit code.");
     return lines.join("\n");
 }
+/**
+ * The transitional local helpers BAPI-1102 retires.
+ *
+ * `~/.local/bin` scripts, never shipped in this package and not in this
+ * repository, so nothing here can delete them — removal is an OPERATOR step. What
+ * the repository CAN do is notice them and say so, which is the difference
+ * between a documented retirement and a silent one: an operator whose muscle
+ * memory still types `bapi-drive` would otherwise keep driving epics through a
+ * path that predates the scoped-lane bring-up, and diagnose the resulting
+ * unscoped run as a server problem.
+ *
+ * Relative to the home directory, joined at collection time so no absolute path
+ * is baked into the module.
+ */
+export const LEGACY_DRIVE_HELPER_RELATIVE_PATHS = [
+    ".local/bin/bapi-runtime-up",
+    ".local/bin/bapi-drive",
+];
 /**
  * Collect the operational advisories, read-only.
  *
@@ -1514,7 +1539,30 @@ export async function collectOperationalAdvisories(deps) {
             conductorObservation = "observed";
         }
     }
-    return { dispatcher, conductorObservation, conductors, indeterminateLocks };
+    // BAPI-1102 — a pure path-presence check, using the SAME injected `stat` and
+    // `homedir` seams every other advisory here uses, so it stays deterministic
+    // under test and reaches no real filesystem in one. A `stat` that throws is
+    // "absent"; it is never retried, and a permission error is not reported as a
+    // finding, because "I could not stat it" is not evidence that a stale helper is
+    // in use.
+    const legacyDriveHelpers = [];
+    for (const relative of LEGACY_DRIVE_HELPER_RELATIVE_PATHS) {
+        const absolute = path.join(deps.homedir(), relative);
+        try {
+            await deps.stat(absolute);
+            legacyDriveHelpers.push(absolute);
+        }
+        catch {
+            /* absent, or unreadable — either way, nothing to report */
+        }
+    }
+    return {
+        dispatcher,
+        conductorObservation,
+        conductors,
+        indeterminateLocks,
+        legacyDriveHelpers,
+    };
 }
 /** Render the operational-advisories section. Advisory: never changes the exit code. */
 export function formatOperationalAdvisoryReport(diagnostic) {
@@ -1554,6 +1602,21 @@ export function formatOperationalAdvisoryReport(diagnostic) {
         lines.push(`           ${diagnostic.indeterminateLocks} local lock(s) could not be judged (remote host,\n` +
             "           malformed, or unreadable) and are excluded from the live count.");
     }
+    // BAPI-1102. A WARN, never a failure, and deliberately separate from every
+    // readiness signal above: a stale helper says nothing about whether this
+    // repository's conductor works, so classifying it as a readiness problem would
+    // report a perfectly healthy install as runtime-broken and could block a setup
+    // that has nothing wrong with it.
+    if (diagnostic.legacyDriveHelpers.length > 0) {
+        lines.push(`  WARN     Legacy local drive helpers detected: ${diagnostic.legacyDriveHelpers.length} file(s).`);
+        for (const helper of diagnostic.legacyDriveHelpers) {
+            lines.push(`           ${helper}`);
+        }
+        lines.push("           These predate the scoped two-phase bring-up and are retired. Confirm\n" +
+            "           `drive-epic <EPIC> --plan-file <dag>` works for you, then remove them.\n" +
+            "           doctor performed a PATH-PRESENCE check only: it did not run, read, or\n" +
+            "           modify either file, and it cannot delete them for you.");
+    }
     lines.push("           Read-only: this section issues two Bridge GETs and reads local lock state. It");
     lines.push("           runs NO command probe, repairs no scheduler, and never changes the exit code.");
     return lines.join("\n");
@@ -1927,6 +1990,10 @@ export async function runDoctorCli(argv, overrides = {}) {
                 conductorObservation: "unavailable",
                 conductors: [],
                 indeterminateLocks: 0,
+                // Empty, not omitted: a collection that failed has not established
+                // that a legacy helper is absent, and a fallback that CLAIMED to have
+                // checked would be the one kind of wrong answer worse than silence.
+                legacyDriveHelpers: [],
             }));
         }
     }

package/build/drive-epic.js

@@ -54,8 +54,8 @@
 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 { 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 { validateBranchName } from "./base-ref.js";
 // BAPI-806: mcp-identity.ts is the SOLE source of the package-name literal, so
@@ -110,15 +110,62 @@ 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_conductor_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,
+        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 +180,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,12 +244,22 @@ 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.",
+        "",
+        "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.",
         "",
         "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",
@@ -185,6 +280,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 +328,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 +436,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 +451,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 +494,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 +502,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"] : []),
@@ -596,10 +721,23 @@ export function createDefaultDriveEpicDeps() {
             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(),
         // stdout is safe here: `drive-epic` is dispatched BEFORE MCP server
         // construction, so nothing has claimed stdout for the protocol transport.
@@ -672,12 +810,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 +836,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
@@ -716,42 +868,126 @@ export async function runDriveEpicCli(argv, overrides = {}) {
                 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.
+            // ---- 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;
             }
-            // 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.
+            // 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.
+            // ---- 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 runtime was started by this invocation and is STILL RUNNING.`,
+                    `${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;
             }
-            return setupExit;
+            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({
+                repoRoot,
+                planeId: controlPlane.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;
+            }
+            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");