Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytan2e9e80f3e748
diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsv
index d546f89093..5f2ac946e8 100644
--- a/docs/architecture/canonical-writers.tsv
+++ b/docs/architecture/canonical-writers.tsv
@@ -32,6 +32,7 @@ src/commands/reindex-aliases.ts 1 engine_guard Canonical table SQL trigger requi
src/core/persistence/twin-merge.ts 10 coordinator The #6948 twin merge (links in every role, link transitions, timeline, raw data, files, user tags, aliases and facts move onto the canonical page; the twin is marked origin_twin and soft-deleted) runs only inside the managed_maintenance_resolve_origin_twin preparer's coordinated transaction on managed brains, or one maintenanceTransaction on unmanaged brains, after the group verdict is rechecked under both page locks; it writes no file, so there is no filesystem ordering to keep.
src/core/repair/origin-twins.ts 1 coordinator gbrain repair origin-twins and the post-sync heal resolve each verified twin as a receipted managed_maintenance_resolve_origin_twin request (submitDatabaseMaintenanceIntent, owner host only) on managed brains and in one maintenanceTransaction on unmanaged brains; the verdict is recomputed inside the write and any drift holds the file instead of merging.
src/core/repair/unwithdrawn-facts.ts 1 coordinator `gbrain repair unwithdrawn-facts` (#8819) puts the ledger before-state back on preview-approved facts a fact_fence generation retired though no fence held them. On a managed brain the UPDATE runs only inside the managed_maintenance_restore_unwithdrawn_facts publication; an unmanaged or repo-less brain classifies every candidate excluded (unmanaged_reconcile), so a set previewed while it was managed is reclassified in one maintenanceTransaction under the page lock after the revision recheck and restores nothing.
+src/core/repair/private-labels.ts 1 coordinator `gbrain repair private-labels` (GST-2059) removes or re-adds only the previewed privacy keys on preview-approved pages. On a managed brain each page goes through publishMaintenancePage (maintenancePreflight owner check, revision-bound, keep_trust; the Git door on a repo source); an unmanaged or repo-less brain re-imports it in one maintenanceTransaction under the page lock after the revision recheck.
src/core/search-vector-backfill.ts 2 projection backfillPageVectors (reindex-search-vector, the fts_cjk_boundary migration) rewrites only pages.search_vector, through the seal's pageSearchVectorSql over the sanitized timeline and guarded by the knowledge revision it read (its read is an UPDATE-to-self of id); canonical fields are untouched and the managed writer guard passes search_vector-only updates.
src/commands/sources-set-path.ts 1 coordinator Managed rebind uses native exclusion, exact manifest verification and a retained source-incarnation receipt; unmanaged pointer repair remains explicit.
src/commands/sources.ts 10 coordinator Managed add/archive/restore/remove/purge/reclone route through source lifecycle; remaining legacy canonical SQL stays fenced.
diff --git a/docs/guides/access-designations.md b/docs/guides/access-designations.md
index 008fa661e1..25232642d6 100644
--- a/docs/guides/access-designations.md
+++ b/docs/guides/access-designations.md
@@ -126,6 +126,11 @@ database, so a repo-less brain works the same. The owner relaxation applies to a
when it speaks for itself (no audience, or an audience of the owner alone); never to a shared-room audience or an
attested call. `gbrain access owner clear` turns it off.
+One owner credential both reads every private page and writes new `default` pages that other members read, so an
+owner agent can copy private content into a shared page. A prompt planted in a page that agent reads can ask it to.
+Bind only agents you trust with the whole brain as the owner; give every other agent its own member, whose new pages
+stay kept to it.
+
## Related
- [Multi-source brains](multi-source-brains.md): sources and grants.
diff --git a/src/core/persistence/page-prepare.ts b/src/core/persistence/page-prepare.ts
index ec972ba265..fed0044699 100644
--- a/src/core/persistence/page-prepare.ts
+++ b/src/core/persistence/page-prepare.ts
@@ -436,7 +436,10 @@ async function compareFileTarget(engine: BrainEngine, row: Parameters<typeof pre
if (claimants.length) { options.sharedOrigin.onShared({ target, claimants }); return undefined; }
}
// G7a: a page whose file its private transition removed (withheld_source_path) writes it again; the file is absent by design.
- const withheld = !snapshot?.page.source_path && Boolean(snapshot?.page.withheld_source_path);
+ // So does a strict page that was private from its first write (database_only_reason private, no file ever recorded): it
+ // writes its file for the first time when it turns world.
+ const withheld = !snapshot?.page.source_path && (Boolean(snapshot?.page.withheld_source_path) || (!before && !!snapshot && !snapshot.page.source_uri
+ && isPrivacyClass((await engine.executeRaw<{ reason: string | null }>('SELECT database_only_reason AS reason FROM pages WHERE id=$1', [snapshot.page.id]))[0]?.reason)));
if (!before && snapshot && !snapshot.page.deleted_at && !options.allowMissing && !withheld) {
// A declared db_only page has no canonical file by design and publishes to
// the database only. gbrain.yml is consulted only here, where the write
diff --git a/src/core/repair/private-labels.ts b/src/core/repair/private-labels.ts
index f41573266f..664289e16c 100644
--- a/src/core/repair/private-labels.ts
+++ b/src/core/repair/private-labels.ts
@@ -34,7 +34,8 @@
* <gbrain home>/repair/private-labels/<brain_id>.jsonl, src/commands/repair-private-labels.ts),
* and --class restore plans from its lines: each recorded page still live and still
* without those keys gets them back (preview-bound the same way, with its own line).
- * An apply or a restore preview without a ledger is refused.
+ * An apply or a restore preview without a ledger is refused. A git-publish clear is not fully undone: restore re-adds
+ * the label and the file leaves the checkout, but the commits that held it keep the page's content.
*/
import type { BrainEngine } from '../engine.ts';
import { serializePageToMarkdown } from '../markdown.ts';
@@ -152,7 +153,7 @@ async function planRestore(engine: BrainEngine, scope: RepairScope, selection: S
const entries: Approved[] = [];
for (const line of removals) {
const page = byId.get(line.page_id);
- if (!page || page.source_id !== line.source_id) { counts.page_gone++; continue; }
+ if (!page || page.source_id !== line.source_id || page.slug !== line.slug) { counts.page_gone++; continue; }
if (Object.keys(line.removed!).some(key => Object.hasOwn(page.frontmatter ?? {}, key))) { counts.already_restored++; continue; }
counts.restorable++;
entries.push({ mode: 'restore', class: 'restore', brain_id: scope.brain_id, source_id: page.source_id, slug: page.slug, page_id: Number(page.id),
@@ -223,10 +224,13 @@ export const privateLabelsRepair: RepairHandler = {
: 'Clearing a label widens what remote callers that are not the brain owner can read: each cleared page becomes readable remotely (readable_by and folder rules still apply). '
+ 'Undo with: gbrain repair private-labels --class restore',
...(gitPublish && selection.class === 'git-publish' ? [`${gitPublish} page(s) of class git-publish live in git-canonical sources, where private pages are database-only; `
- + 'clearing commits each listed page into its source\'s Git history for the first time.'] : []),
+ + 'clearing commits each listed page into its source\'s Git history for the first time. That part is one-way: --class restore re-adds the label and removes the file '
+ + 'from the checkout, but every earlier commit, and any remote it was pushed to, keeps the page\'s content.'] : []),
...(gitPublish && selection.class !== 'git-publish' ? [`${gitPublish} page(s) of class git-publish (git-canonical sources) carry the same label and are not in this preview: `
+ 'private pages there are database-only, so clearing commits each into its source\'s Git history for the first time. Preview them by name: gbrain repair private-labels --class git-publish'] : []),
...(planned.unreadable ? [`${planned.unreadable} ledger line(s) could not be read and are not planned.`] : []),
+ ...(restore && !Object.values(before).some(Boolean) ? [`The ledger ${ledger!.path} has no line for brain ${scope.brain_id} in this scope. Restore reads only the ledger on the host `
+ + 'and GBRAIN_HOME that ran the clear; run it there.'] : []),
];
return { items: toItems(window, hash), preview_hash: hash, residuals: {}, warnings,
listing: window.map(entry => ({ item: `${entry.source_id}:${entry.slug}`, class: entry.class,
@@ -266,8 +270,13 @@ export const privateLabelsRepair: RepairHandler = {
if (acceptedPendingReceipt(error)) item.ledger.record(line);
throw error;
}
- item.ledger.record(line);
- return { applied: true, outcome: entry.mode === 'clear' ? 'cleared' : 'restored', detail: { ledger: item.ledger.path } };
+ const outcome = entry.mode === 'clear' ? 'cleared' : 'restored';
+ try { item.ledger.record(line); } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ return { applied: true, outcome, reason: `The page was written but its ledger line was not saved (${message}). Keep these values to undo it by hand: ${describeLabels(entry.labels)}.`,
+ detail: { ledger: item.ledger.path, ledger_error: message, labels: entry.labels } };
+ }
+ return { applied: true, outcome, detail: { ledger: item.ledger.path } };
} finally {
if (item.last && item.hash) await clearApprovedSet(ctx.engine, { command: 'private-labels', hash: item.hash });
}
diff --git a/src/core/repair/registry.ts b/src/core/repair/registry.ts
index 44e6bead40..0c03bf86a4 100644
--- a/src/core/repair/registry.ts
+++ b/src/core/repair/registry.ts
@@ -661,7 +661,7 @@ const SPECS: Record<RepairKind, Omit<RepairKindSpec, 'kind'>> = {
+ 'The preview lists one window (--limit, default 1000) by class (alias, alias-and-visibility) with every category\'s count before and after; '
+ '--apply --expect <hash> applies exactly that window, one revision-bound page write each; a bare --apply is refused. Pages in git-canonical sources '
+ '(git-publish: clearing commits them into Git) run only with --class git-publish. Each cleared label is recorded in '
- + '<gbrain home>/repair/private-labels/<brain>.jsonl, and --class restore re-adds it. Runs only when named; never on upgrade.',
+ + '$GBRAIN_HOME/repair/private-labels/<brain>.jsonl, and --class restore re-adds it. Runs only when named; never on upgrade.',
},
'generations': {
handler: generationsRepair, embeds: 'effect', checks: ['generation_retirements', 'generation_held', 'generation_pending'], explicit_only: true, preview_bound: true, consent: 'destructive',
diff --git a/test/fix-wave-5-integration.test.ts b/test/fix-wave-5-integration.test.ts
index 5ee589718c..eead4303dc 100644
--- a/test/fix-wave-5-integration.test.ts
+++ b/test/fix-wave-5-integration.test.ts
@@ -202,7 +202,8 @@ for (const backend of testBackends()) {
'uncommitted-deletions': 'gbrain repair uncommitted-deletions',
// GBRA-161: the generations preview carries its ledger kind and the restore window, so the printed command runs as is.
generations: 'gbrain repair generations --kind atom --since 30d', 'fact-claim-dates': 'gbrain repair fact-claim-dates',
- provenance: 'gbrain repair provenance', 'secret-spans': 'gbrain repair secret-spans', 'rows-behind': 'gbrain repair rows-behind' };
+ provenance: 'gbrain repair provenance', 'secret-spans': 'gbrain repair secret-spans', 'rows-behind': 'gbrain repair rows-behind',
+ 'private-labels': 'gbrain repair private-labels' };
// The post-upgrade banner names both findings with the kind's read-only preview.
const banner = await postUpgradeRecoveryBanner(engine, 'host');
diff --git a/test/import-private-hold-callers-7897.test.ts b/test/import-private-hold-callers-7897.test.ts
index e9e5152e84..7bb1e481a5 100644
--- a/test/import-private-hold-callers-7897.test.ts
+++ b/test/import-private-hold-callers-7897.test.ts
@@ -27,6 +27,7 @@ const AUDITED: Record<string, Audit> = {
'src/core/generations/adapters/page.ts': { calls: { importFromContent: 1 }, disposition: 'derived', why: 'a stored preimage or a producer page gbrain serializes' },
'src/core/import-file.ts': { calls: { importFromContent: 2 }, disposition: 'held', why: 'the identity-move retry passes the caller\'s options; importFromFile holds before it imports' },
'src/core/minions/handlers/ingest-capture.ts': { calls: { importFromContent: 1 }, disposition: 'held', why: 'the shared import options set holdNoncanonicalPrivate (#7880)' },
+ 'src/core/repair/private-labels.ts': { calls: { importFromContent: 1 }, disposition: 'derived', why: 'the stored page re-serialized with only the previewed privacy keys removed or re-added' },
'src/core/oversized-backfill.ts': { calls: { importFromContent: 1 }, disposition: 'derived', why: 're-serializes the stored page' },
'src/core/persistence/connector-sync.ts': { calls: { importFromContent: 1 }, disposition: 'derived',
why: 'GitHub and Google renders: fixed keys, provider text only as quoted values, visibility: private only in lowercase; the rest is the stored page' },
diff --git a/test/repair-private-labels.test.ts b/test/repair-private-labels.test.ts
index d60e6fbc3b..53e3237b7c 100644
--- a/test/repair-private-labels.test.ts
+++ b/test/repair-private-labels.test.ts
@@ -15,7 +15,8 @@
* gbrain repair command entry (argument parse, runner, runRepair).
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
-import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
@@ -31,6 +32,10 @@ import { classifyPrivateLabel } from '../src/core/repair/private-labels.ts';
import { withEnv } from './helpers/with-env.ts';
import { withCoordinatedWrite, withTrustBackfill } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
+import { claimWorktree } from '../src/core/persistence/ownership.ts';
+import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import { registerLocalWriter } from '../src/core/persistence/identity.ts';
let engine: PGLiteEngine;
const dir = mkdtempSync(join(tmpdir(), 'gbrain-private-labels-'));
@@ -250,6 +255,20 @@ describe('repair private-labels', () => {
expect(relisted.details.counts.before.alias).toBe(2);
expect(relisted.details.counts.before['alias-and-visibility']).toBe(1);
});
+
+ test('restore skips a page whose label was set again by hand since the preview, and keeps the value the user set', async () => {
+ const clear = await json(['private-labels', '--class', 'alias']);
+ expect((await json(['private-labels', '--class', 'alias', '--apply', '--expect', clear.preview_hash])).applied).toBe(2);
+ const preview = await json(['private-labels', '--class', 'restore']);
+ expect(preview.listing.map((l: { item: string }) => l.item)).toEqual(['default:notes/alias', 'default:notes/readers']);
+ await seed('notes/alias', 'note', { status: 'draft', access: 'restricted' });
+ const applied = await json(['private-labels', '--class', 'restore', '--apply', '--expect', preview.preview_hash]);
+ expect(applied.applied).toBe(1);
+ expect(applied.skipped).toBe(1);
+ expect((await row('notes/alias')).frontmatter.access).toBe('restricted');
+ expect((await row('notes/readers')).frontmatter.access).toBe('private');
+ expect(ledgerLines(brainId).filter(l => l.restored && l.slug === 'notes/alias')).toHaveLength(1);
+ });
});
/**
@@ -317,6 +336,86 @@ describe('repair private-labels keeps the trust tier', () => {
});
});
+/**
+ * git-publish is the one clear that writes Git history: on a managed brain with a git-canonical source the cleared page
+ * is committed into the source checkout through the maintenance door, and the ledger records it so restore can re-add
+ * the label.
+ */
+describe('repair private-labels --class git-publish on a git-canonical source', () => {
+ test('apply removes the label, commits the page into the source checkout and records it; restore re-adds the label', async () => {
+ const source = 'source-g';
+ const root = join(dir, 'git-checkout');
+ mkdirSync(root, { recursive: true });
+ execFileSync('git', ['init', '-q'], { cwd: root });
+ execFileSync('git', ['-c', 'user.name=example', '-c', '[email protected]', 'commit', '-q', '--allow-empty', '-m', 'init'], { cwd: root });
+ await engine.executeRaw('INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2) ON CONFLICT (id) DO NOTHING', [source, root]);
+ await engine.executeRaw('UPDATE sources SET config = $2::jsonb WHERE id = $1', [source, JSON.stringify({ canonical: 'git' })]);
+ await engine.setConfig('sync.write_through', 'true');
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
+ try {
+ await withEnv({ GBRAIN_HOME: dir }, async () => {
+ await registerLocalWriter(engine, 'cli');
+ await claimWorktree(engine, source, root);
+ const ctx = { engine, sourceId: source, remote: false, config: { engine: engine.kind, embedding_disabled: true } as never, dryRun: false,
+ logger: { info() {}, warn() {}, error() {} } } as OperationContext;
+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug: 'notes/g', request_id: crypto.randomUUID(),
+ content: serializeMarkdown({ access: 'private', topic: 'kept' }, body('notes/g'), '', { type: 'note' as never, title: 'notes/g', tags: ['t1'] }) } });
+ expect(existsSync(join(root, 'notes', 'g.md'))).toBe(false);
+ const before = await row('notes/g', source);
+ const preview = await json(['private-labels', '--source', source, '--class', 'git-publish']);
+ expect(preview.listing).toEqual([{ item: source + ':notes/g', class: 'git-publish', detail: 'remove access: private' }]);
+ const applied = await json(['private-labels', '--source', source, '--class', 'git-publish', '--apply', '--expect', preview.preview_hash]);
+ expect(applied.failed).toEqual([]);
+ expect(applied.applied).toBe(1);
+ const cleared = await row('notes/g', source);
+ const { access: _a, ...rest } = before.frontmatter;
+ expect(cleared.frontmatter).toEqual(rest);
+ expect(cleared.compiled_truth).toBe(before.compiled_truth);
+ const file = join(root, 'notes', 'g.md');
+ expect(existsSync(file)).toBe(true);
+ expect(readFileSync(file, 'utf8')).not.toMatch(/^access:/m);
+ expect(execFileSync('git', ['log', '--format=%H', '--', 'notes/g.md'], { cwd: root, encoding: 'utf8' }).trim()).not.toBe('');
+ const brain = preview.scope.brain_id;
+ expect(ledgerLines(brain).filter(l => l.source_id === source).map(l => [l.slug, l.removed])).toEqual([['notes/g', { access: 'private' }]]);
+
+ const restorePreview = await json(['private-labels', '--source', source, '--class', 'restore']);
+ expect(restorePreview.listing).toEqual([{ item: source + ':notes/g', class: 'restore', detail: 're-add access: private' }]);
+ const restored = await json(['private-labels', '--source', source, '--class', 'restore', '--apply', '--expect', restorePreview.preview_hash]);
+ expect(restored.failed).toEqual([]);
+ expect(restored.applied).toBe(1);
+ expect((await row('notes/g', source)).frontmatter).toEqual(before.frontmatter);
+ });
+ } finally {
+ await disposePersistenceConsumer(engine);
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ }
+ });
+});
+
+describe('repair private-labels when the undo ledger cannot record', () => {
+ test('a clear whose ledger line fails to save still reports the page as applied and names the removed values', async () => {
+ const source = 'source-h';
+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [source]);
+ await seed('notes/h', 'note', { access: 'private' }, source);
+ const preview = await json(['private-labels', '--source', source]);
+ const ledger = preview.details.ledger as string;
+ chmodSync(ledger, 0o400);
+ try {
+ const applied = await json(['private-labels', '--source', source, '--apply', '--expect', preview.preview_hash]);
+ expect(applied.failed).toEqual([]);
+ expect(applied.applied).toBe(1);
+ expect(JSON.stringify(applied)).toContain('access: private');
+ expect('access' in (await row('notes/h', source)).frontmatter).toBe(false);
+ } finally { chmodSync(ledger, 0o600); }
+ });
+
+ test('a restore preview with no ledger line for this brain says where restore has to run', async () => {
+ const preview = await json(['private-labels', '--source', 'source-h', '--class', 'restore']);
+ expect(preview.listing ?? []).toEqual([]);
+ expect(preview.warnings.some((w: string) => w.includes('has no line for brain') && w.includes(preview.details.ledger))).toBe(true);
+ });
+});
+
test('a page with declared lineage keeps its label whatever its type, so its origin decides who reads it', () => {
const lineage: Array<Record<string, unknown>> = [
{ access: 'private', derived_from: 'notes/origin' },