@bridge_gpt/mcp-server 0.2.66 → 0.2.67

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_LIFECYCLE_PHASES, 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_RESTART_FAILURE_REASONS, PLANE_RESTART_REQUEST_FILENAME, PLANE_RESTART_RESULT_FILENAME, PLANE_RUNTIME_DIR, } from "./types.js";
 /**
  * Derive every runtime path beneath a validated repository root.
  *
@@ -27,12 +27,62 @@ import { PLANE_LIFECYCLE_PHASES, PLANE_MANIFEST_FILENAME, PLANE_MANIFEST_SUPPORT
  */
 export function getPlanePaths(repoRoot) {
     const planeDir = path.join(repoRoot, ".bridge", "plane");
+    const snapshotsDir = path.join(planeDir, "snapshots");
     return {
         planeDir,
         manifestPath: path.join(planeDir, PLANE_MANIFEST_FILENAME),
         logPathFor: (member) => path.join(planeDir, `${member}.log`),
+        snapshotsDir,
+        // The leaf is the ONLY variable part and it is shape-checked before it is
+        // joined: a value that is not a bare hexadecimal commit id throws rather than
+        // producing a path, so no caller-supplied string can steer a snapshot path
+        // out of `.bridge/plane/snapshots/`.
+        snapshotPathFor: (sha) => {
+            if (!isFullCommitSha(sha)) {
+                throw new Error("a snapshot path can only be derived from a full hexadecimal commit id");
+            }
+            return path.join(snapshotsDir, sha);
+        },
+        // Fixed file names. The restart request and result are correlated by the
+        // identifiers INSIDE them, never by a name derived from their content.
+        restartRequestPath: path.join(planeDir, PLANE_RESTART_REQUEST_FILENAME),
+        restartResultPath: path.join(planeDir, PLANE_RESTART_RESULT_FILENAME),
     };
 }
