@feigi/fleet-ctl 3.106.0 → 3.107.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.106.0",
3
+ "version": "3.107.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -23,8 +23,10 @@
23
23
  // which session is this run's. The run says it: phase 0 records the
24
24
  // controller's own session directory in its receipt, `.fleet/phase0.json`,
25
25
  // and receiptSpendDir() below reads it back on every tick — never latched,
26
- // because a cockpit outlives the run that launched it and has to follow the
27
- // next run's receipt. `--spend-dir <path>` overrides the receipt outright.
26
+ // because a cockpit lives as long as its run's controller, which can start
27
+ // another run from the same omp session, and a phase-0 relaunch reuses a
28
+ // running server; either way it has to follow the next run's receipt.
29
+ // `--spend-dir <path>` overrides the receipt outright.
28
30
 
29
31
  import { readFileSync, existsSync, statSync } from "node:fs";
30
32
  import { computeSpend, attributeTools, mergeTools } from "./compute-spend.mjs";
@@ -405,9 +407,10 @@ export function mapCi(ciJson, pr) {
405
407
  // the directory its ledger and heartbeat come from, so the three cannot
406
408
  // disagree about which run they belong to — through phase0-receipt.mjs's
407
409
  // readReceipt, the one reading of that file. The caller reads it on EVERY
408
- // tick and keeps nothing: a cockpit survives across runs (a phase-0 relaunch
409
- // reuses a running server), so a session held from an earlier tick would
410
- // keep showing the previous run's spend once the next run's receipt lands.
410
+ // tick and keeps nothing: a cockpit survives across runs (a new run from the
411
+ // same omp session keeps it, and a phase-0 relaunch reuses a running server),
412
+ // so a session held from an earlier tick would keep showing the previous
413
+ // run's spend once the next run's receipt lands.
411
414
  //
412
415
  // A receipt with no session to give is `{ error }`, which the panel shows:
413
416
  // the board names no session rather than guessing one. So is a recorded
@@ -578,14 +578,13 @@ export async function serve({ port: portGiven, interval, open, tick }) {
578
578
  // a turn of the loop costs nothing.
579
579
  await new Promise((resolve) => setImmediate(resolve));
580
580
 
581
- // Deliberately not awaited: the first tick is the slow one, and everything
582
- // below it — the timer, and the two signal handlers that are the only way
583
- // this process is ever asked to stop — must be in place before it returns,
584
- // not after. Nothing here rejects; tick() catches its own faults and the
585
- // `ticking` flag it sets is cleared in a finally (see boardTick()).
581
+ // A tick that answers `true` has written its board and found the run's
582
+ // controller gone: the cockpit lives as long as that controller, and stop()
583
+ // below is its way out, the same one a signal takes. Any other answer, a
584
+ // skipped tick's `undefined` included, serves on.
586
585
  const tickArgs = { served: bound, stateDir, jsonPath, workspace: instance.workspace };
587
- tick(tickArgs);
588
- const timer = setInterval(() => tick(tickArgs), interval * 1000);
586
+ const runTick = async () => { if (await tick(tickArgs) === true) stop(); };
587
+ const timer = setInterval(runTick, interval * 1000);
589
588
 
590
589
  const stop = () => {
591
590
  clearInterval(timer);
@@ -595,6 +594,11 @@ export async function serve({ port: portGiven, interval, open, tick }) {
595
594
  };
596
595
  process.on("SIGINT", stop);
597
596
  process.on("SIGTERM", stop);
597
+ // Deliberately not awaited: the first tick is the slow one, and the timer
598
+ // and both signal handlers above are already in place. Nothing here
599
+ // rejects; tick() catches its own faults and the `ticking` flag it sets is
600
+ // cleared in a finally (see boardTick()).
601
+ runTick();
598
602
 
599
603
  // --open, from this launch alone: it is the one that bound a port and
600
604
  // started a server, and the reuse arms above open nothing. Only
@@ -607,5 +611,5 @@ export async function serve({ port: portGiven, interval, open, tick }) {
607
611
  // could hold the first tick back for the whole session. openBrowser()
608
612
  // never throws; a launcher that is missing or fails is one warning line.
609
613
  if (open) await openBrowser(`http://${COCKPIT_HOST}:${bound}/`);
610
- await new Promise(() => {}); // run until signalled
614
+ await new Promise(() => {}); // run until signalled, or until a tick answers true (the run's controller is gone)
611
615
  }
package/scripts/board.mjs CHANGED
@@ -23,6 +23,7 @@ import { serve, resolveCockpitInstance, cockpitWorkspace } from "./board-server.
23
23
  // the `canonicalise` opt-in only that caller takes, and a second resolution
24
24
  // could answer differently.
25
25
  import { stateFileIn } from "./fleet-state.mjs";
26
+ import { cockpitLifetime, controllerVerdict } from "./cockpit-lifetime.mjs";
26
27
  import { isCLI } from "./is-cli.mjs";
27
28
  import { join } from "node:path";
28
29
  import { inspect } from "node:util";
@@ -317,10 +318,16 @@ async function main() {
317
318
  // owns the socket, the timer and the identity handshake; what a tick reads and
318
319
  // writes is owned here.
319
320
  //
321
+ // The tick answers `true` when the cockpit is to exit: it has just written its
322
+ // board and the Controller record in the heartbeat file names a controller
323
+ // that is gone (cockpit-lifetime.mjs says when). serve() stops through its own
324
+ // stop() on that answer. Nothing else is ever signalled.
325
+ //
320
326
  // The spend source is settled per TICK, never held across ticks: with no
321
327
  // --spend-dir, every tick reads the session the phase-0 receipt records now.
322
- // A cockpit outlives the run that launched it — a phase-0 relaunch reuses a
323
- // running server — so it has to follow the next run's receipt.
328
+ // A cockpit lives as long as its run's controller, and a new run from the same
329
+ // omp session — or a phase-0 relaunch that reuses a running server — has to be
330
+ // followed through its receipt.
324
331
  async function boardTick({ ledgerFile, interval, spendDir, spendSince }) {
325
332
  const { computeBoard } = await import("./compute-board.mjs");
326
333
  // One tick at a time, and the flag is load-bearing rather than defensive.
@@ -337,10 +344,20 @@ async function boardTick({ ledgerFile, interval, spendDir, spendSince }) {
337
344
  //
338
345
  // SKIPPED, not queued: a tick recomputes the whole board from scratch, so
339
346
  // the one that would have been queued has nothing in it the next one does
340
- // not redo. Announced once per process through the same warn-once gate
341
- // every other repeating condition in this file uses — a board falling
342
- // behind its interval is worth saying, and worth saying only once.
347
+ // not redo. Announced once per process through board-common.mjs's warn-once
348
+ // gate — a board falling behind its interval is worth saying, and worth
349
+ // saying only once.
343
350
  let ticking = false;
351
+ // Carried from tick to tick besides `ticking`: whether this cockpit has yet
352
+ // seen its run's controller alive, and why the process table last could not
353
+ // be read. The record itself is read afresh every tick — a latched
354
+ // controller would end a cockpit whose record a new run had replaced.
355
+ let armed = false;
356
+ // Null until the table fails to read, and null again from the first tick it
357
+ // reads. Each outage is said once, and so is each new reason within one: a
358
+ // warnOnce gate would say the first outage of the process's life and none
359
+ // after it.
360
+ let unreadable = null;
344
361
  // `served` is the port this process actually BOUND, handed in rather than
345
362
  // closed over: it is not knowable until listen() returns (--port 0 is an
346
363
  // ephemeral bind, and serve()'s port loop may also land past a
@@ -369,7 +386,7 @@ async function boardTick({ ledgerFile, interval, spendDir, spendSince }) {
369
386
  // assignment that used to sit below this line wrote a field the pure
370
387
  // model did not declare, so `build` printed a board with no identity
371
388
  // at all and only the served copy carried one.
372
- const model = computeBoard(await gather({
389
+ const gathered = await gather({
373
390
  // The ledger's own default (ledger.mjs's defaultLedgerPath()) is
374
391
  // never reached here — board.mjs always passes an explicit --file — so an
375
392
  // absent --ledger has to be defaulted against the SAME instance the state
@@ -390,10 +407,26 @@ async function boardTick({ ledgerFile, interval, spendDir, spendSince }) {
390
407
  // The operator's --spend-dir, else the receipt as it stands at this
391
408
  // tick, read from the same state directory as the ledger and heartbeat.
392
409
  ...spendSource(spendDir, stateDir), spendSince,
393
- }));
410
+ });
411
+ const model = computeBoard(gathered);
394
412
  const tmp = `${jsonPath}.tmp`;
395
413
  writeFileSync(tmp, JSON.stringify(model)); // atomic: write tmp, rename over target
396
414
  renameSync(tmp, jsonPath);
415
+ // After the board is written, so the last board an exiting cockpit
416
+ // leaves is this tick's. A record or process table that cannot be read
417
+ // gives no verdict, and a drain (the Liveness mark's `stopped`) is not
418
+ // read at all.
419
+ const verdict = controllerVerdict(gathered.controller, undefined, (why) => {
420
+ if (why !== unreadable) console.error(`${NAME}: ${why} — the cockpit cannot tell whether its run's controller is alive, so it keeps serving`);
421
+ unreadable = why;
422
+ });
423
+ if (verdict !== null) unreadable = null;
424
+ const next = cockpitLifetime(armed, verdict);
425
+ armed = next.armed;
426
+ if (next.exit) {
427
+ console.error(`${NAME}: the controller of this run (pid ${gathered.controller.pid}) is gone — the cockpit exits`);
428
+ return true;
429
+ }
397
430
  } catch (e) { console.error(`${NAME}: build tick failed: ${e.message}`); }
398
431
  finally { ticking = false; }
399
432
  };
@@ -0,0 +1,53 @@
1
+ // How long the cockpit lives: as long as the controller its run recorded, and
2
+ // no longer. The cockpit is spawned detached (phase0.mjs), so nothing ties it
3
+ // to the omp session that started it; this is the one thing that ends it
4
+ // short of a signal. The decision is a pure function of two values, in the
5
+ // board's own split (compute-board.mjs pure, board-gather.mjs impure), so a
6
+ // test feeds it verdicts instead of killing processes. boardTick() in
7
+ // board.mjs reads the record and the process table and acts on the answer.
8
+
9
+ import { judgeController, processSource, ProcUnreadable } from "./proc.mjs";
10
+
11
+ // What the verdict on the Controller record means for the cockpit, this tick.
12
+ //
13
+ // `verdict` is judgeController()'s answer, or null when there is none to give:
14
+ // no record, or a process table that could not be read. Null is not a death
15
+ // and not a life — it neither arms the cockpit nor ends it, which is also how
16
+ // a heartbeat file that could not be read behaves, since readState() answers
17
+ // that with no record.
18
+ //
19
+ // Any verdict but `dead` is a live controller, and the first one ARMS the
20
+ // cockpit. judgeController()'s `none`, its answer for a missing record, never
21
+ // arrives here: controllerVerdict() below answers a missing record with null.
22
+ // Until the cockpit is armed a `dead` verdict means nothing: a cockpit launched
23
+ // by hand between runs finds the last run's record and must not exit on it.
24
+ // Once armed, the first `dead` ends it. `armed` is the caller's to carry from
25
+ // tick to tick; the record is judged afresh on every one, so a record
26
+ // replaced by a new live controller keeps an armed cockpit serving.
27
+ //
28
+ // A drain is not an input: a controller that has stopped beating is still a
29
+ // controller, and judgeController() never reads the beat.
30
+ export function cockpitLifetime(armed, verdict) {
31
+ if (verdict === null) return { armed, exit: false };
32
+ if (verdict === "dead") return { armed, exit: armed };
33
+ return { armed: true, exit: false };
34
+ }
35
+
36
+ // judgeController() for the cockpit: the record against the process table as
37
+ // it stands now, with no ancestry — it passes an empty chain, so `ancestor`
38
+ // never occurs, and every verdict but `dead` reads the same here. Null when
39
+ // there is no record or the table cannot be read, `onUnreadable` told why.
40
+ // `makeSource` is a parameter for the reason proc.mjs's FLEET_PROC_TABLE
41
+ // exists: a test suite run under a live omp session must not judge that one.
42
+ // Nothing here signals a process; judgeController() reads, and kill(pid, 0)
43
+ // only asks.
44
+ export function controllerVerdict(record, makeSource = processSource, onUnreadable = () => {}) {
45
+ if (!record) return null;
46
+ try {
47
+ return judgeController(record, makeSource(), []);
48
+ } catch (e) {
49
+ if (!(e instanceof ProcUnreadable)) throw e;
50
+ onUnreadable(e.message);
51
+ return null;
52
+ }
53
+ }
@@ -356,9 +356,10 @@ export function writeState(path, name, prev, patch) {
356
356
  // Two readers consume this key and neither of them writes it: fleet-tick at
357
357
  // the start of a run (so a run that died overnight announces itself even when
358
358
  // no cockpit survived it) and board.mjs on every cockpit tick (the better
359
- // surface, the weaker guarantee — whether a backgrounded cockpit outlives the
360
- // session that spawned it is unmeasured and harness-dependent, so the mark is
361
- // the artifact and the cockpit is one renderer of it).
359
+ // surface, the weaker guarantee — the cockpit lives as long as its run's
360
+ // controller (cockpit-lifetime.mjs), so a stopped or stalled run's mark stays
361
+ // on screen while that controller's omp session is open and is gone with it,
362
+ // and the mark is the artifact that outlasts it, the cockpit one renderer of it).
362
363
  //
363
364
  // Both live here for the reason the module header already gives about the
364
365
  // path and the shape: what travels between scripts is the rule, never a copy
@@ -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
 
@@ -186,8 +183,8 @@ else — either way it gets its own board, just not always on the port its
186
183
  hash predicts.
187
184
 
188
185
  The spend panel reads the session directory this run's phase-0 receipt
189
- records, re-read on every tick, so a cockpit that outlives a run follows the
190
- next run's receipt. Until that directory exists and holds a member transcript
186
+ records, re-read on every tick, so a cockpit that serves a later run follows
187
+ that run's receipt. Until that directory exists and holds a member transcript
191
188
  the panel stays hidden; with no receipt, or one recording no session, it says
192
189
  `no session recorded — run phase 0 or pass --spend-dir`. Passing
193
190
  `--spend-dir <path>` to phase 0 overrides the receipt —
@@ -198,6 +195,16 @@ running leaves it reading what it read, flag or not. To put a running
198
195
  cockpit on `--spend-dir`, stop it first: SIGTERM to the pid phase 0's
199
196
  `cockpit` line printed when it launched that server.
200
197
 
198
+ The cockpit lives as long as the controller its run recorded — the omp
199
+ session that owns the run — and exits itself once that session is gone. A
200
+ drained run's cockpit stays up while its session stays open, so you can
201
+ still watch it. A run started from the same session, or from a later one,
202
+ records its own controller, and the cockpit keeps serving it. A cockpit
203
+ launched by hand between runs, while the record still names a dead
204
+ controller, keeps serving until a record names a live one. An unreadable
205
+ heartbeat file or process table is not a death. Nothing at close-out stops
206
+ it and nothing signals its pid.
207
+
201
208
  ## Rotate the ledger
202
209
 
203
210
  **Rotate the ledger before the fold-in below and before shortlisting —