@feigi/fleet-ctl 3.47.2 → 3.47.4

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.
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: review a PR, apply recommended actions, push, watch checks until green
2
+ description: review a PR, apply recommended actions, push — standalone, then watch checks until green; under the fleet, report and stop (the controller owns the CI wait)
3
3
  argument-hint: [pr-number]
4
4
  ---
5
5
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.47.2",
3
+ "version": "3.47.4",
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,11 +65,12 @@
65
65
  // never a path.
66
66
  // unknown — some read failed: git, a hash, HEAD, `origin/main`, or a baseline
67
67
  // that EXISTS but cannot be read (unreadable file, unsearchable
68
- // `.fleet/`, dangling symlink, not written by --record) — or is a
69
- // v1 baseline, which says nothing of HEAD: re-record it — or names
70
- // a commit absent from the repository: examine HEAD, then
71
- // re-record it. "A failure is an unknown answer, never a 'no'" —
72
- // never `clean`.
68
+ // `.fleet/`, dangling symlink, not written by --record) — or is
69
+ // an older version's baseline, which this code cannot compare:
70
+ // re-record it — or is a newer version's, written by a newer
71
+ // plugin: run that plugin — or names a commit absent from the
72
+ // repository: examine HEAD, then re-record it. "A failure is an
73
+ // unknown answer, never a 'no'" — never `clean`.
73
74
  // absent — no baseline at all: the run never recorded one. A refusal
74
75
  // ("record at run start"), never `clean`.
75
76
  //
@@ -78,10 +79,11 @@
78
79
  // the maintainer's clear only AFTER the stray paths are resolved. Over `unknown`
79
80
  // it would walk the run from "could not look" to "certified clean" in one step,
80
81
  // so it refuses on every unknown cause it can see: a baseline that exists but
81
- // cannot be read, and any failed git or hash read (no snapshot, nothing to
82
- // write). A detached HEAD has no symbolic ref to record, so it refuses that
83
- // too. A v1 baseline, and one whose commit is gone (it never reads the
84
- // recorded commit), it overwrites without a word.
82
+ // cannot be read, one a newer plugin wrote (overwriting it would discard a
83
+ // baseline nobody read), and any failed git or hash read (no snapshot, nothing
84
+ // to write). A detached HEAD has no symbolic ref to record, so it refuses that
85
+ // too. An older version's baseline, and one whose commit is gone (it never
86
+ // reads the recorded commit), it overwrites without a word.
85
87
  //
86
88
  // A BASELINE COMMIT GONE FROM THE REPOSITORY is its own unknown. An amend or
87
89
  // reset leaves the baseline's commit unreachable, and once reflog expiry and
@@ -121,8 +123,12 @@ import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
121
123
  export const BASELINE_FILE = "main-checkout.sha";
122
124
  export const RECORD_COMMAND = "~/.fleet/bin/fleet-run main-checkout.mjs --record";
123
125
  const RUN_BOOKKEEPING = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
124
- const HEADER_V1 = "fleet main-checkout baseline v1";
125
- const HEADER = "fleet main-checkout baseline v2";
126
+ // Any change to an entry's hash or to a line's format bumps VERSION: a
127
+ // baseline an older plugin wrote then reads `outdated` (re-record) and one a
128
+ // newer plugin wrote reads `newer`, never as a baseline this code wrote.
129
+ const VERSION = 2;
130
+ const HEADER = `fleet main-checkout baseline v${VERSION}`;
131
+ const HEADER_RE = /^fleet main-checkout baseline v(\d+)$/;
126
132
  const GIT_TIMEOUT_MS = 30_000;
127
133
  const MAX_BUFFER = 64 * 1024 * 1024;
128
134
  const NAME = "main-checkout";
