@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 +1 -1
- package/scripts/finisher-audit.mjs +295 -0
- package/skills/run-team/SKILL.md +60 -97
package/package.json
CHANGED
|
@@ -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");
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -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**
|
|
3213
|
-
|
|
3214
|
-
|
|
3215
|
-
|
|
3216
|
-
|
|
3217
|
-
path
|
|
3218
|
-
|
|
3219
|
-
|
|
3220
|
-
|
|
3221
|
-
|
|
3222
|
-
|
|
3223
|
-
|
|
3224
|
-
`
|
|
3225
|
-
the
|
|
3226
|
-
|
|
3227
|
-
|
|
3228
|
-
|
|
3229
|
-
|
|
3230
|
-
|
|
3231
|
-
|
|
3232
|
-
|
|
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
|
|
3241
|
-
verbatim** —
|
|
3242
|
-
|
|
3243
|
-
and the fix-applier — because duty
|
|
3244
|
-
|
|
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
|
|
3357
|
-
|
|
3358
|
-
|
|
3359
|
-
|
|
3360
|
-
|
|
3361
|
-
|
|
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 — `
|
|
3365
|
-
both under `plugin/scripts/` — and the
|
|
3366
|
-
returned. The rule is stated once, at the
|
|
3367
|
-
is dispatched to read, so it reaches one
|
|
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
|
|
3499
|
-
finisher this verbatim, so it
|
|
3500
|
-
|
|
3501
|
-
|
|
3502
|
-
>
|
|
3503
|
-
>
|
|
3504
|
-
>
|
|
3505
|
-
>
|
|
3506
|
-
>
|
|
3507
|
-
>
|
|
3508
|
-
>
|
|
3509
|
-
>
|
|
3510
|
-
>
|
|
3511
|
-
>
|
|
3512
|
-
>
|
|
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
|
-
>
|
|
3516
|
-
>
|
|
3517
|
-
>
|
|
3518
|
-
>
|
|
3519
|
-
>
|
|
3520
|
-
>
|
|
3521
|
-
>
|
|
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,
|