Skip to content

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

TypeScript
84.7 KB
Raw Blame
/**
 * 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 }),
  });
}