Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Read-only mirrors: the held comparison stops pointing at previews that find nothing (GST-2869) (#9568)
Garry Tanead6d5f497c8
diff --git a/behavior-changes.d/mirror_compare_names_writable_route_gst2869.md b/behavior-changes.d/mirror_compare_names_writable_route_gst2869.mdnew file mode 100644index 0000000000..a813cbda21--- /dev/null+++ b/behavior-changes.d/mirror_compare_names_writable_route_gst2869.md@@ -0,0 +1,4 @@+---+kind: fix+---+On a read-only mirror source, gbrain repair file-drift --held without --prefer no longer names a --prefer file (or --prefer database) preview for a page that differs from its file, in the page's why or in next_actions. Those previews read every mirror page as database-only and found nothing. The comparison keeps each page's verdict and evidence and says the page stays held until the user makes the source writable again with gbrain sources mirror-writable <id>.diff --git a/behavior-changes.d/rehold_retry_not_progress_gst2869.md b/behavior-changes.d/rehold_retry_not_progress_gst2869.mdnew file mode 100644index 0000000000..dabc942ecb--- /dev/null+++ b/behavior-changes.d/rehold_retry_not_progress_gst2869.md@@ -0,0 +1,4 @@+---+kind: fix+---+A stopped sync pass no longer counts as progress when the only holds it rewrote were re-checked because gbrain sync unblock or gbrain sources retry-held asked (the hold is now marked retry_only), or when the rewrite brought a transient hold (preparation_stalled, write_interrupted, or a page write that failed while frozen) to its attempt cap. Before, such a re-hold reset the abandoned-pass count once per retry round, so a source could stay pass_interrupted instead of reaching pass_abandoned.diff --git a/changelog.d/gbra-568-mirror-followups.md b/changelog.d/gbra-568-mirror-followups.mdnew file mode 100644index 0000000000..5a990e5690--- /dev/null+++ b/changelog.d/gbra-568-mirror-followups.md@@ -0,0 +1,9 @@+**On a read-only mirror, the held file-drift comparison no longer points at previews that find nothing, and a pass that only re-held what a retry asked for no longer counts as progress.**++### Fixed+- On a read-only mirror, `gbrain repair file-drift --held` keeps each differing page's verdict and evidence but no longer names a `--prefer` preview, because those previews read every mirror page as database-only. It says the page stays held until the source is writable again (`gbrain sources mirror-writable <id>`).+- A stopped sync pass whose only rewritten holds were re-checked because `sync unblock` or `sources retry-held` asked, or that brought a transient hold to its attempt cap, no longer resets the abandoned-pass count.+- The sync-unblock runbook's `pass_abandoned` row, the repair guide (mirror comparison, `complete: false` on a held dry run) and the `sources status` key-file entry (`by_code` counts every hold) now match what gbrain does.++<!-- behavior-change: mirror_compare_names_writable_route_gst2869 -->+<!-- behavior-change: rehold_retry_not_progress_gst2869 -->diff --git a/docs/architecture/key-files/core-persistence-continued.md b/docs/architecture/key-files/core-persistence-continued.mdindex ca2090e90f..401733e0cf 100644--- a/docs/architecture/key-files/core-persistence-continued.md+++ b/docs/architecture/key-files/core-persistence-continued.md@@ -13,7 +13,7 @@ The #6188 fence check and fence repair live in [fence repair](core-fence-repair.- `src/core/persistence/connector-sync.ts` — managed Google/GitHub API ingestion through source-scoped journaled `connector_v2_import`/`_delete`/`_checkpoint`/`_google_receipts` intents and `managed-connector` checkpoint CAS, not Git cursors. The checkpoint key, admission `configHash`, mid-sweep change check and publication `source_changed` check all use the parsed-config identity from `connector-identity.ts`, so cycle stamps in `sources.config` never rotate them. Unbound connectors use reviewed `connector_database` SQL-only authority; bound connectors retain canonical file publication with guarded root/hash/revision/epoch. Every managed run checks the credential's resolved account against the pin in the connector state row before reading its checkpoint (`assertAccount`), then applies a requested `--reset-checkpoint` (pending writes resolved first, pin kept). Each import or delete is first screened by running `prepareConnectorMutation` on an unadmitted request through the no-op kernel; unchanged items take no admission. An unchanged checkpoint save is skipped and, when it would have stamped freshness, `last_sync_at` is stamped directly inside a lease-asserted coordinated write. Accepted-pending writes are progress: a 30-second total wait budget (writes committing within one second are free), at most one in-flight write per page, outstanding writes kept under the principal's outstanding and intent-byte limits, and `ConnectorWaitBudgetStop` (a `write_pending` error) when the budget is spent. The checkpoint never advances past a pending page; the run records its pending set in the state row, and the next run resolves it first (committed dropped, failed retried automatically through the retry-pointer path without `--retry-failed`, unreached failures after a complete sweep dropped and counted). Retired `managed_connector_*` intents route to `prepareOutdatedConnectorMutation`, which fails them `connector_intent_outdated` (detail `pre_upgrade` before the v176 cutoff). Standalone entry, page reads and submissions authenticate the current source, local grant and canonical owner and settle retained worktree publications before deriving request identity. Explicit `--retry-failed` atomically admits a linked attempt and stores a per-base-request `managed-connector-retry` pointer. Durable connector cursors, retry pointers and state rows survive generic seven-day checkpoint GC. Tests: `test/persistence-connectors.test.ts`, `test/persistence-connector-retry.test.ts`, `test/connector-checkpoint-identity.test.ts`, `test/connector-wave3.test.ts` and `test/helpers/connector-restart.ts` on PGLite and disposable Postgres. #6831: a page import whose content matches a source page purge tombstone is skipped per item instead of ending the run: screened before admission (`carriesPurgedPage`, the guard's content hash, read only when the source has a tombstone), and a `failed`/`purged_content` receipt the guard still produces (a purge that landed mid-run) is skipped wherever it surfaces (the item's wait, `refreshPending`, `resolvePendingSet`): it is dropped from `receipts`, never joins the automatic retry set, has its optimistic pending count taken back, and is counted in `last_run.purged_skipped` and `purged_items`. A replayed purged receipt is re-checked against the live tombstones (`purgedNow`) before `mayRetry`: still purged, it is skipped even under `--retry-failed`; cleared, it gets one automatic retry. A run that ends on any error except `LockStolenError` or an aborted caller signal records `last_failure` (code, else `connector_error`; message, the item and request when the run ended on that item's receipt, `consecutive`); only a complete `finish()` (cursor saved, nothing pending or failed) clears it. Tests: `test/connector-purged-item-6831.test.ts` (+ `test/e2e/` twin).- `src/core/persistence/connector-identity.ts` — `connectorIdentity(kind, rawConfig, localPath)` returns the parsed connector config and a digest over every parsed leaf except credential-delivery fields (Google `access`/`tokenCommand`/`tokenEnv`; GitHub `tokenEnv` and `app` under `scope: repos`, `app.pemPath` always; under `scope: auto` the token env without an App and the App ids are identity). `services`/`repos` are sorted and de-duplicated; a parser leaf missing from `CONNECTOR_LEAF_RULES` joins the identity. #6561: a leaf a parser starts emitting with a behavior-preserving default declares it as `elideWhen` (Google `contactsDir: 'people'`) and is left out of the digest while it holds it, so unchanged sources keep the pre-field key; the non-elided digest is kept as `aliasDigests` (`connectorCheckpointKeys` returns the stable key then its alias keys; `connectorIdentityMatches` accepts an admitted write's frozen `configHash` under either). Also `connectorCheckpointKey` and `isConnectorIntentKind`/`connectorIntentSql`, the one predicate for both intent namespaces. Test: `test/connector-identity.test.ts` enumerates every parser leaf.- `src/core/persistence/connector-state.ts` — (fix wave 4: also `first_attempt_at`, the autopilot connector dispatch gate, recorded before the first provider call of a validated, non-preview sync and seeded by migration v181) the per-source-incarnation `op='managed-connector-state'` row (fingerprint `digest({sourceId, incarnation})`, independent of the identity digest): account pin, pending set `{itemRef, requestId, baseRequestId, admittedAt}`, `upgrade_recovery` (`resumed`/`rewalking_once`/`none`) with `resumed_from`, `continuity_unverified` and last-run counts. `writeManagedConnectorState` checks the connector sync lease in the same statement. `connector-status.ts` renders it for `gbrain sources status` without the account. #6831: `purged_items` (newest `CONNECTOR_PURGED_LIMIT` purged skips) and `last_failure` (`ConnectorRunFailure`); `CONNECTOR_STOPPED_RUNS` (3) consecutive failed runs read as stopped in `connector-status.ts` (`sources status` lines, `readConnectorLastError` for `sync status`'s additive `connector_last_error`; `last_error`, `state` and `next` are untouched) and doctor `sync_freshness` (`stoppedConnectorIssues` in `doctor/sync-outcome.ts`).-- `src/core/persistence/connector-status.ts` — `sources status` views of connector state and Git holds. `gitHoldStatusJson` (#7326) bounds `git_holds` in `--json`: summary by default (`count`, `by_code` with one example each, the first `HELD_STATUS_LIMIT` items, `items_complete`/`items_command`), every item read under `--holds`, or a `pageSortedRows` keyset page by path under `--limit`/`--cursor` (`test/sources-status-holds-bounded-7326.test.ts`, `test/sync-hold-surfaces.test.ts`).+- `src/core/persistence/connector-status.ts` — `sources status` views of connector state and Git holds. `gitHoldStatusJson` (#7326) bounds `git_holds` in `--json`: summary by default (`count`, `by_code` counting every hold of the source, with an example only for a code the listed items include, and `by_code_complete: false` when the count fell back to the listed files, the first `HELD_STATUS_LIMIT` items, `items_complete`/`items_command`), every item read under `--holds`, or a `pageSortedRows` keyset page by path under `--limit`/`--cursor` (`test/sources-status-holds-bounded-7326.test.ts`, `test/sync-hold-surfaces.test.ts`).- `src/core/connectors/item-holds.ts` — fix wave 4 connector item holds, shared by Gmail and GitHub on managed and unmanaged brains: `classifyConnectorError` (the one table: source-scoped, rate-limit and item-scoped codes, content vs transient class) and `ItemHoldsRun` (hold after 3 consecutive attempted runs at one upstream version; circuit breaker at 5 attempted items with half transient or 5 and half one code; backoff 1 h/6 h/24 h/daily for 7 days; cap 100, `connector_holds_exhausted`). A run's changes merge only in `finish()`, so mid-run checkpoints carry the holds the run began with and a cursor never passes an item that is not already held. `carryLegacyFailCounts` reads the retired Gmail ledger once.- `src/core/connectors/item-holds-store.ts` + `connector-hold-session.ts` — reads holds from the cursor state (managed checkpoint row or the unmanaged state file) for `sources status`, doctor `connector_held_items` and `open_loops` completeness; the `connector-hold-retry` request rows and the pending `managed-connector-retry` pointers `sources retry-held` writes; the per-run session that skips held items, publishes holds on a managed abort (`publishHolds`), releases held items' terminal receipts from the automatic retry set and consumes retry-held keys. Git-source holds are not read here: only `sources status` (`persistence/connector-status.ts` `readGitHoldStatuses`, `sources status <id>` filters to one source) and `sources retry-held` (a Git source records a `sync-hold-retry` re-screen request for its held paths; `gbrain sync --retry-held` refuses with that pointer) show them beside connector holds. Writer deactivation and activation never read or block on them.- `src/core/connectors/connector-text.ts` — #5752 render boundary: prose sanitized with `sanitizeForJsonb` before the no-op screen; identity fields refuse with `invalid_connector_text`.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex 56d3585cc2..6372693a8f 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -3686,6 +3686,17 @@ are newer. A `--prefer` preview without a side names this comparison as itsgbrain repair file-drift --source <id> --held --json # compare every held page, no winner named```+<a id="file-drift-compare-mirror"></a>On a [read-only mirror](multi-source-brains.md#read-only-mirror-sources)+(GST-2843), the held comparison reads each held page's file too: a page that+differs reads `prefer_file` or `needs_human` with its `evidence`, one that+matches reads `release_hold`, and only a page whose file is gone reads+`no_drift` with `database_only`. Every compared page in `details.pages`+carries `evidence` (null when nothing was read). The comparison names no+`--prefer` preview there, because a mirror's previews read every page as+database-only and resolve nothing: a differing page stays held until the user+makes the source writable again (`gbrain sources mirror-writable <id>`, which+lets gbrain write files into its checkout) and picks a side then (GST-2869).+<a id="file-drift-kept-newer"></a>`--prefer file` never drops a page edited after its file's last commit inbulk. A `--held`, `--all-drifted` or `--request` preview lists such a page`kept_newer_page`, with the edit's time, the file's commit time and the two ways@@ -3747,7 +3758,11 @@ reads the database a few dozen times, so a large held set against a remotedatabase takes minutes per hundred pages). It reports each page on stderr asit goes. The hash and the printed apply command cover only that window. Apartial window lists `after_window` in its residuals and prints the next-preview command with `--cursor <next_cursor>` (JSON: `details.window`):+preview command with `--cursor <next_cursor>` (JSON: `details.window`). A held+dry run (a comparison or a `--prefer` preview) reports `complete: false` while+held pages remain past its window, and `details.window.next_command` names the+command for the next window; an apply's `complete` still means every item of+the approved window was attempted:```bashgbrain repair file-drift --source <id> --held --side deleted --state file_gone --prefer database # window 1diff --git a/docs/guides/sync-unblock-runbook.md b/docs/guides/sync-unblock-runbook.mdindex e822d09c8c..006d5a2c62 100644--- a/docs/guides/sync-unblock-runbook.md+++ b/docs/guides/sync-unblock-runbook.md@@ -398,7 +398,7 @@ run converges on the next plain sync with no flag.|---|---|---|---|| `pass_unfinished` | resumable | The newest pass is open or stopped at a deadline. | The plain sync (`resume_argv`); safe to loop. || `pass_interrupted` | resumable | The newest pass is open but no process holds the source's drain lease: its process was killed or crashed (an out-of-memory guard, a timeout) before it ended the pass, so nothing recorded a failure. `live` is null and `interrupted` names the pass, its last write and, when the lock row outlived the process, the holder and the pages it committed. Doctor `managed_sync_blocked` lists it as `pass_interrupted` (warn, then fail after an hour). | The plain sync; if that pass stops the same way, the reason becomes `pass_abandoned`. |-| `pass_abandoned` | blocked | Two passes in a row never ended or ended on the same kind of transient stop, and neither committed a page or wrote a hold before it stopped (a pass that committed work moved the source, so it resets the count; a pass that only reported progress does not): the drain stopped them for making no progress, their process was killed, or each hit a statement timeout, a lost connection or write back-pressure (#7982). The newest open pass counts once no process holds the source's drain lease (#7596; a reader without the lease read counts it once its row has not moved for 5 minutes). | `gbrain doctor --json` and a report with the gbrain version and the newest run's `drain.stall`; another plain sync is likely to stop the same way. |+| `pass_abandoned` | blocked | Two passes in a row never ended or ended on the same kind of transient stop, and neither saved work before it stopped. A pass saved work when it committed a page, held a path it had not held before, or re-checked a held path and cleared that hold's re-check trigger (the hold is no longer due, and a `file_drift` hold names the page's current revision); saved work moved the source, so it resets the count. A pass that only reported progress does not count, nor does one that only re-held a page edited again before it (the hold is marked `basis_moved`), re-held a path only because `sync unblock` or `sources retry-held` asked (`retry_only`), or brought a transient hold to its attempt cap. So passes that only re-hold a page edited again before each of them still end `pass_abandoned`, and from that page's third hold `sync status` reports `needs_human: true` with the page's decision. Passes stop this way when the drain stopped them for making no progress, their process was killed, or each hit a statement timeout, a lost connection or write back-pressure (#7982). The newest open pass counts once no process holds the source's drain lease (#7596; a reader without the lease read counts it once its row has not moved for 5 minutes). | `gbrain doctor --json` and a report with the gbrain version and the newest run's `drain.stall`; another plain sync is likely to stop the same way. || `not_converged` | resumable | The pass used its four rounds while another writer kept changing the level. Everything it admitted stands. | The plain sync; after three such passes in a row `next` is `gbrain doctor --json` and a report, because another sync will not change it. || `settle_mismatch` | resumable | A path keeps settling without reading settled. The next pass re-admits it once; after three passes at one level it is a `settle_mismatch` hold that needs a person. | The plain sync, then report the hold. || `deletes_withheld` | blocked | The pass's deletes crossed the mass-delete threshold (#2828) or an absolute cap (#7130: `sync.max_deletes`, default 500; `sync.max_delete_ratio`, default 0.01 above 50 deletes; per source `<key>.source.<id>`). The record's `trip` names which. It wrote one withheld record and synced everything else; no per-page hold is written. | Ask the user: restore the checkout if it is wrong; when the deletion is intended, raise the cap for that source (`gbrain config set sync.max_deletes.source.<id> <n>`) or run `GBRAIN_ALLOW_MASS_RECONCILE=1 gbrain sync --source <id>` on the brain host. `gbrain sync --source <id> --dry-run --json` lists the set and its hash. |diff --git a/src/core/persistence/sync-classify.ts b/src/core/persistence/sync-classify.tsindex 9339a7a28b..e8bf7754c1 100644--- a/src/core/persistence/sync-classify.ts+++ b/src/core/persistence/sync-classify.ts@@ -65,7 +65,7 @@ export interface SyncPathState {* GST-2201 `deletionSide`: a `file_drift` hold on the deletion side (`tombstone_edited`, `purged_differs`, `file_gone`).* GST-2843 `moved`: the hold's basis or drift moved since it was written (`holdBasisMoved`, `movedDriftHolds`).*/- hold: { atLevel: boolean; rescreenDue: boolean; retried: boolean; unscreened?: boolean; deletionSide?: boolean; moved?: boolean } | null;+ hold: { atLevel: boolean; rescreenDue: boolean; retried: boolean; unscreened?: boolean; deletionSide?: boolean; moved?: boolean; retryOnly?: boolean } | null;/*** A deletion marker at the origin: `deleted` (with the blob ids it held) or `legacy` (the baseline blob of a page deleted* before PR 4; `deletion` is the committed deleting request that proves it, and a legacy marker without one settles nothing).diff --git a/src/core/persistence/sync-discovery.ts b/src/core/persistence/sync-discovery.tsindex da6a3c74f3..08e24532d8 100644--- a/src/core/persistence/sync-discovery.ts+++ b/src/core/persistence/sync-discovery.ts@@ -64,6 +64,8 @@ export interface SyncEntry { path: string; sourcePath: string; action: 'import'driftHistory?: string[];/** GST-2843: the pass re-checks this held path because the hold's basis or drift moved; a hold the entry gets is marked `basis_moved`. */basisMoved?: true;+ /** GST-2869: the pass re-checks this held path only because a retry was requested (`sources retry-held`, `sync unblock`); a hold the entry gets is marked `retry_only`. */+ retryOnly?: true;/** #6727: live pages with no recorded origin whose slugs fold to this file's slug, several or one the importer cannot write; the freeze holds it `legacy_slug_conflict`. */legacySlugs?: string[];/** #6729 x #6727: the one legacy page carries an explicit frontmatter id that differs from the file's, so it is another document; held `legacy_slug_conflict` (`explicit_id_conflict`). */diff --git a/src/core/persistence/sync-holds.ts b/src/core/persistence/sync-holds.tsindex e13c1db92d..40f41b6e00 100644--- a/src/core/persistence/sync-holds.ts+++ b/src/core/persistence/sync-holds.ts@@ -154,6 +154,8 @@ export interface GitHoldMeta {page_revision?: string;/** GST-2843: the pass rewrote this hold because its basis or drift moved, not because a re-screen came due; a later rewrite that is not a move drops it. */basis_moved?: true;+ /** GST-2869: the pass rewrote this hold only because a retry was requested, with no re-screen due and nothing moved; a later rewrite that is not one drops it. */+ retry_only?: true;/** #6712 PR 1 `file_drift`: which side moved since the page's last recorded import (`unknown`: no usable record); `page_revision` is the page's revision when held. */sides?: 'database' | 'both' | 'unknown';/** GBRA-133 `file_drift`: the drift screen that held it; an unknown-side hold from an older screen is re-screened (#7340). */diff --git a/src/core/persistence/sync-pass-apply.ts b/src/core/persistence/sync-pass-apply.tsindex cd5cbe9936..d06dfca844 100644--- a/src/core/persistence/sync-pass-apply.ts+++ b/src/core/persistence/sync-pass-apply.ts@@ -402,7 +402,8 @@ async function writeHolds(engine: BrainEngine, level: ShadowLevel, input: Pick<Pawait writeGitHold(tx, { source_id: level.sourceId, incarnation: level.incarnation, path, source_path: sourcePath, slug: hold.slug,page_id: hold.pageId !== undefined ? hold.pageId : hold.entry.state.page?.live ? hold.entry.pageId : null,code: hold.code, message: hold.message, upstream_version: hold.entry.state.levelSha256, observed_at: input.observedAt, run_id: input.passId, mode: 'managed',- meta: { recovery_version: RECOVERY_VERSION, ...levelMeta(level, hold.entry), ...hold.meta, ...(hold.entry.state.hold?.moved ? { basis_moved: true as const } : {}) } });+ meta: { recovery_version: RECOVERY_VERSION, ...levelMeta(level, hold.entry), ...hold.meta, ...(hold.entry.state.hold?.moved ? { basis_moved: true as const } : {}),+ ...(hold.entry.state.hold?.retryOnly ? { retry_only: true as const } : {}) } });}, slice => {for (const hold of slice) {state.holds[hold.kind]++;diff --git a/src/core/persistence/sync-pass-run.ts b/src/core/persistence/sync-pass-run.tsindex 15c102b0d4..7873b15372 100644--- a/src/core/persistence/sync-pass-run.ts+++ b/src/core/persistence/sync-pass-run.ts@@ -232,12 +232,14 @@ async function batchEntries(engine: BrainEngine, level: ShadowLevel, deletes: Sh// GST-2843: those versions are read per batch, just before the batch drains (readDriftHistories), so a pass over tens of// thousands of such holds commits each batch's holds before it reads the next batch's history.const historyOwed = new Map<PassEntry, ShadowPath>();+ // GST-2843 / GST-2869: why the pass re-checks a held path, stamped on the hold it writes (passBanked reads it).+ const recheckOf = (entry: ShadowPath) => ({ ...(entry.state.hold?.moved ? { basisMoved: true as const } : {}), ...(entry.state.hold?.retryOnly ? { retryOnly: true as const } : {}) });const entries: PassEntry[] = [], collisions: SyncSlugCollision[] = [], skipped: ShadowPath[] = [], identity: Array<{ entry: ShadowPath; origin: ShadowPath | null; slug: string; ids: { page: string; file: string } }> = [];const claims = new Map<string, ShadowPath[]>();for (const entry of imports) {if (step.due()) await step.pause();const paths = entryPaths(level, entry.path);- const base = { ...paths, ...committedOnly, action: 'import' as const, working: working(entry), level: entry.state.level, ...(entry.state.hold?.moved ? { basisMoved: true as const } : {}), ...(entry.result.cls === 'drift' && entry.result.side && entry.result.side !== 'deleted' ? { drift: entry.result.side, ...(driftBaseline(entry) ? { driftBaseline: driftBaseline(entry) } : {}) } : {}) };+ const base = { ...paths, ...committedOnly, action: 'import' as const, working: working(entry), level: entry.state.level, ...recheckOf(entry), ...(entry.result.cls === 'drift' && entry.result.side && entry.result.side !== 'deleted' ? { drift: entry.result.side, ...(driftBaseline(entry) ? { driftBaseline: driftBaseline(entry) } : {}) } : {}) };if (entry.state.page) {const built: PassEntry = { ...base, slug: entry.slug!, pageId: entry.pageId, revision: entry.revision };if (entry.result.cls === 'drift' && entry.result.side === 'unknown' && entry.pageId !== null && entry.state.hold?.unscreened) historyOwed.set(built, entry);@@ -277,7 +279,7 @@ async function batchEntries(engine: BrainEngine, level: ShadowLevel, deletes: Shif (losers.length) collisions.push({ slug, kept: kept ?? entryPaths(level, winner!.path).sourcePath, skipped: losers.map(entry => entryPaths(level, entry.path).sourcePath) });if (!winner) continue;const paths = entryPaths(level, winner.path);- const base = { ...paths, ...committedOnly, action: 'import' as const, working: working(winner), level: winner.state.level, slug, ...legacySlugs.get(winner.path) };+ const base = { ...paths, ...committedOnly, action: 'import' as const, working: working(winner), level: winner.state.level, slug, ...recheckOf(winner), ...legacySlugs.get(winner.path) };if (holder) {// #6729: a file whose frontmatter id differs from the page's is another document; it inherits nothing. GBRA-130 B-4: it is// held alone and the page keeps its slug (its origin's deletion waits with it); discovery still refuses the source.diff --git a/src/core/persistence/sync-pass-status.ts b/src/core/persistence/sync-pass-status.tsindex 50ac90a87f..aeaff0cee3 100644--- a/src/core/persistence/sync-pass-status.ts+++ b/src/core/persistence/sync-pass-status.ts@@ -8,7 +8,8 @@ import type { BrainEngine } from '../engine.ts';import type { Action } from '../agent-output.ts';import type { SyncAdmissionStatus } from './sync-admission.ts';import { digest } from './digest.ts';-import { EVERY_PASS_RESCREEN_CODES, fileDriftSide, GIT_HOLD_OP, holdRescreenDue, type GitHoldRecord } from './sync-holds.ts';+import { EVERY_PASS_RESCREEN_CODES, fileDriftSide, GIT_HOLD_OP, holdRescreenDue, outOfAttemptsHold, type GitHoldRecord } from './sync-holds.ts';+import { HOLD_ATTEMPTS_NEEDS_HUMAN } from './sync-fault-class.ts';import { readDeletesWithheld, type DeletesWithheld } from './sync-markers.ts';import { ABANDONED_QUIET_MS, ABANDONED_REPORT_STREAK, MANAGED_SYNC_PASS_OP, NOT_CONVERGED_REPORT_STREAK, passHealth, passReadClock, transientEnding, type PassRoundSummary,type PassRow } from './sync-pass-row.ts';@@ -70,6 +71,10 @@ export async function passConvergence(engine: Pick<BrainEngine, 'executeRaw'>, iduration_ms: t.duration_ms, timings_ms: t.timings_ms, last_full_at: o.converged?.last_full_at ?? null };}+/** GST-2869: the rewrite was the attempt that exhausted a transient hold's retries, so the hold now waits on a person. */+const reachedAttemptCap = (record: GitHoldRecord) => (record.meta.attempts ?? 1) === HOLD_ATTEMPTS_NEEDS_HUMAN+ && (outOfAttemptsHold(record.code) || (record.code === 'page_write_failed' && record.meta.write_failure?.origin === 'freeze'));+/** GST-2843: how many of a pass's rewritten holds `passBanked` reads per page while it looks for one that settled its re-screen. */const RESCREEN_PAGE = 500;@@ -81,6 +86,8 @@ const RESCREEN_PAGE = 500;* leaves the hold due (a code every pass re-screens) is not progress, so passes that only re-hold those still build the streak.* Nor is a rewrite marked `basis_moved`: the pass re-checked the path because its page or file moved again, so passes that* only re-hold a page that keeps moving build the streak too.+ * GST-2869: nor is a rewrite marked `retry_only` (re-checked only because `sync unblock` or `sources retry-held` asked, with+ * nothing due), nor one that brought a transient hold to its attempt cap: both leave the path where it was, waiting on a person.*/export async function passBanked(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, incarnation: string, telemetry: { pass_id: string; started_at: string }): Promise<boolean> {const [row] = await engine.executeRaw<{ banked: boolean }>(`SELECT EXISTS (SELECT 1 FROM persistence_requests r JOIN persistence_source_bindings b ON b.worktree_id=r.worktree_id@@ -94,9 +101,10 @@ export async function passBanked(engine: Pick<BrainEngine, 'executeRaw'>, sourceconst rewritten = await engine.executeRaw<{ fingerprint: string; record: GitHoldRecord; revision: string | null }>(`SELECT h.fingerprint, h.completed_keys->0 AS record, p.knowledge_revision::text AS revisionFROM op_checkpoints h LEFT JOIN pages p ON p.source_id=$1 AND p.id=(h.completed_keys->0->>'page_id')::bigintWHERE h.op=$2 AND left(h.fingerprint, length($3))=$3 AND h.completed_keys->0->>'run_id'=$4 AND (h.completed_keys->0->>'updated_at')::timestamptz >= $5::timestamptz- AND NOT (h.completed_keys->0->>'code' = ANY($6::text[])) AND h.completed_keys->0->'meta'->'basis_moved' IS NULL AND h.fingerprint > $7 ORDER BY h.fingerprint LIMIT $8`,+ AND NOT (h.completed_keys->0->>'code' = ANY($6::text[])) AND h.completed_keys->0->'meta'->'basis_moved' IS NULL+ AND h.completed_keys->0->'meta'->'retry_only' IS NULL AND h.fingerprint > $7 ORDER BY h.fingerprint LIMIT $8`,[sourceId, GIT_HOLD_OP, `${sourceId}:${incarnation}:`, telemetry.pass_id, telemetry.started_at, [...EVERY_PASS_RESCREEN_CODES], after, RESCREEN_PAGE]);- if (rewritten.some(({ record, revision }) => !holdRescreenDue(record, false)+ if (rewritten.some(({ record, revision }) => !holdRescreenDue(record, false) && !reachedAttemptCap(record)&& (record.code !== 'file_drift' || record.page_id == null || (record.meta.page_revision ?? null) === revision))) return true;if (rewritten.length < RESCREEN_PAGE) return false;after = rewritten.at(-1)!.fingerprint;diff --git a/src/core/persistence/sync-pass.ts b/src/core/persistence/sync-pass.tsindex 1ab04a4c13..1bc69068d5 100644--- a/src/core/persistence/sync-pass.ts+++ b/src/core/persistence/sync-pass.ts@@ -835,7 +835,7 @@ export async function readShadowLevel(engine: BrainEngine, input: { sourceId: strecord: record ? { blobOids: recordBlobOids, revision: recordRevision != null ? String(recordRevision) : null, parserSame: sameParser(pages.parserOf(at!), fp(path)) } : null,attested, levelSha256: probe?.rawSha256 ?? null,published: !!attested?.hash && probe?.rawSha256 === attested.hash,- hold: hold ? { atLevel: holdAtLevel(hold, level, probe?.rawSha256 ?? null) && !moved.has(path), rescreenDue: holdRescreenDue(hold, retry.has(hold.path)), retried: retry.has(hold.path), ...(unscreenedDrift(hold) ? { unscreened: true } : {}), ...(hold.code === 'file_drift' && fileDriftSide(hold.meta) === 'deleted' ? { deletionSide: true } : {}), ...(moved.has(path) ? { moved: true } : {}) } : null,+ hold: hold ? { atLevel: holdAtLevel(hold, level, probe?.rawSha256 ?? null) && !moved.has(path), rescreenDue: holdRescreenDue(hold, retry.has(hold.path)), retried: retry.has(hold.path), ...(unscreenedDrift(hold) ? { unscreened: true } : {}), ...(hold.code === 'file_drift' && fileDriftSide(hold.meta) === 'deleted' ? { deletionSide: true } : {}), ...(moved.has(path) ? { moved: true } : retry.has(hold.path) && !holdRescreenDue(hold, false) ? { retryOnly: true } : {}) } : null,marker: marker ?? virtualMarker, baseline: needsBaseline ? baselineOf(path) : null,spelling: legacySpelling.has(path) ? 'legacy' : twins.has(path),episodeUnsatisfied: input.pass ? !!input.pass.episodeFullId && live && (record ? pages.fullEpisode[at!] : undefined) !== input.pass.episodeFullIddiff --git a/src/core/persistence/sync-run.ts b/src/core/persistence/sync-run.tsindex da2790ab20..dbe0721d46 100644--- a/src/core/persistence/sync-run.ts+++ b/src/core/persistence/sync-run.ts@@ -581,8 +581,8 @@ async function managedDryRun(engine: BrainEngine, value: Cursor, base: Cursor, rconst holdClear = (cursor: Cursor, path: string | null | undefined, observedAt: string) => path? (tx: BrainEngine) => clearGitHold(tx, { sourceId: cursor.sourceId, incarnation: cursor.incarnation, path, observedAt }) : undefined;/** #5988: the hold write that commits with the cursor step passing a held entry. */-const heldWrite = (held: Cursor, hold: HeldEntry, observedAt: string, entry: { basisMoved?: true } | undefined) => (tx: BrainEngine) => writeGitHold(tx, { source_id: held.sourceId,- incarnation: held.incarnation, ...hold, ...(entry?.basisMoved ? { meta: { ...hold.meta, basis_moved: true as const } } : {}), observed_at: observedAt, run_id: held.runId, mode: 'managed' });+const heldWrite = (held: Cursor, hold: HeldEntry, observedAt: string, entry: { basisMoved?: true; retryOnly?: true } | undefined) => (tx: BrainEngine) => writeGitHold(tx, { source_id: held.sourceId,+ incarnation: held.incarnation, ...hold, meta: { ...hold.meta, ...(entry?.basisMoved ? { basis_moved: true as const } : {}), ...(entry?.retryOnly ? { retry_only: true as const } : {}) }, observed_at: observedAt, run_id: held.runId, mode: 'managed' });/** #6278: the terminal code an owner stamps on a request whose preparation never settled within its attempts (Lane A, consumer.ts). */export const PREPARATION_STALLED = 'preparation_stalled';diff --git a/src/core/repair/file-drift-compare.ts b/src/core/repair/file-drift-compare.tsindex 08ae1b9f7d..9f58b302cc 100644--- a/src/core/repair/file-drift-compare.ts+++ b/src/core/repair/file-drift-compare.ts@@ -79,6 +79,15 @@ export function newerPageParagraph(sourceId: string, slug: string, evidence: Dri+ `To keep the file, preview gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer file. To keep the page, preview it with --prefer database instead (its apply would rewrite the file from the page and needs the user's consent), or carry the edit into the file, commit it and run gbrain sync --source ${sourceId}.`;}+/**+ * GST-2869: what settles a read-only mirror's differing page. Its file-drift previews read every page as database-only and+ * resolve nothing, so naming one would send a caller to an empty preview; they apply once the source is writable again.+ */+export function mirrorDriftRoute(sourceId: string): string {+ return `this source is a read-only mirror, so gbrain repair's file-drift previews read its pages as database-only and resolve nothing; `+ + `the page stays held until the user makes the source writable again (gbrain sources mirror-writable ${sourceId}, which lets gbrain write files into its checkout) and picks a side then`;+}+/** One selected page, compared: a held page by its hold, any other by its slug. Never writes. */export async function comparePage(engine: BrainEngine, sourceId: string, target: { slug: string | null; hold?: GitHoldRecord; mirror?: boolean }, assessmentAt: string): Promise<ComparedPage> {const { slug, hold } = target;@@ -112,8 +121,10 @@ export async function comparePage(engine: BrainEngine, sourceId: string, target:const { path, ...evidence } = read;const base = { item, slug, ...held, path, evidence };if (evidence.differs === 'none') return { ...base, would: hold ? 'release_hold' : 'no_drift', why: 'nothing differs once gbrain\'s own normalisation is read' };- if (evidence.newer === 'file') return { ...base, would: 'prefer_file', why: `${path} was committed after the page last changed, so the file wins (Git is the parent): gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer file` };- if (evidence.newer === 'database') return { ...base, would: 'needs_human', why: newerPageParagraph(sourceId, slug, { path, ...evidence }) };+ if (evidence.newer === 'file') return { ...base, would: 'prefer_file', why: mirrorHeld ? `${path} was committed after the page last changed, so the file wins (Git is the parent), but ${mirrorDriftRoute(sourceId)}`+ : `${path} was committed after the page last changed, so the file wins (Git is the parent): gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer file` };+ if (evidence.newer === 'database') return { ...base, would: 'needs_human', why: mirrorHeld ? `page ${slug} changed after ${path} was last committed (page updated ${evidence.page_updated_at}, file committed ${evidence.file_committed_at}), so a person decides which side to keep; ${mirrorDriftRoute(sourceId)}`+ : newerPageParagraph(sourceId, slug, { path, ...evidence }) };return { ...base, would: 'needs_human', why: evidence.file_uncommitted ? `${path} has uncommitted bytes, so which side is newer is unknown; commit or restore the file, then compare again`: `which side is newer is unknown (${evidence.file_committed_at ? 'the page has no update time' : `no commit holds ${path}`}); a person decides` };} catch (error) {diff --git a/src/core/repair/file-drift.ts b/src/core/repair/file-drift.tsindex e904190e65..9a2e98f4de 100644--- a/src/core/repair/file-drift.ts+++ b/src/core/repair/file-drift.ts@@ -98,7 +98,7 @@ import { discardedFilePaths, unimportedFile, unimportedFileText, type Unimportedimport { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';import { recordsNoFileOrigin } from '../persistence/unbound-pages.ts';import { sourceMirrorReadOnly } from '../persistence/mirror-read-only.ts';-import { comparedListing, comparePage, linesNotCarried, newerPageParagraph, readDriftEvidence, type ComparedPage } from './file-drift-compare.ts';+import { comparedListing, comparePage, linesNotCarried, mirrorDriftRoute, newerPageParagraph, readDriftEvidence, type ComparedPage } from './file-drift-compare.ts';import { serializePageToMarkdown } from '../markdown.ts';import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairPlanOptions, type RepairScope } from './core.ts';@@ -816,7 +816,8 @@ async function compareSelection(engine: BrainEngine, sourceId: string, opts: Repconst nextCursor = remaining > 0 && windowed > 0 ? heldCursor(held!.targets[windowed - 1]!.hold.path) : undefined;if (remaining > 0) residuals.after_window = remaining;const filesNewer = pages.filter(page => page.would === 'prefer_file').length;- const next = [...(filesNewer ? [`Preview the file side for the ${filesNewer} page(s) whose file is newer: ${previewCommand(sourceId, { ...opts, prefer: 'file' })} (pages newer than their file are left held, kept_newer_page)`] : []),+ const next = [...(filesNewer ? [mirror ? `${filesNewer} page(s) have a newer file, but ${mirrorDriftRoute(sourceId)}`+ : `Preview the file side for the ${filesNewer} page(s) whose file is newer: ${previewCommand(sourceId, { ...opts, prefer: 'file' })} (pages newer than their file are left held, kept_newer_page)`] : []),...(nextCursor ? [`Compare the next window: ${shellQuote(compareArgv(sourceId, { ...opts, cursor: nextCursor }).slice(0, -1))}`] : [])];return { items: [], residuals, listing, ...(held ? { complete: remaining === 0 } : {}), details: { compare: true, writes: 'none',pages: pages.map(({ item: _item, ...page }) => ({ evidence: null, ...page })), ...(next.length ? { next_actions: next } : {}),diff --git a/test/sync-mirror-parked-gst2843.test.ts b/test/sync-mirror-parked-gst2843.test.tsindex e6b9b750bd..d7ac531b51 100644--- a/test/sync-mirror-parked-gst2843.test.ts+++ b/test/sync-mirror-parked-gst2843.test.ts@@ -8,6 +8,8 @@* and only a file that is gone reads no_drift / database_only. It still writes nothing, and sync holds the same paths.* - The held comparison is not complete while held pages remain past its window.* - sources status counts every hold per code, not only the listed ones.+ * GST-2869: on a mirror the comparison names no file-drift preview (each reads the page as database-only) but the writable+ * route; a re-hold that a requested retry alone caused, or that brought a transient hold to its attempt cap, is not saved work.* PGLite always; Postgres when DATABASE_URL is set (managedBrain). Synthetic content only.*/import { describe, expect, setSystemTime, spyOn, test } from 'bun:test';@@ -24,7 +26,9 @@ import { installFaultHook } from '../src/core/persistence/fault-points.ts';import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';import { PASS_BATCH_KEY_PREFIX, readPassBatch } from '../src/core/persistence/sync-pass-batch.ts';import { registerLocalWriter, withVerifiedLocalRegistration } from '../src/core/persistence/identity.ts';-import { FILE_DRIFT_VERSION, writeGitHold } from '../src/core/persistence/sync-holds.ts';+import { FILE_DRIFT_VERSION, requestGitHoldRetry, writeGitHold } from '../src/core/persistence/sync-holds.ts';+import { HOLD_ATTEMPTS_NEEDS_HUMAN } from '../src/core/persistence/sync-fault-class.ts';+import { VERSION } from '../src/version.ts';import { readPassRow } from '../src/core/persistence/sync-pass-row.ts';import { passBanked } from '../src/core/persistence/sync-pass-status.ts';import { performManagedSync } from '../src/core/persistence/sync-run.ts';@@ -211,6 +215,54 @@ describe.each(testBackends())('GST-2843: the held comparison on a read-only mirrexpect(await revisions()).toBe(pages);expect(git(root, 'status', '--porcelain')).toBe('');}, { databaseUrl, setup: heldSetup }), 240_000);++ test('GST-2869: on a mirror the comparison names no file-drift preview, and the route it names resolves the page once the source is writable', () => managedBrain(async ({ engine, root }) => {+ await heldPages(engine, root);+ const compared = await repair(engine, { held: true }) as Plan;+ const why = Object.fromEntries((compared.details!.pages as Array<{ slug: string; would: string; why: string }>).map(page => [page.slug, page.why]));+ for (const slug of ['notes/newer-file', 'notes/newer-page']) {+ expect(why[slug]).not.toContain('gbrain repair file-drift');+ expect(why[slug]).toContain('gbrain sources mirror-writable default');+ }+ const next = (compared.details!.next_actions ?? []) as string[];+ expect(next.join('\n')).not.toContain('--prefer file');+ expect(next.join('\n')).toContain('gbrain sources mirror-writable default');+ await engine.executeRaw(`UPDATE sources SET config = config || '{"mirror_read_only": false}'::jsonb WHERE id='default'`);+ expect(classes(await repair(engine, { slugs: ['notes/newer-file'], prefer: 'file' }))).toEqual({ 'notes/newer-file': 'prefer_file' });+ }, { databaseUrl, setup: heldSetup }), 240_000);+});++describe.each(testBackends())('GST-2869: a re-hold that settled nothing is not saved work (%s)', backend => {+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;+ test('a stopped pass that re-checked a hold only because a retry was requested, and held it again, does not count as progress', () => managedBrain(async ({ engine, root }) => {+ expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');+ files(root, { 'notes/broken': '---\ntype: concept\ntitle: [unclosed\n---\n\nBody.\n' });+ commitAll(root, 'a file sync cannot import');+ await performManagedSync(engine, OPTS);+ const held = (await holdRows(engine)).find(h => h.path === 'notes/broken.md')!;+ expect(held).toBeDefined();+ const inc = await incarnation(engine);+ await requestGitHoldRetry(engine, 'default', inc, ['notes/broken.md']);+ await stoppedSync(engine, 0);+ const telemetry = (await readPassRow(engine, 'default', inc))!.value.telemetry;+ const again = (await holdRows(engine)).find(h => h.path === 'notes/broken.md')!;+ expect([again.code, again.meta.attempts, again.meta.retry_only]).toEqual([held.code, 2, true]);+ expect(await passBanked(engine, 'default', inc, telemetry)).toBe(false);+ }, { databaseUrl, setup: notes(1) }), 240_000);++ test('a re-hold that brought a transient hold to its attempt cap does not count as progress', () => managedBrain(async ({ engine }) => {+ const inc = await incarnation(engine);+ const before = '2026-01-01T00:00:00.000Z', started = '2026-01-02T00:00:00.000Z', during = '2026-01-02T00:05:00.000Z';+ const hold = (path: string, attempts: number) => [`default:${inc}:${path}`, JSON.stringify([{ version: 1, source_id: 'default', incarnation: inc, path, source_path: path, slug: null,+ page_id: null, code: 'preparation_stalled', message: 'synthetic', upstream_version: null, observed_at: during, held_at: before, updated_at: during, run_id: 'pass-1', mode: 'managed',+ meta: { recovery_version: RECOVERY_VERSION, attempts, stall: { request_id: 'r', step: null, attempts: 1, gbrain_version: VERSION } } }])];+ const insert = (rows: string[][]) => coordinated(engine, "INSERT INTO op_checkpoints(op,fingerprint,completed_keys) SELECT 'sync-hold', f, k::jsonb FROM unnest($1::text[], $2::text[]) AS t(f, k)",+ [rows.map(([fingerprint]) => fingerprint), rows.map(([, keys]) => keys)]);+ await insert([hold('a/capped.md', HOLD_ATTEMPTS_NEEDS_HUMAN)]);+ expect(await passBanked(engine, 'default', inc, { pass_id: 'pass-1', started_at: started })).toBe(false);+ await insert([hold('b/past-cap.md', HOLD_ATTEMPTS_NEEDS_HUMAN + 1)]);+ expect(await passBanked(engine, 'default', inc, { pass_id: 'pass-1', started_at: started })).toBe(true);+ }, { databaseUrl }), 120_000);});describe.each(testBackends())('GST-2843: counts past a window or a listing limit (%s)', backend => {