@feigi/fleet-ctl 3.137.5 → 3.138.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.
Files changed (52) hide show
  1. package/agents/fleet-finisher.agent.md +8 -8
  2. package/agents/fleet-fix-applier.agent.md +1 -1
  3. package/agents/fleet-merge-bot.agent.md +1 -1
  4. package/agents/fleet-recipe-deriver.agent.md +5 -5
  5. package/agents/fleet-review-runner.agent.md +1 -1
  6. package/commands/review-and-fix.md +11 -11
  7. package/commands/run-merge-bot.md +9 -9
  8. package/package.json +1 -1
  9. package/scripts/claim-ticket.sh +15 -1
  10. package/scripts/controller-alarm.mjs +1 -1
  11. package/scripts/evict-mark.mjs +1 -1
  12. package/scripts/finisher-audit.mjs +1 -1
  13. package/scripts/finisher-label.mjs +1 -1
  14. package/scripts/finisher-tree.mjs +1 -1
  15. package/scripts/fleet-provenance +9 -52
  16. package/scripts/fleet-run +5 -10
  17. package/scripts/fleet-tick.mjs +3 -3
  18. package/scripts/instruments.sh +3 -4
  19. package/scripts/ledger.mjs +1 -1
  20. package/scripts/main-checkout.mjs +1 -1
  21. package/scripts/phase0-receipt.mjs +1 -1
  22. package/scripts/preflight.mjs +0 -1
  23. package/scripts/recipe-check.mjs +1 -1
  24. package/scripts/release-ticket.sh +16 -0
  25. package/scripts/repo-root.mjs +1 -1
  26. package/scripts/report-schema.mjs +1 -1
  27. package/scripts/review-core.mjs +6 -6
  28. package/scripts/review-eval.mjs +1 -1
  29. package/scripts/ticketless.mjs +1 -1
  30. package/scripts/worktree.sh +46 -0
  31. package/skills/next-ticket/SKILL.md +8 -8
  32. package/skills/run-team/SKILL.md +22 -34
  33. package/skills/run-team/briefs/finisher.md +2 -2
  34. package/skills/run-team/briefs/fix-applier.md +9 -9
  35. package/skills/run-team/briefs/implementer.md +3 -3
  36. package/skills/run-team/briefs/merge-bot.md +2 -2
  37. package/skills/run-team/references/ci-and-staleness.md +1 -1
  38. package/skills/run-team/references/ci-watcher.md +1 -1
  39. package/skills/run-team/references/close-out.md +5 -5
  40. package/skills/run-team/references/failure-handling.md +2 -2
  41. package/skills/run-team/references/finisher.md +2 -2
  42. package/skills/run-team/references/instruments.md +1 -1
  43. package/skills/run-team/references/isolation.md +3 -3
  44. package/skills/run-team/references/ledger.md +1 -1
  45. package/skills/run-team/references/member-lifecycle.md +1 -1
  46. package/skills/run-team/references/phase-0.md +20 -20
  47. package/skills/run-team/references/pull.md +18 -10
  48. package/skills/run-team/references/reaping.md +15 -1
  49. package/skills/run-team/references/reviewers.md +9 -1
  50. package/skills/run-team/references/tick-rows.md +2 -2
  51. package/skills/sizing-a-ticket/SKILL.md +1 -1
  52. package/scripts/fleet-bootstrap +0 -140
@@ -65,7 +65,7 @@ metrics and docs THIS run builds on and nothing pulls them.
65
65
  ## Pin the instruments
66
66
 
67
67
  **Pin the instruments, after that fast-forward and before anything reads
68
- them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
68
+ them, from this main checkout.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run instruments.sh --pin`
69
69
  records what the scripts and runbooks of the Install root — the tree the
70
70
  fleet executes — say right now, which is what every later gate compares
71
71
  against; SKILL.md's **Re-check before you act on any instrument reading** says
@@ -83,7 +83,7 @@ differ. Never dispatch a member into a run whose phase-0 pin refused.
83
83
  ## Record the main-checkout baseline
84
84
 
85
85
  **Record the main-checkout baseline in the same step, right after the
86
- pin.** `~/.fleet/bin/fleet-run main-checkout.mjs --record` writes
86
+ pin.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record` writes
87
87
  `.fleet/main-checkout.sha`: the main checkout's `git status --porcelain
