@bridge_gpt/mcp-server 0.2.51 → 0.2.53

package/build/plane/types.js

@@ -2,23 +2,59 @@
  * Typed contracts for the conductor plane supervisor (BAPI-756, slice C4).
  *
  * The plane is the attended set of processes a conductor run needs: the Bridge
- * API server, the reconciler worker, and one executor per parallel lane. This
- * module carries every boundary type so the runtime modules (preflight,
- * manifest, roster, supervisor, status, shutdown) stay independently testable
- * with injected dependencies and never reach for real I/O in a unit test.
+ * API server, the reconciler worker, one executor per parallel lane, and the
+ * dead-man observer. This module carries every boundary type so the runtime
+ * modules (preflight, manifest, roster, supervisor, status, shutdown) stay
+ * independently testable with injected dependencies and never reach for real
+ * I/O in a unit test.
  *
  * Two ratified requirements shape these types and must not be softened:
  *
- * - **R-3, the dead-man observer stays outside.** There is deliberately no
- *   observer member name, no observer log path, and no observer manifest
- *   record. Its failure domain is independent of the supervisor's by design
- *   (`worker.py:80-85`), so the supervisor never owns its lifecycle.
+ * - **R-1, the dead-man observer is a same-host, separate-process member**
+ *   (BAPI-1029, superseding R-3). The observer runs `worker.py` with
+ *   `CONDUCTOR_DEAD_MAN_ONLY=true` in its OWN OS process, owned by the plane
+ *   lifecycle: it has a member name, a log path, and a manifest record, and
+ *   `plane status` / `plane down` treat it like every other member. Its failure
+ *   domain is independent at the PROCESS level — killing the reconciler leaves
+ *   the observer alive to report the death, which is the whole point. It is NOT
+ *   separate-host isolation; that is A2/R36 and is deliberately out of scope.
+ *   The previous R-3 arrangement (observer absent by construction, started
+ *   out-of-band) could not detect its own death and is retired.
  * - **R-4, crashes are never auto-restarted.** No type here carries a restart
  *   count, a backoff delay, or a retry budget, because no such machinery
  *   exists. A member exit is a finding to report, not a condition to repair.
+ *   The observer inherits this unchanged: it is spawned once and never revived.
  */
-/** Manifest schema version. Bump only with a matching parser change. */
-export const PLANE_MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * Manifest schema version WRITTEN by this build. Bump only with a matching
+ * parser change.
+ *
+ * Bumped to 2 by BAPI-1029, which added the `observer` member. The member set
+ * widened rather than the record shape, so the tempting conclusion was that no
+ * bump was needed — but that reasoning only covers the direction nobody is hurt
+ * by. Old manifests stay readable by a new binary; a NEW manifest is
+ * unreadable by an OLD one, because `isPlaneMemberName` there does not know
+ * `observer` and a single unrecognized name aborted the whole parse. `plane
+ * down` on the old build then returns `unvalidated-manifest` having signalled
+ * nothing, orphaning a fully detached plane and telling the operator to delete
+ * the file by hand.
+ *
+ * The bump does not fix that for an already-shipped old binary — nothing can —
+ * but it makes the failure legible ("schema version is not supported" instead
+ * of what reads like a corrupt file), and it pairs with the member-scoped
+ * rejection in `manifest.ts` so the next member added never reproduces it.
+ */
+export const PLANE_MANIFEST_SCHEMA_VERSION = 2;
+/**
+ * Every schema version this build can READ.
+ *
+ * Deliberately wider than what it writes. A plane already running under the
+ * previous build has a version-1 manifest on disk, and refusing it would
+ * orphan that plane on upgrade — the same failure this bump exists to make
+ * legible, inflicted from the other side. Accepting 1 costs nothing: the two
+ * versions differ only in whether `observer` may appear among the members.
+ */
+export const PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS = [1, 2];
 /** Runtime artifact directory, relative to the repository root. */
 export const PLANE_RUNTIME_DIR = ".bridge/plane";
 /** Manifest filename inside {@link PLANE_RUNTIME_DIR}. */
@@ -87,9 +123,80 @@ export const PLANE_ENTRYPOINT_ACTION = "__entrypoint";
  * together with the runtime's own pid.
  */
 export const PLANE_ID_ENV_VAR = "BAPI_PLANE_ID";
