@feigi/fleet-ctl 3.66.2 → 3.68.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.
@@ -1,6 +1,6 @@
1
1
  # Isolation: filesystem vs stack
2
2
 
3
- Why isolation envelope file not briefing, why private filesystem not private stack. Assertions these justify live in SKILL.md Phase 1 + Guards sections; evidence here.
3
+ Why isolation envelope file not briefing, why private filesystem not private stack. Assertions these justify live in references/pull.md Claiming section and SKILL.md Guards section; evidence here.
4
4
 
5
5
  ## Materialize the isolation envelope as a file, not a briefing
6
6
 
@@ -8,6 +8,109 @@ Env vars in prompt missed five times in one run — including briefed member, an
8
8
 
9
9
  The runner a claim writes is written once and never rewritten — a claim refuses a worktree that already exists — so every copy under `.worktrees/` is frozen at whenever that worktree was claimed; reading or measuring one measures that build, not what the current emitter produces. Line 2 is what tells a reader which build they are holding: `# agent-test template: <cksum>`. Reproduce the number from the installed script (`cksum $(~/.fleet/bin/fleet-run --path claim-ticket.sh)`) or from any revision of it (`git show <rev>:plugin/scripts/claim-ticket.sh | cksum`) and compare the first field — `cksum` also prints a byte count, and the path when it is given a file. It checksums the whole emitting script, not the runner template inside it, so it over-reports: a mismatch means only that `claim-ticket.sh`'s bytes differ from the ones you checksummed — a reworded die message or an edited comment moves it while the runner it produces stays byte-identical — not "the template changed", and not "older" either, because `cksum` carries no order: over `claim-ticket.sh`'s own history both the checksum and the byte count fall as well as rise. It under-reports too, so a match is not the freshness proof it looks like. The stamp covers `claim-ticket.sh` and nothing else, while the command the runner `exec`s is the Recipe cache's Test entrypoint, which it does not cover: two claims under one stamp exec different commands once the Recipe is re-derived between them. So read a match as "this runner came from these bytes of `claim-ticket.sh`"; only a fresh claim writes the current runner. Nothing reads the stamp and nothing refuses on a mismatch; it makes staleness legible to a human, it gates nothing.
10
10
 
