@feigi/fleet-ctl 3.102.7 → 3.104.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.
@@ -109,6 +109,16 @@ had correctly edited — the PR's whole point — and a finisher reading that
109
109
  literally halts a correct PR. It caught the error instead, and said so; do
110
110
  not rely on that.
111
111
 
112
+ **Run the Inert diff verdict before the acceptance mutation.** Run
113
+ `~/.fleet/bin/fleet-run finisher-scope.mjs --worktree <abs-path> --pin <your dispatch pin>`
114
+ (the path you were dispatched with, and the full SHA). It reads the PR's diff
115
+ from the merge base with `origin/main` to your pin and classifies every path.
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
118
+ skips the acceptance mutation below. Exit 1 (not inert) and exit 2 (could not
119
+ look) both run the mutation exactly as it is described below. When you skip,
120
+ the verdict's one JSON line goes in your report in place of the `red:` line.
121
+
112
122
  **Whatever you verify by RUNNING, run in a tree nobody else owns.**
113
123
  Independently re-running the ticket's acceptance mutation — loosen the
114
124
  regex, delete the guard clause, flip the per-entry reset, run `<testCmd>`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.102.7",
3
+ "version": "3.104.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": {
@@ -105,7 +105,7 @@ const NAME = "closeout";
105
105
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
106
106
  const MAX_BUFFER = 64 * 1024 * 1024;
107
107
  const NETWORK_TIMEOUT_MS = 120_000;
108
- const METRICS = ["docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv", "docs/metrics/tier-outcomes.tsv"];
108
+ export const METRICS = Object.freeze(["docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv", "docs/metrics/tier-outcomes.tsv"]);
109
109
  const TICK_OVER = "ACTION: run over";
110
110
 
111
111
  const script = (name) => join(SCRIPTS, name);
@@ -69,6 +69,7 @@ export const isTestName = (p) => testSubject(p) !== null;
69
69
  // that keeps `vite.config.ts` config without a list of JS extensions, and it also
70
70
  // claims a non-JS module named like `app.config.py`.
71
71
  export const isDocs = (p) => /\.(md|mdx|markdown|txt|rst|adoc)$/i.test(p) || /(^|\/)(README|CHANGELOG|LICENSE|CONTRIBUTING)(\.|$)/i.test(p);
72
+ export const isMarkdown = (p) => /\.(md|markdown)$/i.test(p);
72
73
  export const isConfig = (p) =>
73
74
  /\.(ya?ml|toml|ini|cfg|conf|json|json5|lock|env)$/i.test(p) ||
74
75
  /\.config\.[^/.]+$/i.test(p) ||
@@ -0,0 +1,227 @@
1
+ #!/usr/bin/env node
2
+ // The finisher's Inert diff verdict as one command, so duty 2 skips the
3
+ // acceptance mutation only on a script's answer and never on a reading of the
4
+ // diff.
5
+ //
6
+ // finisher-scope.mjs --worktree <abs-path> --pin <sha> [--repo <dir>]
7
+ //
8
+ // `--pin` is the full 40-hex head the finisher was dispatched against. `--repo`
9
+ // is the directory git runs in; it defaults to the worktree, which shares its
10
+ // object store with the repository, so either names the same history.
11
+ //
12
+ // The diff is `git diff-tree` from the merge base of origin/main and the pin to
13
+ // the pin, renames disabled, so a rename is a deletion and an addition and both
14
+ // paths are classified. It never reads `gh pr view --json files` and never
15
+ // reads the worktree's own head or files, so a head that moved past the pin
16
+ // does not change the answer.
17
+ //
18
+ // The diff is an Inert diff only when every rule holds:
19
+ //
20
+ // - it is non-empty, and every record was read;
21
+ // - every entry is a regular-file add, modify or delete on each side, with
22
+ // mode 100644 only: no symlink, submodule, type change, mode change or
23
+ // executable bit on either side;
24
+ // - every path, old and new side, is prose or data.
25
+ //
26
+ // prose isDocs() calls it docs, it ends in .md or .markdown, it is not
27
+ // under a test directory, and it is outside the prompt surface: no
28
+ // directory segment named skills, agents, commands or plugin, no
29
+ // directory segment that starts with a dot, and no file named
30
+ // AGENTS.md, CLAUDE.md or GEMINI.md, at any depth
31
+ // data one of the METRICS paths closeout.mjs names, and no other file
32
+ //
33
+ // Stdout is one JSON line:
34
+ //
35
+ // {verdict, exit, pin, base, paths: [{path, status, class, why}], reason}
36
+ //
37
+ // verdict "inert", "not-inert" or "unknown"
38
+ // exit 0 inert, 1 not inert, 2 could not look
39
+ // class "prose", "data", or null for a path that is neither
40
+ // reason `empty diff` for an empty diff (exit 1); null for any other exit 0
41
+ // or 1; on exit 2, what could not be read
42
+ //
43
+ // Exit vocabulary:
44
+ //
45
+ // 0 inert: the finisher may skip the acceptance mutation
46
+ // 1 not inert: the finisher runs the mutation exactly as today
47
+ // 2 could not look: the finisher runs the mutation exactly as today
48
+ //
49
+ // A usage error (a missing or relative flag, a pin that is not 40 hex) is a
50
+ // die() refusal on stderr with no verdict, exit 2. The script only reads: it
51
+ // never writes to the worktree.
52
+ //
53
+ // The verdict is also exported as inertVerdict(), so another finisher script
54
+ // can call it in-process; that call never exits the process.
55
+
56
+ import { spawnSync } from "node:child_process";
57
+ import { statSync } from "node:fs";
58
+ import { isAbsolute, resolve } from "node:path";
59
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
60
+ import { METRICS } from "./closeout.mjs";
61
+ import { isDocs, isMarkdown, isTestDir } from "./diff-stats.mjs";
62
+ import { gitEnv } from "./git-env.mjs";
63
+ import { isCLI } from "./is-cli.mjs";
64
+
65
+ const NAME = "finisher-scope";
66
+ const GIT_TIMEOUT_MS = 60_000;
67
+ const MAX_BUFFER = 64 * 1024 * 1024;
68
+ const ZERO = "000000";
69
+ const PLAIN = "100644";
70
+ const SHA = /^[0-9a-f]{40}$/;
71
+ const RAW = /^:(\d{6}) (\d{6}) ([0-9a-f]+) ([0-9a-f]+) (\S+)$/;
72
+ const PROMPT_DIRS = new Set(["skills", "agents", "commands", "plugin"]);
73
+ const PROMPT_FILES = new Set(["agents.md", "claude.md", "gemini.md"]);
74
+ const USAGE = "usage: finisher-scope.mjs --worktree <abs-path> --pin <sha> [--repo <dir>]";
75
+ const EXIT = { inert: 0, "not-inert": 1, unknown: 2 };
76
+
77
+ const die = makeDie(NAME);
78
+
79
+ // One read-only git call. `ok` false carries the reason, never a thrown error,
80
+ // and `status` when git ran and exited non-zero.
81
+ function git(cwd, args) {
82
+ const r = spawnSync("git", args, {
83
+ cwd,
84
+ env: gitEnv(),
85
+ encoding: "utf8",
86
+ timeout: GIT_TIMEOUT_MS,
87
+ maxBuffer: MAX_BUFFER,
88
+ });
89
+ if (r.error) return { ok: false, why: `git ${args[0]} could not run: ${r.error.code ?? r.error.message}` };
90
+ if (r.signal) return { ok: false, why: `git ${args[0]} killed by ${r.signal}` };
91
+ if (r.status !== 0) return { ok: false, status: r.status, why: `git ${args[0]} exited ${r.status}: ${r.stderr.trim()}` };
92
+ return { ok: true, stdout: r.stdout };
93
+ }
94
+
95
+ // The mode rule. An entry passes only as a plain-file add, delete, or modify
96
+ // with the same plain mode on both sides; anything else names what it is.
97
+ function modeProblem(status, oldMode, newMode) {
98
+ if (status === "A" && oldMode === ZERO && newMode === PLAIN) return null;
99
+ if (status === "D" && oldMode === PLAIN && newMode === ZERO) return null;
100
+ if (status === "M" && oldMode === PLAIN && newMode === PLAIN) return null;
101
+ if (status === "T") return "type change";
102
+ if (oldMode === "120000" || newMode === "120000") return "symlink";
103
+ if (oldMode === "160000" || newMode === "160000") return "submodule";
104
+ if (oldMode === "100755" || newMode === "100755") return "executable bit";
105
+ return `not a regular-file add, modify or delete (${status})`;
106
+ }
107
+
108
+ // The prompt-surface rule: the harness's names, at any depth. A segment named
109
+ // `skills-notes` is not `skills`, so only whole segments count. A dot-directory
110
+ // is where omp and the tools it discovers keep what they load as instructions
111
+ // (`.omp/rules`, `.omp/RULES.md`, `.omp/SYSTEM.md`, `.claude`, `.cursor`,
112
+ // `.github/copilot-instructions.md`), so every one is the prompt surface
113
+ // rather than a list of them that drifts as discovery grows.
114
+ function promptSurface(path) {
115
+ const parts = path.split("/");
116
+ for (const dir of parts.slice(0, -1)) {
117
+ if (dir.startsWith(".") || PROMPT_DIRS.has(dir.toLowerCase())) return `prompt surface: directory ${dir}`;
118
+ }
119
+ const file = parts.at(-1).toLowerCase();
120
+ if (PROMPT_FILES.has(file)) return `prompt surface: ${parts.at(-1)}`;
121
+ return null;
122
+ }
123
+
124
+ // One entry's class, or null with the reason it is neither. Exported for the
125
+ // test that pins each rule separately.
126
+ export function classifyEntry(path, status, oldMode, newMode) {
127
+ const mode = modeProblem(status, oldMode, newMode);
128
+ if (mode !== null) return { class: null, why: mode };
129
+ if (METRICS.includes(path)) return { class: "data", why: "run metrics file" };
130
+ if (isTestDir(path)) return { class: null, why: "under a test directory" };
131
+ if (!isMarkdown(path)) return { class: null, why: isDocs(path) ? "docs, but not .md or .markdown" : "not prose or data" };
132
+ const surface = promptSurface(path);
133
+ if (surface !== null) return { class: null, why: surface };
134
+ return { class: "prose", why: "plain markdown outside the prompt surface" };
135
+ }
136
+
137
+ // `git diff-tree -z --raw` output as entries, or null when a record is not
138
+ // the shape the command writes.
139
+ export function parseRaw(text) {
140
+ const parts = text.split("\0");
141
+ if (parts.at(-1) === "") parts.pop();
142
+ const entries = [];
143
+ for (let i = 0; i < parts.length; i += 2) {
144
+ const m = RAW.exec(parts[i]);
145
+ if (m === null || i + 1 >= parts.length) return null;
146
+ entries.push({ oldMode: m[1], newMode: m[2], status: m[5], path: parts[i + 1] });
147
+ }
148
+ return entries;
149
+ }
150
+
151
+ // The verdict for one PR. Never exits the process: a caller in-process gets
152
+ // the same object the command prints. `repo` absent or null is the worktree.
153
+ export function inertVerdict({ worktree, pin, repo }) {
154
+ const lowered = typeof pin === "string" ? pin.toLowerCase() : "";
155
+ const sha = SHA.test(lowered) ? lowered : null;
156
+ // Every result is built here, so `exit` is always the one its verdict names.
157
+ const result = (verdict, fields) => ({ verdict, exit: EXIT[verdict], pin: sha, base: null, paths: [], reason: null, ...fields });
158
+ const fail = (reason, base = null) => result("unknown", { base, reason });
159
+ if (typeof worktree !== "string" || !isAbsolute(worktree)) return fail("worktree is not an absolute path");
160
+ if (sha === null) return fail("pin is not a full 40-hex commit SHA");
161
+ const cwd = repo ?? worktree;
162
+
163
+ // `rev-parse --verify --quiet` exits 1 for a name that resolves to nothing;
164
+ // any other failure is git's own, and its reason is the one reported.
165
+ const origin = git(cwd, ["rev-parse", "--verify", "--quiet", "refs/remotes/origin/main^{commit}"]);
166
+ if (!origin.ok) {
167
+ return fail(origin.status === 1 ? "no origin/main to take the merge base against" : `could not read origin/main: ${origin.why}`);
168
+ }
169
+ const head = git(cwd, ["rev-parse", "--verify", "--quiet", `${sha}^{commit}`]);
170
+ if (!head.ok) return fail(head.status === 1 ? "pin names no commit" : `could not read the pin: ${head.why}`);
171
+ const mb = git(cwd, ["merge-base", "--all", "refs/remotes/origin/main", sha]);
172
+ if (!mb.ok) return fail(`no merge base: ${mb.why}`);
173
+ const bases = mb.stdout.trim().split("\n").filter(Boolean);
174
+ if (bases.length !== 1) return fail(`ambiguous merge base: ${bases.length} candidates`);
175
+ const base = bases[0];
176
+
177
+ const d = git(cwd, [
178
+ "diff-tree", "-r", "-z", "--raw", "--no-renames", "--no-abbrev", "--no-commit-id", base, sha,
179
+ ]);
180
+ if (!d.ok) return fail(`diff could not be read: ${d.why}`, base);
181
+ const entries = parseRaw(d.stdout);
182
+ if (entries === null) return fail("diff output could not be parsed", base);
183
+ if (entries.length === 0) return result("not-inert", { base, reason: "empty diff" });
184
+
185
+ const paths = entries.map((e) => {
186
+ const c = classifyEntry(e.path, e.status, e.oldMode, e.newMode);
187
+ return { path: e.path, status: e.status, class: c.class, why: c.why };
188
+ });
189
+ return result(paths.some((p) => p.class === null) ? "not-inert" : "inert", { base, paths });
190
+ }
191
+
192
+ // A path stat cannot read at all (EACCES on a parent) is a usage refusal like a
193
+ // missing one: uncaught, it would exit 1, the not-inert code, about a diff
194
+ // nobody read.
195
+ function isDirectory(p) {
196
+ try {
197
+ return statSync(p, { throwIfNoEntry: false })?.isDirectory() === true;
198
+ } catch (e) {
199
+ return die(`cannot stat ${p}: ${e.code ?? e.message}`);
200
+ }
201
+ }
202
+
203
+ function main() {
204
+ const { arg, sweep, stray } = defineFlags(die, {
205
+ flags: { worktree: "value", pin: "value", repo: "value" },
206
+ });
207
+ // The sweep runs before the required-flag check, so a misspelt flag is named
208
+ // as that and not buried under a missing-flag usage line.
209
+ sweep();
210
+ stray();
211
+ const worktree = arg("worktree");
212
+ const pin = arg("pin");
213
+ const repoArg = arg("repo");
214
+ if (worktree === null || pin === null) die(USAGE);
215
+ if (!isAbsolute(worktree)) die(`--worktree must be an absolute path, got ${worktree}`);
216
+ if (!isDirectory(worktree)) die(`--worktree is not a directory: ${worktree}`);
217
+ if (!SHA.test(pin.toLowerCase())) die(`--pin needs a full 40-character commit SHA, got ${pin}`);
218
+ if (repoArg !== null && !isDirectory(resolve(repoArg))) die(`--repo is not a directory: ${repoArg}`);
219
+
220
+ const v = inertVerdict({ worktree, pin, repo: repoArg === null ? null : resolve(repoArg) });
221
+ // Exit 0 is the only code that skips the mutation, so a verdict that never
222
+ // reached stdout must not leave it set: a lost write is the could-not-look exit.
223
+ if (!writeAll(1, `${JSON.stringify(v)}\n`)) die("the verdict could not be written to stdout");
224
+ process.exitCode = v.exit;
225
+ }
226
+
227
+ if (isCLI(import.meta.url)) main();
@@ -130,6 +130,9 @@ NAME=instruments
130
130
  # operand, and the messages below carry paths that git will happily hand us with
131
131
  # a backslash in them.
132
132
  die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
133
+ # The value of the baseline's first `<key>=` line, the one match every reader
134
+ # of the file takes.
135
+ baseline_field() { sed -n "/^$1=/{s/^$1=//;p;q;}" "$base"; }
133
136
 
134
137
  pin=false
135
138
  repo=""
@@ -238,7 +241,7 @@ elif [ "$pin" = true ] && [ -z "$home" ]; then
238
241
  { [ -e "$base" ] || [ -L "$base" ]; } && [ ! -r "$base" ] \
239
242
  && die "$base exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
240
243
  if [ -r "$base" ]; then
241
- prior=$(sed -n '/^root=/{s/^root=//;p;q;}' "$base") || die "cannot read $base"
244
+ prior=$(baseline_field root) || die "cannot read $base"
242
245
  [ -n "$prior" ] && target=$prior
243
246
  fi
244
247
  fi
@@ -297,7 +300,7 @@ if [ "$pin" != true ]; then
297
300
  # moved or copied `.fleet/`, a clone that arrived carrying another
298
301
  # workspace's baseline) or a forgery. Both refuse; re-pin here fixes the
299
302
  # first and the second is the finding.
300
- rec=$(sed -n '/^root=/{s/^root=//;p;q;}' "$base")
303
+ rec=$(baseline_field root)
301
304
  if [ -n "$home" ] && [ -n "$rec" ] && [ "$rec" != "$root" ]; then
302
305
  die "baseline in $base certifies a foreign audited tree ($rec) while $root tracks its own instrument set — the baseline does not belong to this checkout, or was tampered with; refuse, do not re-read"
303
306
  fi
@@ -357,17 +360,25 @@ digest=$(printf '%s\n' "$per_file" | shasum -a 256 | cut -d' ' -f1) \
357
360
 
358
361
  if [ "$pin" = true ]; then
359
362
  mkdir -p "$root/.fleet" || die "cannot create $root/.fleet"
360
- # Two lines, order fixed: the digest first, the audited tree's toplevel
361
- # second. A reader that only knows the old one-line shape — merge-gate.mjs's
362
- # `readInstruments`, which takes the FIRST stdout line as the digest — keeps
363
- # working, and a check from this script reads both. The root rides in the
364
- # same write as the digest because it is not a suggestion: a pointer an
365
- # attacker with a writable `.fleet/` could repoint at will would move the
366
- # gate to a tree they control, so the check trusts nothing else, re-verifies
367
- # the tree at check time, and refuses if it moved.
363
+ # Three lines, order fixed: the digest first, the audited tree's toplevel
364
+ # second, the audited tree's HEAD commit third. A reader that only knows the
365
+ # old one-line shape — merge-gate.mjs's `readInstruments`, which takes the
366
+ # FIRST stdout line as the digest — keeps working, and a check from this
367
+ # script reads the rest. The root rides in the same write as the digest
368
+ # because it is not a suggestion: a pointer an attacker with a writable
369
+ # `.fleet/` could repoint at will would move the gate to a tree they control,
370
+ # so the check trusts nothing else, re-verifies the tree at check time, and
371
+ # refuses if it moved.
372
+ #
373
+ # The commit is not trusted for any verdict: it exists only so a refusal can
374
+ # say what moved. HEAD unborn or unreadable writes no `commit=` line, and
375
+ # the refusal says so; a baseline from before this line existed reads the
376
+ # same way.
377
+ commit=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || commit=
368
378
  {
369
379
  printf '%s\n' "$digest"
370
380
  printf 'root=%s\n' "$target"
381
+ [ -z "$commit" ] || printf 'commit=%s\n' "$commit"
371
382
  } > "$base" || die "cannot write $base"
372
383
  printf '%s\n' "$digest"
373
384
  printf '%s: pinned %s over %s\n' "$NAME" "$digest" "$target ($set)" >&2
@@ -387,7 +398,62 @@ fi
387
398
  # is about — not the state home the baseline was found in.
388
399
  printf '%s: instrument set CHANGED under this run — expected %s\n' "$NAME" "$want" >&2
389
400
  printf '%s: refuse the gate and report. Do NOT re-read the instrument.\n' "$NAME" >&2
390
- printf '%s: HEAD %s\n' "$NAME" "$(git -C "$target" rev-parse HEAD 2>/dev/null || printf '?')" >&2
401
+ headc=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || headc=
402
+ printf '%s: HEAD %s\n' "$NAME" "${headc:-?}" >&2
391
403
  # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
392
404
  git -C "$target" status --porcelain -- $set >&2 || true
405
+
406
+ # Then what moved, relative to the commit the pin recorded. Only the commit
407
+ # graph can say whether HEAD advanced, rewound or diverged, and the maintainer
408
+ # decides what to do about each, so this names the relation and stops: the
409
+ # verdict above is already refusal. Anything but a full hex id is treated as
410
+ # absent from the repository, so a baseline line cannot reach git as an option.
411
+ pinc=$(baseline_field commit)
412
+ present=false
413
+ case $pinc in
414
+ *[!0-9a-f]*) ;;
415
+ *) if { [ "${#pinc}" -eq 40 ] || [ "${#pinc}" -eq 64 ]; } \
416
+ && git -C "$target" cat-file -e "$pinc^{commit}" 2>/dev/null; then
417
+ present=true
418
+ fi ;;
419
+ esac
420
+ if [ -z "$pinc" ]; then
421
+ printf '%s: pin commit not recorded — the baseline has no commit= line\n' "$NAME" >&2
422
+ elif [ "$present" != true ]; then
423
+ printf '%s: pin commit %s is not in the repository\n' "$NAME" "$pinc" >&2
424
+ elif [ -z "$headc" ]; then
425
+ printf '%s: pin commit %s; HEAD cannot be read\n' "$NAME" "$pinc" >&2
426
+ else
427
+ printf '%s: pin commit %s\n' "$NAME" "$pinc" >&2
428
+ if [ "$headc" = "$pinc" ]; then
429
+ printf '%s: HEAD unmoved — HEAD is the pin commit\n' "$NAME" >&2
430
+ else
431
+ # `--is-ancestor` answers with its exit code: 0 is yes and 1 is no. Any
432
+ # other code is git failing to compare — an unreadable object, a corrupt
433
+ # history — and a relation read off that failure would hand the
434
+ # maintainer a false fact to rule on, so it says unknown and lets git's
435
+ # own error through.
436
+ fwd=0
437
+ git -C "$target" merge-base --is-ancestor "$pinc" "$headc" || fwd=$?
438
+ back=1
439
+ if [ "$fwd" -eq 1 ]; then
440
+ back=0
441
+ git -C "$target" merge-base --is-ancestor "$headc" "$pinc" || back=$?
442
+ fi
443
+ if [ "$fwd" -eq 0 ]; then
444
+ printf '%s: HEAD advanced — the pin commit is an ancestor of HEAD\n' "$NAME" >&2
445
+ git --no-pager -C "$target" log --no-decorate --no-color --oneline -n 20 "$pinc..$headc" >&2 || true
446
+ between=$(git -C "$target" rev-list --count "$pinc..$headc" 2>/dev/null || printf 0)
447
+ if [ "$between" -gt 20 ]; then
448
+ printf '… %s more\n' "$((between - 20))" >&2
449
+ fi
450
+ elif [ "$fwd" -eq 1 ] && [ "$back" -eq 0 ]; then
451
+ printf '%s: HEAD rewound — HEAD is an ancestor of the pin commit\n' "$NAME" >&2
452
+ elif [ "$fwd" -eq 1 ] && [ "$back" -eq 1 ]; then
453
+ printf '%s: HEAD diverged — neither is an ancestor of the other\n' "$NAME" >&2
454
+ else
455
+ printf '%s: HEAD relation unknown — git could not compare the pin commit with HEAD\n' "$NAME" >&2
456
+ fi
457
+ fi
458
+ fi
393
459
  exit 1
