Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Doctor checks that a guest source's two records agree (GBRA-504)

garrytan9d095c514dd9
diff --git a/docs/guides/guest-notes.md b/docs/guides/guest-notes.md
index fb46b8d5af..03acd011b5 100644
--- a/docs/guides/guest-notes.md
+++ b/docs/guides/guest-notes.md
@@ -239,10 +239,13 @@ source other than `guests`. A credential with a `min_trust` floor above
gbrain doctor --only guest_source --json
```
-The `guest_source` check reads, and changes nothing. It fails when a guest source
-is missing its `guest`, `federated` or `trust_ceiling` flags, has a local
-path, is marked guest without its database record, or the brain's
-`guests.present` marker is unset (reads would skip the warning); and when a
+The `guest_source` check reads, and changes nothing. A source is a guest source
+when its config says `guest: true` or it has a guest source record, so its
+notes keep their warning if one of the two is lost. The check fails when the
+two disagree (one is there without the other) and names the repair,
+`gbrain guests init --source <id> --yes`, which restores both and keeps the
+writer list. It also fails when a guest source is missing its `federated` or
+`trust_ceiling` flags or has a local path, and when a
writer names a removed credential or one whose grant reaches beyond the guest
source. It warns when the writer list is empty, no owner is set, a credential bound
to you can't read the guest source (it prints the exact
diff --git a/src/commands/doctor/checks/guest-source.ts b/src/commands/doctor/checks/guest-source.ts
index 2a9dfa37ac..564b19c159 100644
--- a/src/commands/doctor/checks/guest-source.ts
+++ b/src/commands/doctor/checks/guest-source.ts
@@ -2,9 +2,10 @@
* guest_source doctor check (GBRA-504 slice 4, read-only).
*
* For every guest source (a guest_sources row, or a source whose config says guest: true):
- * - fail: the source config lacks guest, federated or the external_untrusted trust_ceiling, it has a local path, the
- * config says guest with no guest_sources row, the brain's guests.present marker is unset (reads would skip the
- * guest warning), a writer names a removed or unknown credential, or a writer's grant reaches beyond the guest source;
+ * - fail: the two guest records disagree (config guest: true with no guest_sources row, or a guest_sources row whose
+ * config lacks guest: true; either alone still marks reads, and gbrain guests init restores both), the config lacks
+ * federated or the external_untrusted trust_ceiling, it has a local path, a writer names a removed or unknown
+ * credential, or a writer's grant reaches beyond the guest source;
* - warn: the writer list is empty or names a principal that is not a remote credential, no brain owner is set, a
* credential bound to the owner cannot read the source (with the exact grant command, and
* gbrain guests grant-owner-clients for all of them), or its min_trust floor hides guest notes (F9).
@@ -15,7 +16,7 @@ import type { BrainEngine } from '../../../core/engine.ts';
import { agentFix, checkError, infoCheck } from '../check-fix.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
import { authSourcesFromGrant, grantFromClient, grantFromRow, grantFromTokenRow } from '../../../core/grants/model.ts';
-import { GUEST_SOURCES_PRESENT_KEY } from '../../../core/guests/marker.ts';
+import { guestSourceSql } from '../../../core/guests/marker.ts';
import { GUEST_TRUST_CEILING } from '../../../core/guests/sources.ts';
import { ownerCredentials } from '../../../core/guests/owner-credentials.ts';
@@ -41,13 +42,14 @@ async function writerFindings(engine: BrainEngine, source: string, writer: strin
return [{ level: 'fail', text: 'writer ' + writer + ' is granted ' + [...new Set([auth.sourceId, ...reads])].join(', ') + ', not exactly ' + source }];
}
-async function sourceFindings(engine: BrainEngine, s: GuestSourceRow, present: boolean): Promise<Finding[]> {
+async function sourceFindings(engine: BrainEngine, s: GuestSourceRow): Promise<Finding[]> {
const out: Finding[] = [];
const init = ['gbrain', 'guests', 'init', '--source', s.id, '--yes'];
const config = json(s.config);
- if (s.writers === null) return [{ level: 'fail', text: 'source ' + s.id + ' says guest: true in its config but is not a guest source (no guest_sources row), so nothing enforces its writer list or ceiling', fix: init }];
- if (!present) out.push({ level: 'fail', text: 'source ' + s.id + ' is a guest source but config ' + GUEST_SOURCES_PRESENT_KEY + ' is unset, so reads skip the guest warning', fix: init });
- const flags = [config.guest === true ? null : 'guest', config.federated === true ? null : 'federated',
+ const repair = '; its notes still read as guest notes, repair: ' + init.join(' ');
+ if (s.writers === null) return [{ level: 'fail', text: 'source ' + s.id + ' says guest: true in its config but has no guest_sources row, so the two guest records disagree and nothing enforces its writer list or ceiling' + repair, fix: init }];
+ if (config.guest !== true) out.push({ level: 'fail', text: 'source ' + s.id + ' has a guest_sources row but its config does not say guest: true, so the two guest records disagree' + repair, fix: init });
+ const flags = [config.federated === true ? null : 'federated',
config.trust_ceiling === GUEST_TRUST_CEILING && s.ceiling === GUEST_TRUST_CEILING ? null : 'trust_ceiling ' + GUEST_TRUST_CEILING].filter(Boolean);
if (flags.length) out.push({ level: 'fail', text: 'source ' + s.id + ' is missing ' + flags.join(', '), fix: init });
if (s.local_path) out.push({ level: 'fail', text: 'source ' + s.id + ' has a local path; a guest source is database-only' });
@@ -72,11 +74,10 @@ export async function guestSourceCheck(engine: BrainEngine): Promise<Check> {
try {
const sources = await engine.executeRaw<GuestSourceRow>(
'SELECT s.id, s.local_path, s.config, g.writers, g.trust_ceiling AS ceiling FROM sources s LEFT JOIN guest_sources g ON g.source_id = s.id '
- + "WHERE g.source_id IS NOT NULL OR s.config->>'guest' = 'true' ORDER BY s.id");
+ + 'WHERE ' + guestSourceSql('s.config', 's.id') + ' ORDER BY s.id');
if (!sources.length) return infoCheck(name, 'Not applicable: this brain has no guest source (gbrain guests init).', 'not_applicable');
- const present = (await engine.getConfig(GUEST_SOURCES_PRESENT_KEY)) === 'true';
const findings: Finding[] = [];
- for (const s of sources) findings.push(...await sourceFindings(engine, s, present));
+ for (const s of sources) findings.push(...await sourceFindings(engine, s));
const ids = sources.map(s => s.id).join(', ');
const details = { sources: sources.map(s => ({ source: s.id, writers: s.writers ?? [] })), findings: findings.map(f => ({ level: f.level, text: f.text })) };
if (!findings.length) return { name, status: 'ok', message: 'Guest source(s) ' + ids + ': flags, ceiling and writers in place, and every owner credential reads them.', details };
diff --git a/test/doctor-guest-source.test.ts b/test/doctor-guest-source.test.ts
index 5fb1e718bb..73cfae7fa6 100644
--- a/test/doctor-guest-source.test.ts
+++ b/test/doctor-guest-source.test.ts
@@ -2,9 +2,10 @@
* guest_source doctor check (GBRA-504 slice 4).
*
* Protects: not_applicable without a guest source; ok for a guest source with its flags, ceiling and a live writer
- * whose grant is exactly the guest source, read by every owner credential; fail when a source is marked guest but the
- * brain's guests.present marker is unset (reads would skip the warning), when a source says guest without its
- * guest_sources row, when a writer names a removed client, or when a writer's grant reaches another source; warn, with
+ * whose grant is exactly the guest source, read by every owner credential; fail, naming gbrain guests init as the
+ * repair, when the two guest records disagree (a guest_sources row whose config lost guest: true, or a config that says
+ * guest with no guest_sources row), when a writer names a removed client, or when a writer's grant reaches another
+ * source; warn, with
* the exact grant command, when an owner credential cannot read the guest source, and when its min_trust floor hides
* guest notes (F9). The check reads only: no grant changes. PGLite in-memory, no repository.
*/
@@ -16,7 +17,6 @@ import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { addMember, bindCredential } from '../src/core/access/members.ts';
import { setOwner } from '../src/core/access/owner.ts';
import { initGuestSource } from '../src/core/guests/sources.ts';
-import { GUEST_SOURCES_PRESENT_KEY } from '../src/core/guests/marker.ts';
import { guestSourceCheck } from '../src/commands/doctor/checks/guest-source.ts';
import { categorizeCheck } from '../src/core/doctor-categories.ts';
import { setMinTrust } from '../src/core/trust/min-trust.ts';
@@ -64,21 +64,24 @@ describe('guest_source doctor check', () => {
expect({ status: check.status, message: check.message }).toEqual({ status: 'ok', message: expect.stringContaining(SRC) });
}, 60_000);
- test('a source marked guest while guests.present is unset fails', async () => {
+ test('a guest_sources row whose config lost guest: true fails as a disagreement and names the repair', async () => {
await healthyBrain();
- await engine.executeRaw('DELETE FROM config WHERE key = $1', [GUEST_SOURCES_PRESENT_KEY]);
+ await engine.executeRaw("UPDATE sources SET config = config - 'guest' WHERE id = $1", [SRC]);
const check = await guestSourceCheck(engine);
expect(check.status).toBe('fail');
- expect(check.message).toContain(GUEST_SOURCES_PRESENT_KEY);
+ expect(check.message).toContain('source ' + SRC + ' has a guest_sources row but its config does not say guest: true');
+ expect(check.message).toContain('repair: gbrain guests init --source ' + SRC + ' --yes');
expect(check.fix?.argv).toEqual(['gbrain', 'guests', 'init', '--source', SRC, '--yes']);
}, 60_000);
- test('a source whose config says guest but has no guest_sources row fails', async () => {
+ test('a source whose config says guest but has no guest_sources row fails as a disagreement and names the repair', async () => {
await healthyBrain();
await engine.executeRaw("UPDATE sources SET config = config || '{\"guest\": true}'::jsonb WHERE id = $1", [PLAIN]);
const check = await guestSourceCheck(engine);
expect(check.status).toBe('fail');
- expect(check.message).toContain(PLAIN);
+ expect(check.message).toContain('source ' + PLAIN + ' says guest: true in its config but has no guest_sources row');
+ expect(check.message).toContain('repair: gbrain guests init --source ' + PLAIN + ' --yes');
+ expect(check.fix?.argv).toEqual(['gbrain', 'guests', 'init', '--source', PLAIN, '--yes']);
}, 60_000);
test('a writer naming a removed client, or a writer granted another source, fails', async () => {
diff --git a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
index bcbb72de8b..4b5353e5fc 100644
--- a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
+++ b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
@@ -1232,10 +1232,19 @@
"severity": "info",
"status": "ok"
},
+ {
+ "category": "brain",
+ "elapsed_ms": "<volatile>",
+ "message": "Not applicable: this brain has no guest source (gbrain guests init).",
+ "name": "guest_source",
+ "readiness_state": "not_applicable",
+ "severity": "info",
+ "status": "ok"
+ },
{
"category": "ops",
"elapsed_ms": "<volatile>",
- "message": "RLS enabled on 178/178 public tables",
+ "message": "RLS enabled on 181/181 public tables",
"name": "rls",
"status": "ok"
},
@@ -1277,7 +1286,7 @@
{
"category": "meta",
"elapsed_ms": "<volatile>",
- "message": "All 178 table(s) the applied migrations create exist.",
+ "message": "All 181 table(s) the applied migrations create exist.",
"name": "schema_missing_tables",
"status": "ok"
},
@@ -6562,10 +6571,19 @@
"severity": "info",
"status": "ok"
},
+ {
+ "category": "brain",
+ "elapsed_ms": "<volatile>",
+ "message": "Not applicable: this brain has no guest source (gbrain guests init).",
+ "name": "guest_source",
+ "readiness_state": "not_applicable",
+ "severity": "info",
+ "status": "ok"
+ },
{
"category": "ops",
"elapsed_ms": "<volatile>",
- "message": "RLS enabled on 178/178 public tables",
+ "message": "RLS enabled on 181/181 public tables",
"name": "rls",
"status": "ok"
},
@@ -6607,7 +6625,7 @@
{
"category": "meta",
"elapsed_ms": "<volatile>",
- "message": "All 178 table(s) the applied migrations create exist.",
+ "message": "All 181 table(s) the applied migrations create exist.",
"name": "schema_missing_tables",
"status": "ok"
},
diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.json
index fadedf9ad3..da3cc89462 100644
--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json
+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json
@@ -1121,6 +1121,15 @@
"severity": "info",
"status": "ok"
},
+ {
+ "category": "brain",
+ "elapsed_ms": "<volatile>",
+ "message": "Not applicable: this brain has no guest source (gbrain guests init).",
+ "name": "guest_source",
+ "readiness_state": "not_applicable",
+ "severity": "info",
+ "status": "ok"
+ },
{
"category": "ops",
"elapsed_ms": "<volatile>",