@feigi/fleet-ctl 3.17.1 → 3.17.3

package/commands/review-and-fix.md

@@ -79,7 +79,7 @@ It cannot ask the user anything and cannot wait on CI — rebasing, watching che
 - **Do not trust the obvious contamination check.** `diff -rq` and `md5` against the mutating tree both returned *clean* — because the probe had been reverted between the two reads. A clean diff against a live tree is not evidence in either direction; only `snap-ro` and the object store settle it.
 - **`git archive` carries tracked files only.** No `node_modules`, no gitignored runner or config. Provision in the same step — symlink `node_modules`, copy in what the runner needs — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement.
 - **Initialize the copy before anyone measures in it — a bare `git archive` tree cannot validly run every suite.** It is not a git repository, so anything that asks git about the checkout breaks: `derive_workspace_id` shells out to `git rev-parse`, falls back to the directory basename and the hook tests fail on the *name* — naming the dir after the repo makes those pass **by coincidence, not correctness** — while every sweep that asks git what ships declines instead of running, which is the silent half (measured on this repo at `ffa9026`: 2401 tests, 2382 pass, 19 skipped in an extraction against 2401/2401/0 in a worktree, the totals identical). `git init && git add -A -f && git commit` in the extracted copy is what makes a count mean what it looks like; the review's snapshot agent does exactly that and verifies it by comparing the new commit's tree hash against the reviewed commit's (#1056), and a hand-cut tree needs the same before you read a count off it. Suites that need the real worktree for some *other* reason — the stack below — still do.
