@feigi/fleet-ctl 3.35.4 → 3.35.5

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.35.4",
3
+ "version": "3.35.5",
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": {
@@ -813,7 +813,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
813
813
  && !fixRunning(st) && !st.inFlight)
814
814
  .map(([n]) => n).sort(asc),
815
815
  // Open, not signed off, closing an issue (GitHub's own linked set — a
816
- // chore PR closing nothing is review work nobody in the run will ever be
816
+ // PR closing nothing is review work nobody in the run will ever be
817
817
  // dispatched against), with no live or returned review on record —
818
818
  // or a returned review its finisher halted `past-pin` against: the
819
819
  // head carries commits no reviewer read, so it is owed a review again
@@ -26,18 +26,20 @@
26
26
  // Explicit `-uall`, never bare `--porcelain`: `status.showUntrackedFiles=no`
27
27
  // silences untracked files otherwise.
28
28
  //
29
- // THE RUN'S OWN BOOKKEEPING IS NOT A STRAY WRITE. Two tracked files in the
29
+ // THE RUN'S OWN BOOKKEEPING IS NOT A STRAY WRITE. Three tracked files in the
30
30
  // main checkout are written by the controller itself mid-run:
31
31
  // `docs/metrics/tier-outcomes.tsv`, appended each time it rules a PR's review
32
- // (run-team/SKILL.md, `tier-outcomes.mjs append`), and
33
- // `docs/metrics/member-outcomes.tsv`, rewritten by the member-facts scrape.
32
+ // (run-team/SKILL.md, `tier-outcomes.mjs append`),
33
+ // `docs/metrics/member-outcomes.tsv`, rewritten by the member-facts scrape, and
34
+ // `docs/metrics/ticket-features.tsv`, which `metrics-refresh.mjs` drains the
35
+ // pending Pull rows into at phase 0 and again at close-out.
34
36
  // Compared like any other path, the first append would hold every
35
37
  // dispatching row for the rest of the run, and clearing it with `--record`
36
38
  // after every ruling would certify whatever stray write landed beside it.
37
- // So `snapshot()` leaves exactly those two paths out, for the reason
38
- // instruments.sh leaves `docs/metrics/` out of its pin. Two named files, not
39
+ // So `snapshot()` leaves exactly those three paths out, for the reason
40
+ // instruments.sh leaves `docs/metrics/` out of its pin. Three named files, not
39
41
  // the directory: anything else under `docs/metrics/` is still a stray write.
40
- // The price: a member's leaked write to one of those two files goes unseen.
42
+ // The price: a member's leaked write to one of those three files goes unseen.
41
43
  //
42
44
  // FOUR ANSWERS, worktree-audit.sh's three plus the baseline's own refusal:
43
45
  // clean — the porcelain entries and hashes equal the baseline's.
@@ -81,7 +83,7 @@ import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
81
83
 
82
84
  export const BASELINE_FILE = "main-checkout.sha";
83
85
  export const RECORD_COMMAND = "~/.fleet/bin/fleet-run main-checkout.mjs --record";
84
- const RUN_BOOKKEEPING = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv"]);
86
+ const RUN_BOOKKEEPING = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
85
87
  const HEADER = "fleet main-checkout baseline v1";
86
88
  const GIT_TIMEOUT_MS = 30_000;
87
89
  const MAX_BUFFER = 64 * 1024 * 1024;
