@feigi/fleet-ctl 3.23.8 → 3.23.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.23.8",
+  "version": "3.23.10",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/reap-cherry-check-prose.test.mjs

@@ -0,0 +1,80 @@
+// reap.sh's branch sweep runs more checks than `git cherry` before its
+// `git update-ref --no-deref -d`: the worktree registry and listing checks,
+// the dirty check, the `worktree remove` refusal and the `wt_holding` re-read
+// can each keep the branch. The cherry check is the only one of them that
+// asks whether the tip is merged, so a comment saying the delete is
+// "authorized by this check and by nothing else" is false as written. The
+// component doc said reap deletes with `-D`; it deletes with `update-ref -d`.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { bullet, paragraph, phrase, runAbove, stripHashGutter } from "./prose-pin.mjs";
+
+const REPO = join(import.meta.dirname, "..", "..");
+const SCRIPT = readFileSync(join(REPO, "plugin", "scripts", "reap.sh"), "utf8");
+const DOC = readFileSync(join(REPO, "docs", "components", "reaping-and-liveness.md"), "utf8");
+
+// The comment block above the branch sweep's cherry probe, and the one above
+// its cherry scan: the two blocks that justify why the cherry check fails
+// closed.
+const probeComment = () =>
+  stripHashGutter(runAbove(SCRIPT, 'if ! cherry=$(git cherry "$base_rev" "$tip"', "reap.sh cherry probe", "#"));
+const scanComment = () =>
+  stripHashGutter(
+    runAbove(SCRIPT, `if ! grep_probe "$cherry" '^+'; then keep "$b"`, "reap.sh cherry scan", "#"),
+  );
+
+const NOTHING_ELSE = phrase("authorized by this check and by nothing else");
+
+for (const [name, comment] of [
+  ["cherry-probe", probeComment],
+  ["cherry-scan", scanComment],
+]) {
+  test(`reap.sh: the ${name} comment does not call the cherry check the delete's sole authorizer`, () => {
+    assert.doesNotMatch(
+      comment(),
+      NOTHING_ELSE,
+      `reap.sh's ${name} comment says the delete is authorized by the cherry check and by nothing else — the worktree checks and \`wt_holding\` can stop the delete too`,
+    );
+  });
+}
+
+test("reap.sh: the cherry-probe comment does not quote the retired \"By nothing else\" sentence", () => {
+  assert.doesNotMatch(
+    probeComment(),
+    phrase('"By nothing else" bounds'),
+    "reap.sh's cherry-probe comment says \"By nothing else\" bounds what ELSE authorizes the delete — the worktree checks and `wt_holding` can stop the delete too, and the sentence restates the sole-authorizer claim",
+  );
+});
+
+test("reap.sh: the cherry comments still say why an unanswerable probe must keep", () => {
+  // Input the pins above must ACCEPT: the fail-closed argument the old
+  // sentence carried survives, restated as what makes the cherry check
+  // unique — it is the only check that asks whether the tip is merged.
+  assert.match(probeComment(), phrase("this is the only one that asks whether `$tip` is merged"));
+  assert.match(probeComment(), phrase("never a `$tip` that is unmerged — so an unanswerable probe must KEEP"));
+  assert.match(scanComment(), phrase("no check between here and the delete below asks whether the branch is merged"));
+});
+
+const reapStep = () =>
+  bullet(DOC, "1. **Reap after every merge pass**", "2. **Release a claim", "reaping-and-liveness.md reap step");
+// The doc's last list item, so the blank-line bound is the end of the file.
+const reapAndRelease = () =>
+  paragraph(
+    DOC,
+    "- **Reap and release are two different scripts on purpose.**",
+    "reaping-and-liveness.md reap-and-release choice",
+  );
+
+test("reaping-and-liveness.md: the reap step names the delete as a compare-and-swap `update-ref -d`, not `-D`", () => {
+  const step = reapStep();
+  assert.match(step, phrase("compare-and-swap `git update-ref -d`"));
+  assert.doesNotMatch(step, /`-D`/, "reaping-and-liveness.md's reap step says the delete is `-D` — reap.sh deletes with `git update-ref -d`");
+});
+
+test("reaping-and-liveness.md: the reap-and-release choice names reap's delete as `update-ref -d`, not `-D`", () => {
+  const choice = reapAndRelease();
+  assert.match(choice, phrase("Reap authorizes a destructive `git update-ref -d`"));
+  assert.doesNotMatch(choice, /`-D`/, "reaping-and-liveness.md says reap authorizes a `-D` — reap.sh deletes with `git update-ref -d`");
+});

package/scripts/reap.sh

