Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
78.7 KB
Raw Blame
/**
 * Fail-fast doctor readiness probes (t_cc234ff5).
 *
 * The base `doctor()` in `doctor.ts` checks static invariants (vault
 * writeability, manifest shapes). These probes go one step further and
 * check that the moving parts an operator depends on are actually wired:
 * the model-inference credential resolves, the embedding provider loads
 * and reports a model and dimension, the runtime-adapter registry can
 * build the canonical MCP payload, and the runtimes recorded as installed
 * still verify against what is on disk.
 *
 * They are opt-in (the `--readiness` CLI flag) so plain `doctor` output
 * stays byte-identical. Each probe reports exactly one member of
 * {@link READINESS_STATUS} so an unconfigured surface is never mistaken
 * for a passing one. Every probe runs under a per-check timeout: a probe
 * that would hang becomes an `unknown` with a "timed out" reason instead
 * of blocking the operator.
 *
 * That reason used to be a `fail`, and the correction is unit U12 of
 * nothing-runs-unwatched. A probe whose budget elapsed has not found the
 * surface broken; it has found out nothing at all, which is what `unknown`
 * says and what `fail` cannot. The consequence was measurable rather than
 * theoretical: on a loaded machine `o2b doctor --readiness` exited 1 -
 * "this installation is broken" - for the same system that exited 0 when
 * the box was idle, so the verdict was a property of the load average.
 * `search/provider-probe.ts` had already drawn the line one release
 * earlier for the embedding provider: only a surface that ANSWERED with a
 * refusal is a fault, and a budget that elapsed is one of the ways of
 * saying "I could not find out". The same rule now holds here, and an
 * exception escaping a probe body is classified the same way for the same
 * reason - it is evidence about the probe, not about the surface.
 *
 * That timeout covers a probe that AWAITS. It cannot cover one that blocks
 * the event loop, because the timer that would fire is queued behind the
 * work it is meant to interrupt. {@link probeInstalledRuntimes} is the one
 * probe that can: an adapter's `verify` is synchronous, and one of them
 * shells out with a synchronous spawn. The limit is stated here rather than
 * left for an operator to discover, and it is stated rather than papered
 * over with an `await` that would move the call off the stack without
 * making it interruptible.
 *
 * The `unknown` member arrived with evidence-at-the-boundary (B5), and it
 * arrived because this docblock's own claim was false. `probeRuntimeAdapterWiring`
 * reported `pass` from in-process construction alone - it never touched
 * disk - so a machine with nothing installed read as "N runtime adapter(s)
 * wired". The repair is two probes, not one: that one keeps its name and
 * now says out loud that it read no disk state, and
 * {@link probeInstalledRuntimes} answers the install question by calling
 * each registered adapter's own `verify`. A probe that could not MEASURE -
 * an install manifest that exists but will not parse - had nowhere honest
 * to go among three members and had to pick one of three wrong answers;
 * it now returns `unknown` with the reason, which is never empty.
 *
 * Determinism note: the deterministic Brain core has no in-repo chat-LLM
 * client (write-time model steps are handed back to the host as
 * `needs-llm-step` envelopes). The only model-inference credential the
 * system itself resolves is the embedding provider's API key, so the
 * "LLM key" probe resolves that.
 *
 * The `registered_commands` probe (t_3477c9e8) re-reads what the install
 * manifest recorded and asks one question per registered client config:
 * does the Open Second Brain command it registered still resolve to an
 * executable? It is read-only - a registration that stopped resolving is
 * reported with the `o2b install <target> --apply` recovery line, never
 * rewritten.
 *
 * The `client_versions` probe (t_8e49ec96) slots beside it and reads the
 * SAME manifest: one fail-soft, read-only, async version ask per recorded
 * client, graded pass/unknown/skipped and never `fail`, because a version
 * row never proves a surface broken. Its rows travel on the verdict's
 * optional `rows` member, which no other probe sets.
 *
 * The `writeback_contract` probe (t_7c01bb39) is check-only in the same
 * way: it audits whether the workspace agent-instruction file(s) carry
 * the same-turn atomic-fact memory write gate. The contract itself - the
 * managed-block detection, the clause keywords in the marker write-back
 * guardrail's own vocabulary, and the symlink refusal - lives in
 * `brain/writeback-contract.ts`, whose docblock is the settled marker
 * contract an installed block must satisfy. No repair or installer is
 * built here, so a file without the block is skipped, not failed. Since
 * t_00b617b6 the probe also grades placement shadowing: a host reading a
 * contract-free file while another candidate carries the contract is a
 * proved `fail`, because the operative host never sees the gate.
 */

import { readFileSync } from "node:fs";

import { discoverConfig } from "./config.ts";
import { homedir } from "node:os";
import { resolveDecisionModelConfig } from "./decision-model/config.ts";
import {
  measuredTuning,
  measuredTuningSummary,
  vaultDecisionModelWarnings,
} from "./decision-model/diagnostics.ts";
import { processDirsEnv } from "./platform-dirs.ts";
import {
  resolveSemanticCapability,
  SEMANTIC_CAPABILITY_CODE,
  semanticCapabilityIsBlocked,
  semanticCapabilityLabel,
} from "./search/capability-tier.ts";
import { providerProducesVectors } from "./search/embeddings/contract.ts";
import { makeProvider } from "./search/embeddings/provider.ts";
import { resolveSearchConfig } from "./search/index.ts";
import { providerConsentIsDeclined, resolveProviderConsent } from "./search/provider-consent.ts";
import { envKeyList, loadProviderRegistry } from "./search/embeddings/registry.ts";
import { loadRerankRegistry } from "./search/rerank/registry.ts";
import {
  COMMAND_PROBE_VERDICT,
  CommandProbeError,
  probeCommandResolvability,
  type CommandProbeContext,
  type CommandProbeOutcome,
} from "./install/command-probe.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "./install/json-merge.ts";
import { parseJsoncObject } from "./install/jsonc.ts";
import { readManifest } from "./install/manifest.ts";
import { buildPayload } from "./install/payload.ts";
import { defaultRegistry } from "./install/registry.ts";
import { registerAllAdapters } from "./install/adapters/all.ts";
import { looksLikeServerEntry } from "./install/adapters/opencode.ts";
import {
  AGENT_INSTRUCTION_FILES,
  WRITEBACK_CONTRACT_FINDING,
  WRITEBACK_CONTRACT_RECOVERY,
  auditWorkspaceWritebackContract,
  resolveShadowedInstructionContracts,
  type WritebackContractFinding,
  type WritebackContractShadow,
} from "./brain/writeback-contract.ts";
import type { InstallEnv, ManifestEntry } from "./install/types.ts";

// ----- Constants ------------------------------------------------------------

/** Default per-check timeout budget for a single readiness probe. */
export const DEFAULT_READINESS_TIMEOUT_MS = 5_000;

/** Stable probe identifiers (also the machine keys in JSON output). */
export const READINESS_PROBE = {
  llmKey: "llm_key",
  embeddingProvider: "embedding_provider",
  providerConsent: "provider_consent",
  runtimeAdapterWiring: "runtime_adapter_wiring",
  installedRuntimes: "installed_runtimes",
  registeredCommands: "registered_commands",
  clientVersions: "client_versions",
  writebackContract: "writeback_contract",
  decisionModel: "decision_model",
} as const;

/**
 * Embedding providers that authenticate with an API key. `local` and
 * `disabled` need none, so the key probe reports `skipped` for them.
 */
const PROVIDERS_REQUIRING_API_KEY: ReadonlySet<string> = new Set(["openai-compat", "zeroentropy"]);

/**
 * The environment-variable PREFIXES that name an embedding-provider or
 * rerank setting.
 *
 * A prefix rather than a hand-written list, because a list would be a
 * second copy of the resolver's spelling table and would drift: a new
 * `OPEN_SECOND_BRAIN_EMBEDDING_*` key added to the resolver would not
 * appear here, and the probe would then under-report what is present in
 * the environment - which is the one thing this probe exists to say. The
 * rerank resolver spells its settings `OPEN_SECOND_BRAIN_SEARCH_RERANK_*`
 * and is missed by the embedding prefix alone.
 */
const PROVIDER_ENV_PREFIXES: ReadonlyArray<string> = Object.freeze([
  "OPEN_SECOND_BRAIN_EMBEDDING_",
  "OPEN_SECOND_BRAIN_SEARCH_RERANK_",
]);

/**
 * The provider environment variables that do NOT carry a prefix above.
 * The switch is one of them: it is the environment twin of the decline
 * record, and an operator who set it in the environment rather than in
 * the config file is exactly the case this probe has to reach.
 */
const PROVIDER_ENV_NAMES: ReadonlyArray<string> = Object.freeze([
  "OPEN_SECOND_BRAIN_SEARCH_SEMANTIC",
]);

/**
 * The env-var NAMES the operator's own provider registrations and rerank
 * settings point at: every embedding profile's `envKey` in
 * `Brain/search/embedding-providers.json`, every rerank profile's
 * `envKey` in `Brain/search/rerank-providers.json`, and the variable the
 * `search_rerank_env_key` setting names. A registry profile keeps its
 * credential in an operator-named variable (`OPENROUTER_API_KEY`, say),
 * which no prefix above can reach - and the probe that misses it reports
 * exactly the credentials an operator set as absent.
 *
 * Reads are fail-soft: a missing registry contributes nothing, and a
 * config that cannot be read contributes its env spelling only.
 */
