@bridge_gpt/mcp-server 0.2.52 → 0.2.54

package/build/plane/alembic-head.js

@@ -13,10 +13,16 @@
  * condition it guards is already reported loudly by the server at dispatch time.
  */
 import path from "path";
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
 /** Remediation embedded in a confirmed-mismatch diagnostic. */
 export const PLANE_ALEMBIC_REMEDIATION = "alembic -c alembic.ini upgrade head";
 /** Fixed prefix of the fail-open warning, so tests and greps can match it. */
 export const PLANE_ALEMBIC_UNVERIFIED_PREFIX = "could not verify database migration head";
+/** Structured fix for a confirmed migration mismatch. */
+export const PLANE_ALEMBIC_MISMATCH_REMEDIATION = `run \`${PLANE_ALEMBIC_REMEDIATION}\` to bring the database up to the migration head, then retry.`;
+/** Structured fix for an unverifiable migration head. Never blocking. */
+export const PLANE_ALEMBIC_UNVERIFIED_REMEDIATION = "verify by hand with `alembic -c alembic.ini heads` and `alembic -c alembic.ini current`; " +
+    "startup continues, and the server reports CONTRACT_MIGRATION_BEHIND at dispatch if the database is behind.";
 /**
  * Path to the repository virtualenv's Alembic executable.
  *
@@ -72,39 +78,62 @@ export function parseAlembicRevisions(output) {
 export async function checkAlembicHead(repoRoot, deps) {
     const alembic = resolveRepositoryAlembicCommand(repoRoot, deps.platform);
     if (!(await deps.fileExists(alembic))) {
-        return unverified("the repository virtualenv Alembic executable was not found");
+        return unverified("the repository virtualenv Alembic executable was not found", "the repository virtualenv Alembic executable was not found");
     }
     const heads = await deps.execFile(alembic, ["-c", "alembic.ini", "heads"], { cwd: repoRoot });
     if (!heads.ok) {
-        return unverified(`\`alembic heads\` did not complete (${heads.error})`);
+        // The interpolated `error` stays in the legacy message for the operator at
+        // the terminal; the consolidated detail is fixed prose. In production that
+        // field is an errno code, but this outcome flows into a wider report and
+        // must not depend on every caller keeping it that way.
+        return unverified(`\`alembic heads\` did not complete (${heads.error})`, "`alembic heads` did not complete");
     }
     const current = await deps.execFile(alembic, ["-c", "alembic.ini", "current"], { cwd: repoRoot });
     if (!current.ok) {
-        return unverified(`\`alembic current\` did not complete (${current.error})`);
+        return unverified(`\`alembic current\` did not complete (${current.error})`, "`alembic current` did not complete");
     }
     const headRevisions = parseAlembicRevisions(heads.stdout);
     const currentRevisions = parseAlembicRevisions(current.stdout);
     if (headRevisions === null || currentRevisions === null) {
-        return unverified("Alembic output did not contain a readable revision");
+        return unverified("Alembic output did not contain a readable revision", "Alembic output did not contain a readable revision");
     }
     const matches = headRevisions.length === currentRevisions.length &&
         headRevisions.every((rev, i) => rev === currentRevisions[i]);
-    if (matches)
-        return null;
-    return {
+    if (matches) {
+        return planeCheckPassed("alembic-head", ALEMBIC_CHECK_LABEL, "the database is at the repository migration head");
+    }
+    return planeCheckFinding({
         check: "alembic-head",
         severity: "blocking",
         message: `the database is not at the migration head — heads [${headRevisions.join(", ")}], ` +
             `current [${currentRevisions.join(", ")}]. A database behind the head blocks ` +
             `conductor dispatch. Run \`${PLANE_ALEMBIC_REMEDIATION}\``,
-    };
+        remediation: PLANE_ALEMBIC_MISMATCH_REMEDIATION,
+    }, ALEMBIC_CHECK_LABEL, 
+    // Revision ids are repository-authored slugs, not secrets, and they are the
+    // one fact that makes this finding actionable.
+    `database at [${currentRevisions.join(", ")}], repository head [${headRevisions.join(", ")}]`);
 }
-function unverified(detail) {
-    return {
+/** Human-readable name for the migration-head prerequisite. */
+const ALEMBIC_CHECK_LABEL = "Database migration head";
+/**
+ * The fail-open branch: warning severity, and never blocking.
+ *
+ * TWO details, deliberately. `messageDetail` is the legacy operator-facing prose
+ * and may name the command's own `error` field; `outcomeDetail` is fixed prose
+ * only, because the outcome flows into the consolidated readiness report. The
+ * production `execFile` adapter puts an errno code in `error`, but this
+ * separation means the consolidated report stays safe even if some caller ever
+ * puts raw stderr, an interpreter path, or a thrown message there.
+ */
+function unverified(messageDetail, outcomeDetail) {
+    const diagnostic = {
         check: "alembic-head",
         severity: "warning",
-        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${detail}. Startup continues — verify with ` +
+        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${messageDetail}. Startup continues — verify with ` +
             `\`alembic -c alembic.ini heads\` and \`alembic -c alembic.ini current\` if a run ` +
             "later reports CONTRACT_MIGRATION_BEHIND.",
+        remediation: PLANE_ALEMBIC_UNVERIFIED_REMEDIATION,
     };
+    return planeCheckFinding(diagnostic, ALEMBIC_CHECK_LABEL, `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${outcomeDetail}`);
 }

