@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/plane/manifest.js

@@ -17,7 +17,7 @@
  *    argv, and no credential field, and unknown keys are rejected outright.
  */
 import path from "path";
-import { PLANE_MANIFEST_FILENAME, PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS, PLANE_RUNTIME_DIR, } from "./types.js";
+import { PLANE_LIFECYCLE_PHASES, PLANE_MANIFEST_FILENAME, PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS, PLANE_RUNTIME_DIR, } from "./types.js";
 /**
  * Derive every runtime path beneath a validated repository root.
  *
@@ -54,7 +54,13 @@ const MANIFEST_KEYS = new Set([
     "members",
     // BAPI-872: the optional server-side epic-run binding.
     "epicRunId",
+    // BAPI-1102: the two-phase lifecycle state and the claim scope phase two
+    // starts its lanes with. Both optional; both absent on a v1/v2 manifest.
+    "lifecycle",
+    "laneScope",
 ]);
+/** Every legal `lifecycle` value, as a set for the strict parse below. */
+const LIFECYCLE_PHASES = new Set(PLANE_LIFECYCLE_PHASES);
 /** 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();
@@ -144,6 +150,16 @@ export function parsePlaneManifest(value) {
     if (record.epicRunId !== undefined && !isNonBlankTrimmedString(record.epicRunId)) {
         return { ok: false, error: "manifest epic run id is malformed" };
     }
+    // BAPI-1102: both are optional and both are validated STRICTLY when present.
+    // Absence means a v1/v2 manifest or a single-phase bring-up, and the reader
+    // resolves absence to `"ready"` — an older build only ever wrote a manifest for
+    // a plane whose whole roster had started.
+    if (record.lifecycle !== undefined && !LIFECYCLE_PHASES.has(record.lifecycle)) {
+        return { ok: false, error: "manifest lifecycle phase is malformed" };
+    }
+    const laneScope = parseManifestLaneScope(record.laneScope);
+    if (!laneScope.ok)
+        return { ok: false, error: laneScope.error };
     const members = [];
     const unrecognizedMemberNames = [];
     const seen = new Set();
@@ -235,9 +251,63 @@ export function parsePlaneManifest(value) {
             updatedAt: record.updatedAt,
             members,
             ...(record.epicRunId !== undefined ? { epicRunId: record.epicRunId } : {}),
+            ...(record.lifecycle !== undefined
+                ? { lifecycle: record.lifecycle }
+                : {}),
+            ...(laneScope.scope !== undefined ? { laneScope: laneScope.scope } : {}),
         },
     };
 }
+/**
+ * Validate the optional `laneScope` record (BAPI-1102).
+ *
+ * Strict, and strict for a specific reason: this value crosses a PROCESS
+ * boundary. The composed caller writes it and the detached runtime reads it, so
+ * it is the one place an untrusted-looking value can become executor argv. Every
+ * shape is checked before it is trusted, and a malformed value is a parse
+ * failure rather than a coerced default.
+ *
+ * It carries run ids and a discriminant only. No credential, environment object,
+ * or argv array may ever be added here — the manifest lives on disk for the
+ * lifetime of the plane, which is the reason the record has always been free of
+ * secrets.
+ */
+function parseManifestLaneScope(value) {
+    if (value === undefined)
+        return { ok: true };
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, error: "manifest lane scope is not an object" };
+    }
+    const record = value;
+    if (record.kind === "repo-wide") {
+        if (Object.keys(record).length !== 1) {
+            return { ok: false, error: "manifest lane scope has unsupported fields" };
+        }
+        return { ok: true, scope: { kind: "repo-wide" } };
+    }
+    if (record.kind !== "epic-runs") {
+        return { ok: false, error: "manifest lane scope kind is malformed" };
+    }
+    if (Object.keys(record).length !== 2 || !Array.isArray(record.epicRunIds)) {
+        return { ok: false, error: "manifest lane scope epic run ids are malformed" };
+    }
+    const ids = record.epicRunIds;
+    if (ids.length === 0 || !ids.every((id) => isNonBlankTrimmedString(id))) {
+        return { ok: false, error: "manifest lane scope epic run ids are malformed" };
+    }
+    return { ok: true, scope: { kind: "epic-runs", epicRunIds: ids } };
+}
+/**
+ * The phase this manifest describes, resolving ABSENCE to `"ready"`.
+ *
+ * The single reader of that rule. A manifest written before BAPI-1102 describes a
+ * plane whose entire roster started before the file was last written, so `ready`
+ * is the truthful reading — and it is the reading that keeps `plane status` and
+ * `plane down` behaving identically on a legacy plane.
+ */
+export function planeManifestLifecycle(manifest) {
+    return manifest.lifecycle ?? "ready";
+}
 /**
  * Read and validate the manifest, distinguishing every outcome.
  *
@@ -463,6 +533,144 @@ export async function bindPlaneManifestEpicRun(repoRoot, planeId, epicRunId, fs)
     }
     return { ok: true, alreadyBound: false };
 }
+/**
+ * Read + validate + identity-check the manifest for a guarded write.
+ *
+ * Shared by every operation below so the three refusals that precede any mutation
+ * are stated once. A caller that wrote its own version of this would eventually
+ * mutate a record it had not validated.
+ */
+async function readOwnedManifest(repoRoot, planeId, 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})`,
+        };
+    }
+    if (read.manifest.planeId !== planeId || read.manifest.repoRoot !== repoRoot) {
+        return {
+            ok: false,
+            reason: "identity-mismatch",
+            message: "plane manifest belongs to a different plane identity",
+        };
+    }
+    return { ok: true, manifest: read.manifest };
+}
+/** Persist a manifest mutation, converting a filesystem failure into a result. */
+async function writeGuardedManifest(manifest, fs) {
+    try {
+        const updated = { ...manifest, updatedAt: new Date().toISOString() };
+        await writePlaneManifest(updated, fs);
+        return { ok: true, manifest: updated };
+    }
+    catch (err) {
+        // The CODE only. A thrown filesystem error carries a path, and this message
+        // reaches an operator's terminal.
+        const code = err?.code;
+        return {
+            ok: false,
+            reason: "error",
+            message: `plane manifest could not be written${code ? ` (${code})` : ""}`,
+        };
+    }
+}
+/**
+ * Move the plane from one lifecycle phase to the next, atomically.
+ *
+ * `expected` is REQUIRED and is the concurrency control. Writing the phase
+ * unconditionally would let a stale writer — a retried request, or a runtime that
+ * resumed after a pause — rewind a plane that has already progressed, which for
+ * `lanes-ready` → `control-plane-ready` would mean the runtime waiting forever
+ * for a phase-two request that had already been served.
+ */
+export async function transitionPlaneManifestLifecycle(repoRoot, planeId, expected, next, fs) {
+    const owned = await readOwnedManifest(repoRoot, planeId, fs);
+    if (!owned.ok)
+        return owned;
+    const current = planeManifestLifecycle(owned.manifest);
+    if (current !== expected) {
+        return {
+            ok: false,
+            reason: "phase-conflict",
+            message: `plane is ${current}, not ${expected}`,
+        };
+    }
+    return writeGuardedManifest({ ...owned.manifest, lifecycle: next }, fs);
+}
+/**
+ * Request phase two: bind the run and record the claim scope the lanes will use.
+ *
+ * The single writer of `laneScope`, and it binds `epicRunId` in the SAME atomic
+ * write. Doing them together is what makes "one composed plane serves exactly one
+ * run" hold: a plane already bound to a different run is refused here, before any
+ * lane exists, rather than being discovered after lanes are already claiming for
+ * the wrong run.
+ *
+ * A composed plane is deliberately SINGLE-RUN. Appending a second run scope to
+ * live lanes was considered and rejected: the lanes are already running with a
+ * fixed argv, so a second scope would require restarting them, and a restart
+ * mid-run is indistinguishable to the reconciler from a lane crash. A second epic
+ * gets a second plane.
+ *
+ * Re-requesting the SAME run is an idempotent no-op when the plane has already
+ * moved past `control-plane-ready`, so a retried composed bring-up does not
+ * refuse a plane it already set up.
+ */
+export async function requestPlaneManifestLanes(repoRoot, planeId, epicRunId, laneScope, fs) {
+    const owned = await readOwnedManifest(repoRoot, planeId, fs);
+    if (!owned.ok)
+        return owned;
+    const manifest = owned.manifest;
+    if (manifest.epicRunId !== undefined && manifest.epicRunId !== epicRunId) {
+        return {
+            ok: false,
+            reason: "run-conflict",
+            message: `plane is already bound to a different epic run (${manifest.epicRunId})`,
+        };
+    }
+    const current = planeManifestLifecycle(manifest);
+    if (current !== "control-plane-ready") {
+        // Already served for THIS run: report success rather than a conflict, so a
+        // retry of the composed flow converges instead of failing on its own work.
+        if (manifest.epicRunId === epicRunId && manifest.laneScope !== undefined) {
+            return { ok: true, manifest };
+        }
+        return {
+            ok: false,
+            reason: "phase-conflict",
+            message: `plane is ${current}, not control-plane-ready`,
+        };
+    }
+    return writeGuardedManifest({ ...manifest, epicRunId, laneScope }, fs);
+}
+/**
+ * Append members to a live manifest, guarded by plane identity.
+ *
+ * Used by the detached runtime as each phase-two cohort begins spawning, so
+ * `plane status` and `plane down` can see and signal members that did not exist
+ * when the manifest was first claimed. A name already listed is REPLACED rather
+ * than duplicated: the manifest's own parse rejects a repeated member name, and
+ * producing a record this module's reader would refuse is never the right way to
+ * report progress.
+ */
+export async function appendPlaneManifestMembers(repoRoot, planeId, members, fs) {
+    const owned = await readOwnedManifest(repoRoot, planeId, fs);
+    if (!owned.ok)
+        return owned;
+    const byName = new Map(owned.manifest.members.map((m) => [m.name, m]));
+    for (const member of members)
+        byName.set(member.name, member);
+    return writeGuardedManifest({ ...owned.manifest, members: [...byName.values()] }, fs);
+}
 /**
  * Take exclusive ownership of `.bridge/plane/plane.json`.
  *

package/build/plane/member-roster.js

@@ -25,6 +25,7 @@
 import path from "path";
 import { PLANE_OBSERVER_MODE_ENV, PLANE_OBSERVER_MODE_VALUE, PLANE_SERVER_HOST, PLANE_SERVER_PORT, PLANE_SERVER_PORT_ENV_VAR, } from "./types.js";
 import { relativeLogPathFor } from "./manifest.js";
+import { EXECUTOR_CLAIM_SCOPE_REQUIRED_MESSAGE, executorClaimScopeArgs, } from "../executor/claim-scope.js";
 /** How long a member with a readiness probe gets to start listening. */
 export const PLANE_READINESS_TIMEOUT_MS = 60_000;
 /**
@@ -310,6 +311,18 @@ export function buildPlaneMemberRoster(params) {
             timeoutMs: PLANE_RECONCILER_READINESS_TIMEOUT_MS,
         },
     };
+    // BAPI-1102 — refused HERE, not merely documented. A lane built without a
+    // scope is a lane that exits at startup (BAPI-1026), and a roster that could
+    // produce one would turn a missing flag into a member crash and a full plane
+    // rollback. The public parser already refuses first; this is the structural
+    // backstop for every internal caller.
+    if (executors > 0 && params.claimScope === undefined) {
+        throw new Error(EXECUTOR_CLAIM_SCOPE_REQUIRED_MESSAGE);
+    }
+    // Built ONCE, outside the lane loop: every lane of one plane serves the same
+    // scope, and rendering it per-lane would be a chance for two lanes of the same
+    // plane to disagree.
+    const scopeArgs = params.claimScope === undefined ? [] : executorClaimScopeArgs(params.claimScope);
     const executorMembers = [];
     for (let lane = 1; lane <= executors; lane += 1) {
         const name = `executor-${lane}`;
@@ -334,6 +347,9 @@ export function buildPlaneMemberRoster(params) {
                 endpoint.baseUrl,
                 "--executor-id",
                 executorId,
+                // Appended LAST and rendered by the executor's OWN argv builder, so the
+                // flag spelling here cannot drift from the parser that reads it.
+                ...scopeArgs,
             ],
             cwd,
             env,
@@ -361,6 +377,60 @@ export function buildPlaneMemberRoster(params) {
     }
     return [server, worker, ...executorMembers, observer];
 }
+// ---------------------------------------------------------------------------
+// BAPI-1102 — the two-phase roster selectors.
+// ---------------------------------------------------------------------------
+// Each is a FILTER over the full roster rather than a second builder, and that
+// is the whole design. Every spec — argv, environment, log path, readiness gate,
+// the executor id minted once and used twice — keeps exactly one definition, so
+// a phase roster cannot drift from the roster the single-phase path builds. It
+// also makes the composition law checkable and cheap:
+//
+//   [...controlPlane, ...executorLanes, ...observer] === buildPlaneMemberRoster(...)
+//
+// which a unit test asserts, so the split can never silently drop or reorder a
+// member. A pair of independent builders would have needed that property
+// re-established by inspection after every future edit.
+/** Is this the name of an executor lane? */
+function isExecutorLaneName(name) {
+    return name.startsWith("executor-");
+}
+/**
+ * Phase one: the server and the reconciler worker, in that order.
+ *
+ * ZERO executor lanes, so no claim scope is required or accepted — which is the
+ * one legitimate zero-lane roster in the system. It is INTERNAL: there is no
+ * public `plane up --executors 0`, because "start a plane that can never do any
+ * work" is not a state an operator should be able to ask for by hand.
+ *
+ * The observer is deliberately NOT here. See {@link PlaneLifecyclePhase}.
+ */
+export function buildPlaneControlPlaneRoster(params) {
+    return buildPlaneMemberRoster({ ...params, executors: 0 }).filter((member) => member.name === "server" || member.name === "worker");
+}
+/**
+ * Phase two, part one: the scoped executor lanes.
+ *
+ * `claimScope` is REQUIRED by the type, not merely by the runtime check inside
+ * the builder — a lane roster is the one thing that cannot be built without a
+ * scope, and making that a compile-time fact removes the whole class of caller
+ * that forgets.
+ */
+export function buildPlaneExecutorLaneRoster(params) {
+    return buildPlaneMemberRoster(params).filter((member) => isExecutorLaneName(member.name));
+}
+/**
+ * Phase two, part two: the dead-man observer, started LAST.
+ *
+ * Split out so the runtime can start it only after every lane's per-instance
+ * heartbeat gate has closed. Starting it at control-plane time would put it on a
+ * plane with zero executor lanes for however long run creation takes — precisely
+ * the state its executor-component sweep would alert on, and precisely the boot
+ * noise the ordering contract above exists to prevent.
+ */
+export function buildPlaneObserverRoster(params) {
+    return buildPlaneMemberRoster({ ...params, executors: 0 }).filter((member) => member.name === "observer");
+}
 /**
  * Deterministic, distinct, CLI-safe executor id for one lane.
  *

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

@@ -18,7 +18,7 @@
  *   liveness is unknown, the manifest is retained so a later `plane down` can
  *   retry. Clearing it would orphan the survivor permanently.
  */
-import { clearPlaneManifest, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
+import { clearPlaneManifest, planeManifestLifecycle, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
 /** SIGTERM→SIGKILL grace period. */
 export const PLANE_SHUTDOWN_GRACE_MS = 10_000;
 /** How long stragglers get after SIGKILL before they are declared unknown. */
@@ -72,6 +72,19 @@ export async function shutdownPlane(repoRoot, deps) {
     }
     const manifest = read.manifest;
     const messages = [];
+    // BAPI-1102 — say WHICH phase is being wound down when it is not a complete
+    // plane. Every intermediate phase is windable by exactly the same mechanism as
+    // a finished one (the whole plane shares one process group, and members that
+    // were never spawned have no pid to probe), so nothing special happens here —
+    // but an operator stopping a plane that is still starting deserves to be told
+    // that is what they stopped, rather than reading a report that looks like a
+    // plane with missing members.
+    const lifecycle = planeManifestLifecycle(manifest);
+    if (lifecycle !== "ready") {
+        messages.push(`This plane had not finished starting (${lifecycle}). Members that had not been ` +
+            "spawned yet have no pid and are reported as such; every member that HAD started is " +
+            "signalled with the rest of the process group.");
+    }
     if (read.unrecognizedMemberNames.length > 0) {
         // Said out loud, never assumed harmless (BAPI-1029). The wind-down still
         // reaches these members — the whole plane shares one process group, and the
@@ -217,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) {
@@ -226,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.`];
@@ -236,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.`,
             ];
     }
 }