@bridge_gpt/mcp-server 0.2.50 → 0.2.52

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

@@ -0,0 +1,213 @@
+/**
+ * Combined merge/review conductor-eligibility assessment for `plan-epic` (BAPI-964).
+ *
+ * Runs once the epic decomposition's child manifest is frozen and every
+ * sub-task's exploration text is written, so this module can predict — before
+ * any conductor worker is spawned — which children are likely to trip the
+ * runtime workflow-file merge guard (`api/library/vcs/conductor_merge_service.py`)
+ * and which of those additionally touch `claude-review.yml` itself, where
+ * automated review cannot run at all (BAPI-941's supply-chain preflight refuses
+ * to review a workflow that differs from the base branch's copy).
+ *
+ * The BROADER merge classification is delegated entirely to the Python
+ * classifier via one Bridge API call for the complete child set — this module
+ * never reimplements "what counts as a workflow file". The NARROWER review
+ * subclass is classified locally by checking each child's combined text for the
+ * full `CLAUDE_REVIEW_WORKFLOW_RELPATH`, imported (not re-declared) from
+ * `claude-review-workflow-drift.js`.
+ *
+ * Fails open, deliberately: any validation failure, classification failure, or
+ * internal contradiction (a review-subset child the backend did not also mark
+ * merge-blocked) becomes the explicit `unavailable` result — never a fabricated
+ * zero count. A caller that cannot get a real answer must say so, not guess.
+ */
+import { CLAUDE_REVIEW_WORKFLOW_RELPATH } from "./claude-review-workflow-drift.js";
+/**
+ * Build the real network-backed classification client that POSTs the complete
+ * child set to `/jira/planning/epic-workflow-eligibility` exactly once.
+ */
+export function createBridgeEpicConductorEligibilityClient(deps) {
+    return {
+        async classifyChildren(children) {
+            const fetchImpl = deps.fetchImpl ?? fetch;
+            const resp = await fetchImpl(deps.buildUrl("/planning/epic-workflow-eligibility"), {
+                method: "POST",
+                headers: await deps.getPostHeaders(),
+                body: JSON.stringify({ repo_name: deps.repoName, children }),
+            });
+            if (!resp.ok) {
+                throw new Error(`epic-workflow-eligibility classification request failed: ${resp.status}`);
+            }
+            return (await resp.json());
+        },
+    };
+}
+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)
+        return "";
+    return typeof value === "string" ? value : null;
+}
+/** Deterministically assemble one child's scan text from its authoritative fields. */
+function buildCombinedText(child) {
+    return [child.title, child.scope, child.description, child.requirements]
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join("\n\n");
+}
+/** Validate the child collection at the module boundary. `null` means malformed. */
+function validateChildren(children) {
+    if (!Array.isArray(children) || children.length === 0)
+        return null;
+    const validated = [];
+    for (const child of children) {
+        if (child === null || typeof child !== "object")
+            return null;
+        if (!isNonBlankString(child.id) || !isNonBlankString(child.title))
+            return null;
+        const scope = optionalTextOrNull(child.scope);
+        const description = optionalTextOrNull(child.description);
+        const requirements = optionalTextOrNull(child.requirements);
+        if (scope === null || description === null || requirements === null)
+            return null;
+        validated.push({
+            id: child.id,
+            title: child.title,
+            combinedText: buildCombinedText({
+                id: child.id,
+                title: child.title,
+                scope,
+                description,
+                requirements,
+            }),
+        });
+    }
+    return validated;
+}
+/**
+ * Assess conductor merge/review eligibility for one frozen epic child set.
+ *
+ * Sends the complete ordered child set to the injected Bridge client exactly
+ * once. Never throws — every failure path (malformed input, client rejection,
+ * malformed backend response, an internal merge/review contradiction) resolves
+ * to the explicit `unavailable` result, diagnosed with `console.error` (never
+ * `console.log`, which is reserved for the MCP stdio transport).
+ */
+export async function assessEpicConductorEligibility(children, deps) {
+    const validated = validateChildren(children);
+    if (validated === null) {
+        console.error("assessEpicConductorEligibility: malformed child collection; unavailable.");
+        return UNAVAILABLE;
+    }
+    let response;
+    try {
+        response = await deps.client.classifyChildren(validated.map((child) => ({ child_id: child.id, combined_text: child.combinedText })));
+    }
+    catch (err) {
+        console.error("assessEpicConductorEligibility: Bridge classification call failed:", err);
+        return UNAVAILABLE;
+    }
+    if (response === null ||
+        typeof response !== "object" ||
+        !Array.isArray(response.predictions) ||
+        !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;
+    }
+    if (response.predictions.length !== validated.length) {
+        console.error("assessEpicConductorEligibility: backend prediction count does not match child count; unavailable.");
+        return UNAVAILABLE;
+    }
+    // The backend is contractually order-preserving; still verify identity and
+    // order rather than trusting it, so a reordered/duplicate/unknown response
+    // never silently mislabels a child's prediction.
+    const predictionById = new Map();
+    for (const prediction of response.predictions) {
+        if (prediction === null ||
+            typeof prediction !== "object" ||
+            !isNonBlankString(prediction.child_id) ||
+            typeof prediction.predicted_workflow_modified !== "boolean" ||
+            !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;
+        }
+        predictionById.set(prediction.child_id, prediction);
+    }
+    const affectedChildren = [];
+    let reviewSubsetChildren = 0;
+    let predictedWorkflowChildren = 0;
+    let containmentChildren = 0;
+    for (const child of validated) {
+        const prediction = predictionById.get(child.id);
+        if (!prediction) {
+            console.error(`assessEpicConductorEligibility: backend response is missing child ${child.id}; unavailable.`);
+            return UNAVAILABLE;
+        }
+        const reviewPathReferenced = child.combinedText.includes(CLAUDE_REVIEW_WORKFLOW_RELPATH);
+        if (reviewPathReferenced && !prediction.predicted_workflow_modified) {
+            // Subset invariant violated: a child naming claude-review.yml itself must
+            // also be in the broader merge-blocked set. Publishing this as a
+            // "review-only" child would contradict the merge count, so refuse instead.
+            console.error(`assessEpicConductorEligibility: child ${child.id} references the review workflow ` +
+                "but the backend did not mark it merge-blocked; refusing contradictory result.");
+            return UNAVAILABLE;
+        }
+        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;
+        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/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;