package/build/plane/build-freshness.js

@@ -13,6 +13,7 @@
  * can be older than a rebuild that overwrote files in place.
  */
 import path from "path";
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
 /** Remediation text embedded in every blocking build diagnostic. */
 export const PLANE_BUILD_REMEDIATION = "cd mcp_server && npm run build";
 /**
@@ -93,42 +94,49 @@ export async function findBuildMtime(executorEntrypoint, deps) {
  * stale or absent build is exactly the failure this check exists to prevent, so
  * unlike the Alembic check there is no fail-open branch.
  */
+export const PLANE_BUILD_FIX_REMEDIATION = "run `cd mcp_server && npm run build` to rebuild the executor entrypoint, then retry.";
 export async function checkPlaneBuildFreshness(repoRoot, deps) {
+    const label = "Executor build freshness";
     const packageRoot = path.join(repoRoot, "mcp_server");
     const buildDir = path.join(packageRoot, "build");
     const executorEntrypoint = path.join(buildDir, "index.js");
     const srcDir = path.join(packageRoot, "src");
     const buildMtime = await findBuildMtime(executorEntrypoint, deps);
     if (!buildMtime.ok) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: `the executor build entrypoint is missing or unreadable at ` +
                 `mcp_server/build/index.js — run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, "the executor build entrypoint is missing or unreadable");
     }
     const sourceMtime = await findNewestSourceMtime(srcDir, deps);
     if (!sourceMtime.ok) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: `could not read mcp_server/src to compare against the build ` +
                 `(${sourceMtime.error}) — run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, 
+        // `sourceMtime.error` is an errno code, already sanitized by `sanitize()`.
+        `the executor sources could not be read for comparison (${sourceMtime.error})`);
     }
     // Equality passes: a build written in the same millisecond as its newest
     // source is current, and treating the boundary as stale would refuse a
     // perfectly good build on a coarse-resolution filesystem.
     if (sourceMtime.mtimeMs !== null && sourceMtime.mtimeMs > buildMtime.mtimeMs) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: "mcp_server/build/ is STALE — a source file under mcp_server/src is newer " +
                 `than mcp_server/build/index.js, so executors would run old code. ` +
                 `Run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, "mcp_server/build/ is stale — a source file is newer than the build entrypoint");
     }
-    return null;
+    return planeCheckPassed("executor-build", label, "the executor build is present and current");
 }
 /**
  * Fixed refusal prose for an unresolvable runtime re-exec target (BAPI-768).
@@ -153,13 +161,16 @@ export const PLANE_RUNTIME_ENTRYPOINT_REFUSAL = "the currently executing MCP bui
  * degraded plane, it is no plane at all.
  */
 export function checkPlaneRuntimeEntrypoint(resolution) {
-    if (resolution.ok)
-        return null;
-    return {
+    const label = "Runtime re-exec entrypoint";
+    if (resolution.ok) {
+        return planeCheckPassed("runtime-entrypoint", label, "the executing build can re-enter itself");
+    }
+    return planeCheckFinding({
         check: "runtime-entrypoint",
         severity: "blocking",
         message: PLANE_RUNTIME_ENTRYPOINT_REFUSAL,
-    };
+        remediation: PLANE_BUILD_FIX_REMEDIATION,
+    }, label, "the currently executing MCP build could not be re-entered");
 }
 function sanitize(err) {
     const code = err?.code;

package/build/plane/cli.js

@@ -13,14 +13,15 @@
  */
 import { randomUUID } from "crypto";
 import { PLANE_ENTRYPOINT_ACTION, PLANE_ID_ENV_VAR, PLANE_MANIFEST_SCHEMA_VERSION, PLANE_OBSERVER_CHANNEL_TYPE_ENV, PLANE_OBSERVER_COMMAND, PLANE_OBSERVER_DESTINATION_ENV, PLANE_RUNTIME_ACTION, PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
+import { validateExecutorClaimScope, } from "../executor/claim-scope.js";
 import { PLANE_RUNTIME_ENTRYPOINT_REFUSAL } from "./build-freshness.js";
 import { relativeLogPathFor } from "./manifest.js";
-import { claimPlaneManifest } from "./manifest.js";
+import { claimPlaneManifest, requestPlaneManifestLanes } from "./manifest.js";
 import { runPlanePreflight } from "./preflight.js";
-import { buildPlaneMemberRoster, resolvePlaneServerEndpoint } from "./member-roster.js";
+import { buildPlaneControlPlaneRoster, buildPlaneExecutorLaneRoster, buildPlaneMemberRoster, buildPlaneObserverRoster, resolvePlaneServerEndpoint, } from "./member-roster.js";
 import { getPlaneStatus, formatPlaneStatus } from "./status.js";
 import { shutdownPlane, formatPlaneShutdown } from "./shutdown.js";
-import { launchPlaneSupervisor, runPlaneRuntime, } from "./supervisor.js";
+import { launchPlaneSupervisor, runPlaneRuntime, PLANE_RUNTIME_TWO_PHASE_FLAG, } from "./supervisor.js";
 import { createMemberLogDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, createPlaneSpawn, probeAutomationHealth, probeTcpPort, registerSignalHandler, resolveHomedir, resolveHostname, resolveNodeExecutable, resolvePackageEntrypoint, } from "./defaults.js";
 import { resolveBapiCredentials } from "../credential-store.js";
 import { resolveRequiredStartTicketsRepoName } from "../start-tickets-repo.js";
@@ -72,8 +73,48 @@ export function parsePlaneArgs(argv) {
         };
     }
     let executors = null;
+    // BAPI-1102 — the claim scope every executor lane will be started with.
+    // `--epic-run-id` is REPEATABLE and order-preserving, matching the executor's
+    // own semantics exactly; `--repo-wide` is valueless and once-only, matching
+    // `--executors`' precedent for a flag that may not be restated.
+    const epicRunIds = [];
+    let repoWide = false;
+    let twoPhase = false;
     for (let i = 0; i < rest.length; i += 1) {
         const arg = rest[i];
+        if (arg === "--epic-run-id") {
+            const raw = rest[i + 1];
+            i += 1;
+            if (raw === undefined) {
+                return { kind: "error", message: "--epic-run-id requires a value" };
+            }
+            if (raw.trim().length === 0) {
+                return { kind: "error", message: "--epic-run-id requires a non-blank value" };
+            }
+            epicRunIds.push(raw.trim());
+            continue;
+        }
+        // BAPI-1102 — private, and accepted ONLY on the detached-runtime action, so
+        // it cannot appear on a public `plane up`. It selects the two-phase
+        // lifecycle; the claim scope then arrives through the manifest, which is why
+        // the scope requirement below is lifted for it.
+        if (arg === PLANE_RUNTIME_TWO_PHASE_FLAG && action === PLANE_RUNTIME_ACTION) {
+            if (twoPhase) {
+                return {
+                    kind: "error",
+                    message: `${PLANE_RUNTIME_TWO_PHASE_FLAG} may be supplied only once`,
+                };
+            }
+            twoPhase = true;
+            continue;
+        }
+        if (arg === "--repo-wide") {
+            if (repoWide) {
+                return { kind: "error", message: "--repo-wide may be supplied only once" };
+            }
+            repoWide = true;
+            continue;
+        }
         if (arg === "--executors") {
             if (executors !== null) {
                 return { kind: "error", message: "--executors may be supplied only once" };
@@ -99,7 +140,43 @@ export function parsePlaneArgs(argv) {
         }
         return { kind: "error", message: `unexpected argument '${arg}' for \`plane ${action}\`` };
     }
