@feigi/fleet-ctl 3.58.1 → 3.59.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.
@@ -215,15 +215,18 @@ three does not gate on one, and the script says so in its receipt. Put the
215
215
  receipt, the JSON line it printed, in your report as printed: it is what tells
216
216
  the controller the label is on.
217
217
 
218
- Report to the controller the label (the script's receipt, the JSON line it printed, as
219
- printed), the deferral issue numbers — a `filed: #N <subject>` line for
220
- every issue duty 2 created, and `unrecorded: #N <subject>` for one whose
221
- `filed` failed twice — and anything
222
- it halted on — cause and evidence, below, never a bare "head moved". The
218
+ Report to the controller in the report file your brief names,
219
+ `<scratch>/reports/<your name>.json`: `outcome` `labelled`, `halted` or
220
+ `failed`; `labelsReadBack` the labels the script's receipt read back; the
221
+ deferral issues as `{issue, subject}` entries — `filed` for every issue duty 2
222
+ created, and `unrecorded` for one whose `filed` failed twice, which the
223
+ controller's settle records — and, for anything it halted on, `cause` and
224
+ `evidence`, below, never a bare "head moved". The
223
225
  cause is one word of the ledger's `halted:<cause>` vocabulary:
224
226
  `live-editor`, `rebase`, `past-pin`, `unreadable`, `missing` or `absent` as
225
227
  duty 1's verdict names it, and `other` for every other halt — that
226
228
  verdict's own `other`, and a halt at duty 2, duty 3 or the instrument
227
- re-check. A duty 1 halt's report carries the verdict as
228
- printed, the JSON line, so a `rebase` halt's report carries the output of
229
- `git cherry <pin> HEAD origin/main` that its `evidence` holds.
229
+ re-check. A duty 1 halt's `evidence` carries the verdict as
230
+ printed, the JSON line, so a `rebase` halt's carries the output of
231
+ `git cherry <pin> HEAD origin/main`. Then send the one line your brief gives,
232
+ `<your name>: <outcome> <path>`.
@@ -5,7 +5,7 @@ model: "@slow:high"
5
5
  spawns: task
6
6
  ---
7
7
 
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.
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. Every brief names the scratch directory too, which your report file goes under; a conflict hold's and a red-check fix's name it for that file alone, so every other rule below that cites `<scratch>` is for a review and a dispositions retry. 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
@@ -155,9 +155,9 @@ arrived, so it defers like a refuted one.
155
155
  defers either way, never applied.** Refuted → the closed suggestion-band
156
156
  record, never an open issue. Survived, or its refuter crashed or abstained →
157
157
  its own open issue labelled `needs-triage`, citing the verdict, or the run
158
- that crashed, in the body. There is no cap on these refuters: count the ones
159
- you dispatch against out-of-scope suggestions, since your report names that
160
- count.
158
+ that crashed, in the body. There is no cap on these refuters: your
159
+ disposition record names each one you dispatch against an out-of-scope
160
+ suggestion, by the `verdictPath` of the suggestion's entry.
161
161
 
162
162
  **A finding's `suggested_fix` is a hypothesis, not a patch — the review never
163
163
  ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
@@ -319,13 +319,17 @@ in-scope `survived` finding verified correct, needing no change, is deferred
319
319
  with `reason` `false-rationale` and filed on the closed suggestion-band
320
320
  record.
321
321
 
322
- Then report to the controller the pushed SHA, your apply/defer split, how
323
- many refuters you dispatched against out-of-scope suggestions, and
324
- the deferral issue numbers — a `filed: #N <subject>` line for every issue
325
- step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
326
- failed twice — and exit. **Deferring everything is a normal
322
+ Then write your report to the file your brief names,
323
+ `<scratch>/reports/<your name>.json`: `head` the pushed SHA, `applied` and
324
+ `deferred` your apply/defer split by bucket and index, each deferral's issue
325
+ number on its `deferred` entry, the deferral issues as `{issue, subject}`
326
+ entries — `filed` for every issue step 5 created, and `unrecorded` for one
327
+ whose `ledger.mjs filed` failed twice, which the controller's settle records —
328
+ `dispositionsRecord` your record's path and `testRun` your test result. Then
329
+ send the one line your brief gives, `<your name>: <outcome> <path>`, and exit.
330
+ **Deferring everything is a normal
327
331
  outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
328
- index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
329
- report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
332
+ index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and your
333
+ report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
330
334
  explicitly — silence there is indistinguishable from a member that died. Never
331
335
  manufacture a commit to make CI fire.
@@ -223,10 +223,14 @@ output, because that format will change and this line has to outlive it. A
223
223
  verdict with nothing beside it is indistinguishable from a guess, and is
224
224
  recorded as one. The controller reads this line as a difficulty covariate when
225
225
  it rules your review, and the PR body is the only place it survives your exit.
226
- **Report to the controller the PR number, the head SHA, and WHEN you ran
227
- `sizing-a-ticket` relative to opening the PR** — "ran sizing-a-ticket at step
228
- 6, before `gh pr create`" if you kept that order, and say so plainly if you did
229
- not, including if the `Sizing:` line was written before the run and corrected
230
- after. Nothing in the PR body separates a measured verdict from one typed in
231
- early; that clause is the only thing that does, and an unreported ordering
232
- costs the covariate. Then exit. Never apply `ready-to-merge`, never merge.
226
+ **Report to the controller in the report file your brief names,
227
+ `<scratch>/reports/<your name>.json`: the PR number, the head SHA, and WHEN you
228
+ ran `sizing-a-ticket` relative to opening the PR** — `sizing.ranBeforePr` true
229
+ if you ran it at step 6, before `gh pr create`, and false if you did not,
230
+ including if the `Sizing:` line was written before the run and corrected after;
231
+ `sizing.verdict` and `sizing.signal` are that line's verdict and signal.
232
+ Nothing in the PR body separates a measured verdict from one typed in early;
233
+ that field is the only thing that does, and an unreported ordering costs the
234
+ covariate. A bail is `outcome` `bailed`, its cause in `bailCause`. Then send
235
+ the one line your brief gives, `<your name>: <outcome> <path>`, and exit. Never
236
+ apply `ready-to-merge`, never merge.
@@ -223,10 +223,14 @@ output, because that format will change and this line has to outlive it. A
223
223
  verdict with nothing beside it is indistinguishable from a guess, and is
224
224
  recorded as one. The controller reads this line as a difficulty covariate when
225
225
  it rules your review, and the PR body is the only place it survives your exit.
