Garry's Opinionated OpenClaw/Hermes Agent Brain
Repair residual damage with gbrain repair
gbrain doctor finds some damage that it cannot fix on its own: timeline
history that exists only in the database, derived pages without an explicit
visibility, pages indexed before the safe-chunk fence, pages imported
without a contextual retrieval mode, connector checkpoint rows no source
can load, and Google source files other local users can read. gbrain repair
fixes those and the other kinds listed in
What each kind fixes. Every run is a preview unless
you pass --apply.
The explicit-only kinds, among them google-file-modes, stale-atoms, atoms-restore, atom-fence-rows, extractor-facts, unwithdrawn-facts, purged-page-facts, purged-change-reasons,
captured-facts, agent-session-facts, redacted-facts, loop-facts, ontology-facts, orphan-children, failed-writes, frontmatter, managed-sync-orphans, content-receipt-root, stuck-recovery, aliases, rename-identity and segmented-mirror, run only when you name them (see Explicit-only repair kinds).
gbrain doctor --remediation-plan lists the same kinds as repair steps, and
gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> runs them under a budget
(see Run repairs through doctor).
Say to your agent: "Doctor says some timeline history is only in the
database. Show me what gbrain repair would change, then apply it." The
agent runs gbrain repair to preview and, after you agree,
gbrain repair <kind> --apply on the brain host.
Preview first
gbrain repair # preview every automatic kind
gbrain repair timeline # preview one kind
gbrain repair --json # machine-readable preview
The preview names the brain and sources it will touch, then prints one block per kind:
Scope: brain <brain id>; sources default
timeline: 12 item(s) to repair
e.g. default:people/alice-example, default:companies/acme-example
materializable_rows=31, kept_unrenderable_rows=2
cost: 12 request ID(s), 196608 receipt bytes, 12 page(s) to re-embed
capacity brain lifetime_ids: 4100 of 1000000 (stops at 900000)
...
apply: gbrain repair timeline --apply
- Items are pages. The sample lists at most 10 of them as
source:slug. - Residuals are named counters: some count what the repair will do
(
materializable_rows,atoms_origin_gone_to_private), others count rows it leaves alone (see What each kind fixes). - Cost is what an apply of the pending items would consume: one permanent
request ID and 16 KiB of reserved receipt space per page for
timelineandvisibility, and nothing forsafe-chunksorcontextual-mode. When an embedding model is configured and priced, the line adds an estimated embedding cost in dollars. - Capacity shows the write-journal counters the run draws on and the 90% line where it stops (see Capacity stop).
- apply is the command that applies this kind with the same
--source(and--no-embed). It does not repeat--limit; add it yourself if you previewed a limited batch.
Apply
gbrain repair timeline --apply
gbrain repair visibility --apply # every class; or preview one window and apply it (below)
gbrain repair safe-chunks --apply
gbrain repair safe-chunks --apply --no-embed # re-seal text now, embed later
gbrain repair contextual-mode --apply
gbrain repair request-indexes --apply
gbrain repair google-file-modes --apply # explicit-only: runs only when named
gbrain repair --all --apply # every automatic kind in order
On a large brain, apply visibility one previewed window at a time. The preview
plans one class at a time in the order remote callers are exposed (world facts
from a private page, remotely readable ones first; Life Chronicle events;
alias-only pages; then atoms and concepts, the only class that reads
concept-provenance links), reports progress on stderr, lists one window
(1,000 items; --limit up to 10,000) and prints the apply command for it:
gbrain repair visibility --class facts # one class: facts, events, aliases or lineage
gbrain repair visibility --class facts --apply --expect <hash> # exactly that window
gbrain repair visibility --slug notes/a-example # make named pages private (repeatable)
gbrain repair visibility --slug notes/a-example --apply --expect <hash>
gbrain repair visibility --slug notes/a-example --readers alice-example,group:team-a # set who reads it
gbrain repair visibility --slugs-file pages.txt --readers alice-example --apply --expect <hash>
gbrain repair visibility --slug notes/a-example --readers none # remove readable_by
Every visibility write is label-only: the page keeps its trust tier, files no
lower_page proposal, and its file changes only on the visibility line (a fact
item: its fence row). Stamps gbrain keeps only in the database (a type a schema
pack renamed, the validate: false grandfather stamp, a legacy_type retype
record) do not count as a difference: such a page is labelled and its file
still gains only the label line (GST-2603). A page whose file cannot take the
change line by line (a label with a block value or a duplicate key, no
frontmatter block, or a file that differs from the page in a real key such as a
date, the tags, the title or the body) is held by the preview: it is listed
under details.held with the key that blocks it and its next step
(gbrain sources reconcile <id> <slug> --preview for a file edited outside
gbrain, the field to fix for a label line), and it stays out of the hash and
the approved set. A page that starts refusing after the preview is declined
with label_edit_refused and nothing
written; it never counts toward item_failures_systemic, so the rest of the
window applies and the receipt names the pages that did.
Labels and folder rules apply per source. When another source holds a live
page with the same slug, labelling the page in one source leaves that copy as
it was, and a reader with no source filter still finds it by slug and in
search. So the preview also lists those copies under details.open_twins:
every same-slug page in another source that is not private already and that a
caller outside the change could read (by its own readable_by and folder
rules). It gives their count and the command that covers them, such as
gbrain repair visibility --source <other> --slug <slug>. The list is
read-only, checks at most 1,000 pages and names at most 50 copies; it is not
part of the preview hash, so applying the window changes only the window. The
--readers preview lists copies a member outside the new readers could read,
gbrain repair private-labels --class restore lists them too, and the preview
of gbrain access rule add or gbrain access rule import lists copies a
narrowed rule leaves open, with the same rule for --source <other>. Whether
a label should follow a copy is your call; nothing changes the copy for you. --slug is the operator's way to make one page private;
a put_page that adds the label is an agent edit and lowers the page. On a brain
without managed persistence, a page whose file sits in its source's checkout gets
the same edit in that file and in the database together, so the next sync reads
the same page. A file holding an edit the database lacks refuses with nothing
written (run gbrain sync first). A file the repair cannot write
(sync.write_through is off, a clone gbrain pulls, a write error) is held
file_backed with nothing written, because the next sync would put the old
label back from the file; make that edit in the file by hand.
--readers <list> sets the named pages' readable_by (members by id, groups as
group:<id>, none removes it) through the same label-only write: the page
keeps its trust tier and provenance, files no lower_page proposal, and its
file changes only on the readable_by line (written readable_by: [a, b]).
Name the pages with --slug (repeatable) or --slugs-file <file> (one slug per
line; blank lines and # comments are skipped; up to 10,000 pages, all in one
preview). An unknown or disabled member, or an unknown group, refuses
access_member_invalid with nothing written. A list that leaves out the brain
owner (gbrain access owner) refuses too, because readable_by binds the owner
and its own keys would stop reading the page; a group the owner belongs to does
not count. Pass --allow-without-owner when that is what you want. A page whose
readers changed after the preview is skipped.
Proposed readers. On a brain that serves several people, gbrain repair visibility --propose [--source <id>] [--out <dir>] [--json]
suggests readers for the pages every member's key can read (no readable_by, no
folder or page rule). It reads each such page's participants, attendees, to, from and
cc addresses and matches each one to an enabled member by the email declared on it
(gbrain access member set <id> --email <address>), exactly and ignoring case. Pages
whose addresses all match are grouped by reader set, with the owner first in every set. Each set gets
a slugs file (mode 0600, in <config dir>/visibility-proposals/ or --out, never inside a
git work tree) and the --readers command above to preview it, then apply it with
--apply --expect <hash>. A page with any address that names no enabled member is
listed as unmatched and gets no proposal, and so is a page whose slug a slugs file cannot carry (it
starts with #, has surrounding spaces or holds a line break): label it with --slug. DM, chat and mail pages with no address list are listed by
folder with a gbrain access rule add --prefix <folder>/ --readers <owner>,<list> command to fill in.
Labelling a page also hides its derived atoms, facts and chronicle events from every remote caller
except the owner, unless access.members_read_lineage is on. --propose itself labels nothing
and changes nothing any key reads. A one-person brain, or one with access.serves set to one, gets
"nothing to propose". It works the same on a repo-less brain.
No lock or transaction spans the run, so a long list does not hold up other
writers. On a managed brain the apply admits a source's pages together, one
admission window at a time; on Postgres the owner publishes them in groups of
up to 8 pages (PGLite publishes one at a time). The Git effect then commits the
files that are ready together, up to 100 per commit, and waits briefly while
more of the run's writes are still publishing, so a long list lands in a few
large commits rather than one per page. Each page still succeeds or fails on
its own. --json reports
details.git, the run's files by effect state (committed, pending,
failed, and skipped for a storage.db_only page, which has no file). A
managed page with no file, outside any declared storage.db_only path, is held
canonical_file_missing with nothing written, because the write would put the
database ahead of Git: declare its folder under storage.db_only in gbrain.yml
and preview again, or restore the file (gbrain repair ghost-pages lists pages
whose file is gone). On a repo-less brain the database is the record, and every
page is written there.
A fenced fact row the apply could not make private is counted in the outcomes
(--json: outcomes, each row in outcome_items), and the text output says
NOT CLOSED: fact_left_readable when remote callers can still read the row,
fact_left_world when the row is still world and only its page's privacy hides
it from them. Today that happens when
the original row is more trusted than the repair (it is kept beside the new
private row), when the page is stored in segments, or when the row is not found
in the page's facts fence.
The apply touches only the listed items and resumes after its last applied item if it stops. Apply the window (or decide not to), then preview again for the next one. Each plan statement is bounded at 120 s; a class that overruns is reported and skipped while the other classes are listed.
--apply writes without a prompt, so review the preview first. With
--apply you must name a kind or pass --all; --yes is refused, and so is
any other option the table below does not list, including --max-usd: a
refused run changes nothing. To cap paid embedding work, run the repairs
through gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --max-usd <n>
(<plan_hash> comes from gbrain doctor --remediation-plan --json). --all
runs timeline, then visibility, then safe-chunks, then contextual-mode, then connector-checkpoints, then request-indexes, then connector-fences, then take-supersession, then orphan-bindings, then embedding-effects, then attribution-backfill, then planner-stats, and stops at the
first kind that stops.
The explicit-only kinds never run under
--all; it lists each with its preview command and still exits 0 when they
are the only findings left. gbrain repair with no kind does the same for a
preview. With --json the list is explicit_kinds[] (kind, code: "explicit_kind_required", preview_command, docs).
Each item is re-checked against the page's current state just before it is
written, and the write is bound to the revision it just read, so an edit made
after planning is kept and repaired too. An item that no longer needs the
repair, or whose page changes during the write, is counted as skipped and
left for the next run. An item the write refuses for its own reasons (its slug
is one the grammar no longer accepts, invalid_params; its file and database
copy disagree and neither is overwritten, source_changed) is listed in
failed[] with its reason and left exactly as it was, and the run goes on to
the next item. A failed item is not retried by a resumed run (a later success
moves the cursor past it); it is retried by the next full scan, which is the
printed apply_command once the run has completed. No kind deletes data except stale-atoms, which
soft-deletes the atoms it retires, and managed-sync-orphans, which deletes
only sync bookkeeping rows nothing current can resume (Managed sync
orphans). Retired atoms stay recoverable through the
restore_page operation for 72 hours, and a later extraction that produces
a retired atom again restores it. See Stale atoms.
extractor-facts only restores previewed facts (it clears expired_at and
gives each a fresh row number); it never deletes or rewrites a page.
| Option | Effect |
|---|---|
--apply |
Write the repair. Without it, only preview. |
--source <id> |
Limit the run to one active source. The default is every active (non-archived) source. An unknown or archived id is refused. |
--limit <n> |
Repair at most n items per kind in this run (a positive integer; with --all, up to n for each kind). Rerun the same command to continue. |
--no-embed |
safe-chunks and contextual-mode: skip the embedding provider. Run gbrain embed --stale later. timeline and visibility pages are re-embedded by their publication either way. |
--all |
Run every automatic kind in order. Explicit-only kinds are listed with their preview command, never run. |
--expect <hash> |
Explicit-only kinds: apply exactly the set the preview printed under this hash. Required with --apply for stale-atoms, atoms-restore, extractor-facts, unwithdrawn-facts, purged-page-facts, purged-change-reasons, captured-facts, redacted-facts, loop-facts, failed-writes, frontmatter, managed-sync-orphans and content-receipt-root. |
--include-ambiguous |
extractor-facts, unwithdrawn-facts, purged-page-facts, captured-facts and agent-session-facts: widen the hashed set to ambiguous facts. purged-change-reasons: add the path_mismatch rows. frontmatter: add interpretive file changes. Pass it to both the preview and the apply. See Extractor facts, Captured facts and Frontmatter. |
--only <path>, --skip <path> |
frontmatter only: select source-relative files (repeatable). The hash covers the selection, so pass the same flags to the apply. |
--diff |
frontmatter only: print every per-file diff instead of one sample per class (--json always carries all of them). |
--yes |
frontmatter --apply only: the user agreed to the previewed file changes (destructive consent). Without it a terminal asks, and a run without a terminal exits 3 with the consent payload. |
--json |
Print { scope, mode, results[], paid_kinds }, one result per kind with paid, affected, sample, residuals, cost, capacity, resumed_from, applied, skipped, failed[] (item, source_id, slug, reason, message, retry: "next_full_scan"), complete, stopped and apply_command, plus explicit_kinds[] when the run skipped explicit-only kinds. |
The command exits 1 when a run stops early (capacity, a pending write, or a
held writer) and when any item failed (failed[] is not empty; complete
still means every pending item was attempted). A --limit batch that leaves
work behind exits 0, so scripts should also check results[].complete.
gbrain doctor --remediate reports a repair step with failed items as
failed, never completed.
What each kind fixes
| Kind | Doctor check that points here | What it does | Left alone and counted |
|---|---|---|---|
timeline |
timeline_history |
Re-saves each page with its current body through a revision-bound put_page. The save writes each database-only timeline entry back into the page as a bullet preceded by <!-- gbrain:materialized v1 <hash> -->. |
kept_unrenderable_rows: entries that would change if written as a bullet (for example an empty source). They stay in the database. |
visibility |
derived_visibility |
Stamps an explicit visibility on extracted atoms and synthesized concepts. An atom takes its origin page's visibility, and becomes private when a rename moved its origin to a private page; transcript atoms and atoms whose origin is gone become private; a concept takes the strictest visibility of its input atoms. A concept input found only through an atom's concepts: list counts as private. Atoms are repaired before concepts. It never loosens an explicit value: private stays private, and world can only become private. A missing value is stamped with the origin's value, which is world when the origin page is public. |
concepts_without_lineage: concepts whose inputs cannot be found. One with no visibility is stamped private (what remote readers already treat it as), so the doctor warning clears; an explicit value stays as it is. atoms_origin_gone_to_private counts atoms made private because their origin page no longer exists. |
request-indexes |
persistence_request_indexes |
Creates a missing request-table index (the managed sync checkpoint pair, the purge slug index, the dream postprocess request-id index, the write claims' foreground-commit index, the failed-writes replay and page-sequence indexes), or drops an INVALID one (left by an interrupted concurrent build) and rebuilds it, on a brain whose schema version is already current. Postgres builds each index CONCURRENTLY, one at a time, so writes continue; PGLite builds inline. It changes no user data, takes no journal admission and runs brain-wide (--source does not narrow it). See managed sync request indexes. |
building: an index another session is still building; it is never dropped. |
connector-fences |
none (a connector_fence_below_timeline refusal names it) |
Moves a facts or takes fence that sits below the timeline sentinel of a Google or GitHub page into the page body through a revision-bound put_page, so the connector's next re-render carries the fence instead of refusing. Then re-attempt the held item with gbrain sources retry-held <source>. |
kept_ambiguous_pages: pages whose fences are duplicated, unbalanced or unparseable. Move the fence by hand: read the page, place the fence above the <!-- timeline --> line, and save it with the current expected_revision. |
take-supersession |
none | Rebuilds takes.superseded_by for supersession chains written before the pointer moved onto the old fence row (#5886). Each struck take is linked to the row that replaced it only from evidence: a committed takes_supersede receipt, a stored superseded_by, or a row carrying the old superseded by #<own row> pointer with exactly one possible predecessor. The pointer is written onto the old row (<source>; superseded by #N) and stale self-pointers are dropped through a revision-bound put_page; a page whose fence is already right but whose stored pointers differ is reprojected without a page write. See take supersession. |
ambiguous_pages / ambiguous_rows: pages where a new row has two or more possible predecessors, or where evidence conflicts. The preview lists each with its candidates and the manual edit; nothing on them changes. unparsed_pages: pages whose takes fence does not parse cleanly. |
accepted-takes |
none | Explicit-only, preview-bound. Restores takes that accepting a held strike-through or kind change removed on v0.60.253.0 (gbrain trust confirm tp<id> ran a takes_remove instead of applying the change). It restores only what the records prove: the accepted proposal, the takes_remove receipt bound to it, the page version that receipt archived (the row the accept should have applied) and the reservation row still holding its number. --apply --expect <hash> republishes each page with that row through a revision-bound put_page. See accepted takes. |
version_missing (the archived version was pruned), row_number_in_use (the number holds a take again), page_missing, fence_unreadable. A grade or resolution the database alone held is not in any record and is not restored. |
connector-checkpoints |
connector_checkpoints |
Deletes managed connector checkpoint rows and retry pointers that no registered connector source can load and that are older than 7 days. They accumulate after a content setting such as g_history_days changes, or when a connector host older than v0.60.11.0 runs during an upgrade. Cleanup only: it never copies or re-keys a checkpoint, takes no journal admission and runs brain-wide (--source does not narrow it). |
Rows a queued or running connector write, or a connector's recorded pending set, still references. |
orphan-bindings |
orphan_persistence_bindings |
Deletes persistence source bindings whose source was removed, or that belong to an earlier incarnation of a source re-added under the same id. gbrain sources remove and gbrain sources purge delete the binding; one an older gbrain left behind makes the re-added source read as claimed, so every gbrain sync --source <id> fails with writer_coordinator_required. Bookkeeping only: no journal admission, no page or file changes, and it runs brain-wide (--source does not narrow it). See orphan bindings. |
A binding that a queued, running or recovering write request of the same source incarnation still references. |
managed-sync-orphans |
sync_failures |
Explicit-only, preview-bound. Retires managed sync bookkeeping nothing current can resume or clear: a managed-sync-failure row whose cursor key has no cursor, and an unfinished managed-sync cursor recorded by a principal that is no longer an active local writer (or a pre-options cursor a later run superseded) whose pending request is terminal, or (#6834) a cursor whose checkpoint can never publish because the source's last_commit moved elsewhere (checkpoint_moved). op_checkpoints rows only; no journal admission, no page or file changes. The preview prints a hash; --apply --expect <hash> retires exactly that set. See managed sync orphans. |
An unfinished cursor whose pending request is still queued, running or recovering, or one the live writer can resume with its recorded options (doctor prints that sync command). |
content-receipt-root |
sync_freshness (content_receipt_stale) |
Explicit-only, preview-bound, owner host. Rebinds a gbrain-owned content source's shared-skills content receipt that still names an old root after a writer transfer or relocation, when the owner's tree still hashes to the recorded worktree manifest. It also lists an unfinished 0.53.0 setup checkpoint that names another root. The receipt row only; the previous value is kept under <key>.backup. See content receipt root. |
A receipt whose source path, owner host or tree does not match: listed with its class and the step to run first. |
stuck-recovery |
none (gbrain sources writer status shows the request recovering, or the withdrawal-mirror effect, with unexpected_file_bytes) |
Explicit-only, preview-bound, destructive consent. Resolves a live page or shared-skill bundle publication recovery whose file matches neither its recorded prior nor its published bytes, and a withdrawal-mirror effect recovery whose file was edited while it was mirroring; each stops every write on its worktree. The preview lists each blocked file with both fingerprints and writes a private diff; --apply --expect <hash> --keep prior|disk --yes backs up both versions, then restores the prior (the write publishes again) or keeps the edit and abandons the write (every file of a bundle one way); an effect's only choice, --keep withdrawn, backs up the edit and writes the withdrawn version. A file over 24 MiB resolves the same way, read in pieces, with a bounded diff summary. See stuck recovery. |
A terminal request with its recovery still set (listed as refused, recovery_choice_refused), an effect or bundle record that cannot be resolved (listed as refused, recovery_effect_unsupported or recovery_bundle_unsupported, with an ask_user fix), a record a newer gbrain wrote (listed as refused, recovery_version_unsupported, fix gbrain upgrade), --keep prior on a large-file recovery whose staged prior copy is missing or damaged (recovery_prior_stage_unavailable; --keep disk still resolves it), a recovery blocked on staging bytes, and a recovery whose file already matches a recorded version (the resident writer finishes those). |
frontmatter-keys |
stale_frontmatter_keys |
Explicit-only, preview-bound. Strips the parser's reserved top-level keys (type, title, tags, slug) that an older import stored inside pages.frontmatter. Since v0.60.176.0 those keys are not file/database drift and never render (#6454), so this is hygiene: database rows only, in source-scoped coordinated batches of up to 1,000 pages, no file, body or embedding change. Each swept page advances its knowledge_revision once, so a client holding an older revision of a swept page gets one revision_conflict and re-reads. See frontmatter keys. |
A page whose keys were cleared by a write between preview and apply (already_clean). |
embedding-effects |
stale_embedding_effects |
Settles stale queued and failed embedding effects of committed writes, which block receipt compaction and activation: reconciled when current vectors pass the effect verifier, superseded when the page was deleted or a newer revision owns its own effect, retry_queued for the owner (paid; a used-up retry allowance gets one new bounded cycle per explicit apply). See stale queued embedding effects. |
blocked effects, counted by reason (owner_unavailable, embedding_disabled, embedding_unconfigured, projection_pending, no_replacement_obligation). |
attribution-backfill |
none | Fills write attribution (who wrote it) on pages, page versions and facts written before attribution was recorded, only where exactly one committed request in the write journal proves the writer: the page write whose recorded result is the row's revision, or the remember that inserted the fact. Fills NULLs only, in committed batches of 1,000 that resume after an interruption; no content, revision, page file or request ID changes. See write attribution. |
unrecorded_pages, unrecorded_page_versions, unrecorded_facts: rows the journal cannot prove. They stay unrecorded; nothing is inferred. |
safe-chunks |
safe_index_pending (also contextual_retrieval_coverage, details.unsealed_pages) |
Rebuilds the chunks of markdown and code pages indexed before the safe-chunk fence, which remote and MCP search withhold. It rebuilds projections only: no page write, no new page version and no request ID. Vectors whose embedding input did not change are kept; the rest are embedded unless you pass --no-embed or no embedding model is configured. |
code_without_source_path: code pages with no recorded file to re-chunk. unsupported_page_kind: other page kinds, such as images. Their importer re-seals them. |
orphan-children |
child_table_orphans (also a storage_corrupt error) |
Explicit-only. Deletes rows of page child tables (chunks, versions, tags, takes, raw data, timeline, links) whose page row no longer exists, and clears dangling links.origin_page_id and files.page_id references, each in one statement that rechecks the orphan condition. See orphan children. |
torn_pages: page rows whose stored body cannot be read (torn TOAST). The preview names them; the repair never changes them. |
planner-stats |
planner_stats_stale |
Runs ANALYZE on the hot tables (pages, links, facts, takes, content_chunks, timeline_entries) whose planner statistics are stale, so search and graph reads stop planning as slow nested loops. PGLite also resets each table's pending row count; Postgres runs each ANALYZE with a 60 s statement timeout and a 2 s lock timeout. No journal admission, no user data changes, brain-wide. |
none |
contextual-mode |
contextual_retrieval_coverage (pages with no recorded mode) |
Stamps the contextual retrieval mode on markdown pages imported without one (for example by a large --no-embed sync, or by a connector source on an older gbrain), exactly as a fresh import of the page would: the page, source and brain settings decide, and the per-chunk synopsis tier lands at the free title tier. It rebuilds projections only: no page write, no new page version and no request ID. A page whose stored vectors already match the stamped convention keeps them and queues no re-embedding; a page whose embedding input changes has only those vectors cleared and is re-embedded once, unless you pass --no-embed. |
unsealed_projection: pages whose chunks lag their text; gbrain embed --stale or safe-chunks seals them first, and the next run stamps them. embed_skip: pages marked to skip embedding keep their stored vectors and are not stamped. |
file-drift |
maintenance_write_drift |
Explicit-only, preview-bound. Resolves pages whose canonical file differs from the database copy (source_changed / file_database_drift) through canonical reconciliation, preferring the file or the database copy within reconcile's protections. --all-drifted refuses mixed drift classes unless --class keeps one; --only/--skip narrow by canonical file path glob. Opt-in storage.keep_db lets the owner host's resident consumer resolve drift under declared prefixes with the database copy. A page whose file is gone from the last commit: --prefer database recreates the file, --prefer file soft-deletes the page (deleted canonical files). See file drift. |
Protected metadata, the tag union and protected takes or private fact rows, listed per page as exceptions; pages changed after the preview (changed_since_preview). |
ghost-pages |
ghost_pages |
Explicit-only, preview-bound, destructive consent. Soft-deletes live pages whose canonical file is missing on the owner host (ghost pages: every write refuses canonical_file_missing and no sync can import a file that is not there), through delete_page bound to the previewed owner, path and revision. --apply --expect <hash> --yes. See ghost pages. |
Declared db_only and never-filed derived pages (never listed); a page whose file came back before the apply (file_restored); pages changed after the preview (changed_since_preview). |
moved-pages |
ghost_pages |
Explicit-only, preview-bound, destructive consent. Folds a page left behind by a file that moved into the page the moved file imported as (GST-2584): when sync held the old page's deletion (file_gone), the new path imported as a fresh page. A page folds only on proof read from Git: its old path's last committed content is what one new path took at the move (or in that path's first commit), and the old page still holds it. Its links, relationship dates, timeline, raw data, files, user tags, aliases, facts and saved versions move to the moved page, its slug becomes an alias, its hold is cleared and it is soft-deleted (restorable for 72 h); no file is written. --apply --expect <hash> --yes. See moved pages. |
Every other page whose file is gone, listed held:<reason>: several_candidates, shared_survivor (another old page with the same content claims the same moved page), segmented_versions (the page or a saved version is stored in segments, over 1 MiB), access_differs (the two pages differ in readers, folder rules or privacy label), both_changed (edited in the database after the move), first_blob_differs, same_id_body_differs, evidence_conflicts, history_shallow, history_unknown, deletion_not_committed, not_moved. |
uncommitted-deletions |
uncommitted_sync_deletions |
Explicit-only, preview-bound, consent. Restores soft-deleted pages a managed sync removed before #7130 although Git never held their recorded file (.gitignore excludes it, or no commit holds it and it is not on the disk), one restore_page with detach each, published database-only: the page comes back live, forgets its recorded file, and no file is written. --apply --expect <hash> --yes. See uncommitted deletions. |
Pages another writer deleted (listed, restored only with --include-ambiguous); tombstones whose file Git once committed or that is on the disk again; paths Git could not answer for (unknown); purged pages (only a backup brings them back). |
rows-behind |
sync_rows_behind_checkpoint |
Explicit-only, preview-bound. Re-imports live pages of a managed source whose row holds an older version of its file than the sync checkpoint (sources.last_commit) says was imported, with no hold (#8071), from the file as committed at the checkpoint, through the managed file repair (no file is written). A file whose import is refused, or that is over the sync read bound, is held with that code instead. --source <id>, then --apply --expect <hash>. See rows behind the checkpoint. |
Rows with no import record (excluded:unproven, joined with --include-ambiguous; one whose older version equals its committed file, so the database moved since, never joins: excluded:database_moved, nor one whose page and file both moved: excluded:both_moved), rows with an uncommitted working-tree edit (excluded:worktree_differs), rows whose import would keep page data the file does not carry (excluded:import_overlay); rows that moved after the preview (changed_since_preview). |
receipt-compaction |
persistence_capacity (terminal bytes) |
Explicit-only, preview-bound, destructive consent. Compacts terminal write receipts now instead of on the idle maintenance tick (#6696): the intent and error message are dropped, the outcome, error code and detail stay, and the unused reservation returns to the receipt-bytes counters. --older-than <72h|30d> is floored at the configured retention unless --force; committed receipts only unless --include-failures. No admission, so it runs at a full cap. See receipt compaction. |
failures_kept: failed, conflict and cancelled receipts left without --include-failures. Receipts of a run whose sync cursor is still open, and the newest sync receipt of each worktree, are never listed. |
aliases |
dangling_aliases (orphaned rows) |
Explicit-only. Deletes free-text page aliases and slug redirects whose target page has no row at all (a page purged before purge removed its aliases, #6619, or a hard-deleted page), each target rechecked under its page lock; a coordinated maintenance write on a managed brain. A redirect from an old name of a page that still exists is never touched. See aliases. | soft_deleted_target: aliases of a soft-deleted page, kept for gbrain restore and removed when the page is purged. |
rename-identity |
rename_identity_downgrades |
Explicit-only, preview-bound, destructive consent. For an inexact Git rename that sync split into a delete plus an add (#6729): carries the old page's identity (id, version history, timeline, links, facts, aliases) onto the new slug, imports the new file onto it as an edit and retires the provisional page; or, with --close, settles the pair and moves nothing. --slug <new-slug> (and --from <old-slug>) names one pair; --apply --expect <hash> --yes. See rename identity. |
fact_rows_collide (a fence row of the old page the new file does not keep with the same claim); managed_remedy_unavailable (a carry on a managed source; --close is the remedy there); pages changed after the preview (changed_since_preview). |
overwritten-edits |
sync_overwritten_db_edits |
Explicit-only, preview-bound. Restores database edits that an incremental managed sync replaced with a committed file edit and no file_drift hold (#6712, fixed by #6887). It restores only what the records prove: a database-only revision (its receipt published no file) archived by a managed-sync import that wrote different content, with no later revision holding the edit again. The preview diffs the live page against the edit; --apply --expect <hash> reverts each page to that version through a revision-bound, database-only revert_version and holds the committed file file_drift when it differs. See overwritten edits. |
unknown_* findings (no persistence outcome on the writer's receipt, the import's content no longer readable, a segmented version), listed but not restored; pages that moved after the preview (changed_since_preview). |
provenance |
provenance_stamp_drift |
Explicit-only, preview-bound, destructive. Restores provenance stamps and lowering markers that remote writes removed before #7892, and stamps the stored tier as the marker on classified pages whose file would re-read higher (#7918). Only lowers; a lowered page files a lower_page proposal. See provenance. |
The owner's own edits (local), pages a later local write also changed (needs_review), pages whose file sync holds (held), unattributed writes without --include-ambiguous; pages that moved after the preview (preview_changed). |
missing-tables |
schema_missing_tables |
Explicit-only, preview-bound. Recreates, empty, a rebuildable cache table (query_cache, code_traversal_cache) that the applied migrations created but the brain no longer has, on a brain whose schema version already covers its creating migration, so apply-migrations never recreates it (#6911). DDL only (IF NOT EXISTS), no journal admission, brain-wide. See missing tables. |
user_data_tables: a missing table that holds user data; this repair never recreates it, so restore its rows from a backup first. other_tables: a missing table that holds no user data; gbrain init --migrate-only recreates it if the base schema defines it. |
url-clone-fences |
none (gbrain sync --source <id> stops at the pull with pull_blocked_local_changes) |
Explicit-only, preview-bound, destructive consent. Clears the ## Facts fence rows an older gbrain appended to files of a clone it owns (gbrain sources add --url), which block every git pull --ff-only that touches those files (#6946). The preview proves each changed file differs from HEAD only by appended fence rows; --apply --expect <hash> --yes backs each file up, keeps its rows database-only and restores the file from HEAD. Unmanaged brains only. See URL clone fences. |
non_fence_edit, unparsed_fence, staged_change, deleted, not_in_head, unreadable_checkout: a file with any other difference from HEAD, named with why; a file whose HEAD would not import as its page (visibility_noncanonical and the other import holds): apply keeps its rows database-only and restores the file so the clone can pull, but does not import HEAD and reports held; files that changed after the preview (changed_since_preview). |
segmented-mirror |
none (doctor does not read segmented files; run the preview once if the brain ran a version before v0.60.299.0) | Explicit-only, preview-bound, destructive consent. Rewrites the canonical file of a page stored in segments that an older binary's withdrawal mirror passed by (page_body_segmented), so the file still holds a row forget, forget_fact or purge_fact removed from the database. The file becomes the page's canonical render (gbrain export's bytes), written by the withdrawal mirror and committed by its Git effect. See segmented mirror. |
file_database_drift: the file also differs from the database for another reason; it is listed held and never rewritten. not_owner_host: the preview ran off the source's owner host and read none of its files. |
segmented-tiling |
segmented_tiling |
Explicit-only, preview-bound, trusted local CLI on the owner host. Republishes, from the file Git holds at HEAD, each live page stored in segments whose live generation's rows do not cover its body (every read of it refuses page_body_rows_unreadable and a managed sync holds its file). --source <id> (--slug <slug> narrows), then --apply --expect <hash>. See segmented tiling. |
Pages with no file, a file HEAD does not hold or one over pages.max_bytes, a file another sync hold withholds or one the next sync's import screen would hold (listed held); pages that changed after the preview (changed_since_preview). A source with no Git checkout, a repo-less brain included, refuses (not_a_git_repo) once it holds a damaged page; with none the preview lists nothing. |
secret-spans |
none (the operator names the pages) | Explicit-only, preview-bound, trusted local CLI. Replaces the credentials the secret scanner finds in the database copies of the named pages with <REDACTED:rule> markers and changes nothing else: title, frontmatter values (never keys), the body (inline or segmented), timeline, fact, take and link rows, raw data; chunks holding a value are rebuilt. Database only: no file write, no Git commit, and a sync hold stays. --source <id> --slug <slug>... [--rules <list>], then --apply --expect <hash>. See secret spans. |
clean (no match), refused (page_not_found, page_kind_unsupported, page_too_large, proof_failed, fact_value_unsupported, timeline_rows_collide); pages that moved after the preview (preview_changed, changed_since_preview). |
Timeline rows that an earlier version of a page produced and its current text
no longer has are removals, not history, so timeline neither counts nor
restores them. Doctor reports those as timeline_orphans; preview their
removal with gbrain extract timeline --prune-orphans --dry-run, then run it
without --dry-run.
A timeline repair can make pages gain marked bullets. That is the fix: the
history is now visible in the page and survives later edits. Deleting a marked
bullet in a save that passes the current expected_revision deletes its entry.
Connector checkpoints and the upgrade to v0.60.11.0
Managed Google and GitHub connector checkpoints are keyed on the parsed
connector settings minus credential-delivery fields, so the per-cycle
last_source_cycle_at stamp does not make a run start over. On an upgrade
across v0.60.11.0, the migration copies each connector source's newest
committed checkpoint to the current key. A source whose newest checkpoint receipt was
compacted re-walks its window once; unchanged pages are not admitted again.
Say to your agent: "Did my Gmail connector stop re-importing everything
every hour?" The agent runs gbrain sources status --json and reads the
connector block below.
gbrain sources status --json adds a connector object to each Google or
GitHub source:
"connector": {
"upgrade_recovery": "resumed",
"resumed_from": "2026-09-28 17:04:11.52+00",
"account_pinned": true,
"continuity_unverified": true,
"pending": 0,
"last_run": { "page_admissions": 0, "skipped_unchanged": 412, "pending": 0, "checkpoint_admissions": 1,
"stopped_on_wait_budget": false, "dropped_upstream": 0, "finished_at": "2026-09-29T21:00:03.114Z" }
}
upgrade_recovery:resumed(the migration copied a pre-upgrade checkpoint fromresumed_from),rewalking_once(until the first post-upgrade run finishes) ornone. Content selection sinceresumed_fromis unverified; if you changed a content setting since then, re-walk once withgbrain sync --source <id> --reset-checkpoint.account_pinned/continuity_unverified: the account the credential resolved to is pinned on the first run. A migrated source is pinned on its first post-upgrade run, so continuity before the upgrade is unverified. The account itself is never printed here.last_run: page admissions, unchanged pages skipped without an admission, writes still pending, checkpoint admissions, whether the 30-second wait budget stopped the run, and items dropped because they were deleted upstream. A quiet source showspage_admissions: 0; a provider whose cursor changes every run (Calendar sync token, Gmail history id) shows one checkpoint admission per run.
gbrain sync --source <id> --reset-checkpoint discards that connector
source's checkpoint, including Google backfill state, after resolving its
pending writes, and re-walks the configured window once. Existing pages stay,
unchanged ones take no admission, and the account pin is kept. It refuses on a
Git-backed source and while the account differs
(connector_account_changed).
Request-table indexes
A managed sync checkpoint checks that every page receipt of its run
committed. Two indexes serve that check, persistence_requests_sync_run_open
and persistence_requests_sync_run_committed, so it stays inside the
coordinator's 5-second statement timeout on a large persistence_requests
table. On Postgres, migration 179
builds them CONCURRENTLY after the upgrade; while it runs it prints
building <index> on ~N rows; this can take minutes; it is safe to leave running. If the check still times out, the checkpoint fails with
checkpoint_validation_timeout
and is not retried ahead of other writes.
Say to your agent: "My sync says checkpoint_validation_timeout. What do I run?"
gbrain doctor reports persistence_request_indexes: ok when every request-table
index is valid, a warning with progress while one is still building (leave it
running), and a warning naming gbrain repair request-indexes --apply when one
is missing or INVALID. After the rebuild, run the retry the refusal printed
(gbrain sync --source <source> --no-pull plus the saved
processing flags).
The same command builds persistence_requests_slug_intent (the page purge's
lookup), persistence_requests_foreground_committed, which every write claim
reads to find the newest foreground commit of a worktree (without it the
claims after a restart can overrun their claim phase on a large request table,
so the write queue grows and sync never commits), and
persistence_requests_request_id, which dream synthesis uses to
find each child's committed page, and (#8707) persistence_requests_replay_id
and persistence_requests_slug_sequence, which gbrain repair failed-writes
reads to find replay attempts and the later requests of a page. When that lookup, or a postprocess request
read, still hits the statement timeout, the synthesis pass is deferred rather
than failed: the phase warns postprocessing deferred, the pages stay
unstamped, and the next pass finishes them without another synthesis call. After
three deferred passes in a row the doctor check names the source, the read, how
long it ran and the pending outputs. It names the rebuild only when an index is
missing or INVALID; otherwise compare the elapsed time with
persistence_session_timeouts.
Say to your agent: "Dream keeps saying postprocessing deferred. What's wrong?"
Missing tables
The schema version records which migrations ran, not which tables still
exist. A table dropped after its migration ran stays missing:
gbrain apply-migrations sees nothing to do and gbrain db-repair checks the
connection, not the tables. How the #6911 brain lost its query_cache is not
known; a manual drop, a restore that skipped the table, or a pooler that
swallowed the DDL are possibilities. When that table is query_cache, every
coordinated page purge used to fail with 42P01, so the dream cycle's purge
phase failed every night with managed_purge_failed (#6911).
The page purge now skips a missing rebuildable cache (query_cache,
code_traversal_cache): there is nothing in it a rebuild cannot regenerate.
The purge receipt lists it under purge.missing_caches, and the store report
shows query_cache as not_present with reason table_missing. The fact
purge skips it the same way. A missing table that holds user data (facts,
takes, notices and the like) still fails the purge, because the purge cannot
honestly say it removed rows from it.
gbrain doctor reports schema_missing_tables. At head it checks every table
a fully migrated brain has on this engine; below head it checks the rebuildable
caches whose creating migration already ran, because a pending migration that
alters a missing cache fails with 42P01 and apply-migrations cannot finish.
A missing rebuildable cache warns with the repair below. A missing table that
holds user data fails. Any other missing table (locks, leases, operational
state) warns: gbrain init --migrate-only recreates the ones the base schema
defines.
Say to your agent: "Doctor says query_cache is missing. Fix it."
gbrain repair missing-tables # read-only: the tables it would recreate empty, and a hash
gbrain repair missing-tables --apply --expect <preview-hash>
The apply recreates each previewed cache table empty, in the shape a fully
migrated brain has, in one transaction per table, then checks it exists. Every
statement is IF NOT EXISTS and waits for locks only as long as a migration
does. A table that exists by the time the apply reaches it is left alone
(already_present). The approval is used once: the last table retires it, so
a later drop needs a fresh preview. The cache refills as searches run. If the
database role gbrain connects as may not create tables (an owner/app role
split), the apply refuses with schema_owner_required, creates nothing and
keeps the approval: run the same apply command connected as the role that owns
the schema. If the brain schema is newer than this gbrain client, upgrade
gbrain first; the repair refuses rather than build an older table shape.
Purges that failed on the missing cache before this fix may have been parked
after five failures. A park records the gbrain version that wrote it, and the
first purge run after an upgrade tries a park an older version wrote once more,
so these clear by themselves. One that fails again is parked under the new
version: doctor purge_parked_pages lists it; preview
gbrain pages purge-deleted --retry-parked --dry-run and run it without
--dry-run after the user agrees.
A missing table that holds user data is listed under user_data_tables; this
repair never recreates it, because an empty table would hide that its rows are
gone. Restore its rows from your own database backup (a pg_dump of the brain,
or your host's point-in-time recovery) before you run gbrain upgrade,
gbrain apply-migrations or gbrain init --migrate-only: those replay the base
schema, recreate a base-schema table empty and clear this check while the rows
stay lost. gbrain backup restore restores a whole brain into a new root, not
one table.
The repair runs only when named and never on upgrade, apply-migrations,
db-repair or the maintenance cycle.
Segmented mirror
Before v0.60.299.0, a withdrawal (forget, forget_fact or purge_fact) of
a row in a page stored in segments struck the row in the database, but the
withdrawal mirror and Git walk skipped the page (skipped reason
page_body_segmented). Its canonical file kept the withdrawn or purged row.
Current versions mirror such a page, but upgrading rewrites nothing, so a file
an older binary left behind keeps the row until this repair runs. Doctor does
not look for these files, because finding one means reading every segmented
page file in full. Run the preview once on each source's owner host if the
brain ever ran an older version with pages.segmented_storage on.
Say to your agent: "We forgot facts on big pages before upgrading. Make sure the files don't still have them."
gbrain repair segmented-mirror --source notes # read-only: each stale file, its hash and size, the render's, and a hash
gbrain repair segmented-mirror --source notes --apply --expect <preview-hash> --yes
The preview reads each live, file-backed segmented page of a source that has withdrawals. Files are hashed in pieces and never held whole. A page is listed when its file is an older render the repair can explain:
- the file passes the check the withdrawal mirror itself runs before it rewrites a file: with the withdrawals applied to its facts fences, the file matches the stored page; and
- applying the withdrawals changes the file, so it still holds a withdrawn or purged row.
Each listed page shows its path, the file's SHA-256 and size, and the SHA-256
and size of the page's canonical render: the bytes gbrain export writes for
it. A file that differs from the database for any other reason, such as a
local edit, is listed as held with file_database_drift and the
gbrain sources reconcile ... --preview command. It is never overwritten:
reconcile it, then preview again. A clean segmented file and an inline page are
never listed.
The apply re-checks every listed page first. If a page's revision or its file's
hash changed since the preview, the apply refuses with preview_changed and
writes nothing. Run the preview again and use the new hash. Each page then gets
one write request (operation: repair_segmented_mirror, its request id derived
from the hash). That request is the page's receipt; read it with
gbrain write-request <request id>. It commits a withdrawal-mirror effect and
a Git effect for the page, and the existing mirror does the rewrite. The mirror
keeps its recovery record, streamed staging file, owner and lock checks, and its
own file/database check. The effect carries the file and render SHA-256 the
preview approved: if the file or the render changed after the preview, even a
formatting-only edit made while the mirror waited, the mirror leaves the file
as it is (skipped reason preview_changed) and the Git effect commits
nothing for it. The Git effect commits the file. Outcomes are mirrored,
mirror_queued (the owner's consumer has not run it yet; preview again later),
held (the mirror's own check refused the file), refused with
preview_changed (its fix re-runs the preview; apply the new hash) or failed
(the mirror's error code). Replaying an apply with the same hash finds each
receipt and writes nothing (replayed), except that a page the mirror refused
reports refused again.
The rewrite replaces the file with the page's canonical render, so any other formatting differences in it are normalized as well. The old bytes stay in earlier Git commits; this repair does not rewrite history.
The repair runs only when named and never on upgrade, apply-migrations or the
maintenance cycle.
Segmented tiling
A page stored in segments is read from the manifest rows of its live
generation, and those rows must cover the page's recorded body size from
byte 0 with no gap. Before this release a write could publish a generation
without its rows: a fact purge's abort, or a sweep's expiry, collected the
write's staging (and deleted its staged rows) while the write prepared, and
the write's last preparation step moved the staging back to prepared. The
publish then passed its staging check, closed the page's old rows and
published none. Every read of such a page refuses page_body_rows_unreadable,
and a managed sync holds its file page_write_failed on every retry; that
hold reads needs_human with safe_actions: ["repair"], and its fix is this
repair's preview for the page (gbrain sync status --source <id> --code page_body_rows_unreadable --json lists it).
Current versions refuse both steps with body_staging_expired (send the write
again), but upgrading rewrites nothing, so a page damaged earlier stays
unreadable until this repair runs.
Doctor segmented_tiling lists such pages: source, slug, live generation,
how many rows it has, the bytes they cover (or that they leave a gap) and the
body size. It reads the manifest only and writes nothing. It skips archived
sources, runs as its own doctor entry, and its fix names the first damaged
source (--source) with the other sources' commands. A preview lists at most
1,000 pages; one that finds more reports truncated, so preview again after
the apply.
To republish them from Git, preview, then apply after the user agrees:
gbrain repair segmented-tiling --source default # preview: each page, its file, HEAD's blob and its sync hold, with a hash
gbrain repair segmented-tiling --source default --apply --expect <hash>
The preview runs only from the trusted local CLI, on the host that owns the
source's checkout, and writes nothing. For each page it lists the live
generation, the bytes its rows cover, the page's file, HEAD's commit, the
file's blob at HEAD (object id, SHA-256 and size) and the sync hold on it. A
page with no file, a file HEAD does not hold or a file over pages.max_bytes
is listed held and never written. So is a file that another sync hold
withholds (any hold but the page_write_failed one a sync opens when it
cannot read the stored body), and a file the next sync's import screen would
hold: purged page content, a write-gate reject, private visibility it would
not store, a fence it refuses. The apply keeps the stored frontmatter, so a
file that changes who can read the page is held too (visibility,
readable_by, a privacy alias such as access or confidentiality, or a
type that is private by default), as is one the next sync's content gate
would quarantine, flag or stop embedding when the stored page carries no
such marker. So is a file over 24 MiB, the most the import screen reads
whole. A source without a Git checkout, a repo-less brain included, previews
nothing while no page is damaged and refuses with not_a_git_repo once one
is: this repair republishes the copy Git holds, and there the database has no
other copy. On such a brain, rewrite the page from a copy you hold
(put_page).
The apply needs the preview's hash. It checks each page again (revision,
generation and blob) and refuses preview_changed when one moved. Then, per
page, in one transaction under the page's key lock (a coordinated maintenance
write on a managed brain), it versions the damaged generation by reference,
screens the blob again, publishes the body the screen's fence step and the
purge and withdrawal overlay admit (a claim the owner purged stays out even
when the file still carries it; a withdrawal committed after the preview
makes the page changed_since_preview) as a new generation through the same flip that
refuses a generation that does not cover its body, keeps the page's title,
type, frontmatter, tags and trust tier, clears the sync hold the preview saw
(a newer hold stays until the next sync re-imports the file),
records the new revision as imported from the HEAD blob when the file imports
to the stored title, type, frontmatter and tags (so the next sync holds no
file_drift for it), asks the next sync to screen the file again (so a file that differs from the
stored page in anything else imports normally) and writes the page's receipt
(op_checkpoints op segmented-tiling-receipt) and a segmented-tiling audit
line. A rerun with the same hash skips pages that already have a receipt.
The repair runs only when named, never from doctor, a remediation plan or an
upgrade.
Request-table growth
gbrain doctor reports persistence_request_growth: the number of rows in
persistence_requests (an estimate on Postgres), each writer's admission rate
over the last 7 days, its lifetime request IDs against
persistence.limits.*, and the date admission would refuse at that rate. It
warns when that date is less than 90 days away and prints the exact
gbrain config set persistence.limits.<limit> <value> line (sized for about
one more year, the same value persistence_capacity prints) and the check to
re-run. Request IDs are permanent, so raising the limit is the intervention;
nothing is evicted.
Receipt compaction
A brain whose receipt-bytes cap is close (doctor persistence_capacity, a
write_quota_exhausted refusal with reason terminal_bytes) gets bytes back
by compacting terminal receipts, which the resident consumer otherwise does
on idle ticks once a receipt is older than persistence.receipt_retention_days
(default 30). The repair runs the same per-receipt compaction on demand:
gbrain repair receipt-compaction --json # preview at the retention floor
gbrain repair receipt-compaction --apply --expect <hash> --yes
--older-than <72h|30d>sets the age; it may not be younger than the configured retention unless--force(a younger receipt is how a caller replays its request id in full). With retention 90 days,--older-than 30dis refused and the refusal's fix is the preview at90d.- Committed receipts only, unless
--include-failures(a failed receipt's error message is whatgbrain write-requestshows; the code and detail stay). - A receipt of a run whose managed-sync cursor is still open, and the newest committed sync receipt of each worktree, are never compacted: a resumed run finds what it committed through them.
- The preview binds an absolute cutoff and the newest request it saw; the apply
compacts only receipts of that set, each in its own short transaction
(counters locked first,
lock_timeout2 s,statement_timeout15 s), and a rerun of the same apply resumes after an interruption. - No admission and no receipt of its own, so it runs at a full cap and its preview charges nothing. Brain-wide.
Verify with gbrain doctor --only persistence_capacity --json: the
terminal_bytes row drops by the bytes the apply freed.
Drain queued text projections
After an upgrade that re-queues text projections (for example the 0.51
protocol activation, which also queued every image page), search and code
results stay incomplete until every queued page is sealed. That activation
(migration 153) keeps a Markdown or code page indexed at or after the
safe-chunk fence in search from its old index until its own rebuild, when the
page has no facts or takes fence, no private-key text and no quarantine marker
and has not changed since; every other queued page stays out of search until
it is sealed. Every queued row
falls in exactly one class, and doctor text_projection_readiness counts each
one (counts only, never page names):
| Class | What it is | What seals it |
|---|---|---|
pending |
Markdown and code pages (segmented pages included); failed counts those whose last rebuild failed |
the resident owner, or gbrain projections drain |
sealable |
image pages the importer already attested: written at or after the safe-chunk fence, one image chunk whose text is the page's own, revision unchanged since (sealable_with_visual have a visual vector) |
only gbrain projections drain: keyless, no provider call, no file read, no re-embedding |
reimport |
every other image page (pre-fence, several chunks, edited since); ocr_required counts the ones whose OCR once held protected content, which the importer seals only after a successful fresh OCR pass (GBRAIN_EMBEDDING_IMAGE_OCR=true) |
the importer: gbrain embed --stale --images (paid: OCR and one multimodal embedding per image) |
protected |
image pages whose text holds a protected fence | nothing: unsealed and out of search by design |
archived |
pages of an archived source | restoring the source |
Doctor warns while pending, sealable or reimport is above 0, and its fix
asks the user before a drain that seals images (gbrain projections drain --limit <n>, <n> sized to finish well inside an agent's tool limit) or
before the paid importer sweep. With only protected and archived rows left
it reports ok (info), and search marks its results projection_by_design
instead of projection_pending.
The resident owner (gbrain serve or autopilot) drains pending rows on
its own: each pass rebuilds up to 100 pages and starts no new page after
250 ms, and takes 2 pages while writes are waiting. A page whose rebuild fails
is retried after 30 seconds. Each pass reads at most 500 queue rows: the 100
newest (so a fresh edit behind a large image queue is reached at once) and 400
from a cursor that walks the queue in key order and wraps, so every row is
reached within one lap. The resident never seals images.
Pages stored in segments are drained first, one build each; a page another gbrain process is building (its claim renewed within the last 60 seconds) is left to that process. This is how a brain with no resident (CLI only, or driven by cron) makes a large new page searchable after its post-commit build died.
To drain now:
gbrain projections drain # until every page queued at the start was tried once
gbrain projections drain --limit 5000
gbrain projections drain --json # {rebuilt, superseded, failed: [{source_id, slug, reason}], remaining, limited, sealed, sealed_with_visual, sealed_text_only, statistics_refreshed, remaining_by_class}
gbrain projections drain --dry-run # change nothing: every class count and the rows a drain takes, oldest first
--dry-run is the preview: it reads the queue only, prints every class count
and the rows a drain with the same --limit (default 50) would take, oldest
first, each with its queue reason (rebuild_failed for a row whose last
rebuild failed); --json gives the class counts and rows. The drain
rebuilds the pending rows search does not answer for first, then seals the
sealable images, then rebuilds the pending rows search still answers for from
the index they had before an upgrade (#9192). On Postgres it rebuilds 4 pages at
once, each on its own pooled connection; --concurrency raises that to the pool
size less 2, and a refused or dropped connection lowers it without stopping the
drain. PGLite and the resident owner rebuild one page at a time. Sealing an
image in place rechecks each page's class under its page lock, writes no chunk and leaves
the visual vector as it is, so image search ranks the page again at once. A
sealed_text_only page (imported with --no-embed) gets its visual vector
from gbrain embed --stale --images. reimport, protected and archived
rows stay queued; the summary lists them with their next step and never says
the backlog is empty while any remain. After a drain that sealed images, the
planner statistics of the projection columns are refreshed
(statistics_refreshed).
An automatic embed-backfill that keeps failing the same way. A page whose
projection cannot be rebuilt (rebuild_failed) leaves its chunks
unembeddable, so every automatic embed-backfill for that source ends
incomplete; N chunks remain and M projections are blocked with nothing
embedded. After the first such failure the next automatic submission waits
twice the cooldown (20, then 40 minutes); after three identical failures
automatic submission stops for that source, and a retry inside one job that
finds the same blockers dead-letters instead of running again. Doctor
embed_backfill_stalled names the blocked pages, their page kind and queue
reason. Preview with gbrain projections drain --dry-run, then run
gbrain projections drain: it retries each queued Markdown or code page in the
foreground and prints why a page still fails and its next step, and seals the
sealable image pages. Other image pages are rebuilt only by their importer
(gbrain embed --stale --images --dry-run --source <id> previews them, then
the paid run; gbrain sync --full --source <id> also works). Embedding
recovery never queues or re-stamps image rows, so an image row keeps its queue
reason. Automatic backfill resumes by
itself once the blocked pages or the stale chunks change, or a run embeds
anything; gbrain embed --stale --source <id> and
gbrain jobs submit embed-backfill are never held back.
| Exit | Meaning |
|---|---|
| 0 | Nothing tried failed. "The projection backlog is empty." appears only when remaining is 0. |
| 1 | Some pages failed. Each prints failed: <source>/<slug>: <reason> and a next: action; the pages stay queued. |
| 2 | Did not run: bad usage (invalid_params), or projection_owner_resident. |
On Postgres the drain is safe while gbrain serve runs: each page is rebuilt
under its page lock with a revision recheck, so a page is rebuilt once whichever
process gets there first. On PGLite a resident process holds the datastore, so
the drain refuses before opening it (also for a mounted PGLite brain selected
with --brain).
A queue row that no longer matches its live page (a legacy or hand-edited
row, or a page recreated under a new source incarnation) is healed under the
page lock instead of being counted again: a stale-revision row is re-keyed to
the page's current revision and rebuilt in the same pass, a row for a page
that is already projected or for a dead incarnation is deleted (superseded
in the summary), and only the exact row the drain listed is touched, so a
newer row the page trigger queued meanwhile survives. A page whose content
changes while it is being rebuilt is listed once under failed with a
revision_conflict: reason, stays queued at its new revision, and is
rebuilt on the next run. The drain continues while a pass rebuilt, removed,
failed or deferred a row and stops on a pass that did nothing.
Verify: gbrain doctor --only text_projection_readiness --json shows
pending, sealable and reimport at 0 (status ok).
Provider key source
An exported provider key (for example OPENAI_API_KEY) wins over the matching
config key (openai_api_key in ~/.gbrain/config.json). When both are
set and differ, every gbrain command except gbrain hook prints one warning
per process naming the variable, the config key and which one is in effect.
No key or part of one is ever printed.
- To use the config key: remove the variable from the environment of the
process that printed the warning (shell profile,
~/.gbrain/.env, or for a daemon its service definition) and restart that process. - If the environment key is intended:
gbrain config unset openai_api_key(or the matching key), which also stops the warning.
Doctor embedding_key_source reports the same plus where the embedding key in
effect comes from. It sees only the environment gbrain doctor runs in: a
daemon has its own and reports a mismatch in its log, with the startup warning
or embedding_auth_failed on the first rejected embedding
(write refusals). After fixing a
rejected key, gbrain embed --stale embeds what was saved meanwhile.
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:
- Read the page with the user:
gbrain get --source <id> -- <slug>. - For each fact they say a sender wrote, withdraw it after they agree:
gbrain forget <fact-id> --source <id>. - 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."
Connector held items
The doctor check connector_held_items counts Google and GitHub items held
after three consecutive failed syncs. It is not a repair kind: fix the cause
the item's error code names, then re-attempt. See
held items for the rules.
Who acts and Consent follow the troubleshooting legend: Preview and Verify are read-only; run Apply only once the named actor has it and the user agreed to the listed effects.
| Symptom | Preview | Apply | Verify | Who acts | Consent |
|---|---|---|---|---|---|
connector_held_items warns, or gbrain waiting says coverage is partial |
gbrain sources status <source> |
gbrain sources retry-held <source>, then gbrain sync --source <source> |
gbrain sources status <source> (a recovered item leaves the list) |
agent, after the user agrees | egress (fetches from the provider again) |
A sync fails with connector_holds_exhausted |
gbrain sources status <source> --json |
Fix the cause, then gbrain sources retry-held <source> and gbrain sync --source <source> |
gbrain doctor |
agent, after the user agrees | egress |
A sync refuses with connector_fence_below_timeline |
gbrain repair connector-fences --source <source> |
gbrain repair connector-fences --source <source> --apply, then gbrain sources retry-held <source> |
gbrain sync --source <source> succeeds |
brain host, after the user agrees | egress |
Take supersession
Say to your agent: "My superseded takes don't point at the take that replaced them. Repair the supersession chains."
Takes superseded before the pointer moved onto the old fence row have
superseded_by empty: the old row was struck without a pointer, and the new
row often cites itself (superseded by #<its own row>). Preview, then apply
after you agree:
gbrain repair take-supersession # per page: each link, its evidence, ambiguous pages
gbrain repair take-supersession --json # details.pages[] and details.ambiguous[]
gbrain repair take-supersession --apply # writes the pointers; a second apply changes nothing
The repair links a struck row to its replacement only from evidence, in this
order: a committed takes_supersede receipt for the page, a stored
superseded_by, then a self-pointer row that has exactly one struck, unlinked
row above it (resolved hop by hop, so a chain of supersessions resolves). It
never guesses. When a new row has two or more possible predecessors, the page
is listed under ambiguous with the candidates and left unchanged. Fix it by
hand: read the page (gbrain get --source <source> -- <slug>), append
; superseded by #<new row> to the source cell of the row each new row
replaced, save it with the current expected_revision, then run the repair
again; it drops the leftover self-pointers and stores the pointers.
Accepted takes
Say to your agent: "I accepted held take changes on v0.60.253.0. Check whether any take was removed and restore it."
On v0.60.253.0, accepting a held change to a take you had confirmed
(gbrain trust confirm tp<id>, or gbrain trust review --accept-all) removed
the take when the change kept its claim: an agent struck it through
(~~claim~~) or changed its kind or holder. The take left the page's takes
fence and the takes index; the accept should have applied the change instead.
A later sync or publish cannot bring it back, because the page no longer
carries the row. A take with a grade in its fence was safe: the removal
refused it.
Preview, then apply after you agree:
gbrain repair accepted-takes # each removed take, its proposal and the page version it comes from
gbrain repair accepted-takes --json # listing[] and residuals
gbrain repair accepted-takes --apply --expect <preview-hash>
A take is listed only when every record agrees: the accepted proposal (a strike
or same-claim change, filed by a page publish or reconcile), the committed
takes_remove receipt bound to it, the page version that removal archived
(whose fence holds the row at that number) and the reservation row the removal
left in the live fence. The apply puts that fence row back in place of the
reservation through a revision-bound put_page, at the tier of the write you
accepted, which is what a correct accept leaves. Not restored, because no
record holds it: a grade or resolution stored only in the database, the take's
id (the row gets a new one) and its embedding (re-embedded). A second preview
lists nothing.
Overwritten database edits
Say to your agent: "Check whether sync overwrote any of my database edits and show me what it would restore."
Before #6887, an ordinary incremental gbrain sync on a managed
brain could publish a committed file edit over a page that was also edited in
the database since its last import (for example a put_page with
sync.write_through off). It wrote no file_drift hold and no backup. The database edit is still in
the page's history: the import archived it as a page version. Doctor
sync_overwritten_db_edits counts the pages per source and names the first ones.
Preview, show the user both versions, then apply after they agree:
gbrain repair overwritten-edits --source <id> # each page, the edit's version, who wrote it, the import that replaced it, a diff
gbrain repair overwritten-edits --source <id> --slug notes/a # one page
gbrain repair overwritten-edits --source <id> --apply --expect <preview-hash>
A page is listed only when the records prove it: the archived revision's writer
is a committed request whose receipt published no file (persistence.mode
database, no Git effect for that revision, not a read-only mirror write), the
request that archived it is a managed-sync import (also after receipt
compaction, from its operation and outcome), the import wrote different content,
and no later revision of the page holds the edit again. Findings the records
cannot prove are listed unknown with the reason and never restored: the
writer's receipt has no persistence outcome, the import's own content is no
longer readable, or a version is segmented. A revision with no recorded writer
(written before write attribution, by a classic sync, or by unattributed
maintenance) is not reported, because it looks exactly like ordinary sync
history.
The apply reverts each page to the archived version through revert_version,
bound to the page revision the preview saw, so a page that moved since is
changed_since_preview and nothing is written. An apply interrupted after a
restore committed replays that restore's request on the next run and then
writes the hold, instead of reporting the page as moved. The restore
publishes to the database only and never rewrites the committed file.
Only the host that owns the source's checkout compares that file with the
restored page. There, a file that differs is held file_drift (outcome
restored_file_held), so no later sync publishes it over the edit; pick the
winner with gbrain repair file-drift. On any other host the
restore still applies, but the file is neither compared nor held: the outcome
is restored_file_unheld (why=checkout_not_on_this_host; the same outcome
with why=file_over_read_bound means the owner host could not read a file
that large). A later sync that imports a change to that file can then publish
it over the restored edit again. No command writes only the hold afterward,
and the restored page is not listed again, so run the apply on the owner host.
After a restore on another host, resolve the page on the owner host so the
file holds the restored edit:
gbrain repair file-drift --source <id> --slug <slug> --prefer database # preview
gbrain repair file-drift --source <id> --slug <slug> --prefer database --apply --expect <preview-hash> --yes # after the user agrees
A restored page is not listed again.
Provenance stamps and trust markers
Say to your agent: "Check whether any page lost the record of where it came from and show me what the repair would change."
Before #7892, a remote write could change or drop a page's provenance stamps
(source_kind, ingested_via, ingested_at) or its lowering trust_tier
marker. The page then reads as more trusted than its origin allows the next time
its file is re-read (a rebuild, a backfill). Separately (#7918), a classified
page below the owner tiers whose file carries no marker, or a higher one, would
re-read above its stored tier. Doctor provenance_stamp_drift counts both per
source from page history and write receipts, split by who made the write
(remote, local, unattributed), and names the first pages. It writes nothing.
Preview, show the user the list, then apply after they agree:
gbrain repair provenance --source <id> # each page: stamps, marker and tier before -> after, and who wrote the change
gbrain repair provenance --source <id> --slug inbox/a # one page
gbrain repair provenance --source <id> --include-ambiguous # also writes with no recorded writer
gbrain repair provenance --source <id> --apply --expect <preview-hash> --yes
Each listed page has a class:
remote: a remote write made the change. The apply restores each stamp to the server-writtenpagescolumn when it has one, else to the value just before the first remote change, stamps the lowest cap the page had as its marker, and lowers the page to it.ambiguous: no recorded writer (written before write attribution). Planned only with--include-ambiguous, which changes the hash.restamp: the classified page from #7918. The apply stamps its stored tier as the marker; the row keeps its tier.local,needs_reviewandheld: the owner's own edit, a page a later local write also changed, or a page whose file sync holds (the hold's code and fix are in the detail; the apply skips a page held after its preview). Listed, never written; edit those pages by hand, or resolve the hold and preview again.
Every change only lowers: no stamp, marker or tier is ever raised. A lowered
page gets a lower_page proposal (proposer provenance_repair) that
gbrain trust review confirms or reverts, and rows derived from the page
follow it down. The apply writes one owner page write per page, bound to the
previewed revision and change, so a page that moved since is preview_changed
and nothing is written. On a managed brain the write publishes the file through
the coordinator (Git stays the parent); on a classic checkout it renders the
repaired page to its file in the same transaction, and a page whose file holds
an edit the database lacks (run gbrain sync first) or whose checkout cannot
be written is listed needs_review instead; on a repo-less brain the database
is the record. It runs only from the local CLI on the brain host, and
never from --all, the remediation plan or an upgrade. A second preview lists
nothing.
Orphan persistence bindings
Say to your agent: "I removed a source and added it back, and now sync says it needs a coordinator. Fix it."
Removing a source also removes that source's persistence binding, and the
claim check counts only a binding of the source's current incarnation. A
binding left behind by an older gbrain is reported by doctor's
orphan_persistence_bindings check. Preview, then apply after you agree:
gbrain repair orphan-bindings # lists each binding and why it is orphaned
gbrain repair orphan-bindings --apply # deletes them
gbrain doctor # orphan_persistence_bindings is ok
Do not delete binding rows by hand: the repair rechecks, in the same statement, that the binding is still orphaned and that no pending write request uses it.
Parked Git effects of a former binding
Say to your agent: "writer status still shows a parked Git group, the exact retry says the canonical binding changed, and the bulk retry previews zero requests."
A Git effect records the canonical worktree binding it was queued under. After
the source moves to another worktree (set-path, a transfer, a re-claim) or is
re-created, the binding guard refuses that effect source_changed on every
retry, and the bulk retries (--parked-code, --parked-pushes) select only
the current binding's effects. A zero there is a different selection, not a
clearance, and a healthy current binding or native-lock probe says nothing
about the old effect. The guard stays: never claim or transfer the source,
re-create it, or edit journal rows to force the effect through.
How it shows up: writer status and doctor parked_effects list the effect in
its own parked group with former_binding (reason, the recorded
worktree_ids, the current_worktree_id, up to five requests), and the
group's command is the settle preview; doctor's per-effect command is
settle-effects --request-id <id> --dry-run; the exact
retry-effects --request-id <id> --dry-run refusal names both bindings and
has that preview as its fix; the bulk retry names the effects it leaves out
under former_worktree.
Disposition, with the user:
reason: binding_changed(same source, new worktree): previewgbrain sources writer settle-effects <source> --request-id <id> --dry-run. It settles the effect only on proof that the current worktree committed and pushed the page's current bytes and the fetched remote branch holds them (settle-effects). Each refusal names the missing piece:no_covering_receiptmeans no later write of the page went through the current binding, so write the page through gbrain (its Git effect commits and pushes it);bytes_unpushedwaits for that push;remote_ref_missingorremote_ref_staleneeds a fetch in the checkout. Preview again, show the user the proof, and run the printedapply_commandonly after they agree. The settlement keeps the failure, request and bytes, and--unsettlereverses it.- The page has since moved on (a later write committed a new revision), was
deleted, or another page took its slug: nothing current owes the old
bytes, so add
--retireto the preview. Each target is listed with its evidence (moved,deleted,replacedorabsent, with the owed and current revision). A page still at the owed revision is refusedpage_not_moved: write it through gbrain first. An effect of the current binding is refusednot_former_binding. reason: source_replaced(the source was archived, removed or re-created after the effect): it owes nothing to the current source, so retry never runs it and plain settle refusessource_replaced. Previewsettle-effects <source> --request-id <id> --retire --dry-run(the group's command); the source being replaced is the evidence.
A retirement is a settlement with proof former_binding_retired: preview
first, bound to the plan hash (a settle plan never applies as a retirement),
asked of the user (actor: user), recorded in data.settled and
data.settlements, never requeued or replayed against the current binding,
idempotent (a second preview lists nothing) and reversed by --unsettle. The
exact retry keeps refusing the effect source_changed.
These do not apply to it: gbrain repair stuck-recovery resolves recovery
records blocked on unexpected file bytes, and a parked Git effect without a
recovery record gives it nothing to resolve; cancelling the request returns a
committed request unchanged; receipt
compaction skips requests with uncommitted effects. A write-request read that
returns not_found under another writer identity is a visibility limit, not
proof the request is gone: writer status and the settle preview read the
journal of the source.
Managed sync orphans
Say to your agent: "doctor has reported the same two sync failures for a week, every sync ends up to date, and rerunning the sync changes nothing."
A managed sync run keeps its cursor under a key derived from the source
incarnation, the writer principal and the sync options. A cursor written under
an older key, by a writer identity that no longer exists (a legacy_token
principal before the local-CLI cutover, a revoked local writer), can never be
resumed: the live writer reads only its own key. Doctor still reads every
unfinished cursor, so sync_failures reports sync_incomplete forever, and a
managed-sync-failure row whose key has no cursor at all is only cleared by a
success under that same key, which never comes. A plain sync follows the
live cursor; --skip-failed is refused on a managed source. Nothing an
operator can run clears either.
gbrain repair managed-sync-orphans is the sanctioned exit. It is
explicit-only and preview-bound: the preview classifies every candidate and
prints a hash, and the apply retires exactly that set.
gbrain repair managed-sync-orphans --source default # preview: lists each orphan with its class
gbrain repair managed-sync-orphans --source default --apply --expect <hash>
gbrain doctor --only sync_failures # the orphaned rows are gone
Classes in the preview:
| Class | What it is | Why nothing current can clear it |
|---|---|---|
no_cursor |
a managed-sync-failure row with no managed-sync cursor under its key |
cleared only by a success under the same key |
principal_unadoptable |
an unfinished cursor recorded by a principal that is not an active local writer | the live writer never reads that key, and the pending request is invisible to it |
superseded |
an unfinished cursor from before sync options were recorded, with a later completed run for the same source and incarnation | its exact options are unknown, so no command resumes it |
incarnation_retired |
an unfinished cursor, or a failure row, recorded under a source incarnation the source no longer has (it was re-pointed at a new checkout, or removed and added again) | the cursor key digests the incarnation, so no current sync selects it, and every incarnation-joined reader (doctor's durable read, the sync retry, --acknowledge-managed) drops it; only the local ledger mirror still shows it. gbrain sync status reports it as cursor: null with last_error.code: cursor_incarnation_retired |
checkpoint_moved |
an unfinished cursor whose pages all committed and whose checkpoint was refused revision_conflict "The source checkpoint changed during this sync." because sources.last_commit moved to a commit that is neither the run's start nor its target (another run, or an older gbrain sharing the database, checkpointed the source elsewhere) |
the checkpoint's compare-and-swap can never succeed, so every plain sync resumes the cursor into the same refusal; its slug __managed_sync_checkpoint__ is bookkeeping, not a page, so there is nothing to read. After the apply the next sync discovers from the commit the source records. No sync retries it, because rediscovering a path-sliced run would move last_commit backward; the orphan repair is the only exit. A cursor whose source already stands at its target is not listed: the next plain sync finishes it. The apply keeps the cursor when the rule no longer holds |
slug_mode_refused |
an unfinished cursor whose checkpoint was refused slug_root_mode_mismatch (a source in a subdirectory of its repository pins one slug_root_mode, the run used the other) while the source keeps the other pin |
the two modes give different slugs, so the checkpoint can never publish under the kept pin. Preview, then --apply --expect <hash>: the apply retires the cursor and the next sync discovers the source again under the kept pin. Setting the pin back to the run's mode instead lets the next plain sync retry the checkpoint by itself. No sync retries this one without a person's choice |
mirror_only |
a row of the local ledger (~/.gbrain/sync-failures.jsonl) carrying a managed_cursor_key with no durable failure row under that key in any incarnation |
the mirror is pruned only after a durable delete, so one whose durable row is already gone keeps gbrain doctor --fast warning. The apply removes the ledger row after reading the durable rows again; a successful sync of the source prunes its own mirror-only rows too |
Kept and counted, never retired: a cursor whose pending request is still
queued, running or recovering (pending_request_live), and a cursor the live
writer can still resume with its recorded options (resumable; doctor prints
the exact gbrain sync ... command). An incarnation_retired
cursor is retired even when its recording principal is the live local writer
with recorded options: that veto is for a cursor the writer could still
resume, which no retired key can be. Rows on an archived source are never
listed, and an apply that finds the source archived meanwhile keeps them.
Retiring an old incarnation's bookkeeping says nothing about whether the
current source's files are imported; gbrain sync status --source <id> --json
does. Without a database connection, gbrain doctor --fast reports the mirror
rows it cannot verify as warn ("could not be verified"), never fail: a
better fast score there is less certainty, not recovery; gbrain doctor --only sync_failures with the brain reachable is the authoritative check.
The apply rechecks every
predicate in the deleting statement and removes the cursor, its same-key
failure row and its manifest (when no other cursor shares the run) in one
transaction, so a cursor the writer picked up meanwhile is left alone. Do not
delete op_checkpoints rows by hand.
Content receipt root
Say to your agent: "after moving the brain's content directory to another machine, doctor fails sync_freshness and the sync it suggests refuses with sync_not_applicable."
A gbrain-owned content directory (created by gbrain init or the 0.53.0
shared-skills migration) never syncs from Git; doctor exempts it because its
content receipt (config shared_skills.content.v1.<source>.<incarnation>)
names the source's root and that root's device and inode. A writer transfer
accept and gbrain sources set-path rebind the receipt of every moved source
(nested sources by their relative path) in their own transaction, and report it
as content_receipts. A receipt an older release left on the old root makes
doctor report content_receipt_stale with this repair as its fix. The repair
also lists an unfinished setup checkpoint that names another root: after a host
move, the 0.53.0 migration refuses The canonical root changed after setup began with this repair as its fix (#7900). The repair lists only sources claimed
under activated writer persistence, so for a moved source that is not, the
refusal names the gbrain sources writer claim and activate previews to run
first (#7915). Follow the class it prints, then run
gbrain apply-migrations --force-retry 0.53.0.
gbrain repair content-receipt-root --source default # preview, on the owner host
gbrain repair content-receipt-root --source default --apply --expect <hash>
gbrain doctor --only sync_freshness # the source is writer-owned again
Classes in the preview:
| Class | What it means | Next |
|---|---|---|
rebind |
The owner binding's root is the source's local_path and the owner's tree hashes to the worktree manifest the last transfer or rebind verified. |
The apply rewrites the receipt's root and root_identity. |
source_path_mismatch |
The source's local_path still names the old root (a transfer was accepted, set-path not yet run). |
gbrain sources set-path <source> <owner root>, which also rebinds the receipt. |
tree_mismatch |
The owner's tree no longer hashes to the recorded manifest (pages were written since, or a claim on a new host recorded none), so it is not proven to be the transferred content; the detail prints both digests. | A self-transfer on the owner host (gbrain sources writer transfer prepare <source> --self-transfer ..., then the accept it prints) re-verifies the tree and rebinds the receipt. With shared skills on, the fix then repeats gbrain sources writer activate --confirm-quiesced --shared-skills for the new owner epoch. |
not_owner_host, root_missing |
This host does not own the checkout, or the owner's root cannot be read. | gbrain sources writer status --source <source> --json. |
The apply recomputes the preview and refuses preview_changed unless it is
unchanged, skips a receipt that changed since the preview, and keeps the
previous value under <receipt key>.backup (gbrain config get <key>.backup
prints it; restoring is gbrain config set <key> '<previous>'). Do not edit
the receipt by hand.
Stuck recovery
Say to your agent: "Every write to my notes source has been pending for an hour and writer status says a request is recovering with unexpected_file_bytes. Show me what changed and let me pick which version to keep."
The same applies to a shared-skill bundle publication (several skill files
published together) and to a withdrawal-mirror effect (gbrain rewriting a page
file after forget) whose file was edited while it was being written.
A page write records its file's prior bytes before it publishes. If the
process dies mid-publication, the owner's recovery pass restores the prior
bytes or finishes the write. When the file matches neither the recorded prior
nor the published bytes (usually a hand edit made while the write was
publishing), recovery refuses to overwrite it: the request stays recovering
with unexpected_file_bytes, no write on that worktree is claimed, and the
resident writer re-checks it every 30 seconds without progress. A sync queued
behind it stops at once with
drain_stalled, cause: head_blocked,
naming the file and this command. Do not delete the file to unblock it.
gbrain repair stuck-recovery is the sanctioned exit. Run it on the host that
owns the source.
gbrain repair stuck-recovery --source notes # preview: each blocked file, its diff, the choices
gbrain repair stuck-recovery --source notes --request-id <uuid> # only one request
gbrain repair stuck-recovery --source notes --keep prior --apply --expect <hash> --yes
gbrain repair stuck-recovery --source notes --keep disk --apply --expect <hash> --yes
gbrain repair stuck-recovery --source notes --request-id <uuid> --keep withdrawn --apply --expect <hash> --yes # a withdrawal-mirror effect
The preview starts from the blocker of the source's queued head and lists
every recovery record on the worktree, and every withdrawal-mirror effect
recovery whose file matches neither recorded version. For each file it prints the prior
(hash, size, mode, or absent: prior was a create), the bytes on disk (or
deleted on disk), what recovery sees, and a private diff written under
~/.gbrain/backups/stuck-recovery/<request>/ with the exact diff -u
command that reproduces it. It prints only the choices available for every
listed record. The hash binds each record's identity, each file's disk bytes
and the page's database revision, so an edit or a page write after the
preview refuses the apply with preview_changed.
A file over the 24 MiB single-string ceiling (normal with segmented page
storage, up to pages.max_bytes) resolves the same way, in bounded memory.
Its write kept the prior file as a hidden staged copy beside it
(.<sha256>.tmp.before-<uuid>) instead of inside the recovery record. The
preview hashes the file and that copy in pieces and prints the copy's state
after the prior fingerprint: staged copy verified, missing or does not match its recorded SHA-256. Both versions are backed up by copy, each
checked against its fingerprint, and the diff file is a summary instead of a
full diff (both hashes and sizes, the first byte where they differ, and a
window of at most 1 KiB around it), marked (summary: ...) in the preview;
its reproduce line is a cmp of the two backups. --keep prior renames
the verified staged copy back over the file, as the writer's own recovery
does, and the write publishes again. A missing or damaged staged copy can't
restore the prior, so the preview offers only --keep disk, and --keep prior refuses with
recovery_prior_stage_unavailable.
--keep disk keeps a damaged copy in the backup directory (0.prior-stage)
and removes it from the checkout.
The choice is the user's: there is no default --keep, the kind never runs
from --all, gbrain doctor --remediate or a remediation step, and a
non-interactive apply without --yes exits 3 with the consent payload and
changes nothing. The backups never authorize an apply by themselves.
What a choice does depends on the request's state:
| Request state | --keep prior |
--keep disk (#6640's drop) |
|---|---|---|
Live (recovering), no recorded failure: the publication was interrupted and its database transaction never committed |
Backs up both versions, writes the recorded prior bytes back through the writer's own durable, confined publication (staged at the record's reserved restoration path; an absent prior unlinks the file); recovery then requeues the request and the accepted write publishes again on the next pass. | Backs up both versions and ends the request conflict with source_changed instead of requeueing a write that would conflict again; recovery then only cleans its staging and clears the record, releasing the recovery bytes it reserved. The record itself is never rewritten. |
Live with a recorded failure (publication_failed) |
Prior bytes back; the request ends failed or conflict with that failure. |
Disk bytes kept; the request ends with that failure. |
Terminal (committed, failed, conflict, cancelled) with its recovery record still set |
Refused (recovery_choice_refused): recovery never restores a terminal request's file, so this would roll back committed bytes. |
Refused (recovery_choice_refused): a terminal outcome is immutable and there is no publication to abandon. |
A shared-skill bundle record is listed with every file of the bundle, each
with both fingerprints, and either choice applies to the whole bundle: every
file is backed up first, then --keep prior writes the prior bytes of the
edited files back and recovery restores the rest (the publication requeues, or
ends with its recorded failure), and --keep disk keeps every file as it is on
disk and abandons the publication. After --keep disk the shared-skill records
keep the version from before the publication; publish the skill again if the
files on disk should become its new version.
A withdrawal-mirror effect has one choice, --keep withdrawn. The withdrawal
is already committed, so keeping the edited file (or the bytes from before the
withdrawal) would leave the forgotten fact on disk, and the next sync would
import it again; --keep disk and --keep prior are refused
(recovery_choice_refused) before anything runs. The preview lists the file,
its bytes from before the withdrawal, the withdrawn bytes the mirror recorded
and the bytes on disk, with a diff of the withdrawn and disk bytes. The apply
backs the edited file up (0.disk beside 0.withdrawn and the diff), writes
the withdrawn bytes through the mirror's own staged publication, and finishes
the effect forward, so the writes queued behind it resume. Commit the file
before the next sync, and make any other change from the edit again from the
backup, leaving the forgotten fact out. A record without usable withdrawn
bytes is listed as refused (recovery_effect_unsupported).
The preview lists a terminal request as refused with the reason and offers
no choice for it. After --keep disk the database page still holds the
content from before the write, so the page shows as file/database drift until
you reconcile it: gbrain sources reconcile <source> <slug> --brain host --preview. On a git-canonical (strict) source Git is the parent, so the kept
bytes are an uncommitted edit instead: publish it with
gbrain git commit-push --path <checkout> -m "<message>" -- <path>, or discard
it with git -C <checkout> restore -- <path>, then run
gbrain sync --source <source> --no-pull; git status --porcelain -- <path>
and gbrain sync status --source <source> --json verify it. The item's fix
asks the user which (#7715). The command never reports the page as repaired.
The apply runs under the worktree lock, so the resident recovery pass cannot
interleave. Each step is journaled (op_checkpoints, op
stuck-recovery-resolution): a run killed at any point resumes with the same
command, and a resident writer of any version can finish a resolution this
command started, because the recovery rule it uses is unchanged. Running the
same apply again after it finished replays the recorded result; the same hash
with the other --keep refuses idempotency_conflict. The finished journal
row is the resolution's audit entry and does not expire; the request's own
receipt is never rewritten by this command (--keep disk completes the live
request; it never changes a terminal one). A bundle record this binary cannot
read is listed as refused with
recovery_bundle_unsupported, and an effect
record without usable withdrawn bytes with
recovery_effect_unsupported. A record of
either kind that a newer gbrain wrote is listed as refused with
recovery_version_unsupported
and the gbrain upgrade fix. The apply waits
at most 10 seconds for the worktree lock, then refuses writer_lock_unavailable
with nothing changed; --keep prior on a record that predates reserved staging
first reserves it and refuses queue_capacity when the recovery budget is full,
also with nothing changed.
#6640's drop (abandon the blocked publication and keep the disk bytes) is
--keep disk on a live request; there is no separate flag.
Frontmatter keys
Say to your agent: "doctor reports stale_frontmatter_keys on tens of
thousands of pages. Is anything broken, and what does the sweep change?"
Imports before mid-2026 could store the parser's four reserved keys (type,
title, tags, slug) inside pages.frontmatter. A file never carries them
there (the parser lifts them into page columns), so for those rows the
canonical file and the database copy never compared equal, and every
coordinated write was refused source_changed (#6454). Since v0.60.176.0 the
comparison and the render skip those four top-level keys on both sides, so
the refusals stop on their own and the stored keys are inert: nothing is
broken. Refused writes whose receipt is retained replay with
gbrain repair failed-writes.
gbrain repair frontmatter-keys removes the inert keys from the rows. It is
explicit-only and preview-bound; the preview says how many pages carry which
keys and prints a hash, and the apply sweeps exactly that set in source-scoped
batches of up to 1,000 pages, each a coordinated maintenance write under the
pages' key locks (a bare UPDATE pages is refused by the managed writer
guard). Database rows only: no file, body, tag or embedding change, no journal
admission. The one visible effect is the revision: the database advances
knowledge_revision on any frontmatter change, so every swept page gets a
new revision once and a client that saved an older expected_revision gets
one revision_conflict on its next write and re-reads.
gbrain doctor --only stale_frontmatter_keys # count per source
gbrain repair frontmatter-keys --source default # preview: pages and keys, prints the hash
gbrain repair frontmatter-keys --source default --apply --expect <hash>
gbrain doctor --only stale_frontmatter_keys # ok
A page whose keys a write cleared between preview and apply is counted
already_clean. Nested user keys with the same names (metadata.title) are
never touched; only the four top-level keys are.
Aliases
Doctor dangling_aliases counts alias rows whose target page is gone. Two
kinds are reported apart:
Orphaned: the target slug has no page row at all, usually a page purged before purge removed its aliases (#6619). A free-text alias can still resolve a name to that missing page. Preview per source, then apply:
gbrain repair aliases --source <id> gbrain repair aliases --source <id> --applyThe apply deletes
page_aliasesrows whoseslugis the missing page andslug_aliasesrows whosecanonical_slugis the missing page. A redirect whose old name happens to be the missing slug but points at a live page (a rename) is kept.Soft-deleted target: the page is in its restore window. Its aliases are kept so
gbrain restorebrings them back; purging the page removes them. Nothing needs running.
Both alias tables carry the managed writer guard, so deleting rows with raw SQL fails on a managed brain; use the repair.
Orphan children
Say to your agent: "gbrain fails with unexpected chunk number or
tuple concurrently deleted, or doctor warns child_table_orphans. Fix it."
These errors (SQLSTATE XX000) mean stored data is damaged, usually after a crash or a full disk. Child rows can outlive their page row, and a page body can be torn, so every command that reads it fails. Preview first; it changes nothing:
gbrain repair orphan-children # orphan child rows per table, plus torn_pages
gbrain repair orphan-children --apply # deletes the orphan rows, clears dangling references
gbrain doctor # child_table_orphans is ok
The preview also reads every page body and lists the rows it cannot read
(torn_pages, with page id, source and slug). The repair never changes those
rows. Recover them from a backup, or create a fresh brain and sync it again
from its source files. Until then, a write that names the revision of a page
the upgrade could not backfill is refused with revision_backfill_pending;
doctor's revision_backfill check names those pages, and
gbrain apply-migrations --force-schema resumes the backfill for the rest and
prints its progress.
Timeline comments
Earlier releases filed an HTML comment next to a [Source: ..., YYYY-MM-DD]
citation (such as <!-- AUTO:slack END -->) as a timeline row and wrote it
back into the page. The parser now skips comments, and a row still carrying
<!-- or --> is never written back (timeline_comment_markup). This
explicit-only kind cleans what is already stored.
Say to your agent: "Preview the timeline comment cleanup, tell me how many rows and pages it touches, then apply after I agree."
gbrain repair timeline-comments --source <id> # preview: comment_only_rows, comment_bearing_rows, pages_with_comment_bullets
gbrain repair timeline-comments --source <id> --apply # clean them
It drops generated bullets that carry markup (yours are left alone), deletes markup-only rows and strips the rest, under the page lock. A second apply finds nothing, and a timeline-only rewrite queues no facts extraction.
Contact rows
A writer that appended a {type, value, last_used} row to a page's
frontmatter contacts: list on every touch, instead of updating the existing
row, left the same value many times (#8109). This explicit-only, preview-bound
kind collapses the rows already stored, whichever writer left them. It never runs from --all, doctor's remediation plan, the
maintenance cycle or an upgrade.
Say to your agent: "Preview which pages repeat contact rows, show me the counts, then apply after I agree."
gbrain repair contact-rows --source <id> [--slug <slug>]... # preview: dedupe / needs_reconcile
gbrain repair contact-rows --source <id> --apply --expect <hash> --yes # rewrites exactly the previewed pages
Rows group by type (trimmed, case-insensitive) and value (trimmed), so two
spellings of one number stay two rows. A group collapses into its first row,
keeping the newest last_used (and any other activity date); a field present on
one row only is kept. A group whose rows differ in any other field only loses
exact copies. Rows that are not {type, value} objects are left alone, and only
the contacts key changes.
The preview counts pages_to_dedupe, rows_to_remove and needs_reconcile.
A page whose canonical file differs from the database is listed
needs_reconcile and never written: preview
gbrain sources reconcile <source> <slug> --brain host --preview --auto-additive
(a last_used that moved forward is structurally additive), apply it, then
preview this repair again. The apply publishes one revision-bound put_page per
page, so a source with a checkout commits the file through the coordinated
writer and a repo-less source writes the database; a page that changed since the
preview refuses with preview_changed.
Timeline order
Bulk imports and hand edits appended timeline bullets at the end of a page,
copied one bullet twice, or started a second ## Timeline section (#7247).
add_timeline_entry already inserts in date order; this explicit-only,
preview-bound kind fixes pages written before that. It never runs from
--all, doctor's remediation plan, the maintenance cycle or an upgrade.
Say to your agent: "Preview which timelines are out of order, show me the list and the pages it would leave alone, then apply after I agree."
gbrain repair timeline-order --source <id> [--slug <slug>]... # preview: reorder / needs_human
gbrain repair timeline-order --source <id> --apply --expect <hash> --yes # rewrites exactly the previewed pages
It sorts - **YYYY-MM-DD** | source — summary bullets, each with its indented
lines and the materialized marker above it, in the direction the page already
uses (ascending unless most neighbouring bullets descend), keeping equal dates
in their order. Prose, sub-headings, comments and code blocks stay where they
are, so bullets are sorted only between them. A later exact copy of a bullet in
the same run is dropped; bullets with one date whose summaries differ only in
case and punctuation are counted as near_duplicates and kept. A later
timeline section joins the first one, under its heading, when it holds nothing
but bullets and the first holds one run of them.
The preview counts pages_to_reorder, duplicates_to_merge,
sections_to_join, needs_human and near_duplicates. A page is listed
needs_human and kept when a line could belong to a bullet (a line right under
it, odd indentation, an indented paragraph after a blank line), when dated
bullets in another format sit among them, when a fence or comment never closes,
when the sections cannot be joined without moving prose, or when the result
would not read back with the same text order and timeline rows. A page whose
database-only timeline rows the write would also put into the page
(pending_materialization) waits for gbrain repair timeline (or
gbrain extract timeline --prune-orphans for rows an edit removed).
Each page is one revision-bound put_page: a managed source publishes its file
through the Git effect and the database is projected from it. No timeline row
is added, removed or rewritten (a dropped copy shared its row with the one that
stays). An apply refuses preview_changed when a previewed page moved since the
preview; preview again. Undo a page on a managed source with git revert of its
commit, or gbrain revert.
Secret spans
A credential pasted into a page is often stored in more places than the page
file: the page row, a held page the sync left alone, timeline, fact and take
rows, link contexts, raw connector data and the chunks built from them. This
explicit-only, preview-bound kind replaces each value the secret scanner finds
in those database copies with a <REDACTED:rule> marker and leaves every other
byte as it was. Redacting the files themselves is a separate step through the
normal write path; this kind never writes a file or a commit.
Say to your agent: "Preview the secret spans on these pages, show me the counts by rule, then apply after I agree."
gbrain repair secret-spans --source <id> --slug <slug>... [--rules <rule,...>] # preview: counts and hashes, never values
gbrain repair secret-spans --source <id> --slug <slug>... --apply --expect <hash> # rewrites exactly the previewed pages
--rules picks the scanner rules (default: every named credential rule, such as
openai, aws_access_key, github_token, jwt, bearer and
private_key_pem). The two broad heuristics, high_entropy_assignment and
labeled_credential, run only when named, because they also match things that
are not keys. An unknown rule name refuses before anything is read. A preview
with no --slug (the command gbrain doctor --remediation-plan lists) reads
nothing and prints how to name the pages; an apply still needs both.
What it reads and rewrites for each page: the title, every string value in the frontmatter (keys are never touched), the body (inline, or the live generation of a segmented page, which is restaged in place), timeline rows of the page or its event page, fact rows held by the page or naming it with no holding page, take rows, the context of its outgoing links and every string value of its raw data. A value found by a rule in one place is also replaced where it appears bare elsewhere on the same page (an echo). A key glued to an existing marker is replaced too, and text that is already only markers is left alone, so a second preview of an applied page is empty.
The preview lists each page with its spans per rule and, for each changed
field, the first 64 bits of its old and new SHA-256 and a hash of the span
offsets. It never prints a value. It also counts the retained page versions,
which are kept as history and not rewritten. A page is refused, and nothing
on it changes, when it does not exist, is a code or image page, has a segmented
body over 24 MiB, when the planned spans and the scanner's own redaction of the
text disagree (proof_failed), when an ontology fact's resolved value holds a
match (fact_value_unsupported: the value keys the fact's dedup; retire the
fact with gbrain forget), or when two timeline rows of one day would read the
same once redacted (timeline_rows_collide: delete the duplicate row first).
The apply checks every previewed page again before writing anything and
refuses preview_changed if one moved; preview again. Each page is then one
transaction under its page lock: a coordinated maintenance write on a managed
brain, an attributed maintenance transaction on any other brain (repo-less
brains included). Trust tiers are kept. Chunks that held a value are deleted
and rebuilt from the redacted body, keeping the vectors of unchanged chunks;
changed chunks are embedded unless --no-embed or the page carries
embed_skip. Fact and take vectors of a rewritten row are cleared. A
value-free receipt per page (field fingerprints and span offsets) is stored
with the write, where a resumed apply finds it for the next 7 days, and
appended to the secret-spans audit log, and the apply re-scans each
page and reports any match left (residual, expected 0).
There is no undo: the old value is gone from the live copies. Page versions,
write receipts and Git history are kept and still hold it. On a brain with a
repository, redact the file too: a later import of the unredacted file (a full
sync, gbrain repair file-drift --prefer file, an edit) writes the value back
into the database. It runs only from
the trusted local CLI on the brain host, only when named, and never from --all, doctor's remediation plan, the maintenance
cycle or an upgrade.
Timeline history scan coverage
Doctor's timeline_history check classifies at most 2,000 pages or 10
seconds of work per run. On a larger brain each run continues where the last
one stopped (the cursor is kept in the config row
doctor.timeline_history.scan:<sources>), so a few consecutive gbrain doctor
runs finish a full pass and report exact counts. While the next pass is in
progress, a clean finished pass keeps the check ok until a newer timeline row
is written. A run that has neither says scan incomplete and is a lower bound;
gbrain repair timeline (preview) counts the whole brain in one go.
Ghost pages
A ghost page is a live page whose canonical file is gone on the source's owner
host: the file was moved or deleted outside gbrain and the deletion was never
imported. Every write to it refuses source_changed with reason
canonical_file_missing (write refusals),
and no sync can import a file that is not there, so retrying never clears it.
Doctor ghost_pages counts them on the owner host (off it, or on a brain with
no source checkout, the check is ok and not applicable); gbrain pages ghosts --source <id> [--json] lists them, read-only. A person decides, per page,
which is right:
- Keep the page: restore its file at the recorded canonical path on the
owner host (from Git or a backup), then run
gbrain sync --source <id>. Do not apply the repair. When the deletion is already committed (the file is gone from HEAD),gbrain repair file-drift --prefer databaserecreates the file from the page instead (deleted canonical files). - Remove the page: preview, then apply after the user agrees.
gbrain repair ghost-pages --source default # preview: each ghost, its recorded path and revision, and a hash
gbrain repair ghost-pages --source default --apply --expect <hash> --yes
The preview writes nothing and prints the apply command with its hash. The
apply needs the user's consent: without --yes a terminal asks, and a
non-interactive run exits 3 (ask_user) with the consent payload and changes
nothing. It soft-deletes exactly the previewed set through delete_page, bound
to the canonical owner the preview ran under (host, worktree, owner epoch,
source incarnation), each page's revision and its recorded path. Each page is
checked again before its request, again in preparation, and its file at
filesystem publication: a page whose file came back is kept (file_restored)
and the result asks for a new preview; anything else that moved is
changed_since_preview. Soft-deleted pages are purged for good by the
autopilot purge phase 72 h after deletion; until then gbrain restore <slug> --force undoes one page (per slug; it writes the file back).
It refuses:
- off the source's canonical owner host,
not_owner_host; - when the checkout is missing or cannot be read reliably (a stat error, an
invalid gbrain.yml, an inconclusive page check),
ghost_storage_unknown: a page is never removed while its file may only be unreadable; - when the ghosts are more than half of a source's file-backed pages (on a
source with more than 20 of them),
ghost_mass_delete_refused: that almost always means the wrong or an unmounted checkout. Check it first; if the removal is genuinely intended, ask the user and rerun the apply withGBRAIN_ALLOW_MASS_RECONCILE=1.
Declared storage.db_only pages, never-filed derive-phase pages, read-only
mirror pages and pages written while their source was unbound publish to the
database only and are never ghosts. Doctor undeclared_db_only_pages is a
separate audit. A preview lists at most 1,000 ghosts; apply them, then preview
again for the rest. Sync never removes ghost pages by itself.
A code or image page (a synced .json, .ts or .png file) is checked at
the file it records, never at <slug>.md: while that file is there the page
is not a ghost. It is a ghost only when its recorded file is gone and no file
sits at its slug path either, and the preview lists it at the recorded path.
The apply retires it at that recorded file too: a recorded file restored
before publication keeps the page (file_restored), and the commit records the
removal of the recorded file. A
page whose recorded path names no file inside the source (an absolute path, a
path with ..) is never a ghost and is never removed: doctor, gbrain pages ghosts and the preview list it apart with code recorded_path_unresolvable.
Uncommitted deletions
Before #7130 a managed sync read any absent recorded file as a deletion, even a
file Git never committed: an agent's write-through file in a directory
.gitignore excludes, or an untracked file removed before any commit. It
soft-deleted those pages, and the purge removes a tombstone for good after its
retention window. Sync now holds such a page instead
(file drift, side deleted, reason never_committed or
ignored). For a brain already hit, doctor uncommitted_sync_deletions
counts, on each source's owner host, the tombstones a sync deleted whose file
.gitignore excludes or no commit of HEAD's history holds (and that is not on
the disk). It reads at most 2,000 tombstones per run across sources, newest
page id first, with their Git evidence; when it was bounded it says so and
names the preview that continues below the last page it read
(--after <page-id>).
Off the owner host, or on a brain without managed sync, it is ok and not
applicable. To restore them, preview, then apply after the user agrees:
gbrain repair uncommitted-deletions --source default # preview: slug, recorded path, deletion time, evidence, who deleted it, and a hash
gbrain repair uncommitted-deletions --source default --apply --expect <hash> --yes
Pages already purged cannot be restored by this command; only a backup
(pg_dump, or a gbrain backup create taken before the purge) can bring them
back. Restore what is still there before the purge runs.
The preview writes nothing. Its default set is the pages a sync deleted (the
open sync-delete-tombstone record of the page's current tombstone, or the
committed managed_sync_delete receipt that made it; a record left from an
earlier deletion of the same page does not count);
pages another writer deleted are listed apart and join the hashed set only with
--include-ambiguous. The apply needs the user's consent: without --yes a
terminal asks, and a non-interactive run exits 3 with the consent payload and
changes nothing. It restores exactly the previewed set, bound to the owner and
each page's revision, through one coordinated restore_page with
detach: true per page, published database-only: the page comes back live
with no recorded file (database_only_reason='detached') and no file is
written, so no later sync reads its file as missing. A page that moved since
the preview is skipped changed_since_preview; one whose file is in the
checkout again is skipped file_restored (commit it and sync instead); one
purged in between is skipped purged. A wrong or stale hash refuses
preview_changed, and off the owner host the preview and
the apply refuse not_owner_host. Undo one
page with gbrain delete <slug>. One preview reads a bounded window of at
most 5,000 tombstones, newest page id first, and lists at most 1,000 pages.
When it is bounded its details.truncated is true and details.next_after
names the page id to continue below: after applying this set (or deciding not
to), preview the next window with
gbrain repair uncommitted-deletions --source default --after <next_after>.
The hash covers --after, and the printed apply command carries it. An apply
stopped part way (--limit, a time budget) resumes over the rest of the same
approved set when rerun. The repair runs only when named, never on upgrade or
from a maintenance cycle.
Rows behind the checkpoint
A managed sync records the commit it imported as the source's checkpoint
(sources.last_commit) and decides that a file needs nothing from the file's
import record. When that record names the current blob while the page row
still holds an older version of the file (#8071), every later sync reports the
source up to date, and search and reads keep returning the old text. The page
is live and has no hold, so the landing checks pass it.
Doctor sync_rows_behind_checkpoint finds these rows. On each managed
source's owner host it compares every live Markdown page with its file read
from Git at the checkpoint commit (never the working tree, never the import
record): an inline page byte for byte through the export view, a page stored
in segments by streamed hash. It then confirms each difference with the
importer itself, so a row that importing the committed file would leave
unchanged is current. A row is reported only when its revision is the one its
last sync import wrote. A row the database changed since that import belongs
to file drift and is not reported here. A row with no import
record is counted as unproven from the content comparison alone and does not warn. Held paths, paths a later
commit changed (the next sync imports them), paths sync would not import
(not_eligible: outside the source's scope, matched by sync.exclude, hidden,
or a reserved skillpack path) and declared database-only pages are skipped. A file over the sync read bound is never read; its row is
reported with the file_too_large refusal sync would hold it with. The scan
is bounded by GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS (default 10 s), checked before
each row's comparison; a scan the budget stopped (doctor names the pages it
decided and the page id it stopped at), or a checkout Git cannot read, is
unknown, never a clean ok. Off the owner host, on a source without a checkout or a
checkpoint, and on a repo-less brain (the database is the record there) the
check is ok and not applicable.
To re-import them, preview, then apply after the user agrees:
gbrain repair rows-behind --source default # preview: each row, its path, the checkpoint blob and the action, with a hash
gbrain repair rows-behind --source default --apply --expect <hash>
The preview writes nothing. Each row in the set has one action:
reimport: the committed file is imported through the managed file repair, the same screen, preparation and projections a sync import uses, bound to the page revision and the previewed result. The file on disk already holds those bytes, so no file is written.hold:<code>: importing the committed file is refused (for example a malformed fence), or the file is over the read bound (hold:file_too_large). The apply opens the hold sync would have opened, with the code and message of the refusal the apply computes again, and the usual held files steps clear it.
Listed but left out of the set: rows with no import record
(excluded:unproven, joined with --include-ambiguous), rows with no import
record whose older version equals the committed file, so the database moved
since and a re-import would replace that edit (excluded:database_moved, never
joined; gbrain repair file-drift --source <id> --slug <slug> --prefer database
keeps it), rows with no import record whose page and file both moved since the
last state they shared (excluded:both_moved, never joined; gbrain repair file-drift --source <id> --slug <slug> decides each one), rows whose
working-tree file differs from the committed one (excluded:worktree_differs:
commit the edit and sync), and rows whose import would keep page data the
file does not carry (excluded:import_overlay; resolve them with
gbrain repair file-drift --source <id> --slug <slug> --prefer file). A row
whose page, owner, checkpoint or file changed since the preview is skipped
changed_since_preview; a wrong or stale hash refuses
preview_changed. Off the owner host the preview and
the apply refuse not_owner_host, and a
repo-less source lists nothing. One preview lists at most 1,000 rows; when
more are behind it says so, and the next preview after the apply lists the
rest. The repair runs only when named, never on upgrade, from --all or
from a maintenance cycle.
Legacy twins
Before #6857, a managed sync could fork a second page for a file an older gbrain
had imported under its raw name: the legacy page (the original id, a slug
such as notes/foo bar that the current slug fold spells differently, no
recorded file, and the page's links, timeline and history) and its twin
(the folded slug notes/foo-bar, recording the file). Sync no longer forks
new pairs, but it leaves the existing ones as they are. Deleting the twin by
hand withdraws the file, because no other live page records it; deleting the
legacy page keeps the file but loses the id, links and history.
gbrain repair legacy-twins converges each pair onto the legacy page.
gbrain repair legacy-twins --source default # preview: each pair, decisions, and a hash
gbrain repair legacy-twins --source default --apply --expect <hash> --yes
The preview writes nothing. It lists every pair with both page ids, slugs and
revisions, the file the twin records and whether the two pages hold the same
content, and prints the apply command with its hash. A pair the repair never
merges on its own is listed as a decision (class decision:<reason>), with the
commands a person uses to decide it:
| Reason | What to decide |
|---|---|
content_differs |
The two pages hold different content. Compare them (gbrain get --source <id> -- '<slug>'); make them the same (edit the file and sync, or edit the legacy page) and preview again, or keep the twin and delete the legacy page. |
several_legacy |
More than one legacy page folds to the twin's slug. Keep one, soft-delete the others, preview again. |
file_missing, file_drift, file_unverified |
The twin's file is gone, differs from the twin, or cannot be checked. Resolve it with ghost pages or file drift first. |
twin_slug_path_occupied |
A file sits at the twin's own slug path (<twin-slug>.md), which the twin's purge would compare or remove. Rename or remove it, sync, preview again. |
twin_has_withdrawals |
Claims were forgotten on the twin. Forget the same claims on the legacy page first, or retire the twin by hand. |
legacy_records_file_uri |
The legacy page records a file URI of its own; reconcile it first. |
twin_evidence_conflicts |
The twin holds a link, relationship date, timeline entry or raw data row that the legacy page holds differently, so the merge would lose it. Make them agree, or retire the twin by hand, then preview again. |
The apply needs the user's consent: without --yes a terminal asks, and a
non-interactive run exits 3 (ask_user) with the consent payload and changes
nothing. Each approved pair is one coordinated write (an unmanaged brain does
the same in one transaction):
- The legacy page records the file. It keeps its id, slug, links, timeline, versions and aliases.
- The twin merge
gbrain repair origin-twinsuses (#6948) moves the twin's links in every role and their dated transitions (links between the two pages stay on the twin), timeline rows, raw data, attachments, user-added tags, slug aliases and facts other pages assert about it to the legacy page; an exact duplicate of a legacy row is dropped, and a differing one makes the pair atwin_evidence_conflictsdecision. The twin's slug becomes an alias of the legacy page, so[[notes/foo-bar]]andgbrain get notes/foo-barkeep resolving. - The twin's sync import record moves to the legacy page, so the next
gbrain sync --source <id>finds the file and the page unchanged: no new page, no hold, no file write. - The twin is soft-deleted as a shared origin: the file is not touched. Its tombstone forgets the file, so the autopilot purge removes it from the database 72 h later without refusing it as a page whose file another page records.
A twin soft-deleted by hand while the legacy page records the file (receipt
write_through.skipped: shared_origin) keeps its recorded file, and the
retention purge removes it database-only too: the file and the legacy page stay
and no content tombstone is written. A tombstone an older release parked after
refusing it gets one automatic attempt from the first purge run after the
upgrade (a park another gbrain version wrote is retried once) and is purged then.
The legacy page keeps its slug: that is also the slug sync gives a never-forked file whose legacy page it takes over (#6727), and the folded slug resolves to it through the alias. The twin's import-owned tags, chunks, versions and the facts and takes its own body projects stay with the twin (the legacy page has the same ones, from the same content). Restoring the twin brings back a page that records no file; what moved stays on the legacy page.
Each pair is checked again before its request, in preparation and under the
publication locks (both page ids, slugs and revisions, the recorded path, the
owner, the content and the file); a pair that moved is skipped
changed_since_preview. It refuses off the canonical owner host
(not_owner_host), when the checkout cannot
be read (legacy_twins_storage_unknown),
and when the pairs are more than half of the source's file-backed pages on a
source with more than 20 of them
(legacy_twin_mass_merge_refused;
rerun with GBRAIN_ALLOW_MASS_RECONCILE=1 only after the user agrees). A
preview lists at most 1,000 pairs and decisions; apply them, then preview
again. Trusted local CLI only; it runs only when named.
Ghosts under the shared skillpack. When a source has an adopted shared
skillpack, its reserved paths (skills/ and skillpack.json) belong to the
shared skill publisher, and knowledge writes there refuse
skill_bundle_required. Two kinds of ghost can sit on those paths:
- A legacy knowledge page that no live pack skill owns (imported before the
pack was adopted, say, under a
skills/<name>/directory the pack does not publish). It is an ordinary ghost: the preview lists it with the others and the apply retires it as a database-only soft delete. Its file is already gone and filesystem publication refuses one that reappears, so no pack file changes. - A page on a path the pack owns:
skillpack.json, a file of a live skill's current revision, or anything under a live skill'sskills/<name>/directory. Its missing file is the pack's own, so the repair never removes the page. The preview lists it apart with codeghost_skill_pack_member(residuals.skill_paths, anddetails.skill_pathswith the first slugs,owned_by: shared_skill_publisherand onerestorecommand per page) and leaves it out of the hash. To clear it, restore the file on the owner host:git -C <source root> checkout -- <path>when the file is committed, or republish the skill withput_skilland its catalogexpected_revisionso the publisher writes it again. The page then stops being a ghost.
Doctor ghost_pages and gbrain pages ghosts count pack-member ghosts apart
(skill_paths, with the same restore step), never as ghosts waiting for this
repair; on their own they leave the check ok.
refused. A page of the approved set that a per-page guard still refuses
during the apply (a refusal of class caller, such as skill_bundle_required
on a page an older preview approved) is recorded with outcome refused and its
code in outcome_items; nothing is written for it, and the apply goes on with
the rest of the set. Read the code (gbrain errors <code>) before retrying
that page. Any other error, such as a storage fault, an unavailable owner or
contention, still stops the apply; rerun the same apply command once it clears.
Origin twins
gbrain repair origin-twins --source <id> (#6948) resolves duplicate-origin twins: several live pages of one source
recording the same file as their origin, which managed sync holds origin_conflict
while the rest of the source syncs. It is explicit-only, preview-bound and destructive, runs only on the source's
canonical owner host (not_owner_host elsewhere), and refuses a remote caller.
The preview lists each group with its pages, ids, revisions and verdict, using the same rule as sync:
- Verified duplicates (no reason): exactly one page is the page the path names, every page holds the same inline
body, the file is readable, no two explicit frontmatter
ids differ, the pages share one visibility and one trust tier, no other page has slug-keyed fact withdrawals or purges or a file at its own slug path, and no other page holds a manual link, relationship date, timeline entry or raw payload that differs from the canonical page's. The apply merges each other page into the canonical one. Links in every role, link transitions, timeline rows, raw data, attachments, user-added tags, free-text aliases and facts other pages assert move to it; an exact duplicate, or a link re-derived from the shared body, is dropped. The twin's slug becomes an alias. The twin forgets the file, is markedorigin_twinand is soft-deleted (the file is untouched), and the 72 h retention purge removes it database-only. Its receipt (origin_twin_resolved) lists every frontmatter key of the twin the canonical page lacks or holds differently, with the twin's value, plus the restore command. The canonical page's frontmatter comes from the file, so add any key you want to keep to the file. - A decision (a reason): listed with the commands to decide it, never resolved by a plain apply. With
--slug <kept-slug>the preview offers only to detach the other pages: they forget the file, are markedorigin_twinand stay live as database-only pages. Nothing is deleted.
A page marked origin_twin never writes or removes a file again: gbrain restore brings back its own text as a
database-only page, an edit publishes database-only, and an owner --purge is refused because its content is the
canonical page's (the retention purge still removes it). A later file at its own slug path, imported by sync, clears the
marker.
The apply refuses origin_twin_mass_merge_refused when its merges
would soft-delete more than half of the source's file-backed pages, unless GBRAIN_ALLOW_MASS_RECONCILE=1.
Sync-time heal. After each successful managed sync, held files whose pages are still verified duplicates are merged
the same way, at most 200 files per run and 1,000 twin pages per source per 24 h, and never on a dry run, under a remote
job, with an unfinished sync cursor, or above the mass valve. gbrain sync --json reports it as
origin_twins_resolved. Opt out with gbrain config set sync.origin_twins.auto_resolve false (default on, like
sync.slug_conflicts.auto_remove).
The index. Migration v257 builds the partial unique index pages_live_origin_key (one live page per recorded
origin; CREATE UNIQUE INDEX CONCURRENTLY on Postgres) only when the brain has no twins. With twins the migration
changes nothing and succeeds, and doctor's origin_twins check reports "Index pending". Once the last group is
resolved, the repair's apply builds the index.
Moved pages
Sync follows a file move when it happens. When the old page's deletion was held (a managed sync holds file_gone for a
page it cannot prove unchanged, including one with no import record), the new path imports as a fresh page and nothing
pairs the two again. Neither side of repair file-drift is right for that page: --prefer file soft-deletes it and drops
its links, facts, timeline and versions, and --prefer database writes a stale duplicate back at the old path. So the
file-drift preview lists such a page moved_to, resolves nothing for it, and names this repair instead:
gbrain repair moved-pages --source <id> [--slug <old-slug>] # preview, writes nothing
gbrain repair moved-pages --source <id> --apply --expect <hash> --yes # after the user agrees
A page folds only on two facts read from Git and the page, never on what the moved file holds today:
- The move. The old path's last committed content (its blob at the parent of the commit that deleted it) is the content one new path took in that same commit, or in the first commit that holds the new path. A Git rename with the same content is the first case. Later edits to the moved file don't matter.
- The old page is untouched. It still holds what that content imports (gbrain's own database-only artefacts, such
as the grandfather
validate: falsestamp and a renamed pack type, count as unchanged).
Exactly one live page may descend from that content. The file name only explains a page with no candidate, because a
move can rename the file too, and a matching frontmatter id alone never pairs two pages. Every other page whose file
is gone is listed with why it is kept: several_candidates, shared_survivor (two or more old pages deleted with the
same content each still back a live page and claim one moved page: the user picks which one moved, and the others are
retired with gbrain repair ghost-pages; the preview then folds the one left), segmented_versions (the old page or one
of its saved versions is stored in segments, over 1 MiB; segmented versions name their own page's body, so this repair
does not move them and the page stays as it is), access_differs (the old and the moved page differ in who may read
them: readable_by, a folder rule or the privacy label; a fold would put the old page's database-only evidence under the
moved page's access, so decide with the user), both_changed (the old page was edited in the database
after the move: decide with the user), first_blob_differs (a page with the same file name started from other content),
same_id_body_differs, evidence_conflicts (a manual link or timeline entry that differs from the moved page's),
history_shallow (run git fetch --unshallow and preview again), history_unknown, deletion_not_committed and
not_moved.
The apply re-checks the proof and both pages under their keys, then folds each pair in one write (a coordinated
managed_maintenance_fold_moved_page maintenance write on a managed source, one maintenance transaction otherwise): the
old page's links in every role, relationship dates, timeline rows, raw data, attachments, user tags, free-text aliases,
facts other pages assert and saved versions move to the moved page, its slug becomes an alias (get_page and links
by the old slug reach the moved page), its file_gone hold is cleared, and it is marked origin_twin and soft-deleted.
No file is written. Each page gets a receipt (moved_page_folded) with the move commit, the blob and the restore
command: gbrain restore <old-slug> within 72 h brings back its own text as a database-only page, and the alias then
stops answering for it; references and versions moved to the moved page stay there. The apply refuses
moved_pages_mass_fold_refused when its folds would soft-delete more
than half of the source's file-backed pages, unless GBRAIN_ALLOW_MASS_RECONCILE=1. A source with no checkout (a
repo-less source) has no file that could move, so the preview lists nothing.
Slug path mismatch
Doctor's slug_path_mismatch check (#7305) counts live pages whose slug their recorded file path does not derive. The
usual case is a hyphen run or a segment-final hyphen: notes/x-1900---2000-ab.md imports as notes/x-1900-2000-ab,
because the path rule folds every hyphen run to one hyphen. Import and sync keep such a page on its own slug only
through the slug: line every render stamps into its file (#5966). A file without that line, such as one an
older gbrain rendered or another tool rewrote, imports as the folded slug and forks a duplicate-origin twin, which sync
holds origin_conflict.
The check is read-only. It reads at most 20,000 candidate pages and 200 recorded files per run, and reports Unknown
when either bound stops it. It warns only when a file read on this host lacks the stamp, naming
gbrain repair frontmatter --source <id>, whose preview proposes the stamp as a safe repair. A twin that already forked
is reported by origin_twins and resolved with gbrain repair origin-twins.
put_page and capture refuse a new slug with a hyphen run or a segment-final hyphen (invalid_params, detail
slug_hyphen_run) and name the folded slug. A page that already holds such a slug keeps updating under it, and its
response carries slug_advisory. To move it, put its content under the folded slug, then delete the old page.
Rename identity
When sync cannot confirm an inexact Git rename (#6729), it imports the pair as a
delete plus an add: the new file starts a fresh page and the old page keeps its
history, facts, links and aliases on its soft-deleted slug. The sync report,
gbrain sync status --source <id> --json (identity_downgrades) and doctor
rename_identity_downgrades name each open pair with its remedy, and the purge
leaves the old page alone until the pair is settled or the old page is restored
or purged. A person picks one of three routes per pair:
- Carry the identity (a deferred true rename): the old page id takes the new slug with its version history, timeline, links, facts and aliases; the new file is imported onto it as an edit; the provisional page is retired (soft-deleted under a purged slug, its history and edges moved onto the carried page) and the old slug redirects to the new one.
- Close the pair: nothing moves; the old page is purged with the next purge after its soft-delete window.
- Keep both pages:
gbrain restore <old-slug> --source-id <id> --force.
gbrain repair rename-identity --source default # lists the open pairs, each with its preview command
gbrain repair rename-identity --source default --slug notes/roadmap # preview one pair (add --from <old-slug> when two pairs share it, --close to close)
gbrain repair rename-identity --source default --slug notes/roadmap --apply --expect <hash> --yes
The preview writes nothing; it binds both page ids, both revisions and the
disposition into its hash. The apply needs the user's consent (destructive):
without --yes a non-interactive run exits 3 with the consent payload and
changes nothing. It re-reads both pages under their page locks and refuses
changed_since_preview when anything moved, and it settles the pair
(remedied or closed) in the same transaction. A rerun finds no open pair
and writes nothing.
A carry keeps the facts of both pages or refuses. Every row of the old page's
## Facts fence must be in the new file's fence at the same row number with
the same claim; the old row (its id, created_at and valid_from) survives
with the new row's fence fields. Anything else refuses
fact_rows_collide before writing, naming
the rows: give each old claim its own row in the new file, commit, sync and
preview again, or take another route.
A carry runs on classic sources only. On a managed source page tables change
only through coordinated publications, so carrying is unavailable there
(managed_remedy_unavailable):
the preview says so and writes nothing, an apply refuses with that code, and
the sync report, sync status and doctor name --close (its preview and
its apply with consent) as the pair's remedy. --close releases the purge
hold without carrying identity, on both kinds of source; restoring the old page
also works on both.
Explicit-only: gbrain repair --all, the maintenance cycle and the doctor
remediation plan never run it.
Calls not scoped
gbrain import --calls on a brain that serves two or more people keeps each new call to the brain owner plus the teammates its Attendees: or Participants: line names. When some caller that could be the owner's own would lose the call, the import stays open, exactly as before, and prints the calls_not_scoped notice with the reason and the one command that fixes it:
| Reason | What it means | Fix |
|---|---|---|
owner_unset |
The brain names no owner, so no reader list could name one. | gbrain access owner set <member> |
owner_inactive |
The owner member is not enabled. | gbrain access member enable <owner> |
unbound_readers |
A token or OAuth client bound to no person still reads the brain (grace, --reads-unscoped, or a host that does not enforce binding). |
The gbrain auth rescope ... --member <member> the notice names, for each one |
stdio_unbound |
A local harness connection bound to nobody still reads the brain. | gbrain setup <harness> --stdio-member <owner> |
Then import again. --readers source imports open on purpose and prints no notice. Calls imported before are not changed by an upgrade.
Stale atoms
gbrain repair stale-atoms (explicit-only) retires atoms that drifted from
their source page and that managed re-extraction never retired (atoms left
by an older gbrain). It lists live atoms bound
to a source page (source_slug) in two classes:
origin_gone: the source page is missing or deleted;origin_changed: the source page was edited, and its current text has already been extracted (a managed brain records a completed extraction at the page's current hash; an unmanaged brain has an atom carrying it). Atoms of an edited page that was not extracted again yet are the extract_atoms backlog, not stale, and are not listed.
It never lists an atom with imported_from or a transcript (file-bound)
atom.
gbrain repair stale-atoms --source <id> # preview: every atom with its class, and a hash
gbrain repair stale-atoms --source <id> --apply --expect <hash>
The apply retires exactly the previewed set. Each atom is checked again first;
one whose revision, class, source page or completion evidence changed since
the preview reports changed_since_preview and is kept. Retiring is a soft
delete stamped with retired_by: stale-atoms: on a managed brain each atom is
one coordinated request (its file is removed through the page deletion path),
on an unmanaged brain a direct soft delete. Retiring also marks the source
page for extraction again, so restoring a deleted page and running
extract_atoms brings its atoms back. --apply without --expect refuses
with the preview and apply commands; a stale hash refuses with
preview_changed. An apply under a different --source
than the preview also refuses with preview_changed. Doctor
atom_provenance_drift names this command when drift crosses its warn
threshold. An atom whose page changed only in its frontmatter or in gbrain's
facts and takes sections is not drift when one of the page's recent versions
still holds the edition it was extracted from (#6825).
Atoms restore
A managed atom re-extraction whose model returned no atoms for a page or
transcript (#7013) retired every earlier atom of that origin: each one was
soft-deleted and stamped retired_by: managed-reextract, and the purge then
removed it for good. gbrain repair atoms-restore brings them back. It is
explicit-only and preview-bound, and nothing runs on upgrade.
gbrain repair atoms-restore --source <id> --json # preview: each atom with its origin, hash and retirement time, and a hash
gbrain repair atoms-restore --source <id> --apply --expect <hash>
The preview lists a retired atom only when all of these hold:
- it is not imported (
imported_from) and carriesretired_by: managed-reextract(astale-atomsretirement is never listed); - its origin is still there: a live page of the same source (
source_slug), or a transcript (source_path); - no live atom of the same origin carries a different source hash, so no later extraction replaced it;
- it belongs to the origin's most recently retired generation (its source hash
is the hash of the origin's latest
managed-reextractretirement), so an older generation that a later non-empty extraction replaced is never revived.
The residuals count what it keeps: origin_gone, replaced and
older_generation, next to restorable and the number of origins.
The apply restores exactly the previewed set and checks each atom again first;
one whose revision or rule match changed since the preview (for example a new
extraction replaced it) reports changed_since_preview and stays deleted. On a
managed brain each atom is one coordinated request bound to the deleted atom's
revision: it reverts the atom to the live version its retirement archived
(same source hash, no retired_by/retired_at), writes its canonical file
back, keeps the derived trust tier an extraction gives it, and the outcome names
the request id (gbrain write-request -- <id> reads its receipt). An atom with
no such version reports no_version and stays deleted. A file that differs from the database at the atom's path reports
file_conflict and is left as it is. On an unmanaged brain the atom is
versioned, restored and has the two keys removed in one transaction. Neither
changes the origin's extraction state. --apply without --expect refuses with
the preview and apply commands; a stale hash or another --source refuses with
preview_changed.
The batch purge (the maintenance cycle, gbrain pages purge-deleted and the
unmanaged bulk delete) holds every atom the preview would list for 30 days
after its deletion instead of the usual 72 hours, so an operator who upgrades
late can still restore it. An explicit gbrain delete <slug> --purge is not
held. Doctor atom_retirements_restorable warns while such atoms exist, with
their count, origins, oldest and newest retirement and the date the first hold
ends; its fix is the read-only preview. Show the user the preview before
running the apply.
Atom fence rows
A world atom carries the claim of a fence row its source page shows only to
the owner when an older extraction read the whole page: a facts row whose
visibility is not world, or a takes row whose holder is not world.
Extraction now reads a page as a world reader sees it, so new atoms never
carry such a row, but atoms already stored keep what they copied and a remote
read returns it. gbrain repair atom-fence-rows finds them and, only when you
apply it, makes them private. It is explicit-only and preview-bound, and
nothing runs on upgrade.
gbrain doctor --only atom_fence_rows --json # count per source; ok when none
gbrain repair atom-fence-rows --source <id> --json # preview: each atom, its source page, the row kinds and numbers, and a hash
gbrain repair atom-fence-rows --source <id> --apply --expect <hash>
An atom is listed when it is live, page-bound (source_slug), stamped
visibility: world, and its title, body or source_quote contains (case and
whitespace folded) the claim of such a row in any fence of its live source page
a world reader does not see (a fence quoted in a code block included), unless
the page's world text holds the same claim too. Claims shorter than 12 characters
are not matched. The preview names each atom with its source page and the
rows (facts row 2, takes row 1), never the row text, and changes nothing.
A source page stored in segments is not read: its world atoms are counted as
origin_unread.
The apply sets visibility: private on exactly the previewed set through a
revision-bound put_page, which re-chunks and re-embeds each atom; remote reads
and search stop returning it, local reads keep it. An atom whose revision,
source page or matched rows changed since the preview reports
changed_since_preview and is kept. --apply without --expect refuses
with the preview and apply commands; a stale hash or another --source
refuses with preview_changed.
Cost: doctor and the preview read every world atom whose source page names a facts or takes fence, in pages of 500 by id, and each such source page once; no model is called. Doctor bounds each statement at 120 seconds and reports the count as unknown when one overruns. Show the user the preview before running the apply.
Generations
Unmanaged atom extraction publishes each page's or transcript's atoms as one
generation (GBRA-161, generations). A result
that would shrink the atom set below generations.shrink_floor, retire items
without proof that the input is empty, change more than generations.max_items
items, trip the retirement valve or touch a segmented page is held: nothing is
written or retired, and the previous atoms stay live. A complete result retires
what it no longer has (versioned, stamped retired_by: extract-atoms, held from
the purge for generations.restore_days, 30 by default). gbrain repair generations undoes or releases them. It is explicit-only and preview-bound,
and nothing runs on upgrade.
gbrain repair generations --kind atom --since 30d --json # --mode defaults to restore
gbrain repair generations --kind atom --mode release-held --held --json
gbrain repair generations --kind atom --key source_slug:<slug> --source <id> --apply --expect <hash> --yes
--kind names the ledger kind (atom in this release); one selector bounds
the set: --run <id> (one extraction run), --since <ISO-8601|7d> (resolved
once to an instant the preview and apply carry), --key <owner>
(source_slug:<page> or source_path:<transcript>), --generation <id>, or
--held (with --mode release-held).
--mode restorerepublishes the item set the selected live generation replaced, as a new generation: atoms it retired come back from their ledger preimages, atoms it overwrote return to their earlier content, and atoms it added are versioned and retired (retired_by: generation-restore). A key with an atom edited since, or one whose preimage is missing (segmented, too large, or purged), is refused whole and listedrefused; the apply exits incomplete and nothing of that key changes.--mode release-heldpublishes a held result once:shrunk,valveandattempts_exhaustedalways,oversizeaftergenerations.max_itemswas raised.no_proof,fence_absent,segmented_unsupportedandtieare refused, because releasing them would supply the proof they lack. On a managed brain, purging the page (gbrain delete --purge, or the purge of an expired tombstone) drops its fence holds, since the purge deletes the rows they would retire.
The preview saves the set under its hash; --apply --expect <hash> --yes
applies exactly that set and rechecks each key under its locks
(changed_since_preview otherwise). Doctor generation_held warns while a
held result waits, with the read-only release preview as its fix;
generation_retirements reports what is restorable. Show the user the preview
before running the apply. Managed brains keep their coordinator path for now.
Facts and takes fences, consolidation chains and extracted facts publish the
same way (--kind fact_fence, take_fence, consolidation,
extracted_facts; key page:<slug> for a fence). A fence restore writes the
earlier fence block into the page as it is now, through a guarded page write
that leaves the rest of the page alone; it works on managed brains too, and a
fence edited since is refused. A consolidation restore reopens the chain's
valid_until and consolidation marks.
Life Chronicle events publish the same way (--kind chronicle-event, key
depth:<slug>): a restore brings back the events a re-judgment or a deleted
depth page retired, with their timeline rows on the depth page, and it runs on
managed brains as one coordinated request.
Dream synthesis outputs publish as a generation per transcript (--kind synthesis, key transcript:<root>/<path>): a complete re-synthesis retires an
earlier output it matched (an exact duplicate, or the same subject with every
claim, quote and citation covered; retired_by: synthesis-resynthesis) and
keeps every other one live. --mode cleanup lists those unmatched
predecessors with why and what each holds alone; show the user the preview, and
--apply --expect <hash> --yes retires exactly the listed ones
(retired_by: synthesis-cleanup). --mode restore brings a retired output back
and puts its file back (unmanaged brains). gbrain config set generations.synthesis.retire_previous false stops automatic retirement.
gbrain repair generations --kind synthesis --mode cleanup --since 30d --json
gbrain repair generations --kind synthesis --mode cleanup --since <ISO-8601> --apply --expect <hash> --yes
gbrain repair generations --kind synthesis --mode restore --since 30d --json
The dream summary, the think synthesis page and the drift report publish as
single-page generations (--kind dream_summary, think_synthesis,
drift_report, key page:<slug>): a writer whose page changed while it
composed writes nothing and the edit stays, and every overwrite keeps the
earlier page, so --mode restore puts it back (gbrain restore <slug> reads
the same copy from page history).
gbrain repair generations --kind drift_report --mode restore --since 7d --json
Fence absent
A page written without its ## Facts (or takes) section keeps its rows: the
fact or take generation is held fence_absent and nothing is retired. Doctor
generation_held, gbrain sync status (fence_holds) and get_page
(fence_held) list the page with an ask-the-user fix. The user may have deleted
the whole section on purpose, or an edit may have lost it: ask which.
- To keep the rows, restore the section (from the page's history or the previous version of its file).
- To retire them, write the empty fence the fix prints into the page; the next write retires every row on it. For facts it is:
## Facts
<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
<!--- gbrain:facts:end -->
A page with no file changes through get_page (include_content: true) and
put_page with that revision as expected_revision; edit_page refuses to
write fence markers. Neither outcome is a default, and nothing changes until the
user chooses.
Private labels (over-stamped access: private)
Older writer templates stamped access: private on ordinary research and ops
pages, so remote callers other than the brain owner get not_found for them.
gbrain repair private-labels clears those labels in reviewed windows and can
put every one back. It is explicit-only and preview-bound, and nothing runs on
upgrade.
Say to your agent: "Preview which of my pages carry an over-stamped access: private label."
gbrain repair private-labels --source <id> --json # preview: one window, counts and a hash
gbrain repair private-labels --source <id> --apply --expect <preview_hash>
What it clears and what it keeps:
- Cleared:
access: privatewith novisibility(classalias: theaccesskey goes), andaccess: privatewithvisibility: private(classalias-and-visibility: both keys go). Nothing else on the page changes, andreadable_byand folder rules still apply. - Kept and counted: pinned questions; derived pages (atoms, pages with
derived_fromorsource_slug, synthesized concepts, life-chronicle events), whose privacy follows their origin;access: restrictedorconfidentialand anyconfidentialityvalue; an explicitvisibility: privatewith noaccess: private.
The preview lists one window of pages under a hash, with every class's count
before and after the window. It also counts, by category and without slugs, the
pages that the window would expose along with its own (details.dependents).
It judges each page by the same rules remote reads use, before and after the
window: derived_from pages, atoms whose origin is a listed page, synthesized
concepts built from such atoms, and life-chronicle events extracted from a
listed page. A warning names the counts when they aren't zero. To keep one of
those pages private, give it its own label before you apply. The preview hash
covers the pages it counted, so if a new page would be exposed by the time you
apply, the apply refuses with preview_changed and you preview again.
--apply --expect <preview_hash> applies exactly that window and checks each
page against its current revision and labels first. A page edited since the
preview reports changed_since_preview and is left alone. A bare --apply is
refused. On a brain without managed persistence the repair writes only the
database, so a page whose file sits in its source's checkout is held with
outcome file_backed. The next sync or re-import would put the label back from
the file, so edit the file's frontmatter, commit it, and run
gbrain sync --source <id>. Repo-less pages clear as usual. A clear or restore
changes only the label lines of the page's file and keeps its trust tier, and
gbrain's own database-only stamps never block it; a file that cannot take the
edit line by line is declined with label_edit_refused, as in
repair visibility; a
restore whose label value isn't a plain word is held as label_not_plain, so
add that label to the file by hand.
Windows and resume. --limit <n> sets the window size (default 1000, at
most 10000). When more pages remain past the window, the preview says so: apply
this window, then preview again for the next one. An apply that stops before
it's done (an interrupt, a time or capacity stop, a pending write or a failed
page) keeps its approved preview. Rerun the same --apply --expect command and
it resumes after the last applied page. You need a new preview only after the
window has been applied in full, or when the preview hash changed
(preview_changed).
Batches, declines and the exit code. On a brain with managed persistence the
apply admits a window's pages together, up to 64 at a time (fewer when the
writer's outstanding-request cap is low), and the owner
publishes them in groups of up to 8, instead of one page and one wait at a time.
Each page still has its own fate: a page whose write is declined fails alone and
the rest of its group lands. A decline is the page's own state refusing the
write: its file differs from the database or is gone (source_changed), its
body is stored in segments, or its file cannot take the label edit line by line
(label_edit_refused, which never
counts toward the systemic-failure stop, even on its first try). The page is left unchanged, the result counts it
under declined by reason, and when every failure of a complete run is a
decline the command exits 0, so a script working through windows carries on.
Any other failure, or a stop, still exits 1. The next preview lists pages an
earlier apply tried and that didn't change after every page not tried yet
(details.window.tried_before counts them), so they stop heading each window.
Clearing a declined page is a separate choice per page: see
file drift. Such a page declining again doesn't count toward the
run's systemic-failure stop (item_failures_systemic), so a window whose tail,
or whole listing, is carried declines completes; pages not tried yet that all
fail the same way, as a dirty checkout makes them, still stop the run.
A script that previews and applies windows in a loop should stop when every
listed page was tried before (details.window.tried_before equals
details.window.listed): what's left is pages that keep declining.
Upgrading from a release before 0.60.649.0. Those releases wrote an undo
ledger line only for a page write that landed, so a page that declined under
them has no record, and the first preview after the upgrade lists it like a
page not tried yet. If five or more such pages head the window, that apply
stops once with item_failures_systemic after its first batch, which is at
most one admission window (up to 64 pages, fewer when the writer's
outstanding-request cap is low). Nothing is written to the declined pages; the
pages of that batch after them that published stay published and are counted
in the result. Every page of the batch sent for writing got its intent line
first, so the next preview lists the declined ones last. Repeat the preview and
the apply: each round gets through at most one window of such pages, and a
window of only carried declines completes with exit 0.
An apply that meets a gbrain sources refresh waits for the refresh to
finish, for up to 10 minutes per step, instead of being refused after 10
seconds. A refresh that runs longer ends the apply with worktree_refreshing
(exit 1): the message names the refresh, its phase, how long it has run and how
long the apply waited. The pages already published stay published, each with its
undo line, the rest are unchanged, and rerunning the same
--apply --expect <hash> after the refresh resumes the window.
A brain without managed persistence (repo-less included) writes one page at a time, as before; the ordering, the exit code, the decline rule and the ledger fields below apply there too.
Git-canonical sources. Private pages there are database-only, so clearing
one commits it into the source's Git history for the first time. That class,
git-publish, is never in the default preview. Run it only by name:
gbrain repair private-labels --class git-publish. The commit is one-way:
restore re-adds the label and removes the file from the checkout, but every
earlier commit, and any remote it was pushed to, keeps the page's content.
Undo. Every change goes to an undo ledger at
~/.gbrain/repair/private-labels/<brain>.jsonl (under $GBRAIN_HOME/.gbrain/ if
set) on the host that ran it. Each page gets an intent line with the exact
removed values before its write and a committed line after it. A run that
stops between the two can still be undone. If the ledger can't take the intent
line, the apply refuses with storage_error and changes nothing. An apply
result names the ledger (details.ledger) and the lines it appended:
details.ledger_rows_written, split into details.ledger_rows.intent and
.committed. The file grows by exactly ledger_rows_written, and committed
equals applied unless a commit line could not be saved, which the item's
outcome then says.
gbrain repair private-labels --source <id> --class restore --json
gbrain repair private-labels --source <id> --class restore --apply --expect <preview_hash>
Restore re-adds only access and visibility: private from the ledger, and
only to pages that are still live and lack those keys. It counts restorable,
already_restored, page_gone and removed_after_restore (a page whose label
was removed by hand after a restore landed; it isn't listed again). A ledger
line with any other key, a non-string value or a page id that isn't an integer
is counted as unreadable and never applied. Run restore on the host and
GBRAIN_HOME that ran the clear, because the ledger lives there.
Open facts saved private before the world default
Facts saved before facts.default_visibility became world were stamped
private, so remote callers that are not the brain owner (a shared token, a
second agent) can't recall them, even on pages everyone may read. Nothing
opens them on upgrade. gbrain repair open-facts opens them when you, the
operator, decide to, from the CLI on the brain host:
gbrain repair open-facts --source <id> --created-before 2026-06-01T00:00:00Z --json # preview; writes nothing
gbrain repair open-facts --source <id> --created-before 2026-06-01T00:00:00Z --apply --expect <preview_hash>
--created-before is required: name the moment the default became world on
this brain, with its offset (a date alone, such as 2026-06-01, is read as
midnight UTC; the preview prints the cut it used), and facts saved after it
stay as they were written. The preview
lists one window of facts (--limit, default 1000; --after <id> previews
the next one), each with its class: fenced (a row of a page's ## Facts
table) or unfenced (a fact stored only in the database, held on a page).
Facts with no page, and facts from transcript lanes (conversation
extraction, capture hooks, connectors), are counted as unpaged:<lane> and
open only when you name that class, for example --class unpaged:mail:extract
(quote a lane that contains spaces).
--ids-file <file> (one fact id per line) narrows the set.
A fact someone saved private on purpose before the cut looks the same as a
legacy one, so it is opened with them. The preview says so and shows samples
and every listed fact; when some must stay private, put the ids you do want
opened in a file and pass --ids-file.
The preview also counts every fact it leaves private, by reason: expired,
superseded, lapsed (its valid_until has passed), member_page, withdrawn (forgotten or purged, at any
visibility), contested (an open trust proposal, or a widening the owner
rejected or undid), holding_page_private, holding_page_missing,
holding_page_quarantined, provenance_private, provenance_unresolved,
provenance_quarantined and entity_page_private. A page counts as private
the same way gbrain repair visibility judges it (its label, a privacy alias,
readable_by, a folder rule), across every row with that slug, deleted or
not, so the tighten repair never plans to close what this opened.
--apply --expect <hash> opens exactly the previewed window, keeping each
fact's id, provenance, creation time and trust tier; a fact that became
eligible inside the window since the preview refuses preview_changed. Each
write locks the pages the fact names and checks it again, so a page made
private while the apply waits keeps its facts private. A fenced row has its
table cell set to world by the same label-only write the other privacy
repairs use, in the table where it sits, above or below the timeline
sentinel. A fact the apply could not open is reported fact_left_private
with the reason, never as applied.
The command refuses remote callers and any CLI running under
GBRAIN_ENFORCED_MEMBER, and it never runs from gbrain repair --all,
gbrain doctor or the remediation plan.
Every change is written ahead to
~/.gbrain/repair/open-facts/<brain>.jsonl (under $GBRAIN_HOME/.gbrain/ if
set). To undo:
gbrain repair open-facts --source <id> --undo <ledger> --json
gbrain repair open-facts --source <id> --undo <ledger> --apply --expect <preview_hash>
Undo reads the ledger you name and refuses one that is missing
(undo_ledger_missing) or that records another brain
(undo_ledger_wrong_brain) or another source (undo_ledger_wrong_source).
It re-privates the facts the ledger opened that are still world and
unchanged, and counts the rest as skipped (expired, superseded,
changed, already_private, gone). A fact whose write confirmed after the
run stopped waiting has only its intent line; undo closes it too, unless it
was already world before that run (world_before_run) or an accepted trust
proposal widened it since (widened_by_proposal). It restores the label only: anything
a remote caller read while a fact was world stays read.
On a personal brain where every remote caller is you, you may not need this
at all: bind the client to the owner instead (gbrain access owner set, then
gbrain auth rescope --client <id> --member <owner>), and it reads private
facts without opening them to anyone else.
On a shared brain with several clients and no owner, gbrain auth rescope --token <name> --private-facts granted-sources (or --client <id>) is the
per-credential alternative to opening facts: that one credential reads every
private fact in the sources its grant lists by id, including facts saved
private on purpose, nobody else does, no fact changes, and --private-facts none switches it off on the next request. A source the credential only
reaches (federated, now or later, or through a future "read every shared
source" switch) never opens. It never reads a fact on a page this repair
would refuse to open, nor an unpaged:<lane> fact (no holding page, or a
transcript lane such as the conversation archive), which this repair opens
only by class (MCP administration).
Lost fence rows
A page rewrite that drops its ## Facts or takes section is safe on its
own: the section's rows stay live, held fence_absent, until you put the
section back or write an empty one. Before this release, a later remember,
takes add, fact extraction or gbrain facts relink on that page built a
new section holding only its own rows, and the next ordinary write (a tag, a
timeline entry, an append, a get and put) read that section as your answer:
the held facts expired and the held takes were deleted. Those writers now put
the held rows back into the section they create. gbrain repair lost-fence-rows brings back the rows an older gbrain already lost.
gbrain repair lost-fence-rows --json # preview; writes nothing
gbrain repair lost-fence-rows --source <id> --json # one source
gbrain repair lost-fence-rows --apply --expect <hash> --yes
A row is listed only when the records prove this shape: a facts or takes
generation retired it without an empty-section proof, no row with the same
claim is on the page now, and page history shows the row in a section that
then vanished before the retirement. A row you removed by editing a section
that stayed in place, a row retired by an explicit empty section, and a
forgotten fact are never listed, and neither is a row you re-added after the
loss and then removed again, or any row of a page where you wrote an empty
section after the loss. A section you rebuilt by hand without a row
leaves the same records as the bug, so read the preview with the user before
applying it. gbrain repair generations --mode restore
does not cover this case, because the retiring write published a fence that
parsed; this kind reads page history instead.
Each row comes back byte for byte from the newest page version that held it,
at its old row number when that number is free. The apply republishes each
page through one revision-bound page write that adds only those rows; a page
changed since the preview is skipped and asks for a new preview. A restored
fact is a new facts row (the expired row stays as history). A restored row
never gets more trust than it had: a fact comes back at the tier the expired
row had, and a take, or a fact with no recorded tier, at the lowest tier
(external_untrusted); the preview says which on each row. If the apply
stops because its page write is still pending, rerun the same apply command:
it finishes lowering the tiers.
It is explicit-only and nothing runs on upgrade: show the user the preview before running the apply.
Extractor facts
A managed write by a gbrain older than v0.60.11.0 to a conversation page
without a Facts fence expires all of that page's conversation-extractor facts
(expired_at set, row_num cleared), so recall stops returning them.
gbrain repair extractor-facts restores them. It is explicit-only and
preview-bound.
gbrain doctor # extractor_facts_expired
gbrain repair extractor-facts # preview: every candidate with its class
gbrain repair extractor-facts --apply --expect <hash>
gbrain doctor
Each candidate gets one class:
| Class | Meaning | Restored |
|---|---|---|
evidenced |
A committed write of the page completed in the same transaction that expired the fact (completed_at = expired_at), and its consumer was older than v0.60.11.0 (no version stamp, or an older one). |
By --apply --expect <hash> |
ambiguous |
Unmanaged brain (no receipts); no committed write at the exact expiry instant; the expiring write came from a fixed consumer (a fence row may legitimately have taken the fact's position); or the page has carried fence facts. | Only with --include-ambiguous and that preview's hash |
excluded:<reason> |
Page missing or deleted, superseded (superseded_by), withdrawn (forget), an active fact with the same text and entity already on the page, or an earlier candidate with the same text and entity. |
Never |
Ambiguous rows are restored as the hashed set; --limit is the only
narrowing. Run gbrain repair extractor-facts --include-ambiguous, review
the list, then gbrain repair extractor-facts --include-ambiguous --apply --expect <hash>.
The apply restores exactly the previewed set. A fact that changed since the
preview (edited, withdrawn, superseded, its page deleted or recreated)
reports changed_since_preview and stays expired; preview_changed means
the hash names no saved preview, the preview is older than 7 days, or the
apply's --source / --include-ambiguous differs from the preview's.
Restored facts get a fresh row number above the page's rows. Nothing is
written to any page or file. On a managed brain each page publishes one
database-only managed_maintenance_restore_extractor_facts request; a
rerun after a crash replays it and restores no new candidate.
Receipts are retained (compaction keeps completed_at), so a history older
than the 30-day receipt retention is still evidenced. Not recoverable
automatically: facts whose extractor batch was since replaced by a
re-extraction (the old rows are gone), and facts on unmanaged brains without
--include-ambiguous. On PGLite the same-transaction rule holds only to the
millisecond (PGLite's clock resolution).
The preview warns, naming the host, when a consumer older than v0.60.11.0
published writes after writer_version_cutoff: an old consumer expires
restored facts again. Upgrade and restart it first.
Unwithdrawn facts
Before this fix, a page write or an extract_facts run retired every fact row
attached to the page with a row number that the page's ## Facts fence did not
hold. That included rows that were never in the fence, such as facts a
put_page writer attached to the page, so a write that changed nothing in the
fence could expire them (expired_at set, row_num cleared, no
superseded_by). When that was the page's first facts-fence generation,
gbrain repair generations --kind fact_fence has no earlier generation to
return to. gbrain repair unwithdrawn-facts restores these rows from the
before-state the generation ledger recorded. It is explicit-only and
preview-bound. On an unmanaged brain, with or without a repository, the
extract_facts reconcile still treats a numbered row its fence lacks as drift
and would retire a restored row again, so the preview lists those candidates
as excluded:unmanaged_reconcile and restores none.
gbrain doctor # unwithdrawn_facts
gbrain repair unwithdrawn-facts # preview: every candidate with its class
gbrain repair unwithdrawn-facts --apply --expect <hash>
gbrain doctor
A candidate is a fact a facts-fence generation retired that is still exactly as the retirement left it: expired at that generation's instant, row number cleared, same claim and visibility, not superseded. Conversation-extractor facts are left to Extractor facts.
| Class | Meaning | Restored |
|---|---|---|
evidenced |
No fence of the page ever held the fact: no facts-fence generation recorded it, and neither the page nor any stored version of it carries it at the same row number, claim and visibility. | By --apply --expect <hash> |
ambiguous |
The page's version history has a gap (pruned versions, or an import that consumed several commits), or it has more stored versions than one preview reads, so an earlier fence holding the fact cannot be ruled out. | Only with --include-ambiguous and that preview's hash |
excluded:<reason> |
Page missing or deleted, superseded, withdrawn (forget, including a forget on the member or scope memory page it sits on), changed since the retirement, held by a fence (fence_held: an edit of the fence removed it, a genuine withdrawal), a claim the page's fence states (fence_states_claim), an active fact with the same text and entity already on the page at any visibility, another candidate with the same text and entity at the same or a narrower visibility (duplicate_candidate; a private copy comes back before a world one), or an unmanaged brain (unmanaged_reconcile). |
Never |
The preview binds each page's revision. If the page was written after the
preview, the apply restores nothing for it and reports
changed_since_preview; preview again. A fact that changed since the preview
reports changed_since_preview and stays expired. A restored fact keeps its id
and gets back its recorded expired_at (cleared), valid_until,
superseded_by and consolidation marks, at its recorded row number, or at a
fresh number above the page's rows when a fence row has taken it. No page or
file is written. Each page publishes one database-only
managed_maintenance_restore_unwithdrawn_facts request. Page writes and
managed extract_facts runs from this release on keep these rows active,
except a row whose claim the page's fence now states, which still retires.
Purged page facts
Before #8859 was fixed, purging a page (gbrain delete --purge, or the
retention purge of a page deleted more than 72 hours ago) left behind the
facts extracted from that page that were filed on no page: their context
named the page, but nothing tied them to it. They stayed active, so recall
kept returning claims from a page you had removed. Purges now take them;
gbrain repair purged-page-facts retires the ones older purges left.
gbrain doctor # purged_page_facts
gbrain repair purged-page-facts # preview: every candidate with its class
gbrain repair purged-page-facts --apply --expect <hash> --yes
gbrain repair purged-page-facts --include-ambiguous # also rows of pages gone with no purge record
A candidate is an active fact written by page extraction, filed on no page,
whose context starts with the slug of a page that no longer exists in its
source (not even as a deleted page, which a restore could bring back). A
slug with no / counts only when the purge ledger records it.
- evidenced: the purge ledger records a purge of that page after the fact was written. Retired by default.
- ambiguous: the page is gone with no purge record. A retention purge
leaves none, and neither does a rename that did not carry its facts, so
these are retired only with
--include-ambiguouson both the preview and the apply. - excluded (listed, never retired): the claim was withdrawn, the row is superseded, or another fact or an open loop references it.
The apply needs the preview's hash and your consent (--yes, or a terminal
prompt). It expires exactly the previewed rows that are still active,
unchanged and still without a page; anything else is reported as
changed_since_preview and kept, and a row that appeared after the preview
is never touched. Rows are expired, not deleted, so their history stays. The
repair writes no purge record, so the same claim could be saved again later. On a
managed brain each batch of up to 200 facts is one database-only
managed_maintenance_expire_purged_page_facts request. It works the same on
a repo-less brain: no page or file is written.
Purged change reasons
Before #8635 was fixed, a sync could read a page's gbrain-reason trailer
from Git, a fact purge could then run, and the sync would still save that
reason as the page version's change reason. So gbrain history could show a
reason quoting a claim you had purged. Syncs no longer do this;
gbrain repair purged-change-reasons finds and redacts the reasons saved
before the fix. Nothing runs it for you: not an upgrade, a sync or doctor.
gbrain repair purged-change-reasons # preview: a count for the brain and for each source
gbrain repair purged-change-reasons --apply --expect <hash> --yes
gbrain repair purged-change-reasons --include-ambiguous # also the same text under another path
When a purge finds a reason quoting the claim in a commit already in Git, it records that commit and file (with no text). For each such record, the repair reads the commit's reason for that file from the source's checkout again, exactly as sync reads it, and looks for page versions in that source whose change reason is that same text:
- evidenced: the version's file is that file. Redacted by default.
- path_mismatch: the same text on a version of another file, or on a
version with no file recorded, or a commit that gives the file more than one
reason (the purge may have matched the other one). Kept, and redacted only
with
--include-ambiguouson both the preview and the apply.
The preview never prints the reason text, only counts and items such as
source-a:notes/a@v42. It also counts unreadable_commit (the checkout is
gone or the commit can no longer be read; nothing is found for those) and
sources_without_checkout. A preview that finds 0 is only complete when
unreadable_commit is 0 too: run it on the brain host, where the checkouts
are. A repo-less source never stored a reason from Git, so it has nothing to
check and the preview still succeeds.
The apply needs the preview's hash and your consent (--yes, or a terminal
prompt). It reads the reasons from Git again, locks the source as a purge
does and sets exactly the previewed versions whose reason is still the same
text to [purged], the value a purge
writes; anything else is reported as changed_since_preview and kept. Pages,
files and Git history are not changed; a commit message keeps its text, as
after any purge. Running the preview again after the apply finds nothing.
Conversation labels
Before v0.60.69 the conversation parser read meeting-note labels such as
**Date:**, **Attendees:** and **Summary:** as speakers, so
gbrain extract-conversation-facts stored facts like "Date said the review is
on Monday", dated at 1970-01-01 when the page had no date. The parser is
fixed, but those pages stay marked complete, so an upgrade never re-extracts
them. gbrain repair conversation-labels retires those facts. It is
explicit-only, preview-bound and destructive (it needs the user's consent),
and it makes no model calls.
Say to your agent: "Doctor says some conversation facts came from
meeting-note labels. Show me which ones before removing anything." The agent
runs the preview, shows you the list and, after you agree, runs the printed
apply command with --yes.
gbrain doctor # conversation_label_facts
gbrain repair conversation-labels # preview: every candidate, per-page outcome, hash
gbrain repair conversation-labels --apply --expect <hash> --yes
gbrain extract-conversation-facts --source-id <id> --slugs <pages> --dry-run # printed by the preview
gbrain extract-conversation-facts --source-id <id> --slugs <pages> --max-cost-usd <n>
gbrain doctor
Candidates are active conversation-extractor facts on pages that carry a bold metadata label line. Each gets one class:
| Class | Meaning | Retired |
|---|---|---|
evidenced |
Its context names a segment 1970-01-01 window, which only the pre-fix parser wrote (the fixed one records an undated page as not extractable). |
By --apply --expect <hash> --yes |
ambiguous |
Any other fact of a label page: a post-fix transcript with a **Date:** header, a model-written context, a fact that legitimately mentions a label. Nothing on the row proves the misattribution. |
Only with --include-ambiguous and that preview's hash |
excluded:<reason> |
current_extractor (the page's outcome carries extractor_version, so the fixed parser extracted it), withdrawn, superseded, superseded_by_reference (another fact names it), open_loop_reference (an open loop points at it). |
Never |
The preview also gives each page its outcome:
| Outcome | What the apply does | Cost |
|---|---|---|
non_extractable |
Retires the facts, expires the completion marker and records the page as not extractable (prose notes, an undated page, a single email), as the fixed parser would. | $0 |
awaiting_reextraction |
Retires the facts and expires the completion marker; the page re-enters the ordinary extraction backlog. | The next extraction, under its own cap |
cleaned |
Retires the facts; the page had no completion marker. | $0 |
A per-fact apply outcome of changed_since_preview means the fact changed (it
was edited, withdrawn, superseded or already expired); it stays as it is.
There is no --reextract or --max-usd here: gbrain repair never spends.
The preview prints the hand-off, one dry run and one capped run per 50 pages
waiting for extraction:
gbrain extract-conversation-facts --source-id <id> --slugs <a,b,…> --dry-run,
then the same command with --max-cost-usd <n> (default $5 when omitted; the
opt-in cycle.conversation_facts_backfill also picks them up at $1 per run and
$5 in total). Nothing re-extracts automatically.
Retired facts are expired, not deleted: each keeps its id and gains
retired: conversation-labels <hash> in its context, recall stops returning
it, and a later extraction, its orphan cleanup and gbrain repair extractor-facts leave it alone. To bring a page's facts back, re-extract the
page with the commands above. Pages apply in batches of up to 25: on a
managed brain each batch publishes one database-only
managed_maintenance_conversation_label_retire request (one receipt for the
batch, each page rechecked on its own), and a rerun after a crash skips
batches whose request already committed. A non-interactive
apply without --yes exits 3 with the consent payload and changes nothing;
preview_changed means the hash names no saved preview, the preview is older
than 7 days, or the apply's --source or --include-ambiguous differs from
the preview's. Under a live gbrain serve on PGLite the command is refused at
once: stop the serve, run the repair, then restart the serve (the refusal's
fix names the steps).
Conversation outcomes now record the parser version (extractor_version=<n>
in the outcome row). Doctor conversation_outcomes_stale counts outcomes a
later parser version would reconsider; they are never reopened automatically.
Captured facts
Automatic capture (the writeback hook, the compaction harvest and the corpus
sweep) skips gbrain's own claude-cli model sessions and text you paste into a
conversation. Facts a gbrain older than v0.60.30.0 captured from them stay
active, so recall and hot memory keep returning them. gbrain repair captured-facts expires them. It is
explicit-only and preview-bound, and it runs on the brain host (it reads the
Claude Code session directory, the live and archived Codex session folders
and the session corpus there).
Say to your agent: "Doctor says some facts were captured from gbrain's own
sessions or from pasted text. Show me which ones before removing anything."
The agent runs gbrain repair captured-facts, shows you the list and, after
you agree, runs the printed apply command.
gbrain doctor # captured_facts_active
gbrain repair captured-facts # preview: every candidate with its class
gbrain repair captured-facts --apply --expect <hash>
gbrain doctor
| Class | Meaning | Expired |
|---|---|---|
evidenced |
The fact's session is one of gbrain's own claude-cli sessions: a harness transcript in a gbrain scratch project, or a corpus file gbrain doctor (self_capture) quarantined. |
By --apply --expect <hash> |
ambiguous |
A paste candidate: at least 60% of the fact's content words appear in the session's retained corpus file only inside pasted blocks. A heuristic, so it is listed in every preview but expired only on request. | Only with --include-ambiguous and that preview's hash |
excluded:legitimate_duplicate |
The same claim and entity also has an active fact from another lane or an unsuspected session, so the claim is legitimate. | Never |
Sessions that cannot be classified on this host (the harness transcript was
pruned, the corpus file is gone, or a corpus file or directory it could not
read) are counted as unclassifiable and kept. Each unreadable corpus file or
directory is listed as unreadable_corpus_file and counted in the
unreadable_corpus_files residual; fix its permissions and preview again.
captured_facts_active counts facts; the self_capture check counts corpus
files. Clear both: quarantine the files with the commands self_capture
prints, then expire the facts here.
The apply expires exactly the previewed set. A fact that changed since the
preview reports changed_since_preview and stays active. A fact with a row in
its entity page's ## Facts fence is struck in the page (one revision-bound
put_page per page, which re-embeds the page), so a later write of the page
cannot reactivate it; a fact with no fence row expires database-only (one
maintenance request per page on a managed brain). Nothing is withdrawn, so
gbrain remember can save the same claim again.
Agent-session facts
An orchestrator that launches headless worker sessions on your account (for
example claude -p workers) renders each worker's first message from a
template brief. Before #8064 the capture hooks banked those sessions as yours,
so the briefs were saved as your own preferences, beliefs and commitments, and
consolidate could promote them into takes held by you. New captures from such
sessions now carry a speaker sidecar and are attributed to the agent.
gbrain repair agent-session-facts fixes the facts already stored. It is
explicit-only, preview-bound and destructive, and it runs on the brain host (it
reads the session corpus there). It never deletes anything.
Say to your agent: "Doctor says some facts came from agent-launched
sessions. Show me which ones and which takes would be retired before changing
anything." The agent runs gbrain repair agent-session-facts, shows you the
list and, after you agree, runs the printed apply command.
gbrain doctor # agent_session_facts
gbrain repair agent-session-facts # preview: every candidate with its class, and the takes to retire
gbrain repair agent-session-facts --cwd /srv/agent-workers --session <session-id> --principal worker-a
gbrain repair agent-session-facts --apply --expect <hash> --yes
gbrain doctor
| Class | Meaning | Re-attributed |
|---|---|---|
evidenced |
The fact's session has a speaker sidecar (<session>.speaker.json in the corpus directory, its sourced/ spool or beside the session's corpus files), you named it with --session <id>, or its <session>.source.json records a working directory under a --cwd <prefix> you passed (compared on whole path segments after resolving symlinks). |
By --apply --expect <hash> --yes |
ambiguous |
The session's first message (spaces collapsed, lowercased, at least 40 characters) matches the first 160 characters of the first message of at least 3 other sessions that have no speaker sidecar: a template brief. A heuristic, so it is listed in every preview but applied only on request. | Only with --include-ambiguous and that preview's hash |
excluded:owner_also_said |
The same claim and entity also has an active fact attributed to you from a session that is not suspect, so you said it too. | Never |
Only active capture-lane facts (hook:writeback, hook:compact,
sweep:corpus) attributed to you or to nobody are candidates. Facts of a
session with no retained corpus file, sidecar or source record are counted as
unclassifiable and kept. --cwd and --session are repeatable; pass the
same flags to the apply (the printed apply command carries them).
The apply sets attributed_to to other and appends
speaker: agent <label>, not the owner to the fact's context. The label is the
sidecar's, else --principal <label>, else agent-launched. A fact with a row
in its page's ## Facts fence is rewritten in the page (one revision-bound
put_page per page); a fact with no fence row is rewritten database-only (one
maintenance request per page on a managed brain, one transaction otherwise).
Then each take of kind fact held by you that is still active and unresolved,
and whose every contributing fact is no longer yours, is retired: struck in its
page's takes fence when the page holds it, otherwise made inactive in the
database. The preview lists those as take_to_retire. A fact or take that
changed since the preview reports changed_since_preview and is kept; a fact
that already reads as the agent's with its speaker note (a resumed apply whose
accepted request committed meanwhile) reports reattributed. A page stored in
segments is read back whole, up to 24 MiB, and written back bound to that
revision; a larger page reports page_body_segmented and its facts and takes
are kept.
Redacted facts
Before the fix for #7125, fact extraction ran the prompt-injection patterns
over the text it stored, and one pattern matched the English word "system"
before a parenthesis. "Acme Business System (ABS)" was stored as "Acme
Business redacted", in the fact, its page's ## Facts fence, the
page's search chunks and its history, and trust scan flags the marker as
instruction-like. Extraction no longer rewrites stored text, and the pattern
now matches only a code call such as os.system("…"). gbrain repair redacted-facts restores the facts already damaged. It is explicit-only and
preview-bound, it runs on the brain host, and it never runs on upgrade.
Say to your agent: "Doctor says some facts lost words to a redaction
marker. Show me what you can restore before changing anything." The agent
runs gbrain repair redacted-facts, shows you each fact with its restored
text and, after you agree, runs the printed apply command.
gbrain doctor # facts_redaction_marker
gbrain repair redacted-facts # preview: every damaged fact with its class and restored text
gbrain repair redacted-facts --apply --expect <hash>
gbrain doctor
Each active fact whose text holds a redaction marker is checked against the pages it came from: the page its context names (the page or transcript the turn came from) and the page that holds it, as each reads now and in up to 50 retained versions. A text proves a restoration when the words around every marker in the fact occur there around exactly one span the marker's pattern matches. A page stored in segments is read as evidence up to 16 MiB.
| Class | Meaning | Restored |
|---|---|---|
evidenced |
Every text that proves a restoration proves the same one. | By --apply --expect <hash> |
ambiguous |
A text holds two different spans around the same words, or two texts prove different restorations. | Never; listed |
unproven |
No page it came from exists any more (no_source_page), or none still holds the words around the marker (not_in_source), or the fact's row number names no active row with its text in its page's ## Facts fence and it did not come from the conversation extractor (fence_row_missing; the listing shows the restored text). |
Never; listed |
segmented |
Proved, but the fact's row sits in the ## Facts fence of a page stored in segments, which this repair does not rewrite (segmented_page). The listing shows the restored text. |
Never; listed |
The apply restores exactly the previewed set. A fact that changed since the
preview reports changed_since_preview and keeps its text. A fact with a row
in its page's ## Facts fence has that row's claim rewritten in the page
(one revision-bound put_page per page, which re-chunks and re-embeds the
page); a fact with no row number, or a conversation-extractor fact whose
row number names no fence row (its page has no ## Facts fence), is
rewritten database-only, row number kept (one maintenance
request per page on a managed brain) and gets restored: redacted-facts repair appended to its context; its vector no longer matches its text, so
the next gbrain embed re-embeds it. Page history keeps the damaged
revisions. Edit an ambiguous, unproven or segmented fact by hand if you know
the missing word.
Loop facts
Closing a commitment loop (gbrain loops done, gbrain loops drop, or the
loops_close tool) retires its commitment fact.
A loop closed by a gbrain older than v0.60.32.0 while that retirement could
not commit (for example on a managed brain, where the write was refused but
the close still reported fact_expired: true) leaves the fact active, so
entity cards and recall keep the finished promise. gbrain repair loop-facts retires those facts. It is explicit-only and preview-bound.
Say to your agent: "Doctor says some closed loops still have an active
commitment. Preview retiring those facts, then apply after I agree." The agent
runs gbrain repair loop-facts and, after you agree, the printed apply command.
gbrain doctor # loop_facts_drift
gbrain repair loop-facts # preview: closed_loop_facts=N
gbrain repair loop-facts --apply --expect <hash>
gbrain doctor
Each candidate is a done or dropped loop whose commitment fact is active
and lives in the loop's own source. A fact that another open loop still
references is skipped (shared_with_open_loop); it is retired when the last
loop that uses it closes. The apply expires the fact and strikes its fence row
in one coordinated write, exactly for the previewed set; a loop or fact that
changed since the preview reports changed_since_preview and is kept. No
withdrawal is recorded, so the same promise made again is stored normally.
Ontology facts
From v0.60.53.0 until v0.60.104.0 the facts step of the maintenance run (the
gbrain serve sweep and the dream cycle) moved ontology observations
(ontology_propose) onto their entity page's ## Facts table: each took the
page as its source, and the next rewrite of the page that did not list it
retired it, so ontology_get stopped returning it (#6264). gbrain repair ontology-facts restores them. It is explicit-only and preview-bound.
Say to your agent: "Doctor says some ontology observations were moved onto
page tables. Preview restoring them, then apply after I agree." The agent runs
gbrain repair ontology-facts and, after you agree, the printed apply command.
gbrain doctor --only ontology_facts_fenced # fenced=N retired=N
gbrain repair ontology-facts # preview: one line per observation
gbrain repair ontology-facts --apply --expect <hash>
gbrain doctor --only ontology_facts_fenced
A candidate is an ontology row with a fence row number, or whose
source_markdown_slug differs from its source; ontology writes produce
neither. The preview classes each one fenced (still on the table) or
retired (a page write retired it), or excludes it: withdrawn (its claim
was forgotten), consolidated, or duplicate (the same observation was
proposed again after it went missing, so restoring it would make a second
copy). The apply gives each restorable row its own source back, takes it off
the table and clears its expiry, exactly for the previewed set; validity dates
and supersession links stay as they are. A row that changed since the preview
reports changed_since_preview and is kept. It writes the database only:
the line the old step added to the page's Facts table stays in the page as an
ordinary page fact. An observation whose source was already the page's own
slug and that a page write detached carries no trace of the move, so it is not
found.
Facts on an entity slug with no page
Before the B-7 resolver fix, an extractor that named an organization under
companies/acme-example missed the page orgs/acme-example, even when that
page listed acme example as an alias, and managed writes kept the invented
slug as the fact's entity (#6925). Those facts sit on an entity_slug no page
answers for, so entity recall and trajectories never find them. gbrain repair facts-rehome moves them to the page they name. It is explicit-only and
preview-bound, and it never runs on upgrade.
Say to your agent: "Some facts sit on entity slugs that have no page.
Preview moving them to their pages, then apply after I agree." The agent runs
gbrain repair facts-rehome and, after you agree, the printed apply command.
gbrain repair facts-rehome # preview: one line per page-less slug
gbrain repair facts-rehome --apply --expect <hash>
The preview lists every page-less entity_slug with its class. rehome: the
strict resolver reaches one live entity page by identity evidence (the exact
page, the same name under another organization directory, or a unique alias),
and the slug's database-only facts move there. ambiguous (more than one page
answers), unverified (only a bare-name guess answers), unresolved (no page
answers) and fence_owned (every fact is a row of a page's Facts table) are
listed and never moved. The apply moves exactly the previewed facts; a slug that
gained a page, lost its target or whose facts changed since the preview reports
changed_since_preview and is kept. A duplicate ontology observation already on
the target is merged rather than copied. It writes the database only; no page is
rewritten.
Facts of a strict source with no Git home
On a source whose pages are canonical in Git (canonical: git), every fact
should be a row in some page's Facts table, so that a database rebuilt from Git
keeps it. Facts saved before the source became strict, or by an older gbrain,
can still live in the database only: a fact for an entity that has no page, or a
fact with no entity. The doctor check strict_facts_outside_git counts them.
gbrain repair facts-home gives them a home in Git. It is explicit-only and
preview-bound, and it never runs on upgrade.
Say to your agent: "Doctor says some facts of my strict source are not in
Git. Preview giving them a home, then apply after I agree." The agent runs
gbrain repair facts-home --source <id> and, after you agree, the printed
apply command.
gbrain repair facts-home --source <id> # preview: one line per fact, by group
gbrain repair facts-home --source <id> --apply --expect <hash> # writes at most 500 facts per run
The preview puts each fact in one group:
| Group | What the apply does |
|---|---|
entity_page_missing |
Writes the fact as a held row that names its entity, one commit per holding page: memory/unattributed, or for an entity under a folder access rule its folder's holding page (<folder>/memory/unattributed, which the rule covers). Once the entity has a page, the next maintenance cycle moves it there. |
no_entity |
Writes the fact to memory/unattributed. |
entity_page_exists |
Nothing: the entity has a page, and the next maintenance cycle (gbrain dream) moves the fact into it. |
cannot_render |
Nothing: the Facts table cannot show the fact as it stands (the class says why). It stays in the database, active and searchable. |
folder_restricted |
Nothing: an exact page rule covers the entity (page_rule: create the entity's page, then the next maintenance cycle moves the fact into it), or this database role cannot read the access rules (access_unreadable). It stays in the database only. |
entity_page_deleted |
Nothing: the entity's page is deleted (it may have been private, and purging it would not reach a row on the holding page). Restore the page or purge it; the fact stays in the database only. |
held_fact_unmovable |
Nothing: a held row whose page cannot take it, with the reason. entity_ambiguous names the pages a bare name could mean; save the fact again with the page slug and forget the held one. |
held_over_30_days |
Nothing: a held row whose entity still has no page after 30 days, with the nearest existing page gbrain finds. |
fenced_page_missing |
Nothing: a row of a page that was deleted. Restore the page or purge it. |
ontology_observation |
Nothing: an ontology observation belongs to its entity's ontology and has no Facts row. |
The apply writes exactly the facts the preview listed. A hash that no longer
matches refuses with preview_changed and prints the preview to run again; a
fact that changed since the preview is kept and reported. Facts keep their ids,
provenance and embeddings. On a source that is not strict the preview lists
nothing and says why, because its database keeps such facts by design.
gbrain sources git-gap <id> shows how far it is from its commit.
Facts consolidation closed at their own effective time
Before this release, when two typed facts stated the same metric, unit and
period for the same effective time (an amount and its correction recorded on
one day, or one statement stored twice), the dream consolidate phase still
merged them: the take kept the higher-confidence statement and the other got
a valid_until equal to its own valid_from, a zero-length validity that
quietly marked a real fact superseded (#6023). The phase now leaves such a
cluster unchanged and reports it under details.same_instant_clusters with a
next step. gbrain repair consolidate-ties finds the facts an earlier run
closed this way and reopens them. It is explicit-only and preview-bound, and it
never runs on upgrade.
Say to your agent: "Preview the facts consolidation closed at their own
effective time, then reopen them after I agree." The agent runs
gbrain repair consolidate-ties and, after you agree, the printed apply command.
gbrain repair consolidate-ties # preview: one line per closed fact
gbrain repair consolidate-ties --apply --expect <hash>
A candidate is an active typed fact consolidated into a take whose
valid_until equals its valid_from, where another fact in the same take
states the same metric, unit and period at the same instant. The preview names
the fact, its tied partners and the take. The apply sets exactly the previewed
facts back to open validity (consolidation only touched facts that were
current) and keeps their consolidation mark; a fact that was expired, edited or
reopened since the preview reports changed_since_preview and is kept. The
take is not changed: if it holds the wrong statement, decide which one is
current and gbrain forget the other. It writes the database only; no page is
rewritten.
Duplicate facts
Before this release, the same claim could be stored many times: conversation
fact extraction saved a standing prompt or instruction again for every session
that repeated it, and recall returned every copy, so a few copies filled the
limit and pushed distinct facts out (#7043, reported by @mikez93). Recall,
the entity card and search saved_facts now collapse copies into one row
(with collapsed_count), and extraction no longer stores a claim an active
conversation fact of the same source already states. Copies stored before the
upgrade stay in the database until gbrain repair duplicate-facts retires
them. It is explicit-only and preview-bound, and it never runs on upgrade.
Say to your agent: "Preview the duplicate facts, then retire the copies
after I agree." The agent runs gbrain repair duplicate-facts and, after you
agree, the printed apply command.
gbrain repair duplicate-facts # preview: one line per group
gbrain repair duplicate-facts --include-cross-entity # also retire copies on other entities
gbrain repair duplicate-facts --apply --expect <hash> --yes
A group is the active facts of one source, visibility and speaker whose text
normalizes to the same fingerprint (the rule forget uses: case, punctuation
and runs of whitespace do not matter). The row in a page's Facts table is kept (the
oldest one if several are), else the oldest row; every other copy gets
expired_at and superseded_by pointing at it, so it leaves recall but is not
deleted or withdrawn, and the claim can be saved again. Groups whose copies all
sit on one entity are same_entity. Groups spread over several entities are
cross_entity: they are listed, and retired only with --include-cross-entity
(the kept row keeps its own entity). A copy that is a row of a page's Facts
table is struck in that page as superseded by #N through a revision-bound
page write when the kept row is in the same table; otherwise it is reported as
fence_kept_elsewhere and kept. A copy in the Facts table of a segmented page
is reported as segmented_page and kept, in the preview and in an apply that
finds the page segmented since. Near duplicates (different wording) are never
touched. A row that changed since the preview reports changed_since_preview
and is kept. To keep the backfill from extracting one source at all, set
gbrain config set cycle.conversation_facts_backfill.exclude_sources '["source-a"]'.
Facts dated with the day a bulk load ran
A bulk import that writes the day it ran into every facts-fence row's
valid_from cell makes those facts look as if they all happened that day, so
timelines and as-of reads put them on one date. Those dates record when the
facts were loaded, not when they happened (#7247). Doctor fact_bulk_dates
warns when one UTC calendar day holds 200 or more of a source's active facts,
at least a quarter of them, across 20 or more entities. It reports each such
day with its fact and entity counts, the most frequent source tags, and how
many of those claims state exactly one earlier ISO date of their own ("Acme
Example closed a seed round on 2025-03-14"). A remote caller sees only its
permitted sources. gbrain repair fact-claim-dates moves those facts to the
date their claim states. It is explicit-only, preview-bound and destructive,
and it never runs on upgrade.
Say to your agent: "Preview which bulk-dated facts can take the date their claim states, then move them after I agree." The agent runs the preview and, after you agree, the printed apply command.
gbrain doctor --only fact_bulk_dates # the loaded days per source
gbrain repair fact-claim-dates --source <id> # preview: one line per page, residual counts
gbrain repair fact-claim-dates --source <id> --day 2026-01-15 # preview a loaded day the rule does not detect
gbrain repair fact-claim-dates --source <id> --apply --expect <hash> --yes
A candidate is an active fact whose valid_from falls on a loaded day and
whose claim holds exactly one YYYY-MM-DD date, a real calendar date from
1900 up to the day before. Facts with no date (no_date), several dates
(several_dates), or one out of range (date_not_earlier) keep the load
day and are counted, and so is a fact whose valid_until falls before its
claim's date (ends_before_claim_date).
A fact held by a page's facts fence is moved in the page: only that row's
valid_from cell changes, and the page is published through a revision-bound
put_page, so on a managed brain the canonical file changes and the facts row
is re-projected from it. A page is listed and kept when its fence does not
parse (unparsed, preview gbrain repair fences), it has a fence on both
sides of the timeline sentinel (split_fences, run gbrain repair split-facts first), it is stored in segments (segmented_page), or the
rewritten fence would not read back as exactly the planned rows
(not_conserved). A row whose cell no longer reads the loaded day is
fence_mismatch. A fact with no fence row is updated in place on an unmanaged
brain; on a managed brain it is counted database_only_managed and kept.
The hash covers each page's revision, row numbers and new dates. The apply
recomputes the plan first and refuses preview_changed when anything moved,
then changes exactly the previewed rows; a page edited during the run reports
changed_since_preview and is kept. A second preview lists nothing. On a
managed brain git revert of the repair commit undoes it, and page history
keeps the earlier revision.
Failed writes
Two kinds of refusal leave a caller's write with a receipt but nothing landed.
On a managed brain whose tags, timeline_entries or takes table has a
source_id column gbrain does not create, the managed writer guard of a
gbrain older than v0.60.38.0 refuses writes it should allow. And a write ends
conflict with source_changed when the page's canonical file and database
copy differed at publication, as every write did on a brain whose v0.13.1
grandfather validate: false stamp lived only in the database (#6429, fixed
in v0.60.157.0: that stamp is no longer read as a file edit). Each refused
write keeps a receipt with its full intent until a later request writes,
removes or repeats it: receipt compaction skips such a refused caller write
however old it is, and gbrain repair receipt-compaction --include-failures
is the explicit way to drop one. gbrain repair failed-writes submits those writes again. It is explicit-only and
preview-bound, and needs v0.60.38.0 or later (gbrain doctor --json reports
schema version 197 or later). Doctor's lost_caller_writes counts the
retained refused writes that may be replayable, per source, and names this
preview; the preview decides which ones it replays. Doctor leaves out (and
lists under details.not_replayable) the two classes it can decide from the
receipt alone: an unpinned remember (unpinned_target) and a put_page
whose page changed after the revision the caller read (revision_superseded, which
the preview classes superseded). The
preview changes no page content, but it records an approval checkpoint for its
replay set, which --apply --expect <hash> reads. The preview reads the write
journal in a few set reads whatever the number of refused writes (#8707); a read
the database ends at its statement timeout stops it with
repair_preview_timeout and a fix,
nothing saved.
Say to your agent: "Preview which refused writes gbrain can replay, show
me the list, then apply after I agree." The agent runs gbrain repair failed-writes and, after you agree, the printed apply command.
gbrain repair failed-writes --source <id> # preview: every refused write with its class
gbrain repair failed-writes --source <id> --apply --expect <hash>
gbrain repair failed-writes --source <id> # replayed writes now read already_written
Candidates are failed receipts refused by the guard (writer_coordinator_required,
or storage_error "Publication failed (P0001)" from releases that did not keep
the guard's message) and conflict receipts refused source_changed at
publication. The preview also lists a fact extraction (extract_facts) refused
revision_conflict because another write moved, replaced or deleted its entity
page, as a producer_owned row. Only writes a caller made directly are replayed:
put_page, add_timeline_entry and remember. The preview gives every
candidate one class:
| Class | Meaning | What happens |
|---|---|---|
replay |
No later write supersedes it. | Replayed on apply. |
already_written |
A later request with the same intent committed, or an earlier apply replayed it. | Kept. |
duplicate |
A later request with the same intent exists; that one is the candidate. | Kept. |
superseded |
A later write or delete of the page committed or is pending; for put_page, also a later failed put_page (newer content) or a page changed since the caller read it. |
Kept; re-issue by hand if still wanted. |
unpinned_target |
A remember saved unattributed; replaying would infer its subject again and could pick another page. |
Kept. Re-issue it with an explicit entity if it is still wanted. |
file_database_drift |
Its last replay hit source_changed and the file still differs from the database. |
Kept until the file matches again (a reconcile that writes only the file counts) or the page changes; reconcile it first. |
producer_owned |
gbrain produced it (sync or file import, reconcile, relink, maintenance page, job), or it is a caller's forget, which is not replayed. |
Kept. The preview prints the command that produces it again from current content (sync: gbrain sync --source <id> --no-pull). A refused forget says resubmit:: nothing produces it again, so read the fact and submit the forget again with a new request_id if it is still wanted. A refused fact extraction (extract_facts, including one refused revision_conflict because another write moved, replaced or deleted its entity page) keeps its extracted facts: when its page write's facts-absorb job is dead and can recover them, the row says recover: gbrain facts retry-dead --reset 'facts-absorb:write:<id>' (the retried job re-admits the retained facts at the page's current revision without a model call); while that job still runs it says pending:; otherwise (the extraction has no page write or its job completed or is gone, the entity page was replaced, the page was written again since or the job would skip its page write for another reason, the follow-up batches were refused as well, or the extraction also holds refusals of another kind, such as a sibling refused for a held file) it says re-extract: with the extract_facts call to make (one model call), or not recoverable: when the entity page of a page write's extraction was deleted. A fact request a later request of the same extraction committed is not listed. |
The apply replays exactly the previewed set. Each write is classified again
and its original caller's authority is checked again first: a write that
changed class since the preview reports changed_since_preview, and one whose
caller lost its grant or whose source was re-created reports
authority_revoked; both are kept. A replay goes through the operation's
normal path on the original caller's trust lane and under its stored authority:
the same writer (an OAuth client stays that client), delegation, scopes,
take-holder and delegated namespace limits and link trust, for the same source
incarnation, checked against the live grant at admission and again at
publication. A write an agent sent over MCP is prepared as a remote write
again, so it can do no more than the original could; a grant revoked or
narrowed between admission and publication refuses the replay at publication.
A subagent or restricted-namespace write gets back the identity it recorded
(the job id of an OAuth-delegated job, or the wiki/agents/<id>/ namespace of
a legacy subagent, which stays database-only); one that recorded neither is
confined to exactly its stored namespace allow-list. Live subagent dispatches
without a job id are still refused. A put_page
replay is bound to the page revision the preview saw (an original force: true
is dropped), so a page changed since the preview reports changed_since_preview
or conflict instead of being overwritten. A remember replay targets the
subject the original resolved. Each replay uses a new request id derived from
the failed one, so a rerun after a crash resumes the same request and a second
apply never writes it twice (pending_elsewhere when another writer holds that
request). Attribution names the original writer. A replay the
brain refuses reports refused with the code. The failed receipts stay as
history.
Since #6693 a remember refused because its page's file held a committed Git
change sync had not imported (pending_import) or was held by sync
(sync_held) is not left for this preview alone: after every managed sync the
same replay runs by itself for those remembers whose page now matches its file
(at most 50 per sync and 30 s; the sync result's replayedRemembers and one
stderr line count them). A replay keeps the fact's original valid_from and
expiry. put_page and add_timeline_entry refusals are only replayed here,
after you preview them. Receipts refused before this release are not replayed
automatically; this preview lists them.
Split facts
A page whose ## Facts fence lived below the timeline sentinel got a second
fence above the sentinel from managed remember and extract_facts writes
before this release (#6686). Writers now edit a lone timeline fence where it
is, and extract_facts reconciles it there, but a page that is already split
keeps two fences: extract_facts leaves its index as it is and warns
FACTS_FENCE_BELOW_SENTINEL naming this repair. gbrain repair split-facts
merges them. It is explicit-only and preview-bound and never runs from
--all, doctor's remediation plan, the maintenance cycle or an upgrade.
Say to your agent: "Preview which pages have split facts fences, show me the list, then merge them after I agree."
gbrain repair split-facts --source <id> # preview: merge / row_collision / unparsed / not_conserved
gbrain repair split-facts --source <id> --apply --expect <hash> # merges exactly the previewed pages
The merged fence stays below the sentinel and holds every row of both fences
under its own row number, so each fact keeps its id; the body fence goes, with
the ## Facts heading above it when that heading holds nothing else. A page is
kept and listed when a fence does not parse cleanly (unparsed: preview
gbrain repair fences), when a row number appears in both fences
(row_collision: edit the page so each number appears once, then preview
again), or when the merged page would not read back exactly
(not_conserved: merge by hand). Each merge is a revision-bound put_page;
a page changed since the preview reports changed_since_preview and is kept.
Undo a merge on a managed source with git revert of its commit.
URL clone fences
A source added with gbrain sources add <id> --url <git-url> is a clone gbrain
owns and updates with git pull --ff-only. Before this release, remember,
extract_facts and page writes on an unmanaged brain wrote ## Facts fence
rows and page files into that clone (#6946). The local change blocks every pull
that touches the same file, so the clone stops following upstream. Current
releases keep those writes database-only: a fact about a clone page is stored
and recalled from the database with no fence row (row_num empty), and page
write-through reports skipped: "url_clone". A managed brain does the same
with gbrain sources mirror-readonly <id>.
Local commits made in an owned clone are different: gbrain sources git-reconcile (autopilot, each tick) publishes them after a secret scan. gbrain config set sources.refresh_publish_diverged false (every source) or gbrain sources set-sync <id> off (one source) keeps them local.
A clone an older release already dirtied still blocks its pulls. gbrain sync --source <id> then prints pull_blocked_local_changes with the changed files
and an ask_user fix naming this repair (the sync JSON reason stays
pull_failed; the cycle's sync phase carries the code in pull_blocked).
Say to your agent: "Preview which files of the clone gbrain changed, show me the list, then restore them after I agree."
gbrain repair url-clone-fences --source <id> # preview: fence_rows_only / refused classes
gbrain repair url-clone-fences --source <id> --apply --expect <hash> --yes # restores exactly the previewed files
gbrain sync --source <id> # pulls again
The preview lists every tracked file that differs from HEAD and proves the
difference is only fence rows gbrain appended: both fences parse, HEAD's rows
are an unchanged prefix of the working copy's, and re-rendering HEAD with the
working fence reproduces the file byte for byte. Any other difference is
named with its class (non_fence_edit, unparsed_fence, staged_change,
deleted, not_in_head, unreadable_checkout) and the file is left alone; resolve it in the clone (keep
the edit upstream, or discard it with git checkout -- <path>), then preview
again. A file whose HEAD bytes would not import as its page is listed under the
hold's code (visibility_noncanonical for a Visibility: private that page privacy
does not read): apply keeps its rows database-only and restores the file from
HEAD so the clone can pull the upstream fix, but does not import HEAD, reports
held with the code and leaves the page at its last imported version. The
restored file equals HEAD, so sync does not screen it again and records no
hold; the page changes once an upstream fix is pulled and synced (#7897). Such
a file is an apply item, not a residual (#7910). Each restored file is first backed up under
~/.gbrain/backups/url-clone-fences/. Its rows stay active and recallable as
database-only facts, HEAD's bytes are imported as the page (as sync would
import them, except for a held file above), and only then is the file restored; each step is idempotent, so
a stopped run previews the same file again. A file that changed since the preview
reports changed_since_preview and is kept. The hash is bound to the --source
selection, each source's incarnation and clone root, and each file's page: an
apply with another --source, or after gbrain sources set-path moved the
source or it was removed and added again under the same id, refuses
preview_changed and writes nothing, and so does a file with a change staged
since the preview. Preview again and approve the new hash. Undo by copying the backup over
the file. It is explicit-only and never runs from --all, doctor's
remediation plan, the maintenance cycle or an upgrade.
URL source origin
A URL source a remote caller (an MCP client) adds records that on its row, and
every later reclone of it, managed or not, clones with git-lfs downloads and
hooks off; a URL source the local operator adds records that too, so doctor
never asks about it. URL sources added before that record existed carry none, and nothing
stored tells a remote caller's add from the local operator's: both wrote the
same row and cloned into the default clone directory ($GBRAIN_HOME/clones/<id>).
Their reclones use the clone settings of a local add. Doctor
url_source_origin (read-only, warn) lists them and says it cannot tell who
added them. A clone outside the default directory is not listed: only the local
CLI can choose that directory. A brain with no URL sources, such as a fresh
keyless brain, has nothing to list.
Say to your agent: "Show me the URL sources gbrain can't place, and record the ones I say a remote caller added."
gbrain doctor --only url_source_origin --json # lists the sources, asks who added them
gbrain sources record-origin <id>... --remote # preview: would_record / refused, writes nothing
gbrain sources record-origin <id>... --remote --apply # records the ids the user named
gbrain sources record-origin <id>... --local --apply # records the rest as local adds
--remote writes the same record a remote add writes, so every later reclone
clones with git-lfs downloads and hooks off, and it turns the same settings on
in the existing checkout's own .git/config now (lfs.fetchexclude=*,
core.hooksPath=/dev/null, lfs.locksverify=false). That is the safer of the
two choices: a reclone happens only when a checkout is lost or replaced, so
without it the checkout would keep fetching git-lfs objects from the endpoint
its repository names, and keep running hooks, while doctor already reads
green. The settings go into the repository's shared config (the one
git rev-parse --git-common-dir names, so a linked worktree gets them too),
and the command then reads back the values Git uses in the checkout: when a
worktree-scoped or included setting still overrides one, it refuses
write_failed, names the key, and says the settings were already written.
A source already recorded as remote whose checkout lacks the lock-down (one
recorded before this) gets it on --remote --apply and reports recorded,
even when its files now use git-lfs (no lfs_tracked refusal for it; only a
checkout Git cannot place refuses it, as lfs_unknown); one that has it stays
already_recorded, and the record is never removed. Each setting's existing values are removed before it is written, so a key that
already holds several values ends with the one clone-time value. The settings
are written to a copy held as Git's config.lock and renamed over the config in
one step, so a failure part way leaves the config as it was (a config.lock
another Git process holds refuses write_failed).
Only .git/config changes, never a tracked file; a gbrain frontmatter
hook wired through core.hooksPath stops running there, as on any clone a
remote caller adds. --local records a local add and changes no checkout, and
doctor stops listing either. Each apply re-reads the source inside one
transaction and refuses source_changed if it moved since the check. On a
managed brain it first takes the worktree locks and rows a reclone takes, so
no reclone runs between the record and the clone; while a reclone, refresh or
write holds them the id is refused source_busy (nothing changed, unless
the reason says the checkout already got the lock-down; run it again once
that process or refresh has finished). A write that fails is reported for its own id as
write_failed, saying whether the checkout already got all or part of the
lock-down, and the other ids keep their results. Without git-lfs files a
clone with these settings holds the same tracked bytes, so the stored writer
manifest needs no change and the reclone verifies as before. --remote
refuses, writing nothing:
lfs_tracked: the checkout tracks files with git-lfs (a tracked path withfilter=lfs), or a committed.gitattributesdeclares an LFS filter (a rule namingfilter=lfs, even one that matches no file yet; comment lines do not count). A reclone gets only the committed attributes, so clone-local ones do not count either. An apply inspects the checkout again under its locks before it writes. A clone with git-lfs downloads off holds pointer files where this checkout holds their content, so its next reclone would stop atwriter_manifest_mismatch, and converting the checkout rewrites its files, which this command does not do. If the source should not keep those files, check that nothing in its checkout is unpushed or only local, then remove it withgbrain sources remove <id> --confirm-destructive.lfs_unknown: gbrain cannot confirm the checkout has no git-lfs files (for a source already recorded as remote, cannot reach it to turn them off), and the reason names which cause applies: the checkout is missing (restore it, then run this again); the clone directory is not the top level of its own Git repository, because Git resolves it to an enclosing repository or to none (check what the directory holds); Git refuses the checkout because another user owns it (safe.directory); or Git could not list or read it (for example a corrupt.git). A clone of an empty repository (no commit yet) has no committed attributes, so it is not refused.custom_clone_dir: the clone sits where only the local CLI can clone.recorded_remote(--local): the source is already recorded as a remote add; this command never removes that record.
It runs only from the trusted local CLI on the brain host; no MCP operation reaches it, and nothing records an origin on upgrade.
File drift
A page whose canonical file differs from its database copy refuses every
coordinated write with source_changed (detail file_database_drift) until
someone resolves it. Before #6643 nothing resolved them in bulk, and
synthesize_concepts paid for a new narrative for each drifted concept on
every cycle, then left another conflict receipt behind. Now maintenance checks
the file before it spends or admits anything: a drifted concept is skipped
(recorded in dream.concepts.drift_skips, released once the file and database
agree), and a maintenance write to a drifted page refuses before admission
without a request row. Doctor's maintenance_write_drift counts the drifted
pages and the skips.
gbrain repair file-drift resolves them through the same canonical
reconciliation as gbrain sources reconcile, preferring one side. It is
explicit-only, preview-bound and runs only from the trusted local CLI on the
canonical owner host.
Say to your agent: "List the pages whose writes keep refusing source_changed, preview resolving them with the file winning, show me the exceptions, then apply after I agree."
gbrain sources reconcile <id> --brain host --audit --conflicts # read-only: receipts per slug, still drifted?, class
gbrain repair file-drift --source <id> --slug notes/a --prefer file # preview one page
gbrain repair file-drift --source <id> --all-drifted --class structurally_additive --prefer file
gbrain repair file-drift --source <id> --all-drifted --class structurally_additive --prefer file --apply --expect <hash>
gbrain repair file-drift --source <id> --all-drifted --only 'concepts/**' --prefer database # preview every drifted page filed under concepts/
gbrain repair file-drift --source <id> --all-drifted --since 7d --prefer database # only pages that drifted in the last 7 days
Select pages with --slug (repeatable), --request <id> (a conflict receipt,
repeatable) or --all-drifted (every page the conflict audit still finds
drifted, up to 1,000). --prefer file takes the canonical file, --prefer database the database copy. The preferred side wins the title, type, body,
timeline and ordinary frontmatter (a key only the other side has is dropped)
inside reconcile's existing protections: protected metadata (provenance,
trust, source and scan fields) stays as the database holds it, tags are the
union of both sides, and protected takes and private fact rows are kept as
stored. Each page's preview lists exceptions, the places where the result
differs from the preferred side and why (protected_metadata, scan_state,
tags_union, protected_takes_or_private_facts). Pages stored in segments
(pages.segmented_storage) resolve the same way and stay segmented. A page
the apply would refuse is listed refused in the preview, and every refused
row or apply outcome prints its next step as fix: (with its consent), or a
read-only preview of that page alone when the refusal names none.
--only <path> and --skip <path> (both repeatable) narrow any selection by
the page's canonical file path, relative to the source. A value with no *
is an exact path (concepts/agi.md selects that file only), as --only is for
frontmatter, fences and slug-conflicts. Globs work on file-drift only:
* matches within one path segment (concepts/* is every file directly under
concepts/) and ** matches across segments (concepts/** is everything under
it, at any depth); the other kinds' --only takes exact paths. A page is
selected when it matches some --only (or there is none) and no --skip.
They match the file path, not the slug: --only concepts/agi selects
nothing, --only concepts/agi.md selects the page. The pages they leave out
are counted as not_selected, the mixed-class check and the 1,000-page bound
run on the selected pages only, and the globs are bound into the preview hash
and printed in the apply command, so running that exact command applies
exactly the previewed pages (an apply under other globs refuses
preview_changed). Quote a glob so the shell does not expand it.
--since <ISO-8601 | age> narrows --all-drifted to the pages whose newest
drift receipt was recorded at or after that instant (#6712 PR 2). An age
(90s, 30m, 12h, 7d) is converted to one concrete UTC instant when the
command runs, and the preview hash and the printed apply command carry that
instant, not the age, so the apply selects the same pages the preview did.
Any other value refuses before anything is read. --since with --slug or
--request refuses: it only narrows --all-drifted. The fix that
gbrain sources writer failures prints for a group of drift receipts already
carries --since with the oldest receipt's time. One parser serves this flag
and gbrain agent logs --since.
--keep belongs to stuck-recovery; file-drift refuses it and names the
equivalent: --prefer database keeps the database copy, --prefer file
keeps the file.
A database-wins repair never silently discards a newer file change (GST-2579).
Before this release, --prefer database (by --held, --all-drifted or
--slug) and a gbrain sources reconcile apply that took the database copy
wrote the page over its file even when the file held another writer's commit
that sync had not imported yet, and the preview said "exactly the preferred
side". Now a database-wins write goes ahead only when the database itself held
the version the file's bytes record: the bytes the page's last import read or left
on disk (sync's import record, including a blob a sync adopted into it), or bytes a Git effect of one of the page's own
writes put in the file for a revision the page has held (its live revision or one
in its version history). So a database edit made after the file's last commit
still wins, shorter or not. Anything else is a change the database never held,
whoever committed it: another writer's commit, an uncommitted edit, gbrain's own
writer commit of a revision whose database row never landed, or a page with no
import record and no write of its own.
| Selection | A newer file edit | A commit that deleted the file (file_gone) |
|---|---|---|
--held, --all-drifted, --request |
listed kept_newer_file, nothing written, the hold stays |
listed kept_newer_delete, nothing written, the hold stays |
--slug <slug> |
approved; the listing, details.pages[].discards, the warnings and the consent name the commit (sha, author, date), or say the edit is uncommitted |
approved; the same places name the deleting commit |
Every gbrain repair file-drift apply now needs the user's consent: run the
printed apply without --yes and it exits 3 with the consent message, which
lists each newer change the database copy overwrites and each file a
tombstone_edited or purged_differs --prefer database apply removes; add
--yes only after the user agrees. gbrain sources reconcile (and MCP
writer_reconcile_preview / writer_reconcile_apply) refuses
source_changed (detail unimported_file_edit) when a decision takes the
database copy over what such a file says (take_database, delete or
set_value); decide take_file for those paths, or preview the page alone with
--slug as above. That covers an unbound collision too (a page an unbound
write left database-only, and a different file at its slug path): --slug <slug> --prefer database reads it as drift, names the file's commit, asks for
consent and records the file as the page's origin. A never_committed file_gone page resolved
--prefer database writes no file, so it is unaffected. The keep_db policy is
unchanged.
Finding earlier overwrites (read-only). Every reconcile apply, a
file-drift page included, first keeps a private backup of both sides at
~/.gbrain/reconciliation-previews/<request_id>.<digest>.json
($GBRAIN_HOME/.gbrain/… when GBRAIN_HOME is set), mode 0600, with
retention: pre_admission_or_terminal. Nothing prunes it: it stays until
gbrain sources reconcile <source> <slug> --remove-backup <ref> removes it once
its request has finished (--backups lists a page's). preview.preimages.file_base64
holds the file bytes the apply replaced. To list database-wins applies and check
whether the replaced bytes came from a commit gbrain never imported:
dir="${GBRAIN_HOME:-$HOME}/.gbrain/reconciliation-previews"
jq -r 'select(any(.preview.decisions[]; .action != "take_file"))
| [.request_id, .preview.preconditions.source_id, .preview.preconditions.slug, .preview.preconditions.relative_path, .preview.preconditions.assessment_at] | @tsv' "$dir"/*.json
# For one listed backup: the blob of the bytes it replaced, and the commit that introduced that blob.
jq -r .preview.preimages.file_base64 "$dir/<backup>.json" | base64 -d | git -C <checkout> hash-object --no-filters --stdin
git -C <checkout> log --all --find-object=<blob> --format='%H %an %aI %s'
A commit there that gbrain did not write is an edit the repair overwrote;
git -C <checkout> show <commit>:<path> (or the decoded backup) recovers it.
A page whose canonical file is gone (#6712). A page selected with
--slug or --request whose recorded canonical file is missing is resolved
by where the deletion stands in Git:
| The file is | Route | --prefer database |
--prefer file |
|---|---|---|---|
| deleted in the worktree but still committed at HEAD (staged or not) | Not file drift: commit the deletion (sync then imports it), or remove the page with gbrain repair ghost-pages (its own valve and consent). To keep the page, restore the file from Git and sync. The file-drift preview lists it deletion_uncommitted and resolves nothing. |
— | — |
| gone from the last commit (a committed deletion sync held because the page changed, or a checkout with no commit) | gbrain repair file-drift --source <id> --slug <slug> --prefer database|file |
Recreates the canonical file from the page through the reconcile apply; the page is unchanged. Git durability commits the file; when it is off the preview warns, and you commit the file yourself, or the next sync imports the committed deletion again | Soft-deletes exactly that page (purged after 72 h; gbrain restore <slug> --force undoes it until then) |
Both are preview-first and bound to the page revision and the observed
absence: a file that reappears, or a page that moves, between preview and
apply is changed_since_preview and nothing is written. Soft deletes honor
the sync mass-delete valve (more than half of a source's file-backed pages
refuses ghost_mass_delete_refused
unless GBRAIN_ALLOW_MASS_RECONCILE=1). gbrain sources reconcile --preview on
such a page refuses and names the same route, and a held deletion's next step
in gbrain sources status is the --prefer database preview. --all-drifted
does not select missing files: it lists each one as unknown
(unknown_canonical_file_missing), to preview alone with --slug.
Pages the live check cannot classify (#6991). A conflicted page whose
live file/database comparison returns no verdict (this host is not the
source's active canonical owner, the page or its canonical file is gone, or
the check refused or failed) is never repaired and never counted as clean.
--all-drifted and the bare gbrain repair file-drift survey list it with
class unknown, count it as unknown_<reason>, and say what to do for that
reason (run on the owner host, decide the content by hand, preview it alone
with --slug, or rerun the conflict audit). No --class preview command is
printed for unknown pages.
Held drift, one Decision at a time (#6712). A managed sync holds a
two-sided change as file_drift with a side (both: the file and the page
both changed since the last import; unknown: the page has no import record
to tell; deleted: one side is a deletion) and, for a deleted side, a
state: tombstone_edited (the page was deleted and the file was edited),
purged_differs (a purged page's file differs from what was purged) or
file_gone (the file was deleted and the page changed). gbrain sources status <id> --json lists each held file with both. --held selects those holds:
gbrain repair file-drift --source <id> --held --side both --prefer file # preview
gbrain repair file-drift --source <id> --held --side deleted --state tombstone_edited --prefer database
gbrain repair file-drift --source <id> --held --side both --prefer file --apply --expect <hash>
One preview resolves one Decision, so a selection that spans several sides or
deleted states refuses file_drift_mixed_selection,
and a deleted side refuses without --state
(file_drift_state_required):
the two --prefer values do opposite things in each state. Those two refusals
apply to a --prefer preview only.
Compare before you pick a side (GST-2568). Any selection (--slug,
--request, --all-drifted or --held, with its narrowing flags) without
--prefer compares each page with its file and writes nothing. Each page
lists what differs (frontmatter with the keys, body, both, or none
once gbrain's own normalisation is read), which side is newer (the file's last
commit time at HEAD against the page's updated_at; unknown when the file
has uncommitted bytes or a time is missing) and what a repair would do:
release_hold or no_drift (they agree), prefer_file (the file was
committed after the page last changed, so the file side is the repair),
needs_human (the page is newer, a page whose file is gone, or a deleted page
whose file differs) or unknown. A held comparison may span several sides and
states, and is windowed like a held preview. The comparison prints no apply
command; its next_actions names the --prefer file preview when some files
are newer. A --prefer preview without a side names this comparison as its
fix.
gbrain repair file-drift --source <id> --held --json # compare every held page, no winner named
On a read-only mirror
(GST-2843), the held comparison reads each held page's file too: a page that
differs reads prefer_file or needs_human with its evidence (a held deleted
page whose file differs reads needs_human and names
keeping the deletion first and gbrain sources mirror-writable <id> second, never a --prefer file preview; a purged_differs
page has no deletion to keep and names only mirror-writable), one that
matches reads release_hold, and only a page whose file is gone reads
no_drift with database_only. Every compared page in details.pages
carries evidence (null when nothing was read). The window previews read the
same way, so --held --side unknown --prefer file lists a page whose file is
newer prefer_file; the comparison names the whole-class
preview of the side, which settles every such page with one approval and never
writes the mirror's checkout.
Whole class. --whole-class previews every window
of one side (--held --side unknown|database|both --prefer file) as one class:
one manifest, one hash, one approval. A large read-only mirror can hold
thousands of pages, and a window preview covers 200.
gbrain repair file-drift --source <id> --held --side unknown --prefer file --whole-class # read-only: writes only a private manifest
gbrain repair file-drift --source <id> --held --side unknown --prefer file --whole-class --apply --expect <hash> --yes # after the user agrees
The preview writes repair-previews/file-drift/class-<hash>.json under the
gbrain config directory: per page its slug, path, revision, file blob, hold
code, side, upstream version and lost lines. Its output (and --json) carries
details.class_manifest with path, hash, complete, pages,
lost_lines_total, top (the 50 pages that lose most lines) and residual
(each kept group's count and next command), then the data-loss card: what is
replaced, how many lines are lost, and how it comes back (gbrain revert from
the page version saved first, and reconcile's private backup). Two groups stay
held: kept_newer_page (edited in gbrain after the file's last commit) and,
on a read-only mirror, kept_protected_parts (the file would need gbrain's
protected keys, takes or private facts appended). A preview that stops early
says complete: false, prints a resume command and no apply command.
The apply needs the user's yes on the hash and the trusted local CLI. Each page
is re-read: it applies only while its revision, file blob, hold code, side,
upstream version and mirror flag still match and its lost lines did not grow,
so a sync that only rewrote hold records keeps the approval; anything else is
skipped and stays held. On a read-only mirror the file is imported into the
page database-only, and the next sync releases each hold. A stopped apply
prints its resume command first, then applied, skipped and remaining, and
exits 1; a rerun resumes at the next window and applies no page twice.
Refusals: whole_class_prefer_unsupported (--prefer database or --side deleted; use the window preview), class_capacity_exceeded (the backups would
pass persistence.limits.brain_recovery_bytes; raising it is the user's call),
class_manifest_stale (the manifest no longer matches its hash; preview again)
and class_apply_busy (another apply of the same manifest is running). A brain
with no repository has no held pages: the preview says so and exits 0.
--prefer file never drops a page edited after its file's last commit in
bulk. A --held, --all-drifted or --request preview lists such a page
kept_newer_page, with the edit's time, the file's commit time and the two ways
to settle it (--prefer database for that page, or carry the edit into the
file, commit it and sync), and leaves its hold in place. Naming the page with
--slug still resolves it file-wins, and the preview's warning says which
database edit the apply drops. A page whose file is gone is never deleted by a
comparison or by --prefer file unless you select its deleted state.
Every --prefer preview also counts what the apply drops from the side it
overwrites: each page's listing line ends "drops N line(s) the file holds" (or
"the page holds"), a warning gives the total across the run, and --json
carries details.pages[].lost_lines and details.lost_lines_total. A line
counts when the result doesn't carry it; blank lines and trailing spaces don't
count. Read those lines before you agree to the apply.
| State | --prefer database |
--prefer file |
|---|---|---|
tombstone_edited |
Keeps the deletion and removes the file (on a read-only mirror: records the kept deletion, removes nothing). | Restores the page and imports the file. |
purged_differs |
Removes the file. | Imports the file as a new page. |
file_gone |
Recreates the file from the page. | Soft-deletes the page (the mass-delete valve applies). |
A file_gone page whose file moved is listed moved_to <slug> under either --prefer and resolved by neither: its
line names gbrain repair moved-pages, which folds it into the moved page.
Keep it deleted on a read-only mirror. On a read-only mirror gbrain never writes the checkout, so a page you deleted whose file the upstream then edited can't be settled by removing the file. Keep the deletion with the same per-window command:
gbrain repair file-drift --source <id> --held --side deleted --state tombstone_edited --prefer database # preview: keep_deleted
gbrain repair file-drift --source <id> --held --side deleted --state tombstone_edited --prefer database --apply --expect <hash> --yes
The preview lists each page keep_deleted, and the apply records the decision
on the hold (keep_deleted: the request id, when, and the tombstone's page id
and revision) once the user agrees. A page or file that changed since the
preview is skipped changed_since_preview. Nothing is deleted, restored or
written: the tombstone stays, no file is removed from the mirror and no page
content changes. The hold stays too, decided: gbrain sources status <id>,
gbrain sync status --source <id> and doctor report it carried with reason
mirror_keep_deleted (beside mirror_database_only) and needs_human: false,
and later previews list it mirror_keep_deleted instead of asking again. Sync
does nothing new: it already leaves an unchanged held file alone. The decision
holds for the file version the hold pinned, so a re-check of the same bytes
(an upgrade that re-screens holds) carries it. It is void, and the hold asks
again, when the upstream edits the file again or the page is restored (gbrain restore); when the tombstone is purged, the decision moves to the
purged_differs hold, bound to the deletion marker. On a writable source the
command removes the file as before, and a decision recorded while the source was
a mirror no longer counts. A brain with no Git repository holds no files, so the
preview finds nothing and exits 0.
--prefer file keeps the file's bytes: it adds only protected frontmatter keys the
file lacks and database-only timeline rows, and refuses
file_wins_rewrite when the result
would change anything else (a database-only timeline row dated before the
file's rows included).
A held page whose page and file agree now is listed release_hold under
either --prefer, whether --held or --slug selected it: its apply writes
nothing to the page or the file, and only asks the next sync to re-screen the
file, which releases the hold. The apply rechecks the page, the file and the
hold the preview observed, and answers changed_since_preview when any of
them changed. A preview that finds nothing still prints an apply command; it
applies nothing. Page and
file agree when they differ only in formatting sync does not import (frontmatter
key order or quoting, or a retype's database-only legacy_type stamp on a file that
still names the old type). An apply refused before it published reserves no request
id, so the apply a fresh preview prints goes through. A page with
no recorded file origin (no source path, and a source URI that is not a
file: URI) is compared with, and adopts, the file at its slug path, spelled
as sync imports it (README.md for slug readme); the apply records that
path. A sync re-screens a held page that changed since it was held even when
Git did not move. A gbrain that compares file drift differently (GST-2568) has
the next sync re-screen every held file_drift page that is not a deletion
once: a page that now agrees with its file is released with no commit and no
change to its body, type or stamps (a stale stored copy of the type key is
normalised away), and the sync prints Released N held file(s) that no longer need a decision. (JSON holds_released). A page a read-only mirror stored database-only (mirror_read_only)
is compared with the file at its slug path once its source is writable again;
the apply records that path and clears the stamp.
A held preview covers one window of the selected holds, in held-path order:
at most 200 pages, and it starts no page after 60 seconds of work (each page
reads the database a few dozen times, so a large held set against a remote
database takes minutes per hundred pages). It reports each page on stderr as
it goes. The hash and the printed apply command cover only that window. A
partial window lists after_window in its residuals and prints the next
preview command with --cursor <next_cursor> (JSON: details.window). A held
dry run (a comparison or a --prefer preview) reports complete: false while
held pages remain past its window, and details.window.next_command names the
command for the next window; an apply's complete still means every item of
the approved window was attempted:
gbrain repair file-drift --source <id> --held --side deleted --state file_gone --prefer database # window 1
gbrain repair file-drift --source <id> --held --side deleted --state file_gone --prefer database --apply --expect <hash> --yes # after the user agrees
gbrain repair file-drift --source <id> --held --side deleted --state file_gone --cursor <next_cursor> --prefer database # window 2
The apply reports each page on stderr as well. If the database refuses an item (a deadlock, a serialization failure, a lost
connection), the apply stops with a result naming what it applied, the reason and the command that resumes from that item. Apply each window (or decide not to), then preview the next one. Pages the
apply resolved leave the held set, so rerunning without --cursor also
starts from the first page still held.
A file_gone hold whose meta.reason is never_committed or ignored
(#7130) is a page whose file is missing although Git never committed it: the
sync could not tell a deletion from a file that never reached the repository,
so the page may hold the only copy. --prefer file deletes it after review;
committing the file again clears the hold. Reason origin_unknown means the
sync's history read did not finish, so it could not tell whether a commit held
the file and kept the page; the provenance below reads the whole history.
Reason storage_invalid (#8007) means gbrain.yml's storage section did not
load, declared db_only in a form that resolved no directory, or listed a
deprecated supabase_only next to canonical keys (ignored) whose directory
holds the page and is not also under db_only, so the sync
could not tell whether the page is database-only and kept it: run
gbrain storage status, fix gbrain.yml, commit it and sync again; the hold
clears and the page is decided under the fixed config.
Provenance: who deleted each gone file. Every page of a
--held --side deleted --state file_gone preview names where its file went
(JSON: details.pages[].provenance, counted in details.provenance with every
kind listed, zeros included), read from HEAD's full history with --full-history,
so a deletion on a branch a merge kept is found (a plain
git log --diff-filter=D -- <path> simplifies it away). The history is walked
once and cached per commit, so a long history costs one walk per preview, and
the preview reports the commits read on stderr while it walks:
| Provenance | Meaning |
|---|---|
deleted_by_commit |
The newest commit that deleted the file, with its sha, author, date and subject (a merge only when its resolution dropped the file). |
never_committed |
No commit ever held the file, so the page holds the only copy. |
deletion_uncommitted |
HEAD still holds the file (even one an older commit deleted and a later one restored); only the worktree lost it. |
unknown |
Git could not answer, or the history touched the file without a deletion it can name. |
--provenance <kind> keeps only the held files of one provenance, so each
population gets its own decision:
# Pages no commit ever held: keep each one database-only. No file is written; the page
# forgets its recorded path (database_only_reason=detached) and the hold is cleared.
gbrain repair file-drift --source <id> --held --side deleted --state file_gone --provenance never_committed --prefer database
# Files a commit deleted on purpose: accept the deletions (soft-deletes those pages).
gbrain repair file-drift --source <id> --held --side deleted --state file_gone --provenance deleted_by_commit --prefer file
A deleted_by_commit page whose revision is not file-backed (written in the
database after its file last held it: not the revision sync last imported from
the file, and not one a committed sync or Git-published write produced; for a
page no import record covers, written after the commit that deleted its file) is
listed apart as database_ahead_of_file and not soft-deleted, since it holds
the only copy of that content. Recreate its file with
gbrain repair file-drift --source <id> --slug <slug> --prefer database, or
keep it. gbrain repair ghost-pages lists such a page apart the same way, and
the soft-delete itself refuses one (refused, database_ahead_of_file).
Letting sync apply proven deletions (sync.apply_held_deletions, off by
default). gbrain config set sync.apply_held_deletions true (or
sync.apply_held_deletions.source.<id> true for one source; a per-source value
wins) lets a managed sync delete a held file_gone page itself, and only when
every check passes: the file's provenance is deleted_by_commit, the page at
its current revision equals the file's last committed bytes (the blob in the
first parent of the newest deleting commit, compared the way sync compares a
file with a page before replacing it), and the page's revision is file-backed
by the test above. The deletion is an ordinary sync deletion: a soft delete
with the same restore window (gbrain restore <slug> --force), counted by the
mass-delete valve and the sync.max_deletes / sync.max_delete_ratio caps,
and its write request carries heldDeletion (the deleting commit and the blob)
as the page's receipt. Any other held page stays held, and its hold records why
(meta.held_deletion.refused: content_differs, database_ahead_of_file,
not_deleted_by_commit or page_changed) at the page's revision, so it is not
screened again until the page changes. A file deleted, committed again with
other bytes and deleted again is judged against its last committed bytes.
Turning the switch on makes the next sync read the whole source once; a sync
screens at most 200 held deletions, and the rest wait for a later sync that
reads the source (a new commit, or the daily full round).
--provenance never_committed --prefer file is refused: it would soft-delete
the only copy of each page. A database-only page is no longer screened against
a file; a file synced back at its old path binds it again. The apply re-checks
each page (same revision, file still missing, still never committed) and
reports changed_since_preview otherwise.
both and unknown resolve as --slug does above. --only / --skip narrow
the held set by file path, and the preview lists each page's action.
The audit gives every drifted page one class: structurally_additive,
additive_with_suggestions, review_required, formatting_only or error.
--all-drifted refuses a selection that mixes classes (the message counts
each one) unless --class <name> keeps exactly one, so a single --prefer
never resolves differently shaped drift in bulk. Review review_required
pages one at a time with --slug.
The preview writes each page's resolved result to a private artifact under
the gbrain config directory (repair-previews/file-drift/<hash>.json,
outside every checkout) and prints the hash. --apply --expect <hash>
applies exactly that set through the reconcile apply, with its preimage
checks and retained backups, under request ids derived from the hash, so an
interrupted apply resumes and never writes a page twice. Each page reports
repaired, refused (with the code) or changed_since_preview (the file or
the page changed after the preview; preview again). A changed set refuses
with preview_changed.
Opt-in policy: keep the database copy under some prefixes. For
derived pages nobody edits by hand (concepts a cycle regenerates, for
example) the database copy is the one to keep. Declare their prefixes in the
source's gbrain.yml:
storage:
keep_db:
- concepts/
The managed sync pass then writes the database copy back to the file for
each page under those prefixes whose database copy changed since its last
import (whether or not the file changed too), the same resolution --prefer database previews (reconcile's protections and
backups apply). It does so only in committed mode and for a clean file: the write is
bound to the bytes the pass froze, and a file with an uncommitted edit is
held instead. A pass admits at most 200 such writes; the rest wait as
keep_db_pending and go first in the next pass. Prefixes match page slugs by
whole path segments, like db_tracked and db_only. A remote caller's sync
never writes them, and outside a sync a short-lived command or a caller
write keeps refusing source_changed until the page is reconciled. Doctor maintenance_write_drift
echoes each declared policy (keep_db_policy: prefixes, how many of the
drifted pages it checked match, their receipt cost). Remove the block to turn
the policy off.
Held files
A file gbrain cannot import without guessing does not stop a sync. Sync holds it, imports the rest of the source, advances the checkpoint and
keeps reporting the file until it changes, is deleted, or a newer gbrain can
read it. A held new file has no page yet; a page whose newer file is held keeps
its last good revision, search marks it stale, get_page carries
file_held, and put_page refuses it until the file is repaired, so an agent
must not retry a refused write. Hold codes and their fixes are in
write refusal reasons.
Say to your agent: "Sync says some files in my notes source are held. Show me what is wrong with each one and what gbrain would change, then fix the safe ones." or "After the upgrade my notes source was blocked by one broken file. Get it syncing again."
The session below is real output (volatile ids, hashes and times shown as
<id>, <hash>, <time>; test/held-files-walkthrough.test.ts runs
these commands and checks every line shown). Before the upgrade, a generator
committed three notes to the notes source: notes/standup.md with a title
that continues on an unquoted line, a new notes/digest.md with title:
twice, and a new notes/roundup.md with an unquoted : in author:. A
gbrain older than v0.60.47.0 blocks the source on the first file it refuses.
After upgrading,
gbrain post-upgradenames the blocked source and the command that unblocks it now. Doing nothing also works: the next scheduled or manual sync recovers the source by itself.$ gbrain post-upgrade frontmatter_holds: 1 source(s) are blocked by a file gbrain could not import (notes). The next scheduled or manual sync recovers a blocked source automatically; to do it now run gbrain sync --source notes --no-pull.The sync recovers the source: both broken files are held, the readable one imports (after quoting
author, which gbrain reports so the generator can be fixed), and the checkpoint advances. The old failed request stays in the journal as it was; the sync no longer resumes from it.$ gbrain sync --source notes --no-pull +1 added, ~0 modified, -0 soft-deleted (recoverable 72h), R0 renamed Held notes/digest.md: invalid_frontmatter (needs_interpretation) at line 4, key "title"; its page is missing until the file imports. Next: gbrain repair frontmatter --source notes --include-ambiguous (docs/guides/write-refusals.md#invalid_frontmatter-needs_interpretation) Held notes/standup.md: invalid_frontmatter (needs_interpretation) at line 2, key "title"; its page keeps its last good revision and is read-only for put_page until the file is repaired. Next: gbrain repair frontmatter --source notes --include-ambiguous (docs/guides/write-refusals.md#invalid_frontmatter-needs_interpretation) 2 file(s) held this run, 2 held in source notes; they do not block sync. Inspect them with 'gbrain sources status notes'; the repair preview proposes each fix and writes nothing. Preview the repair: gbrain repair frontmatter --source notes 1 file(s) under notes/ imported only after quoting unquoted frontmatter values: whatever writes them emits YAML other tools refuse. Fix the generator to quote values (or write through put_page); the preview shows the on-disk quoting fix. Preview: gbrain repair frontmatter --source notesgbrain sources status <id>lists every hold with its code, line, key and next command (--jsonadds the structuredgit_holdsshown in step 6).$ gbrain sources status notes notes: 2 held file(s): not imported, and they do not block sync. A page whose newer file is held keeps its last good revision and is read-only for put_page until the file is repaired. Held notes/digest.md: invalid_frontmatter (needs_interpretation) at line 4, key "title"; its page is missing until the file imports. Next: gbrain repair frontmatter --source notes --include-ambiguous (docs/guides/write-refusals.md#invalid_frontmatter-needs_interpretation) Held since <time>. Most holds re-screen on the next sync by themselves (the file changed or was deleted, or a newer gbrain can read it): gbrain sync --source notes --no-pullPreview, pass 1 (safe changes only). Nothing is written. The safe class only quotes values exactly as gbrain already reads them; the two held files need an interpretation, so they are listed as not selected and the preview names the
--include-ambiguouspass.$ gbrain repair frontmatter --source notes safe: notes:notes/roundup.md (Quoted the value of "author" at line 3 (value unchanged)) interpretive_pending: notes:notes/digest.md (Kept the later "title" (line 4) and dropped the earlier one (line 2)) interpretive_pending: notes:notes/standup.md (Folded the unquoted lines after "title" (line 2) into its value) classes: safe=1, interpretive=0, interpretive (needs --include-ambiguous)=2, needs_review=0 -author: acme-example (citing fund-a) (original: https://example.com/post/1) +author: "acme-example (citing fund-a) (original: https://example.com/post/1)" next: gbrain repair frontmatter --source notes --apply --expect <hash> --yes (asks the user first: destructive) next: gbrain repair frontmatter --source notes --include-ambiguousPreview, pass 2, with the interpretations. Show the user each diff. Here the user approves the folded standup title and wants to look at the digest later, so the preview skips it;
--onlyand--skipare bound into the hash. After the user agrees, apply exactly that preview.$ gbrain repair frontmatter --source notes --include-ambiguous --skip notes/digest.md classes: safe=1, interpretive=1, interpretive (needs --include-ambiguous)=0, needs_review=0 -title: Standup with acme-example -the team agreed to ship on Friday +title: "Standup with acme-example\nthe team agreed to ship on Friday" next: gbrain repair frontmatter --source notes --skip notes/digest.md --include-ambiguous --apply --expect <hash> --yes (asks the user first: destructive) $ gbrain repair frontmatter --source notes --include-ambiguous --skip notes/digest.md --apply --expect <hash> --yes applied 2, skipped 0, failed 0, complete repaired: notes:notes/roundup path=notes/roundup.md, written=true, imported=skipped, hold_cleared=false, committed=queued repaired: notes:notes/standup path=notes/standup.md, written=true, imported=updated, hold_cleared=true, committed=queuedimported=skippedmeans the page already held those values (quoting changed nothing gbrain reads).committed=queuedmeans the Git target effect records the change; a checkout without gbrain's Git durability hook keeps the repaired files uncommitted, so commit them the way you commit any edit. The next sync never re-holds a repaired file that is published but not yet committed.Commit, sync, and read the remaining hold as JSON.
$ git -C ~/brain/notes commit -q -m "Repair frontmatter" -- notes/roundup.md notes/standup.md $ gbrain sync --source notes --no-pull 0 file(s) held this run, 1 held in source notes; they do not block sync. Inspect them with 'gbrain sources status notes'; the repair preview proposes each fix and writes nothing. Preview the repair: gbrain repair frontmatter --source notes $ gbrain sources status notes --json "git_holds": { "count": 1, "path": "notes/digest.md", "code": "invalid_frontmatter", "reason": "needs_interpretation", "key": "title", "line": 4, "message": "Invalid YAML frontmatter: key \"title\" at line 4 appears more than once. Reading it would mean guessing, so it was not imported. Keep one line per key with its whole value quoted on that line, then import it again.", "stale": false, "held_since": "<time>", "actor": "agent", "docs": "docs/guides/write-refusals.md#invalid_frontmatter-needs_interpretation"Every hold carries
code,reason,key,line, a location-onlymessage(never a frontmatter value),stale(a page exists and keeps its older revision),fix(the exact argv) anddocs.Later the user approves the digest interpretation (keep the later title). The apply creates its page and clears the last hold; the next sync is clean.
$ gbrain repair frontmatter --source notes --include-ambiguous --only notes/digest.md interpretive: notes:notes/digest.md (Kept the later "title" (line 4) and dropped the earlier one (line 2)) $ gbrain repair frontmatter --source notes --include-ambiguous --only notes/digest.md --apply --expect <hash> --yes repaired: notes:notes/digest path=notes/digest.md, written=true, imported=created, hold_cleared=true, committed=queued $ git -C ~/brain/notes commit -q -m "Keep the later digest title" -- notes/digest.md $ gbrain sync --source notes --no-pull +0 added, ~0 modified, -0 soft-deleted (recoverable 72h), R0 renamed $ gbrain doctor --only git_held_files,frontmatter_repairable [OK] git_held_files: No Git source files are held. [OK] frontmatter_repairable: No file has frontmatter gbrain repair frontmatter would fix.
Doctor reports the same state: git_held_files (warn per source with counts,
the first paths and the commands; fail above GBRAIN_SYNC_HOLD_ESCALATE_COUNT,
default 50) and frontmatter_repairable (files the repair can fix, including
ones that import only after quoting). Both are explicit-only findings:
gbrain doctor --remediation-plan --json lists them as explicit_kind_required
with gbrain repair frontmatter --source <id>, and --remediate never runs the
repair. frontmatter_hook warns when an installed pre-commit hook is older
than the running gbrain's hook; refresh it with gbrain frontmatter install-hook --force.
A hold that blames the write owner, not the file. A preparation_stalled
hold means the owner could not finish preparing that file's write within its
attempts (persistence.max_preparation_attempts, each bounded by
persistence.sync_preparation_ms). The file is fine and gbrain repair has
nothing to change in it: sources status, sources retry-held and doctor
git_held_files route it to the writer instead of to frontmatter or fence
repair, and a source holding all three kinds prints one route for each. Read
what the owner was stuck on, fix that, then re-screen the held files and run
the same sync with the same options (the hold prints them, --no-embed
included). Nothing here is destructive and no hash is involved.
gbrain sources status notes --json # the held files, each with the step it stalled on
gbrain sources writer status --source notes --json # read-only: the owner, its gbrain version, the stuck step
gbrain sources retry-held notes # after the cause is fixed or gbrain is upgraded
gbrain sync --source notes --no-pull --no-embed # the option-preserving command retry-held prints
Runbook: catch-up stuck / held N files;
reference: preparation_stalled.
Settings, all read by every sync (sync.holds is a brain config key; the GBRAIN_SYNC_* variables are read from the
environment of the process that syncs and replace the sync.hold_* and sync.parser_regression keys retired in
0.60.266.0, see sync config keys):
| Setting | Default | Effect |
|---|---|---|
sync.holds |
hold |
fail makes sync fail closed: a content refusal blocks the sync. |
GBRAIN_SYNC_HOLD_CAP |
500 |
How many holds a sync result lists in detail; storage is never capped and valid files always import. |
GBRAIN_SYNC_HOLD_ESCALATE_COUNT / GBRAIN_SYNC_HOLD_ESCALATE_PCT |
50 / 5 |
A source holding more files, or a run holding more than that share of at least 40 screened imports, reports holds_escalated and doctor git_held_files fails. A run whose preparation_stalled holds would cross it stops as preparation_systemic instead of holding them. |
GBRAIN_SYNC_PARSER_REGRESSION |
hold |
A file whose exact bytes imported under an earlier gbrain is held (parser_regression) and the rest syncs; stop stops the run with sync_parser_regression instead. |
To prevent new broken files, write brain files through put_page/capture
or a YAML serializer, check generated content with
gbrain frontmatter validate --stdin --path <source-relative path> before
writing it, and install the staged-content pre-commit hook with
gbrain frontmatter install-hook (the user's decision: it writes into their
repository). See the frontmatter-guard skill.
The content-repair lane (#6377)
The walkthrough above is the interpretive path: frontmatter fixes change what
a file says, so each one is approved by hash. Holds about a file's content
(invalid_fence, and frontmatter_slug_conflict once its lane kind ships)
take a different path and clear with no one acting. The content-repair lane
(src/core/repair/content-lane.ts) is the ordered list of repair kinds that
clear them, today fences, run under one paid-model allowance and one
deadline: what the first kind spends on the model is gone for the next, and
every kind keeps its own census, owner checks, caps, daily ledger
(fences.repair.max_usd_per_page, fences.repair.max_usd_per_day, shared by
the whole lane), attempt memo and validation gates. It runs from three places:
- The maintenance run:
fence_repairruns thefenceskind right aftersync, andcontent_repairruns every other lane kind right after it, both gated onfences.repair.enabled, so a hold the sync just wrote is repaired before the extract phases read the page. gbrain sync unblock --source <source> --applyruns the lane on exactly the held paths now, one bounded apply, then schedules the re-screen and prints the sync. Each path reportsrepaired,held,needs_humanorskippedwith its reason code, receipt and next step;--no-llmkeeps to the free tiers and--no-repairrestores the refuse-only behaviour (runbook).- By hand:
gbrain repair content --source <source> # preview: every lane kind, read-only, no model call; one hash per kind
gbrain repair content --source <source> --apply --expect <hash>[,<hash>] # the apply command the preview prints: exactly those sets
gbrain repair content --source <source> --only <path> --apply # one file, each kind's current plan
The preview plans every kind before anything is written and prints each
kind's own hash and the apply command; there is no combined hash, and a wrong
hash count refuses (invalid_params) before any kind runs. --max-usd <n> is
the lane's allowance for the run; --no-llm keeps every kind to its free
tiers. --apply alone applies each kind's current plan as gbrain repair <kind> --apply does, each file bound to the bytes the plan read
(changed_since_read).
What a repair proves. Every repair is one coordinated write. On a managed
source the file is rewritten, imported, its hold cleared and the commit queued
through the Git effect, whose subject is gbrain: repair fence in <path> (<classes>) and whose trailer gbrain-repair: <hold_code> <tier> <confidence>
names what was repaired, which tier decided it and how sure the rule was. The
receipt the write carries (location-only: mode, tier, classes, rows, columns,
before_sha256, after_sha256, committed: effect | commit_step | not_in_git, and for a merge the merged fence occurrences, never a cell) is
parsed before it reaches a commit message, so nothing forged lands there.
git revert of that one commit restores the bytes; the hold then re-screens.
A legacy source is backed up under ~/.gbrain/backups/ and prints the commit
step with the same -m pair.
What the model decides, and what it never does. The deterministic tiers
run first and the model sees only the cases they mark ambiguous: the trailing
lines after an unclosed fence on a world-visible page (prose, rows or unsure)
and a slug conflict whose two pages might be the same thing (remove_slug,
merge_into <canonical> or needs_human). The model chooses among coded
answers; every byte written comes from a rule and passes the gates. Merges are
recommended, not executed: a merge_into answer becomes a needs_human
hold naming the canonical page (merge_recommended),
and a world-page close that would expose text waits for the hash-bound
approval (tail_exposure_approval).
gbrain sync status --source <source> --json lists each such hold with its
paragraph in human_reason; fences.repair.llm false turns the model tier
off for the whole lane.
Slug conflicts agree with sync. The slug-conflicts kind screens a held
file, and the edit it would write, with the same screen managed sync froze
the file with. A held file the screen now admits as it is (its slug: line
names the file's own page, or it no longer conflicts) is listed as import
and imported unchanged; the write clears only the hold observation the
preview read, so a hold a newer sync wrote stays and the next run retries it.
A file sync would hold whatever the lane writes (the page it is filed as
carries a different slug than its path, or the line reaches the page only
through an alias) is held slug_page_mismatch
with both slugs and the exact hand edit.
Say to your agent: "Sync is holding a few files over their tables or slugs. Repair what gbrain can by itself and tell me what it wants me to decide."
Frontmatter
A file whose YAML frontmatter gbrain cannot read without guessing is held by
sync instead of blocking it, and some files import only after gbrain
quotes an unquoted value. gbrain repair frontmatter fixes those files on
disk and imports them. It also finds pages an older import stored wrong: a
body that begins with its own frontmatter block, or a title derived from the
slug although the file names one. It is explicit-only and preview-bound.
Say to your agent: "Some files in my notes source are held. Show me what
gbrain would change in each one, then fix the safe ones." The agent runs
gbrain repair frontmatter --source <id> and, after you agree, the printed
apply command.
gbrain repair frontmatter --source <id> # pass 1: safe changes, one sample diff per class
gbrain repair frontmatter --source <id> --apply --expect <hash> --yes
gbrain repair frontmatter --source <id> --include-ambiguous --diff # pass 2: every interpretation, per file
gbrain repair frontmatter --source <id> --include-ambiguous --only notes/a.md --apply --expect <hash> --yes
Each file gets one minimal line change in one class:
| Class | Changes | Default |
|---|---|---|
safe |
Quote a value exactly as gbrain already reads it, strip NUL bytes, swap the outer quotes of a nested quoted value. Every parsed value stays the same. | Included. |
interpretive |
Fold unquoted continuation lines into the value above, keep the later of a duplicated key, quote an unclosed [/{ or a #-leading title, insert a missing closing ---, remove a slug: line that names another page, re-import a page from its file, re-bind a held rename to the old page's current revision. |
Only with --include-ambiguous. |
needs_review |
No rule fixes it (mis-indented YAML, a protected key such as visibility, an import that would keep page data the file does not carry, a file over the page size limit). |
Never written. The preview names the exact manual fix. |
Two passes: when interpretive candidates exist, the safe preview's
next_actions carry both the safe apply and the --include-ambiguous preview.
Review each interpretation in the full diff, then approve all of them or only
some with --only/--skip; a file left out stays held and unchanged.
Every change must leave a file that parses strictly and earns no hold. The
hash binds the selected files, their exact before and after bytes, and the
page each import would store (bound to the page revision). The apply derives
each change again from the file as it is: a file, proposal or page that
changed since the preview reports changed_since_preview and is not written.
The apply refuses a selected file a write in flight or an unfinished managed
sync's frozen manifest still names (sync_in_progress, checked again when the
write is admitted; finish the sync with gbrain sync --source <id> --no-pull
or let the next run pick the file up).
On a managed brain each file is one coordinated write (managed_file_repair):
the exact approved bytes, the import, and the hold clear commit together, and
the file is committed through the Git effect like any page write. On a legacy
brain the apply backs each file up under ~/.gbrain/backups/frontmatter/,
writes it, imports it, clears its hold and prints the gbrain git commit-push
step that commits and pushes only that file. Per-file outcomes report written, imported, hold_cleared and
committed. Repair stays explicit-only: gbrain repair --all and
gbrain doctor --remediate never run it.
Fences
A facts or takes fence gbrain cannot import without guessing never blocks a
sync: sync holds the one file and imports the rest, and a fence with one exact
meaning is rewritten in the same write. gbrain repair fences repairs what is
left, and the maintenance run (cycle phase fence_repair) applies the same
repair by itself on the brain's owner host, so a fence hold usually clears with
no command. It finds held files, stored pages whose fence does not parse, and
checkout files not yet synced. The preview is read-only and makes no model
call; applying needs no extra consent. What each reason means and who acts:
fence holds; the format and every rule:
fence format.
Say to your agent: "Sync held some pages because of their facts or takes tables. Show me what gbrain would change, then repair them." or "How many broken facts tables are left, and what will fixing them cost?"
Each candidate gets the cheapest tier that repairs it exactly:
| Tier | What it does | Cost |
|---|---|---|
deterministic |
The lossless rules every write already runs (missing end marker, stray empty cells with one valid removal, row numbers, header aliases and order, enum and kind synonyms, assistant holders, percent confidences), plus one only the repair runs: a fence marker quoted in prose (quoted_marker) is wrapped in backticks, kept only when every fence row stays put and nothing hidden becomes visible. |
Free. |
resolver |
A holder written as a display name becomes the people/ or companies/ page it names, only on an exact match (slug, unique slug basename or alias; never a guess, never a private page on a world-visible page). |
Free. |
llm |
Rows only a rewrite can realign (no header, a header column with no canonical name, rows above the header, short rows). The repair model sees only the fence header and those rows, never valid rows of a row-level problem and never the rest of the page, with no tools, and answers HOLD instead of guessing when a row has two readings. | Paid, within fences.repair.max_usd_per_page ($0.30) and fences.repair.max_usd_per_day ($1.00). |
manual |
Anything gbrain never guesses (a stray end marker, an unknown takes kind, a weight out of range, a holder no page matches, extra cells that removing empty cells cannot line up, a sentence in the facts kind column). The preview names the exact edit. |
Your edit. |
Every proposal, whichever tier made it, must pass the validation gates (a) to (g) against the bytes as read (claims, existing row numbers and valid cells unchanged, no row more visible, nothing the fence hid shown) and be a normalizer fixed point, or it is not written. A model proposal that does not parse or changes the row count (gates (a) and (e)) gets one corrective re-ask naming the gate and rows; any other gate rejection, a HOLD, or a failed re-ask leaves the file held, and the same bytes are never sent again until the file, the model or the rules change.
The repair model is models.fence_repair when set. Unset, it is the first
model the fence-repair eval measured as accurate enough whose provider key the
brain has: openai:gpt-6.1-sol with an OpenAI key, else
anthropic:claude-opus-5-5 with an Anthropic key. With neither key, model-tier fences wait as
no_measured_model until the user picks a model.
The gates check that no text is lost or rewritten; they cannot tell which of two
free-text columns a moved cell belongs in, which is why only measured models
are defaults. On 40 held-out synthetic malformed fences over three runs
(evals/fence-repair-tier3), openai:gpt-6.1-sol and
anthropic:claude-opus-5-5 each repaired 95 of the 99 attempts that reached
the model, none with a cell in the wrong column, and answered HOLD on the
other 4; rows with stray empty cells were lined up by the free rule instead.
The session below is real output (volatile ids, hashes and times shown as
<id>, <hash>, <time>; test/fence-walkthrough.test.ts runs these
commands against a local stand-in for the model provider and checks every line
shown). Before the upgrade a generator committed three notes to the notes
source: a meeting note whose facts fence has no end marker and an invented
kind, a company note whose facts rows have no header, and a project note whose
takes row names its holder as Alice Example (a people/alice-example page
exists). An older gbrain blocked the source on the first fence it refused.
After upgrading,
gbrain post-upgradenames the blocked source, the malformed-fence count, the preview and the pause command. No maintenance run is active on this brain yet, so nothing repairs the fences by itself.$ gbrain post-upgrade [AGENT] fence_integrity: 3 (not repaired automatically (no maintenance run is active); preview with: gbrain repair fences) [AGENT] fence_holds: 1 source(s) are blocked by a file whose facts or takes fence gbrain could not import (notes). The next scheduled or manual sync recovers each with no command; to do it now run gbrain sync --source notes --no-pull. The file is then held and the rest of the source imports. 3 malformed fence(s) are known so far (gbrain doctor --only fence_integrity counts them by tier); nothing repairs them by itself until a maintenance run is active, so preview them and apply the plan the preview prints once the user agrees. Preview (read-only, no model call): gbrain repair fences. Pause automatic fence repair first with: gbrain config set fences.repair.enabled false. Recipe: docs/guides/repair.md#fencesOne sync gets the source going again: the meeting note's fence is rewritten (claims and row numbers unchanged), and the other two files are held while the rest imports. The old failed request stays in the journal as it was.
$ gbrain sync --source notes --no-pull +1 added, ~0 modified, -0 soft-deleted (recoverable 72h), R0 renamed Held companies/acme-example.md: invalid_fence (no_header) in the facts fence (body), at line 6; its page is missing until the file imports. Next: gbrain repair fences --source notes --only companies/acme-example.md, then gbrain repair fences --source notes --only companies/acme-example.md --apply (docs/guides/write-refusals.md#fence-no_header) Held projects/widget-launch.md: invalid_fence (holder_unresolved) in the takes fence (body), row 1, column who, at line 9; its page is missing until the file imports. Next: gbrain repair fences --source notes --only projects/widget-launch.md, then gbrain repair fences --source notes --only projects/widget-launch.md --apply (docs/guides/write-refusals.md#fence-holder_unresolved) 2 file(s) held this run, 2 held in source notes; they do not block sync. Inspect them with 'gbrain sources status notes'; then nothing repairs the fence and slug-conflict holds by itself (no maintenance run is active), so preview the content repairs with gbrain repair content --source notes (read-only, no model call: it lists each held file with its planned repair or the exact edit, kind by kind, and prints the apply command with --expect <hash>[,<hash>]), then run the apply command it prints. Preview the repair: gbrain repair content --source notes Normalized fences in 1 file(s) (close_fence x1, kind_map x1). 1 file(s) under meetings/ had a malformed facts or takes fence that sync rewrote losslessly and committed (claims and existing row numbers unchanged); whatever writes them emits fences gbrain has to repair. Write facts with `remember` and takes with `takes_add` (or emit the canonical columns) so rows never need normalizing. Re-read a normalized page before editing it.gbrain sources status <id>lists each fence hold with its fence, section, row, column, line and next step (--jsonadds the structuredfenceobject: reasons, rows, columns, tier,auto_retryandnext_attempt_after).$ gbrain sources status notes Held companies/acme-example.md: invalid_fence (no_header) in the facts fence (body), at line 6; its page is missing until the file imports. Next: gbrain repair fences --source notes --only companies/acme-example.md, then gbrain repair fences --source notes --only companies/acme-example.md --apply (docs/guides/write-refusals.md#fence-no_header) Held since <time>.Preview. Nothing is written and no model is called. The resolver tier shows its exact diff; the model tier shows the rows it will rewrite and the estimated cost against what is left of today's cap.
$ gbrain repair fences --source notes cost: 2 request ID(s), 32768 receipt bytes, 2 page(s) to re-embed, paid model ~$0.0273 ($1.0000 left under today's cap) llm: notes:companies/acme-example.md (no_header; rewritten by openai:gpt-6.1-sol at apply time, gated by (a)-(g); est. $0.0273) resolver: notes:projects/widget-launch.md (holder_verified; rows 1) tiers: deterministic=0, resolver=1, llm=1, held=0; model openai:gpt-6.1-sol model caps: $0.30/page, $1.00/day ($1.0000 left today) -| 1 | The launch slips a week | bet | Alice Example | 0.6 | 2026-04 | standup | +| 1 | The launch slips a week | bet | people/alice-example | 0.6 | 2026-04 | standup | next: gbrain repair fences --source notes --apply --expect <hash> Kinds that may call a paid model: fences (estimated $0.0273; $1.0000 left under today's cap).Apply exactly the previewed set. A file that changed since the preview is skipped as
changed_since_preview. Each file is one coordinated write: the repaired bytes, the import and the hold clear commit together.$ gbrain repair fences --source notes --apply --expect <hash> cost: 2 request ID(s), 32768 receipt bytes, 2 page(s) to re-embed, paid model $0.0039 spent ($0.9961 left under today's cap) applied 2, skipped 0, failed 0, complete repaired 2; nothing left in this selection repaired: notes:companies/acme-example tier=llm, classes=no_header, slug=companies/acme-example, mode=managed, path=companies/acme-example.md, imported=created, hold_cleared=true, committed=queued repaired: notes:projects/widget-launch tier=resolver, classes=holder_verified, slug=projects/widget-launch, mode=managed, path=projects/widget-launch.md, imported=created, hold_cleared=true, committed=queuedcommitted=queuedmeans the Git target effect records the change. On a checkout with gbrain's Git durability hook (gbrain sources harden <id>) the owner's persistence worker commits each repaired file with the subjectgbrain: repair fence in <path> (<classes>)(a commit that batches several lists one<path> (<classes>)per body line). This checkout has no durability hook, so the rewritten files (the meeting note sync normalized, too) stay uncommitted: commit them the way you commit any edit.Commit and check. Doctor
fence_integrityisokonce nothing is held, stored malformed or waiting in the checkout.$ git -C ~/brain/notes status --short M companies/acme-example.md M meetings/2026-04-03.md M projects/widget-launch.md $ git -C ~/brain/notes commit -q -m "Repair fences" -- companies/acme-example.md meetings/2026-04-03.md projects/widget-launch.md $ gbrain doctor --only fence_integrity [OK] fence_integrity: No malformed facts or takes fence is held, stored or waiting in a checkout (2 source(s) scanned).
One command got the source syncing again (the sync), and two repaired the rest (preview, apply), for $0.0039 of model spend.
Selection and output:
gbrain repair fences --source <id> --only companies/acme-example.md # one file; --skip <path> leaves one out
gbrain repair fences --source <id> --slug notes/db-only # a stored page with no file
gbrain repair fences --source <id> --diff # every diff, not one sample per tier
gbrain repair fences --source <id> --no-llm # free tiers only; model-tier items stay held (llm_disabled)
gbrain repair fences --source <id> --max-usd 0.10 # at most $0.10 on the model this run (lowers the cap only)
gbrain repair fences --source <id> --json # every diff and the full result
The selection and --no-llm/--max-usd are bound into the preview hash and
printed in its apply command. A bare --apply (what gbrain repair --all,
gbrain doctor --remediate and the maintenance run use) applies the current
plan. The result keeps the shared complete (every pending item was tried) and
adds repaired (what this run repaired), remaining (what still waits, by
reason), scan (fresh_at, partial: whether the census behind the plan
finished) and verification (repairs per tier, holds per reason, the oldest
hold and USD per model repair). A run whose every model proposal is rejected
reports repaired 0 with the gate reasons; a run that ends with only manual
edits left exits 0. When the daily ledger refuses the next model call, the run
stops with budget_exhausted and exits 1, naming what was spent against the
cap, the reset time (the next 00:00 UTC), the pages still waiting and the fix
gbrain config set fences.repair.max_usd_per_day <usd>: raising it is the
user's call.
Where each repair writes: a managed source through managed_file_repair (bound
to the file's before-hash and page revision, committed through the Git effect);
a legacy (unmanaged) source by backing the file up under
~/.gbrain/backups/fences/<run>/, writing it, importing it and recording an
"uncommitted fence repair" notice that gbrain sources status and doctor show
with the exact gbrain git commit-push step until the path is committed; a
stored page with no file by a revision-bound page write; a read-only mirror in
the database only (the file is never written). Every write's receipt carries
the actor fence-repair, the tier, the classes, rows and columns, the model,
the before and after sha256 and the cost, never a cell value. MCP and
thin-client callers cannot run a repair or reach the model; a hold's fix hands
them the owner-host command to give the user.
Fence repair during a sync
A running gbrain sync of the source no longer stops the repair. Each
candidate is checked on its own against the sync's busy set, and only the
ones below wait as sync_in_progress; every other candidate is repaired while
the catch-up runs, including a file the sync held earlier (a held path is not
busy, because the sync retries a held file only once its bytes change, and
the repair is what changes them).
Busy (waits as sync_in_progress) |
Why |
|---|---|
| A file or page a queued, running or recovering write names, or a finished write whose recovery is still open; both endpoints of a rename | The write is still publishing it. |
| A file still ahead in a company-brain sync's frozen manifest, or a legacy cursor's that no pass has retired yet (from the cursor's index on) | The sync admits it later with the raw hash it reads then; a repair that changed the bytes first would make that entry refuse (source_changed). A live pass adds nothing here: it freezes and admits under the drain lease and re-checks each candidate's revision, so only its open requests (the row above) are busy. |
| Every candidate, when the busy set cannot be read (a failed query, a cursor whose manifest is missing) | The check fails closed; the hold's text says so. |
The busy set is read when the plan is made, again when each item is applied
(a sync may have started since the preview), and once more when the managed
file write is admitted, because a sync can freeze the candidate while the
repair waits on its model call. An item caught at that last check is skipped
sync_in_progress, nothing is written, and its model attempt is recorded as
transient, so the next run sends the same bytes again.
Owner reasons
Fence repairs write only on the host that owns the source's checkout. When
this host may not, the candidate is skipped with the condition as its reason
(the same reasons gbrain errors owner_unavailable lists and chronicle and
the other maintenance writers refuse with), and the hold records it:
| Reason | What it means | Who acts | Next |
|---|---|---|---|
host_mismatch |
Another host id owns the checkout; the text prints both ids' first 8 characters and, for a local caller, the host.json path this process read. Two environments on one machine with different GBRAIN_HOME values (a launchd or cron worker and a shell) look exactly like this. Not retryable. |
host administrator | Run the repair on the owner host (gbrain sources writer status --source <id> --json names it), or give the worker and the shell one GBRAIN_HOME. Never copy or regenerate host.json. |
transfer_in_progress |
The worktree is draining for a prepared writer transfer. | nobody | Wait 30 s and retry; the next maintenance run repairs it once the transfer is accepted or cancelled. |
clone_in_progress |
A topology clone or reclone is recovering the worktree. | nobody | Wait 30 s and retry; the next run repairs it once the clone finishes. |
incarnation_changed |
The checkout binding is from an earlier incarnation of the source (removed and re-added, or restored). | host administrator | Review writer status and re-bind the checkout. |
local_path_missing |
This host owns the worktree but has no checkout path registered. | host administrator | Review writer status and register the checkout again. |
coordination_path_missing |
This host's registration has no coordination directory. | host administrator | Review writer status and repair the registration. |
owner_unavailable |
The generic fallback: a source with no owner at all, or an older hold. | host administrator | Review writer status. |
Nothing in this path claims or transfers ownership to get a repair through; the fix is always the read-only writer status. Remote callers get the host ids but never a local path.
Inspect or undo a repair:
- Managed sources:
git log --grep 'repair fence in'lists the repair commits,git show <commit>the change, andgit revert <commit>undoes it (for one file of a batched commit,git checkout <commit>^ -- <path>and commit). - Stored pages:
gbrain history <slug>shows every version, including the one before the repair;gbrain revert <slug> <version_id>restores it. - Legacy sources: the original file is in the backup the apply output names; copy it back and sync.
Turning the settings off stops future repairs and does not undo past ones. A restored malformed fence is held again on the next sync and repaired again by the next maintenance run, so pause first if you want to keep the original.
| Setting | Default | Effect |
|---|---|---|
fences.repair.enabled |
true |
false pauses the maintenance run's repair; gbrain repair fences --apply still works. |
fences.repair.llm |
true |
false keeps every repair to the free tiers; model-tier holds stay llm_disabled. |
fences.repair.max_usd_per_page |
0.30 |
The most one page may spend on the model, checked against each call's worst case (the prompt plus the full output ceiling, with 2,048 tokens for a reasoning model to think). 0 means no model spend. |
fences.repair.max_usd_per_day |
1.00 |
The most all processes together spend per UTC day, through a durable ledger. 0 means no model spend. |
models.fence_repair |
unset: the first measured model with a key (openai:gpt-6.1-sol with an OpenAI key, else anthropic:claude-opus-5-5 with an Anthropic key), else none |
The model Tier 3 calls (gbrain models shows it). A model you set always runs; one gbrain has no price for runs under the default caps at an estimated ceiling (the highest chat rate gbrain knows; gbrain pricing set makes it exact) and waits for its price under a cap you set. |
fences.normalize |
true |
false stops the inline rewrite on writes and syncs: a fixable fence is held or refused like any other. |
Unindexed files
A file an older gbrain refused before refusals became holds has no page and no
hold; incremental sync never revisits it. The
maintenance phase unindexed_files finds such files (bounded, never
clean while incomplete; each run continues the stored scan, also after new
commits, and serves the least recently scanned source first) and schedules a
re-screen, which the next sync consumes once it imports or holds the file; doctor
unindexed_files reports them. Run gbrain sources retry-held <id> --unindexed, then the sync it prints: each file imports or becomes a
hold. slug_taken (the path slug belongs to another page) and deleted_page
(the page was deleted while the file stayed committed) are never scheduled:
rename one of the two files, or delete the file or restore the page.
A committed symlink whose target does not exist is skipped by sync, so it is
never reported as unindexed.
metafile_skipped (never scheduled) lists titled scaffolding files sync skips
on purpose (index.md, README.md, ...) under sync.metafile_pages off; under
the default typed a nested titled one is an ordinary unindexed file. To keep
off and still import one, rename it
(investors/fund-a/index.md to investors/fund-a.md), commit and sync.
Resume
Runs are resumable. After each page commits, the position is saved under the
kind, the brain and the source list. Rerunning the same command (the same kind
and --source) continues after the last committed page, and the preview says
resuming after item .... A finished run clears the saved position. --limit
does not change the position key, so --limit 500 batches continue each other.
Request IDs are derived from the page and its revision, so rerunning after a
crash replays the same write instead of making a second one. If the run stops
with "still pending publication" or "the canonical writer ... is held", check
gbrain sources writer status <source>, then rerun the printed apply command.
Every applying kind waits for each publication with the CLI write wait: --wait <seconds>, then
GBRAIN_WRITE_WAIT_MS, then persistence.write_wait_ms, else 30 seconds. That includes the doctor
remediation run and the replay of a restore a previous extractor-facts apply left pending.
A write that is accepted but still pending when its wait ends does not stop the run while a consumer
on this host is publishing (#6543). The run keeps the receipt, leaves its saved position before that
item, and admits the remaining items without a per-item wait. At most half the principal's
outstanding-request cap (persistence.limits.principal_outstanding, at most 64) stays unresolved at
once; past that the run waits for earlier receipts first. All receipts settle against one shared wait:
the run gives up only when nothing it admitted has published for the write wait. A preview-bound kind
(--expect) settles every earlier receipt before its last item, so its approved set is kept until
every admitted item is accounted for. When the run still stops, pending lists the receipts (item and
request_id) and rerunning the same apply command replays them; a crash leaves the position before
the first unresolved receipt, so the rerun does the same. --wait 0 waits for nothing: it admits what
it can and stops with pending. With no live consumer on this host, or one that reports
restart_required, the run stops at the first pending write as before and its fix names the owner. A malformed
GBRAIN_WRITE_WAIT_MS refuses the apply with invalid_write_wait before anything is written; a preview
never reads it.
Capacity stop
timeline and visibility write through the managed write journal, which has
permanent per-principal and per-brain limits on request IDs and receipt bytes.
Before each page, the repair checks those counters and stops before it would
cross 90% of any limit. The stop message names the setting and a value that
lets the remaining pages finish:
STOPPED: Stopped before crossing 90% of brain lifetime_ids (...). Run: gbrain config set persistence.limits.brain_lifetime_ids 1200000 — then rerun `gbrain repair timeline --apply` to resume.
Raise the limit on the brain host only if you agree, then rerun. Raised limits
are brain-wide; request IDs stay permanent replay protection. safe-chunks
and contextual-mode take no journal admission and never hits this stop. The limits and their
defaults are in bounded admission and retention.
Where it runs
Run gbrain repair on the brain host, the machine that holds the database. A
thin client refuses before doing anything:
`gbrain repair` is not routable. repair runs on the brain host (it publishes coordinated page writes against the local engine). Run `gbrain repair` on the brain host.
A repair is an ordinary trusted local write and follows the same rules as
any other page save. It never transfers an existing owner and does not change
activation, sync checkpoints or search settings. Like any local save on a
PGLite brain, the first timeline or visibility write to a source with a
configured checkout and no owner yet claims that checkout for this host. Do not set
search.remote_private_pages to get derived pages back remotely: that exposes
every private page.
Verify
gbrain repair --json # every kind reports "affected": 0
gbrain doctor --json # timeline_history, derived_visibility, safe_index_pending
gbrain doctor --remediation-plan # no repair steps left
Items the repair leaves alone can keep a doctor warning: concepts without
lineage still count under derived_visibility, and code pages without a
source path or unsupported page kinds still count as unsealed pages. Check
the residual counters before treating a remaining warning as a failed repair.
Run repairs through doctor
Say to your agent: "Preview what doctor would fix after the upgrade, then run the repairs I agree to with a $2 cap."
gbrain doctor --remediation-plan previews two kinds of step. Job steps come
from the brain score and --target-score. Repair steps come from every
gbrain repair kind that has pending items, whatever the score target, and
each is marked requires user agreement. Every step prints the exact command
that applies it, and the plan ends with one combined command:
Repair steps: 2 (requires user agreement; PROTECTED, run on this host only; independent of the score target)
R1. timeline — 12 item(s) (free) [requires user agreement]
apply: gbrain repair timeline --apply
R2. safe-chunks — 40 item(s) (~$0.0031 embeddings) [requires user agreement]
apply: gbrain repair safe-chunks --apply
Apply everything after the user agrees: gbrain doctor --remediate --yes --include-repairs --max-usd 0.01 --expect ph_3f9c2a1b7d4e5f60a1b2c3d4
Ask the user before applying any repair step.
The plan never includes an explicit-only kind as a repair step. It prints them
in an Explicit-only repairs block instead, one line per kind with its
read-only preview command (stale-atoms: gbrain repair stale-atoms), and
--json lists them as explicit_repairs[] (kind, code: "explicit_kind_required", preview_command, docs). Run each by name after
the user agrees (see Explicit-only repair kinds).
A repair kind whose preview errors (on a large brain this is usually a
statement timeout) does not stop the plan. Every other kind is still
previewed, and the failed kind is listed under Repair kinds whose preview failed with its error code, its error and the read-only command that
repeats the preview. In --json it appears in repair_preview_failures[],
which is present only when a preview failed. Each entry is
{kind, code, message, why, fix}: code is timeout for a statement
timeout (raise GBRAIN_STATEMENT_TIMEOUT) and preview_failed for anything
else, message is redacted and then capped at 300 characters, and fix is
the read-only preview. A failed kind is never a step, so gbrain doctor --remediate runs the remaining steps, names the kinds it could not run and
exits 1. An approval covers only the steps the user was shown: once the
failed preview succeeds, the plan changes and the run refuses with
preview_changed. Preview the plan again and ask the user.
gbrain doctor --remediate --yes runs job steps only. Repair steps run only
when you also pass --include-repairs, which records the user's agreement;
without it they are listed as N repair steps skipped (user agreement required): re-run with --include-repairs. Repair steps are PROTECTED: they run in this
process on the brain host, and a remote caller cannot include them. They run
even when the score target is unreachable (a keyless brain often cannot reach
90); --target-score governs job steps only, and an included repair step runs
to completion.
--max-usd <n> is a cumulative cap across the run and every --resume. A paid
step (one that may queue embeddings) whose estimate exceeds what is left is not
started; the free steps still run, and the run then stops as budget-exhausted
with a resume command that repeats the cap and --include-repairs:
Resume with:
gbrain doctor --remediate --yes --include-repairs --max-usd 0 --resume 3f9c2a1b7d4e5f60
The checkpoint lives in ~/.gbrain/remediation/<plan hash>.json on this host
and records the brain, the cap, the --include-repairs agreement, the spend so
far and the original steps. --resume without --max-usd reuses the recorded
cap and prints it; a higher --max-usd raises it. A resume only continues the
original steps: repair kinds or job steps found later need a fresh run and a
fresh agreement. A checkpoint recorded for another brain is refused.
When an embedding model is configured, every kind can spend. timeline and
visibility publish page writes whose embeddings the persistence consumer
computes afterwards, outside this run, so their estimate is charged against the
cap before they start; --no-embed does not change that. The consumer does
not see the cap, so for those kinds the cap bounds the estimate, not each
provider call, and the estimate counts the page as it is before the repair.
safe-chunks embeds in the run itself under the remaining cap and
--no-embed makes it free. When the budget runs out after pages are re-sealed,
the checkpoint keeps their sources and --resume finishes their embeddings
under the same cap; a run that leaves embeddings behind exits 1 and says to run
gbrain embed --stale.
With --json, the result adds repairs[] (one entry per repair step, with
status completed, stopped, failed, budget_refused or
budget_exhausted), repairs_skipped[], budget, repairs_completed,
healthy and findings[]. Each finding has a check_id, a message and a
class:
| Class | Meaning |
|---|---|
cleared |
The finding was present before the run and is gone after it. |
pending |
A repairable finding remains: its step stopped, was refused by the budget, left items behind, or the check could not run. |
consent_required |
A repairable finding whose step was skipped for lack of --include-repairs; command applies it. |
operator_required |
Needs a named manual action on the brain host (instruction), for example raising a journal limit, retrying a parked effect, or quarantining self-captures. |
explicit_kind_required |
Only an explicit-only kind clears it (for example atom_provenance_drift and stale-atoms); command is that kind's read-only preview. It never runs under --remediate and does not fail the exit status. |
unsupported |
No command can clear it yet; it is reported so it is never hidden (a stale queued embedding effect). |
Exit status: 0 when no automatically repairable finding remains and no step
failed, even if operator-required, explicit-only or unsupported findings
remain (they are listed); 1 when a repairable finding remains, a step failed, or the budget
ran out; 2 when the score target is unreachable and there was no repair step
to run, or a resume was refused. healthy is true only when every recovery
check is clean after the run; repairs_completed counts the repair steps that finished.
Doctor budgets
Every doctor check runs under a budget, so a slow check reports unknown instead of holding the run.
- Order: the ops sections run first, then the cheap incident checks (
persistence_capacity,managed_sync_not_moving,managed_sync_blocked,text_projection_readiness,partial_embedding,links_extraction_lag), then the full scans. - Per check:
doctor.entry_budget_ms(default 15000). A check's database statements stop at its budget: Postgres cancels the statement; PGLite refuses the next one but cannot stop one already running, so a check there can finish late. The frontmatter and fence scans report what they read by then. - Per run: a non-interactive
gbrain doctor --json(stderr not a terminal, no--budget-ms,--tier,--fixor remediation flag) caps its check run atdoctor.default_budget_ms(file plane, default 90000; connect and migrations are not counted) and says so on stderr.--budget-ms 0turns it off for one run;gbrain config set doctor.default_budget_ms 0turns it off for good. - Past a budget: the check reports
details.health: "unknown"withdetails.limit(entryoroverall) and printsgbrain doctor --only <check> --budget-ms N --json, which gives that check the whole N.
Recover after an upgrade
Say to your agent: "We just upgraded gbrain. Check what needs repair and walk me through it before changing anything."
gbrain post-upgraderuns the recovery checks once and, when something needs attention, prints an[AGENT] Relay this to your operatorbanner with each finding's count. It never applies anything.- Preview:
gbrain doctor --remediation-plan. Show the user the repair steps and their estimated cost, and ask before applying. - After the user agrees, apply with a budget:
gbrain doctor --remediate --yes --include-repairs --max-usd <n> --expect <plan_hash>(the plan prints<n>and<plan_hash>filled in;--remediation-plan --jsonreports the hash asplan_hash). If the plan changed since the preview, the run refuses withpreview_changedand changes nothing: preview and ask again. - If it stops as budget-exhausted, ask the user again, then run the printed
resume command (raise
--max-usdonly with their agreement). - Follow each
operator_requiredinstruction the run prints, and note theunsupportedones. - Verify:
gbrain doctor --remediation-planlists no repair steps.
| Symptom or error text | Preview | Apply | Verify | Who acts | Consent |
|---|---|---|---|---|---|
Sync BLOCKED on one file (Invalid YAML frontmatter, a frontmatter slug conflict, Content too large); after upgrading, sync prints Held <path>: …; doctor git_held_files or frontmatter_repairable warns; the upgrade banner prints frontmatter_holds: |
gbrain sources status <source>, then gbrain repair frontmatter --source <source> (add --include-ambiguous for interpretations) |
nothing to unblock: the next sync converts the blocked request in place (gbrain sync --source <source> --no-pull does it now); for the backlog, the printed gbrain repair frontmatter … --apply --expect <hash> --yes (held files) |
gbrain doctor --only git_held_files,frontmatter_repairable --json (both ok) |
brain host; the repair apply after the user agrees | destructive (repair apply rewrites the previewed lines) |
Tag, timeline or take writes fail with writer_coordinator_required or storage_error: Publication failed (P0001) on a managed brain; sync ends PARTIAL at a tagged page |
gbrain doctor --json (schema_version is 197 or later) |
the original gbrain sync --source <source> … --no-pull --json, then gbrain extract --stale --source-id <source> and gbrain extract timeline --source db --source-id <source>, then gbrain facts relink --source <source> --dry-run (paid tier only after the user agrees), then gbrain repair failed-writes --source <source> and, after the user agrees, its printed --apply --expect <hash> |
gbrain sources status shows the new last_commit; a second gbrain extract timeline --source db run adds no rows; a second gbrain repair failed-writes preview lists nothing to replay |
brain host; the replay apply after the user agrees | paid (relink tier), destructive (replay apply) |
Sync BLOCKED with checkpoint_validation_timeout |
gbrain doctor (persistence_request_indexes) |
gbrain repair request-indexes --apply when an index is missing or INVALID, then the printed gbrain sync --source <source> --no-pull … |
gbrain doctor --only persistence_request_indexes --json reports ok; gbrain sources status shows the new last_commit |
brain host | none |
Doctor persistence_request_indexes warns |
gbrain repair request-indexes |
gbrain repair request-indexes --apply |
gbrain doctor --only persistence_request_indexes --json |
brain host | none |
Doctor persistence_request_growth warns |
gbrain doctor --json |
the printed gbrain config set persistence.limits.<limit> <value> |
gbrain doctor --only persistence_request_growth --json |
brain host | none |
Working-tree sync prints legacy file(s) skipped … no contextual retrieval mode |
gbrain repair contextual-mode |
gbrain repair contextual-mode --apply |
the next gbrain sync --working-tree no longer prints the line |
brain host, after the user agrees | none |
Working-tree sync prints legacy file(s) skipped … not valid UTF-8 |
find <checkout> -name '*.md' ! -exec iconv -f UTF-8 -t UTF-8 -o /dev/null {} \; -print |
re-save each listed file as UTF-8 | the next gbrain sync --working-tree no longer prints the line |
user (re-saves the files) | none |
Doctor google_file_modes warns, or the upgrade printed [google] Google source <id> keeps its files in <dir>, outside ~/.gbrain |
gbrain repair google-file-modes --source <id> |
gbrain repair google-file-modes --source <id> --apply |
gbrain doctor --only google_file_modes --json (google_file_modes ok) |
brain host, after the user agrees | none |
Recall or hot memory returns facts from gbrain's own claude-cli sessions or from pasted text; doctor captured_facts_active warns; the upgrade banner prints captured_facts_active: N (explicit_kind_required; …) |
gbrain repair captured-facts (add --include-ambiguous to include paste candidates) |
gbrain repair captured-facts --apply --expect <hash> with the hash that preview printed |
gbrain doctor --only captured_facts_active --json (captured_facts_active ok) |
brain host, after the user agrees | destructive (quarantines facts) |
Recall, hot memory or takes treat an orchestrator's worker briefs as your own preferences or commitments; doctor agent_session_facts warns |
gbrain repair agent-session-facts (add --cwd <prefix> or --session <id> for sessions you know an orchestrator launched, --include-ambiguous for repeated openings) |
gbrain repair agent-session-facts --apply --expect <hash> --yes with the hash that preview printed |
gbrain doctor --only agent_session_facts --json (agent_session_facts ok) |
brain host, after the user agrees | destructive (re-attributes facts, retires takes) |
A stored fact reads [redacted](…) where a word such as "System" belongs; doctor facts_redaction_marker warns; trust scan flags the marker |
gbrain repair redacted-facts |
gbrain repair redacted-facts --apply --expect <hash> with the hash that preview printed |
gbrain doctor --only facts_redaction_marker --json (ok, or only facts the preview listed as ambiguous or unproven) |
brain host, after the user agrees | none |
Timelines put hundreds of facts on one day; doctor fact_bulk_dates warns that a day holds a bulk-loaded share of a source's facts |
gbrain repair fact-claim-dates --source <id> |
gbrain repair fact-claim-dates --source <id> --apply --expect <hash> --yes with the hash that preview printed |
gbrain repair fact-claim-dates --source <id> lists nothing to move (doctor keeps warning while facts without a date in the claim keep the load day) |
brain host, after the user agrees | none |
Doctor provenance_stamp_drift warns that pages lost their provenance stamps or trust marker, or would re-read above their stored tier |
gbrain repair provenance --source <id> |
gbrain repair provenance --source <id> --apply --expect <hash> --yes with the hash that preview printed |
gbrain doctor --only provenance_stamp_drift is ok |
brain host, after the user agrees | destructive |
A finished promise still shows on entity cards and in recall after its loop was closed; doctor loop_facts_drift warns; the upgrade banner prints loop_facts_drift: N (explicit_kind_required; …) |
gbrain repair loop-facts |
gbrain repair loop-facts --apply --expect <hash> |
gbrain doctor --only loop_facts_drift --json (loop_facts_drift ok) |
brain host, after the user agrees | destructive (retires facts) |
gbrain upgrade refuses with requires Bun >=<floor> (exit 78), or doctor self_upgrade_health says Auto-upgrade to <target> held |
bun --version |
bun upgrade, then gbrain upgrade (Bun floor) |
gbrain --version shows the target; gbrain doctor --only self_upgrade_health --json (self_upgrade_health ok) |
user | persistent_install |
Say to your agent: "After the upgrade, preview the captured-facts and
loop-facts repairs and tell me what each would expire before applying
anything." The agent runs gbrain repair captured-facts and gbrain repair loop-facts, shows you both lists, and after you agree runs each printed
--apply --expect <hash> command. See Captured facts and
Loop facts.
Hosted and thin-client callers see the same checks in gbrain remote doctor
as one line each, for example
timeline_history: ... host operator action required: on the brain host run gbrain doctor --remediation-plan.
A line that says Unknown: means the check could not run; it is not a clean
result. Ask the brain host's operator to run the steps above.
Upgrading to v0.60.30.0
Say to your agent: "We upgraded gbrain to v0.60.30.0. Preview the unlinked facts relink and the link re-derivation for each source, and tell me what would change before applying anything."
gbrain upgrade applies migrations v187 (fact relink attempts) and v188 (the
per-stint ontology dedup index). Restart every gbrain serve, autopilot and
worker so they run the new code, then work through what applies:
| Symptom | Check or code | Preview | Apply | Verify | Who acts | Consent |
|---|---|---|---|---|---|---|
| "Who invested in X?" or "Who attended ?" finds nobody; meeting attendance edges point meeting -> person, or notes-only mentions are typed attended | none | gbrain extract links --source db --repair-attendance --source-id <id> (attendance only, preview-bound) |
gbrain extract links --source db --include-frontmatter --source-id <id> per source; body links also re-derive on the next gbrain extract --stale |
gbrain graph <person-slug> shows person -> page invested_in / attended edges |
brain host, after the user agrees | none |
Facts saved without an entity are missing from entity recall and skipped as no_entity by the conflict sweep |
doctor unlinked_facts |
gbrain facts relink --dry-run |
gbrain facts relink (model tier capped by --max-usd, default $1.00) |
gbrain doctor (unlinked_facts); gbrain decide status |
agent, after the user agrees | paid (capped by --max-usd) |
remember answers warnings: ["NO_ENTITY"] |
none | none | pass entity, or name exactly one existing person or company in the text; gbrain config set facts.entity_inference off turns inference off |
the response carries entity_inferred or the chosen entity |
agent | none |
| A CLI write on PGLite pauses for up to 30 s, then fails lock-busy | lock busy | none | wait for the other CLI call, or stop the long-running non-serve holder (for example a jobs daemon) | re-run the write | agent | none |
The next gbrain eval suspected-contradictions estimates a full re-judge |
none | the printed cost estimate | run it after you agree (judge prompt v3 invalidated the cache once) | the run reports judged pairs | agent, after the user agrees | paid |
| Hybrid search on Postgres returns keyword-only results or hits the vector timeout | doctor vector_plan |
gbrain doctor |
upgrade and restart; to roll back: gbrain config set search.vector_legacy_guard true, then restart serve and autopilot |
gbrain doctor shows vector_plan ok |
brain host | none |
| Facts about you that came from pasted text or from gbrain's own claude-cli calls | doctor self_capture |
gbrain recall for the fact |
gbrain forget <fact id>; doctor self_capture prints one-time quarantine commands for old self-capture files |
gbrain doctor |
agent, after the user agrees | destructive (forgets the fact) |
Upgrading to v0.60.28.0
Say to your agent: "We upgraded gbrain to v0.60.28.0. Restart everything that runs it, then walk me through what doctor finds, in order, before changing anything."
Most of these fixes take effect only in a process that runs v0.60.28.0 or
later, so restart first. gbrain sources writer status --json lists, in
writer_versions[], the latest version each host and principal was seen
writing with in the retained requests. That is history, not proof: an idle
older gbrain serve never shows up there. Restart in this order:
- Stop autopilot and workers (
gbrain autopilot --statusnames the job;gbrain jobs workor your supervisor for workers). - Stop each resident
gbrain serve: HTTP services through their service manager, and harness-owned stdio servers by quitting the harness. - Upgrade each host:
gbrain upgrade. - Run
gbrain --versionthrough each launcher's own binary path (the path in the service definition, the harness MCP command, the hook commands) and confirm it prints0.60.28.0. - Restart services, harnesses, workers and autopilot.
- Make one write from each host, then confirm a fresh
last_seenfor that host ingbrain sources writer status --json(writer_versions[]).
Then recover what doctor names, in this order (skip a step whose check is ok):
gbrain doctor.- Legacy jobs (
legacy_job_authority): see Legacy job authority. - Projections (
text_projection_readiness):gbrain projections drain(Postgres, or PGLite with no resident); on PGLite with a resident, let it drain or stop, drain and restart it. See Drain queued text projections. - Stale atoms (
atom_provenance_drift):gbrain repair stale-atoms --source <id>, then after the user agreesgbrain repair stale-atoms --source <id> --apply --expect <hash>. - Extractor facts (
extractor_facts_expired):gbrain repair extractor-facts, then after the user agreesgbrain repair extractor-facts --apply --expect <hash>(add--include-ambiguousto both for ambiguous facts). See Extractor facts. gbrain doctoragain, thengbrain doctor --remediation-planfor the automatic kinds.
| Symptom | Check or code | Preview | Apply | Verify | Who acts | Consent |
|---|---|---|---|---|---|---|
synthesize fails every run; POST /ingest returns 409 (500 on an older gbrain); workers refuse to start with "legacy jobs have missing or unsupported authority" |
legacy_job_authority / permission_denied (legacy job authority) |
stop gbrain serve, autopilot and workers; gbrain jobs cancel <active id>; gbrain jobs authorize-legacy --select "status=waiting|delayed|waiting-children|paused" |
gbrain jobs authorize-legacy --select "<same filter>" --expect <hash> --yes, then restart |
gbrain doctor shows legacy_job_authority ok; /ingest returns 202 |
brain host, after the user agrees | paid (authorizes legacy jobs) |
| Search returns atoms quoting text a page no longer has, or atoms of deleted pages | doctor atom_provenance_drift |
gbrain repair stale-atoms --source <id> |
gbrain repair stale-atoms --source <id> --apply --expect <hash> |
gbrain doctor (atom_provenance_drift drops by the retired count) |
brain host, after the user agrees | destructive (removes stale atoms) |
sources add, claim, rebind, archive, remove, clone, reclone or sources writer transfer on a repo with more than ~10k files fails with "The verified source manifest exceeds the 1 MiB administration metadata bound" |
request_too_large |
none: upgrade and restart every writer host and resident gbrain serve |
Re-run the failed command (with the same --request-id if you kept it) |
gbrain sources writer status --json shows the source bound, and its manifest_digest is set |
agent | none |
A stdio agent bound with GBRAIN_SOURCE (or .gbrain-source) gets permission_denied naming the binding when it passes source_id |
permission_denied (hint starts "This connection is bound to source …") |
gbrain sources list (the source must show federated, not isolated or unset) |
gbrain sources federate <id> on the brain host |
Repeat the read with source_id: "<id>"; it returns only that source's rows. See explicit reads from a bound agent connection |
brain host, after the user agrees | none |
A new session's start-up context showed another session's text (Last session activity: …) |
none | none | Upgrade the gbrain each harness runs its hooks with and restart the harness. If you set GBRAIN_HOOKS=0 as a workaround, remove it from the environment the harness starts from (shell profile or service) and restart the harness again |
A new session shows no Last session activity line, and gbrain doctor reports bootstrap_hooks_heartbeat again after a few turns (capture and session persistence are back) |
user (upgrades and restarts the harness) | persistent_install |
connect --harness codex|claude-code|opencode --install stored the bearer token inline in the harness config without telling you |
receipt token_storage: "inline" |
On the brain host: gbrain mcp admin invalidate-tokens <client_id> --url <mcp_url> --admin-token-file <owner-admin-token-file> --json (only if the config file was exposed) |
gbrain mcp admin invalidate-tokens <client_id> --yes --if-version <revision> --url <mcp_url> --admin-token-file <owner-admin-token-file> --json, then gbrain connect <mcp_url> --harness <harness> --credentials-file <handoff> --install --fresh-token, then reload the harness |
The new receipt prints token_storage, config_path, renew_command and if_exposed, and the harness answers a memory round trip |
brain host, after the user agrees | credentials (invalidates tokens) |
A second brain's autopilot replaced the first one's job, logs interleave in ~/.gbrain/autopilot.log, or gbrain autopilot --status --json shows job.needs_reinstall: "legacy_shared_job" (or "wrapper_missing" after moving a brain); install refuses with autopilot_job_owned_by_other_brain |
gbrain autopilot --status --json (job.*) / autopilot_job_owned_by_other_brain |
GBRAIN_HOME=<brain parent> gbrain autopilot --status --json |
GBRAIN_HOME=<brain parent> gbrain autopilot --install (every non-default brain first, then the default brain) |
GBRAIN_HOME=<brain parent> gbrain autopilot --status --json shows job.needs_reinstall: null and the brain's own launchd_label / systemd_unit. See several brains on one host |
brain host, after the user agrees | persistent_install |
gbrain serve started in a .gbrain-mount project: CLI writes fail owner_unavailable and MCP writes stay queued |
owner_unavailable |
none | Upgrade and restart the resident gbrain serve (the harness that spawns it) |
gbrain sources writer status --probe --json from the project answers |
user (upgrades and restarts the harness) | persistent_install |
Backup coverage reports remote evidence: unavailable for a private remote that is pushed |
doctor backup_coverage |
none | Upgrade, then gbrain backup check |
gbrain backup status --json shows verification.state: "verified"; see remote unavailable |
agent, after the user agrees | persistent_install (upgrade) |
On Windows, a write or gbrain sync refuses a colon slug such as calendar:abc |
colon_slug_windows_write_through |
none | Use a slug without :, or write the page from a macOS or Linux host that owns the source |
The write succeeds, or gbrain sync no longer lists the file |
agent | none |
Search empty or incomplete after upgrading; doctor text_projection_readiness warns |
text_projection_readiness |
gbrain doctor --only text_projection_readiness --json (counts per class, also while a PGLite resident runs) |
gbrain projections drain --dry-run, then gbrain projections drain (Postgres, or PGLite with no resident; it seals sealable images too); on PGLite with a resident, wait for text, or stop, drain and restart per projection owner resident; reimport images: gbrain embed --stale --images --dry-run, then the paid run |
gbrain doctor shows text_projection_readiness ok |
brain host | none |
Error [projection_owner_resident] from gbrain projections drain (exit 2) |
projection_owner_resident |
gbrain doctor |
the printed stop, drain and restart commands | gbrain doctor |
brain host | none |
[gbrain] warning: OPENAI_API_KEY in this process's environment differs from openai_api_key …; doctor embedding_key_source warns |
embedding_key_source (provider key source) |
gbrain doctor (embedding_key_source) |
remove the variable and restart that process, or gbrain config unset openai_api_key |
the warning no longer prints; gbrain doctor shows embedding_key_source ok |
user (owns the key) | credentials |
The OpenAI embedding provider rejected its key (HTTP 401) |
embedding_auth_failed |
gbrain doctor (embedding_key_source, embedding_provider) |
the printed fix for the key source in effect, then gbrain embed --stale |
gbrain doctor shows embedding_provider ok |
user (owns the key) | credentials; paid for embed --stale |
| Conversation facts missing from recall after managed writes | extractor_facts_expired |
gbrain repair extractor-facts |
gbrain repair extractor-facts --apply --expect <hash> (ambiguous: add --include-ambiguous to both) |
gbrain doctor |
brain host, after the user agrees | destructive (rewrites expired facts) |
Recall still returns claims from a page you purged; doctor purged_page_facts warns |
purged_page_facts (purged page facts) |
gbrain repair purged-page-facts |
gbrain repair purged-page-facts --apply --expect <hash> --yes (no purge record: add --include-ambiguous to both) |
gbrain doctor |
brain host, after the user agrees | destructive (--yes) |
| Page history still shows a change reason quoting a claim you purged before upgrading | none (run the preview; purged change reasons) | gbrain repair purged-change-reasons |
gbrain repair purged-change-reasons --apply --expect <hash> --yes (same text under another path: add --include-ambiguous to both) |
the preview again finds 0, with unreadable_commit 0 |
brain host, after the user agrees | destructive (--yes) |
Facts missing from recall after a page write or extract_facts run, although no fence of their page held them; doctor unwithdrawn_facts warns |
unwithdrawn_facts (unwithdrawn facts) |
gbrain repair unwithdrawn-facts |
gbrain repair unwithdrawn-facts --apply --expect <hash> (ambiguous: add --include-ambiguous to both) |
gbrain doctor |
brain host, after the user agrees | none |
Recall returns conversation facts such as "Date said …" or "Attendees said …", or facts dated 1970-01-01; doctor conversation_label_facts warns; the upgrade banner prints conversation_label_facts: N (explicit_kind_required; …) |
gbrain repair conversation-labels (ambiguous: add --include-ambiguous) |
gbrain repair conversation-labels --apply --expect <hash> --yes, then the printed gbrain extract-conversation-facts --slugs … --dry-run |
gbrain doctor --only conversation_label_facts --json |
brain host, after the user agrees | destructive (retires facts; no model calls) |
Upgrading to v0.60.20.0
| Symptom or error text | Preview | Apply | Verify | Who acts | Consent |
|---|---|---|---|---|---|
gbrain upgrade said the upgrade failed, or migrations ran twice |
gbrain apply-migrations --list |
gbrain apply-migrations --yes |
gbrain doctor --only minions_migration --json (minions_migration ok) |
agent, after the user agrees | none |
another apply-migrations is running (host …, pid …) |
gbrain doctor |
wait, then gbrain apply-migrations --yes |
gbrain apply-migrations --list |
agent | none |
doctor orphan_persistence_bindings; a re-added source fails with writer_coordinator_required |
gbrain repair orphan-bindings |
gbrain repair orphan-bindings --apply |
gbrain doctor |
brain host, after the user agrees | none |
doctor stale_embedding_effects; writer_not_quiesced names an embedding effect |
gbrain repair embedding-effects --source <id> |
gbrain repair embedding-effects --source <id> --apply |
gbrain doctor (pending until the owner run commits a retry_queued effect) |
brain host, after the user agrees | none |
autopilot never syncs a connector, or prints has never synced |
gbrain sources status <id> |
gbrain sync --source <id> once |
gbrain sources status <id> |
agent | egress (fetches from the provider) |
a connector source keeps a stale local_path |
gbrain sources list |
gbrain sources set-path <id> --clear |
gbrain sources list |
agent, after the user agrees | none |
classic writes refused after leaving managed mode, or local_markers: pending |
gbrain sources writer deactivate --dry-run |
see the deactivate runbook | gbrain sources writer status on every host |
brain host, after the user agrees | none |
orphan-bindings and embedding-effects also run under gbrain repair --all
and gbrain doctor --remediate --include-repairs; embedding-effects is paid
work when it queues a retry. Retry commands: gbrain sources writer retry-effects <source> --request-id <id>
(one failed or parked effect), gbrain sync --source <id> --no-pull
(a failed sync write) and gbrain repair embedding-effects --source <id> --apply
(stuck embedding effects, including a used-up retry allowance).
Quarantine self-captured corpus files
gbrain doctor reports self_capture when the dream session corpus
(dream.synthesize.session_corpus_dir) still holds files captured from
gbrain's own claude-cli sessions. Dream and the sweep skip
the ones they can identify, but nothing removes them. The check never moves
or deletes files. It lists what it classified (a harness transcript under a
gbrain scratch project matches the file) and counts what it cannot decide (no
harness transcript is left for that session).
To quarantine the classified files on the brain host:
gbrain doctor --json > /tmp/gbrain-doctor.json
# Review the list first:
jq -r '.checks[] | select(.name=="self_capture") | .details.classified_sample[]' /tmp/gbrain-doctor.json
# Then run the exact commands doctor printed (one mkdir, one move per file, sidecars included):
jq -r '.checks[] | select(.name=="self_capture") | .details.quarantine_commands[]' /tmp/gbrain-doctor.json | sh
gbrain doctor --json | jq '.checks[] | select(.name=="self_capture") | .details'
The quarantine directory is a sibling of the corpus directory
(<corpus>.quarantine), so dream never reads it. Doctor prints at most 20 move
commands per run; rerun the sequence until classified reaches 0. Review the
unclassifiable files by hand; delete the quarantine directory only when you
are sure you do not need it.
Stale queued embedding effects
Say to your agent: "Doctor says an embedding effect is stuck and it blocks activation. Settle it."
gbrain doctor reports stale_embedding_effects when a committed write still
has an embedding effect that is queued an hour later with no consumer claiming
it, or that failed (for example after a provider outage). Either
one keeps the write receipt from compacting and blocks activation with
writer_not_quiesced. Preview, then apply after you agree, on the brain host:
gbrain repair embedding-effects --source <source> # predicts each effect's outcome
gbrain repair embedding-effects --source <source> --apply # settles them
gbrain doctor # verify: stale_embedding_effects is ok
Each effect ends in exactly one outcome; no obligation is dropped without one:
| Outcome | When | Spends |
|---|---|---|
reconciled |
The page's current chunks already pass the effect's verifier (same revision, selected column, model and hashes). The effect commits. | Nothing |
superseded |
The page was deleted, or a newer revision of the same page owns its own embedding effect. The effect commits as superseded. | Nothing |
retry_queued |
The owner embeds it: a stale queued effect is re-queued; a failed one gets the retry-effects allowance; when that allowance is used up (embedding_retry_exhausted), one new bounded retry cycle, once per explicit apply. |
Provider calls, up to the bounded retry budget |
blocked |
Nothing changed. owner_unavailable (run it on the owner host), embedding_disabled or embedding_unconfigured (configure embeddings first), projection_pending (sync the page first) or no_replacement_obligation (the page changed without a newer embedding obligation; run gbrain embed <slug> --source <source>). |
Nothing |
retry_queued is not success: doctor keeps the effect pending until the
owner's run commits it. The preview marks retries as paid work; through
gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --max-usd <n>, the estimate
covers the whole retry budget each grant authorizes. A resumed run replays the
grant it already made instead of granting another cycle. A signature-mismatched
vector is never reconciled; it is re-embedded.
Recorded-time reads
get_page {known_as_of} and get_versions {known_as_of} read a page as this
brain had recorded it at an instant, from the belief ledger
(design, section 10).
known_as_of is recorded time: an ISO 8601 instant with a zone. It is not
as_of on get_links, which is valid time (a date). A read answers with the
interval the instant falls in, certified (false with uncertified_reason on
an unmanaged source, a drifted interval or a truncated walk), and a body of
live, version, segmented (body_ref gives its size; no read serves an
older segmented body yet) or unavailable
with a body_reason (purged, expired, hard_deleted, pruned,
version_missing). A body no retained version holds is disclosed, never
borrowed from the version next to it. The refusals below change nothing; run
gbrain beliefs status --source <id> --json to see the coverage a read is
checked against.
Coverage from
The ledger does not cover the instant: it is before the ledger was enabled on
the source, or before the page's baseline cut. Earlier times are unknown, not
empty. reason is not_recorded, or backfill_only / backfill_incomplete
when gbrain beliefs backfill seeded best-effort history for the page: that
history carries source times only, so it never answers a recorded-time read.
Ask about an instant at or after the time the message names.
Coverage gap
The ledger was not recording at the instant: coverage was stopped
(reason: not_covered), or a backup restore replaced the ledger with an
archive, and what happened between the archive's time and the restore is
unknown (reason: restore). Ask about an instant outside the gap the message
names.
Clock mismatch
known_as_of got a calendar date (reason: date_for_instant). A date is
valid time; recorded time needs an instant. Pass a full instant such as
2026-10-01T12:00:00Z.
get_page as_of got an instant (reason: instant_for_date). as_of is valid
time: the date an edition was in force, so pass the date alone
(2026-10-01). For the page as the brain had recorded it at a moment, pass
the instant to known_as_of instead (valid time).
Known as of unproven
A change to the page was recorded before the instant, but nothing proves it
had committed by then: its commit mark is later, and no later write to the
same page was recorded by the instant (section 5.3 of the design). The page at
that instant can't be stated either way, so the read refuses rather than
guess. The refusal is retryable: ask about an instant before the write's
recorded time, or after its commit was observed (the message names the write).
A stalled transaction stays unproven until it commits and is marked.
What changed in a window
gbrain beliefs changes [<entity>...] [--since 7d] (and delta {beliefs: true}
for agents) lists each fact, take, link and page that ended the window
different from how it started: before, after, the event that caused it and
its event id. An edit and its revert report nothing. earlier value unknown
means no recorded body answers for the start of the window, not that the
belief was absent; end by <date> is a relationship end the nightly check
inferred, so it ended on or before that date. A window that starts before the
ledger was enabled says where coverage starts. On a thin client the command
runs through the host and lists only world beliefs on pages visible now
(design, section 15).
Repair refusal codes
Each heading below is the docs anchor a refusal carries.
Explicit-only repair kinds
google-file-modes, stale-atoms, extractor-facts, unwithdrawn-facts, captured-facts, agent-session-facts,
loop-facts, ontology-facts, file-drift, missing-tables, segmented-mirror and secret-spans run only when named: gbrain repair <kind> previews, and
gbrain repair <kind> --apply applies (every kind but google-file-modes
also needs --expect <hash>, so it applies exactly the previewed set; google-file-modes re-checks each file's owner,
type and mode at apply time). They are excluded everywhere else:
gbrain repair --all(andgbrain repairwith no kind) lists each with its preview command (--json:explicit_kinds[]) and never runs it. A--all --applyrun exits 0 when only explicit-only kinds remain.gbrain doctor --remediation-planprints them in anExplicit-only repairsblock (--json:explicit_repairs[], each{kind, code: "explicit_kind_required", preview_command, docs}), never as a repair step.gbrain doctor --remediate --include-repairsclassifies a finding only an explicit-only kind clears asexplicit_kind_required, with the preview as itscommand. That class does not fail the exit status.- The
gbrain post-upgradebanner prints such a finding as<check>: N (explicit_kind_required; preview with: gbrain repair <kind>).
open-facts is not in these lists: its preview needs --source and
--created-before, which only you can name, so no listed command would run
as printed.
A remediation step or any other runner that reaches an explicit-only kind
without its name refuses with explicit_kind_required. A build that does not
implement the kind refuses with unavailable.
Preview changed
preview_changed: the hash passed with --expect names no saved preview, the
saved preview is older than 7 days, or the selection no longer matches it (for
stale-atoms, a different --source). Nothing was applied. The message reads
"The preview changed since ; re-run and use the new
hash." Re-run the printed preview command and apply with the new hash. It
applies to gbrain jobs authorize-legacy --select, gbrain jobs cancel --select, gbrain repair stale-atoms, gbrain repair extractor-facts,
gbrain repair unwithdrawn-facts, gbrain repair captured-facts, gbrain repair agent-session-facts and gbrain repair loop-facts.
Recovery bundle unsupported
recovery_bundle_unsupported: gbrain repair stuck-recovery found a
shared-skill bundle recovery record (several skill files published together)
that this binary cannot read: an unknown shape, or more files than a bundle
holds. A readable bundle record is resolved like a page recovery (see
stuck recovery). Nothing was changed. The preview lists it
under refused, and its fix is ask_user with the exact preview command;
naming it with --request-id refuses with this code. Upgrade gbrain on the
brain host and preview again, or ask the user which version of each skill file
to keep, put those bytes in place by hand, and let the resident writer finish
the recovery.
Recovery prior stage unavailable
recovery_prior_stage_unavailable: gbrain repair stuck-recovery can't apply
that --keep choice to a page recovery whose prior file is over the 24 MiB
single-string ceiling, and nothing was changed. Such a recovery keeps its prior
bytes as a staged copy beside the file, named in the record by path and
SHA-256, and that copy is missing, doesn't match its recorded SHA-256, or isn't
a regular file. Without it --keep prior has nothing safe to put back. The
refusal's fix is the remaining exit, the --keep disk apply under the same
preview hash (next: ask_user, because it keeps the edit and abandons the
write), with gbrain sources writer status --source <id> --json as its
verify. When the staged copy isn't a regular file, --keep disk can't back
it up either; the fix is then that read-only status, and the preview offers
the choices again once the path holds a regular file.
Builds before this one listed every large-file recovery as refused with
recovery_large_file_unsupported and had no exit for it; this build resolves
them with gbrain repair stuck-recovery.
Recovery choice refused
recovery_choice_refused: gbrain repair stuck-recovery will not apply that
--keep choice to that request, and nothing was changed. Either the request is
terminal while its recovery record is still set (its outcome is immutable,
recovery never restores its file, and --keep prior would roll back committed
bytes; the record only waits for staging cleanup, see gbrain sources writer status --source <id> --json), or the record cannot support the choice
(--keep prior without stored prior bytes, or a blocked path that is not a
regular file), or a record in the approved preview does not offer that choice
(--keep disk or --keep prior on a withdrawal-mirror effect, --keep withdrawn on a page or bundle; refused before anything runs, so narrow the
preview with --request-id). The preview lists only the choices it can make
safe.
Recovery effect unsupported
recovery_effect_unsupported: a withdrawal-mirror effect recovery blocks the
source's worktree, and its record cannot be written forward: it holds no
usable withdrawn bytes (missing or corrupt), or it was recorded for another
owner epoch, root or source incarnation. A usable record is resolved with
--keep withdrawn (see stuck recovery). That recovery
only finishes forward (it never restores the bytes from before a withdrawal),
so nothing was changed. The preview lists the effect as refused, and its
fix is ask_user with the exact preview command
(gbrain repair stuck-recovery --source <id> --request-id <request>) and a
user_message to relay; naming its request with --request-id refuses with
this code and the same fix. The user copies the edited file aside and puts it
back to its committed version (never deletes it); the resident writer then
finishes the effect, and the edit is made again without the forgotten fact. A
sync queued behind a stuck effect stops at once with
drain_stalled, cause: head_blocked, and
its fix runs the stuck-recovery preview.
Legacy job authority
permission_denied with this anchor means a queued job row has SQL NULL
submission_authority, left by an upgrade across v0.50.
- A resubmission over a dead or cancelled legacy key releases the key and queues a fresh job. No step needed.
- A completed or failed legacy row is reused by local producers (synthesize,
autopilot,
POST /ingest). No step needed. A remotesubmit_jobcaller is refused and resubmits with a new idempotency key. - A live legacy row (waiting, delayed, waiting-children, paused, active)
blocks every worker, so nothing reuses it.
POST /ingestreturns 409{error, message, hint, docs_url}, never 500.
gbrain doctor (legacy_job_authority) counts exactly the rows that block workers,
split into authorizable (SQL NULL) and unsupported (non-NULL) rows, and prints the
filled commands. Recovery, in order:
- Stop producers and workers: the resident
gbrain serve,gbrain autopilot,gbrain jobs work/ supervisor. - Cancel each active job the hint or doctor names:
gbrain jobs cancel <id>. (Stall and timeout sweeps are behind the same gate, so an orphaned active row never finishes on its own.) - Preview:
gbrain jobs authorize-legacy --select "status=waiting|delayed|waiting-children|paused"(narrow with,name=<job>|<job>). It lists counts by job name and status, the first 20 ids, marks paid-provider job names, and prints a hash.--jsonhas the full rows. - Apply exactly that set with the printed command:
gbrain jobs authorize-legacy --select "<same filter>" --expect <hash> --yes. To drop work instead,gbrain jobs cancel --select "<filter>"previews and its printed--expect <hash> --yescancels exactly the previewed set. - Unsupported non-NULL rows cannot be authorized: run matching application and
database versions, or cancel them (
gbrain jobs cancel <id>, as doctor lists). - Restart producers and workers. Verify:
gbrain doctorshowslegacy_job_authorityok;POST /ingestreturns 202.
Legacy jobs active
legacy_jobs_active: authorize-legacy --select/--ids or jobs cancel --select
found active jobs. Legacy review needs nothing active. Stop producers
(gbrain serve, gbrain autopilot) and workers, cancel the listed jobs
(gbrain jobs cancel <id>; the refusal lists up to 10, the rest with
gbrain jobs list --status active), then re-run the preview it names.
Legacy job selection invalid
legacy_job_selection_invalid: --select named an unknown key or value, a
flag combination was wrong (--ids with --select; apply without both
--expect <hash> and --yes), a selected row no longer exists or is not SQL
NULL, or a jobs cancel --select selection would also cancel a job outside it
(the message names those ids; cancel them on purpose or widen the filter). The
grammar is --select "status=<s>[|<s>…],name=<job-name>[|<name>…]"; the
message lists the valid statuses, and the hint is a complete example.
Projection owner resident
projection_owner_resident (exit 2): gbrain projections drain did not run
because a gbrain process (named with its pid) holds this PGLite brain. Nothing
changed. The resident drains queued Markdown and code itself; re-run
gbrain doctor to watch the counts in text_projection_readiness (doctor asks
the resident over its local socket, so the counts show while the resident
runs; a resident that does not answer, or answers without the image classes,
runs an older gbrain, so restart it on the current version).
The resident never seals images, so sealable image pages need the database
to itself. Doctor's fix is then a two-step action the user runs: stop the
owner, run gbrain projections drain --limit <n>, start the owner again. Its
message names the image count and how long the owner is down per drain run;
harnesses connected through that gbrain serve disconnect until it restarts.
Verify with gbrain doctor --only text_projection_readiness --json, which
reads the counts through the restarted resident.
To drain faster, stop the owner, drain, then restart it. The restart runs whether or not the drain failed:
| Owner | Stop, drain, restart |
|---|---|
gbrain serve service, launchd |
launchctl bootout gui/$(id -u)/com.gbrain.serve && { gbrain projections drain; launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.gbrain.serve.plist; } |
gbrain serve service, systemd |
systemctl --user stop gbrain-serve.service && { gbrain projections drain; systemctl --user start gbrain-serve.service; } |
| autopilot, launchd | launchctl bootout gui/$(id -u)/com.gbrain.autopilot && { gbrain projections drain; launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.gbrain.autopilot.plist; } |
| autopilot, systemd | systemctl --user stop gbrain-autopilot.service && { gbrain projections drain; systemctl --user start gbrain-autopilot.service; } |
a manual gbrain serve |
stop it (kill <pid>), run gbrain projections drain, then start gbrain serve again |
The rows above show the default brain's names. The refusal prints these
commands filled in: with --brain <id> for a mounted brain, and with this
brain's own autopilot job (or the shared job an older install still runs it
from) for a brain under another GBRAIN_HOME. The autopilot launchd label
follows GBRAIN_AUTOPILOT_LABEL when set.
Page projection conflict
page_projection_conflict (retryable): another worker installed a newer
search projection (chunks and text seal) of the same page while this command
prepared its own, at an unchanged page revision. The usual other worker is the
persistence owner's resident projection rebuild (gbrain serve or autopilot);
an embed or import run can be one too. Nothing was installed by the losing
command, and the newer projection is kept. detail names what changed:
text_projection_revision (the page was sealed), chunk_digest (its chunk
set changed) or indexing_context (the embedding column, model, chunker
version or another indexing input changed).
Callers that install a projection re-read the page and prepare again up to
three times before reporting this code. To recover, re-run the same command;
it re-reads the current projection. If it conflicts again, another worker is
still installing: wait for it to finish (gbrain doctor shows the pending
count in text_projection_readiness), then re-run. gbrain get --source <id> -- <slug> shows the page as stored now.
File removed during scan
file_removed_during_scan is a non-fixable gbrain lint issue: a file the
scan listed was deleted or renamed before lint read it, so that file was not
linted. Lint continues with the remaining files. Re-run gbrain lint <target>
to check the files that exist now. On a managed brain, lint --fix instead
reports the page as a pending canonical_file_missing repair (counted in
fix_pending); see
lint repairs waiting on a managed brain.
Fix not writable
fix_not_writable is a non-fixable gbrain lint --fix issue: lint found a
fixable problem but the file refused the write (EACCES, EPERM or EROFS:
its permissions or a read-only mount), so the file was left unchanged. The
issue's reason is the lowercased errno. Lint continues with the remaining
files and counts the page in fix_pending; the cycle's lint phase reports
warn, not fail. Make the file writable by the user running gbrain, or pass
its directory or file name to gbrain lint --exclude, then run lint again.
Setup refusals
gbrain setup <harness> resolves the brain, source, transport, launcher and
registration owner before it writes anything, and refuses with one of these
codes when that target is not safe to wire. A refusal writes nothing. Guide:
connect an agent with gbrain setup.
Setup harness unsupported
setup_harness_unsupported: setup wires Claude Code and Codex in this release.
The message names the guide for the harness you asked for (OpenClaw:
docs/mcp/OPENCLAW.md, Hermes:
docs/mcp/HERMES.md); follow its manual steps.
gbrain setup --help lists the supported harnesses.
Setup owner conflict
setup_owner_conflict: something setup does not own holds the target. The
reason says which:
live_serve: a runninggbrain serveholds this PGLite brain's single-writer lock and is not the server this setup registered. A stdio registration would start a second server that fails on the lock. Stop that server (quit the agent session that started it), or keep it and connect through it: a sharedgbrain serve --httpis wired withgbrain bootstrap harness --harness <claude-code|codex>.unowned_entry: the harness configuration already has an entry under the same MCP server name, and its hash is not one this setup recorded (you or another tool wrote it, or you edited it). Setup never overwrites it. A bareclaude mcp addorcodex mcp addregistration is the usual cause: keep it and rungbrain setup <claude-code|codex> --instructions-only, which adds the brain-first block and the per-turn hook and leaves the entry alone. Or pick another name with--name, or remove that entry yourself and run setup again.other_install: the connection receipt for this name belongs to a gbrain install with a differentGBRAIN_HOME. Run setup with--name <other>so each install owns its own entries.harness_lane:gbrain bootstrap harness(or a workspace bootstrap install) already wires gbrain hooks or MCP in this configuration (a harness target in another HOME's orCODEX_HOME's config directory does not count; project-scoped hooks do). Keep that wiring, or remove it withgbrain bootstrap harness --removefirst. On Codex this also fires when the bootstrap Codex lane'sSessionEndhook is inhooks.jsonand you passed--capture: keep that lane and run setup without--capture.
gbrain setup claude-code --dry-run --json shows the resolved target and the
blocking owner without writing anything.
Setup hosted connection
setup_hosted_connection: this machine already reaches a hosted brain (a
thin-client config from gbrain init --mcp-only, a remote gbrain entry in
the harness configuration, or a gbrain connect --install receipt), and no
gbrain setup receipt owns it. Setup never falls back to a new local brain,
because sessions would then read an empty brain while useful memory stays on
the hosted one. Manage that connection with gbrain connect <mcp-url> --harness <claude-code|codex> --install; gbrain doctor --only harness_wiring shows
which brain the registration reaches. The skill resolver needs no local brain:
set it up there with gbrain setup <claude-code|codex> --skills-index-only --skill-loading resolve.
Turn hook not loaded
turn_hook_not_loaded: the per-turn hook that puts "check GBrain first"
beside every user turn is not running in the harness. Agents use the brain
when that rule reaches them on every turn; the MCP tool list or an
instruction file alone rarely gets the brain used. The reason says what
the install check found:
missing: no gbrain per-turn hook is configured for the harness.untrusted: the hook is configured but the harness will not run it yet (Codex: no matching trust entry, trust it in/hooks; OpenClaw:hooks.allowConversationAccessis off; Hermes: the command is not inshell-hooks-allowlist.json).hook_failed: the Claude Code or Codex hook command exited non-zero.no_rule: the hook ran but added no rule, usually because the brain-first block for that harness was opted out.not_loaded: the harness's own check does not show the hook loaded.
Run fix.argv (it re-runs the install that writes the hook), then check
with the harness's own command:
| Harness | Check |
|---|---|
| Claude Code | /hooks in a session lists the UserPromptSubmit hook |
| Codex | /hooks in a session; trust the hook there if it asks |
| OpenClaw | openclaw plugins inspect gbrain-turn-rule --runtime --json shows it loaded with before_prompt_build |
| Hermes | hermes hooks doctor shows the pre_llm_call hook healthy |
gbrain doctor --only harness_wiring --json reports the same state per
harness. opencode and Cursor have no per-turn hook gbrain can install; the
rule reaches them through their instruction file only.
Hook starts gbrain in the session directory
hook_session_cwd: a hook that gbrain setup <claude-code|codex> or the
turn-rule lane wrote, a stdio MCP entry for gbrain serve (#8426), or a hook
from gbrain bootstrap hooks, gbrain bootstrap harness or its Codex
SessionEnd capture (#8428) starts gbrain in the session's working directory. With a
script-mode install (bun install -g, bun link) Bun reads that directory's
bunfig.toml (a top-level preload runs before any gbrain code) and its
.env files first, so opening a session in a cloned repository would run that
repository's code on every prompt. Current hooks start gbrain through
<gbrain config dir>/hook-launcher/gbrain-hook, which records the session
directory in GBRAIN_HOOK_CWD and runs gbrain from its own directory. The
reason says what doctor found:
session_cwd: the hook was written before the launcher existed.missingorstale: the hook names the launcher, but it is gone, changed or not executable, or (on abun install -ginstall) it records no Bun or a Bun that is no longer there, so a harness started without bun on PATH, like the Codex app, cannot start gbrain.foreign: the launcher's directory holds a file gbrain did not write. The launcher refuses to start gbrain there (the hook exits 1 with one stderr line) until you remove it.
Run fix.argv (gbrain setup <harness> for setup's hooks,
gbrain setup <harness> --instructions-only for the turn-rule hook);
gbrain post-upgrade rewrites a stale launcher file in place (no entry or
trust changes), and moves every user-scope hook it can find except
gbrain setup codex's, which only setup rewrites because the rewrite re-trusts
them; post-upgrade prints that command instead. A project-scope
install is refreshed from its project directory. A setup hook you edited after
setup wrote it (edited: true) is never rewritten, so the fix is a
user_message: remove or rewrite that entry, then run setup. When the check
already carried another warning with its own fix, that code and fix stay, and
the launcher fix is in details.hook_launcher_fix; run it after the first fix. Check with
gbrain doctor --only harness_wiring.
An MCP entry or a bootstrap hook carries its own command. A user-scope MCP
entry setup still owns gets fix.argv gbrain setup <harness>, and
post-upgrade moves a Claude Code one itself; a Codex one only gets the setup
command printed, like setup's Codex hooks. An entry you edited after setup
wrote it is kept, so the fix is a user_message to remove or rewrite it
first. A gbrain bootstrap entry names gbrain bootstrap hooks --harness <harness> --repair from the workspace directory, and a gbrain bootstrap harness hook names gbrain bootstrap harness --harness claude-code; both
are the user's to run, since those writers change the workspace or re-trust
Codex hooks.
Connection notices
Two notices tell an agent, on its own MCP connection, why something it expected is out of reach. Neither changes what the connection can call.
Grant blocked operations
grant_blocked_operations (info): this connection's grant cannot call some
operations its scopes allow. The notice says which proven blocker applies,
with counts and never operation names: the grant's operation snapshot, the
client's stored tool surface (a pin the brain owner set), or the server's
tool surface. A missing scope is named only on a refused call, because it is
how the grant was issued. Grant age is kept apart from the blockers: a grant
whose snapshot was written before snapshots recorded their operation catalog
says "this grant's snapshot excludes N currently eligible operations;
original intent unknown", and only a grant with recorded catalog provenance
says it predates operations. Operations outside the grant's scopes are never
counted, so a writer is not told about admin-only operations. A snapshot the
owner narrowed on purpose (catalog provenance recorded, and every operation it
leaves out existed when it was written, as with a guest broker's
--operations list) blocks nothing by mistake, so the notice comes only with a
refused call, never on a call the grant can make.
It arrives once per session: once per (principal, transport session) on
stdio and HTTP, and for a stateless HTTP call with no session id once per
(principal, grant revision), so a rescoped grant is diagnosed afresh.
fix.next is tell_user_to_run: the brain owner previews the change on the
brain host and then applies it (then). For an OAuth client that is
gbrain auth rescope --client <client_id> --operations <OPERATIONS> --surface full --dry-run
(--surface full only when the stored surface also blocks), then the same
command without --dry-run; for a legacy token,
gbrain auth rescope --id <token_id> --refresh-operations and then
... --add <OPERATIONS>. The owner chooses <OPERATIONS>. When only the
server's tool surface blocks, no grant change lifts it, and the fix is the
read-only doctor check that names the setting. fix.verify is read-only:
gbrain doctor --only grant_new_ops_available --json on the host, or
whoami on the same connection (its grant_diagnosis field carries the same
diagnosis). Nothing widens automatically; see
grants that cannot reach new operations.
Hidden tool content
hidden_tool_content (info): a page read, search or query left out takes
(page reads and search never include the takes table for an agent-facing
reader) and the tool that lists them, takes_list, is not in this
connection's tool list. The notice counts the takes and names the result's
own pages, and its fix is the next step this connection can actually take:
takes_listis callable but not listed (an advertised surface narrower than the callable one): the fix is thetakes_listcall itself, and a stdio session also adds it to its tool list. A client that ignorestools/list_changedcan still call it by name.- one
request_tools {surface}call would make it callable: the fix is that call (stdio: this session only, nothing written; HTTP: the client's own surface, within the server ceiling and never past an operator pin). - otherwise only the brain host can change it: on HTTP the fix is the grant
repair from
grant_blocked_operations; on stdio it is the tool's CLI equivalent, relayed to the user.
A fix never names a call the connection cannot make: read-only access,
operator pins, the grant's snapshot and GBRAIN_MCP_FORCE_SURFACE all hold.
Related
- Write refusal reasons — what a refused write means and the recovery command
- Concurrent writes and durable receipts — receipts, retries and capacity limits
- v0.60.5.0 upgrade steps — backup-first upgrade steps for a brain older than v0.60.5.0
- Topologies: claim and activate runbook — quiescence checklist, the writer admin lock