@feigi/fleet-ctl 3.105.6 → 3.106.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.
@@ -41,16 +41,16 @@ Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
41
41
  exit 2 (the check could not answer) both halt you: report what it printed,
42
42
  add no label, and do NOT re-read the script that gave you the reading.
43
43
  `--repo` is required and the spelling is the point — the run's baseline lives
44
- in the audited checkout's gitignored `.fleet/`, which the scratch worktree
44
+ in the main checkout's gitignored `.fleet/`, which the scratch worktree
45
45
  you take at duty 2 does not carry, so a bare invocation from there exits 2 on
46
46
  a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
47
47
  GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
48
48
  pointing this check at the wrong tree — the script's own internal unset
49
- cannot reach back and fix a path you already resolved wrong. The baseline
50
- itself names the tree to audit: a cross-workspace run pinned it once at
51
- phase 0, and your `--repo` only locates that baseline, never the audited
52
- tree — so an exit 2 naming a moved or unreadable audited tree is a halt
53
- like every other, not a spelling for you to correct.
49
+ cannot reach back and fix a path you already resolved wrong. The tree checked
50
+ is the Install root, the tree `fleet-run` executes, which the script resolves
51
+ for itself and `--repo` never names: your `--repo` only locates the baseline
52
+ — so an exit 2 naming a changed or unresolvable Install root is a halt like
53
+ every other, not a spelling for you to correct.
54
54
 
55
55
  **Confirm every deferral — and every claimed APPLY — has a home that outlives
56
56
  the merge.** A deferral of a finding in the review's result is not yours to
@@ -10,6 +10,7 @@ Read `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one*
10
10
  pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
11
11
  for late labels, then report once and exit. The controller dispatched you, which
12
12
  is what makes you hold that grace instead of arming your own watcher.
13
+ The grace ends early, with the report and the exit, once no PR is open.
13
14
 
14
15
  Your scratch directory is `<scratch>/`; you write only under
15
16
  `<scratch>/pr<N>/merge-bot-<n>/`.
@@ -319,6 +319,7 @@ Three dots, never two: a two-dot diff on a stale branch renders `main`'s gains a
319
319
 
320
320
  - Grace starts once no labelled PR is actionable — every one merged, skipped or held. Seed the labelled set then, the way **Then stay armed** seeds its Monitor, so a PR you already handled does not re-fire.
321
321
  - Every 60s, poll `gh pr list --state open --label ready-to-merge --limit 200 --json number`. A number not in the seed → **re-run selection from the top**, hold rule included, drain what it makes actionable, and restart the grace after that drain. A failed poll is no reading: keep the seed and poll again. A poll that returns 200 numbers is not a whole reading either — gh stops at `--limit` with exit 0 and no warning, so a label past it is unseen: act on the numbers it did return, and name `poll-capped-at-200` in the report, so the controller knows the grace's silence covered only the first 200.
322
+ - At grace start and on every 60s poll after it, also read `gh pr list --state open --limit 1 --json number`. An empty list (no PR open at all, any author, labelled or not) ends the grace: report and exit now. A failed read is no reading: keep waiting. It applies draining or not, and again after a late-label drain restarts the grace.
322
323
  - 15 minutes with no new label → report and exit.
323
324
 
324
325
  The wait:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.105.6",
3
+ "version": "3.106.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": {
@@ -1,10 +1,14 @@
1
1
  #!/bin/sh
2
2
  # Did the controller's instrument set change under it?
3
3
  #
4
- # The controller reads the world through scripts and runbooks that live in the
5
- # MAIN checkout, and every member can write to that checkout — except through a
6
- # `write`/`edit`/`ast_edit` that member-write-guard.mjs refuses; a
7
- # `bash` or `eval` write still lands. Worktree isolation
4
+ # The controller reads the world through scripts and runbooks it loads from
5
+ # the Install root — the realpath of
6
+ # `~/.omp/plugins/node_modules/@feigi/fleet-ctl`, the tree fleet-run executes
7
+ # and omp loads the runbooks from — and every member can write to that tree.
8
+ # member-write-guard.mjs refuses a `write`/`edit`/`ast_edit` inside the MAIN
9
+ # checkout only, which is the Install root only when that checkout is linked;
10
+ # a `bash` or `eval` write lands either way, and under a package install
11
+ # nothing refuses any of them. Worktree isolation
8
12
  # and `./agent-test` port derivation protect members from each other; neither
9
13
  # protects the tree the controller measures from. Measured: a member edited two
10
14
  # files in the main checkout instead of its worktree while the CI monitor was
@@ -27,13 +31,26 @@
27
31
  # that fails open on "could not look" protects nothing — the whole point is to
28
32
  # fail closed. The split survives only so the refusal can say WHICH it was: a
29
33
  # changed instrument is a finding about the tree, an unanswerable check is a
30
- # finding about this script. Both stop the gate.
34
+ # finding about this script. Both stop the gate. Only a digest mismatch is
35
+ # exit 1; every refusal to look, a changed Install root among them, is exit 2.
36
+ #
37
+ # WHAT IS IN THE SET: the plugin's own component directories — `commands/
38
+ # scripts/ skills/ agents/ workflows/` — of the Install root, the tree the
39
+ # fleet executes, never the checkout this script happens to run in. How the
40
+ # package entry is installed decides how the set is read, in one of two modes:
41
+ #
42
+ # linked-checkout any other link — GIT mode: every TRACKED file under
43
+ # `plugin/commands plugin/scripts plugin/skills
44
+ # plugin/agents plugin/workflows` of the checkout the
45
+ # link points into, which must be that checkout's
46
+ # `plugin/` directory exactly.
47
+ # npm-install a real directory — FILES mode: every regular file
48
+ # marketplace-install a link into `.omp/plugins/cache/` — and every symlink
49
+ # under the five directories of the realpath.
50
+ #
51
+ # The kinds are named the way fleet-provenance names them, and told apart the
52
+ # same way: the entry's own link-ness, then where the link resolves.
31
53
  #
32
- # WHAT IS IN THE SET: every tracked file under the plugin's own component
33
- # directories — `plugin/commands/ plugin/scripts/ plugin/skills/
34
- # plugin/agents/ plugin/workflows/` — contents read from the AUDITED
35
- # repository: the tree the baseline names (its recorded root, else the working
36
- # directory's checkout), or for a pin the tree named by `--audit` (see below).
37
54
  # Not a written list of instrument names — the
38
55
  # ticket named six and the class is larger (the supply scan, the liveness
39
56
  # probe, the shared `arg.mjs`/`json.sh`/`net.sh` libraries that a single edit
@@ -42,21 +59,28 @@
42
59
  # already knows can be stale). A list rots on the next commit that adds a
43
60
  # script; a directory does not.
44
61
  #
