Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(reads): sources_not_readable counts pages search returns and active facts only (#7993)

garrytan84df752addaa
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 917a8556ba..de65314896 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -4640,7 +4640,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 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 |
+| 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 search returns (for recall and query, no active world fact either), while other sources on the brain hold such pages it cannot read (not federated, and no source grant). | Answering would return an empty result that reads like a clean miss. The check is one yes/no about the whole brain, independent of the query: whether another source holds pages; it never says another source matches the question. Quarantined pages count on neither side, nor private pages when remote reads exclude them. 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 4e0a19a4e9..a58c99e3d7 100644
--- a/docs/guides/multi-source-brains.md
+++ b/docs/guides/multi-source-brains.md
@@ -125,9 +125,11 @@ empty result that reads like a clean miss.
So an unscoped `search`, `query`, `recall` or `list_pages` from such a
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
+the sources it reads hold no page at all (for `recall` and `query`, no active world fact either)
+while other sources on the brain hold pages. Quarantined pages count on neither
+side. The check is one yes/no about the whole brain, independent of the query:
+whether another source holds pages. It never says another source matches the
+question, and it never names a source or page 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
(`gbrain auth rescope --token <name> --sources <ids>`).
diff --git a/src/commands/sources-add-next.ts b/src/commands/sources-add-next.ts
index b480049e35..0a3893aafb 100644
--- a/src/commands/sources-add-next.ts
+++ b/src/commands/sources-add-next.ts
@@ -11,6 +11,7 @@
import type { BrainEngine } from '../core/engine.ts';
import { localFederatedSourceIds } from '../core/source-resolver.ts';
import { privatePagesFilterFragment, resolveExcludePrivatePages } from '../core/search/private-visibility.ts';
+import { quarantineFilterFragment } from '../core/quarantine.ts';
export interface SourcesAddNext {
command: string;
@@ -18,10 +19,11 @@ export interface SourcesAddNext {
why: string;
}
-/** The federate step for `id` when the no-grant floor holds no live page a remote read may show, else null. */
+/** The federate step for `id` when the no-grant floor holds no live, unquarantined page a remote read may show, else null. */
export async function noGrantFloorNext(engine: BrainEngine, id: string): Promise<SourcesAddNext | null> {
const floor = (await localFederatedSourceIds(engine, 'default', 'seed_default')) ?? ['default'];
- const visible = await resolveExcludePrivatePages(engine, true) ? ` AND ${privatePagesFilterFragment('p')}` : '';
+ const visible = ` AND ${quarantineFilterFragment('p')}`
+ + (await resolveExcludePrivatePages(engine, true) ? ` AND ${privatePagesFilterFragment('p')}` : '');
const [row] = await engine.executeRaw<{ holds: boolean }>(
`SELECT EXISTS (SELECT 1 FROM pages p WHERE p.source_id = ANY($1::text[]) AND p.deleted_at IS NULL${visible}) AS holds`, [floor]);
if (row?.holds) return null;
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index af6d21fed8..c85cf99ac7 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -753,7 +753,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 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>`.' },
+ 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 search returns (for recall and query, no active world fact either), while other sources on the brain hold such pages it cannot read (not federated, and no source grant).", why: "Answering would return an empty result that reads like a clean miss. The check is one yes/no about the whole brain, independent of the query: whether another source holds pages; it never says another source matches the question. Quarantined pages count on neither side, nor private pages when remote reads exclude them. 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', retired_in: 'TBD', reasons: ['unreadable', 'no_stable', 'no_release_tag'],
diff --git a/src/core/sources-not-readable.ts b/src/core/sources-not-readable.ts
index 3ba1d46cac..a9211ce235 100644
--- a/src/core/sources-not-readable.ts
+++ b/src/core/sources-not-readable.ts
@@ -1,8 +1,10 @@
/**
* GBRA-156: `sources_not_readable`, the refusal of an unscoped remote read
* that came back empty because its readable sources hold no page it may read
- * (and, for recall and query, no world fact) while other sources hold such
- * pages. Private pages count on neither side when remote reads exclude them.
+ * (and, for recall and query, no active world fact) while other sources hold
+ * such pages. Quarantined pages count on neither side, nor private pages when
+ * remote reads exclude them. The check is one query-independent yes/no about
+ * the brain; it never says another source matches the question.
*
* 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
@@ -22,6 +24,7 @@ import { opError } from './ops/contract.ts';
import { federatedSearchScope } from './ops/context.ts';
import { hostFix } from './ops/op-fix.ts';
import { privatePagesFilterFragment, resolveExcludePrivatePages } from './search/private-visibility.ts';
+import { quarantineFilterFragment } from './quarantine.ts';
const UNSCOPED_READ_OPS: ReadonlySet<string> = new Set(['search', 'query', 'recall', 'list_pages']);
@@ -40,9 +43,11 @@ export async function assertUnscopedReadReachesPages(op: string, params: Record<
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')`
+ ? ` OR EXISTS (SELECT 1 FROM facts WHERE source_id = ANY($1::text[]) AND visibility = 'world'
+ AND expired_at IS NULL AND (valid_until IS NULL OR valid_until > now()))`
: '';
- const visible = await resolveExcludePrivatePages(ctx.engine, ctx.remote) ? ` AND ${privatePagesFilterFragment('p')}` : '';
+ const visible = ` AND ${quarantineFilterFragment('p')}`
+ + (await resolveExcludePrivatePages(ctx.engine, ctx.remote) ? ` AND ${privatePagesFilterFragment('p')}` : '');
const [row] = await ctx.engine.executeRaw<{ refuse: boolean }>(
`SELECT CASE WHEN EXISTS (SELECT 1 FROM pages p WHERE p.source_id = ANY($1::text[]) AND p.deleted_at IS NULL${visible})${readableFacts} THEN false
ELSE EXISTS (SELECT 1 FROM pages p JOIN sources s ON s.id = p.source_id
diff --git a/test/mcp-sources-not-readable.test.ts b/test/mcp-sources-not-readable.test.ts
index 1ec5645f58..f8b1ad2e0b 100644
--- a/test/mcp-sources-not-readable.test.ts
+++ b/test/mcp-sources-not-readable.test.ts
@@ -27,6 +27,7 @@ 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';
+import { noGrantFloorNext } from '../src/commands/sources-add-next.ts';
const HIDDEN = 'source-hidden';
const CANARY = 'harbourcanary';
@@ -258,6 +259,51 @@ for (const kind of testBackends()) {
}
}, 60_000);
+ // Value: protects=quarantined pages count on neither side (#7993): a floor holding only a quarantined page is still refused (and sources add still prints the federate step), and other sources holding only quarantined pages never prompt a federate fix that could not make them searchable;
+ // fails_when=the refusal check or noGrantFloorNext counts pages search never returns;
+ // why_new=the private-page test covers visibility only; seam=none; no_claim=how pages become quarantined (marker set by SQL)
+ test('quarantined pages count on neither side of the refusal, nor in the sources add step', async () => {
+ const quarantine = (where: string, params: unknown[]) => engine.executeRaw(
+ `UPDATE pages SET frontmatter = COALESCE(frontmatter, '{}'::jsonb) || '{"quarantine": {"reason": "junk_pattern"}}'::jsonb WHERE ${where}`, params);
+ await importFromContent(engine, 'notes/floor-quarantined', '# Floor\nA quarantined note in the default source.', { sourceId: 'default', noEmbed: true });
+ await quarantine("source_id = 'default' AND slug = 'notes/floor-quarantined'", []);
+ try {
+ for (const [tool, args] of READS.filter(([tool]) => tool !== 'list_pages')) {
+ expect(envelopeOf(await callTool(serve.base, noGrant, tool, args)).code).toBe('sources_not_readable');
+ }
+ expect((await noGrantFloorNext(engine, HIDDEN))?.argv).toEqual(['gbrain', 'sources', 'federate', HIDDEN]);
+ await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-quarantined'");
+ await quarantine('source_id = $1', [HIDDEN]);
+ for (const [tool, args] of READS) {
+ const out = await callTool(serve.base, noGrant, tool, args);
+ expect({ tool, isError: out.isError === true }).toEqual({ tool, isError: false });
+ expect(JSON.stringify(out.content)).not.toContain(CANARY);
+ }
+ } finally {
+ await engine.executeRaw(`UPDATE pages SET frontmatter = frontmatter - 'quarantine' WHERE source_id = $1`, [HIDDEN]);
+ await engine.executeRaw("DELETE FROM pages WHERE source_id = 'default' AND slug = 'notes/floor-quarantined'");
+ }
+ }, 60_000);
+
+ // Value: protects=only active world facts keep recall and query from the refusal (#7993); fails_when=a forgotten or lapsed world fact, which recall never returns, suppresses the refusal and the read answers empty;
+ // why_new=the facts test above seeds an active fact only; seam=none; no_claim=the forget write path (expired_at and valid_until set by SQL)
+ for (const state of ['forgotten', 'lapsed'] as const) {
+ test(`a ${state} world fact does not keep recall or query from the refusal`, async () => {
+ const [fact] = await engine.executeRaw<{ id: number }>(
+ `INSERT INTO facts (source_id, fact, visibility, source, expired_at, valid_until) VALUES ('default', 'The tidewell gauge runs fast.', 'world', 'test', $1::timestamptz, $2::timestamptz) RETURNING id`,
+ state === 'forgotten' ? [new Date().toISOString(), null] : [null, '2020-01-01T00:00:00Z']);
+ try {
+ for (const [tool, args] of [['recall', {}], ['query', { query: 'zzyzx nothing matches this', expand: false }]] as const) {
+ const out = await callTool(serve.base, noGrant, tool, args);
+ expect({ tool, code: envelopeOf(out).code }).toEqual({ tool, code: 'sources_not_readable' });
+ expect(JSON.stringify(out.content)).not.toContain('tidewell');
+ }
+ } finally {
+ await engine.executeRaw('DELETE FROM facts WHERE id = $1', [fact!.id]);
+ }
+ }, 60_000);
+ }
+
test('a default source that holds a page but matches nothing answers empty, not refused', async () => {
await importFromContent(engine, 'notes/floor-note', '# Floor\nAn unrelated note in the default source.', { sourceId: 'default', noEmbed: true });
try {