@feigi/fleet-ctl 3.54.2 → 3.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.54.2",
3
+ "version": "3.55.0",
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": {
@@ -55,6 +55,15 @@
55
55
  // Anything but `clean` — dirty, unknown, no baseline — prints one
56
56
  // MAIN-CHECKOUT-* line and holds every dispatching row until the
57
57
  // maintainer clears it; it never refuses the tick.
58
+ // phase0 `.fleet/phase0.json`, phase0.mjs's receipt, through
59
+ // phase0-receipt.mjs. Missing, unreadable, a `run` other than
60
+ // the controller record's `at`, one whose controller has exited
61
+ // or cannot be judged, or a step `failed`, `pending` or absent
62
+ // prints one PHASE0-INCOMPLETE line naming what is not done and
63
+ // holds every dispatching row, ahead of the main-checkout reason;
64
+ // it never refuses the tick. A step's `drift` or `unanswered`
65
+ // and a `fold-in` NEED are advice, named on the line and holding
66
+ // nothing. The receipt's `session` fills the tier hold's step.
58
67
  // guard `.fleet/cost-guard.json` beside the shortlist, pr-cost.mjs
59
68
  // --guard's verdict on the implementer cells. Printed as the
60
69
  // `router` row and never acted on here: a missing or unreadable
