Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: ingest_capture and company-brain private holds in write refusals, error registry, key files, behavior changes and CHANGELOG (#7880)

garrytane7a51dd83c0e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 457d9a3a75..2df73962ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,21 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**A capture that asks for `visibility: private` in a spelling page privacy does not read is refused on every brain, never stored world-readable (#7880).**
+
+On a brain without managed persistence, the `ingest_capture` job behind the webhook `POST /ingest` route and the ingestion daemon wrote its content straight to the database. Its content screen did not check how a private request was spelled, so an event whose frontmatter said `Visibility: private`, `visibility: Private`, a block scalar, a list, a flow mapping or a merge key was stored as a world-readable page. A managed brain already refused the same event through `put_page`. Now both refuse it with `visibility_not_applied` and the same message, store nothing, and the worker dead-letters the job on its first attempt with the refusal on its result. A legacy (unmanaged) company-brain connect or sync had the same gap for an approved repository file: it is held as `visibility_noncanonical` instead. The GitHub and Google connectors now hold such a file on a database-only source as they already did with a checkout. `visibility: private` on its own lowercase line keeps working everywhere, and pages stored before this release are not changed.
+
+### Itemized changes
+
+- `src/core/import-file.ts`: `importFromContent` takes `holdNoncanonicalPrivate`, passed to `screenImportContent`, so a caller that imports external content refuses `visibility_noncanonical` before anything is stored.
+- `src/core/minions/handlers/ingest-capture.ts`, `src/core/persistence/visibility-request.ts`: the unmanaged capture opts in and turns the hold into put_page's `visibility_not_applied` refusal (`privateRequestRefusal`), which the worker treats as terminal.
+- `src/core/company-brain/profile.ts`, `src/core/github-source.ts`, `src/core/google/sweep-shared.ts`: the same opt-in for company-brain imports and the connectors' database-only imports.
+- `src/core/error-registry.ts`, `src/core/behavior-change-notice.ts`, `docs/guides/write-refusals.md`: name `ingest_capture` and the new holds.
+- `test/sync-blobs-pinned-order.test.ts`: its counting `git` shim runs the real `git` under the PATH it was created with. On a machine whose `git` is a wrapper that finds the next `git` on PATH (a shared-tree git guard), the shim and the wrapper ran each other until the 60 s test deadline. A second case runs the same reads through such a wrapper.
+- Tests, on PGLite and Postgres with a source folder that has no Git checkout: `test/ingest-capture-private-hold-7880.test.ts`, `test/company-brain-private-hold-7880.test.ts`.
+
## [0.60.483.0] - 2026-10-28
**Captured sessions can no longer be pinned to a fallback source, and work queued or retried from before session routing re-checks the source before it writes.**
diff --git a/docs/architecture/key-files/files-and-sync-2.md b/docs/architecture/key-files/files-and-sync-2.md
index 1618d63662..303b513aba 100644
--- a/docs/architecture/key-files/files-and-sync-2.md
+++ b/docs/architecture/key-files/files-and-sync-2.md
@@ -3,7 +3,7 @@
[Subsystem index](../KEY_FILES.md). Read only the entries relevant to your change.
Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
-- `src/core/persistence/visibility-request.ts` — the private-request guard. `readPrivateRequest(content, parse)` reads whether content asks for `visibility: private`: a frontmatter line in any case, or the parse reading a visibility key of any case as private (block scalars, lists, flow mappings and merge keys count). Page writes (`put_page`, `edit_page`, `capture`; `privateRequestGuarded`) refuse a request the stored frontmatter would not keep as exactly `visibility: private` (`assertPrivateRequestKept`, `visibility_not_applied`). File ingestion holds the same case as `visibility_noncanonical` (`noncanonicalPrivateHold`): classic sync and legacy `gbrain import` through `importFromFile` and `screenLegacyFile`, managed sync and import through `screenImportContent`'s `holdNoncanonicalPrivate`, streamed large files unless they are a page write, with or without a Git checkout. Doctor `git_held_files` counts those holds and the live stored pages `noncanonicalPrivateRequest('', frontmatter)` reads as asking for private (`details.visibility_noncanonical`); nothing rewrites them. Derived writers never refuse. Tests: `test/put-visibility-private-7841.test.ts`, `test/visibility-noncanonical-hold-7848.test.ts` (Postgres: `test/e2e/visibility-noncanonical-hold-7848-postgres.test.ts`).
+- `src/core/persistence/visibility-request.ts` — the private-request guard. `readPrivateRequest(content, parse)` reads whether content asks for `visibility: private`: a frontmatter line in any case, or the parse reading a visibility key of any case as private (block scalars, lists, flow mappings and merge keys count). Page writes (`put_page`, `edit_page`, `capture`; `privateRequestGuarded`) refuse a request the stored frontmatter would not keep as exactly `visibility: private` (`assertPrivateRequestKept`, `visibility_not_applied`); an unmanaged `ingest_capture` job takes the same refusal (`privateRequestRefusal`) after `importFromContent`'s screen holds the content (`holdNoncanonicalPrivate`), and dead-letters without a retry (#7880). File ingestion holds the same case as `visibility_noncanonical` (`noncanonicalPrivateHold`): classic sync and legacy `gbrain import` through `importFromFile` and `screenLegacyFile`, managed sync and import through `screenImportContent`'s `holdNoncanonicalPrivate`, and through `importFromContent`'s opt-in of the same name: `ingest_capture`, company-brain imports (`importCompanyBrainFile`) and the GitHub and Google connectors' database-only imports (#7880), streamed large files unless they are a page write, with or without a Git checkout. Doctor `git_held_files` counts those holds and the live stored pages `noncanonicalPrivateRequest('', frontmatter)` reads as asking for private (`details.visibility_noncanonical`); nothing rewrites them. Derived writers never refuse. Tests: `test/put-visibility-private-7841.test.ts`, `test/visibility-noncanonical-hold-7848.test.ts`, `test/ingest-capture-private-hold-7880.test.ts`, `test/company-brain-private-hold-7880.test.ts` (Postgres: the matching `test/e2e/*-postgres.test.ts` wrappers).
- `src/core/sync-embed-backfill.ts` — Sync command’s engine-aware embedding-delivery seam. It derives separate worker-backed deferral and multi-source fan-out eligibility, keeps automatic-submission policy distinct from capability, invokes the shared cost gate for `--all` and single-source runs, propagates intrinsic large-sync deferral into final delivery outcomes, resolves backfill results through the centralized submitter, formats one truthful human status, and builds the single-source JSON envelope. `syncProducedEmbeddableContent` is the one content gate every automatic submit site (`sync --all`, single-source autodefer, the jobs `sync` handler) applies on top of status: a sweep-only or delete-only run reports `synced` but wrote no chunks, and minting a backfill for it would only arm the per-source cooldown against the next real import (the handler reports `embed_skip_reason: 'no_new_content'`). Keeping these pieces together prevents cost-gate, queue, human, and machine surfaces from drifting while the size-ratcheted `src/commands/sync.ts` façade stays at its committed ceiling.
- `src/core/sync-failure-ledger.ts` — the bounded auto-skip sync failure ledger. A LEAF module (imports only fs/path/crypto/config) so `sync.ts` can re-export it without a circular dependency. State lives in `~/.gbrain/sync-failures.jsonl`, one JSON object per line, keyed by `(source_id, path)` with a per-key `attempts` count and a 3-state machine: `open` (fresh/blocking) → `auto_skipped` (chronic, still doctor-visible) or `acknowledged` (human resolved via `gbrain sync --skip-failed` from either unresolved state). `classifyErrorCode(errorMsg)` regex classifier with 23 named codes (`RENAME_RECONCILE`, `SLUG_MISMATCH`, `DB_DUPLICATE_KEY`, `STATEMENT_TIMEOUT`, `YAML_PARSE`, `YAML_DUPLICATE_KEY`, `MISSING_OPEN`, `MISSING_CLOSE`, `EMPTY_FRONTMATTER`, `NULL_BYTES`, `NESTED_QUOTES`, `INVALID_UTF8`, `FILE_TOO_LARGE`, `SYMLINK_NOT_ALLOWED`, `TAKES_TABLE_MALFORMED`, `TAKES_HOLDER_INVALID`, `EMBEDDING_NO_CREDS`, `EMBEDDING_NO_TOUCHPOINT`, `EMBEDDING_TIMEOUT`, `EMBEDDING_RATE_LIMIT`, `EMBEDDING_QUOTA`, `EMBEDDING_OVERSIZE`, `PAGE_JUNK_PATTERN`) plus `UNKNOWN` (the default fallthrough); `summarizeFailuresByCode(failures)` returns sorted `[{code, count}]`; `MISSING_OPEN`/`EMPTY_FRONTMATTER` regexes match the `markdown.ts` validator strings; `MISSING_CLOSE`'s regex is stale against current `markdown.ts` output — it matches the no-heading-hint case (`No closing --- delimiter found`) but not the heading-hint case (`No closing --- before heading at line N`), which falls through to `UNKNOWN`. `FILE_TOO_LARGE` covers `import-file.ts:395, 1236, 1436` (markdown/text, plain-file, and code-file import paths), `SYMLINK_NOT_ALLOWED` covers `:1231, 2038` (file and image import paths). `EMBEDDING_INFRA_CODES` is the subset (`EMBEDDING_TIMEOUT`/`EMBEDDING_RATE_LIMIT`/`EMBEDDING_QUOTA`) that means the embedding PROVIDER is unhealthy rather than the file being poison — `isEmbeddingInfraCode(code)` is consulted inside `decideGateAction`'s chronic-eligibility loop so these three are never counted toward auto-skip (treated as fresh, forcing `block` instead of `advance_then_autoskip`); an explicit `--skip-failed` still advances past them like any other failure, since that check runs before the loop. All mutations run under `withLedgerLock` (cross-process file lock) with an atomic rename write. The auto-skip threshold resolves via `resolveAutoSkipThreshold()` from `GBRAIN_SYNC_AUTOSKIP_AFTER` (default `DEFAULT_AUTOSKIP_AFTER = 3`; `0` disables the valve = pure fail-closed). Two pure decision functions are the unit-test surface: `decideGateAction({fileFailures, sentinels, attemptsByPath, threshold, skipFailed})` returns `hard_block | block | advance | advance_then_autoskip` (sentinels like `<head>` ALWAYS hard-block, even with `--skip-failed`, so a history rewrite can't auto-skip; any FRESH failure with `attempts < threshold` blocks fail-closed; only when ALL failures are chronic does it `advance_then_autoskip`), and `decideSyncFailureSeverity({entries, nowMs, failHours})` returns the `sync_failures` doctor status (`ok` when zero unresolved; `fail` when ≥10 OPEN-blocking or the oldest OPEN failure's `ts` (last attempt, NOT `first_seen`) is older than `failHours` — a failure retried inside that window keeps refreshing `ts` and never trips this leg even if `first_seen` is much older; otherwise `warn` — `auto_skipped`-only rows stay WARN-visible regardless of count because the bookmark already advanced). `applySyncFailureGate(input)` is the one orchestrator BOTH sync paths (incremental + full/`runImport`) call: it records/clears ledger rows, runs `decideGateAction`, then executes effects in the crash-safe order (advance the bookmark FIRST via the injected `advance()` callback, THEN auto-skip the chronic set) so a crash can never mark a file skipped while leaving sync wedged. `isSkippablePath` rejects `<…>` sentinels. Pinned by `test/sync-failure-ledger.serial.test.ts` + `test/sync-failures.test.ts`. GBRA-130 A-18: the module imports `BILLING_MESSAGE_RE`/`RATE_MESSAGE_RE` from the import-free `ai/errors.ts` (still a leaf). `classifyErrorCode(msg, path?)` never reads path text as a provider error: errno-led messages map to `PERMISSION_DENIED` (EACCES/EPERM) or `FILE_UNREADABLE` (ENOENT and other file errnos), and the infra regexes run on the message with the embed envelope, the path and its tokens stripped, so `billing/q3.md` or `http-429.md` no longer read as `EMBEDDING_QUOTA`/`EMBEDDING_RATE_LIMIT`. `syncFailureCode(error, path)` takes the structured errno first (the import paths pass `SyncFailedFile.code`). `SyncGateInput` gains `code`, `imported` and `systemic`: a run where files imported records `infra_isolated_runs` on an open infra row, and `decideGateAction` treats an infra row with `infra_isolated_runs >= threshold` as chronic, auto-skipped with code `EMBEDDING_INFRA_ISOLATED`; a run where nothing imported never counts toward it. A systemic run (the `sync.import_files` ItemRun breaker, most files failing) adds no attempt to open rows, starts new rows at 1, blocks, and `finalize.ts` prints a blocked message naming `--skip-failed`. Pinned by `test/pathological/a18-ledger-path-text.test.ts` (both engines).
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 787acb31c2..ba0b140410 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -4653,7 +4653,7 @@ More: [docs/ENGINES.md#vector-index-prewarm](../../docs/ENGINES.md#vector-index-
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A file asks for visibility: private in a spelling page privacy does not read, so sync or import held it instead of storing it world-readable. | Page privacy reads only the exact lowercase key and value visibility: private. A file that spells it another way (Visibility: private, visibility: Private, a block scalar, a list, a flow mapping or a merge key) would be stored as a world page while its author believes it is private (#7848); put_page, edit_page and capture refuse the same request as visibility_not_applied. | Write visibility: private on its own frontmatter line (lowercase key and value), then commit and sync, or import the file again. | agent | `repeat the read that failed` | 1 | no |
+| A file asks for visibility: private in a spelling page privacy does not read, so sync or import held it instead of storing it world-readable. | Page privacy reads only the exact lowercase key and value visibility: private. A file that spells it another way (Visibility: private, visibility: Private, a block scalar, a list, a flow mapping or a merge key) would be stored as a world page while its author believes it is private (#7848); put_page, edit_page, capture and ingest_capture refuse the same request as visibility_not_applied. | Write visibility: private on its own frontmatter line (lowercase key and value), then commit and sync, or import the file again. | agent | `repeat the read that failed` | 1 | no |
More: [docs/guides/write-refusals.md#visibility_noncanonical](../../docs/guides/write-refusals.md#visibility_noncanonical)
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 780984b9e9..a6ad6600c3 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -132,7 +132,7 @@ 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). `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)). |
+| <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 the same way on every brain and dead-letters without a retry, its job result carrying the refusal (#7880). `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). |
@@ -230,7 +230,7 @@ with each file and fix the ones that need no guessing."*
| <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="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. `put_page`, `edit_page` and `capture` 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="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). `put_page`, `edit_page`, `capture` and `ingest_capture` 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. |
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 4f446553ca..12926f5db3 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1335,6 +1335,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.483.0', id: 'corpus_realpath_7871', text: 'Dream synthesis and extract_atoms recognize a session-corpus file through symlinks (a meeting folder or corpus path that points into the corpus, a linked `sourced/` folder), so such a file is routed to its session\'s source instead of being read as an ordinary transcript; a listed file whose real path cannot be read is held as `corpus_path_unresolvable` (#7871).' },
// #7848 non-canonical private requests on file ingestion. `since` is stamped at the merge slot.
{ since: '0.60.483.0', id: 'visibility_noncanonical_hold_7848', text: 'Git sync (classic and managed) and `gbrain import` (with or without a Git checkout) hold a file whose frontmatter asks for `visibility: private` in a spelling page privacy does not read (`Visibility: private`, `visibility: Private`, a block scalar, a list, a flow mapping or a merge key) as `visibility_noncanonical` instead of storing a world-readable page; the rest of the source syncs and an existing page keeps its last imported version. Write `visibility: private` on its own frontmatter line (lowercase) and commit, or import the file again. Doctor `git_held_files` counts the held files and the stored pages that already ask for private this way (`details.visibility_noncanonical`); nothing rewrites them. On a brain without managed persistence, `gbrain put --file` and `gbrain capture --file` of a page over the single-string ceiling refuse such a request with `visibility_not_applied`, as a smaller write does.' },
+ // #7880 ingest_capture and company-brain imports on a brain without managed persistence. `since` is stamped at the merge slot.
+ { since: 'TBD', id: 'ingest_capture_private_hold_7880', text: 'On a brain without managed persistence, an `ingest_capture` job (the webhook `POST /ingest` route and the ingestion daemon) whose content asks for `visibility: private` in a spelling page privacy does not read (`Visibility: private`, `visibility: Private`, a block scalar, a list, a flow mapping or a merge key) is refused `visibility_not_applied` and dead-letters on its first attempt instead of storing a world-readable page, as a managed brain already refused it. A legacy company-brain connect or sync holds such a file as `visibility_noncanonical` instead of importing it world-readable, and the GitHub and Google connectors hold it on a database-only source as they do with a checkout. Write `visibility: private` on its own frontmatter line (lowercase) and send it again. Nothing rewrites pages already stored (#7880).' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index da734ae67b..624e962c17 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -779,7 +779,7 @@ export const CODES = {
vector_prewarm_unsupported_engine: { class: 'caller', summary: "`gbrain embeddings prewarm` was refused because the brain is PGLite; nothing was read.", why: "Prewarm fills a Postgres server's shared_buffers so later processes find index pages cached; PGLite runs inside each gbrain process, with no server cache that outlives it.", docs: 'docs/ENGINES.md#vector-index-prewarm', suggestion: 'Nothing to do on PGLite.' },
vector_prewarm_wont_fit: { class: 'host_only', actor: 'host_admin', summary: "`gbrain embeddings prewarm` was refused before reading anything because the brain's HNSW indexes are larger than half of shared_buffers.", why: "Prewarm loads the indexes into shared_buffers, the cache Postgres sizes and keeps; past half of it the prewarm would evict heap and keyword-index pages other reads need, so the next searches would pay first-touch reads on those instead. effective_cache_size does not decide: it is a planner hint, not memory the server holds.", docs: 'docs/ENGINES.md#vector-index-prewarm', suggestion: 'Raise shared_buffers on the database host to at least twice the index size the message names and restart Postgres, or leave the indexes cold; read the fit with gbrain embeddings prewarm --dry-run --json.', fix: { argv: ['gbrain', 'embeddings', 'prewarm', '--dry-run', '--json'], consent: [], actor: 'agent', why: 'Read-only: prints the index sizes, shared_buffers, effective_cache_size and the fit, and reads no relation page.', requires_exclusive: false } },
verification_failed: { class: 'server', summary: "Source content or relationships changed during verification." },
- visibility_noncanonical: { class: 'caller', summary: "A file asks for visibility: private in a spelling page privacy does not read, so sync or import held it instead of storing it world-readable.", why: "Page privacy reads only the exact lowercase key and value visibility: private. A file that spells it another way (Visibility: private, visibility: Private, a block scalar, a list, a flow mapping or a merge key) would be stored as a world page while its author believes it is private (#7848); put_page, edit_page and capture refuse the same request as visibility_not_applied.", docs: 'docs/guides/write-refusals.md#visibility_noncanonical', suggestion: 'Write visibility: private on its own frontmatter line (lowercase key and value), then commit and sync, or import the file again.' },
+ visibility_noncanonical: { class: 'caller', summary: "A file asks for visibility: private in a spelling page privacy does not read, so sync or import held it instead of storing it world-readable.", why: "Page privacy reads only the exact lowercase key and value visibility: private. A file that spells it another way (Visibility: private, visibility: Private, a block scalar, a list, a flow mapping or a merge key) would be stored as a world page while its author believes it is private (#7848); put_page, edit_page, capture and ingest_capture refuse the same request as visibility_not_applied.", docs: 'docs/guides/write-refusals.md#visibility_noncanonical', suggestion: 'Write visibility: private on its own frontmatter line (lowercase key and value), then commit and sync, or import the file again.' },
visibility_not_applied: { class: 'caller', reasons: ['noncanonical_value', 'not_kept'], summary: "A page write asked for visibility: private, but the page would have stayed world-readable, so nothing was written.", why: "A write that reports success while the page stays world-readable leaves the caller believing it is hidden. Page privacy reads only the exact lowercase key and value visibility: private (#7841). When the frontmatter is unreadable or ambiguous, the write is refused invalid_frontmatter instead.", docs: 'docs/guides/write-refusals.md#visibility_not_applied', suggestion: 'Read the page and its revision, write visibility: private on its own frontmatter line (lowercase key and value), then submit again with a new request_id.', fix: { argv: ['gbrain', 'get', '--source', '{source_id}', '--', '{slug}'], consent: [], actor: 'agent', why: 'Read-only: shows the page as it is now, with its revision.', requires_exclusive: false } },
withdrawal_capacity: { class: 'caller', summary: "Withdrawal capacity." },
withdrawal_mirror_failed: { class: 'unavailable', summary: "A page's Git or embedding work is withheld because its withdrawal mirror failed before rewriting the page's file; the file may still hold the withdrawn text.", why: "A withdrawal's Git and embedding effects touch only the pages whose file its mirror recorded rewriting (GBRA-130 A-12); Git never commits a page the mirror passed without rewriting its file. Retrying the request's effects reruns the mirror for this page; once the mirror commits, the withheld work is re-armed automatically.", suggestion: 'Read the parked effects with gbrain doctor --only parked_effects, fix the cause the mirror recorded, then preview gbrain sources writer retry-effects <source> --request-id <id> --dry-run and run it without --dry-run.' },