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
27.5 KB
Raw Blame
/**
 * Brain managed-file upgrade for the release-owned files in
 * `Brain/` (`_brain.yaml`, `_BRAIN.md`), plus one narrow repair pass
 * over `preferences/`: principle frontmatter corrupted by leaked
 * tool-call fragments or escape-amplified quote chains is rewritten
 * once through `sanitisePrinciple` (token-diet, t_40eb1de7). Beyond
 * that repair, user-owned content (`preferences/`, `retired/`,
 * `inbox/`, `log/`) is never touched.
 *
 * Key design choice: `_brain.yaml` is text-walked rather than
 * re-serialised through the strict parser, because the live file
 * carries hand-written comments the parser drops. Existing values,
 * ordering, and comments stay untouched; only missing schema keys
 * and sections are appended. A malformed source surfaces as
 * `status: "error"` so `--apply` refuses to half-merge.
 */

import { existsSync, readFileSync, readdirSync } from "node:fs";
import { join } from "node:path";

import { atomicWriteFileSync, fileMatchesExpected, isFileDrift } from "../fs-atomic.ts";
import { digestVerifies, sealWithDigest } from "../integrity/digest.ts";
import { formatFrontmatter, parseFrontmatterText } from "../vault.ts";
import { sanitisePrinciple } from "./text/sanitize-principle.ts";
import { defaultConfigPath, resolveAgentName } from "../config.ts";
import { appendLogEvent } from "./log.ts";
import { brainConfigPath, brainManualPath, vaultRelative } from "./paths.ts";
import { BrainConfigError, loadBrainConfig } from "./policy.ts";
import { DEFAULT_BRAIN_CONFIG_YAML } from "./config-template.ts";
import { takeSnapshot } from "./snapshot-gate.ts";
import { manualRevisionAhead, renderBrainManualFor } from "./templates.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_SNAPSHOT_REASON } from "./types.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { storeOnlyMode } from "../store/store-only.ts";

// ----- Public types --------------------------------------------------------

export type UpgradeFileStatus = "noop" | "update" | "error";

export interface UpgradeFilePlan {
  /** Vault-relative path, e.g. `Brain/_brain.yaml`. */
  readonly path: string;
  readonly status: UpgradeFileStatus;
  /**
   * Bytes on disk when the plan was read; `null` when the file was absent.
   * An empty file is `""`, so the two states stay apart for the
   * compare-before-write check. Not carried by `noop` and `error` rows,
   * which hold `""`.
   */
  readonly before: string | null;
  /** Target bytes for the file under the current release. */
  readonly after: string;
  /**
   * Diagnostic message when `status === "error"`. Empty for `noop`
   * and `update`.
   */
  readonly error: string;
  /** Set only on a `noop` row for a file a newer template revision wrote. */
  readonly aheadRevision?: number;
}

export interface UpgradePlan {
  readonly files: ReadonlyArray<UpgradeFilePlan>;
  /** Count of `status === "update"` files. */
  readonly pending: number;
  /** Count of `status === "error"` files. */
  readonly errors: number;
  /**
   * The plan's seal (t_18fda844): the integrity module's
   * `sealWithDigest` over the rows, pending and errors above. Sealed
   * inside {@link planUpgrade} and verified at the top of
   * {@link applyUpgrade}, so a plan object edited after it was shown is
   * refused instead of applied. The body carries no wall-clock field,
   * so the same managed-file state seals identically on every run.
   */
  readonly digest: string;
}

export interface UpgradeApplyResult {
  readonly run_id: string;
  readonly snapshot_path: string;
  /** Vault-relative paths of files rewritten by this run. */
  readonly files_updated: ReadonlyArray<string>;
}

export interface ApplyUpgradeOptions {
  /**
   * The plan to apply - the one the operator was shown, or the one the
   * self-heal worker computed. Absent, `applyUpgrade` plans itself.
   */
  readonly plan?: UpgradePlan;
  readonly agent?: string;
  /** The machine config the store-only decision reads (default: the configured one). */
  readonly configPath?: string;
  readonly now?: Date;
}

