@feigi/fleet-ctl 3.82.28 → 3.83.1

package/agents/fleet-recipe-deriver.agent.md

@@ -58,19 +58,27 @@ derive never changes the answer.
   the frozen or locked mode in the command; never rely on the environment to
   imply it.
 - **Test entrypoint** — every test step in the merge-gating CI jobs that can
-  run in a fresh worktree without a running service. Which steps qualify is yours to
-  decide, by reading CI and the repository. Members run it with their own
-  arguments appended (`sh -c '<test> "$@"'`), so it is one invocation: an
-  `&&` chain hands those arguments to its last command alone. Prefer a form
-  where an appended test file or test name lands as an argument to the test
-  runner. The cache reader refuses a command whose first word does not
-  resolve from the repository root (a builtin, a `PATH` entry, or an
-  executable path), one ending in `;`, `&` or a newline, one containing a
-  word that starts with `#`, and one with an unquoted pattern that matches no
-  file tracked from the repository root. Quote a pattern that a program
-  resolves under its own directory option, e.g.
-  `git -C web ls-files -- '*.test.ts'`: the reader accepts a quoted pattern
-  unchecked.
+  run in a fresh worktree without a running service. Which steps qualify is
+  yours to decide, by reading CI and the repository. It is ONE simple command:
+  the reader refuses an unquoted `&&`, `||`, `;`, `|`, a `&` that is not part
+  of a redirection, or a `(`…`)` group. Members run it with their own arguments
+  appended (`sh -c '<test> "$@"'`), and a join or group hands those arguments
+  to its last command alone or breaks the run. An unquoted newline ends a
+  command as `;` does, so it is refused too. `2>&1` and `>&2` stay accepted.
+  A chain is accepted only quoted as the script of `sh -c`, and that form
+  forwards the appended arguments only through `"$@"`:
+  `sh -c 'cd web && npm test -- "$@"' sh`. A suite in a subdirectory uses its
+  runner's directory option, not `cd`: `npm --prefix web test`,
+  `pnpm -C web test`, `make -C web test`, `go -C web test`,
+  `mvn -f web/pom.xml test`, `gradle -p web test`. Prefer a form where an
+  appended test file or test name lands as an argument to the test runner. The
+  cache reader refuses a command whose first word does not resolve from the
+  repository root (a builtin, a `PATH` entry, or an executable path), one
+  ending in `;`, `&` or a newline, one containing a word that starts with `#`,
+  and one with an unquoted pattern that matches no file tracked from the
+  repository root. Quote a pattern that a program resolves under its own
+  directory option, e.g. `git -C web ls-files -- '*.test.ts'`: the reader
+  accepts a quoted pattern unchecked.
 - **Check step** — every merge-gating CI step that is not a test step, that
   the Test entrypoint does not run, and that needs no running service: the format, lint and type checks the
   repository's CI gates on, whatever they are. One invocation, in the same form
@@ -92,6 +100,22 @@ derive never changes the answer.
   PROVEN` with the cause **needs a running service**, never an entrypoint
   that needs one. That is not the case above of no single invocation covering
   every qualifying step.
+- **Covered steps** — every merge-gating CI step the Test entrypoint or the
+  Check step runs, passed as `--covered`: one JSON array of
+  `{"step": "<the CI step>", "by": "test" | "check"}`, one entry per step,
+  `by` naming which of the two runs it. At least one entry is `by: "test"`,
+  and `by: "check"` is refused while the Check step is `true`. A step is in
+  `--covered` or in `--uncovered`, never both: the two lists are compared on
+  the step name exactly, after trimming and collapsing internal whitespace, so
+  write a step the same way in both.
+- **The ledger** — before you propose, classify every test step and every
+  non-test step of every merge-gating CI job: run by the Test entrypoint
+  (`by: "test"`), run by the Check step (`by: "check"`), or uncovered with a
+  reason. Leave none unclassified. A step the Test entrypoint or the Check step
+  runs never goes in `uncovered`; a merge-gating step that needs a running
+  service, or another OS, always does. Which steps qualify is your judgement:
+  no script checks it, so a step left out of both lists (a Docker-gated step
+  omitted from `uncovered`, for example) is the one error nothing here catches.
 
 ## 2. Prove it — this procedure exactly
 
@@ -100,7 +124,7 @@ script creates and removes; `<repo>`'s own tree is never touched.
 
 **First run, to see the output** — no proof flags:
 
-    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>'
+    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>'
 
 It exits 1 with `NOT PROVEN — no proof given` once every command ran, and
 names the Test entrypoint's output file (`test output: <path>`). Any other
@@ -113,7 +137,7 @@ and revise.
   text off that summary line, as printed, into `--count-line`, and the number
   of tests that ran into `--test-count`:
 
-      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>' \
+      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
         --count-line '<literal text of the count line>' --test-count <n>
 
   The number is the tests that ran — never the skipped, the failed, or a
@@ -131,7 +155,7 @@ and revise.
   must change a tracked file; the script runs it in the throwaway worktree,
   requires the suite to go red, and discards the worktree after:
 
-      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>' \
+      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
         --mutate '<shell command that breaks one test>' --mutation '<one line: what it breaks>'
 
 **The Check step's own proof** — when `--check` is not `true`, the Check step
@@ -140,15 +164,17 @@ must run green on `origin/main`, and one mutation must turn it red. Give
 `--check true`. Both proofs ride in one run: the Test entrypoint's proof flags
 from above, and these:
 
-    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --uncovered '<uncovered>' \
+    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --check '<check>' --test '<test>' --covered '<covered>' --uncovered '<uncovered>' \
       --check-mutate '<shell command that breaks one file the Check step reads>' --check-mutation '<one line: what it breaks>' \
       <the Test entrypoint's proof flags>
 
 Exit 0 is the proof holding: the script wrote the Recipe cache and printed
 `PROVEN` and the cache's contents. Exit 1 is `NOT PROVEN`, with the reason;
-no cache was written. Exit 2 means no verdict on the proof: it could not be
-attempted (no `origin/main`, not a repository, a malformed `--uncovered`) or
-the cache could not be written — report it, do not work around it.
+no cache was written. A Test entrypoint, Install step or Check step whose shape
+the reader refuses is `NOT PROVEN` before any command runs. Exit 2 means no
+verdict on the proof: it could not be attempted (no `origin/main`, not a
+repository, a missing or malformed `--covered` or `--uncovered`) or the cache
+could not be written — report it, do not work around it.
 
 The script bounds each command it runs itself — the Install step, the Check
 step, both Test runs and the mutations — and refuses one still running at that

package/package.json

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

package/scripts/claim-ticket.sh

@@ -199,9 +199,11 @@ testcmd=$("$script_dir/derive-testcmd.sh" . test --at origin/main 2>&1) || die "
 echo "    test entrypoint → $testcmd" >&2
 
 # The Test entrypoint is a shell COMMAND, not an argv: the runner hands it to
-# the suite-slot wrapper, which hands it to `sh -c`, so a compound one
-# (`cd sub && make test`) keeps its meaning, with the
-# runner's own arguments appended as "$@". It reaches the runner's source
+# the suite-slot wrapper, which hands it to `sh -c`, so a compound one keeps
+# its meaning, with the runner's own arguments appended as "$@". A compound
+# one reaches here only quoted, as the script of an inner `sh -c`
+# (`sh -c 'cd sub && make test -- "$@"' sh`): derive-testcmd.sh refuses an
+# unquoted join. It reaches the runner's source
 # single-quoted — each embedded `'` closed, escaped and reopened — so nothing
 # in it expands at write time. `LC_ALL=C` so sed reads the command as bytes.
 # Derived here, ahead of every mutation, so a failure refuses before

