Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
44.7 KB
Raw Blame
/**
 * `gbrain repair fences` (#6188): repairs malformed facts and takes fences
 * that sync held, that pages store, or that a checkout holds unsynced.
 *
 * Candidates come from the fence census (holds, stored pages, files), after
 * a bounded census scan; `--only <path>` and `--slug <slug>` also reach a
 * file or page the census has not judged yet. Per candidate the current
 * bytes are re-read and the free tiers run first (Tier 1 rules, then Tier 2
 * holder names verified against `people/` and `companies/` pages); a
 * candidate whose only residuals are rows a model can realign goes to Tier 3
 * (fence-repair/llm.ts) at apply time, under `fences.repair.llm`, the
 * per-page and daily caps (`fences.repair.max_usd_per_page` / `_per_day`,
 * the daily USD ledger) and any lower `--max-usd`, with the attempt memo so
 * an unchanged rejected file never costs twice. Every proposal passes gates
 * (a)-(g) and is a Tier 1 fixed point before it is written
 * (fence-repair/repair-io.ts has the four write-back paths).
 *
 * Preview (no --apply) is read-only and calls no model: per candidate the
 * planned tier, rows and classes, the exact diff for Tier 1/2 (one sample
 * per tier; all with --diff or --json), the estimated model cost against the
 * day's remaining cap, and a preview hash bound to the selection.
 * `--apply --expect <hash>` applies exactly that set (`changed_since_preview`
 * for anything whose bytes or revision moved); a bare `--apply` (from
 * `--all`, `doctor --remediate`, the maintenance cycle) applies the current
 * plan, rotating its start so a backlog under a time budget is not starved.
 *
 * Per-item outcomes: `repaired` (detail: tier, classes, mode, path or slug),
 * `held` (reason: a FenceReason; the hold records it for the surfaces), or
 * `skipped` (an owner reason: host_mismatch, transfer_in_progress,
 * clone_in_progress, incarnation_changed, local_path_missing,
 * coordination_path_missing, or owner_unavailable; sync_in_progress,
 * changed_since_read, changed_since_preview, claimed_elsewhere,
 * already_clean). A source whose sync is running is not skipped as a whole:
 * only the candidates a write in flight or the sync's frozen manifest still
 * names are `sync_in_progress`, and the busy set is read again at apply and
 * at the write's admission (#6278). When the daily
 * ledger refuses a call the run stops with `budget_exhausted` (D15). The
 * result adds `repaired`, `remaining` by reason, `scan` and `verification`;
 * a run whose every model proposal is rejected reports 0 repaired.
 */
import type { BrainEngine } from '../engine.ts';
import type { OperationContext } from '../ops/contract.ts';
import { trustedCliRequired } from '../ops/op-fix.ts';
import { shellQuote, type Action } from '../agent-output.ts';
import { parseMarkdown } from '../markdown.ts';
import { FENCE_REPAIR_MEASURED_MODELS } from '../fence-repair/measured.ts';
import { FENCE_REPAIR_MODEL_KEY, resolveFenceRepairModel } from '../fence-repair/model.ts';
import { loadPricingOverrides } from '../budget/budget-tracker.ts';
import { dailyLedger, FENCE_REPAIR_LEDGER, nextUtcMidnight } from '../budget/daily-ledger.ts';
import { pricingSetCommand } from '../budget/no-pricing.ts';
import type { CapSource } from '../consent.ts';
import { sha256 } from '../persistence/digest.ts';
import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { readGitSourceHolds, recordFenceHoldRepair } from '../persistence/sync-holds.ts';
import { attemptStore } from '../fence-repair/attempts.ts';
import { listFenceCandidates, runFenceCensus, type FenceCandidate } from '../fence-repair/census.ts';
import { fenceRepairLlmEnabled, readFenceRepairCaps } from '../fence-repair/config.ts';
import { mergedReceipt } from '../fence-repair/merge.ts';
import { FENCE_REASONS } from '../fence-repair/reasons.ts';
import { FENCE_REPAIR_ACTOR, type MergedFenceReceipt } from '../fence-repair/receipt.ts';
import { checkoutFileExists, loadFenceSource, pageSha, readFenceTarget, spliceFileSections, writeFenceRepair, type FenceRepairMode, type FenceSource, type FenceTarget } from '../fence-repair/repair-io.ts';
import type { OwnerRefusal } from '../persistence/owner-refusal.ts';
import { repairBusy, repairBusyMessage } from '../persistence/repair-busy.ts';
import { analyzeFences, attemptCandidate, runTier3, tier3Estimate, tier3Memo, type AnalyzeOpts, type FenceAnalysis } from '../fence-repair/repair-tiers.ts';
import type { FenceFix, FenceIssue, FencePage, FenceReason, FenceTier, GateLetter } from '../fence-repair/types.ts';
import { lineDiff } from './frontmatter.ts';
import type { RepairHandler, RepairItem, RepairItemOutcome, RepairListing, RepairPlan, RepairPlanOptions, RepairResult, RepairScope } from './core.ts';
import { rotate, rotationAfter, rotationBrain, rotationKeyOf, saveRotation } from './rotation.ts';

/** The fences result's `verification` (report hook): what the run did and what is left, for the CLI and the cycle phase report. */
export interface FenceRepairVerification {
  /** Candidates the plan found (after selection). */
  candidates: number;
  repaired_by_tier: Record<Exclude<FenceTier, 'manual'>, number>;
  /** Candidates still waiting after the run, by reason (manual-only residuals, gates, budget, ...). */
  held_by_reason: Record<string, number>;
  /** Oldest unresolved `invalid_fence` hold in scope (ISO), or null. */
  oldest_hold_at: string | null;
  /** Successful Tier 3 repairs in this run and the USD per repair (null when none). */
  llm_repairs: number;
  llm_usd_per_repair: number | null;
  /** The scan behind the plan did not finish. */
  partial: boolean;
}

type RepairTier = Exclude<FenceTier, 'manual'>;
interface Selection { source_ids: string[]; only: string[]; skip: string[]; slugs: string[]; no_llm: boolean }