export class BrainUpgradeError extends Error {
  /**
   * The `upgrade-<ts>` snapshot run id when the failure happened
   * after the pre-apply snapshot was taken. `null` for failures
   * during planning (malformed `_brain.yaml`, read errors) or a drift
   * found before the snapshot — those never wrote anything, so there
   * is nothing to roll back.
   */
  readonly runId: string | null;
  /**
   * Vault-relative paths that changed on disk after the plan was read.
   * Empty unless the run was refused for drift.
   */
  readonly drifted: ReadonlyArray<string>;

  constructor(message: string, runId: string | null = null, drifted: ReadonlyArray<string> = []) {
    super(message);
    this.name = "BrainUpgradeError";
    this.runId = runId;
    this.drifted = Object.freeze([...drifted]);
  }
}

// ----- planUpgrade ---------------------------------------------------------

/**
 * Compute the upgrade plan for `vault` without touching disk.
 *
 * Order of files in `plan.files` is fixed: `_brain.yaml`,
 * `_BRAIN.md`. This is the order the CLI renders the per-file diff
 * so the operator's eye lands at the same spot on every run.
 */
export function planUpgrade(vault: string): UpgradePlan {
  const files: UpgradeFilePlan[] = [
    planBrainYaml(vault),
    planManagedPath(
      vault,
      brainManualPath(vault),
      vaultRelative(brainManualPath(vault), vault),
      (existing) => renderBrainManualFor(vault, existing),
      manualRevisionAhead,
    ),
    ...planCorruptedPreferences(vault),
  ];
  const pending = files.filter((f) => f.status === "update").length;
  const errors = files.filter((f) => f.status === "error").length;
  return Object.freeze(sealWithDigest({ files: Object.freeze(files), pending, errors }));
}

// ----- applyUpgrade --------------------------------------------------------

/**
 * Apply every pending update of `opts.plan`, or of a fresh
 * {@link planUpgrade} when no plan is given.
 *
 * Sequence:
 *   1. Take the plan. Verify its digest against its body (t_18fda844)
 *      - a caller-supplied plan that fails the seal is refused before
 *      anything about it is trusted. Then, if `errors > 0`, throw —
 *      never touch disk when the schema source is malformed.
 *   2. If `pending === 0`, return early without taking a snapshot or
 *      appending a log row. Idempotent re-run is free.
 *   3. Check every `update` row against the disk. A file that no
 *      longer holds the bytes (or the absence) the plan read refuses
 *      the whole run, naming each path, before anything is written.
 *   4. `takeSnapshot(vault, "upgrade")`: the sidecar manifest comes
 *      along automatically and retention runs with this archive
 *      protected. The run id includes a `upgrade-` prefix
 *      so the operator can spot upgrade snapshots in `--list`.
 *   5. Write each `update` file via `atomicWriteFileSync` with
 *      `expectBefore: file.before`, so an edit that landed during the
 *      snapshot is refused at its row instead of overwritten.
 *   6. Append a `BRAIN_LOG_EVENT_KIND.upgrade` event.
 *
 * On any write failure mid-step we throw — the snapshot already
 * persisted is the recovery path (`o2b brain rollback upgrade-<ts>`).
 */
/**
 * The refusal for a caller-supplied plan whose digest no longer
 * describes its body (t_18fda844) - the seam where a plan object edited
 * after it was shown used to be trusted as-is. Distinct from the
 * byte-drift refusal below: nothing drifted ON DISK, the PLAN is what
 * failed its own seal, and the remedy is the same fresh dry run.
 */
const UPGRADE_SEAL_REFUSAL =
  "upgrade refused: the upgrade plan does not match its own digest, so the plan object was " +
  "edited or assembled after it was sealed. A plan nobody measured cannot be applied. Nothing " +
  "was written and no snapshot was taken; re-run `o2b brain upgrade --dry-run` to get a sealed " +
  "plan, then apply it.";