88
88
  -uall` entries plus a content hash of every path they name, and its HEAD —
89
89
  symbolic ref and commit. Your own
@@ -117,7 +117,7 @@ and before the pre-flight.** The **Label map** (`.fleet/labels.json`) gives
117
117
  the string this repository's tracker uses for each Label role:
118
118
  `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`,
119
119
  `wontfix`, `in-progress`, `onhold`, `ready-to-merge`. The `labels` step runs
120
- `~/.fleet/bin/fleet-run label-map.mjs ensure` in this main checkout, which
120
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs ensure` in this main checkout, which
121
121
  reads the cached map, the repository's triage-label table and the tracker's
122
122
  live label list, on every call, and never creates a label.
123
123
  This step is yours, once per run start: a member never derives the map and
@@ -164,7 +164,7 @@ want otherwise — a role with no suggestion must be named; labels that do not
164
164
  exist are created on your confirmation.
165
165
 
166
166
  **Write the answer, say how to keep it, run phase 0 again.** Run
167
- `~/.fleet/bin/fleet-run label-map.mjs set --create` with the reply:
167
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs set --create` with the reply:
168
168
  `--accept-suggestions` for `defaults`, and each `<role>=<label>` the
169
169
  maintainer named. Exit 0 prints the map it wrote; exit 1 is a refusal naming
170
170
  the role and the rule, nothing written and nothing created — put it to the
@@ -181,10 +181,10 @@ the maintainer what it printed and stop, as for a failed `labels` step.
181
181
  ## Run the pre-flight
182
182
 
183
183
  **Run the pre-flight, once the pin and the baseline are recorded.**
184
- `~/.fleet/bin/fleet-run preflight.mjs` checks what this machine and this
184
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run preflight.mjs` checks what this machine and this
185
185
  repository must give the fleet — the binaries, `gh` auth, `origin/main`,
186
186
  `.worktrees/` and `.fleet/` ignored, merge commits on, a
187
- ruleset, the Resolver — and prints one `ok`, `WARN` or `FAIL` line per
187
+ ruleset — and prints one `ok`, `WARN` or `FAIL` line per
188
188
  check, each naming its check. **Exit 1 stops the run:** no shortlist, no
189
189
  dispatch. Report every `FAIL` line to the maintainer by its check's name;
190
190
  the run starts again once they are fixed. Exit 2 means it could not run at
@@ -227,7 +227,7 @@ person choosing to.
227
227
 
228
228
  **Drain the pending ticket-features rows and refresh the cost guard, after
229
229
  the fast-forward and before the first Pull is routed.**
230
- `~/.fleet/bin/fleet-run metrics-refresh.mjs` moves
230
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run metrics-refresh.mjs` moves
231
231
  `.fleet/ticket-features.pending.tsv` into `docs/metrics/ticket-features.tsv`,
232
232
  deduped on `session`+`agent` — this recovers the rows of a run that crashed
233
233
  before its close-out — and then runs `pr-cost.mjs --guard`, rewriting
@@ -253,7 +253,7 @@ line leaves the exit at 0, so it never stops the run.
253
253
  ## Launch the cockpit
254
254
 
255
255
  **Launch the cockpit.** On every phase-0 pass, not just the first:
256
- `node ~/.fleet/bin/fleet-run board.mjs serve --open &` in the
256
+ `node ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run board.mjs serve --open &` in the
257
257
  background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
258
258
  feed or update it, and it survives your own compaction. The launch is
259
259
  idempotent per workspace when the running cockpit answers the identity
@@ -295,7 +295,7 @@ it and nothing signals its pid.
295
295
 
296
296
  **Rotate the ledger before the fold-in below and before shortlisting —
297
297
  every run, whatever way the previous one ended.** One ledger per run:
298
- `~/.fleet/bin/fleet-run ledger.mjs rotate` moves the previous run's
298
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs rotate` moves the previous run's
299
299
  `.fleet/ledger.md` byte-for-byte to `.fleet/ledger.<UTC
300
300
  YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind. What it carries forward
301
301
  turns on the verdict it reaches below. After `dead` or `none` nothing is
@@ -391,7 +391,7 @@ Before the rotation, `phase0.mjs` puts the held-aside receipt (`phase0.previous.
391
391
  ## Reclaim scratch
392
392
 
393
393
  **Reclaim scratch straight after the rotation — every run.**
394
- `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch>
394
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --root <scratch>
395
395
  --after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
396
396
  so a run that merges nothing still reclaims the previous run's leftovers
397
397
  (`reclaim-scratch.mjs`'s header says what it removes).
@@ -410,7 +410,7 @@ its reason — and exits 0 even when a removal failed; record nothing on the
410
410
  ledger.
411
411
 
412
412
  Straight after that, the same step reclaims the other keys under the scratch parent:
413
- `~/.fleet/bin/fleet-run reclaim-scratch.mjs --siblings --root <scratch> --apply`. A key
413
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --siblings --root <scratch> --apply`. A key
414
414
  goes whole when nothing under it has changed in 7 days, and stays whole otherwise. The
