@feigi/fleet-ctl 3.137.0 → 3.137.2

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.
@@ -29,12 +29,12 @@ 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
30
  reflog. Exit 0, with `cause` null, is the only code that means the worktree
31
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.
32
+ by commits whose changes your pin already holds, by patch and by content.
33
+ Exit 1 means `cause` is non-null: you are halted, and `cause` is the word you
34
+ name — `live-editor`, `rebase`, `past-pin`, `stray`, `unreadable`, `missing`,
35
+ `absent` or `other`, and `other` is a cause too, not a gap. Exit 2 means the
36
+ script could not look: you are halted with cause `other`, with the line it
37
+ printed on stderr as the evidence.
38
38
 
39
39
  The pin is the SHA you were dispatched against, never `PR headRefOid`: a
40
40
  member that kept working and pushed after the pin matches the branch tip on a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.137.0",
3
+ "version": "3.137.2",
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": {
@@ -89,30 +89,58 @@
89
89
  // replay, so each of those is an unpaired line.
90
90
  // - a `commit` entry, amend and merge commits included: a member kept
91
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'`.
92
+ // A range holds nothing unique only when two tests both find nothing. By
93
+ // patch: `git cherry <upstream> HEAD` prints no `+` line and `git
94
+ // rev-list --merges --count <upstream>..HEAD` is 0 - `git cherry` never
95
+ // lists a merge commit, so a merge's own content is invisible to it, and
96
+ // a merge in the range counts as unique. By content: `git merge-tree
97
+ // --write-tree <upstream> HEAD` exits 0 and the tree id on the first line
98
+ // of its stdout is `<upstream>`'s own tree. Neither test is enough alone.
99
+ // A patch id ignores line numbers and whitespace, so by patch alone a
100
+ // commit that makes the pin's change at another place in the file, the
101
+ // same lines around it, or that differs from a pin commit by whitespace
102
+ // alone, reads clean though the pin lacks its content. By content alone,
103
+ // a commit that after a server-side rebase undoes a change the pin
104
+ // carries reads clean: merging it into the pin changes nothing, and only
105
+ // its `+` line catches it. Both tests compare changes, never commit
106
+ // messages, so a commit that differs from the pin's only in its message
107
+ // reads clean - unless the pin changes its lines again after it: merging
108
+ // the two then conflicts, a false halt the content test accepts.
109
+ // `merge-tree` is read by its exit code and that first line. Exit 0 with
110
+ // a tree id is clean or not by the comparison above. Exit 1 with a tree
111
+ // id there is a conflict, which is a finding, never a failure. Anything
112
+ // else is a failed read: exit 1 with no tree id (git also exits 1 on a
113
+ // revision it cannot merge), exit 128 (on unrelated histories, for one),
114
+ // a signal or a spawn error. A failed read is exit 2, `evidence.error`
115
+ // naming it, as a failed `git cherry` read is, at either call below.
116
+ // Evidence: `commit`, `git log -1 --format='%h %s'`; `cherry` =
117
+ // `{listing, merges}`; and `evidence.content` = `{tree, conflict, paths}`,
118
+ // on every verdict here, clean or not: the merge-tree read against the
119
+ // pin. `tree` is the merge's tree id, so `git diff <pin> <tree>` shows
120
+ // what the worktree would add, `conflict` is a boolean, and `paths` lists
121
+ // the files where `tree` differs from the pin's tree, none when it is
122
+ // clean.
96
123
  // . `pin..HEAD` holds nothing unique: the worktree holds nothing the pin
97
124
  // 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.
125
+ // the worktree's HEAD, `cherry` and `content` the reads that settled
126
+ // it.
100
127
  // . otherwise the branch is read, `git ls-remote origin
101
128
  // refs/heads/<branch>` - the branch being the row's, and the full ref
102
129
  // 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
130
+ // itself - and `<remote sha>..HEAD` is tested the same way, both
131
+ // tests against the remote's SHA and its own tree, not the pin's.
132
+ // Nothing unique there: `past-pin`, a member's commit past the pin
133
+ // that a reviewer can reach. Anything else: `stray`, a commit the
134
+ // branch's remote ref is not shown to carry - the ref lacks it or is
135
+ // absent, or the read could not tell. Evidence adds `remote` =
136
+ // `{ref, sha, carries, error?}`; the remote's own reads record
137
+ // `carries` alone. `carries` is true or false, and null when it could
138
+ // not be told: a failed read, a timeout, a detached HEAD with no
139
+ // branch to ask about, or a remote SHA the object store lacks. An
140
+ // absent ref is `sha` null, `carries` false. The remote is asked
112
141
  // rather than the PR object, whose head lags a ref move.