@@ -0,0 +1,122 @@
1
+ #!/usr/bin/env node
2
+ // The run's two metrics duties that keep the router's inputs current: move the
3
+ // pending ticket-features rows into the tracked corpus, then refresh the cost
4
+ // guard over it.
5
+ //
6
+ // metrics-refresh.mjs [--repo <dir>]
7
+ //
8
+ // --repo the workspace whose `.fleet/` and `docs/metrics/` the duties read
9
+ // and write; default the main checkout of the repository the cwd is
10
+ // in, where the router script appends its pending rows
11
+ //
12
+ // DRAIN. `ticket-router.mjs route` appends one row per Pull to
13
+ // `.fleet/ticket-features.pending.tsv`; this moves them into
14
+ // `docs/metrics/ticket-features.tsv`, deduped on `session` + `agent`, and
15
+ // deletes the pending file. A crash between the write and the delete leaves
16
+ // rows the next drain finds already there, so a second run changes nothing.
17
+ //
18
+ // COST GUARD. `pr-cost.mjs --guard` rewrites `.fleet/cost-guard.json`, which
19
+ // the router reads and fails closed without. It needs all three metrics TSVs;
20
+ // a workspace that lacks one has no corpus to guard yet (its first run), so the
21
+ // guard is skipped with a line naming the missing file and
22
+ // `.fleet/cost-guard.json` is left as it is. Its exit 3 (a cell tripped) and 4
23
+ // (no verdict yet — the baseline cell has too few merged PRs) are verdicts the
24
+ // router and `fleet-tick.mjs` consume, not failures; any other non-zero exit is.
25
+ //
26
+ // One `metrics-refresh: <duty>: …` line per duty on stdout. Exit 0 when
27
+ // neither duty failed; 1 when one failed — named on stderr, and the duty after
28
+ // it did not run (each is safe to run again); 2 on a usage error.
29
+
30
+ import { spawnSync } from "node:child_process";
31
+ import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
32
+ import { dirname, join, resolve } from "node:path";
33
+ import { fileURLToPath } from "node:url";
34
+ import { makeDie, defineFlags } from "./arg.mjs";
35
+ import { gitEnv } from "./git-env.mjs";
36
+ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
37
+ import { isCLI } from "./is-cli.mjs";
38
+ import { FEATURE_COLUMNS, parseFeatures } from "./pr-cost.mjs";
39
+
40
+ const NAME = "metrics-refresh";
41
+ const PR_COST = fileURLToPath(new URL("./pr-cost.mjs", import.meta.url));
42
+ const PENDING = join(".fleet", "ticket-features.pending.tsv");
43
+ const FEATURES = join("docs", "metrics", "ticket-features.tsv");
44
+ const CORPUS = [join("docs", "metrics", "member-outcomes.tsv"), join("docs", "metrics", "tier-outcomes.tsv"), FEATURES];
45
+ const GUARD = join(".fleet", "cost-guard.json");
46
+ // pr-cost.mjs --guard: 0 no cell tripped, 3 a cell tripped, 4 no verdict yet —
47
+ // all three are verdicts its readers consume; anything else is a failure.
48
+ const GUARD_VERDICT_EXITS = new Set([0, 3, 4]);
49
+ const MAX_BUFFER = 64 * 1024 * 1024;
50
+
51
+ const say = (line) => process.stdout.write(`${NAME}: ${line}\n`);
52
+ const headerOf = (text) => String(text).split("\n").find((l) => l.trim() && !l.startsWith("#")).split("\t");
53
+ const pullKey = (r) => `${r.session}\0${r.agent}`;
54
+
55
+ function drain(repo) {
56
+ const pending = join(repo, PENDING);
57
+ if (!existsSync(pending)) return say(`drain: nothing pending in ${PENDING}`);
58
+ const pendingText = readFileSync(pending, "utf8");
59
+ const incoming = parseFeatures(pendingText);
60
+ const target = join(repo, FEATURES);
61
+ let text = existsSync(target) ? readFileSync(target, "utf8") : `${FEATURE_COLUMNS.join("\t")}\n`;
62
+ const seen = new Set(parseFeatures(text).map(pullKey));
63
+ const header = headerOf(text);
64
+ const unknown = headerOf(pendingText).filter((c) => !header.includes(c));
65
+ if (unknown.length) throw new Error(`${PENDING} carries ${unknown.join(", ")}, which ${FEATURES} has no column for`);
66
+ const added = [];
67
+ for (const r of incoming) {
68
+ if (seen.has(pullKey(r))) continue;
69
+ seen.add(pullKey(r));
70
+ added.push(header.map((c) => r[c] ?? "").join("\t"));
71
+ }
72
+ if (added.length) {
73
+ if (!text.endsWith("\n")) text += "\n";
74
+ mkdirSync(dirname(target), { recursive: true });
75
+ writeFileSync(`${target}.tmp`, `${text}${added.join("\n")}\n`);
76
+ renameSync(`${target}.tmp`, target);
77
+ }
78
+ unlinkSync(pending);
79
+ say(`drain: ${added.length} row${added.length === 1 ? "" : "s"} from ${PENDING} into ${FEATURES} (${incoming.length - added.length} already there)`);
80
+ }
81
+
82
+ function costGuard(repo) {
83
+ const missing = CORPUS.filter((f) => !existsSync(join(repo, f)));
84
+ if (missing.length) return say(`cost guard: skipped, ${missing.join(", ")} not found — no corpus to guard yet; ${GUARD} left as it is`);
85
+ const out = join(repo, GUARD);
86
+ const r = spawnSync(process.execPath, [PR_COST, "--guard", "--out", out], {
87
+ cwd: repo, encoding: "utf8", env: gitEnv(), maxBuffer: MAX_BUFFER,
88
+ });
89
+ if (!GUARD_VERDICT_EXITS.has(r.status)) {
90
+ throw new Error(`pr-cost.mjs --guard exited ${r.error?.code ?? r.status ?? r.signal}: ${String(r.stderr ?? "").trim()}`);
91
+ }
92
+ const g = JSON.parse(readFileSync(out, "utf8"));
93
+ const tripped = g.tripped.map((t) => (typeof t === "string" ? t : t?.cell));
94
+ say(`cost guard: verdict ${g.verdict}${tripped.length ? ` (tripped: ${tripped.join(", ")})` : ""}, pr-cost.mjs exit ${r.status}; ${GUARD} computed ${g.computed_at}`);
95
+ }
96
+
97
+ function main() {
98
+ const die = makeDie(NAME);
99
+ const F = defineFlags(die, { flags: { repo: "value" } });
100
+ F.sweep();
101
+ F.stray();
102
+ let repo = F.arg("repo") === null ? null : resolve(F.arg("repo"));
103
+ if (repo === null) {
104
+ try {
105
+ repo = dirname(fleetFile(null));
106
+ } catch (e) {
107
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
108
+ die(`${e.message} — pass --repo <dir>`);
109
+ }
110
+ }
111
+ for (const [name, duty] of [["drain", drain], ["cost guard", costGuard]]) {
112
+ try {
113
+ duty(repo);
114
+ } catch (e) {
115
+ process.stderr.write(`${NAME}: ${name} failed: ${e.message}\n`);
116
+ process.exitCode = 1;
117
+ return;
118
+ }
119
+ }
120
+ }
121
+
122
+ if (isCLI(import.meta.url)) main();
@@ -276,9 +276,10 @@ phase, or in any later one, asks the maintainer which tickets to take.
276
276
  writes `member-write-guard` cannot see — an `eval` cell, a `bash` that
