Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.2 KB
Raw Blame
/**
 * #5255 + short half of #5176 (O-CEO-12, O-DX-8, O-ENG-15): a managed cycle
 * asked to pull syncs local HEAD instead of failing with
 * writer_coordinator_required, reports `upstream_refresh: "skipped_managed"`
 * with the safe refresh sequence, and doctor sync_freshness reports upstream
 * freshness separately from the local projection. An explicit sync without
 * --no-pull keeps refusing.
 */
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runCycle } from '../src/core/cycle.ts';
import { performSync } from '../src/commands/sync.ts';
import { checkSyncFreshness } from '../src/commands/doctor.ts';
import { runMirrorMode } from '../src/commands/sources-mirror.ts';
import { operations } from '../src/core/operations.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
import { flagRejection, gbrainInvocations, liveCliVerbs } from './helpers/cli-command-surface.ts';

const backends = testBackends();
const engines: BrainEngine[] = [];
let closePostgres: (() => Promise<void>) | undefined;
const dirs: string[] = [];

beforeAll(async () => {
  if (backends.includes('pglite')) {
    const engine = new PGLiteEngine();
    await engine.connect({ database_url: '' }); await engine.initSchema(); engines.push(engine);
  }
  if (backends.includes('postgres')) {
    const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
    engines.push(pg.engine); closePostgres = pg.close;
  }
}, 120_000);
afterAll(async () => {
  for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
  await closePostgres?.();
  for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
});

const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, '-c', 'user.name=Example', '-c', '[email protected]', ...args],
  { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const page = (title: string, body: string) => `---\ntitle: ${title}\ntype: note\n---\n${body}\n`;
function commit(root: string, path: string, content: string) {
  mkdirSync(join(root, path, '..'), { recursive: true });
  writeFileSync(join(root, path), content);
  git(root, 'add', '.'); git(root, 'commit', '-qm', `add ${path}`);
}
const logger = { info() {}, warn() {}, error() {} };
/** O-DX-2: every gbrain command a fix prints resolves and parses with the real CLI's flags. */
function expectRunnableFix(fix: string) {
  const invocations = gbrainInvocations(fix);
  expect(invocations.length).toBeGreaterThan(0);
  for (const inv of invocations) {
    expect(liveCliVerbs().has(inv.verb)).toBe(true);
    expect(flagRejection(inv)).toBeNull();
  }
}

/** A managed brain whose source checkout tracks a bare remote another clone pushes to. */
async function managedRemoteSource(engine: BrainEngine, fn: (s: { sourceId: string; root: string; upstream: string; home: string }) => Promise<void>) {
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-managed-pull-')); dirs.push(dir);
  const remote = join(dir, 'origin.git'), upstream = join(dir, 'upstream'), root = join(dir, 'brain');
  execFileSync('git', ['init', '-q', '--bare', '-b', 'main', remote]);
  execFileSync('git', ['clone', '-q', remote, upstream], { stdio: 'ignore' });
  git(upstream, 'checkout', '-q', '-b', 'main');
  commit(upstream, 'notes/first.md', page('First', 'The first synced observation.'));
  git(upstream, 'push', '-q', 'origin', 'main');
  execFileSync('git', ['clone', '-q', remote, root], { stdio: 'ignore' });
  const sourceId = `remote-${Math.random().toString(36).slice(2, 8)}`;
  await withEnv({ GBRAIN_HOME: join(dir, 'home') }, async () => {
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,$3::text::jsonb)',
      [sourceId, root, JSON.stringify({ remote_url: remote })]);
    await claimWorktree(engine, sourceId, root);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    try { await fn({ sourceId, root, upstream, home: join(dir, 'home') }); }
    finally {
      await disposePersistenceConsumer(engine);
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
      await engine.executeRaw('DELETE FROM sources WHERE id=$1', [sourceId]);
    }
  });
}

