Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
39.2 KB
Raw Blame
/**
 * `gbrain repair agent-session-facts` (#8064): re-attribute facts the capture
 * lanes (`hook:writeback`, `hook:compact`, `sweep:corpus`) saved as the
 * owner's own from sessions an orchestrator launched (headless workers on the
 * owner's account), and retire the takes consolidate promoted from them. The
 * capture fix stops new damage (agent sessions get a speaker sidecar and their
 * facts `attributed_to: other`); this kind repairs the facts already stored.
 *
 * Candidates are active capture-lane facts of the scoped sources whose
 * `attributed_to` is `user` or unset. Each is classified from its session
 * (`source_session`; corpus rows resolve with `corpusFileSessionId`):
 *   - evidenced: the session has a speaker sidecar (`<sid>.speaker.json` in
 *     the corpus dir, its spool dir or beside the session's corpus files);
 *     the operator listed it with `--session <id>`; or its `<sid>.source.json`
 *     records a cwd under an operator `--cwd <prefix>` (realpath-normalized,
 *     compared on path boundaries).
 *   - ambiguous: the session's first user turn (whitespace-normalized,
 *     lowercased, at least 40 characters) shares its first 160 characters with
 *     the first user turn of at least 3 other retained sessions with no
 *     speaker sidecar (a template brief). Listed fact by fact; re-attributed only with
 *     `--include-ambiguous` and the hash of that preview.
 *   - excluded: an evidenced or ambiguous row whose claim and entity also have
 *     an active user-attributed row from a session that is not suspect (the
 *     owner said it too); kept.
 * Rows of sessions with no retained corpus file, sidecar or source record are
 * counted `unclassifiable` and never touched.
 *
 * The apply (`--apply --expect <hash> --yes`) never deletes. Each approved
 * fact still exactly as previewed gets `attributed_to: other` and the speaker
 * note (`speakerContextNote`) in its context: a fenced row (`row_num` on its
 * page) in the page's `## Facts` fence by one revision-bound `put_page` per
 * page, so the canonical projection rewrites the row in place; database-only
 * rows by one maintenance request on a managed brain (one transaction on an
 * unmanaged brain). Then each `kind: fact`, `holder: self` take that is still
 * active and unresolved and whose every contributing fact (`consolidated_into`)
 * is now non-user is retired (`active = false`): struck in the page's takes
 * fence by a revision-bound `put_page` when the fence holds it, otherwise in
 * the database by the same kind of request or transaction. A fact or take that
 * changed since the preview is reported `changed_since_preview` and kept.
 */
import { closeSync, existsSync, openSync, readdirSync, readSync, realpathSync, statSync, type Dirent } from 'node:fs';
import { basename, dirname, join, relative, resolve, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { parseFactsFence } from '../facts-fence.ts';
import { strikeFenceRow } from '../facts/forget.ts';
import { parseTakesFence } from '../takes-fence.ts';
import { takesPreparation } from '../takes-write.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { digest } from '../persistence/digest.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { maintenancePreflight, submitDatabaseMaintenanceIntent } from '../persistence/prepared-maintenance.ts';
import { authorizeWrite } from '../persistence/authority.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { submitPageMutation } from '../persistence/page-mutations.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { CONTEXT_NOTE_SEPARATOR } from '../facts/subject-infer.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { corpusFileSessionId, corpusSpoolDir, parseWbFileName, speakerFileName } from '../context/corpus-segments.ts';
import { readSessionSource } from '../context/corpus-source.ts';
import { parseCorpusTurns } from '../context/corpus-turns.ts';
import { DETECTED_PRINCIPAL, readSpeakerSidecar, speakerContextNote, type SpeakerSidecar } from '../context/session-speaker.ts';
import { stripPastedContent } from '../transcripts/pasted-content.ts';
import { wholeBodySnapshot } from '../persistence/segmented-apply.ts';
import { shellQuote } from '../shell-quote.ts';
import { pruneDir } from '../sync.ts';
import { CAPTURE_LANES, captureSessionId } from './captured-facts.ts';
import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairListing, type RepairPlan, type RepairPlanOptions,
  type RepairScope } from './core.ts';

export const AGENT_SESSION_FACTS_INTENT = 'managed_maintenance_agent_session_facts';
const COMMAND = 'agent-session-facts';
const CORPUS_KEY = 'dream.synthesize.session_corpus_dir';
const OPENING_CHARS = 160;
const OPENING_MIN_CHARS = 40;
const OPENING_MIN_OTHERS = 3;
const HEAD_BYTES = 64 * 1024;
/** #9390: what Claude Code writes into a user turn around a slash command (/clear, /model), never text the owner typed. */
const HARNESS_BLOCKS = /<(local-command-caveat|command-name|command-message|command-args|local-command-stdout|local-command-stderr)>[\s\S]*?<\/\1>/g;
const NOTE_SEPARATOR = CONTEXT_NOTE_SEPARATOR;
const NOTE_MARK = 'speaker: agent ';

export type AgentSessionFactClass = 'evidenced' | 'ambiguous' | 'excluded';

/** The operator's evidence flags: `--cwd <prefix>`, `--session <id>` (both repeatable) and `--principal <label>`. */
export interface AgentSessionOptions { cwdPrefixes?: string[]; sessions?: string[]; principal?: string }

