@feigi/fleet-ctl 3.142.0 → 3.143.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/scripts/reap.sh CHANGED
@@ -442,8 +442,10 @@ keep() {
442
442
  # silent (measured on this exact shape).
443
443
  #
444
444
  # The capture is `probe`, over any command; `git_probe` is `probe git`.
445
- # pr_load's gh call below is the one other caller: its stdout fields are
446
- # refnames, numbers, object ids and fixed words, none of which can hold 0x02.
445
+ # pr_load's gh call below is a caller too: its stdout fields are refnames,
446
+ # numbers, object ids and fixed words, none of which can hold 0x02. So are the
447
+ # pair test's `pq_ids`, which prints `git patch-id`'s hex pairs and nothing
448
+ # else, and its `pq_marked`, which prints object ids and nothing else.
447
449
  gp_sep=$(printf '\002')
448
450
  probe() {
449
451
  gp_raw=$(
@@ -998,6 +1000,141 @@ EOF
998
1000
  return 1
999
1001
  }
1000
1002
 
1003
+ # THE PAIR TEST. `git cherry` reads a commit as merged when $base carries a
1004
+ # commit with the same patch id, and a patch id ignores where in a file the
1005
+ # change sits and any whitespace in it. So a commit making a merged change
1006
+ # again at another place in the same file — the second of two identical
1007
+ # blocks — or differing from a merged commit only in whitespace reads `-`
1008
+ # although no other ref holds it. Measured, git 2.54.0 (Apple Git-157): a
1009
+ # claim's first commit squash-merged, its second, never pushed, making the
1010
+ # same change in the file's identical second block — `git cherry` prints `-`
1011
+ # for both.
1012
+ #
1013
+ # So where no line reads `+`, the tip is merged only when every commit in
1014
+ # $base_rev..tip also pairs: some commit M on $base carries its patch id
1015
+ # (`git patch-id --stable`), and `git merge-tree --write-tree --merge-base=C^
1016
+ # M^ C` writes exactly M's tree — C replayed onto M's parent is M. Anything
1017
+ # less is a KEEP with its reason: a merge commit in the range (`git cherry`
1018
+ # skips merges, so what a merge itself changes is read by nothing), a commit
1019
+ # no M carries the patch id of (an empty commit has none: a false keep, and a
1020
+ # harmless one), a replay that differs from or conflicts with every such M,
1021
+ # and any probe that fails. A `+` is not this test's: it keeps, or goes to the
1022
+ # second proof above, unchanged.
1023
+ #
1024
+ # M is looked for among the commits on $base that `git rev-list
1025
+ # --cherry-mark` marks `=` against this tip, so the diffs this script reads
1026
+ # are those commits' and the tip's own, never all of $base since the fork.
1027
+ # That listing itself still names every commit on $base since the fork, and
1028
+ # `probe` splits its capture with `${…#*sep}`, which bash 3.2 — macOS /bin/sh
1029
+ # — runs in time that grows faster than the capture: measured, doubling a
1030
+ # 1600-line capture took `probe` from 3.9s to 18.7s, and on a fork 3200
1031
+ # commits behind a dry run took 6.2s with the whole listing through `probe`
1032
+ # and 0.4s with the `=` ids alone, same payload. So
1033
+ # `pq_marked` keeps the listing to itself and prints only the `=` lines' ids,
1034
+ # and what reaches `probe` grows with the merged commits alone.
1035
+ # Safe for `probe`'s separator: rev-list and rev-parse print object ids and
1036
+ # fixed marks; merge-tree under `--no-messages --name-only` prints a tree id
1037
+ # and, on a conflict, the conflicted paths C-quoted (`"we\002ird"`, measured,
1038
+ # under core.quotePath false too); and `pq_ids` keeps the diff text, which can
1039
+ # hold any byte, to itself and prints only `git patch-id`'s hex pairs. Both of
1040
+ # its pipes read a variable, never git, so the status each returns is git's.
1041
+ # `pq_marked`'s pipe reads a variable too, and git's own status is taken
1042
+ # before it runs.
1043
+ # `merge-tree --write-tree` writes the trees it merges into the object store,
1044
+ # on a dry run too; it moves and deletes nothing.
1045
+ pq_ids() {
1046
+ pq_d=$(printf '%s\n' "$1" | git diff-tree --stdin -p) || return
1047
+ printf '%s\n' "$pq_d" | git patch-id --stable
1048
+ }
1049
+ pq_marked() {
1050
+ pq_l=$(git rev-list --cherry-mark --left-only --no-merges "$1") || return
1051
+ printf '%s\n' "$pq_l" | sed -n 's/^=//p'
1052
+ }
1053
+
1054
+ # Returns 0 when every commit on tip $1 that $base_rev lacks pairs, and 1 with
1055
+ # the reason in $pq_why when one does not or a probe fails.
1056
+ pair_test() {
1057
+ if ! git_probe rev-list --parents "$base_rev..$1"; then
1058
+ pq_why="pair test failed — cannot list the commits $base lacks$(gp_why)"
1059
+ return 1
1060
+ fi
1061
+ pq_cs=
1062
+ while read -r pq_c pq_p pq_more; do
1063
+ [ -n "$pq_c" ] || continue
1064
+ if [ -n "$pq_more" ]; then
1065
+ pq_why="commit $pq_c is a merge, and git cherry does not read what a merge itself changes"
1066
+ return 1
1067
+ elif [ -z "$pq_p" ]; then
1068
+ pq_why="commit $pq_c has no parent to replay it from"
1069
+ return 1
1070
+ fi
1071
+ pq_cs=${pq_cs:+$pq_cs
1072
+ }$pq_c
1073
+ done <<EOF
1074
+ $gp_out
1075
+ EOF
1076
+ [ -n "$pq_cs" ] || return 0
1077
+
1078
+ if ! probe pq_marked "$base_rev...$1"; then
1079
+ pq_why="pair test failed — cannot list the commits on $base to pair with$(gp_why)"
1080
+ return 1
1081
+ fi
1082
+ pq_ms=$gp_out
1083
+ pq_mids=
1084
+ if [ -n "$pq_ms" ]; then
1085
+ if ! probe pq_ids "$pq_ms"; then
1086
+ pq_why="pair test failed — cannot compute the patch ids of the commits on $base$(gp_why)"
1087
+ return 1
1088
+ fi
1089
+ pq_mids=$gp_out
1090
+ fi
1091
+ if ! probe pq_ids "$pq_cs"; then
1092
+ pq_why="pair test failed — cannot compute the patch ids of the commits $base lacks$(gp_why)"
1093
+ return 1
1094
+ fi
1095
+ pq_cids=$gp_out
1096
+
1097
+ for pq_c in $pq_cs; do
1098
+ pq_id=
1099
+ while read -r pq_i pq_o; do
1100
+ [ "$pq_o" != "$pq_c" ] || pq_id=$pq_i
1101
+ done <<EOF
1102
+ $pq_cids
1103
+ EOF
1104
+ pq_with=
1105
+ if [ -n "$pq_id" ]; then
1106
+ while read -r pq_i pq_o; do
1107
+ [ "$pq_i" != "$pq_id" ] || pq_with="$pq_with $pq_o"
1108
+ done <<EOF
1109
+ $pq_mids
1110
+ EOF
1111
+ fi
1112
+ if [ -z "$pq_with" ]; then
1113
+ pq_why="commit $pq_c reads patch-equivalent, but no commit on $base carries its patch id"
1114
+ return 1
1115
+ fi
1116
+ for pq_m in $pq_with; do
1117
+ if ! git_probe rev-parse --verify "$pq_m^{tree}"; then
1118
+ pq_why="pair test failed — cannot read the tree of $pq_m$(gp_why)"
1119
+ return 1
1120
+ fi
1121
+ pq_mt=$gp_out
1122
+ if git_probe merge-tree --write-tree --no-messages --name-only --merge-base="$pq_c^" "$pq_m^" "$pq_c"; then
1123
+ [ "$gp_out" != "$pq_mt" ] || continue 2
1124
+ elif [ "$gp_rc" -ne 1 ]; then
1125
+ pq_why="pair test failed — cannot replay commit $pq_c onto $pq_m^$(gp_why)"
1126
+ return 1
1127
+ fi
1128
+ done
1129
+ case "$pq_with" in
1130
+ *" "*" "*) pq_why="commit $pq_c reads patch-equivalent but is not identical to any of the merged commits$pq_with" ;;
1131
+ *) pq_why="commit $pq_c reads patch-equivalent but is not identical to the merged commit$pq_with" ;;
1132
+ esac
1133
+ return 1
1134
+ done
1135
+ return 0
1136
+ }
1137
+
1001
1138
  # %(upstream:track) emits exactly [gone] as its own field — nothing to