45
- # NOT THE WHOLE REPO, deliberately: the plugin's payload is
46
- # nested under `plugin/`, and the repo root also carries `docs/`, `.github/`
47
- # and `.out-of-scope/`. `docs/metrics/` is APPENDED BY THE CONTROLLER
48
- # MID-RUN, so a whole-repo set would fire the gate on the run's own
49
- # bookkeeping every single time — a guard the controller learns to ignore,
50
- # which is the failure the paragraph below names.
62
+ # NOT THE WHOLE TREE, deliberately, in either mode. A checkout's root also
63
+ # carries `docs/`, `.github/` and `.out-of-scope/`, and `docs/metrics/` is
64
+ # APPENDED BY THE CONTROLLER MID-RUN, so a whole-repo set would fire the gate
65
+ # on the run's own bookkeeping every single time — a guard the controller
66
+ # learns to ignore, which is the failure the paragraph below names. A
67
+ # package's `package.json`, and everything else at its top level, stays out
68
+ # the same way: the set is the five directories in both modes.
51
69
  #
52
- # TRACKED, deliberately: an untracked file appearing under those dirs — a
53
- # `.DS_Store`, an editor swap file, a member's scratch output — changes no
54
- # reading the controller takes, and refusing on it would fire the guard on
55
- # ordinary runs. A guard the controller learns to ignore is worse than none.
70
+ # TRACKED in a checkout, EVERY FILE in a package, deliberately. A checkout
71
+ # counts tracked files only, because an untracked file appearing under those
72
+ # dirs — a `.DS_Store`, an editor swap file, a member's scratch output —
73
+ # changes no reading the controller takes, and refusing on it would fire the
74
+ # guard on ordinary runs. A guard the controller learns to ignore is worse
75
+ # than none. A package counts every file, dotfiles included, because nothing
76
+ # in it is untracked and anything in it executes.
56
77
  #
57
78
  # CONTENT, not `git status`: status answers off the stat cache, so a content
58
79
  # change that lands on the same size and mtime does not reach it, and a bare
59
80
  # `touch` does. This hashes bytes, so it accepts a touch and refuses a rewrite.
81
+ # A symlink is hashed by its target's bytes in both modes — `shasum` reads
82
+ # through it — so a dangling link, or a link to a directory, cannot be hashed
83
+ # and refuses at exit 2.
60
84
  #
61
85
  # MODES ARE NOT IN THE DIGEST, and that one is a GAP rather than a trade: a
62
86
  # mode-only change to a tracked instrument is ACCEPTED. Measured — `chmod +x`
@@ -88,10 +112,13 @@
88
112
  # gate that is noise, and noise is the one failure this check cannot afford.
89
113
  # Sweeping for unexpected refs is a drain-cadence question, not a gate one.
90
114
  #
91
- # COST: two `git ls-files` (the state home's own set, which decides whether a
92
- # recorded root may be followed at all, and the audited tree's set) and one
93
- # pass of `shasum` over those files. No network, no `gh`, no fetch, no
94
- # subprocess per file. It is meant to be run
115
+ # COST: one `git rev-parse` to locate the state home, one listing of the set
116
+ # (`git ls-files` in git mode, `find` in files mode), a second `git rev-parse`
117
+ # in git mode to find the linked checkout, and one pass of `shasum` over those
118
+ # files; a pin in git mode also reads HEAD, a git-mode check that finds a
119
+ # change runs git again to report it, and a files-mode pin or changed check
120
+ # runs `awk` once to read the package's version. No network, no `gh`, no
121
+ # fetch, no subprocess per file. It is meant to be run
95
122
  # before every gate decision and it has to be cheap enough that nobody is
96
123
  # tempted to skip it.
97
124
  set -eu
@@ -103,9 +130,10 @@ set -eu
103
130
  # Here the only constraint left is the real one: above the first git call.
104
131
  #
105
132
  # GIT_WORK_TREE is the wrong-tree defect reached through the environment. The
106
- # contract here is that the audited tree is the WORKING
107
- # DIRECTORY's checkout — and `git rev-parse --show-toplevel` answers with the
108
- # ambient work tree instead the moment one is set, `--repo` or not. Measured:
133
+ # contract here is that the state home is the WORKING DIRECTORY's checkout and
134
+ # a linked install's tree is the checkout its link points into — and
135
+ # `git rev-parse --show-toplevel` answers with the ambient work tree instead
136
+ # the moment one is set, `--repo` or not. Measured:
109
137
  # standing in a checkout whose instruments have been TAMPERED, with
110
138
  # `GIT_WORK_TREE` naming a clean twin that carries its own pinned baseline,
111
139
  # this script exits 0 and prints the twin's digest. The gate passes. That is
@@ -114,7 +142,7 @@ set -eu
114
142
  # worse than no gate.
115
143
  #
116
144
  # GIT_DIR is unset alongside it and is measured INERT here: `ls-files` names
117
- # paths and the digest is taken over the FILES ON DISK under `$root`, so
145
+ # paths and the digest is taken over the FILES ON DISK under the tree, so
118
146
  # pointing the object database elsewhere changes nothing — measured against a
119
147
  # clean twin holding the exact pre-tamper content, the tampered digest came
120
148
  # back unchanged and the gate still refused. It stays on the line because the
@@ -136,24 +164,11 @@ baseline_field() { sed -n "/^$1=/{s/^$1=//;p;q;}" "$base"; }
136
164
 
137
165
  pin=false
138
166
  repo=""
139
- # The tree `--pin` certifies when it is NOT the state home's own checkout —
140
- # the cross-workspace case: a fleet running in a repo that does not track
141
- # `plugin/…` pins the marketplace/clone checkout that does, and the check
142
- # later follows THAT pointer, recorded beside the digest. Pin-only: a check
143
- # that let its caller repoint the tree would turn the baseline into a
144
- # suggestion.
145
- audit=""
146
167
  while [ $# -gt 0 ]; do
147
168
  case "$1" in
148
169
  --pin) pin=true; shift ;;
149
- --audit)
150
- [ $# -ge 2 ] || die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]"
151
- audit=$2
152
- [ -n "$audit" ] || die "--audit requires a non-empty path"
153
- shift 2
154
- ;;
155
170
  --repo)
156
- [ $# -ge 2 ] || die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]"
171
+ [ $# -ge 2 ] || die "usage: instruments.sh [--pin] [--repo <path>]"
157
172
  repo=$2
158
173
  # An empty value falls through the `[ -n "$repo" ]` branch below and
159
174
  # silently re-derives from cwd — measured: `--repo ""`
@@ -163,96 +178,39 @@ while [ $# -gt 0 ]; do
163
178
  [ -n "$repo" ] || die "--repo requires a non-empty path"
164
179
  shift 2
165
180
  ;;
166
- *) die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]" ;;
181
+ *) die "usage: instruments.sh [--pin] [--repo <path>]" ;;
167
182
  esac
168
183
  done
169
- [ -n "$audit" ] && [ "$pin" != true ] \
170
- && die "--audit is only accepted with --pin — a check audits the tree its baseline names, never one its caller names"
171
184
 
172
185
  # Two trees, named apart:
173
186
  #