-/** The exact independent dead-man observer command (R-3). Never spawned here. */
+/**
+ * Operator-facing prose for the dead-man observer, as a copy-pasteable shell
+ * line.
+ *
+ * This is DOCUMENTATION, not an invocation. `plane up` spawns the observer with
+ * a shell-free executable plus argument vector and an observer-only child
+ * environment (see `member-roster.ts#buildPlaneObserverEnv`) — a shell string is
+ * never handed to `spawn`. The constant survives because the documented
+ * session-background FALLBACK still starts the observer by hand, and because an
+ * operator debugging the plane needs to know exactly what the observer member is.
+ */
 export const PLANE_OBSERVER_COMMAND = "CONDUCTOR_DEAD_MAN_ONLY=true python worker.py";
+/** Env var that puts `worker.py` into dead-man-only mode. Observer member ONLY. */
+export const PLANE_OBSERVER_MODE_ENV = "CONDUCTOR_DEAD_MAN_ONLY";
+/** The exact value {@link PLANE_OBSERVER_MODE_ENV} is set to for the observer. */
+export const PLANE_OBSERVER_MODE_VALUE = "true";
 /** Env var naming the observer's alert channel type. */
 export const PLANE_OBSERVER_CHANNEL_TYPE_ENV = "CONDUCTOR_DEADMAN_CHANNEL_TYPE";
 /** Env var naming the env var that holds the observer's destination URL. */
 export const PLANE_OBSERVER_DESTINATION_ENV = "CONDUCTOR_DEADMAN_DESTINATION_REF";
+/** Build a {@link PlaneCheckReport} for a check that ran and passed. */
+export function planeCheckPassed(check, label, detail) {
+    return {
+        diagnostic: null,
+        outcomes: [{ check, id: check, label, status: "pass", ...(detail ? { detail } : {}) }],
+    };
+}
+/**
+ * Build a {@link PlaneCheckReport} from a diagnostic plus its structured fix.
+ *
+ * The severity is the single source of the canonical status — `blocking` is
+ * `fail`, `warning` is `warn` — so the two can never disagree about the same
+ * finding.
+ */
+export function planeCheckFinding(diagnostic, label, detail) {
+    return {
+        diagnostic,
+        outcomes: [
+            {
+                check: diagnostic.check,
+                id: diagnostic.check,
+                label,
+                status: diagnostic.severity === "blocking" ? "fail" : "warn",
+                detail,
+                ...(diagnostic.remediation ? { remediation: diagnostic.remediation } : {}),
+            },
+        ],
+    };
+}
+/** Build a {@link PlaneCheckReport} for a check that was never reached. */
+export function planeCheckSkipped(check, label, detail) {
+    return {
+        diagnostic: null,
+        outcomes: [{ check, id: check, label, status: "skip", detail }],
+    };
+}
+/**
+ * Every value {@link PlaneHeartbeatComponent} may take, for runtime guards.
+ *
+ * A cross-language contract, exactly like the state vocabulary below it: this
+ * string is sent to `GET /automation/health` as `component`, and the route
+ * refuses any value outside the closed set Python declares in
+ * `src/python/llms/process_heartbeats.py`. A component added on one side alone
+ * is a 422 on every probe, so the two declarations are pinned together by
+ * `tests/pytest/mcp_server/test_plane_liveness_vocabulary_pin.py`.
+ */
+export const PLANE_HEARTBEAT_COMPONENTS = [
+    "reconciler",
+    "executor",
+];
+/** Every value {@link PlaneHeartbeatHealthState} may take, for runtime guards. */
+export const PLANE_HEARTBEAT_HEALTH_STATES = [
+    "fresh",
+    "stale",
+    "never_seen",
+    "unknown",
+];

package/build/pr-base-contract.js

@@ -17,6 +17,26 @@
  * for the worker. Consumed by the worker as `gh pr create --base "$BAPI_BASE_BRANCH"`.
  */
 export const PR_BASE_BRANCH_ENV_VAR = "BAPI_BASE_BRANCH";
