Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.7 KB
Raw Blame
/**
 * Filesystem coordination points for the autopilot daemon.
 *
 * A LEAF module (imports only node builtins + `config`) so other commands can read the
 * daemon's state files WITHOUT importing `src/commands/autopilot.ts`.
 *
 * Why that matters concretely: the CLI flag-registry generator follows a
 * command's dynamic `import('./x.ts')` one level deep and harvests every flag
 * literal it finds. A single `await import()` of the autopilot command module inside
 * `migrate-engine.ts` therefore folded autopilot's ENTIRE flag surface (install,
 * uninstall, interval, no-worker, status, repo, ...) into the migrate command's
 * accepted-flag allowlist, which would have made `gbrain migrate` silently
 * accept and ignore any of them. Pinned by `test/cli-flag-validation.test.ts`.
 *
 * Flag names appear here WITHOUT leading dashes on purpose — the generator
 * scans comments too, so writing them literally recreates the very bug this
 * comment describes.
 *
 * Everything here resolves through `gbrainPath` (NOT raw `process.env.HOME`)
 * because that is where the daemon itself writes; a `GBRAIN_HOME` install
 * otherwise has readers looking in a different directory than the writer.
 */
import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'fs';
import { homedir } from 'os';
import { dirname, join, resolve } from 'path';
import { randomBytes } from 'crypto';
import { configDir, gbrainPath } from './config.ts';

/**
 * The daemon's lock file. Its mtime IS the liveness heartbeat — the tick loop
 * refreshes it every pass — so "is autopilot alive?" is `now - mtime` against
 * the expected interval, with no scheduler probing required.
 */
export function autopilotLockPath(): string {
  return gbrainPath('autopilot.lock');
}

/**
 * #7003: the daemon's heartbeat sidecar beside the lock. It records the daemon's own next tick (its adaptive interval),
 * so autopilot status grades staleness from what the daemon scheduled rather than the caller's interval flag
 * (src/core/autopilot-heartbeat.ts). The lock mtime stays the liveness signal.
 */
export function autopilotHeartbeatPath(): string {
  return gbrainPath('autopilot.heartbeat.json');
}

/**
 * Written by the generated wrapper when it self-disables (its captured repo path
 * is gone). Read by the status command so a stopped daemon explains itself
 * instead of looking merely idle.
 */
export function autopilotDisabledMarkerPath(): string {
  return join(gbrainPath(), 'autopilot-disabled');
}

/** The pre-#5195 shared job names, still used by the default brain. */
export const DEFAULT_AUTOPILOT_LAUNCHD_LABEL = 'com.gbrain.autopilot';
export const DEFAULT_AUTOPILOT_SYSTEMD_UNIT = 'gbrain-autopilot.service';

/**
 * The launchd job label / plist basename. `suffix` names a non-default brain's
 * own job (#5195); the default brain keeps the shared label.
 *
 * The env override is a TEST SEAM, not a user knob: it exists so the real-launchd
 * lifecycle e2e can load a genuinely unique job on a dev Mac without colliding
 * with — or tearing down — the machine's actual autopilot install. It is read at
 * CALL time and wins over the per-brain suffix, so every invocation touching the
 * same install (install, status, uninstall, the generated wrapper's self-disable)
 * must run with the same value; a mismatched pair reports a false not-installed
 * or misses the plist.
 *
 * The grammar check is load-bearing: the label reaches a plist FILENAME and a
 * double-quoted shell line inside the generated wrapper. `escapeXml` protects
 * only the XML site, so slashes, quotes, whitespace, `$`, backticks, and
 * dot-dot must be rejected here.
 */
export function autopilotLaunchdLabel(suffix: string | null = null): string {
  const label = process.env.GBRAIN_AUTOPILOT_LABEL
    ?? (suffix ? `${DEFAULT_AUTOPILOT_LAUNCHD_LABEL}.${suffix}` : DEFAULT_AUTOPILOT_LAUNCHD_LABEL);
  if (!/^[A-Za-z0-9._-]+$/.test(label) || label.includes('..')) {
    throw new Error(`invalid GBRAIN_AUTOPILOT_LABEL: ${JSON.stringify(label)}`);
  }
  return label;
}

/** realpath, or `resolve` for a directory that does not exist yet (ENG-O11). */
export function canonicalDir(path: string): string {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- canonicalizes the operator's own brain home for the install-id record; no fs write
  try { return realpathSync(path); } catch { return resolve(path); }
}

