@feigi/fleet-ctl 3.57.0 → 3.58.1

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.
@@ -5,7 +5,7 @@ model: "@slow:high"
5
5
  spawns: task
6
6
  ---
7
7
 
8
- You are a fleet fix-applier. Your brief — for a red-check fix, the prompt the controller writes by hand — names this dispatch's worktree, PR branch and test command, and the kind of work it is: a review's findings to apply or defer, a dispositions retry, a conflict hold to clear, or a red CI check to fix. The brief of a review and of a dispositions retry also names the scratch directory; a conflict hold's names none, so every rule below that cites `<scratch>` is for the kinds whose brief names one. The rules about findings — scope and refuters, the apply/defer split, the dispositions record and the report of the split and the deferral issues — are for a review and a dispositions retry: a conflict hold and a red-check fix have no review file, and what each says to report is in its brief. Every other rule below holds for every kind. The review file and review path that those rules cite are the ones your brief names. Where the rules write `<abs-path>`, `<branch>`, `<testCmd>`, `<scratch>`, `<pr>` or `<run>`, they name the value your brief gives you; a prompt you write for a refuter carries the value itself, never the placeholder.
8
+ You are a fleet fix-applier. Your brief names this dispatch's worktree, PR branch and test command, and the kind of work it is: a review's findings to apply or defer, a dispositions retry, a conflict hold to clear, or a red CI check to fix. The brief of a review and of a dispositions retry also names the scratch directory; a conflict hold's and a red-check fix's name none, so every rule below that cites `<scratch>` is for the kinds whose brief names one. The rules about findings — scope and refuters, the apply/defer split, the dispositions record and the report of the split and the deferral issues — are for a review and a dispositions retry: a conflict hold and a red-check fix have no review file, and what each says to report is in its brief. Every other rule below holds for every kind. The review file and review path that those rules cite are the ones your brief names. Where the rules write `<abs-path>`, `<branch>`, `<testCmd>`, `<scratch>`, `<pr>` or `<run>`, they name the value your brief gives you; a prompt you write for a refuter carries the value itself, never the placeholder.
9
9
 
10
10
  **`edit` and `read` resolve a bare relative path against the SESSION ROOT —
11
11
  the controller's own main checkout — not against that worktree and not
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.57.0",
3
+ "version": "3.58.1",
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
  // Roles: implementer, fix-applier, finisher, merge-bot, review-runner,
8
8
  // recipe-deriver. A role with kinds (fix-applier: review, conflict,
9
- // dispositions-retry; finisher: fresh, repair) requires --kind; a role
9
+ // dispositions-retry, red-check; finisher: fresh, repair) requires --kind; a role
10
10
  // without them refuses it as an unknown flag.
11
11
  //
12
12
  // OUTPUT. The brief on stdout and nothing else. With --json the payload
@@ -22,10 +22,11 @@
22
22
  import { createHash } from "node:crypto";
23
23
 
24
24
  // How an archive beside the ledger is named. `ledger.mjs rotate` files the
25
- // ledger as `ledger.<stamp>.md` and the two run receipts, the phase-0 one as
25
+ // ledger as `ledger.<stamp>.md`, the two run receipts, the phase-0 one as
26
26
  // `phase0.<stamp>.json` and the end-of-run one as `closeout.<stamp>.json`,
27
- // under one stamp. `phase0.mjs` files a phase-0 receipt the rotation left
28
- // behind the same way, so the format lives here once.
27
+ // and the briefs directory as `briefs.<stamp>`, all under one stamp.
28
+ // `phase0.mjs` files a phase-0 receipt the rotation left behind the same
29
+ // way, so the format lives here once.
29
30
  const RECEIPT_STEM = "phase0";
30
31
  export const RECEIPT = `${RECEIPT_STEM}.json`;
31
32
  export const archiveStamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
@@ -33,14 +34,20 @@ export const receiptArchiveName = (stamp) => `${RECEIPT_STEM}.${stamp}.json`;
33
34
  const CLOSEOUT_STEM = "closeout";
34
35
  export const CLOSEOUT_RECEIPT = `${CLOSEOUT_STEM}.json`;
35
36
  export const closeoutArchiveName = (stamp) => `${CLOSEOUT_STEM}.${stamp}.json`;
