@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,516 @@
1
+ // `ledger.mjs dispatch | settle | drain` and the `## Dispatched` list (#1799;
2
+ // spec 2026-09-24 § 6 §2 and § 4 item 2). The token grammar these write is
3
+ // ledger-grammar.test.mjs's subject; this file is about what lands in the
4
+ // file, and what the three subcommands refuse to write.
5
+ //
6
+ // Every call is its own process against one ledger file, with nothing carried
7
+ // between calls but that file — the position a replacement controller is in
8
+ // after a context loss, which is who these records exist for.
9
+
10
+ import { test } from "node:test";
11
+ import assert from "node:assert/strict";
12
+ import { spawnSync } from "node:child_process";
13
+ import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
14
+ import { tmpdir } from "node:os";
15
+ import { join } from "node:path";
16
+ import { fileURLToPath } from "node:url";
17
+ import { computeBoard } from "./compute-board.mjs";
18
+ import { deriveRun } from "./fleet-tick.mjs";
19
+
20
+ const SCRIPT = fileURLToPath(new URL("./ledger.mjs", import.meta.url));
21
+
22
+ function fixture(t, body = null) {
23
+ const dir = mkdtempSync(join(tmpdir(), "ledger-dispatch-"));
24
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
25
+ const file = join(dir, "ledger.md");
26
+ if (body !== null) writeFileSync(file, body);
27
+ // PATH is an empty directory: none of these subcommands may reach gh or
28
+ // git, and with `--file` given nothing else in ledger.mjs does either.
29
+ const bin = join(dir, "bin");
30
+ mkdirSync(bin);
31
+ const env = { ...process.env, PATH: bin };
32
+ delete env.GIT_DIR;
33
+ delete env.GIT_WORK_TREE;
34
+ const cli = (...args) => {
35
+ const r = spawnSync(process.execPath, [SCRIPT, "--file", file, ...args], { encoding: "utf8", env, cwd: dir });
36
+ return { ...r, json: r.status === 0 ? JSON.parse(r.stdout) : null };
37
+ };
38
+ const ok = (...args) => {
39
+ const r = cli(...args);
40
+ assert.equal(r.status, 0, `${args.join(" ")}: got exit ${r.status}\n${r.stderr}`);
41
+ return r.json;
42
+ };
43
+ const read = () => ok("read");
44
+ const bytes = () => (existsSync(file) ? readFileSync(file, "utf8") : null);
45
+ // A refusal is exit 2, a reason on stderr, no payload — and no write.
46
+ const refused = (args, why) => {
47
+ const before = bytes();
48
+ const r = cli(...args);
49
+ assert.equal(r.status, 2, `${args.join(" ")}: got exit ${r.status}\n${r.stderr}`);
50
+ assert.match(r.stderr, why, `${args.join(" ")}: stderr was ${r.stderr}`);
51
+ assert.equal(r.stdout, "", `${args.join(" ")}: a refusal must not also emit a payload`);
52
+ assert.equal(bytes(), before, `${args.join(" ")}: a refusal must not touch the ledger`);
53
+ };
54
+ return { file, cli, ok, read, bytes, refused };
55
+ }
56
+
57
+ test("dispatch appends a live member row and records the dispatch in ## Dispatched", (t) => {
58
+ const { ok, read, bytes } = fixture(t);
59
+ assert.deepEqual(ok("dispatch", "412", "impl-412"), {
60
+ member: "impl-412", ticket: "#412", line: "#412 impl-412", created: true, total: 1,
61
+ });
62
+ const l = read();
63
+ assert.deepEqual(l.rows, ["#412 impl-412"]);
64
+ assert.deepEqual(l.dispatched, ["impl-412"]);
65
+ assert.match(bytes(), /^## Dispatched\n\n- impl-412$/m);
66
+ });
67
+
68
+ // SKILL.md's phase 2 writes `row <N> "impl-<N> · class=routine"` at dispatch
69
+ // today, so a row that already carries the live token is the ordinary case
70
+ // and must be accepted without a second copy of it.
71
+ test("dispatch keeps an existing row's text, appending the token only where it is missing", (t) => {
72
+ const { ok, read } = fixture(t);
73
+ ok("row", "412", "impl-412 · class=routine");
74
+ ok("row", "415", "claimed · class=correction");
75
+ assert.deepEqual(ok("dispatch", "412", "impl-412"), {
76
+ member: "impl-412", ticket: "#412", line: "#412 impl-412 · class=routine", created: false, total: 1,
77
+ });
78
+ assert.equal(ok("dispatch", "#415", "impl-415").line, "#415 claimed · class=correction · impl-415");
79
+ assert.deepEqual(read().dispatched, ["impl-412", "impl-415"]);
80
+ });
81
+
82
+ test("a PR-bound member lands on the row carrying its PR, named by PR or by ticket", (t) => {
83
+ const { ok, read } = fixture(t);
84
+ ok("dispatch", "324", "impl-324");
85
+ ok("settle", "impl-324", "PR#346");
86
+ // By the PR number: found through the implementer's own settled token.
87
+ assert.deepEqual(ok("dispatch", "346", "fix-pr-346"), {
88
+ member: "fix-pr-346", ticket: "#324", line: "#324 impl-324=PR#346 · fix-pr-346", created: false, total: 2,
89
+ });
90
+ // By the ticket number whose row carries that PR.
91
+ assert.equal(ok("dispatch", "324", "finisher-pr-346").line, "#324 impl-324=PR#346 · fix-pr-346 · finisher-pr-346");
92
+ // The human-readable arrow a `row` call writes is found the same way.
93
+ ok("row", "330", "impl-330 → PR#350");
94
+ assert.equal(ok("dispatch", "350", "fix-pr-350").ticket, "#330");
95
+ // A PR no row carries gets a row of its own.
96
+ assert.deepEqual(ok("dispatch", "777", "fix-pr-777"), {
97
+ member: "fix-pr-777", ticket: "#777", line: "#777 fix-pr-777", created: true, total: 5,
98
+ });
99
+ assert.equal(read().rows.length, 3);
100
+ });
101
+
102
+ test("dispatch refuses a call that would record the wrong member, and writes nothing", (t) => {
103
+ const { ok, refused } = fixture(t);
104
+ ok("row", "324", "impl-324");
105
+ for (const [args, why] of [
106
+ [["dispatch", "415", "impl-412"], /impl-412 works ticket #412, not #415/],
107
+ [["dispatch", "324", "fix-pr-346"], /fix-pr-346 works PR #346, and row #324 carries no PR#346/],
108
+ [["dispatch", "412", "review-pr-412"], /unknown member 'review-pr-412'/],
109
+ [["dispatch", "412", "impl-412x"], /unknown member 'impl-412x'/],
110
+ [["dispatch", "5", "merge-bot"], /merge bots work no ticket or PR/],
111
+ [["dispatch", "5", "merge-bot-1"], /merge bots work no ticket or PR/],
112
+ [["dispatch", "--requre-file", "impl-412"], /unknown flag --requre-file — expected a ticket or PR number/],
113
+ [["dispatch", "-require-file", "impl-412"], /unknown flag -require-file — expected a ticket or PR number/],
114
+ [["dispatch", "abc", "impl-412"], /'abc' is not a ticket or PR number/],
115
+ [["dispatch", "impl-412"], /impl-412 works a ticket or PR — usage: ledger\.mjs dispatch <ticket\|pr> <member>/],
116
+ [["dispatch"], /usage: ledger\.mjs dispatch <ticket\|pr> <member>/],
117
+ [["dispatch", "412", "impl-412", "extra"], /usage: ledger\.mjs dispatch <ticket\|pr> <member>/],
118
+ ]) {
119
+ refused(args, why);
120
+ }
121
+ });
122
+
123
+ test("a member is dispatched once; its replacement takes a name of its own", (t) => {
124
+ const { ok, read, refused } = fixture(t);
125
+ ok("dispatch", "412", "impl-412");
126
+ refused(["dispatch", "412", "impl-412"], /impl-412 was already dispatched this run/);
127
+ ok("settle", "impl-412", "killed");
128
+ refused(["dispatch", "412", "impl-412"], /impl-412 was already dispatched this run \(impl-412=killed\)/);
129
+ assert.equal(ok("dispatch", "412", "impl-412-b").line, "#412 impl-412=killed · impl-412-b");
130
+ assert.deepEqual(read().dispatched, ["impl-412=killed", "impl-412-b"]);
131
+ });
132
+
133
+ test("merge-bot-<n> counts the ## Dispatched merge-bot entries, and a new ledger starts again at 1", (t) => {
134
+ const { ok, read, refused } = fixture(t);
135
+ assert.deepEqual(ok("dispatch", "merge-bot"), { member: "merge-bot-1", ticket: null, line: null, created: false, total: 1 });
136
+ ok("dispatch", "412", "impl-412");
137
+ ok("settle", "merge-bot-1", "done");
138
+ // A settled bot still counts: its replacement gets a new n.
139
+ assert.equal(ok("dispatch", "merge-bot").member, "merge-bot-2");
140
+ // The explicit name is accepted when it is the next one, and only then.
141
+ assert.equal(ok("dispatch", "merge-bot-3").member, "merge-bot-3");
142
+ refused(["dispatch", "merge-bot-5"], /the next merge bot this run is merge-bot-4/);
143
+ refused(["dispatch", "merge-bot-2"], /the next merge bot this run is merge-bot-4/);
144
+ const l = read();
145
+ assert.deepEqual(l.dispatched, ["merge-bot-1=done", "impl-412", "merge-bot-2", "merge-bot-3"]);
146
+ assert.deepEqual(l.rows, ["#412 impl-412"], "a merge bot works no ticket, so it writes no row");
147
+
148
+ const fresh = fixture(t);
149
+ assert.equal(fresh.ok("dispatch", "merge-bot").member, "merge-bot-1");
150
+ });
151
+
152
+ test("settle rewrites the member's token in its row and in ## Dispatched, and nothing else", (t) => {
153
+ const { ok, read } = fixture(t);
154
+ ok("row", "412", "impl-412 · class=routine · ports=16412");
155
+ ok("dispatch", "412", "impl-412");
156
+ assert.deepEqual(ok("settle", "impl-412", "PR#420"), {
157
+ member: "impl-412", outcome: "PR#420", ticket: "#412", line: "#412 impl-412=PR#420 · class=routine · ports=16412", changed: true,
158
+ });
159
+ // The one-token spelling the spec's record-before-tick table uses.
160
+ ok("dispatch", "415", "impl-415");
161
+ assert.equal(ok("settle", "impl-415=tier-mismatch").line, "#415 impl-415=tier-mismatch");
162
+ ok("dispatch", "420", "fix-pr-420");
163
+ assert.equal(ok("settle", "fix-pr-420", "applied:73b356de").line, "#412 impl-412=PR#420 · class=routine · ports=16412 · fix-pr-420=applied:73b356de");
164
+ ok("dispatch", "420", "finisher-pr-420");
165
+ ok("settle", "finisher-pr-420", "labelled");
166
+ ok("dispatch", "merge-bot");
167
+ assert.deepEqual(ok("settle", "merge-bot-1", "done"), { member: "merge-bot-1", outcome: "done", ticket: null, line: null, changed: true });
168
+ const l = read();
169
+ assert.deepEqual(l.dispatched, [
170
+ "impl-412=PR#420", "impl-415=tier-mismatch", "fix-pr-420=applied:73b356de", "finisher-pr-420=labelled", "merge-bot-1=done",
171
+ ]);
172
+ assert.deepEqual(l.rows, [
173
+ "#412 impl-412=PR#420 · class=routine · ports=16412 · fix-pr-420=applied:73b356de · finisher-pr-420=labelled",
174
+ "#415 impl-415=tier-mismatch",
175
+ ]);
176
+ });
177
+
178
+ test("settle refuses an outcome outside the member's vocabulary, and a malformed call, writing nothing", (t) => {
179
+ const { ok, refused } = fixture(t);
180
+ ok("dispatch", "412", "impl-412");
181
+ ok("dispatch", "merge-bot");
182
+ for (const [args, why] of [
183
+ [["settle", "impl-412", "done"], /'done' is not an outcome of impl-N — expected PR#M \| bailed \| released \| killed \| tier-mismatch/],
184
+ [["settle", "impl-412=labelled"], /'labelled' is not an outcome of impl-N/],
185
+ [["settle", "impl-412", "PR#420 extra"], /is not an outcome of impl-N/],
186
+ [["settle", "merge-bot-1", "labelled"], /expected done \| killed/],
187
+ [["settle", "review-pr-346", "failed"], /unknown member 'review-pr-346'/],
188
+ [["settle", "--requre-file", "bailed"], /unknown flag --requre-file — expected a member name/],
189
+ [["settle", "impl-412"], /usage: ledger\.mjs settle <member> <outcome>/],
190
+ [["settle"], /usage: ledger\.mjs settle <member> <outcome>/],
191
+ [["settle", "impl-412", "bailed", "extra"], /usage: ledger\.mjs settle <member> <outcome>/],
192
+ ]) {
193
+ refused(args, why);
194
+ }
195
+ });
196
+
197
+ test("settle repeats harmlessly with the same outcome and refuses a different one", (t) => {
198
+ const { ok, bytes, refused } = fixture(t);
199
+ ok("dispatch", "412", "impl-412");
200
+ ok("settle", "impl-412", "bailed");
201
+ const before = bytes();
202
+ assert.deepEqual(ok("settle", "impl-412", "bailed"), {
203
+ member: "impl-412", outcome: "bailed", ticket: "#412", line: "#412 impl-412=bailed", changed: false,
204
+ });
205
+ assert.equal(bytes(), before, "a repeat settle writes nothing");
206
+ refused(["settle", "impl-412", "PR#5"], /impl-412 is already settled as bailed/);
207
+ refused(["settle", "impl-999", "bailed"], /no live impl-999 in the ledger/);
208
+ });
209
+
210
+ // The must-ACCEPT half of settle's lookup: a live token that `dispatch` never
211
+ // wrote (SKILL.md's `row` writes one today), and a dispatched member whose
212
+ // row a later whole-line `row` call rewrote without its token. Refusing either
213
+ // leaves that member counted live for the rest of the run.
214
+ test("settle accepts a live token `row` wrote, and restores a token a later `row` dropped", (t) => {
215
+ const { ok, read } = fixture(t);
216
+ ok("row", "412", "impl-412 · class=routine");
217
+ assert.equal(ok("settle", "impl-412", "bailed").line, "#412 impl-412=bailed · class=routine");
218
+ ok("dispatch", "415", "impl-415");
219
+ ok("row", "415", "rewritten by hand");
220
+ assert.equal(ok("settle", "impl-415", "PR#9").line, "#415 rewritten by hand · impl-415=PR#9");
221
+ assert.deepEqual(read().dispatched, ["impl-415=PR#9"]);
222
+ });
223
+
224
+ // #2139: every reader parses member tokens anywhere in a row, so a malformed
225
+ // one `row` wrote used to land as a permanent settle — `settle merge-bot-1
226
+ // done` then refused as "already settled as dispatched". `row` refuses it
227
+ // instead, new row or rewrite alike, surfacing the grammar's own error.
228
+ test("row refuses a malformed member token anywhere in its text, writing nothing", (t) => {
229
+ const { ok, read, refused } = fixture(t);
230
+ ok("dispatch", "merge-bot");
231
+ refused(
232
+ ["row", "2136", "merge-bot-1=dispatched · ci=123:1:success"],
233
+ /malformed member token 'merge-bot-1=dispatched' — 'dispatched' is not an outcome of merge-bot-n — expected done \| killed/,
234
+ );
235
+ assert.deepEqual(read().rows, []);
236
+ // A rewrite of an existing row is refused the same way; the old line stays.
237
+ ok("row", "412", "impl-412 · class=routine");
238
+ for (const [text, why] of [
239
+ ["impl-412=done · class=routine", /'impl-412=done' — 'done' is not an outcome of impl-N — expected PR#M \| bailed/],
240
+ ["class=routine · impl-412-b=labelled", /'impl-412-b=labelled' — 'labelled' is not an outcome of impl-N/],
241
+ ["impl-412 · fix-pr-9=applied:not-a-sha", /'fix-pr-9=applied:not-a-sha' — .* expected applied:<head> \| no-op/],
242
+ ["impl-412=", /'impl-412=' — '' is not an outcome of impl-N/],
243
+ ]) {
244
+ refused(["row", "412", text], why);
245
+ }
246
+ assert.deepEqual(read().rows, ["#412 impl-412 · class=routine"]);
247
+ assert.equal(ok("settle", "merge-bot-1", "done").outcome, "done");
248
+ });
249
+
250
+ // The must-ACCEPT half: every well-formed member token — live or settled —
251
+ // and every non-member key `row` carries today still goes through, including
252
+ // tier-check.mjs's `tier-ok=`/`tier-mismatch=` verdicts (#1398), which name
253
+ // a member but are not member tokens themselves.
254
+ test("row still writes well-formed member tokens and non-member keys", (t) => {
255
+ const { ok, read } = fixture(t);
256
+ ok("dispatch", "merge-bot");
257
+ const rows = [
258
+ ["7", "impl-7 · class=routine · ports=16007"],
259
+ ["8", "impl-8=PR#9 · fix-pr-9=applied:73b356de · review=wf:r1=failed reviewed=abc1234:1/0/0 · ci=123:1:success"],
260
+ ["10", "held-behind:#9 · merge-bot-1=done · review=member:review-pr-10"],
261
+ ["11", "impl-11 · tier=alt · tier-ok=impl-11:fleet-implementer-alt"],
262
+ ["12", "impl-12=bailed · tier-mismatch=impl-12:fleet-implementer · impl-12: dispatched task, expected fleet-implementer"],
263
+ ];
264
+ for (const [ticket, text] of rows) ok("row", ticket, text);
265
+ assert.deepEqual(read().rows, rows.map(([n, text]) => `#${n} ${text}`));
266
+ });
267
+
268
+ // #1876: the tick owes an open PR a review while its implementer is still
269
+ // live, so a PR-bound member can be dispatched before `settle impl-N=PR#M`
270
+ // names the PR on the ticket row. dispatch's fallback then keys a row of its
271
+ // own to the PR — truthful until the settle, when two rows would name one PR:
272
+ // the cockpit drew two REVIEW cards and the tick's first-row-wins `byPr` lost
273
+ // the live review. The settle folds the PR-keyed row into the ticket row.
274
+ test("settle impl-N=PR#M folds the PR-keyed row a pre-settle dispatch created into the ticket row", (t) => {
275
+ const { ok, read } = fixture(t);
276
+ ok("dispatch", "1300", "impl-1300");
277
+ assert.equal(ok("dispatch", "1301", "fix-pr-1301").line, "#1301 fix-pr-1301");
278
+ ok("row", "1301", "fix-pr-1301 · review=member:review-pr-1301");
279
+ assert.deepEqual(read().rows, ["#1300 impl-1300", "#1301 fix-pr-1301 · review=member:review-pr-1301"]);
280
+
281
+ const folded = "#1300 impl-1300=PR#1301 · fix-pr-1301 · review=member:review-pr-1301";
282
+ assert.deepEqual(ok("settle", "impl-1300=PR#1301"), {
283
+ member: "impl-1300", outcome: "PR#1301", ticket: "#1300", line: folded, changed: true,
284
+ });
285
+ const l = read();
286
+ assert.deepEqual(l.rows, [folded]);
287
+ assert.deepEqual(l.dispatched, ["impl-1300=PR#1301", "fix-pr-1301"], "the fold moves row tokens only");
288
+
289
+ // Both readers see one PR with one live review on it.
290
+ const board = computeBoard({
291
+ ledger: { rows: l.rows, filed: [], ruled: [] }, issues: [], merged: [], ci: {}, prev: { tickets: [] }, now: 0,
292
+ prs: [{ number: 1301, state: "OPEN", labels: [], title: "pr 1301" }],
293
+ });
294
+ const cards = board.tickets.filter((c) => c.pr === 1301);
295
+ assert.equal(cards.length, 1);
296
+ assert.equal(cards[0].column, "REVIEW");
297
+ assert.equal(cards[0].agent, "review-pr-1301");
298
+ assert.equal(board.queue.reviewBacklog, 0, "the PR is under review, not owed one");
299
+ const run = deriveRun({ rows: l.rows, dispatched: l.dispatched, drain: null },
300
+ [{ number: 1301, labels: [], closingIssuesReferences: [{ number: 1300 }] }]);
301
+ assert.equal(run.reviewsLive, 1);
302
+ assert.deepEqual(run.reviewDue, []);
303
+
304
+ // Every later PR-bound write finds the one row naming the PR.
305
+ assert.equal(ok("settle", "fix-pr-1301", "no-op").ticket, "#1300");
306
+ assert.equal(ok("dispatch", "1301", "finisher-pr-1301").ticket, "#1300");
307
+ assert.equal(read().rows.length, 1);
308
+ });
309
+
310
+ // #2064: merge-bot records a conflict its local-rebase fallback would not
311
+ // force with `row`, and the fix-applier is recorded with the ordinary
312
+ // `dispatch`/`settle`. The tick clears the hold only on a settle positioned
313
+ // AFTER the hold token, so the writers must put it there — including when
314
+ // the PR's review-fix `fix-pr-<M>` already settled earlier on the same row.
315
+ test("a conflict hold written by row is cleared by a later dispatch + settle, in the order the tick reads", (t) => {
316
+ const { ok, read } = fixture(t);
317
+ const before = "impl-10=PR#40 · reviewed=abc1234:1/0/0 · fix-pr-40=applied:73b356de";
318
+ ok("row", "10", before);
319
+ ok("row", "10", `${before} · conflict-hold:#40`);
320
+ const tick = () => {
321
+ const l = read();
322
+ return deriveRun({ rows: l.rows, dispatched: l.dispatched, drain: null },
323
+ [{ number: 40, labels: [{ name: "ready-to-merge" }], closingIssuesReferences: [{ number: 10 }] }]);
324
+ };
325
+ assert.deepEqual([tick().fixDue, tick().mergeHeld], [[40], 1], "the earlier settle cannot clear the newer hold");
326
+
327
+ assert.equal(ok("dispatch", "40", "fix-pr-40-b").line, `#10 ${before} · conflict-hold:#40 · fix-pr-40-b`);
328
+ assert.deepEqual([tick().fixDue, tick().mergeHeld], [[], 1], "dispatched is not settled");
329
+
330
+ assert.equal(ok("settle", "fix-pr-40-b", "applied:def5678").line, `#10 ${before} · conflict-hold:#40 · fix-pr-40-b=applied:def5678`);
331
+ assert.deepEqual([tick().fixDue, tick().mergeHeld], [[], 0]);
332
+ });
333
+
334
+ test("the fold takes the PR row's settled tokens in order, under the two-argument spelling, wherever the PR row sits", (t) => {
335
+ const { ok, read } = fixture(t);
336
+ // The PR's row comes first here, and a third row follows the ticket's.
337
+ ok("dispatch", "1311", "fix-pr-1311");
338
+ ok("settle", "fix-pr-1311", "applied:73b356de");
339
+ ok("row", "1311", "fix-pr-1311=applied:73b356de · review=wf:r1=failed reviewed=abc1234:1/0/0 · ci=9:1:success");
340
+ ok("row", "1310", "impl-1310 · class=routine");
341
+ ok("dispatch", "1320", "impl-1320");
342
+ const folded = "#1310 impl-1310=PR#1311 · class=routine · fix-pr-1311=applied:73b356de · review=wf:r1=failed reviewed=abc1234:1/0/0 · ci=9:1:success";
343
+ assert.deepEqual(ok("settle", "impl-1310", "PR#1311"), {
344
+ member: "impl-1310", outcome: "PR#1311", ticket: "#1310", line: folded, changed: true,
345
+ });
346
+ assert.deepEqual(read().rows, [folded, "#1320 impl-1320"]);
347
+ // A PR row holding nothing past its key leaves no stray separator behind.
348
+ ok("row", "1321", " ");
349
+ assert.equal(ok("settle", "impl-1320=PR#1321").line, "#1320 impl-1320=PR#1321");
350
+ assert.deepEqual(read().rows, [folded, "#1320 impl-1320=PR#1321"]);
351
+ });
352
+
353
+ // The must-LEAVE half: only the row keyed to the settled PR, and only when it
354
+ // carries no implementer, is folded. A settle to a PR with no row of its own
355
+ // is today's token rewrite and nothing more.
356
+ test("settle folds no row keyed to another PR, no row carrying an impl- token, and nothing when the PR has no row", (t) => {
357
+ const { ok, read } = fixture(t);
358
+ ok("dispatch", "412", "impl-412");
359
+ ok("dispatch", "777", "fix-pr-777");
360
+ ok("dispatch", "420", "impl-420");
361
+ ok("row", "421", "impl-421=killed · review=wf:r2");
362
+ ok("dispatch", "413", "impl-413");
363
+ ok("dispatch", "414", "impl-414");
364
+ const before = read().rows;
365
+
366
+ // #420 is keyed to the PR but is an implementer's own row (live or settled).
367
+ assert.equal(ok("settle", "impl-412", "PR#420").line, "#412 impl-412=PR#420");
368
+ assert.equal(ok("settle", "impl-413=PR#421").line, "#413 impl-413=PR#421");
369
+ // No row keyed #500 at all; #777 belongs to a PR nobody here settles to.
370
+ assert.equal(ok("settle", "impl-414", "PR#500").line, "#414 impl-414=PR#500");
371
+ assert.deepEqual(read().rows, before.map((r) => r
372
+ .replace(/^#412 impl-412$/, "#412 impl-412=PR#420")
373
+ .replace(/^#413 impl-413$/, "#413 impl-413=PR#421")
374
+ .replace(/^#414 impl-414$/, "#414 impl-414=PR#500")));
375
+ assert.ok(read().rows.includes("#777 fix-pr-777"));
376
+ });
377
+
378
+ // The fold's key match is exact, never a prefix: `#42` must not absorb an
379
+ // unrelated row keyed `#420` just because one key is a prefix of the other.
380
+ test("settle to PR#42 does not fold an unrelated row keyed #420", (t) => {
381
+ const { ok, read } = fixture(t);
382
+ ok("row", "420", "unrelated other content for #420");
383
+ ok("dispatch", "100", "impl-100");
384
+ assert.equal(ok("settle", "impl-100", "PR#42").line, "#100 impl-100=PR#42");
385
+ assert.deepEqual(read().rows, ["#420 unrelated other content for #420", "#100 impl-100=PR#42"]);
386
+ });
387
+
388
+ // #1876 follow-up: a row that already names a PR before this settle writes
389
+ // to it must never be folded from — `rowPr()` and the tick's `PR_MENTION`
390
+ // read only the FIRST `PR#` mention on a row, so folding here would let a
391
+ // second PR's content ride on the first PR's identity (a replacement
392
+ // implementer opening a second, different PR for the same ticket), or bury
393
+ // the row's own fresher `review=` state under an older one the tick reads
394
+ // last. The pre-existing two-row shape is left as it was rather than risk
395
+ // either.
396
+ test("settle does not fold when its own row already names a PR", (t) => {
397
+ const { ok, read } = fixture(t);
398
+ ok("dispatch", "100", "impl-100");
399
+ ok("settle", "impl-100", "PR#150");
400
+ ok("dispatch", "100", "impl-100-b");
401
+ ok("dispatch", "160", "fix-pr-160");
402
+ ok("row", "160", "fix-pr-160 · review=member:review-pr-160");
403
+ assert.equal(ok("settle", "impl-100-b", "PR#160").line, "#100 impl-100=PR#150 · impl-100-b=PR#160");
404
+ assert.deepEqual(read().rows, [
405
+ "#100 impl-100=PR#150 · impl-100-b=PR#160",
406
+ "#160 fix-pr-160 · review=member:review-pr-160",
407
+ ]);
408
+ });
409
+
410
+ // #1876 follow-up: a row keyed `#M` with no impl- token is not always
411
+ // dispatch's PR-M fallback — a mistyped PR number can coincide with an
412
+ // unrelated ticket row (an Exclusion, here) that carries no PR-bound member
413
+ // token at all. The fold must tell the two apart positively, not merely by
414
+ // the absence of an impl- token, or a typo silently deletes real state a
415
+ // settled member can never restore.
416
+ test("settle to a mistyped PR number does not fold an unrelated row with no PR-bound token", (t) => {
417
+ const { ok, read } = fixture(t);
418
+ ok("row", "358", "excluded · behind-pr:#346");
419
+ ok("dispatch", "351", "impl-351");
420
+ assert.equal(ok("settle", "impl-351", "PR#358").line, "#351 impl-351=PR#358");
421
+ assert.deepEqual(read().rows, ["#358 excluded · behind-pr:#346", "#351 impl-351=PR#358"]);
422
+ });
423
+
424
+ // Two genuinely separate PR-bound dispatches (a fix-pr and, after its own
425
+ // settle, a finisher-pr replacement) can land on the same fallback row via
426
+ // runDispatch()'s rowKey fallback — not just one `row` call's worth of
427
+ // text — and an unrelated row between the fallback and the ticket must not
428
+ // disturb the splice/index-repair distance from either side.
429
+ test("the fold carries both families' settled tokens from separate dispatches, across an intervening unrelated row", (t) => {
430
+ const { ok, read } = fixture(t);
431
+ ok("dispatch", "900", "fix-pr-900");
432
+ ok("settle", "fix-pr-900", "failed");
433
+ ok("dispatch", "800", "impl-800");
434
+ ok("dispatch", "900", "finisher-pr-900-b");
435
+ ok("settle", "finisher-pr-900-b", "labelled");
436
+ ok("dispatch", "700", "impl-700");
437
+ assert.deepEqual(read().rows, ["#900 fix-pr-900=failed · finisher-pr-900-b=labelled", "#800 impl-800", "#700 impl-700"]);
438
+ assert.equal(ok("settle", "impl-700", "PR#900").line, "#700 impl-700=PR#900 · fix-pr-900=failed · finisher-pr-900-b=labelled");
439
+ assert.deepEqual(read().rows, ["#800 impl-800", "#700 impl-700=PR#900 · fix-pr-900=failed · finisher-pr-900-b=labelled"]);
440
+ });
441
+
442
+ test("drain writes one marker a later reader recognises, and it holds supply alone", (t) => {
443
+ const { ok, read, bytes, refused } = fixture(t);
444
+ ok("dispatch", "410", "impl-410");
445
+ const reason = "maintainer asked to stop\n## Rows\n- #1 phantom";
446
+ assert.deepEqual(ok("drain", reason), { drain: reason, created: true });
447
+ const l = read();
448
+ assert.equal(l.drain, reason);
449
+ assert.deepEqual(l.rows, ["#410 impl-410"], "the reason is one escaped entry, never a line the parser reads back");
450
+ assert.match(bytes(), /^## Drain\n\n- maintainer asked to stop\\n## Rows\\n- #1 phantom$/m);
451
+ // One marker: a second drain reports the standing one and writes nothing.
452
+ const before = bytes();
453
+ assert.deepEqual(ok("drain", "again"), { drain: reason, created: false });
454
+ assert.equal(bytes(), before);
455
+ // Supply stops — a fresh implementer or a replacement for a live one...
456
+ refused(["dispatch", "412", "impl-412"], /the run is draining \(maintainer asked to stop\n## Rows\n- #1 phantom\) — no implementer dispatch/);
457
+ refused(["dispatch", "410", "impl-410-b"], /the run is draining/);
458
+ // ...and everything else keeps firing until the open PRs are merged.
459
+ ok("settle", "impl-410", "released");
460
+ ok("dispatch", "346", "fix-pr-346");
461
+ ok("dispatch", "346", "finisher-pr-346");
462
+ assert.equal(ok("dispatch", "merge-bot").member, "merge-bot-1");
463
+ });
464
+
465
+ test("drain needs a reason", (t) => {
466
+ const { refused } = fixture(t);
467
+ refused(["drain"], /usage: ledger\.mjs drain "<reason>"/);
468
+ refused(["drain", " "], /usage: ledger\.mjs drain "<reason>"/);
469
+ });
470
+
471
+ test("a ledger written before ## Dispatched existed reads as none dispatched and not draining, and survives a dispatch", (t) => {
472
+ const { ok, read } = fixture(t, "# Fleet run ledger\n\n## Rows\n\n- #7 impl-7 · class=routine\n\n## Filed\n\n- #8 a filed subject\n\n## Ruled\n\n- #9 MERGE · green\n");
473
+ const legacy = { rows: ["#7 impl-7 · class=routine"], filed: ["#8 a filed subject"], ruled: ["#9 MERGE · green"] };
474
+ assert.deepEqual(read(), { ...legacy, dispatched: [], drain: null });
475
+ assert.equal(ok("dispatch", "merge-bot").member, "merge-bot-1");
476
+ assert.deepEqual(read(), { ...legacy, dispatched: ["merge-bot-1"], drain: null });
477
+ });
478
+
479
+ // #1799 fix-applier follow-up: a `## Dispatched` entry this grammar cannot
480
+ // parse used to read, via `parseToken(e)?.name`, as "not this member" —
481
+ // silently treating a corrupted section as though the member it names were
482
+ // free, in both dispatch's duplicate guard and settle's lookup.
483
+ test("a `## Dispatched` entry this grammar cannot parse refuses dispatch and settle, naming it, rather than reading as absent", (t) => {
484
+ const body = "# Fleet run ledger\n\n## Rows\n\n## Dispatched\n\n- impl-412x\n\n## Filed\n\n## Ruled\n";
485
+ const { refused } = fixture(t, body);
486
+ refused(["dispatch", "412", "impl-412"], /## Dispatched has an entry 'impl-412x' this grammar cannot parse/);
487
+ refused(["settle", "impl-412", "PR#420"], /## Dispatched has an entry 'impl-412x' this grammar cannot parse/);
488
+ });
489
+
490
+ // A replacement's own name is never a duplicate of its predecessor's, so the
491
+ // exact-name guard above lets it through — but the predecessor is still live,
492
+ // and the spec counts liveness as "unsettled impl- tokens" per family+number,
493
+ // not per exact name. Two live tokens for #412 would double-count it.
494
+ test("dispatch refuses a replacement while its predecessor is still live, in ## Dispatched or on a row", (t) => {
495
+ const { ok, refused, read } = fixture(t);
496
+ ok("dispatch", "412", "impl-412");
497
+ refused(["dispatch", "412", "impl-412-b"], /impl-412 is still live — `settle impl-412 killed`/);
498
+ ok("settle", "impl-412", "killed");
499
+ // The predecessor is settled now: the replacement is no longer refused.
500
+ assert.equal(ok("dispatch", "412", "impl-412-b").line, "#412 impl-412=killed · impl-412-b");
501
+ assert.deepEqual(read().dispatched, ["impl-412=killed", "impl-412-b"]);
502
+
503
+ // The same refusal when the live token was `row`'s, never `dispatch`'s.
504
+ ok("row", "415", "impl-415");
505
+ refused(["dispatch", "415", "impl-415-b"], /impl-415 is still live — `settle impl-415 killed`/);
506
+ });
507
+
508
+ // `load()`'s one read path for every subcommand: the write side (`drain`'s
509
+ // own `created` guard) already refuses a second marker, but a corrupted file
510
+ // carrying two anyway used to have its second `## Drain` bullet silently
511
+ // dropped by `section(DRAIN)[0] ?? null`, with no warning on either stream.
512
+ test("a ledger carrying two `## Drain` entries refuses to load rather than silently keeping only the first", (t) => {
513
+ const body = "# Fleet run ledger\n\n## Rows\n\n## Dispatched\n\n## Filed\n\n## Ruled\n\n## Drain\n\n- first reason\n- second reason\n";
514
+ const { refused } = fixture(t, body);
515
+ refused(["read"], /has 2 `## Drain` entries — one marker per run/);
516
+ });
@@ -0,0 +1,85 @@
1
+ // The run ledger's member grammar (#1799; spec 2026-09-24 § 6 §2, ADR 0012
2
+ // Decision 5): a member's token is `<member>` while it is live and
3
+ // `<member>=<outcome>` once settled. `ledger.mjs dispatch` writes the bare
4
+ // token and `ledger.mjs settle` rewrites it, so a reader derives every
5
+ // liveness count from the ledger file alone instead of from the controller's
6
+ // memory of what it dispatched.
7
+ //
8
+ // A module of its own, not a function inside ledger.mjs, because ledger.mjs is
9
+ // a CLI that parses argv and exits on import — and `fleet-tick.mjs` is to read
10
+ // this same grammar (#1803). A second copy of it there would be two readings
11
+ // of which members are live, free to drift apart.
12
+ //
13
+ // Rows stay freeform text. Only a token whose name part is a member name is
14
+ // claimed here; everything else a row carries (`class=routine`, `ports=`,
15
+ // `ci=`, `held-behind:#M`, merge-bot's `conflict-hold:#<pr>`, #1773's
16
+ // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member and is left
17
+ // alone.
18
+
19
+ // The outcome vocabulary, verbatim from the spec. A word is matched exactly,
20
+ // except the three that carry a value, which match OUTCOME_PATTERNS below.
21
+ const FAMILIES = {
22
+ impl: { label: "impl-N", bound: "ticket", outcomes: ["PR#M", "bailed", "released", "killed", "tier-mismatch"] },
23
+ "fix-pr": { label: "fix-pr-M", bound: "pr", outcomes: ["applied:<head>", "no-op", "failed", "killed"] },
24
+ "finisher-pr": { label: "finisher-pr-M", bound: "pr", outcomes: ["labelled", "failed", "killed", "halted:<cause>"] },
25
+ "merge-bot": { label: "merge-bot-n", bound: null, outcomes: ["done", "killed"] },
26
+ };
27
+ // A finisher halt's causes (#2083): the finisher worked correctly and refused
28
+ // to label, which `failed` (it crashed or gave up) does not say. `unreadable`,
29
+ // `missing` and `absent` are duty 1's audit-read halts (#1106).
30
+ export const HALT_CAUSES = ["live-editor", "rebase", "past-pin", "unreadable", "missing", "absent", "other"];
31
+ const OUTCOME_PATTERNS = {
32
+ "PR#M": /^PR#[1-9][0-9]*$/,
33
+ "applied:<head>": /^applied:[0-9a-f]{7,40}$/i,
34
+ "halted:<cause>": new RegExp(`^halted:(?:${HALT_CAUSES.join("|")})$`),
35
+ };
36
+
37
+ // A number with no leading zero, so `impl-0412` cannot be a second name for
38
+ // `impl-412`. A single trailing lowercase letter is a replacement's retry
39
+ // suffix (`impl-<N>-b` — member-record.mjs has -b, -c and -d observed);
40
+ // merge bots take none, because a replacement for a dead bot gets a new n.
41
+ // Attempts on one number order by it: no suffix first, then by letter.
42
+ const MEMBER = /^(impl|fix-pr|finisher-pr|merge-bot)-([1-9][0-9]*)(-[a-z])?$/;
43
+
44
+ /** `{name, family, number, retry, bound}` for a member name, else null.
45
+ * `retry` is the suffix letter (`"b"` for `impl-412-b`), null for none.
46
+ * `bound` is "ticket", "pr", or null for a merge bot, which works neither. */
47
+ export function parseMember(name) {
48
+ const m = MEMBER.exec(name);
49
+ if (!m || (m[1] === "merge-bot" && m[3])) return null;
50
+ return { name, family: m[1], number: Number(m[2]), retry: m[3] ? m[3].slice(1) : null, bound: FAMILIES[m[1]].bound };
51
+ }
52
+
53
+ /**
54
+ * One whitespace-delimited token: null when it is not a member token at all,
55
+ * otherwise the member plus `outcome` (null while live) and `error` (null
56
+ * unless the outcome is outside its family's vocabulary). A malformed outcome
57
+ * is reported rather than dropped, so a reader can refuse the row instead of
58
+ * counting the member live or gone on a guess.
59
+ */
60
+ export function parseToken(token) {
61
+ const eq = token.indexOf("=");
62
+ const member = parseMember(eq === -1 ? token : token.slice(0, eq));
63
+ if (!member) return null;
64
+ if (eq === -1) return { ...member, outcome: null, error: null };
65
+ const outcome = token.slice(eq + 1);
66
+ const f = FAMILIES[member.family];
67
+ const ok = f.outcomes.some((o) => (OUTCOME_PATTERNS[o] ? OUTCOME_PATTERNS[o].test(outcome) : o === outcome));
68
+ return {
69
+ ...member,
70
+ outcome,
71
+ error: ok ? null : `'${outcome}' is not an outcome of ${f.label} — expected ${f.outcomes.join(" | ")}`,
72
+ };
73
+ }
74
+
75
+ /** Every member token in a row's text, in order. */
76
+ export function memberTokens(text) {
77
+ return text.split(/\s+/).filter(Boolean).map(parseToken).filter(Boolean);
78
+ }
79
+
80
+ /** The name the next merge bot takes: 1 + the `merge-bot-` entries in
81
+ * `## Dispatched`, settled ones included. One ledger per run, so n restarts
82
+ * at 1 with every run. */
83
+ export function nextMergeBot(dispatched) {
84
+ return `merge-bot-${dispatched.map(parseToken).filter((t) => t?.family === "merge-bot").length + 1}`;
85
+ }