Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(refresh): --resume never finishes at a HEAD a member synced past; writer status names the commit the refusal names

garrytanf79fe6640086
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e6eeb7f1b..88422df734 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,12 +14,12 @@ identifiers and attribution are available in the pre-removal Git revision
**`gbrain sources refresh --abandon` no longer lets the next sync delete pages a member source already synced.**
-A refresh interrupted after a member source synced the upstream commit, then moved to `recovery_required` with the checkout back at the commit it started from, could be abandoned: `--resume` refused and named `--abandon`, `--abandon` lifted the fence, and the next sync diffed that member back to the start commit and soft-deleted every page it had synced. `--abandon` now refuses such a row (`refresh_recovery_required`, nothing changed) once any member's `last_commit` is past the start commit (set, and neither that commit nor an ancestor of it; a commit git cannot find counts as past), and `--resume` no longer names `--abandon` there. Both name the one way out that keeps the pages, as an ask-the-user fix: preview with `git -C <checkout> status --short`, fast-forward the checkout with `git merge --ff-only` to the commit the members synced (the upstream commit, or a later one a member already synced), then `--resume`; when git refuses, `git reset --hard` to that commit is named as the destructive fallback. `--resume` now also finishes a `recovery_required` refresh whose HEAD descends from the upstream commit instead of refusing it. Writer status uses the same member check. A row whose members never moved past the start commit is abandoned exactly as before, and sync's deletion behaviour is unchanged.
+A refresh interrupted after a member source synced the upstream commit, then moved to `recovery_required` with the checkout back at the commit it started from, could be abandoned: `--resume` refused and named `--abandon`, `--abandon` lifted the fence, and the next sync diffed that member back to the start commit and soft-deleted every page it had synced. `--abandon` now refuses such a row (`refresh_recovery_required`, nothing changed) once any member's `last_commit` is past the start commit (set, and neither that commit nor an ancestor of it; a commit git cannot find counts as past), and `--resume` no longer names `--abandon` there. Both name the one way out that keeps the pages, as an ask-the-user fix: preview with `git -C <checkout> status --short`, fast-forward the checkout with `git merge --ff-only` to the commit the members synced (the upstream commit, or a later one a member already synced), then `--resume`; when git refuses, `git reset --hard` to that commit is named as the destructive fallback. `--resume` now also finishes a `recovery_required` refresh whose HEAD descends from the upstream commit instead of refusing it, and never finishes one at a HEAD a member source already synced past. Writer status uses the same member check. A row whose members never moved past the start commit is abandoned exactly as before, and sync's deletion behaviour is unchanged.
### Itemized changes
- `src/core/persistence/worktree-refresh.ts`: one member check (`membersPastStart`) feeds `--abandon`, the `--resume` refusal at the start commit, the stored `recovery_required` fix and writer status.
-- Tests: `test/persistence-worktree-refresh.test.ts` 7r (the three-step chain: crash while syncing, member synced, HEAD reset; pages survive, then reset-to-target and `--resume` completes) 7s (no member moved: `--abandon` still works) 7t (a member behind the start commit still abandons; an unknown commit refuses), 7u (a member synced past the target keeps its pages) and 7v (an unrelated HEAD names no `--abandon`; a HEAD past the target resumes), on PGLite and on Postgres through `test/e2e/worktree-refresh-postgres.test.ts`.
+- Tests: `test/persistence-worktree-refresh.test.ts` 7r (the three-step chain: crash while syncing, member synced, HEAD reset; pages survive, then reset-to-target and `--resume` completes) 7s (no member moved: `--abandon` still works) 7t (a member behind the start commit still abandons; an unknown commit refuses), 7u (a member synced past the target keeps its pages), 7w (`--resume` never finishes at a HEAD a member synced past) and 7v (an unrelated HEAD names no `--abandon`; a HEAD past the target resumes), on PGLite and on Postgres through `test/e2e/worktree-refresh-postgres.test.ts`.
## [0.60.583.0] - 2026-11-05
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index ffcbb28e3e..0f43b81a0e 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -130,6 +130,13 @@ async function keepPagesHead(engine: BrainEngine, row: Pick<WorktreeRefreshRow,
return head;
}).catch(() => row.target_head);
}
+/** GST-1457: a member whose last_commit strictly descends from HEAD; finishing the refresh there would let that member's next sync roll it back to HEAD. */
+async function memberAheadOf(engine: BrainEngine, git: Git, root: string, row: Pick<WorktreeRefreshRow, 'source_ids'>, head: string): Promise<boolean> {
+ for (const member of await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id = ANY($1::text[])', [row.source_ids])) {
+ if (member.last_commit && member.last_commit !== head && await isAncestor(git, root, head, member.last_commit)) return true;
+ }
+ return false;
+}
const keepSyncedWayOut = (row: Pick<WorktreeRefreshRow, 'source_ids'>, root: string, head: string) =>
`Ask the user first: git -C ${q(root)} merge --ff-only ${head} moves the checkout to the commit its members already synced (it keeps uncommitted edits git can carry; git -C ${q(root)} status --short lists them), then gbrain sources refresh ${row.source_ids[0]} --resume finishes the refresh and keeps the pages its members synced. If git refuses (an uncommitted edit overlaps an incoming file, or HEAD is not an ancestor of ${head}), ask the user before git -C ${q(root)} reset --hard ${head}, which discards local commits and uncommitted edits not in it, then --resume.`;
/** GST-1457: the refusal when a member synced past old_head; its fix fast-forwards to the commit the members synced (ask_user, preview first), then --resume. */
@@ -899,7 +906,7 @@ async function recoverOne(engine: BrainEngine, git: Git, row: WorktreeRefreshRow
} else if (row.state === 'fenced' && head === row.old_head) {
await engine.transaction(tx => transition(tx, row, ['fenced'], 'aborted', { refusal: { code: 'refresh_interrupted', cause: 'The refreshing process stopped before merging; HEAD is unchanged.' } }));
} else if (['fenced', 'merged', 'recovery_required'].includes(row.state) && (head === row.target_head || (row.state === 'recovery_required' && head !== null && await isAncestor(git, root, row.target_head, head)))
- && await isAncestor(git, root, row.old_head, row.target_head)) {
+ && await isAncestor(git, root, row.old_head, row.target_head) && !await memberAheadOf(engine, git, root, row, head!)) {
await bookkeeping(engine, row);
} else if (row.state === 'syncing' && head !== null && (head === row.target_head || await isAncestor(git, root, row.target_head, head))) {
// stays syncing; the member syncs run from --resume or any later cycle sync.
@@ -1154,17 +1161,18 @@ export async function refreshHolderReport(engine: BrainEngine, row: Pick<Worktre
// #7712, #7731: what the next step does depends on the checkout HEAD, read on the host that holds the checkout.
const head = binding?.local_path ? await withGit(git => headOf(git, binding.local_path!)).catch(() => null) : undefined;
if (row.state === 'recovery_required') {
- if (head === row.target_head) return { ...base, auto_recovery: 'none', fix: { argv: resume, consent: [], actor: 'agent', requires_exclusive: false, verify,
+ const keep = binding?.local_path ? await keepPagesHead(engine, row, binding.local_path) : row.target_head;
+ if (head === row.target_head && keep === row.target_head) return { ...base, auto_recovery: 'none', fix: { argv: resume, consent: [], actor: 'agent', requires_exclusive: false, verify,
why: `Refresh ${row.id} stopped without verifying the checkout HEAD, which is now the refresh target ${row.target_head}, so --resume records the merge and finishes the refresh; nothing needs resetting.` } };
const moved = await membersPastStart(engine, row, binding?.local_path);
if (head === row.old_head && !moved.length) return { ...base, auto_recovery: 'none', fix: { argv: ['gbrain', 'sources', 'refresh', source, '--abandon'], consent: [], actor: 'agent', requires_exclusive: false, verify,
why: `Refresh ${row.id} stopped without verifying the checkout HEAD, which is back at the pre-refresh commit ${row.old_head}, so --abandon lifts the fence and nothing moved; then gbrain sources refresh ${source} starts again.` } };
if (head === row.old_head) return { ...base, auto_recovery: 'none', fix: { argv: resume, consent: [], actor: 'agent', requires_exclusive: false, verify,
- why: `Refresh ${row.id} stopped with the checkout back at the pre-refresh commit ${row.old_head}, but ${moved.join(', ')} already synced past it, so --abandon refuses (the next sync would roll those pages back). --resume refuses too and names the one way out that keeps them: fast-forward the checkout to the refresh target ${row.target_head} (ask the user first), then --resume.` } };
+ why: `Refresh ${row.id} stopped with the checkout back at the pre-refresh commit ${row.old_head}, but ${moved.join(', ')} already synced past it, so --abandon refuses (the next sync would roll those pages back). --resume refuses too and names the one way out that keeps them: fast-forward the checkout to ${keep}, the commit those members synced toward (ask the user first), then --resume.` } };
if (moved.length) return { ...base, auto_recovery: 'none', fix: { argv: resume, consent: [], actor: 'agent', requires_exclusive: false, verify,
- why: `Refresh ${row.id} could not verify the checkout HEAD, and ${moved.join(', ')} already synced past the start commit ${row.old_head}, so nothing recovers it on its own and --abandon refuses. --resume changes nothing here: it prints the one way out that keeps those pages (move the checkout to the refresh target ${row.target_head}, then --resume); ask the user first.` } };
+ why: `Refresh ${row.id} could not verify the checkout HEAD, and ${moved.join(', ')} already synced past the start commit ${row.old_head}, so nothing recovers it on its own and --abandon refuses. --resume finishes it once HEAD is ${keep} or descends from it, and until then prints the one way out that keeps those pages (move the checkout to ${keep}, then --resume); ask the user first.` } };
return { ...base, auto_recovery: 'none', fix: { argv: resume, consent: [], actor: 'agent', requires_exclusive: false, verify,
- why: `Refresh ${row.id} could not verify the checkout HEAD, so nothing recovers it on its own. --resume changes nothing here: it prints the two ways out (reset to the start commit and --abandon, or to the upstream commit and --resume); resetting is destructive, so ask the user first.` } };
+ why: `Refresh ${row.id} could not verify the checkout HEAD, so nothing recovers it on its own. --resume finishes it once HEAD is the refresh target or descends from it, and otherwise prints the two ways out (reset to the start commit and --abandon, or to the upstream commit and --resume); resetting is destructive, so ask the user first.` } };
}
if (liveness === 'live') return { ...base, auto_recovery: 'none', fix: null };
if (binding && (binding.state !== 'active' || await worktreeRecoveryPending(engine, binding))) return { ...base, auto_recovery: 'none', fix: { argv: verify.argv, consent: [], actor: 'agent', requires_exclusive: false, verify,
diff --git a/test/persistence-worktree-refresh.test.ts b/test/persistence-worktree-refresh.test.ts
index ede190b4db..75b18d7ba5 100644
--- a/test/persistence-worktree-refresh.test.ts
+++ b/test/persistence-worktree-refresh.test.ts
@@ -837,6 +837,31 @@ test('7v. GST-1457 review: at an unrelated HEAD with a member synced, writer sta
expect((await livePages(f, f.alpha)).filter(slug => /two|four/.test(slug)).length).toBe(2);
}), 180_000);
+test('7w. GST-1457 fix-check: --resume never finishes a refresh at a HEAD a member already synced past, and writer status names that member\'s commit', () => each(async f => {
+ // Value: protects=recoverOne refuses to record the merge while a member's last_commit strictly descends from HEAD, so fast-forwarding only to
+ // the target (not the commit 7u's fix names) leaves the fence up instead of completing and letting the next sync roll the member back;
+ // writer status names the same commit as the refusal; fails_when=recoverOne accepts HEAD == target_head without the member check, or writer
+ // status names target_head; why_new=7u follows the named fix exactly; seam=7u's setup with the operator stopping at the target;
+ // no_claim=a member that diverged from HEAD (not a descendant).
+ const target = f.push('alpha/two.md', page('Alpha two', 'Synced to the target.'));
+ const old = f.head();
+ await orphanAt(f, 'syncing', 'syncing');
+ const past = commitFile(f.root, 'alpha/three.md', page('Alpha three', 'Landed on top of the target while syncing.'));
+ await performManagedSync(f.engine, { sourceId: f.alpha, noPull: true, noEmbed: true });
+ const synced = await livePages(f, f.alpha);
+ git(f.root, 'reset', '-q', '--hard', old);
+ await refusedWith(refreshWorktree(f.engine, f.alpha, { resume: true }), 'refresh_recovery_required');
+ const status = await writerStatusRow(f);
+ expect(status.fix.why).toContain(past);
+ git(f.root, 'merge', '-q', '--ff-only', target);
+ const atTarget = await settle(refreshWorktree(f.engine, f.alpha, { resume: true }));
+ await settle(performManagedSync(f.engine, { sourceId: f.alpha, noPull: true, noEmbed: true }));
+ expect(await livePages(f, f.alpha)).toEqual(synced);
+ expect(atTarget.error?.code).toBe('refresh_recovery_required');
+ expect((await writerStatusRow(f)).fix.why).not.toContain('records the merge and finishes the refresh');
+ expect((await f.refreshRows()).map(r => r.state)).toEqual(['recovery_required']);
+}), 180_000);
+
test('8. a queued git effect drains before fenced, and nothing on the worktree is claimed while fenced', () => each(async f => {
f.push('alpha/two.md', page('Alpha two', 'Upstream.'));
await f.put(f.beta, 'notes/effect', page('Effect', 'Has a git effect.'));