Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.8 KB
Raw Blame
import { existsSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { persistenceHome, existingHostIdFor } from './identity.ts';
import { containsPath, getWorktreeBinding, readManagedMode, type WorktreeBinding } from './ownership.ts';
import { verifyOwnerRoot } from './owner-verification.ts';
import { readPhysicalRootReservation, readWedgedPhysicalRootReservation } from './physical-root-record.ts';
import { coordinationHomeIgnored, coordinationLockDirectory } from './coordination-lock.ts';
import { inspectLegacyWriterLocks } from './legacy-locks.ts';
import { UNSUPPORTED_MANAGED_BULK_WRITERS } from './maintenance.ts';
import { isConnectorSourceKind } from './connector-identity.ts';
import { writeThroughConfigured } from './switches.ts';

export function containerPathPreflight(paths: Record<string, string>, mountinfo?: string, container?: boolean) {
  if (container === undefined) container = existsSync('/.dockerenv') || existsSync('/run/.containerenv');
  if (mountinfo === undefined && process.platform === 'linux') {
    try { mountinfo = readFileSync('/proc/self/mountinfo', 'utf8'); } catch { mountinfo = ''; }
  }
  const mounts = (mountinfo ?? '').split('\n').flatMap(line => {
    const [fields, filesystem] = line.split(' - ');
    const mount = fields?.split(' ')[4];
    return mount && filesystem ? [{ path: mount.replace(/\\([0-7]{3})/g, (_match, octal) => String.fromCharCode(parseInt(octal, 8))), type: filesystem.split(' ')[0] }] : [];
  }).sort((a, b) => b.path.length - a.path.length);
  return { container, durability_verified: false, paths: Object.entries(paths).map(([role, path]) => {
    const mount = mounts.find(entry => containsPath(entry.path, path));
    const ephemeral = !!mount && (['tmpfs', 'ramfs'].includes(mount.type) || container && ['overlay', 'aufs'].includes(mount.type));
    return { role, path, backing: ephemeral ? 'ephemeral' : mount ? 'mounted_unverified' : 'unknown', mount_path: mount?.path ?? null, filesystem: mount?.type ?? null };
  }), next_action: 'Verify that the canonical checkout, its parent (which holds the sibling reservation), and the persistence home/coordination lock survive container recreation together. A mounted path is not proof of durability. '
    + 'When GBRAIN_HOME lies inside the checkout, the lock is placed under GBRAIN_COORDINATION_HOME (else ~/.gbrain/persistence) instead, so set GBRAIN_COORDINATION_HOME to a mounted directory outside the checkout. '
    + 'A reservation an older release wrote with its lock inside the checkout (coordination_lock.old_path_wedge, "must live outside the canonical checkout") is repaired by the next claim on the host that reserved it. Do not delete ownership or lock files.' };
}

/**
 * #6765: the coordination lock path of `root` and the rule that chose it, as a claim or transfer resolves it
 * (coordination-lock.ts); an unclaimed root without a reservation reports the directory a claim would use.
 * Read-only: never mints a host identity, so before the first claim the fallback namespace is left off.
 */
function coordinationLockStatus(root: string, binding: WorktreeBinding | null, host: string | null): Record<string, unknown> {
  try {
    const wedged = readWedgedPhysicalRootReservation(root);
    if (wedged) return { path: wedged.coordinationPath, rule: 'reservation', old_path_wedge: true };
    const reservation = readPhysicalRootReservation(root)?.coordinationPath;
    const recorded = reservation ? { path: reservation, rule: 'reservation' } : binding?.coordination_path ? { path: binding.coordination_path, rule: 'binding' } : null;
    if (recorded) {
      const ignored = coordinationHomeIgnored(root, recorded.path);
      return ignored ? { ...recorded, coordination_home_ignored: ignored } : recorded;
    }
    return { path: null, ...coordinationLockDirectory(root, host) };
  } catch (error) {
    return { path: binding?.coordination_path ?? null, rule: null, error: error instanceof Error ? error.message : String(error) };
  }
}

export async function writerOnboardingPreflight(engine: BrainEngine, sourceId?: string) {
  const managed = await readManagedMode(engine);
  const rows = await engine.executeRaw<{ id: string; local_path: string | null; incarnation: string; kind: string | null }>(
    "SELECT id,local_path,incarnation,config->>'kind' AS kind FROM sources WHERE NOT archived AND ($1::text IS NULL OR id=$1) ORDER BY id", [sourceId ?? null]);
  const fallback = await engine.getConfig('sync.repo_path'), host = existingHostIdFor(engine);
  const writeThrough = writeThroughConfigured(await engine.getConfig('sync.write_through'));
  const sources = [];
  for (const row of rows) {
    const binding = await getWorktreeBinding(engine, row.id, host), configured = row.local_path || (row.id === 'default' ? fallback : null);
    const connector = isConnectorSourceKind(row.kind);
    let state = !binding ? connector ? 'connector_database' : configured && writeThrough ? 'claim_required' : 'database_only' : !managed ? 'activation_required' : 'ready';
    let physicalError: string | undefined;
    if (binding && (binding.source_incarnation !== row.incarnation || binding.state !== 'active')) state = 'recovery_required';
    if (binding && binding.owner_host_id !== host) state = 'owner_host_required';
    // #6741 C: the claim's owner verification, shared with background admissions (owner-verification.ts).
    const owner = binding?.owner_host_id === host ? verifyOwnerRoot(binding) : null;
    if (owner) { state = 'recovery_required'; physicalError = owner.physical_error; }
    const root = binding?.local_path ?? (connector ? null : configured);
    const lock = root ? coordinationLockStatus(root, binding, host) : undefined;
    const lockDirectory = typeof lock?.path === 'string' ? dirname(lock.path) : typeof lock?.directory === 'string' ? lock.directory : join(persistenceHome(), 'locks');
    const paths = root ? containerPathPreflight({ canonical_root: root, reservation_parent: dirname(root), persistence_home: persistenceHome(),
      coordination_directory: lockDirectory }) : undefined;
    sources.push({ source_id: row.id, state, write_through: writeThrough, ...(physicalError ? { physical_error: physicalError } : {}),
      ...(lock ? { coordination_lock: lock } : {}), ...(paths ? { storage: paths } : {}) });
  }
  return { sources, legacy_locks: await inspectLegacyWriterLocks(engine), unsupported_maintenance: [...UNSUPPORTED_MANAGED_BULK_WRITERS],
    procedure: 'For deliberate onboarding, stop and upgrade older writers on every host, review all sources and durable paths, explicitly claim each filesystem source using its fresh admin_state, inspect status again, then explicitly activate with --confirm-quiesced and a fresh admin_state. A claim alone fences legacy sync; finish activation before ordinary writes or sync. This inspection never claims, activates, repairs or switches to database-only storage.' };
}