@feigi/fleet-ctl 3.23.18 → 3.23.20

package/package.json

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

package/scripts/derive-testcmd.sh

@@ -37,6 +37,11 @@
 # is asked for must name something that resolves from <repo> (a builtin, a
 # PATH entry, an executable path). A red suite is a finding, not a stale
 # Recipe, so nothing here ever runs the command.
+#
+# Exit status: 0 the command is printed; 1 a refusal about the cache, the
+# repository or the arguments; 3 a tool this script needs to read the cache
+# (node, mktemp, cat) could not be started or node died mid-read, so nothing
+# was read and the cache's usability is unknown.
 set -eu
 
 # Byte semantics for every construct below that reads a string by bytes:
@@ -83,6 +88,15 @@ unset GIT_DIR GIT_WORK_TREE
 NAME=derive-testcmd
 die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 1; }
 
+# A refusal about the environment, not the cache: a tool this script needs to
+# read the cache (the interpreter, mktemp, cat) could not be started, or the
+# interpreter died mid-read, so nothing was read and the cache's usability is
+# unknown. Exit 3, where every refusal about the cache, the repository or the
+# arguments is exit 1. A git that cannot be started is not told apart: it reads
+# as no repository, exit 1. A consumer that only tests for non-zero sees no
+# difference.
+unrunnable() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 3; }
+
 # Named once: every refusal that sends the caller to re-derive names the same
 # step, so a controller or reviewer reading any of them knows what to run.
 derive="run the Recipe derivation step (run-team phase 0, before the first claim — ADR 0015) to derive, prove and write it"
@@ -113,7 +127,7 @@ cache="${common%/*}/.fleet/recipe.json"
 # An INVOCATION, not a name lookup (#1141): a version-manager shim satisfies
 # `command -v node` and then fails, and its stderr would arrive below under the
 # cache's name — a corrupt-cache refusal for a cache nobody read.
-nodeerr=$(node -e 0 </dev/null 2>&1) || die "node is unusable, refusing to read the Recipe cache without the interpreter — $nodeerr"
+nodeerr=$(node -e 0 </dev/null 2>&1) || unrunnable "node is unusable, refusing to read the Recipe cache without the interpreter — $nodeerr"
 
 # Validation and extraction in one pass, so a field is never printed out of a
 # cache the checks did not pass. rc 0 prints the value; anything else carries
@@ -143,11 +157,15 @@ nodeerr=$(node -e 0 </dev/null 2>&1) || die "node is unusable, refusing to read
 #   newline now survives inside the frame, and the trailing-operator check
 #   below treats it exactly like a trailing `;` or `&`: refused, not
 #   silently accepted.
-errf=$(mktemp) || die "cannot create a temporary file to read the Recipe cache"
-lenf=$(mktemp) || die "cannot create a temporary file to read the Recipe cache"
-trap 'rm -f "$errf" "$lenf"' EXIT
+errf=$(mktemp) || unrunnable "cannot create a temporary file to read the Recipe cache"
+lenf=$(mktemp) || unrunnable "cannot create a temporary file to read the Recipe cache"
+# Cleanup decides nothing: an `rm` that cannot be started would otherwise
+# replace the script's own exit status with 127 (and print a line on the
+# success path), so the status the script was leaving with is kept.
+trap 'rc=$?; rm -f "$errf" "$lenf" 2>/dev/null || :; exit $rc' EXIT
 
 open='recipe<' close='>recipe'
+rc=0
 framed=$(node -e '
 const fs = require("fs");
 const [file, field, open, close, lenFile] = process.argv.slice(1);
@@ -166,13 +184,30 @@ if (!counted && !mutated) bad("it carries no proof of real tests — neither a p
 const value = r[field];
 fs.writeFileSync(lenFile, String(Buffer.byteLength(open + value + close)));
 process.stdout.write(open + value + close);
-' "$cache" "$field" "$open" "$close" "$lenf" 2>"$errf") || die "the Recipe cache at $cache is unusable: $(cat "$errf") — $derive"
+' "$cache" "$field" "$open" "$close" "$lenf" 2>"$errf") || rc=$?
+# node's own refusal of the cache is exit 2 (an uncaught fault is exit 1), the
+# reason on stderr either way; a status of 126 or above is the shell failing to
+# run node or the system killing it mid-read, which says nothing about the cache.
+if [ "$rc" -ge 126 ]; then
+  unrunnable "node did not finish reading the Recipe cache (exit $rc), so its usability is unknown"
+fi
+[ "$rc" -eq 0 ] || die "the Recipe cache at $cache is unusable: $(cat "$errf") — $derive"
 carriedmsg="node's stdout carried more than the framed Recipe value — expected exactly the value between '$open' and '$close', got '$framed'. The cache at $cache passed validation; the extra output comes from how node is launched here (a version-manager or proxy shim, a preload), and is refused rather than cut out of the command"
 case $framed in
   "$open"*"$close") ;;
   *) die "$carriedmsg" ;;
 esac
