@feigi/fleet-ctl 3.136.2 → 3.136.3

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.
@@ -27,12 +27,14 @@ that could not look — `outcome` `halted`, `cause` `other`, `evidence` what
27
27
  (the path you were dispatched with, and the full SHA). It finds your
28
28
  worktree's row, reads whether the tree is dirty, compares the worktree's
29
29
  `HEAD` to your pin, and when the head differs derives the cause from the
30
- reflog. Exit 0, with `cause` null, is the only code that means the worktree is
31
- clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
32
- `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
33
- `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
34
- a gap. Exit 2 means the script could not look: you are halted with cause
35
- `other`, with the line it printed on stderr as the evidence.
30
+ reflog. Exit 0, with `cause` null, is the only code that means the worktree
31
+ holds nothing your pin lacks: it sits at your pin, or it differs from it only
32
+ by commits whose patches your pin already carries. Exit 1 means `cause` is
33
+ non-null: you are halted, and `cause` is the word you name — `live-editor`,
34
+ `rebase`, `past-pin`, `stray`, `unreadable`, `missing`, `absent` or `other`,
35
+ and `other` is a cause too, not a gap. Exit 2 means the script could not look:
36
+ you are halted with cause `other`, with the line it printed on stderr as the
37
+ evidence.
36
38
 
37
39
  The pin is the SHA you were dispatched against, never `PR headRefOid`: a
38
40
  member that kept working and pushed after the pin matches the branch tip on a
@@ -44,7 +46,7 @@ it. Put the verdict, the JSON line it printed, in your report as printed: its
44
46
 
45
47
  Every cause halts, always — named or not, you never verify the dirt is
46
48
  harmless and label over it, a rebase is not a fast-forward you get to accept,
47
- a commit past the pin is not one either, and a cause you could not name is
49
+ a commit your pin lacks is not one either, and a cause you could not name is
48
50
  the least settled of the lot. Naming the cause makes the halt cheap to
49
51
  resolve, never a reason to skip it.
50
52
 
@@ -109,7 +111,7 @@ alone — it exists and is correct — and report it `unrecorded: #N <subject>`.
109
111
 
110
112
  **A fix-applier's "applied" is a claim like any other**, and nothing else
111
113
  checks it — the review ran against a snapshot cut before those edits existed.
112
- Confirm `git diff origin/main...HEAD` actually contains what it reported
114
+ Confirm `git diff origin/main...<your dispatch pin>` actually contains what it reported
113
115
  applying. Two finishers in one run extended duty 2 this way unprompted, and
114
116
  one found five applies where the controller's hand-written list named three:
115
117
  a controller's list of what to verify is itself a claim.
@@ -117,8 +119,8 @@ a controller's list of what to verify is itself a claim.
117
119
  **That range is right for the positive check and wrong for a negative one.**
118
120
  It spans the implementer's commits too, so a constraint of the form *file X
119
121
  was not touched* has to be scoped to the apply commit. Measured on one PR:
120
- a controller wrote "neither document was touched" against
121
- `origin/main...HEAD` on a two-commit branch whose documents the IMPLEMENTER
122
+ a controller wrote "neither document was touched" against that range on a
123
+ two-commit branch whose documents the IMPLEMENTER
122
124
  had correctly edited — the PR's whole point — and a finisher reading that
123
125
  literally halts a correct PR. It caught the error instead, and said so; do
124
126
  not rely on that.
@@ -160,7 +162,8 @@ tracked files only, so without that step a suite whose dependencies are
160
162
  ignored cannot start. Mutate and run `<testCmd>` in that tree, then
161
163
  `git worktree remove --force <scratch>/pr<N>/finish-<your member name>`.
162
164
  **At your dispatch pin, never at the fetched branch tip** — duty 1 just
163
- proved the owned worktree sits at that pin, and `PR headRefOid` may carry
165
+ proved the owned worktree holds nothing your dispatch pin lacks, though its
166
+ `HEAD` may differ from it, and `PR headRefOid` may carry
164
167
  commits no reviewer read, the substitution the halt block's head-equality
165
168
  check rejects for the same reason. `<scratch>` is the absolute root your dispatch prompt names. The member name is in the path because
166
169
  the scratch root is shared with every sibling, so `<scratch>/pr<N>` alone
@@ -293,7 +296,7 @@ created, and `unrecorded` for one whose `filed` failed twice, which the
293
296
  controller's settle records — and, for anything it halted on, `cause` and
294
297
  `evidence`, below, never a bare "head moved". The