/**
 * The refusal on a machine that writes the brain store only (design D14
 * item 1): the managed files live in the legacy tree, which a switched
 * machine leaves exactly as it is until the tree leaves the vault, and a
 * vault with no legacy tree must not get one (it would send the machine
 * back to the legacy layout).
 */
const UPGRADE_STORE_ONLY_REFUSAL =
  "upgrade refused: this machine writes the brain store only (it has switched to the store, " +
  "or the vault has no legacy Brain/ tree), so there are no managed files to upgrade. Its " +
  "settings and records live in the store; nothing was written.";

/** {@link applyUpgrade}'s refusal on a store-only machine: no failure, nothing to upgrade. */
export class BrainUpgradeStoreOnlyError extends BrainUpgradeError {
  constructor() {
    super(UPGRADE_STORE_ONLY_REFUSAL);
    this.name = "BrainUpgradeStoreOnlyError";
  }
}

/**
 * Whether the managed-file upgrade does not apply to `vault` on this
 * machine: it writes the brain store only. A caller checks this before
 * planning or prompting, and records no upgrade failure for it.
 */
export function upgradeBlockedByStore(vault: string, configPath?: string): boolean {
  return storeOnlyMode({ vault, ...(configPath !== undefined ? { configPath } : {}) }).storeOnly;
}

export function applyUpgrade(vault: string, opts: ApplyUpgradeOptions = {}): UpgradeApplyResult {
  if (upgradeBlockedByStore(vault, opts.configPath)) throw new BrainUpgradeStoreOnlyError();
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  const plan = opts.plan ?? planUpgrade(vault);
  // The seal is checked FIRST - before the error rows, the no-op
  // return, the byte-drift check and the snapshot. A plan object that
  // fails its own digest is a plan somebody edited after it was shown;
  // its rows are not consulted at all, not even to report their errors.
  // A self-computed plan verifies trivially, so this changes nothing
  // for the caller who plans and applies in one breath.
  const { digest: _digest, ...planBody } = plan;
  if (!digestVerifies(planBody, plan.digest)) {
    throw new BrainUpgradeError(UPGRADE_SEAL_REFUSAL);
  }
  if (plan.errors > 0) {
    const messages = plan.files
      .filter((f) => f.status === "error")
      .map((f) => `${f.path}: ${f.error}`)
      .join("; ");
    throw new BrainUpgradeError(
      `upgrade aborted: ${plan.errors} file(s) failed to plan — ${messages}`,
    );
  }
  if (plan.pending === 0) {
    return Object.freeze({
      run_id: "",
      snapshot_path: "",
      files_updated: Object.freeze([] as ReadonlyArray<string>),
    });
  }

  const drifted = plan.files
    .filter((f) => f.status === "update" && !fileMatchesExpected(join(vault, f.path), f.before))
    .map((f) => f.path);
  if (drifted.length > 0) {
    throw new BrainUpgradeError(
      `upgrade refused: ${drifted.length} file(s) changed on disk since the upgrade plan ` +
        `was read: ${drifted.join(", ")}. Nothing was written and no snapshot was taken; ` +
        "re-run `o2b brain upgrade --dry-run` to review the current plan, then apply it.",
      null,
      drifted,
    );
  }

  const now = opts.now ?? new Date();
  // Through the gate, not `createSnapshot` directly: the gate is what
  // enforces `snapshots.retention_count` (with this archive protected).
  // Calling `createSnapshot` here let upgrade archives bypass retention
  // entirely; a live install that self-healed on every session start
  // held 911 of them. The gate also mints a collision-safe run id under
  // the same `upgrade-` prefix, so two applies in one second no longer
  // refuse each other.
  const snap = takeSnapshot(vault, BRAIN_SNAPSHOT_REASON.upgrade, { now });
  const runId = snap.runId;

  const updated: string[] = [];
  for (const file of plan.files) {
    if (file.status !== "update") continue;
    try {
      atomicWriteFileSync(join(vault, file.path), file.after, { expectBefore: file.before });
    } catch (err) {
      // A drift leaves the edit on disk, so its remedy must not destroy
      // it: no rollback at all, only a re-plan that reads the edit.
      if (isFileDrift(err)) {
        throw new BrainUpgradeError(midApplyDriftMessage(file.path, updated), runId, [file.path]);
      }
      // Mid-apply failure: one or more files have already been
      // rewritten under the new release, the rest still match the
      // old. The pre-apply snapshot is the recovery path — embed
      // its run id so the operator does not need to grep
      // `.snapshots/` to find it.
      throw new BrainUpgradeError(
        `upgrade aborted mid-apply at ${file.path}: ${(err as Error).message ?? String(err)}. ` +
          `${updated.length} file(s) already rewritten; ` +
          `roll back via \`o2b brain rollback ${runId} --force-rollback\` ` +
          `before re-running.`,
        runId,
      );
    }
    updated.push(file.path);
  }

  const agent = opts.agent ?? resolveAgentName(defaultConfigPathOrEmpty());
  try {
    appendLogEvent(vault, {
      timestamp: isoSecond(now),
      eventType: BRAIN_LOG_EVENT_KIND.upgrade,
      body: {
        run_id: runId,
        agent,
        snapshot: snap.path,
        files: updated,
      },
    });
  } catch (err) {
    // Audit-only failure — the files are already on disk. Surface so
    // the operator can record manually if needed.
    process.stderr.write(`warning: append upgrade log failed: ${(err as Error).message}\n`);
  }

  return Object.freeze({
    run_id: runId,
    snapshot_path: snap.path,
    files_updated: Object.freeze(updated),
  });
}