-framedlen=$(cat "$lenf")
+# A `cat` that cannot be started (126/127) is the environment's fault, as for
+# `node` above; a `cat` that ran and failed refuses with its own reason, and a
+# count file that was read but holds no digits is the corrupt-count refusal
+# below.
+rc=0
+framedlen=$(cat "$lenf" 2>"$errf") || rc=$?
+case $rc in
+  0) ;;
+  126|127) unrunnable "cat could not be started (exit $rc), so the Recipe cache cannot be read" ;;
+  *) die "the Recipe cache at $cache is unusable: cat failed reading node's byte-count file (exit $rc): $(cat "$errf" 2>/dev/null) — $derive" ;;
+esac
 case $framedlen in
   ''|*[!0-9]*) die "the Recipe cache at $cache is unusable: node's byte-count file is missing or corrupt — $derive" ;;
 esac

package/scripts/derive-testcmd.test.mjs

@@ -304,9 +304,10 @@ test("the success path writes nothing to stderr, even when node is chatty (#1175
 // cache. PATH is REPLACED with links to exactly what the script runs, so the
 // interpreter is really unreachable rather than shadowed.
 const SHIMMED = ["sh", "git", "mktemp", "cat", "rm"];
-function shimPath({ node }) {
+function shimPath({ node, omit }) {
   const bin = tempDir("derive-path-");
   for (const name of SHIMMED) {
+    if (name === omit) continue;
     const real = execFileSync("sh", ["-c", `command -v ${name}`], { encoding: "utf8" }).trim();
     symlinkSync(real, join(bin, name));
   }
@@ -314,11 +315,14 @@ function shimPath({ node }) {
   return bin;
 }
 
+// Exit 3, where every refusal about the cache, the repository or the arguments
+// is exit 1: the reader read nothing, so a caller can tell its own
+// environment's fault from a verdict on the cache.
 test("an unusable interpreter refuses in this script's own voice, never the cache's", () => {
   const { dir, head } = repo();
   cache(dir, recipe(head, { test: "true" }));
   const absent = derive(dir, "test", { ...process.env, PATH: shimPath({ node: false }) });
-  assert.equal(absent.status, 1);
+  assert.equal(absent.status, 3);
   assert.equal(absent.out, "");
   assert.match(absent.err, /^derive-testcmd: node is unusable/);
   assert.doesNotMatch(absent.err, /is unusable: it does not parse/);
@@ -331,6 +335,119 @@ test("an unusable interpreter refuses in this script's own voice, never the cach
   assert.equal(present.out, "true");
 });
 
+// The reader's other tools, taken away the same way. The control above is the
+// same stripped PATH with every tool present.
+for (const [tool, reason] of [
+  ["mktemp", /^derive-testcmd: cannot create a temporary file to read the Recipe cache$/m],
+  ["cat", /^derive-testcmd: cat could not be started \(exit 127\), so the Recipe cache cannot be read$/m],
+]) {
+  test(`a ${tool} that cannot be started is the environment's refusal, exit 3, never the cache's`, () => {
+    const { dir, head } = repo();
+    cache(dir, recipe(head, { test: "true" }));
+    const r = derive(dir, "test", { ...process.env, PATH: shimPath({ node: true, omit: tool }) });
+    assert.equal(r.status, 3, r.err);
+    assert.equal(r.out, "");
+    assert.match(r.err, reason);
+    assert.doesNotMatch(r.err, /is unusable|byte-count/);
+  });
+}
+
+// The reader asks mktemp twice, and a mktemp that starts and then fails — a
+// full or unwritable temp directory — is the same environment fault as one
+// that is missing, on either call.
+test("a mktemp that runs and fails on its second call is exit 3, never the cache's", () => {
+  const { dir, head } = repo();
+  cache(dir, recipe(head, { test: "true" }));
+  const bin = shimPath({ node: true, omit: "mktemp" });
+  const real = execFileSync("sh", ["-c", "command -v mktemp"], { encoding: "utf8" }).trim();
+  const mark = join(bin, "called");
+  writeExecStub(join(bin, "mktemp"), `#!/bin/sh\nif [ -e '${mark}' ]; then echo 'mktemp: no space left' >&2; exit 1; fi\n: > '${mark}'\nexec '${real}' "$@"\n`);
+  const r = derive(dir, "test", { ...process.env, PATH: bin });
+  assert.equal(r.status, 3, r.err);
+  assert.match(r.err, /^derive-testcmd: cannot create a temporary file to read the Recipe cache$/m);
+});
+
+// The reader's `node -e 0` probe passes, and then the interpreter dies during
+// the real read — killed, or no longer runnable. Nothing was read, so that is
+// exit 3 as well. Node's own refusal of the cache (its exit 2) and an uncaught
+// fault of its own (exit 1) are still the cache's exit 1, with node's reason.
+for (const [what, body, status, reason] of [
+  ["is killed", "kill -9 $$", 3, /^derive-testcmd: node did not finish reading the Recipe cache \(exit 137\)/m],
+  ["can no longer be run", "exit 127", 3, /^derive-testcmd: node did not finish reading the Recipe cache \(exit 127\)/m],
+  ["refuses the cache itself", "echo 'it does not parse: boom' >&2; exit 2", 1, /is unusable: it does not parse: boom/],
+  ["faults on its own", "echo 'TypeError: boom' >&2; exit 1", 1, /is unusable: TypeError: boom/],
+]) {
+  test(`a node that passes the probe and then ${what} is exit ${status}`, () => {
+    const { dir, head } = repo();
+    cache(dir, recipe(head, { test: "true" }));
+    const bin = shimPath({ node: false });
+    writeExecStub(join(bin, "node"), `#!/bin/sh\nif [ "$1" = -e ] && [ "$2" = 0 ]; then exit 0; fi\n${body}\n`);
+    const r = derive(dir, "test", { ...process.env, PATH: bin });
+    assert.equal(r.status, status, r.err);
+    assert.equal(r.out, "");
+    assert.match(r.err, reason);
+  });
+}
+
+// A cat that exits 126 — the status a shell gives a command it found but could
+// not execute — is the environment's fault like one that is missing (127). The
+// stub exits 126 itself: whether a shell reports an unexecutable file as 126
+// depends on the shell and its options, and this pins the reader's reading of
+// the status, not the shell's.
+test("a cat that exits 126 is exit 3, never the cache's", () => {
+  const { dir, head } = repo();
+  cache(dir, recipe(head, { test: "true" }));
+  const bin = shimPath({ node: true, omit: "cat" });
+  writeExecStub(join(bin, "cat"), "#!/bin/sh\nexit 126\n");
+  const r = derive(dir, "test", { ...process.env, PATH: bin });
+  assert.equal(r.status, 3, r.err);
+  assert.equal(r.out, "");
+  assert.match(r.err, /^derive-testcmd: cat could not be started \(exit 126\), so the Recipe cache cannot be read$/m);
+});
+
+// A cat that starts and fails while reading node's byte-count file is the
+// cache refusal, exit 1, and carries cat's own reason.
+test("a cat that runs and fails on the byte-count file is exit 1, carrying its reason", () => {
+  const { dir, head } = repo();
+  cache(dir, recipe(head, { test: "true" }));
+  const bin = shimPath({ node: true, omit: "cat" });
+  const real = execFileSync("sh", ["-c", "command -v cat"], { encoding: "utf8" }).trim();
+  const mark = join(bin, "called");
+  writeExecStub(join(bin, "cat"), `#!/bin/sh\nif [ ! -e '${mark}' ]; then : > '${mark}'; echo 'cat: I/O error' >&2; exit 1; fi\nexec '${real}' "$@"\n`);
+  const r = derive(dir, "test", { ...process.env, PATH: bin });
+  assert.equal(r.status, 1, r.err);
+  assert.equal(r.out, "");
+  assert.match(r.err, /cat failed reading node's byte-count file \(exit 1\): cat: I\/O error/);
+  assert.doesNotMatch(r.err, /could not be started/);
+});
+
+// `rm` is the reader's cleanup only, so it must not decide the outcome: with
+// it gone a good cache still reads cleanly — status 0 and nothing on stderr,
+// the success-path invariant claim-ticket.sh relies on — and a refused cache
+// keeps its own status.
+test("an rm that cannot be started changes neither the value read nor the refusal's status", () => {
+  const { dir, head } = repo();
+  cache(dir, recipe(head, { test: "true" }));
+  const ok = derive(dir, "test", { ...process.env, PATH: shimPath({ node: true, omit: "rm" }) });
+  assert.equal(ok.status, 0, ok.err);
+  assert.equal(ok.out, "true");
+  assert.equal(ok.err, "");
+
+  cache(dir, "not json");
+  const refused = derive(dir, "test", { ...process.env, PATH: shimPath({ node: true, omit: "rm" }) });
+  assert.equal(refused.status, 1, refused.err);
+});
+
+// The false-positive class: a cache the reader really refuses stays exit 1
+// under the same stripped PATH, so exit 3 is not "any refusal".
+test("a cache that is refused stays exit 1 under the stripped PATH", () => {
+  const { dir } = repo();
+  cache(dir, "not json");
+  const r = derive(dir, "test", { ...process.env, PATH: shimPath({ node: true }) });
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /is unusable/);
+});
+
 // --- #2217: node's STDOUT is the capture itself, so the stream split above
 // does nothing for it. A version-manager or proxy shim prints before exec'ing
 // the real node, or — not exec'ing — after it exits, and unframed that chatter

package/scripts/recipe-prove.mjs

@@ -57,8 +57,10 @@
 //         repository, origin/main missing, the worktree could not be made), or
 //         a git or filesystem fault stopped it before the cache was settled
 //         (a git command could not be started, the reader's own git
-//         included, or the reader's `sh`; the cache or its temp file could
-//         not be written). The log directory under $TMPDIR is removed.
+//         included; the reader's `sh`, `node`, `mktemp` or `cat` could not be
+//         started, or its `node` died mid-read — a `cat` that ran and failed
+//         stays the reader's refusal, exit 1; the cache or its temp file
+//         could not be written). The log directory under $TMPDIR is removed.
 
 import { spawnSync } from "node:child_process";
 import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
@@ -110,6 +112,11 @@ class Refusal extends Error {
 const cannot = (message) => new Refusal(2, message);
 const notProven = (message) => new Refusal(1, message);
 
+// The exit status derive-testcmd.sh uses for a refusal about its own
+// environment — a tool it needs would not start, or node died mid-read — where
+// every refusal about the cache is 1.
+const READER_COULD_NOT_RUN = 3;
+
 function parseArgs(argv) {
   const [repo, ...rest] = argv;
   if (!repo || repo.startsWith("--")) throw cannot(USAGE);
@@ -278,9 +285,11 @@ function prove(o, wt, logs) {
 // Write, then read back through the one reader. A cache it refuses is undone:
 // the prior bytes restored, or the file removed when none stood before. The
 // cache is undone just the same when the read-back is no verdict: an `sh` that
-// could not be started read nothing, and the reader runs git itself and reads
-// a git that will not start as no repository at all, so its refusal is a
-// verdict on what was proven only while git still starts.
+// could not be started read nothing; a reader that exits READER_COULD_NOT_RUN
+// could not start its `node`, `mktemp` or `cat`, or lost its `node` mid-read;
+// and the reader runs git itself and reads a git that will not start as no
+// repository at all, so its refusal is a verdict on what was proven only while
+// git still starts.
 function writeCache(cache, recipe, repo) {
   mkdirSync(dirname(cache), { recursive: true });
   const prior = existsSync(cache) ? readFileSync(cache) : null;
@@ -298,6 +307,7 @@ function writeCache(cache, recipe, repo) {
     if (prior === null) unlinkSync(cache);
     else writeFileSync(cache, prior);
     if (r.error && !r.pid) throw cannot(`could not start sh to read the Recipe cache back: ${r.error.message}`);
+    if (r.status === READER_COULD_NOT_RUN) throw cannot(`${r.stderr.trim()} — the Recipe cache reader could not run a tool it needs, so its refusal is no verdict on what was proven`);
     try {
       git(["--version"]);
     } catch (e) {

package/scripts/recipe-prove.test.mjs

@@ -677,6 +677,48 @@ test("an sh that stops starting before the cache is read back is no verdict, nev
   assert.equal(existsSync(cachePath(dir)), false, "a cache the reader never read is rolled back");
 });
 
+// The reader's other external tools, taken away the same way after the proof's
+// last step. The control is the same PATH with the tool left in place, which
+// proves — so the no verdict below is about the missing tool, not a PATH too
+// thin for the reader to run at all. `rm` is the reader's cleanup only: it
+// decides nothing about the cache, so the verdict stands without it.
+const READER_TOOLS = [
+  { tool: "node", reason: /derive-testcmd: node is unusable, refusing to read the Recipe cache without the interpreter/ },
+  { tool: "mktemp", reason: /derive-testcmd: cannot create a temporary file to read the Recipe cache/ },
+  { tool: "cat", reason: /derive-testcmd: cat could not be started/ },
+];
+for (const c of READER_TOOLS) {
+  test(`a ${c.tool} that stops starting before the cache is read back is no verdict, never NOT PROVEN — and the prior cache is restored`, () => {
+    const args = (cmd) => ["--install", "true", "--test", cmd, "--count-line", "tests 1", "--test-count", "1"];
+    const kept = repo(MAVEN_FILES);
+    const ok = prove(kept.dir, args(`echo 'tests 1'`), { env: { PATH: readerPath() } });
+    assert.equal(ok.status, 0, ok.err);
+    assert.match(ok.out, /^recipe-prove: PROVEN/);
+
+    const { dir } = repo(MAVEN_FILES);
+    mkdirSync(join(dir, ".fleet"));
+    writeFileSync(cachePath(dir), "prior bytes");
+    const bin = readerPath();
+    const r = prove(dir, args(`rm '${join(bin, c.tool)}'; echo 'tests 1'`), { env: { PATH: bin } });
+    assert.equal(r.status, 2, r.err);
+    assert.match(r.err, c.reason);
+    assert.match(r.err, /the Recipe cache reader could not run a tool it needs, so its refusal is no verdict/);
+    assert.doesNotMatch(r.err, /NOT PROVEN/);
+    assert.equal(readFileSync(cachePath(dir), "utf8"), "prior bytes", "a cache the reader never settled is rolled back");
+    assert.deepEqual(logDirs(r.tmp), [], "no verdict keeps no logs");
+  });
+}
+
+test("an rm that stops starting before the cache is read back leaves the proof standing — the reader's verdict never depended on it", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const bin = readerPath();
+  // `echo` leads the command: the reader refuses a Test entrypoint whose first word does not resolve, and `rm` would not once the PATH link is gone.
+  const r = prove(dir, ["--install", "true", "--test", `echo 'tests 1'; rm '${join(bin, "rm")}'`, "--count-line", "tests 1", "--test-count", "1"], { env: { PATH: bin } });
+  assert.equal(r.status, 0, r.err);
+  assert.match(r.out, /^recipe-prove: PROVEN/);
+  assert.equal(existsSync(cachePath(dir)), true);
+});
+
 // Whether the process ignores file modes: root writes into a 0555 directory.
 const IGNORES_MODES = process.getuid?.() === 0 && "root ignores file modes";
 

package/skills/next-ticket/SKILL.md

@@ -76,7 +76,7 @@ gh label create in-progress --color FBCA04 --force   # first time only
 gh issue edit <N> --add-label in-progress
 ```
 
-Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, run the Install step, run the Test entrypoint as the baseline — both the repo's **Recipe**, read from its Recipe cache: `~/.fleet/bin/fleet-run derive-testcmd.sh . install` and `… . test` print them. **No usable cache (either refuses) → run the Recipe derivation step first:** dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it reads the repo, proves both commands in a throwaway worktree and writes the cache only on proof. `RECIPE NOT PROVEN` → stop and give the maintainer its reason; never pick a command yourself.
+Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, run the Install step, run the Test entrypoint as the baseline — both the repo's **Recipe**, read from its Recipe cache: `~/.fleet/bin/fleet-run derive-testcmd.sh . install` and `… . test` print them. **No usable cache (either exits 1) → run the Recipe derivation step first:** dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it reads the repo, proves both commands in a throwaway worktree and writes the cache only on proof. `RECIPE NOT PROVEN` → stop and give the maintainer its reason; never pick a command yourself. Exit 3 is no verdict on the cache — the reader could not run a tool it needs — so fix that environment fault and re-run instead of deriving.
 
 Abandoned before PR opens → remove `in-progress`.
 

package/skills/run-team/SKILL.md

@@ -369,7 +369,10 @@ phase, or in any later one, asks the maintainer which tickets to take.
    command. Check it first: `~/.fleet/bin/fleet-run derive-testcmd.sh .
    install` and `~/.fleet/bin/fleet-run derive-testcmd.sh . test`. **Both exit
    0 → the cache is present and valid: use it as it stands and derive
-   nothing.** Either refuses → derive it. This step is yours: one derivation
+   nothing.** Either exits 1 (a refusal about the cache) → derive it. Either
+   exits 3 → the reader could not run a tool it needs, so the cache's state is
+   unknown: fix that environment fault and check again; deriving would not
+   help. This step is yours: one derivation
    per run start at most, never one per member, and a member never derives.
    Dispatch a `task` member named `derive-recipe`, agent
    `fleet-recipe-deriver`, and wait for its report — nothing in this run can