Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.9 KB
Raw Blame
import { createHash, randomUUID } from 'node:crypto';
import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
import { configDir } from '../config.ts';
import { flushDirectory } from '../fs-durable.ts';
import { gitChildEnv } from '../git-env.ts';
import { execFileSync } from '../spawn.ts';
import { opError, OperationError } from '../ops/contract.ts';

export interface ManagedRootRecord {
  local_path: string;
  source_id?: string;
  source_incarnation?: string;
  worktree_id?: string;
  topology_generation?: string | number;
  /** #7338: the brain's own database path, marked in its own directory: it is not a checkout, so no enclosing repository is marked. */
  datastore?: true;
}
function registryDirectory(): string { return join(configDir(), 'persistence', 'managed-roots'); }
function gitMetadataDirectory(root: string): string | null {
  const git = join(root, '.git');
  if (!existsSync(git)) return null;
  if (statSync(git).isDirectory()) return git;
  const match = /^gitdir:\s*(.+)\s*$/m.exec(readFileSync(git, 'utf8'));
  return match ? resolve(root, match[1]) : null;
}
/** The git metadata directory of the checkout enclosing `root` (walks up to a `.git` directory or `gitdir:` file). */
export function enclosingGitMetadata(root: string): string | null {
  let current = root;
  for (;;) {
    const metadata = gitMetadataDirectory(current);
    if (metadata) return metadata;
    const parent = dirname(current);
    if (parent === current) return null;
    current = parent;
  }
}
/**
 * #7988: the git metadata directory of the checkout `root` belongs to: its own `.git`, or an enclosing checkout whose HEAD
 * tracks `root` (a committed subdirectory). A directory a checkout only encloses (a connector clone or a plain directory
 * under a dotfiles home) belongs to none, and so does a `.git`, its own or an enclosing one, that is not a repository
 * (#9430). A Git read that fails for another reason keeps the enclosing checkout, unless the root has its own invalid
 * `.git`: an empty file or a gitdir file pointing nowhere fails every Git read there, so nothing proves the enclosing
 * checkout tracks it.
 */