-- **Give specialists a stack-free test command, not the worktree's runner, and their own scratch dir** — `<scratch>/pr<N>/fleet-review-<key>/`, resolved to an absolute path that you write into that specialist's prompt; a specialist never derives its own. Specialists inherit no environment, and one falling back to the default config runs a `globalSetup` that brings the shared compose stack up and tears it down, recreating the DB mid-run for every sibling. **The snapshot does not cover this** — the compose project name comes from the environment, not the working directory, so three agents on three copies still collide. But `./agent-test` does not fix it either: it exports **one** `TEST_COMPOSE_PROJECT`/port triple per *worktree* (`ab-<issue>`), so N concurrent specialists sharing it tear down each other's postgres mid-run. Observed: a probe returned `No test files found / No such container` and would have read as a test failure. **That war story is from another repo, and the config-swap escape it calls for does not exist here** — `feigi/claude-config` has no compose file, no `globalSetup`, and no vitest, so there is no `vitest.ci.config.ts` to point anyone at. (It does now have CI — `.github/workflows/ci.yml` — but that runs `node --test`, not a stack.) Naming one sends every specialist into `Cannot find module`, which reads as a broken tree rather than a bad instruction. In *this* repo the collision is inert for a different reason: the `export TEST_COMPOSE_PROJECT=…` line `claim-ticket.sh` writes into the runner sets `TEST_COMPOSE_PROJECT`/`TEST_POSTGRES_PORT`/`TEST_OLLAMA_PORT` and **nothing reads them** — the suite is `node --test` throughout. So tell specialists `node --test plugin/scripts/*.test.mjs` directly, glob form — `review-core.mjs` derives the same effective command for this repo now rather than defaulting to it (#142), keeping this bullet's manual command in agreement with it — and keep `./agent-test` for your own verification. **Hand that command with its reading rule: `tests 0` is a failed run, not a pass.** A glob is not self-checking. Where it matches nothing, bash passes the pattern through literally, node globs it itself and finds no files, and you get `ℹ tests 0` / exit 0 — a green having run nothing. Read the count under either reporter: `node --test` prints `ℹ tests 0` to a terminal and `# tests 0` to a pipe on older node, so a rule that greps only for `ℹ` finds nothing in a CI log and cannot tell a zero-test run from a full one. Do not count on the shell to catch it: zsh errors (`no matches found`, exit 1) and bash does not, so the guard has to be the reading rule. Node v26.5.0 has no flag that fails a zero-test run. **And zero is not the only no-work count.** **0 passes with no failures** is everything skipped, and a count **materially below the full suite** is a partial copy of the tree — which is the *documented* behavior, since the prompt tells specialists to run their probe work inside their own copy of the snapshot and nothing anchors an expected count for them. `review-core.mjs` classifies the first itself, in `unrunReason`; the second it structurally cannot, because that function is kept pure and so never learns how many tests the tree has. Handing the rule over with the command is the only guard the partial-copy case has. Carry the rule, not the command: in a repo that *does* have a stack, N concurrent specialists sharing one runner still collide, and the escape is whatever that repo's stack-free config is.
+- **Give specialists a stack-free test command, not the worktree's runner, and their own scratch dir** — `<scratch>/pr<N>/fleet-review-<key>/`, resolved to an absolute path that you write into that specialist's prompt; a specialist never derives its own. Specialists inherit no environment, and one falling back to the default config runs a `globalSetup` that brings the shared compose stack up and tears it down, recreating the DB mid-run for every sibling. **The snapshot does not cover this** — the compose project name comes from the environment, not the working directory, so three agents on three copies still collide. But `./agent-test` does not fix it either: it exports **one** `TEST_COMPOSE_PROJECT`/port triple per *worktree* (`ab-<issue>`), so N concurrent specialists sharing it tear down each other's postgres mid-run. Observed: a probe returned `No test files found / No such container` and would have read as a test failure. **That war story is from another repo, and the config-swap escape it calls for does not exist here** — `feigi/claude-config` has no compose file, no `globalSetup`, and no vitest, so there is no `vitest.ci.config.ts` to point anyone at. (It does now have CI — `.github/workflows/ci.yml` — but that runs `node --test`, not a stack.) Naming one sends every specialist into `Cannot find module`, which reads as a broken tree rather than a bad instruction. In *this* repo the collision is inert for a different reason: the `export TEST_COMPOSE_PROJECT=…` line `claim-ticket.sh` writes into the runner sets `TEST_COMPOSE_PROJECT`/`TEST_POSTGRES_PORT`/`TEST_OLLAMA_PORT` and **nothing reads them** — the suite is `node --test` throughout. So tell specialists this repo's test command directly — read off the Recipe cache the way step 3 reads it (`derive-testcmd.sh <worktree or main checkout> test` prints it; the snapshot carries no `.fleet/` cache, so pointing it at the snapshot refuses), here in glob form `node --test plugin/scripts/*.test.mjs` as this repo's example — and keep `./agent-test` for your own verification. **Hand that command with its reading rule: `tests 0` is a failed run, not a pass.** A glob is not self-checking. Where it matches nothing, bash passes the pattern through literally, node globs it itself and finds no files, and you get `ℹ tests 0` / exit 0 — a green having run nothing. Read the count under either reporter: `node --test` prints `ℹ tests 0` to a terminal and `# tests 0` to a pipe on older node, so a rule that greps only for `ℹ` finds nothing in a CI log and cannot tell a zero-test run from a full one. Do not count on the shell to catch it: zsh errors (`no matches found`, exit 1) and bash does not, so the guard has to be the reading rule. Node v26.5.0 has no flag that fails a zero-test run. **And zero is not the only no-work count.** **0 passes with no failures** is everything skipped, and a count **materially below the full suite** is a partial copy of the tree — which is the *documented* behavior, since the prompt tells specialists to run their probe work inside their own copy of the snapshot and nothing anchors an expected count for them. `review-core.mjs` classifies the first itself, in `unrunReason`; the second it structurally cannot, because that function is kept pure and so never learns how many tests the tree has. Handing the rule over with the command is the only guard the partial-copy case has. Carry the rule, not the command: in a repo that *does* have a stack, N concurrent specialists sharing one runner still collide, and the escape is whatever that repo's stack-free config is.
 - **Completion is not delivery — but you can reach a specialist, so never wait idle.** A specialist you dispatched reports when it settles; if a report is missing, `hub send` it by name and ask for the report. Judge delivery by whether a report came out. **Do not settle a dimension you hold no report for**: ask the specialist, then the controller by name; only when neither answers, rule and name that dimension **unrun** — a killed specialist never reports, so waiting on one is unbounded. Never ship "dispatched, never delivered" as settled; a ruling citing a report you do not hold gets verified from source, never applied on trust.
 - **Apply only once the fan-out is settled — every report either in hand or accounted for.** Collection is not guaranteed; a report that never arrived is an open dimension, not a smaller set. And editing while they read is the same defect as probing — one specialist reviewed uncommitted code that was never in the PR diff.
 

package/package.json

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

package/scripts/tier-roles.mjs

@@ -31,7 +31,10 @@
 //       flagged as a notice — legal, but every `slow-*` cell then measures
 //       the same model as its `task-*` twin;
 //   (f) the agents directory holds at least one `*.agent.md` definition —