113
142
  // 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.
143
+ // cherry` read, exit 2.
116
144
  // - anything else, an empty reflog included: `other`. Evidence: both status
117
145
  // reads (the step-2 read and one after the reflog), the reflog line at
118
146
  // the move, and both SHAs. A cause nobody has named yet is still a cause
@@ -225,11 +253,12 @@ function run(cmd, args, options = {}) {
225
253
 
226
254
  // A git call inside the worktree. A call that could not run, was killed or
227
255
  // exited non-zero stops the audit at exit 2 unless the caller asked to read the
228
- // failure itself (`soft`).
256
+ // failure itself (`soft`), which then carries the exit status and the stdout
257
+ // the call left.
229
258
  function git(step, args, { soft = false, timeout } = {}) {
230
259
  const r = run("git", ["-C", realpath, ...args], timeout === undefined ? {} : { timeout });
231
260
  if (r.error || r.signal || r.status !== 0) {
232
- if (soft) return { ok: false, out: "", error: (r.error?.message ?? r.stderr ?? "").trim() || `exit ${r.status ?? r.signal}` };
261
+ if (soft) return { ok: false, status: r.status, out: r.stdout ?? "", error: (r.error?.message ?? r.stderr ?? "").trim() || `exit ${r.status ?? r.signal}` };
233
262
  const why = r.error?.message ?? (r.signal ? `killed by ${r.signal}` : (r.stderr ?? "").trim() || `exit ${r.status}`);
234
263
  fail(`${step}: git ${args.join(" ")} failed: ${why}`);
235
264
  }
@@ -259,15 +288,47 @@ function remoteState(branch, head) {
259
288
  return { state: r.sha === head ? "pushed" : "differs", ref: r.ref, sha: r.sha };
260
289
  }
261
290
 
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.
291
+ // The tree id `git merge-tree --write-tree` prints first.
292
+ const TREE_ID = /^[0-9a-f]{40}$/;
293
+
294
+ // What merging `HEAD` into `upstream` makes, read by `git merge-tree`'s exit
295
+ // code and the tree id on the first line of its stdout: exit 0 is a merge that
296
+ // went through, exit 1 with a tree id a conflict, which is a finding. Exit 1
297
+ // with no tree id is git refusing a revision it cannot merge, so the exit code
298
+ // alone cannot tell a conflict from it. That, exit 128 (unrelated histories
299
+ // among its causes), a signal and a spawn error are reads that failed: exit 2.
300
+ // The merge's tree and blob objects are written to the object store; no ref and
301
+ // no file of the worktree moves.
302
+ function mergeInto(upstream) {
303
+ const args = ["merge-tree", "--write-tree", upstream, "HEAD"];
304
+ const merge = git("merge-tree", args, { soft: true });
305
+ const tree = merge.out.split("\n")[0];
306
+ if (!TREE_ID.test(tree) || (!merge.ok && merge.status !== 1)) {
307
+ fail(`merge-tree: git ${args.join(" ")} failed: ${merge.error ?? "no tree id on stdout"}`);
308
+ }
309
+ return { tree, conflict: !merge.ok };
310
+ }
311
+
312
+ // The paths where `tree` differs from `upstream`'s own tree, none for a tree
313
+ // that is its own.
314
+ function changedPaths(upstream, tree) {
315
+ return git("paths", ["diff-tree", "-r", "--name-only", "-z", `${upstream}^{tree}`, tree]).out.split("\0").filter((p) => p !== "");
316
+ }
317
+
318
+ // What `HEAD` holds that `upstream` lacks, by two tests, either of which finds
319
+ // it. By patch: `git cherry` prints `+` for a commit whose patch `upstream` does
320
+ // not carry, `-` for one it does. It never lists a merge commit, so a merge's
321
+ // own content is invisible to it and a merge in the range counts as unique. By
322
+ // content: merging `HEAD` into `upstream` conflicts or makes a tree other than
323
+ // `upstream`'s own. An `upstream` the object store lacks fails the read, exit
324
+ // 2, and so does a merge that could not be read.
267
325
  function uniqueIn(upstream) {
268
326
  const listing = git("cherry", ["cherry", upstream, "HEAD"]).out;
269
327
  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("+")) };
328
+ const merged = mergeInto(upstream);
329
+ const content = { ...merged, paths: changedPaths(upstream, merged.tree) };
330
+ const unique = merges > 0 || listing.split("\n").some((l) => l.startsWith("+")) || content.conflict || content.paths.length > 0;
331
+ return { listing, merges, content, unique };
271
332
  }
