Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Merge commit '39cf0ba4915a0cd4b3f7bf5c87bb7a39b58ae5c0' into capy/an-upgrade-refuses-another

garrytan3bd14e728312
diff --cc CHANGELOG.md
index a9deab77ae,082f09405b..fecbd177e5
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -10,18 -10,66 +10,78 @@@ credits are retained; no result has bee
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**An upgrade no longer adopts another application's OAuth table and then stops halfway, and rerunning `gbrain apply-migrations --force-schema` now recovers a brain that stopped.** gbrain creates `oauth_tokens`, `oauth_clients` and `oauth_codes` with `CREATE TABLE IF NOT EXISTS`, so when another application sharing the Postgres database already had a table with one of those names, gbrain took it over, added its own columns to it, and a later upgrade stopped at v210 with `operator does not exist: timestamp with time zone > bigint`. That error named neither the table nor the column, and it came after earlier migrations in the same run had already applied. The documented recovery, rerunning the same command, then could not create gbrain's own table.
+
+### Itemized changes
+
+- **Schema setup refuses a table gbrain did not create, before changing anything.** Before the schema replay (`gbrain init`, every engine start that applies migrations) and before any migration in a run, gbrain checks that each OAuth table that already exists has every column gbrain has always given it, with the same type. When one does not, it stops with the new `foreign_table` error, which names the table, the column, the type it found, the type gbrain needs and the fix: give gbrain its own database, or move the other table with `ALTER TABLE <table> SET SCHEMA <other_schema>`, then run `gbrain apply-migrations --force-schema --yes`. A correctly shaped brain runs exactly as before, and v210 is unchanged. Guide: [foreign table](docs/guides/troubleshooting.md#foreign-table).
+- **`gbrain apply-migrations` replays the schema before the pending migrations on every path.** With the migration lease held (every PGLite brain, and every Postgres brain whose schema has the lease table) it ran the pending migrations without the schema replay, so a table the replay creates that was missing stayed missing and the next migration failed with `relation "<table>" does not exist`. It now goes through the same schema setup as `gbrain init --migrate-only` on every path. A brain an older release stopped at v210 recovers with `gbrain upgrade` and the steps the guide lists.
+- Tests: `test/upgrade-foreign-oauth-table.test.ts` runs on PGLite and Postgres: the refusal on an upgrade (a foreign `oauth_tokens`) and on a fresh install (a foreign `oauth_codes` or `oauth_clients`), the rerun that recreates a missing table, and the full recovery of a brain stopped at v210.
+
+Reported by @jonahberg (#9190, #9191); first fixed by @Masashi-Ono0611 in #9195 and #9193.
+
+ ## [0.60.694.0] - 2026-11-12
+
+ **Labels you set on an agent's page now hold, and an agent can no longer take you out of a page's readers.** When you made an agent-written page private with `gbrain repair visibility` (or set its readers with `--readers`), the page kept its agent tier, so a later agent write at that tier could drop the label again with nothing held. Your label repairs now raise the page's label guard to your tier, so that write is held the same way as one over a page you wrote: it publishes with your labels kept and waits for you in `gbrain trust review`. Separately, a local write below your tier whose `readable_by` would leave you, the brain owner, out of a page you read now keeps you in the list (the rest of the narrowing still applies), and its `lower_page` item records the readers it asked for, which `gbrain trust confirm tp<id>` applies. Confirming such an item on a page whose own tier is an agent's changes only its labels and leaves the page at the agent's tier, so saying yes to a label change never vouches for the body; on a page of yours, confirm still endorses the edit at your tier. Your own readers changes, synced edits, agent narrowing that keeps you, and brains with the owner opt-in to read restricted pages are unaffected. The guard lives in a new database table and is set only by label repairs run after the upgrade, so labels you set earlier, and a managed Git brain rebuilt from a clone, start unguarded: running `gbrain repair visibility --slug <page>` or `--readers <list>` again on a page that already has those labels raises the guard without changing the labels or writing the page (GST-2521).
+
+ - A new schema migration: new `page_label_guards` table, one row per page, removed with the page. `src/core/repair/label-write.ts` and the maintenance door's `keep_trust` path (`src/core/persistence/prepared-maintenance.ts`) raise it to `operator_curated` in the label write's transaction when the page is left private or naming readers, and remove it otherwise.
+ - `src/core/trust/page-write.ts`: the label guard reads the page's guard row as a floor, and names the owner as a reader the write must keep when the owner reads the page by its readers and `access.owner_reads_restricted` is off. The held readers are the requested ones with the owner added, or the stored ones when the request is malformed. An error reading the owner fails the write instead of dropping the owner. The `lower_page` item records the page's own tier before the write (`before_state.page_tier`).
+ - `src/core/trust/page-handlers.ts`: accepting a held item whose page's own tier was below `operator_curated` writes only the requested labels, keeps the page's tier and resolves the item `labels_applied` (status `labelled`); on an owner page the confirm is unchanged. Undo of either restores the kept labels.
+ - `src/core/repair/visibility.ts`, `src/core/repair/readers.ts`: a named page that is already private, or already names the requested readers, and has no guard row is listed (`visibility private kept, label guard raised`, `readers [...] kept, label guard raised`) and applied by raising the guard under the page's row lock, with no page write or commit.
+ - Tests: `test/owner-label-guard.test.ts` covers both routes with unbound, other-member and owner-bound reads before, during and after, accept and reject, an agent's own page, a page that named no readers, accept on an agent page keeping its tier, a re-run of the label repair raising the guard on already-labelled pages (repo-less and a managed batch with no commit), the cases that must pass, and the committed file on a managed Git source, on PGLite and Postgres.
+
+ **A less trusted write that makes a private fenced fact world no longer stores a world fact before the owner decides.** An agent `put_page` that turned a more trusted private `## Facts` row world (the same claim at its row number or restated at another, or a different claim at its row number) stored its row world at once, so remote recall returned the private claim while the owner's proposal waited, and accepting that proposal then failed as stale. The writer's row is now stored private and contested, its proposal records the widening, `gbrain trust confirm tp<id>` makes the claim world and `gbrain trust drop tp<id>` keeps it private, and later writes of that fence by the same writer, and the background facts reconcile, keep it private meanwhile. A claim the page already holds world is not treated as a widening, and an accept applies the widening only while the page's fence row still asks for world. A `remember` that restates a private claim world is not covered by this change. The page text still holds the visibility the writer wrote, so a remote page read shows that row until the owner decides (GST-2511).
+
+ - `src/core/trust/fence-guard.ts`, `src/core/trust/supersede-handlers.ts`: a contested replacement that would make a guarded private row world, or a new world row restating a more trusted private claim of the page, is inserted private, its `supersede_fact` proposal carries `visibility: {from, to}`, the owner's accept sets it (undo restores it), and a lower-tier write keeps that contested row private while its widening is pending, rejected or undone (GST-2511).
+ - `src/core/cycle/extract-facts.ts`: the fence reconcile keeps the visibility of a contested row whose widening proposal is pending, rejected or undone, instead of widening it to the page's cell (GST-2511).
+
+ **An agent edit can no longer make a private page readable before you decide.** A local `put_page` (or `capture`, `edit_page`, `append_page`, `revert_version`, `restore_page`) from a writer less trusted than the page used to publish at once even when it dropped or widened the page's `visibility`, `access`, `confidentiality` or `readable_by`. The only safeguard was a `lower_page` item in `gbrain trust review`, and until you dealt with it, remote callers and other members could read the page. The usual cause was an agent that rewrote a page and forgot its frontmatter. Now that write publishes with the page's earlier labels kept, in the database and in the file it commits, and its receipt names the kept keys (`privacy_labels_kept`). The `lower_page` item shows the labels the edit asked for. `gbrain trust confirm tp<id>` applies exactly those labels if the page hasn't changed since, `gbrain trust drop tp<id>` keeps the earlier ones, and undoing a confirm puts them back while the page is still as the confirm left it. The same hold covers a derived page publication by a maintenance job (for example a dream patterns run that rewrites one of your pages), a page with no trust tier recorded yet (`unknown`), which counts as yours, and an agent that deletes a page and writes it again: a delete no longer lowers the page's tier. A credential bound to you reads the page throughout. Unaffected: writes that only narrow a label, writes that leave the labels alone, writers at or above the page's tier, your own synced edits, and `gbrain repair visibility` (GST-2518).
+
+ ### Itemized changes
+
+ - `src/core/trust/page-write.ts`, `src/core/persistence/page-prepare.ts`: a local content write below `operator_curated`, and below the page's label guard tier, keeps the stored labels it would widen, and so does a derived page publication. The guard tier is the page's tier (`operator_curated` lowered by its frontmatter caps when the tier is `unknown`), raised to the earlier tier recorded on every `lower_page` item of the page since the last one you confirmed. The `lower_page` item records the kept and requested labels, and a later write by the same tier replaces them with what it asked for, so a write that puts the label back withdraws the request. A write that changes only labels publishes nothing and still files its item.
+ - `src/core/trust/page-handlers.ts`: confirming a held item writes the requested labels in the same owner page write that confirms the page. New undo for a confirmed held item restores the kept labels and the edit's tier, and only while the page is at the revision the confirm wrote.
+ - `src/core/persistence/page-prepare.ts`: a soft delete keeps the page's tier (it writes no content). `src/core/persistence/prepared-maintenance.ts`: a derived publication whose labels were kept files one item, with the labels.
+ - `src/core/trust/owner-actions.ts`, `src/core/trust/review.ts`: the confirm and drop previews and the review item name the held labels.
+ - Tests: `test/lower-tier-label-hold.test.ts` covers each label dropped and widened, remote reads (unbound, another member, the owner), accept, reject, undo, a stale undo, a withdrawn request, the two-step and reject-then-lower bypasses, a delete then a write, an `unknown` page, a derived maintenance publication, the cases that must pass unheld, and the committed file on a managed Git source, on PGLite and Postgres.
+
+ ## [0.60.693.0] - 2026-11-12
+
+ **The brain owner's own agents can now withdraw a private fact the brain host saved.** A credential bound to the brain owner (`gbrain access owner set`) reads private facts, but its `forget` refused one the host had saved with `visibility: "private"` and said only the brain host could withdraw it. Now, speaking for itself, the owner's credential (or a stdio server started with `--stdio-member <owner>`) withdraws a private fact it reads when the page that holds it is one the credential can already write. The fact is struck in the page's file on a brain with a Git repository, and on a strict source a fact held for an entity with no page is struck in `memory/unattributed`, so a rebuild from Git keeps it withdrawn. Three things stay as they were. A fact on a `visibility: private` page, on a page whose readers leave the owner out or on another member's page is still withdrawn on the brain host (`gbrain forget <id>`). A fact the owner confirmed or curated still asks the owner first (`forget_requires_owner`). Member credentials, attested calls (`x-qm-actor`), audiences, subagent jobs, slug-fenced clients and unbound connections get exactly the answers they got before.
+
+ **The owner's agents can also withdraw a fact on a page that lists the owner as a reader.** Since 0.60.682.0 the owner's `recall` shows facts on a page whose `readable_by` names the owner, but its `forget` and `forget_fact` answered `not_found` for them. Now they withdraw such a fact, private or shared, when the owner's credential may also write that page and the page of the entity the fact is about, if it has one, is one the owner reads the same way. The owner opt-in that lets the owner read pages kept to other members (`gbrain access owner reads-restricted on`) does not extend to `forget`: those facts are still withdrawn on the brain host. Every caller that is not the owner speaking for itself gets the answer it got before.
+
+ **A member's save no longer reveals that a claim it never read was withdrawn.** When the brain host or the owner withdrew a claim, a member that later saved the same claim on its own member page was refused with `fact_withdrawn`, which told it that a claim it could never read had existed and been forgotten. Now that save succeeds and gets the same reply it would get if the other claim had never existed. The fact is the member's own, it stays active, and the member's `recall` returns it. A save is still refused when the member could read what was withdrawn, which means a fact it forgot itself, its own copy that the brain host's `forget` withdrew, or for the owner, a fact it reads anywhere. A schema migration changes the two database guards that mark a newly saved row as withdrawn so a row on a member page is marked only by that page's own withdrawals; it rewrites no rows. Brains with and without a Git repository behave the same way.
+
+ ### Itemized changes
+
+ - `src/core/persistence/memory-mutations.ts`, `forget-prepare.ts`: the owner's `forget` reaches a fact on a page that names it as a reader (`ownerReachesFact`): that page, and the fact's entity page where one exists, must pass GST-2490's owner read rule (`ownerReadPolicyFragment` in `search/private-visibility.ts`, the opt-in off) and the read rule a member write is held to, for the owner's identity. Preparation re-resolves that identity from the stored principal and checks the fact again under the publication's locks, so a page that drops the owner from its readers after submission refuses `not_found`.
+ - `src/core/facts/single-prepare.ts`: a remote save onto a member page meets the page's own withdrawals and a withdrawal of another subject only when a withdrawn row is one the page's member reads (`memberPageWithdrawal`). Callers in `memory-prepare.ts` and `ops/qm-memory.ts` pass `remote`.
+ - `src/core/facts/withdrawal-schema.ts`, `insert-guard-schema.ts` and a new schema migration make the insert guards mark a row on a member page only by that page's own withdrawals; `access/member-facts.ts` (`withdrawalCoversFactSql`) and `facts/embedding-identity.ts` treat such a row as covered by its own page's withdrawals only. A withdrawal still expires every matching row, member pages included, when it is made.
+ - Tests: `test/owner-facts-d1-gst2346.test.ts` (the owner's forget on a page that names it, the nine non-owner caller shapes and a member reader unchanged, the opt-in, preparation from the stored principal and under locks, the managed-brain file; the member's save compared byte for byte after a host and an owner withdrawal, and the refusals that stay); PGLite and Postgres.
+
+ - `src/core/persistence/memory-mutations.ts`: `forget` and `forget_fact` let the owner speaking for itself through for a private fact off every member and scope page, on a page no remote writer is kept from, and mark the stored request. The refusal that names the brain host now tells the owner what its credential does withdraw.
+ - `src/core/persistence/forget-prepare.ts`, `src/core/persistence/page-visibility.ts`: preparation judges the owner again from the stored principal (`storedOwnerSpeaksForItself`), and once more under the publication's locks. A writer that is no longer the enabled owner, or that named an actor, an audience, a subagent or a slug fence, reads the fact as any remote caller does and gets `not_found`.
+ - Guards kept: the same claim active on a page kept from remote writers refuses `claim_linked` and withdraws nothing; a more trusted fact files the `forget_requires_owner` proposal, which stores the fact's id and tier only.
+ - Docs: access designations, `MEMORY_VERBS_v1.md`, the access key-files entry; behavior-change notice.
+ - Tests: `test/owner-facts-d1-gst2346.test.ts` (the owner's forget and forget_fact, every other caller shape unchanged, the trust proposal and its accept, preparation from the stored principal, the managed-brain file) and `test/remember-strict-held-gst2492.test.ts` (a held private fact on a strict source, with a rebuild); PGLite and Postgres.
+ ## [0.60.692.0] - 2026-11-12
+
+ **On a source whose pages are canonical in Git, every fact writer now commits a fact with no page of its own to Git, and doctor and a new repair find the ones an older gbrain left in the database only.** In the last release only `remember` did this. Google loops, fact extraction, the managed facts writer and an owner releasing a quarantined fact now also commit a fact with no entity, or for an entity with no page, as a row of `memory/unattributed`. Before, they kept it in the database only, where a rebuild from Git lost it, or were refused with `git_home_required` once that page existed. Sources that are not strict, and brains with no Git repository, behave as before.
+
+ - **A fact saved under a bare name moves when its page appears in a folder.** `remember` keys a new name such as "Kofi Example" as `kofi-example`. Once exactly one page with that name exists, such as `people/kofi-example`, the maintenance cycle moves the held fact into it in one commit and re-keys it to that page. If two pages could be meant, the fact stays held, and the doctor check and the repair preview name both pages.
+ - **New doctor check: `strict_facts_outside_git`.** For each strict source it counts facts with no Git home, facts held more than 30 days for a page that never appeared, and held facts that cannot move. Its fix is the read-only preview of the new repair.
+ - **New repair: `gbrain repair facts-home --source <id>`.** It is explicit-only and preview-bound: `--apply --expect <hash>` writes the listed facts to `memory/unattributed`, at most 500 per run, and it never runs on upgrade. It lists, without moving, the facts it cannot place. Those are facts for an entity under a folder access rule, a row the Facts table cannot show, an ontology observation, a row of a deleted page, and a fact whose entity page is deleted (that page may have been private, and purging it would not reach a row on the holding page, so the fact is listed until the page is restored or purged). The new writers skip such an entity the same way.
+ - **Known limit:** a fact for an entity under a folder access rule that has no page yet still stays in the database only, because the holding page is readable by everyone. The doctor check counts these facts and the repair lists them as `folder_restricted`.
+ - **The `entity_page_missing` notice asks before it creates a page.** While the fact is in the database only, the notice's step is now `next: ask_user`: its `user_message` says the fact is saved in the database only and asks whether to create a page for the entity, and the `put_page` call is the fix once the user agrees. When the fact is already held in Git, the notice only says where it is and that it moves once the page exists, with no step to run. This holds for single and batch `remember`, over MCP and in the CLI's `[AGENT]` block.
+ - **A sync into a strict source on a brain without managed persistence says why it imported nothing.** The failure ledger, the summary and `--json` (`failureCodes`, plus a new `failureAdvice`) now carry `strict_requires_managed` instead of `UNKNOWN`. The advice no longer sends you to fix YAML or to use `--skip-failed`. `docs/guides/git-canonical.md` now shows how to rebuild a strict source's database from a clean clone.
+ - **The same claim held for two entities stays two facts.** Fact extraction, and the repair, treated two `memory/unattributed` rows with the same text but different `entity` cells as one duplicate, so one was dropped from the index and the repair could not apply.
+ - **Purge readers now read `memory/unattributed`'s `entity` column.** The guard that drops a failed write's stored copy of purged content, and a page purge's claim inventory, used to see that page's held rows as a malformed table and miss them.
+ - Docs: `docs/guides/repair.md#facts-home`, `docs/guides/git-canonical.md`, `docs/guides/write-refusals.md`, `docs/guides/entity-scoped-facts.md`, the `remember` section of `docs/mcp/TOOL_REFERENCE.md` and `docs/protocol/MEMORY_VERBS_v1.md`. Behaviour-change rows disclose each change after an upgrade.
+ - Tests, on PGLite and Postgres: `test/strict-background-writers-gst2492.test.ts`, `test/repair-facts-home-gst2492.test.ts`, `test/held-bare-name-move-gst2492.test.ts`, `test/sync-strict-unmanaged-gst2492.test.ts`, `test/held-fence-readers-gst2492.test.ts`, `test/facts-home-review-gst2492.test.ts` and `test/doctor-strict-facts-outside-git.test.ts`. The `entity_page_missing` assertions in `test/remember-pageless-entity-gst2446.test.ts` and `test/remember-strict-held-gst2492.test.ts` now pin `ask_user` and the held form.
+
## [0.60.691.0] - 2026-11-12
**A privacy label repair on a database-only page now sticks, and a supported command stops tracking a folder's files without deleting their pages.** Pages under a folder declared `storage.db_only` in `gbrain.yml` live in the database. Some of those folders still had files Git tracked from before the declaration, and on a git-canonical source every sync put the committed file back over the database, undoing a `gbrain repair visibility` that had made the page private. Sync now keeps the database version there, a commit to such a file can no longer widen who reads the page, and `gbrain git commit-push --untrack` takes the old files out of Git safely so the problem cannot come back.