-    const options = { executors: executors ?? PLANE_DEFAULT_EXECUTORS };
+    const resolvedExecutors = executors ?? PLANE_DEFAULT_EXECUTORS;
+    // BAPI-1102 — the claim-scope rule, enforced through the EXECUTOR's own shared
+    // validator and rendered with the executor's own wording. Refusing here, in the
+    // pure parser, is what makes "a lane is never spawned unscoped" structural: the
+    // coordinator below cannot touch the filesystem, open a socket, resolve a
+    // credential, or spawn a child until this function has returned an `up`.
+    //
+    // Spawning the lanes anyway would be the worse failure and is the one this
+    // replaces: since BAPI-1026 an unscoped executor exits at startup, so `plane up`
+    // would report a member that "failed to start" and roll the whole plane back —
+    // a confusing, expensive way to say "you forgot a flag".
+    //
+    // A public `plane up` always resolves to at least one lane (`--executors` has a
+    // floor of 1 and no `--executors 0` exists), so the scope is effectively
+    // mandatory here. The zero-lane control-plane phase is INTERNAL and never
+    // reaches this parser.
+    // BAPI-1102 — the two-phase runtime is the ONE invocation that legitimately
+    // carries no scope in its argv: it has not been told which run it serves yet,
+    // and will read the scope from the manifest once the composed caller records
+    // it. Every other path resolves to at least one lane and must be scoped.
+    if (twoPhase) {
+        if (epicRunIds.length > 0 || repoWide) {
+            return {
+                kind: "error",
+                message: `${PLANE_RUNTIME_TWO_PHASE_FLAG} takes its claim scope from the manifest, not from argv`,
+            };
+        }
+        return { kind: "runtime", options: { executors: resolvedExecutors, twoPhase: true } };
+    }
+    const scope = validateExecutorClaimScope({ epicRunIds, repoWide });
+    if (!scope.ok) {
+        return { kind: "error", message: scope.message };
+    }
+    const options = {
+        executors: resolvedExecutors,
+        claimScope: scope.scope,
+    };
     return action === "up" ? { kind: "up", options } : { kind: "runtime", options };
 }
 /**
@@ -138,8 +215,14 @@ export function getPlaneUsage() {
         "is already live, or to recover after a composed bring-up reported a live plane it",
         "did not wind down. Nothing about this command's behavior has changed.",
         "",
+        "Every executor lane needs a CLAIM SCOPE, and `plane up` refuses without one",
+        "(BAPI-1026): an executor started with no scope exits immediately, so spawning",
+        "lanes unscoped would report a member crash instead of a missing flag. Pass",
+        "--epic-run-id <id> (repeatable) to serve specific runs, or --repo-wide.",
+        "",
         "Actions:",
-        "  plane up [--executors N]   Preflight, then start the plane. Refuses as a",
+        "  plane up <scope> [--executors N]",
+        "                             Preflight, then start the plane. Refuses as a",
         "                             whole if any spawn-blocking check fails.",
         "  plane status               Read the manifest and report each member's state.",
         "  plane down                 Stop the bound server-side epic run FIRST (BAPI-872),",
@@ -150,6 +233,11 @@ export function getPlaneUsage() {
         "",
         "Options:",
         `  --executors N              Executor lanes to start (default ${PLANE_DEFAULT_EXECUTORS}, max ${PLANE_MAX_EXECUTORS}).`,
+        "  --epic-run-id <id>         Claim scope: serve this epic run. REPEATABLE, and",
+        "                             every id is passed to every lane in the order given.",
+        "                             Mutually exclusive with --repo-wide.",
+        "  --repo-wide                Claim scope: deliberately claim repository-wide.",
+        "                             Mutually exclusive with --epic-run-id.",
         "  -h, --help                 Show this help.",
         "",
         "Behavior you can rely on:",
@@ -166,6 +254,11 @@ export function getPlaneUsage() {
         "  * The reconciler worker is not reported ready until it has published a FRESH",
         "    durable heartbeat, read back through GET /automation/health. `plane up`",
         "    cannot print a success banner over a reconciler that never ticked.",
+        "  * Executor lanes start SCOPED. Every lane is spawned with the claim scope you",
+        "    passed, and each is gated on its OWN per-instance heartbeat, so a lane that",
+        "    exits on a rejected credential or an unbuilt bundle is never reported ready.",
+        "  * The observer starts LAST, after every executor lane's gate has closed, so",
+        "    its first sweep cannot alert on lanes that have not published yet.",
         "",
         `Runtime artifacts (manifest + per-member logs) live under ${PLANE_RUNTIME_DIR}/.`,
     ].join("\n");
@@ -230,9 +323,9 @@ export async function runPlaneCli(argv, overrides = {}) {
             case "down":
                 return await runDownAction(sinks, overrides);
             case "up":
-                return await runUpAction(parsed.options.executors, sinks, overrides);
+                return await runUpAction(parsed.options, sinks, overrides);
             case "runtime":
-                return await runRuntimeAction(parsed.options.executors, overrides);
+                return await runRuntimeAction(parsed.options, overrides);
             // Dispatched here, ahead of every action that touches the repository, so
             // the diagnostic answers from an empty directory with no credentials.
             case "entrypoint":
@@ -344,7 +437,8 @@ async function stopBoundEpicRun(epicRunId, manifest) {
         };
     }
 }
-async function runUpAction(executors, sinks, overrides) {
+async function runUpAction(options, sinks, overrides) {
+    const executors = options.executors;
     const repoRoot = overrides.cwd ?? process.cwd();
     const env = overrides.env ?? process.env;
     const preflight = overrides.preflight
@@ -354,19 +448,20 @@ async function runUpAction(executors, sinks, overrides) {
         sinks.stdout(formatDiagnostic(diagnostic));
     }
     if (!preflight.ok) {
-        sinks.stderr("");
-        sinks.stderr("plane up REFUSED — preflight found blocking problems:");
-        for (const diagnostic of preflight.diagnostics.filter((d) => d.severity === "blocking")) {
-            sinks.stderr(formatDiagnostic(diagnostic));
-        }
-        sinks.stderr("");
-        sinks.stderr(`Fix every item above and retry. ${PLANE_NOTHING_STARTED}.`);
+        for (const line of formatPlanePreflightRefusal(preflight))
+            sinks.stderr(line);
         return 1;
     }
     const planeId = (overrides.newPlaneId ?? randomUUID)();
+    // Public `plane up` sequences BOTH phases in one invocation and stays attached
+    // for the plane's lifetime, exactly as it always has. The two-phase lifecycle
+    // is what the COMPOSED caller needs, not what a hand-run `plane up` needs, and
+    // giving the public command a second shape would make the manual recovery path
+    // behave differently from the one operators already know.
+    const launchOptions = { ...(options.claimScope ? { claimScope: options.claimScope } : {}) };
     const launch = overrides.launch
-        ? await overrides.launch(preflight, executors)
-        : await launchPlane(preflight, executors, planeId, sinks, env);
+        ? await overrides.launch(preflight, executors, launchOptions)
+        : await launchPlane(preflight, executors, planeId, sinks, env, launchOptions);
     if (!launch.ok) {
         for (const line of formatPlaneLaunchFailure(launch))
             sinks.stderr(line);
@@ -374,6 +469,24 @@ async function runUpAction(executors, sinks, overrides) {
     }
     return launch.exitCode;
 }
+/**
+ * The aggregate preflight refusal, as lines.
+ *
+ * Extracted by BAPI-1102 so the composed control-plane launch renders the SAME
+ * refusal `plane up` does. A second rendering would have been the fourth place
+ * in this flow where two paths report the same blocking check differently.
+ */
+export function formatPlanePreflightRefusal(preflight) {
+    return [
+        "",
+        "plane up REFUSED — preflight found blocking problems:",
+        ...preflight.diagnostics
+            .filter((d) => d.severity === "blocking")
+            .map((d) => formatDiagnostic(d)),
+        "",
+        `Fix every item above and retry. ${PLANE_NOTHING_STARTED}.`,
+    ];
+}
 /** Stable label so a startup death is greppable in a terminal scrollback. */
 export const PLANE_STARTUP_FAILED = "plane up FAILED — the runtime never came up";
 /**
@@ -416,17 +529,24 @@ export function formatPlaneLaunchFailure(launch) {
     return lines;
 }
 /** Claim the manifest, print the banner, then run the detached supervisor. */