@@ -520,7 +520,7 @@ Pointers: the `/resume` rules are in `references/phase-0.md`; the tick HOLD tier
520
520
 
521
521
  ## The finisher gate
522
522
 
523
- Dispatch a finisher only when every test here passes at once — the review returned, the fix-applier's report arrived, your outbox to it is empty, no reply is owed and the PR's ruling is recorded; hold otherwise, and on a repo with no CI and no declaration report it and add no label.
523
+ Dispatch a finisher only when every test here passes at once — the review returned, the fix-applier's report arrived, your outbox to it is empty, no reply is owed and the PR's ruling is recorded; hold otherwise.
524
524
 
525
525
  ### The tests
526
526
 
@@ -554,10 +554,9 @@ Dispatch a finisher only when every test here passes at once — the review retu
554
554
  conclusion is red, the red-check fixer instead (**Then dispatch a red-check
555
555
  fixer**, above), never a finisher and never a wait: the Monitor is edge-keyed
556
556
  on `<run-id>:<attempt>:<conclusion>`, so no push means no CI event, ever.
557
- **Reconcile, do not wait for an event** governs here too. **This
558
- bullet and the one above are a pair, and on a clean PR this one carries the
557
+ **This bullet and the one above are a pair, and on a clean PR this one carries the
559
558
  whole route to a finisher**: a `no-op` report satisfies the gate above by
