Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
35.6 KB
Raw Blame
import { PENDING_IMPORT, pendingImportRefusal } from './pending-import.ts';
import { deferredWaiting } from './refresh-barrier.ts';
import { withSupersedes } from './import-deferral.ts';
import { withAdoptedLocalEdit } from './local-edit-adoption.ts';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { OperationError } from '../ops/contract.ts';
import { isPhysicalRootDirectoryChangedMessage, relocatedRootTransferFix } from './physical-root-record.ts';
import { LANE_BUSY, PersistenceConsumer, type PersistenceConsumerLike, type PrepareMutation } from './consumer.ts';
import { WaiterOnlyConsumer, type ElectedOwner } from './consumer-election.ts';
import { RESIDENT_CONSUMER_KINDS, startConsumerHeartbeat, type ConsumerHeartbeat } from './consumer-heartbeat.ts';
import { enginePoolStats } from '../postgres-engine/pool-stats.ts';
import { claimOwnerKind, isOneShotCommand } from './claim-phase.ts';
import { noteDirectPoolLease } from '../direct-pool-profile.ts';
import { withEngineScope } from '../engine-scope.ts';
import { preparePageMutation } from './page-prepare.ts';
import { withChangeReason } from './change-reason.ts';
import { withValidTimeAdvisory } from './valid-time-advisory.ts';
import { prepareSemanticPageMutation } from './semantic-pages.ts';
import { getWriteRequestById, getWriteRequestProgress, receiptFor, type WriteRequestProgress } from './journal.ts';
import { OWNER_READ_BUDGET_MS, startOwnerRead, type OwnerActivity } from './owner-activity.ts';
import { isTerminal, type WriteRequest } from './model.ts';
import { isWriteErrorCode, type WriteReceipt } from './types.ts';
import { registerPgliteReopen } from '../pglite-lifecycle.ts';
import { hostIdFor } from './identity.ts';
import { assertMutationProtocol } from './protocol.ts';
import { writeSwitchOn } from './switches.ts';
import { pendingWriteHint } from './health.ts';
import { enterClaimStep, type ClaimPhaseClock } from './claim-phase.ts';
import { receiptDeliveredHint } from './connector-errors.ts';
import type { PgAccessReason } from '../pg-access-classify.ts';
import { contentRefusalFromReceipt } from '../import-screen.ts';
import { fenceIssuesFromDetail, fenceLocationFromDetail } from '../fence-repair/refusal.ts';
import { withdrawnFromDetail } from '../facts/withdrawal.ts';
import { heldFileDiagnostic, storedCheckoutRefusal } from './verb-errors.ts';
import { isMissingPageMessage } from './page-identity.ts';
import { registerPersistenceConsumerConfig } from '../embedding-disabled.ts';

interface Service { consumer: PersistenceConsumerLike; heartbeat?: ConsumerHeartbeat; stopping: boolean; unregisterStop?: () => void; unregisterReopen?: () => void; }
const services = new WeakMap<BrainEngine, Service>();
type ProgressRead = { row: WriteRequestProgress | null } | { error: unknown } | { cancelled: true };
const receiptReads = new WeakMap<BrainEngine, Map<string, { read: Promise<ProgressRead>; abort: AbortController }>>();
const settledWaiters = new WeakMap<BrainEngine, Map<string, Set<(row: WriteRequest) => void>>>();
/**
 * Requests this process's consumer settled most recently. A waiter that registers after its write already
 * settled (a caller that admits a window, then waits on each in turn) missed the handoff, so it reads at once
 * instead of sleeping through the first poll.
 */
const recentlySettled = new WeakMap<BrainEngine, Set<string>>();
const RECENTLY_SETTLED_IDS = 1024;
/** #6007: when this process last settled requests, for pending retry_after_ms estimates. */
const settlements = new WeakMap<BrainEngine, number[]>();
const SETTLEMENT_SAMPLES = 21;
function rememberSettled(engine: BrainEngine, id: string): void {
  let ids = recentlySettled.get(engine);
  if (!ids) { ids = new Set(); recentlySettled.set(engine, ids); }
  ids.add(id);
  if (ids.size > RECENTLY_SETTLED_IDS) ids.delete(ids.values().next().value!);
}
function recordSettlement(engine: BrainEngine): void {
  let times = settlements.get(engine);
  if (!times) { times = []; settlements.set(engine, times); }
  times.push(performance.now());
  if (times.length > SETTLEMENT_SAMPLES) times.shift();
}
/**
 * #6007: a pending receipt's retry_after_ms from this process's recent pace:
 * `remaining` requests at the median gap between settlements, clamped to
 * 250 ms-30 s. Null until this process has settled at least two requests.
 */
