Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: say what a webhook capture of a backfill-pending page gets, and give the 60,000-page retire E2E the 4x file budget
garrytan2769269bdc4d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8b1d8ab6f4..ff31437b10 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,16 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [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.++### 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.+## [0.60.627.0] - 2026-11-09**A webhook capture can no longer drop a page's readers (GST-2112).** `POST /ingest` wrote through a trusted local path whose only check was that the sender could read the page, so a member-bound token granted a source could replace a page whose `readable_by` named it with a body that named no readers, and every caller could then read the page. The route and the `ingest_capture` job now apply the remote `put_page` readers rule: a body that drops `readable_by` from a page that names readers, or names readers that leave out the sender, is refused `readable_by_invalid` (403 at the route, nothing queued; at write time for a job already queued). The job binds its write to the revision it checked, so readers added between the check and the write refuse the write with `revision_conflict` and the retry refuses `readable_by_invalid`. A capture already queued from a member-bound credential whose write source is `default` is refused `permission_denied` at write time, as the route refuses it before queueing. Bodies that keep the readers, and pages without readers, import as before.diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 41083194f8..11a3f506ac 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. | 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)). |+| <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>`. || `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/scripts/run-e2e.sh b/scripts/run-e2e.shindex 86bd3ddd6c..d4da149822 100755--- a/scripts/run-e2e.sh+++ b/scripts/run-e2e.sh@@ -449,7 +449,9 @@ for f in "${files[@]}"; docase "$f" in# graduation-crash-*: one graduation per custody or rollback boundary (5-6 SIGKILL-and-resume cases of ~16 s per file).# large-pages-export: five 20 MiB imports per engine on the string path (~240 s on 4 cores, ~340 s on a loaded gate VM).- */large-pages-export.test.ts|*/skills.test.ts|*/serve-http-multi-agent.test.ts|*/graduation-cli*.test.ts|*/graduation-crash-*.test.ts|*/graduation-faults.test.ts|*/graduation-copy.test.ts|*/graduation-legacy-copy.test.ts) file_timeout=$((file_timeout * 4)) ;;+ # source-retire-batched-postgres: a 60,000-page fixture and three retires of it (~120 s on 4 cores; a loaded runner+ # passed 180 s with its third test in flight).+ */source-retire-batched-postgres.test.ts|*/large-pages-export.test.ts|*/skills.test.ts|*/serve-http-multi-agent.test.ts|*/graduation-cli*.test.ts|*/graduation-crash-*.test.ts|*/graduation-faults.test.ts|*/graduation-copy.test.ts|*/graduation-legacy-copy.test.ts) file_timeout=$((file_timeout * 4)) ;;esacif command -v gtimeout >/dev/null 2>&1; thenTIMEOUT_CMD="gtimeout $file_timeout"diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 6c5239af17..d7753c4a32 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1494,7 +1494,7 @@ 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.' },+ { 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>`.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */