Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(sync,repair): #7909 review follow-ups for held files (#7974)
garrytan174fdac5c5dc
diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex 7be483b047..062759a312 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -2521,7 +2521,8 @@ the two `--prefer` values do opposite things in each state.`--prefer file` keeps the file's bytes: it adds only protected frontmatter keys thefile lacks and database-only timeline rows, and refuses[`file_wins_rewrite`](write-refusals.md#file_wins_rewrite) when the result-would change anything else.+would change anything else (a database-only timeline row dated before the+file's rows included).A held page whose page and file agree now is listed `release_hold` undereither `--prefer`, whether `--held` or `--slug` selected it: its apply writesdiff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex a918b2cda4..7adafcac84 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -258,7 +258,7 @@ with each file and fix the ones that need no guessing."*| <a id="rename_reconcile_failed"></a>`rename_reconcile_failed` | Classic sync (GBRA-133 S-67): a rename fell back to importing the new file, and removing the page of the old name then failed with an unexpected error (the hold records its class and code, never its message). The old page was kept and may duplicate the new one; the rest of the source keeps syncing. A transient database error and the reconcile's own "staleness unprovable" verdict still record the `<rename:…>` marker, which a later run converges. | Ask the user before `gbrain sync --source <source> --full --no-pull`: the full walk removes pages whose file is gone after checking each one (it re-reads the whole source). Or remove the old page with `gbrain delete --source <source> -- <slug>` (recoverable for 72 h). || <a id="concurrent_write"></a>`concurrent_write` | Managed sync was importing a newer Git version of the file while a database-only write (write-through off, a sandboxed or derived write) committed a different version of the same page, so the two diverge (#6194). The proof is the page's revision itself: it was written by a committed non-sync request for that page. Neither version was overwritten: the page keeps the database version, the file is held and the rest of the source syncs. Since #6340 a page that moved with no such request to name is held the same way (the hold records `page_revision` and `expected_revision` instead of a competing request), and so is a page that changed, was deleted or was re-bound in the database between the manifest freeze and the entry's turn; a page that still holds exactly what the file would import is re-bound to its new revision and passed. | `gbrain sources status <source>` names the page and the competing request. Preview with `gbrain sources reconcile <source> <slug> --preview`, decide with the user which content wins, apply the resolved preview, then `gbrain sources retry-held <source>` and `gbrain sync --source <source> --no-pull` re-screen the file. A new commit of the file re-screens it too. || <a id="file_drift"></a>`file_drift` | Managed sync would have imported a file over a database version of its page that sync never saw (#6712). Every import records its provenance (the bytes left on disk, the page revision it wrote, the parser); a page that moved since that record (a database-only write, write-through off) while its file did not change, or, in a tree walk (first sync, `--full`, an unreachable checkpoint), a page whose file and revision both moved or that has no usable record (an upgraded brain: none, a pre-PR 0 record, a partial one), is imported only when the import changes nothing, a sync request wrote its current revision, or its writer's write-through wrote that revision to the file. Otherwise the file is held, the page keeps the database version and the rest of the source syncs. The hold names `sides` (`database`, `both`, `unknown`) and the database request that wrote the page when there was one; a hold the live pass writes also names its Decision, `side` (`both`, `unknown`, `deleted`) and, for a deleted side, `state` (`tombstone_edited`, `purged_differs`, `file_gone`). Pages under `storage.keep_db` prefixes whose file is clean in committed mode are not held: the pass writes the database copy back to the file (at most 200 per pass, the rest the next pass); an uncommitted edit there is held. Holds of this code never escalate; with `sync.holds=fail` the run stops with `file_drift` instead of holding. | `gbrain sources status <source>` names the page. Preview `gbrain repair file-drift --source <source> --slug <slug> --prefer database` (keep the database copy, rewrite the file) or `--prefer file` (import the file), decide with the user, apply it with the plan hash, then `gbrain sync --source <source> --no-pull`. Held pages of one Decision resolve together with [`--held --side <side> [--state <state>]`](repair.md#file-drift-held). A changed file or page revision re-screens the hold by itself. |-| <a id="file_wins_rewrite"></a>`file_wins_rewrite` | `gbrain repair file-drift --prefer file` keeps the canonical file's bytes and adds only the protected parts reconcile keeps from the database: protected frontmatter keys the file lacks (inserted before the closing `---`) and database-only timeline rows (appended to the file's timeline, with a `<!-- timeline -->` line above a bare `## Timeline` heading so they stay in it). When the resolved page also differs in anything else (a value, a tag, the title, the body), keeping the file would mean re-rendering all of it, so the preview refuses the page and nothing is written. | Show the user the page's differences. Commit them into the file through the door (`gbrain git commit-push`) and preview again, or preview `--prefer database` if the database copy should win. |+| <a id="file_wins_rewrite"></a>`file_wins_rewrite` | `gbrain repair file-drift --prefer file` keeps the canonical file's bytes and adds only the protected parts reconcile keeps from the database: protected frontmatter keys the file lacks (inserted before the closing `---`) and database-only timeline rows (appended to the file's timeline, with a `<!-- timeline -->` line above a bare `## Timeline` heading so they stay in it). When the resolved page also differs in anything else (a value, a tag, the title, the body), keeping the file would mean re-rendering all of it, so the preview refuses the page and nothing is written. A database-only timeline row dated before the file's own rows sorts in among them rather than after them, so it refuses too. A file-wins apply accepted before this rule existed refuses the same way when it is prepared, and writes nothing. | Show the user the page's differences. Commit them into the file through the door (`gbrain git commit-push`) and preview again, or preview `--prefer database` if the database copy should win. || <a id="frontmatter_alias_limit"></a>`frontmatter_alias_limit` | A file whose exact bytes an older gbrain imported and validated nests YAML aliases in its frontmatter that expand past the size limit (#7018). This release refuses them on purpose, so only that file is held (its page keeps the last imported version) and the rest of the source syncs; it is never a parser regression. | Reduce the alias nesting in the frontmatter (or write the values out), or remove the file, then commit and `gbrain sync --source <source> --no-pull`. The hold re-screens when the file changes. Before 4b such a file stopped the source as `sync_parser_regression`; the workaround there was `GBRAIN_SYNC_PARSER_REGRESSION=hold` for the process that syncs. || <a id="visibility_noncanonical"></a>`visibility_noncanonical` | The file's frontmatter asks for `visibility: private` in a spelling page privacy does not read: another case (`Visibility: private`, `visibility: Private`), a block scalar, a list, a flow mapping or a merge key. Page privacy reads only the exact lowercase key and value, so importing it would store a world-readable page its author believes is private. Git sync (classic and managed) holds the file and the rest of the source syncs; `gbrain import` (with or without a Git checkout) refuses it and imports the rest. An existing page keeps its last imported version. Company-brain connects and syncs, and the GitHub and Google connectors on a database-only source, hold it the same way (#7880); `gbrain repair url-clone-fences` lists a clone file whose HEAD asks for it this way under this code; apply restores the file from HEAD with its fence rows kept database-only, so the clone can pull, but does not import HEAD and reports `held` (#7897). `put_page`, `edit_page`, `capture`, `ingest_capture`, `brainstorm --save` and `sources reconcile` refuse the same request as [`visibility_not_applied`](#visibility_not_applied). Doctor `git_held_files` counts the held files and the stored pages that ask for private this way (`details.visibility_noncanonical`). | Write `visibility: private` on its own frontmatter line (lowercase key and value), commit, and run `gbrain sync --source <source> --no-pull` (or import the file again). The hold re-screens when the file changes; no frontmatter repair rewrites a privacy request. For a stored page doctor names, rewrite its frontmatter the same way with `put_page` or by editing its file. || <a id="parser_regression"></a>`parser_regression` | A file whose exact bytes imported under an earlier gbrain is now refused. It is held and the rest of the source syncs (the default; `GBRAIN_SYNC_PARSER_REGRESSION=stop` stops the run instead). This is a gbrain bug. | Report it with the gbrain version, the file and the code; upgrade or pin the last good version. After a fixed gbrain is installed, `gbrain sources retry-held <source>` and then `gbrain sync --source <source> --no-pull` re-screen it. |diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex 35a3a3a3dd..ade9981bac 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: linksrc/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 1575 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); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row+src/core/behavior-change-notice.ts 1576 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); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 rowdiff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 0250848b7f..adf285776c 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1377,6 +1377,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;// #7931 parts 2 and 3. since is stamped at the merge slot.{ since: '0.60.516.0', id: 'file_drift_agrees_7931', text: 'A managed sync no longer holds a file as `file_drift` when its page agrees with it as `gbrain repair file-drift` reads them (they differ only in how the file writes the page, such as YAML quoting, or in a reserved key an older import kept in the database copy): the file imports. A held file someone asks to re-screen (`gbrain sources retry-held`, or the apply of a `release_hold` preview) whose page has no import record is now screened again instead of staying held, so an agreeing page is released. A `gbrain repair file-drift --apply` refused before it published no longer makes the apply after a fresh preview with the same `--expect` answer `idempotency_conflict`.' },{ since: '0.60.516.0', id: 'file_drift_slug_release_7950', text: '`gbrain repair file-drift --slug <s>` now lists a held page whose file agrees with it as `release_hold` (it was `no_drift`, and its printed apply always refused `preview_changed`); the apply releases only the hold the preview observed and answers `changed_since_preview` when that hold was replaced. A preview that finds nothing to apply prints an apply command that now applies nothing instead of refusing `preview_changed`.' },+ { since: '0.60.516.0', id: 'file_drift_followups_7974', text: 'A page a read-only mirror stored database-only is compared with the file at its slug path the way `gbrain sources reconcile` reads it: one that agrees is listed `release_hold` instead of drifted, and one whose slug path has several spellings is listed unknown (`slug_path_ambiguous`) instead of aborting `gbrain repair file-drift` and the conflict audit. A held file whose page agrees with a different file than the held one is listed unknown instead of `release_hold`. The slug path of a page with no recorded file follows the source\'s slug-root mode and never resolves through a symlink.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/persistence/drift-conflicts.ts b/src/core/persistence/drift-conflicts.tsindex 69809f35e3..bc2a24f20b 100644--- a/src/core/persistence/drift-conflicts.ts+++ b/src/core/persistence/drift-conflicts.ts@@ -19,7 +19,7 @@* updates and releases it once the file and database agree again;* - doctor `maintenance_write_drift` and `gbrain repair file-drift`.*/-import { existsSync, readFileSync } from 'node:fs';+import { readFileSync } from 'node:fs';import { join, relative, sep } from 'node:path';import type { BrainEngine } from '../engine.ts';import { OperationError, opError } from '../ops/contract.ts';@@ -84,10 +84,18 @@ export async function liveFileDrift(engine: BrainEngine, sourceId: string, slug:if (!page || page.page.deleted_at) return { still_present: null, reason: 'page_missing' };const root = join(binding.local_path, binding.relative_path);// GBRA-133 (#7931): a stale mirror page publishes database-only but reconciles against the file at its slug path.+ // #7974: it is compared as reconcile reads it; a slug path that reading cannot settle (several spellings) is unknown.if (await staleMirrorPage(engine, sourceId, page.page)) {- const path = slugPathFile(root, slug);- if (!existsSync(path)) return { still_present: false, reason: 'database_only', db_revision: page.revision };- return { still_present: true, reason: 'file_database_drift', db_revision: page.revision, path: relative(root, path).split(sep).join('/'), file_hash: sha256(readFileSync(path)) };+ try {+ const state = await readReconcileState(engine, sourceId, slug);+ const agrees = classifyDrift(state.file, reconcileCanonical(state.snapshot.page, state.snapshot.tags)).verdict === 'no_drift';+ return { still_present: !agrees, reason: agrees ? 'agrees' : 'file_database_drift', db_revision: state.snapshot.revision,+ path: relative(state.root, state.path).split(sep).join('/'), file_hash: sha256(state.raw) };+ } catch (error) {+ if (!(error instanceof OperationError)) return { still_present: null, reason: 'error' };+ if (error.detail === 'canonical_file_missing') return { still_present: false, reason: 'database_only', db_revision: page.revision };+ return { still_present: null, reason: typeof error.detail === 'string' ? error.detail : error.code };+ }}try {const file = await prepareFileTarget(engine, { source_id: sourceId, worktree_id: binding.worktree_id, slug }, page, null, hostId!);@@ -111,9 +119,9 @@ export async function liveFileDrift(engine: BrainEngine, sourceId: string, slug:/** The path `prepareFileTarget` compares, resolved the same way (recorded source path, captured file URI, then the slug path). */async function canonicalFilePath(engine: BrainEngine, sourceId: string, root: string, snapshot: PageSnapshot, slug: string): Promise<string> {- const mode = snapshot.page.source_path ? await scannerSlugRootMode(engine, sourceId, root) : undefined;+ const mode = await scannerSlugRootMode(engine, sourceId, root);const captured = recordedPathFromFileUri(snapshot.page.source_uri, root);- return resolveSourceLocalFilePath(root, snapshot.page.source_path, slug, mode) ?? (captured ? join(root, captured) : slugPathFile(root, slug));+ return resolveSourceLocalFilePath(root, snapshot.page.source_path, slug, mode) ?? (captured ? join(root, captured) : slugPathFile(root, slug, mode));}/** Whether Git tracks the canonical file and whether its bytes equal the last commit (null: Git cannot say). */diff --git a/src/core/persistence/file-wins-content.ts b/src/core/persistence/file-wins-content.tsindex 867857a44d..ff16793538 100644--- a/src/core/persistence/file-wins-content.ts+++ b/src/core/persistence/file-wins-content.ts@@ -5,6 +5,9 @@* the file; a timeline the file keeps under a bare `## Timeline` heading gets the `<!-- timeline -->` sentinel above it, so the* appended rows stay in it). Anything else the result changes (a key's value, a tag, the title, the body, a timeline that is not* an extension of the file's) would need a re-render that reorders keys, re-emits lists and rewrites the body, so it refuses.+ * #7974: a database-only timeline row dated before the file's own rows sorts into the result's timeline ahead of them, so+ * that timeline is no extension of the file's and the page refuses too; `--prefer database`, or a commit that adds the row to+ * the file, resolves it.*/import type { ParsedPage } from '../import-file.ts';import { opError } from '../ops/contract.ts';diff --git a/src/core/persistence/page-prepare.ts b/src/core/persistence/page-prepare.tsindex 4cd0ffd2de..3fb740a314 100644--- a/src/core/persistence/page-prepare.ts+++ b/src/core/persistence/page-prepare.ts@@ -320,7 +320,7 @@ export async function prepareFileTarget(engine: BrainEngine, row: Pick<WriteRequconst recordedPath = snapshot?.page.source_path || snapshot?.page.withheld_source_path || null;const mode = recordedPath ? await scannerSlugRootMode(engine, row.source_id, root) : undefined;const candidate = resolveSourceLocalFilePath(root, recordedPath, row.slug, mode)- ?? (capturedPath ? join(root, capturedPath) : snapshot ? slugPathFile(root, row.slug) : join(root, `${row.slug}.md`));+ ?? (capturedPath ? join(root, capturedPath) : snapshot ? slugPathFile(root, row.slug, await scannerSlugRootMode(engine, row.source_id, root)) : join(root, `${row.slug}.md`));if (isWindowsColonTarget(relative(root, candidate))) {if (!options.allowMissing && publishesDatabaseOnly(root, row.slug, snapshot)) return undefined;throw colonSlugWindowsRefusal(row.slug, row.source_id);diff --git a/src/core/persistence/reconcile.ts b/src/core/persistence/reconcile.tsindex 1fb3b4df4d..b2d7a6227b 100644--- a/src/core/persistence/reconcile.ts+++ b/src/core/persistence/reconcile.ts@@ -145,10 +145,16 @@ export async function runReconcilePreview(engine: BrainEngine, params: Record<stsha256(serializePageToMarkdown(state.snapshot.page, state.snapshot.tags)) !== state.pins.raw_file_hash,result_digest: preview.result_digest, preview };}+/**+ * Applies one reconcile preview under its request id. `keep_file_bytes` (`repair file-drift --prefer file`) keeps the canonical+ * file's bytes plus the protected parts the result keeps from the database (`fileWinsContent`), and refuses `file_wins_rewrite`+ * at prepare when the result needs any other change. #7974: a pending request accepted before that rule prepares under it, so+ * it refuses `file_wins_rewrite` instead of rendering the result, writes nothing, and the page is previewed again.+ */export async function runReconcileApply(engine: BrainEngine, params: Record<string, unknown>): Promise<Record<string, unknown>> {strictReconcileKeys(params, ['source_id', 'slug', 'preview', 'request_id', 'keep_file_bytes'], ['source_id', 'slug', 'preview', 'request_id']);if (params.keep_file_bytes !== undefined && params.keep_file_bytes !== true) throw opError('invalid_params', 'keep_file_bytes is true or absent.',- 'Pass keep_file_bytes: true to leave a canonical file that already holds the resolved result byte for byte, or omit it.');+ 'Pass keep_file_bytes: true to keep the canonical file\'s bytes and add only the protected parts the result keeps from the database (any other change refuses file_wins_rewrite), or omit it.');const { sourceId, slug, authority } = await authorizeReconcile(engine, params.source_id, params.slug);const artifact = validateReconcileArtifact(params.preview);artifact.decisions = reconcileDecisions(artifact.decisions);diff --git a/src/core/persistence/unbound-pages.ts b/src/core/persistence/unbound-pages.tsindex 71bbde104e..554548eaa0 100644--- a/src/core/persistence/unbound-pages.ts+++ b/src/core/persistence/unbound-pages.ts@@ -11,7 +11,7 @@* stamped in the publication transaction), so an ordinary page that merely* lacks a recorded origin is never matched to a slug-derived file.*/-import { existsSync, readdirSync, type Dirent } from 'node:fs';+import { readdirSync, type Dirent } from 'node:fs';import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';import { resolveSourceLocalFilePath } from '../markdown.ts';import { opError } from '../ops/contract.ts';@@ -72,14 +72,12 @@ export function recordsNoFileOrigin(page: { source_path?: string | null; source_}/**- * GBRA-133: the file at a page's slug path (source-root relative). When `<slug>.md` is absent, the one file whose path- * imports as the slug in another spelling (`README.md` for slug `readme`) is that file, as discovery names it.+ * GBRA-133: the file at a page's slug path, in the source's slug-root mode. When no ordinary file is spelled `<slug>.md`,+ * the one file whose path imports as the slug in another spelling (`README.md` for slug `readme`) is that file, as+ * discovery names it (#7974: read through `slugDerivedOrigin`, so a symlink or a case-insensitive match never stands in).*/-export function slugPathFile(root: string, slug: string): string {- const exact = join(root, `${slug}.md`);- if (existsSync(exact)) return exact;- const derived = slugDerivedOrigin(root, slug, 'source-root');- return derived && existsSync(derived.path) ? derived.path : exact;+export function slugPathFile(root: string, slug: string, mode: 'git-root' | 'source-root'): string {+ return slugDerivedOrigin(root, slug, mode)?.path ?? join(root, `${slug}.md`);}function entries(dir: string): Dirent[] {diff --git a/src/core/repair/file-drift.ts b/src/core/repair/file-drift.tsindex f89e941fd5..17d6b4a687 100644--- a/src/core/repair/file-drift.ts+++ b/src/core/repair/file-drift.ts@@ -805,6 +805,13 @@ export const fileDriftRepair: RepairHandler = {if (!opts.allDrifted && !opts.held && !selectedByGlobs(live.path, opts)) { count('not_selected'); continue; }const agreedHold = live.reason !== 'agrees' || !live.db_revision ? null : target?.hold?? (source && live.path ? await readGitHold(engine, sourceId, source.incarnation, live.path) : null);+ if (agreedHold?.code === 'file_drift' && live.db_revision && (live.path !== agreedHold.path || !live.file_hash)) {+ count('unknown_release_unproven');+ listing.push({ item: `${sourceId}:${slug}`, class: 'unknown', detail: live.file_hash+ ? `the page agrees with ${live.path}, not with the held file ${agreedHold.path}; the hold stays until that file is resolved`+ : `no file at ${agreedHold.path} to agree with; the hold stays` });+ continue;+ }if (agreedHold?.code === 'file_drift' && live.db_revision) {pages.push({ slug, prefer: opts.prefer, exceptions: [], release_hold: { path: agreedHold.path, incarnation: agreedHold.incarnation, revision: live.db_revision,file_hash: live.file_hash ?? null, observed_at: agreedHold.observed_at } });diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex 5f1cc4981b..a742879f5e 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -490,6 +490,7 @@ test/sync-full-cursor-slices-6349.test.tstest/sync-full-untracked-import-5459.test.tstest/sync-group-member-order.test.tstest/sync-handler-drain-6706.test.ts+test/sync-holds-followups-7974.test.tstest/sync-holds-only-converge-7327.test.tstest/sync-holds-wave-gbra133.test.tstest/sync-import-provenance-disk.test.tsdiff --git a/test/sync-holds-followups-7974.test.ts b/test/sync-holds-followups-7974.test.tsnew file mode 100644index 0000000000..180c64b427--- /dev/null+++ b/test/sync-holds-followups-7974.test.ts@@ -0,0 +1,133 @@+/**+ * #7974: follow-ups from #7909's review of the sync-holds wave.+ *+ * 1. liveFileDrift's stale-mirror branch threw when several spellings of the slug path import as the slug (and none is+ * spelled exactly): every other failure there is still_present null, and the throw aborted the conflict audit.+ * 2. The same branch called a stale mirror page drifted whenever its slug-path file existed, without comparing: an agreeing+ * page was never offered release_hold. It now compares through the reconcile reading.+ * 3. slugPathFile took an exact `<slug>.md` that existsSync found (a symlink, or a case-insensitive match) and always read+ * source-root slugs. It now reads through slugDerivedOrigin in the source's slug-root mode.+ * 4. release_hold was offered when the agreeing file was not the held one; such a page is listed unknown now.+ * 7. A file_drift hold an older gbrain wrote without meta.page_revision reads as moved; its re-screen records the revision,+ * so the next pass is idle again.+ *+ * Holds exist only where sync imports a Git checkout, so there is no repo-less arm.+ */+import { expect, test } from 'bun:test';+import { execFileSync } from 'node:child_process';+import { randomUUID } from 'node:crypto';+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import type { BrainEngine } from '../src/core/engine.ts';+import { RECOVERY_VERSION } from '../src/core/markdown.ts';+import { withCoordinatedWrite } from '../src/core/persistence/context.ts';+import { liveFileDrift } from '../src/core/persistence/drift-conflicts.ts';+import { registerLocalWriter, withVerifiedLocalRegistration } from '../src/core/persistence/identity.ts';+import { readGitHold, writeGitHold } from '../src/core/persistence/sync-holds.ts';+import { movedDriftHolds } from '../src/core/persistence/sync-prescreen.ts';+import { performManagedSync } from '../src/core/persistence/sync-run.ts';+import { slugPathFile } from '../src/core/persistence/unbound-pages.ts';+import { resolveRepairScope } from '../src/core/repair/core.ts';+import { repairRunner } from '../src/core/repair/registry.ts';+import { managedBrain } from './helpers/managed-brain.ts';+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';+import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';++const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, '-c', 'user.name=Example', '-c', '[email protected]',+ '-c', 'commit.gpgsign=false', ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();+const note = (slug: string, body: string) => `---\ntype: concept\ntitle: ${slug}\n---\n\n${body}\n`;+const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: true };+const logger = { info() {}, warn() {}, error() {} };+const commitAll = (root: string, message: string) => { git(root, 'add', '-A'); git(root, 'commit', '-qm', message); };+const coordinated = (engine: BrainEngine, sql: string, params: unknown[] = []) =>+ engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.executeRaw(sql, params), TEST_WRITE_ATTRIBUTION));+const holdRows = async (engine: BrainEngine) => (await engine.executeRaw<{ r: { path: string; code: string; page_id: number | null; meta: { page_revision?: string } } }>(+ "SELECT completed_keys->0 AS r FROM op_checkpoints WHERE op='sync-hold' ORDER BY fingerprint")).map(({ r }) => r);+const incarnation = async (engine: BrainEngine) => (await engine.executeRaw<{ i: string }>("SELECT incarnation::text AS i FROM sources WHERE id='default'"))[0]!.i;+async function heldPreview(engine: BrainEngine, prefer: 'file' | 'database', expectHash?: string) {+ return withVerifiedLocalRegistration(engine, await registerLocalWriter(engine, 'cli'), async () =>+ (await repairRunner(engine, { apply: expectHash !== undefined, logger })).run('file-drift', await resolveRepairScope(engine, 'default'),+ { explicit: true, sourceFlag: 'default', held: true, side: 'unknown', prefer, ...(expectHash ? { expect: expectHash } : {}) }));+}+const listing = (plan: Awaited<ReturnType<typeof heldPreview>>) => (plan as { listing?: Array<{ item: string; class: string }> }).listing?.map(row => `${row.item} ${row.class}`);+const mirrorPage = (engine: BrainEngine, body: string) => coordinated(engine, `INSERT INTO pages(source_id, slug, type, title, compiled_truth, timeline, frontmatter, database_only_reason)+ VALUES('default', 'notes/mirror-page', 'concept', 'notes/mirror-page', $1, '', '{}'::jsonb, 'mirror_read_only')`, [body]);++test('#7974 item 3: slugPathFile never takes a symlink for the slug file, and reads git-root slugs in a Git subfolder source', () => {+ const dir = mkdtempSync(join(tmpdir(), 'slug-path-7974-'));+ try {+ git(dir, 'init', '-q');+ mkdirSync(join(dir, 'sub/notes'), { recursive: true });+ writeFileSync(join(dir, 'outside.md'), note('outside', 'Not this page.'));+ writeFileSync(join(dir, 'sub/HEARTBEAT.md'), note('heartbeat', 'The page.'));+ symlinkSync(join(dir, 'outside.md'), join(dir, 'sub/heartbeat.md'));+ expect(slugPathFile(join(dir, 'sub'), 'heartbeat', 'source-root')).toBe(join(dir, 'sub/HEARTBEAT.md'));+ writeFileSync(join(dir, 'sub/notes/a.md'), note('sub/notes/a', 'Git-root slug.'));+ expect(slugPathFile(join(dir, 'sub'), 'sub/notes/a', 'git-root')).toBe(join(dir, 'sub/notes/a.md'));+ } finally { rmSync(dir, { recursive: true, force: true }); }+});++for (const backend of testBackends()) {+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;+ const setup = ({ root }: { root: string }) => {+ mkdirSync(join(root, 'notes'), { recursive: true }); git(root, 'init', '-q');+ for (const slug of ['notes/n0', 'notes/n1']) writeFileSync(join(root, `${slug}.md`), note(slug, `The committed body of ${slug}.`));+ commitAll(root, 'notes');+ };++ test(`#7974 item 1 [${backend}]: a stale mirror page whose slug path has several spellings is unknown, not a thrown audit`, () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ await mirrorPage(engine, 'The database copy.');+ writeFileSync(join(root, 'notes/Mirror-Page.md'), note('notes/mirror-page', 'One spelling.'));+ writeFileSync(join(root, 'notes/MIRROR-PAGE.md'), note('notes/mirror-page', 'Another spelling.'));+ expect(await liveFileDrift(engine, 'default', 'notes/mirror-page')).toEqual({ still_present: null, reason: 'slug_path_ambiguous' });+ }, { databaseUrl, setup }), 180_000);++ test(`#7974 item 2 [${backend}]: a held stale mirror page that agrees with its slug-path file is listed release_hold, and its apply releases the hold`, () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ await mirrorPage(engine, 'The database copy, written while the source was a mirror.');+ writeFileSync(join(root, 'notes/mirror-page.md'), note('notes/mirror-page', 'The upstream file.')); commitAll(root, 'upstream');+ await performManagedSync(engine, OPTS);+ expect((await holdRows(engine)).map(row => `${row.path} ${row.code}`)).toEqual(['notes/mirror-page.md file_drift']);+ expect(await liveFileDrift(engine, 'default', 'notes/mirror-page')).toMatchObject({ still_present: true, reason: 'file_database_drift', path: 'notes/mirror-page.md' });+ await coordinated(engine, "UPDATE pages SET compiled_truth='The upstream file.', knowledge_revision=$1::uuid WHERE source_id='default' AND slug='notes/mirror-page'", [randomUUID()]);+ expect(await liveFileDrift(engine, 'default', 'notes/mirror-page')).toMatchObject({ still_present: false, reason: 'agrees', path: 'notes/mirror-page.md' });+ const preview = await heldPreview(engine, 'database');+ expect(listing(preview)).toEqual(['default:notes/mirror-page release_hold']);+ expect((await heldPreview(engine, 'database', preview.preview_hash!)).outcomes).toEqual({ repaired: 1 });+ await performManagedSync(engine, OPTS);+ expect(await holdRows(engine)).toEqual([]);+ }, { databaseUrl, setup }), 180_000);++ test(`#7974 item 4 [${backend}]: a held path whose page agrees with another file is listed unknown, not release_hold`, () => managedBrain(async ({ engine }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ const [page] = await engine.executeRaw<{ id: number; revision: string }>("SELECT id, knowledge_revision::text AS revision FROM pages WHERE source_id='default' AND slug='notes/n1'");+ const inc = await incarnation(engine);+ await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation: inc, path: 'notes/n1-twin.md', source_path: 'notes/n1-twin.md',+ slug: 'notes/n1', page_id: Number(page!.id), code: 'file_drift', message: 'notes/n1-twin.md is held: file drift (unknown)', upstream_version: null,+ observed_at: new Date().toISOString(), run_id: null, mode: 'managed', meta: { recovery_version: RECOVERY_VERSION, side: 'unknown', page_revision: page!.revision } }));+ expect(listing(await heldPreview(engine, 'file'))).toEqual(['default:notes/n1 unknown']);+ }, { databaseUrl, setup }), 180_000);++ test(`#7974 item 7 [${backend}]: an older hold with no recorded page revision is re-screened once, records the revision, and the next pass is idle`, () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ await coordinated(engine, `DELETE FROM op_checkpoints WHERE op='sync-import-provenance'+ AND completed_keys->0->>'page_id' IN (SELECT id::text FROM pages WHERE source_id='default' AND slug='notes/n0')`);+ await coordinated(engine, `UPDATE pages SET source_path=NULL, compiled_truth='A stub.', knowledge_revision=$1::uuid, revision_write_request_id=NULL+ WHERE source_id='default' AND slug='notes/n0'`, [randomUUID()]);+ writeFileSync(join(root, 'notes/n0.md'), note('notes/n0', 'The edited body of notes/n0.')); commitAll(root, 'edit n0');+ await performManagedSync(engine, OPTS);+ const [held] = await holdRows(engine);+ expect(held).toMatchObject({ path: 'notes/n0.md', code: 'file_drift' });+ expect(held!.meta.page_revision).toBeString();+ await engine.executeRaw(`UPDATE op_checkpoints SET completed_keys=jsonb_set(completed_keys,'{0,meta}',(completed_keys->0->'meta') - 'page_revision') WHERE op='sync-hold'`);+ expect([...await movedDriftHolds(engine, 'default', await holdRows(engine))]).toEqual(['notes/n0.md']);+ await performManagedSync(engine, OPTS);+ const [again] = await holdRows(engine);+ expect(again).toMatchObject({ path: 'notes/n0.md', code: 'file_drift', meta: { page_revision: held!.meta.page_revision } });+ expect([...await movedDriftHolds(engine, 'default', await holdRows(engine))]).toEqual([]);+ expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');+ expect(await readGitHold(engine, 'default', await incarnation(engine), 'notes/n0.md')).not.toBeNull();+ }, { databaseUrl, setup }), 180_000);+}