@feigi/fleet-ctl 3.104.0 → 3.105.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.
@@ -114,11 +114,20 @@ not rely on that.
114
114
  (the path you were dispatched with, and the full SHA). It reads the PR's diff
115
115
  from the merge base with `origin/main` to your pin and classifies every path.
116
116
  Exit 0 means every path is prose (plain `.md` or `.markdown` outside the
117
- prompt surface) or data (a run-metrics file): an **Inert diff**. Only exit 0
117
+ prompt surface) or data (a run-metrics file): an **Inert diff**, and it
118
118
  skips the acceptance mutation below. Exit 1 (not inert) and exit 2 (could not
119
119
  look) both run the mutation exactly as it is described below. When you skip,
120
120
  the verdict's one JSON line goes in your report in place of the `red:` line.
121
121
 
122
+ **A Ticketless PR has no acceptance mutation to re-run.** Run
123
+ `~/.fleet/bin/fleet-run ticketless.mjs --pr <M>`. It reads whether the PR
124
+ closes an issue in its own repository and whether a settled
125
+ `impl-<N>=PR#<M>` token names it. Only its exit 0 skips the acceptance
126
+ mutation below, whatever the diff, and the rest of duty 2 runs. Where a kill's
127
+ evidence line would go, your report says that no mutation ran because the PR is
128
+ ticketless. Exit 1 and exit 2 (could not look) run duty 2 as it is described
129
+ for a ticket PR.
130
+
122
131
  **Whatever you verify by RUNNING, run in a tree nobody else owns.**
123
132
  Independently re-running the ticket's acceptance mutation — loosen the
124
133
  regex, delete the guard clause, flip the per-entry reset, run `<testCmd>`,
@@ -229,13 +238,18 @@ evidence; label nothing. A kill's evidence line goes in your report.
229
238
  **Duty 3 is one script, and its exit code is your verdict.**