272
333
 
273
334
  // `git range-diff` prints one line per pairing, `<n>: <sha> <marker> <m>: <sha>
@@ -349,10 +410,12 @@ if (/^(reset|rebase)\b/.test(subject)) {
349
410
 
350
411
  if (/^commit\b/.test(subject)) {
351
412
  evidence.commit = git("log", ["log", "-1", "--format=%h %s"]).out.trim();
352
- const { unique, ...cherry } = uniqueIn(pin);
413
+ const { unique, content, ...cherry } = uniqueIn(pin);
353
414
  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.
415
+ evidence.content = content;
416
+ // Nothing in pin..HEAD the pin lacks, by patch or by content: a remote rebase
417
+ // superseded this worktree, or it sits behind the pin. Refreshing it loses
418
+ // nothing.
356
419
  if (!unique) finish(0);
357
420
  const remote = remoteRef(row.branch);
358
421
  evidence.remote = { ref: remote.ref, sha: remote.sha, carries: null };
@@ -2080,7 +2080,7 @@ function checkReaders(where) {
2080
2080
  // field has the type that field has. Anything else was not what was asked
2081
2081
  // for, so it could not look.
2082
2082
  const isString = (v) => typeof v === "string";
2083
- const prFieldOk = { state: isString, labels: Array.isArray, closingIssuesReferences: Array.isArray, url: isString };
2083
+ const prFieldOk = { state: isString, labels: Array.isArray, closingIssuesReferences: Array.isArray, url: isString, headRefName: isString };
2084
2084
  const prView = (pr, fields) => {
2085
2085
  const what = `gh pr view ${pr} --json ${fields}`;
2086
2086
  const { r, v } = lookJson(what, ["pr", "view", String(pr), "--json", fields]);
@@ -2683,7 +2683,8 @@ function recordFiled(id, subject) {
2683
2683
  //
2684
2684
  // impl-N=PR#M verify-sha.sh <branch> <head> exits 0; PR M
2685
2685
  // reads OPEN and its closingIssuesReferences in its
2686
- // own repository name N;
2686
+ // own repository name N; its head branch is
2687
+ // implementer/N-impl-N;
2687
2688
  // the Check-step record (below) holds for <head>
2688
2689
  // impl-N=bailed bailCause is not null; the receipt names it.
2689
2690
  // report-schema.mjs already refuses a bail that
@@ -2860,9 +2861,15 @@ async function runSettleFromReport() {
2860
2861
  const sha = verifyShaOf(report.branch, report.head);
2861
2862
  check(`verify-sha.sh ${report.branch} ${report.head} exits 0`, sha.status === 0);
2862
2863
  recipeGate(report.head);
2863
- const { view: pr, numbers } = prViewClosing(report.pr, "state,closingIssuesReferences,url");
2864
+ const { view: pr, numbers } = prViewClosing(report.pr, "state,closingIssuesReferences,url,headRefName");
2864
2865
  check(`PR #${report.pr} reads OPEN`, pr.state === "OPEN");
2865
2866
  check(`PR #${report.pr} closes #${live.number}`, numbers.includes(live.number));
2867
+ // The claim's branch comes from the ticket: the Pull claims with member
2868
+ // impl-N, so its branch is implementer/N-impl-N, and close-out releases
2869
+ // impl-N. Never from the settling member's name or its report: a
2870
+ // replacement impl-N-x holds the same claim as impl-N.
2871
+ const claimBranch = `implementer/${live.number}-impl-${live.number}`;
2872
+ check(`PR #${report.pr}'s head is ${claimBranch} (GitHub: ${pr.headRefName})`, pr.headRefName === claimBranch);
2866
2873
  } else if (report.outcome === "blocked") {
2867
2874
  outcome = "blocked";
2868
2875
  } else {
@@ -113,6 +113,8 @@ Closes #N"
113
113
  gh pr edit --add-label <patch|minor|major> # own command, own exit status
114
114
  ```
115
115
 
116
+ Push and open the PR from the branch you claimed in step 5, whatever branch the ticket names: release and reap find a claim only through its own branch.
117
+
116
118
  `recipe-check.mjs` runs the Recipe's Check step, then `<test command>` — the
117
119
  Recipe's Test entrypoint, as you were handed it, which runs through the suite
118
120
  slot already — against the staged tree, and records both results beside your
@@ -753,7 +753,7 @@ decides the rest — two resolve automatically, every other one escalates:
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
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
+ | `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry`, `.content` and `.remote`. Push or discard is yours, or the maintainer's if they cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
757
757
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
758
758
  | `human` | **Escalate** — no retry. A Ticketless PR whose diff is not inert: the maintainer labels it (references/finisher.md). |
759
759
 
@@ -12,8 +12,11 @@ literal that path
12
12
  literal outcome
13
13
  ---
14
14
  Implement ticket <N>. You are ALREADY in worktree `<abs-path>`, whose PR branch is
15
- `<branch>`. Your scratch directory is `<scratch>/impl-<N>/`; outside the worktree,
16
- write nowhere else but your report file below.
15
+ `<branch>`: commit on it and open your PR from it, even when the ticket below names
16
+ another branch; the settle refuses a PR from any other branch. If the ticket names
17
+ one, say in the PR body that you used `<branch>`. Your scratch directory is
18
+ `<scratch>/impl-<N>/`; outside the worktree, write nowhere else but your report file
19
+ below.
17
20
 
18
21
  The ticket, pasted verbatim from the controller's own read — its title, the
19
22
  `## Agent Brief` comment or the issue body, whichever carries the brief, and its
@@ -342,27 +342,44 @@ A re-review at the same head is a run of its own, so the earlier round's verdict
342
342
 
343
343
  A worktree whose head differs from the pin because a remote rebase superseded
344
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
345
+ whether `pin..HEAD` holds anything the pin lacks, and a range holds nothing
346
+ only when both of two tests find nothing. By patch: `git cherry <pin> HEAD`
347
+ prints no `+` line and the range holds no merge commit. By content: `git
348
+ merge-tree --write-tree <pin> HEAD` exits 0 and makes the pin's own tree, so
349
+ merging the worktree into the pin changes nothing. A worktree that holds
347
350
  nothing the pin lacks exits 0, because refreshing it would lose nothing — the
348
351
  commits it holds are already in the pin, rebased. Only a range that does hold
349
352
  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.
353
+ `stray` otherwise. Neither test is enough alone. `git cherry` never lists a
354
+ merge commit, so a merge in the range counts as unique whatever its parents
355
+ carry, and a patch id ignores line numbers and whitespace, so by patch alone a
356
+ commit that makes the pin's change at another place in the file, or that
357
+ differs from a pin commit by whitespace alone, reads clean though the pin
358
+ lacks its content. By content alone, a commit that after a server-side rebase
359
+ undoes a change the pin carries reads clean, since merging it into the pin
360
+ changes nothing. A merge that conflicts is a range that holds something, not a
361
+ failure; a `merge-tree` that could not read at all, on unrelated histories for
362
+ one, is exit 2 with the failed read named in `evidence.error`. Both tests
363
+ compare changes, never commit messages, so a commit that differs from the
364
+ pin's only in its message reads clean — unless the pin changes its lines again
365
+ after it: merging the two then conflicts, a false halt the content test
366
+ accepts. A newest move that is a `reset` or a `rebase` stays `rebase`, even
367
+ when `pin..HEAD` would test clean.
356
368
 
357
369
  A `stray` halt is a commit the branch's remote ref is not shown to carry — the
358
370
  ref lacks it or is absent, or the read could not tell — so nothing pushes it and
359
371
  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)
372
+ the pin lacks; `merges` counts merge commits, which the listing never shows),
373
+ what the worktree would add to the pin off `evidence.content` (`tree` is the
374
+ merge's result, so `git diff <pin> <tree>` shows it; `conflict` true: the two
375
+ did not merge; `paths`: the files where `tree` differs from the pin's tree),
361
376
  and `evidence.remote` (`carries` false: the ref lacks it; `sha` null: the ref is
362
377
  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.
378
+ commit that undoes something the pin carries reads clean by content (`paths`
379
+ empty) and only its `+` line catches it, so a `+` beside empty `paths` is not
380
+ by itself safe to discard. A pushed stray is a head no reviewer read: record
381
+ its review by hand with `ledger.mjs review <M>`, under the next runner letter
382
+ as for a `past-pin` re-review below, before any finisher is dispatched.
366
383
 
367
384
  A `human` halt is a Ticketless PR whose diff is not inert: the maintainer adds
368
385
  `ready-to-merge` at the pinned head, which the merge bot merges off the