/**
 * #5195: the default brain is the one at `~/.gbrain` (GBRAIN_HOME unset, or
 * pointing at the user's home). It keeps the shared job names so existing
 * installs need no migration; every other brain gets its own job.
 */
export function isDefaultBrainHome(): boolean {
  return canonicalDir(configDir()) === canonicalDir(join(homedir(), '.gbrain'));
}

/** Where a non-default brain records the random id its job names derive from. */
export function autopilotInstallIdPath(): string {
  return gbrainPath('autopilot-install-id');
}

interface InstallIdRecord { id: string; realpath: string; created_at: string }

function readInstallIdRecord(): InstallIdRecord | null {
  try {
    const rec = JSON.parse(readFileSync(autopilotInstallIdPath(), 'utf-8')) as Partial<InstallIdRecord>;
    if (typeof rec.id !== 'string' || !/^[0-9a-f]{8,64}$/.test(rec.id)) return null;
    if (typeof rec.realpath !== 'string' || !rec.realpath) return null;
    return { id: rec.id, realpath: rec.realpath, created_at: typeof rec.created_at === 'string' ? rec.created_at : '' };
  } catch {
    return null;
  }
}

/**
 * Read-only view of this brain's install id (T4, ENG-O11). The record names the
 * directory it was written for, because a copied brain carries the file along:
 *   - same     — recorded for this directory;
 *   - moved    — the recorded directory no longer exists, so this brain is it,
 *                moved or renamed (the id, and the job, carry over);
 *   - copied   — the recorded directory still exists elsewhere, so this is a
 *                copy that has not installed its own job yet;
 *   - none     — never installed.
 */
export function resolveAutopilotInstallId():
  | { relation: 'same' | 'moved'; id: string; recordedPath: string }
  | { relation: 'copied' | 'none'; id: null; recordedPath: string | null } {
  const rec = readInstallIdRecord();
  if (!rec) return { relation: 'none', id: null, recordedPath: null };
  if (rec.realpath === canonicalDir(configDir())) return { relation: 'same', id: rec.id, recordedPath: rec.realpath };
  if (!existsSync(rec.realpath)) return { relation: 'moved', id: rec.id, recordedPath: rec.realpath };
  return { relation: 'copied', id: null, recordedPath: rec.realpath };
}

function writeRecordExclusive(path: string, rec: InstallIdRecord): boolean {
  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
  writeFileSync(tmp, JSON.stringify(rec) + '\n', { mode: 0o644 });
  try {
    linkSync(tmp, path);
    return true;
  } catch (e) {
    if ((e as NodeJS.ErrnoException).code === 'EEXIST') return false;
    try {
      writeFileSync(path, JSON.stringify(rec) + '\n', { flag: 'wx', mode: 0o644 });
      return true;
    } catch (e2) {
      if ((e2 as NodeJS.ErrnoException).code === 'EEXIST') return false;
      throw e2;
    }
  } finally {
    try { unlinkSync(tmp); } catch { /* already gone */ }
  }
}

function replaceRecord(path: string, rec: InstallIdRecord): void {
  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
  writeFileSync(tmp, JSON.stringify(rec) + '\n', { mode: 0o644 });
  renameSync(tmp, path);
}

/**
 * One installer at a time decides a move or a copy: without it two installers
 * of a freshly copied brain could each mint an id, and the one whose record
 * lost would leave a job nobody can find. A crashed holder's lock is broken
 * after 30 seconds.
 */
function withInstallIdLock<T>(fn: () => T): T {
  const lock = `${autopilotInstallIdPath()}.lock`;
  const deadline = Date.now() + 10_000;
  for (;;) {
    try {
      mkdirSync(lock);
      break;
    } catch (e) {
      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
      try { if (Date.now() - statSync(lock).mtimeMs > 30_000) { rmdirSync(lock); continue; } } catch { continue; }
      if (Date.now() > deadline) throw new Error(`another autopilot install holds ${lock}; retry when it finishes`);
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
    }
  }
  try { return fn(); } finally { try { rmdirSync(lock); } catch { /* already gone */ } }
}

/**
 * The install id for this brain, minting or re-homing it as ENG-O11 describes.
 * The first record is created exclusively, so concurrent first installs agree on
 * one id; a move keeps the id and records the new directory; a copy mints its
 * own id so the original brain's job is never taken over. Moves and copies are
 * decided under a lock, so concurrent installers settle on one id.
 */
