@feigi/fleet-ctl 3.113.0 → 3.114.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.113.0",
3
+ "version": "3.114.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": {
@@ -704,6 +704,7 @@ export const pullEnded = (record) => record.status === "released" || (record.sta
704
704
 
705
705
  export const ROWS = "## Rows";
706
706
  export const DISPATCHED = "## Dispatched";
707
+ export const ROUTED = "## Routed";
707
708
  export const FILED = "## Filed";
708
709
  export const RULED = "## Ruled";
709
710
  export const DRAIN = "## Drain";
@@ -804,6 +805,97 @@ export function drawCell({ session, ticket, policyCell, cells }) {
804
805
  return { cell: E[k - 1], k, K };
805
806
  }
806
807
 
808
+ // A Pull's Routing: the Router's decision for that Pull, the one line
809
+ // `ticket-router.mjs route` prints. The Pull's row step writes it to the
810
+ // ledger's `## Routed` section in the same `ledger.mjs row` write as the row,
811
+ // after the Pull's first implementer's member token, and it never changes
812
+ // after: the row's `tier=`/`cell=` stay the mutable "Cell the next
813
+ // implementer runs at". One grammar for the line, here, read by `pull.mjs` off
814
+ // the router's stdout and by `ledger.mjs` to refuse a malformed one; the
815
+ // cockpit's board card is to read it too, and does not yet. Its words, in
816
+ // this order, `-` for none:
817
+ // POLICY the policy row's Cell CELL the Pull's Cell
818
+ // DRAW k/K of the draw BY burn-in | every-5th
819
+ // STRATUM light | heavy | unknown BRIEF the brief's chars
820
+ // CRITERIA the criteria count SIZED arm B's sizing label
821
+ // OBJECTIVE cost | speed TRIPPED the guard's tripped Cells
822
+ // REASON the first thing that went wrong
823
+ // DRAW and BY are `-` together (no draw); so are BRIEF and CRITERIA (no issue read).
824
+ export const STRATA = Object.freeze(["light", "heavy", "unknown"]);
825
+ // What a run asks the router to minimise. phase0.mjs records the run's in its
826
+ // receipt, and every Routing names the one it routed by.
827
+ export const OBJECTIVES = Object.freeze(["cost", "speed"]);
828
+ const DRAWN_BY = Object.freeze(["burn-in", "every-5th"]);
829
+ export const ROUTING_REASONS = Object.freeze(["ok", "no-issue-json", "no-sizing", "guard-missing", "guard-tripped", "table-cell-tripped"]);
830
+ const SIZINGS = Object.freeze(["light", "heavy"]);
831
+ const ROUTING_KEYS = Object.freeze(["POLICY", "CELL", "DRAW", "BY", "STRATUM", "BRIEF", "CRITERIA", "SIZED", "OBJECTIVE", "TRIPPED", "REASON"]);
832
+ const COUNT = /^(?:0|[1-9][0-9]*)$/;
833
+ const DRAW = /^([1-9][0-9]*)\/([1-9][0-9]*)$/;
834
+
835
+ /**
836
+ * A Routing line read into its parts, or null when it is not one.
837
+ * @returns {null | { policy: string, cell: string, draw: null | { k: number, K: number }, by: null | string,
838
+ * stratum: string, brief: null | number, criteria: null | number, sized: null | string, objective: string,
839
+ * tripped: string[], reason: string }}
840
+ */
841
+ export function parseRouting(line) {
842
+ if (typeof line !== "string") return null;
843
+ const words = line.split(" ");
844
+ if (words.length !== ROUTING_KEYS.length) return null;
845
+ const v = {};
846
+ for (const [i, key] of ROUTING_KEYS.entries()) {
847
+ if (!words[i].startsWith(`${key}=`)) return null;
848
+ v[key] = words[i].slice(key.length + 1);
849
+ }
850
+ const opt = (x, ok) => (x === "-" ? null : ok(x) ? x : undefined);
851
+ const count = (x) => (x === "-" ? null : COUNT.test(x) ? Number(x) : undefined);
852
+ const tripped = v.TRIPPED === "-" ? [] : v.TRIPPED.split(",");
853
+ const d = DRAW.exec(v.DRAW);
854
+ const r = {
855
+ policy: CELL.test(v.POLICY) ? v.POLICY : undefined,
856
+ cell: CELL.test(v.CELL) ? v.CELL : undefined,
857
+ draw: v.DRAW === "-" ? null : d === null ? undefined : { k: Number(d[1]), K: Number(d[2]) },
858
+ by: opt(v.BY, (x) => DRAWN_BY.includes(x)),
859
+ stratum: STRATA.includes(v.STRATUM) ? v.STRATUM : undefined,
860
+ brief: count(v.BRIEF),
861
+ criteria: count(v.CRITERIA),
862
+ sized: opt(v.SIZED, (x) => SIZINGS.includes(x)),
863
+ objective: OBJECTIVES.includes(v.OBJECTIVE) ? v.OBJECTIVE : undefined,
864
+ tripped: tripped.every((c) => CELL.test(c)) ? tripped : undefined,
865
+ reason: ROUTING_REASONS.includes(v.REASON) ? v.REASON : undefined,
866
+ };
867
+ if (Object.values(r).includes(undefined)) return null;
868
+ if (r.draw !== null && r.draw.k > r.draw.K) return null;
869
+ if ((r.draw === null) !== (r.by === null) || (r.brief === null) !== (r.criteria === null)) return null;
870
+ return r;
871
+ }
872
+
873
+ /** The Routing line for parsed parts; throws on parts no Routing line can carry, so nothing writes one parseRouting refuses. */
874
+ export function formatRouting({ policy, cell, draw, by, stratum, brief, criteria, sized, objective, tripped, reason }) {
875
+ const none = (x) => (x === null ? "-" : String(x));
876
+ const line = [
877
+ `POLICY=${policy}`, `CELL=${cell}`, `DRAW=${draw === null ? "-" : `${draw.k}/${draw.K}`}`, `BY=${none(by)}`,
878
+ `STRATUM=${stratum}`, `BRIEF=${none(brief)}`, `CRITERIA=${none(criteria)}`, `SIZED=${none(sized)}`,
879
+ `OBJECTIVE=${objective}`, `TRIPPED=${tripped.length === 0 ? "-" : tripped.join(",")}`, `REASON=${reason}`,
880
+ ].join(" ");
881
+ if (parseRouting(line) === null) throw new Error(`not a Routing: ${line}`);
882
+ return line;
883
+ }
884
+
885
+ /** A `## Routed` entry: the Pull's first implementer's member name, then its Routing line. */
886
+ export function routedEntry(member, line) {
887
+ return `${member} ${line}`;
888
+ }
889
+
890
+ /** A `## Routed` entry read into its implementer's name and Routing, or null when it is not one. */
891
+ export function parseRoutedEntry(entry) {
892
+ const sp = typeof entry === "string" ? entry.indexOf(" ") : -1;
893
+ if (sp === -1) return null;
894
+ const member = entry.slice(0, sp);
895
+ const routing = parseRouting(entry.slice(sp + 1));
896
+ return parseMember(member)?.family === "impl" && routing !== null ? { member, routing } : null;
897
+ }
898
+
807
899
  // The definition an implementer is dispatched under, off its ticket
808
900
  // row's cell token — none means `fleet-implementer-<POLICY_CELL>`,
809
901
  // `tier=<x>` or `cell=<x>` means `fleet-implementer-<x>`. `tier=` is the
@@ -8,7 +8,11 @@
8
8
  // and `token` appends tokens to one, or replaces its `tier=`, which it refuses
9
9
  // while the row's implementer has not settled. `filed` and `ruled` are
10
10
  // append-only, because their whole purpose is to outlive the reasoning that
11
- // produced them; `filed` appends at most one row per issue.
11
+ // produced them; `filed` appends at most one row per issue. `## Routed` is
12
+ // append-only too: `row --routing <line>` files a Pull's Routing under its
13
+ // first implementer in the same write as the row, at most once per member,
14
+ // and a rotate carries an entry exactly when it carries a row naming that
15
+ // member.
12
16
  //
13
17
  // `dispatch`, `settle`, `review` and `drain` exist so a reader can derive
14
18
  // every liveness count from this file alone, rather than from row text a
@@ -58,7 +62,7 @@ import { fileURLToPath } from "node:url";
58
62
  import { spawnSync, execFileSync } from "node:child_process";
59
63
  import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
60
64
  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, 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";
65
+ 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, ROUTED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, parseRouting, parseRoutedEntry, routedEntry, headerRe, escapeText, ledgerSection, nextReviewerName } from "./ledger-grammar.mjs";
62
66
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
63
67
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
64
68
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -490,7 +494,7 @@ function refuseStrayInId(value, what) {
490
494
  let ledgerParsed = false;
491
495
 
492
496
  function load() {
493
- if (!existsSync(file)) return { rows: [], filed: [], ruled: [], ...dispatchedOf([]), drain: null, retired: [] };
497
+ if (!existsSync(file)) return { rows: [], filed: [], ruled: [], ...dispatchedOf([]), routed: [], drain: null, retired: [] };
494
498
  let text;
495
499
  try {
496
500
  text = readFileSync(file, "utf8");
@@ -516,7 +520,7 @@ function load() {
516
520
  }
517
521
  return {
518
522
  rows: section(ROWS), filed: section(FILED), ruled: section(RULED),
519
- ...dispatchedOf(section(DISPATCHED)), drain: drainEntries[0] ?? null,
523
+ ...dispatchedOf(section(DISPATCHED)), routed: section(ROUTED), drain: drainEntries[0] ?? null,
520
524
  retired: section(RETIRED),
521
525
  };
522
526
  }
@@ -538,7 +542,9 @@ function dispatchedOf(entries) {
538
542
  // that is draining. `## Retired` likewise: only an `ancestor` rotate writes
539
543
  // it (runRotate()), as the bare names of the members this omp session has
540
544
  // already run and the new ledger does not carry, so a ledger without it is
541
- // a session's first run.
545
+ // a session's first run. `## Routed` likewise, once a Pull's row step has
546
+ // recorded a Routing (`row --routing`), so a ledger holding none is written
547
+ // exactly as before that section existed.
542
548
  function save(d) {
543
549
  const list = (entries) => entries.map((r) => `- ${escapeText(r)}`).join("\n");
544
550
  const out =
@@ -547,6 +553,7 @@ function save(d) {
547
553
  const name = parseToken(t)?.name;
548
554
  return dispatchedEntry(t, d.briefs[name] ?? null, d.queued[name] ?? null, d.agents[name] ?? null);
549
555
  })) +
556
+ (d.routed.length === 0 ? "" : `\n\n${ROUTED}\n\n` + list(d.routed)) +
550
557
  `\n\n${FILED}\n\n` + list(d.filed) +
551
558
  `\n\n${RULED}\n\n` + list(d.ruled) +
552
559
  (d.drain === null ? "" : `\n\n${DRAIN}\n\n` + list([d.drain])) +
@@ -733,8 +740,15 @@ let data = cmd === "rotate" ? null : load();
733
740
  if (cmd === "read") {
734
741
  console.log(JSON.stringify(data));
735
742
  } else if (cmd === "row") {
736
- const [ticket, ...textParts] = rest;
737
- if (!ticket || textParts.length === 0) die("usage: ledger.mjs row <ticket> <text>");
743
+ // `--routing <line>` records the Pull's Routing in `## Routed` in this same
744
+ // write, so the row and the Routing the router printed for it land together
745
+ // or not at all.
746
+ if (hasEqualsForm("routing", rest)) die("--routing needs a space-separated value, not --routing=");
747
+ const routingIdx = rest.indexOf("--routing");
748
+ const routing = routingIdx === -1 ? null : rest[routingIdx + 1];
749
+ if (routingIdx !== -1 && isFlagLike(routing)) die("--routing needs the line `ticket-router.mjs route` printed");
750
+ const [ticket, ...textParts] = routingIdx === -1 ? rest : rest.toSpliced(routingIdx, 2);
751
+ if (!ticket || textParts.length === 0) die("usage: ledger.mjs row <ticket> <text> [--routing <line>]");
738
752
  // A stray flag here becomes the row KEY, which is what the rewrite-in-place
739
753
  // lookup below matches on — so the real ticket's next `row` call finds no
740
754
  // match and appends a second row instead of rewriting the first.
@@ -793,6 +807,30 @@ if (cmd === "read") {
793
807
  // re-judged. Local only.
794
808
  const refusal = rowWriteRefusal(data.rows, after, oldRow, line);
795
809
  if (refusal !== null) die(`row ${key}: ${refusal}`);
810
+ // The Routing is filed under the Pull's first implementer, the one live
811
+ // `impl-` member the row names, and written once: a second, different entry
812
+ // for that member would give the cockpit two answers to why the Pull ran on
813
+ // its Cell. The same entry again is the row step re-run after its write
814
+ // landed — a `pull.mjs` stopped before it recorded the step done — so it is
815
+ // left as it was and the row is still rewritten.
816
+ let routed = null;
817
+ let routedAlready = false;
818
+ if (routing !== null) {
819
+ if (parseRouting(routing) === null) die(`row ${key}: --routing '${routing}' is not a Routing line — the one \`ticket-router.mjs route\` prints`);
820
+ const impls = memberTokens(line).filter((t) => t.family === "impl" && t.outcome === null);
821
+ if (impls.length !== 1) {
822
+ die(`row ${key}: --routing is filed under the Pull's implementer, so the row must name exactly one live impl- member — it names ${impls.length === 0 ? "none" : impls.map((t) => t.name).join(", ")}`);
823
+ }
824
+ routed = routedEntry(impls[0].name, routing);
825
+ const prior = data.routed.find((e) => e.split(" ")[0] === impls[0].name);
826
+ if (prior === undefined) {
827
+ data.routed = [...data.routed, routed];
828
+ } else if (prior === routed) {
829
+ routedAlready = true;
830
+ } else {
831
+ die(`row ${key}: ${impls[0].name} already has its Routing in ${ROUTED} ('${prior}') — a Pull's Routing is written once`);
832
+ }
833
+ }
796
834
  data.rows = after;
797
835
  // Logged only after save() returns — a failed write must not claim a row
798
836
  // was recorded when it never made it to disk.
@@ -806,7 +844,8 @@ if (cmd === "read") {
806
844
  const dropped = droppedTokens(oldRow, line);
807
845
  console.error(` rewrote row ${key}${dropped.length === 0 ? "" : `; dropped: ${dropped.join(" ")}`}`);
808
846
  }
809
- console.log(JSON.stringify({ ticket: key, line, created }));
847
+ if (routed !== null) console.error(` routed ${routed}${routedAlready ? " (already filed; left as it was)" : ""}`);
848
+ console.log(JSON.stringify({ ticket: key, line, created, ...(routed === null ? {} : { routed }) }));
810
849
  } else if (cmd === "filed") {
811
850
  const [issue, ...subjectParts] = rest;
812
851
  if (!issue || subjectParts.length === 0) die("usage: ledger.mjs filed <issue> <subject>");
@@ -1639,7 +1678,7 @@ function runRotate() {
1639
1678
  }
1640
1679
  // Read before anything moves: a ledger whose live tokens cannot be read is
1641
1680
  // refused with nothing moved, never archived with those tokens dropped.
1642
- let carry = { rows: [], dispatched: [], retired: [], skipped: [] };
1681
+ let carry = { rows: [], dispatched: [], routed: [], retired: [], skipped: [] };
1643
1682
  if (prior === "ancestor" && exists) {
1644
1683
  let text;
1645
1684
  try {
@@ -1708,6 +1747,7 @@ function runRotate() {
1708
1747
  }
1709
1748
  if (carrying) {
1710
1749
  console.error(` carried ${carry.rows.length} row(s) and ${carry.dispatched.length} ## Dispatched entr${carry.dispatched.length === 1 ? "y" : "ies"} from ${archive}`);
1750
+ if (carry.routed.length > 0) console.error(` carried ${carry.routed.length} ${ROUTED} entr${carry.routed.length === 1 ? "y" : "ies"} from ${archive}`);
1711
1751
  console.error(` retired ${carry.retired.length} name(s) from ${archive}`);
1712
1752
  }
1713
1753
  // Re-read rather than reuse the read above: the heartbeat file has other
@@ -1720,7 +1760,7 @@ function runRotate() {
1720
1760
  }
1721
1761
  console.log(JSON.stringify({
1722
1762
  rotated: archive !== null, archive,
1723
- carried: { rows: carry.rows, dispatched: carry.dispatched },
1763
+ carried: { rows: carry.rows, dispatched: carry.dispatched, routed: carry.routed },
1724
1764
  retired: carry.retired,
1725
1765
  skipped: carry.skipped.map((s) => s.line),
1726
1766
  }));
@@ -1788,7 +1828,16 @@ function carryOf(text) {
1788
1828
  const live = liveOnLedger(rows, dispatched);
1789
1829
  const carried = { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched };
1790
1830
  const retired = retiredOnLedger([...rows, ...skippedRows], allDispatched, archivedRetired, carried);
1791
- return { ...carried, briefs: allBriefs, queued: allQueued, agents: allAgents, retired, skipped };
1831
+ // A Pull's Routing travels with its row, as a `## Dispatched` entry does:
1832
+ // each entry whose member a carried row names, and no other.
1833
+ const named = new Set(carried.rows.flatMap(memberTokens).map((t) => t.name));
1834
+ const routed = [];
1835
+ for (const entry of ledgerSection(text, ROUTED)) {
1836
+ const parsed = parseRoutedEntry(entry);
1837
+ if (parsed === null) skipped.push({ line: entry, why: "not an implementer's name and a Routing line" });
1838
+ else if (named.has(parsed.member)) routed.push(entry);
1839
+ }
1840
+ return { ...carried, routed, briefs: allBriefs, queued: allQueued, agents: allAgents, retired, skipped };
1792
1841
  }
1793
1842
 
1794
1843
  // ── dispatch / settle ────────────────────────────────────────────────────────
@@ -11,7 +11,7 @@
11
11
  import { readFileSync } from "node:fs";
12
12
  import { join } from "node:path";
13
13
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
14
- import { RECEIPT } from "./ledger-grammar.mjs";
14
+ import { OBJECTIVES, RECEIPT } from "./ledger-grammar.mjs";
15
15
 
16
16
  const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
17
17
 
@@ -141,10 +141,10 @@ export function sessionFromReceipt(opts) {
141
141
  throw new Error(`no session given and none in the phase-0 receipt ${path} (${why}) — give one, or run ${phase0Command(null)} first`);
142
142
  }
143
143
 
144
- // What a run asks the router to minimise, and the one it asks when nobody
145
- // names one. phase0.mjs records the run's in its receipt; a receipt written
146
- // before it recorded one is read as the default when phase 0 resumes it.
147
- export const OBJECTIVES = Object.freeze(["cost", "speed"]);
144
+ // The Objective a run asks the router to minimise when nobody names one;
145
+ // OBJECTIVES, the ones it can ask, is ledger-grammar.mjs's. phase0.mjs records
146
+ // the run's in its receipt; a receipt written before it recorded one is read
147
+ // as the default when phase 0 resumes it.
148
148
  export const OBJECTIVE_DEFAULT = "cost";
149
149
 
150
150
  /**
@@ -156,9 +156,9 @@ import { readState, stateFileIn } from "./fleet-state.mjs";
156
156
  import { gitEnv } from "./git-env.mjs";
157
157
  import { isCLI } from "./is-cli.mjs";
158
158
  import { GH_LOGIN_ARGS, isOwnedPr, loginOf, ownershipReadable } from "./owned-pr.mjs";
159
- import { RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
159
+ import { OBJECTIVES, RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
160
160
  import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
161
- import { IN_FLIGHT_DEFAULT, OBJECTIVES, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
161
+ import { IN_FLIGHT_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
162
162
 
163
163
  const NAME = "phase0";
164
164
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
package/scripts/pull.mjs CHANGED
@@ -110,7 +110,8 @@
110
110
  // still standing. `--chain-head` is given when a ledger row reads
111
111
  // `excluded · behind-issue:#<N>`: another open ticket
112
112
  // sequences after this one.
113
- // 8 row, render, dispatch `ledger.mjs row`, `dispatch-prompt.mjs render
113
+ // 8 row, render, dispatch `ledger.mjs row … --routing <line>`, the row and
114
+ // the router's line in one write, `dispatch-prompt.mjs render
114
115
  // implementer --member impl-<N>`, `ledger.mjs dispatch`. The
115
116
  // brief and the staleness text are given with `‹name›` for each
116
117
  // `<name>` the implementer template declares: the renderer
@@ -135,7 +136,7 @@ import { isDigits, makeDie } from "./arg.mjs";
135
136
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
136
137
  import { gitEnv } from "./git-env.mjs";
137
138
  import { isCLI } from "./is-cli.mjs";
138
- import { EXCLUDED_REASON, POLICY_CELL, memberTokens, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
139
+ import { EXCLUDED_REASON, POLICY_CELL, memberTokens, parseRouting, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
139
140
  import { sessionFromReceipt } from "./phase0-receipt.mjs";
140
141
  import { briefPaths, briefText, defang, outOfScope, strandedRuling, ticketText } from "./ticket-text.mjs";
141
142
 
@@ -945,8 +946,9 @@ class Pull {
945
946
  "--impl-row", String(k), ...(head ? ["--chain-head"] : []), "--issue", this.p.issue, "--guard", this.p.guard,
946
947
  ];
947
948
  const r = this.script("route", "ticket-router.mjs", args);
948
- const m = r.status === 0 ? /^POLICY=(\S+) CELL=(\S+) DRAW=(\S+) STRATUM=(\S+) OBJECTIVE=(\S+) REASON=(\S+)$/m.exec(r.stdout) : null;
949
- if (m === null) {
949
+ const line = r.stdout.trim();
950
+ const routing = r.status === 0 ? parseRouting(line) : null;
951
+ if (routing === null) {
950
952
  const said = r.status === 0 ? `printed no routing line: ${r.stdout}` : withText(`refused (${r.how})`, r);
951
953
  const rel = this.script("release", "release-ticket.sh", [String(st.ticket), st.member, "implementer", "--apply"]);
952
954
  if (rel.status !== 0) {
@@ -957,19 +959,19 @@ class Pull {
957
959
  st.outcome = { exit: 2, reason: `router ${said}`, at: now() };
958
960
  return this.stop(`ticket-router.mjs ${said}\nits claim is released`);
959
961
  }
960
- st.route = { line: m[0], cell: m[2], draw: m[3], reason: m[6], implRow: k, chainHead: head };
962
+ st.route = { line, cell: routing.cell, draw: routing.draw === null ? "-" : `${routing.draw.k}/${routing.draw.K}`, reason: routing.reason, implRow: k, chainHead: head };
961
963
  st.stage = "row";
962
964
  return null;
963
965
  }
964
966
 
965
967
  stage_row() {
966
968
  const { st } = this;
967
- const { cell, draw, reason } = st.route;
969
+ const { cell, draw } = st.route;
968
970
  // `tier=` marks a draw; a Pull routed without one still dispatches at the
969
971
  // cell the router printed, carried as `cell=` so the row reads as undrawn.
972
+ // The Routing itself goes to `## Routed` in the same write.
970
973
  const carrier = draw !== "-" ? ` · tier=${cell}` : cell !== POLICY_CELL ? ` · cell=${cell}` : "";
971
- const text = `${st.member}${carrier}${reason === "ok" ? "" : ` · route=${reason}`}`;
972
- const r = this.script("row", "ledger.mjs", ["row", String(st.ticket), text]);
974
+ const r = this.script("row", "ledger.mjs", ["row", String(st.ticket), `${st.member}${carrier}`, "--routing", st.route.line]);
973
975
  if (r.status !== 0) return this.stop(withText(`ledger.mjs row failed (${r.how})`, r));
974
976
  st.stage = "render";
975
977
  return null;
@@ -7,8 +7,11 @@
7
7
  // --impl-row <k> --issue <issue.json> --guard <cost-guard.json>
8
8
  // [--sizing <sizing.json>] [--table <router-table.json>]
9
9
  // [--chain-head] [--pending <tsv>]
10
- // Prints one line, `POLICY=<cell> CELL=<cell> DRAW=<k/K|->
11
- // STRATUM=<light|heavy|unknown> OBJECTIVE=<cost|speed> REASON=<reason>`,
10
+ // Prints one line, the Pull's Routing (ledger-grammar.mjs owns its
11
+ // grammar): `POLICY=<cell> CELL=<cell> DRAW=<k/K|-> BY=<burn-in|every-5th|->
12
+ // STRATUM=<light|heavy|unknown> BRIEF=<chars|-> CRITERIA=<n|->
13
+ // SIZED=<light|heavy|-> OBJECTIVE=<cost|speed> TRIPPED=<cell,…|->
14
+ // REASON=<reason>`,
12
15
  // routing by the objective's row set, and appends the Pull's
13
16
  // ticket-features row to the pending TSV (by default
14
17
  // `ticket-features.pending.tsv` beside `--guard`, in the run's `.fleet/`). Exit 0 on
@@ -48,8 +51,8 @@ import { isDeepStrictEqual } from "node:util";
48
51
  import { isCLI } from "./is-cli.mjs";
49
52
  import { gitEnv } from "./git-env.mjs";
50
53
  import { makeDie, defineFlags } from "./arg.mjs";
51
- import { CELL, POLICY_CELL, drawCell, parseMember } from "./ledger-grammar.mjs";
52
- import { OBJECTIVES, objectiveFromReceipt, sessionFromReceipt } from "./phase0-receipt.mjs";
54
+ import { CELL, OBJECTIVES, POLICY_CELL, STRATA, drawCell, formatRouting, parseMember } from "./ledger-grammar.mjs";
55
+ import { objectiveFromReceipt, sessionFromReceipt } from "./phase0-receipt.mjs";
53
56
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
54
57
  import {
55
58
  AttributionError, FEATURE_COLUMNS, TRIP_POINTS, attribute, bootUnit, bootstrapDiffCI, generations, parseFeatures, tally, underFloor,
@@ -61,11 +64,10 @@ const NAME = "ticket-router";
61
64
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
62
65
  export const DEFAULT_TABLE = join(SCRIPT_DIR, "router-table.json");
63
66
 
64
- export const STRATA = Object.freeze(["light", "heavy", "unknown"]);
65
67
  // The free classifier's thresholds: heavy past the median brief length of
66
68
  // the tickets whose sizing verdict is known, or past five criteria.
67
- const HEAVY_BRIEF_CHARS = 3483;
68
- const HEAVY_CRITERIA = 5;
69
+ export const HEAVY_BRIEF_CHARS = 3483;
70
+ export const HEAVY_CRITERIA = 5;
69
71
  // Exploration cadence after burn-in: the Pull that creates `impl-` row 5k.
70
72
  const EXPLORE_EVERY = 5;
71
73
  // The fit's adoption floor (merged PRs per side), margin, and cadence.
@@ -244,7 +246,8 @@ export function route({ session, ticket, arm, implRow, chainHead = false, issue,
244
246
  const costB = arm === "B" && bArmLive(table, "cost");
245
247
  let drawBase = rowFor(table.rows.cost, costB ? sized?.stratum ?? "unknown" : ruleS);
246
248
  let cell;
247
- let draw = "-";
249
+ let draw = null;
250
+ let by = null;
248
251
  if (guard === null) {
249
252
  // The guard cannot be evaded by deleting it: no guard, default cell only.
250
253
  degrade("guard-missing");
@@ -266,7 +269,8 @@ export function route({ session, ticket, arm, implRow, chainHead = false, issue,
266
269
  const d = drawCell({ session, ticket, policyCell, cells: table.cells.filter((c) => !tripped.has(c)) });
267
270
  if (d.K > 0) {
268
271
  cell = d.cell;
269
- draw = `${d.k}/${d.K}`;
272
+ draw = { k: d.k, K: d.K };
273
+ by = table.burn_in ? "burn-in" : "every-5th";
270
274
  }
271
275
  }
272
276
  }
@@ -274,10 +278,15 @@ export function route({ session, ticket, arm, implRow, chainHead = false, issue,
274
278
 
275
279
  const row = {
276
280
  run_date: sessionDate(session), session, agent: `impl-${ticket}`, ticket: String(ticket),
277
- policy_cell: policy, chosen_cell: cell, exploration_draw: draw === "-" ? "" : draw,
281
+ policy_cell: policy, chosen_cell: cell, exploration_draw: draw === null ? "" : `${draw.k}/${draw.K}`,
278
282
  sizing_src: sizingSrc, sizing_pre: sizingPre, router_usd: routerUsd, ...m, objective,
279
283
  };
280
- return { line: `POLICY=${policy} CELL=${cell} DRAW=${draw} STRATUM=${stratum} OBJECTIVE=${objective} REASON=${reason}`, row };
284
+ const line = formatRouting({
285
+ policy, cell, draw, by, stratum,
286
+ brief: metrics === null ? null : Number(metrics.brief_chars), criteria: metrics === null ? null : Number(metrics.criteria),
287
+ sized: sizingPre === "" ? null : sizingPre, objective, tripped: guard?.tripped ?? [], reason,
288
+ });
289
+ return { line, row };
281
290
  }
282
291
 
283
292
  export function formatFeatureRow(row) {
@@ -248,13 +248,18 @@ terminating in exactly one dispatch or an empty shortlist:
248
248
  --apply` (below). Exit 2 → treat it as taken, next entry.
249
249
  7. **Route, row, then dispatch** — `~/.fleet/bin/fleet-run ticket-router.mjs route
250
250
  --session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
251
- <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints
252
- `POLICY=… CELL=… DRAW=… STRATUM=… OBJECTIVE=… REASON=…` (the router's arguments paragraph below the list
253
- says what each argument is); then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>][ · route=<REASON>]"`,
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. 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
251
+ <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints the Pull's
252
+ Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… SIZED=… OBJECTIVE=… TRIPPED=… REASON=…`
253
+ (the router's arguments paragraph below the list says what each argument is);
254
+ then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>]" --routing "<that line>"`,
255
+ `tier=<CELL>` exactly when `DRAW` is not `-`, which writes the row and files
256
+ the line verbatim under `impl-<N>` in `## Routed` in one write; then the
257
+ dispatch at once: claim what you are about to dispatch; dispatch what you
258
+ have just claimed. A Pull routed without a draw writes `cell=<CELL>` instead,
259
+ unless `CELL` is the policy cell, `slow-high`, which a row with neither runs.
260
+ `ledger.mjs` refuses a line that is not a Routing and a second, different
261
+ Routing for `impl-<N>`; the same line again — the row step re-run after its
262
+ write landed — rewrites the row and leaves the entry as it was. Router
258
263
  exit 2 → no row and no dispatch: release the claim (`release-ticket.sh`, SKILL.md's
259
264
  Failure handling row for a claim abandoned mid-run) and emit an event, a probe that could not look — a table the router
260
265
  refuses refuses every Pull.
@@ -271,8 +276,9 @@ row set of the run's Objective, `OBJECTIVE`, which it reads off the phase-0
271
276
  receipt. The printed line is the
272
277
  whole routing decision — never re-derive `CELL` from the table, the guard or
273
278
  this paragraph. A missing or unreadable `.fleet/cost-guard.json` routes the
274
- default cell only (`REASON=guard-missing`), burn-in included, and `REASON`
275
- other than `ok` goes on the row as `route=<REASON>`, nowhere else.
279
+ default cell only (`REASON=guard-missing`), burn-in included. On the ledger the
280
+ whole line, `REASON` with it, is the Pull's `## Routed` entry; a row carries no
281
+ `route=` (an older row's `route=<REASON>` still reads).
276
282
 
277
283
  **The Pull table** — every verdict a Pull can reach, and the one thing each
278
284
  does: