Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (refresh never publishes over a rewritten upstream, #7686)

garrytandb06d9ba6cee
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 860e65a85d..8d5b44c2c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,7 @@ gbrain config set sources.refresh_publish_diverged true
| Diverged checkout, setting off (the default) | refused `refresh_diverged` | unchanged; the refusal now also names the setting |
| A file both sides changed, setting on | n/a | refuses `integrate_conflict` naming the file; nothing is pushed, fenced or moved. With `gbrain.quarantine` on, the remote's version is published instead and the refresh names the ref that keeps this machine's version |
| An uncommitted edit to a file the upstream changed, setting on | n/a | refuses `refresh_dirty` before anything is pushed |
+| An upstream rewritten by a force-push (it no longer holds a commit it held before), or no record of the upstream before the fetch, setting on | n/a | refuses `refresh_diverged` and pushes nothing, so the commits the rewrite removed never come back without the user |
| A refusal after the publish landed | n/a | the refusal says the remote already holds the local commits |
| `--dry-run` | refused `refresh_diverged` | unchanged: a dry run never publishes |
| `gbrain config set sources.refresh_fetch_timeout_ms` / `sources.refresh_drain_wait_ms` | refused as an unknown key, although the refresh reads both | accepted |
@@ -44,7 +45,7 @@ gbrain config set sources.refresh_publish_diverged true
### Itemized changes
-- `src/core/persistence/worktree-refresh.ts`: when `sources.refresh_publish_diverged` is on and the run is not a dry run, the precheck runs the keep-checkout publish (`gbrain git commit-push --push-only --keep-checkout` in a bounded child, never on the PGLite owner's event loop) for a diverged checkout (after refusing `refresh_dirty` first when an uncommitted edit touches a file the upstream changed), re-fetches and continues; the result carries `published` (with any quarantined or superseded paths, which the text output names), and a refusal after the publish says the remote already holds the local commits. The `refresh_diverged` suggestion names the setting.
+- `src/core/persistence/worktree-refresh.ts`: when `sources.refresh_publish_diverged` is on and the run is not a dry run, the precheck runs the keep-checkout publish (`gbrain git commit-push --push-only --keep-checkout` in a bounded child, never on the PGLite owner's event loop) for a diverged checkout (after refusing `refresh_dirty` first when an uncommitted edit touches a file the upstream changed), re-fetches and continues; it refuses `refresh_diverged` instead when the checkout holds a commit the upstream held before (its remote-tracking reflog or a completed refresh's target) but no longer contains, or when neither record exists; the result carries `published` (with any quarantined or superseded paths, which the text output names), and a refusal after the publish says the remote already holds the local commits. The `refresh_diverged` suggestion names the setting.
- `src/commands/sources-refresh.ts`: a text line for the publish.
- `src/core/config-runtime-keys.ts`: registers `sources.refresh_publish_diverged`, `sources.refresh_fetch_timeout_ms` and `sources.refresh_drain_wait_ms`.
- Docs: `docs/guides/live-sync.md`, `docs/guides/write-refusals.md`, `docs/guides/troubleshooting.md`, `docs/guides/shared-checkout-git.md`, `docs/architecture/canonical-writers.md` and its census.
diff --git a/docs/guides/live-sync.md b/docs/guides/live-sync.md
index 4fd28b9a72..e108f7a023 100644
--- a/docs/guides/live-sync.md
+++ b/docs/guides/live-sync.md
@@ -691,7 +691,8 @@ vars — incident-time escape hatches, not everyday knobs.
on, the remote's version is published, this machine's is kept under
`refs/gbrain/quarantine/`, and the refresh says so), an uncommitted edit to a
file the upstream changed refuses `refresh_dirty` before anything is pushed,
- and `--dry-run` never publishes.
+ an upstream rewritten by a force-push (or one gbrain has no earlier record
+ of) still refuses `refresh_diverged`, and `--dry-run` never publishes.
**Say to your agent:** *"Bring my notes source up to date with its remote."*
diff --git a/docs/guides/shared-checkout-git.md b/docs/guides/shared-checkout-git.md
index f2ffc444d4..f96093bdd5 100644
--- a/docs/guides/shared-checkout-git.md
+++ b/docs/guides/shared-checkout-git.md
@@ -272,7 +272,7 @@ commits come in. Four rules keep that checkout able to move:
(automations committing alongside a sibling checkout that pushes the same
branch), the user can turn on `sources.refresh_publish_diverged` (default
off) so each refresh runs that publish itself
- ([live sync](live-sync.md)).
+ ([live sync](live-sync.md)); it never publishes over a rewritten upstream.
3. **Stop syncing a source before rewriting its history.** Before a
force-push or `git filter-repo`, run `gbrain sources set-sync <id> off`
(with the user's agreement) so automatic sync skips it, and
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index feab39f780..c6c4cc04f2 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -548,7 +548,7 @@ this anchor (`--json` puts them in one object on stdout); the command exits 1.
| <a id="refresh_no_upstream"></a>`refresh_no_upstream` | `refresh_no_upstream` | The checkout's branch tracks no upstream, HEAD is detached, or the checkout is not a Git checkout at all (gbrain never initializes Git on its own), so there is nothing to fast-forward to. | `git -C <checkout> branch --set-upstream-to <remote>/<branch>` (the fix fills in the real values), then retry. A checkout that is not Git has nothing to refresh; making it a clone with an upstream is the user's call. |
| <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. With `sources.refresh_publish_diverged` set to `true` (the user's standing consent, default off), the refresh runs that publish itself, in a child process that skips the pre-push hook, and then fast-forwards; a conflicting file then refuses `integrate_conflict` (with `gbrain.quarantine` on, the remote's version is published instead, this machine's is kept under `refs/gbrain/quarantine/`, and the refresh says so), and an uncommitted edit to a file the upstream changed refuses `refresh_dirty`, both with nothing pushed. |
+| <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. With `sources.refresh_publish_diverged` set to `true` (the user's standing consent, default off), the refresh runs that publish itself, in a child process that skips the pre-push hook, and then fast-forwards; a conflicting file then refuses `integrate_conflict` (with `gbrain.quarantine` on, the remote's version is published instead, this machine's is kept under `refs/gbrain/quarantine/`, and the refresh says so), and an uncommitted edit to a file the upstream changed refuses `refresh_dirty`, both with nothing pushed. The setting never publishes over a rewritten upstream: when the checkout holds a commit the upstream held before but no longer contains (a force-push), or gbrain has no record of the upstream before the fetch, the refresh still refuses `refresh_diverged` and the user decides. |
| <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="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. |
diff --git a/llms-full.txt b/llms-full.txt
index 8b13960293..fb4a8bcad1 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -7427,7 +7427,8 @@ vars — incident-time escape hatches, not everyday knobs.
on, the remote's version is published, this machine's is kept under
`refs/gbrain/quarantine/`, and the refresh says so), an uncommitted edit to a
file the upstream changed refuses `refresh_dirty` before anything is pushed,
- and `--dry-run` never publishes.
+ an upstream rewritten by a force-push (or one gbrain has no earlier record
+ of) still refuses `refresh_diverged`, and `--dry-run` never publishes.
**Say to your agent:** *"Bring my notes source up to date with its remote."*
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index 9d1f972cd5..1588335b07 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -286,6 +286,14 @@ async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTi
`git -C ${q(root)} fetch ${remote || 'origin'}, then gbrain sources refresh ${sourceId}`);
if (oldHead !== targetHead && !await isAncestor(git, root, oldHead, targetHead)) {
if (!publishDiverged) throw await divergedRefusal(git, root, sourceId, upstreamRef, oldHead, targetHead);
+ const upstreamFull = (await read(['rev-parse', '--symbolic-full-name', '@{upstream}'])).stdout.trim();
+ const heldUpstream = new Set([...(await read(['log', '-g', '-n', '1000', '--format=%H', upstreamFull, '--'], 128)).stdout.split('\n'),
+ ...(await engine.executeRaw<{ target_head: string }>(`SELECT target_head FROM persistence_worktree_refreshes WHERE worktree_id=$1::uuid AND state='completed' ORDER BY created_at DESC LIMIT 100`, [binding.worktree_id])).map(r => r.target_head)]
+ .map(sha => sha.trim()).filter(Boolean));
+ const removed = (await read(['rev-list', `${targetHead}..${oldHead}`])).stdout.split('\n').map(sha => sha.trim()).find(sha => heldUpstream.has(sha));
+ if (!heldUpstream.size || removed) throw await divergedRefusal(git, root, sourceId, upstreamRef, oldHead, targetHead, removed
+ ? `${upstreamRef} no longer contains ${removed}, which it held before: its history was rewritten (a force-push), and publishing would merge back the commits the rewrite removed.`
+ : `gbrain has no record of what ${upstreamRef} held before this fetch, so it cannot tell a force-push from local commits.`);
const base = (await read(['merge-base', oldHead, targetHead], 1)).stdout.trim() || oldHead;
const incoming = await dirtyOverlap(git, root, base, targetHead);
if (incoming.overlap.length) throw dirtyRefusal(sourceId, incoming.overlap);
@@ -332,16 +340,17 @@ async function publishInChild(root: string, sourceId: string): Promise<{ sha: st
* upstream into HEAD in memory and pushes the merge (refusing on a conflict, never touching the checkout), after which HEAD
* is an ancestor of the upstream and the refresh fast-forwards. It publishes the local commits, so the user decides.
*/
-async function divergedRefusal(git: Git, root: string, sourceId: string, upstreamRef: string, oldHead: string, targetHead: string): Promise<OperationError> {
+async function divergedRefusal(git: Git, root: string, sourceId: string, upstreamRef: string, oldHead: string, targetHead: string, rewrite?: string): Promise<OperationError> {
const count = Number((await git(['-C', root, 'rev-list', '--count', `${targetHead}..${oldHead}`])).stdout.trim()) || 0;
const local = count ? `${count} local commit(s)` : 'the local commits';
const argv = ['gbrain', 'git', 'commit-push', '--push-only', '--keep-checkout', '--path', root, '--json'];
const error = refusal('refresh_diverged',
- `The checkout HEAD ${oldHead} is not an ancestor of ${upstreamRef} (${targetHead}); a fast-forward is impossible and nothing changed.`,
- `Publish ${local} merged with ${upstreamRef}: ${argv.map(q).join(' ')} (it merges in memory, refuses on a conflict and never moves the checkout), then retry gbrain sources refresh ${sourceId}. Ask the user first, because it pushes those commits (git -C ${q(root)} log --stat ${upstreamRef}..HEAD lists them). gbrain sources reclone ${sourceId} replaces the checkout instead and drops them. To let every refresh publish a diverged checkout this way on its own, the user can run gbrain config set ${REFRESH_PUBLISH_DIVERGED_KEY} true.`);
+ `The checkout HEAD ${oldHead} is not an ancestor of ${upstreamRef} (${targetHead}); a fast-forward is impossible and nothing changed.${rewrite ? ` ${rewrite} ${REFRESH_PUBLISH_DIVERGED_KEY} does not publish it on its own.` : ''}`,
+ `Publish ${local} merged with ${upstreamRef}: ${argv.map(q).join(' ')} (it merges in memory, refuses on a conflict and never moves the checkout), then retry gbrain sources refresh ${sourceId}. Ask the user first, because it pushes those commits (git -C ${q(root)} log --stat ${upstreamRef}..HEAD lists them). gbrain sources reclone ${sourceId} replaces the checkout instead and drops them.${rewrite ? '' : ` To let every refresh publish a diverged checkout this way on its own, the user can run gbrain config set ${REFRESH_PUBLISH_DIVERGED_KEY} true.`}`);
error.fix = { argv, consent: [], actor: 'user', ask_user: true, requires_exclusive: false,
why: `HEAD has ${local} that ${upstreamRef} lacks while ${upstreamRef} moved on; pushing HEAD merged with it makes HEAD an ancestor of the upstream, so the refresh can fast-forward.`,
- user_message: `The checkout of source ${sourceId} has ${local} that were never pushed while its remote moved on. Push them, merged with the remote, so gbrain can bring the checkout up to date? Conflicting files stop the push and change nothing.`,
+ user_message: rewrite ? `The remote of source ${sourceId} was rewritten (${rewrite}) Push this checkout's history merged with it anyway, or replace the checkout with gbrain sources reclone ${sourceId}?`
+ : `The checkout of source ${sourceId} has ${local} that were never pushed while its remote moved on. Push them, merged with the remote, so gbrain can bring the checkout up to date? Conflicting files stop the push and change nothing.`,
docs: 'docs/guides/write-refusals.md#refresh_diverged' };
return error;
}
diff --git a/test/refresh-publish-diverged-7686.test.ts b/test/refresh-publish-diverged-7686.test.ts
index 753a57cbdf..c3e6589392 100644
--- a/test/refresh-publish-diverged-7686.test.ts
+++ b/test/refresh-publish-diverged-7686.test.ts
@@ -32,7 +32,7 @@ import { REFRESH_PUBLISH_DIVERGED_KEY, refreshWorktree } from '../src/core/persi
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
-import { git, page, withRefreshFixture, type RefreshFixture } from './helpers/worktree-refresh-fixture.ts';
+import { commitFile, git, page, withRefreshFixture, type RefreshFixture } from './helpers/worktree-refresh-fixture.ts';
const backends = testBackends();
const engines: BrainEngine[] = [];
@@ -202,3 +202,24 @@ test('setting on: a dry run publishes nothing and still refuses refresh_diverged
expect(remoteHead(f)).toBe(remote);
expect(f.head()).toBe(local);
}), 120_000);
+
+test('setting on: an upstream rewritten by a force-push is never published; the refresh refuses refresh_diverged and the remote keeps the rewrite', () => each(async f => {
+ f.push('alpha/purged.md', page('Purged', 'A page the upstream later removed by rewriting history.'));
+ expect(await refreshWorktree(f.engine, f.alpha)).toMatchObject({ status: 'completed' });
+ const purged = f.head();
+ git(f.upstream, 'reset', '-q', '--hard', 'HEAD~1');
+ commitFile(f.upstream, 'alpha/two.md', page('Alpha two', 'Rewritten upstream.'));
+ git(f.upstream, 'push', '-q', '--force', 'origin', 'main');
+ const rewritten = remoteHead(f);
+ writeFileSync(join(f.root, 'beta/local.md'), page('Local', 'A local commit nobody pushed.'));
+ git(f.root, 'add', 'beta/local.md'); git(f.root, 'commit', '-qm', 'local only');
+ const local = f.head();
+ await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');
+ const error = await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_diverged');
+ expect(error.message).toContain(`no longer contains ${purged}`);
+ expect(error.suggestion).not.toContain('gbrain config set');
+ expect(remoteHead(f)).toBe(rewritten);
+ expect(() => git(f.root, 'cat-file', '-e', `origin/main:alpha/purged.md`)).toThrow();
+ expect(f.head()).toBe(local);
+ expect((await f.refreshRows()).filter(r => r.state !== 'completed')).toEqual([]);
+}), 120_000);