1002
1139
  # pattern-match, and no -v/-vv trap.
1003
1140
  #
@@ -1170,21 +1307,22 @@ for b in $gone_branches $nu_branches; do
1170
1307
  # verdict a genuinely clean cherry produces, so "merged" is indistinguishable
1171
1308
  # from "the probe could not answer". An unmerged branch is never the ambiguous
1172
1309
  # one: its `+` line makes grep exit 0 and always keeps. Of the checks that
1173
- # must pass before the delete, this is the only one that asks whether `$tip`
1174
- # is merged — the worktree checks below and the `worktree remove` refusal
1175
- # can each keep the branch, but none of them looks at its commits, and the
1176
- # compare-and-swap refuses a ref that moved off `$tip`, never a `$tip` that
1177
- # is unmerged — so an unanswerable probe must KEEP, the same fail-closed
1178
- # shape the worktree `status` check below already uses.
1310
+ # must pass before the delete, this and the pair test after it are the only
1311
+ # ones that ask whether `$tip` is merged — the worktree checks below and the
1312
+ # `worktree remove` refusal can each keep the branch, but none of them looks
1313
+ # at its commits, and the compare-and-swap refuses a ref that moved off
1314
+ # `$tip`, never a `$tip` that is unmerged — so an unanswerable probe must
1315
+ # KEEP, the same fail-closed shape the worktree `status` check below already
1316
+ # uses.
1179
1317
  # `refs/heads/$b`, never a bare `$b`, where the tip is read above. Restoring
