@feigi/fleet-ctl 3.39.6 → 3.40.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.39.6",
3
+ "version": "3.40.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -16,10 +16,26 @@
16
16
  // they name, so the maintainer's own uncommitted work at run start is allowed
17
17
  // (it is in the baseline) while a further edit to one of those files is still
18
18
  // caught (its hash moves). Any entry that appears, any that disappears, any
19
- // hash that changes: `dirty`.
19
+ // hash that changes: `dirty`. It also holds HEAD: the symbolic ref and the
20
+ // commit `B` it names.
20
21
  //
21
- // THE PROTECTED SET is exactly the non-ignored paths of the main checkout —
22
- // what the member-write-guard protects. `.fleet/`, `.worktrees/` and
22
+ // HEAD. Reads clean when ALL hold: the symbolic ref equals the baseline's (a
23
+ // detached HEAD never does); `B` is HEAD or an ancestor of it; and
24
+ // `git rev-list B..HEAD ^origin/main` is empty. So the controller's
25
+ // fast-forward to `origin/main` and a commit already unpushed at the baseline
26
+ // are clean, while a stray commit, a branch switch, `switch --detach`,
27
+ // `reset --hard HEAD~1` and `commit --amend` are dirty. When HEAD equals `B`
28
+ // the ancestry calls are skipped. `origin/main` is hardcoded — the ref Phase
29
+ // 0 fast-forwards — and read every time: a missing one, an unborn HEAD or any
30
+ // failed git read answers `unknown`.
31
+ //
32
+ // NOT COVERED, BY DESIGN. A faked local `origin/main` (`update-ref`); a branch
33
+ // switch and a switch back between two ticks; a stray commit pushed to `main`
34
+ // in a repository with no protecting ruleset. This is a backstop for
35
+ // accidents, not for adversaries.
36
+ //
37
+ // THE PROTECTED SET is the non-ignored paths of the main checkout — what the
38
+ // member-write-guard protects — and its HEAD. `.fleet/`, `.worktrees/` and
23
39
  // `.agent-brain/` are gitignored in a fleet repo, so run state, members'
24
40
  // worktrees and agent-brain's cache never appear in porcelain and never trip
25
41
  // this.
@@ -42,21 +58,27 @@
42
58
  // The price: a member's leaked write to one of those three files goes unseen.
43
59
  //
44
60
  // FOUR ANSWERS, worktree-audit.sh's three plus the baseline's own refusal:
45
- // clean — the porcelain entries and hashes equal the baseline's.
46
- // dirty — they do not; `changed` names every path that differs.
47
- // unknown — some read failed: git, a hash, or a baseline that EXISTS but
48
- // cannot be read (unreadable file, unsearchable `.fleet/`,
49
- // dangling symlink, not written by --record). "A failure is an
50
- // unknown answer, never a 'no'" — never `clean`.
61
+ // clean — the porcelain entries and hashes equal the baseline's, and HEAD
62
+ // has not moved (see HEAD).
63
+ // dirty — they do not; `changed` names every path that differs, and a HEAD
64
+ // move as a first entry `HEAD <was> → <now>`, which names `HEAD`,
65
+ // never a path.
66
+ // unknown — some read failed: git, a hash, HEAD, `origin/main`, or a baseline
67
+ // that EXISTS but cannot be read (unreadable file, unsearchable
68
+ // `.fleet/`, dangling symlink, not written by --record) — or is a
69
+ // v1 baseline, which says nothing of HEAD: re-record it. "A failure
70
+ // is an unknown answer, never a 'no'" — never `clean`.
51
71
  // absent — no baseline at all: the run never recorded one. A refusal
52
72
  // ("record at run start"), never `clean`.
53
73
  //
54
74
  // RE-BASELINING OVERWRITES, IT DOES NOT COMPARE. `--record` writes
55
- // whatever the tree looks like now, so it is the maintainer's clear only
56
- // AFTER the stray paths are resolved. Over `unknown` it would walk the run
57
- // from "could not look" to "certified clean" in one step, so it refuses on
58
- // every unknown cause it can see: a baseline that exists but cannot be read,
59
- // and any failed git or hash read (no snapshot, nothing to write).
75
+ // whatever the tree looks like now — and whatever branch it is on — so it is
76
+ // the maintainer's clear only AFTER the stray paths are resolved. Over `unknown`
77
+ // it would walk the run from "could not look" to "certified clean" in one step,
78
+ // so it refuses on every unknown cause it can see: a baseline that exists but
79
+ // cannot be read, and any failed git or hash read (no snapshot, nothing to
80
+ // write). A detached HEAD has no symbolic ref to record, so it refuses that
81
+ // too. A v1 baseline is the one thing it overwrites without a word.
60
82
  //
