Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #4091-class root-cause fix — tier-4 registered-source realpath resolution
* must overlap I/O across sources, not serialize behind each other.
*
* Discovered while investigating why `gbrain takes-list` (and any other
* CLI command reaching tier 4 of source resolution with no --source/env/
* dotfile match) took ~40s on a brain with 9 registered sources whose
* local_path all lived under a directory macOS's on-access security scan
* makes slow to `realpath()`: each source added its own multi-second delay
* because the original code called the SYNCHRONOUS `realpathSync` in a
* plain `for` loop — `Promise.all`-wrapping a sync call does not
* parallelize it, since a sync call blocks the whole event loop for its
* full duration regardless of how many promises surround it. The fix
* switches to `fs.promises.realpath` (`realpathOrResolveAsync`) and
* resolves every source's path via a single `Promise.all`, so tier 4's
* cost is bounded by the SLOWEST single source, not their sum.
*
* This test can't reproduce the real macOS-scan slowness portably/in CI,
* so it spies on `realpathOrResolveAsync` to prove concurrency directly:
* every mocked call increments an in-flight counter and hangs on its own
* releaser (never auto-resolving), so the test can assert ALL N+1 calls
* (cwd + every registered source) were issued before ANY of them settled.
* This is deterministic — no wall-clock/timing assertion, so it can't flake
* under CI load, timer throttling, or coverage instrumentation (the wall
* clock version of this test hit exactly that risk in review).
*/
import { describe, test, expect, spyOn } from 'bun:test';
import { resolveSourceId, resolveSourceWithTier } from '../src/core/source-resolver.ts';
import * as pathConfine from '../src/core/path-confine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
function makeStub(paths: Array<{ id: string; local_path: string }>): BrainEngine {
return {
kind: 'pglite',
executeRaw: async <T>(sql: string, params?: unknown[]): Promise<T[]> => {
// Matches both query shapes of listRegisteredLocalPathSources (#3880):
// the archived-column query and its pre-v34 column-less fallback. Rows
// carry no `archived` key here → treated as active.
if (sql.includes('FROM sources WHERE local_path IS NOT NULL')) {
return paths as unknown as T[];
}
// #4368-added archival gate: resolveSourceId/resolveSourceWithTier call
// assertSourceExists on the tier-4 match before returning it. This test
// only exercises resolution ordering/concurrency, not archival — every
// id the resolver checks is treated as active.
if (sql.includes('SELECT id FROM sources WHERE id = $1 AND archived = false')) {
return [{ id: params?.[0] }] as unknown as T[];
}
return [] as unknown as T[];
},
getConfig: async () => null,
} as unknown as BrainEngine;
}
describe('resolveSourceWithTier — tier 4 realpath resolution is parallel, not serial (#4091-class)', () => {
test('all N+1 realpath calls (cwd + every registered source) are in flight together before any settles', async () => {
const N = 6;
const paths = Array.from({ length: N }, (_, i) => ({ id: `src${i}`, local_path: `/slow/path${i}` }));
const engine = makeStub(paths);
let inFlight = 0;
let maxInFlight = 0;
const releasers: Array<() => void> = [];
const spy = spyOn(pathConfine, 'realpathOrResolveAsync').mockImplementation((p: string) => {
inFlight++;
maxInFlight = Math.max(maxInFlight, inFlight);
return new Promise<string>((resolvePromise) => {
releasers.push(() => {
inFlight--;
resolvePromise(p);
});
});
});
try {
const resultPromise = resolveSourceWithTier(engine, null, '/slow/path3/nested');
// Let the microtask queue drain so every Promise.all-issued call has
// started (but none have been released yet — they all hang on their
// own releaser above). If the tier-4 loop were serial, only the FIRST
// call would be in flight at this point; the rest would not even have
// been issued yet, since each `await` blocks starting the next one.
await Promise.resolve();
await Promise.resolve();
await Promise.resolve();
// cwd's own realpath + one per registered source, all outstanding at once.
expect(maxInFlight).toBe(N + 1);
expect(inFlight).toBe(N + 1); // none settled yet either
// Release everything and let resolution complete.
for (const release of releasers) release();
const result = await resultPromise;
expect(result.source_id).toBe('src3');
expect(result.tier).toBe('local_path');
} finally {
spy.mockRestore();
}
});
test('control: same scenario without the spy still resolves correctly (regression guard)', async () => {
const paths = [
{ id: 'gstack', local_path: '/work/gstack' },
{ id: 'other', local_path: '/work/other' },
];
const engine = makeStub(paths);
const result = await resolveSourceWithTier(engine, null, '/work/gstack/src');
expect(result.source_id).toBe('gstack');
expect(result.tier).toBe('local_path');
});
test('resolveSourceId (the other tier-4 caller) shares the same fix — parity check', async () => {
// resolveSourceWithTier is covered directly above; resolveSourceId shares
// resolveRegisteredPathMatch under the hood, so this pins that the
// refactor didn't let the two entry points drift.
const paths = [
{ id: 'gstack', local_path: '/work/gstack' },
{ id: 'other', local_path: '/work/other' },
];
const engine = makeStub(paths);
const id = await resolveSourceId(engine, null, '/work/gstack/src');
expect(id).toBe('gstack');
});
test('a genuine tie (two sources sharing the identical resolved path) keeps the pre-refactor first-row-wins order', async () => {
// The registered-sources query has no ORDER BY, so a real tie (both
// candidates resolve to the SAME length AND the same matched prefix) is
// broken by array/database row order — unchanged by the Promise.all
// refactor (Promise.all preserves input order). Two DIFFERENT local_path
// strings of equal length are not a tie unless both are prefixes of cwd;
// the simplest genuine tie is a duplicate registration (same path twice),
// which is a real edge case (an operator registering a source twice, or
// two ids sharing a symlinked vault).
const paths = [
{ id: 'first', local_path: '/work/same' },
{ id: 'second', local_path: '/work/same' },
];
const engine = makeStub(paths);
const result = await resolveSourceWithTier(engine, null, '/work/same/nested');
expect(result.source_id).toBe('first');
});
});