@feigi/fleet-ctl 3.120.0 → 3.121.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.120.0",
3
+ "version": "3.121.0",
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": {
@@ -168,6 +168,10 @@
168
168
  // `NEED <what> …` line, at the left margin, for the controller to make by
169
169
  // hand.
170
170
  //
171
+ // The labels this script compares and writes are the Label map's strings
172
+ // (label-map.mjs), read once at the command's entry; the label names in this
173
+ // header are Label roles, and the map's string stands where it says one.
174
+ //
171
175
  // Exit: 0 every write made and the tick exited 0. 2 a usage error, refused
172
176
  // before anything is written or ticked: an unknown kind or flag, a `--reason`
173
177
  // that is empty or beside any kind but `drain` and `undrain`, a `--session`
@@ -175,7 +179,8 @@
175
179
  // a name that is no ledger member, no session directory, a session directory
176
180
  // that cannot be listed, a heartbeat file that cannot be used), a member of
177
181
  // the wrong family, a review path outside the PR's partition or a file that
178
- // is no review result, a ledger or phase-0 receipt that cannot be read. A
182
+ // is no review result, a ledger or phase-0 receipt that cannot be read, no
183
+ // valid Label map (the message names `label-map.mjs ensure`). A
179
184
  // ledger write's own refusal — `settle`'s 3 (the report's claim and the world
180
185
  // disagree) or 2, `token`'s or `review`'s 2 — passes its exit and message
181
186
  // through, as do `closeout.mjs begin`'s and `reopen`'s 2 or 3 and the
@@ -194,6 +199,7 @@ import { makeDie, defineFlags, isDigits, writeAll } from "./arg.mjs";
194
199
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
195
200
  import { gitEnv } from "./git-env.mjs";
196
201
  import { isCLI } from "./is-cli.mjs";
202
+ import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
197
203
  import { BRIEFS, REVIEW, REVIEWED, REVIEWER, dispositionsToken, memberTokens, nextReviewerName, parseDispatchedEntry, parseMember, parseToken, readRetired, rowNums } from "./ledger-grammar.mjs";
198
204
  import { NO_TRANSCRIPT_AFTER_DEFAULT, PARKS, controllerState, foldLedger, parkedToken } from "./fleet-tick.mjs";
199
205
  import { phase0Gate, readRunReceipt, tickCaps } from "./phase0-receipt.mjs";
@@ -206,7 +212,6 @@ const SCRIPTS = dirname(fileURLToPath(import.meta.url));
206
212
  const MAX_BUFFER = 64 * 1024 * 1024;
207
213
  const GH_TIMEOUT_MS = 60_000;
208
214
  const CHILD_TIMEOUT_MS = 300_000;
209
- const READY = "ready-to-merge";
210
215
 
