session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/vault-mirror/process.mjs

@@ -6,9 +6,9 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
+import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { execFileSync } from 'node:child_process';
+import { createSecretValueMasker } from '../secret-masker.mjs';
 import { subjectToSlug, isValidSlug, uuidPrefix8, toDate, parseFrontmatter } from './utils.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
@@ -99,6 +99,80 @@ function extractLearningCanonicalFields(noteContent) {
   return { status, expires, confidence, insight, source_session };
 }
 
+/**
+ * The marker every redaction sink in this repo splices in (`redact-spans.mjs`).
+ * Declared here as a literal rather than imported: `redactSpans` does not export
+ * it, and this module needs it as a SEARCH token, not as a replacement.
+ */
+const REDACTION_MARKER = '[REDACTED]';
+
+/**
+ * Does the on-disk `existingVal` match `renderedVal` once every `[REDACTED]`
+ * span in it is treated as a wildcard? (#1025)
+ *
+ * WHY THIS EXISTS. Masking is env-derived and the env is not part of the record,
+ * so the two sides of the idempotency comparison can be masked DIFFERENTLY: a
+ * note written while `FOO_TOKEN` was set carries `[REDACTED]`, and a later run
+ * with that var absent renders the RAW value. Plain equality then reports
+ * "content changed" and the mirror WRITES THE RAW SECRET — the repeated leak
+ * measured in #1025 Probe A. Treating an on-disk redaction as "some value stood
+ * here" makes that second run a `skipped-noop` again.
+ *
+ * DIRECTION IS DELIBERATE — the wildcard is only ever read off the ON-DISK side.
+ * An on-disk `[REDACTED]` is evidence that a mask ran; an on-disk raw value is
+ * evidence of nothing, so the reverse (candidate redacted, disk raw) stays a
+ * mismatch. See the COLD-START FREEZE note in `maskEntrySecrets` for the residual
+ * that this asymmetry leaves open on purpose.
+ *
+ * NAMED CEILING: the wildcard is exactly as wide as the marker spans — every
+ * literal segment AROUND them must still match byte for byte. A genuine content
+ * edit that happens to sit entirely inside a redacted span is therefore read as a
+ * no-op. That is a bounded over-approximation on a field whose masked half is by
+ * definition unpublishable; the alternative (persisting the needle set to disk)
+ * would put a secrets file on disk to protect against secrets, which is worse.
+ *
+ * THE MARKER IS NOT AUTHENTICATED — and it cannot be. `[REDACTED]` is an ordinary
+ * string that this repo's own prose uses freely (ADRs, rule files, learnings), so
+ * its presence is evidence a mask MAY have run, never proof one did. Two cheap
+ * narrowings bound what that costs:
+ *   - A value consisting of NOTHING BUT markers (`[REDACTED]`, or two in a row)
+ *     leaves zero literal anchors, compiling to a pattern that matches every
+ *     string — a field permanently blind to every future edit. Rejected outright:
+ *     with no anchor there is no evidence of what stood there, so the safe read is
+ *     "not a redaction of this candidate".
+ *   - A marker span stands for at least ONE character (`+?`, not `*?`). A masked
+ *     needle is >= `MIN_MASKABLE_LENGTH` (8) characters by construction, so this
+ *     never rejects a real redaction and does reject the empty-span reading.
+ *
+ * REJECTED ALTERNATIVE — gating the wildcard on `needleCount > 0`. It reads as the
+ * obvious authentication ("no needles this run, so an on-disk marker cannot be
+ * ours") and it destroys the fix, because the leaking run is EXACTLY the run with
+ * zero needles: #1025 Probe A reproduced `written` + raw value on the second run
+ * precisely because the env no longer carried the secret. Gating there would
+ * disable the wildcard in the only case it exists for. The needle count of the
+ * CURRENT run says nothing about the env of the run that wrote the file.
+ *
+ * SHARED BY TWO VAULT SINKS — do not inline a second copy. `writeNarrative` in
+ * `scripts/lib/vault-status/narrative-mirror.mjs` imports this for its own
+ * skip-noop decision; both write into the same tracked, pushed vault repo, so the
+ * contract in `secret-masker.mjs`'s header must hold identically in both. (That
+ * module is the natural long-term home for this predicate — see the note there.)
+ *
+ * @param {string} existingVal — field value parsed out of the note on disk
+ * @param {string} renderedVal — same field from the freshly rendered candidate
+ * @returns {boolean}
+ */
+export function matchesModuloRedaction(existingVal, renderedVal) {
+  if (typeof existingVal !== 'string' || typeof renderedVal !== 'string') return false;
+  if (!existingVal.includes(REDACTION_MARKER)) return false;
+  const segments = existingVal.split(REDACTION_MARKER);
+  // Degenerate-wildcard guard: no literal anchor survives, so the pattern would
+  // match anything and freeze the field forever. See the header above.
+  if (segments.every((segment) => segment === '')) return false;
+  const pattern = segments.map((segment) => RegExp.escape(segment)).join('[\\s\\S]+?');
+  return new RegExp(`^${pattern}$`).test(renderedVal);
+}
+
 /**
  * Return true when the existing vault note content and the freshly-rendered
  * candidate share identical canonical fields (i.e. no meaningful update needed).
@@ -123,8 +197,12 @@ function learningContentMatches(existingContent, renderedContent) {
   // For each field: if the existing value is absent (empty string), it cannot
   // signal a mismatch — it means the old note didn't track that field. Only
   // non-empty existing values are compared against the rendered candidate.
+  // #1025: a field whose only difference from the candidate is a `[REDACTED]`
+  // span counts as a match — see matchesModuloRedaction above.
   const fieldMatches = (existingVal, renderedVal) =>
-    existingVal === '' || existingVal === renderedVal;
+    existingVal === '' ||
+    existingVal === renderedVal ||
+    matchesModuloRedaction(existingVal, renderedVal);
   return (
     fieldMatches(existing.status, rendered.status) &&
     fieldMatches(existing.expires, rendered.expires) &&
@@ -136,35 +214,20 @@ function learningContentMatches(existingContent, renderedContent) {
 
 // ── repo derivation ───────────────────────────────────────────────────────────
 
-let _cachedRepo = null;
-
 /**
- * Derive the canonical repo identifier for cross-repo vault aggregation (issue #343).
+ * `deriveRepo` LIVES IN `./namespace.mjs` and is re-exported here (issue #734b).
  *
- * Strategy: parse `git remote get-url origin` and extract the org/name pair
- * (e.g. `git@github.com:Kanevry/session-orchestrator.git` → `Kanevry/session-orchestrator`).
- * Falls back to `path.basename(process.cwd())` when not in a git repo or origin
- * is unavailable. Cached per-process — repo identity does not change mid-run.
+ * Until #734b this module defined it while `namespace.mjs` imported it — and
+ * `namespace.mjs` was in turn imported here for `resolveRepoNamespace`, forming
+ * the repo's only import cycle. Moving the definition down to the leaf-ward
+ * identity module broke the cycle; this re-export keeps `process.mjs`'s public
+ * surface unchanged for the existing consumers that import it from here.
+ *
+ * Do NOT re-add a second definition: `deriveRepo` caches its result in a
+ * module-level variable, so a duplicate would produce two independent caches
+ * (and two `git remote get-url origin` spawns).
  */
