Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
chore(release): unstamp onto master v0.60.708.0; versions are written at release
garrytanc26a1ed2a310
diff --git a/behavior-changes.d/writer_fence_fail_closed_7636.md b/behavior-changes.d/writer_fence_fail_closed_7636.mdnew file mode 100644index 0000000000..168f5356e8--- /dev/null+++ b/behavior-changes.d/writer_fence_fail_closed_7636.md@@ -0,0 +1 @@+Since v0.60.474.0 (#7636, migration v278), a Postgres role that row-level security hides gbrain's writer state from (the `persistence_brain` row; on a managed brain also the `git_canonical_brain` row, a source row while any source is Git-canonical, or the page behind a tag, timeline entry or take) is refused with `writer_coordinator_required` (relationship `unreadable_state`) on every guarded write, unmanaged brains included, where such writes used to pass as unmanaged. Run gbrain as the table owner, a role that bypasses RLS, or a scoped role whose policies cover those rows (docs/ENGINES.md#writer-protocol-fences).diff --git a/changelog.d/capy-train-a-access-search-privacy.md b/changelog.d/capy-train-a-access-search-privacy.mdnew file mode 100644index 0000000000..659a6c418a--- /dev/null+++ b/changelog.d/capy-train-a-access-search-privacy.md@@ -0,0 +1,70 @@+**Private pages stay private in more places, search finds the right page more often, and gbrain warns when one credential would let an agent show one person's chat to another.** This release brings together four changes to access and search privacy. Database functions can no longer be steered by a temporary table another session creates. Trust review shows exactly what you are confirming. A token with the private-pages grant stops seeing an old private marker through page history. Setup and doctor flag a single shared credential behind an agent several people talk to. Search and recall fix eight answers that were quietly wrong or quietly costly, `search.mode tokenmax` brains can see and fix pages that never reached the synopsis tier, and two opt-in switches let a long alias or a name inside a longer query find its page.++### What changed for you++**One credential behind an agent several people use is now flagged.** A credential reads the same pages whoever talks to its agent: an unbound one reads everything its grant reaches, and one bound to a member reads what that member may read. In a host-harness pilot, one bot token over a brain holding many channels' chat made agents answer people with other people's messages. The new `unscoped_multi_user_token` safety notice fires from `gbrain setup openclaw|hermes|grok-bot|muse`, from `setup claude-code` when a chat-channel plugin is enabled, from `mcp grant` and `connect` for a bot harness or a grant that reads chat from 2+ channels, from `skillpack scaffold` into an OpenClaw or Hermes workspace, and from `auth create` and `auth register-client` when the new credential reads chat from 2+ channels. It fires only on a brain that serves several people (`gbrain access serves`); on a one-person brain the routes stay silent and the doctor check is not applicable. Its fix leads with binding the credential (`gbrain auth rescope --token <name> --member <id>`, `--may-act-for <members>` for one agent several people share, or `gbrain setup <harness> --serves several` for a local agent), and names a source rescope, `sources unfederate` or `GBRAIN_SOURCE` only as narrowings that leave the credential unbound. The read-only doctor check `unscoped_multi_user_token` runs the same detection over every active token, OAuth client and wired local agent. No grant, default or exit code changes.++**Database functions keep `pg_temp` last on their search path.** Every gbrain function definition now pins `pg_catalog, public, pg_temp` itself, so a schema replay or `gbrain reindex-search-vector` no longer drops what migration v277 added, and `bun run check:search-path` refuses a definition without it. The end-of-migration hardening retries a concurrent catalog update and skips itself after a lock refusal instead of waiting a second lock timeout. Doctor `function_search_path` points at `gbrain apply-migrations --yes` below v277, and past it prints the `ALTER FUNCTION` statements to run as each function's owner.++**Trust review shows what you confirm.** Release and drop previews quote every free-text field and strip invisible characters. `gbrain trust review --accept-all` skips, and never applies, an item it cannot preview in full. A page the write gate flagged as instructions is listed by `trust review` (`flagged_page`) and is never part of accept-all; confirm it on its own with `gbrain trust confirm` after reading it.++**The private-pages grant closes a history gap.** `get_versions` hides an older version that carried the `pinned_question` marker from a token with the private-pages grant, even after the live page dropped the marker. Rotating a harness token still never carries the grant, and now prints the `gbrain auth rescope` command that grants it again. `docs/guides/multi-source-brains.md` lists which reads the grant opens and which keep hiding private pages.++**Search and recall answers that were quietly wrong now behave.**++| You ask for | Before | Now |+|---|---|---|+| `search` with `match: "keyword"` on a slow brain | "Keyword match count unavailable" | the total |+| keyword search for `acme-example`, a company with an alias | the alias matches, not the company page | both, counted |+| `get_links` to `districts/pa-<long name>` | `districts/<REDACTED:voyage>` | the slug |+| `think` over a take held Sep to Jan | a claim with no dates | `since=… until=… source=…` |+| `gbrain eval trajectory` with an annual then a monthly MRR | a 92% "regression" | nothing flagged |+| repeating a query in brain B after brain A closed mid-embed | a second paid embedding call | the cached vector |+| `gbrain import` as a non-owner role after the owner ran `ANALYZE` | "Projection planner statistics were not refreshed" every time | quiet; a large pass still warns once |+| `open_loops` when the sources table cannot be read | "no google source", coverage complete | `no_google_sources: null`, coverage partial, a notice to retry |++Recall also drops bidi and control characters from evidence titles, a saved fact a correction superseded no longer comes back through entity facts, and `sources_not_readable` counts only pages search returns.++**`search.mode tokenmax` brains can see and fix their synopsis coverage.** Import and sync embed tokenmax pages at the title tier and leave per-chunk synopses to a job that nothing ever queued, so a brain could search on title-tier vectors for weeks while reporting tokenmax. Doctor `synopsis_tier_coverage` now reports chunk and page coverage and warns below 50%. `gbrain reindex --synopsis` previews the pages, tokens and dollars and spends nothing; `--yes [--max-usd <usd>]` runs the sweep under one spend cap and resumes where it stopped. `gbrain config set search.mode tokenmax` names this command instead of `reindex --markdown`. Nothing is scheduled automatically and no default changes.++**Two opt-in switches let a long alias, or a name inside a longer query, find its page.** With `gbrain config set search.qualified_aliases true`, a 3 to 6 word phrase inside a query of up to 14 words that is the alias of exactly one page you can read brings that page to the top. With `gbrain config set search.title_qualified true`, a person or company page whose title appears inside the query gets the title boost once. Both are off by default; with them off, results and cache keys are unchanged. Neither marks a page `create_safety: exists`. A common three-word alias can lead a query about something else, so check your own queries before turning them on. Proposed and first implemented by @calebhicks.++All of this works the same on a brain with no git repository.++### Things to watch++- `takes_search` rows now carry `since_date`, `until_date` and `source`, as `takes_list` already does.+- A trajectory regression now needs two observations with the same unit and period at different dates.+- On a brain that never ran v277, or whose functions another role owns, doctor `function_search_path` warns until the printed `ALTER FUNCTION` statements run as the owner.++### Itemized changes++- `src/core/function-search-path.ts`, `src/core/migrate.ts`, `src/core/schema-migrations/v277-function-search-path-pg-temp.ts`, `scripts/check-search-path.sh`, `src/schema.sql` and every schema module that defines a plpgsql function: definitions pin `pg_catalog, public, pg_temp`; `hardenFunctionSearchPaths` runs v277 and the end-of-run step in one short transaction under the migration timeouts, retries a concurrent `pg_proc` update and turns a lock it cannot take into `schema_lock_blocked`. `src/commands/doctor/checks/function-search-path.ts` names each function still on a legacy path and the `ALTER FUNCTION` to run as its owner.+- `src/core/trust/review.ts`, `owner-actions.ts`, `release-publish.ts`, `src/commands/trust.ts`, `src/commands/doctor/checks/trust-release-unpreviewed.ts`: quoted previews with default-ignorable characters stripped, accept-all skips an item it cannot preview, `flagged_page` items, the `index-previewed` release mode, and the doctor check matching a release by request id.+- `src/core/engine-sql/pages.ts`, `src/core/token-mint.ts`, `src/core/bootstrap/harness.ts`, `src/commands/sources-add-next.ts`: the private-pages grant hides a version that carried `pinned_question`, and a harness token rotation prints the rescope that grants the private pages again.+- `src/core/ops/search.ts`, `src/core/search/evidence-date.ts`, `exact-lookup.ts`, `keyword-statement.ts`, `projection-readiness.ts`, `saved-facts-match.ts`, `src/core/sources-not-readable.ts`, `src/core/last-retrieved.ts`: evidence titles without bidi or control characters, superseded saved facts kept out of entity facts and matched on normalised figures and stemmed names, `sources_not_readable` counting only returned pages and active facts, exact lookup in keyword order, and keyword page search that limits before joining chunks.+- Tests (search path, trust and private pages): `test/function-search-path-harden.test.ts`, `test/function-search-path-pglite.test.ts`, `test/migrate-search-path-best-effort.serial.test.ts`, `test/doctor-function-search-path.test.ts`, `test/scripts/check-search-path.test.ts`, `test/e2e/function-search-path-postgres.test.ts`, `test/trust-owner-actions.test.ts`, `test/trust-release-fence.test.ts`, `test/trust-release-preview-binding.test.ts`, `test/private-pages-grant.test.ts`, `test/auth-private-pages-output.test.ts`, `test/harness-rotation-grants.test.ts`; recall: `test/search-saved-facts-match.test.ts`, `test/search-identifier-lookup.test.ts`, `test/mcp-sources-not-readable.test.ts`, `test/projection-readiness.test.ts`, `test/search/keyword-pages-limit-first.test.ts`, `test/last-retrieved-writers.test.ts` and their Postgres arms under `test/e2e/`.+- `src/core/synopsis-sweep.ts`, `src/commands/reindex-synopsis.ts`, `src/commands/reindex.ts`, `src/cli/commands/reindex.ts`: `gbrain reindex --synopsis` previews and, with `--yes`, queues one `contextual_reindex_per_chunk` job per page under one worker-enforced spend cap, runs them in-process and resumes on a rerun. `src/commands/doctor/checks/synopsis-coverage.ts` (`synopsis_tier_coverage`, also in the remote doctor, confined to the caller's sources), `src/core/search/modes-report.ts` (the coverage line in `gbrain search modes`), `src/core/search/mode-switch-ux.ts` (the tokenmax banner and the TTY prompt). Tests: `test/synopsis-sweep-8744.serial.test.ts`, `test/e2e/synopsis-sweep-8744-postgres.test.ts`, `test/mode-switch-ux.test.ts`.+- `src/core/grants/shared-exposure.ts` (new): the detection (bot harnesses, Claude Code channel plugins, the chat-channel census over a credential's or stdio server's read set), the notice and its fix.+- `src/commands/doctor/checks/unscoped-multi-user-token.ts` (new), registered in the doctor registry and categories; doctor goldens regenerated for the new check.+- The install routes: `src/commands/setup.ts`, `mcp.ts`, `harness-connect.ts`, `skillpack/scaffold.ts`, `auth.ts`. Warnings go to stderr and into `notices` or `warnings` of a `--json` result.+- `src/core/error-registry.ts`: the notice code. `docs/mcp/ADMIN.md#one-token-several-people`, `skills/mcp-access/SKILL.md`.+- Tests: `test/shared-exposure.test.ts`, `test/shared-exposure-routes.test.ts` (PGLite brains with no repository), `test/shared-exposure-serves.test.ts` (a one-person brain stays silent, a bot harness on the owner's brain included; the several-people fix binds first).+- `src/core/search/keyword-paging.ts`: `readKeywordPage` passes its row read to `countKeywordMatches`, so the count waits for the rows plus the grace, as on the hybrid path. Reported and first fixed by @akinduroifedayo in #8500.+- `src/core/search/keyword-handles.ts`: `slugHandles` judges each alternative of a bare `OR` on its own; a negation or a non-handle phrase only stops its own alternative's handles, and quote marks split words and an empty phrase is ignored, as in `websearch_to_tsquery`. Reported and first fixed by @javieraldape in #8633.+- `src/core/search/output-redaction.ts`: `from_slug`, `to_slug`, `origin_slug` and their `*_source_id` are identity fields; link context is still scanned. Reported and first fixed by @calebhicks in #8545.+- `src/core/engine-sql/takes.ts`, `src/core/engine.ts` (`TakeHit`), `src/core/utils.ts`, `src/core/think/gather.ts`, `src/core/think/sanitize.ts`: both take searches select `since_date`, `until_date` and `source`; think renders `until=`, and all three attribute values, plus any holder outside the holder grammar, are neutralized and escaped like the claim. Takes SQL-text and export-surface goldens regenerated. Reported and first fixed by @calebhicks in #8546.+- `src/core/trajectory.ts` (`comparablePairs`), `src/core/trajectory-format.ts`: regressions and the `(superseded prior)` annotation pair only same-metric, same-unit, same-period observations at a strictly later date, and a point with no finite date is left out instead of dropping the entity's whole trajectory block. Reported and first fixed by @calebhicks in #8547 and #8541.+- `src/core/ops/loops.ts`, `src/core/error-registry.ts`, `src/core/notice-ledger.ts`: a failed sources read answers `no_google_sources: null`, `completeness: "partial"` and a `loops_source_read_failed` notice with no database error text; the digest says so. `skills/google-loops/SKILL.md` names the case. Reported and first fixed by @javieraldape in #8718.+- `src/core/ai/query-embed-cache.ts`, `src/core/ai/gateway.ts`, `src/core/ai/engine-gateway.ts`: an engine's close (`dropQueryEmbeddingsTagged`) no longer bumps the process-wide generation. It marks that engine's gateway state `released`, and `embedQuery` skips the store when the state it started under was released, so only the closed engine's in-flight embeds are dropped. A `cache_namespace` engine keeps its in-flight embed for the reopened brain, and a full `clearQueryEmbedCache` still drops every one. Reported and first fixed by @javieraldape in #8639.+- `src/core/search/projection-statistics.ts`: `can_inspect` applies `pg_stats_ext_exprs`'s own rule (`pg_has_role(relowner, 'USAGE')` outside row security), so a SELECT-only role reads the projection statistic as `uninspectable` instead of `uncollected`; `missingSearchStatistics` and doctor `planner_stats_stale` stop listing it as absent (doctor says the role cannot inspect it and adds `projection_statistics: "uninspectable"` to its details, instead of calling it fresh), and `statisticsStillCurrent` lets a pass below the threshold skip the refresh when the statistic is collected or not inspectable. Reported and first fixed by @Masashi-Ono0611 in #8630.+- Tests: `test/search-keyword-paging.test.ts`, `test/search/keyword-handles.test.ts`, `test/search/keyword-handles-or-alternatives-8618.test.ts`, `test/search/output-redaction-link-slugs-8545.test.ts`, `test/takes-search-validity-8546.test.ts`, `test/trajectory.test.ts`, `test/trajectory-format.test.ts`, `test/loops-source-read-failure-8452.test.ts`.+- Tests (query embeddings and planner statistics): `test/engine-gateway-state.test.ts` (closing engine A while engine B's query embed is in flight leaves B's vector cached, so repeating the query makes no provider call; an engine's own in-flight embed is still not cached after it closes); `test/engine-cache-namespace.test.ts` (a namespaced engine's in-flight embed is still there for the reopened brain); `test/projection-statistics.test.ts` (a SELECT-only role over owner-analyzed statistics: nothing missing, `cannot be inspected`, two small passes refresh nothing and print nothing, a large pass warns once); `test/e2e/planner-stats-postgres.test.ts` (doctor run as a SELECT-only role reports the projection statistic as uninspectable).+- `src/core/search/alias-hop.ts`: `qualifiedAliasCandidates` builds the 3 to min(6, n-1) word windows (3+ content words, longest then leftmost, at most 42) and adds them to the same single alias read; the first window with a readable, non-excluded claimant decides, one claimant leads at top-of-organic + epsilon (moved or injected through the private re-check) stamped `qualified_alias_hit`, two suppress it. Order is full-query alias, then qualified, then the token hop. A query over 6 words probes only the windows, so the exact-alias hop, `search.alias_token_hop` and the rerank gate's alias grades keep their 6-word cap.+- `src/core/search/intent-weights.ts`, `src/core/search/hybrid/request.ts`: `applyQualifiedTitleBoost` runs last in `applyIdentityBoosts` on every path; it boosts a person or company title (2+ content words) mentioned in the query or a given-name variant by `title_boost`, stamps `title_mention_boost`, and skips forward title matches and rows that already carry `exact_match_boost`.+- `src/core/search/hybrid/rank.ts`, `src/core/search/remote-page-cap.ts`: autocut and the remote page cap keep a `qualified_alias_hit` row; `classifyEvidence`, CRAG and System One protection do not read it. `gbrain search --explain` prints `title-mention`.+- `src/core/search/mode.ts`, `src/core/search/modes-report.ts`, `src/core/config.ts`, `src/core/search/config-values.ts`: `qualified_aliases` and `title_qualified` mode knobs (off in every bundle), append-only `qa=1` / `tq=1` cache-key parts only when on, `gbrain search modes` rows, and `gbrain config set` refuses a value other than true/false (exit 2, `invalid_params`, nothing written).+- Docs: `docs/architecture/RETRIEVAL.md`, KEY_FILES entries for `alias-hop.ts`, `hybrid.ts`, `explain-formatter.ts`, `title-match.ts` and `remote-page-cap.ts`.+- Tests: `test/search/alias-hop.test.ts`, `test/search/qualified-alias-visibility.test.ts` (PGLite and Postgres, `readable_by` members, `visibility: private`, MCP `search` with `remote: true`; Postgres arm also through `test/e2e/qualified-alias-visibility-postgres.test.ts`), `test/search/title-boost-stage.test.ts`, `test/search/title-retrieval-arm.test.ts` (keyless keyword-only path), `test/search-mode.test.ts`, `test/config-set-unread-prefixed-key.test.ts`, `test/search-remote-page-cap.test.ts`, `test/search/explain-formatter.test.ts`.++<!-- behavior-change: writer_fence_fail_closed_7636 -->diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex e678562c65..94ec4c05a2 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1388,7 +1388,6 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.582.0', id: 'frontmatter_drift_write_8109', text: 'A write that leaves a page\'s frontmatter unchanged (`remember`, a fact or timeline write, a `put_page` of the stored frontmatter) is no longer refused `source_changed` (`file_database_drift`) when the page\'s canonical file differs from the database only in ordinary frontmatter keys (for example a contact row\'s `last_used` moved forward in the file): the write lands in the database and the file keeps its own frontmatter with the new body, so the frontmatter drift stays for `gbrain sources reconcile <source> <slug> --preview --auto-additive`. Drift in the body, timeline, title, type, tags or a policy, privacy, lineage or trust key (`access`, `visibility`, `readable_by`, `derived_from`, `trust_tier`, `aliases`, ...) refuses as before, and so does a write that changes frontmatter (#8109).' },{ since: '0.60.582.0', id: 'contacts_activity_advance_8109', text: '`gbrain sources reconcile --auto-additive` now decides a `contacts` row whose only change is an activity date (`last_used`, `last_*`, `*_last_used`, `updated`) moving forward as structurally additive (rule `contacts_activity_advance`) instead of `review` (`list_entries_changed_or_reordered`); a row that changed in any other way, moved, was removed or moved a date backward or into the future still needs review. Unquoted YAML dates compare as the instants they are instead of `date_not_text` (#8109).' },{ since: '0.60.582.0', id: 'contact_rows_dedupe_8109', text: 'New explicit repair `gbrain repair contact-rows [--source <id>] [--slug <slug>]...` collapses duplicated frontmatter `contacts` rows: one row per (type, value), in first-seen order with the newest `last_used`; a row that differs in another field and every distinct value are kept. the preview writes nothing and prints a hash, `--apply --expect <hash> --yes` rewrites exactly the previewed pages through revision-bound `put_page` (the canonical file on sources with a checkout, the database on repo-less ones), and a page whose file drifted is listed `needs_reconcile`. Nothing runs on upgrade (#8109).' },- { since: 'TBD', id: 'writer_fence_fail_closed_7636', text: 'Since v0.60.474.0 (#7636, migration v278), a Postgres role that row-level security hides gbrain\'s writer state from (the `persistence_brain` row; on a managed brain also the `git_canonical_brain` row, a source row while any source is Git-canonical, or the page behind a tag, timeline entry or take) is refused with `writer_coordinator_required` (relationship `unreadable_state`) on every guarded write, unmanaged brains included, where such writes used to pass as unmanaged. Run gbrain as the table owner, a role that bypasses RLS, or a scoped role whose policies cover those rows (docs/ENGINES.md#writer-protocol-fences).' },{ since: '0.60.525.0', id: 'refresh_sync_budget_8072', text: 'The member syncs of one `gbrain sources refresh` run stop starting work after `sources.refresh_sync_budget_ms` (default 5 minutes; `GBRAIN_REFRESH_SYNC_BUDGET_MS`). Each member gets an equal share of what is left. A run past it reports `sync_deferred` with the members it left `deferred` and still completes the refresh, so writes to the checkout are admitted again and the next `gbrain sources refresh <source>` continues them; a member that committed nothing in its share is reported `refresh_sync_timeout` in `sync_blocked`. A stalled sync no longer holds the refresh lock across scheduled runs or starves the other members.' },{ since: '0.60.543.0', id: 'member_read_access_gbra218', text: 'A page whose frontmatter names readers (`readable_by: [alice-example, group:team-a]`) is now read remotely only by a token, OAuth client or stdio server bound to a listed member (`gbrain access member add`, `gbrain auth rescope --token <name> --member <id>`, config `mcp.stdio_member`). Every other remote caller gets the same `not_found` as for a missing page, including unbound credentials, a `--private-pages granted-sources` bot and both escape hatches (`GBRAIN_REMOTE_PRIVATE_PAGES=1`, `search.remote_private_pages=visible`), which relax only `visibility: private`. A malformed `readable_by` reads as nobody, and a page derived from a restricted page reads as nobody remotely. Pages that already named `readable_by` before this upgrade read as nobody remotely until `gbrain repair access` (preview, then `--apply`). The local CLI is unchanged; `--as <member>` previews one member\'s view.' },{ since: '0.60.543.0', id: 'member_access_hatch_scope_gbra218', text: 'On a brain where any page names readers or any member exists, the escape hatches no longer turn the remote read filter off: remote reads still hide pages the caller\'s member is not listed on, and secondary surfaces that use the identity-free filter (proactive brief, retrieval reflex, entity resolution, known-as-of) hide every restricted page and keep hiding `visibility: private` pages under a hatch. A brain with no restriction keeps the old hatch behaviour exactly. A credential bound to a disabled or removed member is refused at verification (`access_member_disabled`).' },