/** One previewed repair: everything the hash binds (location, hashes, tier), never a cell value. */
interface ApprovedFence {
  source_id: string; key: string; slug: string; path: string | null; mode: FenceRepairMode;
  before: string; revision: string | null; page_id: number | null;
  tier: RepairTier;
  /** sha256 of the repaired bytes (Tier 1/2); null for Tier 3 (rewritten at apply time). */
  after: string | null;
  classes: string[]; rows: number[]; columns: string[];
  estimate_usd: number;
  held: boolean;
  /** Model items from this one to the end of the plan (the pages a budget stop leaves waiting). */
  llm_waiting: number;
}
interface ApprovedSetItem extends ApprovedFence { selection: Selection }
interface FenceItem extends RepairItem { entry: ApprovedFence; hash: string | null; last: boolean; scan_partial: boolean }

interface FileDiff { item: string; tier: RepairTier; classes: string[]; diff: string }
interface HeldEntry { item: string; reason: string; tier: FenceTier; resolution: string; gate?: GateLetter; rows?: number[] }
export interface FencesPreviewDetails {
  counts: Record<RepairTier | 'held', number>;
  model: string | null;
  llm_enabled: boolean;
  samples: Partial<Record<RepairTier, FileDiff>>;
  diffs: FileDiff[];
  llm_items: Array<{ item: string; rows: number[]; reasons: string[]; estimate_usd: number }>;
  held: HeldEntry[];
  caps: { max_usd_per_page: number; max_usd_per_day: number; day_remaining_usd: number | null; run_max_usd: number | null };
  next_actions: Action[];
}

const SCAN_MS = () => { const n = parseInt(process.env.GBRAIN_FENCE_REPAIR_SCAN_MS ?? '', 10); return Number.isFinite(n) && n > 0 ? n : 10_000; };
const CALL_TIMEOUT_MS = () => { const n = parseInt(process.env.GBRAIN_FENCE_REPAIR_CALL_TIMEOUT_MS ?? '', 10); return Number.isFinite(n) && n > 0 ? n : 90_000; };
const ROTATION_OP = 'fence-repair-rotation';

/** Held because no measured model has a key: the exact choice the user makes. */
function noMeasuredModel(rows: readonly number[]): string {
  return `No model measured accurate enough for fence repair has a provider key here (${FENCE_REPAIR_MEASURED_MODELS.join(', ')}) and ${FENCE_REPAIR_MODEL_KEY} is unset, `
    + `so row(s) ${rows.join(', ') || '?'} stay held. Fix them by hand, or ask the user which model to trust, then: gbrain config set ${FENCE_REPAIR_MODEL_KEY} <provider:model>.`;
}

function previewArgv(scope: RepairScope, selection: Selection): string[] {
  return ['gbrain', 'repair', 'fences', ...(scope.source_ids.length === 1 ? ['--source', scope.source_ids[0]!] : []),
    ...selection.only.flatMap(path => ['--only', path]), ...selection.skip.flatMap(path => ['--skip', path]), ...selection.slugs.flatMap(slug => ['--slug', slug]),
    ...(selection.no_llm ? ['--no-llm'] : [])];
}

const itemName = (entry: Pick<ApprovedFence, 'source_id' | 'path' | 'slug'>) => `${entry.source_id}:${entry.path ?? entry.slug}`;

function fixLocation(fixes: readonly FenceFix[], residual: readonly FenceIssue[]) {
  const all = [...fixes, ...residual];
  return { rows: [...new Set(all.flatMap(f => f.row === null ? [] : [f.row]))].sort((a, b) => a - b).slice(0, 200),
    columns: [...new Set(all.flatMap(f => f.column === null ? [] : [f.column]))].sort().slice(0, 40) };
}

function classesOf(fixes: readonly FenceFix[], cleared: readonly string[] = []): string[] {
  return [...new Set([...fixes.map(f => f.class), ...cleared])].sort();
}

/** The repaired bytes as the hash binds them: the spliced file, or the page's two sections. */
function afterBytes(target: FenceTarget, after: FencePage): { sha: string; text: string } | null {
  if (target.content !== null && target.path) {
    const content = spliceFileSections(target.content, target.path, target.page, after);
    return content === null ? null : { sha: sha256(Buffer.from(content, 'utf8')), text: content };
  }
  return { sha: pageSha(after), text: `${after.compiled_truth}\n${after.timeline}` };
}

interface Settings {
  llmEnabled: boolean; model: string | null; overrides: Awaited<ReturnType<typeof loadPricingOverrides>>; capSource: CapSource;
  perPageUsd: number; perDayUsd: number; dayRemaining: number | null; runMaxUsd: number | null;
}

async function settings(engine: BrainEngine, opts: Pick<RepairPlanOptions, 'noLlm' | 'maxLlmUsd'>): Promise<Settings> {
  const caps = await readFenceRepairCaps(engine);
  const model = await resolveFenceRepairModel(engine);
  const day = await dailyLedger(engine, FENCE_REPAIR_LEDGER).readDay().catch(() => null);
  return { llmEnabled: !opts.noLlm && await fenceRepairLlmEnabled(engine), model, overrides: await loadPricingOverrides(engine),
    capSource: caps.perPageSource === 'user' || caps.perDaySource === 'user' || opts.maxLlmUsd !== undefined ? 'user' : 'default',
    perPageUsd: caps.perPageUsd, perDayUsd: caps.perDayUsd, dayRemaining: day ? Math.max(0, caps.perDayUsd - day.committedUsd - day.reservedUsd) : null,
    runMaxUsd: opts.maxLlmUsd ?? null };
}

/** The tier a reason's hold state records. */
function heldTier(reason: string): FenceTier {
  const spec = FENCE_REASONS[reason as FenceReason];
  return spec?.manualOnly || spec?.stage === 'gate' ? 'manual' : spec?.tier ?? 'manual';
}

