Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
revert(refresh): move the #7686 opt-in publish to a follow-up PR; this release ships only the #7782 test reshape
garrytan6e9c79944ad8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f05e0c82dc..86d89a79b0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,44 +12,13 @@ identifiers and attribution are available in the pre-removal Git revision## [0.60.526.0] - 2026-10-31-**A managed checkout that gets local commits while a sibling checkout pushes the same branch can now stay current without a person in the loop. Turn on `sources.refresh_publish_diverged` and a diverged `gbrain sources refresh` publishes the local commits merged with the upstream, then fast-forwards.**+**The #7679 refresh state-matrix tests (7c and 7d) now run in about half the time, with every assertion kept (#7782).**-Before, such a refresh always refused `refresh_diverged`, and the database lagged the upstream until someone ran the keep-checkout publish by hand or a scheduled publish caught up. That repeated every interval. The setting is the user's standing consent to push those local commits. It defaults to off, so nothing changes for existing brains.--### How to get it--```bash-gbrain config set sources.refresh_publish_diverged true-```--### What changed--| Situation | Before | Now |-|---|---|---|-| Diverged checkout, setting on | refused `refresh_diverged` | pushes HEAD merged with the upstream in memory (the `gbrain git commit-push --push-only --keep-checkout` publish), fast-forwards to the merge and reports `published` (sha, local commits, upstream commits merged) |-| 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 |--### Things to watch after you upgrade--- The publish needs a Git identity in the checkout for the merge commit, the same as the manual keep-checkout publish.-- It never uses a `--pull` that moves the checkout. The merge is built in memory and pushed, and the checkout moves only through the refresh's usual fast-forward.-- The push skips the checkout's pre-push hook, as the manual keep-checkout publish does. If you rely on a pre-push secret scanner, leave the setting off.-- The setting covers every managed checkout in the brain.-- If another publish of the same checkout is running, the refresh refuses at once instead of waiting; run it again.+These two tests built a fresh brain for each cell, and on a 2-CPU machine that cost added up to minutes per run. Now 7c hands a cell that ends settled to the next cell instead of building a new brain, and 7d builds one brain per kind of interrupted refresh and runs every action on it in turn, with each action undoing its seam. Nothing changes for users.### 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; it refuses `refresh_diverged` instead when the checkout holds a commit the upstream held before (reachable from the remote-tracking ref before this fetch, from its reflog, or from a completed refresh's target for the same upstream) but no longer contains, or when no record exists (no reflog entry, no completed refresh, and `core.logAllRefUpdates` off, so the ref before the fetch may already be past a force-push); its own fetch always records the move in the reflog; 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.-- Tests: `test/refresh-publish-diverged-7686.test.ts` (setting on and off, a conflict, quarantine, a dirty overlap, a refusal after the publish, a publish child that fails, and a dry run, on PGLite and on Postgres through `test/e2e/worktree-refresh-postgres.test.ts`). Tests 7c and 7d in `test/persistence-worktree-refresh.test.ts` share one fixture across their cells and run in about half the time, with every assertion kept (#7782).+- Tests: 7c and 7d in `test/persistence-worktree-refresh.test.ts` share fixtures across their cells, and every assertion is kept (#7782).## [0.60.525.0] - 2026-10-31diff --git a/docs/architecture/canonical-writers.md b/docs/architecture/canonical-writers.mdindex 4e139e25d3..c8401fbd84 100644--- a/docs/architecture/canonical-writers.md+++ b/docs/architecture/canonical-writers.md@@ -78,10 +78,7 @@ worktree native lock while claims stop (`fenced`), verifies HEAD and runsordinary managed `--no-pull` sync that follows, so every imported page is ajournaled request. A durable `persistence_worktree_refreshes` row lets arestarted owner converge an interrupted refresh without adopting an unverified-HEAD. With `sources.refresh_publish_diverged` on (the user's standing consent,-default off), a diverged refresh first runs the keep-checkout publish, which-pushes HEAD merged with the upstream in memory and never moves the checkout or-writes the database, then fast-forwards as above. Remote sync retains the+HEAD. Remote sync retains theoriginal `submit_job` principal, admin/source/operation ceiling and normalizedpayload; runtime options cannot expand that grant and current revocation ischecked before publication.diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsvindex 7ed57cb942..7f9a2f792a 100644--- a/docs/architecture/canonical-writers.tsv+++ b/docs/architecture/canonical-writers.tsv@@ -254,7 +254,7 @@ src/core/repair/frontmatter.ts 2 coordinator `gbrain repair frontmatter --apply`src/commands/sources-mirror.ts 1 engine_guard `gbrain sources mirror-readonly|mirror-writable` (#5409) updates only sources.config.mirror_read_only, exactly as `sources federate` updates sources.config.federated; the sources managed_writer_guard trigger governs the row and no page, fact or file is written.src/core/sync-upstream.ts 1 engine_guard `recordUpstreamObservation` (#5255/#5176) updates only sources.upstream_checked_at, upstream_commit and upstream_behind, observations of the checkout's Git upstream outside managed_writer_guard's protected topology and checkpoint tuples; no page, fact or file is written, and a failure never fails the sync.src/core/persistence/mirror-read-only.ts 1 coordinator classifyMirrorPage stamps pages.database_only_reason=mirror_read_only only inside the coordinator publication transaction of a page write that published no file into a read-only mirror source (#5409), as classifyUnboundPage does for unbound sources.-src/core/persistence/worktree-refresh.ts 1 coordinator `gbrain sources refresh` (F0) is the one sanctioned managed Git writer: it fast-forwards the checkout only under the worktree native lock after admission refused and claims stopped every checkout write (`fenced`), then updates only sources.upstream_checked_at/upstream_commit/upstream_behind in the merged bookkeeping transaction; pages and the checkpoint advance through the ordinary managed --no-pull sync. #7686: with sources.refresh_publish_diverged on (standing consent, default off) it first runs the keep-checkout publish (a bounded child gbrain git commit-push --push-only --keep-checkout, never on the owner's event loop), which pushes HEAD merged with the upstream in memory and never moves the checkout or the database.+src/core/persistence/worktree-refresh.ts 1 coordinator `gbrain sources refresh` (F0) is the one sanctioned managed Git writer: it fast-forwards the checkout only under the worktree native lock after admission refused and claims stopped every checkout write (`fenced`), then updates only sources.upstream_checked_at/upstream_commit/upstream_behind in the merged bookkeeping transaction; pages and the checkpoint advance through the ordinary managed --no-pull sync.src/core/facts/unfenced-facts.ts 3 coordinator The extract_facts cycle phase and the v0.32.2 migration fence row_num-NULL facts onto their entity pages. On a managed brain the fence publishes through a coordinated maintenance request; an unmanaged brain writes the page file under the source filesystem and page locks, then mirrors the body and stamps row numbers in one maintenanceTransaction.src/core/repair/take-supersession.ts 1 coordinator gbrain repair take-supersession reprojects superseded_by for a page whose fence is already right: inside withCoordinatedWrite under the page key on a managed brain (revision-checked), maintenanceTransaction on an unmanaged one. Fence edits go through a revision-bound put_page request.src/core/repair/timeline-comments.ts 2 coordinator `gbrain repair timeline-comments` (#6184) deletes or rewrites timeline rows carrying HTML comment markup under the page lock: `withCoordinatedWrite` with maintenance attribution on managed brains, `maintenanceTransaction` otherwise; the page body changes go through a revision-bound put_page first.diff --git a/docs/guides/live-sync.md b/docs/guides/live-sync.mdindex e108f7a023..940f3d39f4 100644--- a/docs/guides/live-sync.md+++ b/docs/guides/live-sync.md@@ -680,19 +680,6 @@ vars — incident-time escape hatches, not everyday knobs.means something commits into the checkout outside gbrain: fix that writerinstead of forcing the checkout([scripts and the managed checkout](shared-checkout-git.md#scripts-and-the-managed-checkout)).- When local commits there are expected (automations committing alongside a- sibling checkout that pushes the same branch), the user can give standing- consent with `gbrain config set sources.refresh_publish_diverged true`- (default off): a diverged refresh then pushes the local commits merged with- the upstream in memory, the same publish as- `gbrain git commit-push --push-only --keep-checkout` run as a child process- (it skips the checkout's pre-push hook), and fast-forwards to the merge. It never moves the checkout to merge, a conflicting file refuses- `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,- 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.mdindex f96093bdd5..f01780f65f 100644--- a/docs/guides/shared-checkout-git.md+++ b/docs/guides/shared-checkout-git.md@@ -268,11 +268,7 @@ commits come in. Four rules keep that checkout able to move:stray commits merged with the upstream(`gbrain git commit-push --push-only --keep-checkout --path <checkout>`)and retry the refresh, as the [refusal](write-refusals.md#refresh_diverged)- says. Never force the checkout. When local commits there are expected- (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)); it never publishes over a rewritten upstream.+ says. Never force the checkout.3. **Stop syncing a source before rewriting its history.** Before aforce-push or `git filter-repo`, run `gbrain sources set-sync <id> off`(with the user's agreement) so automatic sync skips it, anddiff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex 35a0c548c7..1638111290 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -31,7 +31,7 @@| A command exited 3 (`confirmation_required`) | relay `user_message`; run `fix.command` only after the user agrees | agent, after the user agrees | the payload's `effects` | the fix's `verify` || A scheduled job, workspace script or hook finds nothing in the brain (every lookup empty), or its log shows `no_brain` or `GBRAIN_DB_ACCESS no_url`, while the same command works by hand | the job runs without the brain's config: call gbrain through one wrapper that sets `GBRAIN_HOME` and loads the brain's env file, and stop discarding its stderr ([the wrapper](cron-schedule.md#calling-gbrain-unattended)); `gbrain doctor --only cron_gbrain_home --json` names crontab lines that skip it | agent | none | the job's log shows results, and `gbrain engine status --json` run through the wrapper names the expected `db_url_source` || `gbrain sources refresh` refuses `refresh_not_owner` from cron or a script but works by hand | the caller resolves another gbrain home, so it is another host; the refusal names the identity file, `HOME` and `GBRAIN_HOME` it read. Set the owner's `GBRAIN_HOME` in the wrapper (not `HOME`, which also swaps git credentials); never copy or delete a `host.json` | agent | none | `gbrain sources refresh <id> --dry-run` through the wrapper |-| `gbrain sources refresh` refuses `refresh_diverged` on every run | something commits into the managed checkout outside gbrain, usually a script that writes files and runs `git commit` without pushing. `git log @{upstream}..HEAD` names the commits; move that writer to `gbrain git commit-push -- <paths>`, then publish the stray commits merged with the upstream (`gbrain git commit-push --push-only --keep-checkout --path <checkout>`) and retry, as the [refusal](write-refusals.md#refresh_diverged) says; never force ([scripts and the managed checkout](shared-checkout-git.md#scripts-and-the-managed-checkout)). When local commits there are expected, the user can instead turn on `sources.refresh_publish_diverged` (default off) so each refresh publishes them itself ([live sync](live-sync.md)) | agent; reconciling after the user agrees | `destructive` when reconciling drops local commits | `gbrain sources refresh <id> --dry-run` |+| `gbrain sources refresh` refuses `refresh_diverged` on every run | something commits into the managed checkout outside gbrain, usually a script that writes files and runs `git commit` without pushing. `git log @{upstream}..HEAD` names the commits; move that writer to `gbrain git commit-push -- <paths>`, then publish the stray commits merged with the upstream (`gbrain git commit-push --push-only --keep-checkout --path <checkout>`) and retry, as the [refusal](write-refusals.md#refresh_diverged) says; never force ([scripts and the managed checkout](shared-checkout-git.md#scripts-and-the-managed-checkout)) | agent; reconciling after the user agrees | `destructive` when reconciling drops local commits | `gbrain sources refresh <id> --dry-run` || A `--json` caller fails to parse gbrain's output | something other than gbrain wrote to stdout, usually a wrapper or a hook it runs; send that output to a log file or stderr (gbrain's own notices already go to stderr) | agent | none | the same call piped to `jq .` parses || gbrain calls time out from a script or language runtime but finish by hand, or each search takes several seconds | a cold CLI start takes 3–6 s on a pooled Postgres brain: set caller timeouts of at least 10 s in both the shell and the runtime (a runtime exec timeout can override the shell's), and turn on the [warm CLI socket](cli-socket.md). If warm searches stay slow, measure the round trip to the database; one in another region dominates search time | agent; moving the database after the user agrees | none | `GBRAIN_DEBUG=1 gbrain search <query>` prints a `[cli-socket] warm:` line || After a database change some processes still use the old server, or a URL variable silently keeps its old value | a shell-sourced env file has an unquoted `&` (the assignment ends there), or a process kept the environment it started with. Quote every value, keep Postgres URLs to `?sslmode=require` (driver options as variables, such as `GBRAIN_PREPARE=false`), update every URL variable the tooling reads, restart every gbrain process, and prove the switch from the database side ([switching a database](../../INSTALL_FOR_AGENTS.md#switching-a-database)). Never paste `env` output into a transcript while debugging | agent, after the user agrees | none | a row written after the restart appears on the new server |diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex c6c4cc04f2..e43d770ea2 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. 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_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. || <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.txtindex fb4a8bcad1..d236f03398 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -7416,19 +7416,6 @@ vars — incident-time escape hatches, not everyday knobs.means something commits into the checkout outside gbrain: fix that writerinstead of forcing the checkout([scripts and the managed checkout](shared-checkout-git.md#scripts-and-the-managed-checkout)).- When local commits there are expected (automations committing alongside a- sibling checkout that pushes the same branch), the user can give standing- consent with `gbrain config set sources.refresh_publish_diverged true`- (default off): a diverged refresh then pushes the local commits merged with- the upstream in memory, the same publish as- `gbrain git commit-push --push-only --keep-checkout` run as a child process- (it skips the checkout's pre-push hook), and fast-forwards to the merge. It never moves the checkout to merge, a conflicting file refuses- `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,- 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."*@@ -9947,7 +9934,7 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro| A command exited 3 (`confirmation_required`) | relay `user_message`; run `fix.command` only after the user agrees | agent, after the user agrees | the payload's `effects` | the fix's `verify` || A scheduled job, workspace script or hook finds nothing in the brain (every lookup empty), or its log shows `no_brain` or `GBRAIN_DB_ACCESS no_url`, while the same command works by hand | the job runs without the brain's config: call gbrain through one wrapper that sets `GBRAIN_HOME` and loads the brain's env file, and stop discarding its stderr ([the wrapper](cron-schedule.md#calling-gbrain-unattended)); `gbrain doctor --only cron_gbrain_home --json` names crontab lines that skip it | agent | none | the job's log shows results, and `gbrain engine status --json` run through the wrapper names the expected `db_url_source` || `gbrain sources refresh` refuses `refresh_not_owner` from cron or a script but works by hand | the caller resolves another gbrain home, so it is another host; the refusal names the identity file, `HOME` and `GBRAIN_HOME` it read. Set the owner's `GBRAIN_HOME` in the wrapper (not `HOME`, which also swaps git credentials); never copy or delete a `host.json` | agent | none | `gbrain sources refresh <id> --dry-run` through the wrapper |-| `gbrain sources refresh` refuses `refresh_diverged` on every run | something commits into the managed checkout outside gbrain, usually a script that writes files and runs `git commit` without pushing. `git log @{upstream}..HEAD` names the commits; move that writer to `gbrain git commit-push -- <paths>`, then publish the stray commits merged with the upstream (`gbrain git commit-push --push-only --keep-checkout --path <checkout>`) and retry, as the [refusal](write-refusals.md#refresh_diverged) says; never force ([scripts and the managed checkout](shared-checkout-git.md#scripts-and-the-managed-checkout)). When local commits there are expected, the user can instead turn on `sources.refresh_publish_diverged` (default off) so each refresh publishes them itself ([live sync](live-sync.md)) | agent; reconciling after the user agrees | `destructive` when reconciling drops local commits | `gbrain sources refresh <id> --dry-run` |+| `gbrain sources refresh` refuses `refresh_diverged` on every run | something commits into the managed checkout outside gbrain, usually a script that writes files and runs `git commit` without pushing. `git log @{upstream}..HEAD` names the commits; move that writer to `gbrain git commit-push -- <paths>`, then publish the stray commits merged with the upstream (`gbrain git commit-push --push-only --keep-checkout --path <checkout>`) and retry, as the [refusal](write-refusals.md#refresh_diverged) says; never force ([scripts and the managed checkout](shared-checkout-git.md#scripts-and-the-managed-checkout)) | agent; reconciling after the user agrees | `destructive` when reconciling drops local commits | `gbrain sources refresh <id> --dry-run` || A `--json` caller fails to parse gbrain's output | something other than gbrain wrote to stdout, usually a wrapper or a hook it runs; send that output to a log file or stderr (gbrain's own notices already go to stderr) | agent | none | the same call piped to `jq .` parses || gbrain calls time out from a script or language runtime but finish by hand, or each search takes several seconds | a cold CLI start takes 3–6 s on a pooled Postgres brain: set caller timeouts of at least 10 s in both the shell and the runtime (a runtime exec timeout can override the shell's), and turn on the [warm CLI socket](cli-socket.md). If warm searches stay slow, measure the round trip to the database; one in another region dominates search time | agent; moving the database after the user agrees | none | `GBRAIN_DEBUG=1 gbrain search <query>` prints a `[cli-socket] warm:` line || After a database change some processes still use the old server, or a URL variable silently keeps its old value | a shell-sourced env file has an unquoted `&` (the assignment ends there), or a process kept the environment it started with. Quote every value, keep Postgres URLs to `?sslmode=require` (driver options as variables, such as `GBRAIN_PREPARE=false`), update every URL variable the tooling reads, restart every gbrain process, and prove the switch from the database side ([switching a database](../../INSTALL_FOR_AGENTS.md#switching-a-database)). Never paste `env` output into a transcript while debugging | agent, after the user agrees | none | a row written after the restart appears on the new server |diff --git a/src/commands/sources-refresh.ts b/src/commands/sources-refresh.tsindex ad368d5765..b3d2f3f857 100644--- a/src/commands/sources-refresh.ts+++ b/src/commands/sources-refresh.ts@@ -54,9 +54,6 @@ function describe(result: WorktreeRefreshResult): string {const head = (value: string | null) => value ? value.slice(0, 12) : '-';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/config-runtime-keys.ts b/src/core/config-runtime-keys.tsindex 79f9d1b565..8d5f12ffd2 100644--- a/src/core/config-runtime-keys.ts+++ b/src/core/config-runtime-keys.ts@@ -19,7 +19,5 @@ export const RUNTIME_READER_CONFIG_KEYS: readonly string[] = ['writer.lint_on_put_page', // output/post-write.ts lint after put_page, default off'context.hot_memory.session_only', // facts/meta-hook.ts, read by the turn_context and context_pack IPC handlers: hot memory never falls back to other sessions' facts, default off'serve.cli_socket', // config.ts loadConfigWithEngine (snapshot only) → serve.ts: a Postgres serve answers CLI reads over a private Unix socket, default off- 'sources.refresh_fetch_timeout_ms', 'sources.refresh_drain_wait_ms', // persistence/worktree-refresh.ts: refresh fetch bound (default 120 s) and drain wait (default 60 s), in ms- 'sources.refresh_publish_diverged', // persistence/worktree-refresh.ts (#7686): refresh publishes a diverged checkout's local commits merged with the upstream before fast-forwarding, default off'serve.vector_prewarm', // config.ts loadConfigWithEngine (snapshot only) → serve.ts: a Postgres serve prewarms the HNSW indexes into shared_buffers at start when they fit, default off];diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.tsindex a650c0fd40..93aab6ef82 100644--- a/src/core/persistence/worktree-refresh.ts+++ b/src/core/persistence/worktree-refresh.ts@@ -20,7 +20,7 @@* so status can say who holds it, and a row whose lock is free is orphaned: the* next plain refresh finishes it through the `--resume` path before refreshing.*/-import { closeSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, rmSync } from 'node:fs';+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';import { hostname } from 'node:os';import { join } from 'node:path';import type { BrainEngine } from '../engine.ts';@@ -42,8 +42,6 @@ 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 type { QuarantineEntry } from '../git/commit-push.ts';-import { isTruthy } from '../connectors/config-keys.ts';import { classifyOriginUniqueViolation } from './origin-guard.ts';export interface WorktreeRefreshRow {@@ -72,8 +70,6 @@ export interface WorktreeRefreshResult {synced: RefreshMemberSync[]; sync_blocked?: RefreshSyncBlocked[]; next?: string;/** #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; 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 }@@ -223,14 +219,11 @@ async function markRecoveryRequired(engine: BrainEngine, row: WorktreeRefreshRowinterface Plan {binding: WorktreeBinding; root: string; members: string[]; upstreamRef: string; oldHead: string; targetHead: string;- overlap: string[]; preserved: string[]; incoming: number; published?: WorktreeRefreshResult['published'];+ overlap: string[]; preserved: string[]; incoming: number;}-/** #7686: standing consent, default off, to publish a diverged checkout's local commits before the fast-forward. */-export const REFRESH_PUBLISH_DIVERGED_KEY = 'sources.refresh_publish_diverged';-/** Steps 1.3/1: refusals before any database state; fetch moves only remote-tracking refs. */-async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTimeoutMs: number, publishDiverged = false): Promise<Plan> {+async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTimeoutMs: number): Promise<Plan> {if (!await managedPersistenceEnabled(engine)) throw refusal('refresh_not_managed','This brain is not managed, so gbrain sync pulls the checkout itself; there is no worktree fence to coordinate.', `gbrain sync --source ${sourceId}`);const binding = await getWorktreeBinding(engine, sourceId, existingLocalHostId());@@ -273,34 +266,8 @@ async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTiconst upstreamRef = upstream.stdout.trim();const remote = (await read(['config', '--get', `branch.${branch}.remote`], 1)).stdout.trim();const merge = (await read(['config', '--get', `branch.${branch}.merge`], 1)).stdout.trim();- const heldUpstream = new Set<string>();- let upstreamRecorded = false;- if (publishDiverged) {- const isSha = (sha: string) => /^[0-9a-f]{40,64}$/.test(sha) && !/^0+$/.test(sha);- const upstreamFull = (await read(['rev-parse', '--symbolic-full-name', '@{upstream}'])).stdout.trim();- const logged = (await read(['log', '-g', '-n', '1000', '--format=%H', upstreamFull, '--'], 128)).stdout.split('\n').map(sha => sha.trim());- let reflog = '';- try {- const fd = openSync((await read(['rev-parse', '--path-format=absolute', '--git-path', `logs/${upstreamFull}`])).stdout.trim(), 'r');- try {- const size = fstatSync(fd).size;- const first = Buffer.alloc(Math.min(size, 512));- const tail = Buffer.alloc(Math.min(size, 262_144));- readSync(fd, first, 0, first.length, 0);- readSync(fd, tail, 0, tail.length, size - tail.length);- reflog = `${first.toString('utf8').split('\n')[0]}\n${tail.toString('utf8')}`;- } finally { closeSync(fd); }- } catch { /* no reflog file: a reftable repository, or no reflog */ }- const columns = reflog.split('\n').flatMap(line => line.split(' ').slice(0, 2));- const rows = await engine.executeRaw<{ target_head: string }>(`SELECT target_head FROM persistence_worktree_refreshes WHERE worktree_id=$1::uuid AND upstream_ref=$2 AND state='completed' ORDER BY created_at DESC LIMIT 100`, [binding.worktree_id, upstreamRef]);- const recorded = [...logged, ...columns, ...rows.map(r => r.target_head)].filter(isSha);- const preFetch = (await read(['rev-parse', '--verify', '-q', '@{upstream}^{commit}'], 1)).stdout.trim();- const unlogged = ['false', 'no', 'off', '0'].includes((await read(['config', '--get', 'core.logAllRefUpdates'], 1)).stdout.trim().toLowerCase());- upstreamRecorded = recorded.length > 0 || (isSha(preFetch) && !unlogged);- for (const sha of [preFetch, ...recorded]) if (isSha(sha)) heldUpstream.add(sha);- }if (remote && remote !== '.') {- const fetched = await git(['-C', root, ...(publishDiverged ? ['-c', 'core.logAllRefUpdates=true'] : []), 'fetch', '--no-tags', '--quiet', remote, merge || branch], fetchTimeoutMs);+ const fetched = await git(['-C', root, 'fetch', '--no-tags', '--quiet', remote, merge || branch], fetchTimeoutMs);if (fetched.code !== 0) throw refusal('fetch_failed',fetched.timedOut ? `git fetch ${remote} did not finish within ${fetchTimeoutMs} ms; nothing changed.`: `git fetch ${remote} failed (${fetched.stderr.trim().split('\n')[0] || `exit ${fetched.code}`}); nothing changed.`,@@ -310,79 +277,29 @@ async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTiconst targetHead = await revParse(git, root, '@{upstream}');if (!oldHead || !targetHead) throw refusal('refresh_no_upstream', `The checkout HEAD or its upstream ${upstreamRef} does not resolve to a commit.`,`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 tips = [...heldUpstream].filter(sha => sha !== targetHead);- const held = new Set(tips.length ? (await read(['rev-list', '--ignore-missing', `^${targetHead}`, ...tips])).stdout.split('\n').map(sha => sha.trim()) : []);- const removed = (await read(['rev-list', `${targetHead}..${oldHead}`])).stdout.split('\n').map(sha => sha.trim()).find(sha => sha && held.has(sha));- if (!upstreamRecorded || 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 (no reflog entry and no completed refresh), 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);- const localCommits = Number((await read(['rev-list', '--count', `${targetHead}..${oldHead}`])).stdout.trim()) || 0;- const pushed = await publishInChild(root, sourceId);- 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 } };- }+ if (oldHead !== targetHead && !await isAncestor(git, root, oldHead, targetHead)) throw await divergedRefusal(git, root, sourceId, upstreamRef, oldHead, targetHead);const dirt = await dirtyOverlap(git, root, oldHead, targetHead);if (dirt.overlap.length) throw dirtyRefusal(sourceId, dirt.overlap);return { binding, root, members, upstreamRef, oldHead, targetHead, ...dirt };}-/** #7686: the bound on the keep-checkout publish child (a fetch, an in-memory merge and a push, repeated while the remote keeps moving). */-const PUBLISH_TIMEOUT_MS = 600_000;--/**- * #7686 (#7010's rule): run the keep-checkout publish in a bounded child `gbrain git commit-push --push-only --keep-checkout`.- * The shared publish is synchronous (fetches, pushes and lock waits block for minutes), and a refresh delegated to a- * PGLite owner runs inside the owner, where blocking would stall lease renewals; a busy publish lock fails at once.- */-async function publishInChild(root: string, sourceId: string): Promise<{ sha: string | null; integrated: number; quarantined?: QuarantineEntry; superseded_remote_paths?: string[] }> {- const { CHILD_ENV, resolveChildCliInvocation } = await import('../minions/job-isolation.ts');- const cli = resolveChildCliInvocation(process.env, process.execPath, process.argv[1], () => null);- if (!cli) throw opError('git_push_unavailable', `This process could not locate its own CLI executable to publish the diverged checkout ${root}; nothing was pushed.`,- `Set ${CHILD_ENV.childCliOverride} to the path of the CLI executable and retry gbrain sources refresh ${sourceId}, or publish by hand: gbrain git commit-push --push-only --keep-checkout --path ${q(root)}.`);- const child = await execFileBounded(cli.cmd, [...cli.argsPrefix, 'git', 'commit-push', '--push-only', '--keep-checkout', '--path', root, '--json'], {- timeout: PUBLISH_TIMEOUT_MS, termGraceMs: 10_000, maxBuffer: 1024 * 1024,- env: { ...process.env, GBRAIN_PUBLISH_LOCK_WAIT_SECONDS: '0', GBRAIN_PUSH_LOCK_WAIT_SECONDS: '0' },- });- let doc: Record<string, unknown> | null = null;- try { doc = JSON.parse(child.stdout.trim()); } catch { /* reported below */ }- if (!child.error && doc?.outcome === 'pushed') return doc as { sha: string | null; integrated: number; quarantined?: QuarantineEntry; superseded_remote_paths?: string[] };- if (doc && typeof doc.code === 'string' && typeof doc.message === 'string') {- throw opError(doc.code as Parameters<typeof opError>[0], doc.message, typeof doc.suggestion === 'string' ? doc.suggestion : '',- { ...(typeof doc.detail === 'string' ? { detail: doc.detail } : {}), ...(doc.fix ? { fix: doc.fix as Action } : {}), retryable: doc.retryable === true });- }- throw opError('push_unconfirmed', `The publish of the diverged checkout ${root} did not report a push (${child.error ? `exit ${String(child.error.code ?? child.error.signal ?? 'unknown')}` : `outcome ${String(doc?.outcome ?? 'unreadable')}`}: ${child.stderr.trim().slice(0, 300) || 'no detail'}); the refresh stopped before fencing anything, and the remote may already hold the merge.`,- `Check gbrain sources writer status --source ${sourceId} --json, then retry gbrain sources refresh ${sourceId}.`, { retryable: true });-}/*** Q1: a diverged checkout is reconciled without moving it: `gbrain git commit-push --push-only --keep-checkout` merges the* 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, rewrite?: string): Promise<OperationError> {+async function divergedRefusal(git: Git, root: string, sourceId: string, upstreamRef: string, oldHead: string, targetHead: 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.${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.`}`);+ `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.`);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: rewrite ? `The checkout of source ${sourceId} cannot be published on its own: ${rewrite} Push this checkout's history merged with the remote 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.`,+ 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.`,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.`,@@ -576,14 +493,10 @@ export async function refreshWorktree(engine: BrainEngine, sourceId: string, opt}async function refreshOnce(engine: BrainEngine, sourceId: string, opts: RefreshOptions, fetchTimeoutMs: number, waitDrainMs: number, syncBudgetMs: number): Promise<WorktreeRefreshResult> {- 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;+ return withGit(async git => {+ const plan = await precheck(engine, git, sourceId, fetchTimeoutMs);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 } : {}) };+ target_head: plan.targetHead, upstream_ref: plan.upstreamRef, preserved_uncommitted: plan.preserved, incoming_files: plan.incoming };if (opts.dryRun) return { ...base, status: 'dry_run', synced: [],next: plan.oldHead === plan.targetHead ? `Already at ${plan.upstreamRef}; nothing to fast-forward.` : `gbrain sources refresh ${sourceId}` };if (plan.oldHead === plan.targetHead) {@@ -629,10 +542,9 @@ async function refreshOnce(engine: BrainEngine, sourceId: string, opts: RefreshOconst merged = await fenceAndMerge(engine, git, sourceId, plan, row, opts.hooks);await opts.hooks?.boundary?.('syncing', merged);const sync = await syncMembers(engine, git, merged, plan.root, syncBudgetMs);- const result = finished(await readRefresh(engine, row.id), sync, plan.preserved);- return plan.published ? { ...result, published: plan.published } : result;+ return finished(await readRefresh(engine, row.id), sync, plan.preserved);} 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/e2e/worktree-refresh-postgres.test.ts b/test/e2e/worktree-refresh-postgres.test.tsindex 10927dda53..4d70b235bc 100644--- a/test/e2e/worktree-refresh-postgres.test.ts+++ b/test/e2e/worktree-refresh-postgres.test.ts@@ -6,5 +6,4 @@ await registerPostgresTests(() => import('../persistence-worktree-refresh.test.ts'),() => import('../persistence-worktree-refresh-restart.test.ts'),() => import('../worktree-refresh-orphan-7679.test.ts'),- () => import('../refresh-publish-diverged-7686.test.ts'),);diff --git a/test/refresh-publish-diverged-7686.test.ts b/test/refresh-publish-diverged-7686.test.tsdeleted file mode 100644index ce686311ac..0000000000--- a/test/refresh-publish-diverged-7686.test.ts+++ /dev/null@@ -1,271 +0,0 @@-/**- * #7686: an opt-in refresh publishes a diverged managed checkout before it- * fast-forwards.- *- * Protects: with `sources.refresh_publish_diverged` on (standing consent, default- * off) a refresh of a checkout that has local commits while its upstream moved- * 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; an uncommitted- * edit on an incoming path refuses `refresh_dirty` before anything is pushed; a dry- * 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- * the refresh is about to refuse a dirty overlap.- * Seams: the `hooks.boundary` callback for the refusal after a publish, and- * GBRAIN_JOB_CHILD_CLI naming the child gbrain that publishes; otherwise- * a real bare remote, a pushing clone and the managed checkout.- */-import { afterAll, beforeAll, expect, test } from 'bun:test';-import { chmodSync, 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';-import { PGLiteEngine } from '../src/core/pglite-engine.ts';-import { KNOWN_CONFIG_KEYS } from '../src/core/config.ts';-import { runSourcesRefresh } from '../src/commands/sources-refresh.ts';-import { _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';-import { REFRESH_PUBLISH_DIVERGED_KEY, refreshWorktree } from '../src/core/persistence/worktree-refresh.ts';-import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';-import { testBackends } from './helpers/test-backends.ts';-import { withEnv } from './helpers/with-env.ts';-import { commitFile, git, page, withRefreshFixture, type RefreshFixture } from './helpers/worktree-refresh-fixture.ts';--const backends = testBackends();-const engines: BrainEngine[] = [];-let closePostgres: (() => Promise<void>) | undefined;-/** The publish runs in a child `gbrain`; under bun test that is this checkout's CLI through a wrapper. */-const bin = mkdtempSync(join(tmpdir(), 'gbrain-7686-bin-'));-const childCli = join(bin, 'gbrain');--beforeAll(async () => {- writeFileSync(childCli, `#!/bin/sh\nexec '${process.execPath}' '${join(import.meta.dir, '..', 'src', 'cli.ts')}' "$@"\n`);- chmodSync(childCli, 0o755);- if (backends.includes('pglite')) {- const engine = new PGLiteEngine();- await engine.connect({}); await engine.initSchema(); engines.push(engine);- }- if (backends.includes('postgres')) {- const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);- engines.push(pg.engine); closePostgres = pg.close;- }-}, 120_000);-afterAll(async () => {- for (const engine of engines) if (engine.kind === 'pglite') await engine.disconnect();- await closePostgres?.();- rmSync(bin, { recursive: true, force: true });-});--const each = async (fn: (f: RefreshFixture) => Promise<void>, cli = childCli) => {- for (const engine of engines) {- await withEnv({ GBRAIN_JOB_CHILD_CLI: cli }, () => withRefreshFixture(engine, async f => {- try { await fn(f); } finally { await engine.unsetConfig(REFRESH_PUBLISH_DIVERGED_KEY); }- }));- }-};-const refusedWith = async (promise: Promise<unknown>, code: string) => {- const error = await promise.then(() => null, e => e as { code?: string; message?: string; suggestion?: string; detail?: string });- expect(error, `expected refusal ${code}`).not.toBeNull();- expect(error!.code).toBe(code);- return error!;-};-const remoteHead = (f: RefreshFixture) => git(f.root, 'ls-remote', 'origin', 'refs/heads/main').split('\t')[0];-/** The upstream moves on while the managed checkout gains a local commit: a diverged checkout. */-function diverge(f: RefreshFixture, local = { path: 'beta/local.md', content: page('Local', 'A local commit nobody pushed.') }): string {- f.push('alpha/two.md', page('Alpha two', 'Upstream side.'));- git(f.root, 'config', 'user.name', 'Example'); git(f.root, 'config', 'user.email', '[email protected]');- writeFileSync(join(f.root, local.path), local.content);- git(f.root, 'add', local.path); git(f.root, 'commit', '-qm', 'local only');- return f.head();-}--test('the setting is a registered knob, default off', () => {- expect(REFRESH_PUBLISH_DIVERGED_KEY).toBe('sources.refresh_publish_diverged');- expect(KNOWN_CONFIG_KEYS).toContain(REFRESH_PUBLISH_DIVERGED_KEY);- expect(KNOWN_CONFIG_KEYS).toEqual(expect.arrayContaining(['sources.refresh_fetch_timeout_ms', 'sources.refresh_drain_wait_ms']));-});--test('setting on: a diverged refresh publishes the local commits merged with the upstream, then fast-forwards and keeps them', () => each(async f => {- const local = diverge(f);- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');- const done = await refreshWorktree(f.engine, f.alpha);- expect(done).toMatchObject({ status: 'completed', old_head: local, published: { local_commits: 1, integrated: 1 } });- expect(done.published!.sha).toBe(remoteHead(f));- expect(done.target_head).toBe(done.published!.sha);- expect(f.head()).toBe(done.published!.sha);- git(f.root, 'merge-base', '--is-ancestor', local, 'HEAD');- expect(readFileSync(join(f.root, 'alpha/two.md'), 'utf8')).toContain('Upstream side.');- expect(readFileSync(join(f.root, 'beta/local.md'), 'utf8')).toContain('A local commit nobody pushed.');- expect(await f.lastCommit(f.alpha)).toBe(done.published!.sha);- expect(await f.lastCommit(f.beta)).toBe(done.published!.sha);-}), 120_000);--test('setting on: the text result names the publish', () => each(async f => {- diverge(f);- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'on');- 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; }- expect(out.join('\n')).toContain('Published 1 local commit(s) merged with 1 upstream commit(s) as ');- expect(out.join('\n')).toContain('Refresh completed');-}), 120_000);--test('setting off (unset or false): the refresh refuses refresh_diverged, pushes nothing and names the setting', () => each(async f => {- const local = diverge(f);- const remote = remoteHead(f);- for (const value of [null, 'false']) {- if (value !== null) await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, value);- const error = await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_diverged');- expect(error.suggestion).toContain('gbrain config set sources.refresh_publish_diverged true');- expect(remoteHead(f)).toBe(remote);- expect(f.head()).toBe(local);- expect(await f.refreshRows()).toEqual([]);- }-}), 120_000);--test('setting on: a conflicting path refuses integrate_conflict naming it, and nothing is pushed, fenced or moved', () => each(async f => {- const local = diverge(f, { path: 'alpha/two.md', content: page('Alpha two', 'Local side.') });- const remote = remoteHead(f);- const lastAlpha = await f.lastCommit(f.alpha);- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');- const error = await refusedWith(refreshWorktree(f.engine, f.alpha), 'integrate_conflict') as { detail?: string; suggestion?: string };- expect(JSON.parse(error.detail!).paths).toEqual(['alpha/two.md']);- expect(error.suggestion).toContain('--keep-checkout');- expect(error.suggestion).toContain('--resolve alpha/two.md=ours|theirs');- expect(remoteHead(f)).toBe(remote);- expect(f.head()).toBe(local);- expect(readFileSync(join(f.root, 'alpha/two.md'), 'utf8')).toContain('Local side.');- expect(git(f.root, 'status', '--porcelain', '--untracked-files=no')).toBe('');- expect(await f.refreshRows()).toEqual([]);- 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 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: the publish runs in a child gbrain, never in this process, so an unusable child refuses and nothing is pushed or fenced', () => each(async f => {- const local = diverge(f);- const remote = remoteHead(f);- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');- const error = await refusedWith(refreshWorktree(f.engine, f.alpha), 'push_unconfirmed');- expect(error.message).toContain('did not report a push');- expect(remoteHead(f)).toBe(remote);- expect(f.head()).toBe(local);- expect(await f.refreshRows()).toEqual([]);-}, '/bin/false'), 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);- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');- await refusedWith(refreshWorktree(f.engine, f.alpha, { dryRun: true }), 'refresh_diverged');- expect(remoteHead(f)).toBe(remote);- expect(f.head()).toBe(local);-}), 120_000);--for (const [label, forget] of [['', false], [' even when the first fetch to see the upstream is the one after the rewrite', true]] as const) {- test(`setting on: an upstream rewritten by a force-push is never published${label}; 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();- if (forget) {- rmSync(git(f.root, 'rev-parse', '--path-format=absolute', '--git-path', 'logs/refs/remotes/origin/main').trim(), { force: true });- await f.engine.executeRaw('DELETE FROM persistence_worktree_refreshes WHERE worktree_id=$1::uuid', [f.worktreeId]);- }- 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);-}--test('setting on, reflog off and no completed refresh: the refusal\'s own fetch records the rewrite, so a second refresh refuses too, and with no record at all it refuses', () => each(async f => {- const reflog = git(f.root, 'rev-parse', '--path-format=absolute', '--git-path', 'logs/refs/remotes/origin/main').trim();- git(f.root, 'config', 'core.logAllRefUpdates', 'false');- rmSync(reflog, { force: true });- f.push('alpha/purged.md', page('Purged', 'A page the upstream later removed by rewriting history.'));- git(f.root, 'fetch', '-q', 'origin'); git(f.root, 'merge', '-q', '--ff-only', 'origin/main');- 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');- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');- for (let run = 0; run < 2; run++) expect((await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_diverged')).message).toContain(`no longer contains ${purged}`);- rmSync(reflog, { force: true });- expect((await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_diverged')).message).toContain('no record of what');- expect(remoteHead(f)).toBe(rewritten);-}), 120_000);--test('setting on: a local commit the upstream held inside a merge, then dropped by a force-push, is never published', () => each(async f => {- const before = remoteHead(f);- writeFileSync(join(f.root, 'beta/local.md'), page('Local', 'Merged upstream from this checkout, then rewritten away.'));- git(f.root, 'add', 'beta/local.md'); git(f.root, 'commit', '-qm', 'local merged upstream');- const local = f.head();- git(f.upstream, 'fetch', '-q', f.root, 'HEAD');- commitFile(f.upstream, 'alpha/side.md', page('Side', 'An upstream commit beside the merge.'));- git(f.upstream, 'merge', '-q', '--no-edit', 'FETCH_HEAD');- git(f.upstream, 'push', '-q', 'origin', 'main');- git(f.root, 'fetch', '-q', 'origin');- git(f.upstream, 'reset', '-q', '--hard', before);- commitFile(f.upstream, 'alpha/two.md', page('Alpha two', 'Rewritten upstream.'));- git(f.upstream, 'push', '-q', '--force', 'origin', 'main');- const rewritten = remoteHead(f);- await f.engine.setConfig(REFRESH_PUBLISH_DIVERGED_KEY, 'true');- expect((await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_diverged')).message).toContain(`no longer contains ${local}`);- expect(remoteHead(f)).toBe(rewritten);- expect(f.head()).toBe(local);-}), 120_000);