Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
GBRA-200: degraded stamp code table moves to MCP_META_CHANNELS; keep llms-full under budget
garrytan7ad4eaa6f4f5
diff --git a/docs/architecture/key-files/agent-contract.md b/docs/architecture/key-files/agent-contract.mdindex 9591e76586..be33db9262 100644--- a/docs/architecture/key-files/agent-contract.md+++ b/docs/architecture/key-files/agent-contract.md@@ -36,3 +36,4 @@ Spec: `docs/designs/AGENT_OPERATOR_WAVE.md`; wire goldens: `test/fixtures/agent-- `src/core/persistence/page-identity.ts` — B4: `pageIdentityError(present, msg)` (a deleted page throws canonical `page_not_found` with the frozen wire/journal `error` `page_identity_changed`; a replaced page keeps `page_identity_changed`), `isMissingPageMessage` (replays recover the distinction from the stored message; no schema change), `yamlLocator` (content-free ` at line L, column C`). Replays (`writeResponse` in `persistence/service.ts`) set `OperationError.receiptFields` (never serialized); `toAgentError` fills the registry fix template (`{slug}`/`{source_id}`/`{request_id}`/`{operation}`, strict per-field patterns, unfillable → dropped) and applies the principal-aware receipt rule (CLI principal → `gbrain write-request`; same-principal MCP → `get_write_request` when callable; otherwise host inspection, actor host_admin). Test: `test/write-receipt-remediation.test.ts`.- `scripts/build-agent-protocol.ts` — generated regions of the agent operator protocol (`bun run build:agent-protocol`, `--check` in verify and `regen:all`): the protocol page's transcripts from the frozen wire goldens, the AGENTS.md quick contract, and `skills/conventions/agent-operator-protocol.md`, the whole protocol page bundled with the skills (a shared dep every copy path carries) with its relative links made absolute. Drift test: `test/agent-protocol-doc.test.ts`.+- `src/core/persistence/write-grant.ts` — the one refusal for a remote write naming a source outside the caller's write grant (remember and every page mutation): `writable_source_ids` lists only the caller's own grant source (`[]` for a sentinel), identical whether the named source exists; remember's `fix` repeats the call against that source (GBRA-200).diff --git a/docs/architecture/key-files/google-and-loops-continued.md b/docs/architecture/key-files/google-and-loops-continued.mdindex de54728726..28ea569fdb 100644--- a/docs/architecture/key-files/google-and-loops-continued.md+++ b/docs/architecture/key-files/google-and-loops-continued.md@@ -7,7 +7,6 @@- `src/core/harness/verify.ts` — Randomized server-side memory verification with revision-conditional cleanup and retained mutation UUIDs, with separate transport, identity, authority, read, write/readback, delegation and cleanup verdicts. Lost mutation responses are reconciled before retry; server success never certifies native-harness activation or cross-conversation behavior.- `src/core/persistence/memory-mutations.ts` + `memory-prepare.ts` — managed `remember`, `forget`, and `forget_fact`: durable same-ID replay precedes entity/TTL/provider work; semantic append preparation preserves hidden canonical fences and revalidates dedup under page guards. Embedding preparation records the stored model/dimension generation and publication compares it under transaction row locks, preserving unchanged runtime overrides while refusing intervening migrations; fact vectors retain their actual provider model. Withdrawal admits and completes in one source-exclusive database transaction, independent of filesystem ownership, with durable mirror/projection work; the call then rebuilds the withdrawn pages' text projections before acknowledging, because a CLI process has no resident projection worker (a failed rebuild stays queued). `src/core/facts/single-prepare.ts` isolates provider preparation from the SQL-only semantic decision and propagates cooperative provider abort without degrading it into success. Preparation checkpoints prevent a late aborted result from reaching publication. Tests: `test/persistence-memory-mutations.test.ts` runs identical races on PGLite and PostgreSQL; `test/withdrawal-followup-writes.test.ts` covers writes after a forget whose effects stay queued. #5836: an omitted `entity` is inferred before admission (`inferRememberTarget`), and the inferred slug is used only when `planRememberTarget`'s checks pass as predicates (plus withdrawal, fence parse, no owner claim); otherwise the save is unattributed with `warnings` (`NO_ENTITY`/`ENTITY_LINK_FAILED`) + `hint`. The `entity_inferred` intent marker makes preparation dedup exact text only (never supersede) and notes the context; `test/remember-entity-inference.test.ts`. `remember.replaces` (caller-directed replacement): `decideReplacement` (`facts/single-prepare.ts`) replaces the cosine decision when the intent names a target; it is checked at submission (fail fast) and again in `validate` with the target row locked `FOR UPDATE`, so two replacements of one fact serialize and the second sees `target_superseded`. Refusals are `invalid_params` with code prefixes (`target_withdrawn`, `target_superseded` naming the chain head, `target_expired`, `replaces_entity_mismatch`, `replaces_cross_page`, `replaces_duplicate`); remote callers get `not_found` for private targets; equal text is a `duplicate` no-op. Every `superseded` outcome carries `superseded_fact_id` (plus `replaced_by_caller` for `replaces`). `forget` responses gain `similar_active` (`facts/similar-active.ts`) after commit and on replay, and `semantic_review: false` keeps the claim out of overnight review. Pinned by `test/remember-replaces.test.ts`. remember's write intent carries the transport-resolved `ctx.sessionId` (MCP `_meta.session_id`, clamped to 256 characters), and preparation stores it as the fact's `source_session`, so `recall({session_id})` finds remembered facts; identity only, never an authorization input (`test/remember-session.test.ts`). #7248: a folder-less `entity` must resolve strictly or is refused with candidates; pending replies carry `write_request.target` (`test/remember-entity-target-7248.test.ts`).-- `src/core/persistence/write-grant.ts` — the one refusal for a remote write naming a source outside the caller's write grant (remember and every page mutation): `writable_source_ids` lists only the caller's own grant source (`[]` for a sentinel), identical whether the named source exists; remember's `fix` repeats the call against that source (GBRA-200).- `src/core/page-state/import-guard.ts` — imported canonical bytes publish only after source/page identity and knowledge-revision CAS, including unchanged-file and legacy hash-repair paths. Prepared same-hash imports compare full canonical metadata and additive tags, since captured timestamps are excluded from content hashes. Tests: `import-revision-concurrency.test.ts`.- `src/core/persistence/{maintenance,root-registry,filesystem-guard,writer-guard-schema}.ts` — fail-closed legacy writer coverage: durable private refusal records and shared refusal-only root markers work before PGLite connect, resolve symlink ancestors, and retain stale roots conservatively. An unchanged per-tick refresh writes nothing: the registry directory and records are chmodded only when their mode differs and the directory is fsynced only when a record changed (`root-registry-idle-chmod-5297.test.ts`). The selected PGLite path is registered at connect/init and source claim refresh, so managed reinit refuses even offline; unmanaged backup acquires the stable sibling native lock through rename. SQL guards include free-text aliases and canonical source sync checkpoints; an update that changes only embedding, telemetry or write-attribution columns of facts/takes is a physical projection and passes without the coordinator. `docs/architecture/canonical-writers.tsv` is the finite writer census; `canonical-writer-inventory.test.ts` rejects unreviewed additions, and `persistence-writer-fences.test.ts`/`pglite-maintenance-fence.test.ts` exercise real engines, competing processes and separate homes.diff --git a/docs/protocol/AGENT_OPERATOR_v1.md b/docs/protocol/AGENT_OPERATOR_v1.mdindex c80b4e7423..60d11f4c8e 100644--- a/docs/protocol/AGENT_OPERATOR_v1.md+++ b/docs/protocol/AGENT_OPERATOR_v1.md@@ -879,22 +879,9 @@ per session); the stamp never is, so it is on every affected call.| CLI `--json`, object result (recall, get, think, context_pack, ...) | a top-level `degraded: { reasons: [...] }` key || CLI `--json`, array result (search, query, list_pages), and human output | the same one line on stderr |-`reasons` is sorted and unique. A code names a cause, never page text or a-source the caller cannot read:--| Code | Ops | Meaning |-|---|---|---|-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |-| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |-| `facts_unembedded` | recall | some facts in scope could not be compared with the question |-| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |-| `delta_incomplete` | delta | delta delivered less than is waiting |-| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |-| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |-| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |-| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |-| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |-| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |+`reasons` is sorted and unique, and a code names a cause, never page text or+a source the caller cannot read. Every code and the ops that emit it:+[`_meta` channels, Degraded stamp codes](MCP_META_CHANNELS.md#degraded-stamp-codes).**What you do.** Answer from the result with the caveat, and never tell theuser the brain has nothing on the subject. A transient code (`embed_timeout`,@@ -902,11 +889,9 @@ an `*_failed` code, `deadline`) may clear on a retry; the notices on thesame result carry the fix. Treat a code you do not know as degraded: the listgrows, and a code never changes meaning.-**Harness authors.** Count a call as degraded when `_meta.degraded.reasons`-is non-empty, or when a content block starts with `[gbrain degraded: `.-A caller-requested limit, page size or token budget that the caller can see-in the result (`listing_truncated`, `has_more`, a `next` cursor) is-pagination, not degradation, and is not stamped.+**Harness authors.** A call is degraded when `_meta.degraded.reasons` is+non-empty or a block starts with `[gbrain degraded: `. Pagination the caller+can see (`listing_truncated`, `has_more`, a `next` cursor) is not stamped.## Consent and preapprovaldiff --git a/docs/protocol/MCP_META_CHANNELS.md b/docs/protocol/MCP_META_CHANNELS.mdindex 58da7ae787..6a935112b7 100644--- a/docs/protocol/MCP_META_CHANNELS.md+++ b/docs/protocol/MCP_META_CHANNELS.md@@ -42,3 +42,21 @@ lives in JSON BODIES of eval commands — a third, unrelated plane. Ambientrecall rides content/hooks, not `_meta`.Adding a key: register it in the table above, one producer, additive-forever.++## Degraded stamp codes++The codes in `_meta.degraded.reasons` ([AGENT_OPERATOR_v1.md, Degraded stamp](AGENT_OPERATOR_v1.md#degraded-stamp)). The list grows; a code never changes meaning.++| Code | Ops | Meaning |+|---|---|---|+| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |+| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |+| `facts_unembedded` | recall | some facts in scope could not be compared with the question |+| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |+| `delta_incomplete` | delta | delta delivered less than is waiting |+| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |+| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |+| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |+| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |+| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |+| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |diff --git a/llms-full.txt b/llms-full.txtindex 8ebdd3928d..76b053e1fc 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -4392,22 +4392,9 @@ per session); the stamp never is, so it is on every affected call.| CLI `--json`, object result (recall, get, think, context_pack, ...) | a top-level `degraded: { reasons: [...] }` key || CLI `--json`, array result (search, query, list_pages), and human output | the same one line on stderr |-`reasons` is sorted and unique. A code names a cause, never page text or a-source the caller cannot read:--| Code | Ops | Meaning |-|---|---|---|-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |-| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |-| `facts_unembedded` | recall | some facts in scope could not be compared with the question |-| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |-| `delta_incomplete` | delta | delta delivered less than is waiting |-| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |-| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |-| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |-| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |-| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |-| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |+`reasons` is sorted and unique, and a code names a cause, never page text or+a source the caller cannot read. Every code and the ops that emit it:+[`_meta` channels, Degraded stamp codes](MCP_META_CHANNELS.md#degraded-stamp-codes).**What you do.** Answer from the result with the caveat, and never tell theuser the brain has nothing on the subject. A transient code (`embed_timeout`,@@ -4415,11 +4402,9 @@ an `*_failed` code, `deadline`) may clear on a retry; the notices on thesame result carry the fix. Treat a code you do not know as degraded: the listgrows, and a code never changes meaning.-**Harness authors.** Count a call as degraded when `_meta.degraded.reasons`-is non-empty, or when a content block starts with `[gbrain degraded: `.-A caller-requested limit, page size or token budget that the caller can see-in the result (`listing_truncated`, `has_more`, a `next` cursor) is-pagination, not degradation, and is not stamped.+**Harness authors.** A call is degraded when `_meta.degraded.reasons` is+non-empty or a block starts with `[gbrain degraded: `. Pagination the caller+can see (`listing_truncated`, `has_more`, a `next` cursor) is not stamped.## Consent and preapproval@@ -11184,87 +11169,4 @@ the [CHANGELOG](../../CHANGELOG.md#exit-code-changes-by-command).----## docs/integrations/reliability-repair.md--Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/integrations/reliability-repair.md--# Reliability repair--Two data-corruption classes can affect a brain on real Postgres or Supabase:-JSONB values stored double-encoded, and markdown bodies truncated at import.-`gbrain doctor` detects both, and the standalone `gbrain repair-jsonb`-command fixes the mechanically fixable class. PGLite brains are not affected-(PGLite parses text to jsonb natively, so the double-encode never happens-there).--## What the checks look for--**JSONB double-encode.** Writing `${JSON.stringify(x)}::jsonb` through-postgres.js stores a JSONB *string literal* instead of an object.-`frontmatter ->> 'key'` returns NULL; GIN indexes are ineffective. Columns-checked: `pages.frontmatter`, `raw_data.data`, `ingest_log.pages_updated`,-`files.metadata`. The write-side rule that prevents it is in-`docs/ENGINES.md` ("JSONB writes: never double-encode").--**Markdown body truncation.** A page whose `compiled_truth` is much shorter-than its `raw_data.data ->> 'content'` lost body content at import time (for-example, when a `---` horizontal rule was treated as a body/timeline-delimiter). Wiki-style pages with multiple `##`/`###` sections are the usual-casualty.--## Detect--```-gbrain doctor-```--Reports two checks:--- `jsonb_integrity` — counts double-encoded rows per table and points you- at `gbrain repair-jsonb`.-- `markdown_body_completeness` — heuristic for pages whose `compiled_truth`- is suspiciously short compared to `raw_data.data ->> 'content'`. A page- stored in segments has no `compiled_truth` column to compare, so it is not- checked; the check reports how many with `skipped_segmented: N`.--## Repair--For JSONB (mechanically fixable):--```-gbrain repair-jsonb-```--Runs `UPDATE <table> SET <col> = (<col>#>>'{}')::jsonb WHERE jsonb_typeof(<col>) = 'string'`-across every affected column. Idempotent. Second run reports 0 rows. Use-`--dry-run` to preview, `--json` for structured output. The `v0_12_2`-version migration runs this automatically on `gbrain upgrade`.--For truncated markdown bodies (source-dependent): the importer skips a file-whose content hash has not changed, and trailing whitespace is trimmed before-hashing, so a re-import needs a real edit to the page body. Make the edit, then-re-import:--```-gbrain sync # git-backed brain: commit the edit first-gbrain sync --working-tree # or import the uncommitted working tree-gbrain import <brain-root> --fresh # or re-import the root you originally imported;- # --fresh ignores a resume checkpoint that would skip the path-```--gbrain cannot recover content that is already lost if you no longer have-the source markdown file. `gbrain doctor` tells you which pages look short;-you decide whether to re-import from source or accept the truncation.--## Verify--```-gbrain doctor-```--All four `jsonb_integrity` rows should read zero. `markdown_body_completeness`-should match your expectations for the corpus.------# Migrationsdiff --git a/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.md b/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.mdindex f68fee172f..49bd5a2713 100644--- a/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.md+++ b/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.md@@ -881,22 +881,9 @@ per session); the stamp never is, so it is on every affected call.| CLI `--json`, object result (recall, get, think, context_pack, ...) | a top-level `degraded: { reasons: [...] }` key || CLI `--json`, array result (search, query, list_pages), and human output | the same one line on stderr |-`reasons` is sorted and unique. A code names a cause, never page text or a-source the caller cannot read:--| Code | Ops | Meaning |-|---|---|---|-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |-| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |-| `facts_unembedded` | recall | some facts in scope could not be compared with the question |-| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |-| `delta_incomplete` | delta | delta delivered less than is waiting |-| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |-| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |-| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |-| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |-| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |-| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |+`reasons` is sorted and unique, and a code names a cause, never page text or+a source the caller cannot read. Every code and the ops that emit it:+[`_meta` channels, Degraded stamp codes](https://github.com/garrytan/gbrain/blob/master/docs/protocol/MCP_META_CHANNELS.md#degraded-stamp-codes).**What you do.** Answer from the result with the caveat, and never tell theuser the brain has nothing on the subject. A transient code (`embed_timeout`,@@ -904,11 +891,9 @@ an `*_failed` code, `deadline`) may clear on a retry; the notices on thesame result carry the fix. Treat a code you do not know as degraded: the listgrows, and a code never changes meaning.-**Harness authors.** Count a call as degraded when `_meta.degraded.reasons`-is non-empty, or when a content block starts with `[gbrain degraded: `.-A caller-requested limit, page size or token budget that the caller can see-in the result (`listing_truncated`, `has_more`, a `next` cursor) is-pagination, not degradation, and is not stamped.+**Harness authors.** A call is degraded when `_meta.degraded.reasons` is+non-empty or a block starts with `[gbrain degraded: `. Pagination the caller+can see (`listing_truncated`, `has_more`, a `next` cursor) is not stamped.## Consent and preapprovaldiff --git a/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.md b/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.mdindex f68fee172f..49bd5a2713 100644--- a/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.md+++ b/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.md@@ -881,22 +881,9 @@ per session); the stamp never is, so it is on every affected call.| CLI `--json`, object result (recall, get, think, context_pack, ...) | a top-level `degraded: { reasons: [...] }` key || CLI `--json`, array result (search, query, list_pages), and human output | the same one line on stderr |-`reasons` is sorted and unique. A code names a cause, never page text or a-source the caller cannot read:--| Code | Ops | Meaning |-|---|---|---|-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |-| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |-| `facts_unembedded` | recall | some facts in scope could not be compared with the question |-| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |-| `delta_incomplete` | delta | delta delivered less than is waiting |-| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |-| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |-| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |-| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |-| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |-| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |+`reasons` is sorted and unique, and a code names a cause, never page text or+a source the caller cannot read. Every code and the ops that emit it:+[`_meta` channels, Degraded stamp codes](https://github.com/garrytan/gbrain/blob/master/docs/protocol/MCP_META_CHANNELS.md#degraded-stamp-codes).**What you do.** Answer from the result with the caveat, and never tell theuser the brain has nothing on the subject. A transient code (`embed_timeout`,@@ -904,11 +891,9 @@ an `*_failed` code, `deadline`) may clear on a retry; the notices on thesame result carry the fix. Treat a code you do not know as degraded: the listgrows, and a code never changes meaning.-**Harness authors.** Count a call as degraded when `_meta.degraded.reasons`-is non-empty, or when a content block starts with `[gbrain degraded: `.-A caller-requested limit, page size or token budget that the caller can see-in the result (`listing_truncated`, `has_more`, a `next` cursor) is-pagination, not degradation, and is not stamped.+**Harness authors.** A call is degraded when `_meta.degraded.reasons` is+non-empty or a block starts with `[gbrain degraded: `. Pagination the caller+can see (`listing_truncated`, `has_more`, a `next` cursor) is not stamped.## Consent and preapprovaldiff --git a/plugin/skills/conventions/agent-operator-protocol.md b/plugin/skills/conventions/agent-operator-protocol.mdindex f68fee172f..49bd5a2713 100644--- a/plugin/skills/conventions/agent-operator-protocol.md+++ b/plugin/skills/conventions/agent-operator-protocol.md@@ -881,22 +881,9 @@ per session); the stamp never is, so it is on every affected call.| CLI `--json`, object result (recall, get, think, context_pack, ...) | a top-level `degraded: { reasons: [...] }` key || CLI `--json`, array result (search, query, list_pages), and human output | the same one line on stderr |-`reasons` is sorted and unique. A code names a cause, never page text or a-source the caller cannot read:--| Code | Ops | Meaning |-|---|---|---|-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |-| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |-| `facts_unembedded` | recall | some facts in scope could not be compared with the question |-| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |-| `delta_incomplete` | delta | delta delivered less than is waiting |-| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |-| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |-| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |-| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |-| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |-| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |+`reasons` is sorted and unique, and a code names a cause, never page text or+a source the caller cannot read. Every code and the ops that emit it:+[`_meta` channels, Degraded stamp codes](https://github.com/garrytan/gbrain/blob/master/docs/protocol/MCP_META_CHANNELS.md#degraded-stamp-codes).**What you do.** Answer from the result with the caveat, and never tell theuser the brain has nothing on the subject. A transient code (`embed_timeout`,@@ -904,11 +891,9 @@ an `*_failed` code, `deadline`) may clear on a retry; the notices on thesame result carry the fix. Treat a code you do not know as degraded: the listgrows, and a code never changes meaning.-**Harness authors.** Count a call as degraded when `_meta.degraded.reasons`-is non-empty, or when a content block starts with `[gbrain degraded: `.-A caller-requested limit, page size or token budget that the caller can see-in the result (`listing_truncated`, `has_more`, a `next` cursor) is-pagination, not degradation, and is not stamped.+**Harness authors.** A call is degraded when `_meta.degraded.reasons` is+non-empty or a block starts with `[gbrain degraded: `. Pagination the caller+can see (`listing_truncated`, `has_more`, a `next` cursor) is not stamped.## Consent and preapprovaldiff --git a/scripts/llms-config.ts b/scripts/llms-config.tsindex e0118e417e..92fd3f3a9c 100644--- a/scripts/llms-config.ts+++ b/scripts/llms-config.ts@@ -376,6 +376,8 @@ export const SECTIONS: DocSection[] = [title: "docs/integrations/reliability-repair.md",description: "Data integrity recovery.",path: "docs/integrations/reliability-repair.md",+ // Linked, not inlined: the GBRA-200 degraded-stamp section in AGENT_OPERATOR_v1.md put llms-full.txt over FULL_SIZE_BUDGET.+ includeInFull: false,},],},diff --git a/skills/conventions/agent-operator-protocol.md b/skills/conventions/agent-operator-protocol.mdindex f68fee172f..49bd5a2713 100644--- a/skills/conventions/agent-operator-protocol.md+++ b/skills/conventions/agent-operator-protocol.md@@ -881,22 +881,9 @@ per session); the stamp never is, so it is on every affected call.| CLI `--json`, object result (recall, get, think, context_pack, ...) | a top-level `degraded: { reasons: [...] }` key || CLI `--json`, array result (search, query, list_pages), and human output | the same one line on stderr |-`reasons` is sorted and unique. A code names a cause, never page text or a-source the caller cannot read:--| Code | Ops | Meaning |-|---|---|---|-| a retrieval stage: `embed_unavailable`, `embed_timeout`, `expansion_failed`, `expansion_partial`, `rescore_skipped`, `vector_arm_failed`, `keyword_arm_failed`, `title_arm_failed`, `budget_dropped_all`, `budget_truncated`, `keyword_zero`, `cache_prestamp`, `rerank_passthrough`, `rerank_failed`, `keyword_relaxed_carried`, `safe_index_pending`, `vector_candidates_incomplete`, `keyword_candidates_incomplete`, `projection_pending`, `projection_by_design`, `projection_status_unknown`, `keyword_count_unavailable` | search, query, recall, find_experts; think and synthesize (their page search) | the stage in `_meta.retrieval.degraded` (every stage except the ranking-only `reranker_skipped`; `projection_pending` only when a pending page could match). `embed_unavailable` also covers a keyless brain and recall's keyword-only markers, so a keyless brain stamps every search |-| `no_query_terms`, `facts_embedding_column_missing`, `facts_read_failed` | recall | `facts_degraded.reason` of a question-ranked recall |-| `facts_unembedded` | recall | some facts in scope could not be compared with the question |-| `deadline`, `server_budget`, `budget_trimmed` | context_pack | `degraded_reason`: the pack is partial |-| `delta_incomplete` | delta | delta delivered less than is waiting |-| `file_held` | get_page | the page's newer file is held by sync; this is its last good revision |-| `gather_hybrid_failed`, `gather_takes_keyword_failed`, `gather_takes_vector_failed`, `gather_graph_failed`, `gather_anchor_hydrate_failed`, `gather_window_floor_failed` | think, synthesize | an evidence stream failed (the matching `GATHER_*_FAILED` warning) |-| `held_files`, `sources_not_readable`, `references_unavailable`, `mention_index`, `relational_chain`, `graph_walk_truncated`, `pinned_answer_stale` | the ops that emit the notice of that code | a `kind: degraded` notice about this result |-| `scan_deadline`, `unreadable_pages` | search_exact | `incomplete_reasons` other than the caller's `limit` |-| `source_stale`, `held_items` | open_loops | `stale` or `completeness: "partial"` |-| `link_coverage_behind`, `link_coverage_unread` | rank_entities | `coverage.state` |+`reasons` is sorted and unique, and a code names a cause, never page text or+a source the caller cannot read. Every code and the ops that emit it:+[`_meta` channels, Degraded stamp codes](https://github.com/garrytan/gbrain/blob/master/docs/protocol/MCP_META_CHANNELS.md#degraded-stamp-codes).**What you do.** Answer from the result with the caveat, and never tell theuser the brain has nothing on the subject. A transient code (`embed_timeout`,@@ -904,11 +891,9 @@ an `*_failed` code, `deadline`) may clear on a retry; the notices on thesame result carry the fix. Treat a code you do not know as degraded: the listgrows, and a code never changes meaning.-**Harness authors.** Count a call as degraded when `_meta.degraded.reasons`-is non-empty, or when a content block starts with `[gbrain degraded: `.-A caller-requested limit, page size or token budget that the caller can see-in the result (`listing_truncated`, `has_more`, a `next` cursor) is-pagination, not degradation, and is not stamped.+**Harness authors.** A call is degraded when `_meta.degraded.reasons` is+non-empty or a block starts with `[gbrain degraded: `. Pagination the caller+can see (`listing_truncated`, `has_more`, a `next` cursor) is not stamped.## Consent and preapprovaldiff --git a/skills/skills.lock.json b/skills/skills.lock.jsonindex 679d7b7b75..5069159d9a 100644--- a/skills/skills.lock.json+++ b/skills/skills.lock.json@@ -44,7 +44,7 @@"concept-synthesis/routing-eval.jsonl": "96dbd7d9c1b606e9e06262d0c06282399741e2bccb8eeb7b9ca88c20f44cda0e","context-audit/SKILL.md": "6d786629d40544ddaab4f4e6e333569d270bcb8b581589dc16fb9f8bcb4f6207","context-audit/routing-eval.jsonl": "fb1832e24cc1b04163a74c5cde72bca53050a66246ca902e1a5f40303f52b5ab",- "conventions/agent-operator-protocol.md": "5917f0ec04e7d5360ec8f313ff07a5c0fa3c72539ba15214333c2fab2634681e",+ "conventions/agent-operator-protocol.md": "19007782dfc86d4d744b8df73a5b83dfca49b89dd396919291183ecfcb41d8f5","conventions/brain-first.md": "e0e4d7c4b760213325dffd286baf934720816a0b6aac5338538a0463e8fe77d2","conventions/brain-routing.md": "392998d9a109b330c9225af4ca5c8798b0ff02eba4d441c93fdb7c263687d0c6","conventions/calibration.md": "500dc26bd7c8400f50dc4c16fd83f1a588f3e7e68c59050a21fd8a0f69e4d198",