@feigi/fleet-ctl 3.25.0 → 3.27.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.
@@ -135,6 +135,19 @@ net_lib="$(dirname "$0")/net.sh"
135
135
  # shellcheck source=net.sh
136
136
  . "$net_lib" || die "$net_lib failed to load"
137
137
 
138
+ # The worktree readers and the Registration probe. worktree.sh's header holds
139
+ # the sourcing contract and the measurements behind it, and json.sh's holds the
140
+ # `[ -r ]` reasoning all three guards share: exit 1 from this script means
141
+ # `taken`, so a library that merely went missing must refuse before the `.`
142
+ # can kill the shell. Below json.sh, so a lone copy of this script still blames
143
+ # json.sh, the name its missing-library test pins. The listing reader owns its
144
+ # own temp file, so it adds nothing to the EXIT trap below.
145
+ wt_lib="$(dirname "$0")/worktree.sh"
146
+ [ -r "$wt_lib" ] || die "cannot read $wt_lib — refusing to answer without the worktree readers"
147
+ # shellcheck source-path=SCRIPTDIR
148
+ # shellcheck source=worktree.sh
149
+ . "$wt_lib" || die "$wt_lib failed to load"
150
+
138
151
  [ $# -eq 1 ] || die "usage: inflight.sh <issue-number>"
139
152
  n=$1
140
153
  case "$n" in ''|*[!0-9]*|0?*) die "issue must be a number, got '$n'";; esac
@@ -162,14 +175,13 @@ remote=""
162
175
  local_b=""
163
176
  wt=""
164
177
 
165
- # The three temp files, and the ONE EXIT trap that removes them. `sh` keeps a
178
+ # The temp files, and the ONE EXIT trap that removes them. `sh` keeps a
166
179
  # single EXIT trap, so a second `trap … EXIT` further down does not add a
167
180
  # handler — it REPLACES this one, silently leaking whatever the first was going
168
- # to remove. All three are therefore declared here and cleaned here rather
181
+ # to remove. Each is therefore declared here and cleaned here rather
169
182
  # than each probe installing its own. Declared empty, too, so the trap can run
170
183
  # under `set -u` after a `die` that fired before any was created.
171
184
  errfile=""
172
- wtfile=""
173
185
  wdfile=""
174
186
  # `${…:+}` so a file that was never created contributes no argument at all
175
187
  # rather than an empty one, and `rm -f` with no operands is specified to exit 0.
@@ -186,8 +198,8 @@ wdfile=""
186
198
  # in one. It returns 0 just as `echo` did, so the status argument above is
187
199
  # unchanged. Format string double-quoted because the trap body is already
188
200
  # single-quoted.
189
- trap 'rm -f ${errfile:+"$errfile"} ${wtfile:+"$wtfile"} ${wdfile:+"$wdfile"} ||
190
- printf "%s: could not remove %s %s %s\n" "$NAME" "$errfile" "$wtfile" "$wdfile" >&2' EXIT
201
+ trap 'rm -f ${errfile:+"$errfile"} ${wdfile:+"$wdfile"} ||
202
+ printf "%s: could not remove %s %s\n" "$NAME" "$errfile" "$wdfile" >&2' EXIT
191
203
 
192
204
  # Probe 1 — a PR that is actually ABOUT this ticket.
193
205
  #
@@ -530,9 +542,10 @@ probe_remote || :
530
542
  # admin dir, and both lookups below report nothing, at rc 0, for a ticket that
531
543
  # has a live branch or worktree — the same wrong "free" this script exists to rule out,
532
544
  # one probe down. Establish each storage was readable before trusting an empty
533
- # result from it — the same rule release-ticket.sh's `-r`/`-x` guard on
534
- # `$wtroot` already applies to its own worktree-registry read — absence
535
- # must be established, never inferred.
545
+ # result from it — the same rule worktree.sh's `wt_count_registry` applies with
546
+ # its `-d`/`-r`/`-x` guard on `$wt_root`, the worktree registry this probe's
547
+ # worktree half reads through `wt_counts` — absence must be established, never
548
+ # inferred.
536
549
  #
537
550
  # Ceiling, left open on purpose: a single loose ref git skips as corrupt
538
551
  # (`warning: ignoring broken ref refs/heads/x`, still rc 0) passes a
@@ -671,281 +684,46 @@ if [ -n "$local_b" ]; then
671
684
  add_hit "local"
