@feigi/fleet-ctl 3.103.0 → 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.103.0",
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();
@@ -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.**