Garry's Opinionated OpenClaw/Hermes Agent Brain
Pooler misroute audit
A brain whose gbrain serve read pool pipelined statements through a
transaction-mode pooler (Supavisor or PgBouncer on port 6543, or a URL with
?prepare=false) before v0.60.187.0 could hand a statement another
statement's rows (#6543). Most of the time that failed loudly
(pg_statement_build_failed with error=UNDEFINED_VALUE, pg_connection_stuck),
but a statement that bound a value from someone else's row and succeeded
leaves a persistence row whose identity belongs to another row.
scripts/audit-pooler-misroute.ts looks for those rows. It only reads.
Say to your agent: "Run the gbrain pooler misroute audit for the window the serve ran through the transaction pooler, and show me the result before changing anything."
When to run it
Run it once after upgrading if, before the upgrade, any of these held for a serve or worker on the brain:
- the database URL used port 6543 or
?prepare=false; - the log carried
pg_statement_build_failed,pg_connection_stuckorpg_connection_desynclines; /health?deep=1showedtransport.max_pipelineother than0behind such a URL.
The window is from the first such serve start (or the first warn line) until the upgraded serve started.
Run
The script is one self-contained file: it needs no checkout and imports
nothing from gbrain, only the postgres driver your install already ships
(vendor/postgres under the gbrain install; set
GBRAIN_AUDIT_POSTGRES_DRIVER=<path to vendor/postgres/src/index.js> if it is
not found). On a host without a checkout, copy scripts/audit-pooler-misroute.ts
from the gbrain repository at this version or later, then:
bun audit-pooler-misroute.ts \
--url 'postgresql://postgres:<password>@db.<project>.supabase.co:5432/postgres?sslmode=require' \
--since 2026-10-01T00:00:00Z --until 2026-10-12T18:00:00Z --json > audit.json
--urlis explicit (never read from the environment) and must be the direct URL or the session pooler (Supabase: port 5432). A transaction-mode URL (port 6543 or?prepare=false) is refused: the audit must not read through the transport it audits. It opens one connection.- Each batch (
--batch-size, default 500 rows) is oneREPEATABLE READ READ ONLYtransaction with a transaction-local timeout (--batch-timeout-ms, default 15000). There is no snapshot across batches; a row written while the audit runs is reportedunknown(changed_during_audit). Running it beside a live serve is safe. - Exit
0: no mismatch. Exit1: at least one mismatch. Exit2: usage error or refused URL.
Read the result
verified_okcounts requests and effects whose identity values all agree.mismatchlists each row and field whose value belongs to another row: an effect whosesource_id,source_incarnationorworktree_iddiffers from its own request (they are copied in one statement), a request whosesource_incarnationis another source's (belongs_to), or a request whosepage_idnames a page in another source.unknownlists rows the audit cannot judge, withreasons(unknown_by_reasoncounts them):changed_during_audit,compacted_history,token_reclaimed(the claim stamp names another execution token),source_removed,source_reincarnated,page_removed,page_slug_differs(usually a later move) andeffect_identity_unset(rows from before those columns). Unknown is not clean: it is a coverage gap.
After a mismatch
Do not repair anything from the audit alone. A corrective write is a one-way
door: send audit.json (it holds row ids and identity values, no page
content) with the serve logs of the window to the brain's owner, and decide
the fix together from a preview. Re-running the audit is always safe.