@feigi/fleet-ctl 3.57.0 → 3.58.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.
@@ -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.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
  // 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
@@ -611,7 +611,8 @@ phase, or in any later one, asks the maintainer which tickets to take.
611
611
  --oneline origin/main..HEAD`, `git -C <worktree> status --short`, and the
612
612
  files under `<scratch>/impl-<N>/`). Record it the ordinary way —
613
613
  `ledger.mjs row <N>
614
- "impl-<N>-b"`, then `ledger.mjs dispatch <N> impl-<N>-b`, then the `task`
614
+ "impl-<N>-b"`, then `dispatch-prompt.mjs render implementer --member
615
+ impl-<N>-b …`, then `ledger.mjs dispatch <N> impl-<N>-b`, then the `task`
615
616
  call naming the `agent` it printed, then the tier check — and never
616
617
  `claim-ticket.sh`: the claim already stands. A `report` goes to the
617
618
  maintainer as `#<N> — <why>` and nothing else: no dispatch, no label change,
@@ -1157,12 +1158,16 @@ a worktree, a branch and an `in-progress` label with no member behind them,
1157
1158
  released by the end-of-run sweep rather than by a member that did the work.
1158
1159
 
1159
1160
  **Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
1160
- the Pull's step 7; `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
1161
- then marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
1162
- Its JSON carries `agent`, the definition that call names — read it off that
1163
- output, never recall it. Live implementers are the `impl-` tokens with no
1161
+ the Pull's step 7; `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
1162
+ implementer --member impl-<N> …` then renders its brief, and
1163
+ `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
1164
+ marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
1165
+ Its JSON carries `agent`, the definition that call names, and `brief.path`,
1166
+ the rendered brief whose content is that call's prompt — read both off that
1167
+ output, never recall them. Live implementers are the `impl-` tokens with no
1164
1168
  `=<outcome>` — the tick reads that count off the ledger, and nobody states
1165
- it. `dispatch` refuses once the
1169
+ it. `dispatch` refuses a member with no brief rendered for its role, naming
1170
+ the `render` command to run first, and refuses once the
1166
1171
  run is draining: drain stops supply. It also refuses a row whose `tier=`
1167
1172
  names no single definition — two different values, or one that is not a
1168
1173
  definition suffix — or names one with no `agents/<definition>.agent.md`,
@@ -1935,8 +1940,10 @@ depth** guard table applied in code. Act on each line as it reads:
1935
1940
  list shows PR M without `ready-to-merge`, and no `label-off=` (**Run ledger**)
1936
1941
  accounts for the removal. Apply the finisher gate (**Reviewers**: the
1937
1942
  `check` job green on the current head), then dispatch the next-suffix
1938
- finisher at that head — `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`, one
1939
- letter past the highest the PR has used. Never add the label yourself. A head
1943
+ finisher at that head, one letter past the highest the PR has used: render
1944
+ its brief with `dispatch-prompt.mjs render finisher --kind repair --member
1945
+ finisher-pr-<M>-<x> …`, then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`.
1946
+ Never add the label yourself. A head
1940
1947
  that moved is caught by the new finisher's duty 1 `past-pin` halt and the
1941
1948
  re-review path that follows it. Finishers take no reviewer slot, so this
1942
1949
  prints whatever the reviewer cap reads.
@@ -2601,8 +2608,9 @@ no review fix-applier
2601
2608
  has landed `applied:`/`no-op` on since, with no fix-applier live on it — one
2602
2609
  named member per PR, `fix-pr-<pr#>` (the next suffix when that name is already
2603
2610
  on record), never the PR's
2604
- implementer, recorded with `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the
2605
- call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
2611
+ implementer, its brief rendered with `dispatch-prompt.mjs render fix-applier
2612
+ --kind review --member fix-pr-<pr#> …` and then recorded with `ledger.mjs
2613
+ dispatch <pr#> fix-pr-<pr#>` before the call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
2606
2614
  the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`,
2607
2615
  `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>`
2608
2616
  in that prompt is the absolute path `scratch-root.mjs` printed, the
@@ -2619,7 +2627,9 @@ unresolved `conflict-hold:#<M>`, the merge bot's (`run-merge-bot.md` step 1's
2619
2627
  fallback) or one you recorded off the tick's `CONFLICT` line —
