Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
23.4 KB
Raw Blame
/**
 * #5182 / #5808: per-host Git-durability opt-in for managed worktrees.
 *
 * [R7i]  The policy resolver is tri-state and fail-closed: a recorded setting
 *        wins over the legacy hook probe in both directions, and an absent
 *        setting defers to the probe, whose failure is an error, not "durable".
 * [R7ii] `writer git-durability` is a real admin verb: it refuses an unclaimed
 *        source, names an unborn branch as unborn (not "detached HEAD"),
 *        requires the admin-intent handshake, records the setting on the
 *        binding, re-queues the Git effects skipped while durability was off
 *        and the worker then commits them; `--disable` wins over a hook.
 *        `--pat-file` refuses a readable token file before writing anything.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { createHash, randomUUID } from 'node:crypto';
import { chmodSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { runPersistenceAdministration } from '../src/core/persistence/administration.ts';
import { PERSISTENCE_ADMIN_OPERATIONS } from '../src/core/persistence/admin-contract.ts';
import { parsePersistenceAdminArgs } from '../src/commands/persistence-admin.ts';
import { gitDurabilityPolicy, gitDurabilityState, planGitDurabilityCatchUp } from '../src/core/persistence/git-durability-policy.ts';
import { claimWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';
import { localHostId, registerLocalWriter } from '../src/core/persistence/identity.ts';
import { submissionAuthority } from '../src/core/persistence/authority.ts';
import { admitWrite, claimNextWrite } from '../src/core/persistence/journal.ts';
import { publishMutation } from '../src/core/persistence/coordinator.ts';
import { runPersistenceEffects } from '../src/core/persistence/effects.ts';
import { serializePageToMarkdown } from '../src/core/markdown.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { v234 } from '../src/core/schema-migrations/v234-persistence-git-durability.ts';
import { PERSISTENCE_GIT_DURABILITY_COLUMN_SQL, PERSISTENCE_SCHEMA_STATEMENTS } from '../src/core/persistence/schema.ts';
import { gitAsync } from './helpers/git-publication.ts';
import { runCli } from './helpers/cli-spawn.ts';
import { withEnv } from './helpers/with-env.ts';
import { reviewedWriterIntent } from './helpers/writer-admin-intent.ts';

let engine: PGLiteEngine;
const roots: string[] = [];
const config = { engine: 'pglite' as const, embedding_disabled: true };
const page = (body: string) => ({ type: 'note', title: 'Example', compiled_truth: body.trim(), timeline: '', frontmatter: {} });
beforeAll(async () => {
  engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema();
}, 120_000);
afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); for (const root of roots) rmSync(root, { recursive: true, force: true }); });

/** Everything runs under a private GBRAIN_HOME so the host identity, the credential store and the file-transport flag are the test's own. */
async function isolated<T>(run: (home: string) => Promise<T>): Promise<T> {
  const home = mkdtempSync(join(tmpdir(), 'gbrain-git-durability-')); roots.push(home);
  try {
    return await withEnv({ GBRAIN_HOME: home, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: undefined, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined,
      GBRAIN_GIT_ALLOW_FILE_TRANSPORT: '1' }, async () => { await registerLocalWriter(engine, 'cli'); return run(home); });
  } finally { await disposePersistenceConsumer(engine); }
}

async function gitRoot(home: string, opts: { commit?: boolean; remote?: boolean } = {}): Promise<string> {
  const root = join(home, `root-${randomUUID().slice(0, 8)}`); mkdirSync(root);
  await gitAsync(root, 'init', '-q', '-b', 'main');
  await gitAsync(root, 'config', 'user.name', 'Example Writer');
  await gitAsync(root, 'config', 'user.email', '[email protected]');
  if (opts.commit !== false) {
    writeFileSync(join(root, 'initial.md'), 'Initial\n');
    await gitAsync(root, 'add', 'initial.md'); await gitAsync(root, 'commit', '-q', '-m', 'Initial');
  }
  if (opts.remote) {
    const remote = join(home, `remote-${randomUUID().slice(0, 8)}.git`); mkdirSync(remote);
    await gitAsync(remote, 'init', '-q', '--bare');
    await gitAsync(root, 'remote', 'add', 'origin', remote); await gitAsync(root, 'push', '-q', '-u', 'origin', 'main');
  }
  return root;
}

async function claimedSource(root: string) {
  const sourceId = `durability-${randomUUID().slice(0, 8)}`;
  await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, root]);
  const binding = await claimWorktree(engine, sourceId, root, localHostId());
  return { sourceId, binding };
}

