@feigi/fleet-ctl 3.18.2 → 3.18.3

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.18.2",
3
+ "version": "3.18.3",
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": {
@@ -14,19 +14,19 @@
14
14
  #
15
15
  # The Install step and the Test entrypoint are READ from the repository's
16
16
  # proven Recipe cache through derive-testcmd.sh — never inferred, never
17
- # defaulted (ADR 0015): this script keeps no table of technologies. An Install
17
+ # defaulted: this script keeps no table of technologies. An Install
18
18
  # step that modifies the tree in a throwaway worktree corrupts it for everyone
19
19
  # (npm@11 pruning cross-platform @esbuild optional deps out of a lockfile broke
20
20
  # CI and the Docker build), so a dirty tree after it is a refusal.
21
21
  set -eu
22
22
 
23
23
  # Directly below `set -eu`, not below a locale pin: this script has none, and
24
- # locale-pin-prose.test.mjs deliberately leaves it off the PINNED list (whether
25
- # its generated runner needs one is #600's question). The five siblings that DO
24
+ # the locale-pin test deliberately leaves it off its PINNED list (whether
25
+ # its generated runner needs one is not settled here). The siblings that DO
26
26
  # carry a pin put this line under it instead, because that file's PROLOGUE
27
27
  # regex admits only comments, blanks and `set -[eux]+` above the pin. Here
28
28
  # there is no pin to sit under, so the only constraint left is the real one:
29
- # above the first git call. #1020
29
+ # above the first git call.
30
30
  #
31
31
  # Both halves are measured on this script, and each defeats a different guard.
32
32
  #
@@ -43,7 +43,7 @@ set -eu
43
43
  # "$wt" status --porcelain -uall`, the one thing standing between a wrong
44
44
  # Install step and a worktree corrupted for everyone — reads the AMBIENT tree
45
45
  # against $wt's index. Measured (against the lockfile-only form this check
46
- # had before ADR 0015) with an install that really does rewrite a tracked file
46
+ # had before the Recipe cache) with an install that really does rewrite a tracked file
47
47
  # in the fresh worktree: reported clean, rc 0, claim handed out, where the
48
48
  # unpoisoned run refuses at exit 2.
49
49
  unset GIT_DIR GIT_WORK_TREE
@@ -51,7 +51,7 @@ unset GIT_DIR GIT_WORK_TREE
51
51
  NAME=claim-ticket
52
52
  die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
53
53
 
54
- # The escaping helpers (#119). json.sh's header holds the sourcing contract and
54
+ # The escaping helpers. json.sh's header holds the sourcing contract and
55
55
  # the measurements behind it. This script uses exit 2 for every refusal and has
56
56
  # no exit 1, so a bare 1 out of it is a code its caller has no reading for. The
57
57
  # guard sits ahead of every mutation, so a missing library refuses before a
@@ -62,7 +62,7 @@ json_lib="$(dirname "$0")/json.sh"
62
62
  # shellcheck source=json.sh
63
63
  . "$json_lib" || die "$json_lib failed to load"
64
64
 
65
- # The worktree readers (#551, #725). worktree.sh's header holds the sourcing
65
+ # The worktree readers. worktree.sh's header holds the sourcing
66
66
  # contract; the `[ -r ]` ahead of the `.` is load-bearing there, not decoration.
67
67
  # Sourced for `gone()` alone — this script reads no listing.
68
68
  wt_lib="$(dirname "$0")/worktree.sh"
@@ -75,8 +75,8 @@ wt_lib="$(dirname "$0")/worktree.sh"
75
75
  issue=$1
76
76
  slug=$2
77
77
  type=$3
78
- # Exact match, and nothing else tolerated in the slot — the #250 demotion, in
79
- # the file that still carried it. Measured on the unguarded script: `5 slug fix`
78
+ # Exact match, and nothing else tolerated in the slot: an unknown flag is refused
79
+ # rather than demoted to a dry run. Measured on the unguarded script: `5 slug fix`
80
80
  # and `5 slug fix --aply` were byte-identical on stdout AND stderr at exit 0,
81
81
  # so nothing anywhere said the flag was not understood; and the arity check
82
82
  # above was a lower bound alone, so `5 slug fix --apply extra --whatever`
@@ -97,7 +97,7 @@ runner="$wt/agent-test"
97
97
 
98
98
  # A repository probe, and deliberately no more. The git-dir identity invariant
99
99
  # release-ticket.sh and no-undo-audit.sh check (the git dir answering for $wt
100
- # must belong to $wt) is not owed here (#421): this script never asks git
100
+ # must belong to $wt) is not owed here: this script never asks git
101
101
  # anything through a $wt it did not just create. The pair below establishes the
102
102
  # path is absent, `git worktree add` then writes the .git and its admin dir
103
103
  # itself, and the one later `git -C "$wt"` call (the tree-mutation check) runs
@@ -124,8 +124,8 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not inside a git repository"
124
124
  # stderr — in the DEFAULT dry run, where `git worktree add` never runs to refuse
125
125
  # it downstream, that is exit 0 and a receipt byte-identical to a free path's.
126
126
  # `gone()` is the predicate that keeps established-absent and could-not-measure
127
- # apart (worktree.sh; #725 made it one definition rather than three), so the
128
- # refusal below is the existing helper, not a new EACCES-aware stat. #727
127
+ # apart (worktree.sh holds the one definition), so the
128
+ # refusal below is the existing helper, not a new EACCES-aware stat.
129
129
  #
130
130
  # ABSOLUTE, and this is the term to leave alone. `gone()` walks up to the
131
131
  # nearest existing ancestor and asks whether IT is searchable; git hands every
@@ -144,7 +144,7 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not inside a git repository"
144
144
  # to. And the wording of the first stays hedged — a dangling link here has two
145
145
  # provenances with opposite claim states (rc-0 residue, and a release halted
146
146
  # mid-flight with the branch and the label still live), and only the hedge is
147
- # true of both. #728
147
+ # true of both.
148
148
  if [ -e "$wt" ] || [ -L "$wt" ]; then
149
149
  die "$wt already exists — ticket may already be claimed"
150
150
  elif ! gone "$PWD/$wt"; then
@@ -153,37 +153,37 @@ fi
153
153
  git rev-parse --verify --quiet "refs/heads/$branch" >/dev/null && die "branch $branch already exists"
154
154
 
155
155
  # The worktree is built FROM origin/main, so it must resolve before anything is
156
- # claimed. The lockfile probe that stood here before ADR 0015 read origin/main
156
+ # claimed. The lockfile probe the Recipe cache replaced read origin/main
157
157
  # and refused on its absence as a side effect; reading the Recipe cache reads
158
158
  # no ref at all, so the precondition is asked for directly — unasked, the
159
159
  # DEFAULT dry run would report a ticket claimable that `git worktree add` then
160
160
  # refuses under --apply, after the in-progress label is already on the issue.
161
161
  # No `--quiet`: git's own reason for not resolving it reaches the terminal
162
- # beside this refusal (muted-git-guard-sweep.test.mjs).
162
+ # beside this refusal.
163
163
  git rev-parse --verify "origin/main^{commit}" >/dev/null \
164
164
  || die "origin/main does not resolve to a commit — nothing to build the worktree from"
165
165
 
166
166
  # The Recipe: its Install step and Test entrypoint, READ from the repository's
167
167
  # Recipe cache by derive-testcmd.sh — the one reader, reused rather than
168
168
  # reimplemented, so the claim and the review snapshot cannot disagree about
169
- # the cache's shape or what makes it usable (#142). Nothing here infers either
169
+ # the cache's shape or what makes it usable. Nothing here infers either
170
170
  # command: an absent, unproven or unrunnable cache is derive-testcmd.sh's own