2620
2628
  is the same slot with a different job, and no review file to hand
2621
2629
  over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2622
- already on record — `dispatch` refuses a reused one — and dispatch it with the
2630
+ already on record — `dispatch` refuses a reused one — render its brief with
2631
+ `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`,
2632
+ and dispatch it with the
2623
2633
  `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
2624
2634
  `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
2625
2635
  row's `tier=` — read it off that output, never recall it. Its prompt takes the prompt below's
@@ -2661,7 +2671,8 @@ edges are the only route there, so do not wait for an event. Edit one of these
2661
2671
  bullets without the others and what strands is exactly the red-only PR.
2662
2672
 
2663
2673
  Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
2664
- refuses a reused name — record it with `ledger.mjs dispatch <pr#> <name>`
2674
+ refuses a reused name — render its brief with `dispatch-prompt.mjs render
2675
+ fix-applier --kind red-check --member <name> …`, record it with `ledger.mjs dispatch <pr#> <name>`
2665
2676
  before the call, and dispatch it with the `agent` that command printed
2666
2677
  (`fleet-fix-applier`, as for a review fix-applier), in the PR's
2667
2678
  existing worktree. Its prompt takes the prompt below's worktree, branch and
@@ -2680,7 +2691,7 @@ reach green" covers.
2680
2691
  **A `DISPATCH fix-pr PR#<M>` on a dispositions mismatch** — the PR's row carries
2681
2692
  `dispositions-mismatch=<member>:<run>` for its latest review's run, and no later
2682
2693
  fix-applier has landed — is one automatic retry, a review fix-applier named the
2683
- next suffix (`fix-pr-<M>-b`) and dispatched like the first. Its prompt is the
2694
+ next suffix (`fix-pr-<M>-b`) and dispatched like the first, its brief rendered with `--kind dispositions-retry`. Its prompt is the
2684
2695
  first one's, with three paths and a list copied in: the review file
2685
2696
  `<scratch>/pr<M>/<run>/review.json`, the mismatched member's record `<scratch>/dispositions-<member>.json`
2686
2697
  it starts from, its own record `<scratch>/dispositions-<its own name>.json` it writes, and the check's violation list **verbatim** — the lines
@@ -3155,7 +3166,9 @@ infer, see the five-condition note in the fix-applier block above) — or
3155
3166
  `ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
3156
3167
  has returned and its fix-applier, if one was dispatched, has sent its report,
3157
3168
  which the CI-completes edge above states in full** — dispatch a
3158
- **finisher** — a fresh small agent, not the fix-applier resumed. Record it with
3169
+ **finisher** — a fresh small agent, not the fix-applier resumed. Render its brief
3170
+ with `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<pr#> …`
3171
+ (`--kind repair` once an earlier finisher reported `labelled` without the label landing), record it with
3159
3172
  `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call, then **dispatch
3160
3173
  it with the `agent` that command printed and omit `model` on the call** — the
3161
3174
  tier lives in that definition's frontmatter, `agents/fleet-finisher.agent.md`,
@@ -3580,8 +3593,11 @@ REVIEW-column open PR without the label, whose latest finisher attempt settled
3580
3593
  so, `finisher:failed` or `finisher:killed` at severity 4 — one token per
3581
3594
  outcome, neither the implementer's bare `killed` flag nor `unlabelled`. You
3582
3595
  resolve it by hand: investigate why the finisher died, or dispatch the
3583
- next-suffix finisher after the finisher gate, `ledger.mjs dispatch <M>
3584
- finisher-pr-<M>-<x>`. The flag clears when a later attempt settles — `labelled`
3596
+ next-suffix finisher after the finisher gate: render its brief with
3597
+ `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<M>-<x>
3598
+ …` (`--kind repair` once an earlier finisher reported `labelled` without the
3599
+ label landing), then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`. The flag
3600
+ clears when a later attempt settles — `labelled`
3585
3601
  (then `unlabelled` takes over while the label is still off), `halted:<cause>`,
3586
3602
  or a live `-b` — or when the PR carries `ready-to-merge`, merges or closes.
