Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(trust,grants): accept-all skips a proposal that would confirm a flagged page; audience and pin text (#8930 review)

garrytan62f5a8efb9d6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 53a026138b..43975ce1e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,7 +24,7 @@ identifiers and attribution are available in the pre-removal Git revision
**An install that hands one unscoped credential to an agent several people talk to now says so, loudly, and doctor reports it.** In the HARN-13 host-harness pilot, one bot token over a brain that held many channels' chat made agents answer people with other people's messages: telling the agent gbrain was live cost 9 to 21 points of pass rate, and every added cross-scope failure cited a channel page the bot grant returned. A credential reads the same pages whoever talks to its agent (an unbound one everything its grant reaches, one bound to a member what that member may read), so gbrain warns.
-The `unscoped_multi_user_token` safety notice fires from `gbrain setup openclaw|hermes|grok-bot|muse`, from `setup claude-code` when a chat-channel plugin is enabled, from `mcp grant` and `connect` for a bot harness or a grant that reads chat from 2+ channels, from `skillpack scaffold` into an OpenClaw or Hermes workspace, and from `auth create` and `auth register-client` when the new credential reads chat from 2+ channels. It names the fixes (a one-source grant, `sources unfederate`, `GBRAIN_SOURCE` for a stdio agent, `visibility: private`, a credential bound to each person with `gbrain auth create <name> --member <id>`, or one shared agent with `--may-act-for` and a per-request audience), says plainly when the chat sits in one source and no source grant can separate it, and says that `source_ids` narrows only the call that sends it. A credential holding `--may-act-for` is not flagged. The new read-only doctor check `unscoped_multi_user_token` runs the same detection over every active token, OAuth client and wired local agent. No grant, default or scoping behaviour changes, and no exit code moves.
+The `unscoped_multi_user_token` safety notice fires from `gbrain setup openclaw|hermes|grok-bot|muse`, from `setup claude-code` when a chat-channel plugin is enabled, from `mcp grant` and `connect` for a bot harness or a grant that reads chat from 2+ channels, from `skillpack scaffold` into an OpenClaw or Hermes workspace, and from `auth create` and `auth register-client` when the new credential reads chat from 2+ channels. It names the fixes (a one-source grant, `sources unfederate`, `GBRAIN_SOURCE` plus `sources unfederate` for a stdio agent, `visibility: private`, a credential bound to each person with `gbrain auth create <name> --member <id>`, or one shared agent with `--may-act-for` and a per-request audience), says plainly when the chat sits in one source and no source grant can separate it, and says that `source_ids` narrows only the call that sends it. A credential holding `--may-act-for` is not flagged, and the notice says its harness must name an audience on every call, because a call that names none reads the credential's full grant. The new read-only doctor check `unscoped_multi_user_token` runs the same detection over every active token, OAuth client and wired local agent. No grant, default or scoping behaviour changes, and no exit code moves.
### Itemized changes
diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.md
index ecb727c573..5beb421f1c 100644
--- a/docs/mcp/ADMIN.md
+++ b/docs/mcp/ADMIN.md
@@ -405,8 +405,9 @@ the page's `channel`, `chat` or `conversation` frontmatter, a leading
channel. The warning goes to stderr (an `[AGENT]` block when stdout is not a
terminal) and into the `notices` or `warnings` list of a `--json` result.
It never changes a grant or an exit code. A credential holding
-`--may-act-for` is not flagged: its reads follow the audience its harness
-names.
+`--may-act-for` is not flagged. Its reads follow the audience its harness
+names, and a call that names no audience reads the credential's full grant, so
+the harness must name one on every call.
`gbrain doctor --only unscoped_multi_user_token` runs the same detection over
every active token and OAuth client, and over the local agents setup wired: it
@@ -422,7 +423,8 @@ Fix it with today's commands:
`gbrain mcp grant <name> --source <source> --federated-read <source>`. Keep
a channel's source out of unscoped reads with `gbrain sources unfederate <id>`.
- For a local stdio agent, set `GBRAIN_SOURCE=<source>` in its MCP server
- environment.
+ environment and run `gbrain sources unfederate <source>`: the pin covers
+ reads that name no source, and a federated sibling source stays nameable.
- When the chat sits in one source, a source grant cannot separate it: mark
the pages nobody else may see `visibility: private`. That hides them from
the agent only while its access may not read private pages.
@@ -434,8 +436,9 @@ Fix it with today's commands:
`gbrain auth create <name> --member <id>`) and put `readable_by` on pages
only some people may read. One agent in a shared channel instead uses a
credential made with `gbrain auth create <name> --may-act-for <members>`,
- and its harness names each request's audience (see
- [above](#inspect-clients-and-edit-access)). Never bind a shared agent's credential to one
+ and its harness names each request's audience on every call (see
+ [above](#inspect-clients-and-edit-access)); a call that names none reads the
+ credential's full grant. Never bind a shared agent's credential to one
person: it then reads as that person for everyone who talks to it.
## Dashboard API keys
diff --git a/src/commands/doctor/checks/unscoped-multi-user-token.ts b/src/commands/doctor/checks/unscoped-multi-user-token.ts
index 3199cb152e..1bba59af2f 100644
--- a/src/commands/doctor/checks/unscoped-multi-user-token.ts
+++ b/src/commands/doctor/checks/unscoped-multi-user-token.ts
@@ -12,7 +12,8 @@
* harness (or of Claude Code with a chat-channel plugin). A bot harness with
* no such chat in reach is reported as information, so a brain with nothing
* to separate yet is not marked unhealthy. A credential holding --may-act-for
- * is skipped: its reads follow the audience its harness names.
+ * is skipped: the per-person fix names it, and its notice says a call that
+ * names no audience reads its full grant.
* A remote caller (run_doctor only) gets counts, never credential names.
*/
import { grantFromClient, grantFromRow, grantFromTokenRow, type PrincipalGrant } from '../../../core/grants/model.ts';
diff --git a/src/commands/trust.ts b/src/commands/trust.ts
index 1493f8b4b0..5d9e7e2eca 100644
--- a/src/commands/trust.ts
+++ b/src/commands/trust.ts
@@ -166,8 +166,8 @@ async function acceptAll(backend: TrustBackend, args: string[], json: boolean):
// A contradiction has no single accept: each of its commands decides it differently, so --accept-all leaves it for the owner.
const contradictions = review.items.filter(item => item.kind === 'contradiction')
.map(item => ({ ref: item.ref, reason: 'contradiction', next: 'Decide it with one of its commands: gbrain trust review --kind contradiction' }));
- const flagged = review.items.filter(item => item.kind === 'flagged_page').map(item => ({ ref: item.ref, reason: 'confirm_on_its_own', next: `gbrain trust confirm ${item.ref}` }));
- const inputs = review.items.filter(item => item.kind !== 'contradiction' && item.kind !== 'flagged_page')
+ const flagged = review.items.filter(item => item.kind === 'flagged_page' || item.flagged).map(item => ({ ref: item.ref, reason: 'confirm_on_its_own', next: `gbrain trust confirm ${item.ref}` }));
+ const inputs = review.items.filter(item => item.kind !== 'contradiction' && item.kind !== 'flagged_page' && !item.flagged)
.map(item => ({ action: item.kind === 'hold' ? 'release' : 'confirm', ref: item.ref, source: item.source_id } as OwnerActionInput));
const skipLines = () => { for (const s of contradictions) console.log(`${s.ref}: skipped (a contradiction; ${s.next})`); };
if (inputs.length === 0 && flagged.length === 0) {
@@ -211,8 +211,9 @@ async function acceptAll(backend: TrustBackend, args: string[], json: boolean):
for (const f of failed) console.log(`${f.ref}: not applied (${(f.error as { message?: string }).message ?? String(f.error)})`);
for (const s of skipped) console.log(`${s.ref}: skipped, ${why(s.reason)}${'error' in s ? ` (${(s.error as { message?: string }).message ?? String(s.error)})` : ''}; run ${s.next} on its own`);
}
- if (failed.length || skipped.length) setCliExitVerdict(1);
+ if (failed.length) setCliExitVerdict(1);
else if (pending.length && (!acceptPendingRequested(getCliOptions().acceptPending) || uncovered > 0)) setCliExitVerdict(PENDING_WRITE_EXIT_CODE);
+ else if (skipped.length) setCliExitVerdict(1);
}
/** Renders a refusal through the shared CLI envelope with its contract exit code (3 for consent refusals). */
diff --git a/src/core/grants/shared-exposure.ts b/src/core/grants/shared-exposure.ts
index a3d1862d54..8f19208256 100644
--- a/src/core/grants/shared-exposure.ts
+++ b/src/core/grants/shared-exposure.ts
@@ -141,7 +141,7 @@ function reach(reasons: readonly ExposureReason[], census: ChatCensus | null | u
/** The per-person setup: a credential per person, or one shared agent reading as each request's audience. */
const PER_PERSON = 'Per-person access: give each person\'s agent its own credential bound to them (gbrain access member add <id>, then gbrain auth create <name> --member <id>) and put readable_by on pages only some people may read; '
- + 'one agent in a shared channel instead uses a credential made with gbrain auth create <name> --may-act-for <members>, and its harness names each request\'s audience. '
+ + 'one agent in a shared channel instead uses a credential made with gbrain auth create <name> --may-act-for <members>, and its harness names each request\'s audience on every call: a call that names none reads the credential\'s full grant. '
+ 'Never bind a shared agent\'s credential to one person: it then reads as that person for everyone who talks to it.';
/**
@@ -152,7 +152,7 @@ export function remedyText(s: ExposureSubject, census?: ChatCensus | null): stri
const steps: string[] = [];
if (splitBySource(census)) {
steps.push(s.kind === 'stdio'
- ? 'pin the agent to one audience\'s source by setting GBRAIN_SOURCE=<source> in its MCP server environment'
+ ? 'pin the agent to one audience\'s source by setting GBRAIN_SOURCE=<source> in its MCP server environment and running gbrain sources unfederate <source> (a federated sibling source stays nameable)'
: `grant one audience's source only (${narrowArgv(s, census)!.join(' ')}; a new harness grant: gbrain mcp grant <name> --source <source> --federated-read <source>)`);
steps.push('keep a channel\'s source out of unscoped reads (gbrain sources unfederate <id>)');
} else {
diff --git a/src/core/trust/review.ts b/src/core/trust/review.ts
index c8055b6028..80d5791863 100644
--- a/src/core/trust/review.ts
+++ b/src/core/trust/review.ts
@@ -57,6 +57,8 @@ export interface TrustReviewItem {
commands: Partial<Record<TrustReviewCommand, string[]>>;
/** Contradiction items: who runs each command, the consent it needs, whether it can be undone and how. */
command_meta?: Partial<Record<TrustReviewCommand, TrustReviewCommandMeta>>;
+ /** A proposal whose target page the write gate flagged as an instruction: accepting it confirms that page, so accept-all skips it. */
+ flagged?: true;
}
export type TrustReviewCommand = 'confirm' | 'drop' | 'release' | 'revert' | 'repair' | 'explain' | 'supersede' | 'forget';
@@ -260,9 +262,12 @@ export async function buildTrustReview(engine: BrainEngine, filter: TrustReviewF
if (wants(filter, 'proposal') || wants(filter, 'lowered_page') || (filter.kind && PROPOSAL_ACTIONS.includes(filter.kind))) {
const action = filter.kind && PROPOSAL_ACTIONS.includes(filter.kind) ? filter.kind as TrustProposalAction
: filter.kind === 'lowered_page' ? 'lower_page' : undefined;
+ const [gate] = await engine.executeRaw<{ t: string | null }>(`SELECT to_regclass('write_gate_receipts')::text AS t`);
for (const p of await listTrustProposals(engine, { status: 'pending', sourceId: filter.sourceId, action, since: filter.since, limit: 1000 })) {
if (filter.kind === 'proposal' && p.action === 'lower_page') continue;
- items.push(proposalItem(p, await pageOf(engine, p), p.action === 'lower_page' && await loweredByUnknownMarker(engine, p)));
+ const flagged = !!gate?.t && p.target_table === 'pages'
+ && (await engine.executeRaw(`SELECT 1 FROM pages p WHERE p.id = $1 AND ${activationSuppressedSql('pages', 'p')}`, [p.target_id])).length > 0;
+ items.push({ ...proposalItem(p, await pageOf(engine, p), p.action === 'lower_page' && await loweredByUnknownMarker(engine, p)), ...(flagged ? { flagged: true as const } : {}) });
}
}
if (wants(filter, 'preference')) items.push(...await standingPreferences(engine, filter));
diff --git a/test/trust-owner-actions.test.ts b/test/trust-owner-actions.test.ts
index 4cb83a357e..bca02c2c34 100644
--- a/test/trust-owner-actions.test.ts
+++ b/test/trust-owner-actions.test.ts
@@ -486,6 +486,11 @@ describe('review, explain and accept-all (CEO-2, DX-10, DX-15, DX-16)', () => {
expect(renderTrustReview(review)).toContain('1 flagged page(s)');
expect((await buildTrustReview(engine, { sourceId: b.sourceId, kind: 'flagged_page' })).items.map(i => i.ref)).toEqual([ref]);
expect((await buildTrustReview(engine, { sourceId: b.sourceId, kind: 'flagged_page', since: new Date(Date.now() + 60_000) })).items).toEqual([]);
+ const loweredRef = lowered.trust_lowered.proposal_ref;
+ expect(review.items.find(i => i.ref === loweredRef)?.flagged).toBe(true);
+ await ownerPage(b, 'notes/lowered-plain-example', 'Owner.');
+ const plain = await run(b.agent, 'put_page', { slug: 'notes/lowered-plain-example', content: page('Owner', 'Lunch moved to one.'), force: true });
+ expect((await buildTrustReview(engine, { sourceId: b.sourceId })).items.find(i => i.ref === plain.trust_lowered.proposal_ref)?.flagged).toBeUndefined();
const io = typesToken();
const original = console.log;
@@ -497,8 +502,12 @@ describe('review, explain and accept-all (CEO-2, DX-10, DX-15, DX-16)', () => {
expect(io.prompt()).toContain('Accept 1 item(s)');
expect(io.prompt()).toContain(`${ref} skipped: a page flagged as instructions is confirmed only after you read it`);
expect(out).toContain(`${ref}: skipped, a page flagged as instructions is confirmed only after you read it; run gbrain trust confirm ${ref} on its own`);
+ expect(io.prompt()).toContain(`${loweredRef.padEnd(6)} skipped: a page flagged as instructions is confirmed only after you read it`);
+ expect(out).toContain(`${loweredRef}: skipped, a page flagged as instructions is confirmed only after you read it; run gbrain trust confirm ${loweredRef} on its own`);
expect(code).toBe(1);
expect((await pageRow(b, 'notes/flagged-a-example')).trust_tier).toBe('agent_written');
+ expect((await pageRow(b, 'notes/lowered-flag-example')).trust_tier).not.toBe('user_confirmed');
+ expect((await pageRow(b, 'notes/lowered-plain-example')).trust_tier).toBe('user_confirmed');
typesToken();
await ownerDo(b, { action: 'confirm', ref });
expect((await pageRow(b, 'notes/flagged-a-example')).trust_tier).toBe('user_confirmed');
@@ -538,10 +547,12 @@ describe('review, explain and accept-all (CEO-2, DX-10, DX-15, DX-16)', () => {
{ name: 'pending beside accepted', h8: 'released', env: {}, exit: 10 },
{ name: 'pending beside failed', h8: 'fails', env: {}, exit: 1 },
{ name: 'pending with --accept-pending', h8: 'released', env: { GBRAIN_ACCEPT_PENDING: '1' }, exit: 0 },
+ { name: 'pending beside a skipped flagged page', h8: 'released', env: {}, exit: 10, flagged: true },
] as const;
for (const c of cases) {
const backend = {
- review: async () => ({ items: [{ kind: 'hold', ref: 'h7', source_id: 'default' }, { kind: 'hold', ref: 'h8', source_id: 'default' }] }),
+ review: async () => ({ items: [{ kind: 'hold', ref: 'h7', source_id: 'default' }, { kind: 'hold', ref: 'h8', source_id: 'default' },
+ ...('flagged' in c ? [{ kind: 'flagged_page', ref: 'p:default/notes/flagged-example', source_id: 'default' }] : [])] }),
explain: async () => [],
preview: async (input: OwnerActionInput) => ({ action: 'release', ref: input.ref, token: input.ref, command: `gbrain trust release ${input.ref}`, raises: true, binding: `b-${input.ref}`, summary: `Release held fact ${input.ref}` }),
apply: async (input: OwnerActionInput) => {