Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Name bisect and squash merges in the adoption refusal and the intent line proof in the key files entry
garrytan0ecd033a0aeb
diff --git a/docs/architecture/key-files/core-persistence-request-indexes.md b/docs/architecture/key-files/core-persistence-request-indexes.mdindex c5ea58bcf8..a78bc19c4b 100644--- a/docs/architecture/key-files/core-persistence-request-indexes.md+++ b/docs/architecture/key-files/core-persistence-request-indexes.md@@ -17,4 +17,4 @@ The online-built request-table indexes (the managed sync checkpoint pair, the pa- `src/core/persistence/hosted-repo.ts` with `src/commands/sources-host-repo.ts` — G7b-2, `gbrain sources host-repo <id> --dir <path> [--push-remote <url>] [--dry-run | --expect <plan_hash>]`: a hosted brain gives an empty, unbound source a bare repository (`<dir>/repo.git`, branch `main`, one commit holding an empty `.gitignore`, repository-local identity `gbrain`) and checks it out as a linked worktree (`<dir>/worktree`) claimed through `runManagedSourceLifecycle` (`add` or `claim`, every physical-root and manifest check), with `config.canonical = "git"` and `config.hosted_repo` set in the claim's own transaction. The door then commits there unchanged. A pre-receive hook (`core.hooksPath` pinned to the repository's `hooks/`) refuses every push, since Git's checked-out-branch refusal ends once the worktree is pruned. The preview (the default without `--expect`) prints the plan in words and a `plan_hash` over the source incarnation, canonical setting, directory state, push remote and hook; the apply refuses `preview_changed` when it moved. Refuses `strict_requires_managed` on an unmanaged brain, `hosted_repo_refused` (`source_bound`, `source_has_path`, `source_has_pages`, `source_archived`, `dir_not_empty`) and `overlapping_path` (a directory in a checkout or a source's directory). On a hosted source the preview reports the hook (`ok`/`missing`/`changed`) and the worktree link, and the apply reinstalls the hook. Trusted local CLI only; no operation. Tests: `test/hosted-repo-g7b2.test.ts` (both engines).- `src/core/persistence/worktree-link.ts` `linkedWorktreeProblem` / `assertLinkedWorktreeIntact` — a claim (`localRoot` in `source-lifecycle.ts`) refuses `git_worktree_link_broken` for a linked worktree whose `.git` file names a repository entry that is gone (pruned) or whose entry names another path (the checkout moved); a submodule's `.git` file is checked for existence only. Tests: `test/hosted-repo-g7b2.test.ts`.- `src/core/persistence/sync-receipt-wait.ts` — how long a managed sync pass waits on its own admitted write, in one place: `syncReceiptWait()` returns `pass` (5 s), `checkpoint` (8 s), `held` (30 s, while this process's consumer still holds the write) and `drain` (30 s, a drain's re-entry). `sync-run.ts` reads every wait from it. `__setSyncReceiptWaitForTests(partial | null)` is the test seam (returns a restore function), so a test outlasts a wait in milliseconds instead of sleeping past 30 s.-- **`src/core/persistence/local-edit-adoption.ts`** — GST-1601 part 2: with `persistence.adopt_local_edits.source.<id>` on, `finishUnpublishedFailure` (`coordinator.ts`) hands a `remember` / `capture` / `add_timeline_entry` refused `file_database_drift` to `adoptLocalEdit`, which reads the drifted file the refusal carries (`localEdit`, set in `page-prepare.ts` compareFileTarget), waits until it is quiet (`persistence.adopt_quiet_ms`, empty reads as the 5000 default, at most three windows and never past 30 s: the caller's claim holds its worktree queue meanwhile), and adopts only a one-sided, safe edit (#8755: a file over `PAGE_MAX_BYTES`, checked by stat before reading, a segmented page, an unmerged path or an operation in progress (`pending-import.ts` `unmergedPath` / `operationMarkerPaths`; #8826 adds `BISECT_LOG` and `SQUASH_MSG` and reads `--absolute-git-dir` as bytes, answering null unless it is one absolute, existing directory in valid UTF-8), and a stale editor save (`staleEditorSave`: the file equals an earlier `page_versions` body, or lacks a list or table row the current revision has and its newest archived version had not) keep the refusal; the repo-less test walks up for `.git`): HEAD's blob matches the database copy (`fileMatchesSnapshot`; a repo-less brain skips this), `protectedLocalEdit` finds no title, type or protected-key change, and `prepareRepairPublication` is `ready`. The adoption is a `managed_file_repair` (`file-repair.ts`) carrying `adoptLocalEdit` (`{ blob, replaced_revision }`), admitted under the CLI writer with a request id derived from the caller's (one adoption per write), claimed and published inline (`publishMutation`, retrying a busy worktree lock for 10 s) so it lands before the caller: it publishes the file's unchanged bytes with the `localEditAdoptionCommit` note, stamps the archived replaced revision `change_reason = 'adopted_local_edit'`, and commits that one file inside its publication transaction (`afterEffects` → `commitAdoptedLocalEdit`; a strict source's door commits it instead). #8755: a publication that fails after that commit is requeued by recovery and `publishAdoption` publishes it again (it retries any release within its 10 s): `adoptedHeadHolds` accepts HEAD holding the adopted blob and the replay names the landed commit (`landed_before_row`). The intent names the caller's claim (`adoptLocalEdit.caller`); `assertAdoptionCaller` (`file-repair.ts` preparation) refuses `write_claim_lost` once that claim is gone, so an adoption orphaned by a crash publishes nothing; its own claim carries the owner stamp. #8824: the check runs only until the adoption's commit lands: once HEAD holds it (`landedAdoptionCommit`: the newest commit on the path has the adoption's subject, trailer and commit-ledger line, its parent holds the pre-adoption blob and HEAD the adopted one), a replay publishes it whatever became of its caller, and `settleAdoption` leaves such a requeued adoption to the consumer instead of cancelling it. #8767: `recoverPublication` (`coordinator.ts`) stamps that commit (`adoptionCommitLanded`) as `outcome.persistence = {git_state: committed, git_commit, landed_before_row: true}` on the requeued or failed receipt, which `completeWrite` keeps on any later end without committing. `settleAdoption` waits up to 120 s more on an adoption whose publication already started; a caller whose claim was lost is returned as `claimLost`, never `released`; an admission failure logs `[persistence] phase=adoption`. The caller is then released with `intent.adopted_local_edit` and prepared again; `withAdoptedLocalEdit` (`service.ts` preparePersistedMutation) puts `adopted` on its receipt. A file changed under the adoption ends both `raw_file_changed`. Commit-ledger lines carry `adopted` (`adoptedBy`, `effect-model.ts`). Doctor `local_edit_adoptions` (`src/commands/doctor/checks/local-edit-adoptions.ts`) lists adoptions of the last 24 h per source from `outcome.adopted_local_edit` (kept by compaction), always ok. Tests: `test/adopt-local-edit.test.ts`, `test/operation-marker-paths.test.ts`.+- **`src/core/persistence/local-edit-adoption.ts`** — GST-1601 part 2: with `persistence.adopt_local_edits.source.<id>` on, `finishUnpublishedFailure` (`coordinator.ts`) hands a `remember` / `capture` / `add_timeline_entry` refused `file_database_drift` to `adoptLocalEdit`, which reads the drifted file the refusal carries (`localEdit`, set in `page-prepare.ts` compareFileTarget), waits until it is quiet (`persistence.adopt_quiet_ms`, empty reads as the 5000 default, at most three windows and never past 30 s: the caller's claim holds its worktree queue meanwhile), and adopts only a one-sided, safe edit (#8755: a file over `PAGE_MAX_BYTES`, checked by stat before reading, a segmented page, an unmerged path or an operation in progress (`pending-import.ts` `unmergedPath` / `operationMarkerPaths`; #8826 adds `BISECT_LOG` and `SQUASH_MSG` and reads `--absolute-git-dir` as bytes, answering null unless it is one absolute, existing directory in valid UTF-8), and a stale editor save (`staleEditorSave`: the file equals an earlier `page_versions` body, or lacks a list or table row the current revision has and its newest archived version had not) keep the refusal; the repo-less test walks up for `.git`): HEAD's blob matches the database copy (`fileMatchesSnapshot`; a repo-less brain skips this), `protectedLocalEdit` finds no title, type or protected-key change, and `prepareRepairPublication` is `ready`. The adoption is a `managed_file_repair` (`file-repair.ts`) carrying `adoptLocalEdit` (`{ blob, replaced_revision }`), admitted under the CLI writer with a request id derived from the caller's (one adoption per write), claimed and published inline (`publishMutation`, retrying a busy worktree lock for 10 s) so it lands before the caller: it publishes the file's unchanged bytes with the `localEditAdoptionCommit` note, stamps the archived replaced revision `change_reason = 'adopted_local_edit'`, and commits that one file inside its publication transaction (`afterEffects` → `commitAdoptedLocalEdit`; a strict source's door commits it instead). #8755: a publication that fails after that commit is requeued by recovery and `publishAdoption` publishes it again (it retries any release within its 10 s): `adoptedHeadHolds` accepts HEAD holding the adopted blob and the replay names the landed commit (`landed_before_row`). The intent names the caller's claim (`adoptLocalEdit.caller`); `assertAdoptionCaller` (`file-repair.ts` preparation) refuses `write_claim_lost` once that claim is gone, so an adoption orphaned by a crash publishes nothing; its own claim carries the owner stamp. #8824: the check runs only until the adoption's commit lands: once HEAD holds it (`landedAdoptionCommit`: the newest commit on the path has the adoption's subject, trailer and commit-ledger line, its parent holds the pre-adoption blob and HEAD the adopted one; the commit line is written after `git commit` and can be missing, so the ledger's intent line also proves the commit when its `head_before` is the commit's parent and its message digest is the commit's), a replay publishes it whatever became of its caller, and `settleAdoption` leaves such a requeued adoption to the consumer instead of cancelling it. #8767: `recoverPublication` (`coordinator.ts`) stamps that commit (`adoptionCommitLanded`) as `outcome.persistence = {git_state: committed, git_commit, landed_before_row: true}` on the requeued or failed receipt, which `completeWrite` keeps on any later end without committing. `settleAdoption` waits up to 120 s more on an adoption whose publication already started; a caller whose claim was lost is returned as `claimLost`, never `released`; an admission failure logs `[persistence] phase=adoption`. The caller is then released with `intent.adopted_local_edit` and prepared again; `withAdoptedLocalEdit` (`service.ts` preparePersistedMutation) puts `adopted` on its receipt. A file changed under the adoption ends both `raw_file_changed`. Commit-ledger lines carry `adopted` (`adoptedBy`, `effect-model.ts`). Doctor `local_edit_adoptions` (`src/commands/doctor/checks/local-edit-adoptions.ts`) lists adoptions of the last 24 h per source from `outcome.adopted_local_edit` (kept by compaction), always ok. Tests: `test/adopt-local-edit.test.ts`, `test/operation-marker-paths.test.ts`.diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 146dbc9324..3ca4d90688 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -51,7 +51,7 @@ of making a duplicate.| Reason | Error code | What it means | Recovery || --- | --- | --- | --- |-| <a id="file_database_drift"></a>`file_database_drift` | `source_changed` | The page's canonical file and its database copy disagree, usually because the file was edited outside a coordinated write. Neither copy was overwritten. The receipt records the cause as `error_detail.origin: file_database_drift` (GST-1601). A file with no `type:` line keeps the stored type, and titles compare trimmed, so those alone do not cause this. Drift only in ordinary frontmatter keys (not a policy, privacy, lineage or trust key such as `readable_by`, `derived_from` or `trust_tier`, nor title, type or tags) does not refuse a write that leaves the frontmatter unchanged, such as `remember`: the write lands and the file keeps its own frontmatter, so that drift is left for reconcile (#8109). With `gbrain config set persistence.adopt_local_edits.source.<source> true` (off by default), a `remember`, `capture` or `add_timeline_entry` that meets a one-sided local edit (Git `HEAD` still holds the database copy; on a repo-less brain, any edit) is not refused: once the file has been unchanged for `persistence.adopt_quiet_ms` (default 5000), the owner commits that file on its own (`gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`; page history reason `adopted_local_edit`), then applies the write on top, and the receipt names `adopted`. A two-sided edit, a file that does not import, an edit to the title, type or a protected key, `put_page` and every other verb still refuse; doctor `local_edit_adoptions` lists adoptions of the last 24 h (GST-1601). The refusal also stays for a file over the page size limit or a page stored in segments, an unmerged path or a merge, cherry-pick, revert or rebase in progress, and a stale editor save (a file equal to an earlier stored revision, or missing a Facts or timeline row the last write added); the quiet wait never passes 30 s, since writes behind it on the same checkout wait meanwhile (#8755). It also stays while a `git bisect` (`BISECT_LOG`) or an uncommitted `git merge --squash` (`SQUASH_MSG`) is in progress, and when `git rev-parse --absolute-git-dir` answers with anything but one absolute, existing directory in valid UTF-8; a `git cherry-pick -n` leaves no marker, and its staged paths stay out of the adoption's commit (#8826). An adoption whose commit landed before its publication failed is published on its replay even after the write it was made for ended, and one that ends without committing after that commit names it on its receipt (`outcome.persistence.git_commit`, `landed_before_row: true`; #8824, #8767). | The receipt's fix (`gbrain sources writer failures <source>`, `gbrain write-request <request_id> --json`) previews keeping the database copy for that one page with `gbrain repair file-drift --source <source> --slug <slug> --prefer database` (`--prefer file` previews importing the file instead); a person picks the side, then the agent runs the apply command the preview prints. A group of such receipts gets `--all-drifted --since <instant>` with the oldest receipt's time, so only pages that drifted since then are selected. For a hand merge: `gbrain sources reconcile <source> <slug> --brain <brain> --preview`, review the preview, resolve it, then `--apply <resolved-preview-file> --request-id <new uuid>`. Retry the original write with a **new** request ID. A page that records no file of its own (no `source_path`, typically written by an older release whose write-through also put `ingested_via` / `ingested_at` / `source_kind` in the file only) reconciles against the file at its slug path only when you add `--adopt-slug-path` to the preview; the refusal names the flag in that case, and apply records that file as the page's origin. See [repair a file/database disagreement](concurrent-writes.md#repair-a-filedatabase-disagreement). Many pages at once: `gbrain sources reconcile <source> --brain host --audit --conflicts` lists them and `gbrain repair file-drift` resolves them, preferring the file or the database copy ([file drift](repair.md#file-drift)). |+| <a id="file_database_drift"></a>`file_database_drift` | `source_changed` | The page's canonical file and its database copy disagree, usually because the file was edited outside a coordinated write. Neither copy was overwritten. The receipt records the cause as `error_detail.origin: file_database_drift` (GST-1601). A file with no `type:` line keeps the stored type, and titles compare trimmed, so those alone do not cause this. Drift only in ordinary frontmatter keys (not a policy, privacy, lineage or trust key such as `readable_by`, `derived_from` or `trust_tier`, nor title, type or tags) does not refuse a write that leaves the frontmatter unchanged, such as `remember`: the write lands and the file keeps its own frontmatter, so that drift is left for reconcile (#8109). With `gbrain config set persistence.adopt_local_edits.source.<source> true` (off by default), a `remember`, `capture` or `add_timeline_entry` that meets a one-sided local edit (Git `HEAD` still holds the database copy; on a repo-less brain, any edit) is not refused: once the file has been unchanged for `persistence.adopt_quiet_ms` (default 5000), the owner commits that file on its own (`gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`; page history reason `adopted_local_edit`), then applies the write on top, and the receipt names `adopted`. A two-sided edit, a file that does not import, an edit to the title, type or a protected key, `put_page` and every other verb still refuse; doctor `local_edit_adoptions` lists adoptions of the last 24 h (GST-1601). The refusal also stays for a file over the page size limit or a page stored in segments, an unmerged path or a merge, cherry-pick, revert, rebase, `git bisect` (`BISECT_LOG`) or uncommitted `git merge --squash` (`SQUASH_MSG`) in progress, and a stale editor save (a file equal to an earlier stored revision, or missing a Facts or timeline row the last write added); the quiet wait never passes 30 s, since writes behind it on the same checkout wait meanwhile (#8755). It also stays when `git rev-parse --absolute-git-dir` answers with anything but one absolute, existing directory in valid UTF-8; a `git cherry-pick -n` leaves no marker, and its staged paths stay out of the adoption's commit (#8826). An adoption whose commit landed before its publication failed is published on its replay even after the write it was made for ended, and one that ends without committing after that commit names it on its receipt (`outcome.persistence.git_commit`, `landed_before_row: true`; #8824, #8767). | The receipt's fix (`gbrain sources writer failures <source>`, `gbrain write-request <request_id> --json`) previews keeping the database copy for that one page with `gbrain repair file-drift --source <source> --slug <slug> --prefer database` (`--prefer file` previews importing the file instead); a person picks the side, then the agent runs the apply command the preview prints. A group of such receipts gets `--all-drifted --since <instant>` with the oldest receipt's time, so only pages that drifted since then are selected. For a hand merge: `gbrain sources reconcile <source> <slug> --brain <brain> --preview`, review the preview, resolve it, then `--apply <resolved-preview-file> --request-id <new uuid>`. Retry the original write with a **new** request ID. A page that records no file of its own (no `source_path`, typically written by an older release whose write-through also put `ingested_via` / `ingested_at` / `source_kind` in the file only) reconciles against the file at its slug path only when you add `--adopt-slug-path` to the preview; the refusal names the flag in that case, and apply records that file as the page's origin. See [repair a file/database disagreement](concurrent-writes.md#repair-a-filedatabase-disagreement). Many pages at once: `gbrain sources reconcile <source> --brain host --audit --conflicts` lists them and `gbrain repair file-drift` resolves them, preferring the file or the database copy ([file drift](repair.md#file-drift)). || <a id="canonical_file_missing"></a>`canonical_file_missing` | `source_changed` (a caller write; maintenance refuses before admission) | The page's recorded canonical file is gone while its database page is still live (a ghost page: the file was moved or deleted outside gbrain). A caller write refuses with "The canonical file was removed outside coordinated publication." and nothing is written; retrying it refuses the same way. A maintenance write (fact-fence adoption, enrichment, `dream`) is refused before admission: no request id, no receipt (before #6696 each cycle settled a `conflict` receipt). `gbrain sources writer failures <source>` reports such receipts as category `canonical_file_missing`. Neither copy was changed. | Decide which copy is right. If the file should exist, restore it at its recorded path and preview the page with `gbrain sources reconcile <source> <slug> --brain host --preview`, or sync. If the page should go, preview the ghost-page repair with `gbrain repair ghost-pages --source <source>` (read-only; it prints the apply command with its hash) and apply it with `--apply --expect <hash> --yes` only after the user agrees; a soft-deleted page can be restored with `gbrain restore <slug> --force` until the autopilot purge 72 h later. `gbrain pages ghosts --source <source>` and doctor `ghost_pages` list them, doctor `maintenance_write_drift` lists held-back maintenance writes. See [ghost pages](repair.md#ghost-pages). || <a id="refusal_breaker"></a>`refusal_breaker` | the code of the earlier refusals | The same maintenance write (same source, slug, page revision, planner and intent) was refused `persistence.maintenance.refusal_breaker_threshold` times (default 3; `0` turns it off) in the last 24 hours, so maintenance submits nothing for it instead of adding another receipt (#6696). It is tried again once the page, the planner or the write changes, or when the oldest refusal is 24 hours old. | Read the last refusal with `gbrain write-request -- <request_id>` (named in the message) and fix what it names. Doctor `maintenance_write_drift` lists every held-back write with its exit. || <a id="canonical_file_absent"></a>`canonical_file_absent` | `source_changed` (`restore_page` / `gbrain restore`) | On a brain without managed persistence, a restore that writes no file (`sync.write_through` off, a sandbox, a database-only source) of a soft-deleted page whose recorded file is no longer among the files sync imports (#6609). A plain restore would be undone by the next `gbrain sync --full`, so nothing was restored. Not retryable; the fix asks the user. | Ask the user. To keep the page with its file: put the file back at its recorded path, commit it and `gbrain sync --source <source>`. To keep it database-only: `gbrain restore <slug> --source-id <source> --detach` (MCP `restore_page` with `detach: true`), which forgets the recorded file and stamps `database_only_reason='detached'`. See [restoring a page whose file is gone](../storage-tiering.md#restoring-a-page-whose-file-is-gone). |