230
239
  `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
231
240
  (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
232
- PR, records the head you audited, adds `ready-to-merge`, and reads the labels
241
+ PR — a Ticketless PR with none gets `patch` added first — records the head you
242
+ audited, adds `ready-to-merge`, and reads the labels
233
243
  back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
234
- carries zero or more than one release label: you are halted before the label,
235
- and the receipt names which it found. Exit 4 means the read-back does not carry
236
- the label, written or not. Exit 2 means a `gh` call or the invocation
237
- itself failed: report the stderr it printed. Every non-zero exit halts you
238
- with cause `other`, with the receipt as evidence, and you do not run any of
244
+ carries zero or more than one release label (a Ticketless PR with none is
245
+ labelled `patch` instead): you are halted
246
+ before the label, and the receipt names which it found. Exit 4 means the
247
+ read-back does not carry the label, written or not. Exit 5 means the PR is a
248
+ Ticketless PR whose diff is not inert, or whose Inert diff verdict could not
249
+ look: the script posted the head record and added no label, and you are halted
250
+ with cause `human`. Exit 2 means a `gh` call or the invocation itself failed:
251
+ report the stderr it printed. Every non-zero exit halts you, with cause `other`
252
+ unless it is exit 5, with the receipt as evidence, and you do not run any of
239
253
  its steps by hand to get past it. A repo whose label list defines none of the
240
254
  three does not gate on one, and the script says so in its receipt. Put the
241
255
  receipt, the JSON line it printed, in your report as printed: it is what tells
@@ -250,7 +264,7 @@ controller's settle records — and, for anything it halted on, `cause` and
250
264
  `evidence`, below, never a bare "head moved". The
251
265
  cause is one word of the ledger's `halted:<cause>` vocabulary:
252
266
  `live-editor`, `rebase`, `past-pin`, `unreadable`, `missing` or `absent` as
253
- duty 1's verdict names it, and `other` for every other halt — that
267
+ duty 1's verdict names it, `human` for duty 3's exit 5, and `other` for every other halt — that
254
268
  verdict's own `other`, and a halt at duty 2, duty 3 or the instrument
255
269
  re-check. A duty 1 halt's `evidence` carries the verdict as
256
270
  printed, the JSON line, so a `rebase` halt's carries `replay`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.104.0",
3
+ "version": "3.105.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": {
@@ -12,14 +12,22 @@
12
12
  //
13
13
  // Steps, in this order, each one only if every earlier one held:
14
14
  //
15
+ // 0 ask ticketless.mjs whether the PR is a Ticketless PR: one that closes no
16
+ // issue in its own repository and that no settled implementer token
17
+ // names. A test that could not look is exit 2.
15
18
  // 1 read the PR's labels and comments and count the release labels,
16
- // `patch`/`minor`/`major`. Exactly one passes. Zero or several is exit 3
17
- // and nothing is written. A repo whose label list defines none of the
18
- // three has nothing to count: the count is skipped and the receipt says
19
- // `releaseLabels: "undefined-in-repo"`. That list is read only when the
20
- // PR carries none of them — one on the PR proves it is defined — and a
21
- // list that fills the limit it was read with proves nothing, so it is
22
- // exit 2 rather than a skipped count.
19
+ // `patch`/`minor`/`major`. Exactly one passes. Several is exit 3 and
20
+ // nothing is written. Zero is exit 3 and nothing is written, except on a
21
+ // Ticketless PR, which gets `patch` added and passes. A repo whose label
22
+ // list defines none of the three has nothing to count: the count is
23
+ // skipped and the receipt says `releaseLabels: "undefined-in-repo"`. That
24
+ // list is read only when the PR carries none of them — one on the PR
25
+ // proves it is defined — and a list that fills the limit it was read with
26
+ // proves nothing, so it is exit 2 rather than a skipped count.
27
+ // 1b on a Ticketless PR, finisher-scope.mjs's Inert diff verdict at `--pin`,
28
+ // run in-process. A diff that is not inert, or a verdict that could not
29
+ // look, stops after step 2: the head record is posted, the label is not
30
+ // added, and the exit is 5.
23
31
  // 2 comment `ready-to-merge-head: <pin>`, the record the merge bot reads as
24
32
  // the head the label was applied to — skipped when the newest such
25
33
  // comment already names this pin.
@@ -33,11 +41,15 @@
33
41
  //
34
42
  // Stdout is always one JSON line, the receipt:
35
43
  //
36
- // {pr, pin, releaseLabels, commented, added, readBack, exit, firstRead
37
- // [, step, error]}
44
+ // {pr, pin, ticketless, releaseLabels, patchAdded, inert, commented, added,
45
+ // readBack, exit, firstRead [, step, error]}
38
46
  //
39
- // releaseLabels the release labels the PR carried, or "undefined-in-repo",
40
- // or null when step 1 never got an answer
47
+ // ticketless the Ticketless test's answer, null when it never got one
48
+ // releaseLabels the release labels the PR carried (`patch` once added to a
49
+ // Ticketless PR), or "undefined-in-repo", or null when step 1
50
+ // never got an answer
51
+ // patchAdded this run added `patch`
52
+ // inert the Inert diff verdict object, null when it never ran
41
53
  // commented this run posted the head record
42
54
  // added this run wrote the label
43
55
  // readBack every label name the step 4 read carried, null if it never ran
@@ -52,16 +64,22 @@
52
64
  // Exit vocabulary:
53
65
  //
54
66
  // 0 the read-back carries `ready-to-merge`
55
- // 2 the invocation or a `gh` call failed — its stderr is in the receipt and
56
- // on stderr, and no later step ran
67
+ // 2 the invocation or a `gh` call failed, or the Ticketless test could not
68
+ // look — its stderr is in the receipt and on stderr, and no later step ran
57
69
  // 3 the PR does not carry exactly one release label — nothing was written
58
70
  // 4 every write returned 0 and the read-back does not carry the label
71
+ // 5 a Ticketless PR whose diff is not inert, or whose verdict could not
72
+ // look: the head record is posted and the label is not added, so the
73
+ // maintainer's `ready-to-merge` is the merge
59
74
 
60
75
  import { spawnSync } from "node:child_process";
61
76
  import { statSync } from "node:fs";
77
+ import { resolve } from "node:path";
62
78
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
79
+ import { inertVerdict } from "./finisher-scope.mjs";
63
80
  import { gitEnv } from "./git-env.mjs";
64
81
  import { LABEL_LIST_ARGS, LABEL_LIST_LIMIT, releaseLabelsDefined, releaseLabelsIn } from "./release-labels.mjs";
82
+ import { ticketlessVerdict } from "./ticketless.mjs";
65
83
 
66
84
  const NAME = "finisher-label";
67
85
  const LABEL = "ready-to-merge";
@@ -85,7 +103,10 @@ if (pr === null || pinArg === null) die(USAGE);
85
103
  const receipt = {
86
104
  pr,
87
105
  pin: pinArg,
106
+ ticketless: null,
88
107
  releaseLabels: null,
108
+ patchAdded: false,
109
+ inert: null,
89
110
  commented: false,
90
111
  added: false,
91
112
  readBack: null,
@@ -150,6 +171,12 @@ const namedList = (v) => Array.isArray(v) && v.every((l) => isObject(l) && typeo
150
171
 
151
172
  const labelNames = (v) => v.labels.map((l) => l.name);
152
173
 
174
+ // --- 0: the Ticketless test ------------------------------------------------
175
+ const test = await ticketlessVerdict({ pr, repo: repo === null ? null : resolve(repo) });
176
+ if (test.exit === 2) fail("ticketless", test.reason);
177
+ const ticketless = test.exit === 0;
178
+ receipt.ticketless = ticketless;
179
+
153
180
  // --- 1: the release-label count -------------------------------------------
154
181
  const first = ghJson("read-labels", ["pr", "view", String(pr), "--json", "labels,comments"], (v) =>
155
182
  isObject(v) && namedList(v.labels) && Array.isArray(v.comments) && v.comments.every((c) => isObject(c) && typeof c.body === "string" && typeof c.createdAt === "string"));
@@ -160,19 +187,31 @@ const found = releaseLabelsIn(firstLabels);
160
187
  if (found.length === 0) {
161
188
  const defined = ghJson("list-labels", LABEL_LIST_ARGS, namedList).map((l) => l.name);
162
189
  const state = releaseLabelsDefined(defined);
163
- if (state === "defined") {
164
- finish(3, { releaseLabels: found }, "the PR carries no release label (patch, minor or major); nothing was written");
165
- }
166
190
  if (state === "cut-off") {
167
191
  fail("list-labels", `the repository has ${LABEL_LIST_LIMIT} or more labels, so the list may be cut off before patch, minor or major`);
168
192
  }
169
- receipt.releaseLabels = "undefined-in-repo";
193
+ if (state === "undefined") {
194
+ receipt.releaseLabels = "undefined-in-repo";
195
+ } else if (!ticketless) {
196
+ finish(3, { releaseLabels: found }, "the PR carries no release label (patch, minor or major); nothing was written");
197
+ } else {
198
+ // No ticket picks the bump of a Ticketless PR, so it gets the smallest.
199
+ gh("add-patch", ["pr", "edit", String(pr), "--add-label", "patch"]);
200
+ receipt.patchAdded = true;
201
+ receipt.releaseLabels = ["patch"];
202
+ }
170
203
  } else if (found.length > 1) {
171
204
  finish(3, { releaseLabels: found }, `the PR carries more than one release label (${found.join(", ")}); nothing was written`);
172
205
  } else {
173
206
  receipt.releaseLabels = found;
174
207
  }
175
208
 
209
+ // --- 1b: the Inert diff verdict, on a Ticketless PR ------------------------
210
+ // No ticket gives a Ticketless PR its ruling or its acceptance mutation, so it
211
+ // merges unattended only when its whole diff is inert; otherwise the head is
212
+ // recorded and the maintainer's label is the merge.
213
+ if (ticketless) receipt.inert = inertVerdict({ worktree: resolve(repo ?? "."), pin });
214
+
176
215
  // --- 2: the head record ----------------------------------------------------
177
216
  // The newest record wins, the way the merge bot reads it: a matching record
178
217
  // older than one naming another head is not the record the bot will act on.
@@ -189,6 +228,11 @@ if (!recorded) {
189
228
  receipt.commented = true;
190
229
  }
191
230
 
231
+ if (ticketless && receipt.inert.exit !== 0) {
232
+ const why = receipt.inert.verdict === "unknown" ? `its diff could not be read (${receipt.inert.reason})` : "its diff is not inert";
233
+ finish(5, {}, `the PR is a Ticketless PR and ${why}: the head is recorded and ${LABEL} is left to the maintainer`);
234
+ }
235
+
192
236
  // --- 3: the label ----------------------------------------------------------
193
237
  if (!(recorded && labelled)) {
194
238
  gh("add-label", ["pr", "edit", String(pr), "--add-label", LABEL]);
@@ -49,10 +49,11 @@
49
49
  // nothing. Missing or unparsable is depth 0 and a
50
50
  // refresh, never a refusal: the depth only ever bounds PULLs
51
51
  // downward. A file with no `dropped` names no drops.
52
- // gh The open PRs, by label, by whether they close an issue, by
53
- // GitHub's `mergeable`, and by head and body — the merge queue,
54
- // which PRs are owed a review, which conflict, which queued PR
55
- // still matches the head and body it was parked at, and the PR
52
+ // gh The open PRs, by label, by owner (author and draft flag), by
53
+ // whether they close an issue, by GitHub's `mergeable`, and by
54
+ // head and body — the merge queue, which PRs are owed a review,
55
+ // which conflict, which queued PR still matches the head and body
56
+ // it was parked at, and the PR
56
57
  // half of the In-flight count:
57
58
  // every open PR that closes an issue, whoever opened it and
58
59
  // whatever its state. Also, for each in-flight `review=` token
@@ -77,9 +78,9 @@
77
78
  // or cannot be judged, or a step `failed`, `pending` or absent
78
79
  // prints one PHASE0-INCOMPLETE line naming what is not done and
79
80
  // holds every dispatching row, ahead of the main-checkout reason;
80
- // it never refuses the tick. A step's `drift` or `unanswered`
81
- // and a `fold-in` NEED are advice, named on the line and holding
82
- // nothing. The receipt's `session` fills the tier hold's step.
81
+ // it never refuses the tick. A step's `drift` or `unanswered` is
82
+ // advice, named on the line and holding nothing. The receipt's
83
+ // `session` fills the tier hold's step.
83
84
  // guard `.fleet/cost-guard.json` beside the shortlist, pr-cost.mjs
84
85
  // --guard's verdict on the implementer cells. Printed as the
85
86
  // `router` row and never acted on here: a missing or unreadable
@@ -1167,16 +1168,16 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed
1167
1168
  && (((st.survived > 0 || st.unverified > 0) && !st.reviewFixed) || conflictHeld(st) || mismatchDue(st))
1168
1169
  && !fixRunning(st) && !st.inFlight)
1169
1170
  .map(([n]) => n).sort(asc),
1170
- // Open, not signed off, closing an issue (GitHub's own linked set — a
1171
- // PR closing nothing is review work nobody in the run will ever be
1172
- // dispatched against), with no live or returned review on record —
1171
+ // Open, not signed off, owned (openPrs() reads that off the PR's author
1172
+ // and draft flag; a PR closing no issue is as due as one closing one),
1173
+ // with no live or returned review on record —
1173
1174
  // or a returned review its finisher halted `past-pin` against: the
1174
1175
  // head carries commits no reviewer read, so it is owed a review again
1175
1176
  // until one is running or has returned. A head that moved past
1176
1177
  // `reviewed=` with no such halt — a fix-applier's push — stays not due:
1177
1178
  // finisher duty 2 verifies what it applied.
1178
1179
  reviewDue: prs
1179
- .filter((p) => !isQueued(p) && p.closingIssuesReferences.length > 0
1180
+ .filter((p) => !isQueued(p) && p.owned
1180
1181
  && (!state(p.number)?.reviewedAny || pastPinDue(state(p.number), p.headRefOid)))
1181
1182
  .map((p) => p.number).sort(asc),
1182
1183
  mergeQueue: queued.length,
@@ -1547,6 +1548,7 @@ import { readRunReceipt, phase0Gate, IN_FLIGHT_DEFAULT } from "./phase0-receipt.
1547
1548
  import { judgeRecord, ProcUnreadable } from "./proc.mjs";
1548
1549
  import { reportFamily, readReport, reportPath, reportsDir } from "./report-files.mjs";
1549
1550
  import { ownClosingIssues } from "./closing-refs.mjs";
1551
+ import { GH_LOGIN_ARGS, isOwnedPr, loginOf, ownershipReadable } from "./owned-pr.mjs";
1550
1552
 
1551
1553
  const NAME = "fleet-tick";
1552
1554
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -1582,6 +1584,10 @@ export function ghBudget(defaultSeconds, override) {
1582
1584
  }
1583
1585
  const GH_TIMEOUT_MS = ghBudget(20, process.env.FLEET_TICK_GH_TIMEOUT);
1584
1586
  const TIMED_OUT = `timed out after ${GH_TIMEOUT_MS / 1000}s`;
1587
+ // Why a `gh` execFileSync threw. Never interpolates e.stderr or e.message:
1588
+ // execFileSync already forwarded the child's stderr to ours, and Node builds
1589
+ // e.message out of it, so either one emits every byte a second time.
1590
+ const execFailure = (e) => (e.code === "ETIMEDOUT" ? TIMED_OUT : e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`));
1585
1591
 