37
+ // The directory dispatch-prompt.mjs renders a member's brief into, beside the
38
+ // ledger, archived by the same rotate under the same stamp: `briefs.<stamp>`.
39
+ export const BRIEFS = "briefs";
40
+ export const briefsArchiveName = (stamp) => `${BRIEFS}.${stamp}`;
36
41
 
37
42
  // The outcome vocabulary, verbatim from the spec. A word is matched exactly,
38
43
  // except the three that carry a value, which match OUTCOME_PATTERNS below.
44
+ // `role` is the dispatch-prompt.mjs template a member of the family is
45
+ // rendered from, the one its brief's sidecar must name.
39
46
  const FAMILIES = {
40
- impl: { label: "impl-N", bound: "ticket", outcomes: ["PR#M", "bailed", "released", "killed", "tier-mismatch"] },
41
- "fix-pr": { label: "fix-pr-M", bound: "pr", outcomes: ["applied:<head>", "no-op", "failed", "killed"] },
42
- "finisher-pr": { label: "finisher-pr-M", bound: "pr", outcomes: ["labelled", "failed", "killed", "halted:<cause>"] },
43
- "merge-bot": { label: "merge-bot-n", bound: null, outcomes: ["done", "killed"] },
47
+ impl: { label: "impl-N", bound: "ticket", role: "implementer", outcomes: ["PR#M", "bailed", "released", "killed", "tier-mismatch"] },
48
+ "fix-pr": { label: "fix-pr-M", bound: "pr", role: "fix-applier", outcomes: ["applied:<head>", "no-op", "failed", "killed"] },
49
+ "finisher-pr": { label: "finisher-pr-M", bound: "pr", role: "finisher", outcomes: ["labelled", "failed", "killed", "halted:<cause>"] },
50
+ "merge-bot": { label: "merge-bot-n", bound: null, role: "merge-bot", outcomes: ["done", "killed"] },
44
51
  };
45
52
  // Every family parseMember can yield: MEMBER below is built from this list,
46
53
  // so every family it matches has an entry here by construction.
@@ -98,6 +105,36 @@ export function memberTokens(text) {
98
105
  return text.split(/\s+/).filter(Boolean).map(parseToken).filter(Boolean);
99
106
  }
100
107
 
108
+ /** The dispatch-prompt.mjs role a member of `family` is rendered as. */
109
+ export function memberRole(family) {
110
+ return FAMILIES[family].role;
111
+ }
112
+
113
+ // A `## Dispatched` entry is a member token, followed by `brief=<hash>` when
114
+ // `ledger.mjs dispatch` recorded the brief the member was dispatched with:
115
+ // the first 8 hex of the sha256 the brief's sidecar carries. `settle`
116
+ // rewrites the token and keeps the word beside it.
117
+ const BRIEF_WORD = /^brief=([0-9a-f]{8})$/;
118
+
119
+ /**
120
+ * `{token, brief}` for one `## Dispatched` entry: the member token and the
121
+ * brief's hash, or null for an entry without one. An entry that is not a
122
+ * member token plus one well-formed `brief=` word is returned whole as
123
+ * `token`, so a reader parsing it with parseToken() refuses it exactly as it
124
+ * refuses any other entry this grammar cannot parse.
125
+ */
126
+ export function parseDispatchedEntry(entry) {
127
+ const words = entry.split(" ");
128
+ const m = words.length === 2 ? BRIEF_WORD.exec(words[1]) : null;
129
+ if (m === null || parseToken(words[0]) === null) return { token: entry, brief: null };
130
+ return { token: words[0], brief: m[1] };
131
+ }
132
+
133
+ /** The `## Dispatched` entry for `token`, with `brief=<brief>` unless brief is null. */
134
+ export function dispatchedEntry(token, brief) {
135
+ return brief === null ? token : `${token} brief=${brief}`;
136
+ }
137
+
101
138
  // `PR#<n>` as a word of a row's text, `PR #<n>` too.
102
139
  const PR_MENTION = /\bPR\s*#(\d+)\b/;
103
140
 
@@ -12,7 +12,8 @@
12
12
  // `dispatch`, `settle`, `review` and `drain` exist so a reader can derive