226
- **Report to the controller the PR number, the head SHA, and WHEN you ran
227
- `sizing-a-ticket` relative to opening the PR** — "ran sizing-a-ticket at step
228
- 6, before `gh pr create`" if you kept that order, and say so plainly if you did
229
- not, including if the `Sizing:` line was written before the run and corrected
230
- after. Nothing in the PR body separates a measured verdict from one typed in
231
- early; that clause is the only thing that does, and an unreported ordering
232
- costs the covariate. Then exit. Never apply `ready-to-merge`, never merge.
226
+ **Report to the controller in the report file your brief names,
227
+ `<scratch>/reports/<your name>.json`: the PR number, the head SHA, and WHEN you
228
+ ran `sizing-a-ticket` relative to opening the PR** — `sizing.ranBeforePr` true
229
+ if you ran it at step 6, before `gh pr create`, and false if you did not,
230
+ including if the `Sizing:` line was written before the run and corrected after;
231
+ `sizing.verdict` and `sizing.signal` are that line's verdict and signal.
232
+ Nothing in the PR body separates a measured verdict from one typed in early;
233
+ that field is the only thing that does, and an unreported ordering costs the
234
+ covariate. A bail is `outcome` `bailed`, its cause in `bailCause`. Then send
235
+ the one line your brief gives, `<your name>: <outcome> <path>`, and exit. Never
236
+ apply `ready-to-merge`, never merge.
@@ -223,10 +223,14 @@ output, because that format will change and this line has to outlive it. A
223
223
  verdict with nothing beside it is indistinguishable from a guess, and is
224
224
  recorded as one. The controller reads this line as a difficulty covariate when
225
225
  it rules your review, and the PR body is the only place it survives your exit.
226
- **Report to the controller the PR number, the head SHA, and WHEN you ran
227
- `sizing-a-ticket` relative to opening the PR** — "ran sizing-a-ticket at step
228
- 6, before `gh pr create`" if you kept that order, and say so plainly if you did
229
- not, including if the `Sizing:` line was written before the run and corrected
230
- after. Nothing in the PR body separates a measured verdict from one typed in
231
- early; that clause is the only thing that does, and an unreported ordering
232
- costs the covariate. Then exit. Never apply `ready-to-merge`, never merge.
226
+ **Report to the controller in the report file your brief names,
227
+ `<scratch>/reports/<your name>.json`: the PR number, the head SHA, and WHEN you
228
+ ran `sizing-a-ticket` relative to opening the PR** — `sizing.ranBeforePr` true
229
+ if you ran it at step 6, before `gh pr create`, and false if you did not,
230
+ including if the `Sizing:` line was written before the run and corrected after;
231
+ `sizing.verdict` and `sizing.signal` are that line's verdict and signal.
232
+ Nothing in the PR body separates a measured verdict from one typed in early;
233
+ that field is the only thing that does, and an unreported ordering costs the
234
+ covariate. A bail is `outcome` `bailed`, its cause in `bailCause`. Then send
235
+ the one line your brief gives, `<your name>: <outcome> <path>`, and exit. Never
236
+ apply `ready-to-merge`, never merge.
@@ -223,10 +223,14 @@ output, because that format will change and this line has to outlive it. A
223
223
  verdict with nothing beside it is indistinguishable from a guess, and is
224
224
  recorded as one. The controller reads this line as a difficulty covariate when
225
225
  it rules your review, and the PR body is the only place it survives your exit.
226
- **Report to the controller the PR number, the head SHA, and WHEN you ran
227
- `sizing-a-ticket` relative to opening the PR** — "ran sizing-a-ticket at step
228
- 6, before `gh pr create`" if you kept that order, and say so plainly if you did
229
- not, including if the `Sizing:` line was written before the run and corrected
230
- after. Nothing in the PR body separates a measured verdict from one typed in
231
- early; that clause is the only thing that does, and an unreported ordering
232
- costs the covariate. Then exit. Never apply `ready-to-merge`, never merge.
226
+ **Report to the controller in the report file your brief names,
227
+ `<scratch>/reports/<your name>.json`: the PR number, the head SHA, and WHEN you
228
+ ran `sizing-a-ticket` relative to opening the PR** — `sizing.ranBeforePr` true
229
+ if you ran it at step 6, before `gh pr create`, and false if you did not,
230
+ including if the `Sizing:` line was written before the run and corrected after;
231
+ `sizing.verdict` and `sizing.signal` are that line's verdict and signal.
232
+ Nothing in the PR body separates a measured verdict from one typed in early;
233
+ that field is the only thing that does, and an unreported ordering costs the
234
+ covariate. A bail is `outcome` `bailed`, its cause in `bailCause`. Then send
235
+ the one line your brief gives, `<your name>: <outcome> <path>`, and exit. Never
236
+ apply `ready-to-merge`, never merge.
@@ -223,10 +223,14 @@ output, because that format will change and this line has to outlive it. A
223
223
  verdict with nothing beside it is indistinguishable from a guess, and is
224
224
  recorded as one. The controller reads this line as a difficulty covariate when
225
225
  it rules your review, and the PR body is the only place it survives your exit.
226
- **Report to the controller the PR number, the head SHA, and WHEN you ran
227
- `sizing-a-ticket` relative to opening the PR** — "ran sizing-a-ticket at step
228
- 6, before `gh pr create`" if you kept that order, and say so plainly if you did
229
- not, including if the `Sizing:` line was written before the run and corrected
230
- after. Nothing in the PR body separates a measured verdict from one typed in
231
- early; that clause is the only thing that does, and an unreported ordering
232
- costs the covariate. Then exit. Never apply `ready-to-merge`, never merge.
226
+ **Report to the controller in the report file your brief names,
227
+ `<scratch>/reports/<your name>.json`: the PR number, the head SHA, and WHEN you
228
+ ran `sizing-a-ticket` relative to opening the PR** — `sizing.ranBeforePr` true
229
+ if you ran it at step 6, before `gh pr create`, and false if you did not,
230
+ including if the `Sizing:` line was written before the run and corrected after;
231
+ `sizing.verdict` and `sizing.signal` are that line's verdict and signal.
232
+ Nothing in the PR body separates a measured verdict from one typed in early;
233
+ that field is the only thing that does, and an unreported ordering costs the
234
+ covariate. A bail is `outcome` `bailed`, its cause in `bailCause`. Then send
235
+ the one line your brief gives, `<your name>: <outcome> <path>`, and exit. Never
236
+ apply `ready-to-merge`, never merge.
@@ -14,6 +14,10 @@ is what makes you hold that grace instead of arming your own watcher.
14
14
  Your scratch directory is `<scratch>/`; you write only under
15
15
  `<scratch>/pr<N>/merge-bot-<n>/`.
16
16
 
17
+ Your report is the one file you write outside it: `<scratch>/reports/merge-bot-<n>.json`,
18
+ the path your brief names, holding every PR you merged in `merged`. Your final
19
+ message is the one line your brief gives, `merge-bot-<n>: done <path>`.
20
+
17
21
  The shell traps below are copied from the controller's skill file,
