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.mdindex 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.mdindex 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 `worktimport moved the page; a blind (`force`) `put_page` or a `capture` lands over it, and its receipt (`supersedes`), itscommit trailer (`gbrain-supersedes: <path>: revision <id> from <commit>`) and the commit ledgername 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 andsubmit 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 releasethat 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.tsindex 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.tsindex 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." },