// ----- Internal helpers ----------------------------------------------------

function planBrainYaml(vault: string): UpgradeFilePlan {
  const path = brainConfigPath(vault);
  const rel = vaultRelative(path, vault);
  let before: string;
  try {
    before = readFileSync(path, "utf8");
  } catch (err) {
    const e = err as NodeJS.ErrnoException;
    if (e.code === "ENOENT") {
      // The file vanished from a `o2b brain init`-bootstrapped
      // vault. Same recovery shape as `planManagedPath`: treat
      // missing as an update from empty so `--apply` restores the
      // canonical body. Refusing here would block every other
      // managed-file update behind one missing config.
      return makeUpdate(rel, null, DEFAULT_BRAIN_CONFIG_YAML);
    }
    return makeError(rel, `read failed: ${e.message ?? String(err)}`);
  }
  // Validate the live file with the strict parser. A malformed source
  // is surfaced as `error` so the operator fixes it manually before
  // `--apply` runs — a half-merged YAML is worse than a refusal.
  try {
    loadBrainConfig(vault);
  } catch (err) {
    if (err instanceof BrainConfigError) {
      return makeError(rel, err.message);
    }
    return makeError(rel, (err as Error).message ?? String(err));
  }
  const after = mergeBrainYaml(before, DEFAULT_BRAIN_CONFIG_YAML);
  if (after === before) {
    return makeNoop(rel);
  }
  return makeUpdate(rel, before, after);
}

function planManagedPath(
  _vault: string,
  absolutePath: string,
  relPath: string,
  renderTarget: (existing: string | null) => string,
  revisionAhead: (existing: string) => number | null,
): UpgradeFilePlan {
  if (!existsSync(absolutePath)) {
    // File missing entirely: an upgrade should restore it. Treat as
    // update from absent (`null`) so the diff shows the full body.
    return makeUpdate(relPath, null, renderTarget(null));
  }
  let before: string;
  try {
    before = readFileSync(absolutePath, "utf8");
  } catch (err) {
    return makeError(relPath, `read failed: ${(err as Error).message}`);
  }
  // A synced file from a newer release is never rewritten back: devices on
  // two releases otherwise rewrote it in turn, a snapshot each time.
  const ahead = revisionAhead(before);
  if (ahead !== null) return Object.freeze({ ...makeNoop(relPath), aheadRevision: ahead });
  // The target is rendered against what is on disk, so a rendering that
  // may legitimately keep an existing spelling (the vault name on a
  // case-insensitive filesystem) can.
  const after = renderTarget(before);
  if (before === after) {
    return makeNoop(relPath);
  }
  return makeUpdate(relPath, before, after);
}

function makeNoop(path: string): UpgradeFilePlan {
  // `noop` rows never expose `before` / `after` bodies — the CLI
  // diff renderer and JSON output only consult `.length`/`.status`
  // for noops, so carrying the full file body here would waste memory
  // on every plan invocation (planUpgrade is read-only and may be
  // called from JSON/CI paths repeatedly).
  return Object.freeze({
    path,
    status: "noop" as const,
    before: "",
    after: "",
    error: "",
  });
}

function makeUpdate(path: string, before: string | null, after: string): UpgradeFilePlan {
  return Object.freeze({
    path,
    status: "update" as const,
    before,
    after,
    error: "",
  });
}

function makeError(path: string, message: string): UpgradeFilePlan {
  return Object.freeze({
    path,
    status: "error" as const,
    before: "",
    after: "",
    error: message,
  });
}

/**
 * The refusal for a row that changed on disk during the apply. The next
 * plan reads the edit, so a fresh dry run is the only way forward offered.
 * A rollback is not: the snapshot manifest predates the apply, so plain
 * rollback reports every rewritten row as drift and exits, and
 * `--force-rollback` would destroy the edit.
 */
function midApplyDriftMessage(drifted: string, updated: ReadonlyArray<string>): string {
  const head =
    `upgrade refused at ${drifted}: the file changed on disk after the upgrade plan was ` +
    "read and was left as it is.";
  if (updated.length === 0) {
    return (
      `${head} Nothing was written; re-run \`o2b brain upgrade --dry-run\` to review a ` +
      "plan that reads the edit, then apply it."
    );
  }
  return (
    `${head} ${updated.length} file(s) already rewritten: ${updated.join(", ")}. ` +
    "Re-run `o2b brain upgrade --dry-run` to plan the rest against the edit, then apply it."
  );
}

/**
 * `applyUpgrade` is callable from tests that may not have set up a
 * real plugin config. Fall back to an empty path string so
 * `resolveAgentName` returns its built-in default rather than
 * throwing on a missing file.
 */
function defaultConfigPathOrEmpty(): string {
  try {
    return defaultConfigPath();
  } catch {
    return "";
  }
}

// ----- `_brain.yaml` text-level merge --------------------------------------

/**
 * Append missing top-level sections / scalars and missing nested keys
 * from `target` (the default YAML the current release ships) into a
 * copy of `live` (the user's current file). Existing values are
 * never rewritten; comments and ordering are preserved.
 *
 * Algorithm:
 *   1. Walk `target` block-by-block. A top-level section is a key
 *      followed by `:` at column 0; a top-level scalar is a key
 *      followed by `: <value>` at column 0.
 *   2. For each top-level scalar in `target`: if the same key
 *      appears at column 0 in `live`, leave it alone. Otherwise
 *      append the line at end-of-file.
 *   3. For each top-level section in `target`: if the section
 *      header is absent from `live`, append the whole block
 *      (header + indented body + leading comment block, if any) at
 *      end-of-file. If present, compute the missing nested keys
 *      (keys present in the target's block but absent in live's
 *      block) and insert each missing line at the end of the live
 *      block.
 *
 * The merge is purely additive — we never delete, reorder, or
 * rewrite. Comment-only lines and blank lines from `target` are
 * carried along with their adjacent section so the inserted block
 * reads the same as the canonical template.
 */
