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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 ENDFROM 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.tsindex 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_maxexport 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.tsindex 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: Recovisibility, ...(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: 'foconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 fLEFT 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?: streturn { 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.tsindex 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.tsnew file mode 100644index 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);