@bridge_gpt/mcp-server 0.2.49 → 0.2.51

package/build/plan-epic-conductor-eligibility.js

@@ -0,0 +1,183 @@
+/**
+ * Combined merge/review conductor-eligibility assessment for `plan-epic` (BAPI-964).
+ *
+ * Runs once the epic decomposition's child manifest is frozen and every
+ * sub-task's exploration text is written, so this module can predict — before
+ * any conductor worker is spawned — which children are likely to trip the
+ * runtime workflow-file merge guard (`api/library/vcs/conductor_merge_service.py`)
+ * and which of those additionally touch `claude-review.yml` itself, where
+ * automated review cannot run at all (BAPI-941's supply-chain preflight refuses
+ * to review a workflow that differs from the base branch's copy).
+ *
+ * The BROADER merge classification is delegated entirely to the Python
+ * classifier via one Bridge API call for the complete child set — this module
+ * never reimplements "what counts as a workflow file". The NARROWER review
+ * subclass is classified locally by checking each child's combined text for the
+ * full `CLAUDE_REVIEW_WORKFLOW_RELPATH`, imported (not re-declared) from
+ * `claude-review-workflow-drift.js`.
+ *
+ * Fails open, deliberately: any validation failure, classification failure, or
+ * internal contradiction (a review-subset child the backend did not also mark
+ * merge-blocked) becomes the explicit `unavailable` result — never a fabricated
+ * zero count. A caller that cannot get a real answer must say so, not guess.
+ */
+import { CLAUDE_REVIEW_WORKFLOW_RELPATH } from "./claude-review-workflow-drift.js";
+/**
+ * Build the real network-backed classification client that POSTs the complete
+ * child set to `/jira/planning/epic-workflow-eligibility` exactly once.
+ */
+export function createBridgeEpicConductorEligibilityClient(deps) {
+    return {
+        async classifyChildren(children) {
+            const fetchImpl = deps.fetchImpl ?? fetch;
+            const resp = await fetchImpl(deps.buildUrl("/planning/epic-workflow-eligibility"), {
+                method: "POST",
+                headers: await deps.getPostHeaders(),
+                body: JSON.stringify({ repo_name: deps.repoName, children }),
+            });
+            if (!resp.ok) {
+                throw new Error(`epic-workflow-eligibility classification request failed: ${resp.status}`);
+            }
+            return (await resp.json());
+        },
+    };
+}
+const UNAVAILABLE = { status: "unavailable" };
+function isNonBlankString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** Treat a missing/undefined optional field as empty text; reject a non-string value. */
+function optionalTextOrNull(value) {
+    if (value === undefined || value === null)
+        return "";
+    return typeof value === "string" ? value : null;
+}
+/** Deterministically assemble one child's scan text from its authoritative fields. */
+function buildCombinedText(child) {
+    return [child.title, child.scope, child.description, child.requirements]
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join("\n\n");
+}
+/** Validate the child collection at the module boundary. `null` means malformed. */
+function validateChildren(children) {
+    if (!Array.isArray(children) || children.length === 0)
+        return null;
+    const validated = [];
+    for (const child of children) {
+        if (child === null || typeof child !== "object")
+            return null;
+        if (!isNonBlankString(child.id) || !isNonBlankString(child.title))
+            return null;
+        const scope = optionalTextOrNull(child.scope);
+        const description = optionalTextOrNull(child.description);
+        const requirements = optionalTextOrNull(child.requirements);
+        if (scope === null || description === null || requirements === null)
+            return null;
+        validated.push({
+            id: child.id,
+            title: child.title,
+            combinedText: buildCombinedText({
+                id: child.id,
+                title: child.title,
+                scope,
+                description,
+                requirements,
+            }),
+        });
+    }
+    return validated;
+}
+/**
+ * Assess conductor merge/review eligibility for one frozen epic child set.
+ *
+ * Sends the complete ordered child set to the injected Bridge client exactly
+ * once. Never throws — every failure path (malformed input, client rejection,
+ * malformed backend response, an internal merge/review contradiction) resolves
+ * to the explicit `unavailable` result, diagnosed with `console.error` (never
+ * `console.log`, which is reserved for the MCP stdio transport).
+ */
+export async function assessEpicConductorEligibility(children, deps) {
+    const validated = validateChildren(children);
+    if (validated === null) {
+        console.error("assessEpicConductorEligibility: malformed child collection; unavailable.");
+        return UNAVAILABLE;
+    }
+    let response;
+    try {
+        response = await deps.client.classifyChildren(validated.map((child) => ({ child_id: child.id, combined_text: child.combinedText })));
+    }
+    catch (err) {
+        console.error("assessEpicConductorEligibility: Bridge classification call failed:", err);
+        return UNAVAILABLE;
+    }
+    if (response === null ||
+        typeof response !== "object" ||
+        !Array.isArray(response.predictions) ||
+        typeof response.total_children !== "number" ||
+        typeof response.predicted_workflow_children !== "number" ||
+        typeof response.reason !== "string") {
+        console.error("assessEpicConductorEligibility: malformed backend response shape; unavailable.");
+        return UNAVAILABLE;
+    }
+    if (response.predictions.length !== validated.length) {
+        console.error("assessEpicConductorEligibility: backend prediction count does not match child count; unavailable.");
+        return UNAVAILABLE;
+    }
+    // The backend is contractually order-preserving; still verify identity and
+    // order rather than trusting it, so a reordered/duplicate/unknown response
+    // never silently mislabels a child's prediction.
+    const predictionById = new Map();
+    for (const prediction of response.predictions) {
+        if (prediction === null ||
+            typeof prediction !== "object" ||
+            !isNonBlankString(prediction.child_id) ||
+            typeof prediction.predicted_workflow_modified !== "boolean" ||
+            !Array.isArray(prediction.matched_paths)) {
+            console.error("assessEpicConductorEligibility: malformed per-child prediction; unavailable.");
+            return UNAVAILABLE;
+        }
+        if (predictionById.has(prediction.child_id)) {
+            console.error("assessEpicConductorEligibility: duplicate child_id in backend response; unavailable.");
+            return UNAVAILABLE;
+        }
+        predictionById.set(prediction.child_id, prediction);
+    }
+    const affectedChildren = [];
+    let reviewSubsetChildren = 0;
+    let predictedWorkflowChildren = 0;
+    for (const child of validated) {
+        const prediction = predictionById.get(child.id);
+        if (!prediction) {
+            console.error(`assessEpicConductorEligibility: backend response is missing child ${child.id}; unavailable.`);
+            return UNAVAILABLE;
+        }
+        const reviewPathReferenced = child.combinedText.includes(CLAUDE_REVIEW_WORKFLOW_RELPATH);
+        if (reviewPathReferenced && !prediction.predicted_workflow_modified) {
+            // Subset invariant violated: a child naming claude-review.yml itself must
+            // also be in the broader merge-blocked set. Publishing this as a
+            // "review-only" child would contradict the merge count, so refuse instead.
+            console.error(`assessEpicConductorEligibility: child ${child.id} references the review workflow ` +
+                "but the backend did not mark it merge-blocked; refusing contradictory result.");
+            return UNAVAILABLE;
+        }
+        if (!prediction.predicted_workflow_modified)
+            continue;
+        predictedWorkflowChildren += 1;
+        if (reviewPathReferenced)
+            reviewSubsetChildren += 1;
+        affectedChildren.push({
+            id: child.id,
+            title: child.title,
+            matchedPaths: [...prediction.matched_paths],
+            requiresHandReview: reviewPathReferenced,
+        });
+    }
+    return {
+        status: "assessed",
+        totalChildren: validated.length,
+        predictedWorkflowChildren,
+        reason: response.reason,
+        reviewSubsetChildren,
+        affectedChildren,
+    };
+}