672
685
  fi
673
686
 
674
- # The worktree registry's check is a different shape from the one above, on
675
- # purpose. It began as release-ticket.sh's own fix for this defect rather
676
- # than a second invented convention — but the two copies diverged from there
677
- # and have converged on most of that ground, but not all of it — see the
678
- # recount below for what still differs. Three of the four items that
679
- # landed here first — the stray-directory skip, the awk counter and the
680
- # direction split — were ported to that copy; the recount was the last
681
- # of the four to follow. That copy's skip reading only `ls`'s output,
682
- # not its exit STATUS, was a further divergence, since closed: both
683
- # copies' skip now reads the exit status.
684
- #
685
- # Porting the recount did not converge the two copies on it at once, though:
686
- # this script's recount re-took `registered` alone (`count_registry`), while
687
- # release-ticket.sh's copy of the SAME recount re-took `registered` AND
688
- # `linked` together, because re-taking `registered` by itself
689
- # leaves `linked` pinned to the first listing and can misname a benign
690
- # concurrent-worktree race as a fault. That divergence is closed here: both
691
- # copies now re-take the pair, this one through the `count_linked` below. The
692
- # mechanism under it is still each script's own — that copy reads the listing
693
- # through worktree.sh's `wt_listing`, this one through the single EXIT trap's
694
- # `$wtfile` — a difference in plumbing, same as before. What is no longer true
695
- # is that the recount ITSELF is: release-ticket.sh's copy is bounded at up
696
- # to two recount passes (`recount_tries`) to close a residual third-mutation
697
- # race window that this script's own still-single-pass recount does not
698
- # close.
699
- #
700
- # A directory-level read+execute test alone is not enough
701
- # here: naming a registry entry needs read+execute on the PARENT only, so a
702
- # `gitdir` file chmod'd 000 INSIDE one entry passes every test on the entry
703
- # itself while `worktree list --porcelain` still drops it, at rc 0
704
- # (measured). Count registry entries on disk against what git reported instead —
705
- # that catches a silent drop whichever file inside the entry was unreadable.
706
- wtroot="$common/worktrees"
707
- # A function because the count is taken twice — see the recount below. Absent
708
- # entirely is fine and answers nothing here: a repo that never had a linked
709
- # worktree has no registry directory at all, and that emptiness is real, not a
710
- # permission problem.
711
- count_registry() {
712
- registered=0
713
- [ -e "$wtroot" ] || return 0
714
- [ -r "$wtroot" ] && [ -x "$wtroot" ] ||
715
- { add_unknown "local" "worktree registry $wtroot could not be read — whether #$n has a worktree is unknown"; return 1; }
716
- for entry in "$wtroot"/*; do
717
- [ -d "$entry" ] || continue
718
- # Skip only an EMPTY directory. That is an operator's stray `mkdir`, which
719
- # git ignores — and counting one fails this probe closed forever, on every
720
- # ticket in the repo, over something git is right to ignore (measured: git
721
- # lists 2, a bare `-d` count said 3). A stray FILE was already skipped by
722
- # the `-d` above; a stray directory was not.
723
- #
724
- # Emptiness, NOT the absence of a `gitdir` file: git drops an entry whose
725
- # `gitdir` was deleted, so keying the skip on that file over-skips into the
726
- # wrong "free" spelled out below (measured: rc 0, `taken=false`). A corrupt
727
- # entry still holds git's own files — commondir, HEAD, index, logs, refs —
728
- # so emptiness separates it from a stray and the missing `gitdir` does not.
729
- #
730
- # `ls`'s STATUS, not just its output: an entry we could not LIST is not an
731
- # empty one, and `2>/dev/null` hides the difference. An entry chmod'd 000
732
- # (unsearchable) OR 0111 (searchable, so an `-x` test passes it, but not
733
- # readable) fails EACCES and prints exactly what a stray `mkdir` prints.
734
- # Over-skip on the missing `gitdir` or on the output alone, and git has
735
- # dropped the entry too, so the counts AGREE (measured: 2 listed, then 1,
736
- # and an output-only skip counts 0 to match), no mismatch fires, and the
737
- # probe answers `taken=false` for a ticket whose checkout is still on disk.
738
- # Could not read it, so we cannot tell → count it and let the mismatch
739
- # below fire.
740
- if contents=$(ls -A "$entry" 2>/dev/null) && [ -z "$contents" ]; then continue; fi
741
- registered=$((registered + 1))
742
- done
743
- return 0
744
- }
745
- count_registry || return 1
687
+ # The worktree half reads git's listing, and an rc-0 listing can be silently
688
+ # incomplete: when the registry under `<git-common-dir>/worktrees` — or any
689
+ # file git needs inside one of its entries — cannot be read, git drops the
690
+ # entry and still exits 0, and a dropped entry here is a live checkout read as
691
+ # FREE, the one answer this script must never invent. worktree.sh's
692
+ # `wt_counts` establishes the listing is complete before its absences are
693
+ # trusted — the registry entries on disk counted against the linked worktrees
694
+ # git listed, recounted before refusing, the direction of a standing
695
+ # disagreement named — and leaves that listing in `$wt_list` for the filter
696
+ # below. Every refusal is this probe's unknown, never a `die`: probes 1 and 2
697
+ # may already have established a verdict. A listing git could not produce at
698
+ # all is named as one, with git's own cause.
699
+ if wt_counts; then :; else
700
+ case $? in
701
+ 2) add_unknown "local" "could not read the worktree list for #$n: $wt_why" ;;
702
+ *) add_unknown "local" "$wt_why" ;;
703
+ esac
704
+ return 1
705
+ fi
746
706
 
747
707
  # Match on the worktree's basename, not its full path — matching the whole
748
708
  # absolute path would false-hit on any checkout whose directory happens to
749
709
  # contain the ticket number as an earlier path segment (e.g. a home dir or
750
- # a sibling directory named with digits), matching every ticket.
751
- #
752
- # `--porcelain -z`, into a temp file rather than a command substitution. The
753
- # plain porcelain terminates every attribute with a newline, and a worktree
754
- # path may legally contain one (APFS and ext4 both allow it), so one record
755
- # splits into two. Measured on the plain form: `…/wt/fix-66-a<LF>b`
756
- # reported `worktree` truncated at `…/fix-66-a`, a path not on disk; and
757
- # `…/wt/plain<LF>fix-33-slug` left the number on the orphaned second line,
758
- # where the `^worktree ` filter never looked, so that ticket came back `taken=false` at
759
- # exit 0 with its checkout live — the one answer this script must never invent.
760
- # A temp file because `-z`'s separator is NUL and no shell variable can hold
761
- # one, and because it keeps the lookup's status readable on its own, apart from
762
- # the reader's below: a pipeline would report only the last stage's, so a `git`
763
- # that could not run at all would read as an empty listing, a wrong "free".
764
- if ! wtfile=$(mktemp); then
765
- # Probe-local for the reason probe 1's is: `die` here would abandon a verdict
766
- # probes 1 and 2 may already have established.
767
- add_unknown "local" "could not create a temporary file to hold the worktree list, so whether #$n has a worktree is unknown"
768
- return 1
769
- fi
770
- # A function, not inline, because the recount below needs this whole pair —
771
- # git's own read of the listing and the count derived from it — re-taken
772
- # TOGETHER rather than one of them re-assigned on its own. `worktrees` and
773
- # `linked` are this function's OUTPUT, exactly as `registered` is
774
- # `count_registry`'s — `listed` is scratch the count derives `linked` from and
775
- # the `-ge 1` guard below checks, never read outside this function, matching
776
- # release-ticket.sh's own `count_linked`, whose comment (line 383) likewise
777
- # names only `linked` and `wt_list`/`wt_err`. Mirrors that same extraction over
778
- # the same pair for the same recount.
779
- #
780
- # The `mktemp` stays ABOVE this function rather than moving inside it, where
781
- # release-ticket.sh's `wt_listing` creates and removes one of its own: the temp
782
- # files here are the ONE EXIT trap's at the top of this file, and it holds a
783
- # single slot per file, so a second `mktemp` in here would overwrite `$wtfile`
784
- # and leak the first path with nothing said. The re-take truncates the same
785
- # inode instead — the reason probe 1's second `2>"$errfile"` does, spelled out
786
- # there.
787
- #
788
- # `return 1` inside returns from THIS function now, not from `probe_local`, so
789
- # every call site carries its own `|| return 1` exactly as `count_registry`'s
790
- # do. Without it a listing that could not be read would be recorded by
791
- # `add_unknown` and then walked straight past, and the probe would answer
792
- # `taken=false` off a listing it never had — the one answer this script must
793
- # never invent.
794
- count_linked() {
795
- # Two operands, one status: the redirect is new here (the base ran this as a
796
- # command substitution, which had nothing to write to), so a `git` that could
797
- # not run and a `$wtfile` that could not be written are indistinguishable at
798
- # this `if`. The message names both rather than blaming git for a write it never
799
- # reached — the shell prints its own "Permission denied" naming the path when it
800
- # is the redirect, which is the half a reader can tell apart.
801
- if ! git worktree list --porcelain -z >"$wtfile"; then
802
- add_unknown "local" "git worktree list failed, or its output could not be written to $wtfile, so whether #$n has a worktree is unknown"
803
- return 1
804
- fi
805
- # NOT `awk -v RS='\0'`. That is a gawk/BWK extension, and the awk this script
806
- # actually runs on macOS — /usr/bin/awk, BWK awk 20200816 — does not merely
807
- # ignore it: it stops dead at the first NUL and reports ONE record for a
808
- # listing of any length. Measured, all three spellings, `-v RS='\0'`,
809
- # `-v RS='\000'` and `BEGIN{RS="\0"}`, every one of them `count=1`. No awk
810
- # program here can hold a NUL byte, so the swap has to happen before awk sees
811
- # the stream at all.
812
- #
813
- # One `tr` pass does it: NUL becomes the newline awk already splits on, and a
814
- # newline inside a path becomes \001. `tr` translates simultaneously from one
815
- # table, so the two mappings cannot feed each other the way two piped stages
816
- # would. Both awks below then read the listing unchanged.
817
- #
818
- # Ceiling, deliberate: jstr renders that \001 as a space rather than as `\n`,
819
- # so a path containing a newline is reported WHOLE but with the newline
820
- # neutralised — the treatment every C0 byte WITHOUT a JSON short form gets. Not
821
- # the tab in `…/fix-88-a<TAB>b`: \011 is one of the five RFC 8259 gives a short
822
- # form, jstr's `sed` escapes it to `\t` before this `tr` stage runs at all, and
823
- # jrewritten's delete set skips it — so a tab round-trips byte-identical and
824
- # reports `worktreeRewritten: false`, which is what the probe-3 tab case pins.
825
- # Swapping the byte back would restore `\n` here at the cost of corrupting the
826
- # opposite case — a path that really contains \001 — for a diagnostic field
827
- # whose verdict is already correct either way. One failure mode is better than
828
- # two.
829
- if ! worktrees=$(LC_ALL=C tr '\n\000' '\001\n' <"$wtfile"); then
830
- add_unknown "local" "could not read the worktree list for #$n"
831
- return 1
832
- fi
833
- # The main worktree is always listed first and has no registry entry of its
834
- # own, hence the -1.
835
- #
836
- # awk, not `grep -c … || true`, for exactly the reason probe 2's filter above
837
- # is one awk. `grep -c` exits 1 on zero matches — legitimate, and `set -e`
838
- # would read it as fatal — so a `|| true` has to absorb it, and that same
839
- # `|| true` absorbs a grep that could not RUN AT ALL. Then the count is the
840
- # empty string, `$((listed - 1))` is -1, and the mismatch report below blames
841
- # `git worktree list` for a count no listing can produce. awk needs no such
842
- # case separated out: the program contains no `exit`, so it returns 0 whether
843
- # or not anything matched and every non-zero status is a real failure.
844
- listed=$(printf '%s\n' "$worktrees" | LC_ALL=C awk '/^worktree /{c++} END{print c+0}') ||
845
- { add_unknown "local" "could not count the worktrees git listed for #$n"; return 1; }
846
- # The guard above closes only the route where awk could not RUN. An empty but
847
- # SUCCESSFUL listing reaches the same -1: awk exits 0 printing `0`, the guard
848
- # cannot fire, and the mismatch report below blames `git worktree list` for the
849
- # very count that guard exists to keep out of an operator's face. One comparison
850
- # closes it for every branch below at once, the recount included. `-ge 1`, not
851
- # `-gt 1`: `listed=1` is the main checkout alone, `linked=0`, the ordinary repo
852
- # with no linked worktree — a guard that refused that would make every probe in
853
- # a clean repo unknown. Real `git worktree list --porcelain` always prints the
854
- # main worktree, so reaching this needs a broken or shimmed git; the refusal
855
- # direction was already right, only the number was nonsense.
856
- [ "$listed" -ge 1 ] ||
857
- { add_unknown "local" "git listed no worktrees at all for #$n — not even the main checkout, so the listing cannot be trusted"; return 1; }
858
- linked=$((listed - 1))
859
- }
860
- count_linked || return 1
861
- # Recount before refusing. The two reads happen at different instants, and the
862
- # gap is not theoretical: measured at ~10ms (two independent methods agreeing —
863
- # the fork+exec of git, which is almost the whole cost of `worktree list`, and
864
- # the observed hit rate under churn). A sibling agent's `git worktree add` or
865
- # `remove` landing in it makes the counts disagree with nothing wrong, which in
866
- # THIS fleet is routine rather than exotic: measured 1.99% of probes aborting
867
- # spuriously at λ = 2 mutations/s, 56.6% under saturation.
710
+ # a sibling directory named with digits), matching every ticket. This is a
711
+ # different question from worktree.sh's `wt_find_branch` — which listed path
712
+ # names this ticket, not which path holds a given branch — so it stays here,
713
+ # over the probe's `$wt_list`.
714
+ #
715
+ # Ceiling, deliberate: `wt_listing` swaps a newline inside a path for \001,
716
+ # and jstr renders that \001 as a space rather than as `\n`, so a path
717
+ # containing a newline is reported WHOLE but with the newline neutralised —
718
+ # the treatment every C0 byte WITHOUT a JSON short form gets. Not the tab in
719
+ # `…/fix-88-a<TAB>b`: \011 is one of the five RFC 8259 gives a short form,
720
+ # jstr's `sed` escapes it to `\t`, and jrewritten's delete set skips it — so a
721
+ # tab round-trips byte-identical and reports `worktreeRewritten: false`, which
722
+ # is what the probe-3 tab case pins. Swapping the byte back would restore `\n`
723
+ # here at the cost of corrupting the opposite case — a path that really
724
+ # contains \001 — for a diagnostic field whose verdict is already correct
725
+ # either way. One failure mode is better than two.
868
726
  #
869
- # One recount closes it rather than moving it: a mutation landing between the
870
- # FIRST count and git's listing is already reflected in that listing, so the
871
- # second count agrees with it — the invariant the ORIGINAL pair above relies
872
- # on. Escaping still needs a SECOND mutation inside the recount's own window.
873
- # The two rates measured for recounting at all — 1.99% → 0.00% at
874
- # λ = 2/s, 56.6% → 1.29% saturated — were taken on the registered-only
875
- # recount this replaces, so that 1.29% residual bounds what narrowing the
876
- # window below can still leave rather than describing it; it was not
877
- # re-measured after that change. A real dropped entry is a standing state,
878
- # not a moment, so it survives the recount and still refuses (verified: an
879
- # unreadable `gitdir` still aborts).
880
- #
881
- # BOTH counts, not `registered` alone, which is what that invariant costs.
882
- # Re-taking the registry by itself leaves `linked` pinned to the FIRST
883
- # listing, so a second sibling mutation landing after that listing returned
884
- # but before the recount re-scans the registry moves one count and not the
885
- # other. Reproduced in both directions, and they fail differently. Two
886
- # `git worktree add`s straddling the listing call FLIP the disagreement:
887
- # `linked -gt registered` on the first pair becomes `linked -lt registered`
888
- # on the recount, reported as "git listed 1 worktrees for 2 registry entries
889
- # … the listing is incomplete" — a corruption report for two ordinary adds.
890
- # A remove then an add makes it PERSIST instead: the registry count comes
891
- # back to the same 1 for a different entry while `linked` stays at the 0 it
892
- # read before the add, and the same message fires at 0 against 1. Neither run
893
- # had anything wrong with it.
894
- # Re-taking `registered` and `linked` together, in the same order the pair
895
- # above takes them, hands the RECOUNT pair the invariant too: the window an
896
- # escape needs is the narrow gap these two calls open between themselves, not
897
- # the whole span back to the first listing. Both directions pinned in
898
- # the test suite. Mirrors release-ticket.sh's copy of this recount, which
899
- # is fixed the same way.
900
- #
901
- # The retake pair above is still two reads, not one, and the gap it opens
902
- # between ITSELF — after `count_registry` has already re-scanned but before
903
- # `count_linked` re-lists — is narrower than the window this recount closes,
904
- # not zero. A mutation landing there still escapes: `registered` is re-taken
905
- # first, so an ADD landing in this gap is missed by the registry scan that
906
- # already ran and IS seen by the git listing still to come — `linked -gt
907
- # registered`, "the registry read missed entries git can see" — while a
908
- # REMOVE the same way lands `linked -lt registered`, "the listing is
909
- # incomplete", indistinguishable from the fault that message exists to name
910
- # even though nothing here is actually wrong. Pinned in the test suite.
911
- # Reordering to `count_linked && count_registry` does not remove this
912
- # residual, it only moves the ADD case's false report onto the
913
- # `linked -lt registered` branch instead — the direction the comment below
914
- # calls out by name as sending an operator hunting a permissions fault that
915
- # is not there. `count_registry` first, `count_linked` second, mirrors
916
- # release-ticket.sh's own recount ordering (count_registry before
917
- # count_linked) — kept fixed for the reason that copy's own comment gives:
918
- # not because a different order would be wrong, but so the reasoning above
919
- # stays about one order instead of two.
920
- #
921
- # `&&`, not `;`, between the two: `count_registry` reports an unreadable
922
- # registry through `add_unknown` and a non-zero return, and under `;` the
923
- # group's status would be `count_linked`'s alone, so this probe would walk
924
- # past a refusal it had already recorded. Measured, that is belt-and-braces
925
- # and not a behaviour difference: every state that fails `count_registry`'s
926
- # `[ -r ] && [ -x ]` guard also stops git enumerating $wtroot, so `linked`
927
- # collapses to 0 alongside `registered` and the comparison below matches
928
- # either way — checked at mode 000 landed inside this very window, under both
929
- # spellings, and the registry message is the only one reported by both. The
930
- # `&&` stays because the status of a count that refused is not
931
- # `count_linked`'s to overwrite, not because a case turns on it today.
932
- [ "$linked" -eq "$registered" ] || { count_registry && count_linked; } || return 1
933
- # Name the direction actually observed. The two disagreements have opposite
934
- # causes and send the reader to opposite places, so one message cannot serve
935
- # both: FEWER listed than registered is git silently dropping an entry it could
936
- # not read, which is the fault this whole check exists to catch. MORE listed
937
- # than registered is the opposite — the on-disk count is the stale read, a
938
- # sibling agent's `git worktree add` having landed between the two, which in a
939
- # parallel fleet is routine rather than exotic. Calling that "the listing is
940
- # incomplete" sends an operator hunting a permissions fault that is not there.
941
- if [ "$linked" -lt "$registered" ]; then
942
- add_unknown "local" "git listed $linked worktrees for $registered registry entries in $wtroot — the listing is incomplete, so no absence it reports can be trusted"
943
- return 1
944
- elif [ "$linked" -gt "$registered" ]; then
945
- add_unknown "local" "git listed $linked worktrees but only $registered registry entries were counted in $wtroot — the registry read missed entries git can see, so no absence it reports can be trusted"
946
- return 1
947
- fi
948
-
949
727
  # substr($0,10), never $2, exactly as release-ticket.sh's own substr($0,10) awks
950
728
  # read the same field: the porcelain prints the path raw, so a checkout under a
951
729
  # directory with a space in it — plain enough on macOS — truncates at the space
@@ -957,8 +735,8 @@ fi
957
735
  # one level down: a failed fork there yields an empty first field and a silent
958
736
  # non-match, and `$(…)` discards the status that would have said so.
959
737
  #
960
- # `\001` counts as a separator for the MATCH, and for the match only. The `tr`
961
- # above turned every newline inside a path into `\001`, and `\001` is not in
738
+ # `\001` counts as a separator for the MATCH, and for the match only.
739
+ # `wt_listing` turned every newline inside a path into `\001`, and `\001` is not in
962
740
  # `([-/]|$)` — so `…/wt/fix-33<LF>slug` arrives as `fix-33\001slug`, the number
963
741
  # stops matching, and a live checkout reads FREE. Measured on real repos with
964
742
  # real linked worktrees: plain porcelain `taken=true` rc 1, `--porcelain -z`
@@ -967,7 +745,7 @@ fi
967
745
  # leaf and `…/wt/fix<LF>33-slug`, which the plain form never matched either.
968
746
  # `b` is the throwaway copy: `p` is untouched, so the evidence this probe
969
747
  # reports — and `worktreeRewritten` with it — still carries the raw bytes.
970
- wt=$(printf '%s\n' "$worktrees" | LC_ALL=C awk -v n="$n" '
748
+ wt=$(printf '%s\n' "$wt_list" | LC_ALL=C awk -v n="$n" '
971
749
  /^worktree / { p = substr($0,10); b = p; sub(".*/", "", b); gsub(/\001/, "/", b)
972
750
  if (b ~ "(^|[/-])" n "([-/]|$)") { out = out sep p; sep = "," } }
