@feigi/fleet-ctl 3.131.2 → 3.132.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.131.2",
3
+ "version": "3.132.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -305,7 +305,11 @@ else
305
305
  # `git push --force-with-lease -u origin HEAD` (skills/next-ticket/SKILL.md
306
306
  # step 7; its no-lease fallback carries `-u` too), or else when the controller
307
307
  # settles the implementer's report, which writes it. Only then can the branch
308
- # be `[gone]`. Until then reap.sh reports it kept.
308
+ # be `[gone]`. Until then reap.sh weighs it as a branch with no upstream, and
309
+ # a fresh claim stays kept: no merged PR has its head branch — or, when a
310
+ # merged PR reused its name, its tip is already on the base and equals no
311
+ # head that PR recorded. Where there is no GitHub repository to ask, it is
312
+ # never selected at all.
309
313
  #
310
314
  # `--no-track` is also why no branch delete uses `-d`: `-d` measures an
311
315
  # upstream-less branch against local HEAD, refusing a pristine claim behind
@@ -4,7 +4,7 @@
4
4
  # Until this script nothing did — the fleet leaned on the repo setting "Automatically
5
5
  # delete head branches", which nothing here enforced or checked, so a repo with
6
6
  # it off accumulated every merged branch, and reap.sh (which reaps only a local
7
- # branch whose upstream is `[gone]`) never saw one to reap.
7
+ # branch whose remote branch is gone) never saw one to reap.
8
8
  #
9
9
  # REMOTE ONLY, on purpose — never `gh pr merge --delete-branch`. That flag's
10
10
  # post-merge LOCAL cleanup dies with `fatal: 'main' is already used by worktree
@@ -49,7 +49,7 @@
49
49
  // not on origin/main, and releases; any other answer, or a detail that
50
50
  // opens with no sha, is a NEED and N is left untouched, claim and all.
51
51
  // The PR a `covered` detail names is never written to.
52
- // A `PR#M` outcome also sets the claim branch's upstream when it has none: `reap.sh` keeps a branch with no upstream, and only an upstream's `[gone]` state makes it reapable. It writes `branch.<b>.remote` and `branch.<b>.merge` only while the merge key is unset, and prints `NEED upstream <b> — <why>` when a write fails.
52
+ // A `PR#M` outcome also sets the claim branch's upstream when it has none: `reap.sh` selects a branch with no upstream only when origin has no branch of its name and its merged PR recorded its tip, while an upstream's `[gone]` state also lets `git cherry`'s proof make it reapable. It writes `branch.<b>.remote` and `branch.<b>.merge` only while the merge key is unset, and prints `NEED upstream <b> — <why>` when a write fails.
53
53
  // A `blocked` outcome takes no action on the ticket beyond the settle: no label, comment, release or upstream, so the ticket keeps `in-progress`. It runs the Recipe read, below.
54
54
  // fix-report <fix-pr-M[-x]>
55
55
  // `settle --from-report`, which records the filings and rulings the
package/scripts/reap.sh CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/bin/sh
2
- # Delete local branches whose upstream is gone, and their worktrees. A branch with no upstream is reported as kept and never deleted.
2
+ # Delete the local branches a merged PR accounts for, and their worktrees: a branch whose upstream is gone, or one with no upstream whose remote branch is gone and whose tip its merged PR recorded.
3
3
  #
4
4
  # Dry-run by default; --apply mutates. Every precondition is recomputed inside
5
5
  # this invocation, because a branch list from an earlier call is already false:
@@ -660,7 +660,8 @@ wt_reg_state() {
660
660
  # with no worktree is exactly as unclearable as the tampered one. Both run on
661
661
  # the listing each branch's own lookup reads — re-read per branch, as the
662
662
  # comment at the lookup below records — so a standing fault keeps every [gone]
663
- # branch in the pass, and a transient one keeps only the branches whose
663
+ # branch, and every selected one with no upstream, in the pass, and a
664
+ # transient one keeps only the branches whose
664
665
  # listing it touched (a transient-fault fixture pins that granularity for the
665
666
  # listing failure; this guard follows it rather than latching).
666
667
  null_head_why() {
@@ -701,11 +702,13 @@ null_head_why() {
701
702
  # stranded tips (every branch has a `!` pair, context drift again) and which,
702
703
  # if it accepted `!`, would also reap a local amend that was never pushed.
703
704
  #
704
- # It is additive. It runs only for a branch `git cherry` already keeps, after
705
- # that verdict, and only ever turns that keep into a reap: the cherry proof,
706
- # the worktree guards, the holder re-check, the compare-and-swap on the tip
707
- # read once and `wt_recheck_delete` are all unchanged, and the tie is computed
708
- # on that same frozen tip. There is no name filter.
705
+ # It is additive. For a branch with an upstream it runs only for one `git
706
+ # cherry` already keeps, after that verdict, and only ever turns that keep
707
+ # into a reap. For a branch with no upstream whose remote branch is gone it is
708
+ # the selection itself, and `git cherry` is not consulted. Either way the
709
+ # worktree guards, the holder re-check, the compare-and-swap on the tip read
710
+ # once and `wt_recheck_delete` are all unchanged, and the tie is computed on
711
+ # that same frozen tip. There is no name filter.
709
712
  #
710
713
  # One lookup per branch, by head name, MERGED PRs only, and a KEEP with its
711
714
  # reason unless ALL of: exactly one PR matches (a reused name can match
@@ -715,12 +718,15 @@ null_head_why() {
715
718
  # here and an ancestor of $base_rev — the ancestry is asked of git, not
716
719
  # trusted from the API; and the tip equals one of the PR's recorded heads or
717
720
  # is an ancestor of one present here. A squash merge's head is not on $base,
718
- # so it stays kept.
721
+ # so it stays kept. A tip already on $base ties by equality only: ancestry
722
+ # counts only for a tip with commits of its own (why is at the check, in
723
+ # pr_tie).
719
724
  #
720
725
  # One aliased `gh api graphql` lookup per run, one call per $pr_chunk branches
721
- # and issued the first time a branch needs it, covers every [gone] branch (a
722
- # superset of the ones waiting: which will need it is only known branch by
723
- # branch). Branch names go in as GraphQL VARIABLES, never spliced into the
726
+ # and issued the first time a branch needs it, covers every [gone] branch and
727
+ # every branch with no upstream whose remote branch is gone (a superset of the
728
+ # ones waiting: which will need it is only known branch by branch).
729
+ # Branch names go in as GraphQL VARIABLES, never spliced into the
724
730
  # query text — `"` is legal in a refname.
725
731
  # Output is captured, never piped, and the call runs under a watchdog. Each of
726
732
  # these keeps every affected branch with its own reason and the run carries on:
@@ -731,8 +737,9 @@ null_head_why() {
731
737
  # script's own `--jq` produces, and a timeline with a next page. Nothing is
732
738
  # cached between runs, so an untied branch is asked about again on every pass.
733
739
  #
734
- # It does not apply — and the reason stays the bare `unmerged commits` — where
735
- # the repository has no GitHub identity to ask about: $base is not a
740
+ # It does not apply — and the reason stays the bare `unmerged commits`, or
741
+ # `no upstream — never selected` for a branch with no upstream — where the
742
+ # repository has no GitHub identity to ask about: $base is not a
736
743
  # remote-tracking ref of `origin`, or `remote.origin.url` is not a
737
744
  # `host/owner/repo` URL (a local path, say). That is not a failure of the
738
745
  # proof, there is simply nobody to put the question to. `git config`, never
@@ -784,6 +791,11 @@ pr_identity() {
784
791
  return 0
785
792
  }
786
793
 
794
+ # Settled once, before any branch is looked at, and asked before pr_load runs:
795
+ # a branch with no upstream asks it to tell "nobody to ask" from a lookup to
796
+ # join, and a `+` branch to keep its bare reason without loading.
797
+ if [ -z "$pr_base" ] || ! pr_identity; then pr_off=true; fi
798
+
787
799
  # `gh "$@"`, neither prompting nor outliving <budget> seconds: the bounded-call
788
800
  # shape net_git has for git, over the same kill walk. It lives here and not in
789
801
  # net.sh because this is the one gh call in the fleet that is bounded; net.sh
@@ -807,8 +819,8 @@ gh_bounded() {
807
819
  )
808
820
  }
809
821
 
810
- # One run's lookup. Sets $pr_off (the proof does not apply here), $pr_all_why
811
- # (it could not be read, for every branch) or $pr_rows (the answer).
822
+ # One run's lookup, for every branch in $pr_branches. Sets $pr_all_why (it
823
+ # could not be read, for every branch) or $pr_rows (the answer).
812
824
  #
813
825
  # At most $pr_chunk aliases per call: GitHub refuses the whole query with
814
826
  # `Resource limits for this query exceeded` somewhere between 850 aliases
@@ -819,8 +831,6 @@ gh_bounded() {
819
831
  pr_chunk=500
820
832
  pr_load() {
821
833
  pr_loaded=true
822
- [ -n "$pr_base" ] || { pr_off=true; return 0; }
823
- pr_identity || { pr_off=true; return 0; }
824
834
  if ! command -v gh >/dev/null 2>&1; then
825
835
  pr_all_why="gh is not installed, so GitHub's record of this tip could not be read"
826
836
  return 0
@@ -835,7 +845,7 @@ pr_load() {
835
845
  "."] | join("\u001f")'
836
846
  pl_budget=$(net_budget 60 "${FLEET_NET_TIMEOUT:-}")
837
847
  pl_n=0
838
- for pl_b in $gone_branches; do pl_n=$((pl_n + 1)); done
848
+ for pl_b in $pr_branches; do pl_n=$((pl_n + 1)); done
839
849
  pl_lo=0
840
850
  while [ "$pl_lo" -lt "$pl_n" ]; do
841
851
  pl_hi=$((pl_lo + pr_chunk))
@@ -843,7 +853,7 @@ pr_load() {
843
853
  pl_sel=
844
854
  set -- -f "owner=$pr_owner" -f "name=$pr_name"
845
855
  pl_i=0
846
- for pl_b in $gone_branches; do
856
+ for pl_b in $pr_branches; do
847
857
  if [ "$pl_i" -ge "$pl_lo" ] && [ "$pl_i" -lt "$pl_hi" ]; then
848
858
  pl_decl="$pl_decl,\$h$pl_i:String!"
849
859
  pl_sel="${pl_sel}b$pl_i:pullRequests(headRefName:\$h$pl_i,states:MERGED,first:2){nodes{number baseRefName isCrossRepository headRefOid timelineItems(itemTypes:[HEAD_REF_FORCE_PUSHED_EVENT],first:100){pageInfo{hasNextPage} nodes{... on HeadRefForcePushedEvent{beforeCommit{oid}}}}}} "
@@ -857,7 +867,7 @@ pr_load() {
857
867
  set -- api graphql --hostname "$pr_host" -f "query=$pl_query" "$@" --jq "$pl_jq"
858
868
  pl_to=$pl_hi
859
869
  [ "$pl_to" -le "$pl_n" ] || pl_to=$pl_n
860
- echo "\$ gh api graphql (merged PRs by head branch, [gone] branches $((pl_lo + 1))-$pl_to of $pl_n)" >&2
870
+ echo "\$ gh api graphql (merged PRs by head branch, branches $((pl_lo + 1))-$pl_to of $pl_n)" >&2
861
871
  if probe gh_bounded "$pl_budget" "$@"; then pl_rc=0; else pl_rc=$?; fi
862
872
  pl_o=$gp_out
863
873
  pl_err=$gp_err
@@ -899,7 +909,7 @@ pr_tie() {
899
909
  pt_b=$1
900
910
  pt_tip=$2
901
911
  pt_i=0
902
- for pt_x in $gone_branches; do
912
+ for pt_x in $pr_branches; do
903
913
  [ "$pt_x" != "$pt_b" ] || break
904
914
  pt_i=$((pt_i + 1))
905
915
  done
@@ -949,15 +959,33 @@ EOF
949
959
  fi
950
960
  return 1
951
961
  fi
952
- # The recorded heads: the head the PR ended on, then every force-pushed-over one.
962
+ # The recorded heads: the head the PR ended on, then every force-pushed-over
963
+ # one. Equality first, against all of them — a membership test on the
964
+ # comma-joined list, the tip quoted so it matches only itself.
965
+ pt_heads="$poid,$pbef"
966
+ case ",$pt_heads," in *,"$pt_tip",*) return 0 ;; esac
967
+ # A tip already on $base ties by equality only; ancestry counts only for a
968
+ # tip with commits of its own. A claim is cut from whatever origin/main this
969
+ # clone last fetched, so a fresh claim that reuses a merged PR's branch name
970
+ # on a clone that has not fetched that merge has no commits, and its tip is
971
+ # an ancestor of that PR's heads: ancestry would tie it, and the reap would
972
+ # remove the live member's clean worktree and branch. A tip that `git
973
+ # cherry` kept has a commit no patch on $base matches, so it is never on
974
+ # $base and this never keeps it.
975
+ if git_probe merge-base --is-ancestor "$pt_tip" "$base_rev"; then
976
+ pr_why="the tip is already on the base and equals no head the PR recorded"
977
+ return 1
978
+ elif [ "$gp_rc" -ne 1 ]; then
979
+ pr_why="cannot tell whether the tip is already on $base$(gp_why)"
980
+ return 1
981
+ fi
953
982
  pt_unsure=false
954
983
  pt_unsure_why=
955
- pt_rest="$poid,$pbef"
984
+ pt_rest=$pt_heads
956
985
  while [ -n "$pt_rest" ]; do
957
986
  pt_h=${pt_rest%%,*}
958
987
  case "$pt_rest" in *,*) pt_rest=${pt_rest#*,} ;; *) pt_rest= ;; esac
959
988
  case "$pt_h" in '' | *[!0123456789abcdef]*) continue ;; esac
960
- if [ "$pt_h" = "$pt_tip" ]; then return 0; fi
961
989
  git_probe cat-file -e "$pt_h^{commit}" || continue
962
990
  if git_probe merge-base --is-ancestor "$pt_tip" "$pt_h"; then return 0; else pt_rc=$?; fi
963
991
  if [ "$pt_rc" -ne 1 ]; then pt_unsure=true; pt_unsure_why=$(gp_why); fi
@@ -1041,12 +1069,64 @@ else
1041
1069
  no_upstream=""
1042
1070
  fi
1043
1071
  fi
1044
- # A branch with no upstream has no [gone] state to act on. It is reported and
1045
- # never selected for deletion, and no other guard runs on it.
1072
+ # A branch with no upstream has no [gone] state to act on, so it is selected on
1073
+ # other evidence, and only when all of it holds: origin has no branch of its
1074
+ # name — asked of refs/remotes/origin/<b>, which the `fetch --prune` above has
1075
+ # just brought up to date, so no further network call — and the second merge
1076
+ # proof ties its tip, read once in the loop below, to a head its merged PR
1077
+ # recorded. Under a fetch refspec that does not map origin's branches into
1078
+ # refs/remotes/origin/, the fetch neither writes nor prunes that ref, so it
1079
+ # says nothing about origin: an absent one passes the first check silently,
1080
+ # whatever origin holds, and the tie alone decides — a branch origin still
1081
+ # holds is then deleted locally only when the tie accounts for its tip, so
1082
+ # nothing on it is local-only. `git cherry` is not consulted for it, neither to
1083
+ # authorize nor to veto, and there is no name filter. Where there is no GitHub
1084
+ # repository to ask, it is never selected. Everything after the selection —
1085
+ # the worktree guards, the holder re-check, the compare-and-swap on the tip and
1086
+ # `wt_recheck_delete` — runs as it does for a [gone] branch; a branch
1087
+ # `wt_recheck_delete` restores still has no upstream, and is weighed again next
1088
+ # pass.
1089
+ nu_branches=
1046
1090
  for b in $no_upstream; do
1047
- keep "$b" "no upstream — never selected"
1091
+ if [ "$pr_off" = true ]; then
1092
+ keep "$b" "no upstream — never selected"
1093
+ elif git_probe show-ref --verify --quiet "refs/remotes/origin/$b"; then
1094
+ keep "$b" "no upstream — origin/$b still exists"
1095
+ elif [ "$gp_rc" -ne 1 ]; then
1096
+ keep "$b" "no upstream — cannot tell whether origin/$b exists$(gp_why)"
1097
+ else
1098
+ nu_branches=${nu_branches:+$nu_branches
1099
+ }$b
1100
+ fi
1048
1101
  done
1049
- for b in $gone_branches; do
1102
+ # One lookup asks about both kinds; pr_tie finds a branch by its place in it.
1103
+ pr_branches=${gone_branches:+$gone_branches
1104
+ }$nu_branches
1105
+ # Returns 1 when no key of branch $1's section is set in the repository's own
1106
+ # config, the one `--remove-section` edits; 0 when one is, or when that config
1107
+ # cannot be read. `--name-only` prints `branch.<name>.<key>`, and a key holds
1108
+ # no `.`, so dropping the last field leaves the section and subsection whole,
1109
+ # whatever `.` the name holds.
1110
+ branch_keys_left() {
1111
+ if git_probe config --local --name-only --get-regexp '^branch\.'; then :
1112
+ elif [ "$gp_rc" -eq 1 ]; then return 1
1113
+ else return 0
1114
+ fi
1115
+ while IFS= read -r bk_k; do
1116
+ [ "${bk_k%.*}" != "branch.$1" ] || return 0
1117
+ done <<EOF
1118
+ $gp_out
1119
+ EOF
1120
+ return 1
1121
+ }
1122
+ # The sweep takes the [gone] branches first: the first $nu_from of it have an
1123
+ # upstream, and every one after has none.
1124
+ nu_from=0
1125
+ for b in $gone_branches; do nu_from=$((nu_from + 1)); done
1126
+ sweep_i=0
1127
+ for b in $gone_branches $nu_branches; do
1128
+ if [ "$sweep_i" -ge "$nu_from" ]; then nu=true; else nu=false; fi
1129
+ sweep_i=$((sweep_i + 1))
1050
1130
 
1051
1131
  # The tip is read ONCE, here, and everything after it measures that frozen
1052
1132
  # SHA rather than the live ref: the cherry below runs against `$tip`, and
@@ -1067,6 +1147,18 @@ for b in $gone_branches; do
1067
1147
  fi
1068
1148
  tip=$gp_out
1069
1149
 
1150
+ if [ "$nu" = true ]; then
1151
+ # No upstream: the second proof, on this `$tip`, is the selection itself
1152
+ # (both rules are above the loop), and `git cherry` is not run.
1153
+ [ "$pr_loaded" = true ] || pr_load
1154
+ if [ -n "$pr_all_why" ]; then
1155
+ keep "$b" "no upstream — $pr_all_why"
1156
+ continue
1157
+ elif ! pr_tie "$b" "$tip"; then
1158
+ keep "$b" "no upstream — $pr_why"
1159
+ continue
1160
+ fi
1161
+
1070
1162
  # git cherry against origin/main, not a local main: a local main never
1071
1163
  # fast-forwarded reads every merged branch as unmerged. A + line is a commit
1072
1164
  # with no patch-equivalent upstream: usually one that exists nowhere else, but
@@ -1109,10 +1201,9 @@ for b in $gone_branches; do
1109
1201
  # the only merge check bounds what ELSE could catch an unmerged branch, not
1110
1202
  # whether this check itself can be wrong — which is why BOTH revs it
1111
1203
  # consumes are qualified.
1112
- if ! cherry=$(git cherry "$base_rev" "$tip" 2>&1); then
1204
+ elif ! cherry=$(git cherry "$base_rev" "$tip" 2>&1); then
1113
1205
  keep "$b" "cherry probe failed — cannot tell if merged: $(printf '%s' "$cherry" | tr '\n' ' ')"
1114
1206
  continue
1115
- fi
1116
1207
  # A `+` only at line start is a commit. $cherry holds stderr too — 2>&1 above,
1117
1208
  # so the failure reason can carry git's own words — and an unanchored match
1118
1209
  # reads a `+` anywhere in a diagnostic as a commit line, keeping a branch that
@@ -1129,7 +1220,7 @@ for b in $gone_branches; do
1129
1220
  # questions; the answers are ruled on here, in the order that makes the
1130
1221
  # unanswerable case fail CLOSED like every other could-not-check in this
1131
1222
  # file: scan first, verdict second.
1132
- if ! grep_probe "$cherry" '^+'; then
1223
+ elif ! grep_probe "$cherry" '^+'; then
1133
1224
  keep "$b" "cherry scan failed — cannot tell if merged$(gp_why "$gq_err")"
1134
1225
  continue
1135
1226
  elif [ "$gq_rc" -eq 0 ]; then
@@ -1138,11 +1229,12 @@ for b in $gone_branches; do
1138
1229
  # after this block — the worktree guards, the holder re-check, the
1139
1230
  # compare-and-swap on `$tip` — runs exactly as it does for a branch the
1140
1231
  # cherry cleared.
1141
- [ "$pr_loaded" = true ] || pr_load
1142
1232
  if [ "$pr_off" = true ]; then
1143
1233
  keep "$b" "unmerged commits"
1144
1234
  continue
1145
- elif [ -n "$pr_all_why" ]; then
1235
+ fi
1236
+ [ "$pr_loaded" = true ] || pr_load
1237
+ if [ -n "$pr_all_why" ]; then
1146
1238
  keep "$b" "unmerged commits — $pr_all_why"
1147
1239
  continue
1148
1240
  elif ! pr_tie "$b" "$tip"; then
@@ -1165,8 +1257,9 @@ for b in $gone_branches; do
1165
1257
  # check at the delete re-reads the listing and keeps on a failed read too, but
1166
1258
  # it answers one question — does a worktree hold this branch — and every guard
1167
1259
  # under `[ -n "$wt" ]` asks others, so this lookup still fails closed on its
1168
- # own. Keeping it strands every [gone] branch in this pass on one repo-level
1169
- # failure, since the listing is re-read per branch (header: every
1260
+ # own. Keeping it strands every [gone] branch, and every selected one with no
1261
+ # upstream, in this pass on one repo-level failure, since the listing is
1262
+ # re-read per branch (header: every
1170
1263
  # precondition is recomputed); reap runs after every merge pass, so each waits
1171
1264
  # one pass with the cause named. A listing that READ is not yet one that can
1172
1265
  # be trusted — see the registry cross-check above — so a disagreeing registry
@@ -1186,13 +1279,13 @@ for b in $gone_branches; do
1186
1279
  keep "$b" "worktree lookup failed — cannot tell whether $b has a worktree; kept until a pass that can read the registry: $wt_why"
1187
1280
  ;;
1188
1281
  *)
1189
- keep "$b" "worktree registry inconsistent — $wt_why; every [gone] branch is kept until a pass that reads a consistent registry"
1282
+ keep "$b" "worktree registry inconsistent — $wt_why; every [gone] branch, and every selected one with no upstream, is kept until a pass that reads a consistent registry"
1190
1283
  ;;
1191
1284
  esac
1192
1285
  continue
1193
1286
  fi
1194
1287
  if ! null_head_why; then
1195
- keep "$b" "worktree registry inconsistent — $reg_why; every [gone] branch is kept until a pass that reads a consistent registry"
1288
+ keep "$b" "worktree registry inconsistent — $reg_why; every [gone] branch, and every selected one with no upstream, is kept until a pass that reads a consistent registry"
1196
1289
  continue
1197
1290
  fi
1198
1291
  if ! wt_find_branch "$b"; then
@@ -1537,7 +1630,8 @@ for b in $gone_branches; do
1537
1630
  # predict `-D`'s": `-D`'s blind spot here was only ever this
1538
1631
  # branch's own paired worktree. A registry read that fails closed for an
1539
1632
  # UNRELATED worktree elsewhere in the listing (reaping.md) keeps every
1540
- # `[gone]` branch in the pass, a repo-wide case `-D` had no equivalent of
1633
+ # `[gone]` branch, and every selected one with no upstream, in the pass, a
1634
+ # repo-wide case `-D` had no equivalent of
1541
1635
  # — it needed no registry answer at all and failed OPEN on one it could
1542
1636
  # not read. The dry run — printing `would reap` unconditionally
1543
1637
  # here — cannot predict any of those keeps either.
@@ -1605,7 +1699,13 @@ for b in $gone_branches; do
1605
1699
  # already deleted, so a failure here is never a keep — but it is not
1606
1700
  # stderr-only either: an unattended caller reading only stdout JSON must
1607
1701
  # still learn the stale upstream was left, so it lands in `warnings` too.
1608
- if ! err=$(git config --remove-section "branch.$b" 2>&1); then
1702
+ #
1703
+ # A branch with no upstream usually has no section at all, and removing
1704
+ # one that is not there fails; a failure that leaves no key of the branch
1705
+ # set left nothing behind, so there is nothing to report.
1706
+ if err=$(git config --remove-section "branch.$b" 2>&1); then :
1707
+ elif [ "$nu" = true ] && ! branch_keys_left "$b"; then :
1708
+ else
1609
1709
  errflat=$(printf '%s' "$err" | tr '\n' ' ')
1610
1710
  printf ' note: %s deleted, but its branch config section was left: %s\n' "$b" "$errflat" >&2
1611
1711
  warnings="${warnings}{\"branch\":$(jfield "$b"),\"note\":$(jfield "branch config section was left: $errflat")},"
@@ -22,18 +22,18 @@ Skill is maintainer's to fix. Do not patch it; do reap yourself.
22
22
  Every precondition recomputed **inside** same command as delete:
23
23
 
24
24
  - **`for-each-ref`, not `git branch | grep`.** `%(upstream:track)` emits exactly `[gone]` as own field. Nothing to pattern-match, no `-v`/`-vv` trap.
25
- - **A branch with no upstream is reported `kept`, never selected.** `%(upstream)` is empty for it, so `%(upstream:track)` has no `[gone]` to match. The sweep reports it with reason `no upstream — never selected` and runs no other guard on it. Its upstream arrives with the first `-u` push, or when the controller settles the implementer's report.
25
+ - **A branch with no upstream is selected only when origin has no branch of its name and its merged PR recorded its tip.** `%(upstream)` is empty for it, so `%(upstream:track)` has no `[gone]` to match. It is selected when `refs/remotes/origin/<b>` is absent after the sweep's own `fetch --prune`, and the second proof below ties its tip, read once, to a head its merged PR recorded; `git cherry` neither authorizes nor vetoes it, and there is no name filter. A tip already on `origin/main` ties only by **equality** with a recorded head, never by ancestry: a claim is cut from whatever `origin/main` the clone last fetched, so a fresh claim that reuses a merged PR's branch name on a clone that has not fetched that merge has no commits of its own and a tip that is an ancestor of that PR's heads — ancestry would tie it, and the reap would remove the live member's clean worktree and branch. Every keep reads `no upstream — <cause>`; where there is no GitHub repository to ask (`BASE_REF` is not an `origin` ref, or `origin` is not a `host/owner/repo` URL) it is never selected and the reason stays `no upstream — never selected`. Once selected, the worktree guards, the holder check and the compare-and-swap below run on it as on a `[gone]` branch. Its upstream arrives with the first `-u` push, or when the controller settles the implementer's report.
26
26
  - **Recompute per branch, in this command.** Branch list from earlier tool call already false: one observed run listed 28 gone branches, two calls later 27 reaped by concurrent session. Benign direction is no-op; dangerous one is worktree that gained work *after* check.
27
27
  - **`git cherry origin/main`, not `git diff main..`.** Against `origin/main` — local `main` you never fast-forwarded reads every merged branch as unmerged. A `+` line is a commit with no patch-equivalent upstream, which is usually a commit that exists nowhere else but not always: a claim the merge bot rebased server-side onto a `main` that had changed its context lines carries a different patch id, so its original tip reads `+` although everything on it merged. That keep is safe but leaky, and the second proof below is what closes it.
28
28
  - **The delete is `git update-ref -d`'s compare-and-swap on a tip read once, authorized by that cherry check and by a fresh check, re-read immediately before the delete, that no worktree holds the branch.** Tip read before the cherry, cherry runs against that SHA, delete refuses unless ref still equals it — commit landing between check and delete is kept with git's own `cannot lock ref`, never force-deleted, as it was under `git branch -D`, the delete this replaced. `--no-deref`, so symref branch deletes the symref, not its target (measured). Branch's config section removed after, as `-D` did — left behind, re-created branch of same name inherits dead upstream and reads `[gone]` at once. `git branch -d` would refuse everything here: upstream gone, so falls back to comparing against `HEAD`, a possibly-behind local `main`. Never delete branch whose cherry output you did not just read.
29
- - **A branch any worktree holds is a KEEP, checked right before the delete.** `update-ref` consults no worktree; `-D` did. So listing is re-read and worktree.sh's `wt_holding` asks: held by a `branch` line, or by detached worktree stopped mid `rebase -i` / mid `bisect` on it (admin dir's `head-name` / `BISECT_START`) — both routes `-D` refused on. Worktree it cannot resolve, or listing that will not re-read, is a KEEP. `--apply` only, like the delete: dry run cannot predict this refusal — not the same limitation `-D`'s dry run had, since an unrelated worktree elsewhere in the listing that this check cannot resolve keeps every `[gone]` branch in the pass (see below), a repo-wide case `-D` never produced.
29
+ - **A branch any worktree holds is a KEEP, checked right before the delete.** `update-ref` consults no worktree; `-D` did. So listing is re-read and worktree.sh's `wt_holding` asks: held by a `branch` line, or by detached worktree stopped mid `rebase -i` / mid `bisect` on it (admin dir's `head-name` / `BISECT_START`) — both routes `-D` refused on. Worktree it cannot resolve, or listing that will not re-read, is a KEEP. `--apply` only, like the delete: dry run cannot predict this refusal — not the same limitation `-D`'s dry run had, since an unrelated worktree elsewhere in the listing that this check cannot resolve keeps every `[gone]` branch, and every selected one with no upstream, in the pass (see below), a repo-wide case `-D` never produced.
30
30
  - **A worktree that checked the branch out while the delete ran is caught after it, and the branch is put back.** git has no lock that stops `git worktree add <p> <b>` between that holder check and the delete, and such an add writes only the new worktree's `HEAD` — the ref does not move, so the compare-and-swap succeeds and leaves the worktree on a branch that no longer exists (measured, git 2.50.1). So worktree.sh's `wt_recheck_delete` re-reads the listing right after the delete — and again, up to 20 times 0.1s apart, while an add in progress is listed `locked initializing` — and when a worktree holds the branch, or the wait runs out, recreates it at the tip with a create-only `git update-ref`. The branch is a KEEP naming the worktree or the entry, and its config section stays. A restore that fails is a KEEP naming the tip, git's error and the command that restores it by hand — or, when something recreated the branch since the delete, the commit it now sits at, left as it is, since the create-only restore never overwrites it. The branch's reflog does not come back.
31
31
  - **A cherry that cannot answer is a KEEP.** Capture git's output; never pipe git itself: `cmd | grep -q` takes grep's exit status, never cmd's, so a `git cherry` that dies (rc 128 — one unreadable loose object is enough) prints nothing, grep exits 1, and a dead probe reads identical to "nothing unmerged" (verified, git 2.50.1). Unanswerable probe authorizes no delete — same fail-closed shape as `worktree remove` below. Read the `+` anchored, too: the capture folds stderr in, so an unanchored match reads a `+` in a diagnostic as a commit. Pinned by a test.
32
32
  - **A branch `git cherry` keeps gets a second proof, from GitHub's record of the PR's heads.** A stranded tip is a head the PR's remote branch once held: a member's `HEAD:<branch>` push from a detached worktree, or the merge bot's server-side rebase, replaced the remote branch and never moved the local ref. GitHub records those heads — the PR's `headRefOid` and the `beforeCommit` of every force-push on it. A tip that **equals** a recorded head, or is an **ancestor** of one this clone has, was pushed and then replaced by its owner's force-push, so nothing on it was ever local-only. Equality or ancestry is enough: no `git range-diff` pairing, which reaped none of the measured tips (every branch has a `!` pair, context drift again) and, if it accepted `!`, would also reap a local amend that was never pushed. The tie is computed on the same tip the delete's compare-and-swap uses, and everything after it — worktree guards, holder re-check, `wt_recheck_delete`, `worktree remove` without `--force` — runs unchanged. There is no name filter.
33
- - **The second proof is a KEEP with a reason unless every check holds.** One lookup by head name, merged PRs only. Exactly one PR matches — none, or several (a reused name), keeps. Its base is the branch `BASE_REF` names. It is not cross-repository. Its `headRefOid` is a commit present locally and an ancestor of `origin/main`, asked of git and never trusted from the API — a squash merge's head is not on `origin/main`, so it stays kept. Its timeline has no next page of force-pushes, since the tie would be read off a partial list. A tip that is none of the recorded heads, or an ancestor of none present locally, is kept.
34
- - **The second proof fails closed, per branch and per cause.** One aliased `gh api graphql` lookup per run covers every `[gone]` branch, at most 500 branches per call (GitHub refused 1000 aliases in one query as over its resource limits, measured), and is issued the first time a branch needs it; a run with no `+` branch never calls `gh`. The host is always the one `origin` names, passed as `--hostname`, so `GH_HOST` cannot redirect it. Branch names go in as GraphQL variables, never spliced into the query. Output is captured, never piped, and the call runs under a bounded timeout. `gh` missing, a non-zero exit with no complete body, a stall past the budget, output that does not parse, and a next page each keep every affected branch with its own reason after `unmerged commits —`, and the run carries on; a non-zero exit that did print a complete body is read, and a branch missing from it keeps with gh's exit status and stderr in its reason. Nothing is cached: an untied branch is asked about again on every pass. Where `origin` has no `host/owner/repo` URL (a local path) or `BASE_REF` is not an `origin` ref there is nobody to ask, and the reason stays the bare `unmerged commits`. An `origin` whose host is an ssh alias (`git@github-work:owner/repo`) or an `insteadOf` shorthand (`gh:owner/repo`) is read as written, so `gh` is asked about a host it cannot reach and every affected branch keeps with `gh failed`. Only the `git fetch` failure still aborts the run.
35
- - **A worktree registry that cannot be read is a KEEP, for every `[gone]` branch in that pass.** The lookup decides whether the dirty, ignored-files and removal checks run at all; an unread registry reads identical to "no worktree", and `-D`, the delete then, needed no answer from the registry to delete a branch that has none — so failing open force-deleted merged branches blind. The holder check before the delete asks only whether a worktree holds the branch, never those other questions, so the lookup still fails closed on its own. The listing is re-read per branch, so one repo-level failure keeps every `[gone]` branch in the pass, each with git's own cause. Reap runs after every merge pass, so the next one retries: nothing is lost, nothing is reaped blind.
36
- - **A registry the listing does not match is a KEEP for the whole pass, not just one branch — if the fault is standing.** Eight real admin-directory faults leave `git worktree list` at rc 0 while the held entry loses its `branch` line (admin `HEAD` garbage, empty, missing or chmod 000) or leaves the listing (`gitdir` missing or chmod 000, admin dir chmod 000, `.git/worktrees` replaced by a file) — and git's own "used by worktree" `-D` refusal read the same admin state, so it deleted the branch a live worktree held (measured, git 2.50.1). The holder check that replaced that refusal reads the same listing and answers "not held" for seven of the eight (measured; "cannot tell" only for `HEAD` missing), so it is no backstop either. So before the lookup is trusted, linked entries listed are counted against entries under `<git-common-dir>/worktrees/` (worktree.sh's `wt_counts`, recount-before-refuse included), and any linked entry with a null `HEAD` and no `branch` line fails it too — the HEAD faults keep the counts equal. A dropped or nameless entry says nothing about which branch it held. The check re-reads the listing per branch, so a standing fault — one still there on every branch's own read — keeps every `[gone]` branch in the pass, the healthy ones included; a transient one, healed before the next branch's read, keeps only the branches whose listing it touched. Either way nothing is reaped blind, and the next pass retries once the registry reads consistent again.
33
+ - **The second proof is a KEEP with a reason unless every check holds.** One lookup by head name, merged PRs only. Exactly one PR matches — none, or several (a reused name), keeps. Its base is the branch `BASE_REF` names. It is not cross-repository. Its `headRefOid` is a commit present locally and an ancestor of `origin/main`, asked of git and never trusted from the API — a squash merge's head is not on `origin/main`, so it stays kept. Its timeline has no next page of force-pushes, since the tie would be read off a partial list. A tip that is none of the recorded heads, or an ancestor of none present locally, is kept. A tip already on `origin/main` that equals none of them is kept too, whatever it is an ancestor of — the reason is in the bullet on a branch with no upstream, above.
34
+ - **The second proof fails closed, per branch and per cause.** One aliased `gh api graphql` lookup per run covers every `[gone]` branch and every branch with no upstream whose remote branch is gone, at most 500 branches per call (GitHub refused 1000 aliases in one query as over its resource limits, measured), and is issued the first time a branch needs it; a run with neither a `+` branch nor such a branch with no upstream never calls `gh`. The host is always the one `origin` names, passed as `--hostname`, so `GH_HOST` cannot redirect it. Branch names go in as GraphQL variables, never spliced into the query. Output is captured, never piped, and the call runs under a bounded timeout. `gh` missing, a non-zero exit with no complete body, a stall past the budget, output that does not parse, and a next page each keep every affected branch with its own reason after `unmerged commits —` (`no upstream —` for a branch with no upstream), and the run carries on; a non-zero exit that did print a complete body is read, and a branch missing from it keeps with gh's exit status and stderr in its reason. Nothing is cached: an untied branch is asked about again on every pass. Where `origin` has no `host/owner/repo` URL (a local path) or `BASE_REF` is not an `origin` ref there is nobody to ask, and the reason stays the bare `unmerged commits` (`no upstream — never selected` for a branch with no upstream). An `origin` whose host is an ssh alias (`git@github-work:owner/repo`) or an `insteadOf` shorthand (`gh:owner/repo`) is read as written, so `gh` is asked about a host it cannot reach and every affected branch keeps with `gh failed`. Only the `git fetch` failure still aborts the run.
35
+ - **A worktree registry that cannot be read is a KEEP, for every `[gone]` branch, and every selected one with no upstream, in that pass.** The lookup decides whether the dirty, ignored-files and removal checks run at all; an unread registry reads identical to "no worktree", and `-D`, the delete then, needed no answer from the registry to delete a branch that has none — so failing open force-deleted merged branches blind. The holder check before the delete asks only whether a worktree holds the branch, never those other questions, so the lookup still fails closed on its own. The listing is re-read per branch, so one repo-level failure keeps every such branch in the pass, each with git's own cause. Reap runs after every merge pass, so the next one retries: nothing is lost, nothing is reaped blind.
36
+ - **A registry the listing does not match is a KEEP for the whole pass, not just one branch — if the fault is standing.** Eight real admin-directory faults leave `git worktree list` at rc 0 while the held entry loses its `branch` line (admin `HEAD` garbage, empty, missing or chmod 000) or leaves the listing (`gitdir` missing or chmod 000, admin dir chmod 000, `.git/worktrees` replaced by a file) — and git's own "used by worktree" `-D` refusal read the same admin state, so it deleted the branch a live worktree held (measured, git 2.50.1). The holder check that replaced that refusal reads the same listing and answers "not held" for seven of the eight (measured; "cannot tell" only for `HEAD` missing), so it is no backstop either. So before the lookup is trusted, linked entries listed are counted against entries under `<git-common-dir>/worktrees/` (worktree.sh's `wt_counts`, recount-before-refuse included), and any linked entry with a null `HEAD` and no `branch` line fails it too — the HEAD faults keep the counts equal. A dropped or nameless entry says nothing about which branch it held. The check re-reads the listing per branch, so a standing fault — one still there on every branch's own read — keeps every `[gone]` branch, and every selected one with no upstream, in the pass, the healthy ones included; a transient one, healed before the next branch's read, keeps only the branches whose listing it touched. Either way nothing is reaped blind, and the next pass retries once the registry reads consistent again.
37
37
  - **`worktree remove` without `--force`.** Refuses on modifications *and* untracked files, so double-covers dirty check. Refusal is finding to report, never something to force past.
38
38
 
39
39
  ## Why a second sweep, over worktrees rather than branches