Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: Step 14.5 audit fixes (a page write outside the grant is permission_denied; saved_facts_withheld stamp code; traverse cap note)

garrytan69ec87a9efda
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fdb9b535a8..4a60e7cbc2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,7 @@ identifiers and attribution are available in the pre-removal Git revision
**A degraded or partial read now says so on the result itself.** Search, query, recall and the other reads already recorded degraded stages (an embedding timeout, a failed arm, a keyword-only brain, a held file) in notices and `_meta` fields that a harness had to know to look for, and recall and think dropped their page search's stages entirely. Every degraded or partial read result now carries one stamp naming why with stable codes. An MCP result gets `_meta.degraded: { reasons: [...] }` and one extra text block, `[gbrain degraded: <reasons>] ...`, after the others; a CLI `--json` object gets a `degraded` key, and other CLI output gets that line on stderr. A clean result carries no stamp, and no existing field changed. The code table is in docs/protocol/MCP_META_CHANNELS.md.
-**A write refused for naming another source says where the connection can write.** A `remember` or page write naming a `source_id` outside the connection's write grant is still refused `scope_denied`, and the refusal now carries `writable_source_ids`: the sources the connection's own grant lets it write, never another source, identical whether the named source exists or not. On `remember` the `fix` repeats the call against that source once the user agrees (`next: ask_user`, naming both sources), keeps the caller's visibility (a visibility the caller left out stays out, so the brain's default applies), and carries no request id; `forget`, `forget_fact` and page writes carry no fix.
+**A write refused for naming another source says where the connection can write.** A `remember` naming a `source_id` outside the connection's write grant is still refused `scope_denied` (a page write: `permission_denied`), and the refusal now carries `writable_source_ids`: the sources the connection's own grant lets it write, never another source, identical whether the named source exists or not. On `remember` the `fix` repeats the call against that source once the user agrees (`next: ask_user`, naming both sources), keeps the caller's visibility (a visibility the caller left out stays out, so the brain's default applies), and carries no request id; `forget`, `forget_fact` and page writes carry no fix.
### Itemized changes
diff --git a/docs/mcp/TOOL_REFERENCE.md b/docs/mcp/TOOL_REFERENCE.md
index 5795d4e53f..b967543acb 100644
--- a/docs/mcp/TOOL_REFERENCE.md
+++ b/docs/mcp/TOOL_REFERENCE.md
@@ -456,7 +456,7 @@ Submit an LLM agent job that the worker dispatches via the gateway-native tool l
## `traverse_graph`
-Traverse link graph from a page. Remote callers default to bidirectional edges (GraphPath[]) at depth 2 (pass depth explicitly for deeper walks); trusted local no-filter callers get the legacy node shape at depth 5. The walk is breadth-first: each page comes back once at its shortest depth and each edge once, and a walk stops at 20,000 visited pages or 5,000 edge rows, keeping the shallowest (a stderr note says when).
+Traverse link graph from a page. Remote callers default to bidirectional edges (GraphPath[]) at depth 2 (pass depth explicitly for deeper walks); trusted local no-filter callers get the legacy node shape at depth 5. The walk is breadth-first: each page comes back once at its shortest depth and each edge once, and a walk stops at 20,000 visited pages or 5,000 edge rows, keeping the shallowest (a stderr note says when, and the result carries a `graph_walk_truncated` degraded notice; above depth 1 its fix repeats the walk one level shallower).
| Parameter | Type | Guidance |
| --- | --- | --- |
diff --git a/docs/protocol/MCP_META_CHANNELS.md b/docs/protocol/MCP_META_CHANNELS.md
index cbd394887f..4899c23eb7 100644
--- a/docs/protocol/MCP_META_CHANNELS.md
+++ b/docs/protocol/MCP_META_CHANNELS.md
@@ -164,8 +164,8 @@ The codes in `_meta.degraded.reasons` ([AGENT_OPERATOR_v1.md, Degraded stamp](AG
| 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 |
+| 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`, `saved_facts_withheld` | 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`, `saved_facts_withheld` | 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 |
diff --git a/docs/protocol/MEMORY_VERBS_v1.md b/docs/protocol/MEMORY_VERBS_v1.md
index 55b3305898..bf9e4f591a 100644
--- a/docs/protocol/MEMORY_VERBS_v1.md
+++ b/docs/protocol/MEMORY_VERBS_v1.md
@@ -330,9 +330,9 @@ suggestion are unchanged.
#### write-grant refusal detail (additive)
-A `remember` (or page write) naming a `source_id` outside the connection's write
-grant is refused `scope_denied` with `write_error: permission_denied`, and the
-envelope carries `writable_source_ids`: the sources this connection's own grant
+A `remember` naming a `source_id` outside the connection's write grant is
+refused `scope_denied` with `write_error: permission_denied` (a page write:
+`permission_denied`), and the envelope carries `writable_source_ids`: the sources this connection's own grant
lets it write (one id, or `[]` when the grant holds no single writable source).
It never names a source outside the grant, a federated read source included,
and the refusal is identical whether the named source exists or not. On
diff --git a/llms-full.txt b/llms-full.txt
index cfc714a884..1ebcb7e6fd 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -8797,9 +8797,9 @@ suggestion are unchanged.
#### write-grant refusal detail (additive)
-A `remember` (or page write) naming a `source_id` outside the connection's write
-grant is refused `scope_denied` with `write_error: permission_denied`, and the
-envelope carries `writable_source_ids`: the sources this connection's own grant
+A `remember` naming a `source_id` outside the connection's write grant is
+refused `scope_denied` with `write_error: permission_denied` (a page write:
+`permission_denied`), and the envelope carries `writable_source_ids`: the sources this connection's own grant
lets it write (one id, or `[]` when the grant holds no single writable source).
It never names a source outside the grant, a federated read source included,
and the refusal is identical whether the named source exists or not. On
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 9c6efa04bb..df4a39ff0d 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1417,7 +1417,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.560.0', id: 'segmented_freeze_hold_gbra287', text: 'A managed sync whose freeze compares a Git-tracked page stored in segments with working-tree bytes that differ from the pinned commit now reads a page up to 24 MiB back whole, as its publication does, instead of refusing with `page_body_segmented` and stopping the source (`sync_blocked`) on every later sync. A page whose stored body cannot be read while it is frozen (`page_body_segmented` or `page_body_rows_unreadable`) is held `page_write_failed` with that code named, and the rest of the source syncs; `gbrain sync status` classifies such a hold by that code (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, no person needed) instead of as an unplaced `page_write_failed`. A sync that stops before admitting any write request shows `last_error.request_id: null` in `gbrain sync status --json` instead of omitting it.' },
{ since: '0.60.560.0', id: 'segmented_reexport_gbra287', text: 'A full sync re-exports a DB-only page (#2426) stored in segments, streaming its file with the bytes `gbrain export` writes, instead of listing it as a `page_body_segmented` failure; a page whose re-export fails is returned in the result\'s `reexport_failures` and the run completes. Write-through of a page stored in segments keeps the existing file\'s mode, skips a file over the pre-push scan cap before binding `source_path`, and with frontmatter overrides returns an error result instead of a `page_body_segmented` one; the derived (generated-page) writer skips such a page (`segmented_page`). A segmented read whose page published a new body between its reads reads one generation (or the new live one) instead of refusing `page_body_rows_unreadable`.' },
// GBRA-200 (harness ask 6: stamp degraded replies). `since` is stamped at the merge slot.
- { since: '0.60.562.0', id: 'write_grant_refusal_gbra200', text: 'A `remember` or page write naming a `source_id` outside the connection\'s write grant is still refused `scope_denied`, and the refusal now carries `writable_source_ids`: the sources the connection\'s own grant lets it write, never another source, identical whether the named source exists or not. On `remember` the `fix` repeats the call against that source once the user agrees (`next: ask_user`, naming both sources), so a harness can retry instead of giving up; `forget`, `forget_fact` and page writes carry no fix.' },
+ { since: '0.60.562.0', id: 'write_grant_refusal_gbra200', text: 'A `remember` naming a `source_id` outside the connection\'s write grant is still refused `scope_denied` (a page write: `permission_denied`), and the refusal now carries `writable_source_ids`: the sources the connection\'s own grant lets it write, never another source, identical whether the named source exists or not. On `remember` the `fix` repeats the call against that source once the user agrees (`next: ask_user`, naming both sources), so a harness can retry instead of giving up; `forget`, `forget_fact` and page writes carry no fix.' },
{ since: '0.60.562.0', id: 'degraded_stamp_gbra200', text: 'Every degraded or partial read result now carries one stamp naming why with stable codes: an MCP result gets `_meta.degraded: { reasons: [...] }` and one extra text block, `[gbrain degraded: <reasons>] ...`, after the others; a CLI `--json` object gets a `degraded` key, and other CLI output (human text, a bare `--json` array such as search results) gets that line on stderr. It covers search, query, recall, find_experts, context_pack, delta, entity, get_page (`file_held`), think and synthesize, search_exact, open_loops and rank_entities. recall and think no longer drop their page search\'s degraded stages (an embed timeout, a failed arm, the keyword rank bound): recall reports them in `_meta.retrieval.degraded` and its `degraded_recall` notice, think and synthesize as `GATHER_DEGRADED:<stage>` warnings, and a keyword-only search or recall on Postgres reports `keyword_candidates_incomplete` when the rank bound applies. A clean result carries no stamp, and no existing field changed.' },
];