Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Say in every file-drift --prefer preview how many lines the apply drops from the side it overwrites (GST-2568)
garrytan6589af2f1d7a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8fefa036b1..8722e7cbba 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,7 @@ identifiers and attribution are available in the pre-removal Git revision- **A page whose file is gone under a `gbrain.yml` `db_only` folder is no drift.** An existing deleted-side hold there now releases.- **`gbrain repair file-drift` compares without a winner.** Any selection without `--prefer` lists, per page, what differs, which side is newer (the file's last commit against the page's `updated_at`) and what a repair would do, and writes nothing. A `--prefer` preview with no side names that comparison as its fix.- **`--prefer file` never drops a newer page in bulk.** A `--held`, `--all-drifted` or `--request` preview lists a page edited after its file's last commit as `kept_newer_page` and leaves it held; naming the page with `--slug` still resolves it, with a warning naming the edit it drops. A page whose file is gone is never deleted by a comparison (GST-2568).+- **A `--prefer` preview says how much it drops.** Each page's listing line counts the lines of the side the apply overwrites that the result doesn't carry ("drops 3 line(s) the file holds"), a warning gives the total for the run, and `--json` carries `details.pages[].lost_lines` and `details.lost_lines_total`, so whoever agrees to the apply sees what the losing side held.## [0.60.699.0] - 2026-11-12diff --git a/docs/architecture/key-files/canonical-reconciliation-continued.md b/docs/architecture/key-files/canonical-reconciliation-continued.mdindex 498887f381..62d45a4f24 100644--- a/docs/architecture/key-files/canonical-reconciliation-continued.md+++ b/docs/architecture/key-files/canonical-reconciliation-continued.md@@ -7,4 +7,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/doctor/checks/rows-behind.ts` — doctor `sync_rows_behind_checkpoint` (BRAIN, after `sync_overwritten_db_edits`): per source counts and first slugs from `scanRowsBehind`; `warn` on `behind` rows with the read-only `gbrain repair rows-behind --source <id> --json` preview as the fix; `unknown` (info) when the `GBRAIN_DOCTOR_ROWS_BEHIND_TIMEOUT_MS` budget (default 10 s) stopped a scan or a checkout is unreadable; not applicable (ok) off the owner host and on repo-less brains.- `src/core/repair/rows-behind.ts` — `gbrain repair rows-behind --source <id>`: explicit-only, preview-bound (`--apply --expect <hash>`, `--include-ambiguous` adds rows with no import record). `reimport` submits the committed bytes through `submitManagedFileRepair`; `hold:<code>` writes the hold sync would have written (`writeGitHold`). Refused off the owner host (`not_owner_host`). Never runs on upgrade. Tests: `test/rows-behind-checkpoint-8071.test.ts` (PGLite and Postgres via `test/e2e/rows-behind-checkpoint-8071-postgres.test.ts`).- GST-2201, a file that comes back after sync deleted its page: `readShadowLevel` (`sync-pass.ts`) reads whether a tombstone is sync-made (`syncDeleteOrigin`, `sync-delete-tombstones.ts`) into `page.syncDeleted`, and `sync-classify.ts` classifies such a path `import` ahead of `deleted_same` / `deleted_edited` (uncommitted bytes take `dirty`; an old hold on it re-runs). The selection fingerprint carries `sync_deleted_restore`, so the first pass after the upgrade reads the whole level once. `originCommitted` (`sync-markers.ts`) says whether a page's file is in the tree at the source's `last_commit` or at HEAD (false off a managed checkout or for a company-brain source; an unreadable checkout counts as committed). A retention purge (`page-prepare.ts`) of a tombstone whose file is committed defers a sync-made tombstone (`revision_conflict`) and purges any other database-only (`databaseOnlyReason: committed_file`), so the file stays. Tests: `test/sync-restored-file-purge.test.ts` (PGLite and Postgres), `test/sync-classify-6712.test.ts`.-- `src/core/repair/file-drift-compare.ts` — GST-2568: `gbrain repair file-drift` with a selection and no `--prefer` (`compareSelection` in file-drift.ts) compares each page with its file through `comparePage` and writes nothing: `driftDifference` over the `reconcileCanonical` readings names what differs, `newerSide` compares the file's last commit at HEAD (`fileCommitEvidence`) with the page's `updated_at` (unknown with uncommitted bytes, a missing time or the same second), and the verdict is `release_hold`, `no_drift`, `prefer_file`, `needs_human` (a newer page, a page whose file is gone, a deleted page whose file differs) or `unknown`. A `--prefer file` preview reads `readDriftEvidence` first and lists a page newer than its file `kept_newer_page` (`newerPageParagraph`) unless `--slug` names it, which adds a warning instead. Test: `test/file-drift-normalisation-gst2568.test.ts`.+- `src/core/repair/file-drift-compare.ts` — GST-2568: `gbrain repair file-drift` with a selection and no `--prefer` (`compareSelection` in file-drift.ts) compares each page with its file through `comparePage` and writes nothing: `driftDifference` over the `reconcileCanonical` readings names what differs, `newerSide` compares the file's last commit at HEAD (`fileCommitEvidence`) with the page's `updated_at` (unknown with uncommitted bytes, a missing time or the same second), and the verdict is `release_hold`, `no_drift`, `prefer_file`, `needs_human` (a newer page, a page whose file is gone, a deleted page whose file differs) or `unknown`. A `--prefer file` preview reads `readDriftEvidence` first and lists a page newer than its file `kept_newer_page` (`newerPageParagraph`) unless `--slug` names it, which adds a warning instead. `linesNotCarried` counts the overwritten side's lines the result does not carry; `prepareDriftPage` renders both with `serializePageToMarkdown` and stores `lost_lines` on each page, which the listing, a total warning and `details.lost_lines_total` report. Test: `test/file-drift-normalisation-gst2568.test.ts`.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex 34acdeaba1..e1e24781e8 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -3388,6 +3388,13 @@ file, commit it and sync), and leaves its hold in place. Naming the page withdatabase edit the apply drops. A page whose file is gone is never deleted by acomparison or by `--prefer file` unless you select its deleted state.+Every `--prefer` preview also counts what the apply drops from the side it+overwrites: each page's listing line ends "drops N line(s) the file holds" (or+"the page holds"), a warning gives the total across the run, and `--json`+carries `details.pages[].lost_lines` and `details.lost_lines_total`. A line+counts when the result doesn't carry it; blank lines and trailing spaces don't+count. Read those lines before you agree to the apply.+| State | `--prefer database` | `--prefer file` ||---|---|---|| `tombstone_edited` | Keeps the deletion and removes the file. | Restores the page and imports the file. |diff --git a/scripts/page-body-readers-baseline.tsv b/scripts/page-body-readers-baseline.tsvindex 2b032015f9..041a75974d 100644--- a/scripts/page-body-readers-baseline.tsv+++ b/scripts/page-body-readers-baseline.tsv@@ -571,6 +571,7 @@ src/core/repair/fact-claim-dates.ts movePage call:serializePageToMarkdown SEGW rsrc/core/repair/fences.ts afterBytes field STREAMsrc/core/repair/fences.ts fencesRepair field STREAMsrc/core/repair/file-drift-compare.ts driftDifference field NONE compares the compiled_truth and timeline of the reconcile reading (readReconcileState materializes a segmented page), never a stored body string+src/core/repair/file-drift.ts prepareDriftPage call:serializePageToMarkdown NONE renders the reconcile reading of both sides and of the result (readReconcileState materializes a segmented page) to count lost lines; no stored page body is read heresrc/core/repair/frontmatter.ts analyzeFile field LEADsrc/core/repair/frontmatter.ts pagesByOrigin sql LEADsrc/core/repair/lost-fence-rows.ts lostIn field NONE walks the history scanLostFenceRows built (inline page_versions bodies and a materialized snapshot); no stored page body is read herediff --git a/src/core/repair/file-drift-compare.ts b/src/core/repair/file-drift-compare.tsindex 745198961b..325f4e5516 100644--- a/src/core/repair/file-drift-compare.ts+++ b/src/core/repair/file-drift-compare.ts@@ -114,6 +114,23 @@ export async function comparePage(engine: BrainEngine, sourceId: string, target:}}+/**+ * How many non-blank lines of `losing` the `winning` text does not carry, each line counted as often as it repeats: what+ * a repair that keeps `winning` drops from the side it overwrites. Trailing spaces are ignored; nothing else is.+ */+export function linesNotCarried(losing: string, winning: string): number {+ const kept = new Map<string, number>();+ for (const line of winning.split('\n')) { const key = line.trimEnd(); if (key.trim()) kept.set(key, (kept.get(key) ?? 0) + 1); }+ let lost = 0;+ for (const line of losing.split('\n')) {+ const key = line.trimEnd();+ if (!key.trim()) continue;+ const left = kept.get(key) ?? 0;+ if (left) kept.set(key, left - 1); else lost++;+ }+ return lost;+}+/** The listing row of a compared page. */export function comparedListing(page: ComparedPage): RepairListing {const evidence = page.evidence ? `differs: ${page.evidence.differs}${page.evidence.keys.length ? ` (${page.evidence.keys.join(', ')})` : ''}; newer: ${page.evidence.newer}; ` : '';diff --git a/src/core/repair/file-drift.ts b/src/core/repair/file-drift.tsindex d83d09af74..f2838a21d7 100644--- a/src/core/repair/file-drift.ts+++ b/src/core/repair/file-drift.ts@@ -93,7 +93,8 @@ import { assertReconcileOutputPath, assertReconcileSize } from '../persistence/rimport { authorizeReconcile, runReconcileApply } from '../persistence/reconcile.ts';import { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';import { recordsNoFileOrigin } from '../persistence/unbound-pages.ts';-import { comparedListing, comparePage, newerPageParagraph, readDriftEvidence, type ComparedPage } from './file-drift-compare.ts';+import { comparedListing, comparePage, linesNotCarried, newerPageParagraph, readDriftEvidence, type ComparedPage } from './file-drift-compare.ts';+import { serializePageToMarkdown } from '../markdown.ts';import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairPlanOptions, type RepairScope } from './core.ts';export type DriftSide = 'file' | 'database';@@ -106,7 +107,9 @@ export interface ArtifactPage { slug: string; prefer: DriftSide; class?: DriftCl/** #6712 wave: the canonical file is gone from the last commit and the apply recreates it from the page. */file_gone?: true;/** GBRA-133: file wins appends protected keys or timeline rows to the canonical file (`fileWinsContent`). */- file_appended?: true }+ file_appended?: true;+ /** How many lines of the side the repair overwrites the result does not carry (`linesNotCarried`, both sides rendered alike). */+ lost_lines: number }/** #6712 wave: a page whose canonical file is gone from the last commit, resolved `--prefer file`: soft-delete exactly that page. */export interface SoftDeletePage { slug: string; prefer: 'file'; exceptions: DriftException[]; soft_delete: { ghost: GhostPage; owner: GhostOwner } }/**@@ -539,7 +542,9 @@ export async function prepareDriftPage(engine: BrainEngine, sourceId: string, slif (error instanceof OperationError && !error.fix) error.fix = readFix(`gbrain wrote a reconcile preview of ${slug} that its own apply refuses, so nothing was approved or written; report it with the output of gbrain doctor --json (the command in fix).`, { argv: ['gbrain', 'doctor', '--json'] });throw error;}- return { slug, prefer, adopt_slug_path: adopt, exceptions: driftExceptions(prepared.result, prefer === 'file' ? file : database), result: prepared.result, preview,+ const rendered = (page: ParsedPage) => serializePageToMarkdown({ ...state.snapshot.page, ...page }, page.tags);+ const lost_lines = opts.fileGone ? 0 : linesNotCarried(rendered(prefer === 'database' ? file : database), rendered(prepared.result));+ return { slug, prefer, adopt_slug_path: adopt, exceptions: driftExceptions(prepared.result, prefer === 'file' ? file : database), result: prepared.result, preview, lost_lines,...(opts.fileGone ? { file_gone: true as const } : {}), ...(appends ? { file_appended: true as const } : {}) };}@@ -911,7 +916,8 @@ export const fileDriftRepair: RepairHandler = {if (classes.has(slug)) page.class = classes.get(slug);pages.push(page);listing.push({ item: `${sourceId}:${slug}`, class: `prefer_${opts.prefer}`,- detail: `${page.exceptions.length ? `kept: ${[...new Set(page.exceptions.map(e => e.reason))].join(', ')}` : 'exactly the preferred side'}${page.adopt_slug_path ? '; adopts the file at its slug path' : ''}` });+ detail: `${page.exceptions.length ? `kept: ${[...new Set(page.exceptions.map(e => e.reason))].join(', ')}` : 'exactly the preferred side'}${page.adopt_slug_path ? '; adopts the file at its slug path' : ''}`+ + (page.lost_lines ? `; drops ${page.lost_lines} line(s) the ${opts.prefer === 'database' ? 'file' : 'page'} holds` : '') });} catch (error) {if (!(error instanceof OperationError) || ['owner_unavailable', 'writer_registration_required'].includes(error.code)) throw error;count(`refused_${error.code}`);@@ -939,6 +945,9 @@ export const fileDriftRepair: RepairHandler = {let warnings: string[] = nextCommand ? [`This preview covered ${previewed} of the ${held!.targets.length} selected held pages${opts.cursor ? ' after its cursor' : ''} (one window stops at ${HELD_WINDOW_PAGES} pages or ${HELD_WINDOW_BUDGET_MS / 1000} s); its hash and apply command cover only these. `+ `After applying this window (or deciding not to), preview the next one: ${nextCommand}`] : [];if (newerPages.length) warnings.unshift(`The apply drops a database edit newer than its file for ${newerPages.length} page(s): ${newerPages.join(' ')}`);+ const losing = pages.flatMap(page => 'preview' in page && page.lost_lines ? [page] : []);+ const lostLines = losing.reduce((sum, page) => sum + page.lost_lines, 0);+ if (lostLines) warnings.push(`The apply drops ${lostLines} line(s) the ${opts.prefer === 'database' ? 'files' : 'pages'} it overwrites hold and the result does not carry, across ${losing.length} page(s); details.pages[].lost_lines counts each. Read them before agreeing.`);const releases = pages.filter(page => 'release_hold' in page).length;if (releases) warnings.push(`The apply only schedules a re-screen of ${releases} held file(s) whose page and file agree; the next sync (gbrain sync --source ${sourceId}) releases each that still agrees.`);let undoneBySync: { recreated: number; removed: number } | null = null;@@ -970,6 +979,7 @@ export const fileDriftRepair: RepairHandler = {...(undoneBySync ? { undone_by_next_sync_unless_committed: undoneBySync } : {}),...(held ? { window: { previewed, remaining, complete: remaining === 0, ...(nextCursor ? { next_cursor: nextCursor, next_command: nextCommand } : {}) } } : {}),...(held?.provenance ? { provenance: held.provenance } : {}),+ lost_lines_total: lostLines,pages: pages.map(page => ({ ...('release_hold' in page ? { slug: page.slug, action: 'release_hold', path: page.release_hold.path, verb: 're-screen the held file (the page and the file agree)', exceptions: page.exceptions }: 'soft_delete' in page ? { slug: page.slug, action: 'soft_delete', path: page.soft_delete.ghost.path, verb: fileDriftActionVerb('deleted', 'file_gone', 'file'), exceptions: page.exceptions }: 'detach_page' in page ? { slug: page.slug, action: 'detach_page', path: page.detach_page.path, verb: 'keep the page database-only (no file)', exceptions: page.exceptions }@@ -977,7 +987,7 @@ export const fileDriftRepair: RepairHandler = {: 'import_file' in page ? { slug: page.slug, action: 'import_file', state: page.import_file.state, path: page.import_file.path, verb: fileDriftActionVerb('deleted', page.import_file.state, 'file'), exceptions: page.exceptions, result_digest: page.import_file.result_digest }: { slug: page.slug, ...(page.file_gone ? { action: 'recreate_file' } : {}), ...(page.class ? { class: page.class } : {}),verb: page.file_gone ? fileDriftActionVerb('deleted', 'file_gone', 'database') : fileDriftActionVerb('both', undefined, page.prefer),- adopt_slug_path: page.adopt_slug_path, exceptions: page.exceptions, result_digest: page.preview.result_digest }),+ adopt_slug_path: page.adopt_slug_path, exceptions: page.exceptions, result_digest: page.preview.result_digest, lost_lines: page.lost_lines }),...(provenanceOf.get(page.slug) ? { provenance: provenanceOf.get(page.slug) } : {}) })),protections: 'Protected metadata stays as the database holds it, tags are the union of both sides, and protected takes and private fact rows are kept; exceptions lists each page\'s.' } };},diff --git a/test/file-drift-normalisation-gst2568.test.ts b/test/file-drift-normalisation-gst2568.test.tsindex 3afce25776..05baa8df00 100644--- a/test/file-drift-normalisation-gst2568.test.ts+++ b/test/file-drift-normalisation-gst2568.test.ts@@ -22,6 +22,8 @@* - item 4: `--prefer file` never drops a page edited after its file's last commit in bulk (`kept_newer_page`, the hold* stays), names the drop in a warning when one `--slug` asks for it, and the comparison never proposes deleting a page* whose file is gone;+ * - a `--prefer` preview counts, per page and in total, the lines of the side it overwrites that the result does not carry, in+ * its listing, a warning and `details.lost_lines`;* - a caller's write (put_page, import) that names the type a retype replaced still takes that type: only a file reading keeps* the retype's stamp.* PGLite always; Postgres too when DATABASE_URL is set. Holds exist only where sync imports a Git checkout, so there is no@@ -242,6 +244,22 @@ for (const backend of testBackends()) {expect(classes(single)['notes/newer-page']).toBe('prefer_file');expect(single.warnings?.join(' ')).toContain('drops a database edit newer than its file');}, { databaseUrl, setup: heldSetup }), 240_000);++ test(`GST-2568 [${backend}]: a --prefer preview counts the lines of the overwritten side the result drops, per page and in total`, () => managedBrain(async ({ engine, root }) => {+ await heldPages(engine, root);+ const lost = (plan: Plan) => Object.fromEntries((plan.details!.pages as Array<{ slug: string; lost_lines?: number }>).flatMap(page => page.lost_lines === undefined ? [] : [[page.slug, page.lost_lines]]));+ const detail = (plan: Plan, slug: string) => plan.listing!.find(entry => entry.item === `default:${slug}`)!.detail;+ const byFile = await repair(engine, { slugs: ['notes/newer-file', 'notes/newer-page'], prefer: 'file' }) as Plan;+ expect(lost(byFile)).toEqual({ 'notes/newer-file': 1, 'notes/newer-page': 1 });+ expect(byFile.details!.lost_lines_total).toBe(2);+ expect(detail(byFile, 'notes/newer-file')).toContain('drops 1 line(s) the page holds');+ expect(byFile.warnings?.join(' ')).toContain('The apply drops 2 line(s) the pages it overwrites hold and the result does not carry, across 2 page(s)');+ const byDatabase = await repair(engine, { slugs: ['notes/newer-page'], prefer: 'database' }) as Plan;+ expect([lost(byDatabase), byDatabase.details!.lost_lines_total]).toEqual([{ 'notes/newer-page': 1 }, 1]);+ expect(detail(byDatabase, 'notes/newer-page')).toContain('drops 1 line(s) the file holds');+ const released = await repair(engine, { held: true, side: 'unknown', prefer: 'file' }) as Plan;+ expect(released.details!.pages.find((page: { slug: string }) => page.slug === 'notes/same').lost_lines).toBeUndefined();+ }, { databaseUrl, setup: heldSetup }), 240_000);}let engine: PGLiteEngine;diff --git a/test/repair-file-drift-origin-twin-gbra108.test.ts b/test/repair-file-drift-origin-twin-gbra108.test.tsindex a3b271e478..eeb84093e5 100644--- a/test/repair-file-drift-origin-twin-gbra108.test.ts+++ b/test/repair-file-drift-origin-twin-gbra108.test.ts@@ -77,7 +77,7 @@ test('a held origin twin is listed by the preview with an apply command, and --pconst planned = await preview(engine, 'database');expect(planned.residuals).toEqual({});expect(planned.affected).toBe(1);- expect(planned.listing).toEqual([{ item: `default:${SLUG}`, class: 'prefer_database', detail: 'exactly the preferred side; adopts the file at its slug path' }]);+ expect(planned.listing).toEqual([{ item: `default:${SLUG}`, class: 'prefer_database', detail: 'exactly the preferred side; adopts the file at its slug path; drops 1 line(s) the file holds' }]);expect((await preview(engine, 'database', planned.preview_hash!)).outcomes).toEqual({ repaired: 1 });await settleManagedGitEffects(engine);git(root, 'commit', '-qam', 'commit the repaired file');