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
/**
* Diagnostics-signal model + guarded repair driver (Source pipeline
* integrity suite, O2, t_bd6cc4cb).
*
* This module is the ONE home for the diagnostics-signal shape the wave
* introduced: an issue class carries its own next-command hint and, when
* a safe deterministic repair exists, its fixer. Hints travel WITH the
* issue definition (the {@link DIAGNOSTIC_SIGNALS} registry) so no
* downstream formatter - not the repair preview, not the O3 operator
* snapshot - hardcodes a command string. Detection stays in its existing
* home: `doctor.ts` produces the issue stream and this module keys off it,
* never re-implementing a lint.
*
* Repair contract:
* - `doctor.ts` (plain / `--strict`) is read-only and byte-identical;
* nothing here runs unless the operator opts in with `--repair`.
* - `planRepair` is a pure read: it previews what `--apply` would do,
* DERIVED FROM the doctor's findings rather than from a scan of its
* own (no-dead-ends, task 9). Each fixer receives exactly the
* findings carrying the doctor code it covers. Neither fixer keeps a
* private detector: the doctor reports `dangling-workrun` from the
* same scan the WAL fixer used to run, and `broken-wikilink` is a
* superset of the orphaned-reference population.
* - `applyRepair({ dryRun: true })` is the preview surface (writes
* nothing); `{ dryRun: false }` performs the fixes and appends ONE
* typed `doctor-repair` event per applied fix.
* - Every fixer is safe, deterministic, and idempotent: a second apply
* finds nothing to do and writes nothing. A detected instance a fixer
* cannot safely repair is reported as needs-review, never silently
* dropped and never pretended-fixed.
*
* Fixers exist ONLY for issue classes the doctor already detects:
* - `wal-gap` closes a dangling dream workrun (an append-only,
* write-ahead-style checkpoint log that never reached a terminal
* phase) by appending the missing terminal `interrupted` marker.
* Additive: forensic content is preserved, the gap is closed.
* - `orphaned-reference` prunes a dead `evidenced_by` wikilink (a
* Brain-managed `pref-`/`ret-`/`sig-` target with no file) from a
* preference or retired record. The removed pointer is captured in
* the typed event, so the change is auditable and recoverable.
* Broken structural links (`supersedes`, `retired_by`,
* `superseded_by`) are reported needs-review: removing one would drop
* lifecycle provenance or break a required field.
*/
import { appendFileSync, existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { normalizeAgentArgument } from "../agent-identity.ts";
import { resolveAgentName } from "../config.ts";
import { renderUnifiedDiff } from "../diff.ts";
import type { TransportReach } from "../graph/transport-reach.ts";
import { pathIsInside, vaultRelative } from "../path-safety.ts";
import { formatFrontmatter, parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";
import type { FrontmatterMap } from "../types.ts";
import { UnclassifiedRepairCodeError, requireMechanicalRepair } from "./applier-capability.ts";
import { collectAllBasenames, runDoctor } from "./doctor.ts";
import {
ENTITY_QUOTE_VARIANT_COLLISION_CODE,
ENTITY_QUOTE_VARIANT_COLLISION_COMMAND,
} from "./entities/canonical.ts";
import { ATTESTATION_CHECK_CODE } from "./doctor/attestation-check.ts";
import { RECEIPT_CONTENT_DRIFT_CODE } from "./doctor/receipt-content-drift-check.ts";
import { GIT_TRACKED_DERIVED_STATE_CODE } from "./doctor/git-tracked-state-check.ts";
import { STORE_SHARD_CORRUPT_LINE_CODE } from "./doctor/store-gap-check.ts";
import { scanDanglingWorkruns, WORKRUN_PHASE } from "./dream-workrun.ts";
import { extractWikilinkRichBodies, parseWikilinkRich } from "./link-graph/parse-wikilink.ts";
import { LINT_CONSOLIDATE_KIND } from "./lint-consolidate.ts";
import { appendLogEvent } from "./log.ts";
import { everyArtifactRefView, type ArtifactRef } from "./artifact-ref-view.ts";
import { ownerScopeView } from "./owner-scope-view.ts";
import { reachView } from "./reach-view.ts";
import { acquireLockSync } from "./sync-lockfile.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND, type DoctorIssue } from "./types.ts";
import { isBrainArtifactId, normaliseWikilinkTarget } from "./wikilink.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { recordRefs } from "./log-events-at-reach.ts";
import { WRITE_REFUSAL_NEXT_COMMAND } from "./write-refusal-exit.ts";
import { extractId } from "./temporal/period-common.ts";
// ----- Diagnostics-signal model --------------------------------------------
/**
* One diagnostics signal: an issue class plus the exact CLI command an
* operator runs next to act on it. `autoRepairable` is true only when a
* fixer in this module can safely, idempotently repair the class.
*/
export interface DiagnosticSignal {
/** Stable code: a doctor issue code, a fixer code, or an O3 source code. */
readonly code: string;
/** Short human label for the issue class. */
readonly issueClass: string;
/** Exact next command to run (a structural CLI string, never prose). */
readonly nextCommand: string;
/** True iff a fixer in this module repairs the class. */
readonly autoRepairable: boolean;
}
/**
* The two states of the search index FILE itself, named here so the
* producer and the registry entry cannot drift into two spellings of one
* code. They are separate classes because their exits differ: an absent
* index is built incrementally, a malformed one is only ever replaced.
*/
export const SEARCH_INDEX_MISSING_CODE = "search-index-missing";
export const SEARCH_INDEX_CORRUPT_CODE = "search-index-corrupt";
/**
* The two attest-CLI states named here so the verb and the registry
* entry cannot drift into two spellings of one code, the same
* one-definition shape the search-index pair above uses. Neither is a
* doctor check's code: both are stdout forward-pointer states of
* `o2b brain attest` itself.
*/
export const ATTESTATIONS_ABSENT_CODE = "attestations-absent";
export const ATTESTATION_STORE_DAMAGED_CODE = "attestation-store-damaged";
/**
* The state the memory-graph repair lane's holdout gate refuses in: at
* least one edge the lane proposes has a target that resolves to no
* durable-memory note, or resolves to one that hydrates into no evidence.
* Named here beside the code it is registered under so the producer in
* `cli/brain/verbs/repair-lane.ts` and the entry below cannot drift into
* two spellings of one code.
*/
export const REPAIR_HOLDOUT_UNRESOLVED_CODE = "repair-holdout-unresolved";
/** Fixer codes (the two auto-repairable classes this release ships). */
export const REPAIR_CODE = Object.freeze({
walGap: "wal-gap",
orphanedReference: "orphaned-reference",
} as const);
/**
* Registry: the single home for every issue class this wave surfaces and
* its next-command hint. Doctor codes, fixer codes, and the O3 snapshot
* source codes all resolve here so a hint is defined exactly once.
*
* no-dead-ends (task 5) widened the population from "issue" to "state a
* caller can be left in": a verb that succeeded and printed nothing
* forward is the same defect from the caller's side, and giving those
* states a code here is what stops the command being retyped inside an
* `ok()` string. Nothing iterates this map expecting only faults; every
* consumer resolves by code.
*/
export const DIAGNOSTIC_SIGNALS: ReadonlyMap<string, DiagnosticSignal> = new Map(
(
[
// --- Auto-repairable fixer classes ---
{
code: REPAIR_CODE.walGap,
issueClass: "dangling dream workrun (WAL gap)",
nextCommand: "o2b brain doctor --repair --apply",
autoRepairable: true,
},
{
code: REPAIR_CODE.orphanedReference,
issueClass: "orphaned evidence reference",
nextCommand: "o2b brain doctor --repair --apply",
autoRepairable: true,
},
// --- Doctor issue classes the fixers back (kept for hint lookup) ---
{
code: "dangling-workrun",
issueClass: "dangling dream workrun (WAL gap)",
nextCommand: "o2b brain doctor --repair --apply",
autoRepairable: true,
},
{
code: "broken-wikilink",
issueClass: "broken frontmatter reference",
nextCommand: "o2b brain doctor --repair --apply",
autoRepairable: true,
},
// --- Detected-but-not-auto-repairable doctor classes ---
{
code: "config-missing",
issueClass: "missing Brain config",
nextCommand: "o2b brain init",
autoRepairable: false,
},
{
code: "store-missing",
issueClass: "brain store not created yet",
nextCommand: "o2b store init",
autoRepairable: false,
},
{
code: "view-writer-silent",
issueClass: "the human view writer has published nothing for days",
nextCommand: "o2b view writer --here",
autoRepairable: false,
},
{
// The dry run is the first step whether or not the store exists:
// it reads the legacy tree alone. The finding names `o2b store
// init` before it when no store exists yet.
code: "migration-available",
issueClass: "brain store migration available",
nextCommand: "o2b brain migrate-store --dry-run",
autoRepairable: false,
},
{
code: "config-invalid",
issueClass: "invalid Brain config",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
{
code: "schema-version-unknown",
issueClass: "unknown schema version",
nextCommand: "o2b brain upgrade --apply",
autoRepairable: false,
},
{
code: "principle-corrupted",
issueClass: "corrupted preference principle",
nextCommand: "o2b brain upgrade --apply",
autoRepairable: false,
},
{
code: "content-hash-drift",
issueClass: "content-hash drift",
nextCommand: "o2b brain doctor --remediate",
autoRepairable: false,
},
{
code: "duplicate-preferences",
issueClass: "duplicate preferences",
nextCommand: "o2b brain merge <keep> <drop>",
autoRepairable: false,
},
{
// Two topic spellings that fold onto one dream-pass key. The exit
// is the same as the duplicate above because the required end
// state is the same - one owner for the key - and it is the only
// structural command that reaches it; renaming a topic is a hand
// edit, which a next-step hint cannot spell.
code: "topic-key-collision",
issueClass: "topic key claimed by two spellings",
nextCommand: "o2b brain merge <keep> <drop>",
autoRepairable: false,
},
{
code: "orphan-evidence",
issueClass: "orphaned apply-evidence artifact",
nextCommand: "o2b brain audit",
autoRepairable: false,
},
{
// An observation signal whose session_ref resolves to no session
// or continuity record. The exit is the detach verb, which is
// dry-run by default and confirm-gated; `autoRepairable` stays
// false because the doctor's repair planner has no fixer for it -
// the repair lives behind the verb the issue's `fix` field names.
code: "orphan-session-ref",
issueClass: "observation whose session_ref resolves to no session",
nextCommand: "o2b brain orphan-repair",
autoRepairable: false,
},
{
code: "broken-backlinks",
issueClass: "broken Brain backlink",
nextCommand: "o2b brain backlinks",
autoRepairable: false,
},
{
// U3, silence-is-not-an-answer. The reverse of the backlink
// question above: not "this reference points at nothing" but
// "this reference points at something that has since changed,
// and the thing holding it predates the change". The trail of
// the state itself is where an operator starts, because it says
// what the rule became and why.
code: "stale-dependency",
issueClass: "consumer resting on a superseded state",
nextCommand: "o2b brain audit <pref-id>",
autoRepairable: false,
},
{
// C1, evidence-at-the-boundary. The exit is the wider view of the
// same measurement: the check reports one fixed window, and the
// per-channel rollup over an operator-chosen one is what says
// whether the transport ever delivered or merely stopped.
code: "recall-channel-silent",
issueClass: "installed recall channel with no deliveries",
nextCommand: "o2b brain recall-telemetry summary --channel <channel> --since <iso>",
autoRepairable: false,
},
{
code: "sync-conflict-log",
issueClass: "sync-conflict log copy",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
{
code: "contradictory-preferences",
issueClass: "contradictory preferences",
nextCommand: "o2b brain health",
autoRepairable: false,
},
{
code: "stale-claim",
issueClass: "stale confirmed preference",
nextCommand: "o2b brain stale",
autoRepairable: false,
},
{
// write-honesty, F4. A count or amount authored with no structural
// date is a claim that answers as true at every instant, because an
// absent `valid_from` is unbounded. The exit is the claim-graph
// query: `--at` and `--history` are what place a claim in time, and
// the write-time finding names the lexeme the reader should check.
//
// Spelled as a literal for the same reason `vault-frozen` above is:
// importing the code from `page-lint.ts` would close an import cycle
// (page-lint -> next-step -> diagnostics -> page-lint). The producer
// and this entry are kept in step by the producer's own test, which
// resolves THIS code through `nextCommandField`.
code: "undated-quantity",
issueClass: "count or amount written with no date",
nextCommand: "o2b brain claims",
autoRepairable: false,
},
{
// The dead-letter exit (t_50794f57). Spelled as a literal for the
// same reason `undated-quantity` above is: importing the code from
// `extract-signals.ts` would close an import cycle (the extractor
// sits inside this module's import graph). The producer and this
// entry are kept in step by the surface test, which resolves THIS
// code through `resolveNextStep` against the command the write
// error's message names.
code: "extract-signals-dead-letter",
issueClass: "a partial extraction write left a dead letter on disk",
nextCommand: "o2b brain dead-letters",
autoRepairable: false,
},
{
// Issue #149. The detector has existed since the hygiene lints
// shipped; what it never had was an exit. Recording real use is
// the only thing that moves a cold-start rule, and the reporter
// reached for a synthetic confidence value precisely because no
// surface said so.
code: "low-evidence-confirmed",
issueClass: "confirmed rule with no recorded use",
nextCommand: "o2b brain apply-evidence --pref <id> --artifact <artifact> --result=applied",
autoRepairable: false,
},
// --- O3 operator-snapshot source classes ---
{
code: "doctor-errors",
issueClass: "doctor errors",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
{
// GitHub #216. The automatic managed-file upgrade failed and is
// backing off; the dry run shows the pending change and the error.
code: "self-heal-upgrade-failed",
issueClass: "automatic Brain upgrade failed",
nextCommand: "o2b brain upgrade --dry-run",
autoRepairable: false,
},
{
// A synced managed file carries a newer template revision than this
// release ships: another device runs a newer release. This device
// keeps the file as it is; updating Open Second Brain here clears it.
code: "managed-file-from-newer-release",
issueClass: "Brain manual written by a newer release",
nextCommand: "o2b brain upgrade --dry-run",
autoRepairable: false,
},
{
code: "doctor-warnings",
issueClass: "doctor warnings",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
{
code: "semantic-health",
issueClass: "semantic-health findings",
nextCommand: "o2b brain health",
autoRepairable: false,
},
{
code: "hygiene-findings",
issueClass: "hygiene findings",
nextCommand: "o2b brain hygiene scan",
autoRepairable: false,
},
{
code: "stale-notes",
issueClass: "stale entries",
nextCommand: "o2b brain stale",
autoRepairable: false,
},
{
code: "review-queue",
issueClass: "review candidates pending",
nextCommand: "o2b brain dream --dry-run",
autoRepairable: false,
},
{
code: "state-file",
issueClass: "state-file health",
nextCommand: "o2b brain init",
autoRepairable: false,
},
// --- Terminal states (no-dead-ends, task 5) ---
// A verb that succeeded and left the caller with nowhere to go.
// These are not defects, so `issueClass` reads as the STATE the
// caller is in rather than a fault; the field is otherwise the
// same short label every other entry carries, and the registry
// stays the single place a structural command is written down.
{
code: "brain-empty",
issueClass: "Brain with nothing recorded in it",
nextCommand: "o2b brain feedback --topic <topic> --signal=positive --principle <principle>",
autoRepairable: false,
},
{
code: "signal-clusters-absent",
issueClass: "no active signal clusters to review",
nextCommand: "o2b brain feedback --topic <topic> --signal=positive --principle <principle>",
autoRepairable: false,
},
{
code: "intentions-absent",
issueClass: "no active intention chains",
nextCommand: "o2b brain intention set --scope <scope> --text <text>",
autoRepairable: false,
},
{
code: "search-index-built",
issueClass: "search index up to date",
nextCommand: "o2b search query <text>",
autoRepairable: false,
},
{
code: SEARCH_INDEX_MISSING_CODE,
issueClass: "search index not built",
nextCommand: "o2b search index",
autoRepairable: false,
},
{
// The state a completed `PRAGMA quick_check` reports when the
// index file is structurally malformed - pages damaged in place
// by a truncated sync, a half-finished replication of the vault
// directory, or failing storage. It is deliberately NOT
// `search-index-missing`: that state's exit is `o2b search
// index`, which is INCREMENTAL and would walk a vault whose
// files have not changed, decide there is nothing to do, and
// leave every damaged page exactly where it is. Only a rebuild
// replaces the file, so only a rebuild ends this state.
code: SEARCH_INDEX_CORRUPT_CODE,
issueClass: "search index failed a structural integrity check",
nextCommand: "o2b search reindex",
autoRepairable: false,
},
// --- Semantic capability tiers (provenance-at-the-boundary, F1) ---
// WHAT THE OPERATOR CONFIGURED, resolved by
// `core/search/capability-tier.ts` and reported by the four
// surfaces that used to each derive it themselves - one of them by
// assembling these very sentences beside the call. The `SearchError`
// codes answer the different question of what a call attempted and
// could not do; nothing reports both for one condition.
//
// The exit for the two blocked tiers is the pre-flight diagnostic
// rather than an edit command: the remediation is a config key, and
// no verb in this tool writes one. `search check` is what names the
// key, the provider and the env var for the operator to set.
{
code: "semantic-capability-disabled",
// Two configurations reach this rung - `search_semantic_enabled=false`
// and `embedding_provider=disabled` - so the sentence names the state
// rather than one of its causes. It is a thrown error message on the
// explicit arm now, where naming the wrong key would send an operator
// to edit a setting that is already correct. `o2b search check` reports
// which of the two it is.
issueClass: "semantic search not configured (disabled by config or provider)",
nextCommand: "o2b search check",
autoRepairable: false,
},
{
code: "semantic-capability-key-missing",
issueClass: "embedding_api_key not configured",
nextCommand: "o2b search check",
autoRepairable: false,
},
{
// Not a fault - the tier an operator wants to be at. It is
// registered because the ladder must be total: a surface that
// resolves a label per tier cannot have one rung with no entry,
// and the honest exit from "configured" is to populate vectors.
code: "semantic-capability-configured",
issueClass: "semantic search configured",
nextCommand: "o2b search vector-backfill",
autoRepairable: false,
},
// --- Vector-population states (provenance-at-the-boundary, F) ---
// Index facts, deliberately named apart from the capability tiers:
// a chunk with no vector is a `chunks` row with no `embeddings` row,
// which is a first-class, already-resumable state and not a
// degraded one.
{
code: "semantic-vectors-deferred",
issueClass: "embeddings not requested this run",
nextCommand: "o2b search vector-backfill --apply",
autoRepairable: false,
},
{
code: "semantic-vectors-pending",
issueClass: "indexed chunks with no vector",
nextCommand: "o2b search vector-backfill --apply",
autoRepairable: false,
},
// --- Event-anchor population (provenance-at-the-boundary) ---
// The same class of index fact as the vector states, for the same
// reason: a schema bump migrates in place and reindexes nothing,
// and the indexer resolves an anchor only for content that
// changed, so a document carried over from a pre-anchor binary
// never gets one. It is a distinct code because the remedy is a
// distinct verb, and because "no anchor resolved" must never be
// reported as the note declaring no date.
{
code: "event-anchors-pending",
issueClass: "indexed documents with no event anchor resolved",
nextCommand: "o2b search event-anchor-backfill --apply",
autoRepairable: false,
},
// --- Oversize-chunk census (what-the-index-already-knew, task H) ---
// The configured chunk size and the configured model's declared
// input window are two settings that overflow each other in
// silence: a provider that truncates server-side returns a vector
// of the right width for a prefix of the passage, and nothing
// local can see that it happened. The census is what makes the
// condition observable; these are its two exits.
{
code: "search-chunk-window-overflow",
issueClass: "indexed chunks larger than the embedding model's input window",
// The chunk boundaries are what must change, and only a rebuild
// re-cuts them - `--embeddings` because vectors computed over the
// old boundaries do not describe the new chunks. Lowering
// `search_chunk_size` first is what makes the rebuild different
// from the run that produced this state; no verb in this tool
// writes a config key, so that half is named in the warning prose
// rather than invented as a command here.
nextCommand: "o2b search reindex --embeddings",
autoRepairable: false,
},
{
code: "search-chunk-window-undeclared",
issueClass: "embedding model with no declared input window",
// Not a fault and not a pass: the check could not run. The exit
// is the curated catalog, because a declared window is exactly
// what distinguishes a model in that table from one outside it,
// and switching models is a config key no verb writes.
nextCommand: "o2b search provider presets",
autoRepairable: false,
},
{
// How long since a state-changing pass left a recovery point.
// The exit is the LISTING verb rather than a command that makes
// one: a snapshot is a side effect of dream, upgrade and the
// memory import, so "take a snapshot" is not a thing an operator
// does, and the listing is what answers the question the finding
// raises - when the last recovery point was taken and for what.
// Spelled as a literal, not imported from the check that produces
// it: importing a `*_CODE` identifier from this module into a
// doctor check would make the census follow the import back and
// read every registry entry below as a doctor code. Same reason
// `recall-channel-silent` is a literal here.
// The vault carries a freeze marker. Spelled as a literal for
// the same reason `recovery-point-stale` below is: importing a
// `*_CODE` identifier from this module into a doctor check would
// make the exit census follow the import back and read every
// registry entry here as a doctor code.
//
// `autoRepairable: false` is load-bearing rather than a default.
// A freeze is an instruction, not a defect, and a repair pass
// that lifted one would be overruling the operator who set it
// from a machine they may not be sitting at.
code: "vault-frozen",
issueClass: "vault frozen: every content write is refused",
nextCommand: "o2b brain unfreeze",
autoRepairable: false,
},
{
// A shard of the Brain log stopped linking up. Spelled as a
// literal for the same reason `vault-frozen` above is: importing
// a `*_CODE` identifier from this module into a doctor check
// would make the exit census follow the import back and read
// every registry entry here as a doctor code.
//
// The exit is the verifier rather than a repair, and
// `autoRepairable: false` is the whole point rather than a
// default: the only way to make a broken chain verify is to
// rewrite the history it records, which is precisely the act the
// chain exists to detect. What an operator can do is SEE the
// damage across every shard, which is what the verb prints.
code: "log-chain-broken",
issueClass: "Brain log shard whose hash chain does not hold",
nextCommand: "o2b brain log verify",
autoRepairable: false,
},
{
// The attestation liveness check's one code (delivery trust,
// t_3bdb82b0): the newest attestation is past its window, the
// signing key is gone while signed evidence exists, or a shard
// diverged or went missing since it was signed. The exit is the
// verifier, the check's damage-first answer, which re-measures the
// store against the newest signed point and prints the per-shard
// verdicts an operator needs before re-signing - and
// `autoRepairable` stays false for the same reason
// `log-chain-broken` above does: the verifier reports, nothing
// repairs, and the follow-up (keygen, then sign) is the
// operator's act. Imported from the check module rather than
// spelled as a literal, keeping one definition; the direction of
// the import is the safe one (the check never imports this
// module), so the exit census reading the check's imports back
// sees nothing new.
code: ATTESTATION_CHECK_CODE,
issueClass: "newest store attestation stale, unkeyed, or diverged from the store",
nextCommand: "o2b brain attest verify",
autoRepairable: false,
},
{
// The attest CLI's empty-list state (delivery-trust wave): the
// vault holds no signed attestation, so `o2b brain attest list`
// has nothing to print and the operator's next act is to mint
// one - which needs the operator's key, so `autoRepairable`
// stays false. Named here beside the constant the verb imports,
// the same one-definition shape the search-index codes above
// use for their CLI-facing states.
code: ATTESTATIONS_ABSENT_CODE,
issueClass: "no store attestation on record for this vault",
nextCommand: "o2b brain attest sign",
autoRepairable: false,
},
{
// The attest CLI's diverged-verify state (delivery-trust wave):
// the per-shard verdict found damage - an edited or removed
// shard, or an invalid signature - and the verifier's own exit
// is the report, not a repair. The forward pointer is the log
// chain's verifier rather than `o2b brain attest verify` again:
// the operator has just run it, and whether the log chain
// itself still links up is the adjacent question the damage
// raises. `autoRepairable` stays false: nothing repairs a
// diverged store, the operator investigates.
code: ATTESTATION_STORE_DAMAGED_CODE,
issueClass: "store diverged from the point the newest attestation vouches for",
nextCommand: "o2b brain log verify",
autoRepairable: false,
},
{
// A payload file nothing in the vault references. Spelled as a
// literal for the same reason `vault-frozen` above is. The exit
// is the gc verb, which is dry-run by default: the operator
// reads what would go before `--apply` removes it behind a
// recovery point, so `autoRepairable` stays false.
code: "payload-orphan",
issueClass: "payload file referenced by nothing in the vault",
nextCommand: "o2b brain payload gc",
autoRepairable: false,
},
{
// An unreadable permissions document: the operator's trust policy
// exists and is not in force, and every gate fails closed until
// the field the loader named is repaired. The exit is the same
// re-derive loop `config-invalid` uses - `show` prints the same
// field-named error after each edit, so the operator can see the
// repair land - and `autoRepairable` stays false because editing
// a policy file is the operator's act, never a fixer's.
code: "permissions-unreadable",
issueClass: "unreadable permissions document",
nextCommand: "o2b brain permissions show",
autoRepairable: false,
},
{
// Write-side trust, the design's foot-gun note on `default_action:
// deny`. The document loaded and its policy is IN FORCE - but it
// denies the locally configured agent the write action, so every
// write this machine's agent attempts is refused. Deliberate for a
// read-only agent; a surprise for the one-agent document that denies
// everything else by construction. The exit is the same `show` loop
// as the unreadable finding above - its dry-run decision table makes
// the denial visible before the first refusal does - and
// `autoRepairable` stays false because editing a policy file is the
// operator's act, never a fixer's. Built from the same constant as
// the two refusal findings below, keeping the string at one
// definition.
code: "permissions-agent-denied",
issueClass: "permissions document denies the locally configured agent's write",
nextCommand: WRITE_REFUSAL_NEXT_COMMAND,
autoRepairable: false,
},
{
// Review finding F461. A store-only machine reads its permissions
// document from the `permissions.document` shared setting; a
// legacy file with deny rules the setting does not hold is a
// policy the operator believes in force and is not. The exit is the
// same `show` loop: it names the document the gates read now.
code: "permissions-legacy-only",
issueClass: "deny rules in a legacy permissions file no reader sees once switched",
nextCommand: WRITE_REFUSAL_NEXT_COMMAND,
autoRepairable: false,
},
{
// Write-side trust, Task 12. A permissions document rule DENIED a
// write. The refusal names the principal, the action and the rule
// that decided; the exit is the same `show` loop, because the fix
// is editing the policy, which is the operator's act - never a
// fixer's - so `autoRepairable` stays false.
code: "write-refused",
issueClass: "write refused by a permissions document rule",
nextCommand: WRITE_REFUSAL_NEXT_COMMAND,
autoRepairable: false,
},
{
// Write-side trust, PR #247 review M3 residual. The destructive
// source-cleanup lane consults the permissions document like
// update and append do, and the document in force denies this
// machine's agent the ingest action those consults answer - so
// cleanups will be refused by policy, not by fault. The finding
// names the covered lanes; the exit is the same `show` loop as
// the other permission findings, and `autoRepairable` stays
// false because editing a policy file is the operator's act.
code: "deny-consulted-lanes",
issueClass: "permissions document denies the ingest action the mutation lanes consult",
nextCommand: WRITE_REFUSAL_NEXT_COMMAND,
autoRepairable: false,
},
{
// Write-side trust, Task 12. `force_confirmed` skips the dream
// trial window, and under a permissions document that skip is
// reserved for callers whose `write` verdict is allow. Same exit
// and the same operator-held fix as `write-refused` above; the
// distinct code is what tells a caller the document did not
// refuse its write outright - it refused the bypass.
code: "force-confirmed-requires-allow",
issueClass:
"force_confirmed refused: the permissions document does not allow this caller's write",
nextCommand: WRITE_REFUSAL_NEXT_COMMAND,
autoRepairable: false,
},
{
// Inbox signals that left the contradiction window unconsumed
// (issue #195). Spelled as a literal for the same reason
// `vault-frozen` above is. The exit is the pass that archives
// them; `autoRepairable` stays false because the doctor's repair
// planner does not run dream, the operator does.
code: "inbox-archivable",
issueClass: "inbox signals that can no longer become candidates",
nextCommand: "o2b brain dream",
autoRepairable: false,
},
{
code: "recovery-point-stale",
issueClass: "newest recovery point older than the liveness window",
nextCommand: "o2b brain snapshot log",
autoRepairable: false,
},
{
// Storage capacity, for a vault whose operator configured a cap.
// Both severities point at the report surface, which carries the
// per-surface census and the trend; the repair - reclaiming space
// or raising the cap - is an operator decision no verb performs.
code: "storage-capacity-warn",
issueClass: "storage usage past the warn band of the configured cap",
nextCommand: "o2b brain storage",
autoRepairable: false,
},
{
code: "storage-capacity-critical",
issueClass: "storage usage past the critical band: capacity-gated writes are refused",
nextCommand: "o2b brain storage",
autoRepairable: false,
},
{
// Receipt-ledger growth (storage-lifecycle): the append-only
// receipt ledgers crossed the foldable threshold. Unlike the
// storage cap the repair is mechanical, so the row points at the
// verb that previews the fold; the confirmed compact behind the
// same command is the rewrite.
code: "receipt-ledger-growth",
issueClass: "receipt ledgers holding more foldable records than the growth threshold",
nextCommand: "o2b brain receipts scan",
autoRepairable: false,
},
{
// Receipt content drift (t_4300e5fd): receipts the verify kernel re-hashes
// against the vault report changed items. The act this finding asks for is
// INSPECTION - which items drifted and whether the edit was legitimate - so
// the row points at the per-receipt verify verb.
code: RECEIPT_CONTENT_DRIFT_CODE,
issueClass: "recent context receipts re-verifying with changed item content",
nextCommand: "o2b brain context-receipts verify <receipt-id>",
autoRepairable: false,
},
{
// An announced decommission of the configured embedding model,
// inside the warning window. The exit is the curated catalog for
// the same reason `search-chunk-window-undeclared` points there:
// the act this finding asks for is CHOOSING a replacement model,
// and switching models is a config key no verb in this tool
// writes. The re-embed that follows the edit is named in the
// warning's own prose rather than invented as the command here,
// because running it before the key changes would rebuild the
// index against the model that is going away.
code: "embedding-model-sunset-announced",
issueClass: "configured embedding model has an announced decommission date",
nextCommand: "o2b search provider presets",
autoRepairable: false,
},
{
// An enabled openai-compat rerank whose endpoint cannot resolve:
// every search fails closed until it does. The exit lists the
// registered rerank profiles, because the usual repair is naming
// one of them (or registering one) rather than typing three keys.
code: "rerank-endpoint-unconfigured",
issueClass: "rerank enabled with an endpoint that cannot resolve",
nextCommand: "o2b search rerank-provider list",
autoRepairable: false,
},
{
// An announced decommission of the configured rerank model. The
// act is choosing another model or endpoint, and registering it
// as a profile is the verb this tool has for that; unlike the
// embedding case no re-embed follows, because rerank stores
// nothing derived from the model.
code: "rerank-model-sunset-announced",
issueClass: "configured rerank model has an announced decommission date",
nextCommand: "o2b search rerank-provider add",
autoRepairable: false,
},
{
// The index behind its embedding configuration: chunks with no
// vector, or stored vectors under a retired model/dimension. The
// registry carries the backfill verb because it is the
// condition's cheapest first act; the warning prose names the
// re-embed remedy the stale half needs beside it, since a
// backfill finds stale rows fully vectorised and leaves them
// where they are.
code: "embeddings-backlog",
issueClass: "indexed chunks with no vector or vectors stale against the configured model",
nextCommand: "o2b search vector-backfill",
autoRepairable: false,
},
{
code: "git-history-absent",
issueClass: "no ingested git history",
nextCommand: "o2b brain git ingest <repo-path>",
autoRepairable: false,
},
{
code: "bridge-proposals-absent",
issueClass: "no bridge-proposal artifact yet",
nextCommand: "o2b brain bridges discover",
autoRepairable: false,
},
{
code: "hallways-proposals-absent",
issueClass: "no hallways proposals artifact yet",
nextCommand: "o2b brain hallways mine",
autoRepairable: false,
},
{
// provenance-at-the-boundary, unit B. A caller-named write
// landed outside the `write_binding.path_prefixes` the operator
// declared. The exit is the per-path policy inspector, which
// reports the binding verdict for one path beside the
// vault-scope verdict, so the operator sees WHY the write was
// refused and what the declaration currently admits.
code: "write-binding-refused",
issueClass: "caller-named write outside the declared write binding",
nextCommand: "o2b vault inspect <relpath>",
autoRepairable: false,
},
{
// Write-side trust, Task 9. A gated write landed in the review
// queue instead of its publish lane. The receipt carries the
// pending id; the exit is the queue command that publishes it.
code: "pending-staged",
issueClass: "write staged into the review queue, awaiting an operator apply",
nextCommand: "o2b brain pending apply <pending-id>",
autoRepairable: false,
},
{
code: "cli-config-absent",
issueClass: "no machine configuration file",
nextCommand: "o2b init --vault <path> --name <name>",
autoRepairable: false,
},
{
code: "staged-captures-pending",
issueClass: "staged captures previewed but not routed",
nextCommand: "o2b brain inbox-drain --apply",
autoRepairable: false,
},
{
// what-the-index-already-knew, final unit. The repair lane's
// holdout gate refuses an apply whose proposed edges point at
// memory that is absent or empty. The exit is the vault-wide
// structural scan rather than the lane itself: the lane reports
// WHICH edges fail (every decision names its action and its
// endpoints), but what has to change is the referenced note - a
// reference to a note that was deleted, or a note that exists
// with nothing in it. The doctor is the surface that finds those
// across the vault, and `--repair --apply` prunes the subset it
// can safely repair. Deliberately NOT `broken-wikilink`: these
// edges are not written yet, so its fixer would find nothing to
// prune and the pointer would promise a repair that never runs.
code: REPAIR_HOLDOUT_UNRESOLVED_CODE,
issueClass: "proposed repair edges point at absent or empty memory",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
// The five states whose exits used to be retyped inside an `ok()`
// string beside the rail rather than resolved through it.
{
code: "dream-bundles-absent",
issueClass: "no staged dream bundles",
nextCommand: "o2b brain dream stage",
autoRepairable: false,
},
{
code: "cluster-notes-absent",
issueClass: "no materialized cluster notes",
nextCommand: "o2b brain clusters run",
autoRepairable: false,
},
{
code: "recall-tuning-absent",
issueClass: "no persisted recall tuning",
nextCommand: "o2b brain tune run --dataset <path>",
autoRepairable: false,
},
// One finding, two readings, so two codes rather than one code
// carrying two commands: which value is authoritative - the
// indexed one or the note's - is the operator's call, and the
// rail's batch form prints both exits for the one state.
{
code: "tier-drift-restore",
issueClass: "tier drift, indexed value authoritative",
nextCommand: "o2b brain tiers restore <path> --apply",
autoRepairable: false,
},
{
code: "tier-drift-accept",
issueClass: "tier drift, note value authoritative",
nextCommand: "o2b brain tiers accept <path>",
autoRepairable: false,
},
// The restamp's local-search consequence, named once: unioning the
// reserved token into `visibility:` moves a marker page out of
// default-scope local search too, because the formal token dominates
// the scope rule. The command is fully structural - the reserved deny
// token is a fixed vocabulary identifier, not a runtime parameter -
// so the rail carries what a hand-written pointer beside it could
// only retype.
{
code: "restamp-local-visibility",
issueClass: "a restamped page is also reserved against default-scope local search",
nextCommand: "o2b search --visibility=private",
autoRepairable: false,
},
// --- Doctor classes the exit census found unregistered ---
// The census (`tests/core/brain/doctor-exit-census.test.ts`) forced
// every doctor code into one of two buckets. These three turned out
// to have a genuine single command; the other twenty-four are
// recorded as having none, with the reason, in `doctor-exits.ts`.
{
code: "brain-root-absent",
issueClass: "resolved root carries no Brain layer",
nextCommand: "o2b brain init",
autoRepairable: false,
},
{
// The exit is the REVIEW, not the repair: what follows it is
// `tier-drift-restore` or `tier-drift-accept`, registered above,
// and which of the two applies is per drifted note.
code: "tier-drift",
issueClass: "identity-field hand-edits staged",
nextCommand: "o2b brain tiers check",
autoRepairable: false,
},
{
// A review, like tier-drift: the status names the last error and
// the backoff, and the repair depends on what the error is.
code: "freshen-failing",
issueClass: "background index refresh keeps failing",
nextCommand: "o2b search status",
autoRepairable: false,
},
{
code: "entity-label-malformed",
issueClass: "entity label fails the quality gate",
nextCommand: "o2b brain entity prune",
autoRepairable: false,
},
{
// what-the-index-already-knew, task A. The identity kernel now
// folds typographic quote variants, so two records that differ
// only in which apostrophe an editor inserted resolve to one
// identity key. Records that coexisted before the fold therefore
// collide after it, at a write seam the operator did nothing new
// to reach - and a refusal met for the first time straight after
// an upgrade is worse than the duplicate it fixes if it names no
// way out.
//
// The exit is `entity archive`, not a merge verb: there is none,
// and there should not be one here. Which of the two records
// keeps the identity, its history and its edges is a reading of
// both files - the same judgement `doctor-exits.ts` records for
// `duplicate-entity` - so the command names the one mechanical
// step that ends the collision and leaves the choice with the
// operator.
//
// PRODUCER: `doctor/entity-checks.ts`, which splits the duplicate
// report by cause and spells this code on the half the fold
// created. That is what makes the registration live: the doctor's
// surfaces resolve a finding's code through the rail, so the
// command below is what an operator is shown. The registry's own
// write-time and read-time refusals are thrown synchronously out
// of core - too early for the rail, and unable to import it
// without closing a module cycle - so they interpolate
// `ENTITY_QUOTE_VARIANT_COLLISION_COMMAND`, the same constant this
// entry is built from.
code: ENTITY_QUOTE_VARIANT_COLLISION_CODE,
issueClass: "entity labels differing only in typographic quote form",
nextCommand: ENTITY_QUOTE_VARIANT_COLLISION_COMMAND,
autoRepairable: false,
},
{
// A subtree the doctor could not enter, reported into the
// `uncertain` stream by every sweep that walks the store by
// hand. The CLI folds that stream into the codes it resolves
// exits for, so an unregistered code printed the finding and
// nothing after it - the dead end this release removes.
//
// The exit is the RE-READ, as with `skill-accept-locked`: no
// command changes a mode or a mount, and the one thing an
// operator needs after restoring access is the pass over the
// subtree that was skipped. Registering it here rather than
// spelling a sentence beside the notice is what keeps the
// structural command in one place.
code: "vault-walk-entry-skipped",
issueClass: "subtree the doctor could not read",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
{
// The structural form; the finding's message carries the concrete
// command with the shard as `<partition>/<shard>` and its offset.
code: STORE_SHARD_CORRUPT_LINE_CODE,
issueClass: "a bad line in the middle of a held store shard",
nextCommand: "o2b store shard quarantine <partition-shard> --offset <n>",
autoRepairable: false,
},
// --- Skill-accept transaction refusals (no-dead-ends, phase 3) ---
// Both are states the accept transaction itself can leave an
// operator in, and both used to refuse without naming a way out.
// They are registered here rather than spelled inside the two
// error messages so the messages resolve one structural command
// from the same registry every other surface reads.
{
code: "skill-accept-journal-unreadable",
issueClass: "unreadable skill-accept journal marker",
nextCommand: "o2b brain skill-proposals recover --discard-unreadable",
autoRepairable: false,
},
{
// The exit is the INSPECTION, not a repair: nothing breaks a
// lock automatically, so what the operator needs first is the
// full list of locks under the Brain tree with their paths.
// Removing the file stays a human judgement - see the
// `stale-lock` refusal in `applier-capability.ts`.
code: "skill-accept-locked",
issueClass: "skill-accept lock held",
nextCommand: "o2b brain doctor",
autoRepairable: false,
},
// --- Runtime-notice conditions (no-dead-ends, task 3) ---
// The notice channel pushes a transient condition at the agent
// (SessionStart injection, `vault_health`, the onboarding
// checklist) rather than waiting to be polled, and it spells its
// codes in the snake case its wire records use. Registering them
// here is what lets a notice carry a structural command instead of
// an English "Run: ..." tail a consumer has to regex.
//
// `search_index_missing` is the same condition the kebab-cased
// `search-index-missing` terminal state reports from `o2b search
// check`, and deliberately resolves to the same command: two
// emitters, two code vocabularies, one exit. Only the codes with a
// genuine single exit are listed - `vault_read_only`,
// `vault_marker_absent`, `brain_config_unreadable` and
// `reindex_in_progress` have none, each for a reason written down
// beside the notice that raises it.
{
code: "search_index_missing",
issueClass: "search index not built",
nextCommand: "o2b search index",
autoRepairable: false,
},
{
code: "semantic_degraded",
issueClass: "semantic search fell back to lexical",
nextCommand: "o2b search check",
autoRepairable: false,
},
// --- Capture-routing states (signals-that-survive, unit 4) ---
// A capture that resolved no scope is recorded and unroutable: it
// is not a fault - the write is exactly what the operator asked
// for - but it leaves the signal in the one bucket no scoped
// recall reaches. The exit is to re-record the SAME capture with
// the routing signal it lacked, which is why the command carries
// `--scope`: without it this entry would be indistinguishable
// from `brain-empty`'s.
// --- Self-healing lint classes (evidence-at-the-boundary, task A4) ---
// Both were registered in `applier-capability.ts` as mechanically
// repairable and NOWHERE here, so `nextCommandField("fix-merged-link")`
// resolved to nothing: the table published that a fixer exists while
// no surface could say what to run to reach it. The write-time page
// lint carries the first of the two on a finding, which is what made
// the omission observable.
//
// Both resolve to the same command because one pass performs both
// repairs; `--yes` rides along because `--apply` refuses without it
// on any non-interactive stream, which is every stream an agent has.
{
code: LINT_CONSOLIDATE_KIND.mergedLink,
issueClass: "wikilink pointing at a page merged away",
nextCommand: "o2b brain lint --consolidate --apply --yes",
autoRepairable: true,
},
{
code: LINT_CONSOLIDATE_KIND.staleStableDemotion,
issueClass: "stable preference aged out with no verification",
nextCommand: "o2b brain lint --consolidate --apply --yes",
autoRepairable: true,
},
{
code: "capture-scope-absent",
issueClass: "capture recorded with no routing scope",
nextCommand:
"o2b brain feedback --topic <topic> --signal=positive --principle <principle> --scope <scope>",
autoRepairable: false,
},
{
// The git tracked-state row (t_206562ae). The ignore half of the
// remediation is the seeder, and the seeder is idempotent and
// merge-safe on an existing vault, so one command ends the
// warning - and the ignore half of the error. The untrack half
// is git's own (one location-independent `git -C <vault> rm -r --cached --
// .open-second-brain` command, named in the finding) because no verb in this tool untracks a file.
code: GIT_TRACKED_DERIVED_STATE_CODE,
issueClass: "derived brain state tracked by git, or present and not git-ignored",
nextCommand: "o2b brain init",
autoRepairable: false,
},
] satisfies ReadonlyArray<DiagnosticSignal>
).map((s) => [s.code, Object.freeze(s)]),
);
/**
* Resolve a signal by code, LENIENTLY. An unregistered code does not
* resolve: this function fabricates a generic `o2b brain doctor` signal
* whose `issueClass` is the raw code. That value is invented here, it is
* not a registry entry, and it does not mean the code is known.
*
* Kept for its two existing consumers (the O3 operator snapshot and the
* repair planner's unfixable aggregation), whose output shape predates
* this release. New consumers MUST use `resolveNextStep` in
* `next-step.ts`, which returns an explicit absent result instead of a
* guessed command.
*/
export function resolveSignal(code: string): DiagnosticSignal {
const known = DIAGNOSTIC_SIGNALS.get(code);
if (known) return known;
return Object.freeze({
code,
issueClass: code,
nextCommand: "o2b brain doctor",
autoRepairable: false,
});
}
// ----- Repair plan shapes ---------------------------------------------------
/** One planned fix (applicable) or a detected-but-needs-review instance. */
export interface RepairItem {
/** Fixer code ({@link REPAIR_CODE}). */
readonly code: string;
/** Stable, vault-relative target identifier the fix acts on. */
readonly target: string;
/** True when a fixer can safely apply this; false = needs-review. */
readonly applicable: boolean;
/** One-line human description of the planned action. */
readonly detail: string;
/** Why the instance is needs-review (present iff `applicable` is false). */
readonly reason?: string;
}
/** A detected issue class with no fixer, aggregated for the preview. */
export interface UnfixableClass {
readonly code: string;
readonly issueClass: string;
readonly count: number;
readonly nextCommand: string;
}
export interface RepairPlan {
/** Every fixer finding: applicable fixes plus needs-review instances. */
readonly fixes: ReadonlyArray<RepairItem>;
/** Detected classes no fixer addresses, each with its next command. */
readonly unfixable: ReadonlyArray<UnfixableClass>;
}
// ----- Fixers ---------------------------------------------------------------
/**
* A doctor finding did not carry the data its fixer needs to plan from.
*
* Raised, not skipped (no-dead-ends, task 9). A `dangling-workrun` with
* no path, or a `broken-wikilink` with no field or target, means the
* detector and this module disagree about the finding contract; dropping
* the item would report a complete plan that had silently omitted a
* detected defect.
*/
export class MalformedDoctorFindingError extends Error {
readonly code: string;
readonly missingField: string;
constructor(code: string, missingField: string) {
super(
`doctor finding ${JSON.stringify(code)} carries no ${JSON.stringify(missingField)}, ` +
"so the fixer for it cannot derive a repair target",
);
this.name = "MalformedDoctorFindingError";
this.code = code;
this.missingField = missingField;
}
}
/**
* A fixer owns one auto-repairable class. `coversDoctorCode` is the
* doctor issue code the fixer represents: the planner hands it exactly
* the findings carrying that code, and excludes the code from the
* needs-a-different-tool `unfixable` list.
*
* `plan` receives those findings rather than the vault alone. Both
* fixers' classes are reported in FULL by the doctor - `dangling-workrun`
* comes from the same `scanDanglingWorkruns` the fixer used to call, and
* `broken-wikilink` is a superset of the orphaned-reference population
* (it also reports targets outside the Brain id space, which this fixer
* skips) - so neither retains an independent scan. `vault` is still
* passed because a repair target is vault-relative; it is not a licence
* to look for work the findings did not name.
*/
interface Fixer {
readonly code: string;
readonly coversDoctorCode: string;
plan(vault: string, findings: ReadonlyArray<DoctorIssue>): RepairItem[];
/** Apply one applicable item. Returns null on an idempotent no-op. */
apply(vault: string, item: RepairItem): AppliedFix | null;
/**
* The consent preview (t_b6bcd984): what `apply` would write to the
* item's file, as raw before/after bytes for the shared unified-diff
* renderer. Read-only and best-effort - `null` when the target is
* gone or the item's shape is not one this fixer can draw. The dry
* run renders it per applied item; the write path re-derives under
* its lock and stays the authority.
*/
preview?(vault: string, item: RepairItem): { before: string; after: string } | null;
}
/** Doctor field name for the evidence list; its raw key is `_evidenced_by`. */
const DOCTOR_EVIDENCE_FIELD = "evidenced_by";
/** Separator between the parts of an `orphaned-reference` target id. */
const TARGET_SEP = "::";
/** Raw frontmatter key for the derived evidence list. */
const EVIDENCED_BY_KEY = "_evidenced_by";
function isBrokenBrainRef(raw: string, known: ReadonlySet<string>): string | null {
const target = normaliseWikilinkTarget(raw);
if (!target) return null;
if (!isBrainArtifactId(target)) return null; // external / non-Brain link: leave it
if (known.has(target)) return null;
return target;
}
/** The terminal marker line a wal-gap close appends (fresh timestamp). */
function interruptedMarkerLine(): string {
return (
JSON.stringify({
phase: WORKRUN_PHASE.interrupted,
at: new Date().toISOString(),
reason: "closed by doctor --repair",
}) + "\n"
);
}
/** Separator before an appended marker on a file not ending in a newline. */
function danglingClosePrefix(existing: string): string {
return existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
}
const walGapFixer: Fixer = {
code: REPAIR_CODE.walGap,
coversDoctorCode: "dangling-workrun",
plan(vault: string, findings: ReadonlyArray<DoctorIssue>): RepairItem[] {
return findings.map((issue) => {
if (issue.path === undefined) throw new MalformedDoctorFindingError(issue.code, "path");
const rel = vaultRelative(issue.path, vault);
return {
code: REPAIR_CODE.walGap,
target: rel,
applicable: true,
detail: `close dangling workrun ${rel} with a terminal 'interrupted' marker`,
};
});
},
preview(vault: string, item: RepairItem): { before: string; after: string } | null {
const path = join(vault, item.target);
if (!existsSync(path)) return null;
const existing = readFileSync(path, "utf8");
return {
before: existing,
after: existing + danglingClosePrefix(existing) + interruptedMarkerLine(),
};
},
apply(vault: string, item: RepairItem): AppliedFix | null {
const path = join(vault, item.target);
if (!existsSync(path)) return null;
let handle: ReturnType<typeof acquireLockSync>;
try {
handle = acquireLockSync(path);
} catch {
return null; // contended: leave for a later run
}
try {
// Re-check under the lock so two concurrent repairs cannot both observe
// the run as dangling and append duplicate terminal markers (idempotent).
if (!scanDanglingWorkruns(vault).some((p) => vaultRelative(p, vault) === item.target)) {
return null;
}
const existing = readFileSync(path, "utf8");
appendFileSync(path, danglingClosePrefix(existing) + interruptedMarkerLine(), "utf8");
return {
code: item.code,
target: item.target,
detail: item.detail,
};
} finally {
handle.release();
}
},
};
/**
* The evidence prune derived in memory: the parsed frontmatter and body
* plus the pruned replacements. One derivation shared by the consent
* preview (which formats both sides into a diff) and the apply path
* (which writes the pruned side under its lock), so the two cannot
* drift. `null` on a page without a list-shaped `_evidenced_by` or when
* nothing would change (idempotent no-op).
*/
function evidencePruneDerived(
vault: string,
path: string,
dead: string,
): { meta: FrontmatterMap; body: string; next: FrontmatterMap; nextBody: string } | null {
const [meta, body] = parseFrontmatter(path);
const arr = meta[EVIDENCED_BY_KEY];
if (!Array.isArray(arr)) return null;
const known = collectAllBasenames(vault);
const next = arr.filter((raw) => {
if (typeof raw !== "string") return true;
const broken = isBrokenBrainRef(raw, known);
return broken !== dead; // drop exactly the still-dead target
});
if (next.length === arr.length) return null; // idempotent no-op
return {
meta,
body,
next: { ...meta, [EVIDENCED_BY_KEY]: next },
nextBody: removeOriginBullet(body, dead),
};
}
const orphanedReferenceFixer: Fixer = {
code: REPAIR_CODE.orphanedReference,
coversDoctorCode: "broken-wikilink",
plan(vault: string, findings: ReadonlyArray<DoctorIssue>): RepairItem[] {
const items: RepairItem[] = [];
for (const issue of findings) {
if (issue.path === undefined) throw new MalformedDoctorFindingError(issue.code, "path");
if (issue.field === undefined) throw new MalformedDoctorFindingError(issue.code, "field");
if (issue.target === undefined) throw new MalformedDoctorFindingError(issue.code, "target");
// The doctor reports every unresolvable basename; only Brain-managed
// ids are this fixer's business. An external / non-Brain link is
// left exactly where it is, as it always was.
if (!isBrainArtifactId(issue.target)) continue;
const rel = vaultRelative(issue.path, vault);
items.push(
issue.field === DOCTOR_EVIDENCE_FIELD
? evidencePrune(rel, issue.target)
: structuralReview(rel, issue.field, issue.target),
);
}
return items;
},
preview(vault: string, item: RepairItem): { before: string; after: string } | null {
const [rel, field, dead] = item.target.split(TARGET_SEP);
if (rel === undefined || field !== EVIDENCED_BY_KEY || dead === undefined) return null;
const path = join(vault, rel);
if (!existsSync(path)) return null;
const derived = evidencePruneDerived(vault, path, dead);
if (derived === null) return null;
// M5: `before` is the file's raw bytes, not a re-serialization of the
// parsed frontmatter. The write lands `formatFrontmatter(next)`, whose
// normalization (de-quoting scalars, the blank line after the closing
// fence) is invisible in a diff whose both sides were formatted - so
// the operator approved a two-line change and got a fourth one. The
// raw before against the formatted after shows every byte the write
// moves, which is the preview's contract.
return {
before: readFileSync(path, "utf8"),
after: formatFrontmatter(derived.next, derived.nextBody),
};
},
apply(vault: string, item: RepairItem): AppliedFix | null {
const [rel, field, dead] = item.target.split(TARGET_SEP);
if (rel === undefined || field !== EVIDENCED_BY_KEY || dead === undefined) return null;
const path = join(vault, rel);
if (!existsSync(path)) return null;
let handle: ReturnType<typeof acquireLockSync>;
try {
handle = acquireLockSync(path);
} catch {
return null; // contended: leave for a later run
}
try {
const derived = evidencePruneDerived(vault, path, dead);
if (derived === null) return null; // unreadable list or idempotent no-op
// Keep the human `## Origin` prose consistent: drop the matching
// `- [[dead]]` bullet so the same dead target cannot re-surface as a
// body-side broken-backlink after the frontmatter is pruned.
writeFrontmatterAtomic(path, derived.next, derived.nextBody, { overwrite: true });
return { code: item.code, target: item.target, detail: item.detail };
} finally {
handle.release();
}
},
};
function evidencePrune(rel: string, dead: string): RepairItem {
return {
code: REPAIR_CODE.orphanedReference,
target: [rel, EVIDENCED_BY_KEY, dead].join(TARGET_SEP),
applicable: true,
detail: `prune orphaned evidence [[${dead}]] from ${rel}`,
};
}
function structuralReview(rel: string, field: string, dead: string): RepairItem {
return {
code: REPAIR_CODE.orphanedReference,
target: [rel, field, dead].join(TARGET_SEP),
applicable: false,
detail: `${rel} has a broken '${field}' link [[${dead}]]`,
reason:
"removing a structural lifecycle link would drop provenance or break a required field; " +
"reconcile it manually",
};
}
/**
* Remove every `- [[<dead>...]]` bullet from a preference/retired body so
* the `## Origin` prose stops naming a target the frontmatter no longer
* references. Only bullet lines whose wikilink normalises to `dead` are
* dropped; all other body content is preserved verbatim.
*/
function removeOriginBullet(body: string, dead: string): string {
const lines = body.split("\n");
let inOrigin = false;
const kept = lines.filter((line) => {
// Track section boundaries so a matching bullet outside `## Origin` (in
// Notes, How-to-apply, or any other section) is never dropped.
if (/^#{1,6}\s+/.test(line)) {
inOrigin = /^##\s+Origin\s*$/.test(line);
return true;
}
if (!inOrigin) return true;
const m = /^\s*-\s+(\[\[.+?\]\])\s*$/.exec(line);
if (!m) return true;
return normaliseWikilinkTarget(m[1]!) !== dead;
});
return kept.join("\n");
}
const FIXERS: ReadonlyArray<Fixer> = Object.freeze([walGapFixer, orphanedReferenceFixer]);
const FIXER_BY_CODE: ReadonlyMap<string, Fixer> = new Map(FIXERS.map((f) => [f.code, f]));
const COVERED_DOCTOR_CODES: ReadonlySet<string> = new Set(FIXERS.map((f) => f.coversDoctorCode));
/**
* The classes this module's fixers repair, as a read-only set. Exported
* so the applier capability table can be checked against the registry
* that actually decides (no-dead-ends, task 8) rather than against a
* hand-maintained copy of it.
*/
export const REPAIR_FIXER_CODES: ReadonlySet<string> = Object.freeze(
new Set(FIXERS.map((f) => f.code)),
);
// ----- Planner --------------------------------------------------------------
export interface PlanRepairOptions {
/**
* The doctor findings to derive the plan from. Omitted, `planRepair`
* runs the doctor itself, which is what every production caller does.
*
* Supplying them is how a caller that has ALREADY run the doctor avoids
* a second full pass, and it is the seam that makes the derivation
* observable: hand in findings that do not match the disk and the plan
* follows the findings, which is the property a re-scanning planner
* cannot have.
*/
readonly issues?: ReadonlyArray<DoctorIssue>;
/**
* The pages the caller may read, when the doctor runs here (no
* {@link issues} supplied). The checks then count and cap over those
* pages only, as `runDoctor` does with the same option. Absent, every
* page counts.
*/
readonly readable?: (rel: string) => boolean;
/**
* The search-index path, when the doctor runs here, for its index-backed
* checks (`tier-drift`, `freshen-failing`). Absent, those checks skip,
* as they do in `runDoctor`.
*/
readonly dbPath?: string;
}
/**
* Preview what a repair would do. Pure read.
*
* The plan is DERIVED FROM the doctor's findings (no-dead-ends, task 9).
* Each fixer is handed exactly the findings carrying the doctor code it
* covers and derives its items from those; it does not scan for work of
* its own. Before this, every fixer re-scanned the vault independently
* while the doctor's findings sat beside them consulted only for counts,
* so the applier shared the detector's vocabulary without consuming its
* output and nothing forced the two to agree.
*
* The remaining classes - the ones no fixer covers - are aggregated from
* the same findings, each with its next-command hint.
*/
export function planRepair(vault: string, opts: PlanRepairOptions = {}): RepairPlan {
const issues = opts.issues ?? collectDoctorIssues(vault, opts.readable, opts.dbPath, false);
const fixes: RepairItem[] = [];
for (const fixer of FIXERS) {
fixes.push(
...fixer.plan(
vault,
issues.filter((i) => i.code === fixer.coversDoctorCode),
),
);
}
const counts = new Map<string, number>();
for (const issue of issues) {
if (COVERED_DOCTOR_CODES.has(issue.code)) continue;
counts.set(issue.code, (counts.get(issue.code) ?? 0) + 1);
}
const unfixable: UnfixableClass[] = [...counts.entries()]
.map(([code, count]) => {
const sig = resolveSignal(code);
return {
code,
issueClass: sig.issueClass,
count,
nextCommand: sig.nextCommand,
};
})
.toSorted((a, b) => a.code.localeCompare(b.code));
return Object.freeze({ fixes: Object.freeze(fixes), unfixable: Object.freeze(unfixable) });
}
/** The doctor's errors and warnings as one stream, in report order. */
function collectDoctorIssues(
vault: string,
readable: ((rel: string) => boolean) | undefined,
dbPath: string | undefined,
withholdsPrivate: boolean,
): ReadonlyArray<DoctorIssue> {
const doctor = runDoctor(vault, {
...(readable !== undefined ? { readable } : {}),
...(dbPath !== undefined ? { dbPath } : {}),
withholdsPrivate,
});
return [...doctor.errors, ...doctor.warnings];
}
// ----- Apply ----------------------------------------------------------------
export interface AppliedFix {
readonly code: string;
readonly target: string;
readonly detail: string;
/** Absolute path of the log file the typed event landed in (apply only). */
readonly logPath?: string;
/**
* Unified diff of the fix, rendered by the shared core leaf against
* the fixer's consent preview (t_b6bcd984). Dry-run only: it shows
* what `--apply` would write. Absent when the fixer cannot draw one.
*/
readonly diff?: string;
}
/**
* How a repair write was authorised, recorded verbatim in each
* doctor-repair event body (t_b6bcd984). The CLI passes `yes-flag` for
* an explicit `--yes` and `interactive-yes` for a confirmed y/N prompt;
* the MCP tool passes `caller-apply` - `apply: true` is the machine
* consent, and no new required argument is added to the tool. A dry run
* writes no event, so it records nothing.
*
* `unchanged` (M3) is the no-op verdict: the run had nothing to apply, so
* no gate ran, nobody was asked and nothing was written. It never reaches
* an event body - a no-op logs none - and rides only the run-level
* {@link RepairOutcome.consent}, where the hard-coded absence (or a
* stale carried verdict) would otherwise report a consent nobody gave.
*/
export type RepairConsent = "yes-flag" | "interactive-yes" | "caller-apply" | "unchanged";
/**
* The two reserved refusal verdicts (CONSENT_VERDICTS in src/core/trust.ts):
* an interactive operator answered no (`refused`), and a `--json`/non-TTY
* run was refused fail-closed for want of `--yes` (`headless-refused`).
* Under `--json` the guarded CLI lanes emit their refusal as a JSON
* envelope `{ consent, written: false, error }` carrying one of these, so
* a headless consumer reads the verdict from the payload stream.
*/
export const REFUSAL_VERDICTS = ["refused", "headless-refused"] as const;
export type RefusalVerdict = (typeof REFUSAL_VERDICTS)[number];
/**
* Every verdict a guarded CLI lane's receipt may carry: the consent
* values ({@link RepairConsent}) plus the two refusal spellings. The
* vocabulary is one set across install, protect, unprotect and doctor so
* a receipt from any lane reads the same way.
*/
export type LaneConsentVerdict = RepairConsent | RefusalVerdict;
export interface RepairOutcome {
readonly dryRun: boolean;
/** Fixes that were (or, under dry-run, would be) applied. */
readonly applied: ReadonlyArray<AppliedFix>;
/** Detected-but-needs-review instances a fixer will not touch. */
readonly needsReview: ReadonlyArray<RepairItem>;
/** Detected classes no fixer addresses. */
readonly unfixable: ReadonlyArray<UnfixableClass>;
/**
* How the write was authorised (M4): every apply's JSON carries the
* consent verdict, exactly as each fix's event body does. Absent on a
* dry run, which writes nothing and records nothing. A no-op apply -
* nothing to fix, so no consent was consumed - reports `unchanged`
* rather than the caller's verdict, keeping a confirmed write
* distinguishable from an automatic run.
*/
readonly consent?: RepairConsent;
}
export interface ApplyRepairOptions {
/** True previews without writing; false performs the fixes. */
readonly dryRun: boolean;
/**
* How the write was authorised ({@link RepairConsent}). Recorded in
* each doctor-repair event body; absent on internal callers, which
* keeps the event's old shape.
*/
readonly consent?: RepairConsent;
/**
* The targets the consent preview showed (t_b6bcd984; the CLI's pin
* between the approved preview and the write, M6 - the sibling of the
* protect/unprotect PREVIEW_DRIFT refusal). Present, the apply skips
* any applicable fix whose target the preview did not name: a finding
* that appears between the operator's preview and their yes stays for
* the next run instead of being written behind an approval that never
* showed it. Absent, every planned fix applies - the pre-pin callers.
*/
readonly approvedTargets?: ReadonlyArray<string>;
/** Wall clock for the typed event timestamps. Defaults to `new Date()`. */
readonly now?: Date;
/** Agent identity recorded on each event. Resolver default when blank. */
readonly agent?: string;
/** Config path for the agent-name resolver. */
readonly configPath?: string;
/**
* Owner scope the repair is bounded by (a-label-is-not-a-boundary,
* U3). Absent / `null` repairs everything, which is what the CLI and
* every pre-gate caller get.
*
* Bounds the PLAN, not the report. `toolBrainDoctor` filters the
* diagnostic streams it returns, and the repair branch returned before
* reaching that filter - so a caller scoped to one owner both read and
* REWROTE another owner's preferences, pruning their frontmatter and
* logging a `doctor-repair` event for each. Filtering the outcome
* afterwards would have hidden the second half while still doing it.
*/
readonly ownerScope?: string | null;
/**
* The reach the caller's transport minted. Present, a record the
* caller cannot read at that reach is absent from the plan: no fix, no
* needs-review item and no unfixable count is derived from it, and
* nothing is written to it. Absent means no transport is involved (the
* CLI) and only {@link ownerScope} bounds the plan.
*/
readonly reach?: TransportReach;
/**
* The pages the caller may read at {@link reach}. The doctor's checks
* count and cap over these pages before any finding exists to filter:
* a withheld page spends no slot of a capped warning and a withheld
* principle adds no concept gap, so the unfixable counts match a vault
* that never held them. Absent, every page counts.
*/
readonly readable?: (rel: string) => boolean;
/**
* The search-index path for the doctor's index-backed checks, so the
* plan lists `tier-drift` and `freshen-failing` as the report does.
* Absent, those checks skip.
*/
readonly dbPath?: string;
}
/** The fields a doctor finding names artifacts in. */
export interface DoctorIssueNaming {
readonly message: string;
readonly path?: string;
readonly target?: string;
readonly sources?: ReadonlyArray<string>;
}
/**
* Every artifact one doctor finding names: its page (vault-relative when
* inside the vault), its target, the referencing sources, and the
* wikilinks its message spells. The semantic-health codes carry no
* structured target and name their subjects inside the message as
* `[[pref-x]]`; they are read through the shared wikilink lexer, a
* structural read of link syntax rather than a match on prose. A finding
* survives a view only when every reference passes it. A record id - the
* target, an id-shaped source, a message wikilink - is asked under every
* spelling it answers to ({@link recordRefs}), so a broken backlink to
* `pref-x` names the reserved `ret-x` it became.
*/
export function doctorIssueRefs(
vault: string | null,
issue: DoctorIssueNaming,
): ReadonlyArray<ArtifactRef> {
return [
issue.path === undefined ? undefined : vaultRelativeOrSelf(vault, issue.path),
...recordRefs(issue.target),
...(issue.sources ?? []).flatMap((source) => [source, ...recordRefs(extractId(source))]),
...extractWikilinkRichBodies(issue.message).flatMap((b) =>
recordRefs(parseWikilinkRich(b).target),
),
];
}
/** The in-vault form of a path, or the path itself when it lies outside. */
function vaultRelativeOrSelf(vault: string | null, path: string): string {
return vault !== null && pathIsInside(path, vault) ? vaultRelative(path, vault) : path;
}
/**
* Every artifact one planned fix would name.
*
* `target` is a stable identifier whose first `::` segment is the
* vault-relative page ({@link RepairItem.target}); `detail` spells the
* same page and the reference being pruned in prose, as wikilinks. Both
* are asked, because a fix that survives on one and discloses on the
* other is not filtered.
*/
function repairRefs(item: RepairItem): ReadonlyArray<string> {
const page = item.target.split("::", 1)[0]!;
return [page, ...extractWikilinkRichBodies(item.detail).map((b) => parseWikilinkRich(b).target)];
}
/**
* Run the guarded repair. `dryRun: true` returns exactly what would be
* applied and writes nothing; `dryRun: false` performs each applicable
* fix and appends one typed `doctor-repair` event per fix that actually
* changed disk. Idempotent: a second non-dry-run call finds nothing to do.
*/
export function applyRepair(vault: string, opts: ApplyRepairOptions): RepairOutcome {
// Vault-identity write guard (context-integrity-gates, Unit J), placed
// per the one rule the three appliers now share: at the entry point,
// before any other work, and only when the call will write. A dry run
// previews and writes nothing, so it stays ungated. See the write-guard
// section of `applier-capability.ts`.
if (opts.dryRun !== true) assertVaultIdentityForWrite(vault);
const owner = ownerScopeView(vault, opts.ownerScope ?? null);
const view =
opts.reach === undefined ? owner : everyArtifactRefView(owner, reachView(vault, opts.reach));
// The findings are bounded BEFORE the plan is derived from them, so the
// unfixable counts describe only records the caller may see; the fixes
// are bounded again by what each one would name, so a fix that reaches
// a withheld page through its detail is not planned either.
const plan = view.filtersNothing
? planRepair(vault, {
...(opts.readable !== undefined ? { readable: opts.readable } : {}),
...(opts.dbPath !== undefined ? { dbPath: opts.dbPath } : {}),
})
: planRepair(vault, {
issues: view.keep(
collectDoctorIssues(vault, opts.readable, opts.dbPath, view.withholdsPrivate === true),
(i) => doctorIssueRefs(vault, i),
),
});
const fixes = view.keep(plan.fixes, repairRefs);
const needsReview = fixes.filter((f) => !f.applicable);
const applicable = fixes.filter((f) => f.applicable);
if (opts.dryRun) {
const applied = applicable.map((f) => {
// The consent preview (t_b6bcd984): what this fix would write to
// the file, drawn by the fixer and rendered by the shared core
// leaf. Best-effort - a fixer that cannot draw one omits the key.
const fixer = FIXER_BY_CODE.get(f.code);
const preview = fixer?.preview?.(vault, f) ?? null;
return {
code: f.code,
target: f.target,
detail: f.detail,
...(preview === null
? {}
: { diff: renderUnifiedDiff(preview.before, preview.after, f.target) }),
};
});
return Object.freeze({
dryRun: true,
applied: Object.freeze(applied),
needsReview: Object.freeze(needsReview),
unfixable: plan.unfixable,
});
}
const agent = normalizeAgentArgument(opts.agent ?? null) ?? resolveAgentName(opts.configPath);
const timestamp = isoSecond(opts.now ?? new Date());
const approved = opts.approvedTargets === undefined ? null : new Set(opts.approvedTargets);
const applied: AppliedFix[] = [];
for (const item of applicable) {
// The approved-preview pin (M6): a fix the consent preview did not
// show is skipped, never written. It stays a finding for the next
// run - skipping (rather than refusing the whole apply, as the
// protect/unprotect PREVIEW_DRIFT twin does) keeps the answers the
// operator DID see still landing when the vault merely moved.
if (approved !== null && !approved.has(item.target)) continue;
// The capability table is the published statement that this code has
// a mechanical repair; the registry is the thing that performs it.
// Consulting the table first turns a disagreement between the two
// into a named error instead of the silent `continue` that used to
// stand here - which would have dropped an applicable item on the
// floor and still reported success.
requireMechanicalRepair(item.code);
const fixer = FIXER_BY_CODE.get(item.code);
if (fixer === undefined) throw new UnclassifiedRepairCodeError(item.code);
const result = fixer.apply(vault, item);
if (!result) continue; // idempotent no-op: nothing changed, no event
const res = appendLogEvent(vault, {
timestamp,
eventType: BRAIN_LOG_EVENT_KIND.doctorRepair,
body: {
code: result.code,
target: result.target,
detail: result.detail,
agent,
// t_b6bcd984: the receipt names how the write was authorised.
...(opts.consent === undefined ? {} : { consent: opts.consent }),
},
});
applied.push({ ...result, logPath: res.logPath });
}
return Object.freeze({
dryRun: false,
applied: Object.freeze(applied),
needsReview: Object.freeze(needsReview),
unfixable: plan.unfixable,
// The run-level verdict (M4): every apply's JSON carries how the
// write was authorised, downgraded to `unchanged` when nothing was
// written - a no-op consumed no consent, and reporting the caller's
// verdict there would make an automatic run read as a confirmed one.
...(opts.consent === undefined
? {}
: { consent: applied.length === 0 ? "unchanged" : opts.consent }),
});
}