@bridge_gpt/mcp-server 0.2.51 → 0.2.53

package/build/plan-epic-conductor-eligibility.js

@@ -46,6 +46,10 @@ const UNAVAILABLE = { status: "unavailable" };
 function isNonBlankString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
+/** Shape-validate an evidence array: every element must be a string. */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
 /** Treat a missing/undefined optional field as empty text; reject a non-string value. */
 function optionalTextOrNull(value) {
     if (value === undefined || value === null)
@@ -113,8 +117,12 @@ export async function assessEpicConductorEligibility(children, deps) {
     if (response === null ||
         typeof response !== "object" ||
         !Array.isArray(response.predictions) ||
-        typeof response.total_children !== "number" ||
-        typeof response.predicted_workflow_children !== "number" ||
+        !Number.isInteger(response.total_children) ||
+        response.total_children < 0 ||
+        !Number.isInteger(response.predicted_workflow_children) ||
+        response.predicted_workflow_children < 0 ||
+        !Number.isInteger(response.containment_children) ||
+        response.containment_children < 0 ||
         typeof response.reason !== "string") {
         console.error("assessEpicConductorEligibility: malformed backend response shape; unavailable.");
         return UNAVAILABLE;
@@ -132,10 +140,17 @@ export async function assessEpicConductorEligibility(children, deps) {
             typeof prediction !== "object" ||
             !isNonBlankString(prediction.child_id) ||
             typeof prediction.predicted_workflow_modified !== "boolean" ||
-            !Array.isArray(prediction.matched_paths)) {
+            !isStringArray(prediction.matched_paths) ||
+            typeof prediction.predicted_containment_hazard !== "boolean" ||
+            !isStringArray(prediction.matched_hazards)) {
             console.error("assessEpicConductorEligibility: malformed per-child prediction; unavailable.");
             return UNAVAILABLE;
         }
+        if (prediction.predicted_containment_hazard !== (prediction.matched_hazards.length > 0)) {
+            console.error(`assessEpicConductorEligibility: child ${prediction.child_id} has a containment flag that ` +
+                "disagrees with whether matched hazard evidence is present; unavailable.");
+            return UNAVAILABLE;
+        }
         if (predictionById.has(prediction.child_id)) {
             console.error("assessEpicConductorEligibility: duplicate child_id in backend response; unavailable.");
             return UNAVAILABLE;
@@ -145,6 +160,7 @@ export async function assessEpicConductorEligibility(children, deps) {
     const affectedChildren = [];
     let reviewSubsetChildren = 0;
     let predictedWorkflowChildren = 0;
+    let containmentChildren = 0;
     for (const child of validated) {
         const prediction = predictionById.get(child.id);
         if (!prediction) {
@@ -160,24 +176,38 @@ export async function assessEpicConductorEligibility(children, deps) {
                 "but the backend did not mark it merge-blocked; refusing contradictory result.");
             return UNAVAILABLE;
         }
-        if (!prediction.predicted_workflow_modified)
+        if (prediction.predicted_workflow_modified) {
+            predictedWorkflowChildren += 1;
+            if (reviewPathReferenced)
+                reviewSubsetChildren += 1;
+        }
+        if (prediction.predicted_containment_hazard)
+            containmentChildren += 1;
+        // A child is affected — and therefore included — when it is workflow-modifying,
+        // containment-flagged, or both. Skip only a child that is neither.
+        if (!prediction.predicted_workflow_modified && !prediction.predicted_containment_hazard)
             continue;
-        predictedWorkflowChildren += 1;
-        if (reviewPathReferenced)
-            reviewSubsetChildren += 1;
         affectedChildren.push({
             id: child.id,
             title: child.title,
             matchedPaths: [...prediction.matched_paths],
             requiresHandReview: reviewPathReferenced,
+            requiresContainmentReview: prediction.predicted_containment_hazard,
+            matchedHazards: [...prediction.matched_hazards],
         });
     }
+    if (containmentChildren !== response.containment_children) {
+        console.error("assessEpicConductorEligibility: containment_children count disagrees with the validated " +
+            "per-child containment flags; unavailable.");
+        return UNAVAILABLE;
+    }
     return {
         status: "assessed",
         totalChildren: validated.length,
         predictedWorkflowChildren,
         reason: response.reason,
         reviewSubsetChildren,
+        containmentChildren,
         affectedChildren,
     };
 }

package/build/plane/alembic-head.js

@@ -13,10 +13,16 @@
  * condition it guards is already reported loudly by the server at dispatch time.
  */
 import path from "path";
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
 /** Remediation embedded in a confirmed-mismatch diagnostic. */
 export const PLANE_ALEMBIC_REMEDIATION = "alembic -c alembic.ini upgrade head";
 /** Fixed prefix of the fail-open warning, so tests and greps can match it. */
 export const PLANE_ALEMBIC_UNVERIFIED_PREFIX = "could not verify database migration head";
+/** Structured fix for a confirmed migration mismatch. */
+export const PLANE_ALEMBIC_MISMATCH_REMEDIATION = `run \`${PLANE_ALEMBIC_REMEDIATION}\` to bring the database up to the migration head, then retry.`;
+/** Structured fix for an unverifiable migration head. Never blocking. */
+export const PLANE_ALEMBIC_UNVERIFIED_REMEDIATION = "verify by hand with `alembic -c alembic.ini heads` and `alembic -c alembic.ini current`; " +
+    "startup continues, and the server reports CONTRACT_MIGRATION_BEHIND at dispatch if the database is behind.";
 /**
  * Path to the repository virtualenv's Alembic executable.
  *
@@ -72,39 +78,62 @@ export function parseAlembicRevisions(output) {
 export async function checkAlembicHead(repoRoot, deps) {
     const alembic = resolveRepositoryAlembicCommand(repoRoot, deps.platform);
     if (!(await deps.fileExists(alembic))) {
-        return unverified("the repository virtualenv Alembic executable was not found");
+        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 });
     if (!heads.ok) {
-        return unverified(`\`alembic heads\` did not complete (${heads.error})`);
+        // The interpolated `error` stays in the legacy message for the operator at
+        // the terminal; the consolidated detail is fixed prose. In production that
+        // field is an errno code, but this outcome flows into a wider report and
+        // 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 });
     if (!current.ok) {
-        return unverified(`\`alembic current\` did not complete (${current.error})`);
+        return unverified(`\`alembic current\` did not complete (${current.error})`, "`alembic current` did not complete");
     }
     const headRevisions = parseAlembicRevisions(heads.stdout);
     const currentRevisions = parseAlembicRevisions(current.stdout);
     if (headRevisions === null || currentRevisions === null) {
-        return unverified("Alembic output did not contain a readable revision");
+        return unverified("Alembic output did not contain a readable revision", "Alembic output did not contain a readable revision");
     }
     const matches = headRevisions.length === currentRevisions.length &&
         headRevisions.every((rev, i) => rev === currentRevisions[i]);
-    if (matches)
-        return null;
-    return {
+    if (matches) {
+        return planeCheckPassed("alembic-head", ALEMBIC_CHECK_LABEL, "the database is at the repository migration head");
+    }
+    return planeCheckFinding({
         check: "alembic-head",
         severity: "blocking",
         message: `the database is not at the migration head — heads [${headRevisions.join(", ")}], ` +
             `current [${currentRevisions.join(", ")}]. A database behind the head blocks ` +
             `conductor dispatch. Run \`${PLANE_ALEMBIC_REMEDIATION}\``,
-    };
+        remediation: PLANE_ALEMBIC_MISMATCH_REMEDIATION,
+    }, ALEMBIC_CHECK_LABEL, 
+    // Revision ids are repository-authored slugs, not secrets, and they are the
+    // one fact that makes this finding actionable.
+    `database at [${currentRevisions.join(", ")}], repository head [${headRevisions.join(", ")}]`);
 }
-function unverified(detail) {
-    return {
+/** Human-readable name for the migration-head prerequisite. */
+const ALEMBIC_CHECK_LABEL = "Database migration head";
+/**
+ * The fail-open branch: warning severity, and never blocking.
+ *
+ * TWO details, deliberately. `messageDetail` is the legacy operator-facing prose
+ * and may name the command's own `error` field; `outcomeDetail` is fixed prose
+ * only, because the outcome flows into the consolidated readiness report. The
+ * production `execFile` adapter puts an errno code in `error`, but this
+ * separation means the consolidated report stays safe even if some caller ever
+ * puts raw stderr, an interpreter path, or a thrown message there.
+ */
+function unverified(messageDetail, outcomeDetail) {
+    const diagnostic = {
         check: "alembic-head",
         severity: "warning",
-        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${detail}. Startup continues — verify with ` +
+        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${messageDetail}. Startup continues — verify with ` +
             `\`alembic -c alembic.ini heads\` and \`alembic -c alembic.ini current\` if a run ` +
             "later reports CONTRACT_MIGRATION_BEHIND.",
+        remediation: PLANE_ALEMBIC_UNVERIFIED_REMEDIATION,
     };
+    return planeCheckFinding(diagnostic, ALEMBIC_CHECK_LABEL, `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${outcomeDetail}`);
 }

package/build/plane/build-freshness.js

@@ -13,6 +13,7 @@
  * can be older than a rebuild that overwrote files in place.
  */
 import path from "path";
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
 /** Remediation text embedded in every blocking build diagnostic. */
 export const PLANE_BUILD_REMEDIATION = "cd mcp_server && npm run build";
 /**
@@ -93,42 +94,49 @@ export async function findBuildMtime(executorEntrypoint, deps) {
  * stale or absent build is exactly the failure this check exists to prevent, so
  * unlike the Alembic check there is no fail-open branch.
  */
+export const PLANE_BUILD_FIX_REMEDIATION = "run `cd mcp_server && npm run build` to rebuild the executor entrypoint, then retry.";
 export async function checkPlaneBuildFreshness(repoRoot, deps) {
+    const label = "Executor build freshness";
     const packageRoot = path.join(repoRoot, "mcp_server");
     const buildDir = path.join(packageRoot, "build");
     const executorEntrypoint = path.join(buildDir, "index.js");
     const srcDir = path.join(packageRoot, "src");
     const buildMtime = await findBuildMtime(executorEntrypoint, deps);
     if (!buildMtime.ok) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: `the executor build entrypoint is missing or unreadable at ` +
                 `mcp_server/build/index.js — run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, "the executor build entrypoint is missing or unreadable");
     }
     const sourceMtime = await findNewestSourceMtime(srcDir, deps);
     if (!sourceMtime.ok) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: `could not read mcp_server/src to compare against the build ` +
                 `(${sourceMtime.error}) — run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, 
+        // `sourceMtime.error` is an errno code, already sanitized by `sanitize()`.
+        `the executor sources could not be read for comparison (${sourceMtime.error})`);
     }
     // Equality passes: a build written in the same millisecond as its newest
     // source is current, and treating the boundary as stale would refuse a
     // perfectly good build on a coarse-resolution filesystem.
     if (sourceMtime.mtimeMs !== null && sourceMtime.mtimeMs > buildMtime.mtimeMs) {
-        return {
+        return planeCheckFinding({
             check: "executor-build",
             severity: "blocking",
             message: "mcp_server/build/ is STALE — a source file under mcp_server/src is newer " +
                 `than mcp_server/build/index.js, so executors would run old code. ` +
                 `Run \`${PLANE_BUILD_REMEDIATION}\``,
-        };
+            remediation: PLANE_BUILD_FIX_REMEDIATION,
+        }, label, "mcp_server/build/ is stale — a source file is newer than the build entrypoint");
     }
-    return null;
+    return planeCheckPassed("executor-build", label, "the executor build is present and current");
 }
 /**
  * Fixed refusal prose for an unresolvable runtime re-exec target (BAPI-768).
@@ -153,13 +161,16 @@ export const PLANE_RUNTIME_ENTRYPOINT_REFUSAL = "the currently executing MCP bui
  * degraded plane, it is no plane at all.
  */
 export function checkPlaneRuntimeEntrypoint(resolution) {
-    if (resolution.ok)
-        return null;
-    return {
+    const label = "Runtime re-exec entrypoint";
+    if (resolution.ok) {
+        return planeCheckPassed("runtime-entrypoint", label, "the executing build can re-enter itself");
+    }
+    return planeCheckFinding({
         check: "runtime-entrypoint",
         severity: "blocking",
         message: PLANE_RUNTIME_ENTRYPOINT_REFUSAL,
-    };
+        remediation: PLANE_BUILD_FIX_REMEDIATION,
+    }, label, "the currently executing MCP build could not be re-entered");
 }
 function sanitize(err) {
     const code = err?.code;

package/build/plane/cli.js

@@ -12,7 +12,7 @@
  * 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, } 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_RUNTIME_ACTION, PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
 import { PLANE_RUNTIME_ENTRYPOINT_REFUSAL } from "./build-freshness.js";
 import { relativeLogPathFor } from "./manifest.js";
 import { claimPlaneManifest } from "./manifest.js";
@@ -21,7 +21,7 @@ import { buildPlaneMemberRoster, resolvePlaneServerEndpoint } from "./member-ros
 import { getPlaneStatus, formatPlaneStatus } from "./status.js";
 import { shutdownPlane, formatPlaneShutdown } from "./shutdown.js";
 import { launchPlaneSupervisor, runPlaneRuntime, } from "./supervisor.js";
-import { createMemberLogDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, createPlaneSpawn, probeTcpPort, registerSignalHandler, resolveHomedir, resolveNodeExecutable, resolvePackageEntrypoint, } from "./defaults.js";
+import { createMemberLogDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, createPlaneSpawn, probeAutomationHealth, probeTcpPort, registerSignalHandler, resolveHomedir, resolveHostname, resolveNodeExecutable, resolvePackageEntrypoint, } from "./defaults.js";
 import { resolveBapiCredentials } from "../credential-store.js";
 import { resolveRequiredStartTicketsRepoName } from "../start-tickets-repo.js";
 /** Upper bound on executor lanes. Guards a typo from forking a fleet. */
@@ -128,7 +128,15 @@ export function getPlaneUsage() {
         "Usage: mcp-server plane <up|status|down> [options]",
         "",
         "Brings up (and winds down) the attended conductor plane in one command:",
-        "the Bridge API server, the reconciler worker, and one executor per lane.",
+        "the Bridge API server, the dead-man observer, the reconciler worker, and",
+        "one executor per lane.",
+        "",
+        "This is the MANUAL / two-step path (BAPI-1054). To stand a plane up and create",
+        "the run together, use `drive-epic <EPIC> --plan-file <path>`, which starts the",
+        "plane for you when that is the only thing missing. Reach for `plane up` directly",
+        "when you want the runtime without a run, when you are driving an epic whose plane",
+        "is already live, or to recover after a composed bring-up reported a live plane it",
+        "did not wind down. Nothing about this command's behavior has changed.",
         "",
         "Actions:",
         "  plane up [--executors N]   Preflight, then start the plane. Refuses as a",
@@ -151,18 +159,32 @@ export function getPlaneUsage() {
         "    (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.",
-        "  * The dead-man observer is NOT part of the plane. It is started and stopped",
-        "    by you, so its failure domain stays independent of the supervisor's.",
-        `    Start it separately: ${PLANE_OBSERVER_COMMAND}`,
+        "  * 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",
+        "    worker comes up. Same-host only — this is not separate-host resilience.",
+        "  * The reconciler worker is not reported ready until it has published a FRESH",
+        "    durable heartbeat, read back through GET /automation/health. `plane up`",
+        "    cannot print a success banner over a reconciler that never ticked.",
         "",
         `Runtime artifacts (manifest + per-member logs) live under ${PLANE_RUNTIME_DIR}/.`,
     ].join("\n");
 }
-/** The observer reminder printed at the end of a successful startup banner. */
-export function getPlaneObserverReminder() {
+/**
+ * How to start the dead-man observer BY HAND.
+ *
+ * No longer printed by `plane up` (BAPI-1029): the plane starts the observer
+ * itself, and telling an operator to start a second one would give them two
+ * evaluators racing the same outage. It is retained for the documented
+ * session-background FALLBACK, which runs the reconciler outside the plane and
+ * therefore has no observer of its own — the one arrangement where this command
+ * is still the right instruction.
+ */
+export function getPlaneObserverFallbackInstructions() {
     return [
         "",
-        "Dead-man observer (independent — not started, listed, or stopped by the plane):",
+        "Dead-man observer for the SESSION-BACKGROUND FALLBACK only (`plane up` starts",
+        "its own observer and needs none of this):",
         `  ${PLANE_OBSERVER_COMMAND}`,
         `  with ${PLANE_OBSERVER_CHANNEL_TYPE_ENV} (slack_webhook|generic_webhook) and`,
         `  ${PLANE_OBSERVER_DESTINATION_ENV} (the NAME of an env var holding the URL).`,
@@ -327,7 +349,7 @@ async function runUpAction(executors, sinks, overrides) {
     const env = overrides.env ?? process.env;
     const preflight = overrides.preflight
         ? await overrides.preflight(repoRoot)
-        : await runPlanePreflight(repoRoot, buildPreflightDeps(env));
+        : await runDefaultPlanePreflight(repoRoot, env);
     for (const diagnostic of preflight.diagnostics.filter((d) => d.severity === "warning")) {
         sinks.stdout(formatDiagnostic(diagnostic));
     }
@@ -366,9 +388,16 @@ export const PLANE_STARTUP_FAILED = "plane up FAILED — the runtime never came
  */
 export function formatPlaneLaunchFailure(launch) {
     if (!launch.startup) {
-        // No child exit information exists, so none is invented — this is the
-        // pre-existing generic spawn-failure path, preserved verbatim in substance.
-        return [`plane up FAILED: ${launch.error}`];
+        // No child exit information exists, so none is invented. The trace pointer
+        // is still emitted (BAPI-1029): a launch that never produced a usable child
+        // used to print one bare line with nowhere to look next, which is the same
+        // dead end BAPI-768 presented as. The file may be empty or absent — saying
+        // where it would be costs nothing and is the only lead this branch has.
+        return [
+            `plane up FAILED: ${launch.error}`,
+            `  trace  ${PLANE_RUNTIME_LOG_PATH} (may be empty — the runtime never started)`,
+            "The plane is not running. `no processes were started`.",
+        ];
     }
     const { exitCode, signal, stderrExcerpt, tracePath } = launch.startup;
     const status = signal !== null ? `signal ${signal}` : `exit code ${exitCode ?? "unknown"}`;
@@ -457,9 +486,8 @@ 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}/`);
+    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.");
-    for (const line of getPlaneObserverReminder())
-        sinks.stdout(line);
     sinks.stdout("");
 }
 /** The private detached-runtime action. Never part of the documented surface. */
@@ -520,6 +548,16 @@ async function runRuntimeAction(executors, overrides) {
         log: createMemberLogDeps(),
         onSignal: registerSignalHandler,
         probePort: probeTcpPort,
+        // The heartbeat readiness reader (BAPI-1029; component-aware since
+        // BAPI-1036). Bound here beside the TCP probe rather than constructed inside
+        // the supervisor, so a unit test substitutes it the same way it substitutes
+        // every other real-I/O seam.
+        probeHealth: probeAutomationHealth,
+        // Half of the local reconciler's published identity (`<hostname>:<pid>`).
+        // Injected for the same reason as every other platform read here: the
+        // supervisor must rebuild a string another process minted, and a test has to
+        // be able to pin that reconstruction without a real hostname.
+        hostname: resolveHostname,
         selfPid: process.pid,
         planeId,
     });
@@ -550,6 +588,31 @@ function buildPreflightDeps(env) {
         resolveCredentials: resolveBapiCredentials,
     };
 }
+/**
+ * The production preflight, as a named seam other commands can reuse (BAPI-1054).
+ *
+ * `drive-epic` composes `plane up`, and it must inspect the SAME preflight this
+ * command runs — same endpoint resolution, same credential resolution, same port
+ * probe, same worktree predicate. Re-resolving any of that at the caller is how
+ * two answers to one question appear: a caller could refuse on a port the plane
+ * was never going to use, or approve one it was.
+ *
+ * Thin by design. It owns no policy — only the `(repoRoot, env)` -> result
+ * binding, so there is exactly one place that knows how a real preflight is built.
+ */
+export function runDefaultPlanePreflight(repoRoot, env = process.env) {
+    return runPlanePreflight(repoRoot, buildPreflightDeps(env));
+}
+/**
+ * Render ONE diagnostic exactly as `plane up` renders it (BAPI-1054).
+ *
+ * Exported so a composing caller surfaces a plane refusal in the plane's own
+ * words. A second renderer would drift, and an operator reading two different
+ * spellings of one check has to work out whether they are the same finding.
+ */
+export function formatPlaneDiagnostic(diagnostic) {
+    return formatDiagnostic(diagnostic);
+}
 function formatDiagnostic(diagnostic) {
     const label = diagnostic.severity === "blocking" ? "BLOCKED" : "WARN   ";
     return `  ${label} [${diagnostic.check}] ${diagnostic.message}`;

package/build/plane/defaults.js

@@ -15,6 +15,7 @@ import net from "net";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
+import { PLANE_HEARTBEAT_HEALTH_STATES, } from "./types.js";
 import { isProcessAlive } from "./manifest.js";
 /** Filesystem primitives bound to `node:fs/promises`. */
 export function createPlaneFsDeps() {
@@ -269,6 +270,170 @@ function defaultIsFile(filePath) {
         return false;
     }
 }
+/**
+ * Per-request budget for one automation-health readiness poll.
+ *
+ * Deliberately much smaller than the readiness budget it runs inside: a hung
+ * request must cost one poll, not the whole 120-second window. Without a
+ * per-request bound, a server that accepts the connection and never answers
+ * would consume the entire budget in a single call and the failure would be
+ * reported as "the reconciler never became fresh" rather than as a hung route.
+ */
+export const PLANE_HEALTH_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Read one component's durable-heartbeat verdict from `GET /automation/health`.
+ *
+ * ## What this does not do
+ *
+ * It does not compute an age, compare against a threshold, or decide what
+ * "fresh" means. `api/library/reconciler_liveness.py` already derives the
+ * verdict against `RECONCILER_STALE_SECONDS` / `EXECUTOR_STALE_SECONDS` and
+ * every other consumer reads that same derivation; a second threshold here is
+ * exactly how a launcher and a health page end up disagreeing at the boundary.
+ * This transports the backend's answer, normalizes its observation timestamp,
+ * and classifies the ways the answer can fail to arrive.
+ *
+ * ## Instance scoping (BAPI-1036)
+ *
+ * `component` selects which block of the response is read.  `instanceId`, when
+ * given, additionally asks the route to derive THAT block from one published
+ * identity. The two travel together or not at all, because the route refuses a
+ * partial pair with a 422 — which this probe would classify as `unavailable`
+ * and then wait out, turning a caller's mistake into a budget burn.
+ *
+ * ## Secret handling
+ *
+ * The API key is sent in `X-API-Key`, the convention every other Bridge client
+ * in this package uses. It is never placed in the URL (which reaches proxy logs
+ * and error strings), never returned, and never rendered: every failure arm of
+ * {@link PlaneHealthProbeResult} is a bare tag with no body, header, status
+ * text, or exception message attached. The observation timestamp returned
+ * BESIDE that classification is a server-derived time and nothing else; see
+ * {@link PlaneHealthObservation} for why it is kept outside the union.
+ */
+export async function probeAutomationHealth(request) {
+    let url;
+    try {
+        const target = new URL("/automation/health", request.baseUrl);
+        target.searchParams.set("repo_name", request.repoName);
+        // BOTH or NEITHER. The route validates the pair and 422s on half of it.
+        if (request.instanceId !== undefined) {
+            target.searchParams.set("component", request.component);
+            target.searchParams.set("instance_id", request.instanceId);
+        }
+        url = target.toString();
+    }
+    catch {
+        // An unparseable base URL is a configuration fault, not a transport blip.
+        return unclassified({ kind: "malformed" });
+    }
+    const doFetch = request.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await doFetch(url, {
+            method: "GET",
+            headers: { "X-API-Key": request.apiKey, Accept: "application/json" },
+            signal: AbortSignal.timeout(request.timeoutMs ?? PLANE_HEALTH_PROBE_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Connection refused, DNS failure, abort on timeout — all retryable, and all
+        // capable of carrying the request URL in their message. None is rendered.
+        return unclassified({ kind: "unavailable" });
+    }
+    // 401/403 are terminal for readiness: the key in the member environment is not
+    // accepted, and polling for two more minutes will not change that.
+    if (response.status === 401 || response.status === 403) {
+        return unclassified({ kind: "unauthorized" });
+    }
+    if (!response.ok)
+        return unclassified({ kind: "unavailable" });
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return unclassified({ kind: "malformed" });
+    }
+    const reading = readComponentObservation(body, request.component);
+    if (reading === null)
+        return unclassified({ kind: "malformed" });
+    return { result: { kind: "state", state: reading.state }, observedAtMs: reading.observedAtMs };
+}
+/** A reading that carries a classification and no observation. */
+function unclassified(result) {
+    return { result, observedAtMs: null };
+}
+/**
+ * The requested component's state and observation time, or `null` for a body
+ * this code does not recognize.
+ *
+ * Every hop is guarded rather than asserted. An unrecognized string is
+ * `malformed`, NOT `unknown`: the backend's `unknown` means "the durable source
+ * could not be read" and is a retryable waiting state, whereas a state string
+ * this code does not recognize means the contract moved — and quietly treating
+ * a renamed state as a transient read failure would make the launcher wait out
+ * its whole budget and then report the wrong reason.
+ *
+ * The two blocks sit at different paths and spell their timestamp field
+ * differently, which is precisely why this reads them by component rather than
+ * from one hardcoded key:
+ *
+ * - reconciler → `body.reconciler.state` / `body.reconciler.heartbeat_last_seen_at`
+ * - executor   → `body.executor.process_heartbeat.state` / `…​.last_seen_at`
+ */
+function readComponentObservation(body, component) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    let block;
+    let timestampKey;
+    if (component === "reconciler") {
+        block = body.reconciler;
+        timestampKey = "heartbeat_last_seen_at";
+    }
+    else {
+        const executor = body.executor;
+        if (typeof executor !== "object" || executor === null)
+            return null;
+        block = executor.process_heartbeat;
+        timestampKey = "last_seen_at";
+    }
+    if (typeof block !== "object" || block === null)
+        return null;
+    const state = block.state;
+    if (typeof state !== "string")
+        return null;
+    if (!PLANE_HEARTBEAT_HEALTH_STATES.includes(state))
+        return null;
+    const known = state;
+    const raw = block[timestampKey];
+    if (raw === null || raw === undefined) {
+        // A timestamp is REQUIRED for the two states derived from an actual row.
+        // `never_seen` has no row and `unknown` means the source could not be read,
+        // so for those an absent time is the contract, not a violation.
+        return known === "fresh" || known === "stale" ? null : { state: known, observedAtMs: null };
+    }
+    if (typeof raw !== "string")
+        return null;
+    const observedAtMs = Date.parse(raw);
+    // An unparseable timestamp on a state that must have one is a moved contract,
+    // not a transient failure — the same reasoning as an unrecognized state.
+    if (Number.isNaN(observedAtMs))
+        return null;
+    return { state: known, observedAtMs };
+}
+/**
+ * The host identity the local reconciler publishes half of its instance id from.
+ *
+ * A seam, not a convenience: `_resolve_process_instance_id` builds
+ * `<hostname>:<pid>` from Python's `socket.gethostname()`, and the supervisor
+ * must reproduce that string exactly to scope a readiness probe to the process
+ * it just spawned. Injecting it keeps the resolver unit-testable without a real
+ * hostname, and keeps the comparison visible rather than buried in a global.
+ */
+export function resolveHostname() {
+    return os.hostname();
+}
 /** Node executable used for the runtime re-exec and executor members. */
 export function resolveNodeExecutable() {
     return process.execPath;