Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The engine-free core of `gbrain pglite-repair --legacy-lock` (GBRA-130 C-3):
* a legacy (pre-kernel) `<data-dir>/.gbrain-lock/` whose owner `acquireLock`
* cannot prove dead refuses `pglite_busy` reason `legacy_owner_unverified`
* forever, so this is its exit.
*
* `inspectLegacyLock` is read-only and never creates anything: it reports the
* legacy metadata, a verdict, the plan hash an approved removal binds (the
* canonical data dir plus the legacy dir's inode, every entry's bytes and the
* marker bytes) and ADVISORY evidence: kill -0 and the command of the recorded
* PID, an open-file scan of /proc (Linux), and the filesystem type (Linux
* statfs; macOS `df -P` plus `mount`, local only with the `local` flag). That evidence covers only this host and PID namespace; it cannot
* see other containers, PID namespaces or hosts sharing the folder, so it is
* never stated as proof. A live holder (an open file under the data dir, a
* live recorded PID whose command could be gbrain, or a comparable live PID),
* a network/shared filesystem, or a filesystem whose locality cannot be read
* (neither Linux nor macOS, a failed probe, an unrecognised type, a macOS
* mount without the `local` flag: fail closed) makes the lock
* not removable.
*
* `applyLegacyLockRemoval` runs only under the stable sibling kernel lock and
* after consent bound to the plan hash: it moves the legacy dir into a sibling
* `<data-dir>.legacy-lock-removed-<ts>/` (nothing is deleted), writes the
* kernel-v1 marker the normal path writes, starts the 10-minute WAL-repair
* quarantine (`<data-dir>.lock-reap.json`, read by `msSinceLastReap`) and
* leaves a receipt with the exact restore command, which also puts back the
* prior ownership marker's exact bytes (or removes the new marker when there
* was none), so an undo restores the original refusal.
*/
import { createHash } from 'node:crypto';
import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, statfsSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { shellQuote } from './agent-output.ts';
import { execFileSync } from './spawn.ts';
import { computePlanHash, type PlanSelection } from './consent.ts';
import { isProcessAlive, legacyOwnerUnverified, pgliteLockDirFor, readMetadata, readProcessArgs, PGLITE_LOCK_PROTOCOL, type LegacyUnverifiedReason } from './pglite-lock.ts';
/** Linux statfs magic numbers of filesystems another host (or a VM host) can mount, where this host cannot see every process. */
const NETWORK_FILESYSTEMS: Readonly<Record<number, string>> = {
0x6969: 'nfs', 0xff534d42: 'cifs', 0xfe534d42: 'smb2', 0x517b: 'smb', 0x01021997: '9p', 0x5346414f: 'afs', 0x73757245: 'coda',
0x564c: 'ncp', 0x00c36400: 'ceph', 0x01161970: 'gfs2', 0x7461636f: 'ocfs2', 0x6a656a63: 'virtiofs', 0x65735546: 'fuse',
0x47504653: 'gpfs', 0x0bd00bd0: 'lustre',
};
const LOCAL_FILESYSTEMS: Readonly<Record<number, string>> = {
0xef53: 'ext4', 0x58465342: 'xfs', 0x9123683e: 'btrfs', 0x01021994: 'tmpfs', 0x794c7630: 'overlay', 0x2fc12fc1: 'zfs', 0xf2f52010: 'f2fs',
0xca451a4e: 'bcachefs', 0x4d44: 'vfat', 0x2011bab0: 'exfat', 0x5346544e: 'ntfs', 0x7366746e: 'ntfs3', 0x482b: 'hfsplus', 0x858458f6: 'ramfs',
0x52654973: 'reiserfs', 0x3153464a: 'jfs', 0x3434: 'nilfs',
};
/** macOS `mount` types that are local disks; a mount counts as local only with one of these AND the `local` flag. */
const DARWIN_LOCAL_FILESYSTEMS: ReadonlySet<string> = new Set(['apfs', 'hfs', 'exfat', 'msdos']);
export function networkFilesystemName(magic: number): string | null {
return NETWORK_FILESYSTEMS[magic >>> 0] ?? null;
}
export const LEGACY_LOCK_EVIDENCE_SCOPE = 'Advisory only: kill -0, the process command and the open-file scan cover only this host and PID namespace. '
+ 'They cannot see processes in other containers or PID namespaces, or on other hosts that share this folder, so they are not proof that the old owner has stopped.';
export interface LegacyLockEvidence {
advisory: true;
scope: string;
pid: number | null;
pid_alive: boolean | null;
pid_command: string | null;
fd_scan: { method: 'proc' | 'unavailable'; holders: Array<{ pid: number; command: string | null; paths: string[] }>; uninspectable: number };
/** `network: null` means locality is unknown (neither Linux nor macOS, a failed probe, an unrecognised type, or a macOS mount that is not local) and refuses `filesystem_unverified`. */
filesystem: { type: string | null; magic: number | null; network: boolean | null };
}
export interface LegacyLockInspection {
data_dir: string;
legacy_lock: {
dir: string;
present: boolean;
/** The dir would block a kernel-v1 open (no marker yet, or metadata from another protocol). */
legacy: boolean;
verdict: 'absent' | 'current' | 'live' | 'dead' | 'unverified';
reason: LegacyUnverifiedReason | null;
metadata: { pid: number | null; command: string | null; acquired_at: number | null; pid_ns: string | null; boot_id: string | null } | null;
};
evidence: LegacyLockEvidence | null;
refusal: { reason: 'live_holder' | 'network_filesystem' | 'filesystem_unverified'; message: string } | null;
removable: boolean;
plan_hash: string | null;
selection: PlanSelection | null;
}
const sha256 = (bytes: Buffer | string) => createHash('sha256').update(bytes).digest('hex');
const markerPathOf = (dataDir: string) => `${dataDir}.gbrain-owner.json`;
/** Test seam for the host probes; production reads the real platform and statfs. */
export interface LegacyLockProbe {
platform?: NodeJS.Platform;
statfs?: (path: string) => { type: number };
/** Runs an absolute-path command without a shell and returns its stdout (macOS `df` and `mount`). */
exec?: (file: string, args: readonly string[]) => string;
}
const execNoShell = (file: string, args: readonly string[]): string =>
String(execFileSync(file, [...args], { encoding: 'utf8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, LC_ALL: 'C' } }));
function scanOpenFiles(dataDir: string, platform: NodeJS.Platform): LegacyLockEvidence['fd_scan'] {
if (platform !== 'linux' || !existsSync('/proc/self/fd')) return { method: 'unavailable', holders: [], uninspectable: 0 };
const holders: LegacyLockEvidence['fd_scan']['holders'] = [];
let uninspectable = 0;
for (const entry of readdirSync('/proc')) {
const pid = Number(entry);
if (!/^\d+$/.test(entry) || pid === process.pid) continue;
let fds: string[];
try { fds = readdirSync(`/proc/${pid}/fd`); } catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') uninspectable++;
continue;
}
const paths = new Set<string>();
for (const fd of fds) {
let target: string;
try { target = readlinkSync(`/proc/${pid}/fd/${fd}`); } catch { continue; }
if (target === dataDir || target.startsWith(`${dataDir}/`)) paths.add(target);
}
if (paths.size > 0) holders.push({ pid, command: readProcessArgs(pid)?.slice(0, 200) ?? null, paths: [...paths].sort().slice(0, 5) });
}
return { method: 'proc', holders, uninspectable };
}
/**
* macOS: the data dir's mount point from `df -P` (everything after the
* capacity column, so spaces survive), then that mount point's one line in
* `mount` (`<dev> on <mountpoint> (<type>, <flags...>)`). Local only with the
* `local` flag and a known-local type; anything else, including a network
* type, a missing or duplicated line and any parse or command failure, is
* unknown (`network: null`).
*/
function darwinFilesystemOf(dataDir: string, exec: NonNullable<LegacyLockProbe['exec']>): LegacyLockEvidence['filesystem'] {
const unknown = (type: string | null = null) => ({ type, magic: null, network: null });
try {
const df = exec('/bin/df', ['-P', dataDir]).split('\n').filter(line => line.trim() !== '');
const mountPoint = df.length === 2 ? /^.+?\s+\d+\s+\d+\s+\d+\s+\d+%\s+(.+)$/.exec(df[1]!)?.[1] : undefined;
if (!mountPoint) return unknown();
const marker = ` on ${mountPoint} (`;
const lines = exec('/sbin/mount', []).split('\n').filter(line => line.endsWith(')') && line.includes(marker));
if (lines.length !== 1) return unknown();
const [type, ...flags] = lines[0]!.slice(lines[0]!.indexOf(marker) + marker.length, -1).split(',').map(part => part.trim());
if (!type) return unknown();
return flags.includes('local') && DARWIN_LOCAL_FILESYSTEMS.has(type) ? { type, magic: null, network: false } : unknown(type);
} catch { return unknown(); }
}
function filesystemOf(dataDir: string, probe: LegacyLockProbe): LegacyLockEvidence['filesystem'] {
const platform = probe.platform ?? process.platform;
if (platform === 'darwin') return darwinFilesystemOf(dataDir, probe.exec ?? execNoShell);
if (platform !== 'linux') return { type: null, magic: null, network: null };
try {
const magic = (probe.statfs ?? statfsSync)(dataDir).type >>> 0;
const network = networkFilesystemName(magic);
const local = LOCAL_FILESYSTEMS[magic];
return { type: network ?? local ?? `0x${magic.toString(16)}`, magic, network: network !== null ? true : local ? false : null };
} catch { return { type: null, magic: null, network: null }; }
}
/** Whether a live recorded PID could still be the legacy gbrain: its command is unreadable, names gbrain, or names the recorded script. */
function couldBeOwner(command: string | null, recorded: string | null): boolean {
if (command === null) return true;
if (command.includes('gbrain')) return true;
const script = recorded?.trim().split(/\s+/)[0];
return !!script && command.includes(script);
}
function planSelection(dataDir: string, lockDir: string): PlanSelection {
const dir = lstatSync(lockDir);
const entries = readdirSync(lockDir).sort().map(name => {
const path = join(lockDir, name);
const st = lstatSync(path);
return { id: `.gbrain-lock/${name}`, revision: st.isFile() ? sha256(readFileSync(path)) : `${st.isDirectory() ? 'dir' : 'other'}:${st.ino}` };
});
const marker = markerPathOf(dataDir);
return {
brain: dataDir, source: null, operation: 'pglite-repair --legacy-lock',
records: [{ id: '.gbrain-lock', revision: `${dir.dev}:${dir.ino}` }, ...entries],
parameters: { marker: existsSync(marker) ? sha256(readFileSync(marker)) : null }, effects: ['destructive'],
};
}
function evidenceFor(dataDir: string, pid: number | null, recordedCommand: string | null, verdict: LegacyLockInspection['legacy_lock']['verdict'], probe: LegacyLockProbe): { evidence: LegacyLockEvidence; refusal: LegacyLockInspection['refusal'] } {
const pidAlive = pid === null ? null : isProcessAlive(pid);
const pidCommand = pid !== null && pidAlive ? readProcessArgs(pid)?.slice(0, 200) ?? null : null;
const evidence: LegacyLockEvidence = { advisory: true, scope: LEGACY_LOCK_EVIDENCE_SCOPE, pid, pid_alive: pidAlive, pid_command: pidCommand,
fd_scan: scanOpenFiles(dataDir, probe.platform ?? process.platform), filesystem: filesystemOf(dataDir, probe) };
const holder = evidence.fd_scan.holders[0];
if (holder) return { evidence, refusal: { reason: 'live_holder', message: `Process ${holder.pid} (${holder.command ?? 'command unreadable'}) has ${holder.paths[0]} open, so the data dir is still in use on this host.` } };
if (pidAlive && (verdict === 'live' || couldBeOwner(pidCommand, recordedCommand))) {
return { evidence, refusal: { reason: 'live_holder', message: `The recorded legacy PID ${pid} is running (${pidCommand ?? 'command unreadable'}) and may still be the old gbrain.` } };
}
const fs = evidence.filesystem, platform = probe.platform ?? process.platform;
if (fs.network) {
return { evidence, refusal: { reason: 'network_filesystem', message: `The data dir is on a ${fs.type} filesystem that other hosts can mount; this host cannot see their processes.` } };
}
if (fs.network === null) {
const why = platform !== 'linux' && platform !== 'darwin' ? `gbrain reads filesystem locality only on Linux and macOS and this host runs ${platform}`
: fs.type === null ? `reading its filesystem type (${platform === 'darwin' ? 'df and mount' : 'statfs'}) failed`
: `its filesystem ${fs.type} is not one gbrain can confirm is a local disk`;
return { evidence, refusal: { reason: 'filesystem_unverified', message: `gbrain could not confirm that the data dir is on a local filesystem (${why}), so another host sharing this folder could still hold the lock.` } };
}
return { evidence, refusal: null };
}
/** Read-only: never creates the data dir, the legacy dir or the kernel lock. */
export function inspectLegacyLock(path: string, probe: LegacyLockProbe = {}): LegacyLockInspection {
const lockDir = pgliteLockDirFor(path), dataDir = dirname(lockDir);
const present = existsSync(lockDir) && lstatSync(lockDir).isDirectory();
let migrated = false;
try { migrated = JSON.parse(readFileSync(markerPathOf(dataDir), 'utf8')).protocol === PGLITE_LOCK_PROTOCOL; } catch { /* not yet upgraded */ }
const metadata = present ? readMetadata(lockDir) : null;
const legacy = present && (!migrated || (!!metadata && metadata.protocol !== PGLITE_LOCK_PROTOCOL));
const reason = legacy ? legacyOwnerUnverified(metadata, lockDir) : null;
const pid = Number.isInteger(metadata?.pid) && metadata!.pid! > 0 ? metadata!.pid! : null;
const verdict = !present ? 'absent' : !legacy ? 'current' : reason ? 'unverified' : isProcessAlive(pid!) ? 'live' : 'dead';
const recordedCommand = typeof metadata?.command === 'string' ? metadata.command : null;
const { evidence, refusal } = legacy ? evidenceFor(dataDir, pid, recordedCommand, verdict, probe) : { evidence: null, refusal: null };
const selection = legacy ? planSelection(dataDir, lockDir) : null;
return {
data_dir: dataDir,
legacy_lock: { dir: lockDir, present, legacy, verdict, reason,
metadata: metadata ? { pid, command: recordedCommand, acquired_at: typeof metadata.acquired_at === 'number' ? metadata.acquired_at : null,
pid_ns: metadata.pid_ns ?? null, boot_id: metadata.boot_id ?? null } : null },
evidence, refusal, removable: legacy && refusal === null,
plan_hash: selection ? computePlanHash(selection) : null, selection,
};
}
export interface LegacyLockRemovalReceipt {
action: 'removed';
data_dir: string;
moved_to: string;
marker_path: string;
prior_marker: string | null;
/** Exact bytes of the prior ownership marker, restored by `restore_command`; null when there was none (the undo removes the new marker). */
prior_marker_backup: string | null;
plan_hash: string;
removed_at: string;
evidence: LegacyLockEvidence | null;
restore_command: string;
}
/** Caller holds the stable sibling kernel lock and consent bound to `inspection.plan_hash`, re-inspected under that lock. */
export function applyLegacyLockRemoval(inspection: LegacyLockInspection, now = new Date()): LegacyLockRemovalReceipt {
const { data_dir: dataDir, legacy_lock: { dir: lockDir } } = inspection;
const markerPath = markerPathOf(dataDir);
const priorBytes = existsSync(markerPath) ? readFileSync(markerPath) : null;
const movedTo = `${dataDir}.legacy-lock-removed-${now.toISOString().replace(/[:.]/g, '-')}`;
mkdirSync(movedTo, { mode: 0o700 });
const priorBackup = priorBytes === null ? null : join(movedTo, 'prior-owner-marker.json');
if (priorBackup) writeFileSync(priorBackup, priorBytes!, { mode: 0o600 });
renameSync(lockDir, join(movedTo, '.gbrain-lock'));
writeFileSync(markerPath, JSON.stringify({ protocol: PGLITE_LOCK_PROTOCOL }), { mode: 0o600 });
writeFileSync(`${dataDir}.lock-reap.json`, JSON.stringify({ ts: now.getTime(), reason: 'legacy_lock_removed' }), { mode: 0o600 });
const restoring = `${markerPath}.restore`;
const markerUndo = priorBackup === null ? [shellQuote(['rm', '-f', markerPath])]
: [shellQuote(['cp', priorBackup, restoring]), shellQuote(['mv', '-f', restoring, markerPath])];
const restore = [shellQuote(['mv', join(movedTo, '.gbrain-lock'), lockDir]), ...markerUndo].join(' && ');
const receipt: LegacyLockRemovalReceipt = { action: 'removed', data_dir: dataDir, moved_to: movedTo, marker_path: markerPath,
prior_marker: priorBytes === null ? null : priorBytes.toString('utf8'), prior_marker_backup: priorBackup,
plan_hash: inspection.plan_hash!, removed_at: now.toISOString(), evidence: inspection.evidence, restore_command: restore };
writeFileSync(join(movedTo, 'receipt.json'), `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
return receipt;
}