171
171
  # refusal, passed through in its own words, which name the step that derives
172
- # the Recipe (ADR 0015).
172
+ # the Recipe.
173
173
  #
174
174
  # `2>&1` so the reason travels: the child refuses on its STDERR and `$(...)`
175
175
  # captures stdout only, so without the merge `die` fires with an empty
176
176
  # argument and prints the bare line `claim-ticket: `. It is safe on the success
177
177
  # path only because derive-testcmd.sh writes nothing to stderr when it
178
- # succeeds, even under an interpreter made deliberately chatty (#1175) — a
179
- # cross-file invariant, so derive-testcmd.test.mjs pins it where the behaviour
178
+ # succeeds, even under an interpreter made deliberately chatty — a
179
+ # cross-file invariant, so derive-testcmd.sh's own tests pin it where the behaviour
180
180
  # lives. The sibling is found beside this script (`dirname -- "$0"`), never on
181
181
  # PATH, for the reason json.sh and worktree.sh are.
182
182
  script_dir=$(dirname -- "$0")
183
183
  # Held in one variable, not repeated as a literal at each die below — the two
184
184
  # copies could drift apart, and derive-testcmd.sh already keeps its own
185
185
  # version the same way (`$derive`).
186
- rederive="the Recipe cache is invalid; run the Recipe derivation step (run-team phase 0, before the first claim — ADR 0015) to re-derive it"
186
+ rederive="the Recipe cache is invalid; run the Recipe derivation step (run-team phase 0, before the first claim) to re-derive it"
187
187
  install=$("$script_dir/derive-testcmd.sh" . install 2>&1) || die "$install"
188
188
  echo " Install step → $install" >&2
189
189
  testcmd=$("$script_dir/derive-testcmd.sh" . test 2>&1) || die "$testcmd"
@@ -193,8 +193,8 @@ echo " test entrypoint → $testcmd" >&2
193
193
  # `sh -c`, so a compound one (`cd sub && make test`) keeps its meaning, with the
194
194
  # runner's own arguments appended as "$@". It reaches the runner's source
195
195
  # single-quoted — each embedded `'` closed, escaped and reopened — so nothing
196
- # in it expands at write time. `LC_ALL=C` so sed reads the command as bytes
197
- # (#582). Derived here, ahead of every mutation, so a failure refuses before
196
+ # in it expands at write time. `LC_ALL=C` so sed reads the command as bytes.
197
+ # Derived here, ahead of every mutation, so a failure refuses before
198
198
  # the label.
199
199
  quoted=$(printf '%s\n' "$testcmd" | LC_ALL=C sed "s/'/'\\\\''/g") \
200
200
  || die "could not quote the Test entrypoint for the runner"
@@ -204,14 +204,14 @@ ollama=$((22000 + issue))
204
204
  echo " ports derive from the issue number: postgres=$pg ollama=$ollama" >&2
205
205
 
206
206
  # Ports above are only ever exported into a FRESH runner this script writes
207
- # (below): a tracked repo-local agent-test is left byte-identical (#1262), so
207
+ # (below): a tracked repo-local agent-test is left byte-identical, so
208
208
  # it never carries them. Starts true and flips to false in that branch, so
209
209
  # the receipt can report which happened instead of asserting exports that
210
210
  # never reached the runner.
211
211
  runner_ports_applied=true
212
212
 
213
213
  # The stamp the runner carries. The runner is written once at claim time and
214
- # never rewritten (#124), so an old worktree can be sitting on a runner a later
214
+ # never rewritten, so an old worktree can be sitting on a runner a later
215
215
  # template fix never reached. This stamp does not detect or fix that — nothing
216
216
  # reads it, nothing refuses on a mismatch — it only makes staleness legible:
217
217
  # diff the stamp against a fresh `cksum` of this script to see if they match.
@@ -266,7 +266,7 @@ else
266
266
  # origin/main, so `@{u}` RESOLVES — to main. Every "did my push land?" check a
267
267
  # member might reach for (`git rev-parse HEAD @{u}`, `git status -sb`) then
268
268
  # answers a question about main and reads healthy no matter what the push did.
269
- # That is #760's sharp half, measured on two live worktrees. Under
269
+ # That is the sharp half, measured on two live worktrees. Under
270
270
  # push.default=upstream the same config is a live hazard rather than a
271
271
  # misleading guard: a bare `git push` would push $branch's commits onto
272
272
  # origin/main. (Under the default push.default=simple it refuses loudly, exit
@@ -282,7 +282,7 @@ else
282
282
  # push, `git push --force-with-lease -u origin HEAD` (skills/next-ticket/SKILL.md
283
283
  # step 7; its no-lease fallback carries `-u` too), and only then can be `[gone]`.
284
284
  #
285
- # `--no-track` is also why no branch delete uses `-d` (#760): `-d` measures an
285
+ # `--no-track` is also why no branch delete uses `-d`: `-d` measures an
286
286
  # upstream-less branch against local HEAD, refusing a pristine claim behind
287
287
  # origin/main. release-ticket.sh's is `git update-ref -d` on a tip read once.
288
288
  printf '$ git worktree add --no-track %s -b %s origin/main\n' "$wt" "$branch" >&2
@@ -292,7 +292,7 @@ else
292
292
  # Through `sh -c`, as the runner runs the Test entrypoint: the Install step
293
293
  # is a shell command out of the cache, not an argv to split. 126 and 127 are
294
294
  # the shell's own "cannot execute" and "not found" — the Recipe failed to
295
- # RUN, which is what invalidates a cache (ADR 0015) — so they are named as
295
+ # RUN, which is what invalidates a cache — so they are named as
296
296
  # that; any other non-zero is the install itself failing, reported as such.
297
297
  irc=0
298
298
  (cd "$wt" && sh -c "$install" >/dev/null 2>&1) || irc=$?
@@ -305,7 +305,7 @@ else
305
305
  # The Install step must leave the tree exactly as `worktree add` checked it
306
306
  # out: the `installClean` proof the cache records, re-asserted on every
307
307
  # claim, over the WHOLE tree rather than a list of lockfile names — fleet-ctl
308
- # keeps no table of which files an install may touch (ADR 0015). Non-empty
308
+ # keeps no table of which files an install may touch. Non-empty
309
309
  # means the Recipe no longer holds, and the worktree is now corrupt for
310
310
  # everyone. Check git's exit status too: a failed status prints nothing,
311
311
  # which is byte-identical to "clean" and would let this guard pass without
@@ -318,14 +318,14 @@ else
318
318
  # which this check would read as an untouched tree it never actually
319
319
  # looked at. `-f`: `git worktree add` writes $wt's `.git` as a regular file,
320
320
  # so no healthy run trips this; reference shape and same reason as
321
- # release-ticket.sh's own linkage guard (#128). `-x "$wt"` for the reason
321
+ # release-ticket.sh's own linkage guard. `-x "$wt"` for the reason
322
322
  # reap.sh and worktree-audit.sh give their own copy: `-f` is equally false
323
323
  # for a `.git` that is absent and for one this process may not stat, and an
324
324
  # unsearchable $wt must not be reported as an absence nothing established.
325
325
  # Left ungated it ate the case before the `git -C` below could reach it —
326
326
  # measured: `.git` still sitting there while the run blamed its deletion.
327
327
  # Gated, git answers with its own denial through the elif, which is what
328
- # release-ticket.test.mjs already pins as the wording to prefer over one this
328
+ # release-ticket.sh's tests already pin as the wording to prefer over one this
329
329
  # script invents.
