@feigi/fleet-ctl 3.129.0 → 3.130.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.129.0",
3
+ "version": "3.130.1",
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": {
@@ -35,21 +35,24 @@
35
35
  #
36
36
  # WHAT IS IN THE SET: the plugin's own component directories — `commands/
37
37
  # scripts/ skills/ agents/ workflows/` — of the Install root, the tree the
38
- # fleet executes, never the checkout this script happens to run in. How the
39
- # package entry is installed decides how the set is read, in one of two modes:
38
+ # fleet executes, never the checkout this script happens to run in, and never
39
+ # the workspace's own. Every regular file and every symlink under those five
40
+ # directories of the realpath is hashed, dotfiles included: nothing in an
41
+ # installed package is untracked and anything in it executes.
40
42
  #
41
- # linked-checkout any other link — GIT mode: every TRACKED file under
42
- # `plugin/commands plugin/scripts plugin/skills
43
- # plugin/agents plugin/workflows` of the checkout the
44
- # link points into, which must be that checkout's
45
- # `plugin/` directory exactly.
46
- # npm-install a real directory — FILES mode: every regular file
47
- # marketplace-install a link into `.omp/plugins/cache/` — and every symlink
48
- # under the five directories of the realpath.
49
- #
50
- # The kinds are named the way fleet-provenance names them, and told apart the
43
+ # THE KINDS are named the way fleet-provenance names them, and told apart the
51
44
  # same way: the entry's own link-ness, then where the link resolves.
52
45
  #
46
+ # npm-install a real directory.
47
+ # marketplace-install a link into `.omp/plugins/cache/`.
48
+ # linked-checkout any other link — `omp plugin link`. REFUSED, at pin
49
+ # and at check, exit 2 and nothing on stdout: a fleet
50
+ # run executes an installed package, and a linked
51
+ # checkout is a working tree that every checkout,
52
+ # merge and edit in it moves under the run. The link
53
+ # remains the dev loop for interactive sessions; the
54
+ # run needs it replaced by the package.
55
+ #
53
56
  # Not a written list of instrument names — the
54
57
  # ticket named six and the class is larger (the supply scan, the liveness
55
58
  # probe, the shared `arg.mjs`/`json.sh`/`net.sh` libraries that a single edit
@@ -58,65 +61,38 @@
58
61
  # already knows can be stale). A list rots on the next commit that adds a
59
62
  # script; a directory does not.
60
63
  #
61
- # NOT THE WHOLE TREE, deliberately, in either mode. A checkout's root also
62
- # carries `docs/`, `.github/` and `.out-of-scope/`, and `docs/metrics/` is
63
- # APPENDED BY THE CONTROLLER MID-RUN, so a whole-repo set would fire the gate
64
- # on the run's own bookkeeping every single time — a guard the controller
65
- # learns to ignore, which is the failure the paragraph below names. A
66
- # package's `package.json`, and everything else at its top level, stays out
67
- # the same way: the set is the five directories in both modes.
68
- #
69
- # TRACKED in a checkout, EVERY FILE in a package, deliberately. A checkout
70
- # counts tracked files only, because an untracked file appearing under those
71
- # dirs — a `.DS_Store`, an editor swap file, a member's scratch output —
72
- # changes no reading the controller takes, and refusing on it would fire the
73
- # guard on ordinary runs. A guard the controller learns to ignore is worse
74
- # than none. A package counts every file, dotfiles included, because nothing
75
- # in it is untracked and anything in it executes.
64
+ # NOT THE WHOLE TREE, deliberately. A package's `package.json`, and everything
65
+ # else at its top level, stays out: the set is the five directories. The
66
+ # state home's `docs/metrics/` is APPENDED BY THE CONTROLLER MID-RUN and is
67
+ # not under the Install root at all, so the run's own bookkeeping cannot fire
68
+ # the gate — a guard the controller learns to ignore is worse than none.
76
69
  #
77
- # CONTENT, not `git status`: status answers off the stat cache, so a content
78
- # change that lands on the same size and mtime does not reach it, and a bare
79
- # `touch` does. This hashes bytes, so it accepts a touch and refuses a rewrite.
80
- # A symlink is hashed by its target's bytes in both modes — `shasum` reads
81
- # through it — so a dangling link, or a link to a directory, cannot be hashed
82
- # and refuses at exit 2.
70
+ # CONTENT, not a stat cache: this hashes bytes, so it accepts a bare `touch`
71
+ # and refuses a rewrite. A symlink is hashed by its target's bytes —
72
+ # `shasum` reads through it — so a dangling link, or a link to a directory,
73
+ # cannot be hashed and refuses at exit 2.
83
74
  #
84
75
  # MODES ARE NOT IN THE DIGEST, and that one is a GAP rather than a trade: a
85
- # mode-only change to a tracked instrument is ACCEPTED. Measured — `chmod +x`
86
- # on a tracked `100644` instrument leaves `git status` printing ` M` for it,
87
- # and `git update-index --chmod=+x` moves the index entry to `100755` with the
88
- # blob untouched; both exit 0 here. A mode change that costs the hash its READ
89
- # is caught instead: `chmod 000` on a tracked instrument refuses at exit 2
90
- # through `could not hash every tracked file` — as root that never fires,
76
+ # mode-only change to an instrument is ACCEPTED. Measured — `chmod +x` on a
77
+ # mode-644 file under the set exits 0 here. A mode change that costs the
78
+ # hash its READ is caught instead: `chmod 000` on an instrument refuses at
79
+ # exit 2 through `could not hash every file` — as root that never fires,
91
80
  # since root reads a mode-000 file regardless (the suite skips
92
81
  # this case there for the same reason). So the exposure is the bits that
