@feigi/fleet-ctl 3.125.0 → 3.125.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.125.0",
3
+ "version": "3.125.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": {
@@ -30,11 +30,10 @@
30
30
 
31
31
  import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
32
32
  import { computeSpend, attributeTools, mergeTools } from "./compute-spend.mjs";
33
- import {
34
- isOmpSessionDirName, ompSessionTranscripts, foldOmpTranscript, ompMemberRecord,
35
- } from "./member-record.mjs";
33
+ import { ompSessionTranscripts, foldOmpTranscript, ompMemberRecord } from "./member-record.mjs";
36
34
  import { readReceipt } from "./phase0-receipt.mjs";
37
- import { RECEIPT, RECEIPT_HELD, CLOSEOUT_RECEIPT, OBJECTIVES } from "./ledger-grammar.mjs";
35
+ import { RECEIPT, RECEIPT_HELD, CLOSEOUT_RECEIPT, OBJECTIVES, isOmpSessionDirName } from "./ledger-grammar.mjs";
36
+ import { lastSegment } from "./pull-attribution.mjs";
38
37
  import { NAME, warnOnce, execRead } from "./board-common.mjs";
39
38
  import { mergedReadPrs, issuesOfPrs } from "./compute-board.mjs";
40
39
  import { readCostGuard } from "./fleet-tick.mjs";
@@ -467,7 +466,7 @@ export function receiptSpendDir(stateDir) {
467
466
 
468
467
  // Scope is the SESSION directory, which is the closest thing to a run
469
468
  // boundary that actually exists on disk — one session, one folder,
470
- // identified by its own NAME: `<ISO>_<uuid>` (member-record.mjs's
469
+ // identified by its own NAME: `<ISO>_<uuid>` (ledger-grammar.mjs's
471
470
  // isOmpSessionDirName, the rule its own readers dispatch on).
472
471
  //
473
472
  // `sinceMs` is opt-in and defaults to no filter. An earlier attempt defaulted it
@@ -723,6 +722,64 @@ export function readHeldImplementers(stateDir, implementers) {
723
722
  }
724
723
  }
725
724
 
725
+ // A carried row's implementer: when `ledger.mjs rotate` carries an
726
+ // implementer's `## Dispatched` entry into the next run's ledger it stamps it
727
+ // `session=<name>`, the omp session the implementer ran in, which no receipt
728
+ // beside the ledger names any more. `sessions` is `ledger.mjs read`'s map of
729
+ // those names by member. Each name is resolved under the directory the
730
+ // current receipt's session sits in, else the held receipt's — this
731
+ // checkout's project under the omp session root — so the ledger holds a name
732
+ // and never a path. From a stamped session the cards take the stamped
733
+ // members' own records and no other implementer's, and each replaces any
734
+ // record a receipt's session gave the same member. No receipt naming a session
735
+ // directory, and a stamped directory not there, add nothing; one that cannot
736
+ // be listed adds nothing and says why on stderr. A transcript that will not
737
+ // read is skipped as readHeldImplementers skips it.
738
+ function readStampedImplementers(stateDir, sessions, implementers) {
739
+ const stamped = new Map();
740
+ for (const [member, session] of Object.entries(sessions ?? {})) {
741
+ if (!isImplementer(member) || !isOmpSessionDirName(session)) continue;
742
+ if (!stamped.has(session)) stamped.set(session, new Set());
743
+ stamped.get(session).add(member);
744
+ }
745
+ if (stamped.size === 0) return;
746
+ const root = sessionRoot(stateDir);
747
+ if (root === null) return;
748
+ for (const [session, members] of stamped) {
749
+ const dir = join(root, session);
750
+ let transcripts;
751
+ try { transcripts = ompSessionTranscripts(dir); } catch (e) {
752
+ if (e.code !== "ENOENT") warnOnce("stamped-session", `${dir}\0${e.code ?? e.message}`, `no card reads ${dir}: ${e.code ?? e.message}`);
753
+ continue;
754
+ }
755
+ for (const { file, agent, spawnDepth } of transcripts) {
756
+ if (!isImplementer(agent) || !members.has(lastSegment(agent))) continue;
757
+ try {
758
+ const folded = foldOmpTranscript(readFileSync(file, "utf8"), file);
759
+ damagedRecord(file, folded);
760
+ const m = ompMemberRecord(folded, agent, spawnDepth);
761
+ if (!m) continue;
762
+ const leaf = lastSegment(m.member);
763
+ for (const key of [...implementers.keys()]) if (key !== m.member && lastSegment(key) === leaf) implementers.delete(key);
764
+ implementers.set(m.member, implementerRecord(m));
765
+ } catch (e) {
766
+ warnOnce("skips", file, `skipping ${file}: ${e.message}`);
767
+ }
768
+ }
769
+ }
770
+ }
771
+
772
+ // The directory this checkout's omp sessions sit in: the parent of the
773
+ // session the current receipt names, else of the held receipt's, or null when
774
+ // neither names an omp session directory.
775
+ function sessionRoot(stateDir) {
776
+ for (const name of [RECEIPT, RECEIPT_HELD]) {
777
+ const read = readReceipt(join(stateDir, name));
778
+ if (read.state === "ok" && isOmpSessionDirName(basename(read.receipt.session))) return dirname(read.receipt.session);
779
+ }
780
+ return null;
781
+ }
782
+
726
783
  // An implementer transcript read for the cards alone, where no spend panel
727
784
  // counts it `damaged`: a malformed middle line can drop the turn its model
728
785
  // came from, so the card's record is said to be suspect, once per file.
@@ -1109,10 +1166,16 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1109
1166
  // whose main() runs it and hands the answer in as `spendSince`.
1110
1167
  // Each implementer's dispatch record, for the cards' Cell lines: off the
1111
1168
  // same transcripts the spend is read from, or — with no `phase0.json`, the
1112
- // state between runs — off the session `phase0.previous.json` names.
1169
+ // state between runs — off the session `phase0.previous.json` names; and,
1170
+ // either way, a carried row's implementer off the session its
1171
+ // `## Dispatched` entry's `session=` names. A named --spend-dir is the one
1172
+ // session read.
1113
1173
  const implementers = new Map();
1114
1174
  const spend = gatherSpend({ dir: spendDir, sinceMs: spendSince, explicit: spendDirExplicit, implementers });
1115
- if (stateDir !== null && !spendDirExplicit && !existsSync(join(stateDir, RECEIPT))) readHeldImplementers(stateDir, implementers);
1175
+ if (stateDir !== null && !spendDirExplicit) {
1176
+ if (!existsSync(join(stateDir, RECEIPT))) readHeldImplementers(stateDir, implementers);
1177
+ readStampedImplementers(stateDir, ledger.sessions, implementers);
1178
+ }
1116
1179
  const routerTable = readRouterTable(scriptDir);
1117
1180
  // The heartbeat's mark, raw. readState() never throws — an absent
1118
1181
  // file is the ordinary state of a run whose heartbeat has not beaten yet,
@@ -97,8 +97,8 @@ import { makeDie, defineFlags } from "./arg.mjs";
97
97
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
98
98
  import { gitEnv } from "./git-env.mjs";
99
99
  import { isCLI } from "./is-cli.mjs";
100
- import { CLOSEOUT_RECEIPT, RECEIPT, RECEIPT_HELD, memberTokens, rowPr } from "./ledger-grammar.mjs";
101
- import { encodeProjectDir, isOmpSessionDirName } from "./member-record.mjs";
100
+ import { CLOSEOUT_RECEIPT, RECEIPT, RECEIPT_HELD, memberTokens, rowPr, isOmpSessionDirName } from "./ledger-grammar.mjs";
101
+ import { encodeProjectDir } from "./member-record.mjs";
102
102
  import { tickCaps } from "./phase0-receipt.mjs";
103
103
 
104
104
  const NAME = "closeout";
@@ -116,46 +116,76 @@ export function memberRole(family) {
116
116
  return FAMILIES[family].role;
117
117
  }
118
118
 
119
+ // An omp session directory is identified STRICTLY by name — `<ISO>_<uuid>`,
120
+ // e.g. `2026-09-08T13-13-27-300Z_01a08126-…` — never by holding `.jsonl`
121
+ // files directly. That second test used to be a shortcut, and it fired one
122
+ // level too high on the real tree: `~/.omp/agent/sessions/-dev-fleet-plugin/`
123
+ // holds the project's MAIN-session transcripts as plain files SIBLING to the
124
+ // per-session directories, so a reader recursing from the encoded-cwd dir
125
+ // hit the `.jsonl` test there first, returned the whole project as "one
126
+ // session", stamped every row `session=-dev-fleet-plugin` instead of the
127
+ // `<ISO>_<uuid>` name the row key is built on, and booked the controller's
128
+ // own top-level transcripts as members. Name-only matching costs nothing a
129
+ // real fixture needs: every fixture in this repo already names its session
130
+ // dir in the real shape.
131
+ const OMP_SESSION_DIR_RE = /^\d{4}-\d{2}-\d{2}T[\d-]+Z_[0-9a-f-]+$/i;
132
+
133
+ // The one definition of the session-directory name rule, shared by the
134
+ // `## Dispatched` grammar's `session=` word, the readers that walk or resolve
135
+ // session directories, and the CLIs that take one explicit directory.
136
+ export function isOmpSessionDirName(name) {
137
+ return OMP_SESSION_DIR_RE.test(name);
138
+ }
139
+
119
140
  // A `## Dispatched` entry is a member token, followed by `brief=<hash>` when
120
141
  // `ledger.mjs dispatch` recorded the brief the member was dispatched with:
121
142
  // the first 8 hex of the sha256 the brief's sidecar carries. A merge bot's
122
143
  // entry then carries `queued=<pr>,<pr>…` — `queued=none` for an empty queue —
123
144
  // the open `ready-to-merge` PRs `dispatch` read when it dispatched the bot,
124
145
  // which its report is judged against at `settle --from-report`. An
125
- // implementer's entry ends with `agent=<definition>`, the definition
146
+ // implementer's entry then carries `agent=<definition>`, the definition
126
147
  // `dispatch` printed for it, which tier-check judges it against. The value
127
148
  // becomes a file name under `agents/`, so it is held to `[a-z0-9]` words
128
- // joined by `-`, the shape of a `tier=` value. `settle` rewrites the token
129
- // and keeps the words beside it.
130
- const DISPATCHED_ENTRY = /^([^ ]*) brief=([0-9a-f]{8})(?: queued=(none|[1-9][0-9]*(?:,[1-9][0-9]*)*))?(?: agent=([a-z0-9]+(?:-[a-z0-9]+)*))?$/;
149
+ // joined by `-`, the shape of a `tier=` value. An implementer's entry a
150
+ // rotation carried ends with `session=<name>`, the omp session directory the
151
+ // implementer ran in — its name alone, never a path, held to
152
+ // isOmpSessionDirName() — which the cockpit reads its transcript from once
153
+ // the next run's receipt names a session of its own. `settle` rewrites the
154
+ // token and keeps the words beside it.
155
+ const DISPATCHED_ENTRY = /^([^ ]*) brief=([0-9a-f]{8})(?: queued=(none|[1-9][0-9]*(?:,[1-9][0-9]*)*))?(?: agent=([a-z0-9]+(?:-[a-z0-9]+)*))?(?: session=([^ ]+))?$/;
131
156
 
132
157
  /**
133
- * `{token, brief, queued, agent}` for one `## Dispatched` entry: the member
134
- * token, the brief's hash or null, the PR numbers of its `queued=` word or
135
- * null for an entry without one, and the definition of its `agent=` word or
136
- * null for an entry without one. An entry that is not a member token plus a
137
- * well-formed `brief=` word, optionally followed by a well-formed `queued=`
138
- * word and a well-formed `agent=` word, is returned whole as `token`, so a
139
- * reader parsing it with parseToken() refuses it exactly as it refuses any
140
- * other entry this grammar cannot parse.
158
+ * `{token, brief, queued, agent, session}` for one `## Dispatched` entry: the
159
+ * member token, the brief's hash or null, the PR numbers of its `queued=`
160
+ * word or null for an entry without one, the definition of its `agent=` word
161
+ * or null for an entry without one, and the session directory name of its
162
+ * `session=` word or null for an entry without one. An entry that is not a
163
+ * member token plus a well-formed `brief=` word, optionally followed by a
164
+ * well-formed `queued=` word, a well-formed `agent=` word and a well-formed
165
+ * `session=` word, is returned whole as `token`, so a reader parsing it with
166
+ * parseToken() refuses it exactly as it refuses any other entry this grammar
167
+ * cannot parse.
141
168
  */
142
169
  export function parseDispatchedEntry(entry) {
143
170
  const m = DISPATCHED_ENTRY.exec(entry);
144
- if (m === null || parseToken(m[1]) === null) return { token: entry, brief: null, queued: null, agent: null };
171
+ if (m === null || parseToken(m[1]) === null || (m[5] !== undefined && !isOmpSessionDirName(m[5]))) {
172
+ return { token: entry, brief: null, queued: null, agent: null, session: null };
173
+ }
145
174
  const queued = m[3] === undefined ? null : m[3] === "none" ? [] : m[3].split(",").map(Number);
146
- return { token: m[1], brief: m[2], queued, agent: m[4] ?? null };
175
+ return { token: m[1], brief: m[2], queued, agent: m[4] ?? null, session: m[5] ?? null };
147
176
  }
148
177
 
149
178
  /**
150
179
  * The `## Dispatched` entry for `token`, with `brief=<brief>` unless brief is
151
- * null and, after it, `queued=…` unless queued is null and `agent=<agent>`
152
- * unless agent is null.
180
+ * null and, after it, `queued=…` unless queued is null, `agent=<agent>`
181
+ * unless agent is null and `session=<session>` unless session is null.
153
182
  */
154
- export function dispatchedEntry(token, brief, queued = null, agent = null) {
183
+ export function dispatchedEntry(token, brief, queued = null, agent = null, session = null) {
155
184
  if (brief === null) return token;
156
185
  let entry = `${token} brief=${brief}`;
157
186
  if (queued !== null) entry += ` queued=${queued.join(",") || "none"}`;
158
187
  if (agent !== null) entry += ` agent=${agent}`;
188
+ if (session !== null) entry += ` session=${session}`;
159
189
  return entry;
160
190
  }
161
191
 
@@ -62,7 +62,8 @@ import { fileURLToPath } from "node:url";
62
62
  import { spawnSync, execFileSync } from "node:child_process";
63
63
  import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
64
64
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.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";
65
+ import { readReceipt } from "./phase0-receipt.mjs";
66
+ 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, isOmpSessionDirName } from "./ledger-grammar.mjs";
66
67
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
67
68
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
68
69
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -528,14 +529,16 @@ function load() {
528
529
 
529
530
  // `## Dispatched` held as its tokens, which is what every reader of `read`
530
531
  // parses, `briefs`, each member's `brief=` hash by name, `queued`, each
531
- // merge bot's `queued=` PR numbers by name, and `agents`, each implementer's
532
- // `agent=` definition by name: one token per member name for
532
+ // merge bot's `queued=` PR numbers by name, `agents`, each implementer's
533
+ // `agent=` definition by name, and `sessions`, each carried implementer's
534
+ // `session=` directory name by name: one token per member name for
533
535
  // the session, so a settle that rewrites the token keeps the name its brief,
534
- // its queue and its definition are filed under. save() joins them back.
536
+ // its queue, its definition and its session are filed under. save() joins
537
+ // them back.
535
538
  function dispatchedOf(entries) {
536
539
  const parsed = entries.map(parseDispatchedEntry);
537
540
  const byName = (field) => Object.fromEntries(parsed.filter((p) => p[field] !== null).map((p) => [parseToken(p.token).name, p[field]]));
538
- return { dispatched: parsed.map((p) => p.token), briefs: byName("brief"), queued: byName("queued"), agents: byName("agent") };
541
+ return { dispatched: parsed.map((p) => p.token), briefs: byName("brief"), queued: byName("queued"), agents: byName("agent"), sessions: byName("session") };
539
542
  }
540
543
 
541
544
  // `## Drain` is written only once there is a marker to hold: an empty section
@@ -552,7 +555,7 @@ function save(d) {
552
555
  `# Fleet run ledger\n\n${ROWS}\n\n` + list(d.rows) +
553
556
  `\n\n${DISPATCHED}\n\n` + list(d.dispatched.map((t) => {
554
557
  const name = parseToken(t)?.name;
555
- return dispatchedEntry(t, d.briefs[name] ?? null, d.queued[name] ?? null, d.agents[name] ?? null);
558
+ return dispatchedEntry(t, d.briefs[name] ?? null, d.queued[name] ?? null, d.agents[name] ?? null, d.sessions[name] ?? null);
556
559
  })) +
557
560
  (d.routed.length === 0 ? "" : `\n\n${ROUTED}\n\n` + list(d.routed)) +
558
561
  `\n\n${FILED}\n\n` + list(d.filed) +
@@ -1680,6 +1683,8 @@ function runRotate() {
1680
1683
  // Read before anything moves: a ledger whose live tokens cannot be read is
1681
1684
  // refused with nothing moved, never archived with those tokens dropped.
1682
1685
  let carry = { rows: [], dispatched: [], routed: [], retired: [], skipped: [] };
1686
+ let sessions = { stamped: {}, unstamped: {} };
1687
+ const receiptPath = join(dirname(file), RECEIPT);
1683
1688
  if (prior === "ancestor" && exists) {
1684
1689
  let text;
1685
1690
  try {
@@ -1688,6 +1693,7 @@ function runRotate() {
1688
1693
  die(`refusing to rotate ${file}: cannot read it to carry this session's live members forward: ${e.message}`);
1689
1694
  }
1690
1695
  carry = carryOf(text);
1696
+ sessions = stampSessions(carry, receiptPath);
1691
1697
  }
1692
1698
  const carrying = carry.rows.length > 0 || carry.dispatched.length > 0 || carry.retired.length > 0;
1693
1699
  // The receipts beside the ledger belong to the run being rotated away, so
@@ -1750,6 +1756,8 @@ function runRotate() {
1750
1756
  console.error(` carried ${carry.rows.length} row(s) and ${carry.dispatched.length} ## Dispatched entr${carry.dispatched.length === 1 ? "y" : "ies"} from ${archive}`);
1751
1757
  if (carry.routed.length > 0) console.error(` carried ${carry.routed.length} ${ROUTED} entr${carry.routed.length === 1 ? "y" : "ies"} from ${archive}`);
1752
1758
  console.error(` retired ${carry.retired.length} name(s) from ${archive}`);
1759
+ for (const [name, session] of Object.entries(sessions.stamped)) console.error(` stamped ${name} session=${session} from ${receiptPath}`);
1760
+ for (const [name, why] of Object.entries(sessions.unstamped)) console.error(` carried ${name} unstamped: ${why}`);
1753
1761
  }
1754
1762
  // Re-read rather than reuse the read above: the heartbeat file has other
1755
1763
  // writers, and a patch built from an older view would undo what they wrote
@@ -1764,9 +1772,44 @@ function runRotate() {
1764
1772
  carried: { rows: carry.rows, dispatched: carry.dispatched, routed: carry.routed },
1765
1773
  retired: carry.retired,
1766
1774
  skipped: carry.skipped.map((s) => s.line),
1775
+ stamped: sessions.stamped, unstamped: sessions.unstamped,
1767
1776
  }));
1768
1777
  }
1769
1778
 
1779
+ // A carried implementer's transcript sits in the session of the run being
1780
+ // rotated away, which nothing beside the next run's ledger names once that
1781
+ // run's receipt is archived. So each carried implementer entry that names no
1782
+ // session yet is stamped `session=<name>` with the session of the receipt this
1783
+ // rotate archives: phase 0 puts a held receipt back at `phase0.json` before it
1784
+ // rotates, so that is the rotated run's own. An entry that already names one
1785
+ // keeps it — the run that dispatched the member, not a run that carried it
1786
+ // since. A receipt that is absent, unreadable or names no omp session
1787
+ // directory, and an entry with no `brief=` for the word to follow, leave the
1788
+ // entry unstamped, its reason returned by member name; the rotation goes on
1789
+ // either way. Only an implementer's entry is stamped: its transcript is the
1790
+ // one a card reads. Writes the stamps into `carry.sessions`, which save()
1791
+ // writes back.
1792
+ function stampSessions(carry, receiptPath) {
1793
+ const stamped = {};
1794
+ const unstamped = {};
1795
+ const read = readReceipt(receiptPath);
1796
+ let session = null;
1797
+ let why = null;
1798
+ if (read.state === "missing") why = `no ${receiptPath} to read its session from`;
1799
+ else if (read.state === "unreadable") why = `${receiptPath} unreadable: ${read.why}`;
1800
+ else if (read.receipt.session === "") why = `${receiptPath} records no session`;
1801
+ else if (!isOmpSessionDirName(basename(read.receipt.session))) why = `${receiptPath} records ${read.receipt.session}, which is not an omp <ISO>_<uuid> session directory`;
1802
+ else session = basename(read.receipt.session);
1803
+ for (const token of carry.dispatched) {
1804
+ const { name, family } = parseToken(token);
1805
+ if (family !== "impl" || Object.hasOwn(carry.sessions, name)) continue;
1806
+ if (!Object.hasOwn(carry.briefs, name)) unstamped[name] = "its entry has no brief=, which a session= word follows";
1807
+ else if (session === null) unstamped[name] = why;
1808
+ else stamped[name] = carry.sessions[name] = session;
1809
+ }
1810
+ return { stamped, unstamped };
1811
+ }
1812
+
1770
1813
  // What an `ancestor` rotate carries out of the archived text, read line by
1771
1814
  // line so one bad line costs only itself: the whole point is to keep live
1772
1815
  // members' tokens, and a ledger load() refuses (a second drain marker, say)
@@ -1801,12 +1844,13 @@ function carryOf(text) {
1801
1844
  return false;
1802
1845
  }
1803
1846
  });
