@feigi/fleet-ctl 3.66.2 → 3.67.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
package/scripts/fleet-event.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// A
|
|
3
|
-
// the tick.
|
|
2
|
+
// A wake recorded as one command: the writes it owes, then the tick.
|
|
4
3
|
//
|
|
5
4
|
// fleet-event.mjs <kind> <args> [--in-flight <n>]
|
|
5
|
+
// fleet-event.mjs drain --reason "<reason>" [--in-flight <n>]
|
|
6
6
|
//
|
|
7
7
|
// Reached through the Resolver and run from the main checkout. Every kind
|
|
8
8
|
// performs its writes, then runs `fleet-tick.mjs --apply` with the In-flight
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
// settled, under any outcome, is not settled again.
|
|
19
19
|
//
|
|
20
20
|
// impl-report <impl-N[-x]>
|
|
21
|
-
// `ledger.mjs settle <member> --from-report
|
|
21
|
+
// `ledger.mjs settle <member> --from-report`, which runs `verify-sha.sh` and reads the PR itself. Settled `bailed`: the
|
|
22
22
|
// report's `bailCause` names the label (undecided `needs-triage`, fork
|
|
23
23
|
// and hands `ready-for-human`), then:
|
|
24
24
|
// `gh issue edit <N> --remove-label ready-for-agent --remove-label
|
|
@@ -35,6 +35,8 @@
|
|
|
35
35
|
// It runs on a second run too: it measures the claim again and
|
|
36
36
|
// writes nothing when nothing is left to release. A refusal prints
|
|
37
37
|
// `NEED hand-release #<N> <blocker>` and is never forced.
|
|
38
|
+
// Dropping `in-progress` is the load-bearing half: phase 1 applied it and `candidates.mjs` excludes it, so leaving it makes the ticket invisible to the controller's scans and the maintainer's. It does not loop; it disappears.
|
|
39
|
+
// `reap.sh` declines a claim that never became a PR, so the release of a bailed claim is `release-ticket.sh`'s.
|
|
38
40
|
// fix-report <fix-pr-M[-x]>
|
|
39
41
|
// `settle --from-report`, which records the filings and rulings the
|
|
40
42
|
// report carries. Settled `applied:`/`no-op`, on a PR whose rows carry
|
|
@@ -54,11 +56,15 @@
|
|
|
54
56
|
// whether or not its settle was accepted, since the settle refuses
|
|
55
57
|
// exactly that read-back. Either comment is skipped when the PR already
|
|
56
58
|
// carries it.
|
|
59
|
+
// A settle that refuses 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.
|
|
57
60
|
// merge-bot-report <merge-bot-n>
|
|
58
61
|
// `ledger.mjs token <pr> held-behind:#<behind>` for each `held[]` entry
|
|
59
62
|
// of the report the PR's rows do not already carry, then `settle
|
|
60
63
|
// --from-report`. The reap and the reclaim run under the tick's
|
|
61
64
|
// `--apply`.
|
|
65
|
+
// The verdict moves no label and leaves nothing in the repo, so the row is the only place the tick can read a `held-behind` from.
|
|
66
|
+
// The reap and the reclaim run once for every merge bot settled `done`, always, even when the pass merged nothing, and again on the next tick after an `APPLY FAILED` line, and on every tick while this run has no controller record to remember the pass by.
|
|
67
|
+
// The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in the same pass, before reporting: a token the bot wrote in that pass, never one `reap.sh` writes.
|
|
62
68
|
// review-result <pr> <path>
|
|
63
69
|
// The review result file at `<path>`, which must be
|
|
64
70
|
// `<scratch>/pr<pr>/<run>/<file>`, `<run>` a review run root
|
|
@@ -66,24 +72,68 @@
|
|
|
66
72
|
// `counts` make `ledger.mjs review <pr>
|
|
67
73
|
// reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`, skipped when
|
|
68
74
|
// the PR's rows already carry that token.
|
|
75
|
+
// The result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root.
|
|
69
76
|
// review-failed <pr> <launch>
|
|
70
77
|
// `ledger.mjs review <pr> review=<launch>=failed`, `<launch>` as the
|
|
71
78
|
// PR's row spells it after `review=` (`member:<runner>` or
|
|
72
79
|
// `wf:<runId>`), skipped when the rows already carry it; the summary
|
|
73
80
|
// names the runner the PR's next launch takes, as `review` reports it.
|
|
81
|
+
// ci <pr>
|
|
82
|
+
// `ci-state.mjs --pr <pr>`, never `--quiet`, then `ledger.mjs token <pr>
|
|
83
|
+
// ci=<run-id>:<attempt>:<conclusion>` on the PR's row, `<conclusion>`
|
|
84
|
+
// `-` when ci-state reports it as `""` or null (an in-progress run),
|
|
85
|
+
// skipped when the PR's rows already carry that token. The payload is
|
|
86
|
+
// the verdict, never the exit code: not-green exits 1 and is an
|
|
87
|
+
// ordinary state. A payload with no `verdict`, or `verdict:
|
|
88
|
+
// rate-limited`, prints `WATCHER DEGRADED: no usable ci-state reading
|
|
89
|
+
// for #<pr> — silence is NOT green` and writes nothing; a payload that
|
|
90
|
+
// binds no run (`no-ci`) writes nothing either.
|
|
91
|
+
// `token` appends the key to the PR's row and keeps every token already on it, where `row` would replace the whole line.
|
|
92
|
+
// That key cannot be reconstructed once the head is superseded, so a controller holding only the colour cannot later tell an edge it has already spent from one that never fired.
|
|
93
|
+
// label <pr>
|
|
94
|
+
// No write: a `ready-to-merge` label was seen, and the tick is the whole
|
|
95
|
+
// of the event.
|
|
96
|
+
// conflict <pr>
|
|
97
|
+
// The tick's `CONFLICT` line for the PR, recorded: `ledger.mjs token
|
|
98
|
+
// <pr> conflict-hold:#<pr>`, no note beside it (`token` refuses any
|
|
99
|
+
// `conflict-hold` word that is not `conflict-hold:#<number>`, spelled
|
|
100
|
+
// with `:` or `-`). `token` appends the hold and keeps every token the row already carries, where `row` would replace the whole line.
|
|
101
|
+
// Refused, nothing written, exit 2, when the PR's row already carries a
|
|
102
|
+
// hold no fix-applier has answered (the tick's own reading of the row),
|
|
103
|
+
// or both spellings. A row whose one hold a fix-applier answered takes
|
|
104
|
+
// the other spelling, `conflict-hold-#<pr>`: `token` writes no word the
|
|
105
|
+
// row already carries, and the tick reads a fresh hold after an answer
|
|
106
|
+
// as unresolved.
|
|
107
|
+
// heartbeat
|
|
108
|
+
// No write: the tick runs with `--fold-unchanged`, which prints one line
|
|
109
|
+
// instead of the rows when the tick asks for nothing and says what the
|
|
110
|
+
// last one said. The hold itself stays `fleet-heartbeat.mjs`, whose
|
|
111
|
+
// interval-elapsed line names this command.
|
|
112
|
+
// drain --reason "<reason>"
|
|
113
|
+
// `closeout.mjs begin --reason "<reason>"`, its output printed as it
|
|
114
|
+
// stands, then the tick.
|
|
115
|
+
// `closeout.mjs begin` drains (`ledger.mjs drain`), then releases every claim that never became a PR and settles each `impl-<N>=released`. Nothing else in the loop fires for those claims.
|
|
116
|
+
// `begin` answers a second drain with the standing marker, so a second
|
|
117
|
+
// run releases what is left and writes nothing else. Its exit 4 (a
|
|
118
|
+
// `NEED hand-release #<N> <blocker>` line) is this script's exit 4; its
|
|
119
|
+
// exit 2 or 3 is passed through. The rest of the end of a run,
|
|
120
|
+
// `closeout.mjs finish` last, is the controller's.
|
|
74
121
|
//
|
|
75
122
|
// A write this script cannot make, and does not refuse, is printed as a
|
|
76
123
|
// `NEED <what> …` line, at the left margin, for the controller to make by
|
|
77
124
|
// hand.
|
|
78
125
|
//
|
|
79
126
|
// Exit: 0 every write made and the tick exited 0. 2 a usage error, refused
|
|
80
|
-
// before anything is written or ticked: an unknown kind or flag, a
|
|
127
|
+
// before anything is written or ticked: an unknown kind or flag, a `--reason`
|
|
128
|
+
// that is empty or beside any kind but `drain`, a member of
|
|
81
129
|
// the wrong family, a review path outside the PR's partition or a file that
|
|
82
130
|
// is no review result, a ledger or phase-0 receipt that cannot be read. A
|
|
83
131
|
// ledger write's own refusal — `settle`'s 3 (the report's claim and the world
|
|
84
132
|
// disagree) or 2, `token`'s or `review`'s 2 — passes its exit and message
|
|
85
|
-
// through,
|
|
86
|
-
//
|
|
133
|
+
// through, as does `closeout.mjs begin`'s 2 or 3 and the refusal of a second
|
|
134
|
+
// conflict hold (2), and the tick still runs so the controller sees the rows.
|
|
135
|
+
// Else the tick's own exit when it is not 0. Else 4 when a NEED line was
|
|
136
|
+
// printed, `begin`'s own exit 4 included.
|
|
87
137
|
//
|
|
88
138
|
// Zero deps: node builtins and sibling scripts only.
|
|
89
139
|
|
|
@@ -96,7 +146,7 @@ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
|
|
|
96
146
|
import { gitEnv } from "./git-env.mjs";
|
|
97
147
|
import { isCLI } from "./is-cli.mjs";
|
|
98
148
|
import { BRIEFS, REVIEW, REVIEWED, memberTokens, nextReviewerName, parseDispatchedEntry, parseMember, parseToken, rowNums } from "./ledger-grammar.mjs";
|
|
99
|
-
import { dispositionsToken } from "./fleet-tick.mjs";
|
|
149
|
+
import { dispositionsToken, foldLedger } from "./fleet-tick.mjs";
|
|
100
150
|
import { readRunReceipt, tickCaps } from "./phase0-receipt.mjs";
|
|
101
151
|
import { defaultScratch, readReportIn, reportsDir } from "./report-files.mjs";
|
|
102
152
|
|
|
@@ -113,12 +163,17 @@ const KINDS = {
|
|
|
113
163
|
"fix-report": { args: ["<member>"], family: "fix-pr" },
|
|
114
164
|
"finisher-report": { args: ["<member>"], family: "finisher-pr" },
|
|
115
165
|
"merge-bot-report": { args: ["<member>"], family: "merge-bot" },
|
|
116
|
-
"review-result": { args: ["<pr>", "<path>"] },
|
|
117
|
-
"review-failed": { args: ["<pr>", "<launch>"] },
|
|
166
|
+
"review-result": { args: ["<pr>", "<path>"], pr: true },
|
|
167
|
+
"review-failed": { args: ["<pr>", "<launch>"], pr: true },
|
|
168
|
+
ci: { args: ["<pr>"], pr: true },
|
|
169
|
+
label: { args: ["<pr>"], pr: true },
|
|
170
|
+
conflict: { args: ["<pr>"], pr: true },
|
|
171
|
+
heartbeat: { args: [] },
|
|
172
|
+
drain: { args: [], flag: "--reason \"<reason>\"" },
|
|
118
173
|
};
|
|
119
|
-
const FLAGS = { "in-flight": "value" };
|
|
174
|
+
const FLAGS = { "in-flight": "value", reason: "value" };
|
|
120
175
|
const USAGE = `usage: ${NAME}.mjs <kind> <args> [--in-flight <n>] — kinds: `
|
|
121
|
-
+ Object.entries(KINDS).map(([k, { args }]) =>
|
|
176
|
+
+ Object.entries(KINDS).map(([k, { args, flag }]) => [k, ...args, ...(flag ? [flag] : [])].join(" ")).join(", ");
|
|
122
177
|
|
|
123
178
|
// The label each `bailCause` demotes to, and the relabel template's kind.
|
|
124
179
|
const BAILS = {
|
|
@@ -501,6 +556,74 @@ function reviewFailed(ev, pr, launch) {
|
|
|
501
556
|
: next === null ? "no free runner name left" : `next free runner ${next}`);
|
|
502
557
|
}
|
|
503
558
|
|
|
559
|
+
// The line the CI watcher prints for a PR whose ci-state reading it cannot use.
|
|
560
|
+
const degraded = (pr) => `WATCHER DEGRADED: no usable ci-state reading for #${pr} — silence is NOT green`;
|
|
561
|
+
|
|
562
|
+
function ci(ev, pr) {
|
|
563
|
+
const r = node("ci-state.mjs", ["--pr", String(pr)]);
|
|
564
|
+
let payload = null;
|
|
565
|
+
try {
|
|
566
|
+
payload = JSON.parse(r.stdout);
|
|
567
|
+
} catch {
|
|
568
|
+
// No payload is a reading that cannot be used, judged below.
|
|
569
|
+
}
|
|
570
|
+
// The payload is the verdict, never the exit: not-green exits 1 and is an
|
|
571
|
+
// ordinary state.
|
|
572
|
+
const verdict = payload?.verdict;
|
|
573
|
+
if (typeof verdict !== "string" || verdict === "" || verdict === "rate-limited") {
|
|
574
|
+
ev.print(degraded(pr));
|
|
575
|
+
ev.note(`#${pr} ci: no usable ci-state reading, nothing written`);
|
|
576
|
+
return;
|
|
577
|
+
}
|
|
578
|
+
const { runId, attempt, conclusion } = payload;
|
|
579
|
+
if (!isDigits(String(runId)) || !isDigits(String(attempt))) {
|
|
580
|
+
ev.note(`#${pr} ci: verdict ${verdict} binds no run, nothing to record`);
|
|
581
|
+
return;
|
|
582
|
+
}
|
|
583
|
+
// `""` is an in-progress run, which `//` would pass through as a conclusion.
|
|
584
|
+
const tok = `ci=${runId}:${attempt}:${conclusion === null || conclusion === undefined || conclusion === "" ? "-" : conclusion}`;
|
|
585
|
+
if (prWords(ev.ledger, pr).includes(tok)) {
|
|
586
|
+
ev.note(`#${pr} already ${tok}`);
|
|
587
|
+
return;
|
|
588
|
+
}
|
|
589
|
+
const w = node("ledger.mjs", ["token", String(pr), tok]);
|
|
590
|
+
if (w.status === 0) ev.note(`#${pr} ${tok}`);
|
|
591
|
+
else ev.refuse(`token #${pr} ${tok}`, w);
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
// A second hold on a row that already answered one is the same word spelled
|
|
595
|
+
// the other way the tick reads, because `token` writes no word a row carries.
|
|
596
|
+
const HOLD_SPELLINGS = (pr) => [`conflict-hold:#${pr}`, `conflict-hold-#${pr}`];
|
|
597
|
+
|
|
598
|
+
function conflict(ev, pr) {
|
|
599
|
+
const open = foldLedger(ev.ledger, new Set(), { lenient: true }).byPr.get(pr)?.conflictOpen === true;
|
|
600
|
+
const words = prWords(ev.ledger, pr);
|
|
601
|
+
const tok = HOLD_SPELLINGS(pr).find((t) => !words.includes(t));
|
|
602
|
+
if (open || tok === undefined) {
|
|
603
|
+
const why = open ? "an unresolved conflict hold" : "every spelling of a conflict hold the tick reads";
|
|
604
|
+
writeAll(2, `${NAME}: conflict: PR #${pr}'s row already carries ${why} — nothing written\n`);
|
|
605
|
+
if (ev.refused === null) ev.refused = 2;
|
|
606
|
+
ev.note(`#${pr} conflict hold refused (row already holds)`);
|
|
607
|
+
return;
|
|
608
|
+
}
|
|
609
|
+
const w = node("ledger.mjs", ["token", String(pr), tok]);
|
|
610
|
+
if (w.status === 0) ev.note(`#${pr} ${tok}`);
|
|
611
|
+
else ev.refuse(`token #${pr} ${tok}`, w);
|
|
612
|
+
}
|
|
613
|
+
|
|
614
|
+
function drain(ev, reason) {
|
|
615
|
+
const r = node("closeout.mjs", ["begin", "--reason", reason]);
|
|
616
|
+
ev.print(r.stdout);
|
|
617
|
+
if (r.status === 0) {
|
|
618
|
+
ev.note("drain begun");
|
|
619
|
+
} else if (r.status === 4) {
|
|
620
|
+
ev.needs += 1;
|
|
621
|
+
ev.note("drain begun, a claim to hand-release");
|
|
622
|
+
} else {
|
|
623
|
+
ev.refuse("closeout begin", r);
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
|
|
504
627
|
// ── main ────────────────────────────────────────────────────────────────────
|
|
505
628
|
|
|
506
629
|
function boundArg(F, name) {
|
|
@@ -530,13 +653,19 @@ function main() {
|
|
|
530
653
|
const [kind, ...args] = positionals();
|
|
531
654
|
if (!Object.hasOwn(KINDS, kind ?? "")) die(kind === undefined ? USAGE : `unknown kind '${kind}' — ${USAGE}`);
|
|
532
655
|
const spec = KINDS[kind];
|
|
533
|
-
if (args.length !== spec.args.length) die(`${kind} takes ${spec.args.join(" ")} — ${USAGE}`);
|
|
656
|
+
if (args.length !== spec.args.length) die(`${kind} takes ${spec.args.join(" ") || "no arguments"} — ${USAGE}`);
|
|
534
657
|
const inFlight = boundArg(F, "in-flight");
|
|
658
|
+
const reason = F.arg("reason");
|
|
659
|
+
if (kind === "drain") {
|
|
660
|
+
if (reason === null) die("drain takes --reason \"<reason>\"");
|
|
661
|
+
} else if (reason !== null) {
|
|
662
|
+
die(`--reason belongs to drain, not ${kind}`);
|
|
663
|
+
}
|
|
535
664
|
let pr = null;
|
|
536
665
|
if (spec.family !== undefined) {
|
|
537
666
|
const m = parseMember(args[0]);
|
|
538
667
|
if (m === null || m.family !== spec.family) die(`${kind} takes a member of the ${spec.family} family, not '${args[0]}'`);
|
|
539
|
-
} else {
|
|
668
|
+
} else if (spec.pr) {
|
|
540
669
|
const digits = args[0].replace(/^#/, "");
|
|
541
670
|
if (!isDigits(digits) || Number(digits) < 1) die(`${kind}: '${args[0]}' is not a PR number`);
|
|
542
671
|
pr = Number(digits);
|
|
@@ -555,7 +684,7 @@ function main() {
|
|
|
555
684
|
}
|
|
556
685
|
const caps = tickCaps(fleetDir);
|
|
557
686
|
if (caps.error) die(`${caps.error} — nothing written`);
|
|
558
|
-
const tickArgs = ["--apply", ...(inFlight === null ? caps.args : ["--in-flight", inFlight])];
|
|
687
|
+
const tickArgs = ["--apply", ...(inFlight === null ? caps.args : ["--in-flight", inFlight]), ...(kind === "heartbeat" ? ["--fold-unchanged"] : [])];
|
|
559
688
|
|
|
560
689
|
const ev = new Event({ fleetDir, scratch, ledger: readLedger() });
|
|
561
690
|
if (kind === "impl-report") implReport(ev, args[0]);
|
|
@@ -563,7 +692,10 @@ function main() {
|
|
|
563
692
|
else if (kind === "finisher-report") finisherReport(ev, args[0]);
|
|
564
693
|
else if (kind === "merge-bot-report") mergeBotReport(ev, args[0]);
|
|
565
694
|
else if (kind === "review-result") reviewResult(ev, pr, args[1]);
|
|
566
|
-
else reviewFailed(ev, pr, args[1]);
|
|
695
|
+
else if (kind === "review-failed") reviewFailed(ev, pr, args[1]);
|
|
696
|
+
else if (kind === "ci") ci(ev, pr);
|
|
697
|
+
else if (kind === "conflict") conflict(ev, pr);
|
|
698
|
+
else if (kind === "drain") drain(ev, reason);
|
|
567
699
|
|
|
568
700
|
writeAll(1, `${[...ev.lines, `event: ${kind}: ${ev.summary.join("; ") || "nothing to record"}`].join("\n")}\n`);
|
|
569
701
|
const tick = spawnSync(process.execPath, [join(SCRIPTS, "fleet-tick.mjs"), ...tickArgs], { stdio: ["ignore", "inherit", "inherit"], env: gitEnv() });
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
// script never reads or reports fleet state: counts captured before a
|
|
33
33
|
// twenty-minute hold and printed after it are a stale verdict, and a stale
|
|
34
34
|
// verdict is how a reconcile prints an ACTION nobody can take. The controller
|
|
35
|
-
// runs fleet-
|
|
35
|
+
// runs `fleet-event.mjs heartbeat` itself at wake time, which ticks and so reads the run as it stands then.
|
|
36
36
|
// It also makes a late hold harmless: if a member reports at minute two and
|
|
37
37
|
// the controller acts, the hold that fires afterwards is a free extra tick.
|
|
38
38
|
//
|
|
@@ -277,7 +277,7 @@ function main() {
|
|
|
277
277
|
// on every hold until the file is repaired.
|
|
278
278
|
const skippedNote = now.degraded ? " — the heartbeat file is degraded and was left as it is, so interval progress is not kept and every hold fires" : "";
|
|
279
279
|
console.log(done
|
|
280
|
-
? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-
|
|
280
|
+
? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-event.mjs heartbeat${skippedNote}`
|
|
281
281
|
: `heartbeat: held ${held}s, ${target - elapsed}s of ${target}s remain (quiet=${state.quiet}) → re-issue this command now, do not end your turn`);
|
|
282
282
|
}
|
|
283
283
|
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -1316,44 +1316,53 @@ unconfirmed. Invoking the command was the opt-in. One exception: **a judgement t
|
|
|
1316
1316
|
evidence cannot settle**.
|
|
1317
1317
|
|
|
1318
1318
|
**Rule: record, tick, act, beat.** Every wake — a member report, a review
|
|
1319
|
-
notification, a label, a CI run reaching a terminal state, a
|
|
1320
|
-
one `fleet-
|
|
1319
|
+
notification, a label, a CI run reaching a terminal state, a `CONFLICT` line, a
|
|
1320
|
+
heartbeat, the maintainer's drain — is one `fleet-event.mjs` call, which makes
|
|
1321
|
+
the wake's writes and ends in one `fleet-tick.mjs` invocation, and you do what
|
|
1322
|
+
it prints. There are no hand-run
|
|
1321
1323
|
refill or dispatch edges left. Record first, because the tick reads the run off
|
|
1322
1324
|
`.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
|
|
1323
1325
|
one it cannot see, and it names the same dispatch again. Every record goes
|
|
1324
|
-
through `ledger.mjs` (**Run ledger**)
|
|
1325
|
-
|
|
1326
|
-
ticket's line — never a hand edit.
|
|
1326
|
+
through `ledger.mjs` (**Run ledger**), which `fleet-event.mjs` drives — never a
|
|
1327
|
+
hand edit. What each kind writes is in the header comment of `fleet-event.mjs`.
|
|
1327
1328
|
|
|
1328
|
-
|
|
1329
|
+
Run each as `~/.fleet/bin/fleet-run fleet-event.mjs <kind> <args>`, from the main checkout:
|
|
1330
|
+
|
|
1331
|
+
| Wake | Command |
|
|
1329
1332
|
|---|---|
|
|
1330
|
-
| Implementer report | `
|
|
1331
|
-
| Review workflow notification / `review-pr-<n>` report |
|
|
1332
|
-
|
|
|
1333
|
-
|
|
|
1334
|
-
| Finisher report
|
|
1335
|
-
|
|
|
1336
|
-
|
|
|
1337
|
-
|
|
|
1338
|
-
|
|
|
1339
|
-
|
|
|
1340
|
-
|
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
owes beyond its
|
|
1333
|
+
| Implementer report | `fleet-event.mjs impl-report impl-<N>` |
|
|
1334
|
+
| Review result file written (workflow notification / `review-pr-<n>` report) | `fleet-event.mjs review-result <pr> <path>` |
|
|
1335
|
+
| Review launch failed | `fleet-event.mjs review-failed <pr> <launch>` |
|
|
1336
|
+
| Fix-applier report | `fleet-event.mjs fix-report fix-pr-<M>` |
|
|
1337
|
+
| Finisher report | `fleet-event.mjs finisher-report finisher-pr-<M>` |
|
|
1338
|
+
| Merge-bot pass report | `fleet-event.mjs merge-bot-report merge-bot-<n>` |
|
|
1339
|
+
| CI run terminal | `fleet-event.mjs ci <pr>` |
|
|
1340
|
+
| Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
|
|
1341
|
+
| `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
|
|
1342
|
+
| Heartbeat | `fleet-event.mjs heartbeat` |
|
|
1343
|
+
| Drain | `fleet-event.mjs drain --reason "<reason>"` |
|
|
1344
|
+
|
|
1345
|
+
Act on every line the call prints, the tick's last, and arm the beat. What a wake
|
|
1346
|
+
owes beyond its call:
|
|
1344
1347
|
|
|
1345
1348
|
- **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
|
|
1346
1349
|
below. A turn that ends on a drained queue is #3's stall itself: nothing
|
|
1347
1350
|
external will wake you, and the level-check you are one command away from
|
|
1348
1351
|
never runs. Listed first because it is the only wake with no trigger —
|
|
1349
1352
|
every other row above arrives; this one is the absence of one.
|
|
1350
|
-
- **Implementer report** →
|
|
1351
|
-
settle the member, then run the tick. The PR is owed a review from here on:
|
|
1353
|
+
- **Implementer report** → the PR is owed a review from here on:
|
|
1352
1354
|
the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
|
|
1353
1355
|
and it names the next shortlist head for the slot the implementer left. Pull
|
|
1354
1356
|
nothing the tick did not name.
|
|
1355
|
-
- **
|
|
1356
|
-
|
|
1357
|
+
- **Finisher reports halted** → the per-cause rule (**Resolving a finisher
|
|
1358
|
+
halt**, below).
|
|
1359
|
+
- **A finisher failed or was killed** → `ledger.mjs settle finisher-pr-<M>=failed` for a
|
|
1360
|
+
finisher that crashed or gave up, `=killed` for one that was killed; no label,
|
|
1361
|
+
and the tick prints no dispatch for it. The cockpit flags the PR
|
|
1362
|
+
`finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand
|
|
1363
|
+
(**Resolving a finisher that died**, below), then run the tick.
|
|
1364
|
+
- **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`
|
|
1365
|
+
settles `impl-<N>=bailed` and demotes by cause:
|
|
1357
1366
|
|
|
1358
1367
|
| Cause | Label |
|
|
1359
1368
|
|---|---|
|
|
@@ -1361,60 +1370,45 @@ owes beyond its row:
|
|
|
1361
1370
|
| genuine fork — options named, none ruled | `ready-for-human` |
|
|
1362
1371
|
| needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
|
|
1363
1372
|
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
`release-ticket.sh` (below — `reap.sh` declines a claim that never became a
|
|
1367
|
-
PR), then run the tick: the head it names next is a *different* ticket.
|
|
1373
|
+
The call relabels, comments the cause and releases the claim, then ticks:
|
|
1374
|
+
the head the tick names next is a *different* ticket.
|
|
1368
1375
|
`needs-triage` routes back to `/triage`, which can return it as
|
|
1369
1376
|
`ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
|
|
1370
1377
|
brief that names no *what*.
|
|
1371
1378
|
|
|
1372
|
-
|
|
1373
|
-
`
|
|
1374
|
-
scans *and* the maintainer's. It does not loop; it disappears. The same causes
|
|
1375
|
-
relabel an unclaimed ticket at the Pull (phase 1), where there is no
|
|
1376
|
-
`in-progress` to drop — the causes and labels are one table, applied at
|
|
1379
|
+
The same causes relabel an unclaimed ticket at the Pull (phase 1), where there
|
|
1380
|
+
is no `in-progress` to drop — the causes and labels are one table, applied at
|
|
1377
1381
|
whichever point the ticket fails them.
|
|
1378
1382
|
- **A review result lands** → see the result file written (by you or by the
|
|
1379
|
-
runner — **Reviewers** says which, per harness)
|
|
1380
|
-
|
|
1383
|
+
runner — **Reviewers** says which, per harness), then
|
|
1384
|
+
`fleet-event.mjs review-result <pr> <path>`: a PR with survived or unverified findings prints as
|
|
1381
1385
|
`DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
|
|
1382
1386
|
fix-applier and dispatch the **finisher** directly — or, when that head's
|
|
1383
1387
|
bound conclusion is red and not solely staleness, the red-check fixer
|
|
1384
1388
|
instead (**Then dispatch a red-check fixer**, below): no member will touch that
|
|
1385
1389
|
PR, so no push is coming and nothing will wake you. A review that failed is
|
|
1386
1390
|
not a result — **Reviewers** says who retries it and what takes over.
|
|
1387
|
-
- **Monitor: `ready-to-merge` appears** →
|
|
1391
|
+
- **Monitor: `ready-to-merge` appears** → `fleet-event.mjs label <pr>`, and
|
|
1388
1392
|
on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
|
|
1389
1393
|
Catches hand-added labels as well as a finisher's own. The bot does not wait
|
|
1390
1394
|
for that finisher's report: its rebase is server-side,
|
|
1391
1395
|
`gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
|
|
1392
1396
|
happen first.
|
|
1393
|
-
- **Merge-bot pass reports done** →
|
|
1394
|
-
|
|
1395
|
-
and leaves nothing in the repo, so the row is the only place the tick can read
|
|
1396
|
-
it from — settle `merge-bot-<n>=done`, and then run the tick: `tick --apply`
|
|
1397
|
-
reaps merged branches and worktrees with `reap.sh --apply` (below), then
|
|
1398
|
-
reclaims their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
|
|
1399
|
-
(below), once for every merge bot settled `done` — always, even when the pass
|
|
1400
|
-
merged nothing — and runs both again on the next tick after an `APPLY FAILED`
|
|
1401
|
-
line, and on every tick while this run has no controller record to remember
|
|
1402
|
-
the pass by. A label that landed at the last moment reads `DISPATCH
|
|
1397
|
+
- **Merge-bot pass reports done** → `fleet-event.mjs merge-bot-report merge-bot-<n>`. A label that
|
|
1398
|
+
landed at the last moment reads `DISPATCH
|
|
1403
1399
|
merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
|
|
1404
1400
|
on a conflict needs no record from you — the bot already appended
|
|
1405
1401
|
`conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
|
|
1406
1402
|
fix-pr PR#<pr>` (**Reviewers**).
|
|
1407
|
-
- **The run ends, or the maintainer says drain** → `
|
|
1408
|
-
(below)
|
|
1409
|
-
else in the loop fires for those claims. The marker is on disk, so the tick
|
|
1403
|
+
- **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
|
|
1404
|
+
first (below). The marker is on disk, so the tick
|
|
1410
1405
|
holds the implementer row at `HOLD (draining)` from then on — for a
|
|
1411
1406
|
replacement controller too — and keeps the review, fix-applier and merge rows
|
|
1412
1407
|
firing until the open PRs merge. The drain starts the end of the run; it does
|
|
1413
1408
|
not end it. **End of run**, in this order:
|
|
1414
|
-
1. `~/.fleet/bin/fleet-run
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
PRs**). A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
|
|
1409
|
+
1. `~/.fleet/bin/fleet-run fleet-event.mjs drain --reason "<reason>"` — runs
|
|
1410
|
+
`closeout.mjs begin --reason "<reason>"` (**Release the claims that never became
|
|
1411
|
+
PRs**), then the tick. A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
|
|
1418
1412
|
refusal is the finding, so run `worktree-audit.sh` and decide by hand.
|
|
1419
1413
|
`begin` selects a claim with no PR and a live or `bailed` implementer token
|
|
1420
1414
|
on every run, so a claim you keep leaves `begin` at exit 4 on every run:
|
|
@@ -1430,15 +1424,12 @@ owes beyond its row:
|
|
|
1430
1424
|
the ledger marks reviewed with no verdict row: append it with the verdict
|
|
1431
1425
|
you rule (**Guard: accumulate per PR**) and run `finish` again. A step it
|
|
1432
1426
|
fails is explained in references/close-out.md. Exit 0 is the run closed.
|
|
1433
|
-
- **Monitor: CI run completes** →
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
controller holding only the colour cannot later tell an edge it has already
|
|
1440
|
-
spent from one that never fired, and that is the distinction the sibling
|
|
1441
|
-
bullet below turns on. The whole key, never the conclusion alone: **a
|
|
1427
|
+
- **Monitor: CI run completes** → `fleet-event.mjs ci <pr>`, which binds the run
|
|
1428
|
+
(`ci-state.mjs --pr <N>`) and **records it as
|
|
1429
|
+
`ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
|
|
1430
|
+
ticket's ledger row, which outlives your context. The key is what the sibling
|
|
1431
|
+
bullet below turns on: it tells an edge already spent from one that never
|
|
1432
|
+
fired. The whole key, never the conclusion alone: **a
|
|
1442
1433
|
conclusion is not stable** (below), because a rerun rewrites the run in
|
|
1443
1434
|
place. The diff-validating `check` job green with no heavy job (the
|
|
1444
1435
|
diff-validating suites, not the `rebase-check` currency gate) in `failure`
|
|
@@ -1502,7 +1493,7 @@ owes beyond its row:
|
|
|
1502
1493
|
repo has no CI configured and no declaration, and stop. Absence never reads as
|
|
1503
1494
|
pass. See `review-and-fix.md` step 6.
|
|
1504
1495
|
|
|
1505
|
-
**
|
|
1496
|
+
**In one line, every wake is one `fleet-event.mjs` call, which ends in the tick.** One tick invocation, and you act on what it prints:
|
|
1506
1497
|
|
|
1507
1498
|
```
|
|
1508
1499
|
~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
|
|
@@ -1559,17 +1550,16 @@ depth** guard table applied in code. Act on each line as it reads:
|
|
|
1559
1550
|
- `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
|
|
1560
1551
|
settled `labelled` and the label is still not on: the tick dispatches no
|
|
1561
1552
|
third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
|
|
1562
|
-
flag and the comment the repair finisher's report left (
|
|
1563
|
-
|
|
1553
|
+
flag and the comment the repair finisher's report left (`fleet-event.mjs`'s
|
|
1554
|
+
`finisher-report` entry).
|
|
1564
1555
|
- `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
|
|
1565
1556
|
tracks it, no conflict hold stands on it, no fix-applier, finisher or
|
|
1566
1557
|
implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
|
|
1567
1558
|
is live: a queued PR is the bot's while one runs, and its own fallback records
|
|
1568
|
-
the hold. Record it with `
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
tokens. Then run the tick: the hold reads as `DISPATCH fix-pr
|
|
1559
|
+
the hold. Record it with `fleet-event.mjs conflict <M>`, not with the `ledger.mjs
|
|
1560
|
+
row` form the row's detail prints: `row` replaces the whole line. The call
|
|
1561
|
+
refuses a PR whose row already carries a hold no fix-applier has answered.
|
|
1562
|
+
The tick then reads the hold as `DISPATCH fix-pr
|
|
1573
1563
|
PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
|
|
1574
1564
|
hold**), and that row obeys every hold. A review in flight does not stop the
|
|
1575
1565
|
line: `fix-due` waits for the review to return. It prints under a
|
|
@@ -1709,8 +1699,8 @@ exactly the way that gate does:
|
|
|
1709
1699
|
|
|
1710
1700
|
It blocks, then prints one line. Which line it is, is the whole protocol:
|
|
1711
1701
|
|
|
1712
|
-
- `… interval elapsed (quiet=<n>) → run fleet-
|
|
1713
|
-
|
|
1702
|
+
- `… interval elapsed (quiet=<n>) → run fleet-event.mjs heartbeat` — the level-check
|
|
1703
|
+
is due. Run that command and act on what the tick it ends in prints.
|
|
1714
1704
|
Then arm the beat again.
|
|
1715
1705
|
- `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
|
|
1716
1706
|
command blocks for a whole interval (omp backgrounds one at 60s, which is
|
|
@@ -1729,7 +1719,7 @@ not a reason to end the run; they are the state a newly triaged ticket arrives
|
|
|
1729
1719
|
into. The run ends when you drain it, when the budget goes, or when this
|
|
1730
1720
|
context does — not because there was briefly nothing to do.
|
|
1731
1721
|
|
|
1732
|
-
**`--fold-unchanged` belongs to the heartbeat alone
|
|
1722
|
+
**`--fold-unchanged` belongs to the heartbeat alone** — `fleet-event.mjs heartbeat` passes it, no other kind does.
|
|
1733
1723
|
It prints one line instead of the rows when a tick asks for nothing AND says
|
|
1734
1724
|
exactly what the last one said, which is what makes an unattended night
|
|
1735
1725
|
affordable; a tick on any other wake is read by a controller that just acted and
|
|
@@ -1921,7 +1911,7 @@ while :; do # one tick
|
|
|
1921
1911
|
echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
|
|
1922
1912
|
keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
|
|
1923
1913
|
esac
|
|
1924
|
-
: # your normal handling of $st for this PR
|
|
1914
|
+
: # your normal handling of $st for this PR; a run at a terminal state is the CI wake: fleet-event.mjs ci "$pr"
|
|
1925
1915
|
done
|
|
1926
1916
|
fi
|
|
1927
1917
|
fi
|
|
@@ -2180,8 +2170,9 @@ No replay exists for a review that ran in a runner's own kernel — `resume` is
|
|
|
2180
2170
|
`refuted` comes back deliberately as well — a refutation is itself a claim, and
|
|
2181
2171
|
one has been reversed on new evidence. The fix-applier may reverse one; it
|
|
2182
2172
|
records each reversal as a `refuted` entry in its disposition record, the
|
|
2183
|
-
evidence in `reason`, and you copy those entries to the ledger's `ruled` line
|
|
2184
|
-
|
|
2173
|
+
evidence in `reason`, and you copy those entries to the ledger's `ruled` line by
|
|
2174
|
+
running `fleet-event.mjs fix-report`, whose `settle --from-report` records each
|
|
2175
|
+
refutation the report defers.
|
|
2185
2176
|
|
|
2186
2177
|
**`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
|
|
2187
2178
|
specialist that dies contributes zero findings while its key stays in
|
|
@@ -2487,8 +2478,8 @@ gated like survivors, and the tick prints `DISPATCH fix-pr PR#<M>` for it: that
|
|
|
2487
2478
|
fix-applier's `no-op` and its `ok` verdict are what open the finisher. The
|
|
2488
2479
|
refusal names its cause. `dispositions
|
|
2489
2480
|
unchecked` — no verdict answers that review: run `dispositions-check.mjs` for
|
|
2490
|
-
the fix-applier that answered the review, as
|
|
2491
|
-
states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
|
|
2481
|
+
the fix-applier that answered the review, as `fleet-event.mjs`'s `fix-report`
|
|
2482
|
+
entry states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
|
|
2492
2483
|
no rule broke, but the check could not read where a deferral was filed, `gh`
|
|
2493
2484
|
unreachable or an issue unreadable: run the check again for that fix-applier
|
|
2494
2485
|
once `gh` answers (an issue that does not exist is unreadable too, and no re-run
|
|
@@ -358,7 +358,7 @@ token, row}]}`:
|
|
|
358
358
|
names. Reconcile them before shortlisting: read `proc://` once, find
|
|
359
359
|
each `name` among this session's jobs, and act on its state.
|
|
360
360
|
`running` → keep the token. `completed` or `failed` → record its
|
|
361
|
-
result from `agent://<id>` as the **
|
|
361
|
+
result from `agent://<id>` as the wake table of **Rule: record, tick, act, beat** records
|
|
362
362
|
that member's report; an output you cannot read is a death the
|
|
363
363
|
Member-killed row confirms. `cancelled` → record it dead. Absent, or a
|
|
364
364
|
state you cannot read → keep the token live and let the Member-killed
|