@feigi/fleet-ctl 3.141.0 → 3.141.2

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.
@@ -269,8 +269,10 @@ cause `other`, with both runs — the mutant's and the unmutated tree's — as
269
269
  evidence; label nothing. A kill's evidence line goes in your report.
270
270
 
271
271
  **Duty 3 is one script, and its exit code is your verdict.**
272
- `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
273
- (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
272
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin> --kill '<evidence line>'`
273
+ (the full SHA; `--kill` carries your kill's evidence line as one quoted
274
+ argument, and a PR whose mutation you skipped — an Inert diff or a Ticketless
275
+ PR — omits it). It confirms exactly one of `patch`/`minor`/`major` is on the
274
276
  PR — a Ticketless PR with none gets `patch` added first — records the head you
275
277
  audited, adds `ready-to-merge`, and reads the labels
276
278
  back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
@@ -280,7 +282,9 @@ before the label, and the receipt names which it found. Exit 4 means the
280
282
  read-back does not carry the label, written or not. Exit 5 means the PR is a
281
283
  Ticketless PR whose diff is not inert, or whose Inert diff verdict could not
282
284
  look: the script posted the head record and added no label, and you are halted
283
- with cause `human`. Exit 2 means a `gh` call or the invocation itself failed:
285
+ with cause `human`. Exit 6 means a ticket PR whose diff is not inert, or whose
286
+ Inert diff verdict could not look, came without a `--kill` in the
287
+ `red: … ; baseline: …` grammar: the script wrote nothing. Exit 2 means a `gh` call or the invocation itself failed:
284
288
  report the stderr it printed. Every non-zero exit halts you, with cause `other`
285
289
  unless it is exit 5, with the receipt as evidence, and you do not run any of
286
290
  its steps by hand to get past it. A repo whose label list defines none of the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.141.0",
3
+ "version": "3.141.2",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -3,12 +3,13 @@
3
3
  // read as one: the release-label check is a precondition, and a finisher that
4
4
  // stopped after it reported `labelled` on a PR that never got the label.
5
5
  //
6
- // finisher-label.mjs --pr <M> --pin <sha> [--repo <dir>]
6
+ // finisher-label.mjs --pr <M> --pin <sha> [--kill <evidence line>] [--repo <dir>]
7
7
  //
8
8
  // `--pin` is the full 40-hex head the finisher audited; `--repo` is the
9
9
  // directory `gh` runs in (it resolves the repository from there), the cwd when
10
- // omitted. Reached through the Resolver: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run
11
- // finisher-label.mjs ...`.
10
+ // omitted. `--kill` is the evidence line of the acceptance mutation's kill,
11
+ // read only at step 1b. Reached through the Resolver:
12
+ // `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run finisher-label.mjs ...`.
12
13
  //
13
14
  // Steps, in this order, each one only if every earlier one held:
14
15
  //
@@ -24,10 +25,14 @@
24
25
  // list is read only when the PR carries none of them — one on the PR
25
26
  // proves it is defined — and a list that fills the limit it was read with
26
27
  // proves nothing, so it is exit 2 rather than a skipped count.
27
- // 1b on a Ticketless PR, finisher-scope.mjs's Inert diff verdict at `--pin`,
28
- // run in-process. A diff that is not inert, or a verdict that could not
29
- // look, stops after step 2: the head record is posted, the label is not
30
- // added, and the exit is 5.
28
+ // 1b finisher-scope.mjs's Inert diff verdict at `--pin`, run in-process on
29
+ // every PR. On a Ticketless PR a diff that is not inert, or a verdict
30
+ // that could not look, stops after step 2: the head record is posted,
31
+ // the label is not added, and the exit is 5. On a ticket PR either one
32
+ // needs a `--kill` claim — non-empty and in the finisher's evidence-line
33
+ // grammar, `red: … ; baseline: …` — and without one the exit is 6 and
34
+ // nothing is written. The claim is taken on its word: the script cannot
35
+ // rerun the mutation. An inert diff, or a Ticketless PR, ignores `--kill`.
31
36
  // 2 comment `ready-to-merge-head: <pin>`, the record the merge bot reads as
32
37
  // the head the label was applied to — skipped when the newest such
33
38
  // comment already names this pin.
@@ -48,8 +53,8 @@
48
53
  //
49
54
  // Stdout is always one JSON line, the receipt:
50
55
  //
51
- // {pr, pin, ticketless, releaseLabels, patchAdded, inert, commented, added,
52
- // readBack, exit, firstRead [, step, error]}
56
+ // {pr, pin, ticketless, releaseLabels, patchAdded, inert, kill, commented,
57
+ // added, readBack, exit, firstRead [, step, error] [, killGiven]}
53
58
  //
