Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Merge master bf475047 into the Train A branch (CHANGELOG only)

garrytane1a93eee536b
diff --cc CHANGELOG.md
index a2e4ce5313,0d991f2561..2859e1b786
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -10,77 -10,29 +10,100 @@@ 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]
+
+**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`.
+
+ ## [0.60.701.0] - 2026-11-12
+
+ ### Flaky and slow tests fixed at their cause
+
+ **Four tests that failed at random in CI now pass reliably, one E2E file is back under its time limit, and one of the fixes is a real bug: a cycle could re-read pages it had already handled.** Each fix was proven with a forced probe that reproduces the CI failure before the fix and passes after it. No assertion, timeout or retry limit was loosened.
+
+ - `src/core/cycle/source-window.ts`: the cycle's page-listing cursor steps back to before the oldest transaction still open on another connection, so a page written by that transaction can't be missed. That count included Postgres autovacuum workers, which never write pages. An autovacuum pass open while the cycle listed pages made the next cycle read the pages written since that pass began a second time. Autovacuum workers no longer move the cursor (`test/sync-disabled-cycle-window.test.ts`).
+ - `test/facts-entity-moved-7602.test.ts`: the test created and killed the page write's facts-absorb job before the write's own background effect had queued it. When the effect ran later, it found a dead job under its key and queued a fresh one, so the preview reported a waiting job. The test now waits for the effect to finish before it touches the job.
+ - `test/persistence-index-lock-reclaim-6932.test.ts`: cleanup killed a helper shell whose `rm -rf` kept running after the shell died (dash forks a script's last command instead of replacing itself with it), and then ran `chmod -R` over the tree that `rm` was still deleting. Cleanup now waits for each helper to exit.
+ - `test/e2e/worktree-refresh-postgres.test.ts` ran six refresh suites in one file and took 139 to 156 s on CI against the 180 s per-file limit. Its crash-recovery, orphan and diverged-publish suites moved to `test/e2e/worktree-refresh-recovery-postgres.test.ts`; all 95 cases still run, and each file takes about 100 s on a 4-vCPU machine.
+ - `scripts/postgres-arm-weights.json`: the two PostgreSQL arm weights that were estimates now hold measured medians.
+ - `test/docs-repo-paths.test.ts` (the scripts/ and test/ paths named in docs must exist) runs in `bun run verify` as `check:docs-repo-paths`. Before, it ran only in the full suite and in `scripts/ci-doc-checks.sh`, so a pull request's own checks never ran it, and a doc edit could name a missing path and pass.
+
+ ## [0.60.700.0] - 2026-11-12
+
+ ### A gbrain commit no longer reverts someone else's commit of the same file
+
+ **When a script, an agent or a person commits their edit of a page file while gbrain is committing the same file, their commit now stays.** If that commit landed between gbrain reading HEAD and moving the branch, gbrain's one retry used to rebuild its commit on top of it with the bytes gbrain had staged earlier. HEAD silently went back to gbrain's version, the next sync reported success with nothing imported, the index kept the other version staged, and later edits to the page could be refused as an uncoordinated local edit. The other writer's bytes survived only in their own commit.
+
+ - A managed brain's Git effect now checks, before each commit attempt, that no commit since it staged its files changed any of them and that the index still holds what it staged. When one did, it commits nothing over it. A file whose edit the other writer committed completes `superseded` (reason `committed_by_another_writer`), the next sync imports the other version, and gbrain's write stays in the page's history. Every other file in the group is put back and retried on the new HEAD, so a file that still holds gbrain's bytes is committed on top.
+ - A strict (`canonical: git`) source's write refuses `git_target_changed` in the same case instead of rebuilding over the other commit, so recovery handles it the way it handles an edit made during the write.
+ - To find edits a brain already lost this way, [docs/guides/shared-checkout-git.md](docs/guides/shared-checkout-git.md#effect-reverted-edits) has a read-only loop over the history.
+
## [0.60.699.0] - 2026-11-12
### The Ubicloud gate VMs run a current git