3587
3603
  You never add the label yourself, and the tick does not retry.
@@ -3650,7 +3666,10 @@ merge-bot` names it before the dispatch call — `n` is 1 + the highest
3650
3666
  `merge-bot-<n>` the session holds, in the ledger's `## Dispatched` list, on a
3651
3667
  row or in `## Retired`, so it restarts at 1 only when none was carried or
3652
3668
  retired (a `dead` or `none` rotate, or a fresh start), a replacement for a
3653
- dead bot takes the next `n`, and nobody counts. Dispatch
3669
+ dead bot takes the next `n`, and nobody counts. With no brief rendered for
3670
+ that name it refuses, naming the bot and the `dispatch-prompt.mjs render
3671
+ merge-bot --member merge-bot-<n> …` to run — render it, then run `ledger.mjs
3672
+ dispatch merge-bot` again. Dispatch
3654
3673
  it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
3655
3674
  enough, and it never waits for the finisher's report. Tell it to read
3656
3675
  `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
@@ -4336,13 +4355,16 @@ it settles** — the grammar is `ledger-grammar.mjs`'s, and the tick derives eve
4336
4355
  live count from it, so nobody states one. Write neither by hand:
4337
4356
 
4338
4357
  - **`ledger.mjs dispatch <ticket|pr> <member>`** — before the dispatch call,
4339
- marks the member live on its row and appends it to `## Dispatched`. `dispatch
4358
+ marks the member live on its row and appends it to `## Dispatched` with
4359
+ `brief=<first 8 hex of its brief's sha256>`. `dispatch
4340
4360
  merge-bot` names the next bot itself. It prints `{member, agent, ticket,
4341
- line, created, total}`; `agent` is the definition the `task` call names — an
4361
+ line, created, total, brief}`, `brief` the `{path, sha256}` of the rendered
4362
+ brief the `task` call is handed; `agent` is the definition the `task` call names — an
4342
4363
  implementer's comes off its row's `tier=` (phase 2's tier check states the
4343
4364
  mapping), a finisher's and a merge bot's are their own definitions, and a
4344
4365
  fix-applier's is `fleet-fix-applier` for every kind of work. It
4345
- refuses a name this session already used — on the ledger or in its
4366
+ refuses a member whose `briefs/<member>.json` beside the ledger is missing,
4367
+ names another role or carries no sha256, a brief file beside it that is missing or does not hash to that sha256, a name this session already used — on the ledger or in its
4346
4368
  `## Retired` — and names the replacement (`-b`, `-c` …), a
4347
4369
  second live member on one ticket or PR, any implementer once the run is
4348
4370
  draining, an implementer whose row's `tier=` names no single definition
@@ -25,6 +25,13 @@ it. Do NOT create another worktree. There is no review file: the PR sits on a
25
25
  conflict hold and you are here to clear it — do not review, do not dispatch
26
26
  specialists.
27
27
 
28
+ ## kind: red-check
29
+ You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
30
+ push destination below, given to you because a detached worktree cannot supply
31
+ it. Do NOT create another worktree. There is no review file: the PR's `check`
32
+ job is red on its current head and you are here to fix it — do not review, do
33
+ not dispatch specialists.
34
+
28
35
  ## kind: review, dispositions-retry
29
36
  Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
30
37
  and 5 only**: split apply-now/defer, commit, push, file every deferral as its
@@ -60,6 +67,13 @@ Bring `<branch>` current with `origin/main`, resolving every conflict by the
60
67
  Run `<testCmd>` from the worktree before you push, then push with
61
68
  `git push origin HEAD:<branch>`. Report the new head, or that no conflict was
62
69
  left.
70
+ ## kind: red-check
71
+ Read the failing job's log and fix the cause. Run `<testCmd>` from the
72
+ worktree before you push, then push with `git push origin HEAD:<branch>`.
73
+ Report the new head and **stop**: do not watch, poll or wait for CI — the
74
+ controller owns the next run on the pushed head. A red that is not yours to
75
+ fix — a flake that passes on rerun, or staleness — gets nothing pushed: report
76
+ that instead.
63
77
  ## kind: dispositions-retry
64
78
 
65
79
  This is the one automatic retry of a dispositions mismatch. The mismatched