@feigi/fleet-ctl 3.143.1 → 3.143.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.
@@ -122,9 +122,9 @@ For each labeled PR, lowest first:
122
122
 
123
123
  This also repairs a branch carrying a merge commit — GitHub's rebase drops those too.
124
124
 
125
- **A worktree for this branch, if one exists, goes stale here** — the API rebased the remote, not your checkout. Expected, not a divergence. To prove it holds nothing unique, run `git cherry origin/<branch> HEAD` from the worktree **before the merge, never after**, and **not** `git cherry origin/main HEAD`: `main` never contained this PR's commits before the merge either, so it reads `+` for all of them regardless of staleness and proves nothing (measured). The window is the point: step 4 deletes the remote branch once the PR lands (`delete-merged-branch.sh`; a repo that auto-deletes head branches removes it at the merge itself), so `origin/<branch>` outlives the merge only until the next pruning fetch, and step 4's `prove-merge.sh` runs one seconds later (`grep -n 'git fetch --quiet origin' scripts/prove-merge.sh`, plain, which prunes under the `fetch.prune=true` this machine's global config sets — `git config --show-origin --get fetch.prune`). Past that fetch the probe fails on a missing ref, an error easy to misread as the divergence it was meant to rule out.
125
+ **A worktree for this branch, if one exists, goes stale here** — the API rebased the remote, not your checkout. Expected, not a divergence. To prove it holds nothing unique, read it against `origin/<branch>` from the worktree **before the merge, never after** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run unique-in-upstream.mjs --worktree <worktree> --upstream origin/<branch>` — and **not** against `origin/main`: `main` never contained this PR's commits before the merge either, so it reads unique for all of them regardless of staleness and proves nothing (measured). The window is the point: step 4 deletes the remote branch once the PR lands (`delete-merged-branch.sh`; a repo that auto-deletes head branches removes it at the merge itself), so `origin/<branch>` outlives the merge only until the next pruning fetch, and step 4's `prove-merge.sh` runs one seconds later (`grep -n 'git fetch --quiet origin' scripts/prove-merge.sh`, plain, which prunes under the `fetch.prune=true` this machine's global config sets — `git config --show-origin --get fetch.prune`). Past that fetch the probe fails on a missing ref, an error easy to misread as the divergence it was meant to rule out.
126
126
 
127
- **Neither result halts this path, and a `+` here is not the diverged-worktree STOP.** The clean answer is the absence of a `+`, not the absence of output: `git cherry` prints a line per commit in `origin/<branch>..HEAD`, `-` where the upstream already holds an equivalent patch and `+` where it does not, so it never goes silent merely because the rebase superseded everything. A worktree that has not fetched since the API rebase — the state this step leaves it in, since no local git command runs here — reads nothing; one that has fetched reads `-` for every rebased commit. Both are clean (measured 2026-08-29 in a scratch repo: a bare remote, a branch rebased onto an advanced `main` and force-pushed, and a clone left at the pre-rebase head — `git cherry origin/feat HEAD` printed nothing before that clone fetched and a `-` per rebased commit after, while an unpushed commit added on top raised a `+` in both). A `+` names a commit the worktree holds and that branch does not — say so alongside the merge, since it is the only signal that something local is unpushed, but it does not stop the merge, because nothing local reaches the remote from here: this step rebases through the API and pushes nothing, and step 4 merges the remote head, so an unpushed local commit is structurally unable to enter the merge. That STOP lives in the fallback (server-side rebase unavailable) and does not halt for the reason just ruled out here: neither path can carry a local commit to the remote, because neither pushes. What differs is what gets verified — the fallback rebases the worktree and verifies *that* head, so a commit only the worktree holds makes the verified tree something other than the reviewed head; here the worktree is only read, never rebased, so a `+` is a report, not a halt.
127
+ **Neither result halts this path, and `unique: true` here is not the diverged-worktree STOP.** The command prints one JSON line and exits 0 whichever way `unique` reads; the clean answer is `"unique": false`, not the absence of output, and the `listing` it carries, the raw `git cherry` output, is evidence and never the verdict. `unique` is true when any of three reads finds something: a `+` in that listing, a merge commit in `origin/<branch>..HEAD`, or a merge of HEAD into `origin/<branch>` that conflicts or makes a tree other than the branch's own. The `+` alone misses an unpushed commit that repeats a change the branch carries at another place in the file, or differs from it by whitespace alone, because a patch id ignores position and whitespace and reads it `-`; the tree comparison alone misses a commit that reverts a change the branch carries, which only the `+` catches. So either read finding something is `unique: true`. A worktree that has not fetched since the API rebase — the state this step leaves it in, since no local git command runs here — reads nothing in `listing`; one that has fetched reads `-` for every rebased commit. Both are `unique: false` (measured 2026-08-29 in a scratch repo: a bare remote, a branch rebased onto an advanced `main` and force-pushed, and a clone left at the pre-rebase head — `git cherry origin/feat HEAD` printed nothing before that clone fetched and a `-` per rebased commit after, while an unpushed commit added on top raised a `+` in both). The exception is a fetched worktree whose branch carried a merge commit: the rebase drops the merge, so the worktree still holds a merge the branch lacks and reads `unique: true` though it holds no work of its own — `merges` above 0, `content.paths` empty, every `listing` line `-`. `unique: true` names something the worktree holds and that branch does not — say so alongside the merge, since it is the only signal that something local is unpushed, but it does not stop the merge, because nothing local reaches the remote from here: this step rebases through the API and pushes nothing, and step 4 merges the remote head, so an unpushed local commit is structurally unable to enter the merge. Exit 2 is no verdict — the read failed and the error is named — so report the worktree as unread, never as clean; it halts nothing here either. That STOP lives in the fallback (server-side rebase unavailable) and does not halt for the reason just ruled out here: neither path can carry a local commit to the remote, because neither pushes. What differs is what gets verified — the fallback rebases the worktree and verifies *that* head, so a commit only the worktree holds makes the verified tree something other than the reviewed head; here the worktree is only read, never rebased, so `unique: true` is a report, not a halt.
128
128
 
129
129
  **Two, and only two, reasons this can't be used:** a real conflict, or `allow_update_branch` off on the repo. Both are whole-branch failures — GitHub's rebase replays every commit or none, no partial credit. Either → the fallback below, not a retry.
130
130
 
@@ -144,7 +144,7 @@ For each labeled PR, lowest first:
144
144
 
145
145
  **Unequal → `git fetch origin` and read the ref once more, then decide on that second reading. Bounded at one re-read, never a third.** Neither operand is a cached value, so a stable second reading cannot flip the verdict; what the re-read is for is the ref MOVING while you verify, which is live here because one way into this fallback is a step-1 poll whose cap ran out with the ref unmoved, and that call is async — it can land a moment after you gave up on it. The two readings differ → the head is not settled and the audit behind the label verified a tree that is already gone, so **refuse: report `head-moved-after-label-#<pr>` and stop**, label untouched, the same verdict and the same remedy — a fresh finisher against the new head — the gate above reaches for a head that moved after the audit. Do not read a third time; that is the unbounded wait step 1 had to be written out of. The two readings agree → the mismatch is real and belongs to one of the two arms below. **`Equal` is not among the outcomes a surviving mismatch can reach**: a worktree that is not on the branch ref never passes this check, whatever the PR object says.
146
146
 
147
- **Ahead or behind is `git cherry origin/<branch> HEAD` from the worktree, run after that fetch — not the sha compare.** A rebase orphans the pre-rebase head, so the ref does not carry the worktree's commits BY SHA even where it carries every patch in them; read the mismatch as "commits the ref lacks" and a worktree holding no work of its own answers yes and takes the STOP. Patch equivalence is the question, and `git cherry` is the instrument this step already uses for it: a `+` → ahead; no `+` → behind, a worktree the rebase superseded included.
147
+ **Ahead or behind is the `unique` verdict of `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run unique-in-upstream.mjs --worktree <worktree> --upstream origin/<branch>`, run after that fetch — not the sha compare.** A rebase orphans the pre-rebase head, so the ref does not carry the worktree's commits BY SHA even where it carries every patch in them; read the mismatch as "commits the ref lacks" and a worktree holding no work of its own answers yes and takes the STOP. Patch equivalence is the question, and the verdict is not a raw `git cherry` line: a patch id ignores position and whitespace, so an unpushed commit that repeats a change the branch carries elsewhere in the file, or differs from it by whitespace alone, reads `-` there and the STOP would not fire. The script reads `unique` true when `git cherry` shows a `+`, `origin/<branch>..HEAD` holds a merge commit, or merging HEAD into `origin/<branch>` conflicts or makes a tree other than the branch's own: `"unique": true` → ahead; `"unique": false` → behind, a worktree the rebase superseded included — unless its branch carried a merge commit the rebase dropped. The worktree still holds that merge, so it reads `"unique": true` with `merges` above 0, `content.paths` empty and every `listing` line `-`, and takes the STOP as ahead though it holds no work of its own; say in the report that the merge is all it holds. Exit 2 is no verdict — the read failed and the error is named — and is not behind: take the STOP, report `worktree-diverged-#<pr>` and quote the error.
148
148
 
149
149
  - **Equal** → proceed.
150
150
  - **Worktree ahead** → STOP, report `worktree-diverged-#<pr>`. A fix-agent that committed locally but never pushed, or was aborted mid-fix, leaves an unpushed, unreviewed commit that a clean-tree audit passes. Nothing on this path pushes, so that commit cannot enter the merge — what it corrupts is the verification: rebase on top of it and both the `origin/main...HEAD` diff and the suite run against a tree that is not the reviewed head, while any merge takes the remote head, so the content-equivalence this path depends on is gone and a green says nothing about what would land. It fails silently, which is why this halts rather than proceeding on the green. The reviewed head lives on the remote, not here; hand the choice back with the PR.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.143.1",
3
+ "version": "3.143.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,6 +89,8 @@
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
+ // The two tests are `uniqueIn()` of unique-in-upstream.mjs, which the merge
93
+ // bot runs as a command; what follows is what it does.
92
94
  // A range holds nothing unique only when two tests both find nothing. By
93
95
  // patch: `git cherry <upstream> HEAD` prints no `+` line and `git
94
96
  // rev-list --merges --count <upstream>..HEAD` is 0 - `git cherry` never
@@ -159,6 +161,7 @@ import { basename, dirname, join, resolve } from "node:path";
159
161
  import { fileURLToPath } from "node:url";
160
162
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
161
163
  import { gitEnv } from "./git-env.mjs";
164
+ import { UniqueReadError, uniqueIn as uniqueInWorktree } from "./unique-in-upstream.mjs";
162
165
 
163
166
  const NAME = "finisher-audit";
164
167
  const die = makeDie(NAME);
@@ -253,12 +256,11 @@ function run(cmd, args, options = {}) {
253
256
 
254
257
  // A git call inside the worktree. A call that could not run, was killed or
255
258
  // exited non-zero stops the audit at exit 2 unless the caller asked to read the
256
- // failure itself (`soft`), which then carries the exit status and the stdout
257
- // the call left.
259
+ // failure itself (`soft`), which then carries the error.
258
260
  function git(step, args, { soft = false, timeout } = {}) {
259
261
  const r = run("git", ["-C", realpath, ...args], timeout === undefined ? {} : { timeout });
260
262
  if (r.error || r.signal || r.status !== 0) {
261
- if (soft) return { ok: false, status: r.status, out: r.stdout ?? "", error: (r.error?.message ?? r.stderr ?? "").trim() || `exit ${r.status ?? r.signal}` };
263
+ if (soft) return { ok: false, error: (r.error?.message ?? r.stderr ?? "").trim() || `exit ${r.status ?? r.signal}` };
262
264
  const why = r.error?.message ?? (r.signal ? `killed by ${r.signal}` : (r.stderr ?? "").trim() || `exit ${r.status}`);
263
265
  fail(`${step}: git ${args.join(" ")} failed: ${why}`);
264
266
  }
@@ -288,47 +290,16 @@ function remoteState(branch, head) {
288
290
  return { state: r.sha === head ? "pushed" : "differs", ref: r.ref, sha: r.sha };
289
291
  }
290
292
 
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.
293
+ // What `HEAD` holds that `upstream` lacks, by the two tests unique-in-upstream.mjs
294
+ // owns. A read that could not be made stops the audit at exit 2, as a failed git
295
+ // call anywhere above does.
325
296
  function uniqueIn(upstream) {
326
- const listing = git("cherry", ["cherry", upstream, "HEAD"]).out;
327
- const merges = Number(git("merges", ["rev-list", "--merges", "--count", `${upstream}..HEAD`]).out.trim());
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 };
297
+ try {
298
+ return uniqueInWorktree(realpath, upstream, { env: GIT_ENV });
299
+ } catch (e) {
300
+ if (e instanceof UniqueReadError) fail(e.message);
301
+ throw e;
302
+ }
332
303
  }
333
304
 
334
305
  // `git range-diff` prints one line per pairing, `<n>: <sha> <marker> <m>: <sha>
@@ -0,0 +1,131 @@
1
+ #!/usr/bin/env node
2
+ // What a worktree's HEAD holds that an upstream lacks, as one verdict, so every
3
+ // reader that asks "is anything here unpushed or unreviewed?" asks it by the
4
+ // same two tests and none of them reads a raw `git cherry` line instead.
5
+ // `finisher-audit.mjs` imports `uniqueIn()`; the merge bot runs the command:
6
+ //
7
+ // unique-in-upstream.mjs --worktree <path> --upstream <ref>
8
+ //
9
+ // `--worktree` is the checkout read, `--upstream` the revision HEAD is compared
10
+ // with: a branch's remote-tracking ref, or a commit. Reached through the
11
+ // Resolver: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run unique-in-upstream.mjs ...`.
12
+ // Nothing is fetched: an `--upstream` the object store lacks fails the read.
13
+ //
14
+ // Stdout is one JSON line, the verdict:
15
+ //
16
+ // {worktree, upstream, listing, merges, content: {tree, conflict, paths}, unique}
17
+ //
18
+ // listing `git cherry <upstream> HEAD`, verbatim
19
+ // merges `git rev-list --merges --count <upstream>..HEAD`
20
+ // content the merge-tree read: `tree` is the tree id merging HEAD into
21
+ // `<upstream>` makes, `conflict` a boolean, and `paths` the files where
22
+ // `tree` differs from `<upstream>`'s own tree, none when it is clean
23
+ // unique true when HEAD holds something `<upstream>` lacks
24
+ //
25
+ // What HEAD holds that `upstream` lacks, by two tests, either of which finds
26
+ // it. By patch: `git cherry` prints `+` for a commit whose patch `upstream` does
27
+ // not carry, `-` for one it does. It never lists a merge commit, so a merge's
28
+ // own content is invisible to it, and a merge in the range counts as unique. By
29
+ // content: merging HEAD into `upstream` conflicts or makes a tree other than
30
+ // `upstream`'s own. Neither test is enough alone. A patch id ignores line
31
+ // numbers and whitespace, so by patch alone a commit that makes `upstream`'s
32
+ // change at another place in the file, the same lines around it, or that
33
+ // differs from one of its commits by whitespace alone, reads clean though
34
+ // `upstream` lacks its content. By content alone, a commit that undoes a change
35
+ // `upstream` carries reads clean: merging it in changes nothing, and only its
36
+ // `+` line catches it.
37
+ //
38
+ // `git merge-tree --write-tree` is read by its exit code and the tree id on the
39
+ // first line of its stdout. Exit 0 with a tree id is a merge that went through,
40
+ // clean or not by the comparison above. Exit 1 with a tree id is a conflict,
41
+ // which is a finding, never a failure. Anything else is a failed read: exit 1
42
+ // with no tree id (git also exits 1 on a revision it cannot merge), exit 128
43
+ // (on unrelated histories, for one), a signal or a spawn error. The merge's
44
+ // tree and blob objects are written to the object store; no ref and no file of
45
+ // the worktree moves.
46
+ //
47
+ // Exit vocabulary:
48
+ //
49
+ // 0 a verdict: read `unique`, which is true or false. Never an exit code for
50
+ // it, so a caller that only reads the exit status cannot take "something
51
+ // unique" for a failure of the read.
52
+ // 2 no verdict: a usage refusal, a read that failed, or a verdict that could
53
+ // not be written to stdout. A failed read prints `{worktree, upstream,
54
+ // error}` on stdout, `error` naming the call, and the message on stderr.
55
+ // It is never a clean answer.
56
+
57
+ import { spawnSync } from "node:child_process";
58
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
59
+ import { gitEnv } from "./git-env.mjs";
60
+ import { isCLI } from "./is-cli.mjs";
61
+
62
+ const NAME = "unique-in-upstream";
63
+ // One git child's stdout: far past spawnSync's 1 MiB default for a merge that
64
+ // changes many paths.
65
+ const BUFFER = 256 * 1024 * 1024;
66
+ // The tree id `git merge-tree --write-tree` prints first.
67
+ const TREE_ID = /^[0-9a-f]{40}$/;
68
+
69
+ // A read that could not be made: a call that did not run, was killed, or
70
+ // exited with a status that is not an answer. The message names the step and
71
+ // the git call, and is what a caller reports.
72
+ export class UniqueReadError extends Error {}
73
+
74
+ // What HEAD of `worktree` holds that `upstream` lacks: `{listing, merges,
75
+ // content, unique}`. Throws `UniqueReadError` for any read that could not be
76
+ // made - an `upstream` the object store lacks, a merge that could not be read -
77
+ // so a failed read is never a clean verdict. `env` is the environment of every
78
+ // git child: the ambient one with GIT_DIR and GIT_WORK_TREE scrubbed when
79
+ // omitted.
80
+ export function uniqueIn(worktree, upstream, { env = gitEnv() } = {}) {
81
+ // A git call inside the worktree. A call that could not run, was killed or
82
+ // exited non-zero throws, unless the caller asked to read the failure itself
83
+ // (`soft`), which then carries the exit status and the stdout the call left.
84
+ const git = (step, args, { soft = false } = {}) => {
85
+ const r = spawnSync("git", ["-C", worktree, ...args], { encoding: "utf8", env, maxBuffer: BUFFER });
86
+ if (r.error || r.signal || r.status !== 0) {
87
+ if (soft) return { ok: false, status: r.status, out: r.stdout ?? "", error: (r.error?.message ?? r.stderr ?? "").trim() || `exit ${r.status ?? r.signal}` };
88
+ const why = r.error?.message ?? (r.signal ? `killed by ${r.signal}` : (r.stderr ?? "").trim() || `exit ${r.status}`);
89
+ throw new UniqueReadError(`${step}: git ${args.join(" ")} failed: ${why}`);
90
+ }
91
+ return { ok: true, out: r.stdout, error: null };
92
+ };
93
+
94
+ const listing = git("cherry", ["cherry", upstream, "HEAD"]).out;
95
+ const merges = Number(git("merges", ["rev-list", "--merges", "--count", `${upstream}..HEAD`]).out.trim());
96
+
97
+ // Exit 1 with no tree id is git refusing a revision it cannot merge, so the
98
+ // exit code alone cannot tell a conflict from it.
99
+ const mergeArgs = ["merge-tree", "--write-tree", upstream, "HEAD"];
100
+ const merge = git("merge-tree", mergeArgs, { soft: true });
101
+ const tree = merge.out.split("\n")[0];
102
+ if (!TREE_ID.test(tree) || (!merge.ok && merge.status !== 1)) {
103
+ throw new UniqueReadError(`merge-tree: git ${mergeArgs.join(" ")} failed: ${merge.error ?? "no tree id on stdout"}`);
104
+ }
105
+ const paths = git("paths", ["diff-tree", "-r", "--name-only", "-z", `${upstream}^{tree}`, tree]).out.split("\0").filter((p) => p !== "");
106
+ const unique = merges > 0 || listing.split("\n").some((l) => l.startsWith("+")) || !merge.ok || paths.length > 0;
107
+ return { listing, merges, content: { tree, conflict: !merge.ok, paths }, unique };
108
+ }
109
+
110
+ function main() {
111
+ const die = makeDie(NAME);
112
+ const { arg, sweep, stray } = defineFlags(die, { flags: { worktree: "value", upstream: "value" } });
113
+ // The sweep runs before the required-flag check so a misspelled flag is named
114
+ // as that, not buried under a missing-flag usage line.
115
+ sweep();
116
+ stray();
117
+ const worktree = arg("worktree");
118
+ const upstream = arg("upstream");
119
+ if (worktree === null || upstream === null) die("usage: unique-in-upstream.mjs --worktree <path> --upstream <ref>");
120
+ try {
121
+ const verdict = uniqueIn(worktree, upstream);
122
+ if (!writeAll(1, `${JSON.stringify({ worktree, upstream, ...verdict })}\n`)) die("the verdict could not be written to stdout");
123
+ process.exit(0);
124
+ } catch (e) {
125
+ if (!(e instanceof UniqueReadError)) throw e;
126
+ writeAll(1, `${JSON.stringify({ worktree, upstream, error: e.message })}\n`);
127
+ die(e.message);
128
+ }
129
+ }
130
+
131
+ if (isCLI(import.meta.url)) main();