Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytan572ead41bc81
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index f3448ef00b..5bdac9f887 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -221,7 +221,7 @@ work behind exits 0, so scripts should also check `results[].complete`.
| `contextual-mode` | `contextual_retrieval_coverage` (pages with no recorded mode) | Stamps the contextual retrieval mode on markdown pages imported without one (for example by a large `--no-embed` sync, or by a connector source on an older gbrain), exactly as a fresh import of the page would: the page, source and brain settings decide, and the per-chunk synopsis tier lands at the free title tier. It rebuilds projections only: no page write, no new page version and no request ID. A page whose stored vectors already match the stamped convention keeps them and queues no re-embedding; a page whose embedding input changes has only those vectors cleared and is re-embedded once, unless you pass `--no-embed`. | `unsealed_projection`: pages whose chunks lag their text; `gbrain embed --stale` or `safe-chunks` seals them first, and the next run stamps them. `embed_skip`: pages marked to skip embedding keep their stored vectors and are not stamped. |
| `file-drift` | `maintenance_write_drift` | Explicit-only, preview-bound. Resolves pages whose canonical file differs from the database copy (`source_changed` / `file_database_drift`) through canonical reconciliation, preferring the file or the database copy within reconcile's protections. `--all-drifted` refuses mixed drift classes unless `--class` keeps one; `--only`/`--skip` narrow by canonical file path glob. Opt-in `storage.keep_db` lets the owner host's resident consumer resolve drift under declared prefixes with the database copy. A page whose file is gone from the last commit: `--prefer database` recreates the file, `--prefer file` soft-deletes the page ([deleted canonical files](#deleted-canonical-files)). See [file drift](#file-drift). | Protected metadata, the tag union and protected takes or private fact rows, listed per page as `exceptions`; pages changed after the preview (`changed_since_preview`). |
| `ghost-pages` | `ghost_pages` | Explicit-only, preview-bound, destructive consent. Soft-deletes live pages whose canonical file is missing on the owner host (ghost pages: every write refuses `canonical_file_missing` and no sync can import a file that is not there), through `delete_page` bound to the previewed owner, path and revision. `--apply --expect <hash> --yes`. See [ghost pages](#ghost-pages). | Declared db_only and never-filed derived pages (never listed); a page whose file came back before the apply (`file_restored`); pages changed after the preview (`changed_since_preview`). |
-| `moved-pages` | `ghost_pages` | Explicit-only, preview-bound, destructive consent. Folds a page left behind by a file that moved into the page the moved file imported as (GST-2584): when sync held the old page's deletion (`file_gone`), the new path imported as a fresh page. A page folds only on proof read from Git: its old path's last committed content is what one new path took at the move (or in that path's first commit), and the old page still holds it. Its links, relationship dates, timeline, raw data, files, user tags, aliases, facts and saved versions move to the moved page, its slug becomes an alias, its hold is cleared and it is soft-deleted (restorable for 72 h); no file is written. `--apply --expect <hash> --yes`. See [moved pages](#moved-pages). | Every other page whose file is gone, listed `held:<reason>`: `several_candidates`, `both_changed` (edited in the database after the move), `first_blob_differs`, `same_id_body_differs`, `evidence_conflicts`, `history_shallow`, `history_unknown`, `deletion_not_committed`, `not_moved`. |
+| `moved-pages` | `ghost_pages` | Explicit-only, preview-bound, destructive consent. Folds a page left behind by a file that moved into the page the moved file imported as (GST-2584): when sync held the old page's deletion (`file_gone`), the new path imported as a fresh page. A page folds only on proof read from Git: its old path's last committed content is what one new path took at the move (or in that path's first commit), and the old page still holds it. Its links, relationship dates, timeline, raw data, files, user tags, aliases, facts and saved versions move to the moved page, its slug becomes an alias, its hold is cleared and it is soft-deleted (restorable for 72 h); no file is written. `--apply --expect <hash> --yes`. See [moved pages](#moved-pages). | Every other page whose file is gone, listed `held:<reason>`: `several_candidates`, `shared_survivor` (another old page with the same content claims the same moved page), `segmented_versions` (the page or a saved version is stored in segments, over 1 MiB), `both_changed` (edited in the database after the move), `first_blob_differs`, `same_id_body_differs`, `evidence_conflicts`, `history_shallow`, `history_unknown`, `deletion_not_committed`, `not_moved`. |
| `uncommitted-deletions` | `uncommitted_sync_deletions` | Explicit-only, preview-bound, consent. Restores soft-deleted pages a managed sync removed before #7130 although Git never held their recorded file (`.gitignore` excludes it, or no commit holds it and it is not on the disk), one `restore_page` with `detach` each, published database-only: the page comes back live, forgets its recorded file, and no file is written. `--apply --expect <hash> --yes`. See [uncommitted deletions](#uncommitted-deletions). | Pages another writer deleted (listed, restored only with `--include-ambiguous`); tombstones whose file Git once committed or that is on the disk again; paths Git could not answer for (`unknown`); purged pages (only a backup brings them back). |
| `rows-behind` | `sync_rows_behind_checkpoint` | Explicit-only, preview-bound. Re-imports live pages of a managed source whose row holds an older version of its file than the sync checkpoint (`sources.last_commit`) says was imported, with no hold (#8071), from the file as committed at the checkpoint, through the managed file repair (no file is written). A file whose import is refused, or that is over the sync read bound, is held with that code instead. `--source <id>`, then `--apply --expect <hash>`. See [rows behind the checkpoint](#rows-behind). | Rows with no import record (`excluded:unproven`, joined with `--include-ambiguous`; one whose older version equals its committed file, so the database moved since, never joins: `excluded:database_moved`, nor one whose page and file both moved: `excluded:both_moved`), rows with an uncommitted working-tree edit (`excluded:worktree_differs`), rows whose import would keep page data the file does not carry (`excluded:import_overlay`); rows that moved after the preview (`changed_since_preview`). |
| `receipt-compaction` | `persistence_capacity` (terminal bytes) | Explicit-only, preview-bound, destructive consent. Compacts terminal write receipts now instead of on the idle maintenance tick (#6696): the intent and error message are dropped, the outcome, error code and detail stay, and the unused reservation returns to the receipt-bytes counters. `--older-than <72h\|30d>` is floored at the configured retention unless `--force`; committed receipts only unless `--include-failures`. No admission, so it runs at a full cap. See [receipt compaction](#receipt-compaction). | `failures_kept`: failed, conflict and cancelled receipts left without `--include-failures`. Receipts of a run whose sync cursor is still open, and the newest sync receipt of each worktree, are never listed. |
@@ -1908,7 +1908,11 @@ A page folds only on two facts read from Git and the page, never on what the mov
Exactly one live page may descend from that content. The file name only explains a page with no candidate, because a
move can rename the file too, and a matching frontmatter `id` alone never pairs two pages. Every other page whose file
-is gone is listed with why it is kept: `several_candidates`, `both_changed` (the old page was edited in the database
+is gone is listed with why it is kept: `several_candidates`, `shared_survivor` (two or more old pages deleted with the
+same content each still back a live page and claim one moved page: the user picks which one moved, and the others are
+retired with `gbrain repair ghost-pages`; the preview then folds the one left), `segmented_versions` (the old page or one
+of its saved versions is stored in segments, over 1 MiB; segmented versions name their own page's body, so this repair
+does not move them and the page stays as it is), `both_changed` (the old page was edited in the database
after the move: decide with the user), `first_blob_differs` (a page with the same file name started from other content),
`same_id_body_differs`, `evidence_conflicts` (a manual link or timeline entry that differs from the moved page's),
`history_shallow` (run `git fetch --unshallow` and preview again), `history_unknown`, `deletion_not_committed` and
diff --git a/src/core/persistence/moved-pages.ts b/src/core/persistence/moved-pages.ts
index 4c7db76186..45407d074c 100644
--- a/src/core/persistence/moved-pages.ts
+++ b/src/core/persistence/moved-pages.ts
@@ -38,30 +38,31 @@ const git = (root: string, args: string[]): string | null => { try { return sync
const shallow = (root: string) => git(root, ['rev-parse', '--is-shallow-repository'])?.trim() === 'true';
const short = (sha: string) => sha.slice(0, 12);
-/** Paths (relative to `root`) that took `blob` in `commit` itself (added or changed to it there), and those it deleted holding `blob`. */
-function sameCommitPaths(root: string, commit: string, blob: string): { paths: string[]; deleted: string[] } | null {
+/** Paths (relative to `root`) that took `blob` in `commit` itself (added or changed to it there). */
+function sameCommitPaths(root: string, commit: string, blob: string): string[] | null {
const out = git(root, ['diff-tree', '-r', '--no-renames', '--no-commit-id', '--relative', '-z', `${commit}^`, commit]);
if (out === null) return null;
const fields = out.split('\0');
- const paths: string[] = [], deleted: string[] = [];
+ const paths: string[] = [];
for (let i = 0; i + 1 < fields.length; i += 2) {
- const [, , previous, next, status] = fields[i]!.split(' ');
+ const [, , , next, status] = fields[i]!.split(' ');
if (next === blob && status !== 'D') paths.push(fields[i + 1]!);
- if (previous === blob && status === 'D') deleted.push(fields[i + 1]!);
}
- return { paths, deleted };
+ return paths;
}
-/** Paths (relative to `root`) whose first commit in HEAD's history added them with `blob`, with that commit. */
-function firstCommitPaths(root: string, blob: string): Map<string, string> | null {
+/** Paths (relative to `root`) whose first commit in HEAD's history added them with `blob`, with that commit, and every path a commit deleted holding `blob`. */
+function firstCommitPaths(root: string, blob: string): { first: Map<string, string>; deleted: Set<string> } | null {
const out = git(root, ['log', '--no-renames', '--relative', '--raw', '--no-abbrev', '--format=commit %H', `--find-object=${blob}`, 'HEAD']);
if (out === null) return null;
- const added = new Map<string, string>();
+ const added = new Map<string, string>(), deleted = new Set<string>();
let commit = '';
for (const line of out.split('\n')) {
if (line.startsWith('commit ')) { commit = line.slice(7).trim(); continue; }
const match = /^:\d+ \d+ [0-9a-f]+ ([0-9a-f]+) A\t(.+)$/.exec(line);
if (match && match[1] === blob && !match[2]!.startsWith('"')) added.set(match[2]!, commit);
+ const gone = /^:\d+ \d+ ([0-9a-f]+) [0-9a-f]+ D\t(.+)$/.exec(line);
+ if (gone && gone[1] === blob && !gone[2]!.startsWith('"')) deleted.add(gone[2]!);
}
const first = new Map<string, string>();
for (const [path, commitOf] of added) {
@@ -69,7 +70,7 @@ function firstCommitPaths(root: string, blob: string): Map<string, string> | nul
if (history === null) return null;
if (history.split('\n').find(Boolean)?.trim() === commitOf) first.set(path, commitOf);
}
- return first;
+ return { first, deleted };
}
/** Of `paths`, those HEAD still holds (relative to `root`). */
@@ -102,13 +103,13 @@ export async function readMovedPage(engine: BrainEngine, input: { sourceId: stri
const added = git(root, ['log', '--no-renames', '--relative', '--diff-filter=A', '--format=%H', '-1', `${commit}^`, '--', ...literalPathspecs([old.path])])?.trim();
if (same === null || first === null || !added) return held('history_unknown', `Git could not read which paths took ${old.path}'s content (blob ${short(blob)})`);
const evidence = new Map<string, { evidence: MovedEvidence; commit: string }>();
- for (const [path, at] of first) {
+ for (const [path, at] of first.first) {
if (path === old.path || at === added) continue;
const base: string | undefined = git(root, ['merge-base', added, at])?.trim();
if (!base) return held('history_unknown', `Git could not order ${path}'s first commit ${short(at)} against the commit that added ${old.path}`);
if (base === added) evidence.set(path, { evidence: 'first_commit', commit: at });
}
- for (const path of same.paths) if (path !== old.path) evidence.set(path, { evidence: 'same_commit', commit });
+ for (const path of same) if (path !== old.path) evidence.set(path, { evidence: 'same_commit', commit });
const present = inHead(root, [...evidence.keys()]);
const rows = present.size ? await engine.executeRaw<{ id: number; slug: string; revision: string; source_path: string }>(`SELECT id, slug, knowledge_revision::text AS revision, source_path
FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND id<>$2 AND source_path=ANY($3::text[]) ORDER BY id`, [sourceId, old.page_id, [...present]]) : [];
@@ -128,8 +129,11 @@ export async function readMovedPage(engine: BrainEngine, input: { sourceId: stri
return held('not_moved', `no live page of the source started from ${old.path}'s last committed content (blob ${short(blob)}), so commit ${short(commit)} deleted it rather than moving it`);
}
const row = rows[0]!;
- const others = same.deleted.filter(path => path !== old.path);
- if (others.length) return held('shared_survivor', `commit ${short(commit)} deleted ${[old.path, ...others].join(', ')} with the same content (blob ${short(blob)}), so which of them moved to ${row.source_path} is a person's decision`, [row.slug]);
+ const gone = [...first.deleted].filter(path => path !== old.path);
+ const back = inHead(root, gone);
+ const others = gone.length ? await engine.executeRaw<{ source_path: string }>(`SELECT source_path FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND id<>$2
+ AND source_path=ANY($3::text[]) ORDER BY source_path`, [sourceId, old.page_id, gone.filter(path => !back.has(path))]) : [];
+ if (others.length) return held('shared_survivor', `${[old.path, ...others.map(other => other.source_path)].join(', ')} were deleted holding the same content (blob ${short(blob)}) and each still backs a live page, so which of them moved to ${row.source_path} is a person's decision`, [row.slug]);
const [storage] = await engine.executeRaw<{ segmented: boolean }>(`SELECT EXISTS (SELECT 1 FROM pages WHERE id=$1 AND body_storage<>'inline')
OR EXISTS (SELECT 1 FROM page_versions WHERE page_id=$1 AND body_storage<>'inline') AS segmented`, [old.page_id]);
if (storage?.segmented) return held('segmented_versions', `${old.path} moved to ${row.source_path}, but page ${old.slug} or one of its saved versions is stored in segments (over 1 MiB), whose body generations belong to ${old.slug} and cannot move to ${row.slug}; fold it by hand with the user`, [row.slug]);
diff --git a/src/core/repair/moved-pages.ts b/src/core/repair/moved-pages.ts
index 9bc55312ec..1189e5eeef 100644
--- a/src/core/repair/moved-pages.ts
+++ b/src/core/repair/moved-pages.ts
@@ -96,8 +96,7 @@ export const movedPagesRepair: RepairHandler = {
const refusal = ghostScanRefusal(scan);
if (refusal) throw refusal;
const owner = scan.owner!, root = scan.root!;
- const named = slugs ? await Promise.all(slugs.map(async slug => (await ghostPageNow(engine, sourceId, slug)).ghost)) : [];
- const ghosts = slugs ? named.filter(ghost => ghost !== null) : scan.ghosts.slice(0, GHOST_REPAIR_LIMIT);
+ const ghosts = scan.ghosts.filter(ghost => !slugs || slugs.includes(ghost.slug)).slice(0, GHOST_REPAIR_LIMIT);
const provenance = await readDeletionProvenance(root, ghosts.map(ghost => ghost.path));
const observedAt = new Date().toISOString();
const pairs: MovedPair[] = [], held: HeldPage[] = [];
@@ -121,7 +120,7 @@ export const movedPagesRepair: RepairHandler = {
const hash = previewHash(hashParts(scope, slugs, owner, pairs, held));
if (pairs.length) await saveApprovedSet<ApprovedPair>(engine, { command: 'moved-pages', hash }, pairs.map(pair => ({ ...pair, owner, selection: scope.source_ids })));
const warnings = [
- ...(missing.length ? [`Not a live page whose file is gone in source ${sourceId}, so nothing to fold: ${missing.join(', ')}.`] : []),
+ ...(missing.length ? [`Not a live page whose file is gone in source ${sourceId}${scan.truncated ? ` among the first ${GHOST_REPAIR_LIMIT} checked (preview the whole source after applying)` : ''}, so nothing to fold: ${missing.join(', ')}.`] : []),
...(mass ? [`${pairs.length} fold(s) against ${scan.file_backed} file-backed page(s) (more than ${Math.round(MASS_RECONCILE_RATIO * 100)}%): the apply refuses unless GBRAIN_ALLOW_MASS_RECONCILE=1; check the source first.`] : []),
...((scan.truncated || scan.ghosts.length > ghosts.length) && !slugs ? [`More pages whose file is gone may exist past the first ${GHOST_REPAIR_LIMIT} checked; apply this set, then preview again.`] : []),
...(held.length ? [`${held.length} page(s) whose file is gone are not proven moved and are never folded by this apply; each lists why.`] : []),
diff --git a/test/moved-pages-gst2584.test.ts b/test/moved-pages-gst2584.test.ts
index 640d181bb1..3499415394 100644
--- a/test/moved-pages-gst2584.test.ts
+++ b/test/moved-pages-gst2584.test.ts
@@ -324,4 +324,24 @@ for (const backend of testBackends()) {
for (const [path, content] of Object.entries({ 'notes/alpha.md': ALPHA, 'notes/beta.md': BETA })) { mkdirSync(join(root, path, '..'), { recursive: true }); writeFileSync(join(root, path), content); }
git(root, 'add', '-A'); git(root, 'commit', '-qm', 'later');
} }), 240_000);
+
+ test(`${backend}: two old pages deleted in separate commits that started one page stay held, and fold once the other is retired`, () => managedBrain(async ({ engine, root }) => {
+ await registerLocalWriter(engine, 'cli');
+ expect((await performManagedSync(engine, SYNC)).status).toBe('first_sync');
+ const before = await engine.executeRaw<{ slug: string; timeline: string }>("SELECT slug, timeline FROM pages WHERE source_id='default' AND slug IN ('notes/alpha', 'notes/alpha-copy')");
+ await raw(engine, "UPDATE pages SET timeline='An edit only the database holds.', knowledge_revision=gen_random_uuid() WHERE source_id='default' AND slug IN ('notes/alpha', 'notes/alpha-copy')");
+ mkdirSync(join(root, 'archive'), { recursive: true }); writeFileSync(join(root, 'archive/alpha.md'), ALPHA); git(root, 'add', '-A'); git(root, 'commit', '-qm', 'copy');
+ git(root, 'rm', '-q', 'notes/alpha.md'); git(root, 'commit', '-qm', 'delete one');
+ git(root, 'rm', '-q', 'notes/alpha-copy.md'); git(root, 'commit', '-qm', 'delete the other');
+ await performManagedSync(engine, SYNC);
+ for (const row of before) await raw(engine, "UPDATE pages SET timeline=$1, knowledge_revision=gen_random_uuid() WHERE source_id='default' AND slug=$2", [row.timeline, row.slug]);
+ const preview = await runner(engine, 'moved-pages', {});
+ expect(preview.affected).toBe(0);
+ expect(listed(preview, 'notes/alpha')).toMatchObject({ class: 'held:shared_survivor' });
+ expect(listed(preview, 'notes/alpha-copy')).toMatchObject({ class: 'held:shared_survivor' });
+ expect(listed(await runner(engine, 'moved-pages', { slugs: ['notes/alpha'] }), 'notes/alpha')).toMatchObject({ class: 'held:shared_survivor' });
+ await raw(engine, "UPDATE pages SET deleted_at=now(), knowledge_revision=gen_random_uuid() WHERE source_id='default' AND slug='notes/alpha-copy'");
+ const after = await runner(engine, 'moved-pages', {});
+ expect(listed(after, 'notes/alpha')).toMatchObject({ class: 'moved_to' });
+ }, opts(backend, { 'notes/alpha.md': ALPHA, 'notes/alpha-copy.md': ALPHA, 'notes/beta.md': BETA })), 240_000);
}