for (const backend of backends) {
  const engine = () => engines[backends.indexOf(backend)];

  test(`${backend}: runCycle({pull:true}) on a managed brain syncs local HEAD and reports skipped_managed (#5255)`, async () => {
    await managedRemoteSource(engine(), async ({ sourceId, root }) => {
      const report = await runCycle(engine(), { brainDir: root, sourceId, phases: ['sync'], pull: true });
      const sync = report.phases.find(p => p.phase === 'sync')!;
      expect(JSON.stringify(sync)).not.toContain('writer_coordinator_required');
      expect(sync.status).toBe('warn');
      expect(sync.details).toMatchObject({ source_id: sourceId, upstream_refresh: 'skipped_managed', added: 1,
        warning: { code: 'managed_pull_skipped', docs: 'docs/guides/write-refusals.md#managed_pull_skipped' } });
      const warning = (sync.details as { warning: { fix: string; cause: string } }).warning;
      expect(warning.cause.length).toBeGreaterThan(0);
      // F0: the one sanctioned managed refresh (drained, worktree-wide ff-only) replaces the manual pull sequence.
      expect(warning.fix).toBe(`gbrain sources refresh ${sourceId}`);
      expectRunnableFix(warning.fix);
      expect((await engine().getPage('notes/first', { sourceId }))?.compiled_truth).toContain('The first synced observation.');
    });
  }, 120_000);

  test(`${backend}: an explicit managed sync without --no-pull keeps refusing (O-ENG-15)`, async () => {
    await managedRemoteSource(engine(), async ({ sourceId, root }) => {
      const refusal = await performSync(engine(), { repoPath: root, sourceId, noPull: false, noEmbed: true }).then(() => null, (e: unknown) => e);
      expect(refusal).toMatchObject({ code: 'writer_coordinator_required',
        fix: { argv: ['gbrain', 'sync', '--no-pull', '--source', sourceId], actor: 'agent' } });
      expect((refusal as { suggestion: string }).suggestion).toContain(`gbrain sync --no-pull --source ${sourceId}`);
      expect((refusal as { suggestion: string }).suggestion).toContain(`gbrain sources refresh ${sourceId}`);
      expect((refusal as { suggestion: string }).suggestion).toContain(`fast-forward and sync the checkout with gbrain sources refresh ${sourceId}`);
    });
  }, 120_000);

  test(`${backend}: mirror ff-only pull then no-pull sync makes the upstream commit recallable, and doctor splits upstream from local freshness`, async () => {
    await managedRemoteSource(engine(), async ({ sourceId, root, upstream }) => {
      await runMirrorMode(engine(), [sourceId], true);
      await performSync(engine(), { repoPath: root, sourceId, noPull: true, noEmbed: true });
      commit(upstream, 'notes/second.md', page('Second', 'A zebracorn observation pushed upstream.'));
      git(upstream, 'push', '-q', 'origin', 'main');

      git(root, 'pull', '-q', '--ff-only');
      await performSync(engine(), { repoPath: root, sourceId, noPull: true, noEmbed: true });
      const query = operations.find(op => op.name === 'query')!;
      const ctx = { engine: engine(), config: { engine: engine().kind } as never, logger, dryRun: false, remote: false, sourceId };
      expect(JSON.stringify(await query.handler(ctx as never, { query: 'zebracorn', limit: 5, expand: false }))).toContain('notes/second');
      const [observed] = await engine().executeRaw<{ upstream_commit: string; upstream_behind: number; upstream_checked_at: Date }>(
        'SELECT upstream_commit,upstream_behind,upstream_checked_at FROM sources WHERE id=$1', [sourceId]);
      expect(observed.upstream_commit).toBe(git(upstream, 'rev-parse', 'HEAD'));
      expect(observed.upstream_behind).toBe(0);
      const fresh = await checkSyncFreshness(engine(), { localOnly: true });
      expect(fresh.status).toBe('ok');
      expect(fresh.details).not.toHaveProperty('upstream_unknown_count');

      // Upstream advances, the checkout fetches but does not merge: the local
      // projection is current (HEAD == last_commit) but upstream is behind.
      commit(upstream, 'notes/third.md', page('Third', 'Not merged yet.'));
      git(upstream, 'push', '-q', 'origin', 'main');
      git(root, 'fetch', '-q');
      await performSync(engine(), { repoPath: root, sourceId, noPull: true, noEmbed: true });
      const behind = await checkSyncFreshness(engine(), { localOnly: true });
      expect(behind.status).toBe('warn');
      expect(behind.message).toContain(`'${sourceId}' upstream 1 commit(s) ahead of the synced commit`);
      expect(behind.message).toContain(`Fix: gbrain sources refresh ${sourceId} (`);
      expectRunnableFix(behind.message.slice(behind.message.indexOf('Fix: ') + 5));
      expect(behind.details).toMatchObject({ unchanged_count: 1, upstream_behind_count: 1 });

      // Neither fetched nor pulled for over 24 h: upstream unknown, never fresh.
      await engine().executeRaw("UPDATE sources SET upstream_behind=0 WHERE id=$1", [sourceId]);
      const stale = await checkSyncFreshness(engine(), { nowMs: Date.now() + 25 * 3_600_000 });
      expect(stale.status).not.toBe('ok');
      expect(stale.message).toContain(`'${sourceId}' upstream unknown (last checked 25h ago)`);
      expect(stale.details).toMatchObject({ upstream_unknown_count: 1 });
    });
  }, 180_000);

  test(`${backend}: a remote-tracking source with no upstream observation is upstream unknown, not fresh`, async () => {
    const sourceId = `never-${backend}`;
    await engine().executeRaw('INSERT INTO sources(id,name,local_path,config,last_sync_at) VALUES($1,$1,$2,$3::text::jsonb,now())',
      [sourceId, '/example/never-observed', JSON.stringify({ remote_url: 'https://example.invalid/repo.git' })]);
    // An API connector source is not a Git remote: it never reads as upstream unknown.
    await engine().executeRaw('INSERT INTO sources(id,name,local_path,config,last_sync_at) VALUES($1,$1,$2,$3::text::jsonb,now())',
      [`${sourceId}-connector`, '/example/connector', JSON.stringify({ kind: 'github', remote_url: 'https://example.invalid/repo.git' })]);
    try {
      const result = await checkSyncFreshness(engine());
      expect(result.status).toBe('warn');
      expect(result.message).toContain(`'${sourceId}' upstream unknown (never checked)`);
      expect(result.message).not.toContain(`'${sourceId}-connector'`);
      expect(result.details).toMatchObject({ upstream_unknown_count: 1 });
    } finally {
      await engine().executeRaw('DELETE FROM sources WHERE id=ANY($1::text[])', [[sourceId, `${sourceId}-connector`]]);
    }
  });
}