function operatorNamedProviderEnvNames(
  opts: ReadinessOptions,
  env: Readonly<Record<string, string | undefined>>,
): ReadonlyArray<string> {
  const names = new Set<string>();
  for (const profile of loadProviderRegistry(opts.vault)) {
    for (const name of envKeyList(profile.envKey)) names.add(name);
  }
  for (const profile of loadRerankRegistry(opts.vault)) names.add(profile.envKey);
  let config: Readonly<Record<string, string>> = {};
  try {
    config = discoverConfig(resolveConfigPath(opts)).data;
  } catch {
    // The consent resolver reports the unreadable record by name; the
    // env census here simply cannot add its config half.
  }
  const rerankEnvKey =
    env["OPEN_SECOND_BRAIN_SEARCH_RERANK_ENV_KEY"] ?? config["search_rerank_env_key"];
  if (typeof rerankEnvKey === "string" && rerankEnvKey.trim() !== "") {
    names.add(rerankEnvKey.trim());
  }
  return Object.freeze([...names]);
}

/**
 * The NAMES of the provider environment variables present in `env`, in
 * alphabetical order. `operatorNamed` extends the membership with the
 * env-var names the operator's own provider and rerank registrations
 * point at.
 *
 * NAMES ONLY, never values: a readiness detail travels into logs, into a
 * JSON payload an operator pastes into a bug report and into the
 * registry's own output, and a value that reached any of those would be
 * a credential published by a diagnostic. The count-and-name form is the
 * same one `probeLlmKey` already uses for a resolved key.
 *
 * An empty value is absent, which is this repository's rule for
 * environment values everywhere else: an operator who exported
 * `OPEN_SECOND_BRAIN_EMBEDDING_KEY=` set nothing.
 */
function presentProviderEnvNames(
  env: Readonly<Record<string, string | undefined>>,
  operatorNamed: ReadonlyArray<string> = [],
): ReadonlyArray<string> {
  const names: string[] = [];
  for (const name of Object.keys(env).toSorted()) {
    const value = env[name];
    if (value === undefined || value === "") continue;
    const isProviderEnv =
      PROVIDER_ENV_NAMES.includes(name) ||
      operatorNamed.includes(name) ||
      PROVIDER_ENV_PREFIXES.some((prefix) => name.startsWith(prefix));
    if (isProviderEnv) names.push(name);
  }
  return Object.freeze(names);
}

// ----- Errors ---------------------------------------------------------------

/** Raised when a probe exceeds its per-check timeout budget. */
export class ReadinessTimeoutError extends Error {
  constructor(label: string, timeoutMs: number) {
    super(`readiness probe '${label}' timed out after ${timeoutMs}ms`);
    this.name = "ReadinessTimeoutError";
  }
}

// ----- Types ----------------------------------------------------------------

/**
 * The four answers a readiness probe can honestly give. None of them is a
 * softer way of saying `pass`: `skipped` is "this surface is not
 * configured, so there is nothing to measure", and `unknown` is "this
 * surface IS configured and the measurement failed", which is a fact
 * about the probe's own reach, never a guess about the surface. Both
 * carry a non-empty detail - see {@link runReadinessProbes}, which
 * enforces it rather than trusting each probe to remember.
 *
 * A budget that elapsed is `unknown`, not a fifth member. `PROVIDER_PROBE`
 * in `search/provider-probe.ts` does spell `timed-out` separately, and the
 * shapes look alike enough to invite copying it - but that vocabulary has
 * no "could not measure" member for it to collapse into, so `timed-out`
 * IS its way of saying that. Here the member already exists, and its
 * meaning - "the probe could not measure; the detail says what stopped
 * it" - is exactly what an elapsed budget reports. A `timed-out` member
 * beside it would be a second spelling of one fact, split by the
 * particular way the measurement was cut short, which every caller would
 * then have to remember to treat identically. The cause is not lost: it is
 * in the detail, which is never empty and which names the budget.
 */
export const READINESS_STATUS = Object.freeze({
  /** The probe ran and the surface answered correctly. */
  pass: "pass",
  /** The probe ran and the surface is broken; the detail names how. */
  fail: "fail",
  /** Nothing to measure: the surface is deliberately not configured. */
  skipped: "skipped",
  /** The probe could not measure; the detail says what stopped it. */
  unknown: "unknown",
} as const);

/** Closed union over {@link READINESS_STATUS}. */
export type ReadinessStatus = (typeof READINESS_STATUS)[keyof typeof READINESS_STATUS];

/** Membership list, in reporting order from best-known to least-known. */
export const READINESS_STATUSES: ReadonlyArray<ReadinessStatus> = Object.freeze([
  READINESS_STATUS.pass,
  READINESS_STATUS.fail,
  READINESS_STATUS.skipped,
  READINESS_STATUS.unknown,
]);

/** Narrow a string read back off disk or across a tool boundary. */
export function isReadinessStatus(value: unknown): value is ReadinessStatus {
  return typeof value === "string" && (READINESS_STATUSES as ReadonlyArray<string>).includes(value);
}

/** The bare outcome a probe body returns, before timing is attached. */
export interface ReadinessVerdict {
  readonly status: ReadinessStatus;
  readonly detail: string;
  /**
   * Per-target machine rows, set ONLY by the `client_versions` probe
   * (t_8e49ec96). Absent on every other probe. Additive and safe: the
   * readiness JSON exists only under `--readiness`, so no byte-identical
   * output contract is stressed, and `readiness_summary` is untouched -
   * a fully-unknown version probe keeps the exit at
   * `DOCTOR_EXIT.probeIncomplete`, never a `fail`.
   */
  readonly rows?: ReadonlyArray<ReadinessVersionRow>;
}

/** One client's answer inside a `client_versions` verdict. */
export interface ReadinessVersionRow {
  /** The install-manifest target the row was asked about. */
  readonly target: string;
  /** pass (answered), unknown (no usable answer), skipped (nothing to ask). */
  readonly status: ReadinessStatus;
  /** The client's own first stdout line when it answered; `null` otherwise. */
  readonly version: string | null;
  /** Why the row graded as it did, never empty. */
  readonly detail: string;
}

/** A completed probe: its verdict plus the name and wall-clock duration. */
export interface ReadinessProbeResult extends ReadinessVerdict {
  readonly name: string;
  readonly durationMs: number;
}

export interface ReadinessReport {
  readonly probes: ReadonlyArray<ReadinessProbeResult>;
  /** Count of probes whose status is `fail`. Drives the non-zero exit code. */
  readonly failed: number;
  /**
   * Count of probes that could not measure - an unreadable install
   * manifest, an elapsed budget, a probe body that threw. Deliberately NOT
   * folded into `failed`: an unmeasured surface is not a broken one, and a
   * caller must never read "0 failed" as "everything was checked". It is
   * not folded into a silent 0 either - the CLI spends a distinct exit
   * code on it (`DOCTOR_EXIT.probeIncomplete` in `cli/main.ts`), because
   * both silences say something this run did not establish.
   */
  readonly unknown: number;
}

export interface ReadinessOptions {
  readonly vault: string;
  readonly config?: string | null;
  readonly cwd?: string;
  readonly home?: string;
  readonly env?: Readonly<Record<string, string | undefined>>;
  /** Per-check timeout budget; defaults to {@link DEFAULT_READINESS_TIMEOUT_MS}. */
  readonly perCheckTimeoutMs?: number;
  /**
   * Ask one client binary its version. Injected only by tests, which
   * cannot install clients; the product spawns `argv` asynchronously
   * (see {@link probeClientVersions} for why async). A throw reads
   * `unknown`, never `fail` - the same contract
   * {@link isWriterLockHeld}-style probes observe.
   */
  readonly clientVersionRunner?: (
    argv: ReadonlyArray<string>,
  ) => Promise<{ readonly exitCode: number; readonly stdout: string }>;
}

// ----- Timeout wrapper ------------------------------------------------------

/**
 * Run `fn` and reject with {@link ReadinessTimeoutError} if it does not
 * settle within `timeoutMs`. The timer is always cleared so a fast
 * resolution never leaves a dangling handle.
 */
export function withReadinessTimeout<T>(
  fn: () => Promise<T>,
  timeoutMs: number,
  label: string,
): Promise<T> {
  return new Promise<T>((resolve, reject) => {
    let settled = false;
    const timer = setTimeout(() => {
      if (settled) return;
      settled = true;
      reject(new ReadinessTimeoutError(label, timeoutMs));
    }, timeoutMs);
    fn().then(
      (value) => {
        if (settled) return;
        settled = true;
        clearTimeout(timer);
        resolve(value);
      },
      (err) => {
        if (settled) return;
        settled = true;
        clearTimeout(timer);
        reject(err as Error);
      },
    );
  });
}

// ----- Probes ---------------------------------------------------------------

function resolveConfigPath(opts: ReadinessOptions): string | undefined {
  if (opts.config) return opts.config;
  try {
    return discoverConfig().path;
  } catch {
    return undefined;
  }
}

/**
 * The model-inference credential resolves. See the module note: this is
 * the embedding provider's API key, the only model credential the
 * deterministic core resolves itself.
 */
