Garry's Opinionated OpenClaw/Hermes Agent Brain
Core Persistence: write capacity
Cumulative write caps (permanent request ids, receipt bytes; opt-in since GBRA-108, DEFAULT_JOURNAL_LIMITS holds Infinity and rows of an unset cap are left out of diagnostics, the forecast and repair capacity) and the paths that keep them honest (#6696). Guide: concurrent writes, growth model and quota.
src/core/persistence/receipt-bytes.ts—receiptReservation({intent, authority}, extra): what an admission reserves (serialized intent and authority plusRECEIPT_COMPLETION_BYTES12 KiB, never belowRECEIPT_RESERVATION_FLOOR16 KiB) on single, group and caller-overridden paths (journal.tstakes the larger of a caller's value and the formula);reservationForRetainedis the same estimate from bytes alone (the sync preflight);retainedReceiptBytesis what a terminal or compacted row keeps, shared withintent-redaction.tsand compaction;EFFECT_BYTES_SQLandTRUE_UP_CLAMP_SQL(counts clamped decrements underpersistence.true_up.clamped).src/core/persistence/receipt-true-up.ts—trueUpRequests(engine, ids): after the settling transaction commits, in its own short transaction, locks the brain and principal counters in key order, then a compare-and-set on each request row (stillterminal_reservationas read, no queued or running effect, same effect bytes) shrinks it toretainedReceiptBytesand releases the difference. Idempotent; never touchesupdated_at. Called from the effect runner (effects.ts, every claimed request),embedding-settlement.ts,embedding-noop-settle.ts(theembed --stalebulk settle),effect-retry.ts(reconciled) andbackup/snapshot.ts(restore).test/persistence-true-up-sites.test.tsfails on an effect state-change site that is not wired.sweepCompactedReservationsis the bounded one-shot pass over receipts compacted with their full reservation (cursorpersistence.true_up.compacted_through,doneat the end).src/core/persistence/admission-origin.ts—withAdmissionOrigin('interactive' | 'background')(an outer background scope wins),resolveAdmissionOrigin(unset reads background, never derived fromctx.remote),persistence.capacity.background_pause_pct(default 80) andbackgroundPaused, thewrite_capacity_backpressurerefusal background producers get past the line. A background scope also carries the per-run owner cache (backgroundOwnerCheck);backgroundWorktreeInactive(arecoveringworktree, read under the admission's lock injournal.ts) andbackgroundOwnerUnverifiedrefuseowner_unavailablepre-receipt with the owner-status fix; a draining worktree still admits.src/core/persistence/owner-verification.ts— #6741 C: the claim's owner verification (verifyOwnerRoot: paths recorded, physical root, marker and reservation intact; a device-only change isrestampable), shared by writer onboarding and background admissions;assertBackgroundOwnerrefuses a background admissionowner_unavailableonce per source per run (cache: admission-origin.tsbackgroundOwnerCheck). Tests:test/background-owner-verification.test.ts.src/core/persistence/capacity-forecast.ts—readCapacityForecast: per principal, one statement walkspersistence_requests_principalnewest first untilcreated_atleaves the 7-day window and buckets by day; gross and net (compacted) receipt rates,days_to_exhaustion(at the larger of the 7-day mean and the last 24 hours),basis(:legacy_under_reservedwhile receipts admitted before the intent-sized reservation remain),recommended_limit(one more year at the 7-day mean, GST-2107, so one bulk day is not projected for a year).lightskips the reclaim read and table size. Thresholdspersistence.capacity.warn_days(30) andfail_days(7).src/core/engine-key.ts+src/core/engine-root.ts— the key every per-engine cache uses.engineKey(engine)returns the engine itself through theENGINE_ROOTsymbol (each engine stores itself there; a page-transaction clone inherits it, forwarding proxies and a recovered degraded engine return it), and otherwise walks a page-transaction clone, a read-through view or a statement-deadline wrapper (engineCacheKey) to the engine behind it. A process with mounted brains keeps one entry per brain in the search telemetry writer (getTelemetryWriter(engine)),search.track_retrieval, minion admission policy,mcp.strict_paramslast-known-good, publication ceiling,write_capacity_lowthrottle,search.hnsw_iterative_scanandsearch.vector_legacy_guard, and a transaction or view shares its engine's entry. A one-brain process behaves as before. Test:test/engine-keyed-caches.test.ts.src/core/persistence/capacity-snapshot.ts—cachedCapacitySnapshot: one light forecast per engine per 60 s, shared by every caller;capacityNoticesbuildswrite_capacity_low(kindinfo, muteable; it says it is not a refusal and its fix is the read-only doctor check,get_brain_healthover MCP, GST-2107; hourly per engine and scope on write and sync receipts,scopeslimits a remote caller to the brain and its own principal) andwrite_capacity_backpressure(once per pause start). Read bymcp/dispatch.ts,cli/main.ts,commands/sync/{run,operator}.ts,cycle.tsand the admin/metricsgauges inserve-http-metrics.ts. #6803: the cache keys on the real engine (engineCacheKey), the shared fetch is bounded atCAPACITY_FETCH_BOUND_MS(10 s) and a timed-out fetch is never cached;capacitySnapshotWithin(sync status, write and sync receipts:CAPACITY_READ_WAIT_MS, 1.5 s) returnsunknownfor that call alone, andcapacityNoticeson an unknown snapshot returns no notice and leaves throttle and pause state as it was. Test:test/capacity-bounded-read-6803.test.ts.src/core/persistence/compaction-pass.ts—runCompactionPass, the consumer's idle and volume maintenance:compactWriteReceiptsDetailed,housekeepReceipts(GBRA-108: while receipts not yet compacted reserve more thanpersistence.housekeeping.receipt_target_bytes(limits.tsreadCompactableReceiptBytes; compacted receipts never count) with the default retention, up to 100 receipts older thanHOUSEKEEPING_FLOOR_DAYSthatEARLY_SQLadmits: settled non-job, non-connector writes that are not a subagent's own (restrictedNamespace), and refused maintenance or managed sync page writes; counted asearly; an error counts ashousekeeping_errorand the sweep still runs), one sweep step, and thepersistence.maintenance.last_compactionrecord (at,host_id,compacted,freed_bytes,skipped_by_reason). Each step resumes from the timer queue (journal.tsyieldToEventLoop), as do the consumer's maintenance chain, the per-table queueVACUUMand the effects drain passes (NOOP_SETTLE_BATCH50), so on PGLite a request waits behind one step at most. The retention pass (compactWriteReceiptsDetailed) skipsterminal-classify.tsUNRESOLVED_CALLER_REFUSAL_SQL(a caller refusalrepair failed-writescould still replay, GBRA-108).journal.tscompactReceiptcompacts one receipt in its own transaction (counters first,lock_timeout2 s,statement_timeout15 s) and skips open managed-sync runs (OPEN_SYNC_CURSOR_EXCLUSION) and the newest sync receipt per worktree (newestSyncReceipt).src/core/repair/receipt-compaction.ts—gbrain repair receipt-compaction: explicit-only, preview-bound, destructive consent,publication: 'projection';--older-than(thepages purge-deletedgrammar) floored at the configured retention unless--force, committed only unless--include-failures; the approved set binds an absolute cutoff and the newest sequence. Test:test/repair-receipt-compaction.test.ts.src/core/persistence/refusal-breaker.ts—assertRefusalBreakerClosed:submitMaintenancerefuses before admission afterpersistence.maintenance.refusal_breaker_threshold(3; 0 off) same-code terminal refusals in 24 h for the same requestdigest(source, slug, intent with its revision and planner);listSuppressedWritesfeeds doctormaintenance_write_drift. The ghost case (canonical_file_missing, tagged bypage-prepare.ts, kept inerror_detail.origin, returned byliveFileDrift) refuses before admission inprepared-maintenance.ts. Test:test/maintenance-ghost-breaker-6696.test.ts.- Sync:
sync-run.tspreflightSyncCapacityrefuseswrite_quota_insufficientbefore a run's first admission;sync-drain.tsstops a later cap refusalresumable/capacity_paused(drain.capacity_pause). Test:test/sync-capacity-preflight.test.ts. - Doctor:
persistence_capacity(forecast of set caps; with none set, receipt storage against the housekeeping target, an operator warning that never blocks a write;test/persistence-opt-in-caps.test.ts),persistence_compactionandpersistence_counter_drift(src/commands/doctor/checks/persistence-compaction.ts; one-statement comparison of counters with request and lifecycle reservations). Test:test/doctor-persistence-compaction.test.ts.
Publication cost
What a managed publish costs in statements and round trips, and how it is measured (#6712 PR 3). Budgets: test/managed-import-statement-budget.test.ts (PGLite) and test/e2e/managed-import-statement-budget.test.ts (Postgres wire trace) count one YC-shaped page's publication transaction; test/sync-status-statement-budget.test.ts holds sync status to a fixed statement count at 61,000 receipts. Helpers: test/helpers/yc-shaped-page.ts, statement-counter.ts, managed-import-budget.ts, latency-proxy.ts.
src/core/persistence/publication-timing.ts(#6712 L6) —timePublicationStep('apply' | 'effects', slug, run)wraps a publication member's apply and itsqueuePublicationEffectscall (coordinator.ts,group-publish.ts): process-local totals (publicationStepTotals) for tests and benchmarks, and one[sync] publish <step> <slug>: Nmsline on stderr only underGBRAIN_SYNC_TRACE. It measures and never changes the outcome (a throwing step is timed and rethrown).addCodeReferenceLinksinsrc/core/engine-sql/links.ts(#6712 L6) — a page's doc↔impl code-reference edges (documentsfrom the page,documented_byback) in one set-based statement: endpoints resolve in the page's source underFOR KEY SHARE, a missing endpoint drops its edge, a repeated edge keeps its last context, and a re-import updates context and origin field in place.import-file.tsandpage-body/streamed-import.tscall it once per page inside a savepoint (a failure leaves the page import intact), where each reference used to cost two sequentialaddLinkstatements.src/core/postgres-engine/pool-stats.ts— #6317 (C1, G1):driverPoolStats(sql)reads the vendored postgres.js driver'ssql.poolgetter (vendor/postgres, patch regenerated) for real{checked_out, max, waiters};enginePoolStats(engine)labels the source (driverortracked_subsetfrompool-gauge.ts). Filled into the heartbeat row,writer statusrunning claims andgetPoolDiagnostics().src/core/persistence/maintenance-wait.ts— how long a maintenance publisher waits for its accepted write to commit before the receipt reportswrite_pending(#5854).MAINTENANCE_WRITE_WAIT_MSis 30 s;MaintenanceWriteWaitis one budget per job: each wait is capped by the job's remaining deadline (zero at or past it), and once one publish is still pending after its wait (observe) every later publish in that job waits zero and is deferred like it. A pending write keeps its request identity and commits later; it is never reported as committed. AMaintenanceWriteWaitwith no deadline also sets the replay window of a subagent tool write whose job has none (minions/tool-write-identity.ts).__setMaintenanceWriteWaitForTestsreplaces the base wait, those tool writes included. Tests:test/maintenance-write-wait.test.ts,test/e2e/maintenance-write-wait.test.ts.src/core/persistence/effect-settle.ts—gbrain sources writer settle-effects <source> (--request-id|--parked-code) [--unsettle] [--dry-run|--apply --expect <plan_hash>](writer_settle_effects, an administration extension) (#7423, #7378): recordsdata.settled(and appends todata.settlements) on a failed Git effect no retry can move, never touching its failure, parked targets, request or bytes. It settles only on an exact-target proof re-checked under row locks at apply: each target declareddb_onlyin the current binding's gbrain.yml (sourceDbOnlyDir), or, for an effectguardEffectSourcerefusessource_changedbecause the source moved to a new worktree (same incarnation, this host owning the active binding), a later committed and pushed Git effect of the current worktree whoseexpected_hashequals the canonical file now and a blob at the already-fetched@{upstream}equal to it (no fetch). Withdrawal effects, claims, open recovery records, revoked writers, replaced sources and unknown targets refuse; an effect of the current binding that is not db_only refusesretry_instead. The plan hash is doctor --remediate'scomputePlanHashover the brain, source, selector, owner epoch and each proof (preview_changedotherwise). Readers that skip settled rows: doctorparked_effects,rearmWithheldTargets,readParkedGroups,readGitPushHolds,retryParkedPushes/--parked-code,retryIndexLockParks,sync status,failedEffectHistory;retryParkedEffectsreports a settled effect asaction: settled.retryParkedPushesalso reaches a push that failed without parked targets (#7378,failedCodes). #7985: an effect outside its source's current binding (CURRENT_BINDING_SQLinparked-groups.ts, the guard's own test) gets its ownreadParkedGroupsgroup (former_binding:binding_changedorsource_replaced, recorded and current worktree, up to five request ids, the settle preview ascommand), doctor's per-effect command for it issettle-effects --request-id,retryParkedEffectsrethrows the guard'ssource_changednaming both bindings with that preview asfix, and the bulk retries'former_worktreelists its worktree and requests.--retire(retiredTarget) settles such an effect asformer_binding_retiredonly on evidence: a replaced source (authority not re-checked), or each target's page absent, deleted, replaced (page_id) or at another revision thaneffect.revision; elsepage_not_moved, and a current-binding effectnot_former_binding; its plan operation iswriter_retire_effectsand its fixactor: user(test/orphan-effect-diagnostics-7985.test.ts). Tests:test/persistence-effect-settle.test.ts(scenarios intest/helpers/effect-settle-scenarios.ts) + the Postgres arm intest/e2e/w5-persistence-postgres.test.ts.src/core/persistence/owner-activity.ts— GBRA-248:ownerActivity(engine, worktreeIds)reads each worktree owner's liveness (apersistence_consumersrow renewed within the lapse window) and last activity (the greatest of the worktree heartbeat, which a consumer's clean stop stamps, its newest consumer renewal and the newest committed receipt, read through the foreground-committed and sync-watermark indexes).staleis true when the owner is not this host and not live, and either this process holds a PGLite file under another identity or the owner has been quiet pastOWNER_STALE_MS(24 h; with no activity recorded, the oldest open request's age decides).startOwnerReadruns it inside a budget the caller already has (the journal's 500 ms receipt read;awaitWrite's last 500 ms, which a shorter wait is extended to, with each worktree's answer reused for 10 s so a batch pays one read) and cancels it past that; staleness uses the database clock;writeHealthmaps a stale owner toowner_unavailable(unless recovery outranks it) with adiagnostic.ownerblock carrying onlylast_active, present whenever the owner is stale, andacceptPendingCoversin write-wait.ts keeps such a write at exit 10 under--accept-pending. Read-only; null activity authorizes nothing.