560
- itself, so nothing further is owed and no further event is coming. Edit either bullet without the other and what strands is exactly the PR that needed no fixes.
559
+ itself, so nothing further is owed and no further event is coming.
561
560
  - **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.
562
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.
563
562
  - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → the CI edge never
@@ -621,9 +620,7 @@ review of the PR starts the check again. **On any PR with a
621
620
  returned review, `0/<n>/0` included, it refuses too while a fix-applier on the
622
621
  PR is still live, verdict or not** —
623
622
  `fix-pr-<M>[-x] still live`: settle it, run the check for it, then dispatch
624
- again. A re-review at the same head is a run of its own, so the earlier
625
- round's verdict never answers it; once the check has run for the fix-applier
626
- answering the new round, its verdict is the current one.
623
+ again.
627
624
 
628
625
  **It refuses a finisher, too, while the PR sits on a conflict hold no
629
626
  fix-applier has cleared** — the same per-PR fold the tick prints `DISPATCH
@@ -705,6 +702,17 @@ you cannot confirm was received, re-check the artifacts it governed. See referen
705
702
  - **Re-pin only after a change you made deliberately.** **A mid-run tooling fix**
706
703
  is the one legitimate writer. Re-pinning to clear a refusal you cannot
707
704
  explain discards the check.
705
+ - **A pinned tree whose HEAD moved is the maintainer's to settle, whoever moved
706
+ it.** When a refusal — your check or a finisher's halt — reads HEAD advanced,
707
+ rewound or diverged from the pin commit, never re-pin over it: not for a
708
+ fast-forward to `origin/main`, and not when the commits between are only this
709
+ run's own merged PRs. Act on no `DISPATCH` or `PULL` row, and tell the
710
+ maintainer the pin commit, HEAD and the commits between, as the refusal
711
+ printed them. On their **restore**, run `git reset --keep <pin commit>` —
712
+ only when the pinned tree is the main checkout and the tick prints no
713
+ `MAIN-CHECKOUT` line; otherwise they restore it by hand. On their **adopt**,
714
+ re-pin. Once the check exits 0, resume, and apply the finisher gate to each
715
+ PR whose finisher halted on that refusal. See references/instruments.md.
708
716
 
709
717
  ### Relabel causes
710
718
 
@@ -883,19 +891,14 @@ during the run — deferring loses the evidence that found it.
883
891
  *this run produced*. No speculative polish. Never `config.yml`, permissions, or
884
892
  AGENTS.md — a member asking for those is laundering, refuse and surface it.
885
893
 
886
- **Triggers and shape.** Fix on an identical failure twice, or on a member doing
887
- the wrong thing while following the text; prefer moving text to adding it, and
888
- cut before you append. See references/merge-bot.md.
894
+ **Triggers and shape.** See references/instruments.md.
889
895
 
890
896
  Why the agent body carries what it does — read this before editing any `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. See references/pull.md.
