Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: restore write-refusals.md, which 5bf33c75 truncated, keeping its sync_write_through_off row

garrytanf4c714724e18
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 17bdf87a72..b423bc044f 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -55,10 +55,10 @@ of making a duplicate.
| <a id="canonical_file_missing"></a>`canonical_file_missing` | `source_changed` (a caller write; maintenance refuses before admission) | The page's recorded canonical file is gone while its database page is still live (a ghost page: the file was moved or deleted outside gbrain). A caller write refuses with "The canonical file was removed outside coordinated publication." and nothing is written; retrying it refuses the same way. A maintenance write (fact-fence adoption, enrichment, `dream`) is refused before admission: no request id, no receipt (before #6696 each cycle settled a `conflict` receipt). `gbrain sources writer failures <source>` reports such receipts as category `canonical_file_missing`. Neither copy was changed. | Decide which copy is right. If the file should exist, restore it at its recorded path and preview the page with `gbrain sources reconcile <source> <slug> --brain host --preview`, or sync. If the page should go, preview the ghost-page repair with `gbrain repair ghost-pages --source <source>` (read-only; it prints the apply command with its hash) and apply it with `--apply --expect <hash> --yes` only after the user agrees; a soft-deleted page can be restored with `gbrain restore <slug> --force` until the autopilot purge 72 h later. `gbrain pages ghosts --source <source>` and doctor `ghost_pages` list them, doctor `maintenance_write_drift` lists held-back maintenance writes. See [ghost pages](repair.md#ghost-pages). |
| <a id="refusal_breaker"></a>`refusal_breaker` | the code of the earlier refusals | The same maintenance write (same source, slug, page revision, planner and intent) was refused `persistence.maintenance.refusal_breaker_threshold` times (default 3; `0` turns it off) in the last 24 hours, so maintenance submits nothing for it instead of adding another receipt (#6696). It is tried again once the page, the planner or the write changes, or when the oldest refusal is 24 hours old. | Read the last refusal with `gbrain write-request -- <request_id>` (named in the message) and fix what it names. Doctor `maintenance_write_drift` lists every held-back write with its exit. |
| <a id="canonical_file_absent"></a>`canonical_file_absent` | `source_changed` (`restore_page` / `gbrain restore`) | On a brain without managed persistence, a restore that writes no file (`sync.write_through` off, a sandbox, a database-only source) of a soft-deleted page whose recorded file is no longer among the files sync imports (#6609). A plain restore would be undone by the next `gbrain sync --full`, so nothing was restored. Not retryable; the fix asks the user. | Ask the user. To keep the page with its file: put the file back at its recorded path, commit it and `gbrain sync --source <source>`. To keep it database-only: `gbrain restore <slug> --source-id <source> --detach` (MCP `restore_page` with `detach: true`), which forgets the recorded file and stamps `database_only_reason='detached'`. See [restoring a page whose file is gone](../storage-tiering.md#restoring-a-page-whose-file-is-gone). |
-| <a id="pending_import"></a>`pending_import` | `source_changed` (detail `file_database_drift`, reason `pending_import`) | The page's canonical file holds a change committed through Git (another agent's commit, a pull) that managed sync has not imported yet: the file on disk is exactly the blob `HEAD` holds for its path and not the one the source's last imported commit holds. The message is "The canonical file holds a committed Git change that sync has not imported yet." Nothing was overwritten. Since #6693 the receipt records origin `pending_import`; a write refused because sync holds the file records origin `sync_held` (see [held files](#held-files-and-content-refusals)). | A `remember` needs nothing from the caller: its `fix.next` is `wait`, the fact is kept in the receipt, and the first managed sync that imports the file (any outcome, a partial run included) makes one replay attempt on the original caller's lane with the fact's original `valid_from` and expiry (the sync result's `replayedRemembers` counts examined, replayed, waiting, skipped, remaining; at most 50 per run and 30 s). Do not save the fact again. A remember refused while sync held its file is replayed the same way once the repaired file is imported. A replay that is refused (authority revoked, page rewritten) stays listed by `gbrain repair failed-writes --source <source>` for a person. Any other write (`put_page`, `add_timeline_entry`) is never replayed automatically, because its body would replace the imported change: wait for the source's running sync owner (`gbrain serve`, autopilot or a sync job) to import the commit, which the refusal's read-only fix `gbrain sync status --source <source> --json` shows, then read the page again and resubmit with a new request ID. Neither refusal tells the caller to start a sync, because a second sync beside a running owner competes with it; when status shows no owner running, ask the user to sync the source on its host. An uncommitted hand edit still refuses `f... (line truncated to 2000 chars)
+| <a id="pending_import"></a>`pending_import` | `source_changed` (detail `file_database_drift`, reason `pending_import`) | The page's canonical file holds a change committed through Git (another agent's commit, a pull) that managed sync has not imported yet: the file on disk is exactly the blob `HEAD` holds for its path and not the one the source's last imported commit holds. The message is "The canonical file holds a committed Git change that sync has not imported yet." Nothing was overwritten. Since #6693 the receipt records origin `pending_import`; a write refused because sync holds the file records origin `sync_held` (see [held files](#held-files-and-content-refusals)). | A `remember` needs nothing from the caller: its `fix.next` is `wait`, the fact is kept in the receipt, and the first managed sync that imports the file (any outcome, a partial run included) makes one replay attempt on the original caller's lane with the fact's original `valid_from` and expiry (the sync result's `replayedRemembers` counts examined, replayed, waiting, skipped, remaining; at most 50 per run and 30 s). Do not save the fact again. A remember refused while sync held its file is replayed the same way once the repaired file is imported. A replay that is refused (authority revoked, page rewritten) stays listed by `gbrain repair failed-writes --source <source>` for a person. Any other write (`put_page`, `add_timeline_entry`) is never replayed automatically, because its body would replace the imported change: wait for the source's running sync owner (`gbrain serve`, autopilot or a sync job) to import the commit, which the refusal's read-only fix `gbrain sync status --source <source> --json` shows, then read the page again and resubmit with a new request ID. Neither refusal tells the caller to start a sync, because a second sync beside a running owner competes with it; when status shows no owner running, ask the user to sync the source on its host. An uncommitted hand edit still refuses `file_database_drift` and needs reconcile. |
| <a id="sync_write_through_off"></a>`sync_write_through_off` | `unavailable` (`forget` / `forget_fact`, detail `sync_write_through_off`) | `sync.write_through` is off and a canonical file carries the claim. The struck row would not reach the file, so a brain rebuilt from Git would bring the claim back; nothing was withdrawn. A claim that only database-only pages carry is still withdrawn. | `gbrain config set sync.write_through true`, then forget the fact again. |
-| <a id="shared_origin"></a>`shared_origin` | `source_changed` (purge, or a delete whose survivor changed); a soft delete commits with `write_through.skipped: shared_origin` | Two live pages of one source recorded the same canonical file (a duplicate-origin twin: the shared file renders one of them, so a delete of either used to refuse `file_database_drift`, reconcile refused "Several pages claim the recorded canonical file" and every managed sync refused `page_identity_changed`). A soft delete (`gbrain delete <slug> --source-id <id> --expected-revision <rev>`) of a page whose file another live page records now keeps the file and publishes database-only: the selected database page is hidden; the file and the surviving page remain. This does not erase that file's contents. The receipt's `write_through.warning` says so and names the surviving slug to the trusted local owner, or to a remote writer whose grant and visibility cover that slug; other remote writers read a generic "another page of this source records the same file". Sync's census and both origin guards apply one rule: a live page wins over tombstones, several live pages refuse, a single tombstone may be reused, several tombstones stay ambiguous. An owner purge (`--purge`) of a shared-origin page refuses with this reason: a purge tombstones the content source-wide and a same-content survivor would refuse `purged_content` on its next import. The 72 h retention purge (the autopilot purge phase, `gbrain pages purge-deleted --older-than 72h --yes`) of such a page once it is soft-deleted writes no tombstone, so it removes the page row, its chunks, links and facts database-only and leaves the file and the surviving page untouched (#7311); a census that changed under it defers to the next run, which re-reads the claimants and, when the tombstone now owns the file alone, purges it normally, file included. A delete whose surviving claimant changed between preparation and publication (the file moved or removed, a surv... (line truncated to 2000 chars)
-| <a id="writer-coordinator-required"></a>`database_guard` or `database_trigger` | `writer_coordinator_required` (or `storage_error` for another trigger) | A database trigger refused a row while a write was being prepared or published, so nothing was committed and any canonical file already replaced was restored. With `database_guard`, a gbrain process wrote a row its publication does not own (another source, an unresolvable source, or a source checkpoint/topology change outside owner administration). This is a gbrain defect or a version mismatch between gbrain processes sharing the database, not a content conflict. The exception is relationship `unreadable_state` (#7636): the database role gbrain connects as cannot see the writer state the guard reads (the `persistence_brain` or `git_canonical_brain` row, or the source or page row the write names) because row-level security hides it, or a `persistence_brain` / `git_canonical_brain` row is missing, so the guard refuses instead of letting the write through as if the brain were unmanaged or the row absent. A derived-state maintainer trigger raises the same refusal (#7637, raiser `gbrain_forget_page_retrievals`, `gbrain_queue_page_projection` and the others [listed in ENGINES.md](../ENGINES.md#derived-state-maintainers)) when row-level security applies to the role on a table it keeps up to date and the role holds no policy for it there, instead of leaving that derived state stale. The receipt's `write_error_detail` names the table, operation, guard branch, source relationship and stage; it never contains page text or source names. For another trigger it also carries a closed `reason`: `attribution_unclassified_table` or `trust_unclassified_table` (a gbrain stamp trigger met a table it is not built for: a version mismatch), `graduation_in_progress` (the engine-graduation fence, SQLSTATE 55000, refuses writes until the move finishes: retry later), or `unknown` (an operator trigger gbrain does not know; its message text s... (line truncated to 2000 chars)
+| <a id="shared_origin"></a>`shared_origin` | `source_changed` (purge, or a delete whose survivor changed); a soft delete commits with `write_through.skipped: shared_origin` | Two live pages of one source recorded the same canonical file (a duplicate-origin twin: the shared file renders one of them, so a delete of either used to refuse `file_database_drift`, reconcile refused "Several pages claim the recorded canonical file" and every managed sync refused `page_identity_changed`). A soft delete (`gbrain delete <slug> --source-id <id> --expected-revision <rev>`) of a page whose file another live page records now keeps the file and publishes database-only: the selected database page is hidden; the file and the surviving page remain. This does not erase that file's contents. The receipt's `write_through.warning` says so and names the surviving slug to the trusted local owner, or to a remote writer whose grant and visibility cover that slug; other remote writers read a generic "another page of this source records the same file". Sync's census and both origin guards apply one rule: a live page wins over tombstones, several live pages refuse, a single tombstone may be reused, several tombstones stay ambiguous. An owner purge (`--purge`) of a shared-origin page refuses with this reason: a purge tombstones the content source-wide and a same-content survivor would refuse `purged_content` on its next import. The 72 h retention purge (the autopilot purge phase, `gbrain pages purge-deleted --older-than 72h --yes`) of such a page once it is soft-deleted writes no tombstone, so it removes the page row, its chunks, links and facts database-only and leaves the file and the surviving page untouched (#7311); a census that changed under it defers to the next run, which re-reads the claimants and, when the tombstone now owns the file alone, purges it normally, file included. A delete whose surviving claimant changed between preparation and publication (the file moved or removed, a survivor deleted or re-pointed) refuses and never removes the file as a fallback. | Delete the page that should not own the file; the kept file still holds whatever text it had, so edit it first if it holds the deleted page's text, then import its current content into the surviving page with `gbrain repair file-drift --source <id> --slug <surviving-slug> --prefer file` (preview, then the apply command it prints) and `gbrain sync --source <id> --no-pull`. Sync does not overwrite a surviving page that differs from the file: it holds it [`file_drift`](#file_drift), whose fix leads with the same command. For a purge of a live page, soft-delete it instead; a soft-deleted one is removed by the retention purge (a tombstone an older release parked after its refusals is retried once by the first purge run after the upgrade). After a `source_changed` on a changed survivor, submit the delete again with a new `request_id`; it re-reads the file's claimants. |
+| <a id="writer-coordinator-required"></a>`database_guard` or `database_trigger` | `writer_coordinator_required` (or `storage_error` for another trigger) | A database trigger refused a row while a write was being prepared or published, so nothing was committed and any canonical file already replaced was restored. With `database_guard`, a gbrain process wrote a row its publication does not own (another source, an unresolvable source, or a source checkpoint/topology change outside owner administration). This is a gbrain defect or a version mismatch between gbrain processes sharing the database, not a content conflict. The exception is relationship `unreadable_state` (#7636): the database role gbrain connects as cannot see the writer state the guard reads (the `persistence_brain` or `git_canonical_brain` row, or the source or page row the write names) because row-level security hides it, or a `persistence_brain` / `git_canonical_brain` row is missing, so the guard refuses instead of letting the write through as if the brain were unmanaged or the row absent. A derived-state maintainer trigger raises the same refusal (#7637, raiser `gbrain_forget_page_retrievals`, `gbrain_queue_page_projection` and the others [listed in ENGINES.md](../ENGINES.md#derived-state-maintainers)) when row-level security applies to the role on a table it keeps up to date and the role holds no policy for it there, instead of leaving that derived state stale. The receipt's `write_error_detail` names the table, operation, guard branch, source relationship and stage; it never contains page text or source names. For another trigger it also carries a closed `reason`: `attribution_unclassified_table` or `trust_unclassified_table` (a gbrain stamp trigger met a table it is not built for: a version mismatch), `graduation_in_progress` (the engine-graduation fence, SQLSTATE 55000, refuses writes until the move finishes: retry later), or `unknown` (an operator trigger gbrain does not know; its message text stays on the brain host). The same `reason`, raiser and table appear on the managed sync failure (`gbrain doctor`, the failure ledger) and in `gbrain sync status --json` `last_error.write_error_detail`. | On the brain host run `gbrain sources writer status --probe --json`. Its `recent_failures[].error_detail` adds the source ids and the gbrain build and host that ran the attempt (`attempt.consumer_version`). If that build differs from `gbrain --version`, upgrade or restart every gbrain process that shares the database (serve, autopilot, sync jobs), then retry with a **new** request ID. If the builds match, report `error_detail` on the gbrain issue tracker. For relationship `unreadable_state` the build is not the cause: run gbrain as a role that can see that state (the table owner, a role that bypasses RLS, or a scoped role whose policies cover those rows, though a change to which sources are Git-canonical passes only the first two; see [writer-protocol fences](../ENGINES.md#opt-in-rls-source-scope-binding-gbrain_rls_scope_binding), and for a maintainer's table the [policies a scoped writer needs](../ENGINES.md#derived-state-maintainers)), then retry with a **new** request ID; a missing row, which `gbrain init` never leaves, is reported like a defect. Never force-write, edit SQL or disable the guard. |
| `ambiguous_source_path` | `page_identity_changed` | A source registered at a Git subfolder `<sub>` has a page whose stored path `<sub>/<file>` could mean either `<file>` in the source directory (the older Git-root spelling) or `<sub>/<file>` inside a folder of the source that repeats its name, and both files exist. Sync refuses instead of guessing. See [sources in a Git subfolder](multi-source-brains.md#sources-in-a-git-subfolder). | Rename or move one of the two files, commit, then `gbrain sync --source <source> --no-pull`. |
| <a id="owner_marker_missing"></a>`owner_marker_missing` | `owner_marker_missing` | The ownership marker `.gbrain-owner.json` is gone from the checkout root while the reservation beside the checkout still names this owner and identifies this exact directory: device, inode and birth time all equal (a cleanup or a restore that dropped dotfiles). A directory the reservation does not identify exactly, a birth time within the 1 µs tolerance included, keeps the generic `recovery_required` and its [recreated-root](#recreated-root) exit. No write publishes there, and a retry never brings the marker back, so the owner finishes each refused write `failed` (its outstanding-request slot is released); a sync stops `blocked_by_failures` on the refused file, without a hold. | Re-create the marker with the verified self-transfer on the brain host: `gbrain sources writer status --source <source> --json` (note `admin_state`), then `gbrain sources writer transfer prepare <source> --self-transfer --admin-intent writer_transfer_prepare --expected-state <admin_state>`, then `gbrain sources writer transfer accept <source> --path <root> --expected-epoch <epoch> --manifest <digest from prepare> --self-transfer --admin-intent writer_transfer_accept --expected-state <fresh admin_state>`. Then run the same `gbrain sync` again. Never create or copy the marker by hand. |
| `physical_root_device_changed` | `recovery_required` | The checkout's filesystem device number changed while everything else matches, which macOS can do after a reboot. When the owner token, brain, worktree, root, inode and a non-zero birth time all match and the caller can verify database ownership, the write path re-stamps ownership by itself and the write proceeds. This refusal means the automatic re-stamp could not be verified; the suggestion says why. | Do a deliberate self-transfer: `gbrain sources writer status <source>` (note `admin_state`), then `gbrain sources writer transfer prepare <source> --self-transfer --admin-intent writer_transfer_prepare --expected-state <admin_state>`, then `gbrain sources writer transfer accept <source> --path <root> --expected-epoch <epoch> --manifest <digest from prepare> --self-transfer --admin-intent writer_transfer_accept --expected-state <fresh admin_state>`. Retry the original write with the **same** request ID. Never delete ownership marker files. |
@@ -86,3 +86,935 @@ of making a duplicate.
| <a id="writer_admin_locked"></a>`writer_admin_locked` | `writer_admin_locked` | The operator set the brain's writer admin lock (`gbrain sources writer lock`), so writer claim, activate, transfer prepare and transfer accept refuse for every caller. Ordinary writes are not affected. | Agents: stop and ask the operator; do not unlock it yourself. The operator runs, on the brain host, `gbrain sources writer unlock`, re-reads `gbrain sources writer status <source> --json`, administers, then `gbrain sources writer lock` again. See the [writer admin lock](../architecture/topologies.md#writer-admin-lock). |
| <a id="writer_not_quiesced"></a>`writer_not_quiesced` | `writer_not_quiesced` | Activation found an older writer, a legacy lock, or queued, running or recovering work. When work blocks it, the message names the blocking effect id, kind, source, page and request id. | Stop the writers named in the [claim and activate runbook](../architecture/topologies.md#claim-and-activate-runbook), inspect the named work with `gbrain sources writer status <source> --json`, let it finish, then retry. A committed write whose embedding effect is stuck queued or failed is settled by `gbrain repair embedding-effects --source <source>` (preview), then the same command with `--apply`; see [stale queued embedding effects](repair.md#stale-queued-embedding-effects). |
| <a id="activation_source_path_missing"></a>`source_path_missing` | `source_changed` | `gbrain sources writer activate` (with or without `--dry-run`) found a source whose recorded `local_path` no longer exists on this host, for example a checkout that lived in a temporary directory. Activation cannot verify that source's canonical directory, so nothing changed. The message names the source and the missing path. Claiming the source at another directory does not help while the stale path stays recorded. | Run the command the suggestion prints: `gbrain sources set-path <source> <directory>` to point the source at its checkout (the suggestion fills in the claimed directory when the source is claimed), or `gbrain sources remove <source> --confirm-destructive` when the source is no longer needed (`gbrain sources archive <source>` keeps a 72-hour grace period). Then `gbrain sources writer activate --confirm-quiesced --dry-run` and activate. |
+| <a id="source_checkout_missing"></a>canonical checkout missing | `recovery_required` | A page write (`put_page`, `capture`, `add_timeline_entry`, `edit_page` and the other page writers; `detail: source_checkout_missing`) found that the source's canonical checkout directory does not exist on this host, for example a brain copied to another machine or container without its source directories; nothing was written, and the message names the source but not the path. A source directory missing inside a checkout that exists (Git keeps no empty directory, so a fresh clone lacks an empty member folder) is not this refusal: the write creates it. A managed source lifecycle command (`gbrain sources archive`, `remove`, `purge`, `restore`, `rebind`) found that the source's canonical checkout directory was deleted out of band. A source with **no pages** that is the **only** source on that checkout is retired anyway: archive, remove and purge succeed and the receipt records `retired_without_checkout` with the missing path. Otherwise nothing changed; the message names the path, the page count and how many other sources share the checkout. Recreating an empty directory at the same path does not help (its physical identity differs). | Restore the checkout (for example from a backup) and retry; `gbrain sources writer status --source <source> --json` shows the registered path. If it is gone for good, switch the brain to classic mode with `gbrain sources writer deactivate --dry-run`, then the printed `apply_command` (see the [deactivate runbook](../architecture/topologies.md#deactivate-runbook)), and retire the source there with `gbrain sources archive <source>`. |
+| <a id="migrations_running"></a>`migrations_running` | `migrations_running` (exit 75) | `gbrain apply-migrations` (or the post-upgrade step of `gbrain upgrade`) found another runner holding the brain's orchestration lock and stopped before touching the migration ledger, so migrations never run twice in parallel. The message names the holder's host and pid. A holder that died is taken over automatically on the next run. `gbrain upgrade` reports this as `Migrations: running`, not as a failed upgrade. | Wait for the other run to finish; `gbrain doctor` shows migration progress. Then `gbrain apply-migrations --yes` confirms everything is applied. |
+| <a id="schema_behind"></a>`schema_behind` | `migrations_pending` (reason `schema_behind`) | A managed write (`put_page` and every write admitted the same way) was refused before admission because the brain schema is at a lower version than this gbrain build needs: an upgrade installed the new binary but `gbrain apply-migrations` did not finish, often because the database role gbrain connects as does not own the tables. The write path reads tables or columns only the pending migrations add, so publishing now would fail. It is not retryable as is (class `caller`): the same write refuses until the schema is migrated. Nothing was admitted and the request id was not used. A replay of a request id accepted earlier still reconciles, and the `apply-migrations` orchestrators are not refused while they hold the migration lock. | Run `gbrain apply-migrations --yes` on the brain host as the database role that owns the gbrain tables (the fix renders `tell_user_to_run` when this connection's role does not own them), confirm with `gbrain doctor --json` (`schema_version` at head), then resubmit the same write: the same request id commits. A write that already failed on a missing column or table is classified `schema_missing` by `gbrain write-request <request_id> --json`. |
+| <a id="writer_deactivate"></a>`writer_deactivate` blockers | `writer_not_quiesced`, `writer_admin_locked`, `writer_admin_state_changed`, `writer_lock_unavailable` | `gbrain sources writer deactivate` found pending work (a queued, running or recovering write, a topology change or effect that is not settled, a held connector item, or a live connector or maintenance lease), the writer admin lock, a changed admin state, or a local process holding a worktree lock. Nothing changed. The suggestion names each blocker and its exit. | Run `gbrain sources writer deactivate --dry-run` for the full list, run each named exit (`gbrain cancel-write-request <request_id>`, `gbrain sync --source <id> --no-pull`, `gbrain repair embedding-effects --source <id>`, `gbrain sources writer retry-effects <source> --request-id <id> --dry-run`, `gbrain sources writer unlock`, `gbrain sources retry-held <id>`), then deactivate again with a fresh `--expected-state` from `gbrain sources writer status --json`. See the [deactivate runbook](../architecture/topologies.md#deactivate-runbook). |
+| <a id="extract-timeline-refused"></a>timeline extract refused | the printed code, usually `writer_coordinator_required` | `gbrain extract timeline --source db` (or a timeline-only `gbrain extract timeline` on a managed brain) could not write a page's timeline rows. It prints `refused: <code>; nothing written; existing timeline rows are untouched` per page, a summary of written versus refused, and exits 1. The rows import already stored for each page stay as they were. | `gbrain extract --stale` (add `--source-id <id>` when you scoped the run) publishes links and missing timeline rows on the managed path. If it refuses too, follow the row for the printed code. |
+| unknown option (repair) | `invalid_params` | `gbrain repair` refuses any option it does not list, so a mistyped flag or `--max-usd` never runs a repair silently without it. | Fix the option (`gbrain repair --help`). To cap paid repair work, preview with `gbrain doctor --remediation-plan --json` and, after the user agrees, run `gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --max-usd <n>`. |
+| <a id="colon_slug_windows_write_through"></a>`colon_slug_windows_write_through` | `colon_slug_windows_write_through` | A page slug such as `calendar:abc` is valid, but its canonical file name would contain `:`, which Windows cannot store (it names an alternate data stream). On Windows, a write that would publish that file is refused before admission, and `gbrain sync` skips each such file with this reason instead of failing the run. Database-only writes of the same slug (no repo configured, `sync.write_through` off, an unbound source, or a [read-only mirror](multi-source-brains.md#read-only-mirror-sources) source and pages created while it was one) still succeed, and macOS and Linux are not affected. | Use a slug without `:` (the suggestion names one), or write the page from a macOS or Linux host that owns the source. For a skipped sync file, rename it without `:` on a macOS or Linux checkout, commit, then run `gbrain sync --source <source> --no-pull` on the Windows host. |
+| <a id="embedding_auth_failed"></a>`embedding_auth_failed` | `embedding_auth_failed` | The embedding provider rejected the configured key (HTTP 401 or 403). Printed once per process on stderr, naming the key source in effect: an environment variable (for example `OPENAI_API_KEY`, which wins over the config key) or the config key in `~/.gbrain/config.json`. No key or part of one is printed. | Environment key in effect but the config key is right: remove the variable from the environment of the process that reported it (shell profile, `~/.gbrain/.env`, or a daemon's service definition) and restart that process. Environment key intended: replace it with a valid key, restart, and run `gbrain config unset openai_api_key` (or the matching key). Config key in effect: `gbrain config set openai_api_key <valid key>`. Then `gbrain embed --stale` embeds what was saved meanwhile. `gbrain doctor` (`embedding_key_source`) shows the key source in doctor's own environment. |
+| <a id="managed_pull_skipped"></a>`managed_pull_skipped` (cycle warn); doctor `sync_freshness` "upstream unknown" or "upstream N commit(s) ahead" | `managed_pull_skipped` | A managed brain never runs `git pull` inside a cycle: Git pull needs an explicit drained maintenance window, so an explicit `gbrain sync` without `--no-pull` is refused with `writer_coordinator_required`. An unattended cycle asked to pull (autopilot passes `pull: true`, `gbrain dream --pull`) instead syncs the checkout as it is and reports it: the sync phase result carries `details.upstream_refresh` (`pulled`, `failed`, `skipped_managed` or `not_requested`), and when the checkout tracks an upstream the phase is `warn` with `details.warning` (`code`, `cause`, `fix`, `docs`). Every sync also records the checkout's last upstream observation (the upstream commit, when it was last fetched or pushed, and how many upstream commits the synced commit lacks) in the source row. Doctor `sync_freshness` reports that separately from the local projection: a source with a `remote_url` whose observation is missing or older than 24 hours is "upstream unknown", and any source whose observation saw upstream commits it has not synced is "behind"; neither is reported fresh. `details.upstream_unknown_count` and `details.upstream_behind_count` count them. | `gbrain sources refresh <source>` (the printed `fix` fills in the source). It drains writes to the source's checkout, fast-forwards it to its upstream and runs the managed sync for every source bound to that checkout; see [worktree refresh refusals](#worktree-refresh-refusals) for what it can refuse. On a brain that is not managed, `gbrain sync --source <source>` pulls and records the observation. |
+| <a id="managed_sync_flag_refused"></a>`managed_sync_flag_refused` (`detail` = the flag) | `managed_sync_flag_refused` | A managed source keeps every failed-receipt and ignored-file guard, so `gbrain sync --skip-failed` and `gbrain sync --include-gitignored` have no managed meaning. A strict (git-canonical, `config.canonical = "git"`) source also refuses `gbrain sync --working-tree`, because it indexes committed bytes only; that refusal comes from the managed-sync guard, which reads the source row. The refusal names the flag and comes before anything runs: at parse in `gbrain sync` (before a legacy ledger row is acknowledged or the cost gate runs, `--all` included), before the serve-delegation ladder looks for the serve's socket, and in the managed-sync guard that sync jobs, MCP `sync_brain` and the cycle reach. Nothing is admitted and no cursor is written. | Rerun the printed `fix` (the same command without the flag). A failed file is fixed and then retried by the plain `gbrain sync --source <source> --no-pull`; an ignored file syncs once it is committed and not ignored, and an edit on a strict source syncs once it is committed (`gbrain git commit-push`). `gbrain sync status --source <source> --json` shows the source's failures and holds. |
+| <a id="facts_absorb_write_refused"></a>`facts_absorb_write_refused (<code>)`; `ingest_log` `write_refused: <code> …` | `facts_absorb_write_refused` | A durable `facts-absorb` job extracted facts but the write path refused to store them, for example `writer_coordinator_required` because the entity's Markdown file sits in a claimed canonical worktree before `sources writer activate`, or `permission_denied`, `invalid_params` or `writer_registration_required`. These refusals do not change on retry, so the job goes straight to `dead` on its first attempt instead of re-running inference; on a brain that is not yet activated, a job whose source root is a claimed worktree is refused before extraction starts, so it makes no model call; the `facts:absorb` row in `ingest_log` (and doctor `facts_extraction_health`) records `write_refused` with the real code, not a provider failure. Two outcomes are not refusals and are logged under their own reasons, which doctor never counts toward its threshold: `write_pending_accepted`, a facts write that was accepted and whose receipt is still queued, running or recovering when the job stopped waiting (the job waits up to 30 s, bounded by its deadline; the write commits later), and `write_deferred_unadmitted`, a canonical writer that was busy before anything was admitted (`writer_lock_unavailable`, no receipt; the job retries). Doctor warns about deferrals only when they persist (see the check's `gbrain sources writer status` fix). Doctor's incident count is a historical metric: it counts the `facts:absorb` rows of a rolling 24 h window, says when they age out, and keeps counting them after the cause is fixed and the job retried, so a warning there does not by itself mean anything is still broken; the threshold (`facts.absorb_warn_threshold`) is unchanged. The current state is the check's `jobs still dead` count: facts-absorb jobs that went dead or failed in the last 24 h and that no later job for the same page completed after, each named with `gbrain jobs retry <id>`. The source page itself was already saved. | Fix the named cause first: `gbrain sources writer status <source>`, then finish the [claim and activate runbook](../architecture/topologies.md#claim-and-activate-runbook) for a claimed worktree, or fix the grant. Then `gbrain jobs retry <job id>` (the error names the id). |
+| <a id="no_context_ceiling"></a>`no_context_ceiling` | `no_context_ceiling` | A queued job under a cost cap you set stopped before a provider call: the model has a registered price, but gbrain knows no context-token ceiling for it, so it cannot reserve the most one call could cost. OpenRouter models hit this, because that provider declares no context window per model. The message names the model, and the JSON `fix` asks you before it reruns the command without your cap. Re-registering the price does not help. | Choose one. Rerun the command without your cap (the `fix` command, which replaces `--max-usd` with `--yes`): the default cap applies and this model runs unmetered with a warning. Or keep your cap: look up the model's context window on the provider's model page (OpenRouter lists it as `context_length`) and give it to the brain-host operator. `gbrain jobs list --group <id> --json` shows the stopped job. |
+| <a id="no_pricing"></a>`no_pricing` | `no_pricing` | A cost cap you set (`--max-cost`, `--max-usd`, `--max-cost-usd`, or an explicit cap in config such as `cycle.extract_atoms.budget_usd`) cannot be enforced, because gbrain has no price for the model the run was about to call. The run stops before that call. Under a default cap an unpriced model warns and runs instead. The message names the model, provider and kind, and JSON output carries the same guidance as fields: `code`, `model`, `provider`, `kind`, `units`, `lookup`, `register_command`, `register_scope` and `docs`. | Look up the provider's current price for the model, for example by searching the web for its pricing page. A chat model needs USD per 1M input tokens and USD per 1M output tokens; an embedding or reranker model needs USD per 1M tokens. On the brain host, run `gbrain pricing set <model> --input <usd> --output <usd> --source <pricing-page-url>` (or `--rate <usd>`), then retry. An agent connected over MCP cannot register prices: give the command to the brain's operator. See [registering a model price](../operations/spend-controls.md#registering-a-model-price). |
+| <a id="managed_raw_upload"></a>raw upload on a managed brain | `writer_coordinator_required` | `gbrain files upload-raw` of a small (git-storage) file whose `.raw/` destination is inside a managed canonical worktree. The persistence coordinator does not publish raw files yet, so the worktree refuses writes from outside it; starting a `gbrain serve` owner does not change that. The refusal comes before anything is created: no `.raw/` directory and no `files` row. With no storage backend, `file_upload` for such a page no longer suggests `upload-raw`. | Configure `storage` (supabase, s3 or local) in the gbrain config, then run the printed `gbrain files upload <file> --page <slug>`; check it with `gbrain files list <slug>`. |
+| <a id="readable_by_invalid"></a>`readable_by_invalid` | `readable_by_invalid` | A remote write (MCP over HTTP or stdio) set frontmatter `readable_by` to a value that names no valid reader (an entry that is not a member id or `group:<id>`, an empty list, a non-string), removed `readable_by` from a page that names readers, or set readers that leave the page unreadable by the writing connection's member. The message names the bad entry; nothing was written. | Write the field as a list of member ids and `group:<id>` entries, for example `readable_by: [alice-example, group:team-a]`, keep your own member or group in it, and submit again with a new `request_id`. To widen or hand a page to other readers only, ask the user to change it on the brain host. |
+| <a id="timeline_rows_would_be_removed"></a>`timeline_rows_would_be_removed` | `timeline_rows_would_be_removed` | A remote `put_page` (or a `put_pages` entry) has no Timeline section at all — no `<!-- timeline -->` sentinel and no `## Timeline` or `## History` heading — and would delete dated entries the page has, including rows `add_timeline_entry` added. `put_page` content replaces the whole page, so the omission must be explicit. Nothing was written. A section that is present but empty is a deliberate delete and is not refused; a local `gbrain put` without `--expected-revision` keeps the rows instead. | Re-read with `get_page include_content:true`, keep the Timeline section and resubmit with a new `request_id`; to remove every dated entry on purpose, resubmit the same content with `drop_timeline: true` (on put_pages, per entry). A successful write that deletes rows reports `timeline_rows_removed {count, earliest, latest, warning, fix}` (dates only); `get_versions` then `revert_version` restores them as new rows. |
+| <a id="purge_lookup_timeout"></a>`purge_lookup_timeout` | `purge_lookup_timeout` | A page purge (`gbrain delete <slug> --purge`) ran one of the journal lookups that still execute inside its publication transaction (the lookup of stored intents for the slug, the re-check of requests admitted after its preparation scan or pending at that scan, the locking read of the requests to redact) and that statement hit the transaction's 5-second statement budget on a large `persistence_requests` table. The request failed terminally instead of being released as `database_contention` and claimed again: nothing of the page was removed or tombstoned, nothing in the journal was redacted, and later writes to the source move again. Do not assume the requested content was erased. The substring search for the page's claims no longer runs here: it runs at preparation in bounded keyset chunks under the preparation budget, and a sweep that outruns that budget twice ends [`preparation_stalled`](#preparation_stalled) instead. A committed purge's receipt reports `journal_sweep` (`scanned`, `ceiling`, `tail`, `pending_rechecked`, `complete`); `complete: false` means a cap was hit (the 10,000-match cap or the tail bound) and some requests were not tested. | If the receipt says the slug index `persistence_requests_slug_intent` is missing or INVALID, run `gbrain repair request-indexes --apply` (the `persistence_request_slug_intent_index` migration builds it online; the index serves the slug lookup, not the substring sweep), then submit the purge again with a new `request_id`. Otherwise submit it again with a new `request_id` (a retry with the same id returns this failure); if it times out again, report the request id with the `persistence_request_indexes` and `persistence_request_growth` entries of `gbrain doctor --json`. |
+| <a id="purge_mirror_unwritable"></a>`purge_mirror_unwritable` | `purge_mirror_unwritable` | A fact or page purge appends a text-free `intent` line to the purge mirror (`<brain home>/.gbrain/purge-events.jsonl`) and fsyncs it before it commits, so a later restore of an older backup can replay the purge. The mirror could not be written (a directory in its place, a read-only home, a full disk), so the purge was refused: nothing was removed, tombstoned or redacted. Do not assume the requested content was erased. | Make the mirror a writable regular file owned by the brain's user (mode 0600), then run the purge again with a new `request_id`. |
+| <a id="preparation_stalled"></a>`preparation_stalled` | `preparation_stalled` | The write's owner could not finish *preparing* it. Every write has a preparation budget (`persistence.sync_preparation_ms` for a managed sync member, `persistence.maintenance_preparation_ms` for every other managed kind, 120 s each; `remember`, `put_page` and `edit_page` keep 30 s), the owner releases the claim at the budget and tries again, and a request cut off `persistence.max_preparation_attempts` times (default 2; a process killed mid-preparation counts too) is finished `failed` with this code instead of being claimed again and holding the rest of its root. The receipt names the last recorded step and what it was waiting on (`git`, `fs`, `db`, `pool` or `unknown`); while the write was still running, `gbrain sources writer status --json` showed the same on `claim.stall` (`preparation_overdue`). The rest of the root keeps publishing. A **managed sync member** (an import, delete or rename of a file) is also **held**: the sync turns the failed receipt into a `preparation_stalled` hold and carries on, so the file is not imported until it is retried. The file is fine; this is the write owner stalling (a database or pool wait, a hung step), never a frontmatter or fence problem, so no repair applies. The hold's `message` names the request and the step; a held deletion keeps its page. A stalled hold re-screens by itself only when the gbrain version changes; a run that stalls many files in a row stops with [`preparation_systemic`](#preparation_systemic) instead of holding them all. A **foreground write** (`put_page`, `edit_page`, `remember`) or a **maintenance write** (fact-fence adoption, maintenance page writes) gets the terminal receipt only. The deadlines sit behind `persistence.preparation_deadlines` (`false` restores the old behaviour, where only `remember`, `put_page` and `edit_page` had a 30 s budget). | Run `gbrain sources writer status --source <source> --json` (read-only: the step, its wait cause, the owner process and its gbrain version), fix what it names (restart or upgrade an owner that predates deadlines, free the pool, let the lock holder finish), then for a sync hold run `gbrain sources retry-held <source>` and the same `gbrain sync` with the same options (the hold's `fix.then.then` and `retry-held` print it, for example `gbrain sync --source <source> --no-pull --no-embed`). When that sync still has a backlog to finish, it finishes it first and re-screens the scheduled files in the same invocation (the drain yields at the checkpoint and discovers again), so one run of the printed command clears the hold. A foreground write needs a new `request_id`; the next maintenance run submits its write again. Runbook: [catch-up stuck / held N files](troubleshooting.md#catch-up-stuck). |
+| `file_unreadable` (sync hold) | `file_unreadable` | A managed sync held one file because it is not a readable regular file inside the source root: a symlink (to a file outside the root or inside it), a non-regular file, or a permission or loop error. Sync never reads or follows it. Until GBRA-130 the whole sync stopped at that file on every run and the rest of the source never imported; now only the file waits. A source root that is itself replaced by a symlink still refuses the whole sync. | Make the file a readable regular file in the checkout (replace the symlink with the file, fix its permissions) or exclude it with `sync.exclude`, and commit. A commit that changes it re-screens the hold on the next sync; after a permission fix run `gbrain sources retry-held <source>`, then the same sync. |
+| <a id="page_write_failed"></a>`page_write_failed` (sync hold) | `page_write_failed` | A managed sync held one file because its write failed the same way three times (the same code, origin, error class and SQLSTATE in this source), with an error gbrain cannot classify: an owner exception (for example Postgres 54000 when a frontmatter tag is too long for its index), or a refusal the receipt does not explain. Until GBRA-130 every sync stopped `blocked_by_failures` at that file and the rest of the source never imported; now the file is held and the rest of the source syncs. The first two failures still stop the run, so a one-off defect never holds a file. | Read the receipt the hold names (`gbrain write-request <request_id>`, read-only). Fix the file when the error names its content (shorten the tag, split the page), or report the receipt with the gbrain version. Then `gbrain sources retry-held <source>` and the same sync. An upgrade re-tests the file on its own. A hold whose `meta.write_failure.origin` is `freeze` (GBRA-133) is different: sync could not even prepare the file (an unexpected error while reading or screening it, before any request was admitted), so it holds it on the first failure and names the error in the hold message; the next syncs re-test it on their own until it has been held 3 times, so a transient fault clears without help. When most files of one run fail that way the run stops instead (the cause is not the files). |
+| <a id="content_null_bytes"></a>`content_null_bytes` (sync hold) | `content_null_bytes` | A managed sync held one Markdown file because its text holds NUL bytes (U+0000). Page text is stored as UTF-8 without NUL bytes. The usual cause is a UTF-16 file (a Windows "Unicode" save; the hold says so when the file starts with a UTF-16 byte order mark), a binary file named `.md` or a crash-padded file. Until GBRA-133 the whole managed sync stopped at that file on every run (`storage_error`, SQLSTATE 22P05) and the rest of the source never imported; now only the file waits. With `sync.holds=fail` the run stops with `content_null_bytes` instead of holding. | Save a UTF-16 file as UTF-8, remove the NUL bytes, or remove a binary file (or leave it out with `sync.exclude`), then commit and `gbrain sync --source <source> --no-pull`. The hold re-screens when the file changes. |
+| <a id="git_object_missing"></a>`git_object_missing` (sync hold) | `git_object_missing` | A managed sync held one committed file because the commit names a Git object the checkout no longer has (an interrupted `git gc`, a partial clone without its promisor remote, disk corruption) and the working-tree copy differs from it or is gone. When the working-tree bytes hash to the committed blob id, sync imports them and holds nothing. Until GBRA-133 the whole managed sync stopped at that file on every run. | Run `git fsck --connectivity-only` in the checkout to see what is missing, restore it with `git fetch` (a partial or shallow clone) or from a backup, then `gbrain sync --source <source> --no-pull`. Every sync re-tests the hold. |
+| <a id="path_not_utf8"></a>`path_not_utf8` (sync hold) | `path_not_utf8` | A managed sync held one committed file because its name is not valid UTF-8 (a Latin-1 name from an older system, an archive or a network share). Git hands the name back with U+FFFD for the bytes that are not UTF-8, and no Git read or file matches that decoded name, so nothing is imported from it. Until GBRA-133 the managed sync either stopped at that file on every run or skipped it with no hold; now only the file waits and the hold names it. With `sync.holds=fail` the run stops with `path_not_utf8` instead of holding. | Rename the file to a UTF-8 name (`git -c core.quotePath=true ls-files` shows its exact bytes; `convmv -f latin1 -t utf8` converts a Latin-1 name), commit, then `gbrain sync --source <source> --no-pull`. The rename clears the hold. |
+| <a id="write_interrupted"></a>`write_interrupted` | `write_interrupted` | A transient interruption kept ending this managed write: the database ended its own statements (SQLSTATE `57014`, a statement timeout or cancel) at preparation or inside its publication transaction, or its publication ran past `persistence.publication_ceiling_ms` and its grace and the owner cancelled it. Each interruption throws the preparation away, but it is load or latency, not the write's content, so it has its own budget: the request is claimed again after a backoff (1 s, 2 s, 4 s, 8 s, then 15 s, scheduled on the request as `next_attempt_at`; no claim, root lock or connection is held while it waits, and `gbrain sources writer status` names the waiting head `transient_backoff`) up to `persistence.max_transient_retries` times (default 5, 0 to 20), and the next interruption finishes it `failed` instead of preparing it again without limit. Interruptions never spend `persistence.max_preparation_attempts`, which preparations cut off at their deadline keep ([`preparation_stalled`](#preparation_stalled)). Nothing was published: a worktree-backed write's canonical file is restored before the failure is recorded. Contention with other transactions (`55P03` lock timeout, `40001` serialization failure, `40P01` deadlock) is released as `database_contention` uncounted, and a dropped connection or a database that is restarting or out of connections is never counted. The receipt's message and owner-only `error_detail` name the interruptions (`attempts`), the retry limit (`limit`, `limit_key`), the `cause` (`statement_cancel` or `publication_ceiling`) and the SQLSTATE (`sqlstate`, public). A managed sync member is held like [`preparation_stalled`](#write_interrupted-hold): the run moves past it and the rest of the source lands, `gbrain sync status` lists the hold (class `page`, safe action `retry`, [runbook row](sync-unblock-runbook.md)), and `gbrain sources retry-held` re-admits it. A group's shared read the database cancels is charged once, to the first member that settles with it, never to every member; and the charge commits with the claim's release, so a crash between them never counts it twice. With `persistence.preparation_deadlines` off nothing is counted and no backoff applies. | Run `gbrain sources writer status --source <source> --json` (read-only: the owner, its pool, what its writes wait on), then submit the write again with a new `request_id` once the database is less loaded; for a held sync file, run `gbrain sources retry-held <source>` and the same sync with its options. A `publication_ceiling` cause on a page that legitimately takes longer to publish is the user's call: ask before raising `persistence.publication_ceiling_ms` (or the database `statement_timeout` for a `statement_cancel`). If the same write ends this way again, report its request id with `gbrain doctor --json`. Do not raise `persistence.max_transient_retries` to get past it. |
+| <a id="write_outcome_unknown"></a>`write_outcome_unknown` | `write_outcome_unknown` | The database session dropped while the write was being admitted (a pooler reap, a failover, `pg_terminate_backend`), and it kept dropping through the re-reads, so whether the write was accepted is unknown (#6355). A single drop never reaches you: the admission attempt is re-run after 100, 300 and 900 ms, and every attempt begins by reading the retained `request_id`, so a re-run replays an admitted row instead of admitting again. Before this code existed the raw socket error (`write CONNECTION_CLOSED …`, `57P01`) reached the caller while the write went on to commit, and a receipt oracle took it for a refusal. | Read the request first: `gbrain write-request -- <request_id>` or `get_write_request { request_id }` (the error's `fix` names it). A committed or pending row means the write was accepted: replay the same `request_id` to wait for it. No row means it was not: submit it again with the same `request_id`. Never resubmit under a new `request_id` without that read. |
+| <a id="connection_inherited_read_only"></a>`connection_inherited_read_only` | `connection_inherited_read_only` | The database refused the write as read-only (SQLSTATE `25006`): the server connection defaults to read-only transactions (a session-level `SET` another client left on a pooled connection, a role or database default, or a read-only server). Nothing was written. A managed sync stops the run with it (systemic). | Ask the database operator to reset the pooler's server connections, stop the client issuing session-level `SET` through the pooler and check `ALTER ROLE` / `ALTER DATABASE` defaults; then submit the write again. |
+| <a id="page_body_segmented"></a>`page_body_segmented` | `page_body_segmented` (a memory verb: `invalid_params` with `write_error: page_body_segmented`) | The target page stores its body in segments (a page over 1 MiB written while `pages.segmented_storage` was on), and this write needs the whole body as one string: `remember` against an entity page over 24 MiB (named, or inferred from the fact), and the other whole-body writers listed under [page_body_segmented](windowed-reads.md#page_body_segmented). It refused before changing anything and is not retryable. | For `remember`, save the claim without an entity (`infer_entity: false`); remembering it with `entity` once that page accepts fact rows replaces that copy. Otherwise edit the page's file and sync it, or read it with `get_page` `body: "auto"`. |
+| <a id="fence_unrenderable"></a>`fence_unrenderable` | `fence_unrenderable` | A legacy fact row (an active `facts` row with no fence row number) was not adopted into its page's `## Facts` fence because the fence codec reads the rendered row back as something other than the stored fact: a whitespace-only claim comes back empty, `~~x~~` comes back struck, a literal `<br>` comes back as a line break, or another column changes. Surrounding whitespace and CRLF line endings are the one accepted difference: such a row is adopted and `facts.fact` takes the fence's text. A second legacy row whose normalized claim, source and visibility the page already carries is left too (`duplicate_claim`; a private and a world row with one text are two facts and both adopt). The cycle and the v0.32.2 migration print `FACTS_FENCE_FAILED: <slug> (fence_unrenderable: N row(s), <class>)`; doctor `fence_integrity` lists the pages, fact ids and reason classes under `unrenderable_legacy_facts` (never the claim text). The same code refuses a planned adoption whose rendered fence does not read back as its facts; that is a gbrain planning defect, not caller input. The planner runs the publisher's own read-back check on the whole rendered fence first, so such a page is reported as unadoptable (class `whole_fence`) instead of being submitted. A managed adoption refused in the last day is not resubmitted: the cycle reports it as class `prior_refusal` with the refused request id (`gbrain write-request -- <id>` reads it), and a direct `submitFactFenceAdoption` call refuses with `The same fact-fence adoption was already refused.`. It is retried a day after the refusal, or at once by a build whose adoption planner revision changed. Unadopted rows hold only their own page: the phantom-redirect pass skips a phantom that owns one and redirects the others. Before v0.60.218.0 the planner could reuse a leftover fence row (one with no database owner) whose visibility differed from the legacy fact's. On a managed brain the publisher refused that page here every cycle, so no private fact was published as world. An unmanaged brain had no such check: it fenced the fact into the leftover row, and the same cycle's reconcile copied that row's visibility into the fact, so a private fact could become world. The current planner never reuses a leftover row for a fact with a different visibility unless the fact is private, and re-renders a reused row from the fact. To count what an older build left in the writer table, run the read-only `scripts/diagnose/fence-adoption-census.sql` on the brain host against the brain's Postgres database (its header shows the `psql` command). | Nothing to fix in the page: the rows stay active and searchable, nothing is lost, and their pages skip destructive fact reconciliation until the rows are adopted. Report the pages and reason classes with the gbrain version. Never `forget_fact` a row to clear the count. |
+| <a id="reconcile-private-facts"></a>reconcile private facts | `permission_denied` | `gbrain sources reconcile --apply` (and its preview) found a `## Facts` row that would edit, renumber or change the visibility of a stored private fact, copy a stored private claim into a row under another visibility, or copy a stored private row's context (24 characters or longer) verbatim into a world row. A row is identified by its row number and claim, so a world row that only shares a private row's claim is not a private row and publishes. The refusal names the row number, never its text. It guards against verbatim copies only; reworded text is not detected, so it is not a confidentiality proof. Sources are not compared, because rows share provenance such as "Slack import". Nothing was written. | Read the stored page with the printed `gbrain get --source <id> -- <slug>`, keep the named row as stored in the file (or remove the copied text), then run a fresh `gbrain sources reconcile <id> <slug> --preview` and apply it. Change private facts with `remember` and `forget`. |
+| <a id="maintenance_backpressure"></a>`maintenance_backpressure` (exit 12) | `maintenance_backpressure` | A managed maintenance run (`gbrain extract-conversation-facts`, its cycle phase or job) publishes each page as its own request, under the same local CLI writer your own CLI writes use. Before the run it counts the requests the whole run plans; before each page's model work it checks again. It stops admitting once the writer's outstanding requests, reserved receipt bytes (`persistence.limits.principal_terminal_bytes`; each request reserves 16 KiB until its receipt compacts after the retention window) or permanent request ids (`persistence.limits.principal_lifetime_ids`; never freed) would pass 80% of their limit, so the last 20% stays free for your other writes. The message names the resource. Pages already published keep their facts and nothing is half-written. | Outstanding requests: read them with `gbrain sources writer status --source <id> --json`; a resident `gbrain serve`, or the next CLI run, publishes them, then rerun the same command. Receipt bytes or request ids: run the smaller batch the message prints (`gbrain extract-conversation-facts --source-id <id> --limit <n>`), or wait for receipts to compact; raising the named `persistence.limits.*` key is the user's call. |
+| <a id="write_quota_exhausted"></a>`write_quota_exhausted` (exit 12) | `write_quota_exhausted` | A cumulative write cap is full: permanent request ids (`persistence.limits.principal_lifetime_ids` or `brain_lifetime_ids`, `reason: lifetime_ids`) or reserved receipt bytes (`principal_terminal_bytes` or `brain_terminal_bytes`, `reason: terminal_bytes`). `begin_page_upload` refuses the same way at the staged-upload caps: staged bytes (`principal_staged_bytes` or `brain_staged_bytes`, `reason: staged_bytes`) or open sessions (`principal_uploads`, `reason: open_uploads`); those free when a session commits, aborts or expires, so `abort_page_upload` on an abandoned session also helps. `detail` names the limit key. Waiting does not help: ids are permanent and receipt bytes free only as receipts compact. Nothing changed. | Run the `fix` on the brain host: `gbrain config set <key> <value>` (the value covers about one more year at the current rate; undo with `gbrain config unset <key>`), then retry with the same `request_id`. For receipt bytes with reclaimable slack, `gbrain repair receipt-compaction` second previews the retained bytes compaction would free (ids: only the raise helps). Verify with `gbrain doctor --only persistence_capacity --json`. [Runbook](concurrent-writes.md#quota-near-exhaustion). |
+| <a id="upload_not_found"></a>`upload_not_found` | `upload_not_found` | An upload call (`upload_page_part`, `get_page_upload`, `commit_page_upload`, `abort_page_upload`) named a session this connection cannot use: no such `upload_id`, another connection's session, a source outside your grant or since re-created, a page deleted or re-created since begin (for mode `create`, a page now at the slug), or an aborted session. Every case gets the same answer, so an `upload_id` reveals nothing. Nothing was written. | Begin a new upload with `begin_page_upload` and a new `request_id`, then send its parts from part 0. |
+| <a id="upload_expired"></a>`upload_expired` | `upload_expired` | The upload session passed its idle deadline (`persistence.limits.upload_idle_seconds`, 1 hour since its last part) or its hard deadline (`upload_max_seconds`, 24 hours since begin) before it was committed. Its parts were discarded and its staged bytes released; nothing was written. | Run the `fix`: `begin_page_upload` again with a new `request_id` and send every part from part 0. An expired session never resumes. |
+| <a id="upload_protected_content"></a>`upload_protected_content` (`reason`: `takes`, `facts` or `timeline`) | `upload_protected_content` | A remote `commit_page_upload` replacing a page with content over 24 MiB was refused: the page holds a takes fence that remote reads hide (`takes`), a facts fence with a row remote reads hide (a non-world row, or a fence that does not parse: `facts`), or timeline rows (`timeline`). put_page keeps the hidden fence and rows and checks which timeline rows its content omits by comparing whole bodies; a body this size is never held whole, so the upload refuses instead of dropping them. The session was discarded and its staged bytes released; nothing was written. | `takes` or `facts`: replace the page with content of at most 24 MiB through put_page (which carries the fence or the hidden rows over), or ask the user to write it on the brain host. `timeline`: upload again and commit with `drop_timeline: true` only if deleting every timeline entry is intended; otherwise send at most 24 MiB through put_page. |
+| <a id="part_too_large"></a>`part_too_large` | `part_too_large` | An `upload_page_part` call's encoded arguments are over this connection's `part_max_frame_bytes` (its inbound request cap, at most 4 MiB, minus a 4 KiB envelope; `detail` names both sizes). JSON escaping counts quotes, backslashes and control characters at their escaped size. The part was not stored. | Cut the part smaller and send it again with the same part number; `get_page_upload` returns `part_max_frame_bytes` and `next_part`. |
+| <a id="upload_too_many_parts"></a>`upload_too_many_parts` | `upload_too_many_parts` | An `upload_page_part` call would be part number 64 plus one per 64 KiB of the declared `total_bytes` (one per eighth of `part_max_frame_bytes` when that is under 512 KiB) or later without completing the content. Each part is a stored row, so a session of tiny parts is bounded. The part was not stored. | Send all remaining bytes in that part if they fit within `part_max_frame_bytes`; otherwise abort and begin again, cutting parts near `part_max_frame_bytes` (`get_page_upload` returns it). |
+| <a id="part_splits_code_point"></a>`part_splits_code_point` | `part_splits_code_point` | An `upload_page_part` text starts or ends with half of a surrogate pair, which has no UTF-8 encoding on its own. The part was not stored. | Move the cut before the high surrogate so the pair travels in one part, then send the part again. |
+| <a id="write_quota_insufficient"></a>`write_quota_insufficient` (exit 12) | `write_quota_insufficient` | A bulk run (a managed sync catch-up, a reclone, a repair) estimated from its manifest more new receipts (ids and 16 KiB reservations) than the capacity left before its producer's pause line, so it did not start. Other writes still work. | Run the `gbrain config set <key> <value>` the message prints on the brain host, then rerun the same command. Verify with `gbrain doctor --only persistence_capacity --json`. |
+| <a id="write_capacity_low"></a>`write_capacity_low` (notice) | `write_capacity_low` | Not a refusal: a `[gbrain notice]` on write receipts, `sync` receipts, `gbrain sync status` and autopilot cycle output when a cumulative cap is at or past 80% or would run out within `persistence.capacity.warn_days` (30) days at its 7-day rate. Receipts carry it at most once an hour per engine and scope; `sync status` and doctor carry it every time. The structured `capacity` object names the scope, resource, days left and the config command. | Follow the [runbook](concurrent-writes.md#quota-near-exhaustion): raise the cap it names with the printed `gbrain config set`, then verify with `gbrain doctor --only persistence_capacity --json`. |
+| <a id="write_capacity_backpressure"></a>`write_capacity_backpressure` (exit 12) | `write_capacity_backpressure` | A background producer (managed maintenance, conversation facts, an autopilot cycle phase, an autopilot catch-up sync) stopped admitting because a cumulative cap of its writer or the brain is past `persistence.capacity.background_pause_pct` (default 0.8). Interactive writes (`remember`, `put_page`, `edit_page`, an operator's `gbrain sync`, an approved `gbrain repair`) keep the remainder. No receipt was written. `reason` names the resource. Doctor `persistence_capacity` names the paused producers. | Depends on `reason`. `lifetime_ids`: ids are never freed, so only the brain host's `gbrain config set <key> <value>` from the `fix` resumes background work; waiting does not. `terminal_bytes`: the same reversible raise resumes it at once, or it resumes by itself as retained receipts compact. Verify with `gbrain doctor --only persistence_capacity --json`. |
+
+### Other error codes
+
+These codes carry no separate reason. Each is listed so every write error code
+a receipt can report has a row here.
+
+| Reason | Error code | What it means | Recovery |
+| --- | --- | --- | --- |
+| `writer_pool_capacity` | `writer_pool_capacity` | The canonical owner has no free publication slot right now; the write stays queued. | Wait and poll the receipt (`gbrain write-request <id>`). If it persists, check `gbrain sources writer status <source>`. |
+| <a id="visibility_not_applied"></a>`noncanonical_value`, `not_kept` | `visibility_not_applied` | A `put_page`, `edit_page` or `capture` write's frontmatter asked for `visibility: private`, but the page would have stayed world-readable, so nothing was written and no no-op was reported (#7841). An `ingest_capture` job (webhook `POST /ingest`, the ingestion daemon) refuses this request on every brain and dead-letters without a retry, its job result carrying the refusal (#7880); the webhook answers 202 before the job runs, so a sender reads the refusal from the job. `gbrain brainstorm` / `gbrain lsd` with `--save` and `gbrain sources reconcile` (a merge that takes a file's `Visibility: private`) refuse it on every brain too and store nothing (#7897). `ingest` refuses a document whose own leading frontmatter asks for it, in any spelling, unless the ingest itself is private (`gbrain ingest --visibility private`), before any provider call or write. `noncanonical_value`: the key or value is in another case (`Visibility: private`, `visibility: Private`) or another shape (a value on the next line, a block scalar, a list, a flow mapping, an explicit or merged key), which page privacy does not read as private. `not_kept`: the request did not survive into the page that would be stored. The check only refuses; it never widens a page or changes what a remote caller may read or write. When the content's frontmatter is unreadable or ambiguous (the importer would hold it), a private request gets the importer's `invalid_frontmatter` refusal with its reason instead; nothing is written either way. | Read the page and its revision (`gbrain get --source <id> -- <slug>`), write `visibility: private` on its own frontmatter line, lowercase, and submit `put_page` again with a new `request_id`. That is the supported way to make an existing page private, on a git-canonical source too (the page publishes database-only, see [`git_private_commit_refused`](#git_private_commit_refused)). |
+| `revision_required` | `revision_required` | The operation must be bound to a revision you reviewed (for example `--if-version` or `expected_revision`), and none was given: a `put_page` of a page that already exists without `expected_revision` reports this since #5385 (earlier releases said `revision_conflict`). | Preview first, then repeat with the revision the preview printed. |
+| `revision_conflict` | `revision_conflict` | The page changed after the revision this write was bound to. Nothing was overwritten. | Re-read the page, merge your change, and save with the new revision. |
+| `revision_changed` | `revision_changed` | An `append_page` with `expected_revision`, or a `commit_page_upload` whose session was bound to a revision, found the page at a newer revision. Nothing was appended or written, and the upload session is aborted with its staged bytes released. | Read the page again (`get_page` with `body: 'none'`), check whether the text is still missing, then append against the new revision with a new `request_id` (for an upload, begin a new session). |
+| <a id="tail_changed"></a>`tail_changed` | `tail_changed` | An `append_page` with `expected_tail_sha256` found a different page end: another writer appended or edited first. Nothing was appended. | Read the page again (`get_page` with `body: 'none'` returns `tail_sha256`), check whether the text is still missing, and append against the current tail with a new `request_id`. |
+| `sync_cursor_replaced` | `sync_cursor_replaced` | A managed sync checkpoint found that another sync run of the same source (a rediscovery, a newer sync) replaced the cursor it belongs to, so it had nothing left to publish. The receipt is a conflict; no managed-sync failure is recorded for it, and the run that awaited it goes on with the cursor that now covers the source. | Nothing: let the current sync finish. `gbrain sync status --source <id> --json` shows that cursor. A same-run index lag keeps reporting `revision_conflict`. |
+| <a id="revision-backfill"></a>`revision_backfill_pending` | `revision_backfill_pending` | The page was written before page revisions existed (an upgrade from below schema v150) and the resumable revision backfill has not reached it, so it has no revision to bind to. Its revision reads as `backfill_pending`, never a UUID. Nothing was written. `gbrain doctor` reports the backfill as `revision_backfill` with the pending count and any failed rows by page. | Resume the backfill on the brain host with `gbrain apply-migrations --force-schema` (it prints its progress; `--yes` alone does not resume it once the schema is current). Rows that used all three attempts are no longer retried: run `gbrain repair orphan-children` to preview orphaned child rows and torn page bodies ([orphan children](repair.md#orphan-children)). |
+| `idempotency_conflict` | `idempotency_conflict` | The `request_id` was already used for a different target, content or protocol. | Use a new `request_id` for a different write; reuse an ID only to replay the same write. |
+| <a id="write_pending"></a>`write_pending` | `write_pending` (CLI exit 10) | The write was accepted but has not committed yet. It keeps its request ID and may still commit. The CLI exits 10, not 1; a lost acknowledgment with no receipt is `submission_status: "unknown"` and exits 1. See [CLI exit status for writes](../protocol/MEMORY_VERBS_v1.md#cli-exit-status-for-writes). | Poll `gbrain call get_write_request '{"request_id":"<id>"}'`, or repeat the same command with the same `--request-id` and a longer `--wait <seconds>`. Scripts that only need the write admitted pass `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) to exit 0, except for a receipt whose `diagnostic.owner` names a stale owner, which still exits 10 ([stale owner](troubleshooting.md#owner-host-stale)). |
+| <a id="invalid_write_wait"></a>`invalid_write_wait` | `invalid_write_wait` | `GBRAIN_WRITE_WAIT_MS` or `persistence.write_wait_ms` is not a whole number of milliseconds from 0 to 600000. Nothing was written. | `unset GBRAIN_WRITE_WAIT_MS` (or set it to e.g. `30000`), or `gbrain config set persistence.write_wait_ms 30000`. |
+| <a id="edit_page"></a>`edit_no_match`, `edit_ambiguous_match`, `edit_protected_span`, `edit_invalid` | same | An `edit_page` edit matched nothing, matched more than once, touched a protected takes/facts section, or was malformed. `detail` names `edit_index` (and `match_count`). Nothing was admitted. | Re-read `get_page include_content:true`, fix the named edit and resend with a **new** request ID. See [partial page edits](../protocol/MEMORY_VERBS_v1.md#partial-page-edits-edit_page). |
+| <a id="file_database_drift"></a>`file_database_drift` | `file_database_drift` (also the `detail` of a `source_changed` refusal) | A page's checkout file and its database copy differ, so the writer left both as they were instead of replacing one with the other (#6982). The page is held, the run reports it (`details.file_holds`, a `FACTS_FENCE_FAILED` or connector hold) and the rest of the batch continues. Nothing was overwritten. | If the file holds the newer edit, `gbrain sync --source <id>` imports it; if the database copy is newer, re-save the page with write-through on (`gbrain get <slug>`, then `gbrain put <slug>`). When both changed, ask the user which version to keep. |
+| `storage_error` | `storage_error` | The write did not commit for a reason with no more specific code. | Inspect the durable request with `gbrain write-request <id>` on the source host and follow its message. |
+| `cancelled` | `cancelled` | The request was cancelled before it committed. Nothing was written. | Submit the write again if you still want it. |
+| `permission_denied` | `permission_denied` | The caller is not allowed to make this write (a trust boundary, slug fence or lock). | Run it as a caller that has the permission, usually the trusted local CLI on the brain host. |
+| <a id="no_source_grant"></a>`fence=no_source_grant` | `permission_denied` | The legacy bearer token's source grant is an explicit empty list (`gbrain auth rescope --token <name> --sources none`), or its sources axis has drifted (an older gbrain edited its `permissions` JSON after the grant moved to columns; doctor `legacy_token_grant_drift`), so it reads and writes no source. A write accepted before that change is refused at publication. It never falls back to the `default` source. | On the brain host: `gbrain auth rescope --token <name>` shows the grant and any drift. Empty grant: the refusal's `fix` carries the command with this token's id filled in (`gbrain auth rescope-token --id <token-id> --sources <id,...>`; the agent asks the user for the sources), or `gbrain auth list` when the token cannot be named. Drift: ask the user which grant is intended, then `gbrain auth rescope --token <name> --adopt-permissions` or `--adopt-columns` (see [grant drift](../mcp/ADMIN.md#grant-drift)). Then retry with the **same** request ID. |
+| `scope_denied` | `scope_denied` | The caller's token or grant does not cover this operation or source. | Use a client with the needed scope and source grant. |
+| `not_found` | `not_found` | The request, source or object named by the call does not exist. | Check the id; `gbrain sources list` lists sources. |
+| `page_not_found` | `page_not_found` | The target page does not exist in that source, or disappeared during the write. | Check the slug and `--source`, then retry. |
+| `write_claim_lost` | `write_claim_lost` | Another execution took over this request while it ran; that execution owns the outcome. | Poll `gbrain write-request <id>`; do not resubmit under a new ID. |
+| `request_too_large` | `request_too_large` | The request is larger than the configured request or recovery capacity. | The message names the limit. Send a `put_pages` batch as smaller batches, or raise that limit on the brain host. A page under the 24 MiB page limit is never split: a transport that cannot carry it is bypassed by writing the file into the source and running `gbrain sync`, or by `gbrain import <file>` on the brain host ([limits per entry point](memory-boundaries.md#large-page-limits)). |
+| `response_too_large` | `response_too_large` | The persistence response exceeded the local transport limit. The write may still have committed. | Poll `gbrain write-request <id>` before retrying. |
+| `writer_registration_required` | `writer_registration_required` | The source needs an active canonical owner before this operation, for example activation. | Claim the source on its owner host (`gbrain sources writer status <source>` names the next step). |
+| `writer_identity_invalid` | `writer_identity_invalid` | This host's local writer identity file is unreadable or has an unknown format. | Run `gbrain doctor` on the host; it names the identity file to repair. |
+| `writer_not_initialized` | `writer_not_initialized` | The brain has no persistence identity yet, usually because migrations have not run. | Run `gbrain apply-migrations --yes` on the brain host. |
+| <a id="managed-guard-page-children"></a>`writer_coordinator_required: canonical writer must use the persistence coordinator` on a tag, timeline or take write; on the client `storage_error: Publication failed (P0001)` | `writer_coordinator_required` (`storage_error` on the stored receipt) | 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 every insert and update of those rows, including coordinated ones. gbrain v0.60.38.0 and later take those rows' source from their page and ignore the column; an uncoordinated delete of such a row on a live page is refused, as on every other brain. | Upgrade to v0.60.38.0 or later on the brain host, then follow its recovery steps in the [CHANGELOG](../../CHANGELOG.md#060380---2026-10-03) (or [repair](repair.md#recover-after-an-upgrade)): `gbrain sync … --no-pull`, `gbrain extract --stale`, `gbrain extract timeline --source db`, a previewed `gbrain facts relink`, then `gbrain repair failed-writes` (preview, then `--apply --expect <hash>`) for the refused `put_page`, `add_timeline_entry` and `remember` calls; see [failed writes](repair.md#failed-writes). |
+| `writer_coordinator_required` | `writer_coordinator_required` | The operation needs managed persistence (the write coordinator) and this brain or call path does not use it. A file write refused because the path sits in a managed canonical worktree names that worktree in the message, and its `detail` reads `root=<directory> source=<id or unknown> evidence=<marker file, managed-root registry or source binding>`. | Run the operation through the command the message names, on a managed brain. When the brain is not managed and the evidence is an ownership file (`.gbrain-owner.json`, `.gbrain-owner-<hash>.json`, `.gbrain-managed`), check it with `gbrain sources writer status` before removing anything: a half-finished claim is finished or rolled back through writer administration. A `gbrain-managed.json` an older gbrain wrote in a repository that only encloses a managed root (a dotfiles home) is named in the message; `gbrain sources writer deactivate` removes it (preview with `--dry-run --json`), then activate again. |
+| `fact_already_expired` | `fact_already_expired` | The fact the write targets is already expired or withdrawn. | Nothing to do; list active facts to find the current one. |
+| `source_writeback_required` | `source_writeback_required` | The write needs a correction to the source's repository files, and this caller or profile never writes them. | Make the correction in the source repository, then sync. |
+| `writer_upgrade_required` | `writer_upgrade_required` | The brain's schema is older than this operation needs. | Run `gbrain upgrade` (or `gbrain apply-migrations --yes`) on the brain host. |
+| `skill_bundle_required` | `skill_bundle_required` | The write targets a shared-skill path, which only the shared skill publisher may write. | Publish the skill through the shared skill publisher instead. |
+| `core_budget_exceeded` | `invalid_params` (detail `core_budget_exceeded`) | The write would make always-loaded core memory larger than `memory.core.max_chars`, or add a 51st core page. The message names the projected size, how far over it is and the largest core pages the caller can see. Nothing was written; writes that shrink core always pass. | Move detail into a linked non-core page and keep a one-line pointer, or ask the user to raise the budget. `gbrain core status --json` shows where the characters go. See [core memory budget](core-memory.md#budget). |
+| `core_mark_owner_only` | `invalid_params` (detail `core_mark_owner_only`) | A remote caller tried to add or remove `always_load` or change `core_priority`. Only the owner designates core pages. Nothing was written. | Resubmit without changing those keys (omitted keys keep their stored values). If the marking itself should change, ask the user to run the `gbrain core add` or `remove` command the message names. See [owner only](core-memory.md#owner-only). |
+| `core_delete_owner_only` | `invalid_params` (detail `core_delete_owner_only`) | A remote caller tried to delete a core page. Nothing was deleted. | Ask the user to run `gbrain core remove <slug>` first; the page can then be deleted. See [owner only](core-memory.md#owner-only). |
+| `core_remote_edit_refused` | `invalid_params` (detail `core_remote_edit_refused`) | `memory.core.remote_edit` is `refuse`, so remote edits to core pages are refused. Nothing was written. | Ask the user to make the edit on the brain host, or to allow remote edits with notices (`gbrain config set memory.core.remote_edit notify`). See [remote edits](core-memory.md#remote-edits). |
+
+`gbrain doctor` reports parked targets as the `parked_effects` check with the
+exact `retry-effects` command per request. When the original writer was revoked,
+the preview reports `action: owner_revoked` with `authority: {ok: false, code,
+message}` and a `fix` that asks the user first, and doctor names that exit instead
+of the retry command: the Git backup of those pages is incomplete. After the user
+agrees, the owner host retries a parked Git effect once under the brain owner's
+authority with `gbrain sources writer retry-effects <source> --request-id <id>
+--admin-intent writer_retry_effects --expected-state <admin_state>`; the effect
+records `retried_under: owner_host`. A withdrawal effect is never retried under
+another authority. `gbrain sources writer git-durability <source> --pat-file
+<path>` retries every parked push of the worktree after wiring the credential;
+a request refused on its own (revoked writer, replaced source, live claim) is
+listed in `parked_pushes.refused` with its fix, the result has `status: partial`,
+and the command exits 1. It reports `persistence_capacity`
+when lifetime request IDs or receipt bytes reach 80% of a limit, with the
+`gbrain config set` value to use; outstanding-request, queued-byte and
+recovery-byte limits can refuse writes without that warning.
+
+<a id="settle-effects"></a>
+**A parked or failed Git effect no retry can ever move** (#7423, #7378): the
+target's prefix was declared `db_only` after the effect was queued, so every
+retry parks it again; or the effect belongs to a former canonical worktree (the
+source was moved with set-path or a transfer), so `retry-effects --request-id`
+refuses it `source_changed` and `--parked-pushes`, which only reaches the current
+worktree, previews nothing (it now names those effects under `former_worktree`,
+and doctor's `git_push_holds` fix for them is the settle preview). Doctor
+`parked_effects` and writer status give such effects their own parked group
+(`former_binding`: the recorded worktree, the current one, the request ids and
+the settle preview as `command`), and the exact retry's refusal names both
+bindings with `settle-effects --request-id <id> --dry-run` as its fix; the
+bulk retry's zero never covers them
+([disposition](repair.md#former-binding-effects)). Do not claim
+or transfer the source to force the old effect through. Settle it on proof
+instead: preview with `gbrain sources writer settle-effects <source> --parked-code
+<code> --dry-run` (or `--request-id <id>`), show the user each effect's proof, and
+after they agree run the printed `apply_command` (`--apply --expect <plan_hash>`;
+a changed plan refuses `preview_changed`). An effect settles only when each
+target is declared `db_only` in the current gbrain.yml (proof `db_only`), or, for a
+former-worktree effect, a later Git effect of the current worktree committed and
+pushed the bytes the canonical file holds now and the already-fetched
+remote-tracking ref of the checkout's branch holds exactly those bytes at that
+path (proof `superseded_remote`; nothing is fetched). Each other effect is listed
+with its refusal: `retry_instead` (current binding: retry it),
+`no_covering_receipt` (write the page through gbrain first), `bytes_unpushed`,
+`remote_ref_missing` or `remote_ref_stale` (fetch in the checkout, then preview
+again), `content_changed`, `content_missing`, `unknown_target`, `withdrawal_effect`
+(never settled), `recovery_open`, `claimed`, `authority_changed`, `source_replaced` and
+`owner_unavailable`. `--retire` (#7985) settles an effect of a former binding
+that nothing current owes, on evidence instead of a remote proof: its source was
+replaced, or each target's page moved to a later revision, was deleted or lost
+its slug to another page (proof `former_binding_retired`; refusals
+`page_not_moved` and `not_former_binding`; the apply asks the user,
+[disposition](repair.md#former-binding-effects)). A settlement is recorded on the effect (`data.settled`, every
+settle and unsettle appended to `data.settlements`); its failure, request, intent
+and target bytes are kept. Doctor `parked_effects`, writer status, the bulk retries
+and `sync status` skip settled effects. `--unsettle` with the same selector
+previews, and with `--apply --expect` reverses, a settlement.
+
+<a id="held-files-and-content-refusals"></a>
+## Held files and content refusals
+
+Some content refuses deterministically: the same bytes refuse on every retry.
+On a write (`put_page`, `capture`, `gbrain import`) the call fails with the code
+below and nothing is written. During `gbrain sync` the file is **held**
+instead: the rest of the source imports, the checkpoint advances, and
+the hold is reported by the sync result (`held`, `held_count`,
+`holds_outstanding`), `gbrain sources status <source>`, doctor
+`git_held_files`, `get_page` (`file_held`) and search (`stale` hits and the
+`held_files` notice). A held new file has no page; a page whose newer file is
+held keeps its last good revision and is read-only for `put_page` until the
+file is repaired, so do not retry a refused write. A hold clears by itself
+when the file changes, is deleted, or a newer gbrain can read it.
+
+Every hold carries `code`, `reason`, `key`, `line`, a location-only `message`
+(never a frontmatter value), `fix` (the exact command) and `docs` (the anchor
+below). Walkthrough: [held files](repair.md#held-files).
+
+**Say to your agent:** *"Sync held some of my notes. Tell me what is wrong
+with each file and fix the ones that need no guessing."*
+
+| Code (`reason`) | What it means | Recovery |
+| --- | --- | --- |
+| <a id="invalid_frontmatter"></a>`invalid_frontmatter` | The file's YAML frontmatter cannot be read without guessing. gbrain imports frontmatter it can read exactly, quoting at most an unquoted value (`author: a (b) (original: https://…)` imports and is reported under `recovered_frontmatter`). Producer checks stay strict: `gbrain frontmatter validate` and the pre-commit hook still fail on it. | Preview the fix: `gbrain repair frontmatter --source <source>`; it writes nothing until `--apply --expect <hash> --yes`. On a write, correct the named line and submit with a new request ID. |
+| <a id="invalid_frontmatter-yaml_parse"></a>`invalid_frontmatter` (`yaml_parse`) | YAML no rule reads safely: a mis-indented list or mapping entry, a key line with no colon. | The preview lists it as `needs_review` with the exact line to fix by hand: one line per key, the whole value quoted. Commit and sync. |
+| <a id="invalid_frontmatter-needs_interpretation"></a>`invalid_frontmatter` (`needs_interpretation`) | Reading it means choosing an interpretation: unquoted continuation lines after a value, a duplicated key, an unclosed `[` or `{`. gbrain never imports a guess. | `gbrain repair frontmatter --source <source> --include-ambiguous` shows the exact interpretation per file. Show the user each diff; apply only what they approve (`--only <path>` / `--skip <path>` select files). |
+| <a id="invalid_frontmatter-ambiguous_identity_key"></a>`invalid_frontmatter` (`ambiguous_identity_key`) | `slug`, `type`, `id` or `source_id` appears twice, or its line was swallowed into another value, so gbrain cannot tell which page the file is. | Edit the file by hand: keep exactly one line for the key. The user decides which value is right. |
+| <a id="invalid_frontmatter-ambiguous_protected_key"></a>`invalid_frontmatter` (`ambiguous_protected_key`) | A key that decides access or provenance (`visibility`, `derived_from`, …) is malformed, duplicated, swallowed into another value, rewritten by quoting, or inside an unclosed fence. gbrain never reads such a key as a broader value. | Edit the file by hand: write the key on one line with one quoted value. Ask the user which visibility is intended; never guess it. |
+| <a id="frontmatter_slug_conflict"></a>`frontmatter_slug_conflict` | The file's frontmatter `slug:` names a different page than its path does (earlier releases reported this as `invalid_params`). The path decides the slug. When the named slug has no page and no file (#6865), the managed sync itself removes the line after it releases its drain lease, imports the file under its path slug, clears the hold, commits the edit and keeps the declared slug as an alias; a file edited since the hold, an unfinished sync or a remote job waits for the next pass (`sync.slug_conflicts.auto_remove false` turns it off; `slug_lines_removed` counts it). The hold has three outcomes once the content-repair lane's `slug-conflicts` kind runs it (the maintenance run's `content_repair` phase, `gbrain sync unblock --apply`, or `gbrain repair content --source <source>`): **removed** (the named slug resolves to no page and names no other file, or to a page of a different type sharing no title token: the stray `slug:` line is removed, the file imported and committed, the hold cleared, with a receipt; a model under the `fences.repair` caps makes the same call when the two pages are not obviously different), **merge recommended** ([`merge_recommended`](#merge_recommended): the two files describe the same thing; gbrain recommends the merge and names the canonical page but never merges pages by itself), or **undecided** ([`content_repair_needs_human`](#content_repair_needs_human)). The lane judges the file with the screen managed sync froze it with: a hold the sync screen now admits as the file is (its slug line names the file's own page as written, or it no longer declares a conflicting slug) is **imported** unchanged in one guarded write that clears only the hold observation the lane read (a hold a newer sync wrote stays, with a retry), and a file sync would hold whatever the lane writes is [`slug_page_mismatch`](#slug_page_mismatch). Until that kind ships, the lane leaves the hold to the frontmatter repair preview below. | Nothing to run when the lane removes the line: the hold clears on the sync it prints. For a recommendation or an undecided hold, `gbrain sync status --source <source> --json` carries the paragraph (`human_reason`): merge the unique sections into the canonical page by hand or decide which page keeps the slug, delete or edit the file, commit, then `gbrain sync --source <source> --no-pull`. `human_reason` asks to "decide which page keeps the slug" only when the line names a live page (a database-only page is labelled) and names any other frontmatter fixes; a hold with no verdict never asks a person, and an older gbrain's verdict is rechecked by the next sync or maintenance run. By hand at any time: remove the `slug:` line or make it match the path, or move the file to the path its slug names (`gbrain repair frontmatter --source <source> --include-ambiguous` proposes removing the line, for approval). |
+| <a id="file_too_large"></a>`file_too_large` | Over the page size limit: 24 MiB for a Markdown page, 5 MB for a code file ([limits per entry point](memory-boundaries.md#large-page-limits)). Every page under the limit is stored, chunked and searchable whatever its size, so this hold only fires above it, and the same bytes are held on every retry. A file sync had to read whole to refuse (over 24 MiB with segmented storage on) is not read again until it changes, gbrain is upgraded, or `gbrain sources retry-held <source>` schedules it; run that after changing a setting its message names. A smaller page refused by an MCP or HTTP transport limit is a different refusal: send it by file. | Leave the file out of the source: read `gbrain config get sync.exclude`, then `gbrain config set sync.exclude '<current list>,<path>'`; or, if it must be in the brain, split it into files under the limit and commit. The next `gbrain sync --source <source> --no-pull` clears the hold, also when nothing was committed since (#6712 PR 2). |
+| <a id="managed_image_sync_unsupported"></a>`managed_image_sync_unsupported` | Managed sync imports image files only while multimodal embedding is on (`GBRAIN_EMBEDDING_MULTIMODAL=true`): the image page, its OCR text and its image vector are built by the coordinated image importer at preparation, and `source_path` is recorded. While multimodal embedding is off, each image import is held with this code instead of refusing the whole sync (#5493); deleting or renaming an image still reconciles its page. These holds count as missing coverage (the image is not searchable) but never escalate, because they are not a content fault. | Nothing is broken. To import the images, set `GBRAIN_EMBEDDING_MULTIMODAL=true` on the owner and run `gbrain sync --source <source> --no-pull`: the next discovery re-screens every image hold and imports the files (#6529). To stop holding them instead, leave them out of the source (`gbrain config get sync.exclude`, then `gbrain config set sync.exclude '<current list>,**/*.png'`); that clears the holds on the next sync. A held image is also re-screened when it changes and on `gbrain sources retry-held <source>`. |
+| <a id="content_rejected"></a>`content_rejected` | The content-sanity gate matched junk and the operator set `content_sanity.junk_disposition` to `reject`, so the file is never imported and always visible. | Remove the matched junk from the file, or ask the user whether `junk_disposition` should go back to `quarantine`; that setting is the user's decision. A managed-sync hold re-screens on every sync, so either clears it on the next one. |
+| <a id="purged_content"></a>`purged_content` | The file (or written content) has the content hash of a page the owner purged with `gbrain delete <slug> --purge`, under any slug, or carries a purged claim the database refuses. Purge leaves a text-free tombstone so a stale file, re-sync or revert cannot bring the content back. | Delete or edit the file and commit; an edited file imports normally. Only if the purge was a mistake, the owner lists tombstones with `gbrain pages purges list` and clears one with `gbrain pages unpurge <slug>` on the brain host; a managed-sync hold re-screens on every sync, so the next one imports it. A Google or GitHub connector item refused this way is skipped and the sync continues; `gbrain sources status` lists it ("skipped as purged content"). See [expire versus purge](memory-boundaries.md#purge). |
+| <a id="write_gate_rejected"></a>`write_gate_rejected` | The source is untrusted, the file reads like an instruction to an agent (an override, a standing rule, an exfiltration or credential request), and the operator set `write_gate.external_mode` to `reject`, so the file is never imported and always visible. Managed sync holds it when it freezes the file (#6712 PR 2; before, the refusal came at preparation and blocked the rest of the source); an owner allow rule (`gbrain trust allow`) covering the source and the file's path admits it at freeze exactly as at preparation. The hold is `needs_human`, and every sync re-screens it, so the setting switched or an allow rule added clears it on the next sync. | Tell the user; whether to edit the file or switch `write_gate.external_mode` back to `quarantine` is their decision. |
+| <a id="legacy_slug_conflict"></a><a id="legacy_slug_conflict-explicit_id_conflict"></a>`legacy_slug_conflict` (`explicit_id_conflict`) | The file has no page at its slug, and several live pages an older gbrain imported before the current slug fold (a space, an emoji, an accent or a trailing dash in the slug; no recorded file) fold to that slug (#6727). Exactly one such page is taken over by the file: the next sync imports into it (same page id, links, timeline and aliases) and records the file as its origin, instead of creating a second page. With several, sync cannot tell which page is the file's, so it holds the file and the rest of the source syncs. It holds the file the same way when the one match has a slug sync cannot write as it stands (capital letters, from a gbrain that predates lowercase slugs; the importer lowercases), rather than creating a second page beside it. With reason `explicit_id_conflict` (#6729), the one match carries an explicit frontmatter `id` that differs from the file's, so it is a different document and is not taken over. With `sync.holds=fail` the run stops with `page_identity_changed`. Twins an older sync already created are not merged by this. | Ask the user which page is the file's (`gbrain sync status --source <source> --json` names every candidate slug). Remove each other one with `gbrain delete --source <source> -- '<slug>'` (soft delete, recoverable for 72 h), or rename the file if none of them is its page; with one match under a slug with capitals, which no command can address yet, keep the file held or rename it to a name that folds to another slug (it then imports as a new page beside the old one, which keeps its links). For `explicit_id_conflict`: give the file the page's `id` if it is the same document; otherwise rename the file or delete the old page. Then `gbrain sync --source <source> --no-pull`. The hold re-screens on every sync. |
+| <a id="origin_conflict"></a><a id="origin_conflict-no_canonical_claimant"></a><a id="origin_conflict-content_differs"></a><a id="origin_conflict-file_unreadable"></a><a id="origin_conflict-explicit_id_conflict"></a><a id="origin_conflict-visibility_differs"></a><a id="origin_conflict-trust_tier_differs"></a><a id="origin_conflict-twin_has_withdrawals"></a><a id="origin_conflict-twin_slug_path_occupied"></a><a id="origin_conflict-twin_evidence_conflicts"></a>`origin_conflict` (`no_canonical_claimant`, `content_differs`, `file_unreadable`, `explicit_id_conflict`, `visibility_differs`, `trust_tier_differs`, `twin_has_withdrawals`, `twin_slug_path_occupied`, `twin_evidence_conflicts`) | Several live pages of the source record this file as their origin (duplicate-origin twins, #6948). Sync used to stop the whole source with `page_identity_changed`; now only this file is held and the rest of the source syncs. With no reason the pages are verified duplicates: the page the path names (`meta.canonical_slug`), one inline body, a readable file, no conflicting frontmatter ids, one visibility and trust tier, no slug-keyed fact withdrawals or purges, no file at a twin's own slug path and no link, relationship date, timeline entry or raw payload the merge would lose. Right after that managed sync, the heal merges each other page into the canonical one (links, relationship dates, timeline, raw data, user tags, aliases and facts move; its slug becomes an alias; it is soft-deleted without touching the file, restorable for 72 h) and the next sync imports the file. A reason means a person decides: `no_canonical_claimant` (no page, or not exactly one, is the page the path names), `content_differs` (the bodies differ, or one cannot be read), `file_unreadable`, `explicit_id_conflict` (different frontmatter `id`s), `visibility_differs`, `trust_tier_differs` (a merge never raises or lowers a tier), `twin_has_withdrawals`, `twin_slug_path_occupied`, `twin_evidence_conflicts`. With `sync.holds=fail` the run stops with `page_identity_changed`. | `gbrain repair origin-twins --source <source>` (read-only) lists every group with its pages, revisions and verdict. Verified groups: let the next sync heal them, or apply the preview now. A decision: read each page (`gbrain get --source <source> -- '<slug>'`), then either `gbrain repair origin-twins --source <source> --slug '<kept-slug>'` (the others forget the file and stay live; nothing is deleted) or soft-delete the others with `gbrain delete`. Then `gbrain sync --source <source> --no-pull`. The heal's kill switch is `gbrain config set sync.origin_twins.auto_resolve false`. The hold re-screens on every sync. Guide: [origin twins](repair.md#origin-twins). |
+| <a id="page_identity_changed-held"></a><a id="page_identity_changed-several_tombstones"></a><a id="page_identity_changed-spelling"></a><a id="page_identity_changed-identity_differs"></a>`page_identity_changed` (`several_tombstones`, `spelling`, `identity_differs`) held | Managed sync cannot decide which page this file is (GBRA-130). `several_tombstones`: several soft-deleted pages record the file as their origin (`meta.identity_slugs`), so reviving one would be a guess. `spelling`: two files differ only by letter case or separator (`notes/Case.md` and `notes/case.md`), which another platform treats as one file (`meta.identity_paths`); both are held. `identity_differs`: the file maps to a page whose own file is gone, but its frontmatter `id` differs from the page's (`meta.identity_ids`), so it is another document and must not inherit that page's facts, links and history (#6729); the page keeps its slug, id and body, and the deletion of its old file waits with the hold. A sync pass used to stop the whole source with `page_identity_changed`; now only these files are held and the rest of the source syncs. A dry run (and a company source's plan) still refuses the source as before, and a remote sync leaves the files for the owner's sync to hold. The hold needs a person (`sync status` names it `page_identity_decision`) and re-screens on every sync. | `several_tombstones`: restore the page that is this file's (`gbrain restore '<slug>' --source-id <source>`; a live page wins over deleted ones) or purge the others. `spelling`: keep one spelling, rename or remove the others and commit. `identity_differs`: give the file the page's `id` if it is the same document, or rename it so its slug differs, and commit. Then `gbrain sync --source <source> --no-pull`. |
+| <a id="rename_held"></a><a id="rename_held-rename_source_changed"></a>`rename_held` (`rename_source_changed`) | A renamed file's hold cleared, but the page it was renamed from changed after the rename was recorded, so the page did not move. | `gbrain repair frontmatter --source <source> --include-ambiguous` proposes re-binding the rename to the old page's current revision; apply after the user agrees. Or restore the old file name. |
+| <a id="rename_identity_unreadable"></a>`rename_identity_unreadable` | Classic sync (GBRA-133 S-51): a file added in the same sync that removed or renamed another has a title or frontmatter `id` the database refused to compare (SQLSTATE 22021 or 22P05), so sync could not tell whether it is that page renamed. The new file is held and the old page keeps its id, links, facts and timeline; the rest of the source keeps syncing. A NUL byte or an unpaired surrogate in a title or id never reaches the database: sync treats such a value as absent and the pair takes the ordinary unconfirmed-rename path. | Remove the characters the database cannot store from the file title and `id`, commit, then `gbrain sync --source <source> --no-pull`. The pair is decided again when the file changes or on `gbrain sources retry-held <source>`. |
+| <a id="rename_reconcile_failed"></a>`rename_reconcile_failed` | Classic sync (GBRA-133 S-67): a rename fell back to importing the new file, and removing the page of the old name then failed with an unexpected error (the hold records its class and code, never its message). The old page was kept and may duplicate the new one; the rest of the source keeps syncing. A transient database error and the reconcile's own "staleness unprovable" verdict still record the `<rename:…>` marker, which a later run converges. | Ask the user before `gbrain sync --source <source> --full --no-pull`: the full walk removes pages whose file is gone after checking each one (it re-reads the whole source). Or remove the old page with `gbrain delete --source <source> -- <slug>` (recoverable for 72 h). |
+| <a id="concurrent_write"></a>`concurrent_write` | Managed sync was importing a newer Git version of the file while a database-only write (write-through off, a sandboxed or derived write) committed a different version of the same page, so the two diverge (#6194). The proof is the page's revision itself: it was written by a committed non-sync request for that page. Neither version was overwritten: the page keeps the database version, the file is held and the rest of the source syncs. Since #6340 a page that moved with no such request to name is held the same way (the hold records `page_revision` and `expected_revision` instead of a competing request), and so is a page that changed, was deleted or was re-bound in the database between the manifest freeze and the entry's turn; a page that still holds exactly what the file would import is re-bound to its new revision and passed. | `gbrain sources status <source>` names the page and the competing request. Preview with `gbrain sources reconcile <source> <slug> --preview`, decide with the user which content wins, apply the resolved preview, then `gbrain sources retry-held <source>` and `gbrain sync --source <source> --no-pull` re-screen the file. A new commit of the file re-screens it too. |
+| <a id="file_drift"></a>`file_drift` | Managed sync would have imported a file over a database version of its page that sync never saw (#6712). Every import records its provenance (the bytes left on disk, the page revision it wrote, the parser); a page that moved since that record (a database-only write, write-through off) while its file did not change, or, in a tree walk (first sync, `--full`, an unreachable checkpoint), a page whose file and revision both moved or that has no usable record (an upgraded brain: none, a pre-PR 0 record, a partial one), is imported only when the import changes nothing, a sync request wrote its current revision, or its writer's write-through wrote that revision to the file. Otherwise the file is held, the page keeps the database version and the rest of the source syncs. The hold names `sides` (`database`, `both`, `unknown`) and the database request that wrote the page when there was one; a hold the live pass writes also names its Decision, `side` (`both`, `unknown`, `deleted`) and, for a deleted side, `state` (`tombstone_edited`, `purged_differs`, `file_gone`). Pages under `storage.keep_db` prefixes whose file is clean in committed mode are not held: the pass writes the database copy back to the file (at most 200 per pass, the rest the next pass); an uncommitted edit there is held. Holds of this code never escalate; with `sync.holds=fail` the run stops with `file_drift` instead of holding. | `gbrain sources status <source>` names the page. Preview `gbrain repair file-drift --source <source> --slug <slug> --prefer database` (keep the database copy, rewrite the file) or `--prefer file` (import the file), decide with the user, apply it with the plan hash, then `gbrain sync --source <source> --no-pull`. Held pages of one Decision resolve together with [`--held --side <side> [--state <state>]`](repair.md#file-drift-held). A changed file or page revision re-screens the hold by itself. |
+| <a id="file_wins_rewrite"></a>`file_wins_rewrite` | `gbrain repair file-drift --prefer file` keeps the canonical file's bytes and adds only the protected parts reconcile keeps from the database: protected frontmatter keys the file lacks (inserted before the closing `---`) and database-only timeline rows (appended to the file's timeline, with a `<!-- timeline -->` line above a bare `## Timeline` heading so they stay in it). When the resolved page also differs in anything else (a value, a tag, the title, the body), keeping the file would mean re-rendering all of it, so the preview refuses the page and nothing is written. A database-only timeline row dated before the file's own rows sorts in among them rather than after them, so it refuses too. A file-wins apply accepted before this rule existed refuses the same way when it is prepared, and writes nothing. | Show the user the page's differences. Commit them into the file through the door (`gbrain git commit-push`) and preview again, or preview `--prefer database` if the database copy should win. |
+| <a id="frontmatter_alias_limit"></a>`frontmatter_alias_limit` | A file whose exact bytes an older gbrain imported and validated nests YAML aliases in its frontmatter that expand past the size limit (#7018). This release refuses them on purpose, so only that file is held (its page keeps the last imported version) and the rest of the source syncs; it is never a parser regression. | Reduce the alias nesting in the frontmatter (or write the values out), or remove the file, then commit and `gbrain sync --source <source> --no-pull`. The hold re-screens when the file changes. Before 4b such a file stopped the source as `sync_parser_regression`; the workaround there was `GBRAIN_SYNC_PARSER_REGRESSION=hold` for the process that syncs. |
+| <a id="visibility_noncanonical"></a>`visibility_noncanonical` | The file's frontmatter asks for `visibility: private` in a spelling page privacy does not read: another case (`Visibility: private`, `visibility: Private`), a block scalar, a list, a flow mapping or a merge key. Page privacy reads only the exact lowercase key and value, so importing it would store a world-readable page its author believes is private. Git sync (classic and managed) holds the file and the rest of the source syncs; `gbrain import` (with or without a Git checkout) refuses it and imports the rest. An existing page keeps its last imported version. Company-brain connects and syncs, and the GitHub and Google connectors on a database-only source, hold it the same way (#7880); `gbrain repair url-clone-fences` lists a clone file whose HEAD asks for it this way under this code; apply restores the file from HEAD with its fence rows kept database-only, so the clone can pull, but does not import HEAD and reports `held` (#7897). `put_page`, `edit_page`, `capture`, `ingest_capture`, `brainstorm --save` and `sources reconcile` refuse the same request as [`visibility_not_applied`](#visibility_not_applied). Doctor `git_held_files` counts the held files and the stored pages that ask for private this way (`details.visibility_noncanonical`). | Write `visibility: private` on its own frontmatter line (lowercase key and value), commit, and run `gbrain sync --source <source> --no-pull` (or import the file again). The hold re-screens when the file changes; no frontmatter repair rewrites a privacy request. For a stored page doctor names, rewrite its frontmatter the same way with `put_page` or by editing its file. |
+| <a id="parser_regression"></a>`parser_regression` | A file whose exact bytes imported under an earlier gbrain is now refused. It is held and the rest of the source syncs (the default; `GBRAIN_SYNC_PARSER_REGRESSION=stop` stops the run instead). This is a gbrain bug. | Report it with the gbrain version, the file and the code; upgrade or pin the last good version. After a fixed gbrain is installed, `gbrain sources retry-held <source>` and then `gbrain sync --source <source> --no-pull` re-screen it. |
+| <a id="settle_mismatch"></a>`settle_mismatch` | A live managed sync pass settled this file at the same level in three consecutive passes, but the next round never classified it settled (#6712). Instead of re-importing it every pass, sync held it at that level and stamped the rest of the source. The hold records the level and `meta.mismatch_streak`. The file is usually fine: a path that keeps coming back unsettled points to a broken writer, a stuck effect or a damaged record. | Run `gbrain doctor --json` and `gbrain sources writer status --source <source> --json` (both read-only), fix or report what they name with the gbrain version, then `gbrain sources retry-held <source>` and `gbrain sync --source <source> --no-pull`. A mismatch that comes back is held again after three passes. |
+| <a id="write_interrupted-hold"></a>`write_interrupted` | The database ended this file's statements (a statement timeout or cancel) at every attempt, so the sync held the file and kept going. The file is fine: no repair applies, and it is not imported until it is retried. Full reference: [`write_interrupted`](#write_interrupted). | `gbrain sources writer status --source <source> --json` (read-only) names the load on the write owner; reduce it, then `gbrain sources retry-held <source>` and the same sync with its options. |
+| <a id="preparation_stalled-hold"></a>`preparation_stalled` | The write for this file could not finish *preparing* within its attempt limit, so the sync held the file and kept going. The file is fine: no repair applies, and it is not imported until it is retried. Full reference: [`preparation_stalled`](#preparation_stalled). | `gbrain sources writer status --source <source> --json` (read-only), fix what it names, then `gbrain sources retry-held <source>` and the same sync with its options. Runbook: [catch-up stuck / held N files](troubleshooting.md#catch-up-stuck). |
+| <a id="worktree_dirty"></a>`worktree_dirty` | The working tree holds uncommitted bytes for this file that match neither the pinned commit nor the current page (an agent mid-edit on a live checkout), and importing the pinned version would discard them (#6340). Before this release the refusal (`source_changed` / `pinned_git_worktree_conflict`) stopped the whole run; now the file is held, the local edit is untouched and the rest of the source syncs. The hold keeps the pinned blob (`meta.blob_oid`) and a hash of the working bytes, counts `meta.attempts` each time the same file is held again, and a page held three times is reported `needs_human` by `gbrain sync status`. Bytes that are **committed at HEAD** past the pinned target are not a conflict at all: sync imports them as HEAD has them and the later pin..HEAD diff re-imports the same bytes as a no-op. Since 0.60.179.0 (#6513) the same hold covers a pinned import whose canonical correction (a fixable fence, reflowed frontmatter) would rewrite a file that holds newer uncommitted bytes: that refusal used to block the cursor with no exit, because `--retry-failed` replays the same pin against the same bytes, `sources refresh` refuses `sync_in_progress` on the unfinished cursor and `--acknowledge-managed` refuses `cursor_unfinished`. Working-tree bytes that already *are* the correction (gbrain's own writeback, published before the request that carried it settled) are not a conflict either: the page imports and the file is left as it is. | Commit the edit (or restore the file), then `gbrain sync unblock --source <source> --apply` re-screens every held file that is now committed and prints the sync to run (`gbrain sources retry-held <source>` does the same for all holds). A later commit that changes the file re-screens it on its own. Never discard or normalize the local bytes. Runbook: [sync unblock](sync-unblock-runbook.md). |
+| <a id="file_unreadable"></a>`file_unreadable` | Classic or managed sync held one file because it is not a readable regular file inside the source root. Sync never reads or follows it, the rest of the source imports, and the bookmark advances. Classic sync re-screens it on every run, so an out-of-band fix needs no commit. | Follow the reason row below. Each hold's `fix` names the exact step; `gbrain sources status <source> --json` lists the holds. |
+| <a id="file_unreadable-symlink_in_repo"></a>`file_unreadable` (`symlink_in_repo`) | The path is a symlink to another file in the repository. Sync reads only regular files and never follows a symlink. | Replace the symlink with the regular file it stands for (or delete it), or leave it out with `sync.exclude` (`gbrain config get sync.exclude`, then `gbrain config set sync.exclude '<current list>,<path>'`). The next sync re-screens it. |
+| <a id="file_unreadable-symlink_outside_root"></a>`file_unreadable` (`symlink_outside_root`) | The path is a symlink to a path outside the repository (it can point anywhere on the host), so sync never reads it. Before GBRA-133 classic sync blocked the source for three runs, then auto-skipped it. | Copy the content you want into a regular file at that path (or delete the link), or leave it out with `sync.exclude`. The next sync re-screens it. |
+| <a id="file_unreadable-symlink_dangling"></a>`file_unreadable` (`symlink_dangling`) | The path is a symlink whose target does not exist. Classic sync used to drop it silently. | Replace it with the regular file, or delete it and commit. The next sync re-screens it. |
+| <a id="file_unreadable-symlink_loop"></a>`file_unreadable` (`symlink_loop`) | The path is a symlink that resolves back to itself. Classic sync used to drop it silently. | Replace it with the regular file, or delete it and commit. The next sync re-screens it. |
+| <a id="file_unreadable-permission_denied"></a>`file_unreadable` (`permission_denied`) | gbrain cannot open the file (EACCES or EPERM), for example a file another user owns with mode 000. Before GBRA-133 classic sync blocked the source for three runs, then auto-skipped it. With `sync.holds=fail` it still fails the run as `PERMISSION_DENIED`. | Make it readable to the account gbrain runs as (`chmod u+r -- <checkout>/<path>`, or fix its owner or a parent directory's permissions). The next sync imports it with no commit needed. |
+| <a id="file_unreadable-not_regular_file"></a>`file_unreadable` (`not_regular_file`) | The path is a FIFO, socket or device in the working tree, which sync never opens. | Replace it with the regular file, or leave it out with `sync.exclude`. |
+| <a id="absent_from_worktree"></a>`absent_from_worktree` | Classic sync held a file the commit names that is missing from the working tree. Before GBRA-133 it was treated as "deleted after the pin" and dropped silently. The rest of the source imports and the bookmark advances; the hold re-screens on every run and clears when the file is back on disk (it imports) or leaves the commit. | Follow the reason row below. The fix is `ask_user`: restoring the file and committing its deletion are both valid. |
+| <a id="absent_from_worktree-skip_worktree"></a>`absent_from_worktree` (`skip_worktree`) | A sparse checkout (or a skip-worktree bit set by hand) keeps the committed file off disk. | Ask the user: widen the sparse checkout (`git -C <checkout> sparse-checkout add <dir>`; for a hand-set bit, `git -C <checkout> update-index --no-skip-worktree -- <path>` and `git -C <checkout> restore -- <path>`) and the next sync imports it; or leave it out with `sync.exclude`. Keeping it held is also safe. |
+| <a id="absent_from_worktree-deleted_locally"></a>`absent_from_worktree` (`deleted_locally`) | The committed file was deleted from the checkout and the deletion is not committed. | Ask the user: restore it (`git -C <checkout> restore -- <path>`) and the next sync imports it; or commit the deletion (`gbrain git commit-push --path <checkout> -m 'Delete <path>' -- <path>`) and the next sync clears the hold. |
+| <a id="unsupported_path"></a><a id="unsupported_path-not_utf8"></a><a id="unsupported_path-control_character"></a>`unsupported_path` (`not_utf8`, `control_character`) | Classic sync: the file's name is not valid UTF-8 (`not_utf8`, a Latin-1 name from an old archive) or contains a control character (`control_character`: a tab, a newline or another byte below 0x20). Git stores a name as bytes and a page path is text, so the file cannot be imported under its own name. Sync reads the diff as bytes (`git diff --raw -z`), never as a lossy decoding: before this the file was checkpointed as "deleted after the pin" with no message (`not_utf8`) or skipped as a malformed name naming no path (`control_character`). The hold key is `/gbrain-bytes/` plus the path with every byte outside a printable UTF-8 character, and every `%`, written `%XX` (`notes/caf%E9.md`); it decodes to the exact bytes and never equals a Git path. The message shows the name C-escaped (`notes/caf\351.md`) with an item id (the first 16 hex digits of the bytes' sha256). The rest of the source syncs and the checkpoint advances. | Rename the file to a valid UTF-8 name without control characters and commit. The fix's `user_message` gives a rename command that spells the old name with printf escapes (`printf 'notes/caf\351.md\000' \| xargs -0 -I{} git mv -- {} 'notes/caf_.md'`, run from the source's checkout), so no raw bytes go on a command line; then `gbrain sync --source <source> --no-pull` imports the file and clears the hold. The hold re-screens on every sync: it stays while a file has that name and clears once the name leaves the tree (renamed, deleted or excluded). |
+| <a id="gitlink_not_followed"></a>`gitlink_not_followed` (notice, not a hold) | Classic sync: the range added a gitlink (a submodule or an embedded repository, mode 160000). It records another repository's commit, not files, so its contents are not indexed. Reported once, in the run that passes it: the result's `gitlinks_not_followed` lists the paths and one stderr line names them. Nothing is held and the checkpoint advances. | Nothing to fix. To index the linked repository, check it out and add the checkout as its own source (`gbrain sources add <name> --path <checkout>`). |
+| <a id="sync_parser_regression"></a>`sync_parser_regression` | Sync stopped without advancing because it would hold a file whose exact bytes imported before, and `GBRAIN_SYNC_PARSER_REGRESSION=stop` (opt-in; the default holds the file) is set for the process that syncs. This is a gbrain bug, not a content problem. | Report it with the gbrain version, the file and the code; upgrade or pin the last good version, then `gbrain sync --source <source> --no-pull`. To keep syncing meanwhile, unset `GBRAIN_SYNC_PARSER_REGRESSION` for the process that syncs (ask the user). |
+| <a id="takes_holder_invalid"></a>takes holder (`invalid_params`) | `takes_add`, or `takes_supersede` with an explicit `holder`, was given a holder the takes fence cannot carry: empty, whitespace, or not `world`, `brain`, `people/<slug>` or `companies/<slug>` (a legacy bare slug is accepted). The value is trimmed first, so `" world "` is stored as `world`. Nothing was written: before this release such a holder was published into the fence and every later takes write on that page was refused `target_fence_malformed`. A supersede without an override keeps the row's stored holder. A page whose stored holder is already malformed still refuses every takes write (`invalid_fence`); `gbrain repair fences` is the way out. | Resend with a holder in that grammar (`holder: me` on the brain host resolves the owner's holder). For a page already carrying a malformed holder, preview `gbrain repair fences --slug <slug>` and apply it, or edit the `who` cell by hand. Format: [holders](fence-format.md#holders). |
+| <a id="changed_since_preview"></a>`changed_since_preview` | A hash-bound repair apply (`gbrain repair frontmatter --apply --expect <hash>`, `gbrain repair fences --apply --expect <hash>`, `gbrain repair content --apply --expect <h1>[,<h2>]`) found a file, its proposed change or its page different from what the preview showed, so that item was not written; the rest of the approved set still applied. | Preview again with the same selection and apply the new hash (for the content lane, one hash per kind in lane order). For frontmatter, show the user the new diff first; a fence repair needs no extra consent ([fence reason](#fence-changed_since_preview)). |
+
+<a id="invalid_fence"></a>
+### Fence holds (`invalid_fence`)
+
+A page's facts and takes fences are its structured rows
+([format](fence-format.md)). A coordinated write (managed sync, managed
+`gbrain import`, `put_page` on a managed brain, managed file repair) refuses a
+fence it cannot import without dropping or guessing rows: code
+`invalid_fence`, wire `error` `invalid_params` (`take_row_collision` for a
+stored-row collision). During managed sync the file is **held** instead and
+the rest of the source syncs. The message reads
+`Fence <reason>: in the <facts|takes> fence (<body|timeline>), row(s) N, column(s) C, at line L.`
+(the parts that apply; the line counts within the section), then the fix. It
+names fence, section, row numbers, column names and lines only, never a claim,
+holder or cell. A failed receipt keeps the location in
+`write_error_detail.fence` (row numbers stay on the brain host).
+
+A managed **maintenance write** (fact-fence adoption and the cycle's other page
+writes) is checked the same way before it is submitted, over the page's whole
+body and timeline: a page that already carries a defect no adoption clears (for
+example a second facts fence in its timeline) is skipped with the fence reason
+in `failed_pages`, no request is created, and the other pages still go. The
+fence census counts the stored defect (`gbrain doctor --only fence_integrity
+--json`), and `gbrain repair fences --source <source>` previews it where a
+repair applies.
+
+<a id="fence-hold"></a>**What a fence hold carries.** Every surface that shows
+a hold (`gbrain sources status <source>`, doctor `git_held_files`,
+`get_page.file_held`, the sync result) gives the same location-only fields:
+
+- `fence`: `reason`, `fence` (`facts` or `takes`), `section` (`body` or
+ `timeline`), `rows` (row numbers), `columns` (column names) and `line` (the
+ first bad line, counted within the section).
+- The reason's `tier`, the repair that clears it (`deterministic`,
+ `resolver`, `llm` or `manual`), and `auto_retry`, whether the maintenance
+ run clears or retries it with no one acting. The table below lists both
+ for every reason.
+- After a repair has tried the file, `fence_repair`: that attempt's `reason`,
+ `tier` and `at`, `next_attempt_after` (when the maintenance run tries it
+ again; null when it will not), and `gate` and `rows` when a proposed repair
+ was rejected.
+- `fix`, the next command (a single held file's preview,
+ `gbrain repair fences --source <source> --only <path>`), and `docs`, the
+ reason's anchor below.
+
+**What gbrain fixes by itself.** Before refusing or holding, every write path
+runs the fence through a lossless normalizer: a missing end marker with only
+blank lines after the table, two-dash takes markers above a table, zero,
+negative or duplicate row numbers (new numbers come after every number the
+page and its stored rows ever used), header aliases and column order,
+header-level defaults (`confidence 1.0`, `notability medium`,
+`visibility private`), enum synonyms (`critical` → `high`; `public` → `world`
+only on a world-visible page, else `private`), invented facts kinds (mapped to
+the closest kind, the original word kept in `context`), a short list of takes
+kind synonyms, assistant holders (`System`, `assistant` → `brain`) and percent
+confidences ([every rule](fence-format.md#normalized)). It never changes a
+claim, an existing row number or a valid cell, and never makes a row more
+visible. A fence it fixes completely is written in its normalized form:
+managed sync commits the rewritten file (a read-only mirror keeps it
+database-only; a company-brain source refuses `source_writeback_required`
+naming the fence), and the result reports `fences_normalized` (`count`,
+`by_class`, `writers`, sample paths for local callers). A write also carries
+one `fence_normalized` coaching notice: the stored page differs from what was
+sent, so re-read it with `get_page` before editing; `remember` and
+`takes_add` write rows that never need it. `gbrain sync --dry-run` lists
+`would_normalize` beside `would_hold`. `gbrain config set fences.normalize false`
+turns normalization off: a fixable fence is then held or refused like any
+other.
+
+What the normalizer cannot fix exactly is refused or held as below; a refusal
+lists every blocking problem in `fence_issues`
+(`[{ fence, section, row, column, line, class, allowed }]`, where `allowed`
+is the column's vocabulary), so the caller can correct all of them at once.
+
+Legacy (unmanaged) sync, `gbrain import` on an unmanaged brain and other
+direct imports store a fence the normalizer cannot fix as written (bad rows
+skipped) and never hold it; the result reports it in `fence_issues`. Two
+documented exceptions keep blocking with the typed refusal instead of
+holding: `sync.holds=fail`, and company-brain sources, which never hold and
+never rewrite repository files (fix the fence in the repository and commit).
+
+<a id="fence-repair"></a>**Repair.** Fence holds clear by themselves: the
+maintenance run's `fence_repair` phase repairs held files and stored pages
+whose fences do not parse, on the brain's owner host. A repaired file is
+committed like any page write on a managed source; on a legacy source it is
+backed up under `~/.gbrain/backups/` and left for you to commit. To see what
+it would change, or to do it now:
+
+```bash
+gbrain repair fences --source <source> # preview: read-only, no model call
+gbrain repair fences --source <source> --apply --expect <hash> # the apply command the preview prints
+```
+
+The preview lists each held file and stored page with its reasons, rows and
+columns, the tier that fixes it and the estimated model cost against the
+remaining daily cap, and prints the apply command with its `--expect` hash.
+Applying needs no extra consent. Tier 1 and 2 changes are exact rules; Tier 3
+sends only the fence header and the rows it must realign (never valid rows,
+never the rest of the page) to the repair model (`models.fence_repair`, or
+unset the first measured model with a key: `openai:gpt-6.1-sol`, else
+`anthropic:claude-opus-5-5`), within `fences.repair.max_usd_per_page` ($0.30) and
+`fences.repair.max_usd_per_day` ($1.00) ([spend](../operations/spend-controls.md#the-gates)).
+Every tier's output passes [gates (a) to (g)](fence-format.md#gates) before
+anything is written. `--no-llm` keeps a run to the free tiers and
+`--max-usd <n>` lowers its cap; raising spend
+(`gbrain config set fences.repair.max_usd_per_day <usd>`) or turning model
+repair back on (`gbrain config set fences.repair.llm true`) is the user's
+call. MCP and thin-client callers cannot run a repair: the hold's fix names
+the owner-host command to hand to the user. Walkthrough with real output:
+[fence repair](repair.md#fences).
+
+A `manual` reason needs a person, because gbrain never guesses it: read the
+page (`gbrain get --source <source> -- <slug>`), edit only the named fence in
+the file (never the frontmatter), commit, then
+`gbrain sync --source <source> --no-pull`. `gbrain sources status <source>`
+lists every fence hold with its location. To add rows without hand-editing a
+table, use `remember` (facts) or `takes_add` (takes).
+
+**Say to your agent:** *"Sync held a page because of its facts table. Show me
+which rows are wrong and fix them."*
+
+<a id="fence-integrity"></a>**How many are left.** `gbrain doctor --only fence_integrity`
+counts, per source, every malformed fence still waiting, once each: a held
+file, a stored page whose fence does not parse (for example one an older
+release imported as written), and a checkout file not yet synced. Each is
+split by the tier that would clear it: `deterministic` (the normalizer fixes
+it the next time the file syncs or the page is written), `resolver` (a
+holder name to resolve), `llm` (a table only a rewrite can realign) and
+`manual` (an edit only a person can decide). It also shows the oldest hold's
+age, the fences normalized in the last 7 days with their top writers (a
+source at 20 or more warns: something keeps writing malformed fences) and the
+model-repair caps `fences.repair.max_usd_per_page` (default $0.30) and
+`fences.repair.max_usd_per_day` (default $1.00) with today's spend. Each run
+scans for at most `GBRAIN_DOCTOR_FENCE_TIMEOUT_MS` (10 s) and resumes where the
+last one stopped; until a scan finishes the check is `partial` and never `ok`.
+The maintenance run repairs the `deterministic` and `resolver` ones by itself,
+and the `llm` ones while model repair is on and within the caps;
+`gbrain repair fences --source <source>` previews the plan.
+
+**Say to your agent:** *"How many broken facts or takes tables are left in my brain?"*
+
+Each reason's **Tier** is the repair that clears it (`-` when that depends on
+the page, which is screened again); **Auto** says whether the maintenance run
+clears or retries it with no one acting.
+
+| `invalid_fence` reason | What it means | Tier | Auto | Recovery |
+| --- | --- | --- | --- | --- |
+| <a id="fence-header_unmapped"></a>`header_unmapped` | The header has a column with no canonical name and no known spelling, so its cells cannot be placed. | `llm` | yes | Repaired by the next maintenance run (preview: `gbrain repair fences --source <source>`). By hand: rename each column to its canonical name. Format: [header spellings](fence-format.md#header-spellings). |
+| <a id="fence-no_header"></a>`no_header` | The fence has table rows but no header row naming `claim` and `kind`. | `llm` | yes | Repaired by the next maintenance run. By hand: add the canonical header as the first table line. Format: [markers](fence-format.md#markers). |
+| <a id="fence-row_before_header"></a>`row_before_header` | Rows sit above the header row. | `llm` | yes | Repaired by the next maintenance run. By hand: move them below the header. Format: [markers](fence-format.md#markers). |
+| <a id="fence-short_row"></a>`short_row` | A row is missing a cell in the middle, so its columns are ambiguous. A row short only in its optional trailing cells parses. | `llm` | yes | Repaired by the next maintenance run. By hand: add the missing cells so every column lines up. Format: [facts](fence-format.md#facts-layouts), [takes](fence-format.md#takes-layouts). |
+| <a id="fence-extra_cells"></a>`extra_cells` | A row has more cells than the header, and removing empty cells does not line it up (stray empty cells with one valid removal are rewritten by themselves). Often an unescaped `\|` cut a cell, usually the claim, in two; no gate can tell that from a misplaced cell, so it is never sent to the model. In a fence with no header, a row that starts with a row number is read by position the same way. | `manual` | no | Join the cut cell with `\|`, or remove the extra cell. Format: [facts](fence-format.md#facts-layouts), [takes](fence-format.md#takes-layouts). |
+| <a id="fence-claim_split"></a>`claim_split` | A facts `kind` cell holds text, not a kind word (more than three words, sentence punctuation, a link or strikethrough): usually the end of a claim an unescaped `\|` cut in two, with the kind cell missing. gbrain does not store it as a kind note. In a fence with no header, a row that starts with a row number is read by position, so its third cell is the kind. | `manual` | no | Join the text back into the claim with `\|` and write the kind. Format: [facts](fence-format.md#facts-columns). |
+| <a id="fence-holder_unresolved"></a>`holder_unresolved` | A takes `who` cell is not `world`, `brain`, `people/<slug>` or `companies/<slug>` (for example a person's display name). | `resolver` | yes | Rewritten by the next maintenance run when it resolves to exactly one verified `people/` or `companies/` page (never a private page on a world-visible page). Otherwise write one of those forms by hand. Format: [holders](fence-format.md#holders). |
+| <a id="fence-missing_begin"></a>`missing_begin` | An end marker has no begin marker before it. | `manual` | no | Add the begin marker above the table, or delete the stray end marker. Format: [markers](fence-format.md#markers). |
+| <a id="fence-split_rows"></a>`split_rows` | A fence has no end marker and its rows are split by blank lines or text, so gbrain cannot tell which rows belong to it. | `manual` | no | Join the rows into one table and add the end marker after the last row. Format: [markers](fence-format.md#markers). |
+| <a id="fence-unclosed_trailing_content"></a>`unclosed_trailing_content` | A fence has no end marker and lines holding a pipe follow its table, so the rules cannot tell table rows from prose. | `llm` | yes | The maintenance run asks the repair model whether the tail is prose; a prose tail closes the fence after its last row (on a private page by itself; on a world-visible page after the user approves the lines it shows, see `tail_exposure_approval`). A tail of plain prose with no pipe never reaches the model: it closes by itself on a private page and waits for approval on a world page. By hand: add the end marker directly after the last table row. Format: [markers](fence-format.md#markers). |
+| <a id="fence-unclosed_ambiguous_tail"></a>`unclosed_ambiguous_tail` | A fence has no end marker and the lines after its table are not plain prose: a row written without pipes, a mention of a fence marker, or a tail the repair model read as rows or could not classify. | `manual` | no | Add the end marker directly after the last table row and fix the rows below it, or wrap a marker mention in backticks; gbrain does not guess where the fence ends. Format: [markers](fence-format.md#markers). |
+| <a id="fence-tail_exposure_approval"></a>`tail_exposure_approval` | A fence on a world-visible page has no end marker and prose follows its table; gbrain can close it after the last row, but the lines after the table would then be visible to readers of the page, so the close waits for the user. | `deterministic` | no | `gbrain repair fences --source <source> --only <path>` previews the close and prints the lines that would become visible with the apply command (`--apply --expect <hash>`); run it once the user agrees. Unattended runs never close it. Format: [markers](fence-format.md#markers). |
+| <a id="fence-quoted_marker"></a>`quoted_marker` | A line quotes a facts or takes fence marker in prose (text follows the marker on its line, or the line is a blockquote), so the section reads as having a repeated or unclosed fence. | `deterministic` | yes | `gbrain repair fences --source <source> --only <path>` previews wrapping each mention in backticks and prints the apply command; `gbrain sync unblock --source <source> --apply` and the maintenance run apply it, with a receipt per file. Or wrap the mention in backticks yourself. Format: [markers](fence-format.md#markers). |
+| <a id="fence-marker_near_miss"></a>`marker_near_miss` | A line uses the two-dash takes marker (`<!-- gbrain:takes:begin -->`) or mentions it with no takes table after it. Two-dash markers directly above a takes table are rewritten by themselves. | `manual` | no | Use the exact three-dash markers around the takes table, or wrap a mere mention in backticks. Format: [markers](fence-format.md#markers). |
+| <a id="fence-repeated_marker"></a>`repeated_marker` | A body or timeline section has a second begin or end marker for the same fence outside code. Two or more fences that each have both markers, the same canonical header and nothing but table lines inside are merged by themselves (`merge_fences`: later rows appended, exact duplicates dropped, colliding numbers renumbered, a repeated section heading removed). | `manual` | no | Give the extra fence both markers and the first fence's header and move any other text out of it, so the next write or maintenance run merges them; or merge by hand, keeping one begin and one end marker per fence in that section with every row in one table. Format: [markers](fence-format.md#markers), [what gbrain rewrites](fence-format.md#normalized). |
+| <a id="fence-takes_in_facts"></a>`takes_in_facts` | A facts fence holds a takes table. | `manual` | no | Move the rows into a takes fence (or add them with `takes_add`), or rewrite them as facts rows. Format: [takes](fence-format.md#takes-columns). |
+| <a id="fence-superseded_ambiguous"></a>`superseded_ambiguous` | Two rows share a number and a `superseded by #N` reference names that number, so renumbering could repoint the reference. | `manual` | no | Decide which row keeps the number, give the other a number above every number on the page, and fix the reference. Format: [row numbers](fence-format.md#row-numbers). |
+| <a id="fence-enum_unmapped"></a>`enum_unmapped` | A facts `kind`, `visibility` or `notability` cell holds a value outside the allowed list and its synonyms (the message names the column and the allowed values). | `manual` | no | Use one of the allowed values. Format: [facts](fence-format.md#facts-columns). |
+| <a id="fence-weight_missing"></a>`weight_missing` | A takes row has no `weight`, or the header has no weight column. Takes have no default weight. | `manual` | no | Add a weight from 0 to 1. Format: [takes](fence-format.md#takes-columns). |
+| <a id="fence-holder_missing"></a>`holder_missing` | A takes row has no holder, or the header has no `who` column. | `manual` | no | Add the holder: `world`, `brain`, `people/<slug>` or `companies/<slug>`. Format: [holders](fence-format.md#holders). |
+| <a id="fence-confidence_out_of_range"></a>`confidence_out_of_range` | A facts `confidence` or takes `weight` is not a number from 0 to 1 (a percent such as `85%` is rewritten by itself). | `manual` | no | Write the intended value as a decimal such as 0.8. Format: [facts](fence-format.md#facts-columns), [takes](fence-format.md#takes-columns). |
+| <a id="fence-claim_value_invalid"></a>`claim_value_invalid` | A facts `claim_value` is not a number. | `manual` | no | Write a number (1,234 separators and a k/M/B suffix are allowed) or leave it empty. Format: [facts](fence-format.md#facts-columns). |
+| <a id="fence-takes_kind_unsupported"></a>`takes_kind_unsupported` | A takes `kind` is not fact, take, bet or hunch and is not one of the few synonyms gbrain maps (a kind the schema pack declares but the parser does not accept included). gbrain never chooses a takes kind for you. | `manual` | no | Use one of the four kinds. Format: [takes](fence-format.md#takes-columns). |
+| <a id="fence-unparseable"></a>`unparseable` | The fence does not parse cleanly: most often it has no end marker, or a row number is not a positive whole number (`column #`). | `-` | yes | Usually repaired by itself on the next write or maintenance run. By hand: add the end marker directly after the last table row, or fix the named row number. Format: [markers](fence-format.md#markers). |
+| <a id="fence-row_collision"></a>`row_collision` | Two rows of the same fence kind share a row number, in one fence or across the body and timeline (`rows` lists the numbers). | `-` | yes | Usually renumbered by itself. By hand: give one row a new number above every number used on the page. Format: [row numbers](fence-format.md#row-numbers). |
+| <a id="fence-quoted_fence_rows"></a>`quoted_fence_rows` | A fence sits inside a code block or inline code span, so readers treat it as an example and importing would remove the stored rows it holds. | `-` | no | Move the fence out of the code, or delete the fence to remove its rows. Format: [markers](fence-format.md#markers). |
+| <a id="fence-stored_row_collision"></a>`stored_row_collision` | A new takes row's number already names a different stored take that is not in the page's fence (wire `take_row_collision`). | `-` | no | Renumber the new row, or add the stored take back to the fence. Format: [row numbers](fence-format.md#row-numbers). |
+| <a id="fence-withdrawn_claim_in_malformed_fence"></a>`withdrawn_claim_in_malformed_fence` | A facts fence that does not parse holds a claim the user withdrew, so gbrain cannot tell whether the row should stay withdrawn. | `-` | yes | Repair the fence so it parses (`gbrain repair fences --source <source>` previews it); the withdrawn row then stays withdrawn. Format: [examples](fence-format.md#examples). |
+| <a id="fence-target_fence_malformed"></a>`target_fence_malformed` | A verb that appends to or edits a page (`remember`, `extract_facts`, `takes_*`, `facts relink`, `edit_page`) found that page's stored fence does not parse and cannot be normalized in the same write (`edit_page` and the other takes writes never normalize). A fact write that would re-render a facts fence the parser reads with warnings (a malformed row, or a header naming a column outside the facts schema) refuses the same way, so the skipped rows are never dropped. Memory verbs keep their v1 code (`invalid_params`, `detail: invalid_fence`). | `-` | yes | The maintenance run repairs the stored fence; to do it now, `gbrain repair fences --slug <slug>` on the brain host. Or read the page, fix the named fence (or write the whole page with `put_page`, which normalizes what it can and names every row it cannot), then retry with a new request_id. Format: [examples](fence-format.md#examples). |
+| <a id="fence-prepare_time"></a>`prepare_time` | Hold only: the file passed the content screen, but its fence was refused while it was prepared against the stored page (a stored-row collision, a withdrawn claim, rows quoted in code). `fence.reason` names which. Managed sync holds it in the same run instead of blocking. | `-` | yes | Fix it as its `fence.reason` says. After a database-side fix (for example removing the conflicting take), `gbrain sources retry-held <source>` re-checks the file. Format: [what gbrain never guesses](fence-format.md#never-guessed). |
+| <a id="fence-normalizer_failed"></a>`normalizer_failed` | The normalizer or its validator failed on this fence (a gbrain bug); the fence was not rewritten. A coordinated write refuses; a legacy import stores the page as written. | `manual` | no | Run `gbrain doctor --json` and report it with the gbrain version; an upgrade re-screens the file. Format: [what gbrain fixes](fence-format.md#normalized). |
+| <a id="fence-llm_unavailable"></a>`llm_unavailable` | The repair model timed out, was rate-limited or returned a server error. | `llm` | yes | Nothing to do: the next maintenance run (or `gbrain repair fences --apply`) retries. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-llm_empty"></a>`llm_empty` | The repair model returned nothing for the fence. | `llm` | no | Fix the named rows by hand. The same file is not sent to the model again until it, the model (`models.fence_repair`) or gbrain's repair rules change. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-llm_refused"></a>`llm_refused` | The repair model declined to repair the fence. | `llm` | no | Fix the named rows by hand; the same file is not sent to the model again until it or the model changes. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-llm_malformed"></a>`llm_malformed` | The repair model did not return exactly one table, or wrote text outside it. | `llm` | no | Fix the named rows by hand; the same file is not sent to the model again until it or the model changes. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-llm_truncated"></a>`llm_truncated` | The repair model stopped before finishing; its output is rejected even when it parses. | `llm` | no | Fix the named rows by hand; the same file is not sent to the model again until it or the model changes. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-llm_declined"></a>`llm_declined` | The repair model answered HOLD: a row has more than one reasonable reading (two values for one column, or a cell that fits two columns), so it declined to guess. | `llm` | no | Fix the named rows by hand; the same file is not sent to the model again until it, the model or the rules change. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-llm_disabled"></a>`llm_disabled` | Model repair is off (`fences.repair.llm false`), so a fence only Tier 3 can realign waits. | `llm` | no | Fix the named rows by hand, or ask the user before turning model repair back on: `gbrain config set fences.repair.llm true` (it spends within the caps). Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-no_measured_model"></a>`no_measured_model` | `models.fence_repair` is unset and no model the fence-repair eval measured as accurate enough (`openai:gpt-6.1-sol`, `anthropic:claude-opus-5-5`, `anthropic:claude-fable-5-1`) has a provider key on this brain, so model repair is off by default. | `llm` | no | Fix the named rows by hand, or ask the user which model to trust, then `gbrain config set models.fence_repair <provider:model>` (an explicit model always runs). Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-budget_exhausted"></a>`budget_exhausted` | The page's repair estimate is over `fences.repair.max_usd_per_page` or over what is left of `fences.repair.max_usd_per_day` today (UTC). A repair run stops with exit 1 naming the spend, the cap, the reset time (next 00:00 UTC) and the pages waiting. | `llm` | yes | Nothing to do: repairs resume after 00:00 UTC. Raising a cap is the user's call: `gbrain config set fences.repair.max_usd_per_day <usd>` (or `fences.repair.max_usd_per_page`). Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-no_pricing"></a>`no_pricing` | A spend cap the user set is in force and gbrain has no price for the repair model, so no call was made. Under the default caps an unpriced model runs, metered at an estimated ceiling. | `llm` | no | Look up the model's per-token price and register it on the brain host: `gbrain pricing set <model> --input <usd> --output <usd>` ([registering a model price](../operations/spend-controls.md#registering-a-model-price)). The next run repairs it. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-ledger_unavailable"></a>`ledger_unavailable` | The spend ledger could not be read or written, so no model call was made. | `llm` | yes | Nothing to do: the next run retries. If it keeps happening, check the database with `gbrain doctor --json`. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-owner_unavailable"></a>`owner_unavailable` | This host is not the brain's owner host, and fence repairs run only there. | `-` | yes | Run `gbrain repair fences` on the owner host (`gbrain sources writer status <source>` names it). A remote caller hands that command to the user. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-owner_cli_required"></a>`owner_cli_required` | The maintenance worker may not apply this managed-file repair; it must be applied from the owner host's CLI. | `-` | no | On the owner host: `gbrain repair fences --source <source>`, then the printed apply command. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-host_mismatch"></a>`host_mismatch` | Another host id owns this source's checkout; the hold names both ids (first 8 characters). Two environments on one machine with different `GBRAIN_HOME` identity files (a launchd or cron worker and a shell) look exactly like this. Retrying from this host cannot change the answer. | `-` | no | Run `gbrain repair fences --source <source>` on the owner host (`gbrain sources writer status --source <source> --json` names it), or give the worker and the shell one `GBRAIN_HOME`. Never copy or regenerate `host.json`: a new identity orphans the ownership recorded for the old one. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-transfer_in_progress"></a>`transfer_in_progress` | A writer transfer of the source is prepared and its worktree is draining, so no host may write it yet. | `-` | yes | Nothing to do: the next run repairs it once the transfer is accepted or cancelled; `gbrain sources writer status --source <source> --json` shows the state. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-clone_in_progress"></a>`clone_in_progress` | A topology clone or reclone of the source's checkout is in progress and its worktree is recovering. | `-` | yes | Nothing to do: the next run repairs it once the clone finishes; `gbrain sources writer status --source <source> --json` shows the state. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-incarnation_changed"></a>`incarnation_changed` | The source's checkout binding belongs to an earlier incarnation of the source (it was removed and re-added, or restored), so the checkout it names is not this source's. | `-` | no | On the brain host, review `gbrain sources writer status --source <source> --json` and re-bind the checkout; the next run after that repairs the file. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-local_path_missing"></a>`local_path_missing` | This host owns the source's worktree but has no checkout path registered for it. | `-` | no | On the brain host, review `gbrain sources writer status --source <source> --json` and register the checkout again; the next run after that repairs the file. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-coordination_path_missing"></a>`coordination_path_missing` | This host's registration for the source has a checkout path but no coordination directory (where the physical-root stamp and locks live). | `-` | no | On the brain host, review `gbrain sources writer status --source <source> --json` and repair the registration; the next run after that repairs the file. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-sync_in_progress"></a>`sync_in_progress` | A write in flight names the file, or the file is still ahead in a running sync's frozen manifest (the sync would refuse it on its raw hash if a repair changed it first), so this one candidate waits; the rest of the source is repaired while the sync runs. A held file is not busy. When the busy set itself cannot be read, every candidate waits. | `-` | yes | Nothing to do: the next run retries. To finish the sync now: `gbrain sync --source <source> --no-pull`. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-time_budget"></a>`time_budget` | The repair run reached its time budget (the maintenance phase stops at the smaller of 300 s and a third of the job's remaining deadline). | `-` | yes | Nothing to do: the next run resumes where it stopped. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-changed_since_read"></a>`changed_since_read` | The file changed after the repair read it, so nothing was written. | `-` | yes | Nothing to do: the next run reads it again. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-changed_since_preview"></a>`changed_since_preview` | `gbrain repair fences --apply --expect <hash>` found the file's bytes or the page's revision changed since the preview, so that item was not applied. | `-` | no | Preview again with the same selection and apply the new `--expect` hash. Format: [tiers](fence-format.md#never-guessed). |
+| <a id="fence-still_invalid"></a>`still_invalid` | Gate (a): the proposed repair still does not parse cleanly. Nothing was written. | `-` | no | Fix the named rows by hand. Format: [gates](fence-format.md#gates). |
+| <a id="fence-claim_changed"></a>`claim_changed` | Gate (b): the proposed repair changed claim text. Nothing was written. | `-` | no | Fix the named rows by hand. Format: [gates](fence-format.md#gates). |
+| <a id="fence-row_number_changed"></a>`row_number_changed` | Gate (c): the proposed repair changed or dropped an existing valid row number. Nothing was written. | `-` | no | Fix the named rows by hand. Format: [gates](fence-format.md#gates). |
+| <a id="fence-visibility_loosened"></a>`visibility_loosened` | Gate (d): the proposed repair made a row more visible. Nothing was written. | `-` | no | Fix the named rows by hand; ask the user which visibility is intended, never widen it yourself. Format: [gates](fence-format.md#gates). |
+| <a id="fence-row_count_changed"></a>`row_count_changed` | Gate (e): the proposed repair added or dropped a row, or left one outside the fence. Nothing was written. | `-` | no | Fix the named rows by hand. Format: [gates](fence-format.md#gates). |
+| <a id="fence-cell_changed"></a>`cell_changed` | Gate (f): the proposed repair changed a cell no named rule allows (a valid weight, holder, date, source, confidence or context). Nothing was written. | `-` | no | Fix the named columns of the named rows by hand. Format: [gates](fence-format.md#gates). |
+| <a id="fence-protection_loosened"></a>`protection_loosened` | Gate (g): the proposed repair would show text the privacy boundary hid before it. Nothing was written. | `-` | no | Add the end marker where the fence really ends. Format: [gates](fence-format.md#gates). |
+
+A managed source a fence refusal blocked before this release recovers on its
+next sync with no command: the file is held and the rest imports
+(`gbrain sync --source <source> --no-pull` does it now).
+
+A source that a gbrain older than v0.60.47.0 blocked on one of these refusals
+recovers on its next sync (scheduled or manual) with no ledger surgery: the blocked request is
+converted in place and reported as `converted_from_failed`. To do it now run
+`gbrain sync --source <source> --no-pull`. `gbrain config set sync.holds fail`
+makes sync fail closed for teams that want it. Escalation:
+more than `GBRAIN_SYNC_HOLD_ESCALATE_COUNT` (default 50) holds in a source, or more
+than `GBRAIN_SYNC_HOLD_ESCALATE_PCT` (default 5%) of a run's screened imports (at
+least 40), sets `holds_escalated` and makes doctor `git_held_files` fail: a
+generator or an upgrade is likely writing or reading files wrong.
+
+<a id="content-repair-lane"></a>
+### The content-repair lane
+
+Fence and slug-conflict holds clear by themselves: the maintenance run's
+`fence_repair` phase runs the `fences` kind and its `content_repair` phase
+runs every other kind of the lane (`src/core/repair/content-lane.ts`), and
+`gbrain sync unblock --source <source> --apply` runs the lane on the held paths
+now. Each repair is a hash-bound write with a receipt and a Git trailer; a
+model decides only the cases the deterministic rules mark ambiguous, under the
+`fences.repair` caps, and every byte written comes from a rule and passes the
+gates. The lane records five outcomes a person reads, each with the agent
+operator envelope (`code`, `message`, `why`, `fix.next`); `gbrain errors <code>`
+explains each offline. Walkthrough: [held files](repair.md#held-files).
+
+**Say to your agent:** *"Sync is holding a few files. Repair the ones gbrain
+can and tell me what it wants me to decide about the rest."*
+
+| Code | What it means | Envelope |
+| --- | --- | --- |
+| <a id="unclosed_ambiguous_tail"></a>`unclosed_ambiguous_tail` | An `invalid_fence` reason: a fence has no end marker, text follows its table, and the repair model read the tail as table rows written without pipes (`rows`) or could not tell (`unsure`), so gbrain will not choose where the fence ends. Nothing was written; the memo keeps the same bytes from costing twice. | `fix.next: tell_user_to_run`, actor `user`: the hold's `fix` is the read-only preview naming the fence, section and last row; the person adds the end marker after the last real row (moving any rows the tail holds into the table), commits, then `gbrain sync --source <source> --no-pull`. `why`: closing after the wrong row would hide rows or expose text. |
+| <a id="tail_exposure_approval"></a>`tail_exposure_approval` | An `invalid_fence` reason on a world-visible page: the repair model read the trailing lines as prose, so closing the fence after its last row is safe for the table but makes those lines visible to remote readers. The close is previewable, never unattended: the preview prints the exact lines (`L1-L2`) that would become visible and the hash binds them. `paid: false`. | `fix.next: ask_user`, actor `user`, `consent: []`: the hold's `fix` is `gbrain repair content --source <source> --only <path> --apply --expect <hash>` with `preview_argv` the lane preview and `plan_hash` the hash; relay the preview's exposed lines, run the fix only after the user agrees. A changed tail invalidates the hash (`changed_since_preview`). `why`: the privacy boundary hid those lines until now. |
+| <a id="merge_recommended"></a>`merge_recommended` | A `frontmatter_slug_conflict` hold whose two files describe the same thing (a duplicate person or company page): the lane's deterministic tier found something to merge into and the model answered `merge_into <canonical>`, so removing the `slug:` line would have minted a second page. Nothing was written; the hold carries `meta.content_repair: { action: 'merge_into', canonical }` (codes and slugs only) and `sync status` renders the paragraph. gbrain does not merge pages by itself yet. | `fix.next: tell_user_to_run`, actor `user`: "This file and page `<canonical>` describe the same `<type>`; gbrain recommends merging the unique sections of `<path>` into `<canonical>` and deleting `<path>`, then committing; the hold clears on the next sync." `fix.argv` reads both pages (`gbrain get --source <source> -- <slug>`); `verify` is `gbrain sync status --source <source> --json`. Not retried until the file changes. |
+| <a id="content_repair_needs_human"></a>`content_repair_needs_human` | A `frontmatter_slug_conflict` hold the lane could not decide: the deterministic tier marked it ambiguous and the model answered `needs_human` (or model repair is off, out of budget or unavailable for the day). Nothing was written; the hold carries `meta.content_repair: { action: 'needs_human' }` and `sync status` says `needs_human: true`. | `fix.next: tell_user_to_run`, actor `user`: "gbrain could not decide whether `<path>` and `<canonical>` are the same page; decide which keeps the slug: remove the `slug:` line, move the file, or merge the pages, then commit." A budget or model wait names its setting instead (`fences.repair.max_usd_per_day`, `fences.repair.llm`, consent `paid`, `fix.next: ask_user`). `verify` is `gbrain sync status --source <source> --json`. |
+| <a id="slug_page_mismatch"></a>`slug_page_mismatch` | A `frontmatter_slug_conflict` hold the lane judged with the same screen managed sync froze it with, and sync would still hold whatever the lane writes: sync files the file as page `<slug>` (the page that records it as its origin, or its path-derived slug), but the path derives another slug, or the `slug:` line reaches that page only through an alias or another spelling. Removing the line would not clear the hold, so nothing was written; the hold carries `meta.content_repair: { action: 'remove_slug', reason: 'slug_page_mismatch', named }` with the other slug. Earlier releases reported this as a generic `still_invalid` ("the frontmatter needs other changes too") or skipped it as `already_exempt`. | `fix.next: run`, actor `agent`: make the `slug:` line name `<slug>` exactly, or move the file to the path that derives `<slug>`, commit, then `gbrain sync --source <source> --no-pull`. `fix.argv` is `gbrain repair content --source <source> --only <path>` (read-only preview); `verify` is `gbrain sources status <source> --json`. |
+
+## Worktree refresh refusals
+
+`gbrain sources refresh <source>` is the one supported way to move a managed
+checkout to new upstream commits. It runs on the source's registered owner
+host, fetches, then refuses new writes to every source that shares the
+checkout while queued writes finish, fast-forwards with `git merge --ff-only`
+and syncs each of those sources with `--no-pull`. Each refusal below prints
+`code`, a one-line `cause`, a literal `fix` with the real source filled in and
+this anchor (`--json` puts them in one object on stdout); the command exits 1.
+
+**Say to your agent:** *"Pull the latest commits into my notes source."* or
+*"The refresh was refused. What do I need to do?"*
+
+| Reason | Error code | What it means | Recovery |
+| --- | --- | --- | --- |
+| <a id="refresh_not_managed"></a>`refresh_not_managed` | `refresh_not_managed` | The brain is not managed, or the source has no claimed checkout. Plain sync already pulls such a source, so there is nothing to coordinate. | `gbrain sync --source <source>`. |
+| <a id="refresh_not_owner"></a>`refresh_not_owner` | `refresh_not_owner` | This host is not the source's registered owner, and only the owner may move its checkout. | Run `gbrain sources refresh <source>` on the owner host; `gbrain sources writer status <source>` names it. |
+| <a id="refresh_no_upstream"></a>`refresh_no_upstream` | `refresh_no_upstream` | The checkout's branch tracks no upstream, HEAD is detached, or the checkout is not a Git checkout at all (gbrain never initializes Git on its own), so there is nothing to fast-forward to. | `git -C <checkout> branch --set-upstream-to <remote>/<branch>` (the fix fills in the real values), then retry. A checkout that is not Git has nothing to refresh; making it a clone with an upstream is the user's call. |
+| <a id="fetch_failed"></a>`fetch_failed` | `fetch_failed` | `git fetch` failed or did not finish within `sources.refresh_fetch_timeout_ms` (default 120000; `GBRAIN_REFRESH_FETCH_TIMEOUT_MS`; `--fetch-timeout-ms` wins over both). Nothing changed and no refresh record was written. | Retry. For a slow remote, raise the bound with `--fetch-timeout-ms <ms>` or `gbrain config set sources.refresh_fetch_timeout_ms <ms>`. Credentials are the user's: ask them to fix authentication rather than changing the remote. |
+| <a id="refresh_git_unavailable"></a>`git_unavailable` | `git_unavailable` | A git command that reads the checkout's branch or remote (`symbolic-ref`, `remote`, `config --get branch.<branch>.remote` or `.merge`) failed or did not finish, so the checkout's state is unknown. The message names the command and git's first error line. A detached HEAD or an unset key is not this refusal. Nothing changed and no refresh record was written. | Run `git -C <checkout> status` to see why git cannot read the checkout, repair what it reports, then retry `gbrain sources refresh <source>`. |
+| <a id="refresh_diverged"></a>`refresh_diverged` | `refresh_diverged` | The checkout has commits its upstream lacks, so a fast-forward is impossible. Nothing changed. | Ask the user, then publish the local commits merged with the upstream: `gbrain git commit-push --push-only --keep-checkout --path <checkout>` merges in memory, pushes the merge, refuses on a conflicting file and never moves the checkout (the refusal's fix fills in the real path and counts the local commits). Then retry `gbrain sources refresh <source>`, which fast-forwards to the merge. `gbrain sources reclone <source>` replaces the checkout instead and drops the local commits. With `sources.refresh_publish_diverged` set to `true` (the user's standing consent, default off), the refresh runs that publish itself, in a child process that skips the pre-push hook, and then fast-forwards; a conflicting file then refuses `integrate_conflict` (with `gbrain.quarantine` on, the remote's version is published instead, this machine's is kept under `refs/gbrain/quarantine/`, and the refresh says so), and an uncommitted edit to a file the upstream changed refuses `refresh_dirty`, both with nothing pushed. The setting never publishes over a rewritten upstream: when the checkout holds a commit the upstream held before but no longer contains (a force-push), or gbrain has no record of the upstream before the fetch, the refresh still refuses `refresh_diverged` and the user decides. |
+| <a id="refresh_dirty"></a>`refresh_dirty` | `refresh_dirty` | Uncommitted or untracked files overlap the incoming upstream changes (the first 20 are named), or `git merge --ff-only` refused for the same reason. HEAD did not move. The merge runs under the checkout's commit lock, so a `gbrain git commit-push` in progress is waited out (#8117); a lock held past its wait refuses as `commit_lock_busy`, and another git process holding `.git/index.lock` refuses as `git_index_locked` after brief retries. Both are retryable. Uncommitted files outside the incoming changes do not refuse; they are kept and listed as `preserved_uncommitted`. | Commit or discard the named paths, then retry. Check `gbrain sources writer status <source> --json` first: a pending Git effect may be about to commit a gbrain-published file. |
+| <a id="sync_in_progress"></a>`sync_in_progress` | `sync_in_progress` | A managed sync of one of the checkout's sources has an unfinished cursor. Moving the checkout now would strand it, and the refresh never waits on a sync. `gbrain repair frontmatter --apply` refuses the same way while an unfinished cursor still names a selected file. | Run the printed `gbrain sync --source <source> --no-pull ...` resume command (it keeps the cursor's options), then retry (for a repair, preview again and approve the new hash). |
+| <a id="refresh_in_progress"></a>`refresh_in_progress` | `refresh_in_progress` | Another refresh of the same checkout is active and its process is still running (the message names its holder's pid and host when the active refresh row is already readable), or a command that changes which sources share the checkout (`sources add`, `remove`, `archive`, `restore`, `reclone`) ran while one was active. A refresh whose process died is not a reason to refuse: the next refresh on the owner host finishes it first (`--dry-run` does not, so it still refuses while the orphan stands, and neither does a refresh that cannot read the checkout's HEAD: it leaves the orphan as it is and refuses until git can read HEAD again). A refresh whose holder is recorded on another host is never taken over either: writer status shows its `liveness` as `unknown`, and `gbrain sources refresh <source> --resume` on the owner host finishes it once that host's refresh is known to have stopped. Pending publication or topology recovery on the checkout refuses `refresh_recovery_required` first. An interrupted refresh that needs a reset decision refuses `refresh_recovery_required` instead. | Wait for the running refresh, or check it with `gbrain sources writer status <source>` (`liveness`, `holder`). `gbrain sources refresh <source> --resume` finishes an orphaned one now; then retry the source command with the same request ID. |
+| <a id="refresh_drain_timeout"></a>`refresh_drain_timeout` | `refresh_drain_timeout` | Queued writes or Git effects on the checkout did not finish within `--wait-drain` (default 60 s; `sources.refresh_drain_wait_ms`; `GBRAIN_REFRESH_DRAIN_WAIT_MS`). The counts are in the message. The fence was lifted and HEAD did not move. | Retry, or wait longer with `--wait-drain <seconds>`. Inspect what is queued with `gbrain sources writer status <source> --json`. |
+| <a id="refresh_lock_timeout"></a>`refresh_lock_timeout` | `refresh_lock_timeout` | The refresh fence locks the brain, worktree, source and refresh rows with a 5 s lock timeout, and another database transaction held one of them longer. `why` lists the five oldest open transactions in this database holding locks on those tables (pid, application, state, how long the transaction has been open). They are candidates: the blocker may not be among them, because Postgres does not show which row each one holds. It never repeats their SQL, and says so when that lookup failed or took longer than 3 s. HEAD did not move: no fence was set, or the draining refresh was aborted. When the same holder also blocked that abort, the refusal says the row stays `draining`, and the next `gbrain sources refresh <source>` resumes it. | Retry `gbrain sources refresh <source>`. If it repeats, a transaction holding one of those rows is stuck: `why` lists the oldest candidates, so confirm the blocker on the brain host before ending any transaction. |
+| <a id="refresh_sync_timeout"></a>`refresh_sync_timeout` | `refresh_sync_timeout` | Reported per source in a refresh's `sync_blocked`, not as a refusal: the source's managed sync committed nothing within its share of the refresh sync budget (each member gets an equal share of what is left; `sources.refresh_sync_budget_ms`, `GBRAIN_REFRESH_SYNC_BUDGET_MS`, default 5 min), for example because no consumer claimed its write. The message names that write and its state. The checkout is at the upstream commit, the refresh completed and released its lock, and the source is behind until its next sync. A sync stopped by the drain's own rules is reported with that stop's code instead (`drain_stalled` and the others). | Run the `resume` command (`gbrain sync --source <source> --no-pull`). If it stalls the same way, check the write it names with `gbrain sources writer status <source> --json`. |
+| <a id="refresh_source_changed"></a>`refresh_source_changed` | `refresh_source_changed` | HEAD moved (an outside commit or checkout), or the checkout's ownership or set of sources changed, between the precheck and the merge. Nothing was merged and the fence was lifted. | Retry `gbrain sources refresh <source>`. |
+| <a id="refresh_recovery_required"></a>`refresh_recovery_required` | `refresh_recovery_required` | Publication or source recovery is pending on the checkout, or a refresh was interrupted and HEAD is neither the commit it started from nor the verified upstream commit. Writes to the checkout stay refused until it is resolved; gbrain never adopts a HEAD it cannot verify. | `gbrain sources writer status <source>`, then `gbrain sources refresh <source> --resume`. When HEAD is unverified the fix names both ways out: reset to the start commit and run `--abandon`, or reset to the upstream commit and run `--resume`. Resetting is destructive, so ask the user first. |
+| <a id="worktree_refreshing"></a>`worktree_refreshing` | `worktree_refreshing` | A write, or a managed sync started by a cycle or another command, reached a checkout while a refresh is draining or merging it. It was not journaled. `detail` is `retry_after_ms=1000`. Writes to database-only memory are not affected. | Retry the same request ID after about a second. `gbrain sources writer status <source>` shows the refresh. A cycle's sync is retried by the next cycle. |
+
+A refresh is recorded in `persistence_worktree_refreshes` and survives a crash.
+When the owner restarts it finishes the deterministic steps on its own: an
+interrupted drain or a fence with HEAD unchanged is abandoned, and a merge
+that already reached the verified upstream commit moves on to syncing.
+`gbrain sources refresh <source> --resume` runs the remaining syncs. A
+refresh whose process died (for example a container replaced mid-refresh)
+does not wedge the checkout: the owner completes a syncing one once every
+source has synced to its target, and the next plain `gbrain sources refresh`
+on the owner host finishes any other one the same way `--resume` does, then
+refreshes. A refresh whose process is still running is never taken over.
+`gbrain sources writer status` and `gbrain sync status` show who holds each
+refresh and whether it is orphaned. With `--json`, a refresh refusal that
+carries a structured next step (`refresh_diverged`'s consent-gated publish,
+`refresh_in_progress`'s writer status read, a git read failure) prints it as the
+v1 `fix` object (`argv`, `next`, `actor`), with the prose in `suggestion`;
+any other refusal keeps the stored command string in `fix`. Doctor
+reports `worktree_refresh_stuck` for a refresh active longer than 15 minutes,
+with the resume command.
+
+## Managed sync drain stops
+
+`gbrain sync` on a managed brain keeps going until the source's cursor is done
+(see [catching up a large backlog](live-sync.md#catching-up-a-large-backlog-on-managed-postgres)).
+When it stops early, the run ends in one outcome: `resumable` (exit 0, safe to
+rerun the same command) or `blocked` (exit 1, needs a fix first). `--json`
+carries `outcome`, `drain.stop_reason` and `next: { command, safe_to_loop,
+retry_after_ms, eta_seconds, rate_pages_per_min, why, docs }`. Run
+`next.command`; loop on it only when `next.safe_to_loop` is true.
+
+**Say to your agent:** *"Catch up my managed brain's sync backlog and tell me how long it will take."*
+
+| Stop reason | Code | Outcome | What it means | Recovery |
+| --- | --- | --- | --- | --- |
+| <a id="drain-stopped-at-its-deadline"></a>`deadline` | `writer_pending` | `resumable` | `--timeout`, `--hard-deadline`, Ctrl-C or the run deadline stopped the drain, or a `sync` job reached its own deadline (its `timeout_ms` less a 60 s reserve). Accepted page writes keep their request IDs and the cursor is intact. | Rerun `next.command` (the same options). It resumes where the last run stopped. A `sync` job that queued a follow-up (`continuation_job_id`) names it in `next` instead: watch it, don't start a second sync beside it. |
+| <a id="drain-stalled"></a>`drain_stalled` | `drain_stalled` | `blocked` | The awaited page write and the oldest unfinished write on its checkout made no progress for the whole stall window: no committed receipt and no step advance. A lease renewal is not a change: the detector keys on the head claim's phase and step. With a live owner on **this host**, the drain does not stop at the allowance (the preparation budget plus 30 s): from there it prints `stalled <N>s on <step>` with the owner's pid and kind every 10 s and keeps going, because the owner's own budget frees the root by `persistence.preparation_ceiling_ms` (600 s) and the next pass holds the entry. It stops `drain_stalled` only when the ceiling passes without the root being released, or when the owner's `persistence_consumers` row reads wedged (`restart_required`, or a root barrier older than the ceiling); the stop then carries `cause: owner_wedged_here`, the owner `{kind, pid, nonce}`, `retry_after_ms` (the time left to the ceiling, 0 once past), `next.safe_to_loop: true` while the ceiling is ahead and `next.fix.next` `wait` before it, `tell_user_to_run` (restart the named pid) after it. A lapsed claim (`owner_missing`) stops at once, unless this host owns the checkout and a live full consumer exists, which gets exactly one more window. Other causes: `preparation_overdue` / `publication_overdue` (a live owner elsewhere past its allowance) and `no_progress` (an unstamped head). A pass that never returns is stopped from inside (`drain.stall.in_pass: true`, the same rules whether or not the drain prints progress): a head claim live in `publishing` past `persistence.publication_ceiling_ms` (default 300 s) stops `publication_overdue`, and its `next` says to restart the process that owns the publication, because an unfinished publish can hold its locks until it settles and nothing reclaims it for you; a pass that admitted nothing and left no unfinished request for 5 minutes stops `no_progress` with the step it was in (`freeze`, `waiver_run`, `admission`, `await_receipt`) and the last statement label, which is what a transaction-mode pooler that never answers a round trip looks like (older builds named this cause `no_admission`; it is retired, and a receipt carrying it means the same). The pass returns when the run's final checkpoint commits: the tail after it (planner statistics, link extraction for the imported pages) runs after the drain lease is released, outside this governor, bounded at 5 minutes; the checkpoint's own transaction records it as owed, so a process that dies before it leaves it for the next sync of the source, and a failed or cut-short tail keeps the run `synced` with a `[gbrain notice sync_tail_degraded]` whose fix is `gbrain extract --stale --source-id <id>`. The owner process bounds its own publish the same way: past the ceiling the claim reads `waiting_on: publication_deadline`, a Postgres publish transaction idle past it is ended by the server (nothing commits), 30 s later a Postgres publish still running is cancelled (its connection is discarded, nothing commits, and the write is queued again), and a publish that still has not settled 35 s after the ceiling makes the owner report `restart_required` (its heartbeat row carries `restart_required`, which the drain reads as `owner_wedged_here`; the consumer status lists it under `stuck_publications`); restart that process. `drain.stall` carries `phase`, `step`, `waiting_on`, `cause`, the owner and whether this host owns the checkout. | `gbrain sources writer status --source <source> --json`: its `next_action` says whether to wait (`retry_after_ms`) or which pid to restart. Before the ceiling, rerun `next.command` after `retry_after_ms` (safe in a loop). Past it, or with a wedged owner, restart the named owner process (`gbrain serve`, the jobs worker or autopilot) on the brain host, then rerun `next.command`; the held entry needs `gbrain sources retry-held <source>` afterwards. When this host is not the owner, make sure the owner's `gbrain serve` is running. |
+| <a id="drain-database-contention"></a>`database_contention` | `database_contention` | `blocked` (or an error) | Three consecutive passes hit database contention, a statement timeout or a dropped connection, or reading the awaited write's state failed (an authentication or permission failure stops at once). The drain retries transient failures with backoff before giving up. Accepted writes keep their request IDs. | Fix database access (`gbrain engine status --probe`), then rerun `next.command`. |
+| <a id="drain-writer-blocked"></a>`recovery_required`, `owner_unavailable`, `unexpected_file_bytes`, `unexpected_staging_bytes` | `recovery_required` | `blocked` | The checkout's writer needs intervention before more pages can publish: interrupted publication recovery, no live owner, or unexpected bytes in the file or staging area. | `gbrain sources writer status <source>` and the fix it prints. Unexpected bytes are the user's edits; ask before discarding them. Then rerun `next.command`. |
+| <a id="drain-blocked-by-a-failed-page"></a>`blocked_by_failures` | `blocked_by_failures` | `blocked` | A page write failed terminally. `managed_write` and `failures` name the page and cause. Rerunning without a fix returns the same failure. | Fix the cause, then run `next.command` (the plain sync with the same options). Ask the user before skipping content. |
+| <a id="drain-preparation-abandoned"></a>`preparation_abandoned` | `preparation_abandoned` | `resumable` | A write this process's own writer holds was still preparing past its allowance (its budget plus 30 s, never more than the ceiling `persistence.preparation_ceiling_ms` plus 30 s) and the process cannot cancel it, so the sync exited to end it. The cursor and accepted writes are intact; `drain.stall` names the step (`stall.step`, `stall.waiting_on`). Exit 0. | Rerun `next.command` (`safe_to_loop` is true). The next pass holds the entry as `preparation_stalled` if it stalls again; `gbrain sources writer status --source <source> --json` shows what it was stuck on. |
+| <a id="preparation_systemic"></a><a id="drain-preparation-systemic"></a>`preparation_systemic` | `preparation_systemic` | `blocked` | The run's breaker tripped: more `preparation_stalled` receipts than a source should hold (the `GBRAIN_SYNC_HOLD_ESCALATE_COUNT` / `GBRAIN_SYNC_HOLD_ESCALATE_PCT` rule over this run's screened imports) or five stalled entries in a row with no page committed between them. The run stopped with one diagnostic instead of holding every file: the write owner, not the files, is the likely cause. `breaker` carries the rule, the counts, the last step and the fix; exit 1. | `gbrain sources writer status --source <source> --json`, fix what it names or upgrade gbrain, then rerun the same sync: it re-freezes the stopped entry under a fresh request and schedules the files this run held for a re-screen. |
+| <a id="drain-write-capacity"></a>`write_capacity` | `queue_capacity` | `blocked` | The sync could not admit its next write for the whole no-progress window (30 s) because other writers' requests held the outstanding-request cap of its write principal (`persistence.limits.principal_outstanding`, default 100; the brain cap `persistence.limits.brain_outstanding`, 1000, works the same way): on one host the CLI sync and a maintenance run (fact-fence adoption, `dream`) share the `local_cli` principal, so a long adoption queue leaves no room for a sync write. Nothing failed and the cursor is intact: the drain retried the admission with backoff while they settled, printing `waiting for write capacity (N outstanding of M)`, and stopped only when the window passed. `drain.capacity` carries the counts and the wait; exit 1. A cumulative cap (permanent request IDs, receipt bytes) is a different refusal: it names its config key and stops at once. | `gbrain sources writer status --source <source> --json` lists the outstanding requests (read-only). Let them finish, or raise the cap (`gbrain config set persistence.limits.principal_outstanding 200`), then rerun the same sync; it resumes where it stopped. |
+| <a id="drain-connection-lost"></a>`connection_lost` | `connection_lost` | `blocked` | The database connection dropped three times in a row (`write ECONNABORTED`, `ECONNRESET`, `ETIMEDOUT`, `EPIPE`: a pooler closing the socket mid-statement) with no page committed between the drops (#6340). Each drop was reconnected and retried after 5, 15 and 45 s; a drop that then moves data is not reported at all. Nothing is recorded against the source: the cursor and its frozen manifest stand, and `drain.connection` carries the count and the last error text (never a URL). Exit 1. | Check the database and pooler (`gbrain doctor --json`), then rerun `next.command` (`safe_to_loop` is true, `retry_after_ms` 60 s): it resumes at the stored cursor without re-freezing the manifest. Runbook: [sync unblock](sync-unblock-runbook.md#connection). |
+| <a id="drain-capacity-paused"></a>`capacity_paused` | `capacity_paused` | `resumable` | The run passed its capacity preflight, then a cumulative write cap refused its next admission (`write_quota_exhausted`) or, for a background sync, the pause line did (`write_capacity_backpressure`): another writer used the room the preflight counted on. Nothing failed; the cursor and every accepted write stand, and `drain.capacity_pause` names the refusal and its config raise. | Run the `gbrain config set` the report names on the brain host (request ids never free; receipt bytes also free as receipts compact), then rerun the same `gbrain sync`. Verify with `gbrain doctor --only persistence_capacity --json`. |
+| <a id="head-blocked"></a>`drain_stalled` with `cause: head_blocked` | `drain_stalled` | `blocked` | The queued write at the head of the source cannot be claimed by any consumer, and its blocker needs an operator (#6543). `drain.stall.blocked_by` names the predicate, its ids, state and owner: `refresh_fence` (a refresh left the checkout `fenced`, `merged` or `recovery_required` and no refresh process holds its lock), `zombie_publication` (a running request ahead of the head is held by a process that reports `restart_required`), or `effect_recovery` with state `unexpected_file_bytes` (a fact-withdrawal mirror's page file was edited while the mirror was publishing, so its forward-only recovery refuses to overwrite it), or `request_recovery` with state `unexpected_file_bytes` (a page write's file, or a file of a shared-skill bundle, was edited while it was publishing, #6650; this also covers a head that is itself that recovering write). For both, `blocked_by.file` names the page and path (an effect's also names its withdrawal request). `effect_recovery` or `request_recovery` with state [`recovery_version_unsupported`](#recovery_version_unsupported) is a record a newer gbrain wrote, which no recovery here finishes. A recovery stuck on `unexpected_staging_bytes` is not classified yet and still waits out the window. The drain stops after one governor tick of confirmation instead of the no-progress window. Live blockers (`root_hold`, a foreground publication; `lease`, a lapsed claim the next consumer reclaims; `withdrawal_mirror`, an `effect_recovery` or `request_recovery` that can still finish, `worktree_owner`) never stop it: the stall line names them as `blocked_by=` beside `consumer=` and the drain keeps waiting. `claimable here` is read for the head itself and prints `unknown` when the probe could not read it. | Run `next.fix`: `refresh_fence` resumes the refresh (`gbrain sources refresh <source> --resume`, which lifts the fence or names why it cannot); `zombie_publication` tells the host admin to restart the named process; `effect_recovery` runs the [`gbrain repair stuck-recovery --source <source> --request-id <request>`](repair.md#stuck-recovery) preview, whose only choice (`--keep withdrawn`, the user's to apply) backs the edit up and writes the withdrawn version; or the user restores the committed version, never deletes the file, and redoes the edit without the forgotten fact; `request_recovery` runs the [`gbrain repair stuck-recovery --source <source>`](repair.md#stuck-recovery) preview, and the user either keeps one version through it or undoes the edit. Then rerun the sync. `gbrain sources writer status --source <source> --json` names the same blocker for every queued head and, only when the caller may cancel the blocking request, `gbrain cancel-write-request <request_id>`; `recovery_version_unsupported` tells the user to run `gbrain upgrade` on the owner host. |
+| <a id="sync_drain_lease_held"></a>`drain_lease_held` | `sync_drain_lease_held` | `resumable` | Another process holds the source's drain lease (#6712): one managed drainer per source, and that holder (a serve, a `sync` job, the dream cycle, another terminal) is still committing pages. `gbrain sync` follows it within its own `--timeout` and run deadline, printing the holder (kind, pid, host, gbrain version) and the pages it commits (every 10 s on a terminal, 60 s otherwise), and takes the lease when the holder releases it. This code means the budget ended first, or the lease moved to another process mid-pass (`lost`); nothing this run admitted is lost and the cursor is intact. `--no-delegate` never skips the lease. `drain.lease_held.holder` reuses the drain's owner fields: `kind`, `id`, `host`, `pid`, `started_at`, `last_heartbeat_at`, `version` and `progress` (`committed`, `last_committed_at`, `last_progress_at`); `next.retry_after_ms` is 60 s and `next.safe_to_loop` is true. Exit 0. A cron that runs `gbrain sync` every few minutes beside a serve exits 0 here on each tick while the serve works. | Rerun `next.command` after `next.retry_after_ms`, or let the holder finish. Ctrl-C while following stops only this run; the holder keeps going. A holder that commits nothing for 5 minutes is not reported here: the run stops [`drain_stalled`](#drain-lease-stalled) instead. |
+| <a id="drain-lease-stalled"></a>`drain_stalled` with `cause: no_progress` and `stall.lease_holder` | `drain_stalled` | `blocked` | The process holding the source's drain lease committed no page and saved no cursor for 5 minutes, so following it would exit 0 forever (#6712). `drain.stall.lease_holder` names it with the fields above; the lease itself is renewed by a live process, so a wedged holder keeps it. A holder that died lets its lease lapse within 2 minutes and the next run takes over without this stop. Exit 1, `next.safe_to_loop` false. | `gbrain sources writer status --source <source> --json` (read-only) shows what the holder is waiting on. Stop or restart the named process; when it is gone but its lock row remains, `gbrain sync --source <source> --no-pull --break-lock` releases a lock whose pid is dead (`--force-break-lock` skips the liveness check: only when you know the holder is gone). Then rerun the same sync. |
+| <a id="drain-not-converged"></a>`not_converged` | `not_converged` | `resumable` | The live pass (#6712 PR 4b) used its rounds without the level settling: another writer kept changing the checkout or the database while it ran. Everything it admitted stands and nothing is held for it; the pass row counts consecutive such passes (`not_converged_streak`). | Rerun the same `gbrain sync` (`next.safe_to_loop` is true). After three consecutive `not_converged` passes `next` turns to `report` (`safe_to_loop` false): run `gbrain sync status --source <id> --json` and `gbrain doctor --json` and report what keeps changing. Exit 0. |
+| <a id="drain-admission-paused"></a>`admission_paused` | `admission_paused` | `resumable` | `sync.admission` is `imports_only` or `classify_only`, so the pass admitted only what it allows (or nothing) and stopped; a destructive write paused at publication is completed `cancelled` with `admission_paused`. Nothing failed. | Restoring admission is the owner's decision: `gbrain config set sync.admission normal` (`next.fix` is `tell_user_to_run`; never run automatically). The next sync continues. Exit 0. |
+| <a id="drain-grant-scope"></a>`grant_scope` | `grant_scope` | `blocked` | The pass ran under a grant that covers only part of the source, so it admitted what the grant can see and cannot stamp the source. | On the owner host run `gbrain sync --source <id> --no-pull` (`next.fix` is `tell_user_to_run`), then verify with `gbrain sync status --source <id> --json`. Exit 1. |
+| <a id="drain-reconcile-host-required"></a>`reconcile_host_required` | `reconcile_host_required` | `blocked` | A remote caller's pass admitted what it could; the rest needs the owner host, because remote callers never write holds, markers, keep_db writes or the stamp. | On the owner host run `gbrain sync --source <id> --no-pull` (`tell_user_to_run`), then verify with `gbrain sync status --source <id> --json`. Exit 1. |
+| <a id="drain-reconcile-read-incomplete"></a>`reconcile_read_incomplete` | `reconcile_read_incomplete` | `blocked` | A Git listing the pass reads (`ls-tree`, `ls-files`, `diff-tree`) did not finish cleanly, so the pass classified and wrote nothing. | Check the checkout with `git -C <dir> status`; report it with `gbrain doctor --json` if it repeats (`next.fix` is `report`). Exit 1. |
+
+## Unbound sources on Postgres
+
+A source with a checkout path (`local_path`, or `sync.repo_path` for the
+`default` source) normally publishes every page write to a markdown file in
+that checkout, through the source's canonical owner. PGLite claims that owner
+automatically on the first write. Postgres does not, because several hosts can
+share one Postgres brain and only one of them may own the files. Neither does
+PGLite for a source `writer activate` listed under `database_only_sources`
+(a rooted source with no owner on a brain whose `sync.write_through` was off,
+#6449; the list is the config key `persistence.database_only_sources`, which
+deactivation clears): turning the setting back on never starts an unreviewed
+claim there. Until someone binds the source, page writes to it refuse with
+`owner_unavailable` and `detail: unbound_source`. The refusal is a
+configuration state, not a transient one: it renders `retryable: false` and a
+`fix` with `next: ask_user`, so an agent never retries it.
+
+**Classic mode (managed persistence not activated).** This is the normal state
+of a self-hosted Postgres brain that never ran
+`gbrain sources writer activate`, and of any brain after
+`gbrain sources writer deactivate`. In classic mode the checkout is the source
+of truth: gbrain reads it and does not write files into it. Page writes through
+`put_page`, `capture`, `delete_page`, `restore_page`, `revert_version`,
+`add_tag`, `remove_tag`, `add_timeline_entry` and the `takes_*` tools refuse
+with `unbound_source`, and so do `remember` about an existing entity page and
+`forget` or `forget_fact` of a claim that a canonical file carries (their
+frozen code stays `unavailable`, with `write_error: owner_unavailable` and the
+same detail and fix; a claim that only database-only pages carry is still
+withdrawn, database-only). What works:
+
+1. **Write the file, commit, sync** (the classic write path). Write or edit
+ `<checkout>/<slug>.md`, check generated frontmatter with
+ `gbrain frontmatter validate --stdin --path <slug>.md`, commit it with
+ `gbrain git commit-push --path <checkout> -m <msg> -- <slug>.md`, then
+ run `gbrain sync --source <id>`. Sync imports commits; `--working-tree`
+ imports uncommitted edits for one run. Delete the file, commit the deletion
+ the same way, sync.
+ Tags and timeline entries are frontmatter and `## Timeline` lines in the
+ same file.
+2. **Database-only pages**, if the user accepts that new pages never reach the
+ checkout, its git history or file backups:
+ `gbrain config set persistence.unbound_write database_only` (below). It
+ never covers pages that came from files.
+3. **Leave classic mode** (a brain-wide decision for the user): claim the
+ source and activate managed persistence
+ ([topologies](../architecture/topologies.md#pre-activation-claims)). A claim
+ without activation blocks classic `gbrain sync` of that source, so never
+ claim to get one refused write through.
+
+**What the agent tells the user.** An agent with a shell on the brain host
+asks once, then uses path 1 itself and reads the page back. A remote agent
+(MCP) cannot write the checkout; it says: *"Your brain is in classic mode, so
+I can't save pages directly. Save it as `<slug>.md` in the `<id>` folder,
+commit it, and run `gbrain sync --source <id>`. Or I can explain the two other
+options: database-only pages, or managed mode."* It does not retry the write.
+
+**Managed mode, or a gbrain-owned checkout.** The suggestion names both ways
+out with the real source filled in:
+
+1. **Bind the source** on the host that holds the checkout. Run
+ `gbrain sources writer status <source> --json` and note `admin_state`, then
+ `gbrain sources writer claim <source> --path <checkout> --admin-intent writer_claim --expected-state <admin_state>`.
+ If an operator has locked writer administration, ask them to unlock it
+ first. Read [topologies](../architecture/topologies.md) before claiming a
+ source that other hosts write to.
+2. **Allow database-only writes** with
+ `gbrain config set persistence.unbound_write database_only` (the default is
+ `refuse`; no other value is accepted, and the key can only be set on the
+ brain host). Every page write to a page with no recorded canonical file
+ (a new page, or one with no stored source path) then writes to the
+ database only: `put_page`, `capture`, `delete_page`, `restore_page`,
+ `revert_version`, `add_tag`, `remove_tag`, `add_timeline_entry`, the
+ `takes_*` writes, and a `remember` (or loop-close retirement) whose fact
+ is fenced into that page's database body. Its result says
+ `write_through: { written: false, skipped: "unbound_source" }` with a
+ warning. Pages written this way stay database-only: binding the source
+ later does not materialize them into canonical files, later writes keep
+ them database-only, and sync never deletes or overwrites them. To restore
+ the refusal, run `gbrain config unset persistence.unbound_write`.
+
+The opt-in never applies to a page that came from a canonical file (it has a
+stored source path). An edit there could be lost on the owner's next sync, so
+it keeps refusing with only the bind option. `revert_version` is also judged on
+the version it writes: reverting to a version recorded while the page had a
+canonical file refuses the same way (a version an older gbrain recorded
+without that information counts as file-less).
+
+If the source is bound after a database-only write was accepted but before it
+was published, the write fails with the same reason and nothing is written;
+read the page again and resubmit with a new request ID. If a canonical file
+appears at the path of a database-only page after binding, sync stops for that
+file with `source_changed` and reason `unbound_source`; neither copy is
+overwritten and the database page stays served. Rename or remove the file,
+commit, and sync again.
+
+`gbrain doctor` reports the `unbound_source` check: the number of such pages
+per source. While the source is unbound it is `ok` and prints the bind command;
+after binding it warns, because those pages sit outside the canonical files.
+There is no command yet that turns them into files; to move one, save its
+content under a new slug and delete the database-only page.
+
+## Foreign ownership marker
+
+<a id="foreign-ownership-marker"></a>
+
+When a host claims a source checkout, gbrain writes two private ownership
+markers: `.gbrain-owner.json` inside the checkout and
+`.gbrain-owner-<sha256 of the path>.json` beside it. Both record the brain id
+and the worktree id they belong to. A claim of a checkout whose markers name
+another brain refuses `recovery_required` ("The physical checkout identity
+changed or belongs to another owner"), because removing a live brain's marker
+to claim its files would let two brains write the same checkout.
+
+A marker left behind by a brain that no longer exists (a PGLite brain later
+moved to Postgres with `gbrain migrate`, a `gbrain init` that was
+redone, a database dropped by hand) refuses the same way, and the refusal does
+not say which file or which brain. `gbrain doctor` reports the
+`foreign_ownership_marker` check for every source checkout and owner binding
+on this host: the marker's path, the brain id it records, and whether this
+brain knows the worktree. The check is read-only and runs only on the brain
+host.
+
+Clearing it is the operator's decision, in this order:
+
+1. Confirm with the user that the recorded brain is retired: it was moved into
+ this database, or it was deleted on purpose. `gbrain doctor --json` on the
+ old brain's home, if it still exists, shows its `brain_id`.
+2. Remove exactly the file doctor names on the brain host. Do not remove a
+ marker of a brain that is still in use; transfer ownership with
+ `gbrain sources writer transfer prepare|accept` instead.
+3. Claim again: `gbrain sources writer claim <source> --path <checkout> --dry-run`,
+ then the printed apply command.
+
+A marker of this brain that other users can read (mode `0644` after a
+recursive `chmod`) is reported by the same check with its mode and the exact
+`chmod 600 '<path>'` that restores it, and every write to that checkout
+refuses [`ownership_record_not_private`](#ownership_record_not_private) until
+then. Do not remove such a marker: it belongs to this brain.
+
+## Secret scan refusals and redaction
+
+GBrain runs one secret scanner in several places. Depending on where a
+credential-shaped value turns up, it blocks a push, leaves an entry out of
+compiled context, skips a relay, or is replaced in output with a
+`<REDACTED:pattern>` token (for example `<REDACTED:url_credentials>`). The
+stored page never changes: redaction applies to what a caller receives, not
+to your files or database.
+
+| Where | What happens | What to do |
+| --- | --- | --- |
+| `gbrain sources push` | Refused with `blocked_secrets`, exit code 5. Nothing is committed; the index is reset to `HEAD` and files on disk are untouched. | Remove a real credential and rotate it. Allowlist only a reviewed false positive (below). |
+| `gbrain bootstrap verify`, `gbrain bootstrap repo` | The secret-scan check fails, or the first push stops before anything is committed or pushed. Each finding shows its file, line, pattern, fingerprint and the version that added the rule. | Same as push. |
+| Compiled context (`gbrain compile-context`) | The entry is left out. One line on stderr names the page, the pattern and the fingerprint, never the value. | Remove the value from the page, or allowlist a reviewed false positive. |
+| Memory relay at compaction | The receipt and relay are skipped for that compaction window only; the checkpoint is kept. A content-free line (`reason: secret_scan_refused`, pattern, fingerprint, hint) goes to `~/.gbrain/integrations/hooks/heartbeat.jsonl`. | Nothing to run; the next window is scanned again. Remove the value from the transcript source if it keeps recurring. |
+| Retrieval output | The value is replaced with `<REDACTED:pattern>`; everything else in the result is unchanged. | Nothing. Read the page on the brain host if you need the value (see what stays raw below). |
+| Page reads | Not redacted. | See [what stays raw by design](#what-stays-raw-by-design). |
+| Configured providers | Not redacted yet. | See [what stays raw by design](#what-stays-raw-by-design). |
+
+An allowlist entry stops pushes and compiled context from refusing a
+finding. It does not turn off retrieval redaction: search and recall still
+replace an allowlisted value.
+
+### Shapes this scanner catches
+
+Vendor key prefixes (OpenAI, Anthropic, Voyage, GitHub, GitLab, Slack, AWS, Google,
+Stripe, SendGrid, Twilio, Supabase, npm, Hugging Face, DigitalOcean, OpenRouter,
+Groq, xAI, Perplexity, Replicate, gbrain tokens), JWTs, `Bearer` tokens, private keys, database URLs carrying a
+password, `http(s)` URLs carrying a password (`url_credentials`) and
+`Authorization: Basic` credentials (`basic_auth`). A private key is caught
+even when a snippet or chunk cut off its `BEGIN` or `END` line: the key body
+lines are redacted along with whichever fence is present.
+
+Search chunks never hold key material. A page whose text contains a private
+key is chunked from a copy in which each key is replaced by
+`<REDACTED:private_key_pem>` (line breaks kept, so positions do not shift),
+and evidence delivery cuts `window`, `section` and `page` text from the same
+copy. A chunk from the middle of a long key, with neither its `BEGIN` nor
+its `END` line, therefore carries the token instead of key lines, and key
+material never reaches the embedding provider. The stored page is unchanged.
+Pages indexed by a gbrain older than v0.60.31.0 that contain a `BEGIN` or
+`END … PRIVATE KEY` line are withheld from search until the upgrade re-chunks them, without
+provider calls; `gbrain doctor` reports them as `credential_projection_pending`
+until then, and `gbrain embed --stale` embeds the new chunks when you choose
+to. Key material with no `BEGIN` or `END` line anywhere on the page, and keys
+inside image OCR text, are not projected.
+
+Retrieval output, transcript import, hooks and the memory relay also run the
+assignment rule (`high_entropy_assignment`): a value of 12 or more characters
+with at least one digit and enough randomness, assigned to a key such as
+`password`, `token`, `secret` or `api_key`. Pushes and compiled context do
+not run that rule, so a plain `DB_PASSWORD=...` line never blocks a push.
+
+Placeholder passwords in URLs are skipped: `<password>`, `${VAR}`, `$VAR`,
+and all-`*` or all-`x` masks. A URL with a user and no password, and paths
+that only contain `@` (`https://registry.example/@scope/pkg`), are not
+credentials.
+
+### When a push is refused
+
+```text
+PUSH BLOCKED — secret scan findings (nothing committed):
+ notes/deploy.md:12 [url_credentials] clone <REDACTED:url_credentials>git.example.com/team/repo.git
+ fingerprint: sha256:<16 hex characters>
+ rule [url_credentials] blocks pushes since gbrain v0.60.31.0
+ allow this finding: printf '\n%s\n' sha256:<16 hex characters> >> '/home/you/brain/.gbrain-scan-allow'
+Remove a real credential from the file (and rotate it) first. Allowlist only a reviewed false positive
+with the "allow this finding" command above (it appends to '/home/you/brain/.gbrain-scan-allow'), then retry:
+ gbrain sources push --path '/home/you/brain'
+Docs: https://github.com/garrytan/gbrain/blob/master/docs/guides/write-refusals.md#secret-scan-refusals-and-redaction
+```
+
+Each finding carries:
+
+- **fingerprint**: `sha256:` plus the first 16 hex characters of the
+ value's hash. It identifies the value without revealing it.
+- **rule ... since**: the gbrain version that added or changed the rule
+ (v0.60.31.0 for `url_credentials`, `basic_auth`, `digitalocean` and
+ private keys whose `BEGIN` or `END` line is missing; v0.60.502.0 for
+ `openrouter`, `groq`, `xai`, `perplexity` and `replicate`). A push that worked before an upgrade and fails after it names
+ the version here.
+- **allow this finding**: the exact command that appends the fingerprint to
+ the `.gbrain-scan-allow` file at the repository root. The path is absolute
+ and quoted, so the command works from any directory.
+- **retry**: the push command to run again, with the same `--path`,
+ `--branch` and `--allow-unverified-remote` you used.
+
+`gbrain sources push --json` returns the same data in `findings[]`, one
+object per finding with `file`, `line`, `pattern`, `redactedPreview`,
+`fingerprint`, `since`, `allowlistPath`, `allowCommand`, `retryCommand`,
+`docs` and, when it applies, `staleAllowlistEntry`. The `reason` field
+stays a one-line summary of at most 140 characters (count, first location,
+pattern), so hook and doctor surfaces show it whole.
+
+### Allowlisting a reviewed false positive
+
+First decide whether the value is a real credential. If it is, remove it
+from the file, rotate it with the provider, and push again; allowlisting a
+real credential publishes it.
+
+If it is not (a sample value in documentation, a test fixture), run the
+"allow this finding" command from the refusal, review the change to
+`.gbrain-scan-allow`, then run the retry command. The file holds one entry
+per line: a fingerprint (`sha256:` and at least 16 hex characters) or a path
+glob (a glob without `/` matches a file name at any depth; one with `/` is
+anchored at the repository root), with `#` comments. Commit the file so
+other machines push the same tree.
+
+Prefer a fingerprint over a glob. A glob skips the scan for every file it
+matches, including credentials added later.
+
+### A stale allowlist entry for a private key
+
+The fingerprint of a private key whose `END` line is missing (a cut-off
+excerpt) covers the key body as well as its `BEGIN` line. gbrain older than
+v0.60.31.0 fingerprinted the `BEGIN` line alone, so an allowlist entry
+written then does not match and the push is refused. The refusal says so and
+gives the replacement:
+
+```text
+ stale allowlist entry: sha256:<old> matched only this key's BEGIN header before gbrain v0.60.31.0; the fingerprint now covers the key body.
+ if the key is a reviewed false positive, replace that line in '/home/you/brain/.gbrain-scan-allow' with: sha256:<new>
+```
+
+Replace the old line only if the key is a reviewed false positive. A cut-off
+key's fingerprint depends on where the text was cut, so an entry for a
+truncated key is not stable: if the excerpt changes, the fingerprint
+changes and the push is refused again. For sample keys in documentation,
+show a placeholder instead of key material.
+
+### Redaction in retrieval output
+
+Every operation that returns retrieved text redacts it before any caller
+sees it: `search`, `query`, evidence delivery, `recall`, `context_pack`,
+`delta`, `entity`, `synthesize`, `think`, takes, timelines, transcripts and
+the other retrieval operations. The same pass applies on the CLI, both MCP
+transports, subagent tools and `gbrain call`.
+
+A safe way to see it, on a scratch brain with a value made up on the spot:
+
+```bash
+export GBRAIN_HOME="$(mktemp -d)"
+gbrain init --pglite --no-embedding
+PW="Gx7$(openssl rand -hex 12)"
+gbrain capture --stdin <<EOF
+Deploy notes for the scratch redaction check.
+clone https://deploy:${PW}@git.example.com/team/repo.git
+staging DB_PASSWORD="${PW}#x"
+EOF
+gbrain search "scratch redaction check" --json | grep chunk_text
+```
+
+Expected (one line, shown wrapped):
+
+```text
+"chunk_text": "# Deploy notes for the scratch redaction check.\n\nDeploy notes for the scratch redaction check.\n
+clone <REDACTED:url_credentials>git.example.com/team/repo.git\nstaging DB_PASSWORD=\"<REDACTED:high_entropy_assignment>\"",
+```
+
+The host and path stay; only the user and password are replaced. IDs and
+slugs are never redacted, so do not put secrets in page slugs.
+
+Remembered facts are the one per-caller difference. The `fact`, `context`
+and `source` fields of `recall`, `context_pack` and `delta` are redacted
+for remote callers and returned raw to the trusted local CLI on the brain
+host, so a credential you asked the brain to remember is readable with
+`gbrain recall` there. Every MCP caller, including stdio MCP, and a thin
+client connected over MCP count as remote. Search results, rendered `text`
+and entity cards are redacted for every caller.
+
+When an agent sees `<REDACTED:pattern>`, the brain holds a value of that
+shape and withheld it. The agent should tell the user that, name the
+pattern, and point to the brain host for the value. It should not retry
+other operations to get around it.
+
+### What stays raw by design
+
+- **Page reads.** `get_page`, `fetch`, `get_chunks`, `get_raw_data` and
+ `get_versions` return the stored text unredacted. They are explicit
+ requests for a page and are governed by page visibility, not redaction.
+ Installed skill files (`get_skill`, `get_skill_asset`, the skill catalog
+ operations) and admin job operations are raw too.
+- **Configured providers.** The embedding provider at import, a hosted
+ reranker, and `synthesize`/`think` generation still receive stored text
+ unredacted, except private keys, which chunks never contain. Redaction covers what callers receive, not what gbrain sends
+ to a model provider you configured.
+- **Your files and database.** Redaction never edits stored content. If a
+ real credential reached the brain, rotate it, then follow
+ ["If a secret reached the brain"](../../SECURITY.md#if-a-secret-reached-the-brain).
+
+## Git-canonical sources
+
+A source with `config.canonical = "git"` (strict, set only by conversion; off for every source by default) commits each
+page file to Git before its database row. Some pages keep no file on purpose: private, alias-private and lineage-private
+pages (`database_only_reason` `private`, `alias_private`, `lineage_private`), pages under a `storage.db_only`
+directory, derive-phase pages that never recorded a file, paths the checkout's Git ignores (`git_ignored`), detached
+pages and origin twins. A write to one of them publishes database-only, with no commit and no Git effect. A page turning
+private is published as a door commit that removes its file, and its recorded path is cleared in the same publication.
+Earlier commits keep whatever was pushed before the change; gbrain never rewrites history.
+
+| Code | What happened | What to do |
+|---|---|---|
+| <a id="git_home_required"></a>`git_home_required` | The write would store content in the database with no file in Git and is in no declared class (`no_file_form`), a publication would commit a file for a declared page (`declared_target`), or a writer with no file form yet wrote to the source (`facts_lane`). Nothing was written. | Ask the user which git home to configure: write the page to a path Git tracks, declare its directory under `storage.db_only` in `gbrain.yml`, or mark it `visibility: private`. `gbrain sources git-gap <source> --json` shows every page's class. Submit again with a new request ID. |
+| <a id="git_private_commit_refused"></a>`git_private_commit_refused` | A publication would have committed the file bytes of a private, alias-private or lineage-private page. Nothing was written and `HEAD` is unchanged. A grouped publication refuses as a whole. | The page stays database-only. Write it with `put_page`, which publishes a private page without a file, or remove `visibility: private` if it belongs in Git. |
+| <a id="git_protocol_required"></a>`git_protocol_required` | A database trigger refused a row on a strict source because the writing process does not declare the git-canonical protocol: an older gbrain, or `gbrain.write_sources` set by hand. Nothing was written. | Upgrade (`gbrain upgrade`) or stop every gbrain process that shares the database, then retry with a new request ID. |
+| <a id="git_lfs_not_enabled"></a>`git_lfs_not_enabled` | The file falls under a Git LFS rule in `.gitattributes`, and either `storage.git_lfs` is off (`opt_in_off`, the default) or the checkout does not configure the LFS filter or git-lfs does not run (`checkout_unconfigured`). Nothing was written. | Ask the user. To store it with LFS: `git lfs install --local` in the checkout, then `gbrain config set storage.git_lfs true`. Otherwise narrow the `.gitattributes` rule. With the key on and LFS configured, the door commits the LFS pointer and the object goes to the checkout's LFS store; a publication that rolls back can leave an unreferenced object there, which is harmless. |
+
+## Member access refusals
+
+Per-member read access (members, groups and frontmatter `readable_by`) lives in the database, so these refusals are the
+same on a repo-less brain and on a git-backed one.
+
+| Code | What happened | What to do |
+|---|---|---|
+| <a id="access_member_invalid"></a>`access_member_invalid` | A member or group id given to `gbrain access`, to `--member` on `gbrain auth create`, `rescope` or `register-client`, or to a local `--as <member>` is ill-formed (`ill_formed`) or names no usable member (`unknown`, `disabled`, `removed`, `unknown_group`), or `member add` named an existing member (`exists`). Nothing was read or changed: an unknown `--as` is refused before the command runs instead of reading as unbound. | Check the id with `gbrain access member list --all`; add the member with `gbrain access member add <id>` or enable it with `gbrain access member enable <id>`. Ids are 1-64 characters: lower-case letters, digits, `.`, `_` or `-`. |
+| <a id="access_member_id_retired"></a>`access_member_id_retired` | `gbrain access member add` or `enable` named an id that `gbrain access member rm --yes` removed. Member ids are never reused, because pages and audit history may still name the removed id. Nothing was created. | Choose a new member id. `gbrain access member disable` is the reversible way to pause a member. |
+| <a id="access_member_disabled"></a>`access_member_disabled` | The access token or OAuth client is bound to a member who is disabled, removed or missing, so it was refused at verification (HTTP 401, `invalid_token` with this code in the description). A credential bound to a member reads as that member, so it is refused rather than silently treated as unbound. | Ask the brain operator to run `gbrain access member enable <id>`, or to rebind the credential with `gbrain auth rescope --token <name> --member <id>` (`--member none` unbinds it; an unbound credential sees no page that names readers). |
+| <a id="access_rule_invalid"></a>`access_rule_invalid` | `gbrain access rule add` was given a rule whose prefix is not a literal lower-case slug folder ending in `/` (or holds `..` or `*`), whose readers are not member ids or `group:<id>`, or whose prefix another rule already covers; nothing was written. Prefixes match slugs literally, so a pattern or typo would restrict the wrong pages. | Write the prefix as a folder such as `partners/alice-example/` and the readers as `alice-example,group:team-a`; to change who reads a folder that already has a rule, pass that rule's `--id`. |
+| <a id="access_policy_invalid"></a>`access_policy_invalid` | A source's committed `.gbrain/access.yml` (or a file given to `gbrain access rule import`) does not validate. The last applied rules stay in force and every prefix the file names reads as nobody for remote callers (the whole source when the file does not parse), so a typo never opens a folder. | `gbrain access rule list --source <id>` shows each problem with its line. Fix the file, commit it with `gbrain git commit-push`, and run `gbrain sync --source <id> --no-pull`. |
+| <a id="access_policy_pending"></a>`access_policy_pending` | A narrowing change to a source's folder rules is still being stamped onto its pages, so pages under the folders it touches read as nobody for remote callers until it finishes (other folders keep the last applied rules). Remote reads carry this as a notice: an empty answer there is not proof of no notes. | Wait and retry. If it stays pending the apply was interrupted: on the brain host run `gbrain access resume --source <id>` (database store) or `gbrain sync --source <id> --no-pull` (git store); `gbrain access rule status --source <id>` shows the pending folders. |
+
+## Shared-agent refusals
+
+A shared agent's harness names the audience a request serves in the `X-Gbrain-On-Behalf-Of` header or request-level
+`_meta.on_behalf_of`. These refusals come before any read, and none reveals page content. `may_act_for` and members
+live in the database, so they are the same on a repo-less brain.
+
+| Code | What happened | What to do |
+|---|---|---|
+| <a id="on_behalf_of_invalid_audience"></a>`on_behalf_of_invalid_audience` | The audience is empty, holds more than 50 entries, holds an entry that is not a member id, `group:<id>` or `guest`, or the header and `_meta.on_behalf_of` name different audiences (`_meta.on_behalf_of` must be a list of strings). Nothing was read. | Fix the harness code that sets it: 1-50 entries, the same in both channels when both are sent. Name a `group:<id>` for a channel larger than 50 people. |
+| <a id="on_behalf_of_unknown_member"></a>`on_behalf_of_unknown_member` | The audience names a member who is disabled, removed or was never added, or a group that does not exist. It is refused rather than read as a guest. Nothing was read. | Name enabled members and existing groups only (`gbrain access member list --all`, `gbrain access group list`); a person who is not a member joins the audience as `guest`. |
+| <a id="on_behalf_of_not_permitted"></a>`on_behalf_of_not_permitted` | The credential's `may_act_for` (for a stdio server, config `mcp.stdio_may_act_for`) does not list every audience entry. The message names the credential and the entries it may not act for. Nothing was read. | The brain operator decides: `fix` carries `gbrain auth rescope --token <name> --may-act-for <list>` (or `--client <id>`, or `gbrain config set mcp.stdio_may_act_for <list>`) with the full list to approve. The agent never runs it; until then, call without the audience. |
+| <a id="on_behalf_of_in_arguments"></a>`on_behalf_of_in_arguments` | A tool call carried `on_behalf_of` in its arguments (top level or an arguments-level `_meta`), where conversation text could set it. Nothing was read. | Remove it from the arguments. Harness code sends the audience as the header or request-level `_meta.on_behalf_of`; a stdio client that cannot set request-level `_meta` uses a credential bound to one member or config `mcp.stdio_member`. |
+
+## Attested-actor refusals
+
+A trusted system (QM) names the person a call serves in the `x-qm-actor` header, as an opaque canonical id that the
+brain operator links to a member (`gbrain access member link <member> --qm <id>`). The credential must hold the attest
+right (`gbrain auth rescope --client <id> --attest-actor qm`). These refusals come before any read or write, none
+reveals page content, and each carries its code in `structuredContent.error.code` as well as the JSON text block.
+Links and the right live in the database, so they are the same on a repo-less brain.
+
+| Code | What happened | What to do |
+|---|---|---|
+| <a id="actor_not_attested"></a>`actor_not_attested` | The call named a person in a way gbrain does not honour. `reason` says which: `no_attest_right` (the credential holds no attest right, or the token of an attest client was issued before the upgrade or by another grant: the message then says to take a new client-credentials token), `op_not_attested` (the operation is not in the credential's attested operations, or is not attestable yet: `list_write_conflicts`, `capture`, `extract_facts` and `takes_add|update|resolve|supersede`; also when a queued write or agent job tool call runs after its operation was removed from the list), `argument_mismatch` (the `acting_user` argument differs from the header), `argument_without_attestation` (`acting_user` came without an attested header), `invalid_actor_id` (the header or argument is not 1-256 visible ASCII characters), `actor_required` (`memory_write` named no attested person) or `audience_not_supported` (the request carries `x-qm-audience`, QM's channel audience, which is refused on every call until wave 2). Nothing was read or written. | `no_attest_right` and `op_not_attested` are the brain operator's call: `fix` carries `gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]`. The other five are fixed in the calling harness: send the canonical id unchanged in the header from the attest credential, the same value or nothing in `acting_user`, and no `x-qm-audience`. |
+| <a id="actor_unlinked"></a>`actor_unlinked` | The id is not linked to an enabled member: never linked, unlinked, or the member is disabled or removed. Ids compare exactly, with no case folding. Nothing was read or written. A queued write or agent job made for the person is refused the same way when its link is gone or now names another member. `memory_recall` answers it as an empty success instead (`structuredContent: {facts: [], truncated: false, code: "actor_unlinked"}`), so a person not yet linked reads nothing. | The brain operator links it: `gbrain access member link <member> --qm <id>` (or `gbrain access member enable <member>`). |
+
+## Related
+
+- [Concurrent writes and durable receipts](concurrent-writes.md) — receipt states, retries, capacity limits
+- [Repair residual damage](repair.md) — `gbrain repair` for history, visibility and safe-chunk damage
+- [Multi-source brains](multi-source-brains.md) — sources, slug-root mode and write-through
+- [Topologies](../architecture/topologies.md) — the writer administration procedure behind self-transfer