@bridge_gpt/mcp-server 0.2.54 → 0.2.55

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

@@ -4,7 +4,7 @@
  * 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`)
+ * runtime workflow-file merge guard (`api/library/vcs/epic_implementer_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).

package/build/plane/cli.js

@@ -402,7 +402,7 @@ async function runDownAction(sinks, overrides) {
  * 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.
+ * `epic-implementer 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
@@ -723,6 +723,40 @@ export async function requestPlaneScopedLanes(args) {
     const result = await requestPlaneManifestLanes(args.repoRoot, args.planeId, args.epicRunId, args.claimScope, createPlaneFsDeps());
     return result.ok ? { ok: true } : { ok: false, reason: result.reason, message: result.message };
 }
+/**
+ * The detached runtime's own output sinks (BAPI-1153).
+ *
+ * The runtime's stdout and stderr are pipes to the LAUNCHER, and the launcher is
+ * allowed to exit long before the plane does — `drive-epic` returns once its run
+ * is created, and a composed bring-up that was refused leaves its control plane
+ * running for a later attach. Once the reading end is gone, Node turns the
+ * runtime's next write into an asynchronous EPIPE that, unhandled, terminates
+ * the process: the plane lost its supervisor at its first event after the
+ * launcher left — a lane request served by attach, a member exit, a shutdown
+ * signal. The launcher side already refuses to let a broken feed take down a
+ * healthy plane; this is the same rule on the runtime side. The feed is
+ * advisory — the manifest and the member logs are the durable record — so a
+ * write that cannot be delivered is dropped, never fatal.
+ */
+function createDetachedRuntimeSinks() {
+    for (const stream of [process.stdout, process.stderr]) {
+        stream.on("error", () => {
+            /* the launcher that was reading this feed has gone; the plane stays up */
+        });
+    }
+    const write = (stream, line) => {
+        try {
+            stream.write(`${line}\n`);
+        }
+        catch {
+            /* a destroyed feed is not a reason to stop supervising */
+        }
+    };
+    return {
+        stdout: (line) => write(process.stdout, line),
+        stderr: (line) => write(process.stderr, line),
+    };
+}
 /** The private detached-runtime action. Never part of the documented surface. */
 async function runRuntimeAction(options, overrides) {
     const executors = options.executors;
@@ -736,10 +770,7 @@ async function runRuntimeAction(options, overrides) {
     // 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`),
