@bridge_gpt/mcp-server 0.2.53 → 0.2.54

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/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

package/build/plane/status.js

@@ -6,7 +6,7 @@
  * a hole in the roster (a member that crashed and was deliberately not
  * restarted) is precisely what this command exists to *show*.
  */
-import { probeManifestMembers, readPlaneManifest, } from "./manifest.js";
+import { planeManifestLifecycle, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
 import { PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
 /** Read the manifest and probe every recorded pid. Strictly read-only. */
 export async function getPlaneStatus(repoRoot, deps) {
@@ -32,6 +32,8 @@ export async function getPlaneStatus(repoRoot, deps) {
         supervisorPgid: manifest.supervisorPgid,
         supervisorLiveness: deps.proc.isAlive(manifest.supervisorPid),
         unrecognizedMemberNames: read.unrecognizedMemberNames,
+        lifecycle: planeManifestLifecycle(manifest),
+        epicRunId: manifest.epicRunId ?? null,
         createdAt: manifest.createdAt,
         updatedAt: manifest.updatedAt,
         members: probeManifestMembers(manifest, deps.proc).map((probe) => ({
@@ -45,6 +47,36 @@ export async function getPlaneStatus(repoRoot, deps) {
         })),
     };
 }
+/**
+ * The lifecycle phase, in operational terms rather than as a bare enum value.
+ *
+ * Each line says what has happened AND what is being waited for, because the
+ * intermediate phases are the ones an operator sees when something is wrong and
+ * "lanes-starting" alone does not say whether that is normal.
+ *
+ * `ready` deliberately does NOT claim the run is dispatchable. A plane can be
+ * fully up while the reconciler still holds dispatch — feature-branch index
+ * preparation is the common case — and a status line that conflated "every
+ * process is up" with "work is flowing" would send an operator hunting for a
+ * problem in the plane that is not there.
+ */
+function describeLifecycle(phase) {
+    switch (phase) {
+        case "control-plane-starting":
+            return "control plane starting (server, reconciler)";
+        case "control-plane-ready":
+            return "control plane ready — waiting for a scoped executor-lane request";
+        case "lanes-starting":
+            return "executor lanes starting — each waits for its own heartbeat gate";
+        case "lanes-ready":
+            return "executor lanes ready — starting the dead-man observer";
+        case "ready":
+            return "plane ready (this reports PROCESSES, not whether the run is dispatchable)";
+        case "lanes-failed":
+            return ("executor lanes FAILED — the lane cohort was stopped and the control plane was " +
+                "left running; nothing is claiming jobs. Wind it down with `plane down`.");
+    }
+}
 /** One line per member: name, state, exit status where known, log path. */
 export function formatPlaneStatus(result) {
     if (!result.ok)
@@ -55,6 +87,8 @@ export function formatPlaneStatus(result) {
     const lines = [
         `Plane ${result.planeId}`,
         `  supervisor   pid ${result.supervisorPid} (group ${result.supervisorPgid}) — ${result.supervisorLiveness}`,
+        `  lifecycle    ${describeLifecycle(result.lifecycle)}`,
+        ...(result.epicRunId !== null ? [`  epic run     ${result.epicRunId}`] : []),
         `  started      ${result.createdAt}`,
         `  updated      ${result.updatedAt}`,
         "",