Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

GBRA-221: doctor check reads indexed fence rows (segment-safe); key-files placement; postgres golden; llms budget

garrytan71de3f7a8556
diff --git a/docs/architecture/key-files/commands-2-continued.md b/docs/architecture/key-files/commands-2-continued.md
index 2af703c048..8b8acc9553 100644
--- a/docs/architecture/key-files/commands-2-continued.md
+++ b/docs/architecture/key-files/commands-2-continued.md
@@ -28,7 +28,6 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/doctor/checks/extraction-input.ts` — `extraction_input_truncated` (large pages A7, BRAIN, registered after `fence_integrity`, before `search_mode`). Groups the live pages with an `input_truncated` receipt in `page_extraction_state` by pipeline and kind (`facts_backstop/head|tail_window`, `extract_atoms/head|tail_window`, `conversation_facts/skipped_too_large`) with three recent `source:slug` samples and a remedy each. Warns when an atoms or conversation-facts receipt exists; the atoms fix is `gbrain config set cycle.extract_atoms.max_input_chars <n>` (`ask_user`, consent `paid`), otherwise `fix_unavailable_reason: operator_judgement`. Facts-only receipts are `ok` with `severity: info`, `readiness_state: degraded` (no knob raises the facts cap; later appends are read incrementally). Reads the database only. Tests: `test/extraction-watermark-facts.test.ts`, `test/extraction-watermark-atoms.test.ts`, `test/conversation-facts-oversized-sidecar.test.ts`.
- `src/commands/doctor/bounded-unknown.ts` — #7145: `boundUnknownDetails(bound)` returns `{ health: 'unknown', reason: 'bound', bound, exact: false }`, the details shape a doctor check uses when it stopped at its own bound (`files`, `time`, `rows`, `roots`, `sample`) before it could say clear; the check adds its `limit` beside it, grades `warn`, and names the bound and the rerun or wider command in its message. Used by `multi_source_drift`, `ghost_pages`, `missing_recorded_files`, `conversation_outcomes_stale`, `maintenance_write_drift`, `git_convergence`, `tracked_ownership_marker`, `orphaned_private_queue`, `link_resolution_opportunity` and `frontmatter_integrity`. A capped list that found rows says "at least N" or "N+" with `exact: false` instead. Tests: `test/doctor-bound-unknown-7145.test.ts`, `test/doctor-capped-counts-7145.test.ts`, `test/doctor-unknown-reads-7145.test.ts`.
- `src/commands/doctor/checks/fence-integrity.ts` — `fence_integrity` (#6188, BRAIN, registered before `search_mode`). Each run advances the fence census within `GBRAIN_DOCTOR_FENCE_TIMEOUT_MS` (default 10 s), then reports per source the malformed facts/takes fences still waiting, each counted once (held file, stored page, unsynced file) and split by planned tier (deterministic, resolver, llm, manual), the oldest hold's age, the 7-day `fences_normalized` trend with top writers (warns at `FENCE_NORMALIZATION_WARN_7D` = 20), and the model-repair caps with today's ledger spend. `ok` only when nothing waits, every source's census is complete and no source reaches the trend threshold; a partial census warns with the resume command. The fix is the read-only `gbrain repair fences --source <id>` preview for holds, stored pages and files alike; a warn reads `readFenceAutoRepair` (details `auto_repair`): while a maintenance run is active and `fences.repair.enabled` is on, the non-manual fences are "repaired automatically by the next maintenance run", otherwise the fix's `then` is the apply. Model-tier fences say why they wait (`fences.repair.llm` off with the command that turns it on, or today's budget spent with the cap command), else the caps. `fenceIntegrityCheck(engine, sourceIds?)` is the `WAVE_CHECKS` entry (scoped for a remote caller). Location only. #6278: the check also counts `unrenderable_legacy_facts`: the active `row_num IS NULL` fact rows the fence step leaves unadopted because the fence codec would change their text (or their page already carries the claim), planned read-only per source within the census time budget (`planUnfencedFacts` + `auditUnadoptableFacts`) and listed by page, fact id and reason class, never the claim text. They stay active and searchable, so the finding says nothing is lost, never suggests `forget_fact`, and when it is the only finding its fix carries no command (`next: report`) with the doctor re-count as verify; an incomplete scan asks for a rerun. #6610: `unbound_legacy_facts` lists, from the same plan, unfenced rows of classic database-only pages that `persistence.unbound_write` keeps unfenced; when it is the only finding the fix is `gbrain config set persistence.unbound_write database_only` with `ask_user`. Test: `test/doctor-fence-integrity.test.ts`, `test/extract-facts-unfenced-rows.test.ts`. Wave B decision #10: `withSkippedSegmented(check, n)` (`src/commands/doctor/check-fix.ts`) adds `Check.skipped_segmented: n` and a `skipped (segmented): n` message tail (unchanged at n = 0) to every check whose scan reads whole bodies: `oversized_pages`, `scraper_junk_pages`, `markdown_body_completeness`, `link_resolution_opportunity`, `fence_integrity` (segmented pages without a walked checkout file), `core_memory`, and `extract_health` via `readFactsReconcileBacklog`'s `skipped_segmented`; each count is one COUNT query that falls back to 0 on a schema without `body_storage`. Test: `test/large-pages/doctor-skipped-segmented.test.ts` (+ Postgres arm).
-- `src/commands/doctor/checks/outside-content-fences.ts` — `outside_content_fences` (GBRA-221, BRAIN, registered after `fence_integrity`, before `search_mode`). Lists live facts, takes and links fence rows on imported pages whose body is outside-authored text (Google `email`/`meeting` pages, every GitHub-source page, pages with `transcript_import` frontmatter), prefiltered in SQL on the begin-marker token and counted with the real fence parsers. Before GBRA-221 a sender could plant such rows and a re-render carries a stored fence forward; gbrain writers also add rows on purpose, so the check only lists pages (location and counts, never a cell value) with an `ask_user` review fix (`gbrain get`) and removes nothing. Segmented pages are counted as skipped. Read-only.
- `src/commands/doctor/checks/git-convergence.ts` — `git_convergence` (#5063, brain category, after `sync_freshness`): for every non-archived filesystem source root plus `sync.repo_path` (connector sources skipped), `git status --porcelain -z` and `rev-list --left-right --count @{u}...HEAD` against the local upstream ref, never a fetch, each call bounded at 5 s and at most 50 roots. Commits not on the upstream warn after 6 h and fail after 24 h (oldest unpushed commit time), except on a managed checkout this host owns with Git durability on and no Git effect of its worktree queued, running or failed: there they warn at once (`stranded: true` in `details.roots`, #7089) with an agent fix `gbrain git commit-push --push-only --keep-checkout --path <root>` and verify `gbrain doctor --only git_convergence --json`; bindings map to their toplevel, and tracked files modified under such a durable source root warn the same way (`uncommitted_pages`, #7091) with an ask-user commit, then that push; uncommitted changes warn once the oldest changed file is older than 6 h; behind is reported, not judged. Emits nothing when no probed root has an upstream. The same entry emits `tracked_ownership_marker` (#5186): `git ls-files --cached` on each of those checkouts, warn when a path `isPhysicalRootMetadata` recognizes is in the index, with a user-run `git -C <root> rm --cached <paths>` fix (an ignore rule never un-tracks a file; the push deny list is the backstop), ok otherwise, nothing without a checkout. `bootstrap-checks.ts` `bootstrap_push_health` also warns, instead of `ok`, when a recent successful push leaves the receipt workspace ahead of `origin/<branch>`. `scripts/smoke-test.sh` accepts a configured database URL (`engine status` `db_url_source`) and trusts doctor `embedding_provider` over raw OpenAI/Voyage keys. Tests: `doctor-git-convergence-5063.test.ts`, `persistence-git-removal-push-7089.test.ts` (stranded roots, both engines), `doctor-ownership-marker.test.ts`, `bootstrap-doctor-checks.test.ts`, `smoke-test-worker.test.ts`.
- `src/commands/doctor/checks/keyword-plan.ts` — `keyword_plan` (#6495, OPS, wave check with operator resolution; the keyword-side twin of `vector_plan` in commands-2.md). Postgres only: reads the commonest lexeme the planner knows for `content_chunks.search_vector` (`pg_stats.most_common_elems` with its frequency), EXPLAINs (no ANALYZE) the strict page-count statement for it (`buildKeywordCountStatement`, the builder the engine uses) and times the engine's own bounded `countKeywordPages(term, { timeoutMs: 2000 })`; warns `canary_timed_out` when that count hits its bound and `canary_slow` when it takes more than half of `search.keyword_statement_timeout_ms`, naming the knob with its range (1000-60000), the fail-open to the vector arm (`keyword_arm_failed`), that a longer bound buys time and not a cheaper statement, that one canary term is not workload coverage, and that a timed-out count is never "no matches". Skipped on PGLite, below 10,000 chunks (`pg_class.reltuples`) and without planner statistics (it names `ANALYZE content_chunks`); a failing probe reports unknown health. `engineKeywordPlanProbe(engine)` is the database side; `keywordPlanCheck(engine, probe?)` takes a fake for tests. Tested in `test/doctor-keyword-plan-6495.test.ts` (fake probe for every outcome; with DATABASE_URL the real probe on a seeded brain and a lock-forced timeout).
diff --git a/docs/architecture/key-files/commands-3-continued.md b/docs/architecture/key-files/commands-3-continued.md
index d2db19e2cf..0f966abef6 100644
--- a/docs/architecture/key-files/commands-3-continued.md
+++ b/docs/architecture/key-files/commands-3-continued.md
@@ -16,3 +16,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/friction.ts` + `src/core/friction.ts` — `gbrain friction {log,render,list,summary,diff}` reporter. Append-only JSONL under `$GBRAIN_HOME/.gbrain/friction/<run-id>.jsonl`. Schema is a flat extension of `StructuredAgentError`; every claw-test run opens with a `phase-marker`/`start` meta record carrying `agent` + `scenario` + `harness_schema` (agent-name resolution depends on it). Render groups by severity → phase, defaults to `--redact` for md output (strips `$HOME`/`$CWD` to placeholders so reports paste safely in PRs). `diff --base <run-or-agent> --compare <run-or-agent>` is the cross-agent instrument: exact run-id wins, else agent name resolves to that agent's latest run; identity is `(kind, phase, normalized 80-char message prefix — digit runs collapsed so durations/counts don't split identities)` over `kind ∈ {friction, delight}` as MULTISETS (per-severity counts + totals are the compared attributes: `count_changed` = volume, `severity_changed` = distribution shape via exact integer proportion test, so a delight→friction flip or a 2×error+1×nit → 1×error+2×nit redistribution always surfaces; markers/interrupted feed the compatibility banner, which warns on scenario/version mismatch); output labels sections "unique to <run>" — an instrument, never a blame-attributor. Run-id resolves from `--run-id` > `$GBRAIN_FRICTION_RUN_ID` > `standalone.jsonl`. Skills the claw-test exercises carry a `_friction-protocol.md` callout so agents know when to log friction.
- `src/commands/frontmatter-install-hook.ts` — `gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]`: writes the frontmatter pre-commit hook at `<git root>/.githooks/pre-commit` and sets `core.hooksPath` when unset. The root comes from `discoverGitRoot` (the same `git rev-parse --show-toplevel` walk `gbrain sync` uses, realpath'd on both sides), so a source registered as a SUBDIRECTORY of a host repo (bootstrap's `<workspace>/brain`) is accepted rather than skipped: the hook lands at the host root with `git diff --cached` limited to that subdirectory via shell-quoted git pathspecs, recorded as `# gbrain-scope: <dir>/` marker lines (one per guarded scope). The script carries `# gbrain-hook-version: N` (`FRONTMATTER_HOOK_VERSION`; no marker = version 1, which validated working-tree bytes), lists staged paths with `-z | tr '\0' '\n'`, collects them in a heredoc-fed `while IFS= read -r` loop (spaces and non-ASCII names survive; a newline inside a name is unsupported) and runs ONE `gbrain frontmatter validate --staged -- <paths>`, which checks the staged blobs under the strict producer rule and names failures as staged content. `inspectFrontmatterHook(localPath, sourceId?)` (read-only) returns the installed gbrain hook's version, `current`, and the `install-hook --force` refresh argv for doctor and post-upgrade. One hook per root — nested sources union their scopes on install and drop only their own on uninstall (the last one removes the file); a root-registered source renders the unscoped script and owns the whole hook. A foreign `.githooks/pre-commit` still needs `--force` (`.bak` saved, restored on uninstall). Both install and uninstall resolve the hook location through `hookPaths(root)`, which lstat-refuses a symlinked `.githooks/` or `pre-commit` (a committed link in a host repo would redirect the write/chmod/rm elsewhere); the CLI prints the refusal as a `skipped` line and continues with the other sources. Only a path outside any repo is otherwise skipped. Every branch that leaves a hook on disk — fresh write, `--force` overwrite, or a byte-identical refresh — reaches the wiring step, because the hook FILE travels with the repo while `core.hooksPath` is per-clone config: a fresh clone of a repo that committed the hook reports `installed` (and gets wired) rather than `unchanged` while inert; `unchanged` means current AND wired. Before wiring `core.hooksPath`, `hooksPathBlocker(root)` returns the operator-facing reason wiring is unsafe, or null: a `core.hooksPath` already set (any scope — a global/corporate value counts; `--type=path`-expanded and resolved against the root) to anywhere that does not realpath to `.githooks` (theirs to keep; git never reads `.githooks/` then — one resolving to `.githooks` counts as wired), a foreign executable under `.githooks/` (wiring would start running it — third-party clones commit hooks there) or an active hook in the repo's own hooks dir (`activeGitHooks` — executable non-`*.sample` entries under `<git rev-parse --git-common-dir>/hooks`, immune to a foreign `core.hooksPath`; wiring would make git ignore them). Every git spawn passes `env: process.env` (Bun's default child env is a startup snapshot), so `GIT_CONFIG_*` overrides reach the child. Any blocker returns `installed_unwired` — the hook is written, `core.hooksPath` stays untouched, and the CLI prints the reason + the manual `git config core.hooksPath .githooks` step. Pinned by `test/frontmatter-install-hook.test.ts`.
+- `src/commands/doctor/checks/outside-content-fences.ts` — `outside_content_fences` (GBRA-221, BRAIN, registered after `fence_integrity`, before `search_mode`). Lists facts (`row_num` set, active; world-visible counted apart), active takes and `links_fence` links indexed from a fence on an imported page whose body is outside-authored text (Google `email`/`meeting` pages, every GitHub-source page, pages with `transcript_import` frontmatter). Reads the derived rows, never a page body, so segmented pages are covered. Before GBRA-221 a sender could plant such rows and a re-render carries a stored fence forward; gbrain writers also add rows on purpose, so it only lists pages (location and counts, never a cell value) with an `ask_user` review fix (`gbrain get`) and removes nothing.
diff --git a/docs/architecture/key-files/graph-and-facts.md b/docs/architecture/key-files/graph-and-facts.md
index 4a2118a31a..70e4192579 100644
--- a/docs/architecture/key-files/graph-and-facts.md
+++ b/docs/architecture/key-files/graph-and-facts.md
@@ -101,7 +101,6 @@ rejection of serve-only flags before a brain opens.
- `src/core/facts-fence.ts` — the `## Facts` fence primitives: parse (`parseFactsFence`; #6385: cells are read by the column the header names (`factsHeaderLayout`, `FACTS_FENCE_COLUMNS`), so an unknown, repeated or missing required header column is one `FACTS_TABLE_MALFORMED` and no rows, a header in canonical order keeps the positional typed tail, and `factsRowProblem` lets a row leave off only trailing optional columns and refuses a non-empty cell past the layout; a confidence cell outside 0..1 or not a plain number is `FACTS_TABLE_MALFORMED`, a `claim_value` cell parses strictly (plain/scientific numbers, `1,234,567` separators, a leading currency symbol, a k/M/B suffix that scales; anything else such as `1,5` or `0.9abc` is `FACTS_TABLE_MALFORMED`), `formatFenceDate` writes UTC-midnight dates as `YYYY-MM-DD` and any other instant as a UTC timestamp so TTLs and write-time `valid_from` round-trip, so the page is non-authoritative instead of failing the DB CHECK), render (`renderFactsTable`), and strip (`stripFactsFence({keepVisibility})` — the remote-read privacy boundary `get_page`/`fetch_page`/the chunker apply), plus the remote write-back merge, plus the ONE fence-placement rule: `replaceOrInsertFactsFence(body, fenceBlock)` replaces an existing fence in place or inserts a fresh `## Facts` section ABOVE the timeline sentinel (`timelineSentinelOffset`, #4756 — below it splitBody() files the fence into page.timeline where extract_facts refuses to reconcile it), EOF only when the page has no sentinel; every writer that materializes a fence (`upsertFactRow`, the phantom-redirect canonical append, the importer's hidden-row merge) routes through it, so no writer can re-grow its own EOF append. `upsertFactRow` throws `FenceRewriteRefusal` (fence-shared.ts) when the fence it starts from parses with warnings (#6385 R12): it re-renders the parsed rows, so a rewrite would delete the rows the parser skipped. `restoreHiddenFactRows(incoming, existing)` is the row-level, visibility-aware merge `import-file.ts` applies per fence-bearing column (compiled_truth AND timeline) when a remote caller writes back a page it read with hidden rows stripped — without it, a remote get→edit→put round-trip would silently drop every non-`world` fact row. Rules: only non-`world` rows of the existing fence are restoration candidates (a caller's deletion of a VISIBLE row stays honored — world rows are never restored); a hidden row whose rowNum is absent from the incoming fence is restored at its stable rowNum (cross-page `#F<N>` refs survive); a rowNum collision (a caller-authored addition landing on a hidden number the caller never saw) keeps the hidden row's number and renumbers the CALLER's row onto fresh appended numbers (upsertFactRow's append-only contract); same rowNum + same claim keeps the incoming version (idempotent full-content write-throughs); either side parsing with warnings returns null — re-rendering a fence that didn't fully parse would drop the caller's unparsed rows — and `factsGapWarning` surfaces exactly that residual loss. Pure and side-effect-free. Pinned by `test/facts-fence.test.ts` + the remote write-back describes in `test/privacy-strip-and-forget.test.ts` (row-level merge, world-only deletion honored, timeline-embedded fence round-trip).
- `src/core/facts/attribution.ts` — speaker attribution's one dedup rule: `attributionCompatible(a, b)` is false only for two different known speakers (`user`, `assistant`, `other`); NULL (no recorded speaker) is compatible with either. Every dedup path applies it before candidate limits: `findCandidateDuplicates` (`attributedTo` option, SQL pre-limit), `decideSingleFact` exact and cosine matches, capture exact/near matches, hot-memory collapse (`collapseHotFacts` splits a fingerprint group by speaker when it holds two), fence reindex (`duplicateActiveFenceRows`) and the managed batch key (`facts-prepare.ts`). `facts.attributed_to` (migration v215) is written by the extractor (`facts.attribution`, default on per `docs/eval/decisions/p2-e3-heldout/`; `false` opts out), carried in the fence's 15th cell (only on rows that have it), returned by `recall` and hot memory, rendered `(assistant said)` in context packs, and kept out of `consolidate` (takes are the user's own). Pinned by `test/facts/speaker-attribution.test.ts`.
-- `src/core/outside-content.ts` — GBRA-221: `neutralizeOutsideText(text)`, the one neutralizer for text a third party wrote before it lands in a page body (Gmail/Calendar/Contacts renders in `google-render.ts`, GitHub `renderItemPage`/`renderRepoCard`, chat transcripts in `transcripts/render.ts`, `book-mirror` chapter output). It escapes every `gbrain<ws>:<ws><name>` marker token to `gbrain\:<name>` (case-insensitive), `[Source:` to `[Source\:`, and backslash-prefixes each timeline sentinel, bare `## Timeline`/`## History` heading, dated timeline row or heading, transcript message anchor and date heading, using the parsers' own predicates. Idempotent and readable; apply it per outside field (or a composed line holding one), never to a whole page that may hold gbrain's own fences or citations. Also owns `escapeAnchorLines` and `MESSAGE_ANCHOR_RE` (re-exported by `transcripts/render.ts`). New connectors use it.
- `src/core/fence-shared.ts` — shared pipe-table primitives for the `## Takes` (`takes-fence.ts`) and `## Facts` (`facts-fence.ts`) fences: `parseRowCells`, `isSeparatorRow`, `stripStrikethrough`, `parseStringCell`, `escapeFenceCell`, and the rewrite guard (#6385 R12) `assertFenceRewritable` / `FenceRewriteRefusal` that `upsertFactRow`, `upsertTakeRow`, `supersedeRow` and `mergePhantomFenceRows` throw when their input fence parses with warnings (the message names the fence only; the warnings, which embed row text, stay on the error). `parseRowCells` is escape-aware: `\|` stays inside its cell and decodes back to a literal `|` (exact inverse of `escapeFenceCell`), while any other backslash passes through verbatim so existing fence text (e.g. Windows paths) is byte-stable across a render → parse cycle. This matters because the fence is canonical and reconcile is wipe-and-reinsert — a pipe inside a cell shifting the column layout would corrupt every row behind it on the next reconcile. `escapeFenceCell` also encodes fence-marker text (`gbrain:facts:begin` and the three siblings) by lengthening the ampersand run before `#58;` (`gbrain:X` → `gbrain&#58;X`, a literal `gbrain&#58;X` → `gbrain&amp;#58;X`), and `decodeFenceCell` (the decoder `parseRowCells` and `fence-repair/raw-rows.ts` share) removes exactly one level, so a claim that quotes a marker never becomes a live marker and a literal entity round-trips byte-identically; the lexical fail-closed privacy rule is unchanged. Pinned by the escape cases in `test/facts-fence.test.ts` + the full render → parse → reconcile round-trip in `test/e2e/facts-fence-reconcile-postgres.test.ts`.
- `src/core/link-extraction.ts` — shared library for the graph layer. `extractEntityRefs` (canonical) matches `[Name](../people/slug)` markdown links and Obsidian `[[people/slug|Name]]` wikilinks; `extractPageLinks`, `resolveMarkdownLinkSlug` (one markdown href resolved from a page exactly as `extractPageLinks` resolves it; the writer's link validator, `src/core/output/validators/link.ts`, uses it so its dangling-link verdict matches the graph), `inferLinkType` heuristics (attended/works_at/invested_in/founded/advises/source/mentions), `parseTimelineEntries`, `isAutoLinkEnabled`. In `inferLinkType` a per-edge verb counts only when it belongs to the link being typed (`attachedVerb`: a match with another link between it and this one, or written immediately before another link, is that link's), then precedence founded > invested_in > advises > works_at decides; `joined [X] as <role>` reads as works_at. `attendanceEvidenceRanges` accepts an `Attendees:`/`Participants:` line (plain or bold) and a `## Attendees`/`## Participants` link-list section (`Participants` since gbrain-evals N12-6, with a `LINK_EXTRACTOR_VERSION_TS` bump so meeting pages re-extract). Markdown links, bare-slug prose refs, and slash-shaped wikilinks match ANY dir-shaped path (`ANY_DIR_SEGMENT`), not a directory whitelist — nonexistent targets are dropped by the persist paths' page-existence checks (`resolveCandidateSources`, put_page's allSlugs filter, `addLinksBatch` INNER JOINs) and counted as `skippedMissingTarget` in the extract summaries; the `DIR_PATTERN` whitelist is only the typed fast-path for pass-2b wikilinks (non-whitelisted `[[dir/...]]` get an equivalent direct typed candidate in pass 2c, plus the flag-gated suffix rescue for non-exact matches). Used by extract.ts, operations.ts auto-link post-hook, and backlinks.ts. **Opt-in global-basename wikilink resolution** (default off): `WIKILINK_GENERIC_RE` catches bare `[[name]]` wikilinks outside `DIR_PATTERN` (third pass `2c` in `extractEntityRefs`); `EntityRef.needsResolution: true` tags refs from this pass (the ref's `slug` is the wikilink TARGET, `name` the optional display alias). `SlugResolver` gains optional `resolveBasenameMatches(name): Promise<string[]>` (multi-match by design — emits one edge per matching page). The single shared basename matcher is `buildBasenameIndex(slugs)` + `queryBasenameIndex(index, name)` + `normalizeBasename` (keys raw/lower/slugified tail, stable-sorted shorter-first then lexical), used by `makeResolver`, the FS `resolveBasenameMatchesFromSlugs`, AND the doctor check so they cannot drift. `makeResolver` step 1 and the FS resolver try `exactSlugCandidates` (`exact-slug-candidates.ts`: the value, then `slugifyPath`), then `resolveSlugWithAlias` (rename aliases); its fuzzy title step and live keyword step (source-scoped) accept a person/company/fund/organization candidate only under `sameEntityName`, so a near-name stays unresolved instead of linking to a different entity (`test/entity-resolution-near-names.test.ts`). With `link_resolution.global_basename` on, `extractFrontmatterLinks` passes `resolve(name, dirHint, { globalBasename, selfSlug })`, and a unique basename match (self excluded) resolves right after the exact steps and before the fuzzy and live keyword steps, the exact-name-first precedence of `resolveEntitySlug` (#5749, `test/link-resolution-basename-before-search.test.ts`). `makeResolver(engine, {mode, sourceId})` builds the index lazily via `engine.getAllSlugs({sourceId})` — source-scoped so a bare `[[name]]` never resolves to a same-tail page in a different source. `extractPageLinks` gains `opts.globalBasename` (routes `needsResolution` refs through `resolveBasenameMatches` keyed on `ref.slug`, emits candidates tagged `linkType: 'wikilink_basename'` + `linkSource: 'wikilink-resolved'`, skips self-loops) and `opts.skipFrontmatter`. All three surfaces (FS extract, DB extract, `put_page` auto-link) tag provenance with `link_source='wikilink-resolved'`; `put_page` includes it in its reconcilable-edge set so stale basename edges are removed when the wikilink or the flag goes away. Exports `WIKILINK_BASENAME_LINK_TYPE` + `isGlobalBasenameEnabled(engine)` (resolution order: env `GBRAIN_LINK_RESOLUTION_GLOBAL_BASENAME` → DB config `link_resolution.global_basename` → default false). `gbrain doctor`'s `link_resolution_opportunity` check surfaces a paste-ready enable hint when ≥5 bare wikilinks would resolve AND ≥20% match. Migration v113 widens `links_link_source_check` to admit `'wikilink-resolved'`; v114 then opens it to any kebab-case provenance (`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, ≤64 chars) so external derivers register their own tag (e.g. `citation-graph`) without a migration. `LINK_EXTRACTOR_VERSION_TS` also lives here (bump like `CHUNKER_VERSION` to invalidate prior extract-stale stamps). Pinned by `test/link-extraction.test.ts`, `test/extract-fs.test.ts`, `test/doctor.test.ts`, `test/e2e/global-basename-pglite.test.ts`. #6191: `inferLinkType` applies `link-target-roles.ts` `targetTakesVerb` to every per-edge and fallback verb: `works_at` never types a link to a person, meeting, calendar-event, media, image or transcript target (unknown type: a `people/`, `meetings/`, `calendar/`, `cal/` slug), `founded`/`invested_in` never a temporal or media one; a refused verb keeps scanning lower-precedence rules, then `mentions` (`test/link-type-target-guard.test.ts`).
diff --git a/docs/architecture/key-files/security.md b/docs/architecture/key-files/security.md
index e620047160..b9f0b57648 100644
--- a/docs/architecture/key-files/security.md
+++ b/docs/architecture/key-files/security.md
@@ -41,3 +41,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/git-env.ts` + `src/core/hardened-git.ts` — #7584, the operator's `safe.directory` in scrubbed Git environments: `hardenedGitEnvironment` still drops system and global config and every `GIT_*` variable, but carries the operator's `safe.directory` entries (system and global, read from `/` with `git config --includes --show-scope` and cached for 30 s, then `GIT_CONFIG_*`) as environment config, so a source repository owned by another user reads once the operator allows it. `gitChildEnv` carries the environment entries the same way (`envSafeDirectories`, `safeDirectoryEnv`). Every other key in those places stays out. Test: `test/hardened-git-safe-directory-7584.test.ts` (ownership forced with `GIT_TEST_ASSUME_DIFFERENT_OWNER` through a `git` wrapper on PATH).
+- `src/core/outside-content.ts` — GBRA-221: `neutralizeOutsideText(text)`, the one neutralizer for text a third party wrote before it lands in a page body (Gmail/Calendar/Contacts renders in `google-render.ts`, GitHub `renderItemPage`/`renderRepoCard`, chat transcripts in `transcripts/render.ts`, `book-mirror` chapter output). It escapes every `gbrain<ws>:<ws><name>` marker token to `gbrain\:<name>` (case-insensitive), `[Source:` to `[Source\:`, and backslash-prefixes each timeline sentinel, bare `## Timeline`/`## History` heading, dated timeline row or heading, transcript message anchor and date heading, using the parsers' own predicates. Idempotent and readable; apply it per outside field (or a composed line holding one), never to a whole page that may hold gbrain's own fences or citations. Also owns `escapeAnchorLines` and `MESSAGE_ANCHOR_RE` (re-exported by `transcripts/render.ts`). New connectors use it.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index d26b8e1297..40242d2224 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -45,7 +45,7 @@
| 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: an imported email, calendar, GitHub or transcript page holds live fence rows](#outside-content-fences) | review each listed page with the user (`gbrain get --source <id> -- <slug>`); withdraw a row they confirm a sender planted with `gbrain forget`. Nothing is removed automatically | agent reads; the user decides each row | the user agrees to each withdrawal | `gbrain doctor --only outside_content_fences --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,7 +108,7 @@
<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, the Google, GitHub and chat-transcript importers copied third-party text into the page body verbatim, so an email, calendar description, issue comment or chat message that carried `<!--- gbrain:facts:begin -->` and a table became a live fence on that page. `extract_facts` then indexed the rows with the visibility and confidence the sender wrote, and a later re-render carries a stored fence forward. Imports now neutralize the markers (`gbrain\:facts:begin`), so new mail cannot do this. The check lists every imported page that still holds live facts, takes or links rows, with counts and never a cell value. gbrain writers (`remember`, loop extraction) also add rows to such pages on purpose, and the check cannot tell which is which, so it removes nothing. Read each page with the user (`gbrain get --source <id> -- <slug>`). For each row they say a sender wrote, withdraw it with `gbrain forget` after they agree. **Say to your agent:** *"Which imported pages hold facts a sender could have planted? Show me before you remove anything."*
+<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).
diff --git a/llms-full.txt b/llms-full.txt
index 76575d3143..0483356dc3 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -10240,6 +10240,7 @@ 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` |
@@ -10302,6 +10303,8 @@ 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 315699e505..e9716bc647 100644
--- a/src/commands/doctor/checks/outside-content-fences.ts
+++ b/src/commands/doctor/checks/outside-content-fences.ts
@@ -1,59 +1,57 @@
/**
- * GBRA-221 `outside_content_fences`: live facts, takes and links fence rows on pages whose body is text a third party
- * wrote (Gmail threads and calendar events from a Google source, GitHub issues, PRs and repo cards, imported chat
- * transcripts). Before GBRA-221 those renderers copied a sender's `<!--- gbrain:facts:begin -->` table into the page
- * verbatim, extract_facts promoted its rows (visibility and confidence as the sender wrote them), and a later re-render
- * carries a stored fence forward as if gbrain had written it. Renders now neutralize the markers, so a fence still on
- * such a page was planted before the fix or added by a gbrain writer (`remember`, loop extraction) on purpose; the
- * check cannot tell which, so it lists each page for review and removes nothing. Contact pages are out of scope: their
- * single-line fields cannot hold a fence. Location and counts only, never a cell value. Reads the database only.
+ * GBRA-221 `outside_content_fences`: facts, takes and links that gbrain indexed from a fence on a page whose body is
+ * text a third party wrote (Gmail threads and calendar events from a Google source, GitHub issues, PRs and repo cards,
+ * imported chat transcripts). Before GBRA-221 those renderers copied a sender's `<!--- gbrain:facts:begin -->` table
+ * into the page verbatim, extract_facts promoted its rows (visibility and confidence as the sender wrote them), and a
+ * later re-render carries a stored fence forward as if gbrain had written it. Renders now neutralize the markers, so a
+ * fence row still indexed from such a page was planted before the fix or added by a gbrain writer (`remember`, loop
+ * extraction) on purpose; the check cannot tell which, so it lists each page for review and removes nothing. It reads
+ * the derived rows (`facts.row_num`, `takes`, `links.origin_field = 'links_fence'`), never a page body, so a
+ * segmented page is covered too. Contact pages are out of scope: their single-line fields cannot hold a fence.
+ * Location and counts only, never a cell value. Reads the database only.
*/
import type { Check } from '../../doctor.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
-import { checkError, doctorVerify, withSkippedSegmented } from '../check-fix.ts';
-import { parseFactsFence } from '../../../core/facts-fence.ts';
-import { parseTakesFence } from '../../../core/takes-fence.ts';
-import { parseLinksFence } from '../../../core/links-fence.ts';
+import { checkError, doctorVerify } from '../check-fix.ts';
const NAME = 'outside_content_fences';
-const MARKER_SQL = 'gbrain:(facts|takes|links):begin';
-interface Row { source_id: string; slug: string; type: string; compiled_truth: string | null; timeline: string | null; segmented: boolean }
+interface Item { source_id: string; slug: string; type: string; facts: number; world_facts: number; takes: number; links: number }
async function runOutsideContentFences(ctx: DoctorContext): Promise<Check[]> {
const checks: Check[] = [];
try {
- const rows = await connectedEngine(ctx).executeRaw<Row>(
- `SELECT p.source_id, p.slug, p.type, p.compiled_truth, p.timeline, p.body_storage = 'segmented' AS segmented
- FROM pages p JOIN sources s ON s.id = p.source_id
+ const items = await connectedEngine(ctx).executeRaw<Item>(
+ `SELECT p.source_id, p.slug, p.type, sum(x.facts)::int AS facts, sum(x.world_facts)::int AS world_facts,
+ sum(x.takes)::int AS takes, sum(x.links)::int AS links
+ FROM (SELECT fp.id AS page_id, 1 AS facts, CASE WHEN f.visibility = 'world' THEN 1 ELSE 0 END AS world_facts, 0 AS takes, 0 AS links
+ FROM facts f JOIN pages fp ON fp.source_id = f.source_id AND fp.slug = f.source_markdown_slug
+ WHERE f.row_num IS NOT NULL AND f.expired_at IS NULL
+ UNION ALL SELECT t.page_id, 0, 0, 1, 0 FROM takes t WHERE t.active
+ UNION ALL SELECT l.origin_page_id, 0, 0, 0, 1 FROM links l WHERE l.origin_field = 'links_fence') x
+ JOIN pages p ON p.id = x.page_id
+ JOIN sources s ON s.id = p.source_id
WHERE p.deleted_at IS NULL AND s.archived IS NOT TRUE
AND ((s.config->>'kind' = 'google' AND p.type IN ('email', 'meeting')) OR s.config->>'kind' = 'github'
OR p.frontmatter ? 'transcript_import')
- AND (p.body_storage = 'segmented' OR p.compiled_truth ~ $1 OR p.timeline ~ $1)
- ORDER BY p.source_id, p.slug`, [MARKER_SQL]);
- const segmented = rows.filter(row => row.segmented).length;
- const items = rows.filter(row => !row.segmented).map(row => {
- const body = `${row.compiled_truth ?? ''}\n${row.timeline ?? ''}`;
- return { source_id: row.source_id, slug: row.slug, type: row.type, facts: parseFactsFence(body).facts.length,
- takes: parseTakesFence(body).takes.length, links: parseLinksFence(body).rows.length };
- }).filter(item => item.facts + item.takes + item.links > 0);
+ 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' };
if (!items.length) {
- checks.push(withSkippedSegmented({ name: NAME, status: 'ok', details,
- message: 'No imported email, calendar, GitHub or transcript page holds a live facts, takes or links fence row.' }, segmented));
+ 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.' });
return checks;
}
const first = items[0]!;
- const list = items.slice(0, 5).map(item => `${item.source_id}:${item.slug} (facts ${item.facts}, takes ${item.takes}, links ${item.links})`).join('; ');
- checks.push(withSkippedSegmented({ name: NAME, status: 'warn', details,
- message: `${items.length} imported page(s) whose body is outside-authored text hold live fence rows: ${list}${items.length > 5 ? `; and ${items.length - 5} more` : ''}. `
- + 'A sender could plant these before this release, and extract_facts indexes them; gbrain writers also add rows on purpose. '
- + 'Review each page with the user; nothing is removed automatically.',
+ const list = items.slice(0, 5).map(item => `${item.source_id}:${item.slug} (facts ${item.facts}, world ${item.world_facts}, takes ${item.takes}, links ${item.links})`).join('; ');
+ checks.push({ name: NAME, status: 'warn', details,
+ message: `${items.length} imported page(s) whose body is outside-authored text have fence rows indexed as facts, takes or links: ${list}${items.length > 5 ? `; and ${items.length - 5} more` : ''}. `
+ + 'A sender could plant these before this release; gbrain writers also add rows on purpose. Review each page with the user; nothing is removed automatically.',
fix: { argv: ['gbrain', 'get', '--source', first.source_id, '--', first.slug], consent: [], actor: 'agent', ask_user: true, requires_exclusive: false,
why: `Shows ${first.source_id}:${first.slug} so the user can say which fence rows a sender wrote; a planted fact is withdrawn with gbrain forget after they agree. Repeat per page in details.items.`,
- verify: doctorVerify(NAME) } }, segmented));
+ verify: doctorVerify(NAME) } });
} catch (error) {
- checks.push(checkError(NAME, 'scan imported pages for live fence rows', error, { details: { health: 'unknown' } }));
+ checks.push(checkError(NAME, 'list fence rows indexed from imported pages', error, { details: { health: 'unknown' } }));
}
return checks;
}
diff --git a/test/doctor-outside-content-fences.test.ts b/test/doctor-outside-content-fences.test.ts
index e04a827984..08ffa87a3e 100644
--- a/test/doctor-outside-content-fences.test.ts
+++ b/test/doctor-outside-content-fences.test.ts
@@ -1,10 +1,12 @@
/**
- * GBRA-221 outside_content_fences: live fence rows on imported pages whose body is outside-authored text are listed for
- * review (location and counts only, never a cell value); pages a gbrain writer owns are not. PGLite in-memory ($0).
+ * GBRA-221 outside_content_fences: fence rows extract_facts indexed from imported pages whose body is outside-authored
+ * text are listed for review (location and counts only, never a cell value); pages a gbrain writer owns are not.
+ * PGLite in-memory ($0).
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
+import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import { outsideContentFencesEntry } from '../src/commands/doctor/checks/outside-content-fences.ts';
import { categorizeCheck } from '../src/core/doctor-categories.ts';
import type { DoctorContext } from '../src/commands/doctor/context.ts';
@@ -38,6 +40,9 @@ async function page(sourceId: string, slug: string, type: string, body: string,
}
async function run(): Promise<Check> {
+ for (const sourceId of ['google-example', 'notes-example', 'github-example']) {
+ if ((await engine.executeRaw('SELECT 1 FROM sources WHERE id = $1', [sourceId])).length) await runExtractFacts(engine, { sourceId });
+ }
const checks = await outsideContentFencesEntry.run({ engine } as unknown as DoctorContext) as Check[];
expect(checks).toHaveLength(1);
return checks[0]!;
@@ -62,10 +67,10 @@ describe('outside_content_fences doctor check', () => {
await page('notes-example', 'conversations/chat-example', 'conversation', FENCE, 'transcript_import:\n harness: example\n session_id: s1\n');
const check = await run();
expect(check.status).toBe('warn');
- const items = (check.details as { items: Array<{ source_id: string; slug: string; facts: number }> }).items;
+ const items = (check.details as { items: Array<{ source_id: string; slug: string; facts: number; world_facts: number }> }).items;
expect(items.map(item => `${item.source_id}:${item.slug}`).sort()).toEqual([
'github-example:gh/acme-example/app/1', 'google-example:emails/2026/01/planted-thread', 'notes-example:conversations/chat-example']);
- expect(items.every(item => item.facts === 1)).toBe(true);
+ expect(items.every(item => item.facts === 1 && item.world_facts === 1)).toBe(true);
expect(check.message).not.toContain(CLAIM);
expect(JSON.stringify(check.details)).not.toContain(CLAIM);
expect((check.fix as { ask_user?: boolean }).ask_user).toBe(true);
diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.json
index 08e4f806e0..76233808f9 100644
--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json
+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json
@@ -3351,7 +3351,7 @@
"pages": 0
},
"elapsed_ms": "<volatile>",
- "message": "No imported email, calendar, GitHub or transcript page holds a live facts, takes or links fence row.",
+ "message": "No fact, take or link is indexed from a fence on an imported email, calendar, GitHub or transcript page.",
"name": "outside_content_fences",
"status": "ok"
},
diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.json
index 030237abf0..1263cabd45 100644
--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json
+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json
@@ -3394,7 +3394,7 @@
"pages": 0
},
"elapsed_ms": "<volatile>",
- "message": "No imported email, calendar, GitHub or transcript page holds a live facts, takes or links fence row.",
+ "message": "No fact, take or link is indexed from a fence on an imported email, calendar, GitHub or transcript page.",
"name": "outside_content_fences",
"status": "ok"
},
diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.json
index ee81dbafcf..a97ba7bcba 100644
--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json
+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json
@@ -3389,6 +3389,18 @@
"name": "fence_integrity",
"status": "ok"
},
+ {
+ "category": "brain",
+ "details": {
+ "docs": "docs/guides/troubleshooting.md#outside-content-fences",
+ "items": [],
+ "pages": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No fact, take or link is indexed from a fence on an imported email, calendar, GitHub or transcript page.",
+ "name": "outside_content_fences",
+ "status": "ok"
+ },
{
"category": "ops",
"elapsed_ms": "<volatile>",