@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/plane/supervisor.js

@@ -25,11 +25,12 @@
  * mystery.
  */
 import path from "path";
-import { PLANE_ID_ENV_VAR, PLANE_RUNTIME_LOG_FILENAME, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
-import { getPlanePaths, readPlaneManifest, writePlaneManifest } from "./manifest.js";
+import { PLANE_ID_ENV_VAR, PLANE_RUNTIME_ACTION, PLANE_RUNTIME_LOG_FILENAME, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
+import { appendPlaneManifestMembers, getPlanePaths, planeManifestLifecycle, readPlaneManifest, transitionPlaneManifestLifecycle, writePlaneManifest, } from "./manifest.js";
+import { executorClaimScopeArgs, } from "../executor/claim-scope.js";
 import { attachMemberOutput, openMemberLog, openPlaneRuntimeLog, writeMemberStartupFailure, writeRuntimeTraceLine, PLANE_MEMBER_STARTUP_FAILURES, PLANE_SUPERVISOR_LOG_PREFIX, } from "./member-logs.js";
 import { absoluteLogPath, describePlaneMember } from "./member-roster.js";
-import { shutdownPlane } from "./shutdown.js";
+import { PLANE_SHUTDOWN_GRACE_MS, PLANE_SHUTDOWN_KILL_WAIT_MS, PLANE_SHUTDOWN_POLL_MS, shutdownPlane, } from "./shutdown.js";
 /** How long the runtime waits for the launcher to record its pid. */
 export const PLANE_HANDSHAKE_TIMEOUT_MS = 10_000;
 /** Handshake poll interval. */
@@ -178,7 +179,7 @@ export function reportMemberCrash(sinks, report) {
  * rather than a per-field judgement call.
  */
 export async function launchPlaneSupervisor(params, deps) {
-    const { context, manifest, executors } = params;
+    const { context, manifest, executors, claimScope, twoPhase } = params;
     const paths = getPlanePaths(context.repoRoot);
     const tracePath = path.join(paths.planeDir, PLANE_RUNTIME_LOG_FILENAME);
     // BAPI-778: the subscription OAuth token is a bearer secret of the same class as
@@ -218,7 +219,18 @@ export async function launchPlaneSupervisor(params, deps) {
     runtimeEnv.BAPI_API_KEY = context.bridgeApiKey;
     let child;
     try {
-        child = deps.spawn(deps.nodeExecutable, [deps.entrypoint, "plane", "__runtime", "--executors", String(executors)], { cwd: context.repoRoot, env: runtimeEnv, detached: true });
+        child = deps.spawn(deps.nodeExecutable, [
+            deps.entrypoint,
+            "plane",
+            PLANE_RUNTIME_ACTION,
+            "--executors",
+            String(executors),
+            // BAPI-1102. In two-phase mode the scope is absent here and arrives
+            // through the manifest instead — the runtime is told WHICH lifecycle to
+            // run, and the lifecycle decides where the scope comes from.
+            ...(twoPhase ? [PLANE_RUNTIME_TWO_PHASE_FLAG] : []),
+            ...(claimScope ? executorClaimScopeArgs(claimScope) : []),
+        ], { cwd: context.repoRoot, env: runtimeEnv, detached: true });
     }
     catch {
         // Fixed prose only. The thrown value can carry the spawn's argv and env,
@@ -249,7 +261,18 @@ export async function launchPlaneSupervisor(params, deps) {
     // The runtime's stdout feed is the operator's view of the plane. It is
     // streamed through rather than teed: per-member detail already lives in the
     // member logs, and this channel carries only attributed events and banners.
+    let controlReadyAnnounced = false;
+    let lanesFailedAnnounced = false;
     const readStdout = createLineReader((line) => {
+        if (line === PLANE_CONTROL_READY_MARKER) {
+            // Private, exactly like the ready marker: forwarding it would put an
+            // internal token in the operator's terminal.
+            if (!controlReadyAnnounced) {
+                controlReadyAnnounced = true;
+                deps.onControlPlaneReady?.({ supervisorPid, supervisorPgid: supervisorPid });
+            }
+            return;
+        }
         if (line === PLANE_READY_MARKER) {
             // Private. Forwarding it would put an internal token in the operator's
             // terminal and, worse, invite something downstream to parse for it.
@@ -259,6 +282,16 @@ export async function launchPlaneSupervisor(params, deps) {
             }
             return;
         }
+        if (line === PLANE_LANES_FAILED_MARKER) {
+            // Private, like the other two. The operator-facing explanation was already
+            // written to stderr by the runtime, so this token carries no text of its
+            // own — only the fact, to whoever is waiting on it.
+            if (!lanesFailedAnnounced) {
+                lanesFailedAnnounced = true;
+                deps.onLanesFailed?.({ supervisorPid, supervisorPgid: supervisorPid });
+            }
+            return;
+        }
         deps.sinks.stdout(line);
     });
     const readStderr = createLineReader((line) => {
@@ -353,6 +386,37 @@ export async function launchPlaneSupervisor(params, deps) {
         exitCode: outcome.code ?? 0,
     };
 }
+/**
+ * Emitted on stdout the moment the CONTROL PLANE is ready (BAPI-1102).
+ *
+ * A second private marker beside {@link PLANE_READY_MARKER}, for the same reason
+ * that one exists: the launcher needs to know a phase completed, and the only
+ * channel to a detached child is its stdout. Never forwarded to the operator's
+ * terminal.
+ */
+export const PLANE_CONTROL_READY_MARKER = "__bapi_plane_control_ready__";
+/**
+ * Phase two failed and the control plane was HELD (BAPI-1102).
+ *
+ * The third private marker, and the only one that reports a failure. It exists
+ * because the held path is the one bring-up outcome that neither reaches
+ * {@link PLANE_READY_MARKER} nor ends the runtime process: a launcher racing
+ * "ready" against "the runtime exited" would wait forever on a plane that is
+ * alive, serving a committed run, and never going to start a lane.
+ */
+export const PLANE_LANES_FAILED_MARKER = "__bapi_plane_lanes_failed__";
+/**
+ * Private argv flag selecting the two-phase lifecycle on `plane __runtime`.
+ *
+ * Never part of the documented surface, exactly like the action it modifies:
+ * the two-phase lifecycle is composed by `drive-epic`, and an operator running
+ * `plane up` by hand wants the single-phase bring-up they already know.
+ */
+export const PLANE_RUNTIME_TWO_PHASE_FLAG = "--two-phase";
+/** Default poll interval while waiting for a phase-two request. */
+export const PLANE_PHASE_REQUEST_POLL_MS = 250;
+/** Default bound on the phase-two wait. */
+export const PLANE_PHASE_REQUEST_TIMEOUT_MS = 15 * 60_000;
 /**
  * The detached supervisor loop: adopt the manifest, spawn the roster, watch it,
  * and wind down on a signal.
@@ -365,19 +429,37 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
     const adopted = await awaitManifestOwnership(repoRoot, deps);
     if (!adopted.ok)
         return { ok: false, error: adopted.error, exitCode: 1 };
+    /** One member's initial manifest record: listed, not yet spawned. */
+    const pendingMember = (spec) => ({
+        name: spec.name,
+        pid: null,
+        state: "spawning",
+        exitCode: null,
+        exitSignal: null,
+        logPath: spec.logPath,
+    });
     let manifest = {
         ...adopted.manifest,
-        members: roster.map((spec) => ({
-            name: spec.name,
-            pid: null,
-            state: "spawning",
-            exitCode: null,
-            exitSignal: null,
-            logPath: spec.logPath,
-        })),
+        // In two-phase mode `roster` is the CONTROL-PLANE cohort; later cohorts are
+        // appended as each phase begins, so `plane status` and `plane down` never
+        // list a member that has not been asked to start.
+        members: roster.map(pendingMember),
+        ...(deps.twoPhase ? { lifecycle: "control-plane-starting" } : {}),
         updatedAt: deps.clock.now().toISOString(),
     };
     const started = [];
+    /**
+     * Has {@link PLANE_CONTROL_READY_MARKER} been announced? (BAPI-1102)
+     *
+     * The single boundary between "roll the whole plane back" and "hold the
+     * control plane and stop only what phase two started". It flips at the
+     * announcement rather than at the manifest transition, because the
+     * announcement is what lets the composed caller go create a run — before it,
+     * nothing outside this process can depend on the plane existing.
+     */
+    let phaseTwoBegun = false;
+    /** Members started by phase two: the ONLY cohort a held failure tears down. */
+    const phaseTwoMembers = [];
     // ---- Serialized manifest persistence (BAPI-950) --------------------------
     //
     // `writePlaneManifest` publishes through a temporary file and an atomic
@@ -481,175 +563,381 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
             selfPid: deps.selfPid,
         });
     };
-    // ---- Spawn the roster in order -----------------------------------------
-    for (const spec of roster) {
-        const absoluteLog = absoluteLogPath(repoRoot, spec);
-        const opened = openMemberLog(spec.name, paths.planeDir, absoluteLog, deps.log);
-        if (!opened.ok) {
-            return finishPartialStart(spec.name, `log could not be opened (${opened.error})`);
-        }
-        // Probed BEFORE the spawn, for every heartbeat-gated member (BAPI-1036;
-        // BAPI-1029 took one such probe, for the reconciler only, and used it merely
-        // to disclose an ambiguity). The baseline is what turns "a fresh heartbeat
-        // exists" into "a heartbeat landed after we started this process" — see
-        // `PlaneHeartbeatBaseline`.
-        //
-        // Taken AFTER the member's log is opened, so a terminal baseline failure is
-        // annotated in the log an operator will actually open for that member —
-        // still before the spawn, which is the property that matters.
-        //
-        // An executor lane is scoped here by the identity the roster already minted;
-        // the reconciler's local identity needs a pid, so its pre-spawn baseline is
-        // the UNSCOPED observation, which is a sound lower bound: the unscoped read
-        // returns the newest row across the deployment, so any row this member later
-        // publishes must be at least as new. A `DYNO` deployment scopes exactly,
-        // because that identity needs no pid.
-        let baseline = { observedAtMs: null };
-        let baselineElapsedMs = 0;
-        if (spec.readiness?.kind === "process-heartbeat") {
-            const readiness = spec.readiness;
-            const baselineInstanceId = readiness.instanceId ?? resolveMemberInstanceId(spec.env, 0, undefined);
-            const outcome = await probeHeartbeatBaseline({
-                deps,
-                spec,
-                readiness,
-                instanceId: baselineInstanceId,
-            });
-            if (outcome.kind === "failed") {
-                // Terminal before the spawn: a rejected credential or a moved contract
-                // cannot be waited out, and starting the member first would leave a live
-                // process to roll back for no reason.
-                return finishPartialStart(spec.name, describeBaselineFailure(outcome.reason), {
-                    log: opened.stream,
-                    failure: PLANE_MEMBER_STARTUP_FAILURES.readinessUnestablished,
-                });
-            }
-            baseline = outcome.baseline;
-            baselineElapsedMs = outcome.elapsedMs;
+    /**
+     * Members phase two stopped on purpose, so their exits are not reported as
+     * crashes. Per-member rather than the plane-wide `shuttingDown` flag: the
+     * control plane stays up and a genuine crash of ITS members must still be
+     * reported after this.
+     */
+    const intentionallyStopped = new Set();
+    /**
+     * Stop exactly the cohort phase two started, and nothing else (BAPI-1102).
+     *
+     * SIGTERM, a grace window on the injected clock, then SIGKILL for whatever is
+     * still alive — the same escalation `shutdownPlane` uses, applied to a subset
+     * rather than to the plane. It deliberately does NOT touch the manifest's
+     * ownership, the supervisor, the server, or the reconciler: the whole point of
+     * the held path is that those survive.
+     *
+     * Liveness is read from the members' own `close` handlers, which is what makes
+     * this correct without retaining child handles: the handler patches
+     * `state: "exited"` on the manifest projection, and that projection is the one
+     * record of member lifecycle everything else here reads.
+     */
+    const stopPhaseTwoCohort = async () => {
+        const outstanding = () => manifest.members.filter((m) => phaseTwoMembers.includes(m.name) && m.pid !== null && m.state !== "exited");
+        const targets = outstanding();
+        if (targets.length === 0)
+            return;
+        for (const m of targets)
+            intentionallyStopped.add(m.name);
+        deps.sinks.stderr(`Stopping ${targets.length} executor-lane member(s) started by this phase. ` +
+            "The control plane is NOT being rolled back.");
+        for (const m of targets) {
+            if (m.pid !== null)
+                deps.proc.signal(m.pid, "SIGTERM");
         }
-        let child;
-        try {
-            child = deps.spawn(spec.command, spec.args, {
-                cwd: spec.cwd,
-                env: spec.env,
-                // Members stay in the RUNTIME's process group, which is what makes one
-                // group signal reach the whole plane.
-                detached: false,
-            });
+        let waited = 0;
+        while (waited < PLANE_SHUTDOWN_GRACE_MS && outstanding().length > 0) {
+            await deps.clock.sleep(PLANE_SHUTDOWN_POLL_MS);
+            waited += PLANE_SHUTDOWN_POLL_MS;
         }
-        catch {
-            return finishPartialStart(spec.name, PLANE_MEMBER_STARTUP_FAILURES.spawnThrew, {
-                log: opened.stream,
-                failure: PLANE_MEMBER_STARTUP_FAILURES.spawnThrew,
-            });
+        const survivors = outstanding();
+        for (const m of survivors) {
+            if (m.pid !== null)
+                deps.proc.signal(m.pid, "SIGKILL");
         }
-        if (child.pid === null || child.pid === undefined) {
-            return finishPartialStart(spec.name, PLANE_MEMBER_STARTUP_FAILURES.noPid, {
-                log: opened.stream,
-                failure: PLANE_MEMBER_STARTUP_FAILURES.noPid,
-            });
+        if (survivors.length > 0) {
+            let killWaited = 0;
+            while (killWaited < PLANE_SHUTDOWN_KILL_WAIT_MS && outstanding().length > 0) {
+                await deps.clock.sleep(PLANE_SHUTDOWN_POLL_MS);
+                killWaited += PLANE_SHUTDOWN_POLL_MS;
+            }
+        }
+        const stubborn = outstanding();
+        if (stubborn.length > 0) {
+            deps.sinks.stderr(`${stubborn.length} executor-lane member(s) did not exit: ` +
+                `${stubborn.map((m) => `${m.name} (pid ${m.pid})`).join(", ")}. ` +
+                "They are still recorded in the manifest and `plane down` will reach them.");
         }
-        attachMemberOutput({ stdout: child.stdout, stderr: child.stderr }, opened.stream);
-        started.push(spec.name);
-        patchMember(spec.name, { pid: child.pid, state: "running" });
         await persist();
-        emitMemberEvent(deps.sinks, {
-            member: spec.name,
-            kind: "start",
-            timestamp: deps.clock.now().toISOString(),
-            logPath: spec.logPath,
-            detail: describePlaneMember(spec),
-        });
-        // Exit watching is registered BEFORE readiness so a member that dies during
-        // its readiness window is reported as a crash rather than as a silent
-        // readiness timeout.
-        child.on("close", ((code, signal) => {
-            const timestamp = deps.clock.now().toISOString();
-            patchMember(spec.name, { state: "exited", exitCode: code, exitSignal: signal });
-            // Enrolled synchronously so simultaneous exits queue in the order their
-            // patches were applied, and tracked so the write is awaited — never
-            // abandoned — before the runtime returns.
-            trackPersist(persist());
+    };
+    /** Record the terminal held phase, best-effort. */
+    const recordLanesFailed = async () => {
+        const current = manifest.lifecycle ?? "ready";
+        const written = await transitionPlaneManifestLifecycle(repoRoot, deps.planeId, current, "lanes-failed", deps.fs);
+        // Best-effort on purpose: the phase is how `plane status` describes a held
+        // plane, not a fact anything decides on. A manifest that cannot be written
+        // is already the subject of its own reported failure, and turning that into
+        // a second one would bury the first.
+        if (written.ok) {
+            manifest = { ...written.manifest, members: manifest.members };
+            await persist();
+        }
+        else {
+            deps.sinks.stderr(`The held plane's lifecycle could not be recorded (${written.reason}); ` +
+                "`plane status` may still describe it as starting lanes.");
+        }
+    };
+    // ---- Spawn one cohort of members, in order ------------------------------
+    //
+    // BAPI-1102 extracted this from a single top-level loop so the two-phase
+    // lifecycle can run it three times — control plane, scoped lanes, observer —
+    // against the SAME closure state. Every property the single pass had is
+    // preserved by construction rather than re-established: one `started` list, one
+    // serialized manifest writer, one rollback, one set of member events.
+    //
+    // Returns `null` on success, or the terminal failure result. A cohort failure
+    // rolls back EVERY member started so far, across all cohorts, which is the
+    // behavior a partially-started plane needs and the reason `started` is shared.
+    const startMembers = async (cohort) => {
+        for (const spec of cohort) {
+            const absoluteLog = absoluteLogPath(repoRoot, spec);
+            const opened = openMemberLog(spec.name, paths.planeDir, absoluteLog, deps.log);
+            if (!opened.ok) {
+                return finishPartialStart(spec.name, `log could not be opened (${opened.error})`);
+            }
+            // Probed BEFORE the spawn, for every heartbeat-gated member (BAPI-1036;
+            // BAPI-1029 took one such probe, for the reconciler only, and used it merely
+            // to disclose an ambiguity). The baseline is what turns "a fresh heartbeat
+            // exists" into "a heartbeat landed after we started this process" — see
+            // `PlaneHeartbeatBaseline`.
+            //
+            // Taken AFTER the member's log is opened, so a terminal baseline failure is
+            // annotated in the log an operator will actually open for that member —
+            // still before the spawn, which is the property that matters.
+            //
+            // An executor lane is scoped here by the identity the roster already minted;
+            // the reconciler's local identity needs a pid, so its pre-spawn baseline is
+            // the UNSCOPED observation, which is a sound lower bound: the unscoped read
+            // returns the newest row across the deployment, so any row this member later
+            // publishes must be at least as new. A `DYNO` deployment scopes exactly,
+            // because that identity needs no pid.
+            let baseline = { observedAtMs: null };
+            let baselineElapsedMs = 0;
+            if (spec.readiness?.kind === "process-heartbeat") {
+                const readiness = spec.readiness;
+                const baselineInstanceId = readiness.instanceId ?? resolveMemberInstanceId(spec.env, 0, undefined);
+                const outcome = await probeHeartbeatBaseline({
+                    deps,
+                    spec,
+                    readiness,
+                    instanceId: baselineInstanceId,
+                });
+                if (outcome.kind === "failed") {
+                    // Terminal before the spawn: a rejected credential or a moved contract
+                    // cannot be waited out, and starting the member first would leave a live
+                    // process to roll back for no reason.
+                    return finishPartialStart(spec.name, describeBaselineFailure(outcome.reason), {
+                        log: opened.stream,
+                        failure: PLANE_MEMBER_STARTUP_FAILURES.readinessUnestablished,
+                    });
+                }
+                baseline = outcome.baseline;
+                baselineElapsedMs = outcome.elapsedMs;
+            }
+            let child;
+            try {
+                child = deps.spawn(spec.command, spec.args, {
+                    cwd: spec.cwd,
+                    env: spec.env,
+                    // Members stay in the RUNTIME's process group, which is what makes one
+                    // group signal reach the whole plane.
+                    detached: false,
+                });
+            }
+            catch {
+                return finishPartialStart(spec.name, PLANE_MEMBER_STARTUP_FAILURES.spawnThrew, {
+                    log: opened.stream,
+                    failure: PLANE_MEMBER_STARTUP_FAILURES.spawnThrew,
+                });
+            }
+            if (child.pid === null || child.pid === undefined) {
+                return finishPartialStart(spec.name, PLANE_MEMBER_STARTUP_FAILURES.noPid, {
+                    log: opened.stream,
+                    failure: PLANE_MEMBER_STARTUP_FAILURES.noPid,
+                });
+            }
+            attachMemberOutput({ stdout: child.stdout, stderr: child.stderr }, opened.stream);
+            started.push(spec.name);
+            // Ledgered separately so a held failure can stop exactly this cohort and
+            // leave the control plane running (BAPI-1102).
+            if (phaseTwoBegun)
+                phaseTwoMembers.push(spec.name);
+            patchMember(spec.name, { pid: child.pid, state: "running" });
+            await persist();
             emitMemberEvent(deps.sinks, {
                 member: spec.name,
-                kind: "exit",
-                timestamp,
+                kind: "start",
+                timestamp: deps.clock.now().toISOString(),
                 logPath: spec.logPath,
-                detail: signal !== null ? `signal ${signal}` : `code ${code ?? "unknown"}`,
+                detail: describePlaneMember(spec),
             });
-            if (!shuttingDown) {
-                reportMemberCrash(deps.sinks, {
+            // Exit watching is registered BEFORE readiness so a member that dies during
+            // its readiness window is reported as a crash rather than as a silent
+            // readiness timeout.
+            child.on("close", ((code, signal) => {
+                const timestamp = deps.clock.now().toISOString();
+                patchMember(spec.name, { state: "exited", exitCode: code, exitSignal: signal });
+                // Enrolled synchronously so simultaneous exits queue in the order their
+                // patches were applied, and tracked so the write is awaited — never
+                // abandoned — before the runtime returns.
+                trackPersist(persist());
+                emitMemberEvent(deps.sinks, {
                     member: spec.name,
+                    kind: "exit",
                     timestamp,
-                    exitCode: code,
-                    exitSignal: signal,
                     logPath: spec.logPath,
+                    detail: signal !== null ? `signal ${signal}` : `code ${code ?? "unknown"}`,
                 });
-            }
-            // NOTHING follows. No respawn, no retry, no backoff timer, and no
-            // shutdown of the survivors: one member's crash is one member's crash.
-        }));
-        child.on("error", (() => {
-            /* surfaced through the close handler's exit status */
-        }));
-        if (spec.readiness) {
-            let resolvedInstanceId;
-            if (spec.readiness.kind === "process-heartbeat") {
-                // Resolved HERE, not on the roster: an executor lane's identity is
-                // minted before the spawn, but the local reconciler's is
-                // `<hostname>:<pid>` and the pid only exists now. The window between
-                // `spawn` returning and this probe is milliseconds, and the child cannot
-                // publish inside it — it has to open its database pools and start its
-                // scheduler first — but it is a window, and it is documented rather than
-                // asserted away. Supplying the identity TO the child would be race-free
-                // and would change a durable heartbeat writer, which this work forbids.
-                resolvedInstanceId =
-                    spec.readiness.instanceId ??
-                        resolveMemberInstanceId(spec.env, child.pid, deps.hostname);
-                // Announced BEFORE the wait, not after it. This is the slowest step in
-                // bring-up by an order of magnitude, and an operator watching a silent
-                // terminal for two minutes has no way to tell waiting from wedged. The
-                // wording is the status itself — no colour, no spinner, no symbol — so
-                // it survives a pipe, a CI log, and a screen reader identically. The
-                // resolved identity is NOT rendered: it is scoping, not news.
-                emitMemberEvent(deps.sinks, {
-                    member: spec.name,
-                    kind: "start",
-                    timestamp: deps.clock.now().toISOString(),
-                    logPath: spec.logPath,
-                    detail: `Starting — awaiting this member's first post-start ${spec.readiness.component} ` +
-                        `heartbeat (expected within ${Math.round(spec.readiness.timeoutMs / 1000)}s; watch ${spec.logPath})`,
+                if (!shuttingDown && !intentionallyStopped.has(spec.name)) {
+                    reportMemberCrash(deps.sinks, {
+                        member: spec.name,
+                        timestamp,
+                        exitCode: code,
+                        exitSignal: signal,
+                        logPath: spec.logPath,
+                    });
+                }
+                // NOTHING follows. No respawn, no retry, no backoff timer, and no
+                // shutdown of the survivors: one member's crash is one member's crash.
+            }));
+            child.on("error", (() => {
+                /* surfaced through the close handler's exit status */
+            }));
+            if (spec.readiness) {
+                let resolvedInstanceId;
+                if (spec.readiness.kind === "process-heartbeat") {
+                    // Resolved HERE, not on the roster: an executor lane's identity is
+                    // minted before the spawn, but the local reconciler's is
+                    // `<hostname>:<pid>` and the pid only exists now. The window between
+                    // `spawn` returning and this probe is milliseconds, and the child cannot
+                    // publish inside it — it has to open its database pools and start its
+                    // scheduler first — but it is a window, and it is documented rather than
+                    // asserted away. Supplying the identity TO the child would be race-free
+                    // and would change a durable heartbeat writer, which this work forbids.
+                    resolvedInstanceId =
+                        spec.readiness.instanceId ??
+                            resolveMemberInstanceId(spec.env, child.pid, deps.hostname);
+                    // Announced BEFORE the wait, not after it. This is the slowest step in
+                    // bring-up by an order of magnitude, and an operator watching a silent
+                    // terminal for two minutes has no way to tell waiting from wedged. The
+                    // wording is the status itself — no colour, no spinner, no symbol — so
+                    // it survives a pipe, a CI log, and a screen reader identically. The
+                    // resolved identity is NOT rendered: it is scoping, not news.
+                    emitMemberEvent(deps.sinks, {
+                        member: spec.name,
+                        kind: "start",
+                        timestamp: deps.clock.now().toISOString(),
+                        logPath: spec.logPath,
+                        detail: `Starting — awaiting this member's first post-start ${spec.readiness.component} ` +
+                            `heartbeat (expected within ${Math.round(spec.readiness.timeoutMs / 1000)}s; watch ${spec.logPath})`,
+                    });
+                }
+                // `memberExited` is read through the closure the `close` handler patches,
+                // so a child that dies mid-wait ends the wait immediately instead of
+                // burning the remaining budget and reporting a timeout it did not have.
+                const outcome = await waitForMemberReady(spec, deps, 250, () => !memberExited(spec.name), {
+                    baseline,
+                    instanceId: resolvedInstanceId,
+                    elapsedMs: baselineElapsedMs,
                 });
+                if (outcome.kind !== "ready") {
+                    return finishPartialStart(spec.name, describeReadinessFailure(spec, outcome), {
+                        log: opened.stream,
+                        failure: spec.readiness.kind === "process-heartbeat"
+                            ? PLANE_MEMBER_STARTUP_FAILURES.heartbeatReadinessTimeout
+                            : PLANE_MEMBER_STARTUP_FAILURES.readinessTimeout,
+                    });
+                }
             }
-            // `memberExited` is read through the closure the `close` handler patches,
-            // so a child that dies mid-wait ends the wait immediately instead of
-            // burning the remaining budget and reporting a timeout it did not have.
-            const outcome = await waitForMemberReady(spec, deps, 250, () => !memberExited(spec.name), {
-                baseline,
-                instanceId: resolvedInstanceId,
-                elapsedMs: baselineElapsedMs,
+            patchMember(spec.name, { state: "ready" });
+            await persist();
+            emitMemberEvent(deps.sinks, {
+                member: spec.name,
+                kind: "ready",
+                timestamp: deps.clock.now().toISOString(),
+                logPath: spec.logPath,
             });
-            if (outcome.kind !== "ready") {
-                return finishPartialStart(spec.name, describeReadinessFailure(spec, outcome), {
-                    log: opened.stream,
-                    failure: spec.readiness.kind === "process-heartbeat"
-                        ? PLANE_MEMBER_STARTUP_FAILURES.heartbeatReadinessTimeout
-                        : PLANE_MEMBER_STARTUP_FAILURES.readinessTimeout,
-                });
-            }
         }
-        patchMember(spec.name, { state: "ready" });
+        return null;
+    };
+    // ---- Phase one: the roster this runtime was handed ------------------------
+    const firstCohort = await startMembers(roster);
+    if (firstCohort !== null)
+        return firstCohort;
+    /**
+     * Phase two: scoped lanes, then the observer (BAPI-1102).
+     *
+     * The runtime stays alive inside this for as long as run creation takes.
+     * Nothing is spawned in the meantime, and the observer is deliberately NOT yet
+     * running: a plane with zero executor lanes is exactly the state its executor
+     * sweep would alert on.
+     *
+     * Returns `null` on success. A failure comes back as the terminal result, and
+     * the caller reads `heldControlPlane` to tell the two failure shapes apart:
+     * one rolled the plane back, the other stopped only what phase two started.
+     * Extracted into a function purely so those two can be distinguished at ONE
+     * place, instead of at each of the six early returns inside it.
+     */
+    const bringUpPhaseTwo = async (twoPhase) => {
+        const controlReady = await transitionPlaneManifestLifecycle(repoRoot, deps.planeId, "control-plane-starting", "control-plane-ready", deps.fs);
+        if (!controlReady.ok) {
+            return finishFailedStart(`the control-plane phase could not be recorded in the manifest (${controlReady.reason}).`);
+        }
+        manifest = { ...manifest, lifecycle: "control-plane-ready" };
+        // Announced only after the transition is DURABLE, so a caller that reads the
+        // manifest the instant it sees this marker cannot observe a stale phase.
+        //
+        // Set BEFORE the announcement: from the instant a caller can act on this
+        // marker, every later bring-up failure holds the control plane instead of
+        // rolling it back. Setting it after would leave a window in which a failure
+        // tore down a plane the caller was already creating a run against.
+        phaseTwoBegun = true;
+        deps.sinks.stdout(PLANE_CONTROL_READY_MARKER);
+        const requested = await awaitLaneScopeRequest(repoRoot, deps, twoPhase);
+        if (!requested.ok) {
+            // Nothing was spawned for phase two, so there is nothing to roll back
+            // beyond the control plane — which `finishPartialStart` handles.
+            return finishFailedStart(`plane bring-up did not complete: ${requested.error}.`);
+        }
+        const laneRoster = twoPhase.buildLaneRoster(requested.scope);
+        const lanesStarting = await transitionPlaneManifestLifecycle(repoRoot, deps.planeId, "control-plane-ready", "lanes-starting", deps.fs);
+        if (!lanesStarting.ok) {
+            return finishFailedStart(`the executor-lane phase could not be recorded in the manifest (${lanesStarting.reason}).`);
+        }
+        // Re-adopt the manifest the guarded write produced. It carries `epicRunId`
+        // and `laneScope`, both written by the OTHER process, and dropping them here
+        // would make the next `persist()` publish a record that had forgotten which
+        // run this plane serves — the exact binding `plane down` reads to stop it.
+        manifest = { ...lanesStarting.manifest, members: manifest.members };
+        await appendPlaneManifestMembers(repoRoot, deps.planeId, laneRoster.map(pendingMember), deps.fs);
+        manifest = { ...manifest, members: [...manifest.members, ...laneRoster.map(pendingMember)] };
         await persist();
-        emitMemberEvent(deps.sinks, {
-            member: spec.name,
-            kind: "ready",
-            timestamp: deps.clock.now().toISOString(),
-            logPath: spec.logPath,
-        });
+        const lanes = await startMembers(laneRoster);
+        if (lanes !== null)
+            return lanes;
+        const lanesReady = await transitionPlaneManifestLifecycle(repoRoot, deps.planeId, "lanes-starting", "lanes-ready", deps.fs);
+        if (!lanesReady.ok) {
+            return finishFailedStart(`executor-lane readiness could not be recorded in the manifest (${lanesReady.reason}).`);
+        }
+        manifest = { ...manifest, lifecycle: "lanes-ready" };
+        // Every lane's own per-instance heartbeat gate has closed. Only now is the
+        // observer's first sweep truthful.
+        manifest = {
+            ...manifest,
+            members: [...manifest.members, ...twoPhase.observerRoster.map(pendingMember)],
+        };
+        await appendPlaneManifestMembers(repoRoot, deps.planeId, twoPhase.observerRoster.map(pendingMember), deps.fs);
+        await persist();
+        const observer = await startMembers(twoPhase.observerRoster);
+        if (observer !== null)
+            return observer;
+        const ready = await transitionPlaneManifestLifecycle(repoRoot, deps.planeId, "lanes-ready", "ready", deps.fs);
+        if (!ready.ok) {
+            return finishFailedStart(`plane readiness could not be recorded in the manifest (${ready.reason}).`);
+        }
+        manifest = { ...manifest, lifecycle: "ready" };
+        return null;
+    };
+    let heldFailure = null;
+    if (deps.twoPhase) {
+        const outcome = await bringUpPhaseTwo(deps.twoPhase);
+        if (outcome !== null) {
+            // A failure BEFORE the control plane was announced ready is terminal, and
+            // has already rolled the whole plane back. One AFTER it is held: the
+            // caller may by then have created and approved a run against this plane,
+            // and `plane down` stops the manifest-bound run before it terminates
+            // processes — so tearing down here would stop a committed run because a
+            // local lane failed to start.
+            if (outcome.ok || outcome.heldControlPlane !== true)
+                return outcome;
+            heldFailure = outcome.error;
+            await stopPhaseTwoCohort();
+        }
+    }
+    if (heldFailure !== null) {
+        // Recorded before it is announced, for the same reason the ready phases are:
+        // a caller that reads the manifest the instant it sees this marker must not
+        // observe a phase that says lanes are still starting.
+        await recordLanesFailed();
+        deps.sinks.stderr("The control plane (server, reconciler) is STILL RUNNING and was not rolled back. " +
+            "No executor lane is claiming jobs, and the dead-man observer was not started. " +
+            "Inspect it with `plane status`, and wind it down with `plane down` once you have " +
+            "decided what to do with the run.");
+        // The failure counterpart of PLANE_READY_MARKER, and the reason it exists:
+        // the runtime does NOT exit here, so a launcher waiting on readiness or on
+        // the process lifetime would otherwise wait for something that never comes.
+        deps.sinks.stdout(PLANE_LANES_FAILED_MARKER);
+    }
+    else {
+        // Every member is spawned, alive, and (where it listens) accepting. Only now
+        // has the launcher been told anything it may print a success banner over.
+        // Emitted EXACTLY ONCE, in both modes, and in two-phase mode only after the
+        // observer is up — the banner claims a whole plane, so it must not be printed
+        // over one that is still half-built.
+        deps.sinks.stdout(PLANE_READY_MARKER);
     }
-    // Every member is spawned, alive, and (where it listens) accepting. Only now
-    // has the launcher been told anything it may print a success banner over.
-    deps.sinks.stdout(PLANE_READY_MARKER);
     // ---- Attended lifetime ---------------------------------------------------
     const exitCode = await new Promise((resolve) => {
         let resolved = false;
@@ -690,8 +978,33 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
     async function finishPartialStart(member, reason, annotate) {
         if (annotate)
             writeMemberStartupFailure(annotate.log, member, annotate.failure);
-        const message = `plane member '${member}' failed to start: ${reason}`;
+        return finishFailedStart(`plane member '${member}' failed to start: ${reason}`);
+    }
+    /**
+     * A bring-up failure that is NOT attributable to one member (BAPI-1102).
+     *
+     * The lifecycle transitions and the phase-two wait can fail with every member
+     * healthy — an unreadable manifest, a plane claimed by someone else, a caller
+     * that died before requesting lanes. Reporting those through
+     * {@link finishPartialStart} would print "plane member 'worker' failed to
+     * start" over a worker that started perfectly well and is still running, which
+     * sends an operator to the wrong log.
+     *
+     * Rollback is identical, deliberately: whatever the reason, a bring-up that did
+     * not complete must not leave half a plane behind.
+     */
+    async function finishFailedStart(message) {
         deps.sinks.stderr(message);
+        // BAPI-1102 — once the control plane has been ANNOUNCED ready, a bring-up
+        // failure must not tear the plane down. The composed caller has by then gone
+        // and created (and possibly approved) a run against this very plane, and
+        // `plane down` stops the manifest-bound run before it terminates processes:
+        // rolling back here would stop a committed run because a local lane failed
+        // to start. The lane cohort is stopped by the caller of this function and the
+        // server, reconciler, and manifest are left exactly as they are.
+        if (phaseTwoBegun) {
+            return { ok: false, error: message, exitCode: 1, heldControlPlane: true };
+        }
         if (started.length > 0) {
             deps.sinks.stderr(`Rolling back ${started.length} member(s) that had already started.`);
             shuttingDown = true;
@@ -708,6 +1021,75 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
         return { ok: false, error: message, exitCode: 1 };
     }
 }
+/**
+ * Wait for the composed caller to record a phase-two request in the manifest.
+ *
+ * BAPI-1102. The runtime and the requester are DIFFERENT PROCESSES — the
+ * requester may even exit before phase two finishes — so the durable manifest is
+ * the only channel between them. Polling it is the honest implementation of that:
+ * there is no shared memory to signal through, and a filesystem watch would add a
+ * platform-dependent dependency to a loop that runs for seconds.
+ *
+ * Bounded, and the bound is not a deadline an operator should ever reach: the
+ * composed caller requests phase two within seconds of the control plane going
+ * ready. It exists so a caller that DIED between the phases leaves a runtime that
+ * eventually reports why, rather than one polling forever.
+ *
+ * Every exit from here is a HELD failure, not a rollback: the control plane has
+ * already been announced ready, so by this point the caller may have created and
+ * approved a run against it. The runtime reports, stops nothing it did not start,
+ * and goes on supervising the server and reconciler until `plane down`.
+ *
+ * A manifest that stops being readable, or whose identity stops matching, ends
+ * the wait immediately — both mean this runtime no longer owns the plane, and
+ * continuing to wait would be waiting for an instruction that can never arrive.
+ * Those two are held as well, deliberately: a runtime that has lost its manifest
+ * cannot safely run `shutdownPlane`, because the manifest it would read and act
+ * on now describes somebody else's plane. It reports and leaves its own members
+ * running for an operator to resolve.
+ */
+async function awaitLaneScopeRequest(repoRoot, deps, twoPhase) {
+    const pollMs = twoPhase.pollIntervalMs ?? PLANE_PHASE_REQUEST_POLL_MS;
+    const timeoutMs = twoPhase.waitTimeoutMs ?? PLANE_PHASE_REQUEST_TIMEOUT_MS;
+    const sleep = twoPhase.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const startedAt = deps.clock.now().getTime();
+    for (;;) {
+        const read = await readPlaneManifest(repoRoot, deps.fs);
+        if (read.kind !== "valid") {
+            return {
+                ok: false,
+                error: "the plane manifest became unreadable while waiting for executor lanes",
+            };
+        }
+        if (read.manifest.planeId !== deps.planeId) {
+            return {
+                ok: false,
+                error: "the plane manifest was claimed by a different plane while waiting for executor lanes",
+            };
+        }
+        const scope = read.manifest.laneScope;
+        if (scope !== undefined)
+            return { ok: true, scope };
+        // A phase that has already moved past `control-plane-ready` with no scope
+        // recorded is incoherent — nothing else writes those phases — so it is
+        // reported rather than waited out.
+        const phase = planeManifestLifecycle(read.manifest);
+        if (phase !== "control-plane-ready" && phase !== "control-plane-starting") {
+            return {
+                ok: false,
+                error: `the plane advanced to ${phase} without recording an executor claim scope`,
+            };
+        }
+        if (deps.clock.now().getTime() - startedAt >= timeoutMs) {
+            return {
+                ok: false,
+                error: `no executor claim scope was requested within ${Math.round(timeoutMs / 1000)}s ` +
+                    "of the control plane becoming ready",
+            };
+        }
+        await sleep(pollMs);
+    }
+}
 /**
  * The pre-spawn baseline for one heartbeat-gated member, or a terminal reason.
  *