211
216
  const KINDS = {
212
217
  "impl-report": { args: ["<member>"], family: "impl" },
@@ -227,14 +232,16 @@ const FLAGS = { "in-flight": "value", reason: "value", session: "value" };
227
232
  const USAGE = `usage: ${NAME}.mjs <kind> <args> [--in-flight <n>] — kinds: `
228
233
  + Object.entries(KINDS).map(([k, { args, flag }]) => [k, ...args, ...(flag ? [flag] : [])].join(" ")).join(", ");
229
234
 
230
- // The label each `bailCause` demotes to, and the relabel template's kind.
231
- // `fixed` takes no label: it closes the ticket once `verify-sha.sh` finds the
232
- // commit on origin/main, and demotes to `needs-triage` when it does not.
235
+ // The Label role each `bailCause` demotes to, and the relabel template's kind;
236
+ // the tracker's string for the role is the map's, resolved where the label is
237
+ // written. `fixed` takes no role: it closes the ticket once `verify-sha.sh`
238
+ // finds the commit on origin/main, and demotes to `needs-triage` when it does
239
+ // not.
233
240
  export const BAILS = {
234
- undecided: { label: "needs-triage", kind: "needs-triage", flag: "line" },
235
- fork: { label: "ready-for-human", kind: "fork", flag: "options" },
236
- hands: { label: "ready-for-human", kind: "hands" },
237
- covered: { label: "ready-for-human", kind: "covered", flag: "detail" },
241
+ undecided: { role: "needs-triage", kind: "needs-triage", flag: "line" },
242
+ fork: { role: "ready-for-human", kind: "fork", flag: "options" },
243
+ hands: { role: "ready-for-human", kind: "hands" },
244
+ covered: { role: "ready-for-human", kind: "covered", flag: "detail" },
238
245
  fixed: { kind: "fixed", flag: "detail" },
239
246
  };
240
247
  // The commit a `fixed` bail's detail opens with.
@@ -415,7 +422,8 @@ function relabelArgs(cause, detail) {
415
422
  }
416
423
 
417
424
  // The comment `dispatch-prompt.mjs render relabel` renders for a bail, or null
418
- // when there is none (the NEED, named `what`, is printed here).
425
+ // when there is none (the NEED, named `what`, is printed here). The template
426
+ // names the role `ready-for-agent`; the comment filed names the map's string.
419
427
  function rendered(ev, ticket, cause, detail, what) {
420
428
  const relabel = relabelArgs(cause, detail);
421
429
  if (relabel.why !== undefined) {
@@ -427,18 +435,23 @@ function rendered(ev, ticket, cause, detail, what) {
427
435
  ev.need(`${what} #${ticket} — dispatch-prompt.mjs render relabel refused: ${said(r)}`);
428
436
  return null;
429
437
  }
430
- return r.stdout;
438
+ return r.stdout.replaceAll("`ready-for-agent`", `\`${ev.labels["ready-for-agent"]}\``);
431
439
  }
432
440
 
441
+ // The map's strings for the labels a pulled ticket carries, which a demotion
442
+ // or a close takes off.
443
+ const pulledLabels = (ev) => [ev.labels["ready-for-agent"], ev.labels["in-progress"]];
444
+
433
445
  // Moves #ticket to `label`, then posts the comment `body()` returns, if any.
434
446
  // False when the move could not be made, so nothing after it may run.
435
447
  function demote(ev, ticket, label, cause, body) {
436
448
  const seen = ev.comments("issue", ticket, `relabel #${ticket} ${label}`);
437
449
  if (seen === null) return false;
438
- if (seen.labels.includes(label) && !seen.labels.includes("ready-for-agent") && !seen.labels.includes("in-progress")) {
450
+ const pulled = pulledLabels(ev);
451
+ if (seen.labels.includes(label) && !pulled.some((l) => seen.labels.includes(l))) {
439
452
  ev.note(`#${ticket} already ${label}`);
440
453
  } else {
441
- const e = gh(["issue", "edit", String(ticket), "--remove-label", "ready-for-agent", "--remove-label", "in-progress", "--add-label", label]);
454
+ const e = gh(["issue", "edit", String(ticket), ...pulled.flatMap((l) => ["--remove-label", l]), "--add-label", label]);
442
455
  if (e.status !== 0) {
443
456
  ev.need(`relabel #${ticket} ${label} — gh issue edit failed: ${said(e)}`);
444
457
  return false;
@@ -461,7 +474,7 @@ function fixed(ev, ticket, detail) {
461
474
  }
462
475
  const v = run("sh", [join(SCRIPTS, "verify-sha.sh"), "main", sha]);
463
476
  if (v.status === 1) {
464
- return demote(ev, ticket, "needs-triage", "fixed", () => `*Relabelled by the fleet controller.* Pulled for implementation and returned as already fixed by ${sha}: ${sha} not on origin/main.`);
477
+ return demote(ev, ticket, ev.labels["needs-triage"], "fixed", () => `*Relabelled by the fleet controller.* Pulled for implementation and returned as already fixed by ${sha}: ${sha} not on origin/main.`);
465
478
  }
466
479
  if (v.status !== 0) {
467
480
  ev.need(`close #${ticket} — verify-sha.sh main ${sha} could not answer (${v.how}): ${said(v)}`);
@@ -482,7 +495,7 @@ function fixed(ev, ticket, detail) {
482
495
  }
483
496
  ev.note(`closed #${ticket}: fixed by ${sha}`);
484
497
  }
485
- const stale = ["ready-for-agent", "in-progress"].filter((l) => seen.labels.includes(l));
498
+ const stale = pulledLabels(ev).filter((l) => seen.labels.includes(l));
486
499
  if (stale.length > 0) {
487
500
  const e = gh(["issue", "edit", String(ticket), ...stale.flatMap((l) => ["--remove-label", l])]);
488
501
  if (e.status !== 0) ev.need(`unlabel #${ticket} ${stale.join(" ")} — gh issue edit failed: ${said(e)}`);
@@ -501,7 +514,7 @@ function bailed(ev, member) {
501
514
  const detail = read.report.bailDetail;
502
515
  const moved = cause === "fixed"
503
516
  ? fixed(ev, ticket, detail)
504
- : demote(ev, ticket, BAILS[cause].label, cause, () => rendered(ev, ticket, cause, detail, "relabel-comment"));
517
+ : demote(ev, ticket, ev.labels[BAILS[cause].role], cause, () => rendered(ev, ticket, cause, detail, "relabel-comment"));
505
518
  if (!moved) return;
506
519
  const release = run("sh", [join(SCRIPTS, "release-ticket.sh"), String(ticket), `impl-${ticket}`, "implementer", "--apply"]);
507
520
  if (release.status === 0) ev.note(`released #${ticket}`);
@@ -616,7 +629,7 @@ function finisherReport(ev, member) {
616
629
  }
617
630
  // The escalation is for a repair finisher that claims the label and reads
618
631
  // back none; a halt says why in its own comment above.
619
- if (self.retry === null || report?.outcome !== "labelled" || report.labelsReadBack.includes(READY)) return;
632
+ if (self.retry === null || report?.outcome !== "labelled" || report.labelsReadBack.includes(ev.labels["ready-to-merge"])) return;
620
633
  const earlier = ledgerMembers(ev.ledger)
621
634
  .filter((t) => t.family === "finisher-pr" && t.number === pr && (t.retry ?? "") < self.retry)
622
635
  .sort((a, b) => (a.retry ?? "").localeCompare(b.retry ?? "")).at(-1)?.name;
@@ -625,7 +638,7 @@ function finisherReport(ev, member) {
625
638
  const prior = ev.report(earlier);
626
639
  before = prior.state === "ok" ? `${earlier} read back: ${listed(prior.report.labelsReadBack)}` : `${earlier}'s report ${prior.path} is ${prior.state}`;
627
640
  }
628
- const body = `**${member}, a repair finisher, read back no \`${READY}\` on PR #${pr}.**\n\n`
641
+ const body = `**${member}, a repair finisher, read back no \`${ev.labels["ready-to-merge"]}\` on PR #${pr}.**\n\n`
629
642
  + `- ${member} read back: ${listed(report.labelsReadBack)}\n- ${before}`;
630
643
  const seen = ev.comments("pr", pr, `escalation-comment PR #${pr}`);
631
644
  if (seen !== null) ev.comment("pr", pr, body, seen, "escalation comment");
@@ -977,7 +990,14 @@ function main() {
977
990
  const caps = tickCaps(fleetDir);
978
991
  if (caps.error) die(`${caps.error} — nothing written`);
979
992
  const tickArgs = ["--apply", ...(inFlight === null ? caps.args : ["--in-flight", inFlight]), ...(kind === "heartbeat" ? ["--fold-unchanged"] : [])];
980
- const ev = new Event({ fleetDir, scratch, ledger: readLedger() });
993
+ let labels;
994
+ try {
995
+ labels = readLabelMap();
996
+ } catch (e) {
997
+ if (!(e instanceof LabelMapUnreadable)) throw e;
998
+ die(`${e.message} — nothing written`);
999
+ }
1000
+ const ev = new Event({ fleetDir, scratch, labels, ledger: readLedger() });
981
1001
  if (kind === "impl-report") implReport(ev, args[0]);
982
1002
  else if (kind === "fix-report") fixReport(ev, args[0]);
983
1003
  else if (kind === "finisher-report") finisherReport(ev, args[0]);
package/scripts/pull.mjs CHANGED
@@ -24,17 +24,19 @@
24
24
  // a Pull for a ticket whose ledger row is an exclusion naming no premise,
25
25
  // or one whose premise still stands, is this exit as well.
26
26
  // 2 could not look, named on stderr: a probe that did not answer, a write
27
- // that failed, a router that refused. `next --head <N>` runs a step that
28
- // failed again; when the failure came from applying an answer, the
29
- // question stands and the answer is given again. A router that refused
30
- // has its claim released and the Pull is over, `next --head <N>` starting
31
- // the ticket over; one whose claim could not be released leaves the Pull
32
- // at the route step with the claim standing, and `next` routes again. An
33
- // exclusion premise `gh` could not read is exit 2 when no other entry is
34
- // left, and always exit 2 when `next --head <N>` starts a Pull for the
35
- // ticket that holds it, the exclusion standing and no record written. An
36
- // unknown flag is exit 2 as well, as for every script that holds a command
37
- // line of its own.
27
+ // that failed, a router that refused, or no valid Label map (the message
28
+ // names `label-map.mjs ensure`; the labels the Pull compares, writes and
29
+ // names in its comments are the map's strings, read once at the command's
30
+ // entry). `next --head <N>` runs a step that failed again; when the failure
31
+ // came from applying an answer, the question stands and the answer is given
32
+ // again. A router that refused has its claim released and the Pull is over,
33
+ // `next --head <N>` starting the ticket over; one whose claim could not be
34
+ // released leaves the Pull at the route step with the claim standing, and
35
+ // `next` routes again. An exclusion premise `gh` could not read is exit 2
36
+ // when no other entry is left, and always exit 2 when `next --head <N>`
37
+ // starts a Pull for the ticket that holds it, the exclusion standing and no
38
+ // record written. An unknown flag is exit 2 as well, as for every script
39
+ // that holds a command line of its own.
38
40
  // 3 usage: any other mistake in the command line, or an answer the pending
39
41
  // question does not take. Nothing is recorded.
40
42
  // 10 a question is pending: its `QUESTION <qid>:` block, with the tokens it
@@ -136,6 +138,7 @@ import { isDigits, makeDie } from "./arg.mjs";
136
138
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
137
139
  import { gitEnv } from "./git-env.mjs";
138
140
  import { isCLI } from "./is-cli.mjs";
141
+ import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
139
142
  import { EXCLUDED_REASON, POLICY_CELL, memberTokens, parseRouting, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
140
143
  import { sessionFromReceipt } from "./phase0-receipt.mjs";
141
144
  import { briefPaths, briefText, defang, outOfScope, strandedRuling, ticketText } from "./ticket-text.mjs";
@@ -155,10 +158,6 @@ const EXPLORE_EVERY = 5;
155
158
  // The states that lift an exclusion's premise.
156
159
  const LIFTED = new Set(["MERGED", "CLOSED"]);
157
160
 
158
- const READY = "ready-for-agent";
159
- const TRIAGE = "needs-triage";
160
- const HUMAN = "ready-for-human";
161
-
162
161
  const USAGE = `usage: ${NAME}.mjs next [--head <N>] | ${NAME}.mjs answer <N> <qid> <token> [--path <p>] [--] [<text>…]`;
163
162
 
164
163
  // ── the comments the script posts ────────────────────────────────────────────
@@ -181,28 +180,31 @@ function handsParts(text) {
181
180
  }
182
181
 
183
182
  /**
184
- * The comment, and the label that replaces `ready-for-agent`, for a Q2 answer
185
- * other than `decided` — or, for `stranded-ruling`, for a ruling or triage
186
- * comment newer than the brief, `text` naming its heading line and its URL.
183
+ * The comment, and the label that replaces the `ready-for-agent` label, for a
184
+ * Q2 answer other than `decided` — or, for `stranded-ruling`, for a ruling or
185
+ * triage comment newer than the brief, `text` naming its heading line and its
186
+ * URL. `labels` is the Label map (role -> the tracker's string): the label
187
+ * returned and the labels the comment names are its strings.
187
188
  */
188
- export function relabel(token, text) {
189
+ export function relabel(token, text, labels) {
190
+ const { "ready-for-agent": ready, "ready-for-human": human } = labels;
189
191
  if (token === "stranded-ruling") {
190
192
  return {
191
- label: HUMAN,
192
- comment: `${RELABELLED} a ruling or triage comment is newer than the brief, and the Pull does not read it: ${text}. To make it the brief, rename its heading to \`## Agent Brief — ruling\` and drop anything that is not decided scope, or delete it; then restore \`${READY}\`.`,
193
+ label: human,
194
+ comment: `${RELABELLED} a ruling or triage comment is newer than the brief, and the Pull does not read it: ${text}. To make it the brief, rename its heading to \`## Agent Brief — ruling\` and drop anything that is not decided scope, or delete it; then restore \`${ready}\`.`,
193
195
  };
194
196
  }
195
197
  if (token === "needs-triage") {
196
198
  return {
197
- label: TRIAGE,
198
- comment: `${RELABELLED} the brief does not decide what to build. Missing decision: ${text}. Returning to /triage; \`${READY}\` restored once decided.`,
199
+ label: labels["needs-triage"],
200
+ comment: `${RELABELLED} the brief does not decide what to build. Missing decision: ${text}. Returning to /triage; \`${ready}\` restored once decided.`,
199
201
  };
200
202
  }
201
203
  if (token === "ready-for-human-fork") {
202
- return { label: HUMAN, comment: `${RELABELLED} the brief leaves a decision open. Open fork: ${text}.` };
204
+ return { label: human, comment: `${RELABELLED} the brief leaves a decision open. Open fork: ${text}.` };
203
205
  }
204
206
  const { cause, line } = handsParts(text);
205
- return { label: HUMAN, comment: `${RELABELLED} needs human hands — ${HANDS[cause]}: ${line}.` };
207
+ return { label: human, comment: `${RELABELLED} needs human hands — ${HANDS[cause]}: ${line}.` };
206
208
  }
207
209
 
208
210
  /** The comment a `yes` to Q1b closes the issue with. */
@@ -809,7 +811,7 @@ class Pull {
809
811
  } catch (e) {
810
812
  return this.stop(`cannot write ${this.p.issue}: ${e.message}`);
811
813
  }
812
- if (!issue.labels.some((l) => l?.name === READY)) return this.leave("relabelled elsewhere");
814
+ if (!issue.labels.some((l) => l?.name === this.p.labels["ready-for-agent"])) return this.leave("relabelled elsewhere");
813
815
  const stranded = strandedRuling(issue);
814
816
  if (stranded !== null) {
815
817
  if (typeof stranded.url !== "string") return this.stop(`gh issue view printed a ruling comment with no url: "${stranded.heading}"`);
@@ -1100,17 +1102,20 @@ class Pull {
1100
1102
 
1101
1103
  // Posts the cause's comment and swaps `ready-for-agent` for its label. One
1102
1104
  // comment per cause: an edit that failed after its comment landed is run
1103
- // again without a second comment.
1105
+ // again without a second comment. The cause is the token and its text, never
1106
+ // the comment, whose wording takes the Label map's strings and so moves with
1107
+ // the map between the failed edit and the retry.
1104
1108
  relabelled(token, text) {
1105
1109
  const { st } = this;
1106
- const { label, comment } = relabel(token, text);
1107
- if (st.commented !== comment) {
1110
+ const { label, comment } = relabel(token, text, this.p.labels);
1111
+ const cause = JSON.stringify([token, text]);
1112
+ if (st.commented !== cause) {
1108
1113
  const c = this.gh("relabel", ["issue", "comment", String(st.ticket), "--body", comment]);
1109
1114
  if (c.status !== 0) return this.stop(withText(`gh issue comment failed (${c.how})`, c));
1110
- st.commented = comment;
1115
+ st.commented = cause;
1111
1116
  this.save();
1112
1117
  }
1113
- const e = this.gh("relabel", ["issue", "edit", String(st.ticket), "--remove-label", READY, "--add-label", label]);
1118
+ const e = this.gh("relabel", ["issue", "edit", String(st.ticket), "--remove-label", this.p.labels["ready-for-agent"], "--add-label", label]);
1114
1119
  if (e.status !== 0) return this.stop(withText(`gh issue edit failed (${e.how}) — the comment is posted`, e));
1115
1120
  return this.leave(`relabelled ${label}: ${token}`);
1116
1121
  }
@@ -1257,11 +1262,21 @@ function setup() {
1257
1262
  }
1258
1263
  const root = spawn(process.execPath, [join(SCRIPTS, "scratch-root.mjs")], { cwd });
1259
1264
  if (root.status !== 0) throw new Refusal(withText(`scratch-root.mjs ${root.how}`, root));
1265
+ // The Label map, read once here: every label the Pull compares, writes or names in a comment is its string. No
1266
+ // valid map is exit 2, the reader's message naming `label-map.mjs ensure`; never the exit that reads as "left".
1267
+ let labels;
1268
+ try {
1269
+ labels = readLabelMap({ cwd });
1270
+ } catch (e) {
1271
+ if (!(e instanceof LabelMapUnreadable)) throw e;
1272
+ throw new Refusal(e.message);
1273
+ }
1260
1274
  const scratch = root.stdout;
1261
1275
  const dir = (n) => join(scratch, `impl-${n}`);
1262
1276
  return {
1263
1277
  cwd,
1264
1278
  scratch,
1279
+ labels,
1265
1280
  shortlist: join(fleetDir, "shortlist.json"),
1266
1281
  guard: join(fleetDir, "cost-guard.json"),
1267
1282
  statePath: (n) => join(dir(n), STATE),