Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Docs name label_edit_refused among repair declines and say only repair visibility holds such pages (GST-2603)
garrytan9078e9019e85
diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex ec70f7874b..edf53077cf 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -2348,8 +2348,10 @@ writer's outstanding-request cap is low), and the ownerpublishes them in groups of up to 8, instead of one page and one wait at a time.Each page still has its own fate: a page whose write is declined fails alone andthe rest of its group lands. A decline is the page's own state refusing the-write: its file differs from the database or is gone (`source_changed`), or its-body is stored in segments. The page is left unchanged, the result counts it+write: its file differs from the database or is gone (`source_changed`), its+body is stored in segments, or its file cannot take the label edit line by line+([`label_edit_refused`](write-refusals.md#label_edit_refused), which never+counts toward the systemic-failure stop, even on its first try). The page is left unchanged, the result counts itunder `declined` by reason, and when every failure of a complete run is adecline the command exits 0, so a script working through windows carries on.Any other failure, or a stop, still exits 1. The next preview lists pages andiff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 222689c13f..ad25222367 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -53,7 +53,7 @@ of making a duplicate.| --- | --- | --- | --- || <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); the preview names any file edit or deletion sync never imported that the database copy would overwrite (in bulk such pages are kept, `kept_newer_file` / `kept_newer_delete`); a person picks the side, and the apply the preview prints asks for their consent (exit 3), taking `--yes` only after they agree ([newer file changes](repair.md#file-drift-newer)). 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. A visibility edit cannot publish while the file is gone, so to keep the page and only narrow who reads it, add a page rule on the brain host: `gbrain access rule add --slug <slug> --readers <member> --source <source>` (it previews; `--yes` applies; list the owner's member to keep the owner reading; removing the rule undoes it; upgrade every gbrain host that shares the brain first). No file is written for the page. 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="label_edit_refused"></a>`label_edit_refused` | `label_edit_refused` (reason `file_differs` or `label_line`) | An operator label repair (`gbrain repair visibility`, `gbrain repair private-labels`) left a page unchanged because its file holds the page but cannot take the label edit line by line (GST-2603). These repairs change only the label lines and never re-render a file, so a person's formatting and comments survive. `file_differs`: once its label lines are edited, the file still differs from the page in a real key, named in `detail` (a frontmatter key such as a date, the title, the type, the tags or the body); stamps gbrain keeps only in the database (a pack-renamed type, `validate: false`, `legacy_type`) never count. `label_line`: the label line has a block or multi-line value or a duplicate key, or the file has no frontmatter block. Nothing was written. The repair counts the page as declined, never toward `item_failures_systemic`, and the next preview holds it under `details.held` with its next step. | A file edited outside gbrain: preview it with `gbrain sources reconcile <source> <slug> --preview` (managed) or run `gbrain sync --source <source>` (unmanaged), then preview the repair again. A label line: write the label as one plain line (`visibility: private`), commit it and sync the source. |+| <a id="label_edit_refused"></a>`label_edit_refused` | `label_edit_refused` (reason `file_differs` or `label_line`) | An operator label repair (`gbrain repair visibility`, `gbrain repair private-labels`) left a page unchanged because its file holds the page but cannot take the label edit line by line (GST-2603). These repairs change only the label lines and never re-render a file, so a person's formatting and comments survive. `file_differs`: once its label lines are edited, the file still differs from the page in a real key, named in `detail` (a frontmatter key such as a date, the title, the type, the tags or the body); stamps gbrain keeps only in the database (a pack-renamed type, `validate: false`, `legacy_type`) never count. `label_line`: the label line has a block or multi-line value or a duplicate key, or the file has no frontmatter block. Nothing was written. The repair counts the page as declined, never toward `item_failures_systemic`. The next `gbrain repair visibility` preview holds it under `details.held` with its next step; `gbrain repair private-labels` has no held list, so its next preview lists the page again. | A file edited outside gbrain: preview it with `gbrain sources reconcile <source> <slug> --preview` (managed) or run `gbrain sync --source <source>` (unmanaged), then preview the repair again. A label line: write the label as one plain line (`visibility: private`), commit it and sync the source. || <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). || <a id="pending_import"></a>`pending_import` | `source_changed` (detail `file_database_drift`, reason `pending_import`) | The page's canonical file holds a change committed through Git (another agent's commit, a pull) that managed sync has not imported yet: the file on disk is exactly the blob `HEAD` holds for its path and not the one the source's last imported commit holds. The message is "The canonical file holds a committed Git change that sync has not imported yet." Nothing was overwritten. Since #6693 the receipt records origin `pending_import`; a write refused because sync holds the file records origin `sync_held` (see [held files](#held-files-and-content-refusals)). | A `remember` needs nothing from the caller: its `fix.next` is `wait`, the fact is kept in the receipt, and the first managed sync that imports the file (any outcome, a partial run included) makes one replay attempt on the original caller's lane with the fact's original `valid_from` and expiry (the sync result's `replayedRemembers` counts examined, replayed, waiting, skipped, remaining; at most 50 per run and 30 s). Do not save the fact again. A remember refused while sync held its file is replayed the same way once the repaired file is imported. A replay that is refused (authority revoked, page rewritten) stays listed by `gbrain repair failed-writes --source <source>` for a person. Any other write (`put_page`, `add_timeline_entry`) is never replayed automatically, because its body would replace the imported change: wait for the source's running sync owner (`gbrain serve`, autopilot or a sync job) to import the commit, which the refusal's read-only fix `gbrain sync status --source <source> --json` shows, then read the page again and resubmit with a new request ID. Neither refusal tells the caller to start a sync, because a second sync beside a running owner competes with it; when status shows no owner running, ask the user to sync the source on its host. An uncommitted hand edit still refuses `file_database_drift` and needs reconcile. With `persistence.refresh_barrier` on, a `put_page`, `capture`, `remember` or `add_timeline_entry` waits for the import instead of being refused ([deferred writes](#pending_import_expired)). |