54
59
  // ticketless the Ticketless test's answer, null when it never got one
55
60
  // releaseLabels the release labels the PR carried (`patch` once added to a
@@ -57,6 +62,7 @@
57
62
  // never got an answer
58
63
  // patchAdded this run added `patch`
59
64
  // inert the Inert diff verdict object, null when it never ran
65
+ // kill the `--kill` claim step 1b accepted, null when it took none
60
66
  // commented this run posted the head record
61
67
  // added this run wrote the label
62
68
  // readBack every label name the step 4 read carried, null if it never ran
@@ -64,6 +70,8 @@
64
70
  // step on exit 2 only, the step that failed: `pin`, `repo`,
65
71
  // `label-map`, or the step whose `gh` call failed
66
72
  // error on exit 2 only, what `gh` (or the invocation) said
73
+ // killGiven on exit 6 only, what `--kill` carried, null when it was
74
+ // not given
67
75
  //
68
76
  // A usage error that never reaches `gh` — a missing or unknown flag — is a
69
77
  // refusal on stderr with no receipt, as in every other script's `die()`.
@@ -80,6 +88,8 @@
80
88
  // 5 a Ticketless PR whose diff is not inert, or whose verdict could not
81
89
  // look: the head record is posted and the label is not added, so the
82
90
  // maintainer's `ready-to-merge` is the merge
91
+ // 6 a ticket PR whose diff is not inert, or whose verdict could not look,
92
+ // with no well-formed `--kill` claim — nothing was written
83
93
 
84
94
  import { spawnSync } from "node:child_process";
85
95
  import { statSync } from "node:fs";
@@ -96,10 +106,10 @@ const NAME = "finisher-label";
96
106
 
97
107
  const die = makeDie(NAME);
98
108
  const { arg, numArg, sweep, stray } = defineFlags(die, {
99
- flags: { pr: "value", pin: "value", repo: "value" },
109
+ flags: { pr: "value", pin: "value", repo: "value", kill: "value" },
100
110
  });
101
111
 
102
- const USAGE = "usage: finisher-label.mjs --pr <M> --pin <sha> [--repo <dir>]";
112
+ const USAGE = "usage: finisher-label.mjs --pr <M> --pin <sha> [--kill <evidence line>] [--repo <dir>]";
103
113
 
104
114
  // The sweep runs before the required-flag check so a misspelt flag is named
105
115
  // as that, not buried under a missing-flag usage line.
@@ -108,6 +118,12 @@ stray();
108
118
  const pr = numArg("pr");
109
119
  const pinArg = arg("pin");
110
120
  const repo = arg("repo");
121
+ // Read by hand past arg(), which refuses an empty value as a usage error: an
122
+ // empty claim is a malformed kill, refused at exit 6 like a missing one, and
123
+ // only where the verdict needs a claim. arg() still reads the absent case, so
124
+ // a `--kill=` form is refused by name rather than read as no claim.
125
+ const killAt = process.argv.indexOf("--kill");
126
+ const killArg = killAt === -1 ? arg("kill") : (process.argv[killAt + 1] ?? "");
111
127
  if (pr === null || pinArg === null) die(USAGE);
112
128
 