277
277
  `cd`s or `git -C`s into this checkout. `.fleet/`, `.worktrees/` and
278
278
  `.agent-brain/` are gitignored and never trip it. Nor does this run's own
279
- bookkeeping: `docs/metrics/tier-outcomes.tsv` and
280
- `docs/metrics/member-outcomes.tsv`, which you write mid-run, are left out
281
- by name — anything else under `docs/metrics/` still trips it. **The same
279
+ bookkeeping: `docs/metrics/tier-outcomes.tsv`,
280
+ `docs/metrics/member-outcomes.tsv` and `docs/metrics/ticket-features.tsv`,
281
+ which you write mid-run, are left out by name — anything else under
282
+ `docs/metrics/` still trips it. **The same
282
283
  command is the clear, and it overwrites; it never compares.** On `MAIN-CHECKOUT-DIRTY`
283
284
  the maintainer resolves the stray paths FIRST — inspect, keep or remove
284
285
  them — and only then re-runs `--record`; re-recording over unresolved paths
@@ -327,6 +328,23 @@ phase, or in any later one, asks the maintainer which tickets to take.
327
328
  there unnoticed because the only thing that ever read the live gate was a
328
329
  person choosing to.
329
330
 
331
+ **Drain the pending ticket-features rows and refresh the cost guard, after
332
+ the fast-forward and before the first Pull is routed.**
333
+ `~/.fleet/bin/fleet-run metrics-refresh.mjs` moves
334
+ `.fleet/ticket-features.pending.tsv` into `docs/metrics/ticket-features.tsv`,
335
+ deduped on `session`+`agent` — this recovers the rows of a run that crashed
336
+ before its close-out — and then runs `pr-cost.mjs --guard`, rewriting
337
+ `.fleet/cost-guard.json`, which the router reads and fails closed without
338
+ (no file: the default cell only). The guard has to be fresh before the
339
+ first Pull is routed, so the verdict reflects any rows just recovered. Exit
340
+ 0: both ran. The guard's own exit 3 (a cell tripped) and 4 (no verdict yet)
341
+ are verdicts the router and `fleet-tick.mjs` read, never failures; the
342
+ script absorbs them. A workspace that lacks one of the three metrics TSVs
343
+ has no corpus to guard yet — its first run: the script prints a line naming
344
+ the missing file, skips the guard and exits 0. Exit 1 or 2 stops the run
345
+ before its first Pull: report the line the script printed on stderr, fix
346
+ the cause and run it again — each duty is safe to repeat.
347
+
330
348
  **Launch the cockpit.** On every phase-0 pass, not just the first:
331
349
  `node ~/.fleet/bin/fleet-run board.mjs serve --open &` in the
332
350
  background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
@@ -453,15 +471,16 @@ phase, or in any later one, asks the maintainer which tickets to take.
453
471
  timed out. It is never a loop: no third derivation, and never a cache
454
472
  written by hand.
455
473
 
456
- **Fold in every PR a prior run left open, before shortlisting.** A chore PR
457
- carrying that run's own metrics, or ticket work whose review was deferred —
458
- both are reviewable work no member otherwise picks up, because the Shortlist
459
- holds ISSUES and nothing looks at inherited PRs. Queue each for review exactly as
460
- ticket work: same review workflow, same fix-applier, same finisher. Measured
461
- 2026-09-03 — a prior run's ticket PR arrived this way and its review found a defect its own PR
462
- body called unreviewed, and a chore PR's review then caught two metrics rows the
463
- controller had missed in its own close-out, so a chore PR is not exempt from
464
- being wrong. Reviewing them next run is also what stops one pinning
474
+ **Fold in every PR a prior run left open, before shortlisting.** However it
475
+ is named and whatever it carries — ticket work whose review was deferred, or
476
+ that run's own metrics — it is reviewable work no member otherwise picks up,
477
+ because the Shortlist holds ISSUES and nothing looks at inherited PRs. Queue
478
+ each for review exactly as ticket work: same review workflow, same
479
+ fix-applier, same finisher. Measured 2026-09-03 — a prior run's ticket PR
480
+ arrived this way and its review found a defect its own PR body called
481
+ unreviewed, and a metrics PR's review then caught two metrics rows the
482
+ controller had missed in its own close-out, so no PR is exempt from being
483
+ wrong. Reviewing them next run is also what stops one pinning
465
484
  `fleet-tick`'s backlog forever: unreviewable AND uncounted is the state
466
485
  that strands it.
467
486
 
