Skip to content

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.ts
index 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, 'preima
const 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.ts
index b2d7a6227b..4b9805d062 100644
--- a/src/core/persistence/reconcile.ts
+++ b/src/core/persistence/reconcile.ts
@@ -13,7 +13,7 @@ import { assertPersistenceAccepting, waitForWrite, writeResponse } from './servi
import { 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<st
const 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.ts
index 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, sl
const 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, artif
if (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.ts
index 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 segmente
expect(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 segmente
expect((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.ts
index 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);