export function estimatedRetryAfterMs(engine: BrainEngine, remaining: number): number | null {
  const times = settlements.get(engine) ?? [];
  if (times.length < 2 || remaining <= 0) return null;
  const gaps = times.slice(1).map((at, i) => at - times[i]!).sort((a, b) => a - b);
  return Math.round(Math.min(30_000, Math.max(250, gaps[Math.floor(gaps.length / 2)]! * remaining)));
}
const preparers = new Map<string, { prepare: PrepareMutation; target: 'page' | 'skill_bundle' }>();
export function registerMutationPreparer(operation: string, prepare: PrepareMutation, target: 'page' | 'skill_bundle' = 'page'): void {
  preparers.set(operation, { prepare, target });
}
/**
 * `signal` is the foreground (remember/put_page/edit_page) statement signal, as before; `clock` (#6278) is the claim's
 * phase clock, which carries the preparation's cancellation to every preparer's `enterClaimStep` boundaries.
 */
export async function preparePersistedMutation(e: BrainEngine, row: WriteRequest, cfg: GBrainConfig, signal?: AbortSignal, clock?: ClaimPhaseClock) {
  // GST-1601: a write prepared again after its page's local edit was adopted names the adoption on its receipt.
  return withAdoptedLocalEdit(row, await prepareByOperation(e, row, cfg, signal, clock));
}
async function prepareByOperation(e: BrainEngine, row: WriteRequest, cfg: GBrainConfig, signal?: AbortSignal, clock?: ClaimPhaseClock) {
  assertMutationProtocol(row);
  enterClaimStep(clock, 'dispatch');
  const registered = preparers.get(row.operation);
  if (registered) {
    if (registered.target !== (row.target_kind ?? 'page')) throw new OperationError('unsupported_mutation_protocol', 'The registered preparer does not support this mutation target.', `Request ${row.request_id} (${row.operation}) was accepted by a gbrain version whose preparer this one lacks, so it has not run. Run gbrain upgrade on every host that serves this brain; the request stays journaled and resumes after the upgrade.`);
    return registered.prepare(e, row, cfg, signal, clock);
  }
  if (row.target_kind === 'skill_bundle') {
    if (['put_skill', 'delete_skill'].includes(row.operation)) return (await import('../shared-skills/publication.ts')).prepareSharedSkillMutation(e, row, cfg);
    throw new OperationError('unsupported_mutation_protocol', 'No compatible skill mutation preparer is registered.', `Request ${row.request_id} (${row.operation}) was accepted by a gbrain version whose preparer this one lacks, so it has not run. Run gbrain upgrade on every host that serves this brain; the request stays journaled and resumes after the upgrade.`);
  }
  if (row.operation === 'submit_job' && String(row.intent?.kind).startsWith('managed_atom_')) return (await import('./atom-maintenance.ts')).prepareManagedAtomMutation(e, row, cfg);
  if (row.operation === 'submit_job' && row.intent?.kind === 'managed_generation_activate') return (await import('../generations/managed.ts')).prepareGenerationActivation(e, row);
  if (row.operation === 'submit_job' && row.intent?.kind === 'managed_generation_restore') return (await import('../generations/repair.ts')).prepareGenerationRestore(e, row);
  if (row.operation === 'submit_job' && row.intent?.kind === 'managed_generation_retire') return (await import('../generations/managed-retire.ts')).prepareGenerationRetireMember(e, row, cfg);
  if (row.operation === 'extract_facts' && String(row.intent?.kind).startsWith('managed_facts_')) return (await import('./facts-prepare.ts')).prepareManagedFactsMutation(e, row, cfg);
  if (row.operation === 'submit_job' && String(row.intent?.kind).startsWith('connector_v2_')) return (await import('./connector-sync.ts')).prepareConnectorMutation(e, row);
  if (row.operation === 'submit_job' && String(row.intent?.kind).startsWith('managed_connector_')) return (await import('./connector-sync.ts')).prepareOutdatedConnectorMutation(e, row);
  if (row.operation === 'put_page' && row.intent?.kind === 'canonical_reconcile') return (await import('./reconcile-prepare.ts')).prepareReconcileMutation(e, row, cfg);
  if (row.operation === 'put_page' && row.intent?.kind === 'managed_grandfather') return (await import('./grandfather.ts')).prepareGrandfatherMutation(e, row);
  if (row.operation === 'submit_job' && row.intent?.kind === 'code_projection_reindex') return (await import('./projection-reindex.ts')).prepareCodeReindex(e, row);
  if (row.operation === 'submit_job' && String(row.intent?.kind).startsWith('managed_sync_')) return (await import('./sync-prepare.ts')).prepareManagedSyncMutation(e, row, cfg, clock);
  if (row.operation === 'submit_job' && String(row.intent?.kind).startsWith('managed_maintenance_')) return (await import('./prepared-maintenance.ts')).prepareMaintenanceMutation(e, row, cfg, clock);
  if (row.operation === 'put_page' && row.intent?.kind === 'managed_file_import') return (await import('./import-prepare.ts')).prepareManagedImportMutation(e, row, cfg);
  if (row.operation === 'put_page' && row.intent?.kind === 'managed_file_repair') return (await import('./file-repair.ts')).prepareManagedFileRepairMutation(e, row, cfg);
  if (row.operation === 'remember') return (await import('./memory-mutations.ts')).prepareMemoryMutation(e, row, cfg, signal, clock);
  if (row.operation === 'forget' || row.operation === 'forget_fact') return (await import('./forget-prepare.ts')).prepareForgetMutation(e, row, cfg, signal);
  if (row.operation === 'loops_close' && row.intent?.kind === 'retire_loop_fact') return (await import('./loop-fact-retirement.ts')).prepareLoopFactRetirement(e, row, cfg);
  if (row.operation === 'decide_proposal') return (await import('../facts/proposal-supersede.ts')).prepareProposalMutation(e, row, cfg);
  if (row.operation === 'trust_owner_page') return (await import('../trust/page-handlers.ts')).prepareTrustOwnerPageMutation(e, row, cfg);
  if (row.operation === 'trust_release') return (await import('../trust/release-publish.ts')).prepareTrustReleaseMutation(e, row, cfg);
  if (row.operation === 'relink_facts') return (await import('../facts/relink-publish.ts')).prepareRelinkMutation(e, row, cfg);
  if (['takes_add','takes_update','takes_supersede','takes_resolve','takes_remove'].includes(row.operation)) return (await import('./takes-prepare.ts')).prepareTakesMutation(e,row,cfg);
  if (['add_tag','remove_tag','add_timeline_entry'].includes(row.operation)) return prepareSemanticPageMutation(e, row, cfg);
  if (row.operation === 'add_link' || row.operation === 'remove_link') return (await import('./manual-links.ts')).prepareManualLinkMutation(e, row, cfg);
  if (row.operation === 'append_page') return (await import('./page-upload.ts')).withStagedBodyIf(e, row, async () => (await import('./page-append.ts')).prepareAppendMutation(e, row, cfg, signal, clock));
  if (['put_page','capture','delete_page','restore_page','revert_version','edit_page'].includes(row.operation)) return withValidTimeAdvisory(row, withChangeReason(row, await withSupersedes(row, await preparePageMutation(e, row, cfg, undefined, signal,
    { coordinated: await writeSwitchOn(e, 'single_write_group').catch(() => true), clock, boundedChunkWrites: true }))));
  throw new OperationError('unsupported_mutation_protocol', 'No compatible mutation preparer is registered for this operation.', `Request ${row.request_id} (${row.operation}) was accepted by a gbrain version whose preparer this one lacks, so it has not run. Run gbrain upgrade on every host that serves this brain; the request stays journaled and resumes after the upgrade.`);
}
/**
 * #6317 (B1): starts this process's consumer, synchronously. A `serve` and every short-lived foreground command (`put`,
 * `import`, `cli`, ...) get a full consumer at once, with its heartbeat row; the other resident kinds (`sync`, `jobs`,
 * `autopilot`, `mcp`) get a `WaiterOnlyConsumer` that probes the host's consumer rows on its first tick and settles to
 * full or waiter-only (consumer-election.ts). Either way the returned object has the consumer's whole surface.
 */
