Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: a revision_backfill_pending refusal names gbrain apply-migrations --force-schema

garrytane16dda5edc8d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff31437b10..0d74360eb9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,13 +12,15 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**The write-refusal guide and the upgrade notice now say what happens to a webhook capture of a page the revision backfill has not reached (follow-up to GST-2112).** Since v0.60.627.0, `POST /ingest` with `X-Gbrain-Slug` answers such a capture 409 `revision_backfill_pending` and stores and queues nothing, so the capture exists only with its sender; an `ingest_capture` job already in the queue refuses at write time and ends `dead` with its body kept. Neither was written down. `docs/guides/write-refusals.md` and the v0.60.627.0 upgrade notice row now say it, with the recovery: `gbrain apply-migrations --force-schema` on the brain host, then send a capture that got the 409 again and re-run a dead job with `gbrain jobs retry <id>`. The E2E runner also gives `test/e2e/source-retire-batched-postgres.test.ts` (60,000 pages) the 4x per-file budget: on a loaded CI runner it ran past the 180 s cap and was killed with its third test in flight and no failed assertion.
+**A `revision_backfill_pending` refusal now names the command that actually resumes the backfill, and the write-refusal guide says what a webhook capture of such a page gets (follow-up to GST-2112).** The refusal's message, which is also the body of the 409 `POST /ingest` answers for a page the revision backfill has not reached and the error a dead `ingest_capture` job keeps, said `gbrain apply-migrations --yes`, which does not resume the backfill once the schema is current, and linked a section that does not cover it. It now says `gbrain apply-migrations --force-schema` on the brain host and links `docs/guides/write-refusals.md#revision-backfill`. Since #8940 that 409 stores and queues nothing, so the capture exists only with its sender, and an `ingest_capture` job already queued for such a page goes straight to `dead`; neither was written down. The guide's `revision_backfill_pending` row and a new upgrade notice row now say both, with the recovery: resume the backfill, send a capture that got the 409 again, and re-run a dead job with `gbrain jobs retry <id>`. The E2E runner also gives `test/e2e/source-retire-batched-postgres.test.ts` (60,000 pages) the 4x per-file budget: on a loaded CI runner it ran past the 180 s cap and was killed with a test in flight and no failed assertion.
### Itemized changes
-- `docs/guides/write-refusals.md`: the `revision_backfill_pending` row covers the 409 at `POST /ingest` and the dead `ingest_capture` job, with the resend and `gbrain jobs retry <job id>` recovery.
-- `src/core/behavior-change-notice.ts`: the `ingest_keeps_readers_gst2112` row names the 409 and its recovery.
-- `scripts/run-e2e.sh`: `source-retire-batched-postgres.test.ts` joins the 4x per-file budget list. No test or assertion changed.
+- `src/core/page-state/types.ts`: `RevisionBackfillPendingError`'s message names `gbrain apply-migrations --force-schema` and the `#revision-backfill` anchor, matching the error registry's fix.
+- `docs/guides/write-refusals.md`: the `revision_backfill_pending` row covers the 409 at `POST /ingest`, the `ingest_capture` job that goes straight to `dead`, and the resend and `gbrain jobs retry <job id>` recovery.
+- `src/core/behavior-change-notice.ts`: one row for the changed message and the recovery.
+- `scripts/run-e2e.sh`: `source-retire-batched-postgres.test.ts` joins the 4x per-file budget list. No assertion in that file changed.
+- Tests: `test/ingest-capture-keeps-readers.test.ts` checks that the 409 body and the job's refusal name `--force-schema` and the anchor.
## [0.60.627.0] - 2026-11-09
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 11a3f506ac..83077fc06f 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -142,7 +142,7 @@ a receipt can report has a row here.
| `revision_changed` | `revision_changed` | An `append_page` with `expected_revision`, or a `commit_page_upload` whose session was bound to a revision, found the page at a newer revision. Nothing was appended or written, and the upload session is aborted with its staged bytes released. | Read the page again (`get_page` with `body: 'none'`), check whether the text is still missing, then append against the new revision with a new `request_id` (for an upload, begin a new session). |
| <a id="tail_changed"></a>`tail_changed` | `tail_changed` | An `append_page` with `expected_tail_sha256` found a different page end: another writer appended or edited first. Nothing was appended. | Read the page again (`get_page` with `body: 'none'` returns `tail_sha256`), check whether the text is still missing, and append against the current tail with a new `request_id`. |
| `sync_cursor_replaced` | `sync_cursor_replaced` | A managed sync checkpoint found that another sync run of the same source (a rediscovery, a newer sync) replaced the cursor it belongs to, so it had nothing left to publish. The receipt is a conflict; no managed-sync failure is recorded for it, and the run that awaited it goes on with the cursor that now covers the source. | Nothing: let the current sync finish. `gbrain sync status --source <id> --json` shows that cursor. A same-run index lag keeps reporting `revision_conflict`. |
-| <a id="revision-backfill"></a>`revision_backfill_pending` | `revision_backfill_pending` | The page was written before page revisions existed (an upgrade from below schema v150) and the resumable revision backfill has not reached it, so it has no revision to bind to. Its revision reads as `backfill_pending`, never a UUID. Nothing was written. `gbrain doctor` reports the backfill as `revision_backfill` with the pending count and any failed rows by page. A webhook capture of such a page (`POST /ingest` with `X-Gbrain-Slug`) is answered 409 `revision_backfill_pending`: nothing is stored and nothing is queued, so the capture exists only with its sender. An `ingest_capture` job already in the queue refuses the same way at write time, keeps its body in the job row and ends `dead` after its attempts (GST-2112). | Resume the backfill on the brain host with `gbrain apply-migrations --force-schema` (it prints its progress; `--yes` alone does not resume it once the schema is current). Rows that used all three attempts are no longer retried: run `gbrain repair orphan-children` to preview orphaned child rows and torn page bodies ([orphan children](repair.md#orphan-children)). After the backfill reaches the page, send a capture that got the 409 again, and re-run a dead `ingest_capture` job with `gbrain jobs retry <job id>`. |
+| <a id="revision-backfill"></a>`revision_backfill_pending` | `revision_backfill_pending` | The page was written before page revisions existed (an upgrade from below schema v150) and the resumable revision backfill has not reached it, so it has no revision to bind to. Its revision reads as `backfill_pending`, never a UUID. Nothing was written. `gbrain doctor` reports the backfill as `revision_backfill` with the pending count and any failed rows by page. A webhook capture of such a page (`POST /ingest` with `X-Gbrain-Slug`) is answered 409 `revision_backfill_pending`: nothing is stored and nothing is queued, so the capture exists only with its sender. An `ingest_capture` job already in the queue refuses the same way at write time and goes straight to `dead` on its first attempt (the refusal does not change on retry); its body stays in the job row until `gbrain jobs prune` removes it (dead jobs older than 30 days by default) (GST-2112). | Resume the backfill on the brain host with `gbrain apply-migrations --force-schema` (it prints its progress; `--yes` alone does not resume it once the schema is current). Rows that used all three attempts are no longer retried: run `gbrain repair orphan-children` to preview orphaned child rows and torn page bodies ([orphan children](repair.md#orphan-children)). After the backfill reaches the page, send a capture that got the 409 again, and re-run a dead `ingest_capture` job with `gbrain jobs retry <job id>`. |
| `idempotency_conflict` | `idempotency_conflict` | The `request_id` was already used for a different target, content or protocol. | Use a new `request_id` for a different write; reuse an ID only to replay the same write. |
| <a id="write_pending"></a>`write_pending` | `write_pending` (CLI exit 10) | The write was accepted but has not committed yet. It keeps its request ID and may still commit. The CLI exits 10, not 1; a lost acknowledgment with no receipt is `submission_status: "unknown"` and exits 1. See [CLI exit status for writes](../protocol/MEMORY_VERBS_v1.md#cli-exit-status-for-writes). | Poll `gbrain call get_write_request '{"request_id":"<id>"}'`, or repeat the same command with the same `--request-id` and a longer `--wait <seconds>`. Scripts that only need the write admitted pass `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) to exit 0, except for a receipt whose `diagnostic.owner` names a stale owner, which still exits 10 ([stale owner](troubleshooting.md#owner-host-stale)). |
| <a id="invalid_write_wait"></a>`invalid_write_wait` | `invalid_write_wait` | `GBRAIN_WRITE_WAIT_MS` or `persistence.write_wait_ms` is not a whole number of milliseconds from 0 to 600000. Nothing was written. | `unset GBRAIN_WRITE_WAIT_MS` (or set it to e.g. `30000`), or `gbrain config set persistence.write_wait_ms 30000`. |
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index d7753c4a32..8df66c77da 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1494,7 +1494,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.622.0', id: 'purge_cancels_deferred_write_gst1602', text: 'With `persistence.refresh_barrier` on, `gbrain forget <id> --purge` no longer refuses `purge_blocked_pending_recovery` while a write deferred behind a refresh holds the claim in its staged body: the deferred write was never claimed, so the purge cancels it with `purged_content`, as it does a queued one, and removes the content at once instead of up to 15 minutes later.' },
{ since: '0.60.623.0', id: 'owner_reads_private_gst2059', text: 'A brain can now name its owner: `gbrain access owner set <member>` (config `access.owner_member`, an enabled member). Every remote credential or stdio server bound to that member reads the whole brain, `visibility: private` pages, privacy-alias pages (`access: private`, ...), derived and pinned-question pages included, through `get_page`, `search`, `query`, `recall` and the other page reads in the sources its grant reads, and `recall` returns its private facts. `readable_by` and folder rules still bind it, and it is not relaxed when it speaks for a shared-room audience. A page the owner\'s credential creates in `default` through `put_page` is not kept to the owner (no `readable_by: [member:<id>]`). Other members, unbound and public callers are unchanged. `_meta.access.relaxation` reads `owner` for such a call, and `gbrain access check --token <name>` reports it. `gbrain repair private-labels` (named runs only) previews the `access: private` labels stamped on ordinary pages with counts per category, keeps real restrictions, and clears the rest in reviewed batches (`--apply --expect <hash>`), recording each change so `--class restore` can put it back. The bulk-ingestion page template no longer writes an `access:` line; what each designation means is in docs/guides/access-designations.md.' },
{ since: '0.60.626.0', id: 'record_origin_checkout_lockdown_8888', text: '`gbrain sources record-origin <id>... --remote --apply` now also turns git-lfs downloads and hooks off in each recorded source\'s existing checkout (its `.git/config`: `lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`), not only on later reclones, in the repository\'s shared config, and refuses `write_failed` naming the key when a worktree-scoped or included setting still overrides one; a source already recorded as remote gets the lock-down on the next `--remote --apply` when its checkout lacks it, even when its files now use git-lfs, and a key that holds several values in that config is replaced by the one clone-time value. On a managed brain it takes the same worktree locks a reclone takes, refusing the id `source_busy` while a reclone, refresh or write holds them, and a reclone reads the record under its own locks. A write that fails is reported for its own id (`write_failed`) instead of ending the run. The git-lfs check reads a committed `.gitattributes` under a directory whose name holds a tab, ignores commented-out `filter=lfs` lines, says when a committed rule only declares an LFS filter, records a clone of an empty repository instead of refusing it, and names the cause of an `lfs_unknown` refusal.' },
- { since: '0.60.627.0', id: 'ingest_keeps_readers_gst2112', text: 'A webhook capture (`POST /ingest` with `X-Gbrain-Slug` and its `ingest_capture` job) is now refused `readable_by_invalid` when its body drops `readable_by` from a page that names readers, or names readers that leave out the sending token or client: the route answers 403 and queues nothing, and a job already queued refuses at write time. Before, such a capture replaced the page and its readers, and every caller could read it. Bodies that keep the readers, and pages without readers, import as before. A capture of a page the revision backfill has not reached is answered 409 `revision_backfill_pending` and stores nothing: send it again after `gbrain apply-migrations --force-schema`; a job already queued ends dead and is re-run with `gbrain jobs retry <id>`.' },
+ { since: '0.60.627.0', id: 'ingest_keeps_readers_gst2112', text: 'A webhook capture (`POST /ingest` with `X-Gbrain-Slug` and its `ingest_capture` job) is now refused `readable_by_invalid` when its body drops `readable_by` from a page that names readers, or names readers that leave out the sending token or client: the route answers 403 and queues nothing, and a job already queued refuses at write time. Before, such a capture replaced the page and its readers, and every caller could read it. Bodies that keep the readers, and pages without readers, import as before.' },
+ { since: 'TBD', id: 'ingest_backfill_409_recovery_gst2112', text: 'A `revision_backfill_pending` refusal (a write to a page the revision backfill has not reached, including the 409 a webhook capture to such a page gets from `POST /ingest`) now names the command that resumes the backfill, `gbrain apply-migrations --force-schema` on the brain host, instead of `gbrain apply-migrations --yes`, which does not resume it once the schema is current. A capture answered 409 stores and queues nothing, so its sender sends it again after the backfill; an `ingest_capture` job already queued for such a page goes straight to dead and is re-run with `gbrain jobs retry <id>`.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/page-state/types.ts b/src/core/page-state/types.ts
index 49e0fa3ff4..c626097f54 100644
--- a/src/core/page-state/types.ts
+++ b/src/core/page-state/types.ts
@@ -108,7 +108,7 @@ export class RevisionBackfillPendingError extends PageRevisionConflictError {
constructor(expectedRevision: string | null) {
super(expectedRevision, REVISION_BACKFILL_PENDING);
this.message = 'This page has no revision yet: the revision backfill for pages written before the upgrade has not reached it. '
- + 'Resume it with: gbrain apply-migrations --yes (see docs/guides/write-refusals.md#other-error-codes).';
+ + 'Resume it on the brain host with: gbrain apply-migrations --force-schema (see docs/guides/write-refusals.md#revision-backfill).';
this.name = 'RevisionBackfillPendingError';
}
}
diff --git a/test/ingest-capture-keeps-readers.test.ts b/test/ingest-capture-keeps-readers.test.ts
index 71f9ce78a0..ecd417d071 100644
--- a/test/ingest-capture-keeps-readers.test.ts
+++ b/test/ingest-capture-keeps-readers.test.ts
@@ -212,9 +212,12 @@ describe('a webhook capture keeps a page\'s stored readers (GST-2112)', () => {
const before = await queuedJobs();
const res = await ingest(BACKFILL, page('Backfill pending', READERS, 'Posted before the backfill.'));
expect(res.status).toBe(409);
- expect((await res.json() as { error: string }).error).toBe('revision_backfill_pending');
+ const answer = await res.json() as { error: string; message: string };
+ expect(answer.error).toBe('revision_backfill_pending');
+ expect(answer.message).toContain('gbrain apply-migrations --force-schema');
+ expect(answer.message).toContain('docs/guides/write-refusals.md#revision-backfill');
expect(await queuedJobs()).toBe(before);
- await expect(makeIngestCaptureHandler(engine)(bobJob(BACKFILL, page('Backfill pending', READERS, 'Captured before the backfill.')))).rejects.toMatchObject({ code: 'revision_backfill_pending' });
+ await expect(makeIngestCaptureHandler(engine)(bobJob(BACKFILL, page('Backfill pending', READERS, 'Captured before the backfill.')))).rejects.toMatchObject({ code: 'revision_backfill_pending', message: expect.stringContaining('gbrain apply-migrations --force-schema') });
expect(await readers(BACKFILL)).toEqual(['alice-example', 'bob-example']);
expect((await stored(BACKFILL))?.compiled_truth).toContain('Original body.');
} finally {