13
13
  // every liveness count from this file alone, rather than from row text a
14
14
  // controller typed by hand: `dispatch` writes a member's live token onto its
15
- // row and appends it to `## Dispatched`, `settle` rewrites that token to
15
+ // row and appends it to `## Dispatched` with `brief=<hash>`, the brief it
16
+ // refuses to dispatch without, `settle` rewrites that token to
16
17
  // `<member>=<outcome>` in both places (an implementer's settle to `PR#M` also
17
18
  // folds the PR's own `#M` row into its ticket's), `review` appends a PR's
18
19
  // `review=`/`reviewed=` tokens to the PR's row, and `drain` writes the
@@ -42,12 +43,13 @@
42
43
  // the rule).
43
44
 
44
45
  import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync, linkSync } from "node:fs";
46
+ import { createHash } from "node:crypto";
45
47
  import { dirname, resolve, join, basename } from "node:path";
46
48
  import { fileURLToPath } from "node:url";
47
49
  import { spawnSync, execFileSync } from "node:child_process";
48
50
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
49
51
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
50
- import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
52
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
51
53
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
52
54
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
53
55
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -465,7 +467,7 @@ function sectionOf(text, name) {
465
467
  }
466
468
 
467
469
  function load() {
468
- if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], drain: null, retired: [] };
470
+ if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], briefs: {}, drain: null, retired: [] };
469
471
  let text;
470
472
  try {
471
473
  text = readFileSync(file, "utf8");
@@ -491,11 +493,23 @@ function load() {
491
493
  }
492
494
  return {
493
495
  rows: section(ROWS), filed: section(FILED), ruled: section(RULED),
494
- dispatched: section(DISPATCHED), drain: drainEntries[0] ?? null,
496
+ ...dispatchedOf(section(DISPATCHED)), drain: drainEntries[0] ?? null,
495
497
  retired: section(RETIRED),
496
498
  };
497
499
  }
498
500
 
501
+ // `## Dispatched` held as its tokens, which is what every reader of `read`
502
+ // parses, and `briefs`, each member's `brief=` hash by name: one token per
503
+ // member name for the session, so a settle that rewrites the token keeps the
504
+ // name its brief is filed under. save() joins them back.
505
+ function dispatchedOf(entries) {
506
+ const parsed = entries.map(parseDispatchedEntry);
507
+ return {
508
+ dispatched: parsed.map((p) => p.token),
509
+ briefs: Object.fromEntries(parsed.filter((p) => p.brief !== null).map((p) => [parseToken(p.token).name, p.brief])),
510
+ };
511
+ }
512
+
499
513
  // `## Drain` is written only once there is a marker to hold: an empty section
500
514
  // under that name would read, to anyone scanning the file by eye, as a run
501
515
  // that is draining. `## Retired` likewise: only an `ancestor` rotate writes
