Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(sync): re-screen older record-less drift holds against earlier versions; held_needs_human on the run; file_drift_unknown verdict (#7199, re-port of #7228)

garrytan9054da87f183
diff --git a/docs/guides/live-sync.md b/docs/guides/live-sync.md
index f532f585b0..cb90d2c807 100644
--- a/docs/guides/live-sync.md
+++ b/docs/guides/live-sync.md
@@ -102,7 +102,7 @@ The run ends in exactly one outcome:
| Outcome | Exit | Meaning | What to do |
| --- | --- | --- | --- |
-| `synced` | 0 | The pass converged and stamped (a company-brain source: the cursor reached its target). A pass at a selection other than the configured one adds `selection_scoped` and does not advance `last_commit`. | Nothing. |
+| `synced` | 0 | The pass converged and stamped (a company-brain source: the cursor reached its target). A pass at a selection other than the configured one adds `selection_scoped` and does not advance `last_commit`; a pass that held files a person must decide adds `held_needs_human` (their count in `held_needs_human`). | Nothing; held files wait on a person (`gbrain sync status --source <id>`). |
| `resumable` | 0 | A deadline, `--timeout` or Ctrl-C stopped it; accepted writes are intact. | Rerun `next.command`; safe in a loop. |
| `resumable` / `not_converged` | 0 | The pass used its four rounds while another writer kept changing the level; everything it admitted stands. | Rerun `next.command`. After three in a row `next` is a report (`gbrain doctor --json`), not another sync. |
| `resumable` / `admission_paused` | 0 | `sync.admission` is `imports_only` or `classify_only`. | Ask the user; `gbrain config set sync.admission normal` ends the pause. |
diff --git a/docs/guides/sync-unblock-runbook.md b/docs/guides/sync-unblock-runbook.md
index c9025269a9..cd4231ab8e 100644
--- a/docs/guides/sync-unblock-runbook.md
+++ b/docs/guides/sync-unblock-runbook.md
@@ -157,6 +157,7 @@ Every hold and error has three fields, from one table
| `origin_conflict` | page | repair | no | the hold carries a reason (the pages differ, ids conflict or none is the page the path names), or the heal is off |
| `rename_identity_unreadable` | page | none | yes | always: the file title or id holds characters the database cannot compare |
| `rename_reconcile_failed` | page | none | yes | always: the old page may be a duplicate |
+| `file_drift_unknown` | page | reconcile | yes | always: the file and the page differ and no import record says which changed |
| `origin_conflict_decision` | page | none | yes | always: the pages differ, their ids conflict or none is the page the path names |
| `page_identity_decision` | page | none | yes | always: only a person decides which page the file is |
| `absent_from_worktree` | page | none | yes | always: only a person decides whether the file comes back or its deletion is committed |
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index d80fca694b..4be863245a 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 1572 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
diff --git a/src/commands/sync-diagnostics.ts b/src/commands/sync-diagnostics.ts
index f986075e85..03c12ca446 100644
--- a/src/commands/sync-diagnostics.ts
+++ b/src/commands/sync-diagnostics.ts
@@ -28,6 +28,9 @@ export function printHoldNotes(result: SyncResult, write: (line: string) => void
if (result.would_hold_count > HOLD_LINES) write(` ... and ${result.would_hold_count - HOLD_LINES} more would be held (--json lists them).`);
}
for (const skipped of (result.screen_skipped ?? []).slice(0, HOLD_LINES)) write(` Screen skipped ${skipped.path}: ${skipped.code} (not a content problem; the real sync reports it).`);
+ // #7199: the source synced, and files held this run wait on a person; the hold fix's verify step names the source.
+ const source = result.holds_fix?.verify?.argv?.[3];
+ if (result.reason === 'held_needs_human' && source) write(`Synced; ${result.held_needs_human} file(s) held for a person (gbrain sync status --source ${source}).`);
for (const item of (result.held ?? []).slice(0, HOLD_LINES)) write(holdLine(item, 'Held'));
const shown = Math.min(result.held?.length ?? 0, HOLD_LINES);
if ((result.held_count ?? 0) > shown) write(` ... and ${(result.held_count ?? 0) - shown} more held this run (--json lists ${result.holds_truncated ? 'the first ones' : 'them all'}).`);
diff --git a/src/commands/sync.ts b/src/commands/sync.ts
index e59571475b..540a4e8c2b 100644
--- a/src/commands/sync.ts
+++ b/src/commands/sync.ts
@@ -135,12 +135,12 @@ export interface SyncResult {
connectorHolds?: { held: number; newly_held: number; retry_command: string; status_command: string };
/**
* #5988 Git holds: files held this run instead of blocking (detail capped at
- * `GBRAIN_SYNC_HOLD_CAP`), their count, the source's outstanding total and the
+ * `GBRAIN_SYNC_HOLD_CAP`), their count (#7199: how many wait on a person), the source's outstanding total and the
* exact inspect and repair commands. Remote callers get `held_count` and
* `holds_fix` (a host-operator relay) only.
*/
held?: import('../core/persistence/sync-holds.ts').GitHoldItem[];
- held_count?: number;
+ held_count?: number; held_needs_human?: number;
holds_outstanding?: number;
holds_escalated?: boolean;
holds_truncated?: boolean;
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index a834798000..7dc7bb8de2 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1372,6 +1372,8 @@ 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.' },
+ // #7199 (re-port of #7228). since is stamped at the merge slot.
+ { since: '0.60.516.0', id: 'classic_drift_rescreen_7199', text: 'A `file_drift` hold with side `unknown` that an older gbrain wrote before sync compared a record-less page with its file at the last synced commit is now compared once more, also with the file\'s last three earlier committed versions, and imports when the page equals one of them; otherwise it stays held and is not re-screened again. Such a hold now names what the page was compared with, and `gbrain sync status` lists it under its own verdict (`file_drift_unknown`, needs a person). A managed sync that holds files a person must decide now reports `reason: held_needs_human` with `held_needs_human: <count>` (JSON) and prints `Synced; N file(s) held for a person (gbrain sync status --source <id>).`; the source still syncs and its status stays `synced`.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/persistence/public-category.ts b/src/core/persistence/public-category.ts
index 967856df29..c60d6aacb7 100644
--- a/src/core/persistence/public-category.ts
+++ b/src/core/persistence/public-category.ts
@@ -33,7 +33,7 @@ export const PUBLIC_BY_TERMINAL: Readonly<Record<TerminalCategory, PublicCategor
/** Fault codes (holds, run stops, receipts) by name; a test pins that every `SYNC_FAULT_TABLE` code is here. */
export const PUBLIC_BY_CODE: Readonly<Record<string, PublicCategory>> = {
- worktree_dirty: 'drift', file_drift: 'drift', source_changed: 'drift', pinned_git_worktree_conflict: 'drift',
+ worktree_dirty: 'drift', file_drift: 'drift', file_drift_unknown: 'drift', source_changed: 'drift', pinned_git_worktree_conflict: 'drift',
concurrent_write: 'conflict', revision_conflict: 'conflict', page_identity_changed: 'conflict', legacy_slug_conflict: 'conflict', origin_conflict: 'conflict', origin_conflict_decision: 'conflict', page_identity_decision: 'conflict',
settle_mismatch: 'defect', page_write_failed: 'defect',
invalid_fence: 'content_refused', invalid_frontmatter: 'content_refused', frontmatter_slug_conflict: 'content_refused', rename_held: 'content_refused',
diff --git a/src/core/persistence/sync-classify.ts b/src/core/persistence/sync-classify.ts
index e08cf29392..8614341676 100644
--- a/src/core/persistence/sync-classify.ts
+++ b/src/core/persistence/sync-classify.ts
@@ -57,8 +57,11 @@ export interface SyncPathState {
levelSha256: string | null;
/** `published`: the disk bytes hash to the attested publication's `expected_hash`, or the disk is absent after a deleting publication. */
published: boolean;
- /** An active hold at `p`: whether it is at level `L` in its own domain, re-screen due, or in the retry set. */
- hold: { atLevel: boolean; rescreenDue: boolean; retried: boolean } | null;
+ /**
+ * An active hold at `p`: whether it is at level `L` in its own domain, re-screen due, or in the retry set. #7199 `unscreened`:
+ * a side-`unknown` drift hold an older gbrain wrote before the drift screen compared the page with the file at the baseline commit.
+ */
+ hold: { atLevel: boolean; rescreenDue: boolean; retried: boolean; unscreened?: boolean } | null;
/**
* A deletion marker at the origin: `deleted` (with the blob ids it held) or `legacy` (the baseline blob of a page deleted
* before PR 4; `deletion` is the committed deleting request that proves it, and a legacy marker without one settles nothing).
@@ -211,7 +214,8 @@ function afterHold(s: SyncPathState): Matched {
}
}
if ((!fileSame && proof && live) || !live) return { cls: 'import', settled: false, action: 'import' };
- if (live && s.record?.revision == null && s.level !== null && s.level === s.baseline) return { cls: 'legacy_unverified', settled: true, action: 'none' };
+ // #7199: an older side-`unknown` hold's pass moved the baseline to its own level, so its one re-screen runs as drift.
+ if (live && s.record?.revision == null && s.level !== null && s.level === s.baseline && !s.hold?.unscreened) return { cls: 'legacy_unverified', settled: true, action: 'none' };
if (live && s.keepDb && s.mode === 'committed' && s.dirty === 'clean') return { cls: 'keep_db', settled: false, action: 'keep_db' };
return { cls: 'drift', settled: false, action: 'hold', side: s.record?.revision != null ? 'both' : 'unknown' };
}
diff --git a/src/core/persistence/sync-discovery.ts b/src/core/persistence/sync-discovery.ts
index a493df9cff..288837691b 100644
--- a/src/core/persistence/sync-discovery.ts
+++ b/src/core/persistence/sync-discovery.ts
@@ -59,6 +59,8 @@ export interface SyncEntry { path: string; sourcePath: string; action: 'import'
drift?: SyncDriftSide;
/** #6712: for `both`, the blob the last recorded import left on disk; #7338: for `unknown`, the file at the baseline commit. The freeze imports when the page still holds what that blob imports. */
driftBaseline?: string;
+ /** #7199: for an older side-`unknown` hold, the file's earlier committed blobs; the freeze imports when the page still holds what one imports. */
+ driftHistory?: string[];
/** #6727: live pages with no recorded origin whose slugs fold to this file's slug, several or one the importer cannot write; the freeze holds it `legacy_slug_conflict`. */
legacySlugs?: string[];
/** #6729 x #6727: the one legacy page carries an explicit frontmatter id that differs from the file's, so it is another document; held `legacy_slug_conflict` (`explicit_id_conflict`). */
diff --git a/src/core/persistence/sync-fault-class.ts b/src/core/persistence/sync-fault-class.ts
index c58d0313d6..7bede4a9b6 100644
--- a/src/core/persistence/sync-fault-class.ts
+++ b/src/core/persistence/sync-fault-class.ts
@@ -115,6 +115,9 @@ export const SYNC_FAULT_TABLE: ReadonlyArray<SyncFaultRule> = [
human_reason: 'The database refused to compare this renamed file title or frontmatter id; a person removes the NUL byte or broken Unicode character from the file and commits, then syncs.' },
{ code: 'rename_reconcile_failed', class: 'page', safe_actions: ['none'], needs_human: true, escalate: 'always: the old page may be a duplicate',
human_reason: 'A rename imported but the old page could not be removed; a person runs a full sync of the source (it removes pages whose file is gone) or removes the old page with gbrain delete.' },
+ // #7199: a `file_drift` hold with side `unknown` (no import record): neither side is known to have moved.
+ { code: 'file_drift_unknown', class: 'page', safe_actions: ['reconcile'], needs_human: true, escalate: 'always: the file and the page differ and no import record says which changed',
+ human_reason: 'The file and the database page differ, and sync has no import record to tell which one changed since the last import, so it held the file instead of overwriting the page; a person chooses which version wins (gbrain repair file-drift --source <source> --slug <slug> --prefer database|file previews it and writes nothing until applied).' },
{ code: 'origin_conflict_decision', class: 'page', safe_actions: ['none'], needs_human: true, escalate: 'always: the pages differ, their ids conflict or none is the page the path names',
human_reason: 'Several live pages record this file as their origin and sync cannot prove they are one document; a person keeps the page that is the file\'s and soft-deletes the others (gbrain repair origin-twins --source <source> lists them with the commands), then syncs.' },
// GBRA-130 A-17/B-3/B-4: a held `page_identity_changed` path (sync-status.ts holdVerdict): several tombstones, a spelling twin or a takeover whose ids differ.
diff --git a/src/core/persistence/sync-git-stream.ts b/src/core/persistence/sync-git-stream.ts
index 3c0341e98d..8bac17e23d 100644
--- a/src/core/persistence/sync-git-stream.ts
+++ b/src/core/persistence/sync-git-stream.ts
@@ -240,6 +240,35 @@ export async function readRenameHints(gitRoot: string, from: string, to: string)
return hints.sort((a, b) => (a.to < b.to ? -1 : a.to > b.to ? 1 : 0));
}
+/**
+ * #7199: the blob ids `path` had at `commit` and its first `depth - 1` first-parent ancestors, newest first, one
+ * per commit that has the path (one `cat-file --batch` of `<commit>~k:<path>` specs; bodies are read past, never kept).
+ * Empty for a path a spec line cannot carry.
+ */
+export async function pathBlobHistory(gitRoot: string, commit: string, path: string, depth: number): Promise<string[]> {
+ if (!OID.test(commit) || /[\n\r]/.test(path) || depth < 1) return [];
+ const oids: string[] = [];
+ let header: Buffer[] = [], skip = 0, answered = 0;
+ const result = await gitStream(gitRoot, ['cat-file', '--batch'], { timeoutMs: READ_TIMEOUT_MS,
+ stdin: lines(Array.from({ length: depth }, (_, k) => `${commit}~${k}:${path}`), '\n'), onChunk: chunk => {
+ let at = 0;
+ while (at < chunk.length) {
+ if (skip) { const take = Math.min(skip, chunk.length - at); skip -= take; at += take; continue; }
+ const newline = chunk.indexOf(10, at);
+ if (newline < 0) { header.push(chunk.subarray(at)); break; }
+ const line = Buffer.concat([...header, chunk.subarray(at, newline)]).toString('utf8');
+ header = []; at = newline + 1; answered += 1;
+ if (line.endsWith(' missing') || line.endsWith(' ambiguous')) continue;
+ const [oid = '', type = '', size = ''] = line.split(' ');
+ if (!OID.test(oid) || !/^\d+$/.test(size)) throw malformed('cat-file', line);
+ if (type === 'blob') oids.push(oid);
+ skip = Number(size) + 1;
+ }
+ } });
+ if (!result.ok || skip || header.length || answered !== depth) throw new SyncTreeReadIncomplete('cat-file', result.ok ? `${answered} of ${depth} specs answered` : outcome(result));
+ return oids;
+}
+
/**
* Blob contents by OID through one `cat-file --batch`. A blob over `maxBytes`,
* a non-blob, a missing object, or one that would pass `maxTotalBytes` is left
diff --git a/src/core/persistence/sync-holds.ts b/src/core/persistence/sync-holds.ts
index 523f8a8ca4..bbf11438b9 100644
--- a/src/core/persistence/sync-holds.ts
+++ b/src/core/persistence/sync-holds.ts
@@ -1312,8 +1312,8 @@ export function fencesNormalizedReport(sourceId: string, tally: FencesTally | un
* commands. Remote callers get the counts and a relay instruction only.
*/
export async function buildHoldReport(engine: Exec, input: { sourceId: string; incarnation: string; runId: string; remote: boolean;
- policy: SyncHoldPolicy | Promise<SyncHoldPolicy>; screened: number; pendingScreen?: boolean }): Promise<Pick<import('../../commands/sync.ts').SyncResult,
- 'held' | 'held_count' | 'holds_outstanding' | 'holds_escalated' | 'holds_truncated' | 'holds_pending_screen' | 'holds_fix'>> {
+ policy: SyncHoldPolicy | Promise<SyncHoldPolicy>; screened: number; pendingScreen?: boolean; needsHuman?: (record: GitHoldRecord, auto: FenceAutoRepair | undefined) => boolean }): Promise<Pick<import('../../commands/sync.ts').SyncResult,
+ 'held' | 'held_count' | 'held_needs_human' | 'holds_outstanding' | 'holds_escalated' | 'holds_truncated' | 'holds_pending_screen' | 'holds_fix'>> {
// #6712 PR 4b: the summary, this run's holds and the policy (a caller may pass its read in flight) in one round trip.
const [[summary], sourceHolds, policy] = await Promise.all([engine.executeRaw<{ count: number | string; images: number | string; fences: number | string; stalled: number | string; concurrent: number | string; dirty: number | string; drift: number | string }>(`SELECT COALESCE((completed_keys->0->>'count')::int,0) AS count,
COALESCE((completed_keys->0->>'drift')::int,0) AS drift,
@@ -1334,6 +1334,8 @@ export async function buildHoldReport(engine: Exec, input: { sourceId: string; i
// #6377: this run's slug-conflict holds route to the content lane; earlier runs' stay in `others` (the summary does not count them).
const slugConflicts = runHolds.filter(hold => hold.code === 'frontmatter_slug_conflict').length;
const auto = fences ? await readFenceAutoRepair(engine) : undefined;
+ // #7199: this run's holds whose verdict waits on a person (sync-status.ts holdVerdict).
+ const needsHuman = input.needsHuman ? runHolds.filter(hold => input.needsHuman!(hold, auto)).length : 0;
const steps = holdRepairSteps(input.sourceId, { fences, others: Math.max(0, outstanding - fences - stalled - concurrent - dirty - drift - slugConflicts), ...(stalled ? { stalled } : {}),
...(concurrent ? { concurrent } : {}), ...(dirty ? { dirty } : {}), ...(drift ? { drift } : {}), ...(slugConflicts ? { slug_conflicts: slugConflicts } : {}) }, auto);
// #6278: the escalation text is routed by code: stalled holds point at the writer, not at a generator.
@@ -1342,14 +1344,14 @@ export async function buildHoldReport(engine: Exec, input: { sourceId: string; i
? ' Escalated: more files are held than a source should carry, and most of them stalled while preparing, so the write owner (not the files) is the likely cause; inspect it with writer status before the backlog grows.'
: ' Escalated: more files are held than a source should carry, so a generator or a gbrain upgrade is likely writing or reading them wrong; fix the cause before the backlog grows.';
const verify = { argv: ['gbrain', 'sources', 'status', input.sourceId, '--json'] };
- if (input.remote) return { held_count: runHolds.length, holds_fix: { argv: steps.argv, consent: [], actor: 'host_admin', requires_exclusive: false, verify,
+ if (input.remote) return { held_count: runHolds.length, ...(needsHuman ? { held_needs_human: needsHuman } : {}), holds_fix: { argv: steps.argv, consent: [], actor: 'host_admin', requires_exclusive: false, verify,
why: `${outstanding} file(s) in source ${input.sourceId} are held and not imported; only the brain host can inspect and repair them.`,
user_message: `Some files in source ${input.sourceId} could not be imported. Please run 'gbrain sources status ${input.sourceId}' on the brain host, then: ${steps.text}.` } };
const fix: Action = { argv: steps.argv, consent: [], actor: 'agent', requires_exclusive: false, verify,
why: `${runHolds.length} file(s) held this run, ${outstanding} held in source ${input.sourceId}; they do not block sync. Inspect them with 'gbrain sources status ${input.sourceId}'; `
+ (fences || stalled || concurrent || dirty || drift || slugConflicts ? `then ${steps.text}.` : 'the repair preview proposes each fix and writes nothing.')
+ (escalated ? escalation : '') };
- return { held: runHolds.slice(0, policy.cap).map(hold => gitHoldItem(hold, auto)), held_count: runHolds.length, holds_outstanding: outstanding,
+ return { held: runHolds.slice(0, policy.cap).map(hold => gitHoldItem(hold, auto)), held_count: runHolds.length, ...(needsHuman ? { held_needs_human: needsHuman } : {}), holds_outstanding: outstanding,
...(escalated ? { holds_escalated: true } : {}), ...(runHolds.length > policy.cap ? { holds_truncated: true } : {}),
...(input.pendingScreen ? { holds_pending_screen: true } : {}), holds_fix: fix };
}
@@ -1357,7 +1359,7 @@ export async function buildHoldReport(engine: Exec, input: { sourceId: string; i
/** The hold fields as the sync JSON envelopes carry them (snake_case already). */
export function syncHoldJsonFields(result: object): Record<string, unknown> {
const fields = result as Record<string, unknown>;
- return Object.fromEntries(['held', 'held_count', 'holds_outstanding', 'holds_escalated', 'holds_truncated', 'holds_pending_screen', 'holds_fix',
+ return Object.fromEntries(['held', 'held_count', 'held_needs_human', 'holds_outstanding', 'holds_escalated', 'holds_truncated', 'holds_pending_screen', 'holds_fix',
'converted_from_failed', 'recovered_frontmatter', 'fences_normalized', 'fence_issues', 'dry_run', 'would_hold', 'would_hold_count', 'would_normalize', 'would_normalize_count', 'screen_skipped', 'breaker', 'slug_lines_removed']
.filter(key => fields[key] !== undefined).map(key => [key, fields[key]]));
}
diff --git a/src/core/persistence/sync-page-fault.ts b/src/core/persistence/sync-page-fault.ts
index 9f07b49a87..47b54d652e 100644
--- a/src/core/persistence/sync-page-fault.ts
+++ b/src/core/persistence/sync-page-fault.ts
@@ -145,12 +145,13 @@ function base(entry: HoldEntry, slug: string, pageId: number | null, code: 'conc
* page revision changes.
*/
export function fileDriftHold(entry: HoldEntry, slug: string, pageId: number | null, intent: Pick<SyncIntent, 'content' | 'blobOid'>,
- observed: { sides: 'database' | 'both' | 'unknown'; revision: string | null; proof: PageChangeProof | null; sharedOrigin: boolean }): HeldEntry {
+ observed: { sides: 'database' | 'both' | 'unknown'; revision: string | null; proof: PageChangeProof | null; sharedOrigin: boolean; baseline?: string | null }): HeldEntry {
const by = observed.proof ? `${observed.proof.operation} request ${observed.proof.request_id} wrote page ${slug} straight to the database` : `page ${slug} changed in the database`;
const file = observed.sides === 'database' ? 'its file did not change in Git' : 'its file changed too';
// GBRA-133: with no import record and no database write on record, nothing shows the database side changed.
+ // #7199: the hold also names what the page was compared with: the file at the last synced commit, or that commit had no file.
const held = observed.sides === 'unknown' && !observed.proof
- ? `page ${slug} differs from its file and has no import record to tell whether the file or the database changed`
+ ? `page ${slug} differs from its file and has no import record to tell whether the file or the database changed; the page also ${observed.baseline ? 'differs from the file at the last synced commit' : 'has no file at the last synced commit to compare with'}`
: `${by} since the file was last imported and ${observed.sides === 'unknown' ? 'there is no import record to tell whether the file changed too' : file}`;
return base(entry, slug, pageId, 'file_drift',
`${entry.path}: ${held}, so sync held the import instead of overwriting the database version; the rest of the source synced.`,
diff --git a/src/core/persistence/sync-pass-row.ts b/src/core/persistence/sync-pass-row.ts
index da23cd26a1..fdc13cd0a7 100644
--- a/src/core/persistence/sync-pass-row.ts
+++ b/src/core/persistence/sync-pass-row.ts
@@ -26,7 +26,9 @@ export const SYNC_PASS_ROW_OPS = [MANAGED_SYNC_PASS_OP, SYNC_ORIGIN_DELETED_OP,
export type PassOutcome = 'open' | 'synced' | 'up_to_date' | 'resumable' | 'blocked';
export type PassKind = 'idle' | 'hold_only' | 'full';
/** #6712 PR 4b (design v3.2 §9): a live pass's `SyncResult.reason` endings. `selection_scoped` rides a converged scoped pass (`synced`). */
-export type PassResultReason = 'not_converged' | 'admission_paused' | 'reconcile_host_required' | 'grant_scope' | 'reconcile_read_incomplete' | 'selection_scoped';
+export type PassResultReason = 'not_converged' | 'admission_paused' | 'reconcile_host_required' | 'grant_scope' | 'reconcile_read_incomplete' | 'selection_scoped'
+ /** #7199: the pass synced and held files a person must decide (`held_needs_human` counts them). */
+ | 'held_needs_human';
/** #6712 PR 4b: `SyncResult.pass`, the live pass that produced a sync result (non-company managed sources; sync-pass-run.ts). */
export interface PassResultSummary { pass_id: string; kind: PassKind; round: number; outcome: string; stop_reason: string | null; candidates: number; settled: number;
remaining: number; not_converged_streak: number }
diff --git a/src/core/persistence/sync-pass-run.ts b/src/core/persistence/sync-pass-run.ts
index 1fd45ff4cf..76ee3019ee 100644
--- a/src/core/persistence/sync-pass-run.ts
+++ b/src/core/persistence/sync-pass-run.ts
@@ -35,7 +35,7 @@ import { passFoldBase, passIdleProbe, readShadowLevel, workingIdleChange, type P
import { ownWritebackCommit, type PassFold } from './sync-pass-fold.ts';
import { openPassRequests, settleCarried } from './sync-pass-carried.ts';
import { loopYield } from './sync-yield.ts';
-import { recallWorkingStatCache, rememberWorkingStatCache, SyncTreeReadIncomplete } from './sync-git-stream.ts';
+import { pathBlobHistory, recallWorkingStatCache, rememberWorkingStatCache, SyncTreeReadIncomplete } from './sync-git-stream.ts';
import { syncPassKind } from './sync-classify.ts';
import { PASS_BATCH_KEY_PREFIX, readConvergedWatermark, SyncAdmissionPaused, type PassEntry } from './sync-pass-batch.ts';
import { assertDrainLease, currentDrainLease } from './sync-lease.ts';
@@ -75,6 +75,8 @@ export const PASS_BATCH_MAX = 10_000;
const IN_FLIGHT_WAITS = 4;
/** #7355: how often a long level read writes the open pass row, so a follower and `sync status` see it working. */
const PASS_HEARTBEAT_MS = 30_000;
+/** #7199: how far back (first-parent commits) an older side-`unknown` hold's re-screen looks, and how many earlier versions it compares. */
+const DRIFT_HISTORY_DEPTH = 50, DRIFT_HISTORY_VERSIONS = 3;
export interface SyncPassInput {
opts: SyncOpts; slice?: { maxPages: number; maxMs: number }; context: ManagedSyncContext; authority: SyncAuthority;
@@ -202,12 +204,19 @@ async function batchEntries(engine: BrainEngine, level: ShadowLevel, deletes: Sh
// #7338: a page with no import record (imported by an older gbrain) has its file at the incarnation's baseline commit as its baseline.
const driftBaseline = (entry: ShadowPath) => entry.pageId === null ? undefined : entry.result.side === 'both' ? baselineRecords.get(entry.pageId)?.disk_blob_oid ?? undefined
: entry.result.side === 'unknown' ? entry.state.baseline ?? undefined : undefined;
+ // #7199: a side-`unknown` hold an older gbrain wrote after the pass that held it moved the source's last commit past the one
+ // the classic sync read; its re-screen also compares the page with the file's last few committed versions before the held one.
+ const history = new Map<string, string[]>();
+ for (const entry of imports) if (entry.result.side === 'unknown' && entry.pageId !== null && entry.state.hold?.unscreened) {
+ const earlier = await pathBlobHistory(level.gitRoot, level.baselineCommit ?? level.head, entry.path, DRIFT_HISTORY_DEPTH).catch(() => []);
+ history.set(entry.path, [...new Set(earlier)].filter(oid => oid !== entry.state.level && oid !== entry.state.baseline).slice(0, DRIFT_HISTORY_VERSIONS));
+ }
const entries: PassEntry[] = [], collisions: SyncSlugCollision[] = [], skipped: ShadowPath[] = [], identity: Array<{ entry: ShadowPath; origin: ShadowPath | null; slug: string; ids: { page: string; file: string } }> = [];
const claims = new Map<string, ShadowPath[]>();
for (const entry of imports) {
if (step.due()) await step.pause();
const paths = entryPaths(level, entry.path);
- const base = { ...paths, ...committedOnly, action: 'import' as const, working: working(entry), level: entry.state.level, ...(entry.result.cls === 'drift' && entry.result.side && entry.result.side !== 'deleted' ? { drift: entry.result.side, ...(driftBaseline(entry) ? { driftBaseline: driftBaseline(entry) } : {}) } : {}) };
+ const base = { ...paths, ...committedOnly, action: 'import' as const, working: working(entry), level: entry.state.level, ...(entry.result.cls === 'drift' && entry.result.side && entry.result.side !== 'deleted' ? { drift: entry.result.side, ...(driftBaseline(entry) ? { driftBaseline: driftBaseline(entry) } : {}), ...(history.get(entry.path)?.length ? { driftHistory: history.get(entry.path) } : {}) } : {}) };
if (entry.state.page) { entries.push({ ...base, slug: entry.slug!, pageId: entry.pageId, revision: entry.revision }); continue; }
const slug = slugOf.get(entry.path);
if (!slug) { skipped.push(entry); continue; }
diff --git a/src/core/persistence/sync-pass.ts b/src/core/persistence/sync-pass.ts
index 1073068c19..26ba9662e8 100644
--- a/src/core/persistence/sync-pass.ts
+++ b/src/core/persistence/sync-pass.ts
@@ -32,7 +32,7 @@ import { sourceMirrorReadOnly } from './mirror-read-only.ts';
import { colonFileRefusal, COLON_REFUSAL_MESSAGES, readSyncFile, resolveManagedSyncContext, syncExcludePatterns, syncGitAsync, type ManagedSyncContext, type SyncFileRefusal } from './sync-discovery.ts';
import { isWindowsColonTarget } from './native-file-target.ts';
import { confirmedSyncDelta } from '../sync-rename-identity.ts';
-import { fileDriftSide, holdBasisMoved, holdRescreenDue, type DeletionCandidate, readGitHoldRetryPaths, readGitSourceHolds, SYNC_IMPORT_PROVENANCE_OP, syncImportParser, syncImportParsers,
+import { FILE_DRIFT_VERSION, fileDriftSide, holdBasisMoved, holdRescreenDue, type DeletionCandidate, readGitHoldRetryPaths, readGitSourceHolds, SYNC_IMPORT_PROVENANCE_OP, syncImportParser, syncImportParsers,
type GitHoldRecord, type SyncImportParser, type SyncImportProvenance } from './sync-holds.ts';
import { movedDriftHolds, sameParser } from './sync-prescreen.ts';
import { sameSyncOrigin, selectOriginClaimant, syncOriginPath, type SyncOriginScope } from './sync-origin.ts';
@@ -804,7 +804,7 @@ export async function readShadowLevel(engine: BrainEngine, input: { sourceId: st
record: record ? { blobOids: recordBlobOids, revision: recordRevision != null ? String(recordRevision) : null, parserSame: sameParser(pages.parserOf(at!), fp(path)) } : null,
attested, levelSha256: probe?.rawSha256 ?? null,
published: !!attested?.hash && probe?.rawSha256 === attested.hash,
- hold: hold ? { atLevel: holdAtLevel(hold, level, probe?.rawSha256 ?? null) && !moved.has(path), rescreenDue: holdRescreenDue(hold, retry.has(hold.path)), retried: retry.has(hold.path) } : null,
+ hold: hold ? { atLevel: holdAtLevel(hold, level, probe?.rawSha256 ?? null) && !moved.has(path), rescreenDue: holdRescreenDue(hold, retry.has(hold.path)), retried: retry.has(hold.path), ...(unscreenedDrift(hold) ? { unscreened: true } : {}) } : null,
marker: marker ?? virtualMarker, baseline: needsBaseline ? baselineOf(path) : null,
spelling: legacySpelling.has(path) ? 'legacy' : twins.has(path),
episodeUnsatisfied: input.pass ? !!input.pass.episodeFullId && live && (record ? pages.fullEpisode[at!] : undefined) !== input.pass.episodeFullId
@@ -1187,6 +1187,13 @@ function readPresent(root: string, gitPath: string, scope: string): boolean {
try { return readSyncFile(root, path) !== null; } catch { return true; }
}
+/**
+ * #7199: a side-`unknown` drift hold written before the drift screen compared the page with the file at the baseline commit
+ * (`drift_version` below FILE_DRIFT_VERSION). The pass that wrote it moved the baseline to the held file, so its one re-screen
+ * (sync-holds.ts holdRescreenDue) also compares the page with the file's earlier committed versions.
+ */
+const unscreenedDrift = (hold: GitHoldRecord) => hold.code === 'file_drift' && fileDriftSide(hold.meta) === 'unknown' && (hold.meta.drift_version ?? 0) < FILE_DRIFT_VERSION;
+
/** Whether a hold still describes the path at level `L`, in the hold's own domain (a pinned blob, working bytes, or a deletion). */
function holdAtLevel(hold: GitHoldRecord, level: string | null, diskSha256: string | null): boolean {
if (hold.meta.deleted) return level === null;
diff --git a/src/core/persistence/sync-run.ts b/src/core/persistence/sync-run.ts
index 94b59b0e42..9b0cf2cb7e 100644
--- a/src/core/persistence/sync-run.ts
+++ b/src/core/persistence/sync-run.ts
@@ -46,7 +46,7 @@ import { managedSyncResumeArgs } from '../sync-reconcile.ts';
import { laneApplyMsPerMember, lanePolicy, openLanes } from './sync-lanes.ts';
import { SYNC_READ_BOUND, type TreeBlob } from './sync-blobs.ts';
import { readDryRunWriterState } from './sync-dry-run-writer.ts';
-import { driftBaselineContent, dryRunScreen, heldImageEntry, isSyncReadBound, loadSyncScreenRun, originConflictHold, oversizeHold, pinnedBlob, pinnedContent, pinnedImageBytes, preparationStalledHold, prepareTimeFenceHold, screenFrozenImport, streamedRefusalHold, unreadableFileHold, type HeldEntry, type SyncScreenRun } from './sync-screen.ts';
+import { pageHoldsDriftBaseline, dryRunScreen, heldImageEntry, isSyncReadBound, loadSyncScreenRun, originConflictHold, oversizeHold, pinnedBlob, pinnedContent, pinnedImageBytes, preparationStalledHold, prepareTimeFenceHold, screenFrozenImport, streamedRefusalHold, unreadableFileHold, type HeldEntry, type SyncScreenRun } from './sync-screen.ts';
import { frozenImageIntent, sameImageBytes } from './sync-image.ts';
import { fenceReceiptLocation } from '../fence-repair/refusal.ts';
import { managedSyncWriteDiagnostic, writeWaitOf } from './sync-write-diagnostic.ts';
@@ -466,10 +466,10 @@ async function freezeEntryOnce(engine: BrainEngine, cursor: Cursor, key: string,
}
// #6712 PR 1: an import whose page moved since its file was last imported runs only as a proven no-op (sync-prescreen.ts).
if (entry.drift && !occupantRebound && content !== null && snapshot && !(image ? sameImageBytes(imageBytes, snapshot.page)
- : await sameContentAtOrigin(engine, cursor, entry, key, snapshot, content, rawHash, lineEndingOnly, run.signal) || await sameContentAtOrigin(engine, cursor, entry, key, snapshot, driftBaselineContent(cursor.gitRoot, entry), null, false, run.signal, true))) {
+ : await sameContentAtOrigin(engine, cursor, entry, key, snapshot, content, rawHash, lineEndingOnly, run.signal) || await pageHoldsDriftBaseline(cursor.gitRoot, entry, baseline => sameContentAtOrigin(engine, cursor, entry, key, snapshot, baseline, null, false, run.signal, true)))) {
if (!holdsOn) throw syncRunRefusal('file_drift', 'An import would overwrite a database version of the page that sync never saw.', retry, `Page ${slug} in source ${cursor.sourceId} ${entry.drift === 'unknown' ? `differs from ${entry.path} and has no import record to tell whether the file or the database changed` : `changed in the database since ${entry.path} was last imported, and the file differs from it`}, so the run stopped before admitting it (sync.holds=fail).`);
const proof = await pageChangeProof(engine, { sourceId: cursor.sourceId, incarnation: cursor.incarnation, pageId, expectedRevision: null }); assertActive();
- return { hold: fileDriftHold(entry, slug, pageId, frozenIntent, { sides: entry.drift, revision: snapshot.revision, proof, sharedOrigin: await sharedOriginSurvivor(engine, cursor.sourceId, entry.sourcePath) }) };
+ return { hold: fileDriftHold(entry, slug, pageId, frozenIntent, { sides: entry.drift, revision: snapshot.revision, proof, sharedOrigin: await sharedOriginSurvivor(engine, cursor.sourceId, entry.sourcePath), baseline: entry.driftBaseline ?? null }) };
}
if (screening && !image) {
const hold = await screenFrozenImport(engine, { cursor, entry, slug, pageId, snapshot, content, rawHash, lineEndingOnly, blob, oversize, streamed: !!bodyRef,
@@ -1278,11 +1278,13 @@ async function performManagedPass(engine: BrainEngine, opts: SyncOpts, slice?: {
const cursor = state.cursor?.() ?? null;
try {
const report = await buildHoldReport(engine, { sourceId: state.sourceId, incarnation: state.incarnation, runId: cursor?.runId ?? '', remote: state.remote === true,
- policy: readSyncHoldPolicy(engine), pendingScreen: synced.reason === 'writer_yield',
+ policy: readSyncHoldPolicy(engine), pendingScreen: synced.reason === 'writer_yield', needsHuman: (await import('./sync-status.ts')).holdNeedsHuman,
screened: 'entries' in (cursor ?? {}) ? (cursor as Cursor).entries.slice(0, cursor!.index).filter(entry => entry.action === 'import').length : 0 });
const recovered = state.remote ? undefined : recoveredReport(state.sourceId, cursor?.counts.recovered);
const fences = fencesNormalizedReport(state.sourceId, cursor?.counts.fences, state.remote === true);
- return { ...synced, ...report, ...(!state.remote && cursor?.convertedFromFailed?.length ? { converted_from_failed: cursor.convertedFromFailed } : {}),
+ // #7199: a pass that synced but held files a person must decide does not read as plain synced.
+ const humanHeld = report.held_needs_human && !synced.reason && ['synced', 'first_sync', 'up_to_date'].includes(synced.status);
+ return { ...synced, ...report, ...(humanHeld ? { reason: 'held_needs_human' as const } : {}), ...(!state.remote && cursor?.convertedFromFailed?.length ? { converted_from_failed: cursor.convertedFromFailed } : {}),
...(recovered ? { recovered_frontmatter: recovered } : {}), ...(fences ? { fences_normalized: fences } : {}) };
} catch {
return synced;
diff --git a/src/core/persistence/sync-screen.ts b/src/core/persistence/sync-screen.ts
index f2dcad868f..5a44062c8d 100644
--- a/src/core/persistence/sync-screen.ts
+++ b/src/core/persistence/sync-screen.ts
@@ -92,6 +92,14 @@ export function driftBaselineContent(gitRoot: string, entry: Pick<SyncEntry, 'dr
try { return readBlobContents(gitRoot, [{ oid: entry.driftBaseline, size: SYNC_READ_BOUND }]).get(entry.driftBaseline) ?? null; } catch { return null; }
}
+/** #7199: whether the page still holds what the entry's baseline or one of its earlier committed versions (`driftHistory`) imports, tried in order. */
+export async function pageHoldsDriftBaseline(gitRoot: string, entry: Pick<SyncEntry, 'drift' | 'driftBaseline' | 'driftHistory'>, same: (content: string | null) => Promise<boolean>): Promise<boolean> {
+ if (await same(driftBaselineContent(gitRoot, entry))) return true;
+ if (entry.drift !== 'unknown') return false;
+ for (const oid of entry.driftHistory ?? []) if (await same(driftBaselineContent(gitRoot, { drift: 'unknown', driftBaseline: oid }))) return true;
+ return false;
+}
+
/** The frozen import content of one entry (`readSyncContent`); a committed entry's pinned blob is read with the entries after it. */
export function pinnedContent(cursor: SyncDiscovery & { index: number }, entry: SyncEntry): string {
const content = entry.working ? null : readPinnedContent(cursor.gitRoot, cursor.target, syncGitPath(cursor, entry.path), upcomingGitPaths(cursor));
diff --git a/src/core/persistence/sync-status.ts b/src/core/persistence/sync-status.ts
index 32390f5955..154766e30a 100644
--- a/src/core/persistence/sync-status.ts
+++ b/src/core/persistence/sync-status.ts
@@ -27,7 +27,7 @@ import type { BrainEngine } from '../engine.ts';
import type { Action } from '../agent-output.ts';
import { managedSyncResumeArgs } from '../sync-reconcile.ts';
import { readManagedSyncFailures, type ManagedSyncFailure } from './sync-failures.ts';
-import { outOfAttemptsHold, fenceAutoRepairFor, gitHoldFix, holdEscalation, noteHoldEdit, readGitSourceHolds, recordHoldAttempt, requestGitHoldRetry, type GitHoldRecord } from './sync-holds.ts';
+import { outOfAttemptsHold, fenceAutoRepairFor, fileDriftSide, gitHoldFix, holdEscalation, noteHoldEdit, readGitSourceHolds, recordHoldAttempt, requestGitHoldRetry, type GitHoldRecord } from './sync-holds.ts';
import type { FenceAutoRepair } from '../fence-repair/hold-fix.ts';
import { classifySyncFault, HOLD_ATTEMPTS_NEEDS_HUMAN, type SyncFaultVerdict } from './sync-fault-class.ts';
import { CONTENT_REPAIR_KINDS, contentHoldDisposition, runContentLane, type ContentHoldDisposition } from '../repair/content-lane.ts';
@@ -303,6 +303,7 @@ export function holdVerdict(record: GitHoldRecord, auto: FenceAutoRepair | undef
const content = record.meta.content_repair ? { content_repair: { ...record.meta.content_repair, path: record.path, slug: record.slug } } : {};
if (record.code === 'origin_conflict' && record.meta.reason) return classifySyncFault({ code: record.code, detail: 'origin_conflict_decision', ...escalation });
if (record.code === 'page_identity_changed') return classifySyncFault({ code: record.code, detail: 'page_identity_decision', ...escalation });
+ if (record.code === 'file_drift' && fileDriftSide(record.meta) === 'unknown') return classifySyncFault({ code: record.code, detail: 'file_drift_unknown', ...escalation });
const disposition = contentHoldDisposition(record, auto);
if (disposition.action !== 'listed' || disposition.state === 'owner') return classifySyncFault({ code: record.code, ...escalation, ...content });
const verdict = classifySyncFault({ code: record.code, ...escalation, detail: disposition.reason, ...content });
@@ -313,6 +314,9 @@ export function holdVerdict(record: GitHoldRecord, auto: FenceAutoRepair | undef
return { ...verdict, safe_actions: ['none'], needs_human: true, human_reason: reason };
}
+/** #7199: whether a hold waits on a person; a sync run counts its own holds this way (sync-holds.ts buildHoldReport). */
+export const holdNeedsHuman = (record: GitHoldRecord, auto: FenceAutoRepair | undefined): boolean => holdVerdict(record, auto).needs_human;
+
function holdStatus(record: GitHoldRecord, auto?: FenceAutoRepair): SyncStatusHold {
const attempts = record.meta.attempts ?? 1;
const verdict = holdVerdict(record, auto);
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index 2341121142..c895ae1e43 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -471,6 +471,7 @@ test/sync-admission-6712.test.ts
test/sync-apply-held-deletions-gbra133.test.ts
test/sync-capacity-preflight.test.ts
test/sync-checkpoint-moved-6834.test.ts
+test/sync-classic-drift-7199.test.ts
test/sync-discovery-legacy-origin-7130.test.ts
test/sync-drain-claims.test.ts
test/sync-drain-effect-recovery-blocked.test.ts
diff --git a/test/sync-classic-drift-7199.test.ts b/test/sync-classic-drift-7199.test.ts
new file mode 100644
index 0000000000..8ca8335312
--- /dev/null
+++ b/test/sync-classic-drift-7199.test.ts
@@ -0,0 +1,139 @@
+/**
+ * #7199: after a classic brain turns managed, a file edited before the first managed pass has a page with no import
+ * record. The pass used to hold every such file as file_drift side unknown, needs_human, and report plain synced.
+ *
+ * Protects:
+ * - a record-less page whose database copy still equals the file at the source's last synced commit imports the newer
+ * file with no hold (the classic sync that last wrote the page read that blob);
+ * - a record-less page whose database copy moved stays held, and the hold says that no import record says which side
+ * moved and, with no database write on record, what it compared (message, fix text and the sync status verdict);
+ * - an existing side-unknown hold written before that comparison (no drift_version) is re-screened once: one that
+ * meets the proof imports and clears, one that does not stays held, records the comparison and is not re-screened again;
+ * - a pass that holds files a person must decide reports reason held_needs_human with their count, not plain synced.
+ * PGLite always; Postgres too when DATABASE_URL is set.
+ */
+import { describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import { performManagedSync } from '../src/core/persistence/sync-run.ts';
+import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
+import { readSyncStatus } from '../src/core/persistence/sync-status.ts';
+import { FILE_DRIFT_VERSION, SYNC_IMPORT_PROVENANCE_OP } from '../src/core/persistence/sync-holds.ts';
+import { MANAGED_SYNC_PASS_OP } from '../src/core/persistence/sync-pass-row.ts';
+import { printHoldNotes } from '../src/commands/sync-diagnostics.ts';
+import { managedBrain } from './helpers/managed-brain.ts';
+import { waitFor } from './helpers/wait-for.ts';
+
+const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+const commit = (root: string, message: string) => { git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); };
+const note = (slug: string, body: string) => `---\ntype: concept\ntitle: ${slug}\n---\n\n${body}\n`;
+const committed = (slug: string) => note(slug, `The committed body of ${slug}.`);
+const SLUGS = ['notes/a', 'notes/b', 'notes/c', 'notes/d'];
+const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: true };
+const setup = ({ root }: { root: string }) => {
+ mkdirSync(join(root, 'notes'), { recursive: true }); git(root, 'init', '-q');
+ for (const slug of SLUGS) writeFileSync(join(root, `${slug}.md`), committed(slug));
+ commit(root, 'notes');
+};
+const bodyOf = async (engine: BrainEngine, slug: string) => (await engine.getPage(slug, { sourceId: 'default' }))?.compiled_truth ?? '';
+async function holds(engine: BrainEngine) {
+ const rows = await engine.executeRaw<{ fingerprint: string; record: { code: string; message: string; meta: Record<string, unknown> } }>(
+ "SELECT fingerprint, completed_keys->0 AS record FROM op_checkpoints WHERE op='sync-hold' ORDER BY fingerprint");
+ return Object.fromEntries(rows.map(row => [row.fingerprint.split(':').slice(2).join(':'), row.record]));
+}
+/** Pages as a classic sync left them: no import record, and no managed pass row yet. */
+async function classicPages(engine: BrainEngine) {
+ await engine.executeRaw('DELETE FROM op_checkpoints WHERE op IN ($1,$2)', [SYNC_IMPORT_PROVENANCE_OP, MANAGED_SYNC_PASS_OP]);
+}
+async function dbEdit(engine: BrainEngine, ctx: OperationContext, slug: string, content: string) {
+ const requestId = randomUUID();
+ const current = await engine.readPageSnapshot(slug, { sourceId: 'default' });
+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: requestId, expected_revision: current!.revision, content } });
+ await waitFor(async () => (await engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [requestId]))[0]?.state === 'committed',
+ { timeoutMs: 20_000, label: `request ${requestId} commits` });
+}
+const PAGE_COLUMNS = ['title', 'type', 'compiled_truth', 'timeline', 'frontmatter', 'content_hash'] as const;
+const pageRow = async (engine: BrainEngine, slug: string) => (await engine.executeRaw<Record<string, unknown>>(
+ `SELECT ${PAGE_COLUMNS.join(', ')} FROM pages WHERE source_id='default' AND slug=$1`, [slug]))[0]!;
+/** Writes a page row back as an older gbrain left it: managed persistence off around the write. */
+async function restorePage(engine: BrainEngine, slug: string, row: Record<string, unknown>) {
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ try {
+ await engine.executeRaw(`UPDATE pages SET title=$2, type=$3, compiled_truth=$4, timeline=$5, frontmatter=$6::jsonb, content_hash=$7 WHERE source_id='default' AND slug=$1`,
+ [slug, row.title, row.type, row.compiled_truth, row.timeline, JSON.stringify(row.frontmatter), row.content_hash]);
+ } finally { await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1'); }
+}
+/** A side-unknown hold as a gbrain before the last-synced-commit comparison wrote it: no drift screen version, no recorded comparison. */
+async function unscreened(engine: BrainEngine, path: string) {
+ await engine.executeRaw("UPDATE op_checkpoints SET completed_keys=jsonb_build_array((completed_keys->0) #- '{meta,baseline_screened}' #- '{meta,drift_version}') WHERE op='sync-hold' AND fingerprint LIKE '%:' || $1", [path]);
+}
+
+for (const databaseUrl of process.env.DATABASE_URL ? [undefined, process.env.DATABASE_URL] : [undefined]) describe(`#7199 classic-era edits after managed activation (${databaseUrl ? 'postgres' : 'pglite'})`, () => {
+ test('a record-less page equal to its file at the last synced commit imports the newer file; one whose page moved stays held with truthful text, and the pass reports held_needs_human', () => managedBrain(async ({ engine, ctx, root }) => {
+ await engine.setConfig('sync.write_through', 'false');
+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
+ await classicPages(engine);
+ // c's page moved in the database through a request; d's moved with no request on record (an older gbrain's write).
+ await dbEdit(engine, ctx, 'notes/c', note('notes/c', 'A database-only edit of notes/c.'));
+ await restorePage(engine, 'notes/d', { ...await pageRow(engine, 'notes/d'), compiled_truth: 'An unrecorded database edit of notes/d.' });
+ for (const slug of SLUGS) writeFileSync(join(root, `${slug}.md`), note(slug, `A newer file body of ${slug}.`));
+ commit(root, 'edits after activation');
+
+ const result = await performManagedSync(engine, OPTS);
+ expect({ status: result.status, reason: result.reason ?? null, held_needs_human: result.held_needs_human ?? null }).toEqual({ status: 'synced', reason: 'held_needs_human', held_needs_human: 2 });
+ expect((result.held ?? []).map(hold => ({ path: hold.path, code: hold.code, side: hold.side }))).toEqual([
+ { path: 'notes/c.md', code: 'file_drift', side: 'unknown' }, { path: 'notes/d.md', code: 'file_drift', side: 'unknown' }]);
+ for (const slug of ['notes/a', 'notes/b']) expect(await bodyOf(engine, slug)).toContain(`A newer file body of ${slug}.`);
+ expect(await bodyOf(engine, 'notes/c')).toContain('A database-only edit of notes/c.');
+ expect(await bodyOf(engine, 'notes/d')).toContain('An unrecorded database edit of notes/d.');
+
+ const held = await holds(engine);
+ expect(Object.keys(held)).toEqual(['notes/c.md', 'notes/d.md']);
+ expect(held['notes/c.md']!.meta).toMatchObject({ side: 'unknown', drift_version: FILE_DRIFT_VERSION });
+ expect(held['notes/d.md']!.message).toContain('page notes/d differs from its file and has no import record to tell whether the file or the database changed; the page also differs from the file at the last synced commit');
+ expect(held['notes/c.md']!.message).toContain('there is no import record to tell whether the file changed too');
+ expect(held['notes/c.md']!.message).not.toContain('changed in the database since');
+ expect(result.held![0]!.fix.why).toContain('no import record says whether the file changed too');
+
+ const status = await readSyncStatus(engine, 'default');
+ const hold = status.holds.find(item => item.path === 'notes/c.md')!;
+ expect(hold).toMatchObject({ code: 'file_drift', needs_human: true });
+ expect(hold.human_reason).toContain('sync has no import record to tell which one changed');
+
+ const lines: string[] = [];
+ printHoldNotes(result, line => lines.push(line));
+ expect(lines[0]).toBe('Synced; 2 file(s) held for a person (gbrain sync status --source default).');
+ expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');
+ }, { databaseUrl, setup }), 240_000);
+
+ test('an older side-unknown hold is re-screened once: the page that meets the proof imports and clears, the one that does not stays held and records the comparison', () => managedBrain(async ({ engine, ctx, root }) => {
+ await engine.setConfig('sync.write_through', 'false');
+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
+ await classicPages(engine);
+ const classic = await pageRow(engine, 'notes/a');
+ for (const slug of ['notes/a', 'notes/c']) await dbEdit(engine, ctx, slug, note(slug, `A database-only edit of ${slug}.`));
+ for (const slug of ['notes/a', 'notes/c']) writeFileSync(join(root, `${slug}.md`), note(slug, `A newer file body of ${slug}.`));
+ commit(root, 'edits after activation');
+ expect((await performManagedSync(engine, OPTS)).held?.map(hold => hold.path).sort()).toEqual(['notes/a.md', 'notes/c.md']);
+ // a's page row goes back to what the classic import wrote: the page an older gbrain held although it equals an earlier
+ // committed version of its file.
+ await restorePage(engine, 'notes/a', classic);
+ // Control: a hold that recorded its comparison is not re-screened, so a stays held.
+ expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');
+ expect(Object.keys(await holds(engine)).sort()).toEqual(['notes/a.md', 'notes/c.md']);
+
+ await unscreened(engine, 'notes/a.md');
+ await unscreened(engine, 'notes/c.md');
+ await performManagedSync(engine, OPTS);
+ expect(await bodyOf(engine, 'notes/a')).toContain('A newer file body of notes/a.');
+ expect(await bodyOf(engine, 'notes/c')).toContain('A database-only edit of notes/c.');
+ const held = await holds(engine);
+ expect(Object.keys(held)).toEqual(['notes/c.md']);
+ expect(held['notes/c.md']!.meta).toMatchObject({ side: 'unknown', drift_version: FILE_DRIFT_VERSION });
+ expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');
+ }, { databaseUrl, setup }), 240_000);
+});
diff --git a/test/sync-legacy-validate-stamp-gbra133.test.ts b/test/sync-legacy-validate-stamp-gbra133.test.ts
index 203ae6df26..29e075f5c3 100644
--- a/test/sync-legacy-validate-stamp-gbra133.test.ts
+++ b/test/sync-legacy-validate-stamp-gbra133.test.ts
@@ -70,7 +70,7 @@ describe('GBRA-133 legacy page with the database-only grandfather stamp', () =>
const held = await readGitHold(engine, 'default', incarnation, 'notes/edited.md');
expect(held).toMatchObject({ code: 'file_drift', meta: { side: 'unknown' } });
// With no import record and no database write on record, the hold does not claim the database changed.
- expect(held!.message).toBe('notes/edited.md: page notes/edited differs from its file and has no import record to tell whether the file or the database changed, so sync held the import instead of overwriting the database version; the rest of the source synced.');
+ expect(held!.message).toBe('notes/edited.md: page notes/edited differs from its file and has no import record to tell whether the file or the database changed; the page also differs from the file at the last synced commit, so sync held the import instead of overwriting the database version; the rest of the source synced.');
expect((await page(engine, 'notes/edited')).compiled_truth).toContain('A database edit.');
}, { setup }), 120_000);
});
diff --git a/test/sync-pass-completion-6712.test.ts b/test/sync-pass-completion-6712.test.ts
index a3d5ec22a7..fe3405471e 100644
--- a/test/sync-pass-completion-6712.test.ts
+++ b/test/sync-pass-completion-6712.test.ts
@@ -113,7 +113,8 @@ describe('#6712 PR 4b lane B: holds with side and state (rows 6, 9, 19)', () =>
const head = git(root, 'rev-parse', 'HEAD');
const result = await performManagedSync(engine, OPTS);
- expect({ status: result.status, reason: result.reason ?? null }).toEqual({ status: 'synced', reason: null });
+ // #7199: the source synced, and the four holds wait on a person, so the pass says so instead of plain synced.
+ expect({ status: result.status, reason: result.reason ?? null, held_needs_human: result.held_needs_human ?? null }).toEqual({ status: 'synced', reason: 'held_needs_human', held_needs_human: 4 });
expect((await source(engine)).last_commit).toBe(head);
const held = await holds(engine);
expect(held['notes/a.md']).toMatchObject({ code: 'file_drift', slug: 'notes/a', meta: { side: 'deleted', state: 'file_gone', deleted: true } });