Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: changelog and key-files note for the segmented replace fix (#8729)
garrytane7effb3852a6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1b24974bc7..ede5d9d0bd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,19 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**A segmented page that sync replaces on Postgres now publishes on the first try instead of being refused `body_staging_expired` ("does not cover its N-byte body") and blocking its source until the next sync.** The import ran its version write, which for a segmented page prunes old versions and sweeps their segment rows, at the same time as the flip that publishes the new body. On Postgres the two overlap on one connection, so the sweep could delete the freshly published tail row between the flip clearing its staging and bumping the page's generation. PGLite runs them in order, so only Postgres was affected. The refusal now records which staging was short, a retry inside the run really prepares the page again, and `gbrain sources writer failures` answers within its bound on a source full of large sync writes.++### Itemized changes++- `src/core/import-file.ts` (#8729): a segmented import writes its version before the page write, as unpinned and demoting imports already did, so the version prune and segment sweep never run beside the flip.+- `src/core/persistence/sync-prepare.ts`: a waiver screen aborts the segmented staging its import opened as soon as the import hands it over, on the unbounded engine so a screen past its deadline still aborts it. Before, every screened replace left a second staging live until the idle sweep.+- `src/core/persistence/sync-pass-batch.ts`, `sync-run.ts`: an in-place re-freeze in a pass takes `passRequestId(…, failedRequestId)` instead of the failed request's own id, so the retry prepares the entry again instead of reading the failed receipt back. The first freeze keeps the v1 id; `STOPS_PER_ENTRY` still bounds retries. A chain restarted in the same pass can still re-derive an earlier chain's ids (#8750).+- `src/core/persistence/publication-failure.ts`, `coordinator.ts`: a `body_staging_expired` refusal's `error_detail` is `{ origin: 'body_staging', staging: { staging_id, state, reason, rows, segment_count, covered_bytes, body_bytes } }`, read field by field from the engine's detail. Remote callers still see only `origin`.+- `src/core/persistence/terminal-classify.ts`, `terminal-failures.ts`: the supersession probe tests the failed row's intent kind before it reads any later request's intent, and `readTerminalFailures` selects its page of rows before the lateral join, so the drill-down and the summary no longer detoast every later sync write's frozen file per failed row. On 200 failed and 2,000 committed large-intent writes the drill-down went from `unknown` at the 5 s bound to about 2 s.+- Tests on PGLite and Postgres: `test/large-pages/segmented-sync-replace-8729.test.ts` and `test/e2e/segmented-sync-replace-8729-postgres.test.ts` (tail-only replaces while every version prunes, no staging left live, a forced refusal recorded and prepared again), `test/e2e/terminal-failures-large-intents-8729-postgres.test.ts`, `test/publication-failure-staging-8729.test.ts`, `test/terminal-supersession-kind-8729.test.ts`, `test/sync-pass-retry-id-8729.test.ts`.+## [0.60.597.0] - 2026-11-06**`gbrain upgrade` now restarts a jobs supervisor started from a source checkout as `bun run src/cli.ts jobs supervisor` instead of refusing the upgrade with `restart_refused`.** The restart planner recognised a gbrain process only when its command line held a path containing "gbrain", so a supervisor launched with a relative `src/cli.ts` was invisible, its worker looked unsupervised, and the upgrade stopped. Four smaller fixes ride along with it, covering a flaky spend-guard SIGTERM test, the PGLite snapshot cache keys, the stress gate's pooled-owner match, and the ownership stamp on a checkout that became a Git repository after it was stamped.diff --git a/docs/architecture/key-files/managed-sync-bookkeeping.md b/docs/architecture/key-files/managed-sync-bookkeeping.mdindex 24d712b3df..94dd1b4769 100644--- a/docs/architecture/key-files/managed-sync-bookkeeping.md+++ b/docs/architecture/key-files/managed-sync-bookkeeping.md@@ -36,7 +36,7 @@ run, and the supersession of a checkpoint whose cursor another run replaced. The- `src/core/persistence/sync-stop-class.ts` — #6712 (L2; #6565): how the settle path in `sync-run.ts` classifies a page request that ended without committing. `receiptClass` reads the terminal classifier: `transport` (a dropped connection or a retryable refusal, re-frozen in place), `page` (held, deferred or blocked under the hold policy) or `systemic` (the run stops with the classifier's action). `resumableStop` is a systemic stop the fault table retries (an unrecognised P0001 or a 55000 surfacing as `storage_error`); `stopRecorded` says an earlier invocation already stopped this run (its failure ledger row carries the run id), so the next plain sync re-freezes every page that refusal failed, bounded by `STOPS_PER_ENTRY`. #6712 PR 3 (L7): `recordedStop` also returns the row's `gbrain_version`. `retryRecordedFailure` in `sync-run.ts` (what `--retry-failed`, now its deprecated alias, did on request) retries every recorded failure on the next plain sync, except a refusal nothing changed since the same version recorded it (`replaysUnchangedRefusal`: a content refusal while the file has its frozen bytes; a `source_changed` pinned import while HEAD is the run's target and the file still holds the working-tree bytes that refused, compared by hash rather than by mtime), a slug-mode refusal and a checkpoint whose source's `last_commit` moved (#6834), which wait for a changed file or `gbrain repair managed-sync-orphans`.- `src/core/persistence/sync-knock-on.ts` — #6643, shrunk by #6712 (one page, one fate): no producer is left. It keeps the legacy predicate over receipts older builds wrote (`error_detail` `{ origin: 'sync_knock_on', reason, root_request_id }`, or the pre-#6643 producers' exact messages, never an operator cancel): `isSyncKnockOn`/`syncKnockOnSql` (one predicate, never NULL) feed the terminal classifier, which renders such a receipt superseded, and `sync-run.ts` `refreezeInPlace`, which re-freezes the entry when a resumed cursor meets one (bounded by `STOPS_PER_ENTRY`, no config key). `cursorFenceCause` reads the two live causes of "cursor changed" (`run_replaced`, `outside_fence`; an older `window_dropped` still parses). `checkpoint-validation.ts` clause 3 skips converted receipts and the cursor's settled index ranges only; #6712 removed the knock-on exemption. `reviveCheckpoint` re-assesses a refused checkpoint at the cursor's end. `sync status` shows the cursor the recorded failure belongs to, `cursors`, and `checkpoint_blockers` (`listIncompleteSyncReceipts`, each with `knock_on`).- `src/core/persistence/terminal-classify.ts` — #6650: `classifyTerminal` turns one terminal receipt (`failed` / `conflict` / `cancelled`, or any row still holding `recovery`) into a `TerminalVerdict` (category, code, origin, class, `safe_actions`, `needs_human`, `defect`, `historical`, `root_request_id`, one structured `action`) at read time; nothing is persisted. A recovery record outranks the code (`recovery_pending` / `recovery_blocked`); a knock-on is read through `isSyncKnockOn` (typed marker survives compaction) or the SQL twin `terminalKnockOnSql`; `storage_error` and `source_changed` route by their recorded origin or cause, and a row whose code and origin do not say what happened is `diagnosis_required` (read-only writer status, never a guessed fix). A `source_changed` whose canonical file is missing is `canonical_file_missing` (a ghost page; its exit is the `gbrain repair ghost-pages` preview, never a sync retry), and an origin-less `fence_unrenderable` adoption refusal is its own defect category. A retryable sync fault's `action` follows its operation (`faultOperation`: a `put_page` under a `canonical_reconcile` or `managed_*` intent kind reads as that kind): `submit_job` and a canonical reconcile keep the sync retry, a caller-submitted page or memory write (`RESUBMITTED_WRITES`) gets the read-only writer-status inspect and a resubmit with a new request_id, a `managed_*` write the inspect and a rerun of its command, any other operation the inspect alone. `TERMINAL_FIXED_IN` names the release that fixed a category; a row whose build (`error_detail.attempt.consumer_version`, else `admitter_version`) is older is historical. It also owns the supersession rule `repair/failed-writes.ts` reuses (`supersessionSql`, `supersessionOrderSql`, `dispositionOf`, `PAGE_REMOVAL_OPERATIONS`). Tests: `test/terminal-failures-6650.test.ts` (TS↔SQL twin parity included), `test/terminal-classify-6696.test.ts`.-- `src/core/persistence/terminal-failures.ts` — #6650: the bounded readers over that classifier. `readTerminalFailureSummary` is one set-based aggregate (GROUPING SETS per source; `TERMINAL_STATEMENT_MS` 5 s statement and `TERMINAL_ACQUIRE_MS` 2 s connection deadlines; past either it returns `status: 'unknown'`, never an empty pile) splitting active blockers (recovery records plus the passed-in `checkpoint_blockers` of `sync-status.ts`, read by `readCheckpointBlockerMap`), unresolved rows (count, distinct slugs and intents, oldest age), historical rows (a later write superseded them, or older than `TERMINAL_FIXED_IN` via the SQL twin `TERMINAL_HISTORICAL_SQL`), 24 h and 7-day daily counts, categories and defect classes; archived sources are skipped. Thresholds `persistence.terminal_failures.window_days` (clamped to `persistence.receipt_retention_days`), `spike_factor`, `spike_min` (`readTerminalThresholds`, `validateTerminalConfigValue`, refused at `config set` by `commands/config/preparation-keys.ts`); `isSpike` against `sevenDayMedian`. `readTerminalFailures` is the drill-down (batches of 200, at most 2,000 rows scanned per call, a sequence cursor, verdict filters, `--group-by category` groups, a `sync_fault` group also split by its operation, with an exact `drill_down` argv each; `--operation` filters on `faultOperation`). Consumers: doctor `persistence_terminal_failures` (`commands/doctor/checks/persistence-requests.ts`), `sync status` `terminal_failures` (`sync-status.ts`, `next` falls back to a recovery blocker's action), the `writer_failures` administration operation, and the admin `/metrics` gauges (`serve-http-metrics.ts` `renderTerminalFailureMetrics`, one aggregate per engine shared by scrapes for `TERMINAL_METRICS_TTL_MS` = 60 s via `cachedTerminalSummary`; never `/health`). Each source also reports `new_last_24h_older_builds` (rows and builds older than their class's fix), and doctor's spike message says an older write owner is producing them when they are most of the spike. Tests: `test/terminal-failures-6650.test.ts`, `test/sync-status-terminal-6650.test.ts`, `test/terminal-failure-metrics-6650.test.ts`, the CLI journey `test/agent-journey-terminal-failures-6650.test.ts`.+- `src/core/persistence/terminal-failures.ts` — #6650: the bounded readers over that classifier. `readTerminalFailureSummary` is one set-based aggregate (GROUPING SETS per source; `TERMINAL_STATEMENT_MS` 5 s statement and `TERMINAL_ACQUIRE_MS` 2 s connection deadlines; past either it returns `status: 'unknown'`, never an empty pile) splitting active blockers (recovery records plus the passed-in `checkpoint_blockers` of `sync-status.ts`, read by `readCheckpointBlockerMap`), unresolved rows (count, distinct slugs and intents, oldest age), historical rows (a later write superseded them, or older than `TERMINAL_FIXED_IN` via the SQL twin `TERMINAL_HISTORICAL_SQL`), 24 h and 7-day daily counts, categories and defect classes; archived sources are skipped. Thresholds `persistence.terminal_failures.window_days` (clamped to `persistence.receipt_retention_days`), `spike_factor`, `spike_min` (`readTerminalThresholds`, `validateTerminalConfigValue`, refused at `config set` by `commands/config/preparation-keys.ts`); `isSpike` against `sevenDayMedian`. `readTerminalFailures` is the drill-down (batches of 200, each selected before the supersession lateral join, which with the summary's probe tests the failed row's intent kind first so later large sync intents are not detoasted per row (#8729), at most 2,000 rows scanned per call, a sequence cursor, verdict filters, `--group-by category` groups, a `sync_fault` group also split by its operation, with an exact `drill_down` argv each; `--operation` filters on `faultOperation`). Consumers: doctor `persistence_terminal_failures` (`commands/doctor/checks/persistence-requests.ts`), `sync status` `terminal_failures` (`sync-status.ts`, `next` falls back to a recovery blocker's action), the `writer_failures` administration operation, and the admin `/metrics` gauges (`serve-http-metrics.ts` `renderTerminalFailureMetrics`, one aggregate per engine shared by scrapes for `TERMINAL_METRICS_TTL_MS` = 60 s via `cachedTerminalSummary`; never `/health`). Each source also reports `new_last_24h_older_builds` (rows and builds older than their class's fix), and doctor's spike message says an older write owner is producing them when they are most of the spike. Tests: `test/terminal-failures-6650.test.ts`, `test/sync-status-terminal-6650.test.ts`, `test/terminal-failure-metrics-6650.test.ts`, the CLI journey `test/agent-journey-terminal-failures-6650.test.ts`.- `src/commands/sources-writer-failures.ts` — #6650: output of `gbrain sources writer failures <source> [--state all] [--group-by category] [--since Nd] [--limit N] [--before <cursor>] [--category|--code|--origin|--operation] [--json]`, dispatched by `persistence-admin.ts` as `writer_failures` (validated in `administration.ts` `writerFailuresQuery`, locally or through the resident owner). A table by default, one JSON document with `--json`; row and group `fix` / `inspect` actions are rendered for the CLI; a full page prints `truncated` with the exact next command. The operation is advertised to clients in the owner's `administration_extensions` (`ipc.ts`, `admin-contract.ts` `PERSISTENCE_ADMIN_EXTENSIONS`), never in the `administration` list an older client validates strictly, and `local-client.ts` delegates it only to an owner that lists it (`ownerAdministers`). Tests: `test/writer-failures-cli-6650.test.ts`.- `src/core/persistence/public-category.ts` — #6712 PR 2 (L5): `publicCategory({ category?, code })`, the closed public vocabulary (`drift`, `conflict`, `content_refused`, `file_missing`, `permission`, `storage`, `config`, `superseded`, `transient`, `defect`) that sits beside the unchanged diagnosis `category`. `PUBLIC_BY_TERMINAL` maps every `TerminalCategory`, `PUBLIC_BY_CODE` every `SYNC_FAULT_TABLE` code (a new fault code needs a row: `test/public-category.test.ts`), and anything else goes by its registry class (unknown codes are `defect`). `classifyTerminal` carries it as `public_category`; `classifyRecordedFault` (terminal-classify.ts) reads a hold, a managed-sync failure row or a run stop as the failed receipt it stands for, so the receipt diagnosis, `managedWrite`, sync status holds and `last_error`, the terminal summary and doctor `sync_failures` (`details.failures`) render one verdict.- Pass round phase lines and honest stalls (GBRA-133 PR 3a, #7243; `src/core/persistence/sync-pass-run.ts`, `sync-pass-status.ts`, `sync-drain.ts`) — each pass round emits `managed_sync.round_level` (paths, target, read time) after its level read and `managed_sync.round_admit` (imports, deletes, in flight) before its import walk, and a `managed_sync.round_batch` (`batch` of `batches`, starting at candidate `base`, #7866) before each import batch; an announcing drain prints the level and admit lines (`[sync] pass round N: …`). The `convergence` block's `target` is the newest pass's pinned commit (telemetry) and `converged_target` the stored converged obligation's target, null while no stamp backs one, so status never presents the pin as converged. The drain counts only page and checkpoint commits as progress (a legacy-sweep slice or a level read still working only keeps the quiet clock fresh); an abandoned pass's late progress is dropped; a stop whose head owner reports `restart_required` is `owner_restart_required` (`drainNext` names the process); a run that committed nothing (no advanced cursor, no committed page) stops as `sync_deadline_stalled` (exit 1). Tests: `test/sync-pass-phase-lines-7243.serial.test.ts`, `test/sync-status-truthful-7243.test.ts`, `test/honest-stalls-gbra133.test.ts`.