export async function probeLlmKey(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  const configPath = resolveConfigPath(opts);
  const { semantic } = resolveSearchConfig({ vault: opts.vault, configPath });
  if (!semantic.enabled || semantic.provider === "disabled") {
    // The arm is SPLIT, because the two situations are not the same
    // fact. A configuration the operator declined is a decision, and it
    // is disclosed by the provider-consent probe beside this one - which
    // names the keys that would re-enable the provider and the provider
    // environment variables that are present. This probe answers the
    // narrower question it was asked (is a model credential required?),
    // and the answer is the same either way, so it says so without
    // repeating the disclosure.
    const consent = resolveProviderConsent({
      configPath,
      env: opts.env ?? process.env,
      semantic,
    });
    if (providerConsentIsDeclined(consent)) {
      return {
        status: READINESS_STATUS.skipped,
        detail: "provider consent declined; no model API key is required",
      };
    }
    return {
      status: READINESS_STATUS.skipped,
      detail: "semantic search disabled; no model API key required",
    };
  }
  if (!PROVIDERS_REQUIRING_API_KEY.has(semantic.provider)) {
    return {
      status: READINESS_STATUS.skipped,
      detail: `provider '${semantic.provider}' needs no API key`,
    };
  }
  const keyCount = semantic.apiKeys?.length ?? (semantic.apiKey ? 1 : 0);
  if (keyCount > 0) {
    return {
      status: READINESS_STATUS.pass,
      detail: `resolved ${keyCount} candidate key(s) for provider '${semantic.provider}'`,
    };
  }
  return {
    status: READINESS_STATUS.fail,
    detail:
      `provider '${semantic.provider}' requires an API key but none resolves ` +
      "from config or env (embedding_api_key / OPEN_SECOND_BRAIN_EMBEDDING_KEY)",
  };
}

/**
 * The provider consent: did the operator write down a decision about the
 * embedding provider, and is it a decline?
 *
 * The probe answers the question the capability tier cannot: the tier
 * says what the configuration can do, and a configuration that says
 * `search_semantic_enabled: false` looks exactly like a configuration
 * that never mentioned semantic search at all. An operator who declined
 * and an operator who never configured anything are two different
 * situations with two different repairs, and this probe is where the
 * first one is named.
 *
 * `skipped`, not `fail`: a decline is a decision, and a decision is not
 * a fault. The detail names the keys the decline was written in, so the
 * operator can see which one is in force, and lists the provider
 * environment variables that are PRESENT - by NAME, on every arm,
 * because a key sitting in the environment beside a recorded decline (or
 * beside no decision at all) is exactly the fact that explains the
 * configuration's behaviour. The names are the point: an operator who set
 * `OPEN_SECOND_BRAIN_EMBEDDING_KEY` in their environment and then wrote a
 * decline in the config file needs to know that the key is still there,
 * and a readiness detail is the wrong place to publish a credential.
 *
 * `unknown`, not `skipped`, when the record could not be read: the
 * resolver fails that arm closed to declined (an unreadable record is
 * not consent), but this probe answers whether a decision EXISTS, and a
 * record nobody could read is a measurement that did not complete. The
 * CLI already carries `unknown` for exactly that, and reporting the
 * fail-closed decline as the operator's choice showed a broken machine
 * configuration as 0 failed / 0 unknown - a clean bill nobody earned.
 */
export async function probeProviderConsent(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  const configPath = resolveConfigPath(opts);
  const env = opts.env ?? process.env;
  const consent = resolveProviderConsent({ configPath, env });
  const present = presentProviderEnvNames(env, operatorNamedProviderEnvNames(opts, env));
  const presentSentence =
    ` Present provider environment variables: ` +
    `${present.length > 0 ? present.join(", ") : "none"}.`;
  if (consent.unreadableReason !== null) {
    return {
      status: READINESS_STATUS.unknown,
      detail: `${consent.detail}${presentSentence}`,
    };
  }
  return {
    status: READINESS_STATUS.skipped,
    detail: `${consent.detail}${presentSentence}`,
  };
}

/**
 * The embedding provider loads and reports a model and a positive
 * dimension. The provider's `ping()` is the authoritative source of the
 * dimension (a cloud provider learns it from the first response), so the
 * probe pings under the per-check timeout rather than trusting config.
 *
 * A configuration the operator has not finished is `skipped`, not
 * `failed`, and WHICH configuration it is comes from the shared
 * capability tier (provenance-at-the-boundary, F1). Two consequences,
 * both deliberate: the sentinel provider is now recognised by the
 * contract predicate rather than by the literal name it happens to
 * carry, and a key-less remote provider is refused HERE instead of
 * making a credential-free outbound request whose only possible outcome
 * is an auth error. `probeLlmKey` above is the probe that reports the
 * missing key as a failure, so nothing is lost by skipping here.
 */
export async function probeEmbeddingProvider(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  const configPath = resolveConfigPath(opts);
  let semantic;
  try {
    semantic = resolveSearchConfig({ vault: opts.vault, configPath }).semantic;
  } catch (err) {
    return {
      status: READINESS_STATUS.fail,
      detail: `config failed to resolve: ${(err as Error).message}`,
    };
  }
  // The consent is read BEFORE the provider is constructed: an operator
  // who deliberately declined is reported as skipped with the decline
  // sentence (the consent probe's wording is the precedent) rather than
  // reporting a failure that contradicts their choice.
  const consent = resolveProviderConsent({
    configPath,
    env: opts.env ?? process.env,
    semantic,
  });
  if (providerConsentIsDeclined(consent)) {
    return {
      status: READINESS_STATUS.skipped,
      detail: consent.detail,
    };
  }
  // The tier is read BEFORE the provider is constructed: a provider whose
  // credential is missing refuses at construction, and reporting that as
  // "failed to load" described the wrong thing entirely.
  const capability = resolveSemanticCapability(semantic);
  if (semanticCapabilityIsBlocked(capability)) {
    return {
      status: READINESS_STATUS.skipped,
      detail: await semanticCapabilityLabel(capability.code),
    };
  }
  let provider;
  try {
    provider = makeProvider(semantic, consent);
  } catch (err) {
    return {
      status: READINESS_STATUS.fail,
      detail: `provider failed to load: ${(err as Error).message}`,
    };
  }
  // A provider that embeds nothing IS the `disabled` capability, whatever
  // the rest of the configuration says, so it names that code rather than
  // the tier's - the two agree for every provider in the tree and this
  // keeps them agreeing for one that is added later.
  if (!providerProducesVectors(provider)) {
    return {
      status: READINESS_STATUS.skipped,
      detail: await semanticCapabilityLabel(SEMANTIC_CAPABILITY_CODE.disabled),
    };
  }
  const pong = await provider.ping();
  if (!pong.ok) {
    return {
      status: READINESS_STATUS.fail,
      detail: `provider '${provider.name}' did not respond: ${pong.reason}`,
    };
  }
  if (provider.model === "" || pong.dimension <= 0) {
    return {
      status: READINESS_STATUS.fail,
      detail: `provider '${provider.name}' responded but reported an empty model or non-positive dimension`,
    };
  }
  return {
    status: READINESS_STATUS.pass,
    detail: `provider '${provider.name}' model '${provider.model}' responded with ${pong.dimension} dims`,
  };
}

/**
 * The optional decision model (issue #213). `skipped` whenever the feature
 * is not active - off, no key, or opted out by the vault - because a
 * missing key is a normal state, not a fault; the detail says how to set
 * it. `fail` only for an enabled config with an invalid value. No request
 * is sent: `o2b decision-model check --ping` is the live probe.
 */
export async function probeDecisionModel(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  const verdict = await decisionModelVerdict(opts);
  const vaultWarnings = vaultDecisionModelWarnings(opts.vault);
  if (vaultWarnings.length === 0) return verdict;
  return { ...verdict, detail: `${verdict.detail}; vault: ${vaultWarnings.join("; ")}` };
}

async function decisionModelVerdict(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  const configPath = resolveConfigPath(opts);
  let data: Readonly<Record<string, string>>;
  try {
    data = discoverConfig(configPath).data;
  } catch (err) {
    return {
      status: READINESS_STATUS.unknown,
      detail: `config could not be read: ${(err as Error).message}`,
    };
  }
  const cfg = resolveDecisionModelConfig({
    config: data,
    vault: opts.vault,
    ...(opts.env !== undefined ? { env: opts.env as NodeJS.ProcessEnv } : {}),
  });
  switch (cfg.status) {
    case "disabled":
      return {
        status: READINESS_STATUS.skipped,
        detail: "off (decision_model_enabled is not true)",
      };
    case "no_key":
      return {
        status: READINESS_STATUS.skipped,
        detail:
          cfg.envKey === null
            ? "enabled but no key variable is named; set decision_model_env_key"
            : `enabled but ${cfg.envKey} is not set; set it in the environment to turn the feature on`,
      };
    case "disabled_by_vault":
      return { status: READINESS_STATUS.skipped, detail: "opted out by this vault's _brain.yaml" };
    case "invalid":
      return { status: READINESS_STATUS.fail, detail: cfg.errors.join("; ") };
    case "active": {
      // The tuning marks live under the state root the OPTIONS env
      // resolves to, not the probe process's ambient one - the same env
      // the config above was resolved from.
      const dirsEnv =
        opts.env === undefined
          ? processDirsEnv()
          : {
              platform: process.platform,
              home: opts.env["HOME"] ?? homedir(),
              env: opts.env as Readonly<Record<string, string | undefined>>,
            };
      const tuning = measuredTuningSummary(measuredTuning(cfg, dirsEnv));
      return {
        status: READINESS_STATUS.pass,
        detail:
          (cfg.keyPresent || cfg.keyRequired !== false
            ? `key present in ${cfg.envKey ?? "?"}, endpoint accepted (${cfg.provider ?? "?"} ${cfg.baseUrl ?? ""})`
            : `no key needed for this loopback server, endpoint accepted (${cfg.provider ?? "?"} ${cfg.baseUrl ?? ""})`) +
          `; tuning: ${tuning}`,
      };
    }
  }
}

/**
 * The `InstallEnv` both install-facing probes hand to the adapters. One
 * builder so the construction probe and the installed-state probe cannot
 * disagree about which HOME, cwd or environment a runtime is judged
 * against - a disagreement there would make the two verdicts describe two
 * different machines.
 */
