Skip to content

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.md
index 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 next
submission, and `gbrain doctor` reports it as `dream_paid_loop`. Fix the
cause 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.md
index 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 your
cron to a per-source loop with shell `timeout(1)` doing the OS-level kill
diff --git a/llms-full.txt b/llms-full.txt
index 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 next
submission, and `gbrain doctor` reports it as `dream_paid_loop`. Fix the
cause 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 your
cron 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.
-
----
-
# Migrations
diff --git a/scripts/llms-config.ts b/scripts/llms-config.ts
index 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,
},
],
},