113
129
  const receipt = {
@@ -117,6 +133,7 @@ const receipt = {
117
133
  releaseLabels: null,
118
134
  patchAdded: false,
119
135
  inert: null,
136
+ kill: null,
120
137
  commented: false,
121
138
  added: false,
122
139
  readBack: null,
@@ -225,11 +242,30 @@ if (found.length === 0) {
225
242
  receipt.releaseLabels = found;
226
243
  }
227
244
 
228
- // --- 1b: the Inert diff verdict, on a Ticketless PR ------------------------
245
+ // --- 1b: the Inert diff verdict ---------------------------------------------
229
246
  // No ticket gives a Ticketless PR its ruling or its acceptance mutation, so it
230
247
  // merges unattended only when its whole diff is inert; otherwise the head is
231
- // recorded and the maintainer's label is the merge.
232
- if (ticketless) receipt.inert = inertVerdict({ worktree: resolve(repo ?? "."), pin });
248
+ // recorded and the maintainer's label is the merge. A ticket PR whose diff is
249
+ // not inert merges on its acceptance mutation's kill, so it is labelled only
250
+ // with that kill's evidence line in hand.
251
+ receipt.inert = inertVerdict({ worktree: resolve(repo ?? "."), pin });
252
+ const why = receipt.inert.verdict === "unknown" ? `its diff could not be read (${receipt.inert.reason})` : "its diff is not inert";
253
+
254
+ // The finisher's evidence-line grammar,
255
+ // `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`,
256
+ // checked for its two halves, each non-blank, on one line (`.` stops at a newline).
257
+ const EVIDENCE = /^red:(.*?); baseline:(.*)$/;
258
+ const evidence = (s) => {
259
+ const m = EVIDENCE.exec(s ?? "");
260
+ return m !== null && m[1].trim() !== "" && m[2].trim() !== "";
261
+ };
262
+ if (!ticketless && receipt.inert.exit !== 0) {
263
+ if (!evidence(killArg)) {
264
+ const claim = killArg === null ? "no --kill claim was given" : `the --kill claim is not an evidence line (red: … ; baseline: …): ${JSON.stringify(killArg)}`;
265
+ finish(6, { killGiven: killArg }, `the PR is a ticket PR and ${why}, and ${claim}; nothing was written`);
266
+ }
267
+ receipt.kill = killArg;
268
+ }
233
269
 
234
270
  // --- 2: the head record ----------------------------------------------------
235
271
  // The newest record wins, the way the merge bot reads it: a matching record
@@ -243,7 +279,6 @@ if (!recorded) {
243
279
  }
244
280
 
245
281
  if (ticketless && receipt.inert.exit !== 0) {
246
- const why = receipt.inert.verdict === "unknown" ? `its diff could not be read (${receipt.inert.reason})` : "its diff is not inert";
247
282
  finish(5, {}, `the PR is a Ticketless PR and ${why}: the head is recorded and ${LABEL} is left to the maintainer`);
248
283
  }
249
284
 
@@ -583,12 +583,13 @@ export function deriveLabelMap({ table, live, cache, answers = new Map() }) {
583
583
  return { kind: "certain", roles: certain, origin };
584
584
  }
585
585
 
586
- // The three inputs of a derivation, read the same way for `ensure` and `set`:
587
- // the table, the live label list and the cache (null when absent or not
588
- // parsing, which is derived again).
586
+ // The three inputs of a derivation, read the same way for `ensure` and `set`,
587
+ // in this order: the table, the cache (null when absent or not parsing, which
588
+ // is derived again) and the live label list. A local fault is named before the
589
+ // network is asked, so a `gh` failure cannot hide it and its refusal never
590
+ // waits on `gh`.
589
591
  function readDerivationInputs(cwd) {
590
592
  const { top, table } = readTriageTable({ cwd });
591
- const live = readLiveLabels({ cwd: top });
592
593
  let cache = null;
593
594
  try {
594
595
  cache = loadCache(fleetFile(LABEL_MAP_FILE, { cwd }));
@@ -599,6 +600,7 @@ function readDerivationInputs(cwd) {
599
600
  // refusal is the reader's own, naming the errno and the repair.
600
601
  if (e.cause) throw new LabelMapUnavailable(`${e.message}; nothing written`);
601
602
  }
603
+ const live = readLiveLabels({ cwd: top });
602
604
  return { top, table, live, cache };
603
605
  }
604
606
 
@@ -244,6 +244,8 @@ head is not part of it, and duty 1 audits that head separately.
244
244
 
245
245
  **Duty 3 holds a Ticketless PR whose diff is not inert.** `finisher-label.mjs` adds `patch` to a Ticketless PR that carries no release label, then runs the Inert diff verdict in-process at your pin. A diff that is not inert, or a verdict that could not look, gets the `ready-to-merge-head:` record and no `ready-to-merge`, and the script exits 5: halt with cause `human`. No ticket gives that PR a ruling or a mutation, so the maintainer's `ready-to-merge` is the merge. The merge bot merges it off the record at the pinned head, and a head that moved after the record is merged by hand.
246
246
 
247
+ **Duty 3 holds a ticket PR whose diff is not inert until it is handed the kill.** `finisher-label.mjs` runs the same Inert diff verdict on a ticket PR. A diff that is not inert, or a verdict that could not look, is labelled only when the call carries `--kill '<evidence line>'`, the kill's evidence line in the `red: … ; baseline: …` grammar, which the receipt records as `kill`. Without one, or with one not in that grammar, the script writes nothing — no head record, no label — and exits 6: halt with cause `other` and the receipt as evidence. The script takes the claim on its word; it cannot rerun the mutation. An Inert diff and a Ticketless PR ran no mutation, so they omit `--kill`, and the script ignores one they pass.
248
+
247
249
  ## Whatever you verify by running, run in a tree nobody else owns
248
250
 
249
251
  **Whatever you verify by RUNNING, run in a tree nobody else owns.**