@@ -506,7 +520,7 @@ function save(d) {
506
520
  const list = (entries) => entries.map((r) => `- ${escapeText(r)}`).join("\n");
507
521
  const out =
508
522
  `# Fleet run ledger\n\n${ROWS}\n\n` + list(d.rows) +
509
- `\n\n${DISPATCHED}\n\n` + list(d.dispatched) +
523
+ `\n\n${DISPATCHED}\n\n` + list(d.dispatched.map((t) => dispatchedEntry(t, d.briefs[parseToken(t)?.name] ?? null))) +
510
524
  `\n\n${FILED}\n\n` + list(d.filed) +
511
525
  `\n\n${RULED}\n\n` + list(d.ruled) +
512
526
  (d.drain === null ? "" : `\n\n${DRAIN}\n\n` + list([d.drain])) +
@@ -1448,7 +1462,8 @@ function runCheck() {
1448
1462
  // atomically when that name is already taken rather than overwriting an older
1449
1463
  // archive. The two receipts beside the ledger, `phase0.json` and
1450
1464
  // `closeout.json`, belong to the same run, so each is archived as
1451
- // `<name>.<stamp>.json` under the ledger archive's own stamp — a warning-only
1465
+ // `<name>.<stamp>.json` under the ledger archive's own stamp, and the
1466
+ // `briefs` directory beside them as `briefs.<stamp>` — a warning-only
1452
1467
  // move after the ledger move, refused up front only when a name is taken.
1453
1468
  //
1454
1469
  // What follows depends on the verdict below. After a `dead` or `none` one
@@ -1556,7 +1571,7 @@ function runRotate() {
1556
1571
  }
1557
1572
  // Read before anything moves: a ledger whose live tokens cannot be read is
1558
1573
  // refused with nothing moved, never archived with those tokens dropped.
1559
- let carry = { rows: [], dispatched: [], retired: [], skipped: [] };
1574
+ let carry = { rows: [], dispatched: [], briefs: {}, retired: [], skipped: [] };
1560
1575
  if (prior === "ancestor" && exists) {
1561
1576
  let text;
1562
1577
  try {
@@ -1569,10 +1584,12 @@ function runRotate() {
1569
1584
  const carrying = carry.rows.length > 0 || carry.dispatched.length > 0 || carry.retired.length > 0;
1570
1585
  // The receipts beside the ledger belong to the run being rotated away, so
1571
1586
  // each takes the archive's own stamp: `phase0.<stamp>.json` and
1572
- // `closeout.<stamp>.json` next to `ledger.<stamp>.md`. A name already taken
1573
- // refuses before anything moves, as the ledger's own does.
1587
+ // `closeout.<stamp>.json` next to `ledger.<stamp>.md`, and the briefs
1588
+ // directory `briefs.<stamp>`, so no brief of that run is found under a
1589
+ // name the next run dispatches. A name already taken refuses before
1590
+ // anything moves, as the ledger's own does.
1574
1591
  const stamp = archiveStamp();
1575
- const receipts = [[RECEIPT, receiptArchiveName], [CLOSEOUT_RECEIPT, closeoutArchiveName]]
1592
+ const receipts = [[RECEIPT, receiptArchiveName], [CLOSEOUT_RECEIPT, closeoutArchiveName], [BRIEFS, briefsArchiveName]]
1576
1593
  .map(([name, archiveName]) => ({ from: join(dirname(file), name), to: join(dirname(file), archiveName(stamp)) }))
1577
1594
  .filter(({ from }) => existsSync(from));
1578
1595
  for (const { to } of receipts) {
@@ -1615,7 +1632,7 @@ function runRotate() {
1615
1632
  // Nothing to carry writes nothing, so the next write starts the skeleton
1616
1633
  // exactly as after any other verdict.
1617
1634
  if (carrying) {
1618
- save({ rows: carry.rows, dispatched: carry.dispatched, filed: [], ruled: [], drain: null, retired: carry.retired });
1635
+ save({ rows: carry.rows, dispatched: carry.dispatched, briefs: carry.briefs, filed: [], ruled: [], drain: null, retired: carry.retired });
1619
1636
  }
1620
1637
  if (archive !== null) console.error(` rotated ${file} -> ${archive}`);
1621
1638
  for (const { line, why } of carry.skipped) {
@@ -1676,7 +1693,10 @@ function carryOf(text) {
1676
1693
  return false;
1677
1694
  }
1678
1695
  });
1679
- const allDispatched = sectionOf(text, DISPATCHED);
1696
+ // An entry's `brief=` travels with it: save() writes a brief only beside
1697
+ // the token it writes, so a carried member's record still names the brief
1698
+ // it was dispatched with and a dropped member's does not.
1699
+ const { dispatched: allDispatched, briefs: allBriefs } = dispatchedOf(sectionOf(text, DISPATCHED));
1680
1700
  const dispatched = allDispatched.filter((e) => {
1681
1701
  const t = parseToken(e);
1682
1702
  if (t !== null && t.error === null) return true;
@@ -1691,7 +1711,7 @@ function carryOf(text) {
1691
1711
  const live = liveOnLedger(rows, dispatched);
1692
1712
  const carried = { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched };
1693
1713
  const retired = retiredOnLedger([...rows, ...skippedRows], allDispatched, archivedRetired, carried);
1694
- return { ...carried, retired, skipped };
1714
+ return { ...carried, briefs: allBriefs, retired, skipped };
1695
1715
  }
1696
1716
 
1697
1717
  // ── dispatch / settle ────────────────────────────────────────────────────────
@@ -1931,6 +1951,10 @@ function runDispatch() {
1931
1951
  die(`${member.name}: ${e.message} — not dispatching ${member.name}`);
1932
1952
  }
1933
1953
 
1954
+ // Last, so every refusal above still names its own cause first, and before
1955
+ // anything is written.
1956
+ const brief = renderedBrief(member.name, memberRole(member.family));
1957
+
1934
1958
  let line = null;
1935
1959
  const created = member.bound !== null && i === -1;
1936
1960
  if (created) {
@@ -1944,13 +1968,60 @@ function runDispatch() {
1944
1968
  data.rows[i] = line;
1945
1969
  }
1946
1970
  data.dispatched.push(member.name);
1971
+ data.briefs[member.name] = brief.sha256.slice(0, 8);
1947
1972
  save(data);
1948
1973
  console.error(` dispatched ${member.name}`);
1949
1974
  console.log(JSON.stringify({
1950
- member: member.name, agent, ticket: line === null ? null : rowKey(line), line, created, total: data.dispatched.length,
1975
+ member: member.name, agent, ticket: line === null ? null : rowKey(line), line, created, total: data.dispatched.length, brief,
1951
1976
  }));
1952
1977
  }
1953
1978
 
1979
+ // The brief `name` is dispatched with, as dispatch-prompt.mjs `render
1980
+ // --member <name>` left it in the briefs directory beside the ledger: the
1981
+ // sidecar `<name>.json` must exist, name `role` — the template of the
1982
+ // member's family — and carry the brief's sha256, and the brief file beside
1983
+ // it, `<name>.md`, must exist and hash to it. `{path, sha256}` comes back,
1984
+ // `path` that file, so the controller hands the `task` call its content from
1985
+ // the path printed. Refused, nothing is written.
1986
+ function renderedBrief(name, role) {
1987
+ const dir = resolve(dirname(file), BRIEFS);
1988
+ const sidecar = join(dir, `${name}.json`);
1989
+ const render = `run \`dispatch-prompt.mjs render ${role} --member ${name} …\` with the ${role} template's arguments, then dispatch again`;
1990
+ let text;
1991
+ try {
1992
+ text = readFileSync(sidecar, "utf8");
1993
+ } catch (e) {
1994
+ if (e.code === "ENOENT") die(`no rendered brief for ${name} — ${render} (${sidecar} does not exist)`);
1995
+ die(`cannot read ${sidecar}: ${e.message} — not dispatching ${name}`);
1996
+ }
1997
+ let s;
1998
+ try {
1999
+ s = JSON.parse(text);
2000
+ } catch (e) {
2001
+ die(`${sidecar} is not JSON (${e.message}) — ${render}`);
2002
+ }
2003
+ if (s === null || typeof s !== "object" || Array.isArray(s)) die(`${sidecar} is not a JSON object — ${render}`);
2004
+ if (s.role !== role) {
2005
+ die(`${sidecar} is a brief for role ${JSON.stringify(s.role ?? null)}, but ${name} is dispatched as ${role} — ${render}`);
2006
+ }
2007
+ if (typeof s.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(s.sha256)) {
2008
+ die(`${sidecar} carries no sha256 of 64 lowercase hex (${JSON.stringify(s.sha256 ?? null)}) — ${render}`);
2009
+ }
2010
+ const path = join(dir, `${name}.md`);
2011
+ let brief;
2012
+ try {
2013
+ brief = readFileSync(path);
2014
+ } catch (e) {
2015
+ if (e.code === "ENOENT") die(`no rendered brief for ${name} — ${render} (${path} does not exist)`);
2016
+ die(`cannot read ${path}: ${e.message} — not dispatching ${name}`);
2017
+ }
2018
+ const actual = createHash("sha256").update(brief).digest("hex");
2019
+ if (actual !== s.sha256) {
2020
+ die(`${path} hashes to ${actual}, but ${sidecar} carries ${s.sha256} — ${render}`);
2021
+ }
2022
+ return { path, sha256: s.sha256 };
2023
+ }
2024
+
1954
2025
  function runSettle() {
1955
2026
  const usage = "usage: ledger.mjs settle <member> <outcome>";
1956
2027
  // `settle impl-<N> PR#<n>`, or the one token it writes — `settle