1180
1318
  # the bare name makes a branch that shares its name with a tag ambiguous AS A
1181
1319
  # REV again, and git resolves an ambiguous one by preferring refs/tags/ over
1182
1320
  # refs/heads/ (measured, git 2.50.1 Apple Git-155). This probe would then
1183
1321
  # answer about the TAG's commit while the delete below removes the BRANCH —
1184
1322
  # and a tag sitting on a merged commit reports clean for a branch whose
1185
- # commits exist nowhere else. No other check before the delete asks whether
1186
- # those commits are merged, so that reads straight through to destroying
1187
- # them: measured on a fixture, the enumeration fix alone turned a branch
1323
+ # commits exist nowhere else. No other check before the delete then asked
1324
+ # whether those commits are merged, so that read straight through to
1325
+ # destroying them: measured on a fixture, the enumeration fix alone turned a branch
1188
1326
  # this script currently KEEPS into `REAPED`, at exit 0, with an empty
1189
1327
  # kept[]. Qualifying changes nothing for an ordinary branch — both spellings
1190
1328
  # name the same commit — and it is the same key the worktree lookup below
@@ -1198,8 +1336,8 @@ for b in $gone_branches $nu_branches; do
1198
1336
  # existed nowhere else REAPED at exit 0 with an empty kept[]. The
1199
1337
  # qualification is built at the top of the file, where its own comment
1200
1338
  # records why the accept-list beside it is what makes prefixing sound. Being
1201
- # the only merge check bounds what ELSE could catch an unmerged branch, not
1202
- # whether this check itself can be wrong — which is why BOTH revs it
1339
+ # one of only two merge checks bounds what ELSE could catch an unmerged
1340
+ # branch, not whether this check itself can be wrong — which is why BOTH revs it
1203
1341
  # consumes are qualified.
1204
1342
  elif ! cherry=$(git cherry "$base_rev" "$tip" 2>&1); then
1205
1343
  keep "$b" "cherry probe failed — cannot tell if merged: $(printf '%s' "$cherry" | tr '\n' ' ')"
@@ -1215,7 +1353,7 @@ for b in $gone_branches $nu_branches; do
1215
1353
  # exists for: taking it is not the same as READING it. grep answers three
1216
1354
  # ways, and the `if` once had two arms — an rc 2 scan that never
1217
1355
  # examined `$cherry` fell into the merged arm, and no check between here and
1218
- # the delete below asks whether the branch is merged. So the deletion went
1356
+ # the delete below then asked whether the branch is merged. So the deletion went
1219
1357
  # ahead on a merge status no tool had established. `grep_probe` splits the two
1220
1358
  # questions; the answers are ruled on here, in the order that makes the
1221
1359
  # unanswerable case fail CLOSED like every other could-not-check in this
@@ -1241,6 +1379,11 @@ for b in $gone_branches $nu_branches; do
1241
1379
  keep "$b" "unmerged commits — $pr_why"
1242
1380
  continue
1243
1381
  fi
1382
+ # No `+`: merged only if every commit the tip holds and $base lacks pairs
1383
+ # with one $base carries — the pair test, its header above the loop.
1384
+ elif ! pair_test "$tip"; then
1385
+ keep "$b" "$pq_why"
1386
+ continue
1244
1387
  fi
1245
1388
 
1246
1389
  # The listing is read per branch, through worktree.sh's `wt_counts`, which
@@ -1905,6 +2048,11 @@ else
1905
2048
  elif [ "$gq_rc" -eq 0 ]; then
1906
2049
  keep "" "worktree $wt holds commits that exist nowhere else"
1907
2050
  continue
2051
+ # No `+`: the pair test, as in the branch sweep; its header is above that
2052
+ # sweep's loop.
2053
+ elif ! pair_test "$head"; then
2054
+ keep "" "worktree $wt — $pq_why"
2055
+ continue
1908
2056
  fi
1909
2057
 
1910
2058
  if [ -e "$wt" ]; then
@@ -34,7 +34,16 @@
34
34
  // of them: a bot's token names no PR, and GitHub reads MERGED
35
35
  // while the bot is still writing under pr<M>/merge-bot-<n>/. An
36
36
  // OPEN PR's pr<M>/ is kept whole except its run-* roots, which
