Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(persistence): restore cancels deferred writes, expiry locks brain before refresh, default owner guard skips sibling worktrees
garrytan9e8b1849f0f1
diff --git a/docs/architecture/key-files/workspace-push-and-backup.md b/docs/architecture/key-files/workspace-push-and-backup.mdindex 81750cfced..9b2946fcf6 100644--- a/docs/architecture/key-files/workspace-push-and-backup.md+++ b/docs/architecture/key-files/workspace-push-and-backup.md@@ -16,4 +16,4 @@ Key files:- `src/commands/doctor/checks/git-writer.ts` — `checkout_lagging`, `dirty_age`, `commits_outside_source_root`, `quarantined_changes` (#7381, brain category, after `git_convergence`): over the unmanaged source checkouts with an upstream (`sourceRoots` from git-convergence, grouped by toplevel with each source's toplevel-relative root), never fetching, every git call bounded at 5 s. Lagging warns when `HEAD..@{u}` holds a commit over an hour old (fix: `gbrain git commit-push --pull --path <top>`, agent). Dirty age warns on pending write-through files older than 30 minutes (`pendingWriteThroughStillDirty`; fix: `commit-push --pending`, agent) and on files staged that long (ask_user: unstage or commit by name). Outside-root warns on unpushed non-merge commits that change files outside the DB source roots plus `gbrain.sourceRoot` (`localCommitsOutsideRoots`; ask_user fix with `--allow-outside-source-root`), and says when the checkout has no root recorded. Test: `test/doctor-git-writer-7381.test.ts`.- `src/core/git/commit-ledger.ts` — the commit ledger (PR B, docs/designs/REFRESH_WRITE_BARRIER.md part 3): `<git common dir>/gbrain/commit-ledger.jsonl`, one O_APPEND JSON line under 1 KiB per record, under its own flock `commit-ledger.lock` (start line, append, 4 MiB rotation to `commit-ledger.1.jsonl`). `recordCommit`/`recordCommitAsync` take the sha and writer kind (`commit_push`, `door`, `merge`, `replay`, `effect`, `sync_init`, `workspace_push`, `bootstrap`, `hosted_repo`); porcelain sites call `recordIntent` (head_before, `messageDigest` of the message) before `git commit`, plumbing sites record the `commit-tree` sha before the ref moves. A failed append never fails the commit (logged once); a directory outside git records nothing. `readLedger` reads both files. Tests: `test/commit-ledger.test.ts`.- `src/commands/doctor/checks/foreign-writers.ts` — `foreign_writers` (PR B part 4): every registered source checkout on this host, managed worktrees included, deduplicated by git common dir. Reflogs (`logs/HEAD`, `logs/refs/heads/*`, `worktrees/*/logs/HEAD`, newest 5,000 entries each) are classified by `classifyReflogMessage`: porcelain creations by new sha, other ref moves by the `old..new` range within 10 minutes of the entry, merges/fast-forwards/resets/checkouts/branch/clone excluded. Unledgered commits fail (`plain`, `amend`, `rewrite`, `plumbing`; `guard_bypassed` when the enforce guard predates the commit); intent matches are `unconfirmed` (warn, never written back); entries before the ledger start are uncovered. Dirty page files come from `status --porcelain=v2` under the source roots minus queued/running git effects and the write-through pending ledger. Repo-less: `not_applicable`. Tests: `test/doctor-foreign-writers.test.ts`.-- `src/commands/sources-guard.ts` — `gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]` (PR B part 5): owner host only (`permission_denied` elsewhere), install/uninstall under the worktree's native writer lock (`acquireWorktree`). `commit-guard.ts` `installOwnerGuard` writes the hook to `<worktree git dir>/gbrain-hooks` and sets `git config --worktree core.hooksPath` (enabling `extensions.worktreeConfig`, moving `core.bare`/`core.worktree` to `config.worktree`, only when linked worktrees exist), refusing when another tool's hook lives at the effective hooks path; `renderGuardHook('enforce')` keeps only the merge exemption, and the default hook is byte-identical to the opt-in one. Tests: `test/sources-guard.test.ts`.+- `src/commands/sources-guard.ts` — `gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]` (PR B part 5): owner host only (`permission_denied` elsewhere), install/uninstall under the worktree's native writer lock (`acquireWorktree`). `commit-guard.ts` `installOwnerGuard` writes the hook to `<worktree git dir>/gbrain-hooks` and sets `git config --worktree core.hooksPath` (enabling `extensions.worktreeConfig`, moving `core.bare`/`core.worktree` to `config.worktree`, only when linked worktrees exist), refusing when another tool's hook lives at the effective hooks path; both owner-path modes exit 0 outside the owner worktree (a worktree added after the install inherits its hooks path through `config.worktree`), `renderGuardHook('enforce')` keeps only the merge exemption, and `renderGuardHook()` with no mode stays byte-identical to the opt-in `gbrain git guard` hook. Tests: `test/sources-guard.test.ts`.diff --git a/src/core/git/commit-guard.ts b/src/core/git/commit-guard.tsindex 2724f3e629..425802325d 100644--- a/src/core/git/commit-guard.ts+++ b/src/core/git/commit-guard.ts@@ -29,18 +29,21 @@ export const GUARD_BYPASS_ENV = 'GBRAIN_COMMIT_GUARD';export const GUARD_ENFORCE_MARKER = '# mode: enforce (managed worktree: only its owner commits; cherry-pick, revert, rebase and sequencer commits are refused too)';export type GuardMode = 'default' | 'enforce';-export function renderGuardHook(mode: GuardMode = 'default'): string {- const enforce = mode === 'enforce';+/** No mode: the shared-checkout guard of `gbrain git guard`. A mode: the owner-path guard of `gbrain sources guard`. */+export function renderGuardHook(owner?: GuardMode): string {+ const enforce = owner === 'enforce';return `#!/usr/bin/env bash${GUARD_BANNER}${enforce ? `${GUARD_ENFORCE_MARKER}-# LOCAL + untracked: installed by gbrain sources guard <source> --install --mode enforce, removed by --uninstall.` : '# LOCAL + untracked: installed by gbrain git guard --install, removed by --uninstall.'}+# LOCAL + untracked: installed by gbrain sources guard <source> --install --mode enforce, removed by --uninstall.`+ : owner ? '# LOCAL + untracked: installed by gbrain sources guard <source> --install, removed by --uninstall.'+ : '# LOCAL + untracked: installed by gbrain git guard --install, removed by --uninstall.'}# Refuses commits in this shared brain checkout (--no-verify included) that did not come# through gbrain git commit-push or gbrain's own page writes, which hold the commit lock.# A person can bypass it for one command: ${GUARD_BYPASS_ENV}=off git <command>[ "\${${GUARD_BYPASS_ENV}:-}" = off ] && exit 0[ "\${2:-}" = merge ] && exit 0-${enforce ? `# git worktree add copies config.worktree, so a worktree added after the install inherits this hooks path: only the owner worktree is guarded.+${owner ? `# git worktree add copies config.worktree, so a worktree added after the install inherits this hooks path: only the owner worktree is guarded.[ "$(cd "$(git rev-parse --absolute-git-dir)" && pwd -P)" = "$(cd "$(dirname "$0")/.." && pwd -P)" ] || exit 0` : ''}for _op in ${enforce ? 'MERGE_HEAD' : 'MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-merge rebase-apply sequencer'}; do[ -e "$(git rev-parse --git-path "$_op")" ] && exit 0diff --git a/src/core/persistence/refresh-barrier.ts b/src/core/persistence/refresh-barrier.tsindex 6a442ee95a..548d27bbec 100644--- a/src/core/persistence/refresh-barrier.ts+++ b/src/core/persistence/refresh-barrier.ts@@ -15,6 +15,7 @@ import { OperationError } from '../ops/contract.ts';import { authorizeWrite } from './authority.ts';import type { BrainEngine } from '../engine.ts';import { completeWrite } from './journal.ts';+import { declarePersistenceProtocol } from './protocol.ts';import type { SqlEngine, WriteRequest } from './model.ts';const GIT_ENV = { GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never', LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0' };@@ -75,8 +76,10 @@ export const REFRESH_BARRIER_MAX_WAIT_MS = 15 * 60_000;/*** The owner's housekeeping: a deferred write whose refresh is still unreleased past the wait limit ends failed with- * `refresh_barrier_expired` (nothing applied, counters released). The refresh row is locked first (lock order: worktree,- * refresh, counters, request), so an expiry and the release that would make the row claimable never both win.+ * `refresh_barrier_expired` (nothing applied, counters released). The transaction declares the persistence protocol (the+ * brain row FOR SHARE) before it locks the refresh row, the order fenceAndMerge takes them in (brain FOR UPDATE, then the+ * refresh), so an expiry overlapping a fence waits instead of deadlocking; with the refresh row locked, an expiry and+ * the release that would make the row claimable never both win.*/export async function expireDeferredWrites(engine: BrainEngine, hostId: string, signal?: AbortSignal): Promise<WriteRequest[]> {const [config] = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key=$1', [REFRESH_BARRIER_MAX_WAIT_KEY], { signal });@@ -89,6 +92,7 @@ export async function expireDeferredWrites(engine: BrainEngine, hostId: string,const finished: WriteRequest[] = [];for (const row of expired) {const done = await engine.transaction(async tx => {+ await declarePersistenceProtocol(tx);const [held] = await tx.executeRaw('SELECT 1 FROM persistence_worktree_refreshes WHERE id=$1::uuid AND released_at IS NULL FOR NO KEY UPDATE', [row.deferred_refresh_id]);if (!held) return null;return completeWrite(tx, row, 'failed', {}, { code: 'refresh_barrier_expired',diff --git a/src/core/shared-skills/restore.ts b/src/core/shared-skills/restore.tsindex 927f338eb1..082b8c7afe 100644--- a/src/core/shared-skills/restore.ts+++ b/src/core/shared-skills/restore.ts@@ -62,7 +62,7 @@ export async function quarantineSharedSkillRestore(tx: BrainEngine, restoreId: sconst protocols = await tx.executeRaw('SELECT * FROM persistence_writer_protocols');await tx.executeRaw('INSERT INTO config(key,value) VALUES($1,$2)', [`restore.${restoreId}.shared_skills`, JSON.stringify({ ...restored, policies, source_bindings: sourceBindings, host_bindings: hostBindings, worktrees, writer_protocols: protocols })]);await declarePersistenceProtocol(tx);- const pending = await tx.executeRaw<WriteRequest>("SELECT * FROM persistence_requests WHERE state IN ('queued','running') ORDER BY sequence FOR UPDATE");+ const pending = await tx.executeRaw<WriteRequest>("SELECT * FROM persistence_requests WHERE state IN ('queued','deferred','running') ORDER BY sequence FOR UPDATE");for (const request of pending) await completeWrite(tx, request, 'cancelled', {}, { code: mode === 'recovery' ? 'restore_recovery' : 'restore_new_brain', message: 'Restored with archived authority revoked; submit with new authority.' });await tx.executeRaw('UPDATE persistence_requests SET execution_token=NULL,claim_expires_at=NULL WHERE execution_token IS NOT NULL OR claim_expires_at IS NOT NULL');await tx.executeRaw("UPDATE persistence_effects SET state='failed',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,error_code=$1,updated_at=now() WHERE state IN ('queued','running')", [mode === 'recovery' ? 'restore_recovery' : 'restore_new_brain']);diff --git a/test/refresh-write-barrier.test.ts b/test/refresh-write-barrier.test.tsindex 7a43927edf..94ae0fec76 100644--- a/test/refresh-write-barrier.test.ts+++ b/test/refresh-write-barrier.test.ts@@ -27,6 +27,7 @@ import { resetWriteSwitches } from '../src/core/persistence/switches.ts';import { _setRefreshFenceWaitForTests } from '../src/core/persistence/admission-retry.ts';import { _resetRefreshBarrierCacheForTests, deferredBacklog, expireDeferredWrites } from '../src/core/persistence/refresh-barrier.ts';import type { WriteRequest } from '../src/core/persistence/model.ts';+import { quarantineSharedSkillRestore } from '../src/core/shared-skills/restore.ts';import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';import { testBackends } from './helpers/test-backends.ts';import { withEnv } from './helpers/with-env.ts';@@ -188,6 +189,64 @@ test('a deferred write past the wait limit ends refresh_barrier_expired and releexpect((await refresh).status).toBe('completed');}), 180_000);+test('a shared-skill restore cancels a deferred write too and releases its counters (restore is PGLite-only)', () => each(async f => {+ if (f.engine.kind !== 'pglite') return;+ let deferred!: WriteRequest;+ const refresh = await duringRefresh(f, async () => {+ const before = await outstanding(f);+ const out = await call(f, 'put_page', { slug: 'notes/restored', content: page('Restored', 'deferred before the restore') });+ deferred = await requestRow(f, out.body.request_id);+ expect(deferred.state).toBe('deferred');+ expect(await outstanding(f)).toBe(before + 1);+ const rolledBack = new Error('roll the restore back');+ await f.engine.transaction(async tx => {+ await quarantineSharedSkillRestore(tx, randomUUID());+ const [row] = await tx.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE id=$1::uuid', [deferred.id]);+ expect(row).toMatchObject({ state: 'cancelled', error_code: 'restore_new_brain' });+ const [counter] = await tx.executeRaw<{ n: number }>("SELECT outstanding_count::int AS n FROM persistence_counters WHERE key='brain'");+ expect(Number(counter!.n)).toBe(before);+ throw rolledBack;+ }).catch(error => { if (error !== rolledBack) throw error; });+ });+ expect((await refresh).status).toBe('completed');+ expect((await settle(f, deferred)).state).toBe('committed');+}), 180_000);++test('an expiry that overlaps a fence waits on the brain row instead of deadlocking with it (Postgres)', () => each(async f => {+ if (f.engine.kind !== 'postgres') return;+ const refresh = await duringRefresh(f, async () => {+ const out = await call(f, 'put_page', { slug: 'notes/expiry-order', content: page('Expiry order', 'body') });+ const deferred = await requestRow(f, out.body.request_id);+ expect(deferred.state).toBe('deferred');+ await f.engine.executeRaw("INSERT INTO config(key,value) VALUES('persistence.refresh_barrier_max_wait_ms','1') ON CONFLICT (key) DO UPDATE SET value=EXCLUDED.value");+ await new Promise(resolve => setTimeout(resolve, 20));+ const [{ owner }] = await f.engine.executeRaw<{ owner: string }>('SELECT owner_host_id::text AS owner FROM persistence_worktrees WHERE id=$1::uuid', [f.worktreeId]);+ let holding!: () => void; const held = new Promise<void>(resolve => { holding = resolve; });+ let waiting!: () => void; const expiryWaits = new Promise<void>(resolve => { waiting = resolve; });+ // fenceAndMerge's order: the brain row FOR UPDATE, then the refresh row.+ const fence = f.engine.transaction(async tx => {+ await tx.executeRaw("SELECT set_config('lock_timeout','10s',true)");+ await tx.executeRaw('SELECT singleton FROM persistence_brain WHERE singleton=1 FOR UPDATE');+ holding();+ await expiryWaits;+ await tx.executeRaw('SELECT 1 FROM persistence_worktree_refreshes WHERE id=$1::uuid FOR NO KEY UPDATE', [deferred.deferred_refresh_id]);+ });+ await held;+ const expiry = expireDeferredWrites(f.engine, owner);+ for (let i = 0; i < 400; i++) {+ const [w] = await f.engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM pg_stat_activity WHERE datname=current_database() AND wait_event_type='Lock'");+ if (Number(w!.n) > 0) break;+ await new Promise(resolve => setTimeout(resolve, 25));+ }+ waiting();+ const [fenced, expired] = await Promise.allSettled([fence, expiry]);+ await f.engine.executeRaw("DELETE FROM config WHERE key='persistence.refresh_barrier_max_wait_ms'");+ expect(fenced.status === 'rejected' ? String(fenced.reason) : 'fence committed').toBe('fence committed');+ expect(expired.status === 'fulfilled' ? expired.value.map(row => row.id) : String(expired.reason)).toEqual([deferred.id]);+ });+ expect((await refresh).status).toBe('completed');+}), 180_000);+test('a live consumer without the capability keeps the refusal; a repo-less source is never deferred', () => each(async f => {const refresh = await duringRefresh(f, async () => {const repoLess = await call(f, 'put_page', { slug: 'notes/repo-less', content: page('Repo-less', 'database only') }, 'default');diff --git a/test/sources-guard.test.ts b/test/sources-guard.test.tsindex ddbdb5c92e..b99f6621ac 100644--- a/test/sources-guard.test.ts+++ b/test/sources-guard.test.ts@@ -34,10 +34,15 @@ afterAll(async () => {const refused = async (promise: Promise<unknown>) => promise.then(() => null, e => e as { code?: string; message?: string });-test('the opt-in hook is byte-identical in default mode; enforce drops only the rewrite exemptions', () => {+test('the opt-in hook is byte-identical; both owner-path modes guard only the owner worktree; enforce drops only the rewrite exemptions', () => {+ const ownerOnly = 'only the owner worktree is guarded';expect(createHash('sha256').update(renderGuardHook()).digest('hex')).toBe('f5afdf64fd917d42c444c7e5b3f721670b2701a92047fceaa2e8fd2c0dac962d');- expect(renderGuardHook('default')).toBe(renderGuardHook());+ expect(renderGuardHook()).not.toContain(ownerOnly);+ const owner = renderGuardHook('default');+ expect(owner).toContain(ownerOnly);+ expect(owner).toContain('for _op in MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-merge rebase-apply sequencer; do');const enforce = renderGuardHook('enforce');+ expect(enforce).toContain(ownerOnly);expect(enforce).toContain('for _op in MERGE_HEAD; do');expect(enforce).not.toContain('CHERRY_PICK_HEAD');});@@ -102,6 +107,29 @@ test('owner host only; enforce refuses a plain commit; refresh, effect and doorexpect(removed).toMatchObject({ installed: false, changed: true });}), 120_000);+test('default mode guards only the owner worktree: a worktree added after the install inherits the hooks path and commits freely', () => withRefreshFixture(engine, async f => {+ git(f.root, 'config', 'user.name', 'Example');+ git(f.root, 'config', 'user.email', '[email protected]');+ const installed = await sourcesGuard(f.engine, { sourceId: f.alpha, action: 'install', mode: 'default' });+ expect(installed).toMatchObject({ installed: true, mode: 'default' });+ const later = join(f.dir, 'later-default');+ git(f.root, 'worktree', 'add', '-q', '-b', 'later-default', later);+ expect(git(later, 'rev-parse', '--path-format=absolute', '--git-path', 'hooks')).toBe(installed.hooks_path);+ writeFileSync(join(later, 'alpha', 'later.md'), page('Later', 'A person commits in a worktree added after the install.'));+ git(later, 'add', 'alpha/later.md');+ git(later, 'commit', '-q', '-m', 'commit in a worktree added after a default-mode install');+ writeFileSync(join(later, 'alpha', 'later-two.md'), page('Later two', 'And with --no-verify.'));+ git(later, 'add', 'alpha/later-two.md');+ git(later, 'commit', '-q', '--no-verify', '-m', 'no-verify in the later worktree');++ writeFileSync(join(f.root, 'alpha', 'stray.md'), page('Stray', 'Refused in the owner worktree.'));+ git(f.root, 'add', 'alpha/stray.md');+ expect(() => git(f.root, 'commit', '-q', '-m', 'plain commit in the managed worktree')).toThrow(/gbrain commit guard/);+ git(f.root, 'restore', '--staged', 'alpha/stray.md');+ rmSync(join(f.root, 'alpha', 'stray.md'));+ await sourcesGuard(f.engine, { sourceId: f.alpha, action: 'uninstall', mode: 'default' });+}), 120_000);+test('the install is worktree-local: a linked sibling keeps its hooks and commits freely; a foreign hook refuses', () => withRefreshFixture(engine, async f => {const sibling = join(f.dir, 'sibling');git(f.root, 'worktree', 'add', '-q', '-b', 'side', sibling);