export interface AgentSessionFactCandidate {
  id: number;
  source_id: string;
  /** The page the fact lives on (fenced rows) or its entity key (database-only rows). */
  slug: string;
  row_num: number | null;
  class: AgentSessionFactClass;
  /** `speaker_sidecar`, `operator_session`, `operator_cwd`, `repeated_opening` or `excluded:owner_also_said`. */
  reason: string;
  session: string;
  evidence: string;
  /** The agent the speaker note names. */
  principal: string;
  /** Digest of the row's claim, visibility, entity, fence position, attribution and context, so an edited row is not rewritten. */
  fact_hash: string;
}

export interface AgentSessionTake { id: number; source_id: string; slug: string; row_num: number; claim: string; fact_ids: number[]; take_hash: string }

export interface AgentSessionFactsClassification {
  candidates: AgentSessionFactCandidate[];
  unclassifiable: number;
  not_suspect: number;
  /** Corpus directories and session files the classification could not read (relative to the corpus dir). */
  unreadable_corpus_files: string[];
}

interface ApprovedPage {
  source_id: string;
  slug: string;
  include_ambiguous: boolean;
  scope: string[];
  /** The normalized evidence flags of the preview; an apply with other flags refuses. */
  options: string;
  facts?: AgentSessionFactCandidate[];
  takes?: AgentSessionTake[];
}

/** `indexes`: the run's corpus index by corpus dir, shared by every item of one run (each run plans new items). */
interface PageItem extends RepairItem { page: ApprovedPage; hash: string; last: boolean; options: AgentSessionOptions; indexes: Map<string | null, CorpusIndex> }

interface FactRow {
  id: number | string; source_id: string; source_session: string | null; fact: string; visibility: string; entity_slug: string | null;
  row_num: number | null; source_markdown_slug: string | null; attributed_to: string | null; context: string | null;
}

type Verdict = { klass: 'evidenced' | 'ambiguous'; reason: string; evidence: string; principal: string } | 'not_suspect' | 'unclassifiable';

interface CorpusIndex {
  corpusDir: string | null;
  files: Map<string, string[]>;
  openings: Map<string, string>;
  openingSessions: Map<string, Set<string>>;
  unreadSessions: Set<string>;
  unreadable: string[];
}

/** Sorted, deduplicated flags: the form the hash, the commands and the approved set carry. */
export function normalizeAgentSessionOptions(opts: AgentSessionOptions): AgentSessionOptions & { cwdPrefixes: string[]; sessions: string[] } {
  return { cwdPrefixes: [...new Set(opts.cwdPrefixes ?? [])].sort(), sessions: [...new Set(opts.sessions ?? [])].sort(), ...(opts.principal ? { principal: opts.principal } : {}) };
}

function canonicalPath(path: string): string {
  const absolute = resolve(path);
  try { return realpathSync(absolute); } catch { return absolute; }
}

const under = (path: string, prefix: string) => path === prefix || path.startsWith(prefix.endsWith(sep) ? prefix : prefix + sep);

function readHead(path: string): string {
  const fd = openSync(path, 'r');
  try {
    const buffer = Buffer.alloc(HEAD_BYTES);
    return buffer.subarray(0, readSync(fd, buffer, 0, HEAD_BYTES, 0)).toString('utf8');
  } finally { closeSync(fd); }
}

/** The session's first user turn with owner text once harness blocks are dropped, normalized; null when no retained file holds one long enough to compare, 'unread' when its files could not be read. */
function openingKey(paths: string[], unreadable: string[]): string | null {
  const ranked = paths.map(path => {
    let mtime = Number.POSITIVE_INFINITY;
    try { mtime = statSync(path).mtimeMs; } catch { /* ranked last */ }
    return { path, wb: parseWbFileName(basename(path)) !== null, mtime };
  }).sort((a, b) => Number(a.wb) - Number(b.wb) || a.mtime - b.mtime || a.path.localeCompare(b.path));
  let unread = false;
  for (const { path, wb } of ranked) {
    let head: string;
    try { head = readHead(path); } catch { unreadable.push(path); unread = true; continue; }
    const ownerText = (text: string) => text.replace(HARNESS_BLOCKS, ' ').replace(/\s+/g, ' ').trim();
    const turn = wb ? ownerText(stripPastedContent(head).text) : parseCorpusTurns(head).filter(t => t.role === 'user').map(t => ownerText(t.body)).find(Boolean);
    const key = turn?.toLowerCase().slice(0, OPENING_CHARS);
    if (key) return key.length >= OPENING_MIN_CHARS ? key : null;
  }
  return unread ? 'unread' : null;
}