330
330
  if [ -x "$wt" ] && [ ! -f "$wt/.git" ]; then
331
331
  die "$wt has no .git file — cannot verify the Install step left the tree clean"
@@ -340,7 +340,7 @@ else
340
340
  # reaches this terminal on its own, which is the "its own denial" the
341
341
  # paragraph above means; the die names the failure, not the reason.
342
342
  #
343
- # `-uall`: #730 (see reap.sh's branch sweep for the full explanation) —
343
+ # `-uall`: see reap.sh's branch sweep for the full explanation —
344
344
  # the untracked mode is CONFIG: an install that CREATES a file the tree does
345
345
  # not track or ignore (a lockfile it was never given) dirties the tree as
346
346
  # surely as one that rewrites a tracked file, and under
@@ -358,13 +358,13 @@ else
358
358
 
359
359
  # A runner is already there: the repo tracks its own `agent-test`, and `git
360
360
  # worktree add` checked it out with everything else — a repo-local runner,
361
- # the home ADR 0015 gives any convenience beyond "exec the Test entrypoint"
361
+ # the home for any convenience beyond "exec the Test entrypoint"
362
362
  # (this repository's own test-argument shim lives in one). Writing
363
363
  # over it is what must not happen: the file is TRACKED, so the write leaves a
364
364
  # modified tracked path, and `reap.sh` calls `git worktree remove` without
365
365
  # `--force` (its own comment: "refuses on modified and untracked files").
366
366
  # Every release of every claim would then strand on a file this script wrote
367
- # itself (#1262). On this path $runner is always the fresh worktree's own
367
+ # itself. On this path $runner is always the fresh worktree's own
368
368
  # `agent-test`, so existence IS trackedness: nothing else could have put a
369
369
  # file there between `worktree add` and here.
370
370
  if [ -e "$runner" ]; then
@@ -394,7 +394,7 @@ fi
394
394
  # `$type/$issue-$slug`, `$wt` is `.worktrees/$issue-$slug`, `$runner` is
395
395
  # `$wt/agent-test`. A quote in either argument emitted a payload no parser
396
396
  # accepts, at exit 0 and — under `--apply` — after the worktree and the label
397
- # already existed (#119). `$install` is the Recipe cache's own string and can
397
+ # already existed. `$install` is the Recipe cache's own string and can
398
398
  # carry any byte a shell command can, a quote included; jstr is what keeps it a
399
399
  # JSON string. The numeric fields stay unwrapped: `$issue` is a JSON
400
400
  # number by the guard above, and the ports are arithmetic on it.
@@ -41,29 +41,29 @@ set -eu
41
41
  # nothing at all, measured — and `grep` silently drops the line holding it.
42
42
  # Such a byte reaches us from a fetched tree even where the local filesystem
43
43
  # refuses to hold the name, and inside `$(...)` a `tr` failure empties the cause
44
- # out of the diagnostic without a trace. #582 measured the cost of leaving this
45
- # ambient in no-undo-audit.sh: a truncated list reported as a clean, confident
46
- # answer.
44
+ # out of the diagnostic without a trace. The cost of leaving this ambient in
45
+ # no-undo-audit.sh was measured: a truncated list reported as a clean,
46
+ # confident answer.
47
47
  #
48
48
  # Safe as a global: nothing in this script sorts, folds case, or holds a POSIX
49
49
  # class. It does use ONE collation range — `*[!0-9]*`, the issue-number guard
50
50
  # below — and a range IS locale-sensitive by spec, its members drawn from the
51
- # collation sequence rather than the codepoint order. Measured inert here
52
- # (#612): `0-9` matches the ASCII digits and nothing else under `C`,
51
+ # collation sequence rather than the codepoint order. Measured inert here:
52
+ # `0-9` matches the ASCII digits and nothing else under `C`,
53
53
  # `en_US.UTF-8`, `de_DE.UTF-8` and `tr_TR.UTF-8` alike, with superscript `²`,
54
54
  # Arabic-Indic digits and `½` excluded in all four. So collation and
55
55
  # case-folding — the two things `LC_ALL=C` otherwise changes — have nothing
56
- # here to act on. locale-pin-prose.test.mjs holds that inventory as a list and
56
+ # here to act on. The locale-pin test holds that inventory as a list and
57
57
  # fails if the code drifts from this paragraph in either direction.
58
58
  export LC_ALL=C
59
59
 
60
60
  # Below the locale pin, not above it with `set -eu`: `unset` touches no
61
- # byte-sensitive tool, but locale-pin-prose.test.mjs treats ANY line here that
61
+ # byte-sensitive tool, but the locale-pin test treats ANY line here that
62
62
  # is not a comment, a blank, or `set -[eux]+` as work the pin must sit above,
63
63
  # and refuses on principle rather than on this line's own behaviour.
64
64
  #
65
- # An ambient GIT_WORK_TREE outranks `-C`, not just plain discovery (measured,
66
- # #427): with GIT_WORK_TREE alone pointing at an unrelated tree, `git -C "$wt"
65
+ # An ambient GIT_WORK_TREE outranks `-C`, not just plain discovery (measured):
66
+ # with GIT_WORK_TREE alone pointing at an unrelated tree, `git -C "$wt"
67
67
  # rev-parse --show-toplevel` answers about THAT tree, not `$wt` — the linkage
68
68
  # guard below then blames a healthy `.git`, reporting it resolves to whatever
69
69
  # the ambient var named. `git -C "$wt" status --porcelain` reads the same
@@ -72,7 +72,7 @@ export LC_ALL=C
72
72
  # script (no `-C` at all) is equally hostage to an ambient GIT_DIR retargeting
73
73
  # it away from the repository the caller actually invoked this in. Unsetting
74
74
  # both here, before any of them runs, is the one fix that reaches all of them
75
- # at once — the same pattern `ledger.mjs` and `inflight.test.mjs` apply by hand
75
+ # at once — the same pattern `ledger.mjs` and inflight.sh's tests apply by hand
76
76
  # per child process, under a comment making the same point: inherited git vars
77
77
  # outrank cwd (and, here, outrank `-C` too).
78
78
  #
@@ -83,8 +83,8 @@ export LC_ALL=C
83
83
  # script, the ones with no `-C` to even attempt insulating them.
84
84
  #
85
85
  # Both halves are pinned, one fixture each: GIT_WORK_TREE by the linkage-guard
86
- # case, GIT_DIR by `an ambient GIT_DIR does not aim the release at another
87
- # repository (#427)`. That second fixture measures the damage end-to-end
86
+ # case, GIT_DIR by the case showing an ambient GIT_DIR does not aim the release
87
+ # at another repository. That second fixture measures the damage end-to-end
88
88
  # through one of the `-C`-less calls: with only `unset GIT_WORK_TREE` here, the
89
89
  # run reports `released: true` after deleting the claim's branch name in a
90
90
  # DIFFERENT repository and leaving this repository's three artefacts intact.
@@ -118,9 +118,9 @@ blockers=""
118
118
  # below, before anything is accumulated — byte-identical to today: no
119
119
  # `$blockers` reference is even reached.
120
120
  #
121
- # Approach 2 (#387): print the same receipt shape the blocked checkpoint and
121
+ # Chosen design: print the same receipt shape the blocked checkpoint and
122
122
  # `halt` already use, with `$1` appended to `$blockers` exactly as `block`
123
- # would have recorded it — not a new schema, and not a second write. Approach 1
123
+ # would have recorded it — not a new schema, and not a second write. The alternative
124
124
  # (emit the receipt as soon as blockers goes non-empty, before whatever can
125
125
  # die) was ruled out: it lets a run print a receipt and then keep going and