package/scripts/derive-testcmd.sh

@@ -61,8 +61,20 @@
 # tree that probe reads instead of <repo>'s own index, for a caller that runs
 # the command in a worktree cut from a ref.
 #
+# A Test entrypoint is ONE simple command: a join or a group (an unquoted
+# newline, or an unquoted `;`, `&`, `|`, `(` or `)` outside a redirection) is
+# refused, because the runner appends a run's arguments to its last simple
+# command and a join hands them to the wrong one. A chain stays usable quoted
+# as the script of `sh -c`, for example `sh -c 'cd web && npm test -- "$@"' sh`.
+#
+# `--propose <repo> <install|check|test> <command> [--at <rev>]` runs the same
+# checks on a command that is in no cache: it reads no cache and runs nothing.
+# Its refusals are verdicts on the proposal. On success it prints the command
+# back and exits 0.
+#
 # Exit status: 0 the field is printed, `uncovered` as one line of compact
-# JSON; 1 a refusal about the cache, the repository or the arguments; 3 a
+# JSON, or a proposal that passes is printed back; 1 a refusal about the cache,
+# the repository, the arguments or a proposal; 3 a
 # tool this script needs to read the cache
 # (git, node, mktemp, cat) could not be started, mktemp could not create its
 # temp file, git did not run to an answer, node died mid-read, or node exited
@@ -134,17 +146,28 @@ derive="run the Recipe derivation step (run-team phase 0, before the first claim
 # the checkout still lists the old layout until someone updates it. Without
 # `--at` the probe reads <repo>'s own index, as for a caller that runs the
 # command in <repo> itself. Three arguments is neither shape: a refusal.
-usage="usage: derive-testcmd.sh <repo> <install|check|test|uncovered> [--at <rev>]"
+usage="usage: derive-testcmd.sh <repo> <install|check|test|uncovered> [--at <rev>]
+       derive-testcmd.sh --propose <repo> <install|check|test> <command> [--at <rev>]"
+propose=
+if [ "${1-}" = --propose ]; then
+  [ $# -ge 4 ] || die "$usage"
+  repo=$2
+  field=$3
+  propose=$4
+  [ -n "$propose" ] || die "--propose needs the command to check, got an empty one — $usage"
+  shift 4
+else
+  [ $# -ge 2 ] || die "$usage"
+  repo=$1
+  field=$2
+  shift 2
+fi
 rev=
-case $# in
-  2) ;;
-  4) [ "$3" = --at ] || die "$usage"
-     rev=$4
-     case $rev in ''|-*) die "--at needs a commit, got '$rev' — $usage" ;; esac ;;
-  *) die "$usage" ;;
-esac
-repo=$1
-field=$2
+if [ $# -gt 0 ]; then
+  [ $# -eq 2 ] && [ "$1" = --at ] || die "$usage"
+  rev=$2
+  case $rev in ''|-*) die "--at needs a commit, got '$rev' — $usage" ;; esac
+fi
 
 # git's own fatal — no repository there, or no such directory — exits 128, the
 # one status that is a verdict on the repository. Any other non-zero status is
@@ -157,7 +180,8 @@ gitout=$(git -C "$repo" rev-parse --git-dir 2>&1) || {
 }
 
 case $field in
-  install|check|test|uncovered) ;;
+  install|check|test) ;;
+  uncovered) [ -z "$propose" ] || die "--propose takes an install, check or test command, not '$field' — $usage" ;;
   *) die "unknown Recipe field '$field' — expected install, check, test or uncovered" ;;
 esac
 
@@ -169,6 +193,21 @@ if [ -n "$rev" ]; then
     || die "--at '$rev' does not resolve to a commit in $repo"
 fi
 
+# A proposed command is checked, never read: the checks below run on it as
+# they run on a cache's field, but nothing is read from the cache and nothing
+# is run. Its refusals are verdicts on the proposal, and say so.
+if [ -n "$propose" ]; then
+  subj="the proposed"
+  tail="no command was run — propose a command that passes these checks"
+  stale="a command that cannot run is refused before any command runs"
+  stale5="so it is refused before any command runs"
+  value=$propose
+  errf=$(mktemp) || unrunnable "cannot create a temporary file to check the proposed $field command"
+  trap 'rc=$?; rm -f "$errf" "$errf.idx" 2>/dev/null || :; exit $rc' EXIT
+else
+# The cache read, for the three fields a Recipe holds. The checks below the
+# `fi` that closes it run on the value it leaves in `value`.
+
 # `--path-format=absolute` so the common dir is a real path whatever the
 # caller's cwd. The workspace it names is git-env.mjs's resolveWorkspace() rule,
 # written out below in shell.