/** Every corpus `.txt` (dream discovery's pruning, the spool dir included) by session, and each session's opening. */
function corpusIndex(corpusDir: string | null): CorpusIndex {
  const index: CorpusIndex = { corpusDir, files: new Map(), openings: new Map(), openingSessions: new Map(), unreadSessions: new Set(), unreadable: [] };
  if (!corpusDir || !existsSync(corpusDir)) return index;
  const walk = (dir: string) => {
    let entries: Dirent[];
    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { index.unreadable.push(dir); return; }
    for (const entry of entries) {
      const full = join(dir, entry.name);
      if (entry.isDirectory()) { if (pruneDir(entry.name, dir)) walk(full); }
      else if (entry.isFile() && entry.name.endsWith('.txt')) {
        const session = corpusFileSessionId(entry.name);
        index.files.set(session, [...(index.files.get(session) ?? []), full]);
      }
    }
  };
  walk(corpusDir);
  for (const [session, paths] of index.files) {
    const key = openingKey(paths, index.unreadable);
    if (key === 'unread') { index.unreadSessions.add(session); continue; }
    if (!key) continue;
    index.openings.set(session, key);
    if (sessionSidecar(corpusDir, paths, session)) continue;
    index.openingSessions.set(key, (index.openingSessions.get(key) ?? new Set<string>()).add(session));
  }
  return index;
}

/** A session's speaker sidecar, read in the corpus root, the spool dir and beside each of its corpus files. */
function sessionSidecar(corpusDir: string, paths: string[], session: string): { dir: string; sidecar: SpeakerSidecar } | null {
  for (const dir of new Set([corpusDir, corpusSpoolDir(corpusDir), ...paths.map(path => dirname(path))])) {
    const sidecar = readSpeakerSidecar(dir, session);
    if (sidecar) return { dir, sidecar };
  }
  return null;
}

function sessionVerdict(session: string, index: CorpusIndex, opts: AgentSessionOptions, cwdPrefixes: string[]): Verdict {
  const fallbackPrincipal = opts.principal ?? DETECTED_PRINCIPAL;
  const corpusDir = index.corpusDir;
  const found = corpusDir ? sessionSidecar(corpusDir, index.files.get(session) ?? [], session) : null;
  if (found) {
    return { klass: 'evidenced', reason: 'speaker_sidecar', principal: found.sidecar.principal,
      evidence: `${relative(corpusDir!, join(found.dir, speakerFileName(session)))} (principal ${found.sidecar.principal})` };
  }
  if (opts.sessions?.includes(session)) return { klass: 'evidenced', reason: 'operator_session', principal: fallbackPrincipal, evidence: `--session ${session}` };
  const record = corpusDir ? readSessionSource(corpusSpoolDir(corpusDir), session) : null;
  if (record?.cwd) {
    const cwd = canonicalPath(record.cwd);
    const prefix = cwdPrefixes.find(p => under(cwd, p));
    if (prefix) return { klass: 'evidenced', reason: 'operator_cwd', principal: fallbackPrincipal, evidence: `cwd ${record.cwd} under --cwd ${prefix}` };
  }
  const key = index.openings.get(session);
  const group = key ? index.openingSessions.get(key) : undefined;
  const others = group ? group.size - (group.has(session) ? 1 : 0) : 0;
  if (others >= OPENING_MIN_OTHERS) {
    return { klass: 'ambiguous', reason: 'repeated_opening', principal: fallbackPrincipal, evidence: `first user turn shared with ${others} other session(s)` };
  }
  return !index.unreadSessions.has(session) && (index.files.has(session) || record) ? 'not_suspect' : 'unclassifiable';
}

const factHash = (row: FactRow) => digest(['agent-session-fact-v1', row.fact, row.visibility, row.entity_slug, row.row_num, row.source_markdown_slug,
  row.attributed_to, row.context]);
const targetSlug = (row: Pick<FactRow, 'source_markdown_slug' | 'entity_slug'>) => row.source_markdown_slug ?? row.entity_slug ?? 'memory/unattributed';

/**
 * Read-only: every user-attributed (or unattributed) capture-lane fact of these sources from a suspect session, classified, in (source, page, id) order.
 * Owner twins are looked up only for facts of suspect sessions, each through idx_facts_withdrawal_fingerprint (every visibility is named so the
 * index's middle column binds), so the cost follows the facts the preview lists, not the size of the facts table (#9503).
 */