415
415
  call runs whatever the root sweep answered, and records nothing on the ledger. A non-zero
416
416
  exit, and each path its receipt's `failed[]` names, is listed in the step's output; neither
@@ -419,7 +419,7 @@ stops the run.
419
419
  ## Evict idle claim trees
420
420
 
421
421
  **Evict straight after the reclaim — every run.**
422
- `~/.fleet/bin/fleet-run evict.mjs --after-rotate --apply` is phase 0's own
422
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --after-rotate --apply` is phase 0's own
423
423
  `evict` step. A claim tree with neither a HEAD move nor a restore in 7 days loses
424
424
  every path git ignores in it but its `agent-test` runner; the claim, its tree,
425
425
  its branch and its commits stay (`evict.mjs`'s header says what keeps a tree).
@@ -434,7 +434,7 @@ straight after its reclaim, and reports it on an `APPLIED evict:` or
434
434
  **An evicted tree is restored before a member runs code there.**
435
435
  `dispatch-prompt.mjs render implementer` and `render fix-applier` refuse a
436
436
  worktree evict.mjs marked, naming
437
- `~/.fleet/bin/fleet-run evict.mjs --restore <tree> --apply`: run it, then render
437
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --restore <tree> --apply`: run it, then render
438
438
  again. It runs the Install step in the tree as a claim does and refuses as a
439
439
  claim does. A refused restore leaves the tree evicted: dispatch nothing into
440
440
  it, report the restore's message, and the row comes up again on the next wake.
@@ -448,9 +448,9 @@ and before the first claim.** Every claim runs this repository's Install
448
448
  step and bakes its Test entrypoint into the member's runner, and every
449
449
  review reads the Test entrypoint, all out of the **Recipe cache**
450
450
  (`.fleet/recipe.json` beside the common git dir); no script infers either
451
- command. Check it first: `~/.fleet/bin/fleet-run derive-testcmd.sh .
452
- install --at origin/main`, `~/.fleet/bin/fleet-run derive-testcmd.sh . check
453
- --at origin/main` and `~/.fleet/bin/fleet-run derive-testcmd.sh . test --at
451
+ command. Check it first: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh .
452
+ install --at origin/main`, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check
453
+ --at origin/main` and `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . test --at
454
454
  origin/main`. **All three exit
455
455
  0 → the cache is present and valid: use it as it stands and derive
456
456
  nothing.** Any exits 1 (a refusal about the cache) → derive it; a refusal
@@ -461,7 +461,7 @@ unknown: fix that environment fault and check again; deriving would not
461
461
  help. This step is yours: one derivation
462
462
  per run start at most, never one per member, and a member never derives.
463
463
  Dispatch a `task` member named `derive-recipe`, agent
464
- `fleet-recipe-deriver`, its prompt the brief `~/.fleet/bin/fleet-run
464
+ `fleet-recipe-deriver`, its prompt the brief `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run
465
465
  dispatch-prompt.mjs render recipe-deriver --member derive-recipe --repo <repo>
466
466
  --scratch <scratch>` prints, and wait for its report — nothing in this run can
467
467
  claim before it lands. `<repo>` is this main checkout's absolute path and
@@ -481,7 +481,7 @@ PROVEN`** → re-run the three reads above (`derive-testcmd.sh . install --at or
481
481
  their output is the Recipe this run uses. **`RECIPE NOT PROVEN`** →
482
482
  stall, below.
483
483
 
484
- **Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.fleet/bin/fleet-run derive-testcmd.sh . check` prints it. Pass it to the fix-applier beside `testCmd`; the review does not run it. Neither member runs the two by hand: `recipe-check.mjs` runs the Check step it reads off that cache, then the `testCmd` it is handed, on the member's staged tree, and writes the record `ledger.mjs settle --from-report` requires of an implementer's and a fix-applier's report.
484
+ **Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check` prints it. Pass it to the fix-applier beside `testCmd`; the review does not run it. Neither member runs the two by hand: `recipe-check.mjs` runs the Check step it reads off that cache, then the `testCmd` it is handed, on the member's staged tree, and writes the record `ledger.mjs settle --from-report` requires of an implementer's and a fix-applier's report.
485
485
 
486
486
  **Mid-run, a cache that stops running is re-derived once, then the run
