Skip to content

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.md
index 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.md
index 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 refusals
diff --git a/src/core/access/requester-scope.ts b/src/core/access/requester-scope.ts
index 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.ts
index 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.ts
index 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 {