-//       with none, (a), (b) and (d) have nothing to check.
+//       with none, (a), (b) and (d) have nothing to check; an agents
+//       directory that cannot be read (missing, not a directory) or a
+//       definition that cannot be read (a directory named `*.agent.md`)
+//       fails too.
 
 import { readFileSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -202,19 +205,35 @@ function kindOf(v) {
 // definitions need. `violations` stop a run (ADR 0014); `notices` never do —
 // they flag a hazard (two roles' cells measuring one model) that is legal
 // configuration, just probably not what the operator meant.
-export function checkRoutes({ agentsDir, modelRoles, overrides, catalog }) {
+export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`, modelRoles, overrides, catalog }) {
   const violations = [];
   const notices = [];
   const usedBy = {}; // role -> [{ file, level }, ...]
 
-  const files = readdirSync(agentsDir).filter((f) => f.endsWith(".agent.md")).sort();
-  // A directory with no definitions has nothing to route, so every
-  // per-definition check below (the model route, the role's resolution, the
-  // level) would pass over it — a wrong `--agents` path that exists must not
-  // read as a healthy install.
-  if (files.length === 0) violations.push(`no *.agent.md definition found in ${agentsDir}`);
+  // A path `readdirSync`/`readFileSync` cannot read (missing, a regular file,
+  // a directory named `*.agent.md`, no permission) is a wrong agents
+  // directory, not a crash: name the path and where it came from
+  // (`agentsSource` — `--agents <dir>`, or the built-in default).
+  const unreadable = (what, e) => `${agentsSource}: cannot read ${what} (${e.code ?? e.message})`;
+  let files = [];
+  try {
+    files = readdirSync(agentsDir).filter((f) => f.endsWith(".agent.md")).sort();
+    // A directory with no definitions has nothing to route, so every
+    // per-definition check below (the model route, the role's resolution, the
+    // level) would pass over it — a wrong `--agents` path that exists must not
+    // read as a healthy install.
+    if (files.length === 0) violations.push(`no *.agent.md definition found in ${agentsDir}`);
+  } catch (e) {
+    violations.push(unreadable("the agents directory", e));
+  }
   for (const file of files) {
-    const text = readFileSync(join(agentsDir, file), "utf8");
+    let text;
+    try {
+      text = readFileSync(join(agentsDir, file), "utf8");
+    } catch (e) {
+      violations.push(unreadable(file, e));
+      continue;
+    }
     const fm = parseFrontmatter(text);
     if (!fm.role || !fm.level) {
       violations.push(`${file}: model ${JSON.stringify(fm.model)} is not @<role>:<level>`);
@@ -317,13 +336,20 @@ function main() {
   const check = has("check");
   if (!check) die("--check is required (usage: tier-roles.mjs --check [--agents <dir>] [--model-roles <path>] [--overrides <path>] [--catalog <path>])");
 
-  const agentsDir = arg("agents") ?? join(SCRIPT_DIR, "..", "agents");
+  const agentsFlag = arg("agents");
+  const agentsDir = agentsFlag ?? join(SCRIPT_DIR, "..", "agents");
   const config = (key) => [() => readOmpConfigValue(key), `omp config get ${key} --json`];
   const overrides = loadJsonObject(arg("overrides"), ...config("task.agentModelOverrides"), "overrides");
   const modelRoles = loadJsonObject(arg("model-roles"), ...config("modelRoles"), "model-roles");
   const catalog = loadJsonObject(arg("catalog"), readOmpModelCatalog, "omp models --json", "catalog");
 
-  const { violations, notices } = checkRoutes({ agentsDir, modelRoles, overrides, catalog });
+  const { violations, notices } = checkRoutes({
+    agentsDir,
+    agentsSource: agentsFlag === null ? `the default agents directory ${agentsDir}` : undefined,
+    modelRoles,
+    overrides,
+    catalog,
+  });
 
   if (violations.length === 0) {
     console.log("tier-roles: every definition routes to a resolvable model at a level it runs, no shadowing override");

package/scripts/tier-roles.test.mjs

@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { chmodSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { tempDir } from "./temp-dir.mjs";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,6 +12,7 @@ import {
 } from "./tier-roles.mjs";
 
 const SCRIPT = fileURLToPath(new URL("./tier-roles.mjs", import.meta.url));
+const SCRIPTS_DIR = fileURLToPath(new URL(".", import.meta.url));
 const REPO_AGENTS = fileURLToPath(new URL("../agents", import.meta.url));
 
 function dir() {
@@ -211,6 +212,32 @@ test("checkRoutes: an empty agents directory still reports the other violations
   assert.match(violations.join("\n"), /task\.agentModelOverrides\.fleet-a shadows/);
 });
 
+test("checkRoutes: an --agents path that is missing, or a regular file, is a violation naming the flag and path, not a crash", () => {
+  const d = dir();
+  const missing = join(d, "nope");
+  const file = join(d, "plain.txt");
+  writeFileSync(file, "x\n");
+  for (const [path, code] of [[missing, "ENOENT"], [file, "ENOTDIR"]]) {
+    const { violations } = checkRoutes({ agentsDir: path, modelRoles: MODEL_ROLES, overrides: {}, catalog: CATALOG });
+    assert.deepEqual(violations, [`--agents ${path}: cannot read the agents directory (${code})`]);
+  }
+});
+
+test("checkRoutes: a directory named *.agent.md is a violation naming the entry, and the readable definitions after it are still checked", () => {
+  const agents = agentsDir({ "fleet-a": "@slow:xhigh", "fleet-b": "@smol:max" });
+  mkdirSync(join(agents, "a.agent.md"));
+  const { violations } = checkRoutes({ agentsDir: agents, modelRoles: MODEL_ROLES, overrides: {}, catalog: CATALOG });
+  assert.equal(violations.length, 2);
+  assert.equal(violations[0], `--agents ${agents}: cannot read a.agent.md (EISDIR)`);
+  assert.match(violations[1], /^fleet-b\.agent\.md: level max is not one modelRoles\.smol's target/);
+});
+
+test("checkRoutes: an unreadable agents directory names the source the caller gives, not --agents", () => {
+  const missing = join(dir(), "nope");
+  const { violations } = checkRoutes({ agentsDir: missing, agentsSource: "the default agents directory X", modelRoles: MODEL_ROLES, overrides: {}, catalog: CATALOG });
+  assert.deepEqual(violations, ["the default agents directory X: cannot read the agents directory (ENOENT)"]);
+});
+
 test("checkRoutes (a): a definition whose model: is not a route is a violation naming the file", () => {
   const { violations } = routes({ "fleet-a": "opus" });
   assert.equal(violations.length, 1);
@@ -358,6 +385,33 @@ test("CLI: --check on an agents directory with no definitions exits 1 naming the
   assert.doesNotMatch(r.stdout, /every definition routes/);
 });
 
+test("CLI: --check on an --agents path that is missing, a regular file, or holds a directory named *.agent.md exits 1 with a refusal naming the cause, no stack trace", () => {
+  const d = dir();
+  const file = join(d, "plain.txt");
+  writeFileSync(file, "x\n");
+  const trap = agentsDir({ "fleet-a": "@slow:xhigh" });
+  mkdirSync(join(trap, "x.agent.md"));
+  for (const [path, code] of [[join(d, "nope"), "ENOENT"], [file, "ENOTDIR"], [trap, "EISDIR"]]) {
+    const r = runCli(["--check", "--agents", path, ...installFlags(d)], d);
+    assert.equal(r.status, 1, path);
+    assert.match(r.stderr, new RegExp(`^tier-roles: --agents ${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}: cannot read .*\\(${code}\\)`), path);
+    assert.doesNotMatch(r.stderr, /\n\s+at /, path);
+    assert.doesNotMatch(r.stdout, /every definition routes/);
+  }
+});
+
+test("CLI: --check with no --agents and an unreadable built-in agents directory refuses without naming a flag it was not given", () => {
+  const d = dir();
+  const scripts = join(d, "scripts");
+  mkdirSync(scripts);
+  for (const f of ["tier-roles.mjs", "arg.mjs", "is-cli.mjs"]) copyFileSync(join(SCRIPTS_DIR, f), join(scripts, f));
+  const r = spawnSync(process.execPath, [join(scripts, "tier-roles.mjs"), "--check", ...installFlags(d)], { cwd: d, encoding: "utf8" });
+  assert.equal(r.status, 1, r.stderr);
+  assert.match(r.stderr, /^tier-roles: the default agents directory .*agents: cannot read the agents directory \(ENOENT\)/);
+  assert.doesNotMatch(r.stderr, /--agents/);
+  assert.doesNotMatch(r.stderr, /\n\s+at /);
+});
+
 test("CLI: --check with a non-route model: exits 1 naming the file", () => {
   const d = dir();
   const agents = agentsDir({ "fleet-a": "opus" });