@feigi/fleet-ctl 3.114.3 → 3.115.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.114.3",
3
+ "version": "3.115.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": {
@@ -19,7 +19,7 @@ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x)
19
19
  // a step not yet run being `pending`. A receipt missing one was not written
20
20
  // by a finished phase 0.
21
21
  export const STEP_NAMES = Object.freeze([
22
- "alarm", "branch", "fast-forward", "pin", "baseline", "preflight", "ruleset", "tier-roles", "metrics",
22
+ "alarm", "branch", "fast-forward", "pin", "baseline", "labels", "preflight", "ruleset", "tier-roles", "metrics",
23
23
  "cockpit", "rotate", "reclaim", "recipe", "fold-in", "stranded", "shortlist",
24
24
  ]);
25
25
 
@@ -36,6 +36,16 @@
36
36
  // pin `instruments.sh --pin`, which certifies the Install root; the
37
37
  // ok line names its kind, root, and version or commit.
38
38
  // baseline `main-checkout.mjs --record`; its refusals fail the step.
39
+ // labels `label-map.mjs ensure`, the Label map derivation step. Exit 0
40
+ // is ok, its output the map ensure printed. Exit 3 is pending,
41
+ // the question payload as one JSON line and then
42
+ // `NEED answer-label-map`; nothing after it runs, the
43
+ // pre-flight included, until the map is written. Exit 1 (the
44
+ // triage-label table breaks the string rules), exit 2 (no
45
+ // repository, or `gh` could not answer), any other exit, and
46
+ // an exit 3 that printed no question payload — a `certain`
47
+ // record and at least one `uncertain` entry, each a record
48
+ // naming its `role` — fail the step with ensure's own words.
39
49
  // preflight `preflight.mjs`. A non-zero exit fails the step; the FAIL, WARN
40
50
  // and PREFLIGHT lines of an exit 1 are printed.
41
51
  // ruleset `.github/scripts/apply-ruleset.sh --check`, when the workspace
@@ -126,8 +136,9 @@
126
136
  // session alone.
127
137
  //
128
138
  // A step that fails stops the script; so does a pending one — nothing after
129
- // the recipe may run before it is proven, and the shortlist waits for the
130
- // stranded claims. The steps after it stay `pending` in the receipt.
139
+ // the Label map may run before it is written, nothing after the recipe before
140
+ // it is proven, and the shortlist waits for the stranded claims. The steps
141
+ // after it stay `pending` in the receipt.
131
142
  //
132
143
  // `--workflow` and `--declare-no-ci` name how a repository without a workflow
133
144
  // called CI runs. `preflight.mjs` takes no arguments, so they are not passed
@@ -239,6 +250,24 @@ function baseline({ cwd }) {
239
250
  return ok("main-checkout baseline recorded");
240
251
  }
241
252
 
