Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (GBRA-156 /ship Step 9)

garrytandb1cc5dd2b44
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7bad05b671..69645560f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,13 +19,13 @@ identifiers and attribution are available in the pre-removal Git revision
| Situation | Before | Now |
|---|---|---|
| A remote `search` or `query` with no `limit`, embeddings on | the vector arm filled the mode's row limit with every page it could reach | every page with a keyword, title, alias or exact-identity match, plus pages found only by meaning up to 3 pages in total. A line after the results says how many were left out and that `limit` returns them; `_meta.retrieval.page_cap` counts them |
-| The same call with an explicit `limit`, a paged call (`offset`), or any local CLI call | | unchanged |
+| The same call with an explicit `limit`, a paged call (`offset`), or any CLI call on the brain host (a thin-client CLI call is remote, so it gets the cap; pass `--limit` for every row) | | unchanged |
| A brain with no embedding model (keyword search) | | unchanged: every keyword match comes back |
| Changing the cap | | `gbrain config set search.remote_page_cap <n>`; `0` turns it off |
-| An unscoped remote `search`, `query`, `recall` or `list_pages` from a connection with no source grant, when every source it reads holds no page and other sources do | `[]` with a `sources_not_readable` notice (kind degraded) | refused with `sources_not_readable` (class host_only). The fix runs on the brain host: `gbrain sources federate <source>`, with the source the user picks, or a grant for the token (`gbrain auth rescope --token <name> --sources <ids>`). It never names a source the connection cannot read |
+| An unscoped remote `search`, `query`, `recall` or `list_pages` from a connection with no source grant that comes back empty, when every source it reads holds no page (for `recall` and `query`, no world fact either) and other sources do | `[]` with a `sources_not_readable` notice (kind degraded) | refused with `sources_not_readable` (class host_only). The fix runs on the brain host: `gbrain sources federate <source>`, with the source the user picks, or a grant for the token (`gbrain auth rescope --token <name> --sources <ids>`). It never names a source the connection cannot read |
| The same read when its sources hold pages that match nothing, or on a brain with no pages; any read from a token granted sources, an OAuth client, a bound connection, or one that names `source_id` or `source_ids` | | unchanged |
-| `gbrain sources add` without `--federated` or `--no-federated` on a brain where connections with no source grant read no page | a stderr warning | also `next: gbrain sources federate <id>` on stdout |
-| `gbrain sources add --json` | not available | `{id, name, local_path, remote_url, federated, next?}` on stdout; the human lines move to stderr |
+| `gbrain sources add` without `--federated` or `--no-federated` on a brain that is not managed, where connections with no source grant read no page | a stderr warning | also `next: gbrain sources federate <id>` on stdout |
+| `gbrain sources add --json` on a brain that is not managed (a managed brain prints its lifecycle receipt, as before) | not available | `{id, name, local_path, remote_url, federated, next?}` on stdout; the human lines move to stderr |
Every vector path (the hybrid vector arm, the embedding-failure fallback and the `query` image branch) now has a test proving it reads only the sources the keyword path reads, for granted tokens and per-call `source_id`/`source_ids`, on PGLite and Postgres. No scope gap was found.
diff --git a/docs/architecture/key-files/agent-contract.md b/docs/architecture/key-files/agent-contract.md
index eb4b3e7758..93802b8b9b 100644
--- a/docs/architecture/key-files/agent-contract.md
+++ b/docs/architecture/key-files/agent-contract.md
@@ -23,7 +23,7 @@ Spec: `docs/designs/AGENT_OPERATOR_WAVE.md`; wire goldens: `test/fixtures/agent-
- `src/cli/json-guard.ts` — picks the `--json` guard mode for an invocation: on only when `jsonRequested(argv)` and the command-table record declares `json: 'document' | 'ndjson'`; wires the E11 `json_document_missing` hook (document mode, exit 0; the event records `command`, `version`, `guard: 'document'` and `exit_code: 0`, never argv values; `outcome` keeps its value, #6629/D26). The guard itself is `installStdoutPipeDelivery({ json })` in `src/core/cli-force-exit.ts`: stdout writes and console.log/info/debug go to stderr, only `writeStdoutFinal`/`writeNdjsonLine` reach fd 1, a non-zero exit with no document writes the fallback document, `spawnCliChild` pipes child stdout to stderr. Test: `test/cli-json-guard.test.ts`. A record whose subcommands differ in shape declares `jsonSubcommands` (keyed by the first positional after the command; `eval`). `writeCliError` adds `status:'error'` to the envelope under the ndjson guard; `writeCliRefusal` (cli-error.ts) keeps a site's pre-v1 stderr line and writes the envelope under `--json`. D5 (`test/cli-contract.test.ts`) has one row per declaration, `<command> <sub>` included.
- `scripts/check-agent-contract.ts` — syntax-only AST scanner (≈2 s) in `bun run verify` and `guards-manifest.tsv` (fixtures `test/fixtures/guards/check-agent-contract.ts/`). Rules: suggestion-less `OperationError`, `throw new Error` in ops/mcp/handlers, hand-built `fix`/`next_action` command strings, legacy advice keys, raw interactive stdin/readline/raw-mode outside `interaction.ts`/`consent.ts`, raw "re-run with --yes" strings outside `consent.ts`, `stdio: 'inherit'` outside `spawnCliChild`, marker literals outside `agent-output.ts`/`agent-markers.ts`, `verify.argv` naming a non-read-only command (read_only command-table records + a static read-only list), plus unregistered codes and code naming (never baselined). Two more never-baselined rules keep every refusal's next step site-specific: `defaulted-suggestion` (a function that builds an error through `opError`, `new OperationError`, `usageError`, `invalidParam` or `hostOnlyError` from a `*suggestion`/`*hint` parameter with a default, an optional marker or a `??` fallback) and `generic-suggestion` (a suggestion whose whole text is a denylisted phrase such as "see --help", "check your input" or "try again", at a constructor or at a call site of a file-local funnel). `funnelSites(files?)` lists every funnel call site (`invalid`, `fail`, `usage`, `deny`, …) with its literal suggestion texts, resolving file-level string constants; `test/helpers/agent-envelope.ts` (`expectFunnelSuggestions`, `envelopeFor`, `caught`) drives the per-funnel table tests in each module's owner test. Per-rule shrink-only baselines in `scripts/agent-contract-baselines/<rule>.tsv`; `--update` lowers them and refuses growth.
- `src/core/interop-notices.ts` — Lane F notice producers (pure; callers emit). `DEGRADED_STAGE_GUIDANCE` (closed, typed exhaustive over recall-affecting stages + the verbs' markers) → one `degraded_recall` notice (kind degraded: names the stages, says a thin result is not proof of absence; fix = the embeddings enablement or a doctor diagnostic; a `rerank_failed` stage names its reason, the `fused_order` fallback and the session's reranker-degraded call count, and when no other stage needs a fix its fix follows the reason: `timeout`/`rate_limited` repeat the same call after 5/20 s (`actor: provider`, `next: wait`), `auth` is the user's key (credentials), the rest run doctor verified by `reranker_health` (`test/rerank-degraded-notice.serial.test.ts`); none on a brain keyless by choice, whose why says no query text was sent and that `gbrain doctor --json` names the enable command). `embeddingOptedOutFor` reads the opt-out markers (search/query degraded reason `embedding_disabled`, recall `keyword_only_embedding_disabled` in `search_degraded` or `facts_degraded.reason`, think `QUESTION_EMBED_SKIPPED_EMBEDDING_DISABLED`); `factEmbeddingDisabled` (src/core/embedding-disabled.ts) gates every query and fact embed. With the call's `_meta.retrieval.coverage`, `degradedRecallNotice` leaves `projection_pending` out when no pending page could match the query, otherwise names the count in its why, and escalates when it is the only stage. `sourceBindingNarrowedNotice` (per-call info: a GBRAIN_SOURCE/.gbrain-source bound stdio read that came back empty while other sources are readable; fix = the explicit `source_id` read). `recallStagesFor` maps recall's `search_degraded` and `facts_degraded.reason` (question ranking) to stages. `recallInteropNotices` is dispatch's one producer call. `chatKeyFix` (credentials + paid, both providers, free fallback, never a key on a command line), `keylessThinkNotice`, `thinkNotSavedNotice`, `degradedDedupNotice`, `privateFactNotice` (#6606: a local... (line truncated to 2000 chars)
-- `src/core/sources-not-readable.ts` — `assertUnscopedReadReachesPages`, the `sources_not_readable` refusal (class host_only) dispatch runs before the handler: an unscoped `search`/`query`/`recall`/`list_pages` (no `source_id`, no non-empty `source_ids`) from a remote connection with no source grant (no `allowedSources`, `hasSourceGrant` not true, no stdio binding; OAuth clients always carry a grant) whose `federatedSearchScope` holds no live page while another live, unarchived source does. One `CASE WHEN EXISTS` read, fail-open on any error. The message and suggestion never name a hidden source; the fix is the host's `gbrain sources federate <source>` (`hostFix`, input `source`: ask the user), with the token rescope named in the suggestion. A scope holding pages that matched nothing and a brain with no pages read as before (`test/mcp-sources-not-readable.test.ts`).
+- `src/core/sources-not-readable.ts` — `assertUnscopedReadReachesPages`, the `sources_not_readable` refusal (class host_only) dispatch runs after a handler's empty result (`emptyRead`, so a read that returns rows costs no extra query): an unscoped `search`/`query`/`recall`/`list_pages` (no `source_id`, no non-empty `source_ids`) from a remote connection with no source grant (no `allowedSources`, `hasSourceGrant` not true, no stdio binding; OAuth clients always carry a grant) whose `federatedSearchScope` holds no live page (for `recall` and `query`, no world fact either) while another live, unarchived source does. One `CASE WHEN EXISTS` read, fail-open on any error. The message and suggestion never name a hidden source; the fix is the host's `gbrain sources federate <source>` (`hostFix`, input `source`: ask the user), with the token rescope named in the suggestion. A scope holding pages that matched nothing and a brain with no pages read as before (`test/mcp-sources-not-readable.test.ts`).
- `src/mcp/status-mode.ts` + `src/commands/serve-status.ts` + `src/commands/serve-http-status.ts` + `src/core/serve-http-status-marker.ts` — F4 status-only serve, stdio and `--http`. cli.ts hands over a host-brain `serve` (not `--fail-fast`/`GBRAIN_SERVE_FAIL_FAST=1`) with no config, an unreadable config, a missing or repair-failed brain, or a PGLite lock held by a live holder; `runStatusModeServe` is the one entry point for both transports and logs `serve_status_mode_enter` / `serve_status_mode_recovered` (`reason`, `transport`, `elapsed_ms`) as one-line JSON on stderr. `probeStatus` reads config + `peekLock` only; `reprobe(state, connect)` is the one re-probe (no lock attempt while blocked, `resetReadinessMemo()` before the throw-only connect from `src/core/engine-connect.ts`); a check that must run on every re-probe hooks the `probeAgain` wrapper in `runStatusModeServe`. stdio: a gated lazy engine (`createDegradedEngine` with the configured `kind`, reconnect `statusReconnect`, ≤1 attempt / 5 s inside tool calls) marked with `StatusModeState`; `statusPayload` → `{status, reason, why (lock owner PID/transport, brain path, config path), fix, user_message, decisions, share_http_plan}`. `--http`: `runHttpStatusServe` binds one `node:http` listener with a mutable handler (`/health` 503 + `Retry-After: 5` + `instance`; `/mcp` stateless SDK server with only `gbrain_status`; every other route a 503 `serve_status_only` envelope), each response built from the allowlist in `httpStatusPayload`/`httpStatusEnvelope` with `reason` collapsed to `unavailable`; a single-flight chained 5 s tick runs the re-probe, and on a connect `runServe(..., { adoptServer })` builds the full app and swaps the handler on the same listener; a failed build disconnects the engine and stays status-only (`brain_unopenable`); SIGINT/SIGTERM during a recovery waits for it, then closes once. The marker `GBRAIN_HOME/serve-http-status-<port>.json` `{pid, instance_nonce, brain_id, bind, port, reason, since}`... (line truncated to 2000 chars)
- `src/mcp/initialize-context.ts` — per-initialize inputs for the generated instructions (`httpInstructionTools`: the tools/list filters with publish gates read on initialize; `instructionReadiness`: config plane + probed tier within 250 ms, HTTP view redacted) and `stdioCapabilityReadiness` (F2). Test: `test/mcp-capabilities-readiness.test.ts`.
- `src/mcp/hidden-tool-hint.ts` + `src/core/ops/cli-equivalent.ts` — F6: on the owner's stdio pipe a real tool outside the surface/read-only access gets `unknown_tool` naming itself and its CLI equivalent (`cliEquivalent`: `cliOnly` argv, curated overrides, `cliHints.name`, else `gbrain call`). Where `request_tools` is callable and session widening is on, the fix is `request_tools {surface:'full'}` (`next: run`, argv kept); otherwise the CLI equivalent with actor `user` and a `user_message`; `why` names the lasting route (`GBRAIN_SURFACE=full` in the harness's per-server env, or a `--surface full` re-registration) and that an inherited `GBRAIN_SURFACE` overrides a pinned `--surface`. Read-only access never offers a widen. HTTP stays opaque. `scripts/generate-plugin-tree.ts` appends the same map as a per-skill note to generated starter-gap skills. Test: `test/hidden-tool-hint.test.ts`. D2: `hiddenToolRoute(op, ToolConnection)` is the one decision for every transport (`callable` | `widen {surface}` | `host {read_only|surface|grant}`): a widen is offered only when the widened connection could call the tool (read-only access, `GBRAIN_MCP_FORCE_SURFACE`, the grant's snapshot/scopes and an operator pin all hold); dispatch builds the connection with `toolConnection(opts)`. `hiddenToolNext` turns a route into the D2 fix (the call itself; request_tools; on HTTP the D4 grant repair; on stdio the CLI equivalent with the call's arguments as flags).
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index ac00ff4bbe..43a1b9f2a6 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -4079,7 +4079,7 @@ More: [docs/guides/write-refusals.md#slug_page_mismatch](../../docs/guides/write
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| An unscoped search, query, recall or list_pages was refused before it ran: every source this connection can read (the default source and federated sources) holds no page, while other sources on the brain hold pages it cannot read (not federated, and no source grant). | Answering would return an empty result that reads like a clean miss. The refusal names the host command that federates a source or grants this connection the sources it should read; it never names a hidden source and never widens access. A scope that holds pages but matched nothing, a granted token, an OAuth client, a bound connection and a read that names a source are never refused. | Only the brain host's operator can resolve this. Tell the user the message and run `gbrain doctor --json` on the brain host. | host_admin | `gbrain doctor --json` | 1 | no |
+| An unscoped search, query, recall or list_pages came back empty and was refused: every source this connection can read (the default source and federated sources) holds no page (for recall and query, no world fact either), while other sources on the brain hold pages it cannot read (not federated, and no source grant). | Answering would return an empty result that reads like a clean miss. The refusal names the host command that federates a source or grants this connection the sources it should read; it never names a hidden source and never widens access. A scope that holds pages but matched nothing, a granted token, an OAuth client, a bound connection and a read that names a source are never refused. | Ask the user which source these connections should read; the brain host runs `gbrain sources federate <source>`, or grants the token its sources with `gbrain auth rescope --token <name> --sources <ids>`. | host_admin | `gbrain doctor --json` | 1 | no |
More: [docs/guides/multi-source-brains.md#an-unscoped-connection-whose-sources-hold-no-pages](../../docs/guides/multi-source-brains.md#an-unscoped-connection-whose-sources-hold-no-pages)
diff --git a/docs/guides/multi-source-brains.md b/docs/guides/multi-source-brains.md
index fd0c91e2c8..4d9e708020 100644
--- a/docs/guides/multi-source-brains.md
+++ b/docs/guides/multi-source-brains.md
@@ -124,8 +124,9 @@ all live in such sources would answer that connection's every search with an
empty result that reads like a clean miss.
So an unscoped `search`, `query`, `recall` or `list_pages` from such a
-connection is refused with `sources_not_readable` when the sources it reads
-hold no page at all while other sources on the brain hold pages. The refusal
+connection that comes back empty is refused with `sources_not_readable` when
+the sources it reads hold no page at all (for `recall` and `query`, no world fact either)
+while other sources on the brain hold pages. The refusal
never names a source the connection cannot read. Its fix is host-side: the
user picks the source these connections should read and the brain host runs
`gbrain sources federate <source>`, or grants the connection its sources
@@ -138,10 +139,11 @@ sources, an OAuth client, a bound connection and a read that names
call, never widens what it reads. Federating a source never shows its
`visibility: private` pages to a remote connection.
-`gbrain sources add` warns on stderr when a new source is not federated, and
+On a brain that is not managed, `gbrain sources add` warns on stderr when a new source is not federated, and
when the sources an unscoped connection reads hold no page it also prints the
next step on stdout (`next: gbrain sources federate <id>`), and as `next`
-(`command`, `argv`, `why`) under `--json`.
+(`command`, `argv`, `why`) under `--json`. A managed brain's `sources add`
+prints its lifecycle receipt instead, without the warning or the next step.
### Explicit reads from a bound agent connection
diff --git a/src/commands/sources.ts b/src/commands/sources.ts
index c2f07b5e72..2456228226 100644
--- a/src/commands/sources.ts
+++ b/src/commands/sources.ts
@@ -460,7 +460,7 @@ async function runAdd(engine: BrainEngine, args: string[]): Promise<void> {
` federated: ${fed}${fed ? ' — appears in cross-source default search' : ' — only searched when explicitly named via --source'}`,
);
if (!fed && federated === null) console.error(`Warning: source "${id}" is not federated. A remote token or agent connection with no source grant cannot read its pages, so its searches answer empty for them. Run \`gbrain sources federate ${id}\` to let every such connection read it, or grant one token with \`gbrain auth rescope --token <name> --sources ${id}\`.`);
- const next = !fed && federated === null ? await noGrantFloorNext(engine, id) : null;
+ const next = !fed && federated === null ? await noGrantFloorNext(engine, id).catch(() => null) : null;
if (next) say(` next: ${next.command} — ${next.why}`);
if (ghKind || gKind) {
say(` sync: run \`gbrain sync --source ${id}\` once; after its first sync, autopilot keeps it synced on the autopilot interval.`);
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index dc0f3618a2..3eb348b90b 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1304,9 +1304,9 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.460.0', text: 'Dream consolidation on a managed brain now closes a fenced fact in its page: the closing `valid_until` is written into the fact\'s row in the entity page\'s `## Facts` fence, published with the take, and the database row takes its value from that cell, so a later sync or re-import keeps the fact closed. Before, only the database row was closed and the next re-import of the page reopened it. A fact with no fence row is still closed in the database. A fenced fact whose fence row is on another page is left open. Facts an earlier release closed in the database only are not changed (GBRA-190).' },
// GBRA-95 RLS backfill. `since` is stamped at the merge slot.
{ since: '0.60.463.0', id: 'rls_backfill_unguarded_tables', text: 'On Postgres, a schema migration now enables row-level security on every gbrain table still without it. A table could be left without RLS because its RLS came only from a full schema replay, which `gbrain apply-migrations --yes` does not run (the four incremental-derivation tables, `page_segment_derivations`, `page_derivation_spend` and the two purge tables), or only from the auto-RLS event trigger, which needs a superuser and is absent on many managed brains. Supabase gives public tables anon and authenticated grants, so with the Data API on such a table was reachable with the anon key. Only a table still without RLS changes; one with a `GBRAIN:RLS_EXEMPT` comment is left alone; no row is read or written. Under a role that does not bypass RLS or does not own a table, the migration names the table on stderr and leaves it, and `gbrain doctor` (rls) keeps naming it with the fix. `gbrain repair missing-tables` now recreates a cache table with RLS on. A role that neither owns a table nor bypasses RLS reads no rows from it and cannot insert or update it once RLS is on (a read-only reporting role or a scoped write role, for example): give that role policies before upgrading (docs/ENGINES.md has the source-scope recipe), or, to keep a table open to it on purpose, add the `GBRAIN:RLS_EXEMPT reason=...` comment to that table. A write role set up with an earlier copy of that recipe also needs its new policies on `page_derivation_spend` and the two purge tables: without them its segmented derivation writes are refused, and the derivation purge triggers its writes fire read no purge, so they do not hold back a purged claim.' },
- { since: 'TBD', id: 'remote_page_cap_gbra156', text: 'A remote `search` or `query` that names no `limit` now returns every page that matched its words, a name or an exact identity, plus pages that matched only by meaning up to 3 pages in total (`search.remote_page_cap`, default 3; `0` turns it off). A line after the results says how many pages were left out, and `_meta.retrieval.page_cap` counts them. An explicit `limit`, a paged call and every local CLI call return the same rows as before.' },
- { since: 'TBD', id: 'sources_not_readable_refusal_gbra156', text: 'An unscoped remote `search`, `query`, `recall` or `list_pages` from a connection with no source grant, when every source it reads holds no page and other sources do, is now refused with `sources_not_readable` (host fix `gbrain sources federate <source>` with the source the user picks, or a grant for the token) instead of answering empty with a degraded notice. A scope that holds pages but matched nothing, a brain with no pages, granted tokens, OAuth clients, bound connections and reads that name a source behave as before.' },
- { since: 'TBD', id: 'sources_add_next_gbra156', text: '`gbrain sources add` without `--federated` or `--no-federated`, on a brain where connections with no source grant read no page, now prints `next: gbrain sources federate <id>` on stdout. `--json` prints `{id, name, local_path, remote_url, federated, next?}` on stdout and moves the human lines to stderr.' },
+ { since: 'TBD', id: 'remote_page_cap_gbra156', text: 'A remote `search` or `query` that names no `limit` now returns every page that matched its words, a name or an exact identity, plus pages that matched only by meaning up to 3 pages in total (`search.remote_page_cap`, default 3; `0` turns it off). A line after the results says how many pages were left out, and `_meta.retrieval.page_cap` counts them. An explicit `limit`, a paged call and every CLI call on the brain host (a thin-client CLI call is remote and gets the cap) return the same rows as before.' },
+ { since: 'TBD', id: 'sources_not_readable_refusal_gbra156', text: 'An unscoped remote `search`, `query`, `recall` or `list_pages` from a connection with no source grant that comes back empty, when every source it reads holds no page (for `recall` and `query`, no world fact either) and other sources do, is now refused with `sources_not_readable` (host fix `gbrain sources federate <source>` with the source the user picks, or a grant for the token) instead of answering empty with a degraded notice. A scope that holds pages but matched nothing, a brain with no pages, granted tokens, OAuth clients, bound connections and reads that name a source behave as before.' },
+ { since: 'TBD', id: 'sources_add_next_gbra156', text: '`gbrain sources add` without `--federated` or `--no-federated`, on a brain that is not managed where connections with no source grant read no page, now prints `next: gbrain sources federate <id>` on stdout. `--json` prints `{id, name, local_path, remote_url, federated, next?}` on stdout and moves the human lines to stderr. A managed brain prints its lifecycle receipt as before.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index c7a1cc52ce..e2fe323318 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -675,7 +675,7 @@ export const CODES = {
source_referenced: { class: 'caller', summary: "OAuth clients still reference this source." },
source_root_conflict: { class: 'caller', summary: "Multiple active sources alias this canonical skill root; resolve ownership before publishing." },
source_writeback_required: { class: 'host_only', summary: "Canonical preparation requires a source-content correction; this profile never writes repository files." },
- sources_not_readable: { class: 'host_only', retryable: false, summary: "An unscoped search, query, recall or list_pages was refused before it ran: every source this connection can read (the default source and federated sources) holds no page, while other sources on the brain hold pages it cannot read (not federated, and no source grant).", why: "Answering would return an empty result that reads like a clean miss. The refusal names the host command that federates a source or grants this connection the sources it should read; it never names a hidden source and never widens access. A scope that holds pages but matched nothing, a granted token, an OAuth client, a bound connection and a read that names a source are never refused.", docs: 'docs/guides/multi-source-brains.md#an-unscoped-connection-whose-sources-hold-no-pages' },
+ sources_not_readable: { class: 'host_only', retryable: false, summary: "An unscoped search, query, recall or list_pages came back empty and was refused: every source this connection can read (the default source and federated sources) holds no page (for recall and query, no world fact either), while other sources on the brain hold pages it cannot read (not federated, and no source grant).", why: "Answering would return an empty result that reads like a clean miss. The refusal names the host command that federates a source or grants this connection the sources it should read; it never names a hidden source and never widens access. A scope that holds pages but matched nothing, a granted token, an OAuth client, a bound connection and a read that names a source are never refused.", docs: 'docs/guides/multi-source-brains.md#an-unscoped-connection-whose-sources-hold-no-pages', suggestion: 'Ask the user which source these connections should read; the brain host runs `gbrain sources federate <source>`, or grants the token its sources with `gbrain auth rescope --token <name> --sources <ids>`.' },
split_bad_ratio: { class: 'caller', summary: "Split bad ratio." },
split_unparseable: { class: 'caller', summary: "Split unparseable." },
stable_channel_unresolved: { class: 'unavailable', reasons: ['unreadable', 'no_stable', 'no_release_tag'], summary: "`gbrain upgrade --channel stable` (or `self_upgrade.channel stable`) could not name the stable release: the repository's tags could not be read, no release has been promoted to stable yet, or the `stable` tag does not share a commit with a `v<version>` release tag. Nothing was changed.", why: "The stable channel installs only a release a maintainer promoted after the production-shaped soak passed on its exact tree; without that answer it installs nothing rather than guess.", docs: 'docs/guides/upgrades-auto-update.md#stable-channel', suggestion: 'Retry later, or upgrade on the latest channel with `gbrain upgrade --channel latest`.' },
diff --git a/src/core/sources-not-readable.ts b/src/core/sources-not-readable.ts
index afd90baa69..0375761f9f 100644
--- a/src/core/sources-not-readable.ts
+++ b/src/core/sources-not-readable.ts
@@ -1,12 +1,13 @@
/**
* GBRA-156: `sources_not_readable`, the refusal of an unscoped remote read
- * whose readable sources hold no page while other sources hold pages.
+ * that came back empty because its readable sources hold no page (and, for
+ * recall and query, no world fact) while other sources hold pages.
*
- * A connection with no source grant (a token minted without --sources, or
- * an unbound agent stdio connection) reads the default source plus the
+ * A connection with no source grant (a legacy token minted without --sources,
+ * whose hasSourceGrant is false, or an unbound agent stdio connection) reads the default source plus the
* federated ones. A new source is not federated by default, so such a
* connection could answer every search with an empty result that reads like
- * a clean miss. The read is refused before it runs instead, naming the host
+ * a clean miss. That empty answer is refused instead, naming the host
* command that makes the pages readable without naming any source the
* connection cannot read. A scope that holds pages but matched nothing, and a
* brain where no source holds a page, read as before. A connection whose
@@ -27,17 +28,20 @@ function namesSources(params: Record<string, unknown>): boolean {
return params.source_id !== undefined || (Array.isArray(ids) ? ids.length > 0 : typeof ids === 'string' && ids.trim() !== '');
}
-/** Throws `sources_not_readable` before an unscoped remote read that can only come back empty. */
+/** Throws `sources_not_readable` for an empty unscoped remote read whose scope holds nothing it could read. */
export async function assertUnscopedReadReachesPages(op: string, params: Record<string, unknown>, ctx: OperationContext): Promise<void> {
if (ctx.remote === false || !UNSCOPED_READ_OPS.has(op) || namesSources(params)) return;
- if (ctx.explicitReadBinding || ctx.auth?.allowedSources !== undefined || ctx.auth?.hasSourceGrant === true) return;
+ if (ctx.explicitReadBinding || (ctx.auth !== undefined && (ctx.auth.allowedSources !== undefined || ctx.auth.hasSourceGrant !== false))) return;
let refuse = false;
try {
const scope = federatedSearchScope(ctx);
const readable = scope.sourceIds ?? (scope.sourceId !== undefined ? [scope.sourceId] : null);
if (!readable) return;
+ const readableFacts = op === 'recall' || op === 'query'
+ ? ` OR EXISTS (SELECT 1 FROM facts WHERE source_id = ANY($1::text[]) AND visibility = 'world')`
+ : '';
const [row] = await ctx.engine.executeRaw<{ refuse: boolean }>(
- `SELECT CASE WHEN EXISTS (SELECT 1 FROM pages WHERE source_id = ANY($1::text[]) AND deleted_at IS NULL) THEN false
+ `SELECT CASE WHEN EXISTS (SELECT 1 FROM pages WHERE source_id = ANY($1::text[]) AND deleted_at IS NULL)${readableFacts} THEN false
ELSE EXISTS (SELECT 1 FROM pages p JOIN sources s ON s.id = p.source_id
WHERE p.deleted_at IS NULL AND s.archived IS NOT TRUE AND NOT (p.source_id = ANY($1::text[])))
END AS refuse`,
diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.ts
index ae908bb653..1c878ca422 100644
--- a/src/mcp/dispatch.ts
+++ b/src/mcp/dispatch.ts
@@ -25,7 +25,7 @@ import { logVerbUsage, recordsFiring, type RecordsFiring } from '../core/verbs/u
import { searchCountLine } from '../core/search/keyword-paging.ts';
import { pageCapLine } from '../core/search/remote-page-cap.ts';
import { dateLabelLine } from '../core/search/date-labels.ts';
-import { hiddenTakesNotice, localTranscriptsNotice, recallInteropNotices, wantsTranscriptHint } from '../core/interop-notices.ts';
+import { emptyRead, hiddenTakesNotice, localTranscriptsNotice, recallInteropNotices, wantsTranscriptHint } from '../core/interop-notices.ts';
import { assertUnscopedReadReachesPages } from '../core/sources-not-readable.ts';
import { hiddenToolHint, hiddenToolNext, hiddenToolRoute, type ToolConnection } from './hidden-tool-hint.ts';
import { opAllowedForBoundClient } from '../core/ops/context.ts';
@@ -1077,7 +1077,6 @@ async function dispatchResolvedCall(
enforceBoundClientOpAllowList(ctx.auth, op);
// #5575 CEO-18: a floored connection only reaches read ops that enforce its floor.
enforceReadTrustFloor(ctx.auth, op);
- await assertUnscopedReadReachesPages(name, safeParams, ctx);
// GBRA-156: a read op does not change what the hook reads, so it runs beside the handler (a degraded engine's reconnect stays the handler's).
const earlyMeta = opts.metaHook && op.mutating === false && !isEngineDegraded(engine) ? runMetaHook(opts.metaHook, name, ctx) : undefined;
const sharedStdio = ctx.transport === 'stdio' && !ctx.auth &&
@@ -1098,6 +1097,7 @@ async function dispatchResolvedCall(
return op.handler(ctx, safeParams);
})
: await op.handler(ctx, safeParams);
+ if (emptyRead(name, result)) await assertUnscopedReadReachesPages(name, safeParams, ctx);
// Hot memory built before a write (forget, remember, …) is never served after it, on every transport;
// #6696 (A4): the write's receipt carries the capacity notices (60 s snapshot, at most hourly per scope).
if (op.mutating) { invalidateHotMemoryForEngine(engine); notices.push(...await writeReceiptCapacityNotices(engine, ctx)); }
diff --git a/test/mcp-sources-not-readable.test.ts b/test/mcp-sources-not-readable.test.ts
index 300ed57f44..6de06b8fd7 100644
--- a/test/mcp-sources-not-readable.test.ts
+++ b/test/mcp-sources-not-readable.test.ts
@@ -23,6 +23,7 @@ import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { callTool, clientCredentialsToken, envelopeOf, legacyToken, ownerCookie, registerOAuthClient, startServeHttp, type LiveServeHttp, type ToolResultWire } from './helpers/live-mcp-servers.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
@@ -73,6 +74,25 @@ for (const kind of testBackends()) {
expect(rows(out)).toEqual([]);
}, 60_000);
+ // Generated by gstack /ship Step 7 coverage audit (GBRA-156).
+ // Value: protects=pages held only by an archived source never trigger the refusal; the read answers empty as before;
+ // fails_when=the archived filter is dropped and the refusal tells the user to federate an archived source;
+ // why_new=no test puts pages in an archived source; seam=none;
+ // no_claim=archive lifecycle commands (archived flag set by SQL; PGLite or Postgres unit)
+ test('pages held only by an archived source do not trigger the refusal', async () => {
+ await engine.executeRaw(`INSERT INTO sources (id, name) VALUES ('source-archived', 'source-archived') ON CONFLICT (id) DO NOTHING`);
+ await importFromContent(engine, 'notes/archived-ledger', '# Archived\nThe quillmarsh ledger, archived copy.', { sourceId: 'source-archived', noEmbed: true });
+ await engine.executeRaw(`UPDATE sources SET archived = true WHERE id = 'source-archived'`);
+ try {
+ const out = await callTool(serve.base, noGrant, 'search', { query: QUERY });
+ expect(out.isError).not.toBe(true);
+ expect(rows(out)).toEqual([]);
+ } finally {
+ await engine.executeRaw(`DELETE FROM pages WHERE source_id = 'source-archived'`);
+ await engine.executeRaw(`DELETE FROM sources WHERE id = 'source-archived'`);
+ }
+ }, 60_000);
+
test('pages arrive in a source the no-grant floor cannot read', async () => {
await importFromContent(engine, 'notes/quillmarsh-ledger', `# Ledger\nThe quillmarsh ledger for the harbour team, ${CANARY}.`, { sourceId: HIDDEN, noEmbed: true });
});
@@ -92,6 +112,67 @@ for (const kind of testBackends()) {
}, 60_000);
}
+ // Generated by gstack /ship Step 7 coverage audit (GBRA-156).
+ // Value: protects=an unbound stdio agent connection is refused like a no-grant token, and a GBRAIN_SOURCE-bound one never is;
+ // fails_when=the explicitReadBinding exemption is dropped (bound reads refused) or the stdio transport skips the check;
+ // why_new=every refusal test drives serve-http tokens only; seam=none;
+ // no_claim=binding resolution from GBRAIN_SOURCE (binding passed as dispatch opts; unit only)
+ test('stdio: an unbound connection is refused, and a connection bound to a source is not', async () => {
+ const stdio = { remote: true, transport: 'stdio' as const, sourceId: 'default', takesHoldersAllowList: ['world'] };
+ const unbound = await dispatchToolCall(engine, 'list_pages', {}, stdio);
+ expect(unbound.isError).toBe(true);
+ expect(JSON.parse(unbound.content[0]!.text).error).toBe('sources_not_readable');
+ expect(JSON.stringify(unbound.content)).not.toContain(HIDDEN);
+ const bound = await dispatchToolCall(engine, 'list_pages', {}, {
+ ...stdio, explicitReadBinding: { sourceId: 'default', via: 'GBRAIN_SOURCE', sourceIds: ['default'], optedOut: [] },
+ });
+ expect(bound.isError).not.toBe(true);
+ expect(JSON.parse(bound.content[0]!.text)).toEqual([]);
+ }, 60_000);
+
+ // Value: protects=recall and query (its facts arm) from a no-grant connection whose default source holds world facts (remember writes no page) are not refused, while a private fact alone still leaves recall refused;
+ // fails_when=the refusal decides recall or query from pages alone, or counts facts a remote caller cannot read;
+ // why_new=the refusal tests seed pages only; seam=none;
+ // no_claim=fact extraction or the remember write path (fact rows inserted by SQL)
+ test('recall and query read world facts in a readable source and are not refused; a private fact does not count', async () => {
+ const [priv] = await engine.executeRaw<{ id: number }>(
+ `INSERT INTO facts (source_id, fact, visibility, source) VALUES ('default', 'The tidewell gauge is private.', 'private', 'test') RETURNING id`);
+ try {
+ const privOnly = await callTool(serve.base, noGrant, 'recall', {});
+ expect(privOnly.isError).toBe(true);
+ expect(envelopeOf(privOnly).code).toBe('sources_not_readable');
+ const [world] = await engine.executeRaw<{ id: number }>(
+ `INSERT INTO facts (source_id, fact, visibility, source) VALUES ('default', 'The tidewell gauge runs fast.', 'world', 'test') RETURNING id`);
+ try {
+ const out = await callTool(serve.base, noGrant, 'recall', {});
+ expect(out.isError).not.toBe(true);
+ expect(JSON.stringify(out.content)).toContain('tidewell gauge runs fast');
+ expect(JSON.stringify(out.content)).not.toContain('is private');
+ const query = await callTool(serve.base, noGrant, 'query', { query: 'zzyzx nothing matches this', expand: false });
+ expect(query.isError).not.toBe(true);
+ const search = await callTool(serve.base, noGrant, 'search', { query: QUERY });
+ expect(envelopeOf(search).code).toBe('sources_not_readable');
+ } finally {
+ await engine.executeRaw(`DELETE FROM facts WHERE id = $1`, [world!.id]);
+ }
+ } finally {
+ await engine.executeRaw(`DELETE FROM facts WHERE id = $1`, [priv!.id]);
+ }
+ }, 60_000);
+
+ // Value: protects=an authenticated context whose hasSourceGrant is undefined (OAuth or an unrestricted resident registration) never widens to federated sources, so it is never told to federate;
+ // fails_when=the gate refuses on hasSourceGrant undefined, the opposite of the scope resolver's convention;
+ // why_new=the serve-http OAuth test always carries a bound source; seam=none;
+ // no_claim=which transports produce hasSourceGrant undefined (auth passed as dispatch opts; unit only)
+ test('an auth context with hasSourceGrant undefined does not read the no-grant floor, so it is not refused', async () => {
+ const out = await dispatchToolCall(engine, 'list_pages', {}, {
+ remote: true, transport: 'http', sourceId: 'default', takesHoldersAllowList: ['world'],
+ auth: { token: 'x', clientId: 'client-undefined-grant', scopes: ['read'], sourceId: 'default' } as never,
+ });
+ expect(out.isError).not.toBe(true);
+ expect(JSON.parse(out.content[0]!.text)).toEqual([]);
+ }, 60_000);
+
test('an OAuth client always carries a grant (at least its bound source), so it is not refused', async () => {
const out = await callTool(serve.base, oauth, 'search', { query: QUERY });
expect(out.isError).not.toBe(true);
diff --git a/test/search-remote-page-cap.test.ts b/test/search-remote-page-cap.test.ts
index 737a93b6cd..fed0ae549f 100644
--- a/test/search-remote-page-cap.test.ts
+++ b/test/search-remote-page-cap.test.ts
@@ -139,6 +139,36 @@ for (const kind of testBackends()) {
}
}, 60_000);
+ // Generated by gstack /ship Step 7 coverage audit (GBRA-156).
+ // Value: protects=a malformed search.remote_page_cap (negative, fractional, text, blank) falls back to the default cap;
+ // fails_when=the integer guard is dropped and a bad value returns no vector page or the wrong count;
+ // why_new=only '5' and '0' were covered; seam=none;
+ // no_claim=config written through engine.setConfig, not the CLI config validator (PGLite unit only)
+ test(`${tool}: a malformed search.remote_page_cap falls back to the default cap`, async () => {
+ try {
+ for (const raw of ['-2', '2.5', 'many', ' ']) {
+ await engine.setConfig(REMOTE_PAGE_CAP_KEY, raw);
+ const out = await callTool(serve.base, token, tool, { query: 'saltpan orbit', ...base });
+ expect({ raw, pages: slugsOf(out).length, cap: (out._meta as any)?.retrieval?.page_cap?.cap })
+ .toEqual({ raw, pages: DEFAULT_REMOTE_PAGE_CAP, cap: DEFAULT_REMOTE_PAGE_CAP });
+ }
+ } finally {
+ await engine.unsetConfig(REMOTE_PAGE_CAP_KEY);
+ }
+ }, 60_000);
+
+ // Generated by gstack /ship Step 7 coverage audit (GBRA-156).
+ // Value: protects=a paged remote call (offset > 0, no limit) keeps today's rows and carries no page_cap;
+ // fails_when=the offset exemption is removed and page 2 of a remote search is cut to the cap;
+ // why_new=existing tests cover limit, local and cap 0, never offset; seam=none;
+ // no_claim=page boundaries across offsets (deterministic in-process embedding; PGLite)
+ test(`${tool}: a paged call (offset > 0) is not capped`, async () => {
+ const out = await callTool(serve.base, token, tool, { query: 'saltpan orbit', offset: 1, ...base });
+ expect(out.isError).not.toBe(true);
+ expect(slugsOf(out).length).toBeGreaterThan(DEFAULT_REMOTE_PAGE_CAP);
+ expect((out._meta as any)?.retrieval?.page_cap).toBeUndefined();
+ }, 60_000);
+
test(`${tool}: a trusted local call is not capped`, async () => {
const ctx = { engine, config: null, logger: console, dryRun: false, remote: false } as never;
const rows = await operationsByName[tool]!.handler(ctx, { query: 'saltpan orbit', ...base }) as Array<{ slug: string }>;
diff --git a/test/sources-add-federation-warning.test.ts b/test/sources-add-federation-warning.test.ts
index a23e865504..ab4ecad1d6 100644
--- a/test/sources-add-federation-warning.test.ts
+++ b/test/sources-add-federation-warning.test.ts
@@ -97,6 +97,42 @@ describe('sources add next step when the no-grant floor holds no page', () => {
expect(stderr).toContain('Created source "source-e"');
});
+ // Generated by gstack /ship Step 7 coverage audit (GBRA-156).
+ // Value: protects=a page in a federated non-default source counts as the no-grant floor holding a page, so no next step prints;
+ // fails_when=the floor query reads only the default source and tells the operator to federate when reads already work;
+ // why_new=the floor tests put pages only in the default source; seam=none;
+ // no_claim=remote read behavior after the add (console spies on the real command; PGLite)
+ test('a page in a federated non-default source fills the floor, so the add prints no next step', async () => {
+ await engine.putPage('notes/federated-page', { type: 'note', title: 'Federated', compiled_truth: 'A page in a federated source.', timeline: '' }, { sourceId: 'source-b' });
+ try {
+ const human = await add(['source-h']);
+ expect(human.stderr).toContain('source "source-h" is not federated');
+ expect(human.stdout).not.toContain('next:');
+ expect(JSON.parse((await add(['source-i', '--json'])).stdout).next).toBeUndefined();
+ } finally {
+ await engine.executeRaw(`DELETE FROM pages WHERE source_id = 'source-b'`);
+ }
+ });
+
+ // Value: protects=a failing floor read after the source is created never fails the add; the add still prints its result without a next step;
+ // fails_when=noGrantFloorNext's read error propagates and the committed add exits non-zero;
+ // why_new=no test fails the floor read; seam=engine.executeRaw spy that throws on the floor query only;
+ // no_claim=which database errors occur in practice (forced error; PGLite)
+ test('a floor read that fails never fails the add; it prints no next step', async () => {
+ const real = engine.executeRaw.bind(engine);
+ const raw = spyOn(engine, 'executeRaw').mockImplementation((async (sql: string, params?: unknown[]) => {
+ if (sql.includes('AS holds')) throw new Error('forced floor read failure');
+ return real(sql, params as never);
+ }) as never);
+ try {
+ const json = JSON.parse((await add(['source-j', '--json'])).stdout);
+ expect(json).toMatchObject({ id: 'source-j', federated: false });
+ expect(json.next).toBeUndefined();
+ } finally {
+ raw.mockRestore();
+ }
+ });
+
test('once the floor holds a page, the add warns but prints no next step', async () => {
await engine.putPage('notes/floor-page', { type: 'note', title: 'Floor', compiled_truth: 'A page in the default source.', timeline: '' });
const human = await add(['source-f']);