@@ -938,23 +938,26 @@ for b in $gone_branches; do
   # enough) prints nothing, grep sees empty input and exits 1 — the identical
   # verdict a genuinely clean cherry produces, so "merged" is indistinguishable
   # from "the probe could not answer". An unmerged branch is never the ambiguous
-  # one: its `+` line makes grep exit 0 and always keeps. The delete is
-  # authorized by this check and by nothing else — its compare-and-swap refuses
-  # a ref that moved off `$tip`, never a `$tip` that is unmerged — so an
-  # unanswerable probe must KEEP, the same fail-closed shape the worktree
-  # `status` check below already uses.
+  # one: its `+` line makes grep exit 0 and always keeps. Of the checks that
+  # must pass before the delete, this is the only one that asks whether `$tip`
+  # is merged — the worktree checks below and the `worktree remove` refusal
+  # can each keep the branch, but none of them looks at its commits, and the
+  # compare-and-swap refuses a ref that moved off `$tip`, never a `$tip` that
+  # is unmerged — so an unanswerable probe must KEEP, the same fail-closed
+  # shape the worktree `status` check below already uses.
   # `refs/heads/$b`, never a bare `$b`, where the tip is read above. Restoring
   # the bare name makes a branch that shares its name with a tag ambiguous AS A
   # REV again, and git resolves an ambiguous one by preferring refs/tags/ over
   # refs/heads/ (measured, git 2.50.1 Apple Git-155). This probe would then
   # answer about the TAG's commit while the delete below removes the BRANCH —
   # and a tag sitting on a merged commit reports clean for a branch whose
-  # commits exist nowhere else. The delete is authorized by this check and by
-  # nothing else, so that reads straight through to destroying them: measured
-  # on a fixture, the enumeration fix alone turned a branch this script
-  # currently KEEPS into `REAPED`, at exit 0, with an empty kept[]. Qualifying
-  # changes nothing for an ordinary branch — both spellings name the same
-  # commit — and it is the same key the worktree lookup below already builds.
+  # commits exist nowhere else. No other check before the delete asks whether
+  # those commits are merged, so that reads straight through to destroying
+  # them: measured on a fixture, the enumeration fix alone turned a branch
+  # this script currently KEEPS into `REAPED`, at exit 0, with an empty
+  # kept[]. Qualifying changes nothing for an ordinary branch — both spellings
+  # name the same commit — and it is the same key the worktree lookup below
+  # already builds.
   #
   # `$base_rev` is the other side of the same rule, and it was missing until
   # #924: `$base` reached this `git cherry` exactly as BASE_REF spelled it, so a
@@ -963,10 +966,10 @@ for b in $gone_branches; do
   # deleted the BRANCH — measured, an unmerged [gone] branch whose commit
   # existed nowhere else REAPED at exit 0 with an empty kept[]. The
   # qualification is built at the top of the file, where its own comment
-  # records why the accept-list beside it is what makes prefixing sound. "By
-  # nothing else" bounds what ELSE authorizes the delete, not whether this
-  # check itself can be wrong — which is why BOTH revs it consumes are
-  # qualified. #634
+  # records why the accept-list beside it is what makes prefixing sound. Being
+  # the only merge check bounds what ELSE could catch an unmerged branch, not
+  # whether this check itself can be wrong — which is why BOTH revs it
+  # consumes are qualified. #634
   if ! cherry=$(git cherry "$base_rev" "$tip" 2>&1); then
     keep "$b" "cherry probe failed — cannot tell if merged: $(printf '%s' "$cherry" | tr '\n' ' ')"
     continue
@@ -981,9 +984,9 @@ for b in $gone_branches; do
   # What "grep's is the only status left to take" missed, and what this shape
   # exists for: taking it is not the same as READING it. grep answers three
   # ways, and until #1419 the `if` had two arms — an rc 2 scan that never
-  # examined `$cherry` fell into the merged arm, and the delete below is
-  # authorized by this check and by nothing else. So the deletion went ahead on
-  # a merge status no tool had established. `grep_probe` splits the two
+  # examined `$cherry` fell into the merged arm, and no check between here and
+  # the delete below asks whether the branch is merged. So the deletion went
+  # ahead on a merge status no tool had established. `grep_probe` splits the two
   # questions; the answers are ruled on here, in the order that makes the
   # unanswerable case fail CLOSED like every other could-not-check in this
   # file: scan first, verdict second.

package/scripts/recipe-prove.mjs

