@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/build/plane/alembic-head.js

@@ -74,13 +74,22 @@ export function parseAlembicRevisions(output) {
 /**
  * Compare the repository's migration heads with the database's current
  * revisions. Blocks only on a confirmed mismatch; warns on anything unverifiable.
+ *
+ * `codeRoot` (BAPI-1362) is the checkout whose `alembic.ini` and migrations are
+ * read — a plane's pinned snapshot — and defaults to `repoRoot`, which keeps every
+ * pre-snapshot caller byte-for-byte unchanged. The executable is deliberately
+ * NOT resolved from it: the virtualenv is untracked and lives only in the operator
+ * checkout, so a snapshot has no `.venv` to find. The check therefore asks "is the
+ * database at the head of the code this plane will RUN", using the operator's
+ * interpreter and dependencies, which is the question a moving checkout made
+ * unanswerable.
  */
-export async function checkAlembicHead(repoRoot, deps) {
+export async function checkAlembicHead(repoRoot, deps, codeRoot = repoRoot) {
     const alembic = resolveRepositoryAlembicCommand(repoRoot, deps.platform);
     if (!(await deps.fileExists(alembic))) {
         return unverified("the repository virtualenv Alembic executable was not found", "the repository virtualenv Alembic executable was not found");
     }
-    const heads = await deps.execFile(alembic, ["-c", "alembic.ini", "heads"], { cwd: repoRoot });
+    const heads = await deps.execFile(alembic, ["-c", "alembic.ini", "heads"], { cwd: codeRoot });
     if (!heads.ok) {
         // The interpolated `error` stays in the legacy message for the operator at
         // the terminal; the consolidated detail is fixed prose. In production that
@@ -88,7 +97,7 @@ export async function checkAlembicHead(repoRoot, deps) {
         // must not depend on every caller keeping it that way.
         return unverified(`\`alembic heads\` did not complete (${heads.error})`, "`alembic heads` did not complete");
     }
-    const current = await deps.execFile(alembic, ["-c", "alembic.ini", "current"], { cwd: repoRoot });
+    const current = await deps.execFile(alembic, ["-c", "alembic.ini", "current"], { cwd: codeRoot });
     if (!current.ok) {
         return unverified(`\`alembic current\` did not complete (${current.error})`, "`alembic current` did not complete");
     }

package/build/plane/base-worktree-guard.js

@@ -0,0 +1,147 @@
+/**
+ * Base-worktree fast-forward guard (BAPI-1362).
+ *
+ * Interactive `start-tickets` fast-forwards the local base branch inside the
+ * worktree that has it checked out. If a live plane's Python member is running
+ * out of that very checkout, the merge replaces code under a running process.
+ * This guard decides, immediately before `git merge --ff-only`, whether that is
+ * safe.
+ *
+ * Posture: fail closed where the harm is a moved checkout. Every ambiguous
+ * reading (an unreadable or invalid manifest, an unknown liveness, a working
+ * directory that cannot be verified or canonicalized) is `protect`. Only a
+ * conclusive "nothing live runs from this checkout" is `safe-to-merge`, so stale
+ * runtime files never permanently disable a refresh.
+ *
+ * The manifest is read ONLY from the base worktree passed in. A manifest under
+ * the caller's own checkout says nothing about the checkout being moved.
+ *
+ * Nothing here echoes manifest bytes, environment, or a raw OS error: the reason
+ * is one of a few fixed phrases plus, when the manifest validated, its plane id.
+ */
+import path from "path";
+import { isCanonicalAbsolutePath, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
+import { readProcessCwd } from "./process-cwd.js";
+/** Members whose code a checkout fast-forward can change under them. */
+const PYTHON_MEMBERS = new Set(["server", "worker", "observer"]);
+/** Canonicalize a path through `realpath`, or fall back lexically when both allow. */
+async function canonical(p, realpath) {
+    try {
+        const resolved = await realpath(p);
+        return isCanonicalAbsolutePath(resolved) ? resolved : null;
+    }
+    catch {
+        // Lexical fallback ONLY for a path that is already its own canonical form.
+        return isCanonicalAbsolutePath(p) ? p : null;
+    }
+}
+export async function evaluateBaseWorktreeGuard(baseWorktreePath, deps) {
+    const manifestLocation = ".bridge/plane/plane.json";
+    const protect = (reason, planeId) => ({
+        kind: "protect",
+        reason,
+        manifestLocation,
+        ...(planeId !== undefined ? { planeId } : {}),
+    });
+    if (!path.isAbsolute(baseWorktreePath))
+        return protect("base-path-unresolvable");
+    let read;
+    try {
+        read = await readPlaneManifest(baseWorktreePath, deps.fs);
+    }
+    catch {
+        return protect("manifest-unreadable");
+    }
+    if (read.kind === "missing")
+        return { kind: "safe-to-merge" };
+    if (read.kind === "unreadable")
+        return protect("manifest-unreadable");
+    if (read.kind === "malformed")
+        return protect("manifest-invalid");
+    const manifest = read.manifest;
+    const planeId = manifest.planeId;
+    // A valid manifest says it belongs here; one copied from elsewhere does not
+    // describe this checkout's processes either way, so it cannot vouch for safety.
+    if (manifest.repoRoot !== baseWorktreePath) {
+        const a = await canonical(manifest.repoRoot, deps.realpath);
+        const b = await canonical(baseWorktreePath, deps.realpath);
+        if (a === null || b === null || a !== b)
+            return protect("manifest-invalid");
+    }
+    const supervisor = deps.proc.isAlive(manifest.supervisorPid);
+    const probes = probeManifestMembers(manifest, deps.proc);
+    const anyUnknown = supervisor === "unknown" || probes.some((p) => p.liveness === "unknown");
+    const live = probes.filter((p) => p.liveness === "alive" && PYTHON_MEMBERS.has(p.member.name));
+    // Conclusively nothing alive anywhere: stale runtime files.
+    if (supervisor === "dead" && probes.every((p) => p.liveness === "dead")) {
+        return { kind: "safe-to-merge" };
+    }
+    const base = await canonical(baseWorktreePath, deps.realpath);
+    if (base === null)
+        return protect("base-path-unresolvable", planeId);
+    let sawUnverifiable = false;
+    for (const probe of live) {
+        let memberCwd = null;
+        if (probe.member.cwd !== undefined) {
+            memberCwd = await canonical(probe.member.cwd, deps.realpath);
+        }
+        else if (probe.member.pid !== null) {
+            const actual = await deps.readProcessCwd(probe.member.pid);
+            if (actual.kind === "cwd")
+                memberCwd = await canonical(actual.cwd, deps.realpath);
+        }
+        if (memberCwd === null) {
+            sawUnverifiable = true;
+            continue;
+        }
+        if (memberCwd === base)
+            return protect("live-member-in-base-checkout", planeId);
+    }
+    if (sawUnverifiable)
+        return protect("cwd-unverifiable", planeId);
+    // A live Python member that could not be probed conclusively is also unsafe.
+    if (anyUnknown)
+        return protect("liveness-unknown", planeId);
+    return { kind: "safe-to-merge" };
+}
+/**
+ * The single sanitized warning line for a `protect` decision.
+ *
+ * Names the plane id when trustworthy, otherwise the manifest location. Never
+ * includes the manifest contents.
+ */
+export function formatBaseWorktreeGuardWarning(decision, baseBranch) {
+    const subject = decision.planeId !== undefined
+        ? `plane ${decision.planeId}`
+        : `the plane record at ${decision.manifestLocation} in that checkout`;
+    return (`Warning: the ${baseBranch} checkout was NOT fast-forwarded because ${subject} may be ` +
+        `running from it (${decision.reason}). The ticket worktree is cut from the fetched ` +
+        `origin/${baseBranch} instead; the local ${baseBranch} branch was not moved.`);
+}
+/** Production bindings. Lazy imports keep unit tests free of real I/O. */
+export async function createBaseWorktreeGuardDeps() {
+    const { readFile, realpath } = await import("fs/promises");
+    const { createProcessCwdDeps } = await import("./process-cwd.js");
+    const cwdDeps = await createProcessCwdDeps();
+    return {
+        fs: { readFile: (p) => readFile(p, "utf-8") },
+        proc: {
+            isAlive: (pid) => {
+                try {
+                    process.kill(pid, 0);
+                    return "alive";
+                }
+                catch (err) {
+                    const code = err?.code;
+                    if (code === "ESRCH")
+                        return "dead";
+                    if (code === "EPERM")
+                        return "alive";
+                    return "unknown";
+                }
+            },
+        },
+        realpath: (p) => realpath(p),
+        readProcessCwd: (pid) => readProcessCwd(pid, cwdDeps),
+    };
+}

package/build/plane/cli.js

@@ -12,17 +12,19 @@
  * if it is ever reused on the server path.
  */
 import { randomUUID } from "crypto";
-import { PLANE_ENTRYPOINT_ACTION, PLANE_ID_ENV_VAR, PLANE_MANIFEST_SCHEMA_VERSION, PLANE_OBSERVER_CHANNEL_TYPE_ENV, PLANE_OBSERVER_COMMAND, PLANE_OBSERVER_DESTINATION_ENV, PLANE_RUNTIME_ACTION, PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
+import { PLANE_ENTRYPOINT_ACTION, PLANE_ID_ENV_VAR, PLANE_MANIFEST_SCHEMA_VERSION, PLANE_OBSERVER_CHANNEL_TYPE_ENV, PLANE_OBSERVER_COMMAND, PLANE_OBSERVER_DESTINATION_ENV, PLANE_RESTARTABLE_MEMBERS, PLANE_RUNTIME_ACTION, PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
 import { validateExecutorClaimScope, } from "../executor/claim-scope.js";
 import { PLANE_RUNTIME_ENTRYPOINT_REFUSAL } from "./build-freshness.js";
-import { relativeLogPathFor } from "./manifest.js";
-import { claimPlaneManifest, requestPlaneManifestLanes } from "./manifest.js";
+import { claimPlaneManifest, clearPlaneManifest, isCanonicalAbsolutePath, planeManifestSnapshot, readPlaneManifest, relativeLogPathFor, requestPlaneManifestLanes, } from "./manifest.js";
+import { lockCodeSnapshot, prepareCodeSnapshot, releaseCodeSnapshotForManifest, revalidateCodeSnapshot, } from "./code-snapshot.js";
+import { checkAlembicHead } from "./alembic-head.js";
+import { formatPlaneRestartOutcome, isPlaneRestartableMember, requestPlaneRestart, } from "./restart.js";
 import { runPlanePreflight } from "./preflight.js";
 import { buildPlaneControlPlaneRoster, buildPlaneExecutorLaneRoster, buildPlaneMemberRoster, buildPlaneObserverRoster, resolvePlaneServerEndpoint, } from "./member-roster.js";
 import { getPlaneStatus, formatPlaneStatus } from "./status.js";
 import { shutdownPlane, formatPlaneShutdown } from "./shutdown.js";
 import { launchPlaneSupervisor, runPlaneRuntime, PLANE_RUNTIME_TWO_PHASE_FLAG, } from "./supervisor.js";
-import { createMemberLogDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, createPlaneSpawn, probeAutomationHealth, probeTcpPort, registerSignalHandler, resolveHomedir, resolveHostname, resolveNodeExecutable, resolvePackageEntrypoint, } from "./defaults.js";
+import { createCodeSnapshotDeps, createMemberLogDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, createPlaneSpawn, planeFileExistsSync, probeAutomationHealth, probeTcpPort, registerSignalHandler, resolveHomedir, resolveHostname, resolveNodeExecutable, resolvePackageEntrypoint, } from "./defaults.js";
 import { resolveBapiCredentials } from "../credential-store.js";
 import { listRunExecutorRecords, verifyRunExecutorProcess } from "../executor-launch.js";
 import { resolveRequiredStartTicketsRepoName } from "../start-tickets-repo.js";
@@ -39,7 +41,10 @@ export const PLANE_DEFAULT_EXECUTORS = 1;
  */
 export function parsePlaneArgs(argv) {
     if (argv.length === 0) {
-        return { kind: "error", message: "missing action (expected `up`, `status`, or `down`)" };
+        return {
+            kind: "error",
+            message: "missing action (expected `up`, `status`, `restart`, or `down`)",
+        };
     }
     if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
         return { kind: "help" };
@@ -55,6 +60,38 @@ export function parsePlaneArgs(argv) {
         }
         return { kind: action };
     }
+    // BAPI-1362 — `plane restart <server|worker|observer>`. Every rejection is here,
+    // in the pure parser, so a malformed invocation has no side effect: no manifest
+    // read, no request file, no signal.
+    if (action === "restart") {
+        if (rest.length === 0) {
+            return {
+                kind: "error",
+                message: `\`plane restart\` requires a member (${PLANE_RESTARTABLE_MEMBERS.join(", ")})`,
+            };
+        }
+        if (rest.length > 1) {
+            return {
+                kind: "error",
+                message: `\`plane restart\` takes exactly one member (got extra argument '${rest[1]}')`,
+            };
+        }
+        const member = rest[0];
+        if (isPlaneRestartableMember(member))
+            return { kind: "restart", member };
+        if (/^executor-[1-9][0-9]*$/.test(member)) {
+            return {
+                kind: "error",
+                message: `per-member restart is unavailable for executor lane '${member}'. Executor lanes are ` +
+                    "scoped to a run, so they are recovered at the run level (re-attach with `drive-epic`), " +
+                    "not with `plane restart`",
+            };
+        }
+        return {
+            kind: "error",
+            message: `'${member}' is not a restartable member (expected ${PLANE_RESTARTABLE_MEMBERS.join(", ")})`,
+        };
+    }
     // Private, and deliberately absent from the usage text and from the
     // expected-action list in the unknown-action error below: it exists for the
     // bundled-artifact regression guard, not for operators.
@@ -70,7 +107,7 @@ export function parsePlaneArgs(argv) {
     if (action !== "up" && action !== PLANE_RUNTIME_ACTION) {
         return {
             kind: "error",
-            message: `unknown action '${action}' (expected \`up\`, \`status\`, or \`down\`)`,
+            message: `unknown action '${action}' (expected \`up\`, \`status\`, \`restart\`, or \`down\`)`,
         };
     }
     let executors = null;
@@ -203,7 +240,7 @@ function parseExecutorCount(raw) {
  */
 export function getPlaneUsage() {
     return [
-        "Usage: mcp-server plane <up|status|down> [options]",
+        "Usage: mcp-server plane <up|status|restart|down> [options]",
         "",
         "Brings up (and winds down) the attended conductor plane in one command:",
         "the Bridge API server, the dead-man observer, the reconciler worker, and",
@@ -225,12 +262,23 @@ export function getPlaneUsage() {
         "  plane up <scope> [--executors N]",
         "                             Preflight, then start the plane. Refuses as a",
         "                             whole if any spawn-blocking check fails.",
-        "  plane status               Read the manifest and report each member's state.",
+        "  plane status               Read the manifest and report the plane's pinned code and",
+        "                             each member's state, with the safest next action.",
+        "  plane restart <server|worker|observer>",
+        "                             Replace ONE member of the live plane from its pinned code",
+        "                             (BAPI-1362). Waits for a bounded readiness outcome and",
+        "                             reports it. The pinned commit and the bound run are",
+        "                             retained and the other members are untouched. It is a",
+        "                             manual recovery: nothing is ever restarted automatically.",
+        "                             Executor lanes are recovered at the run level instead.",
         "  plane down                 Stop the bound server-side epic run FIRST (BAPI-872),",
         "                             then signal the recorded process group, escalating",
         "                             to SIGKILL, and clear the manifest. Process shutdown",
         "                             alone is NOT a run stop — a manifest with no bound",
         "                             run, or an unreachable Bridge API, only warns.",
+        "                             `plane down && plane up` moves the plane to NEW code,",
+        "                             so use it between runs (it stops a bound run); to",
+        "                             recover one member, use `plane restart <member>`.",
         "",
         "Options:",
         `  --executors N              Executor lanes to start (default ${PLANE_DEFAULT_EXECUTORS}, max ${PLANE_MAX_EXECUTORS}).`,
@@ -247,7 +295,12 @@ export function getPlaneUsage() {
         "  * Executors run from this repository's local build tree",
         "    (mcp_server/build/index.js) — never npx, never a published package.",
         "  * A member that exits is reported loudly and is NOT restarted. There is no",
-        "    auto-restart, retry, or backoff: a crash is a finding, not noise.",
+        "    auto-restart, retry, or backoff: a crash is a finding, not noise. Recover it",
+        "    yourself with `plane restart <member>`.",
+        "  * The Python members (server, worker, observer) run from a PINNED, detached code",
+        "    snapshot of the commit checked out when the plane came up, under",
+        `    ${PLANE_RUNTIME_DIR}/snapshots/<sha>, so moving your checkout (a pull, a`,
+        "    fast-forward) does not change the code a live plane is running.",
         "  * The dead-man observer runs as an INDEPENDENT same-host OS process, started",
         "    by `plane up`, listed in `plane status`, and stopped by `plane down`. It is",
         "    started before the reconciler worker, so it is already watching while the",
@@ -323,6 +376,8 @@ export async function runPlaneCli(argv, overrides = {}) {
                 return await runStatusAction(sinks, overrides);
             case "down":
                 return await runDownAction(sinks, overrides);
+            case "restart":
+                return await runRestartAction(parsed.member, sinks, overrides);
             case "up":
                 return await runUpAction(parsed.options, sinks, overrides);
             case "runtime":
@@ -380,6 +435,28 @@ async function runStatusAction(sinks, overrides) {
     sinks.stdout(text);
     return 0;
 }
+/**
+ * `plane restart <member>` (BAPI-1362).
+ *
+ * The CLI half of a member restart: validate, hand the detached runtime one
+ * request, and report its bounded outcome. Everything it can refuse, it refuses
+ * before writing or signalling (see `requestPlaneRestart`), and no outcome it can
+ * report falls back to a plane-wide action.
+ */
+async function runRestartAction(member, sinks, overrides) {
+    const repoRoot = overrides.cwd ?? process.cwd();
+    const outcome = overrides.restart
+        ? await overrides.restart(repoRoot, member)
+        : await requestPlaneRestart(repoRoot, member, {
+            fs: createPlaneFsDeps(),
+            proc: createPlaneProcessDeps(),
+            clock: createPlaneClock(),
+        });
+    const rendered = formatPlaneRestartOutcome(outcome);
+    for (const line of rendered.lines)
+        (rendered.ok ? sinks.stdout : sinks.stderr)(line);
+    return rendered.ok ? 0 : 1;
+}
 async function runDownAction(sinks, overrides) {
     const repoRoot = overrides.cwd ?? process.cwd();
     if (overrides.down) {
@@ -391,10 +468,14 @@ async function runDownAction(sinks, overrides) {
     const proc = createPlaneProcessDeps();
     const execFile = createPlaneExecFile();
     const endpoint = resolvePlaneServerEndpoint(process.env);
+    const snapshotDeps = createCodeSnapshotDeps(proc);
     const result = await shutdownPlane(repoRoot, {
         fs,
         proc,
         clock: createPlaneClock(),
+        // BAPI-1362 — unlock the pinned snapshot, but only once this wind-down has
+        // confirmed every process gone and cleared the manifest. It stays on disk.
+        releaseSnapshot: (manifest) => releaseCodeSnapshotForManifest(manifest, snapshotDeps),
         stopBoundRun: stopBoundEpicRun,
         // BAPI-1279 — stop the run-scoped executors drive-epic started here that
         // target THIS plane's endpoint (the same rule `plane up` binds by).
@@ -586,19 +667,56 @@ export function formatPlaneLaunchFailure(launch) {
 async function launchPlane(preflight, executors, planeId, sinks, env, launchOptions = {}) {
     const fs = createPlaneFsDeps();
     const clock = createPlaneClock();
-    const context = preflight.context;
+    const snapshotDeps = createCodeSnapshotDeps();
+    let context = preflight.context;
     const nodeExecutable = resolveNodeExecutable();
+    // BAPI-1362 — pin the code the Python members will run BEFORE anything is
+    // claimed or spawned. Preflight has already passed (checkout prerequisites and
+    // the existing-plane ownership check both run there, read-only), so this is the
+    // first step with a side effect, and a refusal here leaves the repository
+    // exactly as it found it apart from a snapshot directory a later bring-up
+    // reuses. A caller that already carries a snapshot (a test seam) is trusted.
+    if (context.snapshot === undefined) {
+        const prepared = await prepareCodeSnapshot(context.repoRoot, snapshotDeps);
+        if (!prepared.ok) {
+            return {
+                ok: false,
+                error: `${PLANE_SNAPSHOT_REFUSAL}: ${prepared.message}`,
+                startup: null,
+            };
+        }
+        // The code-dependent migration check, against the snapshot's own
+        // `alembic.ini` and migrations and the operator's virtualenv. Preflight ran
+        // the same check against the checkout; the two agree at launch, and only
+        // this one survives the checkout moving later.
+        const alembic = await checkAlembicHead(context.repoRoot, {
+            execFile: createPlaneExecFile(),
+            fileExists: async (filePath) => planeFileExistsSync(filePath),
+            platform: process.platform,
+        }, prepared.snapshot.path);
+        if (alembic.diagnostic?.severity === "blocking") {
+            return { ok: false, error: alembic.diagnostic.message, startup: null };
+        }
+        if (alembic.diagnostic)
+            sinks.stdout(formatDiagnostic(alembic.diagnostic));
+        context = { ...context, snapshot: prepared.snapshot };
+    }
+    const snapshot = context.snapshot;
     // BAPI-1102 — in two-phase mode the manifest is claimed listing only the
     // CONTROL-PLANE members. Listing lanes that have not been asked to start would
     // make `plane status` report members that do not exist, and `plane down` would
     // have nothing to signal for them.
+    const rosterBase = {
+        context,
+        parentEnv: env,
+        nodeExecutable,
+        venv: operatorVenvLookup(context.repoRoot),
+    };
     const roster = launchOptions.twoPhase
-        ? buildPlaneControlPlaneRoster({ context, parentEnv: env, nodeExecutable })
+        ? buildPlaneControlPlaneRoster(rosterBase)
         : buildPlaneMemberRoster({
-            context,
+            ...rosterBase,
             executors,
-            parentEnv: env,
-            nodeExecutable,
             ...(launchOptions.claimScope ? { claimScope: launchOptions.claimScope } : {}),
         });
     const timestamp = clock.now().toISOString();
@@ -620,7 +738,14 @@ async function launchPlane(preflight, executors, planeId, sinks, env, launchOpti
                 exitCode: null,
                 exitSignal: null,
                 logPath: relativeLogPathFor(spec.name),
+                ...(isCanonicalAbsolutePath(spec.cwd) ? { cwd: spec.cwd } : {}),
             })),
+            // The pinned code identity, recorded in the claim so the detached runtime,
+            // `plane status`, `plane restart`, and the `start-tickets` guard all read the
+            // same answer from the one durable record.
+            ...(snapshot !== undefined
+                ? { snapshotPath: snapshot.path, snapshotSha: snapshot.sha }
+                : {}),
         },
         fs,
         proc: createPlaneProcessDeps(),
@@ -629,6 +754,18 @@ async function launchPlane(preflight, executors, planeId, sinks, env, launchOpti
     // report — `startup: null` is the honest shape, not a placeholder.
     if (!claim.ok)
         return { ok: false, error: claim.message, startup: null };
+    // BAPI-1362 — lock the snapshot for this live plane, before any member exists.
+    // Taken only AFTER the claim succeeded, so a bring-up that loses the claim race
+    // or fails an earlier check never leaves a lock for a plane that did not start.
+    // If the lock cannot be taken the claim is released again: a plane whose code
+    // could be pruned from under it must not start.
+    if (snapshot !== undefined) {
+        const locked = await lockCodeSnapshot(context.repoRoot, snapshot, planeId, snapshotDeps);
+        if (!locked.ok) {
+            await clearPlaneManifest(context.repoRoot, planeId, fs);
+            return { ok: false, error: `${PLANE_SNAPSHOT_REFUSAL}: ${locked.message}`, startup: null };
+        }
+    }
     return launchPlaneSupervisor({
         context,
         manifest: claim.manifest,
@@ -665,6 +802,12 @@ async function launchPlane(preflight, executors, planeId, sinks, env, launchOpti
             : {}),
     });
 }
+/** Stable label so a snapshot refusal is greppable in a terminal scrollback. */
+export const PLANE_SNAPSHOT_REFUSAL = "plane up REFUSED — the code snapshot could not be pinned";
+/** The operator-checkout virtualenv lookup the roster uses for default executables. */
+function operatorVenvLookup(operatorRoot) {
+    return { operatorRoot, platform: process.platform, fileExists: planeFileExistsSync };
+}
 function printStartupBanner(sinks, context, memberCount, executors, launch) {
     // Deliberately built from fixed labels plus non-secret facts. No environment
     // object and no credential value is rendered — the resolved key exists only
@@ -675,8 +818,12 @@ function printStartupBanner(sinks, context, memberCount, executors, launch) {
     sinks.stdout(`  server       ${context.endpoint.baseUrl} (no --reload)`);
     sinks.stdout(`  supervisor   pid ${launch.supervisorPid}, process group ${launch.supervisorPgid}`);
     sinks.stdout(`  logs         ${PLANE_RUNTIME_DIR}/`);
+    if (context.snapshot !== undefined) {
+        sinks.stdout(`  code         pinned ${context.snapshot.sha} (${context.snapshot.path})`);
+    }
     sinks.stdout("  observer     dead-man-only worker.py, its own OS process (same host)");
-    sinks.stdout("  crash policy members are NOT restarted; a member exit is reported loudly.");
+    sinks.stdout("  crash policy members are NOT restarted; a member exit is reported loudly." +
+        " Recover one with `plane restart <member>`.");
     sinks.stdout("");
 }
 /**
@@ -830,6 +977,32 @@ async function runRuntimeAction(options, overrides) {
         sinks.stderr(`plane runtime refused: ${PLANE_ID_ENV_VAR} was not provided by the launcher.`);
         return 1;
     }
+    // BAPI-1362 — the code this plane was pinned to is what its MANIFEST says, read
+    // back from the claim its launcher wrote, and it is revalidated here before any
+    // code-dependent check. The operator checkout is deliberately never consulted
+    // for code identity: by now it may have moved, which is the whole reason the
+    // snapshot exists. A claim with no snapshot (an unpinned launch) resolves to no
+    // snapshot and the runtime behaves as it always did.
+    const runtimeFs = createPlaneFsDeps();
+    const snapshotDeps = createCodeSnapshotDeps();
+    let pinnedSnapshot;
+    {
+        const claimed = await readPlaneManifest(repoRoot, runtimeFs);
+        if (claimed.kind === "valid" && claimed.manifest.planeId === planeId) {
+            const pinned = planeManifestSnapshot(claimed.manifest);
+            if (pinned.kind === "pinned") {
+                const revalidated = await revalidateCodeSnapshot(repoRoot, pinned.snapshot, snapshotDeps);
+                if (!revalidated.ok) {
+                    sinks.stderr("");
+                    sinks.stderr(`plane runtime REFUSED — the plane's pinned code snapshot could not be revalidated: ${revalidated.message}`);
+                    sinks.stderr("");
+                    sinks.stderr(`${PLANE_NOTHING_STARTED}.`);
+                    return 1;
+                }
+                pinnedSnapshot = pinned.snapshot;
+            }
+        }
+    }
     // BAPI-882: hand preflight this runtime's own plane id. The launcher claimed
     // `plane.json` with `supervisorPid: process.pid` as a placeholder BEFORE
     // spawning us, so a preflight without an identity sees that live claim,
@@ -837,7 +1010,11 @@ async function runRuntimeAction(options, overrides) {
     // deadlocking on its own launcher. `planeId` is validated non-empty above.
     const preflight = overrides.preflight
         ? await overrides.preflight(repoRoot)
-        : await runPlanePreflight(repoRoot, { ...buildPreflightDeps(env), ownPlaneId: planeId });
+        : await runPlanePreflight(repoRoot, {
+            ...buildPreflightDeps(env),
+            ownPlaneId: planeId,
+            ...(pinnedSnapshot !== undefined ? { codeSnapshot: pinnedSnapshot } : {}),
+        });
     if (!preflight.ok) {
         // The launcher already ran preflight; reaching here means the world genuinely
         // changed between claim and spawn. Refuse rather than start a half-valid
@@ -855,7 +1032,16 @@ async function runRuntimeAction(options, overrides) {
         return 1;
     }
     const nodeExecutable = resolveNodeExecutable();
-    const rosterBase = { context: preflight.context, parentEnv: env, nodeExecutable };
+    const rosterBase = {
+        // The context carries the pinned snapshot when preflight was given one, so a
+        // test seam that replaced preflight still gets the manifest's identity.
+        context: pinnedSnapshot !== undefined && preflight.context.snapshot === undefined
+            ? { ...preflight.context, snapshot: pinnedSnapshot }
+            : preflight.context,
+        parentEnv: env,
+        nodeExecutable,
+        venv: operatorVenvLookup(preflight.context.repoRoot),
+    };
     // BAPI-1102 — in two-phase mode the runtime is handed the CONTROL-PLANE roster
     // and the two builders it will need later, rather than a finished roster it
     // cannot build yet: the lane roster depends on a claim scope that does not
@@ -888,6 +1074,20 @@ async function runRuntimeAction(options, overrides) {
         hostname: resolveHostname,
         selfPid: process.pid,
         planeId,
+        // BAPI-1362 — unlock the pinned snapshot after a confirmed wind-down or
+        // rollback, and let `plane restart` revalidate it (or, for an unpinned plane,
+        // confirm its launch directory) before replacing anything.
+        releaseSnapshot: (manifest) => releaseCodeSnapshotForManifest(manifest, snapshotDeps),
+        revalidateSnapshot: (snapshot) => revalidateCodeSnapshot(repoRoot, snapshot, snapshotDeps),
+        checkLaunchDirectory: async (directory) => {
+            try {
+                const stat = await snapshotDeps.fs.lstat(directory);
+                return stat !== null && stat.isDirectory && !stat.isSymbolicLink;
+            }
+            catch {
+                return false;
+            }
+        },
         ...(options.twoPhase
             ? {
                 twoPhase: {