Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytanab4ff65547eb
diff --git a/docs/guides/git-canonical.md b/docs/guides/git-canonical.md
index ae35956815..271955e3a6 100644
--- a/docs/guides/git-canonical.md
+++ b/docs/guides/git-canonical.md
@@ -108,7 +108,7 @@ recorded):
| `adopt_db_moved` | An older version of the page equals the committed file, and no newer state was shared: only the database moved. | adopt |
| `git_wins_file_moved` | The page equals an older committed blob of its path, and no newer state was shared: only the file moved (a plain `git commit`, for example). | git wins (`file_moved`) |
| `both_moved` | Both sides moved since the last state they shared. A revert counts as a move: a page reverted to an older state while Git edited the file is `both_moved`, not `git_wins_file_moved`. | discard until decided |
-| `no_evidence` | Nothing shared within the depth (no archived version, a path with one blob, a segmented page whose export matches no blob or that has a version archived after the matching blob), or the other side's history reached the depth or lost versions to pruning (basis `history_truncated`). | discard until decided |
+| `no_evidence` | Nothing shared within the depth (no archived version, a path with one blob, a segmented page whose export matches no blob or that has any archived version, which cannot be compared by content), or the other side's history reached the depth or lost versions to pruning (basis `history_truncated`). | discard until decided |
A later `updated_at` on the database row changes nothing here. The evidence
kind of each page is part of the preview hash, and `gbrain sources git-gap
diff --git a/src/commands/sources-canonical.ts b/src/commands/sources-canonical.ts
index 3f63c19b6e..46ae757151 100644
--- a/src/commands/sources-canonical.ts
+++ b/src/commands/sources-canonical.ts
@@ -4,6 +4,7 @@
* prints the plan, by category with counts and a capped sample of paths, and its hash; `--apply --expect <hash>` runs it
* (persistence/git-conversion.ts). Trusted local CLI on a managed brain only; not an MCP operation, since it prints paths.
*/
+import { resolve } from 'node:path';
import type { BrainEngine } from '../core/engine.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { OperationError, opError } from '../core/ops/contract.ts';
@@ -168,10 +169,11 @@ export async function runSourcesCanonical(engine: BrainEngine, args: string[]):
...(parsed.listOut ? { review_list: await writeConversionFile(engine, parsed.listOut, '--list-out', await conversionReviewList(engine, plan)) } : {}),
...(parsed.approvalOut ? { approval: await writeConversionFile(engine, parsed.approvalOut, '--approval-out', conversionApproval(plan)) } : {}) };
const files = Object.entries(written).map(([kind, path]) => `Wrote the ${kind.replace('_', ' ')} (mode 0600) to ${path}.`);
- print({ ...plan.preview, ...(Object.keys(written).length ? { written } : {}) }, [describeGitPreview(plan.preview), ...files].join('\n'));
+ const preview = parsed.decisions ? { ...plan.preview, apply: [...plan.preview.apply, '--decisions', resolve(parsed.decisions)] } : plan.preview;
+ print({ ...preview, ...(Object.keys(written).length ? { written } : {}) }, [describeGitPreview(preview), ...files].join('\n'));
return;
}
- const processing = { noEmbed: parsed.noEmbed, noExtract: parsed.noExtract, decisions };
+ const processing = { noEmbed: parsed.noEmbed, noExtract: parsed.noExtract, decisions, ...(parsed.decisions ? { decisionsFile: resolve(parsed.decisions) } : {}) };
const approval = parsed.approved ? await readConversionApproval(engine, parsed.approved, parsed.sourceId) : null;
const result = await withConversionReport(engine, parsed.sourceId, json, onProgress => approval
? applyApprovedConversion(engine, parsed.sourceId, approval, { ...processing, onProgress })
diff --git a/src/core/persistence/git-conversion.ts b/src/core/persistence/git-conversion.ts
index 9a92dcb34a..b16aa5f578 100644
--- a/src/core/persistence/git-conversion.ts
+++ b/src/core/persistence/git-conversion.ts
@@ -40,7 +40,7 @@
* remaining categories are reported. `--to mixed` removes the flag and changes nothing else.
*/
import { chmodSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { SyncOpts, SyncResult } from '../../commands/sync.ts';
import type { Action } from '../agent-output.ts';
@@ -223,7 +223,7 @@ export async function assertOutsideSourceRoots(engine: BrainEngine, file: string
const top = gitTopLevel(base);
for (const fence of new Set([base, ...(top ? [top] : [])])) for (const path of new Set([real, linked])) {
const inside = relative(fence, path);
- if (inside !== '' && (inside.startsWith('..') || inside.startsWith(sep) || /^[A-Za-z]:/.test(inside))) continue;
+ if (inside !== '' && (inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside))) continue;
throw opError('conversion_file_in_source_root', `${flag} ${file} is inside source ${root.id}'s checkout (${fence}), so it was refused: a review or decisions file names pages and must never be synced or committed.`,
`Pass a path outside ${fence} and every other source checkout, e.g. under ~/.gbrain when your home directory is not inside it.`, { docs: DOCS });
}
@@ -702,9 +702,9 @@ export function conversionRollback(sourceId: string, mode: 'mixed' | 'git'): str
/** The apply of `--to git` (see the header). Throws preview_changed or git_conversion_blocked before writing anything. */
export async function applyGitConversion(engine: BrainEngine, sourceId: string, expect: string,
- opts: { noEmbed?: boolean; noExtract?: boolean; onProgress?: (progress: ConversionProgress) => void; decisions?: ConversionDecision[] } = {}): Promise<GitConversionResult> {
+ opts: { noEmbed?: boolean; noExtract?: boolean; onProgress?: (progress: ConversionProgress) => void; decisions?: ConversionDecision[]; decisionsFile?: string } = {}): Promise<GitConversionResult> {
const plan = await planGitConversion(engine, sourceId, { decisions: opts.decisions });
- if (plan.preview.preview_hash !== expect) throw previewChangedError(expect, `gbrain sources canonical ${sourceId} --to git --dry-run`);
+ if (plan.preview.preview_hash !== expect) throw previewChangedError(expect, `gbrain sources canonical ${sourceId} --to git --dry-run${opts.decisionsFile ? ` --decisions ${opts.decisionsFile}` : ''}`);
return runConversion(engine, plan, expect, opts);
}
diff --git a/src/core/persistence/git-gap.ts b/src/core/persistence/git-gap.ts
index 4fa2049f14..75a8fab142 100644
--- a/src/core/persistence/git-gap.ts
+++ b/src/core/persistence/git-gap.ts
@@ -310,8 +310,8 @@ interface HistoryEntry { oid: string; at: number; seq: number }
/**
* One filter-free `git log --raw` walk of `tip` under `scope` (Git-root relative; '' is the whole repository): per path of
- * `interest` (Git-root relative), the distinct blobs it held, newest first, at most `depth` + 1 each (the tip's own blob
- * is usually the first). Null when Git could not answer.
+ * `interest` (Git-root relative), the blobs it held, newest first, a blob it held again after another kept again (a
+ * revert), at most `depth` + 1 each (the tip's own blob is usually the first). Null when Git could not answer.
*/
export async function readPathHistory(root: string, tip: string, scope: string, interest: ReadonlySet<string>, depth = EVIDENCE_DEPTH): Promise<Map<string, HistoryEntry[]> | null> {
const history = new Map<string, HistoryEntry[]>();
@@ -327,7 +327,7 @@ export async function readPathHistory(root: string, tip: string, scope: string,
raw = null;
if (!interest.has(path) || status === 'D' || (mode !== '100644' && mode !== '100755')) continue;
const list = history.get(path) ?? [];
- if (list.length <= depth && !list.some(entry => entry.oid === oid)) list.push({ oid, at, seq: seq++ });
+ if (list.length <= depth && list.at(-1)?.oid !== oid) list.push({ oid, at, seq: seq++ });
history.set(path, list);
continue;
}
@@ -360,10 +360,12 @@ export async function readBlobSizes(root: string, oids: readonly string[]): Prom
* (the tip's excluded), each newest first with its digest (null when it does not parse); `capped` says a list reached
* EVIDENCE_DEPTH, so older entries exist that were not read.
*
- * A one-sided verdict needs the matched state to be the newest state both sides shared. The row equals an older blob
- * (only the file moved) unless a state newer than that blob was shared with an older version that differs from the row:
- * then the database left it too (a revert to the row's content is a move). The mirror holds for the file equal to an
- * older version. When the other side's list is capped, a newer shared state may lie past it, so the verdict is no_evidence.
+ * A one-sided verdict needs the matched state to be the newest state both sides shared, and the side that did not move
+ * to have stayed there. The row equals an older blob (only the file moved) unless a state newer than that blob was shared
+ * with an older version that differs from the row, or an archived copy of the row's state is followed by a version that
+ * differs from it (the database left that state and came back: a revert is a move). The mirror holds for the file equal
+ * to an older version, `blobs` keeping a blob the path held again. When the other side's list is capped, a newer shared
+ * state may lie past it, so the verdict is no_evidence.
*/
export function decideDirection(row: string, head: string | null, versions: ReadonlyArray<{ id: number; digest: string }>,
blobs: ReadonlyArray<{ oid: string; digest: string | null }>, capped: { versions: boolean; blobs: boolean } = { versions: false, blobs: false }): Pick<Evidence, 'kind' | 'basis' | 'blob' | 'version'> {
@@ -372,7 +374,11 @@ export function decideDirection(row: string, head: string | null, versions: Read
const fileMoved = fileAt >= 0 ? blobs[fileAt]! : undefined, databaseMoved = databaseAt >= 0 ? versions[databaseAt]! : undefined;
const sharedNewerThanBlob = fileAt >= 0 && blobs.slice(0, fileAt).some(blob => blob.digest !== null && blob.digest !== row && versions.some(version => version.digest === blob.digest));
const sharedNewerThanVersion = databaseAt >= 0 && versions.slice(0, databaseAt).some(version => version.digest !== head && blobs.some(blob => blob.digest === version.digest));
- if ((fileMoved && databaseMoved) || sharedNewerThanBlob || sharedNewerThanVersion) {
+ const rowArchived = fileAt >= 0 ? versions.map(version => version.digest).lastIndexOf(row) : -1;
+ const databaseLeftRow = rowArchived > 0 && versions.slice(0, rowArchived).some(version => version.digest !== row);
+ const headCommitted = databaseAt >= 0 ? blobs.map(blob => blob.digest).lastIndexOf(head) : -1;
+ const fileLeftHead = headCommitted > 0 && blobs.slice(0, headCommitted).some(blob => blob.digest !== head);
+ if ((fileMoved && databaseMoved) || sharedNewerThanBlob || sharedNewerThanVersion || databaseLeftRow || fileLeftHead) {
return { kind: 'both_moved', basis: 'conflicting_history', blob: fileMoved?.oid ?? null, version: databaseMoved?.id ?? null };
}
if (fileMoved) return capped.versions ? { kind: 'no_evidence', basis: 'history_truncated', blob: fileMoved.oid, version: null }
@@ -387,7 +393,7 @@ export function decideDirection(row: string, head: string | null, versions: Read
}
type VersionRow = { id: number; page_id: string; compiled_truth: string | null; frontmatter: unknown; timeline: string | null; title: string | null; type: string | null; tags: unknown;
- segmented: boolean; is_deleted: boolean | null; snapshot_at: number | string };
+ segmented: boolean; is_deleted: boolean | null };
const json = <T>(value: unknown, fallback: T): T => value == null ? fallback : typeof value === 'string' ? JSON.parse(value) as T : value as T;
/**
@@ -419,8 +425,13 @@ export async function readDirectionEvidence(engine: BrainEngine, input: { source
if (!history) { for (const subject of subjects) out.set(subject.id, none('history_unreadable')); return out; }
const older = (subject: EvidenceSubject) => {
const merged = [...paths.get(subject.id)!].flatMap(path => history.get(path) ?? []).sort((a, b) => a.seq - b.seq);
- const seen = new Set<string>([subject.blob.oid]), list: HistoryEntry[] = [];
- for (const entry of merged) if (!seen.has(entry.oid) && list.length < EVIDENCE_DEPTH) { seen.add(entry.oid); list.push(entry); }
+ const seen = new Set<string>(), list: HistoryEntry[] = [];
+ let pastTip = false;
+ for (const entry of merged) {
+ if (!pastTip && entry.oid === subject.blob.oid) continue;
+ pastTip = true;
+ if (!seen.has(entry.oid) && list.length < EVIDENCE_DEPTH) { seen.add(entry.oid); list.push(entry); }
+ }
return { list, committed_at: merged[0]?.at ?? null, capped: list.length >= EVIDENCE_DEPTH || [...paths.get(subject.id)!].some(path => (history.get(path)?.length ?? 0) > EVIDENCE_DEPTH) };
};
const withdrawals = await readExportWithdrawals(engine, sourceId);
@@ -434,7 +445,7 @@ export async function readDirectionEvidence(engine: BrainEngine, input: { source
const current = batch.filter(subject => live.has(subject.id) && live.get(subject.id) === subject.revision);
const snapshots = await readExportPages(tx, current.map(subject => ({ id: subject.id, source_id: sourceId, slug: subject.slug })), withdrawals);
const versions = current.length ? await tx.executeRaw<VersionRow>(`SELECT id, page_id::text AS page_id, compiled_truth, frontmatter, timeline, title, type, tags,
- COALESCE(body_storage,'inline')='segmented' AS segmented, is_deleted, EXTRACT(EPOCH FROM snapshot_at)::float8 AS snapshot_at FROM (SELECT v.*, row_number() OVER (PARTITION BY v.page_id ORDER BY v.id DESC) AS rank FROM page_versions v
+ COALESCE(body_storage,'inline')='segmented' AS segmented, is_deleted FROM (SELECT v.*, row_number() OVER (PARTITION BY v.page_id ORDER BY v.id DESC) AS rank FROM page_versions v
WHERE v.page_id = ANY(string_to_array($1::text, ',')::int[])) ranked WHERE rank <= $2 ORDER BY page_id, id DESC`, [current.map(subject => subject.id).join(','), EVIDENCE_DEPTH]) : [];
const segmentedOids = new Map<string, Set<string>>();
for (const [i, subject] of current.entries()) {
@@ -474,8 +485,7 @@ export async function readDirectionEvidence(engine: BrainEngine, input: { source
if (subject.segmented) {
const match = list.find(entry => read.segmentedOids.get(subject.id)?.has(entry.oid));
const rows = byPage.get(subject.id) ?? [];
- const movedSince = !!match && (read.gaps.has(subject.id) || rows.some(row => Number(row.snapshot_at) > match.at));
- out.set(subject.id, match && !movedSince ? { kind: 'git_wins_file_moved', basis: 'row_matches_older_file', blob: match.oid, version: null, versions: rows.length, blobs: list.length, committed_at }
+ out.set(subject.id, match && !rows.length && !read.gaps.has(subject.id) ? { kind: 'git_wins_file_moved', basis: 'row_matches_older_file', blob: match.oid, version: null, versions: rows.length, blobs: list.length, committed_at }
: { ...none('segmented', committed_at), blob: match?.oid ?? null, versions: rows.length, blobs: list.length });
continue;
}
diff --git a/test/git-canonical-conversion-evidence-d4.test.ts b/test/git-canonical-conversion-evidence-d4.test.ts
index f33a4a880e..6ad63105a2 100644
--- a/test/git-canonical-conversion-evidence-d4.test.ts
+++ b/test/git-canonical-conversion-evidence-d4.test.ts
@@ -120,7 +120,11 @@ for (const backend of testBackends()) describe(`[${backend}] conversion by conte
await databaseOnlyEdit(engine, 'notes/none', DB_EDIT('notes/none'));
const again = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const final = await planGitConversion(engine, 'default', { decisions: again });
- expect(await applyGitConversion(engine, 'default', final.preview.preview_hash, { ...PROCESSING, decisions: again })).toMatchObject({ status: 'converted', reclassified: [] });
+ // The printed apply carries the decisions file the hash binds, so running it exactly as printed applies.
+ const printed = await cli(engine, ['default', '--to', 'git', '--dry-run', '--decisions', join(files.dir, 'decisions.json')]);
+ expect(printed.apply).toEqual(['gbrain', 'sources', 'canonical', 'default', '--to', 'git', '--apply', '--expect', final.preview.preview_hash, '--decisions', join(files.dir, 'decisions.json')]);
+ expect(again).toHaveLength(2);
+ expect(await cli(engine, [...printed.apply.slice(3), '--no-embed', '--no-extract'])).toMatchObject({ status: 'converted', reclassified: [] });
expect(await body(engine, 'notes/file')).toContain(GIT_EDIT('notes/file'));
expect(await body(engine, 'notes/both')).toContain(GIT_EDIT('notes/both'));
expect(await body(engine, 'notes/db')).toContain(DB_EDIT('notes/db'));
diff --git a/test/git-gap-direction-evidence-d4.test.ts b/test/git-gap-direction-evidence-d4.test.ts
index 48006791ad..d6d3a36d39 100644
--- a/test/git-gap-direction-evidence-d4.test.ts
+++ b/test/git-gap-direction-evidence-d4.test.ts
@@ -47,6 +47,12 @@ describe('decideDirection (d4 classifier)', () => {
expect(decideDirection('C', 'A', [v(3, 'B'), v(2, 'A')], [b('oB', 'B'), b('oA', 'A')])).toMatchObject({ kind: 'both_moved', basis: 'conflicting_history' });
expect(decideDirection('B', 'C', [v(3, 'B'), v(2, 'A')], [b('oB', 'B'), b('oA', 'A')])).toMatchObject({ kind: 'git_wins_file_moved', blob: 'oB' });
expect(decideDirection('C', 'B', [v(4, 'C'), v(3, 'B'), v(2, 'A')], [b('oA', 'A')])).toMatchObject({ kind: 'adopt_db_moved', version: 3 });
+ // A revert whose middle state the other side never held: the database went A to B and back while Git edited A to C,
+ // and the mirror, Git going A to B and back (the tip's blob held again) while the database went A to C.
+ expect(decideDirection('A', 'C', [v(3, 'B'), v(2, 'A')], [b('oA', 'A')])).toMatchObject({ kind: 'both_moved', basis: 'conflicting_history' });
+ expect(decideDirection('C', 'A', [v(2, 'A')], [b('oB', 'B'), b('oA', 'A')])).toMatchObject({ kind: 'both_moved', basis: 'conflicting_history' });
+ // A no-op write that archived the row's own content is no move.
+ expect(decideDirection('A', 'C', [v(3, 'A')], [b('oA', 'A')])).toMatchObject({ kind: 'git_wins_file_moved', blob: 'oA' });
});
test('a one-sided verdict needs the other side read in full', () => {
const full = { versions: false, blobs: false };
@@ -114,7 +120,9 @@ for (const backend of testBackends()) describe(`git-gap direction evidence (d4):
}, 120000);
test('the timestamp trap: a non-content updated_at bump after a file edit still goes to Git', async () => {
- await fixture();
+ const root = await fixture();
+ // A file name that starts with two dots is still inside the checkout.
+ await expect(writeConversionFile(engine, join(root, '..review.json'), '--list-out', {})).rejects.toMatchObject({ code: 'conversion_file_in_source_root' });
await engine.executeRaw("UPDATE pages SET updated_at = now() + interval '30 days' WHERE slug IN ('notes/file-moved','notes/both-moved')");
const pages: GitGapPage[] = [];
await censusGitGap(engine, 'default', { sample: 0, evidence: true, collect: page => { pages.push(page); } });
@@ -172,7 +180,7 @@ for (const backend of testBackends()) describe(`git-gap direction evidence (d4):
expect(await writeConversionFile(engine, join(outside, 'review.json'), '--list-out', {})).toBe(join(outside, 'review.json'));
}, 120000);
- test('a segmented page: an older blob equal to its export lets Git win only while no version was archived after that blob', async () => {
+ test('a segmented page: an older blob equal to its export lets Git win only while the page has no archived version', async () => {
const root = tempDir('git-gap-segmented-');
git(root, 'init', '-q');
await engine.executeRaw("UPDATE sources SET local_path=$1 WHERE id='default'", [root]);
@@ -195,11 +203,29 @@ for (const backend of testBackends()) describe(`git-gap direction evidence (d4):
return pages.find(page => page.slug === 'seg/page')?.evidence;
};
expect(await evidence()).toMatchObject({ kind: 'git_wins_file_moved', basis: 'row_matches_older_file' });
- // A version archived after that blob means the database left that state and came back (a revert): not a one-sided move.
- await engine.executeRaw("INSERT INTO page_versions (page_id, compiled_truth, frontmatter, snapshot_at) VALUES ($1, 'An archived state.', '{}', now() + interval '1 minute')", [id]);
+ // Its archived versions cannot be compared by content, so any one of them may be a revert: not a one-sided move.
+ await engine.executeRaw("INSERT INTO page_versions (page_id, compiled_truth, frontmatter, snapshot_at) VALUES ($1, 'An archived state.', '{}', now() - interval '1 day')", [id]);
expect(await evidence()).toMatchObject({ kind: 'no_evidence', basis: 'segmented' });
}, 120000);
+ test('a Git revert under a database edit is both_moved: the path\'s history keeps a blob it held again', async () => {
+ const root = tempDir('git-gap-git-revert-');
+ git(root, 'init', '-q');
+ await engine.executeRaw("UPDATE sources SET local_path=$1 WHERE id='default'", [root]);
+ await body('notes/g', 'Body A.');
+ const a = await rendered('notes/g');
+ put(root, 'notes/g.md', a);
+ commitAll(root, 'A');
+ put(root, 'notes/g.md', a.replace('Body A.', 'Body B.'));
+ commitAll(root, 'B');
+ put(root, 'notes/g.md', a);
+ commitAll(root, 'back to A');
+ await engine.createVersion('notes/g'); await body('notes/g', 'Body C.');
+ const pages: GitGapPage[] = [];
+ await censusGitGap(engine, 'default', { sample: 0, evidence: true, collect: page => { pages.push(page); } });
+ expect(pages.find(page => page.slug === 'notes/g')).toMatchObject({ evidence: { kind: 'both_moved', basis: 'conflicting_history' } });
+ }, 120000);
+
test('a pruned version history counts as unread: an inline page with a history gap gets no one-sided Git verdict', async () => {
await fixture();
await engine.executeRaw("UPDATE pages SET version_history_gap_at = now() WHERE slug = 'notes/file-moved'");