Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
31.2 KB
Raw Blame
/**
 * `gbrain sources writer deactivate` (#5455, #5628): a deliberate, state-bound
 * conversion from managed mode back to classic mode. Brain-wide and
 * trusted-local only.
 *
 * Deactivate takes the native worktree locks like activation, then in one
 * transaction locks `persistence_brain FOR UPDATE` first, checks the expected
 * admin state and the writer admin lock, locks worktrees then sources (the
 * order admission uses) and rechecks quiescence: no request queued, running or
 * recovering, no request or topology change with a recovery record, no queued,
 * running or recovering effect, no live connector or maintenance lease. A
 * terminally failed effect can no longer change, so it does not block: the
 * report lists it in `failed_effects` with its code and exit. It then sets
 * `enabled=false`, increments `mode_epoch`, marks every worktree `retired`
 * (rows kept for receipt and effect foreign keys), deletes source and host
 * bindings, and records a committed `writer_deactivate` topology change naming
 * the brain, the retired epoch and the retired worktree ids and roots. Skill
 * bundle and protocol-floor settings and writer protocol registrations are
 * kept (inert while disabled).
 *
 * Local markers (registry records, `.gbrain-managed`, Git `gbrain-managed.json`,
 * `.gbrain-owner.json` and its reservation) are removed by
 * `cleanupRetiredManagedMarkers` only when they name this brain and a retired
 * epoch (or, without an epoch, a retired worktree id or root) recorded by a
 * committed deactivation; a newer or unknown one is kept and reported pending.
 */