export async function classifyAgentSessionFacts(db: BrainEngine, sourceIds: string[],
  opts: AgentSessionOptions & { corpusDir?: string | null; ids?: number[]; indexes?: Map<string | null, CorpusIndex> } = {}): Promise<AgentSessionFactsClassification> {
  const rows = await db.executeRaw<FactRow>(`
    SELECT f.id, f.source_id, f.source_session, f.fact, f.visibility, f.entity_slug, f.row_num, f.source_markdown_slug, f.attributed_to, f.context
      FROM facts f
     WHERE f.source_id=ANY($1::text[]) AND f.source=ANY($2::text[]) AND f.expired_at IS NULL AND f.superseded_by IS NULL
       AND (f.attributed_to IS NULL OR f.attributed_to='user') AND ($3::bigint[] IS NULL OR f.id=ANY($3::bigint[]))
     ORDER BY f.source_id, f.id`, [sourceIds, [...CAPTURE_LANES], opts.ids ?? null]);
  if (!rows.length) return { candidates: [], unclassifiable: 0, not_suspect: 0, unreadable_corpus_files: [] };
  const corpusDir = (opts.corpusDir === undefined ? await db.getConfig(CORPUS_KEY) : opts.corpusDir) ?? null;
  const index = opts.indexes?.get(corpusDir) ?? corpusIndex(corpusDir);
  opts.indexes?.set(corpusDir, index);
  const cwdPrefixes = (opts.cwdPrefixes ?? []).map(canonicalPath);
  const verdicts = new Map<string, Verdict>();
  const verdict = (sourceSession: string | null): Verdict => {
    const session = captureSessionId(sourceSession || null);
    if (!session) return 'unclassifiable';
    if (!verdicts.has(session)) verdicts.set(session, sessionVerdict(session, index, opts, cwdPrefixes));
    return verdicts.get(session)!;
  };
  const suspect: Array<{ row: FactRow; hit: Exclude<Verdict, string> }> = [];
  let unclassifiable = 0;
  let notSuspect = 0;
  for (const row of rows) {
    const hit = verdict(row.source_session);
    if (hit === 'unclassifiable') unclassifiable++;
    else if (hit === 'not_suspect') notSuspect++;
    else suspect.push({ row, hit });
  }
  const twins = new Map(!suspect.length ? [] : (await db.executeRaw<{ id: number | string; owner_twin: boolean; twin_sessions: Array<string | null> | null }>(`
    SELECT f.id,
           EXISTS (SELECT 1 FROM facts a WHERE a.source_id=f.source_id AND a.visibility IN ('private','world') AND gbrain_fact_fingerprint(a.fact)=gbrain_fact_fingerprint(f.fact)
             AND a.id<>f.id AND a.expired_at IS NULL AND a.superseded_by IS NULL AND a.entity_slug IS NOT DISTINCT FROM f.entity_slug
             AND (a.attributed_to IS NULL OR a.attributed_to='user') AND COALESCE(a.source,'') <> ALL($2::text[])) AS owner_twin,
           ARRAY(SELECT DISTINCT COALESCE(a.source_session,'') FROM facts a WHERE a.source_id=f.source_id AND a.visibility IN ('private','world')
             AND gbrain_fact_fingerprint(a.fact)=gbrain_fact_fingerprint(f.fact) AND a.id<>f.id AND a.expired_at IS NULL AND a.superseded_by IS NULL
             AND a.entity_slug IS NOT DISTINCT FROM f.entity_slug AND (a.attributed_to IS NULL OR a.attributed_to='user') AND a.source=ANY($2::text[])) AS twin_sessions
      FROM facts f
     WHERE f.id=ANY($1::bigint[])`, [suspect.map(({ row }) => Number(row.id)), [...CAPTURE_LANES]])).map(row => [Number(row.id), row]));
  const candidates: AgentSessionFactCandidate[] = suspect.map(({ row, hit }) => {
    const twin = twins.get(Number(row.id));
    const owner = !!twin && (twin.owner_twin || (twin.twin_sessions ?? []).some(s => typeof verdict(s) === 'string'));
    return { id: Number(row.id), source_id: row.source_id, slug: targetSlug(row), row_num: row.row_num === null ? null : Number(row.row_num),
      class: owner ? 'excluded' : hit.klass, reason: owner ? 'excluded:owner_also_said' : hit.reason, session: captureSessionId(row.source_session)!,
      evidence: hit.evidence, principal: hit.principal, fact_hash: factHash(row) };
  });
  candidates.sort((a, b) => a.source_id.localeCompare(b.source_id) || a.slug.localeCompare(b.slug) || a.id - b.id);
  return { candidates, unclassifiable, not_suspect: notSuspect,
    unreadable_corpus_files: index.unreadable.map(path => !corpusDir ? path : relative(corpusDir, path) || basename(path)) };
}

/**
 * Active, unresolved `kind: fact` / `holder: self` takes whose every contributing fact is non-user once the facts in
 * `reattributed` are: at least one of them must be in that set or already carry a speaker note, so takes this repair
 * has nothing to do with are never listed. Contributing facts are grouped in one pass over the listed sources' facts,
 * never one pass per take (#9503) and never over other sources: consolidation only links a fact to a take on a page of
 * the fact's own source.
 */
export async function agentSessionTakes(db: BrainEngine, sourceIds: string[], reattributed: ReadonlySet<number>, ids?: number[]): Promise<AgentSessionTake[]> {
  const rows = await db.executeRaw<{ id: number | string; source_id: string; slug: string; row_num: number | string; claim: string;
    fact_ids: Array<number | string>; user_fact_ids: Array<number | string>; noted: boolean }>(`
    WITH contributing AS (
      SELECT f.consolidated_into AS take_id, array_agg(f.id ORDER BY f.id) AS fact_ids,
             COALESCE(array_agg(f.id ORDER BY f.id) FILTER (WHERE f.attributed_to IS NULL OR f.attributed_to='user'), '{}'::bigint[]) AS user_fact_ids,
             COALESCE(bool_or(f.attributed_to='other' AND position($3::text in COALESCE(f.context,''))>0), false) AS noted,
             min(f.consolidated_at) AS first_consolidated_at
        FROM facts f
       WHERE f.source_id=ANY($1::text[]) AND f.consolidated_into IS NOT NULL AND ($2::bigint[] IS NULL OR f.consolidated_into=ANY($2::bigint[]))
       GROUP BY f.consolidated_into)
    SELECT t.id, p.source_id, p.slug, t.row_num, t.claim, c.fact_ids, c.user_fact_ids, c.noted
      FROM contributing c JOIN takes t ON t.id=c.take_id JOIN pages p ON p.id=t.page_id
     WHERE p.source_id=ANY($1::text[]) AND t.kind='fact' AND t.holder='self' AND t.active AND t.resolved_at IS NULL
       AND t.created_at >= c.first_consolidated_at - interval '1 second'
     ORDER BY p.source_id, p.slug, t.id`, [sourceIds, ids ?? null, NOTE_MARK]);
  return rows.filter(row => row.user_fact_ids.every(id => reattributed.has(Number(id))) && (row.noted || row.user_fact_ids.length > 0))
    .map(row => {
      const factIds = row.fact_ids.map(Number);
      return { id: Number(row.id), source_id: row.source_id, slug: row.slug, row_num: Number(row.row_num), claim: row.claim, fact_ids: factIds,
        take_hash: digest(['agent-session-take-v1', Number(row.id), row.slug, Number(row.row_num), row.claim, factIds]) };
    });
}

