@feigi/fleet-ctl 3.142.0 → 3.143.1

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.
@@ -32,7 +32,7 @@ into one free implementer slot, the moment it frees (phase 1).
32
32
 
33
33
  `phase0.mjs` runs the start sequence in
34
34
  its fixed order — alarm, branch, fast-forward, pin, baseline, labels, preflight, ruleset,
35
- tier-roles, metrics, cockpit, rotate, reclaim, evict, recipe, fold-in, stranded,
35
+ tier-roles, metrics, cockpit, rotate, catch-up, reclaim, evict, recipe, fold-in, stranded,
36
36
  shortlist — prints one `phase0: <step>: <status>` line per step with the
37
37
  `NEED` lines last, and records each step in `.fleet/phase0.json`, which the
38
38
  tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
@@ -79,6 +79,8 @@ yourself. The baseline records the root it
79
79
  certified beside the digest, and every later check — yours, a finisher's, the
80
80
  merge gate's own leg — compares it with the live root and refuses when they
81
81
  differ. Never dispatch a member into a run whose phase-0 pin refused.
82
+ `phase0.mjs` records the version the pin wrote into the receipt as
83
+ `pluginVersion`, so the run's archived receipt says which plugin it ran.
82
84
 
83
85
  ## Record the main-checkout baseline
84
86
 
@@ -388,13 +390,39 @@ archives, hand-named ones included, are left alone.
388
390
  Before the rotation, `phase0.mjs` puts the held-aside receipt (`phase0.previous.json`) back at `phase0.json`, which `ledger.mjs rotate` then files as `phase0.<UTC stamp>.json`.
389
391
  `ledger.mjs rotate` archives the run's two receipts with the ledger, under the ledger archive's own stamp: `.fleet/phase0.<UTC stamp>.json` and `.fleet/closeout.<UTC stamp>.json` beside `.fleet/ledger.<UTC stamp>.md`.
390
392
 
393
+ ## Catch up the run records
394
+
395
+ **Catch up the run records straight after the rotation, before the reclaim —
396
+ every run.** The `catch-up` step copies every run archive in `.fleet/` — the
397
+ previous run's, which the rotation has just filed, and any earlier one — into
398
+ `docs/metrics/runs/<UTC stamp>/`, and every review's evidence under the
399
+ scratch root into `docs/metrics/reviews/<pr>/<run>/`, the same gather the
400
+ close-out runs (references/close-out.md). When main lacks a record of a run
401
+ that never closed out — no `.fleet/closeout.<UTC stamp>.json` beside its
402
+ ledger archive — it commits every file main lacks alone on a branch of its own
403
+ in this checkout, pushes it, opens a PR and switches back to `main`; the
404
+ metrics files' changes stay in the work tree, out of that commit. The PR is an
405
+ Owned PR, so the fold-in below queues it. A run that closed out leaves its
406
+ records to this run's close-out, which gathers them again, so the step opens
407
+ no second PR carrying the same files and its output says so. A run whose
408
+ close-out never ran therefore loses nothing: its ledger, receipts and version
409
+ reach main here, and its review evidence is still in scratch when the reclaim
410
+ runs, which keeps a merged PR's evidence until main holds it. The step never
411
+ stops the run but for a checkout it could not switch back to `main`; a commit
412
+ it could not make is named in its output, with how far it got — a branch
413
+ pushed with no PR open for it is named so — and the close-out gathers those
414
+ files again.
415
+
391
416
  ## Reclaim scratch
392
417
 