-export function deriveRepo() {
-  if (_cachedRepo !== null) return _cachedRepo;
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    // Match git@host:org/name(.git)? OR https://host/org/name(.git)?
-    const sshMatch = url.match(/[:/]([^:/]+\/[^/]+?)(?:\.git)?$/);
-    if (sshMatch && sshMatch[1]) {
-      _cachedRepo = sshMatch[1];
-      return _cachedRepo;
-    }
-  } catch {
-    // git unavailable or no origin configured — fall through
-  }
-  _cachedRepo = basename(process.cwd());
-  return _cachedRepo;
-}
+export { deriveRepo } from './namespace.mjs';
 
 // ── Action output ─────────────────────────────────────────────────────────────
 
@@ -211,6 +274,173 @@ export function emitAction({ action, path, kind, id, vaultDir, meta }) {
   process.stdout.write(JSON.stringify(payload) + '\n');
 }
 
+// ── Secret masking (#974) — THE choke-point ───────────────────────────────────
+
+/**
+ * Lazily-built, process-wide masker. `createSecretValueMasker` scans the whole
+ * env and compiles one RegExp per needle, so it is built ONCE (on the first
+ * record) and reused for every record afterwards — never per entry.
+ *
+ * Lazy rather than module-load-eager so that importing this module for
+ * `deriveRepo`/`emitAction` alone costs nothing, and so the env is read at the
+ * moment the mirror actually runs.
+ *
+ * @type {{ mask: (text: string) => string, needleCount: number } | null}
+ */
+let _secretMasker = null;
+
+/** Records handed to `maskEntrySecrets` this process. Counts only. */
+let _maskedRecords = 0;
+/** String values this process that masking actually CHANGED. Counts only. */
+let _maskHits = 0;
+
+/**
+ * Build (once) and return the process-wide masker.
+ * @returns {{ mask: (text: string) => string, needleCount: number }}
+ */
+function ensureMasker() {
+  if (_secretMasker === null) _secretMasker = createSecretValueMasker(process.env);
+  return _secretMasker;
+}
+
+/**
+ * Counts-only view of the masking that happened in this process (#1025).
+ *
+ * Exists so the CLI can emit `orchestrator.secret_masker.applied` at the END of a
+ * channel run without reaching into a module-private singleton. It FORCE-BUILDS
+ * the masker rather than reporting 0 for an unbuilt one: at 0 processed records
+ * the lazy build never fires, and a `needle_count: 0` from that path would be
+ * indistinguishable from "this channel has no masking wired at all" — the exact
+ * ambiguity the event was added to remove.
+ *
+ * NEVER returns a needle, a prefix of one, or any masked text — only cardinals.
+ *
+ * @returns {{ needleCount: number, records: number, hits: number }}
+ */
+export function getMaskerStats() {
+  return { needleCount: ensureMasker().needleCount, records: _maskedRecords, hits: _maskHits };
+}
+
+/**
+ * Mask every env-derived secret VALUE occurring anywhere in a mirror record,
+ * BEFORE any of it becomes a filename, a stdout line, or vault Markdown.
+ *
+ * WHY THIS IS THE CHOKE-POINT — and why it is on the INPUT, not the output.
+ * Everything this mirror writes lands in a TRACKED, PUSHED artifact
+ * (`auto-commit.mjs` runs `git add` + `commit` in the vault repo), so a leak here
+ * is not deletable — it would need a history rewrite in a foreign repo that
+ * neither this repo's `.gitleaks.toml` nor `check-owner-leakage.mjs` guards.
+ *
+ * THIS IS NOT THE ONLY SUCH CHANNEL — an earlier revision of this comment claimed
+ * it was, and that was wrong. Measured 2026-08-15 against the vault at
+ * `83a868059` (`git -C <vault> ls-files`): 18 tracked `_session-narrative.md`
+ * files (written by `scripts/lib/vault-status/narrative-mirror.mjs`) and 1 tracked
+ * `01-projects/session-orchestrator/research/hardware-patterns.md` (written by
+ * `scripts/export-hw-learnings.mjs`) live in the same pushed repo. All three
+ * channels carry agent-authored free text and all three need hardening
+ * independently — the value masker was wired into `export-hw-learnings.mjs` in
+ * #1025 for exactly this reason. Read "the vault is a tracked sink" as the
+ * property that makes masking necessary HERE, never as a census of the sinks.
+ *
+ * The records carry agent-authored free text (`insight`, `evidence`, `notes`,
+ * `text`) that routinely quotes command lines and error output, which is exactly
+ * the class shape-regexes cannot catch: the VALUE is in the prose, with no
+ * `FOO_TOKEN=` key beside it.
+ *
+ * Masking the ENTRY rather than the rendered Markdown is deliberate, for four
+ * reasons — a post-render mask would be wrong on all four:
+ *   1. The FILENAME. `slug` / `session_id` derive from `subject` / `session_id`,
+ *      and the file path is itself committed. A post-render mask never touches
+ *      the path, so a secret in a subject would be published as a filename.
+ *   2. STDOUT. `emitAction` prints the derived `id` and `path`; masking the input
+ *      keeps the action stream clean too.
+ *   3. YAML VALIDITY. The renderers decide quoting with `yamlQuoteIfNeeded`
+ *      BEFORE emitting `title:`. Masking first lets that decision see the `[`
+ *      of the marker and quote the scalar; masking afterwards would inject a bare
+ *      `title: [REDACTED]` — a YAML flow sequence, which fails the vault-sync
+ *      frontmatter schema at the session-end hard gate.
+ *   4. IDEMPOTENCY. `learningContentMatches` compares the on-disk note against a
+ *      freshly rendered candidate. Masking the input keeps both sides masked, so
+ *      an already-mirrored record still resolves to `skipped-noop`; masking only
+ *      on write would make every affected note re-render (and re-commit) forever.
+ *
+ *      That symmetry holds only while the ENV is stable, and the env is not part
+ *      of the record — so idempotency here is env-DEPENDENT. Reproduced (#1025):
+ *      a run WITH the secret in env writes `[REDACTED]`; a second run WITHOUT it
+ *      renders the raw value, the two differ, and the note is `updated` — i.e.
+ *      the leak is written a second time, by the very run that was supposed to be
+ *      a no-op. `learningContentMatches` now treats an on-disk `[REDACTED]` span
+ *      as a wildcard (see that function) so this direction resolves to
+ *      `skipped-noop` again.
+ *
+ *      KNOWN RESIDUAL — and NOT the one an earlier revision of this note named.
+ *      That revision claimed a COLD-START FREEZE over the CANONICAL fields: first
+ *      run without the env writes the raw value, later runs render `[REDACTED]`,
+ *      and the note freezes. Measured, that direction HEALS: with no marker on the
+ *      on-disk side `matchesModuloRedaction` returns false at its first line, the
+ *      canonical fields differ, and the run writes the masked content. The
+ *      asymmetry is still deliberate (an on-disk redaction is evidence a mask ran;
+ *      an on-disk raw value is evidence of nothing) — it simply does not freeze
+ *      anything the field comparison can see.
+ *
+ *      What DOES freeze is the half the field comparison cannot see.
+ *      `learningContentMatches` compares exactly five canonical fields — `status`,
+ *      `expires`, `confidence`, `insight`, `source_session`. A raw secret sitting
+ *      in any OTHER field (`evidence` is the realistic one; it is agent-authored
+ *      free text and it is rendered into the note) leaves all five identical
+ *      between the raw on-disk note and the masked candidate. The comparison
+ *      reports a match, the run emits `skipped-noop`, and the plaintext stays in
+ *      the tracked, pushed file permanently — no later run rewrites it, because no
+ *      later run ever sees a difference.
+ *
+ *      THE ESCAPE HATCH EXISTS AND IS UNDOCUMENTED ELSEWHERE, which is the real
+ *      defect: `processLearning(entry, n, { ...ctx, force: true })` skips the
+ *      date/content comparison entirely and re-renders from the (masked) entry, so
+ *      a single forced re-mirror with the env populated heals every such note. It
+ *      covers the same-id and legacy-flat paths; the disambiguated-collision
+ *      branch below does not read `force` and is not healed by it.
+ *      Revisit-Trigger: widen the canonical field set (or diff the whole rendered
+ *      body) the first time a mirror run is observed leaving a raw needle in a
+ *      non-canonical field — a test written TODAY would only pin the leak as
+ *      expected behaviour.
+ *
+ * FRONTMATTER AND BODY ARE TREATED IDENTICALLY. A credential is exactly as
+ * published in `title:` as it is under `## Insight` — both live in the same
+ * committed file — so there is no case for exempting the structured half. The
+ * schema risk that exemption would otherwise be arguing for is removed by
+ * reason 3 above rather than by leaving a field unmasked.
+ *
+ * Fail-soft by construction: with zero needles the entry is returned by
+ * reference (byte-identical downstream), and `mask` itself passes non-strings
+ * through — the masker must never be the reason a mirror run dies.
+ *
+ * @template T
+ * @param {T} entry — a normalized learning/session record (plain JSON shape)
+ * @returns {T} the same record with every string value masked
+ */
+function maskEntrySecrets(entry) {
+  const { mask, needleCount } = ensureMasker();
+  // Counted BEFORE the fast path: "records the choke-point saw" must not depend
+  // on whether the env happened to carry a needle.
+  _maskedRecords++;
+  if (needleCount === 0) return entry;
+  const walk = (value) => {
+    if (typeof value === 'string') {
+      const masked = mask(value);
+      if (masked !== value) _maskHits++;
+      return masked;
+    }
+    if (Array.isArray(value)) return value.map(walk);
+    if (value && typeof value === 'object') {
+      const out = {};
+      for (const [k, v] of Object.entries(value)) out[k] = walk(v);
+      return out;
+    }
+    return value;
+  };
+  return walk(entry);
+}
+
 // ── Core processing ───────────────────────────────────────────────────────────
 
 export async function processLearning(rawEntry, _lineNum, ctx) {
@@ -225,7 +455,9 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // #635: map producer alias fields (summary/detail, description/rationale,
   // title/body, name, narrative, content) onto the canonical v1 shape BEFORE
   // schema detection and slug/id derivation. Canonical entries pass through.
-  const entry = normalizeLearningEntry(rawEntry);
+  // #974: the ONE masking site for learnings — before slug/filename derivation,
+  // before the render, before any write. See maskEntrySecrets above.
+  const entry = maskEntrySecrets(normalizeLearningEntry(rawEntry));
   const schema = detectLearningSchema(entry);
   const entryId = entry.id;
 
@@ -438,7 +670,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // #635: map producer alias fields (ended_at, mode, total_waves/waves_completed
   // without a `waves` field) onto the canonical shapes BEFORE schema detection.
   // Canonical v1/v2/v3 entries pass through untouched.
-  const entry = normalizeSessionEntry(rawEntry);
+  // #974: the ONE masking site for sessions — same contract as processLearning.
+  const entry = maskEntrySecrets(normalizeSessionEntry(rawEntry));
   const { session_id: rawSessionId } = entry;
   const schema = detectSessionSchema(entry);
   const generator =

package/scripts/lib/vault-mirror/render-sessions.mjs

@@ -69,6 +69,50 @@ function renderDuration(durationSeconds, durationMinutes) {
   return minutes === undefined || minutes === null ? MISSING_VALUE : `${minutes}m`;
 }
 
+/**
+ * Coerce ONE wave-object count field to a renderable number (#1074).
+ *
+ * ── WHY A TYPE GUARD AND NOT A BARE `??` CHAIN ─────────────────────────────
+ *
+ * The wave-object count fields are POLYMORPHIC across producer generations.
+ * Census over the live ledger (253 records / 599 wave objects, 2026-08-19):
+ *
+ *   agent_count        number 359
+ *   agents             number 210, **ARRAY 14**   ← array-of-agent-descriptors
+ *   agents_dispatched  number  20
+ *   dispatched         number   5
+ *   files_changed      number 366, **ARRAY  1**   ← array-of-file-paths
+ *   files              number   5
+ *
+ * A naive `w.agent_count ?? w.agents` therefore interpolates an array of
+ * objects into a Markdown table cell — `[object Object],[object Object],…` for
+ * the 4 waves of `main-2026-04-27-2231`. That is STRICTLY WORSE than the `?` it
+ * replaces: `?` reads as "unknown", `[object Object]` reads as content. The
+ * array-of-paths half of the same defect is already in production —
+ * `main-2026-05-26-housekeeping-1` renders its whole file list into the Files
+ * cell today, via the plain `w.files_changed` read that predates this helper.
+ *
+ * An array IS a measurement (its length is the count), so it is converted, not
+ * dropped. Any OTHER shape returns `undefined` so the caller's `??` chain keeps
+ * walking to the next alias and ultimately to `MISSING_CELL` — an unrecognised
+ * shape must degrade to "unknown", never to a coerced string. `NaN` is out of
+ * reach here by construction: JSON cannot encode it, and every caller feeds
+ * this JSONL-parsed values.
+ *
+ * ABSENT IS NOT ZERO applies unchanged (see the banner above `MISSING_CELL`):
+ * this returns `0` for a measured `0` and `0` for an empty array, and only
+ * `undefined` for a field the producer never wrote. Callers MUST chain with
+ * `??`, never `||` — `agents_dispatched: 0` occurs 20× in the live ledger.
+ *
+ * @param {unknown} value — one raw wave-object field.
+ * @returns {number|undefined} the count, or `undefined` to continue the chain.
+ */
+function waveCount(value) {
+  if (typeof value === 'number') return value;
+  if (Array.isArray(value)) return value.length;
+  return undefined;
+}
+
 /**
  * ── RENDERABLE ⊋ SCHEMA-VALID (#964) ───────────────────────────────────────
  *
@@ -259,6 +303,29 @@ function fmLine(key, value) {
  * reachability is therefore zero; see the follow-up note in the #964 report
  * before treating it as dead code — deletion is a separate decision, and the
  * `normalizeSessionEntry` alias path can still synthesize a scalar `waves`.
+ *
+ * #1074 — THE v2 BRANCH WAS DEAD AT BIRTH, AND THE NUMBER IS PINNED. Re-measured
+ * 2026-08-19 over 253 records: **v1 253, v2 0, v3 0**, both raw and
+ * post-`normalizeSessionEntry`. This is not a coincidence of the current data —
+ * the v2 clause is UNSATISFIABLE by construction: it requires
+ * `total_agents === undefined`, while `total_agents` is in `REQUIRED_FIELDS`
+ * (scripts/lib/session-schema/constants.mjs) and enforced by
+ * `validateSession`, so every record the writer accepts carries it (measured:
+ * 253/253 define it). Commit 9cb6d9c added the branch 4h23m BEFORE the first
+ * record using the `agents` alias was written, and no historical tracked ledger
+ * state would have routed one either.
+ *
+ * The consequence is the reason `generateSessionNote`'s wave table no longer
+ * consults this function for its alias handling at all: version detection is
+ * the WRONG AXIS for per-wave producer-key drift, because the alias varies per
+ * wave object and no session-level field — `schema_version` included — predicts
+ * it. See the census in the `waveRows` comment there. This function still
+ * routes the three GENERATORS and is unchanged; do not "repair" the wave table
+ * by re-anchoring it here.
+ *
+ * The generators are intentionally NOT deleted (operator decision, deferred
+ * once already in #964). Pinning the number here is the point: the next reader
+ * inherits the measurement instead of re-running it.
  */
 export function detectSessionSchema(entry) {
   if (!entry) return 'v1';
@@ -368,11 +435,55 @@ export function generateSessionNote(entry, options = {}) {
   // validated, so all three are optional and were rendering as the literal
   // string `undefined`. Guarded with the same `?? '?'` the v2 generator's wave
   // rows already used — `??` so a measured `0` still renders `0`.
+  //
+  // ── #1074: PER-WAVE ALIASES, NOT PER-SESSION VERSION DETECTION ────────────
+  //
+  // #M1 stopped the cells reading `undefined`, but left them reading `?` for
+  // every record whose producer used a different key — and that is most of the
+  // ledger. Census over 253 records / 599 wave objects (2026-08-19):
+  //
+  //   Agents  `?` 240 cells in 55 records  (recoverable: agents 214, agents_dispatched 20, dispatched 5)
+  //   Files   `?` 232 cells in 52 records  (recoverable: files 5)
+  //   Quality `?` 386 cells in 88 records  (recoverable: quality_check 168, status 72, result 35, outcome 5)
+  //
+  // The version-detection route cannot fix this. `detectSessionSchema` keys on
+  // SESSION-level fields, but the alias in use varies PER WAVE OBJECT and no
+  // session-level field predicts it — not even `schema_version` (under
+  // `schema_version: 1` the ledger carries agent_count 75, agents 33, none 30,
+  // agents_dispatched 4, both 2, dispatched 1). The axis is empirically
+  // refuted, so the repair is a per-wave alias chain instead.
+  //
+  // v1-canonical names come FIRST in every chain, so a cell that rendered a
+  // value before renders the identical value now: this can only ever replace a
+  // `?`. Verified over all 599 wave objects — repaired 239 agents / 5 files /
+  // 280 quality, with ZERO existing agents or quality values changed. The one
+  // deliberate change is the Files cell of `main-2026-05-26-housekeeping-1`,
+  // which stops printing a raw file-path list and prints `3` (see `waveCount`).
+  //
+  // The Quality chain needs no `waveCount`: all five of its aliases are 100%
+  // strings across the ledger (quality 213, quality_check 168, status 72,
+  // result 35, outcome 5 — zero objects or arrays), so there is no
+  // `[object Object]` hazard to guard. Should a producer ever emit a structured
+  // quality verdict, the fixture-coverage test in render-sessions.test.mjs is
+  // what surfaces it — this comment is the ceiling, that test is the trigger.
+  //
+  // A wave with no count under ANY alias keeps rendering `?`, and must: the
+  // coord-direct wave of `main-2026-05-26-housekeeping-1` dispatched no agents
+  // and recorded no number, so its Agents cell is genuinely unknown. A chain
+  // that "repaired" that one too would be inventing a measurement.
   const waveRows = waves
-    .map(
-      (w) =>
-        `| ${w.wave} | ${w.role} | ${w.agent_count ?? MISSING_CELL} | ${w.files_changed ?? MISSING_CELL} | ${w.quality ?? MISSING_CELL} |`,
-    )
+    .map((w) => {
+      const agentsCell =
+        waveCount(w.agent_count) ??
+        waveCount(w.agents) ??
+        waveCount(w.agents_dispatched) ??
+        waveCount(w.dispatched) ??
+        MISSING_CELL;
+      const filesCell = waveCount(w.files_changed) ?? waveCount(w.files) ?? MISSING_CELL;
+      const qualityCell =
+        w.quality ?? w.quality_check ?? w.status ?? w.result ?? w.outcome ?? MISSING_CELL;
+      return `| ${w.wave} | ${w.role} | ${agentsCell} | ${filesCell} | ${qualityCell} |`;
+    })
     .join('\n');
 
   // Skip-emit guard: avoid `platform: undefined` literal coercion (issue #343).