export function startPersistenceConsumer(engine: BrainEngine, config: GBrainConfig): PersistenceConsumerLike {
  const prior = services.get(engine);
  if (prior) {
    if (prior.stopping) {
      throw new OperationError('unavailable', 'The persistence owner is closing.',
        'The persistence owner in this process is shutting down; start the command again after it exits. Accepted writes stay journaled and resume on the next owner.');
    }
    return prior.consumer;
  }
  noteDirectPoolLease();
  const kind = claimOwnerKind();
  const oneShot = isOneShotCommand() && kind !== 'serve' && !RESIDENT_CONSUMER_KINDS.includes(kind) ? { waiting: () => (settledWaiters.get(engine)?.size ?? 0) > 0 } : undefined;
  const full = () => new PersistenceConsumer(engine, config, preparePersistedMutation,
    { drainNotice: kind === 'serve', oneShot, onSettled: row => { recordSettlement(engine); rememberSettled(engine, row.id); for (const listener of settledWaiters.get(engine)?.get(row.id) ?? []) listener(row); } });
  const service: Service = kind !== 'serve' && RESIDENT_CONSUMER_KINDS.includes(kind) && engine.kind === 'postgres'
    ? { consumer: new WaiterOnlyConsumer(engine, config, full, { kind, hostId: hostIdFor(engine), pool: () => enginePoolStats(engine) }), stopping: false }
    : (() => { const consumer = full(); return { consumer, stopping: false, heartbeat: startConsumerHeartbeat(engine, consumer.hostId,
        // #6317 (C1): the row's pool numbers come from the vendored driver's own queues (postgres-engine/pool-stats.ts).
        { kind, mode: 'full', report: () => ({ restart_required: consumer.restartRequired(), root_barrier_age_ms: consumer.oldestRootBarrierAgeMs(), pool: enginePoolStats(engine) }) }) }; })();
  const { consumer } = service;
  services.set(engine, service);
  const lifecycle = engine as BrainEngine & { registerBeforeDisconnect?: (run: () => Promise<void>) => unknown };
  const unregister = lifecycle.registerBeforeDisconnect?.(() => stopPersistenceConsumer(engine));
  if (typeof unregister === 'function') service.unregisterStop = unregister;
  if (engine.kind === 'pglite') service.unregisterReopen = registerPgliteReopen(engine, sameDatastore => {
    if (services.get(engine) !== service || !service.stopping) return;
    discardStoppedService(engine, service);
    // An explicit switch to another datastore must not inherit the old brain's config.
    if (sameDatastore) startPersistenceConsumer(engine, config);
  });
  // The consumer's publications (embeddings included) run in its engine's scope (engine-scope.ts).
  withEngineScope(engine, () => consumer.start());
  return consumer;
}
export async function stopPersistenceConsumer(engine: BrainEngine): Promise<void> {
  const service = services.get(engine);
  if (!service) return;
  service.stopping = true;
  const pending = [...(receiptReads.get(engine)?.values() ?? [])];
  for (const entry of pending) entry.abort.abort();
  // GBRA-156: a one-shot command's housekeeping runs here, after its reply and before its consumer stops.
  if (service.consumer instanceof PersistenceConsumer) await service.consumer.runOneShotHousekeeping();
  await service.consumer.stop();
  await service.heartbeat?.stop();
  await Promise.all(pending.map(entry => entry.read));
}
/** #6317: the owner a waiter-only consumer in this process defers to, for the `writer_pending` envelope; null when this process consumes itself. */
export function waiterOnlyOwner(engine: BrainEngine): ElectedOwner | null {
  const consumer = services.get(engine)?.consumer;
  return consumer instanceof WaiterOnlyConsumer && consumer.mode === 'waiter_only' ? consumer.electedOwner() : null;
}
/** Reset fixtures and drained lifecycle owners may discard a stopped service. */
export async function disposePersistenceConsumer(engine: BrainEngine): Promise<void> {
  const service = services.get(engine);
  await stopPersistenceConsumer(engine);
  if (service && services.get(engine) === service) discardStoppedService(engine, service);
}
function discardStoppedService(engine: BrainEngine, service: Service): void {
  service.unregisterStop?.(); service.unregisterReopen?.(); services.delete(engine);
}
/**
 * Phase 4.4: runs `run` on this process's warm single-write lane (consumer.ts `onLane`) when its
 * consumer is running and the lane is free; otherwise `fallback()`, on the pool.
 */
