Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.8 KB
Raw Blame
/** Filesystem boundary for the four generic remote jobs; not an OS sandbox.
 * Trust model excludes hostile concurrent same-UID or cross-brain writers.
 * Cooperating writers in this brain share the canonical worktree lock.
 */
import { AsyncLocalStorage } from 'node:async_hooks';
import { setTimeout as delay } from 'node:timers/promises';
import { closeSync, constants, fstatSync, ftruncateSync, lstatSync, openSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { LockStolenError, LockUnavailableError, withRefreshingLock } from '../db-lock.ts';
import { discoverGitRoot, discoverGitRootAsync } from '../sync-git.ts';
import { authorityDigest, currentRemoteJobAuthority, currentJobSignal } from './submission-authority.ts';
import { assertLegacyFilesystemWriter, assertManagedFilesystemWrite } from '../persistence/filesystem-guard.ts';

/** `resolved` keeps the lock root each path resolved to when the lock was taken, so a nested check spawns no git. */
const heldRoots = new AsyncLocalStorage<ReadonlyArray<{ root: string; active: boolean; resolved?: ReadonlyMap<string, string> }>>();
const filesystemSignal = new AsyncLocalStorage<AbortSignal>();
const filesystemLeases = new AsyncLocalStorage<Array<{ key: string; lost: boolean }>>();
export function currentSourceFilesystemSignal(): AbortSignal | undefined {
  const local = filesystemSignal.getStore(), job = currentJobSignal();
  return local && job && local !== job ? AbortSignal.any([local, job]) : local ?? job;
}
export function assertSourceFilesystemActive(allowCallerAbort = false): void {
  if (heldRoots.getStore()?.some(held => !held.active)) throw new LockStolenError('released-worktree-context');
  // Lease ownership is independent of caller cancellation: a timeout racing a
  // later lease loss must never hide the loss behind a resumable partial result.
  for (const lease of filesystemLeases.getStore() ?? []) if (lease.lost) throw new LockStolenError(lease.key);
  if (allowCallerAbort) return;
  const signal = currentSourceFilesystemSignal();
  // Some Bun versions drop an asynchronously created AbortSignal reason.
  if (signal?.aborted) throw signal.reason ?? new DOMException('Source filesystem work cancelled or lock lease lost', 'AbortError');
}
function lockCandidate(path: string): string {
  let canonical = resolve(path);
  try { canonical = realpathSync(canonical); } catch { /* local initialization may create it */ }
  try { if (statSync(canonical).isFile()) canonical = dirname(canonical); } catch { /* nonexistent local target */ }
  return canonical;
}
function lockRoot(path: string): string {
  const canonical = lockCandidate(path);
  try { return realpathSync(discoverGitRoot(canonical)); } catch { return canonical; }
}
/** GBRA-133 2b.3: `lockRoot` without blocking the event loop (every sync takes this lock, in residents too). */
async function lockRootAsync(path: string): Promise<string> {
  const canonical = lockCandidate(path);
  try { return realpathSync(await discoverGitRootAsync(canonical)); } catch { return canonical; }
}
function holdsLockOn(canonical: string): boolean {
  return [...heldRoots.getStore() ?? []].some(held => held.active && encloses(held.root, canonical));
}
function encloses(root: string, path: string): boolean {
  const rel = relative(root, path);
  return !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`);
}
export function hasSourceFilesystemLock(path: string): boolean {
  const held = heldRoots.getStore() ?? [];
  if (!held.some(entry => entry.active)) return false;
  const known = held.find(entry => entry.resolved?.has(path))?.resolved?.get(path);
  return holdsLockOn(known ?? lockRoot(path));
}
async function registeredLockRoot(engine: BrainEngine, pathRoot: string): Promise<string> {
  let root = pathRoot;
  const sources = await engine.executeRaw<{ local_path: string }>(`SELECT local_path FROM sources WHERE local_path IS NOT NULL AND local_path <> ''`);
  // A registered non-Git parent can contain a Git source. Canonicalize every
  // registered source through the same worktree rule, then choose the outermost
  // ancestor so overlapping sources agree regardless of which one starts first.
  for (const source of sources) {
    const candidate = await lockRootAsync(source.local_path);
    if (encloses(candidate, root)) root = candidate;
  }
  return root;
}
export async function withSourceFilesystemLock<T>(engine: BrainEngine, path: string, fn: () => Promise<T>, opts: { signal?: AbortSignal; waitMs?: number } = {}): Promise<T> {
  await assertLegacyFilesystemWriter(engine, path);
  assertSourceFilesystemActive();
  const pathRoot = await lockRootAsync(path);
  if (holdsLockOn(pathRoot)) return fn();
  const root = await registeredLockRoot(engine, pathRoot);
  const rootContext = { root, active: true, resolved: new Map([[path, pathRoot]]) };
  const held = [...heldRoots.getStore() ?? [], rootContext];
  const key = `gbrain-fs:${authorityDigest(root)}`;
  const inheritedSignal = currentSourceFilesystemSignal();
  const signal = opts.signal && inheritedSignal ? AbortSignal.any([opts.signal, inheritedSignal]) : opts.signal ?? inheritedSignal;
  const deadline = Date.now() + (opts.waitMs ?? 5000);
  for (;;) {
    signal?.throwIfAborted();
    let entered = false;
    try {
      const lost = new AbortController();
      const lease = { key, lost: false };
      const activeSignal = signal ? AbortSignal.any([signal, lost.signal]) : lost.signal;
      return await withRefreshingLock(engine, key, () => {
        entered = true;
        return heldRoots.run(held, () => filesystemLeases.run([...(filesystemLeases.getStore() ?? []), lease], () => filesystemSignal.run(activeSignal, async () => {
          assertSourceFilesystemActive();
          try {
            const result = await fn();
            assertSourceFilesystemActive();
            return result;
          } finally { rootContext.active = false; }
        })));
      }, { onLockLost: reason => { lease.lost = true; lost.abort(reason); } });
    } catch (err) {
      // Retry acquisition only: never rerun a partially executed callback.
      if (entered || !(err instanceof LockUnavailableError) || err.lockId !== key || Date.now() >= deadline) throw err;
      await delay(Math.min(50, Math.max(1, deadline - Date.now())), undefined, { signal });
    }
  }
}

export function assertSourceFilePath(path: string): string {
  assertSourceFilesystemActive();
  const authority = currentRemoteJobAuthority();
  if (!authority) return path;
  const root = authority.grant.canonicalRoot;
  if (realpathSync(root) !== root) throw new Error('Source root changed during job');
  const absolute = resolve(path);
  const rel = relative(root, absolute);
  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) throw new Error('Source file escapes registered root');
  let component = root;
  for (const part of rel.split(sep)) {
    component = resolve(component, part);
    if (lstatSync(component).isSymbolicLink()) throw new Error('Remote source jobs do not follow symlinks');
  }
  const real = realpathSync(absolute);
  const realRel = relative(root, real);
  if (isAbsolute(realRel) || realRel === '..' || realRel.startsWith(`..${sep}`)) throw new Error('Source file escapes registered root');
  return real;
}

function openSourceFile(path: string, write: boolean): number {
  const real = assertSourceFilePath(path);
  if (constants.O_NOFOLLOW === undefined) throw new Error('Remote filesystem jobs require O_NOFOLLOW support');
  const fd = openSync(real, (write ? constants.O_WRONLY : constants.O_RDONLY) | constants.O_NOFOLLOW);
  try {
    if (!fstatSync(fd).isFile()) throw new Error('Source path must identify a regular file');
    // Parent-directory checks and final-descriptor checks are complementary;
    // the descriptor is retained through I/O rather than reopening the path.
    assertSourceFilePath(real);
    return fd;
  } catch (err) { closeSync(fd); throw err; }
}
export function readSourceFileSync(path: string): Buffer;
export function readSourceFileSync(path: string, encoding: BufferEncoding): string;
export function readSourceFileSync(path: string, encoding?: BufferEncoding): Buffer | string {
  assertSourceFilesystemActive();
  if (!currentRemoteJobAuthority()) return encoding ? readFileSync(path, encoding) : readFileSync(path);
  const fd = openSourceFile(path, false);
  try { return encoding ? readFileSync(fd, encoding) : readFileSync(fd); }
  finally { closeSync(fd); }
}
export function writeSourceFileSync(path: string, content: string): void {
  assertManagedFilesystemWrite(path);
  assertSourceFilesystemActive();
  if (!currentRemoteJobAuthority()) { writeFileSync(path, content); return; }
  const fd = openSourceFile(path, true);
  try { assertSourceFilesystemActive(); ftruncateSync(fd, 0); writeFileSync(fd, content); }
  finally { closeSync(fd); }
}