/** A committed page write whose Git effect is queued (the persistence-effects fixture, minus the hook). */
async function committedWrite(root: string, sourceId: string, slug: string) {
  const binding = (await getWorktreeBinding(engine, sourceId, localHostId()))!;
  await engine.putPage(slug, page('Before'), { sourceId });
  const snapshot = (await engine.readPageSnapshot(slug, { sourceId }))!;
  const file = join(root, `${slug}.md`); mkdirSync(dirname(file), { recursive: true });
  writeFileSync(file, serializePageToMarkdown(snapshot.page, snapshot.tags));
  const ctx: OperationContext = { engine, config, remote: false, dryRun: false, sourceId, logger: { info() {}, warn() {}, error() {} } };
  const authority = await submissionAuthority(ctx, 'put_page', sourceId, binding.source_incarnation, slug);
  const admitted = await admitWrite(engine, { principal: authority.principal, authority, operation: 'put_page', sourceId,
    sourceIncarnation: binding.source_incarnation, slug, pageId: snapshot.page.id, requestId: randomUUID(),
    callerIntent: { content: 'After' }, intent: { content: 'After' }, worktreeId: binding.worktree_id, topologyGeneration: binding.topology_generation });
  const row = (await claimNextWrite(engine, localHostId()))!;
  expect(row.id).toBe(admitted.id);
  const result = await publishMutation(engine, row, { observedRevision: snapshot.revision, file: { path: file, root, content: 'After' },
    apply: async tx => { await tx.putPage(slug, page('After'), { sourceId }); return {}; } }, localHostId());
  expect(result.state).toBe('committed');
  return row.id;
}
async function gitOutcome(requestId: string) {
  const [row] = await engine.executeRaw<{ state: string; outcome: Record<string, unknown> | null; data: Record<string, unknown> }>(
    "SELECT state,outcome,data FROM persistence_effects WHERE request_id=$1::uuid AND kind='git'", [requestId]);
  return row;
}
/** Every file under the private home: the checkout, its .git (config, index, refs) and the credential store. */
function treeBytes(dir: string, files: Record<string, string> = {}): Record<string, string> {
  for (const name of readdirSync(dir).sort()) {
    const path = join(dir, name);
    if (statSync(path).isDirectory()) treeBytes(path, files);
    else files[path] = createHash('sha256').update(readFileSync(path)).digest('hex');
  }
  return files;
}
async function runEffects() {
  await engine.executeRaw("UPDATE persistence_effects SET next_attempt_at=now() WHERE kind='git'");
  await runPersistenceEffects(engine, config, { hostId: localHostId(), limit: 10 });
}

describe('[R7i] git durability policy is tri-state and fail-closed', () => {
  const probeCalls: string[] = [];
  const probe = (answer: boolean | Error) => async (root: string) => { probeCalls.push(root); if (answer instanceof Error) throw answer; return answer; };

  test('a recorded setting wins over the legacy hook probe in both directions, and the probe is not consulted', async () => {
    probeCalls.length = 0;
    expect(await gitDurabilityPolicy({ git_durability: 'enabled' }, '/srv/a', probe(false))).toEqual({ durable: true, source: 'binding' });
    expect(await gitDurabilityPolicy({ git_durability: 'disabled' }, '/srv/a', probe(true))).toEqual({ durable: false, source: 'binding' });
    expect(probeCalls).toEqual([]);
  });

  test('an absent setting defers to the probe, and a probe failure is an error rather than durable', async () => {
    expect(await gitDurabilityPolicy({ git_durability: null }, '/srv/b', probe(true))).toEqual({ durable: true, source: 'legacy_hook' });
    expect(await gitDurabilityPolicy(null, '/srv/b', probe(false))).toEqual({ durable: false, source: 'no_hook' });
    await expect(gitDurabilityPolicy(undefined, '/srv/b', probe(new Error('hooks dir unreadable')))).rejects.toThrow('hooks dir unreadable');
    expect(gitDurabilityState({ git_durability: 'enabled' })).toBe('on');
    expect(gitDurabilityState({ git_durability: 'disabled' })).toBe('off');
    expect(gitDurabilityState(null)).toBe('unknown');
  });

  test('the column is created by CREATE TABLE on a fresh brain and by v234 on an existing one, never by the replayed schema blob', async () => {
    const [column] = await engine.executeRaw<{ data_type: string; is_nullable: string }>(
      "SELECT data_type,is_nullable FROM information_schema.columns WHERE table_name='persistence_host_bindings' AND column_name='git_durability'");
    expect(column).toEqual({ data_type: 'text', is_nullable: 'YES' });
    expect(v234.sql).toBe(PERSISTENCE_GIT_DURABILITY_COLUMN_SQL);
    expect(v234.sqlFor?.postgres).toContain("lock_timeout = '2s'");
    expect(v234.idempotent).toBe(true);
    expect(await v234.verify!(engine)).toBe(true);
    expect(PERSISTENCE_SCHEMA_STATEMENTS.some(statement => statement.includes('ADD COLUMN IF NOT EXISTS git_durability'))).toBe(false);
    await expect(engine.executeRaw("UPDATE persistence_host_bindings SET git_durability='maybe' WHERE false")).resolves.toBeDefined();
    const [{ ok }] = await engine.executeRaw<{ ok: boolean }>(
      `SELECT EXISTS(SELECT 1 FROM information_schema.check_constraints WHERE check_clause LIKE '%git_durability%') AS ok`);
    expect(ok).toBe(true);
  });
});