import { randomUUID } from 'node:crypto';
import { DATABASE_ONLY_SOURCES_KEY } from './unbound-source.ts';
import { NOT_PAGE_EMBEDDING_LEASE } from '../page-embedding-lease.ts';
import { existsSync, lstatSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { configDir } from '../config.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { acquireWorktree, getWorktreeBinding, readPersistenceBrain, type PersistenceBrainRow } from './ownership.ts';
import { existingHostIdFor } from './identity.ts';
import type { NativeLockHandle } from './native-lock.ts';
import { assertWriterAdminState } from './admin-intent.ts';
import { assertWriterAdminUnlocked, readWriterAdminLock, WRITER_ADMIN_LOCKED_DOCS } from './admin-lock.ts';
import { managedFilesystemDatastorePath, refreshManagedFilesystemRoots } from './filesystem-guard.ts';
import { recordTopologyChange } from './topology-receipts.ts';
import { lockTopologyPrincipal, topologyPrincipal } from './topology-locks.ts';
import { canonicalFilesystemPath } from './root-registry.ts';
import { carryHoldsToClassicState, holdCarryBlocked, planHoldCarry, type HoldCarry } from '../connectors/item-holds-store.ts';
import { assertPhysicalRoot, assertPhysicalRootReservation, PHYSICAL_ROOT_MARKER, physicalRootReservationPath } from './physical-root-record.ts';
import { preActivationClaims, releasePreActivationClaims, type PreActivationClaim } from './pre-activation-release.ts';
import { PARK_AFTER_FAILURES } from './effect-model.ts';
import { EMBEDDING_ZERO_NORM } from '../ai/embedding-guard.ts';

export const DEACTIVATE_DOCS = 'docs/architecture/topologies.md#deactivate-runbook';

export interface DeactivationBlocker {
  kind: 'writer_admin_lock' | 'request' | 'topology_recovery' | 'effect' | 'lease' | 'connector_holds' | 'physical_root';
  id: string;
  source_id?: string;
  detail: string;
  /** The supported exit, filled with real values. */
  exit: string;
}

/** GBRA-130 A-15: a terminally failed effect, reported as history; `exit` is the command that retries it, or null when nothing can. */
export interface FailedEffectEntry {
  effect_id: string; kind: string; source_id: string; request_id: string; code: string | null;
  exit: string | null;
  detail: string;
}

export interface LocalMarkerReport {
  state: 'cleared' | 'pending';
  removed: string[];
  pending: Array<{ path: string; reason: string }>;
  rerun?: string;
}

export interface DeactivationReport {
  mode: 'classic' | 'managed';
  deactivated: boolean;
  dry_run: boolean;
  mode_epoch: number;
  retired_mode_epoch?: number;
  retired_worktrees: Array<{ id: string; roots: string[] }>;
  source_bindings: number;
  kept: { skill_bundles_enabled: boolean; writer_protocol_floor: number; writer_protocol_registrations: number };
  blockers: DeactivationBlocker[];
  /** Held connector items copied (or, on a dry run, to be copied) into each source's classic state file. */
  carried_holds?: HoldCarry[];
  /** Terminally failed effects (history, never blockers), at most 50, each with its code and exit. */
  failed_effects?: FailedEffectEntry[];
  /** #6122: on a never-activated brain, the claimed sources a deactivation releases (dry run) or released. */
  pre_activation_claims?: PreActivationClaim[];
  local_markers?: LocalMarkerReport;
}

type BrainRow = PersistenceBrainRow;

/** #6482: the shared fail-closed read; a missing, duplicated or non-boolean singleton refuses `storage_error`. */
function readBrain(engine: BrainEngine, lock = false): Promise<BrainRow> {
  return readPersistenceBrain(engine, lock ? { lock: 'update' } : {});
}

/** Every piece of work that keeps the brain from quiescing, with its CLI exit. Read-only. */
export async function deactivationBlockers(engine: BrainEngine): Promise<DeactivationBlocker[]> {
  const blockers: DeactivationBlocker[] = [];
  const lock = await readWriterAdminLock(engine);
  if (lock.locked) blockers.push({ kind: 'writer_admin_lock', id: 'persistence.writer_admin_lock', detail: `set at ${lock.set_at ?? 'unknown'}`,
    exit: 'gbrain sources writer unlock' });
  const requests = await engine.executeRaw<{ request_id: string; source_id: string; slug: string; operation: string; state: string; recovering: boolean }>(
    `SELECT request_id::text AS request_id, source_id, slug, operation, state, recovery IS NOT NULL AS recovering FROM persistence_requests
     WHERE state IN ('queued','deferred','running','recovering') OR recovery IS NOT NULL ORDER BY sequence LIMIT 50`);
  for (const r of requests) {
    blockers.push({ kind: 'request', id: r.request_id, source_id: r.source_id, detail: `${r.operation} ${r.state}${r.recovering ? ', recovering' : ''} (${r.source_id}:${r.slug})`,
      exit: r.state === 'queued' && !r.recovering ? `gbrain cancel-write-request ${r.request_id} (MCP: cancel_write_request), or wait for the owner to publish it`
        : r.state === 'running' && !r.recovering ? 'wait for the owner to finish publishing it, then rerun deactivate'
          : `gbrain sync --source ${r.source_id} --no-pull` });
  }
  const topology = await engine.executeRaw<{ id: string; operation: string; source_id: string; request_id: string; admission: boolean; automatic: boolean }>(
    "SELECT id::text AS id, operation, source_id, request_id::text AS request_id, (state='recovering' AND recovery IS NULL) AS admission, COALESCE(outcome->>'expired_only','false')='true' AS automatic FROM persistence_topology_changes WHERE state='recovering' OR recovery IS NOT NULL ORDER BY created_at LIMIT 20");
  for (const t of topology) blockers.push({ kind: 'topology_recovery', id: t.id, source_id: t.source_id,
    detail: !t.admission ? `${t.operation} for ${t.source_id} is recovering`
      : `${t.automatic ? 'automatic expired-archive purge' : t.operation} of ${t.source_id} (request ${t.request_id}) stopped before it finished`,
    exit: t.admission && t.automatic ? `the next automatic expired-archive purge finishes it, or gbrain sources purge with no source id finishes it now (gbrain sources writer status --source ${t.source_id} --json lists the request), then rerun deactivate`
      : t.admission ? `ask the user whether to finish it, because finishing deletes the rest of ${t.source_id}'s pages: to finish, rerun the same gbrain sources ${t.operation} command with all its original flags and --request-id ${t.request_id} (an automatic expired-archive purge finishes on its next run); to keep what is left, any other lifecycle change to the source (gbrain sources restore of an archived source, or archive then restore) abandons the request; then rerun deactivate`
      : `gbrain sources writer status ${t.source_id} --json, then let the owner finish recovery` });
  // GBRA-130 A-15: only work that can still change blocks, as activation checks; terminal failures are failedEffectHistory's.
  const effects = await engine.executeRaw<EffectRow>(`${EFFECT_ROWS} WHERE e.state IN ('queued','running') OR e.recovery IS NOT NULL ORDER BY e.id LIMIT 50`);
  for (const e of effects) {
    blockers.push({ kind: 'effect', id: e.effect_id, source_id: e.source_id, detail: `${e.kind} effect ${e.state}${e.recovering ? ', recovering' : ''}${e.error_code ? ` (${e.error_code})` : ''} for request ${e.request_id}`,
      exit: e.kind === 'links' || e.kind === 'facts-backstop'
        ? `wait for the owner to drain it (a ${e.kind} effect that keeps failing settles after ${PARK_AFTER_FAILURES} attempts), then rerun deactivate`
        : e.kind === 'embedding' && !e.recovering
          ? `wait for the owner to drain it, then rerun deactivate; one still queued after an hour is re-queued by gbrain repair embedding-effects --source ${e.source_id}`
          : 'wait for the owner to drain it, then rerun deactivate' });
  }
  // Managed connector holds live in the managed checkpoint, which classic mode does not read. Deactivation copies
  // them into each source's classic state file; only a source whose holds have nowhere to go blocks it.
  for (const carry of await planHoldCarry(engine, existingHostIdFor(engine))) {
    if (!holdCarryBlocked(carry)) continue;
    const resolve = `gbrain sources status ${carry.source_id} names each item's error; fix its cause, then gbrain sources retry-held ${carry.source_id} and gbrain sync --source ${carry.source_id} (a successful re-attempt clears the hold)`;
    blockers.push({ kind: 'connector_holds', id: carry.source_id, source_id: carry.source_id,
      detail: carry.owner_host
        ? `${carry.items} held item(s) on a worktree owned by host ${carry.owner_host}; deactivate cannot write that host's classic state`
        : carry.state_file
          ? `${carry.items} held item(s); the classic state file ${carry.state_file} does not parse (${carry.unreadable})`
          : `${carry.items} held item(s) and no classic state directory to carry them into`,
      exit: carry.owner_host
        ? `run deactivate on host ${carry.owner_host}; or ${resolve}`
        : carry.state_file ? `move ${carry.state_file} aside, then rerun deactivate; or ${resolve}` : resolve });
  }
  const leases = await engine.executeRaw<{ id: string; holder_host: string; holder_pid: number }>(
    `SELECT id, holder_host, holder_pid FROM gbrain_cycle_locks WHERE ttl_expires_at > now() AND ${NOT_PAGE_EMBEDDING_LEASE} ORDER BY id`);
  for (const l of leases) blockers.push({ kind: 'lease', id: l.id, detail: `held by host ${l.holder_host}, pid ${l.holder_pid}`,
    exit: 'wait for that connector sync or maintenance run to finish (gbrain doctor shows live locks), then rerun deactivate' });
  return blockers;
}

type EffectRow = { effect_id: string; kind: string; state: string; source_id: string; request_id: string; error_code: string | null; recovering: boolean; source_live: boolean };
const EFFECT_ROWS = `SELECT e.id::text AS effect_id, e.kind, e.state, COALESCE(e.source_id, r.source_id) AS source_id, r.request_id::text AS request_id, e.error_code,
       e.recovery IS NOT NULL AS recovering,
       EXISTS (SELECT 1 FROM sources s WHERE s.id = r.source_id AND s.incarnation = r.source_incarnation AND NOT s.archived) AS source_live
     FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id`;

/**
 * GBRA-130 A-15: terminally failed effects, oldest first (at most 50). They block nothing; each carries the exit that
 * retries it: retry-effects for parked targets and failed Git, withdrawal, links and facts-backstop effects,
 * `repair embedding-effects` for a failed embedding effect, and none for a zero-norm refusal (the same input returns
 * the same vector) or an effect whose source was archived, replaced or removed.
 */
export async function failedEffectHistory(engine: BrainEngine): Promise<FailedEffectEntry[]> {
  const rows = await engine.executeRaw<EffectRow>(`${EFFECT_ROWS} WHERE e.state='failed' AND e.recovery IS NULL AND NOT (e.data ? 'settled') ORDER BY e.id LIMIT 50`);
  return rows.map(e => {
    const retry = `gbrain sources writer retry-effects ${e.source_id} --request-id ${e.request_id} --dry-run`;
    const [exit, why] = !e.source_live ? [null, 'its source was archived, replaced or removed, so nothing can run it']
      : e.kind !== 'embedding' || e.error_code === 'targets_parked' ? [retry, 'preview it, fix the recorded cause, then run the command without --dry-run']
        : e.error_code === EMBEDDING_ZERO_NORM ? [null, 'the provider returns a zero vector for this text, so a retry fails the same way; the page keeps no signature, so gbrain embed --stale retries it under another model']
          : [`gbrain repair embedding-effects --source ${e.source_id}`, 'preview the bounded retry, then apply it with --apply after the user approves the cost'];
    return { effect_id: e.effect_id, kind: e.kind, source_id: e.source_id, request_id: e.request_id, code: e.error_code, exit,
      detail: `${e.kind} effect failed${e.error_code ? ` (${e.error_code})` : ''} for request ${e.request_id}: ${why}` };
  });
}

/**
 * #5914 [R9a]: the `physical_root` blockers of this host's owned checkouts, probed
 * exactly as the real operation of each mode will: the managed run takes the
 * strict worktree lock (inode and birth time compared), the classic release
 * publishes nothing and checks only the reservation's worktree id and token.
 * Each preview therefore lists what its own real run would refuse on.
 */
export async function physicalRootBlockers(engine: BrainEngine, mode: 'managed' | 'classic'): Promise<DeactivationBlocker[]> {
  const hostId = existingHostIdFor(engine);
  const sources = mode === 'managed'
    ? await engine.executeRaw<{ id: string }>('SELECT source_id AS id FROM persistence_source_bindings ORDER BY source_id')
    : (await preActivationClaims(engine)).map(claim => ({ id: claim.source_id }));
  const blockers: DeactivationBlocker[] = [];
  const seen = new Set<string>();
  for (const { id } of sources) {
    const binding = await getWorktreeBinding(engine, id, hostId);
    if (!binding || binding.owner_host_id !== hostId || !binding.local_path || !binding.coordination_path || seen.has(binding.worktree_id)) continue;
    seen.add(binding.worktree_id);
    const identity = { worktreeId: binding.worktree_id, coordinationPath: binding.coordination_path };
    try { if (mode === 'managed') assertPhysicalRoot(binding.local_path, identity); else assertPhysicalRootReservation(binding.local_path, identity); }
    catch (error) {
      const detail = error instanceof OperationError ? error.message : String(error);
      blockers.push({ kind: 'physical_root', id: binding.worktree_id, source_id: id, detail: `${binding.local_path}: ${detail}`,
        exit: mode === 'managed'
          ? `gbrain sources writer status ${id} --json, then (same path, directory recreated) gbrain sources writer transfer prepare ${id} --self-transfer --confirm-relocated-root --admin-intent writer_transfer_prepare --expected-state <admin_state> `
            + `and gbrain sources writer transfer accept ${id} --path ${binding.local_path} --expected-epoch <owner_epoch> --manifest <digest> --self-transfer --confirm-relocated-root --admin-intent writer_transfer_accept --expected-state <admin_state>; `
            + 'a checkout moved behind a symlink converges with gbrain sources set-path instead'
          : `gbrain sources writer status ${id} --json; the reservation beside ${binding.local_path} must name this worktree and its stamp must carry the same token (docs/architecture/topologies.md#recreated-root)` });
    }
  }
  return blockers;
}

function blockedError(blockers: DeactivationBlocker[]): OperationError {
  const locked = blockers.find(b => b.kind === 'writer_admin_lock');
  if (locked) return new OperationError('writer_admin_locked', 'Writer administration is locked; deactivation was not applied.',
    `Run gbrain sources writer unlock on the brain host, deactivate, then gbrain sources writer lock again.`, WRITER_ADMIN_LOCKED_DOCS);
  return new OperationError('writer_not_quiesced', `Deactivation requires a quiesced brain; ${blockers.length} item(s) block it.`,
    blockers.slice(0, 10).map(b => `${b.kind} ${b.id} (${b.detail}): ${b.exit}`).join(' | '), DEACTIVATE_DOCS);
}

async function retiredTopology(engine: BrainEngine): Promise<{ worktrees: Array<{ id: string; roots: string[] }>; bindings: number }> {
  const rows = await engine.executeRaw<{ id: string; root: string | null }>(`SELECT w.id::text AS id, h.local_path AS root FROM persistence_worktrees w
      LEFT JOIN persistence_host_bindings h ON h.worktree_id=w.id WHERE w.state<>'retired' ORDER BY w.id, h.local_path`);
  const worktrees = new Map<string, string[]>();
  for (const row of rows) {
    const roots = worktrees.get(row.id) ?? [];
    if (row.root) roots.push(row.root);
    worktrees.set(row.id, roots);
  }
  const [{ n }] = await engine.executeRaw<{ n: number }>('SELECT COUNT(*)::int AS n FROM persistence_source_bindings');
  return { worktrees: [...worktrees].map(([id, roots]) => ({ id, roots })), bindings: Number(n) };
}

async function keptSettings(engine: BrainEngine, brain: BrainRow): Promise<DeactivationReport['kept']> {
  const [{ n }] = await engine.executeRaw<{ n: number }>("SELECT COUNT(*)::int AS n FROM persistence_writer_protocols").catch(() => [{ n: 0 }]);
  return { skill_bundles_enabled: brain.skill_bundles_enabled === true, writer_protocol_floor: brain.writer_protocol_floor ?? 1, writer_protocol_registrations: Number(n) };
}

export async function deactivatePersistence(engine: BrainEngine, opts: { dryRun?: boolean; expectedState?: string; requestId?: string;
  hooks?: { afterLocks?: () => Promise<void> } } = {}): Promise<DeactivationReport> {
  const brain = await readBrain(engine);
  const topology = await retiredTopology(engine);
  const kept = await keptSettings(engine, brain);
  const base = { dry_run: opts.dryRun === true, retired_worktrees: topology.worktrees, source_bindings: topology.bindings, kept };
  if (!brain.enabled) {
    // #6122: a disabled brain has no managed mode to convert, but sources claimed before activation fence classic sync;
    // deactivate releases them. Without claims a rerun only clears this host's retired markers.
    const claims = await preActivationClaims(engine);
    const classic = { ...base, mode: 'classic' as const, deactivated: false, mode_epoch: Number(brain.mode_epoch) };
    if (!claims.length) return { ...classic, retired_worktrees: [], blockers: [], ...(opts.dryRun ? {} : { local_markers: await cleanupRetiredManagedMarkers(engine) }) };
    const blockers = [...await deactivationBlockers(engine), ...await physicalRootBlockers(engine, 'classic')];
    if (opts.dryRun) return { ...classic, retired_worktrees: [], blockers, pre_activation_claims: claims };
    if (blockers.length) throw blockedError(blockers);
    const released = await releasePreActivationClaims(engine, { expectedState: opts.expectedState, requestId: opts.requestId,
      blocked: async tx => { const inside = await deactivationBlockers(tx); return inside.length ? blockedError(inside) : null; } });
    const worktrees = [...new Set(released.map(claim => claim.worktree_id))];
    return { ...classic, retired_worktrees: worktrees.map(id => ({ id, roots: [...new Set(released.filter(c => c.worktree_id === id).flatMap(c => c.roots))] })),
      blockers: [], pre_activation_claims: released, local_markers: await cleanupRetiredManagedMarkers(engine) };
  }
  const blockers = [...await deactivationBlockers(engine), ...await physicalRootBlockers(engine, 'managed')];
  if (opts.dryRun) {
    const carried_holds = (await planHoldCarry(engine, existingHostIdFor(engine))).filter(c => c.items > 0 && !holdCarryBlocked(c));
    return { ...base, mode: 'managed', deactivated: false, mode_epoch: Number(brain.mode_epoch), blockers, carried_holds, failed_effects: await failedEffectHistory(engine) };
  }
  if (blockers.length) throw blockedError(blockers);
  const principal = await topologyPrincipal(engine);
  const requestId = opts.requestId ?? randomUUID();
  const hostId = existingHostIdFor(engine);
  const locks: NativeLockHandle[] = [];
  let report: DeactivationReport;
  try {
    // Native worktree locks precede the transaction, as in activation.
    const sources = await engine.executeRaw<{ id: string }>('SELECT source_id AS id FROM persistence_source_bindings ORDER BY source_id');
    const local = new Map<string, Awaited<ReturnType<typeof getWorktreeBinding>>>();
    for (const { id } of sources) {
      const binding = await getWorktreeBinding(engine, id, hostId);
      if (binding && binding.owner_host_id === hostId && binding.local_path) local.set(binding.worktree_id, binding);
    }
    for (const binding of [...local.values()].sort((a, b) => a!.worktree_id.localeCompare(b!.worktree_id))) {
      const lock = await acquireWorktree(binding!, 0, undefined, undefined, { yieldLanes: true });
      if (!lock) throw new OperationError('writer_lock_unavailable', `A local process holds the canonical worktree lock of source '${binding!.source_id}'.`,
        'Stop the resident owner on this host (gbrain serve or autopilot), then rerun deactivate.');
      locks.push(lock);
    }
    report = await engine.transaction(async tx => {
      await tx.executeRaw("SELECT set_config('lock_timeout','5000ms',true),set_config('synchronous_commit','on',true)");
      const current = await readBrain(tx, true);
      await assertWriterAdminState(tx, opts.expectedState);
      await assertWriterAdminUnlocked(tx);
      if (!current.enabled) {
        throw opError('writer_admin_state_changed', 'The brain was deactivated concurrently.',
          'Another process already deactivated managed persistence, so this run changed nothing more. Confirm the state in writer status; no further deactivation is needed.',
          { fix: readFix('Shows whether managed persistence is enabled, read-only.', { argv: ['gbrain', 'sources', 'writer', 'status', '--json'] }) });
      }
      await tx.executeRaw('SELECT id FROM persistence_worktrees ORDER BY id FOR UPDATE');
      await tx.executeRaw('SELECT id FROM sources ORDER BY id FOR UPDATE');
      await opts.hooks?.afterLocks?.();
      const inside = await deactivationBlockers(tx);
      if (inside.length) throw blockedError(inside);
      // Written before commit: if the transaction then fails, the brain stays managed and ignores these files.
      const carried_holds = await carryHoldsToClassicState(tx, hostId);
      const failed_effects = await failedEffectHistory(tx);
      const retired = await retiredTopology(tx);
      const [epoch] = await tx.executeRaw<{ mode_epoch: string }>(
        'UPDATE persistence_brain SET enabled=false, mode_epoch=mode_epoch+1 WHERE singleton=1 RETURNING mode_epoch::text');
      await tx.executeRaw("UPDATE persistence_worktrees SET state='retired' WHERE state<>'retired'");
      await tx.executeRaw('DELETE FROM persistence_source_bindings');
      await tx.executeRaw('DELETE FROM persistence_host_bindings');
      await tx.unsetConfig(DATABASE_ONLY_SOURCES_KEY);
      const sourceRoots = (await tx.executeRaw<{ local_path: string }>('SELECT local_path FROM sources WHERE local_path IS NOT NULL')).map(r => r.local_path);
      const outcome = { brain_id: current.brain_id, retired_mode_epoch: Number(current.mode_epoch), mode_epoch: Number(epoch.mode_epoch),
        worktrees: retired.worktrees, source_roots: sourceRoots };
      await lockTopologyPrincipal(tx, principal);
      await recordTopologyChange(tx, { principal, requestId, intent: { operation: 'writer_deactivate' }, operation: 'writer_deactivate', sourceId: '*',
        incarnation: null, worktrees: retired.worktrees.map(w => w.id) }, outcome);
      await refreshManagedFilesystemRoots(tx, managedFilesystemDatastorePath(engine));
      return { ...base, mode: 'classic' as const, deactivated: true, mode_epoch: Number(epoch.mode_epoch), retired_mode_epoch: Number(current.mode_epoch),
        retired_worktrees: retired.worktrees, source_bindings: retired.bindings, blockers: [], carried_holds, failed_effects };
    });
  } finally { for (const lock of locks.reverse()) await lock.release(); }
  return { ...report, local_markers: await cleanupRetiredManagedMarkers(engine) };
}

interface RetiredRecord { epochs: Set<number>; worktrees: Set<string>; roots: Set<string> }

/** GBRA-133: `brain` is awaited only after the read is sent, so the caller's persistence_brain read shares its round trip. */
async function readRetired(engine: BrainEngine, brain: Promise<{ brain_id: string }>): Promise<RetiredRecord> {
  const rowsRead = engine.executeRaw<{ outcome: { brain_id?: string; retired_mode_epoch?: number; worktrees?: Array<{ id: string; roots: string[] }>; source_roots?: string[] } }>(
    "SELECT outcome FROM persistence_topology_changes WHERE operation='writer_deactivate' AND state='committed'");
  const [rows, { brain_id: brainId }] = await Promise.all([rowsRead, brain]);
  const retired: RetiredRecord = { epochs: new Set(), worktrees: new Set(), roots: new Set() };
  const canonical = (path: string) => { try { return canonicalFilesystemPath(path); } catch { return path; } };
  for (const { outcome } of rows) {
    if (outcome?.brain_id !== brainId) continue;
    if (typeof outcome.retired_mode_epoch === 'number') retired.epochs.add(outcome.retired_mode_epoch);
    for (const w of outcome.worktrees ?? []) { retired.worktrees.add(w.id); for (const root of w.roots) retired.roots.add(canonical(root)); }
    for (const root of outcome.source_roots ?? []) retired.roots.add(canonical(root));
  }
  return retired;
}

function readJson(path: string): Record<string, unknown> | null {
  try { lstatSync(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; }
  const value = JSON.parse(readFileSync(path, 'utf8'));
  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
}

/**
 * Remove this host's managed markers and registry records of retired epochs of
 * the connected brain. Runs on connect before any filesystem guard check, after
 * deactivate on the deactivating host, and on a rerun of deactivate. Each file
 * is re-read before unlinking; other brains' files and a newer prepared claim
 * are never touched; a filesystem error keeps the file and reports it pending.
 */
export async function cleanupRetiredManagedMarkers(engine: BrainEngine): Promise<LocalMarkerReport> {
  const report: LocalMarkerReport = { state: 'cleared', removed: [], pending: [] };
  const [present] = await engine.executeRaw<{ present: boolean }>("SELECT to_regclass('persistence_topology_changes') IS NOT NULL AS present");
  if (!present?.present) return report;
  const brainRead = readPersistenceBrain(engine);
  const [brain, retired] = await Promise.all([brainRead, readRetired(engine, brainRead)]);
  const current = Number(brain.mode_epoch ?? 1);
  if (!retired.epochs.size && !retired.worktrees.size) return report;
  const activeRoots = new Set(brain.enabled ? (await engine.executeRaw<{ local_path: string }>('SELECT local_path FROM persistence_host_bindings'))
    .map(row => { try { return canonicalFilesystemPath(row.local_path); } catch { return row.local_path; } }) : []);
  const known = retired.epochs.size > 0;
  /** removable, keep (normal), or a pending reason. */
  const judge = (value: Record<string, unknown>, root: string | null): 'remove' | 'keep' | string => {
    const epoch = value.mode_epoch === undefined ? null : Number(value.mode_epoch);
    if (epoch !== null) {
      if (retired.epochs.has(epoch) && epoch < current) return 'remove';
      if (brain.enabled && epoch === current) return 'keep';
      return epoch > current ? 'newer_mode_epoch' : 'unknown_mode_epoch';
    }
    // Worktree ids never repeat: a retired one is removed, any other (a newer prepared claim) is kept.
    const worktree = typeof value.worktree_id === 'string' ? value.worktree_id : typeof value.worktreeId === 'string' ? value.worktreeId : null;
    if (worktree) return retired.worktrees.has(worktree) ? 'remove' : 'keep';
    if (root !== null && retired.roots.has(root) && !activeRoots.has(root)) return 'remove';
    return brain.enabled || !known ? 'keep' : 'unrecorded_pre_epoch_marker';
  };
  const remove = (path: string, value: Record<string, unknown>) => {
    const again = readJson(path);
    if (!again || JSON.stringify(again) !== JSON.stringify(value)) { report.pending.push({ path, reason: 'changed_while_cleaning' }); return; }
    unlinkSync(path);
    report.removed.push(path);
  };
  const visit = (path: string, root: string | null, owns: (value: Record<string, unknown>) => boolean) => {
    try {
      const value = readJson(path);
      if (!value || !owns(value)) return;
      const verdict = judge(value, root);
      if (verdict === 'remove') remove(path, value);
      else if (verdict !== 'keep') report.pending.push({ path, reason: verdict });
    } catch (error) {
      report.pending.push({ path, reason: `unreadable: ${error instanceof Error ? error.message : String(error)}` });
    }
  };
  const ours = (value: Record<string, unknown>) => value.brain_id === brain.brain_id || value.brainId === brain.brain_id;
  const roots = new Set(retired.roots);
  const registry = join(configDir(), 'persistence', 'managed-roots');
  let files: string[] = [];
  try { files = readdirSync(registry).filter(file => file.startsWith(`${brain.brain_id}.`) && file.endsWith('.json')); }
  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') report.pending.push({ path: registry, reason: `unreadable: ${(error as Error).message}` }); }
  for (const file of files) {
    const path = join(registry, file);
    try {
      const value = readJson(path);
      if (value && typeof value.root === 'string') roots.add(value.root);
      visit(path, typeof value?.root === 'string' ? value.root : null, ours);
    } catch (error) { report.pending.push({ path, reason: `unreadable: ${(error as Error).message}` }); }
  }
  for (const root of roots) {
    // A prepared-claim reservation lives beside the checkout and fences it even when the checkout is gone.
    visit(physicalRootReservationPath(root), root, ours);
    if (!existsSync(root)) continue;
    const gitMarker = gitManagedMarker(root);
    for (const marker of [join(root, '.gbrain-managed'), ...(gitMarker ? [gitMarker] : [])]) visit(marker, root, ours);
    visit(join(root, PHYSICAL_ROOT_MARKER), root, ours);
  }
  await refreshManagedFilesystemRoots(engine);
  if (report.pending.length) {
    report.state = 'pending';
    report.rerun = 'gbrain sources writer status (rerun on this host after fixing the named paths)';
  }
  return report;
}

function gitManagedMarker(root: string): string | null {
  for (let current = root; ; current = dirname(current)) {
    const git = join(current, '.git');
    if (existsSync(git)) {
      try {
        if (lstatSync(git).isDirectory()) return join(git, 'gbrain-managed.json');
        const match = /^gitdir:\s*(.+)\s*$/m.exec(readFileSync(git, 'utf8'));
        return match ? join(resolve(current, match[1]), 'gbrain-managed.json') : null;
      } catch { return null; }
    }
    if (dirname(current) === current) return null;
  }
}