Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Test the owner's held fact on a strict source, document purge of held copies, and write one CHANGELOG entry for the train
garrytan78839091ed20
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f46aa2d744..e19c719fc6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,10 +12,22 @@ identifiers and attribution are available in the pre-removal Git revision## [Unreleased]-**`remember` now says when a fact is on no page.** `remember` never creates a page. A fact saved for an entity whose page does not exist yet is stored in the database and recall returns it, but the reply read as if the fact had been written to that page, so an agent would report it as saved to a file. What is stored has not changed; the reply now tells the truth about it.+**`remember` now tells the truth about a fact saved for something that has no page yet, a source that lives in Git keeps that fact in Git, and the brain owner's own agents save facts shared by default.** Three changes to how agents save and withdraw facts land together.++A fact saved for an entity whose page does not exist yet (`remember` never creates a page) used to get a reply that named the missing page, so an agent would report the fact as saved to a file. The reply now says the fact is stored in the database only and names the `put_page` call that creates the page. On a source whose pages are canonical in Git (`canonical: git`), such a fact no longer lives in the database alone, where a rebuild from Git would lose it: it is committed to Git as a row of `memory/unattributed` that names the entity, and maintenance moves it into the entity's page once that page exists. Other sources and brains with no Git repository store it as before.++A credential bound to the brain owner (`gbrain access owner set`) reads the whole brain, but its `remember` kept every fact private on the owner's member page unless the call passed `share: true`, its `visibility: "world"` was refused, and its `forget` refused a fact it had just shared. Those private facts also stayed out of hot memory, turn context and context packs, which carry shared facts only. Now, speaking for itself, the owner's credential saves a fact with no `visibility` on its subject's page for every reader of the source, keeps it private on its member page when the call passes `visibility: "private"`, when the page or `facts.default_visibility` keeps facts private, or when it replaces a fact on that page, and withdraws a shared fact it reads. The trade-off: an owner agent that follows a planted instruction can now share a fact without passing a flag, so pass `visibility: "private"` for a fact that must stay with the owner. Member credentials, attested QM calls (`x-qm-actor`), audiences, subagent jobs and slug-fenced clients keep what they had.++The changes meet on a strict source: the owner's save for an entity with no page is held, shared, on `memory/unattributed` like any other shared save, the owner's `forget` strikes it there, and the brain host's purge removes it from the file.++Upgrade every gbrain host of a strict source together: an older gbrain holds a `memory/unattributed` file that carries the new `entity` column as a malformed fence, with no data loss.++Reported by @andreineacsu (#9101). First fixed by @Masashi-Ono0611 in #9103.### Itemized changes+#### The reply for a fact on no page (GST-2446, #9165)+- The reply names a `page` only when the fact is on one. For an entity with no page it used to carry `page: "<the entity slug>"`, a page that does not exist; now the field is absent. A pending reply's `target.slug` follows the same rule, and so does a fact with no entity on a source that cannot hold the `memory/unattributed` page.- Each `items` entry of a batch carries `persistence` and `write_through`, the same fields the single form returns. Before, a batch item gave no sign of whether it landed in a page file or in the database alone.- When the source has a checkout, the reason no file was written is `write_through.skipped: "entity_page_missing"`, in the reply and in the write receipt. It used to read `no_repo_configured`, which is false for such a source. A source with no checkout still reads `no_repo_configured`.@@ -24,26 +36,29 @@ identifiers and attribution are available in the pre-removal Git revision- Docs: `docs/guides/entity-scoped-facts.md`, the `remember` section of `docs/mcp/TOOL_REFERENCE.md` and `docs/protocol/MEMORY_VERBS_v1.md` describe the reply. One behavior-change row discloses the reply change after an upgrade.- Tests: `test/remember-pageless-entity-gst2446.test.ts` runs on PGLite and Postgres against a Git checkout, a content folder with no Git and a source with no checkout, single and batch, through the operation handler and through MCP dispatch. It also pins that the fact reaches the page's Facts table and its committed file once the page is created.-**On a source whose pages are canonical in Git, a fact saved for an entity with no page is now committed to Git.** Until now such a fact lived only in the database, so rebuilding the brain from its Git repository lost it. `remember` now writes it into `memory/unattributed` as a row whose new `entity` column names the entity, committed before the database row, and moves it into the entity's page once that page exists. Other sources and brains with no Git repository behave as before.+#### A strict source keeps a pageless fact in Git (GST-2492, #9179)- The reply, each batch item and the write receipt say where the fact is: `page: "memory/unattributed"`, `persistence: {mode: "filesystem"}`, `write_through: {written: true, held_for: "<entity>"}`, and the `entity_page_missing` notice says the fact is saved and committed and when it moves.- The `extract_facts` maintenance phase moves held facts into a new entity page in one commit: the fact keeps its id, provenance and embedding, and the held row is struck (`moved to <entity>`); when the page is restricted the held row is removed instead, so the world-readable holding page keeps nothing of it. A page kept out of Git does not take the fact; the run warns `HELD_FACT_UNMOVABLE` and the fact stays held.-- `forget` strikes a held fact's own row, and `purge_fact` removes it from `memory/unattributed` as it removes a fact with no entity, so a rebuild does not bring it back; `remember … replaces` supersedes a held fact from `memory/unattributed` or from the entity's page.+- `forget` strikes a held fact's own row, and `purge_fact` removes it from `memory/unattributed` as it removes a fact with no entity, so a rebuild does not bring it back (a purge of a held fact also drops every copy of the same claim text on `memory/unattributed`, held for another entity or with no entity); `remember … replaces` supersedes a held fact from `memory/unattributed` or from the entity's page.- A client bound to slug prefixes may save a held fact for an entity inside its prefixes; a fact with no entity is still refused for it. An entity under a folder access rule is never held on the world-readable page: its fact stays in the database, as before.- Only `memory/unattributed` reads the `entity` column, and an invalid entity cell makes its fence malformed. Every other page parses exactly as before. An older gbrain holds a `memory/unattributed` file that carries the column as a malformed fence, so upgrade every host of a strict source together.- Tests: `test/remember-strict-held-gst2492.test.ts` on PGLite and Postgres: the commit before the reply (handler, batch, MCP), rebuilds from a clone of HEAD, the move (one commit, interrupted after its commit and replayed), restricted and database-only pages, forget, purge, both supersede paths, a prefix-bound client, duplicates and the fence column.-**The brain owner's own agents now save facts shared by default, the way they already save pages.** A credential bound to the brain owner (`gbrain access owner set`) reads the whole brain, but its `remember` kept every fact private on the owner's member page unless the call passed `share: true`, its `visibility: "world"` was refused, and its `forget` refused a fact it had just shared. Those private facts also stayed out of hot memory, turn context and context packs, which carry shared facts only. Now, speaking for itself, the owner's credential saves a fact with no `visibility` on its subject's page for every reader of the source, keeps it private on its member page when the call passes `visibility: "private"`, when the page or `facts.default_visibility` keeps facts private, or when it replaces a fact on that page, and withdraws a shared fact it reads. An explicit `visibility: "world"` onto a page whose facts are kept private is refused (`share_target_restricted`), as `share: true` is. The reply still names the `page` and `visibility` the fact got. The trade-off: an owner agent that follows a planted instruction can now share a fact without passing a flag, so pass `visibility: "private"` for a fact that must stay with the owner. Member credentials, attested QM calls (`x-qm-actor`), audiences, subagent jobs and slug-fenced clients keep what they had. Works the same on a brain with no Git repository and on a managed one.--Reported by @andreineacsu (#9101). First fixed by @Masashi-Ono0611 in #9103.-### Itemized changes+#### The owner's own facts are shared by default (GST-2346 D1, #9178)+- An explicit `visibility: "world"` onto a page whose facts are kept private is refused (`share_target_restricted`), as `share: true` is, and the reply still names the `page` and `visibility` the fact got. Works the same on a brain with no Git repository and on a managed one.- `src/core/access/member-facts.ts`: `ownerSpeaksForItself` (`CallerAccess.owner`, no attested actor, no audience, not a subagent, no slug fence).- `src/core/persistence/memory-mutations.ts`: `remember` takes the ordinary route for the owner and moves a default save the page or brain default keeps private to the owner's member page; `forget` takes the ordinary remote path for the owner when that path reads the fact. `src/core/verbs.ts`: no `member_share_required` for the owner.- `src/core/facts/writeback-config.ts`, `src/core/ops/memory-settings.ts`, `src/mcp/http-transport.ts`, `src/commands/serve-http-mcp.ts`: with writeback on, the owner's credential gets the instructions of a credential bound to no member.- Docs: access designations, the company-brain tutorial, `TOOL_REFERENCE.md`, `MEMORY_VERBS_v1.md`, the access key-files entry, `skills/brain-ops/SKILL.md`; behaviour-change row `owner_facts_shared_gst2346`.- Tests: `test/owner-facts-d1-gst2346.test.ts` (every caller shape, repo-less and managed, PGLite and Postgres); `test/member-forget-refusal-9101.test.ts` now expects the owner to withdraw a fact it shared.+#### Where the changes meet++- `test/remember-strict-held-gst2492.test.ts` adds an owner-bound OAuth credential on a strict source, on PGLite and Postgres: its save for an entity with no page is held, shared, on `memory/unattributed` with #9179's reply, its `forget` strikes the held row, `purge_fact` over MCP is refused `trusted_local_only`, and the host's purge removes the claim so a rebuild from Git does not bring it back.+- `docs/guides/memory-boundaries.md`: the purge section says a purge of a held fact drops every copy of the same claim text on `memory/unattributed`.+## [0.60.684.0] - 2026-11-12**An agent that runs gbrain for one member can now be held to that member's view of the brain.** Set `GBRAIN_ENFORCED_MEMBER=<member>` in the launcher that starts the agent's gbrain calls, and every command it runs reads exactly what a remote credential bound to that member would read: pages kept to other members, private pages, folders the member is outside of and other members' personal sources leave no slug, title, body, fact or count behind. Writes still land where they land today, as trusted local writes, but the mode refuses a write to a page the member cannot read and every change to a page's readers or visibility. `remember` saves a fact only with `--entity` naming a page the member reads, and its refusal says so with the exact retry command. `gbrain write-request <id>` reads the member's own receipts, and any other id answers exactly like an unknown one. sync, `sources refresh` and `git commit-push` keep working with their output replaced by one line (sync and refresh take only `--source <id>`, `--no-pull`, `--no-embed`, `--json` and `--dry-run`, on a source the member reads), `doctor` prints only check names, statuses and counts, and `hook` succeeds silently so group turns never fail. Every other command is refused with one exact line, exit 3 and the code `enforced_member_refused`, `--help` included, and so is everything when the value is empty, names an unknown member or names the owner. Unset, nothing changes. The mode binds only a caller whose launcher pins the variable; a process that can unset it, or read the brain's files or database directly, is outside it. Guide: [docs/guides/enforced-member.md](docs/guides/enforced-member.md).diff --git a/docs/guides/memory-boundaries.md b/docs/guides/memory-boundaries.mdindex f2d8e67e9f..375b4a2769 100644--- a/docs/guides/memory-boundaries.md+++ b/docs/guides/memory-boundaries.md@@ -490,7 +490,10 @@ What one purge does, in one transaction:- drops the row (not a strike) from the page's facts or takes fence, from thestored page body and from every saved page version, then rebuilds that page'schunks; the canonical file is rewritten by the owner and committed as- `gbrain: purge fact <hash8>` (no claim text in the commit);+ `gbrain: purge fact <hash8>` (no claim text in the commit). A purge of a+ fact held on `memory/unattributed` for an entity with no page also drops+ every copy of the same claim text on that page, whether it is held for+ another entity or has no entity;- redacts stored write intents that carry the claim (a write that is runningor recovering blocks the purge with `purge_blocked_pending_recovery` until itfinishes; retry with the same request id; a write still queued, or deferreddiff --git a/test/remember-strict-held-gst2492.test.ts b/test/remember-strict-held-gst2492.test.tsindex f4ad913743..c6dd8b5f81 100644--- a/test/remember-strict-held-gst2492.test.ts+++ b/test/remember-strict-held-gst2492.test.ts@@ -6,13 +6,14 @@* batch item and receipt say where it is (`page: memory/unattributed`, `write_through.held_for`). A rebuild from a* clone of HEAD brings the fact back for its entity. Once the entity has a page, the extract_facts phase moves the* row into that page in one commit and strikes the holding row; forget and supersede strike the held row, and purge- * removes it from the file.+ * removes it from the file. The brain owner's own credential (GST-2346 D1) holds such a fact the same way, shared,+ * withdraws it, and the host's purge removes it.* 2. Fails when: a strict source keeps such a fact in the database alone (a rebuild loses it), a rebuild brings back a* forgotten, superseded or purged held fact, a move duplicates or loses the fact, or a private entity page is named* on the world-readable holding page.* 3. Existing coverage: test/remember-pageless-entity-gst2446.test.ts pins the non-strict and repo-less answers.* 4. Real seams: the coordinated write and the write door on PGLite and Postgres (DATABASE_URL), a managed Git checkout,- * the operation handler as the local CLI calls it, MCP dispatch as a remote and a prefix-bound caller, and a rebuild+ * the operation handler as the local CLI calls it, MCP dispatch as a remote, an owner-bound OAuth and a prefix-bound caller, and a rebuild* of a fresh database from a clone of HEAD through sync and the facts step.*/import { afterEach, describe, expect, test } from 'bun:test';@@ -30,6 +31,11 @@ import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';import * as fence from '../src/core/facts-fence.ts';import { scanCanonicalFences } from '../src/core/fence-repair/refusal.ts';import { installFaultHook } from '../src/core/persistence/fault-points.ts';+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';+import { sqlQueryForEngine } from '../src/core/sql-query.ts';+import { addMember, bindCredential } from '../src/core/access/members.ts';+import { setOwner } from '../src/core/access/owner.ts';+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';import { durableGitRepo, git } from './helpers/git-publication.ts';import { managedBrain, settleManagedGitEffects, type ManagedBrain } from './helpers/managed-brain.ts';import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';@@ -57,6 +63,22 @@ async function overMcp(engine: BrainEngine, params: Record<string, unknown>, autreturn { body: JSON.parse(out.content[0]!.text) as Record<string, any>, blocks: out.content.slice(1).map(block => block.text), isError: out.isError === true };}+/** A real OAuth client-credentials token bound to the brain owner, verified the way the HTTP transport verifies it. */+async function ownerAuth(engine: BrainEngine): Promise<AuthInfo> {+ const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });+ __resetPrivateVisibilityCacheForTests();+ await addMember(engine, 'carol-example');+ await setOwner(engine, 'carol-example');+ const client = await provider.registerClientManual('owner-example', ['client_credentials'], 'read write', [], 'default');+ await bindCredential(engine, { kind: 'client', id: client.clientId }, { member: 'carol-example' });+ const { access_token } = await provider.exchangeClientCredentials(client.clientId, client.clientSecret ?? '');+ return await provider.verifyAccessToken(access_token) as unknown as AuthInfo;+}+const asOwner = async (engine: BrainEngine, auth: AuthInfo, op: string, params: Record<string, unknown>) => {+ const out = await dispatchToolCall(engine, op, { request_id: randomUUID(), ...params }, { remote: true, transport: 'http', sourceId: 'default', auth });+ return { body: JSON.parse(out.content[0]!.text) as Record<string, any>, text: out.content.map(block => block.text).join('\n'), isError: out.isError === true };+};+/** A fresh database indexed from a clone of HEAD, with the facts step run, as a rebuild would: the rows of each claim. */async function rebuild(root: string, databaseUrl: string | undefined, claims: string[]) {const home = mkdtempSync(join(tmpdir(), 'gst2492-rebuild-'));@@ -312,6 +334,37 @@ for (const backend of testBackends()) describe(`[${backend}] a strict source holexpect(none.body.error).toBe('scope_denied');expect(none.body.message).toContain(`slug '${HOLD}' is not under`);}), 180_000);++ test("the owner's own credential holds a pageless fact shared in Git, its forget strikes it, and the host's purge removes it", () => strict(async ({ engine, ctx, root }) => {+ const owner = await ownerAuth(engine);+ const forgotten = 'The kitchen remodel starts in March.';+ const purged = 'The kitchen remodel needs a permit.';+ const saved = await asOwner(engine, owner, 'remember', { fact: forgotten, entity: PAGELESS, provenance: 'chat 2026-11-11' });+ expect(saved.isError ? saved.text : 'ok').toBe('ok');+ expect(saved.body).toMatchObject({ status: 'inserted', page: HOLD, visibility: 'world', persistence: { mode: 'filesystem' },+ write_through: { written: true, held_for: PAGELESS } });+ expect(lineOf(head(root, HOLD_FILE), forgotten)).toContain(PAGELESS);+ expect(await factRows(engine, forgotten)).toMatchObject([{ entity_slug: PAGELESS, source_markdown_slug: HOLD, active: true }]);+ const forgot = await asOwner(engine, owner, 'forget', { id: String(saved.body.id) });+ expect(forgot.isError ? forgot.text : 'ok').toBe('ok');+ await settleManagedGitEffects(engine);+ expect(lineOf(head(root, HOLD_FILE), forgotten)).toContain(`~~${forgotten}~~`);+ expect(await factRows(engine, forgotten)).toMatchObject([{ active: false }]);++ const second = await asOwner(engine, owner, 'remember', { fact: purged, entity: PAGELESS, provenance: 'chat 2026-11-11' });+ expect(second.body).toMatchObject({ page: HOLD, write_through: { written: true, held_for: PAGELESS } });+ const remote = await asOwner(engine, owner, 'purge_fact', { id: Number(second.body.id), dry_run: true });+ expect([remote.isError, remote.text.includes('trusted_local_only')]).toEqual([true, true]);+ await settleManagedGitEffects(engine);+ const dry = await call(ctx, 'purge_fact', { id: Number(second.body.id), dry_run: true });+ expect(await call(ctx, 'purge_fact', { id: Number(second.body.id), confirm: dry.confirm_token, expected_revision: dry.expected_revision })).toMatchObject({ state: 'committed' });+ await settleManagedGitEffects(engine);+ expect(head(root, HOLD_FILE)).not.toContain(purged);+ expect(await factRows(engine, purged)).toEqual([]);+ const rebuilt = await rebuild(root, databaseUrl, [forgotten, purged]);+ expect(rebuilt[forgotten]!.filter(row => row.active)).toEqual([]);+ expect(rebuilt[purged]!.filter(row => row.active)).toEqual([]);+ }), 300_000);});describe('the entity column of the facts fence (GST-2492)', () => {