async function recordHeld(engine: BrainEngine, src: FenceSource, cand: { path: string | null; held: boolean }, held: { reason: string; gate?: GateLetter; rows?: number[]; next?: string | null }): Promise<void> {
  if (!cand.held || !cand.path || !(held.reason in FENCE_REASONS)) return;
  const reason = held.reason as FenceReason;
  await recordFenceHoldRepair(engine, { sourceId: src.id, incarnation: src.incarnation, path: cand.path, state: { reason, tier: heldTier(reason), at: new Date().toISOString(),
    next_attempt_after: held.next ?? null, ...(held.gate ? { gate: held.gate } : {}), ...(held.rows?.length ? { rows: held.rows.slice(0, 50) } : {}) } }).catch(() => false);
}

/** Candidates the selection names that the census has not judged yet: a file under a source root, or a stored page. */
async function extraCandidates(engine: BrainEngine, scope: RepairScope, selection: Selection, found: readonly FenceCandidate[], sources: Map<string, FenceSource | null>): Promise<{ extra: FenceCandidate[]; unknown: string[] }> {
  const extra: FenceCandidate[] = [];
  const unknown: string[] = [];
  const base = (sourceId: string, key: string, path: string | null): FenceCandidate => ({ source_id: sourceId, key, path, page_id: null, origins: [path ? 'file' : 'page'],
    bucket: path ? 'file' : 'page', tier: 'manual', reasons: [], location: null, bound: {} });
  for (const path of selection.only) {
    if (found.some(c => c.path === path)) continue;
    const hits = scope.source_ids.filter(id => { const src = sources.get(id); return !!src?.root && checkoutFileExists(src.root, path); });
    if (!hits.length) unknown.push(`--only ${path}`);
    for (const id of hits) extra.push(base(id, `path:${path}`, path));
  }
  for (const slug of selection.slugs) {
    if (found.some(c => c.key === slug)) continue;
    const rows = await engine.executeRaw<{ source_id: string }>('SELECT source_id FROM pages WHERE slug=$1 AND source_id=ANY($2::text[]) AND deleted_at IS NULL', [slug, scope.source_ids]);
    if (!rows.length) unknown.push(`--slug ${slug}`);
    for (const row of rows) extra.push(base(row.source_id, slug, null));
  }
  return { extra, unknown };
}

function selected(cand: FenceCandidate, selection: Selection): boolean {
  if (cand.path && selection.skip.includes(cand.path)) return false;
  if (!selection.only.length && !selection.slugs.length) return true;
  return (!!cand.path && selection.only.includes(cand.path)) || selection.slugs.includes(cand.key);
}

const rotationKey = (entry: Pick<ApprovedFence, 'source_id' | 'key'>) => rotationKeyOf(entry.source_id, entry.key);

function item(entry: ApprovedFence, index: number, hash: string | null, last: boolean, partial: boolean): FenceItem {
  return { cursor: { phase: 1, id: index + 1 }, source_id: entry.source_id, slug: entry.slug, chars: 0, action: `${entry.tier}:${entry.path ?? entry.slug}`,
    ...(entry.tier === 'llm' ? { llm_usd: entry.estimate_usd } : {}), entry, hash, last, scan_partial: partial };
}

/** The hold reason of an owner refusal: the matrix reason where the fence reason table has it, else the generic `owner_unavailable`. */
function ownerReason(owner: OwnerRefusal): FenceReason {
  return owner.reason in FENCE_REASONS ? owner.reason as FenceReason : 'owner_unavailable';
}

/** The read-only fix that previews one candidate's repair again. */
const previewFix = (sourceId: string, path: string | null, slug: string): Action => ({ argv: ['gbrain', 'repair', 'fences', '--source', sourceId, ...(path ? ['--only', path] : ['--slug', slug])],
  consent: [], actor: 'agent', requires_exclusive: false, why: 'Previews this fence repair again from the bytes as they are now; nothing is written.' });


/** The hash a preview of this selection prints when it finds nothing to repair. */
async function emptyPlanHash(engine: BrainEngine, scope: RepairScope, selection: Selection): Promise<string> {
  const sourcesRows = await engine.executeRaw<{ id: string; incarnation: string }>('SELECT id, incarnation::text AS incarnation FROM sources WHERE id=ANY($1::text[]) ORDER BY id', [scope.source_ids]);
  return previewHash({ kind: 'fences-v1', brain_id: scope.brain_id, sources: sourcesRows, selection, items: [] });
}