export async function onPersistenceLane<T>(engine: BrainEngine,
  run: (transaction: <R>(fn: (tx: BrainEngine) => Promise<R>) => Promise<R>) => Promise<T>, fallback: () => Promise<T>): Promise<T> {
  const service = services.get(engine);
  if (!service || service.stopping) return fallback();
  const done = await service.consumer.onLane(run);
  return done === LANE_BUSY ? fallback() : done;
}
export function foregroundWriteCompletions(engine: BrainEngine, worktreeId: string): number {
  return services.get(engine)?.consumer.foregroundCompletions(worktreeId) ?? 0;
}
/** The config this process's consumer prepares writes with (its first caller's); undefined when none is running. */
export function persistenceConsumerConfig(engine: BrainEngine): GBrainConfig | undefined {
  const service = services.get(engine);
  return service && !service.stopping ? service.consumer.config : undefined;
}
registerPersistenceConsumerConfig(persistenceConsumerConfig);
export function persistenceConsumerStatus(engine: BrainEngine) {
  const service = services.get(engine);
  return service ? { state: service.stopping ? 'closing' : 'open', ...service.consumer.status() }
    : { state: 'not_running', accepting: false, active_preparations: 0, active_worktrees: 0 };
}
export function assertPersistenceAccepting(engine: BrainEngine): void {
  if (services.get(engine)?.stopping) {
    throw new OperationError('unavailable', 'The persistence owner is closing. Retry the same request_id after restart.',
      'Nothing new was accepted. After the owner restarts, resubmit with the same request_id so a write that was already accepted is never applied twice.');
  }
}
/** DX-A3: pending heads that need intervention, not more waiting. */
export const BLOCKED_WRITE_REASONS = ['recovery_required', 'owner_unavailable', 'unexpected_file_bytes', 'unexpected_staging_bytes'] as const;
const FATAL_READ_REASONS: readonly PgAccessReason[] = ['auth_failed', 'permission_denied', 'tenant_not_found', 'db_missing', 'schema_missing', 'storage_corrupt', 'tls_required_default'];
/** CEO-A7: the first poll waits this long (at most half the wait) for an in-process handoff, or not at all when this process already settled the request; later polls back off from 50 to 250 ms. */
export const WRITE_POLL_START_MS = 200;
export type WriteWait =
  | { kind: 'terminal' | 'pending'; row: WriteRequest }
  | { kind: 'blocked'; row: WriteRequest; request_id: string; cause: typeof BLOCKED_WRITE_REASONS[number]; command: string }
  | { kind: 'read_failed'; row: WriteRequest; request_id: string; reason: PgAccessReason; transient: boolean; sqlstate?: string;
      attempts: number; message: string; why: string };
