Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Never skip files refused because of how a source is set up (GST-2520)
garrytan152d47d49b33
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5ce2e1bc90..01a4164fe7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ identifiers and attribution are available in the pre-removal Git revision- A large source that the background syncer could not finish no longer retries forever with the same short budget. A resident gives its first run 30 seconds, and every resident restart or change of the process holding the notifier counted as "first" again, so each retry stopped at the same point having saved nothing. That short budget now goes only to a source with no failed attempts on record, and a retry after a run that saved nothing gets the full sync budget.- A source the background syncer marked stalled (`notifier_stalled`, "retrying every 300 s") now really is retried every five minutes. With `sync.on_commit` off (the default), the retry only happened while the original sync request was still on record, and a run that stopped early could clear that request, so the source sat stalled with nothing retrying it and nothing in the log. The retry now continues until a run completes, also after a restart or when another resident takes over the notifier, which now reads the state the previous one recorded.+- `gbrain sync --skip-failed`, and the automatic skip after three failed syncs, no longer skip files that were refused because of how the source is set up rather than because anything is wrong with them (`strict_requires_managed`: a `canonical: git` source on a brain without managed persistence). Skipping them moved the sync checkpoint to the latest commit with no pages imported, after which `sync status` said synced and later syncs found nothing to do, even once the setup was fixed. The sync now stays blocked, says why, and names the two fixes: turn on managed persistence, or remove `canonical: git`, after which the next plain sync imports every page. A brain that was already skipped past this way needs one `gbrain sync --source <id> --full`.## [0.60.688.0] - 2026-11-12diff --git a/src/core/sync-failure-ledger.ts b/src/core/sync-failure-ledger.tsindex 3e7bc534e9..735735b0d7 100644--- a/src/core/sync-failure-ledger.ts+++ b/src/core/sync-failure-ledger.ts@@ -212,6 +212,9 @@ export function resolveAutoSkipThreshold(): number {* message. Order matters: DB-layer errors are checked BEFORE YAML-layer* ones so Postgres `duplicate key` isn't mislabeled as a YAML duplicate-key.*/+/** GST-2520: refusals caused by the source's or brain's mode, never the file: no edit to the file clears them, so a skip strands its page. */+const MODE_REFUSAL_CODES = new Set(['strict_requires_managed', 'writer_coordinator_required']);+/** Errno codes of a file the importer could not read: the file's own state, never a provider's. */const FILE_ERRNO_CODES: Record<string, string> = {EACCES: 'PERMISSION_DENIED', EPERM: 'PERMISSION_DENIED',@@ -240,6 +243,7 @@ function providerText(errorMsg: string, path?: string): { text: string; envelopeexport function syncFailureCode(error: unknown, path?: string): string {const errno = (error as { code?: unknown } | null)?.code;if (typeof errno === 'string' && FILE_ERRNO_CODES[errno]) return FILE_ERRNO_CODES[errno]!;+ if (typeof errno === 'string' && MODE_REFUSAL_CODES.has(errno)) return errno;return classifyErrorCode(error instanceof Error ? error.message : String(error), path);}@@ -258,6 +262,10 @@ export function classifyErrorCode(errorMsg: string, path?: string): string {// it the blocked-run breakdown also printed a bare `UNKNOWN: 1`.if (/rename reconcile failed|RENAME_RECONCILE/i.test(errorMsg)) return 'RENAME_RECONCILE';+ // GST-2520: a refusal by the source's or brain's mode (persistence/maintenance.ts); a full import keeps only the message.+ if (/cannot write git-canonical source \S+ on an unmanaged brain/.test(errorMsg)) return 'strict_requires_managed';+ if (/cannot mutate a managed brain through the legacy writer/.test(errorMsg)) return 'writer_coordinator_required';+// #5032: a ':' file name on Windows (src/commands/sync/imports.ts).if (/^colon_slug_windows_write_through:/.test(errorMsg)) return 'COLON_SLUG_WINDOWS_WRITE_THROUGH';@@ -883,6 +891,7 @@ export function isEmbeddingInfraCode(code: string | undefined): boolean {* --skip-failed → advance (ack handled post-advance)* valve disabled (threshold<=0) → block (pure fail-closed) if failures* any fresh (attempts<threshold) → block+ * any mode refusal (GST-2520) → block, even with skipFailed (the setup, not the file)* any embedding-infra code (#3875) → block (provider unhealthy ≠ file poison;* never auto-skip, regardless of attempts)* all chronic (attempts>=threshold) → advance_then_autoskip@@ -901,6 +910,7 @@ export function decideGateAction(args: {}): GateDecision {if (args.sentinels.length > 0) return { action: 'hard_block', autoSkipPaths: [] };if (args.fileFailures.length === 0) return { action: 'advance', autoSkipPaths: [] };+ if (args.fileFailures.some(f => f.code !== undefined && MODE_REFUSAL_CODES.has(f.code))) return { action: 'block', autoSkipPaths: [] };if (args.skipFailed) return { action: 'advance', autoSkipPaths: [] };if (args.threshold <= 0) return { action: 'block', autoSkipPaths: [] };if (args.systemic) return { action: 'block', autoSkipPaths: [] };@@ -1056,6 +1066,9 @@ export async function applySyncFailureGate(input: SyncGateInput): Promise<SyncGa}if (decision.action === 'hard_block' || decision.action === 'block') {+ const mode = codes.find(f => MODE_REFUSAL_CODES.has(f.code));+ if (mode) console.error(` Not skipped${input.skipFailed ? ' (--skip-failed)' : ''}: ${mode.code} comes from how source ${input.sourceId} is set up, not from its files, so skipping them would leave their pages out for good. `+ + (mode.code === 'strict_requires_managed' ? 'Turn on managed persistence for this brain, or remove canonical: git from the source; the next sync then imports them.' : 'Fix the setup the refusal names; the next sync then imports them.'));return {advanced: false,sentinelBlocked: decision.action === 'hard_block',diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex f368b80984..5ec65278fb 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -645,6 +645,7 @@ test/sync-status-commits-waiting-gst2515.test.tstest/sync-status-failure-detail-6513.test.tstest/sync-status-truthful-7243.test.tstest/sync-storage-invalid-8007.test.ts+test/sync-strict-skip-gst2520.test.tstest/sync-tree-reuse-gbra133.test.tstest/sync-unblock-repair-error-gbra130.test.tstest/sync-uncommitted-origin-7130.test.tsdiff --git a/test/sync-strict-skip-gst2520.test.ts b/test/sync-strict-skip-gst2520.test.tsnew file mode 100644index 0000000000..d87544ed76--- /dev/null+++ b/test/sync-strict-skip-gst2520.test.ts@@ -0,0 +1,111 @@+/**+ * GST-2520: a refusal that comes from the source's setup is never skipped past.+ *+ * 1. Protects: on a brain without managed persistence every import into a git-canonical source is refused+ * (strict_requires_managed). The files are fine, so a skip (--skip-failed, or the automatic one after three failed+ * syncs) used to move the checkpoint to HEAD with no pages, after which status read synced, doctor was clean and a+ * plain sync found nothing to do, even once the setup was fixed by removing canonical: git.+ * 2. Fails when: either skip advances last_commit past the refused files, the refusals are not left open under their+ * own code, or removing canonical: git afterwards leaves the pages out of a plain sync.+ * 3. Real seams: performSync on a Git clone of a strict managed brain and the sync failure ledger, PGLite and Postgres.+ */+import { afterEach, describe, expect, spyOn, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import type { BrainEngine } from '../src/core/engine.ts';+import type { OperationContext } from '../src/core/ops/contract.ts';+import { operationsByName } from '../src/core/operations.ts';+import { performSync } from '../src/commands/sync.ts';+import { classifyErrorCode, decideGateAction, syncFailureCode } from '../src/core/sync-failure-ledger.ts';+import { unacknowledgedSyncFailures } from '../src/core/sync.ts';+import { durableGitRepo, git } from './helpers/git-publication.ts';+import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';+import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';++const gitRepo = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };+const page = (title: string) => '---\ntype: person\ntitle: ' + title + '\n---\n\nNotes about ' + title + '.\n';+const call = (ctx: OperationContext, name: string, params: Record<string, unknown>) =>+ operationsByName[name]!.handler(ctx, { request_id: randomUUID(), ...params }) as Promise<Record<string, any>>;+const sync = (engine: BrainEngine, clone: string, extra: Record<string, unknown> = {}) =>+ performSync(engine, { sourceId: 'default', repoPath: clone, noPull: true, noEmbed: true, ...extra } as never) as Promise<Record<string, any>>;+const livePages = async (engine: BrainEngine) => (await engine.executeRaw<{ slug: string }>(+ "SELECT slug FROM pages WHERE source_id='default' AND deleted_at IS NULL ORDER BY slug")).map(r => r.slug);+const lastCommit = async (engine: BrainEngine) => (await engine.executeRaw<{ last_commit: string | null }>("SELECT last_commit FROM sources WHERE id='default'"))[0]?.last_commit ?? null;+const strict = (engine: BrainEngine, on: boolean) => engine.executeRaw(on+ ? "UPDATE sources SET config = config || '{\"canonical\":\"git\"}'::jsonb WHERE id='default'"+ : "UPDATE sources SET config = config - 'canonical' WHERE id='default'");+const refused = () => unacknowledgedSyncFailures().filter(f => f.code === 'strict_requires_managed');+const PAGES = ['people/alice-example', 'people/bea-example'];++/** A strict managed source with two person pages committed, cloned; then a fresh strict database (no managed persistence) on the clone. */+async function onClone(databaseUrl: string | undefined, run: (fresh: BrainEngine, clone: string) => Promise<void>): Promise<void> {+ await managedBrain(async ({ engine, ctx, root }) => {+ await strict(engine, true);+ await call(ctx, 'put_page', { slug: PAGES[0], content: page('Alice Example') });+ await call(ctx, 'put_page', { slug: PAGES[1], content: page('Bea Example') });+ await settleManagedGitEffects(engine);+ const home = mkdtempSync(join(tmpdir(), 'gst2520-strict-skip-'));+ try {+ const clone = join(home, 'content');+ git(home, 'clone', '--quiet', root, clone);+ const fresh = await isolatedSharedSkillsEngine(databaseUrl);+ try {+ await fresh.engine.executeRaw("UPDATE sources SET local_path=$1 WHERE id='default'", [clone]);+ await strict(fresh.engine, true);+ await run(fresh.engine, clone);+ } finally { await fresh.close(); }+ } finally { rmSync(home, { recursive: true, force: true }); }+ }, { databaseUrl, setup: gitRepo });+}++describe('GST-2520: mode refusals are not skippable (pure)', () => {+ test('a mode refusal blocks with --skip-failed and past the auto-skip threshold; a bad file still skips', () => {+ const base = { sentinels: [], threshold: 3, attemptsByPath: new Map([['a.md', 5]]) };+ for (const code of ['strict_requires_managed', 'writer_coordinator_required']) {+ expect(decideGateAction({ ...base, fileFailures: [{ path: 'a.md', code }], skipFailed: true }).action).toBe('block');+ expect(decideGateAction({ ...base, fileFailures: [{ path: 'a.md', code }], skipFailed: false }).action).toBe('block');+ }+ expect(decideGateAction({ ...base, fileFailures: [{ path: 'a.md', code: 'YAML_PARSE' }], skipFailed: true }).action).toBe('advance');+ expect(decideGateAction({ ...base, fileFailures: [{ path: 'a.md', code: 'YAML_PARSE' }], skipFailed: false }).action).toBe('advance_then_autoskip');+ });+ test('the ledger records a mode refusal under its own code', () => {+ expect(classifyErrorCode('direct file import cannot write git-canonical source default on an unmanaged brain.', 'a.md')).toBe('strict_requires_managed');+ expect(classifyErrorCode('direct file import cannot mutate a managed brain through the legacy writer.', 'a.md')).toBe('writer_coordinator_required');+ expect(syncFailureCode(Object.assign(new Error('direct file import cannot write git-canonical source default on an unmanaged brain.'), { code: 'strict_requires_managed' }), 'a.md')).toBe('strict_requires_managed');+ });+});++for (const backend of testBackends()) describe('[' + backend + '] GST-2520: a strict source on an unmanaged brain is never skipped past', () => {+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;+ let stderr: ReturnType<typeof spyOn> | null = null;+ afterEach(() => { stderr?.mockRestore(); stderr = null; });++ test('--skip-failed leaves the checkpoint and the refusals, names the two fixes, and removing canonical: git then imports every page', () => onClone(databaseUrl, async (fresh, clone) => {+ expect((await sync(fresh, clone)).status).toBe('blocked_by_failures');+ stderr = spyOn(console, 'error');+ expect((await sync(fresh, clone, { skipFailed: true })).status).toBe('blocked_by_failures');+ const said = stderr.mock.calls.flat().join('\n');+ stderr.mockRestore(); stderr = null;+ expect(said).toContain('Not skipped (--skip-failed): strict_requires_managed');+ expect(said).toContain('Turn on managed persistence');+ expect(said).toContain('remove canonical: git');+ expect(await lastCommit(fresh)).toBeNull();+ expect(refused().length).toBe(2);+ await strict(fresh, false);+ await sync(fresh, clone);+ expect(await livePages(fresh)).toEqual(PAGES);+ expect(await lastCommit(fresh)).not.toBeNull();+ }), 240_000);++ test('five failed syncs in a row auto-skip nothing', () => onClone(databaseUrl, async (fresh, clone) => {+ const statuses: string[] = [];+ for (let run = 0; run < 5; run++) statuses.push(String((await sync(fresh, clone)).status));+ expect(statuses).toEqual(Array(5).fill('blocked_by_failures'));+ expect(await lastCommit(fresh)).toBeNull();+ expect(refused().length).toBe(2);+ expect(unacknowledgedSyncFailures().filter(f => f.state === 'auto_skipped')).toEqual([]);+ }), 300_000);+});