37
- // follow the --pr rule below.
37
+ // follow the --pr rule below. A MERGED PR's entry that holds
38
+ // review evidence — a `<run>/review.json` under pr<M>/, or a
39
+ // Charges file naming its run — is also kept until origin/main
40
+ // holds every file of it where run-records.mjs's reviewTargets()
41
+ // puts it, under docs/metrics/reviews/<M>/: the Close-out PR
42
+ // carries it there. `git ls-tree origin/main` in the checkout the
43
+ // ledger sits in answers that, once per sweep; a lookup that fails,
44
+ // or evidence that cannot be read, keeps the entry with that
45
+ // reason. A CLOSED PR gets no Ruling, and its entries keep the
46
+ // rule above.
38
47
  // impl-<N>/
39
48
  // removed when issue #N is CLOSED, or OPEN with no live
40
49
  // impl-<N>[-x] token, no claim worktree standing, and idle past
@@ -121,6 +130,7 @@ import { gitEnv } from "./git-env.mjs";
121
130
  import { ghAliasedRead, how } from "./gh-aliased-read.mjs";
122
131
  import { isCLI } from "./is-cli.mjs";
123
132
  import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
133
+ import { REVIEWS_DIR, reviewTargets } from "./run-records.mjs";
124
134
 
125
135
  const NAME = "reclaim-scratch";
126
136
  const die = makeDie(NAME);
@@ -269,6 +279,16 @@ function worktreeListing(checkout) {
269
279
  }
270
280
  }
271
281
 
282
+ // The paths origin/main holds under REVIEWS_DIR, as `{paths}`, or `{unknown}`
283
+ // naming why the checkout could not say. A missing origin/main is an unknown.
284
+ function evidenceOnMain(checkout) {
285
+ const r = spawnSync("git", ["ls-tree", "-r", "-z", "--name-only", "--full-tree", "origin/main", "--", `${REVIEWS_DIR}/`], {
286
+ cwd: checkout, encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv(),
287
+ });
288
+ if (r.error || r.status !== 0) return { unknown: `git ls-tree origin/main -- ${REVIEWS_DIR}/ failed (${how(r)})` };
289
+ return { paths: new Set(r.stdout.split("\0").filter(Boolean)) };
290
+ }
291
+
272
292
  // Whether a claim worktree stands for issue `n`: a listed worktree directly under
273
293
  // `.worktrees/` whose directory name names `n` as a whole segment, and whose
274
294
  // directory is still there. `{stands}` is true or false; `{unknown}`
@@ -329,7 +349,7 @@ function githubStates(numbers) {
329
349
  }
330
350
 
331
351
  // The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}]}`.
332
- function judgeRoot(root, names, live, now, listing) {
352
+ function judgeRoot(root, names, live, now, listing, checkout) {
333
353
  const cutoff = now - RETENTION_MS;
334
354
  const remove = [];
335
355
  const kept = [];
@@ -342,6 +362,22 @@ function judgeRoot(root, names, live, now, listing) {
342
362
  return r !== null && Number(r[1]) === n;
343
363
  });
344
364
  const implHolder = (n) => liveMembers.find((m) => m.family === "impl" && m.number === n)?.name;
365
+ // Why a MERGED PR's entry is kept for its review evidence, or null when it
366
+ // holds none origin/main lacks. origin/main is read once, on first need.
367
+ let onMain = null;
368
+ const evidenceHold = (path, name, n) => {
369
+ let found;
370
+ try {
371
+ found = reviewTargets(path, name);
372
+ } catch (e) {
373
+ return `PR #${n} is MERGED, and its review evidence cannot be read: ${e.code ?? e.message}`;
374
+ }
375
+ if (found.targets.length === 0) return null;
376
+ onMain ??= evidenceOnMain(checkout);
377
+ if (onMain.unknown !== undefined) return `PR #${n} is MERGED, but whether origin/main holds its review evidence cannot be told: ${onMain.unknown}`;
378
+ const missing = found.targets.filter((t) => !onMain.paths.has(t.to)).map((t) => t.to);
379
+ return missing.length === 0 ? null : `PR #${n} is MERGED, but origin/main does not hold its review evidence yet: ${missing.join(", ")}`;
380
+ };
345
381
 
346
382
  const byAge = (path, name, young) => {
347
383
  const holder = live.find((t) => name.includes(t));
@@ -437,7 +473,12 @@ function judgeRoot(root, names, live, now, listing) {
437
473
  continue;
438
474
  }
439
475
  const holder = prHolder(n);
440
- if (holder !== undefined) kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
476
+ if (holder !== undefined) {
477
+ kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
478
+ continue;
479
+ }
480
+ const held = s.state === "MERGED" ? evidenceHold(path, name, n) : null;
481
+ if (held !== null) kept.push({ path, reason: held });
441
482
  else remove.push({ path, reason: `PR #${n} is ${s.state}` });
442
483
  continue;
443
484
  }
@@ -600,7 +641,7 @@ function main() {
600
641
  die(`could not list --root ${root}: ${e.message}`);
601
642
  }
602
643
  const listing = worktreeListing(found.checkout);
603
- ({ remove, kept } = judgeRoot(root, names, live, now, listing));
644
+ ({ remove, kept } = judgeRoot(root, names, live, now, listing, found.checkout));
604
645
  }