253
+ function labels({ cwd }) {
254
+ const r = node("label-map.mjs", ["ensure"], { cwd });
255
+ if (r.status === 0) return ok(`label-map.mjs ensure: ${lines(r.stdout).at(-1) ?? "no output"}`);
256
+ if (r.status !== 3) return failed(withText(`label-map.mjs ensure ${r.how}`, r));
257
+ // The payload is the controller's question, read off the step's output, so
258
+ // it travels as one line: a pretty-printed one would split across lines.
259
+ let payload;
260
+ try {
261
+ payload = JSON.parse(r.stdout);
262
+ } catch {
263
+ payload = null;
264
+ }
265
+ const question = isRecord(payload) && isRecord(payload.certain) && Array.isArray(payload.uncertain) &&
266
+ payload.uncertain.length > 0 && payload.uncertain.every((entry) => isRecord(entry) && typeof entry.role === "string");
267
+ if (!question) return failed(withText(`label-map.mjs ensure ${r.how} printed no question payload`, r));
268
+ return { status: "pending", output: [JSON.stringify(payload), "NEED answer-label-map"].join("\n") };
269
+ }
270
+
242
271
  function preflight({ cwd, ci }) {
243
272
  const r = node("preflight.mjs", [], { cwd });
244
273
  if (r.status !== 0) {
@@ -503,8 +532,8 @@ function alarm({ fleetDir }) {
503
532
  }
504
533
 
505
534
  const STEPS = {
506
- "alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "preflight": preflight,
507
- "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
535
+ "alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "labels": labels,
536
+ "preflight": preflight, "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
508
537
  "reclaim": reclaim, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
509
538
  };
510
539
 
@@ -52,8 +52,6 @@ const PROBE_TIMEOUT_MS = 60_000;
52
52
  const NAME = "preflight";
53
53
  const die = makeDie(NAME);
54
54
 
55
- const label = (l) => ({ name: `label:${l}`, argv: ["gh", "label", "list", "--search", l, "--json", "name", "--jq", ".[].name"], want: l });
56
-
57
55
  // A workflow file whose top-level `name:` is CI, matched the way ci-state.mjs
58
56
  // reads a workflow's name: either quote style, and a trailing ` # comment` is
59
57
  // not part of the name. A plain `^name: *CI *$` would WARN for a repo
@@ -74,9 +72,6 @@ export const CHECKS = [
74
72
  { name: "origin-main", argv: ["git", "rev-parse", "--verify", "-q", "origin/main"] },
75
73
  { name: "worktrees-ignored", argv: ["git", "check-ignore", "-q", ".worktrees/probe"] },
76
74
  { name: "fleet-ignored", argv: ["git", "check-ignore", "-q", ".fleet/probe"] },
77
- label("ready-for-agent"),
78
- label("in-progress"),
79
- label("ready-to-merge"),
80
75
  { name: "allow-merge-commit", argv: ["gh", "api", "repos/{owner}/{repo}", "--jq", ".allow_merge_commit"], want: "true" },
81
76
  { name: "ruleset", argv: ["gh", "api", "repos/{owner}/{repo}/rulesets", "--jq", ".[].name"], want: NONEMPTY },
82
77
  { name: "ci-workflow", argv: ["sh", "-c", CI_NAMED], warn: true },
@@ -51,8 +51,8 @@ Nothing in this phase, or in any later one, asks the maintainer which tickets to
51
51
 
52
52
  The `tier-roles` step runs `~/.fleet/bin/fleet-run tier-roles.mjs --check
53
53
  --in-flight <B>`, `<B>` being the `--in-flight` given, else the default.
54
- **Default: In-flight bound 5, fixed for the run.** See references/pull.md. What it checks is in the header of `scripts/tier-roles.mjs`, under
55
- the tier routes. A line it prints on a pass about omp's `task.maxConcurrency`
54
+ **Default: In-flight bound 5, fixed for the run.** See references/pull.md.
55
+ A line it prints on a pass about omp's `task.maxConcurrency`
56
56
  is a notice in the step's output and never holds: read it, report it, and
57
57
  go on — the fleet never writes that setting.
58
58
 
@@ -65,17 +65,20 @@ Nothing in this phase, or in any later one, asks the maintainer which tickets to
65
65
  run `phase0.mjs` again. `RECIPE NOT PROVEN` → stall: report `STALL —
66
66
  Recipe not proven: <cause>` to the maintainer with the deriver's reason
67
67
  verbatim, and claim, Pull and review nothing.
68
+ - `NEED answer-label-map` — the `labels` line is the Label map question:
69
+ ask it as references/phase-0.md words it, and wait; run
70
+ `label-map.mjs set --create` with the answer (`--accept-suggestions`
71
+ for `defaults`), say how to make it permanent, and run phase 0 again.
72
+ A `failed` `labels` step is no question: show it, stop.
68
73
  - `NEED resume #<n> <worktree> <branch>` — a dead run's claim: no PR, or not only `CLOSED` ones.
69
74
  Dispatch a stranded `impl-<n>-b` the ordinary way (record it with
70
75
  `ledger.mjs row`, render its brief, `ledger.mjs dispatch`, the `task`
71
76
  call, the tier check), in that worktree and branch, and never with
72
- `claim-ticket.sh`: the claim stands. A re-run finds the need met once its
73
- row is written. A `report #<n> — <why>` line is the maintainer's and
74
- nothing else, and a `carried` line is a live token to reconcile first.
75
- A closed-PR `report` takes `replace`/`release #<n>`.
77
+ `claim-ticket.sh`: the claim stands. A `report #<n> — <why>` line is the
78
+ maintainer's and nothing else, and a `carried` line is a live token to
79
+ reconcile first.
76
80
 
77
- A `drift` or `unanswered` ruleset step is advice too: surface the diff and
78
- go on. See references/phase-0.md.
81
+ See references/phase-0.md.
79
82
 
80
83
  1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
81
84
  `.fleet/shortlist.json` — `{scanned, shortlist: [{n, t}], dropped: [{n, reason}]}`:
@@ -29,7 +29,7 @@ refreshes the Shortlist itself, and every admission is a **Pull** — one ticket
29
29
  into one free implementer slot, the moment it frees (phase 1).
30
30
 
31
31
  `phase0.mjs` runs the start sequence in
32
- its fixed order — alarm, branch, fast-forward, pin, baseline, preflight, ruleset,
32
+ its fixed order — alarm, branch, fast-forward, pin, baseline, labels, preflight, ruleset,
33
33
  tier-roles, metrics, cockpit, rotate, reclaim, recipe, fold-in, stranded,
34
34
  shortlist — prints one `phase0: <step>: <status>` line per step with the
35
35
  `NEED` lines last, and records each step in `.fleet/phase0.json`, which the
@@ -102,12 +102,76 @@ repository; the tick's rows say how each is cleared.
102
102
  without a tick.
103
103
  On `MAIN-CHECKOUT-DIRTY` the maintainer may instead ignore a stray path that is untracked and new since the baseline: an entry in `.git/info/exclude` or in the global excludes file hides it from the check, and the hold clears on the next tick with no re-record. Ignoring never clears a tracked or staged file's change, which `git status` reports whatever the excludes say, nor a pattern that also matches a path the baseline holds, which then reads as changed. Ignoring is the maintainer's decision, never the controller's: the controller never writes an exclude or a `.gitignore` entry. Keep the pattern narrow, because an ignored path is invisible to this check, so a later member write that matches it is never seen.
104
104
 
105
+ ## Derive the Label map
106
+
107
+ **Derive the Label map — the Label map derivation step — after the baseline
108
+ and before the pre-flight.** The **Label map** (`.fleet/labels.json`) gives
109
+ the string this repository's tracker uses for each Label role:
110
+ `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`,
111
+ `wontfix`, `in-progress`, `onhold`, `ready-to-merge`. The `labels` step runs
112
+ `~/.fleet/bin/fleet-run label-map.mjs ensure` in this main checkout, which
113
+ reads the cached map, the repository's triage-label table and the tracker's
114
+ live label list, on every call, and never creates a label.
115
+ This step is yours, once per run start: a member never derives the map and
116
+ never asks.
117
+
118
+ - **Exit 0** — the map is in place: the cached one still matches the tracker,
119
+ or one was derived and written. The step is `ok`, its line the map.
120
+ - **Exit 3** — a role is uncertain, and nothing was written. The step is
121
+ `pending`, its line the question payload, one JSON object, and phase 0
122
+ prints `NEED answer-label-map`. Nothing after it runs — no pre-flight, no
123
+ Shortlist, no claim — until the map is written.
124
+ - **Exit 1** — the table breaks the string rules; what it printed names each
125
+ role, the rule and the fix. **Exit 2** — it could not derive at all: no
126
+ repository, or `gh` could not answer, among the causes its message names.
127
+ Either fails the step, as does any other exit and an exit 3 that printed no
128
+ question to ask (no `certain` record, an empty `uncertain` list, or an
129
+ entry naming no `role`): show the maintainer what the step printed and
130
+ stop. Neither is a question. Once the cause is fixed, run phase 0 again.
131
+
132
+ **Ask once, as one question, and wait.** The payload holds `certain`, the
133
+ roles already settled (role → string), and `uncertain`, one entry per role to
134
+ ask about: `{role, suggestion, origin, candidates, exists, was, claimedBy}`.
135
+ Put it to the maintainer as one question listing each uncertain role, its
136
+ suggestion, why, and the alternatives (`candidates`, the near matches the
137
+ tracker has). The why, by the entry:
138
+
139
+ - `origin` `table` — `declared in the triage-label table but not in the tracker`
140
+ - `origin` `near-match` — `near match in the tracker`
141
+ - `origin` `default`, `exists` true — `the default and a near match are both in the tracker`
142
+ - `origin` `default`, `exists` false — `nothing found — the default, to be created`
143
+ - `origin` `gone` — `was <was> when cached; gone from the tracker (renamed or deleted?) — name the label to use`; its `suggestion` is null, never the vanished string
144
+
145
+ Any other entry carrying `was` takes the prefix `was <was> when cached, now
146
+ gone from the tracker; `, and one carrying `claimedBy` the prefix `your
147
+ earlier answer <string> is now <role>'s in the triage-label table; `
148
+ when its `by` is `table`, `your earlier answer <string> is now <role>'s label
149
+ (its default); ` when it is `default`. End the question with: reply
150
+ `defaults` to accept every suggestion, or name `<role>=<label>` for any you
151
+ want otherwise — a role with no suggestion must be named; labels that do not
152
+ exist are created on your confirmation.
153
+
154
+ **Write the answer, say how to keep it, run phase 0 again.** Run
155
+ `~/.fleet/bin/fleet-run label-map.mjs set --create` with the reply:
156
+ `--accept-suggestions` for `defaults`, and each `<role>=<label>` the
157
+ maintainer named. Exit 0 prints the map it wrote; exit 1 is a refusal naming
158
+ the role and the rule, nothing written and nothing created — put it to the
159
+ maintainer and ask again. In the same reply, tell the maintainer how to make
160
+ the answer permanent: add or edit the role's row in the repository's
161
+ triage-label table, the role in the first cell and the string in the
162
+ second. The plugin never writes that table, so neither do you. Then run
163
+ phase 0 again; `ensure` now exits 0. Exit 2 of `set` is no question: a pair
164
+ it could not read (an unknown role, a malformed pair, a role answered twice),
165
+ no repository, `gh` could not create or list a label — what it printed names
166
+ any label it created before it — or the cache not readable or writable. Show
167
+ the maintainer what it printed and stop, as for a failed `labels` step.
168
+
105
169
  ## Run the pre-flight
106
170
 
107
171
  **Run the pre-flight, once the pin and the baseline are recorded.**
108
172
  `~/.fleet/bin/fleet-run preflight.mjs` checks what this machine and this
109
173
  repository must give the fleet — the binaries, `gh` auth, `origin/main`,
110
- `.worktrees/` and `.fleet/` ignored, the three labels, merge commits on, a
174
+ `.worktrees/` and `.fleet/` ignored, merge commits on, a
111
175
  ruleset, the Resolver — and prints one `ok`, `WARN` or `FAIL` line per
112
176
  check, each naming its check. **Exit 1 stops the run:** no shortlist, no
113
177
  dispatch. Report every `FAIL` line to the maintainer by its check's name;
@@ -133,6 +197,8 @@ be answered at all: no spec, no `gh`, a listing or read that failed
133
197
  outright, or a read that succeeded but withheld `bypass_actors` because
134
198
  the session lacks repository admin.
135
199
 
200
+ A `drift` or `unanswered` ruleset step is advice too: surface the diff and go on.
201
+
136
202
  **3 does not stop the run and is not yours to fix** — reconciling is a
137
203
  write to the gate protecting this repo, so it needs the maintainer.
138
204
  Surface the diff and carry on. What it changes is what you may then claim:
@@ -493,7 +559,8 @@ files under `<scratch>/impl-<N>/`). Record it the ordinary way —
493
559
  "impl-<N>-b"`, then `dispatch-prompt.mjs render implementer --member
494
560
  impl-<N>-b …`, then `ledger.mjs dispatch <N> impl-<N>-b`, then the `task`
495
561
  call naming the `agent` it printed, then the tier check — and never
496
- `claim-ticket.sh`: the claim already stands. A `report` goes to the
562
+ `claim-ticket.sh`: the claim already stands. A re-run finds the need met
563
+ once its row is written. A `report` goes to the
497
564
  maintainer as `#<N> — <why>` and nothing else: no dispatch, no label change,
498
565
  no release. One whose `why` reads `PR #<M> closed unmerged` waits on the
499
566
  maintainer's `replace #<N>` or `release #<N>`, the two words the tick's
@@ -599,6 +599,7 @@ one run.
599
599
 
600
600
  `$ARGUMENTS` sets B. It becomes
601
601
  the tick's `--in-flight` and `tier-roles.mjs --check --in-flight`.
602
+ What it checks is in the header of `scripts/tier-roles.mjs`, under the tier routes.
602
603
 
603
604
  **Default: In-flight bound 5, fixed for the run.** The level is set by load, not
604
605
  throughput: B caps live review units (≤ open PRs ≤ B), and the review side is