@feigi/fleet-ctl 3.134.1 → 3.136.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.
@@ -214,7 +214,7 @@ For each labeled PR clearing the hold rule, lowest first:
214
214
 
215
215
  `<text>` is everything after the key, verbatim — `row` rewrites the whole line, so a token you drop is gone. `#<pr>` is this PR, never the one it conflicts with; the tick refuses a hold naming another PR. The `(conflict: …)` note is free text, comma-joined paths from the `diff --name-only` read above — placed *after* the token, never before, so it cannot become the first `PR#` mention a row with no `impl-` token is read by (`ledger-grammar.mjs`'s `rowPr`) or fall inside `CONFLICT_HOLD`'s own pattern. From then on the tick prints `DISPATCH fix-pr PR#<pr>` for it and counts it in `held=` until a fix-applier dispatched after the hold settles `applied:`/`no-op`. Skip the `row` write on an already-unresolved hold, per the paragraph above — nothing else about this path changes: still report `rebase-fallback-#<pr>`, still hand it back.
216
216
 
217
- **The fallback's "verified" needs a clean main-gain check on the local rebased head.** Save the PR body to `<scratch>/pr<N>/merge-bot-<n>/body.md` (`gh pr view <pr> --json body -q .body`) and, from the main checkout, run `~/.fleet/bin/fleet-run main-gain.mjs --head "$(git -C <worktree> rev-parse HEAD)" --body-file <scratch>/pr<N>/merge-bot-<n>/body.md`. Exit 0 is the only clean result; name every `acknowledged[]` entry, with its reason, in the hand-back. Exit 1 (a line `main` gained after the PR began would be removed) or exit 2 (it could not answer) is reported inside `rebase-fallback-#<pr>` — the hits and each one's `ack` line to copy, or the `reason` it could not answer — and the fallback is never reported verified.
217
+ **The fallback's "verified" needs a clean main-gain check on the local rebased head.** Save the PR body to `<scratch>/pr<N>/merge-bot-<n>/body.md` (`gh pr view <pr> --json body -q .body`) and, beside it, what `gh pr view <pr> --json number,url,closingIssuesReferences` prints to `<scratch>/pr<N>/merge-bot-<n>/closing-refs.json`, then from the main checkout run `~/.fleet/bin/fleet-run main-gain.mjs --head "$(git -C <worktree> rev-parse HEAD)" --body-file <scratch>/pr<N>/merge-bot-<n>/body.md --closing-refs <scratch>/pr<N>/merge-bot-<n>/closing-refs.json`, so both paths reach one verdict. Exit 0 is the only clean result; name every `acknowledged[]` entry, with its reason, in the hand-back. Exit 1 (a line `main` gained after the PR began would be removed) or exit 2 (it could not answer) is reported inside `rebase-fallback-#<pr>` — the hits and each one's `ack` line to copy, or the `reason` it could not answer — and the fallback is never reported verified.
218
218
 
219
219
  2. Watch checks settle **on the rebased head**. A missing release label (`patch`/`minor`/`major`) fails `validate-release-label` — add the one matching; `release-label.yml` defines that job and exits 1 when the count of those three is zero. A stale `rebase-check` failure usually means step 1 has not landed. Where a repo chains jobs behind that check with `needs:`, they come back `skipped` rather than red and the currency check is the only thing to fix — check `ci.yml` for a `needs:` chain before assuming that: it declares none as of this reading, so no job is currently skipped behind `rebase-check`. **The wait is bounded: 20 minutes of wall-clock per PR, measured from your first poll for it across every poll cell you issue for it.** The bound belongs to one selection of the PR: a PR re-selected fresh from step 1 after a `behind:<n>` skip is rebased again, runs a new CI run, and gets a fresh bound, whatever the earlier wait spent. A run whose `status` is still not `completed` at that bound is an outcome, not a reason to poll on — skip the PR and report `ci-wait-timeout-#<pr>` with the run id and its `status`, leave the label alone, and move to the next candidate; handled the same way as step 3.1's null-runId cap.
220
220
 
@@ -237,7 +237,7 @@ For each labeled PR clearing the hold rule, lowest first:
237
237
  --out <scratch>/pr<N>/merge-bot-<n>/ci.json; rc=$?
238
238
  ```
239
239
 
240
- `--pre` is the head you recorded at **The labelled head**; `--post` is the head step 1's rebase produced — omit it when no rebase ran, which is the same as passing `pre` twice. `pr<N>` is this PR and `merge-bot-<n>` is your own name, so the reading lands under a directory only you write, never in the scratch root by itself: `<scratch>` is the absolute path your dispatch prompt names, and that root is shared with every sibling. The gate is read-only — it runs the instrument re-check, `gh pr view <pr> --json labels,reviewDecision,headRefOid,body`, the main-gain check against that head in the main checkout, the rebase-carry proof when that head is neither `pre` nor `post`, and `ci-state.mjs --pr <pr>`, answers their conjunction, and never merges, labels, rebases or waits. Stdout is exactly one JSON line, `{pr, verdict, reason, head, bodyDigest, pre, post, rebaseCarry, behind, instruments, mainGain, ci}`; stderr is its children's diagnostics, so never fold `2>&1` into the line you read. Read `rc` straight off the call, as above — never through a pipe.
240
+ `--pre` is the head you recorded at **The labelled head**; `--post` is the head step 1's rebase produced — omit it when no rebase ran, which is the same as passing `pre` twice. `pr<N>` is this PR and `merge-bot-<n>` is your own name, so the reading lands under a directory only you write, never in the scratch root by itself: `<scratch>` is the absolute path your dispatch prompt names, and that root is shared with every sibling. The gate is read-only — it runs the instrument re-check, `gh pr view <pr> --json labels,reviewDecision,headRefOid,body,url,closingIssuesReferences`, the main-gain check against that head in the main checkout (handed the PR's number, `url` and `closingIssuesReferences` as that read printed them), the rebase-carry proof when that head is neither `pre` nor `post`, and `ci-state.mjs --pr <pr>`, answers their conjunction, and never merges, labels, rebases or waits. Stdout is exactly one JSON line, `{pr, verdict, reason, head, bodyDigest, pre, post, rebaseCarry, behind, instruments, mainGain, ci}`; stderr is its children's diagnostics, so never fold `2>&1` into the line you read. Read `rc` straight off the call, as above — never through a pipe.
241
241
 
242
242
  **Run a plain `git fetch origin` in the main checkout before every gate run** — never `git fetch origin <src>:<dst>`, for the reason step 1's fallback gives. The main-gain check and the rebase-carry proof read `origin/main` and the head objects there as they stand and fetch nothing themselves: an unfetched head is `main-gain-unanswerable`, an unheld labelled or carried head is no carry, and a stale `origin/main` is a check against the wrong `main`.
243
243
 
@@ -247,9 +247,9 @@ For each labeled PR clearing the hold rule, lowest first:
247
247
  Each `reason` is a fact the gate now enforces, not a step you run:
248
248
 
249
249
  - **`head-moved-after-label`** — the PR head is neither `pre` nor `post`, nor a head whose net change the gate proved identical to `pre`'s (`rebaseCarry`, which names both). **Any third SHA is a push that landed while you waited on CI, and no CI check can see it**: `ci-state.mjs` selects the run whose `headSha` equals the *current* PR head (`scripts/ci-state.mjs`, the `r.headSha === prHead` filter), so a member's push plus its own green run satisfies every CI check while the audit behind the label belongs to a tree that is gone. A carry is proven only for the head `gh pr view` read; a different head at `ci-state`'s own read is still this row. The remedy is a fresh finisher against the new head, label untouched.
250
- - **`main-gain-removed:<path>`** — merging this head would remove lines `main` gained after the PR's work began: lines a later merge landed, deleted by a branch commit that every rebase since has replayed without a conflict, so no conflict preview and no `origin/main...HEAD` read is sure to show them. `mainGain.hits[]` names each file, the landing key (`#<n>` for a merged PR, else the landing commit's 12-character SHA), the removed lines, and the `ack` line to copy. Skip the PR, leave the label alone, and report `main-gain-removed:<path>-#<pr>` with the hit list and the keys. Never restore the lines yourself — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for every hit; the gate reads the body each run, so editing it is enough. An acknowledged removal is listed in `mainGain.acknowledged[]` and the gate passes it — name each one, with its reason, in your report. Your report's `refused[]` entry for the PR carries the gate's `reason` as it printed it, `main-gain-removed:<path>`, and the gate's `--out` file above stays where the gate wrote it: the controller parks the PR off that entry, at the `head` and `bodyDigest` that file records the gate refused, and no merge bot is dispatched on the PR's account until its head or its body changes — though a bot dispatched for another queued PR may still evaluate it again.
250
+ - **`main-gain-removed:<path>`** — merging this head would remove lines `main` gained after the PR's work began: lines a later merge landed, deleted by a branch commit that every rebase since has replayed without a conflict, so no conflict preview and no `origin/main...HEAD` read is sure to show them. `mainGain.hits[]` names each file, the landing key (`#<n>` for a merged PR, else the landing commit's 12-character SHA), the removed lines, each hunk that held any of them (`hunks[]`: the line numbers, the `added` lines the removed tokens were compared against, and the `missing` tokens with counts, a blank line's token written `"\n"`), and the `ack` line to copy. Skip the PR, leave the label alone, and report `main-gain-removed:<path>-#<pr>` with the hit list and the keys. Never restore the lines yourself — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for every hit; the gate reads the body each run, so editing it is enough. An acknowledged removal is listed in `mainGain.acknowledged[]` and the gate passes it — name each one, with its reason, in your report. Your report's `refused[]` entry for the PR carries the gate's `reason` as it printed it, `main-gain-removed:<path>`, and the gate's `--out` file above stays where the gate wrote it: the controller parks the PR off that entry, at the `head` and `bodyDigest` that file records the gate refused, and no merge bot is dispatched on the PR's account until its head or its body changes — though a bot dispatched for another queued PR may still evaluate it again.
251
251
 
252
- Each hit line carries a `kind`: `modified` when the hunk that removed it also adds lines, none of which claimed it as an in-place edit, or `deleted` when the hunk only removes lines. A removed line edited in place that keeps every token of its text is not a hit; the gate lists it in `mainGain.edited[]` and passes it.
252
+ Each hit line carries a `kind`: `modified` when the hunk that removed it also adds lines, none of which claimed it as an in-place edit, or `deleted` when the hunk only removes lines. The gate clears a gained line, lists it in `mainGain.edited[]` with the `rule` that cleared it, and passes it, by three rules. `line`: a removed line edited in place that keeps every token of its text, one entry per line. `hunk`: every removed line of a hunk that adds lines — gained and older lines alike, a blank line counting as one blank token — has its tokens among the hunk's added lines, as a re-wrap does, so the gained lines no `line` entry covers clear together. `retracted #N`: the hunk rule fails only because the PR deleted a forward reference to a ticket it closes (`once #N lands`, `until #N ships` and the like), so the reference's tokens are dropped from the removed side and the one token after it may differ from an added token in case alone; `N` lists every closing issue its removed phrases named, and a PR that only refers to the ticket (`Refs #N`) gets no such clearing. A `hunk` or `retracted #N` entry is one per cleared hunk: `line` is its first cleared gained line, `text` the cleared lines joined with a newline and `replacement` the added lines compared. Tokens never cross hunks, and a hunk that only removes lines is never cleared, so a `deleted` line is always a hit. The gate reads which issues the PR closes from the references `--closing-refs` carries, echoed as `closes`, `null` when they could not be read, which turns the retraction rule off.
253
253
  - **`main-gain-unanswerable`** — the main-gain check could not answer: a head object the main checkout does not hold after `git fetch origin`, a merge that does not resolve cleanly, a blame that failed. `mainGain.reason` says which. Stop and report `main-gain-unanswerable-#<pr>` with it, label untouched.
254
254
  - **`behind:<n>`** — you are the only place currency is proven, and a sibling merge since your rebase expires it (the staleness below).
255
255
  - **`instrument-set-changed` / `instruments-unanswerable`** — the instrument re-check the controller runs before its own gates (`run-team/SKILL.md`, **You read your instruments out of a tree every member can write to**), taken at this seat because nothing dispatches a merge bot to read that rule. Report `<reason>-#<pr>` with what the gate printed, leave the label alone, and do **not** re-run the gate.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.134.1",
3
+ "version": "3.136.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": {
@@ -25,9 +25,11 @@
25
25
  //
26
26
  // prose isDocs() calls it docs, it ends in .md or .markdown, it is not
27
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
28
+ // directory segment named skills, agents or commands, no directory
29
+ // segment that starts with a dot, and no file named AGENTS.md,
30
+ // CLAUDE.md or GEMINI.md, at any depth. A file directly in the root
31
+ // .out-of-scope/, spelled exactly so, is exempt from the dot rule
32
+ // alone
31
33
  // data one of the METRICS paths closeout.mjs names, and no other file
32
34
  //
33
35
  // Stdout is one JSON line:
@@ -69,7 +71,8 @@ const ZERO = "000000";
69
71
  const PLAIN = "100644";
70
72
  const SHA = /^[0-9a-f]{40}$/;
71
73
  const RAW = /^:(\d{6}) (\d{6}) ([0-9a-f]+) ([0-9a-f]+) (\S+)$/;
72
- const PROMPT_DIRS = new Set(["skills", "agents", "commands", "plugin"]);
74
+ const PROMPT_DIRS = new Set(["skills", "agents", "commands"]);
75
+ const RECORDS_DIR = ".out-of-scope";
73
76
  const PROMPT_FILES = new Set(["agents.md", "claude.md", "gemini.md"]);
74
77
  const USAGE = "usage: finisher-scope.mjs --worktree <abs-path> --pin <sha> [--repo <dir>]";
75
78
  const EXIT = { inert: 0, "not-inert": 1, unknown: 2 };
@@ -110,10 +113,16 @@ function modeProblem(status, oldMode, newMode) {
110
113
  // is where omp and the tools it discovers keep what they load as instructions
111
114
  // (`.omp/rules`, `.omp/RULES.md`, `.omp/SYSTEM.md`, `.claude`, `.cursor`,
112
115
  // `.github/copilot-instructions.md`), so every one is the prompt surface
113
- // rather than a list of them that drifts as discovery grows.
116
+ // rather than a list of them that drifts as discovery grows. The one exception
117
+ // is a file directly in the root `.out-of-scope/`: the triage skill writes a
118
+ // rejection record there, read as settled precedent rather than as an
119
+ // instruction, so the directory rule passes over it. Nested, elsewhere or
120
+ // spelled otherwise, it is a dot-directory like any other, and the file-name
121
+ // rule still applies.
114
122
  function promptSurface(path) {
115
123
  const parts = path.split("/");
116
- for (const dir of parts.slice(0, -1)) {
124
+ const dirs = parts.length === 2 && parts[0] === RECORDS_DIR ? [] : parts.slice(0, -1);
125
+ for (const dir of dirs) {
117
126
  if (dir.startsWith(".") || PROMPT_DIRS.has(dir.toLowerCase())) return `prompt surface: directory ${dir}`;
118
127
  }
119
128
  const file = parts.at(-1).toLowerCase();
@@ -2,7 +2,7 @@
2
2
  // Which lines would merging this head remove that `main` gained after the
3
3
  // PR's work began — the main-gain check, read-only.
4
4
  //
5
- // main-gain.mjs --head <sha> [--base <ref>] [--body-file <path|->]
5
+ // main-gain.mjs --head <sha> [--base <ref>] [--body-file <path|->] [--closing-refs <path>]
6
6
  //
7
7
  // Reads the repository at the cwd. `--head` is a full commit SHA; `--base`
8
8
  // defaults to `origin/main` and is spelled the way no-undo-audit.sh takes its
@@ -10,6 +10,12 @@
10
10
  // full `refs/remotes/` path before any read so a local tag or branch literally
11
11
  // named `origin/main` cannot answer for it. `--body-file` is the PR body
12
12
  // (`-` reads stdin); omitted, the body is empty and nothing is acknowledged.
13
+ // `--closing-refs` is a file holding the JSON object `gh pr view <pr> --json
14
+ // number,url,closingIssuesReferences` prints; the references in this PR's own
15
+ // repository (`ownClosingIssues`, a pure function, so no `gh` call here) are the
16
+ // issues the PR closes, echoed as `closes`. Absent, unreadable, or a reference
17
+ // that cannot be placed: `closes` is `null` and the retraction rule below is
18
+ // off, so there are more hits, never fewer.
13
19
  // It never fetches, writes or changes refs: the caller fetches first.
14
20
  //
15
21
  // The reference point R is the earliest author date among the PR's own
@@ -36,9 +42,21 @@
36
42
  // each added line claims at most one. A token is a run of letters, digits or
37
43
  // underscores, or else one other character that is not whitespace, so
38
44
  // appending a name to an import is an in-place edit and dropping one is not.
39
- // Binary files cannot be read line by line and are listed in `unchecked[]`
40
- // instead of blocking. A merge-tree that reports conflicts is a head that
41
- // cannot merge as it stands, which is no answer about its content.
45
+ //
46
+ // Two more rules clear what in-place pairing leaves, hunk by hunk, for a hunk
47
+ // that adds at least one line; tokens never cross hunks. The hunk rule: the
48
+ // token multiset of every removed line of the hunk that is not a move (gained
49
+ // and older lines alike, a blank line being one blank token) is contained in
50
+ // that of every added line not spent on a move, claimed lines included, so a
51
+ // re-wrap that keeps every token clears. The retraction rule, when the hunk rule
52
+ // fails: a forward reference in the removed tokens (`once #N lands` and the
53
+ // like, read across lines) naming only issues the PR closes is dropped from the
54
+ // removed side, and the one token after it may differ from an added token in
55
+ // case alone; if what remains is contained, the hunk clears. A hunk that only
56
+ // removes lines is never cleared by either rule. Binary files cannot be read
57
+ // line by line and are listed in `unchecked[]` instead of blocking. A
58
+ // merge-tree that reports conflicts is a head that cannot merge as it stands,
59
+ // which is no answer about its content.
42
60
  //
43
61
  // Each hit carries a landing key: `#<n>` when the landing commit's subject is
44
62
  // GitHub's merge subject for PR n, otherwise that commit's 12-character
@@ -47,15 +65,26 @@
47
65
  // with an empty reason does not count. Acknowledged hits move from `hits[]`
48
66
  // to `acknowledged[]` and both are reported.
49
67
  //
50
- // Stdout: one JSON line, `{head, base, since, hits, acknowledged, edited,
51
- // unchecked, reason}`, `since` being R as an ISO timestamp. Each hit is `{path,
52
- // key, landed, lines: [{line, text, kind}], ack}`, `path` the file's name on
68
+ // Stdout: one JSON line, `{head, base, closes, since, hits, acknowledged,
69
+ // edited, unchecked, reason}`, `since` being R as an ISO timestamp and `closes`
70
+ // the PR's own closing issue numbers or `null`. Each hit is `{path, key,
71
+ // landed, lines: [{line, text, kind}], hunks, ack}`, `path` the file's name on
53
72
  // `<base>` and `ack` the body line to copy, reason left for the author to
54
73
  // write. `kind` is `modified` when the hunk that removed the line also adds
55
- // lines, and `deleted` when it only removes them. `edited` lists the gained
56
- // lines an in-place edit kept, as `{path, line, text, replacement}`, the
57
- // `replacement` being the added line that holds their tokens. An edited line is
58
- // not a hit and needs no acknowledgement.
74
+ // lines, and `deleted` when it only removes them. `hunks` has one entry per
75
+ // hunk holding any of the hit's lines, `{lines: [line numbers], added: [the
76
+ // added lines the removed tokens were compared against], missing: [[token,
77
+ // count], ...]}`: the removed tokens those added lines do not carry, with
78
+ // counts, in order of first appearance, case-sensitive, a blank line's token
79
+ // written "\n"; a hunk with no added lines has `added: []` and no `missing`.
80
+ // `edited` lists the gained lines cleared as not removed, as `{path, line,
81
+ // text, replacement, rule}`. `rule` `line` is an in-place edit, one entry per
82
+ // line, `replacement` being the added line that holds its tokens. `hunk` and
83
+ // `retracted #N` (every closing number the removed phrases named, space
84
+ // separated) are one entry per cleared hunk: `line` is the first cleared gained
85
+ // line, `text` the cleared gained lines joined with "\n", `replacement` the
86
+ // added lines compared against, joined with "\n". An edited line is not a hit
87
+ // and needs no acknowledgement.
59
88
  //
60
89
  // 0 clean, or every hit acknowledged
61
90
  // 1 at least one unacknowledged hit reason main-gain-removed:<first path>
@@ -66,19 +95,21 @@
66
95
  import { spawnSync } from "node:child_process";
67
96
  import { readFileSync } from "node:fs";
68
97
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
98
+ import { ownClosingIssues } from "./closing-refs.mjs";
69
99
  import { gitEnv } from "./git-env.mjs";
70
100
 
71
101
  const NAME = "main-gain";
72
102
  const die = makeDie(NAME);
73
103
  const { arg, sweep, stray } = defineFlags(die, {
74
- flags: { head: "value", base: "value", "body-file": "value" },
104
+ flags: { head: "value", base: "value", "body-file": "value", "closing-refs": "value" },
75
105
  });
76
106
 
77
- const USAGE = "usage: main-gain.mjs --head <sha> [--base <ref>] [--body-file <path|->]";
107
+ const USAGE = "usage: main-gain.mjs --head <sha> [--base <ref>] [--body-file <path|->] [--closing-refs <path>]";
78
108
 
79
109
  const headArg = arg("head");
80
110
  const base = arg("base") ?? "origin/main";
81
111
  const bodyFile = arg("body-file");
112
+ const closingRefsFile = arg("closing-refs");
82
113
  if (headArg === null) die(USAGE);
83
114
  sweep();
84
115
  stray();
@@ -97,6 +128,20 @@ if (bodyFile !== null) {
97
128
  }
98
129
  }
99
130
 
131
+ // The issue numbers this PR closes in its own repository, or `null` for no
132
+ // answer: the retraction rule is then off. Unreadable, unparsable and
133
+ // unplaceable all read the same, which is more hits, never fewer.
134
+ function closingIssues() {
135
+ if (closingRefsFile === null) return null;
136
+ try {
137
+ const pr = JSON.parse(readFileSync(closingRefsFile, "utf8"));
138
+ return ownClosingIssues(pr.number, pr.url, pr.closingIssuesReferences);
139
+ } catch {
140
+ return null;
141
+ }
142
+ }
143
+ const closes = closingIssues();
144
+
100
145
  // LC_ALL=C: the `Binary files … differ` line below is read by its text.
101
146
  // GIT_LITERAL_PATHSPECS: a path is a name here, never a glob or magic.
102
147
  const ENV = gitEnv({ LC_ALL: "C", GIT_LITERAL_PATHSPECS: "1" });
@@ -172,11 +217,7 @@ function fileDiff(tree, oldPath, newPath) {
172
217
  // The tokens an in-place edit keeps: a run of letters, digits or underscores is
173
218
  // one token, and each other character that is not whitespace is one.
174
219
  const TOKEN = /[\p{L}\p{N}_]+|[^\s\p{L}\p{N}_]/gu;
175
- function tokensOf(text) {
176
- const counts = new Map();
177
- for (const t of text.match(TOKEN) ?? []) counts.set(t, (counts.get(t) ?? 0) + 1);
178
- return counts;
179
- }
220
+ const tokensOf = (text) => countOf(text.match(TOKEN) ?? []);
180
221
 
181
222
  // Each unclaimed added line of one hunk claims at most one removed line of that
182
223
  // hunk. Removed lines choose in turn, most tokens first so a short line does not
@@ -207,6 +248,104 @@ function claimInPlace(removed, added) {
207
248
  }
208
249
  }
209
250
 
251
+ // The hunk rules read a hunk's lines as token streams, where a blank or
252
+ // whitespace-only line is one blank token, which no real token can equal.
253
+ const BLANK = "\n";
254
+ const streamOf = (lines) => lines.flatMap((text) => text.match(TOKEN) ?? [BLANK]);
255
+
256
+ function countOf(stream) {
257
+ const counts = new Map();
258
+ for (const t of stream) counts.set(t, (counts.get(t) ?? 0) + 1);
259
+ return counts;
260
+ }
261
+
262
+ // `[token, count]` for each removed token the added tokens carry fewer of, in
263
+ // order of first appearance in the removed stream, the count being the shortfall.
264
+ function shortfall(removed, have) {
265
+ const out = [];
266
+ for (const [t, n] of countOf(removed)) {
267
+ const lack = n - (have.get(t) ?? 0);
268
+ if (lack > 0) out.push([t, lack]);
269
+ }
270
+ return out;
271
+ }
272
+
273
+ // The forward references a PR may retract. The patterns run over the tokens
274
+ // joined by single spaces, case-insensitively, and each match must begin and
275
+ // end on a token boundary.
276
+ const ID = "(?:`\\s)?#\\s\\d+(?:\\s`)?";
277
+ const IDS = `${ID}(?:\\s(?:and|,|/|&)\\s${ID})*`;
278
+ const RETRACTION = new RegExp(
279
+ "(?<=^|\\s)(?:" +
280
+ `(?:written\\s)?(?:once|until|when|after|pending)\\s${IDS}\\s(?:lands?|ships?|merges?|is\\sbuilt)(?:\\s,)?` +
281
+ `|pending\\s${ID}\\s,\\snot\\syet\\sbuilt` +
282
+ `|${IDS}\\s(?:are\\s)?still\\sto\\sland` +
283
+ ")(?=\\s|$)",
284
+ "gi",
285
+ );
286
+
287
+ // `{start, end, numbers}` for each phrase in `stream` that names only issues in
288
+ // `closes` — token indices, `end` exclusive — in stream order.
289
+ function retractions(stream, closes) {
290
+ const starts = [];
291
+ let joined = "";
292
+ for (const t of stream) {
293
+ if (joined !== "") joined += " ";
294
+ starts.push(joined.length);
295
+ joined += t === BLANK ? "\0" : t;
296
+ }
297
+ const mine = new Set(closes.map(String));
298
+ const found = [];
299
+ for (const m of joined.matchAll(RETRACTION)) {
300
+ const numbers = [...m[0].matchAll(/#\s(\d+)/g)].map((n) => n[1]);
301
+ if (!numbers.every((n) => mine.has(n))) continue;
302
+ const first = starts.indexOf(m.index);
303
+ let end = first;
304
+ while (end < stream.length && starts[end] < m.index + m[0].length) end++;
305
+ found.push({ start: first, end, numbers });
306
+ }
307
+ return found;
308
+ }
309
+
310
+ // Takes the tokens of `stream` off `have` (mutating it), each exactly; false
311
+ // when one is not there as often as the stream holds it.
312
+ function consume(stream, have) {
313
+ for (const t of stream) {
314
+ const n = have.get(t) ?? 0;
315
+ if (n === 0) return false;
316
+ have.set(t, n - 1);
317
+ }
318
+ return true;
319
+ }
320
+
321
+ // The hunk rule, then the retraction rule, on one hunk's removed and added
322
+ // lines: the rule name when no gained line of the hunk is a hit, else `null`.
323
+ // A hunk that adds nothing is never cleared.
324
+ function clearsHunk(removed, added, closes) {
325
+ if (added.length === 0) return null;
326
+ const gone = streamOf(removed);
327
+ const have = countOf(streamOf(added));
328
+ if (shortfall(gone, have).length === 0) return "hunk";
329
+ if (closes === null) return null;
330
+ const phrases = retractions(gone, closes);
331
+ if (phrases.length === 0) return null;
332
+ const dropped = new Set();
333
+ for (const { start, end } of phrases) for (let i = start; i < end; i++) dropped.add(i);
334
+ const after = new Set(phrases.map((p) => p.end).filter((i) => i < gone.length && !dropped.has(i)));
335
+ const rest = gone.filter((_, i) => !dropped.has(i) && !after.has(i));
336
+ if (!consume(rest, have)) return null;
337
+ // The token after a retracted phrase may differ from an added one in case
338
+ // alone; only after every other token has had its exact match.
339
+ for (const i of [...after].sort((a, b) => a - b)) {
340
+ const t = gone[i];
341
+ const key = (have.get(t) ?? 0) > 0 ? t : [...have.keys()].find((u) => have.get(u) > 0 && u.toLowerCase() === t.toLowerCase());
342
+ if (key === undefined) return null;
343
+ have.set(key, have.get(key) - 1);
344
+ }
345
+ const named = [...new Set(phrases.flatMap((p) => p.numbers))];
346
+ return `retracted ${named.map((n) => `#${n}`).join(" ")}`;
347
+ }
348
+
210
349
  // line number on `<base>` → {sha, time, summary} for the requested lines,
211
350
  // which arrive in ascending order; consecutive ones share one `-L` range.
212
351
  function blame(path, lines) {
@@ -289,7 +428,7 @@ function check() {
289
428
  const twins = new Map();
290
429
  d.hunks.forEach((h, hunk) => {
291
430
  for (const text of h.added) {
292
- const a = { text, claimed: false, tokens: null };
431
+ const a = { text, moved: false, claimed: false, tokens: null };
293
432
  addsByHunk[hunk].push(a);
294
433
  if (!twins.has(text)) twins.set(text, []);
295
434
  twins.get(text).push(a);
@@ -300,7 +439,9 @@ function check() {
300
439
  for (const { line, text } of h.removed) {
301
440
  const spare = twins.get(text);
302
441
  if (spare?.length) {
303
- spare.pop().claimed = true;
442
+ const twin = spare.pop();
443
+ twin.moved = true;
444
+ twin.claimed = true;
304
445
  continue;
305
446
  }
306
447
  const kind = h.added.length > 0 ? "modified" : "deleted";
@@ -308,23 +449,53 @@ function check() {
308
449
  }
309
450
  });
310
451
  d.hunks.forEach((_, hunk) => claimInPlace(candsByHunk[hunk], addsByHunk[hunk]));
452
+ if (candsByHunk.every((cs) => cs.length === 0)) continue;
311
453
  const cands = candsByHunk.flat();
312
- if (cands.length === 0) continue;
313
454
  const blamed = blame(oldPath, cands);
314
455
  const byKey = new Map();
315
- for (const c of cands) {
316
- const b = blamed.get(c.line);
317
- if (b.time <= since) continue;
318
- if (c.replacement !== null) {
319
- edited.push({ path: oldPath, line: c.line, text: c.text, replacement: c.replacement });
320
- continue;
456
+ d.hunks.forEach((h, hunk) => {
457
+ const compared = addsByHunk[hunk].filter((a) => !a.moved).map((a) => a.text);
458
+ const gained = [];
459
+ for (const c of candsByHunk[hunk]) {
460
+ if (blamed.get(c.line).time <= since) continue;
461
+ if (c.replacement !== null) {
462
+ edited.push({ path: oldPath, line: c.line, text: c.text, replacement: c.replacement, rule: "line" });
463
+ } else {
464
+ gained.push(c);
465
+ }
321
466
  }
322
- const key = landingKey(b.sha, b.summary);
323
- if (!byKey.has(key)) {
324
- byKey.set(key, { path: oldPath, key, landed: b.sha, lines: [], ack: `main-gain-removal: ${oldPath} ${key} - <why>` });
467
+ if (gained.length === 0) return;
468
+ const removed = candsByHunk[hunk].map((c) => c.text);
469
+ const cleared = clearsHunk(removed, compared, closes);
470
+ if (cleared !== null) {
471
+ edited.push({
472
+ path: oldPath,
473
+ line: gained[0].line,
474
+ text: gained.map((c) => c.text).join("\n"),
475
+ replacement: compared.join("\n"),
476
+ rule: cleared,
477
+ });
478
+ return;
325
479
  }
326
- byKey.get(key).lines.push({ line: c.line, text: c.text, kind: c.kind });
327
- }
480
+ const missing = h.added.length > 0 ? shortfall(streamOf(removed), countOf(streamOf(compared))) : null;
481
+ // This hunk's diagnosis for each landing key, made once.
482
+ const diagnoses = new Map();
483
+ for (const c of gained) {
484
+ const b = blamed.get(c.line);
485
+ const key = landingKey(b.sha, b.summary);
486
+ if (!byKey.has(key)) {
487
+ byKey.set(key, { path: oldPath, key, landed: b.sha, lines: [], hunks: [], ack: `main-gain-removal: ${oldPath} ${key} - <why>` });
488
+ }
489
+ const hit = byKey.get(key);
490
+ hit.lines.push({ line: c.line, text: c.text, kind: c.kind });
491
+ if (!diagnoses.has(key)) {
492
+ const diagnosis = missing === null ? { lines: [], added: compared } : { lines: [], added: compared, missing };
493
+ diagnoses.set(key, diagnosis);
494
+ hit.hunks.push(diagnosis);
495
+ }
496
+ diagnoses.get(key).lines.push(c.line);
497
+ }
498
+ });
328
499
  hits.push(...byKey.values());
329
500
  }
330
501
  }
@@ -357,5 +528,5 @@ try {
357
528
  result = { since: null, hits: [], acknowledged: [], edited: [], unchecked: [], reason: e.message, unknown: true };
358
529
  }
359
530
  const { unknown, ...payload } = result;
360
- writeAll(1, `${JSON.stringify({ head, base, ...payload })}\n`);
531
+ writeAll(1, `${JSON.stringify({ head, base, closes, ...payload })}\n`);
361
532
  process.exit(unknown ? 2 : payload.hits.length ? 1 : 0);
@@ -4,16 +4,16 @@
4
4
  // merge-gate.mjs --pr <n> --pre <sha> [--post <sha>] [--out <path>]
5
5
  //
6
6
  // Runs, in order, `instruments.sh --repo <main checkout>`, `gh pr view <n>
7
- // --json labels,reviewDecision,headRefOid,body`, `main-gain.mjs` against the
8
- // PR head in the main checkout, and `ci-state.mjs --pr <n> --declare-no-ci`,
9
- // then answers the conjunction. All four run on every call, whatever the
10
- // earlier ones said — except main-gain.mjs, which needs the head and body gh
11
- // read and the main checkout, and is skipped when either could not be had — so
12
- // the JSON line carries every field that was read. A head gh reads outside
13
- // {pre, post} adds one more read, the rebase-carry proof below, in the main
14
- // checkout. It never merges, labels, rebases or waits: the merge bot runs it
15
- // once before any wait and once immediately before `gh pr merge`, and merges
16
- // only on that second exit 0.
7
+ // --json labels,reviewDecision,headRefOid,body,url,closingIssuesReferences`,
8
+ // `main-gain.mjs` against the PR head in the main checkout, and `ci-state.mjs
9
+ // --pr <n> --declare-no-ci`, then answers the conjunction. All four run on
10
+ // every call, whatever the earlier ones said — except main-gain.mjs, which
11
+ // needs the head and body gh read and the main checkout, and is skipped when
12
+ // either could not be had — so the JSON line carries every field that was
13
+ // read. A head gh reads outside {pre, post} adds one more read, the
14
+ // rebase-carry proof below, in the main checkout. It never merges, labels,
15
+ // rebases or waits: the merge bot runs it once before any wait and once
16
+ // immediately before `gh pr merge`, and merges only on that second exit 0.
17
17
  //
18
18
  // `--pre` is the labelled head, `--post` the head the bot's own
19
19
  // `gh pr update-branch --rebase` produced; omitted, it is `--pre` (the
@@ -31,14 +31,14 @@
31
31
  // `bodyDigest`), or null with `head` when gh could not be read, `rebaseCarry`
32
32
  // naming the labelled head and the head accepted as carrying it (`{labelled,
33
33
  // accepted}`), or null when no carry was proven, `mainGain` echoing
34
- // main-gain.mjs's own payload — hits, acknowledged removals, edited lines and unchecked
35
- // files — or null when it did not run or printed no JSON object; an unusable
36
- // payload is still echoed. Stderr: the children's own diagnostics, passed
37
- // straight through and never folded into stdout. A refusal (exit 2 with its
38
- // reason on stderr: a usage error, a Label map that cannot be read — see THE
39
- // LABEL MAP below — an `--out` that cannot be written, a gate that failed)
40
- // prints no JSON line, and one made before any child runs writes no `--out`
41
- // file.
34
+ // main-gain.mjs's own payload — hits, acknowledged removals, edited lines, the
35
+ // closing issues it read and unchecked files — or null when it did not run or
36
+ // printed no JSON object; an unusable payload is still echoed. Stderr: the
37
+ // children's own diagnostics, passed straight through and never folded into
38
+ // stdout. A refusal (exit 2 with its reason on stderr: a usage error, a Label
39
+ // map that cannot be read — see THE LABEL MAP below — an `--out` that cannot
40
+ // be written, a gate that failed) prints no JSON line, and one made before any
41
+ // child runs writes no `--out` file.
42
42
  //
43
43
  // Exit vocabulary — the same three-way contract as inflight.sh, prove-merge.sh
44
44
  // and staleness.mjs:
@@ -94,7 +94,8 @@
94
94
 
95
95
  import { spawnSync } from "node:child_process";
96
96
  import { createHash } from "node:crypto";
97
- import { mkdirSync, writeFileSync } from "node:fs";
97
+ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
98
+ import { tmpdir } from "node:os";
98
99
  import { dirname, join } from "node:path";
99
100
  import { fileURLToPath } from "node:url";
100
101
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
@@ -271,7 +272,7 @@ function readInstruments() {
271
272
  // null for anything that is not the four fields in their gh shapes: a parse
272
273
  // that succeeds on the wrong shape must not reach a check that reads it.
273
274
  function readPr() {
274
- const r = spawnSync("gh", ["pr", "view", String(pr), "--json", "labels,reviewDecision,headRefOid,body"], CHILD);
275
+ const r = spawnSync("gh", ["pr", "view", String(pr), "--json", "labels,reviewDecision,headRefOid,body,url,closingIssuesReferences"], CHILD);
275
276
  if (r.error || r.status !== 0) return null;
276
277
  let v;
277
278
  try {
@@ -286,14 +287,18 @@ function readPr() {
286
287
  if (!Object.hasOwn(v, "reviewDecision") || (v.reviewDecision !== null && typeof v.reviewDecision !== "string")) return null;
287
288
  if (typeof v.headRefOid !== "string" || !/^[0-9a-f]{40}$/.test(v.headRefOid)) return null;
288
289
  // The body carries the main-gain acknowledgements. gh answers `""` for an
289
- // empty one, so a missing field is a read that did not happen.
290
+ // empty one, so a missing field is a read that did not happen. `url` and
291
+ // `closingIssuesReferences` are main-gain.mjs's to read: it takes them as gh
292
+ // printed them, and without them the retraction rule is off.
290
293
  if (typeof v.body !== "string") return null;
291
294
  return v;
292
295
  }
293
296
 
294
297
  // --- main-gain.mjs --------------------------------------------------------
295
298
  // Against the head gh just read, in the main checkout, with the body on
296
- // stdin. Not run without both, and its row then stays silent:
299
+ // stdin and the PR's number, url and closing references, as gh printed them,
300
+ // in a file of their own. Not run without both head and body, and its row then
301
+ // stays silent:
297
302
  // instruments-unanswerable or pr-unreadable names the missing input. As with
298
303
  // ci-state below, the payload decides and the exit code has to agree with
299
304
  // it — exit 0 with a hit, or exit 1 without one, is not a verdict. `payload`
@@ -302,15 +307,26 @@ function readPr() {
302
307
  // `usable`.
303
308
  function readMainGain(root, prView) {
304
309
  if (root === null || prView === null) return { usable: false, exit: null, payload: null };
310
+ // A refs file that cannot be written leaves the retraction rule off: more
311
+ // hits, never fewer.
312
+ let scratch = null;
313
+ const refsArgs = [];
314
+ try {
315
+ scratch = mkdtempSync(join(tmpdir(), "merge-gate-"));
316
+ const refs = join(scratch, "closing-refs.json");
317
+ writeFileSync(refs, JSON.stringify({ number: pr, url: prView.url, closingIssuesReferences: prView.closingIssuesReferences }));
318
+ refsArgs.push("--closing-refs", refs);
319
+ } catch {}
305
320
  const r = spawnSync(
306
321
  process.execPath,
307
- [join(SCRIPT_DIR, "main-gain.mjs"), "--head", prView.headRefOid, "--body-file", "-"],
322
+ [join(SCRIPT_DIR, "main-gain.mjs"), "--head", prView.headRefOid, "--body-file", "-", ...refsArgs],
308
323
  // A PR that removes a large main-gained file prints every removed line:
309
324
  // past spawnSync's 1 MiB default the read fails ENOBUFS and the verdict
310
325
  // that PR earned reads as unanswerable. main-gain.mjs's own git reads
311
326
  // carry the same 1 GiB bound.
312
327
  { ...CHILD, stdio: ["pipe", "pipe", "inherit"], cwd: root, input: prView.body, maxBuffer: 1 << 30 },
313
328
  );
329
+ if (scratch !== null) rmSync(scratch, { recursive: true, force: true });
314
330
  if (r.error) writeAll(2, `merge-gate: main-gain.mjs could not be read: ${r.error.code ?? r.error.message}\n`);
315
331
  let v = null;
316
332
  try {
@@ -790,7 +790,7 @@ and flag the PR for a human. A new review of the PR counts again from none.
790
790
 
791
791
  | Failure | Response |
792
792
  |---|---|
793
- | Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | Relay `main-gain-removed:<path>-#<pr>` to a human with the hit list and the acknowledgement keys the bot printed. PR stays queued, label untouched, and no member is dispatched to restore the lines — the removal may be deliberate. `fleet-event.mjs merge-bot-report` parks it: a `parked=<head>:<body digest>:<reason>` token on its row, at the head and body digest the bot's gate reading `<scratch>/pr<pr>/merge-bot-<n>/ci.json` records it refused, and no bot is dispatched on its account — when nothing else queued is dispatchable the tick prints `HOLD (parked #<pr> <reason>)`, though a bot dispatched for another queued PR may still evaluate it again; a new head or an edited body lifts the park with no write. A hit line's `kind` is `modified` when its hunk also adds lines, `deleted` when it only removes lines; a gained line edited in place keeping every token is listed in `mainGain.edited[]`, not a hit. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
793
+ | Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | In the same turn, read each hit group's `hunks[]` from the bot's gate reading `<scratch>/pr<pr>/merge-bot-<n>/ci.json` — each hunk's `added` lines and `missing` tokens (a blank line is `"\n"`). Draft one `main-gain-removal: <path> <key> - <why>` line per path and key, with a concrete reason, and put one yes/no question to the maintainer quoting each hunk's `missing`. Never write the line without the maintainer's yes. On yes, append the lines to the PR body with `gh pr edit <pr> --body-file <file>` and record `ledger.mjs ruled <pr> main-gain: deliberate - <the main-gain-removal line>` for each; the edited body lifts the park. On no, the PR stays parked: record `ledger.mjs ruled <pr> main-gain: not deliberate - <the maintainer's instruction>` and carry it out — there is no standing restore procedure, and no member restores lines unless the maintainer says so. A re-park naming the same set of path-and-key pairs as a question already put on that PR is that same question: do not ask again, and if the maintainer said yes and the line has left the PR body, restore it from the `ruled` record without asking. `fleet-event.mjs merge-bot-report` parks it (references/ledger.md). It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
794
794
  | Merge bot's gate cannot answer the main-gain check (`main-gain-unanswerable`, exit 2) | Report `main-gain-unanswerable-#<pr>` with what it printed, PR stays queued, label untouched |
795
795
 
796
796
  ## Failure handling
@@ -226,10 +226,14 @@ prompt surface) or only of the run-metrics files. The finisher does not decide
226
226
  that by reading the diff: the script reads it, and only its exit 0 skips the
227
227
  mutation. An exit 1 is not overridden, and an exit 2 is never read as a 0.
228
228
 
229
- The prompt surface stays out of prose. A `.md` under a `skills`, `agents`,
230
- `commands` or `plugin` directory or under any dot-directory (`.omp/rules`,
229
+ The prompt surface stays out of prose. A `.md` under a `skills`, `agents` or
230
+ `commands` directory or under any dot-directory (`.omp/rules`,
231
231
  `.omp/RULES.md`, `.claude`), and any `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`, is
232
- read by the harness, so it can change behavior. A symlink, submodule, mode
232
+ read by the harness, so it can change behavior. The one exception is a file
233
+ directly in the root `.out-of-scope/`, spelled exactly so: a rejection record
234
+ the triage skill writes, read as settled precedent, so it is prose unless it is
235
+ named `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`. Nested or elsewhere,
236
+ `.out-of-scope` is a dot-directory like any other. A symlink, submodule, mode
233
237
  change or other non-regular entry is a code change whatever its name, so it is
234
238
  not prose either. The verdict is read at the dispatch pin: the worktree's own
235
239
  head is not part of it, and duty 1 audits that head separately.
@@ -100,6 +100,8 @@ A member that dies between spawn and write is invisible — and members die in b
100
100
 
101
101
  `parked=<head>:<body digest>:main-gain-removed:<path>` is a row token too, written by `fleet-event.mjs merge-bot-report` off a merge bot's `main-gain-removed` refusal, binding the head and a digest of the body the bot's gate refused, read from its gate reading `<scratch>/pr<N>/merge-bot-<n>/ci.json`: while both still match, the tick counts the PR parked beside the held ones, so it alone never prints `DISPATCH merge-bot`, and a new head or an edited body lifts it with no write. No other refusal reason parks.
102
102
 
103
+ PR stays queued, label untouched, and no member is dispatched to restore the lines — the removal may be deliberate. A hit line's `kind` is `modified` when its hunk also adds lines, `deleted` when it only removes lines; a gained line cleared by in-place pairing, a token-keeping re-wrap of its hunk or the retraction of a forward reference to a ticket the PR closes is in `mainGain.edited[]` with its `rule`, not a hit. The `ruled` record the main-gain-hit row restores an acknowledgement from lasts only the run that wrote it — `ledger.mjs rotate` carries no `ruled` line into the next ledger — so a later run puts the question again.
104
+
103
105
  ## The review pair on a PR's row
104
106
 
105
107
  A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`.