Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Upstream observation for remote-tracking sources (#5255/#5176, O-DX-8).
*
* Sync records, from the checkout's own Git state, the last time anything
* observed the upstream (a fetch, pull or push by any process: FETCH_HEAD and
* the upstream ref's reflog), the upstream commit it saw, and how many of its
* commits the source's synced commit lacks. doctor `sync_freshness` reads the
* three `sources.upstream_*` columns, so a remote doctor needs no subprocess.
* A missing or older-than-24 h observation is "upstream unknown", never fresh.
*/
import { execFileSync } from './spawn.ts';
import { execFileBounded } from './bounded-child-exec.ts';
import { statSync } from 'node:fs';
import type { BrainEngine } from './engine.ts';
import { ERROR_CATALOGUE } from './error-catalogue.ts';
import { parseSourceConfig, sourceConfigHasRemoteUrl } from './sources-load.ts';
import { gitChildEnv } from './git-env.ts';
export const UPSTREAM_OBSERVATION_MAX_AGE_HOURS = 24;
/** How a cycle's sync phase treated the requested upstream refresh (cycle sync `details.upstream_refresh`). */
export type UpstreamRefresh = 'pulled' | 'failed' | 'skipped_managed' | 'not_requested';
export interface UpstreamObservation { checkedAt: Date; commit: string; behind: number | null }
function git(root: string, args: string[]): string | null {
try {
return execFileSync('git', ['-C', root, ...args], { env: gitChildEnv(), encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
} catch {
return null;
}
}
/** GBRA-133 2b.3: `git()` without blocking the event loop; the observation runs after every sync, in residents too. */
async function gitAsync(root: string, args: string[]): Promise<string | null> {
const r = await execFileBounded('git', ['-C', root, ...args], { env: gitChildEnv(), timeout: 10_000 });
return r.error ? null : r.stdout.trim() || null;
}
function mtime(path: string | null): number {
if (!path) return 0;
try { return statSync(path).mtimeMs; } catch { return 0; }
}
/** Whether the checkout's branch tracks an upstream (a `git pull` would have something to refresh). */
export function tracksUpstream(root: string): boolean {
return git(root, ['rev-parse', '--verify', '-q', '@{upstream}']) !== null;
}
/** Reads the checkout's upstream state; null when it has no upstream or none was ever fetched or pushed. */
export async function observeUpstream(root: string, syncedCommit: string | null): Promise<UpstreamObservation | null> {
const commit = await gitAsync(root, ['rev-parse', '--verify', '-q', '@{upstream}^{commit}']);
const ref = commit && await gitAsync(root, ['rev-parse', '--symbolic-full-name', '@{upstream}']);
if (!commit || !ref) return null;
const checkedMs = Math.max(
mtime(await gitAsync(root, ['rev-parse', '--path-format=absolute', '--git-path', 'FETCH_HEAD'])),
mtime(await gitAsync(root, ['rev-parse', '--path-format=absolute', '--git-path', `logs/${ref}`])),
);
if (checkedMs === 0) return null;
const count = syncedCommit ? await gitAsync(root, ['rev-list', '--count', `${syncedCommit}..${commit}`]) : null;
return { checkedAt: new Date(checkedMs), commit, behind: count === null ? null : Number(count) };
}
/** Best-effort: never fails a sync. Compares the upstream with the source's synced commit as stored after the run. */
export async function recordUpstreamObservation(engine: BrainEngine, sourceId: string, repoPath?: string): Promise<void> {
try {
const [source] = await engine.executeRaw<{ local_path: string | null; last_commit: string | null }>(
'SELECT local_path,last_commit FROM sources WHERE id=$1', [sourceId]);
const root = repoPath ?? source?.local_path;
if (!source || !root) return;
const observed = await observeUpstream(root, source.last_commit);
if (!observed) return;
await engine.executeRaw('UPDATE sources SET upstream_checked_at=$2::timestamptz,upstream_commit=$3,upstream_behind=$4 WHERE id=$1',
[sourceId, observed.checkedAt.toISOString(), observed.commit, observed.behind]);
} catch {
// Pre-migration brain or unreadable checkout: freshness stays "upstream unknown".
}
}
/** The managed refresh: a drained, worktree-wide fast-forward of the checkout followed by the managed sync (F0). */
const managedRefreshFix = (sourceId: string) => `gbrain sources refresh ${sourceId}`;
export interface ManagedPullWarning { code: string; cause: string; fix: string; docs: string }
/** #5255: the cycle warn for a skipped pull, only when the checkout tracks an upstream a pull would have refreshed. */
export function managedPullWarning(sourceId: string, checkout: string): ManagedPullWarning | undefined {
if (!tracksUpstream(checkout)) return undefined;
return {
code: ERROR_CATALOGUE.managed_pull_skipped.code,
cause: 'Managed brains do not run git pull inside a cycle; this sync imported the checkout as it is, so new upstream commits are not in the brain.',
fix: managedRefreshFix(sourceId),
docs: ERROR_CATALOGUE.managed_pull_skipped.docs,
};
}
/**
* O-DX-8: doctor's "upstream checked" verdict, separate from "local projection
* current". A Git source (no connector `kind`) with a `remote_url` and no
* observation, or one older than 24 h, is upstream unknown; any source whose last observation saw upstream
* commits its synced commit lacks is behind. Null when neither applies.
*/
export function upstreamFreshness(
source: { id: string; local_path: string | null; config: unknown; upstream_checked_at: Date | null; upstream_behind: number | null },
display: string, now: number, managed: boolean,
): { state: 'unknown' | 'behind'; issue: string } | null {
const checkedMs = source.upstream_checked_at ? new Date(source.upstream_checked_at).getTime() : null;
const behind = source.upstream_behind ?? 0;
const ageHours = checkedMs === null ? null : Math.floor((now - checkedMs) / 3_600_000);
const gitRemote = sourceConfigHasRemoteUrl(source.config) && parseSourceConfig(source.config).kind == null;
const unknown = gitRemote && (ageHours === null || ageHours >= UPSTREAM_OBSERVATION_MAX_AGE_HOURS);
if (!unknown && behind <= 0) return null;
const fix = managed ? managedRefreshFix(source.id) : `gbrain sync --source ${source.id}`;
const fact = unknown
? `upstream unknown (${ageHours === null ? 'never checked' : `last checked ${ageHours}h ago`})`
: `upstream ${behind} commit(s) ahead of the synced commit`;
return {
state: unknown ? 'unknown' : 'behind',
issue: `Source ${display} ${fact}; local projection is not proof of freshness. Fix: ${fix} (${ERROR_CATALOGUE.managed_pull_skipped.docs})`,
};
}