@feigi/fleet-ctl 3.71.0 → 3.71.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.
@@ -0,0 +1,28 @@
1
+ # Invariants: the full statements
2
+
3
+ The invariants SKILL.md states one line each, as they read before they were tightened.
4
+
5
+ - In-flight tickets at most the bound (default 5), ≤ 1 merge bot. The bound
6
+ counts tickets, not live agents — members fan out and their children consume
7
+ slots you never dispatched.
8
+ - A grandchild surfaces as its own task-notification. An unrecognized task-id is
9
+ not a member reporting done.
10
+ - A reviewer never reviews a PR it implemented.
11
+ - The merge bot only touches PRs whose implementer reported done. Rebasing a
12
+ worktree someone is working in destroys uncommitted work.
13
+ - `ready-to-merge` is added by a reviewer only — never an implementer, never you.
14
+ **The run's own artifact PR is exempt, and it is exempt because this invariant
15
+ does not reach it:** what the line forbids is a fleet member signing off its own
16
+ ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
17
+ finisher, and the metrics PR you author has none of them. Label and
18
+ merge that one yourself instead of re-deriving a blocker from this line and
19
+ stranding the rows behind it. The exemption belongs to the run that authors the
20
+ PR and does not outlive it: one still open when the run ends is a PR a prior run
21
+ left open, which phase 0 folds into the next run's review queue as ticket work —
22
+ and a PR is not exempt from being wrong, only from waiting on a reviewer
23
+ no phase of this run will ever dispatch against it.
24
+ - **Every member acts through the maintainer's `gh` credentials, so no write is
25
+ attributable.** Any invariant about *who* did something is unenforceable after
26
+ the fact: when a label moves unexpectedly, ask members directly, rule out
27
+ automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
28
+ - Phase 1 is serial. Everything else may run concurrently.
@@ -1,11 +1,59 @@
1
- # Shell traps: the measurements behind them
1
+ # Shell traps
2
2
 
3
- Evidence for the rules SKILL.md states in **Shell traps**, keyed by the rule each justifies.
3
+ ## Shell traps
4
+
5
+ Monitor and Bash commands run under **zsh**, and the shell in SKILL.md is
6
+ prescriptive — copied verbatim into a watcher or into the merge bot's agent
7
+ body. So every trap here is a zsh-vs-bash difference that ships as a
8
+ green-looking gate: correct in the shell you tested in, silently wrong in the
9
+ one it runs in. Phase 3's monitor paragraph points here instead of restating
10
+ any of it. The merge bot's agent body is the one place this block is copied
11
+ whole (see **Merge bot**); the other deliberate copy is named at the end.
12
+
13
+ **zsh word-splits an unquoted command substitution's result; it does NOT split an unquoted parameter expansion.** See references/shell-traps.md.
14
+
15
+ **Word the rule against the first row.** See references/shell-traps.md.
16
+
17
+ **Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
18
+ line-exact under every shell:
19
+
20
+ ```sh
21
+ while IFS= read -r pr; do
22
+ [ -n "$pr" ] || continue # a blank line from an empty capture, not a probe that could not look
23
+ node …/ci-state.mjs --pr "$pr" </dev/null # every inner call, per the trap below
24
+ done <<EOF
25
+ $prs
26
+ EOF
27
+ ```
28
+
29
+ The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase 3's block uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can. See references/shell-traps.md.
30
+
31
+ **`</dev/null` every command inside a `while read` loop.** See references/shell-traps.md.
32
+
33
+ **A probe that could not look emits an event; it never `continue`s.** Stated in
34
+ full at *A probe that cannot read is a transition event, not silence* in Phase 3,
35
+ and it binds every watcher in SKILL.md rather than that one block: the third
36
+ value beside pass and fail is what turns a broken loop into a loud failure
37
+ instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
38
+ || continue` — makes *could not look* indistinguishable from *nothing to report*.
39
+
40
+ **`$?`/`PIPESTATUS` is unconditionally-TRUE in zsh.** zsh has no `PIPESTATUS`
41
+ (its array is lowercase `pipestatus`, 1-indexed), so `${PIPESTATUS[0]}` is always
42
+ empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
43
+ an exit code.
44
+
45
+ **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. Name the variable anything else (`ci_status`). See references/shell-traps.md.
46
+
47
+ **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
48
+ mechanism bites argv as well as loops, and that instance stays written out in the
49
+ fix-applier body and every refuter brief rather than here,
50
+ because the seats that inject faults are the ones that need it and a bot reads
51
+ gates without ever injecting one. Do not fold it into this block, and do not
52
+ restate this block there.
4
53
 
5
54
  ## zsh splits a command substitution, never an unquoted parameter expansion
6
55
 
7
- **zsh word-splits an unquoted command substitution's result; it does NOT split
8
- an unquoted parameter expansion.** That one difference is the whole rule, and the
56
+ That one difference is the whole rule, and the
9
57
  hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
10
58
  against `849`, `850`, `852` on three lines:
11
59
 
@@ -17,7 +65,7 @@ against `849`, `850`, `852` on three lines:
17
65
 
18
66
  ## Word the rule against the first row
19
67
 
20
- **Word the rule against the first row.** A warning spelled *never `for x in
68
+ A warning spelled *never `for x in
21
69
  $(…)`* names the safe form as the hazard, so a reader avoids the form that works,