93
82
  # still permit reading, the exec bit above all — and that bit is not how a
94
83
  # fleet probe runs: fleet-run hands `.sh` to `sh` and `.mjs` to `node`, so a
95
84
  # stripped `+x` is invisible through the Resolver, while invoking one by path
96
85
  # instead is EACCES at exec (126), loud rather than a wrong verdict. Folding
97
- # modes in — digesting `git ls-files -s` alongside the contents, or a per-file
98
- # `[ -x "$f" ]` — is a behaviour change to the gate on a channel with no
86
+ # modes in is a behaviour change to the gate on a channel with no
99
87
  # silently wrong reading to its name, and whether a mode-only edit is worth
100
88
  # refusing on is a decision rather than a fix, so this paragraph names the gap and
101
- # leaves the behaviour alone. The suite pins the accepted pair,
89
+ # leaves the behaviour alone. The suite pins the accepted case,
102
90
  # so closing the gap later goes red there rather than leaving this
103
91
  # paragraph stale.
104
92
  #
105
- # REFS ARE DELIBERATELY NOT IN THE DIGEST, and the reason is not that they do
106
- # not matter. The corroborating evidence is a stray `fix/42-slug` branch
107
- # left in the main checkout by something running this repo's own fixtures — a
108
- # ref write, which no hash of files can see. But `claim-ticket.sh` creates a
109
- # branch per ticket and `reap.sh` deletes them, in the ref store every worktree
110
- # shares, so a ref digest changes several times per pass as ORDINARY WORK. Per
111
- # gate that is noise, and noise is the one failure this check cannot afford.
112
- # Sweeping for unexpected refs is a drain-cadence question, not a gate one.
113
- #
114
- # COST: one `git rev-parse` to locate the state home, one listing of the set
115
- # (`git ls-files` in git mode, `find` in files mode), a second `git rev-parse`
116
- # in git mode to find the linked checkout, and one pass of `shasum` over those
117
- # files; a pin in git mode also reads HEAD, a git-mode check that finds a
118
- # change runs git again to report it, and a files-mode pin or changed check
119
- # runs `awk` once to read the package's version. No network, no `gh`, no
93
+ # COST: one `git rev-parse` to locate the state home, one `find` over the set
94
+ # and one pass of `shasum` over those files; a pin or a changed check runs
95
+ # `awk` once to read the package's version. No network, no `gh`, no
120
96
  # fetch, no subprocess per file. It is meant to be run
121
97
  # before every gate decision and it has to be cheap enough that nobody is
122
98
  # tempted to skip it.
@@ -129,26 +105,23 @@ set -eu
129
105
  # Here the only constraint left is the real one: above the first git call.
130
106
  #
131
107
  # GIT_WORK_TREE is the wrong-tree defect reached through the environment. The
132
- # contract here is that the state home is the WORKING DIRECTORY's checkout and
133
- # a linked install's tree is the checkout its link points into — and
134
- # `git rev-parse --show-toplevel` answers with the ambient work tree instead
135
- # the moment one is set, `--repo` or not. Measured:
136
- # standing in a checkout whose instruments have been TAMPERED, with
137
- # `GIT_WORK_TREE` naming a clean twin that carries its own pinned baseline,
138
- # this script exits 0 and prints the twin's digest. The gate passes. That is
108
+ # contract here is that the state home is the WORKING DIRECTORY's checkout —
109
+ # and `git rev-parse --show-toplevel` answers with the ambient work tree
110
+ # instead the moment one is set, `--repo` or not. Measured:
111
+ # standing in a checkout whose baseline is honest, with
112
+ # `GIT_WORK_TREE` naming a twin whose own pinned baseline matches the
113
+ # tampered Install root, this script exits 0 and prints the tampered digest.
114
+ # The gate passes. That is
139
115
  # the same wrong-tree write `--repo ""` produced before this script refused it, one
140
116
  # door further out, and a gate that certifies a tree nobody looked at is
141
117
  # worse than no gate.
142
118
  #
143
- # GIT_DIR is unset alongside it and is measured INERT here: `ls-files` names
144
- # paths and the digest is taken over the FILES ON DISK under the tree, so
145
- # pointing the object database elsewhere changes nothing — measured against a
146
- # clean twin holding the exact pre-tamper content, the tampered digest came
147
- # back unchanged and the gate still refused. It stays on the line because the
119
+ # GIT_DIR is unset alongside it and is measured INERT here: the only git call
120
+ # is `rev-parse --show-toplevel`, and the digest is taken over the FILES ON
121
+ # DISK under the Install root, so pointing the object database elsewhere
122
+ # changes nothing. It stays on the line because the
148
123
  # pair is one hazard with one remedy, and because "inert today" is a
149
- # measurement of the current call set: a digest taken from `git show` or
150
- # `cat-file` rather than from disk would reintroduce the half nothing here
151
- # can see. The suite pins the line itself, which is
124
+ # measurement of the current call set. The suite pins the line itself, which is
152
125
  # what keeps that half from being quietly dropped.
153
126
  unset GIT_DIR GIT_WORK_TREE
154
127
 
@@ -209,6 +182,42 @@ else
209
182
  fi
210
183
  base="$root/.fleet/instruments.sha"
211
184
 