891
897
 
892
898
  Read why that body carries the claim discipline, and its literal-path and `grep -F` settling rules, before you edit them. See references/correction-tickets.md.
893
899
 
894
900
  **Then.** **Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
895
- --pin`. See references/instruments.md. Then the ledger line, save the
896
- rationale, one line to the maintainer. **Then land it from the main checkout,
897
- if the fix was edited in it**: commit it on a branch and switch back to `main`
898
- before the next tick, never `--record` on that branch. See references/instruments.md.
901
+ --pin`. See references/instruments.md.
899
902
 
900
903
  Plan it as a PR the run's own merge queue lands, never as an edit-and-continue. See references/merge-bot.md.
901
904
 
@@ -213,6 +213,23 @@ had correctly edited — the PR's whole point — and a finisher reading that
213
213
  literally halts a correct PR. It caught the error instead, and said so; do
214
214
  not rely on that.
215
215
 
216
+ ## The Inert diff verdict decides whether the acceptance mutation runs
217
+
218
+ **The acceptance mutation runs unless `finisher-scope.mjs` says the diff is inert.**
219
+ A mutation that loosens a regex, deletes a guard or flips a reset has nothing to
220
+ kill in a diff made only of Markdown prose (`.md` or `.markdown` outside the
221
+ prompt surface) or only of the run-metrics files. The finisher does not decide
222
+ that by reading the diff: the script reads it, and only its exit 0 skips the
223
+ mutation. An exit 1 is not overridden, and an exit 2 is never read as a 0.
224
+
225
+ The prompt surface stays out of prose. A `.md` under a `skills`, `agents`,
226
+ `commands` or `plugin` directory or under any dot-directory (`.omp/rules`,
227
+ `.omp/RULES.md`, `.claude`), and any `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`, is
228
+ read by the harness, so it can change behavior. A symlink, submodule, mode
229
+ change or other non-regular entry is a code change whatever its name, so it is
230
+ not prose either. The verdict is read at the dispatch pin: the worktree's own
231
+ head is not part of it, and duty 1 audits that head separately.
232
+
216
233
  ## Whatever you verify by running, run in a tree nobody else owns