295
298
  cause is one word of the ledger's `halted:<cause>` vocabulary:
296
- `live-editor`, `rebase`, `past-pin`, `unreadable`, `missing` or `absent` as
299
+ `live-editor`, `rebase`, `past-pin`, `stray`, `unreadable`, `missing` or `absent` as
297
300
  duty 1's verdict names it, `human` for duty 3's exit 5, and `other` for every other halt — that
298
301
  verdict's own `other`, and a halt at duty 2, duty 3 or the instrument
299
302
  re-check. A duty 1 halt's `evidence` carries the verdict as
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.136.2",
3
+ "version": "3.136.3",
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": {
@@ -22,12 +22,12 @@
22
22
  // pin the pin, lowercased
23
23
  // head `git -C <worktree> rev-parse HEAD`, null when it was never read
24
24
  // cause null, or the word the ledger's `halted:<cause>` takes: live-editor,
25
- // rebase, past-pin, unreadable, missing, absent or other
25
+ // rebase, past-pin, stray, unreadable, missing, absent or other
26
26
  // evidence one entry per step that ran, each holding what that step read
27
27
  //
28
28
  // Exit vocabulary:
29
29
  //
30
- // 0 the worktree is clean at the pin: `cause` is null and nothing else is
30
+ // 0 the worktree holds nothing the pin lacks: `cause` is null and nothing else is
31
31
  // 1 a halt cause: `cause` names it and `evidence` holds what it was derived from
32
32
  // 2 it could not look - the invocation or a read failed, `evidence.error`
33
33
  // says which and the same line is on stderr. `cause` is null in that
@@ -70,41 +70,56 @@
70
70
  //
71
71
  // 4 Only when the head differs from the pin: `git -C <wt> reflog -n 20`, and the
72
72
  // newest entry is the move that put HEAD where it is.
