Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytand9e4a027fcb5
diff --git a/docs/designs/REFRESH_WRITE_BARRIER.md b/docs/designs/REFRESH_WRITE_BARRIER.md
index b51e740116..08a3bfe35f 100644
--- a/docs/designs/REFRESH_WRITE_BARRIER.md
+++ b/docs/designs/REFRESH_WRITE_BARRIER.md
@@ -214,15 +214,18 @@ after the held-at commit that touched the file), a `gbrain-supersedes: <path>: r
door commits). The replaced revision stays in `page_versions` and the imported commit stays in
Git, an ancestor of the write's commit.
-**Age bound and schema.** A row held for an import that has not landed past
-`persistence.refresh_barrier_max_wait_ms` ends `failed` with `pending_import_expired` in the owner's
-housekeeping turn, which rechecks under the request lock that the row is still unclaimed and its
-import still pending. Migration v294 adds the nullable `persistence_requests.deferred_import_from` and
+**Age bound and schema.** A row held for an import that has not landed within
+`persistence.refresh_barrier_max_wait_ms` of its hold (measured from the hold, not from admission) ends
+`failed` with `pending_import_expired` in the owner's housekeeping turn, which rechecks under the
+request lock that the row is still unclaimed and its import still pending. A `remember` ends as its
+`pending_import` refusal did instead (conflict `source_changed`, origin `pending_import`), so the
+first sync that imports the file replays the fact. Migration v294 adds the nullable `persistence_requests.deferred_import_from` and
widens `gbrain_guard_deferred_request`: a running row may move to `deferred` only under the barrier's
session declaration and only naming the import it waits for, and a deferred row moves to `running`
-only once every hold it names is released. Only the write owner's consumer, already a barrier
-consumer, holds a row for an import; a mixed-version window on one owner host is the
-consumer-capability gap #8688 tracks.
+only once every hold it names is released. Only the write owner's consumer holds a row for an
+import, and only when every live consumer of the owner host advertises `refresh_barrier_import_1`
+(a barrier consumer from before v294 would stall on the held row); otherwise the write keeps the
+`pending_import` refusal.
### Idempotency
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 7335b82927..a7251a8bb3 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -3440,7 +3440,7 @@ More: [docs/guides/dream-patterns.md#cadence](../../docs/guides/dream-patterns.m
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit. | With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. | Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id. | provider | `repeat the read that failed` | 1 | no |
+| A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit. | With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once it has been held for persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. A remember ends as its pending_import refusal did instead, and is replayed after the import. | Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id. | provider | `repeat the read that failed` | 1 | no |
More: [docs/guides/write-refusals.md#pending_import_expired](../../docs/guides/write-refusals.md#pending_import_expired)
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 2d39908f24..78fa50f74e 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -625,9 +625,12 @@ syncing it is accepted and waits for the refresh instead of being refused `workt
import moved the page; a blind (`force`) `put_page` lands, and its receipt (`supersedes`), its
commit trailer (`gbrain-supersedes: <path>: revision <id> from <commit>`) and the commit ledger
name the imported revision and commit it replaced, both still in page history and Git. A write
- whose import has not landed after the wait limit ends `failed` with `pending_import_expired`,
+ whose import has not landed within the wait limit of its hold ends `failed` with `pending_import_expired`,
nothing applied: check `gbrain sync status --source <source> --json`, then read the page again and
- submit with a new request ID.
+ submit with a new request ID. A `remember` ends as the [`pending_import`](#pending_import) refusal
+ did instead: the fact is kept, the first sync that imports the file replays it, and the caller does
+ not save it again. A write keeps the refusal when a live consumer on the owner host runs a release
+ that cannot claim a held write.
- Still refused as before: batches (`put_pages`, `remember` with `items`), jobs, skill bundles,
and any brain where a live consumer on the owner host runs a release without the barrier.
Repo-less brains and database-only sources never wait.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 51744fc0dd..fd681753dc 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1465,7 +1465,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.594.0', id: 'doctor_foreign_writers_prb', text: 'New doctor check `foreign_writers`: in every source checkout on this host, managed worktrees included, a commit gbrain\'s commit ledger does not name fails the check with the newest such commit and a fix that asks who makes it; an unconfirmed commit (a crash between `git commit` and the ledger line) and page files left uncommitted for over 30 minutes warn. Commits before the ledger started are reported as uncovered, not foreign. A repo-less brain reports not_applicable.' },
{ since: '0.60.594.0', id: 'sources_guard_prb', text: 'New `gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]`: the commit guard on a managed source\'s worktree, from its owner host only, installed in a hooks directory private to that worktree. `--mode enforce` also refuses cherry-pick, revert, rebase and sequencer commits. `gbrain git guard` is unchanged.' },
{ since: '0.60.594.0', id: 'refresh_barrier_prb', text: 'New setting `persistence.refresh_barrier` (off by default): with it on, a single page write (`put_page`, `remember` and the other single-page verbs) that reaches a checkout while `gbrain sources refresh` drains or merges it is journaled and answered `pending` at once (MCP `isError: false`, CLI exit 10) instead of refused `worktree_refreshing`. It commits after the refresh, or ends `revision_conflict` when the refresh changed its file, or `refresh_barrier_expired` after `persistence.refresh_barrier_max_wait_ms` (15 minutes). Syncs, jobs and batches keep the refusal. `gbrain upgrade --check-downgrade` exits 3 `downgrade_blocked_deferred_writes` while such writes wait.' },
- { since: 'TBD', id: 'refresh_barrier_import_gst1582', text: 'With `persistence.refresh_barrier` on, no page write bounces because a sync is running: a `put_page`, `capture`, `remember` or `add_timeline_entry` whose page file holds a committed change managed sync has not imported yet is answered `pending` (receipt `deferred: { pending_import: true }`) instead of refused `pending_import`, and is prepared again once the import lands (a `put_page` with `expected_revision` then ends `revision_conflict` if the import moved the page; a blind one lands and names the revision and commit it replaced in `supersedes`, a `gbrain-supersedes:` commit trailer and the commit ledger), or ends `pending_import_expired` after the wait limit. A write during a refresh in `recovery_required` waits too, and `persistence.refresh_barrier_max_deferred` is no longer read: no write past it is refused. With the barrier off those refusals are unchanged. Wherever `worktree_refreshing` still refuses, `retry_after_ms` is estimated from the refresh (its typical duration minus how long it has run, at least 15 s while syncing and 2 s otherwise) instead of a fixed 1000, the message says the write was not saved and when to retry, and the CLI\'s human output ends with one line saying the same.' },
+ { since: 'TBD', id: 'refresh_barrier_import_gst1582', text: 'With `persistence.refresh_barrier` on, no page write bounces because a sync is running: a `put_page`, `capture`, `remember` or `add_timeline_entry` whose page file holds a committed change managed sync has not imported yet is answered `pending` (receipt `deferred: { pending_import: true }`) instead of refused `pending_import`, and is prepared again once the import lands (a `put_page` with `expected_revision` then ends `revision_conflict` if the import moved the page; a blind one lands and names the revision and commit it replaced in `supersedes`, a `gbrain-supersedes:` commit trailer and the commit ledger), or ends `pending_import_expired` once held past the wait limit (a `remember` ends as its `pending_import` refusal did and is replayed after the import). A write during a refresh in `recovery_required` waits too, and `persistence.refresh_barrier_max_deferred` is no longer read: no write past it is refused. With the barrier off those refusals are unchanged. Wherever `worktree_refreshing` still refuses, `retry_after_ms` is estimated from the refresh (its typical duration minus how long it has run, at least 15 s while syncing and 2 s otherwise) instead of a fixed 1000, the message says the write was not saved and when to retry, and the CLI\'s human output ends with one line saying the same.' },
{ since: '0.60.594.0', id: 'commit_push_base_prb', text: '`gbrain git commit-push` takes `--base <path>=<blob>|absent` (repeatable, each path one the command commits): it refuses `commit_base_moved`, committing nothing, when the file at HEAD is no longer the blob the caller read. Without `--base` nothing changes.' },
{ since: '0.60.594.0', id: 'file_drift_held_needs_prefer_8615', text: '`gbrain repair file-drift` with `--held`, `--side`, `--state`, `--cursor` or `--provenance` and no `--prefer` now refuses with the usage line (`invalid_params`, and `file_drift_state_required` for a deleted side without `--state`) instead of silently running the all-drifted survey, which counted a different set of pages (#8615).' },
{ since: '0.60.594.0', id: 'refresh_source_changed_retry_8617', text: 'A `gbrain sources refresh` run refused `refresh_source_changed` because the checkout HEAD moved (a writer committing) or work reached the checkout after the drain check now retries once from a fresh precheck in the same run, so the tick is not lost (#8617). When the retry is refused too, the run returns the first `refresh_source_changed` refusal with the retry\'s cause appended; ownership or source-membership changes are not retried.' },
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 2c84f5e4df..a6fd379cb2 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -665,7 +665,7 @@ export const CODES = {
refresh_no_upstream: { class: 'caller', summary: "The worktree has no upstream to refresh from." },
refresh_not_managed: { class: 'host_only', summary: "The source is not managed, so it cannot be refreshed." },
refresh_not_owner: { class: 'host_only', summary: "This process does not own the worktree it would refresh." },
- pending_import_expired: { class: 'caller', actor: 'provider', summary: "A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit.", why: "With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied.", docs: 'docs/guides/write-refusals.md#pending_import_expired', suggestion: 'Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id.' },
+ pending_import_expired: { class: 'caller', actor: 'provider', summary: "A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit.", why: "With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once it has been held for persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied. A remember ends as its pending_import refusal did instead, and is replayed after the import.", docs: 'docs/guides/write-refusals.md#pending_import_expired', suggestion: 'Check the source with gbrain sync status --source <id> --json, then read the page again and submit the write with a new request_id.' },
refresh_barrier_expired: { class: 'caller', actor: 'provider', summary: "A write that waited behind a worktree refresh was not applied, because the refresh was still unfinished after the barrier's wait limit.", why: "With persistence.refresh_barrier on, a page write that reaches a refreshing checkout is accepted and waits for the refresh to end. A refresh that never ends (a stuck member sync, a host that stopped) would hold those writes forever, so the owner finishes each one failed after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied.", docs: 'docs/guides/write-refusals.md#deferred-writes', suggestion: 'Check the refresh with gbrain sources writer status --source <id> --json, then submit the write again with a new request_id.' },
refresh_source_changed: { class: 'caller', summary: "The source changed during the refresh." },
refresh_sync_timeout: { class: 'retryable', summary: "A refresh's member sync committed nothing within the refresh sync budget." },
diff --git a/src/core/persistence/consumer-heartbeat.ts b/src/core/persistence/consumer-heartbeat.ts
index d6bf7fd479..4129561173 100644
--- a/src/core/persistence/consumer-heartbeat.ts
+++ b/src/core/persistence/consumer-heartbeat.ts
@@ -213,8 +213,11 @@ export interface ConsumerHeartbeat {
}
type DirectEngine = SqlEngine & Partial<Pick<BrainEngine, 'kind' | 'executeRawDirect'>>;
-/** What this binary's consumer can drain (v292): `refresh_barrier_1` claims writes deferred behind a worktree refresh. */
-export const CONSUMER_CAPABILITIES = ['refresh_barrier_1'] as const;
+/**
+ * What this binary's consumer can drain: `refresh_barrier_1` (v292) claims writes deferred behind a worktree refresh,
+ * `refresh_barrier_import_1` (v294) writes held for an import.
+ */
+export const CONSUMER_CAPABILITIES = ['refresh_barrier_1', 'refresh_barrier_import_1'] as const;
const RENEW_SQL = `WITH purged AS (
DELETE FROM persistence_consumers WHERE host_id=$1::uuid AND renewed_at < now() - ($14::integer * interval '1 millisecond') AND NOT (pid=$2::integer AND nonce=$3))
INSERT INTO persistence_consumers(host_id,pid,nonce,pid_ns,kind,mode,restart_required,root_barrier_age_ms,pool,host_json_path,persistence_home,minted_under,version,boot_id,process_start,segment_reader,capabilities)
diff --git a/src/core/persistence/import-deferral.ts b/src/core/persistence/import-deferral.ts
index d8a38f2c56..831909e889 100644
--- a/src/core/persistence/import-deferral.ts
+++ b/src/core/persistence/import-deferral.ts
@@ -12,7 +12,7 @@
import { relative, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { PreparedMutation } from './coordinator.ts';
-import { publicationGroupKey, REFRESH_BARRIER_CLAIM_PREDICATE } from './journal.ts';
+import { deferralRoom, IMPORT_HOLD_CAPABILITY, publicationGroupKey, REFRESH_BARRIER_CLAIM_PREDICATE } from './journal.ts';
import type { WriteRequest } from './model.ts';
import { landedCommit } from './pending-import.ts';
import { PERSISTENCE_PROTOCOL_PREDICATE } from './protocol.ts';
@@ -23,12 +23,14 @@ export const SUPERSEDES_TRAILER_KEY = 'gbrain-supersedes';
/**
* A claimed write whose preparation was refused `pending_import` (`importFrom`: the last imported commit the check saw),
- * moved back to `deferred` behind that import; null when it keeps the refusal (barrier off, another operation, a batch).
+ * moved back to `deferred` behind that import; null when it keeps the refusal (barrier off, another operation, a batch, a
+ * live consumer on the owner host that cannot claim a held write).
*/
export async function holdForImport(engine: BrainEngine, row: WriteRequest, error: unknown): Promise<WriteRequest | null> {
const from = (error as { importFrom?: unknown } | null)?.importFrom;
if (typeof from !== 'string' || !IMPORT_HELD_OPERATIONS.includes(row.operation) || (row.target_kind ?? 'page') !== 'page' || !row.worktree_id
- || publicationGroupKey(row) !== null || !await writeSwitchOn(engine, 'refresh_barrier').catch(() => false)) return null;
+ || publicationGroupKey(row) !== null || !await writeSwitchOn(engine, 'refresh_barrier').catch(() => false)
+ || !await deferralRoom(engine, row.worktree_id, IMPORT_HOLD_CAPABILITY)) return null;
const [held] = await engine.executeRaw<WriteRequest>(`UPDATE persistence_requests SET state='deferred',deferred_import_from=$3,execution_token=NULL,
claim_expires_at=NULL,blocked_reason=NULL,claim_phase=NULL,updated_at=now()
WHERE id=$1::uuid AND execution_token=$2::uuid AND state='running' AND recovery IS NULL AND publication_started=false
diff --git a/src/core/persistence/journal.ts b/src/core/persistence/journal.ts
index d9cc4fb64a..d0ad2c6878 100644
--- a/src/core/persistence/journal.ts
+++ b/src/core/persistence/journal.ts
@@ -620,6 +620,8 @@ async function assertWorktreeAdmission(tx: BrainEngine, input: WriteAdmission, r
/** What a consumer advertises (consumer-heartbeat.ts CONSUMER_CAPABILITIES) and admission requires of every live one on the owner host. */
export const REFRESH_BARRIER_CAPABILITY = 'refresh_barrier_1';
+/** GST-1582: a consumer that claims a write held for an import (`deferred_import_from`); an older one would stall on it. */
+export const IMPORT_HOLD_CAPABILITY = 'refresh_barrier_import_1';
/** A single page write whose caller opted in may wait behind a refresh; jobs (managed sync included), grouped batches and skill bundles keep the refusal. */
function deferrable(input: WriteAdmission): boolean {
return input.deferrable === true && (input.targetKind ?? 'page') === 'page' && input.operation !== 'submit_job' && publicationGroupKey({ operation: input.operation, intent: input.intent }) === null;
@@ -632,11 +634,11 @@ async function readRefreshBarrier(engine: BrainEngine): Promise<boolean> {
* Every live consumer of the worktree's owner host can drain a deferred write. GST-1582: there is no per-refresh cap; the
* journal's outstanding and byte limits bound deferred writes like queued ones.
*/
-async function deferralRoom(tx: BrainEngine, worktreeId: string): Promise<boolean> {
+export async function deferralRoom(tx: SqlEngine, worktreeId: string, capability: string = REFRESH_BARRIER_CAPABILITY): Promise<boolean> {
const [row] = await tx.executeRaw<{ incapable: boolean }>(`SELECT
EXISTS (SELECT 1 FROM persistence_consumers c JOIN persistence_worktrees w ON w.owner_host_id=c.host_id WHERE w.id=$1::uuid
AND c.renewed_at>now()-($2::integer*interval '1 millisecond') AND NOT ($3=ANY(c.capabilities))) AS incapable`,
- [worktreeId, CONSUMER_LIVE_MS, REFRESH_BARRIER_CAPABILITY]);
+ [worktreeId, CONSUMER_LIVE_MS, capability]);
return !!row && !row.incapable;
}
/** The refresh to defer this write behind, or null when it is admitted normally; otherwise refuses. */
diff --git a/src/core/persistence/refresh-barrier.ts b/src/core/persistence/refresh-barrier.ts
index f310c33711..3e32222c3c 100644
--- a/src/core/persistence/refresh-barrier.ts
+++ b/src/core/persistence/refresh-barrier.ts
@@ -15,6 +15,7 @@ import { OperationError } from '../ops/contract.ts';
import { authorizeWrite } from './authority.ts';
import type { BrainEngine } from '../engine.ts';
import { completeWrite } from './journal.ts';
+import { PENDING_IMPORT } from './pending-import.ts';
import { declarePersistenceProtocol } from './protocol.ts';
import type { SqlEngine, WriteRequest } from './model.ts';
@@ -87,10 +88,12 @@ export const overdueDeferredWorkSql = (host: string) => `EXISTS (SELECT 1 FROM p
* brain row FOR SHARE) before it locks the refresh row, the order fenceAndMerge takes them in (brain FOR UPDATE, then the
* refresh), so an expiry overlapping a fence waits instead of deadlocking; with the refresh row locked, an expiry and
* the release that would make the row claimable never both win.
- * GST-1582: one held for an import that has not landed past the limit ends `pending_import_expired` the same way; its
- * claim and its expiry both move the row, so the expiry checks the row is still unclaimed and its import still pending
- * with the sources row locked FOR SHARE (after the protocol's brain lock, the order a fence takes them in), so an import
- * that is landing makes the check wait and then see it landed.
+ * GST-1582: one held for an import that has not landed within the limit of its hold ends `pending_import_expired` the
+ * same way, except a `remember`, which ends as its `pending_import` refusal did (conflict `source_changed`, origin
+ * `pending_import`), so the first sync that imports the file replays the fact. Its claim and its expiry both move the row,
+ * so the expiry checks the row is still unclaimed and its import still pending with the sources row locked FOR SHARE
+ * (after the protocol's brain lock, the order a fence takes them in), so an import that is landing makes the check wait
+ * and then see it landed.
*/
export async function expireDeferredWrites(engine: BrainEngine, hostId: string, signal?: AbortSignal): Promise<WriteRequest[]> {
const [config] = await engine.executeRaw<{ ms: number }>(`SELECT ${MAX_WAIT_SQL} AS ms`, undefined, { signal });
@@ -112,13 +115,15 @@ export async function expireDeferredWrites(engine: BrainEngine, hostId: string,
JOIN persistence_worktrees w ON w.id=r.worktree_id JOIN sources s ON s.id=r.source_id
WHERE w.owner_host_id=$1::uuid AND r.state='deferred' AND r.deferred_import_from IS NOT NULL AND COALESCE(s.last_commit,'')=r.deferred_import_from
AND (r.deferred_refresh_id IS NULL OR EXISTS (SELECT 1 FROM persistence_worktree_refreshes f WHERE f.id=r.deferred_refresh_id AND f.released_at IS NOT NULL))
- AND r.created_at<now()-($2::double precision*interval '1 millisecond') ORDER BY r.sequence LIMIT 100`, [hostId, maxWaitMs], { signal });
+ AND r.updated_at<now()-($2::double precision*interval '1 millisecond') ORDER BY r.sequence LIMIT 100`, [hostId, maxWaitMs], { signal });
for (const row of imports) {
const done = await engine.transaction(async tx => {
await declarePersistenceProtocol(tx);
const [held] = await tx.executeRaw(`SELECT 1 FROM persistence_requests r JOIN sources s ON s.id=r.source_id
WHERE r.id=$1::uuid AND r.state='deferred' AND COALESCE(s.last_commit,'')=r.deferred_import_from FOR SHARE OF s`, [row.id]);
if (!held) return null;
+ if (row.operation === 'remember') return completeWrite(tx, row, 'conflict', {}, { code: 'source_changed', detail: { origin: PENDING_IMPORT },
+ message: `Request ${row.request_id} waited more than ${Math.round(maxWaitMs / 1000)} s for managed sync to import a committed change to the file of ${row.slug}, and the import has not landed, so the fact is not saved yet. It is kept: the first managed sync that imports the file replays it once. Do not save it again; check the source with gbrain sync status --source ${row.source_id} --json.` });
return completeWrite(tx, row, 'failed', {}, { code: 'pending_import_expired',
message: `Request ${row.request_id} waited more than ${Math.round(maxWaitMs / 1000)} s for managed sync to import a committed change to the file of ${row.slug}, and the import has not landed, so nothing was applied. Check the source with gbrain sync status --source ${row.source_id} --json, then submit the write again with a new request_id.` });
}).catch(error => { if ((error as { code?: string })?.code === 'write_claim_lost') return null; throw error; });
diff --git a/src/core/persistence/refresh-retry-hint.ts b/src/core/persistence/refresh-retry-hint.ts
index 885d9c41fa..9cadf66c17 100644
--- a/src/core/persistence/refresh-retry-hint.ts
+++ b/src/core/persistence/refresh-retry-hint.ts
@@ -3,7 +3,8 @@
* retry, from the refresh's actual state instead of a fixed second. A refresh tick takes minutes, so a fixed 1 s hint
* sent an obedient caller back into the same tick to be refused again. The estimate is the median duration of the
* worktree's last completed refreshes minus how long this one has run, never below its phase's floor: a refresh with no
- * history, or already past its typical duration, is retried in floor-sized steps.
+ * history, or already past its typical duration, is retried in floor-sized steps. A refresh that stopped in
+ * recovery_required (its outcome keeps the refusal) is left out, since its duration includes the wait for an operator.
*/
import type { SqlEngine } from './model.ts';
@@ -17,7 +18,7 @@ export async function refreshRetryHint(engine: SqlEngine, refresh: { id: string;
const [row] = await engine.executeRaw<{ elapsed_ms: number | string | null; typical_ms: number | string | null }>(`SELECT
(EXTRACT(EPOCH FROM now()-f.created_at)*1000)::bigint AS elapsed_ms,
(SELECT (percentile_cont(0.5) WITHIN GROUP (ORDER BY d.ms))::bigint FROM (SELECT EXTRACT(EPOCH FROM p.completed_at-p.created_at)*1000 AS ms
- FROM persistence_worktree_refreshes p WHERE p.worktree_id=f.worktree_id AND p.state='completed' AND p.completed_at IS NOT NULL
+ FROM persistence_worktree_refreshes p WHERE p.worktree_id=f.worktree_id AND p.state='completed' AND p.completed_at IS NOT NULL AND p.outcome->'refusal' IS NULL
ORDER BY p.completed_at DESC LIMIT ${HISTORY}) d) AS typical_ms
FROM persistence_worktree_refreshes f WHERE f.id=$1::uuid`, [refresh.id]).catch(() => []);
const elapsedMs = row?.elapsed_ms == null ? null : Number(row.elapsed_ms);
diff --git a/test/import-write-barrier.test.ts b/test/import-write-barrier.test.ts
index eaa780f917..f1520304cc 100644
--- a/test/import-write-barrier.test.ts
+++ b/test/import-write-barrier.test.ts
@@ -31,6 +31,7 @@ import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import { refreshWorktree, resumeWorktreeRefreshes } from '../src/core/persistence/worktree-refresh.ts';
import { readLedger } from '../src/core/git/commit-ledger.ts';
import type { WriteRequest } from '../src/core/persistence/model.ts';
+import { replayImportedRemembers } from '../src/core/repair/failed-writes.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
@@ -204,6 +205,66 @@ test('a held write whose import never lands ends pending_import_expired with not
expect(file(f, 'one.md')).toContain(IMPORTED);
}), 180_000);
+const maxWait = (f: RefreshFixture, ms: number) => f.engine.executeRaw(`INSERT INTO config(key,value) VALUES('persistence.refresh_barrier_max_wait_ms',$1)
+ ON CONFLICT (key) DO UPDATE SET value=EXCLUDED.value`, [String(ms)]);
+const ownerHost = async (f: RefreshFixture) => (await f.engine.executeRaw<{ owner: string }>('SELECT owner_host_id::text AS owner FROM persistence_worktrees WHERE id=$1::uuid', [f.worktreeId]))[0]!.owner;
+
+test('a held remember whose import has not landed in time is kept for the replay after the import, never dropped', () => each(async f => {
+ foreignCommit(f, 'people/alice-example.md', PERSON);
+ await importNow(f);
+ foreignCommit(f, 'people/alice-example.md', PERSON.replace('Alice is a person.', `Alice is a person. ${IMPORTED}`));
+ const out = await call(f, 'remember', { fact: 'alice-example likes tea', entity: 'people/alice-example', provenance: 'test' });
+ const held = await requestRow(f, out.body.request_id);
+ expect(held.state).toBe('deferred');
+ await maxWait(f, 1);
+ try {
+ await new Promise(resolve => setTimeout(resolve, 20));
+ expect((await expireDeferredWrites(f.engine, await ownerHost(f))).map(row => row.id)).toEqual([held.id]);
+ } finally {
+ await f.engine.executeRaw("DELETE FROM config WHERE key='persistence.refresh_barrier_max_wait_ms'");
+ }
+ const expired = (await getWriteRequestById(f.engine, held.id))!;
+ expect(expired).toMatchObject({ state: 'conflict', error_code: 'source_changed' });
+ expect((expired.error_detail as { origin?: string }).origin).toBe('pending_import');
+ expect(expired.error_message).toContain('Do not save it again');
+ await importNow(f);
+ expect(await replayImportedRemembers(f.ctx(f.alpha), f.alpha)).toMatchObject({ replayed: 1 });
+ expect(file(f, 'people/alice-example.md')).toContain('alice-example likes tea');
+}), 180_000);
+
+test("a held write's wait limit counts from when it was held, not from its admission", () => each(async f => {
+ foreignCommit(f, 'one.md', page('Alpha one', IMPORTED));
+ const out = await local(f, 'put_page', { slug: 'one', content: page('Alpha one', 'Held, admitted long ago.') });
+ const held = await requestRow(f, out.receipt.request_id);
+ expect(held.state).toBe('deferred');
+ await f.engine.executeRaw("UPDATE persistence_requests SET created_at=now()-interval '2 hours' WHERE id=$1::uuid", [held.id]);
+ await maxWait(f, 60_000);
+ try {
+ expect(await expireDeferredWrites(f.engine, await ownerHost(f))).toEqual([]);
+ expect((await getWriteRequestById(f.engine, held.id))!.state).toBe('deferred');
+ await f.engine.executeRaw("UPDATE persistence_requests SET updated_at=now()-interval '2 hours' WHERE id=$1::uuid", [held.id]);
+ expect((await expireDeferredWrites(f.engine, await ownerHost(f))).map(row => row.id)).toEqual([held.id]);
+ } finally {
+ await f.engine.executeRaw("DELETE FROM config WHERE key='persistence.refresh_barrier_max_wait_ms'");
+ }
+}), 180_000);
+
+test('a live consumer that cannot claim a held write keeps the pending_import refusal', () => each(async f => {
+ const seen = (await f.engine.readPageSnapshot('one', { sourceId: f.alpha }))!.revision;
+ foreignCommit(f, 'one.md', page('Alpha one', IMPORTED));
+ await f.engine.executeRaw(`INSERT INTO persistence_consumers(host_id,pid,nonce,kind,mode,host_json_path,persistence_home,version,capabilities)
+ VALUES($1::uuid,1,'barrier-only-example','serve','full','/nonexistent/host.json','/nonexistent','0.0.1','{refresh_barrier_1}')`, [await ownerHost(f)]);
+ try {
+ const out = await call(f, 'put_page', { slug: 'one', content: page('Alpha one', 'Refused.'), expected_revision: seen });
+ expect(out.isError).toBe(true);
+ const [row] = await f.engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE operation=$1 ORDER BY sequence DESC LIMIT 1', ['put_page']);
+ expect(row).toMatchObject({ state: 'conflict', error_code: 'source_changed', deferred_import_from: null });
+ expect((row!.error_detail as { origin?: string }).origin).toBe('pending_import');
+ } finally {
+ await f.engine.executeRaw("DELETE FROM persistence_consumers WHERE nonce='barrier-only-example'");
+ }
+}), 180_000);
+
test('with the barrier off a write onto a file awaiting import keeps the pending_import refusal', () => each(async f => {
const seen = (await f.engine.readPageSnapshot('one', { sourceId: f.alpha }))!.revision;
foreignCommit(f, 'one.md', page('Alpha one', IMPORTED));
diff --git a/test/refresh-retry-hint-gst1582.test.ts b/test/refresh-retry-hint-gst1582.test.ts
index db35249454..0e3bcf38d2 100644
--- a/test/refresh-retry-hint-gst1582.test.ts
+++ b/test/refresh-retry-hint-gst1582.test.ts
@@ -104,6 +104,17 @@ test('with no refresh history, or past its typical duration, the hint is the pha
expect((await refused(f)).retryAfterMs).toBe(15_000);
}), 120_000);
+test('a refresh that waited in recovery_required does not stretch the typical duration', () => each(async f => {
+ _setRefreshFenceWaitForTests(0);
+ await history(f.engine, f, [200, 240, 220, 7200, 7200, 7200, 7200]);
+ await f.engine.executeRaw(`UPDATE persistence_worktree_refreshes SET outcome='{"refusal":{"code":"refresh_recovery_required"}}'::jsonb
+ WHERE state='completed' AND completed_at-created_at>interval '1000 seconds'`);
+ await activeRefresh(f.engine, f, 'syncing', 20);
+ const { retryAfterMs } = await refused(f);
+ expect(retryAfterMs).toBeGreaterThanOrEqual(190_000);
+ expect(retryAfterMs).toBeLessThanOrEqual(201_000);
+}), 120_000);
+
test('a managed sync the refresh refused gets the same derived hint', () => each(async f => {
await history(f.engine, f, [120]);
await activeRefresh(f.engine, f, 'fenced', 30);