Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(refresh): run the fenced ff-merge under the checkout commit lock so a door commit is waited out, not refresh_dirty (#8117)

garrytan53fc06089104
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bebd4b391d..c89d6afe05 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,15 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**A `gbrain git commit-push` landing during a `gbrain sources refresh` no longer makes the refresh fail as `refresh_dirty` (#8117).** The refresh now runs its HEAD check and fast-forward merge under the checkout's commit lock, the same lock the door uses, so it waits for a door commit to finish instead of colliding with it on `.git/index.lock`.
+
+### Itemized changes
+
+- `src/core/persistence/worktree-refresh.ts`: `fenceAndMerge` takes the checkout's commit lock (`brain-commit.lock` plus the legacy push lock, waiting `GBRAIN_COMMIT_LOCK_WAIT_SECONDS`, default 60) from the HEAD check through the merge. A lock still held past that wait aborts the fenced refresh as retryable `commit_lock_busy`. A git process outside the lock that holds `.git/index.lock` gets three short retries, then a retryable `git_index_locked` refusal instead of the caller-class `refresh_dirty`. Either way HEAD is unchanged and the next run starts fresh.
+- Test: `test/worktree-refresh-index-lock-8117.test.ts`.
+
## [0.60.529.0] - 2026-10-31
**A pull request that adds a file to the PGLite snapshot inputs no longer gets stopped at gstack's pregate secrets check by its own workflow cache keys (#8107).**
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index e43d770ea2..525e232713 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -549,7 +549,7 @@ this anchor (`--json` puts them in one object on stdout); the command exits 1.
| <a id="fetch_failed"></a>`fetch_failed` | `fetch_failed` | `git fetch` failed or did not finish within `sources.refresh_fetch_timeout_ms` (default 120000; `GBRAIN_REFRESH_FETCH_TIMEOUT_MS`; `--fetch-timeout-ms` wins over both). Nothing changed and no refresh record was written. | Retry. For a slow remote, raise the bound with `--fetch-timeout-ms <ms>` or `gbrain config set sources.refresh_fetch_timeout_ms <ms>`. Credentials are the user's: ask them to fix authentication rather than changing the remote. |
| <a id="refresh_git_unavailable"></a>`git_unavailable` | `git_unavailable` | A git command that reads the checkout's branch or remote (`symbolic-ref`, `remote`, `config --get branch.<branch>.remote` or `.merge`) failed or did not finish, so the checkout's state is unknown. The message names the command and git's first error line. A detached HEAD or an unset key is not this refusal. Nothing changed and no refresh record was written. | Run `git -C <checkout> status` to see why git cannot read the checkout, repair what it reports, then retry `gbrain sources refresh <source>`. |
| <a id="refresh_diverged"></a>`refresh_diverged` | `refresh_diverged` | The checkout has commits its upstream lacks, so a fast-forward is impossible. Nothing changed. | Ask the user, then publish the local commits merged with the upstream: `gbrain git commit-push --push-only --keep-checkout --path <checkout>` merges in memory, pushes the merge, refuses on a conflicting file and never moves the checkout (the refusal's fix fills in the real path and counts the local commits). Then retry `gbrain sources refresh <source>`, which fast-forwards to the merge. `gbrain sources reclone <source>` replaces the checkout instead and drops the local commits. |
-| <a id="refresh_dirty"></a>`refresh_dirty` | `refresh_dirty` | Uncommitted or untracked files overlap the incoming upstream changes (the first 20 are named), or `git merge --ff-only` refused for the same reason. HEAD did not move. Uncommitted files outside the incoming changes do not refuse; they are kept and listed as `preserved_uncommitted`. | Commit or discard the named paths, then retry. Check `gbrain sources writer status <source> --json` first: a pending Git effect may be about to commit a gbrain-published file. |
+| <a id="refresh_dirty"></a>`refresh_dirty` | `refresh_dirty` | Uncommitted or untracked files overlap the incoming upstream changes (the first 20 are named), or `git merge --ff-only` refused for the same reason. HEAD did not move. The merge runs under the checkout's commit lock, so a `gbrain git commit-push` in progress is waited out (#8117); a lock held past its wait refuses as `commit_lock_busy`, and another git process holding `.git/index.lock` refuses as `git_index_locked` after brief retries. Both are retryable. Uncommitted files outside the incoming changes do not refuse; they are kept and listed as `preserved_uncommitted`. | Commit or discard the named paths, then retry. Check `gbrain sources writer status <source> --json` first: a pending Git effect may be about to commit a gbrain-published file. |
| <a id="sync_in_progress"></a>`sync_in_progress` | `sync_in_progress` | A managed sync of one of the checkout's sources has an unfinished cursor. Moving the checkout now would strand it, and the refresh never waits on a sync. `gbrain repair frontmatter --apply` refuses the same way while an unfinished cursor still names a selected file. | Run the printed `gbrain sync --source <source> --no-pull ...` resume command (it keeps the cursor's options), then retry (for a repair, preview again and approve the new hash). |
| <a id="refresh_in_progress"></a>`refresh_in_progress` | `refresh_in_progress` | Another refresh of the same checkout is active and its process is still running (the message names its holder's pid and host when the active refresh row is already readable), or a command that changes which sources share the checkout (`sources add`, `remove`, `archive`, `restore`, `reclone`) ran while one was active. A refresh whose process died is not a reason to refuse: the next refresh on the owner host finishes it first (`--dry-run` does not, so it still refuses while the orphan stands, and neither does a refresh that cannot read the checkout's HEAD: it leaves the orphan as it is and refuses until git can read HEAD again). A refresh whose holder is recorded on another host is never taken over either: writer status shows its `liveness` as `unknown`, and `gbrain sources refresh <source> --resume` on the owner host finishes it once that host's refresh is known to have stopped. Pending publication or topology recovery on the checkout refuses `refresh_recovery_required` first. An interrupted refresh that needs a reset decision refuses `refresh_recovery_required` instead. | Wait for the running refresh, or check it with `gbrain sources writer status <source>` (`liveness`, `holder`). `gbrain sources refresh <source> --resume` finishes an orphaned one now; then retry the source command with the same request ID. |
| <a id="refresh_drain_timeout"></a>`refresh_drain_timeout` | `refresh_drain_timeout` | Queued writes or Git effects on the checkout did not finish within `--wait-drain` (default 60 s; `sources.refresh_drain_wait_ms`; `GBRAIN_REFRESH_DRAIN_WAIT_MS`). The counts are in the message. The fence was lifted and HEAD did not move. | Retry, or wait longer with `--wait-drain <seconds>`. Inspect what is queued with `gbrain sources writer status <source> --json`. |
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index 93aab6ef82..7c6641f627 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -83,6 +83,9 @@ const describeHolder = (holder: RefreshHolder | null) => holder ? `pid ${holder.
const DRAIN_POLL_MS = 250;
const SYNC_BUDGET_MS = 300_000;
const MAX_MEMBER_SYNC_PASSES = 20;
+const INDEX_LOCKED = /index\.lock': File exists|Unable to create '.*index\.lock'/;
+const INDEX_LOCK_ATTEMPTS = 4;
+const INDEX_LOCK_RETRY_MS = 250;
const GIT_ENV = { GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never', LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0' };
function refusal(name: CatalogueName, cause: string, fix: string, refreshId?: string): OperationError {
@@ -591,22 +594,38 @@ async function fenceAndMerge(engine: BrainEngine, git: Git, sourceId: string, pl
});
const current = await readRefresh(engine, row.id);
await hooks?.boundary?.('fenced', current);
- const head = await headOf(git, plan.root);
- if (head !== row.old_head) {
- if (head === null) throw await markRecoveryRequired(engine, current, head, plan.root);
- await abort(engine, current, ['fenced'], refusal('refresh_source_changed',
- `The checkout HEAD moved from ${row.old_head} to ${head} after the precheck (an external commit or checkout); nothing was merged.`, `Retry gbrain sources refresh ${sourceId}`));
- }
- const dirt = await dirtyOverlap(git, plan.root, row.old_head, row.target_head);
- if (dirt.overlap.length) await abort(engine, current, ['fenced'], dirtyRefusal(sourceId, dirt.overlap));
- const merge = await git(['-C', plan.root, 'merge', '--ff-only', '--no-edit', '--quiet', row.target_head], 120_000);
- const after = await headOf(git, plan.root);
- if (merge.code !== 0 || after !== row.target_head) {
- if (after === row.old_head) await abort(engine, current, ['fenced'], refusal('refresh_dirty',
- `git merge --ff-only refused (${merge.stderr.trim().split('\n')[0] || `exit ${merge.code}`}); HEAD is unchanged at ${row.old_head}.`,
- `Commit or discard the paths git names (check gbrain sources writer status ${sourceId} --json for pending git effects), then retry gbrain sources refresh ${sourceId}.`));
- throw await markRecoveryRequired(engine, current, after, plan.root);
- }
+ // #8117: `gbrain git commit-push` serializes on the checkout's commit lock, not on the refresh fence, so the HEAD check
+ // through the merge runs under that lock too: a door commit can neither move HEAD nor hold .git/index.lock in between.
+ const { acquireCommitLockAsync } = await import('../git/commit-push.ts');
+ const commitLock = await acquireCommitLockAsync(plan.root).catch(error => abort(engine, current, ['fenced'], error instanceof OperationError ? error
+ : opError('commit_lock_busy', `The checkout's commit lock could not be taken (${error instanceof Error ? error.message : String(error)}); nothing moved.`, `Retry gbrain sources refresh ${sourceId}.`, { retryable: true })));
+ try {
+ const head = await headOf(git, plan.root);
+ if (head !== row.old_head) {
+ if (head === null) throw await markRecoveryRequired(engine, current, head, plan.root);
+ await abort(engine, current, ['fenced'], refusal('refresh_source_changed',
+ `The checkout HEAD moved from ${row.old_head} to ${head} after the precheck (an external commit or checkout); nothing was merged.`, `Retry gbrain sources refresh ${sourceId}`));
+ }
+ const dirt = await dirtyOverlap(git, plan.root, row.old_head, row.target_head);
+ if (dirt.overlap.length) await abort(engine, current, ['fenced'], dirtyRefusal(sourceId, dirt.overlap));
+ let merge = await git(['-C', plan.root, 'merge', '--ff-only', '--no-edit', '--quiet', row.target_head], 120_000);
+ let after = await headOf(git, plan.root);
+ for (let attempt = 1; attempt < INDEX_LOCK_ATTEMPTS && merge.code !== 0 && after === row.old_head && INDEX_LOCKED.test(merge.stderr); attempt++) {
+ await new Promise(resolve => setTimeout(resolve, INDEX_LOCK_RETRY_MS * attempt));
+ merge = await git(['-C', plan.root, 'merge', '--ff-only', '--no-edit', '--quiet', row.target_head], 120_000);
+ after = await headOf(git, plan.root);
+ }
+ if (merge.code !== 0 || after !== row.target_head) {
+ const refused = merge.stderr.trim().split('\n')[0] || `exit ${merge.code}`;
+ if (after === row.old_head && INDEX_LOCKED.test(merge.stderr)) await abort(engine, current, ['fenced'], opError('git_index_locked',
+ `git merge --ff-only could not take the checkout's index lock (${refused}); HEAD is unchanged at ${row.old_head}.`,
+ `A git process outside gbrain's commit lock holds .git/index.lock. Retry gbrain sources refresh ${sourceId} once it exits; nothing moved.`, { retryable: true }));
+ if (after === row.old_head) await abort(engine, current, ['fenced'], refusal('refresh_dirty',
+ `git merge --ff-only refused (${refused}); HEAD is unchanged at ${row.old_head}.`,
+ `Commit or discard the paths git names (check gbrain sources writer status ${sourceId} --json for pending git effects), then retry gbrain sources refresh ${sourceId}.`));
+ throw await markRecoveryRequired(engine, current, after, plan.root);
+ }
+ } finally { await commitLock.release(); }
await hooks?.boundary?.('merged', current);
await bookkeeping(engine, current);
return readRefresh(engine, row.id);
diff --git a/test/worktree-refresh-index-lock-8117.test.ts b/test/worktree-refresh-index-lock-8117.test.ts
new file mode 100644
index 0000000000..1cbda0f780
--- /dev/null
+++ b/test/worktree-refresh-index-lock-8117.test.ts
@@ -0,0 +1,68 @@
+/**
+ * #8117: a refresh's fenced ff-merge and `gbrain git commit-push` used different locks, so a door commit holding
+ * .git/index.lock made the merge fail as refresh_dirty (caller-class) for a transient collision. The HEAD check through
+ * the merge now runs under the checkout's commit lock; a lockless git holding the index lock is retried briefly and then
+ * refused as retryable git_index_locked; a commit lock held past its wait is commit_lock_busy. Each refusal aborts the
+ * fenced row with HEAD unchanged.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { OperationError } from '../src/core/ops/contract.ts';
+import { acquireCommitLockAsync } from '../src/core/git/commit-push.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { refreshWorktree } from '../src/core/persistence/worktree-refresh.ts';
+import { page, withRefreshFixture } from './helpers/worktree-refresh-fixture.ts';
+import { withEnv } from './helpers/with-env.ts';
+
+let engine: PGLiteEngine;
+beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 120_000);
+afterAll(async () => { await disposePersistenceConsumer(engine as BrainEngine); await engine.disconnect(); });
+
+test('a door commit holding the commit lock and index.lock at the fence is waited out, and the refresh completes', () => withRefreshFixture(engine, async f => {
+ const target = f.push('alpha/two.md', page('Alpha two', 'Upstream side.'));
+ const indexLock = join(f.root, '.git', 'index.lock');
+ let done: Promise<void> | undefined;
+ const result = await refreshWorktree(f.engine, f.alpha, { hooks: { boundary: async point => {
+ if (point !== 'fenced') return;
+ const door = await acquireCommitLockAsync(f.root, 0);
+ writeFileSync(indexLock, '');
+ done = new Promise(resolve => setTimeout(async () => { rmSync(indexLock, { force: true }); await door.release(); resolve(); }, 1500));
+ } } });
+ await done;
+ expect(result.status).toBe('completed');
+ expect(f.head()).toBe(target);
+}), 120_000);
+
+test('a lockless git holding index.lock is refused as retryable git_index_locked, not refresh_dirty, and the next run completes', () => withRefreshFixture(engine, async f => {
+ const before = f.head();
+ const target = f.push('alpha/two.md', page('Alpha two', 'Upstream side.'));
+ const indexLock = join(f.root, '.git', 'index.lock');
+ const failure = await refreshWorktree(f.engine, f.alpha, { hooks: { boundary: point => { if (point === 'fenced') writeFileSync(indexLock, ''); } } })
+ .then(() => null, error => error).finally(() => rmSync(indexLock, { force: true }));
+ expect(failure).toBeInstanceOf(OperationError);
+ expect(failure.code).toBe('git_index_locked');
+ expect(failure.retryable).toBe(true);
+ const [row] = await f.refreshRows();
+ expect(row!.state).toBe('aborted');
+ expect(f.head()).toBe(before);
+ expect(existsSync(indexLock)).toBe(false);
+ expect((await refreshWorktree(f.engine, f.alpha)).status).toBe('completed');
+ expect(f.head()).toBe(target);
+}), 120_000);
+
+test('a commit lock held past its wait aborts the fenced refresh as commit_lock_busy with HEAD unchanged', () => withRefreshFixture(engine, async f => {
+ const before = f.head();
+ f.push('alpha/two.md', page('Alpha two', 'Upstream side.'));
+ let door: { release(): Promise<void> } | undefined;
+ const failure = await withEnv({ GBRAIN_COMMIT_LOCK_WAIT_SECONDS: '1', GBRAIN_PUSH_LOCK_WAIT_SECONDS: undefined }, () => refreshWorktree(f.engine, f.alpha,
+ { hooks: { boundary: async point => { if (point === 'fenced') door = await acquireCommitLockAsync(f.root, 0); } } }))
+ .then(() => null, error => error).finally(() => door?.release());
+ expect(failure).toBeInstanceOf(OperationError);
+ expect(failure.code).toBe('commit_lock_busy');
+ const [row] = await f.refreshRows();
+ expect(row!.state).toBe('aborted');
+ expect(f.head()).toBe(before);
+}), 120_000);