217
234
 
218
235
  **Whatever you verify by RUNNING, run in a tree nobody else owns.**
@@ -286,6 +303,10 @@ a minute apart showed *different* mutants, so a member's report and any single
286
303
  otherwise you send "your red is staleness, do not rebase" once per member per
287
304
  merge. `review-and-fix.md` states them; the body says they apply.
288
305
 
306
+ ## A re-review at the same head answers on its own run
307
+
308
+ A re-review at the same head is a run of its own, so the earlier round's verdict never answers it; once the check has run for the fix-applier answering the new round, its verdict is the current one.
309
+
289
310
  ## A halt's cause comes from one script
290
311
 
291
312
  A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
@@ -43,6 +43,11 @@ You just changed the instrument set under your own check, and this is the
43
43
  only edit that legitimately does; skip it and the next gate refuses on your own
44
44
  fix, which teaches you to ignore the refusal.
45
45
 
46
+ ## Triggers and shape of a mid-run tooling fix
47
+
48
+ Fix on an identical failure twice, or on a member doing the wrong thing while
49
+ following the text; prefer moving text to adding it, and cut before you append.
50
+
46
51
  ## Landing a mid-run tooling fix from the main checkout
47
52
 
48
53
  **Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
@@ -62,3 +67,47 @@ dirty again. Any other path on that line is a stray write — leave the hold for
62
67
  the maintainer, because `--record` would certify it with yours. Live members