126
126
  # fail anyway, which is a run with two writes or a receipt describing a state
@@ -132,10 +132,10 @@ blockers=""
132
132
  # string stays byte-identical to the blocked checkpoint's rather than growing a
133
133
  # second blockers slot only this one caller uses.
134
134
  #
135
- # release-ticket.test.mjs's "block() then die() compose a receipt that still
136
- # parses as JSON, blockers in order (#1080)" pins this by name: two `block()`
135
+ # The test "block() then die() compose a receipt that still
136
+ # parses as JSON, blockers in order" pins this by name: two `block()`
137
137
  # calls, then a `die()` splice, composed for real rather than reasoned about
138
- # by hand the way PR #983 did. Mutation-verified both directions — `block`
138
+ # by hand. Mutation-verified both directions — `block`
139
139
  # dropping its comma, or appending two instead of one — reds that test.
140
140
  #
141
141
  # The `||` arm is the receipt's only voice. `|| die` is what `block` and `halt`
@@ -162,9 +162,9 @@ die() {
162
162
  }
163
163
 
164
164
 
165
- # The escaping helpers (#119). json.sh's header holds the sourcing contract and
165
+ # The escaping helpers. json.sh's header holds the sourcing contract and
166
166
  # the measurements behind it; only what is true of THIS script is repeated here.
167
- # Below `export LC_ALL=C` deliberately: locale-pin-prose.test.mjs allows only
167
+ # Below `export LC_ALL=C` deliberately: the locale-pin test allows only
168
168
  # comments, blanks, a shebang or a `set -` line above that pin, and `json_lib=`
169
169
  # is none of them.
170
170
  #
@@ -179,7 +179,7 @@ json_lib="$(dirname "$0")/json.sh"
179
179
  # shellcheck source=json.sh
180
180
  . "$json_lib" || die "$json_lib failed to load"
181
181
 
182
- # The worktree readers (#551, #725). worktree.sh's header holds the sourcing
182
+ # The worktree readers. worktree.sh's header holds the sourcing
183
183
  # contract and the measurements behind it, and json.sh's holds the `[ -r ]`
184
184
  # reasoning both guards share. This script reads exit 1 as its own blocked
185
185
  # verdict, which is the whole reason that guard is not `|| die` alone.
@@ -189,7 +189,7 @@ wt_lib="$(dirname "$0")/worktree.sh"
189
189
  # shellcheck source=worktree.sh
190
190
  . "$wt_lib" || die "$wt_lib failed to load"
191
191
 
192
- # The bounded, prompt-suppressed git transport (#92, #346, #347). The
192
+ # The bounded, prompt-suppressed git transport. The
193
193
  # pushed-branch lookup below is unattended: with no bound it can prompt for a
194
194
  # credential or a host key, or stall on a transport that connects and then goes
195
195
  # quiet, and either holds a fleet slot until something outside kills it.
@@ -294,7 +294,7 @@ git rev-parse --verify "$base_rev" >/dev/null || die "$base does not resolve"
294
294
  # one level too shallow, because naming an entry needs read+execute on the
295
295
  # PARENT only. `chmod 000` on the `gitdir` FILE inside an entry passes every
296
296
  # permission test this script could make on the entry itself and still drops
297
- # the worktree from the listing — measured, and that is #84 unclosed. Count
297
+ # the worktree from the listing — measured. Count
298
298
  # instead: one registry entry on disk per linked worktree, against what git
299
299
  # reported. A mismatch is a silent drop, whichever file inside was unreadable.
300
300
  #
@@ -306,14 +306,12 @@ common=$(git rev-parse --path-format=absolute --git-common-dir) ||
306
306
  die "cannot resolve the git common directory"
307
307
  wtroot="$common/worktrees"
308
308
 
