@feigi/fleet-ctl 3.61.1 → 3.62.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.61.1",
3
+ "version": "3.62.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": {
@@ -89,6 +89,19 @@
89
89
  // REPORT-UNREADABLE. Advice, like CHECK-LIVENESS: the tick
90
90
  // settles nothing. A review runner has no report schema and files
91
91
  // none, so no `review=` token is looked up.
92
+ // session The listing of the session directory omp writes one
93
+ // `<member>.jsonl` transcript into per dispatched member: this
94
+ // run's phase-0 receipt's `session`, else `--session`; with
95
+ // neither the check is skipped with one stderr line. One readdir
96
+ // per tick, and no file in it is read. A `<stem>.jsonl` whose stem
97
+ // is a member name the ledger records nowhere — no row token, no
98
+ // `## Dispatched` entry, no `## Retired` line — prints
99
+ // `UNRECORDED <stem>`; a live member token first seen more than
100
+ // `--no-transcript-after` minutes ago with no file prints
101
+ // `NO-TRANSCRIPT <member>`. The receipt's directory not there yet
102
+ // holds no transcript; a `--session` one that is not there, like
103
+ // one that cannot be listed, skips the check with one stderr line.
104
+ // Advice, like CHECK-LIVENESS.
92
105
  //
93
106
  // The pure half below is `reconcile()` over the counts `deriveRun()` reads off
94
107
  // the ledger; main() does the I/O. Split so the guard table and the reading are
@@ -826,7 +839,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
826
839
  export const pastPinDue = (st, head) => st !== undefined && st.pastPinHalt && !st.inFlight && st.reviewedHead !== null
827
840
  && !String(head).toLowerCase().startsWith(st.reviewedHead);
828
841
 
829
- export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(), finished = new Set()) {
842
+ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed = new Set(), finished = new Set()) {
830
843
  const open = new Set(prs.map((p) => p.number));
831
844
  const { members, byPr, verdicts, claimed, excluded } = foldLedger({ rows, dispatched }, open);
832
845
 
@@ -839,9 +852,9 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
839
852
  // replacement's own check passes, the row holds — a replacement that is
840
853
  // ALSO mismatched keeps holding, and one not yet checked holds as
841
854
  // unchecked. A member with no verdict at all holds whether it is live or
842
- // settled — the tick never reads a transcript, so only tier-check.mjs can
843
- // say whether one exists; a settled member whose transcript was never
844
- // written gets `tier-unverifiable=` from it, which clears the hold here.
855
+ // settled — the tick reads no transcript, so only tier-check.mjs can judge
856
+ // one; a settled member whose transcript was never written gets
857
+ // `tier-unverifiable=` from it, which clears the hold here.
845
858
  const newest = impls.filter((m, i) => !impls.some((o, j) => j > i && o.number === m.number));
846
859
  // A mismatch on a ticket whose issue is CLOSED holds nothing: there
847
860
  // is nothing left for `impl-<N>-b` to replace, and a retired definition can
@@ -986,6 +999,10 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
986
999
  // unsettled member token. A review runner has no report schema and a
987
1000
  // `review=wf:` run no member, so neither files one.
988
1001
  reporters: unsettled,
1002
+ // Every member name the ledger records, settled or live: each row's
1003
+ // member tokens, each `## Dispatched` entry and each `## Retired` line —
1004
+ // the names a transcript in the session directory is accounted for by.
1005
+ recorded: new Set([...members.keys(), ...retired]),
989
1006
  };
990
1007
  }
991
1008
 
@@ -1132,6 +1149,45 @@ export function reportLines({ reporters, reports, now, reportsFrom = null }) {
1132
1149
  return out;
1133
1150
  }
1134
1151
 
1152
+ // The stems of the `<stem>.jsonl` names in a session directory's listing,
1153
+ // sorted: the listing's own order is the filesystem's.
1154
+ export const transcriptStems = (names) => names.filter((n) => n.endsWith(".jsonl")).map((n) => n.slice(0, -".jsonl".length)).sort();
1155
+
1156
+ // The UNRECORDED lines: one per stem in `stems` that is a member name
1157
+ // (parseMember's, any family, retry letters included) and that `recorded`
1158
+ // — deriveRun's every name on the ledger — lacks, as `{kind, name, line, key}`. A
1159
+ // transcript is a dispatch the ledger never recorded, so the next tick would
1160
+ // name that dispatch again. A stem that is no member's name (a reviewer
1161
+ // runner's, `agent-abc123`) is never one. Advice: nothing here writes
1162
+ // the ledger.
1163
+ export function unrecordedLines({ stems, recorded }) {
1164
+ return stems.filter((stem) => parseMember(stem) !== null && !recorded.has(stem)).map((name) => {
1165
+ const line = `UNRECORDED ${name} (transcript exists, no ledger token)`;
1166
+ return { kind: "UNRECORDED", name, line, key: line };
1167
+ });
1168
+ }
1169
+
1170
+ // The NO-TRANSCRIPT lines: one per live member token in `live` whose `seen`
1171
+ // stamp is more than `after` minutes old and whose `<member>.jsonl` is not
1172
+ // among `stems`, as `{kind, name, line, key}` — a ledger token whose `task` call
1173
+ // was never made. A `review:PR#<n>` launch is no member and has no
1174
+ // transcript named after it, so it is never one. `key` is the line without
1175
+ // its age, what the digest `--fold-unchanged` compares takes.
1176
+ export function noTranscriptLines({ live, seen, stems, session, after, now }) {
1177
+ const has = new Set(stems);
1178
+ const out = [];
1179
+ for (const name of live) {
1180
+ if (parseMember(name) === null || seen[name] === undefined || has.has(name)) continue;
1181
+ const ms = now - seen[name];
1182
+ if (ms <= after * 60_000) continue;
1183
+ out.push({
1184
+ kind: "NO-TRANSCRIPT", name, key: `NO-TRANSCRIPT ${name}`,
1185
+ line: `NO-TRANSCRIPT ${name} (live ${Math.floor(ms / 60_000)}m, no ${join(session, `${name}.jsonl`)})`,
1186
+ });
1187
+ }
1188
+ return out;
1189
+ }
1190
+
1135
1191
  // --apply's pure half. The merge-bot numbers `applied.reapAfter` names for
1136
1192
  // THIS run: none when its `run` is not the controller record's `at`, since
1137
1193
  // merge-bot numbering restarts with a run and the state file outlives it
@@ -1194,7 +1250,7 @@ export function reclaimSummary(stdout) {
1194
1250
 
1195
1251
  import { execFileSync, spawnSync } from "node:child_process";
1196
1252
  import { createHash } from "node:crypto";
1197
- import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
1253
+ import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
1198
1254
  import { tmpdir } from "node:os";
1199
1255
  import { dirname, join } from "node:path";
1200
1256
  import { fileURLToPath } from "node:url";
@@ -1281,6 +1337,13 @@ const OPTIONS = {
1281
1337
  // receipt names none; the receipt's `scratch` wins when it does. Empty is
1282
1338
  // absent, as with --state.
1283
1339
  scratch: { type: "string", default: "" },
1340
+ // The session directory the transcript listing is read off, for a run whose
1341
+ // phase-0 receipt names none; the receipt's `session` wins when it does.
1342
+ // Empty is absent, as with --state.
1343
+ session: { type: "string", default: "" },
1344
+ // Minutes a live member token may go with no transcript in the session
1345
+ // directory before NO-TRANSCRIPT names it.
1346
+ "no-transcript-after": { type: "string", default: "5" },
1284
1347
  // Minutes a live token of each family may run before CHECK-LIVENESS names it.
1285
1348
  ...Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [flag, { type: "string", default: String(LIVENESS_DEFAULTS[family]) }])),
1286
1349
  };
@@ -1313,6 +1376,7 @@ function options() {
1313
1376
  implCap: positive("implementer-cap"), reviewerCap,
1314
1377
  maxReviews: values["max-reviews"] === undefined ? reviewerCap : positive("max-reviews"),
1315
1378
  fold: values["fold-unchanged"], apply: values.apply, state: values.state || statePath(NAME), scratch: values.scratch,
1379
+ session: values.session || null, noTranscriptAfter: positive("no-transcript-after"),
1316
1380
  liveness: Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [family, positive(flag)])),
1317
1381
  };
1318
1382
  }
@@ -1721,8 +1785,23 @@ function readReports(scratch, reporters) {
1721
1785
  return out;
1722
1786
  }
1723
1787
 
1788
+ // The transcript stems in `session`, off one readdir: no file in it is read.
1789
+ // The receipt's directory not being there yet holds no transcript, so it lists
1790
+ // none; a `--session` one that is not there is a path somebody typed, and is
1791
+ // no such case. One that cannot be listed is null and one stderr line — read
1792
+ // as empty, it would name every live member NO-TRANSCRIPT.
1793
+ function listTranscripts(session, { missingIsEmpty }) {
1794
+ try {
1795
+ return transcriptStems(readdirSync(session));
1796
+ } catch (e) {
1797
+ if (e.code === "ENOENT" && missingIsEmpty) return [];
1798
+ console.error(`${NAME}: transcripts not checked — cannot list ${session} (${e.code ?? e.message})`);
1799
+ return null;
1800
+ }
1801
+ }
1802
+
1724
1803
  function main() {
1725
- const { fold, apply, state: path, liveness, scratch: scratchFlag, ...caps } = options();
1804
+ const { fold, apply, state: path, liveness, scratch: scratchFlag, session: sessionFlag, noTranscriptAfter, ...caps } = options();
1726
1805
  const listPath = shortlistPath();
1727
1806
  const current = readShortlist(listPath);
1728
1807
  // Beside the shortlist, off the same git probe rather than a second one.
@@ -1755,6 +1834,24 @@ function main() {
1755
1834
  : {}));
1756
1835
  }
1757
1836
 
1837
+ // This run's phase 0, off its receipt: unfinished holds the same rows the
1838
+ // main checkout does, and never refuses the tick either. Judged against
1839
+ // the controller record this tick started from, and against whether that
1840
+ // record's process is still there: a finished receipt of the run before
1841
+ // carries the same `at` until this run's rotation writes the next.
1842
+ const receipt = readRunReceipt();
1843
+ const phase0 = phase0Gate(receipt.read, {
1844
+ path: receipt.path, controllerAt: controller?.at, controller: controllerState(controller),
1845
+ });
1846
+ // The session directory's listing, ahead of every ledger read: a dispatch is
1847
+ // written to the ledger before its `task` call makes the transcript, so a
1848
+ // stem listed here is on whatever ledger is read after. Listed later, a
1849
+ // dispatch landing in between would print UNRECORDED for a token the ledger
1850
+ // holds. This run's receipt's `session`, else --session, else no check.
1851
+ const session = phase0.session ?? sessionFlag;
1852
+ if (session === null) console.error(`${NAME}: transcripts not checked — no session in this run's phase-0 receipt and no --session`);
1853
+ const stems = session === null ? null : listTranscripts(session, { missingIsEmpty: phase0.session !== null });
1854
+
1758
1855
  // Every read happens before anything prints: a partial tick is worse than no
1759
1856
  // tick, because half a reconcile still reads like a reconcile. The APPLIED
1760
1857
  // lines are the exception, printed as each duty runs: they say what was
@@ -1767,15 +1864,6 @@ function main() {
1767
1864
  // every answer but `clean` is a hold on the dispatching rows plus one line
1768
1865
  // saying why, so the rest of the run keeps reporting.
1769
1866
  const mainCheckout = checkMainCheckout();
1770
- // This run's phase 0, off its receipt: unfinished holds the same rows the
1771
- // main checkout does, and never refuses the tick either. Judged against
1772
- // the controller record this tick started from, and against whether that
1773
- // record's process is still there: a finished receipt of the run before
1774
- // carries the same `at` until this run's rotation writes the next.
1775
- const receipt = readRunReceipt();
1776
- const phase0 = phase0Gate(receipt.read, {
1777
- path: receipt.path, controllerAt: controller?.at, controller: controllerState(controller),
1778
- });
1779
1867
 
1780
1868
  if (apply) {
1781
1869
  // Reap and reclaim after every merge pass settled `done` since the last
@@ -1855,6 +1943,13 @@ function main() {
1855
1943
  // Advisory the same way: a report on disk prints the settle it is for, and
1856
1944
  // nothing here runs it.
1857
1945
  const reported = reportLines({ reporters: run.reporters, reports, now, reportsFrom: scratch?.flagged ? reportsDir(scratch.root) : null });
1946
+ // Advisory the same way: a transcript the ledger records nowhere, and a live
1947
+ // member token with no transcript past `--no-transcript-after`. Neither is a
1948
+ // row, and nothing here dispatches, settles or kills.
1949
+ const transcribed = stems === null ? [] : [
1950
+ ...unrecordedLines({ stems, recorded: run.recorded }),
1951
+ ...noTranscriptLines({ live: run.live, seen, stems, session, after: noTranscriptAfter, now }),
1952
+ ];
1858
1953
  const above = [...(phase0.line === null ? [] : [phase0.line]), ...(said === null ? [] : [said]), ...stale.map((s) => s.line)];
1859
1954
  const rowLines = formatLines(rows);
1860
1955
  // The run is over once it is draining and nothing is left in flight: no
@@ -1863,13 +1958,14 @@ function main() {
1863
1958
  // last act, and only the controller can write it.
1864
1959
  const over = run.draining !== null && prs.length === 0 && run.implLive === 0;
1865
1960
  if (over) rowLines.push(RUN_OVER);
1866
- const lines = [...above, ...reported.map((r) => r.line), ...rowLines];
1961
+ const advice = [...transcribed, ...reported];
1962
+ const lines = [...above, ...advice.map((a) => a.line), ...rowLines];
1867
1963
 
1868
1964
  // The back-off streak and the fold digest, written on EVERY tick: an edge
1869
1965
  // tick that dispatched is the clearest possible "there is work here". Digest,
1870
- // not the lines themselves, so the file stays readable. A report line goes in
1871
- // without its age.
1872
- const digest = createHash("sha256").update([...above, ...reported.map((r) => r.key), ...rowLines].join("\n")).digest("hex");
1966
+ // not the lines themselves, so the file stays readable. A report or
1967
+ // NO-TRANSCRIPT line goes in without its age.
1968
+ const digest = createHash("sha256").update([...above, ...advice.map((a) => a.key), ...rowLines].join("\n")).digest("hex");
1873
1969
  const acts = actionable(rows) || over;
1874
1970
  // `seen` is pruned to the live set on the same write; an empty one removes
1875
1971
  // the key. A file that was degraded at this read is left byte-identical, so
@@ -1899,11 +1995,14 @@ function main() {
1899
1995
  // A report waiting on disk persists the same way, for as long as its
1900
1996
  // member stays live.
1901
1997
  const settle = reported.filter((r) => r.settle).map((r) => `; SETTLE ${r.member} persists`).join("");
1998
+ // A transcript the ledger lacks, or a live token lacking one, the same
1999
+ // way, for as long as it holds.
2000
+ const unmatched = transcribed.map((t) => `; ${t.kind} ${t.name} persists`).join("");
1902
2001
  // The to-spec drops the same way: advice, and the one reason an empty
1903
2002
  // shortlist is not "no work".
1904
2003
  const specs = specsDropped(dropped);
1905
2004
  const drops = specs ? `; ${specs} persists` : "";
1906
- console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held}${aged}${settle}${drops} — full rows on the next change`);
2005
+ console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held}${aged}${unmatched}${settle}${drops} — full rows on the next change`);
1907
2006
  return;
1908
2007
  }
1909
2008
  for (const line of lines) console.log(line);
@@ -1652,6 +1652,22 @@ depth** guard table applied in code. Act on each line as it reads:
1652
1652
  token. It repeats every tick while the token stays live past the threshold.
1653
1653
  `--liveness-impl`, `--liveness-fix-pr`, `--liveness-finisher`,
1654
1654
  `--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
1655
+ - `UNRECORDED <stem> (transcript exists, no ledger token)`, printed above the
1656
+ rows — the session directory holds a `<stem>.jsonl` whose stem is a member
1657
+ name no row token, `## Dispatched` entry or `## Retired` line names: a
1658
+ dispatch whose ledger write was forgotten. Record it with `ledger.mjs
1659
+ dispatch`, or confirm it is a stranger's member.
1660
+ Advice, like `CHECK-LIVENESS`: it resets no `quiet`, changes no row and
1661
+ frees no slot, it repeats every tick while it holds, and the folded line
1662
+ names it (`…; UNRECORDED <stem> persists — …`).
1663
+ - `NO-TRANSCRIPT <member> (live <age>m, no <session>/<member>.jsonl)`, printed
1664
+ above the rows — a live ledger token first seen more than
1665
+ `--no-transcript-after` minutes ago (default 5) has no transcript in the
1666
+ session directory: a dispatch whose `task` call was never made. Make the
1667
+ `task` call, or settle the token `killed`. Advice the same way, folded as
1668
+ `…; NO-TRANSCRIPT <member> persists — …`. Both lines read the session
1669
+ directory this run's phase-0 receipt names, else `--session <dir>`; with
1670
+ neither the tick skips them with one stderr line.
1655
1671
 
1656
1672
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
1657
1673
  phase 2's own step, run by `tick --apply`: a mismatch it finds is the
@@ -184,9 +184,10 @@ the run. `dispatch` refuses a retired name and names the replacement — one
184
184
  retry letter past the highest the session has used on that number,
185
185
  `impl-42-b` for a ticket this session's earlier run worked as `impl-42` —
186
186
  `review` refuses a retired runner name and names the next free reviewer
187
- name, and `dispatch merge-bot` numbers past retired bots. The tick never
188
- reads `## Retired`: a ticket an earlier run worked is not claimed by it
189
- and can be shortlisted again.
187
+ name, and `dispatch merge-bot` numbers past retired bots. The tick reads
188
+ `## Retired` only to account for a transcript in the session directory: a
189
+ ticket an earlier run worked is not claimed by it and can be shortlisted
190
+ again.
190
191
  A line it cannot parse is skipped with a warning naming it, and the
191
192
  rotation still succeeds; a member name on a skipped line that carries an
192
193
  outcome is retired all the same, and a bare member token on a skipped row