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.mdindex 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 changesdiff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.mdindex 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 leadingchannel. The warning goes to stderr (an `[AGENT]` block when stdout is not aterminal) 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 overevery 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>`. Keepa 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: markthe pages nobody else may see `visibility: private`. That hides them fromthe 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 pagesonly some people may read. One agent in a shared channel instead uses acredential 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 oneperson: it then reads as that person for everyone who talks to it.## Dashboard API keysdiff --git a/src/commands/doctor/checks/unscoped-multi-user-token.ts b/src/commands/doctor/checks/unscoped-multi-user-token.tsindex 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.tsindex 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.tsindex 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): striconst 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.tsindex 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: TrustReviewFif (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.tsindex 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) => {