/** The evidence flags as CLI arguments, in their normalized order. */
export function agentSessionFlagArgs(opts: AgentSessionOptions): string[] {
  const normal = normalizeAgentSessionOptions(opts);
  return [...normal.cwdPrefixes.flatMap(p => ['--cwd', p]), ...normal.sessions.flatMap(s => ['--session', s]), ...(normal.principal ? ['--principal', normal.principal] : [])];
}

function previewCommand(scope: RepairScope, all: string[], opts: AgentSessionOptions, includeAmbiguous: boolean): string {
  const source = scope.source_ids.length === 1 && all.length > 1 ? ` --source ${scope.source_ids[0]}` : '';
  return `gbrain repair ${COMMAND}${source}${agentSessionFlagArgs(opts).map(arg => ` ${shellQuote(arg)}`).join('')}${includeAmbiguous ? ' --include-ambiguous' : ''}`;
}

async function activeSources(engine: BrainEngine): Promise<string[]> {
  return (await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE archived IS NOT TRUE ORDER BY id')).map(row => row.id);
}

async function brainId(engine: BrainEngine): Promise<string> {
  const [brain] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1').catch(() => []);
  return brain?.brain_id ?? 'host';
}

/**
 * One item per write, in cursor order. A fact page with both database-only and fenced rows is two items, the fenced one
 * after every fact page (`id` = page count + index), so a database write still pending never skips the page's fenced
 * rows and the runner holds the fenced rewrite until that write settles, like any later write to the same page.
 */
function pageItems(approved: ApprovedPage[], hash: string, options: AgentSessionOptions, indexes: Map<string | null, CorpusIndex>): PageItem[] {
  const parts = approved.flatMap((page, i) => {
    const fenced = page.facts?.filter(f => f.row_num !== null) ?? [];
    return !fenced.length || fenced.length === page.facts!.length ? [{ page, id: i }]
      : [{ page: { ...page, facts: page.facts!.filter(f => f.row_num === null) }, id: i }, { page: { ...page, facts: fenced }, id: approved.length + i }];
  }).sort((a, b) => Number(!a.page.facts) - Number(!b.page.facts) || a.id - b.id);
  return parts.map(({ page, id }, i) => ({ cursor: { phase: page.facts ? 0 : 1, id }, source_id: page.source_id, slug: page.slug, chars: 0,
    action: page.facts ? `re-attribute ${page.facts.length} agent-session fact(s)` : `retire ${page.takes!.length} take(s)`, page, hash, last: i === parts.length - 1,
    options, indexes }));
}

function groupByPage<T extends { source_id: string; slug: string }>(rows: T[], make: (first: T) => ApprovedPage, field: 'facts' | 'takes'): ApprovedPage[] {
  const pages = new Map<string, ApprovedPage>();
  for (const row of rows) {
    const key = `${row.source_id}\u0000${row.slug}`;
    const page = pages.get(key) ?? make(row);
    (page[field] as unknown as T[]).push(row);
    pages.set(key, page);
  }
  return [...pages.values()];
}

const evidenceOptions = (opts: RepairPlanOptions | undefined) =>
  normalizeAgentSessionOptions({ cwdPrefixes: opts?.cwdPrefixes, sessions: opts?.sessions, principal: opts?.principal });

export const agentSessionFactsRepair: RepairHandler = {
  kind: 'agent-session-facts',
  embeds: false,
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    const includeAmbiguous = opts?.includeAmbiguous === true;
    const options = evidenceOptions(opts);
    const optionsKey = JSON.stringify(options);
    const command = previewCommand(scope, await activeSources(engine), options, includeAmbiguous);
    const hashOf = async (candidates: AgentSessionFactCandidate[], takes: AgentSessionTake[]) => previewHash(['agent-session-facts-v1', await brainId(engine),
      scope.source_ids, includeAmbiguous, options, candidates.map(c => [c.id, c.class, c.reason, c.principal, c.fact_hash]), takes.map(t => [t.id, t.take_hash])]);
    if (!opts?.apply) {
      const { candidates, unclassifiable, not_suspect, unreadable_corpus_files } = await classifyAgentSessionFacts(engine, scope.source_ids, options);
      const approvedFacts = candidates.filter(c => c.class === 'evidenced' || (c.class === 'ambiguous' && includeAmbiguous));
      const takes = await agentSessionTakes(engine, scope.source_ids, new Set(approvedFacts.map(c => c.id)));
      const hash = await hashOf(candidates, takes);
      const base = (row: { source_id: string; slug: string }) => ({ source_id: row.source_id, slug: row.slug, include_ambiguous: includeAmbiguous,
        scope: scope.source_ids, options: optionsKey });
      const approved = [...groupByPage(approvedFacts, row => ({ ...base(row), facts: [] }), 'facts'), ...groupByPage(takes, row => ({ ...base(row), takes: [] }), 'takes')];
      if (approved.length) await saveApprovedSet(engine, { command: COMMAND, hash }, approved);
      const count = (klass: AgentSessionFactClass) => candidates.filter(c => c.class === klass).length;
      const listing: RepairListing[] = candidates.map(c => ({ item: `${c.source_id}:${c.slug}#${c.id}`, class: c.class === 'excluded' ? c.reason : c.class,
        detail: `${c.reason}; session ${c.session}; ${c.evidence}; principal ${c.principal}` }));
      for (const take of takes) listing.push({ item: `${take.source_id}:${take.slug}@take:${take.id}`, class: 'take_to_retire',
        detail: `row ${take.row_num}; contributing facts ${take.fact_ids.join(', ')}` });
      for (const path of unreadable_corpus_files) listing.push({ item: path, class: 'unreadable_corpus_file',
        detail: 'not read (check its permissions); facts of its sessions are counted unclassifiable and kept' });
      return { items: pageItems(approved, hash, options, new Map()), preview_hash: hash, listing,
        residuals: { evidenced: count('evidenced'), ambiguous: count('ambiguous'), excluded: count('excluded'), unclassifiable, not_suspect, takes_to_retire: takes.length,
          ...(unreadable_corpus_files.length ? { unreadable_corpus_files: unreadable_corpus_files.length } : {}) } };
    }
    if (!opts.expect) {
      throw new OperationError('invalid_params', `gbrain repair ${COMMAND} --apply re-attributes only the set a preview printed.`,
        `Preview first: ${command} — then run the apply command it prints after the user agrees: ${command} --apply --expect <preview-hash> --yes`,
        'docs/guides/repair.md#explicit-only-repair-kinds');
    }
    const approved = await loadApprovedSet<ApprovedPage>(engine, { command: COMMAND, hash: opts.expect, previewCommand: command, emptyHash: () => hashOf([], []) });
    const scopeKey = JSON.stringify(scope.source_ids);
    if (approved.items.some(page => page.include_ambiguous !== includeAmbiguous || JSON.stringify(page.scope) !== scopeKey || page.options !== optionsKey)) {
      throw previewChangedError(opts.expect, command);
    }
    const items = pageItems(approved.items, opts.expect, options, new Map()).filter(item => afterCursor(item.cursor, after));
    if (!items.length) await clearApprovedSet(engine, { command: COMMAND, hash: opts.expect });
    return { items, preview_hash: opts.expect, residuals: { approved_pages: approved.items.length, pending_pages: items.length } };
  },
  async apply(ctx, entry): Promise<RepairItemOutcome> {
    const { page, hash, last, options, indexes } = entry as PageItem;
    const engine = ctx.engine;
    const done: number[] = [];
    if (page.facts) {
      const live = new Map((await classifyAgentSessionFacts(engine, [page.source_id], { ...options, ids: page.facts.map(f => f.id), indexes })).candidates.map(c => [c.id, c]));
      const gone = page.facts.filter(f => !live.has(f.id));
      const settled = gone.length ? await engine.executeRaw<{ id: number | string; context: string | null }>(
        "SELECT id, context FROM facts WHERE source_id=$1 AND id=ANY($2::bigint[]) AND attributed_to='other' AND expired_at IS NULL AND superseded_by IS NULL",
        [page.source_id, gone.map(f => f.id)]) : [];
      done.push(...gone.filter(f => settled.some(row => Number(row.id) === f.id && (row.context ?? '').includes(speakerContextNote(f.principal)))).map(f => f.id));
      const unchanged = page.facts.filter(f => {
        const current = live.get(f.id);
        return !!current && (['class', 'reason', 'principal', 'fact_hash', 'slug', 'row_num'] as const).every(field => current[field] === f[field]);
      });
      const dbOnly = unchanged.filter(f => f.row_num === null);
      if (dbOnly.length) done.push(...await databaseWrite(engine, page, hash, { facts: dbOnly.map(f => ({ id: f.id, note: speakerContextNote(f.principal) })) }));
      const fenced = unchanged.filter(f => f.row_num !== null);
      if (fenced.length) done.push(...await rewriteFencedFacts(ctx, entry, page, fenced));
    } else {
      const live = new Map((await agentSessionTakes(engine, [page.source_id], new Set(), page.takes!.map(t => t.id))).map(t => [t.id, t]));
      const unchanged = page.takes!.filter(t => live.get(t.id)?.take_hash === t.take_hash);
      if (unchanged.length) done.push(...await retireTakes(ctx, entry, page, hash, unchanged));
    }
    if (last) await clearApprovedSet(engine, { command: COMMAND, hash });
    const all = (page.facts ?? page.takes!).map(row => row.id);
    const changed = all.filter(id => !done.includes(id));
    const verb = page.facts ? 'reattributed' : 'retired';
    return { applied: done.length > 0, outcome: !changed.length ? verb : done.length ? `partially_${verb}` : 'changed_since_preview',
      ...(changed.length ? { reason: `${done.length} of ${all.length} ${verb}; changed since the preview: ${changed.join(', ')}` } : {}) };
  },
};

