@feigi/fleet-ctl 3.19.8 → 3.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.19.8",
+  "version": "3.21.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/ambient-git-vars-mjs-prose.test.mjs

@@ -255,6 +255,18 @@ const COVERED_MJS = {
   // cache reader child gets the same env but unsets both itself, so no
   // fixture can tell its env apart.
   "recipe-prove.mjs": 1,
+  // TWO scrubbed children. `defaultGuardPath()`'s `rev-parse --git-common-dir`
+  // names the workspace the guard file is written into: an ambient GIT_DIR
+  // would answer for ANOTHER repository, and the verdict would land in its
+  // `.fleet/` at exit 0 while fleet-tick reads this one's. Measured in
+  // pr-cost.test.mjs, "an ambient GIT_DIR naming another repository cannot move
+  // the guard file out of the repository pr-cost runs in". The `gh pr list`
+  // child is the second: gh's remote resolution follows GIT_DIR too (measured
+  // for shortlist.mjs's `probeState()` above), so merged state could be read
+  // for another repository's PRs; the gh stub in pr-cost.test.mjs, "an ambient
+  // GIT_DIR does not reach the gh child that reads merged state", records
+  // that the child sees no GIT_DIR.
+  "pr-cost.mjs": 2,
 };
 
 // The two-name-only exemption list #1599's second design question answers

package/scripts/fleet-tick.mjs

@@ -45,6 +45,12 @@
 //             Anything but `clean` — dirty, unknown, no baseline — prints one
 //             MAIN-CHECKOUT-* line and holds every dispatching row until the
 //             maintainer clears it; it never refuses the tick.
+//   guard     `.fleet/cost-guard.json` beside the shortlist, pr-cost.mjs
+//             --guard's verdict on the implementer cells. Printed as the
+//             `router` row and never acted on here: a missing or unreadable
+//             file reads DEFAULT-ONLY, the way the router (not in the tree
+//             yet; ADR 0016) is to read it. pr-cost.mjs writes the main
+//             workspace's file by default, the one read here.
 //
 // The pure half below is `reconcile()` over the counts `deriveRun()` reads off
 // the ledger; main() does the I/O. Split so the guard table and the reading are
@@ -61,7 +67,7 @@ import { parseMember, parseToken } from "./ledger-grammar.mjs";
 // reads what they leave: the slots this tick's own dispatches fill.
 export function reconcile(s) {
   const rev = reviewers(s);
-  return [...mainCheckoutHold(s, [implementers(s, rev.left), ...rev.rows, mergeBot(s)]), ...shortlistRows(s)];
+  return [...mainCheckoutHold(s, [implementers(s, rev.left), ...rev.rows, mergeBot(s)]), ...shortlistRows(s), ...routerRows(s)];
 }
 
 // #2210: a main checkout changed since the run's baseline — or one the tick
@@ -254,6 +260,59 @@ function shortlistRows(s) {
   }];
 }
 