393
- **Reclaim scratch straight after the rotation — every run.**
418
+ **Reclaim scratch straight after the catch-up — every run.**
394
419
  `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --root <scratch>
395
420
  --after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
396
421
  so a run that merges nothing still reclaims the previous run's leftovers
397
422
  (`reclaim-scratch.mjs`'s header says what it removes).
423
+ A merged PR's `pr<pr>/` and Charges files that hold review evidence stay
424
+ until `origin/main` holds that evidence under `docs/metrics/reviews/<pr>/`,
425
+ and a lookup that cannot answer keeps them.
398
426
  `--after-rotate` goes on this call always and on no other: rotate leaves
399
427
  no ledger behind when it carried nothing, and the flag reads that absence
400
428
  as "no live token" — rotate's own verdict — where without it the script
@@ -25,7 +25,8 @@ Every precondition recomputed **inside** same command as delete:
25
25
  - **A branch with no upstream is selected only when origin has no branch of its name and its merged PR recorded its tip.** `%(upstream)` is empty for it, so `%(upstream:track)` has no `[gone]` to match. It is selected when `refs/remotes/origin/<b>` is absent after the sweep's own `fetch --prune`, and the second proof below ties its tip, read once, to a head its merged PR recorded; `git cherry` neither authorizes nor vetoes it, and there is no name filter. A tip already on `origin/main` ties only by **equality** with a recorded head, never by ancestry: a claim is cut from whatever `origin/main` the clone last fetched, so a fresh claim that reuses a merged PR's branch name on a clone that has not fetched that merge has no commits of its own and a tip that is an ancestor of that PR's heads — ancestry would tie it, and the reap would remove the live member's clean worktree and branch. Every keep reads `no upstream — <cause>`; where there is no GitHub repository to ask (`BASE_REF` is not an `origin` ref, or `origin` is not a `host/owner/repo` URL) it is never selected and the reason stays `no upstream — never selected`. Once selected, the worktree guards, the holder check and the compare-and-swap below run on it as on a `[gone]` branch. Its upstream arrives with the first `-u` push, or when the controller settles the implementer's report.
26
26
  - **Recompute per branch, in this command.** Branch list from earlier tool call already false: one observed run listed 28 gone branches, two calls later 27 reaped by concurrent session. Benign direction is no-op; dangerous one is worktree that gained work *after* check.
27
27
  - **`git cherry origin/main`, not `git diff main..`.** Against `origin/main` — local `main` you never fast-forwarded reads every merged branch as unmerged. A `+` line is a commit with no patch-equivalent upstream, which is usually a commit that exists nowhere else but not always: a claim the merge bot rebased server-side onto a `main` that had changed its context lines carries a different patch id, so its original tip reads `+` although everything on it merged. That keep is safe but leaky, and the second proof below is what closes it.
28
- - **The delete is `git update-ref -d`'s compare-and-swap on a tip read once, authorized by that cherry check and by a fresh check, re-read immediately before the delete, that no worktree holds the branch.** Tip read before the cherry, cherry runs against that SHA, delete refuses unless ref still equals it — commit landing between check and delete is kept with git's own `cannot lock ref`, never force-deleted, as it was under `git branch -D`, the delete this replaced. `--no-deref`, so symref branch deletes the symref, not its target (measured). Branch's config section removed after, as `-D` did — left behind, re-created branch of same name inherits dead upstream and reads `[gone]` at once. `git branch -d` would refuse everything here: upstream gone, so falls back to comparing against `HEAD`, a possibly-behind local `main`. Never delete branch whose cherry output you did not just read.
28
+ - **A branch whose commits all read `-` is merged only if every one of them pairs.** A patch id ignores where in a file a change sits and any whitespace in it, so a commit making a merged change again at another place in the same file — the second of two identical blocks — or differing from a merged commit only in whitespace reads `-` while no other ref holds it. So each commit `C` that `origin/main` lacks has to pair: a commit `M` on `origin/main` carries `C`'s `git patch-id --stable`, and `git merge-tree --write-tree --merge-base=C^ M^ C` writes exactly `M`'s tree — `C` replayed onto `M`'s parent is `M`. Anything less is a KEEP with its reason: a merge commit in the range (`git cherry` skips merges, so what one changes is read by nothing), a commit no `M` carries the patch id of (an empty commit has none — a harmless false keep), a replay that differs from or conflicts with every such `M`, and any probe that fails. A `+` is not the pair test's to rule on; it keeps, or goes to the second proof below.
29
+ - **The delete is `git update-ref -d`'s compare-and-swap on a tip read once, authorized by that cherry check, the pair test above, and a fresh check, re-read immediately before the delete, that no worktree holds the branch.** Tip read before the cherry, cherry runs against that SHA, delete refuses unless ref still equals it — commit landing between check and delete is kept with git's own `cannot lock ref`, never force-deleted, as it was under `git branch -D`, the delete this replaced. `--no-deref`, so symref branch deletes the symref, not its target (measured). Branch's config section removed after, as `-D` did — left behind, re-created branch of same name inherits dead upstream and reads `[gone]` at once. `git branch -d` would refuse everything here: upstream gone, so falls back to comparing against `HEAD`, a possibly-behind local `main`. Never delete branch whose cherry output you did not just read.
29
30
  - **A branch any worktree holds is a KEEP, checked right before the delete.** `update-ref` consults no worktree; `-D` did. So listing is re-read and worktree.sh's `wt_holding` asks: held by a `branch` line, or by detached worktree stopped mid `rebase -i` / mid `bisect` on it (admin dir's `head-name` / `BISECT_START`) — both routes `-D` refused on. Worktree it cannot resolve, or listing that will not re-read, is a KEEP. `--apply` only, like the delete: dry run cannot predict this refusal — not the same limitation `-D`'s dry run had, since an unrelated worktree elsewhere in the listing that this check cannot resolve keeps every `[gone]` branch, and every selected one with no upstream, in the pass (see below), a repo-wide case `-D` never produced.
30
31
  - **A worktree that checked the branch out while the delete ran is caught after it, and the branch is put back.** git has no lock that stops `git worktree add <p> <b>` between that holder check and the delete, and such an add writes only the new worktree's `HEAD` — the ref does not move, so the compare-and-swap succeeds and leaves the worktree on a branch that no longer exists (measured, git 2.50.1). So worktree.sh's `wt_recheck_delete` re-reads the listing right after the delete — and again, up to 20 times 0.1s apart, while an add in progress is listed `locked initializing` — and when a worktree holds the branch, or the wait runs out, recreates it at the tip with a create-only `git update-ref`. The branch is a KEEP naming the worktree or the entry, and its config section stays. A restore that fails is a KEEP naming the tip, git's error and the command that restores it by hand — or, when something recreated the branch since the delete, the commit it now sits at, left as it is, since the create-only restore never overwrites it. The branch's reflog does not come back.
31
32
  - **A cherry that cannot answer is a KEEP.** Capture git's output; never pipe git itself: `cmd | grep -q` takes grep's exit status, never cmd's, so a `git cherry` that dies (rc 128 — one unreadable loose object is enough) prints nothing, grep exits 1, and a dead probe reads identical to "nothing unmerged" (verified, git 2.50.1). Unanswerable probe authorizes no delete — same fail-closed shape as `worktree remove` below. Read the `+` anchored, too: the capture folds stderr in, so an unanchored match reads a `+` in a diagnostic as a commit. Pinned by a test.
@@ -45,7 +46,7 @@ Above walk finds branch's worktree by `branch refs/heads/<name>` line `git workt
45
46
  So `reap.sh` enumerates worktrees git lists with **no `branch` line at all** and decides each on own state:
46
47
 
47
48
  - **Bounded to `*/.worktrees/*` — fleet's own worktree home — and everything outside it is a `kept` entry.** Branch sweep authorizes its branch delete on evidence PR merged (`%(upstream:track)` reads exactly `[gone]`). This sweep has none to read: branchless + clean + patch-equivalent also describes human's `git worktree add --detach` scratch checkout that was never ticket. Unbounded, `--apply` deleted it (measured in review). Bound is ownership, never contents.
48
- - **`git cherry` against `origin/main`, never `merge-base --is-ancestor`.** Branch was rebased before it merged, so tip fully upstream is patch-equivalent, not ancestor — ancestry answers no for exactly work that is safe. A `+` can also be context drift rather than missing work, so its keep is safe but leaky; this sweep's code is unchanged, and it has no branch name to look a PR up by. Subject is full object id off porcelain, so no refname shadows it.
49
+ - **`git cherry` against `origin/main`, never `merge-base --is-ancestor`.** Branch was rebased before it merged, so tip fully upstream is patch-equivalent, not ancestor — ancestry answers no for exactly work that is safe. A `+` can also be context drift rather than missing work, so its keep is safe but leaky; this sweep runs no second proof, having no branch name to look a PR up by. Where no line reads `+`, the tip has to pass the branch sweep's pair test too. Subject is full object id off porcelain, so no refname shadows it.
49
50
  - **Absent `branch` line is not by itself detached HEAD.** git prints none for worktree whose HEAD it cannot resolve either, reporting null object id instead — four measured corruption routes for admin `HEAD`. Nothing about such worktree decidable, so report and leave. Null id alone is not the test: unborn branch is legitimate null id and DOES carry `branch` line.
50
51
  - **A git operation in progress is a keep, and git is no backstop for it.** Measured, git 2.50.1 (Apple Git-155): `worktree remove` *without* `--force` removes worktree holding interrupted rebase, and one holding bisect, at rc 0. Both detach, both leave `status --porcelain` empty — so every other check passes them and sequencer state, todo list and original head go with directory. Interrupted rebase is exactly how fleet worktree wanders off its branch (see `release-ticket.sh`'s own stray guard).
51
52
  - **Every decline is a `kept` entry, `branch` null.** No branch to name. Gap was invisible precisely because nothing was reported.