export const fencesRepair: RepairHandler = {
  kind: 'fences',
  outcomeItemsLimit: 1000,
  async plan(engine, scope, _after, opts): Promise<RepairPlan> {
    const selection: Selection = { source_ids: scope.source_ids, only: [...(opts?.only ?? [])].sort(), skip: [...(opts?.skip ?? [])].sort(),
      slugs: [...(opts?.slugs ?? [])].sort(), no_llm: opts?.noLlm === true };
    const preview = previewArgv(scope, selection);
    if (opts?.apply && opts.expect) {
      // #6377: a preview that found nothing saved no set; its hash still binds "nothing to apply" (the content lane passes one hash per kind).
      if (opts.expect === await emptyPlanHash(engine, scope, selection)) return { items: [], preview_hash: opts.expect, residuals: {}, llm: { usd: 0, cap_remaining_usd: null } };
      const approved = await loadApprovedSet<ApprovedSetItem>(engine, { command: 'fences', hash: opts.expect, previewCommand: shellQuote(preview) });
      if (approved.items.some(entry => digestOf(entry.selection) !== digestOf(selection))) throw previewChangedError(opts.expect, shellQuote(preview));
      const items = approved.items.map(({ selection: _chosen, ...entry }, index) => item(entry, index, opts.expect!, index === approved.items.length - 1, false));
      const s = await settings(engine, opts);
      return { items, preview_hash: opts.expect, residuals: {}, llm: { usd: items.reduce((sum, i) => sum + (i.llm_usd ?? 0), 0), cap_remaining_usd: s.llmEnabled ? s.dayRemaining : 0 } };
    }
    const now = Date.now();
    const runs = await runFenceCensus(engine, { sourceIds: scope.source_ids, deadline: Math.min(now + SCAN_MS(), opts?.deadline ?? Infinity) });
    const sources = new Map<string, FenceSource | null>();
    for (const id of scope.source_ids) sources.set(id, await loadFenceSource(engine, id, { remote: opts?.remote !== false }));
    const found = await listFenceCandidates(engine, scope.source_ids);
    const { extra, unknown } = await extraCandidates(engine, scope, selection, found, sources);
    const candidates = rotate([...found, ...extra].filter(cand => selected(cand, selection)), c => rotationKey({ source_id: c.source_id, key: c.key }),
      opts?.apply ? await rotationAfter(engine, ROTATION_OP, scope.brain_id) : null);
    const s = await settings(engine, opts ?? { noLlm: false });
    const store = attemptStore(engine);
    const residuals: Record<string, number> = {};
    const warnings = unknown.map(name => `${name}: no such file, page or fence candidate in scope; check the source-relative path or slug.`);
    const approved: ApprovedFence[] = [];
    const diffs: FileDiff[] = [];
    const held: HeldEntry[] = [];
    const llmItems: FencesPreviewDetails['llm_items'] = [];
    const hold = (cand: FenceCandidate, entry: HeldEntry) => { held.push(entry); residuals[entry.reason] = (residuals[entry.reason] ?? 0) + 1; return entry; };
    let unpricedWarned = false;
    for (const cand of candidates) {
      const name = `${cand.source_id}:${cand.path ?? cand.key}`;
      const isHeld = cand.origins.includes('hold');
      const src = sources.get(cand.source_id) ?? null;
      if (!src) continue;
      const keep = async (entry: HeldEntry, next: string | null = null) => {
        hold(cand, entry);
        if (opts?.apply) await recordHeld(engine, src, { path: cand.path, held: isHeld }, { reason: entry.reason, gate: entry.gate, rows: entry.rows, next });
      };
      if (src.owner) { await keep({ item: name, reason: ownerReason(src.owner), tier: 'manual', resolution: `${src.owner.message} ${src.owner.why}` }); continue; }
      if (repairBusy(src.busy, { path: cand.path, slug: cand.key })) {
        await keep({ item: name, reason: 'sync_in_progress', tier: cand.tier, resolution: repairBusyMessage(src.busy, src.id, cand.path ?? cand.key) });
        continue;
      }
      const read = await readFenceTarget(engine, src, { key: cand.key, path: cand.path });
      if (!read.ok) {
        if (read.reason !== 'gone') await keep({ item: name, reason: read.reason, tier: 'manual', resolution: read.reason === 'origin_conflict' ? read.message : read.reason === 'unsafe_path'
          ? `${cand.path} is a symlink, sits under one, or resolves outside the source root; gbrain never writes through one. Replace it with the real file.`
          : `${cand.path} is not valid UTF-8; re-save it as UTF-8 and preview again.` });
        continue;
      }
      const target = read.target;
      const analysis = await analyzeFences(engine, target, await analysisOpts(engine, target, src, { apply: opts?.apply === true, expect: opts?.expect, model: s.model }));
      if (analysis.status === 'clean') { residuals.already_clean = (residuals.already_clean ?? 0) + 1; continue; }
      if (analysis.status === 'manual') {
        await keep({ item: name, reason: analysis.reason, tier: 'manual', resolution: analysis.resolution, ...(analysis.gate ? { gate: analysis.gate } : {}), ...(analysis.rows ? { rows: analysis.rows } : {}) });
        continue;
      }
      const base: Omit<ApprovedFence, 'tier' | 'after' | 'classes' | 'rows' | 'columns' | 'estimate_usd' | 'llm_waiting'> = { source_id: src.id, key: cand.key, slug: target.slug, path: target.path,
        mode: target.mode, before: target.before, revision: target.snapshot?.revision ?? null, page_id: target.snapshot?.page.id ?? null, held: isHeld };
      if (analysis.status === 'proposal') {
        const bytes = afterBytes(target, analysis.after);
        if (!bytes) { await keep({ item: name, reason: 'unparseable', tier: 'manual', resolution: `gbrain could not place the repaired fence back into ${target.path}; edit the fence there by hand.` }); continue; }
        const at = fixLocation(analysis.fixes, []);
        approved.push({ ...base, tier: analysis.tier, after: bytes.sha, classes: classesOf(analysis.fixes), ...at, estimate_usd: 0, llm_waiting: 0 });
        const beforeText = target.content ?? `${target.page.compiled_truth}\n${target.page.timeline}`;
        diffs.push({ item: name, tier: analysis.tier, classes: classesOf(analysis.fixes), diff: lineDiff(target.path ?? target.slug, beforeText, bytes.text) });
        continue;
      }
      const reasons = [...new Set(analysis.residual.map(i => i.reason))];
      const at = fixLocation(analysis.fixes, analysis.residual);
      const llmHeld = (reason: FenceReason, resolution: string, next: string | null = null) => keep({ item: name, reason, tier: 'llm', resolution, rows: at.rows }, next);
      if (!s.llmEnabled) {
        await llmHeld('llm_disabled', `Model repair is off (${selection.no_llm ? '--no-llm' : 'fences.repair.llm false'}), so row(s) ${at.rows.join(', ') || '?'} stay held (${reasons.join(', ')}). `
          + 'Fix them by hand, or ask the user before turning model repair on: gbrain config set fences.repair.llm true.');
        continue;
      }
      const model = s.model;
      if (!model) { await llmHeld('no_measured_model', noMeasuredModel(at.rows)); continue; }
      if (target.mode === 'managed' && target.snapshot && !target.snapshot.page.deleted_at) {
        const fileTags = new Set(parseMarkdown(target.content ?? '', target.path ?? 'page.md').tags);
        if (target.snapshot.tags.some(tag => !fileTags.has(tag))) {
          await keep({ item: name, reason: 'canonical_overlay', tier: 'manual', resolution: `The page of ${target.path} carries tags its file does not, so a repaired file could not publish as written; add the tags to the file's frontmatter (gbrain get --source ${src.id} -- ${target.slug} shows them), then preview again.` });
          continue;
        }
      }
      const estimate = tier3Estimate(analysis.requests, { model, overrides: s.overrides, capSource: s.capSource }, analysis.tails);
      if (!estimate.ok) {
        await llmHeld('no_pricing', `A spend cap is set but gbrain has no price for ${model}. ${estimate.guidance.lookup} Register it with: ${estimate.guidance.register_command}`);
        continue;
      }
      if (estimate.estimated && !unpricedWarned) {
        unpricedWarned = true;
        warnings.push(`gbrain has no price for the fence repair model ${model}; model repair runs under the default caps and is metered at an estimated ceiling (the highest chat rate gbrain knows). Make it exact with: ${pricingSetCommand(model, 'chat')}`);
      }
      if (s.perPageUsd === 0 || s.perDayUsd === 0) {
        await llmHeld('budget_exhausted', `Model repair spend is set to 0 (fences.repair.max_usd_per_${s.perPageUsd === 0 ? 'page' : 'day'}), so these rows stay held. Raising it is the user's call: gbrain config set fences.repair.max_usd_per_${s.perPageUsd === 0 ? 'page' : 'day'} <usd>.`);
        continue;
      }
      if (estimate.usd > s.perPageUsd + 1e-9) {
        await llmHeld('budget_exhausted', `The estimated model cost ($${estimate.usd.toFixed(4)}) exceeds fences.repair.max_usd_per_page ($${s.perPageUsd.toFixed(2)}). Raising it is the user's call: gbrain config set fences.repair.max_usd_per_page <usd>.`);
        continue;
      }
      const memo = await store.read(attemptCandidate(target, src.incarnation));
      if (memo && memo.memo === tier3Memo(target, model) && memo.state === 'rejected') {
        const reason = (memo.reason ?? 'still_invalid') as FenceReason;
        await keep({ item: name, reason, tier: 'manual', resolution: `${model}'s repair of these exact bytes was rejected (${reason}${memo.gate ? `, gate ${memo.gate}` : ''}); it is not retried until the file, the model or the rules change. `
          + `Fix row(s) ${(memo.rows ?? at.rows).join(', ') || '?'} by hand.`, ...(memo.gate ? { gate: memo.gate as GateLetter } : {}), ...(memo.rows ? { rows: memo.rows } : {}) });
        continue;
      }
      approved.push({ ...base, tier: 'llm', after: null, classes: [...new Set([...classesOf(analysis.fixes), ...reasons])].sort(), ...at, estimate_usd: estimate.usd, llm_waiting: 0 });
      llmItems.push({ item: name, rows: at.rows, reasons, estimate_usd: estimate.usd });
    }
    let waiting = 0;
    for (const entry of [...approved].reverse()) { if (entry.tier === 'llm') waiting++; entry.llm_waiting = entry.tier === 'llm' ? waiting : 0; }
    const sourcesRows = await engine.executeRaw<{ id: string; incarnation: string }>('SELECT id, incarnation::text AS incarnation FROM sources WHERE id=ANY($1::text[]) ORDER BY id', [scope.source_ids]);
    const hash = previewHash({ kind: 'fences-v1', brain_id: scope.brain_id, sources: sourcesRows, selection, items: approved });
    if (approved.length && !opts?.apply) await saveApprovedSet<ApprovedSetItem>(engine, { command: 'fences', hash }, approved.map(entry => ({ ...entry, selection })));
    const partial = runs.some(run => !run.complete);
    const freshAt = runs.every(run => run.fresh_at) ? runs.map(run => run.fresh_at!).sort()[0] ?? null : null;
    const listing: RepairListing[] = [
      ...approved.map(entry => ({ item: itemName(entry), class: entry.tier, detail: `${entry.classes.join(', ')}${entry.rows.length ? `; rows ${entry.rows.join(', ')}` : ''}`
        + `${entry.tier === 'llm' ? `; rewritten by ${s.model} at apply time, gated by (a)-(g); est. $${entry.estimate_usd.toFixed(4)}` : ''}` })),
      ...held.map(entry => ({ item: entry.item, class: entry.reason, detail: entry.resolution })),
    ];
    const llmUsd = approved.reduce((sum, entry) => sum + entry.estimate_usd, 0);
    const apply = [...preview, ...(s.runMaxUsd !== null ? ['--max-usd', String(s.runMaxUsd)] : []), '--apply', '--expect', hash];
    const next_actions: Action[] = approved.length ? [{ argv: apply, consent: [], actor: 'agent', requires_exclusive: false, plan_hash: hash, preview_argv: preview,
      why: `Applies exactly the ${approved.length} previewed fence repair(s)${llmItems.length ? `, ${llmItems.length} of them by the model (estimated $${llmUsd.toFixed(4)})` : ''}; a file or page that changed since this preview is skipped.`,
      verify: { argv: ['gbrain', 'doctor', '--only', 'fence_integrity', '--json'] } }] : [];
    const counts = { deterministic: 0, resolver: 0, llm: 0, held: held.length };
    for (const entry of approved) counts[entry.tier]++;
    const details: FencesPreviewDetails = { counts, model: s.llmEnabled ? s.model : null, llm_enabled: s.llmEnabled,
      samples: Object.fromEntries((['deterministic', 'resolver'] as const).flatMap(tier => { const d = diffs.find(x => x.tier === tier); return d ? [[tier, d]] : []; })),
      diffs, llm_items: llmItems, held, caps: { max_usd_per_page: s.perPageUsd, max_usd_per_day: s.perDayUsd, day_remaining_usd: s.dayRemaining, run_max_usd: s.runMaxUsd }, next_actions };
    return { items: approved.map((entry, index) => item(entry, index, null, index === approved.length - 1, partial)), preview_hash: hash, residuals, listing,
      ...(warnings.length ? { warnings } : {}), details: details as unknown as Record<string, unknown>,
      llm: { usd: llmUsd, cap_remaining_usd: s.llmEnabled ? s.dayRemaining : 0 }, scan: { fresh_at: freshAt, partial } };
  },
  async apply(ctx, raw, opts): Promise<RepairItemOutcome> {
    if (ctx.remote !== false) throw trustedCliRequired('gbrain repair fences writes files and may call a paid model, so it runs only from the trusted local CLI or the maintenance job on the brain host.');
    const { entry, hash, last } = raw as FenceItem;
    try {
      return await retireAfterLastItem(ctx.engine, 'fences', hash, last, () => applyFence(ctx, entry, { embed: opts?.embed === true, expect: hash, allowanceUsd: opts?.llmAllowanceUsd, deadline: opts?.deadline, noLlm: opts?.noLlm === true }));
    } finally {
      if (!hash) await saveRotation(ctx.engine, ROTATION_OP, await rotationBrain(ctx.engine), rotationKey(entry)).catch(() => undefined);
    }
  },
  render(details, opts) {
    const d = details as unknown as FencesPreviewDetails;
    const lines = [`  tiers: deterministic=${d.counts.deterministic}, resolver=${d.counts.resolver}, llm=${d.counts.llm}, held=${d.counts.held}`
      + `${d.llm_enabled ? `; model ${d.model}` : '; model repair off'}`];
    const capLine = `  model caps: $${d.caps.max_usd_per_page.toFixed(2)}/page, $${d.caps.max_usd_per_day.toFixed(2)}/day${d.caps.day_remaining_usd !== null ? ` ($${d.caps.day_remaining_usd.toFixed(4)} left today)` : ''}`
      + `${d.caps.run_max_usd !== null ? `; this run at most $${d.caps.run_max_usd.toFixed(4)}` : ''}`;
    if (d.counts.llm || d.held.some(h => h.tier === 'llm')) lines.push(capLine);
    const shown = opts.diff ? d.diffs : Object.values(d.samples);
    for (const diff of shown) lines.push(`  ${diff.tier}: ${diff.item} (${diff.classes.join(', ')})`, ...diff.diff.split('\n').map(line => `    ${line}`));
    if (!opts.diff && d.diffs.length > shown.length) lines.push(`  (one sample diff per tier; --diff or --json shows all ${d.diffs.length})`);
    for (const llm of d.llm_items) lines.push(`  llm: ${llm.item}${llm.rows.length ? ` rows ${llm.rows.join(', ')}` : ''} (${llm.reasons.join(', ')}): rewritten by ${d.model} at apply time, gated by (a)-(g); est. $${llm.estimate_usd.toFixed(4)}`);
    for (const h of d.held) lines.push(`  held ${h.item} [${h.reason}${h.gate ? `, gate ${h.gate}` : ''}]: ${h.resolution}`);
    for (const action of d.next_actions) lines.push(`  next: ${shellQuote(action.argv!)}`);
    return lines;
  },
  async report(ctx, scope, result, opts) {
    return reportFences(ctx, scope, result, opts);
  },
};

