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
/**
* 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`,
};
}