Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(repair): provenance preview and apply share one held-page filter; held pages list as held (#8009)

garrytan61158447ff4e
diff --git a/docs/architecture/key-files/security.md b/docs/architecture/key-files/security.md
index 7b98dad7ae..1786583d66 100644
--- a/docs/architecture/key-files/security.md
+++ b/docs/architecture/key-files/security.md
@@ -33,7 +33,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/trust/taint.ts`, `derived-gate.ts`, `timeline-projection.ts` (#5575 derived rows; the rest of `src/core/trust/` is above): `taint.ts` (I2, ENG-3/ENG-7): `readTaintInputs`/`deriveTrust` read the stored tiers of every row a deriver placed in its prompt (a vanished input reads `unknown`); `derivedWriteTrust` caps model output at `agent_written` and a deterministic projection (fence or timeline parse) at `operator_curated`; `recordTaintEdges` writes the complete `derivation_inputs` edges; `lowerToDerivedTier`/`lowerDerivedPage` (and `lowerDerivedPageIn`, the same inside a caller's coordinated transaction) lower a derived row whose republish changed no content column; `derivedMaintenanceTransaction` is the unmanaged deriver seam; `declareDerivation`/`declaredWriteTrust` carry a derivation in a maintenance or facts intent (the preparer stamps it, never above `agent_written`); `readDerivedTaintShare` is the doctor CEO-24 diagnostic. `derived-gate.ts`: the derivers' row-level write gate at the declared tier (`derivedGateConfig`, `applyGateDecision`: insert + flag receipt, hold, or skip a reject; `recordTimelineFlag`). `timeline-projection.ts`: `gbrain extract` timeline walks stamped per page tier and gated. Tests: `test/trust-taint.test.ts`, `test/trust-taint-origin.test.ts` (PGLite and Postgres), `test/trust-taint-dream.test.ts`.
- `src/core/trust/claim.ts` + `claim-state.ts` + `claim-notice.ts`, `src/commands/trust-claim.ts`: #5575 legacy content. `gbrain trust claim-sources` (local CLI; typed source id on a TTY, `--yes` never counts, non-TTY refuses `confirmation_required` with a tell_user_to_run fix) records a claim in `sources.config` (`trust_tier: operator_curated`, `trust_claimed_at`, `trust_claim_lifted_at`) and lifts the source's legacy `unknown` rows (ids at or below `write_gate.scan_baseline`) through `trust/backfill.ts` scoped to the claimed sources (own cursor, `write_origin.channel` `trust_claim`), lowered by `frontmatterTrustCapsSql` (channel.ts, pinned to `frontmatterTrustCaps`) and every backfill signal, never above operator_curated; connector sources refuse. Doctor `trust_sources_unclaimed`, `gbrain post-upgrade` and the behavior-change notice name the claim (`actor: user`, tell_user_to_run); doctor `trust_scan`'s fix is the user's to run; the scan refuses while a lift is pending; explain and review show pending rows as owner tier. `claim-sources --relower [--dry-run]` (`relowerClaimedRows`, backfill.ts) is the lower-only #6533 repair: `trust_claim` rows whose page rule now ranks below their stored tier (legacy `extracted_by: extract_atoms-*` atoms) drop to it, pages first with child rows following through the relower-mode page taint, receipt `write_origin.channel` `trust_relower`; the dry run reports the same rows; doctor `trust_sources_unclaimed` names it. Guide: `docs/guides/memory-trust.md`. Tests: `test/trust-claim.test.ts`, `test/trust-claim-relower.test.ts`.
- `src/core/trust/marker-repair.ts`: #6550 `gbrain trust backfill --repair-unknown-markers` (local CLI, `src/cli/commands/trust.ts`). `previewMarkerRepair` lists live pages whose frontmatter `trust_tier` is `unknown` while the row is higher, with evidence (first `page_versions` snapshot showing the marker vs the fixed release `UNKNOWN_MARKER_FIX_RELEASE`: its commit time bounds the first run, `upgrade-state.json` can name it; whether the oldest kept version had the marker), an `assessment` (`consistent_with_6550` only when a pre-fix snapshot shows it and the first import did not, else `ambiguous`), pages already lowered through the marker (with their revert command), a `preview_hash` and the apply argv naming only the consistent pages. `applyMarkerRepair` refuses `preview_changed` unless the fresh preview hashes to `--expect`, then calls `page-handlers.ts` `repairPageMarker` per named slug: the `trust_owner_page` mode `repair_marker` (refused for remote requests) rewrites the marker to `repairedMarker(stored tier)` (none at owner tiers) at the previewed revision and keeps the tier. `review.ts` adds a `repair` command to `lower_page` items an `unknown` marker caused. Pinned by `test/trust-channel-writes.test.ts` (#6550 repair) and `test/trust-cli.test.ts`.
-- `src/core/trust/provenance-drift.ts`, `src/core/repair/provenance.ts`, `src/commands/doctor/checks/provenance-stamp-drift.ts`: #7891 / #7918. `analyzePageDrift` (pure) walks a page's `page_versions` plus its live row; each transition's writer is the older snapshot's `archived_write_request_id` (joined to `persistence_requests.id` for `authority.remote`, else the principal kind; none: `unattributed`). Verdicts: `remote`, `ambiguous`, `local`, `needs_review` (a later local write changed the same stamp) and `restamp` (a classified page whose live caps rank above its stored tier). A restore puts each stamp back to the server-written column or the value before the first non-local change, and stamps min(lost cap, live caps, stored tier) with `stampTrustMarker`, so it only lowers. `scanProvenanceDrift` is bounded (`DRIFT_SCAN_LIMIT` per source) and degrades to `pre_trust` / `pre_attribution`. The doctor check is read-only; the repair kind is explicit-only and preview-bound (`provenance-v1` hash, approved set) and writes through `trust_owner_page` mode `restore_provenance` (`restorePageProvenance` in `page-handlers.ts`, local CLI only, re-checked against `plannedDigest`, files `lower_page` with proposer `provenance_repair`) or `repair_marker` for `restamp`. Both repair modes render the page to its file on a classic checkout (`writePageThrough` with the preimage bytes). #7917: `recordAgentPageLowering` also files for derived publications and for callers that name a proposer; `prepareMaintenanceMutation` and `derivedMaintenanceTransaction` (rows carrying `prior`) call it. #7918: `derivationWriteTrust` rates a present but unreadable declaration `unknown`.
+- `src/core/trust/provenance-drift.ts`, `src/core/repair/provenance.ts`, `src/commands/doctor/checks/provenance-stamp-drift.ts`: #7891 / #7918. `analyzePageDrift` (pure) walks a page's `page_versions` plus its live row; each transition's writer is the older snapshot's `archived_write_request_id` (joined to `persistence_requests.id` for `authority.remote`, else the principal kind; none: `unattributed`). Verdicts: `remote`, `ambiguous`, `local`, `needs_review` (a later local write changed the same stamp) and `restamp` (a classified page whose live caps rank above its stored tier). A restore puts each stamp back to the server-written column or the value before the first non-local change, and stamps min(lost cap, live caps, stored tier) with `stampTrustMarker`, so it only lowers. `scanProvenanceDrift` is bounded (`DRIFT_SCAN_LIMIT` per source) and degrades to `pre_trust` / `pre_attribution`. The doctor check is read-only; the repair kind is explicit-only and preview-bound (`provenance-v1` hash, approved set) and writes through `trust_owner_page` mode `restore_provenance` (`restorePageProvenance` in `page-handlers.ts`, local CLI only, re-checked against `plannedDigest`, files `lower_page` with proposer `provenance_repair`) or `repair_marker` for `restamp`. A page sync holds is listed `held` by the preview and skipped `held` by the apply, both through `pageHolds` (#8009), so the apply writes what the preview counted. Both repair modes render the page to its file on a classic checkout (`writePageThrough` with the preimage bytes). #7917: `recordAgentPageLowering` also files for derived publications and for callers that name a proposer; `prepareMaintenanceMutation` and `derivedMaintenanceTransaction` (rows carrying `prior`) call it. #7918: `derivationWriteTrust` rates a present but unreadable declaration `unknown`.
- `src/core/write-gate.ts` + `src/core/write-gate-patterns.ts` — the #5575 blocking write gate, separate from observe-only `guardrails.ts` (never imported). Deterministic and model-free (P8): `WRITE_GATE_PATTERNS` (bounded clones of the detection-grade `think/sanitize.ts` `INJECTION_DETECTION_PATTERNS`, the exported transcript `IMPERATIVE_RES`, plus standing-instruction (incl. agent-addressed rules with long run-ups, concealment and act-without-asking clauses), exfiltration (incl. passive "must be emailed to <address>" rules and direct cc/bcc) and credential patterns; families `override`, `standing_instruction`, `exfiltration`, `credential`). `detectInstructionLike` decodes tag characters, strips invisibles and NFKC-folds compatibility forms only when present, finds anchor words in one allocation-light hash pass (one tight loop per word), then runs each pattern only on 4 KB windows (overlap `MAX_MATCH_CHARS` + `MAX_PRECEDING_CHARS`) holding its anchors, tracked as sliding per-window anchor counts, and inside a window only within the pattern's longest match (`write-gate-regex.ts`, the analysis the regex lint uses) of its own anchor words, except `WHOLE_WINDOW_PATTERNS`; `preceded` regexes check context before a rare-token match, a `neg` group rejects negated matches. `assessPageForGate` (title, body minus managed fence table rows, frontmatter strings), `assessFactForGate` (fact, context, value, provenance, pre-sanitized `source_text`), `assessTakeForGate` and `assessTimelineForGate` scan every attacker-controllable field plus origin strings. Verdicts by tier: owner tiers never assessed; `external_untrusted` -> `write_gate.external_mode` (`flag` default per the paid eval, `quarantine` opt-in, `reject`, `off`), detector error -> quarantine; `agent_written`/`unknown` -> `flag` (`write_gate.agent_mode=off`), detector error -> allow. `writeGateOutcome` is the DX-1 `gate` shape; `writeHeldError` / `writeGateRejectedError` build the `write_held` / `write_gate_rejected` refusals (families only, no pattern names). `scripts/check-write-gate-regex.ts` (in verify) proves every pattern bounded. `assessPageForGate` / `assessWriteGate` take an optional `WriteGateWork` accumulator (`createWriteGateWork`) the detector fills per assessment with the work it did (normalization and anchor-pass input units, windows, pattern checks past the prefilter, regex executions, searched characters); nothing is kept between calls (#6490). Tests: `test/write-gate.test.ts`, `test/write-gate-perf.slow.test.ts` (quiet-round absolute p95 with the receipt insert, 5 MB linear bounds), `test/write-gate-work-counters-6490.test.ts` (the counters pinned per corpus; four mutants fail it: disabled prefilter, REACH x8, a per-window normalization pass, a pattern anchored on `the`), `test/write-gate-anchor-ranges.test.ts` (sampled matches of every narrowed pattern hold an anchor word within its longest match), and `test/write-gate-detector-differential.test.ts` (identical hits to the pre-optimization detector v2 kept as `test/helpers/write-gate-detector-reference.ts`, over the detector corpora, BrainBench fixtures, docs/skills and a seeded random corpus).
- `src/core/write-gate-store.ts` + `src/core/write-gate-schema.ts` — `write_gate_receipts` (flag/quarantine verdicts per persisted target, unique on target, content hash and detector version; pattern names only) and `write_gate_holds` (quarantined facts/takes kept out of `facts`/`takes`, unique on source, slug, fingerprint and detector version; re-arrival re-opens a decided hold). Writers record inside their publication transaction: `recordPageGateReceipt` resolves the live page row, `recordWriteGateReceipt`, `recordWriteGateHold`; `decideFactWrite` / `decideTakeWrite` return insert/hold/reject per row and `recordFlaggedRow` receipts an inserted flagged row. Owner review: `listWriteGateHolds`, `getWriteGateHold`, `releaseWriteGateHold` (returns the payload for the confirm path; authorization is the caller's), `dropWriteGateHold`; `pruneWriteGateReceipts` drops receipts unseen for 365 days except a pending hold's. Tests: `test/write-gate-store.test.ts` (+ Postgres arm `test/e2e/write-gate-store-postgres.test.ts`).
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index 37aec25d0c..cff5bd1990 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -168,7 +168,7 @@ work behind exits 0, so scripts should also check `results[].complete`.
| `aliases` | `dangling_aliases` (orphaned rows) | Explicit-only. Deletes free-text page aliases and slug redirects whose target page has no row at all (a page purged before purge removed its aliases, #6619, or a hard-deleted page), each target rechecked under its page lock; a coordinated maintenance write on a managed brain. A redirect from an old name of a page that still exists is never touched. See [aliases](#aliases). | `soft_deleted_target`: aliases of a soft-deleted page, kept for `gbrain restore` and removed when the page is purged. |
| `rename-identity` | `rename_identity_downgrades` | Explicit-only, preview-bound, destructive consent. For an inexact Git rename that sync split into a delete plus an add (#6729): carries the old page's identity (id, version history, timeline, links, facts, aliases) onto the new slug, imports the new file onto it as an edit and retires the provisional page; or, with `--close`, settles the pair and moves nothing. `--slug <new-slug>` (and `--from <old-slug>`) names one pair; `--apply --expect <hash> --yes`. See [rename identity](#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`). |
-| `provenance` | `provenance_stamp_drift` | Explicit-only, preview-bound, destructive. Restores provenance stamps and lowering markers that remote writes removed before #7892, and stamps the stored tier as the marker on classified pages whose file would re-read higher (#7918). Only lowers; a lowered page files a `lower_page` proposal. See [provenance](#provenance). | The owner's own edits (`local`), pages a later local write also changed (`needs_review`), unattributed writes without `--include-ambiguous`; pages that moved after the preview (`preview_changed`). |
+| `provenance` | `provenance_stamp_drift` | Explicit-only, preview-bound, destructive. Restores provenance stamps and lowering markers that remote writes removed before #7892, and stamps the stored tier as the marker on classified pages whose file would re-read higher (#7918). Only lowers; a lowered page files a `lower_page` proposal. See [provenance](#provenance). | The owner's own edits (`local`), pages a later local write also changed (`needs_review`), pages whose file sync holds (`held`), unattributed writes without `--include-ambiguous`; pages that moved after the preview (`preview_changed`). |
| `missing-tables` | `schema_missing_tables` | Explicit-only, preview-bound. Recreates, empty, a rebuildable cache table (`query_cache`, `code_traversal_cache`) that the applied migrations created but the brain no longer has, on a brain whose schema version already covers its creating migration, so `apply-migrations` never recreates it (#6911). DDL only (`IF NOT EXISTS`), no journal admission, brain-wide. See [missing tables](#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): 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. |
@@ -772,8 +772,10 @@ Each listed page has a class:
only with `--include-ambiguous`, which changes the hash.
- `restamp`: the classified page from #7918. The apply stamps its stored tier as
the marker; the row keeps its tier.
-- `local` and `needs_review`: the owner's own edit, or a page a later local
- write also changed. Listed, never written; edit those pages by hand.
+- `local`, `needs_review` and `held`: the owner's own edit, a page a later local
+ write also changed, or a page whose file sync holds (the hold's code and fix are
+ in the detail; the apply skips a page held after its preview). Listed, never
+ written; edit those pages by hand, or resolve the hold and preview again.
Every change only lowers: no stamp, marker or tier is ever raised. A lowered
page gets a `lower_page` proposal (proposer `provenance_repair`) that
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index d80fca694b..d7d75adfed 100644
--- a/scripts/module-size-limits.tsv
+++ b/scripts/module-size-limits.tsv
@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: link
src/core/search/evidence-delivery.ts 1755 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned)
src/commands/config.ts 1524 ratchet new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)
src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)
-src/core/behavior-change-notice.ts 1570 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope)
+src/core/behavior-change-notice.ts 1571 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +1 GBRA-247 #8009 provenance_repair_held_8009 row; +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope)
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index a834798000..eece806854 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1372,6 +1372,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.514.0', id: 'storage_ignored_dirs_8015', text: 'When gbrain.yml lists a deprecated `supabase_only` next to canonical keys (which ignores it), a managed sync now holds only the missing-file pages under the ignored directories `db_only` does not already cover, and deletes other missing-file pages as usual; it used to hold every missing-file page of the source. `gbrain storage status` now names those directories, and the deprecation warning no longer points to a `gbrain doctor --fix` rename that does not exist. A `db_only` or `supabase_only` line whose inline value the parser refuses (a missing comma, a nested list, a bare scalar) now counts as unresolved even when another key resolves, so missing-file pages are held rather than deleted.' },
{ since: '0.60.514.0', id: 'company_db_only_keep_8014', text: 'A company-brain source now keeps a live page under a declared `storage.db_only` directory when its file is not in the approved manifest, and keeps every such page while its gbrain.yml storage section is invalid, as other managed sources do; it used to delete them. The decision reads gbrain.yml at the approved commit, never the working tree.' },
{ since: '0.60.514.0', id: 'redaction_marker_not_credential_7997', text: 'The transcript `labeled_credential` detector no longer reads an importer redaction marker (`login **<REDACTED:user-pattern>**`) as a typed user/password pair, so a correctly redacted page clears `gbrain transcripts audit-secrets`; a password written beside a marker is still found. The audit detector version moves to 3, so `gbrain doctor` asks for a fresh audit once.' },
+ { since: '0.60.516.0', id: 'provenance_repair_held_8009', text: '`gbrain repair provenance` now lists a page whose file sync holds (a `file_drift` hold, for example) as `held`, with the hold\'s code and fix, instead of planning it: the owner page write refuses such a page, so the preview used to count pages the apply could not write and the batch ended with a failed item. The apply also skips a page held after its preview as `held` rather than failing it, so it writes the count the preview printed.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/repair/provenance.ts b/src/core/repair/provenance.ts
index 309ea849cc..77de375a32 100644
--- a/src/core/repair/provenance.ts
+++ b/src/core/repair/provenance.ts
@@ -9,7 +9,8 @@
* `restore_provenance` (trust/page-handlers.ts `restorePageProvenance`).
* - `restamp` (#7918): the stored tier stamped as the marker; the row keeps its tier (mode `repair_marker`).
* - Listed, never written: `needs_review` (a later local write also changed the stamp), `local` (the owner's own
- * edit), `ambiguous` without the flag.
+ * edit), `ambiguous` without the flag, and `held` (#8009): a page whose file sync holds, which an owner page write
+ * refuses (`pageHolds`, read by the preview and again by the apply, so the apply writes what the preview counted).
*
* Explicit-only and preview-bound: the preview lists each page with its revision and planned change under a hash and
* writes nothing but the approval checkpoint; `--apply --expect <hash> --yes` writes exactly that set, one owner page
@@ -21,6 +22,7 @@ import type { BrainEngine } from '../engine.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
+import { GIT_HOLD_OP, gitHoldFix, type GitHoldRecord } from '../persistence/sync-holds.ts';
import { ownerRepairFile, repairPageMarker, restorePageProvenance } from '../trust/page-handlers.ts';
import { plannedDigest, readPageDrift, scanProvenanceDrift, type DriftItem } from '../trust/provenance-drift.ts';
import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairListing, type RepairPlan, type RepairScope } from './core.ts';
@@ -60,6 +62,21 @@ function writerDetail(item: DriftItem): string {
return change ? `written by a ${change.writer} write${change.request_id ? ` (request ${change.request_id})` : ''}` : '';
}
+/** #8009: the sync holds of the source's live incarnation on these pages (by page id or slug), keyed by page id. */
+async function pageHolds(engine: BrainEngine, sourceId: string, pages: ReadonlyArray<{ id: number; slug: string }>): Promise<Map<number, GitHoldRecord>> {
+ if (!pages.length) return new Map();
+ const holds = (await engine.executeRaw<{ record: GitHoldRecord }>(`SELECT h.completed_keys->0 AS record FROM op_checkpoints h
+ JOIN sources s ON s.id=h.completed_keys->0->>'source_id' AND s.incarnation::text=h.completed_keys->0->>'incarnation'
+ WHERE h.op=$1 AND s.id=$2 AND (h.completed_keys->0->>'slug'=ANY($3::text[]) OR h.completed_keys->0->>'page_id'=ANY($4::text[]))`,
+ [GIT_HOLD_OP, sourceId, pages.map(page => page.slug), pages.map(page => String(page.id))])).map(row => row.record);
+ return new Map(pages.flatMap(page => {
+ const hold = holds.find(record => Number(record.page_id) === page.id || record.slug === page.slug);
+ return hold ? [[page.id, hold] as const] : [];
+ }));
+}
+
+const heldDetail = (hold: GitHoldRecord) => `sync holds the page file (${hold.code}), so a page write refuses it; resolve the hold (${(gitHoldFix(hold).argv ?? []).join(' ')}), then preview again`;
+
const segmented = async (engine: BrainEngine, pageId: number) =>
(await engine.executeRaw<{ body_storage: string | null }>('SELECT body_storage FROM pages WHERE id = $1', [pageId]))[0]?.body_storage === 'segmented';
@@ -67,10 +84,11 @@ const segmented = async (engine: BrainEngine, pageId: number) =>
async function scan(engine: BrainEngine, scope: RepairScope, selection: Selection) {
const planned: PlannedPage[] = [];
const listing: RepairListing[] = [];
- const residuals: Record<string, number> = { restore: 0, restamp: 0, ambiguous: 0, needs_review: 0, local: 0 };
+ const residuals: Record<string, number> = { restore: 0, restamp: 0, ambiguous: 0, needs_review: 0, local: 0, held: 0 };
const managedBrain = await managedPersistenceEnabled(engine);
for (const sourceId of scope.source_ids) {
const drift = await scanProvenanceDrift(engine, sourceId, { limit: Number.MAX_SAFE_INTEGER, includeAmbiguous: selection.include_ambiguous, slugs: selection.slugs });
+ const holds = await pageHolds(engine, sourceId, drift.items.map(item => ({ id: item.page_id, slug: item.slug })));
for (const item of drift.items) {
const label = `${item.source_id}:${item.slug} (revision ${item.revision})`;
const { verdict } = item;
@@ -81,6 +99,8 @@ async function scan(engine: BrainEngine, scope: RepairScope, selection: Selectio
listing.push({ item: label, class: 'ambiguous', detail: `no recorded writer; previewed with --include-ambiguous only; ${writerDetail(item)}` });
continue;
}
+ const hold = holds.get(item.page_id);
+ if (hold) { residuals.held!++; listing.push({ item: label, class: 'held', detail: heldDetail(hold) }); continue; }
if (await segmented(engine, item.page_id)) {
residuals.needs_review!++;
listing.push({ item: label, class: 'needs_review', detail: 'the page stores its body in segments, which this repair does not rewrite; edit its frontmatter by hand' });
@@ -155,6 +175,8 @@ export const provenanceRepair: RepairHandler = {
const { page, hash, includeAmbiguous, last } = entry as ProvenanceItem;
try {
if (await stillPlanned(ctx.engine, page, includeAmbiguous) !== 'planned') return { applied: false, outcome: 'changed_since_preview', reason: 'the page changed since the preview' };
+ const hold = (await pageHolds(ctx.engine, page.source_id, [page])).get(page.id);
+ if (hold) return { applied: false, outcome: 'held', reason: heldDetail(hold) };
const input = { sourceId: page.source_id, slug: page.slug, expectedRevision: page.revision, confirmation: { via: 'preview_hash' as const }, config: ctx.config };
const result = page.action === 'restamp' ? await repairPageMarker(ctx.engine, input)
: await restorePageProvenance(ctx.engine, { ...input, planned: page.planned, includeAmbiguous });
diff --git a/test/provenance-drift-7891.test.ts b/test/provenance-drift-7891.test.ts
index 85a1a22824..51b8cc616b 100644
--- a/test/provenance-drift-7891.test.ts
+++ b/test/provenance-drift-7891.test.ts
@@ -26,6 +26,7 @@ import { resetGateway } from '../src/core/ai/gateway.ts';
import { withTrustPromotion, withWriteAttribution } from '../src/core/persistence/context.ts';
import type { WriteAttribution } from '../src/core/persistence/attribution.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { writeGitHold } from '../src/core/persistence/sync-holds.ts';
import { resolveRepairScope } from '../src/core/repair/core.ts';
import { AUTO_REPAIR_REGISTRY, repairRunner } from '../src/core/repair/registry.ts';
import { analyzePageDrift } from '../src/core/trust/provenance-drift.ts';
@@ -35,7 +36,7 @@ import { withEnv } from './helpers/with-env.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
-import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';
+import { managedBrain, settleManagedGitEffects, type ManagedBrain } from './helpers/managed-brain.ts';
import { operationsByName } from '../src/core/operations.ts';
import { withManagedFixtureWrite } from './helpers/managed-e2e-fixture-write.ts';
@@ -260,8 +261,8 @@ for (const kind of testBackends()) {
for (const kind of testBackends()) {
const databaseUrl = kind === 'postgres' ? requirePostgresTestDatabase() : undefined;
describe(`#7891 provenance drift (${kind}, managed repository brain)`, () => {
- test('apply publishes the restore through the coordinator: the file and the row carry the restored stamps and marker', () => managedBrain(async ({ engine, ctx, root }) => {
- const slug = 'inbox/managed-restore';
+ /** A managed page a pre-#7892 remote write left without its stamps; its file matches the row. */
+ const remoteDrop = async ({ engine, ctx, root }: ManagedBrain, slug: string) => {
await operationsByName.put_page.handler(ctx, { slug, content: '---\ntitle: Seeded\ntype: note\n---\nCaptured body\n' });
await settleManagedGitEffects(engine);
const seeded = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
@@ -277,13 +278,20 @@ for (const kind of testBackends()) {
});
const live = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
fs.writeFileSync(path.join(root, `${slug}.md`), serializePageToMarkdown(live.page, live.tags));
- const repair = (apply: boolean, expect?: string) => (async () => (await repairRunner(engine, { apply, logger }))
- .run('provenance', await resolveRepairScope(engine, 'default'), { explicit: true, sourceFlag: 'default', ...(expect ? { expect } : {}) }))() as Promise<Record<string, any>>;
- const dry = await repair(false);
+ return live;
+ };
+ const repair = (engine: BrainEngine, apply: boolean, expect?: string) => (async () => (await repairRunner(engine, { apply, logger }))
+ .run('provenance', await resolveRepairScope(engine, 'default'), { explicit: true, sourceFlag: 'default', ...(expect ? { expect } : {}) }))() as Promise<Record<string, any>>;
+
+ test('apply publishes the restore through the coordinator: the file and the row carry the restored stamps and marker', () => managedBrain(async brain => {
+ const { engine, root } = brain;
+ const slug = 'inbox/managed-restore';
+ await remoteDrop(brain, slug);
+ const dry = await repair(engine, false);
expect(dry.listing.map((entry: Record<string, string>) => entry.class)).toEqual(['remote']);
const fileBefore = fs.readFileSync(path.join(root, `${slug}.md`), 'utf8');
expect(fs.readFileSync(path.join(root, `${slug}.md`), 'utf8')).toBe(fileBefore);
- await repair(true, dry.preview_hash);
+ await repair(engine, true, dry.preview_hash);
await settleManagedGitEffects(engine);
const row = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.page.frontmatter;
const file = parseMarkdown(fs.readFileSync(path.join(root, `${slug}.md`), 'utf8'), slug).frontmatter;
@@ -292,7 +300,44 @@ for (const kind of testBackends()) {
expect(row.trust_tier).toBe('external_untrusted');
expect(file.trust_tier).toBe('external_untrusted');
expect((await engine.executeRaw<{ trust_tier: string }>('SELECT trust_tier FROM pages WHERE source_id = $1 AND slug = $2', ['default', slug]))[0]!.trust_tier).toBe('external_untrusted');
- expect((await repair(false)).affected).toBe(0);
+ expect((await repair(engine, false)).affected).toBe(0);
+ }, { databaseUrl }), 120_000);
+
+ test('#8009: a page sync holds as file_drift is listed held with its code, never planned; the apply writes exactly the previewed count', () => managedBrain(async brain => {
+ const { engine, root } = brain;
+ const [clear, held] = ['inbox/managed-clear', 'inbox/managed-held'];
+ await remoteDrop(brain, clear);
+ const heldPage = await remoteDrop(brain, held);
+ // Sync found the file and the row both changed and held the file (file_drift): an owner page write refuses the page.
+ fs.appendFileSync(path.join(root, `${held}.md`), '\nAn edit made in the checkout.\n');
+ const [{ incarnation }] = await engine.executeRaw<{ incarnation: string }>("SELECT incarnation::text AS incarnation FROM sources WHERE id = 'default'");
+ await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation: incarnation!, path: `${held}.md`, source_path: `${held}.md`, slug: held,
+ page_id: heldPage.page.id, code: 'file_drift', message: 'The file and the database copy both changed.', upstream_version: null, observed_at: new Date().toISOString(),
+ run_id: 'run-a', mode: 'managed', meta: { side: 'both' } } as Parameters<typeof writeGitHold>[1]));
+ const dry = await repair(engine, false);
+ expect(dry.listing.map((entry: Record<string, string>) => [entry.class, entry.item.split(' ')[0]])).toEqual([['remote', `default:${clear}`], ['held', `default:${held}`]]);
+ expect(dry.listing[1].detail).toContain('file_drift');
+ expect(dry.affected).toBe(1);
+ const applied = await repair(engine, true, dry.preview_hash);
+ await settleManagedGitEffects(engine);
+ expect(applied.failed).toEqual([]);
+ expect(applied.applied).toBe(dry.affected);
+ expect(stampsOf((await engine.readPageSnapshot(clear, { sourceId: 'default' }))!.page.frontmatter)).toEqual(STORED);
+ expect((await engine.readPageSnapshot(held, { sourceId: 'default' }))!.revision).toBe(heldPage.revision);
+
+ // The apply reads the same holds: a page held after its preview is skipped as held, not a failed write.
+ const late = 'inbox/managed-late';
+ const latePage = await remoteDrop(brain, late);
+ const before = await repair(engine, false);
+ expect(before.listing.map((entry: Record<string, string>) => [entry.class, entry.item.split(' ')[0]])).toEqual([['held', `default:${held}`], ['remote', `default:${late}`]]);
+ fs.appendFileSync(path.join(root, `${late}.md`), '\nAn edit made in the checkout.\n');
+ await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation: incarnation!, path: `${late}.md`, source_path: `${late}.md`, slug: late,
+ page_id: latePage.page.id, code: 'file_drift', message: 'The file and the database copy both changed.', upstream_version: null, observed_at: new Date().toISOString(),
+ run_id: 'run-b', mode: 'managed', meta: { side: 'both' } } as Parameters<typeof writeGitHold>[1]));
+ const skipped = await repair(engine, true, before.preview_hash);
+ expect(skipped.failed).toEqual([]);
+ expect([skipped.applied, skipped.outcomes]).toEqual([0, { held: 1 }]);
+ expect((await engine.readPageSnapshot(late, { sourceId: 'default' }))!.revision).toBe(latePage.revision);
}, { databaseUrl }), 120_000);
});
}