73
- // - a `reset` or `rebase` entry: `rebase`. The branch replayed onto a new
74
- // base - its own commits on a new parent, content-identical only on a
75
- // conflict-free replay. Evidence: `replay`, the verdict of `git range-diff
76
- // --no-patch origin/main <pin> HEAD` run in the worktree; `rangeDiff`, that
77
- // output (or the error that stopped it); and `remote`, read as `past-pin`
78
- // reads it. `pure` only when every pinned commit pairs with an unchanged
79
- // one. A dropped, edited or added commit, or a stale `origin/main`, is
80
- // `changed`; a listing that cannot be read is `unknown`. `range-diff`
81
- // lists non-merge commits only, so a merge commit in either range is
82
- // `changed` as well: its own content - an evil merge, a conflict resolved
83
- // inside it - would otherwise leave no line. Not `git cherry`: it lists
84
- // only the head-side commits, reads a whitespace-only edit as unchanged,
85
- // and reads a conflict resolved to main's side as nothing at all.
86
- // `range-diff` pairs both sides of the replay, so each of those is an
87
- // unpaired line.
88
- // - a plain `commit` entry: `past-pin`. A member kept working after the
89
- // dispatch. Evidence: `git log -1 --format='%h %s'` and whether that
90
- // commit is pushed, unpushed or unknown, read from `git ls-remote origin
91
- // refs/heads/<branch>` - the branch being the row's, and the full ref
92
- // name so a branch named like the tail of another ref matches only
93
- // itself. Only a successful read settles pushed against unpushed: the
94
- // remote's value equal to HEAD is `pushed`, anything else from a read
95
- // that succeeded is `unpushed`, the commit existing only in that
96
- // worktree where no reviewer can reach it. A failed read - a non-zero
97
- // exit, a timeout, a detached HEAD with no branch to ask about - is
98
- // `unknown`, never `unpushed`, the same rule `release-ticket.sh`'s own
99
- // `ls-remote` states. The remote is asked rather than the PR object,
100
- // whose head lags a ref move.
73
+ // - a `reset` or `rebase` entry: `rebase`, even when `pin..HEAD` would test
74
+ // clean. The branch replayed onto a new base - its own commits on a new
75
+ // parent, content-identical only on a conflict-free replay. Evidence:
76
+ // `replay`, the verdict of `git range-diff --no-patch origin/main <pin>
77
+ // HEAD` run in the worktree; `rangeDiff`, that output (or the error that
78
+ // stopped it); and `remote`, whose `state` is `pushed` when the branch's
79
+ // remote ref equals HEAD and `differs` for any other value or an absent
80
+ // ref, `unknown` when the read failed (see the next entry). `pure` only
81
+ // when every pinned commit pairs with an unchanged one. A dropped, edited
82
+ // or added commit, or a stale `origin/main`, is `changed`; a listing that
83
+ // cannot be read is `unknown`. `range-diff` lists non-merge commits only,
84
+ // so a merge commit in either range is `changed` as well: its own content
85
+ // - an evil merge, a conflict resolved inside it - would otherwise leave
86
+ // no line. Not `git cherry`: it lists only the head-side commits, reads a
87
+ // whitespace-only edit as unchanged, and reads a conflict resolved to
88
+ // main's side as nothing at all. `range-diff` pairs both sides of the
89
+ // replay, so each of those is an unpaired line.
90
+ // - a `commit` entry, amend and merge commits included: a member kept
91
+ // working after the dispatch, or a remote rebase superseded this worktree.
92
+ // A range holds nothing unique when `git cherry <upstream> HEAD` prints no
93
+ // `+` line and `git rev-list --merges --count <upstream>..HEAD` is 0: `git
94
+ // cherry` never lists a merge commit, so a merge's own content is
95
+ // invisible to it. Evidence: `commit`, `git log -1 --format='%h %s'`.
96
+ // . `pin..HEAD` holds nothing unique: the worktree holds nothing the pin
97
+ // lacks and refreshing it loses nothing. `cause` null, exit 0, `head`
98
+ // the worktree's HEAD, `cherry` = `{listing, merges}` the read that
99
+ // settled it.
100
+ // . otherwise the branch is read, `git ls-remote origin
101
+ // refs/heads/<branch>` - the branch being the row's, and the full ref
102
+ // name so a branch named like the tail of another ref matches only
103
+ // itself - and `<remote sha>..HEAD` is tested the same way. Nothing
104
+ // unique there: `past-pin`, a member's commit past the pin that a
105
+ // reviewer can reach. Anything else: `stray`, a commit the branch's
106
+ // remote ref is not shown to carry - the ref lacks it or is absent,
107
+ // or the read could not tell. Evidence adds `cherry` and `remote` =
108
+ // `{ref, sha, carries, error?}`. `carries` is true or false, and null
109
+ // when it could not be told: a failed read, a timeout, a detached HEAD
110
+ // with no branch to ask about, or a remote SHA the object store lacks.
111
+ // An absent ref is `sha` null, `carries` false. The remote is asked
112
+ // rather than the PR object, whose head lags a ref move.
113
+ // Nothing is fetched: a pin the object store lacks fails the `git
114
+ // cherry` read, exit 2. The patch test ignores whitespace, so a local
115
+ // commit that differs from a pushed one only in whitespace reads clean.
101
116
  // - anything else, an empty reflog included: `other`. Evidence: both status
102
117
  // reads (the step-2 read and one after the reflog), the reflog line at
103
118
  // the move, and both SHAs. A cause nobody has named yet is still a cause
104
119
  // observed, and the report is what gets it named.
105
120
  //
106
121
  // Every cause halts, always - named or not. A rebase is not a fast-forward the
107
- // finisher gets to accept, a commit past the pin is not one either, and a cause
122
+ // finisher gets to accept, a commit the pin lacks is not one either, and a cause
108
123
  // that could not be named is the least settled of the lot.
109
124
  //
110
125
  // A usage refusal (a missing, unknown or malformed flag) is a one-line refusal
@@ -221,19 +236,38 @@ function git(step, args, { soft = false, timeout } = {}) {
221
236
  return { ok: true, out: r.stdout, error: null };
222
237
  }
223
238
 
