@feigi/fleet-ctl 3.67.0 → 3.68.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.
@@ -311,7 +311,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
311
311
  blocker → drop.
312
312
  - **Live Exclusions** — a ticket whose ledger row reads `excluded ·
313
313
  behind-pr:#M` or `excluded · behind-issue:#M` stays out while its premise
314
- holds (phase 1, **Exclusion**).
314
+ holds (references/pull.md, **Exclusion**).
315
315
  - **In-flight check** — `inflight.sh <N>` per survivor. Exit 1 is taken, and
316
316
  any other non-zero exit is a check that could not answer, which is never
317
317
  free. Both drop the ticket, logged by number.
@@ -373,7 +373,7 @@ concurrent `worktree add` and label writes race.
373
373
 
374
374
  A Pull's entry is `~/.fleet/bin/fleet-run pull.mjs next --head <N>`, run from the
375
375
  main checkout (without `--head`, the next shortlist entry). It runs the
376
- mechanical steps below in order and stops at each judgement with a `QUESTION
376
+ mechanical steps in order and stops at each judgement with a `QUESTION
377
377
  <qid>:` block and exit 10; `pull.mjs answer <N> <qid> <token> [--path <p>] [--]
378
378
  [<text>…]` records the answer and resumes it. Exit 0 prints `DISPATCH {name,
379
379
  agent, brief}`, the `task` call phase 2 makes; exit 1 means the ticket left the
@@ -382,67 +382,31 @@ Pull, so take the next entry; exit 2 names what could not be looked at —
382
382
  retries one that failed while applying an answer (the question stands), and
383
383
  after a router refusal `next --head <N>` starts the ticket over; exit 3 is a
384
384
  usage mistake, or an answer the question does not take, and records nothing.
385
- The record is `<scratch>/impl-<N>/pull.json`. The steps below are what
386
- the driver runs, and the guidance for answering `staleness`, `decided` and
387
- `collision`.
388
-
389
- One free implementer slot is one Pull. The tick names the heads — `PULL #<n>
390
- #<m>`, one per free slot — and each Pull runs this sequence on its head,
391
- terminating in exactly one dispatch or an empty shortlist:
392
-
393
- 1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
394
- `impl-` row and no `excluded` row whose premise still holds, which is the
395
- ticket the tick's `PULL` row names.
396
- 2. **In-flight check, again** — `~/.fleet/bin/fleet-run inflight.sh <N>`; any
397
- hit = taken, drop it and take the next entry. The shortlist is as old as its
398
- last refresh. It runs all three probes (PRs, remote heads, local
399
- worktrees + branches) so a partial one cannot read as free. The PR probe is
400
- two signals rather than a bare full-text match — GitHub's own closing-PR links
401
- plus branch-segment matching — and both drop `MERGED` and `CLOSED`, so a
402
- merged or abandoned PR the `gh pr list` window covers cannot hold a ticket
403
- forever. A linked PR that window does *not* cover has no state to read: it
404
- prints `?` and still counts as taken, merged or not.
405
-
406
- **Exit 2 is not free** — the question went unanswered, so treat it as taken
407
- and say which ticket it was in the log. A probe that could not look is
408
- recorded rather than aborting the run, so exit 2 from one prints the same
409
- JSON as 0 and 1 plus an `unknown[]` naming the probes that could not look:
410
- read `unknown`, never `taken` alone, because exit 2 says `"taken": false`,
411
- which summarizes `hits` and is not a claim the ticket is free. A hit outranks
412
- an unknown — a payload can carry a non-empty `hits[]` and a non-empty
413
- `unknown[]` at exit 1, which is taken. Four causes print nothing at all — a
414
- bad argument, not inside a git repository, no such issue, a verdict that could
415
- not be written — so never assume exit 2 parses.
416
-
417
- **A free verdict is not evidence that nobody is editing the ticket's
418
- target files.** All three probes ask whether a branch-shaped claim
419
- exists — a PR, a remote head, a local branch, or a worktree — and
420
- nothing else; work done directly against the shared checkout, by a
421
- human or another agent session, stakes no branch-shaped claim and trips
422
- none of them.
423
- 3. **Read the ticket in full, once** — `gh issue view <N> --json title,body,comments,labels,createdAt`
424
- written to `<scratch>/impl-<N>/issue.json`, then read off that file with `jq -r
425
- '.title, .body, ([.labels[].name]|join(",")), (.comments[]|.author.login + ": " + .body)'`.
426
- One read answers every question the Pull asks; step 7's router reads the same file. Record the ticket's real
427
- brief — the `## Agent Brief` comment where one exists, otherwise the issue
428
- body, which is where most tickets actually carry it (a controller probe found only 43/100 open
429
- `ready-for-agent` issues have a separate Agent Brief comment; the rest,
430
- this ticket included, carry the brief in the body) — plus its `Out of
431
- scope` sequencing wherever that section is found. Then judge **decided?**
432
- — never size.
433
-
434
- **Still live?** A backlog ticket's claims rot. Before `decided?`, settle the
435
- ticket's central claim against `origin/main` — never the working tree, never
436
- the ticket's own line numbers, which drift. One `git show origin/main:<file>`
437
- piped to `grep` does it for any ticket citing a construct, which is most of
438
- them. **That read is fatal, not empty, when the path is untracked in
439
- `origin/main`** — `git show origin/main:<path>` exits 128 saying the path
440
- does not exist, and the file may still sit right there on disk, so it is a
441
- probe that could not look rather than a clean tree. Fall back to
442
- `git ls-tree origin/main -- <path>` (empty output at exit 0 = untracked)
443
- before reading the failure as "unfixed". Already fixed → close it citing the
444
- commit, do not claim it. Partly fixed → say which acceptance criteria the
445
- tree already meets, and which the tree now **contradicts**.
385
+ The record is `<scratch>/impl-<N>/pull.json`. See references/pull.md for what
386
+ each step does, and why.
387
+
388
+ **The tick's `PULL` rows name the command.** One free implementer slot is one
389
+ Pull, and each head a free slot Pulls gets its own row, read off that head's
390
+ `pull.json` and never folded:
391
+
392
+ | Row | Where the Pull stands |
393
+ |---|---|
394
+ | `PULL #N — pull.mjs next --head N` | none of this run's in progress — `next` starts it, or resumes one a failed step left |
395
+ | `PULL #N (Q2 pending — pull.mjs answer N decided …)` | a question stands: answer it; `next --head N` prints it again |
396
+ | `… (stale)` appended | that question has stood longer than `--pull-stale-minutes` (120 by default) |
397
+ | `PULL #N (dispatched, row missing — ledger.mjs row N "…")` | dispatched, yet the head holds no `impl-` row: write the row it names |
398
+
399
+ A head whose Pull already ended in this run — the ticket left, or the router
400
+ refused it and its claim was released — gets no row: `next` without `--head`
401
+ skips it, `next --head <N>` would start the ticket over, and the next head
402
+ fills the slot.
403
+
404
+ **The questions**, each answered with `pull.mjs answer <N> <qid> <token> …`:
405
+
406
+ 1. **`staleness` (Q1)** — `gone --path <p> [--] <string>`, the string the fix
407
+ must remove from `<p>` on `origin/main`, or `present --path <p> [--]
408
+ <string>`, the string it must add: each runs `staleness.mjs` and asks again.
409
+ `none <why>` (no string settles it) and `done` end the question.
446
410
 
