Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: pending_import_expired hold ceiling, conditional remember replay and later-write revision_conflict (ship docs audit)

garrytanb4f663b42c5f
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index d84a55057f..3038d6c9c0 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -3440,7 +3440,7 @@ More: [docs/guides/dream-patterns.md#cadence](../../docs/guides/dream-patterns.m
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit. | With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once it has been held for persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. A remember ends as its pending_import refusal did instead, and is replayed after the import. | Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id. | provider | `repeat the read that failed` | 1 | no |
+| A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit. | With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once one hold has lasted persistence.refresh_barrier_max_wait_ms (15 minutes by default), or once it has waited four of those limits (at least 4 hours) since its admission across repeated holds. Nothing was applied. A remember ends as its pending_import refusal did instead: one that named its entity is replayed by the first sync that imports the file, and gbrain repair failed-writes lists the rest for a person to replay. | Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id. | provider | `repeat the read that failed` | 1 | no |
More: [docs/guides/write-refusals.md#pending_import_expired](../../docs/guides/write-refusals.md#pending_import_expired)
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index a6ec9bf35b..0b9e8497ba 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -625,12 +625,18 @@ syncing it is accepted and waits for the refresh instead of being refused `workt
import moved the page; a blind (`force`) `put_page` or a `capture` lands over it, and its receipt (`supersedes`), its
commit trailer (`gbrain-supersedes: <path>: revision <id> from <commit>`) and the commit ledger
name the imported revision and commit it replaced, both still in page history and Git. A write
- whose import has not landed within the wait limit of its hold ends `failed` with `pending_import_expired`,
+ whose import has not landed within the wait limit of its hold, or that has waited four wait limits (at least
+ 4 hours) since its admission across repeated holds, ends `failed` with `pending_import_expired`,
nothing applied: check `gbrain sync status --source <source> --json`, then read the page again and
submit with a new request ID. A `remember` ends as the [`pending_import`](#pending_import) refusal
- did instead: the fact is kept, the first sync that imports the file replays it, and the caller does
- not save it again. A write keeps the refusal when a live consumer on the owner host runs a release
+ did instead: the fact is kept and the caller does not save it again. When it named its entity, the
+ first sync that imports the file replays it; otherwise `gbrain repair failed-writes --source <source>`
+ lists it for a person to replay. A write keeps the refusal when a live consumer on the owner host runs a release
that cannot claim a held write.
+- A write that waited behind a refresh or for an import ends `revision_conflict`, nothing applied, when a
+ later write to the same page (anything but `remember` or `add_timeline_entry`) committed before it,
+ which a consumer from an older release can cause by claiming the later write first. Read the page
+ again and submit the change with a new request ID.
- Still refused as before: batches (`put_pages`, `remember` with `items`), jobs, skill bundles,
and any brain where a live consumer on the owner host runs a release without the barrier.
Repo-less brains and database-only sources never wait.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 54b6953013..853b85f12a 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1475,7 +1475,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.594.0', id: 'file_drift_held_needs_prefer_8615', text: '`gbrain repair file-drift` with `--held`, `--side`, `--state`, `--cursor` or `--provenance` and no `--prefer` now refuses with the usage line (`invalid_params`, and `file_drift_state_required` for a deleted side without `--state`) instead of silently running the all-drifted survey, which counted a different set of pages (#8615).' },
{ since: '0.60.594.0', id: 'refresh_source_changed_retry_8617', text: 'A `gbrain sources refresh` run refused `refresh_source_changed` because the checkout HEAD moved (a writer committing) or work reached the checkout after the drain check now retries once from a fresh precheck in the same run, so the tick is not lost (#8617). When the retry is refused too, the run returns the first `refresh_source_changed` refusal with the retry\'s cause appended; ownership or source-membership changes are not retried.' },
{ since: '0.60.594.0', id: 'commit_push_checkout_not_a_source_8662', text: '`gbrain git commit-push` now refuses `checkout_not_a_source` before staging anything when this brain home records its source checkouts (a managed brain) and the checkout it resolved from the working directory (no `--path`) is none of them and has no `gbrain.sourceRoot`, for example a wrapper that changed into another repository (#8662). The refusal names the resolved path and the brain\'s checkouts; pass `--path` with the absolute brain checkout. Hosts whose brain records no source checkout behave as before.' },
- { since: '0.60.608.0', id: 'refresh_barrier_later_write_gst1623', text: 'With `persistence.refresh_barrier` on, a write that waited behind a refresh or an import now ends `revision_conflict` instead of applying when a later write to the same page (other than `remember` or `add_timeline_entry`) committed first, which a consumer from an older release can cause; read the page again and resubmit with a new `request_id`. A write held again and again behind imports now expires at the wait limit counted from its admission. With the barrier on or off, a plain-git commit that lands on the start commit right before a refresh merges makes git refuse the fast-forward, and the refresh now ends `refresh_source_changed` with the fence lifted and the commit kept, instead of leaving the checkout `recovery_required`; one that lands right after the merge is recorded and synced.' },
+ { since: '0.60.608.0', id: 'refresh_barrier_later_write_gst1623', text: 'With `persistence.refresh_barrier` on, a write that waited behind a refresh or an import now ends `revision_conflict` instead of applying when a later write to the same page (other than `remember` or `add_timeline_entry`) committed first, which a consumer from an older release can cause; read the page again and resubmit with a new `request_id`. A write held again and again behind imports now expires once it has waited four wait limits (at least 4 hours) since its admission, even when each hold is shorter than one wait limit. With the barrier on or off, a plain-git commit that lands on the start commit right before a refresh merges makes git refuse the fast-forward, and the refresh now ends `refresh_source_changed` with the fence lifted and the commit kept, instead of leaving the checkout `recovery_required`; one that lands right after the merge is recorded and synced.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index cde8952c97..24093bca22 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -665,7 +665,7 @@ export const CODES = {
refresh_no_upstream: { class: 'caller', summary: "The worktree has no upstream to refresh from." },
refresh_not_managed: { class: 'host_only', summary: "The source is not managed, so it cannot be refreshed." },
refresh_not_owner: { class: 'host_only', summary: "This process does not own the worktree it would refresh." },
- pending_import_expired: { class: 'caller', actor: 'provider', summary: "A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit.", why: "With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once it has been held for persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. A remember ends as its pending_import refusal did instead, and is replayed after the import.", docs: 'docs/guides/write-refusals.md#pending_import_expired', suggestion: 'Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id.' },
+ pending_import_expired: { class: 'caller', actor: 'provider', summary: "A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit.", why: "With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once one hold has lasted persistence.refresh_barrier_max_wait_ms (15 minutes by default), or once it has waited four of those limits (at least 4 hours) since its admission across repeated holds. Nothing was applied. A remember ends as its pending_import refusal did instead: one that named its entity is replayed by the first sync that imports the file, and gbrain repair failed-writes lists the rest for a person to replay.", docs: 'docs/guides/write-refusals.md#pending_import_expired', suggestion: 'Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id.' },
refresh_barrier_expired: { class: 'caller', actor: 'provider', summary: "A write that waited behind a worktree refresh was not applied, because the refresh was still unfinished after the barrier's wait limit.", why: "With persistence.refresh_barrier on, a page write that reaches a refreshing checkout is accepted and waits for the refresh to end. A refresh that never ends (a stuck member sync, a host that stopped) would hold those writes forever, so the owner finishes each one failed after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied.", docs: 'docs/guides/write-refusals.md#deferred-writes', suggestion: 'Check the refresh with gbrain sources writer status --source <id> --json, then submit the write again with a new request_id.' },
refresh_source_changed: { class: 'caller', summary: "The source changed during the refresh." },
refresh_sync_timeout: { class: 'retryable', summary: "A refresh's member sync committed nothing within the refresh sync budget." },