Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.3 KB
Raw Blame
/**
 * Bootstrap-run mutex [G9, CX2-16] + the bootstrap family's typed-error
 * machinery.
 *
 * Two concurrent `gbrain bootstrap` runs against the same workspace would
 * interleave renders, gh calls, and receipt writes. The mutex is an atomic
 * `mkdir` at `<workspace>/.gbrain-bootstrap.lock` with a `meta.json`
 * ({pid, acquired_at, token}) written tmp+rename so a concurrent reader never
 * sees a torn file.
 *
 * Steal policy (the pid-reuse learning from pglite-lock #2058/#2348 applied):
 * a holder is stolen ONLY when its PID is affirmatively dead (kill-0 → ESRCH)
 * AND the lock is older than STALE_AGE_MS. Both conditions are required —
 * a dead-looking young lock may be a concurrent acquirer that hasn't written
 * meta yet, and PID liveness alone is unreliable under PID reuse. A live PID
 * is NEVER stolen regardless of age. Everything else gets the typed
 * BOOTSTRAP_IN_PROGRESS refusal the runbook relays to the human.
 *
 * Release is ownership-checked: the on-disk token must match ours before the
 * lock dir is removed, so a stolen-and-replaced handle can never delete the
 * new owner's live lock (same defense as pglite-lock's releaseLock).
 *
 * This module is the dependency root of the bootstrap family — `BootstrapError`
 * lives here so repo.ts / attach.ts / uninstall.ts can share it without cycles.
 */

import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { isProcessAlive } from '../pglite-lock.ts';

// ---------------------------------------------------------------------------
// Typed errors (shared by the whole bootstrap family)
// ---------------------------------------------------------------------------

export type BootstrapErrorCode =
  /** `gh` binary not on PATH — human must install it (exit-code-2 semantics). */
  | 'GH_MISSING'
  /** `gh auth status` failed — human must run `gh auth login` (exit 2). */
  | 'GH_AUTH'
  /** Workspace already has an `origin` remote bootstrap can neither adopt nor
   * claim (foreign owner / receipt mismatch) — pointed at attach [G8]. */
  | 'ORIGIN_EXISTS'
  /** A create-repo-first origin the authed user owns has FOREIGN content —
   * bootstrap adopts only an empty repo (or one carrying our own history), so
   * it never silently no-ops onto an existing project [G8]. */
  | 'ORIGIN_NOT_EMPTY'
  /** Could not reach the origin to confirm it is safe to adopt (git ls-remote
   * failed) — refuse and re-run; never adopt on uncertainty [G8]. */
  | 'REMOTE_CHECK_FAILED'
  /** `gh repo create` (or a required git step) failed. */
  | 'REPO_CREATE_FAILED'
  /** The pre-push secret scan found an unallowlisted secret in the workspace —
   * nothing is committed or pushed until it is removed/allowlisted [G8/D6]. */
  | 'SECRET_SCAN_BLOCKED'
  /** Privacy verify returned an affirmative non-private answer — hard stop. */
  | 'REPO_NOT_PRIVATE'
  /** Privacy verify could not complete (rate limit / 5xx) — refuse and name
   * the reason, never fail-open; the fix is re-running, not panic [G8]. */
  | 'VERIFY_UNAVAILABLE'
  /** Cloud sandbox: a repo created mid-session is never attached to the
   * session's GitHub proxy scope (REST 403, push denied) — creation must
   * happen outside; the session is opened ON the repo, then attach [D-cloud]. */
  | 'CLOUD_SANDBOX_REPO'
  /** No agent.json — not an agent workspace. */
  | 'NOT_A_WORKSPACE'
  /** agent.json says `initialized: false` — an unrendered template clone [CX2-1]. */
  | 'TEMPLATE_UNINITIALIZED'
  /** agent.json unreadable / conflict markers / bad JSON. */
  | 'MANIFEST_INVALID'
  /** agent.json format_version is newer than this binary understands. */
  | 'NEWER_FORMAT'
  /** Another bootstrap run holds the workspace lock [G9]. */
  | 'BOOTSTRAP_IN_PROGRESS'
  /** No machine-local install receipt — nothing bootstrap-created here [CX2-12]. */
  | 'NO_RECEIPT'
  /** The receipt on this machine belongs to a different workspace. */
  | 'RECEIPT_MISMATCH'
  /** A live process (serve or other) holds the PGLite data-dir lock. */
  | 'LIVE_SERVE'
  /** --delete-brain requested but bootstrap did not create this brain [G2]. */
  | 'DELETE_BRAIN_REFUSED'
  /** GBRAIN_HOME guard tripped: not explicit / bad signature / symlink [S3#5]. */
  | 'HOME_GUARD'
  /** The resolved --workspace (or its cwd default) is the user's home
   * directory — refuse before any home-directory-scale git operation runs. */
  | 'HOME_WORKSPACE'
  /** The harness could not resolve (or verify) the source its hooks + token
   * must bind to — pass --source <id> explicitly. */
  | 'SOURCE_UNRESOLVED';

/**
 * The bootstrap family's error type. `exitCode` carries dispatcher semantics:
 * 2 = a human action is required (install gh, gh auth login); 1 = everything
 * else. Callers branch on `code`, never on message text.
 */
export class BootstrapError extends Error {
  readonly code: BootstrapErrorCode;
  readonly exitCode: number;
  readonly details: Record<string, unknown>;

  constructor(code: BootstrapErrorCode, message: string, opts?: { exitCode?: number; details?: Record<string, unknown> }) {
    super(message);
    this.name = 'BootstrapError';
    this.code = code;
    this.exitCode = opts?.exitCode ?? 1;
    this.details = opts?.details ?? {};
  }
}