@@ -356,6 +395,10 @@ esac
 [ "${#framed}" -eq "$framedlen" ] || die "$carriedmsg"
 value=${framed#"$open"}
 value=${value%"$close"}
+subj="the Recipe cache at $cache is invalid: its"
+tail=$derive
+stale="a Recipe that cannot run is stale, not a finding"
+stale5="so the Recipe is stale, not a finding"
 
 # `uncovered` is data, not a command: nothing runs it and nothing appends to
 # it, so none of the command checks below apply. JSON.stringify above made it
@@ -364,6 +407,7 @@ if [ "$field" = uncovered ]; then
   printf '%s\n' "$value"
   exit 0
 fi
+fi
 
 # claim-ticket.sh appends the runner's own arguments after this string
 # textually (`exec sh -c '<cmd> "$@"' agent-test "$@"`), so a command ending in
@@ -383,7 +427,7 @@ fi
 # neither hazard is about whether the command resolves.
 case $value in
   *';'|*'&'|*'
-') die "the Recipe cache at $cache is invalid: its $field command '$value' ends in ';', '&', or a newline — a runner-appended argument after it would run as an unrelated command instead of reaching the Test entrypoint; $derive" ;;
+') die "$subj $field command '$value' ends in ';', '&', or a newline — a runner-appended argument after it would run as an unrelated command instead of reaching the Test entrypoint; $tail" ;;
 esac
 set -f
 IFS=' 	
@@ -391,7 +435,7 @@ IFS='
 # shellcheck disable=SC2086 # field splitting is the point: scanning every word
 for word in $value; do
   case $word in
-    '#'*) set +f; die "the Recipe cache at $cache is invalid: its $field command '$value' contains a '#' word — a runner-appended argument would be swallowed as a comment rather than reaching the Test entrypoint; $derive" ;;
+    '#'*) set +f; die "$subj $field command '$value' contains a '#' word — a runner-appended argument would be swallowed as a comment rather than reaching the Test entrypoint; $tail" ;;
   esac
 done
 set +f
@@ -418,7 +462,7 @@ while [ $# -gt 0 ]; do
     *) break ;;
   esac
 done
