@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/plane/cli.js

@@ -18,27 +18,22 @@ import { PLANE_RUNTIME_ENTRYPOINT_REFUSAL } from "./build-freshness.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 { checkSchemaCompatibility } from "./schema-compatibility.js";
 import { formatPlaneRestartOutcome, isPlaneRestartableMember, requestPlaneRestart, } from "./restart.js";
 import { runPlanePreflight } from "./preflight.js";
-import { buildPlaneControlPlaneRoster, buildPlaneExecutorLaneRoster, buildPlaneMemberRoster, buildPlaneObserverRoster, resolvePlaneServerEndpoint, } from "./member-roster.js";
+import { buildPlaneControlPlaneRoster, buildPlaneExecutorLaneRoster, buildPlaneMemberRoster, buildPlaneObserverRoster, resolvePlaneServerEndpoint, resolvePythonExecutable, } from "./member-roster.js";
 import { getPlaneStatus, formatPlaneStatus } from "./status.js";
 import { shutdownPlane, formatPlaneShutdown } from "./shutdown.js";
+import { buildPlaneTeardownDeps } from "./shutdown-deps.js";
+import { cleanupTerminalRunPlane, createTerminalRunCleanupDeps, terminalRunCleanupStderrLine, } from "./terminal-run-cleanup.js";
 import { launchPlaneSupervisor, runPlaneRuntime, PLANE_RUNTIME_TWO_PHASE_FLAG, } from "./supervisor.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";
 /** Upper bound on executor lanes. Guards a typo from forking a fleet. */
 export const PLANE_MAX_EXECUTORS = 32;
 /** Default executor lane count when `--executors` is omitted. */
 export const PLANE_DEFAULT_EXECUTORS = 1;
