Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
persistence: add_timeline_entry waits for a pending import too (GST-1582)
garrytanea29d4538ca2
diff --git a/docs/designs/REFRESH_WRITE_BARRIER.md b/docs/designs/REFRESH_WRITE_BARRIER.mdindex 50763c6d76..bb0f094159 100644--- a/docs/designs/REFRESH_WRITE_BARRIER.md+++ b/docs/designs/REFRESH_WRITE_BARRIER.md@@ -190,15 +190,15 @@ barrier exists to keep, and with the flag on each now waits instead (with it offThe row is released when the refresh is resumed or abandoned (both end it `completed` or`aborted`), takes the refresh-change check, and is bound by the same age limit.- **The per-refresh cap.** Removed (see Capacity).-- **`pending_import`.** A `put_page`, `capture` or `remember` whose page file holds a change+- **`pending_import`.** A `put_page`, `capture`, `remember` or `add_timeline_entry` whose page file holds a changecommitted through Git that managed sync has not imported yet was refused at preparation(`source_changed`, reason `pending_import`), after admission. The refusal now carries the lastimported commit the check compared against (read before the check, so a commit the check sawimported is never awaited), and the consumer moves its own claim back to `deferred` with`deferred_import_from` set to that commit (`''` when the source had never imported). The row isreleased when `sources.last_commit` differs from it (and any refresh it also names is released),- then claimed and prepared from scratch, as if it had queued behind the import: a `remember` or- `capture` applies on top; a `put_page` with `expected_revision` meets the moved page and ends+ then claimed and prepared from scratch, as if it had queued behind the import: a `remember`,+ `capture` or `add_timeline_entry` applies on top; a `put_page` with `expected_revision` meets the moved page and ends`revision_conflict`; a blind (`force`) `put_page` lands. An import that lands without coveringthe file only re-arms the hold at the new commit. The receipt reads `queued` with`deferred: { pending_import: true }`, and the caller's wait returns pending at once.diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex e4c4f10649..d108a65e25 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -3420,7 +3420,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 or remember 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 after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. | 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 after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. | 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 aa0f3433dd..2a93a6c547 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -617,11 +617,11 @@ syncing it is accepted and waits for the refresh instead of being refused `workt- A refresh in `recovery_required` holds writes the same way: they wait until the refresh is resumedor abandoned, under the same wait limit. There is no per-refresh cap: deferred writes count againstthe journal's ordinary outstanding and byte limits, like queued ones.-- <a id="pending_import_expired"></a>A `put_page`, `capture` or `remember` whose page file holds a+- <a id="pending_import_expired"></a>A `put_page`, `capture`, `remember` or `add_timeline_entry` whose page file holds acommitted change managed sync has not imported yet ([`pending_import`](#pending_import)) also waitsinstead of being refused: the receipt stays pending with `deferred: { pending_import: true }`, and- once the import lands the write is prepared again against the imported page. A `remember` or- `capture` applies on top; a `put_page` with `expected_revision` ends `revision_conflict` when the+ once the import lands the write is prepared again against the imported page. A `remember`,+ `capture` or `add_timeline_entry` applies on top; a `put_page` with `expected_revision` ends `revision_conflict` when theimport moved the page; a blind (`force`) `put_page` lands, 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 writediff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 0a1abf96a4..07d56feefa 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1456,7 +1456,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: 'TBD', id: 'doctor_foreign_writers_prb', text: 'New doctor check `foreign_writers`: in every source checkout on this host, managed worktrees included, a commit gbrain\'s commit ledger does not name fails the check with the newest such commit and a fix that asks who makes it; an unconfirmed commit (a crash between `git commit` and the ledger line) and page files left uncommitted for over 30 minutes warn. Commits before the ledger started are reported as uncovered, not foreign. A repo-less brain reports not_applicable.' },{ since: 'TBD', id: 'sources_guard_prb', text: 'New `gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]`: the commit guard on a managed source\'s worktree, from its owner host only, installed in a hooks directory private to that worktree. `--mode enforce` also refuses cherry-pick, revert, rebase and sequencer commits. `gbrain git guard` is unchanged.' },{ since: 'TBD', id: 'refresh_barrier_prb', text: 'New setting `persistence.refresh_barrier` (off by default): with it on, a single page write (`put_page`, `remember` and the other single-page verbs) that reaches a checkout while `gbrain sources refresh` drains or merges it is journaled and answered `pending` at once (MCP `isError: false`, CLI exit 10) instead of refused `worktree_refreshing`. It commits after the refresh, or ends `revision_conflict` when the refresh changed its file, or `refresh_barrier_expired` after `persistence.refresh_barrier_max_wait_ms` (15 minutes). Syncs, jobs and batches keep the refusal. `gbrain upgrade --check-downgrade` exits 3 `downgrade_blocked_deferred_writes` while such writes wait.' },- { since: 'TBD', id: 'refresh_barrier_import_gst1582', text: 'With `persistence.refresh_barrier` on, no page write bounces because a sync is running: a `put_page`, `capture` or `remember` whose page file holds a committed change managed sync has not imported yet is answered `pending` (receipt `deferred: { pending_import: true }`) instead of refused `pending_import`, and is prepared again once the import lands (a `put_page` with `expected_revision` then ends `revision_conflict` if the import moved the page; a blind one lands and names the revision and commit it replaced in `supersedes`, a `gbrain-supersedes:` commit trailer and the commit ledger), or ends `pending_import_expired` after the wait limit. A write during a refresh in `recovery_required` waits too, and `persistence.refresh_barrier_max_deferred` is no longer read: no write past it is refused. With the barrier off those refusals are unchanged. Wherever `worktree_refreshing` still refuses, `retry_after_ms` is estimated from the refresh (its typical duration minus how long it has run, at least 15 s while syncing and 2 s otherwise) instead of a fixed 1000, the message says the write was not saved and when to retry, and the CLI\'s human output ends with one line saying the same.' },+ { since: 'TBD', id: 'refresh_barrier_import_gst1582', text: 'With `persistence.refresh_barrier` on, no page write bounces because a sync is running: a `put_page`, `capture`, `remember` or `add_timeline_entry` whose page file holds a committed change managed sync has not imported yet is answered `pending` (receipt `deferred: { pending_import: true }`) instead of refused `pending_import`, and is prepared again once the import lands (a `put_page` with `expected_revision` then ends `revision_conflict` if the import moved the page; a blind one lands and names the revision and commit it replaced in `supersedes`, a `gbrain-supersedes:` commit trailer and the commit ledger), or ends `pending_import_expired` after the wait limit. A write during a refresh in `recovery_required` waits too, and `persistence.refresh_barrier_max_deferred` is no longer read: no write past it is refused. With the barrier off those refusals are unchanged. Wherever `worktree_refreshing` still refuses, `retry_after_ms` is estimated from the refresh (its typical duration minus how long it has run, at least 15 s while syncing and 2 s otherwise) instead of a fixed 1000, the message says the write was not saved and when to retry, and the CLI\'s human output ends with one line saying the same.' },{ since: 'TBD', id: 'commit_push_base_prb', text: '`gbrain git commit-push` takes `--base <path>=<blob>|absent` (repeatable, each path one the command commits): it refuses `commit_base_moved`, committing nothing, when the file at HEAD is no longer the blob the caller read. Without `--base` nothing changes.' },{ since: 'TBD', 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: 'TBD', 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.' },diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex d3a3406069..9810fcfbc0 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -663,7 +663,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 or remember 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 after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied.", 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 after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied.", 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." },diff --git a/src/core/persistence/import-deferral.ts b/src/core/persistence/import-deferral.tsindex 3aae427856..d8a38f2c56 100644--- a/src/core/persistence/import-deferral.ts+++ b/src/core/persistence/import-deferral.ts@@ -1,9 +1,9 @@/*** GST-1582 (docs/designs/REFRESH_WRITE_BARRIER.md, "Writes that wait for an import"): with the refresh write barrier on, a- * put_page, capture or remember whose page file holds a committed change managed sync has not imported yet is not refused+ * put_page, capture, remember or add_timeline_entry whose page file holds a committed change managed sync has not imported yet is not refused* `pending_import`. The consumer moves its own claim back to `deferred`, naming the source's last imported commit, and the* row waits (invisible to claims, journal.ts RELEASED_DEFERRED) until `sources.last_commit` moves past it. It is then- * prepared again from scratch, as if it had queued behind the import: a remember or capture applies on top, a put_page+ * prepared again from scratch, as if it had queued behind the import: a remember, capture or add_timeline_entry applies on top, a put_page* with expected_revision ends revision_conflict when the import moved the page, and a blind put_page lands. A blind* put_page that replaces content the import brought in names what it replaced (`supersedes`) on its receipt, in a* `gbrain-supersedes:` commit trailer and on the commit ledger line; the replaced revision stays in page history and@@ -18,7 +18,7 @@ import { landedCommit } from './pending-import.ts';import { PERSISTENCE_PROTOCOL_PREDICATE } from './protocol.ts';import { writeSwitchOn } from './switches.ts';-const IMPORT_HELD_OPERATIONS = ['put_page', 'capture', 'remember'];+const IMPORT_HELD_OPERATIONS = ['put_page', 'capture', 'remember', 'add_timeline_entry'];export const SUPERSEDES_TRAILER_KEY = 'gbrain-supersedes';/**diff --git a/test/import-write-barrier.test.ts b/test/import-write-barrier.test.tsindex a72bbafd6d..599ff7e7a3 100644--- a/test/import-write-barrier.test.ts+++ b/test/import-write-barrier.test.ts@@ -2,9 +2,9 @@* GST-1582: a page write never bounces because a sync is running (docs/designs/REFRESH_WRITE_BARRIER.md, "Writes that* wait for an import").*- * Protects: with persistence.refresh_barrier on, a put_page, capture or remember whose page file holds a committed change+ * Protects: with persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a committed change* managed sync has not imported yet (`pending_import`) is held `deferred` and answered pending, then published by itself- * once the import lands, prepared again as if it had queued behind the import: remember applies on top, a put_page with+ * once the import lands, prepared again as if it had queued behind the import: remember and add_timeline_entry apply on top, a put_page with* expected_revision (what a remote caller must send for an existing page) ends revision_conflict, a blind (force) put_page or capture lands, and a put_page's receipt,* its commit trailer and the commit ledger name the imported revision and commit it replaced (both stay in page history and git). A write admitted while a* refresh is in recovery_required waits behind it and lands once the refresh is released. A held write whose import never@@ -162,6 +162,20 @@ test('a remember onto a file awaiting import lands on top of the imported page',expect(content).toContain('alice-example likes tea');}), 180_000);+test('an add_timeline_entry onto a file awaiting import lands on top of the imported page', () => each(async f => {+ foreignCommit(f, 'one.md', page('Alpha one', IMPORTED));+ const out = await call(f, 'add_timeline_entry', { slug: 'one', date: '2026-11-06', summary: 'Entry added while the import waited.' });+ expect(out.isError).toBe(false);+ expect(out.body.status).toBe('pending');+ const held = await requestRow(f, out.body.request_id);+ expect(held.state).toBe('deferred');+ await importNow(f);+ expect((await settle(f, held)).state).toBe('committed');+ const content = file(f, 'one.md');+ expect(content).toContain(IMPORTED);+ expect(content).toContain('Entry added while the import waited.');+}), 180_000);+test('a put_page with expected_revision onto a file awaiting import ends revision_conflict once the import moved the page', () => each(async f => {const seen = (await f.engine.readPageSnapshot('one', { sourceId: f.alpha }))!.revision;foreignCommit(f, 'one.md', page('Alpha one', IMPORTED));