Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

GBRA-221: operator docs for outside_content_fences live in repair.md (keeps llms-full under budget on the .476 tree)

garrytanb379ddd88e0f
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index bbb4170780..291aac9748 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -586,6 +586,19 @@ or `embedding_auth_failed` on the first rejected embedding
([write refusals](write-refusals.md#embedding_auth_failed)). After fixing a
rejected key, `gbrain embed --stale` embeds what was saved meanwhile.
+<a id="outside-content-fences"></a>
+### Outside-content fences
+
+Doctor's `outside_content_fences` check warns when an imported page whose body is someone else's text (a Gmail thread or calendar event from a Google source, a GitHub issue, PR or repo card, an imported chat transcript) has facts, takes or links indexed from a fence on it. Before GBRA-221 those importers copied the text verbatim. A sender who wrote `<!--- gbrain:facts:begin -->` and a table planted facts, which `extract_facts` saved with the visibility and confidence the sender chose. A re-render carries a stored fence forward. Imports now escape the markers, so new mail can't do this. Rows planted earlier stay until someone removes them.
+
+The check lists each page with its counts (world-visible facts counted apart), never a cell value. It reads the indexed rows, so a fence not yet extracted shows up after the next `extract_facts` run. gbrain's own writers (`remember`, loop extraction) also add rows to some of these pages, and the check can't tell which is which, so there is no automatic repair:
+
+1. Read the page with the user: `gbrain get --source <id> -- <slug>`.
+2. For each fact they say a sender wrote, withdraw it after they agree: `gbrain forget <fact-id> --source <id>`.
+3. Verify with `gbrain doctor --only outside_content_fences --json`.
+
+**Say to your agent:** *"Which imported pages hold facts a sender could have planted? Show me before you remove anything."*
+
<a id="connector-held-items"></a>
### Connector held items
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 40242d2224..37aac2e35a 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -45,7 +45,6 @@
| Low health score | preview `gbrain doctor --remediation-plan --json`; then `gbrain doctor --remediate --yes --target-score 90 --max-usd 5` | agent, after the user agrees | `paid`; `destructive` with `--include-repairs` (approve with `--expect <plan_hash>` from the preview) | `gbrain doctor --json` |
| [Sync held a file (`Held <path>: invalid_frontmatter …`, `git_held_files`)](#held-files) | `gbrain sources status <id>`, then preview `gbrain repair frontmatter --source <id>` and apply the printed `--apply --expect <hash> --yes` | agent; the apply after the user agrees | `destructive` (rewrites the previewed lines of the files) | `gbrain doctor --only git_held_files --json` |
| [Sync held a file for its facts or takes fence (`Held <path>: invalid_fence …`)](#held-fence-files) | nothing for most holds: the next maintenance run repairs and commits the fence. To see or do it now, preview `gbrain repair fences --source <id>` and run its printed `--apply --expect <hash>`; to pause automatic repair, `gbrain config set fences.repair.enabled false` (ask the user first). A `manual` reason needs the edit the hold names | agent; the apply needs no extra consent | none (model repair spends within the `fences.repair.*` caps; raising them is `paid`, the user's call) | `gbrain doctor --only fence_integrity --json` |
-| [Doctor `outside_content_fences` warns](#outside-content-fences) | review each listed page with the user; `gbrain forget` a fact they confirm a sender planted | agent reads; the user decides | per withdrawal | `gbrain doctor --only outside_content_fences --json` |
| A managed catch-up on a live checkout keeps dying (`revision_conflict`, `pinned_git_worktree_conflict`, `page_identity_changed`, `write ECONNABORTED`), or you want an agent to drive the recovery | `gbrain sync status --source <id> --json` (cursor, `committed_last_10m`, each hold and the last error with `class` / `safe_actions` / `needs_human`); when nothing moved and `needs_human` is false, `gbrain sync unblock --source <id> --apply`, then the sync it prints ([runbook](sync-unblock-runbook.md)) | agent; a person only when `needs_human` names a slug | none | `gbrain sync status --source <id> --json` |
| [Every write on a source stays pending; writer status shows a request `recovering` with `unexpected_file_bytes`](repair.md#stuck-recovery) | preview `gbrain repair stuck-recovery --source <id>` on the owner host, show the user the diff it prints, then run the choice they pick: `--keep prior` or `--keep disk` with `--apply --expect <hash> --yes`; never delete the file to unblock it | agent; the apply after the user picks a version | `destructive` (both versions are backed up first) | `gbrain sources writer status --source <id> --json` shows no recovering request |
| [Sync held a file with `worktree_dirty`](#worktree-dirty-hold) | commit (or restore) the file, then `gbrain sync unblock --source <id> --apply` and the sync it prints | agent; whoever edits the file commits it | none | `gbrain sources status <id> --json` |
@@ -108,8 +107,6 @@
<a id="held-fence-files"></a>**Sync held a file because of its facts or takes fence (`Held <path>: invalid_fence …`)?** Managed sync succeeded; only that file waits. The hold names the fence, section, row numbers, columns and reason, never a cell, and most holds clear by themselves: the maintenance run's `fence_repair` phase repairs the fence on the owner host and commits the file. To see the plan or do it now, run `gbrain repair fences --source <id>` (a read-only preview with no model call), then the apply command it prints; applying needs no extra consent. Model repair spends only within `fences.repair.max_usd_per_page` and `fences.repair.max_usd_per_day`; raising them, or pausing automatic repair with `gbrain config set fences.repair.enabled false`, is the user's call. A hold whose reason is `manual` needs a person: read the page (`gbrain get --source <id> -- <slug>`), edit only that fence in the file (not the frontmatter; `gbrain repair frontmatter` does not touch fences), commit, and run `gbrain sync --source <id> --no-pull`. A `prepare_time` hold was refused against stored rows (for example a takes row number a stored take already uses): fix it as its `fence.reason` says, and after a database-side fix run `gbrain sources retry-held <id>`. A source a fence blocked before upgrading recovers on its next sync. A fence with one obvious meaning is never held: sync rewrites it losslessly, commits the file and reports `fences_normalized`; a `fence_normalized` notice on a write means re-read the page before editing it. `gbrain doctor --only fence_integrity` counts every malformed fence still waiting (held, stored or unsynced) by tier. See [fence holds](write-refusals.md#invalid_fence), [fence repair](repair.md#fences) and the [fence format](fence-format.md).
-<a id="outside-content-fences"></a>**Doctor warns `outside_content_fences`?** Before GBRA-221, importers copied third-party text (email, calendar, GitHub, chat transcripts) into page bodies verbatim, so a sender could plant a facts, takes or links fence that `extract_facts` indexed. Imports now neutralize the markers. The check lists imported pages with fence rows indexed, never a cell value; gbrain writers add some rows on purpose, so nothing is removed. Review each page with the user (`gbrain get --source <id> -- <slug>`) and withdraw a planted fact with `gbrain forget` after they agree.
-
<a id="concurrent-write-hold"></a>**Sync held a file with `concurrent_write`?** A Git edit raced a database-only write; nothing was overwritten. Preview `gbrain sources reconcile <id> <slug> --preview`, let the user choose, then `gbrain sources retry-held <id>`. See [concurrent_write](write-refusals.md#concurrent_write).
<a id="worktree-dirty-hold"></a>**Sync held a file with `worktree_dirty`?** The working tree holds uncommitted bytes for the file that match neither the pinned commit nor the page (an agent mid-edit on a live checkout), so sync held it instead of overwriting the edit and kept going; nothing is lost and the run finished. Commit the file (or restore it), then `gbrain sync unblock --source <id> --apply` re-screens every held file that is now committed and prints the sync to run; a later commit that changes the file re-screens it on its own. A file held three times is reported `needs_human` by `gbrain sync status`: find out what keeps editing it. Bytes committed at HEAD past the pinned target are imported as HEAD has them, never held. See [worktree_dirty](write-refusals.md#worktree_dirty) and the [sync unblock runbook](sync-unblock-runbook.md).
diff --git a/llms-full.txt b/llms-full.txt
index 0483356dc3..76575d3143 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -10240,7 +10240,6 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro
| Low health score | preview `gbrain doctor --remediation-plan --json`; then `gbrain doctor --remediate --yes --target-score 90 --max-usd 5` | agent, after the user agrees | `paid`; `destructive` with `--include-repairs` (approve with `--expect <plan_hash>` from the preview) | `gbrain doctor --json` |
| [Sync held a file (`Held <path>: invalid_frontmatter …`, `git_held_files`)](#held-files) | `gbrain sources status <id>`, then preview `gbrain repair frontmatter --source <id>` and apply the printed `--apply --expect <hash> --yes` | agent; the apply after the user agrees | `destructive` (rewrites the previewed lines of the files) | `gbrain doctor --only git_held_files --json` |
| [Sync held a file for its facts or takes fence (`Held <path>: invalid_fence …`)](#held-fence-files) | nothing for most holds: the next maintenance run repairs and commits the fence. To see or do it now, preview `gbrain repair fences --source <id>` and run its printed `--apply --expect <hash>`; to pause automatic repair, `gbrain config set fences.repair.enabled false` (ask the user first). A `manual` reason needs the edit the hold names | agent; the apply needs no extra consent | none (model repair spends within the `fences.repair.*` caps; raising them is `paid`, the user's call) | `gbrain doctor --only fence_integrity --json` |
-| [Doctor `outside_content_fences` warns](#outside-content-fences) | review each listed page with the user; `gbrain forget` a fact they confirm a sender planted | agent reads; the user decides | per withdrawal | `gbrain doctor --only outside_content_fences --json` |
| A managed catch-up on a live checkout keeps dying (`revision_conflict`, `pinned_git_worktree_conflict`, `page_identity_changed`, `write ECONNABORTED`), or you want an agent to drive the recovery | `gbrain sync status --source <id> --json` (cursor, `committed_last_10m`, each hold and the last error with `class` / `safe_actions` / `needs_human`); when nothing moved and `needs_human` is false, `gbrain sync unblock --source <id> --apply`, then the sync it prints ([runbook](sync-unblock-runbook.md)) | agent; a person only when `needs_human` names a slug | none | `gbrain sync status --source <id> --json` |
| [Every write on a source stays pending; writer status shows a request `recovering` with `unexpected_file_bytes`](repair.md#stuck-recovery) | preview `gbrain repair stuck-recovery --source <id>` on the owner host, show the user the diff it prints, then run the choice they pick: `--keep prior` or `--keep disk` with `--apply --expect <hash> --yes`; never delete the file to unblock it | agent; the apply after the user picks a version | `destructive` (both versions are backed up first) | `gbrain sources writer status --source <id> --json` shows no recovering request |
| [Sync held a file with `worktree_dirty`](#worktree-dirty-hold) | commit (or restore) the file, then `gbrain sync unblock --source <id> --apply` and the sync it prints | agent; whoever edits the file commits it | none | `gbrain sources status <id> --json` |
@@ -10303,8 +10302,6 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro
<a id="held-fence-files"></a>**Sync held a file because of its facts or takes fence (`Held <path>: invalid_fence …`)?** Managed sync succeeded; only that file waits. The hold names the fence, section, row numbers, columns and reason, never a cell, and most holds clear by themselves: the maintenance run's `fence_repair` phase repairs the fence on the owner host and commits the file. To see the plan or do it now, run `gbrain repair fences --source <id>` (a read-only preview with no model call), then the apply command it prints; applying needs no extra consent. Model repair spends only within `fences.repair.max_usd_per_page` and `fences.repair.max_usd_per_day`; raising them, or pausing automatic repair with `gbrain config set fences.repair.enabled false`, is the user's call. A hold whose reason is `manual` needs a person: read the page (`gbrain get --source <id> -- <slug>`), edit only that fence in the file (not the frontmatter; `gbrain repair frontmatter` does not touch fences), commit, and run `gbrain sync --source <id> --no-pull`. A `prepare_time` hold was refused against stored rows (for example a takes row number a stored take already uses): fix it as its `fence.reason` says, and after a database-side fix run `gbrain sources retry-held <id>`. A source a fence blocked before upgrading recovers on its next sync. A fence with one obvious meaning is never held: sync rewrites it losslessly, commits the file and reports `fences_normalized`; a `fence_normalized` notice on a write means re-read the page before editing it. `gbrain doctor --only fence_integrity` counts every malformed fence still waiting (held, stored or unsynced) by tier. See [fence holds](write-refusals.md#invalid_fence), [fence repair](repair.md#fences) and the [fence format](fence-format.md).
-<a id="outside-content-fences"></a>**Doctor warns `outside_content_fences`?** Before GBRA-221, importers copied third-party text (email, calendar, GitHub, chat transcripts) into page bodies verbatim, so a sender could plant a facts, takes or links fence that `extract_facts` indexed. Imports now neutralize the markers. The check lists imported pages with fence rows indexed, never a cell value; gbrain writers add some rows on purpose, so nothing is removed. Review each page with the user (`gbrain get --source <id> -- <slug>`) and withdraw a planted fact with `gbrain forget` after they agree.
-
<a id="concurrent-write-hold"></a>**Sync held a file with `concurrent_write`?** A Git edit raced a database-only write; nothing was overwritten. Preview `gbrain sources reconcile <id> <slug> --preview`, let the user choose, then `gbrain sources retry-held <id>`. See [concurrent_write](write-refusals.md#concurrent_write).
<a id="worktree-dirty-hold"></a>**Sync held a file with `worktree_dirty`?** The working tree holds uncommitted bytes for the file that match neither the pinned commit nor the page (an agent mid-edit on a live checkout), so sync held it instead of overwriting the edit and kept going; nothing is lost and the run finished. Commit the file (or restore it), then `gbrain sync unblock --source <id> --apply` re-screens every held file that is now committed and prints the sync to run; a later commit that changes the file re-screens it on its own. A file held three times is reported `needs_human` by `gbrain sync status`: find out what keeps editing it. Bytes committed at HEAD past the pinned target are imported as HEAD has them, never held. See [worktree_dirty](write-refusals.md#worktree_dirty) and the [sync unblock runbook](sync-unblock-runbook.md).
diff --git a/src/commands/doctor/checks/outside-content-fences.ts b/src/commands/doctor/checks/outside-content-fences.ts
index e9716bc647..fb9623717b 100644
--- a/src/commands/doctor/checks/outside-content-fences.ts
+++ b/src/commands/doctor/checks/outside-content-fences.ts
@@ -36,7 +36,7 @@ async function runOutsideContentFences(ctx: DoctorContext): Promise<Check[]> {
OR p.frontmatter ? 'transcript_import')
GROUP BY p.source_id, p.slug, p.type
ORDER BY p.source_id, p.slug`);
- const details = { pages: items.length, items, docs: 'docs/guides/troubleshooting.md#outside-content-fences' };
+ const details = { pages: items.length, items, docs: 'docs/guides/repair.md#outside-content-fences' };
if (!items.length) {
checks.push({ name: NAME, status: 'ok', details,
message: 'No fact, take or link is indexed from a fence on an imported email, calendar, GitHub or transcript page.' });
diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.json
index 76233808f9..ebc584033f 100644
--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json
+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json
@@ -3346,7 +3346,7 @@
{
"category": "brain",
"details": {
- "docs": "docs/guides/troubleshooting.md#outside-content-fences",
+ "docs": "docs/guides/repair.md#outside-content-fences",
"items": [],
"pages": 0
},
diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.json
index 1263cabd45..825a5c5c01 100644
--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json
+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json
@@ -3389,7 +3389,7 @@
{
"category": "brain",
"details": {
- "docs": "docs/guides/troubleshooting.md#outside-content-fences",
+ "docs": "docs/guides/repair.md#outside-content-fences",
"items": [],
"pages": 0
},
diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.json
index a97ba7bcba..aa6b9f4244 100644
--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json
+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json
@@ -3392,7 +3392,7 @@
{
"category": "brain",
"details": {
- "docs": "docs/guides/troubleshooting.md#outside-content-fences",
+ "docs": "docs/guides/repair.md#outside-content-fences",
"items": [],
"pages": 0
},