22
70
  keeps the one that collapses, and rewrites correct bounded polls on the way.
23
71
  A ticket was once filed carrying that inversion in its own remedy clause and in its title,
@@ -26,18 +74,15 @@ row. `$(…)` splits. Leave it alone.
26
74
 
27
75
  ## The inline `$(printf …)` form splits on every whitespace character
28
76
 
29
- The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
30
- 3's block uses, but it splits on *every* whitespace character, so it is safe only
31
- for values that cannot contain one — PR numbers cannot, branch names and paths
32
- can. Measured on a two-line list whose first value is `two words`: three
77
+ Measured on a two-line list whose first value is `two words`: three
33
78
  iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
34
79
  `$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
35
80
  iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
36
- the guard in SKILL.md's heredoc block is what stops that iteration from probing `--pr ""`.
81
+ the guard above is what stops that iteration from probing `--pr ""`.
37
82
 
38
83
  ## `</dev/null` every command inside a `while read` loop
39
84
 
40
- **`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
85
+ The loop's stdin *is*
41
86
  the list, and any inner command that reads stdin eats the rest of it. Measured on
42
87
  the three-line list above: one unredirected inner reader takes the loop to **1
43
88
  iteration**, `</dev/null` on it restores 3 — the identical signature to the
@@ -46,7 +91,7 @@ fix at all, and reads as one.
46
91
 
47
92
  ## `status` is a read-only variable in zsh
48
93
 
49
- **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
94
+ So the obvious
50
95
  bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
51
96
  with `read-only variable: status`. Measured this way it fails safe (a hard abort,
52
97
  no merge), but the same assignment inside an `if`, or with stderr suppressed,
