@feigi/fleet-ctl 3.54.3 → 3.56.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.
@@ -164,11 +164,12 @@ makes one up.
164
164
  ## Shell traps
165
165
 
166
166
  Monitor and Bash commands run under **zsh**, and the shell in this file is
167
- prescriptive — copied verbatim into a watcher or pasted into a bot's brief. So
168
- every trap here is a zsh-vs-bash difference that ships as a green-looking gate:
169
- correct in the shell you tested in, silently wrong in the one it runs in. Phase
170
- 3's monitor paragraph and the **Merge bot**'s brief both point here
171
- instead of restating any of it; the one deliberate copy is named at the end.
167
+ prescriptive — copied verbatim into a watcher or into the merge bot's agent
168
+ body. So every trap here is a zsh-vs-bash difference that ships as a
169
+ green-looking gate: correct in the shell you tested in, silently wrong in the
170
+ one it runs in. Phase 3's monitor paragraph points here instead of restating
171
+ any of it. The merge bot's agent body is the one place this block is copied
172
+ whole (see **Merge bot**); the other deliberate copy is named at the end.
172
173
 
173
174
  **zsh word-splits an unquoted command substitution's result; it does NOT split
174
175
  an unquoted parameter expansion.** That one difference is the whole rule, and the
@@ -236,7 +237,7 @@ reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
236
237
  trap, opposite failure direction — so name the variable anything else
237
238
  (`ci_status`).
238
239
 
239
- **The one deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
240
+ **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
240
241
  mechanism bites argv as well as loops, and that instance stays written out in the
241
242
  fix-applier prompt and every refuter brief under **Reviewers** rather than here,
242
243
  because the seats that inject faults are the ones that need it and a bot reads
@@ -1262,8 +1263,8 @@ one. Only the newest member counts, so a replacement (`impl-<N>-b`) is what
1262
1263
  clears a mismatch — and is then owed its own check. A mismatch on a ticket
1263
1264
  whose issue is already CLOSED holds nothing: the tick probes that issue and
1264
1265
  drops it, since there is nothing left to replace. The tick never reads a
1265
- transcript: clear an unchecked hold by running the check on that member with
1266
- `session`. A settled member's check works only when its transcript exists;
1266
+ transcript: clear an unchecked hold by running the check on that member. A
1267
+ settled member's check works only when its transcript exists;
1267
1268
  without one, the verdict is `tier-unverifiable` for a member settled `killed`
1268
1269
  or `released`, and exit 2 naming the wrong session for any other. Clear a
1269
1270
  mismatch by fixing the definition or the dispatch and dispatching the
@@ -1288,14 +1289,16 @@ dispatch time, so a late check judges a member against a tier it was never
1288
1289
  dispatched under.
1289
1290
 
1290
1291
  **The batch file is a JSON array, one entry per dispatched member** — under
1291
- Pull, a batch of one, the member just dispatched: `{member, session}`.
1292
- `member` is the AgentId the dispatch returns (`impl-<N>`). `session` is the
1293
- SAME session directory `member-outcomes.mjs`/`board.mjs` are already handed
1294
- for this run; the check reads the member's own `<session>/<member>.jsonl`
1295
- directly, so a member with no assistant turn yet still resolves off its
1296
- dispatch-time record. A caller already holding the exact transcript path may
1297
- give `transcript` instead. Either one is required: the agent type an
1298
- implementer was dispatched as lives only in its transcript. `resolvedModel`
1292
+ Pull, a batch of one, the member just dispatched: `{member}`.
1293
+ `member` is the AgentId the dispatch returns (`impl-<N>`). An entry that
1294
+ names neither `session` nor `transcript` takes the session directory phase
1295
+ 0's receipt `.fleet/phase0.json` records, and is exit 2 naming the receipt
1296
+ when it records none; the check reads the member's own
1297
+ `<session>/<member>.jsonl` directly, so a member with no assistant turn yet
1298
+ still resolves off its dispatch-time record. A `session` the entry gives
1299
+ wins over the receipt's; a caller already holding the exact transcript path
1300
+ may give `transcript` instead. The agent type an implementer was dispatched
1301
+ as lives only in its transcript. `resolvedModel`
1299
1302
  **and** `resolvedThinkingLevel` together — the dispatch's own job record —
1300
1303
  may ride beside it and are preferred for the model and level. An `impl-`