@@ -1396,27 +1415,35 @@ why in `note`.
1396
1415
  Each WARNING names a PR this run's ledger marks `reviewed=` that has no row yet
1397
1416
  — append it before committing if it is an implementer PR.
1398
1417
 
1399
- Both files are the run's own artifacts and neither commits itself. Carry them to
1400
- main the same way the run carries any other controller-authored change; leaving a
1401
- regenerated 5,000-row corpus uncommitted in the checkout is how it gets discarded by
1402
- the next `git checkout` with nothing to show it ever ran.
1403
-
1404
- **Commit both to `chore/run-artifacts-<date>` and open a PR — at end of run, and
1405
- that branch name is the convention rather than a suggestion.** Phase 0's
1406
- fast-forward step calls this the previous run's close-out PR and says the rules
1407
- THIS run needs arrive in it, so the next controller goes looking for it by shape;
1408
- a name of your own invention still merges and still cannot be found. Suffix a
1409
- letter when the date already has one (`chore/run-artifacts-2026-08-23b`).
1410
-
1411
- **Data rows and rule-doc prose never share a PR — one branch each, and when the
1412
- rules here compete this is the one to keep.** The two halves have opposite cost
1413
- profiles, and bundling makes the cheap-to-strand half gate the expensive one.
1414
- Stranding a data row loses it: `member-outcomes.tsv` is regenerated from harness
1415
- transcripts this repo does not own, so re-running the scrape later is worth only
1416
- what the harness still holds. Stranding a rule change costs the status quo, which
1417
- is where it already was. So `chore/run-artifacts-<date>` carries the two
1418
- `docs/metrics/` files and nothing else, and prose that wants review goes on its
1419
- own branch with its own PR.
1418
+ **Drain the pending ticket-features rows and refresh the cost guard, after
1419
+ the member-outcomes scrape and every `tier-outcomes.mjs append`, before the
1420
+ metrics files are committed.** `~/.fleet/bin/fleet-run metrics-refresh.mjs`
1421
+ moves `.fleet/ticket-features.pending.tsv` — the row the router script
1422
+ appended for each Pull at dispatch — into `docs/metrics/ticket-features.tsv`,
1423
+ deduped on `session`+`agent`, so this run's own rows are in the file that gets
1424
+ committed; that file is a run artifact too and is committed with the other
1425
+ two. It then runs `pr-cost.mjs --guard`, which rewrites
1426
+ `.fleet/cost-guard.json` from all three files. Exit 0: both ran. The guard's
1427
+ own exit 3 (a cell tripped) and 4 (no verdict yet, baseline too thin) are
1428
+ verdicts the router and `fleet-tick.mjs` read, never failures; the script
1429
+ absorbs them. Exit 1 names the duty that failed on stderr and the duty after it
1430
+ did not run; exit 2 is a usage error. At close-out a failure is reported to the
1431
+ maintainer and does not stop the commit — the pending file stays in `.fleet/`
1432
+ and the next run's phase-0 pass drains it — but never commit the metrics files
1433
+ with a drain that failed claiming the corpus is complete.
1434
+
1435
+ The metrics files are the run's own artifacts and none commits itself. Carry
1436
+ them to main the same way the run carries any other controller-authored change;
1437
+ leaving a regenerated 5,000-row corpus uncommitted in the checkout is how it gets
1438
+ discarded by the next `git checkout` with nothing to show it ever ran.
1439
+
1440
+ **Commit the metrics files and open a PR — at end of run.** The branch name is
1441
+ the repository's choice. A PR still open when the run ends is one phase 0's
1442
+ fold-in queues for review next run, however it is named, so the files reach
1443
+ `main` through the same review as ticket work rather than being lost. Stranding
1444
+ a data row loses it: `member-outcomes.tsv` is regenerated from harness
1445
+ transcripts the fleet does not own, so re-running the scrape later is worth
1446
+ only what the harness still holds.
1420
1447
 