package/build/plane/cli.js

@@ -17,7 +17,7 @@ import { PLANE_RUNTIME_ENTRYPOINT_REFUSAL } from "./build-freshness.js";
 import { relativeLogPathFor } from "./manifest.js";
 import { claimPlaneManifest } from "./manifest.js";
 import { runPlanePreflight } from "./preflight.js";
-import { buildPlaneMemberRoster } from "./member-roster.js";
+import { buildPlaneMemberRoster, resolvePlaneServerEndpoint } from "./member-roster.js";
 import { getPlaneStatus, formatPlaneStatus } from "./status.js";
 import { shutdownPlane, formatPlaneShutdown } from "./shutdown.js";
 import { launchPlaneSupervisor, runPlaneRuntime, } from "./supervisor.js";
@@ -454,7 +454,7 @@ function printStartupBanner(sinks, context, memberCount, executors, launch) {
     sinks.stdout("");
     sinks.stdout(`Plane up — ${memberCount} members (${executors} executor lane(s))`);
     sinks.stdout(`  repository   ${context.repoName} (${context.repoRoot})`);
-    sinks.stdout(`  server       ${context.baseUrl} (no --reload)`);
+    sinks.stdout(`  server       ${context.endpoint.baseUrl} (no --reload)`);
     sinks.stdout(`  supervisor   pid ${launch.supervisorPid}, process group ${launch.supervisorPgid}`);
     sinks.stdout(`  logs         ${PLANE_RUNTIME_DIR}/`);
     sinks.stdout("  crash policy members are NOT restarted; a member exit is reported loudly.");
@@ -525,9 +525,19 @@ async function runRuntimeAction(executors, overrides) {
     });
     return result.exitCode;
 }
