Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.0 KB
Raw Blame
/**
 * #6122: a source claimed on a brain whose managed persistence was never
 * activated. The claim (a source binding plus its worktree and host binding)
 * fences classic sync (`sync-authority.ts` refuses `writer_coordinator_required`)
 * but nothing publishes through it, so `gbrain sources writer deactivate` on
 * such a brain releases it: once nothing is queued, running or recovering
 * (the same blockers as a managed deactivation), one transaction marks the
 * claimed worktrees `retired` (rows kept, as deactivation does), deletes the
 * source and host bindings and records a committed `writer_deactivate`
 * topology change (`outcome.pre_activation: true`) naming the worktrees and
 * roots, so the retired-marker cleanup removes this host's claim markers.
 * The brain stays classic and its `mode_epoch` does not move. The topology change
 * needs the administering CLI registration, which a never-activated brain may lack;
 * it is created (idempotently, as activation would) for the trusted local caller.
 */
import { randomUUID } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { acquireWorktree, getWorktreeBinding, readPersistenceBrain } from './ownership.ts';
import { currentVerifiedLocalWriter, registerLocalWriter, existingHostIdFor } from './identity.ts';
import type { NativeLockHandle } from './native-lock.ts';
import { assertWriterAdminState } from './admin-intent.ts';
import { assertWriterAdminUnlocked } 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 type { SqlEngine } from './model.ts';

export interface PreActivationClaim { source_id: string; worktree_id: string; roots: string[] }

/** Every source binding of the brain with its worktree's roots. Read-only. */
export async function preActivationClaims(engine: SqlEngine): Promise<PreActivationClaim[]> {
  const rows = await engine.executeRaw<{ source_id: string; worktree_id: string; root: string | null }>(`SELECT b.source_id, b.worktree_id::text AS worktree_id, h.local_path AS root
    FROM persistence_source_bindings b LEFT JOIN persistence_host_bindings h ON h.worktree_id=b.worktree_id ORDER BY b.source_id, h.local_path`);
  const claims = new Map<string, PreActivationClaim>();
  for (const row of rows) {
    const claim = claims.get(row.source_id) ?? { source_id: row.source_id, worktree_id: row.worktree_id, roots: [] };
    if (row.root && !claim.roots.includes(row.root)) claim.roots.push(row.root);
    claims.set(row.source_id, claim);
  }
  return [...claims.values()];
}

/**
 * Releases every pre-activation claim; the caller has checked that the brain is
 * disabled and that nothing blocks. `blockers` re-runs inside the transaction.
 */
export async function releasePreActivationClaims(engine: BrainEngine, opts: { expectedState?: string; requestId?: string;
  blocked: (tx: BrainEngine) => Promise<OperationError | null> }): Promise<PreActivationClaim[]> {
  // A never-activated brain may have no CLI writer registration yet (activation creates it); the trusted local
  // operator running deactivate gets the same one, so the topology change has its administering principal.
  if (!currentVerifiedLocalWriter()) await registerLocalWriter(engine, 'cli');
  const principal = await topologyPrincipal(engine);
  const requestId = opts.requestId ?? randomUUID();
  const hostId = existingHostIdFor(engine);
  const locks: NativeLockHandle[] = [];
  try {
    // Native worktree locks precede the transaction, as in activation and deactivation.
    const locked = new Set<string>();
    for (const claim of await preActivationClaims(engine)) {
      const binding = await getWorktreeBinding(engine, claim.source_id, hostId);
      if (!binding || binding.owner_host_id !== hostId || !binding.local_path || locked.has(binding.worktree_id)) continue;
      locked.add(binding.worktree_id);
      // #5914: the release publishes nothing, so it needs the native lock and the reservation's worktree id and token, not the inode of a recreated directory.
      const lock = await acquireWorktree(binding, 0, undefined, undefined, { yieldLanes: true, identity: 'reservation' });
      if (!lock) throw new OperationError('writer_lock_unavailable', `A local process holds the worktree lock of claimed source '${claim.source_id}'.`,
        'Stop the gbrain process on this host that holds it (gbrain serve or autopilot), then rerun deactivate.');
      locks.push(lock);
    }
    return await engine.transaction(async tx => {
      await tx.executeRaw("SELECT set_config('lock_timeout','5000ms',true),set_config('synchronous_commit','on',true)");
      const brain = await readPersistenceBrain(tx, { lock: 'update' });
      await assertWriterAdminState(tx, opts.expectedState);
      await assertWriterAdminUnlocked(tx);
      if (brain.enabled) throw opError('writer_admin_state_changed', 'Managed persistence was activated concurrently; no claim was released.',
        'Another process activated managed persistence while this release ran, so the claims now belong to the managed writer. Review the brain-wide deactivation preview before deciding anything else.',
        { fix: readFix('Previews the brain-wide deactivation and its blockers; changes nothing.', { argv: ['gbrain', 'sources', 'writer', 'deactivate', '--dry-run', '--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');
      const refused = await opts.blocked(tx);
      if (refused) throw refused;
      const claims = await preActivationClaims(tx);
      if (!claims.length) return [];
      const worktrees = [...new Set(claims.map(claim => claim.worktree_id))];
      await tx.executeRaw("UPDATE persistence_worktrees SET state='retired' WHERE id=ANY($1::uuid[]) AND state<>'retired'", [worktrees]);
      await tx.executeRaw('DELETE FROM persistence_source_bindings');
      await tx.executeRaw('DELETE FROM persistence_host_bindings WHERE worktree_id=ANY($1::uuid[])', [worktrees]);
      const retired = worktrees.map(id => ({ id, roots: [...new Set(claims.filter(claim => claim.worktree_id === id).flatMap(claim => claim.roots))] }));
      await lockTopologyPrincipal(tx, principal);
      await recordTopologyChange(tx, { principal, requestId, intent: { operation: 'writer_deactivate' }, operation: 'writer_deactivate', sourceId: '*',
        incarnation: null, worktrees }, { brain_id: brain.brain_id, pre_activation: true, mode_epoch: Number(brain.mode_epoch), worktrees: retired,
        source_roots: retired.flatMap(worktree => worktree.roots), sources: claims.map(claim => claim.source_id) });
      await refreshManagedFilesystemRoots(tx, managedFilesystemDatastorePath(engine));
      return claims;
    });
  } finally { for (const lock of locks.reverse()) await lock.release(); }
}