Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: remote-added clone settings on managed reclone and install-hook; regenerate structural suites
garrytan749b45badfee
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6838f7ef6b..17e880138b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,16 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**A source that a remote caller added by URL keeps its clone settings when a managed brain reclones it, and `gbrain frontmatter install-hook` leaves that clone's hooks off.** v0.60.601.0 wrote git-lfs downloads off and hooks off into such a clone's own git config, but `gbrain sources reclone` on a managed brain cloned it again without them. `install-hook` read the clone's hooks-off setting as a hooks directory someone else chose, wrote a hook it would never run, and told the operator how to turn hooks back on.++### Itemized changes++- `src/core/persistence/topology-filesystem.ts`, `src/core/persistence/topology-clone.ts`: the managed reclone of a source recorded `added_by_remote_caller` clones with the same `git clone --config` settings as `cloneRepo`'s `skipLfs` (shared as `LFS_OFF_CLONE_CONFIG` in `src/core/git-remote.ts`).+- `src/commands/frontmatter-install-hook.ts`: a checkout whose `core.hooksPath` is `/dev/null` is skipped (`skipped_hooks_off`) with nothing written and no wiring advice, `--force` included.+- Tests: `test/persistence-source-lifecycle.test.ts` (PGLite and Postgres), `test/sources-remote-lfs.test.ts`, `test/frontmatter-install-hook.test.ts`.+## [0.60.601.0] - 2026-11-07**Security wave from a /cso audit: four remote-surface holes closed on `gbrain serve --http` and `gbrain mcp expose`.** A write-scoped token could replace, through `POST /ingest`, pages that every MCP write refuses it: another member's `readable_by` page, an owner `visibility: private` page, another member's fact page. A read-scoped caller could make `search_by_image` read a file on the brain host by passing a `file://` URI or an absolute path as `image_url`, which echoed the file's first bytes, sent server images to the embedding provider, or hung or exhausted the server. And an unsigned GitHub push webhook answered whether a repository was wired to the brain, its tracked branch and its source id before checking the signature. A remote caller adding a source by URL could also make the brain host contact an address the cloned repository names for itself, which the URL check never sees. A default keyless install (stdio MCP, no HTTP surface) was not exposed to any of them.diff --git a/docs/architecture/key-files/commands-3-continued.md b/docs/architecture/key-files/commands-3-continued.mdindex 23c3d7e1a1..fec20b46f8 100644--- a/docs/architecture/key-files/commands-3-continued.md+++ b/docs/architecture/key-files/commands-3-continued.md@@ -15,6 +15,6 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/friction.ts` + `src/core/friction.ts` — `gbrain friction {log,render,list,summary,diff}` reporter. Append-only JSONL under `$GBRAIN_HOME/.gbrain/friction/<run-id>.jsonl`. Schema is a flat extension of `StructuredAgentError`; every claw-test run opens with a `phase-marker`/`start` meta record carrying `agent` + `scenario` + `harness_schema` (agent-name resolution depends on it). Render groups by severity → phase, defaults to `--redact` for md output (strips `$HOME`/`$CWD` to placeholders so reports paste safely in PRs). `diff --base <run-or-agent> --compare <run-or-agent>` is the cross-agent instrument: exact run-id wins, else agent name resolves to that agent's latest run; identity is `(kind, phase, normalized 80-char message prefix — digit runs collapsed so durations/counts don't split identities)` over `kind ∈ {friction, delight}` as MULTISETS (per-severity counts + totals are the compared attributes: `count_changed` = volume, `severity_changed` = distribution shape via exact integer proportion test, so a delight→friction flip or a 2×error+1×nit → 1×error+2×nit redistribution always surfaces; markers/interrupted feed the compatibility banner, which warns on scenario/version mismatch); output labels sections "unique to <run>" — an instrument, never a blame-attributor. Run-id resolves from `--run-id` > `$GBRAIN_FRICTION_RUN_ID` > `standalone.jsonl`. Skills the claw-test exercises carry a `_friction-protocol.md` callout so agents know when to log friction.-- `src/commands/frontmatter-install-hook.ts` — `gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]`: writes the frontmatter pre-commit hook at `<git root>/.githooks/pre-commit` and sets `core.hooksPath` when unset. The root comes from `discoverGitRoot` (the same `git rev-parse --show-toplevel` walk `gbrain sync` uses, realpath'd on both sides), so a source registered as a SUBDIRECTORY of a host repo (bootstrap's `<workspace>/brain`) is accepted rather than skipped: the hook lands at the host root with `git diff --cached` limited to that subdirectory via shell-quoted git pathspecs, recorded as `# gbrain-scope: <dir>/` marker lines (one per guarded scope). The script carries `# gbrain-hook-version: N` (`FRONTMATTER_HOOK_VERSION`; no marker = version 1, which validated working-tree bytes), lists staged paths with `-z | tr '\0' '\n'`, collects them in a heredoc-fed `while IFS= read -r` loop (spaces and non-ASCII names survive; a newline inside a name is unsupported) and runs ONE `gbrain frontmatter validate --staged -- <paths>`, which checks the staged blobs under the strict producer rule and names failures as staged content. `inspectFrontmatterHook(localPath, sourceId?)` (read-only) returns the installed gbrain hook's version, `current`, and the `install-hook --force` refresh argv for doctor and post-upgrade. One hook per root — nested sources union their scopes on install and drop only their own on uninstall (the last one removes the file); a root-registered source renders the unscoped script and owns the whole hook. A foreign `.githooks/pre-commit` still needs `--force` (`.bak` saved, restored on uninstall). Both install and uninstall resolve the hook location through `hookPaths(root)`, which lstat-refuses a symlinked `.githooks/` or `pre-commit` (a committed link in a host repo would redirect the write/chmod/rm elsewhere); the CLI prints the refusal as a `skipped` line and continues with the other sources. Only a path outside any repo is otherwise skipped. Every branch that leaves a hook on disk — fresh write, `--force` overwrite, or a byte-identical refresh — reaches the wiring step, because the hook FILE travels with the repo while `core.hooksPath` is per-clone config: a fresh clone of a repo that committed the hook reports `installed` (and gets wired) rather than `unchanged` while inert; `unchanged` means current AND wired. Before wiring `core.hooksPath`, `hooksPathBlocker(root)` returns the operator-facing reason wiring is unsafe, or null: a `core.hooksPath` already set (any scope — a global/corporate value counts; `--type=path`-expanded and resolved against the root) to anywhere that does not realpath to `.githooks` (theirs to keep; git never reads `.githooks/` then — one resolving to `.githooks` counts as wired), a foreign executable under `.githooks/` (wiring would start running it — third-party clones commit hooks there) or an active hook in the repo's own hooks dir (`activeGitHooks` — executable non-`*.sample` entries under `<git rev-parse --git-common-dir>/hooks`, immune to a foreign `core.hooksPath`; wiring would make git ignore them). Every git spawn passes `env: process.env` (Bun's default child env is a startup snapshot), so `GIT_CONFIG_*` overrides reach the child. Any blocker returns `installed_unwired` — the hook is written, `core.hooksPath` stays untouched, and the CLI prints the reason + the manual `git config core.hooksPath .githooks` step. Pinned by `test/frontmatter-install-hook.test.ts`.+- `src/commands/frontmatter-install-hook.ts` — `gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]`: writes the frontmatter pre-commit hook at `<git root>/.githooks/pre-commit` and sets `core.hooksPath` when unset. The root comes from `discoverGitRoot` (the same `git rev-parse --show-toplevel` walk `gbrain sync` uses, realpath'd on both sides), so a source registered as a SUBDIRECTORY of a host repo (bootstrap's `<workspace>/brain`) is accepted rather than skipped: the hook lands at the host root with `git diff --cached` limited to that subdirectory via shell-quoted git pathspecs, recorded as `# gbrain-scope: <dir>/` marker lines (one per guarded scope). The script carries `# gbrain-hook-version: N` (`FRONTMATTER_HOOK_VERSION`; no marker = version 1, which validated working-tree bytes), lists staged paths with `-z | tr '\0' '\n'`, collects them in a heredoc-fed `while IFS= read -r` loop (spaces and non-ASCII names survive; a newline inside a name is unsupported) and runs ONE `gbrain frontmatter validate --staged -- <paths>`, which checks the staged blobs under the strict producer rule and names failures as staged content. `inspectFrontmatterHook(localPath, sourceId?)` (read-only) returns the installed gbrain hook's version, `current`, and the `install-hook --force` refresh argv for doctor and post-upgrade. One hook per root — nested sources union their scopes on install and drop only their own on uninstall (the last one removes the file); a root-registered source renders the unscoped script and owns the whole hook. A foreign `.githooks/pre-commit` still needs `--force` (`.bak` saved, restored on uninstall). Both install and uninstall resolve the hook location through `hookPaths(root)`, which lstat-refuses a symlinked `.githooks/` or `pre-commit` (a committed link in a host repo would redirect the write/chmod/rm elsewhere); the CLI prints the refusal as a `skipped` line and continues with the other sources. Only a path outside any repo is otherwise skipped. Every branch that leaves a hook on disk — fresh write, `--force` overwrite, or a byte-identical refresh — reaches the wiring step, because the hook FILE travels with the repo while `core.hooksPath` is per-clone config: a fresh clone of a repo that committed the hook reports `installed` (and gets wired) rather than `unchanged` while inert; `unchanged` means current AND wired. Before wiring `core.hooksPath`, `hooksPathBlocker(root)` returns the operator-facing reason wiring is unsafe, or null: a `core.hooksPath` already set (any scope — a global/corporate value counts; `--type=path`-expanded and resolved against the root) to anywhere that does not realpath to `.githooks` (theirs to keep; git never reads `.githooks/` then — one resolving to `.githooks` counts as wired), a foreign executable under `.githooks/` (wiring would start running it — third-party clones commit hooks there) or an active hook in the repo's own hooks dir (`activeGitHooks` — executable non-`*.sample` entries under `<git rev-parse --git-common-dir>/hooks`, immune to a foreign `core.hooksPath`; wiring would make git ignore them). Every git spawn passes `env: process.env` (Bun's default child env is a startup snapshot), so `GIT_CONFIG_*` overrides reach the child. A `core.hooksPath` of `/dev/null` (a URL source a remote caller added: hooks off on purpose) returns `skipped_hooks_off` before anything is written, `--force` included, and `hooksPathBlocker` names it without wiring advice. Any other blocker returns `installed_unwired` — the hook is written, `core.hooksPath` stays untouched, and the CLI prints the reason + the manual `git config core.hooksPath .githooks` step. Pinned by `test/frontmatter-install-hook.test.ts`.- `src/commands/doctor/checks/outside-content-fences.ts` — `outside_content_fences` (GBRA-221, BRAIN, registered before `fence_integrity`). Lists facts (`row_num` set, active; world-visible counted apart), active takes and `links_fence` links indexed from a fence on an imported page whose body is outside-authored text (Google `email`/`meeting` pages, every GitHub-source page, pages with `transcript_import` frontmatter). Reads the derived rows, never a page body, so segmented pages are covered. Before GBRA-221 a sender could plant such rows and a re-render carries a stored fence forward; gbrain writers also add rows on purpose, so it only lists pages (location and counts, never a cell value) with an `ask_user` review fix (`gbrain get`) and removes nothing.- `src/commands/doctor/checks/owner-host-stale.ts` + `src/commands/doctor/checks/embedding-plane.ts` — GBRA-248: doctor `owner_host_stale` (writes waiting on worktrees whose owner is stale per persistence/owner-activity.ts; fix is the read-only writer status) and `embedding_plane_disagreement` (the config file disables embeddings while the database does not and holds vectors; fix is `enableArgv` from core/readiness.ts for the stored model and width).diff --git a/docs/architecture/key-files/core-persistence.md b/docs/architecture/key-files/core-persistence.mdindex 8f90d77602..7a4a9f4c2d 100644--- a/docs/architecture/key-files/core-persistence.md+++ b/docs/architecture/key-files/core-persistence.md@@ -47,4 +47,4 @@ Managed facts extraction (withdrawn-candidate skip and recovery, conversation fa- `src/core/persistence/{semantic,semantic-pages}.ts` — revision-bound semantic tag/timeline merges through the journal. Supported merges reprepare against a newer snapshot (`mayReprepare`: `revision_conflict` or, #5385 [R13], `revision_required`, both only when the caller named no `expected_revision`); exact timeline replay leaves canonical bytes, revision, versions and structured rows unchanged. The `add_timeline_entry` receipt carries `bullet`, the rendered Markdown line (#5970): there is no update/remove verb because the page is the system of record, so the caller corrects an entry by editing that line with `edit_page` and the row follows the page (both timeline op descriptions say so; `test/timeline-correction-path-5970.test.ts`). #5251: `add_tag` / `remove_tag` prepare with `deferEmbedding: true` (a tag change leaves every chunk's text as it was, so no `embedding` effect is queued and `embedding_state` reads `deferred`; the stale sweep still covers any chunk the republication left without a vector); the full page republication they ride stays, so the issue stays open. The public timeline handler resolves durable replay before page-existence preflight, retaining original outcomes after page purge or recreation; fresh writes preserve same-source diagnostics. `page-state/projections.ts` completes sanitized text and page search vectors together, and installs delayed embeddings with UPDATE-only revision/chunk/text/index-context checks. New vectors receive the full provider:model captured before provider execution, and a runtime model switch invalidates the prepared indexing context. Metadata updates preserve the sanitized vector. Tests: `persistence-semantic-pages.test.ts`, `page-projection-concurrency.test.ts`.-- `src/core/persistence/{source-lifecycle,managed-sources,topology-schema,topology-locks,topology-receipts,topology-clone,topology-clone-model,topology-filesystem,topology-recovery}.ts` — migration 157 coordinates source add/claim/archive/restore/remove/purge/rebind/reclone. Native root locks precede topology/source/grant/counter/request guards; `withTopologyLocks(..., { relocation: true })` (rebind only, #5914 P1.3c) verifies a recorded root that now resolves through a symlink to the rebind target with `inspectRelocatedPhysicalRoot` instead of the realpath check, and the rebind transaction then calls `relocatePhysicalRoot` and moves `local_path`, the host binding and `relative_path` in place of a new worktree; a shared root advances every membership and permanently conflicts accepted old-topology requests. Withdrawal mirrors and running publication must settle first. Administrative UUIDs share the page journal's principal-scoped conflict domain and permanent capacity counters. Directory replacement reserves the configured recovery budget before provider/staging work, records a verified manifest and physical identity, and recovers only known bytes; clone failure retains the original checkout and a replayable failure receipt. Rebinding accepts a fresh candidate with exactly matching canonical content, including deletions. Stored worktree manifests and clone recovery records keep `digest`, `file_count`, `canonical_stamp` and `self_transfer` but no per-file map (#5790), so their size is independent of the worktree; `compactStoredManifest` drops a legacy map on rewrite, and transfer prepare/accept hash under the native lock before their transaction. #5200 (W14 P1.4): only a lifecycle operation that compares or records checkout bytes (`add` at an existing root, `claim`, `rebind`, `restore`; `reclone` in `topology-clone.ts`) walks and hashes the checkout; `archive`, `remove` and `purge` skip the walk when every binding of the source already carries a verified `digest` and refresh the stored manifest's `canonical_stamp` in place (`manifest = COALESCE(manifest,'{}') || {canonical_stamp}`), so a symlink that appeared after the claim no longer refuses a retire (a binding claimed before activation has no digest yet, and the retire records that first manifest because clone recovery needs it), and every dry run reports `manifest_required` so preview and real run agree (`test/source-retire-symlink-manifest.test.ts`). The `writer_manifest_unsafe` text names the manifest, not a transfer, since claim and rebind raise it too. Large-repo tests: `test/persistence-large-manifest.test.ts` (12k files, both engines via `test/e2e/persistence-large-manifest-postgres.test.ts`) and `test/e2e/persistence-large-manifest-50k.test.ts`. Old root refusal records remain. Metadata deletion retains local storage. Restart recovery rotates a bounded root scan so one conflict cannot starve other roots. Tests: `test/persistence-source-lifecycle.test.ts` on PGLite and guarded isolated Postgres. #6099: manifests are Git-scoped for Git checkouts; see `worktree-manifest.ts` in [managed sync and persistence stalls](persistence-stalls.md).+- `src/core/persistence/{source-lifecycle,managed-sources,topology-schema,topology-locks,topology-receipts,topology-clone,topology-clone-model,topology-filesystem,topology-recovery}.ts` — migration 157 coordinates source add/claim/archive/restore/remove/purge/rebind/reclone. Native root locks precede topology/source/grant/counter/request guards; `withTopologyLocks(..., { relocation: true })` (rebind only, #5914 P1.3c) verifies a recorded root that now resolves through a symlink to the rebind target with `inspectRelocatedPhysicalRoot` instead of the realpath check, and the rebind transaction then calls `relocatePhysicalRoot` and moves `local_path`, the host binding and `relative_path` in place of a new worktree; a shared root advances every membership and permanently conflicts accepted old-topology requests. Withdrawal mirrors and running publication must settle first. Administrative UUIDs share the page journal's principal-scoped conflict domain and permanent capacity counters. Directory replacement reserves the configured recovery budget before provider/staging work, records a verified manifest and physical identity, and recovers only known bytes; clone failure retains the original checkout and a replayable failure receipt. A reclone of a source recorded `added_by_remote_caller` passes `skipLfs` to `cloneTopologyCheckout`, which writes `LFS_OFF_CLONE_CONFIG` (`git-remote.ts`) into the clone as `cloneRepo` does. Rebinding accepts a fresh candidate with exactly matching canonical content, including deletions. Stored worktree manifests and clone recovery records keep `digest`, `file_count`, `canonical_stamp` and `self_transfer` but no per-file map (#5790), so their size is independent of the worktree; `compactStoredManifest` drops a legacy map on rewrite, and transfer prepare/accept hash under the native lock before their transaction. #5200 (W14 P1.4): only a lifecycle operation that compares or records checkout bytes (`add` at an existing root, `claim`, `rebind`, `restore`; `reclone` in `topology-clone.ts`) walks and hashes the checkout; `archive`, `remove` and `purge` skip the walk when every binding of the source already carries a verified `digest` and refresh the stored manifest's `canonical_stamp` in place (`manifest = COALESCE(manifest,'{}') || {canonical_stamp}`), so a symlink that appeared after the claim no longer refuses a retire (a binding claimed before activation has no digest yet, and the retire records that first manifest because clone recovery needs it), and every dry run reports `manifest_required` so preview and real run agree (`test/source-retire-symlink-manifest.test.ts`). The `writer_manifest_unsafe` text names the manifest, not a transfer, since claim and rebind raise it too. Large-repo tests: `test/persistence-large-manifest.test.ts` (12k files, both engines via `test/e2e/persistence-large-manifest-postgres.test.ts`) and `test/e2e/persistence-large-manifest-50k.test.ts`. Old root refusal records remain. Metadata deletion retains local storage. Restart recovery rotates a bounded root scan so one conflict cannot starve other roots. Tests: `test/persistence-source-lifecycle.test.ts` on PGLite and guarded isolated Postgres. #6099: manifests are Git-scoped for Git checkouts; see `worktree-manifest.ts` in [managed sync and persistence stalls](persistence-stalls.md).diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsvindex 4d3e6a72ef..3246f15aec 100644--- a/scripts/structural-suites.tsv+++ b/scripts/structural-suites.tsv@@ -201,7 +201,7 @@ test/fix-wave-structural.test.ts v0.41.8.0 #1340 — PGLite WASM init classifiertest/fix-wave-structural.test.ts v0.42.20.0 — background-work registry drains every sink before disconnect 9 readFileSync,source-surface-helpertest/fix-wave-structural.test.ts v0.42.20.0 — search-cache drained via the background-work registry 1 source-surface-helpertest/fix-wave-structural.test.ts v0.42.43.0 #2095 — volunteer-events sink + cycle purge wiring (structural pins) 2 readFileSync,source-surface-helper-test/frontmatter-install-hook.test.ts frontmatter install-hook (B13) 25 readFileSync+test/frontmatter-install-hook.test.ts frontmatter install-hook (B13) 26 readFileSynctest/fts-cjk-boundary.test.ts one copy of the DDL 2 readFileSynctest/gbrain-owned-page-types.test.ts #5881 gbrain-owned page types are declared by gbrain-base-v2 3 readFileSynctest/get-page-federated-scope.test.ts #2555 get_chunks federated scope 5 source-surface-helper