@feigi/fleet-ctl 3.40.1 → 3.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.40.1",
3
+ "version": "3.41.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -14,8 +14,9 @@
14
14
  // unattended fleet has no channel to one.
15
15
  //
16
16
  // Exit-code contract — the whole interface for a caller that reads no
17
- // stderr: 0 = survivors, JSON array on stdout. 1 = the query succeeded and
18
- // returned no rows at all. 2 = the query broke (bad args, gh failure, a
17
+ // stderr: 0 = survivors, JSON array on stdout (under `--with-dropped`, the
18
+ // envelope described below). 1 = the query succeeded and returned no rows at
19
+ // all. 2 = the query broke (bad args, gh failure, a
19
20
  // reduction that did not apply, a capped result). 3 = the query succeeded,
20
21
  // returned at least one row, and every row was removed by the to-spec
21
22
  // filter — distinct from 1 so a caller such as run-team's phase 0 can say
@@ -24,6 +25,14 @@
24
25
  // `--allow-fallback`, a labeled all-specs pass that falls back to a
25
26
  // genuinely empty unfiltered pass is exit 1, not 3; the drop count is never
26
27
  // carried across the two attempts.
28
+ //
29
+ // `--with-dropped` changes stdout and nothing else: `{rows, dropped}`, where
30
+ // `rows` is the survivor array the flagless run prints and `dropped` names
31
+ // every row the to-spec filter removed as `{n, reason}`, oldest first. It
32
+ // describes the same final attempt `rows` and exit 3 do. The exit codes are
33
+ // the same with and without it. It exists for a caller that reads no stderr —
34
+ // shortlist.mjs — so an empty or short shortlist can still name what the
35
+ // filter took.
27
36
 
28
37
  import { execFileSync } from "node:child_process";
29
38
  import { parseArgs } from "node:util";
@@ -44,6 +53,7 @@ const has = makeHas(die);
44
53
 
45
54
  const requireLabel = arg("require-label");
46
55
  const allowFallback = has("allow-fallback");
56
+ const withDropped = has("with-dropped");
47
57
 
48
58
  // Default well above the proving ground's real volume. Measured 2026-07-23:
49
59
  // 106 issues survive the exclusions, so the previous hardcoded 100 dropped six
@@ -82,6 +92,7 @@ if (!Number.isInteger(limit) || limit < 1) die(`--limit must be a positive integ
82
92
  const OPTIONS = {
83
93
  "require-label": { type: "string" },
84
94
  "allow-fallback": { type: "boolean" },
95
+ "with-dropped": { type: "boolean" },
85
96
  "limit": { type: "string" },
86
97
  };
87
98
  // No `strict: true`: strict IS parseArgs' default, and stays the default when
@@ -501,6 +512,9 @@ function refuseIfCapped(rows, description) {
501
512
  }
502
513
  }
503
514
 
515
+ // The `reason` a `--with-dropped` caller receives for a to-spec drop.
516
+ const SPEC_REASON = "to-spec: User Stories heading";
517
+
504
518
  // `## User Stories` is to-spec's signature — mandatory in its template, absent
505
519
  // from every ticket template. to-spec stamps a whole spec `ready-for-agent`
506
520
  // with "no need for additional triage", so it arrives looking admissible; it is
@@ -564,16 +578,18 @@ function refuseIfCapped(rows, description) {
564
578
  // from "2 drops, 2 specs" at a glance. Deliberately not deduplicated.
565
579
  function dropSpecs(rows, pass) {
566
580
  const kept = [];
581
+ const dropped = [];
567
582
  for (const { spec, ...rest } of rows) {
568
583
  if (spec) {
569
584
  // "no silent caps" covers drops too — a filtered list that does not say
570
585
  // what it filtered is indistinguishable from a complete one.
571
586
  console.error(` dropped #${rest.n} — to-spec spec, not a ticket (User Stories heading) [${pass}]`);
587
+ dropped.push({ n: rest.n, reason: SPEC_REASON });
572
588
  } else {
573
589
  kept.push(rest);
574
590
  }
575
591
  }
576
- return kept;
592
+ return { kept, dropped };
577
593
  }
578
594
 
579
595
  let rows = query(requireLabel);
@@ -592,7 +608,8 @@ refuseIfCapped(rows, requireLabel ? ` with label:${requireLabel}` : "");
592
608
  // all-filtered (raw>0) whose fallback pass is genuinely empty (raw=0), which
593
609
  // must read as the fallback's own facts (exit 1), not a merge of the two.
594
610
  const rawCount1 = rows.length;
595
- rows = dropSpecs(rows, requireLabel ? `label:${requireLabel}` : "unfiltered");
611
+ let dropped;
612
+ ({ kept: rows, dropped } = dropSpecs(rows, requireLabel ? `label:${requireLabel}` : "unfiltered"));
596
613
  let allFilteredOut = rawCount1 > 0 && rows.length === 0;
597
614
 
598
615
  if (rows.length === 0 && allowFallback && requireLabel) {
@@ -604,7 +621,7 @@ if (rows.length === 0 && allowFallback && requireLabel) {
604
621
  // not transfer, as no gate follows this one. The call must exist because the
605
622
  // fallback's rows arrive raw and nothing downstream drops a spec.
606
623
  const rawCount2 = rows.length;
607
- rows = dropSpecs(rows, "unfiltered (fallback)");
624
+ ({ kept: rows, dropped } = dropSpecs(rows, "unfiltered (fallback)"));
608
625
  allFilteredOut = rawCount2 > 0 && rows.length === 0;
609
626
  }
610
627
 
@@ -619,6 +636,7 @@ if (rows.length === 0 && allowFallback && requireLabel) {
619
636
  // Native sub-issue links are still not read: parent/child is hierarchy, not
620
637
  // blocking, so a blocker recorded only as one reaches it with none.
621
638
  rows.sort((a, b) => a.n - b.n);
639
+ dropped.sort((a, b) => a.n - b.n);
622
640
 
623
641
  for (const r of rows) {
624
642
  console.error(` #${r.n} [${r.l.join(",")}] ${r.t}${r.d.length ? ` deps:${r.d.join(";")}` : ""}`);
@@ -658,7 +676,8 @@ for (const r of rows) {
658
676
  // without copying up to `--limit` rows to do it. Add a field to the
659
677
  // reduction that stdout SHOULD carry and it needs naming here, or it
660
678
  // silently never ships.
661
- console.log(JSON.stringify(rows, (k, v) => (k === "dh" ? undefined : v)));
679
+ const replacer = (k, v) => (k === "dh" ? undefined : v);
680
+ console.log(withDropped ? JSON.stringify({ rows, dropped }, replacer) : JSON.stringify(rows, replacer));
662
681
 
663
682
  // Exit 1 for a successful query with no survivors, exit 3 when those zero
664
683
  // survivors are the filter's doing rather than the query's — see the
@@ -35,9 +35,12 @@
35
35
  // the git common dir as ledger.mjs resolves the ledger. Its
36
36
  // entries minus every ticket with an `impl-` row, or an `excluded`
37
37
  // row whose premise still holds, are the heads a PULL names; its
38
- // `scanned` is the supply. Missing or unparsable is depth 0 and a
38
+ // `scanned` is the supply. Its `dropped`, the rows candidates.mjs's
39
+ // to-spec filter removed before `scanned` was counted, is named on
40
+ // the implementer row as `specs-dropped=` and counts toward
41
+ // nothing. Missing or unparsable is depth 0 and a
39
42
  // refresh, never a refusal: the depth only ever bounds PULLs
40
- // downward.
43
+ // downward. A file with no `dropped` names no drops.
41
44
  // gh The open PRs, by label, by whether they close an issue and by
42
45
  // GitHub's `mergeable` — the merge queue, which PRs are owed a
43
46
  // review, and which conflict. Also, for each ticket
@@ -153,10 +156,22 @@ function replaceStep(held, implNames) {
153
156
  ].filter(Boolean).join("; ");
154
157
  }
155
158
 
159
+ // `specs-dropped=#<n> #<n> (to-spec: User Stories heading)`, one clause per
160
+ // reason, or "" when nothing was dropped. A dropped ticket never reaches
161
+ // `supply`, so without this an all-specs queue reads as no work at all.
162
+ function specsDropped(dropped) {
163
+ if (!dropped.length) return "";
164
+ const by = new Map();
165
+ for (const { n, reason } of dropped) by.set(reason, [...(by.get(reason) ?? []), `#${n}`]);
166
+ return `specs-dropped=${[...by].map(([reason, ns]) => `${ns.join(" ")} (${reason})`).join(", ")}`;
167
+ }
168
+
156
169
  function implementers(s, left) {
170
+ const dropped = specsDropped(s.dropped);
157
171
  const row = mkRow("implementers", s.implLive, s.implCap,
158
172
  `unclaimed=${s.heads.length} supply=${s.supply ?? "?"} unreviewed=${left.unreviewed}`
159
- + (s.shortlistStatus === "ok" ? "" : ` shortlist=${s.shortlistStatus}`));
173
+ + (s.shortlistStatus === "ok" ? "" : ` shortlist=${s.shortlistStatus}`)
174
+ + (dropped ? ` ${dropped}` : ""));
160
175
 
161
176
  // Drain stops supply and nothing else. Read from the file, so
162
177
  // a replacement controller that never saw the drain is held by it too.
@@ -898,9 +913,11 @@ export function unclaimed(entries, run) {
898
913
  return entries.map((e) => e.n).filter((n) => !run.claimed.has(n) || unverifiable.has(n));
899
914
  }
900
915
 
901
- // shortlist.mjs's payload, `{scanned, shortlist: [{n, t}]}`, or unparsable.
916
+ // shortlist.mjs's payload, `{scanned, shortlist: [{n, t}], dropped: [{n,
917
+ // reason}]}`, or unparsable. A payload with no `dropped` predates the field
918
+ // and reads as no drops.
902
919
  export function parseShortlist(text) {
903
- const none = { status: "unparsable", scanned: null, entries: [] };
920
+ const none = { status: "unparsable", scanned: null, entries: [], dropped: [] };
904
921
  let d;
905
922
  try {
906
923
  d = JSON.parse(text);
@@ -909,7 +926,12 @@ export function parseShortlist(text) {
909
926
  }
910
927
  if (!d || typeof d !== "object" || !Number.isInteger(d.scanned) || d.scanned < 0 || !Array.isArray(d.shortlist)
911
928
  || !d.shortlist.every((e) => e && Number.isInteger(e.n) && e.n > 0 && typeof e.t === "string")) return none;
912
- return { status: "ok", scanned: d.scanned, entries: d.shortlist.map(({ n, t }) => ({ n, t })) };
929
+ const dropped = d.dropped === undefined ? [] : d.dropped;
930
+ if (!Array.isArray(dropped) || !dropped.every((e) => e && Number.isInteger(e.n) && e.n > 0 && typeof e.reason === "string")) return none;
931
+ return {
932
+ status: "ok", scanned: d.scanned, entries: d.shortlist.map(({ n, t }) => ({ n, t })),
933
+ dropped: dropped.map(({ n, reason }) => ({ n, reason })),
934
+ };
913
935
  }
914
936
 
915
937
  // Why this tick refreshes the shortlist, or null. The premise-lifted
@@ -1178,16 +1200,16 @@ function shortlistPath() {
1178
1200
  }
1179
1201
 
1180
1202
  function readShortlist(path) {
1181
- if (path === null) return { status: "missing", scanned: null, entries: [] };
1203
+ if (path === null) return { status: "missing", scanned: null, entries: [], dropped: [] };
1182
1204
  let text;
1183
1205
  try {
1184
1206
  text = readFileSync(path, "utf8");
1185
1207
  } catch (e) {
1186
- if (e.code === "ENOENT") return { status: "missing", scanned: null, entries: [] };
1208
+ if (e.code === "ENOENT") return { status: "missing", scanned: null, entries: [], dropped: [] };
1187
1209
  // Distinct from `unparsable`: that label's only other producer is
1188
1210
  // genuinely malformed JSON, and a permissions/filesystem fault reported
1189
1211
  // as a JSON-content fault sends the operator chasing the wrong repair.
1190
- return { status: "unreadable", scanned: null, entries: [], code: e.code ?? null, message: e.message };
1212
+ return { status: "unreadable", scanned: null, entries: [], dropped: [], code: e.code ?? null, message: e.message };
1191
1213
  }
1192
1214
  return parseShortlist(text);
1193
1215
  }
@@ -1369,6 +1391,7 @@ function main() {
1369
1391
  // so a slot the current file could not fill does not wait a tick for it.
1370
1392
  let heads = unclaimed(current.entries, run);
1371
1393
  let supply = current.scanned;
1394
+ let dropped = current.dropped;
1372
1395
  let fresh = null;
1373
1396
  const trigger = refreshWhy({ draining: run.draining, status: current.status, entries: current.entries.length,
1374
1397
  unclaimed: heads.length, implCap: caps.implCap })
@@ -1379,6 +1402,7 @@ function main() {
1379
1402
  const excludedSet = new Set(run.excluded.map((x) => x.n));
1380
1403
  heads = [...new Set([...heads, ...unclaimed(r.entries, run)])];
1381
1404
  supply = r.scanned;
1405
+ dropped = r.dropped;
1382
1406
  fresh = {
1383
1407
  ok: true, trigger, entries: r.entries.length,
1384
1408
  lifted: r.entries.filter((e) => excludedSet.has(e.n)).length,
@@ -1396,7 +1420,7 @@ function main() {
1396
1420
  const mainCheckout = checkMainCheckout();
1397
1421
 
1398
1422
  const rows = reconcile({
1399
- ...caps, ...run, heads, supply, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
1423
+ ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
1400
1424
  });
1401
1425
  const said = describe(mainCheckout, run.live);
1402
1426
  // Re-read rather than reusing priorState: this must be the freshest
@@ -1446,7 +1470,11 @@ function main() {
1446
1470
  // `quiet`, and named on the folded line for as long as it stays live
1447
1471
  // past its threshold. The digest already moves when its bucket does.
1448
1472
  const aged = stale.map((s) => `; CHECK-LIVENESS ${s.member} persists`).join("");
1449
- console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held}${aged} — full rows on the next change`);
1473
+ // The to-spec drops the same way: advice, and the one reason an empty
1474
+ // shortlist is not "no work".
1475
+ const specs = specsDropped(dropped);
1476
+ const drops = specs ? `; ${specs} persists` : "";
1477
+ console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held}${aged}${drops} — full rows on the next change`);
1450
1478
  return;
1451
1479
  }
1452
1480
  for (const line of lines) console.log(line);
@@ -462,15 +462,23 @@ function launchedRunners(text) {
462
462
  * refuses a repeat from within a run — and every reviewer runner a row
463
463
  * launched, that `liveOnLedger` does not carry, plus every name the archive's
464
464
  * own `## Retired` already held (`retired`, bare retirable names — the caller
465
- * validates them), once each, in that order. A retired name stays taken for
466
- * the rest of the omp session: the process that ran the member still holds a
467
- * peer under it, and omp answers a second task of that name with `<name>-2`
468
- * while `hub send <name>` keeps reaching the first. `carried` is
469
- * `{rows, dispatched}`, the texts of the rows and the `## Dispatched` entries
470
- * the new ledger carries (`liveOnLedger`'s picks); a name it carries, live or
471
- * as a settled copy, is on the new ledger already and is not listed twice. A
472
- * row is read whether or not it parsed, but an unsettled member token on it
473
- * retires nothing: only a settled name is known gone.
465
+ * validates them), once each: the `## Retired` names first, then the
466
+ * `## Dispatched` entries' in order, then the rows' in the order given, a
467
+ * row's member tokens before the reviewer runners it launched. A retired
468
+ * name stays taken for the rest of the omp session: the process that ran
469
+ * the member still holds a peer under it, and omp answers a second task of
470
+ * that name with `<name>-2` while `hub send <name>` keeps reaching the
471
+ * first. `carried` is `{rows, dispatched}`, the texts of the rows and the
472
+ * `## Dispatched` entries the new ledger carries (`liveOnLedger`'s picks); a
473
+ * name it carries, live or as a settled copy, is on the new ledger already
474
+ * and is not listed twice.
475
+ * `dispatched` is every entry the archive held, well-formed or not, and a row
476
+ * is read whether or not it parsed. A token with an outcome is a name this
477
+ * session used, so it is retired whether or not its outcome is one of its
478
+ * family's: the name on `impl-5=bogus` is retired, though the line is not
479
+ * carried. An unsettled member token — a bare name, no outcome — retires
480
+ * nothing: only a name known gone is retired, and a line whose name does not
481
+ * parse names no member.
474
482
  */
475
483
  export function retiredOnLedger(rows, dispatched, retired, carried) {
476
484
  const seen = new Set();
@@ -488,10 +496,10 @@ export function retiredOnLedger(rows, dispatched, retired, carried) {
488
496
  for (const name of retired) add(name);
489
497
  for (const e of dispatched) {
490
498
  const t = parseToken(e);
491
- if (t !== null && t.error === null && t.outcome !== null) add(t.name);
499
+ if (t !== null && t.outcome !== null) add(t.name);
492
500
  }
493
501
  for (const text of rows) {
494
- for (const t of memberTokens(text)) if (t.error === null && t.outcome !== null) add(t.name);
502
+ for (const t of memberTokens(text)) if (t.outcome !== null) add(t.name);
495
503
  for (const name of launchedRunners(text)) add(name);
496
504
  }
497
505
  return out;
@@ -20,7 +20,8 @@
20
20
  // dispatch and never loses or reorders one — settling annotates an entry in
21
21
  // place — which is what lets `merge-bot-<n>` be numbered from it; a rotate
22
22
  // that carries a run's live entries forward carries a settled one only for a
23
- // member a carried row names, and retires every other settled name into
23
+ // member a carried row names, and retires every other settled name — and a
24
+ // name whose outcome is outside its family's vocabulary — into
24
25
  // `## Retired`, where `dispatch` and that numbering still read it.
25
26
  //
26
27
  // Writer policy: the controller owns run state
@@ -1564,7 +1565,8 @@ function runCheck() {
1564
1565
  // controller's to read and no script's.
1565
1566
  //
1566
1567
  // An `ancestor` rotate also writes `## Retired`: the bare name of every
1567
- // member the archive settled and the new ledger does not carry, of every
1568
+ // member the archive settled, or gave an outcome outside its family's
1569
+ // vocabulary, and the new ledger does not carry, of every
1568
1570
  // reviewer runner its rows launched and the new ledger does not carry, and
1569
1571
  // every name the archive's own `## Retired` held. The omp process those
1570
1572
  // members ran in is still this run's, and it answers a second task under a
@@ -1721,10 +1723,13 @@ function runRotate() {
1721
1723
  // siblings' with them, and the tick's per-PR reading of the PR is unchanged;
1722
1724
  // and the `## Dispatched` entries, settled ones among them, that keep a
1723
1725
  // carried member from reading live again. retiredOnLedger() names the rest:
1724
- // every settled member neither travels, and every reviewer runner a row
1725
- // launched, read off the parsed rows and the skipped ones alike — a row the
1726
- // tick refuses still names members this session ran — and the archive's own
1727
- // `## Retired`, each line of which must be a bare member or reviewer name.
1726
+ // every member neither travels that a line gives an outcome — a settled one,
1727
+ // or one whose outcome is outside its family's vocabulary, which skips the
1728
+ // line but not the name — and every reviewer runner a row launched, read off
1729
+ // the parsed rows, the skipped ones and every `## Dispatched` entry alike — a
1730
+ // line the tick refuses still names members this session ran — and the
1731
+ // archive's own `## Retired`, each line of which must be a bare member or
1732
+ // reviewer name.
1728
1733
  function carryOf(text) {
1729
1734
  const skipped = [];
1730
1735
  const skippedRows = [];
@@ -1739,7 +1744,8 @@ function carryOf(text) {
1739
1744
  return false;
1740
1745
  }
1741
1746
  });
1742
- const dispatched = sectionOf(text, DISPATCHED).filter((e) => {
1747
+ const allDispatched = sectionOf(text, DISPATCHED);
1748
+ const dispatched = allDispatched.filter((e) => {
1743
1749
  const t = parseToken(e);
1744
1750
  if (t !== null && t.error === null) return true;
1745
1751
  skipped.push({ line: e, why: t === null ? "not a member token" : `${t.name}: ${t.error}` });
@@ -1752,7 +1758,7 @@ function carryOf(text) {
1752
1758
  });
1753
1759
  const live = liveOnLedger(rows, dispatched);
1754
1760
  const carried = { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched };
1755
- const retired = retiredOnLedger([...rows, ...skippedRows], dispatched, archivedRetired, carried);
1761
+ const retired = retiredOnLedger([...rows, ...skippedRows], allDispatched, archivedRetired, carried);
1756
1762
  return { ...carried, retired, skipped };
1757
1763
  }
1758
1764
 
@@ -6,8 +6,11 @@
6
6
  //
7
7
  // The filters, in the order they run:
8
8
  //
9
- // 1. `candidates.mjs --require-label ready-for-agent`, oldest-first and never
10
- // re-ranked. Its row count is `scanned`, the supply the tick reports.
9
+ // 1. `candidates.mjs --require-label ready-for-agent --with-dropped`,
10
+ // oldest-first and never re-ranked. Its row count is `scanned`, the
11
+ // supply the tick reports; the rows its to-spec filter removed are
12
+ // `dropped`, which counts toward nothing and is carried so an empty or
13
+ // short shortlist still names them.
11
14
  // 2. The dependency scan on each row's `d`: an open blocker drops the ticket
12
15
  // (next-ticket step 2). A blocker that is itself a candidate is open by
13
16
  // construction — candidates.mjs queries `--state open` — so only the rest
@@ -50,9 +53,9 @@
50
53
  // Unlike the ledger there
51
54
  // is no cwd-relative degrade: outside a repository inflight.sh cannot answer
52
55
  // for a single ticket either, so there is nothing honest to write. The payload
53
- // is `{scanned, shortlist: [{n, t}]}`, written to a sibling temp file and
54
- // renamed over the target so a reader never sees half of it; stdout carries
55
- // the same object plus `file`.
56
+ // is `{scanned, shortlist: [{n, t}], dropped: [{n, reason}]}`, written to a
57
+ // sibling temp file and renamed over the target so a reader never sees half
58
+ // of it; stdout carries the same object plus `file`.
56
59
  //
57
60
  // The ledger is read through `ledger.mjs read`, never parsed here, so the
58
61
  // ledger keeps one parser. candidates.mjs's stderr passes straight through —
@@ -150,31 +153,36 @@ function shortlistPath() {
150
153
  }
151
154
 
152
155
  function scan() {
153
- const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", LABEL], {
156
+ const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", LABEL, "--with-dropped"], {
154
157
  encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "inherit"],
155
158
  });
156
159
  if (r.error) die(`candidates.mjs did not run: ${how(r)}`);
157
- const out = (r.stdout ?? "").trim();
158
160
  // Exit 1 (an empty queue) and exit 3 (every row a to-spec spec) are both the
159
161
  // empty answer. Exit 1 is also Node's own code for a crash, so the payload
160
- // decides.
161
- if ((r.status === 1 || r.status === 3) && out === "[]") return [];
162
- if (r.status !== 0) {
162
+ // decides: it must parse, with no rows.
163
+ if (r.status !== 0 && r.status !== 1 && r.status !== 3) {
163
164
  die(`candidates.mjs ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`} — the scan did not answer, so there is no shortlist to write`);
164
165
  }
165
- let rows;
166
+ let out;
166
167
  try {
167
- rows = JSON.parse(out);
168
+ out = JSON.parse(r.stdout ?? "");
168
169
  } catch (e) {
170
+ if (r.status !== 0) die(`candidates.mjs exited ${r.status} — the scan did not answer, so there is no shortlist to write`);
169
171
  die(`could not parse candidates.mjs output: ${e.message}`);
170
172
  }
171
- if (!Array.isArray(rows)) die("candidates.mjs did not return an array");
173
+ if (!out || typeof out !== "object" || !Array.isArray(out.rows) || !Array.isArray(out.dropped)) {
174
+ die("candidates.mjs did not return {rows, dropped}");
175
+ }
176
+ const { rows, dropped } = out;
177
+ if (r.status !== 0 && rows.length) die(`candidates.mjs exited ${r.status} with rows — the scan did not answer, so there is no shortlist to write`);
172
178
  const bad = rows.findIndex(
173
179
  (row) => !row || !Number.isInteger(row.n) || typeof row.t !== "string" ||
174
180
  !Array.isArray(row.d) || !row.d.every(Number.isInteger),
175
181
  );
176
182
  if (bad !== -1) die(`candidates.mjs row ${bad} is not {n, t, d} with integer refs`);
177
- return rows;
183
+ const badDrop = dropped.findIndex((e) => !e || !Number.isInteger(e.n) || typeof e.reason !== "string");
184
+ if (badDrop !== -1) die(`candidates.mjs dropped entry ${badDrop} is not {n, reason}`);
185
+ return { rows, dropped: dropped.map(({ n, reason }) => ({ n, reason })) };
178
186
  }
179
187
 
180
188
  function ledgerRows() {
@@ -236,7 +244,7 @@ async function main() {
236
244
  const extra = process.argv.slice(2);
237
245
  if (extra.length) die(`takes no arguments, got ${extra.join(" ")}`);
238
246
  const file = shortlistPath();
239
- const rows = scan();
247
+ const { rows, dropped } = scan();
240
248
  const ledger = ledgerRows();
241
249
 
242
250
  // Dependency scan.
@@ -316,7 +324,7 @@ async function main() {
316
324
  return false;
317
325
  });
318
326
 
319
- const payload = { scanned: rows.length, shortlist: survivors.map(({ n, t }) => ({ n, t })) };
327
+ const payload = { scanned: rows.length, shortlist: survivors.map(({ n, t }) => ({ n, t })), dropped };
320
328
  const tmp = `${file}.${process.pid}.tmp`;
321
329
  try {
322
330
  mkdirSync(dirname(file), { recursive: true });
@@ -410,9 +410,10 @@ phase, or in any later one, asks the maintainer which tickets to take.
410
410
  every unsettled `## Dispatched` entry and the settled entry of each
411
411
  member a carried row names; exclusions, `## Filed`, `## Ruled` and the
412
412
  drain marker are never carried. Every other settled name — in
413
- `## Dispatched` or on any row — and every reviewer runner a row launched
414
- goes into the new ledger's `## Retired` as a bare name, with whatever the
415
- archive's own `## Retired` held: omp answers a second `task` under a name
413
+ `## Dispatched` or on any row, and including a name whose outcome is
414
+ outside its family's vocabulary, whose line is skipped below — and every
415
+ reviewer runner a row launched goes into the new ledger's `## Retired` as
416
+ a bare name, with whatever the archive's own `## Retired` held: omp answers a second `task` under a name
416
417
  this process has used with `<name>-2` while `hub send <name>` keeps
417
418
  reaching the first, so a settled name stays taken for the session, not
418
419
  the run. `dispatch` refuses a retired name and names the replacement — one
@@ -423,7 +424,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
423
424
  reads `## Retired`: a ticket an earlier run worked is not claimed by it
424
425
  and can be shortlisted again.
425
426
  A line it cannot parse is skipped with a warning naming it, and the
426
- rotation still succeeds. It prints `{rotated, archive, carried: {rows,
427
+ rotation still succeeds; a member name on a skipped line that carries an
428
+ outcome is retired all the same, and a bare member token on a skipped row
429
+ retires nothing. It prints `{rotated, archive, carried: {rows,
427
430
  dispatched}, retired, skipped}`. The carried tokens keep the tick from
428
431
  dispatching onto those members' work, keep their names taken, and give
429
432
  their late results a token to settle; the stranded-claim step below
@@ -603,8 +606,10 @@ phase, or in any later one, asks the maintainer which tickets to take.
603
606
  — no ticket body is read here, because a Pull reads one ticket in full at
604
607
  the moment it admits it:
605
608
 
606
- - **Candidate scan** — `candidates.mjs --require-label ready-for-agent`,
607
- oldest-first, never re-ranked. Its row count is `scanned`, the supply.
609
+ - **Candidate scan** — `candidates.mjs --require-label ready-for-agent
610
+ --with-dropped`, oldest-first, never re-ranked. Its row count is
611
+ `scanned`, the supply; the rows its to-spec filter removed are
612
+ `dropped`, counted nowhere.
608
613
  - **Dependency scan**, `next-ticket` step 2, on each row's `d` array. Open
609
614
  blocker → drop.
610
615
  - **Live Exclusions** — a ticket whose ledger row reads `excluded ·
@@ -615,7 +620,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
615
620
  free. Both drop the ticket, logged by number.
616
621
 
617
622
  It writes the survivors, in order, to `.fleet/shortlist.json` —
618
- `{scanned, shortlist: [{n, t}]}` — resolved against the git common dir by
623
+ `{scanned, shortlist: [{n, t}], dropped: [{n, reason}]}` — resolved against the git common dir by
619
624
  `fleet-dir.mjs`, the one locator `ledger.mjs` resolves `.fleet/ledger.md`
620
625
  with too, so you, the tick and a member in its own worktree all name one
621
626
  file. **Exit 0 is the file written,
@@ -635,15 +640,20 @@ phase, or in any later one, asks the maintainer which tickets to take.
635
640
  widen the list: `ready-for-human` needs a human to brainstorm first and you
636
641
  have no channel to one mid-flight.
637
642
 
638
- `candidates.mjs`'s exit 3 reaches you as an empty shortlist with its to-spec
639
- notice on stderr. **Exit 3 is not that empty queue, and never a reason to
643
+ `candidates.mjs`'s exit 3 reaches you as an empty shortlist whose `dropped`
644
+ names every ticket the to-spec filter took, by number and reason — and the
645
+ tick prints the same list on every tick, `specs-dropped=#<N> (to-spec: User
646
+ Stories heading)` on the implementer row. **Exit 3 is not that empty queue, and never a reason to
640
647
  widen the net.** It says the labeled query returned rows and the to-spec
641
648
  filter took every one: what is queued is to-tickets' input rather than
642
649
  claimable tickets, and a member handed one implements an entire spec as a
643
650
  single ticket. Log it as
644
- specs awaiting to-tickets, not as no work — and still do not pass
651
+ specs awaiting to-tickets, not as no work — read the numbers off
652
+ `dropped` or `specs-dropped=`, not off stderr, which the tick's own
653
+ refresh discards — and still do not pass
645
654
  `--allow-fallback`, whose second pass is unfiltered and so reaches the
646
- `ready-for-human` and untriaged work you have no channel for.
655
+ `ready-for-human` and untriaged work you have no channel for. A partial
656
+ drop, survivors and specs together, is named the same way.
647
657
  2. **Refresh is the tick's from here on.** `fleet-tick.mjs` runs
648
658
  `shortlist.mjs` itself when unclaimed entries fall below the implementer
649
659
  cap, when the file is missing or empty, and when an `excluded` premise has
@@ -1856,6 +1866,10 @@ depth** guard table applied in code. Act on each line as it reads:
1856
1866
  blind until it can.
1857
1867
  - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
1858
1868
  Suggest, never run (**Queue depth**).
1869
+ - `specs-dropped=#<N> … (to-spec: User Stories heading)` at the end of the
1870
+ implementer row's counts, whatever its ACTION — the tickets the to-spec
1871
+ filter kept out of `supply`, read off the shortlist's `dropped`. Never
1872
+ actionable. Log them as specs awaiting to-tickets (phase 0), not as no work.
1859
1873
  - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
1860
1874
  a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**Reviewers**). Printed
1861
1875
  ahead of reviews on purpose: finishing what is started beats starting more.
@@ -2015,6 +2029,9 @@ A live member past its family's threshold folds the same way — it is advice, s
2015
2029
  nothing for the heartbeat to act on by itself — and the folded line names each
2016
2030
  such member (`…; CHECK-LIVENESS fix-pr-5 persists — …`) for as long as it stays
2017
2031
  live past the threshold.
2032
+ To-spec drops fold the same way, and the folded line names them
2033
+ (`…; specs-dropped=#<N> (to-spec: User Stories heading) persists — …`) for as
2034
+ long as the shortlist carries them.
2018
2035
 
2019
2036
  **When you stop on purpose, say why — one command, and it is the last thing
2020
2037
  you owe the next run.** The beat leaves a dated mark on every hold, so a run
@@ -3811,6 +3828,10 @@ never as a second, hand-run copy of it.
3811
3828
  | below the cap, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
3812
3829
  | 0 after that refresh | `SUGGEST /triage, hold idle` |
3813
3830
 
3831
+ Whatever the row prints, a `specs-dropped=#<N> (…)` at the end of its counts
3832
+ names the tickets the to-spec filter kept out of the shortlist — specs
3833
+ awaiting to-tickets, so an empty shortlist carrying one is not "no work".
3834
+
3814
3835
  Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
3815
3836
  recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is
3816
3837
  dispatched at the right tier, `HOLD (tier unchecked impl-<N>)` until
@@ -4200,7 +4221,8 @@ live count from it, so nobody states one. Write neither by hand:
4200
4221
  same `<file>.lock`, and the next write starts the empty skeleton — unless
4201
4222
  the previous run was this session's own, when it first writes the rows and
4202
4223
  `## Dispatched` entries still live into a new ledger, and every other
4203
- settled name into its `## Retired` (phase 0 says which). Refused
4224
+ settled name, or name given an out-of-vocabulary outcome, into its
4225
+ `## Retired` (phase 0 says which). Refused
4204
4226
  while the recorded controller is alive and not this run's ancestor, ledger
4205
4227
  or none — or, with no record and a ledger to move, while the heartbeat mark
4206
4228
  is still beating — or when the archive name already exists, the process
@@ -4352,7 +4374,7 @@ Plus a queue-depth line: shortlist, supply, whether triage was suggested.
4352
4374
  - "This member finished, send it the next ticket" → resumes its transcript.
4353
4375
  - "The name is cosmetic" → the name is the ledger token and the hub address.
4354
4376
  - "Name the specialists too" → a depth-2 member cannot dispatch further.
4355
- - "ready-for-agent came back empty, widen to ready-for-human" → empty means no work.
4377
+ - "ready-for-agent came back empty, widen to ready-for-human" → empty with no `specs-dropped=` means no work; empty with drops means specs awaiting to-tickets, and is still never a reason to widen.
4356
4378
  - "The reap at the end will pick up the claim I never dispatched" → it declines:
4357
4379
  not `[gone]`, no unique commits. Release it, or it reads as taken next run.
4358
4380
  - "Touches eight files, too big for the fleet" → size is not the axis. Decided is.