@feigi/fleet-ctl 0.0.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.
Files changed (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,482 @@
1
+ #!/bin/sh
2
+ # Per worktree: how many commits ahead of the base, and what is uncommitted.
3
+ #
4
+ # Run before dispatching a replacement for a killed member. The distinction that
5
+ # matters is committed-and-pushed vs committed-only vs uncommitted-in-the-worktree:
6
+ # only the last exists nowhere else, and a replacement told the wrong one will
7
+ # either redo finished work or destroy unfinished work.
8
+ #
9
+ # Read-only. Never exits non-zero for a dirty or absent worktree — that is the
10
+ # finding, not an error. Three states, never two: present-and-readable (real
11
+ # counts), established absent (a directory that really is not there — zero
12
+ # counts, a measurement), or unknown (anything this script could not actually
13
+ # look at — null counts, readable:false). A worktree that IS present but whose
14
+ # git commands fail (permissions, corrupt git dir), one behind an unreadable
15
+ # parent (a dropped mount, a chmod'd ancestor), and one whose .git linkage is
16
+ # missing (git would silently answer for the ENCLOSING repo instead, rc 0) are
17
+ # all the unknown state — none of them is ever silently ahead:0, dirty:0, which
18
+ # reads as "nothing here, safe to discard" and is indistinguishable from a
19
+ # genuinely empty worktree. #82, #128.
20
+ set -eu
21
+
22
+ # Byte semantics for the `awk` and `paste` below — this script runs no `tr`,
23
+ # no `sed` and no `grep`. Both are fed worktree paths and the file names
24
+ # `git status --porcelain` prints, which reach us from a fetched tree even
25
+ # where the local filesystem refuses to hold the name. `paste -sd, -` is the
26
+ # obvious one — fed `b\377ad.txt` then `plain.txt` it emits the single byte `b`
27
+ # under `en_US.UTF-8` and the whole pair under `C`, exiting 0 both times, a
28
+ # truncation carrying no stderr and no status. #582 measured the cost of
29
+ # leaving this ambient in no-undo-audit.sh: a truncated list reported as a
30
+ # clean, confident answer.
31
+ #
32
+ # `awk` used to be the immune one — measured byte-identical under
33
+ # `en_US.UTF-8` and `C` — and #617 ended that: `jesc` below turns git's octal
34
+ # escapes back into bytes with `sprintf("%c", n)`, and that IS locale-sensitive.
35
+ # Measured, `%c` with 195: gawk 5.4.1 emits the two-byte UTF-8 encoding of
36
+ # U+00C3 under `en_US.UTF-8` and the single byte \303 under `C`; BWK awk
37
+ # 20200816 emits the byte under both. gawk is what Linux CI runs, so without
38
+ # the pin every non-ASCII dirty filename would come back double-encoded there
39
+ # and correct on the developer's Mac.
40
+ #
41
+ # Safe as a global: nothing in this script sorts, folds case, or uses a `[a-z]`
42
+ # range or a POSIX class, so collation and case-folding — the two things
43
+ # `LC_ALL=C` otherwise changes — have nothing here to act on. "Nothing" is an
44
+ # inventory, not a hope: locale-pin-prose.test.mjs enforces it (#612), because
45
+ # this sentence shipped false in no-undo-audit.sh and a `sort` added below
46
+ # would otherwise leave every test in this suite green.
47
+ export LC_ALL=C
48
+
49
+ # Below the locale pin, not above it with `set -eu`: `unset` touches no
50
+ # byte-sensitive tool, but locale-pin-prose.test.mjs treats ANY line here that
51
+ # is not a comment, a blank, or `set -[eux]+` as work the pin must sit above,
52
+ # and refuses on principle rather than on this line's own behaviour. Same
53
+ # placement, same reason, as release-ticket.sh's copy.
54
+ #
55
+ # Both halves are measured on THIS script (#1020), and they break it in two
56
+ # different directions — which is why the line names both rather than the one
57
+ # that happened to be found first.
58
+ #
59
+ # GIT_DIR: every git call above the per-worktree loop is bare — `rev-parse
60
+ # --git-dir`, `rev-parse --verify "$base_rev"`, and the `worktree list` behind
61
+ # `wt_listing` — so an ambient one retargets the whole listing. Measured:
62
+ # standing in clone A with `GIT_DIR` naming clone B's `.git`, this script
63
+ # emits a full, confident array describing B's worktrees, at rc 0, with
64
+ # nothing on stderr to say the question was not the one asked. The fleet
65
+ # controller reads this report to decide whether a replacement member would
66
+ # REDO work or DESTROY it, and an answer about another checkout is the worst
67
+ # possible input to that decision.
68
+ #
69
+ # GIT_WORK_TREE: it outranks `-C`, so the `git -C "$wt" status --porcelain
70
+ # -uall` in the loop stops answering about `$wt`. Measured, on the fleet's own
71
+ # layout (`.worktrees/` gitignored, so the parent really is clean): a worktree
72
+ # holding an uncommitted file comes back `dirty: 0, dirtyFiles: [],
73
+ # readable: true` — a false CLEAN, at rc 0, indistinguishable from a worktree
74
+ # that genuinely holds nothing. Same shape as #730's `showUntrackedFiles=no`
75
+ # silence, reached through the environment instead of the config.
76
+ unset GIT_DIR GIT_WORK_TREE
77
+
78
+ NAME=worktree-audit
79
+ die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
80
+
81
+ # No positional argument (#525). A caller-supplied path was silently discarded
82
+ # — no `$#` check, no usage — so a missing worktree returned a full audit of
83
+ # every OTHER worktree at exit 0, first row the main checkout. Refuse loudly
84
+ # instead of adding a filter: this script's whole contract is "every worktree,
85
+ # every time", and refusing makes every existing caller correct rather than
86
+ # teaching the script a second, path-scoped one. Above the opening `[`, same as
87
+ # the json_lib guard below, so a refusal never emits a truncated array.
88
+ [ $# -eq 0 ] || die "takes no arguments; audits every worktree"
89
+
90
+ # The escaping helpers (#119). json.sh's header holds the sourcing contract and
91
+ # the measurements behind it. This script defines no exit 1 at all, so a bare 1
92
+ # out of it is a code its caller has no reading for. Placed here, above the
93
+ # opening `[`, so a missing library refuses before the array is started rather
94
+ # than truncating it.
95
+ json_lib="$(dirname "$0")/json.sh"
96
+ [ -r "$json_lib" ] || die "cannot read $json_lib — refusing to audit without the JSON escaping helpers"
97
+ # shellcheck source-path=SCRIPTDIR
98
+ # shellcheck source=json.sh
99
+ . "$json_lib" || die "$json_lib failed to load"
100
+
101
+ # The worktree readers (#551, #725). worktree.sh's header holds the sourcing
102
+ # contract and the measurements behind it, and json.sh's holds the `[ -r ]`
103
+ # reasoning both guards share. Above the opening `[` for the reason the json_lib
104
+ # guard is: a missing library must refuse before the array is started.
105
+ wt_lib="$(dirname "$0")/worktree.sh"
106
+ [ -r "$wt_lib" ] || die "cannot read $wt_lib — refusing to audit without the worktree readers"
107
+ # shellcheck source-path=SCRIPTDIR
108
+ # shellcheck source=worktree.sh
109
+ . "$wt_lib" || die "$wt_lib failed to load"
110
+ # One unknown state, one place: null counts, readable:false, one reason. Seven
111
+ # call sites below reach this function — #2220's admin-dir-unreadable arm
112
+ # among them — and differ in nothing but that reason, so one more added
113
+ # later cannot half-set the quadruple and emit a record whose counts
114
+ # contradict its own `readable` field. The MISSING branch stays spelled out —
115
+ # it is the one state with non-null counts, and looking different is the point.
116
+ unknown() { readable=false; ahead=null; dirty=null; files=""; note=; printf ' UNREADABLE: %s (%s)\n' "$wt" "$1" >&2; }
117
+
118
+ # A `detached` record may still be a worktree's own branch, held: a stopped
119
+ # rebase or bisect detaches HEAD and moves it — measured, git 2.50.1, a bisect
120
+ # on a claim branch lands HEAD on a commit `origin/main` already has — so a
121
+ # count from HEAD alone read such a worktree as `ahead:0, dirty:0`, the
122
+ # "nothing here" row, while the branch it holds carries unpushed commits.
123
+ # `wt_op_state` (#2218) reads the held branch out of the admin dir; this sets
124
+ # `held` to those refs, relabels `short` with their short names and `note`
125
+ # with the operation, for the count below to run over HEAD and `held`
126
+ # together: that union is the branch's own commits plus whatever a rebase
127
+ # has replayed so far onto HEAD alone. Attached rows are untouched. 1: the
128
+ # admin dir cannot be read, so whether a branch is held is unknown. #2220
129
+ #
130
+ # A bisect started from a detached HEAD writes that HEAD's SHA, not a branch,
131
+ # into BISECT_START, and `wt_op_state` still returns it as `refs/heads/<sha>`
132
+ # (its own header says why). That names no branch: dropped here, so the row
133
+ # stays today's DETACHED rather than going unreadable over a ref that never
134
+ # existed. A real held branch that no longer resolves is kept, and fails the
135
+ # count below into the unknown state — never a zero.
136
+ op_held() {
137
+ held=
138
+ [ "$br" = DETACHED ] || return 0
139
+ wt_op_state "$wt" || return 1
140
+ for h in $wt_op_held; do
141
+ sha=$(git -C "$wt" rev-parse --verify "${h#refs/heads/}^{commit}" 2>/dev/null) || sha=
142
+ # A bisect-from-detached-HEAD write drops here because `$h` never names a
143
+ # real ref (#2218: it is HEAD's own SHA reread as `refs/heads/<sha>`). The
144
+ # sha=name match alone cannot tell that case apart from a real branch that
145
+ # happens to be NAMED as the 40-hex string it also resolves to — so the
146
+ # second, structural check is what actually distinguishes them: a real
147
+ # `refs/heads/<name>` ref resolves here, a phantom one does not.
148
+ if [ "$sha" = "${h#refs/heads/}" ] && ! git -C "$wt" rev-parse --verify --quiet "$h" >/dev/null 2>&1; then
149
+ continue
150
+ fi
151
+ case " $held " in *" $h "*) ;; *) held="${held:+$held }$h" ;; esac
152
+ done
153
+ [ -n "$held" ] || return 0
154
+ short=
155
+ for h in $held; do short="${short:+$short }${h#refs/heads/}"; done
156
+ # `$wt_op` names only the LAST admin marker `wt_op_state` found (#2218's own
157
+ # last-wins scan), so it cannot tell a worktree with ONE operation from one
158
+ # with a rebase stopped and a bisect then started on top of it — both leave
159
+ # BISECT_LOG present and `wt_op=BISECT_LOG`, even though the branch actually
160
+ # kept in `$held` came from the rebase. `$wt_op_held` (raw, pre-filter) is
161
+ # the signal that does not collapse: more than one entry means more than
162
+ # one admin source contributed, which `wt_op` alone cannot say. Measured,
163
+ # git 2.50.1: a stopped rebase with a bisect started on the resulting
164
+ # detached HEAD leaves rebase-merge/head-name AND BISECT_START both
165
+ # present, `wt_op_held` two entries wide, `wt_op` still `BISECT_LOG`.
166
+ case $wt_op_held in
167
+ *" "*) note=" (rebase and bisect both in progress: HEAD detached, ahead counts HEAD and the held branch)" ;;
168
+ *)
169
+ case $wt_op in
170
+ BISECT_LOG) op=bisect ;;
171
+ *) op=rebase ;;
172
+ esac
173
+ note=" (mid-$op: HEAD detached, ahead counts HEAD and the held branch)"
174
+ ;;
175
+ esac
176
+ }
177
+
178
+ base=${BASE_REF:-origin/main}
179
+ # Only a remote-tracking ref is accepted — the accept-list reap.sh:156 (#924)
180
+ # and release-ticket.sh:229 (#1320) both carry, and this script had none of.
181
+ # Unlike those two, this script is audit-only: it prints ahead/dirty counts
182
+ # to stdout and never itself writes to git state, so a fleet controller
183
+ # acting on a wrong number is the whole blast radius, not this process. That
184
+ # does not make the list optional, because the qualify step below
185
+ # unconditionally prepends `refs/remotes/` to whatever $base is. A spelling
186
+ # that used to resolve fine before this fix — a bare `main`, a raw 40-char
187
+ # SHA, `HEAD`, `refs/heads/main` — turns into a ref nothing asked to exist
188
+ # (`refs/remotes/main`, `refs/remotes/<sha>`, …) and the resolve below dies.
189
+ # Restricting the input first turns that crash into a refusal naming the
190
+ # real constraint, not a "$base does not resolve" that blames a guess for a
191
+ # qualification this script chose to make.
192
+ case "$base" in
193
+ origin/*|refs/remotes/*) ;;
194
+ *) die "BASE_REF must be a remote-tracking ref, got '$base'";;
195
+ esac
196
+
197
+ # release-ticket.sh (#1320) found the same bug in the same default: `origin/
198
+ # main` is a SHORTHAND, and git resolves a shorthand through its own
199
+ # disambiguation order (gitrevisions: refs/<name>, refs/tags/<name>,
200
+ # refs/heads/<name>, refs/remotes/<name>, …), in which refs/remotes/origin/
201
+ # main comes LAST. A local TAG literally named `origin/main` — `git tag
202
+ # origin/main refs/heads/<branch>` — outranks the real remote-tracking
203
+ # branch, and every measurement against the bare shorthand then answers
204
+ # about the tag's target instead: `ahead` silently reads 0 against a
205
+ # worktree that genuinely carries unpushed work, exactly the "nothing here"
206
+ # signal #82, #128 established this script's readers trust.
207
+ #
208
+ # The fix is to stop MEASURING against the shorthand: qualify it to the full
209
+ # refs/remotes/ path, where there is nothing left to disambiguate, unless it
210
+ # is already qualified. The accept-list above is what makes this qualify
211
+ # step safe rather than a guess — #924 recorded qualifying as unavailable
212
+ # without one, because BASE_REF could otherwise name a tag, a SHA or a local
213
+ # branch, leaving no prefix that is always correct. $base itself is left
214
+ # unqualified — it never appears in this script's JSON output, only in
215
+ # `die` text, where the shorthand spelling is what an operator expects to
216
+ # read.
217
+ case "$base" in
218
+ refs/remotes/*) base_rev=$base;;
219
+ *) base_rev="refs/remotes/$base";;
220
+ esac
221
+ git rev-parse --git-dir >/dev/null 2>&1 || die "not inside a git repository"
222
+ git rev-parse --verify "$base_rev" >/dev/null || die "$base does not resolve"
223
+
224
+ echo "\$ git worktree list --porcelain -z" >&2
225
+
226
+ # Read above the opening `[`, and its failure is a `die` for the reason the
227
+ # library guards are: this script had NO status check on the listing at all, so
228
+ # a git that could not run emitted `[]` — an empty audit, indistinguishable from
229
+ # a repo with no worktrees, which is the answer the fleet controller reads to
230
+ # decide whether a replacement member would redo work or destroy it.
231
+ wt_listing || die "$wt_err"
232
+
233
+ first=1
234
+ printf '['
235
+ # The worktree path is the whole rest of its line, never awk's $2:
236
+ # `git worktree list --porcelain` prints it raw, so a checkout living under a
237
+ # directory with a space in it — ordinary on macOS — was otherwise truncated
238
+ # at the first one, and every consumer below given a wrong, nonexistent path.
239
+ # The branch line's $2 stays: a ref name cannot contain a space.
240
+ #
241
+ # A newline in that path used to end the record before `substr($0,10)` could
242
+ # read past it, AND end the `read -r` line below — two truncations, and the loop
243
+ # saw a shorter path than even the awk had. `wt_listing` swaps both separators
244
+ # before either stage runs, so the path arrives on one line; `nl_path` below is
245
+ # what refuses to stat it. #551
246
+ #
247
+ # The path goes LAST, and the branch first, because the tab this awk delimits
248
+ # with is itself a byte a path may hold — and `read -r wt br` split such a path
249
+ # at it, reporting a truncated `MISSING on disk` for a worktree that is present
250
+ # and clean, with the tail of its path swallowed into the branch field. That is
251
+ # #551's own defect shape surviving in #551's own rewrite. With the path last,
252
+ # `read` assigns the whole remainder of the line to the final name whatever it
253
+ # holds, so no byte in a path can split it. The branch cannot take that slot: a
254
+ # ref name rejects a tab outright, which is what makes it safe to read first.
255
+ printf '%s\n' "$wt_list" | awk '/^worktree /{w=substr($0,10)} /^branch /{print $2"\t"w} /^detached$/{print "DETACHED\t"w}' |
256
+ while IFS="$(printf '\t')" read -r br wt; do
257
+ short=${br#refs/heads/}
258
+ note=
259
+ # FIRST, because every arm below stats `$wt` and none of them can: the byte
260
+ # `wt_listing` substituted stands in for a newline, so this path does not name
261
+ # the file git named. Reported rather than skipped — jstr renders the
262
+ # substituted byte as a space, so the entry still names which worktree could
263
+ # not be audited, whole, with the byte neutralised. The same ceiling
264
+ # inflight.sh's probe 3 records, and here it costs a diagnosis rather than a
265
+ # verdict. #551
266
+ if nl_path "$wt"; then
267
+ unknown "path holds a newline — git's own listing cannot be read back to a name this script can stat"
268
+ elif [ -d "$wt" ]; then
269
+ # Establish the .git linkage exists before trusting anything git says
270
+ # through it. Delete a worktree's .git file outright — directory and every
271
+ # uncommitted file still on disk — and `git -C` does not fail: it walks UP
272
+ # to the enclosing repo and reports THAT repo's status at rc 0, which the
273
+ # chain below would otherwise believe. Only a SEARCHABLE $wt lacking a
274
+ # `.git` regular file is a measured absence; an unsearchable $wt is left to
275
+ # the git commands below, which fail on their own and land in the existing
276
+ # unreadable branch — this must not invent a second, weaker guess for it.
277
+ # `.git` is a regular FILE for every linked worktree (`git worktree add`
278
+ # always writes one) but a DIRECTORY for the main checkout, which this
279
+ # script also lists and audits. reap.sh reaches the main checkout too —
280
+ # `git worktree list --porcelain` emits a `branch refs/heads/...` line for
281
+ # it, so a `[gone]` branch checked out there binds reap.sh's own `$wt` to
282
+ # it — and handles that shape explicitly before its own `-f` linkage guard
283
+ # (#128 reference shape) rather than by construction. Here the guard itself
284
+ # must accept both: a real git dir always has `HEAD` sitting directly in
285
+ # it, and an empty stand-in directory or a dangling symlink — the two
286
+ # shapes a broken/deleted linkage takes, and what leaks the parent's status
287
+ # at rc 0 — has neither. `-x "$wt"` gates it for the reason release-ticket.sh
288
+ # gives its own guard: an unsearchable $wt must not be misread as "no
289
+ # linkage established" — leave it to the git commands below, which fail on
290
+ # their own and land in the existing unreadable branch.
291
+ # shellcheck disable=SC2086 # `$held` below, split on purpose; see there
292
+ if [ -x "$wt" ] && [ ! -f "$wt/.git" ] && [ ! -f "$wt/.git/HEAD" ]; then
293
+ unknown "no .git linkage — git would answer for the enclosing repo, not this worktree"
294
+ # Below the linkage guard, never above it: `wt_op_state` asks git FROM
295
+ # `$wt`, which without a linkage answers for the enclosing repo. #2220
296
+ elif ! op_held; then
297
+ unknown "cannot read its admin dir — a rebase or bisect there may hold a branch HEAD no longer points at"
298
+ # Chain on `&&`, not `|| echo 0`: a piped `wc -l` always exits 0 even when
299
+ # the git command feeding it failed, so a fallback tacked onto the pipe
300
+ # never fires and a permissions/corruption failure reads as "0 ahead, 0
301
+ # dirty" — indistinguishable from a genuinely clean worktree.
302
+ #
303
+ # `-uall`: #730 (see reap.sh's branch sweep for the full explanation) — a
304
+ # bare `--porcelain` reads `dirty: 0` over a dirty tree under
305
+ # `status.showUntrackedFiles = no`, and the `&&` chain above, built
306
+ # precisely so a failure to look is never scored as clean, cannot see it
307
+ # either, because the status IS 0.
308
+ #
309
+ # `-uall` over `-unormal` here specifically, unlike reap.sh's `--ignored`
310
+ # reason-string probe (which switched to `-unormal`, same PR): this
311
+ # report's `dirtyFiles[]` is what a fleet controller reads to decide
312
+ # whether a replacement member would REDO work or DESTROY it, and #617
313
+ # already invested in translating git's C-quoting to JSON precisely so
314
+ # `dirtyFiles[]` round-trips to the real path on disk — infrastructure
315
+ # that exists to let the array name individual files, not just
316
+ # directories. `-unormal` would collapse an untracked directory to one
317
+ # entry, silently dropping that granularity for whoever reads this
318
+ # array. Proven, not just asserted: see the nested-directory test in
319
+ # worktree-audit.test.mjs.
320
+ #
321
+ # `$held` unquoted: a space-separated list of full `refs/heads/` names,
322
+ # empty for every attached row, and a ref name holds no space or glob byte.
323
+ elif ahead=$(git -C "$wt" rev-list --count "$base_rev"..HEAD $held 2>/dev/null) \
324
+ && status_out=$(git -C "$wt" status --porcelain -uall 2>/dev/null); then
325
+ dirty=$(printf '%s\n' "$status_out" | awk 'NF{c++} END{print c+0}')
326
+ # substr, not $2: a dirty file's own name may hold a space — "XY " is
327
+ # always exactly three bytes in porcelain v1, so the path starts at the
328
+ # fourth. Same truncation as the worktree path above, one caller down.
329
+ #
330
+ # git C-quotes the path itself (wraps it in its own "…", backslash-
331
+ # escaped) whenever it holds a space or other unusual byte — measured,
332
+ # git 2.50.1 — and C-quoting is NOT JSON escaping. `\303\251` for the `é`
333
+ # in `café.txt` is an invalid JSON escape, so ONE such file made the whole
334
+ # array unparseable and cost the caller every other worktree's entry too.
335
+ # #617 settled the open half of that: TRANSLATE git's form into JSON's, so
336
+ # `dirtyFiles[]` round-trips to the real name on disk. The alternative
337
+ # #617 weighed — JSON-escape the C-quoted text itself — parses, but hands
338
+ # a fleet controller a string it cannot pass back to the filesystem, which
339
+ # is the same defect `nl_path` above refuses rather than reports.
340
+ #
341
+ # Not `--porcelain -z` (git's raw, unquoted form) even though it would
342
+ # delete the rename scan below: no shell variable holds a NUL and no awk
343
+ # program holds one either (worktree.sh states that measurement), so it
344
+ # buys a temp file and a `tr` swap, and a filename holding a real newline
345
+ # then becomes indistinguishable from two files — a regression, since
346
+ # C-quoting keeps every path on one line, which is also what keeps the
347
+ # `dirty` count above honest.
348
+ #
349
+ # Not `jstr`: the value arriving here is already an ESCAPED form, not the
350
+ # raw bytes jstr's rules are written for, and it arrives one per line
351
+ # inside awk where no shell function is reachable. The two agree on where
352
+ # it matters — `jesc` replaces the same C0 bytes json.sh's `tr` replaces
353
+ # (\001-\007 \013 \016-\037 → space), plus \000: `tr`'s range starts at
354
+ # \001 because a shell string cannot hold a real NUL byte to feed it, but
355
+ # `jesc` meets \000 as three literal digit characters (git's own octal
356
+ # spelling of the byte), never as an embedded NUL, so the exclusion that
357
+ # protects `tr` does not apply here. Emits the same five short forms, and
358
+ # leaves \177 alone (#146).
359
+ if jfiles=$(printf '%s\n' "$status_out" | awk '
360
+ # git C-quoting to JSON, byte for byte. An UNQUOTED path is returned
361
+ # untouched: git quotes for `"`, `\`, any control byte and any byte with
362
+ # the high bit set, so what it left bare is printable ASCII with nothing
363
+ # JSON needs escaped. `index("01234567", c)`, not a `[0-7]` bracket range
364
+ # — locale-pin-prose.test.mjs scans this file for collation ranges and a
365
+ # range here would read as one (#612). git spells an octal escape with
366
+ # exactly three digits, so the two lookahead reads below always land.
367
+ # jesc_err is a global, deliberately never reset: an unrecognized escape
368
+ # exits the awk program (below) before a second call could matter, so
369
+ # nothing here ever needs to un-set it.
370
+ function jesc(p, out,i,c,n) {
371
+ if (substr(p,1,1) != "\"") return p
372
+ i=2
373
+ while (i < length(p)) {
374
+ c=substr(p,i,1); i++
375
+ if (c != "\\") { out=out c; continue }
376
+ c=substr(p,i,1); i++
377
+ if (index("01234567", c) > 0) {
378
+ n=(c*64) + (substr(p,i,1)*8) + substr(p,i+1,1); i+=2
379
+ out = out (n < 32 ? " " : sprintf("%c", n))
380
+ } else if (c=="a" || c=="v") out=out " "
381
+ else if (index("bfnrt\\\"", c) > 0) out=out "\\" c
382
+ # An escape letter git 2.50.1 never emits (the #617 enumeration
383
+ # above is exhaustive against it) — dead code under real git, same
384
+ # as the header states. Fail loud rather than pass the byte through
385
+ # unescaped: this file has one rule above every other one, never
386
+ # silently report a wrong answer as a clean one, and a
387
+ # silently-dropped backslash here is exactly that, one dirtyFiles[]
388
+ # entry at a time.
389
+ else { jesc_err=c; return out }
390
+ }
391
+ return out
392
+ }
393
+ NF{
394
+ p=substr($0,4)
395
+ # A rename/copy line is `<src> -> <dst>`; emit the DESTINATION only —
396
+ # the source path no longer exists, so reporting it names a file that
397
+ # is not there. Gate on the X status byte (R/C), never on a literal
398
+ # " -> ": a filename may legally hold one, and splitting on that emits
399
+ # two broken halves of a name git never split. git C-quotes any path
400
+ # holding a space — measured, git 2.51 — so an UNQUOTED src cannot
401
+ # contain the delimiter, while a QUOTED one can and ends at its own
402
+ # unescaped closing quote, which the scan below finds. Reading the
403
+ # whole rename line as one path put the quotes git had already added
404
+ # inside the pair added below: one such file made the WHOLE payload
405
+ # unparseable, taking every other worktree entry down with it (#82).
406
+ if (substr($0,1,1) ~ /[RC]/) {
407
+ if (substr(p,1,1) == "\"") {
408
+ for (i=2; i<=length(p); i++) {
409
+ c=substr(p,i,1)
410
+ if (c=="\\") i++
411
+ else if (c=="\"") break
412
+ }
413
+ if (substr(p,i+1,4) == " -> ") p=substr(p,i+5)
414
+ } else {
415
+ i=index(p," -> ")
416
+ if (i) p=substr(p,i+4)
417
+ }
418
+ }
419
+ e=jesc(p)
420
+ # Checked here, not after the pipeline: `awk ... | paste -sd, -` would
421
+ # otherwise report the PASTE exit status, and paste never fails on
422
+ # this input — the jesc_err below would kill awk with nothing
423
+ # downstream ever finding out (#617 suggestion 3).
424
+ if (jesc_err != "") {
425
+ print "jesc: unrecognized C-quote escape \\" jesc_err > "/dev/stderr"
426
+ exit 1
427
+ }
428
+ print "\"" e "\""
429
+ }'); then
430
+ readable=true
431
+ files=$(printf '%s\n' "$jfiles" | paste -sd, -)
432
+ else
433
+ unknown "jesc: unrecognized C-quote escape — refusing a corrupted dirtyFiles entry"
434
+ fi
435
+ else
436
+ unknown "git rev-list/status failed — treat as unknown, not empty"
437
+ fi
438
+ elif gone "$wt"; then
439
+ readable=false
440
+ ahead=0; dirty=0; files=""
441
+ printf ' MISSING on disk: %s\n' "$wt" >&2
442
+ elif [ -e "$wt" ] || [ -L "$wt" ]; then
443
+ # `-L` beside `-e`, never folded into it: every other `test` primary STATS,
444
+ # so a DANGLING symlink is `-e` false and `-L` true, and without this it fell
445
+ # past both this arm and `gone` into "an ancestor could not be read" — prose
446
+ # that is false of a path whose every ancestor was read fine. `gone` now
447
+ # refuses it too (#725), so this arm is where it lands, and the diagnosis
448
+ # below is true of it: a link IS there, and it is not a directory. The
449
+ # wording stays hedged deliberately — a dangling worktree link is rc-0
450
+ # residue OR release-ticket.sh's rc-255 halt path with the claim still live,
451
+ # and only the hedge is true of both (#728).
452
+ #
453
+ # `-d` false does not mean "not there". A registered worktree path replaced
454
+ # by a regular file, a symlink to one, or a FIFO is all three still LISTED
455
+ # by git (with its `branch` line, so this loop still sees it) and reads
456
+ # perfectly — measured, all three land here. Saying an ancestor could not
457
+ # be read about a path whose every ancestor was read sends a debugger at
458
+ # permissions that are fine. Safe after `gone`, never before: `gone()`
459
+ # requires `[ ! -e "$1" ]`, so reaching here with `-e` true means it
460
+ # already answered false. The state is the same unknown either way — only
461
+ # the reported cause differs.
462
+ unknown "exists but is not a directory"
463
+ else
464
+ unknown "cannot tell whether it exists — an ancestor could not be read"
465
+ fi
466
+ printf ' %s branch=%s ahead=%s dirty=%s%s\n' "$wt" "$short" "$ahead" "$dirty" "$note" >&2
467
+ [ "$first" = 1 ] || printf ','
468
+ first=0
469
+ # `$wt` and `$short` are both reachable, by different routes: a branch name
470
+ # accepts a `"` (git rejects `\` in a ref), while a worktree path is a
471
+ # filename and accepts both. This script's whole output is one array, so a
472
+ # single unescaped byte costs the caller every entry, not just this one.
473
+ # `$files` is NOT wrapped here: its elements arrive already quoted and already
474
+ # JSON-escaped, by `jesc` in the `files=` awk above (#617).
475
+ # `die` rather than a null field, unlike reap.sh: nothing has been mutated
476
+ # here, so refusing costs no record of work already done.
477
+ wt_j=$(jstr "$wt") && short_j=$(jstr "$short") \
478
+ || die "could not escape the entry for $wt"
479
+ printf '{"worktree":"%s","branch":"%s","ahead":%s,"dirty":%s,"dirtyFiles":[%s],"readable":%s}' \
480
+ "$wt_j" "$short_j" "$ahead" "$dirty" "$files" "$readable"
481
+ done
482
+ printf ']\n'