Skip to content

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.md
index 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.md
index 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 the
database 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 is
unchanged.
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 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 file
appears at the path of a database-only page after binding, sync stops for that
file with `source_changed` and reason `unbound_source`; neither copy is
overwritten 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 pages
per 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.ts
index 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: Dri
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 });