@feigi/fleet-ctl 3.82.12 → 3.82.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.82.12",
+  "version": "3.82.13",
   "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

@@ -118,7 +118,10 @@
 //             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
+//             shortlist of ended heads refreshes. A Pull that left on an
+//             exclusion (its reason starts `excluded ·`) is no such end: its
+//             head is counted and Pulled again once the exclusion lifts. 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
@@ -139,7 +142,7 @@
 // the ledger; main() does the I/O. Split so the guard table and the reading are
 // both unit-testable without a network.
 
-import { parseMember, parseToken, premisesOf, rowNums, nextRetry, readRetired, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
+import { parseMember, parseToken, premisesOf, rowNums, nextRetry, readRetired, pullEnded, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
 
 // The implementer and reviewer rows' TARGET is the In-flight bound; the merge
 // bot's is 1. Availability of work belongs in the ACTION, not the target: a
@@ -273,8 +276,10 @@ const QUESTION_NUMBERS = { staleness: "Q1", close: "Q1b", decided: "Q2", collisi
  * PULL row: `{kind: "pending", qid, stale}`, `{kind: "dispatched", text}` with
  * the text the Pull's own `ledger.mjs row` wrote (null when it recorded none),
  * `{kind: "ended"}` for a Pull that left or was released, or null for the
- * fresh row. `since` is the file's mtime and `session` this run's phase-0
- * session, null when the receipt names none.
+ * fresh row. A Pull that left on an Exclusion (its reason starts `excluded ·`)
+ * is the fresh row too: it is no end, since the head claims a PULL row again
+ * once the tick's own lift logic admits it. `since` is the file's mtime and
+ * `session` this run's phase-0 session, null when the receipt names none.
  */
 export function pullOf(record, { session, since, now, staleMinutes }) {
   if (record === null || typeof record !== "object" || Array.isArray(record)) return null;
@@ -283,7 +288,14 @@ export function pullOf(record, { session, since, now, staleMinutes }) {
   if (session !== null && record.session !== session) return null;
   // pull.mjs's `next` skips a Pull that ended in this run, and `next --head`
   // would start the ticket over: the head is no one for a PULL row to name.
-  if (record.status === "left" || record.status === "released") return { kind: "ended" };
+  // `pullEnded` is the one test both read. A Pull that left on an Exclusion is
+  // no such end, so it falls through to the fresh row. While a `behind-pr:#M`
+  // premise stands, the ledger claims the head and it never reaches here; a
+  // `behind-issue` or branch-named premise only the refreshed shortlist keeps
+  // out, by dropping its ticket (unclaimed), so after a failed refresh the
+  // head can get a PULL row that `pull.mjs` leaves again. Once the premise
+  // lifts, `next` takes it again.
+  if (pullEnded(record)) return { kind: "ended" };
   if (record.status === "running" && typeof record.pending?.qid === "string") {
     return { kind: "pending", qid: record.pending.qid, stale: now - since > staleMinutes * 60_000 };
   }
@@ -308,7 +320,8 @@ function pullAction(n, p) {
 }
 
 // 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.
+// no slot, and the next head takes it. A Pull that left on an Exclusion is no
+// such end (pullOf). Order kept, so the slots fill oldest first.
 function pullable(heads, pulls) {
   return heads.filter((n) => pulls?.get(n)?.kind !== "ended");
 }
@@ -366,7 +379,8 @@ function implementers(s) {
   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
+  // whose Pull ended in this run, which `pull.mjs next` skips — a Pull that
+  // left on an Exclusion is no such end (pullOf). `SUGGEST /triage` asks a
   // MAINTAINER to tick tickets, and on the unattended night the heartbeat
   // exists for there is nobody to ask — so it prints (the fold shows it once)
   // but is not actionable, or it would pin the interval at the base all night.
@@ -1195,10 +1209,12 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed
 // `behind-issue` or branch-named premise) is different: its row is rewritten
 // only when a Pull dispatches the ticket (shortlist.mjs's own header, §3),
 // never on its own, so once shortlist.mjs's live probe has re-admitted the
-// ticket to these entries, that stale row no longer blocks it.
+// ticket to these entries, that stale row no longer blocks it. A row naming no
+// premise has nothing to lift: it claims its ticket for good, as `pull.mjs
+// next` and shortlist.mjs read it.
 export function unclaimed(entries, run) {
   const unverifiable = new Set(run.excluded
-    .filter((e) => e.premises.every(({ kind, target }) => kind !== "pr" || !isDigits(target)))
+    .filter((e) => e.premises.length > 0 && e.premises.every(({ kind, target }) => kind !== "pr" || !isDigits(target)))
     .map((e) => e.n));
   return entries.map((e) => e.n).filter((n) => !run.claimed.has(n) || unverifiable.has(n));
 }
@@ -1226,8 +1242,9 @@ export function parseShortlist(text) {
 
 // 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.
+// in it — a Pull that left on an Exclusion is no such end (pullOf). 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
 // the bound refreshes and Pulls in the same tick, so nothing is lost.
@@ -2168,8 +2185,8 @@ function main() {
   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.
+  // can fill one. A Pull that left on an Exclusion is no such end (pullOf). 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 });
@@ -2186,7 +2203,8 @@ function main() {
   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.
+  // the refresh that finds the head to take its slot. A Pull that left on an
+  // Exclusion is no such end (pullOf).
   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

package/scripts/ledger-grammar.mjs

@@ -609,6 +609,20 @@ export function premisesOf(row) {
   return [...m[1].matchAll(PREMISE)].map(([, kind, target]) => ({ kind, target }));
 }
 
+/** The prefix of the `outcome.reason` of a Pull that ended on an Exclusion. pull.mjs writes it on every path that
+ * ends a Pull on an Exclusion naming a premise; a row naming no premise leaves the row's own text as the reason,
+ * which carries the prefix only when the row does — that Exclusion never lifts, so neither reader takes its head
+ * again whatever the reason says. The fleet tick and `pull.mjs next` read it to tell such a Pull from one that ended
+ * for good: taken, relabelled, closed or released. */
+export const EXCLUDED_REASON = "excluded ·";
+
+/** Whether a Pull's `outcome.reason` says it ended on an Exclusion. */
+const exclusionEnded = (reason) => typeof reason === "string" && reason.startsWith(EXCLUDED_REASON);
+
+/** Whether a Pull record ended for good: released, or left for any reason but an Exclusion. The fleet tick's
+ * pullOf and `pull.mjs next` both read a Pull's end through it, so the two cannot disagree. */
+export const pullEnded = (record) => record.status === "released" || (record.status === "left" && !exclusionEnded(record.outcome?.reason));
+
 export const ROWS = "## Rows";
 export const DISPATCHED = "## Dispatched";
 export const FILED = "## Filed";

package/scripts/pull.mjs

@@ -8,7 +8,9 @@
 // Reached through the Resolver and run from the MAIN checkout (a linked
 // worktree refuses). `next` starts a Pull on the shortlist head — `--head`, else
 // the first `.fleet/shortlist.json` entry with no `impl-` row, no live
-// `excluded` row and no Pull of its own already ended in this phase-0 session — or resumes the
+// `excluded` row and no Pull of its own already ended in this phase-0 session
+// (a Pull that ended on an exclusion whose premise has since lifted is not
+// ended in this sense, and its head is taken again) — or resumes the
 // one in progress for `--head`; `answer` records one answer and resumes. Both
 // run until the next question or the end of the Pull, and both are safe to
 // run again: the state is on disk after every step.
@@ -132,7 +134,7 @@ import { isDigits, makeDie } from "./arg.mjs";
 import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
 import { gitEnv } from "./git-env.mjs";
 import { isCLI } from "./is-cli.mjs";
-import { memberTokens, premisesOf, tierValues } from "./ledger-grammar.mjs";
+import { EXCLUDED_REASON, memberTokens, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
 import { sessionFromReceipt } from "./phase0-receipt.mjs";
 import { briefPaths, briefText, outOfScope, strandedRuling } from "./ticket-router.mjs";
 
@@ -1133,7 +1135,7 @@ class Pull {
     }
     const r = this.script("exclude", "ledger.mjs", ["row", String(st.ticket), `excluded · ${token}`]);
     if (r.status !== 0) return this.stop(withText(`ledger.mjs row failed (${r.how})`, r));
-    return this.leave(`excluded · ${token}`);
+    return this.leave(`${EXCLUDED_REASON} ${token}`);
   }
 }
 
@@ -1196,7 +1198,7 @@ function heldOut(p, n) {
     throw new Refusal(`#${n}: the premise of its exclusion could not be read, so the exclusion stands: ${standing.unread} — run again once gh answers`);
   }
   if (standing.token === null) return row.slice(rowKey(row).length).trim();
-  return `excluded · ${standing.token}${standing.state === null ? "" : ` ${standing.state}`}`;
+  return `${EXCLUDED_REASON} ${standing.token}${standing.state === null ? "" : ` ${standing.state}`}`;
 }
 
 // The phase-0 session names the run a Pull belongs to: the persistent scratch
@@ -1235,7 +1237,8 @@ function shortlistHead(p, run) {
       continue;
     }
     const ended = readPull(p.statePath(n));
-    if (ended !== null && (ended.status === "left" || ended.status === "released") && (run === null || ended.session === run)) continue;
+    // A Pull that left on an exclusion whose premise has lifted — checked above — is not an end: the head is taken again.
+    if (ended !== null && pullEnded(ended) && (run === null || ended.session === run)) continue;
     return n;
   }
   if (unreadable.length > 0) {

package/skills/run-team/SKILL.md

@@ -149,7 +149,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
    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`. A head whose Pull ended
-   this run is not counted. Phase 0 runs it by hand
+   this run is not counted, unless on a lifted exclusion. 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**).
@@ -452,7 +452,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
+head whose Pull ended this run is not counted, unless on a lifted exclusion. 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
@@ -583,7 +583,7 @@ Pull, and each head a free slot Pulls gets its own row, read off that head's
 A head whose Pull already ended in this run — the ticket left, or the router
 refused it and its claim was released — gets no row: `next` without `--head`
 skips it, `next --head <N>` would start the ticket over, and the next head
-fills the slot.
+fills the slot. A lifted exclusion's head (reason `excluded ·`) is the exception: it is counted and Pulled again.
 
 **A Pull never re-admits a ticket already relabelled**: the issue step reads the
 labels fresh and exits 1 `relabelled elsewhere` once `ready-for-agent` is gone.
@@ -1718,7 +1718,7 @@ 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.
+  run is not counted, unless on a lifted exclusion.
 - **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
@@ -1774,7 +1774,7 @@ consult under a merge-side event storm, and that is how implementers reached
 0/target with ~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. The table's shortlist counts no head
-whose Pull ended this run. A refresh at unclaimed < B leaves `unclaimed=` at
+whose Pull ended this run, unless on a lifted exclusion. A refresh at unclaimed < B leaves `unclaimed=` at
 that count, so `SUGGEST /triage` can print it above 0.
 
 | shortlist (unclaimed) | implementer row prints |
@@ -1792,7 +1792,7 @@ 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. Unclaimed there
-counts no head whose Pull ended this run.
+counts no head whose Pull ended this run, unless on a lifted exclusion.
 
 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/tick-rows.md

@@ -10,12 +10,15 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
   FAILED` is yours: `shortlist.mjs` could not run, and the implementer row is
   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
+  this run not counted (unless it ended on an exclusion whose premise has
+  lifted), 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**). 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.
+  heads triggers the refresh before this row prints. It is not printed while the
+  refreshed shortlist holds a head whose Pull ended only on an exclusion whose
+  premise has lifted and a slot is free: that head gets its `PULL` row.
 - `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