174
187
  # `root` — the STATE HOME — is the WORKING DIRECTORY's checkout, never the
175
188
  # checkout this script happens to ship from. Under the install-only dev loop
176
- # this file runs out of a plugin cache — on a real install, under
177
- # `~/.omp/plugins/cache/...` — and the OLD own-location contract (`git -C
189
+ # this file runs out of the Install root — on a real install, under
190
+ # `~/.omp/plugins/...` — and the OLD own-location contract (`git -C
178
191
  # "$(dirname "$0")" …`) resolved it to whatever git checkout happens to
179
- # CONTAIN that cache path. Measured, pre-cutover: on a real box that
192
+ # CONTAIN that path. Measured, pre-cutover: on a real box that
180
193
  # was the operator's unrelated personal dotfiles checkout, and `--pin` run
181
194
  # that way writes `.fleet/instruments.sha` into it. `--repo <path>` is the
182
195
  # explicit override for the one legitimate case that needs a home other than
183
- # cwd's: auditing a named worktree from elsewhere. Resolution happens before
184
- # anything is read or written, so a cwd outside any checkout refuses here,
185
- # not partway through. The baseline lives here, so every reader that knows
186
- # only the run's workspace finds it without configuration.
196
+ # cwd's: reading a named checkout's baseline from elsewhere. Resolution
197
+ # happens before anything is read or written, so a cwd outside any checkout
198
+ # refuses here, not partway through. The state home only locates `.fleet/`:
199
+ # the baseline lives there, so every reader that knows only the run's
200
+ # workspace finds it without configuration, and nothing in it is hashed.
187
201
  #
188
- # `target` — the AUDITED TREE — is the checkout whose `plugin/…` files are
189
- # hashed. `--pin --audit <path>` names it for the cross-workspace case: a
190
- # fleet running in a repo that does not track `plugin/…` has no instrument
191
- # set to certify of its own (that empty set is exactly the refusal below),
192
- # so the pin certifies the plugin checkout that DOES and records its toplevel
193
- # beside the digest. A plain check then follows the RECORDED root, not cwd:
194
- # the pointer travels inside the baseline, from the same write as the digest,
195
- # so no later caller can repoint it. Absent a recorded root, target == root:
196
- # the shape every existing baseline was made over, byte-for-byte.
202
+ # `target` — the CERTIFIED TREE — is the live Install root, resolved below on
203
+ # every pin and every check and never taken from anywhere else.
197
204
  if [ -n "$repo" ]; then
198
205
  root=$(git -C "$repo" rev-parse --show-toplevel) \
199
- || die "$repo is not inside a git checkout — cannot identify the instrument set"
206
+ || die "$repo is not inside a git checkout — cannot locate the baseline"
200
207
  else
201
208
  root=$(git rev-parse --show-toplevel) \
202
- || die "the working directory is not inside a git checkout — cannot identify the instrument set (pass --repo <path> to audit a tree other than cwd's)"
209
+ || die "the working directory is not inside a git checkout — cannot locate the baseline (pass --repo <path> to name a checkout other than cwd's)"
203
210
  fi
204
-
205
- # `root` is the STATE HOME (the baseline's checkout, the run's own tree);
206
- # `target` is the AUDITED TREE the digest covers. They are the same tree in
207
- # every ordinary run.
208
- set='plugin/commands plugin/scripts plugin/skills plugin/agents plugin/workflows'
209
211
  base="$root/.fleet/instruments.sha"
210
212
 
211
- # Whether the state home tracks an instrument set OF ITS OWN decides if a
212
- # second tree may be named at all — and it is what closes the door a recorded
213
- # root would otherwise open: measured, a member who can write `.fleet/`
214
- # (member-write-guard does not stop `bash`) can keep the honest
215
- # run-start digest on line 1 and move `root=` to a pristine clone of the
216
- # workspace whose bytes match it — the old script hashed the tampered tree and
217
- # refused; a check that trusted the pointer would certify the clone and pass.
218
- # The pointer therefore rides on the SAME trust the digest has: honoured only
219
- # where the state home tracks no set of its own (the cross-workspace shape,
220
- # where the pointer is the only tree the check CAN audit), and `--audit` is
221
- # refused at the pin on a checkout that does track the set — so a forged pair
222
- # can only ever aim at a tree whose own audit stays intact.
223
- # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
224
- home=$(git -C "$root" ls-files -- $set) \
225
- || die "git ls-files failed under $root for: $set"
226
-
227
- target=$root
228
- if [ -n "$audit" ]; then
229
- [ -z "$home" ] || die "--audit names a tree outside this checkout only when this checkout tracks no instrument set; it tracks one — drop --audit and the pin audits its own tree"
230
- target=$(git -C "$audit" rev-parse --show-toplevel) \
231
- || die "$audit is not inside a git checkout — cannot identify the instrument set to pin"
232
- elif [ "$pin" = true ] && [ -z "$home" ]; then
233
- # The check path's unreadable-baseline refusals, mirrored here: a baseline
234
- # that EXISTS but cannot
235
- # be read names the tree this re-pin is supposed to keep certifying, and
236
- # overwriting it blind would discard the pointer with no record that it was
237
- # ever there.
238
- basedir="$(dirname "$base")"
239
- [ -d "$basedir" ] && [ ! -x "$basedir" ] \
240
- && die "$basedir exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
241
- { [ -e "$base" ] || [ -L "$base" ]; } && [ ! -r "$base" ] \
242
- && die "$base exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
243
- if [ -r "$base" ]; then
244
- prior=$(baseline_field root) || die "cannot read $base"
245
- [ -n "$prior" ] && target=$prior
246
- fi
247
- fi
248
-
249
213
  if [ "$pin" != true ]; then
250
- # A check reads its baseline BEFORE it hashes anything, because the baseline
251
- # names the tree to hash. A run pinned with `--audit` certified a checkout
252
- # other than this workspace's; standing here, the only honest comparison is
253
- # against THAT tree, and there is no cwd, flag, or config that says
254
- # otherwise — `--repo` moves the state home, never the audited tree.
255
- #
256
214
  # No baseline is not "nothing has changed" — it is a run that never pinned,
257
215
  # and the check has nothing to compare against. Refusing is the whole
258
216
  # contract.
@@ -282,65 +240,152 @@ if [ "$pin" != true ]; then
282
240
  [ -r "$base" ] || die "no baseline at $base — run instruments.sh --pin once at run start"
283
241
  want=$(sed -n '1p' "$base") || die "cannot read $base"
284
242
  [ -n "$want" ] || die "$base is empty — re-pin, do not guess"