/** One approved database-only write: facts to re-attribute (each with its speaker note) and takes to retire. */
export interface AgentSessionWrite { facts?: Array<{ id: number; note: string }>; take_ids?: number[] }

/**
 * Re-attributes each named database-only fact still user-attributed and active, appending its note once, and retires
 * each named take still active, unresolved, `kind: fact` / `holder: self` on a page of the source whose every
 * contributing fact is non-user. The checks run in the UPDATEs, under the row locks. Returns the changed ids.
 */
export async function applyAgentSessionWrite(tx: BrainEngine, sourceId: string, write: AgentSessionWrite): Promise<{ reattributed: number[]; retired: number[] }> {
  const reattributed = write.facts?.length ? (await tx.executeRaw<{ id: number | string }>(`UPDATE facts f
      SET attributed_to='other',
          context=CASE WHEN position(r.note in COALESCE(f.context,''))>0 THEN f.context ELSE concat_ws($3::text, NULLIF(f.context,''), r.note) END
     FROM jsonb_to_recordset($2::text::jsonb) AS r(id bigint, note text)
    WHERE f.source_id=$1 AND f.id=r.id AND (f.attributed_to IS NULL OR f.attributed_to='user') AND f.expired_at IS NULL AND f.superseded_by IS NULL
      AND f.row_num IS NULL
    RETURNING f.id`, [sourceId, JSON.stringify(write.facts), NOTE_SEPARATOR])).map(row => Number(row.id)) : [];
  const retired = write.take_ids?.length ? (await tx.executeRaw<{ id: number | string }>(`UPDATE takes t SET active=false, updated_at=now()
     FROM pages p
    WHERE p.id=t.page_id AND p.source_id=$1 AND t.id=ANY($2::bigint[]) AND t.active AND t.resolved_at IS NULL AND t.kind='fact' AND t.holder='self'
      AND t.created_at >= (SELECT min(f.consolidated_at) FROM facts f WHERE f.consolidated_into=t.id) - interval '1 second'
      AND NOT EXISTS (SELECT 1 FROM facts f WHERE f.consolidated_into=t.id AND (f.attributed_to IS NULL OR f.attributed_to='user'))
    RETURNING t.id`, [sourceId, write.take_ids])).map(row => Number(row.id)) : [];
  return { reattributed, retired };
}