+/**
+ * A full Git object id: 40 hexadecimal characters (SHA-1) or 64 (SHA-256).
+ *
+ * Lowercase only. `git rev-parse` prints lowercase, so an uppercase spelling is
+ * not something this code produced, and accepting it would let two spellings of
+ * one commit name two different snapshot directories.
+ */
+export function isFullCommitSha(value) {
+    return typeof value === "string" && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(value);
+}
+/**
+ * A canonical absolute path: absolute, already normalized (no `.` or `..`
+ * segment, no doubled or trailing separator), and free of control characters.
+ *
+ * "Canonical" here is lexical — it says the string IS its own normal form — and
+ * it does not claim the path exists or is free of symlinks. Symlink resolution
+ * needs a filesystem and belongs to the snapshot module's ownership checks.
+ */
+export function isCanonicalAbsolutePath(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f]/.test(value))
+        return false;
+    if (!path.isAbsolute(value))
+        return false;
+    return path.normalize(value) === value && (value === path.parse(value).root || !value.endsWith(path.sep));
+}
+export function planeManifestSnapshot(manifest) {
+    if (manifest.snapshotPath !== undefined && manifest.snapshotSha !== undefined) {
+        return { kind: "pinned", snapshot: { path: manifest.snapshotPath, sha: manifest.snapshotSha } };
+    }
+    return { kind: "legacy" };
+}
 /** Repository-relative log path recorded in the manifest for a member. */
 export function relativeLogPathFor(member) {
     return `${PLANE_RUNTIME_DIR}/${member}.log`;
@@ -42,7 +92,10 @@ const VALID_STATES = new Set([
     "running",
     "ready",
     "exited",
+    "restarting",
 ]);
+/** Every legal `restartFailure` value, for the strict member parse. */
+const RESTART_FAILURE_REASONS = new Set(PLANE_RESTART_FAILURE_REASONS);
 const MANIFEST_KEYS = new Set([
     "schemaVersion",
     "planeId",
@@ -58,6 +111,9 @@ const MANIFEST_KEYS = new Set([
     // starts its lanes with. Both optional; both absent on a v1/v2 manifest.
     "lifecycle",
     "laneScope",
+    // BAPI-1362: the pinned code snapshot. Optional, and only ever both or neither.
+    "snapshotPath",
+    "snapshotSha",
 ]);
 /** Every legal `lifecycle` value, as a set for the strict parse below. */
 const LIFECYCLE_PHASES = new Set(PLANE_LIFECYCLE_PHASES);
@@ -72,6 +128,9 @@ const MEMBER_KEYS = new Set([
     "exitCode",
     "exitSignal",
     "logPath",
+    // BAPI-1362: both optional, both absent on a pre-v4 manifest.
+    "cwd",
+    "restartFailure",
 ]);
 /**
  * `server`, `worker`, `observer`, or `executor-<positive integer>`. Nothing else.
@@ -160,6 +219,9 @@ export function parsePlaneManifest(value) {
     const laneScope = parseManifestLaneScope(record.laneScope);
     if (!laneScope.ok)
         return { ok: false, error: laneScope.error };
+    const snapshot = parseManifestSnapshot(record.snapshotPath, record.snapshotSha, record.repoRoot);
+    if (!snapshot.ok)
+        return { ok: false, error: snapshot.error };
     const members = [];
     const unrecognizedMemberNames = [];
     const seen = new Set();
@@ -215,6 +277,20 @@ export function parsePlaneManifest(value) {
         if (member.logPath !== relativeLogPathFor(member.name)) {
             return { ok: false, error: `manifest member '${member.name}' has an unexpected log path` };
         }
+        // BAPI-1362. `cwd`, when present, must be its own canonical absolute form:
+        // it is later compared against a real checkout path to decide whether a
+        // base-worktree fast-forward is safe, and a relative or `..`-bearing value
+        // could be made to match or to miss a path it does not name.
+        if (member.cwd !== undefined && !isCanonicalAbsolutePath(member.cwd)) {
+            return {
+                ok: false,
+                error: `manifest member '${member.name}' has a working directory that is not a canonical absolute path`,
+            };
+        }
+        if (member.restartFailure !== undefined &&
+            !RESTART_FAILURE_REASONS.has(member.restartFailure)) {
+            return { ok: false, error: `manifest member '${member.name}' has an invalid restart failure` };
+        }
         members.push({
             name: member.name,
             pid: member.pid,
@@ -222,6 +298,10 @@ export function parsePlaneManifest(value) {
             exitCode: member.exitCode,
             exitSignal: member.exitSignal,
             logPath: member.logPath,
+            ...(member.cwd !== undefined ? { cwd: member.cwd } : {}),
+            ...(member.restartFailure !== undefined
+                ? { restartFailure: member.restartFailure }
+                : {}),
         });
     }
     // Every listed member was unrecognized: there is nothing this build can act
@@ -255,9 +335,48 @@ export function parsePlaneManifest(value) {
                 ? { lifecycle: record.lifecycle }
                 : {}),
             ...(laneScope.scope !== undefined ? { laneScope: laneScope.scope } : {}),
+            ...(snapshot.snapshot !== undefined
+                ? { snapshotPath: snapshot.snapshot.path, snapshotSha: snapshot.snapshot.sha }
+                : {}),
         },
     };
 }
+/**
+ * Validate the optional snapshot identity pair (BAPI-1362).
+ *
+ * Three rules, each a hard rejection rather than a coerced default:
+ *
+ * 1. The two fields arrive TOGETHER. A half-pinned record would let a consumer
+ *    read "pinned" off one field while the other said nothing.
+ * 2. The SHA is a full lowercase commit id.
+ * 3. The path is EXACTLY `<repoRoot>/.bridge/plane/snapshots/<sha>`. The manifest
+ *    is untrusted input that later steers a restart at a directory, so it is
+ *    never allowed to name an arbitrary path — the only legal spelling is the one
+ *    this build derives from the repository root and the SHA.
+ */
+function parseManifestSnapshot(snapshotPath, snapshotSha, repoRoot) {
+    if (snapshotPath === undefined && snapshotSha === undefined)
+        return { ok: true };
+    if (snapshotPath === undefined) {
+        return { ok: false, error: "manifest snapshot SHA is present without its snapshot path" };
+    }
+    if (snapshotSha === undefined) {
+        return { ok: false, error: "manifest snapshot path is present without its snapshot SHA" };
+    }
+    if (!isFullCommitSha(snapshotSha)) {
+        return { ok: false, error: "manifest snapshot SHA is not a full commit id" };
+    }
+    if (typeof repoRoot !== "string" || !isCanonicalAbsolutePath(repoRoot)) {
+        return { ok: false, error: "manifest snapshot cannot be validated without a canonical repository root" };
+    }
+    if (snapshotPath !== getPlanePaths(repoRoot).snapshotPathFor(snapshotSha)) {
+        return {
+            ok: false,
+            error: "manifest snapshot path is not the canonical snapshot location for its SHA",
+        };
+    }
+    return { ok: true, snapshot: { path: snapshotPath, sha: snapshotSha } };
+}
 /**
  * Validate the optional `laneScope` record (BAPI-1102).
  *

package/build/plane/member-roster.js

@@ -65,19 +65,82 @@ export const PLANE_RECONCILER_READINESS_TIMEOUT_MS = 120_000;
  * fail a lane that recovers on its second try.
  */
 export const PLANE_EXECUTOR_READINESS_TIMEOUT_MS = 90_000;
-/** Executable used for the Python members. Overridable for a non-default venv. */
-export function resolvePythonExecutable(env) {
+/** Path of a virtualenv executable inside the operator checkout. */
+function operatorVenvExecutable(lookup, name) {
+    return lookup.platform === "win32"
+        ? path.join(lookup.operatorRoot, ".venv", "Scripts", `${name}.exe`)
+        : path.join(lookup.operatorRoot, ".venv", "bin", name);
+}
+/**
+ * Executable used for the Python members.
+ *
+ * Precedence: the documented `BAPI_PLANE_PYTHON` override, then the operator
+ * checkout's absolute `.venv` interpreter when one is found, then the bare name.
+ * The last step is the historical behavior, kept for a machine that keeps its
+ * environment elsewhere: an ABSOLUTE path to a file that is not there would turn
+ * "uses whatever `python` is on PATH" into "every member fails to spawn".
+ */
+export function resolvePythonExecutable(env, venv) {
     const configured = env.BAPI_PLANE_PYTHON;
-    return typeof configured === "string" && configured.trim().length > 0
-        ? configured.trim()
-        : "python";
+    if (typeof configured === "string" && configured.trim().length > 0)
+        return configured.trim();
+    if (venv) {
+        const candidate = operatorVenvExecutable(venv, "python");
+        if (venv.fileExists(candidate))
+            return candidate;
+    }
+    return "python";
 }
-/** Executable used for the server member. */
-export function resolveUvicornExecutable(env) {
+/** Executable used for the server member. Same precedence as {@link resolvePythonExecutable}. */
+export function resolveUvicornExecutable(env, venv) {
     const configured = env.BAPI_PLANE_UVICORN;
-    return typeof configured === "string" && configured.trim().length > 0
-        ? configured.trim()
-        : "uvicorn";
+    if (typeof configured === "string" && configured.trim().length > 0)
+        return configured.trim();
+    if (venv) {
+        const candidate = operatorVenvExecutable(venv, "uvicorn");
+        if (venv.fileExists(candidate))
+            return candidate;
+    }
+    return "uvicorn";
+}
+/**
+ * Drop import-path entries that point at the MOVING operator checkout from a
+ * snapshot member's `PYTHONPATH` (BAPI-1362).
+ *
+ * A Python member launched from a snapshot imports its application code from the
+ * snapshot because the interpreter puts the script directory (or, for uvicorn,
+ * the working directory) first on `sys.path`. An inherited `PYTHONPATH` entry
+ * that names the operator checkout would sit beside that and could still satisfy
+ * an import the snapshot does not — silently loading code that changes under the
+ * plane. Entries that are the operator checkout or inside it (other than the
+ * snapshot itself, which lives inside it) are removed; every unrelated entry is
+ * kept, so an operator's own library path is unaffected.
+ *
+ * Returns the environment to use. The input is never mutated.
+ */
+export function sanitizeSnapshotPythonPath(env, operatorRoot, snapshotPath) {
+    const raw = env.PYTHONPATH;
+    if (typeof raw !== "string" || raw.length === 0)
+        return env;
+    const insideOperator = (entry) => {
+        const resolved = path.resolve(entry);
+        const relative = path.relative(operatorRoot, resolved);
+        if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+            const toSnapshot = path.relative(snapshotPath, resolved);
+            const inSnapshot = toSnapshot === "" || (!toSnapshot.startsWith("..") && !path.isAbsolute(toSnapshot));
+            return !inSnapshot;
+        }
+        return false;
+    };
+    const kept = raw
+        .split(path.delimiter)
+        .filter((entry) => entry.length > 0 && !insideOperator(entry));
+    const next = { ...env };
+    if (kept.length === 0)
+        delete next.PYTHONPATH;
+    else
+        next.PYTHONPATH = kept.join(path.delimiter);
+    return next;
 }
 /** Highest port number a TCP endpoint can occupy. */
 const MAX_TCP_PORT = 65_535;
@@ -218,7 +281,19 @@ export function buildPlaneObserverEnv(childEnv) {
 export function buildPlaneMemberRoster(params) {
     const { context, executors, parentEnv, nodeExecutable } = params;
     const env = buildPlaneChildEnv(parentEnv, context);
+    // BAPI-1362 — the working directory the PYTHON members run from: the pinned
+    // snapshot when preflight prepared one, otherwise the operator checkout (the
+    // unpinned behavior every pre-snapshot caller has). Executor lanes are
+    // deliberately NOT moved: they run compiled Node from this repository's
+    // gitignored build tree by absolute path, which a snapshot does not contain and
+    // a checkout update does not change.
     const cwd = context.repoRoot;
+    const pythonCwd = context.snapshot?.path ?? context.repoRoot;
+    // Only a snapshot launch needs the import-path guard; an unpinned launch keeps
+    // the exact environment it always had.
+    const pythonEnv = (base) => context.snapshot
+        ? sanitizeSnapshotPythonPath(base, context.repoRoot, context.snapshot.path)
+        : base;
     // One resolved endpoint for the bind argv, the readiness probe, every
     // executor's `--base-url`, and the child `BAPI_BASE_URL`. Reading the default
     // constants here instead is what would let uvicorn bind one port while the
@@ -226,7 +301,7 @@ export function buildPlaneMemberRoster(params) {
     const endpoint = context.endpoint;
     const server = {
         name: "server",
-        command: resolveUvicornExecutable(parentEnv),
+        command: resolveUvicornExecutable(parentEnv, params.venv),
         // NO `--reload`, at any layer, ever. `--reload` restarts the worker process
         // on file change and drops in-flight MCP calls, which during a conductor run
         // silently truncates long tool calls the executor is waiting on.
@@ -237,14 +312,14 @@ export function buildPlaneMemberRoster(params) {
             "--port",
             String(endpoint.port),
         ],
-        cwd,
+        cwd: pythonCwd,
         // BAPI-1279 — the server member runs NO scheduler. `main.py` starts one
         // whenever DISABLE_SCHEDULER is unset, and that scheduler ticks the
         // reconciler: the plane would run two reconcilers of its own, and the
         // pre-worker foreign-reconciler guard would see this server's heartbeat
         // and refuse the plane's own worker. The `worker` member below is the one
         // reconciler, exactly as a Heroku web dyno leaves scheduling to `worker:`.
-        env: { ...env, DISABLE_SCHEDULER: "true" },
+        env: pythonEnv({ ...env, DISABLE_SCHEDULER: "true" }),
         logPath: relativeLogPathFor("server"),
         readiness: {
             kind: "tcp",
@@ -283,19 +358,19 @@ export function buildPlaneMemberRoster(params) {
      */
     const observer = {
         name: "observer",
-        command: resolvePythonExecutable(parentEnv),
+        command: resolvePythonExecutable(parentEnv, params.venv),
         args: ["worker.py"],
-        cwd,
-        env: buildPlaneObserverEnv(env),
+        cwd: pythonCwd,
+        env: pythonEnv(buildPlaneObserverEnv(env)),
         logPath: relativeLogPathFor("observer"),
         readiness: null,
     };
     const worker = {
         name: "worker",
-        command: resolvePythonExecutable(parentEnv),
+        command: resolvePythonExecutable(parentEnv, params.venv),
         args: ["worker.py"],
-        cwd,
-        env,
+        cwd: pythonCwd,
+        env: pythonEnv(env),
         // The reconciler has no listening socket, so it used to be `readiness: null`
         // — "spawned and still alive", which cannot tell a booting reconciler from
         // one that crashed on its first tick. It is now gated on a FRESH durable

package/build/plane/preflight.js

@@ -316,7 +316,9 @@ export async function runPlanePreflight(repoRoot, deps) {
         execFile: deps.execFile,
         fileExists: (filePath) => fileExists(filePath, deps.fs),
         platform: deps.platform,
-    }));
+    }, 
+    // The code this plane will RUN. The executable still comes from `repoRoot`.
+    deps.codeSnapshot?.path ?? repoRoot));
     const existing = await checkExistingPlane(repoRoot, deps);
     record(existing);
     observations.existingPlane = existing.observation;
@@ -349,6 +351,7 @@ export async function runPlanePreflight(repoRoot, deps) {
             runtimeEntrypoint: runtimeEntrypoint.entrypoint,
             bridgeApiKey: credentials.apiKey,
             bridgeCredentialSource: credentials.source,
+            ...(deps.codeSnapshot !== undefined ? { snapshot: deps.codeSnapshot } : {}),
         },
     };
 }
@@ -903,7 +906,32 @@ const PLANE_UNREPORTED_REMEDIATION = "run `plane up` (or `epic-implementer readi
  * - A launch-permitting `warning` maps to `warn`, never `fail` and never `skip`,
  *   and nothing here feeds back into the preflight's own `ok` calculation.
  */
-export function mapPlanePreflightToReadinessChecks(result) {
+/**
+ * Fixed detail for each descriptor that does not apply to the target (BAPI-1360).
+ * Neither string carries a URL, port, or path: the target is only ever named by
+ * its kind.
+ */
+const PLANE_NOT_APPLICABLE_DETAIL = {
+    remote: "not applicable: the target is a remote Bridge API, not a local plane",
+    unresolvable: "not applicable: endpoint could not be resolved from target URL",
+};
+export function mapPlanePreflightToReadinessChecks(result, 
+/**
+ * An EXPLICIT statement that the plane checks do not apply to this target. It is
+ * the only way a `skip` is produced here: a missing preflight result with no such
+ * input stays the failure it always was, so an unrun probe is never mistaken for
+ * an inapplicable one.
+ */
+notApplicable) {
+    if (notApplicable !== undefined) {
+        return PLANE_READINESS_DESCRIPTORS.map(({ id, label }) => createReadinessCheck({
+            id: `plane.${id}`,
+            source: "plane",
+            label,
+            status: "skip",
+            detail: PLANE_NOT_APPLICABLE_DETAIL[notApplicable],
+        }));
+    }
     const byId = new Map();
     for (const outcome of result?.outcomes ?? []) {
         if (!byId.has(outcome.id))

package/build/plane/process-cwd.js

@@ -0,0 +1,67 @@
+/**
+ * Actual working directory of a live process (BAPI-1362).
+ *
+ * The base-worktree fast-forward guard needs to know whether a plane member is
+ * running out of a given checkout. A v4 manifest records each member's `cwd`, but
+ * a legacy manifest records nothing, so the only evidence is the process itself.
+ *
+ * Closed result, never a throw, and never raw command output: the only string a
+ * caller can receive is a path that passed {@link isCanonicalAbsolutePath}.
+ * Anything this function cannot establish is `unverifiable`, and the guard reads
+ * that as "unsafe to merge", not as "somewhere else".
+ */
+import { isCanonicalAbsolutePath } from "./manifest.js";
+/** Positive integer pids only; anything else can never be placed in an argv. */
+function isUsablePid(pid) {
+    return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0;
+}
+/**
+ * Parse `lsof -Fn` field output and return the path on its `n` line.
+ *
+ * Exactly one `n` line is accepted. Zero or several mean the output is not what
+ * this code understands, which is `unverifiable` rather than a guess.
+ */
+export function parseLsofCwd(stdout) {
+    const names = stdout
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("n"))
+        .map((line) => line.slice(1));
+    if (names.length !== 1)
+        return null;
+    return isCanonicalAbsolutePath(names[0]) ? names[0] : null;
+}
+export async function readProcessCwd(pid, deps) {
+    if (!isUsablePid(pid))
+        return { kind: "unverifiable" };
+    try {
+        if (deps.platform === "linux") {
+            const target = await deps.readlink(`/proc/${pid}/cwd`);
+            return isCanonicalAbsolutePath(target) ? { kind: "cwd", cwd: target } : { kind: "unverifiable" };
+        }
+        if (deps.platform === "darwin") {
+            const result = await deps.execFile("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]);
+            if (!result.ok)
+                return { kind: "unverifiable" };
+            const cwd = parseLsofCwd(result.stdout);
+            return cwd === null ? { kind: "unverifiable" } : { kind: "cwd", cwd };
+        }
+    }
+    catch {
+        /* every failure is the same closed answer */
+    }
+    return { kind: "unverifiable" };
+}
+/** Production bindings. The only place this module touches the platform. */
+export async function createProcessCwdDeps() {
+    const { readlink } = await import("fs/promises");
+    const { execFile } = await import("child_process");
+    return {
+        platform: process.platform,
+        readlink: (linkPath) => readlink(linkPath),
+        execFile: (file, args) => new Promise((resolve) => {
+            execFile(file, args, { shell: false, windowsHide: true, timeout: 5_000 }, (error, stdout) => {
+                resolve(error ? { ok: false } : { ok: true, stdout: String(stdout) });
+            });
+        }),
+    };
+}