63
68
  hold the old text — re-brief only if it changes what they do *now*.
64
69
 
70
+ ## A pinned tree whose HEAD moved is the maintainer's to settle
71
+
72
+ `instruments.sh --pin` records the pinned tree's HEAD as `commit=<sha>` after
73
+ the digest and `root=`, and an exit-1 refusal prints that pin commit and how
74
+ HEAD relates to it: `advanced` (the pin commit is an ancestor of HEAD, with the
75
+ commits between, at most 20 and then `… N more`), `rewound`, `diverged`, or
76
+ `unmoved` (HEAD is the pin commit, so the porcelain lines name the edits). When
77
+ git cannot compare the two — an unreadable object, a corrupt history — it says
78
+ the relation is `unknown`, with git's own error, rather than guess one; HEAD is
79
+ not the pin commit there either, so never re-pin over it. A baseline with no
80
+ `commit=` line, or one whose commit is gone from the repository, prints one
81
+ line saying so and no relation.
82
+
83
+ **The measured case.** Another session fast-forwarded the main checkout to
84
+ `origin/main` mid-run. The commits that brought in were only this run's own
85
+ merged PRs, the controller counted them as its own, re-pinned without asking and
86
+ dispatched the next finishers. The tick could not see the move: its
87
+ main-checkout guard reads a fast-forward to `origin/main` as clean, and the tick
88
+ never runs the instrument check. Only the gate re-checks saw it — a finisher
89
+ halting with cause `other`, the merge gate refusing with
90
+ `instrument-set-changed`. A refusal cannot tell a move the maintainer would
91
+ adopt from one they would not, because only they know whether a session of
92
+ theirs is working in that checkout, so the pin stays frozen and the move stays
93
+ a refusal even when the commits between are only the run's own.
94
+
95
+ **Why the reset is the controller's only on a clean tick.** A clean
96
+ main-checkout reading means HEAD is still on `main` and every commit since the
97
+ baseline is on `origin/main`. So `git reset --keep <pin commit>` moves no other
98
+ branch and drops nothing that exists only locally, and `--keep` refuses rather
99
+ than overwrite an uncommitted edit that conflicts with the move. On a switched
100
+ branch the guard prints `MAIN-CHECKOUT-DIRTY HEAD …`, and a reset there would
101
+ move that other branch, so the maintainer restores such a tree by hand.
102
+
103
+ Measured in a temp clone with the real `main-checkout.mjs` and
104
+ `instruments.sh`, the pin 3 commits behind `origin/main` and 4 set paths
105
+ different:
106
+
107
+ | Checkout state | Main-checkout guard | Instrument check |
108
+ |---|---|---|
109
+ | at the pin commit | clean | 0 |
110
+ | fast-forwarded to `origin/main` | clean | 1 |
111
+ | after `git reset --keep <pin commit>` | clean | 0 |
112
+ | on another branch | `MAIN-CHECKOUT-DIRTY HEAD refs/heads/main@… → refs/heads/other@…` | 1 |
113
+