Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.41.13 (#1434) — sole_non_default tier (5.5) in resolveSourceId /
* resolveSourceWithTier.
*
* When NO brain_default config is set AND exactly one registered source has
* local_path set and isn't 'default', auto-route to it. Closes the bug
* class where `gbrain sync` without --source silently routed to source_id
* 'default' even though the user had a single Vault-mounted source.
*
* Tier ordering placement codex review forced:
* - AFTER brain_default (explicit user intent wins)
* - BEFORE seed_default (auto-route beats the empty terminal)
*
* Tests use a stub BrainEngine that only implements the three methods the
* resolver touches: executeRaw, getConfig, kind. Hermetic — no PGLite.
*/
import { describe, test, expect } from 'bun:test';
import {
resolveSourceId,
resolveSourceWithTier,
SOURCE_TIER_NAMES,
formatSoleNonDefaultNudge,
} from '../src/core/source-resolver.ts';
import { withEnv } from './helpers/with-env.ts';
type StubSource = { id: string; local_path: string | null; archived?: boolean; config?: Record<string, unknown> };
function makeStub(
sources: StubSource[],
globalDefault: string | null = null,
opts?: { defaultActivePages?: number; pagesProbeThrows?: boolean },
) {
return {
kind: 'pglite' as const,
async executeRaw<T>(sql: string, _params?: unknown[]): Promise<T[]> {
// Query shapes hit in the resolver:
// 1. tier 4 (local_path match): SELECT id, local_path FROM sources WHERE local_path IS NOT NULL
// 2. assertSourceExists: SELECT id FROM sources WHERE id = $1
// 3. tier 5.5 (sole_non_default): SELECT id FROM sources WHERE local_path IS NOT NULL AND id != 'default' AND archived = false
// 4. tier 5.5 emptiness guard (#3070): SELECT 1 ... FROM pages WHERE source_id = 'default' AND deleted_at IS NULL LIMIT 1
if (sql.includes('FROM pages')) {
if (opts?.pagesProbeThrows) throw new Error('relation "pages" probe failed (legacy schema)');
return (opts?.defaultActivePages ?? 0) > 0 ? ([{ one: 1 }] as unknown as T[]) : [];
}
if (sql.includes('archived = false')) {
return sources.filter(s => s.local_path !== null && s.id !== 'default' && s.archived !== true)
.map(s => ({ id: s.id, config: s.config ?? {} })) as unknown as T[];
}
if (sql.includes('local_path IS NOT NULL AND id != \'default\'')) {
return sources.filter(s => s.local_path !== null && s.id !== 'default')
.map(s => ({ id: s.id })) as unknown as T[];
}
if (
sql.includes('SELECT id, local_path FROM sources WHERE local_path IS NOT NULL') ||
sql.includes(', archived FROM sources WHERE local_path IS NOT NULL')
) {
return sources.filter(s => s.local_path !== null)
.map(s => ({ id: s.id, local_path: s.local_path, archived: s.archived === true })) as unknown as T[];
}
if (sql.includes('SELECT id FROM sources WHERE id =')) {
const id = (_params as string[])?.[0];
return sources.filter(s => s.id === id).map(s => ({ id: s.id })) as unknown as T[];
}
return [];
},
async getConfig(_key: string): Promise<string | null> {
return globalDefault;
},
} as unknown as Parameters<typeof resolveSourceId>[0];
}
describe('#1434 — sole_non_default tier', () => {
test('fires when exactly one non-default source is registered (no brain_default)', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
]);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('studiovault');
expect(result.tier).toBe('sole_non_default');
});
test('does NOT fire when 2+ non-default sources exist (ambiguous — user must pick)', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
{ id: 'second-vault', local_path: '/Users/india/other-vault' },
]);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('seed_default');
});
test('does NOT fire when 0 non-default sources exist (fresh install)', async () => {
const engine = makeStub([{ id: 'default', local_path: null }]);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('seed_default');
});
test('does NOT fire when sole non-default has NULL local_path (no on-disk shape)', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'remote-only', local_path: null }, // GitHub-only source
]);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('seed_default');
});
test('does NOT fire when brain_default is set (explicit user intent wins)', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
'default', // user explicitly set sources.default
);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('brain_default');
});
test('does NOT fire when explicit --source flag is passed (tier 1 wins)', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
]);
const result = await resolveSourceWithTier(engine, 'default', '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('flag');
});
test('does NOT fire when GBRAIN_SOURCE env is set (tier 2 wins)', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
]);
await withEnv({ GBRAIN_SOURCE: 'default' }, async () => {
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('env');
});
});
test('archived non-default source is ignored (does not count toward the 1)', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
{ id: 'old-vault', local_path: '/Users/india/archive', archived: true },
]);
const result = await resolveSourceWithTier(engine, null, '/tmp');
// archived 'old-vault' shouldn't count → still one non-default → fires
expect(result.source_id).toBe('studiovault');
expect(result.tier).toBe('sole_non_default');
});
test('resolveSourceId mirrors resolveSourceWithTier on the new tier', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
]);
const flat = await resolveSourceId(engine, null, '/tmp');
const tagged = await resolveSourceWithTier(engine, null, '/tmp');
expect(flat).toBe(tagged.source_id);
});
test('detail string explains the routing', async () => {
const engine = makeStub([
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
]);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.detail).toContain('only non-default');
});
// #3070 — the emptiness guard: the tier's charter is rescuing brains whose
// 'default' holds 0 pages. An ESTABLISHED default corpus must not have its
// bare writes hijacked into the sole side-source.
test("#3070: does NOT fire when 'default' holds an established corpus", async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
null,
{ defaultActivePages: 1045 },
);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('seed_default');
expect(await resolveSourceId(engine, null, '/tmp')).toBe('default');
});
test('#3070: still fires when default is empty (the #1434 charter preserved)', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
null,
{ defaultActivePages: 0 },
);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('studiovault');
expect(result.tier).toBe('sole_non_default');
});
// The #3070 flip must not be silent: one stray page in 'default' quietly
// reroutes every bare command away from the sole side-source. A one-line
// stderr warning names both sides so the misroute is diagnosable.
test('#3070: the flip prints a one-line stderr warning naming both sources', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
null,
{ defaultActivePages: 1 },
);
const originalError = console.error;
const errLines: string[] = [];
console.error = (...args: unknown[]) => { errLines.push(args.join(' ')); };
try {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: undefined }, async () => {
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
expect(result.tier).toBe('seed_default');
});
} finally {
console.error = originalError;
}
expect(errLines.length).toBe(1);
const line = errLines[0];
expect(line).toContain("'studiovault'");
expect(line).toContain("'default'");
expect(line).toContain('non-empty');
});
test('#3070 (GST-2732): no flip warning when the side source is federated, since default search already reads it', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'company', local_path: '/tmp/company', config: { federated: true } },
],
null,
{ defaultActivePages: 1 },
);
const originalError = console.error;
const errLines: string[] = [];
console.error = (...args: unknown[]) => { errLines.push(args.join(' ')); };
try {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: undefined }, async () => {
expect((await resolveSourceWithTier(engine, null, '/tmp')).source_id).toBe('default');
});
} finally {
console.error = originalError;
}
expect(errLines.length).toBe(0);
});
test('#3070: the flip warning is suppressed via GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE=1', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
null,
{ defaultActivePages: 1 },
);
const originalError = console.error;
const errLines: string[] = [];
console.error = (...args: unknown[]) => { errLines.push(args.join(' ')); };
try {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: '1' }, async () => {
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('default');
});
} finally {
console.error = originalError;
}
expect(errLines.length).toBe(0);
});
test('#3070: no flip warning when default is empty (tier fires normally)', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
null,
{ defaultActivePages: 0 },
);
const originalError = console.error;
const errLines: string[] = [];
console.error = (...args: unknown[]) => { errLines.push(args.join(' ')); };
try {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: undefined }, async () => {
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('studiovault');
});
} finally {
console.error = originalError;
}
expect(errLines.length).toBe(0);
});
test('#3070: pages-probe failure keeps the pre-guard routing (legacy brain)', async () => {
const engine = makeStub(
[
{ id: 'default', local_path: null },
{ id: 'studiovault', local_path: '/Users/india/vault' },
],
null,
{ pagesProbeThrows: true },
);
const result = await resolveSourceWithTier(engine, null, '/tmp');
expect(result.source_id).toBe('studiovault');
expect(result.tier).toBe('sole_non_default');
});
});
describe('SOURCE_TIER_NAMES includes sole_non_default at index 5', () => {
test('positioned between brain_default and seed_default', () => {
const idx = SOURCE_TIER_NAMES.indexOf('sole_non_default');
expect(idx).toBeGreaterThan(SOURCE_TIER_NAMES.indexOf('brain_default'));
expect(idx).toBeLessThan(SOURCE_TIER_NAMES.indexOf('seed_default'));
});
});
describe('formatSoleNonDefaultNudge', () => {
test('returns canonical nudge string in default env', async () => {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: undefined }, async () => {
expect(formatSoleNonDefaultNudge('studiovault')).toBe(
"[gbrain] routing to source 'studiovault' (sole non-default source registered; pass --source to override).",
);
});
});
test('returns null when GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE=1 suppresses', async () => {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: '1' }, async () => {
expect(formatSoleNonDefaultNudge('studiovault')).toBeNull();
});
});
test('any value other than literal "1" does NOT suppress', async () => {
await withEnv({ GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: 'true' }, async () => {
expect(formatSoleNonDefaultNudge('studiovault')).not.toBeNull();
});
});
});