Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

persistence: barrier surfaces (pending at once, MCP pending success, expiry, downgrade check, writer status) and tests

garrytane3078a53be7b
diff --git a/src/cli/commands/upgrade.ts b/src/cli/commands/upgrade.ts
index 08c2faf26d..2d581012ab 100644
--- a/src/cli/commands/upgrade.ts
+++ b/src/cli/commands/upgrade.ts
@@ -2,9 +2,25 @@
* `gbrain upgrade`: pre-connect dispatch (engine-free), run by
* handleCliOnly before the connectEngine() terminator. Moved verbatim from
* src/cli.ts (refactor wave 1, W4 cli); the record lives in src/cli/command-table.ts.
+ * PR B: `--check-downgrade` (read-only) opens the brain and refuses while writes deferred behind a refresh wait.
*/
+import type { CliDispatchContext } from '../command-table.ts';
-export async function run(args: string[]): Promise<void> {
+export async function run(args: string[], ctx: CliDispatchContext): Promise<void> {
+ if (args.includes('--check-downgrade')) {
+ const [{ deferredBacklog }, { opError }, { finishCliTeardown, setCliExitVerdict }, { writeCliError }] = await Promise.all([
+ import('../../core/persistence/refresh-barrier.ts'), import('../../core/ops/contract.ts'), import('../../core/cli-force-exit.ts'), import('../cli-error.ts')]);
+ const engine = await ctx.connectEngine({ probeOnly: true });
+ try {
+ const backlog = await deferredBacklog(engine);
+ if (backlog.count === 0) { console.log(args.includes('--json') ? JSON.stringify({ ok: true, deferred: 0 }) : 'No deferred writes are waiting; a downgrade leaves nothing undrained.'); return; }
+ setCliExitVerdict(writeCliError(opError('downgrade_blocked_deferred_writes',
+ `${backlog.count} write(s) deferred behind a worktree refresh are still waiting (oldest ${Math.round(backlog.oldest_age_ms / 1000)} s), and an older gbrain cannot drain them.`,
+ 'Turn the barrier off with gbrain config set persistence.refresh_barrier false, wait until gbrain upgrade --check-downgrade exits 0, then downgrade.',
+ { detail: `count=${backlog.count} oldest_age_ms=${backlog.oldest_age_ms}` }), 'upgrade', { argv: args }));
+ } finally { await finishCliTeardown({ engine }); }
+ return;
+ }
const { runUpgrade } = await import('../../commands/upgrade.ts');
await runUpgrade(args);
}
diff --git a/src/commands/serve-http-mcp.ts b/src/commands/serve-http-mcp.ts
index 5d4e5915fa..8fcca493d6 100644
--- a/src/commands/serve-http-mcp.ts
+++ b/src/commands/serve-http-mcp.ts
@@ -638,7 +638,7 @@ async function recordMcpToolResult(
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, params)
VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
[authInfo.clientId, agentName, name, latency, successStatus],
- [logParamsObj],
+ [successStatus === 'accepted_pending' ? { ...(logParamsObj && typeof logParamsObj === 'object' ? logParamsObj : {}), write_request_id: acceptedPendingReceipt(toolResult)?.request_id } : logParamsObj],
);
} catch { /* best effort */ }
broadcastEvent({
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index dbf85164b5..a9a983ffec 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -261,6 +261,7 @@ export const CODES = {
},
deleted_page_chunks_overdue: { class: 'consent', summary: "Chunks of pages soft-deleted longer than the purge window (72h) are still stored.", why: 'Search never reads them; the purge lifecycle (`gbrain pages purge-deleted`, the autopilot purge phase) hard-deletes such pages and their chunks. The purge is brain-wide and irreversible, so it needs the user.', docs: 'docs/guides/troubleshooting.md#embedding-state', suggestion: 'Preview with `gbrain pages purge-deleted --dry-run --json`, then run `gbrain pages purge-deleted --yes` once the user agrees.', fix: { argv: ['gbrain', 'pages', 'purge-deleted', '--dry-run', '--json'], consent: [], actor: 'agent', why: 'Lists the soft-deleted pages the purge would remove; changes nothing.', requires_exclusive: false, verify: { argv: ['gbrain', 'doctor', '--only', 'embedding_state', '--json'] } } },
demo_graph_failed: { class: 'server', summary: "The fictional graph did not verify." },
+ downgrade_blocked_deferred_writes: { class: 'consent', actor: 'host_admin', exit: 3, summary: "Writes deferred behind a worktree refresh are still waiting, and an older gbrain cannot drain them.", why: "A release before the refresh write barrier never claims a deferred write, so after a downgrade those writes wait until the next upgrade. Safety does not depend on this check; liveness does.", docs: 'docs/guides/write-refusals.md#deferred-writes', suggestion: 'Turn the barrier off (gbrain config set persistence.refresh_barrier false), wait until gbrain upgrade --check-downgrade exits 0, then downgrade.' },
demo_import_failed: { class: 'server', summary: "The fictional page did not import successfully." },
demo_verification_failed: { class: 'server', summary: "Expected ownership or decision provenance is missing." },
derived_cap_exhausted: { class: 'server', summary: "Paid work stopped at the cost cap derived from its estimate; the run is resumable." },
@@ -660,6 +661,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." },
+ 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." },
relay_disabled: { class: 'caller', summary: "Google connect credential error: relay disabled.", docs: 'docs/guides/google-connect.md#troubleshooting' },
diff --git a/src/core/persistence/consumer.ts b/src/core/persistence/consumer.ts
index 467ee827c4..c337f8fe72 100644
--- a/src/core/persistence/consumer.ts
+++ b/src/core/persistence/consumer.ts
@@ -3,6 +3,7 @@ import { withoutCallerAccess } from '../search/private-visibility.ts';
import { withEngineScope } from '../engine-scope.ts';
import type { GBrainConfig } from '../config.ts';
import { claimableWriteSql, foregroundPrioritySql, claimGroupFollowers, claimNextLaneHead, claimNextWrite, publicationGroupKey, syncGroup, floorPreparationAttempts, hasClaimableWrite, getWriteRequestById, releaseUnpublishedClaim, renewWriteClaim, vacuumPersistenceQueues, independentGroup, sweepSegmentStorage, yieldToEventLoop } from './journal.ts';
+import { expireDeferredWrites } from './refresh-barrier.ts';
import { connectionCapFailure, finishPreparationStalled, finishUnpublishedFailure, preparationAbortReason, recoverPublication, transientDatabaseFailure, type PreparedMutation } from './coordinator.ts';
import { hostIdFor } from './identity.ts';
import { executeClaimedGroup, PAGE_BATCH_GROUP_MAX, publishSingleWrite, singleWrite } from './group-publish.ts';
@@ -710,6 +711,8 @@ export class PersistenceConsumer implements PersistenceConsumerLike {
UPDATE persistence_requests r SET state='queued',execution_token=NULL,claim_expires_at=NULL,
preparation_attempts=r.preparation_attempts+CASE WHEN $2::boolean THEN ${EXPIRED_PREPARING_CHARGE_SQL('r')} ELSE 0 END
FROM expired WHERE r.id=expired.id`, [this.hostId, this.policy.deadlines, deadOwners], { signal }));
+ // PR B: a write deferred behind a refresh that outlived the barrier's wait limit ends failed, nothing applied.
+ for (const row of await this.phase('deferred_expiry', signal => expireDeferredWrites(this.engine, this.hostId, signal))) this.settled(row);
}
if (this.housekeepingOnly) return;
if (publicationConcurrency(this.engine) === 0) {
diff --git a/src/core/persistence/journal.ts b/src/core/persistence/journal.ts
index 5a325589d2..0895b4a95c 100644
--- a/src/core/persistence/journal.ts
+++ b/src/core/persistence/journal.ts
@@ -67,6 +67,8 @@ export interface WriteAdmission {
origin?: AdmissionOrigin;
/** Phase 4.2: the brain the cached pre-admission reads came from; admission under another brain throws PreadmitBrainChanged. */
brainId?: string;
+ /** PR B: the caller reports a pending receipt for a write deferred behind a refresh (page and memory verbs); others keep the refusal. */
+ deferrable?: boolean;
}
interface Counter {
key: string; outstanding_count: number | string; intent_bytes: number | string;
@@ -621,9 +623,9 @@ export const REFRESH_BARRIER_MAX_DEFERRED_KEY = 'persistence.refresh_barrier_max
export const REFRESH_BARRIER_MAX_DEFERRED = 1000;
/** 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';
-/** A single page write may wait behind a refresh; jobs (managed sync included), grouped batches and skill bundles keep the refusal. */
+/** 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.targetKind ?? 'page') === 'page' && input.operation !== 'submit_job' && publicationGroupKey({ operation: input.operation, intent: input.intent }) === null;
+ return input.deferrable === true && (input.targetKind ?? 'page') === 'page' && input.operation !== 'submit_job' && publicationGroupKey({ operation: input.operation, intent: input.intent }) === null;
}
async function readRefreshBarrier(engine: BrainEngine): Promise<RefreshBarrier | null> {
if (!await writeSwitchOn(engine, 'refresh_barrier').catch(() => false)) return null;
diff --git a/src/core/persistence/memory-mutations.ts b/src/core/persistence/memory-mutations.ts
index 21f6dfc449..fea7b74a8e 100644
--- a/src/core/persistence/memory-mutations.ts
+++ b/src/core/persistence/memory-mutations.ts
@@ -228,7 +228,7 @@ export async function submitRememberMutation(ctx: OperationContext, params: Reco
visibility, ...(call.visibilityDefaulted ? { visibility_defaulted: true } : {}), ...(memberPage ? { member_page: true } : {}),
...(linked ? { entity_inferred: linked.via } : {}), ...(inference && 'warning' in inference ? { entity_warning: inference.warning } : {}),
session_id: ctx.sessionId ?? null },
- authority, worktreeId: writeThrough ? binding?.worktree_id : null, topologyGeneration: writeThrough ? binding?.topology_generation : null });
+ authority, worktreeId: writeThrough ? binding?.worktree_id : null, topologyGeneration: writeThrough ? binding?.topology_generation : null, deferrable: true });
const written = await waitForWrite(ctx.engine, row, ctx.config, waitMs ?? ctx.writeWaitMs);
const response = throwIfHeld(withRememberTarget(row, () => writeResponse(written)));
emitFenceNotice(ctx, response, row.slug);
@@ -350,7 +350,7 @@ export async function submitForgetMutation(ctx: OperationContext, operation: 'fo
const row = await admitWrite(ctx.engine, { origin: ctx.admissionOrigin, principal, operation, sourceId, sourceIncarnation: source.incarnation,
slug, pageId: snapshot?.page.id ?? null, requestId, clientRequestId, callerIntent,
intent: { ...callerIntent, reason, semantic_review: !ownPage && p.semantic_review !== false, ...(ownPage ? { member_page: ownPage } : {}) }, authority,
- worktreeId: binding?.worktree_id ?? null, topologyGeneration: binding?.topology_generation ?? null });
+ worktreeId: binding?.worktree_id ?? null, topologyGeneration: binding?.topology_generation ?? null, deferrable: true });
const written = await waitForWrite(ctx.engine, row, ctx.config, waitMs ?? ctx.writeWaitMs);
return withSimilarActive(ctx, operation, sourceId, p, writeResponse(written));
}
diff --git a/src/core/persistence/page-mutations.ts b/src/core/persistence/page-mutations.ts
index 41f258f4c8..129adbefe2 100644
--- a/src/core/persistence/page-mutations.ts
+++ b/src/core/persistence/page-mutations.ts
@@ -552,5 +552,5 @@ export async function preparePageAdmission(ctx: OperationContext,
return { typeWarning, slugAdvisory, admission: { origin: ctx.admissionOrigin, principal, operation: input.operation, sourceId, sourceIncarnation: source.incarnation,
slug, pageId: snapshot?.page.id ?? null, requestId, clientRequestId: input.batch ? undefined : clientRequestIdOf(params.request_id), callerIntent, intent, authority,
...(input.operation === 'edit_page' ? { terminalReservation: receiptReservation({ intent, authority }, (await import('./page-edit.ts')).EDIT_PAGE_RECEIPT_RESERVE) } : {}),
- worktreeId: writeThrough ? binding?.worktree_id : null, topologyGeneration: writeThrough ? binding?.topology_generation : null } };
+ worktreeId: writeThrough ? binding?.worktree_id : null, topologyGeneration: writeThrough ? binding?.topology_generation : null, deferrable: true } };
}
diff --git a/src/core/persistence/refresh-barrier.ts b/src/core/persistence/refresh-barrier.ts
index e07f4faa1c..db0ba668f2 100644
--- a/src/core/persistence/refresh-barrier.ts
+++ b/src/core/persistence/refresh-barrier.ts
@@ -13,6 +13,8 @@ import { execFileBounded } from '../bounded-child-exec.ts';
import { gitChildEnv } from '../git-env.ts';
import { OperationError } from '../ops/contract.ts';
import { authorizeWrite } from './authority.ts';
+import type { BrainEngine } from '../engine.ts';
+import { completeWrite } from './journal.ts';
import type { SqlEngine, WriteRequest } from './model.ts';
const GIT_ENV = { GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never', LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0' };
@@ -31,7 +33,7 @@ async function refreshChangedPaths(engine: SqlEngine, refreshId: string, root: s
'SELECT state,old_head,target_head,released_at IS NOT NULL AS released FROM persistence_worktree_refreshes WHERE id=$1::uuid', [refreshId]);
if (!refresh?.released) return null;
if (refresh.state === 'aborted' || refresh.old_head === refresh.target_head) return new Set<string>();
- const { error, stdout } = await execFileBounded('git', ['-C', root, '-c', 'core.quotepath=false', 'diff', '--name-only', '-z', '--no-renames',
+ const { error, stdout } = await execFileBounded('git', ['-C', root, '-c', 'core.quotepath=false', 'diff', '--name-only', '-z', '--no-renames', '--relative',
refresh.old_head, refresh.target_head], { timeout: DIFF_TIMEOUT_MS, maxBuffer: 64 * 1024 ** 2, env: gitChildEnv(GIT_ENV) });
return error ? null : new Set(stdout.split('\0').filter(Boolean));
})();
@@ -68,5 +70,48 @@ export async function deferredReplayRefusal(engine: SqlEngine, row: WriteRequest
: `Refresh ${refreshId} changed ${touched.join(', ')} after request ${row.request_id} was accepted, so nothing was applied and no newer content was overwritten. Read the page again and submit the change with a new request_id.` } };
}
+export const REFRESH_BARRIER_MAX_WAIT_KEY = 'persistence.refresh_barrier_max_wait_ms';
+export const REFRESH_BARRIER_MAX_WAIT_MS = 15 * 60_000;
+
+/**
+ * The owner's housekeeping: a deferred write whose refresh is still unreleased past the wait limit ends failed with
+ * `refresh_barrier_expired` (nothing applied, counters released). The refresh row is locked first (lock order: worktree,
+ * refresh, counters, request), so an expiry and the release that would make the row claimable never both win.
+ */
+export async function expireDeferredWrites(engine: BrainEngine, hostId: string, signal?: AbortSignal): Promise<WriteRequest[]> {
+ const [config] = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key=$1', [REFRESH_BARRIER_MAX_WAIT_KEY], { signal });
+ const configured = Number(config?.value);
+ const maxWaitMs = Number.isSafeInteger(configured) && configured > 0 ? configured : REFRESH_BARRIER_MAX_WAIT_MS;
+ const expired = await engine.executeRaw<WriteRequest>(`SELECT r.* FROM persistence_requests r
+ JOIN persistence_worktrees w ON w.id=r.worktree_id JOIN persistence_worktree_refreshes f ON f.id=r.deferred_refresh_id
+ WHERE w.owner_host_id=$1::uuid AND r.state='deferred' AND f.released_at IS NULL
+ AND r.created_at<now()-($2::double precision*interval '1 millisecond') ORDER BY r.sequence LIMIT 100`, [hostId, maxWaitMs], { signal });
+ const finished: WriteRequest[] = [];
+ for (const row of expired) {
+ const done = await engine.transaction(async tx => {
+ const [held] = await tx.executeRaw('SELECT 1 FROM persistence_worktree_refreshes WHERE id=$1::uuid AND released_at IS NULL FOR NO KEY UPDATE', [row.deferred_refresh_id]);
+ if (!held) return null;
+ return completeWrite(tx, row, 'failed', {}, { code: 'refresh_barrier_expired',
+ message: `Request ${row.request_id} waited behind refresh ${row.deferred_refresh_id} for more than ${Math.round(maxWaitMs / 1000)} s, and the refresh has not finished, so nothing was applied. Check the refresh with gbrain sources writer status --source ${row.source_id} --json, then submit the write again with a new request_id.` });
+ });
+ if (done) finished.push(done);
+ }
+ return finished;
+}
+
+/** Whether the refresh a deferred write waits behind has ended (a read that fails counts as not ended). */
+export async function refreshReleased(engine: SqlEngine, refreshId: string | null | undefined): Promise<boolean> {
+ if (!refreshId) return true;
+ const [row] = await engine.executeRaw<{ released: boolean }>('SELECT released_at IS NOT NULL AS released FROM persistence_worktree_refreshes WHERE id=$1::uuid', [refreshId]).catch(() => []);
+ return row?.released === true;
+}
+
+/** Deferred writes still waiting, for `gbrain upgrade --check-downgrade` and writer status. */
+export async function deferredBacklog(engine: SqlEngine): Promise<{ count: number; oldest_age_ms: number }> {
+ const [row] = await engine.executeRaw<{ count: number; oldest_age_ms: number | null }>(`SELECT count(*)::int AS count,
+ (EXTRACT(EPOCH FROM now()-min(created_at))*1000)::bigint AS oldest_age_ms FROM persistence_requests WHERE state='deferred'`);
+ return { count: Number(row?.count ?? 0), oldest_age_ms: Number(row?.oldest_age_ms ?? 0) };
+}
+
/** Test seam: forget every cached refresh diff. */
export function _resetRefreshBarrierCacheForTests(): void { changed.clear(); }
diff --git a/src/core/persistence/service.ts b/src/core/persistence/service.ts
index ba615ac459..f39b5ce924 100644
--- a/src/core/persistence/service.ts
+++ b/src/core/persistence/service.ts
@@ -1,4 +1,5 @@
import { PENDING_IMPORT, pendingImportRefusal } from './pending-import.ts';
+import { refreshReleased } from './refresh-barrier.ts';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { OperationError } from '../ops/contract.ts';
@@ -237,6 +238,8 @@ export type WriteWait =
export async function awaitWrite(engine: BrainEngine, row: WriteRequest, config: GBrainConfig,
opts: { waitMs?: number; signal?: AbortSignal; whileHeldMs?: number } = {}): Promise<WriteWait> {
if (isTerminal(row)) return { kind: 'terminal', row };
+ // PR B: a write deferred behind a refresh still running cannot publish before it ends, so its pending receipt is returned at once.
+ if (row.state === 'deferred' && !await refreshReleased(engine, row.deferred_refresh_id)) return { kind: 'pending', row };
const consumer = startPersistenceConsumer(engine, config);
const service = services.get(engine)!;
const id = row.id;
diff --git a/src/core/persistence/types.ts b/src/core/persistence/types.ts
index 0bdc0d8ad5..4ee0376c15 100644
--- a/src/core/persistence/types.ts
+++ b/src/core/persistence/types.ts
@@ -164,6 +164,7 @@ export function publicWriteReceipt(receipt: WriteReceipt): WriteReceipt {
...(receipt.created_at !== undefined ? { created_at: receipt.created_at } : {}),
...(receipt.updated_at !== undefined ? { updated_at: receipt.updated_at } : {}),
...(receipt.target !== undefined ? { target: receipt.target } : {}),
+ ...(receipt.deferred !== undefined && !isTerminalWriteState(receipt.state) ? { deferred: { refresh_id: receipt.deferred.refresh_id } } : {}),
...(!isTerminalWriteState(receipt.state) && isWriteDiagnostic(receipt.diagnostic) ? { diagnostic: {
age_ms: receipt.diagnostic.age_ms, assessment: receipt.diagnostic.assessment,
reason: receipt.diagnostic.reason, next_action: receipt.diagnostic.next_action,
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index 2298ad8ed4..624555adc1 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -1202,7 +1202,10 @@ export async function refreshHolderReport(engine: BrainEngine, row: Pick<Worktre
/** `gbrain sources writer status`: active refreshes (optionally of one source's worktree) with their holder and the command that moves each on. */
export async function activeWorktreeRefreshes(engine: BrainEngine, sourceId?: string): Promise<Array<Record<string, unknown>>> {
- const rows = await engine.executeRaw<WorktreeRefreshRow & { owner_host_id: string | null }>(`SELECT f.*,w.owner_host_id::text AS owner_host_id FROM persistence_worktree_refreshes f
+ const rows = await engine.executeRaw<WorktreeRefreshRow & { owner_host_id: string | null; deferred_count: number; deferred_oldest_ms: number | null }>(`SELECT f.*,w.owner_host_id::text AS owner_host_id,
+ (SELECT count(*)::int FROM persistence_requests d WHERE d.deferred_refresh_id=f.id AND d.state='deferred') AS deferred_count,
+ (SELECT (EXTRACT(EPOCH FROM now()-min(d.created_at))*1000)::bigint FROM persistence_requests d WHERE d.deferred_refresh_id=f.id AND d.state='deferred') AS deferred_oldest_ms
+ FROM persistence_worktree_refreshes f
LEFT JOIN persistence_worktrees w ON w.id=f.worktree_id WHERE f.state IN ${ACTIVE_REFRESH_STATES_SQL}
AND ($1::text IS NULL OR $1=ANY(f.source_ids)) ORDER BY f.created_at`, [sourceId ?? null]);
return Promise.all(rows.map(async row => {
@@ -1210,6 +1213,7 @@ export async function activeWorktreeRefreshes(engine: BrainEngine, sourceId?: st
return { refresh_id: row.id, worktree_id: row.worktree_id, state: row.state, source_ids: row.source_ids,
old_head: row.old_head, target_head: row.target_head, upstream_ref: row.upstream_ref, updated_at: new Date(row.updated_at).toISOString(),
...(row.outcome.refusal ? { refusal: row.outcome.refusal } : {}), ...report,
+ ...(Number(row.deferred_count) > 0 ? { deferred: { count: Number(row.deferred_count), oldest_age_ms: Number(row.deferred_oldest_ms ?? 0), refresh_id: row.id } } : {}),
next: report.liveness === 'live' && row.state === 'draining' ? 'Writes to this worktree are refused while queued work drains; retry them after about a second.'
: report.liveness === 'live' ? `Wait for it: ${describeHolder(report.holder)} holds the refresh lock and finishes it.`
: report.liveness === 'unknown' && report.fix?.argv ? `On host ${report.holder?.hostname ?? 'unknown'} (${report.holder?.host_id ?? row.owner_host_id ?? 'unknown host id'}), which holds the refresh lock: ${report.fix.argv.map(q).join(' ')}`
diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.ts
index 3fce62c0a3..7c7c150b6a 100644
--- a/src/mcp/dispatch.ts
+++ b/src/mcp/dispatch.ts
@@ -58,7 +58,7 @@ import { enforceReadTrustFloor } from '../core/eligibility/registry.ts';
import { invalidateHotMemoryForEngine } from '../core/facts/meta-hook.ts';
import { withSearchConnectionBudget } from '../core/search/connection-budget.ts';
import { isEngineDegraded } from '../core/degraded-marker.ts';
-import { admittedPendingReceipt, type WriteReceipt } from '../core/persistence/types.ts';
+import { admittedPendingReceipt, isWriteReceipt, publicWriteReceipt, type WriteReceipt } from '../core/persistence/types.ts';
import { currentVerifiedLocalWriter, readLocalWriter, verifyLocalWriter, withRequestIdentityMemo, withVerifiedLocalRegistration } from '../core/persistence/identity.ts';
import { frameOverCap, resultTooLargeError } from '../core/egress-budget.ts';
import { isAIInvocationPolicyError } from '../core/ai/invocation-guard.ts';
@@ -543,9 +543,27 @@ export type RequestLogStatus = 'success' | 'success_with_warnings' | 'accepted_p
/** #5249: the receipt of a write the dispatcher returned as accepted but not yet committed. */
export function acceptedPendingReceipt(result: ToolResult): WriteReceipt | null {
- if (!result.isError) return null;
- try { return admittedPendingReceipt(JSON.parse(result.content[0]?.text ?? '{}')); }
- catch { return null; }
+ try {
+ const parsed: unknown = JSON.parse(result.content[0]?.text ?? '{}');
+ return result.isError ? admittedPendingReceipt(parsed) : deferredPendingReceipt(parsed);
+ } catch { return null; }
+}
+
+/** PR B: the receipt of a successful `status: "pending"` result, a write deferred behind a refresh. */
+function deferredPendingReceipt(parsed: unknown): WriteReceipt | null {
+ const body = parsed as { status?: unknown; receipt?: unknown } | null;
+ return body?.status === 'pending' && isWriteReceipt(body.receipt) ? body.receipt : null;
+}
+
+/**
+ * PR B (docs/designs/REFRESH_WRITE_BARRIER.md): a write deferred behind a worktree refresh was accepted and publishes after
+ * it, so MCP answers it as a pending success instead of an error. Any other `write_pending` stays an error.
+ */
+export function deferredWriteResult(e: unknown): Record<string, unknown> | null {
+ if (!(e instanceof OperationError) || (e.code !== 'write_pending' && e.writeError !== 'write_pending') || !e.writeRequest?.deferred) return null;
+ const receipt = publicWriteReceipt(e.writeRequest);
+ return { status: 'pending', request_id: receipt.request_id, receipt, deferred: e.writeRequest.deferred,
+ next: { tool: 'get_write_request', arguments: { request_id: receipt.request_id }, cli: `gbrain write-request ${receipt.request_id}`, retry_after_ms: receipt.retry_after_ms } };
}
/**
@@ -571,6 +589,7 @@ export function requestLogStatusForResult(result: ToolResult): RequestLogStatus
} catch { /* unparseable error content stays plain 'error' */ }
return 'error';
}
+ if (acceptedPendingReceipt(result)) return 'accepted_pending';
const warnings = result._meta?.warnings;
return Array.isArray(warnings) && warnings.length > 0 ? 'success_with_warnings' : 'success';
}
@@ -1334,6 +1353,8 @@ async function dispatchResolvedCall(
// never tells a mutating op with an unknown outcome to retry.
notices.push(...await sessionSafetyNotices(engine, opts, ctx.config));
notices.push(...await grantBlockedNotices(engine, opts, refusedByGrant(e)));
+ const deferred = deferredWriteResult(e);
+ if (deferred) return toolResultWithNotices(deferred, admitNotices(notices, opts), dispatchRenderContext(opts));
return errorResult(e, opts, { op: name, mutating: op.mutating === true, idempotent: op.idempotent === true, notices: admitNotices(notices, opts) });
}
}
diff --git a/test/refresh-write-barrier.test.ts b/test/refresh-write-barrier.test.ts
new file mode 100644
index 0000000000..5db60ae19a
--- /dev/null
+++ b/test/refresh-write-barrier.test.ts
@@ -0,0 +1,209 @@
+/**
+ * PR B refresh write barrier (docs/designs/REFRESH_WRITE_BARRIER.md).
+ *
+ * Protects: with persistence.refresh_barrier on, a page write that reaches a refreshing checkout is journaled `deferred`
+ * and answered pending at once (MCP isError false, status pending; receipt state queued plus `deferred`); after the
+ * refresh ends it commits, unless the refresh changed its file, which ends it `revision_conflict` with nothing applied;
+ * a consumer claim without the barrier's session declaration (an older binary) cannot move a deferred row; a replay of the
+ * request id returns the same receipt; a write past the wait limit ends `refresh_barrier_expired` with its counters
+ * released; a live consumer without the capability keeps the refusal; a repo-less source is never deferred.
+ * Seams: the real refresh state machine paused at its drained boundary (`hooks.boundary`); GBRAIN_REFRESH_BARRIER.
+ */
+import { afterAll, afterEach, beforeAll, beforeEach, expect, test } from 'bun:test';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { disposePersistenceConsumer, waitForWrite } from '../src/core/persistence/service.ts';
+import { refreshWorktree } from '../src/core/persistence/worktree-refresh.ts';
+import { getWriteRequestById } from '../src/core/persistence/journal.ts';
+import { resetWriteSwitches } from '../src/core/persistence/switches.ts';
+import { _setRefreshFenceWaitForTests } from '../src/core/persistence/admission-retry.ts';
+import { _resetRefreshBarrierCacheForTests, deferredBacklog, expireDeferredWrites } from '../src/core/persistence/refresh-barrier.ts';
+import type { WriteRequest } from '../src/core/persistence/model.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { testBackends } from './helpers/test-backends.ts';
+import { page, withRefreshFixture, type RefreshFixture } from './helpers/worktree-refresh-fixture.ts';
+
+const backends = testBackends();
+const engines: BrainEngine[] = [];
+let closePostgres: (() => Promise<void>) | undefined;
+const savedBarrier = process.env.GBRAIN_REFRESH_BARRIER;
+
+beforeAll(async () => {
+ if (backends.includes('pglite')) {
+ const engine = new PGLiteEngine();
+ await engine.connect({}); await engine.initSchema(); engines.push(engine);
+ }
+ if (backends.includes('postgres')) {
+ const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
+ engines.push(pg.engine); closePostgres = pg.close;
+ }
+}, 120_000);
+afterAll(async () => {
+ for (const engine of engines) { await disposePersistenceConsumer(engine); if (engine.kind === 'pglite') await engine.disconnect(); }
+ await closePostgres?.();
+});
+beforeEach(() => { process.env.GBRAIN_REFRESH_BARRIER = '1'; resetWriteSwitches(); _setRefreshFenceWaitForTests(0); _resetRefreshBarrierCacheForTests(); });
+afterEach(() => {
+ if (savedBarrier === undefined) delete process.env.GBRAIN_REFRESH_BARRIER; else process.env.GBRAIN_REFRESH_BARRIER = savedBarrier;
+ resetWriteSwitches(); _setRefreshFenceWaitForTests(null);
+});
+
+const each = async (fn: (f: RefreshFixture) => Promise<void>) => { for (const engine of engines) await withRefreshFixture(engine, fn); };
+
+/** Runs `fn` while a real refresh of the checkout is paused at its drained boundary; the refresh changes alpha/two.md. */
+async function duringRefresh(f: RefreshFixture, fn: () => Promise<void>, change: [string, string] = ['alpha/two.md', page('Alpha two', 'An upstream observation.')]) {
+ f.push(...change);
+ let release!: () => void; const gate = new Promise<void>(resolve => { release = resolve; });
+ let reached!: () => void; const drained = new Promise<void>(resolve => { reached = resolve; });
+ const refresh = refreshWorktree(f.engine, f.alpha, { hooks: { boundary: async point => { if (point === 'drained') { reached(); await gate; } } } });
+ await drained;
+ try { await fn(); } catch (error) { release(); await refresh.catch(() => undefined); throw error; }
+ release();
+ return refresh;
+}
+
+async function call(f: RefreshFixture, name: string, params: Record<string, unknown>, sourceId = f.alpha) {
+ const result = await dispatchToolCall(f.engine, name, params, { remote: true, transport: 'stdio', sourceId, admissionOrigin: 'interactive' });
+ return { isError: result.isError === true, body: JSON.parse(result.content[0]!.text) as Record<string, any> };
+}
+
+async function requestRow(f: RefreshFixture, requestId: string): Promise<WriteRequest> {
+ const [row] = await f.engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE request_id=$1::uuid', [requestId]);
+ return row!;
+}
+
+/** Drives this process's consumer until the released deferred row settles. */
+async function settle(f: RefreshFixture, row: WriteRequest): Promise<WriteRequest> {
+ return waitForWrite(f.engine, (await getWriteRequestById(f.engine, row.id))!, { engine: f.engine.kind } as never, 30_000);
+}
+
+async function outstanding(f: RefreshFixture): Promise<number> {
+ const [row] = await f.engine.executeRaw<{ n: number }>("SELECT outstanding_count::int AS n FROM persistence_counters WHERE key='brain'");
+ return Number(row?.n ?? 0);
+}
+
+test('a page write during a refresh is deferred, answered pending at once, and commits after the refresh', () => each(async f => {
+ let deferred!: WriteRequest;
+ const refresh = await duringRefresh(f, async () => {
+ const started = performance.now();
+ const out = await call(f, 'put_page', { slug: 'notes/deferred', content: page('Deferred', 'written during the refresh') });
+ expect(performance.now() - started).toBeLessThan(5000);
+ expect(out.isError).toBe(false);
+ expect(out.body).toMatchObject({ status: 'pending', receipt: { state: 'queued' }, next: { tool: 'get_write_request' } });
+ expect(out.body.deferred.refresh_id).toBe(out.body.receipt.deferred.refresh_id);
+ deferred = await requestRow(f, out.body.request_id);
+ expect(deferred.state).toBe('deferred');
+ expect(deferred.deferred_refresh_id).toBe(out.body.deferred.refresh_id);
+ expect((await deferredBacklog(f.engine)).count).toBe(1);
+ const replay = await call(f, 'put_page', { slug: 'notes/deferred', content: page('Deferred', 'written during the refresh'), request_id: out.body.request_id });
+ expect(replay.isError).toBe(false);
+ expect(replay.body.request_id).toBe(out.body.request_id);
+ expect(await f.requestCount()).toBeGreaterThan(0);
+ const [{ n }] = await f.engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM persistence_requests WHERE request_id=$1::uuid', [out.body.request_id]);
+ expect(Number(n)).toBe(1);
+ });
+ expect((await refresh).status).toBe('completed');
+ const done = await settle(f, deferred);
+ expect(done.state).toBe('committed');
+ const [row] = await f.engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [f.alpha, 'notes/deferred']);
+ expect(Number(row!.n)).toBe(1);
+ expect((await deferredBacklog(f.engine)).count).toBe(0);
+}), 180_000);
+
+test('a deferred create of a page the refresh added is refused by the page guard and never overwrites it', () => each(async f => {
+ let deferred!: WriteRequest;
+ const refresh = await duringRefresh(f, async () => {
+ const out = await call(f, 'put_page', { slug: 'two', content: page('Mine', 'a local version that must not win') });
+ expect(out.isError).toBe(false);
+ deferred = await requestRow(f, out.body.request_id);
+ expect(deferred.state).toBe('deferred');
+ });
+ expect((await refresh).status).toBe('completed');
+ const done = await settle(f, deferred);
+ expect(done.state).toBe('conflict');
+ expect(done.error_code).toBe('revision_required');
+ const [stored] = await f.engine.executeRaw<{ compiled_truth: string }>('SELECT compiled_truth FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [f.alpha, 'two']);
+ expect(stored?.compiled_truth ?? '').not.toContain('must not win');
+}), 180_000);
+
+const PERSON = '---\ntitle: Alice Example\ntype: person\n---\nAlice is a person.\n';
+
+test('a deferred blind write to a page the refresh changed ends revision_conflict naming the file, nothing applied', () => each(async f => {
+ f.push('alpha/people/alice-example.md', PERSON);
+ expect((await refreshWorktree(f.engine, f.alpha)).status).toBe('completed');
+ let deferred!: WriteRequest;
+ const refresh = await duringRefresh(f, async () => {
+ const out = await call(f, 'remember', { fact: 'alice-example likes tea', entity: 'people/alice-example', provenance: 'test' });
+ expect(out.isError).toBe(false);
+ expect(out.body.status).toBe('pending');
+ deferred = await requestRow(f, out.body.request_id);
+ expect(deferred.state).toBe('deferred');
+ }, ['alpha/people/alice-example.md', PERSON.replace('Alice is a person.', 'Alice is a person who moved.')]);
+ expect((await refresh).status).toBe('completed');
+ const done = await settle(f, deferred);
+ expect(done).toMatchObject({ state: 'conflict', error_code: 'revision_conflict' });
+ expect(done.error_message).toContain('people/alice-example.md');
+ const [{ n }] = await f.engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM facts WHERE fact LIKE '%likes tea%'");
+ expect(Number(n)).toBe(0);
+}), 180_000);
+
+test('a claim without the barrier declaration cannot move a deferred row, released or not', () => each(async f => {
+ let deferred!: WriteRequest;
+ const refresh = await duringRefresh(f, async () => {
+ const out = await call(f, 'put_page', { slug: 'notes/guarded', content: page('Guarded', 'body') });
+ deferred = await requestRow(f, out.body.request_id);
+ await expect(f.engine.executeRaw("UPDATE persistence_requests SET state='running' WHERE id=$1::uuid", [deferred.id])).rejects.toThrow();
+ await expect(f.engine.executeRaw("UPDATE persistence_requests SET state='queued' WHERE id=$1::uuid", [deferred.id])).rejects.toThrow();
+ });
+ expect((await refresh).status).toBe('completed');
+ await expect(f.engine.executeRaw("UPDATE persistence_requests SET state='running' WHERE id=$1::uuid", [deferred.id])).rejects.toThrow();
+ expect((await settle(f, deferred)).state).toBe('committed');
+}), 180_000);
+
+test('a deferred write past the wait limit ends refresh_barrier_expired and releases its counters', () => each(async f => {
+ const refresh = await duringRefresh(f, async () => {
+ const before = await outstanding(f);
+ const out = await call(f, 'put_page', { slug: 'notes/expired', content: page('Expired', 'body') });
+ const deferred = await requestRow(f, out.body.request_id);
+ expect(await outstanding(f)).toBe(before + 1);
+ await 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");
+ await new Promise(resolve => setTimeout(resolve, 20));
+ const [{ owner }] = await f.engine.executeRaw<{ owner: string }>('SELECT owner_host_id::text AS owner FROM persistence_worktrees WHERE id=$1::uuid', [f.worktreeId]);
+ const expired = await expireDeferredWrites(f.engine, owner);
+ expect(expired.map(row => row.id)).toEqual([deferred.id]);
+ const after = (await getWriteRequestById(f.engine, deferred.id))!;
+ expect(after).toMatchObject({ state: 'failed', error_code: 'refresh_barrier_expired' });
+ expect(await outstanding(f)).toBe(before);
+ await f.engine.executeRaw("DELETE FROM config WHERE key='persistence.refresh_barrier_max_wait_ms'");
+ });
+ expect((await refresh).status).toBe('completed');
+}), 180_000);
+
+test('a live consumer without the capability keeps the refusal; a repo-less source is never deferred', () => each(async f => {
+ const refresh = await duringRefresh(f, async () => {
+ const repoLess = await call(f, 'put_page', { slug: 'notes/repo-less', content: page('Repo-less', 'database only') }, 'default');
+ expect(repoLess.isError).toBe(false);
+ expect(repoLess.body.status).not.toBe('pending');
+ const [{ owner }] = await f.engine.executeRaw<{ owner: string }>('SELECT owner_host_id::text AS owner FROM persistence_worktrees WHERE id=$1::uuid', [f.worktreeId]);
+ 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,'old-binary-example','serve','full','/nonexistent/host.json','/nonexistent','0.0.1','{}')`, [owner]);
+ const before = await f.requestCount();
+ const refused = await call(f, 'put_page', { slug: 'notes/old-consumer', content: page('Old consumer', 'refused') });
+ expect(refused.isError).toBe(true);
+ expect(refused.body.code).toBe('worktree_refreshing');
+ expect(await f.requestCount()).toBe(before);
+ await f.engine.executeRaw("DELETE FROM persistence_consumers WHERE nonce='old-binary-example'");
+ });
+ expect((await refresh).status).toBe('completed');
+}), 180_000);
+
+test('with the barrier off a write during a refresh is still refused worktree_refreshing', () => each(async f => {
+ process.env.GBRAIN_REFRESH_BARRIER = '0'; resetWriteSwitches();
+ const refresh = await duringRefresh(f, async () => {
+ const out = await call(f, 'put_page', { slug: 'notes/off', content: page('Off', 'refused') });
+ expect(out.isError).toBe(true);
+ expect(out.body.code).toBe('worktree_refreshing');
+ });
+ expect((await refresh).status).toBe('completed');
+}), 180_000);