Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
An unbound collision can keep its database side through a consented file-drift step, and the consent names the lines it drops (GST-2568)
garrytan6c4d6cb47633
diff --git a/changelog.d/capy-sync-stops-holding-pages.md b/changelog.d/capy-sync-stops-holding-pages.mdindex 5708102833..5f1ec04dcf 100644--- a/changelog.d/capy-sync-stops-holding-pages.md+++ b/changelog.d/capy-sync-stops-holding-pages.md@@ -8,4 +8,6 @@- **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.+- **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. The consent the apply asks for repeats the total.+- **An unbound collision can keep its database side, with consent.** A page an unbound write left database-only, with a different file at its slug path, is drift to `gbrain repair file-drift --slug <slug>`. `sources reconcile` refuses to take its database side over that file and names this step: `--prefer database` names the file's commit, its apply needs the user's consent, and it records the file as the page's origin.+- **The kept-newer-page text prints previews, not runs.** It tells you to preview either side, and says a database-wins apply needs the user's consent.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex bcc969eae7..f16b8c34cd 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -3336,7 +3336,10 @@ lists each newer change the database copy overwrites and each file a`source_changed` (detail `unimported_file_edit`) when a decision takes thedatabase copy over what such a file says (`take_database`, `delete` or`set_value`); decide `take_file` for those paths, or preview the page alone with-`--slug` as above. A `never_committed` `file_gone` page resolved+`--slug` as above. That covers an unbound collision too (a page an unbound+write left database-only, and a different file at its slug path): `--slug+<slug> --prefer database` reads it as drift, names the file's commit, asks for+consent and records the file as the page's origin. A `never_committed` `file_gone` page resolved`--prefer database` writes no file, so it is unaffected. The keep_db policy isunchanged.diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 174153c537..a6a52a5878 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -784,7 +784,11 @@ read the page again and resubmit with a new request ID. If a canonical fileappears at the path of a database-only page after binding, sync stops for thatfile with `source_changed` and reason `unbound_source`; neither copy isoverwritten and the database page stays served. Rename or remove the file,-commit, and sync again.+commit, and sync again. Or settle the pair: `gbrain sources reconcile <source>+<slug> --preview` and decide `take_file` to keep the file, or preview+`gbrain repair file-drift --source <source> --slug <slug> --prefer database` to+keep the database copy (it names the file's commit, and its apply needs the+user's consent).`gbrain doctor` reports the `unbound_source` check: the number of such pagesper source. While the source is unbound it is `ok` and prints the bind command;diff --git a/src/core/repair/file-drift-compare.ts b/src/core/repair/file-drift-compare.tsindex 325f4e5516..b44a74f5a4 100644--- a/src/core/repair/file-drift-compare.ts+++ b/src/core/repair/file-drift-compare.ts@@ -76,7 +76,7 @@ export function newerPageParagraph(sourceId: string, slug: string, evidence: Driconst what = evidence.differs === 'both' ? 'body and frontmatter' : evidence.differs === 'body' ? 'body' : `frontmatter (${evidence.keys.join(', ')})`;return `page ${slug} changed after its file was last committed (page updated ${evidence.page_updated_at}, ${evidence.path} committed ${evidence.file_committed_at}) and its ${what} differs, `+ `so letting the file win may drop a database edit; it stays held for a person. updated_at also moves on gbrain's own writes (a retype), so read both sides first. `- + `To keep the file, run gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer file; to keep the page, run it with --prefer database (rewrites the file from the page) or carry the edit into the file, commit it and run gbrain sync --source ${sourceId}.`;+ + `To keep the file, preview gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer file. To keep the page, preview it with --prefer database instead (its apply would rewrite the file from the page and needs the user's consent), or carry the edit into the file, commit it and run gbrain sync --source ${sourceId}.`;}/** One selected page, compared: a held page by its hold, any other by its slug. Never writes. */diff --git a/src/core/repair/file-drift.ts b/src/core/repair/file-drift.tsindex 9bc874f985..6ecc8ca728 100644--- a/src/core/repair/file-drift.ts+++ b/src/core/repair/file-drift.ts@@ -54,7 +54,7 @@*/import { randomUUID } from 'node:crypto';import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';-import { join, sep } from 'node:path';+import { join, relative, sep } from 'node:path';import type { BrainEngine } from '../engine.ts';import { configDir } from '../config.ts';import { flushDirectory } from '../fs-durable.ts';@@ -65,11 +65,13 @@ import { matchesRepairPath } from './path-glob.ts';import { shellQuote } from '../agent-output.ts';import { commitPushCommand } from '../git/commit-push.ts';import type { ParsedPage } from '../import-file.ts';-import { digest, stableJson } from '../persistence/digest.ts';+import { digest, sha256, stableJson } from '../persistence/digest.ts';import { currentVerifiedLocalWriter, readLocalWriter, withVerifiedLocalRegistration } from '../persistence/identity.ts';import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';import { canonicalFilesystemPath } from '../persistence/root-registry.ts';-import { auditDriftConflicts, DRIFT_CLASSES, driftClass, liveFileDrift, type DriftClass } from '../persistence/drift-conflicts.ts';+import { auditDriftConflicts, DRIFT_CLASSES, driftClass, liveFileDrift, type DriftClass, type LiveDrift } from '../persistence/drift-conflicts.ts';+import { classifyDrift } from '../persistence/reconcile-additive.ts';+import { isUnboundSourcePage } from '../persistence/unbound-source.ts';import { protectedReconcileKey, reconcileCanonical, RECONCILE_SCAN_KEYS, type ReconcileDecision } from '../persistence/reconcile-merge.ts';import { fileWinsContent } from '../persistence/file-wins-content.ts';import { ABSENT_FILE_HASH, canonicalDeletionState, missingFileRoute, readCanonicalFileText, readDeletedDriftTarget, readReconcileState, assertReconcileRevision, validateReconcileArtifact, type DeletedDriftChange, type DeletedDriftTarget, type ReconcileArtifact } from '../persistence/reconcile-state.ts';@@ -727,6 +729,23 @@ async function applyDeletedSide(ctx: OperationContext, page: ApprovedPage, artif}}+/**+ * GST-2579: an unbound collision (#5254: a page an unbound write left database-only, and a file at its slug path that differs)+ * read as drift, so an exact --slug selection resolves it. `sources reconcile` refuses to take its database side over a file+ * the database never held and names this step, whose apply records the file as the page's origin and needs consent.+ */+async function unboundCollisionDrift(engine: BrainEngine, sourceId: string, slug: string): Promise<LiveDrift | null> {+ if (!await isUnboundSourcePage(engine, sourceId, slug)) return null;+ try {+ const state = await readReconcileState(engine, sourceId, slug);+ if (classifyDrift(state.file, reconcileCanonical(state.snapshot.page, state.snapshot.tags)).verdict === 'no_drift') return null;+ return { still_present: true, reason: 'unbound_collision', 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 null;+ throw error;+ }+}+/** GBRA-133: re-checks a held page whose page and file agreed at the preview and schedules its re-screen (`sources retry-held` for one path). */async function releaseAgreedHold(engine: BrainEngine, page: ApprovedPage, pin: ReleasePin, requestId: string): Promise<RepairItemOutcome> {const hold = await readGitHold(engine, page.source_id, pin.incarnation, pin.path);@@ -801,26 +820,31 @@ async function compareSelection(engine: BrainEngine, sourceId: string, opts: Rep/*** GST-2579: the consent wording of a file-drift apply, naming every file edit sync never imported that the previewed- * database-wins resolutions overwrite (the artifact's `discards`).+ * database-wins resolutions overwrite (the artifact's `discards`), and GST-2568: how many lines of the overwritten copies the+ * results do not carry (`lost_lines`).*/export function fileDriftConsentText(hash: string, sourceId: string | undefined): { what: string; why: string; risk: string; user_message: string } {let discards: UnimportedFile[] = [];let removals: string[] = [];+ let losing: number[] = [];try {const pages = [...readArtifact(hash, `gbrain repair file-drift --source ${sourceId ?? '<source>'}`).values()];discards = pages.flatMap(page => 'discards' in page && page.discards ? [page.discards] : []);removals = pages.flatMap(page => 'remove_file' in page ? [page.remove_file.path] : []);+ losing = pages.flatMap(page => 'lost_lines' in page && page.lost_lines ? [page.lost_lines] : []);} catch { /* the apply itself refuses a missing or changed artifact */ }const list = (items: string[]) => items.slice(0, 10).join('; ') + (items.length > 10 ? `; and ${items.length - 10} more (listed in the preview)` : '');const named = list(discards.map(unimportedFileText));+ const lost = losing.reduce((sum, lines) => sum + lines, 0);+ const dropping = lost ? ` It drops ${lost} line(s) that the copies it overwrites hold and the result does not carry, across ${losing.length} page(s).` : '';const removing = removals.length ? ` It also removes ${removals.length} file(s) that changed after their page was deleted, and the page does not hold what they say: ${list(removals)}.` : '';return {what: 'Apply the previewed file-drift resolutions: each listed page takes the preferred side, so either the canonical file is rewritten from the database copy or the page is replaced from the file.',- why: `The preview ${hash} listed each page and the side that wins it${discards.length ? `, and the file edits sync never imported that the database copy overwrites (${discards.length})` : ''}${removals.length ? `, and the files it removes (${removals.length})` : ''}.`,+ why: `The preview ${hash} listed each page and the side that wins it${discards.length ? `, and the file edits sync never imported that the database copy overwrites (${discards.length})` : ''}${removals.length ? `, and the files it removes (${removals.length})` : ''}${lost ? `, and the lines the overwritten copies hold that the result drops (${lost})` : ''}.`,risk: 'The losing side is replaced: a file rewrite is a new commit (git revert brings the edit back) and reconcile keeps a private backup of the replaced copy; a removed file comes back with git revert only when it was committed; a page that changed since the preview is skipped.',user_message: (discards.length? `Apply the previewed file-drift repair? It overwrites file edits sync never imported with the database copy: ${named}.`- : 'Apply the previewed file-drift repair? Each listed page takes the side the preview showed, and the other copy is replaced.') + removing,+ : 'Apply the previewed file-drift repair? Each listed page takes the side the preview showed, and the other copy is replaced.') + dropping + removing,};}@@ -901,7 +925,8 @@ export const fileDriftRepair: RepairHandler = {if (targetSlug === null) { count('no_page'); listing.push({ item: `${sourceId}:${label}`, class: 'no_page', detail: 'the hold names no page; the next sync re-classifies it' }); continue; }const slug = targetSlug;await authorizeReconcile(engine, sourceId, slug);- const live = await liveFileDrift(engine, sourceId, slug);+ const found = await liveFileDrift(engine, sourceId, slug);+ const live = opts.slugs?.length && found.reason === 'database_only' ? await unboundCollisionDrift(engine, sourceId, slug) ?? found : found;if (target && (target.state === 'file_gone') !== (live.reason === 'canonical_file_missing')) {count('side_changed');listing.push({ item: `${sourceId}:${slug}`, class: 'side_changed', detail: `its file is ${live.reason === 'canonical_file_missing' ? 'gone' : 'present'} now; gbrain sources status ${sourceId} --json shows its current Decision after the next sync` });diff --git a/test/db-wins-unimported-gst2579.test.ts b/test/db-wins-unimported-gst2579.test.tsindex fc48b0e807..8214bb9189 100644--- a/test/db-wins-unimported-gst2579.test.ts+++ b/test/db-wins-unimported-gst2579.test.ts@@ -12,7 +12,10 @@* - a database copy that is provably newer still wins: the file holds the bytes sync imported, or gbrain's write of a* revision the page has since moved past (a later, shorter database edit included, --all-drifted --only), or a blob* sync adopted into the page's import record (with the version history pruned), and the repair is listed and applied- * as before.+ * as before;+ * - an unbound collision (a database-only page from an unbound write, and another writer's file at its slug path) whose+ * database side a reconcile refuses to take is resolved by the step that refusal names: --slug --prefer database,+ * which names the commit, needs the user's consent and records the file as the page's origin.* Real PGLite (and Postgres when DATABASE_URL is set), a managed worktree with real Git commits; no seams.*/import { expect, test } from 'bun:test';@@ -45,6 +48,8 @@ const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root'-c', 'commit.gpgsign=false', ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();const FIRST = '---\ntype: concept\ntitle: A\n---\n\nThe first body.\n';const EDIT = '---\ntype: concept\ntitle: A\n---\n\nAn edit by another writer.\n';+const UNBOUND_DB = '---\ntype: note\ntitle: B\n---\n\nWritten while the source had no canonical owner.\n';+const UNBOUND_FILE = '---\ntype: note\ntitle: B\n---\n\nWritten into the checkout by another writer.\n';const WRITER_LINE = 'A line only gbrain\'s own writer committed.';const WRITER = `---\ntype: concept\ntitle: A\n---\n\nThe first body.\n\n${WRITER_LINE}\n`;const setup = ({ root }: { root: string }) => {@@ -197,7 +202,7 @@ for (const backend of testBackends()) {const preview = await runner(engine, { held: true, side: 'both', prefer: 'database' });expect(preview.affected).toBe(1);expect(preview.residuals.kept_newer_file).toBeUndefined();- expect(preview.listing!.find(entry => entry.item === 'default:notes/a')).toMatchObject({ class: 'prefer_database', detail: 'exactly the preferred side' });+ expect(preview.listing!.find(entry => entry.item === 'default:notes/a')).toMatchObject({ class: 'prefer_database', detail: 'exactly the preferred side; drops 1 line(s) the file holds' });expect((await runner(engine, { held: true, side: 'both', prefer: 'database', expect: preview.preview_hash })).outcomes).toEqual({ repaired: 1 });await settle();expect(readFileSync(join(root, 'notes/a.md'), 'utf8')).toContain('A database-only edit.');@@ -353,4 +358,42 @@ for (const backend of testBackends()) {expect((await engine.readPageSnapshot('notes/b', { sourceId: 'default' }))?.page.compiled_truth).toContain('Only ever in the working tree.');expect(fileHasEdit(root)).toBe(true);}), 240_000);++ test(`${backend}: an unbound collision's database side wins only through --slug --prefer database, named and with the user's consent`, () => managedBrain(async ({ engine, ctx, root }) => {+ await registerLocalWriter(engine, 'cli');+ expect((await performManagedSync(engine, SYNC)).status).toBe('first_sync');+ // The database row an unbound write leaves: database-only, with the #5254 marker and no origin.+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug: 'notes/b', content: UNBOUND_DB, request_id: randomUUID() } });+ await settleManagedGitEffects(engine);+ await engine.executeRaw("UPDATE pages SET database_only_reason='unbound_source', source_path=NULL, source_uri=NULL WHERE source_id='default' AND slug='notes/b'");+ // After binding, another writer commits a different file at its slug path, which no sync imported.+ writeFileSync(join(root, 'notes/b.md'), UNBOUND_FILE);+ git(root, 'add', '-A'); git(root, 'commit', '-qm', 'other writer file');+ const commit = git(root, 'rev-parse', 'HEAD');+ const fix = await cli(engine, async () => {+ const fresh = await runReconcilePreview(engine, { source_id: 'default', slug: 'notes/b' });+ const refused = await refusal(() => runReconcilePreview(engine, { source_id: 'default', slug: 'notes/b', from: fresh.preview,+ decisions: (fresh.conflict_paths as string[]).map(path => ({ path, action: 'take_database' })) }));+ expect(refused).toMatchObject({ code: 'source_changed', detail: 'unimported_file_edit' });+ return refused.fix as { argv: string[] };+ });+ expect(fix.argv).toEqual(['gbrain', 'repair', 'file-drift', '--source', 'default', '--slug', 'notes/b', '--prefer', 'database']);+ const preview = JSON.parse((await repairCli(engine, fix.argv.slice(3))).out).results[0];+ expect(preview.affected).toBe(1);+ const listed = preview.listing.find((entry: { item: string }) => entry.item === 'default:notes/b');+ expect(listed.class).toBe('prefer_database');+ expect(listed.detail).toContain(`discards commit ${commit.slice(0, 12)} by Other Writer`);+ const apply = [...fix.argv.slice(3), '--apply', '--expect', preview.preview_hash];+ const unconsented = await repairCli(engine, apply);+ expect(unconsented.exitCode).toBe(3);+ expect(unconsented.out).toContain(commit.slice(0, 12));+ await settle();+ expect(readFileSync(join(root, 'notes/b.md'), 'utf8')).toBe(UNBOUND_FILE);+ expect(JSON.parse((await repairCli(engine, [...apply, '--yes'])).out).results[0].outcomes).toEqual({ repaired: 1 });+ await settle();+ expect(readFileSync(join(root, 'notes/b.md'), 'utf8')).toContain('Written while the source had no canonical owner.');+ const [page] = await engine.executeRaw<{ source_path: string | null; database_only_reason: string | null }>(+ "SELECT source_path, database_only_reason FROM pages WHERE source_id='default' AND slug='notes/b'");+ expect(page).toEqual({ source_path: 'notes/b.md', database_only_reason: null });+ }, backendOpts(backend)), 240_000);}diff --git a/test/file-drift-normalisation-gst2568.test.ts b/test/file-drift-normalisation-gst2568.test.tsindex 05baa8df00..26a9988912 100644--- a/test/file-drift-normalisation-gst2568.test.ts+++ b/test/file-drift-normalisation-gst2568.test.ts@@ -43,6 +43,7 @@ import { registerLocalWriter, withVerifiedLocalRegistration } from '../src/core/import { FILE_DRIFT_VERSION, writeGitHold } from '../src/core/persistence/sync-holds.ts';import { performManagedSync } from '../src/core/persistence/sync-run.ts';import { resolveRepairScope, type RepairPlanOptions } from '../src/core/repair/core.ts';+import { fileDriftConsentText } from '../src/core/repair/file-drift.ts';import { repairRunner } from '../src/core/repair/registry.ts';import { managedBrain } from './helpers/managed-brain.ts';import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';@@ -254,6 +255,8 @@ for (const backend of testBackends()) {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)');+ // The consent the apply asks for says the same.+ expect(fileDriftConsentText(byFile.preview_hash!, 'default').user_message).toContain('It drops 2 line(s) that the copies 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');diff --git a/test/sync-pass-confirm-6712.test.ts b/test/sync-pass-confirm-6712.test.tsindex aac58df416..f17cbc8902 100644--- a/test/sync-pass-confirm-6712.test.ts+++ b/test/sync-pass-confirm-6712.test.ts@@ -24,7 +24,7 @@ import type { BrainEngine } from '../src/core/engine.ts';import type { OperationContext } from '../src/core/ops/contract.ts';import { installFaultHook } from '../src/core/persistence/fault-points.ts';import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';-import { readGitHold, SYNC_IMPORT_PROVENANCE_OP, writeGitHold } from '../src/core/persistence/sync-holds.ts';+import { FILE_DRIFT_VERSION, readGitHold, SYNC_IMPORT_PROVENANCE_OP, writeGitHold } from '../src/core/persistence/sync-holds.ts';import { performManagedSync } from '../src/core/persistence/sync-run.ts';import { __resetTreeReuseForTests } from '../src/core/persistence/sync-tree-reuse.ts';import { RECOVERY_VERSION } from '../src/core/markdown.ts';@@ -121,7 +121,8 @@ for (const backend of testBackends()) {const page = (await engine.readPageSnapshot('notes/c', { sourceId: 'default' }))!;await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation, path: 'notes/c.md', source_path: 'notes/c.md', slug: 'notes/c', page_id: Number(page.page.id),code: 'file_drift', message: 'Synthetic file_drift hold.', upstream_version: null, observed_at: new Date().toISOString(), run_id: null, mode: 'managed',- meta: { recovery_version: RECOVERY_VERSION, blob_oid: git(root, 'rev-parse', 'HEAD:notes/c.md'), page_revision: page.revision } } as never));+ // Screened by the current drift rule, so the pass leaves it alone (an older one is re-screened and released by the pass itself, GST-2568).+ meta: { recovery_version: RECOVERY_VERSION, drift_version: FILE_DRIFT_VERSION, blob_oid: git(root, 'rev-parse', 'HEAD:notes/c.md'), page_revision: page.revision } } as never));edit(root, 'notes/a', 'A committed change of notes/a.'); commit(root, 'change a');const run = await pass(engine, async () => { await engine.executeRaw("DELETE FROM op_checkpoints WHERE op='sync-hold' AND fingerprint=$1", [`default:${incarnation}:notes/c.md`]); });expect(round2(run)).toEqual({ taken: false, reason: 'holds', rows: 0 });