export function ensureAutopilotInstallId(): string {
  mkdirSync(configDir(), { recursive: true });
  const path = autopilotInstallIdPath();
  const here = canonicalDir(configDir());
  const current = resolveAutopilotInstallId();
  if (current.relation === 'same') return current.id;
  if (current.relation === 'none') {
    const fresh = { id: randomBytes(16).toString('hex'), realpath: here, created_at: new Date().toISOString() };
    if (writeRecordExclusive(path, fresh)) return fresh.id;
  }
  return withInstallIdLock(() => {
    const locked = resolveAutopilotInstallId();
    if (locked.relation === 'same') return locked.id;
    if (locked.relation === 'moved') {
      replaceRecord(path, { id: locked.id, realpath: here, created_at: readInstallIdRecord()?.created_at || new Date().toISOString() });
      return locked.id;
    }
    const fresh = { id: randomBytes(16).toString('hex'), realpath: here, created_at: new Date().toISOString() };
    replaceRecord(path, fresh);
    return fresh.id;
  });
}

/**
 * Every name one brain's autopilot job uses (#5195). The default brain keeps the
 * shared pre-#5195 names; any other brain gets `<name>-<suffix>` names, where the
 * suffix is the first 8 hex characters of its install id. `unassigned` is a
 * non-default brain that has no id yet (never installed, or an uninstalled
 * copy): it owns no named job, and its names are the shared ones only so the
 * pure generators have something to print.
 */
export interface AutopilotJob {
  kind: 'default' | 'suffixed' | 'unassigned';
  suffix: string | null;
  launchdLabel: string;
  systemdUnit: string;
  /** Ephemeral-container start script, under the brain's own home. */
  startScriptPath: string;
  /** Trailing crontab comment that marks this brain's line; null for the default brain. */
  cronMarker: string | null;
  wrapperPath: string;
  logPath: string;
  errPath: string;
  /** #8017: launchd starts the wrapper through /bin/bash because the brain home is on another volume (macOS only). */
  launchdViaBash?: boolean;
  installIdPath: string | null;
  /** configDir() at resolution time. */
  homeDir: string;
}

export function resolveAutopilotJob(opts: { mint?: boolean } = {}): AutopilotJob {
  const homeDir = configDir();
  let kind: AutopilotJob['kind'] = 'default';
  let suffix: string | null = null;
  if (!isDefaultBrainHome()) {
    const id = opts.mint ? ensureAutopilotInstallId() : resolveAutopilotInstallId().id;
    suffix = id ? id.slice(0, 8) : null;
    kind = suffix ? 'suffixed' : 'unassigned';
  }
  const logs = autopilotLaunchdHostPaths(homeDir, autopilotLaunchdLabel(suffix), homedir(), process.platform === 'darwin' ? undefined : () => 0);
  return {
    kind,
    suffix,
    launchdLabel: autopilotLaunchdLabel(suffix),
    systemdUnit: suffix ? `gbrain-autopilot-${suffix}.service` : DEFAULT_AUTOPILOT_SYSTEMD_UNIT,
    startScriptPath: join(homeDir, suffix ? `start-autopilot-${suffix}.sh` : 'start-autopilot.sh'),
    cronMarker: suffix ? `# gbrain-autopilot:${suffix}` : null,
    wrapperPath: join(homeDir, 'autopilot-run.sh'),
    logPath: logs.logPath,
    errPath: logs.errPath,
    ...(logs.viaBash ? { launchdViaBash: true } : {}),
    installIdPath: kind === 'default' ? null : autopilotInstallIdPath(),
    homeDir,
  };
}

/**
 * #8017: launchd's spawn helper opens a job's Program and its log files before the job runs, and ends the job with
 * EX_CONFIG (78) when they sit on a volume other than the user's home (a brain on an external GBRAIN_HOME). Such a
 * brain gets launchd paths on the home volume: /bin/bash starts the wrapper, and the logs go to
 * ~/Library/Logs/gbrain/<label>.log and .err. A brain on the home volume, or one whose volume cannot be read, keeps
 * its logs in the brain home.
 */
export function autopilotLaunchdHostPaths(
  homeDir: string,
  label: string,
  hostHome: string = homedir(),
  dev: (path: string) => number = path => statSync(path).dev,
): { viaBash: boolean; logPath: string; errPath: string } {
  let external = false;
  try { external = dev(homeDir) !== dev(hostHome); } catch { /* unreadable: keep the brain-home layout */ }
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- hostHome is this user's home directory and the rest are fixed segments.
  const [logDir, base] = external ? [join(hostHome, 'Library', 'Logs', 'gbrain'), label] : [homeDir, 'autopilot'];
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- logDir is the brain's own config dir or ~/Library/Logs/gbrain; label passed autopilotLaunchdLabel's [A-Za-z0-9._-] grammar, which rejects separators and '..'.
  return { viaBash: external, logPath: join(logDir, `${base}.log`), errPath: join(logDir, `${base}.err`) };
}

