Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain sources git-reconcile [<source-id>...] [--dry-run] [--wait <seconds>] [--json]`: bring every source checkout on
* this host level with its upstream, idempotently, so any thread, agent, cron or hook can call it as often and as
* concurrently as it likes. A level checkout costs one fetch and reports in_sync. A managed checkout (a persistence
* worktree) is reconciled by `gbrain sources refresh`, which publishes its local commits (secret gate, rewrite check,
* Git durability) and fast-forwards; a refresh already running is waited for, then the checkout is checked again. Any
* other checkout goes through reconcileCheckout (src/core/git/reconcile.ts). Merges are in memory; nothing rebases or
* force-pushes. A brain with no Git checkout reports no_repo and exits 0.
*
* Exit: 0 when every checkout is level (or has nothing to reconcile), 1 when one needs the user (a conflict, a
* secret, a rewritten upstream, durability off), 4 when one failed in a way a retry can fix (network, a busy lock).
*/
import type { BrainEngine } from '../core/engine.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { reconcileCheckout, fetchLevel, gitReader, withReconcileLock, type CheckoutReconcileStatus } from '../core/git/reconcile.ts';
import { CRASH_SIGNALS } from '../core/git/git-run.ts';
import { isTruthy } from '../core/connectors/config-keys.ts';
import { existsSync, realpathSync } from 'node:fs';
import { classifyGitCheckout } from '../core/git-checkout.ts';
import { gitTopLevel } from '../core/persistence/git-gap.ts';
import { isOwnedClone } from '../core/url-clone.ts';
import { isSyncDisabledConfig } from '../core/sync-policy.ts';
import { OperationError } from '../core/ops/contract.ts';
import { classifyItemFailure, type ClassifiedItemFailure } from '../core/item-failure.ts';
import { existingHostIdFor } from '../core/persistence/identity.ts';
import { getWorktreeBinding, managedPersistenceEnabled } from '../core/persistence/ownership.ts';
import { REFRESH_PUBLISH_DIVERGED_KEY, publishOptedOut, refreshWorktree } from '../core/persistence/worktree-refresh.ts';
import { listSources } from '../core/sources-ops.ts';
const USAGE = 'Usage: gbrain sources git-reconcile [<source-id>...] [--dry-run] [--wait <seconds>] [--json]';
const RETRYABLE = new Set(['fetch_failed', 'push_unconfirmed', 'commit_lock_busy', 'refresh_in_progress', 'refresh_lock_timeout', 'refresh_drain_timeout', 'git_unavailable', 'git_command_stopped']);
export type SourceReconcileStatus = CheckoutReconcileStatus | 'needs_user' | 'failed';
export interface SourceReconcile {
sources: string[]; root: string; managed: boolean; status: SourceReconcileStatus; ahead: number; behind: number;
sha?: string; integrated?: number; reason?: string; refresh_id?: string | null;
/** GST-2250: the sources with `sources.auto_reconcile.source.<id>` false, whose local commits are never published here. */
publish_off?: string[];
error?: { code: string; message: string; suggestion?: string; fix?: unknown };
}
export interface ReconcileOptions { sourceIds?: string[]; dryRun?: boolean; waitMs?: number; sleep?: (ms: number) => Promise<void>; childTimeoutMs?: number }
/** A git command stopped by its output limit or by a git crash stops the same way on a retry, so it goes to the user like the advice says. */
function stoppedForGood(error: OperationError): boolean {
if (error.code !== 'git_command_stopped') return false;
let stop: { reason?: string; signal?: string } = {};
try { stop = JSON.parse(error.detail ?? '{}'); } catch { /* no detail: a retry may finish */ }
const reason = error.reason ?? stop.reason;
return reason === 'output_limit' || (reason === 'signal' && CRASH_SIGNALS.has(stop.signal ?? ''));
}
const refreshBusy = (error: unknown) => error instanceof OperationError && error.code === 'refresh_in_progress';
function groupRefusal(error: unknown, failure: ClassifiedItemFailure): Pick<SourceReconcile, 'status' | 'error'> {
if (!(error instanceof OperationError)) return { status: failure.class === 'transient' ? 'failed' : 'needs_user', error: { code: failure.code, message: failure.message } };
return { status: RETRYABLE.has(error.code) && !stoppedForGood(error) ? 'failed' : 'needs_user',
error: { code: error.code, message: error.message, ...(error.suggestion ? { suggestion: error.suggestion } : {}), ...(error.fix ? { fix: error.fix } : {}) } };
}
async function reconcileManaged(engine: BrainEngine, sourceId: string, root: string, publish: boolean, opts: ReconcileOptions, unpublishedReason: string): Promise<Omit<SourceReconcile, 'sources' | 'root' | 'managed'>> {
const level = await fetchLevel(root, gitReader(root));
if (!level) return { status: 'no_upstream', ahead: 0, behind: 0 };
if (!level.ahead && !level.behind) return { status: 'in_sync', ahead: 0, behind: 0, sha: level.target };
if (level.ahead && !publish) return { status: 'unpublished', ahead: level.ahead, behind: level.behind, sha: level.target, reason: unpublishedReason };
if (opts.dryRun) return { status: level.ahead ? 'published' : 'fast_forwarded', ahead: level.ahead, behind: level.behind, sha: level.target, reason: 'dry run: nothing changed' };
const sleep = opts.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
const deadline = Date.now() + (opts.waitMs ?? 300_000);
for (;;) {
try {
const done = await refreshWorktree(engine, sourceId);
return { status: done.published ? 'published' : 'fast_forwarded', ahead: level.ahead, behind: level.behind, sha: done.target_head ?? undefined, refresh_id: done.refresh_id,
...(done.published ? { integrated: done.published.integrated } : {}) };
} catch (error) {
if (!refreshBusy(error) || Date.now() >= deadline) throw error;
await sleep(2000);
const again = await fetchLevel(root, gitReader(root));
if (again && !again.ahead && !again.behind) return { status: 'in_sync', ahead: 0, behind: 0, sha: again.target };
}
}
}
export async function reconcileSources(engine: BrainEngine, opts: ReconcileOptions = {}): Promise<SourceReconcile[]> {
const explicit = !!opts.sourceIds?.length;
const all = (await listSources(engine)).filter(s => s.local_path);
const listed = all.filter(s => !explicit || opts.sourceIds!.includes(s.id));
const unknown = (opts.sourceIds ?? []).filter(id => !listed.some(s => s.id === id));
if (unknown.length) throw new OperationError('unknown_source', `No source with a local checkout named ${unknown.join(', ')}.`, 'gbrain sources list shows each source and its local path.');
const configs = new Map((await engine.executeRaw<{ id: string; config: unknown }>('SELECT id, config FROM sources')).map(row => [row.id, row.config]));
const managed = await managedPersistenceEnabled(engine);
const configured = (await engine.getConfig(REFRESH_PUBLISH_DIVERGED_KEY))?.trim();
const publishSetting = configured ? isTruthy(configured) : null;
const groups = new Map<string, { sources: string[]; root: string; top: string; managed: boolean; cloned: boolean }>();
const sharers = new Map<string, string[]>();
for (const source of all) {
const binding = managed ? await getWorktreeBinding(engine, source.id, existingHostIdFor(engine)) : null;
if (managed && !binding) continue;
const root = binding?.local_path ?? source.local_path!;
if (!existsSync(root) || classifyGitCheckout(root) === 'not_git') continue;
const top = gitTopLevel(root) ?? realpathSync(root);
sharers.set(top, [...(sharers.get(top) ?? []), source.id]);
if (!listed.includes(source) || (!explicit && isSyncDisabledConfig(configs.get(source.id)))) continue;
const key = binding ? `worktree:${binding.worktree_id}` : `path:${root}`;
const cloned = isOwnedClone({ id: source.id, local_path: source.local_path, config: configs.get(source.id) }) && top === realpathSync(root);
const group = groups.get(key) ?? { sources: [], root, top, managed: !!binding, cloned };
group.sources.push(source.id);
group.cloned &&= cloned;
groups.set(key, group);
}
if (!groups.size) return [{ sources: [], root: '', managed: false, status: 'no_repo', ahead: 0, behind: 0 }];
const out: SourceReconcile[] = [];
for (const group of groups.values()) {
const { cloned, top, ...entry } = group;
let off: { publish_off?: string[] } = {};
try {
const optedOut = await publishOptedOut(engine, sharers.get(top) ?? group.sources);
const publish = optedOut.length ? false : group.managed ? publishSetting !== false : publishSetting ?? cloned;
if (optedOut.length) off = { publish_off: optedOut };
const offReason = `automatic publishing is off for ${optedOut.join(', ')} (sources.auto_reconcile.source.<id> false)`;
const result = group.managed
? await withReconcileLock(group.root, opts.waitMs ?? 300_000, () => reconcileManaged(engine, group.sources[0], group.root, publish, opts,
optedOut.length ? offReason : `automatic publishing is off (${REFRESH_PUBLISH_DIVERGED_KEY} false)`))
: await reconcileCheckout(group.root, { dryRun: opts.dryRun, publish, ...(opts.waitMs !== undefined ? { waitMs: opts.waitMs } : {}), ...(opts.childTimeoutMs ? { childTimeoutMs: opts.childTimeoutMs } : {}),
...(optedOut.length ? { unpublishedReason: offReason } : publishSetting === null && !cloned ? { unpublishedReason: `gbrain sources add --url did not clone this checkout for the source, or the source folder is not the repository root; publish it with gbrain git commit-push --push-only --scan-secrets --path ${group.root}, or set ${REFRESH_PUBLISH_DIVERGED_KEY} true to publish such checkouts automatically` } : {}) });
out.push({ ...entry, ...result, ...off });
} catch (error) {
const failure = classifyItemFailure(error);
if (!(error instanceof OperationError) && failure.scope === 'run') throw error;
out.push({ ...entry, ahead: 0, behind: 0, ...off, ...groupRefusal(error, failure) });
}
}
return out;
}
export function parseReconcileArgs(args: string[]): { json: boolean; options: ReconcileOptions } {
const sourceIds: string[] = [];
let waitMs: number | undefined;
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '--json' || arg === '--dry-run') continue;
if (arg === '--wait') {
const value = Number(args[++i]);
if (!Number.isFinite(value) || value < 0) throw new OperationError('invalid_params', `--wait needs a non-negative number of seconds; got ${args[i] ?? 'nothing'}.`, USAGE);
waitMs = Math.round(value * 1000);
continue;
}
if (arg.startsWith('-')) throw new OperationError('invalid_params', `Unknown sources git-reconcile flag: ${arg}.`, USAGE);
sourceIds.push(arg);
}
return { json: args.includes('--json'), options: { sourceIds, dryRun: args.includes('--dry-run'), ...(waitMs !== undefined ? { waitMs } : {}) } };
}
function line(r: SourceReconcile): string {
const who = r.sources.length ? `${r.sources.join(', ')} (${r.root})` : 'this brain';
const counts = r.ahead || r.behind ? ` [${r.ahead} ahead, ${r.behind} behind]` : '';
switch (r.status) {
case 'in_sync': return `${who}: in sync with its upstream`;
case 'published': return `${who}: published local commits${r.integrated ? ` merged with ${r.integrated} upstream commit(s)` : ''}${counts}${r.reason ? ` (${r.reason})` : ''}`;
case 'fast_forwarded': return `${who}: brought up to its upstream${counts}${r.reason ? ` (${r.reason})` : ''}`;
case 'lagging': return `${who}: published, but the checkout did not advance: ${r.reason ?? 'local edits block it'}`;
case 'unpublished': return `${who}: ${r.ahead} local commit(s) left unpublished: ${r.reason}${counts}`;
case 'no_repo': return `${who}: no Git checkout, nothing to reconcile`;
case 'no_upstream': return `${who}: the branch has no upstream, nothing to reconcile`;
default: return `${who}: ${r.status === 'needs_user' ? 'needs the user' : 'failed, retry'}: ${r.error?.code}: ${r.error?.message}${r.error?.suggestion ? ` Next: ${r.error.suggestion}` : ''}`;
}
}
export async function runSourcesReconcile(engine: BrainEngine, args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) { console.log(USAGE); return; }
const { json, options } = parseReconcileArgs(args);
const results = await reconcileSources(engine, options);
const exit = results.some(r => r.status === 'needs_user') ? 1 : results.some(r => r.status === 'failed') ? 4 : 0;
if (json) console.log(JSON.stringify({ results, exit }, null, 2));
else for (const r of results) console.log(`${line(r)}${r.publish_off && r.status !== 'unpublished' ? ` (automatic publishing is off for ${r.publish_off.join(', ')})` : ''}`);
if (exit) setCliExitVerdict(exit);
}