@bridge_gpt/mcp-server 0.2.49 → 0.2.50

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.
  *