-[ $# -gt 0 ] || die "the Recipe cache at $cache is invalid: its $field command names no command, only assignments — $derive"
+[ $# -gt 0 ] || die "$subj $field command names no command, only assignments — $tail"
 case $1 in
   *[\'\"\\\$\`\(\)\{\}\<\>\|\&\;\*\?\[\~]*) ;;
   *)
@@ -431,7 +475,7 @@ case $1 in
     # or a PATH match) has no path to test and is left to `command -v`.
     (cd "$repo" && command -v -- "$1" || exit 1
       case $1 in */*) [ -x "$1" ] || exit 1 ;; esac) >/dev/null 2>&1 \
-      || die "the Recipe cache at $cache is invalid: its $field command '$1' is not found or not executable from $repo — a Recipe that cannot run is stale, not a finding; $derive"
+      || die "$subj $field command '$1' is not found or not executable from $repo — $stale; $tail"
     ;;
 esac
 
@@ -457,8 +501,8 @@ esac
 # that cannot run. An option, an `=`
 # assignment or value, a path outside <repo>, or the target of a `<` or `>`
 # redirection is the program's own to read, or selects no test, and is
-# accepted unprobed too. The scan stops judging at a `cd` or `pushd` piece,
-# past which a pattern no longer resolves from <repo>.
+# accepted unprobed too. A join or a group, an unquoted newline included, is
+# refused as soon as the scan reaches it, so no piece after one is judged.
 # A program's own directory option,
 # such as `git -C`, does not stop it: whether that option moves where the
 # program resolves a pattern is the program's to say, so a Recipe must quote a
@@ -482,7 +526,9 @@ esac
 # private index file, and the symlink and submodule test reads that tree
 # too; the ignore rules are still <repo>'s working copy's, the one place git
 # reads them from. The resolvability probe of the command's leading word
-# above stays <repo>'s own.
+# above stays <repo>'s own. A git call of the probe that fails is git not
+# running to an answer, exit 3: no verdict on the cache or on a proposal, so
+# recipe-prove.mjs never reads it as NOT PROVEN.
 if [ "$field" = test ]; then
   # An ambient index would answer `ls-files` for whatever repository or commit
   # the caller is in the middle of, not for <repo>'s tracked files.
@@ -493,7 +539,7 @@ if [ "$field" = test ]; then
     export GIT_INDEX_FILE="$errf.idx"
     git -C "$repo" read-tree "$revc" 2>"$errf" || {
       listed=$?
-      die "cannot read the tree of $rev in $repo (git read-tree exit $listed): $(cat "$errf" 2>/dev/null)"
+      unrunnable "cannot read the tree of $rev in $repo (git read-tree exit $listed): $(cat "$errf" 2>/dev/null)"
     }
   fi
   # Whether <path> is a directory git lists as ONE entry and never beneath: a
@@ -518,14 +564,12 @@ if [ "$field" = test ]; then
   # written) or `Q` (quoted or expansion-bearing: opaque), $2 the piece. Dies
   # on a stale pattern; otherwise returns 0 having accepted the piece.
   judge() {
-    [ -z "$stop" ] || return 0
     piece=$2
     was=$before
     before=$piece
     if [ -n "$redir" ]; then redir=; return 0; fi
     [ "$1" = P ] || return 0
     case $piece in
-      cd|pushd) stop=1; return 0 ;;
       -*|*=*|/*|*..*) return 0 ;;
       *'*'*|*'?'*|*'['*']'*) ;;
       *) return 0 ;;
@@ -539,7 +583,7 @@ if [ "$field" = test ]; then
     # the prefix of the files beneath it.
     tracked=$(git -C "$repo" ls-files -- ":(glob)$piece" ":(glob)${piece%/}/**" 2>"$errf") || {
       listed=$?
-      die "cannot list the files tracked in $where to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)"
+      unrunnable "cannot list the files tracked in $where to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)"
     }
     [ -z "$tracked" ] || return 0
     lead=${piece%%[*?[]*}
@@ -550,15 +594,15 @@ if [ "$field" = test ]; then
       case $opq in
         0) return 0 ;;
         1) ;;
-        *) die "cannot ask git whether '$lead' is a symlink or a submodule in $where, to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)" ;;
+        *) unrunnable "cannot ask git whether '$lead' is a symlink or a submodule in $where, to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)" ;;
       esac
     done
     ignored=0
     git -C "$repo" check-ignore -q --no-index -- "$piece" 2>"$errf" || ignored=$?
     case $ignored in
       0) ;;
-      1) die "the Recipe cache at $cache is invalid: its test command's pattern '$piece' matches no file tracked in $where — a Test entrypoint that selects no tests passes having run nothing, so the Recipe is stale, not a finding; a pattern that a program resolves under its own directory option, such as git -C, must be quoted; $derive" ;;
-      *) die "cannot ask git whether $repo ignores its test command's pattern '$piece' (git check-ignore exit $ignored): $(cat "$errf" 2>/dev/null)" ;;
+      1) die "$subj test command's pattern '$piece' matches no file tracked in $where — a Test entrypoint that selects no tests passes having run nothing, $stale5; a pattern that a program resolves under its own directory option, such as git -C, must be quoted; $tail" ;;
+      *) unrunnable "cannot ask git whether $repo ignores its test command's pattern '$piece' (git check-ignore exit $ignored): $(cat "$errf" 2>/dev/null)" ;;
     esac
   }
   # End the piece being read, if there is one, and judge it.
@@ -567,11 +611,14 @@ if [ "$field" = test ]; then
     scan_piece=
     scan_kind=P
   }
+  # Refuse the Test entrypoint for the unquoted join or group $1 names.
+  joined() {
+    die "$subj $field command '$value' has an unquoted $1, which joins or groups commands — a runner-appended argument would land after the last one, not reach the Test entrypoint; write one invocation with no unquoted operator or newline (a directory option such as npm --prefix web test, pnpm -C web, make -C web, go -C web, mvn -f web, gradle -p web, or a tracked script; or sh -c 'cd web && npm test -- \"\$@\"' sh so the appended arguments reach the inner command), and list any other step in uncovered; $tail"
+  }
   nl='
 '
   before=
   redir=
-  stop=
   scan_rest=$value
   scan_piece=
   scan_kind=P
@@ -650,9 +697,22 @@ if [ "$field" = test ]; then
         scan_piece=$scan_piece$scan_c
         scan_dollar ;;
       '{'|'}'|'~') scan_kind=Q; scan_piece=$scan_piece$scan_c ;;
-      ' '|'	'|"$nl") flush ;;
+      ' '|'	') flush ;;
+      # A join or a group is refused on the Test entrypoint: a runner appends
+      # its arguments after the whole string, so they reach only the last
+      # command. An unquoted newline ends a command as `;` does. A
+      # redirection's own `&`, and the `<` or `>` itself, are not.
+      "$nl")
+        flush
+        joined newline ;;
       ';'|'&'|'|'|'('|')'|'<'|'>')
         flush
+        if [ -z "$redir" ]; then
+          case $scan_c in
+            '<'|'>') ;;
+            *) joined "'$scan_c'" ;;
+          esac
+        fi
         before=
         case $scan_c in '<'|'>') redir=1 ;; esac ;;
       *) scan_piece=$scan_piece$scan_c ;;
@@ -660,7 +720,7 @@ if [ "$field" = test ]; then
   done
   flush
   if [ -n "$scan_sq" ] || [ -n "$scan_ctx" ]; then
-    die "the Recipe cache at $cache is invalid: its test command leaves a quote, a backtick, a \$( or a \${ open, so sh cannot run it — a Recipe that cannot run is stale, not a finding; $derive"
+    die "$subj test command leaves a quote, a backtick, a \$( or a \${ open, so sh cannot run it — $stale; $tail"
   fi
 fi
 

package/scripts/fleet-tick.mjs

@@ -54,13 +54,13 @@
 //             whatever its state. Also, for each in-flight `review=` token
 //             whose PR the open list does not carry, and for each ticket's
 //             latest settled `impl-*=PR#<M>` PR the open list does not carry,
-//             that PR's state (`gh pr view`, once per PR): a review cannot
-//             be running against a finished PR, so its dangling token is not
-//             a review unit, and a PR CLOSED unmerged prints an ESCALATE line
-//             for its ticket. And, for each ticket holding the implementer
-//             row on a tier mismatch, owed a replacement, or whose keyed PR
-//             read CLOSED or unread, whether its issue is CLOSED (`gh issue
-//             view`): a closed ticket's mismatch holds nothing, its owed
+//             that PR's state (one `gh api graphql` read per hundred PRs): a
+//             review cannot be running against a finished PR, so its dangling
+//             token is not a review unit, and a PR CLOSED unmerged prints an
+//             ESCALATE line for its ticket. And, for each ticket holding the
+//             implementer row on a tier mismatch, owed a replacement, or whose
+//             keyed PR read CLOSED or unread, whether its issue is CLOSED (`gh
+//             issue view`): a closed ticket's mismatch holds nothing, its owed
 //             replacement is not in flight, and its PR prints no line.
 //   main      The main checkout against the run-start baseline
 //             `.fleet/main-checkout.sha`, through main-checkout.mjs.
@@ -958,7 +958,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
 export const pastPinDue = (st, head) => st !== undefined && st.pastPinHalt && !st.inFlight && st.reviewedHead !== null
   && !String(head).toLowerCase().startsWith(st.reviewedHead);
 
-// The states `gh pr view --json state` answers: anything else is no answer.
+// The states a PR-state probe answers: anything else is no answer.
 const PR_STATES = ["OPEN", "MERGED", "CLOSED"];
 
 export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed = new Set(), prStates = new Map()) {
@@ -1007,7 +1007,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed
   // A mismatch on the keyed member itself is no replacement of M and still
   // prints. A keyed PR the open list carries is normal flow; one it does not
   // is named in `prKeyed` for the caller's state probe, `prStates` its
-  // answers (null for a probe that could not answer, none by default).
+  // answers (none for a PR whose probe could not answer, as by default).
   // CLOSED escalates, an unanswered probe escalates as unchecked, OPEN and
   // MERGED say nothing, and a ticket whose issue the caller found CLOSED
   // (`closed`) says nothing either way.
@@ -1493,6 +1493,7 @@ import { isCLI } from "./is-cli.mjs";
 import { parseArgs } from "node:util";
 import { makeDie, isDigits } from "./arg.mjs";
 import { gitEnv } from "./git-env.mjs";
+import { ghAliasedRead } from "./gh-aliased-read.mjs";
 import { fleetFile, FleetDirUnresolvable, scratchRoot } from "./fleet-dir.mjs";
 import { statePath, readState, writeState, assessBeat, isStalled, isReported, stallReport, stallOwner } from "./fleet-state.mjs";
 import { checkMainCheckout, describe } from "./main-checkout.mjs";
@@ -1815,34 +1816,36 @@ function closedTickets(mismatched, owed, surfacing) {
   return closed;
 }
 
-// The state of each PR the tick asks gh about, one `gh pr view --json state`
-// per PR however many readings need it: `reviews`, the PRs whose review the
-// ledger reads as in flight yet the open list does not carry, and `keyed`,
-// each ticket's keyed PR the open list does not carry (deriveRun's
-// `prKeyed`). The answer is OPEN, MERGED or CLOSED, or null for a probe that
-// could not answer — a nonzero exit, a reply carrying no state, a state that
-// is none of the three — which is disclosed with what it leaves standing.
+// The state of each PR the tick asks gh about, one aliased `gh api graphql`
+// read per hundred PRs however many readings need them: `reviews`, the PRs
+// whose review the ledger reads as in flight yet the open list does not carry,
+// and `keyed`, each ticket's keyed PR the open list does not carry (deriveRun's
+// `prKeyed`). The answer is OPEN, MERGED or CLOSED. A probe that could not
+// answer — a failed call, an alias GitHub errored on or answered with nothing,
+// a node carrying no state, a state that is none of the three — leaves its PR
+// out of the map and is disclosed, per PR, with what it leaves standing; a
+// call killed at GH_TIMEOUT_MS is disclosed with that bound.
 function prStates(reviews, keyed) {
   const states = new Map();
   const reviewed = new Set(reviews);
   // Two tickets can be keyed on one PR: each is named, on its one probe.
   const ticketsOf = new Map();
   for (const k of keyed) ticketsOf.set(k.pr, [...(ticketsOf.get(k.pr) ?? []), k.n]);
-  for (const number of [...new Set([...reviews, ...ticketsOf.keys()])].sort((a, b) => a - b)) {
+  const numbers = [...new Set([...reviews, ...ticketsOf.keys()])].sort((a, b) => a - b);
+  const read = ghAliasedRead(numbers, { field: "pullRequest", selection: "{state}", timeoutMs: GH_TIMEOUT_MS });
+  for (const number of numbers) {
+    const r = read.get(number);
+    const st = r.node?.state;
+    if (PR_STATES.includes(st)) {
+      states.set(number, st);
+      continue;
+    }
     const unconfirmed = [
       ...(reviewed.has(number) ? [`review on PR#${number} unconfirmed finished, its unit stands`] : []),
       ...(ticketsOf.get(number) ?? []).map((n) => `#${n}'s PR#${number} unconfirmed closed, printed as pr-unchecked`),
     ].join("; ");
-    states.set(number, null);
-    const r = spawnSync("gh", ["pr", "view", String(number), "--json", "state"], { encoding: "utf8", timeout: GH_TIMEOUT_MS, env: gitEnv({ GH_REPO: "" }) });
-    if (r.error || r.status !== 0) {
-      console.error(`${NAME}: ${failure(r, `gh pr view ${number}`)} — ${unconfirmed}`);
-      continue;
-    }
-    let st = null;
-    try { st = JSON.parse(r.stdout).state; } catch { /* no state: disclosed below */ }
-    if (PR_STATES.includes(st)) states.set(number, st);
-    else console.error(`${NAME}: gh pr view ${number} printed no PR state — ${unconfirmed}`);
+    const why = r.unreachable === "ETIMEDOUT" ? TIMED_OUT : r.unreachable ?? (r.notFound ? "no such pull request" : "no PR state");
+    console.error(`${NAME}: gh api graphql gave no answer for PR#${number} (${why}) — ${unconfirmed}`);
   }
   return states;
 }

