@feigi/fleet-ctl 3.76.5 → 3.76.7

package/package.json

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

package/scripts/fleet-tick.mjs

@@ -104,16 +104,20 @@
 //             up; a member with no schema is never checked against one.
 //   pulls     `<scratch>/impl-<N>/pull.json`, pull.mjs's record of a Pull, for
 //             every head on the shortlist, `<scratch>` as for the report
-//             files. A question standing prints `PULL #<N> (Q<n> pending —
-//             pull.mjs answer <N> <qid> …)` in place of the fresh row, with
-//             ` (stale)` once the file is older than `--pull-stale-minutes`; a
-//             Pull that dispatched with the head still holding no `impl-` row
-//             prints `(dispatched, row missing — ledger.mjs row …)`. A Pull
-//             that ended in this run's session (the ticket left, or its claim
-//             was released) names no row: `pull.mjs next` skips it, `next
-//             --head` would start the ticket over, so the next head fills the
-//             slot. A record from another phase-0 session, or one unreadable
-//             or absent, is the fresh row: `pull.mjs next` starts or resumes it.
+//             files: read before the refresh is judged, and again for the
+//             heads a refresh replaced them with. A question standing prints
+//             `PULL #<N> (Q<n> pending — pull.mjs answer <N> <qid> …)` in
+//             place of the fresh row, with ` (stale)` once the file is older
+//             than `--pull-stale-minutes`; a Pull that dispatched with the
+//             head still holding no `impl-` row prints `(dispatched, row
+//             missing — ledger.mjs row …)`. A Pull that ended in this run's
+//             session (the ticket left, or its claim was released) names no
+//             row: `pull.mjs next` skips it, `next --head` would start the
+//             ticket over, so the next head fills the slot. Nor is it counted
+//             in `unclaimed=` or toward the short-queue refresh, so a
+//             shortlist of ended heads refreshes. A record from another
+//             phase-0 session, or one unreadable or absent, is the fresh row:
+//             `pull.mjs next` starts or resumes it.
 //   session   The listing of the session directory omp writes one
 //             `<member>.jsonl` transcript into per dispatched member: this
 //             run's phase-0 receipt's `session`, else `--session`; with
@@ -278,12 +282,23 @@ function pullAction(n, p) {
   return `PULL #${n} — pull.mjs next --head ${n}`;
 }
 
+// The heads a PULL row could name: a head whose Pull ended in this run takes
+// no slot, and the next head takes it. Order kept, so the slots fill oldest first.
+function pullable(heads, pulls) {
+  return heads.filter((n) => pulls?.get(n)?.kind !== "ended");
+}
+
 // The implementer rows: one per head a free slot Pulls, else the one row
-// saying why none is pulled.
+// saying why none is pulled. `unclaimed=` counts the heads a PULL row could
+// name. A refresh whose trigger text names a count carries it as `unclaimed`,
+// and the row prints that count, not the refreshed file's: one tick never
+// prints two different counts.
 function implementers(s) {
   const dropped = specsDropped(s.dropped);
+  const heads = pullable(s.heads, s.pulls);
+  const counted = s.refresh?.unclaimed ?? heads.length;
   const one = mkRow("implementers", s.inFlight, s.bound,
-    `implementers=${s.inFlightImpl} prs=${s.inFlightPrs} unclaimed=${s.heads.length} supply=${s.supply ?? "?"}`
+    `implementers=${s.inFlightImpl} prs=${s.inFlightPrs} unclaimed=${counted} supply=${s.supply ?? "?"}`
     + (s.shortlistStatus === "ok" ? "" : ` shortlist=${s.shortlistStatus}`)
     + (dropped ? ` ${dropped}` : ""));
   const row = (...a) => [one(...a)];
@@ -323,9 +338,7 @@ function implementers(s) {
     return s.owedCounted.length ? row(hold, { acts: true, extra: replaceStep(s.owedCounted, s.implNames) }) : row(hold);
   }
 
-  // A head whose Pull ended in this run takes no slot: the next head does.
-  const pullable = s.heads.filter((n) => s.pulls?.get(n)?.kind !== "ended");
-  if (pullable.length) return pullable.slice(0, s.bound - s.inFlight).map((n) => one(pullAction(n, s.pulls?.get(n)), { acts: true }));
+  if (heads.length) return heads.slice(0, s.bound - s.inFlight).map((n) => one(pullAction(n, s.pulls?.get(n)), { acts: true }));
 
   // Nothing to Pull even after a refresh: no unclaimed head, or only heads
   // whose Pull ended in this run, which `pull.mjs next` skips. `SUGGEST /triage` asks a
@@ -1138,7 +1151,9 @@ export function parseShortlist(text) {
   };
 }
 
