Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(changelog): source_changed causes and opt-in local edit adoption (GST-1601)

garrytan043bef73d11e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b416478004..c9809b3bf5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,18 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**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.
diff --git a/TODOS.md b/TODOS.md
index a1b70418dd..79c83bc76a 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,5 +1,9 @@
# TODOS
+## Local edit adoption follow-ups (filed 2026-11-07, GBRA-341, #8755)
+
+- [ ] **P2 — Harden `adopt_local_edits` before any source turns it on (#8755).** **What:** the adoption can import merge-conflict markers, adopt an editor's stale save over gbrain's committed write, read a huge file whole, hold the worktree queue through its quiet window, leave its Git commit behind when the publication transaction rolls back, and treat a nested checkout's unreadable `HEAD` as repo-less. **Fix:** per item in #8755. **Effort:** M. **Priority:** P2.
+
## Memory train follow-ups (filed 2026-11-04, GBRA-286, #8481)
- [ ] **P3 — `extraction_pending`'s local relink argv can carry fenced fact text (#8597).** **What:** running the owner's relink action stores the quote fence as fact text. **Fix:** unquote before building the argv. **Effort:** S. **Priority:** P3.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index f5374c05bc..f9263a4511 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1467,7 +1467,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.594.0', id: 'refresh_barrier_prb', text: 'New setting `persistence.refresh_barrier` (off by default): with it on, a single page write (`put_page`, `remember` and the other single-page verbs) that reaches a checkout while `gbrain sources refresh` drains or merges it is journaled and answered `pending` at once (MCP `isError: false`, CLI exit 10) instead of refused `worktree_refreshing`. It commits after the refresh, or ends `revision_conflict` when the refresh changed its file, or `refresh_barrier_expired` after `persistence.refresh_barrier_max_wait_ms` (15 minutes). Syncs, jobs and batches keep the refusal. `gbrain upgrade --check-downgrade` exits 3 `downgrade_blocked_deferred_writes` while such writes wait.' },
{ since: '0.60.596.0', id: 'refresh_barrier_import_gst1582', text: 'With `persistence.refresh_barrier` on, no page write bounces because a sync is running: 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` (receipt `deferred: { pending_import: true }`) instead of refused `pending_import`, and is prepared again once the import lands (a `put_page` with `expected_revision` then ends `revision_conflict` if the import moved the page; a blind one lands and names the revision and commit it replaced in `supersedes`, a `gbrain-supersedes:` commit trailer and the commit ledger), or ends `pending_import_expired` once held past the wait limit (a `remember` ends as its `pending_import` refusal did and is replayed after the import). A write during a refresh in `recovery_required` waits too, and `persistence.refresh_barrier_max_deferred` is no longer read: no write past it is refused. With the barrier off those refusals are unchanged. Wherever `worktree_refreshing` still refuses, `retry_after_ms` is estimated from the refresh (its typical duration minus how long it has run, at least 15 s while syncing and 2 s otherwise) instead of a fixed 1000, 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.' },
{ since: 'TBD', id: 'source_changed_origin_gst1601', text: 'A page write refused `source_changed` now records its cause in the receipt\'s `error_detail.origin` (`file_database_drift` for an uncoordinated local edit, `canonical_path_occupied`, `raw_file_changed`, `pinned_git_worktree_conflict`, `unsafe_file_target`, `source_binding_changed` or `unbound_source`), not only for `pending_import`, `sync_held` and `canonical_file_missing`, so `gbrain write-request`, doctor and receipt queries name it. Nothing else about the refusal changed, and none of these is replayed.' },
- { since: 'TBD', id: 'adopt_local_edits_gst1601', text: 'New per-source opt-in `persistence.adopt_local_edits.source.<id>` (off by default): a `remember`, `capture` or `add_timeline_entry` whose page file holds a local edit nobody committed, while Git `HEAD` still holds the database\'s copy (on a repo-less brain, any such edit), is no longer refused `file_database_drift`. Once the file has been unchanged for `persistence.adopt_quiet_ms` (default 5000), the owner commits the edit on its own (only that file, subject `gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`, a commit-ledger line; repo-less brains record it in the database only), keeps the replaced revision in page history with reason `adopted_local_edit`, then applies the write on top; its receipt names `adopted: { path, blob, replaced_revision }` and doctor `local_edit_adoptions` lists the last 24 h. An edit to the title, the type or a protected frontmatter key, a file that does not import, an edit on both sides, `put_page` and every other verb keep the refusal; a file changed again during the adoption ends `raw_file_changed` with nothing written.' },
+ { since: 'TBD', id: 'adopt_local_edits_gst1601', text: 'New per-source opt-in `persistence.adopt_local_edits.source.<id>` (off by default): a `remember`, `capture` or `add_timeline_entry` whose page file holds a local edit nobody committed, while Git `HEAD` still holds the database\'s copy (on a repo-less brain, any such edit), is no longer refused `file_database_drift`. Once the file has been unchanged for `persistence.adopt_quiet_ms` (default 5000), the owner commits the edit on its own (only that file, subject `gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`, a commit-ledger line; repo-less brains record it in the database only), keeps the replaced revision in page history with reason `adopted_local_edit`, then applies the write on top; its receipt names `adopted: { path, blob, replaced_revision }` and doctor `local_edit_adoptions` lists the last 24 h. An edit to the title, the type or a protected frontmatter key, a file that does not import, an edit on both sides, `put_page` and every other verb keep the refusal; a file changed again during the adoption ends `raw_file_changed` with nothing written, and bytes that are not valid UTF-8, a `HEAD` that moved or that Git cannot read, or a cancelled caller adopt nothing.' },
{ since: '0.60.594.0', id: 'commit_push_base_prb', text: '`gbrain git commit-push` takes `--base <path>=<blob>|absent` (repeatable, each path one the command commits): it refuses `commit_base_moved`, committing nothing, when the file at HEAD is no longer the blob the caller read. Without `--base` nothing changes.' },
{ since: '0.60.594.0', id: 'file_drift_held_needs_prefer_8615', text: '`gbrain repair file-drift` with `--held`, `--side`, `--state`, `--cursor` or `--provenance` and no `--prefer` now refuses with the usage line (`invalid_params`, and `file_drift_state_required` for a deleted side without `--state`) instead of silently running the all-drifted survey, which counted a different set of pages (#8615).' },
{ since: '0.60.594.0', id: 'refresh_source_changed_retry_8617', text: 'A `gbrain sources refresh` run refused `refresh_source_changed` because the checkout HEAD moved (a writer committing) or work reached the checkout after the drain check now retries once from a fresh precheck in the same run, so the tick is not lost (#8617). When the retry is refused too, the run returns the first `refresh_source_changed` refusal with the retry\'s cause appended; ownership or source-membership changes are not retried.' },