-/**
- * Parse everything after the `plane` token.
- *
- * Pure by construction: every rejection happens here, before the coordinator
- * can touch the filesystem, open a socket, resolve a credential, or spawn a
- * child. A malformed invocation therefore has no side effect at all.
- */
 export function parsePlaneArgs(argv) {
     if (argv.length === 0) {
         return {
@@ -51,6 +46,30 @@ export function parsePlaneArgs(argv) {
     }
     const action = argv[0];
     const rest = argv.slice(1);
+    // BAPI-1496 — `plane down --expect-epic-run-id <id>`: wind down only the plane
+    // bound to that run. The one option `down` takes; everything else is refused.
+    if (action === "down" && rest.length > 0) {
+        if (rest[0] !== "--expect-epic-run-id") {
+            return {
+                kind: "error",
+                message: `unknown option '${rest[0]}' for \`plane down\` (expected --expect-epic-run-id <id>)`,
+            };
+        }
+        const raw = rest[1];
+        if (raw === undefined) {
+            return { kind: "error", message: "--expect-epic-run-id requires a value" };
+        }
+        if (raw.trim().length === 0) {
+            return { kind: "error", message: "--expect-epic-run-id requires a non-blank value" };
+        }
+        if (rest.length > 2) {
+            return {
+                kind: "error",
+                message: `unexpected argument '${rest[2]}' for \`plane down\` (--expect-epic-run-id may be supplied only once)`,
+            };
+        }
+        return { kind: "down", expectEpicRunId: raw.trim() };
+    }
     if (action === "status" || action === "down") {
         if (rest.length > 0) {
             return {
@@ -279,6 +298,11 @@ export function getPlaneUsage() {
         "                             `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>`.",
+        "  plane down --expect-epic-run-id <id>",
+        "                             Wind down ONLY if the plane is bound to run <id>.",
+        "                             The binding is checked before any run stop or signal;",
+        "                             an unbound plane, another run's plane, or an unreadable",
+        "                             manifest is refused with nothing stopped or signalled.",
         "",
         "Options:",
         `  --executors N              Executor lanes to start (default ${PLANE_DEFAULT_EXECUTORS}, max ${PLANE_MAX_EXECUTORS}).`,
@@ -375,7 +399,7 @@ export async function runPlaneCli(argv, overrides = {}) {
             case "status":
                 return await runStatusAction(sinks, overrides);
             case "down":
-                return await runDownAction(sinks, overrides);
+                return await runDownAction(sinks, overrides, parsed.expectEpicRunId);
             case "restart":
                 return await runRestartAction(parsed.member, sinks, overrides);
             case "up":
@@ -457,58 +481,61 @@ async function runRestartAction(member, sinks, overrides) {
         (rendered.ok ? sinks.stdout : sinks.stderr)(line);
     return rendered.ok ? 0 : 1;
 }
-async function runDownAction(sinks, overrides) {
+/** Said when `plane down --expect-epic-run-id` refuses (BAPI-1496). Fixed prose. */
+export const PLANE_DOWN_OWNERSHIP_REFUSED = "plane down REFUSED: the plane is not bound to the expected epic run (or its manifest could not " +
+    "be read). Nothing was stopped or signalled and the manifest was kept; inspect it with " +
+    "`plane status`.";
+async function runDownAction(sinks, overrides, expectEpicRunId) {
     const repoRoot = overrides.cwd ?? process.cwd();
     if (overrides.down) {
-        const injected = await overrides.down(repoRoot);
+        const injected = expectEpicRunId === undefined
+            ? await overrides.down(repoRoot)
+            : await overrides.down(repoRoot, { expectEpicRunId });
         (injected.ok ? sinks.stdout : sinks.stderr)(injected.text);
         return injected.ok ? 0 : 1;
     }
     const fs = createPlaneFsDeps();
-    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),
+    const result = await shutdownPlane(repoRoot, buildPlaneTeardownDeps({
+        repoRoot,
+        env: process.env,
         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).
-        runExecutors: {
-            list: () => listRunExecutorRecords(repoRoot, fs),
-            targetsThisPlane: (baseUrl) => endpoint.ok && urlNamesLoopbackPort(baseUrl, endpoint.endpoint.port),
-            verify: (record) => verifyRunExecutorProcess(record, { isAlive: proc.isAlive, execFile }, repoRoot),
-        },
-    });
+        ...(expectEpicRunId !== undefined
+            ? { ownershipGuard: expectedRunOwnershipGuard(repoRoot, expectEpicRunId, fs) }
+            : {}),
+    }));
+    // An unreadable manifest cannot show the expected binding either, so under
+    // `--expect-epic-run-id` it is refused with the same fixed line (BAPI-1496).
+    if (!result.ok &&
+        (result.reason === "ownership-aborted" ||
+            (expectEpicRunId !== undefined && result.reason === "unvalidated-manifest"))) {
+        sinks.stderr(PLANE_DOWN_OWNERSHIP_REFUSED);
+        return 1;
+    }
     const text = formatPlaneShutdown(result);
     (result.ok ? sinks.stdout : sinks.stderr)(text);
     return result.ok ? 0 : 1;
 }
-/** Loopback spellings that reach the plane's `127.0.0.1` bind. */
-const PLANE_LOOPBACK_HOSTNAMES = new Set([
-    "127.0.0.1",
-    "localhost",
-    "[::1]",
-    "::1",
-]);
-/** Does `baseUrl` name a loopback `http` endpoint on `port`? Pure. */
-function urlNamesLoopbackPort(baseUrl, port) {
-    let url;
-    try {
-        url = new URL(baseUrl);
-    }
-    catch {
-        return false;
-    }
-    if (url.protocol !== "http:")
-        return false;
-    const actual = url.port === "" ? 80 : Number(url.port);
-    return PLANE_LOOPBACK_HOSTNAMES.has(url.hostname) && actual === port;
+/**
+ * The `--expect-epic-run-id` ownership guard (BAPI-1496).
+ *
+ * The manifest `shutdownPlane` validated must be bound to the expected run, and
+ * a fresh re-read must still show the same plane bound to it — so a plane that
+ * was replaced between the two reads is never signalled. Fixed abort wording:
+ * the CLI prints {@link PLANE_DOWN_OWNERSHIP_REFUSED} instead.
+ */
+function expectedRunOwnershipGuard(repoRoot, expectEpicRunId, fs) {
+    return async (manifest) => {
+        if (manifest.epicRunId !== expectEpicRunId) {
+            return { kind: "abort", message: "the plane is not bound to the expected epic run" };
+        }
+        const reread = await readPlaneManifest(repoRoot, fs);
+        if (reread.kind !== "valid" ||
+            reread.manifest.planeId !== manifest.planeId ||
+            reread.manifest.epicRunId !== expectEpicRunId) {
+            return { kind: "abort", message: "the plane manifest changed during wind-down" };
+        }
+        return { kind: "proceed" };
+    };
 }
 /**
  * `plane down`'s pre-signal run-stop capability (BAPI-872).
@@ -555,6 +582,22 @@ async function runUpAction(options, sinks, overrides) {
     const executors = options.executors;
     const repoRoot = overrides.cwd ?? process.cwd();
     const env = overrides.env ?? process.env;
+    // BAPI-1496 — before preflight, tear down this checkout's plane if it is bound
+    // to a run that has FINISHED and nothing else depends on it; otherwise the
+    // `existing-plane` check below would refuse over a plane nobody needs. Only for
+    // the resolved local-plane endpoint: an unresolvable one is preflight's to
+    // report. An ineligible plane is left alone silently; an incomplete or aborted
+    // cleanup says so once and keeps its manifest, and preflight then refuses over
+    // it exactly as it always has — there is no exemption.
+    const planeEndpoint = resolvePlaneServerEndpoint(env);
+    if (planeEndpoint.ok) {
+        const cleanup = overrides.terminalRunCleanup
+            ? await overrides.terminalRunCleanup({ repoRoot, endpoint: planeEndpoint.endpoint })
+            : await cleanupTerminalRunPlane({ repoRoot, endpoint: planeEndpoint.endpoint }, createTerminalRunCleanupDeps(env));
+        const line = terminalRunCleanupStderrLine(cleanup);
+        if (line !== null)
+            sinks.stderr(line);
+    }
     const preflight = overrides.preflight
         ? await overrides.preflight(repoRoot)
         : await runDefaultPlanePreflight(repoRoot, env);
@@ -699,6 +742,17 @@ async function launchPlane(preflight, executors, planeId, sinks, env, launchOpti
         }
         if (alembic.diagnostic)
             sinks.stdout(formatDiagnostic(alembic.diagnostic));
+        // BAPI-1455 — a stamp is not proof of schema. Ask the shared Python check
+        // whether the launch-critical objects exist, from the snapshot with the
+        // interpreter the Python members will use. Still before any claim or spawn:
+        // only a proven-missing object refuses; anything unverifiable warns.
+        sinks.stdout("Verifying local launch-critical schema…");
+        const schema = await checkSchemaCompatibility(resolvePythonExecutable(env, operatorVenvLookup(context.repoRoot)), prepared.snapshot.path, { execFile: createPlaneExecFile() });
+        if (schema.diagnostic?.severity === "blocking") {
+            return { ok: false, error: schema.diagnostic.message, startup: null };
+        }
+        if (schema.diagnostic)
+            sinks.stdout(formatDiagnostic(schema.diagnostic));
         context = { ...context, snapshot: prepared.snapshot };
     }
     const snapshot = context.snapshot;

package/build/plane/defaults.js

@@ -131,6 +131,9 @@ export function createPlaneExecFile() {
             shell: false,
             windowsHide: true,
             timeout: options.timeoutMs ?? 30_000,
+            // Merged over the inherited environment, so a caller adds a variable
+            // without losing PATH or the user's Git configuration (BAPI-1476).
+            ...(options.env !== undefined ? { env: { ...process.env, ...options.env } } : {}),
         }, (error, stdout, stderr) => {
             if (error) {
                 const code = error.code;

package/build/plane/plane-freshness.js

@@ -0,0 +1,294 @@
+/**
+ * Local-plane freshness evidence (BAPI-1476).
+ *
+ * Three read-only observations a launch collects BEFORE it creates a run:
+ *
+ *   - `plane-snapshot-freshness` — is the plane's pinned code snapshot behind
+ *     `origin/main`?
+ *   - `plane-database-head` — is the database at the migration head of the code
+ *     the plane will run? (Delegates to {@link checkAlembicHead}, unchanged.)
+ *   - `host-sleep` — is this Mac likely to sleep under a long run? (Advisory only.)
+ *
+ * This module only OBSERVES. It does not decide whether a launch may proceed,
+ * does not format output, and never prints. Whether a finding blocks run creation
+ * is the orchestrator's call (`drive-epic.ts`), because the same finding blocks a
+ * create and only warns on a reattach to a run that already exists.
+ *
+ * Asymmetry, as with the Alembic check: a finding is `fail` (blocking severity)
+ * ONLY when the evidence is confirmed. A command failure, a timeout, a missing
+ * object, shallow history, or output it cannot parse is an `unverified` warning —
+ * a false refusal is worse than a skipped check. Unverified detail is fixed prose:
+ * it never carries raw stderr, an error string, a credential, or parser internals.
+ *
+ * Nothing here mutates the checkout, the plane, the database, power settings, or
+ * any run. `git fetch` updates remote-tracking refs, which is the one write.
+ */
+import { checkAlembicHead, } from "./alembic-head.js";
+import { planeCheckFinding, planeCheckPassed, planeCheckSkipped, } from "./types.js";
+/** Finite bound on every subprocess this module starts. */
+export const PLANE_FRESHNESS_TIMEOUT_MS = 30_000;
+export const PLANE_SNAPSHOT_FRESHNESS_ID = "plane-snapshot-freshness";
+export const PLANE_DATABASE_HEAD_ID = "plane-database-head";
+export const PLANE_HOST_SLEEP_ID = "host-sleep";
+const SNAPSHOT_LABEL = "Plane snapshot freshness";
+const SLEEP_LABEL = "Host sleep";
+/** Said on every unverified report. The operator's one next step. */
+export const PLANE_FRESHNESS_UNVERIFIED_REMEDY = "restore the missing evidence and rerun";
+/**
+ * The ordered fix for a snapshot behind `origin/main`. The first step is the
+ * operator's: this CLI never updates the checkout.
+ */
+export const PLANE_SNAPSHOT_STALE_REMEDY = "bring the main checkout up to `origin/main`, then run `plane down` and `plane up`. " +
+    "This CLI does not update the checkout. `--allow-stale-plane` overrides this refusal " +
+    "for one invocation only and repairs nothing.";
+/**
+ * BAPI-1496 — the stale-snapshot fix for a plane BOUND to an epic run.
+ *
+ * {@link PLANE_SNAPSHOT_STALE_REMEDY} says "run `plane down`", which is right for
+ * an unbound plane and wrong for a bound one: `plane down` stops the bound run
+ * server-side. So a bound plane gets ownership-specific advice instead, chosen by
+ * the run's validated status. These fragments are fixed prose; only a validated
+ * run id and a status from the closed vocabulary below are ever interpolated.
+ */
+export const PLANE_BOUND_STALE_OVERRIDE_NOTE = "`--allow-stale-plane` overrides this refusal for one invocation only and repairs nothing.";
+/** Run statuses the bound remedy may name. Anything else renders as unknown. */
+const BOUND_RUN_STATUSES = new Set([
+    "planning",
+    "pending_approval",
+    "active",
+    "blocked",
+    "stopped",
+    "abandoned",
+    "done",
+]);
+/** The run statuses after which nothing more will happen (as `wait-run` uses). */
+const BOUND_RUN_TERMINAL_STATUSES = new Set(["done", "abandoned"]);
+/** A run id is rendered only when it has a plain, bounded identifier shape. */
+const BOUND_RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/**
+ * The stale-snapshot remedy for a plane bound to an epic run (BAPI-1496).
+ *
+ * - Non-terminal and unknown status: inspect the run and the plane. It NEVER
+ *   recommends `plane down`, because that would stop a run that may still be
+ *   working, and an unknown status is not evidence that it is finished.
+ * - Terminal status (`done`/`abandoned`): the next local launch's guarded cleanup
+ *   tears the plane down; if that cleanup reports it was incomplete, inspect with
+ *   `plane status` before any manual wind-down.
+ *
+ * Pure and secret-free: the output names only the run id and a closed status.
+ */
+export function formatBoundPlaneStaleRemedy(input) {
+    const runLabel = BOUND_RUN_ID_PATTERN.test(input.epicRunId)
+        ? `run ${input.epicRunId}`
+        : "its bound run";
+    const status = typeof input.status === "string" && BOUND_RUN_STATUSES.has(input.status) ? input.status : null;
+    if (status !== null && BOUND_RUN_TERMINAL_STATUSES.has(status)) {
+        return (`this plane is bound to ${runLabel}, which is ${status}. Bring the main checkout up to ` +
+            "`origin/main`; the next local launch's guarded cleanup then winds this plane down " +
+            "and starts a fresh one. If that cleanup reports it was incomplete, inspect the plane " +
+            "with `plane status` before winding it down by hand. This CLI does not update the " +
+            `checkout. ${PLANE_BOUND_STALE_OVERRIDE_NOTE}`);
+    }
+    const statusText = status === null ? "whose status could not be confirmed" : `which is ${status}`;
+    return (`this plane is bound to ${runLabel}, ${statusText}. Do not wind it down while that run ` +
+        "may still be working: inspect the run and the plane (`plane status`) first, and let the " +
+        "run finish or stop it deliberately before refreshing the plane. This CLI does not update " +
+        `the checkout. ${PLANE_BOUND_STALE_OVERRIDE_NOTE}`);
+}
+/** The fix for a confirmed database-head mismatch, plus the override. */
+export const PLANE_DATABASE_HEAD_REMEDY = "run `alembic -c alembic.ini upgrade head`, then retry. `--allow-stale-plane` overrides " +
+    "this refusal for one invocation only and repairs nothing.";
+export const PLANE_SLEEP_BATTERY_ADVISORY = "the host is drawing battery power, so it may sleep during a long run";
+export const PLANE_SLEEP_LID_ADVISORY = "closing the lid will sleep the host (SleepDisabled is not 1)";
+export const PLANE_SLEEP_REMEDY = "executor `caffeinate -i -s` only holds the host awake on AC power: plug in and keep the lid open.";
+const HEX_OBJECT_ID = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+const GIT_ENV = { GIT_TERMINAL_PROMPT: "0" };
+function unverifiedSnapshot(reason) {
+    return planeCheckFinding({
+        check: PLANE_SNAPSHOT_FRESHNESS_ID,
+        severity: "warning",
+        message: `could not verify plane snapshot freshness: ${reason}.`,
+        remediation: PLANE_FRESHNESS_UNVERIFIED_REMEDY,
+    }, SNAPSHOT_LABEL, `could not verify plane snapshot freshness: ${reason}`);
+}
+async function git(deps, repoRoot, args, timeoutMs) {
+    const result = await deps.execFile("git", args, { cwd: repoRoot, timeoutMs, env: { ...GIT_ENV } });
+    return result.ok ? result.stdout.trim() : null;
+}
+/** Resolve a revision to a commit id, or `null` for anything that is not one. */
+async function resolveCommit(deps, repoRoot, revision, timeoutMs) {
+    const out = await git(deps, repoRoot, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`], timeoutMs);
+    return out !== null && HEX_OBJECT_ID.test(out) ? out : null;
+}
+async function checkSnapshot(repoRoot, deps, options, timeoutMs, manifestRead) {
+    if (!options.ownsManifest) {
+        return unverifiedSnapshot("no plane manifest in this checkout belongs to the selected plane");
+    }
+    if (manifestRead === null || manifestRead.kind !== "valid") {
+        return unverifiedSnapshot("the plane manifest could not be read");
+    }
+    const manifest = manifestRead.manifest;
+    if (manifest.repoRoot !== repoRoot) {
+        return unverifiedSnapshot("the plane manifest belongs to a different checkout");
+    }
+    if (options.expectedPlaneId !== undefined && manifest.planeId !== options.expectedPlaneId) {
+        return unverifiedSnapshot("the plane manifest is not the selected plane's");
+    }
+    const snapshotSha = manifest.snapshotSha;
+    if (snapshotSha === undefined || !HEX_OBJECT_ID.test(snapshotSha)) {
+        return unverifiedSnapshot("the plane manifest records no pinned snapshot");
+    }
+    // Refresh the remote-tracking ref first. A failed fetch stops this check: a
+    // stale cached `origin/main` would read as "fresh" and prove nothing.
+    if ((await git(deps, repoRoot, ["fetch", "--quiet", "--no-tags", "origin", "main"], timeoutMs)) === null) {
+        return unverifiedSnapshot("`origin` could not be fetched");
+    }
+    const snapshotCommit = await resolveCommit(deps, repoRoot, snapshotSha, timeoutMs);
+    if (snapshotCommit === null) {
+        return unverifiedSnapshot("the snapshot commit is not present in this checkout");
+    }
+    const originCommit = await resolveCommit(deps, repoRoot, "origin/main", timeoutMs);
+    if (originCommit === null) {
+        return unverifiedSnapshot("`origin/main` could not be resolved");
+    }
+    if (snapshotCommit === originCommit) {
+        return planeCheckPassed(PLANE_SNAPSHOT_FRESHNESS_ID, SNAPSHOT_LABEL, "the snapshot is at origin/main");
+    }
+    // The injected runner reports success or failure, not an exit status, so
+    // ancestry is read off VALIDATED `merge-base` output rather than from a
+    // nonzero exit that could equally mean "not an ancestor" or "git failed".
+    const base = await git(deps, repoRoot, ["merge-base", snapshotCommit, originCommit], timeoutMs);
+    if (base === null || !HEX_OBJECT_ID.test(base)) {
+        return unverifiedSnapshot("the ancestry of the snapshot could not be determined");
+    }
+    if (base === originCommit) {
+        return planeCheckPassed(PLANE_SNAPSHOT_FRESHNESS_ID, SNAPSHOT_LABEL, "the snapshot is ahead of origin/main");
+    }
+    if (base === snapshotCommit) {
+        return planeCheckFinding({
+            check: PLANE_SNAPSHOT_FRESHNESS_ID,
+            severity: "blocking",
+            message: "the plane snapshot is behind origin/main.",
+            remediation: PLANE_SNAPSHOT_STALE_REMEDY,
+        }, SNAPSHOT_LABEL, "the plane snapshot is behind origin/main");
+    }
+    // Both sides moved. That is not proof of staleness, and not proof of freshness.
+    return unverifiedSnapshot("the snapshot and origin/main have diverged");
+}
+/**
+ * Collect the snapshot and database freshness reports, independently: an
+ * unverified snapshot never suppresses a confirmed database refusal, or the
+ * reverse.
+ *
+ * `checkout` is the code root whose `alembic.ini` the database check reads. When
+ * the selected plane's manifest pins a snapshot, that snapshot is used instead —
+ * the code the plane will actually RUN — exactly as plane preflight does.
+ */
+export async function checkPlaneFreshness(repoRoot, deps, checkout, options) {
+    const timeoutMs = options.timeoutMs ?? PLANE_FRESHNESS_TIMEOUT_MS;
+    let manifestRead = null;
+    if (options.ownsManifest) {
+        try {
+            manifestRead = await deps.readPlaneManifest(repoRoot);
+        }
+        catch {
+            manifestRead = null;
+        }
+    }
+    const codeRoot = manifestRead?.kind === "valid" && manifestRead.manifest.snapshotPath !== undefined
+        ? manifestRead.manifest.snapshotPath
+        : checkout;
+    const guarded = async (run, fallback) => {
+        try {
+            return await run();
+        }
+        catch {
+            return fallback();
+        }
+    };
+    const [snapshot, database] = await Promise.all([
+        guarded(() => checkSnapshot(repoRoot, deps, options, timeoutMs, manifestRead), () => unverifiedSnapshot("the check did not complete")),
+        guarded(() => checkAlembicHead(repoRoot, { execFile: deps.execFile, fileExists: deps.fileExists, platform: deps.platform }, codeRoot), () => planeCheckFinding({
+            check: "alembic-head",
+            severity: "warning",
+            message: "could not verify database migration head: the check did not complete.",
+            remediation: PLANE_FRESHNESS_UNVERIFIED_REMEDY,
+        }, "Database migration head", "could not verify database migration head: the check did not complete")),
+    ]);
+    return { snapshot, database };
+}
+function unverifiedSleep(detail, advisories = []) {
+    const text = [...advisories, detail].join("; ");
+    return planeCheckFinding({
+        check: PLANE_HOST_SLEEP_ID,
+        severity: "warning",
+        message: text,
+        remediation: PLANE_FRESHNESS_UNVERIFIED_REMEDY,
+    }, SLEEP_LABEL, text);
+}
+/**
+ * Read this Mac's sleep posture. Advisory only: it never blocks setup.
+ *
+ * "Pass" here means "does not block setup", not "guaranteed to stay awake".
+ * `not applicable` (a skip, never a pass) off macOS. Lid-close risk comes from
+ * `pmset -g`'s `SleepDisabled`, not the idle-sleep values in `pmset -g custom`:
+ * the executor holds idle sleep off itself, but nothing holds a closed lid open.
+ */
+export async function inspectHostSleep(repoRoot, deps, options = {}) {
+    if (deps.platform !== "darwin") {
+        return planeCheckSkipped(PLANE_HOST_SLEEP_ID, SLEEP_LABEL, "not applicable on this platform");
+    }
+    const timeoutMs = options.timeoutMs ?? PLANE_FRESHNESS_TIMEOUT_MS;
+    const run = async (args) => {
+        try {
+            const result = await deps.execFile("pmset", args, { cwd: repoRoot, timeoutMs });
+            return result.ok ? result.stdout : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const [batt, settings] = await Promise.all([run(["-g", "batt"]), run(["-g"])]);
+    const advisories = [];
+    let battPresent = null;
+    let onBattery = null;
+    if (batt !== null) {
+        const source = /Now drawing from '([^']+)'/.exec(batt);
+        if (source !== null) {
+            onBattery = /battery/i.test(source[1] ?? "");
+            battPresent = onBattery || /InternalBattery|present:\s*true/i.test(batt);
+        }
+    }
+    if (onBattery === true)
+        advisories.push(PLANE_SLEEP_BATTERY_ADVISORY);
+    let sleepDisabled = null;
+    if (settings !== null) {
+        const match = /^\s*SleepDisabled\s+(\d)/m.exec(settings);
+        if (match !== null)
+            sleepDisabled = match[1] === "1";
+    }
+    if (battPresent === true && sleepDisabled === false)
+        advisories.push(PLANE_SLEEP_LID_ADVISORY);
+    // Anything we could not read is "unverified", never a quiet pass. Battery
+    // evidence that WAS readable is kept in the same report.
+    if (battPresent === null || (battPresent === true && sleepDisabled === null)) {
+        return unverifiedSleep("could not verify sleep settings", advisories);
+    }
+    if (advisories.length === 0) {
+        return planeCheckPassed(PLANE_HOST_SLEEP_ID, SLEEP_LABEL, "no host sleep risk found; does not block setup");
+    }
+    const detail = `${advisories.join("; ")}. ${PLANE_SLEEP_REMEDY} Does not block setup.`;
+    return {
+        diagnostic: null,
+        outcomes: [
+            {
+                check: PLANE_HOST_SLEEP_ID,
+                id: PLANE_HOST_SLEEP_ID,
+                label: SLEEP_LABEL,
+                status: "pass",
+                // The advice lives in `detail`: a passing outcome carries no remediation.
+                detail,
+            },
+        ],
+    };
+}