Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
requester_scope_unknown says the settings could not be read and carries a read-only verify
garrytan24917c52b06c
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex b5246d27f8..f3f1a51c12 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -4294,7 +4294,7 @@ More: [docs/guides/write-refusals.md#requester_scope_required](../../docs/guides| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| A remote read came from a connection bound to no member, and whether the brain serves one person or several could not be read (the config read failed, and so did one re-read), so it was refused before any work and nothing was read. | A statement timeout, a lock wait or a dropped pooled connection can fail one config read while the next read succeeds. Reading that as a one-person brain would let a connection bound to nobody read every page no rule restricts on a brain that may serve several people, so gbrain refuses until it can tell. | Retry the same call in a few seconds. If it keeps failing, the brain host's operator checks the database with gbrain doctor --json. A connection bound to a member is never refused this way. | provider | `repeat the read that failed` | 1 | yes |+| A remote read came from a connection bound to no member, and the brain's settings (whether it serves one person or several) could not be read: the config read failed, and so did one re-read. The call was not answered and nothing was read; this is not an access decision, and the same call can succeed once the database answers. | A statement timeout, a lock wait or a dropped pooled connection can fail one config read while the next read succeeds. Reading that as a one-person brain would let a connection bound to nobody read every page no rule restricts on a brain that may serve several people, so gbrain refuses until it can tell. | Retry the same call in a few seconds. If it keeps failing, the brain host's operator checks the database with gbrain doctor --json. A connection bound to a member is never refused this way. | provider | `repeat the read that failed` | 1 | yes |More: [docs/guides/write-refusals.md#requester_scope_unknown](../../docs/guides/write-refusals.md#requester_scope_unknown)diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 9cf06b06fb..799f1f8b04 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -1083,7 +1083,7 @@ reads `state: "not_enforced"` and nothing is refused.| Code | What happened | What to do ||---|---|---|| <a id="requester_scope_required"></a>`requester_scope_required` | A remote read came from a connection bound to nobody. `reason` says which: `grace_ended` (the connection is older than the brain's several-people date and its 14 days ran out), `created_after` (it was created after that date, so it had to be scoped at creation) or `since_unknown` (the date could not be read; fail closed). The message names the connection and the operation. Nothing was read; the code is also in `structuredContent.error.code` and the audit trail (`access-audience`). Read-only identity and health calls (`whoami`, `get_brain_identity`, `get_status_snapshot`, `search_modes`, `get_health`, and a non-admin credential's own `get_job` / `wait_job`) still answer. | The brain operator runs `fix` on the brain host: `gbrain auth rescope --token <name> --member <id>` (or `--client <id>`; preview with `gbrain access check --token <name>`), or for a stdio server, when only one person uses that harness, `gbrain setup claude-code|codex --stdio-member <id>`, which binds that one harness entry on that machine, on PGLite or Postgres (setup refuses it where OpenClaw or Hermes is installed); for a harness several people talk to, give each person a key over HTTP instead (`gbrain serve --http` with `gbrain auth create <name> --member <id>` keys). `gbrain doctor` fails `shared_stdio_binding` when `mcp.stdio_member` is set on a host where OpenClaw or Hermes is installed and the brain serves several people. A shared agent instead lists whom it may act for (`--may-act-for`) and names the person on each call. Last resort, for a team that shares everything: `gbrain auth rescope --token <name> --reads-unscoped --yes` lets that one credential read every page no rule restricts for whoever is asking (`--reads-unscoped none` takes it back). |-| <a id="requester_scope_unknown"></a>`requester_scope_unknown` | A remote read came from a connection bound to nobody, and gbrain could not tell whether the brain serves one person or several: its config read failed (a statement timeout, a lock wait or a dropped pooled connection) and so did one re-read of the serves keys. Nothing was read. The message does not claim the brain serves several people, because that is what could not be read. A connection bound to a member is never refused this way. | Retry the same call after `retry_after_ms` (`fix.next` is `wait`). If it keeps failing, the brain host's operator checks the database with `gbrain doctor --json`. |+| <a id="requester_scope_unknown"></a>`requester_scope_unknown` | A remote read came from a connection bound to nobody, and gbrain could not tell whether the brain serves one person or several: its config read failed (a statement timeout, a lock wait or a dropped pooled connection) and so did one re-read of the serves keys. Nothing was read. The message says the brain's settings could not be read and that this is not an access decision; it does not claim the brain serves several people, because that is what could not be read. This applies on a brain pinned `access.serves one` too, since the pin is one of the settings that failed to read. A connection bound to a member is never refused this way. | Retry the same call after `retry_after_ms` (`fix.next` is `wait`). If it keeps failing, the brain host's operator checks the database with `gbrain doctor --json`; `fix.verify` (`gbrain access serves --json`, read-only) confirms the settings read again. || <a id="credential_scope_required"></a>`credential_scope_required` | `gbrain auth create` or `gbrain auth register-client` was asked for a credential bound to no member on a brain that serves several people. Nothing was created. | Pass `--member <id>` (`gbrain access member list`), or `--may-act-for <members>` for a shared agent. `--reads-unscoped --yes` creates one that reads unscoped on purpose. |## Attested-actor refusalsdiff --git a/src/core/access/requester-scope.ts b/src/core/access/requester-scope.tsindex b1e72c219f..49fa448cb6 100644--- a/src/core/access/requester-scope.ts+++ b/src/core/access/requester-scope.ts@@ -161,11 +161,12 @@ export async function withServesReread<T extends Partial<CallerAccess>>(engine:function requesterScopeUnknown(op: string, c: Connection): OperationError {return opError('requester_scope_unknown',- `Whether this brain serves one person or several could not be read (its config read failed twice), so ${op} from ${c.handle}, which is bound to no member, was refused and nothing was read.`,+ `This brain's settings could not be read (whether it serves one person or several; the config read failed twice), so ${op} from ${c.handle}, which is bound to no member, was not answered and nothing was read. This is not an access decision: the same call can succeed once the database answers.`,'Retry the same call in a few seconds. If it keeps failing, the brain host\'s operator checks the database with gbrain doctor --json.',{ retryable: true, detail: 'retry_after_ms=2000',fix: { argv: ['gbrain', 'doctor', '--json'], consent: [], actor: 'provider', requires_exclusive: false,- why: 'Nothing was read. Repeat the same call after about 2 s (retry_after_ms=2000); this read-only command shows whether the database is answering.' } });+ why: 'Nothing was read. Repeat the same call after about 2 s (retry_after_ms=2000); this read-only command shows whether the database is answering.',+ verify: { argv: ['gbrain', 'access', 'serves', '--json'] } } });}function requesterScopeRequired(op: string, c: Connection, serves: ServesPolicy, transport: Transport, reason: string): OperationError {diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex b58c5cfeb6..04a7948877 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -77,7 +77,7 @@ export const CODES = {access_policy_store_mismatch: { class: 'host_only', actor: 'user', summary: "A source's persisted folder-rule store (sources.config.access_store) disagrees with what this host sees (a git store with no visible work tree, or a database store whose root became a repository), so the persisted store and its applied rules stay in force and nothing switches on its own.", why: 'Inferring the store per host would let a missing checkout or a stray git init change which rules apply; only gbrain access rule migrate moves them, and neither direction widens.', suggestion: 'On the brain host, preview the move with gbrain access rule migrate --source <id>, then apply it by adding --yes.', fix: { argv: ['gbrain', 'access', 'rule', 'status', '--source', '{source_id}', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows the persisted store and the applied rules; changes nothing.' } },access_rule_invalid: { class: 'caller', docs: 'docs/guides/write-refusals.md#access_rule_invalid', summary: 'A folder rule given to gbrain access rule add is invalid (its prefix is not a literal lower-case folder ending in /, holds .. or *, its readers are not member ids or group:<id>, or another rule already covers the prefix), so nothing was written.', why: 'Prefixes are matched literally against slugs; a pattern or a typo would silently restrict the wrong pages or none.', suggestion: 'Write the prefix as a slug folder ending in / (partners/alice-example/) and the readers as member ids or group:<id>.' },requester_scope_required: { class: 'host_only', actor: 'user', reasons: ['grace_ended', 'created_after', 'since_unknown'], docs: 'docs/guides/write-refusals.md#requester_scope_required', summary: 'A remote read came from a connection bound to no member (an access token, an OAuth client or a local stdio server) on a brain that serves several people (two or more enabled members, or config access.serves = several), so it was refused before any work and nothing was read.', why: 'On a brain that serves several people a connection bound to nobody reads every page no rule restricts, for whoever is asking; gbrain refuses rather than guess whose notes a read is for. A connection that existed when the brain started serving several people gets 14 days of in-band notices first (reason grace_ended); one created after that is refused at once (created_after).', suggestion: 'On the brain host, bind the connection to the person it serves: gbrain auth rescope --token <name>|--client <id> --member <id> (preview with gbrain access check --token <name>); for a stdio server, when only one person uses that harness, gbrain setup claude-code --stdio-member <id> (gbrain setup codex --stdio-member <id> on Codex), which binds that one harness entry on that machine (refused where OpenClaw or Hermes is installed); for a harness several people talk to, give each person a key over HTTP instead (gbrain serve --http with gbrain auth create <name> --member <id> keys). A shared agent lists whom it may act for (--may-act-for) and names the person on each call. Last resort: --reads-unscoped --yes lets that one credential read every page no rule restricts for any asker.' },- requester_scope_unknown: { class: 'retryable', retryable: true, actor: 'provider', docs: 'docs/guides/write-refusals.md#requester_scope_unknown', summary: 'A remote read came from a connection bound to no member, and whether the brain serves one person or several could not be read (the config read failed, and so did one re-read), so it was refused before any work and nothing was read.', why: 'A statement timeout, a lock wait or a dropped pooled connection can fail one config read while the next read succeeds. Reading that as a one-person brain would let a connection bound to nobody read every page no rule restricts on a brain that may serve several people, so gbrain refuses until it can tell.', suggestion: 'Retry the same call in a few seconds. If it keeps failing, the brain host\'s operator checks the database with gbrain doctor --json. A connection bound to a member is never refused this way.' },+ requester_scope_unknown: { class: 'retryable', retryable: true, actor: 'provider', docs: 'docs/guides/write-refusals.md#requester_scope_unknown', summary: 'A remote read came from a connection bound to no member, and the brain\'s settings (whether it serves one person or several) could not be read: the config read failed, and so did one re-read. The call was not answered and nothing was read; this is not an access decision, and the same call can succeed once the database answers.', why: 'A statement timeout, a lock wait or a dropped pooled connection can fail one config read while the next read succeeds. Reading that as a one-person brain would let a connection bound to nobody read every page no rule restricts on a brain that may serve several people, so gbrain refuses until it can tell.', suggestion: 'Retry the same call in a few seconds. If it keeps failing, the brain host\'s operator checks the database with gbrain doctor --json. A connection bound to a member is never refused this way.' },credential_scope_required: { class: 'caller', docs: 'docs/guides/write-refusals.md#credential_scope_required', summary: 'gbrain auth create or gbrain auth register-client was asked for a credential bound to no member on a brain that serves several people, so nothing was created.', why: 'A credential bound to nobody on such a brain is refused on every read (requester_scope_required); creating one would hand out a key that cannot work, or one that reads everyone\'s unmarked notes.', suggestion: 'Bind it to the person it serves: gbrain auth create <name> --member <id> (gbrain access member list names the members). A shared agent passes --may-act-for <members> instead; --reads-unscoped --yes creates one that reads every page no rule restricts for any asker, on purpose.', fix: { argv: ['gbrain', 'access', 'member', 'list', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Read-only: lists the members a credential can be bound to.' } },access_serves_roster_empty: { class: 'caller', summary: 'gbrain setup --serves several or gbrain access serves several was given no people (no --members, an empty --members-file), so nothing was written.', why: 'Each person gets a member, a folder only they read and a key bound to them; the installer never guesses who they are.', suggestion: 'Name every person: --members alice-example,bob-example, or --members-file <file> with one id per line.' },access_serves_key_dir_in_git: { class: 'caller', summary: 'The directory the per-member keys would be written to is inside a git work tree, so no key, member or rule was written.', why: 'Key files hold live credentials; a file inside a checkout can be committed and pushed.', suggestion: 'Point GBRAIN_HOME at a directory outside any git checkout (the default is your home directory) and run the command again.' },diff --git a/test/requester-scope.test.ts b/test/requester-scope.test.tsindex 8526ba7ec4..176aadf0c8 100644--- a/test/requester-scope.test.ts+++ b/test/requester-scope.test.ts@@ -45,6 +45,7 @@ import { ownerLines } from '../src/commands/access.ts';import { buildBrainTools } from '../src/core/minions/tools/brain-allowlist.ts';import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';import { getBrainHotMemoryMeta } from '../src/core/facts/meta-hook.ts';+import { CODES } from '../src/core/error-registry.ts';import { testBackends } from './helpers/test-backends.ts';import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';import { runCli } from './helpers/cli-spawn.ts';@@ -232,6 +233,27 @@ for (const kind of testBackends()) {} finally { await engine.unsetConfig('access.serves'); }}, 60_000);+ test('N2: on a brain pinned one, a double config-read failure is a wait-and-retry for an unbound read, saying the settings could not be read; bound callers read', async () => {+ await engine.setConfig('access.serves', 'one');+ try {+ const out = await withConfigReadsFailing(true, () => search('old-unbound'));+ expect({ isError: out.isError, code: out.json.code }).toEqual({ isError: true, code: 'requester_scope_unknown' });+ const err = out.structured?.error;+ expect(err).toMatchObject({ code: 'requester_scope_unknown', detail: 'retry_after_ms=2000',+ fix: { next: 'wait', actor: 'provider', argv: ['gbrain', 'doctor', '--json'], consent: [], verify: { argv: ['gbrain', 'access', 'serves', '--json'] } } });+ expect({ retryable: out.json.retryable, class: out.json.class }).toEqual({ retryable: true, class: 'retryable' });+ expect(err.fix.why).toContain('retry_after_ms=2000');+ expect(CODES.requester_scope_unknown.why).toContain('config read');+ expect(out.json.message).toContain("settings could not be read");+ expect(out.json.message).toContain('not an access decision');+ expect(out.json.message).not.toMatch(/denied|bound to nobody|serves several/i);+ for (const canary of Object.values(PAGES)) expect(out.text).not.toContain(canary);+ const bound = await withConfigReadsFailing(true, () => search('alice-key'));+ expect(bound.isError).toBe(false);+ expect(bound.meta?.access?.requester_scope).toBeUndefined();+ } finally { await engine.unsetConfig('access.serves'); }+ }, 60_000);+test('on a one-person brain, a failed first read and a good re-read run the call with no notice', async () => {await engine.setConfig('access.serves', 'one');try {