/** Database-only rows: one maintenance request on the page key on a managed brain (owner-checked, receipted); one transaction otherwise. */
async function databaseWrite(engine: BrainEngine, page: ApprovedPage, hash: string, write: AgentSessionWrite): Promise<number[]> {
  const key = write.facts ? 'reattributed' : 'retired';
  if (!await managedPersistenceEnabled(engine)) return (await maintenanceTransaction(engine, tx => applyAgentSessionWrite(tx, page.source_id, write)))[key];
  const authority = (await maintenancePreflight(engine, page.source_id))!;
  const snapshot = await engine.readPageSnapshot(page.slug, { sourceId: page.source_id });
  const h = digest(['agent-session-facts-write-v1', hash, page.source_id, page.slug, write, snapshot?.revision ?? null]);
  const receipt = await submitDatabaseMaintenanceIntent(engine, authority, page.slug,
    { kind: AGENT_SESSION_FACTS_INTENT, expected_revision: snapshot?.revision ?? null, ...write },
    `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`);
  return (receipt[key] as number[] | undefined) ?? [];
}

/** Preparer for `managed_maintenance_agent_session_facts`: re-attributes the named database-only facts and retires the named takes. */
export async function prepareAgentSessionFactsWrite(engine: BrainEngine, row: WriteRequest): Promise<PreparedMutation> {
  const intent = (row.intent ?? {}) as { facts?: unknown; take_ids?: unknown };
  const facts = intent.facts ?? [];
  const takeIds = intent.take_ids ?? [];
  const valid = Array.isArray(facts) && facts.every(f => !!f && typeof f === 'object' && Number.isSafeInteger((f as { id: unknown }).id)
    && typeof (f as { note: unknown }).note === 'string') && Array.isArray(takeIds) && takeIds.every(id => Number.isSafeInteger(id)) && facts.length + takeIds.length > 0;
  if (!valid) {
    throw opError('invalid_params', 'The agent-session facts intent does not name its facts or takes.',
      `Request ${row.request_id} in source ${row.source_id} does not name the facts or takes to change, so nothing changed. Preview the repair again and apply the new preview after the user approves.`,
      { fix: readFix('Previews the agent-session-facts repair without changing anything.', { argv: ['gbrain', 'repair', COMMAND, '--source', row.source_id, '--json'] }) });
  }
  const snapshot = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id });
  await authorizeWrite(engine, row.authority, 'submit_job', row.slug);
  return { observedRevision: snapshot?.revision ?? null, noop: true,
    validate: async tx => { await authorizeWrite(tx, row.authority, 'submit_job', row.slug); },
    apply: async tx => ({ status: 'completed', ...await applyAgentSessionWrite(tx, row.source_id,
      { facts: facts as Array<{ id: number; note: string }>, take_ids: takeIds as number[] }) }) };
}