61
83
  // ROOT. The main checkout is the parent of `git rev-parse --git-common-dir`
62
84
  // (git-env.mjs's `workspaceDirFromGitCommonDir`, as fleet-tick.mjs resolves
@@ -84,7 +106,8 @@ import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
84
106
  export const BASELINE_FILE = "main-checkout.sha";
85
107
  export const RECORD_COMMAND = "~/.fleet/bin/fleet-run main-checkout.mjs --record";
86
108
  const RUN_BOOKKEEPING = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
87
- const HEADER = "fleet main-checkout baseline v1";
109
+ const HEADER_V1 = "fleet main-checkout baseline v1";
110
+ const HEADER = "fleet main-checkout baseline v2";
88
111
  const GIT_TIMEOUT_MS = 30_000;
89
112
  const MAX_BUFFER = 64 * 1024 * 1024;
90
113
  const NAME = "main-checkout";
@@ -99,9 +122,9 @@ function git(what, args, cwd, env) {
99
122
  env: gitEnv({ LC_ALL: "C" }, env),
100
123
  });
101
124
  if (!r.error && r.status === 0) return { ok: true, stdout: r.stdout };
102
- if (r.error) return { ok: false, why: `${what} did not run: ${r.error.code ?? r.error.message}` };
125
+ if (r.error) return { ok: false, why: `${what} did not run: ${r.error.code ?? r.error.message}`, status: null };
103
126
  const last = String(r.stderr ?? "").trim().split("\n").at(-1);
104
- return { ok: false, why: `${what} ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`}${last ? `: ${last}` : ""}` };
127
+ return { ok: false, why: `${what} ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`}${last ? `: ${last}` : ""}`, status: r.status };
105
128
  }
106
129
 
107
130
  /** The main checkout `cwd` belongs to: `{ok, root}` or `{ok: false, why}`. */
@@ -149,16 +172,28 @@ const sha = (buf) => createHash("sha256").update(buf).digest("hex");
149
172
  // every path they name, so a further edit to a file already dirty in it moves
150
173
  // the hash where its status line would not — folded with its HEAD, so a
151
174
  // commit in it moves the hash too. A commitless repository's HEAD is the
152
- // branch it names. Nothing is left out: the run's bookkeeping is the main
153
- // checkout's two paths, not a nested repository's. Any git that fails
154
- // throws: `unknown`, never a hash that reads clean.
175
+ // branch it names. Nothing is left out: the run's bookkeeping is
176
+ // `RUN_BOOKKEEPING`, the main checkout's named paths, not a nested
177
+ // repository's. Any git that fails throws: `unknown`, never a hash that reads
178
+ // clean.
155
179
  function nestedHash(abs, env) {
156
180
  const now = entriesAt(abs, env, new Set());
157
181
  if (!now.ok) throw new Error(now.why);
158
182
  let head = git("git rev-parse HEAD", ["rev-parse", "-q", "--verify", "HEAD^{commit}"], abs, env);
159
- if (!head.ok) head = git("git symbolic-ref HEAD", ["symbolic-ref", "-q", "HEAD"], abs, env);
160
- if (!head.ok) throw new Error(head.why);
161
- return `repo:${sha(`${head.stdout}${formatBaseline(now.entries)}`)}`;
183
+ if (!head.ok) {
184
+ // No readable commit. Only a branch whose ref does not exist yet (show-ref
185
+ // exit 1) is unborn and hashes as the name HEAD holds; a ref that exists,
186
+ // or a show-ref that failed any other way, is a failed read.
187
+ const symbolic = git("git symbolic-ref HEAD", ["symbolic-ref", "-q", "HEAD"], abs, env);
188
+ // HEAD is detached or otherwise invalid.
189
+ if (!symbolic.ok) throw new Error(symbolic.why);
190
+ const ref = symbolic.stdout.trim();
191
+ const probe = git("git show-ref --verify", ["show-ref", "-q", "--verify", "--", ref], abs, env);
192
+ if (probe.ok) throw new Error(`HEAD points to ${ref} but the commit cannot be resolved`);
193
+ if (probe.status !== 1) throw new Error(probe.why);
194
+ head = symbolic;
195
+ }
196
+ return `repo:${sha(`${head.stdout}${formatEntries(now.entries)}`)}`;
162
197
  }
163
198
 
164
199
  /**
@@ -192,15 +227,76 @@ function entriesAt(root, env, skip) {
192
227
  return { ok: true, entries };
193
228
  }
194
229
 
195
- export function formatBaseline(entries) {
196
- const body = [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
230
+ // `ref` and `oid` lines name HEAD; the entries follow, one `hash<TAB>"line"` each.
231
+ export function formatBaseline(entries, head) {
232
+ return `${HEADER}\nref ${head.ref}\noid ${head.oid}\n${formatEntries(entries)}`;
233
+ }
234
+
235
+ function formatEntries(entries) {
236
+ return [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
197
237
  .map(([line, hash]) => `${hash}\t${JSON.stringify(line)}\n`).join("");
198
- return `${HEADER}\n${body}`;
199
238
  }
200
239
 
201
240
  /**
202
- * The run's baseline: `{status: "ok", entries}`, `{status: "absent"}`, or
203
- * `{status: "unreadable", why}`. ABSENT is only "nothing at that name": a
241
+ * The main checkout's HEAD: `{ok, ref, oid}` — `ref` is the symbolic ref, or
242
+ * null for a detached HEAD — or `{ok: false, why}`. An unborn HEAD has no
243
+ * commit to name, so it fails: `rev-parse -q --verify HEAD^{commit}`, because
244
+ * a bare `rev-parse HEAD` prints the word `HEAD` there.
245
+ */
246
+ function readHead(root, env) {
247
+ const sym = git("git symbolic-ref -q HEAD", ["symbolic-ref", "-q", "HEAD"], root, env);
248
+ // `-q` makes a detached HEAD exit 1 without a word; any other failure is a failure.
249
+ if (!sym.ok && sym.status !== 1) return sym;
250
+ const oid = git("git rev-parse --verify HEAD^{commit}", ["rev-parse", "-q", "--verify", "HEAD^{commit}"], root, env);
251
+ if (!oid.ok) return { ok: false, why: `${oid.why} — HEAD is unborn or unreadable` };
252
+ return { ok: true, ref: sym.ok ? sym.stdout.trim() : null, oid: oid.stdout.trim() };
253
+ }
254
+
255
+ /** The tree (`snapshot`) and HEAD together: `{ok, entries, head}` or `{ok: false, why}`. */
256
+ function readState(root, env) {
257
+ const now = snapshot(root, env);
258
+ if (!now.ok) return now;
259
+ const head = readHead(root, env);
260
+ return head.ok ? { ok: true, entries: now.entries, head } : head;
261
+ }
262
+
263
+ const headLabel = ({ ref, oid }) => `${ref ?? "(detached)"}@${oid.slice(0, 7)}`;
264
+
265
+ // The `origin/main` read the clean rule rests on: `{ok: true, …}` or
266
+ // `{ok: false, why}`. The check and `--record` both make it, so a baseline is
267
+ // never written that the check could only answer `unknown` to.
268
+ function originMain(root, env) {
269
+ const r = git("git rev-parse --verify refs/remotes/origin/main", ["rev-parse", "-q", "--verify", "refs/remotes/origin/main^{commit}"], root, env);
270
+ return r.ok ? r : { ok: false, why: `origin/main is missing or unreadable (${r.why})` };
271
+ }
272
+
273
+ /**
274
+ * Did HEAD move off the baseline's? `{ok, change}`: `change` is null, or the
275
+ * `HEAD <was> → <now>` entry; `{ok: false, why}` when a read failed.
276
+ * Clean is all of: the same symbolic ref; the baseline's commit an ancestor of
277
+ * HEAD or equal to it; no commit in `B..HEAD` that `origin/main` lacks. So a
278
+ * fast-forward to `origin/main` and a commit already unpushed at the baseline
279
+ * read clean, while a stray commit, a reset or an amend do not. `origin/main`
280
+ * is read even when HEAD equals the baseline: a checkout that cannot name it
281
+ * is one this cannot vouch for.
282
+ */
283
+ function headMove(root, env, was, now) {
284
+ const origin = originMain(root, env);
285
+ if (!origin.ok) return origin;
286
+ const moved = { ok: true, change: `HEAD ${headLabel(was)} → ${headLabel(now)}` };
287
+ if (now.ref !== was.ref) return moved;
288
+ if (now.oid === was.oid) return { ok: true, change: null };
289
+ const ancestor = git("git merge-base --is-ancestor", ["merge-base", "--is-ancestor", was.oid, now.oid], root, env);
290
+ if (!ancestor.ok) return ancestor.status === 1 ? moved : ancestor;
291
+ const stray = git("git rev-list", ["rev-list", "--max-count=1", `${was.oid}..${now.oid}`, "^refs/remotes/origin/main"], root, env);
292
+ if (!stray.ok) return stray;
293
+ return stray.stdout.trim() === "" ? { ok: true, change: null } : moved;
294
+ }
295
+
296
+ /**
297
+ * The run's baseline: `{status: "ok", entries, head}`, `{status: "absent"}`,
298
+ * `{status: "outdated", why}` (a v1 file) or `{status: "unreadable", why}`.
299
+ * ABSENT is only "nothing at that name": a
204
300
  * dangling symlink is present-but-broken, and an unsearchable `.fleet/`
205
301
  * answers EACCES rather than ENOENT, so neither can fall through to
206
302
  * "no baseline" (a mislabel this once made) — both are `unreadable`.
@@ -222,18 +318,21 @@ export function readBaseline(path) {
222
318
  return { status: "unreadable", why: `${path} exists but cannot be read: ${e?.code ?? e?.message}` };
223
319
  }
224
320
  const lines = text.split("\n");
225
- if (lines[0] !== HEADER || lines.at(-1) !== "") {
321
+ if (lines[0] === HEADER_V1) return { status: "outdated", why: "baseline v1 — re-record" };
322
+ const ref = lines[1]?.startsWith("ref ") ? lines[1].slice(4) : "";
323
+ const oid = lines[2]?.startsWith("oid ") ? lines[2].slice(4) : "";
324
+ if (lines[0] !== HEADER || lines.at(-1) !== "" || !ref || !/^[0-9a-f]{40,64}$/.test(oid)) {
226
325
  return { status: "unreadable", why: `${path} is not a baseline main-checkout.mjs --record wrote` };
227
326
  }
228
327
  const entries = new Map();
229
- for (const l of lines.slice(1, -1)) {
328
+ for (const l of lines.slice(3, -1)) {
230
329
  const tab = l.indexOf("\t");
231
330
  let line;
232
331
  try { line = tab > 0 ? JSON.parse(l.slice(tab + 1)) : null; } catch { line = null; }
233
332
  if (typeof line !== "string") return { status: "unreadable", why: `${path} carries a line --record never writes: ${JSON.stringify(l)}` };
234
333
  entries.set(line, l.slice(0, tab));
235
334
  }
236
- return { status: "ok", entries };
335
+ return { status: "ok", entries, head: { ref, oid } };
237
336
  }
238
337
 
239
338
  /** Every path whose entry appeared, disappeared or changed hash, sorted. */
@@ -245,11 +344,13 @@ export function changedPaths(baseline, current) {
245
344
  }
246
345
 
247
346
  /**
248
- * The tick's question: `{state, root?, baseline?, changed?, why?, cause?}`.
249
- * `cause` tells the two unknowns apart — `"baseline"` (it exists but cannot
250
- * be read) from `"read"` (git or a hash failed) — since each has its own
347
+ * The tick's question: `{state, root?, baseline?, changed?, headMove?, why?, cause?}`.
348
+ * `cause` tells the three unknowns apart — `"baseline"` (it exists but cannot
349
+ * be read), `"outdated"` (a v1 baseline: it says nothing of HEAD, so it can
350
+ * answer nothing) and `"read"` (git or a hash failed) — since each has its own
251
351
  * message. The baseline is read before the tree, because without one there
252
352
  * is nothing to compare against and no reason to look.
353
+ * A HEAD move is the first entry of `changed`, also named in `headMove`.
253
354
  */
254
355
  export function checkMainCheckout({ cwd = process.cwd(), env = process.env } = {}) {
255
356
  const where = resolveMainCheckout(cwd, env);
@@ -259,10 +360,18 @@ export function checkMainCheckout({ cwd = process.cwd(), env = process.env } = {
259
360
  const base = readBaseline(path);
260
361
  if (base.status === "absent") return { state: "absent", root, baseline: path };
261
362
  if (base.status === "unreadable") return { state: "unknown", cause: "baseline", root, baseline: path, why: base.why };
262
- const now = snapshot(root, env);
263
- if (!now.ok) return { state: "unknown", cause: "read", root, baseline: path, why: now.why };
363
+ if (base.status === "outdated") return { state: "unknown", cause: "outdated", root, baseline: path, why: base.why };
364
+ const unknown = (why) => ({ state: "unknown", cause: "read", root, baseline: path, why });
365
+ const now = readState(root, env);
366
+ if (!now.ok) return unknown(now.why);
367
+ const move = headMove(root, env, base.head, now.head);
368
+ if (!move.ok) return unknown(move.why);
264
369
  const changed = changedPaths(base.entries, now.entries);
265
- return changed.length ? { state: "dirty", root, baseline: path, changed } : { state: "clean", root, baseline: path };
370
+ if (move.change !== null) changed.unshift(move.change);
371
+ if (!changed.length) return { state: "clean", root, baseline: path };
372
+ return move.change === null
373
+ ? { state: "dirty", root, baseline: path, changed }
374
+ : { state: "dirty", root, baseline: path, changed, headMove: move.change };
266
375
  }
267
376
 
268
377
  // A path printed on one line: anything that would split or blur it is quoted.
@@ -281,11 +390,16 @@ export function describe(check, live = null) {
281
390
  case "clean":
282
391
  return null;
283
392
  case "dirty":
284
- return `MAIN-CHECKOUT-DIRTY ${check.changed.map(shown).join(" ")} — changed since the run's baseline${members}`
393
+ // The HEAD entry is text, not a path: quoting it would blur it.
394
+ return `MAIN-CHECKOUT-DIRTY ${check.changed.map((p) => (p === check.headMove ? p : shown(p))).join(" ")} — changed since the run's baseline${members}`
285
395
  + ` — dispatch held: resolve the stray paths FIRST, then re-baseline with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
286
396
  case "absent":
287
397
  return `MAIN-CHECKOUT-NO-BASELINE no baseline at ${check.baseline} — dispatch held: record it at run start with ${RECORD_COMMAND}`;
288
398
  default:
399
+ if (check.cause === "outdated") {
400
+ return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
401
+ + ` — dispatch held: resolve any stray paths FIRST, then re-record with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
402
+ }
289
403
  return check.cause === "baseline"
290
404
  ? `MAIN-CHECKOUT-UNKNOWN baseline unreadable: ${check.why}${members}`
291
405
  + " — dispatch held: fix the baseline so it can be read; NEVER re-baseline over it, --record overwrites rather than compares"
@@ -295,9 +409,11 @@ export function describe(check, live = null) {
295
409
  }
296
410
 
297
411
  /**
298
- * Write the baseline: `{ok, path, entries}` or `{ok: false, why}`. Refuses
299
- * over a baseline that exists but cannot be read — overwriting it blind
300
- * discards evidence nobody read — and on any failed read of the tree.
412
+ * Write the baseline: `{ok, path, entries, head}` or `{ok: false, why}`.
413
+ * Refuses over a baseline that exists but cannot be read — overwriting it
414
+ * blind discards evidence nobody read — and on any failed read of the tree, of
415
+ * HEAD or of `origin/main`, and on a detached HEAD, which has no symbolic ref
416
+ * to record. A v1 baseline is not unreadable: it is the one this overwrites.
301
417
  * Written to a temporary name and renamed, so a reader never sees half of it.
302
418
  */
303
419
  export function recordBaseline({ cwd = process.cwd(), env = process.env } = {}) {
@@ -308,17 +424,22 @@ export function recordBaseline({ cwd = process.cwd(), env = process.env } = {})
308
424
  if (prior.status === "unreadable") {
309
425
  return { ok: false, why: `${prior.why} — fix it first; do NOT --record over it, --record overwrites rather than compares` };
310
426
  }
311
- const now = snapshot(where.root, env);
427
+ const now = readState(where.root, env);
312
428
  if (!now.ok) return { ok: false, why: `${now.why} — could not look, so there is nothing to record` };
429
+ if (now.head.ref === null) {
430
+ return { ok: false, why: "HEAD is detached, so there is no symbolic ref to record — switch to the run's branch first" };
431
+ }
432
+ const origin = originMain(where.root, env);
433
+ if (!origin.ok) return { ok: false, why: `${origin.why} — could not look, so there is nothing to record` };
313
434
  try {
314
435
  mkdirSync(join(where.root, ".fleet"), { recursive: true });
315
436
  const tmp = `${path}.${process.pid}.tmp`;
316
- writeFileSync(tmp, formatBaseline(now.entries));
437
+ writeFileSync(tmp, formatBaseline(now.entries, now.head));
317
438
  renameSync(tmp, path);
318
439
  } catch (e) {
319
440
  return { ok: false, why: `cannot write ${path}: ${e?.code ?? e?.message}` };
320
441
  }
321
- return { ok: true, path, entries: now.entries.size };
442
+ return { ok: true, path, entries: now.entries.size, head: now.head };
322
443
  }
323
444
 
324
445
  function main() {
@@ -332,7 +453,7 @@ function main() {
332
453
  if (record) {
333
454
  const r = recordBaseline();
334
455
  if (!r.ok) die(r.why);
335
- console.log(`main-checkout: recorded ${r.entries} porcelain entr${r.entries === 1 ? "y" : "ies"} at ${r.path}`);
456
+ console.log(`main-checkout: recorded ${r.entries} porcelain entr${r.entries === 1 ? "y" : "ies"} at ${r.path}; HEAD ${headLabel(r.head)}`);
336
457
  return;
337
458
  }
338
459
  const c = checkMainCheckout();
@@ -33,7 +33,7 @@
33
33
  // ignored in a fleet repo, so worktrees, run state and agent-brain's cache
34
34
  // stay writable, and what is protected is exactly what the main
35
35
  // checkout's `git status` would show dirty (main-checkout.mjs watches the
36
- // same set).
36
+ // same set, and the checkout's HEAD besides).
37
37
  // - `bash` cwd, for every `fleet-implementer-<cell>` (ledger-grammar.mjs's
38
38
  // `CELL_DEF`), and for a fix-applier's own id (`fix-pr-<n>`) directly,
39
39
  // since a review fix-applier is a generic `task`: refuse when
@@ -258,7 +258,11 @@ phase, or in any later one, asks the maintainer which tickets to take.
258
258
  0. **Once per run, before anything else.**
259
259
 
260
260
  **Fast-forward the checkout before you trust these rules — you are reading
261
- them from it.** `git fetch origin && git rev-list --count main..origin/main`;
261
+ them from it.** First, `git symbolic-ref -q HEAD` must print
262
+ `refs/heads/main`; anything else, stop and tell the maintainer — a checkout
263
+ left on a branch whose PR has merged would fast-forward that branch, and the
264
+ baseline below would record it as the run's ref. Then
265
+ `git fetch origin && git rev-list --count main..origin/main`;
262
266
  non-zero means the SKILL.md you are executing is superseded, so
263
267
  `git merge --ff-only origin/main` and re-read what changed under
264
268
  `commands/`, `scripts/` and `skills/`. The usual cause is the PREVIOUS run's own close-out PR: it
@@ -287,7 +291,8 @@ phase, or in any later one, asks the maintainer which tickets to take.
287
291
  **Record the main-checkout baseline in the same step, right after the
288
292
  pin.** `~/.fleet/bin/fleet-run main-checkout.mjs --record` writes
289
293
  `.fleet/main-checkout.sha`: the main checkout's `git status --porcelain
290
- -uall` entries plus a content hash of every path they name. Your own
294
+ -uall` entries plus a content hash of every path they name, and its HEAD —
295
+ symbolic ref and commit. Your own
291
296
  uncommitted work is fine — it is in the baseline and holds nothing. From
292
297
  then on every `fleet-tick.mjs` compares the main checkout against it and
293
298
  holds dispatch on any change: the backstop for the stray member
@@ -1523,7 +1528,9 @@ leaving a regenerated 5,000-row corpus uncommitted in the checkout is how it get
1523
1528
  discarded by the next `git checkout` with nothing to show it ever ran.
1524
1529
 
1525
1530
  **Commit the metrics files and open a PR — at end of run.** The branch name is
1526
- the repository's choice. A PR still open when the run ends is one phase 0's
1531
+ the repository's choice. Make the commit on a branch in the main checkout,
1532
+ switch back to `main` before the next tick, and never `--record` while on that
1533
+ branch; the round trip reads clean. A PR still open when the run ends is one phase 0's
1527
1534
  fold-in queues for review next run, however it is named, so the files reach
1528
1535
  `main` through the same review as ticket work rather than being lost. Stranding
1529
1536
  a data row loses it: `member-outcomes.tsv` is regenerated from harness
@@ -1904,19 +1911,26 @@ depth** guard table applied in code. Act on each line as it reads:
1904
1911
  - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
1905
1912
  dispatching row (implementers, reviewers, merge-bot) reading
1906
1913
  `HOLD (main checkout dirty)` — the main checkout changed since the Phase 0
1907
- baseline. The line names the changed paths and every live member; it
1914
+ baseline. The line names the changed paths, or a `HEAD <was> → <now>` entry
1915
+ when HEAD moved, and every live member; it
1908
1916
  attributes nothing, because concurrent members make that a guess. Dispatch
1909
1917
  nothing new and tell the maintainer: they resolve the stray paths FIRST,
1910
1918
  then re-baseline with `~/.fleet/bin/fleet-run main-checkout.mjs --record`.
1911
- The hold lasts until that re-baseline, tick after tick. Never revert the
1919
+ A path entry holds until that re-baseline, tick after tick; a `HEAD …` entry
1920
+ clears itself once HEAD reads clean again, and is never re-baselined while
1921
+ HEAD is off the run's branch. Never revert the
1912
1922
  paths yourself, and never re-baseline over paths nobody has resolved. The
1913
- one change of yours that trips it is a mid-run tooling fix edited in this
1914
- checkout; **Fix the tooling mid-run** says how that one is cleared.
1923
+ changes of yours that trip it are a mid-run tooling fix edited in this
1924
+ checkout and the close-out commit's round trip through a branch; **Fix the
1925
+ tooling mid-run** and **Commit the metrics files and open a PR — at end of
1926
+ run** say how each is cleared.
1915
1927
  - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
1916
1928
  could not look: a git or hash read failed (`could not look:`), or the
1917
1929
  baseline exists but cannot be read (`baseline unreadable:`). Never clean,
1918
1930
  and **never re-baseline over it** — `--record` overwrites, so that certifies
1919
- a tree nobody read. Fix what the line names and tick again.
1931
+ a tree nobody read. Fix what the line names and tick again. The one
1932
+ exception is `baseline v1 — re-record`: an old-format baseline says nothing
1933
+ of HEAD, and `--record` is its remedy.
1920
1934
  - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
1921
1935
  baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
1922
1936
  that vanished mid-run is not a fresh run — report it to the maintainer
@@ -4016,11 +4030,18 @@ the step. Cut before you append.
4016
4030
  --pin`. You just changed the instrument set under your own check, and this is the
4017
4031
  only edit that legitimately does; skip it and the next gate refuses on your own
4018
4032
  fix, which teaches you to ignore the refusal. Then the ledger line, save the
4019
- rationale, one line to the maintainer. **Then re-baseline the main checkout,
4020
- if the fix was edited in it** — the next tick reads `MAIN-CHECKOUT-DIRTY`
4021
- naming your own paths. Run `~/.fleet/bin/fleet-run main-checkout.mjs --check`
4022
- first, and only when the paths it names are exactly the ones you just edited,
4023
- run `--record`. Any other path on that line is a stray write — leave the hold for
4033
+ rationale, one line to the maintainer. **Then land it from the main checkout,
4034
+ if the fix was edited in it** — until you do, the next tick reads
4035
+ `MAIN-CHECKOUT-DIRTY` naming your own paths. Commit the fix on a branch and
4036
+ switch back to `main` before the next tick, and never `--record` while on that
4037
+ branch: the switch back restores the tree the baseline recorded, so the hold
4038
+ clears itself with nothing re-recorded, and the fix leaves the checkout until
4039
+ its PR merges. A `HEAD …` entry is none of your paths and clears the same way.
4040
+ Re-baseline only a fix you leave edited in the checkout: run
4041
+ `~/.fleet/bin/fleet-run main-checkout.mjs --check` first, and only when the
4042
+ paths it names are exactly the ones you just edited, run `--record` — never
4043
+ before the commit, because the switch back would then read your own paths
4044
+ dirty again. Any other path on that line is a stray write — leave the hold for
4024
4045
  the maintainer, because `--record` would certify it with yours. Live members
4025
4046
  hold the old text — re-brief only if it changes what they do *now*.
4026
4047