1586
1592
  // die() shared with the other fleet scripts (writeSync-based, pipe-safe —
1587
1593
  // see arg.mjs for the rationale). This file parses its own
@@ -1665,20 +1671,31 @@ function options() {
1665
1671
  // The open PRs, validated, each with its closingIssuesReferences reduced to
1666
1672
  // `{number}` for every issue it closes in its own repository, by
1667
1673
  // ownClosingIssues()'s rule: another repository's reference, whatever its
1668
- // number, closes none of this repository's tickets. A failed read is not an
1669
- // empty pipeline: backlog 0 + merge-queue 0 is a plausible tick, so printing
1670
- // it off a failed query is the silent stall this script exists to end.
1671
- const PR_ROW_SHAPE = "{number,labels,closingIssuesReferences[{number,url|repository{name,owner{login}}}],headRefOid,mergeable,body,url} rows, url ending /pull/<number>, mergeable one of MERGEABLE, CONFLICTING, UNKNOWN";
1674
+ // number, closes none of this repository's tickets. Each also carries `owned`,
1675
+ // owned-pr.mjs's rule applied to the login the `gh` credentials answer to,
1676
+ // read once here: a read that failed or printed no login refuses the tick,
1677
+ // because "owns nothing" would drop every PR from review work. A failed read
1678
+ // is not an empty pipeline: backlog 0 + merge-queue 0 is a plausible tick, so
1679
+ // printing it off a failed query is the silent stall this script exists to end.
1680
+ const PR_ROW_SHAPE = "{number,labels,closingIssuesReferences[{number,url|repository{name,owner{login}}}],headRefOid,mergeable,body,url,author{login},isDraft} rows, url ending /pull/<number>, mergeable one of MERGEABLE, CONFLICTING, UNKNOWN";
1681
+ function runLogin() {
1682
+ let out;
1683
+ try {
1684
+ out = execFileSync("gh", GH_LOGIN_ARGS, { encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS });
1685
+ } catch (e) {
1686
+ die(`gh ${GH_LOGIN_ARGS.join(" ")} failed: ${execFailure(e)} — a failed read is not a login that owns nothing`);
1687
+ }
1688
+ const login = loginOf(out);
1689
+ if (login === null) die(`gh ${GH_LOGIN_ARGS.join(" ")} printed no login — a read that answered nothing is not a login that owns nothing`);
1690
+ return login;
1691
+ }
1672
1692
  function openPrs() {
1673
1693
  let out;
1674
1694
  try {
1675
1695
  out = execFileSync("gh", ["pr", "list", "--state", "open", "--limit", String(PR_LIMIT),
1676
- "--json", "number,labels,closingIssuesReferences,headRefOid,mergeable,body,url"], { encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS });
1696
+ "--json", "number,labels,closingIssuesReferences,headRefOid,mergeable,body,url,author,isDraft"], { encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS });
1677
1697
  } catch (e) {
1678
- // Never interpolates e.stderr or e.message: execFileSync already forwarded
1679
- // the child's stderr to ours, and Node builds e.message out of it, so
1680
- // either one emits every byte a second time.
1681
- die(`gh pr list failed: ${e.code === "ETIMEDOUT" ? TIMED_OUT : e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)} — a failed read is not an empty queue`);
1698
+ die(`gh pr list failed: ${execFailure(e)} — a failed read is not an empty queue`);
1682
1699
  }
1683
1700
  let prs;