-async function launchPlane(preflight, executors, planeId, sinks, env) {
+async function launchPlane(preflight, executors, planeId, sinks, env, launchOptions = {}) {
     const fs = createPlaneFsDeps();
     const clock = createPlaneClock();
     const context = preflight.context;
     const nodeExecutable = resolveNodeExecutable();
-    const roster = buildPlaneMemberRoster({
-        context,
-        executors,
-        parentEnv: env,
-        nodeExecutable,
-    });
+    // BAPI-1102 — in two-phase mode the manifest is claimed listing only the
+    // CONTROL-PLANE members. Listing lanes that have not been asked to start would
+    // make `plane status` report members that do not exist, and `plane down` would
+    // have nothing to signal for them.
+    const roster = launchOptions.twoPhase
+        ? buildPlaneControlPlaneRoster({ context, parentEnv: env, nodeExecutable })
+        : buildPlaneMemberRoster({
+            context,
+            executors,
+            parentEnv: env,
+            nodeExecutable,
+            ...(launchOptions.claimScope ? { claimScope: launchOptions.claimScope } : {}),
+        });
     const timestamp = clock.now().toISOString();
     const claim = await claimPlaneManifest({
         manifest: {
@@ -455,7 +575,13 @@ async function launchPlane(preflight, executors, planeId, sinks, env) {
     // report — `startup: null` is the honest shape, not a placeholder.
     if (!claim.ok)
         return { ok: false, error: claim.message, startup: null };
-    return launchPlaneSupervisor({ context, manifest: claim.manifest, executors }, {
+    return launchPlaneSupervisor({
+        context,
+        manifest: claim.manifest,
+        executors,
+        ...(launchOptions.claimScope ? { claimScope: launchOptions.claimScope } : {}),
+        ...(launchOptions.twoPhase ? { twoPhase: true } : {}),
+    }, {
         fs,
         clock,
         spawn: createPlaneSpawn(),
@@ -470,10 +596,19 @@ async function launchPlane(preflight, executors, planeId, sinks, env) {
         // The banner is now a consequence of the runtime's readiness handshake
         // rather than of the launcher reaching the end of its own function. That
         // is the whole point: `spawn()` succeeding never meant the plane was up.
-        onReady: ({ supervisorPid, supervisorPgid }) => printStartupBanner(sinks, context, roster.length, executors, {
-            supervisorPid,
-            supervisorPgid,
-        }),
+        //
+        // In two-phase mode the member count is not known until the lanes are
+        // requested, so the banner reports the count the plane ENDED with.
+        onReady: ({ supervisorPid, supervisorPgid }) => {
+            printStartupBanner(sinks, context, launchOptions.twoPhase ? roster.length + executors + 1 : roster.length, executors, { supervisorPid, supervisorPgid });
+            launchOptions.onPlaneReady?.({ planeId });
+        },
+        ...(launchOptions.onControlPlaneReady
+            ? { onControlPlaneReady: () => launchOptions.onControlPlaneReady?.({ planeId }) }
+            : {}),
+        ...(launchOptions.onLanesFailed
+            ? { onLanesFailed: () => launchOptions.onLanesFailed?.({ planeId }) }
+            : {}),
     });
 }
 function printStartupBanner(sinks, context, memberCount, executors, launch) {
@@ -490,8 +625,107 @@ function printStartupBanner(sinks, context, memberCount, executors, launch) {
     sinks.stdout("  crash policy members are NOT restarted; a member exit is reported loudly.");
     sinks.stdout("");
 }
+/**
+ * Start the control plane (server + reconciler) and RESOLVE WHEN IT IS READY.
+ *
+ * The composed caller needs the server up so it can create a run, and needs
+ * control back to do it. Both phases still run inside the one detached runtime;
+ * this only waits for the first.
+ *
+ * Preflight is INJECTED rather than re-run, so the port that was probed is the
+ * port that gets launched and the composed caller's refusal and this launch can
+ * never disagree about the world.
+ */
+export async function launchPlaneControlPlane(args) {
+    if (!args.preflight.ok) {
+        return { ok: false, lines: formatPlanePreflightRefusal(args.preflight) };
+    }
+    const preflight = args.preflight;
+    const planeId = (args.newPlaneId ?? randomUUID)();
+    let signalControlReady;
+    const controlReady = new Promise((resolve) => {
+        signalControlReady = resolve;
+    });
+    let signalPlaneReady;
+    const planeReady = new Promise((resolve) => {
+        signalPlaneReady = resolve;
+    });
+    // BAPI-1102 — the held-failure signal. Raced alongside readiness and the
+    // runtime's lifetime because the held path resolves NEITHER of those: the
+    // plane never goes ready and the runtime never exits, so without this the
+    // caller would wait on a plane that is alive and never going to start a lane.
+    let signalLanesFailed;
+    const lanesFailed = new Promise((resolve) => {
+        signalLanesFailed = resolve;
+    });
+    const lifetime = launchPlane(preflight, args.executors, planeId, args.sinks, args.env, {
+        twoPhase: true,
+        onControlPlaneReady: () => signalControlReady?.(),
+        onPlaneReady: () => signalPlaneReady?.(),
+        onLanesFailed: () => signalLanesFailed?.(),
+    });
+    // Whichever comes first: the control plane going ready, or the launch failing.
+    // Racing them is what turns a runtime that died during phase one into a
+    // refusal instead of a hang — the ready callback would simply never fire.
+    const outcome = await Promise.race([
+        controlReady.then(() => ({ kind: "ready" })),
+        lifetime.then((result) => ({ kind: "settled", result })),
+    ]);
+    if (outcome.kind === "settled") {
+        // Settled before ready ⇒ it never came up. A successful settle here would
+        // mean a plane that went up and down before reporting readiness, which is
+        // still not a plane the caller can create a run against.
+        const lines = outcome.result.ok
+            ? ["plane up FAILED: the runtime exited before the control plane was ready"]
+            : formatPlaneLaunchFailure(outcome.result);
+        return { ok: false, lines };
+    }
+    return {
+        ok: true,
+        planeId,
+        lifetime,
+        awaitPlaneReady: async () => {
+            const settled = await Promise.race([
+                planeReady.then(() => ({ kind: "ready" })),
+                lanesFailed.then(() => ({ kind: "held" })),
+                lifetime.then((result) => ({ kind: "settled", result })),
+            ]);
+            if (settled.kind === "ready")
+                return { ok: true };
+            if (settled.kind === "held") {
+                // The runtime already wrote the operator-facing explanation to stderr as
+                // it happened, and it is STILL RUNNING. Repeating its text here would
+                // print the same paragraph twice; the caller adds only what it alone
+                // knows — what became of the run.
+                return {
+                    ok: false,
+                    lines: ["the plane's executor lanes did not start; its control plane is still running"],
+                };
+            }
+            return {
+                ok: false,
+                lines: settled.result.ok
+                    ? ["the plane runtime exited before its executor lanes became ready"]
+                    : formatPlaneLaunchFailure(settled.result),
+            };
+        },
+    };
+}
+/**
+ * Request phase two: bind the run and record the scope its lanes will use.
+ *
+ * Writes the request into the manifest and returns. The DETACHED RUNTIME
+ * performs the spawn and the readiness gating — this process may well have
+ * exited by then, which is precisely why the request is durable state rather
+ * than a function call.
+ */
+export async function requestPlaneScopedLanes(args) {
+    const result = await requestPlaneManifestLanes(args.repoRoot, args.planeId, args.epicRunId, args.claimScope, createPlaneFsDeps());
+    return result.ok ? { ok: true } : { ok: false, reason: result.reason, message: result.message };
+}
 /** The private detached-runtime action. Never part of the documented surface. */
-async function runRuntimeAction(executors, overrides) {
+async function runRuntimeAction(options, overrides) {
+    const executors = options.executors;
     const repoRoot = overrides.cwd ?? process.cwd();
     if (overrides.runtime)
         return overrides.runtime(repoRoot, executors);
@@ -533,12 +767,19 @@ async function runRuntimeAction(executors, overrides) {
         sinks.stderr(`${PLANE_NOTHING_STARTED}.`);
         return 1;
     }
-    const roster = buildPlaneMemberRoster({
-        context: preflight.context,
-        executors,
-        parentEnv: env,
-        nodeExecutable: resolveNodeExecutable(),
-    });
+    const nodeExecutable = resolveNodeExecutable();
+    const rosterBase = { context: preflight.context, parentEnv: env, nodeExecutable };
+    // BAPI-1102 — in two-phase mode the runtime is handed the CONTROL-PLANE roster
+    // and the two builders it will need later, rather than a finished roster it
+    // cannot build yet: the lane roster depends on a claim scope that does not
+    // exist until the run does.
+    const roster = options.twoPhase
+        ? buildPlaneControlPlaneRoster(rosterBase)
+        : buildPlaneMemberRoster({
+            ...rosterBase,
+            executors,
+            ...(options.claimScope ? { claimScope: options.claimScope } : {}),
+        });
     const result = await runPlaneRuntime(repoRoot, roster, {
         fs: createPlaneFsDeps(),
         clock: createPlaneClock(),
@@ -560,6 +801,14 @@ async function runRuntimeAction(executors, overrides) {
         hostname: resolveHostname,
         selfPid: process.pid,
         planeId,
+        ...(options.twoPhase
+            ? {
+                twoPhase: {
+                    buildLaneRoster: (scope) => buildPlaneExecutorLaneRoster({ ...rosterBase, executors, claimScope: scope }),
+                    observerRoster: buildPlaneObserverRoster(rosterBase),
+                },
+            }
+            : {}),
     });
     return result.exitCode;
 }