/**
 * Waits for an admitted write and classifies how the wait ended. A request this
 * process publishes is handed over by its consumer without a read; otherwise a
 * narrow progress read polls, and the full row is read once when terminal. The
 * waiter's own cancelled reads are not failures; database read failures are
 * classified (`read_failed`) instead of reading as a still-pending write.
 * The waiter never owns a provider, database connection, or kernel lock.
 */
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 (GST-1582: or an import not landed) cannot publish before it ends,
  // so its pending receipt is returned at once.
  if (row.state === 'deferred' && await deferredWaiting(engine, row)) return { kind: 'pending', row };
  const consumer = startPersistenceConsumer(engine, config);
  const service = services.get(engine)!;
  const id = row.id;
  let handed: WriteRequest | undefined;
  let wake: (() => void) | undefined;
  let waiters = settledWaiters.get(engine);
  if (!waiters) { waiters = new Map(); settledWaiters.set(engine, waiters); }
  const listeners = waiters.get(id) ?? new Set();
  const listener = (settled: WriteRequest) => { handed = settled; wake?.(); };
  listeners.add(listener); waiters.set(id, listeners);
  // The admission transaction has committed: publish now, not after the idle backoff.
  consumer.wake(true);
  const waitMs = opts.waitMs ?? 5000;
  const started = performance.now();
  // `whileHeldMs`: past `waitMs`, keep waiting (to that total) while this process's consumer is executing the request or it
  // is still queued unblocked: a consumer busy past `waitMs` (an effect pass under load) has not claimed it yet.
  let deadline = started + waitMs;
  const firstPoll = recentlySettled.get(engine)?.has(id) ? 0 : Math.min(WRITE_POLL_START_MS, waitMs / 2);
  let delay = firstPoll, failure: { error: unknown; attempts: number } | undefined;
  // GBRA-248: owner facts for a write that may be left pending or blocked, read during the wait's last OWNER_READ_BUDGET_MS (a
  // shorter wait is extended to that budget); waiters on one worktree share the read and reuse its answer (sharedOwnerRead).
  let ownerRead: SharedOwnerRead | undefined;
  try {
    while (!service.stopping && !opts.signal?.aborted) {
      if (handed) {
        row = handed; handed = undefined;
        if (isTerminal(row)) return { kind: 'terminal', row };
        if (row.state === 'deferred' && await deferredWaiting(engine, row)) return { kind: 'pending', row };
      }
      const remaining = deadline - performance.now();
      if (!ownerRead && row.worktree_id && remaining <= OWNER_READ_BUDGET_MS) ownerRead = sharedOwnerRead(engine, row.worktree_id);
      if (remaining <= 0) {
        if (opts.whileHeldMs && opts.whileHeldMs > waitMs && deadline === started + waitMs
          && (consumer.holds(id) || row.state === 'queued' && !row.blocked_reason)) { deadline = started + opts.whileHeldMs; continue; }
        break;
      }
      await new Promise<void>(resolve => {
        const done = () => { clearTimeout(timer); wake = undefined; opts.signal?.removeEventListener('abort', done); resolve(); };
        const timer = setTimeout(done, Math.min(delay, remaining));
        wake = done; opts.signal?.addEventListener('abort', done, { once: true });
      });
      if (handed || service.stopping || opts.signal?.aborted || performance.now() >= deadline) continue;
      delay = delay === firstPoll ? 50 : Math.min(250, delay * 2);
      if (consumer.holds(id)) continue;
      const read = await readProgress(engine, id, deadline - performance.now());
      if ('cancelled' in read) continue;
      if ('error' in read) {
        failure = { error: read.error, attempts: (failure?.attempts ?? 0) + 1 };
        const { classifyPgAccessError } = await import('../pg-access-classify.ts');
        if (FATAL_READ_REASONS.includes(classifyPgAccessError(read.error).reason)) break;
        continue;
      }
      failure = undefined;
      if (!read.row) continue;
      row = { ...row, ...read.row };
      if (isTerminal(row)) return { kind: 'terminal', row: await getWriteRequestById(engine, id).catch(() => null) ?? row };
      if (row.state === 'deferred' && await deferredWaiting(engine, row)) return { kind: 'pending', row: await getWriteRequestById(engine, id).catch(() => null) ?? row };
    }
    // A stopped wait settles only what this process can settle at once: one consumer tick (it claims and publishes the
    // request when nothing holds it back) and the request this consumer is still executing. A write that cannot move
    // (another owner's lock, a consumer that defers to another process) is left queued under its request id.
    if (opts.signal?.aborted && !service.stopping && !handed) {
      const left = () => deadline - performance.now();
      await Promise.race([consumer.tick().catch(() => undefined), new Promise<void>(resolve => setTimeout(resolve, Math.max(0, left())))]);
      while (!handed && consumer.holds(id) && left() > 0) {
        await new Promise<void>(resolve => {
          const done = () => { clearTimeout(timer); wake = undefined; resolve(); };
          const timer = setTimeout(done, Math.min(50, left()));
          wake = done;
        });
      }
    }
  } finally {
    listeners.delete(listener);
    if (!listeners.size && waiters.get(id) === listeners) waiters.delete(id);
  }
  if (handed) row = handed;
  // A stopped wait then reads the receipt once, so a write that committed meanwhile is banked rather than reported pending.
  if (!isTerminal(row) && opts.signal?.aborted && !service.stopping) {
    const latest = await getWriteRequestProgress(engine, id).catch(() => null);
    if (latest) row = { ...row, ...latest };
    if (isTerminal(row)) return { kind: 'terminal', row: await getWriteRequestById(engine, id).catch(() => null) ?? row };
  }
  if (isTerminal(row)) return { kind: 'terminal', row };
  if (failure) {
    const { classifyPgAccessError } = await import('../pg-access-classify.ts');
    const diagnosis = classifyPgAccessError(failure.error);
    return { kind: 'read_failed', row, request_id: row.request_id, reason: diagnosis.reason, transient: diagnosis.transient,
      ...(diagnosis.sqlstate ? { sqlstate: diagnosis.sqlstate } : {}), attempts: failure.attempts, message: diagnosis.message, why: diagnosis.remediation };
  }
  // GBRA-248: a write left pending or blocked names a stale owner, so the receipt (and --accept-pending) can tell it from a slow commit.
  if (row.worktree_id) {
    const owner = await (ownerRead ?? sharedOwnerRead(engine, row.worktree_id)).answer();
    if (owner) observedOwners.set(row, owner);
  }
  const cause = BLOCKED_WRITE_REASONS.find(reason => reason === row.blocked_reason);
  if (cause) return { kind: 'blocked', row, request_id: row.request_id, cause, command: `gbrain sources writer status ${row.source_id} --json` };
  return { kind: 'pending', row };
}
/** At most four progress reads per engine; concurrent waiters on one request share a read. */
async function readProgress(engine: BrainEngine, id: string, remaining: number): Promise<ProgressRead> {
  let reads = receiptReads.get(engine);
  if (!reads) { reads = new Map(); receiptReads.set(engine, reads); }
  let pending = reads.get(id);
  const ownsRead = !pending;
  if (!pending) {
    if (reads.size >= 4) return { cancelled: true };
    const abort = new AbortController();
    const shared = reads;
    const read: Promise<ProgressRead> = getWriteRequestProgress(engine, id, engine.kind === 'postgres' ? abort.signal : undefined)
      .then(row => ({ row }), error => abort.signal.aborted ? { cancelled: true as const } : { error })
      .finally(() => { if (shared.get(id)?.read === read) shared.delete(id); });
    pending = { read, abort };
    reads.set(id, pending);
  }
  const owned = pending;
  let timer: ReturnType<typeof setTimeout> | undefined;
  return Promise.race([owned.read, new Promise<ProgressRead>(resolve => {
    timer = setTimeout(() => { if (ownsRead) owned.abort.abort(); resolve({ cancelled: true }); }, remaining);
  })]).finally(() => { if (timer) clearTimeout(timer); });
}
/** Compatibility form of `awaitWrite`: the latest row, terminal or still pending. */
export async function waitForWrite(engine: BrainEngine, row: WriteRequest, config: GBrainConfig, waitMs = 5000): Promise<WriteRequest> {
  return (await awaitWrite(engine, row, config, { waitMs })).row;
}
/**
 * #6007: wait for several admitted writes against one deadline. Every row waits at once, so each one's consumer handoff is registered
 * before a grouped publication settles them together; waiting one after
 * another left all but the first to the progress polls.
 */