function digestOf(selection: Selection): string {
  return sha256(JSON.stringify([selection.source_ids, selection.only, selection.skip, selection.slugs, selection.no_llm]));
}

interface ApplyOptions { embed: boolean; expect: string | null; allowanceUsd?: number; deadline?: number; noLlm: boolean }

async function applyFence(ctx: OperationContext, entry: ApprovedFence, opts: ApplyOptions): Promise<RepairItemOutcome> {
  const engine = ctx.engine;
  const where = { ...(entry.path ? { path: entry.path } : {}), slug: entry.slug, mode: entry.mode, tier: entry.tier };
  const moved = opts.expect ? 'changed_since_preview' : 'changed_since_read';
  const skipped = (reason: string, message: string): RepairItemOutcome => ({ applied: false, outcome: 'skipped', reason, detail: { ...where, message } });
  const src = await loadFenceSource(engine, entry.source_id, { remote: ctx.remote !== false });
  if (!src) return skipped(moved, `Source ${entry.source_id} is gone or archived.`);
  const heldOutcome = async (reason: string, message: string, extra: { gate?: GateLetter; rows?: number[]; next?: string | null; tier?: FenceTier } = {}): Promise<RepairItemOutcome> => {
    await recordHeld(engine, src, entry, { reason, ...extra });
    return { applied: false, outcome: 'held', reason, detail: { ...where, tier: extra.tier ?? heldTier(reason), message, ...(extra.gate ? { gate: extra.gate } : {}), ...(extra.rows?.length ? { rows: extra.rows } : {}) } };
  };
  if (src.owner) {
    const reason = ownerReason(src.owner);
    await recordHeld(engine, src, entry, { reason });
    const out = skipped(reason, src.owner.message);
    return { ...out, detail: { ...out.detail, why: src.owner.why, fix: src.owner.fix.argv, retryable: src.owner.retryable } };
  }
  // Re-checked here and again at the write's admission (file-repair.ts): a sync may have frozen this candidate since the plan.
  if (repairBusy(src.busy, { path: entry.path, slug: entry.slug })) {
    await recordHeld(engine, src, entry, { reason: 'sync_in_progress' });
    return skipped('sync_in_progress', repairBusyMessage(src.busy, src.id, entry.path ?? entry.slug));
  }
  const read = await readFenceTarget(engine, src, { key: entry.key, path: entry.path });
  if (!read.ok) return skipped(moved, `The candidate is ${read.reason === 'gone' ? 'gone' : read.reason}.`);
  const target = read.target;
  if (target.before !== entry.before || (target.snapshot?.revision ?? null) !== entry.revision && target.mode !== 'managed' && target.mode !== 'legacy') {
    return skipped(moved, `${entry.path ?? entry.slug} changed since it was ${opts.expect ? 'previewed' : 'read'}; preview again with gbrain repair fences --source ${src.id}.`);
  }
  const runModel = (await settings(engine, { noLlm: opts.noLlm })).model;
  const analysisFor = (tailProse?: ReadonlySet<string>) => analysisOpts(engine, target, src, { apply: true, expect: opts.expect ?? null, model: runModel })
    .then(base => analyzeFences(engine, target, tailProse ? { ...base, tailProse } : base));
  const analysis = await analysisFor();
  if (analysis.status === 'clean') return skipped('already_clean', `${entry.path ?? entry.slug} no longer has a malformed fence.`);
  if (analysis.status === 'manual') return heldOutcome(analysis.reason, analysis.resolution, { ...(analysis.gate ? { gate: analysis.gate } : {}), ...(analysis.rows ? { rows: analysis.rows } : {}) });
  if (analysis.status === 'proposal') {
    const bytes = afterBytes(target, analysis.after);
    if (opts.expect && bytes?.sha !== entry.after) return skipped('changed_since_preview', `The repair of ${entry.path ?? entry.slug} differs from the preview; preview again.`);
    return write(ctx, src, target, analysis.after, { tier: analysis.tier, classes: classesOf(analysis.fixes), ...fixLocation(analysis.fixes, []), model: null, cost: 0, merged: mergedReceipt(target.page, analysis.fixes) }, opts, heldOutcome);
  }
  return tier3(ctx, src, target, analysis, entry, opts, heldOutcome, analysisFor);
}