/**
 * Who a job definition belongs to, judged by the wrapper path it runs (the
 * wrapper always lives at `<brain home>/autopilot-run.sh`):
 *   - own      — this brain's wrapper;
 *   - dangling — a wrapper that no longer exists (a moved or deleted brain);
 *   - other    — a live wrapper of another brain (`home` is that brain's dir);
 *   - unknown  — the definition names no wrapper.
 */
export function autopilotWrapperOwner(
  wrapperPath: string | null,
  homeDir: string = configDir(),
): { owner: 'own' | 'dangling' | 'unknown' } | { owner: 'other'; home: string } {
  if (!wrapperPath) return { owner: 'unknown' };
  const dir = dirname(wrapperPath);
  if (canonicalDir(dir) === canonicalDir(homeDir)) return { owner: 'own' };
  if (!existsSync(wrapperPath)) return { owner: 'dangling' };
  return { owner: 'other', home: dir };
}

/**
 * Cooperative pause. While present the tick loop keeps heartbeating but does no
 * work. `gbrain migrate` uses it to quiesce the daemon for the
 * duration of a cross-engine copy, so the daemon cannot keep writing into an
 * engine that is about to stop being the configured one.
 *
 * A marker rather than stopping the supervisor: ephemeral-container installs
 * have no supervisor to restart afterwards, a crash mid-migration leaves a
 * removable file rather than an uninstalled daemon, and it is one code path
 * across launchd / systemd / cron / container.
 */
export function autopilotPausedMarkerPath(): string {
  return join(gbrainPath(), 'autopilot-paused');
}

/**
 * The daemon's latest brain-wide maintenance verdict (GBRA-130 C-6), written
 * each full-cycle tick so the engine-free `autopilot --status` can exit 1 while
 * maintenance is stalled without opening the database.
 */
export function autopilotGlobalMaintenanceVerdictPath(): string {
  return join(gbrainPath(), 'autopilot-global-maintenance.json');
}

/**
 * Consecutive-miss counter for the wrapper's self-disable guard. A repo on an
 * external volume, NFS, or a cloud-synced folder is routinely absent for the
 * first daemon launch after login, and a single missed probe must not
 * permanently take the install out of rotation — the guard requires several
 * consecutive strikes before disabling, and any successful probe resets this
 * file.
 */
export function autopilotDisableStrikesPath(): string {
  return join(gbrainPath(), 'autopilot-disable-strikes');
}

/**
 * First line of every pause marker written by `gbrain migrate` — the ownership
 * signature that separates a migrate-owned pause (safe to adopt when its pid
 * is dead) from an operator's manual hold (never touched).
 */
export const MIGRATE_PAUSE_MARKER_PREFIX = 'paused by gbrain migrate';

/**
 * Is the pid recorded in a pause-marker body still a live process?
 * ESRCH = provably dead. EPERM = exists but owned by another user: alive.
 * No parseable pid = unknown (treat as a foreign hold; adoption needs proof).
 */
export function markerHolderAlive(body: string): 'alive' | 'dead' | 'unknown' {
  const m = /\(pid (\d+)\)/.exec(body);
  if (!m) return 'unknown';
  try {
    process.kill(Number(m[1]), 0);
    return 'alive';
  } catch (e) {
    return (e as NodeJS.ErrnoException)?.code === 'ESRCH' ? 'dead' : 'alive';
  }
}

/**
 * The operator's own pause (the autopilot pause subcommand), kept apart from
 * the migration/restore hold above: installing autopilot and upgrading gbrain
 * clear a leaked migration hold but never this marker, and resuming clears
 * only this marker, never a live migration's hold.
 */
export function autopilotOperatorPauseMarkerPath(): string {
  return join(gbrainPath(), 'autopilot-operator-paused');
}

/** True while either pause marker is present; the daemon and workers do no new work. */
export function autopilotPaused(): boolean {
  return existsSync(autopilotOperatorPauseMarkerPath()) || existsSync(autopilotPausedMarkerPath());
}

/** The recorded reason for the active pause (the operator pause first), or null. */
export function autopilotPauseReason(): string | null {
  for (const path of [autopilotOperatorPauseMarkerPath(), autopilotPausedMarkerPath()]) {
    try { return readFileSync(path, 'utf-8').trim() || 'pause marker present (no reason recorded)'; } catch { /* not present */ }
  }
  return null;
}