@feigi/fleet-ctl 3.58.0 → 3.59.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.
@@ -251,375 +251,47 @@ refreshes the Shortlist itself, and every admission is a **Pull** — one ticket
251
251
  into one free implementer slot, the moment it frees (phase 1). Nothing in this
252
252
  phase, or in any later one, asks the maintainer which tickets to take.
253
253
 
254
- 0. **Once per run, before anything else.**
255
-
256
- **Fast-forward the checkout before you trust these rules — you are reading
257
- them from it.** First, `git symbolic-ref -q HEAD` must print
258
- `refs/heads/main`; anything else, stop and tell the maintainer — a checkout
259
- left on a branch whose PR has merged would fast-forward that branch, and the
260
- baseline below would record it as the run's ref. Then
261
- `git fetch origin && git rev-list --count main..origin/main`;
262
- non-zero means the SKILL.md you are executing is superseded, so
263
- `git merge --ff-only origin/main` and re-read what changed under
264
- `commands/`, `scripts/` and `skills/`. The usual cause is the PREVIOUS run's own close-out PR: it
265
- lands the rules THIS run needs and nothing pulls them. Measured twice — 57
266
- commits stale in one run, 20 in another, the second shipping every dispatch
267
- prompt without two rules that had merged the day before. Silent by
268
- construction: stale text reads as authoritative.
269
-
270
- **Pin the instruments, after that fast-forward and before anything reads
271
- them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
272
- records what the scripts and runbooks in this repo say right now, which is
273
- what every later gate compares against; the rule above says what its exit
274
- codes mean. Pinning before that fast-forward would instead pin the
275
- superseded text and certify it for the rest of the run.
276
- **When this workspace does not track `plugin/…`** — fleets run here on an
277
- installed plugin rather than a vendored tree — the bare pin refuses on an
278
- empty instrument set, because this checkout holds no instruments to certify.
279
- Name the plugin checkout to the pin instead:
280
- `~/.fleet/bin/fleet-run instruments.sh --pin --audit <plugin-checkout>`.
281
- The baseline records the audited tree beside the digest, and every later
282
- check — yours, a finisher's, the merge gate's own leg — follows that
283
- recorded root without being told twice. Refusing the bare pin and naming
284
- the tree once is the whole cross-workspace contract; never dispatch a
285
- member into a run whose phase-0 pin refused.
286
-
287
- **Record the main-checkout baseline in the same step, right after the
288
- pin.** `~/.fleet/bin/fleet-run main-checkout.mjs --record` writes
289
- `.fleet/main-checkout.sha`: the main checkout's `git status --porcelain
290
- -uall` entries plus a content hash of every path they name, and its HEAD —
291
- symbolic ref and commit. Your own
292
- uncommitted work is fine — it is in the baseline and holds nothing. From
293
- then on every `fleet-tick.mjs` compares the main checkout against it and
294
- holds dispatch on any change: the backstop for the stray member
295
- writes `member-write-guard` cannot see — an `eval` cell, a `bash` that
296
- `cd`s or `git -C`s into this checkout. `.fleet/`, `.worktrees/` and
297
- `.agent-brain/` are gitignored and never trip it. Nor does this run's own
298
- bookkeeping: `docs/metrics/tier-outcomes.tsv`,
299
- `docs/metrics/member-outcomes.tsv` and `docs/metrics/ticket-features.tsv`,
300
- which you write mid-run, are left out by name — anything else under
301
- `docs/metrics/` still trips it. **The same
302
- command is the clear, and it overwrites; it never compares.** On `MAIN-CHECKOUT-DIRTY`
303
- the maintainer resolves the stray paths FIRST — inspect, keep or remove
304
- them — and only then re-runs `--record`; re-recording over unresolved paths
305
- certifies them. **Never re-record over `MAIN-CHECKOUT-UNKNOWN`**: that
306
- walks the run from "could not look" to "certified clean" in one step, so
307
- `--record` itself refuses over a baseline it cannot read, over one a newer
308
- plugin wrote, and on any git read that fails. The exceptions are an
309
- older-version baseline and a baseline whose commit is missing from the
310
- repository; Phase 3's tick lines say how each is cleared.
311
- `main-checkout.mjs --check` prints the same answer
312
- without a tick.
313
-
314
- **Run the pre-flight, once the pin and the baseline are recorded.**
315
- `~/.fleet/bin/fleet-run preflight.mjs` checks what this machine and this
316
- repository must give the fleet — the binaries, `gh` auth, `origin/main`,
317
- `.worktrees/` and `.fleet/` ignored, the three labels, merge commits on, a
318
- ruleset, the Resolver — and prints one `ok`, `WARN` or `FAIL` line per
319
- check, each naming its check. **Exit 1 stops the run:** no shortlist, no
320
- dispatch. Report every `FAIL` line to the maintainer by its check's name;
321
- the run starts again once they are fixed. Exit 2 means it could not run at
322
- all, or every check passed and the marker could not be written, and stops
323
- the run the same way. `WARN ci-workflow` stops nothing:
324
- a repo with no workflow named CI still runs, its workflow named per call
325
- with `--workflow` or declared absent with `--declare-no-ci`. A pass writes
326
- `.fleet/preflight.json`, keyed to a hash of the check set, and every later
327
- run prints `PREFLIGHT SKIPPED` without a single `gh` call until a check is
328
- added or changed.
329
-
330
- **Check the merge gate against its spec, once the fast-forward has put the
331
- ratified spec in front of you.** Where the workspace checks a ruleset spec
332
- in, `.github/scripts/apply-ruleset.sh --check` compares it to the live gate
333
- without writing anything (no spec checked in → nothing to run, skip it).
334
- Three statuses and they are not interchangeable: **0** the gate is what the
335
- tree says it is; **3** it is not — including the gate having been deleted
336
- or renamed — and the diff it prints says how; **2** the question could not
337
- be answered at all: no spec, no `gh`, a listing or read that failed
338
- outright, or a read that succeeded but withheld `bypass_actors` because
339
- the session lacks repository admin.
340
-
341
- **3 does not stop the run and is not yours to fix** — reconciling is a
342
- write to the gate protecting this repo, so it needs the maintainer.
343
- Surface the diff and carry on. What it changes is what you may then claim:
344
- every statement this run makes about which checks must pass before a merge
345
- is sourced from the checked-in spec and is true of the live gate only
346
- while this check is green, so a 3 means saying "the gate requires X"
347
- without naming the drift is a false claim, and a 2 means you never learned
348
- either way. Measured 2026-09-23: four contexts the spec required were
349
- enforced by nothing live, and the gap sat
350
- there unnoticed because the only thing that ever read the live gate was a
351
- person choosing to.
352
-
353
- **Drain the pending ticket-features rows and refresh the cost guard, after
354
- the fast-forward and before the first Pull is routed.**
355
- `~/.fleet/bin/fleet-run metrics-refresh.mjs` moves
356
- `.fleet/ticket-features.pending.tsv` into `docs/metrics/ticket-features.tsv`,
357
- deduped on `session`+`agent` — this recovers the rows of a run that crashed
358
- before its close-out — and then runs `pr-cost.mjs --guard`, rewriting
359
- `.fleet/cost-guard.json`, which the router reads and fails closed without
360
- (no file: the default cell only). The guard has to be fresh before the
361
- first Pull is routed, so the verdict reflects any rows just recovered. Exit
362
- 0: both ran. The guard's own exit 3 (a cell tripped) and 4 (no verdict yet)
363
- are verdicts the router and `fleet-tick.mjs` read, never failures; the
364
- script absorbs them. A workspace that lacks one of the three metrics TSVs
365
- has no corpus to guard yet — its first run: the script prints a line naming
366
- the missing file, skips the guard and exits 0. Exit 1 or 2 stops the run
367
- before its first Pull: report the line the script printed on stderr, fix
368
- the cause and run it again — each duty is safe to repeat.
369
-
370
- **Launch the cockpit.** On every phase-0 pass, not just the first:
371
- `node ~/.fleet/bin/fleet-run board.mjs serve --open &` in the
372
- background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
373
- feed or update it, and it survives your own compaction. The launch is
374
- idempotent per workspace when the running cockpit answers the identity
375
- handshake: an already-served workspace's launch finds the running server
376
- over HTTP, prints its URL, and exits 0 without starting a second one —
377
- nothing to skip. It opens nothing either: `--open` opens a tab
378
- only from the launch that binds a port and starts the server, so a
379
- re-shortlist leaves the board tab you already have alone. A second fleet
380
- on another workspace collides with none of that: its own launch derives
381
- that workspace's own port and binds it when free, or scans to the next
382
- free port in its range when the derived one is already held by something
383
- else — either way it gets its own board, just not always on the port its
384
- hash predicts.
385
-
386
- The spend panel reads this workspace's own `~/.omp/agent/sessions` tree,
387
- and is pinned to whichever session first writes a transcript on this
388
- cockpit's own watch: it will not follow a workspace that
389
- already had another session's transcripts sitting there at launch. If the
390
- panel is reading someone else's numbers, relaunch with `--spend-dir <path>`
391
- naming this run's own session directory to override the heuristic outright —
392
- `~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>` (the directory, never
393
- the `.jsonl` file of the same name beside it).
394
-
395
- **Rotate the ledger before the fold-in below and before shortlisting —
396
- every run, whatever way the previous one ended.** One ledger per run:
397
- `~/.fleet/bin/fleet-run ledger.mjs rotate` moves the previous run's
398
- `.fleet/ledger.md` byte-for-byte to `.fleet/ledger.<UTC
399
- YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind. What it carries forward
400
- turns on the verdict it reaches below. After `dead` or `none` nothing is
401
- carried — no row, exclusion, `## Filed` or `## Ruled` entry — so this
402
- run's first write starts the empty skeleton, and an unchecked `impl-` row
403
- a prior run left behind can no longer hold this run's tick: a dead
404
- controller took its in-process members with it. After `ancestor` — this
405
- session's own earlier run, whose members run inside the same omp process
406
- and may still be live — it writes a new ledger holding every row of a
407
- stream (one PR's rows) in which a row carries an unsettled member token
408
- or an open `review=` launch, whole and with every other token on it, plus
409
- every unsettled `## Dispatched` entry and the settled entry of each
410
- member a carried row names; exclusions, `## Filed`, `## Ruled` and the
411
- drain marker are never carried. Every other settled name — in
412
- `## Dispatched` or on any row, and including a name whose outcome is
413
- outside its family's vocabulary, whose line is skipped below — and every
414
- reviewer runner a row launched goes into the new ledger's `## Retired` as
415
- a bare name, with whatever the archive's own `## Retired` held: omp answers a second `task` under a name
416
- this process has used with `<name>-2` while `hub send <name>` keeps
417
- reaching the first, so a settled name stays taken for the session, not
418
- the run. `dispatch` refuses a retired name and names the replacement — one
419
- retry letter past the highest the session has used on that number,
420
- `impl-42-b` for a ticket this session's earlier run worked as `impl-42` —
421
- `review` refuses a retired runner name and names the next free reviewer
422
- name, and `dispatch merge-bot` numbers past retired bots. The tick never
423
- reads `## Retired`: a ticket an earlier run worked is not claimed by it
424
- and can be shortlisted again.
425
- A line it cannot parse is skipped with a warning naming it, and the
426
- rotation still succeeds; a member name on a skipped line that carries an
427
- outcome is retired all the same, and a bare member token on a skipped row
428
- retires nothing. It prints `{rotated, archive, carried: {rows,
429
- dispatched}, retired, skipped}`. The carried tokens keep the tick from
430
- dispatching onto those members' work, keep their names taken, and give
431
- their late results a token to settle; the stranded-claim step below
432
- reconciles them.
433
- What an unclean end left in
434
- flight comes back through the ordinary per-run path: open PRs through the
435
- fold-in below, `behind-pr:`/`behind-issue:` exclusions through phase 1's
436
- collision and sequence checks, and a claim a dead run left without a PR
437
- through the stranded-claim step below — resumed by a new member under a
438
- new name when its worktree is in this checkout, reported to the
439
- maintainer otherwise. An exclusion that expires with the run that wrote
440
- it (`deferred-to-session-end` and its like) must be restated if it still
441
- holds. **The guard is the
442
- controller record**, `controller` in `.fleet/heartbeat.json`: the omp
443
- process the previous run's rotation found above itself, and that
444
- process's start time. Rotate judges it once, before anything moves. A
445
- recorded controller that is still alive, still the same process (its
446
- start time matches), and not an ancestor of this run refuses — exit 2,
447
- nothing moved — **whatever its heartbeat mark says**, because a
448
- controller can stop beating and keep dispatching. A dead one, a pid
449
- reused by another process, or this session's own earlier run lets it
450
- rotate. With no record the heartbeat mark decides, as the only guard
451
- there is: still beating or acting — a beat inside its window, or with no
452
- beat at all a tick or ledger write inside its window — refuses, naming
453
- the latest beat, tick or ledger write and when it would count as stalled;
454
- a stalled mark, a recorded `--stop`, or no mark at all lets it rotate —
455
- and that fallback proves "not beating", never "dead", and
456
- guards a ledger only: with none to move the mark is not consulted. With no
457
- ledger the record is still judged, so a live recorded controller refuses
458
- even then. It also refuses, nothing moved, when the stamped archive name
459
- already exists, when the process table cannot be read, or when
460
- `.fleet/heartbeat.json` exists but cannot be used — unreadable, not JSON,
461
- not a JSON object, or holding a `controller` that cannot be judged — a
462
- record nobody could judge is never taken for no record. On that refusal
463
- phase 0 stops and the refusal goes to the maintainer verbatim: the
464
- controller never edits or removes `.fleet/heartbeat.json`, because
465
- removing it inside a live omp session makes this rotate judge `none` and
466
- forfeits the carry — the live members and the retired names — so this
467
- run could dispatch onto their work and reuse their names. Every writer
468
- (`fleet-tick.mjs`, `fleet-heartbeat.mjs`, the ledger's write subcommands)
469
- leaves such a file as it is. Its last act, ledger or none, is
470
- to replace the record with this run's own — the nearest `omp` process
471
- above it, its start time, as `prior` the verdict it reached on the
472
- record it found (`dead`, `ancestor` or `none`), and as `at` when it wrote
473
- it — or to remove the key when
474
- no `omp` process is above it. The same write stamps `acted`, the time of
475
- this run's latest ledger write, which every write subcommand stamps from
476
- then on. That write can fail, and then exit 2 follows
477
- a move: `rotated <file> -> <archive>` on stderr, then the refusal that the
478
- record could not be written. Run the rotation before this run's own first
479
- tick, beat or ledger write, each of which writes a mark the fallback reads. Older
480
- archives, hand-named ones included, are left alone.
481
-
482
- **Reclaim scratch straight after the rotation — every run.**
483
- `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch>
484
- --after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
485
- so a run that merges nothing still reclaims the previous run's leftovers
486
- (**Reclaim scratch after each merge pass** says what it removes).
487
- `--after-rotate` goes on this call always and on no other: rotate leaves
488
- no ledger behind when it carried nothing, and the flag reads that absence
489
- as "no live token" — rotate's own verdict — where without it the script
490
- refuses. A ledger rotate did write is read as usual. Record nothing on the
491
- ledger and act on nothing in its receipt.
492
-
493
- **Derive the Recipe — the Recipe derivation step — before the fold-in below
494
- and before the first claim.** Every claim runs this repository's Install
495
- step and bakes its Test entrypoint into the member's runner, and every
496
- review reads the Test entrypoint, all out of the **Recipe cache**
497
- (`.fleet/recipe.json` beside the common git dir); no script infers either
498
- command. Check it first: `~/.fleet/bin/fleet-run derive-testcmd.sh .
499
- install` and `~/.fleet/bin/fleet-run derive-testcmd.sh . test --at
500
- origin/main`. **Both exit
501
- 0 → the cache is present and valid: use it as it stands and derive
502
- nothing.** Either exits 1 (a refusal about the cache) → derive it; a refusal
503
- naming `--at` says `origin/main` does not resolve, which is no cache fault —
504
- fetch it and check again, since deriving would not help. Either
505
- exits 3 → the reader could not run a tool it needs, so the cache's state is
506
- unknown: fix that environment fault and check again; deriving would not
507
- help. This step is yours: one derivation
508
- per run start at most, never one per member, and a member never derives.
509
- Dispatch a `task` member named `derive-recipe`, agent
510
- `fleet-recipe-deriver`, and wait for its report — nothing in this run can
511
- claim before it lands:
512
-
513
- > Derive, prove and cache the Recipe of the repository at `<repo>`. Your
514
- > scratch directory is `<scratch>/derive-recipe/`; write nowhere else.
515
- > Follow your definition's procedure exactly, and end with its report line.
516
-
517
- `<repo>` is this main checkout's absolute path and `<scratch>` is the
518
- absolute path `scratch-root.mjs` prints (**The scratch root is computed**
519
- above), written into the prompt before you send it. The member reads the repository,
520
- proposes both commands and proves them with `recipe-prove.mjs` in a
521
- throwaway worktree of `origin/main`: the Install step must leave the tree
522
- clean, and the Test entrypoint must be shown to run real tests — the
523
- runner's own non-zero count, or a deliberate mutation of one test that
524
- turns the run red. Only a proof writes the cache, with `derivedAt` (the
525
- `origin/main` commit it ran against) and the proof itself. **`RECIPE
526
- PROVEN`** → re-run both reads above (`derive-testcmd.sh . install` and
527
- `derive-testcmd.sh . test --at origin/main`); their output is the
528
- Recipe this run uses. **`RECIPE NOT PROVEN`** → stall, below.
529
-
530
- **Mid-run, a cache that stops running is re-derived once, then the run
531
- stalls.** A claim or a review that refuses because the Recipe cache is
532
- invalid — a command that no longer runs, or an Install step that changed
533
- the tree — is the one mid-run trigger: dispatch `derive-recipe` again
534
- exactly as above, then retry what refused. The Install step's refusals
535
- fire after the claim has labelled the ticket and created its worktree, so
536
- release that claim with `release-ticket.sh` first (**Release the claims
537
- that never became PRs**). A red suite never triggers it: a failing test is
538
- a finding, not a stale Recipe. **Stall:** `RECIPE NOT PROVEN` from any
539
- derivation, or a second invalid-cache refusal after this run's one
540
- re-derivation, halts the run — no Pull, no claim, no review dispatch — and
541
- you report `STALL — Recipe not proven: <cause>` to the maintainer with the
542
- deriver's reason verbatim. A repository the fleet cannot run needs human
543
- hands, the `ready-for-human` cause: a toolchain this machine lacks, a
544
- suite that runs no tests the proof can see, or an Install step, Test
545
- entrypoint or mutation that hangs until the proof's own bound refuses it as
546
- timed out. It is never a loop: no third derivation, and never a cache
547
- written by hand.
548
-
549
- **Fold in every PR a prior run left open, before shortlisting.** However it
550
- is named and whatever it carries — ticket work whose review was deferred, or
551
- that run's own metrics — it is reviewable work no member otherwise picks up,
552
- because the Shortlist holds ISSUES and nothing looks at inherited PRs. Queue
553
- each for review exactly as ticket work: same review workflow, same
554
- fix-applier, same finisher. **Skip a PR a row rotate carried already
555
- holds** — its `#<pr>` key, or the PR of its `impl-<N>=PR#<pr>` token: that
556
- row already queues it, and a `ledger.mjs row` write replaces the whole
557
- line, wiping the live tokens carried on it. Measured 2026-09-03 — a prior
558
- run's ticket PR arrived this way and its review found a defect its own PR
559
- body called
560
- unreviewed, and a metrics PR's review then caught two metrics rows the
561
- controller had missed in its own close-out, so no PR is exempt from being
562
- wrong. Reviewing them next run is also what stops one pinning
563
- `fleet-tick`'s backlog forever: unreviewable AND uncounted is the state
564
- that strands it.
565
-
566
- **Resume the claims a dead run left without a PR — after the fold-in,
567
- before shortlisting.** A claim's label and worktree exist before its first
568
- push, and rotation after a dead run carries no row forward, the candidate
569
- scan excludes `in-progress`, and the in-flight check reads the worktree as
570
- taken — so a
571
- claim the previous run left without a PR is held by nobody until this step
572
- names it. `~/.fleet/bin/fleet-run stranded.mjs` lists and classifies; you
573
- dispatch. It reads the `prior` rotate just recorded, never the record
574
- itself, which names this run's own live controller, and prints
575
- `{prior, claims: [{n, t, action, worktree, branch, why}], carried: [{name,
576
- token, row}]}`:
577
-
578
- - `prior: dead` — every open `in-progress` issue with no open PR (one with
579
- an open PR is the fold-in's): `resume` when exactly one worktree for it
580
- sits under this checkout's `.worktrees/`, `report` otherwise.
581
- - `prior: ancestor` — this session's own earlier run: no claim is listed.
582
- `carried` lists every live token rotate carried — its member or runner
583
- `name` (a `review=wf:` launch's runId), the `token` as the ledger holds
584
- it, and the `row` carrying it, null for a member only `## Dispatched`
585
- names. Reconcile them before shortlisting: read `proc://` once, find
586
- each `name` among this session's jobs, and act on its state.
587
- `running` → keep the token. `completed` or `failed` → record its
588
- result from `agent://<id>` as the **Record, then tick** table records
589
- that member's report; an output you cannot read is a death the
590
- Member-killed row confirms. `cancelled` → record it dead. Absent, or a
591
- state you cannot read → keep the token live and let the Member-killed
592
- row clear it: a token nothing confirms dead counts as live. Recording a
593
- death has two forms, here and on the Member-killed row alike. An
594
- `impl-`, `fix-pr-`, `finisher-pr-` or `merge-bot-` member is settled:
595
- `ledger.mjs settle <name> killed`. A reviewer is no member `settle`
596
- takes — `settle review-pr-<n> killed` exits 2 — so its launch is
597
- settled `=failed` where it stands: a `ledger.mjs review <pr>
598
- review=member:<name>=failed` call that turns `review=member:<name>` on
599
- the PR's row into `review=member:<name>=failed`
600
- (`wf:` launches alike), after which the tick owes the PR
601
- a review again under the next free reviewer name.
602
- - `prior: none` — no record proves the previous run dead (no record yet, or
603
- no `omp` process found above the rotation): every claim is `report`, and
604
- nothing is resumed.
605
-
606
- A `resume` follows the Member-killed row across the run boundary: a new
607
- member under a new name — `impl-<N>-b`, or one letter past the highest
608
- `impl-<N>-<x>` in the archive that rotate printed the path of — on the same
609
- ticket, in the printed worktree and branch, its prompt the phase 2 prompt
610
- off a fresh read of the issue plus what it inherits (`git -C <worktree> log
611
- --oneline origin/main..HEAD`, `git -C <worktree> status --short`, and the
612
- files under `<scratch>/impl-<N>/`). Record it the ordinary way —
613
- `ledger.mjs row <N>
614
- "impl-<N>-b"`, then `dispatch-prompt.mjs render implementer --member
615
- impl-<N>-b …`, then `ledger.mjs dispatch <N> impl-<N>-b`, then the `task`
616
- call naming the `agent` it printed, then the tier check — and never
617
- `claim-ticket.sh`: the claim already stands. A `report` goes to the
618
- maintainer as `#<N> — <why>` and nothing else: no dispatch, no label change,
619
- no release. Exit 2 is a list that did not answer — a `gh` or `git`
620
- failure, a list at its cap, a worktree whose presence cannot be told, or,
621
- after `ancestor`, a ledger that cannot be read — and is never nothing
622
- stranded.
254
+ 0. **Once per run, before anything else.** Run `~/.fleet/bin/fleet-run
255
+ phase0.mjs --session <session-dir>` from this main checkout, `<session-dir>`
256
+ being this run's own session directory. Add `--implementer-cap <n>` and
257
+ `--reviewer-cap <n>` for the caps `$ARGUMENTS` gave, `--plugin-checkout
258
+ <dir>` when this workspace tracks no `plugin/…` of its own, `--spend-dir
259
+ <dir>` to name the directory the cockpit's spend panel reads, and
260
+ `--workflow <name>` or `--declare-no-ci` when the repository has no workflow
261
+ named CI. It runs the start sequence in its fixed order — branch,
262
+ fast-forward, pin, baseline, preflight, ruleset, tier-roles, metrics,
263
+ cockpit, rotate, reclaim, recipe, fold-in, stranded, shortlist — prints one
264
+ `phase0: <step>: <status>` line per step with the `NEED` lines last, and
265
+ records each step in `.fleet/phase0.json`, which the tick reads: it prints
266
+ `PHASE0-INCOMPLETE` and holds every dispatching row until the receipt is whole.
267
+ Dispatch nothing before it exits 0. Exit 3 is a step that failed: its line
268
+ carries the refusal, so fix the cause and run it again. Exit 4 is a step
269
+ that needs you: act on each `NEED` line below, then run it again. Once
270
+ `rotate` has run, a re-run skips every `ok` step and resumes where the last
271
+ one stopped; before it, a re-run runs every step again.
272
+
273
+ - `NEED derive-recipe` — the Recipe cache holds nothing valid. Dispatch a
274
+ `task` member named `derive-recipe`, agent `fleet-recipe-deriver`, its
275
+ prompt the brief `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
276
+ recipe-deriver --member derive-recipe --repo <repo> --scratch <scratch>`
277
+ prints (`<repo>` this main checkout's absolute path, `<scratch>` what
278
+ `scratch-root.mjs` prints), and wait for its report. `RECIPE PROVEN` →
279
+ run `phase0.mjs` again. `RECIPE NOT PROVEN` → stall: report `STALL —
280
+ Recipe not proven: <cause>` to the maintainer with the deriver's reason
281
+ verbatim, and claim, Pull and review nothing.
282
+ - `NEED resume #<n> <worktree> <branch>` — a dead run's claim with no PR.
283
+ Dispatch a stranded `impl-<n>-b` the ordinary way (record it with
284
+ `ledger.mjs row`, render its brief, `ledger.mjs dispatch`, the `task`
285
+ call, the tier check), in that worktree and branch, and never with
286
+ `claim-ticket.sh`: the claim stands. A re-run finds the need met once its
287
+ row is written. A `report #<n> — <why>` line is the maintainer's and
288
+ nothing else, and a `carried` line is a live token to reconcile first.
289
+ - `NEED review PR#<pr> (closes no issue)` — an open PR a prior run left
290
+ that no row can queue. Advice, never an exit status: hand-dispatch its
291
+ review exactly as ticket work, or leave it.
292
+
293
+ A `drift` or `unanswered` ruleset step is advice too: surface the diff and
294
+ go on. See references/phase-0.md.
623
295
 
624
296
  1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
625
297
  `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
@@ -1506,90 +1178,9 @@ in-between width cannot be told apart from a shifted one. The `note` field is
1506
1178
  free text and sits before those four, so the script refuses a tab or newline in
1507
1179
  it: one tab would shift all four for that row alone.
1508
1180
 
1509
- **Then record the run's member facts — do not author them.** Scrape EVERY session
1510
- directory for this cwd, not one:
1511
-
1512
- ```bash
1513
- PROJECT_DIR="$(node -e 'import("./scripts/member-record.mjs").then(m => console.log(m.encodeProjectDir(process.cwd())))')"
1514
- for d in "$HOME/.omp/agent/sessions/$PROJECT_DIR"/*/; do
1515
- node scripts/member-outcomes.mjs "$d"
1516
- done
1517
- ```
1518
-
1519
- `encodeProjectDir` (defined in `scripts/member-record.mjs`) encodes the cwd
1520
- exactly as omp names its session directories — see its comment for the rule — and hand-guessing that path is why
1521
- the fleet's own panel once rendered nothing here. The trailing `/` on the glob matters:
1522
- the same encoded-cwd directory also holds this cwd's own top-level session
1523
- transcripts as loose FILES sibling to the per-session directories, and a
1524
- glob without it would try to scrape one of those as if it were a session.
1525
-
1526
- **Do not narrow this to "this run's session" with `findSubagentsDir`.** That helper
1527
- answers a different question — the session with the NEWEST transcript for this cwd,
1528
- which is not the same as the one you are in. Any other session sharing this cwd —
1529
- a second terminal, a second controller run — can hold a newer transcript than
1530
- yours at the moment you reach this step, and a second session dispatching
1531
- anything while you reach it wins the tie: the run then re-scrapes a stranger's
1532
- members, prints a plausible row count and exits 0 while its own facts are
1533
- never recorded. Looping every session dir costs a few seconds, cannot pick
1534
- wrong, and is idempotent by construction.
1535
-
1536
- The scraper takes the session directory itself and refuses a path it cannot
1537
- read — a missing, unreadable or non-directory path all exit 2 — so a wrong
1538
- path fails loudly instead of writing nothing and exiting 0. It reports the
1539
- run's own YIELD, `scraped N of M members (D dropped)`, alongside the file's
1540
- total: read the yield, because the total is the whole corpus and looks
1541
- healthy even when every member of this session dropped.
1542
-
1543
- It derives every row from the member transcripts omp already wrote — both the
1544
- flat ones and a member's own nested fan-out one level down — so a
1545
- second run over the same session changes nothing and a re-run after a member is
1546
- re-dispatched picks the new transcript up. **Never hand-edit
1547
- `docs/metrics/member-outcomes.tsv`** — it is regenerated wholesale whenever the
1548
- role classifier changes, and a hand-entered value would not survive that. The
1549
- verdict for a PR goes to `tier-outcomes.tsv` through `tier-outcomes.mjs
1550
- append`, as above. Once both files hold this run's rows, and before either is
1551
- committed, run `~/.fleet/bin/fleet-run tier-outcomes.mjs check --live`. Exit 1
1552
- names each row whose `tier` disagrees with the one implementer the member facts
1553
- say ran for its ticket: correct that row's `tier` to the short name it prints,
1554
- or blank it and say why in `note`. Exit 1 also names the PRs of the case where
1555
- the latest `run_date`'s filled rows have no implementer row in the member file
1556
- and none could be compared, so nothing from that run was checked: append the
1557
- run's member rows if they are missing, or blank each named row's `tier` and say
1558
- why in `note`.
1559
- Each WARNING names a PR this run's ledger marks `reviewed=` that has no row yet
1560
- — append it before committing if it is an implementer PR.
1561
-
1562
- **Drain the pending ticket-features rows and refresh the cost guard, after
1563
- the member-outcomes scrape and every `tier-outcomes.mjs append`, before the
1564
- metrics files are committed.** `~/.fleet/bin/fleet-run metrics-refresh.mjs`
1565
- moves `.fleet/ticket-features.pending.tsv` — the row the router script
1566
- appended for each Pull at dispatch — into `docs/metrics/ticket-features.tsv`,
1567
- deduped on `session`+`agent`, so this run's own rows are in the file that gets
1568
- committed; that file is a run artifact too and is committed with the other
1569
- two. It then runs `pr-cost.mjs --guard`, which rewrites
1570
- `.fleet/cost-guard.json` from all three files. Exit 0: both ran. The guard's
1571
- own exit 3 (a cell tripped) and 4 (no verdict yet, baseline too thin) are
1572
- verdicts the router and `fleet-tick.mjs` read, never failures; the script
1573
- absorbs them. Exit 1 names the duty that failed on stderr and the duty after it
1574
- did not run; exit 2 is a usage error. At close-out a failure is reported to the
1575
- maintainer and does not stop the commit — the pending file stays in `.fleet/`
1576
- and the next run's phase-0 pass drains it — but never commit the metrics files
1577
- with a drain that failed claiming the corpus is complete.
1578
-
1579
- The metrics files are the run's own artifacts and none commits itself. Carry
1580
- them to main the same way the run carries any other controller-authored change;
1581
- leaving a regenerated 5,000-row corpus uncommitted in the checkout is how it gets
1582
- discarded by the next `git checkout` with nothing to show it ever ran.
1583
-
1584
- **Commit the metrics files and open a PR — at end of run.** The branch name is
1585
- the repository's choice. Make the commit on a branch in the main checkout,
1586
- switch back to `main` before the next tick, and never `--record` while on that
1587
- branch; the round trip reads clean. A PR still open when the run ends is one phase 0's
1588
- fold-in queues for review next run, however it is named, so the files reach
1589
- `main` through the same review as ticket work rather than being lost. Stranding
1590
- a data row loses it: `member-outcomes.tsv` is regenerated from harness
1591
- transcripts the fleet does not own, so re-running the scrape later is worth
1592
- only what the harness still holds.
1181
+ The member-facts scrape, the drain of the pending ticket-features rows and the
1182
+ commit of the metrics files are steps of `closeout.mjs finish`, which **End of
1183
+ run** (Phase 3) drives. See references/close-out.md.
1593
1184
 
1594
1185
  **Why not decide inside one run.** A run holds 2-3 implementer PRs, and ticket
1595
1186
  difficulty swamps the tier effect — a gojq parity harness and a two-statement
@@ -1725,15 +1316,15 @@ ticket's line — never a hand edit.
1725
1316
 
1726
1317
  | Wake | Record, then tick |
1727
1318
  |---|---|
1728
- | Implementer report | `verify-sha.sh`; `ledger.mjs settle impl-<N>=PR#<M>`, or `=bailed` and relabel by cause (**Implementer bails before implementing**, below) |
1319
+ | Implementer report | `ledger.mjs settle impl-<N> --from-report`, which runs `verify-sha.sh` and reads the PR itself (**Run ledger**); on `bailed`, relabel by the cause its receipt names (**Implementer bails before implementing**, below) |
1729
1320
  | Review workflow notification / `review-pr-<n>` report | the result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root; `ledger.mjs review <pr> reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` on the PR's row (**Reviewers**) |
1730
- | Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges that member's own record `<scratch>/dispositions-<member>.json` against the review file the PR's latest `reviewed=` names, `<scratch>/pr<M>/<run>/review.json`, writes `dispositions-ok=`, `dispositions-mismatch=`, `dispositions-escalate=` or `dispositions-unchecked=<member>:<run>` onto the PR's row itself, and exits 1 on a mismatch, an escalation or an unchecked, naming each violating or escalated entry's bucket and index, a violation its rule too, and each entry whose filed issue `gh` could not read — **Then dispatch a fix-applier** says what a mismatch asks of you, the gate paragraph below what an escalation or an unchecked does; copy the refutations it reversed — the record's `refuted` entries — to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1731
- | Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled` as reported, even when its read-back lacks `ready-to-merge` — the tick's `DISPATCH finisher PR#<M>` catches that next. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment. `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1732
- | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M>=halted:<cause>`; `gh pr comment <M>` with the finisher's halt report, cause and evidence; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line; then the per-cause rule (**Resolving a finisher halt**, below) |
1321
+ | Fix-applier report | `ledger.mjs settle fix-pr-<M> --from-report`, which records each `unrecorded` filing and copies to `ruled` each refutation the report defers; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges that member's own record `<scratch>/dispositions-<member>.json` against the review file the PR's latest `reviewed=` names, `<scratch>/pr<M>/<run>/review.json`, writes `dispositions-ok=`, `dispositions-mismatch=`, `dispositions-escalate=` or `dispositions-unchecked=<member>:<run>` onto the PR's row itself, and exits 1 on a mismatch, an escalation or an unchecked, naming each violating or escalated entry's bucket and index, a violation its rule too, and each entry whose filed issue `gh` could not read — **Then dispatch a fix-applier** says what a mismatch asks of you, the gate paragraph below what an escalation or an unchecked does; copy any other refutation it reversed — a `refuted` entry of the record the report does not defer — to `ruled` yourself |
1322
+ | Finisher report | `ledger.mjs settle finisher-pr-<M> --from-report`, which records each `unrecorded` filing. Its exit 3 on `ready-to-merge` — missing from the PR or from the read-back — is the case the tick's `DISPATCH finisher PR#<M>` catches next: settle it `ledger.mjs settle finisher-pr-<M>=labelled` as reported, and `ledger.mjs filed <N> "<subject>"` for each `unrecorded` entry. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment |
1323
+ | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M> --from-report`, which records each `unrecorded` filing; `gh pr comment <M>` with the finisher's halt report, cause and evidence; then the per-cause rule (**Resolving a finisher halt**, below) |
1733
1324
  | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1734
1325
  | Label seen (persistent Monitor) | nothing to record |
1735
1326
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1736
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1327
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n> --from-report`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1737
1328
  | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1738
1329
  | Heartbeat | nothing to record |
1739
1330
 
@@ -1802,25 +1393,32 @@ owes beyond its row:
1802
1393
  on a conflict needs no record from you — the bot already appended
1803
1394
  `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
1804
1395
  fix-pr PR#<pr>` (**Reviewers**).
1805
- - **The run ends, or the maintainer says drain** → `ledger.mjs drain
1806
- "<reason>"` first, then release every claim that never became a PR (below)
1807
- and settle each `impl-<N>=released`. Nothing else in the loop fires for those
1808
- claims. The marker is on disk, so the tick holds the implementer row at
1809
- `HOLD (draining)` from then on — for a replacement controller too — and keeps
1810
- the review, fix-applier and merge rows firing until the open PRs merge.
1811
- The drain starts the end of the run; it does not end it. **End of run**, in
1812
- this order:
1813
- 1. `ledger.mjs drain "<reason>"`.
1814
- 2. Release every claim that never became a PR, settling each
1815
- `impl-<N>=released`.
1816
- 3. Act on the review, fix-applier and merge rows until no PR is open. Once
1817
- the run is draining with no open PR and no live implementer, the tick's
1818
- last line is `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`.
1819
- 4. Scrape the run's member facts, append every `tier-outcomes.mjs` row, and
1820
- run `metrics-refresh.mjs` (above).
1821
- 5. Commit the metrics files and open their PR (above).
1822
- 6. `~/.fleet/bin/fleet-run fleet-heartbeat.mjs --stop "<reason>"` — last,
1823
- because every reader takes a recorded stop as the end of the run.
1396
+ - **The run ends, or the maintainer says drain** → `closeout.mjs begin` first
1397
+ (below): it drains and releases every claim that never became a PR. Nothing
1398
+ else in the loop fires for those claims. The marker is on disk, so the tick
1399
+ holds the implementer row at `HOLD (draining)` from then on — for a
1400
+ replacement controller too — and keeps the review, fix-applier and merge rows
1401
+ firing until the open PRs merge. The drain starts the end of the run; it does
1402
+ not end it. **End of run**, in this order:
1403
+ 1. `~/.fleet/bin/fleet-run closeout.mjs begin --reason "<reason>"` — drains
1404
+ (`ledger.mjs drain`), then releases every claim that never became a PR and
1405
+ settles each `impl-<N>=released` (**Release the claims that never became
1406
+ PRs**). A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
1407
+ refusal is the finding, so run `worktree-audit.sh` and decide by hand.
1408
+ `begin` selects a claim with no PR and a live or `bailed` implementer token
1409
+ on every run, so a claim you keep leaves `begin` at exit 4 on every run:
1410
+ release the rest by hand and run `begin` again.
1411
+ 2. Act on the review, fix-applier and merge rows until the tick prints
1412
+ `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
1413
+ once the run is draining with no open PR and no live implementer.
1414
+ 3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
1415
+ the run's member facts, checks the tier-outcomes rows, refreshes the
1416
+ metrics, commits the three metrics files and opens their PR, then records
1417
+ `fleet-heartbeat.mjs --stop` last, because every reader takes a recorded
1418
+ stop as the end of the run. A `NEED tier-outcomes append <pr>` is a PR
1419
+ the ledger marks reviewed with no verdict row: append it with the verdict
1420
+ you rule (**Guard: accumulate per PR**) and run `finish` again. A step it
1421
+ fails is explained in references/close-out.md. Exit 0 is the run closed.
1824
1422
  - **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
1825
1423
  it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
1826
1424
  ticket's ledger row, which outlives your context: `ledger.mjs token <key>
@@ -2001,8 +1599,8 @@ depth** guard table applied in code. Act on each line as it reads:
2001
1599
  paths yourself, and never re-baseline over paths nobody has resolved. The
2002
1600
  changes of yours that trip it are a mid-run tooling fix edited in this
2003
1601
  checkout and the close-out commit's round trip through a branch; **Fix the
2004
- tooling mid-run** and **Commit the metrics files and open a PR — at end of
2005
- run** say how each is cleared.
1602
+ tooling mid-run** and the commit section of references/close-out.md say how
1603
+ each is cleared.
2006
1604
  - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
2007
1605
  could not look: a git or hash read failed (`could not look:`), or the
2008
1606
  baseline exists but cannot be read (`baseline unreadable:`). Never clean,
@@ -3139,14 +2737,18 @@ all.
3139
2737
  > with `reason` `false-rationale` and filed on the closed suggestion-band
3140
2738
  > record.
3141
2739
  >
3142
- > Then report to the controller the pushed SHA, your apply/defer split, how
3143
- > many refuters you dispatched against out-of-scope suggestions, and
3144
- > the deferral issue numbers — a `filed: #N <subject>` line for every issue
3145
- > step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
3146
- > failed twice — and exit. **Deferring everything is a normal
2740
+ > Then write your report to the file your brief names,
2741
+ > `<scratch>/reports/<your name>.json`: `head` the pushed SHA, `applied` and
2742
+ > `deferred` your apply/defer split by bucket and index, each deferral's issue
2743
+ > number on its `deferred` entry, the deferral issues as `{issue, subject}`
2744
+ > entries — `filed` for every issue step 5 created, and `unrecorded` for one
2745
+ > whose `ledger.mjs filed` failed twice, which the controller's settle records —
2746
+ > `dispositionsRecord` your record's path and `testRun` your test result. Then
2747
+ > send the one line your brief gives, `<your name>: <outcome> <path>`, and exit.
2748
+ > **Deferring everything is a normal
3147
2749
  > outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
3148
- > index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
3149
- > report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
2750
+ > index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and your
2751
+ > report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
3150
2752
  > explicitly — silence there is indistinguishable from a member that died. Never
3151
2753
  > manufacture a commit to make CI fire.
3152
2754
 
@@ -4385,6 +3987,24 @@ live count from it, so nobody states one. Write neither by hand:
4385
3987
  row as its own. `settle impl-N=PR#M` refuses a settle after which a PR maps
4386
3988
  to more than one row when it did not before, judged after the fold — a PR
4387
3989
  has one row, the PR's row; a split already on disk is carried.
3990
+ - **`ledger.mjs settle <member> --from-report [--reports <dir>]`** — the
3991
+ settle for a member that wrote a report: reads `<dir>/<member>.json`
3992
+ (`<dir>` defaults to `<scratch>/reports`), derives the outcome from it and,
3993
+ before writing, checks what that outcome claims — `PR#M`: `verify-sha.sh`
3994
+ on the report's branch and head, and PR M OPEN and closing N; `bailed`: a
3995
+ `bailCause`, which the receipt names; `applied:<head>`: origin's branch at
3996
+ that head; `no-op`: origin's branch at the head the PR's latest
3997
+ `reviewed=` names; `labelled`: `ready-to-merge` on the PR and in the
3998
+ read-back; `halted:<cause>`: a cause and non-empty evidence; `done`: every
3999
+ PR the bot merged reads MERGED. It then records each `unrecorded` filing in
4000
+ **filed** and, for a fix-applier, each refutation the report defers in
4001
+ **ruled**, once however often it runs, and prints `{member, outcome,
4002
+ checks, filed, ruled}`. Exit 3: a check failed — the member's claim and the
4003
+ world disagree — and nothing is written; you rule. Exit 2: the report is
4004
+ absent or invalid, or a check could not look, and nothing is written; a
4005
+ check that could not look is run again once `gh` and `git` answer. The bare
4006
+ form above, for an outcome a report carries, warns `settled without
4007
+ --from-report` on stderr.
4388
4008
  - **`ledger.mjs review <pr> <token>…`** — the only writer of `review=` and
4389
4009
  `reviewed=` (below): appends each to the PR's row — the ticket row once
4390
4010
  `settle impl-<N>=PR#M` has run, else `#M`, created when neither exists —
@@ -4472,7 +4092,8 @@ Plus two append-only lists:
4472
4092
  one, not you: `review-and-fix.md` step 5 and finisher duty 2 each run `filed`
4473
4093
  immediately after their own `gh issue create`, with the subject they passed
4474
4094
  to `check`, and report `filed: #N <subject>`. A filer whose `filed` failed
4475
- twice reports `unrecorded: #N <subject>` instead, and you run `filed` for it.
4095
+ twice reports `unrecorded: #N <subject>` instead — an `unrecorded` entry of
4096
+ its report file — and `settle <member> --from-report` runs `filed` for it.
4476
4097
  - **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
4477
4098
  so a replacement controller does not re-litigate a settled call.
4478
4099