Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-133 PR 2b.5: the oldest commit a source has not synced yet, and how long it has waited, for doctor
* `managed_sync_latency` (managed and classic sources) and `source-health.ts` lag. A source whose sync stalled has no
* new receipts, so a latency read from synced commits alone says nothing about it; this reads the commit that is
* still waiting.
*
* A source is behind when its checkout HEAD differs from `sources.last_commit` (HEAD only: an uncommitted edit is not
* a pending commit). The wait is dated, in order:
* 1. the reflog: the time of the entry that first moved HEAD away from `last_commit` (`<git dir>/logs/HEAD`, read as
* a file). That is when the commit landed in the checkout, not its committer time, so a pulled old commit does
* not inflate the wait;
* 2. the persisted `first_due_at` of the commit notifier (`sync_notifier_sources` while not idle, or a due freshness
* marker in `sync_wanted_markers`), current source incarnation only. It is the only clock for a caller that runs
* no git (a remote doctor) and for a checkout without a usable reflog;
* 3. otherwise unknown, with the reason: `no_reflog` (no reflog entry reaches `last_commit`, which is an ancestor of
* HEAD) or `history_rewritten` (`last_commit` is not an ancestor of HEAD, or not in the repository).
* Without git, a source the notifier never recorded as due reads `not_observed`, never current. Nothing is written.
*/
import { closeSync, existsSync, fstatSync, openSync, readSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from './engine.ts';
import { execFileBounded } from './bounded-child-exec.ts';
import { gitChildEnv } from './git-env.ts';
import { readCheckoutHead } from './checkout-head.ts';
import { enclosingGitMetadata } from './persistence/root-registry.ts';
import { missingTable } from './notifier/store.ts';
export type PendingState = 'current' | 'behind' | 'unknown' | 'not_observed' | 'never_synced';
export type PendingUnknownReason = 'no_reflog' | 'history_rewritten' | 'no_checkout';
export interface PendingCommit {
source_id: string;
state: PendingState;
/** The checkout HEAD (git), or the notifier's observed HEAD without git. */
head: string | null;
synced_commit: string | null;
/** When the oldest unsynced commit landed or was first due; null unless behind. */
since: string | null;
age_seconds: number | null;
evidence: 'reflog' | 'first_due_at' | null;
reason: PendingUnknownReason | null;
first_due_at: string | null;
}
export interface PendingSource { id: string; root: string | null; last_commit: string | null }
/** At most this many trailing bytes of logs/HEAD are read (about 5,000 entries). */
const REFLOG_TAIL_BYTES = 1 << 20;
const SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
const ENTRY = /^([0-9a-f]{40,64}) ([0-9a-f]{40,64}) .*? (\d+) [+-]\d{4}\t/;
function readTail(file: string): string | null {
let fd: number;
try { fd = openSync(file, 'r'); } catch { return null; }
try {
const size = fstatSync(fd).size;
const length = Math.min(size, REFLOG_TAIL_BYTES);
const buffer = Buffer.alloc(length);
readSync(fd, buffer, 0, length, size - length);
const text = buffer.toString('utf8');
return length < size ? text.slice(text.indexOf('\n') + 1) : text;
} catch { return null; } finally { closeSync(fd); }
}
/** Unix seconds of the reflog entry that first moved HEAD away from `synced` after its last arrival there, or null. */
export function reflogDepartureSeconds(gitDir: string, synced: string): number | null {
const text = readTail(join(gitDir, 'logs', 'HEAD'));
if (!text) return null;
const entries = text.split('\n').map(line => ENTRY.exec(line)).filter((m): m is RegExpExecArray => m !== null)
.map(m => ({ from: m[1]!, to: m[2]!, at: Number(m[3]) }));
for (let i = entries.length - 1; i >= 0; i--) {
if (entries[i]!.to === synced) return entries[i + 1]?.at ?? null;
}
return entries.find(e => e.from === synced)?.at ?? null;
}
async function isAncestor(root: string, ancestor: string): Promise<boolean> {
const r = await execFileBounded('git', ['-C', root, 'merge-base', '--is-ancestor', ancestor, 'HEAD'], { timeout: 10_000, env: gitChildEnv({ GIT_OPTIONAL_LOCKS: '0' }) });
return r.error === null;
}
export interface GitPendingEvidence { head: string; behind: boolean; departedAt: number | null; reason: PendingUnknownReason | null }
/** One checkout: HEAD, whether it moved past `synced`, and when it left it (reflog). Null when no checkout can be read. */
export async function readGitPendingEvidence(root: string, synced: string): Promise<GitPendingEvidence | null> {
const gitDir = enclosingGitMetadata(root);
if (!gitDir || !existsSync(root)) return null;
const checkout = await readCheckoutHead(root);
if (!checkout) return null;
if (checkout.head === synced) return { head: checkout.head, behind: false, departedAt: null, reason: null };
const departedAt = reflogDepartureSeconds(gitDir, synced);
if (departedAt !== null) return { head: checkout.head, behind: true, departedAt, reason: null };
const reason: PendingUnknownReason = SHA.test(synced) && await isAncestor(root, synced) ? 'no_reflog' : 'history_rewritten';
return { head: checkout.head, behind: true, departedAt: null, reason };
}
interface DueRow { source_id: string; first_due_at: unknown; observed_head: string | null }
export interface PersistedDue { firstDueAt: number | null; observedHead: string | null }
/** The notifier's persisted first_due_at per source (state not idle, or a due freshness marker), current incarnation only. */
export async function readFirstDue(engine: Pick<BrainEngine, 'executeRaw'>, sourceIds: string[]): Promise<Map<string, PersistedDue>> {
const out = new Map<string, PersistedDue>();
if (!sourceIds.length) return out;
let rows: DueRow[];
try {
rows = await engine.executeRaw<DueRow>(
`SELECT s.id AS source_id, n.observed_head,
LEAST(CASE WHEN n.state <> 'idle' THEN n.first_due_at END,
(SELECT min(m.first_due_at) FROM sync_wanted_markers m WHERE m.source_id = s.id AND m.intent = 'freshness'
AND m.source_incarnation IS NOT DISTINCT FROM s.incarnation::text
AND (m.wanted_head IS NULL OR m.wanted_head IS DISTINCT FROM s.last_commit))) AS first_due_at
FROM sources s LEFT JOIN sync_notifier_sources n ON n.source_id = s.id AND n.source_incarnation IS NOT DISTINCT FROM s.incarnation::text
WHERE s.id = ANY($1::text[])`, [sourceIds]);
} catch (error) {
if (missingTable(error)) return out;
throw error;
}
for (const row of rows) {
const raw = row.first_due_at;
const at = raw === null || raw === undefined ? NaN : (raw instanceof Date ? raw : new Date(String(raw))).getTime();
out.set(row.source_id, { firstDueAt: Number.isFinite(at) ? at : null, observedHead: row.observed_head });
}
return out;
}
/**
* The oldest unsynced commit of each source. `git: false` (a remote caller) reads only the database. With git, each
* source costs one `rev-parse HEAD`, a file read of its reflog and, only when no reflog entry reaches
* `last_commit`, one `merge-base --is-ancestor`.
*/
export async function readPendingCommits(engine: Pick<BrainEngine, 'executeRaw'>, sources: PendingSource[], opts: { git: boolean; nowMs?: number }): Promise<PendingCommit[]> {
const nowMs = opts.nowMs ?? Date.now();
const due = await readFirstDue(engine, sources.map(s => s.id));
const iso = (ms: number) => new Date(ms).toISOString();
return Promise.all(sources.map(async (source): Promise<PendingCommit> => {
const persisted = due.get(source.id) ?? { firstDueAt: null, observedHead: null };
const base = { source_id: source.id, synced_commit: source.last_commit, first_due_at: persisted.firstDueAt === null ? null : iso(persisted.firstDueAt),
head: null as string | null, since: null as string | null, age_seconds: null as number | null, evidence: null as PendingCommit['evidence'], reason: null as PendingUnknownReason | null };
const dated = (head: string | null, sinceMs: number, evidence: 'reflog' | 'first_due_at'): PendingCommit =>
({ ...base, state: 'behind', head, since: iso(sinceMs), age_seconds: Math.max(0, Math.round((nowMs - sinceMs) / 1000)), evidence });
if (!source.last_commit) return { ...base, state: 'never_synced' };
const git = opts.git && source.root ? await readGitPendingEvidence(source.root, source.last_commit).catch(() => null) : null;
if (git && !git.behind) return { ...base, state: 'current', head: git.head };
if (git && git.departedAt !== null) return dated(git.head, git.departedAt * 1000, 'reflog');
if (persisted.firstDueAt !== null) return dated(git?.head ?? persisted.observedHead, persisted.firstDueAt, 'first_due_at');
if (git) return { ...base, state: 'unknown', head: git.head, reason: git.reason };
return { ...base, state: 'not_observed', head: persisted.observedHead, reason: opts.git && source.root ? 'no_checkout' : null };
}));
}
export interface EmbedBacklog {
source_id: string;
/** disabled: a keyless brain (nothing will embed); behind: chunks wait for a vector; unknown: a waiting chunk has no pending-since stamp. */
state: 'current' | 'behind' | 'unknown' | 'disabled';
pending_chunks: number;
oldest_pending_since: string | null;
age_seconds: number | null;
}
/**
* The embedding backlog of each source: live chunks of the published body generation without a vector in the active
* embedding column (embed_skip pages excluded, as the doctor embeddings check counts them), aged from the oldest `content_chunks.embedding_pending_since`.
*/
export async function readEmbedBacklog(engine: BrainEngine, sourceIds: string[], opts: { nowMs?: number } = {}): Promise<Map<string, EmbedBacklog>> {
const out = new Map<string, EmbedBacklog>();
if (!sourceIds.length) return out;
const nowMs = opts.nowMs ?? Date.now();
const { embeddingsDisabled } = await import('./embedding-disabled.ts');
if (await embeddingsDisabled(engine)) {
for (const id of sourceIds) out.set(id, { source_id: id, state: 'disabled', pending_chunks: 0, oldest_pending_since: null, age_seconds: null });
return out;
}
const { quoteIdentifier, resolveActiveEmbeddingColumnFromEngine } = await import('./search/embedding-column.ts');
const { chunkGenerationFilter } = await import('./search/safe-chunks.ts');
const column = quoteIdentifier((await resolveActiveEmbeddingColumnFromEngine(engine, { fallbackToLegacy: true })).name);
const rows = await engine.executeRaw<{ source_id: string; pending: unknown; unaged: unknown; oldest: unknown }>(
`SELECT p.source_id, count(*)::int AS pending, count(*) FILTER (WHERE cc.embedding_pending_since IS NULL)::int AS unaged,
min(cc.embedding_pending_since) AS oldest
FROM content_chunks cc JOIN pages p ON p.id = cc.page_id
WHERE cc.${column} IS NULL AND p.deleted_at IS NULL AND p.source_id = ANY($1::text[]) AND ${chunkGenerationFilter('p', 'cc')}
AND NOT jsonb_exists(COALESCE(p.frontmatter, '{}'::jsonb), 'embed_skip')
GROUP BY p.source_id`, [sourceIds]);
const byId = new Map(rows.map(row => [row.source_id, row]));
for (const id of sourceIds) {
const row = byId.get(id);
const pending = Number(row?.pending ?? 0);
const oldestMs = row?.oldest === null || row?.oldest === undefined ? NaN : (row.oldest instanceof Date ? row.oldest : new Date(String(row.oldest))).getTime();
if (!pending) { out.set(id, { source_id: id, state: 'current', pending_chunks: 0, oldest_pending_since: null, age_seconds: null }); continue; }
const aged = Number(row?.unaged ?? 0) === 0 && Number.isFinite(oldestMs);
out.set(id, { source_id: id, state: aged ? 'behind' : 'unknown', pending_chunks: pending, oldest_pending_since: aged ? new Date(oldestMs).toISOString() : null,
age_seconds: aged ? Math.max(0, Math.round((nowMs - oldestMs) / 1000)) : null });
}
return out;
}
export interface RosterSource extends PendingSource { managed: boolean }
/**
* Every source whose commits sync: managed sources (bound worktree; the root is this host's binding, else the source
* path) and classic sources with a local path, not archived and not sync-disabled. `sourceIds` confines it in SQL.
*/
export async function loadPendingRoster(engine: Pick<BrainEngine, 'executeRaw'>, sourceIds?: string[]): Promise<RosterSource[]> {
const { existingHostIdFor } = await import('./persistence/identity.ts');
const { isSyncDisabledConfig } = await import('./sync-policy.ts');
const rows = await engine.executeRaw<{ id: string; last_commit: string | null; root: string | null; managed: unknown; config: unknown }>(
`SELECT s.id, s.last_commit, s.config, (b.source_id IS NOT NULL) AS managed, COALESCE(h.local_path, s.local_path) AS root
FROM sources s
LEFT JOIN persistence_source_bindings b ON b.source_id = s.id AND b.source_incarnation = s.incarnation
LEFT JOIN persistence_host_bindings h ON h.worktree_id = b.worktree_id AND h.host_id::text = $2
WHERE s.archived IS NOT TRUE AND (b.source_id IS NOT NULL OR s.local_path IS NOT NULL)
AND ($1::text[] IS NULL OR s.id = ANY($1::text[]))
ORDER BY s.id`, [sourceIds ?? null, existingHostIdFor(engine)]);
return rows.filter(row => !isSyncDisabledConfig(row.config))
.map(row => ({ id: row.id, last_commit: row.last_commit, root: row.root, managed: row.managed === true || row.managed === 't' }));
}