Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
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;
}