Skip to content

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.md
index 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 off
The 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 change
committed 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 last
imported commit the check compared against (read before the check, so a commit the check saw
imported 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 is
released 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 covering
the 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.md
index 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.md
index 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 resumed
or abandoned, under the same wait limit. There is no per-refresh cap: deferred writes count against
the 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 a
committed change managed sync has not imported yet ([`pending_import`](#pending_import)) also waits
instead 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 the
import moved the page; a blind (`force`) `put_page` lands, 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
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 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.ts
index 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.ts
index 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.ts
index 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));