describe('[R7ii] writer git-durability verb', () => {
  test('the verb is an admin operation with a CLI spelling, and its flags parse', () => {
    expect(PERSISTENCE_ADMIN_OPERATIONS).toContain('writer_git_durability');
    const parsed = parsePersistenceAdminArgs('writer', ['git-durability', 'notes', '--enable', '--dry-run', '--json']);
    expect(parsed).toMatchObject({ operation: 'writer_git_durability', params: { source_id: 'notes', enable: true, dry_run: true }, json: true });
    expect(parsePersistenceAdminArgs('writer', ['git-durability', 'notes', '--pat-file', '/tmp/token']).params.pat_file).toBe('/tmp/token');
    expect(() => parsePersistenceAdminArgs('writer', ['git-durability', 'notes', '--enable=yes'])).toThrow(/does not accept a value/);
  });

  test('an unclaimed source is refused with the claim as the next step; --enable and --disable together are refused', () => isolated(async () => {
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: `nobody-${randomUUID().slice(0, 6)}`, enable: true, dry_run: true }))
      .rejects.toMatchObject({ code: 'writer_registration_required' });
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: 'x', enable: true, disable: true, dry_run: true }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('not both') });
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: 'x', dry_run: true }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('--enable, --disable, or --pat-file') });
  }));

  test('an unborn branch is named as unborn, a detached HEAD as detached, and a plain directory as not a checkout', () => isolated(async home => {
    const unborn = await claimedSource(await gitRoot(home, { commit: false }));
    const refusal = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: unborn.sourceId, enable: true, dry_run: true }).catch(error => error);
    expect(refusal).toMatchObject({ code: 'git_branch_unborn' });
    expect(refusal.message).toContain('unborn');
    expect(refusal.message).not.toContain('detached');
    expect(refusal.suggestion).toContain('git add -A && git commit');
    const detachedRoot = await gitRoot(home);
    await gitAsync(detachedRoot, 'checkout', '-q', '--detach');
    const detached = await claimedSource(detachedRoot);
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: detached.sourceId, enable: true, dry_run: true }))
      .rejects.toMatchObject({ code: 'git_detached_head' });
    const plain = join(home, 'plain'); mkdirSync(plain);
    const notGit = await claimedSource(plain);
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: notGit.sourceId, enable: true, dry_run: true }))
      .rejects.toMatchObject({ code: 'git_checkout_required' });
    // A refused preview recorded nothing.
    for (const { sourceId } of [unborn, detached, notGit]) expect((await getWorktreeBinding(engine, sourceId, localHostId()))!.git_durability).toBeNull();
  }));

  test('enable needs the admin-intent handshake, records the setting, re-queues skipped Git effects and the worker commits them', () => isolated(async home => {
    const root = await gitRoot(home, { remote: true });
    const { sourceId } = await claimedSource(root);
    // Without a hook and nothing recorded, a managed write's Git effect completes as skipped.
    const first = await committedWrite(root, sourceId, 'alpha');
    const second = await committedWrite(root, sourceId, 'beta');
    await runEffects();
    expect(await gitOutcome(first)).toMatchObject({ state: 'committed', outcome: { reason: 'durability_not_enabled' } });
    expect(await gitOutcome(second)).toMatchObject({ state: 'committed', outcome: { reason: 'durability_not_enabled' } });
    expect((await gitAsync(root, 'status', '--porcelain', '--', 'alpha.md', 'beta.md')).trim()).not.toBe('');

    const preview = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, dry_run: true });
    expect(preview).toMatchObject({ dry_run: true, git_durability: { before: null, after: 'enabled' }, current_policy: { durable: false, source: 'no_hook' },
      branch: 'main', tracking_remote: 'origin', push_probe: { ok: true }, catch_up: { planned: 2 }, queued_catch_up: 0 });
    expect((preview.fix as { argv: string[] }).argv.join(' ')).toContain('--admin-intent writer_git_durability --expected-state ');
    expect((await getWorktreeBinding(engine, sourceId, localHostId()))!.git_durability).toBeNull();
    expect((await planGitDurabilityCatchUp(engine, (await getWorktreeBinding(engine, sourceId, localHostId()))!)).map(effect => effect.relative_path).sort()).toEqual(['alpha.md', 'beta.md']);

    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true }))
      .rejects.toMatchObject({ code: 'writer_admin_intent_required' });
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, admin_intent: 'writer_activate', expected_state: 'f'.repeat(64) }))
      .rejects.toMatchObject({ code: 'writer_admin_intent_required' });
    const stale = await reviewedWriterIntent(engine, 'writer_git_durability');
    const applied = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, ...stale });
    expect(applied).toMatchObject({ applied: true, git_durability: { before: null, after: 'enabled' }, queued_catch_up: 2 });
    expect((await getWorktreeBinding(engine, sourceId, localHostId()))!.git_durability).toBe('enabled');
    expect(await gitOutcome(first)).toMatchObject({ state: 'queued', outcome: null, data: { durability_catch_up: 1 } });

    // The recorded setting is part of the admin state: the pre-apply fingerprint is stale now.
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, disable: true, ...stale }))
      .rejects.toMatchObject({ code: 'writer_admin_state_changed' });
    const status = await runPersistenceAdministration(engine, 'writer_status', { source_id: sourceId }) as { bindings: Array<Record<string, unknown>> };
    expect(status.bindings.find(binding => binding.source_id === sourceId)).toMatchObject({ git_durability: 'enabled', git_durability_state: 'on' });

    // The worker runs the re-queued effects: both files are committed and pushed, with no hook anywhere.
    await runEffects();
    expect(await gitOutcome(first)).toMatchObject({ state: 'committed', outcome: { git: 'committed' } });
    expect(await gitOutcome(second)).toMatchObject({ state: 'committed', outcome: { git: 'committed' } });
    expect((await gitAsync(root, 'status', '--porcelain', '--', 'alpha.md', 'beta.md')).trim()).toBe('');
    expect(await gitAsync(root, 'ls-tree', '--name-only', 'origin/main')).toContain('alpha.md');
    expect(await gitAsync(root, 'ls-tree', '--name-only', 'origin/main')).toContain('beta.md');
    // Enabling again plans nothing: the caught-up effects are no longer skipped.
    const again = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, dry_run: true });
    expect(again).toMatchObject({ catch_up: { planned: 0 }, why: expect.stringContaining('already as requested') });
  }), 120_000);

  for (const refusal of ['missing', 'wrong', 'stale'] as const) {
    test(`#7634 a refused apply (${refusal} approval) leaves the checkout, the credential store and the parked push unchanged`, () => isolated(async home => {
      const root = await gitRoot(home, { remote: true });
      writeFileSync(join(root, 'AGENTS.md'), '# Operator instructions\n');
      await gitAsync(root, 'add', 'AGENTS.md'); await gitAsync(root, 'commit', '-q', '-m', 'Instructions'); await gitAsync(root, 'push', '-q');
      const { sourceId } = await claimedSource(root);
      const id = await committedWrite(root, sourceId, 'parked7634');
      await engine.executeRaw(`UPDATE persistence_effects SET state='failed',error_code='targets_parked',data=data || $2::text::jsonb
        WHERE request_id=$1::uuid AND kind='git'`, [id, JSON.stringify({ parked: [{ slug: 'parked7634', error_code: 'git_push_unavailable' }], target_failures: 5 })]);
      const token = join(home, 'synthetic-token');
      writeFileSync(token, 'synthetic-test-only-token\n', { mode: 0o600 });
      const reviewed = await reviewedWriterIntent(engine, 'writer_git_durability');
      if (refusal === 'stale') await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [`other-${randomUUID().slice(0, 8)}`]);
      const params = { source_id: sourceId, enable: true, pat_file: token,
        ...(refusal === 'missing' ? {} : refusal === 'wrong' ? { ...reviewed, admin_intent: 'writer_activate' } : reviewed) };
      const before = treeBytes(home);
      const effect = await gitOutcome(id);
      const error = await runPersistenceAdministration(engine, 'writer_git_durability', params).catch(caught => caught);
      expect(error).toMatchObject({ code: refusal === 'stale' ? 'writer_admin_state_changed' : 'writer_admin_intent_required' });
      expect(treeBytes(home)).toEqual(before);
      expect(await gitOutcome(id)).toEqual(effect);
      expect((await getWorktreeBinding(engine, sourceId, localHostId()))!.git_durability).toBeNull();
    }), 120_000);
  }

  test('--disable wins over a legacy hook: the next Git effect completes as skipped; --pat-file refuses a readable token file first', () => isolated(async home => {
    const root = await gitRoot(home);
    const hook = join(root, '.git', 'hooks', 'post-commit');
    writeFileSync(hook, '#!/bin/sh\n# gbrain brain-durability post-commit hook (v0.42.44+)\n'); chmodSync(hook, 0o755);
    const { sourceId } = await claimedSource(root);
    expect(await gitDurabilityPolicy(await getWorktreeBinding(engine, sourceId, localHostId()), root)).toEqual({ durable: true, source: 'legacy_hook' });
    const disabled = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, disable: true, ...await reviewedWriterIntent(engine, 'writer_git_durability') });
    expect(disabled).toMatchObject({ applied: true, git_durability: { before: null, after: 'disabled' }, queued_catch_up: 0 });
    const request = await committedWrite(root, sourceId, 'gamma');
    await runEffects();
    expect(await gitOutcome(request)).toMatchObject({ state: 'committed', outcome: { reason: 'durability_not_enabled' } });
    expect(await gitAsync(root, 'log', '--oneline')).not.toContain('gamma');

    const token = join(home, 'token'); writeFileSync(token, 'ghp_exampletoken\n'); chmodSync(token, 0o644);
    const refusal = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, pat_file: token, dry_run: true }).catch(error => error);
    expect(refusal).toMatchObject({ code: 'pat_file_unreadable' });
    expect(refusal.message).not.toContain('ghp_exampletoken');
    expect(refusal.suggestion).toContain('chmod 600');
    expect((await gitAsync(root, 'config', '--local', '--get', 'credential.helper').catch(() => '')).trim()).toBe('');
    await expect(runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, disable: true, pat_file: token, dry_run: true }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('--pat-file cannot be combined with --disable') });
  }), 120_000);
});