function installEnvFor(opts: ReadinessOptions): InstallEnv {
  // InstallEnv.env is a defined-only string map; drop any undefined values
  // that a raw `process.env` snapshot may carry.
  const rawEnv = opts.env ?? process.env;
  const cleanEnv: Record<string, string> = {};
  for (const [k, v] of Object.entries(rawEnv)) {
    if (typeof v === "string") cleanEnv[k] = v;
  }
  return {
    vault: opts.vault,
    home: opts.home ?? process.env["HOME"] ?? opts.vault,
    cwd: opts.cwd ?? process.cwd(),
    env: cleanEnv,
    now: new Date(),
  };
}

/**
 * The runtime-adapter registry is populated, every adapter can build a
 * plan, and the canonical MCP payload builds - the wiring every install
 * target depends on.
 *
 * What this probe deliberately does NOT answer: whether any runtime is
 * actually installed. It reads no disk state, calls neither `detect` nor
 * `verify`, and would report `pass` on a machine where nothing has ever
 * been installed - which is exactly what it used to claim with the words
 * "N runtime adapter(s) wired", and exactly why that wording is gone.
 * {@link probeInstalledRuntimes} is the probe that answers the install
 * question, and the detail below names it so an operator reading one
 * verdict knows where the other lives.
 */
export async function probeRuntimeAdapterWiring(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  registerAllAdapters();
  const targets = defaultRegistry.targets();
  if (targets.length === 0) {
    return { status: READINESS_STATUS.fail, detail: "no runtime adapters registered" };
  }
  const env = installEnvFor(opts);
  let payload;
  try {
    payload = buildPayload({ vault: opts.vault, agent_name: null, timezone: null });
  } catch (err) {
    return {
      status: READINESS_STATUS.fail,
      detail: `MCP payload failed to build: ${(err as Error).message}`,
    };
  }
  for (const target of targets) {
    const adapter = defaultRegistry.get(target);
    if (!adapter) {
      return { status: READINESS_STATUS.fail, detail: `registry lost adapter '${target}'` };
    }
    try {
      adapter.plan(payload, env);
    } catch (err) {
      return {
        status: READINESS_STATUS.fail,
        detail: `adapter '${target}' failed to plan: ${(err as Error).message}`,
      };
    }
  }
  return {
    status: READINESS_STATUS.pass,
    detail:
      `${targets.length} runtime adapter(s) construct a plan and the MCP payload builds; ` +
      `no disk state read - '${READINESS_PROBE.installedRuntimes}' answers whether any ` +
      "runtime is installed",
  };
}

/**
 * What is actually installed on this machine, read off disk through each
 * registered adapter's OWN `verify(env)`.
 *
 * Delegating to `verify` rather than re-reading the runtime config files
 * here is the whole point: the adapter already knows where its config
 * lives, what the canonical payload looks like for it, and - for the
 * runtimes that have a CLI to ask (`copilot-cli`, `codex`) - how to
 * consult the runtime itself. Re-implementing any of that in a doctor
 * probe would
 * produce a second, quietly divergent opinion about the same disk.
 *
 * The closed `VerifyStatus` vocabulary maps onto readiness with no
 * default arm, so a fifth verify status fails the typecheck here instead
 * of silently landing in whichever bucket a `default:` happened to name.
 * A `verify` that THROWS - the sidecar install manifest exists but will
 * not parse, or a runtime CLI that cannot be spawned - is `unknown` for
 * that target with the thrown reason. It is emphatically not a skip: a
 * manifest we cannot read is not a machine with nothing installed.
 */
/**
 * NOTE ON THE TIMEOUT: every `verify` here is synchronous, and both
 * `copilot-cli` and `codex` verify by spawning their own CLI
 * synchronously. While that spawn runs, the event loop is blocked and the
 * runner's timeout timer
 * cannot fire, so this probe is the one the module-level timeout promise
 * does not cover. Making it interruptible means an async adapter contract,
 * which is a change to every adapter and belongs in its own unit.
 */
export async function probeInstalledRuntimes(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  registerAllAdapters();
  const adapters = defaultRegistry.list();
  if (adapters.length === 0) {
    return { status: READINESS_STATUS.fail, detail: "no runtime adapters registered" };
  }
  const env = installEnvFor(opts);
  const broken: string[] = [];
  const unmeasured: string[] = [];
  const installed: string[] = [];
  const absent: string[] = [];

  for (const adapter of adapters) {
    let result;
    try {
      result = adapter.verify(env);
    } catch (err) {
      unmeasured.push(`${adapter.target}: ${flattenReason((err as Error).message)}`);
      continue;
    }
    const reason = `${adapter.target}: ${result.details.join("; ")}`;
    switch (result.status) {
      case "ok":
        installed.push(adapter.target);
        break;
      case "drift":
      case "mcp-unreachable":
        broken.push(result.fix_hint === null ? reason : `${reason} - fix: ${result.fix_hint}`);
        break;
      case "not-installed":
        absent.push(adapter.target);
        break;
      default: {
        // Exhaustiveness over the closed `VerifyStatus` set: a fifth
        // member stops compiling here rather than being folded into
        // whichever bucket a permissive default happened to name. Should
        // one ever arrive from a JavaScript caller at runtime, it lands in
        // `unmeasured` - the only bucket that claims nothing.
        const unmapped: never = result.status;
        unmeasured.push(`${adapter.target}: unmapped verify status '${String(unmapped)}'`);
        break;
      }
    }
  }

  // Precedence, worst-known first: a runtime PROVED broken outranks one we
  // could not measure, which outranks a verified install, which outranks a
  // machine where nothing is installed at all. The counts below travel with
  // every verdict so the winning bucket never hides the others.
  const census =
    `(${installed.length} ok, ${broken.length} broken, ` +
    `${unmeasured.length} unmeasured, ${absent.length} not-installed)`;
  if (broken.length > 0) {
    return {
      status: READINESS_STATUS.fail,
      detail: `${broken.length} runtime(s) verified broken ${census}: ${broken.join("; ")}`,
    };
  }
  if (unmeasured.length > 0) {
    return {
      status: READINESS_STATUS.unknown,
      detail: `could not verify ${unmeasured.length} runtime(s) ${census}: ${unmeasured.join("; ")}`,
    };
  }
  if (installed.length > 0) {
    return {
      status: READINESS_STATUS.pass,
      detail: `${installed.length} runtime(s) verified installed ${census}: ${installed.join(", ")}`,
    };
  }
  return {
    status: READINESS_STATUS.skipped,
    detail: `no runtime installed: all ${absent.length} registered target(s) report not-installed`,
  };
}

/** One-line an error message so a multi-line reason stays one probe detail. */
function flattenReason(message: string): string {
  return message.replace(/\s+/g, " ").trim();
}

// ----- Registered-command probe (t_3477c9e8) --------------------------------

/**
 * Top-level JSON objects an Open Second Brain MCP registration may live under: the
 * json-merge default (`mcpServers` - cursor, kiro, gemini-cli and the
 * generic printout), opencode's legacy `mcp`, and opencode V2's native
 * `mcp.servers` - the one dotted key, resolved through nested objects,
 * so a healthy V2 install is probed instead of reported as having no
 * entry.
 */
const JSON_MCP_TOP_LEVEL_KEYS: ReadonlyArray<string> = ["mcpServers", "mcp", "mcp.servers"];

/** The Open Second Brain entry names, as JSON keys and as `[mcp_servers.<name>]` tables. */
const OSB_ENTRY_KEYS: ReadonlySet<string> = new Set([OSB_KEY_FULL, OSB_KEY_WRITER]);

/** Matches exactly the `[mcp_servers.<name>]` table header grok/codex write. */
const TOML_MCP_SERVER_HEADER = /^\[mcp_servers\.([^[\]]+)\]$/;

/**
 * One registered command extracted from a client config: the Open Second Brain entry
 * name plus the `command`/`args` exactly as the config records them.
 */
interface RegisteredCommandEntry {
  readonly key: string;
  readonly command: string;
  readonly args: ReadonlyArray<string>;
}

/**
 * What one recorded config file yielded. `none` and `malformed` are
 * distinct on purpose: a config with no Open Second Brain command entry has nothing to
 * probe (and registration drift is the installed-runtimes probe's
 * finding), while Open Second Brain entries that exist but carry no usable command stop
 * the measurement - which is the `unknown` vocabulary, not a skip.
 */
type CommandExtraction =
  | { readonly kind: "entries"; readonly entries: ReadonlyArray<RegisteredCommandEntry> }
  | { readonly kind: "none" }
  | { readonly kind: "malformed"; readonly reason: string };

/** Worst-first severity order over the readiness statuses. */
const READINESS_SEVERITY: ReadonlyArray<ReadinessStatus> = [
  READINESS_STATUS.fail,
  READINESS_STATUS.unknown,
  READINESS_STATUS.skipped,
  READINESS_STATUS.pass,
];

function readinessRank(status: ReadinessStatus): number {
  return READINESS_SEVERITY.indexOf(status);
}

function countByStatus(statuses: ReadonlyArray<ReadinessStatus>): Record<ReadinessStatus, number> {
  const counts: Record<ReadinessStatus, number> = { pass: 0, fail: 0, unknown: 0, skipped: 0 };
  for (const status of statuses) counts[status] += 1;
  return counts;
}

function statusForProbeOutcome(outcome: CommandProbeOutcome): ReadinessStatus {
  switch (outcome.verdict) {
    case COMMAND_PROBE_VERDICT.resolves:
      return READINESS_STATUS.pass;
    case COMMAND_PROBE_VERDICT.absent:
      return READINESS_STATUS.fail;
    case COMMAND_PROBE_VERDICT.unresolved:
      return READINESS_STATUS.unknown;
  }
}