+// The cost guard's verdict, as pr-cost.mjs --guard wrote it: OK, DEFAULT-ONLY
+// (a cell tripped, or no readable guard file — the router then runs the
+// default cell alone), or NO VERDICT (the baseline is short of its n). The
+// controller has nothing to do about any of them inside a run, so the row
+// never acts; it is here so the verdict is printed by code, not recalled.
+// Every verdict carries the guard's own `computed_at`: a refresh that failed
+// leaves the old file on disk, and only its age says the OK is not current.
+// No `router` state at all (a caller that read no guard) prints no row.
+export function routerRows(s) {
+  const g = s.router;
+  if (g === undefined) return [];
+  const row = (action, detail) => [{ role: "router", action, acts: false, detail }];
+  const run = "run pr-cost.mjs --guard";
+  if (g.status === "missing") return row("DEFAULT-ONLY", `cost-guard.json missing — ${run}`);
+  if (g.status !== "ok") return row("DEFAULT-ONLY", `cost-guard.json unreadable (${g.why}) — ${run}`);
+  const { baseline: b, cells, tripped, verdict, min_n: minN, computed_at: computed } = g.guard;
+  const age = `guard computed ${computed}`;
+  if (verdict === "none") return row("NO VERDICT", `baseline n=${b.n}/${minN}; ${age}`);
+  const pct = (x) => (x === null ? "n/a" : `${Math.round(x * 100)}%`);
+  const usd = (x) => (x === null ? "n/a" : `$${x.toFixed(2)}`);
+  const vs = (c) => `${c.cell} ${usd(c.mean_usd)} vs ${usd(b.mean_usd)}, fail ${pct(c.fail_rate)} vs ${pct(b.fail_rate)}, n=${c.n}/${b.n}`;
+  if (verdict === "tripped") {
+    const retired = g.guard.retire ? "; every non-default stage-1 cell tripped — the router retires" : "";
+    return row("DEFAULT-ONLY", `cost guard: ${cells.filter((c) => tripped.includes(c.cell)).map(vs).join("; ")}${retired}; ${age}`);
+  }
+  const others = cells.filter((c) => c.cell !== b.cell);
+  return row("OK", `${others.length ? others.map(vs).join("; ") : `baseline ${b.cell} ${usd(b.mean_usd)}, n=${b.n}`}; ${age}`);
+}
+
+// pr-cost.mjs's guard file, read as the router is to read it: anything but a
+// well-formed, self-consistent verdict is not one.
+export function readCostGuard(path) {
+  if (path === null) return { status: "missing" };
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    return e.code === "ENOENT" ? { status: "missing" } : { status: "unreadable", why: e.code ?? e.message };
+  }
+  let guard;
+  try { guard = JSON.parse(text); } catch { return { status: "unreadable", why: "not JSON" }; }
+  const cellShaped = (c) => c && typeof c.cell === "string" && Number.isInteger(c.n)
+    && (c.mean_usd === null || typeof c.mean_usd === "number") && (c.fail_rate === null || typeof c.fail_rate === "number");
+  const ok = guard && ["ok", "tripped", "none"].includes(guard.verdict) && typeof guard.computed_at === "string"
+    && cellShaped(guard.baseline) && Array.isArray(guard.cells) && guard.cells.every(cellShaped) && Number.isInteger(guard.min_n)
+    && Array.isArray(guard.tripped) && guard.tripped.every((c) => typeof c === "string")
+    // The verdict is "tripped" exactly when a cell is named, and only a reported cell can be named.
+    && (guard.verdict === "tripped") === (guard.tripped.length > 0)
+    && guard.tripped.every((c) => guard.cells.some((x) => x.cell === c))
+    && (guard.retire === undefined || typeof guard.retire === "boolean");
+  return ok ? { status: "ok", guard } : { status: "unreadable", why: "not a guard verdict" };
+}
+
 export function formatLines(rows) {
   const w = Math.max(...rows.map((r) => r.role.length));
   return rows.map((r) => r.actual === undefined
@@ -1086,7 +1145,10 @@ function claimed() {
 
 function main() {
   const { fold, state: path, ...caps } = options();
-  const current = readShortlist(shortlistPath());
+  const listPath = shortlistPath();
+  const current = readShortlist(listPath);
+  // Beside the shortlist, off the same git probe rather than a second one.
+  const router = readCostGuard(listPath === null ? null : join(dirname(listPath), "cost-guard.json"));
 
   // The PRIOR run's liveness, before anything that can refuse — #1597. The gh
   // read and the ledger read below both exit 2 on failure, and a stall
@@ -1142,7 +1204,7 @@ function main() {
   const mainCheckout = checkMainCheckout();
 
   const rows = reconcile({
-    ...caps, ...run, heads, supply, shortlistStatus: current.status, refresh: fresh, mainCheckout,
+    ...caps, ...run, heads, supply, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
   });
   const said = describe(mainCheckout, run.live);
   const lines = [...(said === null ? [] : [said]), ...formatLines(rows)];

package/scripts/fleet-tick.test.mjs

@@ -278,6 +278,93 @@ test("no refresh, no shortlist row", () => {
   assert.deepEqual(reconcile(state()).map((r) => r.role), ["implementers", "reviewers", "merge-bot"]);
 });
 
+// ---------------------------------------------------------------------------
+// The router row: pr-cost.mjs --guard's verdict, read off a guard file the way
+// the tick reads it. One case per state, each against a fixture file.
+
+import { routerRows, readCostGuard } from "./fleet-tick.mjs";
+
+const BASE = { cell: "slow-high", n: 31, mean_usd: 31, fail_rate: 0.29 };
+const guardJson = (over = {}) => JSON.stringify({
+  computed_at: "2026-10-03T00:00:00.000Z", window_start: "2026-10-03", baseline: BASE,
+  cells: [{ cell: "slow-high", n: 31, mean_usd: 31, fail_rate: 0.29 }, { cell: "task-high", n: 24, mean_usd: 12.3, fail_rate: 0.25 }],
+  tripped: [], verdict: "ok", retire: false, min_n: 20, ...over,
+});
+function routerRowOf(text) {
+  const dir = mkdtempSync(join(tmpdir(), "fleet-tick-guard-"));
+  try {
+    const path = join(dir, "cost-guard.json");
+    if (text !== null) writeFileSync(path, text);
+    const rows = reconcile(state({ router: readCostGuard(path) }));
+    assert.equal(actionable(rows), false, "no router state is work for the controller");
+    const r = rows.filter((x) => x.role === "router");
+    assert.equal(r.length, 1);
+    assert.equal(rows.at(-1), r[0], "the router row prints last");
+    return { ...r[0], line: formatLines(rows).at(-1) };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("router: a guard with no cell tripped is OK, naming each cell against the baseline", () => {
+  const r = routerRowOf(guardJson());
+  assert.equal(r.action, "OK");
+  assert.equal(r.acts, false);
+  assert.equal(r.line, "router       → OK   (task-high $12.30 vs $31.00, fail 25% vs 29%, n=24/31; guard computed 2026-10-03T00:00:00.000Z)");
+});
+
+test("router: the row carries the guard's own computed_at, so a stale OK reads as old", () => {
+  const r = routerRowOf(guardJson({ computed_at: "2026-09-01T08:00:00.000Z" }));
+  assert.equal(r.action, "OK");
+  assert.match(r.detail, /; guard computed 2026-09-01T08:00:00\.000Z$/);
+});
+
+test("router: a tripped cell is DEFAULT-ONLY, naming the cost guard and the cell it tripped", () => {
+  const r = routerRowOf(guardJson({
+    verdict: "tripped", tripped: ["smol-high"],
+    cells: [{ ...BASE }, { cell: "smol-high", n: 21, mean_usd: 9.5, fail_rate: 0.45 }, { cell: "task-high", n: 24, mean_usd: 12.3, fail_rate: 0.25 }],
+  }));
+  assert.equal(r.action, "DEFAULT-ONLY");
+  assert.equal(r.detail, "cost guard: smol-high $9.50 vs $31.00, fail 45% vs 29%, n=21/31; guard computed 2026-10-03T00:00:00.000Z");
+  const retired = routerRowOf(guardJson({ verdict: "tripped", tripped: ["task-high"], retire: true }));
+  assert.match(retired.detail, /^cost guard: task-high .*; every non-default stage-1 cell tripped — the router retires; guard computed /);
+});
+
+test("router: a baseline short of its n is NO VERDICT, with the count and the n it needs", () => {
+  const r = routerRowOf(guardJson({ verdict: "none", baseline: { ...BASE, n: 7 } }));
+  assert.equal(r.action, "NO VERDICT");
+  assert.equal(r.line, "router       → NO VERDICT   (baseline n=7/20; guard computed 2026-10-03T00:00:00.000Z)");
+});
+
+test("router: no guard file is DEFAULT-ONLY, naming the command that writes one", () => {
+  const r = routerRowOf(null);
+  assert.equal(r.line, "router       → DEFAULT-ONLY   (cost-guard.json missing — run pr-cost.mjs --guard)");
+});
+
+test("router: a guard file that is not a verdict reads DEFAULT-ONLY too — deleting or breaking it cannot evade the guard", () => {
+  const cell = { cell: "task-high", n: 24, mean_usd: 1, fail_rate: 0 };
+  for (const [text, why] of [["{", "not JSON"], [guardJson({ verdict: "maybe" }), "not a guard verdict"],
+    [guardJson({ tripped: "smol-high" }), "not a guard verdict"], [guardJson({ min_n: undefined }), "not a guard verdict"],
+    [guardJson({ computed_at: undefined }), "not a guard verdict"],
+    [guardJson({ cells: [{ ...cell, n: "24" }] }), "not a guard verdict"],
+    [guardJson({ cells: [{ ...cell, mean_usd: "12" }] }), "not a guard verdict"],
+    [guardJson({ cells: [{ ...cell, fail_rate: "0.2" }] }), "not a guard verdict"],
+    [guardJson({ baseline: { ...BASE, mean_usd: "31" } }), "not a guard verdict"],
+    // Self-contradicting files: a verdict that disagrees with tripped[], a tripped cell the file never reports, a non-boolean retire.
+    [guardJson({ verdict: "ok", tripped: ["task-high"] }), "not a guard verdict"],
+    [guardJson({ verdict: "tripped", tripped: [] }), "not a guard verdict"],
+    [guardJson({ verdict: "tripped", tripped: ["ghost"] }), "not a guard verdict"],
+    [guardJson({ retire: "yes" }), "not a guard verdict"]]) {
+    const r = routerRowOf(text);
+    assert.equal(r.action, "DEFAULT-ONLY", text);
+    assert.equal(r.detail, `cost-guard.json unreadable (${why}) — run pr-cost.mjs --guard`, text);
+  }
+});
+
+test("router: with no guard state read at all, no router row", () => {
+  assert.deepEqual(routerRows(state()), []);
+});
+
 test("formatLines prints role, actual/target and the ACTION on one line each", () => {
   assert.deepEqual(
     formatLines(reconcile(state({
@@ -1054,7 +1141,7 @@ test("deriveRun: the row text it does not own is accepted as it stands", () => {
   // The accept side of every refusal below: freeform row text, the arrow, the
   // board's own tokens and an empty ledger are the ordinary case.
   assert.doesNotThrow(() => run({
-    rows: ["#324 impl-324=PR#346 → PR#346 · fix-pr-346=no-op · ruled:6-applies · ci=123:1:success · ports=16324 · tier=alt"],
+    rows: ["#324 impl-324=PR#346 → PR#346 · fix-pr-346=no-op · ruled:6-applies · ci=123:1:success · ports=16324 · tier=task-high"],
     dispatched: ["impl-324=PR#346", "fix-pr-346=no-op"],
   }, [pr(346)]));
   const empty = run({});
@@ -1320,6 +1407,18 @@ test("CLI: runCli with keep: true hands back a fixture dir that still exists", (
   assert.equal(existsSync(runCli([]).dir), false, "without keep the dir is gone on return");
 });
 
+test("CLI: the router row reads the run's .fleet/cost-guard.json, and prints DEFAULT-ONLY without one", () => {
+  const none = runCli([], { shortlist: shortlistText([]) });
+  assert.equal(none.status, 0, none.stderr);
+  assert.deepEqual(lineOf(none, "router"), ["router       → DEFAULT-ONLY   (cost-guard.json missing — run pr-cost.mjs --guard)"]);
+  const ok = runCli([], {
+    shortlist: shortlistText([]),
+    beforeRun: (repo) => writeFileSync(join(repo, ".fleet", "cost-guard.json"), guardJson({ verdict: "none", baseline: { ...BASE, n: 12 } })),
+  });
+  assert.equal(ok.status, 0, ok.stderr);
+  assert.deepEqual(lineOf(ok, "router"), ["router       → NO VERDICT   (baseline n=12/20; guard computed 2026-10-03T00:00:00.000Z)"]);
+});
+
 test("CLI: the #1692 shape, read off the ledger — two live implementers at cap 2 pull nothing", () => {
   const r = runCli([], {
     ledger: { rows: ["#412 impl-412 · tier-ok=impl-412:fleet-implementer", "#415 impl-415 · tier-ok=impl-415:fleet-implementer"], dispatched: ["impl-412", "impl-415"] },

package/scripts/ledger-dispatch.test.mjs

@@ -173,28 +173,53 @@ test("dispatch prints the agent definition the call names: the row's tier for an
 // A `tier=` of the right shape whose definition has no file is refused the
 // same way: a `task` call naming it cannot resolve. Two of those: a cell
 // outside the shipped grid (`smol-max` — haiku has no `max`), and the
-// pre-cell `alt` whose definition #2129 deleted.
+// pre-cell `alt`, whose definition is deleted. `row` refuses a non-cell
+// `tier=` before it is written, so the rows `row` would refuse are written
+// as a ledger edited by hand — the case dispatch's own check still meets.
 test("dispatch refuses an implementer whose row names no single definition, or one with no file, before marking it live", (t) => {
-  const { ok, read, refused } = fixture(t);
-  ok("row", "7", "class=routine · tier=alt · tier=slow-high");
+  const rows = ["#7 class=routine · tier=alt · tier=slow-high", "#8 class=routine · tier=../../etc", "#9 class=routine · tier=", "#11 class=routine · tier=alt"];
+  const { ok, read, refused } = fixture(t, `# Fleet run ledger\n\n## Rows\n\n${rows.map((r) => `- ${r}\n`).join("")}\n## Filed\n\n## Ruled\n\n`);
   refused(["dispatch", "7", "impl-7"], /impl-7: row carries conflicting tier= tokens \(tier=alt, tier=slow-high\) — fix the row with `ledger\.mjs row` — not dispatching impl-7/);
-  ok("row", "8", "class=routine · tier=../../etc");
   refused(["dispatch", "8", "impl-8"], /impl-8: tier=\.\.\/\.\.\/etc is not a definition suffix — expected \[a-z0-9\] words joined by '-' — fix the row with `ledger\.mjs row` — not dispatching impl-8/);
-  ok("row", "9", "class=routine · tier=");
   refused(["dispatch", "9", "impl-9"], /impl-9: tier= is not a definition suffix/);
   ok("row", "10", "class=routine · tier=smol-max");
   refused(["dispatch", "10", "impl-10"], /impl-10: row #10's tier= names fleet-implementer-smol-max, which has no agents\/fleet-implementer-smol-max\.agent\.md — fix the row with `ledger\.mjs row` — not dispatching impl-10/);
-  ok("row", "11", "class=routine · tier=alt");
   refused(["dispatch", "11", "impl-11"], /impl-11: row #11's tier= names fleet-implementer-alt, which has no agents\/fleet-implementer-alt\.agent\.md/);
+  ok("row", "12", "class=routine · tier=task-high · tier=slow-high");
+  refused(["dispatch", "12", "impl-12"], /impl-12: row carries conflicting tier= tokens \(tier=task-high, tier=slow-high\)/);
   assert.deepEqual(read().dispatched, []);
 });
 
+// `row` holds `tier=` to the cell grammar, so a retired or misspelt tier is
+// refused at the Pull's own write, before the claim is dispatched on — and a
+// cell token is accepted whether or not its definition has shipped, which is
+// `dispatch`'s to check. The value is held to the whole grammar, not a prefix
+// of it: a real family with an unknown level, a cell with trailing text, or a
+// case-variant of a cell is refused. Only a token that STARTS with `tier=` is
+// a tier token, so one that merely contains it (`x-tier=alt`) is written as is.
+test("row refuses a tier= that is not a cell token, and accepts every cell token", (t) => {
+  const { ok, read, refused } = fixture(t);
+  const bads = [
+    "tier=alt", "tier=", "tier=../../etc", "tier=Task-High", "tier=task-high · tier=alt", "tier=haiku-high",
+    "tier=slow-ultra", "tier=task-", "tier=smol-", "tier=slow", "tier=task-high-x", "tier=task-high-", "tier=task-highx",
+    "tier==task-high", "tier=task-high,", "tier=TASK-HIGH", "tier=Slow-High", "tier=slow-HIGH", "tier=xslow-high",
+  ];
+  for (const bad of bads) {
+    refused(["row", "7", `impl-7 · ${bad}`], /row #7: 'tier=[^']*' is not tier=<cell>/);
+  }
+  assert.deepEqual(read().rows, []);
+  const goods = ["tier=task-high", "tier=slow-high", "tier=smol-max", "tier-ok=impl-7:fleet-implementer-task-high", "x-tier=alt", "x-tier=Slow-ultra · tier=task-high"];
+  for (const good of goods) {
+    assert.equal(ok("row", "7", `impl-7 · ${good}`).line, `#7 impl-7 · ${good}`);
+  }
+});
+
 // The refusal is about the implementer's own definition: a member whose
 // definition does not come off `tier=` must still be dispatchable on such a
 // row, or one bad token would strand the PR's finisher and fix-applier.
 test("a malformed tier= on a row does not refuse a member whose definition ignores it", (t) => {
   const { ok } = fixture(t);
-  ok("row", "7", "impl-7=PR#70 · tier=alt · tier=slow-high");
+  ok("row", "7", "impl-7=PR#70 · tier=task-high · tier=slow-high");
   assert.equal(ok("dispatch", "70", "fix-pr-70").agent, null);
   assert.equal(ok("dispatch", "7", "finisher-pr-70").agent, "fleet-finisher");
 });
@@ -215,7 +240,7 @@ test("dispatch names a fix-applier on an unresolved conflict hold of its own PR
   // `tier=` is not consulted — conflicting values neither change nor refuse it.
   ok("row", "50", "impl-50=PR#51 · tier=task-high · conflict-hold:#51");
   assert.equal(ok("dispatch", "51", "fix-pr-51").agent, "fleet-implementer-slow-high");
-  ok("row", "60", "impl-60=PR#61 · tier=alt · tier=slow-high · conflict-hold:#61");
+  ok("row", "60", "impl-60=PR#61 · tier=task-high · tier=slow-high · conflict-hold:#61");
   assert.equal(ok("dispatch", "61", "fix-pr-61").agent, "fleet-implementer-slow-high");
 
   // The hold's other spelling the tick reads (fleet-tick.mjs's CONFLICT_HOLD).
@@ -387,7 +412,7 @@ test("row still writes well-formed member tokens and non-member keys", (t) => {
     ["7", "impl-7 · class=routine · ports=16007"],
     ["8", "impl-8=PR#9 · fix-pr-9=applied:73b356de · review=wf:r1=failed reviewed=abc1234:1/0/0 · ci=123:1:success"],
     ["10", "held-behind:#9 · merge-bot-1=done · review=member:review-pr-10"],
-    ["11", "impl-11 · tier=alt · tier-ok=impl-11:fleet-implementer-alt"],
+    ["11", "impl-11 · tier=task-high · tier-ok=impl-11:fleet-implementer-task-high"],
     ["12", "impl-12=bailed · tier-mismatch=impl-12:fleet-implementer · impl-12: dispatched task, expected fleet-implementer"],
   ];
   for (const [ticket, text] of rows) ok("row", ticket, text);

package/scripts/ledger-grammar.mjs

@@ -99,8 +99,9 @@ export const CELL = /^(slow|task|smol)-(minimal|low|medium|high|xhigh|max)$/;
 export const CELL_DEF = new RegExp(`^fleet-implementer-${CELL.source.slice(1)}`);
 
 // The cell a row with no `tier=` runs at: `policy_cell`, `slow-high` on every
-// Pull until the router (spec § 4) picks one per stratum.
-const POLICY_CELL = "slow-high";
+// Pull until the router's table picks one per stratum. Exported so
+// ticket-router.mjs defaults to the same cell this file maps a bare row to.
+export const POLICY_CELL = "slow-high";
 
 // The Exploration Pull's draw (spec § 2): uniform over every cell but
 // `policyCell`, keyed off the row's own `session` and `ticket`, so the draw
@@ -134,9 +135,14 @@ export function drawCell({ session, ticket, policyCell, cells }) {
 // different definitions for one row and fail a dispatch made exactly as
 // printed.
 const TIER_SUFFIX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Every `tier=` value a row's text carries, in order, duplicates kept. */
+export function tierValues(rowText) {
+  return String(rowText ?? "").split(/\s+/).filter((t) => t.startsWith("tier=")).map((t) => t.slice("tier=".length));
+}
+
 export function expectedDefinition(rowText) {
-  const values = [...new Set(String(rowText ?? "").split(/\s+/)
-    .filter((t) => t.startsWith("tier=")).map((t) => t.slice("tier=".length)))];
+  const values = [...new Set(tierValues(rowText))];
   if (values.length === 0) return `fleet-implementer-${POLICY_CELL}`;
   if (values.length > 1) throw new Error(`row carries conflicting tier= tokens (${values.map((v) => `tier=${v}`).join(", ")}) — fix the row with \`ledger.mjs row\``);
   if (!TIER_SUFFIX.test(values[0])) throw new Error(`tier=${values[0]} is not a definition suffix — expected [a-z0-9] words joined by '-' — fix the row with \`ledger.mjs row\``);

package/scripts/ledger.mjs

@@ -35,7 +35,7 @@ import { fileURLToPath } from "node:url";
 import { spawnSync, execFileSync } from "node:child_process";
 import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
 import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
-import { parseMember, parseToken, memberTokens, nextMergeBot, agentDefinition } from "./ledger-grammar.mjs";
+import { parseMember, parseToken, memberTokens, nextMergeBot, agentDefinition, CELL, tierValues } from "./ledger-grammar.mjs";
 import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
 import { stateFileIn, readState, assessBeat, stallsAt } from "./fleet-state.mjs";
 
@@ -841,6 +841,11 @@ if (cmd === "read") {
   // rewrite alike; a well-formed token, live or settled, still goes through.
   const malformed = memberTokens(line).find((t) => t.error !== null);
   if (malformed) die(`row ${key}: malformed member token '${malformed.name}=${malformed.outcome}' — ${malformed.error}`);
+  // `tier=` names the implementer cell an exploration Pull dispatched, so its
+  // value must be a cell token: a retired or misspelt tier written here would
+  // only be refused later, by `dispatch`, after the claim.
+  const badTier = tierValues(line).find((v) => !CELL.test(v));
+  if (badTier !== undefined) die(`row ${key}: 'tier=${badTier}' is not tier=<cell> — a cell is <slow|task|smol>-<level>`);
   // `label-off=<attempt>` tells the tick a missing `ready-to-merge` is
   // the controller's own removal, not a finisher's miss — so one naming no
   // finisher-pr member this run has would mask a real miss behind a record of

package/scripts/member-outcomes.mjs

@@ -77,24 +77,30 @@ export function rowsForSession(sessionDir, stats = {}) {
     tokensCacheCreate: r.tokens_cache_create, tokensOut: r.tokens_out,
     wallS: r.wall_s, turns: r.turns, agent: r.agent, torn: false,
     subagentType: r.subagent_type,
+    tokensIn: r.tokens_in, tokensCacheRead: r.tokens_cache_read,
+    tokensCacheWrite1h: r.tokens_cache_write_1h ?? "", cost: r.cost == null ? "" : Number(r.cost.toFixed(6)),
   }));
 }
 
 // APPENDED TO, never inserted into: every read-out in the file's header and
-// in docs/specs indexes by position, so a column added anywhere but the end
-// silently repoints every `$n` a reader already wrote down. `subagent_type`
-// (#1066) is therefore last, after `harness`.
+// in the design specs indexes by position, so a column added anywhere but the
+// end silently repoints every `$n` a reader already wrote down.
+// `subagent_type` therefore follows `harness`, and the four priced columns
+// follow it. `cost` is the provider's own per-turn `usage.cost.total`, summed
+// to the micro-dollar — the $ of record; `tokens_cache_write_1h` and `cost`
+// are blank where the transcript recorded no figure, never 0.
 export const COLUMNS = [
   "session", "run_date", "role", "member", "model", "effort", "ticket", "pr",
   "tokens_cache_create", "tokens_out", "wall_s", "turns", "agent", "harness",
-  "subagent_type",
+  "subagent_type", "tokens_in", "tokens_cache_read", "tokens_cache_write_1h", "cost",
 ];
 
 // Row objects use camelCase; the file uses snake_case. One map, one direction
 // each, so a rename cannot silently drop a column.
 const FIELD = {
   tokens_cache_create: "tokensCacheCreate", tokens_out: "tokensOut", wall_s: "wallS",
-  subagent_type: "subagentType",
+  subagent_type: "subagentType", tokens_in: "tokensIn", tokens_cache_read: "tokensCacheRead",
+  tokens_cache_write_1h: "tokensCacheWrite1h",
 };
 const field = (c) => FIELD[c] ?? c;
 // Keyed on the transcript's path-relative stem, not the member name: `member`
@@ -118,13 +124,16 @@ export function formatTsv(rows) {
 }
 
 // REFUSES a row whose cell count is not exactly COLUMNS.length rather than
-// padding it. Padding looked harmless and was not: `agent` is the LAST column,
-// so a short row parsed to `agent: ""` — a key rowsForSession can never
-// produce, which means mergeRows can never REPLACE it. Three ways to reach that
-// were measured, all previously exit 0: a transcript torn mid-write became a
-// permanent phantom that re-scraping could not heal; git conflict markers became
-// three data rows; and adding one column ahead of `agent` collapsed the corpus
-// onto one key per session, 2,702 rows to 156.
+// padding it. Padding looked harmless and was not: when this was written
+// `agent` was the LAST column, so a short row parsed to `agent: ""` — a key
+// rowsForSession can never produce, which means mergeRows can never REPLACE
+// it. Three ways to reach that were measured, all previously exit 0: a
+// transcript torn mid-write became a permanent phantom that re-scraping could
+// not heal; git conflict markers became three data rows; and adding one column
+// ahead of `agent` collapsed the corpus onto one key per session, 2,702 rows
+// to 156. `agent` is no longer last — the priced columns follow it — and
+// there a padded "" would read as "no figure was recorded" for a member whose
+// transcript carried one, so a short row stays refused for that too.
 export function parseTsv(text) {
   return String(text ?? "").split("\n")
     .filter((l) => l.trim() && !l.startsWith("#"))

package/scripts/member-outcomes.test.mjs

@@ -137,6 +137,37 @@ test("a generated word pair that merely starts with a family word yields blanks
   assert.deepEqual(parseMemberName("Impl1341/Impl1341.CwdProbe"), { ticket: "", pr: "" });
 });
 
+test("a review fan-out label books its PR, in the label's own spelling and in the stem omp writes for it", () => {
+  // omp names the member by deleting every character outside [A-Za-z0-9_-]
+  // from the label and appending -<n> from a label's second dispatch on.
+  for (const [label, stem] of [
+    ["review:correctness:pr2132", "reviewcorrectnesspr2132"],
+    ["review:silent-failure:pr2132", "reviewsilent-failurepr2132"],
+    ["verify:comments:pr2132", "verifycommentspr2132"],
+    ["snapshot:pr2132", "snapshotpr2132"],
+    ["test-run:pr2132", "test-runpr2132"],
+  ]) {
+    assert.deepEqual(parseMemberName(label), { ticket: "", pr: "2132" }, label);
+    assert.deepEqual(parseMemberName(stem), { ticket: "", pr: "2132" }, stem);
+    assert.deepEqual(parseMemberName(`${stem}-7`), { ticket: "", pr: "2132" }, `${stem}-7`);
+    // Nested under the reviewer that dispatched it: the last segment is the member.
+    assert.deepEqual(parseMemberName(`review-pr-2132/${stem}`), { ticket: "", pr: "2132" }, `nested ${stem}`);
+  }
+  // A dimension key that itself spells `pr` still yields the trailing number.
+  assert.deepEqual(parseMemberName("reviewprpr12"), { ticket: "", pr: "12" });
+});
+
+test("a fan-out stem that carries no PR, or a name that only resembles one, books nothing", () => {
+  // Measured stems from before the label carried its PR.
+  for (const name of ["verifycorrectness-26", "reviewtests", "snapshot-8", "snapshot", "test-run",
+    // Generated or human names: PascalCase never matches, and a bare number is not `pr<n>`.
+    "ReviewCorrectness", "VerifyAndRepair", "Verify685", "ReviewTestsPr12", "review:correctness", "verify::pr", "reviewpr",
+    // Look-alikes of a fan-out stem: a prefix before the family word, a key-less `verify`, a hyphen before `pr`.
+    "xreviewfoopr12", "xsnapshotpr12", "verifypr12", "snapshot-pr12", "test-run-pr12", "verify-pr12", "reviewers-sprint-pr3"]) {
+    assert.deepEqual(parseMemberName(name), { ticket: "", pr: "" }, name);
+  }
+});
+
 // ---------------------------------------------------------------------------
 // omp fixtures — shaped like real ~/.omp/agent/sessions/**/*.jsonl lines
 // ---------------------------------------------------------------------------
@@ -271,25 +302,37 @@ test("`subagent_type` is what the DISPATCH named, and blank when it named nothin
 });
 
 test("a row whose cell count is wrong is REFUSED, never padded", () => {
-  // Padding put "" in the LAST column — `agent` when this was written,
-  // `subagent_type` now — a key rowsForSession can never produce, so mergeRows
+  // Padding put "" in the trailing columns — `agent` was the LAST one when
+  // this was written, a key rowsForSession can never produce, so mergeRows
   // could never replace it. Three measured routes there, all exit 0: a torn
   // last line became a permanent phantom that re-scraping could not heal, git
   // conflict markers became three data rows, and adding one column ahead of
-  // `agent` collapsed 2,702 rows to 156.
+  // `agent` collapsed 2,702 rows to 156. The columns that trail `agent` now
+  // are the priced ones, where a padded blank reads as "no figure recorded".
   //
-  // The 14-field spelling is the PREVIOUS schema, still on every branch cut
-  // before #1066: it must be refused rather than padded with a blank
-  // `subagent_type`, which would read as "this member was dispatched untyped"
-  // for rows that were nothing of the kind. Regenerating is the migration.
+  // The 15-field spelling is the PREVIOUS schema, from before the four priced
+  // columns: it must be refused rather than padded with blank prices, which
+  // would read as "no figure was recorded" for members whose transcript
+  // carried one. Re-scraping is the migration. The 14-field one before it is
+  // refused the same way.
   //
   // Mutation this must survive: restoring `cells[i] ?? ""`.
   const short = ["s1", "2026-08-25", "memory"].join("\t");
-  assert.throws(() => parseTsv(short), /malformed row: 3 fields, expected 15/);
+  assert.throws(() => parseTsv(short), /malformed row: 3 fields, expected 19/);
   assert.throws(() => parseTsv("<<<<<<< HEAD"), /malformed row/);
-  assert.throws(() => parseTsv(formatTsv([row()]).trim().split("\t").slice(0, 14).join("\t")), /14 fields, expected 15/);
+  const full = formatTsv([row()]).replace(/\n$/, "").split("\t");
+  assert.equal(full.length, 19);
+  assert.throws(() => parseTsv(full.slice(0, 15).join("\t")), /15 fields, expected 19/);
+  assert.throws(() => parseTsv(full.slice(0, 14).join("\t")), /14 fields, expected 19/);
   // A long row is refused too — that is the schema-drift direction.
-  assert.throws(() => parseTsv(formatTsv([row()]).trim() + "\textra"), /16 fields/);
+  assert.throws(() => parseTsv(full.join("\t") + "\textra"), /20 fields/);
+});
+
+test("the four priced columns follow subagent_type, and a scraped member fills them", () => {
+  assert.deepEqual(COLUMNS.slice(COLUMNS.indexOf("subagent_type")),
+    ["subagent_type", "tokens_in", "tokens_cache_read", "tokens_cache_write_1h", "cost"]);
+  const [parsed] = parseTsv(formatTsv([row({ tokensIn: 12, tokensCacheRead: 3400, tokensCacheWrite1h: 900, cost: 0.123457 })]));
+  assert.deepEqual([parsed.tokensIn, parsed.tokensCacheRead, parsed.tokensCacheWrite1h, parsed.cost], ["12", "3400", "900", "0.123457"]);
 });
 
 const row = (o = {}) => ({
@@ -300,7 +343,8 @@ const row = (o = {}) => ({
   // only `member` still get distinct transcript ids, and fixtures that share
   // the default member (untouched) still key as the SAME agent.
   agent: o.member ?? "impl-580", harness: "omp",
-  subagentType: "fleet-implementer", ...o,
+  subagentType: "fleet-implementer",
+  tokensIn: 0, tokensCacheRead: 0, tokensCacheWrite1h: 0, cost: 0.01, ...o,
 });
 
 test("re-scraping a session REPLACES its rows rather than appending duplicates", () => {
@@ -442,6 +486,19 @@ test("two separate sessions scraped in two runs merge into one TSV", () => {
   assert.equal(rows.find((r) => r.member === "Solo").subagentType, "fleet-implementer-alt");
 });
 
+test("a scrape writes the priced columns off the transcript's usage, the 1h share off its cttl", () => {
+  const dir = fixture([["impl-580", [sessionEvt("/x"), thinkingEvt("high"),
+    assistantEvt("claude-opus-5", { input: 7, cacheRead: 500, cacheWrite: 300, cttl: { ephemeral1h: 300 }, cost: { total: 0.25 } }),
+    assistantEvt("claude-opus-5", { input: 3, cacheRead: 800, cacheWrite: 40, cttl: { ephemeral5m: 40 }, cost: { total: 0.0500004 } }, "2026-08-25T10:05:00.000Z"),
+  ]]]);
+  const out = join(tempDir("mo-out-"), "member-outcomes.tsv");
+  const r = spawnSync(process.execPath, [CLI, dir, "--file", out], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  const [row] = parseTsv(readFileSync(out, "utf8"));
+  assert.deepEqual([row.tokensIn, row.tokensCacheRead, row.tokensCacheCreate, row.tokensCacheWrite1h, row.cost],
+    ["10", "1300", "340", "300", "0.3"]);
+});
+
 test("a run writes rows, and a second run over the same session changes nothing", () => {
   const dir = fixture([["impl-580", [sessionEvt("/x"), thinkingEvt("xhigh"), assistantEvt("claude-opus-5")]]]);
   const out = join(tempDir("mo-out-"), "member-outcomes.tsv");