973
751
  END { printf "%s", out }') ||
@@ -1661,10 +1661,16 @@ function dispositionsRefusal(pr, review) {
1661
1661
  if (review.survived === 0 && review.unverified === 0) return null;
1662
1662
  const v = review.dispositions;
1663
1663
  if (v === null) {
1664
- return `dispositions unchecked — no dispositions-ok=/dispositions-mismatch=/dispositions-escalate= token answers PR #${pr}'s latest review, `
1664
+ return `dispositions unchecked — no dispositions-ok=/dispositions-mismatch=/dispositions-escalate=/dispositions-unchecked= token answers PR #${pr}'s latest review, `
1665
1665
  + `reviewed=${review.head}; run dispositions-check.mjs --member fix-pr-${pr}[-<x>] --scratch <scratch> for the fix-applier `
1666
1666
  + "that answered that review, then dispatch the finisher again";
1667
1667
  }
1668
+ if (v.verdict === "unchecked") {
1669
+ return `dispositions unchecked — ${v.member}'s check of review ${review.head} could not read where a deferral was filed (gh unreachable, `
1670
+ + "or an issue unreadable — an issue that does not exist is unreadable too, and no re-run answers that one: the check's stderr names "
1671
+ + `it, and the record's issue number needs correcting); run dispositions-check.mjs --member ${v.member} --scratch <scratch> again once gh answers, `
1672
+ + "then dispatch the finisher again";
1673
+ }
1668
1674
  if (v.verdict === "mismatch") {
1669
1675
  return `dispositions mismatch — ${v.member}'s disposition record fails the check against review ${review.head}; `
1670
1676
  + `dispositions-check.mjs --member ${v.member} --scratch <scratch> names each violating entry by bucket, index and rule`;
package/scripts/net.sh CHANGED
@@ -385,8 +385,8 @@ net_git() {
385
385
  # that fault, fetched through this function unmodified, loses the
386
386
  # registry entry between the fetch returning and the caller's own next
387
387
  # read of it — a worktree whose fault is seconds old, not months.
388
- # reap.sh's registry recount (`count_registry`/`count_linked`,
389
- # `wt_registry_why`) reads the very corruption this detached run erases:
388
+ # reap.sh's registry recount (worktree.sh's `wt_counts`) reads the very
389
+ # corruption this detached run erases:
390
390
  # with the entry gone, the registry count drops to match the listing's
391
391
  # linked count, in lockstep, and the guard a stray `git worktree add`
392
392
  # mid-run is built to catch sees no mismatch to refuse on — both branches
@@ -236,6 +236,16 @@ json_lib="$(dirname "$0")/json.sh"
236
236
  # shellcheck source=json.sh
237
237
  . "$json_lib" || die "$json_lib failed to load"
238
238
 
239
+ # The worktree readers and the Registration probe, for the linkage compare
240
+ # below. worktree.sh's header holds the sourcing contract and the measurements
241
+ # behind it; the `[ -r ]` comes first for json.sh's reason above, since exit 1
242
+ # here is a verdict too.
243
+ wt_lib="$(dirname "$0")/worktree.sh"
244
+ [ -r "$wt_lib" ] || die "cannot read $wt_lib — refusing to act without the worktree readers"
245
+ # shellcheck source-path=SCRIPTDIR
246
+ # shellcheck source=worktree.sh
247
+ . "$wt_lib" || die "$wt_lib failed to load"
248
+
239
249
  # Every string that reaches the JSON goes through `jstr`/`jarr` from json.sh —
240
250
  # `$wt` is argv and therefore a filesystem path, which may hold a `"`, a `\`
241
251
  # or a control byte that git's ref rules would reject. The rule list, its
@@ -532,39 +542,29 @@ fi
532
542
  # `git worktree move`, under `worktree.useRelativePaths`, on a submodule, a
533
543
  # `--separate-git-dir` clone and a `core.worktree` naming $wt itself.
534
544
  #
535
- # Compared as a DIRECTORY (`-ef`, same device and inode), never as a string,
536
- # for reap.sh's reason: a worktree whose name is Unicode NFD-composed
537
- # (`cafe` + U+0301), passed in the PRECOMPOSED spelling `worktree list
538
- # --porcelain` echoes under the `core.precomposeunicode` git writes into every
539
- # new repo on macOS, keeps that spelling through `cd && pwd -P`, while
540
- # `--show-toplevel` answers the on-disk NFD bytes — visually identical,
541
- # byte-different, one directory (measured, git 2.50.1, Apple Git-155).
542
- # A byte compare refused every such healthy worktree. `-ef` answers "same
543
- # directory" for both and for any other spelling the filesystem aliases, and
544
- # still refuses every redirect — each names a different directory.
545
- # POSIX.1-2017's `test` does not define `-ef`; it is a ksh-derived extension
546
- # bash, dash and BSD sh share, and POSIX.1-2024 adds it. A `[` that cannot
547
- # evaluate it fails, which is the refusing direction.
548
- #
549
- # `$top` is compared as git spells it, NOT canonicalised through `cd`, which
550
- # `-ef` does not need and which would add two holes: a `core.worktree` naming
551
- # a missing or unsearchable directory still answers at rc 0 (measured), so the
552
- # `cd` fails and `set -e` exits 1 — the DIRTY verdict — over a tree nothing
553
- # looked at; and an empty `$top` makes `cd ""` a no-op in the caller's cwd,
554
- # which may be $wt. `-ef` over a missing or empty `$top` is false, not an
555
- # error: the refusing direction, exit 2.
545
+ # worktree.sh's `wt_linkage` asks it — the compare reap.sh and release-ticket.sh
546
+ # make before their own dirty checks — as a DIRECTORY compare (`-ef`): a worktree
547
+ # whose name is Unicode NFD-composed, passed in the PRECOMPOSED spelling
548
+ # `worktree list --porcelain` echoes, keeps that spelling through
549
+ # `cd && pwd -P` while `--show-toplevel` answers the on-disk NFD bytes, and a
550
+ # byte compare refused every such healthy worktree; its comment carries the
551
+ # measurement. `$top` is never canonicalised through `cd`, which `-ef` does
552
+ # not need and which would add two holes: a `core.worktree` naming a missing
553
+ # or unsearchable directory still answers at rc 0 (measured), so the `cd`
554
+ # fails and `set -e` exits 1 — the DIRTY verdict — over a tree nothing looked
555
+ # at; and an empty `$top` makes `cd ""` a no-op in the caller's cwd, which may
556
+ # be $wt. `-ef` over a missing or empty `$top` is false, not an error: the
557
+ # refusing direction, exit 2. Asked of `$wt_real`, which holds no symlink, so
558
+ # the probe's question about a linked worktree directory replaced by a symlink
559
+ # never turns a caller's symlinked spelling of $wt into a refusal here.
556
560
  #
557
561
  # Not refused, because git does not honour them and `status` reads $wt
558
562
  # (measured): `core.worktree` in the COMMON config seen from a linked worktree,
559
563
  # one reached through `include.path`, and one passed as GIT_CONFIG_COUNT or
560
564
  # GIT_CONFIG_PARAMETERS. The check keys on git's answer, not on the config, so
561
565
  # it cannot refuse a setting git ignores.
562
- top=$(git -C "$wt" rev-parse --show-toplevel && echo x) \
563
- || die "git will not name the working tree answering for $wt — cannot verify its linkage"
564
- top=${top%?x}
565
- # shellcheck disable=SC3013 # -ef is a ksh-derived extension bash/dash/BSD sh share, base in POSIX.1-2024; this file targets dash too and -ef is verified there
566
- [ "$top" -ef "$wt_real" ] \
567
- || die "git answers for the working tree at $top, not $wt — cannot tell a clean worktree from a dirty one"
566
+ wt_linkage "$wt_real" \
567
+ || die "$wt_why — cannot tell a clean worktree from a dirty one"
568
568
 
569
569
  git -C "$wt" rev-parse --verify "$base_rev" >/dev/null || die "$base does not resolve as $base_rev"
570
570
  # Left unchecked, merge-tree below fails silently and "no conflicting files" is