-// Why this tick refreshes the shortlist, or null. The premise-lifted
+// Why this tick refreshes the shortlist, or null. `unclaimed` counts the
+// heads a PULL row could name, so a head whose Pull ended in this run is not
+// in it. The premise-lifted
 // trigger costs gh calls, so main() asks it only when these answer null.
 // Nothing refreshes while the bound holds (`held`, n ≥ B, whichever HOLD row
 // prints): a refresh then cannot feed a Pull, and the first tick back under
@@ -1147,10 +1162,15 @@ export function refreshWhy({ draining, held, status, entries, unclaimed: k, boun
   if (draining !== null || held) return null;
   if (status !== "ok") return `shortlist ${status}`;
   if (entries === 0) return "shortlist empty";
-  if (k < bound) return `unclaimed ${k} < in-flight bound ${bound}`;
+  if (k < bound) return shortQueue(k, bound);
   return null;
 }
 
+// The short-queue trigger's text, the one trigger that names a count.
+function shortQueue(k, bound) {
+  return `unclaimed ${k} < in-flight bound ${bound}`;
+}
+
 // How long, in minutes, a live token of each family may run before the tick
 // asks the controller to look at it. Each default is that family's p99
 // run time: a token past it is rare among members that finished, so a line
@@ -2046,49 +2066,58 @@ function main() {
     if (unchecked.length && applyTierChecks(unchecked, phase0.session)) run = readRun(prs);
   }
 
+  // The scratch root of the report files and the Pull records alike.
+  const scratch = reportsScratch(receipt, scratchFlag);
+  if (scratch === null) console.error(`${NAME}: report files and Pull records not checked — no scratch in the phase-0 receipt and no --scratch`);
+  // Each head's Pull record read, not only the heads a free slot names: a head
+  // whose Pull ended gives its slot to the next, so the heads past the slots
+  // can fill one. The session it is judged against is the receipt's, as
+  // pull.mjs judges it.
+  const runSession = receipt.read.state === "ok" && receipt.read.receipt.session !== "" ? receipt.read.receipt.session : null;
+  const pullsOf = (hs) => scratch === null ? new Map()
+    : readPulls(scratch.root, hs, { session: runSession, now: Date.now(), staleMinutes: pullStaleMinutes });
+
   // Pull from the current file first; refresh when it is short, absent, an
   // exclusion has lifted, or a branch-named or issue one still names a ticket on it.
   // A refresh that succeeds replaces the heads outright: the PULL is read off
   // what shortlist.mjs just probed, never merged with the file's own heads,
   // or a ticket the refresh dropped would be pulled anyway.
   let heads = unclaimed(current.entries, run);
+  let pulls = pullsOf(heads);
   let supply = current.scanned;
   let dropped = current.dropped;
   let fresh = null;
+  // Short means fewer heads than B that a PULL row could name: `pull.mjs next`
+  // skips a head whose Pull ended in this run, so counting it would hold back
+  // the refresh that finds the head to take its slot.
+  const counted = pullable(heads, pulls).length;
   // While the bound holds a refresh cannot feed a Pull, so none of its
   // triggers runs: the first tick back under the bound refreshes and Pulls in
   // the same tick.
   const held = run.inFlight >= caps.bound;
   const trigger = refreshWhy({ draining: run.draining, held, status: current.status, entries: current.entries.length,
-    unclaimed: heads.length, bound: caps.bound })
+    unclaimed: counted, bound: caps.bound })
     ?? (run.draining === null && !held ? liftedPremise(run.excluded, current.entries, prs) : null);
   if (trigger) {
     const r = refresh();
     if (r.ok) {
       const excludedSet = new Set(run.excluded.map((x) => x.n));
       heads = unclaimed(r.entries, run);
+      pulls = pullsOf(heads);
       supply = r.scanned;
       dropped = r.dropped;
       fresh = {
         ok: true, trigger, entries: r.entries.length,
         lifted: r.entries.filter((e) => excludedSet.has(e.n)).length,
         changed: r.entries.map((e) => e.n).join(",") !== current.entries.map((e) => e.n).join(","),
+        // The count this trigger's text names, which the implementer row prints in place of the refreshed file's.
+        ...(trigger === shortQueue(counted, caps.bound) ? { unclaimed: counted } : {}),
       };
     } else {
       fresh = { ok: false, trigger, why: r.why };
     }
   }
 
