Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: an orphaned worktree refresh recovers on the next refresh; another host's holder is never adopted (#7679)

garrytanfa0ece015e04
diff --git a/docs/guides/live-sync.md b/docs/guides/live-sync.md
index fde4ec7a10..f532f585b0 100644
--- a/docs/guides/live-sync.md
+++ b/docs/guides/live-sync.md
@@ -653,8 +653,15 @@ vars — incident-time escape hatches, not everyday knobs.
`--wait-drain <seconds>` (default 60; `sources.refresh_drain_wait_ms`,
`GBRAIN_REFRESH_DRAIN_WAIT_MS`) and `--fetch-timeout-ms` (default 120000;
`sources.refresh_fetch_timeout_ms`, `GBRAIN_REFRESH_FETCH_TIMEOUT_MS`).
- A refresh interrupted by a crash is finished by the restarted owner or by
- `gbrain sources refresh <source-id> --resume`. A cron that keeps a managed
+ A refresh whose process died (a crash, a replaced container) does not
+ wedge the checkout: the owner finishes what it can on its own, and the next
+ `gbrain sources refresh <source-id>` on the owner host finishes the rest
+ the way `gbrain sources refresh <source-id> --resume` does before its own
+ refresh. A refresh whose process is still running is never taken over, and
+ one whose HEAD cannot be verified waits for the user
+ ([`refresh_recovery_required`](write-refusals.md#refresh_recovery_required)).
+ `gbrain sources writer status <source-id>` shows who holds a refresh and
+ whether it is orphaned. A cron that keeps a managed
brain current runs the refresh instead of `git pull`, through the same
[wrapper](cron-schedule.md#calling-gbrain-unattended) as every other
scheduled gbrain call (so it runs as the owner host). `refresh_diverged`
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 74ea98466d..2b4be8749c 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -519,7 +519,7 @@ this anchor (`--json` puts them in one object on stdout); the command exits 1.
| <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). 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. |
+| <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. |
| <a id="refresh_drain_timeout"></a>`refresh_drain_timeout` | `refresh_drain_timeout` | Queued writes or Git effects on the checkout did not finish within `--wait-drain` (default 60 s; `sources.refresh_drain_wait_ms`; `GBRAIN_REFRESH_DRAIN_WAIT_MS`). The counts are in the message. The fence was lifted and HEAD did not move. | Retry, or wait longer with `--wait-drain <seconds>`. Inspect what is queued with `gbrain sources writer status <source> --json`. |
| <a id="refresh_source_changed"></a>`refresh_source_changed` | `refresh_source_changed` | HEAD moved (an outside commit or checkout), or the checkout's ownership or set of sources changed, between the precheck and the merge. Nothing was merged and the fence was lifted. | Retry `gbrain sources refresh <source>`. |
| <a id="refresh_recovery_required"></a>`refresh_recovery_required` | `refresh_recovery_required` | Publication or source recovery is pending on the checkout, or a refresh was interrupted and HEAD is neither the commit it started from nor the verified upstream commit. Writes to the checkout stay refused until it is resolved; gbrain never adopts a HEAD it cannot verify. | `gbrain sources writer status <source>`, then `gbrain sources refresh <source> --resume`. When HEAD is unverified the fix names both ways out: reset to the start commit and run `--abandon`, or reset to the upstream commit and run `--resume`. Resetting is destructive, so ask the user first. |
diff --git a/llms-full.txt b/llms-full.txt
index f6a7602ed8..76575d3143 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -7696,8 +7696,15 @@ vars — incident-time escape hatches, not everyday knobs.
`--wait-drain <seconds>` (default 60; `sources.refresh_drain_wait_ms`,
`GBRAIN_REFRESH_DRAIN_WAIT_MS`) and `--fetch-timeout-ms` (default 120000;
`sources.refresh_fetch_timeout_ms`, `GBRAIN_REFRESH_FETCH_TIMEOUT_MS`).
- A refresh interrupted by a crash is finished by the restarted owner or by
- `gbrain sources refresh <source-id> --resume`. A cron that keeps a managed
+ A refresh whose process died (a crash, a replaced container) does not
+ wedge the checkout: the owner finishes what it can on its own, and the next
+ `gbrain sources refresh <source-id>` on the owner host finishes the rest
+ the way `gbrain sources refresh <source-id> --resume` does before its own
+ refresh. A refresh whose process is still running is never taken over, and
+ one whose HEAD cannot be verified waits for the user
+ ([`refresh_recovery_required`](write-refusals.md#refresh_recovery_required)).
+ `gbrain sources writer status <source-id>` shows who holds a refresh and
+ whether it is orphaned. A cron that keeps a managed
brain current runs the refresh instead of `git pull`, through the same
[wrapper](cron-schedule.md#calling-gbrain-unattended) as every other
scheduled gbrain call (so it runs as the owner host). `refresh_diverged`