1301
1304
  entry carries no `agentFile`: its definition is the row's, never the
@@ -1963,7 +1966,8 @@ depth** guard table applied in code. Act on each line as it reads:
1963
1966
  `released` with no transcript, clears it), a mismatch by dispatching the
1964
1967
  replacement at the right tier (phase 2). Each
1965
1968
  prints its clearing step in the row's detail: the `tier-check.mjs` command
1966
- with a batch entry per member it names (fill in `<file>` and `<session>`),
1969
+ with a batch entry per member it names (fill in `<file>`; `<session>` too
1970
+ when no receipt of this run records one),
1967
1971
  or the replacement's name — `impl-<N>-b` on a first retry, else one letter
1968
1972
  past the highest the ticket has used, or that no retry letter is left.
1969
1973
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
@@ -2000,6 +2004,22 @@ depth** guard table applied in code. Act on each line as it reads:
2000
2004
  baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
2001
2005
  that vanished mid-run is not a fresh run — report it to the maintainer
2002
2006
  before recording over whatever the tree now holds.
2007
+ - `PHASE0-INCOMPLETE <step>[, <step>…] …`, printed first above the rows,
2008
+ with every dispatching row (implementers, reviewers, merge-bot) reading
2009
+ `HOLD (phase 0 incomplete)` — this run's phase-0 receipt
2010
+ `.fleet/phase0.json` names a step `failed` or `pending`, or lacks one. In
2011
+ place of the steps the line says the receipt is missing, unreadable,
2012
+ another run's (its `run` is not the `at` in the controller record), or a
2013
+ run whose controller has exited — the previous run's finished receipt, in
2014
+ a session that has not yet run its own phase 0. It outranks every
2015
+ other reason on those rows, `MAIN-CHECKOUT-*` included, whose lines still
2016
+ print; a `baseline` step not `ok` is one of the steps it names.
2017
+ `CONFLICT` rows and the stall report still print. Run the
2018
+ `phase0.mjs` command the line names and act on what it prints: a re-run
2019
+ resumes at the step that stopped. A `drift` or `unanswered` step and a
2020
+ `fold-in` `NEED` are advice, named after `; advice:` on the line, or alone
2021
+ on a `PHASE0-ADVICE …` line when nothing is incomplete; advice holds
2022
+ nothing.
2003
2023
  - `CHECK-LIVENESS <member> (<family> > p99 <t>m)`, printed above the rows — a
2004
2024
  live ledger token has stayed live past its family's p99 run time, counted