export function mergeBrainYaml(live: string, target: string): string {
  const targetBlocks = parseYamlBlocks(target);
  const liveBlocks = parseYamlBlocks(live);
  const liveByName = new Map(liveBlocks.map((b) => [b.name, b]));
  const liveScalars = new Set(liveBlocks.filter((b) => b.kind === "scalar").map((b) => b.name));
  const liveSections = new Map(
    liveBlocks.filter((b) => b.kind === "section").map((b) => [b.name, b] as const),
  );

  let result = live;
  // Pass 1: append missing top-level scalars / sections.
  for (const tb of targetBlocks) {
    if (tb.kind === "scalar" && !liveScalars.has(tb.name)) {
      result = appendBlockAtEnd(result, tb.text);
    } else if (tb.kind === "section" && !liveSections.has(tb.name)) {
      result = appendBlockAtEnd(result, tb.text);
    }
  }

  // Pass 2: for each section present in both, splice missing nested
  // keys into the existing live block.
  for (const tb of targetBlocks) {
    if (tb.kind !== "section") continue;
    const live = liveByName.get(tb.name);
    if (!live || live.kind !== "section") continue;
    const liveKeys = new Set(live.nestedKeys);
    // Only consider lines that are real key declarations. Blank
    // lines and comment lines return an empty `extractKey`, which
    // would otherwise look "missing from liveKeys" and inflate the
    // diff with whitespace.
    const missing = tb.nestedLines.filter((line) => {
      const key = extractKey(line);
      return key.length > 0 && !liveKeys.has(key);
    });
    if (missing.length === 0) continue;
    result = insertLinesAtSectionEnd(result, tb.name, missing);
  }

  return result;
}

interface YamlBlock {
  readonly kind: "scalar" | "section" | "comment";
  /** Identifier key for scalar/section; `""` for comment-only block. */
  readonly name: string;
  /** Block source text including trailing newline. */
  readonly text: string;
  /** Lines under a section (indented), in source order. Empty for scalar / comment. */
  readonly nestedLines: ReadonlyArray<string>;
  /** Convenience: keys extracted from `nestedLines` (one per indented key line). */
  readonly nestedKeys: ReadonlyArray<string>;
}