185
+ # The Install root, resolved inline on every pin and every check: the same
186
+ # path fleet-run, fleet-provenance and fleet-bootstrap resolve, the same way —
187
+ # the package entry's own link-ness for the kind, its realpath for the tree.
188
+ # Mirrored rather than called. The placed `~/.fleet/bin/fleet-run` can drift
189
+ # from the package, and an environment override or a `node` call would be a
190
+ # second way to name a tree the fleet does not execute.
191
+ #
192
+ # HOME is checked by hand because `set -u` does not answer for it: measured,
193
+ # macOS `/bin/sh` exits 1 on an unset HOME under `set -eu`, and exit 1 is the
194
+ # one code that means the set changed.
195
+ [ -n "${HOME:-}" ] || die "HOME is unset — cannot resolve the Install root"
196
+ entry="$HOME/.omp/plugins/node_modules/@feigi/fleet-ctl"
197
+ if [ -L "$entry" ]; then
198
+ [ -e "$entry" ] || die "omp plugin \"@feigi/fleet-ctl\" link $entry is dangling"
199
+ live=$(CDPATH='' cd -P "$entry" && pwd -P) \
200
+ || die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
201
+ case $live in
202
+ */.omp/plugins/cache/*) kind=marketplace-install ;;
203
+ *) kind=linked-checkout ;;
204
+ esac
205
+ else
206
+ [ -e "$entry" ] || die "no omp plugin \"@feigi/fleet-ctl\" at $entry"
207
+ live=$(CDPATH='' cd -P "$entry" && pwd -P) \
208
+ || die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
209
+ kind=npm-install
210
+ fi
211
+
212
+ # A linked checkout is refused, at pin and at check, before anything is read
213
+ # from or written to the state home and before anything is hashed. A fleet run
214
+ # executes an installed package: a link's tree moves under the run with every
215
+ # checkout, merge and edit in it, which no digest can tell from tampering. The
216
+ # controller never runs `omp plugin`; the message is for the maintainer.
217
+ if [ "$kind" = linked-checkout ]; then
218
+ die "Install root $live is a linked checkout (omp plugin link) — a fleet run executes an installed package; omp plugin uninstall @feigi/fleet-ctl, then omp plugin install @feigi/fleet-ctl, and restart."
219
+ fi
220
+
212
221
  if [ "$pin" != true ]; then
213
222
  # No baseline is not "nothing has changed" — it is a run that never pinned,
214
223
  # and the check has nothing to compare against. Refusing is the whole
@@ -241,51 +250,9 @@ if [ "$pin" != true ]; then
241
250
  [ -n "$want" ] || die "$base is empty — re-pin, do not guess"
242
251
  fi
243
252
 
244
- # The Install root, resolved inline on every pin and every check: the same
245
- # path fleet-run, fleet-provenance and fleet-bootstrap resolve, the same way —
246
- # the package entry's own link-ness for the kind, its realpath for the tree.
247
- # Mirrored rather than called. The placed `~/.fleet/bin/fleet-run` can drift
248
- # from the package, and an environment override or a `node` call would be a
249
- # second way to name a tree the fleet does not execute.
250
- #
251
- # HOME is checked by hand because `set -u` does not answer for it: measured,
252
- # macOS `/bin/sh` exits 1 on an unset HOME under `set -eu`, and exit 1 is the
253
- # one code that means the set changed.
254
- [ -n "${HOME:-}" ] || die "HOME is unset — cannot resolve the Install root"
255
- entry="$HOME/.omp/plugins/node_modules/@feigi/fleet-ctl"
256
- if [ -L "$entry" ]; then
257
- [ -e "$entry" ] || die "omp plugin \"@feigi/fleet-ctl\" link $entry is dangling"
258
- live=$(CDPATH='' cd -P "$entry" && pwd -P) \
259
- || die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
260
- case $live in
261
- */.omp/plugins/cache/*) kind=marketplace-install ;;
262
- *) kind=linked-checkout ;;
263
- esac
264
- else
265
- [ -e "$entry" ] || die "no omp plugin \"@feigi/fleet-ctl\" at $entry"
266
- live=$(CDPATH='' cd -P "$entry" && pwd -P) \
267
- || die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
268
- kind=npm-install
269
- fi
270
-
271
- # A linked checkout is certified as the checkout it is — git mode, over the
272
- # toplevel, the tree and the shape a checkout's pin has always been made over
273
- # — and only when the link points at that checkout's `plugin/` directory
274
- # exactly. A link to the checkout's root, to a nested copy of `plugin/`, or to
275
- # a directory outside any checkout names a tree whose tracked set is not the
276
- # one the fleet executes, so it refuses rather than guess which it meant.
253
+ # The five component directories, as the digest lists them.
277
254
  dirs='commands scripts skills agents workflows'
278
- set=
279
- for d in $dirs; do set="${set:+$set }plugin/$d"; done
280
- if [ "$kind" = linked-checkout ]; then
281
- mode=git
282
- badlink="Install root $live is not the plugin/ directory of a git checkout — a linked install must point at <checkout>/plugin"
283
- target=$(git -C "$live" rev-parse --show-toplevel 2>/dev/null) || die "$badlink"
284
- [ "$live" = "$target/plugin" ] || die "$badlink"
285
- else
286
- mode=files
287
- target=$live
288
- fi
255
+ target=$live
289
256
 
290
257
  # The top-level "version" of the package's `package.json`, or nothing. It is
291
258
  # evidence for a refusal to name, never part of a verdict, so a file that is
@@ -354,37 +321,27 @@ files=$(mktemp) || die "cannot create a temp file"
354
321
  trap 'rm -f "$files"' EXIT
355
322
  trap 'rm -f "$files"; exit 2' INT HUP TERM
356
323
 
357
- if [ "$mode" = git ]; then
358
- # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
359
- git -C "$target" ls-files -z -- $set > "$files" \
360
- || die "git ls-files failed under $target for: $set"
361
- # An empty listing is the shape a wrong tree produces — a symlinked skills
362
- # dir resolving to a different repository, most plausibly. Certifying it
363
- # would hand back "unchanged" for a set that was never read.
364
- [ -s "$files" ] || die "no tracked file under $target for: $set — refusing to certify an empty instrument set"
365
- else
366
- # Absent directories are skipped, but a name that is present in any form
367
- # — a file, a dangling link — is listed, so it reaches `shasum` and refuses
368
- # there rather than vanishing from the set. With none present there is
369
- # nothing to certify, and `find` given no path would list `.` instead.
370
- present=
371
- for d in $dirs; do
372
- if [ -e "$target/$d" ] || [ -L "$target/$d" ]; then
373
- present="$present $d"
374
- fi
375
- done
376
- [ -n "$present" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
377
- # Paths relative to the realpath, NUL-separated, in byte order: `find`
378
- # lists in directory order, which is the filesystem's to choose, so the
379
- # sort is what makes the digest a function of the tree alone. Two steps
380
- # with a status check each, for the reason the hashing below spells out.
381
- # shellcheck disable=SC2086 # $present is a list of fixed directory names
382
- (cd "$target" && find $present \( -type f -o -type l \) -print0) > "$files" \
383
- || die "could not list every file under $target for: $dirs"
384
- LC_ALL=C sort -z -o "$files" "$files" \
385
- || die "could not sort the instrument set under $target"
386
- [ -s "$files" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
387
- fi
324
+ # Absent directories are skipped, but a name that is present in any form
325
+ # — a file, a dangling link — is listed, so it reaches `shasum` and refuses
326
+ # there rather than vanishing from the set. With none present there is
327
+ # nothing to certify, and `find` given no path would list `.` instead.
328
+ present=
329
+ for d in $dirs; do
330
+ if [ -e "$target/$d" ] || [ -L "$target/$d" ]; then
331
+ present="$present $d"
332
+ fi
333
+ done
334
+ [ -n "$present" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
335
+ # Paths relative to the realpath, NUL-separated, in byte order: `find`
336
+ # lists in directory order, which is the filesystem's to choose, so the
337
+ # sort is what makes the digest a function of the tree alone. Two steps
338
+ # with a status check each, for the reason the hashing below spells out.
339
+ # shellcheck disable=SC2086 # $present is a list of fixed directory names
340
+ (cd "$target" && find $present \( -type f -o -type l \) -print0) > "$files" \
341
+ || die "could not list every file under $target for: $dirs"
342
+ LC_ALL=C sort -z -o "$files" "$files" \
343
+ || die "could not sort the instrument set under $target"
344
+ [ -s "$files" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
388
345
 
389
346
  # Two steps, each with its own status check, because a pipeline reports only its
390
347
  # LAST command: with `xargs … | shasum` as one pipeline, a `shasum` that cannot
@@ -393,45 +350,37 @@ fi
393
350
  # — a verdict about the tree — off a failure to look. reap.sh shipped this exact
394
351
  # bug against `git cherry` and it deleted branches.
395
352
  #
396
- # `xargs` exits 123 when `shasum` failed on any file, which is how a tracked
397
- # file deleted from the worktree arrives — and a dangling link, or a link to a
398
- # directory: as exit 2 naming it, not as a digest quietly missing a line. Both
353
+ # `xargs` exits 123 when `shasum` failed on any file — a dangling link, or a
354
+ # link to a directory, or a file that cannot be read — as exit 2 naming it,
355
+ # not as a digest quietly missing a line. Both
399
356
  # refuse; only one of them is honest about why.
400
357
  per_file=$(cd "$target" && xargs -0 shasum -a 256 < "$files") \
401
- || die "could not hash every tracked file under $target — see the errors above"
358
+ || die "could not hash every file under $target — see the errors above"
402
359
  digest=$(printf '%s\n' "$per_file" | shasum -a 256 | cut -d' ' -f1) \
403
360
  || die "could not digest the instrument set"
404
361
  [ -n "$digest" ] || die "empty digest for $target"
405
362
 
406
363
  if [ "$pin" = true ]; then
407
364
  mkdir -p "$root/.fleet" || die "cannot create $root/.fleet"
408
- # Three lines, order fixed: the digest first, the certified tree second, and
409
- # third what says which state of it was pinned — the checkout's HEAD commit
410
- # in git mode, the package's version in files mode. A reader that only
365
+ # Three lines at most, order fixed: the digest first, the certified tree
366
+ # second, and third the package's version. A reader that only
411
367
  # knows the old one-line shape — merge-gate.mjs's `readInstruments`, which
412
368
  # takes the FIRST stdout line as the digest — keeps working, and a check
413
369
  # from this script reads the rest. The root rides in the same write as the
414
370
  # digest so a check can tell the Install root moved; the check compares it
415
371
  # and never follows it.
416
372
  #
417
- # Neither third line is trusted for any verdict: each exists only so a
418
- # refusal can say what moved. HEAD unborn or unreadable writes no `commit=`
419
- # line, a package with no readable version writes no `version=` line, and
420
- # the refusal says so.
421
- if [ "$mode" = git ]; then
422
- key=commit
423
- val=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || val=
424
- else
425
- key=version
426
- val=$(pkg_version)
427
- fi
373
+ # The version line is not trusted for any verdict: it exists only so a
374
+ # refusal can say what moved. A package with no readable version writes no
375
+ # `version=` line, and the refusal says so.
376
+ val=$(pkg_version)
428
377
  {
429
378
  printf '%s\n' "$digest"
430
379
  printf 'root=%s\n' "$target"
431
- [ -z "$val" ] || printf '%s=%s\n' "$key" "$val"
380
+ [ -z "$val" ] || printf 'version=%s\n' "$val"
432
381
  } > "$base" || die "cannot write $base"
433
382
  printf '%s\n' "$digest"
434
- printf '%s: pinned %s over %s %s (%s %s)\n' "$NAME" "$digest" "$kind" "$target" "$key" "${val:-?}" >&2
383
+ printf '%s: pinned %s over %s %s (version %s)\n' "$NAME" "$digest" "$kind" "$target" "${val:-?}" >&2
435
384
  exit 0
436
385
  fi
437
386
 
@@ -449,73 +398,8 @@ printf '%s: refuse the gate and report. Do NOT re-read the instrument.\n' "$NAME
449
398
  # changed: the versions are what the maintainer rules on — adopt what is
450
399
  # installed, or put the pinned version back. Never the controller: a
451
400
  # reinstall swaps the files every live member is running.
452
- if [ "$mode" = files ]; then
453
- pinv=$(baseline_field version) || pinv=
454
- nowv=$(pkg_version)
455
- printf '%s: %s %s: version %s pinned, %s now\n' "$NAME" "$kind" "$target" "${pinv:-?}" "${nowv:-?}" >&2
456
- printf '%s: the installed package changed or was reinstalled — the maintainer adopts it (re-pin) or restores version %s\n' "$NAME" "${pinv:-?}" >&2
457
- exit 1
458
- fi
459
-
460
- # A checkout: `git status` names the uncommitted half, which is the shape
461
- # this header's measured near-miss took; a checked-out branch that moved
462
- # shows as nothing here and the HEAD line is what names it.
463
- headc=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || headc=
464
- printf '%s: HEAD %s\n' "$NAME" "${headc:-?}" >&2
465
- # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
466
- git -C "$target" status --porcelain -- $set >&2 || true
467
-
468
- # Then what moved, relative to the commit the pin recorded. Only the commit
469
- # graph can say whether HEAD advanced, rewound or diverged, and the maintainer
470
- # decides what to do about each, so this names the relation and stops: the
471
- # verdict above is already refusal. Anything but a full hex id is treated as
472
- # absent from the repository, so a baseline line cannot reach git as an option.
473
- pinc=$(baseline_field commit)
474
- present=false
475
- case $pinc in
476
- *[!0-9a-f]*) ;;
477
- *) if { [ "${#pinc}" -eq 40 ] || [ "${#pinc}" -eq 64 ]; } \
478
- && git -C "$target" cat-file -e "$pinc^{commit}" 2>/dev/null; then
479
- present=true
480
- fi ;;
481
- esac
482
- if [ -z "$pinc" ]; then
483
- printf '%s: pin commit not recorded — the baseline has no commit= line\n' "$NAME" >&2
484
- elif [ "$present" != true ]; then
485
- printf '%s: pin commit %s is not in the repository\n' "$NAME" "$pinc" >&2
486
- elif [ -z "$headc" ]; then
487
- printf '%s: pin commit %s; HEAD cannot be read\n' "$NAME" "$pinc" >&2
488
- else
489
- printf '%s: pin commit %s\n' "$NAME" "$pinc" >&2
490
- if [ "$headc" = "$pinc" ]; then
491
- printf '%s: HEAD unmoved — HEAD is the pin commit\n' "$NAME" >&2
492
- else
493
- # `--is-ancestor` answers with its exit code: 0 is yes and 1 is no. Any
494
- # other code is git failing to compare — an unreadable object, a corrupt
495
- # history — and a relation read off that failure would hand the
496
- # maintainer a false fact to rule on, so it says unknown and lets git's
497
- # own error through.
498
- fwd=0
499
- git -C "$target" merge-base --is-ancestor "$pinc" "$headc" || fwd=$?
500
- back=1
501
- if [ "$fwd" -eq 1 ]; then
502
- back=0
503
- git -C "$target" merge-base --is-ancestor "$headc" "$pinc" || back=$?
504
- fi
505
- if [ "$fwd" -eq 0 ]; then
506
- printf '%s: HEAD advanced — the pin commit is an ancestor of HEAD\n' "$NAME" >&2
507
- git --no-pager -C "$target" log --no-decorate --no-color --oneline -n 20 "$pinc..$headc" >&2 || true
508
- between=$(git -C "$target" rev-list --count "$pinc..$headc" 2>/dev/null || printf 0)
509
- if [ "$between" -gt 20 ]; then
510
- printf '… %s more\n' "$((between - 20))" >&2
511
- fi
512
- elif [ "$fwd" -eq 1 ] && [ "$back" -eq 0 ]; then
513
- printf '%s: HEAD rewound — HEAD is an ancestor of the pin commit\n' "$NAME" >&2
514
- elif [ "$fwd" -eq 1 ] && [ "$back" -eq 1 ]; then
515
- printf '%s: HEAD diverged — neither is an ancestor of the other\n' "$NAME" >&2
516
- else
517
- printf '%s: HEAD relation unknown — git could not compare the pin commit with HEAD\n' "$NAME" >&2
518
- fi
519
- fi
520
- fi
401
+ pinv=$(baseline_field version) || pinv=
402
+ nowv=$(pkg_version)
403
+ printf '%s: %s %s: version %s pinned, %s now\n' "$NAME" "$kind" "$target" "${pinv:-?}" "${nowv:-?}" >&2
404
+ printf '%s: the installed package changed or was reinstalled — the maintainer adopts it (re-pin) or restores version %s\n' "$NAME" "${pinv:-?}" >&2
521
405
  exit 1
@@ -40,8 +40,9 @@
40
40
  // fleet-run executes scripts from and omp loads the runbooks from — the
41
41
  // root itself included. No gitignore exemption: nothing under it is a
42
42
  // member's to write. It holds whichever repository the session runs in,
43
- // or none, and for every install kind; under a linked checkout the
44
- // Install root is that checkout's `plugin/`.
43
+ // or none, and for every install kind. A fleet run refuses a linked
44
+ // Install root (instruments.sh), but an interactive session may still
45
+ // link a checkout, whose Install root is then that checkout's `plugin/`.
45
46
  // - `bash` cwd, for every `fleet-implementer-<cell>` (ledger-grammar.mjs's
46
47
  // `CELL_DEF`), and for a fix-applier's own id (`fix-pr-<n>`) directly,
47
48
  // since its definition, `fleet-fix-applier`, is no implementer cell and
@@ -17,8 +17,8 @@
17
17
  // Reached through the Resolver and run from the MAIN checkout (a linked
18
18
  // worktree refuses: the checks below judge the checkout the controller reads
19
19
  // its rules from). The steps, each a named entry in the receipt, run in
20
- // this order because the order is the point — the pin certifies the tree the
21
- // fast-forward left, the rotation comes before the fold-in, the scratch
20
+ // this order because the order is the point — the pin is recorded after the
21
+ // fast-forward, the rotation comes before the fold-in, the scratch
22
22
  // reclaim straight after the rotation, the metrics refresh before the first
23
23
  // Pull is routed:
24
24
  //
@@ -29,12 +29,15 @@
29
29
  // on a branch whose PR has merged would fast-forward that branch
30
30
  // and the baseline would record it as the run's ref.
31
31
  // fast-forward `git fetch origin`, `rev-list --count main..origin/main`,
32
- // `merge --ff-only origin/main`. HEAD moving means the rules this
33
- // script came from are superseded: prints `SUPERSEDED <n>
34
- // commits; re-run phase0.mjs` and fails, so the re-run executes
35
- // from the new tree.
32
+ // `merge --ff-only origin/main`. HEAD moving is ok, the count
33
+ // in the output. It still runs because the workspace's own
34
+ // tracked files (`docs/metrics/*`, its docs and CI-facing
35
+ // files) must be at origin/main and the baseline is recorded
36
+ // after it; the rules come from the installed package, which
37
+ // a fast-forward does not touch.
36
38
  // pin `instruments.sh --pin`, which certifies the Install root; the
37
- // ok line names its kind, root, and version or commit.
39
+ // ok line names its kind, root and version. A linked
40
+ // checkout refuses: a fleet run executes an installed package.
38
41
  // baseline `main-checkout.mjs --record`; its refusals fail the step.
39
42
  // labels `label-map.mjs ensure`, the Label map derivation step. Exit 0
40
43
  // is ok, its output the map ensure printed. Exit 3 is pending,
@@ -236,13 +239,13 @@ function fastForward({ cwd }) {
236
239
  if (behind === 0) return ok("main is level with origin/main");
237
240
  const merge = run("git", ["merge", "--ff-only", "origin/main"], { cwd });
238
241
  if (merge.status !== 0) return refusal("git merge --ff-only origin/main failed:", merge);
239
- return failed(`SUPERSEDED ${behind} commits; re-run phase0.mjs`);
242
+ return ok(`fast-forwarded ${behind} commits to origin/main`);
240
243
  }
241
244
 
242
245
  function pin({ cwd }) {
243
246
  const r = sh("instruments.sh", ["--pin"], { cwd });
244
247
  if (r.status !== 0) return refusal("instruments.sh --pin failed:", r);
245
- // `instruments: pinned <digest> over <kind> <root> (version <v>|commit <sha>)`
248
+ // `instruments: pinned <digest> over <kind> <root> (version <v>)`
246
249
  const m = /^instruments: pinned [0-9a-f]+ over (.+)$/m.exec(r.stderr);
247
250
  return ok(`instruments pinned: ${m ? m[1] : r.stderr || "?"}`);
248
251
  }
package/scripts/reap.sh CHANGED
@@ -1299,17 +1299,12 @@ for b in $gone_branches; do
1299
1299
  # `git_probe`'s stderr capture reach it: the config yields rc 0, empty
1300
1300
  # stdout AND empty stderr, so there is nothing for `gp_cut_short` to
1301
1301
  # match. Pinning the mode on the command line is the only fix: a probe
1302
- # whose EMPTY answer licenses an action pins an explicit mode; a probe
1303
- # that only reports after a gate has already refused need not (see
1304
- # below). `git worktree remove`'s own refusal is no backstop, being the
1302
+ # whose EMPTY answer licenses an action pins an explicit mode.
1303
+ # `git worktree remove`'s own refusal is no backstop, being the
1305
1304
  # same machinery the same config silences (measured at the --apply call
1306
1305
  # below).
1307
1306
  #
1308
- # The one bare `--porcelain` left in a SCRIPT is deliberate:
1309
- # instruments.sh prints one to stderr to say WHAT changed, after a digest
1310
- # over `git ls-files` has already refused. That digest covers TRACKED
1311
- # files only, so no untracked file can trigger it and the silenced mode
1312
- # cannot hide the thing being reported. A report, not a gate. (Prose
1307
+ # No script carries a bare `--porcelain`. (Prose
1313
1308
  # instructions to an agent are a separate inventory — see SKILL.md,
1314
1309
  # pinned alongside the scripts.)
1315
1310
  #
@@ -699,22 +699,16 @@ you cannot confirm was received, re-check the artifacts it governed. See referen
699
699
  - **Re-pin only on the maintainer's adopt.** Nothing you change yourself is a
700
700
  reason: a tooling defect is reported, never fixed by you. Re-pinning to clear
701
701
  a refusal you cannot explain discards the check.
702
- - **A pinned tree whose HEAD moved is the maintainer's to settle, whoever moved
703
- it — and so is an installed plugin that changed.** When a refusal — your check
704
- or a finisher's halt — reads HEAD advanced, rewound or diverged from the pin
705
- commit, never re-pin over it: not for a fast-forward to `origin/main`, and not
706
- when the commits between are only this run's own merged PRs. The same holds
707
- when it names a changed package or an Install root that now resolves
708
- elsewhere, even an upgrade to a release of this run's own PRs. Act on no
709
- `DISPATCH` or `PULL` row, and tell the maintainer what the refusal printed:
710
- the pin commit, HEAD and the commits between, or the pinned and current
711
- Install root and version. On their **restore**, run `git reset --keep <pin commit>` —
712
- only when the pinned tree is the main checkout and the tick prints no
713
- `MAIN-CHECKOUT` line; otherwise they restore it by hand, and an installed
714
- package always: never run `omp plugin` yourself, because a reinstall swaps the
715
- files every live member is running. On their **adopt**, re-pin. Once the
716
- check exits 0, resume, and apply the finisher gate to each PR whose finisher
717
- halted on that refusal. See references/instruments.md.
702
+ - **A changed installed plugin is the maintainer's to settle, whoever changed
703
+ it.** When a refusal — your check or a finisher's halt — names a changed
704
+ package or an Install root that now resolves elsewhere, never re-pin over it,
705
+ even for an upgrade to a release of this run's own PRs. Act on no `DISPATCH` or
706
+ `PULL` row, and tell the maintainer what the refusal printed: the pinned and
707
+ current Install root and version. On their **restore** they reinstall the
708
+ pinned version by hand: never run `omp plugin` yourself, because a reinstall
709
+ swaps the files every live member is running. On their **adopt**, re-pin.
710
+ Once the check exits 0, resume, and apply the finisher gate to each PR whose
711
+ finisher halted on that refusal. See references/instruments.md.
718
712
 
719
713
  ### Relabel causes
720
714
 
@@ -9,8 +9,7 @@ Evidence for the rule SKILL.md states in **Re-check the instruments before a gat
9
9
  **You read your instruments out of a tree every member can write to — re-check
10
10
  them before every gate decision.** Per-member worktrees and `./agent-test`'s port
11
11
  derivation protect members from each other; neither protects the Install root,
12
- the tree you run every gate probe out of and read these runbooks from. It is
13
- the main checkout only when that checkout is linked as the install. The
12
+ the tree you run every gate probe out of and read these runbooks from. The
14
13
  `member-write-guard` extension refuses a `write`/`edit`/`ast_edit` into the
15
14
  Install root, as it does into the main checkout, but a `bash` or `eval` write
16
15
  into the Install root still lands, and this re-check is what catches one.
@@ -34,8 +33,11 @@ in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge
34
33
 
35
34
  It covers the Install root's plugin component directories — `commands/`,
36
35
  `scripts/`, `skills/`, `agents/`, `workflows/` — the probes, the libraries they
37
- source, and these runbooks, which you also read from that tree: the tracked
38
- files of a linked checkout's `plugin/…`, or every file of an installed package.
36
+ source, and these runbooks, which you also read from that tree: every file of
37
+ the installed package. A linked Install root (`omp plugin link`) is not covered
38
+ but refused, at the pin and at every check: a fleet run executes an installed
39
+ package, so the maintainer uninstalls the link and installs the package, and you
40
+ never run `omp plugin`.
39
41
  Not the whole repo: `docs/metrics/` is appended by THIS run, so covering it
40
42
  would refuse on the run's own bookkeeping every time. It does not cover refs,
41
43
  deliberately: `claim-ticket.sh` creates a branch per ticket and `reap.sh`
@@ -92,58 +94,20 @@ defect reaches whenever it changes what that member does — live members now,
92
94
  later ones right after their dispatch — and count a repeat of the same failure
93
95
  as this defect, not a new trigger.
94
96
 
95
- ## A pinned tree whose HEAD moved is the maintainer's to settle
96
-
97
- Pinned from a linked checkout, `instruments.sh --pin` records the checkout's
98
- HEAD as `commit=<sha>` after the digest and `root=`, and an exit-1 refusal
99
- prints that pin commit and how
100
- HEAD relates to it: `advanced` (the pin commit is an ancestor of HEAD, with the
101
- commits between, at most 20 and then `… N more`), `rewound`, `diverged`, or
102
- `unmoved` (HEAD is the pin commit, so the porcelain lines name the edits). When
103
- git cannot compare the two — an unreadable object, a corrupt history — it says
104
- the relation is `unknown`, with git's own error, rather than guess one; HEAD is
105
- not the pin commit there either, so never re-pin over it. A baseline with no
106
- `commit=` line, or one whose commit is gone from the repository, prints one
107
- line saying so and no relation.
108
-
109
- **An installed package has no HEAD.** Pinned from an npm or marketplace
110
- install, the baseline records the package's `version=` in place of a commit,
111
- and an exit-1 refusal names the pinned version and the current one, with no
112
- git output. An Install root that now resolves elsewhere than the pinned one —
113
- a reinstall that moved it, a switch between a package and a linked checkout,
114
- a link pointed elsewhere — refuses at exit 2, naming the pinned root and the
115
- current one. Restore is the maintainer reinstalling the pinned version by
116
- hand, never the controller: a reinstall swaps the files under every live
117
- member.
118
-
119
- **The measured case.** Another session fast-forwarded the main checkout to
120
- `origin/main` mid-run. The commits that brought in were only this run's own
121
- merged PRs, the controller counted them as its own, re-pinned without asking and
122
- dispatched the next finishers. The tick could not see the move: its
123
- main-checkout guard reads a fast-forward to `origin/main` as clean, and the tick
124
- never runs the instrument check. Only the gate re-checks saw it — a finisher
125
- halting with cause `other`, the merge gate refusing with
126
- `instrument-set-changed`. A refusal cannot tell a move the maintainer would
127
- adopt from one they would not, because only they know whether a session of
128
- theirs is working in that checkout, so the pin stays frozen and the move stays
129
- a refusal even when the commits between are only the run's own.
130
-
131
- **Why the reset is the controller's only on a clean tick.** A clean
132
- main-checkout reading means HEAD is still on `main` and every commit since the
133
- baseline is on `origin/main`. So `git reset --keep <pin commit>` moves no other
134
- branch and drops nothing that exists only locally, and `--keep` refuses rather
135
- than overwrite an uncommitted edit that conflicts with the move. On a switched
136
- branch the guard prints `MAIN-CHECKOUT-DIRTY HEAD …`, and a reset there would
137
- move that other branch, so the maintainer restores such a tree by hand.
138
-
139
- Measured in a temp clone with the real `main-checkout.mjs` and
140
- `instruments.sh`, the pin 3 commits behind `origin/main` and 4 set paths
141
- different:
142
-
143
- | Checkout state | Main-checkout guard | Instrument check |
144
- |---|---|---|
145
- | at the pin commit | clean | 0 |
146
- | fast-forwarded to `origin/main` | clean | 1 |
147
- | after `git reset --keep <pin commit>` | clean | 0 |
148
- | on another branch | `MAIN-CHECKOUT-DIRTY HEAD refs/heads/main@… → refs/heads/other@…` | 1 |
97
+ ## A changed installed plugin is the maintainer's to settle
98
+
99
+ **An installed package has no HEAD.** `instruments.sh --pin` records the
100
+ package's `version=` after the digest and `root=`, and an exit-1 refusal names
101
+ the pinned version and the current one, with no git output. An Install root
102
+ that now resolves elsewhere than the pinned one — a reinstall that moved it, a
103
+ move into omp's cache, a baseline from an older plugin that recorded a checkout
104
+ — refuses at exit 2, naming the pinned root and the current one. A linked
105
+ Install root refuses at exit 2 at the pin and at every check, naming the link.
106
+ Restore is the maintainer reinstalling the pinned version by hand, never the
107
+ controller: a reinstall swaps the files under every live member.
108
+
109
+ A fast-forward of the main checkout is no refusal: the pin certifies the
110
+ installed package, not the checkout, so moving the checkout changes no
111
+ instrument. The tick's main-checkout guard reads a fast-forward to
112
+ `origin/main` as clean and holds the run on a branch switch or an edit.
149
113
 
@@ -44,19 +44,23 @@ until the receipt is whole.
44
44
 
45
45
  ## Fast-forward the checkout
46
46
 
47
- **Fast-forward the checkout before you trust these rules — you are reading
48
- them from it.** First, `git symbolic-ref -q HEAD` must print
47
+ **Fast-forward the checkout before the run starts — its own tracked files
48
+ must be at `origin/main`.** First, `git symbolic-ref -q HEAD` must print
49
49
  `refs/heads/main`; anything else, stop and tell the maintainer — a checkout
50
50
  left on a branch whose PR has merged would fast-forward that branch, and the
51
51
  baseline below would record it as the run's ref. Then
52
52
  `git fetch origin && git rev-list --count main..origin/main`;
53
- non-zero means the SKILL.md you are executing is superseded, so
54
- `git merge --ff-only origin/main` and re-read what changed under
55
- `commands/`, `scripts/` and `skills/`. The usual cause is the PREVIOUS run's own close-out PR: it
56
- lands the rules THIS run needs and nothing pulls them. Measured twice — 57
57
- commits stale in one run, 20 in another, the second shipping every dispatch
58
- prompt without two rules that had merged the day before. Silent by
59
- construction: stale text reads as authoritative.
53
+ non-zero means the checkout is behind, so `git merge --ff-only origin/main`.
54
+ `phase0.mjs` does this itself and records the move as `ok`, naming the
55
+ count. It still runs because the workspace's own tracked files —
56
+ `docs/metrics/*`, the repo's own docs and CI-facing files — are what this run
57
+ reads and appends to, and the baseline below is recorded after it: recording
58
+ the baseline before that fast-forward would record a HEAD behind `origin/main`
59
+ as the run's own. The rules
60
+ come from the installed package, which a fast-forward does not touch, so
61
+ nothing you read is stale after it and no re-run follows. The usual cause of
62
+ a stale checkout is the PREVIOUS run's own close-out PR, which lands the
63
+ metrics and docs THIS run builds on and nothing pulls them.
60
64
 
61
65
  ## Pin the instruments
62
66
 
@@ -65,11 +69,13 @@ them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
65
69
  records what the scripts and runbooks of the Install root — the tree the
66
70
  fleet executes — say right now, which is what every later gate compares
67
71
  against; SKILL.md's **Re-check before you act on any instrument reading** says
68
- what its exit codes mean. When this main checkout is the linked install,
69
- pinning before that fast-forward would instead pin the superseded text and
70
- certify it for the rest of the run. The pin certifies the Install root and
72
+ what its exit codes mean. The pin certifies the Install root and
71
73
  keeps its baseline in this checkout's `.fleet/`, so a workspace that tracks no
72
- `plugin/…` of its own pins with no flag. The baseline records the root it
74
+ `plugin/…` of its own pins with no flag. A linked Install root (`omp plugin
75
+ link`) refuses the pin at exit 2: a fleet run executes an installed package,
76
+ so tell the maintainer to `omp plugin uninstall @feigi/fleet-ctl` and
77
+ `omp plugin install @feigi/fleet-ctl`, then restart; never run `omp plugin`
78
+ yourself. The baseline records the root it
73
79
  certified beside the digest, and every later check — yours, a finisher's, the
74
80
  merge gate's own leg — compares it with the live root and refuses when they
75
81
  differ. Never dispatch a member into a run whose phase-0 pin refused.