/**
 * What is registered, and does it still resolve? Reads the install
 * manifest, re-reads every recorded client config, extracts the Open Second Brain
 * `command`/`args` the install wrote (JSON `mcpServers`, opencode's legacy
 * `mcp`, opencode V2's nested `mcp.servers`, or the
 * `[mcp_servers.*]` TOML tables grok and codex write), and probes each
 * command word via `command-probe.ts`.
 *
 * The verdict is worst-of per entry, then worst-of overall
 * (`fail` > `unknown` > `skipped` > `pass`), with the full per-target
 * table in the detail and the counts travelling with the winning bucket -
 * the same shape {@link probeInstalledRuntimes} reports in. Every row is
 * read-only: the only command printed is the recovery line
 * `o2b install <target> --apply`.
 *
 * Grading follows the false-alarm bound the design settles. A
 * proved-absent path-form command is a `fail` carrying the recovery line.
 * A bare name this process's PATH does not carry is `unknown` - the host
 * client spawns with its own PATH, which may still resolve it. A recorded
 * config that is gone, or that cannot be read into a command, is
 * `unknown` (unmeasured, not broken); a config with no Open Second Brain command entry
 * at all is `skipped` by name - nothing-to-probe is a verdict, not
 * silence.
 */
export async function probeRegisteredCommands(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  let manifest;
  try {
    manifest = readManifest(opts.vault);
  } catch (err) {
    return {
      status: READINESS_STATUS.unknown,
      detail:
        "install manifest could not be read, so no registered command could be probed: " +
        flattenReason((err as Error).message),
    };
  }
  const installs = Object.values(manifest.installs);
  if (installs.length === 0) {
    return {
      status: READINESS_STATUS.skipped,
      detail: "install manifest records no installs; nothing to probe",
    };
  }
  const env = installEnvFor(opts);
  const context: CommandProbeContext = { env: env.env, cwd: env.cwd };
  const rows = installs.map((entry) => registeredCommandRow(entry, context));
  const counts = countByStatus(rows.map((row) => row.status));
  // Worst rows lead the detail; toSorted is stable, so within one bucket
  // the manifest's own order stands.
  const ordered = rows.toSorted((a, b) => readinessRank(a.status) - readinessRank(b.status));
  const rowText = ordered.map((row) => `${row.target}: ${row.detail}`).join("; ");
  const census =
    `(${counts.pass} pass, ${counts.fail} fail, ` +
    `${counts.unknown} unknown, ${counts.skipped} skipped)`;
  if (counts.fail > 0) {
    return {
      status: READINESS_STATUS.fail,
      detail: `${counts.fail} registered command(s) proved unresolvable ${census}: ${rowText}`,
    };
  }
  if (counts.unknown > 0) {
    return {
      status: READINESS_STATUS.unknown,
      detail: `could not confirm ${counts.unknown} registered command(s) ${census}: ${rowText}`,
    };
  }
  if (counts.skipped > 0) {
    return {
      status: READINESS_STATUS.skipped,
      detail:
        `nothing to probe for ${counts.skipped} of ${rows.length} registered target(s) ` +
        `${census}: ${rowText}`,
    };
  }
  return {
    status: READINESS_STATUS.pass,
    detail: `${counts.pass} registered command(s) resolve ${census}: ${rowText}`,
  };
}

/** One manifest entry's answer: what was registered and whether it resolves. */
interface RegisteredCommandRow {
  readonly target: string;
  readonly status: ReadinessStatus;
  readonly detail: string;
}

function registeredCommandRow(
  entry: ManifestEntry,
  context: CommandProbeContext,
): RegisteredCommandRow {
  const target = entry.target;
  if (entry.config_path === null) {
    return {
      target,
      status: READINESS_STATUS.skipped,
      detail: "no config_path recorded - nothing to probe",
    };
  }
  const configPath = entry.config_path;
  let raw: string;
  try {
    raw = readFileSync(configPath, "utf8");
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
      return {
        target,
        status: READINESS_STATUS.unknown,
        detail:
          `recorded config ${configPath} does not exist; ` +
          `'o2b install ${target} --check' answers whether the registration is gone`,
      };
    }
    return {
      target,
      status: READINESS_STATUS.unknown,
      detail:
        `recorded config ${configPath} could not be read: ` + flattenReason((err as Error).message),
    };
  }
  const extraction = extractRegisteredCommands(raw);
  switch (extraction.kind) {
    case "none":
      return {
        target,
        status: READINESS_STATUS.skipped,
        detail: `no Open Second Brain command entry found in ${configPath} - nothing to probe`,
      };
    case "malformed":
      return {
        target,
        status: READINESS_STATUS.unknown,
        detail:
          `registered Open Second Brain entry in ${configPath} is not a usable command: ` +
          flattenReason(extraction.reason),
      };
    case "entries":
      return probeRegisteredEntries(target, configPath, extraction.entries, context);
  }
}

function probeRegisteredEntries(
  target: string,
  configPath: string,
  entries: ReadonlyArray<RegisteredCommandEntry>,
  context: CommandProbeContext,
): RegisteredCommandRow {
  const summaries: string[] = [];
  let worst: ReadinessStatus = READINESS_STATUS.pass;
  for (const entry of entries) {
    let outcome: CommandProbeOutcome;
    try {
      outcome = probeCommandResolvability(entry.command, entry.args, context);
    } catch (err) {
      if (err instanceof CommandProbeError) {
        return {
          target,
          status: READINESS_STATUS.unknown,
          detail:
            `registered command in ${configPath} could not be probed: ` +
            flattenReason(err.message),
        };
      }
      throw err;
    }
    const status = statusForProbeOutcome(outcome);
    // The recovery line rides exactly the rows that proved their fault.
    const summary =
      `command '${entry.command}': ${outcome.detail}` +
      (outcome.verdict === COMMAND_PROBE_VERDICT.absent
        ? ` - fix: o2b install ${target} --apply`
        : "");
    if (!summaries.includes(summary)) summaries.push(summary);
    if (readinessRank(status) < readinessRank(worst)) worst = status;
  }
  return { target, status: worst, detail: summaries.join("; ") };
}

// ----- client_versions (t_8e49ec96) -----------------------------------------

/**
 * The version command asked of each install target's client, and the one
 * target with no client binary of its own.
 *
 * A client INSTALLED but never registered through Open Second Brain is out
 * of scope by construction: detection comes from the install manifest,
 * exactly like `registered_commands`, so the probe asks only the clients
 * this tool recorded.
 *
 * Binary names are pinned to each adapter's own spawn precedent
 * (`copilot-cli.ts` spawns `copilot --version`; `codex.ts` resolves `codex`
 * via `Bun.which`; `gemini-cli.ts`'s notes name `gemini`) and to each
 * client's documented CLI. `generic` writes a user-named config and has no
 * client binary of its own, so it is skipped by name rather than probed.
 * A correction to a row is a one-line follow-up in this table's own module.
 */
const CLIENT_VERSION_COMMANDS: Readonly<Record<string, ReadonlyArray<string> | null>> =
  Object.freeze({
    aider: ["aider", "--version"],
    codex: ["codex", "--version"],
    "copilot-cli": ["copilot", "--version"],
    cursor: ["cursor", "--version"],
    "gemini-cli": ["gemini", "--version"],
    grok: ["grok", "--version"],
    kiro: ["kiro", "--version"],
    opencode: ["opencode", "--version"],
    pi: ["pi", "--version"],
    generic: null,
  });

/**
 * Clients format their version freely ("codex-cli 0.9.0", "GitHub Copilot
 * CLI 1.0.5"), so the raw line is the value and nothing is parsed - but a
 * runaway first line must not carry a readiness payload, so it is capped.
 */
const CLIENT_VERSION_MAX_LENGTH = 200;

/**
 * The product runner: an ASYNC spawn, not `spawnSync`.
 *
 * `probeInstalledRuntimes`' docblock records the cost of the synchronous
 * kind: it blocks the event loop, so the timeout timer that is meant to
 * cut a hung probe off cannot fire behind it. This probe's version ask is
 * exactly the kind of subprocess a hung binary would wedge, so it runs on
 * the promise machinery the per-probe budget already covers. Read-only and
 * fail-soft: the child inherits the environment and writes nothing.
 *
 * The ask carries a child-level budget of its own (defaulting to the
 * per-probe budget, {@link DEFAULT_READINESS_TIMEOUT_MS}): the probe-level
 * wrapper can only abandon the promise it awaits, so a hung `--version`
 * child would otherwise survive the cut as an orphan. The child's exit is
 * raced against the timer here, and the child itself is killed when the
 * timer wins - SIGTERM first, then SIGKILL after a short grace
 * ({@link CLIENT_KILL_GRACE_MS}), because a client that traps or ignores
 * TERM would otherwise outlive doctor together with everything it
 * spawned. stderr is ignored, not piped: nothing observes it, and a pipe
 * a chatty child fills unread would block the child on write.
 *
 * stdout is drained INCREMENTALLY, never as one await of EOF: a client
 * whose `--version` forks a background helper that inherits stdout (an
 * update checker, a daemon) prints its version and exits 0 while the
 * helper keeps the pipe open, so an EOF-await would time out an ask that
 * was actually answered. The drain settles at the first newline - the
 * only thing the grader reads - or at EOF, or, once the child has
 * exited, at a short bounded window ({@link STDOUT_DRAIN_WINDOW_MS})
 * over whatever stdout has already buffered.
 */