function parseYamlBlocks(yaml: string): YamlBlock[] {
  const lines = yaml.split("\n");
  const blocks: YamlBlock[] = [];
  let i = 0;
  // Buffer comment / blank lines so they attach to the next block
  // header — that way an inserted section copies its leading
  // commentary verbatim.
  let preface: string[] = [];
  while (i < lines.length) {
    const line = lines[i]!;
    if (line.trimEnd() === "" || /^\s*#/.test(line)) {
      preface.push(line);
      i++;
      continue;
    }
    const m = /^([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(line);
    if (m && !line.startsWith(" ") && !line.startsWith("\t")) {
      const key = m[1]!;
      const rest = m[2]!;
      const trimmedRest = rest.trim();
      // Scalar: `key: value`. Section: `key:` (rest is empty after
      // colon) followed by indented continuation.
      if (trimmedRest === "") {
        // Section header. Consume continuation lines (indented or blank).
        const start = i;
        i++;
        const nestedLines: string[] = [];
        while (i < lines.length) {
          const next = lines[i]!;
          if (next.startsWith(" ") || next.startsWith("\t")) {
            nestedLines.push(next);
            i++;
            continue;
          }
          if (next.trim() === "") {
            // Trailing blank line belongs to the section block.
            nestedLines.push(next);
            i++;
            // The next non-blank determines whether we are still
            // inside the section.
            if (i < lines.length && !/^[ \t]/.test(lines[i]!)) break;
            continue;
          }
          break;
        }
        const text = [...preface, lines[start]!, ...nestedLines].join("\n") + "\n";
        preface = [];
        blocks.push({
          kind: "section",
          name: key,
          text,
          nestedLines: nestedLines.filter((l) => l.trim() !== ""),
          nestedKeys: nestedLines.filter((l) => /^\s+[A-Za-z_]/.test(l)).map(extractKey),
        });
        continue;
      }
      // Scalar at column 0.
      const text = [...preface, line].join("\n") + "\n";
      preface = [];
      blocks.push({
        kind: "scalar",
        name: key,
        text,
        nestedLines: [],
        nestedKeys: [],
      });
      i++;
      continue;
    }
    // Unrecognised top-level line (e.g. a stray non-key). Treat as
    // commentary so we never silently drop it.
    preface.push(line);
    i++;
  }
  if (preface.length > 0) {
    blocks.push({
      kind: "comment",
      name: "",
      text: preface.join("\n") + (preface.at(-1) === "" ? "" : "\n"),
      nestedLines: [],
      nestedKeys: [],
    });
  }
  return blocks;
}

function extractKey(indentedLine: string): string {
  const m = /^\s+([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(indentedLine);
  return m ? m[1]! : "";
}

function appendBlockAtEnd(yaml: string, block: string): string {
  // Ensure exactly one blank line between the existing content and
  // the new block, and exactly one trailing newline overall.
  const trimmedTail = yaml.replace(/\s+$/, "");
  const trimmedBlock = block.replace(/\s+$/, "");
  return `${trimmedTail}\n\n${trimmedBlock}\n`;
}

function insertLinesAtSectionEnd(
  yaml: string,
  sectionName: string,
  newLines: ReadonlyArray<string>,
): string {
  const lines = yaml.split("\n");
  const header = `${sectionName}:`;
  const headerIdx = lines.findIndex(
    (l) => l === header || l.startsWith(`${header} `) || l === header.trimEnd(),
  );
  if (headerIdx === -1) {
    // Section not in live (shouldn't happen given the caller guard);
    // append the lines at end-of-file as a fallback.
    return appendBlockAtEnd(yaml, newLines.join("\n"));
  }
  // Find the end of the section: first column-0 non-blank line after
  // the header.
  let end = headerIdx + 1;
  while (end < lines.length) {
    const l = lines[end]!;
    if (l !== "" && !/^[ \t]/.test(l)) break;
    end++;
  }
  // Insert the new keys right before `end`, after stripping any
  // trailing blank lines inside the section so the inserted lines
  // land flush with the existing keys.
  let insertAt = end;
  while (insertAt > headerIdx + 1 && lines[insertAt - 1]!.trim() === "") {
    insertAt--;
  }
  const before = lines.slice(0, insertAt);
  const after = lines.slice(insertAt);
  return [...before, ...newLines, ...after].join("\n");
}

// ----- Corrupted preference repair (token-diet, t_40eb1de7) ----------------

/**
 * One narrow, idempotent repair over `Brain/preferences/`: rewrite
 * files whose `principle` frontmatter still carries leaked tool-call
 * fragments or escape-amplified quote chains (written before the
 * write-seam sanitizer and the frontmatter unescape fix shipped).
 *
 * The rewrite goes through the raw frontmatter map - not the typed
 * preference parser - so every other field round-trips through the
 * same `formatFrontmatter` the writers use and unknown keys survive
 * verbatim. Files that fail to parse, or whose principle is already
 * clean, are left untouched; on the pass after the repair the plan is
 * empty again.
 */
function planCorruptedPreferences(vault: string): UpgradeFilePlan[] {
  const dir = join(vault, "Brain", "preferences");
  if (!existsSync(dir)) return [];
  const plans: UpgradeFilePlan[] = [];
  for (const name of readdirSync(dir).toSorted()) {
    if (!name.endsWith(".md")) continue;
    const abs = join(dir, name);
    const rel = `Brain/preferences/${name}`;
    let before: string;
    try {
      before = readFileSync(abs, "utf8");
    } catch {
      continue; // unreadable file is doctor's domain, not upgrade's
    }
    const [meta, body] = parseFrontmatterText(before);
    const principle = meta["principle"];
    if (typeof principle !== "string") continue;
    const repaired = sanitisePrinciple(principle);
    if (repaired === principle || repaired.length === 0) continue;
    const after = formatFrontmatter({ ...meta, principle: repaired }, body);
    if (after === before) continue;
    plans.push(
      Object.freeze({
        path: rel,
        status: "update" as const,
        before,
        after,
        error: "",
      }),
    );
  }
  return plans;
}