@bridge_gpt/mcp-server 0.2.42 → 0.2.44

package/build/plane/cli.js

@@ -134,8 +134,11 @@ export function getPlaneUsage() {
         "  plane up [--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                 Signal the recorded process group, escalating to",
-        "                             SIGKILL, and clear the manifest.",
+        "  plane down                 Stop the bound server-side epic run FIRST (BAPI-872),",
+        "                             then signal the recorded process group, escalating",
+        "                             to SIGKILL, and clear the manifest. Process shutdown",
+        "                             alone is NOT a run stop — a manifest with no bound",
+        "                             run, or an unreachable Bridge API, only warns.",
         "",
         "Options:",
         `  --executors N              Executor lanes to start (default ${PLANE_DEFAULT_EXECUTORS}, max ${PLANE_MAX_EXECUTORS}).`,
@@ -272,11 +275,53 @@ async function runDownAction(sinks, overrides) {
         fs: createPlaneFsDeps(),
         proc: createPlaneProcessDeps(),
         clock: createPlaneClock(),
+        stopBoundRun: stopBoundEpicRun,
     });
     const text = formatPlaneShutdown(result);
     (result.ok ? sinks.stdout : sinks.stderr)(text);
     return result.ok ? 0 : 1;
 }
+/**
+ * `plane down`'s pre-signal run-stop capability (BAPI-872).
+ *
+ * Resolves Bridge access scoped to the MANIFEST's own repository root (never
+ * the process's `cwd`, which is not necessarily the same directory) and calls
+ * the shared `stopEpicRunRecovery` — the identical stop semantics
+ * `conductor stop-run` uses, so the two surfaces can never drift apart.
+ *
+ * Never throws. `shutdownPlane` awaits this directly with no try/catch of its
+ * own, so a credential, transport, or unexpected failure here is converted
+ * into a fixed `unavailable` outcome rather than propagating — a failure to
+ * stop the run must never prevent the validated process-group shutdown that
+ * follows it.
+ */
+async function stopBoundEpicRun(epicRunId, manifest) {
+    try {
+        const { resolveConductorBridgeApiAccess } = await import("../conductor/bridge-api-client.js");
+        const { stopEpicRunRecovery } = await import("../conductor/recovery-operations.js");
+        const accessResult = await resolveConductorBridgeApiAccess({ cwd: manifest.repoRoot });
+        if (!accessResult.ok) {
+            return { kind: "unavailable", epicRunId, message: accessResult.error };
+        }
+        const result = await stopEpicRunRecovery(accessResult.access, { epicRunId });
+        if (result.ok) {
+            return result.kind === "committed"
+                ? { kind: "committed", epicRunId }
+                : { kind: "already-stopped", epicRunId };
+        }
+        if (result.kind === "terminal") {
+            return { kind: "terminal", epicRunId, status: result.status };
+        }
+        return { kind: "unavailable", epicRunId, message: result.message };
+    }
+    catch (err) {
+        return {
+            kind: "unavailable",
+            epicRunId,
+            message: err instanceof Error ? err.constructor.name : "run-stop failed unexpectedly",
+        };
+    }
+}
 async function runUpAction(executors, sinks, overrides) {
     const repoRoot = overrides.cwd ?? process.cwd();
     const env = overrides.env ?? process.env;
@@ -424,7 +469,12 @@ async function runRuntimeAction(executors, overrides) {
         return overrides.runtime(repoRoot, executors);
     const env = overrides.env ?? process.env;
     const planeId = env[PLANE_ID_ENV_VAR];
-    const sinks = {
+    // BAPI-882: honour injected sinks. The runtime writes straight to the real
+    // process streams in production, but a test that cannot capture this output
+    // cannot assert the refusal at all — which is why the refusal below had never
+    // executed under test and its message string appeared nowhere else in the
+    // repository.
+    const sinks = overrides.sinks ?? {
         stdout: (line) => process.stdout.write(`${line}\n`),
         stderr: (line) => process.stderr.write(`${line}\n`),
     };
@@ -432,11 +482,27 @@ async function runRuntimeAction(executors, overrides) {
         sinks.stderr(`plane runtime refused: ${PLANE_ID_ENV_VAR} was not provided by the launcher.`);
         return 1;
     }
-    const preflight = await runPlanePreflight(repoRoot, buildPreflightDeps(env));
+    // BAPI-882: hand preflight this runtime's own plane id. The launcher claimed
+    // `plane.json` with `supervisorPid: process.pid` as a placeholder BEFORE
+    // spawning us, so a preflight without an identity sees that live claim,
+    // classifies it as "another plane is running", and refuses — the runtime
+    // deadlocking on its own launcher. `planeId` is validated non-empty above.
+    const preflight = overrides.preflight
+        ? await overrides.preflight(repoRoot)
+        : await runPlanePreflight(repoRoot, { ...buildPreflightDeps(env), ownPlaneId: planeId });
     if (!preflight.ok) {
-        // The launcher already ran preflight; reaching here means the world changed
-        // between claim and spawn. Refuse rather than start a half-valid plane.
-        sinks.stderr(`plane runtime refused: preflight no longer passes. ${PLANE_NOTHING_STARTED}.`);
+        // The launcher already ran preflight; reaching here means the world genuinely
+        // changed between claim and spawn. Refuse rather than start a half-valid
+        // plane — but say WHICH check failed. Naming only "preflight no longer
+        // passes" threw away diagnostics that had just been computed and left the
+        // operator with nothing to act on.
+        sinks.stderr("");
+        sinks.stderr("plane runtime REFUSED — preflight found blocking problems:");
+        for (const diagnostic of preflight.diagnostics.filter((d) => d.severity === "blocking")) {
+            sinks.stderr(formatDiagnostic(diagnostic));
+        }
+        sinks.stderr("");
+        sinks.stderr(`${PLANE_NOTHING_STARTED}.`);
         return 1;
     }
     const roster = buildPlaneMemberRoster({

package/build/plane/defaults.js

@@ -54,13 +54,23 @@ export function createPlaneFsDeps() {
         },
     };
 }
-/** Wall-clock time and real sleeps. */
+/**
+ * Wall-clock time and real sleeps.
+ *
+ * The sleep timer is deliberately NOT `.unref()`'d. `plane down`'s wait loop
+ * (`shutdown.ts#waitForDeath`) awaits this from a short-lived CLI process's
+ * top-level `await` (`index.ts`) — an unref'd timer lets Node consider the
+ * event loop empty while that await is still pending, which Node reports as
+ * an "unsettled top-level await" and answers by forcing exit code 13,
+ * corrupting the CLI's real exit code and losing its buffered stdout. A
+ * long-running `plane up` supervisor is unaffected either way: it stays alive
+ * on its own child-process and signal-handler activity regardless of this
+ * timer's ref state.
+ */
 export function createPlaneClock() {
     return {
         now: () => new Date(),
-        sleep: (ms) => new Promise((resolve) => {
-            setTimeout(resolve, ms).unref?.();
-        }),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     };
 }
 /** Liveness and signal delivery bound to `process.kill`. */

package/build/plane/manifest.js

@@ -52,7 +52,13 @@ const MANIFEST_KEYS = new Set([
     "createdAt",
     "updatedAt",
     "members",
+    // BAPI-872: the optional server-side epic-run binding.
+    "epicRunId",
 ]);
+/** Non-blank string, trimmed equal to itself (no leading/trailing whitespace). */
+function isNonBlankTrimmedString(value) {
+    return typeof value === "string" && value.trim().length > 0 && value === value.trim();
+}
 const MEMBER_KEYS = new Set([
     "name",
     "pid",
@@ -113,6 +119,14 @@ export function parsePlaneManifest(value) {
     if (!Array.isArray(record.members) || record.members.length === 0) {
         return { ok: false, error: "manifest members are missing" };
     }
+    // BAPI-872: `epicRunId` is optional — absent means a legacy or still-unbound
+    // manifest, which is a perfectly valid state. When present it must be a
+    // genuine non-blank, untrimmed-clean string; anything else is rejected here
+    // rather than silently coerced, because a malformed value would otherwise
+    // reach `plane down`'s run-stop lookup as an unvalidated identifier.
+    if (record.epicRunId !== undefined && !isNonBlankTrimmedString(record.epicRunId)) {
+        return { ok: false, error: "manifest epic run id is malformed" };
+    }
     const members = [];
     const seen = new Set();
     for (const raw of record.members) {
@@ -169,6 +183,7 @@ export function parsePlaneManifest(value) {
             createdAt: record.createdAt,
             updatedAt: record.updatedAt,
             members,
+            ...(record.epicRunId !== undefined ? { epicRunId: record.epicRunId } : {}),
         },
     };
 }
@@ -294,6 +309,81 @@ export async function clearPlaneManifest(repoRoot, planeId, fs) {
         };
     }
 }
+/**
+ * Atomically bind `epicRunId` onto the plane manifest (BAPI-872).
+ *
+ * The one and only writer of `PlaneManifest.epicRunId`. Fully validates the
+ * manifest AND the calling plane's identity before ANY mutation — a
+ * malformed/untrusted record is refused rather than bound, and a manifest that
+ * legitimately belongs to a DIFFERENT plane (a stale record from an earlier
+ * run at the same repository root) is refused rather than silently claimed.
+ *
+ * Binding the SAME `epicRunId` a second time is a safe, idempotent no-op
+ * (`alreadyBound: true`) — a re-run of `setup-epic` reusing a live run must
+ * not fail here. Binding a DIFFERENT `epicRunId` onto an already-bound
+ * manifest is refused (`conflict`): this function never repoints a plane at a
+ * different run, because guessing which one is right is exactly the ambiguity
+ * this binding exists to remove.
+ */
+export async function bindPlaneManifestEpicRun(repoRoot, planeId, epicRunId, fs) {
+    const read = await readPlaneManifest(repoRoot, fs);
+    if (read.kind === "missing") {
+        return {
+            ok: false,
+            reason: "no-manifest",
+            message: "no plane manifest found for this repository",
+        };
+    }
+    if (read.kind !== "valid") {
+        return {
+            ok: false,
+            reason: "unvalidated-manifest",
+            message: `plane manifest could not be validated (${read.error})`,
+        };
+    }
+    const manifest = read.manifest;
+    if (manifest.planeId !== planeId) {
+        return {
+            ok: false,
+            reason: "identity-mismatch",
+            message: "plane manifest belongs to a different plane identity",
+        };
+    }
+    if (manifest.repoRoot !== repoRoot) {
+        // Defense in depth: the manifest is already located BY `repoRoot` (it can
+        // only be found at `<repoRoot>/.bridge/plane/plane.json`), so this fires
+        // only for a manifest file that was copied or symlinked from elsewhere and
+        // still carries its origin's `repoRoot`. Refusing here keeps that stale
+        // self-description from ever being trusted as this repository's own.
+        return {
+            ok: false,
+            reason: "identity-mismatch",
+            message: "plane manifest belongs to a different repository root",
+        };
+    }
+    if (manifest.epicRunId === epicRunId) {
+        return { ok: true, alreadyBound: true };
+    }
+    if (manifest.epicRunId !== undefined) {
+        return {
+            ok: false,
+            reason: "conflict",
+            message: `plane manifest is already bound to a different epic run (${manifest.epicRunId})`,
+        };
+    }
+    try {
+        await writePlaneManifest({ ...manifest, epicRunId, updatedAt: new Date().toISOString() }, fs);
+    }
+    catch (err) {
+        const code = err?.code;
+        return {
+            ok: false,
+            reason: "error",
+            message: `could not bind the epic run to the plane manifest (${typeof code === "string" ? code : "write failed"})`,
+        };
+    }
+    return { ok: true, alreadyBound: false };
+}
 /**
  * Take exclusive ownership of `.bridge/plane/plane.json`.
  *

package/build/plane/preflight.js

@@ -336,6 +336,25 @@ export async function checkExistingPlane(repoRoot, deps) {
                 "it by hand if no plane is running.",
         };
     }
+    // BAPI-882: a manifest carrying THIS process's own plane id is its own claim,
+    // not a competitor. Checked after validation and BEFORE the liveness probe,
+    // because the launcher writes `supervisorPid: process.pid` as a placeholder
+    // before spawning the runtime — so the process the probe finds alive is the
+    // very launcher that started us.
+    //
+    // Plane ids are minted per launch (`randomUUID` in cli.ts), so the only
+    // process that can have written a manifest bearing this id is the launcher
+    // that spawned this runtime. That makes identity, not liveness, the correct
+    // discriminator here. This is not a new predicate: `clearPlaneManifest` and
+    // `bindPlaneManifestEpicRun` already gate on exactly `manifest.planeId ===
+    // <own id>`, and `runPlaneRuntime` applies it one layer later. This moves the
+    // recognition earlier, to the only place that was still missing it.
+    //
+    // A live manifest with a DIFFERENT plane id still blocks, unchanged — that is
+    // a genuine second plane and the whole point of the check.
+    if (deps.ownPlaneId !== undefined && read.manifest.planeId === deps.ownPlaneId) {
+        return null;
+    }
     if (!manifestHasLiveProcess(read.manifest, deps.proc)) {
         // Stale. Reported as information so the operator understands why an old
         // manifest is about to be replaced; the claim revalidates before it does.

package/build/plane/shutdown.js

@@ -42,11 +42,13 @@ export async function shutdownPlane(repoRoot, deps) {
             manifestCleared: false,
             members: [],
             messages: ["No plane manifest found — nothing to wind down."],
+            runShutdown: { kind: "unbound" },
         };
     }
     if (read.kind !== "valid") {
         // Deliberately before any liveness probe: an unvalidated record must never
-        // become a signal target, not even a signal-zero one.
+        // become a signal target, not even a signal-zero one — and, as of BAPI-872,
+        // must never authorize a run-stop lookup either.
         return {
             ok: false,
             reason: "unvalidated-manifest",
@@ -54,10 +56,25 @@ export async function shutdownPlane(repoRoot, deps) {
                 "signalled. Inspect the file and remove it by hand once you have confirmed no plane " +
                 "is running.",
             members: [],
+            runShutdown: { kind: "unbound" },
         };
     }
     const manifest = read.manifest;
     const messages = [];
+    // BAPI-872: the server-side run stop, computed ONCE right after the manifest
+    // has passed every validation and identity check above — strictly before the
+    // first process-group signal in every branch that sends one (the sole branch
+    // that never signals, `already-dead`, still runs it first since it is the
+    // earliest safe point and the outcome is reused unchanged in every return
+    // below). A manifest with no bound run never invokes the capability at all.
+    const runShutdown = manifest.epicRunId
+        ? await (deps.stopBoundRun?.(manifest.epicRunId, manifest) ??
+            Promise.resolve({
+                kind: "unavailable",
+                epicRunId: manifest.epicRunId,
+                message: "no run-stop capability was configured for this wind-down",
+            }))
+        : { kind: "unbound" };
     if (!isAnythingAlive(manifest, deps.proc, deps.selfPid)) {
         const cleared = await clearPlaneManifest(repoRoot, manifest.planeId, deps.fs);
         if (!cleared.ok) {
@@ -66,6 +83,7 @@ export async function shutdownPlane(repoRoot, deps) {
                 reason: "clear-failed",
                 message: cleared.message,
                 members: reportMembers(manifest, deps.proc),
+                runShutdown,
             };
         }
         return {
@@ -75,6 +93,7 @@ export async function shutdownPlane(repoRoot, deps) {
             manifestCleared: cleared.removed,
             members: reportMembers(manifest, deps.proc),
             messages: ["Every recorded plane process was already gone; manifest cleared."],
+            runShutdown,
         };
     }
     messages.push(deps.selfPid === undefined
@@ -104,11 +123,12 @@ export async function shutdownPlane(repoRoot, deps) {
             message: `wind-down could not confirm every process was terminated: ${survivors.join(", ")}. ` +
                 "The manifest was RETAINED so `plane down` can be retried.",
             members,
+            runShutdown,
         };
     }
     const cleared = await clearPlaneManifest(repoRoot, manifest.planeId, deps.fs);
     if (!cleared.ok) {
-        return { ok: false, reason: "clear-failed", message: cleared.message, members };
+        return { ok: false, reason: "clear-failed", message: cleared.message, members, runShutdown };
     }
     return {
         ok: true,
@@ -117,6 +137,7 @@ export async function shutdownPlane(repoRoot, deps) {
         manifestCleared: cleared.removed,
         members,
         messages,
+        runShutdown,
     };
 }
 /**
@@ -171,9 +192,56 @@ async function waitForDeath(manifest, deps, budgetMs, pollMs) {
         waited += pollMs;
     }
 }
-/** Render a wind-down result for the terminal. */
+/**
+ * Render the server-side run-shutdown outcome (BAPI-872) as its own message
+ * lines — never claims signalling local processes changed server-side state,
+ * and always names the supported `conductor stop-run` check/remediation
+ * surface for every outcome that is not a fresh committed stop.
+ */
+function formatRunShutdown(outcome) {
+    switch (outcome.kind) {
+        case "unbound":
+            return [
+                "Run shutdown: no epic run is bound to this plane. If a server-side run is " +
+                    "active, this command did NOT stop it and its queued work may remain live. " +
+                    "Run `conductor stop-run --epic-run-id <epic_run_id>` to stop it explicitly.",
+            ];
+        case "committed":
+            return [`Run shutdown: stopped run ${outcome.epicRunId} — its queued work was cancelled.`];
+        case "already-stopped":
+            return [`Run shutdown: run ${outcome.epicRunId} was already stopped; no further action.`];
+        case "terminal":
+            return [
+                `Run shutdown: run ${outcome.epicRunId} is terminal (${outcome.status}) and cannot be ` +
+                    "stopped. Signalling local processes does not change this — run " +
+                    `\`conductor stop-run --epic-run-id ${outcome.epicRunId}\` to check its state.`,
+            ];
+        case "unavailable":
+            return [
+                `Run shutdown: could not reach the Bridge API to stop run ${outcome.epicRunId} ` +
+                    `(${outcome.message}). The run may remain active with queued work — run ` +
+                    `\`conductor stop-run --epic-run-id ${outcome.epicRunId}\` to retry.`,
+            ];
+    }
+}
+/**
+ * Render a wind-down result for the terminal.
+ *
+ * BAPI-872: "Run shutdown" (the server-side epic run) is rendered as its own
+ * section BEFORE "Process shutdown" (the local plane processes) — the two are
+ * independent outcomes, and the ordering makes it visible even when the
+ * process section reads as an unqualified success. The one exception is an
+ * unvalidated manifest: there is no trustworthy record to read a run binding
+ * from, so nothing is claimed about run shutdown at all.
+ */
 export function formatPlaneShutdown(result) {
     const lines = [];
+    const skipRunSection = !result.ok && result.reason === "unvalidated-manifest";
+    if (!skipRunSection) {
+        lines.push(...formatRunShutdown(result.runShutdown));
+        lines.push("");
+        lines.push("Process shutdown:");
+    }
     if (!result.ok) {
         lines.push(`plane down FAILED: ${result.message}`);
     }