Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(refresh): refuse refresh_dirty before publishing a diverged checkout (#7686)

garrytanec100b3cb6e3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2eff3a8f0b..d29b7fcdfc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,7 +39,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 `commitAndPush` (`pushOnly`, `keepCheckout`) for a diverged checkout, re-fetches and continues; the result carries `published`. 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 `commitAndPush` (`pushOnly`, `keepCheckout`) 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`. 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/architecture/canonical-writers.md` and its census.
diff --git a/docs/guides/live-sync.md b/docs/guides/live-sync.md
index 719fcdb28c..f3ca4b633f 100644
--- a/docs/guides/live-sync.md
+++ b/docs/guides/live-sync.md
@@ -675,8 +675,9 @@ vars — incident-time escape hatches, not everyday knobs.
the upstream in memory, the same publish as
`gbrain git commit-push --push-only --keep-checkout`, and fast-forwards to
the merge. It never moves the checkout to merge, a conflicting file refuses
- `integrate_conflict` naming it with nothing pushed, and `--dry-run` never
- publishes.
+ `integrate_conflict` naming it with nothing pushed, an uncommitted edit to a
+ file the upstream changed refuses `refresh_dirty` before anything is pushed,
+ and `--dry-run` never publishes.
**Say to your agent:** *"Bring my notes source up to date with its remote."*
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 3bf83fa9ab..6d3fbe251b 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 and then fast-forwards; a conflicting file then refuses `integrate_conflict` 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 and then fast-forwards; a conflicting file then refuses `integrate_conflict`, and an uncommitted edit to a file the upstream changed refuses `refresh_dirty`, both with nothing pushed. |
| <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 560a2fac37..759b78ec04 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -7411,8 +7411,9 @@ vars — incident-time escape hatches, not everyday knobs.
the upstream in memory, the same publish as
`gbrain git commit-push --push-only --keep-checkout`, and fast-forwards to
the merge. It never moves the checkout to merge, a conflicting file refuses
- `integrate_conflict` naming it with nothing pushed, and `--dry-run` never
- publishes.
+ `integrate_conflict` naming it with nothing pushed, an uncommitted edit to a
+ file the upstream changed refuses `refresh_dirty` before anything is pushed,
+ 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 fdee6d8ba6..8d8bd86722 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -283,6 +283,9 @@ 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 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);
const localCommits = Number((await read(['rev-list', '--count', `${targetHead}..${oldHead}`])).stdout.trim()) || 0;
const pushed = commitAndPush({ repo: root, pushOnly: true, keepCheckout: true });
const plan = await precheck(engine, git, sourceId, fetchTimeoutMs);
diff --git a/test/refresh-publish-diverged-7686.test.ts b/test/refresh-publish-diverged-7686.test.ts
index 41b5f4c171..575aa96fae 100644
--- a/test/refresh-publish-diverged-7686.test.ts
+++ b/test/refresh-publish-diverged-7686.test.ts
@@ -7,11 +7,13 @@
* on pushes HEAD merged with the upstream in memory (the keep-checkout publish,
* which never moves the checkout), then fast-forwards, keeping the local commits;
* with the setting off it refuses `refresh_diverged` as before; a conflicting path
- * refuses `integrate_conflict` naming the path and changes nothing; a dry run never
- * publishes.
+ * refuses `integrate_conflict` naming the path and changes nothing; an uncommitted
+ * edit on an incoming path refuses `refresh_dirty` before anything is pushed; a dry
+ * run never publishes.
* Regression it catches: a refresh that pushes local commits without the
* setting, one that moves the checkout or drops the local commits while
- * publishing, and one that pushes or fences anything when the merge conflicts.
+ * publishing, and one that pushes or fences anything when the merge conflicts or
+ * the refresh is about to refuse a dirty overlap.
* Seams: none; a real bare remote, a pushing clone and the managed checkout.
*/
import { afterAll, beforeAll, expect, test } from 'bun:test';
@@ -132,6 +134,19 @@ test('setting on: a conflicting path refuses integrate_conflict naming it, and n
expect(await f.lastCommit(f.alpha)).toBe(lastAlpha);
}), 120_000);
+test('setting on: an uncommitted edit on an incoming path refuses refresh_dirty before publishing, so nothing is pushed, fenced or moved', () => each(async f => {
+ const local = diverge(f);
+ const remote = remoteHead(f);
+ writeFileSync(join(f.root, 'alpha/two.md'), page('Alpha two', 'An uncommitted local edit.'));
+ await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');
+ const error = await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_dirty');
+ expect(error.message).toContain('alpha/two.md');
+ expect(remoteHead(f)).toBe(remote);
+ expect(f.head()).toBe(local);
+ expect(readFileSync(join(f.root, 'alpha/two.md'), 'utf8')).toContain('An uncommitted local edit.');
+ expect(await f.refreshRows()).toEqual([]);
+}), 120_000);
+
test('setting on: a dry run publishes nothing and still refuses refresh_diverged', () => each(async f => {
const local = diverge(f);
const remote = remoteHead(f);