@feigi/fleet-ctl 3.52.0 → 3.53.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.52.0",
3
+ "version": "3.53.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,295 @@
1
+ #!/usr/bin/env node
2
+ // The finisher's worktree audit (duty 1) as one command, so the row lookup, the
3
+ // dirty check, the head-equality check and the reflog cause derivation cannot be
4
+ // run, or skipped, one at a time:
5
+ //
6
+ // finisher-audit.mjs --worktree <abs> --pin <sha> [--sample-seconds <n>] [--repo <dir>]
7
+ //
8
+ // `--worktree` is the absolute path the finisher was dispatched with, spelled
9
+ // however it was reached: it is matched by its realpath. `--pin` is the full
10
+ // 40-hex head the finisher was dispatched against. `--repo` is the directory
11
+ // `worktree-audit.sh` runs in (it audits the worktrees of whichever repository
12
+ // it stands in); the cwd when omitted. `--sample-seconds` is the gap between the
13
+ // two `git diff --stat` samples of a dirty tree, 60 when omitted. Reached
14
+ // through the Resolver: `~/.fleet/bin/fleet-run finisher-audit.mjs ...`.
15
+ //
16
+ // Stdout is always one JSON line, the verdict:
17
+ //
18
+ // {worktree, realpath, pin, head, cause, evidence}
19
+ //
20
+ // worktree the path as given
21
+ // realpath its physical path, the form the audit's row names it by
22
+ // pin the pin, lowercased
23
+ // head `git -C <worktree> rev-parse HEAD`, null when it was never read
24
+ // cause null, or the word the ledger's `halted:<cause>` takes: live-editor,
25
+ // rebase, past-pin, unreadable, missing, absent or other
26
+ // evidence one entry per step that ran, each holding what that step read
27
+ //
28
+ // Exit vocabulary:
29
+ //
30
+ // 0 the worktree is clean at the pin: `cause` is null and nothing else is
31
+ // 1 a halt cause: `cause` names it and `evidence` holds what it was derived from
32
+ // 2 it could not look - the invocation or a read failed, `evidence.error`
33
+ // says which and the same line is on stderr. `cause` is null in that
34
+ // verdict and means nothing: only exit 0 is clean.
35
+ //
36
+ // Derivation, in this order, each step's output in `evidence`. A step runs only
37
+ // if every earlier one answered "no cause".
38
+ //
39
+ // 1 The row. `worktree-audit.sh` takes no argument and audits every worktree,
40
+ // so the row is found by `realpath(--worktree)` against the row's `worktree`,
41
+ // which is the physical path `git worktree list` reports - never by the path
42
+ // as written, so a spelling reached through a symlink (macOS's `/tmp` and
43
+ // `/var/folders` are symlinks too) still finds a healthy worktree's row.
44
+ // - no row at all: `absent`.
45
+ // - `readable:false` with null counts: `unreadable`, the script's own
46
+ // `UNREADABLE: <wt> (<cause>)` stderr line quoted in `evidence.audit`.
47
+ // - `readable:false` with zero counts: `missing`, its `MISSING on disk:
48
+ // <wt>` line quoted the same way.
49
+ // `git status` is no substitute for the row on the first two: in a worktree
50
+ // whose `.git` linkage is missing it answers for the enclosing repository, at
51
+ // rc 0.
52
+ //
53
+ // 2 Dirty. The row's `dirty` count, cross-checked with `git -C <wt> status
54
+ // --porcelain -unormal` - the explicit mode, never bare `--porcelain`, or
55
+ // `status.showUntrackedFiles = no` reads a dirty tree as clean. Either one
56
+ // reporting dirt is dirt. Then `git diff --stat` is sampled twice,
57
+ // `--sample-seconds` apart, and the cause is `live-editor` with both samples
58
+ // in the evidence: a diffstat that grew between them is someone still writing.
59
+ // Every dirty tree halts, grown or not - a finisher that verifies the dirt is
60
+ // harmless and labels anyway has replaced the rule with its purpose.
61
+ //
62
+ // 3 Head-equality. `git -C <wt> rev-parse HEAD` equal to the pin on a clean tree
63
+ // settles it: `cause` null, exit 0. It is against the dispatch pin, never
64
+ // against the PR's `headRefOid`: a member that kept working and pushed after
65
+ // the pin matches the branch tip on a clean tree, so a `headRefOid` comparison
66
+ // would report "settled" over commits no reviewer read. And no reflog entry
67
+ // is read at all on this path - a rebase sitting at or behind the pin is that
68
+ // head's provenance (the implementer's own pre-push replay), not divergence
69
+ // from it.
70
+ //
71
+ // 4 Only when the head differs from the pin: `git -C <wt> reflog -n 20`, and the
72
+ // newest entry is the move that put HEAD where it is.
73
+ // - a `reset` or `rebase` entry: `rebase`. The branch replayed onto a new
74
+ // base - its own commits on a new parent, content-identical only on a
75
+ // conflict-free replay. Evidence: the reflog line and the output of
76
+ // `git cherry <pin> HEAD origin/main`, run in the worktree.
77
+ // - a plain `commit` entry: `past-pin`. A member kept working after the
78
+ // dispatch. Evidence: `git log -1 --format='%h %s'` and whether that
79
+ // commit is pushed, unpushed or unknown, read from `git ls-remote origin
80
+ // refs/heads/<branch>` - the branch being the row's, and the full ref
81
+ // name so a branch named like the tail of another ref matches only
82
+ // itself. Only a successful read settles pushed against unpushed: the
83
+ // remote's value equal to HEAD is `pushed`, anything else from a read
84
+ // that succeeded is `unpushed`, the commit existing only in that
85
+ // worktree where no reviewer can reach it. A failed read - a non-zero
86
+ // exit, a timeout, a detached HEAD with no branch to ask about - is
87
+ // `unknown`, never `unpushed`, the same rule `release-ticket.sh`'s own
88
+ // `ls-remote` states. The remote is asked rather than the PR object,
89
+ // whose head lags a ref move.
90
+ // - anything else, an empty reflog included: `other`. Evidence: both status
91
+ // reads (the step-2 read and one after the reflog), the reflog line at
92
+ // the move, and both SHAs. A cause nobody has named yet is still a cause
93
+ // observed, and the report is what gets it named.
94
+ //
95
+ // Every cause halts, always - named or not. A rebase is not a fast-forward the
96
+ // finisher gets to accept, a commit past the pin is not one either, and a cause
97
+ // that could not be named is the least settled of the lot.
98
+ //
99
+ // A usage refusal (a missing, unknown or malformed flag) is a one-line refusal
100
+ // on stderr with no verdict, exit 2, as in every other script's `die()`.
101
+
102
+ import { spawnSync } from "node:child_process";
103
+ import { realpathSync, statSync } from "node:fs";
104
+ import { basename, dirname, join, resolve } from "node:path";
105
+ import { fileURLToPath } from "node:url";
106
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
107
+ import { gitEnv } from "./git-env.mjs";
108
+
109
+ const NAME = "finisher-audit";
110
+ const die = makeDie(NAME);
111
+ const { arg, numArg, sweep, stray } = defineFlags(die, {
112
+ flags: { worktree: "value", pin: "value", "sample-seconds": "value", repo: "value" },
113
+ });
114
+ const USAGE = "usage: finisher-audit.mjs --worktree <abs> --pin <sha> [--sample-seconds <n>] [--repo <dir>]";
115
+ // The sweep runs before the required-flag check so a misspelled flag is named
116
+ // as that, not buried under a missing-flag usage line.
117
+ sweep();
118
+ stray();
119
+
120
+ const AUDIT = join(dirname(fileURLToPath(import.meta.url)), "worktree-audit.sh");
121
+ const DEFAULT_SAMPLE_SECONDS = 60;
122
+ // A read of the remote that has not answered by now is an unknown answer, not a
123
+ // reason to hold the finisher's halt report.
124
+ const LS_REMOTE_TIMEOUT_MS = 30_000;
125
+ // One audit row per worktree, each carrying its dirty files: far past
126
+ // spawnSync's 1 MiB default on a repository with many dirty worktrees.
127
+ const AUDIT_BUFFER = 256 * 1024 * 1024;
128
+ const REFLOG_LIMIT = "20";
129
+ // Atomics.wait never blocks on a value nothing writes, so it is a plain sleep.
130
+ const IDLE = new Int32Array(new SharedArrayBuffer(4));
131
+
132
+ const worktree = arg("worktree");
133
+ const pinArg = arg("pin");
134
+ const sampleSeconds = numArg("sample-seconds");
135
+ const repoArg = arg("repo");
136
+ if (worktree === null || pinArg === null) die(USAGE);
137
+ if (!worktree.startsWith("/")) die(`--worktree needs an absolute path, got ${worktree}`);
138
+ // Full SHAs only, lowercased: a shorter pin could not be compared to HEAD, and
139
+ // case is folded rather than refused, as finisher-label.mjs does.
140
+ const pin = pinArg.toLowerCase();
141
+ if (!/^[0-9a-f]{40}$/.test(pin)) die(`--pin needs a full 40-character commit SHA, got ${pinArg}`);
142
+ // A missing directory makes spawn report ENOENT for the binary itself, which
143
+ // would blame git or sh for a bad --repo. A stat that throws (EACCES on an
144
+ // ancestor) is the same refusal, not a crash with no verdict.
145
+ if (repoArg !== null) {
146
+ let isDir = false;
147
+ try {
148
+ isDir = statSync(repoArg, { throwIfNoEntry: false })?.isDirectory() === true;
149
+ } catch (e) {
150
+ die(`--repo cannot be read: ${repoArg} (${e.code ?? e.message})`);
151
+ }
152
+ if (!isDir) die(`--repo is not a directory: ${repoArg}`);
153
+ }
154
+ const repo = repoArg === null ? process.cwd() : resolve(repoArg);
155
+
156
+ // The physical form of a path, for a path that may no longer exist: the deepest
157
+ // ancestor that resolves is made physical and the rest is appended as written,
158
+ // which is how `git worktree list` names a worktree whose directory is gone
159
+ // under a symlinked ancestor.
160
+ function physical(path) {
161
+ const tail = [];
162
+ let here = resolve(path);
163
+ for (;;) {
164
+ try {
165
+ return join(realpathSync(here), ...tail.reverse());
166
+ } catch {
167
+ const up = dirname(here);
168
+ if (up === here) return resolve(path);
169
+ tail.push(basename(here));
170
+ here = up;
171
+ }
172
+ }
173
+ }
174
+
175
+ const realpath = physical(worktree);
176
+ const GIT_ENV = gitEnv({ GIT_TERMINAL_PROMPT: "0" });
177
+ const verdict = { worktree, realpath, pin, head: null, cause: null, evidence: {} };
178
+ const evidence = verdict.evidence;
179
+
180
+ function finish(exit, cause = null) {
181
+ verdict.cause = cause;
182
+ writeAll(1, `${JSON.stringify(verdict)}\n`);
183
+ process.exit(exit);
184
+ }
185
+
186
+ // The finisher could not look: the verdict carries what failed and the exit is
187
+ // 2, so a read that failed is never taken for a read that found nothing.
188
+ function fail(error) {
189
+ evidence.error = error;
190
+ writeAll(2, `\n${NAME}: ${error}\n`);
191
+ finish(2);
192
+ }
193
+
194
+ const halt = (cause) => finish(1, cause);
195
+
196
+ function run(cmd, args, options = {}) {
197
+ return spawnSync(cmd, args, { encoding: "utf8", env: GIT_ENV, maxBuffer: AUDIT_BUFFER, ...options });
198
+ }
199
+
200
+ // A git call inside the worktree. A call that could not run, was killed or
201
+ // exited non-zero stops the audit at exit 2 unless the caller asked to read the
202
+ // failure itself (`soft`).
203
+ function git(step, args, { soft = false, timeout } = {}) {
204
+ const r = run("git", ["-C", realpath, ...args], timeout === undefined ? {} : { timeout });
205
+ if (r.error || r.signal || r.status !== 0) {
206
+ if (soft) return { ok: false, out: "", error: (r.error?.message ?? r.stderr ?? "").trim() || `exit ${r.status ?? r.signal}` };
207
+ const why = r.error?.message ?? (r.signal ? `killed by ${r.signal}` : (r.stderr ?? "").trim() || `exit ${r.status}`);
208
+ fail(`${step}: git ${args.join(" ")} failed: ${why}`);
209
+ }
210
+ return { ok: true, out: r.stdout, error: null };
211
+ }
212
+
213
+ // --- 1: the row --------------------------------------------------------------
214
+ const audit = run("sh", [AUDIT], { cwd: repo });
215
+ if (audit.error || audit.signal || audit.status !== 0) {
216
+ fail(`worktree-audit.sh failed: ${audit.error?.message ?? (audit.signal ? `killed by ${audit.signal}` : (audit.stderr ?? "").trim() || `exit ${audit.status}`)}`);
217
+ }
218
+ let rows;
219
+ try {
220
+ rows = JSON.parse(audit.stdout);
221
+ } catch {
222
+ fail(`worktree-audit.sh printed no JSON: ${audit.stdout.slice(0, 200)}`);
223
+ }
224
+ if (!Array.isArray(rows)) fail(`worktree-audit.sh printed an unexpected shape: ${audit.stdout.slice(0, 200)}`);
225
+
226
+ const row = rows.find((r) => r !== null && typeof r === "object" && typeof r.worktree === "string" && physical(r.worktree) === realpath);
227
+ // The audit's own stderr line for a row, quoted where it printed one.
228
+ const quote = (prefix) => audit.stderr.split("\n").find((l) => l.trimStart().startsWith(prefix)) ?? null;
229
+ if (!row) {
230
+ evidence.audit = { row: null, rows: rows.map((r) => r?.worktree ?? null) };
231
+ halt("absent");
232
+ }
233
+ if (row.readable !== true) {
234
+ const unreadable = row.ahead === null || row.dirty === null;
235
+ evidence.audit = { row, stderr: quote(unreadable ? `UNREADABLE: ${row.worktree} (` : `MISSING on disk: ${row.worktree}`)?.trim() ?? null };
236
+ halt(unreadable ? "unreadable" : "missing");
237
+ }
238
+ evidence.audit = { row };
239
+
240
+ // --- 2: dirty ----------------------------------------------------------------
241
+ const status = () => git("status", ["status", "--porcelain", "-unormal"]).out;
242
+ const statusFirst = status();
243
+ evidence.status = [statusFirst];
244
+ if (row.dirty > 0 || statusFirst.trim() !== "") {
245
+ const stat = () => git("sample", ["diff", "--stat"]).out;
246
+ const first = stat();
247
+ Atomics.wait(IDLE, 0, 0, (sampleSeconds ?? DEFAULT_SAMPLE_SECONDS) * 1000);
248
+ const second = stat();
249
+ evidence.samples = [first, second];
250
+ halt("live-editor");
251
+ }
252
+
253
+ // --- 3: head-equality ----------------------------------------------------------
254
+ const head = git("head", ["rev-parse", "HEAD"]).out.trim();
255
+ verdict.head = head;
256
+ if (head === pin) finish(0);
257
+
258
+ // --- 4: the reflog -------------------------------------------------------------
259
+ // `--no-decorate --no-color`: a user's `log.decorate` or `color.ui` config would
260
+ // otherwise put `(HEAD -> branch)` or an escape ahead of the subject, and the
261
+ // subject match below would read every move as `other`.
262
+ const reflog = git("reflog", ["reflog", "--no-decorate", "--no-color", "-n", REFLOG_LIMIT]).out;
263
+ const move = reflog.split("\n").find((l) => l.trim() !== "") ?? null;
264
+ // `<abbrev> HEAD@{0}: <subject>`: the subject is what names the operation.
265
+ const subject = move === null ? "" : (/^\S+ [^\s:]*@\{\d+\}: (.*)$/.exec(move)?.[1] ?? "");
266
+ evidence.reflog = move;
267
+
268
+ if (/^(reset|rebase)\b/.test(subject)) {
269
+ const cherry = git("cherry", ["cherry", pin, "HEAD", "origin/main"], { soft: true });
270
+ evidence.cherry = cherry.ok ? cherry.out : { error: cherry.error };
271
+ halt("rebase");
272
+ }
273
+
274
+ if (/^commit\b/.test(subject)) {
275
+ evidence.commit = git("log", ["log", "-1", "--format=%h %s"]).out.trim();
276
+ const branch = row.branch === "DETACHED" ? null : row.branch;
277
+ if (typeof branch !== "string" || branch === "") {
278
+ evidence.remote = { state: "unknown", error: "detached HEAD: no branch to ask the remote about" };
279
+ } else {
280
+ const ref = `refs/heads/${branch}`;
281
+ const r = git("ls-remote", ["ls-remote", "origin", ref], { soft: true, timeout: LS_REMOTE_TIMEOUT_MS });
282
+ if (!r.ok) {
283
+ evidence.remote = { state: "unknown", ref, error: r.error };
284
+ } else {
285
+ const line = r.out.split("\n").find((l) => l.split("\t")[1] === ref);
286
+ const sha = line === undefined ? null : line.split("\t")[0];
287
+ evidence.remote = { state: sha === head ? "pushed" : "unpushed", ref, sha };
288
+ }
289
+ }
290
+ halt("past-pin");
291
+ }
292
+
293
+ evidence.status.push(status());
294
+ evidence.shas = { pin, head };
295
+ halt("other");
@@ -3209,40 +3209,34 @@ correctly halted. Note what that costs to detect: two reads of the same worktree
3209
3209
  a minute apart showed *different* mutants, so a member's report and any single
