session-orchestrator 5.12.0 → 5.13.0

package/scripts/lib/agent-status.mjs

@@ -339,7 +339,8 @@ async function pushRecord(record, opts) {
   if (!acquired.ok) return acquired;
 
   try {
-    const map = readCurrentMap(currentFile);
+    // Retention trim (#1633) — the reader drops the same entries, see LIFECYCLE_RETENTION_MS.
+    const map = withoutExpired(readCurrentMap(currentFile), typeof opts?.now === 'number' ? opts.now : Date.now());
     map[record.agentId] = record;
     const written = writeJsonAtomicSync(currentFile, map, { tmpPrefix: '.agent-status-current' });
     if (!written.ok) return { ok: false, reason: 'fs-error', error: written.error };
@@ -415,6 +416,113 @@ export async function setProgress(agentId, progress = {}, opts = {}) {
   return pushRecord(record, opts);
 }
 
+// Lifecycle entries (#1580) carry a fresh harness agent_id per subagent, so —
+// unlike the wave-executor's reused ids — the cache grew by one ~200-byte entry
+// per subagent, and the lock wait of a write grew with it (#1633: 18 parallel
+// writers, 10,000 entries → p50 468 ms / max 910 ms against a 1 s timeout).
+// Pruning the cache ALONE is wrong: readCurrentStatus() folds cache ∪ ledger
+// tail, and an id present only in the ledger tail flips the whole read to
+// `rebuilt-log` (cache-behind-ledger). So the retention bound below is applied
+// on BOTH sides with one predicate: every write drops expired lifecycle entries
+// from the cache, and every read drops them from the cache view AND the ledger
+// view before the fold. Expiry is monotone in time (expired at write time ⇒
+// expired at any later read), so a trimmed cache reads exactly like the
+// untrimmed one. The ledger itself is never rewritten.
+// CEILING: 14 days of subagents stay in the cache (#1633 measured 725 starts in
+// 31 days here ≈ 330 entries per 14 days); a repo with no subagent for 14 days
+// reads as "no lifecycle record" (HUD "?") until the next start.
+// REVISIT-TRIGGER: a session that legitimately lives longer than 14 days, or a
+// repo starting more than ~5,000 subagents per 14 days (the cache is back in the
+// measured slow range) — then shorten the window or trim per session.
+const LIFECYCLE_STATES = new Set(['running', 'done']);
+export const LIFECYCLE_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+
+// A `running` lifecycle entry without a SubagentStop (#1633: 2 of 725 agents
+// since 2026-09-15, 0.28 %) would otherwise count as running forever. Bound
+// measured 2026-10-16 on this repo's `.orchestrator/metrics/subagents.jsonl`
+// (start→stop wall clock per agent_id): since 2026-09-15 n=810, p50 5.7 min,
+// p99 47 min, max 715.5 min; all time n=3017, p99 55.1 min, max 1042.9 min
+// (17.4 h — a batch of agents stopped together at a session resume; the hook's
+// own duration_ms max is 132 min). 24 h sits above every observed pair.
+// CEILING: a subagent genuinely running longer than 24 h is reported as decayed,
+// not running. REVISIT-TRIGGER: any start→stop pair above ~20 h in subagents.jsonl.
+export const LIFECYCLE_DECAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Whether a record is a lifecycle entry older than the retention window
+ * (`LIFECYCLE_RETENTION_MS`). Records without a parsable `ts` never expire.
+ * @param {object} rec
+ * @param {number} now  Epoch millis.
+ * @returns {boolean}
+ */
+function isLifecycleExpired(rec, now) {
+  const ms = rec?.kind === 'lifecycle' ? recordTsMs(rec) : null;
+  return ms !== null && now - ms > LIFECYCLE_RETENTION_MS;
+}
+
+/**
+ * Whether a lifecycle entry still says `running` but is older than
+ * `LIFECYCLE_DECAY_MS` — its SubagentStop most likely never arrived (#1633).
+ * Such an agent is neither running nor done: report it as decayed.
+ * @param {object} rec
+ * @param {number} now  Epoch millis.
+ * @returns {boolean}
+ */
+export function isLifecycleDecayed(rec, now) {
+  if (rec?.kind !== 'lifecycle' || rec.status !== 'running') return false;
+  const ms = recordTsMs(rec);
+  return ms !== null && now - ms > LIFECYCLE_DECAY_MS;
+}
+
+/**
+ * Copy of a map without its expired lifecycle entries (null-prototype).
+ * @param {Record<string, object>} entries
+ * @param {number} now
+ * @returns {Record<string, object>}
+ */
+function withoutExpired(entries, now) {
+  const out = Object.create(null);
+  for (const [id, rec] of Object.entries(entries)) {
+    if (!isLifecycleExpired(rec, now)) out[id] = rec;
+  }
+  return out;
+}
+
+/**
+ * Record a subagent lifecycle transition from the SubagentStart/SubagentStop
+ * hooks (#1580): `running` on start, `done` on stop, bound to the parent
+ * session so the HUD counts only its own session's agents. No-throw,
+ * best-effort — same result contract as `setStatus`.
+ *
+ * @param {string} agentId  Harness agent id (LWW map key).
+ * @param {{ status: 'running'|'done', sessionId: string, agentType?: string|null }} lifecycle
+ * @param {{ repoRoot?: string, timeoutMs?: number, now?: number }} [opts]
+ * @returns {Promise<{ ok: true } | { ok: false, reason: 'invalid-input'|'timeout'|'fs-error', error?: string }>}
+ */
+export async function setLifecycle(agentId, lifecycle = {}, opts = {}) {
+  if (typeof agentId !== 'string' || agentId.trim().length === 0 || UNSAFE_MAP_KEYS.has(agentId)) {
+    return { ok: false, reason: 'invalid-input', error: 'agentId must be a non-empty, safe string' };
+  }
+  const { status, sessionId, agentType } = lifecycle ?? {};
+  if (!LIFECYCLE_STATES.has(status)) {
+    return { ok: false, reason: 'invalid-input', error: 'status must be running or done' };
+  }
+  if (typeof sessionId !== 'string' || sessionId.trim().length === 0) {
+    return { ok: false, reason: 'invalid-input', error: 'sessionId must be a non-empty string' };
+  }
+  const now = typeof opts?.now === 'number' ? opts.now : Date.now();
+  const record = {
+    agentId,
+    kind: 'lifecycle',
+    status,
+    session_id: sessionId,
+    ts: new Date(now).toISOString(),
+  };
+  if (typeof agentType === 'string' && agentType.trim().length > 0) record.agent_type = truncate(agentType);
+
+  return pushRecord(record, opts);
+}
+
 /**
  * Rebuild the current-status map from a bounded TAIL of the append-only ledger
  * (#1342). The ledger is the source of truth; this is how a consumer reads it
@@ -599,14 +707,24 @@ export function rebuildCurrentFromLedger(opts = {}) {
  * per-agentId, a `rebuilt-log` view can hold BOTH kinds. A consumer must treat
  * `binding` as optional — its ABSENCE means "from the cache", never "bound".
  *
- * @param {{ repoRoot?: string, maxBytes?: number }} [opts]
+ * Retention (#1633): lifecycle entries older than `LIFECYCLE_RETENTION_MS`
+ * (relative to `opts.now`, default `Date.now()`) are absent from the view.
+ *
+ * @param {{ repoRoot?: string, maxBytes?: number, now?: number }} [opts]
  * @returns {{ entries: Record<string, object>, source: 'live-map'|'rebuilt-log'|'stale-cache'|'absent', at: string|null, degraded?: object }}
  */
 export function readCurrentStatus(opts = {}) {
-  const cache = readCurrentMapDetailed(currentPathFor(opts?.repoRoot));
+  const now = typeof opts?.now === 'number' ? opts.now : Date.now();
+  const cacheRead = readCurrentMapDetailed(currentPathFor(opts?.repoRoot));
   const rebuilt = rebuildCurrentFromLedger(opts);
+  // Both views lose their expired lifecycle entries BEFORE the fold (#1633), so a
+  // cache trimmed at write time reads exactly like the untrimmed one.
+  const cache = { ...cacheRead, entries: withoutExpired(cacheRead.entries, now) };
+  const ledgerEntries = withoutExpired(rebuilt.entries, now);
 
   const cacheNewest = newestTsMs(cache.entries);
+  // Provenance checks read the UNTRIMMED ledger: trimming can only lower the
+  // cache's newest stamp, so comparing against the full ledger stays exact.
   const ledgerNewest = rebuilt.at === null ? null : Date.parse(rebuilt.at);
   const ledgerUnusable =
     rebuilt.degraded !== null &&
@@ -626,7 +744,7 @@ export function readCurrentStatus(opts = {}) {
   let at;
 
   const cacheIds = Object.keys(cache.entries);
-  const ledgerIds = Object.keys(rebuilt.entries);
+  const ledgerIds = Object.keys(ledgerEntries);
 
   if (ledgerUnusable && cacheIds.length === 0) {
     // Nothing on disk at all — no ledger to verify against AND no cached entry
@@ -648,8 +766,8 @@ export function readCurrentStatus(opts = {}) {
       const cached = Object.prototype.hasOwnProperty.call(cache.entries, id)
         ? cache.entries[id]
         : undefined;
-      const logged = Object.prototype.hasOwnProperty.call(rebuilt.entries, id)
-        ? rebuilt.entries[id]
+      const logged = Object.prototype.hasOwnProperty.call(ledgerEntries, id)
+        ? ledgerEntries[id]
         : undefined;
 
       if (cached === undefined) {
@@ -682,7 +800,7 @@ export function readCurrentStatus(opts = {}) {
     }
 
     at = newestTsMs(entries);
-    if (tookFromLedger || (!cache.ok && ledgerIds.length > 0)) {
+    if (tookFromLedger || (!cache.ok && Object.keys(rebuilt.entries).length > 0)) {
       source = 'rebuilt-log';
       if (cache.reason !== 'ok') reasons.unshift(cache.reason);
       else reasons.unshift('cache-behind-ledger');

package/scripts/lib/agent-usage-census.mjs

@@ -0,0 +1,394 @@
+/**
+ * agent-usage-census.mjs — which agent types ran, on which model, at what cost
+ * shape (#1617). Read-only, stdlib only.
+ *
+ * ## Why the transcripts and not the ledger
+ *
+ * `.orchestrator/metrics/subagents.jsonl` sees only dispatches from sessions in
+ * THIS repo, carries no observed model on most records and no effort at all, and
+ * ~87% of its stop records are the #939 phantom class with no type. The fleet
+ * dispatches from 20+ repos. The Claude Code transcripts are the source that
+ * holds all of it:
+ *
+ *   <root>/<project>/<session>/subagents/**\/agent-<id>.meta.json   → agentType
+ *   <root>/<project>/<session>/subagents/**\/agent-<id>.jsonl       → message.model + usage
+ *
+ * (`**` because Workflow agents nest one level deeper, under
+ * `subagents/workflows/<wf-id>/`.)
+ *
+ * ## Definitions (the numbers are only comparable if these hold)
+ *
+ *   run      one `agent-<id>.jsonl` whose FIRST turn falls inside the window.
+ *            Window membership by first turn, not by file mtime, so a run is
+ *            never split across two weekly censuses.
+ *   turn     one API response. Streaming writes several assistant lines per
+ *            response; they are collapsed on `requestId`, else `message.id`, last
+ *            usage block wins — the same recipe as hooks/subagent-telemetry.mjs
+ *            extractTranscriptUsage() (#950/#963). A line carrying neither key is
+ *            its own turn. The turn's timestamp is its FIRST line (request time).
+ *            Only lines with a `message.model` count as turns. The raw line
+ *            count is reported beside it as `assistant_lines` /
+ *            `models_by_lines` — the unit the #1617 discovery measured.
+ *   rebuild  a cache re-creation after an idle gap: the gap to the previous turn
+ *            exceeds GAP_SECONDS AND this turn's cache_creation exceeds
+ *            REBUILD_MIN_CREATION AND its cache_read is below its cache_creation.
+ *   start    input + cache_creation + cache_read of the run's first turn.
+ *
+ * ## Unreadable lines
+ *
+ * Every line is parsed; a line that does not parse is skipped AND counted in
+ * `malformed_lines` (measurement-discipline.md § Unlesbare JSONL-Zeilen). A
+ * meta.json that is missing or unreadable puts the run under `(no-meta)` /
+ * `(unreadable-meta)` rather than dropping it.
+ *
+ * Memory: transcripts are streamed line by line (readline). Per file only the
+ * turn map of that one run is held, so a multi-GB window stays bounded by the
+ * largest single run.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+export const SCHEMA = 'agent-usage-census/1';
+export const GAP_SECONDS = 300;
+export const REBUILD_MIN_CREATION = 20_000;
+export const DEFAULT_DAYS = 14;
+
+const AGENT_FILE_RE = /^agent-[A-Za-z0-9_-]+\.jsonl$/;
+
+const clamp = (v) => (Number.isInteger(v) && v >= 0 ? v : 0);
+
+/** Median of a numeric array; null for an empty one. */
+export function median(values) {
+  if (values.length === 0) return null;
+  const s = [...values].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+/**
+ * List every subagent transcript under `root` whose mtime is at or after
+ * `cutoffMs` (a cheap pre-filter: a file untouched since the cutoff cannot hold
+ * a first turn inside the window). Unreadable directories are skipped and
+ * counted.
+ *
+ * @param {string} root
+ * @param {number} cutoffMs
+ * @returns {{ files: string[], unreadable_dirs: number }}
+ */
+export function findSubagentTranscripts(root, cutoffMs) {
+  const files = [];
+  let unreadableDirs = 0;
+  const list = (dir) => {
+    try {
+      return fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      unreadableDirs++;
+      return [];
+    }
+  };
+  const walkSubagents = (dir) => {
+    for (const e of list(dir)) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walkSubagents(p);
+      else if (e.isFile() && AGENT_FILE_RE.test(e.name)) {
+        try {
+          if (fs.statSync(p).mtimeMs >= cutoffMs) files.push(p);
+        } catch {
+          // vanished between readdir and stat — not part of the window
+        }
+      }
+    }
+  };
+  for (const project of list(root)) {
+    if (!project.isDirectory()) continue;
+    for (const session of list(path.join(root, project.name))) {
+      if (!session.isDirectory()) continue;
+      const sub = path.join(root, project.name, session.name, 'subagents');
+      // lstat, not existsSync: a `subagents` symlink is skipped like every
+      // other symlink in this walk (Dirent types do not follow links).
+      let subStat;
+      try {
+        subStat = fs.lstatSync(sub);
+      } catch {
+        continue;
+      }
+      if (subStat.isDirectory()) walkSubagents(sub);
+    }
+  }
+  files.sort();
+  return { files, unreadable_dirs: unreadableDirs };
+}
+
+/**
+ * Agent type from the sibling meta.json.
+ * @param {string} jsonlPath
+ * @returns {string} agentType, or '(no-meta)' / '(unreadable-meta)'
+ */
+export function readAgentType(jsonlPath) {
+  const metaPath = jsonlPath.replace(/\.jsonl$/, '.meta.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(metaPath, 'utf8');
+  } catch {
+    return '(no-meta)';
+  }
+  try {
+    const t = JSON.parse(raw)?.agentType;
+    return typeof t === 'string' && t.trim() ? t : '(no-meta)';
+  } catch {
+    return '(unreadable-meta)';
+  }
+}
+
+/**
+ * Stream one subagent transcript into a run summary.
+ *
+ * @param {string} jsonlPath
+ * @returns {Promise<{ turns: Array<{ model: string, ts: number|null, input: number,
+ *   cacheCreation: number, cacheRead: number, output: number }>,
+ *   lines: Record<string, number>, malformed: number }>}
+ */
+export async function readRunTurns(jsonlPath) {
+  const byKey = new Map();
+  const unkeyed = [];
+  /** Raw assistant lines per model, BEFORE the streaming dedup. */
+  const lines = {};
+  let malformed = 0;
+  const rl = readline.createInterface({
+    input: fs.createReadStream(jsonlPath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      malformed++;
+      continue;
+    }
+    if (obj?.type !== 'assistant') continue;
+    const msg = obj.message;
+    const model = typeof msg?.model === 'string' && msg.model ? msg.model : null;
+    if (model === null) continue;
+    lines[model] = (lines[model] ?? 0) + 1;
+    const u = msg.usage && typeof msg.usage === 'object' ? msg.usage : {};
+    const ts = Date.parse(obj.timestamp);
+    const snap = {
+      model,
+      input: clamp(u.input_tokens),
+      cacheCreation: clamp(u.cache_creation_input_tokens),
+      cacheRead: clamp(u.cache_read_input_tokens),
+      output: clamp(u.output_tokens),
+    };
+    const key =
+      typeof obj.requestId === 'string' && obj.requestId
+        ? `r:${obj.requestId}`
+        : typeof msg.id === 'string' && msg.id
+          ? `m:${msg.id}`
+          : null;
+    if (key === null) {
+      unkeyed.push({ ...snap, ts: Number.isFinite(ts) ? ts : null });
+      continue;
+    }
+    const prev = byKey.get(key);
+    // Last usage block wins; the timestamp stays the FIRST one (request time).
+    byKey.set(key, { ...snap, ts: prev ? prev.ts : Number.isFinite(ts) ? ts : null });
+  }
+  return { turns: [...byKey.values(), ...unkeyed], lines, malformed };
+}
+
+/**
+ * Derive the per-run metrics from its turns (in file order).
+ * @param {Array<{ model: string, ts: number|null, input: number, cacheCreation: number,
+ *   cacheRead: number, output: number }>} turns
+ */
+export function summarizeRun(turns) {
+  const ordered = [...turns].sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+  const models = {};
+  let output = 0;
+  let rebuilds = 0;
+  for (let i = 0; i < ordered.length; i++) {
+    const t = ordered[i];
+    models[t.model] = (models[t.model] ?? 0) + 1;
+    output += t.output;
+    const prev = ordered[i - 1];
+    if (prev && prev.ts !== null && t.ts !== null && (t.ts - prev.ts) / 1000 > GAP_SECONDS
+      && t.cacheCreation > REBUILD_MIN_CREATION && t.cacheRead < t.cacheCreation) {
+      rebuilds++;
+    }
+  }
+  const first = ordered[0];
+  return {
+    firstTs: first?.ts ?? null,
+    turns: ordered.length,
+    models,
+    output,
+    rebuilds,
+    startContext: first ? first.input + first.cacheCreation + first.cacheRead : null,
+  };
+}
+
+const shareMap = (counts, total, unit = 'turns') =>
+  Object.fromEntries(
+    Object.entries(counts)
+      .sort((a, b) => b[1] - a[1])
+      .map(([m, n]) => [m, { [unit]: n, share: total ? +(n / total).toFixed(4) : 0 }]),
+  );
+
+/**
+ * Fold run summaries into the per-type census.
+ * @param {Array<{ agentType: string } & ReturnType<typeof summarizeRun>>} runs
+ */
+export function aggregate(runs) {
+  const groups = new Map();
+  const allModels = {};
+  let totalTurns = 0;
+  for (const r of runs) {
+    let g = groups.get(r.agentType);
+    if (!g) {
+      g = { runs: [], models: {} };
+      groups.set(r.agentType, g);
+    }
+    g.runs.push(r);
+    for (const [m, n] of Object.entries(r.models)) {
+      g.models[m] = (g.models[m] ?? 0) + n;
+      allModels[m] = (allModels[m] ?? 0) + n;
+      totalTurns += n;
+    }
+  }
+  const byType = [...groups.entries()].map(([agentType, g]) => {
+    const turns = g.runs.reduce((s, r) => s + r.turns, 0);
+    return {
+      agent_type: agentType,
+      dispatches: g.runs.length,
+      turns,
+      models: shareMap(g.models, turns),
+      turns_per_run_median: median(g.runs.map((r) => r.turns)),
+      output_tokens_per_run_median: median(g.runs.map((r) => r.output)),
+      cache_rebuilds: g.runs.reduce((s, r) => s + r.rebuilds, 0),
+      runs_with_cache_rebuild: g.runs.filter((r) => r.rebuilds > 0).length,
+      start_context_median: median(g.runs.map((r) => r.startContext).filter((v) => v !== null)),
+    };
+  });
+  byType.sort((a, b) => b.turns - a.turns || a.agent_type.localeCompare(b.agent_type));
+  return { turns: totalTurns, models: shareMap(allModels, totalTurns), by_agent_type: byType };
+}
+
+/**
+ * Run the census over a transcript root.
+ *
+ * @param {{ root: string, days?: number, now?: number, concurrency?: number }} opts
+ */
+export async function runCensus({ root, days = DEFAULT_DAYS, now = Date.now(), concurrency = 4 }) {
+  const cutoffMs = now - days * 86_400_000;
+  const { files, unreadable_dirs } = findSubagentTranscripts(root, cutoffMs);
+  const runs = [];
+  let malformed = 0;
+  let unreadableFiles = 0;
+  let outsideWindow = 0;
+  let emptyRuns = 0;
+  const lineModels = {};
+  let next = 0;
+  const worker = async () => {
+    while (next < files.length) {
+      const file = files[next++];
+      let res;
+      try {
+        res = await readRunTurns(file);
+      } catch {
+        unreadableFiles++;
+        continue;
+      }
+      malformed += res.malformed;
+      if (res.turns.length === 0) {
+        emptyRuns++;
+        continue;
+      }
+      const s = summarizeRun(res.turns);
+      if (s.firstTs === null || s.firstTs < cutoffMs || s.firstTs > now) {
+        outsideWindow++;
+        continue;
+      }
+      runs.push({ agentType: readAgentType(file), ...s });
+      for (const [m, n] of Object.entries(res.lines)) lineModels[m] = (lineModels[m] ?? 0) + n;
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker));
+  return {
+    schema: SCHEMA,
+    measured_at: new Date(now).toISOString(),
+    root,
+    window_days: days,
+    cutoff: new Date(cutoffMs).toISOString(),
+    definition: {
+      turn: 'assistant response with message.model, deduped on requestId else message.id (last usage wins)',
+      run_in_window: 'first turn timestamp >= cutoff',
+      cache_rebuild: `gap > ${GAP_SECONDS}s, cache_creation > ${REBUILD_MIN_CREATION}, cache_read < cache_creation`,
+      start_context: 'input + cache_creation + cache_read of the first turn',
+    },
+    files_scanned: files.length,
+    runs: runs.length,
+    runs_outside_window: outsideWindow,
+    runs_without_turns: emptyRuns,
+    unreadable_files: unreadableFiles,
+    unreadable_dirs,
+    malformed_lines: malformed,
+    ...aggregate(runs),
+    // Raw streaming lines, not API turns: the #1617 discovery counted these
+    // (349,519 in 14 days); one response is ~1.9 lines. Kept for comparability.
+    assistant_lines: Object.values(lineModels).reduce((a, b) => a + b, 0),
+    models_by_lines: shareMap(lineModels, Object.values(lineModels).reduce((a, b) => a + b, 0), 'lines'),
+  };
+}
+
+const pct = (s) => `${(s * 100).toFixed(1)}%`;
+const fmt = (v) => (v === null ? '-' : Number.isInteger(v) ? String(v) : v.toFixed(1));
+
+/** Human-readable table of a census result. */
+export function formatTable(result, { top = 25 } = {}) {
+  const out = [];
+  out.push(
+    `agent-usage-census: ${result.runs} runs / ${result.turns} turns, last ${result.window_days} days ` +
+      `(${result.files_scanned} files, malformed_lines ${result.malformed_lines}, ` +
+      `unreadable_files ${result.unreadable_files})`,
+  );
+  out.push(
+    'models: ' +
+      Object.entries(result.models)
+        .map(([m, v]) => `${m} ${pct(v.share)} (${v.turns})`)
+        .join(' · '),
+  );
+  out.push(
+    `raw assistant lines ${result.assistant_lines}: ` +
+      Object.entries(result.models_by_lines)
+        .slice(0, 3)
+        .map(([m, v]) => `${m} ${pct(v.share)}`)
+        .join(' · '),
+  );
+  out.push('');
+  const head = ['agent_type', 'runs', 'turns', 'models', 'turns/run', 'out/run', 'rebuilds', 'start_ctx'];
+  const rows = result.by_agent_type.slice(0, top).map((t) => [
+    t.agent_type,
+    String(t.dispatches),
+    String(t.turns),
+    Object.entries(t.models)
+      .slice(0, 3)
+      .map(([m, v]) => `${m.replace(/^claude-/, '')} ${pct(v.share)}`)
+      .join(', '),
+    fmt(t.turns_per_run_median),
+    fmt(t.output_tokens_per_run_median),
+    `${t.cache_rebuilds}/${t.runs_with_cache_rebuild}`,
+    fmt(t.start_context_median),
+  ]);
+  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (r) => r.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+  out.push(line(head));
+  for (const r of rows) out.push(line(r));
+  if (result.by_agent_type.length > top) out.push(`… ${result.by_agent_type.length - top} more types (--json for all)`);
+  out.push('');
+  out.push('rebuilds = cache rebuild events / runs with ≥1; medians per run.');
+  return out.join('\n');
+}

package/scripts/lib/auto-dialectic.mjs

@@ -36,7 +36,11 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { atomicWriteText, envelopeToError } from './io.mjs';
 
-import { filterRealSessions } from './session-schema.mjs';
+import { canonicalizeSessions, isMeasuredSession } from './sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
+import { resolveLedgerPath } from './ledger-path.mjs';
+import { withVisibleInboxText } from './learnings/surface.mjs';
+import { inboxPathFor } from './learnings/store-role.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -82,11 +86,11 @@ function consumedDirPath(repoRoot) {
 }
 
 function sessionsJsonlPath(repoRoot) {
-  return path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
+  return path.join(resolveEventsLedgerRoot(repoRoot), '.orchestrator', 'metrics', 'sessions.jsonl');
 }
 
 function learningsJsonlPath(repoRoot) {
-  return path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+  return resolveLedgerPath('.orchestrator/metrics/learnings.jsonl', repoRoot);
 }
 
 // ---------------------------------------------------------------------------
@@ -163,11 +167,10 @@ export async function readDialecticSignals({ repoRoot } = {}) {
           continue; // malformed line — skip silently
         }
       }
-      // Abandoned-session filter (#834): mirrors auto-dream.mjs
-      // readDreamSignals() — phantom `status: 'abandoned'` stubs are
-      // legitimate DATA but not legitimate SIGNAL, and must not fire the
-      // /evolve --dialectic cadence off zero real work.
-      const realEntries = filterRealSessions(entries);
+      // Canonical identities precede the shared measured-work predicate.
+      // Keep ID-less legacy rows: this cadence reader has always accepted them.
+      const realEntries = canonicalizeSessions(entries, { keepUnidentified: true })
+        .filter(isMeasuredSession);
       for (const entry of realEntries) {
         const startedAt = entry.started_at;
         if (typeof startedAt !== 'string' || startedAt.length === 0) continue;
@@ -181,10 +184,14 @@ export async function readDialecticSignals({ repoRoot } = {}) {
   }
 
   // Learnings
+  // The visible inbox records count too (#1516, #1685): shared visibility rule,
+  // also when the live store is absent (inbox host); an unreadable inbox never
+  // costs the live count (`withVisibleInboxText` swallows its own errors).
   const learningsPath = learningsJsonlPath(repoRoot);
-  if (existsSync(learningsPath)) {
+  if (existsSync(learningsPath) || existsSync(inboxPathFor(learningsPath))) {
     try {
-      const raw = await readFile(learningsPath, 'utf8');
+      const live = existsSync(learningsPath) ? await readFile(learningsPath, 'utf8') : '';
+      const raw = await withVisibleInboxText(learningsPath, live);
       const lines = raw.split('\n').filter((l) => l.length > 0);
       for (const line of lines) {
         let entry;