309
- # A function, not inline, because the count is taken twice: once here, and
310
- # once more at the recount below if the cross-check disagrees with git's own
311
- # listing (#694). The body is unchanged from what stood here as plain
312
- # top-level code before this ticket — mirrors inflight.sh's own
313
- # count_registry, which the same recount need already lives behind there,
314
- # adapted for the difference the ticket turns on: that copy returns a status
315
- # into an accumulate-and-continue probe, this one dies, so the loop itself
316
- # still just dies on an unreadable registry rather than returning past it.
309
+ # A function, not inline, because the count is taken more than once: here, and
310
+ # again by the recount loop below, up to `recount_tries` times, while the
311
+ # cross-check disagrees with git's own listing. It mirrors inflight.sh's own
312
+ # count_registry, adapted for the difference that matters: that copy returns a
313
+ # status into an accumulate-and-continue probe; this one dies, so an unreadable
314
+ # registry still just dies here rather than returning past it.
317
315
  count_registry() {
318
316
  registered=0
319
317
  [ -e "$wtroot" ] || return 0
@@ -340,9 +338,7 @@ count_registry() {
340
338
  # on disk (measured: listed 1 → linked 0, and a gitdir-keyed count returns 0
341
339
  # to match). A corrupt entry still holds git's own files — commondir, HEAD,
342
340
  # index, logs, refs — so emptiness separates it from a stray where the
343
- # missing `gitdir` does not. This is #384's own second commit, and #395
344
- # exists partly to keep this copy from inheriting the discriminator it
345
- # replaced.
341
+ # missing `gitdir` does not.
346
342
  #
347
343
  # `ls`'s STATUS, not just its output, and that is the whole point: an entry
348
344
  # we could not LIST is not an empty one, and `2>/dev/null` hides the
@@ -369,14 +365,14 @@ count_registry
369
365
  # A newline in that path was the same truncation one byte further out: the plain
370
366
  # porcelain ends every attribute with one, so the record split and every
371
367
  # `substr($0,10)` below stopped at the newline. `wt_listing` reads `-z` and
372
- # swaps the separators, so a record ends where git says it ends. #551
368
+ # swaps the separators, so a record ends where git says it ends.
373
369
  #
374
370
  # `|| die`, where this was a bare assignment: left bare the read died on `set -e`
375
371
  # under git's own diagnostic, with no line carrying the `release-ticket:` prefix
376
372
  # a caller greps stderr for — the very reason every lookup OVER this listing is
377
373
  # already guarded that way.
378
374
  #
379
- # A function, not inline, because the recount below (#694) needs this whole
375
+ # A function, not inline, because the recount below needs this whole
380
376
  # pair — git's own read and the count derived from it — re-taken TOGETHER, not
381
377
  # just re-assigned in isolation. `linked` and `wt_list`/`wt_err` are this
382
378
  # function's OUTPUT, exactly as `registered` is `count_registry`'s.
@@ -412,7 +408,7 @@ count_linked() {
412
408
  # count over this listing can see the truncation. It is a count of records against
413
409
  # registry entries and catches an entry git DROPPED; the path inside a record it
414
410
  # does keep is `nl_path`'s to refuse, below. Under `-z` the count is now right by
415
- # construction — one `worktree ` line per record, whatever the path holds. #551
411
+ # construction — one `worktree ` line per record, whatever the path holds.
416
412
  listed=$(printf '%s\n' "$wt_list" | LC_ALL=C awk '/^worktree /{c++} END{print c+0}') ||
417
413
  die "could not count the worktrees git listed for #$issue"
418
414
  # The `|| die` above closes only the route where awk could not RUN. An empty but
@@ -424,7 +420,7 @@ count_linked() {
424
420
  # linked worktree at all — a guard that refused that would refuse most releases
425
421
  # in this repo. Real `git worktree list --porcelain` always prints the main
426
422
  # worktree, so reaching this needs a broken or shimmed git; the refusal
427
- # direction was already right, only the number was nonsense. #699
423
+ # direction was already right, only the number was nonsense.
428
424
  [ "$listed" -ge 1 ] ||
429
425
  die "git listed no worktrees at all for #$issue — not even the main checkout, so the listing cannot be trusted"
430
426
  linked=$((listed - 1))
@@ -438,18 +434,18 @@ count_linked
438
434
  # sibling agent's `git worktree add` having landed between the two, which in a
439
435
  # parallel fleet is routine rather than exotic. Calling that "the listing is
440
436
  # incomplete" sends an operator hunting a permissions fault that is not there.
441
- # Recount before refusing (#694). The registry scan above and git's listing
437
+ # Recount before refusing. The registry scan above and git's listing
442
438
  # just taken are two reads at two different instants, not one atomic read, and
443
439
  # a sibling agent's `git worktree add` or `remove` landing in the gap makes the
444
440
  # two counts disagree with nothing actually wrong — measured against this
445
441
  # script directly: 3/100 dry-run releases aborted on this cross-check under a
446
442
  # throttled churner, 48-66/80 unthrottled, all with zero real faults among them.
447
443
  #
448
- # inflight.sh already recounts here (#694) into its own accumulate-and-continue
444
+ # inflight.sh already recounts here into its own accumulate-and-continue
449
445
  # probe; this script's whole contract is `die` on any unmet precondition
450
446
  # instead, so the port keeps that shape rather than inheriting the accumulator.
451
- # Both copies recount BOTH `registered` and `linked` — this one from #1408,
452
- # inflight.sh's from #1421, which closed the same window in that copy.
447
+ # Both copies recount BOTH `registered` and `linked`, which closes the same
448
+ # window in each.
453
449
  # Re-taking `registered` alone leaves `linked` pinned to the FIRST `wt_listing`
454
450
  # call: a second sibling mutation landing after that call returns but before
455
451
  # the lone recount re-scans the registry inflates `registered` without touching
@@ -474,9 +470,9 @@ count_linked
474
470
  # The order is kept the same as the original pair for THIS argument's sake —
475
471
  # it lets the invariant above carry over instead of being re-derived for a
476
472
  # different order — not because a different order would be wrong. Verified
477
- # directly (#1424): swapping the recount to `count_linked` first then
473
+ # directly: swapping the recount to `count_linked` first then
478
474
  # `count_registry` still passes all four tests below (the two single-mutation
479
- # absorptions and the two #1408 regression cases) unchanged. Both functions
475
+ # absorptions and the two regression cases) unchanged. Both functions
480
476
  # only read — neither writes anything the other observes — so whichever runs
481
477
  # first merely trades which of the two symmetric windows (before the first
482
478
  # call, between the two, after the second) a same-shaped mutation would need
@@ -497,8 +493,8 @@ count_linked
497
493
  # one atomic read: a THIRD sibling mutation landing between the recount's own
498
494
  # `count_registry` and `count_linked` calls escapes the single-recount
499
495
  # invariant the same way a second mutation once escaped the original pair,
500
- # and mislabels the same benign race under one of the two `die`s below (#1424,
501
- # deferred from #1408's own review). Verified directly with a shim landing a
496
+ # and mislabels the same benign race under one of the two `die`s below.
497
+ # Verified directly with a shim landing a
502
498
  # first mutation ahead of the initial listing and a second squarely inside the
503
499
  # recount's own gap: the wrong-direction message reproduced against this
504
500
  # script before the loop below existed.
@@ -519,8 +515,8 @@ count_linked
519
515
  # within this one invocation — while a genuine corruption is a standing
520
516
  # state, not a moment, and still survives every pass and still refuses once
521
517
  # the loop below runs out. `recount_tries` bounds it at one more attempt than
522
- # #1408 already took (closing the specific #1424 residual without turning
523
- # this into the open-ended chase the issue itself calls out) rather than a
518
+ # the single recount already took (closing the specific residual without turning
519
+ # this into an open-ended chase) rather than a
524
520
  # measured constant — sustained real churn settling in two extra reads is not
525
521
  # something this fixture can measure a percentage for, unlike the numbers
526
522
  # above.
@@ -543,16 +539,16 @@ fi
543
539
  # `locked` and `unresolved_head` below read the same `$wt_list` through awk and
544
540
  # answer THROUGH its exit status, where telling "could not run" from "no match"
545
541
  # needs more than a `|| die`. Each captures that status itself and refuses above
546
- # the range its answer occupies; `locked` carries why (#454).
542
+ # the range its answer occupies; `locked` carries why.
547
543
  #
548
- # Neither #243 trigger is what makes these guards worth having, and both are
544
+ # Neither of the two triggers described next is what makes these guards worth having, and both are
549
545
  # narrower than they look. A newline in <slug> reaches the branch lookup as a
550
546
  # `-v` value, where BSD awk refuses it outright but mawk and gawk accept it
551
547
  # (measured), so on those the run simply walks past. An undecodable byte would
552
548
  # arrive as record data instead — the trigger no policy on <slug> could also
553
549
  # cover — but it is held shut here by one line, `export LC_ALL=C` above: under
554
550
  # a UTF-8 locale these very programs exit 2 on such a byte, under `C` they read
555
- # it as data (both measured, #582). What the guards actually answer for is an
551
+ # it as data (both measured). What the guards actually answer for is an
556
552
  # awk that could not run AT ALL, which no locale or implementation rules out.
557
553
  #
558
554
  # Guarding these ASSIGNMENTS cannot turn an empty answer into a refusal: none of
@@ -605,7 +601,7 @@ main_wt=$(printf '%s\n' "$wt_list" | awk '/^worktree /{print substr($0,10); exit
605
601
  # Unlike `locked`'s path, this needle is built from argv rather than read off
606
602
  # disk — but argv is not exempt from a backslash either, and awk itself still
607
603
  # exits 0 having simply matched nothing: the permissive answer, in a probe whose
608
- # whole job is to catch a claim whose branch moved (#799). ENVIRON does no such
604
+ # whole job is to catch a claim whose branch moved. ENVIRON does no such
609
605
  # processing.
610
606
  stray=$(printf '%s\n' "$wt_list" |
611
607
  D="/$issue-$slug" awk '/^worktree /{n++; p=substr($0,10); d=ENVIRON["D"]
@@ -620,7 +616,7 @@ git rev-parse --verify --quiet "refs/heads/$branch" >/dev/null && has_branch=tru
620
616
  # so without it a single `"` or backslash anywhere emits a payload the caller
621
617
  # cannot parse — while the delete has already happened and the exit code still
622
618
  # says success. The rule list and its ordering live in json.sh, once, rather
623
- # than here and in inflight.sh and in no-undo-audit.sh (#119).
619
+ # than here and in inflight.sh and in no-undo-audit.sh.
624
620
  # A `$(...)` in printf's ARGUMENT list sits outside the `|| die` on the printf
625
621
  # itself: a substitution that fails contributes an EMPTY argument and printf
626
622
  # still exits 0 — and an unquoted `%s` slot then emits `"...Rewritten":,`,
@@ -665,7 +661,7 @@ wt_outcome=Unreleased
665
661
  # Why the measurement could not be taken, empty whenever it could. Only
666
662
  # `Indeterminate` ever carries one, and `halt` appends it to that state's report:
667
663
  # "could not be measured" names the failure without naming its cause, which is
668
- # the one line an operator mid-release has nothing else to go on. #551
664
+ # the one line an operator mid-release has nothing else to go on.
669
665
  wt_why=
670
666
  done_branch=false
671
667
  halt() {
@@ -739,7 +735,7 @@ block() {
739
735
  # whose whole job is to refuse to answer permissively. ENVIRON does no such
740
736
  # processing.
741
737
  # And the status is CAPTURED rather than answered with, for the same reason one
742
- # rung down (#454). This predicate's answer IS awk's exit status — 0 locked, 1
738
+ # rung down. This predicate's answer IS awk's exit status — 0 locked, 1
743
739
  # not locked — so an awk that could not run lands above both and, called in a
744
740
  # condition as both callers must call it, is read as the FALSE answer: "not
745
741
  # locked" again, the permissive one. Measured through this script with awk
@@ -771,8 +767,8 @@ locked() {
771
767
  # on some other branch? Four ways an admin HEAD file breaks all produce the
772
768
  # same porcelain shape — the null object id with no `branch` line: `chmod 000`
773
769
  # on it, garbage content in it, a dangling symlink in its place, or a
774
- # directory in its place (measured, git 2.50.1). release-ticket.test.mjs
775
- # builds all four. `chmod 000` is the only one needing a permission bit, so it
770
+ # directory in its place (measured, git 2.50.1). The release-ticket tests
771
+ # build all four. `chmod 000` is the only one needing a permission bit, so it
776
772
  # alone carries the `EUID0` skip the file's other permission fixtures do and
777
773
  # measures nothing on a root runner; the other three reproduce as any user.
778
774
  #
@@ -830,17 +826,17 @@ unresolved_head() {
830
826
  occupied() { [ -e "$1" ] || [ -L "$1" ]; }
831
827
 
832
828
  # The registration PROBE at the heart of the arm below: is $1 still listed in
833
- # $now, the fresh post-removal listing? #798. `locked` and `unresolved_head`
829
+ # $now, the fresh post-removal listing? `locked` and `unresolved_head`
834
830
  # read their own awk's exit status STRAIGHT as the answer — 0 true, 1 false —
835
831
  # so an awk that could not run (rc >= 2: killed, OOM, a broken interpreter) and
836
832
  # an awk that ran fine and found no match (rc 1, the genuine "not registered")
837
- # both land on the false side of the same elif, and #798 measured what that
833
+ # both land on the false side of the same elif, and it was measured what that
838
834
  # fold did here: with nothing left to distinguish them, the run fell through to
839
835
  # `elif occupied "$1"; then wt_outcome=Deregistered` and wrote a false
840
836
  # Deregistered into the JSON receipt for a registration nothing established was
841
837
  # actually cleared.
842
838
  #
843
- # `locked` and `unresolved_head`'s own fix (#454) is not enough copied
839
+ # `locked` and `unresolved_head`'s own fix is not enough copied
844
840
  # verbatim: both `die` on an awk that could not run, which is right for a
845
841
  # precondition gate — abort before any mutation is attempted — and wrong here.
846
842
  # `release_outcome` runs AFTER `git worktree remove` has already run, is called
@@ -867,7 +863,7 @@ ro_registered() {
867
863
  }
868
864
 
869
865
  # Which release outcome does $1 hold after a `git worktree remove` that refused?
870
- # Measured, never inferred from the rc — that inference is this file's #208.
866
+ # Measured, never inferred from the rc — recording the rc instead of what landed is the defect this exists to remove.
871
867
  # git drops the registration BEFORE the directory and does not restore it when
872
868
  # the directory delete fails, so one call has three landing shapes and the exit
873
869
  # code separates none of them. All measured on git 2.50.1:
@@ -887,8 +883,8 @@ ro_registered() {
887
883
  # cannot-stat apart. No second predicate and no third value inside `gone`: it is
888
884
  # now a single definition in worktree.sh that every caller in the fleet shares,
889
885
  # so a third value added for this one caller lands in all of them — and this file
890
- # already carries two answers on unreadable worktrees (#83) from a concept that
891
- # got duplicated. #725
886
+ # already carries two answers on unreadable worktrees from a concept that
887
+ # got duplicated.
892
888
  #
893
889
  # Only the four named states, so the two cells CONTEXT.md has no name for are
894
890
  # not asserted: a registration that survived a directory that did not is
@@ -900,7 +896,7 @@ ro_registered() {
900
896
  # `$wt_err` — would die with it. That is not hypothetical, it is what this
901
897
  # function did: the one case where the headline degrades to "what landed could
902
898
  # not be measured" was the one case whose cause never reached the operator, on
903
- # stderr or in the receipt. Assigning globals is what carries it out. #551
899
+ # stderr or in the receipt. Assigning globals is what carries it out.
904
900
  release_outcome() {
905
901
  # `wt_listing` writes the shared `$wt_list`, and this function must not disturb
906
902
  # the pre-mutation capture the guards above read off it. Saved and put back in
@@ -924,7 +920,7 @@ release_outcome() {
924
920
  elif [ -n "$wt_why" ]; then
925
921
  # awk could not run at all (rc >= 2), which is a different fact from
926
922
  # "ran fine and found nothing" — the latter alone means Deregistered is on
927
- # the table below. #798
923
+ # the table below.
928
924
  wt_outcome=Indeterminate
929
925
  elif occupied "$1"; then
930
926
  wt_outcome=Deregistered
@@ -939,7 +935,7 @@ release_outcome() {
939
935
  # it whole with the newline substituted, and the substituted byte is one no
940
936
  # `git worktree remove`, no `[ -d ]` and no `git -C` below can name — so every
941
937
  # check over it would answer about a different path, which is exactly the silent
942
- # truncation this ticket exists to end. #551
938
+ # truncation this check exists to end.
943
939
  #
944
940
  # `block`, not `die`: this is a refused precondition like every other one here,
945
941
  # and the caller gets the receipt that verdict carries. `nl_path ""` is false, so
@@ -1000,7 +996,7 @@ fi
1000
996
  # a repo under a directory with a backslash in its name would arrive mangled and
1001
997
  # the comparison would fall to the permissive answer — no match, and back to the
1002
998
  # silent release this exists to stop. The suffix key above went through ENVIRON
1003
- # too, for the same reason (#799): its needle is built from argv rather than
999
+ # too, for the same reason: its needle is built from argv rather than
1004
1000
  # read off disk, but argv is not exempt from a backslash either.
1005
1001
  #
1006
1002
  # Absent entry, unreadable entry, or one pointing somewhere git is not listing:
@@ -1017,7 +1013,7 @@ stray_own="matches this claim's directory name $issue-$slug"
1017
1013
  # and the operator is handed a command the shell refuses to parse at all
1018
1014
  # (`unexpected EOF`, rc 2, measured) — loud rather than wrong, but an
1019
1015
  # instruction that cannot run, over a path git accepts in both a refname and a
1020
- # worktree directory name. #1100
1016
+ # worktree directory name.
1021
1017
  #
1022
1018
  # A parameter-expansion loop, not the `sed` one-liner it wants to be. Two
1023
1019
  # measurements say why, both on /bin/sh (bash 3.2) and /bin/dash:
@@ -1061,8 +1057,8 @@ shquote() {
1061
1057
  #
1062
1058
  # A search, not a name built from the directory. The entry name is git's own,
1063
1059
  # on the two measurements the block above already turns on. So `${stray##*/}`
1064
- # would assert a path this script never read, which is the defect class #179
1065
- # exists to remove, and after a move or behind an entry thief it resolves to
1060
+ # would assert a path this script never read, a claim nothing observed, and
1061
+ # after a move or behind an entry thief it resolves to
1066
1062
  # somebody else's entry outright.
1067
1063
  #
1068
1064
  # `-x`, not a substring: `gitdir` holds exactly one line whose whole content is
@@ -1148,8 +1144,8 @@ if [ -z "$wt" ] && [ -n "$stray" ]; then
1148
1144
  # prints the FIRST in porcelain order, so a stranger registered under that
1149
1145
  # basename and sorting ahead of the claim is what it answers with — measured
1150
1146
  # on a healthy decoy at `.worktrees/0-decoy/<issue>-<slug>`, which took this
1151
- # blocker while the claim's own detached directory sat behind it (#1064, and
1152
- # the fixture is pinned below). `is this claim's` then sent an operator to
1147
+ # blocker while the claim's own detached directory sat behind it (the fixture
1148
+ # is pinned below). `is this claim's` then sent an operator to
1153
1149
  # hand-release somebody else's live tree, over a worktree the script had just
1154
1150
  # read a DIFFERENT branch off — the one case where it can say the assertion is
1155
1151
  # false. Name the collision instead: same directory name, wrong branch, which
@@ -1167,10 +1163,10 @@ if [ -z "$wt" ] && [ -n "$stray" ]; then
1167
1163
  # The unlock command below is the one other pasted remedy in this chain that
1168
1164
  # takes `$stray` as an argument — `git worktree prune` and `release it by
1169
1165
  # hand` name no path — so it is the one other arm `shquote` must cover for
1170
- # the same reason #1100 covered the entry search: an embedded `'` closes the
1166
+ # the same reason it covers the entry search: an embedded `'` closes the
1171
1167
  # quote this hint has no quote of its own to reopen, and the operator is
1172
1168
  # handed a command that runs against a truncated, different path instead of
1173
- # being refused outright. (#1554)
1169
+ # being refused outright.
1174
1170
  shquote "$stray"
1175
1171
  stray_shq=$shq
1176
1172
  if locked "$stray"; then
@@ -1200,8 +1196,7 @@ fi
1200
1196
  #
1201
1197
  # In the PRECONDITION block deliberately, not in the mutation path: here the dry
1202
1198
  # run predicts the refusal for free, where placed below it would report only
1203
- # under --apply and rebuild the dry/apply asymmetry #86, #385 and #386 were
1204
- # filed against.
1199
+ # under --apply and rebuild the dry/apply asymmetry.
1205
1200
  #
1206
1201
  # Gated on this claim having no registration of ours. With `wt` or `stray` set
1207
1202
  # the directory IS registered and a guard above owns it — which is what keeps a
@@ -1230,10 +1225,10 @@ if [ -z "$wt" ] && [ -z "$stray" ]; then
1230
1225
  # untouched — invisible to candidates.mjs and still in-flight. Refuse
1231
1226
  # instead of guessing.
1232
1227
  #
1233
- # Deferred past the orphan probe above (#624) rather than fired the moment
1228
+ # Deferred past the orphan probe above rather than fired the moment
1234
1229
  # `has_branch` reads false: this exact input — no branch, no worktree, no
1235
- # stray — is also what #208's knock-on leaves behind, a claim whose branch
1236
- # a prior half-release already deleted with its directory still on disk.
1230
+ # stray — is also what a prior half-release leaves behind: a claim whose branch
1231
+ # was already deleted, with its directory still on disk.
1237
1232
  # Fired unconditionally, that state got the same "check the <slug> and
1238
1233
  # <type> arguments" prose as a genuine typo, naming the wrong cause over a
1239
1234
  # directory sitting right there with a real remedy. The orphan probe above
@@ -1339,17 +1334,17 @@ fi
1339
1334
  # stat, and only the second is unknown — so the existence test has to be the one
1340
1335
  # that agrees with `gone` about what "exists" means. It did not. Every `test`
1341
1336
  # primary except `-L` STATS, so a DANGLING symlink is `-e` false, and once `gone`
1342
- # stopped calling that established-absent (#725) this guard read it as "cannot
1337
+ # stopped calling that established-absent this guard read it as "cannot
1343
1338
  # tell" and died at exit 2 with no receipt — for a path whose state is known
1344
1339
  # exactly, and which the stand-in blocker below already answers. Measured on
1345
- # release-ticket.test.mjs's own dangling-link fixture, which is what caught it.
1340
+ # the release-ticket tests' own dangling-link fixture, which is what caught it.
1346
1341
  #
1347
1342
  # `! occupied && ! gone` is the tri-valued pairing `gone`'s contract prescribes,
1348
1343
  # and the same one `release_outcome` composes: present or link-present is not
1349
1344
  # unknown, established-absent is not unknown, and what is left over is.
1350
1345
  #
1351
1346
  # `! nl_path` for the same reason the dangling link needed `occupied`, and it is
1352
- # the same trap a second time: `gone` now refuses a substituted path too (#551),
1347
+ # the same trap a second time: `gone` now refuses a substituted path too,
1353
1348
  # so without this exemption the pairing reads it as "cannot tell" and dies — for
1354
1349
  # a path the newline blocker above has already answered in the operator's own
1355
1350
  # terms, downgrading a receipt-carrying `NOT released` verdict to an exit-2 die
@@ -1403,7 +1398,7 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1403
1398
  #
1404
1399
  # Existence is not enough on its own: a .git naming a gitdir whose
1405
1400
  # core.worktree is some OTHER directory is a well-formed regular file too, and
1406
- # git then answers happily about that other tree at rc 0 (measured, #135). The
1401
+ # git then answers happily about that other tree at rc 0 (measured). The
1407
1402
  # block below closes that — this one only establishes the file is there to
1408
1403
  # examine.
1409
1404
  #
@@ -1432,9 +1427,9 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1432
1427
  # `git -C "$wt" rev-parse --show-toplevel` answers with the linkage's own
1433
1428
  # idea of $wt's working tree. Comparing it against $wt itself refuses every
1434
1429
  # shape that moves git's WORKING TREE away from $wt while $wt/.git still
1435
- # passes the `-f` gate above — #74/#115's walk-up (an absent, empty-directory,
1430
+ # passes the `-f` gate above — the walk-up shape (an absent, empty-directory,
1436
1431
  # or dangling-symlink .git) fails that gate and is refused there instead,
1437
- # never reaching this compare: #135's own repro, a hand-written .git naming
1432
+ # never reaching this compare. What it does refuse: a hand-written .git naming
1438
1433
  # a gitdir whose core.worktree is elsewhere, whether or not that gitdir is
1439
1434
  # named `.git`; and core.worktree set in the worktree's own config.worktree
1440
1435
  # under extensions.worktreeConfig, the .git file untouched (all measured, git
@@ -1447,9 +1442,9 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1447
1442
  # is no substitute either: `--show-prefix` is empty at rc 0 for both
1448
1443
  # core.worktree shapes above.
1449
1444
  #
1450
- # What this does NOT cover (#421): shapes that swap which git dir answers
1445
+ # What this does NOT cover: shapes that swap which git dir answers
1451
1446
  # while the working tree stays $wt. A .git naming a SIBLING worktree's admin
1452
- # dir (#189; copying one worktree's contents, .git included, over another
1447
+ # dir (copying one worktree's contents, .git included, over another
1453
1448
  # produces it), or a foreign git dir whose core.worktree points back at $wt.
1454
1449
  # `--show-toplevel` answers $wt for both, so the compare passes them. They
1455
1450
  # are stopped downstream, before anything changes: the status below reads
@@ -1459,8 +1454,8 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1459
1454
  # point back to .git/worktrees/<name>", measured). The cost is a dry run that
1460
1455
  # can call such a claim releasable and an --apply that then halts. Left
1461
1456
  # there on purpose: these shapes need a hand-copied .git or deliberate
1462
- # tampering, `git worktree` never writes one, and #421 ruled a stricter
1463
- # check here not worth its code.
1457
+ # tampering, `git worktree` never writes one, and a stricter check here was
1458
+ # ruled not worth its code.
1464
1459
  #
1465
1460
  # Compared as a DIRECTORY (`-ef`, same device and inode), never as a string,
1466
1461
  # or this false-refuses a HEALTHY worktree: `$wt` is the path `worktree list
@@ -1472,7 +1467,7 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1472
1467
  # PRECOMPOSED by the `core.precomposeunicode` git writes into every new repo
1473
1468
  # on macOS, while `--show-toplevel` answers the on-disk NFD bytes — visually
1474
1469
  # identical, byte-different, one directory (measured, git 2.50.1, Apple
1475
- # Git-155, #2094; reap.sh's copy of this compare, #2072). Under bash —
1470
+ # Git-155; reap.sh's copy of this compare compares as a directory too). Under bash —
1476
1471
  # macOS's own `/bin/sh` — `cd "$wt" && pwd -P` canonicalised only the
1477
1472
  # first: it echoes the spelling it was given, so a byte compare against it
1478
1473
  # refused every healthy NFD worktree at exit 2 there; dash's own `pwd -P`
@@ -1489,9 +1484,9 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1489
1484
  # trailing newline, so a `core.worktree` naming a sibling directory called
1490
1485
  # `$wt` plus a newline byte — git accepts one as an ordinary path character —
1491
1486
  # would otherwise name `$wt` itself and pass the redirect, the dirty check
1492
- # then reading that sibling's clean copy over $wt's work (measured, #2073;
1493
- # the shape no-undo-audit.sh closed the same way, #2040, and reap.sh's copy
1494
- # of this compare, #2042). The sentinel leaves `$(...)` only git's own
1487
+ # then reading that sibling's clean copy over $wt's work (measured;
1488
+ # the shape no-undo-audit.sh closed the same way, and reap.sh's copy
1489
+ # of this compare). The sentinel leaves `$(...)` only git's own
1495
1490
  # terminating newline to strip.
1496
1491
  #
1497
1492
  # A $wt whose own leaf was replaced by a symlink — never `git worktree add`'s
@@ -1500,7 +1495,7 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1500
1495
  # `-ef` follows the link, and `--show-toplevel` resolves through it to the
1501
1496
  # same real, possibly newline-suffixed, directory, so the two compare equal
1502
1497
  # and that case stays exactly as blocked — "not a directory" at exit 1 — never
1503
- # a fabricated "does not point at itself" mismatch at exit 2 (#2073).
1498
+ # a fabricated "does not point at itself" mismatch at exit 2.
1504
1499
  if [ -f "$wt/.git" ]; then
1505
1500
  toplevel=$(git -C "$wt" rev-parse --show-toplevel && echo x) ||
1506
1501
  die "cannot read the git repository at $wt (its .git file or the gitdir it names), so whether it holds uncommitted work is unknown"
@@ -1512,7 +1507,7 @@ if [ -n "$wt" ] && [ -d "$wt" ]; then
1512
1507
 
1513
1508
  # Same reason: folded-in stderr would be counted as uncommitted changes.
1514
1509
  #
1515
- # `-uall`: #730 (see reap.sh's branch sweep for the full explanation) — a
1510
+ # `-uall`: see reap.sh's branch sweep for the full explanation — a
1516
1511
  # bare `--porcelain` reads clean over a dirty tree under
1517
1512
  # `status.showUntrackedFiles = no`, releasing a claim whose only copy of
1518
1513
  # that work is the directory about to be deleted. The `git worktree remove`
@@ -1561,7 +1556,7 @@ if ! labels=$(gh issue view "$issue" --json labels --jq '.labels[].name'); then
1561
1556
  die "gh issue view $issue failed, so the in-progress label cannot be released"
1562
1557
  fi
1563
1558
  # grep's OWN scan failing (rc 2+) must not read as "no in-progress label":
1564
- # the same defect PR #1519 fixed in reap.sh's grep_probe (#1543). A bare
1559
+ # the same defect reap.sh's grep_probe guards against. A bare
1565
1560
  # `if … grep -qx …; then has_label=true; else has_label=false; fi` has room
1566
1561
  # for only two of grep's three `-q` outcomes — rc 0 matched, rc 1 none did,
1567
1562
  # rc 2+ the scan itself broke — so a scan that could not look would read
@@ -1597,7 +1592,7 @@ else
1597
1592
  printf '$ git worktree remove %s\n' "$wt" >&2
1598
1593
  # Measure on the REFUSAL only. git's two deletes are ordered, not atomic, so
1599
1594
  # a non-zero rc tells us a step failed and nothing about which — that is the
1600
- # whole of #208. A zero rc is different in kind: both deletes completed, and
1595
+ # whole of it. A zero rc is different in kind: both deletes completed, and
1601
1596
  # `Released` restates git's own success rather than inferring past a
1602
1597
  # failure. Re-measuring here would also make the happy path answerable by a
1603
1598
  # probe that can return Indeterminate, refusing releases that plainly worked.
@@ -1625,7 +1620,7 @@ else
1625
1620
  # including the delete, turns "recount, then hope nothing moved before
1626
1621
  # the call" into "delete only if nothing moved". Measured against $base,
1627
1622
  # not local HEAD, so it answers the safety question without
1628
- # reintroducing the staleness `-d` fails on (#760). The `git cherry` half
1623
+ # reintroducing the staleness `-d` fails on. The `git cherry` half
1629
1624
  # is deliberately not recounted: a commit that landed in the window is
1630
1625
  # ahead of $base by construction, and one cherry would mark `-` is
1631
1626
  # patch-equivalent to something already upstream.
@@ -1651,7 +1646,7 @@ else
1651
1646
  # separate git invocation, and nothing here can ask `update-ref` to verify
1652
1647
  # it atomically with the delete the way `-D` verified its own.
1653
1648
  #
1654
- # What that window can cost, per the ruling on #1330 (Q2): a checkout
1649
+ # What that window can cost, per the maintainer's ruling: a checkout
1655
1650
  # landing in it leaves that worktree holding a deleted branch, which
1656
1651
  # breaks the worktree. It cannot lose a commit. A commit made there before
1657
1652
  # the delete moves the ref off $tip, and the compare-and-swap below then
@@ -1673,7 +1668,7 @@ else
1673
1668
  # in this repo's own registry for it (a worktree `rm -rf`'d out from
1674
1669
  # under git), a listed path it cannot hand back to git byte for byte, or
1675
1670
  # a porcelain record naming neither `branch` nor `detached` at all — a
1676
- # worktree whose admin `HEAD` holds garbage, not a ref. #2218, ADR 0018
1671
+ # worktree whose admin `HEAD` holds garbage, not a ref.
1677
1672
  wt_listing || halt "cannot re-read the worktree list to check $branch before the delete: $wt_err"
1678
1673
  if wt_holding "refs/heads/$branch"; then cas_rc=0; else cas_rc=$?; fi
1679
1674
  case $cas_rc in
@@ -1688,7 +1683,7 @@ else
1688
1683
  # authorizes its own [gone] deletes with `git cherry` ALONE — not this
1689
1684
  # pairing. `-d` measures against HEAD and the branch's upstream, and a
1690
1685
  # claim has no upstream until its first push (claim-ticket.sh passes
1691
- # --no-track, #760), so `-d` falls back to local HEAD alone and refuses a
1686
+ # --no-track), so `-d` falls back to local HEAD alone and refuses a
1692
1687
  # pristine claim whenever local main is behind origin/main —
1693
1688
  # half-releasing it: worktree deleted, branch stranded, in-progress still
1694
1689
  # on the issue. Measured.