285
-
286
- # The recorded root, if this baseline carries one. Absent — every baseline
287
- # pinned before the audited tree could live apart from the state home, and
288
- # every pin that CERTIFIED the state home itself — the audited tree IS the
289
- # state home, the shape that digest was made over.
290
- #
291
- # Honoured only where a foreign pointer is admissible at all: this
292
- # checkout's own recorded root is the shape every ordinary pin writes beside
293
- # its own digest and means nothing — hashing `rec` here is hashing `root`.
294
- # A FOREIGN pointer while the state home tracks a set of its own is the
295
- # alarm: a member who could rewrite `root=`, keeping the honest line-1
296
- # digest, would move the gate to a pristine clone whose bytes match it and
297
- # watch the check exit 0 over a tree nobody read. No legitimate pin of this
298
- # script can write that pair — the pin refuses `--audit` on a checkout that
299
- # tracks the set — so it is a baseline that does not belong to this home (a
300
- # moved or copied `.fleet/`, a clone that arrived carrying another
301
- # workspace's baseline) or a forgery. Both refuse; re-pin here fixes the
302
- # first and the second is the finding.
303
- rec=$(baseline_field root)
304
- if [ -n "$home" ] && [ -n "$rec" ] && [ "$rec" != "$root" ]; then
305
- die "baseline in $base certifies a foreign audited tree ($rec) while $root tracks its own instrument set — the baseline does not belong to this checkout, or was tampered with; refuse, do not re-read"
306
- fi
307
- if [ -n "$rec" ] && [ "$rec" != "$root" ]; then
308
- # Re-verified, not trusted. What this catches: the tree moved (the path
309
- # is now inside a DIFFERENT checkout, so `--show-toplevel` answers another
310
- # name), or stopped being one (deleted, de-repo'd) — both refuse, because
311
- # comparing a digest made over one tree against the bytes of nothing (or
312
- # of a parent repo's tree) is not an answer. What it cannot catch is a
313
- # REPLACEMENT: a checkout placed at the recorded path is audited by
314
- # content, and content matching line 1 is exactly as indistinguishable
315
- # from the pinned tree as a forged digest line is — no new power, and the
316
- # foreign-pointer guard above already refuses this whole channel for any
317
- # home that tracks a set of its own.
318
- again=$(git -C "$rec" rev-parse --show-toplevel 2>/dev/null) \
319
- || die "audited tree $rec (pinned in $base) is not a git checkout — the tree moved; refuse, do not re-read"
320
- [ "$again" = "$rec" ] \
321
- || die "audited tree moved: $rec now resolves to $again — refusing to certify a tree other than the one pinned"
322
- target=$rec
323
- fi
324
243
  fi
325
244
 
326
- # Hash the AUDITED tree — `$target`, which a baseline's recorded root may have
327
- # repointed above.
245
+ # The Install root, resolved inline on every pin and every check: the same
246
+ # path fleet-run, fleet-provenance and fleet-bootstrap resolve, the same way —
247
+ # the package entry's own link-ness for the kind, its realpath for the tree.
248
+ # Mirrored rather than called. The placed `~/.fleet/bin/fleet-run` can drift
249
+ # from the package, and an environment override or a `node` call would be a
250
+ # second way to name a tree the fleet does not execute.
328
251
  #