11
+ ## A worktree no claim built: the runner, and the commit
12
+
13
+ **A reused worktree may lack the runner.** `claim-ticket.sh` writes
14
+ `agent-test` only into the fresh worktree it claims, so a tree no claim
15
+ built — an already-open PR's worktree you sent a rebaser/resolver into,
16
+ a `git archive` snapshot, a `cp -R` subset — has no `./agent-test`
17
+ unless the repository tracks its own, and a member told to run one
18
+ stalls on a missing script (observed with a rebase-resolver in a
19
+ prior-run worktree). There, tell the member the runner is absent and to
20
+ run docker-free suites directly — the Recipe's Test entrypoint
21
+ (`~/.fleet/bin/fleet-run derive-testcmd.sh <main checkout> test --at origin/main` prints
22
+ it) only when it brings up no shared stack to collide on, else that
23
+ repo's own stack-free command.
24
+
25
+ **A reused worktree may also be on the wrong COMMIT.** `git worktree add <path>
26
+ <branch>` checks out the existing LOCAL branch and never consults the remote, so
27
+ a branch a previous run left behind wins over the rebased `origin/` ref that is
28
+ actually the PR. Measured in a scratch repo (git 2.50.1): with the branch rebased
29
+ on the remote and a stale local ref standing, `git worktree add <path> <branch>`
30
+ checked out the stale commit and printed `HEAD is now at <stale-sha> <subject>` —
31
+ the same subject the PR head carries, because a rebase preserves it. Neither
32
+ commit was an ancestor of the other, so *behind* is the wrong model; it is a
33
+ fork. Every other signal reads normal too: `git worktree list` shows the worktree
34
+ present on the expected branch, and the tree is clean. `claim-ticket.sh` never
35
+ touches this path — it claims only fresh tickets, and builds those from
36
+ `origin/main`.
37
+
38
+ **The two reuse failures are not symmetric.** A missing runner fails LOUDLY: the
39
+ member stalls on a script that is not there. A stale base fails SILENTLY and
40
+ produces confident wrong output — a review cut its immutable snapshot at the
41
+ stale commit and a fix-applier was dispatched into it, halted only before a push
42
+ that would have been a non-fast-forward.
43
+
44
+ So, when you re-create a worktree for an already-open PR:
45
+
46
+ - **Create it detached from the remote ref**, never from the bare branch name:
47
+ `git worktree add --detach <path> origin/<branch>`. Same scratch repo, same
48
+ moment: this landed on the remote's commit. It removes the mechanism rather
49
+ than catching it, and leaves no local ref for the next run to inherit.
50
+ - **Then verify against the branch REF, and refuse on mismatch.** Compare
51
+ `git -C <path> rev-parse HEAD` against
52
+ `git ls-remote origin refs/heads/<branch> | cut -f1` — the ref itself, which
53
+ is what the PR's head actually is, and **never `git rev-parse
54
+ origin/<branch>`**, which is the ref the worktree was just cut from and so
55
+ agrees with it by construction. Unequal → dispatch nothing into that
56
+ worktree, and report it naming BOTH commits, since their subjects will not
57
+ tell them apart. **An empty read is neither equal nor a mismatch**: the read
58
+ failed, or that head branch is not on `origin` at all (a fork PR, where the
59
+ creation form above cannot work either), so report the ref as unreadable
60
+ rather than the worktree as wrong — the same hole `[ -n "$pre" ]` closes on
61
+ the way into `run-merge-bot.md`'s step-1 poll.
62
+ - **Read `gh pr view <N> --json headRefOid -q .headRefOid` here too, and
63
+ record it — it is NOT the gate.** A `headRefOid` that disagrees with the ref
64
+ is the PR-object desync `run-merge-bot.md`'s step 1 says needs a controller,
65
+ so it is a fact to carry into that decision, never the operand this refusal
66
+ turns on.
67
+
68
+ **Why the ref and not `headRefOid`: during the PR object's lag both operands go
69
+ stale in the SAME direction, so that compare fails OPEN as readily as it fails
70
+ closed.** The PR object spends the lag sitting on the PRE-rebase sha — cleared
71
+ on re-poll attempt 24 (~2 min) in one merge pass and attempt 14 (~84s) in the next,
72
+ both after `gh pr update-branch --rebase` returned `rc=0`, measured in
73
+ `run-merge-bot.md`'s step 1 — and that is the very commit a clone which has not
74
+ fetched since the rebase still has `origin/<branch>` pointing at. So the false
75
+ REFUSAL (worktree current, PR object behind) is only half of it: cut the
76
+ worktree from the stale remote-tracking ref and both sides read the superseded
77
+ sha, the check reads EQUAL, and the dispatch lands on exactly the commit this
78
+ paragraph exists to catch. Measured in a scratch repo (git 2.50.1): with the
79
+ branch rebased onto an advanced `main`, force-pushed, and the clone not fetched
80
+ since, `git worktree add --detach <path> origin/<branch>` landed on the
81
+ pre-rebase `c774756` and printed its subject unchanged by the rebase, while
82
+ `git ls-remote origin refs/heads/<branch>` read the true tip `62ba798` from
83
+ that same unfetched clone. **Re-reading `headRefOid` on a settle window does
84
+ not reach that half at all** — it fires only where the two disagree — which is
85
+ why the operand changes here rather than the verdict gaining a window.
86
+
87
+ **A mismatch is usually one `git fetch origin` old, so `git worktree remove
88
+ --force <path>` first, then fetch and re-create once before reporting it.**
89
+ `git worktree add --detach <path> origin/<branch>` resolves the LOCAL
90
+ remote-tracking ref (measured above), so the ordinary cause is this clone's
91
+ own staleness, and re-creating after a fetch costs seconds where the refusal
92
+ costs a dispatch. **Bounded at one retry**: still unequal after the fetch →
93
+ refuse and report, because the second reading is a push that landed while
94
+ you worked, or a ref this clone cannot resolve, and neither gets better with
95
+ more waiting.
96
+
97
+ `review-core.mjs` refuses a snapshot whose head is not the branch ref's, so the
98
+ review path is backstopped — except when the operand comes back
99
+ empty, which skips the compare rather than refusing on it. A same-repo PR
100
+ still reads `refs/heads/<branch>` first and falls back to
101
+ `refs/pull/<number>/head` only when that comes back empty; a cross-repo PR (a
102
+ fork) skips the branch-ref read entirely and goes straight to the pull ref,
103
+ because a fork's branch NAME can collide with an unrelated branch the base
104
+ repo already carries under that name — so a fork PR now gets this
105
+ operand populated in the ordinary case, and the skip is rare rather than the
106
+ norm for forks. Its run log names the skip: `head ref (absent): head check
107
+ SKIPPED`. A worktree you hand to an agent directly is not backstopped at all.
108
+ Verify here anyway. **That backstop now compares against the same ref this
109
+ bullet does** — it moved its operand off `headRefOid` for the reason
110
+ above — so it is a second
111
+ chance to notice a stale snapshot on the one path it covers, never a reason
112
+ to skip the ref compare here.
113
+
11
114
  ## Filesystem isolation is not stack isolation
12
115
 
13
116
  Private copy and test command solve different problems; conflating them is how second gets skipped: compose project name comes from environment, not working directory, so three agents on three snapshots still collide on one postgres. Symlinking installed dependencies in does not help. "I'm on my own copy" is exactly the intuition that skips command — say both, every time. Which command depends on audience: member in worktree uses `./agent-test`; specialist on snapshot does not, takes one `review-and-fix.md` hands out. Which runner the worktree holds decides why: the runner a claim writes is untracked, so a `git archive` snapshot never carries it; one the repository tracks does ride along, but no claim exported ports into it — its isolation is whatever that repository built, not one triple per snapshot.
@@ -358,7 +358,7 @@ token, row}]}`:
358
358
  names. Reconcile them before shortlisting: read `proc://` once, find