@@ -148,11 +148,25 @@ function parseArgs(argv) {
 // proof that did not hold. Only a spawn that produced no process counts:
 // spawnSync also sets `error` for a git that ran and was killed — ENOBUFS,
 // when its output outgrows the default maxBuffer — and that is a failed git
-// command like any other, never a git that could not be started.
+// command, never a git that could not be started.
+//
+// A git killed by a signal (that buffer kill, an OOM kill, a timeout wrapper)
+// is still a failed command, never a throw: each caller maps a failed git to
+// its own refusal. But it has no exit status and mostly no stderr, so `err`
+// names the kill, after whatever git did write — a caller quoting `err` would
+// otherwise quote an empty reason.
 function git(args, cwd) {
   const r = spawnSync("git", args, { cwd, env: ENV, encoding: "utf8" });
   if (r.error && !r.pid) throw cannot(`could not start git: ${r.error.message}`);
-  return { ok: r.status === 0, out: (r.stdout ?? "").replace(/\n$/, ""), err: (r.stderr ?? "").trim() };
+  const err = (r.stderr ?? "").trim();
+  const killed = r.signal && `git was killed by ${r.signal}${killCause(r.error)}`;
+  return { ok: r.status === 0, out: (r.stdout ?? "").replace(/\n$/, ""), err: [err, killed].filter(Boolean).join("; ") };
+}
+
+function killCause(error) {
+  if (!error) return "";
+  if (error.code === "ENOBUFS") return " (ENOBUFS: its output outgrew the spawn buffer)";
+  return ` (${error.code ?? error.message})`;
 }
 
 // Run a Recipe command through `sh -c` from the worktree root, its output to
@@ -338,12 +352,13 @@ function removeLogs(logs) {
 
 function main(argv) {
   const o = parseArgs(argv);
-  if (!git(["rev-parse", "--git-dir"], o.repo).ok) throw cannot(`${o.repo} is not a git repository`);
+  const gitDir = git(["rev-parse", "--git-dir"], o.repo);
+  if (!gitDir.ok) throw cannot(`${o.repo} is not a git repository: ${gitDir.err}`);
   const common = git(["rev-parse", "--path-format=absolute", "--git-common-dir"], o.repo);
   const workspace = common.ok ? workspaceDirFromGitCommonDir(common.out, o.repo) : null;
   if (!workspace) throw cannot(`cannot resolve the common git dir of ${o.repo}: ${common.err}`);
   const sha = git(["rev-parse", "--verify", "origin/main^{commit}"], o.repo);
-  if (!sha.ok) throw cannot("origin/main does not resolve to a commit — fetch it; the proof runs against it");
+  if (!sha.ok) throw cannot(`origin/main does not resolve to a commit (${sha.err}) — fetch it; the proof runs against it`);
 
   const logs = mkdtempSync(join(tmpdir(), `${NAME}-`));
   const cache = join(workspace, ".fleet", "recipe.json");

package/scripts/recipe-prove.test.mjs

@@ -506,6 +506,112 @@ test("a git whose output outgrows the spawn buffer is a failed command, not a gi
   assert.doesNotMatch(r.err, /could not start git/);
 });
 
+// A `git` first on PATH that runs `act` when its arguments match the sh `case`
+// pattern `when`, and otherwise execs the real one.
+function fakeGit(when, act) {
+  const realGit = execFileSync("sh", ["-c", "command -v git"], { encoding: "utf8" }).trim();
+  const bin = tempDir("recipe-prove-path-");
+  writeExecStub(join(bin, "git"), `#!/bin/sh\ncase "$*" in ${when}) ${act} ;; esac\nexec '${realGit}' "$@"\n`);
+  return `${bin}:${BIN}:${process.env.PATH}`;
+}
+
+const COUNT_PROOF = ["--install", "true", "--test", "echo 'tests 1'", "--count-line", "tests 1", "--test-count", "1"];
+
+// A git that ran and was killed has no exit status and, mostly, no stderr: its
+// failure must name the kill, or every caller quoting git's reason quotes an
+// empty one. Each caller keeps its own refusal class — NOT PROVEN (1) inside
+// the proof, no verdict (2) for the probes that come before it.
+const KILLED_GIT = [
+  {
+    name: "a git killed by SIGKILL reading the tree state",
+    when: "status*", act: "kill -9 $$",
+    status: 1, reason: /NOT PROVEN — could not read the tree state in the throwaway worktree: git was killed by SIGKILL; install output: /,
+  },
+  {
+    name: "a git killed by SIGTERM reading the tree state",
+    when: "status*", act: "kill -TERM $$",
+    status: 1, reason: /NOT PROVEN — could not read the tree state in the throwaway worktree: git was killed by SIGTERM; install output: /,
+  },
+  {
+    name: "a git killed for outgrowing the spawn buffer reading the tree state",
+    when: "status*", act: "yes | head -c 2000000; exit 0",
+    status: 1, reason: /NOT PROVEN — could not read the tree state in the throwaway worktree: git was killed by SIGTERM \(ENOBUFS: its output outgrew the spawn buffer\); install output: /,
+  },
+  {
+    name: "a git that wrote to stderr and was then killed",
+    when: "status*", act: "echo boom >&2; kill -9 $$",
+    status: 1, reason: /NOT PROVEN — could not read the tree state in the throwaway worktree: boom; git was killed by SIGKILL; install output: /,
+  },
+  {
+    name: "a git killed restoring the tree before the mutation",
+    when: "reset*", act: "kill -9 $$", files: GO_FILES, args: GO_PROOF,
+    status: 1, reason: /NOT PROVEN — could not restore the tree before the mutation: git was killed by SIGKILL; test output: /,
+  },
+  {
+    name: "a git killed reading what the mutation changed",
+    when: "diff*", act: "kill -9 $$", files: GO_FILES, args: GO_PROOF,
+    status: 1, reason: /NOT PROVEN — could not read what the mutation changed: git was killed by SIGKILL; its output: /,
+  },
+  {
+    name: "a git killed probing for the repository",
+    when: '"rev-parse --git-dir"', act: "kill -9 $$",
+    status: 2, reason: /^recipe-prove: .* is not a git repository: git was killed by SIGKILL$/m,
+  },
+  {
+    name: "a git killed resolving the common git dir",
+    when: '"rev-parse --path-format=absolute --git-common-dir"', act: "kill -9 $$",
+    status: 2, reason: /^recipe-prove: cannot resolve the common git dir of .*: git was killed by SIGKILL$/m,
+  },
+  {
+    name: "a git killed resolving origin/main",
+    when: '"rev-parse --verify"*', act: "kill -9 $$",
+    status: 2, reason: /^recipe-prove: origin\/main does not resolve to a commit \(git was killed by SIGKILL\) — fetch it/m,
+  },
+  {
+    name: "a git killed creating the throwaway worktree",
+    when: '"worktree add"*', act: "kill -9 $$",
+    status: 2, reason: /^recipe-prove: could not create the throwaway worktree: git was killed by SIGKILL$/m,
+  },
+];
+
+for (const c of KILLED_GIT) {
+  test(`${c.name} names the signal in its refusal`, () => {
+    const { dir } = repo(c.files ?? MAVEN_FILES);
+    const r = prove(dir, c.args ?? COUNT_PROOF, { env: { PATH: fakeGit(c.when, c.act) } });
+    assert.equal(r.status, c.status, r.err);
+    assert.match(r.err, c.reason);
+    assert.doesNotMatch(r.err, /could not start git/);
+    if (c.status === 2) assert.doesNotMatch(r.err, /NOT PROVEN/);
+  });
+}
+
+// The control: a git that ran and exited non-zero is quoted as it wrote, with
+// no kill named.
+test("a git that exits non-zero is refused with exactly its stderr, naming no signal", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, COUNT_PROOF, { env: { PATH: fakeGit("status*", "echo boom >&2; exit 3") } });
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /NOT PROVEN — could not read the tree state in the throwaway worktree: boom; install output: /);
+  assert.doesNotMatch(r.err, /killed/);
+});
+
+// A killed `worktree remove` is a failed one: cleanup falls back to the plain
+// delete, and the proof's own NOT PROVEN — which keeps its log directory,
+// the throwaway worktree's parent — stands.
+test("a git killed removing the throwaway worktree still leaves it deleted", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, ["--install", "false", "--test", "true", "--count-line", "x 1", "--test-count", "1"], {
+    env: { PATH: fakeGit('"worktree remove"*', "kill -9 $$") },
+  });
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /NOT PROVEN — the Install step 'false' failed/);
+  assert.doesNotMatch(r.err, /skipped git/);
+  const kept = logDirs(r.tmp);
+  assert.equal(kept.length, 1, `log directories in ${r.tmp}: ${kept}`);
+  assert.equal(existsSync(join(r.tmp, kept[0], "wt")), false, "the throwaway worktree is gone");
+  assert.equal(git(dir, "worktree", "list", "--porcelain").split("\n").filter((l) => l.startsWith("worktree ")).length, 1, "only the main worktree stays registered");
+});
+
 // A git that starts for the worktree removal and not for the prune after it:
 // the stub deletes itself once `worktree remove` has run. The proof's own
 // outcome is NOT PROVEN (the Install step fails), and the prune that cannot