package/scripts/gh-aliased-read.mjs

@@ -0,0 +1,95 @@
+// One GraphQL read of the current repository for many numbers at once: each
+// number is an aliased `<field>(number:N){…}` of the one query, a hundred to a
+// call, so a caller that would ask `gh` about every number one `gh … view` at a
+// time asks once per hundred instead. The caller names the field
+// (`pullRequest`, `issueOrPullRequest`) and what to select on it; what an
+// answer means is the caller's.
+//
+// `gh api graphql` exits 1 when any one alias errors yet still prints the full
+// body, `data.repository` holding every alias GitHub answered and `errors[]`
+// naming each failed one by `path: ["repository", "<alias>"]`. So a body that
+// carries an object `data.repository` is read alias by alias at any exit
+// status, never as "the whole call failed".
+//
+// `-F owner={owner} -F name={repo}` is filled in from the environment gh sees:
+// an inherited GH_REPO outranks the repository the cwd is bound to, and a
+// GIT_DIR naming another repository moves it too. gitEnv({ GH_REPO: "" })
+// scrubs both, so the read is of the repository the cwd is in.
+
+import { spawnSync } from "node:child_process";
+import { gitEnv } from "./git-env.mjs";
+
+const BATCH = 100;
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+/** A child that did not answer, as one short reason. */
+export function how(r) {
+  if (r.error) return r.error.code ?? r.error.message;
+  if (r.signal) return `killed by ${r.signal}`;
+  const said = String(r.stderr ?? "").trim().split("\n").at(-1);
+  return said ? `exit ${r.status}: ${said}` : `exit ${r.status}`;
+}
+
+/**
+ * What GitHub says of each of `numbers`, as a Map keyed by number:
+ *
+ *   `{ node }`         — the alias GitHub answered with an object, as parsed.
+ *   `{ notFound }`     — null with a NOT_FOUND error naming the alias at path
+ *                        length 2: GitHub's own "this number names nothing".
+ *   `{ unreachable }`  — no usable answer, with the reason. Any other error
+ *                        naming an alias, an error naming no alias (it may
+ *                        belong to any of the batch), a null no NOT_FOUND
+ *                        explains, a missing alias, and an unparseable or
+ *                        absent body all land here: a failed lookup is not an
+ *                        answer.
+ *
+ * `field` and `selection` build each alias, `n<N>:<field>(number:<N>)<selection>`;
+ * `timeoutMs` bounds each `gh` call.
+ */
+export function ghAliasedRead(numbers, { field, selection, timeoutMs }) {
+  const out = new Map();
+  for (let i = 0; i < numbers.length; i += BATCH) {
+    const batch = numbers.slice(i, i + BATCH);
+    const fields = batch.map((n) => `n${n}:${field}(number:${n})${selection}`).join(" ");
+    const r = spawnSync("gh", ["api", "graphql", "-F", "owner={owner}", "-F", "name={repo}",
+      "-f", `query=query($owner:String!,$name:String!){repository(owner:$owner,name:$name){${fields}}}`], {
+      encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: timeoutMs, env: gitEnv({ GH_REPO: "" }),
+    });
+    let body;
+    let unparseable;
+    try {
+      body = JSON.parse(r.stdout);
+    } catch (e) {
+      if (r.status === 0) unparseable = e.message;
+    }
+    const repo = body?.data?.repository;
+    const errors = body?.errors ?? [];
+    const answered = repo !== null && typeof repo === "object" && !Array.isArray(repo) && Array.isArray(errors);
+    const nothing = new Set();
+    const refused = new Map();
+    let batchWide;
+    if (answered) {
+      for (const e of errors) {
+        const path = e?.path;
+        const alias = Array.isArray(path) && path[0] === "repository" && typeof path[1] === "string" ? path[1] : null;
+        const said = `${e?.type ?? "error"}${e?.message ? `: ${e.message}` : ""}`;
+        if (alias === null) batchWide ??= said;
+        else if (e.type === "NOT_FOUND" && path.length === 2) nothing.add(alias);
+        else refused.set(alias, said);
+      }
+    }
+    for (const n of batch) {
+      const alias = `n${n}`;
+      const gone = (why) => out.set(n, { unreachable: why });
+      if (!answered) gone(unparseable === undefined ? how(r) : `${how(r)}: unparseable body: ${unparseable}`);
+      else if (refused.has(alias)) gone(refused.get(alias));
+      else if (batchWide !== undefined) gone(batchWide);
+      else if (!Object.hasOwn(repo, alias)) gone(how(r));
+      else if (repo[alias] === null) {
+        if (nothing.has(alias)) out.set(n, { notFound: true });
+        else gone("null with no NOT_FOUND error");
+      } else out.set(n, { node: repo[alias] });
+    }
+  }
+  return out;
+}