+/**
+ * Bind preflight's dependencies to the real platform for one environment.
+ *
+ * This is the ONLY production path that reads the plane's server-port override
+ * (BAPI-950). Both `plane up` and the private `plane __runtime` action go
+ * through here, so the launcher and the detached runtime it spawns resolve the
+ * endpoint by exactly the same rule — a second lookup elsewhere is what would
+ * let the two disagree about which port the plane is on.
+ */
 function buildPreflightDeps(env) {
     return {
         env,
+        endpoint: resolvePlaneServerEndpoint(env),
         platform: process.platform,
         homedir: resolveHomedir,
         fs: createPlaneFsDeps(),

package/build/plane/manifest.js

@@ -259,14 +259,38 @@ export function manifestHasLiveProcess(manifest, proc) {
 export function formatPlaneManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+/**
+ * Monotonic per-process discriminator for temporary manifest filenames.
+ *
+ * Module-local and used for nothing else. It never appears in the published
+ * manifest, in a diagnostic, or in any path that outlives the rename below.
+ */
+let manifestWriteCounter = 0;
 /**
  * Persist a state transition through a same-directory temporary file and an
  * atomic rename, so a crash mid-write can never leave a half-written manifest
  * that a subsequent `plane down` would read as a kill list.
+ *
+ * The temporary name is unique per WRITE, not per plane (BAPI-950). It used to
+ * be keyed only by `planeId`, which every writer of the same plane shares — so
+ * two overlapping writes wrote the one temp file simultaneously and the rename
+ * published their interleaved bytes as `plane.json`. `readPlaneManifest` then
+ * reported "manifest is not valid JSON" and `plane down` refused to remove a
+ * manifest it could not validate, leaving the plane un-windable.
+ *
+ * The runtime serializes its own writes (see `runPlaneRuntime`), which is the
+ * primary fix; this is defense in depth for INDEPENDENT writers — the launcher,
+ * the claim path, an epic-run binding — that no single in-process queue can
+ * order. `process.pid` separates processes, the counter separates writes within
+ * one process, and `planeId` is retained so a stray temp file is still
+ * attributable to the plane that produced it.
  */
 export async function writePlaneManifest(manifest, fs) {
     const { manifestPath } = getPlanePaths(manifest.repoRoot);
-    const tempPath = `${manifestPath}.${manifest.planeId}.tmp`;
+    manifestWriteCounter += 1;
+    // Same directory as `plane.json`, so the rename stays a same-filesystem
+    // atomic replacement rather than a copy across a mount boundary.
+    const tempPath = `${manifestPath}.${manifest.planeId}.${process.pid}.${manifestWriteCounter}.tmp`;
     await fs.writeFile(tempPath, formatPlaneManifest(manifest));
     await fs.rename(tempPath, manifestPath);
 }

package/build/plane/member-roster.js

@@ -17,7 +17,7 @@
  * member name, log path, or formatted description is built from a secret.
  */
 import path from "path";
-import { PLANE_SERVER_HOST, PLANE_SERVER_PORT, } from "./types.js";
+import { PLANE_SERVER_HOST, PLANE_SERVER_PORT, PLANE_SERVER_PORT_ENV_VAR, } from "./types.js";
 import { relativeLogPathFor } from "./manifest.js";
 /** How long a member with a readiness probe gets to start listening. */
 export const PLANE_READINESS_TIMEOUT_MS = 60_000;
@@ -35,6 +35,55 @@ export function resolveUvicornExecutable(env) {
         ? configured.trim()
         : "uvicorn";
 }
+/** Highest port number a TCP endpoint can occupy. */
+const MAX_TCP_PORT = 65_535;
+/**
+ * The only diagnostic an invalid override ever produces.
+ *
+ * Fixed prose, built from the variable's own name and the accepted range and
+ * nothing else. The supplied value is deliberately NOT echoed: an operator who
+ * pasted a secret into the wrong shell export would otherwise have it printed
+ * to the terminal and copied into the preflight trace on disk.
+ */
+export const PLANE_SERVER_PORT_INVALID_MESSAGE = `${PLANE_SERVER_PORT_ENV_VAR} must be a whole TCP port number in the range 1..${MAX_TCP_PORT}. ` +
+    "Unset it to use the default port " +
+    `${PLANE_SERVER_PORT}, or export a valid port and retry.`;
+/** Build an endpoint from a port, deriving the base URL from the same fields. */
+function endpointForPort(port) {
+    return { host: PLANE_SERVER_HOST, port, baseUrl: `http://${PLANE_SERVER_HOST}:${port}` };
+}
+/**
+ * Resolve the local server endpoint from the environment, exactly once.
+ *
+ * Absent or blank leaves the historical contract untouched: the default is
+ * `127.0.0.1:8000` and `http://127.0.0.1:8000`, identical to the constants that
+ * were previously read directly.
+ *
+ * Anything present is validated STRICTLY and, when invalid, *refused* rather
+ * than quietly falling back to 8000. A silent fallback is the failure mode this
+ * override exists to remove: an operator who set the variable precisely because
+ * 8000 was occupied would watch the plane bind 8000 anyway and see a port
+ * collision they had already worked around.
+ *
+ * The host is never read from the environment — see {@link PLANE_SERVER_HOST}.
+ */
+export function resolvePlaneServerEndpoint(env) {
+    const configured = env[PLANE_SERVER_PORT_ENV_VAR];
+    if (typeof configured !== "string" || configured.trim().length === 0) {
+        return { ok: true, endpoint: endpointForPort(PLANE_SERVER_PORT) };
+    }
+    const raw = configured.trim();
+    // Digits only, deliberately: `Number()` accepts "0x1f4", "1e3", " 8000 ", and
+    // "+8000", and `parseInt` accepts "8000x" by stopping at the first non-digit.
+    // Either would let a typo resolve to a port the operator never wrote.
+    if (!/^[0-9]+$/.test(raw))
+        return { ok: false, message: PLANE_SERVER_PORT_INVALID_MESSAGE };
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > MAX_TCP_PORT) {
+        return { ok: false, message: PLANE_SERVER_PORT_INVALID_MESSAGE };
+    }
+    return { ok: true, endpoint: endpointForPort(port) };
+}
 /**
  * Build a child environment: a copy of the parent plus the resolved values the
  * existing processes already expect.
@@ -51,7 +100,7 @@ export function buildPlaneChildEnv(parentEnv, context) {
             env[key] = value;
     }
     env.BAPI_REPO_NAME = context.repoName;
-    env.BAPI_BASE_URL = context.baseUrl;
+    env.BAPI_BASE_URL = context.endpoint.baseUrl;
     env.BAPI_API_KEY = context.bridgeApiKey;
     delete env.CONDUCTOR_DEAD_MAN_ONLY;
     return env;
@@ -64,6 +113,11 @@ export function buildPlaneMemberRoster(params) {
     const { context, executors, parentEnv, nodeExecutable } = params;
     const env = buildPlaneChildEnv(parentEnv, context);
     const cwd = context.repoRoot;
+    // One resolved endpoint for the bind argv, the readiness probe, every
+    // executor's `--base-url`, and the child `BAPI_BASE_URL`. Reading the default
+    // constants here instead is what would let uvicorn bind one port while the
+    // probe and the executors addressed another.
+    const endpoint = context.endpoint;
     const server = {
         name: "server",
         command: resolveUvicornExecutable(parentEnv),
@@ -73,16 +127,16 @@ export function buildPlaneMemberRoster(params) {
         args: [
             "main:app",
             "--host",
-            PLANE_SERVER_HOST,
+            endpoint.host,
             "--port",
-            String(PLANE_SERVER_PORT),
+            String(endpoint.port),
         ],
         cwd,
         env,
         logPath: relativeLogPathFor("server"),
         readiness: {
-            host: PLANE_SERVER_HOST,
-            port: PLANE_SERVER_PORT,
+            host: endpoint.host,
+            port: endpoint.port,
             timeoutMs: PLANE_READINESS_TIMEOUT_MS,
         },
     };
@@ -111,7 +165,7 @@ export function buildPlaneMemberRoster(params) {
                 "--repo",
                 context.repoName,
                 "--base-url",
-                context.baseUrl,
+                endpoint.baseUrl,
                 "--executor-id",
                 buildExecutorId(context.repoName, lane),
             ],

package/build/plane/preflight.js

@@ -12,7 +12,7 @@
  * it — including any manifest belonging to a plane that is already running.
  */
 import path from "path";
-import { PLANE_SERVER_BASE_URL, PLANE_SERVER_HOST, PLANE_SERVER_PORT, } from "./types.js";
+import { PLANE_SERVER_PORT_ENV_VAR, } from "./types.js";
 import { checkPlaneBuildFreshness, checkPlaneRuntimeEntrypoint } from "./build-freshness.js";
 import { checkAlembicHead } from "./alembic-head.js";
 import { manifestHasLiveProcess, readPlaneManifest } from "./manifest.js";
@@ -56,7 +56,15 @@ export async function runPlanePreflight(repoRoot, deps) {
     // unresolvable re-exec target aggregates with them instead of short-circuiting.
     const runtimeEntrypoint = deps.resolveRuntimeEntrypoint();
     add(checkPlaneRuntimeEntrypoint(runtimeEntrypoint));
-    add(await checkServerPort(deps));
+    // An unresolvable override is a configuration failure, not a port failure:
+    // there is no port to probe, so the probe is skipped entirely rather than
+    // falling back to 8000 and reporting on a port the operator did not ask for.
+    if (deps.endpoint.ok) {
+        add(await checkServerPort(deps, deps.endpoint.endpoint));
+    }
+    else {
+        add({ check: "server-port", severity: "blocking", message: deps.endpoint.message });
+    }
     add(await checkAlembicHead(repoRoot, {
         execFile: deps.execFile,
         fileExists: (filePath) => fileExists(filePath, deps.fs),
@@ -67,7 +75,10 @@ export async function runPlanePreflight(repoRoot, deps) {
     // `!runtimeEntrypoint.ok` is already covered by the blocking count; it is
     // repeated here so the compiler narrows the union rather than requiring a
     // non-null assertion on the context field below.
-    if (blocking.length > 0 || !credentials.ok || !runtimeEntrypoint.ok) {
+    // `!deps.endpoint.ok` is already covered by the blocking count; it is repeated
+    // here, like `!runtimeEntrypoint.ok`, so the compiler narrows the union rather
+    // than requiring a non-null assertion on the context field below.
+    if (blocking.length > 0 || !credentials.ok || !runtimeEntrypoint.ok || !deps.endpoint.ok) {
         return { ok: false, diagnostics };
     }
     return {
@@ -76,7 +87,9 @@ export async function runPlanePreflight(repoRoot, deps) {
         context: {
             repoRoot,
             repoName: credentials.repoName,
-            baseUrl: PLANE_SERVER_BASE_URL,
+            // The SAME object `checkServerPort` probed above. Never re-resolved, so
+            // the probed port and the launched port cannot diverge.
+            endpoint: deps.endpoint.endpoint,
             // Location-chosen: always THIS repository's build tree, so an executor can
             // never come from a published package.
             executorEntrypoint: path.join(repoRoot, "mcp_server", "build", "index.js"),
@@ -296,23 +309,25 @@ function createResolverWarningBuffer() {
  * let two servers race for the port, and silently assuming "occupied" would
  * refuse a perfectly good bring-up.
  */
-export async function checkServerPort(deps) {
-    const result = await deps.probePort(PLANE_SERVER_HOST, PLANE_SERVER_PORT, PLANE_PORT_PROBE_TIMEOUT_MS);
+export async function checkServerPort(deps, endpoint) {
+    const target = `${endpoint.host}:${endpoint.port}`;
+    const result = await deps.probePort(endpoint.host, endpoint.port, PLANE_PORT_PROBE_TIMEOUT_MS);
     if (result.kind === "refused")
         return null;
     if (result.kind === "connected") {
         return {
             check: "server-port",
             severity: "blocking",
-            message: `${PLANE_SERVER_HOST}:${PLANE_SERVER_PORT} is already accepting connections. ` +
+            message: `${target} is already accepting connections. ` +
                 "That port may belong to a SIBLING WORKTREE's server — check before you kill it. " +
-                "Stop the existing server (or wind down its plane) and retry.",
+                `Stop the existing server (or wind down its plane) and retry, or set ${PLANE_SERVER_PORT_ENV_VAR} ` +
+                "to a free port.",
         };
     }
     return {
         check: "server-port",
         severity: "warning",
-        message: `could not determine whether ${PLANE_SERVER_HOST}:${PLANE_SERVER_PORT} is free ` +
+        message: `could not determine whether ${target} is free ` +
             `(${result.error}); startup continues and uvicorn will fail loudly if the port is taken.`,
     };
 }

package/build/plane/supervisor.js

@@ -176,7 +176,7 @@ export async function launchPlaneSupervisor(params, deps) {
     }
     runtimeEnv[PLANE_ID_ENV_VAR] = manifest.planeId;
     runtimeEnv.BAPI_REPO_NAME = context.repoName;
-    runtimeEnv.BAPI_BASE_URL = context.baseUrl;
+    runtimeEnv.BAPI_BASE_URL = context.endpoint.baseUrl;
     runtimeEnv.BAPI_API_KEY = context.bridgeApiKey;
     let child;
     try {
@@ -339,12 +339,76 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
         })),
         updatedAt: deps.clock.now().toISOString(),
     };
-    await writePlaneManifest(manifest, deps.fs);
     const started = [];
-    const persist = async () => {
+    // ---- Serialized manifest persistence (BAPI-950) --------------------------
+    //
+    // `writePlaneManifest` publishes through a temporary file and an atomic
+    // rename. That is safe for ONE writer and unsafe for two: overlapping writers
+    // interleave on the temp file and the rename then publishes a half-written
+    // `plane.json`, which `readPlaneManifest` rejects as "manifest is not valid
+    // JSON" and `plane down` refuses to act on — the corrupt manifest is then
+    // un-removable and poisons every later bring-up. The runtime used to make
+    // that overlap routine: the spawn loop awaited `persist()` while every
+    // member's `close` handler fired `void persist()` with nothing serializing
+    // them, so reaping several members in one window (exactly what `plane down`
+    // and a SIGKILL do) raced them against each other.
+    //
+    // One promise tail removes the overlap for this process's own writes.
+    let persistTail = Promise.resolve();
+    // Writes nobody awaits inline — the `close`-handler ones. Held so the runtime
+    // can wait for them instead of leaving detached filesystem work behind.
+    const pendingPersists = new Set();
+    // Set the moment the manifest's ownership passes to `shutdownPlane`, which
+    // removes it. A write that landed after that removal would resurrect a
+    // `plane.json` describing a plane that no longer exists.
+    let manifestReleased = false;
+    const persist = () => {
+        if (manifestReleased)
+            return Promise.resolve();
+        // Stamped and snapshotted SYNCHRONOUSLY, at enqueue time. A queued write
+        // must publish the state as it stood when it was enqueued; reading the
+        // mutable `manifest` binding when the write finally runs would let a later
+        // member patch overwrite an earlier transition's record.
         manifest = { ...manifest, updatedAt: deps.clock.now().toISOString() };
-        await writePlaneManifest(manifest, deps.fs);
+        const snapshot = manifest;
+        const operation = persistTail.then(() => writePlaneManifest(snapshot, deps.fs));
+        // The tail is recovered but the caller's promise is not: one failed write
+        // must not poison every write queued behind it, and it must not be
+        // swallowed either. `operation` still rejects with the original error.
+        persistTail = operation.catch(() => undefined);
+        return operation;
     };
+    /**
+     * Enroll a write whose completion no caller awaits, and observe its failure.
+     *
+     * The message is fixed prose. The thrown value can carry a path or an errno
+     * struct, and the runtime's stderr is the operator's terminal.
+     */
+    const trackPersist = (operation) => {
+        const tracked = operation.catch(() => {
+            deps.sinks.stderr("Plane manifest could not be updated after a member exit.");
+        });
+        pendingPersists.add(tracked);
+        void tracked.then(() => {
+            pendingPersists.delete(tracked);
+        });
+    };
+    /** Wait for every manifest write already enqueued, including untracked ones. */
+    const drainPersists = async () => {
+        // Looped because a member can exit — and enqueue — while an earlier write
+        // is still settling. Each close enqueues exactly one write, and `persist`
+        // stops enqueuing once the manifest is released, so this terminates.
+        while (pendingPersists.size > 0) {
+            await Promise.all([...pendingPersists]);
+        }
+        await persistTail;
+    };
+    /** Hand the manifest to `shutdownPlane` with no runtime write still in flight. */
+    const releaseManifest = async () => {
+        manifestReleased = true;
+        await drainPersists();
+    };
+    await persist();
     const patchMember = (name, patch) => {
         manifest = {
             ...manifest,
@@ -357,6 +421,10 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
             return null;
         shuttingDown = true;
         deps.sinks.stdout(`Received ${signal} — winding the plane down.`);
+        // Before `shutdownPlane` reads and removes the manifest, not after: it must
+        // see this runtime's completed state, and no queued write may outlive its
+        // removal.
+        await releaseManifest();
         return shutdownPlane(repoRoot, {
             fs: deps.fs,
             proc: deps.proc,
@@ -413,7 +481,10 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
         child.on("close", ((code, signal) => {
             const timestamp = deps.clock.now().toISOString();
             patchMember(spec.name, { state: "exited", exitCode: code, exitSignal: signal });
-            void persist();
+            // 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",
@@ -499,6 +570,7 @@ export async function runPlaneRuntime(repoRoot, roster, deps) {
         if (started.length > 0) {
             deps.sinks.stderr(`Rolling back ${started.length} member(s) that had already started.`);
             shuttingDown = true;
+            await releaseManifest();
             const result = await shutdownPlane(repoRoot, {
                 fs: deps.fs,
                 proc: deps.proc,

package/build/plane/types.js

@@ -35,12 +35,32 @@ export const PLANE_MANIFEST_FILENAME = "plane.json";
 export const PLANE_RUNTIME_LOG_FILENAME = "runtime.log";
 /** Repository-relative path of the runtime startup trace. */
 export const PLANE_RUNTIME_LOG_PATH = `${PLANE_RUNTIME_DIR}/${PLANE_RUNTIME_LOG_FILENAME}`;
-/** Host the local Bridge API server binds for an attended run. */
+/**
+ * Host the local Bridge API server binds for an attended run.
+ *
+ * Loopback, and NOT overridable. The plane binds a development server with no
+ * authentication in front of it; letting an operator move it off `127.0.0.1`
+ * would expose that server to the local network, which is a different decision
+ * from "run it on a different port because 8000 is taken".
+ */
 export const PLANE_SERVER_HOST = "127.0.0.1";
-/** Port the local Bridge API server binds for an attended run. */
+/** Default port the local Bridge API server binds for an attended run. */
 export const PLANE_SERVER_PORT = 8000;
-/** Base URL the executor members are pointed at. */
+/** Default base URL the executor members are pointed at. */
 export const PLANE_SERVER_BASE_URL = `http://${PLANE_SERVER_HOST}:${PLANE_SERVER_PORT}`;
+/**
+ * Environment variable that overrides {@link PLANE_SERVER_PORT}.
+ *
+ * Named to match the existing `BAPI_PLANE_PYTHON` / `BAPI_PLANE_UVICORN`
+ * convention: `BAPI_PLANE_*` is the plane's own configuration namespace, kept
+ * distinct from `BAPI_*` values (`BAPI_BASE_URL`, `BAPI_API_KEY`) that the
+ * spawned members consume.
+ *
+ * Only the PORT is configurable. An absent or blank value resolves to exactly
+ * the default endpoint — `http://127.0.0.1:8000` — so a machine that never sets
+ * it is byte-for-byte unchanged.
+ */
+export const PLANE_SERVER_PORT_ENV_VAR = "BAPI_PLANE_PORT";
 /**
  * Private action name for the detached supervisor runtime.
  *