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.mdindex 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.tsindex 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.tsindex 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, optsconst 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.tsindex 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; thexpect(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);