fix(branchsync): settle wedged custody records via axi sync --recover --keep-local (#824)

docs/src/content/docs/guides/agents.md

@@ -178,6 +178,8 @@ no-mistakes axi abort --run <id>
 Before any post-pipeline local commit or fresh run, read `branch_sync`.
 Only when its structured `next_action.code` is `sync`, run `no-mistakes axi sync` first.
 When `next_action.code` is `recover_custody` - a terminal run left unpublished pipeline commits preserved in the local gate - run `no-mistakes axi sync --recover` to return custody, or `no-mistakes rerun` to resume validating the preserved head.
+When `next_action.code` is `return_custody_keep_local` - a terminal run whose recorded pipeline head cannot be verified, either because no reachable object store still has it or because the run's own recovery evidence names a different commit - run `no-mistakes axi sync --recover --keep-local` to return custody at your current head and point the gate branch at it where that branch still names a different head.
+When `next_action.code` is `complete_custody_return` - an earlier recovery already applied its Git changes and only the custody record is missing - re-run the exact command it names, `no-mistakes axi sync --recover` or `no-mistakes axi sync --recover --keep-local`, to complete the record; every Git step it repeats is idempotent once applied.
 A `branch_sync.state` of `user_owned` means the run went terminal before changing the submitted head and cancellation released the branch: it is immediately usable and needs no sync action.
 When `next_action.code` is `continue_active_run`, run the reported command and keep driving the active run.
 If synchronization is blocked, process that state instead of improvising reset, stash, merge, rebase, force, or branch replacement.

docs/src/content/docs/guides/tui.md

@@ -144,6 +144,8 @@ Pressing `u` explicitly refreshes the configured upstream or fork target, then o
 Confirm with `u` or Enter, or cancel with Escape.
 The apply path rechecks every mutable assumption and can only perform the same exact strict fast-forward or anchored equivalent-diverged advance as `no-mistakes sync`; blocked states never trigger destructive Git recovery.
 When the owning run ended without publishing its pipeline commits, the same box offers `u recover custody` instead: `u` opens a confirmation naming the terminal status, the local head, and the preserved head, and applying routes through the guarded recovery documented in [`no-mistakes axi sync`](/no-mistakes/reference/cli/#no-mistakes-axi-sync).
+When the state instead carries `next_action.code: return_custody_keep_local` - the terminal run's recorded pipeline head can no longer be verified, so there is nothing to recover - the box offers `u settle custody at local head`, and its own separate confirmation names the kept local head and the unverifiable recorded head before applying. Settlement keeps your head where recovery takes the preserved one, so the two never share a confirmation; applying routes through the same `--recover --keep-local` settlement documented in [`no-mistakes axi sync`](/no-mistakes/reference/cli/#no-mistakes-axi-sync).
+When the state instead carries `next_action.code: complete_custody_return` - an earlier custody return applied its Git changes but could not record the custody return - the box offers `u complete custody return`, and its own confirmation says that the record is what is missing rather than repeating the settlement's claim that the recorded head cannot be verified. Applying re-runs the exact recovery the state names, `--recover` or `--recover --keep-local`, because every Git step it repeats is idempotent once applied; a command shape the TUI does not recognize offers no key at all rather than guessing which head to keep.
 
 ### Footer
 
@@ -193,7 +195,7 @@ When the instruction editor is open, press `Ctrl+s` or `Ctrl+enter` to save, or
 | `?` | Toggle help overlay |
 | `y` | Toggle yolo mode, which auto-resolves paused steps |
 | `r` | Retry a failed fix-review state or diff load; otherwise start a rerun after a failed or cancelled run |
-| `u` | Refresh and confirm local branch synchronization, or confirm custody recovery, when offered |
+| `u` | Refresh and confirm local branch synchronization, or confirm custody recovery, custody settlement at the local head, or completion of an unrecorded custody return, when offered |
 | `q` | Detach from TUI (or quit if run is done) |
 
 In diff view, `n`/`p` jumps the viewport to the file and line of the next/previous finding.

internal/branchsync/claims.go

@@ -0,0 +1,73 @@
+package branchsync
+
+import "strings"
+
+// SettlementGateMoveQualifier is the condition under which the keep-local
+// custody return actually moves the gate branch. Every path that returns
+// before recoverKeepLocal's swap leaves the gate untouched: the equal/ahead
+// branch stamps custody directly, recoverSettleInconsistent returns early when
+// the gate branch is PROVEN ABSENT or no gate is configured, and
+// recoverKeepLocal skips its whole block when the gate already names the kept
+// head. A record whose gate branch was deleted is admitted by the
+// advertisement predicates on purpose, so a surface promising the settlement
+// points the gate branch anywhere is telling that operator something false.
+const SettlementGateMoveQualifier = "still names a different head"
+
+// settlementGateMovePromises are the ways a surface states that promise. The
+// list lives beside the code whose behavior makes the promise conditional, not
+// beside any one surface, because the drift this guards against was never
+// confined to a single file: a correction applied to the four cobra help
+// strings left the identical claim standing on the structured branch_sync
+// error, the TUI confirmation, the agent guidance, the skill and the agents
+// guide.
+var settlementGateMovePromises = []string{
+	"points the gate branch at",
+	"point the gate branch at",
+	"points that branch at",
+	"point that branch at",
+	"points the gate branch to",
+	"moves the gate branch to",
+	"move the gate branch to",
+	"moving the gate branch to",
+	"moving the local gate branch to",
+	"moving that branch to",
+	"compare-and-swaps onto the kept head",
+	"the gate follows the kept head",
+	"points it at the kept head",
+}
+
+// UnqualifiedGateMovePromise returns the first sentence of text that promises
+// the keep-local custody return moves the gate branch onto the kept head
+// without conditioning it on SettlementGateMoveQualifier, or "" when the
+// invariant holds. Sentences are the unit because the qualifier has to travel
+// with the promise an operator reads, not merely appear somewhere in the same
+// document.
+func UnqualifiedGateMovePromise(text string) string {
+	for _, sentence := range claimSentences(text) {
+		promised := false
+		for _, promise := range settlementGateMovePromises {
+			if strings.Contains(sentence, promise) {
+				promised = true
+				break
+			}
+		}
+		if !promised || strings.Contains(sentence, SettlementGateMoveQualifier) {
+			continue
+		}
+		return sentence
+	}
+	return ""
+}
+
+// claimSentences normalizes whitespace before splitting so a claim stays one
+// sentence across hard-wrapped help text, TUI box lines, and Go string
+// concatenation.
+func claimSentences(text string) []string {
+	var out []string
+	for _, part := range strings.Split(strings.Join(strings.Fields(text), " "), ". ") {
+		if trimmed := strings.TrimSpace(part); trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}