Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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 its
gbrain 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 in
bulk. 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 remote
database takes minutes per hundred pages). It reports each page on stderr as
it goes. The hash and the printed apply command cover only that window. A
partial 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:
```bash
gbrain repair file-drift --source <id> --held --side deleted --state file_gone --prefer database # window 1
diff --git a/docs/guides/sync-unblock-runbook.md b/docs/guides/sync-unblock-runbook.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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<P
await 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.ts
index 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: Sh
if (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.ts
index 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'>, i
duration_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'>, source
const 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 revision
FROM op_checkpoints h LEFT JOIN pages p ON p.source_id=$1 AND p.id=(h.completed_keys->0->>'page_id')::bigint
WHERE 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.ts
index 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: st
record: 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.episodeFullId
diff --git a/src/core/persistence/sync-run.ts b/src/core/persistence/sync-run.ts
index 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, r
const 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.ts
index 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.ts
index 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 Unimported
import { 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: Rep
const 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.ts
index 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 mirr
expect(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 => {