@feigi/fleet-ctl 3.110.4 → 3.111.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.110.4",
3
+ "version": "3.111.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": {
@@ -1,9 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
  // The Label map: the string the consumer's tracker uses for each Label role.
3
3
  // This module owns the map's cache format — the file, its validity rules, the
4
- // writer and the reader every role-reading script imports — and the `show`
5
- // verb. It derives nothing: the derivation step is `ensure`, which is not
6
- // here yet, so every refusal below names it as the step that writes the map.
4
+ // writer and the reader every role-reading script imports — and the verbs
5
+ // that read or derive it: `show`, and `ensure`, the derivation step that
6
+ // writes the map. Where the reader or `show` refuses the cache, the message
7
+ // names `ensure` as the step that writes the map.
7
8
  //
8
9
  // THE CACHE is `.fleet/labels.json`, resolved through fleet-dir.mjs's
9
10
  // fleetFile() like the pre-flight marker, so a member in its own worktree and
@@ -11,6 +12,7 @@
11
12
  // so the file is never committed, and it is never written by hand. Content:
12
13
  // derivedAt ISO time of the derivation that wrote it
13
14
  // table what the triage-label table said then: { present, rows: {role: string} }
15
+ // (a role with two rows of different strings maps to the array of them)
14
16
  // roles every Label role -> the string the tracker uses
15
17
  // origin every Label role -> "table" | "default" | "maintainer"
16
18
  //
@@ -28,6 +30,20 @@
28
30
  // It writes what it is handed: checking the map is its caller's step.
29
31
  //
30
32
  // CLI:
33
+ // label-map.mjs ensure the Label map derivation step. Reads the
34
+ // cache, the repository's triage-label table
35
+ // and the live label list (`gh label list`,
36
+ // every call), and prints the map as JSON
37
+ // (exit 0, writing the cache only when it
38
+ // derived one), or the question payload as
39
+ // JSON (exit 3, nothing written). It never
40
+ // creates a label. Exit 1: the table breaks
41
+ // the string rules, the message naming each
42
+ // role, the rule and the fix. Exit 2: no
43
+ // repository, the table not readable, the
44
+ // cache present but not readable or not
45
+ // writable, `gh` could not answer, the label
46
+ // list filled its limit, or a usage refusal.
31
47
  // label-map.mjs show [<role>] the mapped string for <role>, or the whole
32
48
  // `roles` object as JSON with no role.
33
49
  // Exit 0 printed; 1 no cache or an invalid one, the message naming `ensure`;
@@ -35,15 +51,17 @@
35
51
  //
36
52
  // Zero deps: node builtins and sibling scripts only.
37
53
 
54
+ import { spawnSync } from "node:child_process";
38
55
  import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
39
- import { dirname } from "node:path";
56
+ import { dirname, join } from "node:path";
40
57
  import { isCLI } from "./is-cli.mjs";
41
58
  import { makeDie, writeAll } from "./arg.mjs";
59
+ import { DEFAULT_GIT_TIMEOUT_MS, gitEnv } from "./git-env.mjs";
42
60
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
43
61
 
44
62
  const NAME = "label-map";
45
63
  const die = makeDie(NAME);
46
- const USAGE = "usage: label-map.mjs show [<role>]";
64
+ const USAGE = "usage: label-map.mjs ensure | show [<role>]";
47
65
  const MAX_LENGTH = 50;
48
66
  const DERIVE = "run `label-map.mjs ensure`, the Label map derivation step";
49
67
 
@@ -60,9 +78,11 @@ export const LABEL_ROLES = Object.freeze([
60
78
  "ready-to-merge",
61
79
  ]);
62
80
 
81
+ // `cause` is the filesystem's own error when the cache exists and cannot be
82
+ // read; an absent cache or one that does not parse has none.
63
83
  export class LabelMapUnreadable extends Error {
64
- constructor(message) {
65
- super(message);
84
+ constructor(message, options) {
85
+ super(message, options);
66
86
  this.name = "LabelMapUnreadable";
67
87
  }
68
88
  }
@@ -125,29 +145,41 @@ export function writeLabelMap(map, { cwd = process.cwd() } = {}) {
125
145
  return file;
126
146
  }
127
147
 
128
- /**
129
- * The `roles` object (every Label role -> its string) of the cache of the
130
- * repository `cwd` belongs to. Throws LabelMapUnreadable, its message naming
131
- * `ensure`, when the cache is absent, does not parse, lacks a role or breaks
132
- * the string rules; throws FleetDirUnresolvable outside a repository.
133
- */
134
- export function readLabelMap({ cwd = process.cwd() } = {}) {
148
+ // The parsed cache of the repository `cwd` belongs to, with its path. Throws
149
+ // LabelMapUnreadable, its message naming `ensure`, when the file is absent,
150
+ // cannot be read or does not parse; FleetDirUnresolvable outside a repository.
151
+ function loadCache(cwd) {
135
152
  const file = fleetFile(LABEL_MAP_FILE, { cwd });
136
153
  let text;
137
154
  try {
138
155
  text = readFileSync(file, "utf8");
139
156
  } catch (e) {
140
157
  if (e.code === "ENOENT") throw new LabelMapUnreadable(`no Label map at ${file}: ${DERIVE}`);
141
- throw new LabelMapUnreadable(`cannot read the Label map at ${file} (${e.code ?? e.message}): ${DERIVE}`);
158
+ throw new LabelMapUnreadable(`cannot read the Label map at ${file} (${e.code ?? e.message}): ${DERIVE}`, { cause: e });
142
159
  }
143
- let cache;
144
160
  try {
145
- cache = JSON.parse(text);
161
+ return { file, cache: JSON.parse(text) };
146
162
  } catch (e) {
147
163
  throw new LabelMapUnreadable(`the Label map at ${file} does not parse (${e.message}): ${DERIVE}`);
148
164
  }
165
+ }
166
+
167
+ const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
168
+ const own = (record, key) => (Object.hasOwn(record, key) ? record[key] : undefined);
169
+
170
+ // The eight roles of `roles`, keyed in role order.
171
+ const inRoleOrder = (roles) => Object.fromEntries(LABEL_ROLES.map((role) => [role, roles[role]]));
172
+
173
+ /**
174
+ * The `roles` object (every Label role -> its string) of the cache of the
175
+ * repository `cwd` belongs to. Throws LabelMapUnreadable, its message naming
176
+ * `ensure`, when the cache is absent, does not parse, lacks a role or breaks
177
+ * the string rules; throws FleetDirUnresolvable outside a repository.
178
+ */
179
+ export function readLabelMap({ cwd = process.cwd() } = {}) {
180
+ const { file, cache } = loadCache(cwd);
149
181
  const roles = cache?.roles;
150
- if (roles === null || typeof roles !== "object" || Array.isArray(roles)) {
182
+ if (!isRecord(roles)) {
151
183
  throw new LabelMapUnreadable(`the Label map at ${file} holds no \`roles\` object: ${DERIVE}`);
152
184
  }
153
185
  const faults = labelStringFaults(roles);
@@ -155,12 +187,392 @@ export function readLabelMap({ cwd = process.cwd() } = {}) {
155
187
  const why = faults.map(({ role, rule }) => `${role}: ${rule}`).join("; ");
156
188
  throw new LabelMapUnreadable(`the Label map at ${file} is invalid — ${why}: ${DERIVE}`);
157
189
  }
158
- return Object.fromEntries(LABEL_ROLES.map((role) => [role, roles[role]]));
190
+ return inRoleOrder(roles);
159
191
  }
160
192
 
161
- function main() {
162
- const [verb, ...rest] = process.argv.slice(2);
163
- if (verb !== "show") die(verb === undefined ? USAGE : `unknown verb ${JSON.stringify(verb)}; ${USAGE}`);
193
+ // THE TABLE (TRIAGE_TABLE_FILE, under the checkout's top level): the
194
+ // first table whose second header cell, backticks and whitespace stripped, is
195
+ // TABLE_HEADER. A row is a table line whose first cell, stripped the same way,
196
+ // is a Label role and whose stripped second cell is not empty. `rows` maps a
197
+ // role to its string; a role with two rows of different strings maps to the
198
+ // array of them, in file order, so the cache's `table` still shows a changed
199
+ // second row. Any other table in the file is not read.
200
+ export const TRIAGE_TABLE_FILE = join("docs", "agents", "triage-labels.md");
201
+ const TABLE_HEADER = "Label in our tracker";
202
+
203
+ /** The tracker's answer could not be had, or the table could not be read: `ensure`'s exit 2. */
204
+ export class LabelMapUnavailable extends Error {
205
+ constructor(message) {
206
+ super(message);
207
+ this.name = "LabelMapUnavailable";
208
+ }
209
+ }
210
+
211
+ const stripCell = (cell) => cell.replace(/^[\s`]+|[\s`]+$/g, "");
212
+
213
+ // The cells of a markdown table line — any line holding an unescaped `|`, its
214
+ // leading and trailing pipes optional as GFM has them — or null for any other.
215
+ function cellsOf(line) {
216
+ let inner = line.trim();
217
+ if (!/(?<!\\)\|/.test(inner)) return null;
218
+ if (inner.startsWith("|")) inner = inner.slice(1);
219
+ if (inner.endsWith("|") && !inner.endsWith("\\|")) inner = inner.slice(0, -1);
220
+ return inner.split(/(?<!\\)\|/).map((cell) => cell.replace(/\\\|/g, "|"));
221
+ }
222
+
223
+ const isSeparator = (cells) => cells !== null && cells.every((cell) => /^\s*:?-+:?\s*$/.test(cell));
224
+
225
+ /** The `{ present: true, rows }` the triage-label table text says. */
226
+ export function parseTriageTable(text) {
227
+ const lines = text.split(/\r?\n/).map(cellsOf);
228
+ const found = new Map();
229
+ for (let i = 0; i + 1 < lines.length; i++) {
230
+ const head = lines[i];
231
+ if (head === null || head.length < 2 || !isSeparator(lines[i + 1]) || stripCell(head[1]) !== TABLE_HEADER) continue;
232
+ for (let j = i + 2; j < lines.length && lines[j] !== null; j++) {
233
+ const role = stripCell(lines[j][0]);
234
+ const value = stripCell(lines[j][1] ?? "");
235
+ if (!LABEL_ROLES.includes(role) || value === "") continue;
236
+ const strings = found.get(role) ?? [];
237
+ if (!strings.includes(value)) strings.push(value);
238
+ found.set(role, strings);
239
+ }
240
+ break;
241
+ }
242
+ const rows = {};
243
+ for (const role of LABEL_ROLES) {
244
+ const strings = found.get(role);
245
+ if (strings) rows[role] = strings.length === 1 ? strings[0] : strings;
246
+ }
247
+ return { present: true, rows };
248
+ }
249
+
250
+ /**
251
+ * The top level of the checkout `cwd` is in and the table it holds:
252
+ * `{ top, table }`, `table` being `{ present: false, rows: {} }` when the file
253
+ * is absent. Throws FleetDirUnresolvable outside a work tree and
254
+ * LabelMapUnavailable when the file exists and cannot be read.
255
+ */
256
+ export function readTriageTable({ cwd = process.cwd() } = {}) {
257
+ const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", env: gitEnv(), timeout: DEFAULT_GIT_TIMEOUT_MS });
258
+ const top = (r.stdout ?? "").trim();
259
+ if (r.status !== 0 || top === "") {
260
+ const why = (r.error?.message ?? (r.stderr ?? "").trim()) || `exit ${r.status}`;
261
+ throw new FleetDirUnresolvable(`could not resolve --show-toplevel: ${why}`);
262
+ }
263
+ const file = join(top, TRIAGE_TABLE_FILE);
264
+ let text;
265
+ try {
266
+ text = readFileSync(file, "utf8");
267
+ } catch (e) {
268
+ if (e.code === "ENOENT") return { top, table: { present: false, rows: {} } };
269
+ throw new LabelMapUnavailable(`cannot read ${file} (${e.code ?? e.message})`);
270
+ }
271
+ return { top, table: parseTriageTable(text) };
272
+ }
273
+
274
+ // The live label list is capped at this many labels per call: a list that
275
+ // fills the limit may be cut, and is a refusal (the capped-list rule).
276
+ export const LIVE_LABEL_LIMIT = 1000;
277
+ // `gh label list` is killed after this long, so a `gh` hung on auth or the
278
+ // network is `ensure`'s exit 2 rather than a hang.
279
+ const GH_TIMEOUT_MS = 60_000;
280
+
281
+ /**
282
+ * The names of every label the tracker has, from `gh label list`. Throws
283
+ * LabelMapUnavailable when `gh` cannot answer, answers something else, or
284
+ * the list fills LIVE_LABEL_LIMIT.
285
+ */
286
+ export function readLiveLabels({ cwd = process.cwd() } = {}) {
287
+ const args = ["label", "list", "--limit", String(LIVE_LABEL_LIMIT), "--json", "name"];
288
+ const r = spawnSync("gh", args, { cwd, encoding: "utf8", env: gitEnv({ GH_REPO: "" }), stdio: ["ignore", "pipe", "pipe"], timeout: GH_TIMEOUT_MS });
289
+ if (r.error?.code === "ETIMEDOUT") throw new LabelMapUnavailable(`gh label list timed out after ${GH_TIMEOUT_MS / 1000}s`);
290
+ if (r.error) throw new LabelMapUnavailable(`could not run gh: ${r.error.message}`);
291
+ if (r.signal) throw new LabelMapUnavailable(`gh was killed by ${r.signal}`);
292
+ if (r.status !== 0) {
293
+ throw new LabelMapUnavailable(`gh label list failed: ${(r.stderr ?? "").trim().split("\n")[0] || `exit ${r.status}`}`);
294
+ }
295
+ let rows;
296
+ try {
297
+ rows = JSON.parse(r.stdout);
298
+ } catch (e) {
299
+ throw new LabelMapUnavailable(`gh label list did not answer JSON (${e.message})`);
300
+ }
301
+ if (!Array.isArray(rows) || !rows.every((row) => isRecord(row) && typeof row.name === "string")) {
302
+ throw new LabelMapUnavailable("gh label list did not answer a list of { name }");
303
+ }
304
+ if (rows.length >= LIVE_LABEL_LIMIT) {
305
+ throw new LabelMapUnavailable(
306
+ `exactly ${rows.length} labels — the list is capped and may be truncated; a map derived from a cut list is not an answer`,
307
+ );
308
+ }
309
+ return rows.map((row) => row.name);
310
+ }
311
+
312
+ // A table's identity for "the table now in the repo equals the cached one":
313
+ // role order, so key order in the file does not matter; null for a malformed one.
314
+ function tableKey(table) {
315
+ if (!isRecord(table) || typeof table.present !== "boolean" || !isRecord(table.rows)) return null;
316
+ if (!Object.keys(table.rows).every((key) => LABEL_ROLES.includes(key))) return null;
317
+ return JSON.stringify([table.present, LABEL_ROLES.map((role) => own(table.rows, role) ?? null)]);
318
+ }
319
+
320
+ const lc = (text) => text.toLowerCase();
321
+ const compare = (a, b) => (lc(a) < lc(b) ? -1 : lc(a) > lc(b) ? 1 : a < b ? -1 : a > b ? 1 : 0);
322
+ // A label equals a role's name after lowercasing and dropping every
323
+ // non-alphanumeric character: `on-hold` for `onhold`, `Ready For Agent` for
324
+ // `ready-for-agent`.
325
+ const squash = (text) => lc(text).replace(/[^\p{L}\p{N}]/gu, "");
326
+
327
+ /**
328
+ * Derive the Label map from `table` (`{ present, rows }`), `live` (the
329
+ * tracker's label names) and `cache` (the parsed cache, any JSON value, or
330
+ * null; only its `roles` and `origin` records are read). Pure: no file, no
331
+ * `gh`. One of
332
+ * { kind: "certain", roles, origin } every role certain, the map valid
333
+ * { kind: "break", faults: [{ role, rule, fix }] } the table breaks the string rules
334
+ * { kind: "uncertain", payload: { certain, uncertain } } the maintainer decides
335
+ */
336
+ export function deriveLabelMap({ table, live, cache }) {
337
+ const exact = new Set(live);
338
+ const byKey = new Map();
339
+ for (const name of live) if (!byKey.has(lc(name))) byKey.set(lc(name), name);
340
+ // The live label a string names, in the tracker's own spelling.
341
+ const liveOf = (text) => (exact.has(text) ? text : byKey.get(lc(text)));
342
+ const rowsOf = (role) => (Object.hasOwn(table.rows, role) ? [].concat(table.rows[role]) : []);
343
+
344
+ const cacheRoles = isRecord(cache?.roles) ? cache.roles : {};
345
+ const cacheOrigin = isRecord(cache?.origin) ? cache.origin : {};
346
+ // The cache's strings decide which roles are gone, valid or not; only a
347
+ // cache whose strings pass the string rules carries answers. A role the
348
+ // cache lacks is no string to break them, so it drops no answer.
349
+ const cacheValid = labelStringFaults(cacheRoles).every(({ rule }) => rule === "missing");
350
+ const was = (role) => {
351
+ const text = own(cacheRoles, role);
352
+ return typeof text === "string" && text.trim() !== "" && liveOf(text) === undefined ? text : undefined;
353
+ };
354
+
355
+ const rowKeys = new Set(LABEL_ROLES.flatMap((role) => rowsOf(role).map(lc)));
356
+ // Live near matches of `role` the maintainer may be offered: none that the
357
+ // string rules reject, none that a table row or a carried answer holds.
358
+ const nearOf = (role, held) =>
359
+ [...exact]
360
+ .filter((name) => squash(name) === squash(role) && lc(name) !== lc(role) && stringFault(name) === null && !held.has(lc(name)))
361
+ .sort(compare);
362
+ const heldBy = (carried) => new Set([...rowKeys, ...[...carried].map((role) => lc(cacheRoles[role]))]);
363
+
364
+ // Roles with no row that the cache answered as the maintainer, the answer
365
+ // still live: the answers that carry over, before any is dropped.
366
+ const candidates = cacheValid
367
+ ? LABEL_ROLES.filter(
368
+ (role) =>
369
+ rowsOf(role).length === 0 &&
370
+ own(cacheOrigin, role) === "maintainer" &&
371
+ Object.hasOwn(cacheRoles, role) &&
372
+ liveOf(cacheRoles[role]) !== undefined,
373
+ )
374
+ : [];
375
+
376
+ // What each role with no row and no carried answer resolves to by its
377
+ // default: its certain string, or its suggestion.
378
+ const resolve = (carried, dropped) => {
379
+ const held = heldBy(carried);
380
+ const out = new Map();
381
+ for (const role of LABEL_ROLES) {
382
+ if (rowsOf(role).length || carried.has(role)) continue;
383
+ const def = liveOf(role);
384
+ const near = nearOf(role, held);
385
+ // A dropped answer and a gone label are asked again, a live default or not.
386
+ const askAgain = dropped.has(role) || was(role) !== undefined;
387
+ if (def !== undefined && near.length === 0 && !askAgain) out.set(role, { certain: true, string: def, origin: "default" });
388
+ else if (def !== undefined) out.set(role, { certain: false, string: def, origin: "default" });
389
+ else if (near.length) out.set(role, { certain: false, string: near[0], origin: "near-match" });
390
+ else out.set(role, { certain: false, string: role, origin: "default" });
391
+ }
392
+ return out;
393
+ };
394
+
395
+ // An answer is dropped when a table row names its string, or another role
396
+ // resolves to it as its default; dropping one can make its role resolve to
397
+ // its default and so drop another, so this runs until nothing more drops,
398
+ // starting with every answer carried. A carried role has no row and is
399
+ // never in `resolved`, so neither check can find the role itself.
400
+ const dropped = new Map();
401
+ let carried;
402
+ let resolved;
403
+ for (;;) {
404
+ carried = new Set(candidates.filter((role) => !dropped.has(role)));
405
+ resolved = resolve(carried, dropped);
406
+ let changed = false;
407
+ for (const role of carried) {
408
+ const key = lc(cacheRoles[role]);
409
+ let claimedBy = null;
410
+ for (const other of LABEL_ROLES) {
411
+ const row = rowsOf(other).find((text) => lc(text) === key);
412
+ if (row !== undefined) {
413
+ claimedBy = { role: other, string: row, by: "table" };
414
+ break;
415
+ }
416
+ }
417
+ if (claimedBy === null) {
418
+ for (const [other, verdict] of resolved) {
419
+ if (lc(verdict.string) === key) {
420
+ claimedBy = { role: other, string: verdict.string, by: "default" };
421
+ break;
422
+ }
423
+ }
424
+ }
425
+ if (claimedBy !== null) {
426
+ dropped.set(role, claimedBy);
427
+ changed = true;
428
+ }
429
+ }
430
+ if (!changed) break;
431
+ }
432
+
433
+ // The string rules on the verdicts, before any suggestion is withheld.
434
+ const faults = [];
435
+ const fixRow = (role) => `edit the ${role} row in ${TRIAGE_TABLE_FILE}`;
436
+ const firstRowOwner = new Map();
437
+ for (const role of LABEL_ROLES) {
438
+ const rows = rowsOf(role);
439
+ for (const text of rows) {
440
+ const rule = stringFault(text);
441
+ if (rule) faults.push({ role, rule: `its row names ${JSON.stringify(text)}, which is not a valid label string (${rule})`, fix: fixRow(role) });
442
+ }
443
+ if (rows.length === 0 || stringFault(rows[0])) continue;
444
+ const owner = firstRowOwner.get(lc(rows[0]));
445
+ if (owner !== undefined) {
446
+ faults.push({
447
+ role,
448
+ rule: `its row names ${JSON.stringify(rows[0])}, the same string as the ${owner} row (compared ignoring case)`,
449
+ fix: `edit the ${role} row or the ${owner} row in ${TRIAGE_TABLE_FILE}`,
450
+ });
451
+ } else {
452
+ firstRowOwner.set(lc(rows[0]), role);
453
+ }
454
+ // `resolved` holds only roles with no row, so never this one.
455
+ for (const [other, verdict] of resolved) {
456
+ if (lc(verdict.string) === lc(rows[0])) {
457
+ faults.push({
458
+ role,
459
+ rule: `its row names ${JSON.stringify(rows[0])}, the string ${other} resolves to as its default (${other} has no row and no answer of its own)`,
460
+ fix: `${fixRow(role)}, or run \`label-map.mjs set ${other}=<label>\` to give ${other} another label`,
461
+ });
462
+ }
463
+ }
464
+ }
465
+ if (faults.length) return { kind: "break", faults };
466
+
467
+ const held = heldBy(carried);
468
+ const certain = {};
469
+ const origin = {};
470
+ const uncertain = [];
471
+ for (const role of LABEL_ROLES) {
472
+ const rows = rowsOf(role);
473
+ let settled = null;
474
+ let suggested = null;
475
+ if (rows.length) {
476
+ const live1 = rows.length === 1 ? liveOf(rows[0]) : undefined;
477
+ if (live1 !== undefined) settled = { string: live1, origin: "table" };
478
+ else suggested = { string: liveOf(rows[0]) ?? rows[0], origin: "table" };
479
+ } else if (carried.has(role)) {
480
+ settled = { string: liveOf(cacheRoles[role]), origin: "maintainer" };
481
+ } else {
482
+ const verdict = resolved.get(role);
483
+ if (verdict.certain) settled = { string: verdict.string, origin: "default" };
484
+ else suggested = { string: verdict.string, origin: verdict.origin };
485
+ }
486
+ if (settled !== null) {
487
+ certain[role] = settled.string;
488
+ origin[role] = settled.origin;
489
+ continue;
490
+ }
491
+ // A gone role is never offered the string that vanished back.
492
+ const vanished = was(role);
493
+ const withheld = vanished !== undefined && lc(suggested.string) === lc(vanished);
494
+ const entry = {
495
+ role,
496
+ suggestion: withheld ? null : suggested.string,
497
+ origin: withheld ? "gone" : suggested.origin,
498
+ candidates: nearOf(role, held),
499
+ exists: !withheld && liveOf(suggested.string) !== undefined,
500
+ };
501
+ if (vanished !== undefined) entry.was = vanished;
502
+ if (dropped.has(role)) entry.claimedBy = dropped.get(role);
503
+ uncertain.push(entry);
504
+ }
505
+ if (uncertain.length) return { kind: "uncertain", payload: { certain, uncertain } };
506
+ // Nothing above lets two certain roles share a string; this is the belt to
507
+ // that suspenders, the same rules the reader and the writer's caller hold.
508
+ const broken = labelStringFaults(certain);
509
+ if (broken.length) return { kind: "break", faults: broken.map(({ role, rule }) => ({ role, rule, fix: fixRow(role) })) };
510
+ return { kind: "certain", roles: certain, origin };
511
+ }
512
+
513
+ /**
514
+ * The Label map derivation step: `{ code, stdout, stderr }` for the CLI to
515
+ * print. 0 the map (the cache valid as it stands, or derived and written),
516
+ * 1 the table breaks the string rules, 3 the question payload. Writes only
517
+ * the cache, and only on code 0 from a derivation; never creates a label.
518
+ * Throws FleetDirUnresolvable and LabelMapUnavailable, both exit 2.
519
+ */
520
+ export function ensureLabelMap({ cwd = process.cwd() } = {}) {
521
+ const { top, table } = readTriageTable({ cwd });
522
+ const live = readLiveLabels({ cwd: top });
523
+ let cache = null;
524
+ try {
525
+ cache = loadCache(cwd).cache;
526
+ } catch (e) {
527
+ if (!(e instanceof LabelMapUnreadable)) throw e;
528
+ // Absent or not parsing is derived again; a cache that exists and cannot
529
+ // be read may hold maintainer answers, so it is never written over.
530
+ if (e.cause) throw new LabelMapUnavailable(`cannot read the Label map at ${e.cause.path} (${e.cause.code ?? e.cause.message}); nothing written`);
531
+ }
532
+ const mapOf = (roles) => JSON.stringify(inRoleOrder(roles));
533
+ // Valid as it stands: every mapped string is in the tracker's own spelling,
534
+ // so a label whose case was changed after caching is derived again.
535
+ if (
536
+ isRecord(cache) &&
537
+ isRecord(cache.roles) &&
538
+ labelStringFaults(cache.roles).length === 0 &&
539
+ tableKey(cache.table) === tableKey(table) &&
540
+ LABEL_ROLES.every((role) => live.includes(cache.roles[role]))
541
+ ) {
542
+ return { code: 0, stdout: mapOf(cache.roles) };
543
+ }
544
+ const derived = deriveLabelMap({ table, live, cache });
545
+ if (derived.kind === "break") {
546
+ const lines = derived.faults.map(({ role, rule, fix }) => ` ${role}: ${rule}. Fix: ${fix}`);
547
+ return {
548
+ code: 1,
549
+ stderr: `\n${NAME}: ${TRIAGE_TABLE_FILE} gives a Label map that breaks the string rules; nothing written, nothing created:\n${lines.join("\n")}\n`,
550
+ };
551
+ }
552
+ if (derived.kind === "uncertain") return { code: 3, stdout: JSON.stringify(derived.payload) };
553
+ try {
554
+ writeLabelMap({ derivedAt: new Date().toISOString(), table, roles: derived.roles, origin: derived.origin }, { cwd });
555
+ } catch (e) {
556
+ throw new LabelMapUnavailable(`cannot write the Label map: ${e.message}`);
557
+ }
558
+ return { code: 0, stdout: mapOf(derived.roles) };
559
+ }
560
+
561
+ function ensure(rest) {
562
+ if (rest.length) die(`ensure takes no arguments, got: ${rest.join(" ")}; ${USAGE}`);
563
+ let result;
564
+ try {
565
+ result = ensureLabelMap();
566
+ } catch (e) {
567
+ if (e instanceof FleetDirUnresolvable || e instanceof LabelMapUnavailable) die(e.message);
568
+ throw e;
569
+ }
570
+ if (result.stderr) writeAll(2, result.stderr);
571
+ if (result.stdout !== undefined) console.log(result.stdout);
572
+ process.exitCode = result.code;
573
+ }
574
+
575
+ function show(rest) {
164
576
  if (rest.length > 1) die(`show takes at most one role, got: ${rest.join(" ")}; ${USAGE}`);
165
577
  const [role] = rest;
166
578
  if (role !== undefined && !LABEL_ROLES.includes(role)) {
@@ -179,4 +591,11 @@ function main() {
179
591
  console.log(role === undefined ? JSON.stringify(roles) : roles[role]);
180
592
  }
181
593
 
594
+ function main() {
595
+ const [verb, ...rest] = process.argv.slice(2);
596
+ if (verb === "ensure") return ensure(rest);
597
+ if (verb === "show") return show(rest);
598
+ die(verb === undefined ? USAGE : `unknown verb ${JSON.stringify(verb)}; ${USAGE}`);
599
+ }
600
+
182
601
  if (isCLI(import.meta.url)) main();
@@ -781,9 +781,10 @@ export function nextRetry(name, names) {
781
781
  export const CELL = /^(slow|task|smol)-(minimal|low|medium|high|xhigh|max)$/;
782
782
  export const CELL_DEF = new RegExp(`^fleet-implementer-${CELL.source.slice(1)}`);
783
783
 
784
- // The cell a row with no `tier=` runs at: `policy_cell`, `slow-high` on every
785
- // Pull until the router's table picks one per stratum. Exported so
786
- // ticket-router.mjs defaults to the same cell this file maps a bare row to.
784
+ // The cell a row with neither `tier=` nor `cell=` runs at: `policy_cell`,
785
+ // `slow-high` on every Pull until the router's table picks one per stratum.
786
+ // Exported so ticket-router.mjs defaults to the same cell this file maps a
787
+ // bare row to.
787
788
  export const POLICY_CELL = "slow-high";
788
789
 
789
790
  // The Exploration Pull's draw: uniform over every cell but
@@ -804,13 +805,18 @@ export function drawCell({ session, ticket, policyCell, cells }) {
804
805
  }
805
806
 
806
807
  // The definition an implementer is dispatched under, off its ticket
807
- // row's `tier=` token — none means `fleet-implementer-<POLICY_CELL>`,
808
- // `tier=<x>` means `fleet-implementer-<x>`. The value becomes a file
808
+ // row's cell token — none means `fleet-implementer-<POLICY_CELL>`,
809
+ // `tier=<x>` or `cell=<x>` means `fleet-implementer-<x>`. `tier=` is the
810
+ // cell a draw picked (a row carrying one is a drawn Pull, which `implRow`
811
+ // reads); `cell=` is the cell the router printed for a Pull it routed without
812
+ // a draw, and reads as no draw. When a row carries both, `tier=` decides: it
813
+ // is the replacement's cell `ledger.mjs token` writes. The value becomes a file
809
814
  // name under `agents/`, so it is held to `[a-z0-9]` words joined by `-`
810
- // rather than joined into a path as written, and two different `tier=`
811
- // values on one row name no single definition — refused, never resolved by
812
- // position. A value with no definition behind it (the retired `tier=alt`) is
813
- // `ledger.mjs dispatch`'s to refuse: it checks the file exists.
815
+ // rather than joined into a path as written, and two different values
816
+ // of the deciding token on one row name no single definition — refused,
817
+ // never resolved by position. A value with no definition behind it (the
818
+ // retired `tier=alt`) is `ledger.mjs dispatch`'s to refuse: it checks the file
819
+ // exists.
814
820
  //
815
821
  // Here, not in tier-check.mjs, because two readers must agree on it:
816
822
  // `ledger.mjs dispatch` prints the definition before the call and records
@@ -820,16 +826,36 @@ export function drawCell({ session, ticket, policyCell, cells }) {
820
826
  // definitions for one row and fail a dispatch made exactly as printed.
821
827
  const TIER_SUFFIX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
822
828
 
829
+ const tokenValues = (rowText, name) =>
830
+ String(rowText ?? "").split(/\s+/).filter((t) => t.startsWith(`${name}=`)).map((t) => t.slice(name.length + 1));
831
+
823
832
  /** Every `tier=` value a row's text carries, in order, duplicates kept. */
824
833
  export function tierValues(rowText) {
825
- return String(rowText ?? "").split(/\s+/).filter((t) => t.startsWith("tier=")).map((t) => t.slice("tier=".length));
834
+ return tokenValues(rowText, "tier");
835
+ }
836
+
837
+ /** Every `cell=` value a row's text carries, in order, duplicates kept. */
838
+ export function cellValues(rowText) {
839
+ return tokenValues(rowText, "cell");
840
+ }
841
+
842
+ /**
843
+ * The token that decides a row's cell, and its values: `tier=` when the row
844
+ * carries one, else `cell=`. Values are empty on a row with neither, and
845
+ * `name` then names no token the row carries.
846
+ * @returns {{name: "tier"|"cell", values: string[]}}
847
+ */
848
+ export function decidingCell(rowText) {
849
+ const tiers = tierValues(rowText);
850
+ return tiers.length > 0 ? { name: "tier", values: tiers } : { name: "cell", values: cellValues(rowText) };
826
851
  }
827
852
 
828
853
  export function expectedDefinition(rowText) {
829
- const values = [...new Set(tierValues(rowText))];
854
+ const { name, values: all } = decidingCell(rowText);
855
+ const values = [...new Set(all)];
830
856
  if (values.length === 0) return `fleet-implementer-${POLICY_CELL}`;
831
- 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\``);
832
- 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\``);
857
+ if (values.length > 1) throw new Error(`row carries conflicting ${name}= tokens (${values.map((v) => `${name}=${v}`).join(", ")}) — fix the row with \`ledger.mjs row\``);
858
+ if (!TIER_SUFFIX.test(values[0])) throw new Error(`${name}=${values[0]} is not a definition suffix — expected [a-z0-9] words joined by '-' — fix the row with \`ledger.mjs row\``);
833
859
  return `fleet-implementer-${values[0]}`;
834
860
  }
835
861
 
@@ -58,7 +58,7 @@ import { fileURLToPath } from "node:url";
58
58
  import { spawnSync, execFileSync } from "node:child_process";
59
59
  import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
60
60
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
61
- import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, ledgerSection, nextReviewerName } from "./ledger-grammar.mjs";
61
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, cellValues, decidingCell, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, ledgerSection, nextReviewerName } from "./ledger-grammar.mjs";
62
62
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
63
63
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
64
64
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -748,11 +748,14 @@ if (cmd === "read") {
748
748
  // rewrite alike; a well-formed token, live or settled, still goes through.
749
749
  const malformed = memberTokens(line).find((t) => t.error !== null);
750
750
  if (malformed) die(`row ${key}: malformed member token '${malformed.name}=${malformed.outcome}' — ${malformed.error}`);
751
- // `tier=` names the implementer cell an exploration Pull dispatched, so its
752
- // value must be a cell token: a retired or misspelt tier written here would
753
- // only be refused later, by `dispatch`, after the claim.
754
- const badTier = tierValues(line).find((v) => !CELL.test(v));
755
- if (badTier !== undefined) die(`row ${key}: 'tier=${badTier}' is not tier=<cell> — a cell is <slow|task|smol>-<level>`);
751
+ // `tier=` names the implementer cell an exploration Pull dispatched, and
752
+ // `cell=` the cell a Pull the router routed without a draw did, so each value
753
+ // must be a cell token: a retired or misspelt one written here would only be
754
+ // refused later, by `dispatch`, after the claim.
755
+ for (const [name, values] of [["tier", tierValues(line)], ["cell", cellValues(line)]]) {
756
+ const bad = values.find((v) => !CELL.test(v));
757
+ if (bad !== undefined) die(`row ${key}: '${name}=${bad}' is not ${name}=<cell> — a cell is <slow|task|smol>-<level>`);
758
+ }
756
759
  // A Pull's cell binds its implementer until that member settles; see
757
760
  // cellChangeRefusal(). A new row binds nothing yet.
758
761
  const i = data.rows.findIndex((r) => r.split(/\s/)[0] === key);
@@ -2226,14 +2229,14 @@ async function runDispatch() {
2226
2229
 
2227
2230
  // The definition the `task` call names, printed so the controller reads it
2228
2231
  // off this output rather than recalling it from prose a compaction drops.
2229
- // An implementer's comes off its row's `tier=`, the same function
2230
- // tier-check.mjs falls back to for an entry with no record, and `dispatch`
2231
- // records what it prints on the member's `## Dispatched` entry, which
2232
- // tier-check judges the member against — so a row that names no single
2233
- // definition, or names one with no file under `agents/` (a well-formed
2234
- // `tier=` whose definition has not shipped: a `task` call naming it cannot
2235
- // resolve), is refused here, before the member is live, not discovered by
2236
- // the check after the call.
2232
+ // An implementer's comes off its row's `tier=`, else its `cell=`, the same
2233
+ // function tier-check.mjs falls back to for an entry with no record, and
2234
+ // `dispatch` records what it prints on the member's `## Dispatched` entry,
2235
+ // which tier-check judges the member against — so a row that names no
2236
+ // single definition, or names one with no file under `agents/` (a
2237
+ // well-formed `tier=` or `cell=` whose definition has not shipped: a `task`
2238
+ // call naming it cannot resolve), is refused here, before the member is
2239
+ // live, not discovered by the check after the call.
2237
2240
  //
2238
2241
  // A fix-applier is `fleet-fix-applier` for every kind of work — review,
2239
2242
  // conflict hold, dispositions retry — so its definition reads nothing off
@@ -2287,15 +2290,18 @@ async function runDispatch() {
2287
2290
  const failures = labelled === null ? closing.failures : [...closing.failures, labelled];
2288
2291
  if (failures.length > 0) die(`${member.name}: ${failures.join("; ")} — not dispatching ${member.name}`);
2289
2292
  }
2290
- // Every error caught here carries its own cause and remedy — a row's `tier=`
2293
+ // Every error caught here carries its own cause and remedy — a row's `tier=` or `cell=`
2291
2294
  // (fix it with `ledger.mjs row`) for an implementer, a family
2292
2295
  // ledger-grammar.mjs has no definition case for otherwise — so this
2293
2296
  // refusal's tail names neither.
2294
2297
  let agent;
2295
2298
  try {
2296
- agent = agentDefinition(member, i === -1 ? "" : data.rows[i]);
2299
+ const row = i === -1 ? "" : data.rows[i];
2300
+ agent = agentDefinition(member, row);
2297
2301
  if (member.family === "impl" && !existsSync(join(AGENTS_DIR, `${agent}.agent.md`))) {
2298
- throw new Error(`row #${member.number}'s tier= names ${agent}, which has no agents/${agent}.agent.md — fix the row with \`ledger.mjs row\``);
2302
+ const { name, values } = decidingCell(row);
2303
+ const cause = values.length === 0 ? `row #${member.number} has no tier= or cell=, so it runs the policy cell ${agent}` : `row #${member.number}'s ${name}= names ${agent}`;
2304
+ throw new Error(`${cause}, which has no agents/${agent}.agent.md — fix the row with \`ledger.mjs row\``);
2299
2305
  }
2300
2306
  } catch (e) {
2301
2307
  die(`${member.name}: ${e.message} — not dispatching ${member.name}`);
@@ -2925,10 +2931,11 @@ function badLabelOff(words) {
2925
2931
  });
2926
2932
  }
2927
2933
 
2928
- // The cell a row's implementer runs at — its `tier=`, or POLICY_CELL on a row
2929
- // with none — read the way `dispatch` reads it: null for a row whose `tier=`
2930
- // values conflict or name no agents/<definition>.agent.md, which `dispatch`
2931
- // refuses, so such a row has no draw to bind.
2934
+ // The cell a row's implementer runs at — its `tier=`, else its `cell=`, or
2935
+ // POLICY_CELL on a row with neither — read the way `dispatch` reads it: null
2936
+ // for a row whose deciding values conflict or name no
2937
+ // agents/<definition>.agent.md, which `dispatch` refuses, so such a row has no
2938
+ // draw to bind.
2932
2939
  function runnableCell(rowText) {
2933
2940
  let definition;
2934
2941
  try {
@@ -2937,7 +2944,7 @@ function runnableCell(rowText) {
2937
2944
  return null;
2938
2945
  }
2939
2946
  if (!existsSync(join(AGENTS_DIR, `${definition}.agent.md`))) return null;
2940
- return tierValues(rowText)[0] ?? POLICY_CELL;
2947
+ return definition.slice("fleet-implementer-".length);
2941
2948
  }
2942
2949
 
2943
2950
  // The member a row's cell binds, while it has not settled, else null: the
@@ -2966,7 +2973,7 @@ function cellChangeRefusal(oldLine, line) {
2966
2973
  if (oldLine === null) return null;
2967
2974
  const cell = runnableCell(oldLine);
2968
2975
  if (cell === null) return null;
2969
- const tiers = [...new Set(tierValues(line))];
2976
+ const tiers = [...new Set(decidingCell(line).values)];
2970
2977
  const to = tiers.length === 0 ? POLICY_CELL : tiers.join(" and ");
2971
2978
  if (to === cell) return null;
2972
2979
  const member = unsettledImplementer(oldLine);
@@ -2991,7 +2998,8 @@ function withTier(line, tok) {
2991
2998
  // then dedupe against), and the row's ` · ` separator are no token. A member
2992
2999
  // token is `dispatch`'s or `settle`'s, a review token `review`'s. A word
2993
3000
  // shaped like a member that the grammar cannot parse, a `tier=` that is not
2994
- // a cell, a `tier=` naming a second tier in one call, a `held-behind`,
3001
+ // a cell, a `tier=` naming a second tier in one call, any `cell=` (the row
3002
+ // step's, never a token), a `held-behind`,
2995
3003
  // `conflict-hold` or `parked` token the tick cannot read, and a lone `→` — an
2996
3004
  // arrow with no PR beside it points at nothing — are refused. Every other
2997
3005
  // word is a freeform token.
@@ -3026,6 +3034,9 @@ function tokenRefusal(tok, earlier) {
3026
3034
  return `names a second tier — this call already names tier=${other}, and a row names one`;
3027
3035
  }
3028
3036
  }
3037
+ if (tok.startsWith("cell=")) {
3038
+ return "is the cell the Pull's row step wrote for a Pull routed without a draw — a replacement's cell is `tier=<cell>`";
3039
+ }
3029
3040
  if (tok === "→") return "is the row's arrow, which is written with the PR it points at — ledger.mjs row writes the whole line";
3030
3041
  if (badLabelOff([tok]) !== undefined) return LABEL_OFF_UNKNOWN;
3031
3042
  return null;
package/scripts/pull.mjs CHANGED
@@ -135,7 +135,7 @@ import { isDigits, makeDie } from "./arg.mjs";
135
135
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
136
136
  import { gitEnv } from "./git-env.mjs";
137
137
  import { isCLI } from "./is-cli.mjs";
138
- import { EXCLUDED_REASON, memberTokens, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
138
+ import { EXCLUDED_REASON, POLICY_CELL, memberTokens, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
139
139
  import { sessionFromReceipt } from "./phase0-receipt.mjs";
140
140
  import { briefPaths, briefText, defang, outOfScope, strandedRuling, ticketText } from "./ticket-text.mjs";
141
141
 
@@ -217,7 +217,8 @@ const isImplRow = (row) => memberTokens(row).some((t) => t.family === "impl");
217
217
  /**
218
218
  * The `--impl-row` the router is given: the row count the Pull creates — or,
219
219
  * while an exploration assignment is rolling (the latest row 5k and every row
220
- * after it carry no `tier=`), that row's number.
220
+ * after it carry no `tier=`: a `cell=` is a routed Pull's cell, not a draw), that
221
+ * row's number.
221
222
  */
222
223
  export function implRow(rows) {
223
224
  const impl = rows.filter(isImplRow);
@@ -964,7 +965,10 @@ class Pull {
964
965
  stage_row() {
965
966
  const { st } = this;
966
967
  const { cell, draw, reason } = st.route;
967
- const text = `${st.member}${draw === "-" ? "" : ` · tier=${cell}`}${reason === "ok" ? "" : ` · route=${reason}`}`;
968
+ // `tier=` marks a draw; a Pull routed without one still dispatches at the
969
+ // cell the router printed, carried as `cell=` so the row reads as undrawn.
970
+ const carrier = draw !== "-" ? ` · tier=${cell}` : cell !== POLICY_CELL ? ` · cell=${cell}` : "";
971
+ const text = `${st.member}${carrier}${reason === "ok" ? "" : ` · route=${reason}`}`;
968
972
  const r = this.script("row", "ledger.mjs", ["row", String(st.ticket), text]);
969
973
  if (r.status !== 0) return this.stop(withText(`ledger.mjs row failed (${r.how})`, r));
970
974
  st.stage = "render";
@@ -58,7 +58,7 @@
58
58
  // ledger's terms, not the caller's: the definition it should have
59
59
  // run under is the one its `## Dispatched` entry recorded at dispatch
60
60
  // (`agent=`, read through `ledger.mjs read`), falling back for an entry
61
- // without one to its ticket row's `tier=` token (ledger-grammar.mjs's
61
+ // without one to its ticket row's `tier=` or `cell=` token (ledger-grammar.mjs's
62
62
  // `expectedDefinition` — the same function `ledger.mjs dispatch` prints the
63
63
  // definition from), the agent type
64
64
  // it was actually dispatched as is
@@ -481,7 +481,7 @@ function main() {
481
481
  die(`batch entry missing member/agentFile: ${JSON.stringify(raw)}`);
482
482
  }
483
483
  if (impl && raw.agentFile) {
484
- die(`${raw.member}: an impl- entry carries no agentFile — its definition is the one its ## Dispatched entry recorded at dispatch, else the one its ledger row's tier= token names`);
484
+ die(`${raw.member}: an impl- entry carries no agentFile — its definition is the one its ## Dispatched entry recorded at dispatch, else the one its ledger row's tier= token, or cell= when it has none, names`);
485
485
  }
486
486
  const hasJobRecord = raw.resolvedModel && raw.resolvedThinkingLevel;
487
487
  let frontmatter = null, transcriptText = null, ticket = null, definition = null;
@@ -72,13 +72,15 @@ One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`; `ledg
72
72
  #<t5> excluded · behind-issue:#<t3>
73
73
  ```
74
74
 
75
+ A row's cell is its `tier=` (the cell a draw picked), else its `cell=` (the cell the router printed for a Pull it routed without a draw, like `#<t6> impl-<t6> · cell=task-high`; `row` writes it, `token` refuses it), else the policy cell, `slow-high`.
76
+
75
77
  ## Writing before dispatch
76
78
 
77
79
  A member that dies between spawn and write is invisible — and members die in batches.
78
80
 
79
81
  `dispatch merge-bot` also records the queue the bot is dispatched against: its `## Dispatched` entry carries `queued=<pr>,<pr>…` (`queued=none` for an empty queue), the open `ready-to-merge` PRs gh lists at that moment. A gh that cannot answer refuses the dispatch, nothing written. `settle merge-bot-<n> --from-report` judges the bot's report against that queue, not against anything the report names: a PR from it that is still open and carries the label, with no verdict in `merged`, `held`, `conflictHold` or `refused`, fails the settle at exit 3, naming the PR, and an entry without `queued=` cannot be judged (exit 2) — settle that bot by hand.
80
82
 
81
- `dispatch impl-<N>` also records the definition it prints: the implementer's `## Dispatched` entry ends with `agent=<definition>` (`agent=fleet-implementer-<cell>`), and `ledger.mjs read` prints it under `agents`, by member name. tier-check judges the implementer against that record, falling back to the row's `tier=` for an entry without one, so a `tier=` replaced after the implementer settled does not change what it is judged against. `settle` and `rotate` keep the word with its entry. A value that is not `[a-z0-9]` words joined by `-` makes the entry malformed, and the ledger is refused.
83
+ `dispatch impl-<N>` also records the definition it prints: the implementer's `## Dispatched` entry ends with `agent=<definition>` (`agent=fleet-implementer-<cell>`), and `ledger.mjs read` prints it under `agents`, by member name. tier-check judges the implementer against that record, falling back to the row's `tier=` (else `cell=`) for an entry without one, so a `tier=` replaced after the implementer settled does not change what it is judged against. `settle` and `rotate` keep the word with its entry. A value that is not `[a-z0-9]` words joined by `-` makes the entry malformed, and the ledger is refused.
82
84
 
83
85
  ## filed and ruled
84
86
 
@@ -110,4 +112,4 @@ The ledger half reports its own readability as its own field, `ledger.ok`, the p
110
112
 
111
113
  ## Adding a token
112
114
 
113
- Token additions go through `ledger.mjs token`. `ledger.mjs token <key> <token>…` adds a token and keeps every token already on the row. A `tier=` replaces the row's `tier=` instead and keeps every other token; while the row's implementer has not settled, `token` and `row` both refuse a write that changes the row's cell. Re-typing the row with `row` replaces the whole line, so it drops the tokens you do not restate.
115
+ Token additions go through `ledger.mjs token`. `ledger.mjs token <key> <token>…` adds a token and keeps every token already on the row. A `tier=` replaces the row's `tier=` instead and keeps every other token, a `cell=` beside it included, which the `tier=` then overrides; while the row's implementer has not settled, `token` and `row` both refuse a write that changes the row's cell. Re-typing the row with `row` replaces the whole line, so it drops the tokens you do not restate.
@@ -149,7 +149,7 @@ Each member's outcome arrives as its own job status. Settle (CONTEXT.md § Coord
149
149
 
150
150
  ## The implementer's tier is the definition's
151
151
 
152
- The tier lives in that definition's frontmatter (`agents/fleet-implementer-<cell>.agent.md`; `slow-high`, the policy cell, for a row with no `tier=`), which is what an omitted `model` takes first — the session's tier applies only when the definition names none, and a member dispatched with `model` set does not get the declared tier back. Omitting `model` is therefore still the mechanism; what changed is that the tier it resolves to is now declared and pinned rather than inherited by accident. Keep `name: impl-<N>`: the name is what makes a member, and both the spend classifier and `member-outcomes.mjs` read it.
152
+ The tier lives in that definition's frontmatter (`agents/fleet-implementer-<cell>.agent.md`; `slow-high`, the policy cell, for a row with no `tier=` or `cell=`), which is what an omitted `model` takes first — the session's tier applies only when the definition names none, and a member dispatched with `model` set does not get the declared tier back. Omitting `model` is therefore still the mechanism; what changed is that the tier it resolves to is now declared and pinned rather than inherited by accident. Keep `name: impl-<N>`: the name is what makes a member, and both the spend classifier and `member-outcomes.mjs` read it.
153
153
 
154
154
  ## The merge bot's tier buys nothing its backstop does not cover
155
155
 
@@ -252,7 +252,9 @@ terminating in exactly one dispatch or an empty shortlist:
252
252
  `POLICY=… CELL=… DRAW=… STRATUM=… OBJECTIVE=… REASON=…` (the router's arguments paragraph below the list
253
253
  says what each argument is); then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>][ · route=<REASON>]"`,
254
254
  `tier=<CELL>` exactly when `DRAW` is not `-`; then the dispatch at once: claim
255
- what you are about to dispatch; dispatch what you have just claimed. Router
255
+ what you are about to dispatch; dispatch what you have just claimed. A Pull
256
+ routed without a draw writes `cell=<CELL>` instead, unless `CELL` is the policy
257
+ cell, `slow-high`, which a row with neither runs. Router
256
258
  exit 2 → no row and no dispatch: release the claim (`release-ticket.sh`, SKILL.md's
257
259
  Failure handling row for a claim abandoned mid-run) and emit an event, a probe that could not look — a table the router
258
260
  refuses refuses every Pull.
@@ -261,7 +263,8 @@ terminating in exactly one dispatch or an empty shortlist:
261
263
  row count the Pull creates — or, while an assignment is rolling (the latest
262
264
  row 5k and every row after it carry no `tier=`), that row's number;
263
265
  `--chain-head` marks a ticket another open ticket sequences after, which is
264
- what rolls it. `--arm` is `A` for an even ticket number and `B` for an odd
266
+ what rolls it. A `cell=` is no draw: a row carrying one and no `tier=` still
267
+ rolls. `--arm` is `A` for an even ticket number and `B` for an odd
265
268
  one; a B Pull routes exactly as an A one until the table opens arm B.
266
269
  `--session` is this run's own session directory. The router routes by the
267
270
  row set of the run's Objective, `OBJECTIVE`, which it reads off the phase-0
@@ -399,7 +402,8 @@ the `render` command to run first, and refuses once the
399
402
  run is draining: drain stops supply. It also refuses a row whose `tier=`
400
403
  names no single definition — two different values, or one that is not a
401
404
  definition suffix — or names one with no `agents/<definition>.agent.md`,
402
- before the member is live; fix the row with `row` first. Once every refusal
405
+ before the member is live; fix the row with `row` first. A row with no `tier=`
406
+ is held to the same through its `cell=`. Once every refusal
403
407
  has passed, `dispatch` deletes the member's prior report,
404
408
  `<scratch>/reports/<member>.json`, when its brief's sidecar names an absolute
405
409
  `scratch`, so a prior run's report cannot settle this one. A sidecar naming
@@ -436,8 +440,12 @@ policy cell is the `cost` row set's, so the draw is the same under both. While t
436
440
  true every Pull draws, over every cell, the policy cell included. An
437
441
  Exploration Pull records `tier=<cell>` in the row, and a replacement inherits the row's tier —
438
442
  written at the Pull's row step, ahead of `ledger.mjs dispatch`, which reads it
439
- and prints `fleet-implementer-<cell>` as the `agent` to dispatch; a row with
440
- no `tier=` runs the policy cell. The Pull's cell binds the row's implementer
443
+ and prints `fleet-implementer-<cell>` as the `agent` to dispatch. A Pull the
444
+ router routes without a draw records the cell it printed as `cell=<cell>`
445
+ instead, and dispatches there the same way; `cell=` is no draw, so a row
446
+ carrying it and no `tier=` still reads as "the draw has not happened yet",
447
+ and a draw skipped on a chain head still passes to the next Pull. A `tier=` on the row decides over a
448
+ `cell=`. A row with neither runs the policy cell. The Pull's cell binds the row's implementer
441
449
  (its newest, on a resumed or re-Pulled row):
442
450
  `ledger.mjs row` and `ledger.mjs token` refuse a write that changes it until that implementer has
443
451
  settled. Once it has, a replacement may run at another cell, set with