605
646
 
606
647
  const removed = [];
@@ -1455,8 +1455,9 @@ else
1455
1455
  # update-ref, authorized by the `ahead` and `git cherry` guards above,
1456
1456
  # this recount, and the worktree check above — and carrying its own
1457
1457
  # compare-and-swap on $tip on top, which `-D` never had. reap.sh asks
1458
- # whether its own [gone] branches are merged with `git cherry` alone — no
1459
- # `ahead` count, no recount — so not this pairing, though it too
1458
+ # whether its own [gone] branches are merged with `git cherry` and a pair
1459
+ # test that replays each commit onto the one it matches — no `ahead`
1460
+ # count, no recount — so not this pairing, though it too
1460
1461
  # re-checks the worktree with `wt_holding` before its own compare-and-swap
1461
1462
  # delete. `-d` measures against HEAD and the branch's upstream, and a
1462
1463
  # claim has no upstream until its first push (claim-ticket.sh passes
@@ -0,0 +1,251 @@
1
+ // A run's records and each reviewed PR's review evidence, as files the
2
+ // Close-out PR commits under docs/metrics/ — the one place that names them.
3
+ //
4
+ // docs/metrics/runs/<stamp>/ledger.md, phase0.json, closeout.json,
5
+ // plugin-version
6
+ // docs/metrics/reviews/<pr>/<run>/review.json,
7
+ // dispositions-fix-pr-<pr>[-x].json
8
+ //
9
+ // `<stamp>` is the ledger archive's own (`ledger.<stamp>.md`, archiveStamp()
10
+ // in ledger-grammar.mjs), and the three files under it are the archives
11
+ // `ledger.mjs rotate` leaves beside the ledger: `ledger.<stamp>.md`,
12
+ // `phase0.<stamp>.json` and `closeout.<stamp>.json`. The phase-0 receipt is
13
+ // committed with its `recipe` step's output withheld: that output is the
14
+ // Recipe's command lines, and a command can carry an environment assignment,
15
+ // a secret among them. A phase-0 archive that cannot be read as JSON cannot be
16
+ // withheld from, so it is not committed. `plugin-version` is one line, the
17
+ // `pluginVersion` that run's phase-0 receipt recorded from the instruments
18
+ // pin; a receipt that records none gets no file. `<run>` is the review's run
19
+ // root (`run-` and eight characters), `<scratch>/pr<pr>/<run>/`, and a Charges
20
+ // file goes into the run its own `run` field names.
21
+ //
22
+ // isRunRecord() is the allowlist: the commit step stages only paths it
23
+ // accepts, as isPlainFile() files, finisher-scope.mjs classifies only those as
24
+ // data beside the metrics TSVs, and main-checkout.mjs leaves the plain files
25
+ // among them out of its snapshot as the run's own bookkeeping. A file of any
26
+ // other name under those directories — a recipe, a transcript, a brief — is
27
+ // never staged. reviewTargets() is the one mapping from a scratch entry to the
28
+ // paths its evidence is committed under: gather() copies along it, and
29
+ // reclaim-scratch.mjs keeps a merged PR's evidence until origin/main holds
30
+ // every one of them.
31
+ //
32
+ // Zero deps: node builtins and sibling scripts only.
33
+
34
+ import { chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
35
+ import { dirname, join } from "node:path";
36
+
37
+ export const RUNS_DIR = "docs/metrics/runs";
38
+ export const REVIEWS_DIR = "docs/metrics/reviews";
39
+ export const RECORD_DIRS = Object.freeze([RUNS_DIR, REVIEWS_DIR]);
40
+ export const PLUGIN_VERSION = "plugin-version";
41
+
42
+ const STAMP = "[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{6}Z";
43
+ const RUN_ROOT = /^run-[A-Za-z0-9]{8}$/;
44
+ const RUN_RECORD = new RegExp(`^${RUNS_DIR}/${STAMP}/(?:ledger\\.md|phase0\\.json|closeout\\.json|${PLUGIN_VERSION})$`);
45
+ const RUN_DIR = new RegExp(`^${RUNS_DIR}/(${STAMP})/`);
46
+ const REVIEW_RECORD = new RegExp(`^${REVIEWS_DIR}/([1-9][0-9]*)/run-[A-Za-z0-9]{8}/(?:review\\.json|dispositions-fix-pr-\\1(?:-[a-z])?\\.json)$`);
47
+ // The archives `ledger.mjs rotate` leaves beside the ledger, by stamp, and the
48
+ // name each takes under docs/metrics/runs/<stamp>/.
49
+ const ARCHIVE = new RegExp(`^(?:ledger\\.(${STAMP})\\.md|phase0\\.(${STAMP})\\.json|closeout\\.(${STAMP})\\.json)$`);
50
+ const PR_ENTRY = /^pr([1-9][0-9]*)$/;
51
+ const DISPOSITIONS_ENTRY = /^dispositions-fix-pr-([1-9][0-9]*)(?:-[a-z])?\.json$/;
52
+
53
+ /** Whether `path` (repository-relative, `/`-separated) is a run record or review evidence file the Close-out PR may commit. */
54
+ export const isRunRecord = (path) => RUN_RECORD.test(path) || REVIEW_RECORD.test(path);
55
+
56
+ // The lstat of `path` when it is a regular file — never a symlink's target —
57
+ // else null; an absent path is null, any other failure throws.
58
+ const fileStat = (path) => {
59
+ try {
60
+ const st = lstatSync(path);
61
+ return st.isFile() ? st : null;
62
+ } catch (e) {
63
+ if (e.code === "ENOENT") return null;
64
+ throw e;
65
+ }
66
+ };
67
+
68
+ const isFile = (path) => fileStat(path) !== null;
69
+
70
+ /** Whether `path` is a regular file with no executable bit: the only kind of run record a commit carries. */
71
+ export const isPlainFile = (path) => {
72
+ const st = fileStat(path);
73
+ return st !== null && (st.mode & 0o111) === 0;
74
+ };
75
+
76
+ /** What the committed phase-0 receipt holds in place of its `recipe` step's output. */
77
+ export const RECIPE_WITHHELD = "withheld: the Recipe's command lines can carry environment assignments";
78
+
79
+ /**
80
+ * The run records `fleetDir` holds: `{copies: [{from, to}], writes: [{to,
81
+ * text}], notes}`, `to` repository-relative. A phase-0 archive is written with
82
+ * its `recipe` step's output withheld, and one that cannot be read as JSON is
83
+ * left out, with a note. Throws when `fleetDir` cannot be listed or a phase-0
84
+ * archive cannot be read.
85
+ */
86
+ export function runArchives(fleetDir) {
87
+ const copies = [];
88
+ const writes = [];
89
+ const notes = [];
90
+ for (const name of readdirSync(fleetDir).sort()) {
91
+ const m = ARCHIVE.exec(name);
92
+ if (m === null) continue;
93
+ const from = join(fleetDir, name);
94
+ if (!isFile(from)) continue;
95
+ const [stamp, file] = m[1] ? [m[1], "ledger.md"] : m[2] ? [m[2], "phase0.json"] : [m[3], "closeout.json"];
96
+ const dir = `${RUNS_DIR}/${stamp}`;
97
+ if (file !== "phase0.json") {
98
+ copies.push({ from, to: `${dir}/${file}` });
99
+ continue;
100
+ }
101
+ const text = readFileSync(from, "utf8");
102
+ let receipt;
103
+ try {
104
+ receipt = JSON.parse(text);
105
+ } catch {
106
+ // Not the parser's message: it can quote the receipt's own bytes.
107
+ notes.push(`${from} not committed: it is not JSON, so its recipe step cannot be withheld`);
108
+ continue;
109
+ }
110
+ const recipe = receipt?.steps?.recipe;
111
+ if (recipe !== null && typeof recipe === "object" && "output" in recipe) recipe.output = RECIPE_WITHHELD;
112
+ writes.push({ to: `${dir}/phase0.json`, text: `${JSON.stringify(receipt, null, 2)}\n` });
113
+ const version = receipt?.pluginVersion;
114
+ if (typeof version === "string" && /^[^\s]+$/.test(version)) writes.push({ to: `${dir}/${PLUGIN_VERSION}`, text: `${version}\n` });
115
+ }
116
+ return { copies, writes, notes };
117
+ }
118
+
119
+ /**
120
+ * The paths a scratch entry's review evidence is committed under, as
121
+ * `{targets: [{from, to}], notes}`. `pr<M>/` gives each `<run>/review.json`
122
+ * under it; `dispositions-fix-pr-<M>[-x].json` gives itself, in the run its
123
+ * `run` field names, or a note when it names none. Any other entry gives
124
+ * nothing. Throws when the entry cannot be read.
125
+ */
126
+ export function reviewTargets(path, name) {
127
+ const pr = PR_ENTRY.exec(name);
128
+ if (pr !== null) {
129
+ let runs;
130
+ try {
131
+ runs = readdirSync(path, { withFileTypes: true });
132
+ } catch (e) {
133
+ if (e.code === "ENOTDIR") return { targets: [], notes: [] };
134
+ throw e;
135
+ }
136
+ const targets = runs
137
+ .filter((d) => d.isDirectory() && RUN_ROOT.test(d.name) && isFile(join(path, d.name, "review.json")))
138
+ .map((d) => ({ from: join(path, d.name, "review.json"), to: `${REVIEWS_DIR}/${pr[1]}/${d.name}/review.json` }))
139
+ .sort((a, b) => (a.to < b.to ? -1 : 1));
140
+ return { targets, notes: [] };
141
+ }
142
+ const d = DISPOSITIONS_ENTRY.exec(name);
143
+ if (d === null || !isFile(path)) return { targets: [], notes: [] };
144
+ let run;
145
+ try {
146
+ run = JSON.parse(readFileSync(path, "utf8")).run;
147
+ } catch (e) {
148
+ return { targets: [], notes: [`${path} names no review run: ${e.message}`] };
149
+ }
150
+ if (typeof run !== "string" || !RUN_ROOT.test(run)) return { targets: [], notes: [`${path} names no review run: run is ${JSON.stringify(run ?? null)}`] };
151
+ return { targets: [{ from: path, to: `${REVIEWS_DIR}/${d[1]}/${run}/${name}` }], notes: [] };
152
+ }
153
+
154
+ /**
155
+ * Every review evidence file under `scratch`, as reviewTargets() maps it.
156
+ * An absent scratch root holds none; one that cannot be listed throws.
157
+ */
158
+ export function reviewEvidence(scratch) {
159
+ let names;
160
+ try {
161
+ names = readdirSync(scratch).sort();
162
+ } catch (e) {
163
+ if (e.code === "ENOENT") return { copies: [], notes: [] };
164
+ throw e;
165
+ }
166
+ const copies = [];
167
+ const notes = [];
168
+ for (const name of names) {
169
+ const found = reviewTargets(join(scratch, name), name);
170
+ copies.push(...found.targets);
171
+ notes.push(...found.notes);
172
+ }
173
+ return { copies, notes };
174
+ }
175
+
176
+ /**
177
+ * Copies every run archive in `fleetDir` and every review evidence file under
178
+ * `scratch` into the checkout at `cwd`, plain mode 0644, replacing what is
179
+ * there: a file already committed comes back byte for byte, so git sees only
180
+ * what is new. What stood at a destination is removed first, so a symlink
181
+ * there is replaced rather than written through. The lines it returns say
182
+ * what was gathered; it throws on a directory it cannot list or a file it
183
+ * cannot copy.
184
+ */
185
+ export function gather({ cwd, fleetDir, scratch }) {
186
+ const runs = runArchives(fleetDir);
187
+ const reviews = reviewEvidence(scratch);
188
+ const place = (to) => {
189
+ const abs = join(cwd, to);
190
+ mkdirSync(dirname(abs), { recursive: true });
191
+ rmSync(abs, { force: true });
192
+ return abs;
193
+ };
194
+ for (const { from, to } of [...runs.copies, ...reviews.copies]) {
195
+ const abs = place(to);
196
+ copyFileSync(from, abs);
197
+ chmodSync(abs, 0o644);
198
+ }
199
+ for (const { to, text } of runs.writes) {
200
+ const abs = place(to);
201
+ writeFileSync(abs, text);
202
+ chmodSync(abs, 0o644);
203
+ }
204
+ return [
205
+ `${runs.copies.length + runs.writes.length} run record file(s) from ${fleetDir}`,
206
+ `${reviews.copies.length} review evidence file(s) from ${scratch}`,
207
+ ...runs.notes,
208
+ ...reviews.notes,
209
+ ];
210
+ }
211
+
212
+ /**
213
+ * The run records among `paths` whose run left no close-out receipt
214
+ * (`closeout.<stamp>.json`) in `fleetDir`. A run that closed out leaves its
215
+ * records to the next run's close-out; phase 0's catch-up commits for the
216
+ * others.
217
+ */
218
+ export function unclosedRecords(fleetDir, paths) {
219
+ return paths.filter((path) => {
220
+ const m = RUN_DIR.exec(path);
221
+ return m !== null && !isFile(join(fleetDir, `closeout.${m[1]}.json`));
222
+ });
223
+ }
224
+
225
+ /** The output line naming a path recordChanges() refused. */
226
+ export const refusedLine = (path) => `not staged, not a run record isRunRecord() allows: ${path}`;
227
+
228
+ /**
229
+ * What the commit may stage under RECORD_DIRS in the checkout at `cwd`, which
230
+ * `git` runs in: `{allowed, refused}`, each a list of repository-relative
231
+ * paths, or `{error}`. The candidates are what `git ls-files --others
232
+ * --modified --exclude-standard` lists there, and what the index already
233
+ * holds staged there, as a commit that failed after its `git add` leaves it.
234
+ * Only a regular file isRunRecord() accepts, with no executable bit, is
235
+ * allowed; anything else — another name, a symlink, an executable, a
236
+ * deletion — is refused, so a commit never carries it.
237
+ */
238
+ export function recordChanges(git, cwd) {
239
+ const paths = [];
240
+ for (const args of [["ls-files", "-z", "--others", "--modified", "--exclude-standard"], ["diff", "--cached", "--name-only", "--no-renames", "-z"]]) {
241
+ const r = git([...args, "--", ...RECORD_DIRS]);
242
+ if (r.status !== 0) return { error: `git ${args[0]} -- ${RECORD_DIRS.join(" ")} failed: ${[r.stdout, r.stderr].filter(Boolean).join("\n") || r.how}` };
243
+ paths.push(...r.stdout.split("\0").filter(Boolean));
244
+ }
245
+ const allowed = [];
246
+ const refused = [];
247
+ for (const path of new Set(paths)) {
248
+ (isRunRecord(path) && isPlainFile(join(cwd, path)) ? allowed : refused).push(path);
249
+ }
250
+ return { allowed, refused };
251
+ }
@@ -1,6 +1,6 @@
1
1
  # Close-out: what each metrics step does and why
2
2
 
3
- `closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the commit of the metrics files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
3
+ `closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the gather of the run records and the review evidence, the commit of the metrics and record files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
4
4
 
5
5
  - **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
6
6
  first (below). The marker is on disk, so the tick
@@ -19,7 +19,8 @@
19
19
  once the run is draining with no open PR and no live implementer.
20
20
  3. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
21
21
  the run's member facts, checks the tier-outcomes rows, refreshes the
22
- metrics, commits the three metrics files and opens their PR, sets the
22
+ metrics, gathers the earlier runs' records and the review evidence,
23
+ commits them with the three metrics files and opens their PR, sets the
23
24
  phase-0 receipt aside as `.fleet/phase0.previous.json`, records
24
25
  `fleet-heartbeat.mjs --stop`, because every reader takes a recorded stop
25
26
  as the end of the run, and then merges the Close-out PR. On `NEED
@@ -124,6 +125,26 @@ the cause and run `finish` again — the pending file stays in `.fleet/` and the
124
125
  next run's phase-0 pass drains it — and never commit the metrics files with a
125
126
  drain that failed claiming the corpus is complete.
126
127
 
128
+ ## Gather the run records and the review evidence
129
+
130
+ **Gather the run records and the review evidence after the metrics refresh,
131
+ before the commit.** The `gather` step of `closeout.mjs finish` copies, from
132
+ `.fleet/`, every run archive `ledger.mjs rotate` left there into
133
+ `docs/metrics/runs/<UTC stamp>/` — `ledger.md`, `phase0.json`, `closeout.json`,
134
+ and a `plugin-version` line from the version the phase-0 receipt recorded —
135
+ and, from the scratch root, every review's `review.json` into
136
+ `docs/metrics/reviews/<pr>/<run>/`, with each Charges file
137
+ (`dispositions-fix-pr-<pr>[-x].json`) beside the review run it answers. The
138
+ phase-0 receipt goes in with its `recipe` step's output withheld, because that
139
+ output is the Recipe's command lines and a command can carry an environment
140
+ assignment; a phase-0 archive that cannot be read as JSON is not gathered, and
141
+ the step's output names it. A run's own archives exist only once the next run
142
+ has rotated, so the records it carries are the earlier runs'; a file main
143
+ already holds comes back byte for byte and adds nothing. A Charges file that
144
+ names no review run is not gathered, and the step's output names it. A
145
+ directory it cannot list or a file it cannot copy fails the step, so
146
+ `commit-and-pr` stays pending: fix the cause and run `finish` again.
147
+
127
148
  ## Commit the metrics files and open a PR
128
149
 
129
150
  The metrics files are the run's own artifacts and none commits itself. Carry
@@ -141,6 +162,14 @@ a data row loses it: `member-outcomes.tsv` is regenerated from harness
141
162
  transcripts the fleet does not own, so re-running the scrape later is worth
142
163
  only what the harness still holds.
143
164
 
165
+ The commit carries the run records and the review evidence beside the three
166
+ metrics files, because a review's evidence is deleted from scratch once its PR
167
+ has merged and main holds it, and a run's ledger and receipts otherwise stay on
168
+ one machine. Only the files `isRunRecord()` in `run-records.mjs` allows are
169
+ staged: the shapes above, regular files with no executable bit. Anything else
170
+ under `docs/metrics/runs/` or `docs/metrics/reviews/` — a recipe, a transcript,
171
+ a brief — is left out of the commit, and the step's output names it.
172
+
144
173
  ## Move the phase-0 receipt
145
174
 
146
175
  **Set aside the phase-0 receipt after the commit — before the heartbeat.** The receipt `.fleet/phase0.json` records each phase-0 step's result and the In-flight bound the tick reads; `closeout.mjs finish` moves it to `.fleet/phase0.previous.json` so the next run can find it under the name `phase0.mjs` reserves for a previous run's receipt, and that run's rotation restores and archives it with the ledger. A missing `.fleet/phase0.json` counts as nothing to move and is `ok`.
@@ -222,7 +222,7 @@ not rely on that.
222
222
  **The acceptance mutation runs unless `finisher-scope.mjs` says the diff is inert.**
223
223
  A mutation that loosens a regex, deletes a guard or flips a reset has nothing to
224
224
  kill in a diff made only of Markdown prose (`.md` or `.markdown` outside the
225
- prompt surface) or only of the run-metrics files. The finisher does not decide
225
+ prompt surface) or only of the run-metrics files, run records and review evidence. 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