export async function spawnClientVersion(
  argv: ReadonlyArray<string>,
  timeoutMs: number = DEFAULT_READINESS_TIMEOUT_MS,
): Promise<{ exitCode: number; stdout: string }> {
  const child = Bun.spawn({ cmd: [...argv], stdout: "pipe", stderr: "ignore" });
  let exited = false;
  void child.exited.then(() => {
    exited = true;
  });
  let timer: ReturnType<typeof setTimeout> | undefined;
  const budget = new Promise<never>((_, reject) => {
    timer = setTimeout(() => {
      try {
        child.kill();
      } catch {
        /* already gone */
      }
      // SIGTERM can be trapped or ignored, and the escalation must
      // outlive this function - the budget rejects now, the grace timer
      // keeps its appointment regardless. A child that answered in
      // between is already reaped and is left alone.
      setTimeout(() => {
        if (!exited) {
          try {
            child.kill("SIGKILL");
          } catch {
            /* already gone */
          }
        }
      }, CLIENT_KILL_GRACE_MS);
      reject(new ReadinessTimeoutError(`client version ${argv[0]}`, timeoutMs));
    }, timeoutMs);
  });
  try {
    return await Promise.race([
      (async () => {
        // The drain starts immediately so a child writing past the pipe
        // buffer is consumed rather than wedged on write, but the ask
        // settles on the child's EXIT, not on the pipe closing.
        const drained = drainVersionStdout(child.stdout, child.exited);
        const exitCode = await child.exited;
        const stdout = await drained;
        return { exitCode, stdout };
      })(),
      budget,
    ]);
  } finally {
    clearTimeout(timer);
  }
}

/**
 * How long the drain keeps reading past the child's exit before
 * returning what stdout has buffered: a helper holding the pipe can keep
 * EOF from ever arriving, and the buffered bytes are already there - the
 * window is the bound that turns them into an answer instead of a
 * timeout. Long enough to be a rounding error on a real spawn, short
 * enough to never matter against the ask's budget.
 */
const STDOUT_DRAIN_WINDOW_MS = 250;

/** The gap between the budget's SIGTERM and its SIGKILL follow-up. */
const CLIENT_KILL_GRACE_MS = 250;

/**
 * Read the child's stdout incrementally, settling at the first newline
 * (the version is graded from the raw first line and nothing beyond it),
 * at EOF, or - once `exited` resolves - at the bounded window, returning
 * whatever has buffered by then. A read that rejects (the stream erroring
 * while a helper still holds the pipe) returns what buffered too, never
 * rejects the ask.
 */
async function drainVersionStdout(
  stream: ReadableStream<Uint8Array>,
  exited: Promise<unknown>,
): Promise<string> {
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  let text = "";
  // Armed once per ask: the window opens when the child exits, not when
  // the drain starts, so a child that answers late is not penalized.
  const windowCloses: Promise<null> = exited
    .then(
      () => Bun.sleep(STDOUT_DRAIN_WINDOW_MS),
      () => Bun.sleep(STDOUT_DRAIN_WINDOW_MS),
    )
    .then(() => null);
  for (;;) {
    const read = reader.read().then(
      (chunk) => ({ chunk }),
      () => null,
    );
    const settled = await Promise.race([read, windowCloses]);
    if (settled === null) return text;
    if (settled.chunk.done || settled.chunk.value === undefined) return text;
    text += decoder.decode(settled.chunk.value, { stream: true });
    if (text.includes("\n")) return text;
  }
}

/**
 * The ask's own budget, derived from the probe's: the normal ask keeps a
 * fifth of the probe budget in reserve (the 80% share), floored at 50 ms
 * so a real spawn never answers against nothing. The floor is capped at
 * the probe budget minus a margin, less whatever the probe already
 * spent, so the ask's timer expires strictly BEFORE the probe-level
 * wrapper's - which was armed first and expires at a fixed point - even
 * though each ask's timer is armed later, one spawn at a time. The
 * wrapper can then only ever fire on a child that ignored its own
 * (earlier) budget, and the verdict that carries the rows wins the race.
 * Under the floor the ask dies the margin before the wrapper, so the
 * verdict still carries its rows, each naming its own timeout; a
 * degenerate budget clamps at zero instead of going negative, and the
 * row says timed out after 0ms - a measurement that had no budget, never
 * a negative one.
 */
export function clientAskBudgetMs(probeBudgetMs: number, elapsedMs: number = 0): number {
  return Math.max(
    0,
    Math.min(
      probeBudgetMs - CLIENT_ASK_MARGIN_MS - Math.max(0, elapsedMs),
      Math.max(50, Math.floor(probeBudgetMs * 0.8)),
    ),
  );
}

/** First stdout line, trimmed and length-capped - the raw line, never parsed. */
function firstVersionLine(stdout: string): string | null {
  const line = stdout.split("\n")[0]?.trim() ?? "";
  if (line === "") return null;
  return line.length > CLIENT_VERSION_MAX_LENGTH ? line.slice(0, CLIENT_VERSION_MAX_LENGTH) : line;
}

/**
 * One manifest target's version answer, graded pass/unknown/skipped and
 * never `fail`: "the client answered with a version" is the only measured
 * fact here, and no version row proves a surface broken - resolvability
 * itself is `registered_commands`' finding, and a client this doctor's
 * PATH cannot see may still resolve for the host that spawns it. An
 * unanswered row therefore points at that probe's finding rather than
 * raising this one's own alarm.
 */
async function clientVersionRow(
  target: string,
  runner: (argv: ReadonlyArray<string>) => Promise<{ exitCode: number; stdout: string }>,
): Promise<ReadinessVersionRow> {
  const argv = CLIENT_VERSION_COMMANDS[target];
  if (argv === undefined) {
    // Loud, never silent: a manifest target the table does not know is a
    // table that lags the adapter registry, and the row names the fix.
    return {
      target,
      status: READINESS_STATUS.unknown,
      version: null,
      detail: `no version command is known for target '${target}' - extend CLIENT_VERSION_COMMANDS`,
    };
  }
  if (argv === null) {
    return {
      target,
      status: READINESS_STATUS.skipped,
      version: null,
      detail: "no client binary of its own (it writes a user-named config) - nothing to ask",
    };
  }
  let answered: { exitCode: number; stdout: string };
  try {
    answered = await runner(argv);
  } catch (err) {
    const code = (err as NodeJS.ErrnoException)?.code;
    const pointer = "resolvability is 'registered_commands' finding, so this row is not a fail";
    return {
      target,
      status: READINESS_STATUS.unknown,
      version: null,
      detail:
        code === "ENOENT"
          ? `${argv[0]} is not on the doctor's PATH (ENOENT; the host may still resolve it); ${pointer}`
          : `the version ask failed (${code ?? "unknown error"}): ${flattenReason((err as Error).message)}; ${pointer}`,
    };
  }
  if (answered.exitCode !== 0) {
    return {
      target,
      status: READINESS_STATUS.unknown,
      version: null,
      detail: `${argv[0]} exited ${answered.exitCode} with no version; ${argv.join(" ")} did not answer`,
    };
  }
  const version = firstVersionLine(answered.stdout);
  if (version === null) {
    return {
      target,
      status: READINESS_STATUS.unknown,
      version: null,
      detail: `${argv[0]} answered with no version output; ${argv.join(" ")} exited 0 but printed nothing`,
    };
  }
  return {
    target,
    status: READINESS_STATUS.pass,
    version,
    detail: `${argv.join(" ")} answered: ${version}`,
  };
}

/**
 * The wall-clock headroom the ask's own timer keeps below the probe-level
 * wrapper's fixed expiry: timers carry millisecond precision and the
 * asks' timers are armed one spawn after another, so the margin - not a
 * one-millisecond subtraction - is what keeps every ask's expiry strictly
 * earlier than the wrapper's.
 */
const CLIENT_ASK_MARGIN_MS = 5;

/**
 * Which version of each detected agent client answered (t_8e49ec96).
 *
 * Slot beside `registered_commands` and read the SAME detection source -
 * the install manifest - because "which clients are here" is a question
 * that must not grow two answers. Read-only, fail-soft, and graded
 * pass/unknown/skipped with no `fail`: a version row never proves a
 * surface broken, so a fully-unknown probe keeps the doctor exit at
 * `DOCTOR_EXIT.probeIncomplete` (6), never 1.
 *
 * There is deliberately no minimum-version table in v1: no `minVersion`
 * column, no config surface. Adding one is a design decision (what a
 * below-minimum row should DO to the exit code) to settle when a consumer
 * exists, not a column to ship half-decided.
 */
