Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Read only the newest reflog entries and require an unbroken chain before aborting a refused-merge refresh

garrytan85f4504396d9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ec75ed7fa..6c4374fa56 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,9 +16,9 @@ identifiers and attribution are available in the pre-removal Git revision
### Itemized changes
-- `src/core/persistence/worktree-refresh.ts`: the update that marks `outcome.merge_started` also records `merge_started_at` (epoch ms, the refresher's clock). `recoverOne` aborts a `fenced` row `refresh_interrupted` when its merge started, HEAD descends from the start commit without the target, no member synced off HEAD, and the reflogs of HEAD and its branch (`reachedTargetSince`) show no move to the target since `merge_started_at` less 5 s. A missing, empty or unreadable reflog keeps `recovery_required`. `--abandon` lifts such a row the same way instead of marking it `recovery_required`.
+- `src/core/persistence/worktree-refresh.ts`: the update that marks `outcome.merge_started` also records `merge_started_at` (epoch ms, the refresher's clock). `recoverOne` aborts a `fenced` row `refresh_interrupted` when its merge started, HEAD descends from the start commit without the target, no member synced off HEAD, and the reflogs of HEAD and its branch (`reachedTargetSince`) show no move to the target since `merge_started_at` less 5 s. It reads at most the last 1 MiB of each reflog file and needs an unbroken old-to-new chain back past that time or to the log's first entry; a missing, empty or unreadable reflog, a gap in the chain or a tail that ends inside the window keeps `recovery_required`, and a reflog read git cannot finish leaves the row `fenced` for the next scan. Refresh git calls no longer inherit `GIT_COMMITTER_DATE`. `--abandon` lifts such a row the same way instead of marking it `recovery_required`.
- `spec/tla/refresh-barrier`: `RefusedAbortable` models the new recovery rule, `FfMerge` aborts a refused merge as the code has since #8765, and `RecoveryOnlyByPolicy` now allows `recovery_required` only for a merge that ran. The guard mutant `resume-marks-refused-merge-recovery` reverts the rule.
-- Tests: `test/persistence-worktree-refresh-restart.test.ts` SIGKILLs a real refresh process right after git refused its merge, on PGLite and Postgres: recovery aborts it, a write deferred behind it commits and the next refresh completes; with the reflog deleted, or with no `merge_started_at`, it stays `recovery_required`.
+- Tests: `test/persistence-worktree-refresh-restart.test.ts` SIGKILLs a real refresh process right after git refused its merge, on PGLite and Postgres: recovery aborts it, a write deferred behind it commits and the next refresh completes; with the reflog deleted, with no `merge_started_at`, after a merge that reached the target and was reset (also with those reflog entries expired), or with a reflog tail that holds nothing from before the merge, it stays `recovery_required`; a 32 MiB reflog still aborts, and a reflog read git cannot finish leaves the row `fenced`.
## [0.60.614.0] - 2026-11-08
diff --git a/docs/designs/REFRESH_WRITE_BARRIER.md b/docs/designs/REFRESH_WRITE_BARRIER.md
index 6870f302dd..820fa4369e 100644
--- a/docs/designs/REFRESH_WRITE_BARRIER.md
+++ b/docs/designs/REFRESH_WRITE_BARRIER.md
@@ -296,8 +296,12 @@ Deferred rows are durable rows; nothing about them lives in process memory.
- Killed after the merge started but before HEAD reached the target (a commit landed on `old_head`
right before the merge, so git refused the fast-forward): the row also records
`outcome.merge_started_at`, and when the reflogs of HEAD and its branch show no move to the target
- since then, recovery aborts the row the same way and keeps that commit (GST-1674). Without a
- readable reflog, or on a row an older version wrote, it stays `recovery_required`.
+ since then, recovery aborts the row the same way and keeps that commit (GST-1674). It reads the
+ last 1 MiB of each reflog file and needs an unbroken old-to-new chain from HEAD back past the merge
+ start (or to the log's first entry). Without a readable reflog, with a gap in the chain, with a
+ tail that ends inside that window, or on a row an older version wrote, it stays `recovery_required`.
+ A reflog read git cannot finish leaves the row `fenced` for the next scan. Refresh git calls
+ drop `GIT_COMMITTER_DATE`, so the merge's reflog entry carries the clock recovery compares with.
- Killed after the merge, with HEAD at the target or a commit on top of it and no member synced off
it: recovery records the merge and the next refresh finishes the member syncs, with no `--resume`.
- A merge that ran and a HEAD that no longer holds the target (a reset and an unrelated commit)
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index 028b652f20..31efcc9cb3 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -181,10 +181,15 @@ async function movedBeforeMerge(engine: BrainEngine, git: Git, root: string, row
}
/** Reflog timestamps have one-second resolution, so an entry written just after merge_started_at can read up to a second before it. */
const REFLOG_SLACK_MS = 5_000;
+/** The most of each reflog file recovery reads: its newest entries, which a recent merge start falls inside. */
+const REFLOG_TAIL_BYTES = 1024 ** 2;
/**
- * GST-1674: whether the reflogs of HEAD and the branch it names record a move to the target at or after `sinceMs` (less REFLOG_SLACK_MS):
- * true or false, or null when git fails or either reflog is missing, empty or does not end at `head` (core.logAllRefUpdates off, a deleted log).
- * A git call that does not finish within its bound or cannot start throws git_unavailable instead, so the row stays and a later run retries it.
+ * GST-1674: whether the reflogs of HEAD and the branch it names record a move to the target at or after `sinceMs` (less REFLOG_SLACK_MS).
+ * Each reflog file's last REFLOG_TAIL_BYTES are read raw and walked newest first; every entry's new value must equal the next entry's old
+ * value, back to an entry older than the window or to the log's first entry (a creation from zeros). It answers true or false only then,
+ * and null on any doubt: no readable log (core.logAllRefUpdates off, a deleted log, reftable), a log that does not end at `head`, a gap in
+ * the chain (entries expired out of the middle), or a tail that ends inside the window. A git call that does not finish within its bound or
+ * cannot start throws git_unavailable instead, so the row stays and a later run retries it.
*/
async function reachedTargetSince(git: Git, root: string, row: WorktreeRefreshRow, head: string, sinceMs: number): Promise<boolean | null> {
const read = async (args: string[]) => {
@@ -197,11 +202,30 @@ async function reachedTargetSince(git: Git, root: string, row: WorktreeRefreshRo
const branch = await read(['symbolic-ref', '-q', 'HEAD']);
if (branch.code !== 0 && branch.code !== 1) return null;
for (const ref of ['HEAD', ...(branch.code === 0 ? [branch.stdout.trim()] : [])]) {
- const out = await read(['log', '-g', '--format=%H %gd', '--date=unix', ref, '--']);
- if (out.code !== 0) return null;
- const entries = out.stdout.split('\n').filter(Boolean).map(line => /^([0-9a-f]{40,64}) \S*@\{(\d+)\}$/.exec(line));
- if (!entries.length || entries.some(entry => !entry) || entries[0]![1] !== head) return null;
- if (entries.some(entry => entry![1] === row.target_head && Number(entry![2]) * 1000 >= sinceMs - REFLOG_SLACK_MS)) return true;
+ const path = await read(['rev-parse', '--path-format=absolute', '--git-path', `logs/${ref}`]);
+ if (path.code !== 0) return null;
+ let text: string, whole: boolean;
+ try {
+ const fd = openSync(path.stdout.trim(), 'r');
+ try {
+ const size = fstatSync(fd).size, tail = Buffer.alloc(Math.min(size, REFLOG_TAIL_BYTES));
+ readSync(fd, tail, 0, tail.length, size - tail.length);
+ text = tail.toString('utf8'); whole = tail.length === size;
+ } finally { closeSync(fd); }
+ } catch { return null; }
+ const lines = text.split('\n');
+ if (!whole) lines.shift();
+ const entries = lines.filter(Boolean).map(line => /^([0-9a-f]{40,64}) ([0-9a-f]{40,64}) .*> (\d+) [+-]\d{4}(?:\t|$)/.exec(line));
+ if (!entries.length || entries.some(entry => !entry) || entries.at(-1)![2] !== head) return null;
+ let complete = false;
+ for (let i = entries.length - 1; i >= 0 && !complete; i--) {
+ const [, old, now, at] = entries[i]!;
+ if (i < entries.length - 1 && now !== entries[i + 1]![1]) return null;
+ if (Number(at) * 1000 < sinceMs - REFLOG_SLACK_MS) complete = true;
+ else if (now === row.target_head) return true;
+ else if (i === 0 && whole && /^0+$/.test(old!)) complete = true;
+ }
+ if (!complete) return null;
}
return false;
}
@@ -257,7 +281,10 @@ function inProgress(cause: string, sourceId: string, refreshId?: string): Operat
}
const q = (value: string) => /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
-/** Hardened git: no prompts, no user hooks, untranslated output, bounded. */
+/**
+ * Hardened git: no prompts, no user hooks, untranslated output, bounded. GST-1674: no inherited GIT_COMMITTER_DATE, so the reflog entries
+ * the refresh writes carry the clock recovery compares merge_started_at with.
+ */
async function withGit<T>(run: (git: (args: string[], timeoutMs?: number) => Promise<{ stdout: string; stderr: string; code: number; timedOut: boolean }>) => Promise<T>): Promise<T> {
const base = join(persistenceHome(), 'empty-hooks');
mkdirSync(base, { recursive: true, mode: 0o700 });
@@ -265,7 +292,7 @@ async function withGit<T>(run: (git: (args: string[], timeoutMs?: number) => Pro
try {
return await run(async (args, timeoutMs = 30_000) => {
const { error, stdout, stderr } = await execFileBounded('git', ['-c', 'core.quotepath=false', '-c', `core.hooksPath=${hooks}`, ...args],
- { timeout: timeoutMs, maxBuffer: 32 * 1024 ** 2, env: gitChildEnv(GIT_ENV) });
+ { timeout: timeoutMs, maxBuffer: 32 * 1024 ** 2, env: { ...gitChildEnv(GIT_ENV), GIT_COMMITTER_DATE: undefined } });
const timedOut = !!error && (error.killed || typeof error.code !== 'number');
return { stdout, stderr, code: error ? (typeof error.code === 'number' ? error.code : -1) : 0, timedOut };
});
diff --git a/test/persistence-worktree-refresh-restart.test.ts b/test/persistence-worktree-refresh-restart.test.ts
index 7b2dd49031..f44320fad6 100644
--- a/test/persistence-worktree-refresh-restart.test.ts
+++ b/test/persistence-worktree-refresh-restart.test.ts
@@ -19,7 +19,7 @@
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
@@ -171,9 +171,32 @@ test('GST-1674: a refresh killed after git refused its fast-forward recovers by
});
}, 300_000);
-test('GST-1674: the same crash stays recovery_required when the reflog is gone, the row predates merge_started_at, or HEAD reached the target and was reset', async () => {
- for (const doubt of ['reflog', 'started_at', 'reset'] as const) for (const index of cases.keys()) await withRefusedMergeKill(index, async ({ f, target, foreign }) => {
- if (doubt === 'reflog') {
+/**
+ * Rewrites the HEAD reflog to hold over 32 MiB of earlier entries dated `at` (epoch seconds), chained into
+ * the real ones: the log's creation entry now starts from the first commit, which a backfilled creation entry from zeros makes first.
+ */
+function backfillHeadReflog(f: RefreshFixture, at: number): void {
+ const log = join(f.root, '.git', 'logs', 'HEAD');
+ const real = readFileSync(log, 'utf8').split('\n').filter(Boolean);
+ const first = real[0]!.split(' ')[1]!;
+ real[0] = `${first} ${real[0]!.slice(real[0]!.indexOf(' ') + 1)}`;
+ const line = `${first} ${first} Example <[email protected]> ${at} +0000\tbackfill\n`;
+ writeFileSync(log, `${'0'.repeat(first.length)} ${first} Example <[email protected]> ${at} +0000\tbackfill\n${line.repeat(Math.ceil(33 * 1024 ** 2 / line.length))}${real.join('\n')}\n`);
+}
+
+test('GST-1674: the same crash stays recovery_required when the reflog is gone, the row predates merge_started_at, HEAD reached the target and was reset (also onto another commit with those entries expired), or the reflog tail holds no entry from before the merge', async () => {
+ for (const doubt of ['reflog', 'started_at', 'reset', 'expired', 'recent'] as const) for (const index of cases.keys()) await withRefusedMergeKill(index, async ({ f, old, target, foreign, orphan }) => {
+ if (doubt === 'recent') {
+ backfillHeadReflog(f, Math.floor(orphan.outcome.merge_started_at / 1000));
+ } else if (doubt === 'expired') {
+ git(f.root, 'branch', 'keep-foreign', foreign);
+ git(f.root, 'reset', '-q', '--hard', target);
+ git(f.root, 'reset', '-q', '--hard', old);
+ git(f.root, '-c', 'user.name=Example', '-c', '[email protected]', '-c', 'commit.gpgsign=false', 'commit', '-q', '--allow-empty', '-m', 'after reset');
+ for (const ref of git(f.root, 'for-each-ref', '--format=%(refname)', 'refs/remotes').split('\n').filter(Boolean)) git(f.root, 'update-ref', '-d', ref);
+ git(f.root, 'reflog', 'expire', '--expire-unreachable=all', '--all');
+ expect(git(f.root, 'log', '-g', '--format=%H', 'HEAD', '--').split('\n')).not.toContain(target);
+ } else if (doubt === 'reflog') {
git(f.root, 'config', 'core.logAllRefUpdates', 'false');
rmSync(join(f.root, '.git', 'logs'), { recursive: true, force: true });
} else if (doubt === 'reset') {
@@ -184,9 +207,19 @@ test('GST-1674: the same crash stays recovery_required when the reflog is gone,
}
await resumeWorktreeRefreshes(f.engine);
const [row] = await f.refreshRows() as Row[];
+ const head = doubt === 'expired' ? f.head() : foreign;
expect([doubt, row!.state]).toEqual([doubt, 'recovery_required']);
- expect(row!.outcome.observed_head).toBe(foreign);
- expect(f.head()).toBe(foreign);
+ expect(row!.outcome.observed_head).toBe(head);
+ expect(f.head()).toBe(head);
+ });
+}, 300_000);
+
+test('GST-1674: a HEAD reflog file over 32 MiB still lets recovery abort the crash, reading only its newest entries', async () => {
+ for (const index of cases.keys()) await withRefusedMergeKill(index, async ({ f, foreign, orphan }) => {
+ backfillHeadReflog(f, Math.floor(orphan.outcome.merge_started_at / 1000) - 3600);
+ await resumeWorktreeRefreshes(f.engine);
+ const [row] = await f.refreshRows() as Row[];
+ expect([row!.state, row!.outcome.observed_head]).toEqual(['aborted', foreign]);
});
}, 300_000);
@@ -194,7 +227,7 @@ test('GST-1674: a reflog read that git cannot finish leaves the crash fenced for
for (const index of cases.keys()) await withRefusedMergeKill(index, async ({ f, foreign }) => {
const bin = join(f.root, '..', 'wedged-git');
mkdirSync(bin, { recursive: true });
- writeFileSync(join(bin, 'git'), `#!/bin/sh\nfor a in "$@"; do if [ "$a" = "-g" ]; then kill -9 $$; fi; done\nPATH='${process.env.PATH}' exec git "$@"\n`, { mode: 0o755 });
+ writeFileSync(join(bin, 'git'), `#!/bin/sh\nfor a in "$@"; do if [ "$a" = "--git-path" ]; then kill -9 $$; fi; done\nPATH='${process.env.PATH}' exec git "$@"\n`, { mode: 0o755 });
const errors: string[] = [];
const consoleError = console.error;
console.error = (...args: unknown[]) => { errors.push(args.join(' ')); };