export function checkoutGitMetadata(root: string): string | null {
  const own = gitMetadataDirectory(root);
  if (own && isGitDirectory(own)) return own;
  const enclosing = enclosingGitMetadata(dirname(root));
  if (!enclosing) return null;
  try { execFileSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', 'HEAD:./'], { stdio: 'ignore', timeout: 10_000, env: gitChildEnv() }); }
  catch (error) { if ((error as { status?: unknown }).status === 1 || existsSync(join(root, '.git')) || !isGitDirectory(enclosing)) return null; }
  return enclosing;
}
/** #9430: Git's own test for a repository directory: HEAD, plus objects/ and refs/ in its common directory (`commondir` in a linked worktree). */
function isGitDirectory(metadata: string): boolean {
  if (!existsSync(join(metadata, 'HEAD'))) return false;
  let common = metadata;
  try { common = resolve(metadata, readFileSync(join(metadata, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
  return existsSync(join(common, 'objects')) && existsSync(join(common, 'refs'));
}
/** An idle refresh must not touch inode metadata, so chmod only when the mode differs (#5297). */
function ensureMode(path: string, mode: number): void {
  if ((statSync(path).mode & 0o777) !== mode) chmodSync(path, mode);
}
/** Returns whether the record changed; a changed record is already durable with its directory entry. */
function writePrivateRecord(file: string, value: string): boolean {
  if (existsSync(file) && readFileSync(file, 'utf8') === value) { ensureMode(file, 0o600); return false; }
  const temporary = `${file}.${randomUUID()}.tmp`;
  const fd = openSync(temporary, 'wx', 0o600);
  try { writeFileSync(fd, value); fsyncSync(fd); } finally { closeSync(fd); }
  try { renameSync(temporary, file); flushDirectory(dirname(file)); }
  finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } }
  return true;
}
function markerExists(path: string): boolean {
  try { lstatSync(path); return true; }
  catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
    throw opError('writer_coordinator_required', 'Managed-root marker cannot be inspected.',
      `gbrain could not read ${path} (${(error as NodeJS.ErrnoException).code ?? 'unknown error'}), so it cannot tell whether this checkout is managed and refuses the write. Fix the path's permissions for this user, then run the command again.`);
  }
}
/** Shared refusal marker helps installations with separate homes. It NEVER grants ownership. */
export function hasManagedRootMarker(path: string): boolean {
  return managedRootMarkerFor(path) !== null;
}
/** The nearest ownership marker covering `path`: the root it marks and the marker file that proves it. */
export function managedRootMarkerFor(path: string): { root: string; marker: string } | null {
  let current = canonicalFilesystemPath(path);
  for (;;) {
    // A prepared claim is already a durable refusal, including when its target
    // directory does not yet exist. Ownership still requires SQL/native proof.
    const reservation = join(dirname(current), `.gbrain-owner-${createHash('sha256').update(current).digest('hex')}.json`);
    if (markerExists(reservation)) return { root: current, marker: reservation };
    if (existsSync(current) && statSync(current).isDirectory()) {
      for (const marker of [join(current, '.gbrain-owner.json'), join(current, '.gbrain-managed')]) {
        if (markerExists(marker)) return { root: current, marker };
      }
      const metadata = gitMetadataDirectory(current);
      if (metadata && markerExists(join(metadata, 'gbrain-managed.json'))) return { root: current, marker: join(metadata, 'gbrain-managed.json') };
    }
    const parent = dirname(current);
    if (parent === current) return null;
    current = parent;
  }
}
/** Resolve existing ancestors too, so an alias to a managed tree cannot bypass the fence. */
export function canonicalFilesystemPath(path: string): string {
  return resolveFilesystemPath(path, realpathSync);
}
export function nativeFilesystemPath(path: string): string {
  return resolveFilesystemPath(path, realpathSync.native);
}
function resolveFilesystemPath(path: string, realpath: (path: string) => string): string {
  let current = resolve(path);
  const missing: string[] = [];
  for (;;) {
    try { return resolve(realpath(current), ...missing.reverse()); }
    catch (error) {
      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
      const parent = dirname(current);
      if (parent === current) throw error;
      missing.push(basename(current)); current = parent;
    }
  }
}
const rootRank = (record: ManagedRootRecord) => [record.worktree_id ? 0 : 1, record.worktree_id, record.source_id, record.source_incarnation, record.topology_generation]
  .map(value => value == null ? '\u{10FFFF}' : String(value));
/**
 * #7203: one record per filesystem identity. Aliases of one directory (a
 * symlink, macOS /var vs /private/var, a case variant) collapse to its
 * canonical path, and a bound worktree row outranks an unbound source path
 * regardless of spelling or input order.
 */
export function canonicalManagedRoots(records: ManagedRootRecord[]): ManagedRootRecord[] {
  const byRoot = new Map<string, ManagedRootRecord>();
  for (const record of records) {
    const root = canonicalFilesystemPath(record.local_path);
    const held = byRoot.get(root);
    if (held) {
      const [next, current] = [rootRank(record), rootRank(held)];
      const at = next.findIndex((value, i) => value !== current[i]);
      if (at < 0 || next[at]! > current[at]!) continue;
    }
    byRoot.set(root, { ...record, local_path: root });
  }
  return [...byRoot.values()];
}
/**
 * One private immutable path identity per brain/root; topology metadata can be
 * refreshed but stale roots stay fenced until an explicit verified drain clears
 * them. Per-root files prevent independent registration from dropping siblings.
 * Returns the canonical records it holds, one per root.
 */
export function recordManagedRoots(brainId: string, records: ManagedRootRecord[], modeEpoch?: number): ManagedRootRecord[] {
  if (!/^[a-f0-9-]{36}$/i.test(brainId)) {
    throw opError('storage_error', 'Invalid managed-root brain identity.',
      'The managed-root registry was given a brain identity that is not a UUID, so nothing was recorded. This is an internal fault: run gbrain doctor --json and report it to the user.');
  }
  const canonical = canonicalManagedRoots(records);
  if (!canonical.length) return canonical;
  const directory = registryDirectory(); mkdirSync(directory, { recursive: true, mode: 0o700 }); ensureMode(directory, 0o700);
  let changed = false;
  for (const record of canonical) {
    const root = record.local_path;
    const key = createHash('sha256').update(root).digest('hex');
    const file = join(directory, `${brainId}.${key}.json`);
    const value = JSON.stringify({ version: 1, brain_id: brainId, root, ...record, local_path: root,
      ...(record.topology_generation != null ? { topology_generation: String(record.topology_generation) } : {}),
      ...(modeEpoch !== undefined ? { mode_epoch: modeEpoch } : {}) });
    changed = writePrivateRecord(file, value) || changed;
    if (existsSync(root) && statSync(root).isDirectory()) {
      // #7338/#7988: a datastore, or a root no checkout tracks, is marked in its own directory, never in the metadata of a
      // repository that only encloses it.
      const metadata = record.datastore ? null : checkoutGitMetadata(root);
      const marker = metadata ? join(metadata, 'gbrain-managed.json') : join(root, '.gbrain-managed');
      if (!existsSync(marker)) writePrivateRecord(marker, JSON.stringify({ version: 1, managed: true, brain_id: brainId, ...(modeEpoch !== undefined ? { mode_epoch: modeEpoch } : {}) }));
    }
  }
  if (changed) flushDirectory(directory);
  return canonical;
}
/** Available before connect, including while another process owns local PGLite. */
export function registeredManagedRoots(): string[] {
  return registeredManagedRootRecords().map(record => record.root);
}
/** The registry records with the source each root was recorded for (when the binding named one). */
export function registeredManagedRootRecords(): Array<{ root: string; source_id?: string }> {
  const directory = registryDirectory();
  let files: string[];
  try { files = readdirSync(directory); }
  catch (error) {
    const code = (error as NodeJS.ErrnoException).code;
    if (code === 'ENOENT') return [];
    // GST-1623: an unlistable registry is a typed refusal, never a raw error.
    throw opError('writer_coordinator_required', 'Managed-root ownership records cannot be listed.',
      `gbrain could not read ${directory} (${code ?? 'unknown error'}), so it cannot tell which checkouts this brain manages and refuses the command. Fix the path's permissions for this user (or move aside a file standing where that directory belongs), then run the command again.`);
  }
  const records: Array<{ root: string; source_id?: string }> = [];
  for (const file of files.filter(file => file.endsWith('.json'))) {
    try {
      const value = JSON.parse(readFileSync(join(directory, file), 'utf8'));
      if (value.version !== 1 || typeof value.root !== 'string' || !isAbsolute(value.root)) throw new Error('invalid record');
      records.push({ root: canonicalFilesystemPath(value.root), ...(typeof value.source_id === 'string' ? { source_id: value.source_id } : {}) });
    } catch {
      throw new OperationError('writer_coordinator_required', 'Managed-root ownership records are unreadable.',
        'Repair the local persistence registry through writer administration before running filesystem maintenance.');
    }
  }
  return records;
}