export async function waitForWrites(engine: BrainEngine, rows: readonly WriteRequest[], config: GBrainConfig, waitMs = 5000): Promise<WriteRequest[]> {
  return Promise.all(rows.map(row => waitForWrite(engine, row, config, waitMs)));
}
/** B4: what a terminal receipt means for the caller, without guessing a mutation. */
function terminalReceiptHint(row: WriteRequest, reason: string): string {
  const what = `The ${row.operation ? `${row.operation} ` : ''}write (request_id ${row.request_id}) ended ${row.state} with ${reason}; it will not publish.`;
  return row.state === 'cancelled'
    ? `${what} Submit again only if the change is still wanted, with a new request_id.`
    : `${what} Read the receipt and the current state before deciding to submit again; a new attempt needs a new request_id.`;
}
/** GBRA-248: owner facts awaitWrite observed for a row it left pending (by identity; the row object travels to writeResponse unchanged). */
const observedOwners = new WeakMap<WriteRequest, OwnerActivity>();
/** GBRA-248: staleness moves on a 24 h scale, so an owner answer is reused for a few seconds and a batch of waiters pays one read. */
const OWNER_CACHE_MS = 10_000;
interface SharedOwnerRead { at: number; answer(): Promise<OwnerActivity | undefined> }
const ownerReads = new WeakMap<BrainEngine, Map<string, SharedOwnerRead>>();
/** One owner read per engine and worktree at a time; it answers within OWNER_READ_BUDGET_MS of its start (undefined: no stale-owner facts). */
function sharedOwnerRead(engine: BrainEngine, worktreeId: string): SharedOwnerRead {
  let reads = ownerReads.get(engine);
  if (!reads) { reads = new Map(); ownerReads.set(engine, reads); }
  const current = reads.get(worktreeId);
  if (current && performance.now() - current.at < OWNER_CACHE_MS) return current;
  const at = performance.now();
  const settled = startOwnerRead(engine, [worktreeId])(OWNER_READ_BUDGET_MS).then(owners => {
    if (!owners && reads!.get(worktreeId) === read) reads!.delete(worktreeId);
    return owners?.get(worktreeId);
  });
  const read: SharedOwnerRead = { at, answer: () => settled };
  reads.set(worktreeId, read);
  return read;
}
export function writeResponse(row: WriteRequest, hints: { retryAfterMs?: number | null; waiterOnlyOwner?: ElectedOwner | null } = {}): Record<string, unknown> {
  const owner = isTerminal(row) ? undefined : observedOwners.get(row);
  const receipt = receiptFor(row, owner ? { owner } : undefined);
  // #6007: an in-process estimate beats the fixed fallback, never an owner-inspection hold.
  if (!isTerminal(row) && hints.retryAfterMs != null && receipt.diagnostic?.next_action !== 'inspect_owner') receipt.retry_after_ms = hints.retryAfterMs;
  if (row.state === 'committed') return { ...receipt, write_request: receipt };
  const reason = !isTerminal(row) ? 'write_pending' : row.error_code ?? (row.state === 'cancelled' ? 'cancelled' : 'storage_error');
  const delivered = isTerminal(row) ? receiptDeliveredHint(row) : null;
  // #5988: a content refusal reports its typed code, reason, key and line, and the content fix.
  const content = isTerminal(row) ? contentRefusalFromReceipt(row.error_code, row.error_message) : null;
  // The page's file is held by sync: name the repair, so the caller does not retry into the same refusal.
  const held = isTerminal(row) && reason === 'source_changed' ? heldFileDiagnostic(row.error_message, row.source_id) : null;
  const error = new OperationError(reason, !isTerminal(row) ? 'The write is accepted and is still pending.'
    : row.error_message ?? 'The write did not commit.', !isTerminal(row)
      ? pendingWriteHint(receipt, row.operation)
      : delivered?.suggestion ?? content?.suggestion ?? held?.suggestion ?? terminalReceiptHint(row, reason), delivered?.docs);
  if (delivered?.detail ?? held?.reason) error.detail = delivered?.detail ?? held?.reason;
  // #7671: a copied or restored checkout; the receipt kept only the message, so name the relocated-root self-transfer here.
  if (isTerminal(row) && reason === 'recovery_required' && isPhysicalRootDirectoryChangedMessage(row.error_message)) {
    Object.assign(error, { detail: 'physical_root_directory_changed', fix: relocatedRootTransferFix(row.source_id) });
  }
  // #6693: a write refused while its page's file awaited import says so, with the wait (remember) or the sync to run first.
  if (isTerminal(row) && reason === 'source_changed' && (row.error_detail as { origin?: unknown } | null | undefined)?.origin === PENDING_IMPORT) {
    const pending = pendingImportRefusal(row, row.authority?.remote === true);
    Object.assign(error, { suggestion: pending.suggestion, fix: pending.fix, reason: pending.reason, detail: pending.detail, docs: pending.docs ?? error.docs });
  }
  const checkout = isTerminal(row) ? storedCheckoutRefusal((row.error_detail as { origin?: unknown } | null | undefined)?.origin, row.source_id, row.slug || null) : undefined;
  if (checkout) Object.assign(error, { suggestion: checkout.suggestion, fix: checkout.fix, detail: checkout.detail, docs: checkout.docs });
  // GST-2462 (D2): a page whose file left git can still be narrowed: name the page rule, not only the ghost-page repair (which deletes it).
  if (isTerminal(row) && reason === 'source_changed' && (row.error_detail as { origin?: unknown } | null | undefined)?.origin === 'canonical_file_missing') error.suggestion = `${error.suggestion} The page's file is gone, so a visibility edit cannot publish; to narrow who reads it without restoring the file, add a page rule on the brain host: gbrain access rule add --slug ${row.slug} --readers <member> --source ${row.source_id} (it previews; --yes applies, and removing the rule undoes it). See docs/guides/write-refusals.md#canonical_file_missing.`;
  // #6317 (B1b): a waiter-only process names the owner that publishes for it, so the caller is told who holds the write instead of polling blind.
  if (!isTerminal(row) && hints.waiterOnlyOwner) {
    const owner = hints.waiterOnlyOwner;
    const claim = receipt.diagnostic as { claim?: { stall?: { step?: string | null } } } | undefined;
    error.why = `${error.why} This process runs no consumer of its own: the ${owner.kind} process (pid ${owner.pid}) on this host owns publication${claim?.claim?.stall?.step ? `, and its claim is stalled on step ${claim.claim.stall.step}` : ''}.`;
    error.fix = { argv: ['gbrain', 'sources', 'writer', 'status', '--source', row.source_id, '--json'], consent: [], actor: 'agent', requires_exclusive: false,
      why: 'Read-only: names the owner process, the running claim\'s step and every write waiting behind it.',
      verify: { argv: ['gbrain', 'doctor', '--json'] } };
  }
  if (content) {
    if (content.code !== reason) error.canonical = content.code;
    if (content.reason) error.reason = content.reason;
    // #6188: the stored fence location and blocking issues (the caller's own rows; refused before any merge).
    if (content.code === 'invalid_fence') {
      const fence = fenceLocationFromDetail(row.error_detail) ?? content.fence;
      if (fence) error.fence = { ...fence };
      const issues = fenceIssuesFromDetail(row.error_detail);
      if (issues.length) error.fenceIssues = issues;
    }
    if (content.key || content.line !== undefined) error.detail = [content.key ? `key ${content.key}` : '', content.line !== undefined ? `line ${content.line}` : ''].filter(Boolean).join(', ');
  }
  const withdrawn = isTerminal(row) ? withdrawnFromDetail(row.error_detail) : undefined;
  if (withdrawn) error.withdrawn = withdrawn;
  if (reason === 'page_identity_changed' && isMissingPageMessage(row.error_message)) error.canonical = 'page_not_found';
  error.receiptFields = { operation: row.operation, source_id: row.source_id, slug: row.slug || null, principal_kind: row.principal_kind, principal_id: row.principal_id };
  error.writeRequest = receipt as WriteReceipt;
  error.writeError = isWriteErrorCode(reason) ? reason : reason === 'page_identity_changed' ? 'source_changed' : 'storage_error';
  throw error;
}