@feigi/fleet-ctl 3.57.0 → 3.58.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.
- package/agents/fleet-fix-applier.agent.md +1 -1
- package/package.json +1 -1
- package/scripts/dispatch-prompt.mjs +1 -1
- package/scripts/ledger-grammar.mjs +44 -7
- package/scripts/ledger.mjs +85 -14
- package/skills/run-team/SKILL.md +112 -492
- package/skills/run-team/briefs/fix-applier.md +14 -0
- package/skills/run-team/references/close-out.md +95 -0
- package/skills/run-team/references/phase-0.md +397 -0
|
@@ -25,6 +25,13 @@ it. Do NOT create another worktree. There is no review file: the PR sits on a
|
|
|
25
25
|
conflict hold and you are here to clear it — do not review, do not dispatch
|
|
26
26
|
specialists.
|
|
27
27
|
|
|
28
|
+
## kind: red-check
|
|
29
|
+
You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
|
|
30
|
+
push destination below, given to you because a detached worktree cannot supply
|
|
31
|
+
it. Do NOT create another worktree. There is no review file: the PR's `check`
|
|
32
|
+
job is red on its current head and you are here to fix it — do not review, do
|
|
33
|
+
not dispatch specialists.
|
|
34
|
+
|
|
28
35
|
## kind: review, dispositions-retry
|
|
29
36
|
Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
|
|
30
37
|
and 5 only**: split apply-now/defer, commit, push, file every deferral as its
|
|
@@ -60,6 +67,13 @@ Bring `<branch>` current with `origin/main`, resolving every conflict by the
|
|
|
60
67
|
Run `<testCmd>` from the worktree before you push, then push with
|
|
61
68
|
`git push origin HEAD:<branch>`. Report the new head, or that no conflict was
|
|
62
69
|
left.
|
|
70
|
+
## kind: red-check
|
|
71
|
+
Read the failing job's log and fix the cause. Run `<testCmd>` from the
|
|
72
|
+
worktree before you push, then push with `git push origin HEAD:<branch>`.
|
|
73
|
+
Report the new head and **stop**: do not watch, poll or wait for CI — the
|
|
74
|
+
controller owns the next run on the pushed head. A red that is not yours to
|
|
75
|
+
fix — a flake that passes on rerun, or staleness — gets nothing pushed: report
|
|
76
|
+
that instead.
|
|
63
77
|
## kind: dispositions-retry
|
|
64
78
|
|
|
65
79
|
This is the one automatic retry of a dispositions mismatch. The mismatched
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Close-out: what each metrics step does and why
|
|
2
|
+
|
|
3
|
+
`closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh and the commit of the metrics files, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
|
|
4
|
+
|
|
5
|
+
## Scrape the member facts and check the tier rows
|
|
6
|
+
|
|
7
|
+
**Then record the run's member facts — do not author them.** Scrape EVERY session
|
|
8
|
+
directory for this cwd, not one:
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
PROJECT_DIR="$(node -e 'import("./scripts/member-record.mjs").then(m => console.log(m.encodeProjectDir(process.cwd())))')"
|
|
12
|
+
for d in "$HOME/.omp/agent/sessions/$PROJECT_DIR"/*/; do
|
|
13
|
+
node scripts/member-outcomes.mjs "$d"
|
|
14
|
+
done
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`encodeProjectDir` (defined in `scripts/member-record.mjs`) encodes the cwd
|
|
18
|
+
exactly as omp names its session directories — see its comment for the rule — and hand-guessing that path is why
|
|
19
|
+
the fleet's own panel once rendered nothing here. The trailing `/` on the glob matters:
|
|
20
|
+
the same encoded-cwd directory also holds this cwd's own top-level session
|
|
21
|
+
transcripts as loose FILES sibling to the per-session directories, and a
|
|
22
|
+
glob without it would try to scrape one of those as if it were a session.
|
|
23
|
+
|
|
24
|
+
**Do not narrow this to "this run's session" with `findSubagentsDir`.** That helper
|
|
25
|
+
answers a different question — the session with the NEWEST transcript for this cwd,
|
|
26
|
+
which is not the same as the one you are in. Any other session sharing this cwd —
|
|
27
|
+
a second terminal, a second controller run — can hold a newer transcript than
|
|
28
|
+
yours at the moment you reach this step, and a second session dispatching
|
|
29
|
+
anything while you reach it wins the tie: the run then re-scrapes a stranger's
|
|
30
|
+
members, prints a plausible row count and exits 0 while its own facts are
|
|
31
|
+
never recorded. Looping every session dir costs a few seconds, cannot pick
|
|
32
|
+
wrong, and is idempotent by construction.
|
|
33
|
+
|
|
34
|
+
The scraper takes the session directory itself and refuses a path it cannot
|
|
35
|
+
read — a missing, unreadable or non-directory path all exit 2 — so a wrong
|
|
36
|
+
path fails loudly instead of writing nothing and exiting 0. It reports the
|
|
37
|
+
run's own YIELD, `scraped N of M members (D dropped)`, alongside the file's
|
|
38
|
+
total: read the yield, because the total is the whole corpus and looks
|
|
39
|
+
healthy even when every member of this session dropped.
|
|
40
|
+
|
|
41
|
+
It derives every row from the member transcripts omp already wrote — both the
|
|
42
|
+
flat ones and a member's own nested fan-out one level down — so a
|
|
43
|
+
second run over the same session changes nothing and a re-run after a member is
|
|
44
|
+
re-dispatched picks the new transcript up. **Never hand-edit
|
|
45
|
+
`docs/metrics/member-outcomes.tsv`** — it is regenerated wholesale whenever the
|
|
46
|
+
role classifier changes, and a hand-entered value would not survive that. The
|
|
47
|
+
verdict for a PR goes to `tier-outcomes.tsv` through `tier-outcomes.mjs
|
|
48
|
+
append`, as above. Once both files hold this run's rows, and before either is
|
|
49
|
+
committed, run `~/.fleet/bin/fleet-run tier-outcomes.mjs check --live`. Exit 1
|
|
50
|
+
names each row whose `tier` disagrees with the one implementer the member facts
|
|
51
|
+
say ran for its ticket: correct that row's `tier` to the short name it prints,
|
|
52
|
+
or blank it and say why in `note`. Exit 1 also names the PRs of the case where
|
|
53
|
+
the latest `run_date`'s filled rows have no implementer row in the member file
|
|
54
|
+
and none could be compared, so nothing from that run was checked: append the
|
|
55
|
+
run's member rows if they are missing, or blank each named row's `tier` and say
|
|
56
|
+
why in `note`.
|
|
57
|
+
Each WARNING names a PR this run's ledger marks `reviewed=` that has no row yet
|
|
58
|
+
— append it before committing if it is an implementer PR.
|
|
59
|
+
|
|
60
|
+
## Drain the pending ticket-features rows and refresh the cost guard
|
|
61
|
+
|
|
62
|
+
**Drain the pending ticket-features rows and refresh the cost guard, after
|
|
63
|
+
the member-outcomes scrape and every `tier-outcomes.mjs append`, before the
|
|
64
|
+
metrics files are committed.** `~/.fleet/bin/fleet-run metrics-refresh.mjs`
|
|
65
|
+
moves `.fleet/ticket-features.pending.tsv` — the row the router script
|
|
66
|
+
appended for each Pull at dispatch — into `docs/metrics/ticket-features.tsv`,
|
|
67
|
+
deduped on `session`+`agent`, so this run's own rows are in the file that gets
|
|
68
|
+
committed; that file is a run artifact too and is committed with the other
|
|
69
|
+
two. It then runs `pr-cost.mjs --guard`, which rewrites
|
|
70
|
+
`.fleet/cost-guard.json` from all three files. Exit 0: both ran. The guard's
|
|
71
|
+
own exit 3 (a cell tripped) and 4 (no verdict yet, baseline too thin) are
|
|
72
|
+
verdicts the router and `fleet-tick.mjs` read, never failures; the script
|
|
73
|
+
absorbs them. Exit 1 names the duty that failed on stderr and the duty after it
|
|
74
|
+
did not run; exit 2 is a usage error. At close-out a failure fails the
|
|
75
|
+
`metrics` step of `closeout.mjs finish`, so `commit-and-pr` stays pending: fix
|
|
76
|
+
the cause and run `finish` again — the pending file stays in `.fleet/` and the
|
|
77
|
+
next run's phase-0 pass drains it — and never commit the metrics files with a
|
|
78
|
+
drain that failed claiming the corpus is complete.
|
|
79
|
+
|
|
80
|
+
## Commit the metrics files and open a PR
|
|
81
|
+
|
|
82
|
+
The metrics files are the run's own artifacts and none commits itself. Carry
|
|
83
|
+
them to main the same way the run carries any other controller-authored change;
|
|
84
|
+
leaving a regenerated 5,000-row corpus uncommitted in the checkout is how it gets
|
|
85
|
+
discarded by the next `git checkout` with nothing to show it ever ran.
|
|
86
|
+
|
|
87
|
+
**Commit the metrics files and open a PR — at end of run.** The branch name is
|
|
88
|
+
the repository's choice. Make the commit on a branch in the main checkout,
|
|
89
|
+
switch back to `main` before the next tick, and never `--record` while on that
|
|
90
|
+
branch; the round trip reads clean. A PR still open when the run ends is one phase 0's
|
|
91
|
+
fold-in queues for review next run, however it is named, so the files reach
|
|
92
|
+
`main` through the same review as ticket work rather than being lost. Stranding
|
|
93
|
+
a data row loses it: `member-outcomes.tsv` is regenerated from harness
|
|
94
|
+
transcripts the fleet does not own, so re-running the scrape later is worth
|
|
95
|
+
only what the harness still holds.
|
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
# Phase 0: what each step does and why
|
|
2
|
+
|
|
3
|
+
`phase0.mjs` runs the start sequence and writes the receipt `.fleet/phase0.json`; SKILL.md's phase 0 step 0 says how to drive it and what to do about each `NEED` line. This file is what each step means, in the order the script runs them, for the controller to read when a step refuses or a line asks for more than SKILL.md says. One heading per step.
|
|
4
|
+
|
|
5
|
+
## Fast-forward the checkout
|
|
6
|
+
|
|
7
|
+
**Fast-forward the checkout before you trust these rules — you are reading
|
|
8
|
+
them from it.** First, `git symbolic-ref -q HEAD` must print
|
|
9
|
+
`refs/heads/main`; anything else, stop and tell the maintainer — a checkout
|
|
10
|
+
left on a branch whose PR has merged would fast-forward that branch, and the
|
|
11
|
+
baseline below would record it as the run's ref. Then
|
|
12
|
+
`git fetch origin && git rev-list --count main..origin/main`;
|
|
13
|
+
non-zero means the SKILL.md you are executing is superseded, so
|
|
14
|
+
`git merge --ff-only origin/main` and re-read what changed under
|
|
15
|
+
`commands/`, `scripts/` and `skills/`. The usual cause is the PREVIOUS run's own close-out PR: it
|
|
16
|
+
lands the rules THIS run needs and nothing pulls them. Measured twice — 57
|
|
17
|
+
commits stale in one run, 20 in another, the second shipping every dispatch
|
|
18
|
+
prompt without two rules that had merged the day before. Silent by
|
|
19
|
+
construction: stale text reads as authoritative.
|
|
20
|
+
|
|
21
|
+
## Pin the instruments
|
|
22
|
+
|
|
23
|
+
**Pin the instruments, after that fast-forward and before anything reads
|
|
24
|
+
them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
|
|
25
|
+
records what the scripts and runbooks in this repo say right now, which is
|
|
26
|
+
what every later gate compares against; SKILL.md's **Re-check before you act
|
|
27
|
+
on any instrument reading** says what its exit codes mean. Pinning before that fast-forward would instead pin the
|
|
28
|
+
superseded text and certify it for the rest of the run.
|
|
29
|
+
**When this workspace does not track `plugin/…`** — fleets run here on an
|
|
30
|
+
installed plugin rather than a vendored tree — the bare pin refuses on an
|
|
31
|
+
empty instrument set, because this checkout holds no instruments to certify.
|
|
32
|
+
Name the plugin checkout to the pin instead:
|
|
33
|
+
`~/.fleet/bin/fleet-run instruments.sh --pin --audit <plugin-checkout>`.
|
|
34
|
+
The baseline records the audited tree beside the digest, and every later
|
|
35
|
+
check — yours, a finisher's, the merge gate's own leg — follows that
|
|
36
|
+
recorded root without being told twice. Refusing the bare pin and naming
|
|
37
|
+
the tree once is the whole cross-workspace contract; never dispatch a
|
|
38
|
+
member into a run whose phase-0 pin refused.
|
|
39
|
+
|
|
40
|
+
## Record the main-checkout baseline
|
|
41
|
+
|
|
42
|
+
**Record the main-checkout baseline in the same step, right after the
|
|
43
|
+
pin.** `~/.fleet/bin/fleet-run main-checkout.mjs --record` writes
|
|
44
|
+
`.fleet/main-checkout.sha`: the main checkout's `git status --porcelain
|
|
45
|
+
-uall` entries plus a content hash of every path they name, and its HEAD —
|
|
46
|
+
symbolic ref and commit. Your own
|
|
47
|
+
uncommitted work is fine — it is in the baseline and holds nothing. From
|
|
48
|
+
then on every `fleet-tick.mjs` compares the main checkout against it and
|
|
49
|
+
holds dispatch on any change: the backstop for the stray member
|
|
50
|
+
writes `member-write-guard` cannot see — an `eval` cell, a `bash` that
|
|
51
|
+
`cd`s or `git -C`s into this checkout. `.fleet/`, `.worktrees/` and
|
|
52
|
+
`.agent-brain/` are gitignored and never trip it. Nor does this run's own
|
|
53
|
+
bookkeeping: `docs/metrics/tier-outcomes.tsv`,
|
|
54
|
+
`docs/metrics/member-outcomes.tsv` and `docs/metrics/ticket-features.tsv`,
|
|
55
|
+
which you write mid-run, are left out by name — anything else under
|
|
56
|
+
`docs/metrics/` still trips it. **The same
|
|
57
|
+
command is the clear, and it overwrites; it never compares.** On `MAIN-CHECKOUT-DIRTY`
|
|
58
|
+
the maintainer resolves the stray paths FIRST — inspect, keep or remove
|
|
59
|
+
them — and only then re-runs `--record`; re-recording over unresolved paths
|
|
60
|
+
certifies them. **Never re-record over `MAIN-CHECKOUT-UNKNOWN`**: that
|
|
61
|
+
walks the run from "could not look" to "certified clean" in one step, so
|
|
62
|
+
`--record` itself refuses over a baseline it cannot read, over one a newer
|
|
63
|
+
plugin wrote, and on any git read that fails. The exceptions are an
|
|
64
|
+
older-version baseline and a baseline whose commit is missing from the
|
|
65
|
+
repository; Phase 3's tick lines say how each is cleared.
|
|
66
|
+
`main-checkout.mjs --check` prints the same answer
|
|
67
|
+
without a tick.
|
|
68
|
+
|
|
69
|
+
## Run the pre-flight
|
|
70
|
+
|
|
71
|
+
**Run the pre-flight, once the pin and the baseline are recorded.**
|
|
72
|
+
`~/.fleet/bin/fleet-run preflight.mjs` checks what this machine and this
|
|
73
|
+
repository must give the fleet — the binaries, `gh` auth, `origin/main`,
|
|
74
|
+
`.worktrees/` and `.fleet/` ignored, the three labels, merge commits on, a
|
|
75
|
+
ruleset, the Resolver — and prints one `ok`, `WARN` or `FAIL` line per
|
|
76
|
+
check, each naming its check. **Exit 1 stops the run:** no shortlist, no
|
|
77
|
+
dispatch. Report every `FAIL` line to the maintainer by its check's name;
|
|
78
|
+
the run starts again once they are fixed. Exit 2 means it could not run at
|
|
79
|
+
all, or every check passed and the marker could not be written, and stops
|
|
80
|
+
the run the same way. `WARN ci-workflow` stops nothing:
|
|
81
|
+
a repo with no workflow named CI still runs, its workflow named per call
|
|
82
|
+
with `--workflow` or declared absent with `--declare-no-ci`. A pass writes
|
|
83
|
+
`.fleet/preflight.json`, keyed to a hash of the check set, and every later
|
|
84
|
+
run prints `PREFLIGHT SKIPPED` without a single `gh` call until a check is
|
|
85
|
+
added or changed.
|
|
86
|
+
|
|
87
|
+
## Check the merge gate against its spec
|
|
88
|
+
|
|
89
|
+
**Check the merge gate against its spec, once the fast-forward has put the
|
|
90
|
+
ratified spec in front of you.** Where the workspace checks a ruleset spec
|
|
91
|
+
in, `.github/scripts/apply-ruleset.sh --check` compares it to the live gate
|
|
92
|
+
without writing anything (no spec checked in → nothing to run, skip it).
|
|
93
|
+
Three statuses and they are not interchangeable: **0** the gate is what the
|
|
94
|
+
tree says it is; **3** it is not — including the gate having been deleted
|
|
95
|
+
or renamed — and the diff it prints says how; **2** the question could not
|
|
96
|
+
be answered at all: no spec, no `gh`, a listing or read that failed
|
|
97
|
+
outright, or a read that succeeded but withheld `bypass_actors` because
|
|
98
|
+
the session lacks repository admin.
|
|
99
|
+
|
|
100
|
+
**3 does not stop the run and is not yours to fix** — reconciling is a
|
|
101
|
+
write to the gate protecting this repo, so it needs the maintainer.
|
|
102
|
+
Surface the diff and carry on. What it changes is what you may then claim:
|
|
103
|
+
every statement this run makes about which checks must pass before a merge
|
|
104
|
+
is sourced from the checked-in spec and is true of the live gate only
|
|
105
|
+
while this check is green, so a 3 means saying "the gate requires X"
|
|
106
|
+
without naming the drift is a false claim, and a 2 means you never learned
|
|
107
|
+
either way. Measured 2026-09-23: four contexts the spec required were
|
|
108
|
+
enforced by nothing live, and the gap sat
|
|
109
|
+
there unnoticed because the only thing that ever read the live gate was a
|
|
110
|
+
person choosing to.
|
|
111
|
+
|
|
112
|
+
## Drain the pending ticket-features rows and refresh the cost guard
|
|
113
|
+
|
|
114
|
+
**Drain the pending ticket-features rows and refresh the cost guard, after
|
|
115
|
+
the fast-forward and before the first Pull is routed.**
|
|
116
|
+
`~/.fleet/bin/fleet-run metrics-refresh.mjs` moves
|
|
117
|
+
`.fleet/ticket-features.pending.tsv` into `docs/metrics/ticket-features.tsv`,
|
|
118
|
+
deduped on `session`+`agent` — this recovers the rows of a run that crashed
|
|
119
|
+
before its close-out — and then runs `pr-cost.mjs --guard`, rewriting
|
|
120
|
+
`.fleet/cost-guard.json`, which the router reads and fails closed without
|
|
121
|
+
(no file: the default cell only). The guard has to be fresh before the
|
|
122
|
+
first Pull is routed, so the verdict reflects any rows just recovered. Exit
|
|
123
|
+
0: both ran. The guard's own exit 3 (a cell tripped) and 4 (no verdict yet)
|
|
124
|
+
are verdicts the router and `fleet-tick.mjs` read, never failures; the
|
|
125
|
+
script absorbs them. A workspace that lacks one of the three metrics TSVs
|
|
126
|
+
has no corpus to guard yet — its first run: the script prints a line naming
|
|
127
|
+
the missing file, skips the guard and exits 0. Exit 1 or 2 stops the run
|
|
128
|
+
before its first Pull: report the line the script printed on stderr, fix
|
|
129
|
+
the cause and run it again — each duty is safe to repeat.
|
|
130
|
+
|
|
131
|
+
## Launch the cockpit
|
|
132
|
+
|
|
133
|
+
**Launch the cockpit.** On every phase-0 pass, not just the first:
|
|
134
|
+
`node ~/.fleet/bin/fleet-run board.mjs serve --open &` in the
|
|
135
|
+
background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
|
|
136
|
+
feed or update it, and it survives your own compaction. The launch is
|
|
137
|
+
idempotent per workspace when the running cockpit answers the identity
|
|
138
|
+
handshake: an already-served workspace's launch finds the running server
|
|
139
|
+
over HTTP, prints its URL, and exits 0 without starting a second one —
|
|
140
|
+
nothing to skip. It opens nothing either: `--open` opens a tab
|
|
141
|
+
only from the launch that binds a port and starts the server, so a
|
|
142
|
+
re-shortlist leaves the board tab you already have alone. A second fleet
|
|
143
|
+
on another workspace collides with none of that: its own launch derives
|
|
144
|
+
that workspace's own port and binds it when free, or scans to the next
|
|
145
|
+
free port in its range when the derived one is already held by something
|
|
146
|
+
else — either way it gets its own board, just not always on the port its
|
|
147
|
+
hash predicts.
|
|
148
|
+
|
|
149
|
+
The spend panel reads this workspace's own `~/.omp/agent/sessions` tree,
|
|
150
|
+
and is pinned to whichever session first writes a transcript on this
|
|
151
|
+
cockpit's own watch: it will not follow a workspace that
|
|
152
|
+
already had another session's transcripts sitting there at launch. If the
|
|
153
|
+
panel is reading someone else's numbers, relaunch with `--spend-dir <path>`
|
|
154
|
+
naming this run's own session directory to override the heuristic outright —
|
|
155
|
+
`~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>` (the directory, never
|
|
156
|
+
the `.jsonl` file of the same name beside it).
|
|
157
|
+
|
|
158
|
+
## Rotate the ledger
|
|
159
|
+
|
|
160
|
+
**Rotate the ledger before the fold-in below and before shortlisting —
|
|
161
|
+
every run, whatever way the previous one ended.** One ledger per run:
|
|
162
|
+
`~/.fleet/bin/fleet-run ledger.mjs rotate` moves the previous run's
|
|
163
|
+
`.fleet/ledger.md` byte-for-byte to `.fleet/ledger.<UTC
|
|
164
|
+
YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind. What it carries forward
|
|
165
|
+
turns on the verdict it reaches below. After `dead` or `none` nothing is
|
|
166
|
+
carried — no row, exclusion, `## Filed` or `## Ruled` entry — so this
|
|
167
|
+
run's first write starts the empty skeleton, and an unchecked `impl-` row
|
|
168
|
+
a prior run left behind can no longer hold this run's tick: a dead
|
|
169
|
+
controller took its in-process members with it. After `ancestor` — this
|
|
170
|
+
session's own earlier run, whose members run inside the same omp process
|
|
171
|
+
and may still be live — it writes a new ledger holding every row of a
|
|
172
|
+
stream (one PR's rows) in which a row carries an unsettled member token
|
|
173
|
+
or an open `review=` launch, whole and with every other token on it, plus
|
|
174
|
+
every unsettled `## Dispatched` entry and the settled entry of each
|
|
175
|
+
member a carried row names; exclusions, `## Filed`, `## Ruled` and the
|
|
176
|
+
drain marker are never carried. Every other settled name — in
|
|
177
|
+
`## Dispatched` or on any row, and including a name whose outcome is
|
|
178
|
+
outside its family's vocabulary, whose line is skipped below — and every
|
|
179
|
+
reviewer runner a row launched goes into the new ledger's `## Retired` as
|
|
180
|
+
a bare name, with whatever the archive's own `## Retired` held: omp answers a second `task` under a name
|
|
181
|
+
this process has used with `<name>-2` while `hub send <name>` keeps
|
|
182
|
+
reaching the first, so a settled name stays taken for the session, not
|
|
183
|
+
the run. `dispatch` refuses a retired name and names the replacement — one
|
|
184
|
+
retry letter past the highest the session has used on that number,
|
|
185
|
+
`impl-42-b` for a ticket this session's earlier run worked as `impl-42` —
|
|
186
|
+
`review` refuses a retired runner name and names the next free reviewer
|
|
187
|
+
name, and `dispatch merge-bot` numbers past retired bots. The tick never
|
|
188
|
+
reads `## Retired`: a ticket an earlier run worked is not claimed by it
|
|
189
|
+
and can be shortlisted again.
|
|
190
|
+
A line it cannot parse is skipped with a warning naming it, and the
|
|
191
|
+
rotation still succeeds; a member name on a skipped line that carries an
|
|
192
|
+
outcome is retired all the same, and a bare member token on a skipped row
|
|
193
|
+
retires nothing. It prints `{rotated, archive, carried: {rows,
|
|
194
|
+
dispatched}, retired, skipped}`. The carried tokens keep the tick from
|
|
195
|
+
dispatching onto those members' work, keep their names taken, and give
|
|
196
|
+
their late results a token to settle; the stranded-claim step below
|
|
197
|
+
reconciles them.
|
|
198
|
+
What an unclean end left in
|
|
199
|
+
flight comes back through the ordinary per-run path: open PRs through the
|
|
200
|
+
fold-in below, `behind-pr:`/`behind-issue:` exclusions through phase 1's
|
|
201
|
+
collision and sequence checks, and a claim a dead run left without a PR
|
|
202
|
+
through the stranded-claim step below — resumed by a new member under a
|
|
203
|
+
new name when its worktree is in this checkout, reported to the
|
|
204
|
+
maintainer otherwise. An exclusion that expires with the run that wrote
|
|
205
|
+
it (`deferred-to-session-end` and its like) must be restated if it still
|
|
206
|
+
holds. **The guard is the
|
|
207
|
+
controller record**, `controller` in `.fleet/heartbeat.json`: the omp
|
|
208
|
+
process the previous run's rotation found above itself, and that
|
|
209
|
+
process's start time. Rotate judges it once, before anything moves. A
|
|
210
|
+
recorded controller that is still alive, still the same process (its
|
|
211
|
+
start time matches), and not an ancestor of this run refuses — exit 2,
|
|
212
|
+
nothing moved — **whatever its heartbeat mark says**, because a
|
|
213
|
+
controller can stop beating and keep dispatching. A dead one, a pid
|
|
214
|
+
reused by another process, or this session's own earlier run lets it
|
|
215
|
+
rotate. With no record the heartbeat mark decides, as the only guard
|
|
216
|
+
there is: still beating or acting — a beat inside its window, or with no
|
|
217
|
+
beat at all a tick or ledger write inside its window — refuses, naming
|
|
218
|
+
the latest beat, tick or ledger write and when it would count as stalled;
|
|
219
|
+
a stalled mark, a recorded `--stop`, or no mark at all lets it rotate —
|
|
220
|
+
and that fallback proves "not beating", never "dead", and
|
|
221
|
+
guards a ledger only: with none to move the mark is not consulted. With no
|
|
222
|
+
ledger the record is still judged, so a live recorded controller refuses
|
|
223
|
+
even then. It also refuses, nothing moved, when the stamped archive name
|
|
224
|
+
already exists, when the process table cannot be read, or when
|
|
225
|
+
`.fleet/heartbeat.json` exists but cannot be used — unreadable, not JSON,
|
|
226
|
+
not a JSON object, or holding a `controller` that cannot be judged — a
|
|
227
|
+
record nobody could judge is never taken for no record. On that refusal
|
|
228
|
+
phase 0 stops and the refusal goes to the maintainer verbatim: the
|
|
229
|
+
controller never edits or removes `.fleet/heartbeat.json`, because
|
|
230
|
+
removing it inside a live omp session makes this rotate judge `none` and
|
|
231
|
+
forfeits the carry — the live members and the retired names — so this
|
|
232
|
+
run could dispatch onto their work and reuse their names. Every writer
|
|
233
|
+
(`fleet-tick.mjs`, `fleet-heartbeat.mjs`, the ledger's write subcommands)
|
|
234
|
+
leaves such a file as it is. Its last act, ledger or none, is
|
|
235
|
+
to replace the record with this run's own — the nearest `omp` process
|
|
236
|
+
above it, its start time, as `prior` the verdict it reached on the
|
|
237
|
+
record it found (`dead`, `ancestor` or `none`), and as `at` when it wrote
|
|
238
|
+
it — or to remove the key when
|
|
239
|
+
no `omp` process is above it. The same write stamps `acted`, the time of
|
|
240
|
+
this run's latest ledger write, which every write subcommand stamps from
|
|
241
|
+
then on. That write can fail, and then exit 2 follows
|
|
242
|
+
a move: `rotated <file> -> <archive>` on stderr, then the refusal that the
|
|
243
|
+
record could not be written. Run the rotation before this run's own first
|
|
244
|
+
tick, beat or ledger write, each of which writes a mark the fallback reads. Older
|
|
245
|
+
archives, hand-named ones included, are left alone.
|
|
246
|
+
|
|
247
|
+
`ledger.mjs rotate` archives the run's two receipts with the ledger, under the ledger archive's own stamp: `.fleet/phase0.<UTC stamp>.json` and `.fleet/closeout.<UTC stamp>.json` beside `.fleet/ledger.<UTC stamp>.md`.
|
|
248
|
+
|
|
249
|
+
## Reclaim scratch
|
|
250
|
+
|
|
251
|
+
**Reclaim scratch straight after the rotation — every run.**
|
|
252
|
+
`~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch>
|
|
253
|
+
--after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
|
|
254
|
+
so a run that merges nothing still reclaims the previous run's leftovers
|
|
255
|
+
(**Reclaim scratch after each merge pass** says what it removes).
|
|
256
|
+
`--after-rotate` goes on this call always and on no other: rotate leaves
|
|
257
|
+
no ledger behind when it carried nothing, and the flag reads that absence
|
|
258
|
+
as "no live token" — rotate's own verdict — where without it the script
|
|
259
|
+
refuses. A ledger rotate did write is read as usual. Record nothing on the
|
|
260
|
+
ledger and act on nothing in its receipt.
|
|
261
|
+
|
|
262
|
+
## Derive the Recipe
|
|
263
|
+
|
|
264
|
+
**Derive the Recipe — the Recipe derivation step — before the fold-in below
|
|
265
|
+
and before the first claim.** Every claim runs this repository's Install
|
|
266
|
+
step and bakes its Test entrypoint into the member's runner, and every
|
|
267
|
+
review reads the Test entrypoint, all out of the **Recipe cache**
|
|
268
|
+
(`.fleet/recipe.json` beside the common git dir); no script infers either
|
|
269
|
+
command. Check it first: `~/.fleet/bin/fleet-run derive-testcmd.sh .
|
|
270
|
+
install` and `~/.fleet/bin/fleet-run derive-testcmd.sh . test --at
|
|
271
|
+
origin/main`. **Both exit
|
|
272
|
+
0 → the cache is present and valid: use it as it stands and derive
|
|
273
|
+
nothing.** Either exits 1 (a refusal about the cache) → derive it; a refusal
|
|
274
|
+
naming `--at` says `origin/main` does not resolve, which is no cache fault —
|
|
275
|
+
fetch it and check again, since deriving would not help. Either
|
|
276
|
+
exits 3 → the reader could not run a tool it needs, so the cache's state is
|
|
277
|
+
unknown: fix that environment fault and check again; deriving would not
|
|
278
|
+
help. This step is yours: one derivation
|
|
279
|
+
per run start at most, never one per member, and a member never derives.
|
|
280
|
+
Dispatch a `task` member named `derive-recipe`, agent
|
|
281
|
+
`fleet-recipe-deriver`, and wait for its report — nothing in this run can
|
|
282
|
+
claim before it lands:
|
|
283
|
+
|
|
284
|
+
> Derive, prove and cache the Recipe of the repository at `<repo>`. Your
|
|
285
|
+
> scratch directory is `<scratch>/derive-recipe/`; write nowhere else.
|
|
286
|
+
> Follow your definition's procedure exactly, and end with its report line.
|
|
287
|
+
|
|
288
|
+
`<repo>` is this main checkout's absolute path and `<scratch>` is the
|
|
289
|
+
absolute path `scratch-root.mjs` prints (SKILL.md's **The scratch root is
|
|
290
|
+
computed**), written into the prompt before you send it. The member reads the repository,
|
|
291
|
+
proposes both commands and proves them with `recipe-prove.mjs` in a
|
|
292
|
+
throwaway worktree of `origin/main`: the Install step must leave the tree
|
|
293
|
+
clean, and the Test entrypoint must be shown to run real tests — the
|
|
294
|
+
runner's own non-zero count, or a deliberate mutation of one test that
|
|
295
|
+
turns the run red. Only a proof writes the cache, with `derivedAt` (the
|
|
296
|
+
`origin/main` commit it ran against) and the proof itself. **`RECIPE
|
|
297
|
+
PROVEN`** → re-run both reads above (`derive-testcmd.sh . install` and
|
|
298
|
+
`derive-testcmd.sh . test --at origin/main`); their output is the
|
|
299
|
+
Recipe this run uses. **`RECIPE NOT PROVEN`** → stall, below.
|
|
300
|
+
|
|
301
|
+
**Mid-run, a cache that stops running is re-derived once, then the run
|
|
302
|
+
stalls.** A claim or a review that refuses because the Recipe cache is
|
|
303
|
+
invalid — a command that no longer runs, or an Install step that changed
|
|
304
|
+
the tree — is the one mid-run trigger: dispatch `derive-recipe` again
|
|
305
|
+
exactly as above, then retry what refused. The Install step's refusals
|
|
306
|
+
fire after the claim has labelled the ticket and created its worktree, so
|
|
307
|
+
release that claim with `release-ticket.sh` first (**Release the claims
|
|
308
|
+
that never became PRs**). A red suite never triggers it: a failing test is
|
|
309
|
+
a finding, not a stale Recipe. **Stall:** `RECIPE NOT PROVEN` from any
|
|
310
|
+
derivation, or a second invalid-cache refusal after this run's one
|
|
311
|
+
re-derivation, halts the run — no Pull, no claim, no review dispatch — and
|
|
312
|
+
you report `STALL — Recipe not proven: <cause>` to the maintainer with the
|
|
313
|
+
deriver's reason verbatim. A repository the fleet cannot run needs human
|
|
314
|
+
hands, the `ready-for-human` cause: a toolchain this machine lacks, a
|
|
315
|
+
suite that runs no tests the proof can see, or an Install step, Test
|
|
316
|
+
entrypoint or mutation that hangs until the proof's own bound refuses it as
|
|
317
|
+
timed out. It is never a loop: no third derivation, and never a cache
|
|
318
|
+
written by hand.
|
|
319
|
+
|
|
320
|
+
## Fold in every PR a prior run left open
|
|
321
|
+
|
|
322
|
+
**Fold in every PR a prior run left open, before shortlisting.** However it
|
|
323
|
+
is named and whatever it carries — ticket work whose review was deferred, or
|
|
324
|
+
that run's own metrics — it is reviewable work no member otherwise picks up,
|
|
325
|
+
because the Shortlist holds ISSUES and nothing looks at inherited PRs. Queue
|
|
326
|
+
each for review exactly as ticket work: same review workflow, same
|
|
327
|
+
fix-applier, same finisher. **Skip a PR a row rotate carried already
|
|
328
|
+
holds** — its `#<pr>` key, or the PR of its `impl-<N>=PR#<pr>` token: that
|
|
329
|
+
row already queues it, and a `ledger.mjs row` write replaces the whole
|
|
330
|
+
line, wiping the live tokens carried on it. Measured 2026-09-03 — a prior
|
|
331
|
+
run's ticket PR arrived this way and its review found a defect its own PR
|
|
332
|
+
body called
|
|
333
|
+
unreviewed, and a metrics PR's review then caught two metrics rows the
|
|
334
|
+
controller had missed in its own close-out, so no PR is exempt from being
|
|
335
|
+
wrong. Reviewing them next run is also what stops one pinning
|
|
336
|
+
`fleet-tick`'s backlog forever: unreviewable AND uncounted is the state
|
|
337
|
+
that strands it.
|
|
338
|
+
|
|
339
|
+
## Resume the claims a dead run left without a PR
|
|
340
|
+
|
|
341
|
+
**Resume the claims a dead run left without a PR — after the fold-in,
|
|
342
|
+
before shortlisting.** A claim's label and worktree exist before its first
|
|
343
|
+
push, and rotation after a dead run carries no row forward, the candidate
|
|
344
|
+
scan excludes `in-progress`, and the in-flight check reads the worktree as
|
|
345
|
+
taken — so a
|
|
346
|
+
claim the previous run left without a PR is held by nobody until this step
|
|
347
|
+
names it. `~/.fleet/bin/fleet-run stranded.mjs` lists and classifies; you
|
|
348
|
+
dispatch. It reads the `prior` rotate just recorded, never the record
|
|
349
|
+
itself, which names this run's own live controller, and prints
|
|
350
|
+
`{prior, claims: [{n, t, action, worktree, branch, why}], carried: [{name,
|
|
351
|
+
token, row}]}`:
|
|
352
|
+
|
|
353
|
+
- `prior: dead` — every open `in-progress` issue with no open PR (one with
|
|
354
|
+
an open PR is the fold-in's): `resume` when exactly one worktree for it
|
|
355
|
+
sits under this checkout's `.worktrees/`, `report` otherwise.
|
|
356
|
+
- `prior: ancestor` — this session's own earlier run: no claim is listed.
|
|
357
|
+
`carried` lists every live token rotate carried — its member or runner
|
|
358
|
+
`name` (a `review=wf:` launch's runId), the `token` as the ledger holds
|
|
359
|
+
it, and the `row` carrying it, null for a member only `## Dispatched`
|
|
360
|
+
names. Reconcile them before shortlisting: read `proc://` once, find
|
|
361
|
+
each `name` among this session's jobs, and act on its state.
|
|
362
|
+
`running` → keep the token. `completed` or `failed` → record its
|
|
363
|
+
result from `agent://<id>` as the **Record, then tick** table records
|
|
364
|
+
that member's report; an output you cannot read is a death the
|
|
365
|
+
Member-killed row confirms. `cancelled` → record it dead. Absent, or a
|
|
366
|
+
state you cannot read → keep the token live and let the Member-killed
|
|
367
|
+
row clear it: a token nothing confirms dead counts as live. Recording a
|
|
368
|
+
death has two forms, here and on the Member-killed row alike. An
|
|
369
|
+
`impl-`, `fix-pr-`, `finisher-pr-` or `merge-bot-` member is settled:
|
|
370
|
+
`ledger.mjs settle <name> killed`. A reviewer is no member `settle`
|
|
371
|
+
takes — `settle review-pr-<n> killed` exits 2 — so its launch is
|
|
372
|
+
settled `=failed` where it stands: a `ledger.mjs review <pr>
|
|
373
|
+
review=member:<name>=failed` call that turns `review=member:<name>` on
|
|
374
|
+
the PR's row into `review=member:<name>=failed`
|
|
375
|
+
(`wf:` launches alike), after which the tick owes the PR
|
|
376
|
+
a review again under the next free reviewer name.
|
|
377
|
+
- `prior: none` — no record proves the previous run dead (no record yet, or
|
|
378
|
+
no `omp` process found above the rotation): every claim is `report`, and
|
|
379
|
+
nothing is resumed.
|
|
380
|
+
|
|
381
|
+
A `resume` follows the Member-killed row across the run boundary: a new
|
|
382
|
+
member under a new name — `impl-<N>-b`, or one letter past the highest
|
|
383
|
+
`impl-<N>-<x>` in the archive that rotate printed the path of — on the same
|
|
384
|
+
ticket, in the printed worktree and branch, its prompt the phase 2 prompt
|
|
385
|
+
off a fresh read of the issue plus what it inherits (`git -C <worktree> log
|
|
386
|
+
--oneline origin/main..HEAD`, `git -C <worktree> status --short`, and the
|
|
387
|
+
files under `<scratch>/impl-<N>/`). Record it the ordinary way —
|
|
388
|
+
`ledger.mjs row <N>
|
|
389
|
+
"impl-<N>-b"`, then `dispatch-prompt.mjs render implementer --member
|
|
390
|
+
impl-<N>-b …`, then `ledger.mjs dispatch <N> impl-<N>-b`, then the `task`
|
|
391
|
+
call naming the `agent` it printed, then the tier check — and never
|
|
392
|
+
`claim-ticket.sh`: the claim already stands. A `report` goes to the
|
|
393
|
+
maintainer as `#<N> — <why>` and nothing else: no dispatch, no label change,
|
|
394
|
+
no release. Exit 2 is a list that did not answer — a `gh` or `git`
|
|
395
|
+
failure, a list at its cap, a worktree whose presence cannot be told, or,
|
|
396
|
+
after `ancestor`, a ledger that cannot be read — and is never nothing
|
|
397
|
+
stranded.
|