3210
3210
  `git status` are each valid only at their instant. Its duties, in this order:
3211
3211
 
3212
- 1. **Audit the worktree** — run `worktree-audit.sh` (it takes no argument; it
3213
- audits every worktree in one pass, so find this worktree's row in its
3214
- output). Match the row by the resolved form of the worktree path you were
3215
- dispatched with — `realpath <abs-path>`, or `cd <abs-path> && pwd -P` —
3216
- never by that path as written: the row's `worktree` field is the physical
3217
- path `git worktree list` reports, so a spelling reached through a symlink
3218
- (macOS's `/tmp` and `/var/folders` are symlinks too) matches no row on a
3219
- healthy worktree. Two checks, each with the instrument that can answer it.
3220
- **Dirty:** the row's `dirty` field, or `git status --porcelain -unormal`
3221
- inside the worktree itself — the explicit mode, never bare `--porcelain`, or
3222
- `status.showUntrackedFiles = no` reads a dirty worktree as clean. The
3223
- row is the better read: in a worktree whose `.git` linkage is missing,
3224
- `git status` answers for the enclosing repo at rc 0, where the audit reports
3225
- the worktree unreadable. **Diverged:** the worktree's `HEAD` against your
3226
- dispatch pin — the cause block's head-equality check below. Neither
3227
- instrument above answers it: `git status --porcelain` reports no commits,
3228
- and the row's `ahead` is counted against `origin/main`, which a healthy
3229
- worktree on an open, unmerged PR is ahead of too, so it cannot answer this.
3230
- Three row shapes halt too, each named in the report with the script's
3231
- stderr line quoted where it prints one: `readable:false` with `null` counts
3232
- (`UNREADABLE: <wt> (<cause>)`) is *worktree unreadable*, `readable:false`
3233
- with zero counts (`MISSING on disk: <wt>`) is *worktree missing*, and no
3234
- row for this worktree at all is *worktree absent*. `git status` is no
3235
- substitute for the audit here — it answers the dirty check only, and a
3236
- finisher that cannot see the tree it labels cannot vouch for it. Dirty,
3237
- diverged, unreadable, missing or absent halts the finisher *here*, before
3238
- the label: it reports what it found and labels nothing. A finisher that
3212
+ 1. **Audit the worktree** by running one script, `finisher-audit.mjs` — the row
3213
+ lookup, the dirty check, the head-equality check and the cause derivation
3214
+ are one command, because each of them alone reads like the whole duty. Its
3215
+ exit code is the verdict of this duty:
3216
+ `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`,
3217
+ the path the one you were dispatched with, however it was spelled, and the
3218
+ pin the full SHA. It runs `worktree-audit.sh` itself and finds this
3219
+ worktree's row by its `realpath`, so a spelling reached through a symlink
3220
+ still finds a healthy worktree's row; it reads dirty from the row and from
3221
+ `git status --porcelain -unormal`; it compares the worktree's `HEAD` to your
3222
+ dispatch pin; and when the head differs from the pin it derives the cause
3223
+ from the reflog. It prints one JSON verdict,
3224
+ `{worktree, realpath, pin, head, cause, evidence}`. Exit 0, `cause` null, is
3225
+ the only result that means the worktree is clean at your pin. Exit 1 means
3226
+ `cause` names why not — `live-editor`, `rebase`, `past-pin`, `unreadable`,
3227
+ `missing`, `absent` or `other` — and exit 2 means the script could not
3228
+ look. Every non-zero exit halts the finisher *here*, before the label: it
3229
+ reports the verdict as printed and labels nothing, and an exit 2 is cause
3230
+ `other` with the line the script printed on stderr as its evidence. A
3231
+ finisher that cannot see the tree it labels cannot vouch for it, so none of
3232
+ the script's steps is run by hand to get past a halt. A finisher that
3239
3233
  verifies the dirt is harmless and labels anyway has substituted the rule's
3240
- purpose for the rule, and you find out at merge time. **Give it the cause block below,
3241
- verbatim** — a bare SHA mismatch names no cause, and the halt report needs
3242
- one. **Give it `<testCmd>` too** — the same string you passed the workflow
3243
- and the fix-applier — because duty 2's mutation gate runs it and nothing
3244
- else hands the finisher one; substituted with nothing it leaves that gate
3245
- no command at all.
3234
+ purpose for the rule, and you find out at merge time. **Give it the cause
3235
+ block below, verbatim** — it holds the script call and what each exit
3236
+ means, and a bare SHA mismatch names no cause. **Give it `<testCmd>` too** —
3237
+ the same string you passed the workflow and the fix-applier — because duty
3238
+ 2's mutation gate runs it and nothing else hands the finisher one;
3239
+ substituted with nothing it leaves that gate no command at all.
3246
3240
  2. **Confirm every deferral — and every claimed APPLY — has a home that outlives
3247
3241
  the merge.** The test is a durable home, not a tracker number: a tracker
3248
3242
  issue and a committed in-tree comment both qualify, and for a finding whose
@@ -3353,18 +3347,19 @@ a minute apart showed *different* mutants, so a member's report and any single
3353
3347
  `filed` failed twice — and anything
3354
3348
  it halted on — cause and evidence, below, never a bare "head moved". The
3355
3349
  cause is one word of the ledger's `halted:<cause>` vocabulary:
3356
- `live-editor`, `rebase` or `past-pin` from the cause block below,
3357
- `unreadable`, `missing` or `absent` from duty 1's row shapes, and `other`
3358
- for every other halt — the block's *anything else*, and a halt at duty 2,
3359
- duty 3, the instrument re-check or the CI gate. A `rebase` halt's report
3360
- carries the output of `git cherry <pin> HEAD origin/main`, run in the
3361
- worktree.
3350
+ `live-editor`, `rebase`, `past-pin`, `unreadable`, `missing` or `absent` as
3351
+ duty 1's verdict names it, and `other` for every other halt — that
3352
+ verdict's own `other`, and a halt at duty 2, duty 3, the instrument
3353
+ re-check or the CI gate. A duty 1 halt's report carries the verdict as
3354
+ printed, the JSON line, so a `rebase` halt's report carries the output of
3355
+ `git cherry <pin> HEAD origin/main` that its `evidence` holds.
3362
3356
 
3363
3357
  **Give the finisher the instrument re-check verbatim too.** Duty 1 and duty 2
3364
- each run a script the digest covers — `worktree-audit.sh` and `ledger.mjs`,
3365
- both under `plugin/scripts/` — and the label at duty 3 rests on what they
3366
- returned. The rule is stated once, at the top of this file, which no finisher
3367
- is dispatched to read, so it reaches one through this block or not at all:
3358
+ each run a script the digest covers — `finisher-audit.mjs` (which runs
3359
+ `worktree-audit.sh`) and `ledger.mjs`, both under `plugin/scripts/` — and the
3360
+ label at duty 3 rests on what they returned. The rule is stated once, at the
3361
+ top of this file, which no finisher is dispatched to read, so it reaches one
3362
+ through this block or not at all:
3368
3363
 
3369
3364
  > **Re-check the instrument set before you act on what duty 1 or duty 2 read,
3370
3365
  > and again before you add the label.**
@@ -3495,61 +3490,29 @@ guard — but its refusal costs a pass and leaves the label lying, which is your
3495
3490
  to clear either way, the same way: `label-off=` first, then the removal.
3496
3491
 
3497
3492
  A halt at step 1 reads identical from a bare SHA mismatch whatever caused it,
3498
- and the causes below are the ones seen so far, not a closed list. Give the
3499
- finisher this verbatim, so it derives the cause itself instead of asking anyone:
3500
-
3501
- > Worktree differs from your pin, or from what you last read. **Check
3502
- > head-equality first: `worktree HEAD == the SHA you were dispatched against` on
3503
- > a clean tree settles it.** Against your dispatch pin, never against
3504
- > `PR headRefOid`: a member that kept working and pushed after the pin matches
3505
- > the branch tip on a clean tree, so a headRefOid comparison reports "settled"
3506
- > over commits no reviewer read — the exact divergence this halt exists to
3507
- > catch. `headRefOid` is a second, separate read (pushed vs unpushed), never the
3508
- > equality the halt turns on. A rebase entry sitting at or behind the pin is
3509
- > that head's provenance — the implementer's own pre-push replay — not
3510
- > divergence from it, and needs no adjudication at all. Three finishers in one
3511
- > run adjudicated a reflog this one check had already answered. Only when the
3512
- > head differs from your pin, work out what happened. Each cause below is cheap
3513
- > and self-checkable, and `anything else` is a cause too, not a gap:
3493
+ and the causes `finisher-audit.mjs` names are the ones seen so far, not a
3494
+ closed list. Give the finisher this verbatim, so it gets the cause from one
3495
+ script instead of asking anyone:
3496
+
3497
+ > **Duty 1 is one script, and its exit code is your verdict.**
3498
+ > `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
3499
+ > (the path you were dispatched with, and the full SHA). It finds your
3500
+ > worktree's row, reads whether the tree is dirty, compares the worktree's
3501
+ > `HEAD` to your pin, and when the head differs derives the cause from the
3502
+ > reflog. Exit 0, with `cause` null, is the only code that means the worktree is
3503
+ > clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
3504
+ > `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
3505
+ > `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
3506
+ > a gap. Exit 2 means the script could not look: you are halted with cause
3507
+ > `other`, with the line it printed on stderr as the evidence.
3514
3508
  >
3515
- > - **Live editor.** `git status --porcelain -unormal` is dirty. Sample
3516
- > `git diff --stat` twice, a minute apart — diffstat growing means someone
3517
- > is still writing. Halt, name `live-editor`, report both samples.
3518
- > - **Rebase.** `git status --porcelain -unormal` is clean, head still differs
3519
- > from your pin. `git reflog` in the worktree: a `reset`/rebase entry near
3520
- > the move, not a plain `commit`, means the branch replayed onto a new
3521
- > base — its own commits on a new parent, content-identical only on a
3522
- > conflict-free replay.
3523
- > Halt, name `rebase`, report the reflog line and the output of
3524
- > `git cherry <pin> HEAD origin/main`, run in the worktree.
3525
- > - **Work past the pin.** `git status --porcelain -unormal` is clean, head
3526
- > still differs from your pin, and `git reflog` in the worktree reads a plain
3527
- > `commit` at the move — no `reset`/rebase entry there, any of those sitting
3528
- > at or behind the pin as provenance. A member kept working and committed
3529
- > after you were dispatched. Measured 2026-08-28 on one PR, where the finisher
3530
- > matched neither cause above and halted on its own judgement.
3531
- > Halt, name `past-pin`, and report **the commit, and whether it
3532
- > is pushed, unpushed, or unknown**: `git log -1 --format='%h %s'` names it,
3533
- > and `git ls-remote origin <branch>` answers the rest — a non-zero exit or
3534
- > any other failed read is **unknown**, never folded into "unpushed": the
3535
- > same rule `release-ticket.sh`'s own `ls-remote` names ("a failure here is
3536
- > an unknown answer, never a 'no'") and `reaping.md`'s remote check shares
3537
- > ("its failure is an unknown answer, never a 'not pushed'"). Only a
3538
- > successful read settles pushed vs not: equal to that commit means pushed,
3539
- > and a fresh finisher can audit it; a successful read that comes back
3540
- > without it means the commit exists only in that worktree, where no
3541
- > reviewer can reach it. Ask the remote, not the PR object, whose head lags
3542
- > a ref move — the same field `run-merge-bot.md` refuses to poll, for that
3543
- > reason. The controller's next move differs between pushed, unpushed, and
3544
- > unknown, so a report naming only two of the three is not a report of this
3545
- > cause.
3546
- > - **Anything else.** Matching none of the above is not a licence to report
3547
- > the mismatch as unexplained — that report is the one this block exists to
3548
- > make unnecessary, and it is where labelling over a moved head starts
3549
- > looking reasonable. Halt, name `other`, and name what you did find: both
3550
- > `git status --porcelain -unormal` samples, the `git reflog` line at the
3551
- > move, and both SHAs. A cause nobody has named yet is still a cause you
3552
- > observed, and your report is what gets it named.
3509
+ > The pin is the SHA you were dispatched against, never `PR headRefOid`: a
3510
+ > member that kept working and pushed after the pin matches the branch tip on a
3511
+ > clean tree, so a headRefOid comparison reports "settled" over commits no
3512
+ > reviewer read — the exact divergence this halt exists to catch. You do not
3513
+ > run any of the script's steps by hand to get past a halt or to second-guess
3514
+ > it. Put the verdict, the JSON line it printed, in your report as printed: its
3515
+ > `evidence` is what the controller resolves the halt from.
3553
3516
  >
3554
3517
  > Every cause halts, always — named or not, you never verify the dirt is
3555
3518
  > harmless and label over it, a rebase is not a fast-forward you get to accept,