Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(sync): sync status names a failure no request was admitted for (request_id null) (GBRA-287)

garrytana54eeea22c31
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04ea7f7a52..8ef7b72b3f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**A page stored in segments no longer stops a source's sync.** A managed sync re-importing a Git-tracked page stored in segments (`pages.segmented_storage`) whose working-tree bytes differ from the pinned commit, as on a live checkout, compared the file against the stored page with a whole-body read. That read refused with `page_body_segmented`, recorded as a run failure in the freeze phase, and every later sync stopped `sync_blocked` at the same file, with a retry command that could not help. The freeze now compares a segmented page up to 24 MiB read back whole, as its publication already did, so the page gets the outcome an inline page gets. A page whose stored body can't be read at the freeze (`page_body_segmented`, or `page_body_rows_unreadable`) is held `page_write_failed`, naming its code, and the rest of the source syncs. `gbrain sync status` classifies such a hold by that code (`page_body_rows_unreadable`: retry, no person needed), not as an unplaced `page_write_failed`.
+**A page stored in segments no longer stops a source's sync.** A managed sync re-importing a Git-tracked page stored in segments (`pages.segmented_storage`) whose working-tree bytes differ from the pinned commit, as on a live checkout, compared the file against the stored page with a whole-body read. That read refused with `page_body_segmented`, recorded as a run failure in the freeze phase, and every later sync stopped `sync_blocked` at the same file, with a retry command that could not help. The freeze now compares a segmented page up to 24 MiB read back whole, as its publication already did, so the page gets the outcome an inline page gets. A page whose stored body can't be read at the freeze (`page_body_segmented`, or `page_body_rows_unreadable`) is held `page_write_failed`, naming its code, and the rest of the source syncs. `gbrain sync status` classifies such a hold by that code (`page_body_rows_unreadable`: retry, no person needed), not as an unplaced `page_write_failed`. A run that does stop before any write request is admitted (discovery, freeze or admission) now shows `last_error.request_id: null` in `gbrain sync status --json` instead of leaving the field out: there is no receipt, root request or `write_error_detail` to look for, and the phase, code and message name the error.
A full sync's DB-only reconcile (#2426) now re-exports a page stored in segments instead of refusing it: the file is measured from the segments of one generation, then streamed through the staging writer the withdrawal mirror and restore_page use, written under an in-progress name and renamed once whole, with the bytes `gbrain export` writes and the existing file's mode. A file over the pre-push secret-scan cap is skipped before the page's `source_path` is bound. Pages whose re-export fails are listed in the result's `reexport_failures`, and the run completes. A segmented read no longer refuses a healthy page `page_body_rows_unreadable` because a new body published between its reads.
@@ -21,7 +21,7 @@ A full sync's DB-only reconcile (#2426) now re-exports a page stored in segments
- `src/core/page-state/import-guard.ts` (`sameCanonicalImport`): a stored body left unread (over 24 MiB) differs from any parsed body, as `sameContentAnyKeyOrder` already said, instead of reading the throwing getter.
- `src/core/persistence/sync-screen.ts` (`frozenImportScreenInput`): the freeze screen reads the page snapshot (and a rename's base) through `materializedSnapshot`.
- `src/core/persistence/sync-entry-fault.ts` (`freezeFaultHold`): `page_body_segmented` and `page_body_rows_unreadable` thrown while freezing one entry hold that entry `page_write_failed` (origin `freeze`, `write_failure.code` the page-body code) instead of stopping the run. The item breaker still applies.
-- `src/core/persistence/sync-fault-class.ts`, `public-category.ts`, `sync-status.ts` (`holdVerdict`): rows for both codes (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, the segment-table grant), applied to a `page_write_failed` hold whose `write_failure.code` names one.
+- `src/core/persistence/sync-fault-class.ts`, `public-category.ts`, `sync-status.ts` (`holdVerdict`): rows for both codes (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, the segment-table grant), applied to a `page_write_failed` hold whose `write_failure.code` names one; `last_error.request_id` is `null` for a failure no request was admitted for.
- `src/core/write-through.ts` (`writePageThrough`): a page stored in segments is measured from its segments (`unreadPageFile`) and checked against the pre-push scan cap before `source_path` is bound, then streamed (`stageStreamedContent`, which refuses bytes that changed since the measure) on the engine it was given, so a caller inside a transaction (an owner repair) works, keeping the existing file's mode, and renamed over the target after the file-changed check; frontmatter overrides on such a page are refused with an error result.
- `src/core/persistence/page-prepare.ts` (`fileMatchesSnapshot`): a segmented snapshot is compared read back whole, so the freeze drift screen no longer reads a format-only difference as drift.
- `src/core/cycle/derived-write-through.ts` (`writeDerivedFile`): a generated page stored in segments is skipped (`segmented_page`), since the batch rollback compares file strings.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 7fb99b915c..c979fcb22e 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1414,7 +1414,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.553.0', id: 'empty_nonstring_args_gst927', text: 'Read tools now treat an optional argument as not provided when its own schema rules the value out: 0 where the range starts above zero (limit: 0, around_chunk_id: 0, schema_version: 0 and others), [] where the list must not be empty (types, only, traverse_graph hops), {} where the object needs a field (get_page lines and bytes), false on get_versions diff, and get_page context without grep. These calls used to refuse with invalid_params; now they answer as if the argument were left out. get_page known_as_of beside window or view arguments still refuses, and the refusal names the arguments to drop.' },
// GBRA-283 Wave A (supersedes #8454): per-engine caches; release:restamp stamps since at the merge slot.
{ since: '0.60.556.0', id: 'engine_keyed_caches_gbra283', text: 'A process serving several brains (mounts) now keeps each brain\'s search telemetry in that brain\'s own database and reads each brain\'s own search.track_retrieval, admission quotas, mcp.strict_params fallback, publication ceiling, capacity-notice throttle and the two vector-search rollback settings. Before, the first brain to be read decided these for every brain in the process, and every brain\'s search telemetry was written into the first brain\'s database. A process with one brain behaves as before.' },
- { since: 'TBD', id: 'segmented_freeze_hold_gbra287', text: 'A managed sync whose freeze compares a Git-tracked page stored in segments with working-tree bytes that differ from the pinned commit now reads a page up to 24 MiB back whole, as its publication does, instead of refusing with `page_body_segmented` and stopping the source (`sync_blocked`) on every later sync. A page whose stored body cannot be read while it is frozen (`page_body_segmented` or `page_body_rows_unreadable`) is held `page_write_failed` with that code named, and the rest of the source syncs; `gbrain sync status` classifies such a hold by that code (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, no person needed) instead of as an unplaced `page_write_failed`.' },
+ { since: 'TBD', id: 'segmented_freeze_hold_gbra287', text: 'A managed sync whose freeze compares a Git-tracked page stored in segments with working-tree bytes that differ from the pinned commit now reads a page up to 24 MiB back whole, as its publication does, instead of refusing with `page_body_segmented` and stopping the source (`sync_blocked`) on every later sync. A page whose stored body cannot be read while it is frozen (`page_body_segmented` or `page_body_rows_unreadable`) is held `page_write_failed` with that code named, and the rest of the source syncs; `gbrain sync status` classifies such a hold by that code (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, no person needed) instead of as an unplaced `page_write_failed`. A sync that stops before admitting any write request shows `last_error.request_id: null` in `gbrain sync status --json` instead of omitting it.' },
{ since: 'TBD', id: 'segmented_reexport_gbra287', text: 'A full sync re-exports a DB-only page (#2426) stored in segments, streaming its file with the bytes `gbrain export` writes, instead of listing it as a `page_body_segmented` failure; a page whose re-export fails is returned in the result\'s `reexport_failures` and the run completes. Write-through of a page stored in segments keeps the existing file\'s mode, skips a file over the pre-push scan cap before binding `source_path`, and with frontmatter overrides returns an error result instead of a `page_body_segmented` one; the derived (generated-page) writer skips such a page (`segmented_page`). A segmented read whose page published a new body between its reads reads one generation (or the new live one) instead of refusing `page_body_rows_unreadable`.' },
];
diff --git a/src/core/persistence/sync-status.ts b/src/core/persistence/sync-status.ts
index d4bf0555af..a24befaa27 100644
--- a/src/core/persistence/sync-status.ts
+++ b/src/core/persistence/sync-status.ts
@@ -79,7 +79,12 @@ export interface SyncStatusError extends SyncFaultVerdict {
write_error_detail?: Record<string, unknown>;
slug?: string;
path?: string;
- request_id?: string;
+ /**
+ * The write request the failure's receipt belongs to (`gbrain write-request <id>`). GBRA-287: null when the run stopped
+ * in its discovery, freeze or admission phase before any request was admitted, so there is no receipt, root request
+ * (`root_cause`) or `write_error_detail` to read; `phase`, `code` and `message` name the error.
+ */
+ request_id?: string | null;
phase: ManagedSyncFailure['phase'];
first_seen: string;
attempts: number;
@@ -388,7 +393,7 @@ export async function readSyncStatus(engine: BrainEngine, sourceId: string, opts
const lastError: SyncStatusError | null = failure ? { code: failure.code, category: recorded!.category, public_category: recorded!.public_category,
...(laneFault ? { detail: laneFault } : {}), message: failure.message, ...(failure.write_error_detail ? { write_error_detail: failure.write_error_detail } : {}),
path: failure.path, phase: failure.phase, first_seen: failure.first_seen, attempts: failure.attempts,
- ...(failure.request_id ? { request_id: failure.request_id } : {}), ...(rootCause ? { root_cause: rootCause } : {}),
+ request_id: failure.request_id ?? null, ...(rootCause ? { root_cause: rootCause } : {}),
...(failure.repeats ? { repeats: failure.repeats } : {}),
...classifySyncFault({ code: failure.code, detail: laneFault, message: failure.message, repeated: failure.repeats ? { path: failure.path, runs: failure.repeats } : null }) }
: retired ? { code: 'cursor_incarnation_retired', category: 'sync_fault', public_category: 'superseded', message: `An unfinished sync cursor of ${sourceId} was recorded under an incarnation the source no longer has; no current sync selects it, and it says nothing about whether the current files are imported. `
diff --git a/test/large-pages/managed-sync-segmented-freeze.test.ts b/test/large-pages/managed-sync-segmented-freeze.test.ts
index d0f0d54222..fd0b45aebe 100644
--- a/test/large-pages/managed-sync-segmented-freeze.test.ts
+++ b/test/large-pages/managed-sync-segmented-freeze.test.ts
@@ -5,7 +5,8 @@
* the stored page read back whole, as its publication does, so a segmented page up to the single-string ceiling earns
* exactly the outcome its inline twin earns (here the `worktree_dirty` hold) and the run completes. A page whose
* stored body cannot be read (segment rows that do not tile it) is held at the freeze, naming
- * `page_body_rows_unreadable`, while the rest of the commit imports and the run completes.
+ * `page_body_rows_unreadable`, while the rest of the commit imports and the run completes; `gbrain sync status` classifies
+ * that hold by its page-body code. A run that does stop in its freeze phase reports `request_id: null` (none admitted).
* 2. Fails when: the freeze reads the snapshot's throwing body getter (`rowToPage.compiled_truth`, `page_body_segmented`)
* and the run stops `blocked` with a recorded failure, or a page-body fault blocks the run instead of holding the page.
* 3. PGLite.
@@ -21,6 +22,9 @@ import { claimWorktree } from '../../src/core/persistence/ownership.ts';
import { performManagedSync } from '../../src/core/persistence/sync-run.ts';
import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';
import { withEnv } from '../helpers/with-env.ts';
+import { opError } from '../../src/core/ops/contract.ts';
+import { installFaultHook } from '../../src/core/persistence/fault-points.ts';
+import { readSyncStatus } from '../../src/core/persistence/sync-status.ts';
import { withManagedFixtureWrite } from '../helpers/managed-e2e-fixture-write.ts';
import { conversationBody } from '../helpers/conversation-page.ts';
@@ -88,10 +92,22 @@ test('a segmented page whose rows do not tile its body is held at the freeze; th
expect(result.failures).toBeUndefined();
expect((result.held ?? []).map(hold => [hold.path, hold.code])).toEqual([['people/person-example.md', 'page_write_failed']]);
expect(result.held![0]!.message).toContain('page_body_rows_unreadable');
- const { readSyncStatus } = await import('../../src/core/persistence/sync-status.ts');
expect((await readSyncStatus(engine, f.sourceId, { detail: false })).holds).toEqual([expect.objectContaining({ code: 'page_write_failed',
path: 'people/person-example.md', needs_human: false, safe_actions: ['retry'] })]);
const [other] = await engine.executeRaw<{ compiled_truth: string }>("SELECT compiled_truth FROM pages WHERE source_id=$1 AND slug='people/other-example'", [f.sourceId]);
expect(other!.compiled_truth).toContain('second');
expect(await engine.executeRaw('SELECT last_commit FROM sources WHERE id=$1', [f.sourceId])).toEqual([{ last_commit: git(f.root, 'rev-parse', 'HEAD') }]);
}), 300_000);
+
+test('a run stopped in its freeze phase, before any request is admitted, says so in sync status (request_id null)', async () => withEnv(env, async () => {
+ const f = await fixture(false, 4 * 1024);
+ writeFileSync(join(f.root, 'people/other-example.md'), '---\ntype: person\ntitle: Other Example\n---\n\nsecond\n');
+ commit(f.root);
+ installFaultHook(point => { if (point === 'sync:after_freeze') throw opError('plan_stale', 'synthetic deliberate refusal', 'none'); });
+ try {
+ await expect(performManagedSync(engine, { sourceId: f.sourceId, noPull: true, noEmbed: true, noExtract: true })).rejects.toThrow('request=<not-admitted>');
+ } finally { installFaultHook(undefined); }
+ const { last_error } = await readSyncStatus(engine, f.sourceId, { detail: false });
+ expect(last_error).toMatchObject({ code: 'plan_stale', phase: 'freeze', path: 'people/other-example.md', request_id: null });
+ expect(last_error!.root_cause).toBeUndefined();
+}), 300_000);