-    };
+    const sinks = overrides.sinks ?? createDetachedRuntimeSinks();
     if (typeof planeId !== "string" || planeId.length === 0) {
         sinks.stderr(`plane runtime refused: ${PLANE_ID_ENV_VAR} was not provided by the launcher.`);
         return 1;

package/build/plane/preflight.js

@@ -15,11 +15,97 @@ import path from "path";
 import { PLANE_SERVER_PORT_ENV_VAR, planeCheckFinding, planeCheckPassed, } from "./types.js";
 import { checkPlaneBuildFreshness, checkPlaneRuntimeEntrypoint } from "./build-freshness.js";
 import { checkAlembicHead } from "./alembic-head.js";
-import { manifestHasLiveProcess, readPlaneManifest } from "./manifest.js";
+import { manifestHasLiveProcess, planeManifestLifecycle, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "../claude-login.js";
 import { createReadinessCheck, createReadinessCheckSafely, } from "../readiness-check.js";
 /** Files that must exist for a path to be this repository's root. */
 const REQUIRED_REPO_FILES = ["main.py", "worker.py", "alembic.ini"];
+/** Phases in which a plane already serving a BOUND run can be re-attached to it. */
+const BOUND_RUN_ATTACHABLE_PHASES = [
+    "lanes-starting",
+    "lanes-ready",
+    "ready",
+];
+/**
+ * Classify a VALID, LIVE manifest found at `repoRoot` for attachment. Pure.
+ *
+ * The exact-root comparison is the same one `bindPlaneManifestEpicRun` and the
+ * guarded lifecycle writers apply (`manifest.repoRoot !== repoRoot`), so a
+ * manifest this repository could not bind or request lanes on is never reported
+ * attachable.
+ */
+export function classifyLivePlaneForAttach(repoRoot, manifest, proc) {
+    if (manifest.repoRoot !== repoRoot)
+        return { kind: "foreign-root" };
+    const lifecycle = planeManifestLifecycle(manifest);
+    const probes = probeManifestMembers(manifest, proc);
+    const memberAlive = (name) => probes.some((probe) => probe.member.name === name && probe.liveness === "alive");
+    if (!memberAlive("server") || !memberAlive("worker")) {
+        return { kind: "not-attachable", lifecycle };
+    }
+    if (lifecycle === "control-plane-ready")
+        return { kind: "attachable", manifest };
+    if (BOUND_RUN_ATTACHABLE_PHASES.includes(lifecycle) &&
+        manifest.epicRunId !== undefined &&
+        manifest.laneScope !== undefined) {
+        return { kind: "attachable", manifest };
+    }
+    return { kind: "not-attachable", lifecycle };
+}
+/** Fixed remediation for an occupied port that is not this repository's plane. */
+export const PLANE_PORT_UNRELATED_LISTENER_REMEDIATION = "the listener is not a live plane of this repository — it is often a SIBLING WORKTREE's " +
+    "server. Stop it (or wind down its plane from its own worktree) and run drive-epic again.";
+/** Fixed remediation for a live manifest naming a different repository root. */
+export const PLANE_FOREIGN_ROOT_REMEDIATION = "the plane manifest here names a different repository root (copied or symlinked). " +
+    "Inspect .bridge/plane/plane.json, wind that plane down from its own repository, and run " +
+    "drive-epic again.";
+/** Fixed remediation for this repository's live plane that cannot take a run. */
+export const PLANE_NOT_ATTACHABLE_REMEDIATION = "this repository's plane is running but cannot take a new run — it is still starting, its " +
+    "server or reconciler is gone, its lanes failed, or its lanes were started by hand with " +
+    "their own claim scope. Inspect it with `plane status`; wait for it to finish starting, or " +
+    "wind it down with `plane down` and run drive-epic again to cold-start.";
+/** Fixed remediation when this repository's attachable plane was not attached to. */
+export const PLANE_ATTACHABLE_BASE_URL_REMEDIATION = `do not stop it — point BAPI_BASE_URL at the plane endpoint (http://127.0.0.1:<port>, the port ` +
+    `${PLANE_SERVER_PORT_ENV_VAR} or the default, with no trailing slash) and run drive-epic again to attach.`;
+/**
+ * Describe what occupies the plane port, for a single operator refusal. Pure.
+ *
+ * Every non-attachable occupant keeps its own classification and fix, but they
+ * all render as ONE refusal: the operator has one thing to do, and it depends on
+ * which of these it is.
+ */
+export function describePlanePortOccupant(observation) {
+    switch (observation?.kind) {
+        case "unvalidated":
+            return {
+                classification: "an existing plane manifest could not be validated",
+                remediation: PLANE_MANIFEST_UNREADABLE_REMEDIATION,
+            };
+        case "foreign-root":
+            return {
+                classification: "a live plane manifest names a different repository root",
+                remediation: PLANE_FOREIGN_ROOT_REMEDIATION,
+            };
+        case "not-attachable":
+            return {
+                classification: `this repository's plane is live but not attachable (lifecycle: ${observation.lifecycle})`,
+                remediation: PLANE_NOT_ATTACHABLE_REMEDIATION,
+            };
+        case "attachable":
+            // Reached only when the caller declined to attach — the Bridge API it
+            // talks to is not this plane. Telling the operator to stop the listener
+            // would stop a healthy plane; the fix is the base URL.
+            return {
+                classification: "this repository's own healthy plane holds the port, but BAPI_BASE_URL does not name it",
+                remediation: PLANE_ATTACHABLE_BASE_URL_REMEDIATION,
+            };
+        default:
+            return {
+                classification: "the port is held by a listener that is not a live plane of this repository",
+                remediation: PLANE_PORT_UNRELATED_LISTENER_REMEDIATION,
+            };
+    }
+}
 /** Fixed remediation for a `plane up` run started outside the repository root. */
 export const PLANE_REPOSITORY_ROOT_REMEDIATION = "run `plane up` from the Bridge API repository root (the directory holding main.py, worker.py, and alembic.ini).";
 /** Fixed remediation for an unresolvable Bridge repository identity. */
@@ -148,8 +234,11 @@ export async function runPlanePreflight(repoRoot, 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.
+    const observations = {};
     if (deps.endpoint.ok) {
-        record(await checkServerPort(deps, deps.endpoint.endpoint));
+        const port = await checkServerPort(deps, deps.endpoint.endpoint);
+        record(port);
+        observations.serverPort = port.probe;
     }
     else {
         // The endpoint resolver owns this diagnostic's prose; the structured fix is
@@ -166,7 +255,9 @@ export async function runPlanePreflight(repoRoot, deps) {
         fileExists: (filePath) => fileExists(filePath, deps.fs),
         platform: deps.platform,
     }));
-    record(await checkExistingPlane(repoRoot, deps));
+    const existing = await checkExistingPlane(repoRoot, deps);
+    record(existing);
+    observations.existingPlane = existing.observation;
     const blocking = diagnostics.filter((d) => d.severity === "blocking");
     // `!runtimeEntrypoint.ok` is already covered by the blocking count; it is
     // repeated here so the compiler narrows the union rather than requiring a
@@ -175,12 +266,13 @@ export async function runPlanePreflight(repoRoot, deps) {
     // 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, outcomes };
+        return { ok: false, diagnostics, outcomes, observations };
     }
     return {
         ok: true,
         diagnostics,
         outcomes,
+        observations,
         context: {
             repoRoot,
             repoName: credentials.repoName,
@@ -559,16 +651,22 @@ function createResolverWarningBuffer() {
  * refuse a perfectly good bring-up.
  */
 export async function checkServerPort(deps, endpoint) {
+    // BAPI-1153: the probe's own result kind rides beside the unchanged report, so
+    // a composing caller reads what was observed instead of re-probing the port.
+    const report = await checkServerPortReport(deps, endpoint);
+    return { ...report.report, probe: report.probe };
+}
+async function checkServerPortReport(deps, endpoint) {
     const label = "Local server port";
     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 planeCheckPassed("server-port", label, `${target} is free`);
+        return { report: planeCheckPassed("server-port", label, `${target} is free`), probe: "refused" };
     }
     // Severity is unchanged in both branches: `connected` still blocks, an
     // indeterminate probe still only warns.
     if (result.kind === "connected") {
-        return planeCheckFinding({
+        const occupied = planeCheckFinding({
             check: "server-port",
             severity: "blocking",
             message: `${target} is already accepting connections. ` +
@@ -577,8 +675,9 @@ export async function checkServerPort(deps, endpoint) {
                 "to a free port.",
             remediation: PLANE_SERVER_PORT_OCCUPIED_REMEDIATION,
         }, label, `${target} is already accepting connections`);
+        return { report: occupied, probe: "connected" };
     }
-    return planeCheckFinding({
+    const indeterminate = planeCheckFinding({
         check: "server-port",
         severity: "warning",
         message: `could not determine whether ${target} is free ` +
@@ -588,6 +687,7 @@ export async function checkServerPort(deps, endpoint) {
     // The probe's own `error` text stays in the legacy message for the operator
     // at the terminal and is not copied into the consolidated detail.
     `could not determine whether ${target} is free`);
+    return { report: indeterminate, probe: "error" };
 }
 /**
  * Refuse to start over a plane that is still alive.
@@ -602,11 +702,18 @@ export async function checkExistingPlane(repoRoot, deps) {
     // Three distinct states, three distinct fixes (BAPI-1055): unreadable/malformed,
     // stale, and live. Manifest validation, the liveness probe, and the
     // never-touch-disk rule are all unchanged.
+    //
+    // BAPI-1153: each arm also returns its ATTACH classification. The diagnostics
+    // are untouched — a live plane still blocks `plane up` — and the classification
+    // is read from this one manifest read, never a second one.
     if (read.kind === "missing") {
-        return planeCheckPassed("existing-plane", label, "no plane manifest is present");
+        return {
+            ...planeCheckPassed("existing-plane", label, "no plane manifest is present"),
+            observation: { kind: "none" },
+        };
     }
     if (read.kind !== "valid") {
-        return planeCheckFinding({
+        const unvalidated = planeCheckFinding({
             check: "existing-plane",
             severity: "blocking",
             message: `an existing .bridge/plane/plane.json could not be validated (${read.error}). ` +
@@ -614,6 +721,7 @@ export async function checkExistingPlane(repoRoot, deps) {
                 "it by hand if no plane is running.",
             remediation: PLANE_MANIFEST_UNREADABLE_REMEDIATION,
         }, label, "an existing plane manifest could not be validated");
+        return { ...unvalidated, observation: { kind: "unvalidated" } };
     }
     // 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,
@@ -632,13 +740,17 @@ export async function checkExistingPlane(repoRoot, deps) {
     // 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 planeCheckPassed("existing-plane", label, "the existing manifest carries this launch's own plane id");
+        return {
+            ...planeCheckPassed("existing-plane", label, "the existing manifest carries this launch's own plane id"),
+            observation: { kind: "own-plane" },
+        };
     }
     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.
         // No remediation: the operator has nothing to do — the claim replaces it.
         return {
+            observation: { kind: "stale" },
             diagnostic: {
                 check: "existing-plane",
                 severity: "warning",
@@ -656,7 +768,7 @@ export async function checkExistingPlane(repoRoot, deps) {
             ],
         };
     }
-    return planeCheckFinding({
+    const running = planeCheckFinding({
         check: "existing-plane",
         severity: "blocking",
         message: `a plane is already running (supervisor pid ${read.manifest.supervisorPid}). ` +
@@ -666,6 +778,10 @@ export async function checkExistingPlane(repoRoot, deps) {
     // The supervisor pid stays in the legacy message; the consolidated detail
     // reports the fact, not the process identifier.
     "a plane is already running for this repository");
+    return {
+        ...running,
+        observation: classifyLivePlaneForAttach(repoRoot, read.manifest, deps.proc),
+    };
 }
 async function fileExists(filePath, fs) {
     try {
@@ -702,7 +818,7 @@ export const PLANE_READINESS_DESCRIPTORS = [
 /** Fixed detail for a plane prerequisite the preflight never reported on. */
 const PLANE_UNREPORTED_DETAIL = "not reported — the plane preflight produced no outcome for this prerequisite";
 /** Fixed remediation for a plane prerequisite the preflight never reported on. */
-const PLANE_UNREPORTED_REMEDIATION = "run `plane up` (or `conductor readiness` again) to re-collect the plane preflight; this " +
+const PLANE_UNREPORTED_REMEDIATION = "run `plane up` (or `epic-implementer readiness` again) to re-collect the plane preflight; this " +
     "prerequisite's state is unknown, not healthy.";
 /**
  * Project a plane preflight result into canonical readiness checks.

package/build/plane/shutdown.js

@@ -230,7 +230,7 @@ async function waitForDeath(manifest, deps, budgetMs, pollMs) {
 /**
  * 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
+ * and always names the supported `epic-implementer stop-run` check/remediation
  * surface for every outcome that is not a fresh committed stop.
  */
 function formatRunShutdown(outcome) {
@@ -239,7 +239,7 @@ function formatRunShutdown(outcome) {
             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.",
+                    "Run `epic-implementer 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.`];
@@ -249,13 +249,13 @@ function formatRunShutdown(outcome) {
             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.`,
+                    `\`epic-implementer 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.`,
+                    `\`epic-implementer stop-run --epic-run-id ${outcome.epicRunId}\` to retry.`,
             ];
     }
 }

package/build/readiness-check.js

@@ -2,7 +2,7 @@
  * The canonical shared readiness-check contract (BAPI-1055, AC-6).
  *
  * Conductor prerequisite probing is spread across five loci — `bridge doctor`
- * ({@link file:./install-doctor.ts}), `conductor doctor`
+ * ({@link file:./install-doctor.ts}), `epic-implementer doctor`
  * ({@link file:./conductor/doctor.ts}), `plane` preflight
  * ({@link file:./plane/preflight.ts}), the server `conductor-readiness`
  * collector, and the unified install doctor
@@ -277,7 +277,7 @@ export function createReadinessCheck(input) {
 /** Fixed prose for a check that had to be replaced because it was malformed. */
 export const READINESS_MALFORMED_CHECK_DETAIL = "this prerequisite reported a result that failed the readiness contract, so its real state is unknown";
 /** Fixed remediation for a replaced malformed check. */
-export const READINESS_MALFORMED_CHECK_REMEDIATION = "re-run `conductor readiness`; if it persists, run `conductor doctor` and `install conductor` to re-collect this locus.";
+export const READINESS_MALFORMED_CHECK_REMEDIATION = "re-run `epic-implementer readiness`; if it persists, run `epic-implementer doctor` and `install conductor` to re-collect this locus.";
 /** Fixed label for a replaced malformed check. */
 export const READINESS_MALFORMED_CHECK_LABEL = "Unreadable prerequisite";
 /**
@@ -330,7 +330,7 @@ export function summarizeReadinessChecks(checks) {
 /** Fixed stand-in for a source detail that failed the secret-safety contract. */
 export const READINESS_UNSAFE_DETAIL_REPLACEMENT = "detail withheld — the source reported it in a form this report may not carry";
 /** Fixed stand-in for a source remediation that failed the secret-safety contract. */
-export const READINESS_UNSAFE_REMEDIATION_REPLACEMENT = "re-run `conductor readiness`; this prerequisite's own fix text could not be carried into this report safely.";
+export const READINESS_UNSAFE_REMEDIATION_REPLACEMENT = "re-run `epic-implementer readiness`; this prerequisite's own fix text could not be carried into this report safely.";
 /**
  * Build a check, degrading REJECTED prose rather than losing the finding — and
  * never throwing.