1804
- // An entry's `brief=`, `queued=` and `agent=` travel with it: save() writes
1805
- // them only beside the token it writes, so a carried member's record still
1806
- // names the brief it was dispatched with — a carried merge bot the queue it
1807
- // is judged against, a carried implementer the definition it is judged
1808
- // against — and a dropped member's does not.
1809
- const { dispatched: allDispatched, briefs: allBriefs, queued: allQueued, agents: allAgents } = dispatchedOf(ledgerSection(text, DISPATCHED));
1847
+ // An entry's `brief=`, `queued=`, `agent=` and `session=` travel with it:
1848
+ // save() writes them only beside the token it writes, so a carried member's
1849
+ // record still names the brief it was dispatched with — a carried merge bot
1850
+ // the queue it is judged against, a carried implementer the definition it
1851
+ // is judged against and the session it ran in — and a dropped member's
1852
+ // does not.
1853
+ const { dispatched: allDispatched, briefs: allBriefs, queued: allQueued, agents: allAgents, sessions: allSessions } = dispatchedOf(ledgerSection(text, DISPATCHED));
1810
1854
  const dispatched = allDispatched.filter((e) => {
1811
1855
  const t = parseToken(e);
1812
1856
  if (t !== null && t.error === null) return true;
@@ -1838,7 +1882,7 @@ function carryOf(text) {
1838
1882
  if (parsed === null) skipped.push({ line: entry, why: "not an implementer's name and a Routing line" });
1839
1883
  else if (named.has(parsed.member)) routed.push(entry);
1840
1884
  }
1841
- return { ...carried, routed, briefs: allBriefs, queued: allQueued, agents: allAgents, retired, skipped };
1885
+ return { ...carried, routed, briefs: allBriefs, queued: allQueued, agents: allAgents, sessions: allSessions, retired, skipped };
1842
1886
  }
1843
1887
 
1844
1888
  // ── dispatch / settle ────────────────────────────────────────────────────────
@@ -14,7 +14,8 @@
14
14
  import { readdirSync, readFileSync, statSync } from "node:fs";
15
15
  import { join, basename, dirname } from "node:path";
16
16
 
17
- import { readOmpSession, normalizeModel, parseMemberName, isOmpSessionDirName } from "./member-record.mjs";
17
+ import { readOmpSession, normalizeModel, parseMemberName } from "./member-record.mjs";
18
+ import { isOmpSessionDirName } from "./ledger-grammar.mjs";
18
19
  import { stripLevel } from "./tier-roles.mjs";
19
20
  import { reportFamily, reportStatus, defaultScratch } from "./report-files.mjs";
20
21
  import { FleetDirUnresolvable } from "./fleet-dir.mjs";
@@ -26,6 +26,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
26
26
  import { join, basename, relative, isAbsolute, sep } from "node:path";
27
27
 
28
28
  import { classifyRole, canonicalMemberName, CANONICAL_MEMBER_NAME_PREFIXES } from "./compute-spend.mjs";
29
+ import { isOmpSessionDirName } from "./ledger-grammar.mjs";
29
30
 
30
31
  // ---------------------------------------------------------------------------
31
32
  // cwd encoder
@@ -928,28 +929,8 @@ export function readOmpSession(sessionDir, activity = null) {
928
929
  return rows;
929
930
  }
930
931
 
931
- // An omp session directory is identified STRICTLY by name — `<ISO>_<uuid>`,
932
- // e.g. `2026-09-08T13-13-27-300Z_01a08126-…` — never by holding `.jsonl`
933
- // files directly. That second test used to be a shortcut, and it fired one
934
- // level too high on the real tree: `~/.omp/agent/sessions/-dev-fleet-plugin/`
935
- // holds the project's MAIN-session transcripts as plain files SIBLING to the
936
- // per-session directories, so `findOmpSessionDirs` recursing from the
937
- // encoded-cwd dir hit the `.jsonl` test there first, returned the whole
938
- // project as "one session", stamped every row `session=-dev-fleet-plugin`
939
- // instead of the `<ISO>_<uuid>` name the row key is built on, and booked
940
- // the controller's own top-level transcripts as members. Name-only matching
941
- // costs nothing a real fixture needs: every fixture in this repo already
942
- // names its session dir in the real shape.
943
- const OMP_SESSION_DIR_RE = /^\d{4}-\d{2}-\d{2}T[\d-]+Z_[0-9a-f-]+$/i;
944
-
945
- // Exposed for callers that already hold one EXPLICIT directory rather than a
946
- // tree to search — member-outcomes.mjs's CLI, so the pattern is defined once.
947
- export function isOmpSessionDirName(name) {
948
- return OMP_SESSION_DIR_RE.test(name);
949
- }
950
-
951
932
  function findOmpSessionDirs(root) {
952
- if (OMP_SESSION_DIR_RE.test(basename(root))) return [root];
933
+ if (isOmpSessionDirName(basename(root))) return [root];
953
934
  let ents;
954
935
  try { ents = readdirSync(root, { withFileTypes: true }); }
955
936
  catch { return []; }
@@ -84,6 +84,8 @@ A member that dies between spawn and write is invisible — and members die in b
84
84
 
85
85
  `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.
86
86
 
87
+ `rotate` records where a carried implementer ran: when it carries an implementer's entry that has no `session=` yet, it adds `session=<name>` after `agent=`, `<name>` the omp `<ISO>_<uuid>` session directory the receipt it archives names — the directory's name alone, never a path. An entry carried a second time keeps the session it already names, the run that dispatched it. A receipt that is absent, unreadable or names no omp session directory, or an entry with no `brief=`, leaves the entry unstamped; the rotation still goes on, and its stderr and its JSON's `unstamped` say why, as `stamped` names each entry it stamped. Only implementer entries take the word. `ledger.mjs read` prints it under `sessions`, by member name, and `settle` and `rotate` keep it with its entry. The cockpit reads a stamped implementer's transcript from that session, under the directory the current or held receipt's session sits in, so its card keeps its model and level once the next run's receipt names a session of its own. A value that is not an omp session directory name makes the entry malformed, and the ledger is refused.
88
+
87
89
  ## filed and ruled
88
90
 
89
91
  `filed` is checked with `ledger.mjs check <subject>` before every `gh issue create`, so a finding already recorded this run is not filed twice. That is not a guarantee against duplicates at large; the tracker query, described under `check`'s exits and its `verdict` above, is what covers those.