1684
1701
  try {
@@ -1700,15 +1717,17 @@ function openPrs() {
1700
1717
  // matched or lifted.
1701
1718
  if (!Array.isArray(prs) || prs.some((p) => !p || typeof p.number !== "number"
1702
1719
  || !Array.isArray(p.labels) || !Array.isArray(p.closingIssuesReferences) || typeof p.url !== "string"
1703
- || typeof p.headRefOid !== "string" || !MERGEABLE_STATES.includes(p.mergeable) || typeof p.body !== "string")) {
1720
+ || typeof p.headRefOid !== "string" || !MERGEABLE_STATES.includes(p.mergeable) || typeof p.body !== "string"
1721
+ || !ownershipReadable(p))) {
1704
1722
  die(`gh pr list did not return ${PR_ROW_SHAPE}`);
1705
1723
  }
1706
1724
  if (prs.length === PR_LIMIT) {
1707
1725
  die(`exactly ${PR_LIMIT} open PRs — the list is capped and may be truncated. Raise PR_LIMIT; a backlog that silently drops PRs is not a reconcile.`);
1708
1726
  }
1727
+ const login = runLogin();
1709
1728
  return prs.map((p) => {
1710
1729
  try {
1711
- return { ...p, closingIssuesReferences: ownClosingIssues(p.number, p.url, p.closingIssuesReferences).map((number) => ({ number })) };
1730
+ return { ...p, owned: isOwnedPr(p, login), closingIssuesReferences: ownClosingIssues(p.number, p.url, p.closingIssuesReferences).map((number) => ({ number })) };
1712
1731
  } catch (e) {
1713
1732
  die(`gh pr list did not return ${PR_ROW_SHAPE}: PR #${p.number} answered ${e.message}`);
1714
1733
  }
@@ -59,8 +59,9 @@ const FAMILIES = {
59
59
  export const MEMBER_FAMILIES = Object.freeze(Object.keys(FAMILIES));
60
60
  // A finisher halt's causes: the finisher worked correctly and refused
61
61
  // to label, which `failed` (it crashed or gave up) does not say. `unreadable`,
62
- // `missing` and `absent` are duty 1's audit-read halts.
63
- export const HALT_CAUSES = ["live-editor", "rebase", "past-pin", "unreadable", "missing", "absent", "other"];
62
+ // `missing` and `absent` are duty 1's audit-read halts. `human` is a Ticketless
63
+ // PR whose diff is not inert: it merges only when the maintainer labels it.
64
+ export const HALT_CAUSES = ["live-editor", "rebase", "past-pin", "unreadable", "missing", "absent", "other", "human"];
64
65
  const OUTCOME_PATTERNS = {
65
66
  "PR#M": /^PR#[1-9][0-9]*$/,
66
67
  "applied:<head>": /^applied:[0-9a-f]{7,40}$/i,
@@ -66,6 +66,7 @@ import { attemptLock, releaseLockFile, reapPathOf } from "./pid-lock.mjs";
66
66
  import { readCheckRecordIn, readReportIn, reportsDir, reportFamily, defaultScratch, reportPath } from "./report-files.mjs";
67
67
  import { mergeBotVerdicts } from "./report-schema.mjs";
68
68
  import { ownClosingIssues } from "./closing-refs.mjs";
69
+ import { isTicketless } from "./ticketless.mjs";
69
70
  import { RELEASE_LABELS, LABEL_LIST_ARGS, LABEL_LIST_LIMIT, releaseLabelsIn, releaseLabelsDefined } from "./release-labels.mjs";
70
71
 
71
72
  const NAME = "ledger";
@@ -2081,10 +2082,12 @@ async function closingRefusals(member, { tickets, ruling, tsv }) {
2081
2082
  // rulingOf() found settled implementer tokens naming the PR for, and `refs`
2082
2083
  // the issues closingRefusals() read it closing, its own suggestion-band
2083
2084
  // record aside. Returns the refusal, or null.
2084
- // A PR with none is repaired with `patch` only when it closes no ticket and
2085
- // no such token names it; any other PR's bump is not picked here, and
2086
- // neither is which of several labels stays. A read the check needs dies,
2087
- // naming the labels it could not read, and writes nothing.
2085
+ // A Ticketless PR (ticketless.mjs's isTicketless) with none is not refused:
2086
+ // finisher-label.mjs adds `patch` to it. A repository label list that may be
2087
+ // cut off still refuses it, as finisher-label.mjs refuses it then too. Any
2088
+ // other PR's bump is not picked here, and neither is which of several labels
2089
+ // stays. A read the check needs dies, naming the labels it could not read,
2090
+ // and writes nothing.
2088
2091
  function releaseLabelRefusal(member, tickets, refs) {
2089
2092
  const pr = member.number;
2090
2093
  const where = `dispatch ${member.name}`;
@@ -2097,8 +2100,8 @@ function releaseLabelRefusal(member, tickets, refs) {
2097
2100
  if (defined === "cut-off") {
2098
2101
  die(`${where}: could not read the repository's labels — gh ${LABEL_LIST_ARGS.join(" ")} answered ${LABEL_LIST_LIMIT} or more, so the list may be cut off before ${RELEASE_LABELS.join(", ")}; nothing written`);
2099
2102
  }
2103
+ if (isTicketless(refs, tickets)) return null;
2100
2104
  const missing = `PR #${pr} carries no release label (${RELEASE_LABELS.join(", ")})`;
2101
- if (refs.length === 0 && tickets.length === 0) return `${missing} and closes no ticket — add one: gh pr edit ${pr} --add-label patch`;
2102
2105
  const closes = refs.length > 0
2103
2106
  ? `closes ${refs.map((n) => `#${n}`).join(", ")}`
2104
2107
  : `closes no ticket, and is the implementer PR of ${tickets.map((n) => `#${n}`).join(", ")}`;
@@ -0,0 +1,34 @@
1
+ // Which open PRs the fleet owns, as one rule for every reader. An Owned PR is
2
+ // an open, non-draft PR whose `author.login` is the login the fleet's `gh`
3
+ // credentials answer to: every member acts through those credentials, so every
4
+ // PR the fleet opens carries it. A bot's PR, a stranger's, a fork's and a draft
5
+ // are not owned, whatever they close.
6
+ //
7
+ // Each reader reads the login itself, at its own read, with GH_LOGIN_ARGS, and
8
+ // parses what `gh` printed with loginOf(). A read that failed or printed no
9
+ // login is a refusal by that reader, never "owns nothing".
10
+
11
+ // The `gh` arguments whose stdout is the login the credentials answer to.
12
+ export const GH_LOGIN_ARGS = ["api", "user", "-q", ".login"];
13
+
14
+ // The login `gh api user -q .login` printed, or null when it printed none.
15
+ export function loginOf(stdout) {
16
+ const login = typeof stdout === "string" ? stdout.trim() : "";
17
+ return login === "" ? null : login;
18
+ }
19
+
20
+ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
21
+
22
+ // Whether `pr`, a row of `gh pr list --json author,isDraft,…`, carries what
23
+ // isOwnedPr() reads: an author that is null (an account GitHub no longer has)
24
+ // or has a string login, and a boolean draft flag. A reader refuses a row that
25
+ // does not, since whether it is owned is unknown.
26
+ export function ownershipReadable(pr) {
27
+ return isRecord(pr) && (pr.author === null || (isRecord(pr.author) && typeof pr.author.login === "string")) && typeof pr.isDraft === "boolean";
28
+ }
29
+
30
+ // Whether `pr`, a row of `gh pr list --json author,isDraft,…`, is an Owned PR
31
+ // of `login`. An absent or malformed author or draft flag is not owned.
32
+ export function isOwnedPr(pr, login) {
33
+ return typeof login === "string" && login !== "" && pr?.author?.login === login && pr?.isDraft === false;
34
+ }
@@ -94,9 +94,8 @@ const phase0Command = (session) => `~/.fleet/bin/fleet-run phase0.mjs --session
94
94
  * run's, else null.
95
95
  *
96
96
  * A step `failed` or `pending`, in a status this reader does not know, or
97
- * absent from the receipt, holds. `drift` and `unanswered`, and a `NEED` line
98
- * in a `fold-in` step's output, are advice: named on the line, holding
99
- * nothing.
97
+ * absent from the receipt, holds. `drift` and `unanswered` are advice: named
98
+ * on the line, holding nothing.
100
99
  */
101
100
  export function phase0Gate(read, { path, controllerAt = null, controller = "none" }) {
102
101
  const held = (why, session = null) => ({
@@ -120,11 +119,7 @@ export function phase0Gate(read, { path, controllerAt = null, controller = "none
120
119
  ...steps.filter(([, step]) => !DONE.has(step.status)).map(([name]) => name),
121
120
  ...absent,
122
121
  ];
123
- const advice = [
124
- ...steps.filter(([, step]) => ADVICE.has(step.status)).map(([name, step]) => `${name} ${step.status}`),
125
- ...String(receipt.steps["fold-in"]?.output ?? "").split("\n").map((l) => l.trim())
126
- .filter((l) => l.startsWith("NEED ")).map((l) => `fold-in ${l}`),
127
- ];
122
+ const advice = steps.filter(([, step]) => ADVICE.has(step.status)).map(([name, step]) => `${name} ${step.status}`);
128
123
  const session = receipt.session === "" ? null : receipt.session;
129
124
  if (incomplete.length) {
130
125
  const said = held(incomplete.join(", "), session);
@@ -61,10 +61,12 @@
61
61
  // Either exiting 1 is a cache with nothing valid in it: pending,
62
62
  // `NEED derive-recipe`. Exit 3 (a tool the reader could not run)
63
63
  // fails the step — deriving would not help.
64
- // fold-in every open PR no carried ledger row names: one that closes an
65
- // issue gets a `#<pr>` row from `ledger.mjs row` (the tick queues
66
- // its review off it); one that closes none is listed as `NEED
67
- // review PR#<pr> (closes no issue)`.
64
+ // fold-in every Owned PR (owned-pr.mjs: open, not a draft, authored by
65
+ // the login `gh api user` answers to) that no carried ledger
66
+ // row names gets a `#<pr>` row from `ledger.mjs row`, closing an
67
+ // issue or not (the tick queues its review off it). A PR that
68
+ // is not owned gets no row and no line, whatever it closes. A
69
+ // login read that fails fails the step.
68
70
  // stranded `stranded.mjs`. A `resume` entry whose ticket has no ledger row
69
71
  // yet is pending: `NEED resume #<n> <worktree> <branch>`. A
70
72
  // `report` entry is printed as `report #<n> — <why>`, and the step
@@ -138,10 +140,7 @@
138
140
  // Exit 0 every step ok, or `drift`/`unanswered` — advice the run goes on past;
139
141
  // 2 a usage error; 3 a step failed, or the run could not start or record itself
140
142
  // (the scratch root, the controller record, the receipt); 4 a step needs the
141
- // controller — dispatch what the NEED line names, then run this again. A NEED
142
- // the fold-in prints is advice too and changes no exit status: a PR with no
143
- // issue behind it is the controller's to queue or leave, and nothing a re-run
144
- // could meet.
143
+ // controller — dispatch what the NEED line names, then run this again.
145
144
  //
146
145
  // Zero deps: node builtins and sibling scripts only.
147
146
 
@@ -156,6 +155,7 @@ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
156
155
  import { readState, stateFileIn } from "./fleet-state.mjs";
157
156
  import { gitEnv } from "./git-env.mjs";
158
157
  import { isCLI } from "./is-cli.mjs";
158
+ import { GH_LOGIN_ARGS, isOwnedPr, loginOf, ownershipReadable } from "./owned-pr.mjs";
159
159
  import { RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
160
160
  import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
161
161
  import { IN_FLIGHT_DEFAULT, OBJECTIVES, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
@@ -363,7 +363,7 @@ function ledgerRows(cwd) {
363
363
  const rowKey = (row) => row.split(/\s/)[0];
364
364
 
365
365
  function foldIn({ cwd }) {
366
- const list = run("gh", ["pr", "list", "--state", "open", "--json", "number,closingIssuesReferences,url", "--limit", String(PR_LIMIT)], {
366
+ const list = run("gh", ["pr", "list", "--state", "open", "--json", "number,closingIssuesReferences,url,author,isDraft", "--limit", String(PR_LIMIT)], {
367
367
  cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS,
368
368
  });
369
369
  if (list.status !== 0) return refusal("gh pr list failed:", list);
@@ -375,16 +375,31 @@ function foldIn({ cwd }) {
375
375
  }
376
376
  if (!Array.isArray(prs)) return failed("gh pr list did not print a JSON array");
377
377
  if (prs.length >= PR_LIMIT) return failed(`gh pr list came back at its cap of ${PR_LIMIT} — it may hold more PRs than it showed, so none is folded in`);
378
- // The issues each PR closes in its own repository, by ownClosingIssues()'s
379
- // rule — another repository's reference closes none of this one's — read
380
- // for every PR before any row is written, so one that cannot be read folds
381
- // nothing in.
378
+ // Which PRs are the fleet's to fold in is decided by the login the `gh`
379
+ // credentials answer to. A read that failed or printed none is a refusal,
380
+ // never "owns nothing": that would fold nothing in and say ok.
381
+ const who = run("gh", GH_LOGIN_ARGS, { cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS });
382
+ if (who.status !== 0) return refusal(`gh ${GH_LOGIN_ARGS.join(" ")} failed:`, who);
383
+ const login = loginOf(who.stdout);
384
+ if (login === null) return failed(`gh ${GH_LOGIN_ARGS.join(" ")} printed no login — which PRs are owned is unknown, so none is folded in`);
385
+ // A null author is a PR whose account GitHub no longer has: no login of the
386
+ // run's, so not owned. A row with no `author` key, or no draft flag, is not
387
+ // what was asked for, and whether it is owned is unknown.
388
+ const unreadable = prs.find((pr) => !ownershipReadable(pr));
389
+ if (unreadable !== undefined) {
390
+ return failed(`gh pr list answered PR #${unreadable?.number} without an author and a draft flag — whether it is owned is unknown, so none is folded in`);
391
+ }
392
+ const owned = prs.filter((pr) => isOwnedPr(pr, login));
393
+ // The issues each owned PR closes in its own repository, by
394
+ // ownClosingIssues()'s rule — another repository's reference closes none of
395
+ // this one's — read for every one before any row is written, so one that
396
+ // cannot be read folds nothing in.
382
397
  const closing = new Map();
383
- for (const pr of prs) {
398
+ for (const pr of owned) {
384
399
  try {
385
- closing.set(pr, ownClosingIssues(pr?.number, pr?.url, pr?.closingIssuesReferences ?? []));
400
+ closing.set(pr, ownClosingIssues(pr.number, pr.url, pr.closingIssuesReferences ?? []));
386
401
  } catch (e) {
387
- return failed(`gh pr list answered PR #${pr?.number} with ${e.message} — which issues it closes is unknown, so none is folded in`);
402
+ return failed(`gh pr list answered PR #${pr.number} with ${e.message} — which issues it closes is unknown, so none is folded in`);
388
403
  }
389
404
  }
390
405
  const ledger = ledgerRows(cwd);
@@ -399,25 +414,20 @@ function foldIn({ cwd }) {
399
414
  if (pr !== null) named.add(pr);
400
415
  }
401
416
  const queued = [];
402
- const advice = [];
403
417
  let carried = 0;
404
- for (const pr of [...prs].sort((a, b) => a.number - b.number)) {
418
+ for (const pr of [...owned].sort((a, b) => a.number - b.number)) {
405
419
  if (named.has(pr.number)) {
406
420
  carried += 1;
407
421
  continue;
408
422
  }
409
423
  const issues = closing.get(pr);
410
- if (issues.length === 0) {
411
- advice.push(`NEED review PR#${pr.number} (closes no issue)`);
412
- continue;
413
- }
414
- const closes = `closes ${issues.map((n) => `#${n}`).join(", ")}`;
424
+ const closes = issues.length === 0 ? "closes no issue" : `closes ${issues.map((n) => `#${n}`).join(", ")}`;
415
425
  const w = node("ledger.mjs", ["row", String(pr.number), `PR#${pr.number} · inherited (${closes})`], { cwd });
416
426
  if (w.status !== 0) return refusal(`ledger.mjs row ${pr.number} failed:`, w);
417
427
  queued.push(`queued PR#${pr.number} for review (${closes})`);
418
428
  }
419
- const head = `${queued.length} PR(s) queued, ${carried} already on a carried row, ${advice.length} closing no issue`;
420
- return ok([head, ...queued, ...advice].join("\n"));
429
+ const head = `${queued.length} PR(s) queued, ${carried} already on a carried row`;
430
+ return ok([head, ...queued].join("\n"));
421
431
  }
422
432
 
423
433
  function stranded({ cwd }) {
@@ -0,0 +1,156 @@
1
+ #!/usr/bin/env node
2
+ // The Ticketless PR test as one script, so every reader that asks it asks the
3
+ // same question: is this PR one no ticket stands behind?
4
+ //
5
+ // ticketless.mjs --pr <M> [--repo <dir>] [--ledger <file>]
6
+ //
7
+ // A Ticketless PR closes no issue in its own repository (closing-refs.mjs's
8
+ // ownClosingIssues, read off `gh pr view --json closingIssuesReferences,url`)
9
+ // and no settled `impl-<N>=PR#<M>` token in the run ledger names it. No ticket
10
+ // then supplies its acceptance mutation or its ruling. The tokens are read
11
+ // through `ledger.mjs read`, as tier-check.mjs reads the ledger, and
12
+ // tier-outcomes.mjs's implementerClaims() decides which tokens name the PR.
13
+ //
14
+ // `--repo` is the directory `gh` runs in and the run ledger is resolved from
15
+ // (the cwd when omitted), against the git common dir as `ledger.mjs` resolves
16
+ // it; `--ledger` names the ledger file instead. A ledger that cannot be
17
+ // resolved is exit 2: `ledger.mjs`'s own cwd-relative fallback is never taken,
18
+ // since an empty cwd-local ledger would answer Ticketless. Reached through the
19
+ // Resolver: `~/.fleet/bin/fleet-run ticketless.mjs ...`.
20
+ //
21
+ // Stdout is one JSON line:
22
+ //
23
+ // {verdict, exit, pr, closing, tickets, reason}
24
+ //
25
+ // verdict "ticketless", "ticketed" or "unknown"
26
+ // exit 0 ticketless, 1 ticketed, 2 could not look
27
+ // closing the issue numbers the PR closes in its own repository, or null
28
+ // tickets the tickets the settled impl tokens naming the PR carry, or null
29
+ // reason null, or on exit 2 what could not be read
30
+ //
31
+ // Exit vocabulary:
32
+ //
33
+ // 0 Ticketless: the PR closes no own-repository issue and no settled impl
34
+ // token names it
35
+ // 1 not Ticketless: it closes an own-repository issue, or a settled impl
36
+ // token names it
37
+ // 2 could not look: a `gh` or ledger read failed, the run ledger could not
38
+ // be resolved, or the invocation was refused — never read as either answer
39
+ //
40
+ // The test is also exported as ticketlessVerdict(), which never exits the
41
+ // process, and as isTicketless(), the predicate over what was read, for a
42
+ // caller that has read the closing references and the tokens itself.
43
+
44
+ import { execFileSync } from "node:child_process";
45
+ import { statSync } from "node:fs";
46
+ import { dirname, join, resolve } from "node:path";
47
+ import { fileURLToPath } from "node:url";
48
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
49
+ import { ownClosingIssues } from "./closing-refs.mjs";
50
+ import { fleetFile } from "./fleet-dir.mjs";
51
+ import { gitEnv } from "./git-env.mjs";
52
+ import { isCLI } from "./is-cli.mjs";
53
+
54
+ const NAME = "ticketless";
55
+ const LEDGER_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "ledger.mjs");
56
+ const READ_TIMEOUT_MS = 60_000;
57
+ const USAGE = "usage: ticketless.mjs --pr <M> [--repo <dir>] [--ledger <file>]";
58
+ const EXIT = { ticketless: 0, ticketed: 1, unknown: 2 };
59
+
60
+ const die = makeDie(NAME);
61
+
62
+ // The test itself: no own-repository closing issue and no settled implementer
63
+ // ticket. `closing` and `tickets` are the arrays a reader got.
64
+ export function isTicketless(closing, tickets) {
65
+ return closing.length === 0 && tickets.length === 0;
66
+ }
67
+
68
+ // What a child printed on stderr, for a reason that names why it failed.
69
+ const why = (e) => String(e.stderr ?? "").trim().split("\n").at(-1) || e.code || e.message;
70
+
71
+ // The verdict for PR `pr`. Never exits the process: a caller in-process gets
72
+ // the same object the command prints. `repo` absent or null is the cwd, and
73
+ // `ledgerFile` absent or null is the run ledger resolved from `repo`.
74
+ export async function ticketlessVerdict({ pr, repo = null, ledgerFile = null }) {
75
+ const result = (verdict, fields) => ({ verdict, exit: EXIT[verdict], pr, closing: null, tickets: null, reason: null, ...fields });
76
+ const fail = (reason) => result("unknown", { reason });
77
+ if (!Number.isInteger(pr) || pr < 1) return fail("pr is not a positive integer");
78
+ const opts = { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: gitEnv(), timeout: READ_TIMEOUT_MS, ...(repo === null ? {} : { cwd: repo }) };
79
+
80
+ let view;
81
+ try {
82
+ view = JSON.parse(execFileSync("gh", ["pr", "view", String(pr), "--json", "closingIssuesReferences,url"], opts));
83
+ } catch (e) {
84
+ return fail(`gh pr view ${pr} --json closingIssuesReferences,url: ${why(e)}`);
85
+ }
86
+ let closing;
87
+ try {
88
+ closing = ownClosingIssues(pr, view?.url, view?.closingIssuesReferences);
89
+ } catch (e) {
90
+ return fail(`gh pr view ${pr} --json closingIssuesReferences,url answered ${e.message}`);
91
+ }
92
+
93
+ // The ledger path is resolved here, not left to `ledger.mjs read`: unable to
94
+ // resolve it, that falls back to a cwd-relative `.fleet/ledger.md` with only
95
+ // a warning on stderr, and reads its absence as no token at all.
96
+ let ledgerPath = ledgerFile;
97
+ if (ledgerPath === null) {
98
+ try {
99
+ ledgerPath = fleetFile("ledger.md", { cwd: repo ?? process.cwd(), timeoutMs: READ_TIMEOUT_MS });
100
+ } catch (e) {
101
+ return fail(`could not resolve the run ledger: ${e.message}`);
102
+ }
103
+ }
104
+ let ledger;
105
+ try {
106
+ const out = execFileSync(process.execPath, [LEDGER_SCRIPT, "--file", ledgerPath, "read"], opts);
107
+ ledger = JSON.parse(out);
108
+ } catch (e) {
109
+ return fail(`could not read the ledger: ${why(e)}`);
110
+ }
111
+ if (!Array.isArray(ledger?.rows) || !ledger.rows.every((r) => typeof r === "string")) return fail("ledger.mjs read printed no {rows}");
112
+ // tier-outcomes.mjs is imported here, not at the top: its import graph is
113
+ // several modules a caller that only wants isTicketless() never loads.
114
+ const { implementerClaims } = await import("./tier-outcomes.mjs");
115
+ const tickets = [...new Set(implementerClaims(ledger, pr).map((c) => c.ticket))];
116
+ return result(isTicketless(closing, tickets) ? "ticketless" : "ticketed", { closing, tickets });
117
+ }
118
+
119
+ // A path stat cannot read at all (EACCES on a parent) is a usage refusal like a
120
+ // missing one: uncaught, it would exit 1, the not-Ticketless code, about a PR
121
+ // nobody looked at.
122
+ function isDirectory(p) {
123
+ try {
124
+ return statSync(p, { throwIfNoEntry: false })?.isDirectory() === true;
125
+ } catch (e) {
126
+ return die(`cannot stat ${p}: ${e.code ?? e.message}`);
127
+ }
128
+ }
129
+
130
+ async function main() {
131
+ const { arg, numArg, sweep, stray } = defineFlags(die, {
132
+ flags: { pr: "value", repo: "value", ledger: "value" },
133
+ });
134
+ // The sweep runs before the required-flag check, so a misspelt flag is named
135
+ // as that and not buried under a missing-flag usage line.
136
+ sweep();
137
+ stray();
138
+ const pr = numArg("pr");
139
+ const repoArg = arg("repo");
140
+ const ledgerArg = arg("ledger");
141
+ if (pr === null) die(USAGE);
142
+ if (repoArg !== null && !isDirectory(resolve(repoArg))) die(`--repo is not a directory: ${repoArg}`);
143
+
144
+ const v = await ticketlessVerdict({
145
+ pr,
146
+ repo: repoArg === null ? null : resolve(repoArg),
147
+ ledgerFile: ledgerArg === null ? null : resolve(ledgerArg),
148
+ });
149
+ // Exit 0 is the only code that skips the acceptance mutation, so a verdict
150
+ // that never reached stdout must not leave it set: a lost write is the
151
+ // could-not-look exit.
152
+ if (!writeAll(1, `${JSON.stringify(v)}\n`)) die("the verdict could not be written to stdout");
153
+ process.exitCode = v.exit;
154
+ }
155
+
156
+ if (isCLI(import.meta.url)) await main();
@@ -74,9 +74,6 @@ Nothing in this phase, or in any later one, asks the maintainer which tickets to
74
74
  row is written. A `report #<n> — <why>` line is the maintainer's and
75
75
  nothing else, and a `carried` line is a live token to reconcile first.
76
76
  A closed-PR `report` takes `replace`/`release #<n>`.
77
- - `NEED review PR#<pr> (closes no issue)` — an open PR a prior run left
78
- that no row can queue. Advice, never an exit status: hand-dispatch its
79
- review exactly as ticket work, or leave it.
80
77
 
81
78
  A `drift` or `unanswered` ruleset step is advice too: surface the diff and
82
79
  go on. See references/phase-0.md.
@@ -558,7 +555,7 @@ Dispatch a finisher only when every test here passes at once — the review retu
558
555
  whole route to a finisher**: a `no-op` report satisfies the gate above by
559
556
  itself, so nothing further is owed and no further event is coming.
560
557
  - **The PR's closing references match its ruling and exclude its own suggestion-band record** → `ledger.mjs dispatch` refuses the finisher otherwise, naming the PR and the ticket: repair the body with `gh pr edit <M> --body-file <file>`, then dispatch again.
561
- - **The PR carries exactly one release label, or its repo defines none** → `ledger.mjs dispatch` refuses the finisher otherwise, naming `patch` as the repair only when the PR closes no ticket and no settled `impl-<N>=PR#<M>` token names it. Fix the labels, then dispatch again. In full: references/finisher.md.
558
+ - **The PR carries exactly one release label, or its repo defines none** → `ledger.mjs dispatch` refuses the finisher otherwise, except a Ticketless PR with none, which `finisher-label.mjs` labels `patch`. Fix them, then dispatch again. In full: references/finisher.md.
562
559
  - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → the CI edge never
563
560
  fires: dispatch the finisher off the reviewer's final verdict the moment it
564
561
  lands, never while you still owe it a reply. Its gate is then the
@@ -755,6 +752,7 @@ decides the rest — two resolve automatically, every other one escalates:
755
752
  | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
756
753
  | `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
757
754
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
755
+ | `human` | **Escalate** — no retry. A Ticketless PR whose diff is not inert: the maintainer adds `ready-to-merge` at the pinned head, which the merge bot merges off the finisher's `ready-to-merge-head:` comment; a moved head is merged by hand. |
758
756
 
759
757
  ### Resolving a finisher that died
760
758
 
@@ -127,7 +127,7 @@ discarded by the next `git checkout` with nothing to show it ever ran.
127
127
  **Commit the metrics files and open a PR — at end of run.** The branch name is
128
128
  the repository's choice. Make the commit on a branch in the main checkout,
129
129
  switch back to `main` before the next tick, and never `--record` while on that
130
- branch; the round trip reads clean. A PR still open when the run ends is one phase 0's
130
+ branch; the round trip reads clean. An Owned PR still open when the run ends is one phase 0's
131
131
  fold-in queues for review next run, however it is named, so the files reach
132
132
  `main` through the same review as ticket work rather than being lost. Stranding
133
133
  a data row loses it: `member-outcomes.tsv` is regenerated from harness
@@ -118,7 +118,7 @@ and will act on it. Relay everything — reversals too — then dispatch.
118
118
  is never held once the first passed; a PR no such token names is not gated.
119
119
  No flag skips it: a PR `append` refuses is fixed on the ledger, as at close-out.
120
120
  - **The PR's closing references match its ruling and exclude its own suggestion-band record** → `ledger.mjs dispatch` reads the PR's `closingIssuesReferences` from `gh pr view <M>` before it dispatches any finisher, counting only those in the PR's own repository: a reference into another repository closes none of this repository's tickets, whatever its number. When the ruled row says `closed_own_ticket=yes`, each ticket a settled `impl-<N>=PR#<M>` token names must be closed by the body (`Closes #<N>`); when it says `no`, none may be, and no reference may be the PR's own suggestion-band record. A blank verdict is refused until it is set. A refusal names the PR and the ticket. The controller repairs the body itself with `gh pr edit <M> --body-file <file>`, then dispatches the finisher again. A `gh` read that fails refuses the dispatch and writes nothing.
121
- - **The PR carries exactly one release label** → `ledger.mjs dispatch` reads the PR's labels from `gh pr view <M>` before it dispatches any finisher, and refuses unless exactly one of `patch`, `minor` and `major` is among them — the count `finisher-label.mjs` makes before it labels. A repository whose label list defines none of the three is not gated. A PR with none, which closes no ticket and no settled `impl-<N>=PR#<M>` token names, is refused naming the repair, `gh pr edit <M> --add-label patch`; any other PR with none is refused naming the tickets it closes, and one with several naming the labels found — the bump, or which label stays, is not picked for the controller. The controller adds or removes the label itself, then dispatches the finisher again. A `gh` read that fails or answers malformed refuses the dispatch, saying the labels could not be read, and writes nothing.
121
+ - **The PR carries exactly one release label** → `ledger.mjs dispatch` reads the PR's labels from `gh pr view <M>` before it dispatches any finisher, and refuses unless exactly one of `patch`, `minor` and `major` is among them — the count `finisher-label.mjs` makes before it labels. A repository whose label list defines none of the three is not gated. A Ticketless PR with none is not refused: `finisher-label.mjs` adds `patch` to it before its count. Any other PR with none is refused naming the tickets it closes, and any PR with several naming the labels found — the bump, or which label stays, is not picked for the controller. The controller adds or removes the label itself, then dispatches the finisher again. A `gh` read that fails or answers malformed refuses the dispatch, saying the labels could not be read, and writes nothing.
122
122
 
123
123
  Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
124
124
  reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
@@ -230,6 +230,12 @@ change or other non-regular entry is a code change whatever its name, so it is
230
230
  not prose either. The verdict is read at the dispatch pin: the worktree's own
231
231
  head is not part of it, and duty 1 audits that head separately.
232
232
 
233
+ ## A Ticketless PR has no mutation and no ruling
234
+
235
+ **A Ticketless PR skips the acceptance mutation on `ticketless.mjs`'s exit 0 alone.** Run `~/.fleet/bin/fleet-run ticketless.mjs --pr <M>`. It reads whether the PR closes an issue in its own repository and whether a settled `impl-<N>=PR#<M>` token names it; with neither, no ticket supplies a mutation to re-run, so exit 0 skips it whatever the diff, and the rest of duty 2 runs. Exit 1 and exit 2 (could not look) run duty 2 as for a ticket PR. Where a kill's evidence line would go, the report says that no mutation ran because the PR is ticketless.
236
+
237
+ **Duty 3 holds a Ticketless PR whose diff is not inert.** `finisher-label.mjs` adds `patch` to a Ticketless PR that carries no release label, then runs the Inert diff verdict in-process at your pin. A diff that is not inert, or a verdict that could not look, gets the `ready-to-merge-head:` record and no `ready-to-merge`, and the script exits 5: halt with cause `human`. No ticket gives that PR a ruling or a mutation, so the maintainer's `ready-to-merge` is the merge. The merge bot merges it off the record at the pinned head, and a head that moved after the record is merged by hand.
238
+
233
239
  ## Whatever you verify by running, run in a tree nobody else owns
234
240
 
235
241
  **Whatever you verify by RUNNING, run in a tree nobody else owns.**
@@ -383,24 +383,29 @@ entrypoint or mutation that hangs until the proof's own bound refuses it as
383
383
  timed out. It is never a loop: no third derivation, and never a cache
384
384
  written by hand.
385
385
 
386
- ## Fold in every PR a prior run left open
387
-
388
- **Fold in every PR a prior run left open, before shortlisting.** However it
389
- is named and whatever it carries — ticket work whose review was deferred, or
390
- that run's own metrics — it is reviewable work no member otherwise picks up,
391
- because the Shortlist holds ISSUES and nothing looks at inherited PRs. Queue
392
- each for review exactly as ticket work: same review workflow, same
393
- fix-applier, same finisher. **Skip a PR a row rotate carried already
394
- holds** — its `#<pr>` key, or the PR of its `impl-<N>=PR#<pr>` token: that
395
- row already queues it, and a `ledger.mjs row` write replaces the whole
396
- line, wiping the live tokens carried on it. Measured 2026-09-03 — a prior
397
- run's ticket PR arrived this way and its review found a defect its own PR
398
- body called
399
- unreviewed, and a metrics PR's review then caught two metrics rows the
400
- controller had missed in its own close-out, so no PR is exempt from being
401
- wrong. Reviewing them next run is also what stops one pinning
402
- `fleet-tick`'s backlog forever: unreviewable AND uncounted is the state
403
- that strands it.
386
+ ## Fold in every Owned PR a prior run left open
387
+
388
+ **Fold in every Owned PR a prior run left open, before shortlisting.** An Owned
389
+ PR is an open PR, not a draft, whose author is the login `gh api user` answers
390
+ to: every member acts through the maintainer's `gh` credentials, so every PR
391
+ the fleet opens carries it. A PR that is not owned — another author's, a
392
+ bot's, a fork's, a draft — gets no row and no advice, whatever it closes. A
393
+ login read that fails fails the step. However an Owned PR is named and
394
+ whatever it carries — ticket work whose review was deferred, that run's own
395
+ metrics, a Ticketless PR that closes no issue — it is reviewable work no
396
+ member otherwise picks up, because the Shortlist holds ISSUES and nothing
397
+ looks at inherited PRs. Queue each for review exactly as ticket work: same
398
+ review workflow, same fix-applier, same finisher. The fold-in writes it a
399
+ `#<pr>` row, `PR#<pr> · inherited (closes #…)`, or `PR#<pr> · inherited
400
+ (closes no issue)` for a Ticketless PR, and the tick queues its review off
401
+ that row. **Skip a PR a row rotate carried already holds** — its `#<pr>` key,
402
+ or the PR of its `impl-<N>=PR#<pr>` token: that row already queues it, and a
403
+ `ledger.mjs row` write replaces the whole line, wiping the live tokens
404
+ carried on it. Measured 2026-09-03 — a prior run's ticket PR arrived this way
405
+ and its review found a defect its own PR body called unreviewed, and a
406
+ metrics PR's review then caught two metrics rows the controller had missed in
407
+ its own close-out, so no PR is exempt from being wrong. Reviewing them next
408
+ run is also what stops one pinning `fleet-tick`'s backlog forever.
404
409
 
405
410
  ## Resume the claims a dead run left without a PR
406
411
 
@@ -182,10 +182,9 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
182
182
  print; a `baseline` step not `ok` is one of the steps it names.
183
183
  `CONFLICT` rows and the stall report still print. Run the
184
184
  `phase0.mjs` command the line names and act on what it prints: a re-run
185
- resumes at the step that stopped. A `drift` or `unanswered` step and a
186
- `fold-in` `NEED` are advice, named after `; advice:` on the line, or alone
187
- on a `PHASE0-ADVICE …` line when nothing is incomplete; advice holds
188
- nothing.
185
+ resumes at the step that stopped. A `drift` or `unanswered` step is advice,
186
+ named after `; advice:` on the line, or alone on a `PHASE0-ADVICE …` line
187
+ when nothing is incomplete; advice holds nothing.
189
188
  - `CHECK-LIVENESS <member> (<family> > p99 <t>m)`, printed above the rows — a
190
189
  live ledger token has stayed live past its family's p99 run time, counted
191
190
  from the first tick that saw it (`> 2×p99 …` from the second multiple of the