-  // The scratch root of the report files and the Pull records alike.
-  const scratch = reportsScratch(receipt, scratchFlag);
-  if (scratch === null) console.error(`${NAME}: report files and Pull records not checked — no scratch in the phase-0 receipt and no --scratch`);
-  // Each head's Pull record read, not only the heads a free slot names: a head
-  // whose Pull ended gives its slot to the next, so the heads past the slots
-  // can fill one. The session it is judged against is the receipt's, as
-  // pull.mjs judges it.
-  const runSession = receipt.read.state === "ok" && receipt.read.receipt.session !== "" ? receipt.read.receipt.session : null;
-  const pulls = scratch === null ? new Map()
-    : readPulls(scratch.root, heads, { session: runSession, now: Date.now(), staleMinutes: pullStaleMinutes });
   const rows = reconcile({
     ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router, pulls,
   });

package/scripts/tier-check.mjs

@@ -22,8 +22,10 @@
 //      readers — a member with no assistant turn yet still resolves off its
 //      dispatch-time `session_init` record, never treated as absent). An
 //      entry that names neither a `session` nor a `transcript` takes the
-//      `session` the phase-0 receipt `.fleet/phase0.json` records, and is
-//      exit 2 naming the receipt when it records none. That session is taken
+//      `session` the phase-0 receipt `.fleet/phase0.json` records — the one
+//      in the workspace holding `--ledger`, or the cwd's when `--ledger` is
+//      omitted, resolved the same way the default ledger is — and is exit 2
+//      naming the receipt when it records none. That session is taken
 //      as the receipt stands: whether the receipt is this run's is judged by
 //      fleet-tick.mjs's phase-0 gate, not here, and a message about it names
 //      the receipt's session where it would name `--session`.
@@ -77,14 +79,16 @@
 // LIVE member may yet write one; a member settled `PR#M`, `bailed`, `blocked`
 // or `tier-mismatch` ran, so its transcript exists and the `session` is the
 // wrong directory; a `session` that is empty, missing or not a directory,
-// or omitted with none in the phase-0 receipt, is exit 2 whether the member
-// is live or settled; and a session
+// or omitted with none in the phase-0 receipt — a `--ledger` outside any
+// repository or in a directory that does not exist among them, since no
+// workspace holds it and so there is no receipt to read — is exit 2 whether
+// the member is live or settled; and a session
 // directory that cannot be searched (EACCES) is exit 2 naming the errno,
 // never read as holding no transcript.
 
 import { readFileSync, existsSync, statSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { join, dirname, isAbsolute } from "node:path";
+import { join, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isCLI } from "./is-cli.mjs";
 import { makeDie, defineFlags } from "./arg.mjs";
@@ -328,6 +332,19 @@ function sessionLacksTranscript(repoRoot, sessionPath, member) {
 // tier can still be judged.
 const NO_TRANSCRIPT_OUTCOMES = new Set(["killed", "released"]);
 
+// Where the phase-0 receipt is read from: the workspace the ledger in use
+// belongs to, so a `--ledger` naming another workspace's judges that
+// workspace's transcripts, not the cwd's. `--ledger` takes any path, not
+// always one under a `.fleet/` — so the workspace is the one git names for
+// the ledger's directory, the same answer ledger.mjs's own default gives
+// from the cwd. A ledger under no repository, or in a directory that does not
+// exist, has no workspace and so no receipt: sessionFromReceipt refuses
+// naming why, and the whole batch is exit 2 with nothing written. Omitted,
+// the cwd's.
+function receiptOpts(ledgerFile) {
+  return ledgerFile ? { cwd: dirname(resolve(ledgerFile)) } : undefined;
+}
+
 function runLedger(ledgerFile, args, what) {
   try {
     return execFileSync(process.execPath, [LEDGER_SCRIPT, ...(ledgerFile ? ["--file", ledgerFile] : []), ...args], { encoding: "utf8" });
@@ -480,7 +497,7 @@ function main() {
         // session directory the phase-0 receipt records — read once per
         // batch — and refuses naming the receipt when it records none. A
         // given one always wins.
-        const session = raw.session ?? (raw.transcript ? undefined : (receiptSession ??= sessionFromReceipt()));
+        const session = raw.session ?? (raw.transcript ? undefined : (receiptSession ??= sessionFromReceipt(receiptOpts(ledgerFile))));
         // Said as the caller's flag only when the caller gave it.
         const where = raw.session ? `--session ${session}` : `the phase-0 receipt's session ${session}`;
         if (session) {

package/skills/run-team/SKILL.md

@@ -147,7 +147,8 @@ phase, or in any later one, asks the maintainer which tickets to take.
    lifted, and when a branch-named `behind-pr` exclusion whose PR is not yet
    MERGED or CLOSED, or a `behind-issue` exclusion whose issue is not yet
    closed, names a ticket the file still carries, and prints
-   `REFRESHED shortlist: <n> entries; <k> lifted`. Phase 0 runs it by hand
+   `REFRESHED shortlist: <n> entries; <k> lifted`. A head whose Pull ended
+   this run is not counted. Phase 0 runs it by hand
    once because a dead run's shortlist is stale by definition.
    None of those triggers runs while `HOLD (in-flight <n>/<B>)` stands
    (**Queue depth**).
@@ -249,6 +250,7 @@ unclaimed count is below the In-flight bound, when the file is missing or
 empty, when an Exclusion's premise has lifted, or when a branch-named
 `behind-pr` or a `behind-issue` Exclusion still not lifted names a ticket the
 file carries — never while the bound holds; the open PRs come off `gh`. A
+head whose Pull ended this run is not counted. A
 ledger token it
 cannot read, it refuses rather than guessing — a member counted live or gone on
 a guess is the over- or under-dispatch it exists to prevent — so correct that
@@ -738,10 +740,11 @@ dispatched under.
 Pull, a batch of one, the member just dispatched: `{member}`.
 `member` is the AgentId the dispatch returns (`impl-<N>`). An entry that
 names neither `session` nor `transcript` takes the session directory phase
-0's receipt `.fleet/phase0.json` records, and is exit 2 naming the receipt
-when it records none; the check reads the member's own
-`<session>/<member>.jsonl` directly, so a member with no assistant turn yet
-still resolves off its dispatch-time record. A `session` the entry gives
+0's receipt `.fleet/phase0.json` of `--ledger`'s workspace (else the cwd's,
+resolved as the default ledger is) records, and is exit 2 naming the receipt
+when it records none; the check reads `<session>/<member>.jsonl`, so a
+member with no assistant turn yet still resolves off its dispatch-time
+record. A `session` the entry gives
 wins over the receipt's; a caller already holding the exact transcript path
 may give `transcript` instead. The agent type an implementer was dispatched
 as lives only in its transcript. `resolvedModel`
@@ -2110,6 +2113,8 @@ Read the depth off the tick and never derive it by hand: act on the row it print
 
 - **shortlist** — `.fleet/shortlist.json`'s entries with no `impl-` row and no
   live `excluded` row: admissible, not yet pulled. The tick's `unclaimed=`.
+  Not after a refresh at unclaimed < B (below). A head whose Pull ended this
+  run is not counted.
 - **supply** — `scanned`, the open `ready-for-agent` tickets `shortlist.mjs`'s
   candidate scan returned, before any filter. Only a Pull's full read judges
   decided?, so a shortlist of undecided tickets is supply that every Pull
@@ -2149,18 +2154,12 @@ Read the depth off the tick and never derive it by hand: act on the row it print
 
 **The review backlog never gates, and the merge-queue depth is still no
 signal.** The only gate on a Pull is the In-flight count. A deep backlog is a
-`DISPATCH review` on the same tick, never a reason to idle an implementer. A
-deep `ready-to-merge` queue adds no rebases per PR — each PR rebases exactly
-once, when it becomes the candidate — and those PRs count as In flight because
-they sit between Claim and merge, not because the queue is deep.
-
-**Reconcile, do not wait for an event.** "A slot is free and the shortlist is
-non-empty" is a *level* condition — re-derive the deficit on **every** tick,
-whatever woke you: a member finishing, a member bailing before implementing, a
-merge landing. An edge-triggered loop that only Pulls on completion stalls
-silently the moment the shortlist empties, because 0 implementers emit no
-completion event. With the shortlist empty the table below governs — refresh,
-and never Pull a ticket the shortlist does not hold.
+`DISPATCH review` on the same tick, never a reason to idle an implementer.
+For the merge queue, see references/pull.md.
+
+**Reconcile, do not wait for an event.** With the shortlist empty the table
+below governs — refresh, and never Pull a ticket the shortlist does not hold.
+See references/pull.md.
 
 **Do not re-derive this by hand — `fleet-tick.mjs` computes it.** One invocation
 prints per-role `actual/target` and an explicit ACTION with the backlog gate
@@ -2170,7 +2169,9 @@ the whole point: a table you must remember to consult is one you will not
 consult under a merge-side event storm, and that is how implementers reached
 0/target with one approved ticket waiting and ~57 `ready-for-agent` in supply while nobody
 noticed (#3). What follows stays here as the explanation of what the script decides —
-never as a second, hand-run copy of it.
+never as a second, hand-run copy of it. The table's shortlist counts no head
+whose Pull ended this run. A refresh at unclaimed < B leaves `unclaimed=` at
+that count, so `SUGGEST /triage` can print it above 0.
 
 | shortlist (unclaimed) | implementer row prints |
 |---|---|
@@ -2186,7 +2187,8 @@ awaiting to-tickets, so an empty shortlist carrying one is not "no work".
 
 The refresh runs at unclaimed < B and, with every other refresh trigger, never
 while the bound holds: a refresh then cannot feed a Pull, and the first tick
-back under the bound refreshes and Pulls in the same tick.
+back under the bound refreshes and Pulls in the same tick. Unclaimed there
+counts no head whose Pull ended this run.
 
 Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
 recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is

package/skills/run-team/references/pull.md

@@ -435,3 +435,16 @@ raising B past that buys nothing. 8 was rejected: peak review concurrency above
 the former reviewer count, for a throughput gain the backlog does not show it
 needs. Re-derive it from the map's guard once 20 or more PRs have merged under
 it, never from one run's rows.
+
+A deep `ready-to-merge` queue adds no rebases per PR — each PR rebases exactly
+once, when it becomes the candidate — and those PRs count as In flight because
+they sit between Claim and merge, not because the queue is deep.
+
+## Reconcile, do not wait for an event
+
+"A slot is free and the shortlist is
+non-empty" is a *level* condition — re-derive the deficit on **every** tick,
+whatever woke you: a member finishing, a member bailing before implementing, a
+merge landing. An edge-triggered loop that only Pulls on completion stalls
+silently the moment the shortlist empties, because 0 implementers emit no
+completion event.

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

@@ -8,9 +8,14 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
 - `REFRESHED shortlist: <n> entries; <k> lifted` — the tick refreshed the
   shortlist itself, and its `PULL` row already reads the result. `REFRESH
   FAILED` is yours: `shortlist.mjs` could not run, and the implementer row is
-  blind until it can.
+  blind until it can. When the refresh ran because fewer than B heads were
+  unclaimed (`unclaimed <u> < in-flight bound <B>`), a head whose Pull ended
+  this run not counted, the implementer row's `unclaimed=` prints that same
+  `<u>`, not the refreshed file's count.
 - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
-  Suggest, never run (**Queue depth**).
+  Suggest, never run (**Queue depth**). A head whose Pull already ended in
+  this run is not counted toward the refresh, so a shortlist of only such
+  heads triggers the refresh before this row prints.
 - `specs-dropped=#<N> … (to-spec: User Stories heading)` at the end of the
   implementer row's counts, whatever its ACTION — the tickets the to-spec
   filter kept out of `supply`, read off the shortlist's `dropped`. Never