package/scripts/recipe-prove.mjs

@@ -5,7 +5,7 @@
 // reads: the deriving agent chooses all three commands by reading the repository,
 // and this script is what turns that choice into a cache, or refuses to.
 //
-//   recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --uncovered <json>
+//   recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --covered <json> --uncovered <json>
 //                    [--count-line <literal> --test-count <n>]
 //                    [--mutate <cmd> --mutation <description>]
 //                    [--check-mutate <cmd> --check-mutation <description>]
@@ -17,6 +17,14 @@
 // required, so a cache never stays silent about a CI step left unrun; it is
 // written as given, as the cache's `uncovered`.
 //
+// `--covered` is one JSON array of `{ "step": <string>, "by": "test" | "check" }`,
+// one per merge-gating CI step that the Test entrypoint or the Check step runs:
+// "test" for a step the Test entrypoint runs, "check" for one the Check step
+// runs. At least one entry is "test"; "check" is never used with `--check true`;
+// and no step is in both `--covered` and `--uncovered`. Its shape is checked
+// before any command runs, and it is never written to the cache: nothing here
+// can check which steps a command runs.
+//
 // Every check runs in a throwaway worktree of `origin/main`, detached and
 // removed afterwards, so neither the caller's checkout nor its uncommitted
 // state takes part — `derivedAt` is the commit the proof ran against:
@@ -102,7 +110,7 @@ import { isDigits } from "./arg.mjs";
 
 const NAME = "recipe-prove";
 const USAGE =
-  "usage: recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --uncovered <json> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>] [--check-mutate <cmd> --check-mutation <description>]";
+  "usage: recipe-prove.mjs <repo> --install <cmd> --check <cmd|true> --test <cmd> --covered <json> --uncovered <json> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>] [--check-mutate <cmd> --check-mutation <description>]";
 const READER = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
 
 // Scrubbed once, for every child: an ambient GIT_DIR or GIT_WORK_TREE — set