224
- // The remote ref of `branch`, the row's, against `head`. Only a successful read
225
- // settles pushed against unpushed; a failed read, a timeout, or a detached HEAD
226
- // is `unknown`.
227
- function remoteState(branch, head) {
239
+ // The remote's value of `branch`, the row's, read once: `{ref, sha}` on a read
240
+ // that succeeded (`sha` null when the ref is absent), `{ref, error}` on a failed
241
+ // read, a timeout, or a detached HEAD, which has no branch to ask about.
242
+ function remoteRef(branch) {
228
243
  if (typeof branch !== "string" || branch === "" || branch === "DETACHED") {
229
- return { state: "unknown", error: "detached HEAD: no branch to ask the remote about" };
244
+ return { ref: null, sha: null, error: "detached HEAD: no branch to ask the remote about" };
230
245
  }
231
246
  const ref = `refs/heads/${branch}`;
232
247
  const r = git("ls-remote", ["ls-remote", "origin", ref], { soft: true, timeout: LS_REMOTE_TIMEOUT_MS });
233
- if (!r.ok) return { state: "unknown", ref, error: r.error };
248
+ if (!r.ok) return { ref, sha: null, error: r.error };
234
249
  const line = r.out.split("\n").find((l) => l.split("\t")[1] === ref);
235
- const sha = line === undefined ? null : line.split("\t")[0];
236
- return { state: sha === head ? "pushed" : "unpushed", ref, sha };
250
+ return { ref, sha: line === undefined ? null : line.split("\t")[0] };
251
+ }
252
+
253
+ // The remote ref of `branch` against `head`, for a replayed branch. Only a
254
+ // successful read settles pushed against differs; a failed read, a timeout, or
255
+ // a detached HEAD is `unknown`.
256
+ function remoteState(branch, head) {
257
+ const r = remoteRef(branch);
258
+ if (r.error !== undefined) return r.ref === null ? { state: "unknown", error: r.error } : { state: "unknown", ref: r.ref, error: r.error };
259
+ return { state: r.sha === head ? "pushed" : "differs", ref: r.ref, sha: r.sha };
260
+ }
261
+
262
+ // What `HEAD` holds that `upstream` lacks, by patch: `git cherry` prints `+` for
263
+ // a commit whose patch `upstream` does not carry, `-` for one it does. It never
264
+ // lists a merge commit, so a merge's own content is invisible to it and a merge
265
+ // in the range counts as unique. An `upstream` the object store lacks fails the
266
+ // read, exit 2.
267
+ function uniqueIn(upstream) {
268
+ const listing = git("cherry", ["cherry", upstream, "HEAD"]).out;
269
+ const merges = Number(git("merges", ["rev-list", "--merges", "--count", `${upstream}..HEAD`]).out.trim());
270
+ return { listing, merges, unique: merges > 0 || listing.split("\n").some((l) => l.startsWith("+")) };
237
271
  }
238
272
 
239
273
  // `git range-diff` prints one line per pairing, `<n>: <sha> <marker> <m>: <sha>
@@ -315,8 +349,21 @@ if (/^(reset|rebase)\b/.test(subject)) {
315
349
 
316
350
  if (/^commit\b/.test(subject)) {
317
351
  evidence.commit = git("log", ["log", "-1", "--format=%h %s"]).out.trim();
318
- evidence.remote = remoteState(row.branch, head);
319
- halt("past-pin");
352
+ const { unique, ...cherry } = uniqueIn(pin);
353
+ evidence.cherry = cherry;
354
+ // Nothing in pin..HEAD the pin lacks: a remote rebase superseded this
355
+ // worktree, or it sits behind the pin. Refreshing it loses nothing.
356
+ if (!unique) finish(0);
357
+ const remote = remoteRef(row.branch);
358
+ evidence.remote = { ref: remote.ref, sha: remote.sha, carries: null };
359
+ if (remote.error !== undefined) evidence.remote.error = remote.error;
360
+ else if (remote.sha === null) evidence.remote.carries = false;
361
+ else if (!git("remote-sha", ["cat-file", "-e", `${remote.sha}^{commit}`], { soft: true }).ok) {
362
+ evidence.remote.error = "the remote's SHA is not in the object store";
363
+ } else {
364
+ evidence.remote.carries = !uniqueIn(remote.sha).unique;
365
+ }
366
+ halt(evidence.remote.carries === true ? "past-pin" : "stray");
320
367
  }
321
368
 
322
369
  evidence.status.push(status());
@@ -58,10 +58,12 @@ const FAMILIES = {
58
58
  // so every family it matches has an entry here by construction.
59
59
  export const MEMBER_FAMILIES = Object.freeze(Object.keys(FAMILIES));
60
60
  // A finisher halt's causes: the finisher worked correctly and refused
61
- // to label, which `failed` (it crashed or gave up) does not say. `unreadable`,
61
+ // to label, which `failed` (it crashed or gave up) does not say. `stray` is a
62
+ // worktree commit past the pin that the branch's remote ref is not shown to
63
+ // carry: the ref lacks it or is absent, or the read could not tell. `unreadable`,
62
64
  // `missing` and `absent` are duty 1's audit-read halts. `human` is a Ticketless
63
65
  // PR whose diff is not inert: it merges only when the maintainer labels it.
64
- export const HALT_CAUSES = ["live-editor", "rebase", "past-pin", "unreadable", "missing", "absent", "other", "human"];
66
+ export const HALT_CAUSES = ["live-editor", "rebase", "past-pin", "stray", "unreadable", "missing", "absent", "other", "human"];
65
67
  const OUTCOME_PATTERNS = {
66
68
  "PR#M": /^PR#[1-9][0-9]*$/,
67
69
  "applied:<head>": /^applied:[0-9a-f]{7,40}$/i,
@@ -751,10 +751,11 @@ decides the rest — two resolve automatically, every other one escalates:
751
751
  | Cause | Resolution |
752
752
  |---|---|
753
753
  | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
754
- | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
754
+ | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
755
755
  | `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
756
+ | `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry` and `.remote`. Push or discard is yours, or the maintainer's if the evidence cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
756
757
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
757
- | `human` | **Escalate** — no retry. A Ticketless PR whose diff is not inert: the maintainer adds `ready-to-merge` at the pinned head, which the merge bot merges off the finisher's `ready-to-merge-head:` comment; a moved head is merged by hand. |
758
+ | `human` | **Escalate** — no retry. A Ticketless PR whose diff is not inert: the maintainer labels it (references/finisher.md). |
758
759
 
759
760
  ### Resolving a finisher that died
760
761
 
@@ -264,7 +264,8 @@ tracked files only, so without that step a suite whose dependencies are
264
264
  ignored cannot start. Mutate and run `<testCmd>` in that tree, then
265
265
  `git worktree remove --force <scratch>/pr<N>/finish-<your member name>`.
266
266
  **At your dispatch pin, never at the fetched branch tip** — duty 1 just
267
- proved the owned worktree sits at that pin, and `PR headRefOid` may carry
267
+ proved the owned worktree holds nothing your dispatch pin lacks, though its
268
+ `HEAD` may differ from it, and `PR headRefOid` may carry
268
269
  commits no reviewer read, the substitution the halt block's head-equality
269
270
  check rejects for the same reason. `<scratch>` is the absolute root your dispatch prompt names. The member name is in the path because
270
271
  the scratch root is shared with every sibling, so `<scratch>/pr<N>` alone
@@ -339,6 +340,36 @@ A re-review at the same head is a run of its own, so the earlier round's verdict
339
340
 
340
341
  ## A halt's cause comes from one script
341
342
 
343
+ A worktree whose head differs from the pin because a remote rebase superseded
344
+ it is not a halt. When the newest reflog move is a `commit`, duty 1 tests
345
+ whether `pin..HEAD` holds anything the pin lacks: `git cherry <pin> HEAD`
346
+ prints no `+` line and the range holds no merge commit. A worktree that holds
347
+ nothing the pin lacks exits 0, because refreshing it would lose nothing — the
348
+ commits it holds are already in the pin, rebased. Only a range that does hold
349
+ something is a halt: `past-pin` when the branch's remote ref carries it,
350
+ `stray` otherwise. The test is by patch, so it has two limits. `git
351
+ cherry` never lists a merge commit, so a merge in the range counts as unique
352
+ whatever its parents carry. And patch ids ignore whitespace, so a local commit
353
+ that differs from a pushed one only in whitespace reads clean; it stays behind
354
+ in the owned worktree and never reaches the merge. A newest move that is a
355
+ `reset` or a `rebase` stays `rebase`, even when `pin..HEAD` would test clean.
356
+
357
+ A `stray` halt is a commit the branch's remote ref is not shown to carry — the
358
+ ref lacks it or is absent, or the read could not tell — so nothing pushes it and
359
+ nothing re-reviews it. Read the patches off `evidence.cherry` (`+` for a patch
360
+ the pin lacks; `merges` counts merge commits, which the listing never shows)
361
+ and `evidence.remote` (`carries` false: the ref lacks it; `sha` null: the ref is
362
+ absent; `carries` null: the read could not be told, and `error` says why). A
363
+ pushed stray is a head no reviewer read: record its review by hand with
364
+ `ledger.mjs review <M>`, under the next runner letter as for a `past-pin`
365
+ re-review below, before any finisher is dispatched.
366
+
367
+ A `human` halt is a Ticketless PR whose diff is not inert: the maintainer adds
368
+ `ready-to-merge` at the pinned head, which the merge bot merges off the
369
+ finisher's `ready-to-merge-head:` comment; a moved head is merged by hand.
370
+
371
+ The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate.
372
+
342
373
  A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
343
374
  and the causes `finisher-audit.mjs` names are the ones seen so far, not a
344
375
  closed list; the finisher's agent body gives it the cause from one script