describe('GST-2767 the durability block the verb writes is never left untracked without the exact commit command', () => {
  test('enable names the door command for the AGENTS.md it writes and for an untracked copy an earlier run left; the command commits it', () => isolated(async home => {
    const root = await gitRoot(home, { remote: true });
    const { sourceId } = await claimedSource(root);
    const argv = ['gbrain', 'git', 'commit-push', '--path', root, '-m', `gbrain: durability rules for source ${sourceId}`, '--', 'AGENTS.md'];
    const head = (await gitAsync(root, 'rev-parse', 'HEAD')).trim();
    const applied = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, ...await reviewedWriterIntent(engine, 'writer_git_durability') }) as Record<string, any>;
    expect(applied.agents).toMatchObject({ status: 'fixed', file: 'AGENTS.md', commit_argv: argv });
    expect((await gitAsync(root, 'rev-parse', 'HEAD')).trim()).toBe(head);
    // The block is already current on the next run, and the untracked file still gets the command (it used to get nothing).
    const again = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, ...await reviewedWriterIntent(engine, 'writer_git_durability') }) as Record<string, any>;
    expect(again.agents).toMatchObject({ status: 'ok', commit_argv: argv, commit: expect.stringContaining('gbrain git commit-push') });
    const run = await runCli(argv.slice(1), { home, cwd: root, timeoutMs: 120_000 });
    expect(run.exitCode).toBe(0);
    expect((await gitAsync(root, 'status', '--porcelain', '--untracked-files=all', '--', 'AGENTS.md')).trim()).toBe('');
    const settled = await runPersistenceAdministration(engine, 'writer_git_durability', { source_id: sourceId, enable: true, ...await reviewedWriterIntent(engine, 'writer_git_durability') }) as Record<string, any>;
    expect(settled.agents.commit_argv).toBeUndefined();
  }), 180_000);
});