Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (refresh names quarantined publish; refusals after a publish say so)

garrytan01ac97fe617f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d29b7fcdfc..4648a6e24b 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 (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/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` (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/architecture/canonical-writers.md` and its census.
diff --git a/docs/guides/live-sync.md b/docs/guides/live-sync.md
index f3ca4b633f..fa7fee3976 100644
--- a/docs/guides/live-sync.md
+++ b/docs/guides/live-sync.md
@@ -675,7 +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, an uncommitted edit to a
+ `integrate_conflict` naming it with nothing pushed (with `gbrain.quarantine`
+ 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.
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 6d3fbe251b..1bbedb8e55 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`, 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 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_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 759b78ec04..e8fe59a260 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -7411,7 +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, an uncommitted edit to a
+ `integrate_conflict` naming it with nothing pushed (with `gbrain.quarantine`
+ 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.
diff --git a/src/commands/sources-refresh.ts b/src/commands/sources-refresh.ts
index 6a3186c312..e46e4bb4d8 100644
--- a/src/commands/sources-refresh.ts
+++ b/src/commands/sources-refresh.ts
@@ -55,6 +55,8 @@ function describe(result: WorktreeRefreshResult): string {
const lines = [`Refresh ${result.status}: sources ${result.source_ids.join(', ')}; ${head(result.old_head)} -> ${head(result.target_head)}${result.upstream_ref ? ` (${result.upstream_ref})` : ''}.`];
if (result.recovered) lines.push(`Recovered orphaned refresh ${result.recovered.refresh_id} (${result.recovered.status}; previous holder: ${result.recovered.previous_holder ? `pid ${result.recovered.previous_holder.pid} on ${result.recovered.previous_holder.hostname}` : 'not recorded'}).`);
if (result.published) lines.push(`Published ${result.published.local_commits} local commit(s) merged with ${result.published.integrated} upstream commit(s) as ${head(result.published.sha)} before the fast-forward (sources.refresh_publish_diverged).`);
+ if (result.published?.quarantined) lines.push(`The remote also changed ${result.published.quarantined.paths.join(', ')}: its version was published and this machine's version is kept under ${result.published.quarantined.ref}; gbrain doctor lists it (quarantined_changes).`);
+ if (result.published?.superseded_remote_paths) lines.push(`Kept this machine's version of ${result.published.superseded_remote_paths.join(', ')}: the remote held a version this checkout had already replaced (docs/guides/shared-checkout-git.md#conflicts).`);
if (result.incoming_files !== undefined) lines.push(`Incoming files: ${result.incoming_files}.`);
for (const member of result.synced) lines.push(` ${member.source_id}: sync ${member.status}, last_commit ${head(member.last_commit)}`);
if (result.preserved_uncommitted.length) lines.push(`Preserved uncommitted paths (outside the incoming diff): ${result.preserved_uncommitted.slice(0, 20).join(', ')}${result.preserved_uncommitted.length > 20 ? ' ...' : ''}`);
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index 8d8bd86722..1dbd07783a 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -42,7 +42,7 @@ import { startPersistenceConsumer } from './service.ts';
import { lockTopologyPrincipal, lockTopologyRows, topologyPrincipal, withTopologyLocks } from './topology-locks.ts';
import { ACTIVE_REFRESH_STATES_SQL, CHECKOUT_EFFECT_KINDS_SQL, type WorktreeRefreshState } from './worktree-refresh-schema.ts';
import { gitChildEnv } from '../git-env.ts';
-import { commitAndPush } from '../git/commit-push.ts';
+import { commitAndPush, type QuarantineEntry } from '../git/commit-push.ts';
import { isTruthy } from '../connectors/config-keys.ts';
import { classifyOriginUniqueViolation } from './origin-guard.ts';
@@ -71,7 +71,7 @@ export interface WorktreeRefreshResult {
/** #7679: an orphaned refresh this run finished (or rolled back) through the `--resume` path before its own refresh. */
recovered?: { refresh_id: string; state: WorktreeRefreshState; status: WorktreeRefreshResult['status']; previous_holder: RefreshHolder | null };
/** #7686: the diverged checkout's local commits this run published, merged with the upstream, before fast-forwarding (`sources.refresh_publish_diverged`). */
- published?: { sha: string; local_commits: number; integrated: number };
+ published?: { sha: string; local_commits: number; integrated: number; quarantined?: QuarantineEntry; superseded_remote_paths?: string[] };
}
/** #7679: the process that holds a refresh's lock, recorded on the row so status can name it. */
export interface RefreshHolder { host_id: string | null; hostname: string; pid: number; started_at: string }
@@ -288,8 +288,10 @@ async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTi
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);
- return { ...plan, published: { sha: pushed.sha ?? plan.targetHead, local_commits: localCommits, integrated: pushed.integrated } };
+ const published = { sha: pushed.sha ?? targetHead, local_commits: localCommits, integrated: pushed.integrated,
+ ...(pushed.quarantined ? { quarantined: pushed.quarantined } : {}), ...(pushed.superseded_remote_paths ? { superseded_remote_paths: pushed.superseded_remote_paths } : {}) };
+ const plan = await precheck(engine, git, sourceId, fetchTimeoutMs).catch(error => { throw notePublished(error, published); });
+ return { ...plan, published: { ...published, sha: pushed.sha ?? plan.targetHead } };
}
const dirt = await dirtyOverlap(git, root, oldHead, targetHead);
if (dirt.overlap.length) throw dirtyRefusal(sourceId, dirt.overlap);
@@ -313,6 +315,11 @@ async function divergedRefusal(git: Git, root: string, sourceId: string, upstrea
docs: 'docs/guides/write-refusals.md#refresh_diverged' };
return error;
}
+/** #7686: a refusal after this run's publish says the remote already holds the local commits, so "nothing changed" is not misread. */
+function notePublished(error: unknown, published: WorktreeRefreshResult['published']): unknown {
+ if (published && error instanceof Error) error.message += ` This run had already published the checkout's ${published.local_commits} local commit(s) merged with the upstream as ${published.sha} (${REFRESH_PUBLISH_DIVERGED_KEY}), so the remote holds them.`;
+ return error;
+}
function dirtyRefusal(sourceId: string, overlap: string[], refreshId?: string): OperationError {
const named = overlap.slice(0, 20).join(', ') + (overlap.length > 20 ? ` and ${overlap.length - 20} more` : '');
return refusal('refresh_dirty', `Uncommitted or untracked paths overlap the incoming upstream changes: ${named}. Nothing changed.`,
@@ -453,9 +460,11 @@ export async function refreshWorktree(engine: BrainEngine, sourceId: string, opt
}
async function refreshOnce(engine: BrainEngine, sourceId: string, opts: RefreshOptions, fetchTimeoutMs: number, waitDrainMs: number): Promise<WorktreeRefreshResult> {
- return withGit(async git => {
+ let published: WorktreeRefreshResult['published'];
+ return withGit<WorktreeRefreshResult>(async git => {
const publishDiverged = !opts.dryRun && isTruthy(await engine.getConfig(REFRESH_PUBLISH_DIVERGED_KEY));
const plan = await precheck(engine, git, sourceId, fetchTimeoutMs, publishDiverged);
+ published = plan.published;
const base = { refresh_id: null, worktree_id: plan.binding.worktree_id, source_ids: plan.members, old_head: plan.oldHead,
target_head: plan.targetHead, upstream_ref: plan.upstreamRef, preserved_uncommitted: plan.preserved, incoming_files: plan.incoming,
...(plan.published ? { published: plan.published } : {}) };
@@ -504,7 +513,7 @@ async function refreshOnce(engine: BrainEngine, sourceId: string, opts: RefreshO
const result = finished(await readRefresh(engine, row.id), sync, plan.preserved);
return plan.published ? { ...result, published: plan.published } : result;
} finally { await refreshLock.release(); }
- });
+ }).catch(error => { throw notePublished(error, published); });
}
/** Step 2: native topology + worktree locks, then one transaction inserting the `draining` row. */
diff --git a/test/refresh-publish-diverged-7686.test.ts b/test/refresh-publish-diverged-7686.test.ts
index 575aa96fae..d86dd56e3d 100644
--- a/test/refresh-publish-diverged-7686.test.ts
+++ b/test/refresh-publish-diverged-7686.test.ts
@@ -9,7 +9,8 @@
* with the setting off it refuses `refresh_diverged` as before; a conflicting path
* 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.
+ * run never publishes; with gbrain.quarantine on, the refresh names the parked
+ * local version; a refusal after the publish says the remote already holds it.
* 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 or
@@ -147,6 +148,31 @@ test('setting on: an uncommitted edit on an incoming path refuses refresh_dirty
expect(await f.refreshRows()).toEqual([]);
}), 120_000);
+test('setting on with gbrain.quarantine: a conflicting path is published as the remote version and the refresh names the parked local version', () => each(async f => {
+ diverge(f, { path: 'alpha/two.md', content: page('Alpha two', 'Local side.') });
+ git(f.root, 'config', 'gbrain.quarantine', 'true');
+ await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');
+ const out: string[] = [];
+ const log = console.log;
+ _resetCliExitVerdictForTests();
+ console.log = (line: string) => { out.push(line); };
+ try { await runSourcesRefresh(f.engine, [f.alpha]); } finally { console.log = log; _resetCliExitVerdictForTests(); process.exitCode = 0; }
+ const ref = git(f.root, 'for-each-ref', '--format=%(refname)', 'refs/gbrain/quarantine/').trim();
+ expect(ref).toMatch(/^refs\/gbrain\/quarantine\//);
+ expect(git(f.root, 'show', `${ref}:alpha/two.md`)).toContain('Local side.');
+ expect(out.join('\n')).toContain(`this machine's version is kept under ${ref}`);
+ expect(out.join('\n')).toContain('alpha/two.md');
+}), 120_000);
+
+test('setting on: a refusal after the publish says the local commits were already published', () => each(async f => {
+ diverge(f);
+ await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');
+ const error = await refusedWith(refreshWorktree(f.engine, f.alpha, { hooks: { boundary: point => {
+ if (point === 'drained') git(f.root, 'commit', '-q', '--allow-empty', '-m', 'external');
+ } } }), 'refresh_source_changed');
+ expect(error.message).toContain(`already published the checkout's 1 local commit(s) merged with the upstream as ${remoteHead(f)}`);
+}), 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);