Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: CHANGELOG entry and notices for the privacy hotfix (#7805, #7841)

garrytan6de373ebb81d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b2453a1be..641198f918 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,57 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**Synthesis stops filing a session into the wrong source, and a write that asks for a private page can no longer quietly publish it.**
+
+Two privacy bugs. First, dream synthesis could write a captured conversation into whichever source the cycle happened to run for, even when the conversation belonged to another source. A session you kept in a frozen source could land, as a page, in a source others can read. Second, if you asked for `visibility: private` but spelled it a little differently (`Visibility: Private`, a value on the next line), the write reported success while the page stayed world-readable. Now synthesis writes each session only to the source it recorded, and a write that asks for private but would not get it is refused with a plain message and changes nothing.
+
+### How to use it
+
+```bash
+gbrain dream --source <id> --phase synthesize # runs the sessions that belong to that source
+gbrain sweep --assign-corpus <source> # preview: map held sessions with no recorded source
+gbrain sweep --assign-corpus <source> --apply # apply the mapping, then run synthesis again
+```
+
+To make a page private, write `visibility: private` on its own frontmatter line, lowercase key and value, then submit again with a new `request_id`.
+
+### What changed
+
+| Situation | Before | Now |
+|---|---|---|
+| A session of another source during `dream` for source A | written into source A | left for `gbrain dream --source <id> --phase synthesize` |
+| A session whose source never resolved, or an older file on a brain with several sources | written into the running source | held until `gbrain sweep --assign-corpus <source>` maps it, already-extracted ones included |
+| A write asking for `visibility: private` spelled `Private`, `PRIVATE`, `Visibility`, on the next line, as a block scalar, a list, a flow mapping, or an explicit or merged key | stored, page world-readable, reported as done | refused with `visibility_not_applied`, nothing written |
+
+### Things to watch after you upgrade
+
+- Pages an earlier release already wrote into the wrong source are not moved. Repair is a separate, preview-first step.
+- A held session counts in the phase summary and in `details.source_routing`. Nothing is dropped; it waits for `--assign-corpus`.
+- A page that already stores `Visibility: Private` is still world-readable until you rewrite the key in lowercase.
+- The refusal applies to `put_page`, `edit_page` and `capture`. A file that arrives through git sync or import is not checked yet.
+
+Contributed by @exGeni (#7805) and @TGreen87 (#7841), who reported the two bugs.
+
+## To take advantage of v0.60.481.0
+
+`gbrain upgrade` should do this automatically. If you run synthesis on a brain with more than one source:
+
+1. **Preview held sessions:** `gbrain sweep --assign-corpus <source>`
+2. **Apply the mapping you read:** `gbrain sweep --assign-corpus <source> --apply`
+3. **Verify:** `gbrain dream --source <source> --phase synthesize` and `gbrain doctor`
+4. If a step fails or the numbers look wrong, file an issue at https://github.com/garrytan/gbrain/issues with the output of `gbrain doctor`.
+
+### Itemized changes
+
+- `src/core/cycle/synthesize-source-routing.ts`: resolves each session file's source from the `.src-<id>` name or its frozen record, passes through files outside the session corpus, and holds the unresolved ones.
+- `src/core/cycle/synthesize.ts`: the synthesize phase uses that routing and reports both counts in `details.source_routing`.
+- `src/core/context/corpus-source.ts`, `src/commands/sweep.ts`: holds list already-extracted sessions, so `--assign-corpus` can release them.
+- `src/core/persistence/visibility-request.ts`, `src/core/persistence/page-prepare.ts`: a write for `put_page`, `edit_page` or `capture` whose frontmatter parses to a private request that the stored page would not keep is refused `visibility_not_applied` (`noncanonical_value` or `not_kept`). The YAML parse decides; a line scan is the fallback.
+- `src/core/error-registry.ts`, `docs/guides/error-codes.md`, `docs/guides/write-refusals.md`, `src/core/behavior-change-notice.ts`: the new code, its fix and the upgrade notices.
+- `test/fixtures/goldens/exports/types.json`: the exported error union lists `visibility_not_applied`, so typed clients see the new code.
+
## [0.60.480.0] - 2026-10-28
**Converting a source to Git-canonical now plans quickly on big brains, tells you where it is while it runs, converts sources with private pages instead of refusing, and pushes what it commits.**
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 05e410a36d..3ea348c7bf 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -132,7 +132,7 @@ a receipt can report has a row here.
| Reason | Error code | What it means | Recovery |
| --- | --- | --- | --- |
| `writer_pool_capacity` | `writer_pool_capacity` | The canonical owner has no free publication slot right now; the write stays queued. | Wait and poll the receipt (`gbrain write-request <id>`). If it persists, check `gbrain sources writer status <source>`. |
-| <a id="visibility_not_applied"></a>`noncanonical_value`, `not_kept` | `visibility_not_applied` | A page write's frontmatter asked for `visibility: private`, but the page would have stayed world-readable, so nothing was written and no no-op was reported (#7841). `noncanonical_value`: the key or value is in another case (`Visibility: private`, `visibility: Private`) or another shape (a value on the next line, a block scalar, a list), which page privacy does not read as private. `not_kept`: the request did not survive into the page that would be stored. The check only refuses; it never widens a page or changes what a remote caller may read or write. | Read the page and its revision (`gbrain get --source <id> -- <slug>`), write `visibility: private` on its own frontmatter line, lowercase, and submit `put_page` again with a new `request_id`. That is the supported way to make an existing page private, on a git-canonical source too (the page publishes database-only, see [`git_private_commit_refused`](#git_private_commit_refused)). |
+| <a id="visibility_not_applied"></a>`noncanonical_value`, `not_kept` | `visibility_not_applied` | A `put_page`, `edit_page` or `capture` write's frontmatter asked for `visibility: private`, but the page would have stayed world-readable, so nothing was written and no no-op was reported (#7841). `noncanonical_value`: the key or value is in another case (`Visibility: private`, `visibility: Private`) or another shape (a value on the next line, a block scalar, a list, a flow mapping, an explicit or merged key), which page privacy does not read as private. `not_kept`: the request did not survive into the page that would be stored. The check only refuses; it never widens a page or changes what a remote caller may read or write. | Read the page and its revision (`gbrain get --source <id> -- <slug>`), write `visibility: private` on its own frontmatter line, lowercase, and submit `put_page` again with a new `request_id`. That is the supported way to make an existing page private, on a git-canonical source too (the page publishes database-only, see [`git_private_commit_refused`](#git_private_commit_refused)). |
| `revision_required` | `revision_required` | The operation must be bound to a revision you reviewed (for example `--if-version` or `expected_revision`), and none was given: a `put_page` of a page that already exists without `expected_revision` reports this since #5385 (earlier releases said `revision_conflict`). | Preview first, then repeat with the revision the preview printed. |
| `revision_conflict` | `revision_conflict` | The page changed after the revision this write was bound to. Nothing was overwritten. | Re-read the page, merge your change, and save with the new revision. |
| `revision_changed` | `revision_changed` | An `append_page` with `expected_revision`, or a `commit_page_upload` whose session was bound to a revision, found the page at a newer revision. Nothing was appended or written, and the upload session is aborted with its staged bytes released. | Read the page again (`get_page` with `body: 'none'`), check whether the text is still missing, then append against the new revision with a new `request_id` (for an upload, begin a new session). |
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 07579576bd..62a9715af2 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1325,7 +1325,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
// #7617 / #7618 / #7644 / #7655 conversion. `since` is stamped at the merge slot.
{ since: '0.60.480.0', id: 'git_conversion_withhold_progress_push', text: '`gbrain sources canonical <source> --to git --apply` now converts a source with private pages instead of refusing: a private page whose committed file differs from it has the file\'s removal committed and stays in the database (`withhold` in the preview; before, the apply refused `git_conversion_blocked`), a private page whose file was removed by hand is withheld instead of deleted by the strict pass, and a private page whose committed file still equals it keeps that file in Git, as before. The apply prints a progress line on stderr at each phase and every 10 seconds, and prints a partial report on stdout when stopped by SIGTERM, SIGINT or SIGHUP (exit 143, 130 or 129). The source is git-canonical once `recordConversion` runs before strict_pass_2; the runtime report is authoritative: a stop before that leaves the source mixed, and a new preview lists what is left. Where the source pushes its commits, the apply pushes its own; a push that does not land is named in the receipt with the command that pushes now. One path Git cannot check no longer discards every adoption candidate, and holds clear only after the strict recheck passes.' },
{ since: 'TBD', id: 'synthesize_session_source_7805', text: 'Dream synthesis writes a captured session only into the source its session recorded (the `.src-<id>` name in the corpus `sourced/` folder, or the session\'s frozen record), never into the source the cycle runs for. A session of another source waits for `gbrain dream --source <id> --phase synthesize`; a session whose source never resolved, and a file written before sessions recorded their source on a brain with more than one source, is held, already-extracted ones included, until `gbrain sweep --assign-corpus <source>` previews and `--apply` maps it. The phase summary and `details.source_routing` count both. Pages an earlier release already wrote into the wrong source are not moved (#7805, reported by @exGeni).' },
- { since: 'TBD', id: 'put_visibility_not_applied_7841', text: '`put_page` content that asks for `visibility: private` in a form gbrain does not apply (`Private`, `PRIVATE`, or a `Visibility` key) is refused with `visibility_not_applied` instead of committing a world-readable page. Write `visibility: private` on its own frontmatter line, lowercase. Nothing ever widens a page\'s visibility (#7841).' },
+ { since: 'TBD', id: 'put_visibility_not_applied_7841', text: '`put_page`, `edit_page` and `capture` content that asks for `visibility: private` in a form gbrain does not apply (`Private`, `PRIVATE`, or a `Visibility` key, however YAML spells it) is refused with `visibility_not_applied` instead of committing a world-readable page. Write `visibility: private` on its own frontmatter line, lowercase. Nothing ever widens a page\'s visibility (#7841).' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */