@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,79 @@
1
+ import { test } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { readFileSync } from "node:fs";
4
+ import { join } from "node:path";
5
+ import { between, phrase, stripHashGutter } from "./prose-pin.mjs";
6
+
7
+ // #346 asked for one thing that no behaviour test can hold: that the fate of
8
+ // the per-transport knobs be DECIDED rather than left implicit. The watchdog
9
+ // bounds every transport, which makes ConnectTimeout, the ServerAlive pair and
10
+ // the lowSpeed keys redundant AS THE BOUND — so keeping them is a choice, and a
11
+ // choice with no reason written beside it decays into an accident nobody dares
12
+ // touch. The reason is the artifact; this file is what keeps it.
13
+ //
14
+ // A pair, like inflight-ssh-precedence-prose.test.mjs's. The positive pins
15
+ // carry the decision and its grounds; the negative pin refuses the wording that
16
+ // was true before the watchdog landed and is a lie after it. Neither holds
17
+ // alone — the positive pins survive a stale "this is still open" sentence
18
+ // spliced back in beside them, and the negative pin survives the whole
19
+ // rationale being deleted.
20
+ //
21
+ // THE CEILING: presence pins over a bounded slice. Text spliced INSIDE a pinned
22
+ // clause reddens them; a new sentence appended beside one does not. Reflow stays
23
+ // green by design — the words are pinned, not their layout.
24
+ const NET = readFileSync(join(import.meta.dirname, "net.sh"), "utf8");
25
+
26
+ // Bounded by the http paragraph's own opening and by the first construct that
27
+ // follows the comment block. net_git's is the only comment in net.sh that
28
+ // discusses http transport options, but the bounds are what stop a later block
29
+ // elsewhere from satisfying these pins with this clause gutted.
30
+ const httpRationale = () =>
31
+ stripHashGutter(
32
+ between(
33
+ NET,
34
+ "# http: lowSpeedLimit/lowSpeedTime is git's (curl's) own bound",
35
+ "net_base_ssh=$(git config --get core.sshCommand",
36
+ "net.sh",
37
+ ),
38
+ );
39
+
40
+ // The negative pins get a WIDER slice than the positive ones, and that is the
41
+ // whole point of separating them. The stale sentence this PR deleted lived in
42
+ // the ssh paragraph, above the http heading — so run over `httpRationale` the
43
+ // two `doesNotMatch` pins below missed it entirely: measured, reinserting
44
+ // "Closing that needs a bound outside git … An https origin can still hold a
45
+ // fleet slot" into the ssh paragraph left both of them green. A negative pin
46
+ // scoped narrower than the prose it forbids forbids nothing. The positive pins
47
+ // stay on the narrow slice, where a bound at both ends is what stops an
48
+ // unrelated block from satisfying them.
49
+ const transportRationale = () =>
50
+ stripHashGutter(
51
+ between(
52
+ NET,
53
+ "# ssh: BatchMode=yes refuses any interactive prompt",
54
+ "net_base_ssh=$(git config --get core.sshCommand",
55
+ "net.sh",
56
+ ),
57
+ );
58
+
59
+ test("net_git's comment states that the per-transport knobs are kept, and why", () => {
60
+ const text = httpRationale();
61
+ assert.match(text, phrase("stay anyway, and that is a decision rather than an oversight"),
62
+ "#346 required the knobs' fate to be stated outright — a reader must not have to infer it from the fact that the lines are still there");
63
+ assert.match(text, phrase("fails earlier than the watchdog and in git's own words"),
64
+ "the first ground for keeping them: git's own diagnostic is the more useful thing to read, and the watchdog can only report that a budget elapsed");
65
+ assert.match(text, phrase("would make every ssh stall wait out the full budget"),
66
+ "the second ground, and the one that makes removal an actual regression rather than a wash");
67
+ });
68
+
69
+ // The negative half. Before the watchdog, this comment closed by saying the
70
+ // gap was still open and named the issue that would close it. That sentence is
71
+ // now false, and false in the most expensive direction: it would send the next
72
+ // reader off to implement the watchdog that the same comment block introduces.
73
+ test("net_git's comment no longer defers the bound to a ticket net.sh now carries", () => {
74
+ const text = transportRationale();
75
+ assert.doesNotMatch(text, phrase("Closing that needs a bound outside git"),
76
+ "the bound is no longer needed, it is present — this wording describes the tree as it stood before the watchdog");
77
+ assert.doesNotMatch(text, /can still hold a fleet slot/,
78
+ "an https origin cannot: the watchdog bounds it whatever the transport does, which is what inflight.test.mjs measures against a silent listener");
79
+ });
package/scripts/net.sh ADDED
@@ -0,0 +1,409 @@
1
+ # shellcheck shell=sh
2
+ # The fleet's bounded, prompt-suppressed git transport (#92, #346, #347).
3
+ # Sourced, never executed — no shebang, and the `shell=sh` directive above is
4
+ # what tells shellcheck what to check it as.
5
+ #
6
+ # Source it as:
7
+ #
8
+ # net_lib="$(dirname "$0")/net.sh"
9
+ # [ -r "$net_lib" ] || die "cannot read $net_lib"
10
+ # # shellcheck source-path=SCRIPTDIR
11
+ # # shellcheck source=net.sh
12
+ # . "$net_lib" || die "$net_lib failed to load"
13
+ #
14
+ # The `[ -r ]` is not belt-and-braces; json.sh's header holds the measurements
15
+ # behind that shape and they apply here unchanged — `.` is a POSIX special
16
+ # builtin, so failing to open its operand aborts a non-interactive shell before
17
+ # any `||` on the line can run.
18
+ #
19
+ # WHY A LIB. #346 landed this mechanism inside inflight.sh's probe 2, for the
20
+ # one call that probe makes. Every other unattended `git` network call in the
21
+ # fleet — release-ticket.sh's pushed-branch lookup, and the fetches in
22
+ # prove-merge.sh, reap.sh and verify-sha.sh — still ran raw, so each of them
23
+ # could prompt on a credential or a host key, or stall on a transport that
24
+ # connects and then goes quiet, holding a fleet slot indefinitely (#347). The
25
+ # alternative considered was copying the transport flags to each call site; it
26
+ # is what this file exists to avoid, and it would not have bounded the connect
27
+ # phase in any case, since git exposes no knob for it. So the mechanism moved
28
+ # here whole and probe 2 became its first caller rather than its owner.
29
+ #
30
+ # `gh` calls are deliberately NOT routed through this. Measured during the
31
+ # PR #332 review, `gh issue view` against a silent listener failed on its own at
32
+ # 10.0s with `net/http: TLS handshake timeout` — `gh` is already bounded, and
33
+ # wrapping it would buy a second bound over the first.
34
+ #
35
+ # `LC_ALL=C` is a per-command prefix below, never an export, for the reason
36
+ # json.sh gives: prove-merge.sh and verify-sha.sh do not pin the locale, and
37
+ # exporting from a sourced lib would silently re-locale every other tool in them.
38
+
39
+ # net_budget <default> <override> — print the budget a call gets, in seconds.
40
+ #
41
+ # The override exists so the tests can buy a short budget instead of paying the
42
+ # default one per case. It can only ever SHORTEN: a knob that could lengthen it
43
+ # would be one more way for configuration to remove the bound, which is the
44
+ # defect the ssh half of #346 reports, and reproducing it here to be convenient
45
+ # would be its own bug. A value that is not a positive integer is not an error
46
+ # and not a bound either — the default stands.
47
+ #
48
+ # `??????*` is that last clause holding for a digit string too large for the
49
+ # shell's integer. Without it `[` is handed the value and contradicts the
50
+ # sentence above out loud: measured, `sh` says `[: 99999999999999999999:
51
+ # integer expression expected` and dash says `[: Illegal number:` — a raw
52
+ # diagnostic naming a line number rather than the variable, on the same stderr
53
+ # that carries the caller's own reasons. Six digits, not twenty: anything from
54
+ # 100000 up was going to be ignored by the `-lt` below regardless, so the arm
55
+ # costs no reachable value and leaves the five-digit forms `[` reads correctly
56
+ # (029 among them) taking the same path they always did.
57
+ #
58
+ # The caller passes the override's VALUE, not its name, so each script keeps its
59
+ # own env var and the one this file would otherwise impose on all of them does
60
+ # not exist. `printf`, not `echo`: the value reaches here as raw environment.
61
+ net_budget() {
62
+ net_budget_v=$1
63
+ case ${2:-} in
64
+ '' | *[!0-9]* | ??????*) : ;;
65
+ *) if [ "$2" -gt 0 ] && [ "$2" -lt "$net_budget_v" ]; then net_budget_v=$2; fi ;;
66
+ esac
67
+ printf '%s' "$net_budget_v"
68
+ }
69
+
70
+ # net_fetch_budget — print the budget (seconds) a fetch call gets. No
71
+ # arguments: the default and the override variable both live here, so the one
72
+ # thing every fetch call site does is ask.
73
+ #
74
+ # 300s, and the number is chosen against the FALSE FAILURE, not against the
75
+ # stall: this fetch moves objects rather than refs, so a cold or large one can
76
+ # legitimately run for minutes, and a bound that turns a working slow link into
77
+ # exit 2 is worse than the hang it replaces — exit 2 is a verdict the controller
78
+ # acts on. Well above any healthy incremental fetch, and still a bound.
79
+ # `FLEET_NET_TIMEOUT` is the shorten-only override the fleet's fetches share;
80
+ # the rule is net_budget's, in net.sh.
81
+ net_fetch_budget() {
82
+ net_budget 300 "${FLEET_NET_TIMEOUT:-}"
83
+ }
84
+
85
+ # Kill $1 and everything descended from it. Killing the named process alone is
86
+ # not enough and not a near miss: git hands the transport to a helper, and that
87
+ # helper inherits this script's stderr. Measured against the accept-then-silent
88
+ # listener, killing only the `ls-remote` process left a `git remote-https`
89
+ # holding that pipe — the script had already written its answer and exited, and
90
+ # the caller still sat until its own cap expired, reading as a hang in a script
91
+ # that had in fact terminated. So the subtree is the unit, not the process.
92
+ #
93
+ # A process group would say this in one signal, but `set -m` is how a POSIX
94
+ # shell asks for one and it is not available where this runs: measured, dash
95
+ # with no controlling terminal answers "can't access tty; job control turned
96
+ # off" and the group kill then fails, and dash is `/bin/sh` on the Linux this
97
+ # suite runs under.
98
+ #
99
+ # The snapshot is taken BEFORE anything is signalled, because killing the root
100
+ # reparents its children and the links this walk follows are gone by then.
101
+ #
102
+ # Ceiling: with no `ps` to read, this falls back to the named process alone and
103
+ # a helper can survive it. That is the pre-#346 behaviour for that one case, not
104
+ # a new failure, and it is preferred over signalling a set derived from nothing.
105
+ # But it is not silent: the fallback records itself in $net_wdfile so the reason
106
+ # printed downstream can say the bound may not have held. A degraded kill that
107
+ # reads exactly like a clean one is the defect #346 asks this script not to
108
+ # have — measured, `ps` shimmed to exit 127 produced byte-identical stderr to
109
+ # the healthy run while a `git remote-https` survived and held the caller for
110
+ # its whole cap. `${net_wdfile:-/dev/null}` because net_kill_tree also runs
111
+ # before that file exists and on the path where mktemp is not reached at all.
112
+ #
113
+ # TERM then KILL, with no pause between them: a descendant that traps TERM
114
+ # otherwise holds the fetch's inherited stderr and the caller hangs past the
115
+ # budget anyway — measured against a GIT_SSH_COMMAND wrapper doing `trap '' TERM`,
116
+ # the caller sat out its full 30s backstop with the script long since exited.
117
+ # A `sleep 1` between the two signals, the obvious shape, does NOT work here:
118
+ # the watchdog subshell is itself killed through this same function while it
119
+ # would be inside that sleep, so the KILL never lands. Which signal git actually
120
+ # dies of is no longer load-bearing — $net_wdfile, not the exit status, is
121
+ # what says the watchdog fired.
122
+ #
123
+ # The `do { … } while (grew)` fixpoint is not decoration. `for (p in parent)`
124
+ # visits keys in awk's own hash order, so a single pass misses any descendant
125
+ # the iteration reaches before its own parent has been marked. `ps -A` prints
126
+ # parents first, which is exactly why every end-to-end case here stays green on
127
+ # that mutant.
128
+ #
129
+ # What holds it is the descending-pid chain in net.test.mjs's net_kill_tree
130
+ # case — each child's pid BELOW its parent's, the shape pid wraparound produces.
131
+ # Feeding the rows in a different order does not hold it: the hash order is not
132
+ # the input order, and measured, the same key set fed parents-first and
133
+ # children-first iterated identically, so a child-ahead-of-parent table stays
134
+ # green on the single-pass mutant. The descending chain reds it on every awk
135
+ # reachable from here — one-true-awk 20200816 (darwin's /usr/bin/awk), mawk
136
+ # 1.3.4 (what ubuntu-latest runs) and gawk 5.4.1. An ASCENDING chain is not a
137
+ # substitute: gawk walks those keys in ascending order, which is already
138
+ # topological, so the mutant survives it there.
139
+ net_kill_tree() {
140
+ net_kin=$1
141
+ if net_snap=$(ps -A -o pid=,ppid= 2>/dev/null); then
142
+ net_kin=$(printf '%s\n' "$net_snap" | LC_ALL=C awk -v root="$1" '
143
+ { parent[$1] = $2 }
144
+ END { doomed[root] = 1
145
+ do { grew = 0
146
+ for (p in parent)
147
+ if (!(p in doomed) && (parent[p] in doomed)) {
148
+ doomed[p] = 1; grew = 1
149
+ }
150
+ } while (grew)
151
+ for (p in doomed) printf "%s ", p }') ||
152
+ { net_kin=$1; printf 'degraded ' >>"${net_wdfile:-/dev/null}" || :; }
153
+ else
154
+ printf 'degraded ' >>"${net_wdfile:-/dev/null}" || :
155
+ fi
156
+ # shellcheck disable=SC2086 # a pid list, and word splitting is how kill reads it
157
+ kill $net_kin 2>/dev/null || :
158
+ # shellcheck disable=SC2086
159
+ kill -9 $net_kin 2>/dev/null || :
160
+ }
161
+
162
+ # net_wdnote <wdfile> — what the watchdog recorded about the last net_git call:
163
+ # `fired` if the budget elapsed and the call was killed, `degraded` if the
164
+ # process table could not be read and only the named process was signalled.
165
+ #
166
+ # It has to be a file rather than a variable. The sleeper is a background
167
+ # grandchild, so nothing it sets in a variable reaches the shell that reads it,
168
+ # and its own exit status is discarded; a caller that captures net_git's stdout
169
+ # puts the whole call in a command substitution besides, which loses every
170
+ # assignment it makes. The marker is written BEFORE net_kill_tree, never after,
171
+ # because `wait` returns the instant the call dies and would otherwise race the
172
+ # write.
173
+ #
174
+ # A file a caller WANTS, not one it needs: `mktemp` failing must not cost a
175
+ # verdict that is otherwise answerable, so an empty <wdfile> is legal and reads
176
+ # back as an empty note. What is lost then is the wording, never the answer.
177
+ net_wdnote() {
178
+ [ -n "${1:-}" ] || return 0
179
+ cat "$1" 2>/dev/null || true
180
+ }
181
+
182
+ # net_stalled <status> — was the call most likely killed by the watchdog?
183
+ #
184
+ # The weaker of the two tests, for a caller with no temp file to give. It reads
185
+ # the watchdog's work off a signal number this shell does not own, so it cannot
186
+ # tell our SIGTERM from anyone else's: a call killed from OUTSIDE is reported as
187
+ # a stall. Accepted, and the reason is that both wordings sit under the same
188
+ # verdict — the caller could not answer either way — so the cost is a sentence,
189
+ # never a claim. 137 as well as 143, because net_kill_tree escalates to SIGKILL
190
+ # and git can lose that race.
191
+ #
192
+ # A caller that owns a temp file gets the sharper test instead: net_wdnote reads
193
+ # a marker written by the watchdog and by nothing else, which is what separates
194
+ # a 30s budget that really elapsed from a 4s kill reported as one. inflight.sh
195
+ # has that file, keeps it, and reads it back through net_wdnote; the scripts
196
+ # with no temp file and no EXIT trap of their own take this instead, rather than
197
+ # growing one apiece for a wording — as does inflight.sh itself, on the one path
198
+ # where its own mktemp failed and there is no marker to read.
199
+ net_stalled() {
200
+ [ "$1" -eq 143 ] || [ "$1" -eq 137 ]
201
+ }
202
+
203
+ # net_git <wdfile> <budget> <git arg>... — run one `git` network call
204
+ # unattended: it neither prompts nor outlives <budget> seconds.
205
+ #
206
+ # stdout is git's stdout, stderr is left on stderr — git's own diagnostic of a
207
+ # failure is the useful thing to read, and folding it into the value is how a
208
+ # host-key notice comes back looking like a result. The return status is git's
209
+ # own, so `if ! out=$(net_git …)` reads exactly as `if ! out=$(git …)` did.
210
+ #
211
+ # <wdfile> is how the watchdog says it fired, and the caller reads it AFTER the
212
+ # call with net_wdnote — see there for why it is a file and not a variable. A
213
+ # caller with no file to give passes an empty string and loses only the sharper
214
+ # wording, never the verdict.
215
+ #
216
+ # GIT_TERMINAL_PROMPT=0 covers git's own username/password prompt.
217
+ # Unconditional, not gated on stdin being a tty: every caller here answers on a
218
+ # machine-read exit status, and a human with no cached credential is better
219
+ # served by that status naming what is unknown than by a prompt a machine
220
+ # caller never answers.
221
+ #
222
+ # A suppressed prompt is not a bound: measured, a stalled transport blocks
223
+ # identically with or without GIT_TERMINAL_PROMPT=0 (killed at 8s, rc 142
224
+ # either way) — prompting and hanging are different failures. `timeout(1)`
225
+ # would be the obvious bound but is GNU coreutils, absent by default here
226
+ # (verified: neither `timeout` nor `gtimeout` on this host's PATH), so the
227
+ # bound comes from git's own transport knobs.
228
+ #
229
+ # ssh: BatchMode=yes refuses any interactive prompt (host key, passphrase)
230
+ # rather than hanging on one, so it doubles as prompt suppression for the ssh
231
+ # case.
232
+ #
233
+ # ConnectTimeout is the option that bounds the stalled transport measured
234
+ # above: it gates the banner exchange, not only the TCP handshake, so a peer
235
+ # that accepts the connection and then never speaks is cut off at
236
+ # ConnectTimeout. Measured against that exact case (OpenSSH_10.2p1, the
237
+ # accept-then-silent listener the test at inflight.test.mjs uses) — both
238
+ # options set: "Connection timed out during banner exchange" at 10.0s;
239
+ # ConnectTimeout alone, ServerAlive dropped: 10.0s, identical; ServerAlive
240
+ # alone, ConnectTimeout dropped: still running at 30s, killed from outside.
241
+ # ServerAlive keepalives only ride an established transport, and here that
242
+ # transport never comes up, so they contribute nothing to this case. Their job
243
+ # is the session that gets past banner and authentication and only then goes
244
+ # quiet, which nothing here exercises.
245
+ #
246
+ # 10s to connect and 2x5s of silence: generous enough for a slow-but-working
247
+ # link, short enough that a stalled call does not hold a fleet slot for
248
+ # minutes. Retune here if either stops holding — but retune the right one: the
249
+ # accept-then-silent case rides on ConnectTimeout alone, so shortening
250
+ # ServerAlive does not tighten it and dropping ConnectTimeout removes it.
251
+ #
252
+ # A user's own ssh command is honoured, not replaced — these options are
253
+ # appended to whatever GIT_SSH_COMMAND, core.sshCommand or GIT_SSH already says
254
+ # (falling back to plain "ssh"), so a configured identity file or proxy command
255
+ # still runs. All three, because git's own precedence is GIT_SSH_COMMAND >
256
+ # core.sshCommand > GIT_SSH: setting GIT_SSH_COMMAND here without consulting
257
+ # GIT_SSH would silently drop a wrapper the user had working before this call
258
+ # was bounded at all.
259
+ #
260
+ # Appended, so they are defaults the user's own command overrides, never a
261
+ # ceiling over it: ssh takes the FIRST value of a repeated -o, so an option
262
+ # their command already carries is the one that applies and the value set here
263
+ # is discarded. Measured, OpenSSH_10.2p1: `ssh -o ConnectTimeout=45 -o
264
+ # ConnectTimeout=10 -G` reports connecttimeout 45; and against the
265
+ # accept-then-silent listener, with these options appended to a user command
266
+ # exactly as net_git appends them, a user ConnectTimeout of 3 cut the
267
+ # connection at 3.0s and one of 25 at 25.0s, the 10s set here applying only
268
+ # where the user set none. So the bound degrades to whatever bound the user
269
+ # asked for, and terminates only where that value does. Measured on the same
270
+ # listener: a user ConnectTimeout of 0 is accepted, wins by the same rule and
271
+ # left the call still connecting at 40s, where the 10s set here cut at 10.2s —
272
+ # unbounded, through the user's own config, which is the #92 hang again. The
273
+ # watchdog below is what now bounds that case, since it bounds the call rather
274
+ # than the transport and so does not depend on any value ssh resolved (#346).
275
+ # Ordering these first would bound the call at its own value instead,
276
+ # at the cost of silently overriding a deliberate proxy or timeout config: a
277
+ # real regression traded for a hypothetical one, so it is not done.
278
+ #
279
+ # The same rule makes BatchMode a user opt-out. A command carrying
280
+ # `-o BatchMode=no` keeps it and ssh goes back to asking, which
281
+ # GIT_TERMINAL_PROMPT=0 does not reach — that suppresses git's own credential
282
+ # prompt, not ssh's. Measured with GIT_TERMINAL_PROMPT=0 set throughout: with
283
+ # the BatchMode=yes set here alone, an unknown host key fails at once ("Host key
284
+ # verification failed"); with a user's BatchMode=no ahead of it and a terminal
285
+ # reachable, ssh sat on "Are you sure you want to continue connecting" until
286
+ # killed — the unattended hang #92 exists to stop. Reachable is the operative
287
+ # word: with no terminal available it aborts rather than waiting. Honoured
288
+ # anyway, because it is the user's explicit setting; this records what that
289
+ # costs rather than warning about a choice they made on purpose. The watchdog
290
+ # below is what now ends that wait, and it is the only thing here that can:
291
+ # the prompt is ssh's, so no git-side variable reaches it, and the setting that
292
+ # opens it is the user's own, so overriding it is not on offer either. No test
293
+ # covers this one — the exposure needs a reachable terminal, and the harness
294
+ # runs without one, where ssh aborts at once instead of asking (#346).
295
+ #
296
+ # http: lowSpeedLimit/lowSpeedTime is git's (curl's) own bound for a transfer
297
+ # that goes quiet — abort if it sits under 1000 bytes/s for 10s.
298
+ #
299
+ # It bounds a transfer already under way and nothing before one, so it is a
300
+ # weaker bound than the ssh side, not a counterpart to it. Measured against the
301
+ # same accept-then-silent listener: a plain http origin aborts at 10.0s
302
+ # ("Operation too slow"), but an https one never starts a transfer at all — the
303
+ # TLS handshake does not complete, so the timer never arms and the call outlived
304
+ # every cap put on it. Nothing here reaches the connect phase either, on either
305
+ # scheme: `git help config` lists lowSpeedLimit and lowSpeedTime as its whole
306
+ # http timing vocabulary, and `git config --get http.connectTimeout` finds no
307
+ # such key to read. What is left of connect is curl's own default, which this
308
+ # script does not set and cannot shorten.
309
+ #
310
+ # Hence the watchdog below, and hence these knobs are no longer the bound. They
311
+ # stay anyway, and that is a decision rather than an oversight (#346): each one
312
+ # fails earlier than the watchdog and in git's own words, which is the more
313
+ # useful thing to read on a terminal, and dropping them would make every ssh
314
+ # stall wait out the full budget where ConnectTimeout ends it in a fraction of
315
+ # that. Defence in depth costs nothing here — the watchdog does not care whether
316
+ # they fired, and neither reads the other's state.
317
+ # Backgrounded and waited on, rather than polled: `wait` returns the moment the
318
+ # call does, so a reachable origin pays nothing for the bound being here. The
319
+ # sleeper is what enforces it, and it is killed by the same subtree walk as the
320
+ # call — its own `sleep` is a child, and an orphaned sleeper does not sit
321
+ # harmlessly: it wakes at the end of its budget and fires net_kill_tree at a pid
322
+ # this shell no longer owns, which after a budget's worth of pid churn can be an
323
+ # unrelated process — and, since #346, an unrelated SUBTREE. It cannot leak onto
324
+ # the caller's stderr whatever else it does, because the `>/dev/null 2>&1` below
325
+ # is on the sleeper itself and both its descriptors are already closed.
326
+ #
327
+ # `wait` is captured through an explicit `|| net_status=$?`, and `set -e` is
328
+ # why: a bare `wait` on a killed child aborts at that line, which is after the
329
+ # call is dealt with but before the sleeper is, and the sleeper would be the
330
+ # leak. The status is then carried out by an explicit `exit` rather than by
331
+ # whatever the subshell happens to end with, and the function returns what the
332
+ # subshell exited with.
333
+ net_git() {
334
+ # The whole body is a SUBSHELL, and that is not style. A caller who captures
335
+ # stdout gets one for free from `$( )`; a caller who does not — the fetches,
336
+ # which write to stderr and are read by their exit status — runs the body in
337
+ # its own shell, and there the shell REPORTS the SLEEPER it reaped once the
338
+ # caller runs on past the call: measured, `verify-sha.sh: line 77: 61980
339
+ # Terminated: 15 { sleep …` landed on the script's stderr, between its own
340
+ # trace line and its own result, on a completely healthy fetch. The notice is
341
+ # the shell's, not the job's, so no redirection on the job can reach it; `( )`
342
+ # is what covers it, by leaving the sleeper behind in a shell that exits
343
+ # before it would announce anything. Bash-as-sh is the shell that prints it —
344
+ # measured, dash announces no sleeper with the subshell or without it.
345
+ #
346
+ # That is the SLEEPER, and it is the whole of what `( )` buys. The git job is
347
+ # a separate notice on a separate path: it is reaped by an explicit `wait`,
348
+ # which announces a signalled child from INSIDE the subshell, onto the same
349
+ # stderr, on the watchdog-killed path, with the subshell and without it alike.
350
+ #
351
+ # WHICH signal that notice names is not the shell's call: net_kill_tree above
352
+ # sends TERM then KILL with no pause, so whichever one reaps the job first is
353
+ # a race, not a property either shell owns. What the shell DOES fix is the
354
+ # FORM — bash-as-sh names the job (the long form); dash's notice is bare, just
355
+ # `<signal>: <n>`. Measured for #1042 by replaying net_git's own mechanism
356
+ # against a plain `sleep`: on this machine, `/bin/sh` (bash 3.2.57) and
357
+ # `/bin/dash` both gave TERM, every run — a quiet-system sample, not a signal
358
+ # either shell is owed, which is why a caller has to accept either.
359
+ #
360
+ # Either way the notice lands above the caller's own reason, and a caller
361
+ # that CAPTURES stdout got it too, so there was never a path where nothing
362
+ # printed it. The `2>/dev/null` on the `wait` below is what covers that one.
363
+ (
364
+ net_wdfile=$1
365
+ net_budget_s=$2
366
+ shift 2
367
+ net_base_ssh=$(git config --get core.sshCommand 2>/dev/null || true)
368
+ # GIT_SSH is a program PATH, not a command line, so it is quoted rather than
369
+ # pasted raw: git runs GIT_SSH_COMMAND through a shell, which would otherwise
370
+ # split a path containing spaces into a program and its arguments.
371
+ [ -n "$net_base_ssh" ] || net_base_ssh="${GIT_SSH:+\"$GIT_SSH\"}"
372
+ [ -n "$net_base_ssh" ] || net_base_ssh=ssh
373
+ # `-c maintenance.auto=false`: `git fetch --prune`, once it updates refs,
374
+ # spawns `git maintenance run --auto --quiet --detach` as a side effect —
375
+ # measured via `GIT_TRACE=1` (git 2.55.0) on a bare `fetch --prune`, no
376
+ # wrapper involved. One of that detached run's tasks is `git worktree
377
+ # prune --expire 3.months.ago`, and a linked worktree whose `gitdir`
378
+ # pointer FILE is itself missing or unreadable — as opposed to the
379
+ # worktree directory, HEAD, or anything else in the entry — is pruned on
380
+ # sight: the 3-month floor bounds staleness git can measure from the
381
+ # entry's own files, and a missing pointer gives it nothing to measure,
382
+ # so the floor does not apply. Measured (#2078): a fixture with exactly
383
+ # that fault, fetched through this function unmodified, loses the
384
+ # registry entry between the fetch returning and the caller's own next
385
+ # read of it — a worktree whose fault is seconds old, not months.
386
+ # reap.sh's registry recount (`count_registry`/`count_linked`,
387
+ # `wt_registry_why`) reads the very corruption this detached run erases:
388
+ # with the entry gone, the registry count drops to match the listing's
389
+ # linked count, in lockstep, and the guard a stray `git worktree add`
390
+ # mid-run is built to catch sees no mismatch to refuse on — both branches
391
+ # in that fixture's pass were wrongly reaped. A bare foreground fetch
392
+ # usually wins this race (the detached child has not run yet by the time
393
+ # the caller reads the registry); this function's own extra fork/wait
394
+ # overhead was measured to flip the outcome reliably. `maintenance.auto`
395
+ # is fetch's own config for the hook that spawns the detached run — the
396
+ # narrowest knob that stops it without touching `--prune`'s unrelated,
397
+ # still-wanted job of dropping stale remote-tracking refs.
398
+ GIT_TERMINAL_PROMPT=0 \
399
+ GIT_SSH_COMMAND="${GIT_SSH_COMMAND:-$net_base_ssh} -o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=5 -o ServerAliveCountMax=2" \
400
+ git -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=10 -c maintenance.auto=false "$@" &
401
+ net_pid=$!
402
+ { sleep "$net_budget_s"; printf 'fired ' >>"$net_wdfile" || :; net_kill_tree "$net_pid"; } >/dev/null 2>&1 &
403
+ net_wd_pid=$!
404
+ net_status=0
405
+ wait "$net_pid" 2>/dev/null || net_status=$?
406
+ net_kill_tree "$net_wd_pid"
407
+ exit "$net_status"
408
+ )
409
+ }