@@ -0,0 +1,172 @@
1
+ # The tick's rows: what each asks of the controller
2
+
3
+ The full text of each row `fleet-tick.mjs` prints and what it asks of the controller. SKILL.md's **The tick's rows** carries one line for each.
4
+
5
+ - `PULL #<N> …` — one Pull per named ticket, in the order printed: phase 1's
6
+ read, then phase 2's dispatch. A ticket that fails the read is relabelled or
7
+ excluded (phase 1), and the next tick names the next head.
8
+ - `REFRESHED shortlist: <n> entries; <k> lifted` — the tick refreshed the
9
+ shortlist itself, and its `PULL` row already reads the result. `REFRESH
10
+ FAILED` is yours: `shortlist.mjs` could not run, and the implementer row is
11
+ blind until it can.
12
+ - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
13
+ Suggest, never run (**Queue depth**).
14
+ - `specs-dropped=#<N> … (to-spec: User Stories heading)` at the end of the
15
+ implementer row's counts, whatever its ACTION — the tickets the to-spec
16
+ filter kept out of `supply`, read off the shortlist's `dropped`. Never
17
+ actionable. Log them as specs awaiting to-tickets (phase 0), not as no work.
18
+ - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
19
+ a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**Reviewers**). Printed
20
+ ahead of reviews on purpose: finishing what is started beats starting more.
21
+ - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
22
+ (**Reviewers**).
23
+ - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
24
+ - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled`, yet the open
25
+ list shows PR M without `ready-to-merge`, and no `label-off=` (**Run ledger**)
26
+ accounts for the removal. Apply the finisher gate (**Reviewers**: the
27
+ `check` job green on the current head), then dispatch the next-suffix
28
+ finisher at that head, one letter past the highest the PR has used: render
29
+ its brief with `dispatch-prompt.mjs render finisher --kind repair --member
30
+ finisher-pr-<M>-<x> …`, then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`.
31
+ Never add the label yourself. A head
32
+ that moved is caught by the new finisher's duty 1 `past-pin` halt and the
33
+ re-review path that follows it. Finishers are not review units, so this
34
+ prints whatever the unit count reads.
35
+ - `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
36
+ settled `labelled` and the label is still not on: the tick dispatches no
37
+ third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
38
+ flag and the comment the repair finisher's report left (`fleet-event.mjs`'s
39
+ `finisher-report` entry).
40
+ - `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
41
+ tracks it, no conflict hold stands on it, no fix-applier, finisher or
42
+ implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
43
+ is live: a queued PR is the bot's while one runs, and its own fallback records
44
+ the hold. Record it with `fleet-event.mjs conflict <M>`, not with the `ledger.mjs
45
+ row` form the row's detail prints: `row` replaces the whole line. The call
46
+ refuses a PR whose row already carries a hold no fix-applier has answered.
47
+ The tick then reads the hold as `DISPATCH fix-pr
48
+ PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
49
+ hold**), and that row obeys every hold. A review in flight does not stop the
50
+ line: `fix-due` waits for the review to return. It prints under a
51
+ main-checkout hold and a drain too, since it writes a record and dispatches
52
+ nothing.
53
+ - `ESCALATE conflict PR#<M> …` — PR M reads CONFLICTING again after two
54
+ conflict fix-appliers landed on it: a rebase treadmill. Comment on the PR
55
+ and flag it for a human; write no hold and dispatch no fix-applier. Not
56
+ actionable; it repeats while the PR reads CONFLICTING and clears once it
57
+ stops, closes or merges.
58
+ - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
59
+ unchecked tier, the In-flight bound reached (`HOLD (in-flight <n>/<B>)` —
60
+ nothing to do unless its detail names a replacement to dispatch, else a
61
+ merge brings n below B), or every
62
+ queued merge candidate held behind a lower PR or on a conflict hold no
63
+ fix-applier has cleared. An unchecked tier is `tick --apply`'s to check, and
64
+ the hold stays while the check writes no verdict (its `tier-ok=`, or
65
+ `tier-unverifiable=` for a member settled `killed` or `released` with no
66
+ transcript, clears it); a mismatch is yours to clear, by dispatching the
67
+ replacement at the right tier (phase 2). Each prints its clearing step in
68
+ the row's detail. For a mismatch that is the replacement's name —
69
+ `impl-<N>-b` on a first retry, else one letter past the highest the ticket
70
+ has used, or that no retry letter is left. For an unchecked tier, which
71
+ `tick --apply` has already tried, it is the `tier-check.mjs` command to run
72
+ by hand when the tick ran without `--apply` or the check wrote no verdict,
73
+ with a batch entry per member it names (fill in `<file>`; `<session>` too
74
+ when no receipt of this run records one).
75
+ - `AT CAP`, `IDLE OK` — nothing to do on that row.
76
+ - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
77
+ dispatching row (implementers, reviewers, merge-bot) reading
78
+ `HOLD (main checkout dirty)` — the main checkout changed since the Phase 0
79
+ baseline. The line names the changed paths, or a `HEAD <was> → <now>` entry
80
+ when HEAD moved, and every live member; it
81
+ attributes nothing, because concurrent members make that a guess. Dispatch
82
+ nothing new and tell the maintainer: they resolve the stray paths FIRST,
83
+ then re-baseline with `~/.fleet/bin/fleet-run main-checkout.mjs --record`.
84
+ A path entry holds until that re-baseline, tick after tick; a `HEAD …` entry
85
+ clears itself once HEAD reads clean again, and is never re-baselined while
86
+ HEAD is off the run's branch. Never revert the
87
+ paths yourself, and never re-baseline over paths nobody has resolved. The
88
+ changes of yours that trip it are a mid-run tooling fix edited in this
89
+ checkout and the close-out commit's round trip through a branch; **Fix the
90
+ tooling mid-run** and the commit section of references/close-out.md say how
91
+ each is cleared.
92
+ - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
93
+ could not look: a git or hash read failed (`could not look:`), or the
94
+ baseline exists but cannot be read (`baseline unreadable:`). Never clean,
95
+ and **never re-baseline over it** — `--record` overwrites, so that certifies
96
+ a tree nobody read. Fix what the line names and tick again. `baseline v<n>
97
+ written by a newer plugin` is a baseline a newer plugin version wrote:
98
+ `--record` refuses over it too — run the plugin that wrote it. The
99
+ exceptions are the two whose remedy is `--record`: `baseline v<n> —
100
+ re-record`, an older-format baseline this plugin cannot compare; and
101
+ `baseline commit <oid> is missing from this repository`, which an amend or
102
+ reset followed by gc leaves — examine HEAD against `origin/main` FIRST,
103
+ since HEAD moved off that commit and nobody has looked at the move, and
104
+ resolve any stray paths, which the line does not name; only then re-record.
105
+ - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
106
+ baseline was recorded. Yours to fix: run
107
+ `~/.fleet/bin/fleet-run main-checkout.mjs --record`, which references/phase-0.md
108
+ describes under "Record the main-checkout baseline". A baseline
109
+ that vanished mid-run is not a fresh run — report it to the maintainer
110
+ before recording over whatever the tree now holds.
111
+ - `PHASE0-INCOMPLETE <step>[, <step>…] …`, printed first above the rows,
112
+ with every dispatching row (implementers, reviewers, merge-bot) reading
113
+ `HOLD (phase 0 incomplete)` — this run's phase-0 receipt
114
+ `.fleet/phase0.json` names a step `failed` or `pending`, or lacks one. In
115
+ place of the steps the line says the receipt is missing, unreadable,
116
+ another run's (its `run` is not the `at` in the controller record), or a
117
+ run whose controller has exited — the previous run's finished receipt, in
118
+ a session that has not yet run its own phase 0. It outranks every
119
+ other reason on those rows, `MAIN-CHECKOUT-*` included, whose lines still
120
+ print; a `baseline` step not `ok` is one of the steps it names.
121
+ `CONFLICT` rows and the stall report still print. Run the
122
+ `phase0.mjs` command the line names and act on what it prints: a re-run
123
+ resumes at the step that stopped. A `drift` or `unanswered` step and a
124
+ `fold-in` `NEED` are advice, named after `; advice:` on the line, or alone
125
+ on a `PHASE0-ADVICE …` line when nothing is incomplete; advice holds
126
+ nothing.
127
+ - `CHECK-LIVENESS <member> (<family> > p99 <t>m)`, printed above the rows — a
128
+ live ledger token has stayed live past its family's p99 run time, counted
129
+ from the first tick that saw it (`> 2×p99 …` from the second multiple of the
130
+ threshold on; `review:PR#<n>` names an in-flight `review=` launch). Advice,
131
+ not an action: it is not actionable, resets no `quiet`, changes no row and
132
+ frees no slot, and the tick settles and kills nothing. Take the census the
133
+ **Member unaccounted** row of **Failure handling** gives before you touch the
134
+ token. It repeats every tick while the token stays live past the threshold.
135
+ `--liveness-impl`, `--liveness-fix-pr`, `--liveness-finisher`,
136
+ `--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
137
+ - `UNRECORDED <stem> (transcript exists, no ledger token)`, printed above the
138
+ rows — the session directory holds a `<stem>.jsonl` whose stem is a member
139
+ name no row token, `## Dispatched` entry or `## Retired` line names: a
140
+ dispatch whose ledger write was forgotten. Record it with `ledger.mjs
141
+ dispatch`, or confirm it is a stranger's member.
142
+ Advice, like `CHECK-LIVENESS`: it resets no `quiet`, changes no row and
143
+ frees no slot, it repeats every tick while it holds, and the folded line
144
+ names it (`…; UNRECORDED <stem> persists — …`).
145
+ - `NO-TRANSCRIPT <member> (live <age>m, no <session>/<member>.jsonl)`, printed
146
+ above the rows — a live ledger token first seen more than
147
+ `--no-transcript-after` minutes ago (default 5) has no transcript in the
148
+ session directory: a dispatch whose `task` call was never made. Make the
149
+ `task` call, or settle the token `killed`. Advice the same way, folded as
150
+ `…; NO-TRANSCRIPT <member> persists — …`. Both lines read the session
151
+ directory this run's phase-0 receipt names, else `--session <dir>`; with
152
+ neither the tick skips them with one stderr line. A heartbeat state file
153
+ that exists but cannot be used — unreadable, not JSON, not a JSON object,
154
+ or holding a `controller` that cannot be judged — holds no first-seen
155
+ ages, and the tick never rewrites it, so every live token reads as first
156
+ seen that tick and neither `CHECK-LIVENESS` nor `NO-TRANSCRIPT` can fire.
157
+ The tick says so with one stderr line, `fleet-tick: CHECK-LIVENESS and
158
+ NO-TRANSCRIPT not checked — <file> <cause>, so first-seen ages are
159
+ unavailable`, naming only the checks that would have run that tick.
160
+ - `SETTLE <member> (report on disk since <n>m — ledger.mjs settle <member>
161
+ --from-report)`, printed above the rows — a live ledger token whose report
162
+ file, `<scratch>/reports/<member>.json`, is on disk and passes its member
163
+ family's report schema. Run that member's report wake from the wake table:
164
+ it runs the settle the line prints and the follow-on work its report
165
+ calls for, which a bare settle does not do. Advice, like
166
+ `CHECK-LIVENESS`: the tick settles nothing. Three lines name a report file
167
+ `settle --from-report` cannot settle from: `REPORT-MISMATCH <path> (member:
168
+ …)`, a file whose `member` is not its filename's; `REPORT-UNREADABLE <path>
169
+ (…)`, one that is there but cannot be read; and `REPORT-INVALID <path> (…)`,
170
+ one that names its own member and fails its family's schema, with the first
171
+ violation. A review runner has no report schema and files none, so none of
172
+ these lines names one.