@@ -86,12 +95,12 @@ import { parseMember, parseToken, premisesOf, rowNums, nextRetry, REVIEW, REVIEW
86
95
  export function reconcile(s) {
87
96
  const rev = reviewers(s);
88
97
  // The conflict rows only ask the controller to write a record — never to
89
- // dispatch — so they stand outside the main-checkout hold: the fix-applier a
98
+ // dispatch — so they stand outside the dispatch hold: the fix-applier a
90
99
  // conflict hold leads to obeys the hold through its own role's row.
91
100
  return [
92
- ...mainCheckoutHold(s, [implementers(s, rev.left), ...rev.rows]),
101
+ ...dispatchHold(s, [implementers(s, rev.left), ...rev.rows]),
93
102
  ...rev.conflictRows,
94
- ...mainCheckoutHold(s, [mergeBot(s)]),
103
+ ...dispatchHold(s, [mergeBot(s)]),
95
104
  ...shortlistRows(s),
96
105
  ...routerRows(s),
97
106
  ];
@@ -114,9 +123,20 @@ function mainCheckoutHoldReason(mainCheckout) {
114
123
  if (state === "clean") return null;
115
124
  return MAIN_CHECKOUT_HOLD[state] ?? "main checkout unknown";
116
125
  }
117
- function mainCheckoutHold(s, rows) {
118
- const why = mainCheckoutHoldReason(s.mainCheckout);
119
- if (why === null) return rows;
126
+ // A phase 0 this run has not finished holds the same rows the same way, and
127
+ // outranks the main-checkout reason on them: the baseline is one of its
128
+ // steps. Only a gate that answered `held: false` lets dispatch through — no
129
+ // answer is not a finished phase 0. Not actionable, so the fold carries it
130
+ // across an unattended night; a missing baseline under it still asks the
131
+ // controller to act, as it does alone.
132
+ const PHASE0_HOLD = "phase 0 incomplete";
133
+ // Every reason dispatch is held on this tick, outermost first.
134
+ function holdReasons(s) {
135
+ return [s.phase0?.held === false ? null : PHASE0_HOLD, mainCheckoutHoldReason(s.mainCheckout)].filter((w) => w !== null);
136
+ }
137
+ function dispatchHold(s, rows) {
138
+ const [why] = holdReasons(s);
139
+ if (why === undefined) return rows;
120
140
  const acts = s.mainCheckout?.state === "absent";
121
141
  const held = [];
122
142
  for (const r of rows) {
@@ -134,11 +154,13 @@ const mkRow = (role, actual, target, detail) => (action, { acts = false, extra =
134
154
  });
135
155
 
136
156
  // The clearing step a tier hold names in its detail. The tick reads no
137
- // transcript and so does not know the session directory: `<session>` stays a
138
- // placeholder the controller fills in, as `<file>` does — one batch file, one
139
- // entry per held member (SKILL.md's phase-2 tier check).
140
- const tierCheckStep = (members) => "run ~/.fleet/bin/fleet-run tier-check.mjs --batch <file> with "
141
- + JSON.stringify(members.map((member) => ({ member, session: "<session>" })));
157
+ // transcript; the session directory is the phase-0 receipt's, which
158
+ // tier-check.mjs reads itself when an entry omits it. Without a receipt of
159
+ // this run, `<session>` stays a placeholder the controller fills in, as
160
+ // `<file>` does — one batch file, one entry per held member (SKILL.md's
161
+ // phase-2 tier check).
162
+ const tierCheckStep = (members, session) => "run ~/.fleet/bin/fleet-run tier-check.mjs --batch <file> with "
163
+ + JSON.stringify(members.map((member) => (session ? { member } : { member, session: "<session>" })));
142
164
 
143
165
  // A mismatch clears when the next attempt on the ticket is dispatched at its
144
166
  // row's tier: ledger-grammar.mjs's nextRetry(), one letter past the highest
@@ -189,7 +211,7 @@ function implementers(s, left) {
189
211
  // controller's own step, so it is asked to act, with the command in the
190
212
  // detail.
191
213
  if (s.tierUnchecked.length) {
192
- return row(`HOLD (tier unchecked ${s.tierUnchecked.join(" ")})`, { acts: true, extra: tierCheckStep(s.tierUnchecked) });
214
+ return row(`HOLD (tier unchecked ${s.tierUnchecked.join(" ")})`, { acts: true, extra: tierCheckStep(s.tierUnchecked, s.phase0?.session) });
193
215
  }
194
216
 
195
217
  const deficit = s.implCap - s.implLive;
@@ -1068,6 +1090,8 @@ import { gitEnv } from "./git-env.mjs";
1068
1090
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
1069
1091
  import { statePath, readState, writeState, assessBeat, isStalled, isReported, stallReport, stallOwner } from "./fleet-state.mjs";
1070
1092
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
1093
+ import { readRunReceipt, phase0Gate } from "./phase0-receipt.mjs";
1094
+ import { judgeRecord, ProcUnreadable } from "./proc.mjs";
1071
1095
 
1072
1096
  const NAME = "fleet-tick";
1073
1097
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -1412,6 +1436,21 @@ function claimed() {
1412
1436
  return n === CLAIMED_LIMIT ? `${n}+` : n;
1413
1437
  }
1414
1438
 
1439
+ // What the controller record's process is now, for the phase-0 gate: `none`
1440
+ // with no record, else judgeRecord()'s answer. A process table that cannot
1441
+ // be read is `unreadable`, said on stderr: a controller nobody could judge
1442
+ // is not one whose receipt this tick may take as this run's.
1443
+ function controllerState(controller) {
1444
+ if (controller === null) return "none";
1445
+ try {
1446
+ return judgeRecord(controller);
1447
+ } catch (e) {
1448
+ if (!(e instanceof ProcUnreadable)) throw e;
1449
+ console.error(`${NAME}: WARNING ${e.message} — the recorded controller pid ${controller.pid} cannot be judged, so the phase-0 receipt is held`);
1450
+ return "unreadable";
1451
+ }
1452
+ }
1453
+
1415
1454
  function main() {
1416
1455
  const { fold, state: path, liveness, ...caps } = options();
1417
1456
  const listPath = shortlistPath();
@@ -1495,9 +1534,18 @@ function main() {
1495
1534
  // every answer but `clean` is a hold on the dispatching rows plus one line
1496
1535
  // saying why, so the rest of the run keeps reporting.
1497
1536
  const mainCheckout = checkMainCheckout();
1537
+ // This run's phase 0, off its receipt: unfinished holds the same rows the
1538
+ // main checkout does, and never refuses the tick either. Judged against
1539
+ // the controller record this tick started from, and against whether that
1540
+ // record's process is still there: a finished receipt of the run before
1541
+ // carries the same `at` until this run's rotation writes the next.
1542
+ const receipt = readRunReceipt();
1543
+ const phase0 = phase0Gate(receipt.read, {
1544
+ path: receipt.path, controllerAt: controller?.at, controller: controllerState(controller),
1545
+ });
1498
1546
 
1499
1547
  const rows = reconcile({
1500
- ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
1548
+ ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router,
1501
1549
  });
1502
1550
  const said = describe(mainCheckout, run.live);
1503
1551
  // Re-read rather than reusing priorState: this must be the freshest
@@ -1512,7 +1560,7 @@ function main() {
1512
1560
  // and frees no slot — and nothing here settles, kills or writes the ledger.
1513
1561
  const seen = stampSeen({ live: run.live, prev: prev.seen, controller: prev.controller, now });
1514
1562
  const stale = livenessLines({ live: run.live, seen, thresholds: liveness, now });
1515
- const lines = [...(said === null ? [] : [said]), ...stale.map((s) => s.line), ...formatLines(rows)];
1563
+ const lines = [...(phase0.line === null ? [] : [phase0.line]), ...(said === null ? [] : [said]), ...stale.map((s) => s.line), ...formatLines(rows)];
1516
1564
  // The run is over once it is draining and nothing is left in flight: no
1517
1565
  // open PR and no implementer still holding a claim. Printed last and read
1518
1566
  // as actionable, so it never folds away: the stop it names is the run's
@@ -1540,13 +1588,12 @@ function main() {
1540
1588
  }
1541
1589
 
1542
1590
  // Fold only when BOTH hold: nothing to act on, and nothing new to say. A
1543
- // main-checkout hold still holding dispatch stays named on the folded line
1544
- // — not actionable, so it never resets `quiet`, but the one reason
1545
- // nothing dispatches must not drop out of view. Outside the digest, which
1546
- // already covers it through the rows.
1591
+ // phase-0 or main-checkout hold still holding dispatch stays named on the
1592
+ // folded line — not actionable, so it never resets `quiet`, but the one
1593
+ // reason nothing dispatches must not drop out of view. Outside the digest,
1594
+ // which already covers it through the rows.
1547
1595
  if (fold && !acts && digest === prev.digest) {
1548
- const why = mainCheckoutHoldReason(mainCheckout);
1549
- const held = why === null ? "" : `; HOLD (${why}) persists`;
1596
+ const held = holdReasons({ phase0, mainCheckout }).map((why) => `; HOLD (${why}) persists`).join("");
1550
1597
  // A stale member persists the same way: advisory, so it never resets
1551
1598
  // `quiet`, and named on the folded line for as long as it stays live
1552
1599
  // past its threshold. The digest already moves when its bucket does.
@@ -0,0 +1,145 @@
1
+ // The phase-0 receipt, read. `.fleet/phase0.json` is written by phase0.mjs
2
+ // after every step (its header gives the shape); this module is its readers'
3
+ // half: the tick's dispatch gate, and the session directory tier-check.mjs
4
+ // and ticket-router.mjs take when their own flag is omitted. One reading of
5
+ // the file, so the gate and the session readers cannot disagree about what a
6
+ // receipt is.
7
+ //
8
+ // Zero deps: node builtins and sibling modules only.
9
+
10
+ import { readFileSync } from "node:fs";
11
+ import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
12
+ import { RECEIPT } from "./ledger-grammar.mjs";
13
+
14
+ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
15
+
16
+ // The steps phase0.mjs runs, in order: its receipt always carries every one,
17
+ // a step not yet run being `pending`. A receipt missing one was not written
18
+ // by a finished phase 0.
19
+ export const STEP_NAMES = Object.freeze([
20
+ "branch", "fast-forward", "pin", "baseline", "preflight", "ruleset", "tier-roles", "metrics",
21
+ "cockpit", "rotate", "reclaim", "recipe", "fold-in", "stranded", "shortlist",
22
+ ]);
23
+
24
+ // The statuses a step can end in that let the run go on: `ok`, and the two
25
+ // a ruleset check answers with when the gate drifted or could not be asked.
26
+ // Every other status — `failed`, `pending`, or one this reader does not know
27
+ // — is a step not done.
28
+ const ADVICE = new Set(["drift", "unanswered"]);
29
+ const DONE = new Set(["ok", ...ADVICE]);
30
+
31
+ /**
32
+ * `{ state: "missing" }`, `{ state: "unreadable", why }`, or
33
+ * `{ state: "ok", receipt }`. A receipt is a JSON object carrying `run`, a
34
+ * string `session` and a `steps` object whose every entry has a string
35
+ * `status` — the shape phase0.mjs writes and resumes from.
36
+ */
37
+ export function readReceipt(path) {
38
+ let text;
39
+ try {
40
+ text = readFileSync(path, "utf8");
41
+ } catch (e) {
42
+ if (e.code === "ENOENT") return { state: "missing" };
43
+ return { state: "unreadable", why: e.code ?? e.message };
44
+ }
45
+ let r;
46
+ try {
47
+ r = JSON.parse(text);
48
+ } catch (e) {
49
+ return { state: "unreadable", why: `not JSON (${e.message})` };
50
+ }
51
+ if (!(isRecord(r) && isRecord(r.steps) && Object.hasOwn(r, "run") && typeof r.session === "string")) {
52
+ return { state: "unreadable", why: "not a receipt: it needs run, session and steps" };
53
+ }
54
+ for (const [name, step] of Object.entries(r.steps)) {
55
+ if (!isRecord(step) || typeof step.status !== "string") return { state: "unreadable", why: `step ${name} has no status` };
56
+ }
57
+ return { state: "ok", receipt: r };
58
+ }
59
+
60
+ // The receipt at its resolved place — resolved the way phase0.mjs resolves
61
+ // it, so a worktree and the main checkout name one file — or the reason it
62
+ // has none: an unresolvable workspace is a receipt nobody can read.
63
+ export function readRunReceipt(opts) {
64
+ let path;
65
+ try {
66
+ path = fleetFile(RECEIPT, opts);
67
+ } catch (e) {
68
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
69
+ return { path: RECEIPT, read: { state: "unreadable", why: e.message } };
70
+ }
71
+ return { path, read: readReceipt(path) };
72
+ }
73
+
74
+ const phase0Command = (session) => `~/.fleet/bin/fleet-run phase0.mjs --session ${session ?? "<session>"}`;
75
+
76
+ /**
77
+ * The tick's gate over one read of the receipt. `controllerAt` is the `at`
78
+ * of the controller record in `.fleet/heartbeat.json` now, null when there is
79
+ * no record or it carries no `at` — the value phase0.mjs records as `run`, and
80
+ * compares the same way. `controller` is what that record's process is now,
81
+ * as proc.mjs's judgeController() answers (`none`, `dead`, `alive`,
82
+ * `ancestor`), or `unreadable` when the process table could not be read.
83
+ *
84
+ * `run` alone cannot tell this run's receipt from the previous run's: the
85
+ * record keeps the previous run's `at` until this run's rotation writes the
86
+ * next, so a finished receipt of the run before still matches it. A record
87
+ * whose process is gone, or cannot be judged, is that case, and holds.
88
+ *
89
+ * `{ held, line, session }`: `held` holds every dispatching row; `line` is the
90
+ * one line printed above the rows, or null when there is nothing to say;
91
+ * `session` is the receipt's session directory when the receipt is this
92
+ * run's, else null.
93
+ *
94
+ * A step `failed` or `pending`, in a status this reader does not know, or
95
+ * absent from the receipt, holds. `drift` and `unanswered`, and a `NEED` line
96
+ * in a `fold-in` step's output, are advice: named on the line, holding
97
+ * nothing.
98
+ */
99
+ export function phase0Gate(read, { path, controllerAt = null, controller = "none" }) {
100
+ const held = (why, session = null) => ({
101
+ held: true,
102
+ line: `PHASE0-INCOMPLETE ${why} — dispatch held: run ${phase0Command(session)} and act on what it prints`,
103
+ session,
104
+ });
105
+ if (read.state === "missing") return held(`no receipt at ${path}`);
106
+ if (read.state !== "ok") return held(`receipt ${path} unreadable: ${read.why}`);
107
+ const { receipt } = read;
108
+ if (receipt.run !== controllerAt) {
109
+ return held(`receipt ${path} is another run's: run ${receipt.run ?? "none"}, controller record ${controllerAt ?? "none"}`);
110
+ }
111
+ if (controller === "dead" || controller === "unreadable") {
112
+ const why = controller === "dead" ? "its controller has exited" : "its controller cannot be judged";
113
+ return held(`receipt ${path} is run ${receipt.run ?? "none"}'s and ${why}: not this session's finished phase 0`);
114
+ }
115
+ const steps = Object.entries(receipt.steps);
116
+ const absent = STEP_NAMES.filter((name) => !Object.hasOwn(receipt.steps, name));
117
+ const incomplete = [
118
+ ...steps.filter(([, step]) => !DONE.has(step.status)).map(([name]) => name),
119
+ ...absent,
120
+ ];
121
+ const advice = [
122
+ ...steps.filter(([, step]) => ADVICE.has(step.status)).map(([name, step]) => `${name} ${step.status}`),
123
+ ...String(receipt.steps["fold-in"]?.output ?? "").split("\n").map((l) => l.trim())
124
+ .filter((l) => l.startsWith("NEED ")).map((l) => `fold-in ${l}`),
125
+ ];
126
+ const session = receipt.session === "" ? null : receipt.session;
127
+ if (incomplete.length) {
128
+ const said = held(incomplete.join(", "), session);
129
+ return advice.length ? { ...said, line: `${said.line}; advice: ${advice.join(", ")}` } : said;
130
+ }
131
+ return { held: false, line: advice.length ? `PHASE0-ADVICE ${advice.join(", ")}` : null, session };
132
+ }
133
+
134
+ /**
135
+ * The session directory the receipt records, for a reader whose own flag was
136
+ * omitted. Throws an Error naming the receipt when it has none to give.
137
+ */
138
+ export function sessionFromReceipt(opts) {
139
+ const { path, read } = readRunReceipt(opts);
140
+ if (read.state === "ok" && read.receipt.session !== "") return read.receipt.session;
141
+ const why = read.state === "missing" ? "no receipt"
142
+ : read.state === "unreadable" ? `unreadable: ${read.why}`
143
+ : "it records no session";
144
+ throw new Error(`no session given and none in the phase-0 receipt ${path} (${why}) — give one, or run ${phase0Command(null)} first`);
145
+ }
@@ -3,7 +3,7 @@
3
3
  // for dispatch and for the offline fit, because the stratum rule is the one
4
4
  // function that must never read differently between the two.
5
5
  //
6
- // route --session <dir|id> --ticket <N> --arm A|B --impl-row <k>
6
+ // route [--session <dir|id>] --ticket <N> --arm A|B --impl-row <k>
7
7
  // --issue <issue.json> --guard <cost-guard.json>
8
8
  // [--sizing <sizing.json>] [--table <router-table.json>]
9
9
  // [--chain-head] [--pending <tsv>]
@@ -13,7 +13,9 @@
13
13
  // `ticket-features.pending.tsv` beside `--guard`, in the run's `.fleet/`). Exit 0 on
14
14
  // every data degradation — a missing or unreadable issue, sizing or guard
15
15
  // file degrades the line, never the exit. Exit 2 only on a usage error or
16
- // an unreadable/invalid table: the caller does not dispatch then.
16
+ // an unreadable/invalid table: the caller does not dispatch then. With no
17
+ // `--session`, the session is the one the phase-0 receipt
18
+ // `.fleet/phase0.json` records; a receipt that records none is exit 2.
17
19
  // fit --table <json> --features <tsv> --members <tsv> --verdicts <tsv>
18
20
  // --guard <cost-guard.json> --commit <rev> [--due]
19
21
  // Re-fits the table from the three TSVs as committed at `--commit` (read
@@ -43,6 +45,7 @@ import { isCLI } from "./is-cli.mjs";
43
45
  import { gitEnv } from "./git-env.mjs";
44
46
  import { makeDie, defineFlags } from "./arg.mjs";
45
47
  import { CELL, POLICY_CELL, drawCell, parseMember } from "./ledger-grammar.mjs";
48
+ import { sessionFromReceipt } from "./phase0-receipt.mjs";
46
49
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
47
50
  import { DATE, lastPullByTicket, parseTierOutcomes, rulingFor, rulingsByTicket } from "./tier-outcomes.mjs";
48
51
 
@@ -546,8 +549,6 @@ function main() {
546
549
  if (valid instanceof Error) die(`${tablePath}: ${valid.message}`);
547
550
 
548
551
  if (mode === "route") {
549
- const sessionArg = need("session").replace(/\/+$/, "");
550
- const session = basename(sessionArg);
551
552
  const ticket = need("ticket");
552
553
  if (!/^[1-9][0-9]*$/.test(ticket)) die(`--ticket ${ticket} is not an issue number`);
553
554
  const arm = need("arm");
@@ -556,6 +557,13 @@ function main() {
556
557
  if (!/^[1-9][0-9]*$/.test(implRowArg)) die(`--impl-row ${implRowArg} is not a positive row count`);
557
558
  const issuePath = need("issue");
558
559
  const guardPath = need("guard");
560
+ // `--session` omitted is the session directory the phase-0 receipt
561
+ // records; a receipt that records none is a usage error naming it.
562
+ let sessionArg = F.arg("session");
563
+ if (sessionArg === null) {
564
+ try { sessionArg = sessionFromReceipt(); } catch (e) { die(e.message); }
565
+ }
566
+ const session = basename(sessionArg.replace(/\/+$/, ""));
559
567
  const { line, row } = route({
560
568
  session, ticket: Number(ticket), arm, implRow: Number(implRowArg), chainHead: F.has("chain-head"),
561
569
  issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard: readGuard(readJson(guardPath)), table,
@@ -20,7 +20,13 @@
20
20
  // member's own transcript lives: the flat `<session>/<member>.jsonl`
21
21
  // file, read directly (this layer's extension to member-record.mjs's
22
22
  // readers — a member with no assistant turn yet still resolves off its
23
- // dispatch-time `session_init` record, never treated as absent).
23
+ // dispatch-time `session_init` record, never treated as absent). An
24
+ // entry that names neither a `session` nor a `transcript` takes the
25
+ // `session` the phase-0 receipt `.fleet/phase0.json` records, and is
26
+ // exit 2 naming the receipt when it records none. That session is taken
27
+ // as the receipt stands: whether the receipt is this run's is judged by
28
+ // fleet-tick.mjs's phase-0 gate, not here, and a message about it names
29
+ // the receipt's session where it would name `--session`.
24
30
  // 3. `--transcript <file>` — the member's own transcript, when the caller
25
31
  // already holds the exact path (tests, or a caller with no session
26
32
  // root handy).
@@ -70,8 +76,9 @@
70
76
  // the tier was right. Every other case with no transcript is still exit 2: a
71
77
  // LIVE member may yet write one; a member settled `PR#M`, `bailed` or
72
78
  // `tier-mismatch` ran, so its transcript exists and the `session` is the
73
- // wrong directory; a `session` that is omitted, empty, missing or not a
74
- // directory is exit 2 whether the member is live or settled; and a session
79
+ // wrong directory; a `session` that is empty, missing or not a directory,
80
+ // or omitted with none in the phase-0 receipt, is exit 2 whether the member
81
+ // is live or settled; and a session
75
82
  // directory that cannot be searched (EACCES) is exit 2 naming the errno,
76
83
  // never read as holding no transcript.
77
84
 
@@ -84,6 +91,7 @@ import { makeDie, defineFlags } from "./arg.mjs";
84
91
  import { foldOmpTranscript, parseMemberName } from "./member-record.mjs";
85
92
  import { parseFrontmatter, expectedOmpModel, modelsEqual, readOmpConfigValue } from "./tier-roles.mjs";
86
93
  import { parseMember, parseToken, memberTokens, expectedDefinition } from "./ledger-grammar.mjs";
94
+ import { sessionFromReceipt } from "./phase0-receipt.mjs";
87
95
 
88
96
  const NAME = "tier-check";
89
97
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -289,10 +297,10 @@ function resolvePath(repoRoot, p) {
289
297
  // (`<parent-AgentId>/<stem>.jsonl`, one directory level down) is out of
290
298
  // reach of this flat lookup — pass `--transcript` for a transcript this
291
299
  // cannot find directly.
292
- function resolveViaSession(repoRoot, sessionPath, member) {
300
+ function resolveViaSession(repoRoot, sessionPath, member, where) {
293
301
  const root = resolvePath(repoRoot, sessionPath);
294
302
  const flat = join(root, `${member}.jsonl`);
295
- if (!existsSync(flat)) throw new Error(`no ${member}.jsonl found under --session ${sessionPath}`);
303
+ if (!existsSync(flat)) throw new Error(`no ${member}.jsonl found under ${where}`);
296
304
  return readFileSync(flat, "utf8");
297
305
  }
298
306
 
@@ -385,7 +393,7 @@ function recordImplementer(ledgerFile, r) {
385
393
  // ticket's row, under the same presence rule as the other two.
386
394
  function recordUnverifiable(ledgerFile, r) {
387
395
  const token = tierUnverifiableToken(r.member);
388
- console.error(`${r.member}: settled ${r.outcome} with no ${r.member}.jsonl under --session ${r.session} — nothing to check; recorded ${token}`);
396
+ console.error(`${r.member}: settled ${r.outcome} with no ${r.member}.jsonl under ${r.where} — nothing to check; recorded ${token}`);
389
397
  const existing = rowText(readLedger(ledgerFile), r.ticket);
390
398
  const updated = withToken(existing, token);
391
399
  if (updated === existing) console.error(` ${r.member}: row #${r.ticket} already carries ${token} — not written again`);
@@ -442,6 +450,7 @@ function main() {
442
450
  // expected definition comes off its row, and nothing this loop does
443
451
  // writes a `tier=` token.
444
452
  let ledgerData = null;
453
+ let receiptSession;
445
454
  const results = entries.map((raw) => {
446
455
  const parsed = parseMember(String(raw.member ?? ""));
447
456
  const impl = parsed?.family === "impl";
@@ -466,7 +475,14 @@ function main() {
466
475
  // An implementer's transcript is read even beside a full job record:
467
476
  // the agent type it was dispatched as lives only there.
468
477
  if (impl || !hasJobRecord) {
469
- if (raw.session) {
478
+ // An entry naming neither a session nor a transcript takes the
479
+ // session directory the phase-0 receipt records — read once per
480
+ // batch — and refuses naming the receipt when it records none. A
481
+ // given one always wins.
482
+ const session = raw.session ?? (raw.transcript ? undefined : (receiptSession ??= sessionFromReceipt()));
483
+ // Said as the caller's flag only when the caller gave it.
484
+ const where = raw.session ? `--session ${session}` : `the phase-0 receipt's session ${session}`;
485
+ if (session) {
470
486
  // A member settled `killed` or `released` with no transcript under
471
487
  // a session directory that does exist: its dispatch failed before
472
488
  // one was written, so there is nothing to judge. Recorded, not
@@ -474,12 +490,12 @@ function main() {
474
490
  // ledger nowhere, or a session path that is not a directory still
475
491
  // refuses below; one settled any other way ran, so its missing
476
492
  // transcript names the wrong session and refuses here.
477
- if (impl && sessionLacksTranscript(repoRoot, raw.session, raw.member)) {
493
+ if (impl && sessionLacksTranscript(repoRoot, session, raw.member)) {
478
494
  const outcome = memberOutcome(ledgerData, raw.member);
479
- if (NO_TRANSCRIPT_OUTCOMES.has(outcome)) return { impl: true, unverifiable: true, member: raw.member, ticket, outcome, session: raw.session };
480
- if (outcome) throw new Error(`settled ${outcome} with no ${raw.member}.jsonl under --session ${raw.session} — a member settled ${outcome} ran, so its transcript exists: name the session directory that dispatched it`);
495
+ if (NO_TRANSCRIPT_OUTCOMES.has(outcome)) return { impl: true, unverifiable: true, member: raw.member, ticket, outcome, where };
496
+ if (outcome) throw new Error(`settled ${outcome} with no ${raw.member}.jsonl under ${where} — a member settled ${outcome} ran, so its transcript exists: name the session directory that dispatched it`);
481
497
  }
482
- transcriptText = resolveViaSession(repoRoot, raw.session, raw.member);
498
+ transcriptText = resolveViaSession(repoRoot, session, raw.member, where);
483
499
  } else if (raw.transcript) {
484
500
  transcriptText = readFileSync(resolvePath(repoRoot, raw.transcript), "utf8");
485
501
  } else if (impl) {
@@ -1262,8 +1262,8 @@ one. Only the newest member counts, so a replacement (`impl-<N>-b`) is what
1262
1262
  clears a mismatch — and is then owed its own check. A mismatch on a ticket
1263
1263
  whose issue is already CLOSED holds nothing: the tick probes that issue and
1264
1264
  drops it, since there is nothing left to replace. The tick never reads a
1265
- transcript: clear an unchecked hold by running the check on that member with
1266
- `session`. A settled member's check works only when its transcript exists;
1265
+ transcript: clear an unchecked hold by running the check on that member. A
1266
+ settled member's check works only when its transcript exists;
1267
1267
  without one, the verdict is `tier-unverifiable` for a member settled `killed`
1268
1268
  or `released`, and exit 2 naming the wrong session for any other. Clear a
1269
1269
  mismatch by fixing the definition or the dispatch and dispatching the
@@ -1288,14 +1288,16 @@ dispatch time, so a late check judges a member against a tier it was never
1288
1288
  dispatched under.
1289
1289
 
1290
1290
  **The batch file is a JSON array, one entry per dispatched member** — under
1291
- Pull, a batch of one, the member just dispatched: `{member, session}`.
1292
- `member` is the AgentId the dispatch returns (`impl-<N>`). `session` is the
1293
- SAME session directory `member-outcomes.mjs`/`board.mjs` are already handed
1294
- for this run; the check reads the member's own `<session>/<member>.jsonl`
1295
- directly, so a member with no assistant turn yet still resolves off its
1296
- dispatch-time record. A caller already holding the exact transcript path may
1297
- give `transcript` instead. Either one is required: the agent type an
1298
- implementer was dispatched as lives only in its transcript. `resolvedModel`
1291
+ Pull, a batch of one, the member just dispatched: `{member}`.
1292
+ `member` is the AgentId the dispatch returns (`impl-<N>`). An entry that
1293
+ names neither `session` nor `transcript` takes the session directory phase
1294
+ 0's receipt `.fleet/phase0.json` records, and is exit 2 naming the receipt
1295
+ when it records none; the check reads the member's own
1296
+ `<session>/<member>.jsonl` directly, so a member with no assistant turn yet
1297
+ still resolves off its dispatch-time record. A `session` the entry gives
1298
+ wins over the receipt's; a caller already holding the exact transcript path
1299
+ may give `transcript` instead. The agent type an implementer was dispatched
1300
+ as lives only in its transcript. `resolvedModel`
1299
1301
  **and** `resolvedThinkingLevel` together — the dispatch's own job record —
1300
1302
  may ride beside it and are preferred for the model and level. An `impl-`
1301
1303
  entry carries no `agentFile`: its definition is the row's, never the
@@ -1963,7 +1965,8 @@ depth** guard table applied in code. Act on each line as it reads:
1963
1965
  `released` with no transcript, clears it), a mismatch by dispatching the
1964
1966
  replacement at the right tier (phase 2). Each
1965
1967
  prints its clearing step in the row's detail: the `tier-check.mjs` command
1966
- with a batch entry per member it names (fill in `<file>` and `<session>`),
1968
+ with a batch entry per member it names (fill in `<file>`; `<session>` too
1969
+ when no receipt of this run records one),
1967
1970
  or the replacement's name — `impl-<N>-b` on a first retry, else one letter
1968
1971
  past the highest the ticket has used, or that no retry letter is left.
1969
1972
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
@@ -2000,6 +2003,22 @@ depth** guard table applied in code. Act on each line as it reads:
2000
2003
  baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
2001
2004
  that vanished mid-run is not a fresh run — report it to the maintainer
2002
2005
  before recording over whatever the tree now holds.
2006
+ - `PHASE0-INCOMPLETE <step>[, <step>…] …`, printed first above the rows,
2007
+ with every dispatching row (implementers, reviewers, merge-bot) reading
2008
+ `HOLD (phase 0 incomplete)` — this run's phase-0 receipt
2009
+ `.fleet/phase0.json` names a step `failed` or `pending`, or lacks one. In
2010
+ place of the steps the line says the receipt is missing, unreadable,
2011
+ another run's (its `run` is not the `at` in the controller record), or a
2012
+ run whose controller has exited — the previous run's finished receipt, in
2013
+ a session that has not yet run its own phase 0. It outranks every
2014
+ other reason on those rows, `MAIN-CHECKOUT-*` included, whose lines still
2015
+ print; a `baseline` step not `ok` is one of the steps it names.
2016
+ `CONFLICT` rows and the stall report still print. Run the
2017
+ `phase0.mjs` command the line names and act on what it prints: a re-run
2018
+ resumes at the step that stopped. A `drift` or `unanswered` step and a
2019
+ `fold-in` `NEED` are advice, named after `; advice:` on the line, or alone
2020
+ on a `PHASE0-ADVICE …` line when nothing is incomplete; advice holds
2021
+ nothing.
2003
2022
  - `CHECK-LIVENESS <member> (<family> > p99 <t>m)`, printed above the rows — a
2004
2023
  live ledger token has stayed live past its family's p99 run time, counted
2005
2024
  from the first tick that saw it (`> 2×p99 …` from the second multiple of the