/**
 * Fenced facts: set `attributed_to: other` and append the note on each still-matching, still user-attributed active
 * fence row and publish the page once, bound to the revision read; the canonical projection rewrites the rows in
 * place. Returns the facts that now read back as `other`. A page stored in segments (#9027) is read back whole, as
 * every fence write through the put path reads it, and one over 24 MiB declines `page_body_segmented`, its rows kept.
 */
async function rewriteFencedFacts(ctx: Parameters<RepairHandler['apply']>[0], item: RepairItem, page: ApprovedPage, facts: AgentSessionFactCandidate[]): Promise<number[]> {
  const engine = ctx.engine;
  const snapshot = await wholeBodySnapshot(engine, await engine.readPageSnapshot(page.slug, { sourceId: page.source_id }), 'repair agent-session-facts');
  if (!snapshot) return [];
  const rows = await engine.executeRaw<{ id: number | string; fact: string; row_num: number }>(
    'SELECT id, fact, row_num FROM facts WHERE source_id=$1 AND id=ANY($2::bigint[]) AND expired_at IS NULL', [page.source_id, facts.map(f => f.id)]);
  let body = snapshot.page.compiled_truth ?? '';
  const rewritten: number[] = [];
  for (const row of rows) {
    const note = speakerContextNote(facts.find(f => f.id === Number(row.id))!.principal);
    const fenceRow = parseFactsFence(body).facts.find(f => f.rowNum === Number(row.row_num));
    if (!fenceRow?.active || fenceRow.claim.trim() !== row.fact.trim() || (fenceRow.attributedTo !== undefined && fenceRow.attributedTo !== 'user')) continue;
    const next = strikeFenceRow(body, Number(row.row_num), current => ({ ...current, attributedTo: 'other',
      context: current.context?.includes(note) ? current.context : [current.context?.trim(), note].filter(Boolean).join(NOTE_SEPARATOR) }));
    if (next === null) continue;
    body = next;
    rewritten.push(Number(row.id));
  }
  if (!rewritten.length) return [];
  await submitPageMutation(ctx, { operation: 'put_page', params: { slug: page.slug, source_id: page.source_id,
    content: serializePageToMarkdown({ ...snapshot.page, compiled_truth: body }, snapshot.tags), expected_revision: snapshot.revision,
    request_id: await repairRequestId(ctx, 'agent-session-facts', item, snapshot.revision) } });
  return (await engine.executeRaw<{ id: number | string }>("SELECT id FROM facts WHERE source_id=$1 AND id=ANY($2::bigint[]) AND attributed_to='other'",
    [page.source_id, rewritten])).map(row => Number(row.id));
}

/**
 * Takes: a take the page's takes fence holds (same row and claim, active) is struck there by one revision-bound
 * `put_page` (the projection sets `active = false`); the rest are retired in the database. A page stored in
 * segments is read back whole, as rewriteFencedFacts reads it. Returns the retired takes.
 */
async function retireTakes(ctx: Parameters<RepairHandler['apply']>[0], item: RepairItem, page: ApprovedPage, hash: string, takes: AgentSessionTake[]): Promise<number[]> {
  const engine = ctx.engine;
  const snapshot = await wholeBodySnapshot(engine, await engine.readPageSnapshot(page.slug, { sourceId: page.source_id }), 'repair agent-session-facts');
  const body = snapshot ? serializePageToMarkdown(snapshot.page, snapshot.tags) : '';
  const fence = parseTakesFence(body);
  const fenced = takes.filter(t => fence.takes.some(row => row.rowNum === t.row_num && row.claim.trim() === t.claim.trim() && row.active));
  const retired: number[] = [];
  const databaseOnly = fence.takes.length ? [] : takes.filter(t => !fenced.includes(t)); // a fenced page's unmatched take stays: the file is the parent
  if (databaseOnly.length) retired.push(...await databaseWrite(engine, page, hash, { take_ids: databaseOnly.map(t => t.id) }));
  if (fenced.length && snapshot) {
    const rows = new Set(fenced.map(t => t.row_num));
    const content = takesPreparation.replaceFence(body, fence.takes.map(row => rows.has(row.rowNum) ? { ...row, active: false } : row));
    await submitPageMutation(ctx, { operation: 'put_page', params: { slug: page.slug, source_id: page.source_id, content,
      expected_revision: snapshot.revision, request_id: await repairRequestId(ctx, 'agent-session-facts', item, snapshot.revision) } });
    retired.push(...(await engine.executeRaw<{ id: number | string }>('SELECT id FROM takes WHERE id=ANY($1::bigint[]) AND active=false',
      [fenced.map(t => t.id)])).map(row => Number(row.id)));
  }
  return retired;
}