Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytan0e17c98d3759
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e1433ccb4a..e3d1411fe3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,7 +21,7 @@ identifiers and attribution are available in the pre-removal Git revision
- `src/core/pg-tls.ts` (new): `resolvePgTls` / `withPgTls`, the one TLS resolver every `postgres()` call site in `src/` uses (the module pool in `db.ts`, worker instance pools in `postgres-engine.ts`, the read and direct pools in `connection-manager.ts`, the graduation target probe and the schema-lock diagnostic connection). An `ssl` option, `sslmode` / `ssl` / `sslrootcert=system` in the URL, or the driver's `PGSSL` variable is explicit and left alone; a loopback host or socket keeps the driver default; anything else gets `ssl: 'require'`. After a failed default-required connect, `tlsRequiredDefaultError` sends the protocol's SSLRequest to the server and turns a "no" into `postgres_tls_required` (DNS, refused and timeout failures are not probed).
- `src/core/error-registry.ts`: new code `postgres_tls_required` (host_only, actor user; fix asks the user, reads `gbrain engine status --probe --json`, verifies with `gbrain doctor --only postgres_tls --json`). `docs/guides/error-codes.md` regenerated.
- `src/core/pg-access-classify.ts`: new reason `tls_required_default` (manual tier in `gbrain db-repair`, which never removes TLS on its own; fatal for persistence reads).
-- `src/commands/doctor/checks/postgres-tls.ts` (new): `postgres_tls` (ops) judges TLS from the client side, from the mode the driver used for the URL the engine connected with. It warns on `sslmode=disable` and on a `sslmode=prefer` connection that fell back to plaintext, and is ok for a TLS client behind a pooler. The session's `pg_stat_ssl` row, which behind a pooler describes the pooler's hop, is detail only. It emits nothing on PGLite.
+- `src/commands/doctor/checks/postgres-tls.ts` (new): `postgres_tls` (ops) judges TLS from the client side, from the mode the driver used for the URL the engine connected with. It warns on `sslmode=disable` and on a `sslmode=prefer` connection that fell back or may have fallen back to plaintext (it never certifies prefer as encrypted), and is ok for a TLS client behind a pooler. The session's `pg_stat_ssl` row, which behind a pooler describes the pooler's hop, is detail only. It emits nothing on PGLite.
- `src/core/behavior-change-notice.ts`: one row (`postgres_tls_default`) disclosing the new default and the opt-out.
- `gbrain init` prints the Supabase URL format with `?sslmode=require`; `docs/ENGINES.md#tls-for-postgres-connections` documents the modes, `verify-full` with Supabase's CA, and the opt-out; the personal-brain tutorial and the other documented Postgres URLs carry `?sslmode=require`.
- `scripts/ci-local.sh`, `scripts/run-e2e.sh`: the Docker CI gate reaches its untrusted-by-name service hosts (`postgres-N`, `pgbouncer`) with an explicit `sslmode=disable`, and the derived PgBouncer E2E URL keeps the base URL's query.
diff --git a/docs/ENGINES.md b/docs/ENGINES.md
index 1b561f83e5..fad4efb266 100644
--- a/docs/ENGINES.md
+++ b/docs/ENGINES.md
@@ -223,7 +223,9 @@ which names both choices: turn TLS on at the server, or add
connection to a non-local server uses TLS. It judges that from the client side:
`sslmode=require`, `verify-ca` and `verify-full` make the driver refuse a
server without TLS. It warns on `sslmode=disable`, and on `sslmode=prefer` when
-the server does not offer TLS (prefer then falls back to plaintext). Behind a
+the server does not offer TLS or reports the session unencrypted (prefer falls
+back to plaintext without saying so, so doctor never certifies a prefer
+connection as encrypted). Behind a
pooler, the server's `pg_stat_ssl` row describes the pooler's own hop to the
database, which can't be checked from your machine, so doctor shows it as detail
and never warns about it. PGLite opens no network connection, so none of this
diff --git a/docs/architecture/key-files/commands-2-continued.md b/docs/architecture/key-files/commands-2-continued.md
index ca90faeee5..ebdfdf082c 100644
--- a/docs/architecture/key-files/commands-2-continued.md
+++ b/docs/architecture/key-files/commands-2-continued.md
@@ -6,7 +6,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/doctor/checks/integrations-memorable.ts` — `memorable_relay_health` (OPS category), the doctor surface for the optional third-party relay. Engine-free (file-plane reads only), pushed unconditionally so it survives `--fast`/`--scope`. Rung ladder: gate off → quiet ok; enabled WITHOUT the gbrain disclosure stamp → FAIL naming the exact fix (the `memorable enable` out-of-band state); CLI-side consent absent → warn; no runnable binary → FAIL; last relay run failed → warn with the CLAMPED cause (the shared `clampRelayCause`; child text never lands in a doctor message verbatim) — EXCEPT the documented openclaw `no_decisive_steps` rejection, which becomes an ok-with-note (`expected_openclaw_rejection`, name-only capture refused until argument capture lands) held as a DEFERRED note that surfaces only after the codex rung below passes: on a mixed openclaw+codex host the rejection is the persistent last-relay state, and an early return would paint the check green while a trust-stale codex hook sits silently dead; receipts written but the child never reported → warn; codex hooks wired but no codex-harness receipt in the recent receipt window (tail-200 read) → warn (`codex_hooks_never_fired` — codex hooks fail silently on a stale trust entry); healthy → ok with structured details (`out_of_band_settable: true` always rides — the enable flag can be flipped by the external CLI, which is exactly why the gate also demands the stamp). Pinned by `test/doctor-memorable.test.ts`.
- `src/commands/doctor/checks/routing-federation.ts` — `checkOauthClientScopeHealth` (`oauth_client_scope_health`, re-exported by the doctor.ts façade) has three warn arms: (a) dangling federated read grants, (b) orphaned empty `<name>-workspace` sources, (c) privileged self-registered clients — active `oauth_clients` rows whose scope word-matches `DCR_PRIVILEGED_SCOPES` — the DERIVED complement `ALLOWED_SCOPES_LIST \ DCR_REGISTRABLE_SCOPES` (exported; bound as a `$1` regex parameter, never interpolated) — and the `(read/write)` / `--scopes read,write` copy is built from `DCR_REGISTRABLE_SCOPES`; pinned by the set-equality + per-scope loop in `test/doctor-oauth-client-scope-health.test.ts`; rows with `grant_revision = 0` and no `oauth_grant_audit` row with `action = 'register'` (every operator path writes one; the anonymous DCR insert does not). Arm (c) is advisory (the signature also matches operator clients that predate the grant audit log) and carries the `gbrain auth rescope-client <client_id> --scopes read,write` / `gbrain auth revoke-client <client_id>` remedy; when the audit table or `grant_revision` column is absent it fails OPEN and the ok message states the self-registered-client audit was skipped (unknown). Pinned by `test/doctor-oauth-client-scope-health.test.ts`.
-- `src/commands/doctor/checks/postgres-tls.ts` — `postgres_tls` (OPS, after `rls`), judged from the client side: the mode `resolvePgTls` gives for `engine.connectedDatabaseUrl` (the config URL only as a fallback). `require`, `allow`, `verify-ca` and `verify-full` are ok, because the driver refuses a server without TLS; `sslmode=disable` warns; `sslmode=prefer` sends one SSLRequest probe (`probeServerTls`) and warns when the answer is no, since the driver then falls back to plaintext. The session's `pg_stat_ssl` row is detail only: behind a pooler it describes the pooler's hop to the database. Ok on a loopback host, nothing on PGLite. The fix asks the user; verify is `gbrain doctor --only postgres_tls`. `postgresTlsCheck(url, session, env, preferAnswer)` is the pure half (`test/doctor-postgres-tls.test.ts`; real servers and a TLS-client pooler in `test/e2e/pg-tls-postgres.test.ts`).
+- `src/commands/doctor/checks/postgres-tls.ts` — `postgres_tls` (OPS, after `rls`), judged from the client side: the mode `resolvePgTls` gives for `engine.connectedDatabaseUrl` (the config URL only as a fallback). `require`, `allow`, `verify-ca` and `verify-full` are ok, because the driver refuses a server without TLS; `sslmode=disable` warns; `sslmode=prefer` sends one SSLRequest probe (`probeServerTls`) and warns when the answer is no or the session reads unencrypted, since the driver falls back to plaintext silently; otherwise it is ok with `client_tls: null` (a fresh probe is not the engine's socket). A `PGSSL` value is TLS to the driver even when it reads `disable` (only URL values turn TLS off). The session's `pg_stat_ssl` row is detail only: behind a pooler it describes the pooler's hop to the database. Ok on a loopback host, nothing on PGLite. The fix asks the user; verify is `gbrain doctor --only postgres_tls`. `postgresTlsCheck(url, session, env, preferAnswer)` is the pure half (`test/doctor-postgres-tls.test.ts`; real servers and a TLS-client pooler in `test/e2e/pg-tls-postgres.test.ts`).
- `src/commands/doctor/checks/embedding-identity.ts` — `embedding_identity_unqualified` (#6113, BRAIN, right after `embedding_env_override`): warns when the DB `config` row `embedding_model` has no provider prefix (managed fact extraction reads only that row and `config set` refuses it). The fix is the read-only `gbrain migrate embeddings --to <provider:model> --dry-run`, filled from `loadConfig()`'s provider-qualified `embedding_model`, or `<PROVIDER_MODEL>` plus an `inputs` entry when none is configured; `details.target_differs` flags a configured model with another name (applying it switches models). Applying re-embeds active facts (paid, user's call). The free relabel is parked (TODOS). Test: `test/doctor-embedding-identity-unqualified.test.ts`.
- `src/commands/doctor/checks/embedding-state.ts` — `embedding_state` (#6696 B3, BRAIN, `tier: 'ops'`, `opsPglite: 'not_applicable'`, after `embeddings`): `readEmbeddingState` in `ops` mode on the ops tier, `full` otherwise. Warns only on chunks of pages soft-deleted past the 72 h purge window (`deleted_page_chunks_overdue`, fix `pages purge-deleted`) and, on a keyed brain, live pages with body text but no chunks (`chunkless_pages_healable`, fix `embed --stale`); the pending backlog stays `embeddings`' warning and quarantined pages `quarantined_pages`'. keyword_only, deleted chunks inside the window and a keyless brain are `infoCheck`; ops without a covering index warns with `details.health: 'unknown'` (`embedding_state_unknown`). Test: `test/doctor-embedding-state.test.ts`.
- `src/commands/doctor/checks/knowledge-health.ts` — `facts_extraction_health` reads the last 24 h of `facts:absorb` rows in `ingest_log` (written by `src/core/facts/absorb-log.ts`) per source and reason (`split_part(summary, ':', 1)`) and warns when a failure reason reaches `facts.absorb_warn_threshold` (default 10) in a source. Two reasons are not failures and never count: `write_pending_accepted` (the absorb log read the facts write's receipt back from the journal and it is still queued, running or recovering after the job's publish wait) and `write_deferred_unadmitted` (`writer_lock_unavailable` before admission, no receipt; the job retries). Deferrals warn on their own when, in a source, more than 10 or one over an hour old have no later completed `facts-absorb` job for the same page; that warning's fix is the read-only `gbrain sources writer status --source <id> --json`. The failure count is history: the message gives the incidents in the rolling 24 h window and when the newest ages out, and `details.facts_absorb` (`incidents_24h`, `ages_out_at`, `jobs_still_dead`, `dead_jobs`) adds the current state, the `facts-absorb` jobs dead or failed in the last 24 h with no later completed job for the same page (source and slug); they never change the status, and when no other fix applies the newest one gets the paid `gbrain jobs retry <id>` fix (`retry_job` over MCP, asks first). Tests: `test/doctor-facts-absorb-contention-6778.test.ts`, `test/facts-absorb-publish-wait-6778.test.ts`, `test/doctor-facts-absorb-history-6761.test.ts`.
diff --git a/src/commands/doctor/checks/postgres-tls.ts b/src/commands/doctor/checks/postgres-tls.ts
index e68165439f..f762766bcf 100644
--- a/src/commands/doctor/checks/postgres-tls.ts
+++ b/src/commands/doctor/checks/postgres-tls.ts
@@ -45,29 +45,34 @@ export function postgresTlsCheck(
if (hosts.length > 0 && hosts.every(isLoopbackPgHost)) {
return { name: 'postgres_tls', status: 'ok', message: 'The Postgres host is on this machine; TLS is not required.' };
}
- const { mode } = resolvePgTls(url, {}, env);
+ const { source, mode } = resolvePgTls(url, {}, env);
const serverView = session ? { server_reports_ssl: session.ssl, server_ssl_version: session.version } : {};
- if (mode === 'disable' || (mode === 'prefer' && preferAnswer === 'N')) {
+ const optedOut = mode === 'disable' && source !== 'env';
+ const prefer = mode === 'prefer';
+ if (optedOut || (prefer && (preferAnswer === 'N' || session?.ssl === false))) {
return {
name: 'postgres_tls', status: 'warn',
- message: mode === 'disable'
+ message: optedOut
? 'Connected to a non-local Postgres host without TLS (sslmode=disable in the database URL): the password and page contents cross the network in plaintext. Turn TLS on at the server and use sslmode=require or sslmode=verify-full.'
- : 'sslmode=prefer fell back to plaintext: the non-local Postgres server does not offer TLS, so the password and page contents cross the network unencrypted. Turn TLS on at the server and use sslmode=require, which refuses to fall back.',
- details: { client_tls: false, sslmode: mode, ...serverView },
+ : preferAnswer === 'N'
+ ? 'sslmode=prefer fell back to plaintext: the non-local Postgres server does not offer TLS, so the password and page contents cross the network unencrypted. Turn TLS on at the server and use sslmode=require, which refuses to fall back.'
+ : 'sslmode=prefer may have fallen back to plaintext: the server reports this session unencrypted, and prefer lets the driver connect without TLS whenever a server does not offer it. Use sslmode=require, which refuses to fall back.',
+ details: { client_tls: optedOut || preferAnswer === 'N' ? false : null, sslmode: mode, ...serverView },
fix: TLS_FIX,
};
}
- if (mode === 'prefer' && preferAnswer !== 'S') return null;
- const unverified = mode === 'require' || mode === 'prefer' || mode === 'allow';
+ if (prefer && preferAnswer !== 'S' && !session?.ssl) return null;
+ const unverified = mode === 'require' || prefer || mode === 'allow';
const notes = [
- mode === 'prefer' ? 'sslmode=prefer falls back to plaintext if the server ever stops offering TLS; sslmode=require refuses to.' : '',
unverified ? 'sslmode=' + mode + ' does not verify the server certificate; sslmode=verify-full with the server CA also verifies it.' : '',
- session && !session.ssl ? 'The server reports this session unencrypted: behind a pooler that is the pooler\'s own hop to the database, which cannot be checked from this machine.' : '',
+ !prefer && session && !session.ssl ? 'The server reports this session unencrypted: behind a pooler that is the pooler\'s own hop to the database, which cannot be checked from this machine.' : '',
].filter(Boolean).join(' ');
return {
name: 'postgres_tls', status: 'ok',
- message: 'This connection to the non-local Postgres host uses TLS' + (session?.ssl && session.version ? ' (' + session.version + ')' : '') + '.' + (notes ? ' ' + notes : ''),
- details: { client_tls: true, sslmode: mode, ...serverView },
+ message: (prefer
+ ? 'sslmode=prefer: the non-local Postgres server ' + (session?.ssl ? 'reports this session encrypted' : 'offers TLS') + ', but prefer lets the driver fall back to plaintext without saying so, and that cannot be confirmed from this machine; sslmode=require refuses to fall back.'
+ : 'This connection to the non-local Postgres host uses TLS' + (session?.ssl && session.version ? ' (' + session.version + ')' : '') + '.') + (notes ? ' ' + notes : ''),
+ details: { client_tls: prefer ? null : true, sslmode: mode, ...serverView },
};
}
diff --git a/test/doctor-postgres-tls.test.ts b/test/doctor-postgres-tls.test.ts
index aca635c30b..66332fe269 100644
--- a/test/doctor-postgres-tls.test.ts
+++ b/test/doctor-postgres-tls.test.ts
@@ -83,6 +83,25 @@ describe('postgres_tls doctor check', () => {
expect(postgresTlsCheck('postgres://[email protected]:5432/brain', { ssl: false, version: null }, {})!.status).toBe('ok');
});
+ test('sslmode=prefer with a session the server reports unencrypted warns, whatever a fresh probe answers', () => {
+ for (const answer of ['S', null] as const) {
+ const c = postgresTlsCheck(REMOTE + '?sslmode=prefer', { ssl: false, version: null }, {}, answer)!;
+ expect(c.status).toBe('warn');
+ expect(c.message).toContain('plaintext');
+ expect(c.details?.client_tls).not.toBe(true);
+ }
+ });
+
+ test('sslmode=prefer never certifies the client hop: a fresh probe is not the engine socket', () => {
+ const c = postgresTlsCheck(REMOTE + '?sslmode=prefer', { ssl: true, version: 'TLSv1.3' }, {}, 'S')!;
+ expect(c.details?.client_tls).toBeNull();
+ });
+
+ test('PGSSL=disable is TLS for the driver (only URL values turn it off), so doctor does not warn', () => {
+ const c = postgresTlsCheck(REMOTE, { ssl: true, version: 'TLSv1.3' }, { PGSSL: 'disable' })!;
+ expect(c.status).toBe('ok');
+ });
+
test('sslmode=prefer with no answer from the server emits nothing', () => {
expect(postgresTlsCheck(REMOTE + '?sslmode=prefer', null, {}, null)).toBeNull();
});