@@ -320,7 +326,8 @@ function headMove(root, env, was, now) {
320
326
 
321
327
  /**
322
328
  * The run's baseline: `{status: "ok", entries, head}`, `{status: "absent"}`,
323
- * `{status: "outdated", why}` (a v1 file) or `{status: "unreadable", why}`.
329
+ * `{status: "outdated", why}` (an older VERSION's file), `{status: "newer",
330
+ * why}` (a newer VERSION's) or `{status: "unreadable", why}`.
324
331
  * ABSENT is only "nothing at that name": a
325
332
  * dangling symlink is present-but-broken, and an unsearchable `.fleet/`
326
333
  * answers EACCES rather than ENOENT, so neither can fall through to
@@ -343,7 +350,9 @@ export function readBaseline(path) {
343
350
  return { status: "unreadable", why: `${path} exists but cannot be read: ${e?.code ?? e?.message}` };
344
351
  }
345
352
  const lines = text.split("\n");
346
- if (lines[0] === HEADER_V1) return { status: "outdated", why: "baseline v1 — re-record" };
353
+ const version = HEADER_RE.exec(lines[0]);
354
+ if (version && Number(version[1]) < VERSION) return { status: "outdated", why: `baseline v${version[1]} — re-record` };
355
+ if (version && Number(version[1]) > VERSION) return { status: "newer", why: `baseline v${version[1]} written by a newer plugin` };
347
356
  const ref = lines[1]?.startsWith("ref ") ? lines[1].slice(4) : "";
348
357
  const oid = lines[2]?.startsWith("oid ") ? lines[2].slice(4) : "";
349
358
  if (lines[0] !== HEADER || lines.at(-1) !== "" || !ref || !/^[0-9a-f]{40,64}$/.test(oid)) {
@@ -370,10 +379,11 @@ export function changedPaths(baseline, current) {
370
379
 
371
380
  /**
372
381
  * The tick's question: `{state, root?, baseline?, changed?, headMove?, why?, cause?}`.
373
- * `cause` tells the four unknowns apart — `"baseline"` (it exists but cannot
374
- * be read), `"outdated"` (a v1 baseline: it says nothing of HEAD, so it can
375
- * answer nothing), `"missing"` (the baseline's commit is absent from the
376
- * repository) and `"read"` (git or a hash failed) — since each has its own
382
+ * `cause` tells the unknowns apart — `"baseline"` (it exists but cannot
383
+ * be read), `"outdated"` (an older version's baseline: this code cannot
384
+ * compare it, so it can answer nothing), `"newer"` (a newer plugin wrote it),
385
+ * `"missing"` (the baseline's commit is absent from the repository) and
386
+ * `"read"` (git or a hash failed) — since each has its own
377
387
  * message. The baseline is read before the tree, because without one there
378
388
  * is nothing to compare against and no reason to look.
379
389
  * A HEAD move is the first entry of `changed`, also named in `headMove`.
@@ -388,6 +398,7 @@ export function checkMainCheckout({ cwd = process.cwd(), env = process.env } = {
388
398
  const unknown = (why, cause = "read") => ({ state: "unknown", cause, root, baseline: path, why });
389
399
  if (base.status === "unreadable") return unknown(base.why, "baseline");
390
400
  if (base.status === "outdated") return unknown(base.why, "outdated");
401
+ if (base.status === "newer") return unknown(base.why, "newer");
391
402
  const now = readState(root, env);
392
403
  if (!now.ok) return unknown(now.why);
393
404
  const move = headMove(root, env, base.head, now.head);
@@ -426,6 +437,7 @@ export function describe(check, live = null) {
426
437
  return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
427
438
  + ` — dispatch held: resolve any stray paths FIRST, then re-record with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
428
439
  }
440
+ if (check.cause === "newer") return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members} — dispatch held: run the plugin that wrote it`;
429
441
  if (check.cause === "missing") {
430
442
  return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
431
443
  + " — dispatch held: examine HEAD against origin/main FIRST, since a missing baseline commit means HEAD moved off it by an amend or reset nobody has looked at, and resolve any stray paths;"
@@ -441,10 +453,11 @@ export function describe(check, live = null) {
441
453
 
442
454
  /**
443
455
  * Write the baseline: `{ok, path, entries, head}` or `{ok: false, why}`.
444
- * Refuses over a baseline that exists but cannot be read — overwriting it
445
- * blind discards evidence nobody read — and on any failed read of the tree, of
446
- * HEAD or of `origin/main`, and on a detached HEAD, which has no symbolic ref
447
- * to record. A v1 baseline is not unreadable: it is the one this overwrites.
456
+ * Refuses over a baseline that exists but cannot be read, and over one a
457
+ * newer plugin wrote — overwriting either blind discards evidence nobody
458
+ * read — and on any failed read of the tree, of HEAD or of `origin/main`, and
459
+ * on a detached HEAD, which has no symbolic ref to record. An older version's
460
+ * baseline is not unreadable: it is the one this overwrites.
448
461
  * Written to a temporary name and renamed, so a reader never sees half of it.
449
462
  */
450
463
  export function recordBaseline({ cwd = process.cwd(), env = process.env } = {}) {
@@ -455,6 +468,9 @@ export function recordBaseline({ cwd = process.cwd(), env = process.env } = {})
455
468
  if (prior.status === "unreadable") {
456
469
  return { ok: false, why: `${prior.why} — fix it first; do NOT --record over it, --record overwrites rather than compares` };
457
470
  }
471
+ if (prior.status === "newer") {
472
+ return { ok: false, why: `${prior.why} — run the plugin that wrote it; do NOT --record over it, --record overwrites rather than compares` };
473
+ }
458
474
  const now = readState(where.root, env);
459
475
  if (!now.ok) return { ok: false, why: `${now.why} — could not look, so there is nothing to record` };
460
476
  if (now.head.ref === null) {
@@ -307,10 +307,11 @@ phase, or in any later one, asks the maintainer which tickets to take.
307
307
  them — and only then re-runs `--record`; re-recording over unresolved paths
308
308
  certifies them. **Never re-record over `MAIN-CHECKOUT-UNKNOWN`**: that
309
309
  walks the run from "could not look" to "certified clean" in one step, so
310
- `--record` itself refuses over a baseline it cannot read and on any git
311
- read that fails. The exceptions are a v1 baseline and a baseline whose
312
- commit is missing from the repository; Phase 3's tick lines say how each
313
- is cleared. `main-checkout.mjs --check` prints the same answer
310
+ `--record` itself refuses over a baseline it cannot read, over one a newer
311
+ plugin wrote, and on any git read that fails. The exceptions are an
312
+ older-version baseline and a baseline whose commit is missing from the
313
+ repository; Phase 3's tick lines say how each is cleared.
314
+ `main-checkout.mjs --check` prints the same answer
314
315
  without a tick.
315
316
 
316
317
  **Run the pre-flight, once the pin and the baseline are recorded.**
@@ -1760,7 +1761,9 @@ owes beyond its row:
1760
1761
  runner — **Reviewers** says which, per harness) and record `reviewed=` off its
1761
1762
  digest with `ledger.mjs review <M>`, then run the tick: a PR with survived or unverified findings prints as
1762
1763
  `DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
1763
- fix-applier and dispatch the **finisher** directly: no member will touch that
1764
+ fix-applier and dispatch the **finisher** directly — or, when that head's
1765
+ bound conclusion is red and not solely staleness, the red-check fixer
1766
+ instead (**Then dispatch a red-check fixer**, below): no member will touch that
1764
1767
  PR, so no push is coming and nothing will wake you. A review that failed is
1765
1768
  not a result — **Reviewers** says who retries it and what takes over.
1766
1769
  - **Monitor: `ready-to-merge` appears** → nothing to record; run the tick, and
@@ -1811,7 +1814,9 @@ owes beyond its row:
1811
1814
  place. The diff-validating `check` job green with no heavy job (the
1812
1815
  diff-validating suites, not the `rebase-check` currency gate) in `failure`
1813
1816
  → a finisher CANDIDATE (gated below), a `check`
1814
- **failure** → a fixer. A `check`-green board whose heavy jobs are merely
1817
+ **failure** that is not solely staleness → the **red-check fixer** (**Then
1818
+ dispatch a red-check fixer**, below), behind the same review-returned and
1819
+ fix-applier-reported gate as a finisher. A `check`-green board whose heavy jobs are merely
1815
1820
  `skipped` (behind-count staleness, the normal case after a merge) still labels — do NOT
1816
1821
  gate on `ci-state --quiet` exit 0, which a behind PR never reaches. **This
1817
1822
  edge fires for every CI run the PR produces, and the implementer's own
@@ -1834,10 +1839,15 @@ owes beyond its row:
1834
1839
  first — including any ruling you have withdrawn or reversed — then dispatch
1835
1840
  (below); a final report is not proof it stopped. A PR that needs nothing fixed
1836
1841
  reaches a finisher through the **fix-applier reports `no-op`** bullet below,
1837
- never by waiting for a second CI event this head will never produce.
1842
+ never by waiting for a second CI event this head will never produce. The
1843
+ same goes for a red one: a red that fired before the review never fires
1844
+ again, so the **fix-applier reports `no-op`** and **review result lands**
1845
+ bullets are also the only routes to the red-check fixer there.
1838
1846
  Then run the tick.
1839
1847
  - **A fix-applier reports `no-op`, or a SHA you have already bound** → dispatch
1840
- the finisher **now**, against the existing head. No push means no new run, and
1848
+ the finisher **now**, against the existing head — when that head's bound
1849
+ conclusion is red, the red-check fixer instead (**Then dispatch a red-check
1850
+ fixer**, below), never a finisher and never a wait. No push means no new run, and
1841
1851
  the Monitor above is edge-keyed on `<run-id>:<attempt>:<conclusion>` — that
1842
1852
  head's terminal state already fired once and will never fire again, so waiting
1843
1853
  for the CI event waits forever. This stays a common outcome on a clean PR:
@@ -1972,13 +1982,15 @@ depth** guard table applied in code. Act on each line as it reads:
1972
1982
  could not look: a git or hash read failed (`could not look:`), or the
1973
1983
  baseline exists but cannot be read (`baseline unreadable:`). Never clean,
1974
1984
  and **never re-baseline over it** — `--record` overwrites, so that certifies
1975
- a tree nobody read. Fix what the line names and tick again. The exceptions
1976
- are the two whose remedy is `--record`: `baseline v1 — re-record`, an
1977
- old-format baseline that says nothing of HEAD; and `baseline commit <oid> is
1978
- missing from this repository`, which an amend or reset followed by gc
1979
- leaves — examine HEAD against `origin/main` FIRST, since HEAD moved off
1980
- that commit and nobody has looked at the move, and resolve any stray paths,
1981
- which the line does not name; only then re-record.
1985
+ a tree nobody read. Fix what the line names and tick again. `baseline v<n>
1986
+ written by a newer plugin` is a baseline a newer plugin version wrote:
1987
+ `--record` refuses over it too — run the plugin that wrote it. The
1988
+ exceptions are the two whose remedy is `--record`: `baseline v<n> —
1989
+ re-record`, an older-format baseline this plugin cannot compare; and
1990
+ `baseline commit <oid> is missing from this repository`, which an amend or
1991
+ reset followed by gc leaves — examine HEAD against `origin/main` FIRST,
1992
+ since HEAD moved off that commit and nobody has looked at the move, and
1993
+ resolve any stray paths, which the line does not name; only then re-record.
1982
1994
  - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
1983
1995
  baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
1984
1996
  that vanished mid-run is not a fresh run — report it to the maintainer
@@ -2556,6 +2568,46 @@ is a review fix-applier, dispatched as above. On a PR carrying
2556
2568
  bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
2557
2569
  handling**.
2558
2570
 
2571
+ **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the
2572
+ PR's current head that is not **solely** staleness: a `rebase-check` red, or
2573
+ heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the
2574
+ five-condition note in the fix-applier block below states how to establish
2575
+ that). The tick prints no `DISPATCH` for it, so you reconcile it yourself, and
2576
+ it always goes after the review, never before. Take the common case, the
2577
+ implementer's own first CI firing turning red before any review exists: the
2578
+ review is still dispatched against that head as normal, because a red suite is
2579
+ review evidence and not a blocker. While a review or a review fix-applier on
2580
+ the PR is live or still owes its report — a dispositions mismatch awaiting its
2581
+ retry and a conflict hold awaiting its fix-applier included — the red-check
2582
+ fixer does not fire: their push starts a new run, and a fixer racing them
2583
+ would work on a SHA that is still moving. These edges dispatch it, each the
2584
+ finisher's own: **Monitor: CI run completes** binding a red on a head
2585
+ whose review has returned and whose fix-applier, if any, has reported;
2586
+ **A fix-applier reports `no-op`**, or a SHA you have already bound, when that
2587
+ head's bound conclusion is red; and **A review result lands** with no finding
2588
+ and nothing to file, when that head's bound conclusion is red. The Monitor is
2589
+ edge-keyed on `<run-id>:<attempt>:<conclusion>`, so a red that fired before the
2590
+ review never fires again, and with no push there is no new run — the other
2591
+ edges are the only route there, so do not wait for an event. Edit one of these
2592
+ bullets without the others and what strands is exactly the red-only PR.
2593
+
2594
+ Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
2595
+ refuses a reused name — record it with `ledger.mjs dispatch <pr#> <name>`
2596
+ before the call, and dispatch it with the `agent` that command printed (`null`
2597
+ while no conflict hold stands, as for a review fix-applier), in the PR's
2598
+ existing worktree. Its prompt takes the prompt below's worktree, branch and
2599
+ path discipline, but in place of its review paragraphs: read the failing job's
2600
+ log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
2601
+ It is told outright not to watch, poll or wait for CI: your persistent Monitor
2602
+ owns the next run on the pushed head, and the finisher gate — review returned
2603
+ AND fix-applier report sent — applies to this member the same way. Settle it
2604
+ `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red
2605
+ turns out not to be this member's to fix — a flake that passes on rerun, or
2606
+ staleness — with nothing pushed; `no-op` counts as landed, so it never stands
2607
+ for "could not fix". Settle it `failed` when it cannot reach green, which the
2608
+ **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot
2609
+ reach green" covers.
2610
+
2559
2611
  **A `DISPATCH fix-pr PR#<M>` on a dispositions mismatch** — the PR's row carries
2560
2612
  `dispositions-mismatch=<member>:<run>` for its latest review's run, and no later
2561
2613
  fix-applier has landed — is one automatic retry, a review fix-applier named the
@@ -4144,7 +4196,7 @@ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
4144
4196
  | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
4145
4197
  | Implementer blocked or ambiguous *mid-implementation* | Free the slot, leave `in-progress`, report — the row above is the pre-code bail, not this one |
4146
4198
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
4147
- | Reviewer or fix-applier cannot reach green | Report, leave the PR unlabeled, free the slot |
4199
+ | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — a fix-applier or red-check fixer settles `failed` |
4148
4200
  | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
4149
4201
  | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
4150
4202
  | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |