@feigi/fleet-ctl 3.128.3 → 3.130.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/scripts/closeout.mjs +250 -21
- package/scripts/instruments.sh +120 -236
- package/scripts/member-write-guard.mjs +3 -2
- package/scripts/phase0.mjs +12 -9
- package/scripts/reap.sh +3 -8
- package/skills/run-team/SKILL.md +14 -20
- package/skills/run-team/references/close-out.md +5 -3
- package/skills/run-team/references/instruments.md +22 -58
- package/skills/run-team/references/invariants.md +0 -10
- package/skills/run-team/references/phase-0.md +19 -13
package/package.json
CHANGED
package/scripts/closeout.mjs
CHANGED
|
@@ -41,12 +41,22 @@
|
|
|
41
41
|
// commit-and-pr `git switch -c <branch>` (`--branch`, default
|
|
42
42
|
// `chore/run-artifacts-<UTC date>`, suffixed `b`, `c`… while
|
|
43
43
|
// that name exists locally or on origin), commit exactly the
|
|
44
|
-
// three `docs/metrics/*.tsv` files,
|
|
45
|
-
//
|
|
46
|
-
//
|
|
47
|
-
//
|
|
48
|
-
//
|
|
49
|
-
//
|
|
44
|
+
// three `docs/metrics/*.tsv` files, `git fetch origin`, `git
|
|
45
|
+
// rebase origin/main`, push `-u` with a lease, `gh pr
|
|
46
|
+
// create --label patch` with a body naming the reason and the
|
|
47
|
+
// rows each file gained and lost, `git switch main`. The
|
|
48
|
+
// rebase is three-way, so rows `main` gained during the run
|
|
49
|
+
// stay; one that conflicts or that git refuses is aborted, the
|
|
50
|
+
// branch is pushed as it was, and the PR is opened all the
|
|
51
|
+
// same, for the merge step to leave open. The lease expects
|
|
52
|
+
// origin's branch at the head the receipt last recorded as
|
|
53
|
+
// pushed, or absent before the first push, so a re-run
|
|
54
|
+
// pushes its rebased branch over the one it pushed before,
|
|
55
|
+
// and over nothing else: a branch someone else pushed to
|
|
56
|
+
// fails the step. The branch, the pushed head
|
|
57
|
+
// (the merge step's pin) and the PR once it exists are kept
|
|
58
|
+
// in the receipt: a re-run after a failed push or PR resumes
|
|
59
|
+
// on that branch and never opens a second PR.
|
|
50
60
|
// phase0-receipt moves `.fleet/phase0.json` to `.fleet/phase0.previous.json`,
|
|
51
61
|
// the name `phase0.mjs` holds a previous run's receipt under,
|
|
52
62
|
// so a run that ended here leaves no phase-0 receipt for the
|
|
@@ -56,8 +66,46 @@
|
|
|
56
66
|
// before the stop. No `phase0.json` is nothing to move and is
|
|
57
67
|
// `ok`; a held receipt already there that is not this one is
|
|
58
68
|
// a failed step.
|
|
59
|
-
// heartbeat-stop `fleet-heartbeat.mjs --stop "<reason>"
|
|
60
|
-
//
|
|
69
|
+
// heartbeat-stop `fleet-heartbeat.mjs --stop "<reason>"`. Every reader takes
|
|
70
|
+
// a recorded stop as the end of the run, and it comes before
|
|
71
|
+
// the merge step because a stopped beat starts no alarm
|
|
72
|
+
// turn: before the stop, every wake ends in a tick, which
|
|
73
|
+
// lists the open Close-out PR as a review to dispatch and
|
|
74
|
+
// holds the run open. A `finish` call omp has moved to the
|
|
75
|
+
// background still delivers its result as a turn of its own.
|
|
76
|
+
// merge merges the Close-out PR the step before opened. A rebase
|
|
77
|
+
// that conflicted or was refused leaves it open at once.
|
|
78
|
+
// Otherwise `inertVerdict()` (finisher-scope.mjs) at the
|
|
79
|
+
// pin; anything but `inert` leaves it open. Then, every 30 s,
|
|
80
|
+
// `gh pr view <n> --json state,headRefOid,mergeStateStatus`
|
|
81
|
+
// and `ci-state.mjs --pr <n> --declare-no-ci`: green CI, the
|
|
82
|
+
// head at the pin and `mergeStateStatus` CLEAN or HAS_HOOKS
|
|
83
|
+
// is one `gh pr merge <n> --merge --match-head-commit <pin>`,
|
|
84
|
+
// then a read that confirms MERGED: `merged PR #<n> at <sha>`.
|
|
85
|
+
// A PR already MERGED is that line too; one CLOSED is
|
|
86
|
+
// `closed: PR #<n>`. A failed check (UNSTABLE included), a
|
|
87
|
+
// head off the pin, BEHIND or DIRTY is `left open: PR #<n> —
|
|
88
|
+
// <reason>`, ok, with nothing armed or retried: the next
|
|
89
|
+
// run's phase 0 folds it in. Every other state keeps the
|
|
90
|
+
// step pending, `NEED merge-wait PR #<n>` over the last state
|
|
91
|
+
// read: CI pending, gh or CI unreadable, green CI with
|
|
92
|
+
// `mergeStateStatus` neither CLEAN nor HAS_HOOKS, or a `gh pr
|
|
93
|
+
// merge` that failed or has not landed. 30 minutes after the
|
|
94
|
+
// step first ran, that state leaves the PR open the same way:
|
|
95
|
+
// `the 30-min bound: <state>`, or `gh unreadable until the
|
|
96
|
+
// bound` / `CI unreadable until the bound`. The step stops
|
|
97
|
+
// waiting within 4 minutes of the `finish` call's start; the
|
|
98
|
+
// steps before it are not held to that. The next call resumes
|
|
99
|
+
// from the receipt without pushing, opening or merging again,
|
|
100
|
+
// and one call asks `gh pr merge` at most once. A receipt
|
|
101
|
+
// whose `mergeStarted` is not a past time, or whose `rebase`
|
|
102
|
+
// is neither null nor a reason, fails the step. The step runs
|
|
103
|
+
// gh and read-only git only, and never moves HEAD, the index
|
|
104
|
+
// or a ref. It never arms auto-merge: GitHub keeps
|
|
105
|
+
// auto-merge armed across pushes by anyone with write
|
|
106
|
+
// access, and every member pushes with the maintainer's
|
|
107
|
+
// credentials. It never passes `--delete-branch`, which also
|
|
108
|
+
// deletes the local branch and switches the checkout.
|
|
61
109
|
//
|
|
62
110
|
// `reopen` undoes `begin` for a run that must drain again: refused (exit 2)
|
|
63
111
|
// once any `finish` step is ok, since the tick and what follows it have already
|
|
@@ -68,15 +116,19 @@
|
|
|
68
116
|
// THE RECEIPT is `.fleet/closeout.json` (resolved through fleet-dir.mjs, so a
|
|
69
117
|
// worktree and the main checkout name one file), shared by all three commands:
|
|
70
118
|
//
|
|
71
|
-
// { reason, begun, branch, pr,
|
|
119
|
+
// { reason, begun, branch, pr, pin, rebase, mergeStarted, mergeOutcome,
|
|
120
|
+
// steps: { <name>: { status, at, output } } }
|
|
72
121
|
//
|
|
73
122
|
// `status` is ok, pending or failed; `at` an ISO time; `output` the step's own
|
|
74
123
|
// words. Every step name of both commands is always present: one not yet run
|
|
75
124
|
// is `pending`. `begun` is the time `begin` finished its steps, ok or pending,
|
|
76
|
-
// null until then; `branch
|
|
77
|
-
//
|
|
78
|
-
// `
|
|
79
|
-
//
|
|
125
|
+
// null until then; `branch`, `pr`, `pin` (the head pushed) and `rebase` (null,
|
|
126
|
+
// or why the rebase was aborted) belong to the commit-and-pr step;
|
|
127
|
+
// `mergeStarted` (the merge step's first run, an ISO time) and `mergeOutcome`
|
|
128
|
+
// (its final line) to the merge step. A re-run skips every `ok` step and runs
|
|
129
|
+
// the rest, stopping at the first that is not `ok`, so the steps after it stay
|
|
130
|
+
// `pending`. `ledger.mjs rotate` archives the receipt beside the ledger as
|
|
131
|
+
// `closeout.<UTC stamp>.json`.
|
|
80
132
|
//
|
|
81
133
|
// One `closeout: <step>: <status>` line per step on stdout, its output under
|
|
82
134
|
// it, indented, with the `NEED` lines at the left margin. Exit 0 every step
|
|
@@ -95,6 +147,7 @@ import { dirname, join } from "node:path";
|
|
|
95
147
|
import { fileURLToPath } from "node:url";
|
|
96
148
|
import { makeDie, defineFlags } from "./arg.mjs";
|
|
97
149
|
import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
|
|
150
|
+
import { inertVerdict } from "./finisher-scope.mjs";
|
|
98
151
|
import { gitEnv } from "./git-env.mjs";
|
|
99
152
|
import { isCLI } from "./is-cli.mjs";
|
|
100
153
|
import { CLOSEOUT_RECEIPT, RECEIPT, RECEIPT_HELD, memberTokens, rowPr, isOmpSessionDirName } from "./ledger-grammar.mjs";
|
|
@@ -148,6 +201,8 @@ function fatal(message) {
|
|
|
148
201
|
// ── the receipt ──────────────────────────────────────────────────────────────
|
|
149
202
|
|
|
150
203
|
const blank = () => ({ status: "pending", at: null, output: "" });
|
|
204
|
+
// The receipt's own fields, in the order it is written; each null until set.
|
|
205
|
+
const RECEIPT_FIELDS = ["reason", "begun", "branch", "pr", "pin", "rebase", "mergeStarted", "mergeOutcome"];
|
|
151
206
|
|
|
152
207
|
function readReceipt(path, stepNames) {
|
|
153
208
|
let prior = null;
|
|
@@ -157,7 +212,7 @@ function readReceipt(path, stepNames) {
|
|
|
157
212
|
if (e.code !== "ENOENT") fatal(`cannot read receipt ${path}: ${e.message}`);
|
|
158
213
|
}
|
|
159
214
|
const steps = Object.fromEntries(stepNames.map((n) => [n, { ...blank(), ...prior?.steps?.[n] }]));
|
|
160
|
-
return {
|
|
215
|
+
return { ...Object.fromEntries(RECEIPT_FIELDS.map((k) => [k, prior?.[k] ?? null])), steps };
|
|
161
216
|
}
|
|
162
217
|
|
|
163
218
|
function writeReceipt(path, receipt) {
|
|
@@ -303,6 +358,33 @@ function rowCounts(git) {
|
|
|
303
358
|
return { lines: r.stdout.split("\n").filter(Boolean).map((l) => l.split("\t")).map(([added, removed, file]) => `- ${file}: +${added} -${removed}`) };
|
|
304
359
|
}
|
|
305
360
|
|
|
361
|
+
// Replays the branch's commit onto the `origin/main` just fetched, three-way,
|
|
362
|
+
// so rows `main` gained during the run stay. A replay that stops on a
|
|
363
|
+
// conflict, or that git refuses to start, is aborted and the branch stays as
|
|
364
|
+
// it was: `{ leftOpen }` names why, and the step goes on to push and open the
|
|
365
|
+
// PR. `{ error }` is a fetch, or an abort, that failed.
|
|
366
|
+
function rebaseOntoMain(git) {
|
|
367
|
+
const fetch = git(["fetch", "origin"], NETWORK_TIMEOUT_MS);
|
|
368
|
+
if (fetch.status !== 0) return { error: `git fetch origin failed: ${detail(fetch)}` };
|
|
369
|
+
const rebase = git(["rebase", "origin/main"]);
|
|
370
|
+
if (rebase.status === 0) return { leftOpen: null };
|
|
371
|
+
const unmerged = git(["diff", "--name-only", "--diff-filter=U"]);
|
|
372
|
+
const stopped = git(["rev-parse", "--verify", "--quiet", "REBASE_HEAD"]);
|
|
373
|
+
if (stopped.status === 0) {
|
|
374
|
+
const abort = git(["rebase", "--abort"]);
|
|
375
|
+
if (abort.status !== 0) return { error: `git rebase origin/main stopped and git rebase --abort failed: ${detail(abort)}` };
|
|
376
|
+
}
|
|
377
|
+
// git's first line, then the paths it lists indented under it, such as the
|
|
378
|
+
// untracked files a replay would overwrite.
|
|
379
|
+
const [said, ...rest] = detail(rebase).split("\n");
|
|
380
|
+
const named = rest.filter((l) => /^\s/.test(l)).map((l) => l.trim());
|
|
381
|
+
const refused = [said, named.join(", ")].filter(Boolean).join(" ");
|
|
382
|
+
if (unmerged.status !== 0) return { leftOpen: `rebase failed: ${refused}; git diff --diff-filter=U failed: ${detail(unmerged)}` };
|
|
383
|
+
const files = unmerged.stdout.split("\n").filter(Boolean);
|
|
384
|
+
if (files.length > 0) return { leftOpen: `rebase conflict: ${files.join(", ")}` };
|
|
385
|
+
return { leftOpen: `rebase refused: ${refused}` };
|
|
386
|
+
}
|
|
387
|
+
|
|
306
388
|
// Everything the step does while the checkout is on the metrics branch; the
|
|
307
389
|
// caller switches back to main whatever this returns.
|
|
308
390
|
function onBranch({ git, cwd, reason, receipt, save }) {
|
|
@@ -312,14 +394,25 @@ function onBranch({ git, cwd, reason, receipt, save }) {
|
|
|
312
394
|
const commit = git(["commit", "-m", `Closeout: ${reason}`, "--", ...METRICS]);
|
|
313
395
|
if (commit.status !== 0) return failed(`git commit failed: ${detail(commit)}`);
|
|
314
396
|
}
|
|
397
|
+
const rebased = rebaseOntoMain(git);
|
|
398
|
+
if (rebased.error) return failed(rebased.error);
|
|
315
399
|
const ahead = git(["rev-list", "--count", "origin/main..HEAD"]);
|
|
316
400
|
if (ahead.status !== 0) return failed(`git rev-list --count origin/main..HEAD failed: ${detail(ahead)}`);
|
|
317
401
|
if (ahead.stdout === "0") return failed(`nothing to commit: ${METRICS.join(", ")} are unchanged`);
|
|
402
|
+
const head = git(["rev-parse", "HEAD"]);
|
|
403
|
+
if (head.status !== 0) return failed(`git rev-parse HEAD failed: ${detail(head)}`);
|
|
318
404
|
|
|
319
|
-
|
|
405
|
+
// The lease is the head this step last pushed, never what the fetch above
|
|
406
|
+
// just read: an empty one expects the branch absent from origin.
|
|
407
|
+
const lease = `--force-with-lease=refs/heads/${receipt.branch}:${receipt.pin ?? ""}`;
|
|
408
|
+
const push = git(["push", "-u", lease, "origin", receipt.branch], NETWORK_TIMEOUT_MS);
|
|
320
409
|
if (push.status !== 0) return failed(`git push failed: ${detail(push)}`);
|
|
410
|
+
receipt.pin = head.stdout;
|
|
411
|
+
receipt.rebase = rebased.leftOpen;
|
|
412
|
+
save();
|
|
413
|
+
const lines = [`pushed ${receipt.pin}`, ...(rebased.leftOpen === null ? [] : [rebased.leftOpen])];
|
|
321
414
|
|
|
322
|
-
if (receipt.pr !== null) return ok(`PR ${receipt.pr} already opened for ${receipt.branch}`);
|
|
415
|
+
if (receipt.pr !== null) return ok([...lines, `PR ${receipt.pr} already opened for ${receipt.branch}`].join("\n"));
|
|
323
416
|
const counts = rowCounts(git);
|
|
324
417
|
if (counts.error) return failed(counts.error);
|
|
325
418
|
const body = `Closeout: ${reason}\n\nRows changed:\n${counts.lines.join("\n")}\n`;
|
|
@@ -327,13 +420,19 @@ function onBranch({ git, cwd, reason, receipt, save }) {
|
|
|
327
420
|
if (pr.status !== 0) return failed(`gh pr create failed: ${detail(pr)}`);
|
|
328
421
|
receipt.pr = pr.stdout.split("\n").at(-1);
|
|
329
422
|
save();
|
|
330
|
-
return ok(`PR ${receipt.pr} opened on ${receipt.branch}`);
|
|
423
|
+
return ok([...lines, `PR ${receipt.pr} opened on ${receipt.branch}`].join("\n"));
|
|
331
424
|
}
|
|
332
425
|
|
|
333
|
-
|
|
426
|
+
// The work tree the command runs in, as `{ cwd }`, or `{ error }`.
|
|
427
|
+
function workTree() {
|
|
334
428
|
const top = run("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() });
|
|
335
|
-
|
|
336
|
-
|
|
429
|
+
return top.status === 0 ? { cwd: top.stdout } : { error: `not inside a git work tree: ${detail(top)}` };
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
function stepCommitAndPR({ reason, branch, receipt, save }) {
|
|
433
|
+
const wt = workTree();
|
|
434
|
+
if (wt.error) return failed(wt.error);
|
|
435
|
+
const { cwd } = wt;
|
|
337
436
|
const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
|
|
338
437
|
|
|
339
438
|
if (receipt.branch === null) {
|
|
@@ -383,6 +482,135 @@ function stepHeartbeatStop({ cwd, reason }) {
|
|
|
383
482
|
return r.status === 0 ? ok(r.stdout) : failed(`fleet-heartbeat.mjs --stop failed: ${detail(r)}`);
|
|
384
483
|
}
|
|
385
484
|
|
|
485
|
+
// One read of the PR: `{ state, headRefOid, mergeStateStatus }`, or
|
|
486
|
+
// `{ unreadable }` naming what gh answered instead.
|
|
487
|
+
function readPr(n, cwd, timeoutMs) {
|
|
488
|
+
const r = run("gh", ["pr", "view", n, "--json", "state,headRefOid,mergeStateStatus"], { cwd, env: { GH_REPO: "" }, timeoutMs });
|
|
489
|
+
if (r.status !== 0) return { unreadable: `gh pr view failed: ${detail(r)}` };
|
|
490
|
+
let v = null;
|
|
491
|
+
try {
|
|
492
|
+
v = JSON.parse(r.stdout);
|
|
493
|
+
} catch {
|
|
494
|
+
// Not JSON: named below with what gh printed.
|
|
495
|
+
}
|
|
496
|
+
if (typeof v?.state === "string" && typeof v.headRefOid === "string" && typeof v.mergeStateStatus === "string") return v;
|
|
497
|
+
return { unreadable: `gh pr view answered ${r.stdout || "nothing"}` };
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
// CI as the merge gate reads it, `ci-state.mjs --pr <n> --declare-no-ci`, with
|
|
501
|
+
// the payload and the exit status agreeing. A not-green answer whose run has
|
|
502
|
+
// not completed, or that found no run on the head yet, is still pending; one
|
|
503
|
+
// whose run completed is a failed check.
|
|
504
|
+
function readCi(n, cwd, timeoutMs) {
|
|
505
|
+
const r = node("ci-state.mjs", ["--pr", n, "--declare-no-ci"], { cwd, env: { GH_REPO: "" }, timeoutMs });
|
|
506
|
+
let ci = null;
|
|
507
|
+
try {
|
|
508
|
+
ci = JSON.parse(r.stdout);
|
|
509
|
+
} catch {
|
|
510
|
+
// Not JSON: unreadable below.
|
|
511
|
+
}
|
|
512
|
+
if (ci === null || typeof ci !== "object") return { unreadable: `ci-state.mjs answered nothing readable: ${detail(r)}` };
|
|
513
|
+
if (r.status === 0 && (ci.verdict === "green" || ci.verdict === "no-ci")) return { green: true, prHead: ci.prHead };
|
|
514
|
+
if (r.status === 1 && ci.verdict === "not-green" && Array.isArray(ci.reasons)) {
|
|
515
|
+
const why = ci.reasons.join("; ") || "not green";
|
|
516
|
+
return ci.status === "completed" ? { failed: why } : { pending: why };
|
|
517
|
+
}
|
|
518
|
+
return { unreadable: `ci-state.mjs ${r.how}, verdict ${ci.verdict ?? "absent"}` };
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
// The merge step's clocks: it stops waiting within CALL_MS of the `finish`
|
|
522
|
+
// call's start, reads the PR every POLL_MS, sleeps only while READ_MS is left
|
|
523
|
+
// after the sleep for the reads that follow it, and stops waiting BOUND_MS
|
|
524
|
+
// after its first run. CLOSEOUT_CALL_MS and CLOSEOUT_POLL_MS can only shorten
|
|
525
|
+
// theirs.
|
|
526
|
+
const shorter = (name, ms) => {
|
|
527
|
+
const v = Number(process.env[name]);
|
|
528
|
+
return Number.isInteger(v) && v > 0 && v < ms ? v : ms;
|
|
529
|
+
};
|
|
530
|
+
const CALL_MS = shorter("CLOSEOUT_CALL_MS", 4 * 60_000);
|
|
531
|
+
const POLL_MS = shorter("CLOSEOUT_POLL_MS", 30_000);
|
|
532
|
+
const READ_MS = CALL_MS / 8;
|
|
533
|
+
const BOUND_MS = 30 * 60_000;
|
|
534
|
+
const BOUND = "the 30-min bound";
|
|
535
|
+
const PR_NUMBER = /\/pull\/(\d+)$/;
|
|
536
|
+
const FULL_SHA = /^[0-9a-f]{40}$/;
|
|
537
|
+
const MERGEABLE = new Set(["CLEAN", "HAS_HOOKS"]);
|
|
538
|
+
// Atomics.wait never blocks on a value nothing writes, so it is a plain sleep.
|
|
539
|
+
const IDLE = new Int32Array(new SharedArrayBuffer(4));
|
|
540
|
+
|
|
541
|
+
function stepMerge({ receipt, save, started }) {
|
|
542
|
+
const n = PR_NUMBER.exec(receipt.pr ?? "")?.[1];
|
|
543
|
+
if (n === undefined) return failed(`no PR number in the receipt's pr: ${receipt.pr}`);
|
|
544
|
+
const done = (line) => {
|
|
545
|
+
receipt.mergeOutcome = line;
|
|
546
|
+
save();
|
|
547
|
+
return ok(line);
|
|
548
|
+
};
|
|
549
|
+
const leftOpen = (why) => done(`left open: PR #${n} — ${why}`);
|
|
550
|
+
const merged = (oid) => done(`merged PR #${n} at ${oid}`);
|
|
551
|
+
const { rebase } = receipt;
|
|
552
|
+
if (rebase !== null && (typeof rebase !== "string" || rebase === "")) return failed(`the receipt's rebase is neither null nor a reason: ${JSON.stringify(rebase)}`);
|
|
553
|
+
if (rebase !== null) return leftOpen(rebase);
|
|
554
|
+
if (!FULL_SHA.test(receipt.pin ?? "")) return failed(`no pushed head in the receipt to pin the merge to: ${receipt.pin}`);
|
|
555
|
+
const wt = workTree();
|
|
556
|
+
if (wt.error) return failed(wt.error);
|
|
557
|
+
const { cwd } = wt;
|
|
558
|
+
if (receipt.mergeStarted === null) {
|
|
559
|
+
receipt.mergeStarted = new Date().toISOString();
|
|
560
|
+
save();
|
|
561
|
+
}
|
|
562
|
+
// NaN, from anything but a time string, fails the comparison too.
|
|
563
|
+
const begun = typeof receipt.mergeStarted === "string" ? Date.parse(receipt.mergeStarted) : NaN;
|
|
564
|
+
if (!(begun <= Date.now())) return failed(`the receipt's mergeStarted is not a past time: ${JSON.stringify(receipt.mergeStarted)}`);
|
|
565
|
+
|
|
566
|
+
const v = inertVerdict({ worktree: cwd, pin: receipt.pin });
|
|
567
|
+
if (v.verdict !== "inert") {
|
|
568
|
+
const why = v.reason ?? v.paths.filter((p) => p.class === null).map((p) => `${p.path} (${p.why})`).join(", ");
|
|
569
|
+
return leftOpen(`verdict ${v.verdict}: ${why}`);
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
const bound = begun + BOUND_MS;
|
|
573
|
+
const deadline = started + CALL_MS - CALL_MS / 8;
|
|
574
|
+
const budget = () => Math.min(NETWORK_TIMEOUT_MS, Math.max(1, Math.floor(deadline - Date.now())));
|
|
575
|
+
// `at` is how the bound names the state if it is the last one read.
|
|
576
|
+
const atBound = (last) => leftOpen(`${last.at}: ${last.why}`);
|
|
577
|
+
const NOT_YET = { at: BOUND, why: "gh pr merge answered and the PR is not MERGED yet" };
|
|
578
|
+
let last = { at: BOUND, why: "not read yet" };
|
|
579
|
+
// What the call's one `gh pr merge` answered, kept for every later poll so a
|
|
580
|
+
// failed merge's own words reach the NEED line and the bound.
|
|
581
|
+
let asked = null;
|
|
582
|
+
while (Date.now() < deadline) {
|
|
583
|
+
const pr = readPr(n, cwd, budget());
|
|
584
|
+
if (pr.unreadable) last = { at: "gh unreadable until the bound", why: pr.unreadable };
|
|
585
|
+
else if (pr.state === "MERGED") return merged(pr.headRefOid);
|
|
586
|
+
else if (pr.state === "CLOSED") return done(`closed: PR #${n}`);
|
|
587
|
+
else if (pr.headRefOid !== receipt.pin) return leftOpen(`head moved off the pin ${receipt.pin}: ${pr.headRefOid}`);
|
|
588
|
+
else if (pr.mergeStateStatus === "BEHIND" || pr.mergeStateStatus === "DIRTY") return leftOpen(pr.mergeStateStatus);
|
|
589
|
+
else {
|
|
590
|
+
const ci = readCi(n, cwd, budget());
|
|
591
|
+
if (ci.failed) return leftOpen(`a check failed: ${ci.failed}`);
|
|
592
|
+
if (ci.unreadable) last = { at: "CI unreadable until the bound", why: ci.unreadable };
|
|
593
|
+
else if (ci.pending) last = { at: BOUND, why: `CI pending: ${ci.pending}` };
|
|
594
|
+
else if (ci.prHead !== receipt.pin) return leftOpen(`head moved off the pin ${receipt.pin}: ${ci.prHead}`);
|
|
595
|
+
else if (pr.mergeStateStatus === "UNSTABLE") return leftOpen("a check failed: UNSTABLE");
|
|
596
|
+
else if (!MERGEABLE.has(pr.mergeStateStatus)) last = { at: BOUND, why: `CI green, mergeStateStatus ${pr.mergeStateStatus}` };
|
|
597
|
+
else if (asked !== null) last = asked;
|
|
598
|
+
else {
|
|
599
|
+
const merge = run("gh", ["pr", "merge", n, "--merge", "--match-head-commit", receipt.pin], { cwd, env: { GH_REPO: "" }, timeoutMs: budget() });
|
|
600
|
+
const after = readPr(n, cwd, budget());
|
|
601
|
+
if (after.state === "MERGED") return merged(after.headRefOid);
|
|
602
|
+
asked = merge.status === 0 ? NOT_YET : { at: BOUND, why: `gh pr merge failed: ${detail(merge)}` };
|
|
603
|
+
last = asked;
|
|
604
|
+
}
|
|
605
|
+
}
|
|
606
|
+
if (Date.now() >= bound) return atBound(last);
|
|
607
|
+
if (Date.now() + POLL_MS + READ_MS >= deadline) break;
|
|
608
|
+
Atomics.wait(IDLE, 0, 0, POLL_MS);
|
|
609
|
+
}
|
|
610
|
+
if (Date.now() >= bound) return atBound(last);
|
|
611
|
+
return pending(`NEED merge-wait PR #${n}\n${last.why}`);
|
|
612
|
+
}
|
|
613
|
+
|
|
386
614
|
// ── the steps, in order ──────────────────────────────────────────────────────
|
|
387
615
|
|
|
388
616
|
const BEGIN = { drain: stepDrain, release: stepRelease };
|
|
@@ -394,6 +622,7 @@ const FINISH = {
|
|
|
394
622
|
"commit-and-pr": stepCommitAndPR,
|
|
395
623
|
"phase0-receipt": stepPhase0Receipt,
|
|
396
624
|
"heartbeat-stop": stepHeartbeatStop,
|
|
625
|
+
merge: stepMerge,
|
|
397
626
|
};
|
|
398
627
|
const STEP_NAMES = [...Object.keys(BEGIN), ...Object.keys(FINISH)];
|
|
399
628
|
|
|
@@ -470,7 +699,7 @@ function main() {
|
|
|
470
699
|
const receiptPath = join(fleetDir, CLOSEOUT_RECEIPT);
|
|
471
700
|
const receipt = readReceipt(receiptPath, STEP_NAMES);
|
|
472
701
|
receipt.reason = reason;
|
|
473
|
-
const ctx = { cwd: process.cwd(), fleetDir, reason, branch };
|
|
702
|
+
const ctx = { cwd: process.cwd(), fleetDir, reason, branch, started: performance.timeOrigin };
|
|
474
703
|
if (cmd === "reopen") {
|
|
475
704
|
process.exitCode = reopen(ctx, receipt, receiptPath);
|
|
476
705
|
} else if (cmd === "begin") {
|
package/scripts/instruments.sh
CHANGED
|
@@ -35,21 +35,24 @@
|
|
|
35
35
|
#
|
|
36
36
|
# WHAT IS IN THE SET: the plugin's own component directories — `commands/
|
|
37
37
|
# scripts/ skills/ agents/ workflows/` — of the Install root, the tree the
|
|
38
|
-
# fleet executes, never the checkout this script happens to run in
|
|
39
|
-
#
|
|
38
|
+
# fleet executes, never the checkout this script happens to run in, and never
|
|
39
|
+
# the workspace's own. Every regular file and every symlink under those five
|
|
40
|
+
# directories of the realpath is hashed, dotfiles included: nothing in an
|
|
41
|
+
# installed package is untracked and anything in it executes.
|
|
40
42
|
#
|
|
41
|
-
#
|
|
42
|
-
# `plugin/commands plugin/scripts plugin/skills
|
|
43
|
-
# plugin/agents plugin/workflows` of the checkout the
|
|
44
|
-
# link points into, which must be that checkout's
|
|
45
|
-
# `plugin/` directory exactly.
|
|
46
|
-
# npm-install a real directory — FILES mode: every regular file
|
|
47
|
-
# marketplace-install a link into `.omp/plugins/cache/` — and every symlink
|
|
48
|
-
# under the five directories of the realpath.
|
|
49
|
-
#
|
|
50
|
-
# The kinds are named the way fleet-provenance names them, and told apart the
|
|
43
|
+
# THE KINDS are named the way fleet-provenance names them, and told apart the
|
|
51
44
|
# same way: the entry's own link-ness, then where the link resolves.
|
|
52
45
|
#
|
|
46
|
+
# npm-install a real directory.
|
|
47
|
+
# marketplace-install a link into `.omp/plugins/cache/`.
|
|
48
|
+
# linked-checkout any other link — `omp plugin link`. REFUSED, at pin
|
|
49
|
+
# and at check, exit 2 and nothing on stdout: a fleet
|
|
50
|
+
# run executes an installed package, and a linked
|
|
51
|
+
# checkout is a working tree that every checkout,
|
|
52
|
+
# merge and edit in it moves under the run. The link
|
|
53
|
+
# remains the dev loop for interactive sessions; the
|
|
54
|
+
# run needs it replaced by the package.
|
|
55
|
+
#
|
|
53
56
|
# Not a written list of instrument names — the
|
|
54
57
|
# ticket named six and the class is larger (the supply scan, the liveness
|
|
55
58
|
# probe, the shared `arg.mjs`/`json.sh`/`net.sh` libraries that a single edit
|
|
@@ -58,65 +61,38 @@
|
|
|
58
61
|
# already knows can be stale). A list rots on the next commit that adds a
|
|
59
62
|
# script; a directory does not.
|
|
60
63
|
#
|
|
61
|
-
# NOT THE WHOLE TREE, deliberately
|
|
62
|
-
#
|
|
63
|
-
# APPENDED BY THE CONTROLLER MID-RUN
|
|
64
|
-
#
|
|
65
|
-
#
|
|
66
|
-
# package's `package.json`, and everything else at its top level, stays out
|
|
67
|
-
# the same way: the set is the five directories in both modes.
|
|
68
|
-
#
|
|
69
|
-
# TRACKED in a checkout, EVERY FILE in a package, deliberately. A checkout
|
|
70
|
-
# counts tracked files only, because an untracked file appearing under those
|
|
71
|
-
# dirs — a `.DS_Store`, an editor swap file, a member's scratch output —
|
|
72
|
-
# changes no reading the controller takes, and refusing on it would fire the
|
|
73
|
-
# guard on ordinary runs. A guard the controller learns to ignore is worse
|
|
74
|
-
# than none. A package counts every file, dotfiles included, because nothing
|
|
75
|
-
# in it is untracked and anything in it executes.
|
|
64
|
+
# NOT THE WHOLE TREE, deliberately. A package's `package.json`, and everything
|
|
65
|
+
# else at its top level, stays out: the set is the five directories. The
|
|
66
|
+
# state home's `docs/metrics/` is APPENDED BY THE CONTROLLER MID-RUN and is
|
|
67
|
+
# not under the Install root at all, so the run's own bookkeeping cannot fire
|
|
68
|
+
# the gate — a guard the controller learns to ignore is worse than none.
|
|
76
69
|
#
|
|
77
|
-
# CONTENT, not
|
|
78
|
-
#
|
|
79
|
-
# `
|
|
80
|
-
#
|
|
81
|
-
# through it — so a dangling link, or a link to a directory, cannot be hashed
|
|
82
|
-
# and refuses at exit 2.
|
|
70
|
+
# CONTENT, not a stat cache: this hashes bytes, so it accepts a bare `touch`
|
|
71
|
+
# and refuses a rewrite. A symlink is hashed by its target's bytes —
|
|
72
|
+
# `shasum` reads through it — so a dangling link, or a link to a directory,
|
|
73
|
+
# cannot be hashed and refuses at exit 2.
|
|
83
74
|
#
|
|
84
75
|
# MODES ARE NOT IN THE DIGEST, and that one is a GAP rather than a trade: a
|
|
85
|
-
# mode-only change to
|
|
86
|
-
#
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
# is caught instead: `chmod 000` on a tracked instrument refuses at exit 2
|
|
90
|
-
# through `could not hash every tracked file` — as root that never fires,
|
|
76
|
+
# mode-only change to an instrument is ACCEPTED. Measured — `chmod +x` on a
|
|
77
|
+
# mode-644 file under the set exits 0 here. A mode change that costs the
|
|
78
|
+
# hash its READ is caught instead: `chmod 000` on an instrument refuses at
|
|
79
|
+
# exit 2 through `could not hash every file` — as root that never fires,
|
|
91
80
|
# since root reads a mode-000 file regardless (the suite skips
|
|
92
81
|
# this case there for the same reason). So the exposure is the bits that
|
|
93
82
|
# still permit reading, the exec bit above all — and that bit is not how a
|
|
94
83
|
# fleet probe runs: fleet-run hands `.sh` to `sh` and `.mjs` to `node`, so a
|
|
95
84
|
# stripped `+x` is invisible through the Resolver, while invoking one by path
|
|
96
85
|
# instead is EACCES at exec (126), loud rather than a wrong verdict. Folding
|
|
97
|
-
# modes in
|
|
98
|
-
# `[ -x "$f" ]` — is a behaviour change to the gate on a channel with no
|
|
86
|
+
# modes in is a behaviour change to the gate on a channel with no
|
|
99
87
|
# silently wrong reading to its name, and whether a mode-only edit is worth
|
|
100
88
|
# refusing on is a decision rather than a fix, so this paragraph names the gap and
|
|
101
|
-
# leaves the behaviour alone. The suite pins the accepted
|
|
89
|
+
# leaves the behaviour alone. The suite pins the accepted case,
|
|
102
90
|
# so closing the gap later goes red there rather than leaving this
|
|
103
91
|
# paragraph stale.
|
|
104
92
|
#
|
|
105
|
-
#
|
|
106
|
-
#
|
|
107
|
-
#
|
|
108
|
-
# ref write, which no hash of files can see. But `claim-ticket.sh` creates a
|
|
109
|
-
# branch per ticket and `reap.sh` deletes them, in the ref store every worktree
|
|
110
|
-
# shares, so a ref digest changes several times per pass as ORDINARY WORK. Per
|
|
111
|
-
# gate that is noise, and noise is the one failure this check cannot afford.
|
|
112
|
-
# Sweeping for unexpected refs is a drain-cadence question, not a gate one.
|
|
113
|
-
#
|
|
114
|
-
# COST: one `git rev-parse` to locate the state home, one listing of the set
|
|
115
|
-
# (`git ls-files` in git mode, `find` in files mode), a second `git rev-parse`
|
|
116
|
-
# in git mode to find the linked checkout, and one pass of `shasum` over those
|
|
117
|
-
# files; a pin in git mode also reads HEAD, a git-mode check that finds a
|
|
118
|
-
# change runs git again to report it, and a files-mode pin or changed check
|
|
119
|
-
# runs `awk` once to read the package's version. No network, no `gh`, no
|
|
93
|
+
# COST: one `git rev-parse` to locate the state home, one `find` over the set
|
|
94
|
+
# and one pass of `shasum` over those files; a pin or a changed check runs
|
|
95
|
+
# `awk` once to read the package's version. No network, no `gh`, no
|
|
120
96
|
# fetch, no subprocess per file. It is meant to be run
|
|
121
97
|
# before every gate decision and it has to be cheap enough that nobody is
|
|
122
98
|
# tempted to skip it.
|
|
@@ -129,26 +105,23 @@ set -eu
|
|
|
129
105
|
# Here the only constraint left is the real one: above the first git call.
|
|
130
106
|
#
|
|
131
107
|
# GIT_WORK_TREE is the wrong-tree defect reached through the environment. The
|
|
132
|
-
# contract here is that the state home is the WORKING DIRECTORY's checkout
|
|
133
|
-
#
|
|
134
|
-
#
|
|
135
|
-
#
|
|
136
|
-
#
|
|
137
|
-
#
|
|
138
|
-
#
|
|
108
|
+
# contract here is that the state home is the WORKING DIRECTORY's checkout —
|
|
109
|
+
# and `git rev-parse --show-toplevel` answers with the ambient work tree
|
|
110
|
+
# instead the moment one is set, `--repo` or not. Measured:
|
|
111
|
+
# standing in a checkout whose baseline is honest, with
|
|
112
|
+
# `GIT_WORK_TREE` naming a twin whose own pinned baseline matches the
|
|
113
|
+
# tampered Install root, this script exits 0 and prints the tampered digest.
|
|
114
|
+
# The gate passes. That is
|
|
139
115
|
# the same wrong-tree write `--repo ""` produced before this script refused it, one
|
|
140
116
|
# door further out, and a gate that certifies a tree nobody looked at is
|
|
141
117
|
# worse than no gate.
|
|
142
118
|
#
|
|
143
|
-
# GIT_DIR is unset alongside it and is measured INERT here:
|
|
144
|
-
#
|
|
145
|
-
#
|
|
146
|
-
#
|
|
147
|
-
# back unchanged and the gate still refused. It stays on the line because the
|
|
119
|
+
# GIT_DIR is unset alongside it and is measured INERT here: the only git call
|
|
120
|
+
# is `rev-parse --show-toplevel`, and the digest is taken over the FILES ON
|
|
121
|
+
# DISK under the Install root, so pointing the object database elsewhere
|
|
122
|
+
# changes nothing. It stays on the line because the
|
|
148
123
|
# pair is one hazard with one remedy, and because "inert today" is a
|
|
149
|
-
# measurement of the current call set
|
|
150
|
-
# `cat-file` rather than from disk would reintroduce the half nothing here
|
|
151
|
-
# can see. The suite pins the line itself, which is
|
|
124
|
+
# measurement of the current call set. The suite pins the line itself, which is
|
|
152
125
|
# what keeps that half from being quietly dropped.
|
|
153
126
|
unset GIT_DIR GIT_WORK_TREE
|
|
154
127
|
|
|
@@ -209,6 +182,42 @@ else
|
|
|
209
182
|
fi
|
|
210
183
|
base="$root/.fleet/instruments.sha"
|
|
211
184
|
|
|
185
|
+
# The Install root, resolved inline on every pin and every check: the same
|
|
186
|
+
# path fleet-run, fleet-provenance and fleet-bootstrap resolve, the same way —
|
|
187
|
+
# the package entry's own link-ness for the kind, its realpath for the tree.
|
|
188
|
+
# Mirrored rather than called. The placed `~/.fleet/bin/fleet-run` can drift
|
|
189
|
+
# from the package, and an environment override or a `node` call would be a
|
|
190
|
+
# second way to name a tree the fleet does not execute.
|
|
191
|
+
#
|
|
192
|
+
# HOME is checked by hand because `set -u` does not answer for it: measured,
|
|
193
|
+
# macOS `/bin/sh` exits 1 on an unset HOME under `set -eu`, and exit 1 is the
|
|
194
|
+
# one code that means the set changed.
|
|
195
|
+
[ -n "${HOME:-}" ] || die "HOME is unset — cannot resolve the Install root"
|
|
196
|
+
entry="$HOME/.omp/plugins/node_modules/@feigi/fleet-ctl"
|
|
197
|
+
if [ -L "$entry" ]; then
|
|
198
|
+
[ -e "$entry" ] || die "omp plugin \"@feigi/fleet-ctl\" link $entry is dangling"
|
|
199
|
+
live=$(CDPATH='' cd -P "$entry" && pwd -P) \
|
|
200
|
+
|| die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
|
|
201
|
+
case $live in
|
|
202
|
+
*/.omp/plugins/cache/*) kind=marketplace-install ;;
|
|
203
|
+
*) kind=linked-checkout ;;
|
|
204
|
+
esac
|
|
205
|
+
else
|
|
206
|
+
[ -e "$entry" ] || die "no omp plugin \"@feigi/fleet-ctl\" at $entry"
|
|
207
|
+
live=$(CDPATH='' cd -P "$entry" && pwd -P) \
|
|
208
|
+
|| die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
|
|
209
|
+
kind=npm-install
|
|
210
|
+
fi
|
|
211
|
+
|
|
212
|
+
# A linked checkout is refused, at pin and at check, before anything is read
|
|
213
|
+
# from or written to the state home and before anything is hashed. A fleet run
|
|
214
|
+
# executes an installed package: a link's tree moves under the run with every
|
|
215
|
+
# checkout, merge and edit in it, which no digest can tell from tampering. The
|
|
216
|
+
# controller never runs `omp plugin`; the message is for the maintainer.
|
|
217
|
+
if [ "$kind" = linked-checkout ]; then
|
|
218
|
+
die "Install root $live is a linked checkout (omp plugin link) — a fleet run executes an installed package; omp plugin uninstall @feigi/fleet-ctl, then omp plugin install @feigi/fleet-ctl, and restart."
|
|
219
|
+
fi
|
|
220
|
+
|
|
212
221
|
if [ "$pin" != true ]; then
|
|
213
222
|
# No baseline is not "nothing has changed" — it is a run that never pinned,
|
|
214
223
|
# and the check has nothing to compare against. Refusing is the whole
|
|
@@ -241,51 +250,9 @@ if [ "$pin" != true ]; then
|
|
|
241
250
|
[ -n "$want" ] || die "$base is empty — re-pin, do not guess"
|
|
242
251
|
fi
|
|
243
252
|
|
|
244
|
-
# The
|
|
245
|
-
# path fleet-run, fleet-provenance and fleet-bootstrap resolve, the same way —
|
|
246
|
-
# the package entry's own link-ness for the kind, its realpath for the tree.
|
|
247
|
-
# Mirrored rather than called. The placed `~/.fleet/bin/fleet-run` can drift
|
|
248
|
-
# from the package, and an environment override or a `node` call would be a
|
|
249
|
-
# second way to name a tree the fleet does not execute.
|
|
250
|
-
#
|
|
251
|
-
# HOME is checked by hand because `set -u` does not answer for it: measured,
|
|
252
|
-
# macOS `/bin/sh` exits 1 on an unset HOME under `set -eu`, and exit 1 is the
|
|
253
|
-
# one code that means the set changed.
|
|
254
|
-
[ -n "${HOME:-}" ] || die "HOME is unset — cannot resolve the Install root"
|
|
255
|
-
entry="$HOME/.omp/plugins/node_modules/@feigi/fleet-ctl"
|
|
256
|
-
if [ -L "$entry" ]; then
|
|
257
|
-
[ -e "$entry" ] || die "omp plugin \"@feigi/fleet-ctl\" link $entry is dangling"
|
|
258
|
-
live=$(CDPATH='' cd -P "$entry" && pwd -P) \
|
|
259
|
-
|| die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
|
|
260
|
-
case $live in
|
|
261
|
-
*/.omp/plugins/cache/*) kind=marketplace-install ;;
|
|
262
|
-
*) kind=linked-checkout ;;
|
|
263
|
-
esac
|
|
264
|
-
else
|
|
265
|
-
[ -e "$entry" ] || die "no omp plugin \"@feigi/fleet-ctl\" at $entry"
|
|
266
|
-
live=$(CDPATH='' cd -P "$entry" && pwd -P) \
|
|
267
|
-
|| die "cannot resolve omp plugin \"@feigi/fleet-ctl\" at $entry"
|
|
268
|
-
kind=npm-install
|
|
269
|
-
fi
|
|
270
|
-
|
|
271
|
-
# A linked checkout is certified as the checkout it is — git mode, over the
|
|
272
|
-
# toplevel, the tree and the shape a checkout's pin has always been made over
|
|
273
|
-
# — and only when the link points at that checkout's `plugin/` directory
|
|
274
|
-
# exactly. A link to the checkout's root, to a nested copy of `plugin/`, or to
|
|
275
|
-
# a directory outside any checkout names a tree whose tracked set is not the
|
|
276
|
-
# one the fleet executes, so it refuses rather than guess which it meant.
|
|
253
|
+
# The five component directories, as the digest lists them.
|
|
277
254
|
dirs='commands scripts skills agents workflows'
|
|
278
|
-
|
|
279
|
-
for d in $dirs; do set="${set:+$set }plugin/$d"; done
|
|
280
|
-
if [ "$kind" = linked-checkout ]; then
|
|
281
|
-
mode=git
|
|
282
|
-
badlink="Install root $live is not the plugin/ directory of a git checkout — a linked install must point at <checkout>/plugin"
|
|
283
|
-
target=$(git -C "$live" rev-parse --show-toplevel 2>/dev/null) || die "$badlink"
|
|
284
|
-
[ "$live" = "$target/plugin" ] || die "$badlink"
|
|
285
|
-
else
|
|
286
|
-
mode=files
|
|
287
|
-
target=$live
|
|
288
|
-
fi
|
|
255
|
+
target=$live
|
|
289
256
|
|
|
290
257
|
# The top-level "version" of the package's `package.json`, or nothing. It is
|
|
291
258
|
# evidence for a refusal to name, never part of a verdict, so a file that is
|
|
@@ -354,37 +321,27 @@ files=$(mktemp) || die "cannot create a temp file"
|
|
|
354
321
|
trap 'rm -f "$files"' EXIT
|
|
355
322
|
trap 'rm -f "$files"; exit 2' INT HUP TERM
|
|
356
323
|
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
# lists in directory order, which is the filesystem's to choose, so the
|
|
379
|
-
# sort is what makes the digest a function of the tree alone. Two steps
|
|
380
|
-
# with a status check each, for the reason the hashing below spells out.
|
|
381
|
-
# shellcheck disable=SC2086 # $present is a list of fixed directory names
|
|
382
|
-
(cd "$target" && find $present \( -type f -o -type l \) -print0) > "$files" \
|
|
383
|
-
|| die "could not list every file under $target for: $dirs"
|
|
384
|
-
LC_ALL=C sort -z -o "$files" "$files" \
|
|
385
|
-
|| die "could not sort the instrument set under $target"
|
|
386
|
-
[ -s "$files" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
|
|
387
|
-
fi
|
|
324
|
+
# Absent directories are skipped, but a name that is present in any form
|
|
325
|
+
# — a file, a dangling link — is listed, so it reaches `shasum` and refuses
|
|
326
|
+
# there rather than vanishing from the set. With none present there is
|
|
327
|
+
# nothing to certify, and `find` given no path would list `.` instead.
|
|
328
|
+
present=
|
|
329
|
+
for d in $dirs; do
|
|
330
|
+
if [ -e "$target/$d" ] || [ -L "$target/$d" ]; then
|
|
331
|
+
present="$present $d"
|
|
332
|
+
fi
|
|
333
|
+
done
|
|
334
|
+
[ -n "$present" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
|
|
335
|
+
# Paths relative to the realpath, NUL-separated, in byte order: `find`
|
|
336
|
+
# lists in directory order, which is the filesystem's to choose, so the
|
|
337
|
+
# sort is what makes the digest a function of the tree alone. Two steps
|
|
338
|
+
# with a status check each, for the reason the hashing below spells out.
|
|
339
|
+
# shellcheck disable=SC2086 # $present is a list of fixed directory names
|
|
340
|
+
(cd "$target" && find $present \( -type f -o -type l \) -print0) > "$files" \
|
|
341
|
+
|| die "could not list every file under $target for: $dirs"
|
|
342
|
+
LC_ALL=C sort -z -o "$files" "$files" \
|
|
343
|
+
|| die "could not sort the instrument set under $target"
|
|
344
|
+
[ -s "$files" ] || die "no file under $target for: $dirs — refusing to certify an empty instrument set"
|
|
388
345
|
|
|
389
346
|
# Two steps, each with its own status check, because a pipeline reports only its
|
|
390
347
|
# LAST command: with `xargs … | shasum` as one pipeline, a `shasum` that cannot
|
|
@@ -393,45 +350,37 @@ fi
|
|
|
393
350
|
# — a verdict about the tree — off a failure to look. reap.sh shipped this exact
|
|
394
351
|
# bug against `git cherry` and it deleted branches.
|
|
395
352
|
#
|
|
396
|
-
# `xargs` exits 123 when `shasum` failed on any file
|
|
397
|
-
#
|
|
398
|
-
#
|
|
353
|
+
# `xargs` exits 123 when `shasum` failed on any file — a dangling link, or a
|
|
354
|
+
# link to a directory, or a file that cannot be read — as exit 2 naming it,
|
|
355
|
+
# not as a digest quietly missing a line. Both
|
|
399
356
|
# refuse; only one of them is honest about why.
|
|
400
357
|
per_file=$(cd "$target" && xargs -0 shasum -a 256 < "$files") \
|
|
401
|
-
|| die "could not hash every
|
|
358
|
+
|| die "could not hash every file under $target — see the errors above"
|
|
402
359
|
digest=$(printf '%s\n' "$per_file" | shasum -a 256 | cut -d' ' -f1) \
|
|
403
360
|
|| die "could not digest the instrument set"
|
|
404
361
|
[ -n "$digest" ] || die "empty digest for $target"
|
|
405
362
|
|
|
406
363
|
if [ "$pin" = true ]; then
|
|
407
364
|
mkdir -p "$root/.fleet" || die "cannot create $root/.fleet"
|
|
408
|
-
# Three lines, order fixed: the digest first, the certified tree
|
|
409
|
-
#
|
|
410
|
-
# in git mode, the package's version in files mode. A reader that only
|
|
365
|
+
# Three lines at most, order fixed: the digest first, the certified tree
|
|
366
|
+
# second, and third the package's version. A reader that only
|
|
411
367
|
# knows the old one-line shape — merge-gate.mjs's `readInstruments`, which
|
|
412
368
|
# takes the FIRST stdout line as the digest — keeps working, and a check
|
|
413
369
|
# from this script reads the rest. The root rides in the same write as the
|
|
414
370
|
# digest so a check can tell the Install root moved; the check compares it
|
|
415
371
|
# and never follows it.
|
|
416
372
|
#
|
|
417
|
-
#
|
|
418
|
-
# refusal can say what moved.
|
|
419
|
-
#
|
|
420
|
-
|
|
421
|
-
if [ "$mode" = git ]; then
|
|
422
|
-
key=commit
|
|
423
|
-
val=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || val=
|
|
424
|
-
else
|
|
425
|
-
key=version
|
|
426
|
-
val=$(pkg_version)
|
|
427
|
-
fi
|
|
373
|
+
# The version line is not trusted for any verdict: it exists only so a
|
|
374
|
+
# refusal can say what moved. A package with no readable version writes no
|
|
375
|
+
# `version=` line, and the refusal says so.
|
|
376
|
+
val=$(pkg_version)
|
|
428
377
|
{
|
|
429
378
|
printf '%s\n' "$digest"
|
|
430
379
|
printf 'root=%s\n' "$target"
|
|
431
|
-
[ -z "$val" ] || printf '
|
|
380
|
+
[ -z "$val" ] || printf 'version=%s\n' "$val"
|
|
432
381
|
} > "$base" || die "cannot write $base"
|
|
433
382
|
printf '%s\n' "$digest"
|
|
434
|
-
printf '%s: pinned %s over %s %s (
|
|
383
|
+
printf '%s: pinned %s over %s %s (version %s)\n' "$NAME" "$digest" "$kind" "$target" "${val:-?}" >&2
|
|
435
384
|
exit 0
|
|
436
385
|
fi
|
|
437
386
|
|
|
@@ -449,73 +398,8 @@ printf '%s: refuse the gate and report. Do NOT re-read the instrument.\n' "$NAME
|
|
|
449
398
|
# changed: the versions are what the maintainer rules on — adopt what is
|
|
450
399
|
# installed, or put the pinned version back. Never the controller: a
|
|
451
400
|
# reinstall swaps the files every live member is running.
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
printf '%s: the installed package changed or was reinstalled — the maintainer adopts it (re-pin) or restores version %s\n' "$NAME" "${pinv:-?}" >&2
|
|
457
|
-
exit 1
|
|
458
|
-
fi
|
|
459
|
-
|
|
460
|
-
# A checkout: `git status` names the uncommitted half, which is the shape
|
|
461
|
-
# this header's measured near-miss took; a checked-out branch that moved
|
|
462
|
-
# shows as nothing here and the HEAD line is what names it.
|
|
463
|
-
headc=$(git -C "$target" rev-parse --verify --quiet HEAD 2>/dev/null) || headc=
|
|
464
|
-
printf '%s: HEAD %s\n' "$NAME" "${headc:-?}" >&2
|
|
465
|
-
# shellcheck disable=SC2086 # $set is a deliberate list of pathspecs, not one path
|
|
466
|
-
git -C "$target" status --porcelain -- $set >&2 || true
|
|
467
|
-
|
|
468
|
-
# Then what moved, relative to the commit the pin recorded. Only the commit
|
|
469
|
-
# graph can say whether HEAD advanced, rewound or diverged, and the maintainer
|
|
470
|
-
# decides what to do about each, so this names the relation and stops: the
|
|
471
|
-
# verdict above is already refusal. Anything but a full hex id is treated as
|
|
472
|
-
# absent from the repository, so a baseline line cannot reach git as an option.
|
|
473
|
-
pinc=$(baseline_field commit)
|
|
474
|
-
present=false
|
|
475
|
-
case $pinc in
|
|
476
|
-
*[!0-9a-f]*) ;;
|
|
477
|
-
*) if { [ "${#pinc}" -eq 40 ] || [ "${#pinc}" -eq 64 ]; } \
|
|
478
|
-
&& git -C "$target" cat-file -e "$pinc^{commit}" 2>/dev/null; then
|
|
479
|
-
present=true
|
|
480
|
-
fi ;;
|
|
481
|
-
esac
|
|
482
|
-
if [ -z "$pinc" ]; then
|
|
483
|
-
printf '%s: pin commit not recorded — the baseline has no commit= line\n' "$NAME" >&2
|
|
484
|
-
elif [ "$present" != true ]; then
|
|
485
|
-
printf '%s: pin commit %s is not in the repository\n' "$NAME" "$pinc" >&2
|
|
486
|
-
elif [ -z "$headc" ]; then
|
|
487
|
-
printf '%s: pin commit %s; HEAD cannot be read\n' "$NAME" "$pinc" >&2
|
|
488
|
-
else
|
|
489
|
-
printf '%s: pin commit %s\n' "$NAME" "$pinc" >&2
|
|
490
|
-
if [ "$headc" = "$pinc" ]; then
|
|
491
|
-
printf '%s: HEAD unmoved — HEAD is the pin commit\n' "$NAME" >&2
|
|
492
|
-
else
|
|
493
|
-
# `--is-ancestor` answers with its exit code: 0 is yes and 1 is no. Any
|
|
494
|
-
# other code is git failing to compare — an unreadable object, a corrupt
|
|
495
|
-
# history — and a relation read off that failure would hand the
|
|
496
|
-
# maintainer a false fact to rule on, so it says unknown and lets git's
|
|
497
|
-
# own error through.
|
|
498
|
-
fwd=0
|
|
499
|
-
git -C "$target" merge-base --is-ancestor "$pinc" "$headc" || fwd=$?
|
|
500
|
-
back=1
|
|
501
|
-
if [ "$fwd" -eq 1 ]; then
|
|
502
|
-
back=0
|
|
503
|
-
git -C "$target" merge-base --is-ancestor "$headc" "$pinc" || back=$?
|
|
504
|
-
fi
|
|
505
|
-
if [ "$fwd" -eq 0 ]; then
|
|
506
|
-
printf '%s: HEAD advanced — the pin commit is an ancestor of HEAD\n' "$NAME" >&2
|
|
507
|
-
git --no-pager -C "$target" log --no-decorate --no-color --oneline -n 20 "$pinc..$headc" >&2 || true
|
|
508
|
-
between=$(git -C "$target" rev-list --count "$pinc..$headc" 2>/dev/null || printf 0)
|
|
509
|
-
if [ "$between" -gt 20 ]; then
|
|
510
|
-
printf '… %s more\n' "$((between - 20))" >&2
|
|
511
|
-
fi
|
|
512
|
-
elif [ "$fwd" -eq 1 ] && [ "$back" -eq 0 ]; then
|
|
513
|
-
printf '%s: HEAD rewound — HEAD is an ancestor of the pin commit\n' "$NAME" >&2
|
|
514
|
-
elif [ "$fwd" -eq 1 ] && [ "$back" -eq 1 ]; then
|
|
515
|
-
printf '%s: HEAD diverged — neither is an ancestor of the other\n' "$NAME" >&2
|
|
516
|
-
else
|
|
517
|
-
printf '%s: HEAD relation unknown — git could not compare the pin commit with HEAD\n' "$NAME" >&2
|
|
518
|
-
fi
|
|
519
|
-
fi
|
|
520
|
-
fi
|
|
401
|
+
pinv=$(baseline_field version) || pinv=
|
|
402
|
+
nowv=$(pkg_version)
|
|
403
|
+
printf '%s: %s %s: version %s pinned, %s now\n' "$NAME" "$kind" "$target" "${pinv:-?}" "${nowv:-?}" >&2
|
|
404
|
+
printf '%s: the installed package changed or was reinstalled — the maintainer adopts it (re-pin) or restores version %s\n' "$NAME" "${pinv:-?}" >&2
|
|
521
405
|
exit 1
|
|
@@ -40,8 +40,9 @@
|
|
|
40
40
|
// fleet-run executes scripts from and omp loads the runbooks from — the
|
|
41
41
|
// root itself included. No gitignore exemption: nothing under it is a
|
|
42
42
|
// member's to write. It holds whichever repository the session runs in,
|
|
43
|
-
// or none, and for every install kind
|
|
44
|
-
// Install root
|
|
43
|
+
// or none, and for every install kind. A fleet run refuses a linked
|
|
44
|
+
// Install root (instruments.sh), but an interactive session may still
|
|
45
|
+
// link a checkout, whose Install root is then that checkout's `plugin/`.
|
|
45
46
|
// - `bash` cwd, for every `fleet-implementer-<cell>` (ledger-grammar.mjs's
|
|
46
47
|
// `CELL_DEF`), and for a fix-applier's own id (`fix-pr-<n>`) directly,
|
|
47
48
|
// since its definition, `fleet-fix-applier`, is no implementer cell and
|
package/scripts/phase0.mjs
CHANGED
|
@@ -17,8 +17,8 @@
|
|
|
17
17
|
// Reached through the Resolver and run from the MAIN checkout (a linked
|
|
18
18
|
// worktree refuses: the checks below judge the checkout the controller reads
|
|
19
19
|
// its rules from). The steps, each a named entry in the receipt, run in
|
|
20
|
-
// this order because the order is the point — the pin
|
|
21
|
-
// fast-forward
|
|
20
|
+
// this order because the order is the point — the pin is recorded after the
|
|
21
|
+
// fast-forward, the rotation comes before the fold-in, the scratch
|
|
22
22
|
// reclaim straight after the rotation, the metrics refresh before the first
|
|
23
23
|
// Pull is routed:
|
|
24
24
|
//
|
|
@@ -29,12 +29,15 @@
|
|
|
29
29
|
// on a branch whose PR has merged would fast-forward that branch
|
|
30
30
|
// and the baseline would record it as the run's ref.
|
|
31
31
|
// fast-forward `git fetch origin`, `rev-list --count main..origin/main`,
|
|
32
|
-
// `merge --ff-only origin/main`. HEAD moving
|
|
33
|
-
//
|
|
34
|
-
//
|
|
35
|
-
//
|
|
32
|
+
// `merge --ff-only origin/main`. HEAD moving is ok, the count
|
|
33
|
+
// in the output. It still runs because the workspace's own
|
|
34
|
+
// tracked files (`docs/metrics/*`, its docs and CI-facing
|
|
35
|
+
// files) must be at origin/main and the baseline is recorded
|
|
36
|
+
// after it; the rules come from the installed package, which
|
|
37
|
+
// a fast-forward does not touch.
|
|
36
38
|
// pin `instruments.sh --pin`, which certifies the Install root; the
|
|
37
|
-
// ok line names its kind, root
|
|
39
|
+
// ok line names its kind, root and version. A linked
|
|
40
|
+
// checkout refuses: a fleet run executes an installed package.
|
|
38
41
|
// baseline `main-checkout.mjs --record`; its refusals fail the step.
|
|
39
42
|
// labels `label-map.mjs ensure`, the Label map derivation step. Exit 0
|
|
40
43
|
// is ok, its output the map ensure printed. Exit 3 is pending,
|
|
@@ -236,13 +239,13 @@ function fastForward({ cwd }) {
|
|
|
236
239
|
if (behind === 0) return ok("main is level with origin/main");
|
|
237
240
|
const merge = run("git", ["merge", "--ff-only", "origin/main"], { cwd });
|
|
238
241
|
if (merge.status !== 0) return refusal("git merge --ff-only origin/main failed:", merge);
|
|
239
|
-
return
|
|
242
|
+
return ok(`fast-forwarded ${behind} commits to origin/main`);
|
|
240
243
|
}
|
|
241
244
|
|
|
242
245
|
function pin({ cwd }) {
|
|
243
246
|
const r = sh("instruments.sh", ["--pin"], { cwd });
|
|
244
247
|
if (r.status !== 0) return refusal("instruments.sh --pin failed:", r);
|
|
245
|
-
// `instruments: pinned <digest> over <kind> <root> (version <v
|
|
248
|
+
// `instruments: pinned <digest> over <kind> <root> (version <v>)`
|
|
246
249
|
const m = /^instruments: pinned [0-9a-f]+ over (.+)$/m.exec(r.stderr);
|
|
247
250
|
return ok(`instruments pinned: ${m ? m[1] : r.stderr || "?"}`);
|
|
248
251
|
}
|
package/scripts/reap.sh
CHANGED
|
@@ -1299,17 +1299,12 @@ for b in $gone_branches; do
|
|
|
1299
1299
|
# `git_probe`'s stderr capture reach it: the config yields rc 0, empty
|
|
1300
1300
|
# stdout AND empty stderr, so there is nothing for `gp_cut_short` to
|
|
1301
1301
|
# match. Pinning the mode on the command line is the only fix: a probe
|
|
1302
|
-
# whose EMPTY answer licenses an action pins an explicit mode
|
|
1303
|
-
#
|
|
1304
|
-
# below). `git worktree remove`'s own refusal is no backstop, being the
|
|
1302
|
+
# whose EMPTY answer licenses an action pins an explicit mode.
|
|
1303
|
+
# `git worktree remove`'s own refusal is no backstop, being the
|
|
1305
1304
|
# same machinery the same config silences (measured at the --apply call
|
|
1306
1305
|
# below).
|
|
1307
1306
|
#
|
|
1308
|
-
#
|
|
1309
|
-
# instruments.sh prints one to stderr to say WHAT changed, after a digest
|
|
1310
|
-
# over `git ls-files` has already refused. That digest covers TRACKED
|
|
1311
|
-
# files only, so no untracked file can trigger it and the silenced mode
|
|
1312
|
-
# cannot hide the thing being reported. A report, not a gate. (Prose
|
|
1307
|
+
# No script carries a bare `--porcelain`. (Prose
|
|
1313
1308
|
# instructions to an agent are a separate inventory — see SKILL.md,
|
|
1314
1309
|
# pinned alongside the scripts.)
|
|
1315
1310
|
#
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -24,7 +24,7 @@ These hold in every phase: check each wake against them, and report evidence tha
|
|
|
24
24
|
- A grandchild surfaces as its own task-notification; an unrecognized task-id is not a member reporting done.
|
|
25
25
|
- A reviewer never reviews a PR it implemented.
|
|
26
26
|
- The merge bot only touches PRs whose implementer reported done; rebasing a worktree someone is working in destroys uncommitted work.
|
|
27
|
-
- `ready-to-merge` is added by a reviewer only — never an implementer, never you
|
|
27
|
+
- `ready-to-merge` is added by a reviewer only — never an implementer, never you.
|
|
28
28
|
- Every member acts through the maintainer's `gh` credentials, so no write is attributable: when a label moves unexpectedly, ask members directly, rule out automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
|
|
29
29
|
- Phase 1 is serial; everything else may run concurrently.
|
|
30
30
|
|
|
@@ -193,9 +193,9 @@ owes beyond its call:
|
|
|
193
193
|
`ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
|
|
194
194
|
once the run is draining with no open PR and no live implementer.
|
|
195
195
|
3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"`, which
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
is a reviewed PR with no verdict row — for an implementer's, one that never
|
|
196
|
+
records `fleet-heartbeat.mjs --stop` and then merges the Close-out PR. On `NEED merge-wait PR #<n>`,
|
|
197
|
+
run `finish` again at once. A PR it names `left open` is the next run's: you never label or merge it.
|
|
198
|
+
A `NEED tier-outcomes append <pr>` is a reviewed PR with no verdict row — for an implementer's, one that never
|
|
199
199
|
reached its finisher: run `append <pr>` (**Guard: accumulate per PR**) and run `finish` again.
|
|
200
200
|
A PR closing none or several: a NEED if a settled `impl-<N>=PR#<pr>` token
|
|
201
201
|
names it, else a note. A step it fails is explained in
|
|
@@ -699,22 +699,16 @@ you cannot confirm was received, re-check the artifacts it governed. See referen
|
|
|
699
699
|
- **Re-pin only on the maintainer's adopt.** Nothing you change yourself is a
|
|
700
700
|
reason: a tooling defect is reported, never fixed by you. Re-pinning to clear
|
|
701
701
|
a refusal you cannot explain discards the check.
|
|
702
|
-
- **A
|
|
703
|
-
it
|
|
704
|
-
or
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
the
|
|
711
|
-
|
|
712
|
-
only when the pinned tree is the main checkout and the tick prints no
|
|
713
|
-
`MAIN-CHECKOUT` line; otherwise they restore it by hand, and an installed
|
|
714
|
-
package always: never run `omp plugin` yourself, because a reinstall swaps the
|
|
715
|
-
files every live member is running. On their **adopt**, re-pin. Once the
|
|
716
|
-
check exits 0, resume, and apply the finisher gate to each PR whose finisher
|
|
717
|
-
halted on that refusal. See references/instruments.md.
|
|
702
|
+
- **A changed installed plugin is the maintainer's to settle, whoever changed
|
|
703
|
+
it.** When a refusal — your check or a finisher's halt — names a changed
|
|
704
|
+
package or an Install root that now resolves elsewhere, never re-pin over it,
|
|
705
|
+
even for an upgrade to a release of this run's own PRs. Act on no `DISPATCH` or
|
|
706
|
+
`PULL` row, and tell the maintainer what the refusal printed: the pinned and
|
|
707
|
+
current Install root and version. On their **restore** they reinstall the
|
|
708
|
+
pinned version by hand: never run `omp plugin` yourself, because a reinstall
|
|
709
|
+
swaps the files every live member is running. On their **adopt**, re-pin.
|
|
710
|
+
Once the check exits 0, resume, and apply the finisher gate to each PR whose
|
|
711
|
+
finisher halted on that refusal. See references/instruments.md.
|
|
718
712
|
|
|
719
713
|
### Relabel causes
|
|
720
714
|
|
|
@@ -20,9 +20,11 @@
|
|
|
20
20
|
3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
|
|
21
21
|
the run's member facts, checks the tier-outcomes rows, refreshes the
|
|
22
22
|
metrics, commits the three metrics files and opens their PR, sets the
|
|
23
|
-
phase-0 receipt aside as `.fleet/phase0.previous.json`,
|
|
24
|
-
`fleet-heartbeat.mjs --stop
|
|
25
|
-
|
|
23
|
+
phase-0 receipt aside as `.fleet/phase0.previous.json`, records
|
|
24
|
+
`fleet-heartbeat.mjs --stop`, because every reader takes a recorded stop
|
|
25
|
+
as the end of the run, and then merges the Close-out PR. On `NEED
|
|
26
|
+
merge-wait PR #<n>`, run `finish` again at once. A PR it names `left open`
|
|
27
|
+
is the next run's: you never label or merge it. A `NEED tier-outcomes append <pr>` is a
|
|
26
28
|
reviewed PR with no verdict row — for an implementer's PR, one that never
|
|
27
29
|
reached its finisher, since `ledger.mjs dispatch` refuses that finisher
|
|
28
30
|
until the row exists: run `append <pr>` (**Guard: accumulate per PR**) and run `finish` again. A reviewed
|
|
@@ -9,8 +9,7 @@ Evidence for the rule SKILL.md states in **Re-check the instruments before a gat
|
|
|
9
9
|
**You read your instruments out of a tree every member can write to — re-check
|
|
10
10
|
them before every gate decision.** Per-member worktrees and `./agent-test`'s port
|
|
11
11
|
derivation protect members from each other; neither protects the Install root,
|
|
12
|
-
the tree you run every gate probe out of and read these runbooks from.
|
|
13
|
-
the main checkout only when that checkout is linked as the install. The
|
|
12
|
+
the tree you run every gate probe out of and read these runbooks from. The
|
|
14
13
|
`member-write-guard` extension refuses a `write`/`edit`/`ast_edit` into the
|
|
15
14
|
Install root, as it does into the main checkout, but a `bash` or `eval` write
|
|
16
15
|
into the Install root still lands, and this re-check is what catches one.
|
|
@@ -34,8 +33,11 @@ in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge
|
|
|
34
33
|
|
|
35
34
|
It covers the Install root's plugin component directories — `commands/`,
|
|
36
35
|
`scripts/`, `skills/`, `agents/`, `workflows/` — the probes, the libraries they
|
|
37
|
-
source, and these runbooks, which you also read from that tree:
|
|
38
|
-
|
|
36
|
+
source, and these runbooks, which you also read from that tree: every file of
|
|
37
|
+
the installed package. A linked Install root (`omp plugin link`) is not covered
|
|
38
|
+
but refused, at the pin and at every check: a fleet run executes an installed
|
|
39
|
+
package, so the maintainer uninstalls the link and installs the package, and you
|
|
40
|
+
never run `omp plugin`.
|
|
39
41
|
Not the whole repo: `docs/metrics/` is appended by THIS run, so covering it
|
|
40
42
|
would refuse on the run's own bookkeeping every time. It does not cover refs,
|
|
41
43
|
deliberately: `claim-ticket.sh` creates a branch per ticket and `reap.sh`
|
|
@@ -92,58 +94,20 @@ defect reaches whenever it changes what that member does — live members now,
|
|
|
92
94
|
later ones right after their dispatch — and count a repeat of the same failure
|
|
93
95
|
as this defect, not a new trigger.
|
|
94
96
|
|
|
95
|
-
## A
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
and an exit-1 refusal names the pinned version and the current one, with no
|
|
112
|
-
git output. An Install root that now resolves elsewhere than the pinned one —
|
|
113
|
-
a reinstall that moved it, a switch between a package and a linked checkout,
|
|
114
|
-
a link pointed elsewhere — refuses at exit 2, naming the pinned root and the
|
|
115
|
-
current one. Restore is the maintainer reinstalling the pinned version by
|
|
116
|
-
hand, never the controller: a reinstall swaps the files under every live
|
|
117
|
-
member.
|
|
118
|
-
|
|
119
|
-
**The measured case.** Another session fast-forwarded the main checkout to
|
|
120
|
-
`origin/main` mid-run. The commits that brought in were only this run's own
|
|
121
|
-
merged PRs, the controller counted them as its own, re-pinned without asking and
|
|
122
|
-
dispatched the next finishers. The tick could not see the move: its
|
|
123
|
-
main-checkout guard reads a fast-forward to `origin/main` as clean, and the tick
|
|
124
|
-
never runs the instrument check. Only the gate re-checks saw it — a finisher
|
|
125
|
-
halting with cause `other`, the merge gate refusing with
|
|
126
|
-
`instrument-set-changed`. A refusal cannot tell a move the maintainer would
|
|
127
|
-
adopt from one they would not, because only they know whether a session of
|
|
128
|
-
theirs is working in that checkout, so the pin stays frozen and the move stays
|
|
129
|
-
a refusal even when the commits between are only the run's own.
|
|
130
|
-
|
|
131
|
-
**Why the reset is the controller's only on a clean tick.** A clean
|
|
132
|
-
main-checkout reading means HEAD is still on `main` and every commit since the
|
|
133
|
-
baseline is on `origin/main`. So `git reset --keep <pin commit>` moves no other
|
|
134
|
-
branch and drops nothing that exists only locally, and `--keep` refuses rather
|
|
135
|
-
than overwrite an uncommitted edit that conflicts with the move. On a switched
|
|
136
|
-
branch the guard prints `MAIN-CHECKOUT-DIRTY HEAD …`, and a reset there would
|
|
137
|
-
move that other branch, so the maintainer restores such a tree by hand.
|
|
138
|
-
|
|
139
|
-
Measured in a temp clone with the real `main-checkout.mjs` and
|
|
140
|
-
`instruments.sh`, the pin 3 commits behind `origin/main` and 4 set paths
|
|
141
|
-
different:
|
|
142
|
-
|
|
143
|
-
| Checkout state | Main-checkout guard | Instrument check |
|
|
144
|
-
|---|---|---|
|
|
145
|
-
| at the pin commit | clean | 0 |
|
|
146
|
-
| fast-forwarded to `origin/main` | clean | 1 |
|
|
147
|
-
| after `git reset --keep <pin commit>` | clean | 0 |
|
|
148
|
-
| on another branch | `MAIN-CHECKOUT-DIRTY HEAD refs/heads/main@… → refs/heads/other@…` | 1 |
|
|
97
|
+
## A changed installed plugin is the maintainer's to settle
|
|
98
|
+
|
|
99
|
+
**An installed package has no HEAD.** `instruments.sh --pin` records the
|
|
100
|
+
package's `version=` after the digest and `root=`, and an exit-1 refusal names
|
|
101
|
+
the pinned version and the current one, with no git output. An Install root
|
|
102
|
+
that now resolves elsewhere than the pinned one — a reinstall that moved it, a
|
|
103
|
+
move into omp's cache, a baseline from an older plugin that recorded a checkout
|
|
104
|
+
— refuses at exit 2, naming the pinned root and the current one. A linked
|
|
105
|
+
Install root refuses at exit 2 at the pin and at every check, naming the link.
|
|
106
|
+
Restore is the maintainer reinstalling the pinned version by hand, never the
|
|
107
|
+
controller: a reinstall swaps the files under every live member.
|
|
108
|
+
|
|
109
|
+
A fast-forward of the main checkout is no refusal: the pin certifies the
|
|
110
|
+
installed package, not the checkout, so moving the checkout changes no
|
|
111
|
+
instrument. The tick's main-checkout guard reads a fast-forward to
|
|
112
|
+
`origin/main` as clean and holds the run on a branch switch or an edit.
|
|
149
113
|
|
|
@@ -13,16 +13,6 @@ The invariants SKILL.md states one line each, as they read before they were tigh
|
|
|
13
13
|
- The merge bot only touches PRs whose implementer reported done. Rebasing a
|
|
14
14
|
worktree someone is working in destroys uncommitted work.
|
|
15
15
|
- `ready-to-merge` is added by a reviewer only — never an implementer, never you.
|
|
16
|
-
**The run's own artifact PR is exempt, and it is exempt because this invariant
|
|
17
|
-
does not reach it:** what the line forbids is a fleet member signing off its own
|
|
18
|
-
ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
|
|
19
|
-
finisher, and the metrics PR you author has none of them. Label and
|
|
20
|
-
merge that one yourself instead of re-deriving a blocker from this line and
|
|
21
|
-
stranding the rows behind it. The exemption belongs to the run that authors the
|
|
22
|
-
PR and does not outlive it: one still open when the run ends is a PR a prior run
|
|
23
|
-
left open, which phase 0 folds into the next run's review queue as ticket work —
|
|
24
|
-
and a PR is not exempt from being wrong, only from waiting on a reviewer
|
|
25
|
-
no phase of this run will ever dispatch against it.
|
|
26
16
|
- **Every member acts through the maintainer's `gh` credentials, so no write is
|
|
27
17
|
attributable.** Any invariant about *who* did something is unenforceable after
|
|
28
18
|
the fact: when a label moves unexpectedly, ask members directly, rule out
|
|
@@ -44,19 +44,23 @@ until the receipt is whole.
|
|
|
44
44
|
|
|
45
45
|
## Fast-forward the checkout
|
|
46
46
|
|
|
47
|
-
**Fast-forward the checkout before
|
|
48
|
-
|
|
47
|
+
**Fast-forward the checkout before the run starts — its own tracked files
|
|
48
|
+
must be at `origin/main`.** First, `git symbolic-ref -q HEAD` must print
|
|
49
49
|
`refs/heads/main`; anything else, stop and tell the maintainer — a checkout
|
|
50
50
|
left on a branch whose PR has merged would fast-forward that branch, and the
|
|
51
51
|
baseline below would record it as the run's ref. Then
|
|
52
52
|
`git fetch origin && git rev-list --count main..origin/main`;
|
|
53
|
-
non-zero means the
|
|
54
|
-
`
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
53
|
+
non-zero means the checkout is behind, so `git merge --ff-only origin/main`.
|
|
54
|
+
`phase0.mjs` does this itself and records the move as `ok`, naming the
|
|
55
|
+
count. It still runs because the workspace's own tracked files —
|
|
56
|
+
`docs/metrics/*`, the repo's own docs and CI-facing files — are what this run
|
|
57
|
+
reads and appends to, and the baseline below is recorded after it: recording
|
|
58
|
+
the baseline before that fast-forward would record a HEAD behind `origin/main`
|
|
59
|
+
as the run's own. The rules
|
|
60
|
+
come from the installed package, which a fast-forward does not touch, so
|
|
61
|
+
nothing you read is stale after it and no re-run follows. The usual cause of
|
|
62
|
+
a stale checkout is the PREVIOUS run's own close-out PR, which lands the
|
|
63
|
+
metrics and docs THIS run builds on and nothing pulls them.
|
|
60
64
|
|
|
61
65
|
## Pin the instruments
|
|
62
66
|
|
|
@@ -65,11 +69,13 @@ them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
|
|
|
65
69
|
records what the scripts and runbooks of the Install root — the tree the
|
|
66
70
|
fleet executes — say right now, which is what every later gate compares
|
|
67
71
|
against; SKILL.md's **Re-check before you act on any instrument reading** says
|
|
68
|
-
what its exit codes mean.
|
|
69
|
-
pinning before that fast-forward would instead pin the superseded text and
|
|
70
|
-
certify it for the rest of the run. The pin certifies the Install root and
|
|
72
|
+
what its exit codes mean. The pin certifies the Install root and
|
|
71
73
|
keeps its baseline in this checkout's `.fleet/`, so a workspace that tracks no
|
|
72
|
-
`plugin/…` of its own pins with no flag.
|
|
74
|
+
`plugin/…` of its own pins with no flag. A linked Install root (`omp plugin
|
|
75
|
+
link`) refuses the pin at exit 2: a fleet run executes an installed package,
|
|
76
|
+
so tell the maintainer to `omp plugin uninstall @feigi/fleet-ctl` and
|
|
77
|
+
`omp plugin install @feigi/fleet-ctl`, then restart; never run `omp plugin`
|
|
78
|
+
yourself. The baseline records the root it
|
|
73
79
|
certified beside the digest, and every later check — yours, a finisher's, the
|
|
74
80
|
merge gate's own leg — compares it with the live root and refuses when they
|
|
75
81
|
differ. Never dispatch a member into a run whose phase-0 pin refused.
|