/**
 * #6377: how a run may treat an unclosed fence with trailing text. An explicit preview, and an apply bound to one
 * (`--expect`), carry the user's approval to show the tail of a world-visible page; a bare apply (the cycle,
 * `sync unblock`) never does. A memo that recorded the classifier's prose verdict (`tail_exposure_approval`) lets the
 * approved run close without asking the model again.
 */
async function analysisOpts(engine: BrainEngine, target: FenceTarget, src: FenceSource, run: { apply: boolean; expect?: string | null; model: string | null }): Promise<AnalyzeOpts> {
  const approve = !run.apply || !!run.expect;
  const base: AnalyzeOpts = { pageId: target.snapshot?.page.id ?? null, ...(approve ? { approveTailExposure: true } : {}) };
  if (!approve || !run.model) return base;
  const memo = await attemptStore(engine).read(attemptCandidate(target, src.incarnation)).catch(() => null);
  return memo && memo.memo === tier3Memo(target, run.model) && memo.state === 'rejected' && memo.reason === 'tail_exposure_approval' ? { ...base, tailProse: new Set(['*']) } : base;
}

type HeldFn = (reason: string, message: string, extra?: { gate?: GateLetter; rows?: number[]; next?: string | null; tier?: FenceTier }) => Promise<RepairItemOutcome>;