2005
2025
  from the first tick that saw it (`> 2×p99 …` from the second multiple of the
@@ -2592,10 +2612,8 @@ is the same slot with a different job, and no review file to hand
2592
2612
  over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2593
2613
  already on record — `dispatch` refuses a reused one — and dispatch it with the
2594
2614
  `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
2595
- `dispatch` reads the unresolved hold off the tick's own per-PR state — every
2596
- row naming the PR, not one — and prints this member's own definition, whatever
2597
- the row's `tier=` — read it off that output, never recall it; a review
2598
- fix-applier's is `null`. Its prompt takes the prompt below's
2615
+ `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
2616
+ row's `tier=` — read it off that output, never recall it. Its prompt takes the prompt below's
2599
2617
  worktree, branch and path discipline, but in place of its review paragraphs:
2600
2618
  bring `<branch>` current with `origin/main`, resolving every conflict by
2601
2619
  `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
@@ -2604,8 +2622,8 @@ what lifts the tick's merge hold; a dispatched-but-live one does not, and
2604
2622
  `failed`/`killed` leave the PR fix-due for a replacement. It answers the
2605
2623
  hold and nothing else: survived or unverified findings of a returned review the row also carries
2606
2624
  stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
2607
- PR#<M>` again once it lands, and that one — `dispatch` now prints `null` —
2608
- is a review fix-applier, dispatched as above. On a PR carrying
2625
+ PR#<M>` again once it lands, and that one is a review fix-applier, dispatched
2626
+ as above. On a PR carrying
2609
2627
  `ready-to-merge`, the push moves the head after the label, so the next merge
2610
2628
  bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
2611
2629
  handling**.
@@ -2635,8 +2653,8 @@ bullets without the others and what strands is exactly the red-only PR.
2635
2653
 
2636
2654
  Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
2637
2655
  refuses a reused name — record it with `ledger.mjs dispatch <pr#> <name>`
2638
- before the call, and dispatch it with the `agent` that command printed (`null`
2639
- while no conflict hold stands, as for a review fix-applier), in the PR's
2656
+ before the call, and dispatch it with the `agent` that command printed
2657
+ (`fleet-fix-applier`, as for a review fix-applier), in the PR's
2640
2658
  existing worktree. Its prompt takes the prompt below's worktree, branch and
2641
2659
  path discipline, but in place of its review paragraphs: read the failing job's
2642
2660
  log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
@@ -3359,7 +3377,7 @@ each run a script the digest covers — `finisher-audit.mjs` (which runs
3359
3377
  `worktree-audit.sh`) and `ledger.mjs`, both under `plugin/scripts/` — and the
3360
3378
  label at duty 3 rests on what they returned. The rule is stated once, at the
3361
3379
  top of this file, which no finisher is dispatched to read, so it reaches one
3362
- through this block or not at all:
3380
+ through this block, which `agents/fleet-finisher.agent.md` carries in its body:
3363
3381
 
3364
3382
  > **Re-check the instrument set before you act on what duty 1 or duty 2 read,
3365
3383
  > and again before you add the label.**
@@ -3381,7 +3399,7 @@ through this block or not at all:
3381
3399
 
3382
3400
  **Give the finisher the test-run verdict rule verbatim too.** Duty 2 runs
3383
3401
  `<testCmd>` for the acceptance mutation, and the finisher's agent definition
3384
- says nothing about what a run that was cut short looks like. A `node --test`
3402
+ carries a copy of the rule below. A `node --test`
3385
3403
  stopped by an outside `timeout` still prints a summary, covering only the tests
3386
3404
  it reached, so reading that summary alone reads a partial suite as a whole one:
3387
3405
 
@@ -3451,8 +3469,8 @@ it reached, so reading that summary alone reads a partial suite as a whole one:
3451
3469
  > evidence; label nothing. A kill's evidence line goes in your report.
3452
3470
 
3453
3471
  **Give the finisher duty 3 verbatim as well, as one script.** The finisher's
3454
- agent definition carries no duty text, so this brief is the whole of duty 3 it
3455
- sees. Two finishers in one run read the release-label check as the whole duty
3472
+ agent definition carries this block in its body, so the brief does not repeat
3473
+ it. Two finishers in one run read the release-label check as the whole duty
3456
3474
  and reported `labelled` on a PR that never got the label, so the check and the
3457
3475
  label write are one command and the finisher never runs either alone:
3458
3476
 
@@ -3645,14 +3663,17 @@ deterministic, script-driven backstop run before every push specifically to
3645
3663
  catch a wrongly-resolved conflict, so the tier buys nothing that backstop
3646
3664
  doesn't already cover.
3647
3665
 
3648
- **Put the shell traps in the bot's brief, not in a follow-up message.** A bot
3649
- already looping cannot be corrected — the loop consumes the turns a correction
3650
- would land in. **Every entry in Shell traps, verbatim** — that section is where
3651
- they are stated once, and this is the seat that has to paste them: the bot
3652
- reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
3653
- `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
3654
- grace poll captures `gh pr list` output and loops over it, which is the
3655
- assigned-variable trap. The brief always travels with the dispatch.
3666
+ **The shell traps live in the merge bot's agent body, not in its brief and not
3667
+ in a follow-up message.** A bot already looping cannot be corrected — the loop
3668
+ consumes the turns a correction would land in — so
3669
+ `agents/fleet-merge-bot.agent.md` carries **every entry in Shell traps**, copied
3670
+ from that section, and the bot has them before its first turn. The bot reads an
3671
+ exit code off `gh pr update-branch`, `merge-gate.mjs` and `prove-merge.sh`,
3672
+ which is the `PIPESTATUS` and read-only-`status` pair, and its grace poll
3673
+ captures `gh pr list` output and loops over it, which is the assigned-variable
3674
+ trap. Its brief names the bot and `<scratch>`, plus the one-line
3675
+ no-acknowledgement notice; do not paste the
3676
+ traps there. An edit to Shell traps lands in that body in the same change.
3656
3677
 
3657
3678
  **Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
3658
3679
  `merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
@@ -4309,14 +4330,13 @@ live count from it, so nobody states one. Write neither by hand:
4309
4330
  merge-bot` names the next bot itself. It prints `{member, agent, ticket,
4310
4331
  line, created, total}`; `agent` is the definition the `task` call names — an
4311
4332
  implementer's comes off its row's `tier=` (phase 2's tier check states the
4312
- mapping), a finisher's and a merge bot's are their own definitions, a
4313
- review fix-applier's is `null`, and a conflict-hold fix-applier's is
4314
- `fleet-implementer-slow-high`: its own section says how it is dispatched. It
4333
+ mapping), a finisher's and a merge bot's are their own definitions, and a
4334
+ fix-applier's is `fleet-fix-applier` for every kind of work. It
4315
4335
  refuses a name this session already used — on the ledger or in its
4316
4336
  `## Retired` — and names the replacement (`-b`, `-c` …), a
4317
4337
  second live member on one ticket or PR, any implementer once the run is
4318
4338
  draining, an implementer whose row's `tier=` names no single definition
4319
- or one with no file under `agents/`, and a fix-applier on a ledger the tick
4339
+ or one with no file under `agents/`, and a finisher on a ledger the tick
4320
4340
  itself refuses.
4321
4341
  - **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
4322
4342
  `<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
@@ -3,135 +3,18 @@ arg worktree abs-path
3
3
  arg pin your dispatch pin
4
4
  arg pr M
5
5
  arg testCmd testCmd
6
+ arg scratch scratch
6
7
  path worktree
7
- literal args
8
- literal cmd
9
- literal test
8
+ path scratch
10
9
  ---
11
10
  ## kind: fresh, repair
12
- **Re-check the instrument set before you act on what duty 1 or duty 2 read,
13
- and again before you add the label.**
14
- `~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
15
- Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
16
- exit 2 (the check could not answer) both halt you: report what it printed,
17
- add no label, and do NOT re-read the script that gave you the reading.
18
- `--repo` is required and the spelling is the point — the run's baseline lives
19
- in the audited checkout's gitignored `.fleet/`, which the scratch worktree
20
- you take at duty 2 does not carry, so a bare invocation from there exits 2 on
21
- a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
22
- GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
23
- pointing this check at the wrong tree — the script's own internal unset
24
- cannot reach back and fix a path you already resolved wrong. The baseline
25
- itself names the tree to audit: a cross-workspace run pinned it once at
26
- phase 0, and your `--repo` only locates that baseline, never the audited
27
- tree — so an exit 2 naming a moved or unreadable audited tree is a halt
28
- like every other, not a spelling for you to correct.
11
+ Finish PR <M>. Your arguments are the whole of your per-dispatch task:
29
12
 
30
- **A test run is a verdict only if it ran to completion — and you read that
31
- off the test command's own exit status.**
32
- Redirect the run's output to a file in your scratch directory and read the
33
- command's own `$?` straight after it, then read the file. In an `eval` cell
34
- there is no `$?`: spawn `<testCmd>` with its output going to that file and
35
- read the exit code and the signal off the spawn result — `exitCode` and
36
- `signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
37
- which is negative for a signal. Never read the status of
38
- `<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
39
- last stage's, so the filter's 0 hides the run's own exit, and the array that
40
- holds the earlier stages' statuses is spelled differently per shell. A run is
41
- a verdict only when that exit status is 0 **and** its summary shows `tests`
42
- above 0 and `cancelled` 0. A summary line without that
43
- is not a verdict, whatever pass count it prints.
44
- **A run completed when the command itself returned on its own** — an exit
45
- code, no signal, and no `timeout`, deadline or kill of yours having fired.
46
- Judge that by how the run ended, never by its `cancelled` count: a failing
47
- `before` hook or a per-test `timeout` cancels tests inside a run that
48
- completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
49
- in a run that did not.
50
- **Any run that did not complete is a killed run** — 124 (`timeout`), 137
51
- (SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
52
- deadline — and read for green it is FAILED, the same bucket as
53
- `tests 0`, however many tests had passed before the kill. Halt with cause
54
- `other` and the exit code plus the summary line as evidence; label nothing.
55
- The same holds for the mutation gate: a killed run is not a mutant that
56
- reddened, and the files it cancelled are not failures — only a run that
57
- completed can kill a mutant. A completed run that exits 1 is not a killed run
58
- either, whatever its `cancelled` count, and not a killed mutant on its exit
59
- status alone: the acceptance mutation scores a kill only by the rules below.
60
- Exit 0 with `tests 0` stays FAILED.
61
- Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
62
- `eval` cell with `timeout: 0`, as the review runner does, and wait for it.
63
-
64
- **Valid red:** a run that completed — the command returned on its own, with
65
- no signal and no timeout, deadline or kill having fired — in which the test
66
- the claim names is reported failing. An exit ≠ 0 with no failing test is not
67
- red, and a different test failing is not red for this claim. A red in the full
68
- suite only triggers a narrowed run; it is never evidence on its own.
69
-
70
- **Narrowed run:** the Test entrypoint with arguments appended,
71
- `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
72
- that is promised about them, so a narrowed run counts only if it reports
73
- `tests` > 0 and its output names the claimed test. If no narrowing can be
74
- proven, run the full `<testCmd>` and read the named test's own result from its
75
- output.
76
-
77
- **Kill:** the mutant produced a valid red in a narrowed run, and the same
78
- narrowed command, in the same tree with the mutant reverted, ran a valid green
79
- with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
80
- completed exit ≠ 0 with the named test not failing is not a kill, and no kill
81
- stands without that green run on the unmutated tree. The result is
82
- inconclusive, never a kill, when the red does not reproduce in the narrowed
83
- run, when the unmutated tree is red too, or when no usable run exists.
84
-
85
- **Evidence line:** every kill and every valid red you claim carries one line
86
- in the claim's own free-text field:
87
- `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
88
- A failing-test finding filed off the review's shared run carries the `red:`
89
- half alone.
90
-
91
- An inconclusive acceptance mutation is neither a kill nor a pass: halt with
92
- cause `other`, with both runs — the mutant's and the unmutated tree's — as
93
- evidence; label nothing. A kill's evidence line goes in your report.
94
-
95
- **Duty 3 is one script, and its exit code is your verdict.**
96
- `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
97
- (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
98
- PR, records the head you audited, adds `ready-to-merge`, and reads the labels
99
- back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
100
- carries zero or more than one release label: you are halted before the label,
101
- and the receipt names which it found. Exit 4 means the read-back does not carry
102
- the label, written or not. Exit 2 means a `gh` call or the invocation
103
- itself failed: report the stderr it printed. Every non-zero exit halts you
104
- with cause `other`, with the receipt as evidence, and you do not run any of
105
- its steps by hand to get past it. A repo whose label list defines none of the
106
- three does not gate on one, and the script says so in its receipt. Put the
107
- receipt, the JSON line it printed, in your report as printed: it is what tells
108
- the controller the label is on.
109
-
110
- **Duty 1 is one script, and its exit code is your verdict.**
111
- `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
112
- (the path you were dispatched with, and the full SHA). It finds your
113
- worktree's row, reads whether the tree is dirty, compares the worktree's
114
- `HEAD` to your pin, and when the head differs derives the cause from the
115
- reflog. Exit 0, with `cause` null, is the only code that means the worktree is
116
- clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
117
- `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
118
- `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
119
- a gap. Exit 2 means the script could not look: you are halted with cause
120
- `other`, with the line it printed on stderr as the evidence.
121
-
122
- The pin is the SHA you were dispatched against, never `PR headRefOid`: a
123
- member that kept working and pushed after the pin matches the branch tip on a
124
- clean tree, so a headRefOid comparison reports "settled" over commits no
125
- reviewer read — the exact divergence this halt exists to catch. You do not
126
- run any of the script's steps by hand to get past a halt or to second-guess
127
- it. Put the verdict, the JSON line it printed, in your report as printed: its
128
- `evidence` is what the controller resolves the halt from.
129
-
130
- Every cause halts, always — named or not, you never verify the dirt is
131
- harmless and label over it, a rebase is not a fast-forward you get to accept,
132
- a commit past the pin is not one either, and a cause you could not name is
133
- the least settled of the lot. Naming the cause makes the halt cheap to
134
- resolve, never a reason to skip it.
13
+ pr: <M>
14
+ worktree: <abs-path>
15
+ pin: <your dispatch pin>
16
+ testCmd: <testCmd>
17
+ scratch: <scratch>
135
18
  ## kind: repair
136
19
 
137
20
  An earlier finisher on this PR reported `labelled`, but its read-back did not carry `ready-to-merge`: you are the repair finisher. Duty 3's script decides whether the label is on, as above.