487
487
  stalls.** A claim or a review that refuses because the Recipe cache is
@@ -542,7 +542,7 @@ push, and rotation after a dead run carries no row forward, the candidate
542
542
  scan excludes `in-progress`, and the in-flight check reads the worktree as
543
543
  taken — so a
544
544
  claim the previous run left without a PR is held by nobody until this step
545
- names it. `~/.fleet/bin/fleet-run stranded.mjs` lists and classifies; you
545
+ names it. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run stranded.mjs` lists and classifies; you
546
546
  dispatch. It reads the `prior` rotate just recorded, never the record
547
547
  itself, which names this run's own live controller, and prints
548
548
  `{prior, claims: [{n, t, action, worktree, branch, why}], carried: [{name,
@@ -622,7 +622,7 @@ stranded.
622
622
 
623
623
  ## Build the Shortlist
624
624
 
625
- 1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
625
+ 1. **Build the Shortlist** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run shortlist.mjs`, then read
626
626
  `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
627
627
  — no ticket body is read here, because a Pull reads one ticket in full at
628
628
  the moment it admits it:
@@ -16,7 +16,7 @@ terminating in exactly one dispatch or an empty shortlist:
16
16
  1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
17
17
  `impl-` row and no `excluded` row whose premise still holds, which is the
18
18
  ticket the tick's `PULL` row names.
19
- 2. **In-flight check, again** — `~/.fleet/bin/fleet-run inflight.sh <N>`; any
19
+ 2. **In-flight check, again** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run inflight.sh <N>`; any
20
20
  hit = taken, drop it and take the next entry. The shortlist is as old as its
21
21
  last refresh. It runs all three probes (PRs, remote heads, local
22
22
  worktrees + branches) so a partial one cannot read as free. The PR probe is
@@ -166,7 +166,7 @@ terminating in exactly one dispatch or an empty shortlist:
166
166
  `origin/main`, the fatal-not-empty case above.
167
167
 
168
168
  **`staleness.mjs` runs that check for you, and answers in THREE values.**
169
- `~/.fleet/bin/fleet-run staleness.mjs --path <path> --gone
169
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run staleness.mjs --path <path> --gone
170
170
  '<string>'`, or `--present '<string>'`, once per claim the ticket makes.
171
171
  It goes here and not in `shortlist.mjs` because choosing WHICH string
172
172
  settles a ticket needs the ticket read, which the step above already did —
@@ -245,9 +245,9 @@ terminating in exactly one dispatch or an empty shortlist:
245
245
  scope` `#N` refs as candidates: `clear`; `behind-pr:#M`, an open PR or a
246
246
  branch with no PR yet by its name; `behind-issue:#M`, an open issue that
247
247
  section sequences this one after; or `paths <p>…`, which scans again.
248
- 6. **Claim** — `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer
248
+ 6. **Claim** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run claim-ticket.sh <N> impl-<N> implementer
249
249
  --apply` (below). Exit 2 → treat it as taken, next entry.
250
- 7. **Route, row, then dispatch** — `~/.fleet/bin/fleet-run ticket-router.mjs route
250
+ 7. **Route, row, then dispatch** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ticket-router.mjs route
251
251
  --session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
252
252
  <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints the Pull's
253
253
  Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… PARENT=… SIZED=… OBJECTIVE=… TRIPPED=… REASON=…`
@@ -320,8 +320,8 @@ the stranded comment's heading line and URL, which is not one of the
320
320
  `briefs/relabel.md` comments.
321
321
  `gh issue edit <N> --remove-label "<ready-for-agent string>" --add-label "<label string>"` (no
322
322
  `in-progress` to drop — it was never claimed), preceded by exactly one comment,
323
- the one `~/.fleet/bin/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
324
- prints. Each `<… string>` is what `~/.fleet/bin/fleet-run label-map.mjs show <role>` prints for that role — `<label string>` for the role the cause names — and you type that string, not the role name; where the rendered comment names `ready-for-agent`, file the string `~/.fleet/bin/fleet-run label-map.mjs show ready-for-agent` prints in its place. `--kind needs-triage` takes `--line`, the one-line missing decision;
323
+ the one `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
324
+ prints. Each `<… string>` is what `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show <role>` prints for that role — `<label string>` for the role the cause names — and you type that string, not the role name; where the rendered comment names `ready-for-agent`, file the string `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run label-map.mjs show ready-for-agent` prints in its place. `--kind needs-triage` takes `--line`, the one-line missing decision;
325
325
  `--kind fork` takes `--options`, the options verbatim from the brief, and is
326
326
  the `ready-for-human` comment for a fork; `--kind hands` takes `--hands`,
327
327
  one of external access, manual testing or judgment during the work, and
@@ -356,7 +356,7 @@ read that way: `gh pr view` finds no PR for the branch, so it is exit 2, not a
356
356
 
357
357
  ## Claiming
358
358
 
359
- **Claiming.** `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
359
+ **Claiming.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
360
360
  the label, worktree, branch, the Recipe's Install step, the clean-tree assertion, and the
361
361
  isolation runner in one serial pass. The two arguments are always that literal
362
362
  pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
@@ -396,9 +396,9 @@ a worktree, a branch and an `in-progress` label with no member behind them,
396
396
  released by the end-of-run sweep rather than by a member that did the work.
397
397
 
398
398
  **Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
399
- the Pull's step 7; `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
399
+ the Pull's step 7; `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run dispatch-prompt.mjs render
400
400
  implementer --member impl-<N> …` then renders its brief, and
401
- `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
401
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ledger.mjs dispatch <N> impl-<N>`
402
402
  marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
403
403
  Its JSON carries `agent`, the definition that call names, and `brief.path`,
404
404
  the rendered brief whose content is that call's prompt — read both off that
@@ -660,7 +660,7 @@ floor to a count on stderr.
660
660
 
661
661
  ## A Pull's entry and exits, in full
662
662
 
663
- A Pull's entry is `~/.fleet/bin/fleet-run pull.mjs next --head <N>`, run from the
663
+ A Pull's entry is `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run pull.mjs next --head <N>`, run from the
664
664
  main checkout (without `--head`, the next shortlist entry). It runs the
665
665
  mechanical steps in order and stops at each judgement with a `QUESTION
666
666
  <qid>:` block and exit 10; `pull.mjs answer <N> <qid> <token> [--path <p>] [--]
@@ -680,3 +680,11 @@ one scan, oldest first; admission never is. The invariant this replaces — one
680
680
  human decision per batch of admissions, zero unilateral grabs — is retired
681
681
  is retired: zero human decisions per admission, and every non-admission is a
682
682
  label or a premise the maintainer can read.
683
+
684
+ ## Red flags: is it decided
685
+
686
+ - "Touches eight files, too big for the fleet" → size is not the axis. Decided is.
687
+ - "Body is three lines, so it's simple" → short bodies hide open design choices.
688
+ - "The brief is thorough, so it's decided" → thorough ≠ decided. Read it for the
689
+ choice it leaves open.
690
+ - "I'd have to pick an approach myself" → that IS undecided.
@@ -72,6 +72,8 @@ So nothing in the run cleans it up. Next run, the in-flight probe's local-worktr
72
72
 
73
73
  **A checkout that lands between that fresh check and the delete halts the release after it.** `git worktree add` of an existing branch does not move the ref, so the compare-and-swap succeeds under it. The same `wt_recheck_delete` reap uses then finds the worktree, recreates the branch at the tip, and the release halts with exit 2, `released:false` and a blocker naming that worktree — the shape of a holder caught before the delete. A restore that fails halts the same way, with the tip and the repair command in the blocker.
74
74
 
75
+ **The branch's config section goes after the delete, as reap's does.** `git update-ref -d` removes the ref and not `[branch "<name>"]`; a later claim of the same name would inherit the dead upstream and read `[gone]` at once. worktree.sh's `wt_clear_branch_config` removes it; a claim that never pushed has none, which is not a fault, and a section that cannot be removed is a note on stderr, never a halt — the ref is already deleted. claim-ticket.sh `--apply` clears the same section before `git worktree add`, since whatever deleted the branch, config under a name no branch holds is leftover; there, a section that cannot be removed refuses the claim.
76
+
75
77
  **`worktree remove` without `--force`** refuses on modified and untracked files and deletes ignored files silently (verified, git 2.50.1). Ignored-silently is what is wanted: `claim-ticket.sh` writes an `agent-test` into each fresh worktree it claims of a repository that tracks none, and ignores it through the repository's exclude file, so treating ignored files as dirt would strand every such release. The same asymmetry is why a claim never writes over a tracked `agent-test`: that write would leave a modified tracked path, which this refusal does not forgive. Its refusal is the dirty check recomputed by git at the moment of the delete — for the live-directory case ONLY. `worktree remove` gates that clean check on the same `stat` the guard does, so it is not an independent second opinion: where the path cannot be stat'ed git reaches the same "gone" by the same means, accepts the entry at rc 0 and deregisters a worktree whose files are still on disk (measured, git 2.50.1: an untracked file in a worktree under a `chmod 000` parent). There the `gone` guard is sole arbiter — which is why it establishes absence instead of inferring it from a failed `-e`, and why the fail-open fixed in `1e54bac` survived being reasoned about: guard and backstop fail on the same inputs.
76
78
 
77
79
  **A worktree that wandered off the branch blocks too.** The worktree is located by the branch it has checked out, and it does not stay there — an interrupted rebase leaves it detached, a member can switch it. The lookup then finds nothing, which reads as "no worktree of ours": the dirty check is skipped entirely and the release reports success while the worktree stands with the member's work in it, so the next run's probe still reads the ticket as taken. So a linked worktree at `claim-ticket.sh`'s `.worktrees/<issue>-<slug>` that is *not* on the branch is its own blocker — which remedy it names is the next paragraph, and is not always a hand-release. The path is read as the whole rest of the `worktree list --porcelain` line, never the first whitespace field, or every checkout under a directory with a space in its name reads as a different path.
@@ -89,4 +91,16 @@ fix-pr PR#<pr>` (**The fix-applier**).
89
91
 
90
92
  ## Never reap a branch a live member is on
91
93
 
92
- Cross-check `.fleet/ledger.md` before running: row without terminal state means someone may still be in that worktree — merged PR can still have reviewer filing follow-ups. Dirty check does not see member that committed but not pushed. Update reaped tickets' ledger rows in same step, report reaped and kept counts. Kept-with-reason is half worth reading.
94
+ Cross-check `.fleet/ledger.md` before running: row without terminal state means someone may still be in that worktree — merged PR can still have reviewer filing follow-ups. Dirty check does not see member that committed but not pushed. Update reaped tickets' ledger rows in same step, report reaped and kept counts. Kept-with-reason is half worth reading.
95
+
96
+ ## Red flags: reaping and removing a worktree
97
+
98
+ - "The reap at the end will pick up the claim I never dispatched" → it declines:
99
+ not `[gone]`, no unique commits. Release it, or it reads as taken next run.
100
+ - "`commit-commands:clean_gone` printed nothing, the tree is clean" → its
101
+ `[gone]` detection works fine; it just runs `-D`/`--force` with no merged
102
+ check, so "printed nothing" only means nothing was gone yet, not that it's safe.
103
+ - "`--force` the worktree removal, the PR merged anyway" → merged says nothing
104
+ about uncommitted files, and the reviewer may still be in there.
105
+ - "Reap once at the end of the run" → stale worktrees make phase 0 read merged
106
+ tickets as taken, so the starvation compounds with every Pull.
@@ -96,7 +96,7 @@ reads gates and never injects a fault.
96
96
  the worktree from. Pass it as `--branch`, because
97
97
  the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
98
98
  with `--detach`, and there `git branch --show-current` prints nothing and exits 0
99
- (measured 2026-09-18, git 2.50.1), so `~/.fleet/bin/fleet-run push-sync.mjs
99
+ (measured 2026-09-18, git 2.50.1), so `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs
100
100
  --branch "$(git branch --show-current)"` is handed an empty branch and exits 2
101
101
  before pushing anything. A brief rendered without it would leave the push no
102
102
  destination at all, which is why the renderer requires it.
@@ -229,3 +229,11 @@ retry letter's when there are several), so you pass no `--sizing`; the member
229
229
  also puts it in the PR body's `Sizing:` line, with the signal it turned on;
230
230
  `profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
231
231
  diff.
232
+
233
+ ## What a shared snapshot did to its readers
234
+
235
+ `review-and-fix.md`'s **Cut TWO trees, not one** rests on this. Observed with a single shared snapshot: three specialists read two *different* in-flight mutations, one reporting the PR's own bug as still present; elsewhere three watched their file go clean → `M` mid-analysis; twice a reviewer came one step from filing a false finding.
236
+
237
+ ## What an unbounded read costs
238
+
239
+ `review-and-fix.md`'s **Then bound the read** rests on this. The cost of not bounding is never one-off: a specialist that dumps a 37 KB file carries it in its prefix for every remaining turn, re-billed as cache-read on each. Over one run's 92 subagents the 88 unpiped whole-file calls carried 434 KB (~110k tokens) — the single largest attributed line item in that run — against 319 piped ones. Agents already reach for the bounded form; nothing told them when it is required.
@@ -143,7 +143,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
143
143
  when HEAD moved, and every live member; it
144
144
  attributes nothing, because concurrent members make that a guess. Dispatch
145
145
  nothing new and tell the maintainer: they resolve the stray paths FIRST,
146
- then re-baseline with `~/.fleet/bin/fleet-run main-checkout.mjs --record`.
146
+ then re-baseline with `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record`.
147
147
  A path entry holds until that re-baseline, tick after tick; a `HEAD …` entry
148
148
  clears itself once HEAD reads clean again, and is never re-baselined while
149
149
  HEAD is off the run's branch. Never revert the
@@ -164,7 +164,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
164
164
  resolve any stray paths, which the line does not name; only then re-record.
165
165
  - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
166
166
  baseline was recorded. Yours to fix: run
167
- `~/.fleet/bin/fleet-run main-checkout.mjs --record`, which references/phase-0.md
167
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record`, which references/phase-0.md
168
168
  describes under "Record the main-checkout baseline". A baseline
169
169
  that vanished mid-run is not a fresh run — report it to the maintainer
170
170
  before recording over whatever the tree now holds.
@@ -17,7 +17,7 @@ Read first: `gh issue view <N> --json title,body,comments --jq '.title, .body, (
17
17
  | **light** | States exactly what to change, one-two files, no design choice open | Test first, make the one change, run it with the repo's test runner |
18
18
  | **heavy** | Ambiguity in *what* to build, >~3 files, new API/schema/UX, or several viable approaches | Write a short plan, then carry it out inline, test first |
19
19
 
20
- **Fleet member on heavy: write the plan under your own scratch path, `<scratch>/impl-<N>/` (`<scratch>` is the path your dispatch prompt names; with no dispatcher, the output of `~/.fleet/bin/fleet-run scratch-root.mjs`), then carry it out inline, test first.**
20
+ **Fleet member on heavy: write the plan under your own scratch path, `<scratch>/impl-<N>/` (`<scratch>` is the path your dispatch prompt names; with no dispatcher, the output of `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run scratch-root.mjs`), then carry it out inline, test first.**
21
21
  Heavy is never a reason to give up: a `ready-for-agent` ticket's `## Agent Brief`
22
22
  already settles the open design choices, so plan from it. Solo session has a user:
23
23
  settle the open design choices with them before planning.
@@ -1,140 +0,0 @@
1
- #!/usr/bin/env node
2
- // The Resolver's one-time bootstrap. Places a copy
3
- // of `fleet-run` at `~/.fleet/bin/fleet-run` — the one artefact this repo
4
- // owns OUTSIDE the plugin, because the Resolver cannot resolve itself and no
5
- // per-session mechanism can carry it (nothing survives between harness
6
- // Bash-tool calls). Idempotent: re-running reports "unchanged" once the
7
- // placed copy already matches.
8
- //
9
- // SOURCE, and the one licensed exception. Every other script's rule is
10
- // "only installed scripts run" — never a source checkout.
11
- // This script's source is always ITS OWN sibling `fleet-run`, i.e. whatever
12
- // directory this file itself is running from. Two shapes exist for that:
13
- // - run as an INSTALLED script (this file's own directory IS a registry
14
- // installPath's scripts/ — the steady state, e.g. invoked as
15
- // `fleet-run fleet-bootstrap` once a Resolver already exists), or
16
- // - run DIRECTLY FROM A CHECKOUT (this file's own directory is not any
17
- // registered installPath) — the state the world is actually in the
18
- // first time this ever runs, since no install anywhere yet carries
19
- // `scripts/fleet-run`. This exception is licensed exactly once, loudly.
20
- // This file cannot tell those apart by calling git (that would be exactly
21
- // the self-location-derives-a-repo pattern every other script is barred from); it
22
- // tells them apart by comparing its own directory's PARENT against the
23
- // registries' recorded installPath strings — a plain string compare, no git
24
- // involved, so it never anchors a git root to its own location.
25
- "use strict";
26
-
27
- const fs = require("node:fs");
28
- const path = require("node:path");
29
- const os = require("node:os");
30
- const crypto = require("node:crypto");
31
-
32
- const NAME = "fleet-bootstrap";
33
-
34
- function die(message) {
35
- process.stderr.write(`${NAME}: ${message}\n`);
36
- process.exit(2);
37
- }
38
-
39
- // The Install root, same resolution point as scripts/fleet-run:
40
- // the realpath of `~/.omp/plugins/node_modules/@feigi/fleet-ctl`. Absent or
41
- // dangling answers null, which the caller reports as "omp: not installed".
42
- function readInstallPath(packagePath) {
43
- try {
44
- return fs.realpathSync(packagePath);
45
- } catch {
46
- return null;
47
- }
48
- }
49
-
50
- function sha256(buf) {
51
- return crypto.createHash("sha256").update(buf).digest("hex");
52
- }
53
-
54
- function main() {
55
- const argv = process.argv.slice(2);
56
- const fromCheckoutFlag = argv.includes("--from-checkout");
57
-
58
- const ownDir = __dirname;
59
- const source = path.join(ownDir, "fleet-run");
60
-
61
- let sourceBuf;
62
- try {
63
- sourceBuf = fs.readFileSync(source);
64
- } catch (e) {
65
- die(`cannot read ${source} — bootstrap copies fleet-run from its OWN directory and found nothing there (${e.code || e.message})`);
66
- }
67
-
68
- const home = os.homedir();
69
- const PLUGIN_KEY = "@feigi/fleet-ctl"; // the plugin's package name, and its node_modules package dir.
70
- const ompInstall = readInstallPath(path.join(home, ".omp", "plugins", "node_modules", PLUGIN_KEY));
71
- // Both sides are realpaths — readInstallPath() already resolved the install,
72
- // and this file's own directory exists, so its parent resolves too — so a
73
- // path reached through a symlink (macOS /tmp → /private/tmp) compares equal.
74
- const parent = fs.realpathSync(path.dirname(ownDir));
75
- const runningFromInstall = parent === ompInstall;
76
-
77
- const target = path.join(home, ".fleet", "bin", "fleet-run");
78
-
79
- // The exception is opt-in, not merely announced: a stray checkout run
80
- // (a wrong branch, a stale worktree) must not silently overwrite the one
81
- // artefact outside the plugin. Every steady-state invocation — through
82
- // the Resolver, once it exists — runs from an install and never needs
83
- // this flag at all.
84
- if (!runningFromInstall && !fromCheckoutFlag) {
85
- die(
86
- `refusing to place ${target} from ${ownDir}, which is not omp's resolved install root (looked at `
87
- + `${ompInstall ? `omp: ${ompInstall}` : "omp: not installed"}) — re-run with --from-checkout to take `
88
- + "the one-time bootstrap exception explicitly",
89
- );
90
- }
91
-
92
- if (!runningFromInstall) {
93
- process.stderr.write(
94
- `${NAME}: BOOTSTRAP EXCEPTION — running from a source checkout (${ownDir}), not omp's resolved `
95
- + "install root (looked at "
96
- + `${ompInstall ? `omp: ${ompInstall}` : "omp: not installed"}). `
97
- + "This is licensed ONCE, as the Resolver's own bootstrap, because no install anywhere yet carries "
98
- + "scripts/fleet-run for an install-root-driven copy to come from. Every other fleet script must run through "
99
- + "the Resolver once it exists.\n",
100
- );
101
- }
102
-
103
- fs.mkdirSync(path.dirname(target), { recursive: true });
104
-
105
- let existingBuf = null;
106
- try {
107
- existingBuf = fs.readFileSync(target);
108
- } catch {
109
- existingBuf = null;
110
- }
111
-
112
- const changed = existingBuf === null || !existingBuf.equals(sourceBuf);
113
- if (changed) {
114
- fs.writeFileSync(target, sourceBuf);
115
- }
116
- fs.chmodSync(target, 0o755);
117
-
118
- const sourceHash = sha256(sourceBuf);
119
- if (existingBuf === null) {
120
- process.stdout.write(`${NAME}: wrote ${target} (new, sha256 ${sourceHash})\n`);
121
- } else if (changed) {
122
- process.stdout.write(`${NAME}: wrote ${target} (changed: sha256 ${sha256(existingBuf)} -> ${sourceHash})\n`);
123
- } else {
124
- process.stdout.write(`${NAME}: unchanged — ${target} already matches ${source} (sha256 ${sourceHash})\n`);
125
- }
126
- process.stdout.write(`${NAME}: source ${source}\n`);
127
-
128
- const pathDirs = (process.env.PATH || "").split(path.delimiter);
129
- const binDir = path.dirname(target);
130
- if (pathDirs.includes(binDir)) {
131
- process.stdout.write(`${NAME}: PATH already includes ${binDir}\n`);
132
- } else {
133
- process.stdout.write(
134
- `${NAME}: PATH does not include ${binDir} — add it yourself if you want to run "fleet-run" bare `
135
- + `(e.g. add \`export PATH="${binDir}:$PATH"\` to your shell rc); this script edits no rc file\n`,
136
- );
137
- }
138
- }
139
-
140
- main();