+/**
+ * The environment variable carrying THIS JOB's own branch (BAPI-1020).
+ *
+ * Read by the deterministic PreToolUse worker guard
+ * (`executor/worker-guard-hook.ts`), which cannot otherwise answer the two
+ * questions a deny glob is incapable of expressing: "is this `git push`
+ * destination the worker's own branch?" and "is this `git reset --hard` ref the
+ * worker's own ref?". A glob sees a string; the guard needs the identity.
+ *
+ * Declared HERE, beside {@link PR_BASE_BRANCH_ENV_VAR}, rather than as a bare
+ * string literal at the injection site, so the producing and consuming sides
+ * cannot drift apart on the spelling.
+ *
+ * It is set from the EXPLICIT job value only and is on `EXPLICIT_DENY_KEYS` in
+ * `executor/env.ts`, which matters more here than for the base branch: an ambient
+ * `BAPI_WORKER_BRANCH` exported in the operator's shell would otherwise reach a
+ * worker and REDEFINE which branch the guard considers safe to push to — turning
+ * the guard's own input into an attack surface.
+ */
+export const WORKER_BRANCH_ENV_VAR = "BAPI_WORKER_BRANCH";
 /**
  * A SINGLE-LINE, secret-free worker launch instruction telling the worker to
  * open its PR against the injected run base. Kept free of newlines, `;`, single

package/build/readiness-check.js

@@ -0,0 +1,412 @@
+/**
+ * The canonical shared readiness-check contract (BAPI-1055, AC-6).
+ *
+ * Conductor prerequisite probing is spread across five loci — `bridge doctor`
+ * ({@link file:./install-doctor.ts}), `conductor doctor`
+ * ({@link file:./conductor/doctor.ts}), `plane` preflight
+ * ({@link file:./plane/preflight.ts}), the server `conductor-readiness`
+ * collector, and the unified install doctor
+ * ({@link file:./conductor/install-doctor.ts}) that already composes four of
+ * them. Each speaks its own status vocabulary. This module is the ONE record
+ * shape they are all projected into, so a consolidated report can say
+ * pass/fail and name exactly one remediation per failure without any locus
+ * having to abandon its own verdicts.
+ *
+ * DEPENDENCY-NEUTRAL LEAF. It imports nothing: no fs, no network, no CLI, no
+ * sibling diagnostic. That is what makes it safe to import from every surface,
+ * including ones pinned to issue zero probes.
+ *
+ * ## Exhaustive source-status mapping (the accepted four-state vocabulary)
+ *
+ * The shared vocabulary has FOUR states, not three, because four is the
+ * minimum that lets every source verdict round-trip without a lossy merge.
+ * Collapsing `degraded` onto `fail` would make a fallback npm channel read
+ * identically to an unusable ledger, which would contradict the rule that each
+ * section's own advisory semantics stay unchanged.
+ *
+ * | Source                              | Source verdict                | Canonical |
+ * | ----------------------------------- | ----------------------------- | --------- |
+ * | `install-doctor` `InstallCheckStatus`  | `PASS`                        | `pass`    |
+ * | `install-doctor` `InstallCheckStatus`  | `WARN`                        | `warn`    |
+ * | `install-doctor` `InstallCheckStatus`  | `SKIP`                        | `skip`    |
+ * | `install-doctor` `InstallCheckStatus`  | `INFO`                        | see below |
+ * | `conductor/install-doctor` section  | `ok`                          | `pass`    |
+ * | `conductor/install-doctor` section  | `degraded`                    | `warn`    |
+ * | `conductor/install-doctor` section  | `fatal`                       | `fail`    |
+ * | `conductor/doctor` inspection       | `degraded: true`              | `warn`    |
+ * | `plane` diagnostic                  | `severity: "warning"`         | `warn`    |
+ * | `plane` diagnostic                  | `severity: "blocking"`         | `fail`    |
+ * | server readiness                    | unreadable / `null` / missing | `fail`    |
+ *
+ * `INFO` never becomes a canonical status. It is informational by definition,
+ * so its content is preserved in {@link ReadinessCheck.detail} while the check
+ * takes `pass`, `warn`, or `skip` according to that check's own established
+ * semantics — chosen per check id by the adapter, never guessed here.
+ *
+ * Three states are deliberately NOT interchangeable:
+ *
+ * - `fail` means a prerequisite is not satisfied, INCLUDING the case where its
+ *   state could not be established. An unreadable liveness read, a failed
+ *   permission probe, `executor.ready === null`, and a field a newer server
+ *   would have sent are all `fail` with a remediation for restoring the probe.
+ *   Uncertainty must never appear healthy.
+ * - `warn` means the prerequisite is degraded but usable, or a launch-permitting
+ *   plane warning. It is not a soft failure and is never derived from silence.
+ * - `skip` means the check genuinely did not apply or a dependency prevented it
+ *   from running. It is never used to hide an unknown.
+ *
+ * ## The failure/remediation invariant
+ *
+ * AC-6 requires exactly ONE named remediation on every failure, so the union
+ * below makes that a property of the type: the `fail` variant REQUIRES one
+ * non-empty scalar remediation and the `pass` variant PROHIBITS one. `warn` and
+ * `skip` may each carry at most one, because an actionable warning and the
+ * actionable deny-probe skip both have a named next step, while a
+ * dependency-driven skip has none.
+ *
+ * ## Secret discipline
+ *
+ * Every `detail` and `remediation` is fixed prose plus non-secret facts: a
+ * label, a closed enum, a count, a boolean, a timestamp, a relative identifier,
+ * or an approved base/setup URL. The helpers here cap length, strip control
+ * characters, and refuse obvious absolute paths — but they are a last line of
+ * defence, NOT permission to pass a raw exception, subprocess output, a request
+ * header, a response body, or a credential into the constructor. Projecting
+ * source data into safe prose is the adapter's job; this module only refuses
+ * the most obvious leaks.
+ */
+/** Every valid status, for exhaustive validation and test enumeration. */
+export const READINESS_CHECK_STATUSES = [
+    "pass",
+    "warn",
+    "fail",
+    "skip",
+];
+/** Every valid source, for exhaustive validation and test enumeration. */
+export const READINESS_CHECK_SOURCES = [
+    "install",
+    "conductor",
+    "plane",
+    "server",
+];
+/** Raised by {@link createReadinessCheck} for input that cannot be projected. */
+export class ReadinessCheckValidationError extends Error {
+    constructor(reason) {
+        // The reason names the RULE that was broken, never the offending value: the
+        // value is exactly the untrusted material this module exists to keep out of
+        // output, and an error message is an output.
+        super(`invalid readiness check: ${reason}`);
+        this.name = "ReadinessCheckValidationError";
+    }
+}
+/** Length cap for a projected detail line. */
+export const READINESS_DETAIL_MAX_LENGTH = 400;
+/** Length cap for a projected remediation. */
+export const READINESS_REMEDIATION_MAX_LENGTH = 400;
+/**
+ * Stable id grammar: `<source>.<segment>[.<segment>...]`.
+ *
+ * Lowercase, digits, and hyphens only. Whitespace, uppercase, quotes, slashes,
+ * and colons are all rejected, which is what makes an interpolated value — a
+ * path, a repo name, an error string — structurally unable to become an id.
+ */
+const ID_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+const READINESS_ID_PATTERN = new RegExp(`^${ID_SEGMENT}(?:\\.${ID_SEGMENT})+$`);
+/**
+ * Filesystem roots an absolute POSIX path leak actually starts with.
+ *
+ * An allowlist of DANGER rather than a general "starts with a slash" rule,
+ * because the strings this contract legitimately carries are full of leading
+ * slashes that are not paths at all: the slash commands remediations name
+ * (`/install-bridge`), and the endpoint identifiers details name (`/jira/ping`).
+ * Rejecting those would push adapters toward vaguer prose without removing any
+ * real leak — the leak is always a home, temp, or system root.
+ */
+const POSIX_PATH_ROOTS = [
+    "Users",
+    "home",
+    "root",
+    "var",
+    "tmp",
+    "private",
+    "opt",
+    "usr",
+    "etc",
+    "srv",
+    "mnt",
+    "media",
+    "Applications",
+    "Library",
+    "System",
+    "Volumes",
+    "node_modules",
+];
+/**
+ * Absolute POSIX and Windows paths, and `file://` URLs.
+ *
+ * Deliberately narrow: it catches the obvious leak (`/Users/...`, `/private/tmp/...`,
+ * `C:\\...`) without rejecting the relative, repository-conventional paths
+ * remediations legitimately name (`.github/workflows/claude-review.yml`,
+ * `docs/claude/epic-conductor-v2-operator-runbook.md`) or the approved setup
+ * URLs (`https://host/setup`) — note the Windows drive alternative requires a
+ * word boundary before the letter, so the `s:/` inside `https://` is not a hit.
+ */
+const ABSOLUTE_PATH_PATTERN = new RegExp("(^|[\\s\"'`(<])(?:" +
+    `\\/(?:${POSIX_PATH_ROOTS.join("|")})\\/` +
+    "|[A-Za-z]:[\\\\/]" +
+    "|file:\\/\\/)");
+/** True when `value` looks like it embeds an absolute filesystem path. */
+export function containsAbsolutePath(value) {
+    return ABSOLUTE_PATH_PATTERN.test(value);
+}
+/**
+ * Request headers and serialized response bodies.
+ *
+ * Both have recognizable shapes, which is what makes them worth refusing here:
+ * unlike a credential value — a random-looking string no validator can tell
+ * from a repository name — an `Authorization:` header or a JSON object body
+ * announces itself. Neither belongs in a report field under any circumstances,
+ * so this is a structural refusal rather than a judgement call.
+ *
+ * The credential value itself is NOT covered, and cannot be: nothing in this
+ * module ever holds one. That guarantee lives at the collectors that do, which
+ * is why they author prose instead of copying resolver output.
+ */
+const TRANSPORT_ARTIFACT_PATTERN = /(^|[\s"'`(<])(?:authorization\s*:|x-api-key\s*:|bearer\s+\S|\{\s*"[A-Za-z_$][\w$]*"\s*:)/i;
+/** True when `value` looks like a request header or a serialized response body. */
+export function containsTransportArtifact(value) {
+    return TRANSPORT_ARTIFACT_PATTERN.test(value);
+}
+/**
+ * Normalize already-projected prose for a bounded, secret-free field.
+ *
+ * Strips control characters (including the newlines that would let one field
+ * forge another report line), collapses runs of whitespace, trims, and caps the
+ * length. Throws when the result is empty or still looks like an absolute path.
+ */
+function normalizeProse(value, field, maxLength) {
+    if (typeof value !== "string") {
+        // Arrays are called out by name because "one remediation" is the invariant
+        // an array silently violates: a caller handing over two fixes is not a
+        // formatting problem, it is a contract violation.
+        throw new ReadinessCheckValidationError(Array.isArray(value) ? `${field} must be a single string, not an array` : `${field} must be a string`);
+    }
+    // eslint-disable-next-line no-control-regex -- stripping control characters is the point
+    const stripped = value.replace(/[\u0000-\u001f\u007f]+/g, " ");
+    const collapsed = stripped.replace(/\s{2,}/g, " ").trim();
+    if (collapsed.length === 0) {
+        throw new ReadinessCheckValidationError(`${field} must not be blank`);
+    }
+    if (containsAbsolutePath(collapsed)) {
+        throw new ReadinessCheckValidationError(`${field} must not contain an absolute path`);
+    }
+    if (containsTransportArtifact(collapsed)) {
+        throw new ReadinessCheckValidationError(`${field} must not contain a request header or a response body`);
+    }
+    return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 1).trimEnd()}…` : collapsed;
+}
+/** Normalize a detail line. Exported so adapters project through one helper. */
+export function normalizeReadinessDetail(value) {
+    return normalizeProse(value, "detail", READINESS_DETAIL_MAX_LENGTH);
+}
+/** Normalize a remediation. Exported so adapters project through one helper. */
+export function normalizeReadinessRemediation(value) {
+    return normalizeProse(value, "remediation", READINESS_REMEDIATION_MAX_LENGTH);
+}
+/**
+ * Build one validated {@link ReadinessCheck}.
+ *
+ * The ONLY sanctioned way to construct a canonical check. It enforces the
+ * failure/remediation invariant, the id namespace, the closed vocabularies, and
+ * the bounded secret-free field rules — so a report cannot acquire a failure
+ * with no fix, a fix attached to a pass, or an id derived from untrusted input.
+ *
+ * Throws {@link ReadinessCheckValidationError}; callers assembling a report from
+ * external material should route through {@link validateReadinessChecks}, which
+ * converts a throw into a stable failed check rather than losing the locus.
+ */
+export function createReadinessCheck(input) {
+    if (input === null || typeof input !== "object") {
+        throw new ReadinessCheckValidationError("check must be an object");
+    }
+    if (!READINESS_CHECK_SOURCES.includes(input.source)) {
+        throw new ReadinessCheckValidationError("source is not a supported readiness source");
+    }
+    if (!READINESS_CHECK_STATUSES.includes(input.status)) {
+        throw new ReadinessCheckValidationError("status is not a supported readiness status");
+    }
+    if (typeof input.id !== "string" || !READINESS_ID_PATTERN.test(input.id)) {
+        throw new ReadinessCheckValidationError("id is not a stable dotted lowercase identifier");
+    }
+    if (!input.id.startsWith(`${input.source}.`)) {
+        throw new ReadinessCheckValidationError("id namespace does not match its source");
+    }
+    const label = normalizeProse(input.label, "label", READINESS_DETAIL_MAX_LENGTH);
+    const detail = input.detail === undefined ? undefined : normalizeReadinessDetail(input.detail);
+    if (input.status === "pass") {
+        if (input.remediation !== undefined) {
+            // A pass with a fix attached is how a report starts telling operators to
+            // act on things that are already fine, which is how they learn to ignore it.
+            throw new ReadinessCheckValidationError("a passing check must not carry a remediation");
+        }
+        return { id: input.id, source: input.source, label, status: "pass", ...(detail ? { detail } : {}) };
+    }
+    if (input.status === "fail") {
+        if (input.remediation === undefined) {
+            throw new ReadinessCheckValidationError("a failing check must carry exactly one remediation");
+        }
+        return {
+            id: input.id,
+            source: input.source,
+            label,
+            status: "fail",
+            ...(detail ? { detail } : {}),
+            remediation: normalizeReadinessRemediation(input.remediation),
+        };
+    }
+    const remediation = input.remediation === undefined ? undefined : normalizeReadinessRemediation(input.remediation);
+    return {
+        id: input.id,
+        source: input.source,
+        label,
+        status: input.status,
+        ...(detail ? { detail } : {}),
+        ...(remediation ? { remediation } : {}),
+    };
+}
+/** Fixed prose for a check that had to be replaced because it was malformed. */
+export const READINESS_MALFORMED_CHECK_DETAIL = "this prerequisite reported a result that failed the readiness contract, so its real state is unknown";
+/** Fixed remediation for a replaced malformed check. */
+export const READINESS_MALFORMED_CHECK_REMEDIATION = "re-run `conductor readiness`; if it persists, run `conductor doctor` and `install conductor` to re-collect this locus.";
+/** Fixed label for a replaced malformed check. */
+export const READINESS_MALFORMED_CHECK_LABEL = "Unreadable prerequisite";
+/**
+ * Validate a whole array of checks, replacing every malformed entry with a
+ * stable, source-scoped failure rather than dropping it.
+ *
+ * Dropping is the dangerous direction: a locus that vanished reads as "nothing
+ * to report", while a failed check with fixed prose reads as "this could not be
+ * established" — which is the truth. The replacement satisfies the
+ * one-remediation invariant like any other failure.
+ *
+ * `fallbackSource` is used when the malformed entry does not even carry a usable
+ * source, so the substitute still lands in a namespace a reader can act on.
+ */
+export function validateReadinessChecks(checks, fallbackSource = "conductor") {
+    const validated = [];
+    let malformedIndex = 0;
+    for (const candidate of checks) {
+        try {
+            validated.push(createReadinessCheck(candidate));
+        }
+        catch {
+            const raw = (candidate ?? {});
+            const source = READINESS_CHECK_SOURCES.includes(raw.source)
+                ? raw.source
+                : fallbackSource;
+            // The malformed entry's OWN id is never reused: it is the untrusted value
+            // that failed validation, so the substitute gets a generated stable id in
+            // the right namespace instead.
+            malformedIndex += 1;
+            validated.push(createReadinessCheck({
+                id: `${source}.unreadable-check-${malformedIndex}`,
+                source,
+                label: READINESS_MALFORMED_CHECK_LABEL,
+                status: "fail",
+                detail: READINESS_MALFORMED_CHECK_DETAIL,
+                remediation: READINESS_MALFORMED_CHECK_REMEDIATION,
+            }));
+        }
+    }
+    return validated;
+}
+/** Count checks by canonical status. Pure; used by report summaries and tests. */
+export function summarizeReadinessChecks(checks) {
+    const counts = { pass: 0, warn: 0, fail: 0, skip: 0 };
+    for (const check of checks)
+        counts[check.status] += 1;
+    return counts;
+}
+/** Fixed stand-in for a source detail that failed the secret-safety contract. */
+export const READINESS_UNSAFE_DETAIL_REPLACEMENT = "detail withheld — the source reported it in a form this report may not carry";
+/** Fixed stand-in for a source remediation that failed the secret-safety contract. */
+export const READINESS_UNSAFE_REMEDIATION_REPLACEMENT = "re-run `conductor readiness`; this prerequisite's own fix text could not be carried into this report safely.";
+/**
+ * Build a check, degrading REJECTED prose rather than losing the finding — and
+ * never throwing.
+ *
+ * Legacy sections and diagnostics author their prose for a terminal, and some of
+ * them legitimately name an absolute path there — the executor service-unit
+ * collector reports the LaunchAgents directory it searched, for instance. That
+ * is fine in the report it was written for and NOT fine in this one, which is a
+ * wider surface.
+ *
+ * The two obvious responses are both wrong. Passing it through would put a home
+ * directory into the consolidated report; dropping the whole check on a
+ * validation failure would silently remove a real prerequisite because its prose
+ * was unsafe. So the offending FIELD is replaced and the id, label, and status —
+ * the parts an operator acts on — survive.
+ *
+ * The ladder degrades one field at a time, least-destructive first, so a check
+ * loses no more of itself than the failure requires. The last rung is a stable
+ * failure in the same namespace: this function is called from inside
+ * {@link file:./conductor/readiness.ts}'s checks-array literal, which is built
+ * BEFORE {@link validateReadinessChecks} runs, so a throw here would escape the
+ * aggregator's "never throws" contract rather than being absorbed by it. An
+ * earlier revision of this function replaced only `detail` and justified the gap
+ * by pointing at that later validation pass — which does not run early enough to
+ * catch it.
+ */
+export function createReadinessCheckSafely(input) {
+    // A pass may not carry a remediation at all, so for a pass the field is
+    // DROPPED rather than replaced — substituting prose there would invent an
+    // action for a prerequisite that is already satisfied.
+    const safeRemediation = () => input?.status === "pass"
+        ? { remediation: undefined }
+        : { remediation: READINESS_UNSAFE_REMEDIATION_REPLACEMENT };
+    // 1. As authored.
+    try {
+        return createReadinessCheck(input);
+    }
+    catch {
+        /* fall through */
+    }
+    // 2. The detail alone — the field untrusted source prose usually arrives in.
+    try {
+        return createReadinessCheck({ ...input, detail: READINESS_UNSAFE_DETAIL_REPLACEMENT });
+    }
+    catch {
+        /* fall through */
+    }
+    // 3. The remediation alone, keeping a detail that was never the problem.
+    try {
+        return createReadinessCheck({ ...input, ...safeRemediation() });
+    }
+    catch {
+        /* fall through */
+    }
+    // 4. Both.
+    try {
+        return createReadinessCheck({
+            ...input,
+            detail: READINESS_UNSAFE_DETAIL_REPLACEMENT,
+            ...safeRemediation(),
+        });
+    }
+    catch {
+        /* fall through */
+    }
+    // 5. Structurally invalid — a bad id, source, or status, which is a caller bug
+    //    rather than untrusted prose. Reported as an unreadable prerequisite in the
+    //    caller's namespace when it named a usable one, exactly as
+    //    `validateReadinessChecks` would have. Never a throw, and never a pass.
+    const source = READINESS_CHECK_SOURCES.includes(input?.source) ? input.source : "conductor";
+    return createReadinessCheck({
+        id: `${source}.unreadable-check`,
+        source,
+        label: READINESS_MALFORMED_CHECK_LABEL,
+        status: "fail",
+        detail: READINESS_MALFORMED_CHECK_DETAIL,
+        remediation: READINESS_MALFORMED_CHECK_REMEDIATION,
+    });
+}