Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(repair): url-clone-fences restores a held file from HEAD without importing it, so the clone can pull the upstream fix (#7897)
garrytanb5067b715996
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3ca3b94c41..014b7e4a1f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,11 +14,11 @@ identifiers and attribution are available in the pre-removal Git revision**Three more writers refuse a `visibility: private` request page privacy does not read instead of storing a world-readable page (#7897).**-`gbrain repair url-clone-fences` restored a clone file by importing HEAD's bytes as its page without checking how a private request was spelled, and ignored the import's result. On a brain without managed persistence, a HEAD whose frontmatter said `Visibility: private` (or another spelling sync holds as `visibility_noncanonical`) was stored world-readable and reported `restored`. The preview now lists such a file under the hold's code and leaves it alone, rows and page included, and an approval saved before this release applies as `held`. `gbrain brainstorm` / `gbrain lsd` `--save` on an unmanaged brain had the same gap for content passed to the exported save function; the CLI's own frontmatter never carries a private request, and it now refuses one with put_page's `visibility_not_applied` and exits 1. `gbrain sources reconcile` protected only the lowercase `visibility` key from the file side, so a file adding `Visibility: private` merged in (as an additive field under `--auto-additive`) and published world-readable; it now refuses `visibility_not_applied` at preview and apply. `visibility: private` on its own lowercase line keeps working everywhere, and pages stored before this release are not changed.+`gbrain repair url-clone-fences` restored a clone file by importing HEAD's bytes as its page without checking how a private request was spelled, and ignored the import's result. On a brain without managed persistence, a HEAD whose frontmatter said `Visibility: private` (or another spelling sync holds as `visibility_noncanonical`) was stored world-readable and reported `restored`. The preview now lists such a file under the hold's code. Apply still keeps its fence rows database-only and restores the file from HEAD, so the clone can pull the upstream fix, but it does not import HEAD as the page and reports `held` (an approval saved before this release applies the same way). `gbrain brainstorm` / `gbrain lsd` `--save` on an unmanaged brain had the same gap for content passed to the exported save function; the CLI's own frontmatter never carries a private request, and it now refuses one with put_page's `visibility_not_applied` and exits 1. `gbrain sources reconcile` protected only the lowercase `visibility` key from the file side, so a file adding `Visibility: private` merged in (as an additive field under `--auto-additive`) and published world-readable; it now refuses `visibility_not_applied` at preview and apply. `visibility: private` on its own lowercase line keeps working everywhere, and pages stored before this release are not changed.### Itemized changes-- `src/core/repair/url-clone-fences.ts`: the preview and the apply screen HEAD's bytes with `holdNoncanonicalPrivate` before any backup or row move; the import opts in too, and a refused import reports `held` with its code instead of `restored`.+- `src/core/repair/url-clone-fences.ts`: the preview and the apply screen HEAD's bytes with `holdNoncanonicalPrivate`, and the import opts in too; a held HEAD still gets its rows kept database-only and its file restored (so the clone's pull is unblocked), skips the import and reports `held` with its code instead of `restored`.- `src/commands/brainstorm.ts`: the unmanaged save opts in, turns the hold into `visibility_not_applied` (`privateRequestRefusal`) and treats any refused import as not saved.- `src/core/persistence/reconcile-prepare.ts`: the merged result imports with `holdNoncanonicalPrivate` and refuses `visibility_not_applied`.- `test/import-private-hold-callers-7897.test.ts`: lists every `importFromContent` / `screenImportContent` call that does not opt in, with why it is held another way or derived from a stored page, and fails on a new unlisted call.diff --git a/docs/architecture/key-files/core-persistence-graduation.md b/docs/architecture/key-files/core-persistence-graduation.mdindex f8399d2897..95981bf038 100644--- a/docs/architecture/key-files/core-persistence-graduation.md+++ b/docs/architecture/key-files/core-persistence-graduation.md@@ -17,6 +17,6 @@ Verified engine graduation, PGLite to Postgres ([operator guide](../../guides/mo- `src/commands/migrate-graduation.ts` — the `gbrain migrate` graduation CLI, routed before connect from `routeEngineFreeSubcommands` in `src/cli.ts` when `routesToGraduation` holds (run-scoped verbs and `--plan` always; a bare `--to postgres|supabase` on a durable PGLite config unless `migrate.graduation` is false or the host is Windows). Without `--yes --expect` it plans and returns the `confirmation_required` payload (effects egress and destructive, what moves and what stays, `plan_hash`, the `--plan` preview; no stdin prompt); `--plan`/`--dry-run` prints the plan; the run reports the receipt, retained copy, target doctor, `gbrain mcp expose` and the MCP restart note. Exit codes 0/1/2/3, 11 for a progressing drain stop (1 when a blocker needs a person), 75 for `graduation_in_progress`, 130 after SIGINT (stops at the next batch boundary). `--json` prints one document; progress goes to stderr per table and batch. Test: `test/migrate-graduation-cli.serial.test.ts`.- `src/commands/doctor/checks/engine-graduation.ts` — `graduationStateCheck`, emitted from the filesystem lane of `local-audits.ts`: `graduation_interrupted` fails when a manifest or marker is non-terminal with no live owner (fix `gbrain migrate --resume`, rollback named) or a stray brain sits at the old path, is `ok` while a live run owns it, exempts the run named by `GBRAIN_GRADUATION_RUN`, and emits nothing on a brain that never graduated. The retained `.graduated-*` copy is reported by `pglite_leftovers` (`src/core/pglite-leftovers-check.ts`), silent while a manifest is non-terminal.- `src/core/repair/missing-tables.ts` — `gbrain repair missing-tables` (#6911), explicit-only and preview-bound (`--apply --expect <hash>`), brain-wide, DDL only. The preview lists the missing rebuildable caches `readMissingTables` reports (`recreate`), plus `user_data_tables` and `other_tables` residuals it never recreates; the hash covers the brain id, `LATEST_VERSION` and the tables. Apply refuses when the brain schema is newer than the client, leaves a table that already exists alone (`already_present`, no DDL), runs `recreateStep` in one transaction per table under the migration statement and lock timeouts (`schemaLockBlockedError` on a lock timeout), maps 42501 to `schema_owner_required` (approval kept) and 23505/42P07 races to `already_present`, and retires the approved set with the last item. Tests: `test/purge-missing-cache-6911.test.ts`, `test/schema-missing-tables.test.ts`.-- `src/core/repair/url-clone-fences.ts` — `gbrain repair url-clone-fences` (#6946, GBRA-130 C-2): explicit-only, preview-bound, destructive consent; unmanaged brains only (a managed brain gets a warning naming `sources mirror-readonly`). The survey lists every tracked file of each owned clone in scope that differs from HEAD (`trackedChanges`) and proves per file (`proveFenceRowsOnly`) that HEAD's fence rows are an unchanged prefix of the working copy's and that re-rendering HEAD with the working fence matches byte for byte (`fence_rows_only`); anything else is listed as `non_fence_edit` / `unparsed_fence` / `staged_change` / `deleted` / `not_in_head` / `unreadable_checkout` and never touched, and so is a file whose HEAD would not import (`headHold`, the import screen with `holdNoncanonicalPrivate`), listed under the hold's code; at apply that check runs before the backup and the row move, the import opts in too, and a held file reports `held` with the code instead of `restored` (#7897). The preview hash binds the approved set (preview-approval, keyed by the command string). The apply, per file under the source filesystem lock and page lock, rechecks both sides (`changed_since_preview`), backs the file up under `~/.gbrain/backups/url-clone-fences/`, clears `row_num`/`source_markdown_slug` on the appended rows in one `maintenanceTransaction` (inserting database-only any row the database lost), imports HEAD's bytes as the page through `importFromContent`, and only then restores the file from HEAD; each step is idempotent. Tests: `test/pathological/c2-url-clone-fences.test.ts`, `test/url-clone-fences-private-hold-7897.test.ts`.+- `src/core/repair/url-clone-fences.ts` — `gbrain repair url-clone-fences` (#6946, GBRA-130 C-2): explicit-only, preview-bound, destructive consent; unmanaged brains only (a managed brain gets a warning naming `sources mirror-readonly`). The survey lists every tracked file of each owned clone in scope that differs from HEAD (`trackedChanges`) and proves per file (`proveFenceRowsOnly`) that HEAD's fence rows are an unchanged prefix of the working copy's and that re-rendering HEAD with the working fence matches byte for byte (`fence_rows_only`); anything else is listed as `non_fence_edit` / `unparsed_fence` / `staged_change` / `deleted` / `not_in_head` / `unreadable_checkout` and never touched; a file whose HEAD would not import (`headHold`, the import screen with `holdNoncanonicalPrivate`) is listed under the hold's code, and at apply its rows still go database-only and the file is restored (so the clone can pull) but HEAD is not imported; the import opts in too, and a held file reports `held` with the code instead of `restored` (#7897). The preview hash binds the approved set (preview-approval, keyed by the command string). The apply, per file under the source filesystem lock and page lock, rechecks both sides (`changed_since_preview`), backs the file up under `~/.gbrain/backups/url-clone-fences/`, clears `row_num`/`source_markdown_slug` on the appended rows in one `maintenanceTransaction` (inserting database-only any row the database lost), imports HEAD's bytes as the page through `importFromContent`, and only then restores the file from HEAD; each step is idempotent. Tests: `test/pathological/c2-url-clone-fences.test.ts`, `test/url-clone-fences-private-hold-7897.test.ts`.- `src/core/schema-missing-tables.ts` — #6911 expected-table check. `readMissingTables`: at head every graduation-inventory table for the engine, below head only the recreatable caches whose creating migration (`CREATED_BY`) already ran, `skipped` (`client_behind`) when the brain is newer; each missing table carries its inventory class and `loss_kind`. `recreateStep` (own-key lookup, rebuild class only) rebuilds `query_cache` (v055 DDL sized from the live `facts.embedding` shape, then the v056/v090/v091 statements) and `code_traversal_cache` (v059), then on Postgres enables RLS on the recreated table through v275's `protectTables` (a role that does not bypass RLS or own the table leaves it RLS-off and names it on stderr). `test/schema-missing-tables.test.ts` pins each recreated table's columns and indexes to the migrated brain's on both engines and checks that every inventory rebuild table is either in `RECREATABLE_TABLES` or defined by the base schema (so `init --migrate-only` recreates it). Doctor `schema_missing_tables` (`src/commands/doctor/checks/schema-health.ts`) renders it: warn for caches (repair preview fix) and tables without user data, fail for `user_data` tables.- `src/core/persistence/rebuildable-cache.ts` — #6911 purge-side skip: `isRebuildableCache` (inventory class `rebuild`), `relationExists` (`to_regclass` on the connection's search path), and `clearRebuildableCache(tx, table)`, which returns the rows deleted or null when the cache table is absent; the existence check runs first because a 42P01 aborts a Postgres transaction. Callers: page purge (`purge.missing_caches`) and fact purge.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex fb44f90930..2b2a89808e 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -169,7 +169,7 @@ work behind exits 0, so scripts should also check `results[].complete`.| `rename-identity` | `rename_identity_downgrades` | Explicit-only, preview-bound, destructive consent. For an inexact Git rename that sync split into a delete plus an add (#6729): carries the old page's identity (id, version history, timeline, links, facts, aliases) onto the new slug, imports the new file onto it as an edit and retires the provisional page; or, with `--close`, settles the pair and moves nothing. `--slug <new-slug>` (and `--from <old-slug>`) names one pair; `--apply --expect <hash> --yes`. See [rename identity](#rename-identity). | `fact_rows_collide` (a fence row of the old page the new file does not keep with the same claim); `managed_remedy_unavailable` (a carry on a managed source; `--close` is the remedy there); pages changed after the preview (`changed_since_preview`). || `overwritten-edits` | `sync_overwritten_db_edits` | Explicit-only, preview-bound. Restores database edits that an incremental managed sync replaced with a committed file edit and no `file_drift` hold (#6712, fixed by #6887). It restores only what the records prove: a database-only revision (its receipt published no file) archived by a managed-sync import that wrote different content, with no later revision holding the edit again. The preview diffs the live page against the edit; `--apply --expect <hash>` reverts each page to that version through a revision-bound, database-only `revert_version` and holds the committed file `file_drift` when it differs. See [overwritten edits](#overwritten-edits). | `unknown_*` findings (no persistence outcome on the writer's receipt, the import's content no longer readable, a segmented version), listed but not restored; pages that moved after the preview (`changed_since_preview`). || `missing-tables` | `schema_missing_tables` | Explicit-only, preview-bound. Recreates, empty, a rebuildable cache table (`query_cache`, `code_traversal_cache`) that the applied migrations created but the brain no longer has, on a brain whose schema version already covers its creating migration, so `apply-migrations` never recreates it (#6911). DDL only (`IF NOT EXISTS`), no journal admission, brain-wide. See [missing tables](#missing-tables). | `user_data_tables`: a missing table that holds user data; this repair never recreates it, so restore its rows from a backup first. `other_tables`: a missing table that holds no user data; `gbrain init --migrate-only` recreates it if the base schema defines it. |-| `url-clone-fences` | none (`gbrain sync --source <id>` stops at the pull with `pull_blocked_local_changes`) | Explicit-only, preview-bound, destructive consent. Clears the `## Facts` fence rows an older gbrain appended to files of a clone it owns (`gbrain sources add --url`), which block every `git pull --ff-only` that touches those files (#6946). The preview proves each changed file differs from HEAD only by appended fence rows; `--apply --expect <hash> --yes` backs each file up, keeps its rows database-only and restores the file from HEAD. Unmanaged brains only. See [URL clone fences](#url-clone-fences). | `non_fence_edit`, `unparsed_fence`, `staged_change`, `deleted`, `not_in_head`, `unreadable_checkout`: a file with any other difference from HEAD, named with why; a file whose HEAD would not import as its page (`visibility_noncanonical` and the other import holds; an approval saved earlier applies as `held`); files that changed after the preview (`changed_since_preview`). |+| `url-clone-fences` | none (`gbrain sync --source <id>` stops at the pull with `pull_blocked_local_changes`) | Explicit-only, preview-bound, destructive consent. Clears the `## Facts` fence rows an older gbrain appended to files of a clone it owns (`gbrain sources add --url`), which block every `git pull --ff-only` that touches those files (#6946). The preview proves each changed file differs from HEAD only by appended fence rows; `--apply --expect <hash> --yes` backs each file up, keeps its rows database-only and restores the file from HEAD. Unmanaged brains only. See [URL clone fences](#url-clone-fences). | `non_fence_edit`, `unparsed_fence`, `staged_change`, `deleted`, `not_in_head`, `unreadable_checkout`: a file with any other difference from HEAD, named with why; a file whose HEAD would not import as its page (`visibility_noncanonical` and the other import holds): apply keeps its rows database-only and restores the file so the clone can pull, but does not import HEAD and reports `held`; files that changed after the preview (`changed_since_preview`). || `segmented-mirror` | none (doctor does not read segmented files; run the preview once if the brain ran a version before v0.60.299.0) | Explicit-only, preview-bound, destructive consent. Rewrites the canonical file of a page stored in segments that an older binary's withdrawal mirror passed by (`page_body_segmented`), so the file still holds a row `forget`, `forget_fact` or `purge_fact` removed from the database. The file becomes the page's canonical render (`gbrain export`'s bytes), written by the withdrawal mirror and committed by its Git effect. See [segmented mirror](#segmented-mirror). | `file_database_drift`: the file also differs from the database for another reason; it is listed held and never rewritten. `not_owner_host`: the preview ran off the source's owner host and read none of its files. |Timeline rows that an earlier version of a page produced and its current text@@ -2306,8 +2306,10 @@ named with its class (`non_fence_edit`, `unparsed_fence`, `staged_change`,the edit upstream, or discard it with `git checkout -- <path>`), then previewagain. A file whose HEAD bytes would not import as its page is listed under thehold's code (`visibility_noncanonical` for a `Visibility: private` that page privacy-does not read) and left alone too, rows and page included; an approval saved-before that applies as `held` with the code (#7897). Each restored file is first backed up under+does not read): apply keeps its rows database-only and restores the file from+HEAD so the clone can pull the upstream fix, but does not import HEAD, reports+`held` with the code and leaves the page at its last imported version; sync+holds the file until upstream fixes it (#7897). Each restored file is first backed up under`~/.gbrain/backups/url-clone-fences/`. Its rows stay active and recallable asdatabase-only facts, HEAD's bytes are imported as the page (as sync wouldimport them), and only then is the file restored; each step is idempotent, sodiff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 3ebb536ca2..3126507620 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -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. 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 and leaves the file, its fence rows and the page as they are (#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="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. |diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 16e2a13474..29a2aa936d 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1338,7 +1338,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;// #7880 ingest_capture and company-brain imports on a brain without managed persistence. `since` is stamped at the merge slot.{ since: '0.60.485.0', 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).' },// #7897 the remaining content imports without the private-request hold. `since` is stamped at the merge slot.- { since: 'TBD', id: 'private_hold_sweep_7897', text: 'Three more writers refuse content that 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) instead of storing a world-readable page. `gbrain repair url-clone-fences` lists such a clone file under `visibility_noncanonical` and leaves the file, its fence rows and the page alone; an approval previewed before this release applies as `held`, not `restored`. On a brain without managed persistence, `gbrain brainstorm` / `gbrain lsd` `--save` refuses it `visibility_not_applied` and exits 1, as a managed brain already did, and a save whose import is refused for another reason is reported not saved. `gbrain sources reconcile` refuses a merge that takes a file\'s `Visibility: private` with `visibility_not_applied`. Write `visibility: private` on its own frontmatter line (lowercase) and try again. Nothing rewrites pages already stored (#7897).' },+ { since: 'TBD', id: 'private_hold_sweep_7897', text: 'Three more writers refuse content that 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) instead of storing a world-readable page. `gbrain repair url-clone-fences` lists such a clone file under `visibility_noncanonical`; apply keeps its fence rows database-only and restores the file from HEAD so the clone can pull again, but does not import HEAD as the page and reports `held`, not `restored` (an approval previewed before this release applies the same way). On a brain without managed persistence, `gbrain brainstorm` / `gbrain lsd` `--save` refuses it `visibility_not_applied` and exits 1, as a managed brain already did, and a save whose import is refused for another reason is reported not saved. `gbrain sources reconcile` refuses a merge that takes a file\'s `Visibility: private` with `visibility_not_applied`. Write `visibility: private` on its own frontmatter line (lowercase) and try again. Nothing rewrites pages already stored (#7897).' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/repair/url-clone-fences.ts b/src/core/repair/url-clone-fences.tsindex e62d3104fd..019502940c 100644--- a/src/core/repair/url-clone-fences.ts+++ b/src/core/repair/url-clone-fences.ts@@ -147,13 +147,11 @@ async function survey(engine: BrainEngine, sourceIds: string[]): Promise<{ files}const { slug, page_id } = await pageOf(engine, source.id, path);const hold = headHold(head!, slug);- if (hold) {- listing.push({ item, class: hold.code, detail: `HEAD's bytes would not import as ${slug}, so the file is left as it is: ${hold.message} Fix the file upstream, pull, then preview again: ${preview(source.id)}` });- continue;- }files.push({ source_id: source.id, incarnation: source.incarnation, root, path, slug, page_id, head_sha256: sha256(head!), work_sha256: sha256(work!),rows: proof.added.map(row => row.rowNum), selection: sourceIds });- listing.push({ item, class: 'fence_rows_only', detail: `${proof.added.length} fence row(s) gbrain appended to ${slug}: kept database-only, then the file is restored from HEAD` });+ listing.push(hold+ ? { item, class: hold.code, detail: `${proof.added.length} fence row(s) gbrain appended to ${slug}: kept database-only, then the file is restored from HEAD so the clone can pull again, but HEAD's bytes are not imported as the page: ${hold.message} The page keeps its last imported version and sync holds the file until it is fixed upstream.` }+ : { item, class: 'fence_rows_only', detail: `${proof.added.length} fence row(s) gbrain appended to ${slug}: kept database-only, then the file is restored from HEAD` });}}return { files, listing };@@ -198,15 +196,14 @@ async function restoreFile(engine: BrainEngine, file: ClonedFile, runId: string)if (!proof.ok || sha256(head!) !== file.head_sha256 || sha256(work!) !== file.work_sha256) {return { applied: false, outcome: 'changed_since_preview', detail: { path: file.path } };}- const hold = headHold(head!, file.slug);- if (hold) return { applied: false, outcome: 'held', reason: hold.code, detail: { path: file.path, message: hold.message } };const backup = createFrontmatterBackup(abs, { sourcePath: file.root, backupRoot: gbrainPath('backups', 'url-clone-fences', runId) });const { moved, inserted } = await keepRowsDatabaseOnly(engine, file, proof.added);- const imported = await importFromContent(engine, file.slug, head!, { sourceId: file.source_id, sourcePath: file.path, sourceRoot: file.root, noEmbed: true, holdNoncanonicalPrivate: true });- if (imported.refusal) return { applied: false, outcome: 'held', reason: imported.refusal.code, detail: { path: file.path, message: imported.refusal.message, backup, rows_moved: moved, rows_inserted: inserted } };+ const hold = headHold(head!, file.slug)+ ?? (await importFromContent(engine, file.slug, head!, { sourceId: file.source_id, sourcePath: file.path, sourceRoot: file.root, noEmbed: true, holdNoncanonicalPrivate: true })).refusal;assertSourceFilesystemActive();atomicWriteFileSync(abs, head!);- return { applied: true, outcome: 'restored', detail: { path: file.path, slug: file.slug, backup, rows_moved: moved, rows_inserted: inserted } };+ const detail = { path: file.path, slug: file.slug, backup, rows_moved: moved, rows_inserted: inserted };+ return hold ? { applied: true, outcome: 'held', reason: hold.code, detail: { ...detail, message: hold.message } } : { applied: true, outcome: 'restored', detail };}export const urlCloneFencesRepair: RepairHandler = {diff --git a/test/url-clone-fences-private-hold-7897.test.ts b/test/url-clone-fences-private-hold-7897.test.tsindex f20ff86810..5b93d149ce 100644--- a/test/url-clone-fences-private-hold-7897.test.ts+++ b/test/url-clone-fences-private-hold-7897.test.ts@@ -4,9 +4,10 @@* that asks for `visibility: private` in a spelling page privacy does not read (sync holds it `visibility_noncanonical`)* was imported world-readable on an unmanaged brain and reported `restored`.*- * Protects: the preview lists such a file under the hold's code and offers nothing to apply; an approval saved before- * this release (a preview that listed it `fence_rows_only`) applies as `held` with the code, and the file, its fence- * rows and the page stay as they were. HEAD with `visibility: private` still restores a private page, and a HEAD that+ * Protects: the preview lists such a file under the hold's code, and apply (from that preview, or from an approval saved+ * before this release that listed it `fence_rows_only`) reports `held` with the code: the row is kept database-only and+ * the file is restored from HEAD, so the clone pulls the upstream fix, but HEAD is not imported and the page stays as it+ * was. HEAD with `visibility: private` still restores a private page, and a HEAD that* asks for nothing private still restores. The brain has no repository of its own (no `sync.repo_path`); the repair* applies only to a source that is an owned Git clone, so there is no clone-less arm.*@@ -38,11 +39,11 @@ const person = (extra: string) => `---\ntype: person\ntitle: Alice Example\n${exconst git = (dir: string, args: string[]) => execFileSync('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'commit.gpgsign=false', '-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');-interface Clone { engine: BrainEngine; root: string; file: () => string; head: () => string; page: () => Promise<{ frontmatter: Record<string, unknown>; compiled_truth: string } | null>;+interface Clone { engine: BrainEngine; root: string; upstream: string; file: () => string; head: () => string; page: () => Promise<{ frontmatter: Record<string, unknown>; compiled_truth: string } | null>;rows: () => Promise<Array<number | null>> }/**- * An owned clone whose first sync imported a world page; HEAD then moves to `extra` frontmatter (a local commit) and an+ * An owned clone whose first sync imported a world page; HEAD then moves to `extra` frontmatter (an upstream commit the clone pulled) and an* older gbrain's fence writer appends one row to the working copy, so the file differs from HEAD by fence rows only.*/async function withClone(databaseUrl: string | undefined, extra: string, run: (c: Clone) => Promise<void>): Promise<void> {@@ -68,13 +69,14 @@ async function withClone(databaseUrl: string | undefined, extra: string, run: (cawait engine.executeRaw('INSERT INTO sources (id, name, local_path, config) VALUES ($1, $1, $2, $3::text::jsonb)', [SOURCE, root, JSON.stringify(config)]);const { performSync } = await import('../src/commands/sync.ts');expect((await performSync(engine, { sourceId: SOURCE, repoPath: root, noEmbed: true, noExtract: true })).status).toBe('first_sync');- writeFileSync(join(root, FILE), person(extra));- git(root, ['commit', '-q', '-am', 'head moves']);+ writeFileSync(join(upstream, FILE), person(extra));+ git(upstream, ['commit', '-q', '-am', 'head moves']);+ git(root, ['pull', '-q', '--ff-only']);await engine.executeRaw('UPDATE sources SET config = $1::text::jsonb WHERE id = $2', [JSON.stringify({ remote_url: config.remote_url }), SOURCE]);await writeSingleFact(engine, SOURCE, { fact: 'Alice Example leads the platform team at Acme Example.', provenance: 'test:7897', entity: ALICE, visibility: 'world', remote: false });await engine.executeRaw('UPDATE sources SET config = $1::text::jsonb WHERE id = $2', [JSON.stringify(config), SOURCE]);const c: Clone = {- engine, root,+ engine, root, upstream,file: () => readFileSync(join(root, FILE), 'utf8'),head: () => git(root, ['show', `HEAD:${FILE}`]),page: async () => (await engine.getPage(ALICE, { sourceId: SOURCE })) as never,@@ -105,22 +107,30 @@ async function savedApproval(c: Clone): Promise<string> {const arms = testBackends().map(backend => ({ backend, databaseUrl: backend === 'pglite' ? undefined : requirePostgresTestDatabase() }));for (const { backend, databaseUrl } of arms) describe(`[${backend}] repair url-clone-fences (#7897)`, () => {- test('a HEAD asking for Visibility: private previews as held under visibility_noncanonical, with nothing to apply', async () => {+ /** The held file is restored and HEAD is not imported: the page is unchanged and world-readable, the row is database-only, and the clone pulls the upstream fix. */+ const expectHeldRestore = async (c: Clone, page: Awaited<ReturnType<Clone['page']>>, applied: RepairResult) => {+ expect({ applied: applied.applied, outcomes: applied.outcomes, item: applied.outcome_items?.[0] })+ .toEqual({ applied: 1, outcomes: { held: 1 }, item: expect.objectContaining({ outcome: 'held', reason: 'visibility_noncanonical' }) });+ expect({ file: c.file() === c.head(), page: await c.page(), rows: await c.rows() }).toEqual({ file: true, page, rows: [null] });+ expect(Object.keys((await c.page())!.frontmatter).map(k => k.toLowerCase())).not.toContain('visibility');+ writeFileSync(join(c.upstream, FILE), person('visibility: private\n'));+ git(c.upstream, ['commit', '-q', '-am', 'upstream fixes the spelling']);+ expect(() => git(c.root, ['pull', '-q', '--ff-only'])).not.toThrow();+ };++ test('a HEAD asking for Visibility: private previews under visibility_noncanonical; apply restores the file without importing HEAD, so the clone pulls again', async () => {await withClone(databaseUrl, 'Visibility: private\n', async c => {+ const page = await c.page();const preview = await repair(c.engine, { apply: false });- expect({ listing: preview.listing, hash: preview.preview_hash ?? null }).toEqual({ hash: null,- listing: [{ item: `${SOURCE}:${FILE}`, class: 'visibility_noncanonical', detail: expect.stringContaining(`gbrain repair url-clone-fences --source ${SOURCE}`) }] });+ expect(preview.listing).toEqual([{ item: `${SOURCE}:${FILE}`, class: 'visibility_noncanonical', detail: expect.stringContaining('restored from HEAD so the clone can pull again') }]);+ await expectHeldRestore(c, page, await repair(c.engine, { apply: true, expect: preview.preview_hash }));});}, 180_000);- test('an approval saved before the fix applies as held: nothing is imported, the file and its fence rows stay', async () => {+ test('an approval saved before the fix applies as held: the file is restored and its row kept database-only, HEAD is not imported', async () => {await withClone(databaseUrl, 'visibility: Private\n', async c => {- const [file, page, rows] = [c.file(), await c.page(), await c.rows()];- const applied = await repair(c.engine, { apply: true, expect: await savedApproval(c) });- expect({ applied: applied.applied, outcomes: applied.outcomes, item: applied.outcome_items?.[0] })- .toEqual({ applied: 0, outcomes: { held: 1 }, item: expect.objectContaining({ outcome: 'held', reason: 'visibility_noncanonical' }) });- expect({ file: c.file() === file, page: await c.page(), rows: await c.rows() }).toEqual({ file: true, page, rows });- expect(Object.keys((await c.page())!.frontmatter).map(k => k.toLowerCase())).not.toContain('visibility');+ const page = await c.page();+ await expectHeldRestore(c, page, await repair(c.engine, { apply: true, expect: await savedApproval(c) }));});}, 180_000);