async function write(ctx: OperationContext, src: FenceSource, target: FenceTarget, after: FencePage,
  r: { tier: RepairTier; classes: string[]; rows: number[]; columns: string[]; model: string | null; cost: number | null; merged?: MergedFenceReceipt[] | undefined }, opts: ApplyOptions, held: HeldFn): Promise<RepairItemOutcome> {
  const outcome = await writeFenceRepair(ctx, src, target, after, { actor: FENCE_REPAIR_ACTOR, tier: r.tier, classes: r.classes, rows: r.rows, columns: r.columns, model: r.model, cost_usd: r.cost,
    ...(r.merged ? { merged: r.merged } : {}) }, { embed: opts.embed });
  if (!outcome.ok) {
    if (outcome.reason === 'changed_since_read') return { applied: false, outcome: 'skipped', reason: 'changed_since_read', detail: { path: target.path, slug: target.slug, mode: target.mode, message: outcome.message } };
    if (outcome.reason === 'sync_in_progress') {
      await recordHeld(ctx.engine, src, { path: target.path, held: target.hold !== null }, { reason: 'sync_in_progress' });
      return { applied: false, outcome: 'skipped', reason: 'sync_in_progress', detail: { path: target.path, slug: target.slug, mode: target.mode, message: outcome.message } };
    }
    return held(outcome.reason, outcome.message, { tier: 'manual' });
  }
  return { applied: true, outcome: 'repaired', detail: { tier: r.tier, classes: r.classes.join(', '), slug: target.slug, ...outcome.detail }, ...(r.cost ? { llm_usd: r.cost } : {}) };
}

async function tier3(ctx: OperationContext, src: FenceSource, target: FenceTarget, analysis: Extract<FenceAnalysis, { status: 'llm' }>, entry: ApprovedFence, opts: ApplyOptions, held: HeldFn,
  reanalyze: (tailProse: ReadonlySet<string>) => Promise<FenceAnalysis>): Promise<RepairItemOutcome> {
  const engine = ctx.engine;
  const s = await settings(engine, { noLlm: opts.noLlm, ...(opts.allowanceUsd !== undefined ? { maxLlmUsd: opts.allowanceUsd } : {}) });
  const rows = fixLocation(analysis.fixes, analysis.residual).rows;
  if (!s.llmEnabled) return held('llm_disabled', `Model repair is off; row(s) ${rows.join(', ')} stay held.`, { rows, tier: 'llm' });
  const model = s.model;
  if (!model) return held('no_measured_model', noMeasuredModel(rows), { rows, tier: 'llm' });
  if (s.perPageUsd === 0 || s.perDayUsd === 0) return held('budget_exhausted', 'Model repair spend is set to 0.', { rows, tier: 'llm' });
  const now = () => new Date();
  const timeoutMs = Math.max(5_000, Math.min(CALL_TIMEOUT_MS(), opts.deadline !== undefined ? opts.deadline - Date.now() : Infinity));
  const result = await runTier3(target, analysis, src.incarnation, { ledger: dailyLedger(engine, FENCE_REPAIR_LEDGER), store: attemptStore(engine), model, overrides: s.overrides,
    capSource: s.capSource, perPageUsd: s.perPageUsd, perDayUsd: s.perDayUsd, ...(opts.allowanceUsd !== undefined ? { allowanceUsd: opts.allowanceUsd } : {}), timeoutMs, now, reanalyze });
  if (!result.ok) {
    if (result.reason === 'claimed_elsewhere') return { applied: false, outcome: 'skipped', reason: 'claimed_elsewhere', detail: { path: target.path, slug: target.slug, message: result.message } };
    const next = result.reason === 'budget_exhausted' ? result.resetsAt ?? nextUtcMidnight(new Date()) : null;
    const out = await held(result.reason, result.message, { ...(result.gate ? { gate: result.gate } : {}), ...(result.rows ? { rows: result.rows } : {}), next, tier: FENCE_REASONS[result.reason]?.stage === 'gate' ? 'manual' : 'llm' });
    const withSpend = { ...out, ...(result.spentUsd ? { llm_usd: result.spentUsd } : {}), detail: { ...out.detail, ...(result.memoHit ? { memo: 'rejected_before' } : {}) } };
    if (!result.stop) return withSpend;
    const day = await dailyLedger(engine, FENCE_REPAIR_LEDGER).readDay().catch(() => null);
    const resets = result.resetsAt ?? nextUtcMidnight(new Date());
    const message = opts.allowanceUsd !== undefined && !result.resetsAt
      ? `Stopped: ${result.message} ${entry.llm_waiting} page(s) wait for the model. Rerun with a larger --max-usd, or leave them to the maintenance run.`
      : `Stopped: the daily fence-repair budget is spent ($${(day?.committedUsd ?? 0).toFixed(4)} of $${s.perDayUsd.toFixed(2)} today). It resets at ${resets}; `
        + `${entry.llm_waiting} page(s) wait for the model and the next run after that repairs them. Raising the cap is the user's call: gbrain config set fences.repair.max_usd_per_day <usd>.`;
    return { ...withSpend, stop: { reason: 'budget_exhausted', message, fix: { argv: ['gbrain', 'config', 'set', 'fences.repair.max_usd_per_day', '<usd>'], consent: ['paid'], actor: 'agent', requires_exclusive: false,
      why: `Model fence repair stopped at the daily cap; ${entry.llm_waiting} page(s) wait until ${resets} unless the cap is raised.`,
      user_message: `The daily model budget for fence repair ($${s.perDayUsd.toFixed(2)}) is spent and ${entry.llm_waiting} page(s) still wait. Raise it for today, or let them repair after ${resets}?`,
      inputs: [{ name: 'usd', how: 'The new daily cap in USD the user agrees to; it must exceed what is already spent today.' }],
      verify: { argv: ['gbrain', 'doctor', '--only', 'fence_integrity', '--json'] } } } };
  }
  const written = await write(ctx, src, target, result.after, { tier: 'llm', classes: classesOf(analysis.fixes, result.cleared), ...fixLocation(analysis.fixes, analysis.residual), model, cost: result.spentUsd,
    merged: mergedReceipt(target.page, analysis.fixes) }, opts, held);
  const store = attemptStore(engine);
  if (written.applied) await store.publish(result.claim);
  else if (written.reason === 'changed_since_read' || written.reason === 'sync_in_progress') await store.transient(result.claim, written.reason);
  else await store.reject(result.claim, { reason: written.reason ?? 'still_invalid' });
  return { ...written, ...(result.spentUsd ? { llm_usd: result.spentUsd } : {}) };
}