1421
1448
  **Why not decide inside one run.** A run holds 2-3 implementer PRs, and ticket
1422
1449
  difficulty swamps the tier effect — a gojq parity harness and a two-statement
@@ -3578,20 +3605,20 @@ where the controller itself runs from.
3578
3605
  (**Resolving a finisher halt**) — and it
3579
3606
  prints them as `review-due=`. Exact, not a wider read: the ledger records
3580
3607
  which PRs are under review or reviewed, so nothing about it is guesswork. The
3581
- closing-issue test is what keeps it from widening: a chore PR you author
3582
- yourself closes nothing and is left unlabelled for the maintainer, so no
3583
- member of the fleet will ever review it, and counting it floors the backlog at
3584
- a depth nothing in the run can drain — the implementer gate then holds for the
3585
- rest of the run against a queue of nothing. GitHub's own linked-issue
3586
- set decides that, not a keyword regex over the body.
3587
- **That exemption is for the chore PR THIS run
3588
- authors, never one a PRIOR run left open** — step 0 folds those into this
3589
- run's review queue, so count one when you reason about backlog BY HAND. **The
3590
- `fleet-tick.mjs` number still excludes it**: nothing in its filter
3591
- distinguishes an inherited chore PR from this run's own, since a PR closing no
3592
- issue fails the closing-issue test either way — folding one in cannot reach
3593
- the count. So the by-hand judgement and the script's output differ here, and
3594
- such a PR's review is dispatched by hand.
3608
+ closing-issue test is what keeps it from widening: a PR that closes no issue
3609
+ — one you author yourself, for instance — is left unlabelled for the
3610
+ maintainer, so no member of the fleet will ever review it, and counting it
3611
+ floors the backlog at a depth nothing in the run can drain — the implementer
3612
+ gate then holds for the rest of the run against a queue of nothing.
3613
+ GitHub's own linked-issue set decides that, not a keyword regex over the body.
3614
+ **That exemption is for a PR THIS run authors, never one a PRIOR run left
3615
+ open** — step 0 folds those into this run's review queue, so count one when
3616
+ you reason about backlog BY HAND. **The `fleet-tick.mjs` number still
3617
+ excludes it**: nothing in its filter distinguishes an inherited PR from this
3618
+ run's own, since a PR closing no issue fails the closing-issue test either
3619
+ way — folding one in cannot reach the count. So the by-hand judgement and
3620
+ the script's output differ here, and such a PR's review is dispatched by
3621
+ hand.
3595
3622
 
3596
3623
  **Defaults: 2 implementers, 6 reviewers — no hard cap on either.** Reviewer
3597
3624
  slots in use ≈ I·(T_review + 0.94·T_fix)/T_impl ≈ 1.95·I (medians since
@@ -3667,12 +3694,12 @@ A starved implementer queue never stalls the review or merge side.
3667
3694
  **The run's own artifact PR is exempt, and it is exempt because this invariant
3668
3695
  does not reach it:** what the line forbids is a fleet member signing off its own
3669
3696
  ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
3670
- finisher, and the data-only close-out PR you author has none of them. Label and
3697
+ finisher, and the metrics PR you author has none of them. Label and
3671
3698
  merge that one yourself instead of re-deriving a blocker from this line and
3672
3699
  stranding the rows behind it. The exemption belongs to the run that authors the
3673
3700
  PR and does not outlive it: one still open when the run ends is a PR a prior run
3674
3701
  left open, which phase 0 folds into the next run's review queue as ticket work —
3675
- and a chore PR is not exempt from being wrong, only from waiting on a reviewer
3702
+ and a PR is not exempt from being wrong, only from waiting on a reviewer
3676
3703
  no phase of this run will ever dispatch against it.
3677
3704
  - **Every member acts through the maintainer's `gh` credentials, so no write is
3678
3705
  attributable.** Any invariant about *who* did something is unenforceable after