359
359
  each `name` among this session's jobs, and act on its state.
360
360
  `running` → keep the token. `completed` or `failed` → record its
361
- result from `agent://<id>` as the **Record, then tick** table records
361
+ result from `agent://<id>` as the wake table of **Rule: record, tick, act, beat** records
362
362
  that member's report; an output you cannot read is a death the
363
363
  Member-killed row confirms. `cancelled` → record it dead. Absent, or a
364
364
  state you cannot read → keep the token live and let the Member-killed
@@ -0,0 +1,346 @@
1
+ # The Pull: what each step does and why
2
+
3
+ `pull.mjs` runs the Pull; SKILL.md's phase 1 says how to drive it, how to read the tick's `PULL` row and how to answer the questions it asks. This file is what each step means, and the measured reasons behind them, for the controller to read when a step refuses or an answer needs more than SKILL.md says.
4
+
5
+ ## The steps
6
+
7
+ The steps below are what the driver runs, and the guidance for answering
8
+ `staleness`, `decided` and `collision`.
9
+
10
+ One free implementer slot is one Pull. The tick names the heads — one `PULL` row
11
+ per free slot — and each Pull runs this sequence on its head,
12
+ terminating in exactly one dispatch or an empty shortlist:
13
+
14
+ 1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
15
+ `impl-` row and no `excluded` row whose premise still holds, which is the
16
+ ticket the tick's `PULL` row names.
17
+ 2. **In-flight check, again** — `~/.fleet/bin/fleet-run inflight.sh <N>`; any
18
+ hit = taken, drop it and take the next entry. The shortlist is as old as its
19
+ last refresh. It runs all three probes (PRs, remote heads, local
20
+ worktrees + branches) so a partial one cannot read as free. The PR probe is
21
+ two signals rather than a bare full-text match — GitHub's own closing-PR links
22
+ plus branch-segment matching — and both drop `MERGED` and `CLOSED`, so a
23
+ merged or abandoned PR the `gh pr list` window covers cannot hold a ticket
24
+ forever. A linked PR that window does *not* cover has no state to read: it
25
+ prints `?` and still counts as taken, merged or not.
26
+
27
+ **Exit 2 is not free** — the question went unanswered, so treat it as taken
28
+ and say which ticket it was in the log. A probe that could not look is
29
+ recorded rather than aborting the run, so exit 2 from one prints the same
30
+ JSON as 0 and 1 plus an `unknown[]` naming the probes that could not look:
31
+ read `unknown`, never `taken` alone, because exit 2 says `"taken": false`,
32
+ which summarizes `hits` and is not a claim the ticket is free. A hit outranks
33
+ an unknown — a payload can carry a non-empty `hits[]` and a non-empty
34
+ `unknown[]` at exit 1, which is taken. Four causes print nothing at all — a
35
+ bad argument, not inside a git repository, no such issue, a verdict that could
36
+ not be written — so never assume exit 2 parses.
37
+
38
+ **A free verdict is not evidence that nobody is editing the ticket's
39
+ target files.** All three probes ask whether a branch-shaped claim
40
+ exists — a PR, a remote head, a local branch, or a worktree — and
41
+ nothing else; work done directly against the shared checkout, by a
42
+ human or another agent session, stakes no branch-shaped claim and trips
43
+ none of them.
44
+ 3. **Read the ticket in full, once** — `gh issue view <N> --json title,body,comments,labels,createdAt`
45
+ written to `<scratch>/impl-<N>/issue.json`, then read off that file with `jq -r
46
+ '.title, .body, ([.labels[].name]|join(",")), (.comments[]|.author.login + ": " + .body)'`.
47
+ One read answers every question the Pull asks; step 7's router reads the same file. Record the ticket's real
48
+ brief — the `## Agent Brief` comment where one exists, otherwise the issue
49
+ body, which is where most tickets actually carry it (a controller probe found only 43/100 open
50
+ `ready-for-agent` issues have a separate Agent Brief comment; the rest,
51
+ this ticket included, carry the brief in the body) — plus its `Out of
52
+ scope` sequencing wherever that section is found. Then judge **decided?**
53
+ — never size.
54
+
55
+ **Still live?** A backlog ticket's claims rot. Before `decided?`, settle the
56
+ ticket's central claim against `origin/main` — never the working tree, never
57
+ the ticket's own line numbers, which drift. One `git show origin/main:<file>`
58
+ piped to `grep` does it for any ticket citing a construct, which is most of
59
+ them. **That read is fatal, not empty, when the path is untracked in
60
+ `origin/main`** — `git show origin/main:<path>` exits 128 saying the path
61
+ does not exist, and the file may still sit right there on disk, so it is a
62
+ probe that could not look rather than a clean tree. Fall back to
63
+ `git ls-tree origin/main -- <path>` (empty output at exit 0 = untracked)
64
+ before reading the failure as "unfixed". Already fixed → close it citing the
65
+ commit, do not claim it. Partly fixed → say which acceptance criteria the
66
+ tree already meets, and which the tree now **contradicts**.
67
+
68
+ Old string gone from `git show origin/main:<file>`
69
+ ⇒ the fix landed, and
70
+ `git log -S '<old string>' --oneline origin/main -- <file> | head -1` names
71
+ the commit that removed it; close citing that commit. Seconds either way,
72
+ and the construct half alone is the probe that could not look.
73
+ **No ancestry check on what that walk printed.** `origin/main` is where the
74
+ walk starts, so every commit it can print is reachable from `origin/main` by
75
+ construction, and `git merge-base --is-ancestor <sha> origin/main` is true
76
+ for all of them — true again when the sha *is* `origin/main`. A step that
77
+ cannot answer no is not evidence, and reads as evidence anyway.
78
+ **That check belongs one input over — a sha the TICKET quotes**, where it
79
+ can answer no: a rebase leaves the commit it orphaned a whole object, so
80
+ `git show` resolves it happily while nothing in `origin/main`'s history
81
+ reaches it, and a "fixed in `<sha>`" premise built on one describes a tree
82
+ that no longer exists. Separate its two non-zero answers before citing
83
+ either — exit 1 is the answer *not reachable*, while exit 128 with `Not a
84
+ valid object name` is a sha this clone does not have at all, a probe that
85
+ could not look rather than an orphan (measured: one ticket's comment cited
86
+ `35c0845` on a since-deleted branch, and 128 is what it exits here).
87
+
88
+ **Both halves of that command are load-bearing.** Drop the `origin/main`
89
+ argument and `git log -S` searches `HEAD`, contradicting the rule a paragraph
90
+ up — and the two searches fail differently there. On a checkout behind the
91
+ fix the prescribed **old**-string search names a *wrong* commit at exit 0,
92
+ the old string still being present in that tree: measured at
93
+ `0dc39ef^`, `| head -1` names the rename `4fd2f73`, not the fix. It is the
94
+ **new**-string search the paragraph above forbids that prints nothing at exit
95
+ 0 there, indistinguishable from "the change never landed"; the old-string
96
+ search goes empty on a checkout that predates the old string's own arrival
97
+ at that path — behind that rename in that case, and with no rename in play
98
+ at all in this file's: measured at `647ae44^`, which already tracks this
99
+ path under this name, `git log -S 'ls-tree origin/main'` prints nothing at
100
+ exit 0.
101
+ Add `--reverse` and you get the *oldest* count-changing commit, which is the
102
+ file's last rename whenever the string predates one — measured on a ticket's old
103
+ wording, `--reverse` names `4fd2f73` ("move next-ticket and sizing-a-ticket
104
+ into the plugin"), a refactor that clears an ancestry gate exactly as
105
+ well as the real fix, while newest-first `| head -1` names `0dc39ef`, the
106
+ commit that actually did it.
107
+ (`--follow` fixes the rename half but is mutually destructive with
108
+ `--reverse`: the two together return empty at exit 0, and `--follow` takes
109
+ exactly one pathspec or exits 128.) So read the subject of whatever it names
110
+ before citing it in the close, and treat empty output as an answer you did
111
+ not get rather than a commit.
112
+
113
+ Measured, one run: one ticket's one-line remedy had shipped in `e7b11e6` ten days
114
+ earlier and another's AC-2 asked for an exit code a later design
115
+ deliberately changed — neither commit carried a trailer back, so the tracker
116
+ showed both as open work. The one-line-remedy ticket cost a full claim, worktree and implementer
117
+ dispatch to learn this; the exit-code ticket would have shipped a test asserting the opposite
118
+ of the shipped behaviour. The two probes that settled both took seconds.
119
+ **A ticket deferred from a review is a claim about a tree that has since
120
+ moved** — and the older the ticket, the more it has moved, so this bites
121
+ hardest at exactly the head of an oldest-first queue.
122
+
123
+ Measured again 2026-08-19: four stale in the 20 oldest, and the construct
124
+ probe caught **none** of the four. It **missed** a ticket whose two pins and the
125
+ `contentWords()` extraction it asks for had all landed (`d016414`, `1abd6c8`)
126
+ while `overlap()`, the construct, sat right where the ticket said, so the
127
+ probe passed the ticket through as live work and it cost a claim, a worktree
128
+ and a dispatch. It **missed** a ticket whose `d:` scan the candidates test suite
129
+ already pinned — `6d94451` and `43d6ac5` both added `.d` assertions, and the
130
+ ticket's own closing comment cites both. It **missed** a ticket whose wording
131
+ defect `0dc39ef` had already fixed — by an **equivalent rewording**, not by
132
+ the literal string the ticket proposed, which appears nowhere in
133
+ `origin/main`; the ticket's **line number** had drifted too, `:95` → `:98`.
134
+ And one ticket it could not read at all: that ticket's file is untracked in
135
+ `origin/main`, the fatal-not-empty case above.
136
+
137
+ **`staleness.mjs` runs that check for you, and answers in THREE values.**
138
+ `~/.fleet/bin/fleet-run staleness.mjs --path <path> --gone
139
+ '<string>'`, or `--present '<string>'`, once per claim the ticket makes.
140
+ It goes here and not in `shortlist.mjs` because choosing WHICH string
141
+ settles a ticket needs the ticket read, which the step above already did —
142
+ so the cost lands on the pulled ticket and never on the backlog.
143
+ `--gone` is a defect the fix must remove, the wording the ticket quotes as
144
+ wrong; `--present` is what the fix must add, the assertion a pin ticket asks
145
+ for. Give exactly one — the direction is not inferable from the string, and
146
+ the wrong one answers the opposite verdict with full confidence.
147
+
148
+ A needle that itself starts with `--` — `--label ready-for-agent`
149
+ is one this backlog carries — needs the end-of-options separator: `--gone
150
+ -- '<string>'`/`--present -- '<string>'`. Given bare, with no `--`
151
+ immediately before it, the value guard still refuses it — `staleness:
152
+ --gone needs a value` — at exit 2, a could-not-check to admit and annotate,
153
+ not an invocation to retry.
154
+
155
+ The third value is the one that has to survive. A probe that could not look
156
+ answers exactly like a probe that looked and found nothing, so folding it
157
+ into either neighbour retires live supply on a guess in one direction and
158
+ reports a defect as live on a spelling the tree stopped using in the other.
159
+ Exit 2 is also where every guard and every failed git call in that script
160
+ lands, so a probe that breaks keeps the ticket in the queue.
161
+
162
+ What it refuses to answer is the point of it. It reads `origin/main` and
163
+ nothing else — never the working tree, never anything on disk — so a path
164
+ this repo does not track is exit 2 rather than a clean read: that is the untracked-file
165
+ case and the generated-artifact case together, `agent-test` being written
166
+ into a claimed worktree by `claim-ticket.sh`'s heredoc, which makes every
167
+ copy under `.worktrees/` a snapshot of whenever that worktree was claimed.
168
+ `fixed` is never read off the string's presence alone either: it carries the
169
+ commit `git log -S` names for that string at that path, reachable from
170
+ `origin/main` by construction since that is where the walk starts. A
171
+ `--gone` string absent from the file that ALSO never changed count there is
172
+ exit 2, not a fix — that is the positive control, and without it a typo in
173
+ the string closes a live ticket.
174
+
175
+ It does not run a reproduction. The general "is this still reproducible?"
176
+ oracle over the whole backlog is ruled out, and a reproduction run
177
+ without a positive and a negative control misattributes causes rather than
178
+ merely missing defects — one such check needed a purpose-built fixture plus
179
+ both. A ticket no single string settles is a `could not check`: admitted,
180
+ annotated in the dispatch prompt (phase 2), never quietly dropped.
181
+
182
+ **This is a consumption gate**, priced for the seat where implementer
183
+ divergence costs a claim, a worktree and a dispatch; at filing time every
184
+ issue the plugin creates is filed `needs-triage`, and only triage sets
185
+ `ready-for-agent`.
186
+
187
+ No sizing agent here. `sizing-a-ticket` picks the *process path*, and that is
188
+ phase 2's call, after the ticket is claimed.
189
+ 4. **Collision scan against open PRs and live branches** — `pull.mjs` runs it
190
+ before Q3 and prints one line per open PR or live worktree branch that shares
191
+ a path with the brief, `no overlap` when none, and `could not look: <which>`
192
+ for one it could not read. Answer Q3 off those lines: an overlap →
193
+ `behind-pr:#M`, a branch with no PR yet by its name; a target file the brief
194
+ does not spell as a path → `paths <p>…`, which scans again and asks again. A
195
+ PR the scan could not read is still yours to judge, and `behind-pr` on it is
196
+ taken. `pr-overlap.mjs` is **PR-vs-PR only** — it runs `gh pr diff` on both
197
+ args and errors on an issue number, so never run it on a ticket here.
198
+ 5. **Sequence check** — the `#N` refs of the brief's `Out of scope` section are
199
+ printed beside Q3 as the candidates: one naming an open ticket this one
200
+ sequences after → `behind-issue:#M`. No overlap and no such ticket →
201
+ `clear`.
202
+ 6. **Claim** — `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer
203
+ --apply` (below). Exit 2 → treat it as taken, next entry.
204
+ 7. **Route, row, then dispatch** — `~/.fleet/bin/fleet-run ticket-router.mjs route
205
+ --session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
206
+ <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints
207
+ `POLICY=… CELL=… DRAW=… STRATUM=… REASON=…` (phase 2's exploration rule
208
+ says what each argument is); then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>][ · route=<REASON>]"`,
209
+ `tier=<CELL>` exactly when `DRAW` is not `-`; then phase 2 at once: claim
210
+ what you are about to dispatch; dispatch what you have just claimed. Router
211
+ exit 2 → no row and no dispatch: release the claim (`release-ticket.sh`, SKILL.md's
212
+ **Release the claims that never became PRs**) and emit an event, a probe that could not look — a table the router
213
+ refuses refuses every Pull.
214
+
215
+ **The Pull table** — every verdict a Pull can reach, and the one thing each
216
+ does:
217
+
218
+ | At the Pull | Action |
219
+ |---|---|
220
+ | in-flight hit, or an in-flight check that could not answer | drop, next entry |
221
+ | no longer labelled `ready-for-agent` | drop, next entry |
222
+ | `staleness.mjs` exit 1 — provably fixed | close citing the commit, next entry |
223
+ | brief names no *what* | relabel `needs-triage`, next entry |
224
+ | genuine fork — options named, none ruled | relabel `ready-for-human`, next entry |
225
+ | needs human hands — external access, manual testing, judgment during the work | relabel `ready-for-human`, next entry |
226
+ | target files collide with an open PR or a live branch | exclude `behind-pr:#M`, next entry |
227
+ | `Out of scope` sequences it after an open ticket | exclude `behind-issue:#M`, next entry |
228
+ | `claim-ticket.sh` exit 2 | taken, next entry |
229
+ | decided, live, free, claimed | row, then dispatch (phase 2) |
230
+
231
+ **The shortlist runs out → run `shortlist.mjs` once and Pull again; still
232
+ empty → hold the slot idle until the next refresh trigger.** Within a turn,
233
+ Pull from the current list first and refresh second — a refresh never delays a
234
+ dispatch.
235
+
236
+ ## Relabels and exclusions
237
+
238
+ **A Pull never re-admits a ticket already relabelled.** The shortlist file can
239
+ be older than a relabel — this run's own Pulls, or a demotion in phase 3 — so
240
+ read the ticket's labels in step 3's full read (`--json
241
+ title,body,comments,labels`) and drop it when `ready-for-agent` is gone. A Pull
242
+ that trusted a list built before the relabel landed would hand a ticket the
243
+ fleet has already judged unimplementable straight to the next member.
244
+
245
+ **Relabel by cause.** An unclaimed ticket is yours to reclassify at the Pull —
246
+ three causes, two labels: `ready-for-human` for hands or a fork;
247
+ `needs-triage` for a brief that names no *what*.
248
+ `gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
249
+ `in-progress` to drop — it was never claimed), preceded by exactly one comment,
250
+ the one `~/.fleet/bin/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
251
+ prints. `--kind needs-triage` takes `--line`, the one-line missing decision;
252
+ `--kind fork` takes `--options`, the options verbatim from the brief, and is
253
+ the `ready-for-human` comment for a fork; `--kind hands` takes `--hands`,
254
+ one of external access, manual testing or judgment during the work, and
255
+ `--line`, and is the `ready-for-human` comment for hands. The three comments
256
+ live in `briefs/relabel.md`; `pull.mjs` posts its own one-line copy of the same
257
+ words when a Pull answer relabels, so a change to either is a change to both.
258
+
259
+ Neither label invokes anything: `/triage` is maintainer-run, and both labels
260
+ only stop the ticket costing a read per scan. These comments are the only
261
+ writes the fleet makes to a ticket it did not claim.
262
+
263
+ **Exclusion is a ticket row with a premise.** `ledger.mjs row <N> "excluded ·
264
+ behind-pr:#M"` or `ledger.mjs row <N> "excluded · behind-issue:#M"` — `#M` is
265
+ the open PR, or the branch name until its PR exists, or the issue this ticket
266
+ sequences after. No new ledger section. `shortlist.mjs` probes every premise at
267
+ each refresh — MERGED or CLOSED lifts a `behind-pr`, CLOSED lifts a
268
+ `behind-issue` — and a lifted ticket re-enters the shortlist in its own
269
+ oldest-first slot; its row is rewritten to `impl-<N> …` when it is pulled,
270
+ because `row` replaces the whole line.
271
+
272
+ ## Claiming
273
+
274
+ **Claiming.** `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
275
+ the label, worktree, branch, the Recipe's Install step, the clean-tree assertion, and the
276
+ isolation runner in one serial pass. The two arguments are always that literal
277
+ pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
278
+ branch `implementer/<N>-impl-<N>`, worktree `.worktrees/<N>-impl-<N>`. Never
279
+ read them off `git branch -r` or `git worktree list`: human branches on origin
280
+ (`fix/…`, `docs/…`) have another shape, and the script takes both arguments as
281
+ free text, so a pair copied from one claims under that shape at exit 0.
282
+
283
+ **The Install step comes from the Recipe cache — never pass or infer one.** The
284
+ claim reads it through `derive-testcmd.sh . install`, and the Test entrypoint
285
+ through `derive-testcmd.sh . test --at origin/main`, runs the
286
+ Install step in the fresh worktree and refuses if it left any file changed: an
287
+ install that rewrites the tree in a throwaway worktree corrupts it for everyone.
288
+ No cache is phase 0's Recipe derivation step not having run; an invalid one is
289
+ its re-derive-once rule.
290
+
291
+ **Materialize the isolation envelope as a file, not a briefing.** The claim
292
+ writes the runner, `agent-test`, into the fresh worktree it creates: an exec of
293
+ the Recipe's Test entrypoint, through the suite-slot wrapper (see SKILL.md's **The
294
+ suite slot bound**), that exports one port triple derived from `<N>`
295
+ (so collisions stay impossible), kept out of `git status` through the
296
+ repository's exclude file. A repository that tracks its own `agent-test` keeps
297
+ it byte-identical, with whatever isolation that repository built, and takes the
298
+ suite slot bound for its own full runs itself: nothing else will. Brief members
299
+ with `./agent-test` and nothing else — anyone who finds the worktree finds the
300
+ runner, including grandchildren you never dispatched. Its arguments land after
301
+ the Test entrypoint, so what one may name — a test file, a test name — is that
302
+ entrypoint's to say, and nothing in the runner refuses one that selects no
303
+ test: a run of zero tests is a failed run, not a pass. See isolation.md.
304
+
305
+ ## Claim, record, render: the dispatch steps
306
+
307
+ **Claim what you are about to dispatch; dispatch what you have just claimed.**
308
+ Phase 1 makes the claim, serially in the main checkout — its rule is measured —
309
+ and the dispatch follows it at once. A claim that runs ahead of its dispatch is
310
+ a worktree, a branch and an `in-progress` label with no member behind them,
311
+ released by the end-of-run sweep rather than by a member that did the work.
312
+
313
+ **Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
314
+ the Pull's step 7; `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
315
+ implementer --member impl-<N> …` then renders its brief, and
316
+ `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
317
+ marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
318
+ Its JSON carries `agent`, the definition that call names, and `brief.path`,
319
+ the rendered brief whose content is that call's prompt — read both off that
320
+ output, never recall them. Live implementers are the `impl-` tokens with no
321
+ `=<outcome>` — the tick reads that count off the ledger, and nobody states
322
+ it. `dispatch` refuses a member with no brief rendered for its role, naming
323
+ the `render` command to run first, and refuses once the
324
+ run is draining: drain stops supply. It also refuses a row whose `tier=`
325
+ names no single definition — two different values, or one that is not a
326
+ definition suffix — or names one with no `agents/<definition>.agent.md`,
327
+ before the member is live; fix the row with `row` first.
328
+
329
+ **The prompt carries only what varies.** Everything shared — the
330
+ unattended-member block, the `edit`/`read` absolute-path rule, the
331
+ issue re-read and re-derive backstop, commit incrementally, no `git stash`, the
332
+ shared `eval` kernel, enumerate-and-declare, sizing and the PR steps —
333
+ is the body of every `agents/fleet-implementer-<cell>.agent.md`, byte-identical
334
+ across all of them, and each harness injects it as the
335
+ member's system prompt. Never re-paste it. The prompt fills that body's
336
+ placeholders — the ticket number, the worktree abs path and branch
337
+ (`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/` — absolute,
338
+ `<scratch>` as `scratch-root.mjs` printed it — and the
339
+ distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
340
+ comment or the issue body, whichever carries the brief, and its `Out of
341
+ scope`, pasted verbatim from the Pull's own read. Beyond those
342
+ `briefs/implementer.md` carries only its report paragraph, the
343
+ no-acknowledgement line, the foreground-suite line
344
+ — and a `staleness.mjs` **could not check** verdict with its
345
+ reason when the Pull got one, so the member's own re-derive step knows the
346
+ controller's probe could not look.