@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.
- package/package.json +1 -1
- package/scripts/claim-ticket.sh +1 -1
- package/scripts/fleet-event.mjs +147 -15
- package/scripts/fleet-heartbeat.mjs +2 -2
- package/scripts/fleet-tick.mjs +104 -10
- package/skills/run-team/SKILL.md +148 -515
- package/skills/run-team/references/isolation.md +104 -1
- package/skills/run-team/references/phase-0.md +1 -1
- package/skills/run-team/references/pull.md +346 -0
package/skills/run-team/SKILL.md
CHANGED
|
@@ -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 (
|
|
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
|
|
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`.
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
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.
|
|
456
|
-
|
|
457
|
-
`
|
|
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
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
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
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
`
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
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.
|
|
459
|
+
|
|
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.
|
|
643
462
|
|
|
644
|
-
**
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
`
|
|
654
|
-
`
|
|
655
|
-
|
|
656
|
-
the
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
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.
|
|
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
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
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
|
|
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
|
|
@@ -1316,44 +958,53 @@ unconfirmed. Invoking the command was the opt-in. One exception: **a judgement t
|
|
|
1316
958
|
evidence cannot settle**.
|
|
1317
959
|
|
|
1318
960
|
**Rule: record, tick, act, beat.** Every wake — a member report, a review
|
|
1319
|
-
notification, a label, a CI run reaching a terminal state, a
|
|
1320
|
-
one `fleet-
|
|
961
|
+
notification, a label, a CI run reaching a terminal state, a `CONFLICT` line, a
|
|
962
|
+
heartbeat, the maintainer's drain — is one `fleet-event.mjs` call, which makes
|
|
963
|
+
the wake's writes and ends in one `fleet-tick.mjs` invocation, and you do what
|
|
964
|
+
it prints. There are no hand-run
|
|
1321
965
|
refill or dispatch edges left. Record first, because the tick reads the run off
|
|
1322
966
|
`.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
|
|
1323
967
|
one it cannot see, and it names the same dispatch again. Every record goes
|
|
1324
|
-
through `ledger.mjs` (**Run ledger**)
|
|
1325
|
-
|
|
1326
|
-
|
|
968
|
+
through `ledger.mjs` (**Run ledger**), which `fleet-event.mjs` drives — never a
|
|
969
|
+
hand edit. What each kind writes is in the header comment of `fleet-event.mjs`.
|
|
970
|
+
|
|
971
|
+
Run each as `~/.fleet/bin/fleet-run fleet-event.mjs <kind> <args>`, from the main checkout:
|
|
1327
972
|
|
|
1328
|
-
| Wake |
|
|
973
|
+
| Wake | Command |
|
|
1329
974
|
|---|---|
|
|
1330
|
-
| Implementer report | `
|
|
1331
|
-
| Review workflow notification / `review-pr-<n>` report |
|
|
1332
|
-
|
|
|
1333
|
-
|
|
|
1334
|
-
| Finisher report
|
|
1335
|
-
|
|
|
1336
|
-
|
|
|
1337
|
-
|
|
|
1338
|
-
|
|
|
1339
|
-
|
|
|
1340
|
-
|
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
owes beyond its
|
|
975
|
+
| Implementer report | `fleet-event.mjs impl-report impl-<N>` |
|
|
976
|
+
| Review result file written (workflow notification / `review-pr-<n>` report) | `fleet-event.mjs review-result <pr> <path>` |
|
|
977
|
+
| Review launch failed | `fleet-event.mjs review-failed <pr> <launch>` |
|
|
978
|
+
| Fix-applier report | `fleet-event.mjs fix-report fix-pr-<M>` |
|
|
979
|
+
| Finisher report | `fleet-event.mjs finisher-report finisher-pr-<M>` |
|
|
980
|
+
| Merge-bot pass report | `fleet-event.mjs merge-bot-report merge-bot-<n>` |
|
|
981
|
+
| CI run terminal | `fleet-event.mjs ci <pr>` |
|
|
982
|
+
| Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
|
|
983
|
+
| `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
|
|
984
|
+
| Heartbeat | `fleet-event.mjs heartbeat` |
|
|
985
|
+
| Drain | `fleet-event.mjs drain --reason "<reason>"` |
|
|
986
|
+
|
|
987
|
+
Act on every line the call prints, the tick's last, and arm the beat. What a wake
|
|
988
|
+
owes beyond its call:
|
|
1344
989
|
|
|
1345
990
|
- **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
|
|
1346
991
|
below. A turn that ends on a drained queue is #3's stall itself: nothing
|
|
1347
992
|
external will wake you, and the level-check you are one command away from
|
|
1348
993
|
never runs. Listed first because it is the only wake with no trigger —
|
|
1349
994
|
every other row above arrives; this one is the absence of one.
|
|
1350
|
-
- **Implementer report** →
|
|
1351
|
-
settle the member, then run the tick. The PR is owed a review from here on:
|
|
995
|
+
- **Implementer report** → the PR is owed a review from here on:
|
|
1352
996
|
the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
|
|
1353
997
|
and it names the next shortlist head for the slot the implementer left. Pull
|
|
1354
998
|
nothing the tick did not name.
|
|
1355
|
-
- **
|
|
1356
|
-
|
|
999
|
+
- **Finisher reports halted** → the per-cause rule (**Resolving a finisher
|
|
1000
|
+
halt**, below).
|
|
1001
|
+
- **A finisher failed or was killed** → `ledger.mjs settle finisher-pr-<M>=failed` for a
|
|
1002
|
+
finisher that crashed or gave up, `=killed` for one that was killed; no label,
|
|
1003
|
+
and the tick prints no dispatch for it. The cockpit flags the PR
|
|
1004
|
+
`finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand
|
|
1005
|
+
(**Resolving a finisher that died**, below), then run the tick.
|
|
1006
|
+
- **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`
|
|
1007
|
+
settles `impl-<N>=bailed` and demotes by cause:
|
|
1357
1008
|
|
|
1358
1009
|
| Cause | Label |
|
|
1359
1010
|
|---|---|
|
|
@@ -1361,60 +1012,45 @@ owes beyond its row:
|
|
|
1361
1012
|
| genuine fork — options named, none ruled | `ready-for-human` |
|
|
1362
1013
|
| needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
|
|
1363
1014
|
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
`release-ticket.sh` (below — `reap.sh` declines a claim that never became a
|
|
1367
|
-
PR), then run the tick: the head it names next is a *different* ticket.
|
|
1015
|
+
The call relabels, comments the cause and releases the claim, then ticks:
|
|
1016
|
+
the head the tick names next is a *different* ticket.
|
|
1368
1017
|
`needs-triage` routes back to `/triage`, which can return it as
|
|
1369
1018
|
`ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
|
|
1370
1019
|
brief that names no *what*.
|
|
1371
1020
|
|
|
1372
|
-
|
|
1373
|
-
`
|
|
1374
|
-
scans *and* the maintainer's. It does not loop; it disappears. The same causes
|
|
1375
|
-
relabel an unclaimed ticket at the Pull (phase 1), where there is no
|
|
1376
|
-
`in-progress` to drop — the causes and labels are one table, applied at
|
|
1021
|
+
The same causes relabel an unclaimed ticket at the Pull (phase 1), where there
|
|
1022
|
+
is no `in-progress` to drop — the causes and labels are one table, applied at
|
|
1377
1023
|
whichever point the ticket fails them.
|
|
1378
1024
|
- **A review result lands** → see the result file written (by you or by the
|
|
1379
|
-
runner — **Reviewers** says which, per harness)
|
|
1380
|
-
|
|
1025
|
+
runner — **Reviewers** says which, per harness), then
|
|
1026
|
+
`fleet-event.mjs review-result <pr> <path>`: a PR with survived or unverified findings prints as
|
|
1381
1027
|
`DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
|
|
1382
1028
|
fix-applier and dispatch the **finisher** directly — or, when that head's
|
|
1383
1029
|
bound conclusion is red and not solely staleness, the red-check fixer
|
|
1384
1030
|
instead (**Then dispatch a red-check fixer**, below): no member will touch that
|
|
1385
1031
|
PR, so no push is coming and nothing will wake you. A review that failed is
|
|
1386
1032
|
not a result — **Reviewers** says who retries it and what takes over.
|
|
1387
|
-
- **Monitor: `ready-to-merge` appears** →
|
|
1033
|
+
- **Monitor: `ready-to-merge` appears** → `fleet-event.mjs label <pr>`, and
|
|
1388
1034
|
on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
|
|
1389
1035
|
Catches hand-added labels as well as a finisher's own. The bot does not wait
|
|
1390
1036
|
for that finisher's report: its rebase is server-side,
|
|
1391
1037
|
`gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
|
|
1392
1038
|
happen first.
|
|
1393
|
-
- **Merge-bot pass reports done** →
|
|
1394
|
-
|
|
1395
|
-
and leaves nothing in the repo, so the row is the only place the tick can read
|
|
1396
|
-
it from — settle `merge-bot-<n>=done`, and then run the tick: `tick --apply`
|
|
1397
|
-
reaps merged branches and worktrees with `reap.sh --apply` (below), then
|
|
1398
|
-
reclaims their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
|
|
1399
|
-
(below), once for every merge bot settled `done` — always, even when the pass
|
|
1400
|
-
merged nothing — and runs both again on the next tick after an `APPLY FAILED`
|
|
1401
|
-
line, and on every tick while this run has no controller record to remember
|
|
1402
|
-
the pass by. A label that landed at the last moment reads `DISPATCH
|
|
1039
|
+
- **Merge-bot pass reports done** → `fleet-event.mjs merge-bot-report merge-bot-<n>`. A label that
|
|
1040
|
+
landed at the last moment reads `DISPATCH
|
|
1403
1041
|
merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
|
|
1404
1042
|
on a conflict needs no record from you — the bot already appended
|
|
1405
1043
|
`conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
|
|
1406
1044
|
fix-pr PR#<pr>` (**Reviewers**).
|
|
1407
|
-
- **The run ends, or the maintainer says drain** → `
|
|
1408
|
-
(below)
|
|
1409
|
-
else in the loop fires for those claims. The marker is on disk, so the tick
|
|
1045
|
+
- **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
|
|
1046
|
+
first (below). The marker is on disk, so the tick
|
|
1410
1047
|
holds the implementer row at `HOLD (draining)` from then on — for a
|
|
1411
1048
|
replacement controller too — and keeps the review, fix-applier and merge rows
|
|
1412
1049
|
firing until the open PRs merge. The drain starts the end of the run; it does
|
|
1413
1050
|
not end it. **End of run**, in this order:
|
|
1414
|
-
1. `~/.fleet/bin/fleet-run
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
PRs**). A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
|
|
1051
|
+
1. `~/.fleet/bin/fleet-run fleet-event.mjs drain --reason "<reason>"` — runs
|
|
1052
|
+
`closeout.mjs begin --reason "<reason>"` (**Release the claims that never became
|
|
1053
|
+
PRs**), then the tick. A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
|
|
1418
1054
|
refusal is the finding, so run `worktree-audit.sh` and decide by hand.
|
|
1419
1055
|
`begin` selects a claim with no PR and a live or `bailed` implementer token
|
|
1420
1056
|
on every run, so a claim you keep leaves `begin` at exit 4 on every run:
|
|
@@ -1430,15 +1066,12 @@ owes beyond its row:
|
|
|
1430
1066
|
the ledger marks reviewed with no verdict row: append it with the verdict
|
|
1431
1067
|
you rule (**Guard: accumulate per PR**) and run `finish` again. A step it
|
|
1432
1068
|
fails is explained in references/close-out.md. Exit 0 is the run closed.
|
|
1433
|
-
- **Monitor: CI run completes** →
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
controller holding only the colour cannot later tell an edge it has already
|
|
1440
|
-
spent from one that never fired, and that is the distinction the sibling
|
|
1441
|
-
bullet below turns on. The whole key, never the conclusion alone: **a
|
|
1069
|
+
- **Monitor: CI run completes** → `fleet-event.mjs ci <pr>`, which binds the run
|
|
1070
|
+
(`ci-state.mjs --pr <N>`) and **records it as
|
|
1071
|
+
`ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
|
|
1072
|
+
ticket's ledger row, which outlives your context. The key is what the sibling
|
|
1073
|
+
bullet below turns on: it tells an edge already spent from one that never
|
|
1074
|
+
fired. The whole key, never the conclusion alone: **a
|
|
1442
1075
|
conclusion is not stable** (below), because a rerun rewrites the run in
|
|
1443
1076
|
place. The diff-validating `check` job green with no heavy job (the
|
|
1444
1077
|
diff-validating suites, not the `rebase-check` currency gate) in `failure`
|
|
@@ -1502,7 +1135,7 @@ owes beyond its row:
|
|
|
1502
1135
|
repo has no CI configured and no declaration, and stop. Absence never reads as
|
|
1503
1136
|
pass. See `review-and-fix.md` step 6.
|
|
1504
1137
|
|
|
1505
|
-
**
|
|
1138
|
+
**In one line, every wake is one `fleet-event.mjs` call, which ends in the tick.** One tick invocation, and you act on what it prints:
|
|
1506
1139
|
|
|
1507
1140
|
```
|
|
1508
1141
|
~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
|
|
@@ -1559,17 +1192,16 @@ depth** guard table applied in code. Act on each line as it reads:
|
|
|
1559
1192
|
- `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
|
|
1560
1193
|
settled `labelled` and the label is still not on: the tick dispatches no
|
|
1561
1194
|
third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
|
|
1562
|
-
flag and the comment the repair finisher's report left (
|
|
1563
|
-
|
|
1195
|
+
flag and the comment the repair finisher's report left (`fleet-event.mjs`'s
|
|
1196
|
+
`finisher-report` entry).
|
|
1564
1197
|
- `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
|
|
1565
1198
|
tracks it, no conflict hold stands on it, no fix-applier, finisher or
|
|
1566
1199
|
implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
|
|
1567
1200
|
is live: a queued PR is the bot's while one runs, and its own fallback records
|
|
1568
|
-
the hold. Record it with `
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
tokens. Then run the tick: the hold reads as `DISPATCH fix-pr
|
|
1201
|
+
the hold. Record it with `fleet-event.mjs conflict <M>`, not with the `ledger.mjs
|
|
1202
|
+
row` form the row's detail prints: `row` replaces the whole line. The call
|
|
1203
|
+
refuses a PR whose row already carries a hold no fix-applier has answered.
|
|
1204
|
+
The tick then reads the hold as `DISPATCH fix-pr
|
|
1573
1205
|
PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
|
|
1574
1206
|
hold**), and that row obeys every hold. A review in flight does not stop the
|
|
1575
1207
|
line: `fix-due` waits for the review to return. It prints under a
|
|
@@ -1709,8 +1341,8 @@ exactly the way that gate does:
|
|
|
1709
1341
|
|
|
1710
1342
|
It blocks, then prints one line. Which line it is, is the whole protocol:
|
|
1711
1343
|
|
|
1712
|
-
- `… interval elapsed (quiet=<n>) → run fleet-
|
|
1713
|
-
|
|
1344
|
+
- `… interval elapsed (quiet=<n>) → run fleet-event.mjs heartbeat` — the level-check
|
|
1345
|
+
is due. Run that command and act on what the tick it ends in prints.
|
|
1714
1346
|
Then arm the beat again.
|
|
1715
1347
|
- `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
|
|
1716
1348
|
command blocks for a whole interval (omp backgrounds one at 60s, which is
|
|
@@ -1729,7 +1361,7 @@ not a reason to end the run; they are the state a newly triaged ticket arrives
|
|
|
1729
1361
|
into. The run ends when you drain it, when the budget goes, or when this
|
|
1730
1362
|
context does — not because there was briefly nothing to do.
|
|
1731
1363
|
|
|
1732
|
-
**`--fold-unchanged` belongs to the heartbeat alone
|
|
1364
|
+
**`--fold-unchanged` belongs to the heartbeat alone** — `fleet-event.mjs heartbeat` passes it, no other kind does.
|
|
1733
1365
|
It prints one line instead of the rows when a tick asks for nothing AND says
|
|
1734
1366
|
exactly what the last one said, which is what makes an unattended night
|
|
1735
1367
|
affordable; a tick on any other wake is read by a controller that just acted and
|
|
@@ -1921,7 +1553,7 @@ while :; do # one tick
|
|
|
1921
1553
|
echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
|
|
1922
1554
|
keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
|
|
1923
1555
|
esac
|
|
1924
|
-
: # your normal handling of $st for this PR
|
|
1556
|
+
: # your normal handling of $st for this PR; a run at a terminal state is the CI wake: fleet-event.mjs ci "$pr"
|
|
1925
1557
|
done
|
|
1926
1558
|
fi
|
|
1927
1559
|
fi
|
|
@@ -2180,8 +1812,9 @@ No replay exists for a review that ran in a runner's own kernel — `resume` is
|
|
|
2180
1812
|
`refuted` comes back deliberately as well — a refutation is itself a claim, and
|
|
2181
1813
|
one has been reversed on new evidence. The fix-applier may reverse one; it
|
|
2182
1814
|
records each reversal as a `refuted` entry in its disposition record, the
|
|
2183
|
-
evidence in `reason`, and you copy those entries to the ledger's `ruled` line
|
|
2184
|
-
|
|
1815
|
+
evidence in `reason`, and you copy those entries to the ledger's `ruled` line by
|
|
1816
|
+
running `fleet-event.mjs fix-report`, whose `settle --from-report` records each
|
|
1817
|
+
refutation the report defers.
|
|
2185
1818
|
|
|
2186
1819
|
**`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
|
|
2187
1820
|
specialist that dies contributes zero findings while its key stays in
|
|
@@ -2418,7 +2051,7 @@ substituting `<testCmd>` with nothing leaves it no gate at all.
|
|
|
2418
2051
|
**Where `<branch>` comes from:** the PR's head branch —
|
|
2419
2052
|
`gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
|
|
2420
2053
|
the worktree from. Pass it as `--branch`, because
|
|
2421
|
-
the member cannot read it off git:
|
|
2054
|
+
the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
|
|
2422
2055
|
with `--detach`, and there `git branch --show-current` prints nothing and exits 0
|
|
2423
2056
|
(measured 2026-09-18, git 2.50.1), so `git push origin
|
|
2424
2057
|
"HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
|
|
@@ -2487,8 +2120,8 @@ gated like survivors, and the tick prints `DISPATCH fix-pr PR#<M>` for it: that
|
|
|
2487
2120
|
fix-applier's `no-op` and its `ok` verdict are what open the finisher. The
|
|
2488
2121
|
refusal names its cause. `dispositions
|
|
2489
2122
|
unchecked` — no verdict answers that review: run `dispositions-check.mjs` for
|
|
2490
|
-
the fix-applier that answered the review, as
|
|
2491
|
-
states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
|
|
2123
|
+
the fix-applier that answered the review, as `fleet-event.mjs`'s `fix-report`
|
|
2124
|
+
entry states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
|
|
2492
2125
|
no rule broke, but the check could not read where a deferral was filed, `gh`
|
|
2493
2126
|
unreachable or an issue unreadable: run the check again for that fix-applier
|
|
2494
2127
|
once `gh` answers (an issue that does not exist is unreadable too, and no re-run
|
|
@@ -2639,7 +2272,7 @@ refuses a finisher brief rendered without it.
|
|
|
2639
2272
|
to the fleet's worktree home, so a tree under `<scratch>` is a `kept` entry
|
|
2640
2273
|
it reports and never collects. No claim built the tree you added, so it has
|
|
2641
2274
|
`./agent-test` only if the repository tracks one — run that or `<testCmd>`
|
|
2642
|
-
in it, per **A reused worktree may lack the runner
|
|
2275
|
+
in it, per `references/isolation.md`, **A reused worktree may lack the runner**.
|
|
2643
2276
|
|
|
2644
2277
|
**None of this licenses a write to the owned worktree.** Duty 1 is a read;
|
|
2645
2278
|
you never restore that tree, because you never wrote to it. A controller
|