18
22
  `run-team/SKILL.md`. In them "Phase 3" is the controller's event loop, which you
19
23
  do not run, and "this file" is that skill file; each trap applies to every shell
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.58.1",
3
+ "version": "3.59.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": {
@@ -15,7 +15,9 @@
15
15
  // row and appends it to `## Dispatched` with `brief=<hash>`, the brief it
16
16
  // refuses to dispatch without, `settle` rewrites that token to
17
17
  // `<member>=<outcome>` in both places (an implementer's settle to `PR#M` also
18
- // folds the PR's own `#M` row into its ticket's), `review` appends a PR's
18
+ // folds the PR's own `#M` row into its ticket's) — with `--from-report`, the
19
+ // outcome derived from the member's report file and checked against git and
20
+ // GitHub first, see runSettleFromReport() — `review` appends a PR's
19
21
  // `review=`/`reviewed=` tokens to the PR's row, and `drain` writes the
20
22
  // one marker that stops supply. The token grammar is
21
23
  // ledger-grammar.mjs's. Within a run `## Dispatched` gains an entry per
@@ -47,13 +49,14 @@ import { createHash } from "node:crypto";
47
49
  import { dirname, resolve, join, basename } from "node:path";
48
50
  import { fileURLToPath } from "node:url";
49
51
  import { spawnSync, execFileSync } from "node:child_process";
50
- import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
52
+ import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
51
53
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.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";
54
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
53
55
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
54
56
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
55
57
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
56
58
  import { attemptLock, releaseLockFile, reapPathOf } from "./pid-lock.mjs";
59
+ import { readReportIn, reportsDir, reportFamily, defaultScratch } from "./report-files.mjs";
57
60
 
58
61
  const NAME = "ledger";
59
62
  // The plugin's own agent definitions — the directory tier-check.mjs reads
@@ -664,11 +667,14 @@ async function acquireLock() {
664
667
  if (requireFile && !existsSync(file)) die(`--require-file given but ledger file does not exist: ${file}`);
665
668
 
666
669
  const WRITE_COMMANDS = new Set(["row", "token", "filed", "ruled", "dispatch", "settle", "review", "drain", "rotate"]);
667
- if (WRITE_COMMANDS.has(cmd)) await acquireLock();
670
+ // `settle --from-report` takes the lock itself, once its checks have run —
671
+ // see runSettleFromReport().
672
+ const FROM_REPORT = cmd === "settle" && rest.includes("--from-report");
673
+ if (WRITE_COMMANDS.has(cmd) && !FROM_REPORT) await acquireLock();
668
674
  // `rotate` never load()s: a ledger load() would refuse is still the previous
669
675
  // run's record, and it is archived as-is — and read line by line when it
670
676
  // carries live members forward, see carryOf().
671
- const data = cmd === "rotate" ? null : load();
677
+ let data = cmd === "rotate" ? null : load();
672
678
 
673
679
  // The payload subcommands end by falling out of this chain, never by calling
674
680
  // process.exit(). On a pipe, process.stdout.write is async and process.exit()
@@ -784,21 +790,11 @@ if (cmd === "read") {
784
790
  // `check` against that row silently degrades from the hard "already
785
791
  // filed" block to a soft near-miss suggestion instead.
786
792
  if (!isDigits(id)) die(`'${issue}' is not an issue number`);
787
- // Both callers retry once on a failure they observed, and an observed
788
- // failure is not proof the write failed — a timeout after the row landed
789
- // reads as one — so a repeat filing of an issue already on file is a no-op.
790
- // Identity is the issue number alone, matched NUMERICALLY — so a
791
- // non-canonical spelling (`08`) still dedupes against `8` — as the token
792
- // between `#` and the first whitespace: never `check`'s fuzzy subject
793
- // matcher, and never a prefix test, which would dedupe issue 8 against issue 80.
794
- // The existing row wins, subject and all — a retry reworded is still the
795
- // same filing.
796
- const existing = data.filed.find((row) => Number(row.match(/^#(\S+)/)?.[1]) === Number(id));
797
- if (existing !== undefined) {
798
- console.error(` already recorded: ${existing}`);
799
- console.log(JSON.stringify({ issue, subject, total: data.filed.length, alreadyRecorded: true, row: existing }));
793
+ const { row, alreadyRecorded } = recordFiled(id, subject);
794
+ if (alreadyRecorded) {
795
+ console.error(` already recorded: ${row}`);
796
+ console.log(JSON.stringify({ issue, subject, total: data.filed.length, alreadyRecorded: true, row }));
800
797
  } else {
801
- data.filed.push(`#${id} ${subject}`);
802
798
  save(data);
803
799
  console.log(JSON.stringify({ issue, subject, total: data.filed.length }));
804
800
  }
@@ -819,7 +815,8 @@ if (cmd === "read") {
819
815
  } else if (cmd === "dispatch") {
820
816
  runDispatch();
821
817
  } else if (cmd === "settle") {
822
- runSettle();
818
+ if (FROM_REPORT) await runSettleFromReport();
819
+ else runSettle();
823
820
  } else if (cmd === "token") {
824
821
  runToken();
825
822
  } else if (cmd === "review") {
@@ -2022,8 +2019,18 @@ function renderedBrief(name, role) {
2022
2019
  return { path, sha256: s.sha256 };
2023
2020
  }
2024
2021
 
2022
+ // Whether `outcome` is one whose claim a member's report carries and `settle
2023
+ // --from-report` checks against git or GitHub before writing. Settled with
2024
+ // the bare form, the claim goes unchecked, so that form says so on stderr.
2025
+ function reportedOutcome(outcome) {
2026
+ return /^(?:PR#|applied:|halted:)|^(?:bailed|no-op|labelled|done)$/.test(outcome);
2027
+ }
2028
+
2025
2029
  function runSettle() {
2026
- const usage = "usage: ledger.mjs settle <member> <outcome>";
2030
+ const usage = "usage: ledger.mjs settle <member> <outcome> | settle <member> --from-report [--reports <dir>]";
2031
+ // `--reports` names where `--from-report` reads; alone it would land here
2032
+ // as an outcome.
2033
+ if (rest.includes("--reports")) die(`--reports is read only with --from-report — ${usage}`);
2027
2034
  // `settle impl-<N> PR#<n>`, or the one token it writes — `settle
2028
2035
  // impl-<N>=PR#<n>` — which is how the spec's record-before-tick table
2029
2036
  // spells every settlement.
@@ -2032,6 +2039,27 @@ function runSettle() {
2032
2039
  const parsed = parseToken(rest.length === 2 ? `${rest[0]}=${rest[1]}` : rest[0]);
2033
2040
  if (!parsed) die(unknownMember(rest[0].split("=")[0]));
2034
2041
  if (parsed.error) die(`${parsed.name}: ${parsed.error}`);
2042
+ const { name, outcome } = parsed;
2043
+ const token = `${name}=${outcome}`;
2044
+ const { i, changed } = settleMember(parsed);
2045
+ if (changed) {
2046
+ save(data);
2047
+ console.error(` settled ${token}`);
2048
+ }
2049
+ if (reportedOutcome(outcome)) {
2050
+ console.error(`${NAME}: WARNING ${token} settled without --from-report — the member's claim was not checked`);
2051
+ }
2052
+ console.log(JSON.stringify({
2053
+ member: name, outcome, ticket: i === -1 ? null : rowKey(data.rows[i]), line: i === -1 ? null : data.rows[i], changed,
2054
+ }));
2055
+ }
2056
+
2057
+ // The settle both forms share: rewrites `parsed`'s live token to
2058
+ // `<member>=<outcome>` in `data`, saving nothing. `{i, changed}`: `i` the row
2059
+ // the token sits on (-1 for none), `changed` false when the same outcome was
2060
+ // already on record and nothing was rewritten. Every refusal is die(), exit 2,
2061
+ // before anything in `data` changes.
2062
+ function settleMember(parsed) {
2035
2063
  const { name, outcome } = parsed;
2036
2064
  const token = `${name}=${outcome}`;
2037
2065
  // Same guard as runDispatch(): a `## Dispatched` entry this grammar cannot
@@ -2048,14 +2076,10 @@ function runSettle() {
2048
2076
 
2049
2077
  const liveRows = data.rows.flatMap((r, i) => (carries(r, name, true) ? [i] : []));
2050
2078
  const liveEntry = entry !== null && entry.outcome === null;
2051
- const payload = (i, changed) => ({
2052
- member: name, outcome, ticket: i === -1 ? null : rowKey(data.rows[i]), line: i === -1 ? null : data.rows[i], changed,
2053
- });
2054
2079
  if (!liveEntry && liveRows.length === 0) {
2055
2080
  if (settled.length === 0) die(`no live ${name} in the ledger — \`dispatch\` it first`);
2056
2081
  // The same outcome again: already on record, so nothing is written.
2057
- console.log(JSON.stringify(payload(data.rows.findIndex((r) => carries(r, name)), false)));
2058
- return;
2082
+ return { i: data.rows.findIndex((r) => carries(r, name)), changed: false };
2059
2083
  }
2060
2084
 
2061
2085
  // The rows before any write below: the fold's guard reads the row this
@@ -2112,9 +2136,299 @@ function runSettle() {
2112
2136
  // carried. The refused member settles `=bailed` or to a PR of its own.
2113
2137
  const split = newSplitRow(before, data.rows);
2114
2138
  if (split !== null) die(`settle ${token}: ${splitRowClause(split)}; settle ${name} =bailed or to a PR of its own`);
2115
- save(data);
2116
- console.error(` settled ${token}`);
2117
- console.log(JSON.stringify(payload(i, true)));
2139
+ return { i, changed: true };
2140
+ }
2141
+
2142
+ // One filing into `## Filed`, unsaved: `{row, alreadyRecorded}`. A repeat
2143
+ // filing of an issue already on file is a no-op — both callers of `filed`
2144
+ // retry once on a failure they observed, and an observed failure is not
2145
+ // proof the write failed (a timeout after the row landed reads as one), and
2146
+ // `settle --from-report` run twice records the same report twice. Identity
2147
+ // is the issue number alone, matched NUMERICALLY — so a non-canonical
2148
+ // spelling (`08`) still dedupes against `8` — as the token between `#` and
2149
+ // the first whitespace: never `check`'s fuzzy subject matcher, and never a
2150
+ // prefix test, which would dedupe issue 8 against issue 80. The existing row
2151
+ // wins, subject and all — a retry reworded is still the same filing.
2152
+ function recordFiled(id, subject) {
2153
+ const existing = data.filed.find((row) => Number(row.match(/^#(\S+)/)?.[1]) === Number(id));
2154
+ if (existing !== undefined) return { row: existing, alreadyRecorded: true };
2155
+ const row = `#${id} ${subject}`;
2156
+ data.filed.push(row);
2157
+ return { row, alreadyRecorded: false };
2158
+ }
2159
+
2160
+ // -- settle --from-report -----------------------------------------------------
2161
+ //
2162
+ // `settle <member> --from-report [--reports <dir>]`: the member's outcome read
2163
+ // off the report file it wrote, `<dir>/<member>.json` — `<dir>` by default
2164
+ // `<scratch>/reports`, `<scratch>` the root scratch-root.mjs prints — rather
2165
+ // than typed by hand. The file must check against its family's schema
2166
+ // (report-schema.mjs) and name this member in `member`. The token is derived
2167
+ // from it, and an outcome that asserts a git or GitHub state has that state
2168
+ // checked before anything is written:
2169
+ //
2170
+ // impl-N=PR#M verify-sha.sh <branch> <head> exits 0; PR M
2171
+ // reads OPEN and its closingIssuesReferences name N
2172
+ // impl-N=bailed bailCause is not null; the receipt names it
2173
+ // fix-pr-M=applied:<head> origin's refs/heads/<branch> is <head>
2174
+ // fix-pr-M=no-op origin's refs/heads/<branch> is the head PR M's
2175
+ // latest reviewed= names, as the tick folds it
2176
+ // finisher-pr-M=labelled PR M's labels carry ready-to-merge, and so does
2177
+ // the report's labelsReadBack
2178
+ // finisher-pr-M=halted:<c> cause is in the halted:<cause> vocabulary and
2179
+ // evidence is not empty
2180
+ // merge-bot-n=done every merged[].pr reads MERGED
2181
+ //
2182
+ // A `failed` report claims no state, so it settles `=failed` unchecked. A
2183
+ // fix-applier's `refuted` deferral claims one more thing: that its disposition
2184
+ // record gives the reversal a reason, which is the text `## Ruled` gets.
2185
+ //
2186
+ // Exit 3: a check failed — the member's claim and the world disagree — and
2187
+ // stderr names each failed check; nothing written. Exit 2: the report is
2188
+ // absent, unreadable or invalid, a check could not look (a `gh`, `git` or
2189
+ // verify-sha.sh call that failed, printed what it was not asked for, or never
2190
+ // finished), or a refusal the bare form makes; nothing written either.
2191
+ //
2192
+ // After the settle, in the same write: every `unrecorded` entry goes to `##
2193
+ // Filed` the way `filed` records one, and for a fix-applier every `deferred`
2194
+ // entry in the `refuted` bucket goes to `## Ruled` as `#M reversed refutation
2195
+ // <index>: <reason>`. A line already there is not written again, so a second
2196
+ // run of the same settle writes nothing. The receipt on stdout is `{member,
2197
+ // outcome, checks: [{name, ok}], filed, ruled}`, `filed` and `ruled` the
2198
+ // lines this call added.
2199
+ //
2200
+ // The checks run before the write lock is taken, against the ledger as read
2201
+ // without it, because they are network calls and every other writer waits
2202
+ // for the lock 10 s at most. The settle itself is judged again under the
2203
+ // lock, on the ledger reloaded there.
2204
+
2205
+ // A failed check: die()'s refusal shape, on stderr with nothing on stdout,
2206
+ // at exit 3.
2207
+ function mismatch(msg) {
2208
+ try {
2209
+ writeAll(2, `\n${NAME}: ${msg}\n`);
2210
+ } catch {
2211
+ // The message may be lost; the exit code may not.
2212
+ }
2213
+ process.exit(3);
2214
+ }
2215
+
2216
+ async function runSettleFromReport() {
2217
+ const usage = "usage: ledger.mjs settle <member> --from-report [--reports <dir>]";
2218
+ const verifySha = join(dirname(fileURLToPath(import.meta.url)), "verify-sha.sh");
2219
+ const ready = "ready-to-merge";
2220
+ // The bound on each child a check runs: generous, because verify-sha.sh
2221
+ // fetches, and still a bound, because the child may never answer at all.
2222
+ const checkTimeoutMs = 60_000;
2223
+ let member;
2224
+ let reports = null;
2225
+ for (let k = 0; k < rest.length; k++) {
2226
+ const a = rest[k];
2227
+ if (a === "--from-report") continue;
2228
+ if (a === "--reports") {
2229
+ const v = rest[++k];
2230
+ if (isFlagLike(v)) die(`--reports needs a directory — ${usage}`);
2231
+ if (reports !== null) die(`--reports given twice — ${usage}`);
2232
+ reports = v;
2233
+ } else if (a.startsWith("-")) {
2234
+ die(`unknown flag '${a}' — ${usage}`);
2235
+ } else if (member === undefined) {
2236
+ member = a;
2237
+ } else {
2238
+ die(usage);
2239
+ }
2240
+ }
2241
+ if (member === undefined) die(usage);
2242
+ if (member.includes("=")) die(`settle --from-report takes a member name, not '${member}': the outcome is the report's — ${usage}`);
2243
+ const live = parseToken(member);
2244
+ if (!live) die(unknownMember(member));
2245
+ const where = `settle ${member} --from-report`;
2246
+
2247
+ if (reports === null) {
2248
+ try {
2249
+ reports = reportsDir(defaultScratch());
2250
+ } catch (e) {
2251
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
2252
+ die(`${where}: no --reports, and the scratch root could not be resolved — ${e.message}`);
2253
+ }
2254
+ }
2255
+ const read = readReportIn(reports, member);
2256
+ if (read.state === "absent") die(`${where}: no report at ${read.path}; nothing written`);
2257
+ if (read.state === "invalid") die(`${where}: ${read.path} is not a ${reportFamily(member)} report — ${read.violation}; nothing written`);
2258
+ const report = read.report;
2259
+ const invalid = (violation) => die(`${where}: ${read.path} is not a ${reportFamily(member)} report — ${violation}; nothing written`);
2260
+ if (report.member !== member) invalid(`$.member: ${JSON.stringify(report.member)} is not ${member}`);
2261
+ // An issue number is a positive integer. A negative id writes a row `#-3 …`
2262
+ // that `filed` refuses and `check`'s subjectOf() cannot strip.
2263
+ for (const [k, { issue }] of (report.unrecorded ?? []).entries()) {
2264
+ if (!Number.isInteger(issue) || issue < 1) invalid(`$.unrecorded[${k}].issue: ${JSON.stringify(issue)} is not an issue number`);
2265
+ }
2266
+
2267
+ // Every child runs from the ledger's repository with runCheck()'s
2268
+ // environment, for runCheck()'s reasons: GH_REPO would point gh at another
2269
+ // tracker whatever the cwd, and GIT_DIR/GIT_WORK_TREE git at another repo.
2270
+ const env = { ...process.env, GH_REPO: "" };
2271
+ delete env.GIT_DIR;
2272
+ delete env.GIT_WORK_TREE;
2273
+ let repo = null;
2274
+ const repoDir = () => {
2275
+ if (repo !== null) return repo;
2276
+ let dir = dirname(resolve(file));
2277
+ while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
2278
+ const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8", env, timeout: GIT_TIMEOUT_MS });
2279
+ if (r.status !== 0) {
2280
+ const why = cause(r.error && r.error.message, r.stderr);
2281
+ die(`${where}: could not look — cannot resolve the ledger's repository (${dir})${why ? `: ${why}` : ""}; nothing written`);
2282
+ }
2283
+ repo = r.stdout.trim();
2284
+ return repo;
2285
+ };
2286
+ // A child that must answer with one of `answers`; anything else — another
2287
+ // status, a spawn failure, a timeout — could not look.
2288
+ const look = (what, cmd, args, answers = [0]) => {
2289
+ const r = spawnSync(cmd, args, { encoding: "utf8", cwd: repoDir(), env, timeout: checkTimeoutMs, stdio: ["ignore", "pipe", "pipe"] });
2290
+ if (r.status === null || !answers.includes(r.status)) {
2291
+ const why = cause(r.error && r.error.message, r.stderr);
2292
+ die(`${where}: could not look — ${what}${r.status === null ? "" : ` exited ${r.status}`}${why ? `: ${why}` : ""}; nothing written`);
2293
+ }
2294
+ return r;
2295
+ };
2296
+ // A `gh pr view --json <fields>` answer: an object whose every requested
2297
+ // field has the type that field has. Anything else was not what was asked
2298
+ // for, so it could not look.
2299
+ const prFieldOk = { state: (v) => typeof v === "string", labels: Array.isArray, closingIssuesReferences: Array.isArray };
2300
+ const prView = (pr, fields) => {
2301
+ const what = `gh pr view ${pr} --json ${fields}`;
2302
+ const r = look(what, "gh", ["pr", "view", String(pr), "--json", fields]);
2303
+ let v = null;
2304
+ try {
2305
+ v = JSON.parse(r.stdout);
2306
+ } catch {
2307
+ // Falls through to the refusal below.
2308
+ }
2309
+ if (v === null || typeof v !== "object") {
2310
+ die(`${where}: could not look — ${what} printed no JSON object: ${cause(r.stdout)}; nothing written`);
2311
+ }
2312
+ const missing = fields.split(",").filter((f) => !prFieldOk[f](v[f]));
2313
+ if (missing.length > 0) {
2314
+ die(`${where}: could not look — ${what} answered without a usable ${missing.join(", ")}: ${cause(r.stdout)}; nothing written`);
2315
+ }
2316
+ return v;
2317
+ };
2318
+ // origin's head of `branch`, or null when origin has no such branch.
2319
+ const remoteHead = (branch) => {
2320
+ const ref = `refs/heads/${branch}`;
2321
+ const r = look(`git ls-remote origin ${ref}`, "git", ["ls-remote", "origin", ref]);
2322
+ const line = r.stdout.split("\n").find((l) => l.endsWith(`\t${ref}`));
2323
+ return line === undefined ? null : line.split("\t")[0];
2324
+ };
2325
+
2326
+ const checks = [];
2327
+ const check = (name, ok) => {
2328
+ checks.push({ name, ok });
2329
+ return ok;
2330
+ };
2331
+ const ruledLines = [];
2332
+ let outcome;
2333
+ if (live.family === "impl") {
2334
+ if (report.outcome === "pr") {
2335
+ if (report.pr === null || report.pr < 1) invalid(`$.pr: ${JSON.stringify(report.pr)} is not a PR number, with outcome "pr"`);
2336
+ if (report.head === null) invalid('$.head: null, with outcome "pr"');
2337
+ outcome = `PR#${report.pr}`;
2338
+ const sha = look(`verify-sha.sh ${report.branch} ${report.head}`, "sh", [verifySha, report.branch, report.head], [0, 1]);
2339
+ check(`verify-sha.sh ${report.branch} ${report.head} exits 0`, sha.status === 0);
2340
+ const pr = prView(report.pr, "state,closingIssuesReferences");
2341
+ check(`PR #${report.pr} reads OPEN`, pr.state === "OPEN");
2342
+ check(`PR #${report.pr} closes #${live.number}`, pr.closingIssuesReferences.some((c) => c?.number === live.number));
2343
+ } else {
2344
+ outcome = "bailed";
2345
+ check(`bailCause: ${report.bailCause}`, report.bailCause !== null);
2346
+ }
2347
+ } else if (live.family === "fix-pr") {
2348
+ if (report.outcome === "applied") {
2349
+ outcome = `applied:${report.head}`;
2350
+ const head = remoteHead(report.branch);
2351
+ check(`origin refs/heads/${report.branch} is ${report.head}`, head === report.head);
2352
+ } else if (report.outcome === "no-op") {
2353
+ outcome = "no-op";
2354
+ let fold;
2355
+ try {
2356
+ fold = deriveRun({ rows: data.rows, dispatched: data.dispatched, drain: data.drain }, []);
2357
+ } catch (e) {
2358
+ if (!(e instanceof LedgerError)) throw e;
2359
+ die(`${where}: ${e.message} — fleet-tick.mjs refuses this ledger, so PR #${live.number}'s latest reviewed= cannot be read off it; nothing written`);
2360
+ }
2361
+ const reviewed = fold.reviewed.find((r) => r.pr === live.number)?.head ?? null;
2362
+ if (reviewed === null) {
2363
+ check(`PR #${live.number}'s row names a reviewed= head`, false);
2364
+ } else {
2365
+ const head = remoteHead(report.branch);
2366
+ check(`origin refs/heads/${report.branch} is ${reviewed}, the head PR #${live.number}'s latest reviewed= names`,
2367
+ head !== null && head.toLowerCase().startsWith(reviewed.toLowerCase()));
2368
+ }
2369
+ } else {
2370
+ outcome = "failed";
2371
+ }
2372
+ const refuted = report.deferred.filter((d) => d.bucket === "refuted");
2373
+ if (refuted.length > 0) {
2374
+ const path = report.dispositionsRecord;
2375
+ let record;
2376
+ try {
2377
+ record = JSON.parse(readFileSync(path, "utf8"));
2378
+ } catch (e) {
2379
+ die(`${where}: could not look — the disposition record ${path} could not be read as JSON: ${e.code ?? e.message}; nothing written`);
2380
+ }
2381
+ const entries = Array.isArray(record?.entries) ? record.entries : [];
2382
+ for (const d of refuted) {
2383
+ const entry = entries.find((e) => e?.bucket === "refuted" && e?.index === d.index);
2384
+ const reason = typeof entry?.reason === "string" ? entry.reason.trim() : "";
2385
+ if (check(`${path} gives refuted[${d.index}] a reason`, reason !== "")) {
2386
+ ruledLines.push(`#${live.number} reversed refutation ${d.index}: ${reason}`);
2387
+ }
2388
+ }
2389
+ }
2390
+ } else if (live.family === "finisher-pr") {
2391
+ if (report.outcome === "labelled") {
2392
+ outcome = "labelled";
2393
+ const pr = prView(live.number, "labels");
2394
+ check(`PR #${live.number} carries ${ready}`, pr.labels.some((l) => l?.name === ready));
2395
+ check(`labelsReadBack carries ${ready}`, report.labelsReadBack.includes(ready));
2396
+ } else if (report.outcome === "halted") {
2397
+ outcome = `halted:${report.cause}`;
2398
+ check(`cause ${report.cause} is in the halted:<cause> vocabulary`, HALT_CAUSES.includes(report.cause));
2399
+ check("evidence is not empty", (report.evidence ?? "").trim() !== "");
2400
+ } else {
2401
+ outcome = "failed";
2402
+ }
2403
+ } else {
2404
+ outcome = "done";
2405
+ for (const { pr } of report.merged) check(`PR #${pr} reads MERGED`, prView(pr, "state").state === "MERGED");
2406
+ }
2407
+
2408
+ const failed = checks.filter((c) => !c.ok);
2409
+ if (failed.length > 0) {
2410
+ mismatch(`${where}: the report's claim and the world disagree — ${failed.map((c) => `failed: ${c.name}`).join("; ")}; nothing written`);
2411
+ }
2412
+ const parsed = parseToken(`${member}=${outcome}`);
2413
+ if (parsed.error) invalid(`${parsed.name}: ${parsed.error}`);
2414
+
2415
+ await acquireLock();
2416
+ data = load();
2417
+ const { changed } = settleMember(parsed);
2418
+ const filed = [];
2419
+ for (const { issue, subject } of report.unrecorded ?? []) {
2420
+ const { row, alreadyRecorded } = recordFiled(String(issue), subject);
2421
+ if (!alreadyRecorded) filed.push(row);
2422
+ }
2423
+ const ruled = [];
2424
+ for (const line of ruledLines) {
2425
+ if (data.ruled.includes(line)) continue;
2426
+ data.ruled.push(line);
2427
+ ruled.push(line);
2428
+ }
2429
+ if (changed || filed.length > 0 || ruled.length > 0) save(data);
2430
+ if (changed) console.error(` settled ${member}=${outcome}`);
2431
+ console.log(JSON.stringify({ member, outcome, checks, filed, ruled }));
2118
2432
  }
2119
2433
 
2120
2434
  // A ticket or PR number argument as a number: a leading `#` is allowed, a
@@ -38,9 +38,14 @@ export const reportPath = (scratch, member) => join(reportsDir(scratch), `${memb
38
38
  * wrong shape, or `{state: "absent", path}`. Throws on a member no schema
39
39
  * covers: ask reportFamily() first. */
40
40
  export function readReport(scratch, member) {
41
+ return readReportIn(reportsDir(scratch), member);
42
+ }
43
+
44
+ /** readReport() for a reports directory named directly, `<dir>/<member>.json`. */
45
+ export function readReportIn(dir, member) {
41
46
  const family = reportFamily(member);
42
47
  if (family === null) throw new Error(`no report schema for '${member}'`);
43
- const path = reportPath(scratch, member);
48
+ const path = join(dir, `${member}.json`);
44
49
  let text;
45
50
  try {
46
51
  text = readFileSync(path, "utf8");
@@ -1316,15 +1316,15 @@ ticket's line — never a hand edit.
1316
1316
 
1317
1317
  | Wake | Record, then tick |
1318
1318
  |---|---|
1319
- | Implementer report | `verify-sha.sh`; `ledger.mjs settle impl-<N>=PR#<M>`, or `=bailed` and relabel by cause (**Implementer bails before implementing**, below) |
1319
+ | Implementer report | `ledger.mjs settle impl-<N> --from-report`, which runs `verify-sha.sh` and reads the PR itself (**Run ledger**); on `bailed`, relabel by the cause its receipt names (**Implementer bails before implementing**, below) |
1320
1320
  | Review workflow notification / `review-pr-<n>` report | the result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root; `ledger.mjs review <pr> reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` on the PR's row (**Reviewers**) |
1321
- | Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges that member's own record `<scratch>/dispositions-<member>.json` against the review file the PR's latest `reviewed=` names, `<scratch>/pr<M>/<run>/review.json`, writes `dispositions-ok=`, `dispositions-mismatch=`, `dispositions-escalate=` or `dispositions-unchecked=<member>:<run>` onto the PR's row itself, and exits 1 on a mismatch, an escalation or an unchecked, naming each violating or escalated entry's bucket and index, a violation its rule too, and each entry whose filed issue `gh` could not read — **Then dispatch a fix-applier** says what a mismatch asks of you, the gate paragraph below what an escalation or an unchecked does; copy the refutations it reversed — the record's `refuted` entries — to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1322
- | Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled` as reported, even when its read-back lacks `ready-to-merge` — the tick's `DISPATCH finisher PR#<M>` catches that next. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment. `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1323
- | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M>=halted:<cause>`; `gh pr comment <M>` with the finisher's halt report, cause and evidence; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line; then the per-cause rule (**Resolving a finisher halt**, below) |
1321
+ | Fix-applier report | `ledger.mjs settle fix-pr-<M> --from-report`, which records each `unrecorded` filing and copies to `ruled` each refutation the report defers; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges that member's own record `<scratch>/dispositions-<member>.json` against the review file the PR's latest `reviewed=` names, `<scratch>/pr<M>/<run>/review.json`, writes `dispositions-ok=`, `dispositions-mismatch=`, `dispositions-escalate=` or `dispositions-unchecked=<member>:<run>` onto the PR's row itself, and exits 1 on a mismatch, an escalation or an unchecked, naming each violating or escalated entry's bucket and index, a violation its rule too, and each entry whose filed issue `gh` could not read — **Then dispatch a fix-applier** says what a mismatch asks of you, the gate paragraph below what an escalation or an unchecked does; copy any other refutation it reversed — a `refuted` entry of the record the report does not defer — to `ruled` yourself |
1322
+ | Finisher report | `ledger.mjs settle finisher-pr-<M> --from-report`, which records each `unrecorded` filing. Its exit 3 on `ready-to-merge` — missing from the PR or from the read-back — is the case the tick's `DISPATCH finisher PR#<M>` catches next: settle it `ledger.mjs settle finisher-pr-<M>=labelled` as reported, and `ledger.mjs filed <N> "<subject>"` for each `unrecorded` entry. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment |
1323
+ | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M> --from-report`, which records each `unrecorded` filing; `gh pr comment <M>` with the finisher's halt report, cause and evidence; then the per-cause rule (**Resolving a finisher halt**, below) |
1324
1324
  | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1325
1325
  | Label seen (persistent Monitor) | nothing to record |
1326
1326
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1327
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1327
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n> --from-report`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1328
1328
  | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1329
1329
  | Heartbeat | nothing to record |
1330
1330
 
@@ -2737,14 +2737,18 @@ all.
2737
2737
  > with `reason` `false-rationale` and filed on the closed suggestion-band
2738
2738
  > record.
2739
2739
  >
2740
- > Then report to the controller the pushed SHA, your apply/defer split, how
2741
- > many refuters you dispatched against out-of-scope suggestions, and
2742
- > the deferral issue numbers — a `filed: #N <subject>` line for every issue
2743
- > step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
2744
- > failed twice — and exit. **Deferring everything is a normal
2740
+ > Then write your report to the file your brief names,
2741
+ > `<scratch>/reports/<your name>.json`: `head` the pushed SHA, `applied` and
2742
+ > `deferred` your apply/defer split by bucket and index, each deferral's issue
2743
+ > number on its `deferred` entry, the deferral issues as `{issue, subject}`
2744
+ > entries — `filed` for every issue step 5 created, and `unrecorded` for one
2745
+ > whose `ledger.mjs filed` failed twice, which the controller's settle records —
2746
+ > `dispositionsRecord` your record's path and `testRun` your test result. Then
2747
+ > send the one line your brief gives, `<your name>: <outcome> <path>`, and exit.
2748
+ > **Deferring everything is a normal
2745
2749
  > outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
2746
- > index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
2747
- > report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
2750
+ > index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and your
2751
+ > report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
2748
2752
  > explicitly — silence there is indistinguishable from a member that died. Never
2749
2753
  > manufacture a commit to make CI fire.
2750
2754
 
@@ -3983,6 +3987,24 @@ live count from it, so nobody states one. Write neither by hand:
3983
3987
  row as its own. `settle impl-N=PR#M` refuses a settle after which a PR maps
3984
3988
  to more than one row when it did not before, judged after the fold — a PR
3985
3989
  has one row, the PR's row; a split already on disk is carried.
3990
+ - **`ledger.mjs settle <member> --from-report [--reports <dir>]`** — the
3991
+ settle for a member that wrote a report: reads `<dir>/<member>.json`
3992
+ (`<dir>` defaults to `<scratch>/reports`), derives the outcome from it and,
3993
+ before writing, checks what that outcome claims — `PR#M`: `verify-sha.sh`
3994
+ on the report's branch and head, and PR M OPEN and closing N; `bailed`: a
3995
+ `bailCause`, which the receipt names; `applied:<head>`: origin's branch at
3996
+ that head; `no-op`: origin's branch at the head the PR's latest
3997
+ `reviewed=` names; `labelled`: `ready-to-merge` on the PR and in the
3998
+ read-back; `halted:<cause>`: a cause and non-empty evidence; `done`: every
3999
+ PR the bot merged reads MERGED. It then records each `unrecorded` filing in
4000
+ **filed** and, for a fix-applier, each refutation the report defers in
4001
+ **ruled**, once however often it runs, and prints `{member, outcome,
4002
+ checks, filed, ruled}`. Exit 3: a check failed — the member's claim and the
4003
+ world disagree — and nothing is written; you rule. Exit 2: the report is
4004
+ absent or invalid, or a check could not look, and nothing is written; a
4005
+ check that could not look is run again once `gh` and `git` answer. The bare
4006
+ form above, for an outcome a report carries, warns `settled without
4007
+ --from-report` on stderr.
3986
4008
  - **`ledger.mjs review <pr> <token>…`** — the only writer of `review=` and
3987
4009
  `reviewed=` (below): appends each to the PR's row — the ticket row once
3988
4010
  `settle impl-<N>=PR#M` has run, else `#M`, created when neither exists —
@@ -4070,7 +4092,8 @@ Plus two append-only lists:
4070
4092
  one, not you: `review-and-fix.md` step 5 and finisher duty 2 each run `filed`
4071
4093
  immediately after their own `gh issue create`, with the subject they passed
4072
4094
  to `check`, and report `filed: #N <subject>`. A filer whose `filed` failed
4073
- twice reports `unrecorded: #N <subject>` instead, and you run `filed` for it.
4095
+ twice reports `unrecorded: #N <subject>` instead — an `unrecorded` entry of
4096
+ its report file — and `settle <member> --from-report` runs `filed` for it.
4074
4097
  - **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
4075
4098
  so a replacement controller does not re-litigate a settled call.
4076
4099
 
@@ -6,6 +6,8 @@ arg testCmd testCmd
6
6
  arg scratch scratch
7
7
  path worktree
8
8
  path scratch
9
+ literal your name
10
+ literal outcome
9
11
  ---
10
12
  ## kind: fresh, repair
11
13
  Finish PR <M>. Your arguments are the whole of your per-dispatch task:
@@ -15,6 +17,15 @@ worktree: <abs-path>
15
17
  pin: <your dispatch pin>
16
18
  testCmd: <testCmd>
17
19
  scratch: <scratch>
20
+
21
+ Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
22
+ `finisher-pr-<M>[-x]` you were dispatched as, in the shape
23
+ `~/.fleet/bin/fleet-run report-schema.mjs print finisher` prints. Write it
24
+ before your final message, and send nothing until
25
+ `~/.fleet/bin/fleet-run report-schema.mjs validate finisher <scratch>/reports/<your name>.json`
26
+ answers `valid`. Your final message is then one line,
27
+ `<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
28
+ report's `outcome`.
18
29
  ## kind: repair
19
30
 
20
31
  An earlier finisher on this PR reported `labelled`, but its read-back did not carry `ready-to-merge`: you are the repair finisher. Duty 3's script decides whether the label is on, as above.
@@ -11,6 +11,7 @@ path worktree
11
11
  path scratch
12
12
  path mismatched-record
13
13
  literal your name
14
+ literal outcome
14
15
  ---
15
16
  ## kind: review, dispositions-retry
16
17
  You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
@@ -74,6 +75,16 @@ Report the new head and **stop**: do not watch, poll or wait for CI — the
74
75
  controller owns the next run on the pushed head. A red that is not yours to
75
76
  fix — a flake that passes on rerun, or staleness — gets nothing pushed: report
76
77
  that instead.
78
+ ## kind: review, dispositions-retry, conflict, red-check
79
+
80
+ Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
81
+ `fix-pr-` name you were dispatched as, in the shape
82
+ `~/.fleet/bin/fleet-run report-schema.mjs print fix-pr` prints. Write it
83
+ before your final message, and send nothing until
84
+ `~/.fleet/bin/fleet-run report-schema.mjs validate fix-pr <scratch>/reports/<your name>.json`
85
+ answers `valid`. Your final message is then one line,
86
+ `<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
87
+ report's `outcome`.
77
88
  ## kind: dispositions-retry
78
89
 
79
90
  This is the one automatic retry of a dispositions mismatch. The mismatched
@@ -7,10 +7,12 @@ arg brief distilled brief
7
7
  arg staleness staleness
8
8
  path worktree
9
9
  path scratch
10
+ literal your name
11
+ literal outcome
10
12
  ---
11
13
  Implement ticket <N>. You are ALREADY in worktree `<abs-path>`, whose PR branch is
12
- `<branch>`. Your scratch directory is `<scratch>/impl-<N>/`; write nowhere else
13
- outside the worktree.
14
+ `<branch>`. Your scratch directory is `<scratch>/impl-<N>/`; outside the worktree,
15
+ write nowhere else but your report file below.
14
16
 
15
17
  The ticket, pasted verbatim from the controller's own read — its title, the
16
18
  `## Agent Brief` comment or the issue body, whichever carries the brief, and its
@@ -20,5 +22,14 @@ The ticket, pasted verbatim from the controller's own read — its title, the
20
22
 
21
23
  The controller's staleness probe: <staleness>
22
24
 
25
+ Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
26
+ `impl-<N>[-x]` you were dispatched as, in the shape
27
+ `~/.fleet/bin/fleet-run report-schema.mjs print impl` prints. Write it before
28
+ your final message, and send nothing until
29
+ `~/.fleet/bin/fleet-run report-schema.mjs validate impl <scratch>/reports/<your name>.json`
30
+ answers `valid`. Your final message is then one line,
31
+ `<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
32
+ report's `outcome`.
33
+
23
34
  The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
24
35
  A member runs its test suite in the foreground and blocks on it. Exit 75 from the suite is not a test result; run the command again.
@@ -7,4 +7,11 @@ You are merge-bot-<n>.
7
7
 
8
8
  scratch: <scratch>
9
9
 
10
+ Your report is a file, `<scratch>/reports/merge-bot-<n>.json`, in the shape
11
+ `~/.fleet/bin/fleet-run report-schema.mjs print merge-bot` prints. Write it
12
+ before your final message, and send nothing until
13
+ `~/.fleet/bin/fleet-run report-schema.mjs validate merge-bot <scratch>/reports/merge-bot-<n>.json`
14
+ answers `valid`. Your final message is then one line,
15
+ `merge-bot-<n>: done <scratch>/reports/merge-bot-<n>.json`.
16
+
10
17
  The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.