@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,355 @@
1
+ #!/usr/bin/env node
2
+ // The Shortlist (ADR 0013 §1, §3; docs/specs/2026-09-24-slot-based-fleet-loop-design.md
3
+ // § 1): the ordered list of tickets the controller may admit, built from cheap
4
+ // filters only. No ticket body is read here — a Pull reads one ticket in full
5
+ // at the moment it admits it (ADR 0013 §2); this file decides which tickets are
6
+ // worth that read, and in what order.
7
+ //
8
+ // The filters, in the order they run:
9
+ //
10
+ // 1. `candidates.mjs --require-label ready-for-agent`, oldest-first and never
11
+ // re-ranked. Its row count is `scanned`, the supply the tick reports.
12
+ // 2. The dependency scan on each row's `d`: an open blocker drops the ticket
13
+ // (next-ticket step 2). A blocker that is itself a candidate is open by
14
+ // construction — candidates.mjs queries `--state open` — so only the rest
15
+ // cost a `gh issue view <N> --json state`, which answers for a PR number
16
+ // as well as an issue. A ticket naming itself blocks nothing.
17
+ // 3. Live Exclusions. A ticket whose ledger row reads `excluded ·
18
+ // behind-pr:#M` or `excluded · behind-issue:#M` stays out while its
19
+ // premise holds: `behind-pr` is asked of `gh pr view M`, which takes the
20
+ // PR number or the branch name recorded before that PR existed, and
21
+ // `behind-issue` of `gh issue view M`. MERGED or CLOSED lifts either.
22
+ // Nothing here rewrites the row — the Pull that admits the ticket does —
23
+ // so a lifted ticket re-enters in its oldest-first slot simply because
24
+ // step 1's order is the only order there is.
25
+ // 4. `inflight.sh <N>` per survivor: exit 1 is taken, and every other
26
+ // non-zero exit is an in-flight check that could not answer, which is
27
+ // never "free". Both drop the ticket.
28
+ //
29
+ // ADR 0013 lists step 3 last. Steps 2-4 only intersect, so their order changes
30
+ // what they cost and nothing else: the ledger is a local read and a premise
31
+ // one `gh` call, while inflight.sh is three network round-trips (measured at
32
+ // 2.6 s a ticket against this repository, 23 live candidates), so it runs on
33
+ // what the cheaper two leave.
34
+ //
35
+ // Every probe that cannot answer fails CLOSED and is logged by ticket number:
36
+ // an unreadable blocker counts as open, an unreadable premise leaves its
37
+ // exclusion standing, an unanswered in-flight check counts as taken. A ticket
38
+ // dropped wrongly waits one refresh; a ticket admitted wrongly costs a Pull's
39
+ // full read at best and two members on one ticket at worst.
40
+ //
41
+ // What REFUSES instead (exit 2), leaving the previous file exactly as it was: a
42
+ // scan that did not answer, a ledger that could not be read, a workspace that
43
+ // could not be resolved, a file that could not be written. An empty shortlist
44
+ // written in any of those cases would read as "no work". Exit 0 is the file
45
+ // written, an empty shortlist included — the empty queue is an answer. Never
46
+ // exit 1: this script has no verdict to report (docs/specs/2026-07-23-fleet-plugin-design.md
47
+ // § Script surface), and 1 is also Node's own code for a crash.
48
+ //
49
+ // The file is `<workspace>/.fleet/shortlist.json`, the workspace resolved from
50
+ // `git rev-parse --git-common-dir` through git-env.mjs, exactly as ledger.mjs's
51
+ // defaultLedgerPath() resolves `.fleet/ledger.md` — so the controller, the tick
52
+ // and a member in its own worktree all name one file. Unlike the ledger there
53
+ // is no cwd-relative degrade: outside a repository inflight.sh cannot answer
54
+ // for a single ticket either, so there is nothing honest to write. The payload
55
+ // is `{scanned, shortlist: [{n, t}]}`, written to a sibling temp file and
56
+ // renamed over the target so a reader never sees half of it; stdout carries
57
+ // the same object plus `file`.
58
+ //
59
+ // The ledger is read through `ledger.mjs read`, never parsed here, so the
60
+ // ledger keeps one parser. candidates.mjs's stderr passes straight through —
61
+ // the per-candidate lines phase 0 always read, #1032's dependency-heading
62
+ // notice among them. inflight.sh's and gh's are captured and summarised, one
63
+ // line per dropped ticket.
64
+
65
+ import { spawnSync, execFile } from "node:child_process";
66
+ import { mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
67
+ import { dirname, join } from "node:path";
68
+ import { fileURLToPath } from "node:url";
69
+ import { makeDie, writeAll, isDigits } from "./arg.mjs";
70
+ import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
71
+
72
+ const NAME = "shortlist";
73
+ const die = makeDie(NAME);
74
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
75
+ const LABEL = "ready-for-agent";
76
+ // The states that lift a premise or clear a blocker. `gh pr view` answers
77
+ // OPEN, CLOSED or MERGED; `gh issue view` answers OPEN or CLOSED for an issue
78
+ // and the PR's own state for a PR number — so one set serves every probe here.
79
+ const CLOSED = new Set(["MERGED", "CLOSED"]);
80
+ // Network probes run this many at a time. inflight.sh alone is ~2.6 s a
81
+ // ticket, so 23 candidates probed one after another cost up to a minute of the
82
+ // tick's turn. Results land by index, so the order written is candidates.mjs's,
83
+ // whatever order the probes finish in.
84
+ const IN_FLIGHT = 4;
85
+ // Bounds on children that could otherwise never return. None is a stopwatch:
86
+ // each is far past the healthy case (a `rev-parse` answers in milliseconds, a
87
+ // `gh … view` in under a second, inflight.sh in ~2.6 s), and each timeout
88
+ // lands on the same fail-closed path as any other failed probe.
89
+ const GIT_TIMEOUT_MS = 10_000;
90
+ const GH_TIMEOUT_MS = 20_000;
91
+ const INFLIGHT_TIMEOUT_MS = 120_000;
92
+ const MAX_BUFFER = 64 * 1024 * 1024;
93
+
94
+ // Synchronous, so a die() that follows cannot strand a log line in an async
95
+ // stderr queue when it exits.
96
+ const log = (line) => writeAll(2, `${line}\n`);
97
+
98
+ // The last non-blank line a child printed, bounded: a cause, not a transcript.
99
+ function lastLine(text) {
100
+ const lines = String(text ?? "").split("\n").map((l) => l.trim()).filter(Boolean);
101
+ const line = lines.at(-1) ?? "";
102
+ return line.length > 300 ? `…${line.slice(-300)}` : line;
103
+ }
104
+
105
+ // How a child that did not exit 0 ended, for a log line or a refusal.
106
+ function how(r) {
107
+ if (r.error) return r.error.code ?? r.error.message;
108
+ return r.signal ? `killed by ${r.signal}` : `exit ${r.status}`;
109
+ }
110
+
111
+ function describe(r) {
112
+ const said = lastLine(r.stderr);
113
+ return said ? `${how(r)}: ${said}` : how(r);
114
+ }
115
+
116
+ // execFile, promised, with its error folded into spawnSync's result shape.
117
+ // execFile packs three things into `err`: a numeric `code` is the child's own
118
+ // exit status, a `signal` is a kill (the timeout's among them), and anything
119
+ // else is a child that never ran — ENOENT and the like.
120
+ function run(file, args, options) {
121
+ return new Promise((resolve) => {
122
+ execFile(file, args, { encoding: "utf8", maxBuffer: MAX_BUFFER, ...options }, (err, stdout, stderr) => {
123
+ const status = err ? (typeof err.code === "number" ? err.code : null) : 0;
124
+ const signal = err?.signal ?? null;
125
+ resolve({ status, signal, error: err && status === null && !signal ? err : null, stdout, stderr });
126
+ });
127
+ });
128
+ }
129
+
130
+ // fn over items, IN_FLIGHT at a time, results in the items' own order.
131
+ async function eachLimited(items, fn) {
132
+ const results = new Array(items.length);
133
+ let next = 0;
134
+ const worker = async () => {
135
+ while (next < items.length) {
136
+ const i = next++;
137
+ results[i] = await fn(items[i]);
138
+ }
139
+ };
140
+ await Promise.all(Array.from({ length: Math.min(IN_FLIGHT, items.length) }, worker));
141
+ return results;
142
+ }
143
+
144
+ function shortlistPath() {
145
+ const r = spawnSync("git", ["rev-parse", "--git-common-dir"], {
146
+ encoding: "utf8", timeout: GIT_TIMEOUT_MS, env: gitEnv(),
147
+ });
148
+ const workspace = workspaceDirFromGitCommonDir(r.stdout);
149
+ if (workspace === null) {
150
+ die(`could not resolve the workspace — git rev-parse --git-common-dir: ${describe(r)}`);
151
+ }
152
+ return join(workspace, ".fleet", "shortlist.json");
153
+ }
154
+
155
+ function scan() {
156
+ const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", LABEL], {
157
+ encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "inherit"],
158
+ });
159
+ if (r.error) die(`candidates.mjs did not run: ${how(r)}`);
160
+ const out = (r.stdout ?? "").trim();
161
+ // Exit 1 (an empty queue) and exit 3 (every row a to-spec spec) are both the
162
+ // empty answer. Exit 1 is also Node's own code for a crash, so the payload
163
+ // decides.
164
+ if ((r.status === 1 || r.status === 3) && out === "[]") return [];
165
+ if (r.status !== 0) {
166
+ die(`candidates.mjs ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`} — the scan did not answer, so there is no shortlist to write`);
167
+ }
168
+ let rows;
169
+ try {
170
+ rows = JSON.parse(out);
171
+ } catch (e) {
172
+ die(`could not parse candidates.mjs output: ${e.message}`);
173
+ }
174
+ if (!Array.isArray(rows)) die("candidates.mjs did not return an array");
175
+ const bad = rows.findIndex(
176
+ (row) => !row || !Number.isInteger(row.n) || typeof row.t !== "string" ||
177
+ !Array.isArray(row.d) || !row.d.every(Number.isInteger),
178
+ );
179
+ if (bad !== -1) die(`candidates.mjs row ${bad} is not {n, t, d} with integer refs`);
180
+ return rows;
181
+ }
182
+
183
+ function ledgerRows() {
184
+ const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "ledger.mjs"), "read"], {
185
+ encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "inherit"],
186
+ });
187
+ if (r.error) die(`ledger.mjs read did not run: ${how(r)}`);
188
+ if (r.status !== 0) {
189
+ die(`ledger.mjs read ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`} — no exclusion could be honoured, so there is no shortlist to write`);
190
+ }
191
+ let data;
192
+ try {
193
+ data = JSON.parse(r.stdout);
194
+ } catch (e) {
195
+ die(`could not parse ledger.mjs read output: ${e.message}`);
196
+ }
197
+ if (!data || !Array.isArray(data.rows) || !data.rows.every((row) => typeof row === "string")) {
198
+ die("ledger.mjs read returned no rows[] of strings");
199
+ }
200
+ return data.rows;
201
+ }
202
+
203
+ // A ticket row is `#N <text>`; it is an exclusion when `excluded` is the text's
204
+ // first word — `impl-N · … excluded …` is a row about something else. Answers
205
+ // the premises the row names, possibly none, or null for any other row.
206
+ const EXCLUDED_ROW = /^#[0-9]+[ \t]+excluded(?=[ \t]|$)([\s\S]*)$/;
207
+ const PREMISE = /\bbehind-(pr|issue):#?([^\s,;]+)/g;
208
+ function premisesOf(row) {
209
+ const m = EXCLUDED_ROW.exec(row);
210
+ if (!m) return null;
211
+ return [...m[1].matchAll(PREMISE)].map(([, kind, target]) => ({ kind, target }));
212
+ }
213
+
214
+ // gh takes a `-`-led argument as a flag, and `gh issue view` takes a number.
215
+ const askable = ({ kind, target }) => !target.startsWith("-") && (kind === "pr" || isDigits(target));
216
+ const premiseKey = ({ kind, target }) => `${kind} ${target}`;
217
+ const premiseLabel = ({ kind, target }) => `behind-${kind}:#${target}`;
218
+
219
+ async function probeState(kind, target) {
220
+ // gh's own remote resolution follows GIT_DIR/GIT_WORK_TREE exactly as git's
221
+ // does, and GH_REPO outranks even that (ledger.mjs's tracker-query probe,
222
+ // measured) — so this call needs the same scrub shortlistPath()'s git call
223
+ // gets, or an ambient one of the three silently answers for a different
224
+ // repository while `.fleet/shortlist.json` still lands in the right one.
225
+ const r = await run("gh", [kind, "view", target, "--json", "state"], {
226
+ timeout: GH_TIMEOUT_MS, env: gitEnv({ GH_REPO: "" }),
227
+ });
228
+ if (r.status !== 0) return { error: describe(r) };
229
+ let state;
230
+ try {
231
+ ({ state } = JSON.parse(r.stdout));
232
+ } catch {
233
+ // Unparseable: `state` stays undefined and is refused as missing.
234
+ }
235
+ return typeof state === "string" && state
236
+ ? { state }
237
+ : { error: `gh ${kind} view ${target} answered no state: ${lastLine(r.stdout)}` };
238
+ }
239
+
240
+ function inflightPayload(r) {
241
+ try {
242
+ const p = JSON.parse(r.stdout);
243
+ return p && typeof p === "object" ? p : null;
244
+ } catch {
245
+ return null;
246
+ }
247
+ }
248
+
249
+ async function main() {
250
+ const extra = process.argv.slice(2);
251
+ if (extra.length) die(`takes no arguments, got ${extra.join(" ")}`);
252
+ const file = shortlistPath();
253
+ const rows = scan();
254
+ const ledger = ledgerRows();
255
+
256
+ // Dependency scan.
257
+ const candidates = new Set(rows.map((row) => row.n));
258
+ const blockersOf = (row) => row.d.filter((b) => b !== row.n);
259
+ const unknownBlockers = [...new Set(rows.flatMap(blockersOf))].filter((b) => !candidates.has(b));
260
+ const blockerStates = await eachLimited(unknownBlockers, (b) => probeState("issue", String(b)));
261
+ const blocker = new Map(unknownBlockers.map((b, i) => [b, blockerStates[i]]));
262
+ const blockedBy = (row) => {
263
+ for (const b of blockersOf(row)) {
264
+ if (candidates.has(b)) return `open blocker #${b}`;
265
+ const s = blocker.get(b);
266
+ if (s.error) return `blocker #${b}'s state could not be read (${s.error}), so it counts as open`;
267
+ if (s.state === "OPEN") return `open blocker #${b}`;
268
+ if (!CLOSED.has(s.state)) return `blocker #${b} is ${s.state}, not MERGED or CLOSED`;
269
+ }
270
+ return null;
271
+ };
272
+ const unblocked = rows.filter((row) => {
273
+ const why = blockedBy(row);
274
+ if (why) log(` #${row.n} dropped — ${why}`);
275
+ return !why;
276
+ });
277
+
278
+ // Live exclusions. One row per ticket, rewritten in place by ledger.mjs, which
279
+ // matches the FIRST row carrying a key — so the first is the one read here.
280
+ const rowOf = new Map();
281
+ for (const line of ledger) {
282
+ const key = line.split(/\s/)[0];
283
+ if (!rowOf.has(key)) rowOf.set(key, line);
284
+ }
285
+ const excluded = new Map();
286
+ for (const row of unblocked) {
287
+ const line = rowOf.get(`#${row.n}`);
288
+ const premises = line === undefined ? null : premisesOf(line);
289
+ if (premises) excluded.set(row.n, premises);
290
+ }
291
+ const premiseKeys = [...new Set([...excluded.values()].flat().filter(askable).map(premiseKey))];
292
+ const premiseStates = await eachLimited(premiseKeys, (k) => probeState(...k.split(" ")));
293
+ const premise = new Map(premiseKeys.map((k, i) => [k, premiseStates[i]]));
294
+ const stillExcluded = (premises) => {
295
+ if (premises.length === 0) return "excluded with no behind-pr:/behind-issue: premise to probe, so the exclusion stands";
296
+ for (const p of premises) {
297
+ if (!askable(p)) return `excluded · ${premiseLabel(p)}, which gh cannot be asked about, so the exclusion stands`;
298
+ const s = premise.get(premiseKey(p));
299
+ if (s.error) return `excluded · ${premiseLabel(p)}, whose state could not be read (${s.error}), so the exclusion stands`;
300
+ if (!CLOSED.has(s.state)) return `excluded · ${premiseLabel(p)}, which is ${s.state}`;
301
+ }
302
+ return null;
303
+ };
304
+ const admissible = unblocked.filter((row) => {
305
+ const premises = excluded.get(row.n);
306
+ if (!premises) return true;
307
+ const why = stillExcluded(premises);
308
+ if (why) {
309
+ log(` #${row.n} dropped — ${why}`);
310
+ return false;
311
+ }
312
+ log(` #${row.n} lifted — ${premises.map((p) => `${premiseLabel(p)} is ${premise.get(premiseKey(p)).state}`).join(", ")}`);
313
+ return true;
314
+ });
315
+
316
+ // In-flight check.
317
+ const verdicts = await eachLimited(admissible, (row) =>
318
+ run("sh", [join(SCRIPT_DIR, "inflight.sh"), String(row.n)], { timeout: INFLIGHT_TIMEOUT_MS }));
319
+ const survivors = admissible.filter((row, i) => {
320
+ const r = verdicts[i];
321
+ if (r.status === 0) return true;
322
+ const p = inflightPayload(r);
323
+ if (r.status === 1) {
324
+ const hits = Array.isArray(p?.hits) && p.hits.length ? `: hits ${p.hits.join(",")}` : "";
325
+ log(` #${row.n} dropped — taken (inflight.sh exit 1${hits})`);
326
+ } else {
327
+ const why = Array.isArray(p?.unknown) && p.unknown.length ? p.unknown.join("; ") : lastLine(r.stderr);
328
+ log(` #${row.n} dropped — in-flight check could not answer (inflight.sh ${how(r)})${why ? `: ${why}` : ""}`);
329
+ }
330
+ return false;
331
+ });
332
+
333
+ const payload = { scanned: rows.length, shortlist: survivors.map(({ n, t }) => ({ n, t })) };
334
+ const tmp = `${file}.${process.pid}.tmp`;
335
+ try {
336
+ mkdirSync(dirname(file), { recursive: true });
337
+ writeFileSync(tmp, `${JSON.stringify(payload)}\n`);
338
+ renameSync(tmp, file);
339
+ } catch (e) {
340
+ rmSync(tmp, { force: true });
341
+ die(`cannot write ${file}: ${e.message}`);
342
+ }
343
+ log(`${NAME}: ${payload.shortlist.length} of ${payload.scanned} scanned → ${file}`);
344
+ // Printed and left to drain, never followed by process.exit(): stdout on a
345
+ // pipe is async, and an exit would cut the payload mid-JSON (#246).
346
+ console.log(JSON.stringify({ file, ...payload }));
347
+ }
348
+
349
+ try {
350
+ await main();
351
+ } catch (e) {
352
+ // Nothing inside main() is expected to throw; if something does, the answer
353
+ // is still "could not answer", never Node's exit 1.
354
+ die(`unexpected failure: ${e?.stack ?? e}`);
355
+ }