@@ -155,7 +163,7 @@ const READER_COULD_NOT_RUN = 3;
 function parseArgs(argv) {
   const [repo, ...rest] = argv;
   if (!repo || repo.startsWith("--")) throw cannot(USAGE);
-  const flags = new Set(["--install", "--check", "--test", "--uncovered", "--count-line", "--test-count", "--mutate", "--mutation", "--check-mutate", "--check-mutation"]);
+  const flags = new Set(["--install", "--check", "--test", "--covered", "--uncovered", "--count-line", "--test-count", "--mutate", "--mutation", "--check-mutate", "--check-mutation"]);
   const a = {};
   for (let i = 0; i < rest.length; i += 2) {
     const [flag, value] = [rest[i], rest[i + 1]];
@@ -169,6 +177,7 @@ function parseArgs(argv) {
     if (!a[f] || !a[f].trim()) throw cannot(`${f} needs a non-empty command — ${USAGE}`);
   }
   if (!("--uncovered" in a)) throw cannot(`--uncovered is required: the merge-gating CI steps neither the Test entrypoint nor the Check step runs, as one JSON array, \`[]\` for none — ${USAGE}`);
+  if (!("--covered" in a)) throw cannot(`--covered is required: the merge-gating CI steps the Test entrypoint or the Check step runs, one JSON array of { step, by } with by "test" or "check" — ${USAGE}`);
   const uncovered = parseUncovered(a["--uncovered"]);
   if (("--count-line" in a) !== ("--test-count" in a)) throw cannot("--count-line and --test-count go together");
   if ("--test-count" in a && !isDigits(a["--test-count"])) {
@@ -189,6 +198,7 @@ function parseArgs(argv) {
     if (!("--check-mutate" in a) || !a["--check-mutate"].trim()) throw cannot(`a Check step other than \`true\` needs --check-mutate, the command that turns it red — ${USAGE}`);
     if (!a["--check-mutation"].trim()) throw cannot("--check-mutation needs a non-empty description");
   }
+  checkCovered(a["--covered"], uncovered, a["--check"]);
   return {
     repo,
     install: a["--install"],
@@ -204,18 +214,20 @@ function parseArgs(argv) {
   };
 }
 
+function parseFlagJson(flag, json) {
+  try {
+    return JSON.parse(json);
+  } catch (e) {
+    throw cannot(`${flag} is not JSON: ${e.message}`);
+  }
+}
+
 // The same rule derive-testcmd.sh holds the cache to, applied before any
 // command runs, so a malformed list is a usage error rather than a proof that
 // held and a cache the reader then refuses.
 function parseUncovered(json) {
-  let list;
-  try {
-    list = JSON.parse(json);
-  } catch (e) {
-    throw cannot(`--uncovered is not JSON: ${e.message}`);
-  }
+  const list = parseFlagJson("--uncovered", json);
   if (!Array.isArray(list)) throw cannot("--uncovered is not a JSON array of { step, reason } entries, `[]` for none");
-  const filled = (s) => typeof s === "string" && s.trim() !== "";
   list.forEach((u, i) => {
     if (u === null || typeof u !== "object" || Array.isArray(u) || !filled(u.step) || !filled(u.reason)) {
       throw cannot(`--uncovered entry ${i + 1} is not an object with a non-empty \`step\` and \`reason\``);
@@ -224,6 +236,43 @@ function parseUncovered(json) {
   return list;
 }
 
+const filled = (s) => typeof s === "string" && s.trim() !== "";
+const normStep = (s) => s.trim().replace(/\s+/g, " ");
+
+// The ledger of CI steps the Test entrypoint or the Check step runs: a JSON
+// array of { step, by }, `by` exactly "test" or "check". Checked here, before
+// any command runs, and never written to the cache: nothing can check which
+// steps a command runs, only that the ledger is well-formed and agrees with
+// `uncovered` about what it leaves out.
+function checkCovered(json, uncovered, check) {
+  const list = parseFlagJson("--covered", json);
+  if (!Array.isArray(list)) throw cannot(`--covered is not a JSON array of { step, by } entries — ${USAGE}`);
+  list.forEach((c, i) => {
+    if (c === null || typeof c !== "object" || Array.isArray(c) || !filled(c.step) || (c.by !== "test" && c.by !== "check")) {
+      throw cannot(`--covered entry ${i + 1} is not an object with a non-empty \`step\` and a \`by\` of exactly "test" or "check"`);
+    }
+  });
+  if (!list.some((c) => c.by === "test")) throw cannot(`--covered names no step with by "test": the Test entrypoint runs at least one merge-gating CI step, or there is nothing to prove`);
+  if (check === "true" && list.some((c) => c.by === "check")) throw cannot(`--covered names a step with by "check", but --check is true, so no Check step runs`);
+  const listed = new Set(uncovered.map((u) => normStep(u.step)));
+  const both = list.find((c) => listed.has(normStep(c.step)));
+  if (both) throw cannot(`the step '${both.step}' is in both --covered and --uncovered: a step that runs is never listed as uncovered`);
+}
+
+// The reader's shape check, before any command runs: `--propose` holds a
+// proposed command to the rules the cache is held to, with no cache read and no
+// command run, so one the cache would refuse is refused before the proof.
+function preflight(field, command, repo, at) {
+  const args = [READER, "--propose", repo, field, command, ...(field === "test" ? ["--at", at] : [])];
+  const r = spawnSync("sh", args, { env: ENV, encoding: "utf8" });
+  if (r.error && !r.pid) throw cannot(`could not start sh to check the ${field} command: ${r.error.message}`);
+  if (r.signal) throw cannot(`the reader's sh was killed by ${r.signal}${errorCause(r.error)}, so the ${field} command was not checked`);
+  if (r.status === 0) return;
+  if (r.status === READER_COULD_NOT_RUN) throw cannot(`${r.stderr.trim()} — the reader could not run a tool it needs, so the ${field} command was not checked`);
+  if (r.status === 1) throw notProven(r.stderr.trim() || `the reader refused the ${field} command and said nothing`);
+  throw cannot(`the reader exited ${r.status} checking the ${field} command: ${r.stderr.trim()}`);
+}
+
 // A git that cannot be started is no verdict, as for `sh` below: read as a
 // failed git command, it would surface as whatever that command's failure
 // means to its caller — a missing repository, an unfetched origin/main, a
@@ -534,6 +583,9 @@ function main(argv) {
   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 (${sha.err}) — fetch it; the proof runs against it`);
+  // Each command's shape is checked before any command runs, and before the
+  // proof's worktree exists: a command the cache reader would refuse is refused here.
+  for (const field of ["install", "check", "test"]) preflight(field, o[field], o.repo, sha.out);
 
   const logs = mkdtempSync(join(tmpdir(), `${NAME}-`));
   const cache = join(workspace, ".fleet", "recipe.json");

package/scripts/reclaim-scratch.mjs

@@ -109,6 +109,7 @@ import { fileURLToPath } from "node:url";
 import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
 import { fleetFile, FleetDirUnresolvable, SCRATCH_KEY_SHAPE, scratchRoot } from "./fleet-dir.mjs";
 import { gitEnv } from "./git-env.mjs";
+import { ghAliasedRead, how } from "./gh-aliased-read.mjs";
 import { isCLI } from "./is-cli.mjs";
 import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
 
@@ -116,7 +117,6 @@ const NAME = "reclaim-scratch";
 const die = makeDie(NAME);
 const DAY_MS = 24 * 60 * 60 * 1000;
 export const RETENTION_MS = 7 * DAY_MS;
-const BATCH = 100;
 const GH_TIMEOUT_MS = 30_000;
 const MAX_BUFFER = 64 * 1024 * 1024;
 
@@ -151,13 +151,6 @@ const REPORT_PR_ENTRY = /^(?:fix-pr|finisher-pr|review-pr)-([1-9][0-9]*)(?:-[a-z
 const REPORT_IMPL_ENTRY = /^impl-([1-9][0-9]*)(?:-[a-z])?(?:\.check)?\.json$/;
 const RUN_ROOT = /^run-/;
 
-function how(r) {
-  if (r.error) return r.error.code ?? r.error.message;
-  if (r.signal) return `killed by ${r.signal}`;
-  const said = String(r.stderr ?? "").trim().split("\n").at(-1);
-  return said ? `exit ${r.status}: ${said}` : `exit ${r.status}`;
-}
-
 /** The path of something under `path` (itself included) modified at or after
  * `cutoff`, or null when everything is older. Symlinks are not followed. A
  * directory that cannot be listed counts its own mtime only, and so does one
@@ -302,59 +295,18 @@ function claimWorktree(listing, n) {
 
 // `{type, state}` per number GitHub answered (type "Issue" or "PullRequest",
 // or null for a number that names nothing), or `{unreachable}` for a number
-// that has no usable answer. GitHub resolves every alias it can and nulls the
-// rest, and gh exits 1 with the whole body, so a body carrying an object
-// `data.repository` is read alias by alias at any exit status. An alias is
-// answered by a node, or by null with a NOT_FOUND error naming it — GitHub's
-// own "this number names nothing". Any other error naming an alias, a null
-// no NOT_FOUND explains, and an error naming no alias (it may belong to any
-// of the batch) leave the number unreachable: a failed lookup is not an
-// answer.
+// that has no usable answer. What counts as an answer is gh-aliased-read.mjs's:
+// a number GitHub nulls with NOT_FOUND names nothing, and a failed lookup is
+// not an answer.
 function githubStates(numbers) {
   const out = new Map();
-  for (let i = 0; i < numbers.length; i += BATCH) {
-    const batch = numbers.slice(i, i + BATCH);
-    const fields = batch.map((n) => `n${n}:issueOrPullRequest(number:${n}){__typename ... on Issue{state} ... on PullRequest{state}}`).join(" ");
-    const r = spawnSync("gh", ["api", "graphql", "-F", "owner={owner}", "-F", "name={repo}",
-      "-f", `query=query($owner:String!,$name:String!){repository(owner:$owner,name:$name){${fields}}}`], {
-      encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv({ GH_REPO: "" }),
-    });
-    let body;
-    let unparseable;
-    try {
-      body = JSON.parse(r.stdout);
-    } catch (e) {
-      body = undefined;
-      if (r.status === 0) unparseable = e.message;
-    }
-    const repo = body?.data?.repository;
-    const errors = body?.errors ?? [];
-    const answered = repo !== null && typeof repo === "object" && !Array.isArray(repo) && Array.isArray(errors);
-    const nothing = new Set();
-    const refused = new Map();
-    let batchWide;
-    if (answered) {
-      for (const e of errors) {
-        const path = e?.path;
-        const alias = Array.isArray(path) && path[0] === "repository" && typeof path[1] === "string" ? path[1] : null;
-        const said = `${e?.type ?? "error"}${e?.message ? `: ${e.message}` : ""}`;
-        if (alias === null) batchWide ??= said;
-        else if (e.type === "NOT_FOUND" && path.length === 2) nothing.add(alias);
-        else refused.set(alias, said);
-      }
-    }
-    for (const n of batch) {
-      const alias = `n${n}`;
-      const gone = (why) => out.set(n, { unreachable: `gh api graphql gave no answer for #${n} (${why})` });
-      if (!answered) gone(unparseable === undefined ? how(r) : `${how(r)}: unparseable body: ${unparseable}`);
-      else if (refused.has(alias)) gone(refused.get(alias));
-      else if (batchWide !== undefined) gone(batchWide);
-      else if (!Object.hasOwn(repo, alias)) gone(how(r));
-      else if (repo[alias] === null) {
-        if (nothing.has(alias)) out.set(n, { type: null });
-        else gone("null with no NOT_FOUND error");
-      } else out.set(n, { type: repo[alias].__typename, state: String(repo[alias].state).toUpperCase() });
-    }
+  const read = ghAliasedRead(numbers, {
+    field: "issueOrPullRequest", selection: "{__typename ... on Issue{state} ... on PullRequest{state}}", timeoutMs: GH_TIMEOUT_MS,
+  });
+  for (const [n, r] of read) {
+    if (r.unreachable !== undefined) out.set(n, { unreachable: `gh api graphql gave no answer for #${n} (${r.unreachable})` });
+    else if (r.notFound) out.set(n, { type: null });
+    else out.set(n, { type: r.node.__typename, state: String(r.node.state).toUpperCase() });
   }
   return out;
 }

package/skills/run-team/references/tick-rows.md

@@ -95,8 +95,8 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
   carried on at the right tier — and once that one settles, the line reads it
   the same way. A tier mismatch on the member that settled `PR#<M>` itself
   replaces nothing, so the line stands beside that hold.
-- `ESCALATE pr-unchecked #<N> PR#<M>` — the same ticket, but `gh pr view
-  <M>` could not answer, so whether M closed is unknown. The maintainer's on
+- `ESCALATE pr-unchecked #<N> PR#<M>` — the same ticket, but gh could not
+  answer for PR M, so whether M closed is unknown. The maintainer's on
   the same terms as `pr-closed`; the next tick probes again.
 - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
   unchecked tier, the In-flight bound reached (`HOLD (in-flight <n>/<B>)` —