329
- # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
252
+ # HOME is checked by hand because `set -u` does not answer for it: measured,
253
+ # macOS `/bin/sh` exits 1 on an unset HOME under `set -eu`, and exit 1 is the
254
+ # one code that means the set changed.
255
+ [ -n "${HOME:-}" ] || die "HOME is unset — cannot resolve the Install root"
256
+ entry="$HOME/.omp/plugins/node_modules/@feigi/fleet-ctl"
257
+ if [ -L "$entry" ]; then
258
+ [ -e "$entry" ] || die "omp plugin \"@feigi/fleet-ctl\" link $entry is dangling"
259
+ live=$(CDPATH='' cd -P "$entry" && pwd -P) \
260
+ || die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
261
+ case $live in
262
+ */.omp/plugins/cache/*) kind=marketplace-install ;;
263
+ *) kind=linked-checkout ;;
264
+ esac
265
+ else
266
+ [ -e "$entry" ] || die "no omp plugin \"@feigi/fleet-ctl\" at $entry"
267
+ live=$(CDPATH='' cd -P "$entry" && pwd -P) \
268
+ || die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
269
+ kind=npm-install
270
+ fi
271
+
272
+ # A linked checkout is certified as the checkout it is — git mode, over the
273
+ # toplevel, the tree and the shape a checkout's pin has always been made over
274
+ # — and only when the link points at that checkout's `plugin/` directory
275
+ # exactly. A link to the checkout's root, to a nested copy of `plugin/`, or to
276
+ # a directory outside any checkout names a tree whose tracked set is not the
277
+ # one the fleet executes, so it refuses rather than guess which it meant.
278
+ dirs='commands scripts skills agents workflows'
279
+ set=
280
+ for d in $dirs; do set="${set:+$set }plugin/$d"; done
281
+ if [ "$kind" = linked-checkout ]; then
282
+ mode=git
283
+ badlink="Install root $live is not the plugin/ directory of a git checkout — a linked install must point at <checkout>/plugin"
284
+ target=$(git -C "$live" rev-parse --show-toplevel 2>/dev/null) || die "$badlink"
285
+ [ "$live" = "$target/plugin" ] || die "$badlink"
286
+ else
287
+ mode=files
288
+ target=$live
289
+ fi
290
+
291
+ # The top-level "version" of the package's `package.json`, or nothing. It is
292
+ # evidence for a refusal to name, never part of a verdict, so a file that is
293
+ # missing, unparseable or carries no string version reads as unknown rather
294
+ # than refusing. A brace-depth scan rather than a line match: a nested
295
+ # "version" key (an `engines` entry, say) must not answer for the package.
296
+ pkg_version() {
297
+ v=$(awk '
298
+ { s = s $0 "\n" }
299
+ END {
300
+ n = length(s); depth = 0; i = 1
301
+ while (i <= n) {
302
+ c = substr(s, i, 1)
303
+ if (c == "\"") {
304
+ k = ""; i++
305
+ while (i <= n && (c = substr(s, i, 1)) != "\"") {
306
+ if (c == "\\") { k = k c substr(s, i + 1, 1); i += 2 } else { k = k c; i++ }
307
+ }
308
+ i++
309
+ if (depth == 1 && k == "version") {
310
+ while (substr(s, i, 1) ~ /[ \t\r\n]/) i++
311
+ if (substr(s, i, 1) != ":") continue
312
+ i++
313
+ while (substr(s, i, 1) ~ /[ \t\r\n]/) i++
314
+ if (substr(s, i, 1) != "\"") exit
315
+ j = i + 1; out = ""
316
+ while (j <= n && (c = substr(s, j, 1)) != "\"") { out = out c; j++ }
317
+ if (j <= n) print out
318
+ exit
319
+ }
320
+ continue
321
+ }
322
+ if (c == "{" || c == "[") depth++
323
+ else if (c == "}" || c == "]") depth--
324
+ i++
325
+ }
326
+ }' "$target/package.json" 2>/dev/null) || v=
327
+ case $v in
328
+ *[!0-9A-Za-z.+-]*) v= ;;
329
+ esac
330
+ printf '%s' "$v"
331
+ }
332
+
333
+ if [ "$pin" != true ]; then
334
+ # The check takes its tree from the live Install root and from nothing else.
335
+ # The baseline's `root=` is evidence of which tree the pin certified, never
336
+ # a path to follow: a check that hashed it would let anyone who can write
337
+ # `.fleet/` keep the honest digest on line 1, point `root=` at a
338
+ # byte-identical clone, and watch the clone certify. Compared instead, a
339
+ # forged `root=` can only make the check refuse. Any difference is a
340
+ # different tree under the same gate: an upgrade or a reinstall that moved
341
+ # the realpath, a switch between a package and a link, a link retargeted, or
342
+ # a baseline from before the root was recorded. Equal roots imply equal
343
+ # kinds, so the root alone answers for a kind change too. Exit 2, before
344
+ # anything is hashed: the question "did this tree change?" has no answer
345
+ # against a digest made over another one.
346
+ rec=$(baseline_field root) || die "cannot read $base"
347
+ [ "$rec" = "$target" ] \
348
+ || die "Install root now resolves to $target ($kind), pinned ${rec:-<none recorded>} — the installed plugin changed under this run; the maintainer adopts it (re-pin) or restores the pinned install"
349
+ fi
350
+
351
+ # Hash the certified tree.
330
352
  files=$(mktemp) || die "cannot create a temp file"
331
353
  # INT/HUP/TERM as well as EXIT: a controller that kills a stalled gate check
332
354
  # should not leave the temp file behind on a shared machine.
333
355
  trap 'rm -f "$files"' EXIT
334
356
  trap 'rm -f "$files"; exit 2' INT HUP TERM
335
357
 
336
- # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
337
- git -C "$target" ls-files -z -- $set > "$files" \
338
- || die "git ls-files failed under $target for: $set"
339
- # An empty listing is the shape a wrong root produces — a symlinked skills dir
340
- # resolving to a different repository, most plausibly, or a workspace that
341
- # simply does not vendor the plugin. Certifying it would hand back "unchanged"
342
- # for a set that was never read.
343
- [ -s "$files" ] || die "no tracked file under $target for: $set — refusing to certify an empty instrument set"
358
+ if [ "$mode" = git ]; then
359
+ # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
360
+ git -C "$target" ls-files -z -- $set > "$files" \
361
+ || die "git ls-files failed under $target for: $set"
362
+ # An empty listing is the shape a wrong tree produces — a symlinked skills
363
+ # dir resolving to a different repository, most plausibly. Certifying it
364
+ # would hand back "unchanged" for a set that was never read.
365
+ [ -s "$files" ] || die "no tracked file under $target for: $set — refusing to certify an empty instrument set"
366
+ else
367
+ # Absent directories are skipped, but a name that is present in any form
368
+ # — a file, a dangling link — is listed, so it reaches `shasum` and refuses
369
+ # there rather than vanishing from the set. With none present there is
370
+ # nothing to certify, and `find` given no path would list `.` instead.
371
+ present=
372
+ for d in $dirs; do
373
+ if [ -e "$target/$d" ] || [ -L "$target/$d" ]; then
374
+ present="$present $d"
375
+ fi
376
+ done
377
+ [ -n "$present" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
378
+ # Paths relative to the realpath, NUL-separated, in byte order: `find`
379
+ # lists in directory order, which is the filesystem's to choose, so the
380
+ # sort is what makes the digest a function of the tree alone. Two steps
381
+ # with a status check each, for the reason the hashing below spells out.
382
+ # shellcheck disable=SC2086 # $present is a list of fixed directory names
383
+ (cd "$target" && find $present \( -type f -o -type l \) -print0) > "$files" \
384
+ || die "could not list every file under $target for: $dirs"
385
+ LC_ALL=C sort -z -o "$files" "$files" \
386
+ || die "could not sort the instrument set under $target"
387
+ [ -s "$files" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
388
+ fi
344
389
 
345
390
  # Two steps, each with its own status check, because a pipeline reports only its
346
391
  # LAST command: with `xargs … | shasum` as one pipeline, a `shasum` that cannot
@@ -350,38 +395,44 @@ git -C "$target" ls-files -z -- $set > "$files" \
350
395
  # bug against `git cherry` and it deleted branches.
351
396
  #
352
397
  # `xargs` exits 123 when `shasum` failed on any file, which is how a tracked
353
- # file deleted from the worktree arrives: as exit 2 naming it, not as a digest
354
- # quietly missing a line. Both refuse; only one of them is honest about why.
398
+ # file deleted from the worktree arrives — and a dangling link, or a link to a
399
+ # directory: as exit 2 naming it, not as a digest quietly missing a line. Both
400
+ # refuse; only one of them is honest about why.
355
401
  per_file=$(cd "$target" && xargs -0 shasum -a 256 < "$files") \
356
- || die "could not hash every tracked file under $set — see the errors above"
402
+ || die "could not hash every tracked file under $target — see the errors above"
357
403
  digest=$(printf '%s\n' "$per_file" | shasum -a 256 | cut -d' ' -f1) \
358
404
  || die "could not digest the instrument set"
359
- [ -n "$digest" ] || die "empty digest for $target ($set)"
405
+ [ -n "$digest" ] || die "empty digest for $target"
360
406
 
361
407
  if [ "$pin" = true ]; then
362
408
  mkdir -p "$root/.fleet" || die "cannot create $root/.fleet"
363
- # Three lines, order fixed: the digest first, the audited tree's toplevel
364
- # second, the audited tree's HEAD commit third. A reader that only knows the
365
- # old one-line shape — merge-gate.mjs's `readInstruments`, which takes the
366
- # FIRST stdout line as the digest — keeps working, and a check from this
367
- # script reads the rest. The root rides in the same write as the digest
368
- # because it is not a suggestion: a pointer an attacker with a writable
369
- # `.fleet/` could repoint at will would move the gate to a tree they control,
370
- # so the check trusts nothing else, re-verifies the tree at check time, and
371
- # refuses if it moved.
409
+ # Three lines, order fixed: the digest first, the certified tree second, and
410
+ # third what says which state of it was pinned — the checkout's HEAD commit
411
+ # in git mode, the package's version in files mode. A reader that only
412
+ # knows the old one-line shape — merge-gate.mjs's `readInstruments`, which
413
+ # takes the FIRST stdout line as the digest — keeps working, and a check
414
+ # from this script reads the rest. The root rides in the same write as the
415
+ # digest so a check can tell the Install root moved; the check compares it
416
+ # and never follows it.
372
417
  #
373
- # The commit is not trusted for any verdict: it exists only so a refusal can
374
- # say what moved. HEAD unborn or unreadable writes no `commit=` line, and
375
- # the refusal says so; a baseline from before this line existed reads the
376
- # same way.
377
- commit=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || commit=
418
+ # Neither third line is trusted for any verdict: each exists only so a
419
+ # refusal can say what moved. HEAD unborn or unreadable writes no `commit=`
420
+ # line, a package with no readable version writes no `version=` line, and
421
+ # the refusal says so.
422
+ if [ "$mode" = git ]; then
423
+ key=commit
424
+ val=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || val=
425
+ else
426
+ key=version
427
+ val=$(pkg_version)
428
+ fi
378
429
  {
379
430
  printf '%s\n' "$digest"
380
431
  printf 'root=%s\n' "$target"
381
- [ -z "$commit" ] || printf 'commit=%s\n' "$commit"
432
+ [ -z "$val" ] || printf '%s=%s\n' "$key" "$val"
382
433
  } > "$base" || die "cannot write $base"
383
434
  printf '%s\n' "$digest"
384
- printf '%s: pinned %s over %s\n' "$NAME" "$digest" "$target ($set)" >&2
435
+ printf '%s: pinned %s over %s %s (%s %s)\n' "$NAME" "$digest" "$kind" "$target" "$key" "${val:-?}" >&2
385
436
  exit 0
386
437
  fi
387
438
 
@@ -391,13 +442,25 @@ if [ "$digest" = "$want" ]; then
391
442
  fi
392
443
 
393
444
  # Cold path only, so it costs the ordinary run nothing. The controller has to
394
- # report WHAT changed, and neither digest says. `git status` names the
395
- # uncommitted half, which is the shape this header's measured near-miss took; a
396
- # checked-out branch that moved shows as nothing here and the HEAD line is what
397
- # names it. Both are read from the AUDITED tree, which is the one the verdict
398
- # is about — not the state home the baseline was found in.
445
+ # report WHAT changed, and neither digest says.
399
446
  printf '%s: instrument set CHANGED under this run — expected %s\n' "$NAME" "$want" >&2
400
447
  printf '%s: refuse the gate and report. Do NOT re-read the instrument.\n' "$NAME" >&2
448
+
449
+ # A package has no HEAD and no status to read, and anything in it may have
450
+ # changed: the versions are what the maintainer rules on — adopt what is
451
+ # installed, or put the pinned version back. Never the controller: a
452
+ # reinstall swaps the files every live member is running.
453
+ if [ "$mode" = files ]; then
454
+ pinv=$(baseline_field version) || pinv=
455
+ nowv=$(pkg_version)
456
+ printf '%s: %s %s: version %s pinned, %s now\n' "$NAME" "$kind" "$target" "${pinv:-?}" "${nowv:-?}" >&2
457
+ printf '%s: the installed package changed or was reinstalled — the maintainer adopts it (re-pin) or restores version %s\n' "$NAME" "${pinv:-?}" >&2
458
+ exit 1
459
+ fi
460
+
461
+ # A checkout: `git status` names the uncommitted half, which is the shape
462
+ # this header's measured near-miss took; a checked-out branch that moved
463
+ # shows as nothing here and the HEAD line is what names it.
401
464
  headc=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || headc=
402
465
  printf '%s: HEAD %s\n' "$NAME" "${headc:-?}" >&2
403
466
  # shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
@@ -225,10 +225,11 @@ const CHILD = { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] };
225
225
  // own top level: from a worktree that has no baseline, and instruments.sh
226
226
  // exits 2 on a missing baseline instead of comparing anything. gitEnv():
227
227
  // an ambient GIT_DIR would otherwise answer `--git-common-dir` for a
228
- // different repository, and the gate would certify that tree's instruments.
229
- // `--repo` locates the baseline only; the baseline itself names the tree to
230
- // audit, so a workspace that does not track `plugin/…` still reaches a
231
- // verdict over the checkout its run pinned — no flag here repoints it.
228
+ // different repository, and the gate would judge against that repository's
229
+ // baseline. `--repo` locates the baseline only: instruments.sh certifies the
230
+ // live Install root and compares it with the baseline's `root=`, never
231
+ // following it, so a workspace that does not track `plugin/…` still reaches a
232
+ // verdict and no flag here repoints the audited tree.
232
233
  // `root` is returned too: main-gain.mjs reads the same main checkout.
233
234
  function readInstruments() {
234
235
  const common = spawnSync("git", ["rev-parse", "--git-common-dir"], { ...CHILD, env: gitEnv() });
@@ -2,7 +2,7 @@
2
2
  // Phase 0 as one command: the run's start sequence, in order, with a receipt.
3
3
  //
4
4
  // phase0.mjs [--session <dir>] [--in-flight n] [--objective cost|speed]
5
- // [--plugin-checkout <dir>] [--spend-dir <dir>]
5
+ // [--spend-dir <dir>]
6
6
  // [--workflow <name> | --declare-no-ci]
7
7
  //
8
8
  // The session directory is `--session`, else `PI_ARTIFACTS_DIR`, which omp
@@ -33,8 +33,8 @@
33
33
  // script came from are superseded: prints `SUPERSEDED <n>
34
34
  // commits; re-run phase0.mjs` and fails, so the re-run executes
35
35
  // from the new tree.
36
- // pin `instruments.sh --pin`, with `--audit <plugin-checkout>` when
37
- // given (a workspace that tracks no `plugin/…` of its own).
36
+ // pin `instruments.sh --pin`, which certifies the Install root; the
37
+ // ok line names its kind, root, and version or commit.
38
38
  // baseline `main-checkout.mjs --record`; its refusals fail the step.
39
39
  // preflight `preflight.mjs`. A non-zero exit fails the step; the FAIL, WARN
40
40
  // and PREFLIGHT lines of an exit 1 are printed.
@@ -225,10 +225,12 @@ function fastForward({ cwd }) {
225
225
  return failed(`SUPERSEDED ${behind} commits; re-run phase0.mjs`);
226
226
  }
227
227
 
228
- function pin({ cwd, pluginCheckout }) {
229
- const r = sh("instruments.sh", ["--pin", ...(pluginCheckout ? ["--audit", pluginCheckout] : [])], { cwd });
228
+ function pin({ cwd }) {
229
+ const r = sh("instruments.sh", ["--pin"], { cwd });
230
230
  if (r.status !== 0) return refusal("instruments.sh --pin failed:", r);
231
- return ok(pluginCheckout ? `instruments pinned, auditing ${pluginCheckout}` : "instruments pinned");
231
+ // `instruments: pinned <digest> over <kind> <root> (version <v>|commit <sha>)`
232
+ const m = /^instruments: pinned [0-9a-f]+ over (.+)$/m.exec(r.stderr);
233
+ return ok(`instruments pinned: ${m ? m[1] : r.stderr || "?"}`);
232
234
  }
233
235
 
234
236
  function baseline({ cwd }) {
@@ -545,7 +547,7 @@ function main() {
545
547
  const die = makeDie(NAME);
546
548
  const F = defineFlags(die, {
547
549
  flags: {
548
- session: "value", "in-flight": "value", objective: "value", "plugin-checkout": "value",
550
+ session: "value", "in-flight": "value", objective: "value",
549
551
  "spend-dir": "value", workflow: "value", "declare-no-ci": "bool",
550
552
  },
551
553
  });
@@ -587,9 +589,7 @@ function main() {
587
589
  if (named !== null && !OBJECTIVES.includes(named)) die(`--objective needs ${OBJECTIVES.join(" or ")}, got ${named}`);
588
590
  if (F.has("declare-no-ci") && !absent("workflow")) die("--workflow and --declare-no-ci are alternatives, not a pair");
589
591
  const ci = F.has("declare-no-ci") ? "CI: declared absent (--declare-no-ci)" : absent("workflow") ? null : `CI: workflow ${F.arg("workflow")} (--workflow)`;
590
- const pathOf = (name) => (absent(name) ? null : resolve(F.arg(name)));
591
- const pluginCheckout = pathOf("plugin-checkout");
592
- const spendDir = pathOf("spend-dir");
592
+ const spendDir = absent("spend-dir") ? null : resolve(F.arg("spend-dir"));
593
593
 
594
594
  let fleetDir;
595
595
  try {
@@ -668,7 +668,7 @@ function main() {
668
668
  receipt.steps[name] = was?.status === "ok" ? was : { status: "pending", at: now, output: "not run" };
669
669
  }
670
670
 
671
- const ctx = { cwd, fleetDir, held, receipt, receiptPath, scratch, pluginCheckout, spendDir, ci };
671
+ const ctx = { cwd, fleetDir, held, receipt, receiptPath, scratch, spendDir, ci };
672
672
  const say = (line) => process.stdout.write(`${line}\n`);
673
673
  say(`session ${session} (from ${source})`);
674
674
  let stop = null;
@@ -41,8 +41,7 @@ Nothing in this phase, or in any later one, asks the maintainer which tickets to
41
41
  cell in this main checkout, without `--session`:
42
42
  `subprocess.run([os.path.expanduser("~/.fleet/bin/fleet-run"),
43
43
  "phase0.mjs", …], stderr=subprocess.STDOUT)`. Add `--in-flight <n>` and
44
- `--objective <o>` as `$ARGUMENTS` gave them, `--plugin-checkout <dir>` when
45
- this workspace tracks no `plugin/…` of its own, `--spend-dir <dir>` for the
44
+ `--objective <o>` as `$ARGUMENTS` gave them, `--spend-dir <dir>` for the
46
45
  spend panel, and `--workflow <name>` or `--declare-no-ci`
47
46
  when the repository has no workflow named CI. Its steps and receipt: See
48
47
  references/phase-0.md. Dispatch nothing before it exits 0. Exit 4 is a
@@ -700,16 +699,21 @@ you cannot confirm was received, re-check the artifacts it governed. See referen
700
699
  is the one legitimate writer. Re-pinning to clear a refusal you cannot
701
700
  explain discards the check.
702
701
  - **A pinned tree whose HEAD moved is the maintainer's to settle, whoever moved
703
- it.** When a refusal — your check or a finisher's halt — reads HEAD advanced,
704
- rewound or diverged from the pin commit, never re-pin over it: not for a
705
- fast-forward to `origin/main`, and not when the commits between are only this
706
- run's own merged PRs. Act on no `DISPATCH` or `PULL` row, and tell the
707
- maintainer the pin commit, HEAD and the commits between, as the refusal
708
- printed them. On their **restore**, run `git reset --keep <pin commit>` —
702
+ it — and so is an installed plugin that changed.** When a refusal — your check
703
+ or a finisher's halt — reads HEAD advanced, rewound or diverged from the pin
704
+ commit, never re-pin over it: not for a fast-forward to `origin/main`, and not
705
+ when the commits between are only this run's own merged PRs. The same holds
706
+ when it names a changed package or an Install root that now resolves
707
+ elsewhere, even an upgrade to a release of this run's own PRs. Act on no
708
+ `DISPATCH` or `PULL` row, and tell the maintainer what the refusal printed:
709
+ the pin commit, HEAD and the commits between, or the pinned and current
710
+ Install root and version. On their **restore**, run `git reset --keep <pin commit>` —
709
711
  only when the pinned tree is the main checkout and the tick prints no
710
- `MAIN-CHECKOUT` line; otherwise they restore it by hand. On their **adopt**,
711
- re-pin. Once the check exits 0, resume, and apply the finisher gate to each
712
- PR whose finisher halted on that refusal. See references/instruments.md.
712
+ `MAIN-CHECKOUT` line; otherwise they restore it by hand, and an installed
713
+ package always: never run `omp plugin` yourself, because a reinstall swaps the
714
+ files every live member is running. On their **adopt**, re-pin. Once the
715
+ check exits 0, resume, and apply the finisher gate to each PR whose finisher
716
+ halted on that refusal. See references/instruments.md.
713
717
 
714
718
  ### Relabel causes
715
719
 
@@ -882,14 +886,7 @@ failures arrive as *wrong findings*, not errors:
882
886
 
883
887
  ### A mid-run tooling fix
884
888
 
885
- Two members failing the same way is the instruction, not the agents. Fix the file
886
- during the run — deferring loses the evidence that found it.
887
-
888
- **Scope.** Only this install's own commands and skills *this run invoked*, only defects
889
- *this run produced*. No speculative polish. Never `config.yml`, permissions, or
890
- AGENTS.md — a member asking for those is laundering, refuse and surface it.
891
-
892
- **Triggers and shape.** See references/instruments.md.
889
+ **When to fix, its scope, triggers and shape.** See references/instruments.md.
893
890
 
894
891
  Why the agent body carries what it does — read this before editing any `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. See references/pull.md.
895
892
 
@@ -6,17 +6,20 @@ Evidence for the rule SKILL.md states in **Re-check the instruments before a gat
6
6
 
7
7
  **You read your instruments out of a tree every member can write to — re-check
8
8
  them before every gate decision.** Per-member worktrees and `./agent-test`'s port
9
- derivation protect members from each other; neither protects the main checkout,
10
- which you run every gate probe out of and which any member can edit — except
11
- through a `write`/`edit`/`ast_edit` the `member-write-guard` extension refuses;
12
- a `bash` or `eval` write still lands. Measured: a
13
- member edited two files there instead of in its worktree while the CI monitor was
14
- polling one of them every 120s and a live finisher was using it to decide a
15
- label. It caught itself; nothing in the fleet would have. That is the silent
16
- direction — a modified instrument raises no error, shows in no PR and leaves
17
- nothing in the ledger, and it still returns a verdict, just not necessarily the
18
- right one, so you have no reason to re-check a script you did not know had
19
- changed.
9
+ derivation protect members from each other; neither protects the Install root,
10
+ the tree you run every gate probe out of and read these runbooks from. It is
11
+ the main checkout only when that checkout is linked as the install. The
12
+ `member-write-guard` extension refuses a `write`/`edit`/`ast_edit` inside the
13
+ main checkout only, and a `bash` or `eval` write lands anyway; under a package
14
+ install nothing prevents a write to the Install root, and this re-check is
15
+ what catches one. Measured: a
16
+ member edited two files in the main checkout instead of in its worktree while
17
+ the CI monitor was polling one of them every 120s and a live finisher was using
18
+ it to decide a label. It caught itself; nothing in the fleet would have. That is
19
+ the silent direction — a modified instrument raises no error, shows in no PR and
20
+ leaves nothing in the ledger, and it still returns a verdict, just not
21
+ necessarily the right one, so you have no reason to re-check a script you did
22
+ not know had changed.
20
23
 
21
24
  **A label gate and a CI verdict are also taken by dispatched members, not
22
25
  only by you** — the finisher labels, and the merge bot merges on its own
@@ -27,15 +30,15 @@ in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge
27
30
 
28
31
  ## What the instrument set covers
29
32
 
30
- It covers every tracked file under this repo's own plugin component directories
31
- — `plugin/commands/`, `plugin/scripts/`, `plugin/skills/`, `plugin/agents/`,
32
- `plugin/workflows/` — the probes, the libraries they source, and these runbooks,
33
- which you also read from that tree. Not the whole repo: `docs/metrics/` is
34
- appended by THIS run, so covering it would refuse on the run's own bookkeeping
35
- every time. It does not cover refs, deliberately: `claim-ticket.sh` creates a
36
- branch per ticket and `reap.sh` deletes them in the ref store every worktree
37
- shares, so ordinary work moves refs several times a run and a per-gate
38
- refusal on that is noise.
33
+ It covers the Install root's plugin component directories — `commands/`,
34
+ `scripts/`, `skills/`, `agents/`, `workflows/` — the probes, the libraries they
35
+ source, and these runbooks, which you also read from that tree: the tracked
36
+ files of a linked checkout's `plugin/…`, or every file of an installed package.
37
+ Not the whole repo: `docs/metrics/` is appended by THIS run, so covering it
38
+ would refuse on the run's own bookkeeping every time. It does not cover refs,
39
+ deliberately: `claim-ticket.sh` creates a branch per ticket and `reap.sh`
40
+ deletes them in the ref store every worktree shares, so ordinary work moves
41
+ refs several times a run and a per-gate refusal on that is noise.
39
42
 
40
43
  ## Re-pin first after a mid-run tooling fix
41
44
 
@@ -45,6 +48,13 @@ fix, which teaches you to ignore the refusal.
45
48
 
46
49
  ## Triggers and shape of a mid-run tooling fix
47
50
 
51
+ Two members failing the same way is the instruction, not the agents. Fix the file
52
+ during the run — deferring loses the evidence that found it.
53
+
54
+ **Scope.** Only this install's own commands and skills *this run invoked*, only defects
55
+ *this run produced*. No speculative polish. Never `config.yml`, permissions, or
56
+ AGENTS.md — a member asking for those is laundering, refuse and surface it.
57
+
48
58
  Fix on an identical failure twice, or on a member doing the wrong thing while
49
59
  following the text; prefer moving text to adding it, and cut before you append.
50
60
 
@@ -69,8 +79,9 @@ hold the old text — re-brief only if it changes what they do *now*.
69
79
 
70
80
  ## A pinned tree whose HEAD moved is the maintainer's to settle
71
81
 
72
- `instruments.sh --pin` records the pinned tree's HEAD as `commit=<sha>` after
73
- the digest and `root=`, and an exit-1 refusal prints that pin commit and how
82
+ Pinned from a linked checkout, `instruments.sh --pin` records the checkout's
83
+ HEAD as `commit=<sha>` after the digest and `root=`, and an exit-1 refusal
84
+ prints that pin commit and how
74
85
  HEAD relates to it: `advanced` (the pin commit is an ancestor of HEAD, with the
75
86
  commits between, at most 20 and then `… N more`), `rewound`, `diverged`, or
76
87
  `unmoved` (HEAD is the pin commit, so the porcelain lines name the edits). When
@@ -80,6 +91,16 @@ not the pin commit there either, so never re-pin over it. A baseline with no
80
91
  `commit=` line, or one whose commit is gone from the repository, prints one
81
92
  line saying so and no relation.
82
93
 
94
+ **An installed package has no HEAD.** Pinned from an npm or marketplace
95
+ install, the baseline records the package's `version=` in place of a commit,
96
+ and an exit-1 refusal names the pinned version and the current one, with no
97
+ git output. An Install root that now resolves elsewhere than the pinned one —
98
+ a reinstall that moved it, a switch between a package and a linked checkout,
99
+ a link pointed elsewhere — refuses at exit 2, naming the pinned root and the
100
+ current one. Restore is the maintainer reinstalling the pinned version by
101
+ hand, never the controller: a reinstall swaps the files under every live
102
+ member.
103
+
83
104
  **The measured case.** Another session fast-forwarded the main checkout to
84
105
  `origin/main` mid-run. The commits that brought in were only this run's own
85
106
  merged PRs, the controller counted them as its own, re-pinned without asking and
@@ -60,20 +60,17 @@ construction: stale text reads as authoritative.
60
60
 
61
61
  **Pin the instruments, after that fast-forward and before anything reads
62
62
  them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
63
- records what the scripts and runbooks in this repo say right now, which is
64
- what every later gate compares against; SKILL.md's **Re-check before you act
65
- on any instrument reading** says what its exit codes mean. Pinning before that fast-forward would instead pin the
66
- superseded text and certify it for the rest of the run.
67
- **When this workspace does not track `plugin/…`** — fleets run here on an
68
- installed plugin rather than a vendored tree — the bare pin refuses on an
69
- empty instrument set, because this checkout holds no instruments to certify.
70
- Name the plugin checkout to the pin instead:
71
- `~/.fleet/bin/fleet-run instruments.sh --pin --audit <plugin-checkout>`.
72
- The baseline records the audited tree beside the digest, and every later
73
- check — yours, a finisher's, the merge gate's own leg — follows that
74
- recorded root without being told twice. Refusing the bare pin and naming
75
- the tree once is the whole cross-workspace contract; never dispatch a
76
- member into a run whose phase-0 pin refused.
63
+ records what the scripts and runbooks of the Install root — the tree the
64
+ fleet executes — say right now, which is what every later gate compares
65
+ against; SKILL.md's **Re-check before you act on any instrument reading** says
66
+ what its exit codes mean. When this main checkout is the linked install,
67
+ pinning before that fast-forward would instead pin the superseded text and
68
+ certify it for the rest of the run. The pin certifies the Install root and
69
+ keeps its baseline in this checkout's `.fleet/`, so a workspace that tracks no
70
+ `plugin/…` of its own pins with no flag. The baseline records the root it
71
+ certified beside the digest, and every later check — yours, a finisher's, the
72
+ merge gate's own leg — compares it with the live root and refuses when they
73
+ differ. Never dispatch a member into a run whose phase-0 pin refused.
77
74
 
78
75
  ## Record the main-checkout baseline
79
76