Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6712 PR 2 (L4): after a managed sync, count the source's ghost pages (live pages whose canonical file is gone) with the
* one classifier, `scanGhostSource` (ghost-pages.ts), and name the read-only `gbrain repair ghost-pages` preview. Sync never
* deletes or tombstones such a page on its own: a file missing from the checkout but not deleted in Git is either an edit
* in progress or a mistake, and only a person decides which. A path that holds a sync hold (a held deletion) is the hold's
* to settle and is not counted. Bounded by the scan's own limits; off the owner host, or when the scan cannot tell, there
* is no count. Best effort: a failed scan never fails the sync.
*
* GBRA-133 2b.2: the scan reads every live page of the source (365 ms at 100k pages), and ghosts are outside the git
* delta, so it keeps its full walk but no longer runs inside the sync. `countSyncGhosts` answers from the source's last
* scan (one op_checkpoints row, op `sync-ghost-report`, fingerprint the source id) and, at most once per
* `GBRAIN_SYNC_GHOST_INTERVAL_MS` (default 5 minutes) per source across processes (an atomic claim on that row), starts
* the scan in the background, and only once a sync has landed since the last claim (`sources.last_sync_at`, which every
* successful sync stamps): a cancelled or never-landed sync writes nothing. The sync returns, and releases its drain lease and the serve's single-flight slot, without
* waiting; the next sync reports what the scan found. A CLI exit waits for an in-flight scan within the background-work
* drain budget; an engine disconnect aborts it before the next statement. Every decision is recorded
* (`syncGhostDecisions`) for tests.
*/
import type { BrainEngine } from '../engine.ts';
import type { Action } from '../agent-output.ts';
import { registerBackgroundWorkDrainer } from '../background-work.ts';
import { scanGhostSource } from '../ghost-pages.ts';
import { GIT_HOLD_OP, gitHoldFingerprint } from './sync-holds.ts';
/** Full checks per sync: the count is exact up to this many candidates, `truncated` past it. */
export const SYNC_GHOST_CHECK_LIMIT = 50;
export const SYNC_GHOST_REPORT_OP = 'sync-ghost-report';
export const SYNC_GHOST_INTERVAL_MS_DEFAULT = 300_000;
export interface SyncGhostPages { count: number; truncated: boolean; samples: string[]; fix: Action; observed_at?: string }
export type SyncGhostDecision = { source_id: string; decision: 'scan_started' | 'rate_limited' | 'scan_in_flight' | 'scan_done' | 'scan_failed' | 'scan_aborted'; error?: string };
/** The last decisions of this process, oldest first (bounded). */
export const syncGhostDecisions: SyncGhostDecision[] = [];
function decide(source_id: string, decision: SyncGhostDecision['decision'], error?: unknown): void {
syncGhostDecisions.push({ source_id, decision, ...(error === undefined ? {} : { error: error instanceof Error ? error.message : String(error) }) });
if (syncGhostDecisions.length > 200) syncGhostDecisions.splice(0, syncGhostDecisions.length - 200);
}
function scanIntervalMs(env: Record<string, string | undefined> = process.env): number {
const raw = env.GBRAIN_SYNC_GHOST_INTERVAL_MS;
const value = raw === undefined || raw === '' ? NaN : Number(raw);
return Number.isFinite(value) && value >= 0 ? Math.floor(value) : SYNC_GHOST_INTERVAL_MS_DEFAULT;
}
interface EngineScans { inFlight: Map<string, Promise<void>>; controller: AbortController; unregister: () => void }
const scans = new Map<BrainEngine, EngineScans>();
/** The ghost report from the source's last scan; starts a background scan when the source's interval has passed. */
export async function countSyncGhosts(engine: BrainEngine, sourceId: string): Promise<SyncGhostPages | null> {
const inFlight = scans.get(engine)?.inFlight.has(sourceId) === true;
const [row] = await engine.executeRaw<{ report: SyncGhostPages[] | null; claimed: boolean }>(inFlight
? 'SELECT completed_keys AS report, false AS claimed FROM op_checkpoints WHERE op=$1 AND fingerprint=$2'
: `WITH prior AS (SELECT completed_keys FROM op_checkpoints WHERE op=$1 AND fingerprint=$2),
claim AS (INSERT INTO op_checkpoints (op, fingerprint, completed_keys, updated_at)
SELECT $1, $2, '[]'::jsonb, now() WHERE EXISTS (SELECT 1 FROM sources WHERE id=$2 AND last_sync_at IS NOT NULL)
ON CONFLICT (op, fingerprint) DO UPDATE SET updated_at = now()
WHERE op_checkpoints.updated_at <= now() - ($3::bigint * interval '1 millisecond')
AND EXISTS (SELECT 1 FROM sources WHERE id=$2 AND last_sync_at > op_checkpoints.updated_at) RETURNING 1)
SELECT (SELECT completed_keys FROM prior) AS report, EXISTS (SELECT 1 FROM claim) AS claimed`,
inFlight ? [SYNC_GHOST_REPORT_OP, sourceId] : [SYNC_GHOST_REPORT_OP, sourceId, scanIntervalMs()]).catch(() => []);
if (inFlight) decide(sourceId, 'scan_in_flight');
else if (row?.claimed) startScan(engine, sourceId);
else decide(sourceId, 'rate_limited');
const report = typeof row?.report === 'string' ? JSON.parse(row.report) as SyncGhostPages[] : row?.report;
return report?.[0] ?? null;
}
/** Resolves when every background scan of `engine` (default: every engine) has settled. */
export async function settleSyncGhostScans(engine?: BrainEngine): Promise<void> {
const states = engine ? [scans.get(engine)].filter((state): state is EngineScans => !!state) : [...scans.values()];
await Promise.all(states.flatMap(state => [...state.inFlight.values()]));
}
function startScan(engine: BrainEngine, sourceId: string): void {
let state = scans.get(engine);
if (!state) {
const created: EngineScans = { inFlight: new Map(), controller: new AbortController(), unregister: () => {} };
created.unregister = engine.registerBeforeDisconnect(async () => {
created.controller.abort(new Error('engine disconnecting'));
await Promise.all(created.inFlight.values());
created.unregister();
if (scans.get(engine) === created) scans.delete(engine);
});
scans.set(engine, created);
state = created;
}
const owned = state;
decide(sourceId, 'scan_started');
const run = (async () => {
try {
const report = await scanReport(engine, sourceId, owned.controller.signal);
owned.controller.signal.throwIfAborted();
await engine.executeRaw('UPDATE op_checkpoints SET completed_keys=$3::text::jsonb, updated_at=now() WHERE op=$1 AND fingerprint=$2',
[SYNC_GHOST_REPORT_OP, sourceId, JSON.stringify(report ? [report] : [])]);
decide(sourceId, 'scan_done');
} catch (error) {
if (owned.controller.signal.aborted) decide(sourceId, 'scan_aborted');
else decide(sourceId, 'scan_failed', error);
} finally {
owned.inFlight.delete(sourceId);
}
})();
owned.inFlight.set(sourceId, run);
}
/** One full scan, held paths left out; null when nothing is to report or the scan could not tell. */
async function scanReport(engine: BrainEngine, sourceId: string, signal: AbortSignal): Promise<SyncGhostPages | null> {
const scan = await scanGhostSource(engine, sourceId, { candidateLimit: SYNC_GHOST_CHECK_LIMIT, signal });
if (scan.status !== 'known' || (!scan.ghosts.length && !scan.truncated)) return null;
const incarnation = scan.owner?.source_incarnation ?? '';
const held = new Set(scan.ghosts.length ? (await engine.executeRaw<{ path: string }>(`SELECT completed_keys->0->>'path' AS path FROM op_checkpoints WHERE op=$1 AND fingerprint=ANY($2::text[])`,
[GIT_HOLD_OP, scan.ghosts.map(ghost => gitHoldFingerprint(sourceId, incarnation, ghost.path))])).map(row => row.path) : []);
const ghosts = scan.ghosts.filter(ghost => !held.has(ghost.path));
if (!ghosts.length && !scan.truncated) return null;
return { count: ghosts.length, truncated: scan.truncated, samples: ghosts.slice(0, 5).map(ghost => ghost.slug), observed_at: new Date().toISOString(),
fix: { argv: ['gbrain', 'repair', 'ghost-pages', '--source', sourceId], consent: [], actor: 'agent', requires_exclusive: false, docs: 'docs/guides/repair.md#ghost-pages',
why: `Lists the live pages of ${sourceId} whose canonical file is missing and writes nothing. Sync never deletes them: restore a file and sync to keep its page, `
+ 'or apply the printed removal only after the user agrees.',
verify: { argv: ['gbrain', 'sources', 'status', sourceId, '--json'] } } };
}
registerBackgroundWorkDrainer({
name: 'sync-ghost-scans',
order: 45,
async drain(timeoutMs, mode): Promise<{ unfinished: number }> {
if (mode === 'disconnect') return { unfinished: 0 };
const pending = [...scans.values()].flatMap(state => [...state.inFlight.values()]);
if (!pending.length) return { unfinished: 0 };
await Promise.race([Promise.all(pending), new Promise<void>(resolve => { const timer = setTimeout(resolve, timeoutMs); timer.unref?.(); })]);
return { unfinished: [...scans.values()].reduce((sum, state) => sum + state.inFlight.size, 0) };
},
});