Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(file-drift): review fixes — backfill refusal only in previews, exhausted rows point at orphan-children, held argv for deleted-side fixes, guard negative test (GST-1555)
garrytan652b829f2b44
diff --git a/src/core/persistence/reconcile-state.ts b/src/core/persistence/reconcile-state.tsindex da721e34be..45ebfd54a8 100644--- a/src/core/persistence/reconcile-state.ts+++ b/src/core/persistence/reconcile-state.ts@@ -9,7 +9,7 @@ import { parseDataFrontmatter } from '../data-frontmatter.ts';import { OperationError, opError } from '../ops/contract.ts';import { readFix } from '../ops/op-fix.ts';import { REVISION_BACKFILL_PENDING, type PageSnapshot } from '../page-state/types.ts';-import { REVISION_BACKFILL_RESUME_COMMAND } from '../page-state/revision-backfill-schema.ts';+import { readRevisionBackfillStatus, REVISION_BACKFILL_MAX_ATTEMPTS, REVISION_BACKFILL_RESUME_COMMAND } from '../page-state/revision-backfill-schema.ts';import { isWriteTargetContained } from '../path-confine.ts';import { recordedPathFromFileUri, scannerSlugRootMode, scannerSourcePath } from '../write-through.ts';import { absentCanonicalPath, findLiveFileClaimants, recordedReconcilePath, type FileClaimTarget } from './file-claims.ts';@@ -230,10 +230,6 @@ export async function readReconcileState(engine: BrainEngine, sourceId: string,if (!snapshot || snapshot.page.deleted_at) throw opError('page_not_found', 'Reconciliation requires an existing live page; use the separate restore workflow for deleted pages.',`Page ${slug} in '${sourceId}' is deleted or missing; nothing changed. If it was deleted by mistake, restore it (gbrain restore, within the 72-hour window) and then preview it again.`,{ fix: readFix('Shows whether the page exists or is soft-deleted in this source.', { argv: ['gbrain', 'get', '--source', sourceId, '--include-deleted', '--', slug] }) });- if (snapshot.revision === REVISION_BACKFILL_PENDING) throw opError('revision_backfill_pending', 'Reconciliation requires the page revision, and this page has none yet.',- `Nothing changed. Page ${slug} in '${sourceId}' was written before page revisions and the revision backfill has not reached it, so no reconcile preview can bind to it. Resume the backfill on the brain host with ${REVISION_BACKFILL_RESUME_COMMAND} (the command in fix), then preview the page again.`,- { fix: { argv: REVISION_BACKFILL_RESUME_COMMAND.split(' '), consent: [], actor: 'agent', requires_exclusive: true, docs: 'docs/guides/write-refusals.md#revision-backfill',- why: 'Re-runs the schema migration pass on the brain host, which resumes the page revision backfill and prints its progress; it changes no page content.' } });if (binding.source_incarnation !== snapshot.sourceIncarnation) staleReconcile('source binding incarnation');const [storedPage] = await engine.executeRaw<Record<string, unknown>>(`SELECT id,source_id,slug,type,title,compiled_truth,timeline,frontmatter,content_hash,source_path,source_kind,source_uri,ingested_via,ingested_at,knowledge_revision,deleted_at FROM pages WHERE id=$1 AND source_id=$2`, [snapshot.page.id, sourceId]);@@ -319,6 +315,24 @@ export function reconcilePreviewAdopts(artifact: Pick<ReconcileArtifact, 'preimaconst stored = (artifact.preimages as { stored_page?: { source_path?: unknown; source_uri?: unknown } | null } | null)?.stored_page;return stored != null && stored.source_path == null && recordsNoFileOrigin({ source_uri: typeof stored.source_uri === 'string' ? stored.source_uri : null });}+/**+ * GST-1555: a reconcile preview binds the page's revision, so a page the revision backfill has not reached refuses before+ * anything is prepared. Its fix resumes the backfill, or, for a row that used every attempt, previews the torn-body repair.+ * Read-only classification (drift class, audit) reads such a page normally; only previews call this.+ */+export async function assertReconcileRevision(engine: BrainEngine, snapshot: PageSnapshot, sourceId: string, slug: string): Promise<void> {+ if (snapshot.revision !== REVISION_BACKFILL_PENDING) return;+ const exhausted = (await readRevisionBackfillStatus(engine)).failed.some(f => f.id === Number(snapshot.page.id) && f.attempts >= REVISION_BACKFILL_MAX_ATTEMPTS);+ const verify = { argv: ['gbrain', 'doctor', '--only', 'revision_backfill', '--json'] };+ throw opError('revision_backfill_pending', 'Reconciliation requires the page revision, and this page has none yet.',+ `Nothing changed. Page ${slug} in '${sourceId}' was written before page revisions and the revision backfill has not reached it, so no reconcile preview can bind to it. `+ + (exhausted ? 'The backfill used every attempt on this row (usually a torn page body): preview gbrain repair orphan-children (the command in fix) and recover the page from a backup or a re-sync, then preview it again.'+ : `Resume the backfill on the brain host with ${REVISION_BACKFILL_RESUME_COMMAND} (the command in fix), then preview the page again.`),+ { fix: exhausted+ ? { ...readFix('Previews orphaned child rows and lists torn page bodies (torn_pages) without changing anything.', { argv: ['gbrain', 'repair', 'orphan-children'] }), verify, docs: 'docs/guides/repair.md#orphan-children' }+ : { argv: REVISION_BACKFILL_RESUME_COMMAND.split(' '), consent: [], actor: 'agent', requires_exclusive: true, verify, docs: 'docs/guides/write-refusals.md#revision-backfill',+ why: 'Re-runs the schema migration pass on the brain host, which resumes the page revision backfill and prints its progress; it changes no page content.' } });+}export function assertReconcilePins(expected: ReconcilePins, actual: ReconcilePins): void {for (const key of Object.keys(expected) as Array<keyof ReconcilePins>) if (expected[key] !== actual[key]) staleReconcile(key);}diff --git a/src/core/persistence/reconcile.ts b/src/core/persistence/reconcile.tsindex b2d7a6227b..4b9805d062 100644--- a/src/core/persistence/reconcile.ts+++ b/src/core/persistence/reconcile.ts@@ -13,7 +13,7 @@ import { assertPersistenceAccepting, waitForWrite, writeResponse } from './serviimport { digest, requireUuid, sha256, stableJson } from './digest.ts';import { mergeReconcile, reconcileCanonical, reconcileDecisions, strictReconcileKeys } from './reconcile-merge.ts';import { additiveDecisions, assertAutoDecisions, classifyDrift, type AutoDecision, type DriftClassification } from './reconcile-additive.ts';-import { assertReconcilePins, readReconcileState, reconcilePreviewAdopts, reconcileReadOptions, staleReconcile, validateReconcileArtifact, type ReconcileArtifact, type ReconcileState } from './reconcile-state.ts';+import { assertReconcilePins, assertReconcileRevision, readReconcileState, reconcilePreviewAdopts, reconcileReadOptions, staleReconcile, validateReconcileArtifact, type ReconcileArtifact, type ReconcileState } from './reconcile-state.ts';import { prepareReconcileResult } from './reconcile-prepare.ts';import { assertReconcileOutputPath, assertReconcileSize, manageReconcileBackups, retainReconcileBackup } from './reconcile-backup.ts';import type { LocalGrant } from './identity.ts';@@ -116,6 +116,7 @@ export async function runReconcilePreview(engine: BrainEngine, params: Record<stconst state = await readReconcileState(engine, sourceId, slug, from?.preconditions.assessment_at,{ adoptSlugPath: params.adopt_slug_path === true || (from !== undefined && reconcilePreviewAdopts(from)) });if (from) assertPreimages(from, state);+ await assertReconcileRevision(engine, state.snapshot, sourceId, slug);const database = reconcileCanonical(state.snapshot.page, state.snapshot.tags);const classification = auto ? classifyDrift(state.file, database) : undefined;let decisions = reconcileDecisions(params.decisions ?? from?.decisions ?? []);diff --git a/src/core/repair/file-drift.ts b/src/core/repair/file-drift.tsindex 99ad7f8d05..d5a2ac20d6 100644--- a/src/core/repair/file-drift.ts+++ b/src/core/repair/file-drift.ts@@ -72,7 +72,7 @@ import { canonicalFilesystemPath } from '../persistence/root-registry.ts';import { auditDriftConflicts, DRIFT_CLASSES, driftClass, liveFileDrift, type DriftClass } from '../persistence/drift-conflicts.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, validateReconcileArtifact, type DeletedDriftChange, type DeletedDriftTarget, type ReconcileArtifact } from '../persistence/reconcile-state.ts';+import { ABSENT_FILE_HASH, canonicalDeletionState, missingFileRoute, readCanonicalFileText, readDeletedDriftTarget, readReconcileState, assertReconcileRevision, validateReconcileArtifact, type DeletedDriftChange, type DeletedDriftTarget, type ReconcileArtifact } from '../persistence/reconcile-state.ts';import { sourceDbOnlyVerdict } from '../persistence/source-storage.ts';import { clearGitHold, readGitHold, fileDriftActionVerb, fileDriftSide, FILE_DRIFT_DELETED_STATES, FILE_DRIFT_SIDES, GIT_HOLD_OP, heldDriftPreviewArgv, requestGitHoldRetry, type FileDriftDeletedState, type FileDriftSide, type GitHoldRecord } from '../persistence/sync-holds.ts';import { prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../persistence/file-repair.ts';@@ -506,6 +506,7 @@ export async function prepareDriftPage(engine: BrainEngine, sourceId: string, slconst database = reconcileCanonical(state.snapshot.page, state.snapshot.tags);const file = reconcileCanonical(state.file, state.file.tags);const decisions = preferSideDecisions(state.file, database, prefer);+ await assertReconcileRevision(engine, state.snapshot, sourceId, slug);const prepared = await prepareReconcileResult(engine, state, decisions);if (prepared.conflicts.length || !prepared.ready) throw opError('invalid_params', 'Some paths still need a decision.',`Preview ${slug} with gbrain sources reconcile ${sourceId} ${slug} --brain host --preview --out <file> and resolve it there.`);@@ -686,7 +687,10 @@ async function applyDeletedSide(ctx: OperationContext, page: ApprovedPage, artifif (acceptedPendingReceipt(error) || !(error instanceof OperationError) || ['owner_unavailable', 'writer_lock_unavailable', 'writer_busy', 'write_pending'].includes(error.code)) throw error;const changed = ['changed_since_preview', 'revision_conflict', 'page_identity_changed', 'page_not_found', 'source_changed'].includes(error.code);return { applied: false, outcome: changed ? 'changed_since_preview' : 'refused', reason: error.code,- detail: { request_id: requestId, action, message: error.message, fix: error.fix ?? repreviewFix(page, artifact.prefer) } };+ detail: { request_id: requestId, action, message: error.message, fix: error.fix ?? repreviewFix(page, 'detach_page' in artifact+ ? ['gbrain', 'repair', 'file-drift', '--source', page.source_id, '--held', '--side', 'deleted', '--state', 'file_gone', '--provenance', 'never_committed', '--prefer', 'database']+ : heldDriftPreviewArgv(page.source_id, 'deleted', ('remove_file' in artifact ? artifact.remove_file : artifact.import_file).state, artifact.prefer,+ ('remove_file' in artifact ? artifact.remove_file : artifact.import_file).path)) } };}}@@ -713,10 +717,9 @@ function provenanceText(found: DeletionProvenance): string {: 'provenance unknown: Git could not name the deleting commit';}-/** The next step after a page's apply refused or found it changed: preview that page alone again (read-only), which names its current refusal or a fresh apply command. */-function repreviewFix(page: ApprovedPage, prefer: DriftSide) {- return readFix(`Previews ${page.slug} in '${page.source_id}' alone again: it re-reads the page and its file and prints the current refusal with its fix, or a new apply command.`,- { argv: ['gbrain', 'repair', 'file-drift', '--source', page.source_id, '--slug', page.slug, '--prefer', prefer] });+/** The next step after a page's apply refused or found it changed: the preview that selects it again (read-only), which names its current refusal or a fresh apply command. */+function repreviewFix(page: ApprovedPage, argv: string[]) {+ return readFix(`Previews ${page.slug} in '${page.source_id}' again: it re-reads the page and its file and prints the current refusal with its fix, or a new apply command.`, { argv });}function item(page: ApprovedPage, index: number, hash: string, last: boolean, prefer: DriftSide): DriftItem {@@ -930,7 +933,7 @@ export const fileDriftRepair: RepairHandler = {const changed = error.code === 'revision_conflict' || error.code === 'page_identity_changed' || error.code === 'page_not_found'|| error.code === 'source_changed' && error.message.startsWith('Reconciliation preview is stale');outcome = { applied: false, outcome: changed ? 'changed_since_preview' : 'refused', reason: error.code,- detail: { request_id: requestId, message: error.message, fix: error.fix ?? repreviewFix(page, artifact.prefer) } };+ detail: { request_id: requestId, message: error.message, fix: error.fix ?? repreviewFix(page, ['gbrain', 'repair', 'file-drift', '--source', page.source_id, '--slug', page.slug, '--prefer', artifact.prefer]) } };}if (last) {await clearApprovedSet(ctx.engine, { command: 'file-drift', hash });diff --git a/test/file-drift-segmented-protected-gst1555.test.ts b/test/file-drift-segmented-protected-gst1555.test.tsindex b8e47ea7d3..0a419e9802 100644--- a/test/file-drift-segmented-protected-gst1555.test.ts+++ b/test/file-drift-segmented-protected-gst1555.test.ts@@ -29,6 +29,7 @@ import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';import { performManagedSync } from '../src/core/persistence/sync-run.ts';import { strictReconcileKeys } from '../src/core/persistence/reconcile-merge.ts';import { materializedSnapshot } from '../src/core/persistence/segmented-apply.ts';+import { REVISION_BACKFILL_MAX_ATTEMPTS, REVISION_BACKFILL_STATE_KEY } from '../src/core/page-state/revision-backfill-schema.ts';import { resolveRepairScope } from '../src/core/repair/core.ts';import { repairRunner } from '../src/core/repair/registry.ts';import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';@@ -126,6 +127,12 @@ for (const backend of testBackends()) describe(`GST-1555 file wins on a segmenteexpect(row!.detail).toStartWith('revision_backfill_pending: ');expect(row!.fix?.argv).toEqual(['gbrain', 'apply-migrations', '--force-schema']);expect(preview.details!.pages).toEqual([]);+ // A row the backfill gave up on (every attempt used) is not resumed by that command: the fix previews the torn-body repair.+ const [{ id }] = await engine.executeRaw<{ id: number }>("SELECT id FROM pages WHERE source_id='default' AND slug=$1", [SLUG]);+ await engine.setConfig(REVISION_BACKFILL_STATE_KEY, JSON.stringify({ cursor: Number(id), backfilled: 0, failed: [{ id: Number(id), attempts: REVISION_BACKFILL_MAX_ATTEMPTS, error: 'example' }] }));+ const exhausted = ((await fileDrift(engine, { slugs: [SLUG] })).listing as Listing)[0]!;+ expect(exhausted.detail).toStartWith('revision_backfill_pending: ');+ expect(exhausted.fix?.argv).toEqual(['gbrain', 'repair', 'orphan-children']);expect(readFileSync(join(root, `${SLUG}.md`), 'utf8')).toBe(before);}, { databaseUrl, setup: repo }), 240_000);@@ -151,6 +158,24 @@ for (const backend of testBackends()) describe(`GST-1555 file wins on a segmenteexpect((await fileDrift(engine, { slugs: [SLUG], expect: again.preview_hash })).outcomes).toEqual({ repaired: 1 });await assertImported(engine, root, before);}, { databaseUrl }), 240_000);++ test('a preview whose artifact its own apply would refuse is listed refused in the preview, with a fix, and approves nothing', () => managedBrain(async ({ engine, ctx, root }) => {+ // 40,000 frontmatter values pass the page's own reconcile check once, but the artifact carries them three times+ // (the stored row, the snapshot and the result), past the 100,000-value bound the apply's validation enforces.+ const refs = Array.from({ length: 40_000 }, (_, i) => i);+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug: 'notes/wide', request_id: randomUUID(),+ content: `---\ntype: note\ntitle: Wide\nrefs: [${refs.join(', ')}]\n---\n\nStored body.\n` } });+ await settleManagedGitEffects(engine);+ const file = join(root, 'notes/wide.md');+ writeFileSync(file, readFileSync(file, 'utf8').replace('Stored body.', 'File body.'));+ const preview = await fileDrift(engine, { slugs: ['notes/wide'] });+ const [row] = preview.listing as Listing;+ expect(row).toMatchObject({ item: 'default:notes/wide', class: 'refused' });+ expect(row!.detail).toStartWith('request_too_large: ');+ expect(row!.fix).toBeDefined();+ expect(preview.details!.pages).toEqual([]);+ expect(preview.affected).toBe(0);+ }, { databaseUrl }), 240_000);});describe('GST-1555 reconcile field refusals name the fields', () => {diff --git a/test/repair-file-drift-held-6712.test.ts b/test/repair-file-drift-held-6712.test.tsindex 37d9591bdd..da8dad57a2 100644--- a/test/repair-file-drift-held-6712.test.ts+++ b/test/repair-file-drift-held-6712.test.ts@@ -249,6 +249,8 @@ for (const backend of testBackends()) describe(`#6712 PR 4b: repair file-drift -writeFileSync(join(f.root, path), page('notes/tomb', 'Edited again after the preview.'));const applied = await run(f.sourceId, { side: 'deleted', state: 'tombstone_edited', prefer: 'database', expect: preview.preview_hash! });expect(applied.outcomes).toEqual({ changed_since_preview: 1 });+ // GST-1555: the outcome carries the refusal's own next step.+ expect((applied.outcome_items![0]!.detail!.fix as { argv: string[] }).argv).toEqual(['gbrain', 'sources', 'status', f.sourceId, '--json']);expect(readFileSync(join(f.root, path), 'utf8')).toContain('Edited again after the preview.');expect(await readGitHold(engine, f.sourceId, f.incarnation, path)).not.toBeNull();}), 240_000);