export async function probeClientVersions(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  // The probe's own start, before anything is read: the wrapper's timer
  // was armed just before this call, so every ask's budget is measured
  // against this instant - the manifest read and the earlier spawns spend
  // the asks' shared share, never the wrapper's margin.
  const startedAtMs = Date.now();
  let manifest;
  try {
    manifest = readManifest(opts.vault);
  } catch (err) {
    return {
      status: READINESS_STATUS.unknown,
      detail:
        "install manifest could not be read, so no client version could be asked: " +
        flattenReason((err as Error).message),
    };
  }
  const installs = Object.values(manifest.installs);
  if (installs.length === 0) {
    return {
      status: READINESS_STATUS.skipped,
      detail: "install manifest records no installs; no client version to ask",
    };
  }
  // The asks run TOGETHER, and each child's own budget stays below the
  // probe's, so a verdict that carries the rows always wins the race
  // against the probe-level cutoff. Sequential asks could spend the
  // whole probe budget on the first slow client - the cutoff would then
  // replace every answered row with a bare timeout while the loop kept
  // spawning children nobody awaited any more.
  const probeBudgetMs = opts.perCheckTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
  // Each ask's budget is read at ask time against the probe's own start,
  // so the manifest read and the time spawning the earlier children took
  // come off the later asks' share, never off the wrapper's margin. A
  // budget with nothing left spawns nothing: a child started only to be
  // killed on a zero timer would race its own first tick.
  const ask =
    opts.clientVersionRunner ??
    ((argv: ReadonlyArray<string>) => {
      const budgetMs = clientAskBudgetMs(probeBudgetMs, Date.now() - startedAtMs);
      return budgetMs <= 0
        ? Promise.reject(new ReadinessTimeoutError(`client version ${argv[0]}`, 0))
        : spawnClientVersion(argv, budgetMs);
    });
  // Promise.all preserves the manifest's order, whichever ask settles first.
  const rows: ReadinessVersionRow[] = await Promise.all(
    installs.map((entry) => clientVersionRow(entry.target, ask)),
  );
  const counts = countByStatus(rows.map((row) => row.status));
  // The rows carry every client's own answer on every surface that reads
  // this verdict - the human renderer prints one line per row, and the
  // JSON report carries the rows array - so the detail stays the census
  // and never repeats what the rows already say.
  const census = `(${counts.pass} pass, ${counts.unknown} unknown, ${counts.skipped} skipped)`;
  const base = { rows: Object.freeze(rows) };
  if (counts.unknown > 0) {
    return {
      ...base,
      status: READINESS_STATUS.unknown,
      detail: `could not read ${counts.unknown} client version(s) ${census} - each row names its own`,
    };
  }
  if (counts.skipped > 0) {
    return {
      ...base,
      status: READINESS_STATUS.skipped,
      detail: `nothing to ask of ${counts.skipped} of ${rows.length} target(s) ${census}`,
    };
  }
  return {
    ...base,
    status: READINESS_STATUS.pass,
    detail: `${counts.pass} client version(s) answered ${census}`,
  };
}

function extractRegisteredCommands(raw: string): CommandExtraction {
  const fromJson = extractFromJsonConfig(raw);
  if (fromJson !== null) return fromJson;
  return extractFromTomlConfig(raw);
}

/** Walk a (possibly dotted) key path through parsed JSON objects; null when any hop is missing or not an object. */
function resolveJsonKeyPath(root: Record<string, unknown>, dottedKey: string): unknown {
  let current: unknown = root;
  for (const segment of dottedKey.split(".")) {
    if (current === null || typeof current !== "object" || Array.isArray(current)) return null;
    current = (current as Record<string, unknown>)[segment] ?? null;
  }
  return current;
}

/**
 * Read the Open Second Brain entries out of a JSON client config. Returns `null` when
 * the text is not JSON at all, so the TOML reader gets its turn - grok
 * and codex record the very same Open Second Brain names as `[mcp_servers.*]` tables.
 * A JSONC config (opencode V2's `.jsonc`, comments and trailing commas)
 * parses through the vendored editor; text neither reader accepts is
 * not JSON.
 */
function extractFromJsonConfig(raw: string): CommandExtraction | null {
  // Editors may save a BOM at the head; JSON.parse refuses it (the same
  // tolerance json-merge applies when writing these files).
  const stripped = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
  let parsed: unknown;
  try {
    parsed = JSON.parse(stripped);
  } catch {
    try {
      parsed = parseJsoncObject(raw);
    } catch {
      return null;
    }
  }
  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
    return { kind: "none" };
  }
  const root = parsed as Record<string, unknown>;
  const entries: RegisteredCommandEntry[] = [];
  const malformed: string[] = [];
  // The resolved shape's key owns the probe: a V2 file that still holds
  // legacy top-level copies would otherwise have the same entry name
  // scanned twice, and a stale legacy copy reported as a broken command
  // beside its healthy native twin. The native block is scanned alone
  // when it is present AND is the native map - the same judgment the
  // opencode adapter's `shapeIsV2` makes (its `looksLikeServerEntry`,
  // shared here so both readers resolve one file to one shape): a block
  // carrying type/command/url directly on it is a legacy user server
  // that happens to be named `servers`, the file keeps the legacy shape,
  // and the legacy keys are scanned (entry names deduped, first block
  // wins) instead.
  const native = resolveJsonKeyPath(root, "mcp.servers");
  const scanKeys =
    native !== null &&
    typeof native === "object" &&
    !Array.isArray(native) &&
    !looksLikeServerEntry(native)
      ? ["mcp.servers"]
      : JSON_MCP_TOP_LEVEL_KEYS.filter((topKey) => topKey !== "mcp.servers");
  const seen = new Set<string>();
  for (const topKey of scanKeys) {
    const block = resolveJsonKeyPath(root, topKey);
    if (block === null || typeof block !== "object" || Array.isArray(block)) continue;
    for (const [key, value] of Object.entries(block as Record<string, unknown>)) {
      if (!OSB_ENTRY_KEYS.has(key) || seen.has(key)) continue;
      seen.add(key);
      const normalized = normalizeOnDiskEntry(value);
      if (normalized === null) malformed.push(`${topKey}.${key}`);
      else entries.push({ key, ...normalized });
    }
  }
  if (entries.length > 0) return { kind: "entries", entries };
  if (malformed.length > 0) {
    return {
      kind: "malformed",
      reason: `Open Second Brain entries ${malformed.join(", ")} carry no usable command/args`,
    };
  }
  return { kind: "none" };
}

/**
 * The two on-disk entry shapes this repo writes: `{command, args}` and
 * opencode's whole-argv form `{command: [bin, ...args]}`. Anything else
 * is not a command this probe can judge.
 */
function normalizeOnDiskEntry(
  value: unknown,
): { command: string; args: ReadonlyArray<string> } | null {
  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
  const record = value as Record<string, unknown>;
  if (typeof record["command"] === "string" && record["command"].length > 0) {
    const args = stringArgsOrEmpty(record["args"]);
    return args === null ? null : { command: record["command"], args };
  }
  const argv = stringArgsOrEmpty(record["command"]);
  if (argv !== null && argv.length > 0 && argv[0]!.length > 0) {
    return { command: argv[0]!, args: argv.slice(1) };
  }
  return null;
}

/** A string array as stored, `[]` when absent, `null` when malformed. */
function stringArgsOrEmpty(candidate: unknown): ReadonlyArray<string> | null {
  if (candidate === undefined) return [];
  if (!Array.isArray(candidate) || !candidate.every((a) => typeof a === "string")) return null;
  return candidate as string[];
}

/**
 * Read the Open Second Brain entries out of a grok/codex-style TOML config, by
 * line-section and only for the value shapes `grok-config.ts` writes: a
 * quoted-string `command` and a single-line string-array `args`. Codex's
 * CLI-serialized layout has no published grammar and is not guessed at -
 * a table whose values do not parse reports `malformed`, naming it.
 */
function extractFromTomlConfig(raw: string): CommandExtraction {
  const tables = new Map<string, { command: string | null; args: ReadonlyArray<string> | null }>();
  let current: string | null = null;
  for (const rawLine of raw.split("\n")) {
    const line = rawLine.trim();
    if (line.startsWith("[")) {
      const header = TOML_MCP_SERVER_HEADER.exec(line);
      current = header !== null && OSB_ENTRY_KEYS.has(header[1]!) ? header[1]! : null;
      continue;
    }
    if (current === null || line.length === 0 || line.startsWith("#")) continue;
    const eq = line.indexOf("=");
    if (eq <= 0) continue;
    const field = line.slice(0, eq).trim();
    const value = line.slice(eq + 1).trim();
    const table = tables.get(current) ?? { command: null, args: null };
    tables.set(current, table);
    if (field === "command") table.command = parseTomlBasicString(value);
    else if (field === "args") table.args = parseTomlStringArray(value);
  }
  const entries: RegisteredCommandEntry[] = [];
  const malformed: string[] = [];
  for (const [name, table] of tables) {
    if (typeof table.command === "string" && table.command.length > 0) {
      entries.push({ key: name, command: table.command, args: table.args ?? [] });
    } else {
      malformed.push(name);
    }
  }
  if (entries.length > 0) return { kind: "entries", entries };
  if (malformed.length > 0) {
    return {
      kind: "malformed",
      reason: `Open Second Brain tables ${malformed.join(", ")} declare no parseable command`,
    };
  }
  return { kind: "none" };
}

/** TOML basic string, or a literal string (no escapes) between single quotes. */
function parseTomlBasicString(value: string): string | null {
  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
    try {
      const parsed: unknown = JSON.parse(value);
      return typeof parsed === "string" ? parsed : null;
    } catch {
      return null;
    }
  }
  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
    return value.slice(1, -1);
  }
  return null;
}

function parseTomlStringArray(value: string): ReadonlyArray<string> | null {
  if (value.length < 2 || !value.startsWith("[") || !value.endsWith("]")) return null;
  try {
    const parsed: unknown = JSON.parse(value);
    if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) return null;
    return parsed as ReadonlyArray<string>;
  } catch {
    return null;
  }
}

// ----- Write-back contract probe (t_7c01bb39) -------------------------------

/**
 * Map one audited instruction file onto the readiness vocabulary. The two
 * measured faults of a PRESENT block (`malformed-block`, `missing-clauses`)
 * are `fail` - the block was installed and read, so this is a verdict
 * about the surface. `missing-block` and `absent` are `skipped` - an
 * ordinary instruction file that never had the block installed, or no
 * file at all, is not a contract violation.
 * `symlink` and `unreadable` are `unknown` - the read was refused or
 * failed, which is evidence about the probe's reach, never about the gate.
 */
function statusForContractFinding(finding: WritebackContractFinding): ReadinessStatus {
  switch (finding) {
    case WRITEBACK_CONTRACT_FINDING.conforming:
      return READINESS_STATUS.pass;
    case WRITEBACK_CONTRACT_FINDING.malformedBlock:
    case WRITEBACK_CONTRACT_FINDING.missingClauses:
      return READINESS_STATUS.fail;
    case WRITEBACK_CONTRACT_FINDING.missingBlock:
    case WRITEBACK_CONTRACT_FINDING.absent:
      return READINESS_STATUS.skipped;
    case WRITEBACK_CONTRACT_FINDING.symlink:
    case WRITEBACK_CONTRACT_FINDING.unreadable:
      return READINESS_STATUS.unknown;
  }
}