// ---------------------------------------------------------------------------
// The bootstrap-run mutex
// ---------------------------------------------------------------------------

export const BOOTSTRAP_LOCK_DIRNAME = '.gbrain-bootstrap.lock';
const META_FILE = 'meta.json';

/** A dead-PID holder younger than this is NOT stolen (pid-reuse + mkdir-then-
 * write-meta race guard). Exported for tests. */
export const BOOTSTRAP_LOCK_STALE_AGE_MS = 120_000;

export interface BootstrapLockMeta {
  pid: number;
  acquired_at: number;
  token: string;
}

export interface BootstrapLockHandle {
  /** Absolute path of the lock directory. */
  dir: string;
  /** Ownership token — release verifies the on-disk meta still carries it. */
  token: string;
  /** True when this acquisition stole a stale (dead + old) holder's lock. */
  stole: boolean;
  release(): void;
}

export function bootstrapLockDir(workspaceDir: string): string {
  return join(workspaceDir, BOOTSTRAP_LOCK_DIRNAME);
}

function readMeta(lockDir: string): BootstrapLockMeta | null {
  try {
    const parsed = JSON.parse(readFileSync(join(lockDir, META_FILE), 'utf8')) as Partial<BootstrapLockMeta>;
    if (typeof parsed.pid !== 'number' || typeof parsed.acquired_at !== 'number' || typeof parsed.token !== 'string') {
      return null;
    }
    return parsed as BootstrapLockMeta;
  } catch {
    return null;
  }
}

/** Age of the holder: meta.acquired_at when readable, else the dir's mtime. */
function holderAgeMs(lockDir: string, meta: BootstrapLockMeta | null, now: number): number {
  if (meta) return now - meta.acquired_at;
  try {
    return now - statSync(lockDir).mtimeMs;
  } catch {
    return 0; // dir vanished mid-check — treat as brand new; the retry handles it
  }
}

function inProgressError(meta: BootstrapLockMeta | null): BootstrapError {
  const pid = meta?.pid;
  return new BootstrapError(
    'BOOTSTRAP_IN_PROGRESS',
    pid !== undefined
      ? `bootstrap already running (pid ${pid}) — wait for it to finish, or remove ${BOOTSTRAP_LOCK_DIRNAME} if you are sure it is dead`
      : `bootstrap already running — wait for it to finish, or remove ${BOOTSTRAP_LOCK_DIRNAME} if you are sure it is dead`,
    { details: { pid } },
  );
}

/**
 * Acquire the workspace bootstrap mutex. Throws BOOTSTRAP_IN_PROGRESS when a
 * live (or not-provably-stale) holder exists. Never waits: bootstrap runs are
 * human-triggered, so the right UX for a collision is an immediate, typed
 * refusal the agent can relay — not a silent queue.
 */
export async function acquireBootstrapLock(
  workspaceDir: string,
  opts?: { now?: () => number },
): Promise<BootstrapLockHandle> {
  const now = opts?.now ?? Date.now;
  const lockDir = bootstrapLockDir(workspaceDir);
  let stole = false;

  // At most two attempts: initial, and one retry after stealing a stale lock.
  for (let attempt = 0; attempt < 2; attempt++) {
    try {
      mkdirSync(lockDir, { recursive: false });
    } catch {
      // Held (or the workspace dir itself is missing — surface that plainly).
      try {
        statSync(workspaceDir);
      } catch {
        throw new BootstrapError('NOT_A_WORKSPACE', `workspace directory does not exist: ${workspaceDir}`);
      }
      const meta = readMeta(lockDir);
      const age = holderAgeMs(lockDir, meta, now());
      const dead = meta !== null && !isProcessAlive(meta.pid);
      // Steal ONLY dead + old. A live PID is never stolen; a young lock —
      // even with unreadable meta — may be a concurrent acquirer mid-write.
      const stealable = age > BOOTSTRAP_LOCK_STALE_AGE_MS && (dead || meta === null);
      if (!stealable) throw inProgressError(meta);
      stole = true;
      try {
        rmSync(lockDir, { recursive: true, force: true });
      } catch { /* raced with the holder's own release — retry below */ }
      continue;
    }

    // mkdir succeeded — write meta atomically (tmp + rename) so a concurrent
    // reader sees the file complete or absent, never torn.
    const meta: BootstrapLockMeta = {
      pid: process.pid,
      acquired_at: now(),
      token: `${process.pid}:${now()}:${crypto.randomUUID()}`,
    };
    const metaPath = join(lockDir, META_FILE);
    const tmp = `${metaPath}.tmp-${process.pid}`;
    writeFileSync(tmp, `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
    renameSync(tmp, metaPath);

    const handle: BootstrapLockHandle = {
      dir: lockDir,
      token: meta.token,
      stole,
      release: () => releaseBootstrapLock(handle),
    };
    return handle;
  }

  // Steal raced with a fresh acquirer — someone live owns it now.
  throw inProgressError(readMeta(lockDir));
}

/**
 * Release the mutex. Ownership-checked: if the on-disk token is readable and
 * is NOT ours, someone stole-and-replaced us — leave their lock alone.
 * Unreadable/absent meta falls through to a best-effort remove (mirrors
 * pglite-lock's releaseLock).
 */
export function releaseBootstrapLock(handle: Pick<BootstrapLockHandle, 'dir' | 'token'>): void {
  const meta = readMeta(handle.dir);
  if (meta && meta.token !== handle.token) return; // not ours anymore
  try {
    rmSync(handle.dir, { recursive: true, force: true });
  } catch { /* already gone */ }
}