Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* pglite-leftovers-check — detect abandoned PGLite stores after an engine
* migration (#3856).
*
* A pglite -> postgres migration leaves `brain.pglite/` (the old engine's
* store) under the gbrain home, untouched, forever. It weighs roughly as much
* as the live DB, nothing ever surfaces it, and it silently rides along in any
* backup that archives the gbrain home — the reporting brain paid to
* permanently archive a dead engine's corpse on Arweave for 2.5 months
* (~half the monthly cost, once excluded by hand).
*
* Pure assessment helpers (filesystem-only, no network, no shelling out) so
* `gbrain doctor` can warn with receipts, in the same shape as
* npm-squat-check.ts (#505). The caller supplies the engine kind — which MUST
* come from the DURABLE file config, not the resolved/env-overridden one: a
* transient `DATABASE_URL` (#427) can make a live PGLite brain look like
* postgres for one process, and deletion advice must never rest on that.
*
* Scope is deliberately `brain.pglite` alone — the one directory the engines
* themselves create. gbrain does NOT create pre-migrate safety copies or any
* other `brain.pglite.*` sibling (hand-made `.bak` copies, operator scripts,
* etc.); every such sibling has unknown provenance and is NOT claimed.
*
* Migration-in-flight gate: `gbrain migrate` banks resume progress in
* `migrate-manifest.json` at the gbrain home root and clears it only on clean
* completion — the same completion that flips the durable engine (#3194). So
* while the manifest exists, the durable engine can still read `postgres`
* even though `brain.pglite/` is the LIVE TARGET of an interrupted
* postgres -> pglite migration. Deleting it then would leave the manifest
* behind, and a re-run would silently skip the "already completed" pages
* against an empty store. The check therefore skips whenever the manifest is
* present and never assesses leftovers, let alone offers deletion advice.
*
* Deliberately warn-only with a MANUAL remediation: deciding when the old
* store is safe to drop is a policy question (#3856 ask 2) — this check only
* makes the corpse visible, it never deletes anything. The remediation text
* names no CLI command that does not exist (#3697).
*/
import { existsSync, lstatSync, opendirSync } from 'node:fs';
import { join } from 'node:path';
export interface PgliteLeftoverDir {
path: string;
/** Bytes summed over a bounded, symlink-free walk — a floor when size_incomplete. */
approx_bytes: number;
/** True when the walk hit its budget OR any entry was unreadable — approx_bytes is then a floor. */
size_incomplete: boolean;
/** The directory inode's own mtime (ISO) — labeled as such in the message: file
* contents can change without touching the parent dir's mtime. */
dir_mtime: string | null;
}
export interface PgliteLeftoversAssessment {
status: 'ok' | 'warn' | 'skip';
message: string;
leftovers: PgliteLeftoverDir[];
/** Engine graduation's retained source copies (`<path>.graduated-<run_id>`). */
retained?: PgliteLeftoverDir[];
}
/** Engine graduation's retained copy of a moved brain: `<data dir>.graduated-<run_id>`. */
export const GRADUATED_COPY_RE = /\.graduated-[A-Za-z0-9_-]+$/;
/** What graduation's manifest tells this check (file read by the caller). */
export interface GraduationLeftoverContext {
/** The manifest state is non-terminal: a move is in flight or interrupted. */
inFlight: boolean;
/** The retained copy path the manifest records (it can live outside the gbrain home). */
retainedPath?: string;
}
/**
* Bound on how many directory entries the size walk visits across the WHOLE
* assessment (all leftover dirs share one budget). A PGLite store is a modest
* number of large files, so real stores finish well under this; the cap exists
* so a pathological tree cannot stall doctor's synchronous path.
*/
export const SIZE_WALK_MAX_ENTRIES = 20_000;
/** The resume manifest `gbrain migrate` writes at the gbrain home root; it
* survives an interrupted run and is cleared only on clean completion. */
export const MIGRATE_MANIFEST_NAME = 'migrate-manifest.json';
/** True only for the one directory the legacy copier leaves: the old
* store `brain.pglite` (engine graduation's `<path>.graduated-<run_id>`
* copies are matched separately by GRADUATED_COPY_RE). gbrain never creates `brain.pglite.*` siblings
* (no pre-migrate copies, no backups) — those all have unknown provenance
* and are out of scope. */
export function isMigrationLeftoverName(name: string): boolean {
return name === 'brain.pglite';
}
/** Iterative, symlink-free size walk. Shares `budget` across calls; flags
* incompleteness on budget exhaustion AND on any unreadable entry (an
* unreadable multi-GB store must never be reported as exactly 0 B). */
function walkSize(root: string, budget: { entries: number }): { bytes: number; incomplete: boolean } {
let bytes = 0;
let incomplete = false;
const stack: string[] = [root];
while (stack.length > 0) {
const dir = stack.pop() as string;
let handle: ReturnType<typeof opendirSync>;
try {
handle = opendirSync(dir);
} catch {
incomplete = true;
continue;
}
try {
for (;;) {
if (budget.entries <= 0) {
incomplete = true;
break;
}
let entry: ReturnType<typeof handle.readSync>;
try {
entry = handle.readSync();
} catch {
// opendirSync can succeed on a dir whose entries we cannot read
// (mode 000) — the EACCES surfaces here, not at open (measured).
incomplete = true;
break;
}
if (entry === null) break;
budget.entries--;
const p = join(dir, entry.name);
if (entry.isSymbolicLink()) continue; // never follow — the walk must not escape the store
if (entry.isDirectory()) {
stack.push(p);
} else if (entry.isFile()) {
try {
bytes += lstatSync(p).size;
} catch {
incomplete = true;
}
}
}
} finally {
try {
handle.closeSync();
} catch {
// already closed / racing unlink — nothing to do
}
}
if (budget.entries <= 0 && stack.length > 0) {
incomplete = true;
break;
}
}
return { bytes, incomplete };
}
/** Human-readable size. For floors (incomplete walks) the value is rounded
* DOWN, so ">= 1.6 MB" can never display as ">= 2 MB". */
function humanBytes(n: number, floor: boolean): string {
const fmt = (v: number, digits: number) => (floor ? Math.floor(v * 10 ** digits) / 10 ** digits : v).toFixed(digits);
if (n >= 1024 ** 3) return `${fmt(n / 1024 ** 3, 1)} GB`;
if (n >= 1024 ** 2) return `${fmt(n / 1024 ** 2, 0)} MB`;
if (n >= 1024) return `${fmt(n / 1024, 0)} KB`;
return `${n} B`;
}
/**
* Assess a gbrain home for abandoned PGLite migration leftovers.
*
* - engine `postgres` is the ONLY value that can warn: that is the migration
* target #3856 documents, and the one case where `brain.pglite` is known
* dead weight. `pglite` means the store is live; anything else (missing /
* unreadable / future engines) skips — deletion advice must fail open.
* - `migrate-manifest.json` present at the home root -> `skip`, even on a
* durable postgres engine: an engine migration is in progress or was
* interrupted, and `brain.pglite` may be its live target (see file header).
* - postgres + no leftover dirs -> `ok`.
* - postgres + leftovers -> `warn`, naming each dir with a floor-marked
* approximate size and its directory mtime.
*
* `engineKind` must be the DURABLE file-config engine (see file header).
* `maxEntries` exists for tests; production callers use the default.
*/
export function assessPgliteLeftovers(
engineKind: string | null | undefined,
gbrainHome: string,
maxEntries: number = SIZE_WALK_MAX_ENTRIES,
graduation: GraduationLeftoverContext | null = null,
): PgliteLeftoversAssessment {
if (engineKind !== 'postgres') {
return { status: 'skip', message: '', leftovers: [] };
}
if (graduation?.inFlight) {
return {
status: 'skip',
message: 'An engine graduation is in flight or interrupted; its PGLite source and retained copy are not leftovers until it finishes.',
leftovers: [],
};
}
if (existsSync(join(gbrainHome, MIGRATE_MANIFEST_NAME))) {
return {
status: 'skip',
message:
`${MIGRATE_MANIFEST_NAME} is present: an engine migration is in progress or was ` +
`interrupted, and brain.pglite may be the live migration target — not assessing leftovers.`,
leftovers: [],
};
}
let names: string[] = [];
const retainedPaths = new Set<string>();
const budget = { entries: maxEntries };
try {
const handle = opendirSync(gbrainHome);
try {
for (;;) {
const entry = handle.readSync();
if (entry === null) break;
// Top-level symlinks are skipped too: a symlinked brain.pglite is not
// a store this check can claim ownership of.
if (entry.isDirectory() && !entry.isSymbolicLink() && isMigrationLeftoverName(entry.name)) {
names.push(entry.name);
} else if (entry.isDirectory() && !entry.isSymbolicLink() && GRADUATED_COPY_RE.test(entry.name)) {
retainedPaths.add(join(gbrainHome, entry.name));
}
}
} finally {
handle.closeSync();
}
} catch {
return { status: 'skip', message: '', leftovers: [] };
}
if (graduation?.retainedPath) {
try {
const st = lstatSync(graduation.retainedPath);
if (st.isDirectory() && !st.isSymbolicLink()) retainedPaths.add(graduation.retainedPath);
} catch {
// the user already deleted it — nothing to report
}
}
const measure = (p: string): PgliteLeftoverDir => {
let mtime: string | null = null;
try {
const st = lstatSync(p);
mtime = st.mtime ? st.mtime.toISOString() : null;
} catch {
// stat raced a concurrent delete — still report the dir, without a date
}
const { bytes, incomplete } = walkSize(p, budget);
return { path: p, approx_bytes: bytes, size_incomplete: incomplete, dir_mtime: mtime };
};
const leftovers: PgliteLeftoverDir[] = names.sort().map(name => measure(join(gbrainHome, name)));
const retained: PgliteLeftoverDir[] = [...retainedPaths].sort().map(measure);
if (retained.length > 0) {
const listing = retained.map(l => `${l.path} (${l.size_incomplete ? '>=' : ''}${humanBytes(l.approx_bytes, l.size_incomplete)})`).join('; ');
const legacy = leftovers.length ? ` The legacy copier's old store also remains: ${leftovers.map(l => l.path).join('; ')}.` : '';
return {
status: 'warn',
message:
`Engine graduation kept the PGLite brain it moved to Postgres: ${listing}. It still holds private ` +
`memory and access-token hashes, and it is what a rollback to PGLite restores. Deleting it is the ` +
`user's call; afterwards a rollback is no longer possible.${legacy}`,
leftovers,
retained,
};
}
if (leftovers.length === 0) {
return {
status: 'ok',
message: 'No abandoned PGLite store under the gbrain home (engine: postgres).',
leftovers,
};
}
const total = leftovers.reduce((s, l) => s + l.approx_bytes, 0);
const anyIncomplete = leftovers.some((l) => l.size_incomplete);
const listing = leftovers
.map(
(l) =>
`${l.path} (${l.size_incomplete ? '>=' : ''}${humanBytes(l.approx_bytes, l.size_incomplete)}` +
`${l.dir_mtime ? `, dir mtime ${l.dir_mtime.slice(0, 10)}` : ''})`,
)
.join('; ');
return {
status: 'warn',
message:
`Engine is postgres, but the old PGLite store remains: ${listing} — ` +
`${anyIncomplete ? 'at least ' : ''}${humanBytes(total, anyIncomplete)} of reclaimable disk. ` +
`It also inflates any backup that archives the gbrain home. Your live data is in the postgres ` +
`engine; once you have verified that (a recent restore or backup of it), the dir is safe to ` +
`delete by hand — gbrain never deletes it for you. Preview: du -sh ${leftovers[0]!.path}; then, after the user agrees: ` +
`${leftovers.map((l) => `rm -rf ${l.path}`).join('; ')}.`,
leftovers,
};
}