447
411
  **Grep for the ticket's ASKED-FOR CHANGE, not only its subject construct** —
448
412
  the construct check passes on every stale pin ticket, because the construct
@@ -452,92 +416,9 @@ terminating in exactly one dispatch or an empty shortlist:
452
416
  quotes as wrong, never the new wording it proposes. A proposed replacement is
453
417
  a suggestion the implementer is free to reword — an equivalent rewording
454
418
  satisfies the ticket while failing a grep for its literal text — and the
455
- quoted defect is the fact. Old string gone from `git show origin/main:<file>`
456
- ⇒ the fix landed, and
457
- `git log -S '<old string>' --oneline origin/main -- <file> | head -1` names
458
- the commit that removed it; close citing that commit. Seconds either way,
459
- and the construct half alone is the probe that could not look.
460
- **No ancestry check on what that walk printed.** `origin/main` is where the
461
- walk starts, so every commit it can print is reachable from `origin/main` by
462
- construction, and `git merge-base --is-ancestor <sha> origin/main` is true
463
- for all of them — true again when the sha *is* `origin/main`. A step that
464
- cannot answer no is not evidence, and reads as evidence anyway.
465
- **That check belongs one input over — a sha the TICKET quotes**, where it
466
- can answer no: a rebase leaves the commit it orphaned a whole object, so
467
- `git show` resolves it happily while nothing in `origin/main`'s history
468
- reaches it, and a "fixed in `<sha>`" premise built on one describes a tree
469
- that no longer exists. Separate its two non-zero answers before citing
470
- either — exit 1 is the answer *not reachable*, while exit 128 with `Not a
471
- valid object name` is a sha this clone does not have at all, a probe that
472
- could not look rather than an orphan (measured: one ticket's comment cited
473
- `35c0845` on a since-deleted branch, and 128 is what it exits here).
474
-
475
- **Both halves of that command are load-bearing.** Drop the `origin/main`
476
- argument and `git log -S` searches `HEAD`, contradicting the rule a paragraph
477
- up — and the two searches fail differently there. On a checkout behind the
478
- fix the prescribed **old**-string search names a *wrong* commit at exit 0,
479
- the old string still being present in that tree: measured at
480
- `0dc39ef^`, `| head -1` names the rename `4fd2f73`, not the fix. It is the
481
- **new**-string search the paragraph above forbids that prints nothing at exit
482
- 0 there, indistinguishable from "the change never landed"; the old-string
483
- search goes empty on a checkout that predates the old string's own arrival
484
- at that path — behind that rename in that case, and with no rename in play
485
- at all in this file's: measured at `647ae44^`, which already tracks this
486
- path under this name, `git log -S 'ls-tree origin/main'` prints nothing at
487
- exit 0.
488
- Add `--reverse` and you get the *oldest* count-changing commit, which is the
489
- file's last rename whenever the string predates one — measured on a ticket's old
490
- wording, `--reverse` names `4fd2f73` ("move next-ticket and sizing-a-ticket
491
- into the plugin"), a refactor that clears an ancestry gate exactly as
492
- well as the real fix, while newest-first `| head -1` names `0dc39ef`, the
493
- commit that actually did it.
494
- (`--follow` fixes the rename half but is mutually destructive with
495
- `--reverse`: the two together return empty at exit 0, and `--follow` takes
496
- exactly one pathspec or exits 128.) So read the subject of whatever it names
497
- before citing it in the close, and treat empty output as an answer you did
498
- not get rather than a commit.
499
-
500
- Measured, one run: one ticket's one-line remedy had shipped in `e7b11e6` ten days
501
- earlier and another's AC-2 asked for an exit code a later design
502
- deliberately changed — neither commit carried a trailer back, so the tracker
503
- showed both as open work. The one-line-remedy ticket cost a full claim, worktree and implementer
504
- dispatch to learn this; the exit-code ticket would have shipped a test asserting the opposite
505
- of the shipped behaviour. The two probes that settled both took seconds.
506
- **A ticket deferred from a review is a claim about a tree that has since
507
- moved** — and the older the ticket, the more it has moved, so this bites
508
- hardest at exactly the head of an oldest-first queue.
509
-
510
- Measured again 2026-08-19: four stale in the 20 oldest, and the construct
511
- probe caught **none** of the four. It **missed** a ticket whose two pins and the
512
- `contentWords()` extraction it asks for had all landed (`d016414`, `1abd6c8`)
513
- while `overlap()`, the construct, sat right where the ticket said, so the
514
- probe passed the ticket through as live work and it cost a claim, a worktree
515
- and a dispatch. It **missed** a ticket whose `d:` scan the candidates test suite
516
- already pinned — `6d94451` and `43d6ac5` both added `.d` assertions, and the
517
- ticket's own closing comment cites both. It **missed** a ticket whose wording
518
- defect `0dc39ef` had already fixed — by an **equivalent rewording**, not by
519
- the literal string the ticket proposed, which appears nowhere in
520
- `origin/main`; the ticket's **line number** had drifted too, `:95` → `:98`.
521
- And one ticket it could not read at all: that ticket's file is untracked in
522
- `origin/main`, the fatal-not-empty case above.
523
-
524
- **`staleness.mjs` runs that check for you, and answers in THREE values.**
525
- `~/.fleet/bin/fleet-run staleness.mjs --path <path> --gone
526
- '<string>'`, or `--present '<string>'`, once per claim the ticket makes.
527
- It goes here and not in `shortlist.mjs` because choosing WHICH string
528
- settles a ticket needs the ticket read, which the step above already did —
529
- so the cost lands on the pulled ticket and never on the backlog.
530
- `--gone` is a defect the fix must remove, the wording the ticket quotes as
531
- wrong; `--present` is what the fix must add, the assertion a pin ticket asks
532
- for. Give exactly one — the direction is not inferable from the string, and
533
- the wrong one answers the opposite verdict with full confidence.
534
-
535
- A needle that itself starts with `--` — `--label ready-for-agent`
536
- is one this backlog carries — needs the end-of-options separator: `--gone
537
- -- '<string>'`/`--present -- '<string>'`. Given bare, with no `--`
538
- immediately before it, the value guard still refuses it — `staleness:
539
- --gone needs a value` — at exit 2, a could-not-check to admit and annotate,
540
- not an invocation to retry.
419
+ quoted defect is the fact.
420
+
421
+ `staleness.mjs` answers each `gone` and `present` in three values:
541
422
 
542
423
  | Exit | Verdict | What it does at the Pull |
543
424
  |---|---|---|
@@ -545,32 +426,14 @@ terminating in exactly one dispatch or an empty shortlist:
545
426
  | 1 | provably fixed | do not admit; close citing the payload's `commit` and `subject` |
546
427
  | 2 | could not check | admit it, **and say the probe could not check** |
547
428
 
548
- The third value is the one that has to survive. A probe that could not look
549
- answers exactly like a probe that looked and found nothing, so folding it
550
- into either neighbour retires live supply on a guess in one direction and
551
- reports a defect as live on a spelling the tree stopped using in the other.
552
- Exit 2 is also where every guard and every failed git call in that script
553
- lands, so a probe that breaks keeps the ticket in the queue.
554
-
555
- What it refuses to answer is the point of it. It reads `origin/main` and
556
- nothing else — never the working tree, never anything on disk — so a path
557
- this repo does not track is exit 2 rather than a clean read: that is the untracked-file
558
- case and the generated-artifact case together, `agent-test` being written
559
- into a claimed worktree by `claim-ticket.sh`'s heredoc, which makes every
560
- copy under `.worktrees/` a snapshot of whenever that worktree was claimed.
561
- `fixed` is never read off the string's presence alone either: it carries the
562
- commit `git log -S` names for that string at that path, reachable from
563
- `origin/main` by construction since that is where the walk starts. A
564
- `--gone` string absent from the file that ALSO never changed count there is
565
- exit 2, not a fix — that is the positive control, and without it a typo in
566
- the string closes a live ticket.
567
-
568
- It does not run a reproduction. The general "is this still reproducible?"
569
- oracle over the whole backlog is ruled out, and a reproduction run
570
- without a positive and a negative control misattributes causes rather than
571
- merely missing defects — one such check needed a purpose-built fixture plus
572
- both. A ticket no single string settles is a `could not check`: admitted,
573
- annotated in the dispatch prompt (phase 2), never quietly dropped.
429
+ 2. **`close` (Q1b)** — asked when the probe exits 1 naming a commit: `yes`
430
+ closes the issue with a comment citing the commit and its subject; `no
431
+ <why>` keeps the ticket and asks Q1 again.
432
+ 3. **`decided` (Q2)** — `decided`, `needs-triage <the missing decision>`,
433
+ `ready-for-human-fork <the options, verbatim from the brief>` or
434
+ `ready-for-human-hands <external access|manual testing|judgment> <one
435
+ line>`; any but `decided` posts that cause's comment and replaces
436
+ `ready-for-agent` with its label.
574
437
 
575
438
  **Decided?** Would two competent implementers, reading only this ticket, build
576
439
  materially different things? "Material" by inventory, not feel:
@@ -587,226 +450,33 @@ terminating in exactly one dispatch or an empty shortlist:
587
450
  Pull surfaces it to the maintainer. Opposite of
588
451
  `sizing-a-ticket`'s *torn → take the heavier row*, deliberately — see that skill.
589
452
 
590
- **This is a consumption gate**, priced for the seat where implementer
591
- divergence costs a claim, a worktree and a dispatch; at filing time every
592
- issue the plugin creates is filed `needs-triage`, and only triage sets
593
- `ready-for-agent`.
594
-
595
- No sizing agent here. `sizing-a-ticket` picks the *process path*, and that is
596
- phase 2's call, after the ticket is claimed.
597
- 4. **Collision scan against open PRs and live branches** — `pull.mjs` runs it
598
- before Q3 and prints one line per open PR or live worktree branch that shares
599
- a path with the brief, `no overlap` when none, and `could not look: <which>`
600
- for one it could not read. Answer Q3 off those lines: an overlap →
601
- `behind-pr:#M`, a branch with no PR yet by its name; a target file the brief
602
- does not spell as a path → `paths <p>…`, which scans again and asks again. A
603
- PR the scan could not read is still yours to judge, and `behind-pr` on it is
604
- taken. `pr-overlap.mjs` is **PR-vs-PR only** — it runs `gh pr diff` on both
605
- args and errors on an issue number, so never run it on a ticket here.
606
- 5. **Sequence check** — the `#N` refs of the brief's `Out of scope` section are
607
- printed beside Q3 as the candidates: one naming an open ticket this one
608
- sequences after → `behind-issue:#M`. No overlap and no such ticket →
609
- `clear`.
610
- 6. **Claim** — `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer
611
- --apply` (below). Exit 2 → treat it as taken, next entry.
612
- 7. **Route, row, then dispatch** — `~/.fleet/bin/fleet-run ticket-router.mjs route
613
- --session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
614
- <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints
615
- `POLICY=… CELL=… DRAW=… STRATUM=… REASON=…` (phase 2's exploration rule
616
- says what each argument is); then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>][ · route=<REASON>]"`,
617
- `tier=<CELL>` exactly when `DRAW` is not `-`; then phase 2 at once: claim
618
- what you are about to dispatch; dispatch what you have just claimed. Router
619
- exit 2 → no row and no dispatch: release the claim (`release-ticket.sh`,
620
- below) and emit an event, a probe that could not look — a table the router
621
- refuses refuses every Pull.
622
-
623
- **The Pull table** — every verdict a Pull can reach, and the one thing each
624
- does:
625
-
626
- | At the Pull | Action |
627
- |---|---|
628
- | in-flight hit, or an in-flight check that could not answer | drop, next entry |
629
- | no longer labelled `ready-for-agent` | drop, next entry |
630
- | `staleness.mjs` exit 1 — provably fixed | close citing the commit, next entry |
631
- | brief names no *what* | relabel `needs-triage`, next entry |
632
- | genuine fork — options named, none ruled | relabel `ready-for-human`, next entry |
633
- | needs human hands — external access, manual testing, judgment during the work | relabel `ready-for-human`, next entry |
634
- | target files collide with an open PR or a live branch | exclude `behind-pr:#M`, next entry |
635
- | `Out of scope` sequences it after an open ticket | exclude `behind-issue:#M`, next entry |
636
- | `claim-ticket.sh` exit 2 | taken, next entry |
637
- | decided, live, free, claimed | row, then dispatch (phase 2) |
638
-
639
- **The shortlist runs out → run `shortlist.mjs` once and Pull again; still
640
- empty → hold the slot idle until the next refresh trigger.** Within a turn,
641
- Pull from the current list first and refresh second — a refresh never delays a
642
- dispatch.
453
+ 4. **`collision` (Q3)** — asked after the scan prints one line per open PR or
454
+ live worktree branch sharing a path with the brief (`no overlap` when none,
455
+ `could not look: <which>` for one it could not read) and the brief's `Out of
456
+ scope` `#N` refs as candidates: `clear`; `behind-pr:#M`, an open PR or a
457
+ branch with no PR yet by its name; `behind-issue:#M`, an open issue that
458
+ section sequences this one after; or `paths <p>…`, which scans again.
643
459
 
644
- **A Pull never re-admits a ticket already relabelled.** The shortlist file can
645
- be older than a relabel — this run's own Pulls, or a demotion in phase 3 — so
646
- read the ticket's labels in step 3's full read (`--json
647
- title,body,comments,labels`) and drop it when `ready-for-agent` is gone. A Pull
648
- that trusted a list built before the relabel landed would hand a ticket the
649
- fleet has already judged unimplementable straight to the next member.
650
-
651
- **Relabel by cause.** An unclaimed ticket is yours to reclassify at the Pull —
652
- three causes, two labels: `ready-for-human` for hands or a fork;
653
- `needs-triage` for a brief that names no *what*.
654
- `gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
655
- `in-progress` to drop — it was never claimed), preceded by exactly one comment,
656
- the one `~/.fleet/bin/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
657
- prints. `--kind needs-triage` takes `--line`, the one-line missing decision;
658
- `--kind fork` takes `--options`, the options verbatim from the brief, and is
659
- the `ready-for-human` comment for a fork; `--kind hands` takes `--hands`,
660
- one of external access, manual testing or judgment during the work, and
661
- `--line`, and is the `ready-for-human` comment for hands. The three comments
662
- live in `briefs/relabel.md`; `pull.mjs` posts its own one-line copy of the same
663
- words when a Pull answer relabels, so a change to either is a change to both.
664
-
665
- Neither label invokes anything: `/triage` is maintainer-run, and both labels
666
- only stop the ticket costing a read per scan. These comments are the only
667
- writes the fleet makes to a ticket it did not claim.
668
-
669
- **Exclusion is a ticket row with a premise.** `ledger.mjs row <N> "excluded ·
670
- behind-pr:#M"` or `ledger.mjs row <N> "excluded · behind-issue:#M"` — `#M` is
671
- the open PR, or the branch name until its PR exists, or the issue this ticket
672
- sequences after. No new ledger section. `shortlist.mjs` probes every premise at
673
- each refresh — MERGED or CLOSED lifts a `behind-pr`, CLOSED lifts a
674
- `behind-issue` — and a lifted ticket re-enters the shortlist in its own
675
- oldest-first slot; its row is rewritten to `impl-<N> …` when it is pulled,
676
- because `row` replaces the whole line.
677
-
678
- **Claiming.** `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
679
- the label, worktree, branch, the Recipe's Install step, the clean-tree assertion, and the
680
- isolation runner in one serial pass. The two arguments are always that literal
681
- pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
682
- branch `implementer/<N>-impl-<N>`, worktree `.worktrees/<N>-impl-<N>`. Never
683
- read them off `git branch -r` or `git worktree list`: human branches on origin
684
- (`fix/…`, `docs/…`) have another shape, and the script takes both arguments as
685
- free text, so a pair copied from one claims under that shape at exit 0.
686
-
687
- **The Install step comes from the Recipe cache — never pass or infer one.** The
688
- claim reads it through `derive-testcmd.sh . install`, and the Test entrypoint
689
- through `derive-testcmd.sh . test --at origin/main`, runs the
690
- Install step in the fresh worktree and refuses if it left any file changed: an
691
- install that rewrites the tree in a throwaway worktree corrupts it for everyone.
692
- No cache is phase 0's Recipe derivation step not having run; an invalid one is
693
- its re-derive-once rule.
694
-
695
- **Materialize the isolation envelope as a file, not a briefing.** The claim
696
- writes the runner, `agent-test`, into the fresh worktree it creates: an exec of
697
- the Recipe's Test entrypoint, through the suite-slot wrapper (see **The suite
698
- slot bound**), that exports one port triple derived from `<N>`
699
- (so collisions stay impossible), kept out of `git status` through the
700
- repository's exclude file. A repository that tracks its own `agent-test` keeps
701
- it byte-identical, with whatever isolation that repository built, and takes the
702
- suite slot bound for its own full runs itself: nothing else will. Brief members
703
- with `./agent-test` and nothing else — anyone who finds the worktree finds the
704
- runner, including grandchildren you never dispatched. Its arguments land after
705
- the Test entrypoint, so what one may name — a test file, a test name — is that
706
- entrypoint's to say, and nothing in the runner refuses one that selects no
707
- test: a run of zero tests is a failed run, not a pass. See
708
- references/isolation.md.
709
-
710
- **A reused worktree may lack the runner.** `claim-ticket.sh` writes
711
- `agent-test` only into the fresh worktree it claims, so a tree no claim
712
- built — an already-open PR's worktree you sent a rebaser/resolver into,
713
- a `git archive` snapshot, a `cp -R` subset — has no `./agent-test`
714
- unless the repository tracks its own, and a member told to run one
715
- stalls on a missing script (observed with a rebase-resolver in a
716
- prior-run worktree). There, tell the member the runner is absent and to
717
- run docker-free suites directly — the Recipe's Test entrypoint
718
- (`~/.fleet/bin/fleet-run derive-testcmd.sh <main checkout> test --at origin/main` prints
719
- it) only when it brings up no shared stack to collide on, else that
720
- repo's own stack-free command.
721
-
722
- **A reused worktree may also be on the wrong COMMIT.** `git worktree add <path>
723
- <branch>` checks out the existing LOCAL branch and never consults the remote, so
724
- a branch a previous run left behind wins over the rebased `origin/` ref that is
725
- actually the PR. Measured in a scratch repo (git 2.50.1): with the branch rebased
726
- on the remote and a stale local ref standing, `git worktree add <path> <branch>`
727
- checked out the stale commit and printed `HEAD is now at <stale-sha> <subject>` —
728
- the same subject the PR head carries, because a rebase preserves it. Neither
729
- commit was an ancestor of the other, so *behind* is the wrong model; it is a
730
- fork. Every other signal reads normal too: `git worktree list` shows the worktree
731
- present on the expected branch, and the tree is clean. `claim-ticket.sh` never
732
- touches this path — it claims only fresh tickets, and builds those from
733
- `origin/main`.
734
-
735
- **The two reuse failures are not symmetric.** A missing runner fails LOUDLY: the
736
- member stalls on a script that is not there. A stale base fails SILENTLY and
737
- produces confident wrong output — a review cut its immutable snapshot at the
738
- stale commit and a fix-applier was dispatched into it, halted only before a push
739
- that would have been a non-fast-forward.
740
-
741
- So, when you re-create a worktree for an already-open PR:
742
-
743
- - **Create it detached from the remote ref**, never from the bare branch name:
744
- `git worktree add --detach <path> origin/<branch>`. Same scratch repo, same
745
- moment: this landed on the remote's commit. It removes the mechanism rather
746
- than catching it, and leaves no local ref for the next run to inherit.
747
- - **Then verify against the branch REF, and refuse on mismatch.** Compare
748
- `git -C <path> rev-parse HEAD` against
749
- `git ls-remote origin refs/heads/<branch> | cut -f1` — the ref itself, which
750
- is what the PR's head actually is, and **never `git rev-parse
751
- origin/<branch>`**, which is the ref the worktree was just cut from and so
752
- agrees with it by construction. Unequal → dispatch nothing into that
753
- worktree, and report it naming BOTH commits, since their subjects will not
754
- tell them apart. **An empty read is neither equal nor a mismatch**: the read
755
- failed, or that head branch is not on `origin` at all (a fork PR, where the
756
- creation form above cannot work either), so report the ref as unreadable
757
- rather than the worktree as wrong — the same hole `[ -n "$pre" ]` closes on
758
- the way into `run-merge-bot.md`'s step-1 poll.
759
- - **Read `gh pr view <N> --json headRefOid -q .headRefOid` here too, and
760
- record it — it is NOT the gate.** A `headRefOid` that disagrees with the ref
761
- is the PR-object desync `run-merge-bot.md`'s step 1 says needs a controller,
762
- so it is a fact to carry into that decision, never the operand this refusal
763
- turns on.
764
-
765
- **Why the ref and not `headRefOid`: during the PR object's lag both operands go
766
- stale in the SAME direction, so that compare fails OPEN as readily as it fails
767
- closed.** The PR object spends the lag sitting on the PRE-rebase sha — cleared
768
- on re-poll attempt 24 (~2 min) in one merge pass and attempt 14 (~84s) in the next,
769
- both after `gh pr update-branch --rebase` returned `rc=0`, measured in
770
- `run-merge-bot.md`'s step 1 — and that is the very commit a clone which has not
771
- fetched since the rebase still has `origin/<branch>` pointing at. So the false
772
- REFUSAL (worktree current, PR object behind) is only half of it: cut the
773
- worktree from the stale remote-tracking ref and both sides read the superseded
774
- sha, the check reads EQUAL, and the dispatch lands on exactly the commit this
775
- paragraph exists to catch. Measured in a scratch repo (git 2.50.1): with the
776
- branch rebased onto an advanced `main`, force-pushed, and the clone not fetched
777
- since, `git worktree add --detach <path> origin/<branch>` landed on the
778
- pre-rebase `c774756` and printed its subject unchanged by the rebase, while
779
- `git ls-remote origin refs/heads/<branch>` read the true tip `62ba798` from
780
- that same unfetched clone. **Re-reading `headRefOid` on a settle window does
781
- not reach that half at all** — it fires only where the two disagree — which is
782
- why the operand changes here rather than the verdict gaining a window.
783
-
784
- **A mismatch is usually one `git fetch origin` old, so `git worktree remove
785
- --force <path>` first, then fetch and re-create once before reporting it.**
786
- `git worktree add --detach <path> origin/<branch>` resolves the LOCAL
787
- remote-tracking ref (measured above), so the ordinary cause is this clone's
788
- own staleness, and re-creating after a fetch costs seconds where the refusal
789
- costs a dispatch. **Bounded at one retry**: still unequal after the fetch →
790
- refuse and report, because the second reading is a push that landed while
791
- you worked, or a ref this clone cannot resolve, and neither gets better with
792
- more waiting.
793
-
794
- `review-core.mjs` refuses a snapshot whose head is not the branch ref's, so the
795
- review path is backstopped — except when the operand comes back
796
- empty, which skips the compare rather than refusing on it. A same-repo PR
797
- still reads `refs/heads/<branch>` first and falls back to
798
- `refs/pull/<number>/head` only when that comes back empty; a cross-repo PR (a
799
- fork) skips the branch-ref read entirely and goes straight to the pull ref,
800
- because a fork's branch NAME can collide with an unrelated branch the base
801
- repo already carries under that name — so a fork PR now gets this
802
- operand populated in the ordinary case, and the skip is rare rather than the
803
- norm for forks. Its run log names the skip: `head ref (absent): head check
804
- SKIPPED`. A worktree you hand to an agent directly is not backstopped at all.
805
- Verify here anyway. **That backstop now compares against the same ref this
806
- bullet does** — it moved its operand off `headRefOid` for the reason
807
- above — so it is a second
808
- chance to notice a stale snapshot on the one path it covers, never a reason
809
- to skip the ref compare here.
460
+ **A Pull never re-admits a ticket already relabelled**: the issue step reads the
461
+ labels fresh and exits 1 `relabelled elsewhere` once `ready-for-agent` is gone.
462
+
463
+ **The exit table** — how a Pull ends, and what follows:
464
+
465
+ | `pull.mjs` | At the Pull | Then |
466
+ |---|---|---|
467
+ | 0 `DISPATCH {…}` | decided, live, free, claimed, routed; row, brief and dispatch recorded | the `task` call (phase 2) |
468
+ | 1 `LEFT #N: taken …` | in-flight hit, an in-flight check that could not answer, or `claim-ticket.sh` exit 2 | next entry |
469
+ | 1 `LEFT #N: relabelled elsewhere` | no longer labelled `ready-for-agent` | next entry |
470
+ | 1 `LEFT #N: closed: fixed by …` | `close` answered `yes` | next entry |
471
+ | 1 `LEFT #N: relabelled <label>: …` | `decided` answered with a cause | next entry |
472
+ | 1 `LEFT #N: excluded · behind-…` | `collision` answered `behind-pr:#M` or `behind-issue:#M` | next entry |
473
+ | 1 `EMPTY` | the shortlist holds no entry to pull | run `shortlist.mjs` once and Pull again; still empty, hold the slot idle until the next refresh trigger |
474
+ | 2 | could not look, named on stderr | as the entry paragraph says |
475
+ | 3 | a usage mistake, or a token the question does not take | correct it; nothing was recorded |
476
+ | 10 `QUESTION <qid>:` | a question pending | answer it |
477
+
478
+ Relabelling by cause, exclusion rows and claiming are in references/pull.md; a
479
+ worktree re-created for an already-open PR is in references/isolation.md.
810
480
 
811
481
  ## Phase 2 — dispatch the Pull's implementer
812
482
 
@@ -830,46 +500,18 @@ auto-delivers on its own, like every other member's.
830
500
  definition's own frontmatter, whichever `fleet-implementer-<cell>`
831
501
  definition the Pull names, and a member's Resolved tier stays readable from its transcript.
832
502
 
833
- **Claim what you are about to dispatch; dispatch what you have just claimed.**
834
- Phase 1 makes the claim, serially in the main checkout — its rule is measured —
835
- and the dispatch follows it at once. A claim that runs ahead of its dispatch is
836
- a worktree, a branch and an `in-progress` label with no member behind them,
837
- released by the end-of-run sweep rather than by a member that did the work.
838
-
839
- **Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
840
- the Pull's step 7; `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
841
- implementer --member impl-<N> …` then renders its brief, and
842
- `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
843
- marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
844
- Its JSON carries `agent`, the definition that call names, and `brief.path`,
845
- the rendered brief whose content is that call's prompt — read both off that
846
- output, never recall them. Live implementers are the `impl-` tokens with no
847
- `=<outcome>` — the tick reads that count off the ledger, and nobody states
848
- it. `dispatch` refuses a member with no brief rendered for its role, naming
849
- the `render` command to run first, and refuses once the
850
- run is draining: drain stops supply. It also refuses a row whose `tier=`
851
- names no single definition — two different values, or one that is not a
852
- definition suffix — or names one with no `agents/<definition>.agent.md`,
853
- before the member is live; fix the row with `row` first.
854
-
855
- **The prompt carries only what varies.** Everything shared — the
856
- unattended-member block, the `edit`/`read` absolute-path rule, the
857
- issue re-read and re-derive backstop, commit incrementally, no `git stash`, the
858
- shared `eval` kernel, enumerate-and-declare, sizing and the PR steps —
859
- is the body of every `agents/fleet-implementer-<cell>.agent.md`, byte-identical
860
- across all of them, and each harness injects it as the
861
- member's system prompt. Never re-paste it. The prompt fills that body's
862
- placeholders — the ticket number, the worktree abs path and branch
863
- (`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/` — absolute,
864
- `<scratch>` as `scratch-root.mjs` printed it — and the
865
- distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
866
- comment or the issue body, whichever carries the brief, and its `Out of
867
- scope`, pasted verbatim from the Pull's own read. Beyond those
868
- `briefs/implementer.md` carries only its report paragraph, the
869
- no-acknowledgement line, the foreground-suite line
870
- — and a `staleness.mjs` **could not check** verdict with its
871
- reason when the Pull got one, so the member's own re-derive step knows the
872
- controller's probe could not look.
503
+ **Claim what you are about to dispatch, and dispatch it at once**: `pull.mjs`'s
504
+ claim step runs `claim-ticket.sh`, its route, row, render and dispatch steps
505
+ follow in the same command, and your `task` call follows its `DISPATCH` line.
506
+
507
+ **The dispatch is recorded before you make it**: `pull.mjs`'s row step writes the
508
+ row, its render step renders the brief and its dispatch step runs `ledger.mjs
509
+ dispatch`, whose `agent` and `brief.path` its `DISPATCH` line prints as `agent`
510
+ and `brief`.
511
+
512
+ **The prompt carries only what varies**: `pull.mjs`'s render step fills the
513
+ implementer brief's placeholders from the Pull's own read, and the agent body
514
+ carries everything shared, so never re-paste it.
873
515
 
874
516
  **The prompt pastes the Pull's own read of the ticket rather than telling the
875
517
  member to re-fetch it, and this still costs one `gh issue view` per ticket,
@@ -1022,7 +664,7 @@ is an Exploration Pull, and the router draws its cell: `k = 1 +
1022
664
  `cells` minus the policy cell, in token order. While the table's `burn_in` is
1023
665
  true every Pull draws, over every cell, the policy cell included. An
1024
666
  Exploration Pull records `tier=<cell>` in the row, and a replacement inherits the row's tier —
1025
- written at the Pull's step 7, ahead of `ledger.mjs dispatch`, which reads it
667
+ written at the Pull's row step, ahead of `ledger.mjs dispatch`, which reads it
1026
668
  and prints `fleet-implementer-<cell>` as the `agent` to dispatch; a row with
1027
669
  no `tier=` runs the policy cell. The
1028
670
  assignment rolls to the next Pull when another open ticket sequences after
@@ -1662,7 +1304,14 @@ depth** guard table applied in code. Act on each line as it reads:
1662
1304
  `task` call, or settle the token `killed`. Advice the same way, folded as
1663
1305
  `…; NO-TRANSCRIPT <member> persists — …`. Both lines read the session
1664
1306
  directory this run's phase-0 receipt names, else `--session <dir>`; with
1665
- neither the tick skips them with one stderr line.
1307
+ neither the tick skips them with one stderr line. A heartbeat state file
1308
+ that exists but cannot be used — unreadable, not JSON, not a JSON object,
1309
+ or holding a `controller` that cannot be judged — holds no first-seen
1310
+ ages, and the tick never rewrites it, so every live token reads as first
1311
+ seen that tick and neither `CHECK-LIVENESS` nor `NO-TRANSCRIPT` can fire.
1312
+ The tick says so with one stderr line, `fleet-tick: CHECK-LIVENESS and
1313
+ NO-TRANSCRIPT not checked — <file> <cause>, so first-seen ages are
1314
+ unavailable`, naming only the checks that would have run that tick.
1666
1315
 
1667
1316
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
1668
1317
  phase 2's own step, run by `tick --apply`: a mismatch it finds is the
@@ -2409,7 +2058,7 @@ substituting `<testCmd>` with nothing leaves it no gate at all.
2409
2058
  **Where `<branch>` comes from:** the PR's head branch —
2410
2059
  `gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
2411
2060
  the worktree from. Pass it as `--branch`, because
2412
- the member cannot read it off git: phase 1 creates an already-open PR's worktree
2061
+ the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
2413
2062
  with `--detach`, and there `git branch --show-current` prints nothing and exits 0
2414
2063
  (measured 2026-09-18, git 2.50.1), so `git push origin
2415
2064
  "HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
@@ -2630,7 +2279,7 @@ refuses a finisher brief rendered without it.
2630
2279
  to the fleet's worktree home, so a tree under `<scratch>` is a `kept` entry
2631
2280
  it reports and never collects. No claim built the tree you added, so it has
2632
2281
  `./agent-test` only if the repository tracks one — run that or `<testCmd>`
2633
- in it, per **A reused worktree may lack the runner** above.
2282
+ in it, per `references/isolation.md`, **A reused worktree may lack the runner**.
2634
2283
 
2635
2284
  **None of this licenses a write to the owned worktree.** Duty 1 is a read;
2636
2285
  you never restore that tree, because you never wrote to it. A controller