Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Merge remote-tracking branch 'origin/master' into capy/gbra346-stable-install-default
garrytanc340fd839978
diff --cc CHANGELOG.mdindex ced7cb75fc,c4d8d4e461..dfd36ffae0--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -10,17 -10,151 +10,162 @@@ credits are retained; no result has beeidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**New installs now start on the stable channel: the soaked release, not every release.** The documented install (`bun install -g github:garrytan/gbrain#stable`) and the clone fallback (`git clone --branch stable`) follow the `stable` tag, which moves only to a published release whose exact tree passed the production soak, at least weekly. A fresh `gbrain init` (and so `gbrain setup claude-code` or `codex`) writes `self_upgrade.channel: stable`, so the update check and `gbrain upgrade` offer only stable releases. `#latest-stable` keeps working as the alpha line with every release. An existing brain is not changed: a re-init never sets or alters its channel.++### Itemized changes++- Install pins move from `#latest-stable` to `#stable` in README, AGENTS.md, INSTALL_FOR_AGENTS.md, BOOTSTRAP_FOR_AGENTS.md, docs/INSTALL.md, the MCP, headless, in-agent and tutorial guides, the setup skills, the Codex plugin manifests and launcher, doctor's npm-squat fix, the bootstrap hints and the agent-workspace template. The bootstrap runbook fetch and the in-agent setup helper read the `stable` ref, and the in-agent helper pins the commit `refs/tags/stable` peels to.+- `scripts/check-bootstrap-tag.sh` sanctions `stable` as the one distribution ref and now refuses `#latest-stable` in the entry docs.+- `src/commands/init.ts`: a fresh install (new content database, no prior config file) persists `self_upgrade.channel: stable` on PGLite and Postgres. A re-init keeps whatever the config says, including no channel. `test/init-stable-channel.test.ts` covers the fresh, re-init and explicit-channel cases.+- `docs/guides/upgrades-auto-update.md#stable-channel` describes stable as the default for new installs and `latest` as the alpha line.++ ## [0.60.602.0] - 2026-11-07++ **A TLA+ model of the refresh write barrier and its deferred-write queue now runs in CI. It checks that a refresh killed at any phase recovers without stranding the writes deferred behind it, that held writes commit in admission order, and that no lock order deadlocks.** Nothing changes at run time: this release adds a model, its CI job and tests.++ ### Itemized changes++ - `spec/tla/refresh-barrier/`: `RefreshBarrier.tla` models write admission and deferral, the drain, the fence and the merge, a crash at each phase followed by recovery, ledger commits that move HEAD during the drain, writes held for an import, deferral behind `recovery_required`, and local-edit adoption. Four configs check every safety property and one checks liveness; two larger configs run nightly. The model reproduces the fenced-orphan recovery bug fixed in 0.60.596.0 and passes on the fix.+ - `spec/tla/refresh-barrier/mutants.json`: 19 mutants. Each removes one guard from the model, and TLC must report the named property. 15 make the same edit to the code, and a named PGLite or Postgres test must then fail on an assertion. Run them with `bun scripts/spec/mutants.ts refresh-barrier`.+ - `.github/workflows/tla-spec.yml`: TLC and the mutants run for both TLA+ specs, nightly and on pull requests and pushes that touch a spec, its runner, the code it models or a test a mutant names. Each spec uploads its own log artifact, `tla-spec-logs-<spec>`.+ - Tests: `test/spec-refresh-barrier.test.ts` keeps the configs, the workflow's path filter and the README's mutant table in step with the catalogue. New tests cover an import expiry overlapping a fence (Postgres), a claimed write that holds the drain, a token revoked after its write was claimed, and the owner scan aborting a refresh killed at the fence after an outside commit. The two Postgres race tests now fail if the operation they start never waits on the lock.++ ## [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.++ ### Itemized changes++ - `src/commands/serve-http-webhooks.ts`, `src/core/minions/handlers/ingest-capture.ts`: `POST /ingest` stores the caller's token or OAuth client on the job. The route answers `404 page_not_found` for an `X-Gbrain-Slug` the caller cannot read and `403 permission_denied` for a member fact page or the scope page, and queues nothing. An `X-Gbrain-Slug` that is not a valid slug gets `400 invalid_slug` instead of a queued job that fails later (#8763). The job checks the same writer again right before it writes, so a page restricted after the 202 is still refused, and a queued webhook job with no stored writer is checked as a guest. Fresh slugs and pages the caller can read import as before.+ - `src/core/ops/image.ts`, `src/core/search/image-loader.ts`: `search_by_image` accepts only an http(s) `image_url` from any caller that is not the trusted local CLI, and refuses `image_path` unless the context says the caller is local. The loader reads local paths only when its caller opts in, and checks for a regular file and the size cap before it reads.+ - `src/commands/serve-http-webhooks.ts`: a push event is verified against the source's secret before anything about the repository is answered. An unknown repository, a source with no secret and a bad signature all get the same `401 signature_mismatch`; the missing-secret case is logged on the server with the command that sets it.+ - `src/core/git-remote.ts`, `src/core/sources-ops.ts`, `src/core/ops/sources.ts`: a URL source a remote caller adds is cloned with git-lfs downloads off, written into the clone's own git config (`lfs.fetchexclude=*`, which outranks the repository's `.lfsconfig`, with hooks off so git-lfs's pre-push hook never runs), so every later pull, managed refresh and commit-push in that checkout keeps large files as pointer files and contacts no LFS endpoint. The source records `added_by_remote_caller: true` so a re-clone keeps it off. A URL source a remote caller added before this release carries no such record, so remove it and add it again (from the remote caller or with `gbrain sources add --url`, which keeps git-lfs) to choose its setting. A remote caller whose clone fails gets a fixed message; git's own error goes to the brain host's log. Sources added from the local CLI keep git-lfs.+ - Tests: `test/serve-http-ingest-member-access.test.ts` (real token verifier and Express route, two members), `test/search-by-image-op.test.ts`, `test/cross-modal-phase2.test.ts`, `test/serve-http-github-push-webhook.test.ts` and `test/sources-remote-lfs.test.ts` (real git-lfs against a local LFS endpoint).++ ## [0.60.600.0] - 2026-11-07++ **With the refresh write barrier on, writes waiting behind an import no longer use up the capacity the import itself needs, so a full cap no longer stalls managed sync until the waits expire.** The barrier is still off by default (`persistence.refresh_barrier`), and with it off nothing changes. Before, every held write kept its outstanding-request slot and intent bytes, so enough of them could leave a managed sync job, or a bulk import group, refused `queue_capacity`, and the writes it would have released waited out the limit and expired. A held `capture` that replaces an imported page now names what it replaced, as a blind `put_page` does, and the expiry pass no longer expires a hold that an import and a new deferral replaced while it ran.++ ### Itemized changes++ - `src/core/persistence/journal.ts`: a managed sync job, and a bulk sync group in `admitWriteGroupInTransaction` whose writes are all managed sync jobs, is admitted as if the writes held for an import or a refresh took no outstanding-request slot and no intent bytes. The held writes are counted only when the plain check would refuse, so an admission that fits reads nothing more. The importer can pass a cap by at most what the held writes hold. Other writes still count them.+ - `src/core/persistence/import-deferral.ts`: a held `capture` that lands over imported content records `supersedes` on its receipt, the `gbrain-supersedes:` commit trailer and the commit-ledger line, as a blind `put_page` does.+ - `src/core/persistence/refresh-barrier.ts`: `expireDeferredWrites` rechecks, under the lock, that the hold it scanned is still waiting on the same import and is still older than the wait limit, so a hold that an import and a new deferral replaced between the scan and the lock is left alone.+ - Tests on PGLite and Postgres: `test/import-write-barrier.test.ts` (a held capture's `supersedes`, the capacity a single import and a bulk import group need, the expiry racing a new hold) and `test/refresh-write-barrier.test.ts` (the capacity a refresh's own sync needs). Follow-ups are in #8759.++ ## [0.60.599.0] - 2026-11-07++ **A page write refused `source_changed` now says why in its receipt, and a source can opt in to having a `remember`, `capture` or `add_timeline_entry` adopt an uncommitted local edit instead of being refused.** Before, only `pending_import`, `sync_held` and `canonical_file_missing` refusals carried a cause, so a write lost to a hand edit, an occupied path or a file that moved mid-write looked the same in `gbrain write-request` and doctor. Every `source_changed` refusal now records `error_detail.origin`. With `persistence.adopt_local_edits.source.<id>` on (off by default), a one-sided local edit (Git `HEAD` still holds the database's copy, or any edit on a repo-less brain) is committed as its own write first, then the caller's write lands on top. Keep the flag off until the follow-ups in #8755 are done.++ ### Itemized changes++ - `src/core/persistence/publication-failure.ts`, `coordinator.ts`, `page-prepare.ts`, `git-door.ts`: a `source_changed` refusal's `error_detail` is `{ origin }`, one of `file_database_drift`, `canonical_path_occupied`, `raw_file_changed`, `pinned_git_worktree_conflict`, `unsafe_file_target`, `source_binding_changed` or `unbound_source`. Classification, retries and replay are unchanged. `gbrain sources writer status` leaves these routine refusals out of its recent database refusals.+ - `src/core/persistence/local-edit-adoption.ts` (new), `file-repair.ts`, `effect-git.ts`, `commit-ledger.ts`: the adoption is a `managed_file_repair` admitted under the installation's CLI writer with a request id derived from the caller's, so a write adopts at most once. It waits until the file has been unchanged for `persistence.adopt_quiet_ms` (default 5000, at most three windows), imports the exact bytes, keeps the replaced revision with change reason `adopted_local_edit` and, on a Git-durable checkout, commits only that file (`gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`, a commit-ledger `adopted` line). The caller's receipt names `adopted: { path, blob, replaced_revision }`.+ - The adoption keeps the refusal for an edit to the title, type or a protected frontmatter key, a file that does not import, an edit on both sides, bytes that are not valid UTF-8, a `HEAD` that moved before publication or that Git cannot read, a cancelled caller, `put_page`, batches and every other verb. A file changed again during the adoption ends `raw_file_changed` with nothing written. An adoption still waiting on the worktree lock when the caller gives up is cancelled.+ - `src/commands/doctor/checks/local-edit-adoptions.ts` (new): doctor `local_edit_adoptions` lists the last 24 hours of adoptions per source.+ - Tests on PGLite and Postgres: `test/adopt-local-edit.test.ts` (each verb, every kept refusal, the quiet window, the lock and cancel races, a moved or unreadable `HEAD`, the doctor check, a repo-less brain) and `test/remember-pending-import.test.ts`.++ ## [0.60.598.0] - 2026-11-07++ **A segmented page that sync replaces on Postgres now publishes on the first try instead of being refused `body_staging_expired` ("does not cover its N-byte body") and blocking its source until the next sync.** The import ran its version write, which for a segmented page prunes old versions and sweeps their segment rows, at the same time as the flip that publishes the new body. On Postgres the two overlap on one connection, so the sweep could delete the freshly published tail row between the flip clearing its staging and bumping the page's generation. PGLite runs them in order, so only Postgres was affected. The refusal now records which staging was short, a retry inside the run really prepares the page again, and `gbrain sources writer failures` answers within its bound on a source full of large sync writes.++ ### Itemized changes++ - `src/core/import-file.ts` (#8729): a segmented import writes its version before the page write, as unpinned and demoting imports already did, so the version prune and segment sweep never run beside the flip.+ - `src/core/persistence/sync-prepare.ts`: a waiver screen aborts the segmented staging its import opened as soon as the import hands it over, on the unbounded engine so a screen past its deadline still aborts it. Before, every screened replace left a second staging live until the idle sweep.+ - `src/core/persistence/sync-pass-batch.ts`, `sync-run.ts`: an in-place re-freeze in a pass takes `passRequestId(…, failedRequestId)` instead of the failed request's own id, so the retry prepares the entry again instead of reading the failed receipt back. The first freeze keeps the v1 id; `STOPS_PER_ENTRY` still bounds retries. A chain restarted in the same pass can still re-derive an earlier chain's ids (#8750).+ - `src/core/persistence/publication-failure.ts`, `coordinator.ts`: a `body_staging_expired` refusal's `error_detail` is `{ origin: 'body_staging', staging: { staging_id, state, reason, rows, segment_count, covered_bytes, body_bytes } }`, read field by field from the engine's detail. Remote callers still see only `origin`.+ - `src/core/persistence/terminal-classify.ts`, `terminal-failures.ts`: the supersession probe tests the failed row's intent kind before it reads any later request's intent, and `readTerminalFailures` selects its page of rows before the lateral join, so the drill-down and the summary no longer detoast every later sync write's frozen file per failed row. On 200 failed and 2,000 committed large-intent writes the drill-down went from `unknown` at the 5 s bound to about 2 s.+ - Tests on PGLite and Postgres: `test/large-pages/segmented-sync-replace-8729.test.ts` and `test/e2e/segmented-sync-replace-8729-postgres.test.ts` (tail-only replaces while every version prunes, no staging left live, a forced refusal recorded and prepared again), `test/e2e/terminal-failures-large-intents-8729-postgres.test.ts`, `test/publication-failure-staging-8729.test.ts`, `test/terminal-supersession-kind-8729.test.ts`, `test/sync-pass-retry-id-8729.test.ts`.++ ## [0.60.597.0] - 2026-11-06++ **`gbrain upgrade` now restarts a jobs supervisor started from a source checkout as `bun run src/cli.ts jobs supervisor` instead of refusing the upgrade with `restart_refused`.** The restart planner recognised a gbrain process only when its command line held a path containing "gbrain", so a supervisor launched with a relative `src/cli.ts` was invisible, its worker looked unsupervised, and the upgrade stopped. Four smaller fixes ride along with it, covering a flaky spend-guard SIGTERM test, the PGLite snapshot cache keys, the stress gate's pooled-owner match, and the ownership stamp on a checkout that became a Git repository after it was stamped.++ ### Itemized changes++ - `src/core/upgrade-restart.ts`: `gbrainEntry` resolves a relative entry point against the process's working directory (`/proc/<pid>/cwd` on Linux), skips interpreter flags that take a value (`--preload x`, `--cwd x`, `-r x`; after the value of any other flag, such as `--dns-result-order ipv4first`, the entry is the next path) and treats `src/cli.ts` as gbrain when the package two levels up is named gbrain; an unreadable package falls back to the old path match. `bun run <file>` runs the file in its own process and is classified; `bunx`, `bun x` and `bun run <bin>` are wrappers whose child is the gbrain process, so they are no longer counted twice. A worker whose parent is not recognised as gbrain is refused with that parent's pid and executable name; its command line, which can carry credentials, is never printed or put in `--json` output. On macOS, where the working directory is not read, a relative entry still matches a gbrain path; otherwise its worker is refused with the parent's pid and executable name (`ps -p <pid> -o command=` shows the rest).+ - `scripts/eval-spend-guard.sh` (#8717): the lease's start time is read before the signal traps are armed, so no command substitution is parsed between arming them and `wait`. A TERM that landed there ran its trap while bash 5.2 still expected the lease line's `)`, the trap failed with "unexpected EOF while looking for matching `)'", the signal was lost and the guard waited out its command and exited 0. Under CPU load the original guard did that in 3 of 3000 forced TERMs and the fixed guard in 0 of 3000, interleaved. `test/eval-spend-guard.test.ts` pins that no command substitution sits in that window; the exit-143 assertion is unchanged.+ - `.github/workflows/test.yml`, `e2e.yml`, `stress.yml` (#8700): the 15 `pglite-snapshot` cache keys hash `src/core/**/*.ts` (plus the snapshot builder and its test helper) instead of `src/core/*.ts` and a hand list of subdirectory files, so a schema input in a new `src/core` folder needs no workflow edit. A change anywhere under `src/core` now rebuilds the snapshot cache.+ - `scripts/stress/run.ts` (#8702): a pooler-gated test is exempt from the stress gate only when the workflow job that names it, or the script lines beside it, set `GBRAIN_CI_REQUIRE_PGBOUNCER`; a flag elsewhere in the same file no longer counts. `test/e2e/graduation-cli-topologies.test.ts` is no longer exempt, and a script owner is reported as an "owning pooled runner".+ - `src/core/persistence/physical-root-record.ts` (#8713): verifying a physical root inside a Git checkout writes the ownership-marker exclude once per process, so a repo-less brain that later ran `git init` stops offering its `.gbrain-owner.json` to `git add -A`. The conversion refusal for a root with no Git history now says to add the exclude before the first `git add -A`. Doctor's existing `tracked_ownership_marker` check (#5186) still names a stamp already in the index with the `git rm --cached` fix, which keeps the file and history.++ ## [0.60.596.0] - 2026-11-06++ **With the refresh write barrier on, a page write no longer bounces because a sync is running, and a `gbrain sources refresh` killed at any point recovers on its own or stops for an operator, never losing work.** The barrier is still off by default (`persistence.refresh_barrier`), and with it off writes behave as before. With it on, a `put_page`, `capture`, `remember` or `add_timeline_entry` whose page file holds a committed change managed sync has not imported yet is answered pending instead of refused `pending_import`, then prepared again once the import lands. A write during a refresh stuck in `recovery_required` waits too, and the per-refresh deferral cap is gone. Wherever `worktree_refreshing` still refuses, `retry_after_ms` is estimated from the refresh instead of a fixed second.++ ### What changed++ | Situation (barrier on) | Before | Now |+ |---|---|---|+ | A page write onto a file with a committed change sync has not imported | refused `pending_import` | pending; lands after the import (a `put_page` with `expected_revision` ends `revision_conflict` when the import moved the page) |+ | A blind `put_page` that replaces imported content | n/a | lands and names the revision and commit it replaced in `supersedes`, a `gbrain-supersedes:` commit trailer and the commit ledger |+ | The import never lands within the wait limit of the hold | n/a | `pending_import_expired`, nothing applied; a `remember` ends as its `pending_import` refusal did and is replayed after the import |+ | A write during a refresh in `recovery_required` | refused `refresh_recovery_required` | waits behind the refresh and lands once it is resumed or abandoned |+ | Writes past `persistence.refresh_barrier_max_deferred` | refused | deferred; the setting is no longer read |+ | `retry_after_ms` on `worktree_refreshing` | always 1000 | the refresh's typical remaining time, at least 15 s while syncing and 2 s otherwise |++ ### Itemized changes++ - Import holds (`src/core/persistence/import-deferral.ts`, journal claim, `refresh-barrier.ts`): the consumer moves its own claim back to `deferred` naming the last imported commit, and the row is claimable again once `sources.last_commit` moves. A later write to the same page never passes a held one, and expiry rechecks under the source lock that the import still has not landed. An idle owner counts an overdue hold as work, so expiry runs with nothing else queued. A hold happens only when every live consumer on the owner host advertises `refresh_barrier_import_1`; otherwise the write keeps the refusal. Schema migration v294 adds `persistence_requests.deferred_import_from` and widens the deferred-row guard.+ - Refresh crash recovery (`src/core/persistence/worktree-refresh.ts`): a refresh records `merge_started` in a committed transaction before `git merge --ff-only`. A refresh killed at `fenced` before its merge, whose HEAD then moved on its own line (gbrain commits from its drain, or anyone else's), aborts as `refresh_interrupted` instead of being recorded as merged. One whose HEAD reached the target records the merge. A started merge followed by a reset and an unrelated commit still stops at `recovery_required` for an operator.+ - Retry hint (`src/core/persistence/refresh-retry-hint.ts`): the median duration of the worktree's last completed refreshes minus how long this one has run, leaving out refreshes that waited in `recovery_required`. The message says the write was not saved and when to retry, and the CLI's human output ends with one line saying the same.+ - Tests on PGLite and Postgres: `test/import-write-barrier.test.ts` (every held operation, supersedes, expiry, the remember replay, the hold clock, the capability gate, the idle-owner expiry, recovery_required and same-page ordering), `test/refresh-retry-hint-gst1582.test.ts`, and the crash-recovery cases in `test/refresh-write-barrier.test.ts`. Design note: docs/designs/REFRESH_WRITE_BARRIER.md, "Writes that wait for an import" and "Crash recovery".++ ## [0.60.595.0] - 2026-11-06++ **A `memory_recall` that names sources reads as that scope, never as the attested person, so a shared turn can no longer recall one member's private facts into a shared channel.** `memory_recall` gains `source_id` and `source_ids`. Named, the read drops the person's own recent facts and every member-page fact, keeps restricted pages hidden and never relaxes `visibility: private`. The contract for it is the new `docs/contracts/qm-memory-provider/v2.json`; `v1.json` stays byte-identical and a test holds it there. Three smaller provider fixes ride along.++ ### What changed++ | Situation | Before | Now |+ |---|---|---|+ | `memory_recall` with `source_id` / `source_ids` | the argument was ignored (`unknown_param`) and the call read as the person, own facts first | reads the named sources as their audience: no own facts, no member-page facts; a source outside the grant is `permission_denied`, `__all__` is `invalid_params` |+ | `memory_recall` without sources | the person's read | unchanged |+ | `acting_user` with no `x-qm-actor`, from a credential bound to a member | `argument_without_attestation` | its own member id (or a linked canonical id) is dropped and the call runs as the credential; any other value is `argument_mismatch` |+ | `recall` with `max_chars` | unknown argument | 200-12000: whole facts, then results, that fit; `truncated` says if some were cut |+ | A read that ignores an undeclared argument | a `[gbrain notice unknown_param]` text block in the result | only `_meta.warnings`, so a harness that stores tool output never stores it; writes still refuse |++ QM clients that read v1 keep working unchanged. A shared-scope turn should name its sources and read the v2 contract.++ **QM can now save a shared scope's memory (a project, channel or team) as well as each person's, and nothing else can read that scope.** `memory_write` gains `source_id`: named, the facts go to that scope source's `memory/scope` page, world-readable inside the source, still attested to the person who said them. The operator lists the scope sources on the QM credential with `gbrain auth rescope --attest-sources`, which marks each one a scope source for good. A scope source is never federated and never joins another credential's read grant, so its memory is read only by naming it from the scope credential, and a person read never sees it.++ | Situation | Before | Now |+ |---|---|---|+ | `memory_write` with `source_id` | refused (`unknown_param`) | saves on `memory/scope` in that source when the credential lists it in `--attest-sources`; otherwise `permission_denied` reason `source_not_attested`; the credential's own write source is `invalid_params` reason `source_is_member_source` |+ | `gbrain auth rescope --attest-sources a,b\|none` | no such flag | lists the scope sources; refuses `default`, a federated source, the own write source, a source another credential reads, ops beyond the memory tools and the private-pages grant |+ | A grant, token or registration that reads a scope source | n/a | refused (`QM scope source`), also after the scope credential is revoked |+ | `sources federate` / `sources restore` on a scope source | federates | refused / restored unfederated; a federated flag on a scope source is ignored |+ | Remote write to `memory/scope` (put_page, remember, delete_page, tags, links, timeline) | allowed like any page | refused unless it is a scope `memory_write` |+ | `memory_recall` without sources from a credential that reads a scope source | n/a | never reads the scope source |++ **A long recall question that opens with an instruction preamble finds the facts its last message asks about on a keyword-only brain, and refusals say what they need.** Recall used to score a question on its first 12 content words, so a provider preamble filled all 12 and nothing cleared the admission floor.++ | Situation | Before | Now |+ |---|---|---|+ | `recall` `question` over 12 content words | scored on its first 12 | searched on its last 24, scored on the 12 of those the fewest candidate facts hold; shorter questions unchanged |+ | Candidates found, none above the admission floor | empty `facts`, nothing else | empty `facts` plus `facts_below_floor: <n>` (absent when nothing matched) |+ | `recall` `question` over 2,000 characters | bare `invalid_params` | `invalid_params` reason `question_too_long`, detail `max_chars=2000 received_chars=<n>`; never cut |+ | `acting_user` refused `argument_without_attestation` | no detail | detail `missing=x-qm-actor`, `missing=attest_right` or both, also in `structuredContent.error` |++ ## [0.60.594.0] - 2026-11-06++ **A page write that reaches a checkout while `gbrain sources refresh` runs can now wait for the refresh instead of being refused, and every commit gbrain makes is recorded, so doctor can name commits made outside it.** The write barrier is off by default (`persistence.refresh_barrier`). With it on, a single page write that arrives while a refresh drains or merges the checkout is journaled and answered pending at once: MCP gets `isError: false` with `status: "pending"`, and the CLI exits 10 with the command that polls it, on the owner socket and on a thin client alike. The write commits after the refresh. It ends `revision_conflict` with nothing applied when the refresh changed its file, and `refresh_barrier_expired` when the refresh outlives `persistence.refresh_barrier_max_wait_ms` (15 minutes), even on an owner with nothing else to do. The commit ledger and doctor's new `foreign_writers` check run on every brain with a Git checkout. The owner-path guard installs only when you run `gbrain sources guard --install`.++ ### Itemized changes++ - Refresh write barrier (`src/core/persistence/refresh-barrier.ts`, journal admission and claim, the consumer): requests gain a `deferred` state tied to the refresh they wait behind. Only a claim that declares the barrier can move a deferred row, and only after its refresh is released. A released write replays its change check against the refresh's diff, so a blind write never overwrites a file the refresh changed. Syncs, jobs and batches keep the `worktree_refreshing` refusal, and a live consumer that cannot drain deferred rows keeps it too. Restore, cancel, token revocation and source lifecycle changes end a deferred write with nothing applied and release its counters. Schema migration v292 adds the columns, the release trigger and an online partial index over the four open request states, so receipt polls stay index-served on a long receipt history.+ - `gbrain upgrade --check-downgrade` exits 3 `downgrade_blocked_deferred_writes` while deferred writes wait. `gbrain sources writer status` lists them.+ - Commit ledger (`src/core/git/commit-ledger.ts`): every gbrain commit site appends one line to `<git common dir>/gbrain/commit-ledger.jsonl`, rotated at 4 MiB. A failed append never fails the commit.+ - New doctor check `foreign_writers`: a commit in a source checkout on this host that the ledger does not name fails the check with the newest such commit and a fix that asks who makes it. Unconfirmed commits and page files uncommitted for over 30 minutes warn. Its git reads take no optional locks, so a doctor run never holds `index.lock` against a commit. A repo-less brain reports not_applicable.+ - New `gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]`: the commit guard on a managed source's worktree, from its owner host, in a hooks directory private to that worktree. gbrain's own hooks at the old hooks path, the brain-durability post-commit hook included, are copied along, so installing it never turns Git durability off. `--mode enforce` also refuses cherry-pick, revert, rebase and sequencer commits.+ - `gbrain git commit-push --base <path>=<blob>|absent` refuses `commit_base_moved`, committing nothing, when the file at HEAD is no longer the blob the caller read. It also refuses `checkout_not_a_source` when a managed brain's command resolved a checkout from the working directory that is none of its sources (#8662).+ - `gbrain repair file-drift` with `--held`, `--side`, `--state`, `--cursor` or `--provenance` and no `--prefer` refuses with the usage line instead of running the all-drifted survey (#8615).+ - A `gbrain sources refresh` run refused `refresh_source_changed` by a moving HEAD or late work retries once from a fresh precheck in the same run (#8617).+ - Tests on PGLite and Postgres: `test/refresh-write-barrier.test.ts` (every deferred outcome, including edit_page, forget and source lifecycle changes, the idle-owner expiry and the owner-socket exit 10), `test/commit-ledger.test.ts`, `test/doctor-foreign-writers.test.ts`, `test/sources-guard.test.ts`, `test/mcp-client.test.ts` (a thin client's pending deferred write) and the state audit in `test/refresh-barrier-state-audit.test.ts`. Design note: docs/designs/REFRESH_WRITE_BARRIER.md.+## [0.60.593.0] - 2026-11-06**`gbrain repair failed-writes` now previews a brain with a large write journal in about a second instead of timing out.** On Postgres, the preview of refused writes read the request table once per refused write, and one of those reads walked the table from that write to its end. With hundreds of refused writes and a journal of over a million requests, the preview ran for minutes and the server's statement timeout ended it with a bare `internal_error`, so the operator had no way to see or recover the lost writes. The preview now classes refused writes together in set reads, each sized so it stays short even on a page with hundreds of refused writes and a long history. On a synthetic journal of 1.5 million requests with over 800 refused writes it took about a second (it took 265 seconds before), with the same classes and the same preview hash. When a preview read does still run past the timeout, it refuses `repair_preview_timeout` with a fix instead of `internal_error`, and nothing is saved.