Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
W3: keep llms-full.txt under its budget; shorter troubleshooting rows
garrytand29f01d06820
diff --git a/docs/guides/cron-schedule.md b/docs/guides/cron-schedule.mdindex 654ab73446..8c38f2ec88 100644--- a/docs/guides/cron-schedule.md+++ b/docs/guides/cron-schedule.md@@ -381,9 +381,7 @@ times (default 3; `0` disables) within 24 hours is refused before the nextsubmission, and `gbrain doctor` reports it as `dream_paid_loop`. Fix thecause first (a missing provider key, a quota, a failing transcript), then`gbrain dream reset-key --list` shows the refused keys and-`gbrain dream reset-key '<key>'` re-enables one. A purge or consolidate write-still pending after its publish wait is deferred and reconciled on the next-pass instead of failing the cycle (`dream_write_deferred` after 3 passes). Details in+`gbrain dream reset-key '<key>'` re-enables one. Details in[spend controls](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).Three more fields answer "what did that cost and did it land":diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex 74402452eb..709b3a9d95 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -82,8 +82,8 @@| `gbrain init` or `gbrain upgrade` stops with `schema_lock_blocked` naming a pid (or, before #5227, sat in `wait_event_type=Lock` with no output) | let the named session finish, or with the user's agreement end it on the database host: `SELECT pg_terminate_backend(<pid>)`; then rerun the same command ([ENGINES.md](../ENGINES.md#schema-lock-blocked)) | brain host, after the user agrees | `destructive` when it ends another session | the rerun completes; `gbrain doctor --json` shows the schema at head || [`queue_capacity`, `persistence_capacity` or `persistence_request_growth`](#write-capacity) | run the printed `gbrain config set persistence.limits.<limit> <value>` | brain host | none | `gbrain doctor --only persistence_capacity,persistence_request_growth --json` || [`dream_paid_loop`, or dream keeps skipping one transcript](#dream-paid-loop) | fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'` | agent, after the user agrees | `paid` (the key is retried) | `gbrain doctor --only dream_paid_loop --json` |-| [`dream_write_deferred`: a purge or consolidate write is still pending after 3 passes](#dream-write-deferred) | read the receipt it names (`gbrain write-request -- <id>`), then `gbrain sources writer status --source <id> --json` | agent | none | `gbrain doctor --only dream_write_deferred --json` |-| [`embedding_restamp_stalled`](#embedding-restamp-stalled) | fix the error it names, then `gbrain dream --phase embed --json` | agent | `paid` only for stale chunks the embed phase embeds | `gbrain doctor --only embedding_restamp_stalled --json` |+| [`dream_write_deferred`](#dream-write-deferred) | `gbrain write-request -- <id>`, then `gbrain sources writer status --source <id> --json` | agent | none | `gbrain doctor --only dream_write_deferred --json` |+| [`embedding_restamp_stalled`](#embedding-restamp-stalled) | fix the named error, then `gbrain dream --phase embed --json` | agent | `paid` for stale chunks only | `gbrain doctor --only embedding_restamp_stalled --json` || [A page exists (`gbrain get <slug>` returns it) but search never finds text from it](memory-boundaries.md#large-pages) | `gbrain reindex --oversized --dry-run --json` lists pages stored before the upgrade with a size-based `embed_skip` marker (without `--dry-run` it keyword-indexes them, free); a page above an operator-lowered `content_sanity.bytes_block` keeps its marker until it is raised; a page the content-quality gate quarantined shows in `gbrain quarantine list` (`gbrain quarantine clear <slug>` re-checks it once the user agrees); a file over the 24 MiB page ceiling was never stored ([`file_too_large`](write-refusals.md#file_too_large)). Its chunks waiting for embedding approval (doctor `partial_embedding`) are a paid step: `gbrain embed --held --dry-run`, then `gbrain embed --held --source <id> --max-usd <N>` as printed | agent for the reindex; the user decides embedding spend, a `bytes_block` change and a quarantine clear | none for the reindex; `paid` for `gbrain embed` | `gbrain reindex --oversized --dry-run --json` lists nothing; `gbrain search "<phrase from deep in the page>"` returns the page || [Search answers look keyword-only on a large Postgres brain](#hybrid-search-returns-only-keyword-hits) | read doctor's `vector_plan`; run the index command it prints | brain host | none | `gbrain doctor --only vector_plan --json` || [Broad keyword queries take about 8 s and come back vector-only (`keyword_arm_failed`, or `skipped_after_timeout` for 10 minutes after a timeout) on a large Postgres brain](#keyword-search-times-out-on-a-large-postgres-brain) | read doctor's `keyword_plan`; narrow with `--source-id`, or raise `search.keyword_statement_timeout_ms` on the brain host and restart the serving process | brain host | none | `gbrain doctor --only keyword_plan --json` |@@ -286,9 +286,9 @@ A running sync is not one of these: `gbrain repair fences` now runs during a cat<a id="dream-paid-loop"></a>**Dream keeps skipping one transcript, or doctor warns `dream_paid_loop`?** A dream key died `dream.breaker.max_dead_submissions` times (default 3) in 24 hours and is refused so it stops billing you. Fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'`. See [the paid-loop breaker](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).-<a id="dream-write-deferred"></a>**Doctor warns `dream_write_deferred`?** A purge or consolidate write was accepted but still pending after its publish wait. The phase reports it as deferred (warn, not a failed cycle), keeps the receipt id and reconciles it on the next pass before it submits anything for that source. After 3 passes still pending, doctor names the receipt: read it with `gbrain write-request -- <id>`, and `gbrain sources writer status --source <id> --json` says why the writer has not committed it. `gbrain config set dream.write_deferral.enabled false` turns deferral off (a pending write then fails the phase, as before).+<a id="dream-write-deferred"></a>**Doctor warns `dream_write_deferred`?** A purge or consolidate write is still pending 3 passes after its publish wait; each pass re-reads its receipt before submitting more for that source. Read the named receipt; `dream.write_deferral.enabled false` restores the failing phase.-<a id="embedding-restamp-stalled"></a>**Doctor warns `embedding_restamp_stalled`?** The embed phase first stamps the current embedding signature on pages whose vectors already match the current model, with no provider call. That stamp failed 3 runs in a row; the message names the error. Fix it, then run `gbrain dream --phase embed --json`. `gbrain config set embed.restamp.enabled false` turns the restamp off.+<a id="embedding-restamp-stalled"></a>**Doctor warns `embedding_restamp_stalled`?** The free signature restamp the embed phase runs first failed 3 runs in a row; the message names the error. `embed.restamp.enabled false` turns it off.**Hourly cron sync keeps timing out on a federated brain?** Switch yourcron to a per-source loop with shell `timeout(1)` doing the OS-level killdiff --git a/llms-full.txt b/llms-full.txtindex 019601628e..3cb19a429c 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -8206,9 +8206,7 @@ times (default 3; `0` disables) within 24 hours is refused before the nextsubmission, and `gbrain doctor` reports it as `dream_paid_loop`. Fix thecause first (a missing provider key, a quota, a failing transcript), then`gbrain dream reset-key --list` shows the refused keys and-`gbrain dream reset-key '<key>'` re-enables one. A purge or consolidate write-still pending after its publish wait is deferred and reconciled on the next-pass instead of failing the cycle (`dream_write_deferred` after 3 passes). Details in+`gbrain dream reset-key '<key>'` re-enables one. Details in[spend controls](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).Three more fields answer "what did that cost and did it land":@@ -10293,8 +10291,8 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro| `gbrain init` or `gbrain upgrade` stops with `schema_lock_blocked` naming a pid (or, before #5227, sat in `wait_event_type=Lock` with no output) | let the named session finish, or with the user's agreement end it on the database host: `SELECT pg_terminate_backend(<pid>)`; then rerun the same command ([ENGINES.md](../ENGINES.md#schema-lock-blocked)) | brain host, after the user agrees | `destructive` when it ends another session | the rerun completes; `gbrain doctor --json` shows the schema at head || [`queue_capacity`, `persistence_capacity` or `persistence_request_growth`](#write-capacity) | run the printed `gbrain config set persistence.limits.<limit> <value>` | brain host | none | `gbrain doctor --only persistence_capacity,persistence_request_growth --json` || [`dream_paid_loop`, or dream keeps skipping one transcript](#dream-paid-loop) | fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'` | agent, after the user agrees | `paid` (the key is retried) | `gbrain doctor --only dream_paid_loop --json` |-| [`dream_write_deferred`: a purge or consolidate write is still pending after 3 passes](#dream-write-deferred) | read the receipt it names (`gbrain write-request -- <id>`), then `gbrain sources writer status --source <id> --json` | agent | none | `gbrain doctor --only dream_write_deferred --json` |-| [`embedding_restamp_stalled`](#embedding-restamp-stalled) | fix the error it names, then `gbrain dream --phase embed --json` | agent | `paid` only for stale chunks the embed phase embeds | `gbrain doctor --only embedding_restamp_stalled --json` |+| [`dream_write_deferred`](#dream-write-deferred) | `gbrain write-request -- <id>`, then `gbrain sources writer status --source <id> --json` | agent | none | `gbrain doctor --only dream_write_deferred --json` |+| [`embedding_restamp_stalled`](#embedding-restamp-stalled) | fix the named error, then `gbrain dream --phase embed --json` | agent | `paid` for stale chunks only | `gbrain doctor --only embedding_restamp_stalled --json` || [A page exists (`gbrain get <slug>` returns it) but search never finds text from it](memory-boundaries.md#large-pages) | `gbrain reindex --oversized --dry-run --json` lists pages stored before the upgrade with a size-based `embed_skip` marker (without `--dry-run` it keyword-indexes them, free); a page above an operator-lowered `content_sanity.bytes_block` keeps its marker until it is raised; a page the content-quality gate quarantined shows in `gbrain quarantine list` (`gbrain quarantine clear <slug>` re-checks it once the user agrees); a file over the 24 MiB page ceiling was never stored ([`file_too_large`](write-refusals.md#file_too_large)). Its chunks waiting for embedding approval (doctor `partial_embedding`) are a paid step: `gbrain embed --held --dry-run`, then `gbrain embed --held --source <id> --max-usd <N>` as printed | agent for the reindex; the user decides embedding spend, a `bytes_block` change and a quarantine clear | none for the reindex; `paid` for `gbrain embed` | `gbrain reindex --oversized --dry-run --json` lists nothing; `gbrain search "<phrase from deep in the page>"` returns the page || [Search answers look keyword-only on a large Postgres brain](#hybrid-search-returns-only-keyword-hits) | read doctor's `vector_plan`; run the index command it prints | brain host | none | `gbrain doctor --only vector_plan --json` || [Broad keyword queries take about 8 s and come back vector-only (`keyword_arm_failed`, or `skipped_after_timeout` for 10 minutes after a timeout) on a large Postgres brain](#keyword-search-times-out-on-a-large-postgres-brain) | read doctor's `keyword_plan`; narrow with `--source-id`, or raise `search.keyword_statement_timeout_ms` on the brain host and restart the serving process | brain host | none | `gbrain doctor --only keyword_plan --json` |@@ -10497,9 +10495,9 @@ A running sync is not one of these: `gbrain repair fences` now runs during a cat<a id="dream-paid-loop"></a>**Dream keeps skipping one transcript, or doctor warns `dream_paid_loop`?** A dream key died `dream.breaker.max_dead_submissions` times (default 3) in 24 hours and is refused so it stops billing you. Fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'`. See [the paid-loop breaker](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).-<a id="dream-write-deferred"></a>**Doctor warns `dream_write_deferred`?** A purge or consolidate write was accepted but still pending after its publish wait. The phase reports it as deferred (warn, not a failed cycle), keeps the receipt id and reconciles it on the next pass before it submits anything for that source. After 3 passes still pending, doctor names the receipt: read it with `gbrain write-request -- <id>`, and `gbrain sources writer status --source <id> --json` says why the writer has not committed it. `gbrain config set dream.write_deferral.enabled false` turns deferral off (a pending write then fails the phase, as before).+<a id="dream-write-deferred"></a>**Doctor warns `dream_write_deferred`?** A purge or consolidate write is still pending 3 passes after its publish wait; each pass re-reads its receipt before submitting more for that source. Read the named receipt; `dream.write_deferral.enabled false` restores the failing phase.-<a id="embedding-restamp-stalled"></a>**Doctor warns `embedding_restamp_stalled`?** The embed phase first stamps the current embedding signature on pages whose vectors already match the current model, with no provider call. That stamp failed 3 runs in a row; the message names the error. Fix it, then run `gbrain dream --phase embed --json`. `gbrain config set embed.restamp.enabled false` turns the restamp off.+<a id="embedding-restamp-stalled"></a>**Doctor warns `embedding_restamp_stalled`?** The free signature restamp the embed phase runs first failed 3 runs in a row; the message names the error. `embed.restamp.enabled false` turns it off.**Hourly cron sync keeps timing out on a federated brain?** Switch yourcron to a per-source loop with shell `timeout(1)` doing the OS-level kill@@ -11148,87 +11146,4 @@ the [CHANGELOG](../../CHANGELOG.md#exit-code-changes-by-command).----## docs/integrations/reliability-repair.md--Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/integrations/reliability-repair.md--# Reliability repair--Two data-corruption classes can affect a brain on real Postgres or Supabase:-JSONB values stored double-encoded, and markdown bodies truncated at import.-`gbrain doctor` detects both, and the standalone `gbrain repair-jsonb`-command fixes the mechanically fixable class. PGLite brains are not affected-(PGLite parses text to jsonb natively, so the double-encode never happens-there).--## What the checks look for--**JSONB double-encode.** Writing `${JSON.stringify(x)}::jsonb` through-postgres.js stores a JSONB *string literal* instead of an object.-`frontmatter ->> 'key'` returns NULL; GIN indexes are ineffective. Columns-checked: `pages.frontmatter`, `raw_data.data`, `ingest_log.pages_updated`,-`files.metadata`. The write-side rule that prevents it is in-`docs/ENGINES.md` ("JSONB writes: never double-encode").--**Markdown body truncation.** A page whose `compiled_truth` is much shorter-than its `raw_data.data ->> 'content'` lost body content at import time (for-example, when a `---` horizontal rule was treated as a body/timeline-delimiter). Wiki-style pages with multiple `##`/`###` sections are the usual-casualty.--## Detect--```-gbrain doctor-```--Reports two checks:--- `jsonb_integrity` — counts double-encoded rows per table and points you- at `gbrain repair-jsonb`.-- `markdown_body_completeness` — heuristic for pages whose `compiled_truth`- is suspiciously short compared to `raw_data.data ->> 'content'`. A page- stored in segments has no `compiled_truth` column to compare, so it is not- checked; the check reports how many with `skipped_segmented: N`.--## Repair--For JSONB (mechanically fixable):--```-gbrain repair-jsonb-```--Runs `UPDATE <table> SET <col> = (<col>#>>'{}')::jsonb WHERE jsonb_typeof(<col>) = 'string'`-across every affected column. Idempotent. Second run reports 0 rows. Use-`--dry-run` to preview, `--json` for structured output. The `v0_12_2`-version migration runs this automatically on `gbrain upgrade`.--For truncated markdown bodies (source-dependent): the importer skips a file-whose content hash has not changed, and trailing whitespace is trimmed before-hashing, so a re-import needs a real edit to the page body. Make the edit, then-re-import:--```-gbrain sync # git-backed brain: commit the edit first-gbrain sync --working-tree # or import the uncommitted working tree-gbrain import <brain-root> --fresh # or re-import the root you originally imported;- # --fresh ignores a resume checkpoint that would skip the path-```--gbrain cannot recover content that is already lost if you no longer have-the source markdown file. `gbrain doctor` tells you which pages look short;-you decide whether to re-import from source or accept the truncation.--## Verify--```-gbrain doctor-```--All four `jsonb_integrity` rows should read zero. `markdown_body_completeness`-should match your expectations for the corpus.------# Migrationsdiff --git a/scripts/llms-config.ts b/scripts/llms-config.tsindex e0118e417e..d5313b345d 100644--- a/scripts/llms-config.ts+++ b/scripts/llms-config.ts@@ -376,6 +376,8 @@ export const SECTIONS: DocSection[] = [title: "docs/integrations/reliability-repair.md",description: "Data integrity recovery.",path: "docs/integrations/reliability-repair.md",+ // Linked, not inlined: the GBRA-224 W3 troubleshooting rows put llms-full.txt over FULL_SIZE_BUDGET.+ includeInFull: false,},],},