@feigi/fleet-ctl 3.67.0 → 3.68.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.67.0",
3
+ "version": "3.68.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": {
@@ -6,7 +6,7 @@
6
6
  #
7
7
  # The claim is branch `<type>/<issue>-<slug>` and worktree
8
8
  # `.worktrees/<issue>-<slug>`. The fleet always calls it as
9
- # `claim-ticket.sh <N> impl-<N> implementer` (run-team SKILL.md, **Claiming**),
9
+ # `claim-ticket.sh <N> impl-<N> implementer` (run-team references/pull.md, **Claiming**),
10
10
  # giving `implementer/<N>-impl-<N>` and `.worktrees/<N>-impl-<N>`, and releases
11
11
  # with the same pair through release-ticket.sh. <slug> and <type> are
12
12
  # free text — neither derived nor validated here — so a caller outside the fleet
@@ -9,7 +9,8 @@
9
9
  //
10
10
  // So compute the deficit instead of remembering it. Every wake ends in one
11
11
  // invocation (record, tick, act, beat), and each prints
12
- // actual/target and a named ACTION per role — `PULL #<n> #<n>`, `DISPATCH
12
+ // actual/target and a named ACTION per role — `PULL #<n> — pull.mjs next --head
13
+ // <n>`, one row per head, `DISPATCH
13
14
  // fix-pr PR#<pr>`, `DISPATCH review PR#<pr>`, `DISPATCH merge-bot`, `HOLD (…)`,
14
15
  // `REFRESHED shortlist: …` — with run-team's guards applied in code rather than
15
16
  // recalled from its table. You cannot forget what a script prints at you. A
@@ -101,6 +102,18 @@
101
102
  // CHECK-LIVENESS: the tick settles nothing. A review runner has no
102
103
  // report schema and files none, so no `review=` token is looked
103
104
  // up; a member with no schema is never checked against one.
105
+ // pulls `<scratch>/impl-<N>/pull.json`, pull.mjs's record of a Pull, for
106
+ // every head on the shortlist, `<scratch>` as for the report
107
+ // files. A question standing prints `PULL #<N> (Q<n> pending —
108
+ // pull.mjs answer <N> <qid> …)` in place of the fresh row, with
109
+ // ` (stale)` once the file is older than `--pull-stale-minutes`; a
110
+ // Pull that dispatched with the head still holding no `impl-` row
111
+ // prints `(dispatched, row missing — ledger.mjs row …)`. A Pull
112
+ // that ended in this run's session (the ticket left, or its claim
113
+ // was released) names no row: `pull.mjs next` skips it, `next
114
+ // --head` would start the ticket over, so the next head fills the
115
+ // slot. A record from another phase-0 session, or one unreadable
116
+ // or absent, is the fresh row: `pull.mjs next` starts or resumes it.
104
117
  // session The listing of the session directory omp writes one
105
118
  // `<member>.jsonl` transcript into per dispatched member: this
106
119
  // run's phase-0 receipt's `session`, else `--session`; with
@@ -131,7 +144,7 @@ export function reconcile(s) {
131
144
  // dispatch — so they stand outside the dispatch hold: the fix-applier a
132
145
  // conflict hold leads to obeys the hold through its own role's row.
133
146
  return [
134
- ...dispatchHold(s, [implementers(s), ...rev.rows]),
147
+ ...dispatchHold(s, [...implementers(s), ...rev.rows]),
135
148
  ...rev.conflictRows,
136
149
  ...dispatchHold(s, [mergeBot(s)]),
137
150
  ...shortlistRows(s),
@@ -221,12 +234,59 @@ function specsDropped(dropped) {
221
234
  return `specs-dropped=${[...by].map(([reason, ns]) => `${ns.join(" ")} (${reason})`).join(", ")}`;
222
235
  }
223
236
 
237
+ // The question numbers SKILL.md's phase 1 gives pull.mjs's questions. The row
238
+ // names the number and the command names the qid, which is what `pull.mjs
239
+ // answer` takes; a qid with no number here is named by itself.
240
+ const QUESTION_NUMBERS = { staleness: "Q1", close: "Q1b", decided: "Q2", collision: "Q3" };
241
+
242
+ /**
243
+ * Where a head's Pull stands, off its `pull.json` record as parsed, for the
244
+ * PULL row: `{kind: "pending", qid, stale}`, `{kind: "dispatched", text}` with
245
+ * the text the Pull's own `ledger.mjs row` wrote (null when it recorded none),
246
+ * `{kind: "ended"}` for a Pull that left or was released, or null for the
247
+ * fresh row. `since` is the file's mtime and `session` this run's phase-0
248
+ * session, null when the receipt names none.
249
+ */
250
+ export function pullOf(record, { session, since, now, staleMinutes }) {
251
+ if (record === null || typeof record !== "object" || Array.isArray(record)) return null;
252
+ // pull.mjs ends a record from another phase-0 session whatever it says, and
253
+ // starts the ticket afresh.
254
+ if (session !== null && record.session !== session) return null;
255
+ // pull.mjs's `next` skips a Pull that ended in this run, and `next --head`
256
+ // would start the ticket over: the head is no one for a PULL row to name.
257
+ if (record.status === "left" || record.status === "released") return { kind: "ended" };
258
+ if (record.status === "running" && typeof record.pending?.qid === "string") {
259
+ return { kind: "pending", qid: record.pending.qid, stale: now - since > staleMinutes * 60_000 };
260
+ }
261
+ if (record.status === "dispatched") {
262
+ const row = Array.isArray(record.commands)
263
+ ? record.commands.findLast((c) => c?.step === "row" && c.exit === 0 && Array.isArray(c.cmd))
264
+ : undefined;
265
+ return { kind: "dispatched", text: typeof row?.cmd[3] === "string" ? row.cmd[3] : null };
266
+ }
267
+ return null;
268
+ }
269
+
270
+ // A head's PULL action. A question standing is a Pull in progress: the fresh
271
+ // row there would ask it twice. A dispatched Pull whose head still holds no
272
+ // `impl-` row should not occur, and must not read as a fresh Pull either.
273
+ function pullAction(n, p) {
274
+ if (p?.kind === "pending") {
275
+ return `PULL #${n} (${QUESTION_NUMBERS[p.qid] ?? p.qid} pending — pull.mjs answer ${n} ${p.qid} …)${p.stale ? " (stale)" : ""}`;
276
+ }
277
+ if (p?.kind === "dispatched") return `PULL #${n} (dispatched, row missing — ledger.mjs row ${n} ${p.text === null ? "…" : JSON.stringify(p.text)})`;
278
+ return `PULL #${n} — pull.mjs next --head ${n}`;
279
+ }
280
+
281
+ // The implementer rows: one per head a free slot Pulls, else the one row
282
+ // saying why none is pulled.
224
283
  function implementers(s) {
225
284
  const dropped = specsDropped(s.dropped);
226
- const row = mkRow("implementers", s.inFlight, s.bound,
285
+ const one = mkRow("implementers", s.inFlight, s.bound,
227
286
  `implementers=${s.inFlightImpl} prs=${s.inFlightPrs} unclaimed=${s.heads.length} supply=${s.supply ?? "?"}`
228
287
  + (s.shortlistStatus === "ok" ? "" : ` shortlist=${s.shortlistStatus}`)
229
288
  + (dropped ? ` ${dropped}` : ""));
289
+ const row = (...a) => [one(...a)];
230
290
 
231
291
  // Drain stops supply and nothing else. Read from the file, so
232
292
  // a replacement controller that never saw the drain is held by it too.
@@ -263,9 +323,12 @@ function implementers(s) {
263
323
  return s.owedCounted.length ? row(hold, { acts: true, extra: replaceStep(s.owedCounted, s.implNames) }) : row(hold);
264
324
  }
265
325
 
266
- if (s.heads.length) return row(`PULL ${s.heads.slice(0, s.bound - s.inFlight).map((n) => `#${n}`).join(" ")}`, { acts: true });
326
+ // A head whose Pull ended in this run takes no slot: the next head does.
327
+ const pullable = s.heads.filter((n) => s.pulls?.get(n)?.kind !== "ended");
328
+ if (pullable.length) return pullable.slice(0, s.bound - s.inFlight).map((n) => one(pullAction(n, s.pulls?.get(n)), { acts: true }));
267
329
 
268
- // Nothing unclaimed even after a refresh. `SUGGEST /triage` asks a
330
+ // Nothing to Pull even after a refresh: no unclaimed head, or only heads
331
+ // whose Pull ended in this run, which `pull.mjs next` skips. `SUGGEST /triage` asks a
269
332
  // MAINTAINER to tick tickets, and on the unattended night the heartbeat
270
333
  // exists for there is nobody to ask — so it prints (the fold shows it once)
271
334
  // but is not actionable, or it would pin the interval at the base all night.
@@ -1378,6 +1441,9 @@ const OPTIONS = {
1378
1441
  // Minutes a live member token may go with no transcript in the session
1379
1442
  // directory before NO-TRANSCRIPT names it.
1380
1443
  "no-transcript-after": { type: "string", default: "5" },
1444
+ // Minutes a Pull's question may stand, its `pull.json` unwritten, before the
1445
+ // PULL row naming it says `(stale)`.
1446
+ "pull-stale-minutes": { type: "string", default: "120" },
1381
1447
  // Minutes a live token of each family may run before CHECK-LIVENESS names it.
1382
1448
  ...Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [flag, { type: "string", default: String(LIVENESS_DEFAULTS[family]) }])),
1383
1449
  };
@@ -1408,7 +1474,7 @@ function options() {
1408
1474
  return {
1409
1475
  bound: positive("in-flight"),
1410
1476
  fold: values["fold-unchanged"], apply: values.apply, state: values.state || statePath(NAME), scratch: values.scratch,
1411
- session: values.session || null, noTranscriptAfter: positive("no-transcript-after"),
1477
+ session: values.session || null, noTranscriptAfter: positive("no-transcript-after"), pullStaleMinutes: positive("pull-stale-minutes"),
1412
1478
  liveness: Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [family, positive(flag)])),
1413
1479
  };
1414
1480
  }
@@ -1850,8 +1916,28 @@ function listTranscripts(session, { missingIsEmpty }) {
1850
1916
  }
1851
1917
  }
1852
1918
 
1919
+ // Where each head's Pull stands, as pullOf() reads its record, for the heads
1920
+ // with one. A record that is not there, or cannot be read or parsed, is the
1921
+ // fresh row: `pull.mjs next` names one it cannot use, in its own words.
1922
+ function readPulls(scratch, heads, { session, now, staleMinutes }) {
1923
+ const out = new Map();
1924
+ for (const n of heads) {
1925
+ const path = join(scratch, `impl-${n}`, "pull.json");
1926
+ let since, record;
1927
+ try {
1928
+ since = statSync(path).mtimeMs;
1929
+ record = JSON.parse(readFileSync(path, "utf8"));
1930
+ } catch {
1931
+ continue;
1932
+ }
1933
+ const p = pullOf(record, { session, since, now, staleMinutes });
1934
+ if (p !== null) out.set(n, p);
1935
+ }
1936
+ return out;
1937
+ }
1938
+
1853
1939
  function main() {
1854
- const { fold, apply, state: path, liveness, scratch: scratchFlag, session: sessionFlag, noTranscriptAfter, ...caps } = options();
1940
+ const { fold, apply, state: path, liveness, scratch: scratchFlag, session: sessionFlag, noTranscriptAfter, pullStaleMinutes, ...caps } = options();
1855
1941
  const listPath = shortlistPath();
1856
1942
  const current = readShortlist(listPath);
1857
1943
  // Beside the shortlist, off the same git probe rather than a second one.
@@ -1972,15 +2058,23 @@ function main() {
1972
2058
  }
1973
2059
  }
1974
2060
 
2061
+ // The scratch root of the report files and the Pull records alike.
2062
+ const scratch = reportsScratch(receipt, scratchFlag);
2063
+ if (scratch === null) console.error(`${NAME}: report files and Pull records not checked — no scratch in the phase-0 receipt and no --scratch`);
2064
+ // Each head's Pull record read, not only the heads a free slot names: a head
2065
+ // whose Pull ended gives its slot to the next, so the heads past the slots
2066
+ // can fill one. The session it is judged against is the receipt's, as
2067
+ // pull.mjs judges it.
2068
+ const runSession = receipt.read.state === "ok" && receipt.read.receipt.session !== "" ? receipt.read.receipt.session : null;
2069
+ const pulls = scratch === null ? new Map()
2070
+ : readPulls(scratch.root, heads, { session: runSession, now: Date.now(), staleMinutes: pullStaleMinutes });
1975
2071
  const rows = reconcile({
1976
- ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router,
2072
+ ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router, pulls,
1977
2073
  });
1978
2074
  const said = describe(mainCheckout, run.live);
1979
2075
  // The report files of the live members, read before the state file for the
1980
2076
  // reason given below. A member's report on disk is the outcome its message
1981
2077
  // was to carry, whether or not that message arrived.
1982
- const scratch = reportsScratch(receipt, scratchFlag);
1983
- if (scratch === null) console.error(`${NAME}: report files not checked — no scratch in the phase-0 receipt and no --scratch`);
1984
2078
  const reports = scratch === null ? new Map() : readReports(scratch.root, run.reporters);
1985
2079
  // Re-read rather than reusing priorState: this must be the freshest
1986
2080
  // snapshot, or this tick reverts whatever the heartbeat wrote while the