/** Verification and the summary counts: what this run repaired by tier, what is left by reason, and the oldest hold. */
/** Candidates of the selection this run did not touch, by the reason they are held (the last repair's, else the census's). */
async function heldInScope(engine: BrainEngine, scope: RepairScope, opts: RepairPlanOptions, result: RepairResult): Promise<Record<string, number>> {
  const selection: Selection = { source_ids: scope.source_ids, only: opts.only ?? [], skip: opts.skip ?? [], slugs: opts.slugs ?? [], no_llm: opts.noLlm === true };
  const touched = new Set((result.outcome_items ?? []).map(outcome => outcome.item));
  const holds = new Map((await readGitSourceHolds(engine, { sourceIds: scope.source_ids })).flatMap(source => source.holds.map(hold => [`${hold.source_id}:${hold.path}`, hold] as const)));
  const out: Record<string, number> = {};
  for (const cand of await listFenceCandidates(engine, scope.source_ids)) {
    if (!selected(cand, selection) || touched.has(`${cand.source_id}:${cand.key}`)) continue;
    const hold = cand.path ? holds.get(`${cand.source_id}:${cand.path}`) : undefined;
    const reason = hold?.meta.fence_repair?.reason ?? cand.reasons[0] ?? 'unparseable';
    out[reason] = (out[reason] ?? 0) + 1;
  }
  return out;
}

async function reportFences(ctx: OperationContext, scope: RepairScope, result: RepairResult, opts: RepairPlanOptions) {
  const repairedByTier: Record<RepairTier, number> = { deterministic: 0, resolver: 0, llm: 0 };
  const remaining: Record<string, number> = {};
  for (const [reason, count] of Object.entries(result.residuals)) if (reason !== 'already_clean') remaining[reason] = (remaining[reason] ?? 0) + count;
  const repaired = result.mode === 'apply' ? result.outcomes?.repaired ?? 0 : 0;
  if (result.mode === 'apply') {
    for (const outcome of result.outcome_items ?? []) {
      if (outcome.outcome === 'repaired') { const tier = outcome.detail?.tier as RepairTier | undefined; if (tier) repairedByTier[tier]++; }
      else if (outcome.reason && outcome.reason !== 'already_clean') remaining[outcome.reason] = (remaining[outcome.reason] ?? 0) + 1;
    }
    const unattempted = result.affected - result.applied - result.skipped - result.failed.length;
    if (unattempted > 0 && result.stopped) remaining[result.stopped.reason] = (remaining[result.stopped.reason] ?? 0) + unattempted;
    // An --expect apply replays the approved set only; re-check the selection for what the preview listed as held.
    if (opts.expect) for (const [reason, count] of Object.entries(await heldInScope(ctx.engine, scope, opts, result))) remaining[reason] = (remaining[reason] ?? 0) + count;
  } else if (result.affected) remaining.pending_repair = result.affected;
  const [oldest] = await ctx.engine.executeRaw<{ held_at: string | null }>(`SELECT min(completed_keys->0->>'held_at') AS held_at FROM op_checkpoints
    WHERE op='sync-hold' AND completed_keys->0->>'code'='invalid_fence' AND completed_keys->0->>'source_id'=ANY($1::text[])`, [scope.source_ids]).catch(() => [{ held_at: null }]);
  const llmRepairs = repairedByTier.llm;
  const spent = typeof result.cost.llm_usd === 'number' ? result.cost.llm_usd : 0;
  const verification: FenceRepairVerification = { candidates: result.affected + Object.values(result.residuals).reduce((a, b) => a + b, 0) - (result.residuals.already_clean ?? 0),
    repaired_by_tier: repairedByTier, held_by_reason: Object.fromEntries(Object.entries(remaining).filter(([reason]) => reason !== 'pending_repair')),
    oldest_hold_at: oldest?.held_at ?? null, llm_repairs: llmRepairs, llm_usd_per_repair: llmRepairs ? spent / llmRepairs : null, partial: result.scan?.partial ?? false };
  return { repaired, remaining, verification: verification as unknown as Record<string, unknown> };
}