Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(repair): disposition for parked Git effects of a former binding (#7985)

garrytan179cd8a5af41
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index 37aec25d0c..8abef4fef3 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -810,6 +810,59 @@ Do not delete binding rows by hand: the repair rechecks, in the same
statement, that the binding is still orphaned and that no pending write
request uses it.
+<a id="former-binding-effects"></a>
+### Parked Git effects of a former binding
+
+**Say to your agent:** *"writer status still shows a parked Git group, the
+exact retry says the canonical binding changed, and the bulk retry previews
+zero requests."*
+
+A Git effect records the canonical worktree binding it was queued under. After
+the source moves to another worktree (set-path, a transfer, a re-claim) or is
+re-created, the binding guard refuses that effect `source_changed` on every
+retry, and the bulk retries (`--parked-code`, `--parked-pushes`) select only
+the current binding's effects. A zero there is a different selection, not a
+clearance, and a healthy current binding or native-lock probe says nothing
+about the old effect. The guard stays: never claim or transfer the source,
+re-create it, or edit journal rows to force the effect through.
+
+How it shows up: writer status and doctor `parked_effects` list the effect in
+its own parked group with `former_binding` (`reason`, the recorded
+`worktree_ids`, the `current_worktree_id`, up to five `requests`), and the
+group's `command` is the settle preview; doctor's per-effect command is
+`settle-effects --request-id <id> --dry-run`; the exact
+`retry-effects --request-id <id> --dry-run` refusal names both bindings and
+has that preview as its `fix`; the bulk retry names the effects it leaves out
+under `former_worktree`.
+
+Disposition, with the user:
+
+1. `reason: binding_changed` (same source, new worktree): preview
+ `gbrain sources writer settle-effects <source> --request-id <id> --dry-run`.
+ It settles the effect only on proof that the current worktree committed and
+ pushed the page's current bytes and the fetched remote branch holds them
+ ([settle-effects](write-refusals.md#settle-effects)). Each refusal names the
+ missing piece: `no_covering_receipt` means no later write of the page went
+ through the current binding, so write the page through gbrain (its Git effect
+ commits and pushes it); `bytes_unpushed` waits for that push;
+ `remote_ref_missing` or `remote_ref_stale` needs a fetch in the checkout.
+ Preview again, show the user the proof, and run the printed `apply_command`
+ only after they agree. The settlement keeps the failure, request and bytes,
+ and `--unsettle` reverses it.
+2. `reason: source_replaced` (the source was archived, removed or re-created
+ after the effect): it owes nothing to the current source, and neither retry
+ nor settle runs it (settle refuses `source_replaced`). There is no
+ supported command that retires it yet; leave it parked and tell the user
+ what it is.
+
+These do not apply to it: `gbrain repair stuck-recovery` resolves recovery
+records blocked on unexpected file bytes, and a parked Git effect without a
+recovery record gives it nothing to resolve; cancelling the request returns a committed request unchanged; receipt
+compaction skips requests with uncommitted effects. A `write-request` read that
+returns `not_found` under another writer identity is a visibility limit, not
+proof the request is gone: writer status and the settle preview read the
+journal of the source.
+
### Managed sync orphans
<a id="managed-sync-orphans"></a>