@feigi/fleet-ctl 3.127.5 → 3.127.7

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.127.5",
3
+ "version": "3.127.7",
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": {
@@ -65,7 +65,10 @@
65
65
  // Ruling's note is not one `tier-outcomes.mjs append` derives (`isDerivedNote`);
66
66
  // `no_ruling`, the Pulls whose PR merged on GitHub with no Ruling, which stay
67
67
  // not merged; and `pending`, the Pulls whose PR is still open or not in the
68
- // list. Beside `min_n` it records `trip_points`, the floor's margin, and
68
+ // list. `no_ruling_prs` and `pending_prs` name the PRs behind the last two,
69
+ // ascending, as the report's top-level `pending` list does: a `no_ruling`
70
+ // Pull contributes the implementer PRs that make it one. Beside `min_n` it
71
+ // records `trip_points`, the floor's margin, and
69
72
  // `tsv_blobs`: the git blob id of each TSV it read, by the path it read it at.
70
73
 
71
74
  import { createHash } from "node:crypto";
@@ -117,27 +120,43 @@ export function computeReport({ members, tiers, features, prs, routerTable = nul
117
120
  const bootUnits = (g) => g.pulls.map((u) => bootUnit(u));
118
121
  const meanUsd = (t) => (t.merged ? t.spend / t.merged : null);
119
122
  const base = tallies.get(BASELINE_CELL) ?? null;
123
+ // The PRs behind each generation's `no_ruling` and `pending` counts, as the
124
+ // top-level `pending` list prints them: ascending, each once.
125
+ const behind = new Map();
126
+ for (const u of units) {
127
+ if (u.status === "excluded") continue;
128
+ const k = `${u.cell}\0${u.generation}`;
129
+ const held = behind.get(k) ?? behind.set(k, { no_ruling_prs: new Set(), pending_prs: new Set() }).get(k);
130
+ for (const pr of u.noRulingPrs) held.no_ruling_prs.add(pr);
131
+ if (u.status === "pending") held.pending_prs.add(u.pendingPr);
132
+ }
133
+ const prList = (set = []) => [...set].sort((x, y) => Number(x) - Number(y));
120
134
  // One generation's figures. The interval is the newest generation's against
121
135
  // the baseline's newest; an older generation is printed, never compared.
122
- const figuresOf = (cell, g, newest) => ({
123
- cell,
124
- generation: g.generation,
125
- n_pulls: g.n,
126
- n_merged: g.merged,
127
- n_claims: g.claims,
128
- n_failed: g.failed,
129
- fail_rate: g.claims ? round(g.failed / g.claims) : null,
130
- mean_usd: round(meanUsd(g), 2),
131
- median_usd: round(median(g.pulls.filter((u) => u.merged).map((u) => u.spend)), 2),
132
- by_hand: g.by_hand,
133
- no_ruling: g.no_ruling,
134
- pending: g.pending,
135
- router_usd: round(g.pulls.reduce((s, u) => s + routerUsd(u.pull), 0), 4),
136
- usd_diff_ci95: !newest || cell === BASELINE_CELL || !base ? null : bootstrapDiffCI(bootUnits(g), bootUnits(base)),
137
- left_out: g.left_out,
138
- unpriced: g.unpriced,
139
- untimed: g.untimed,
140
- });
136
+ const figuresOf = (cell, g, newest) => {
137
+ const held = behind.get(`${cell}\0${g.generation}`);
138
+ return {
139
+ cell,
140
+ generation: g.generation,
141
+ n_pulls: g.n,
142
+ n_merged: g.merged,
143
+ n_claims: g.claims,
144
+ n_failed: g.failed,
145
+ fail_rate: g.claims ? round(g.failed / g.claims) : null,
146
+ mean_usd: round(meanUsd(g), 2),
147
+ median_usd: round(median(g.pulls.filter((u) => u.merged).map((u) => u.spend)), 2),
148
+ by_hand: g.by_hand,
149
+ no_ruling: g.no_ruling,
150
+ no_ruling_prs: prList(held?.no_ruling_prs),
151
+ pending: g.pending,
152
+ pending_prs: prList(held?.pending_prs),
153
+ router_usd: round(g.pulls.reduce((s, u) => s + routerUsd(u.pull), 0), 4),
154
+ usd_diff_ci95: !newest || cell === BASELINE_CELL || !base ? null : bootstrapDiffCI(bootUnits(g), bootUnits(base)),
155
+ left_out: g.left_out,
156
+ unpriced: g.unpriced,
157
+ untimed: g.untimed,
158
+ };
159
+ };
141
160
  const figures = [...tallies.values()].map((t) => ({
142
161
  ...figuresOf(t.cell, t, true),
143
162
  excluded: t.excluded,
@@ -283,8 +283,11 @@ function numberOf(row, field, column = field) {
283
283
  /**
284
284
  * One unit per ticket-features row dated on or after `windowStart` (every dated
285
285
  * row when null), in file order: `{ pull, cell, stratum, generation, status,
286
- * merged, pr, ruling, pendingPr, noRuling, claims, falseClaims, rows, spend, workS }`,
287
- * `generation` null exactly when the Pull is excluded. `spend` is null when a
286
+ * merged, pr, ruling, pendingPr, noRuling, noRulingPrs, claims, falseClaims, rows, spend, workS }`,
287
+ * `generation` null exactly when the Pull is excluded. `noRulingPrs` are the
288
+ * Pull's own implementer PRs that are merged and that no Pull holds a Ruling
289
+ * for, which is what makes the Pull `noRuling`; [] when the Pull itself has a
290
+ * Ruling, or when PR state is unknown. `spend` is null when a
288
291
  * booked `cost` is blank, and `workS`, its work time in seconds, when a booked
289
292
  * `work_s` of a row naming no parent is. `prs` is `gh pr list`'s
290
293
  * `{ number, state }` rows, or null when PR state is unknown (the fit). `stratum`
@@ -358,7 +361,7 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
358
361
  const r = ruled.get(pull) ?? null;
359
362
  let merged = r !== null;
360
363
  let pendingPr = null;
361
- let noRuling = false;
364
+ let noRulingPrs = [];
362
365
  if (state) {
363
366
  if (r) {
364
367
  const s = state.get(r.pr);
@@ -366,7 +369,7 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
366
369
  merged = s === "MERGED";
367
370
  } else {
368
371
  pendingPr = own.find((m) => m.pr && state.get(m.pr) === "OPEN")?.pr ?? null;
369
- noRuling = own.some((m) => m.pr && state.get(m.pr) === "MERGED" && !held.has(m.pr));
372
+ noRulingPrs = own.filter((m) => m.pr && state.get(m.pr) === "MERGED" && !held.has(m.pr)).map((m) => m.pr);
370
373
  }
371
374
  }
372
375
  let claims = 0, falseClaims = 0;
@@ -396,8 +399,8 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
396
399
  else if (blank || (r && !r.carried)) status = "unpriced";
397
400
  else if (untimed) status = "untimed";
398
401
  return {
399
- pull, cell: pull.chosen_cell, stratum: stratum(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null, noRuling,
400
- pendingPr, claims, falseClaims, rows: booked, spend: blank ? null : spend, workS: untimed ? null : workS,
402
+ pull, cell: pull.chosen_cell, stratum: stratum(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null,
403
+ noRuling: noRulingPrs.length > 0, noRulingPrs, pendingPr, claims, falseClaims, rows: booked, spend: blank ? null : spend, workS: untimed ? null : workS,
401
404
  };
402
405
  });
403
406
  }
@@ -576,24 +576,29 @@ export function fitTable({ prior, features, members, verdicts, guard, commit = n
576
576
 
577
577
  let { stage, cells } = prior;
578
578
  cells = [...cells];
579
- const star = judgeRow(estimates["*"], pulls["*"], cells, tripped);
580
- const rows = { cost: { "*": star.cell ?? POLICY_CELL }, speed: {} };
581
- const reasons = { cost: { "*": { ...star, cell: rows.cost["*"] } }, speed: {} };
582
- for (const s of STRATA) {
583
- if (!estimates[s]) continue;
584
- reasons.cost[s] = judgeRow(estimates[s], pulls[s], cells, tripped);
585
- if (reasons.cost[s].cell !== null) rows.cost[s] = reasons.cost[s].cell;
586
- }
587
- for (const s of Object.keys(reasons.cost)) {
588
- const costCell = rows.cost[s];
589
- if (costCell === undefined) {
590
- reasons.speed[s] = unjudged();
591
- continue;
579
+ // The rows and their reasons over `cells`: a fitted table's `reasons` cover exactly its `cells`.
580
+ const judgeRows = () => {
581
+ const star = judgeRow(estimates["*"], pulls["*"], cells, tripped);
582
+ const rows = { cost: { "*": star.cell ?? POLICY_CELL }, speed: {} };
583
+ const reasons = { cost: { "*": { ...star, cell: rows.cost["*"] } }, speed: {} };
584
+ for (const s of STRATA) {
585
+ if (!estimates[s]) continue;
586
+ reasons.cost[s] = judgeRow(estimates[s], pulls[s], cells, tripped);
587
+ if (reasons.cost[s].cell !== null) rows.cost[s] = reasons.cost[s].cell;
592
588
  }
593
- const record = judgeSpeedRow(estimates[s], pulls[s], cells, tripped, costCell);
594
- rows.speed[s] = record.cell ?? costCell;
595
- reasons.speed[s] = { ...record, cell: rows.speed[s] };
596
- }
589
+ for (const s of Object.keys(reasons.cost)) {
590
+ const costCell = rows.cost[s];
591
+ if (costCell === undefined) {
592
+ reasons.speed[s] = unjudged();
593
+ continue;
594
+ }
595
+ const record = judgeSpeedRow(estimates[s], pulls[s], cells, tripped, costCell);
596
+ rows.speed[s] = record.cell ?? costCell;
597
+ reasons.speed[s] = { ...record, cell: rows.speed[s] };
598
+ }
599
+ return { rows, reasons };
600
+ };
601
+ let { rows, reasons } = judgeRows();
597
602
  const atN = (c) => (guard.n[c] ?? 0) >= MIN_N;
598
603
  const adopted = Object.values(rows).some((set) => set["*"] !== POLICY_CELL);
599
604
  if (stage === 1 && cells.every(atN) && (adopted || cells.some((c) => tripped.has(c)))) {
@@ -601,6 +606,8 @@ export function fitTable({ prior, features, members, verdicts, guard, commit = n
601
606
  for (const { cell, survives } of STAGE2) {
602
607
  if (!cells.includes(cell) && cells.includes(survives) && !tripped.has(survives)) cells.push(cell);
603
608
  }
609
+ // The stage-2 cells were added after the rows were judged: judge the rows again over the new `cells`.
610
+ ({ rows, reasons } = judgeRows());
604
611
  }
605
612
  return {
606
613
  window_start: window,
@@ -698,9 +698,9 @@ you cannot confirm was received, re-check the artifacts it governed. See referen
698
698
  lets a gate proceed. Exit 1 (the set changed) and exit 2 (the check could not
699
699
  answer) both refuse: report what it printed and do NOT re-read the
700
700
  instrument** — a guard that fails open on "could not look" protects nothing.
701
- - **Re-pin only after a change you made deliberately.** **A mid-run tooling fix**
702
- is the one legitimate writer. Re-pinning to clear a refusal you cannot
703
- explain discards the check.
701
+ - **Re-pin only on the maintainer's adopt.** Nothing you change yourself is a
702
+ reason: a tooling defect is reported, never fixed by you. Re-pinning to clear
703
+ a refusal you cannot explain discards the check.
704
704
  - **A pinned tree whose HEAD moved is the maintainer's to settle, whoever moved
705
705
  it — and so is an installed plugin that changed.** When a refusal — your check
706
706
  or a finisher's halt — reads HEAD advanced, rewound or diverged from the pin
@@ -887,18 +887,15 @@ failures arrive as *wrong findings*, not errors:
887
887
  - **Never relay a diagnostic without reproducing it in that member's specific worktree**
888
888
  (re-run the check that raised it from there). See references/isolation.md.
889
889
 
890
- ### A mid-run tooling fix
890
+ ### A tooling defect found mid-run
891
891
 
892
- **When to fix, its scope, triggers and shape.** See references/instruments.md.
892
+ **When to report one, its scope, triggers and shape.** See references/instruments.md.
893
893
 
894
894
  Why the agent body carries what it does — read this before editing any `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. See references/pull.md.
895
895
 
896
896
  Read why that body carries the claim discipline, and its literal-path and `grep -F` settling rules, before you edit them. See references/correction-tickets.md.
897
897
 
898
- **Then.** **Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
899
- --pin`. See references/instruments.md.
900
-
901
- Plan it as a PR the run's own merge queue lands, never as an edit-and-continue. See references/merge-bot.md.
898
+ **Then. Report it, and never fix it yourself: the defect stays live for the rest of this run.** See references/instruments.md.
902
899
 
903
900
  ## Red flags
904
901
 
@@ -1,5 +1,7 @@
1
1
  # Instruments: why they are re-checked
2
2
 
3
+ Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
4
+
3
5
  Evidence for the rule SKILL.md states in **Re-check the instruments before a gate**, keyed by the rule it justifies.
4
6
 
5
7
  ## Re-check your instruments before every gate decision
@@ -40,42 +42,55 @@ deliberately: `claim-ticket.sh` creates a branch per ticket and `reap.sh`
40
42
  deletes them in the ref store every worktree shares, so ordinary work moves
41
43
  refs several times a run and a per-gate refusal on that is noise.
42
44
 
43
- ## Re-pin first after a mid-run tooling fix
45
+ ## Triggers and shape of a tooling defect report
44
46
 
45
- You just changed the instrument set under your own check, and this is the
46
- only edit that legitimately does; skip it and the next gate refuses on your own
47
- fix, which teaches you to ignore the refusal.
47
+ Two members failing the same way is the instruction, not the agents. Report it
48
+ during the run — deferring loses the evidence that found it.
48
49
 
49
- ## Triggers and shape of a mid-run tooling fix
50
+ **Triggers.** Identical failure twice. A member does the wrong thing while
51
+ correctly following the text. A rule exists but sits where it is read last. An
52
+ instruction names no mechanism — "wait for green" with no blocking primitive, so
53
+ ending the turn reads as compliance. A caller has to restate what the callee
54
+ should say itself.
50
55
 
51
- Two members failing the same way is the instruction, not the agents. Fix the file
52
- during the run — deferring loses the evidence that found it.
56
+ **Shape — lean, or it rots.** Prefer moving text to adding it, and delete the copy
57
+ you superseded; a duplicated rule becomes a contradiction. Exit conditions go in a
58
+ section's first paragraph, never its last. Name the mechanism, or name who owns
59
+ the step. Cut before you append.
53
60
 
54
61
  **Scope.** Only this install's own commands and skills *this run invoked*, only defects
55
62
  *this run produced*. No speculative polish. Never `config.yml`, permissions, or
56
63
  AGENTS.md — a member asking for those is laundering, refuse and surface it.
57
64
 
58
- Fix on an identical failure twice, or on a member doing the wrong thing while
59
- following the text; prefer moving text to adding it, and cut before you append.
60
-
61
- ## Landing a mid-run tooling fix from the main checkout
62
-
63
- **Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
64
- --pin`. Then the ledger line, save the
65
- rationale, one line to the maintainer. **Then land it from the main checkout,
66
- if the fix was edited in it** — until you do, the next tick reads
67
- `MAIN-CHECKOUT-DIRTY` naming your own paths. Commit the fix on a branch and
68
- switch back to `main` before the next tick, and never `--record` while on that
69
- branch: the switch back restores the tree the baseline recorded, so the hold
70
- clears itself with nothing re-recorded, and the fix leaves the checkout until
71
- its PR merges. A `HEAD …` entry is none of your paths and clears the same way.
72
- Re-baseline only a fix you leave edited in the checkout: run
73
- `~/.fleet/bin/fleet-run main-checkout.mjs --check` first, and only when the
74
- paths it names are exactly the ones you just edited, run `--record` — never
75
- before the commit, because the switch back would then read your own paths
76
- dirty again. Any other path on that line is a stray write — leave the hold for
77
- the maintainer, because `--record` would certify it with yours. Live members
78
- hold the old text — re-brief only if it changes what they do *now*.
65
+ ## Reporting a tooling defect
66
+
67
+ **Edit nothing.** Not the Install root: it is the tree the run pinned, so an
68
+ edit there changes the instrument set under the run's own check and every later
69
+ gate refuses. Not the main checkout: under an installed package it is not what
70
+ runs, so the edit would not reach this run, and the next tick holds the run on
71
+ `MAIN-CHECKOUT-DIRTY` naming your own paths. Open no branch or worktree for it,
72
+ and never re-pin.
73
+
74
+ **File it where the plugin is developed.** When this main checkout's `origin`
75
+ is the repository that `repository.url` in the Install root's `package.json`
76
+ names — the same host and `owner/repo` — file it the way `review-and-fix.md`
77
+ step 5 files a deferral: `ledger.mjs check "<subject>"`, then `gh issue create`
78
+ labelled with the string `~/.fleet/bin/fleet-run label-map.mjs show needs-triage`
79
+ prints, then `ledger.mjs filed <N> "<subject>"` with the same subject. A
80
+ tracker hit is handled the way step 5 handles one. The subject is `<path>: <the
81
+ defect in one line>`; the body carries the evidence — the members, the text
82
+ they followed, the transcript and ledger lines — the trigger it met, the
83
+ proposed change, and the run it came from. Then one line to the maintainer
84
+ naming the issue. In any other workspace file nothing, because `check` and
85
+ `filed` answer for this checkout's own tracker only: give the maintainer the
86
+ same report instead.
87
+
88
+ **The defect stays live for the rest of this run.** A fix reaches a run once
89
+ that run's Install root holds it: for an installed package, once the maintainer
90
+ installs a release that carries it. Send the correction to every member the
91
+ defect reaches whenever it changes what that member does — live members now,
92
+ later ones right after their dispatch — and count a repeat of the same failure
93
+ as this defect, not a new trigger.
79
94
 
80
95
  ## A pinned tree whose HEAD moved is the maintainer's to settle
81
96
 
@@ -2,31 +2,7 @@
2
2
 
3
3
  Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
4
4
 
5
- Evidence for the rules SKILL.md states in **A mid-run tooling fix** and in the `ready-to-merge` wake, keyed by the rule each justifies.
6
-
7
- ## When to fix the tooling mid-run, and its shape
8
-
9
- **Triggers.** Identical failure twice. A member does the wrong thing while
10
- correctly following the text. A rule exists but sits where it is read last. An
11
- instruction names no mechanism — "wait for green" with no blocking primitive, so
12
- ending the turn reads as compliance. A caller has to restate what the callee
13
- should say itself.
14
-
15
- **Shape — lean, or it rots.** Prefer moving text to adding it, and delete the copy
16
- you superseded; a duplicated rule becomes a contradiction. Exit conditions go in a
17
- section's first paragraph, never its last. Name the mechanism, or name who owns
18
- the step. Cut before you append.
19
-
20
- ## A mid-run tooling fix lands through a PR
21
-
22
- **Landing it.** The file being right is not the end of it. `main` carries a
23
- ruleset with no bypass actors, so a direct `git push origin main` is **refused** —
24
- `! [remote rejected] main -> main (push declined due to repository rule
25
- violations)`, measured 2026-08-10 by a controller that tried exactly that at the
26
- end of a 7-PR run. A mid-run tooling fix goes through a PR like every other
27
- change, and that PR faces every required check any other PR faces — the set
28
- `.github/rulesets/main.json` declares — so it carries a release label too.
29
- Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
5
+ Evidence for the rules SKILL.md states in the `ready-to-merge` wake, keyed by the rule each justifies.
30
6
 
31
7
  ## You own the merge watcher, not the bot
32
8
 
@@ -147,11 +147,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
147
147
  A path entry holds until that re-baseline, tick after tick; a `HEAD …` entry
148
148
  clears itself once HEAD reads clean again, and is never re-baselined while
149
149
  HEAD is off the run's branch. Never revert the
150
- paths yourself, and never re-baseline over paths nobody has resolved. The
151
- changes of yours that trip it are a mid-run tooling fix edited in this
152
- checkout and the close-out commit's round trip through a branch; SKILL.md's
153
- **A mid-run tooling fix** and the commit section of references/close-out.md say how
154
- each is cleared.
150
+ paths yourself, and never re-baseline over paths nobody has resolved. The change of yours that trips it is the close-out commit's round trip through a branch; the commit section of references/close-out.md says how it is cleared.
155
151
  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-baseline. 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; 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 member write that matches it is never seen.
156
152
  - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
157
153
  could not look: a git or hash read failed (`could not look:`), or the