/**
 * The detail of one placement-shadow row (t_00b617b6): the file the host
 * reads, the host by name, the file that carries the contract, and the
 * same read-only recovery clause the per-file rows carry - adding the
 * block to the file the host reads is content-editing, so the probe
 * offers recovery prose, never a command that writes.
 *
 * The contract side's condition is the row's advice, so it is worded from
 * the triple's own finding: a `conforming` contract file "carries the
 * write-back contract" and copying its block is the right move, while any
 * block-bearing-but-broken finding (`malformed-block`, `missing-clauses`)
 * "carries a broken managed block" - following that file verbatim would
 * copy a broken block, and the row must not say otherwise.
 */
function writebackShadowRowDetail(shadow: WritebackContractShadow): string {
  const carries =
    shadow.contractFinding === WRITEBACK_CONTRACT_FINDING.conforming
      ? "carries the write-back contract"
      : "carries a broken managed block";
  return (
    `${shadow.readsPath} is the instruction file the ${shadow.host} host reads, but it ` +
    `carries no Open Second Brain managed block while ${shadow.contractPath} ${carries} - ` +
    `the operative host never sees the same-turn atomic-fact write ` +
    `gate; ${WRITEBACK_CONTRACT_RECOVERY}`
  );
}

/**
 * Does the vault's workspace agent-instruction file(s) carry the same-turn
 * atomic-fact memory write gate? Reads the candidates
 * {@link AGENT_INSTRUCTION_FILES} at the vault root through
 * `brain/writeback-contract.ts`, which owns the whole contract: the
 * managed-block detection, the clause keywords, and the symlink refusal.
 * This probe is only the verdict mapping and aggregation - a second copy
 * of the contract here is exactly how the check and the runtime would
 * drift apart.
 *
 * The vault root, not the CLI's cwd, is the audited workspace: it is where
 * this tree already locates instruction files (the instruction-file
 * ceiling and the removed-tool sweep both read them at `join(vault, ...)`),
 * and a readiness probe must grade the surface an agent actually reads,
 * not whichever directory the `o2b` invocation happened to start in.
 *
 * Grading per file follows the probe rule: a file whose installed block is
 * broken or lacks the gate is a `fail` whose row carries the recovery
 * clause (nothing is rewritten here). A file with no block at all is
 * `skipped` with the reason that the block is not installed. A refused or
 * unreadable read is `unknown` by name. A vault with NO instruction file
 * at all is `skipped` - nothing installed is not a contract violation -
 * while one conforming file among absent peers passes: the absent
 * candidates did not participate, and the census in the detail says so
 * rather than hiding them.
 *
 * Placement shadowing (t_00b617b6) grades beside the per-file rows: a host
 * whose preferred file (`HOST_INSTRUCTION_PRECEDENCE` in
 * `brain/writeback-contract.ts`) carries no managed block while another
 * candidate carries the contract is a proved fault of the surface - the
 * operative host never sees the gate, however conforming the file it does
 * not read is. Each shadow triple becomes one `fail` row keyed by the file
 * the host reads, naming the host, both files and the read-only recovery
 * clause; shadow-free multi-file workspaces and absent-only workspaces
 * grade exactly as before. Shadow rows enter the census and the worst-of
 * aggregate like any other row, which is why the fail header counts
 * findings, not files.
 */
export async function probeWritebackContract(opts: ReadinessOptions): Promise<ReadinessVerdict> {
  const workspace = opts.vault;
  const audits = auditWorkspaceWritebackContract(workspace);
  const rows = audits.map((audit) => ({
    path: audit.path,
    status: statusForContractFinding(audit.finding),
    detail: audit.detail,
  }));
  const shadowRows = resolveShadowedInstructionContracts(audits).map((shadow) => ({
    path: shadow.readsPath,
    status: READINESS_STATUS.fail,
    detail: writebackShadowRowDetail(shadow),
  }));
  const graded = [...rows, ...shadowRows];
  const counts = countByStatus(graded.map((row) => row.status));
  // Worst rows lead the detail; toSorted is stable, so within one bucket
  // the candidate list's priority order stands.
  const ordered = graded.toSorted((a, b) => readinessRank(a.status) - readinessRank(b.status));
  const rowText = ordered.map((row) => `${row.path}: ${row.detail}`).join("; ");
  const census =
    `(${counts.pass} pass, ${counts.fail} fail, ` +
    `${counts.unknown} unknown, ${counts.skipped} skipped)`;
  if (counts.fail > 0) {
    return {
      status: READINESS_STATUS.fail,
      detail: `${counts.fail} agent-instruction finding(s) fail the write-back contract ${census}: ${rowText}`,
    };
  }
  if (counts.unknown > 0) {
    return {
      status: READINESS_STATUS.unknown,
      detail: `could not measure ${counts.unknown} agent-instruction file(s) ${census}: ${rowText}`,
    };
  }
  if (counts.pass === 0 && audits.some((a) => a.finding !== WRITEBACK_CONTRACT_FINDING.absent)) {
    return {
      status: READINESS_STATUS.skipped,
      detail: `the ambient write-back managed block is not installed ${census}: ${rowText}`,
    };
  }
  if (counts.pass === 0) {
    return {
      status: READINESS_STATUS.skipped,
      detail:
        `no agent-instruction file in ${workspace} ` +
        `(checked ${AGENT_INSTRUCTION_FILES.join(", ")}) - nothing installed is ` +
        "not a contract violation",
    };
  }
  return {
    status: READINESS_STATUS.pass,
    detail: `${counts.pass} agent-instruction file(s) carry the write-back contract ${census}: ${rowText}`,
  };
}

// ----- Runner ---------------------------------------------------------------

export interface NamedProbe {
  readonly name: string;
  readonly fn: (opts: ReadinessOptions) => Promise<ReadinessVerdict>;
}

/** The default probe set, in stable output order. */
export const DEFAULT_PROBES: ReadonlyArray<NamedProbe> = [
  { name: READINESS_PROBE.llmKey, fn: probeLlmKey },
  { name: READINESS_PROBE.embeddingProvider, fn: probeEmbeddingProvider },
  { name: READINESS_PROBE.providerConsent, fn: probeProviderConsent },
  { name: READINESS_PROBE.runtimeAdapterWiring, fn: probeRuntimeAdapterWiring },
  { name: READINESS_PROBE.installedRuntimes, fn: probeInstalledRuntimes },
  { name: READINESS_PROBE.registeredCommands, fn: probeRegisteredCommands },
  { name: READINESS_PROBE.clientVersions, fn: probeClientVersions },
  { name: READINESS_PROBE.writebackContract, fn: probeWritebackContract },
  { name: READINESS_PROBE.decisionModel, fn: probeDecisionModel },
];

/**
 * Run every readiness probe under its per-check timeout and aggregate the
 * outcomes. A probe that throws or times out becomes an `unknown` with a
 * reason rather than aborting the run, so one unreadable surface never
 * hides the others and none of them is reported as broken on the strength
 * of a measurement that never completed. `probes` is injectable for
 * testing the timeout and aggregation paths deterministically; it defaults
 * to {@link DEFAULT_PROBES}.
 */
export async function runReadinessProbes(
  opts: ReadinessOptions,
  probes: ReadonlyArray<NamedProbe> = DEFAULT_PROBES,
): Promise<ReadinessReport> {
  const timeoutMs = opts.perCheckTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
  // Probes are independent, so run them together; the mapped array preserves
  // input order regardless of which settles first.
  const results = await Promise.all(
    probes.map(async (probe): Promise<ReadinessProbeResult> => {
      const startedAt = Date.now();
      let verdict: ReadinessVerdict;
      try {
        verdict = await withReadinessTimeout(() => probe.fn(opts), timeoutMs, probe.name);
      } catch (err) {
        // Neither arm has heard from the surface: one budget elapsed, one
        // probe body threw. Both are reported as what they are - a
        // measurement that did not complete - with the cause in the detail.
        const detail =
          err instanceof ReadinessTimeoutError
            ? `timed out after ${timeoutMs}ms, so nothing was established about this surface`
            : `probe error, so nothing was established about this surface: ${(err as Error).message}`;
        verdict = { status: READINESS_STATUS.unknown, detail };
      }
      return {
        name: probe.name,
        ...withNonEmptyDetail(probe.name, verdict),
        durationMs: Date.now() - startedAt,
      };
    }),
  );
  const failed = results.filter((p) => p.status === READINESS_STATUS.fail).length;
  const unknown = results.filter((p) => p.status === READINESS_STATUS.unknown).length;
  return { probes: results, failed, unknown };
}

/**
 * A verdict whose detail is blank claims a status and gives no evidence
 * for it, which is precisely the shape this module exists to refuse. The
 * rule is enforced HERE, once, rather than asserted in each probe's
 * docblock and trusted: a detail-less verdict becomes `unknown` naming
 * the probe and the status it could not substantiate. Rejected
 * alternative: throwing, which would turn a probe's sloppiness into a
 * `fail` and so report a working surface as broken.
 */
function withNonEmptyDetail(name: string, verdict: ReadinessVerdict): ReadinessVerdict {
  if (verdict.detail.trim().length > 0) return verdict;
  return {
    status: READINESS_STATUS.unknown,
    detail: `probe '${name}' claimed '${verdict.status}' with no detail, so the claim is unverified`,
  };
}