@saadnvd1/agent-os 0.3.498 → 0.3.501

package/lib/usage/ratchet.ts

@@ -0,0 +1,275 @@
+/**
+ * The ratchet. The baseline is the first week of rollups, and from then on
+ * only ever moves to a better value. An alert fires, once, when cost per
+ * merged PR or the clean-merge rate has drifted past the configured margin,
+ * naming the supporting metric that moved most.
+ */
+
+import { db } from "../db";
+import { spanOf, type Rollup, type Span } from "./span";
+import type { UsageConfig } from "./config";
+
+export type Direction = "lower" | "higher";
+
+// The better of the two. A missing or invalid candidate keeps what was.
+export function ratchet(
+  prev: number | null,
+  candidate: number | null,
+  better: Direction
+): number | null {
+  if (candidate === null || !Number.isFinite(candidate)) return prev;
+  if (prev === null || !Number.isFinite(prev)) return candidate;
+  return better === "lower"
+    ? Math.min(prev, candidate)
+    : Math.max(prev, candidate);
+}
+
+// What the baseline is judged on.
+export const HEADLINE = {
+  costPerMerged: "lower",
+  costPerClean: "lower",
+  cleanRate: "higher",
+} as const satisfies Record<string, Direction>;
+export type HeadlineKey = keyof typeof HEADLINE;
+
+// Supporting metrics, each where lower is better, per PR where it is a count.
+export interface Supporting {
+  reviewPerPr: number | null;
+  over200kShare: number | null;
+  orchestratorShare: number | null;
+  opusShare: number | null;
+  fixRoundsPerPr: number | null;
+  escalationsPerPr: number | null;
+  scopeChangesPerPr: number | null;
+  escapesPerPr: number | null;
+}
+
+export const SUPPORTING_LABELS: Record<keyof Supporting, string> = {
+  reviewPerPr: "review cost per PR",
+  over200kShare: "share of calls above 200k context",
+  orchestratorShare: "orchestrator share",
+  opusShare: "Opus share of the model mix",
+  fixRoundsPerPr: "fix rounds per PR",
+  escalationsPerPr: "escalations per PR",
+  scopeChangesPerPr: "scope changes per PR",
+  escapesPerPr: "escapes per PR",
+};
+
+const per = (n: number | null, merged: number) =>
+  n !== null && merged > 0 ? n / merged : null;
+
+export function supportingOf(s: Span): Supporting {
+  return {
+    reviewPerPr: s.reviewPerPr,
+    over200kShare: s.over200kShare,
+    orchestratorShare: s.orchestratorShare,
+    opusShare: s.opusShare,
+    fixRoundsPerPr: s.fixRoundsPerPr,
+    escalationsPerPr: per(s.escalations, s.merged),
+    scopeChangesPerPr: per(s.scopeChanges, s.merged),
+    escapesPerPr: per(s.escapes, s.merged),
+  };
+}
+
+export interface Baseline {
+  values: Record<HeadlineKey, number | null>;
+  supporting: Supporting;
+  setAt: number;
+}
+
+// The next baseline. None until `cfg.baselineDays` complete days exist with
+// at least `cfg.minMerges` merges among them: a quiet week would lock in a
+// baseline nothing can meet, so the seed waits for the first week that has
+// enough work, and a ratchet step skips a week that doesn't. The first is
+// those first days, and each night after it, the trailing week of days is
+// ratcheted in. The supporting snapshot follows cost per merged PR:
+// it is replaced only when that improves.
+export function nextBaseline(
+  prev: Baseline | null,
+  complete: Rollup[],
+  cfg: UsageConfig,
+  now = Date.now()
+): Baseline | null {
+  const days = [...complete].sort((a, b) => a.day.localeCompare(b.day));
+  if (days.length < cfg.baselineDays) return prev;
+  if (!prev) {
+    let s = spanOf(days.slice(0, cfg.baselineDays));
+    if (s.merged < cfg.minMerges) s = spanOf(days.slice(-cfg.baselineDays));
+    if (s.merged < cfg.minMerges) return null;
+    return {
+      values: {
+        costPerMerged: s.costPerMerged,
+        costPerClean: s.costPerClean,
+        cleanRate: s.cleanRate,
+      },
+      supporting: supportingOf(s),
+      setAt: now,
+    };
+  }
+  const s = spanOf(days.slice(-cfg.baselineDays));
+  if (s.merged < cfg.minMerges) return prev;
+  const values = { ...prev.values };
+  for (const k of Object.keys(HEADLINE) as HeadlineKey[])
+    values[k] = ratchet(prev.values[k], s[k], HEADLINE[k]);
+  const improved =
+    s.costPerMerged !== null &&
+    (prev.values.costPerMerged === null ||
+      s.costPerMerged < prev.values.costPerMerged);
+  return {
+    values,
+    supporting: improved ? supportingOf(s) : prev.supporting,
+    setAt: improved ? now : prev.setAt,
+  };
+}
+
+export interface Alert {
+  kind: "cost" | "quality";
+  message: string;
+}
+
+const round = (x: number) => Math.round(x * 1e6) / 1e6;
+
+// The supporting metric that moved furthest the wrong way since the baseline.
+export function biggestMover(
+  base: Supporting,
+  now: Supporting
+): { label: string; change: string } | null {
+  let best: { key: keyof Supporting; score: number } | null = null;
+  for (const key of Object.keys(base) as (keyof Supporting)[]) {
+    const b = base[key];
+    const c = now[key];
+    if (b === null || c === null) continue;
+    const score = b > 0 ? (c - b) / b : c > 0 ? 1 : 0;
+    if (score > 0 && (!best || score > best.score)) best = { key, score };
+  }
+  if (!best) return null;
+  const b = base[best.key] as number;
+  return {
+    label: SUPPORTING_LABELS[best.key],
+    change: b > 0 ? `+${Math.round(best.score * 100)}%` : "up from none",
+  };
+}
+
+// Conditions that hold now, over the last `avgDays` complete days.
+export function evaluateAlerts(
+  complete: Rollup[],
+  baseline: Baseline | null,
+  cfg: UsageConfig
+): Alert[] {
+  if (!baseline) return [];
+  const days = [...complete]
+    .sort((a, b) => a.day.localeCompare(b.day))
+    .slice(-cfg.avgDays);
+  const s = spanOf(days);
+  if (days.length < cfg.avgDays || s.merged < cfg.minMerges) return [];
+  const mover = biggestMover(baseline.supporting, supportingOf(s));
+  const moved = mover ? ` Biggest mover: ${mover.label} ${mover.change}.` : "";
+  const out: Alert[] = [];
+  const baseCost = baseline.values.costPerMerged;
+  if (s.costPerMerged !== null && baseCost !== null && baseCost > 0) {
+    const over = round(((s.costPerMerged - baseCost) / baseCost) * 100);
+    if (over > cfg.costPct)
+      out.push({
+        kind: "cost",
+        message: `Usage: cost per merged PR, ${cfg.avgDays}-day average, is ${Math.round(over)}% over baseline.${moved}`,
+      });
+  }
+  const baseClean = baseline.values.cleanRate;
+  if (s.cleanRate !== null && baseClean !== null) {
+    const under = round((baseClean - s.cleanRate) * 100);
+    if (under > cfg.cleanPoints)
+      out.push({
+        kind: "quality",
+        message: `Usage: clean-merge rate, ${cfg.avgDays}-day average, is ${Math.round(under)} points under baseline.${moved}`,
+      });
+  }
+  return out;
+}
+
+// Which firing alerts are new (to send), and which open ones have cleared.
+export function nextAlertState(
+  open: string[],
+  firing: Alert[]
+): { notify: Alert[]; clear: string[] } {
+  const now = new Set(firing.map((a) => a.kind));
+  return {
+    notify: firing.filter((a) => !open.includes(a.kind)),
+    clear: open.filter((k) => !now.has(k as Alert["kind"])),
+  };
+}
+
+export function loadBaseline(): Baseline | null {
+  const rows = db
+    .prepare(`SELECT metric, value, set_at, supporting FROM usage_baseline`)
+    .all() as {
+    metric: string;
+    value: number;
+    set_at: number;
+    supporting: string | null;
+  }[];
+  if (!rows.length) return null;
+  const values: Baseline["values"] = {
+    costPerMerged: null,
+    costPerClean: null,
+    cleanRate: null,
+  };
+  let supporting: Supporting | null = null;
+  let setAt = 0;
+  for (const r of rows) {
+    if (r.metric in values) values[r.metric as HeadlineKey] = r.value;
+    if (r.metric === "costPerMerged" && r.supporting)
+      supporting = JSON.parse(r.supporting) as Supporting;
+    setAt = Math.max(setAt, r.set_at);
+  }
+  return {
+    values,
+    supporting: supporting ?? supportingOf(spanOf([])),
+    setAt,
+  };
+}
+
+export function saveBaseline(b: Baseline): void {
+  db.transaction(() => {
+    for (const k of Object.keys(HEADLINE) as HeadlineKey[]) {
+      const v = b.values[k];
+      if (v === null) continue;
+      db.prepare(
+        `INSERT INTO usage_baseline (metric, value, set_at, supporting) VALUES (?, ?, ?, ?)
+         ON CONFLICT(metric) DO UPDATE SET value = excluded.value, set_at = excluded.set_at,
+           supporting = excluded.supporting`
+      ).run(
+        k,
+        v,
+        b.setAt,
+        k === "costPerMerged" ? JSON.stringify(b.supporting) : null
+      );
+    }
+  })();
+}
+
+export function openAlerts(): string[] {
+  return (
+    db
+      .prepare(`SELECT kind FROM usage_alerts WHERE cleared_at IS NULL`)
+      .all() as { kind: string }[]
+  ).map((r) => r.kind);
+}
+
+export function applyAlertState(
+  state: { notify: Alert[]; clear: string[] },
+  now = Date.now()
+): void {
+  db.transaction(() => {
+    for (const a of state.notify)
+      db.prepare(
+        `INSERT INTO usage_alerts (kind, opened_at, cleared_at, message) VALUES (?, ?, NULL, ?)
+         ON CONFLICT(kind) DO UPDATE SET opened_at = excluded.opened_at, cleared_at = NULL,
+           message = excluded.message`
+      ).run(a.kind, now, a.message);
+    for (const k of state.clear)
+      db.prepare(`UPDATE usage_alerts SET cleared_at = ? WHERE kind = ?`).run(
+        now,
+        k
+      );
+  })();
+}

package/lib/usage/rate-limits.ts

@@ -0,0 +1,192 @@
+/**
+ * The account's limit windows as Claude Code reports them: its
+ * rate_limit_event carries what the anthropic-ratelimit-unified-* headers
+ * said on a response, for the window that matters most at that moment. Each
+ * reading is kept with its time; between readings the weekly figure is an
+ * estimate from recorded usage, and labelled as one.
+ */
+
+import { db } from "../db";
+import { weighted, type TokenRow } from "./weights";
+import { readUsageConfig } from "./config";
+
+export type LimitWindow = "five_hour" | "seven_day";
+
+export interface Reading {
+  window: LimitWindow;
+  // Percent used, 0-100.
+  utilization: number;
+  raw: number;
+  // Epoch ms.
+  resetsAt: number | null;
+  status: string | null;
+}
+
+const WINDOWS: LimitWindow[] = ["five_hour", "seven_day"];
+const num = (v: unknown) =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+
+// A rate_limit_event carries what the headers said: utilization as a
+// fraction (0.42) and the reset in epoch seconds. A plan's per-window object
+// carries a percent (42) and an ISO time. Each source has one unit.
+const eventPercent = (fraction: number) => fraction * 100;
+
+// Readings in what the CLI emits: a rate_limit_event's info, or a plan's
+// per-window object. Anything else gives none.
+export function parseRateLimit(info: unknown): Reading[] {
+  if (!info || typeof info !== "object") return [];
+  const i = info as Record<string, unknown>;
+  const out: Reading[] = [];
+  const status = typeof i.status === "string" ? i.status : null;
+  const type = i.rateLimitType;
+  const raw = num(i.utilization);
+  if ((type === "five_hour" || type === "seven_day") && raw !== null) {
+    const reset = num(i.resetsAt);
+    out.push({
+      window: type,
+      utilization: eventPercent(raw),
+      raw,
+      resetsAt: reset === null ? null : reset * 1000,
+      status,
+    });
+  }
+  for (const w of WINDOWS) {
+    const o = i[w] as Record<string, unknown> | null | undefined;
+    const u = o && num(o.utilization);
+    if (!o || u === null || u === undefined) continue;
+    const reset =
+      typeof o.resets_at === "string" ? Date.parse(o.resets_at) : NaN;
+    out.push({
+      window: w,
+      utilization: u,
+      raw: u,
+      resetsAt: Number.isFinite(reset) ? reset : null,
+      status,
+    });
+  }
+  return out;
+}
+
+// Stores a reading only when it differs from that window's last, so a busy
+// day adds a handful of rows, not one per response.
+export function recordReadings(
+  readings: Reading[],
+  source: string,
+  sessionId: string | null = null,
+  at = Date.now()
+): number {
+  let added = 0;
+  for (const r of readings) {
+    const last = db
+      .prepare(
+        `SELECT utilization, resets_at, status FROM rate_limit_readings
+         WHERE window = ? ORDER BY id DESC LIMIT 1`
+      )
+      .get(r.window) as
+      | { utilization: number; resets_at: number | null; status: string | null }
+      | undefined;
+    if (
+      last &&
+      last.utilization === r.utilization &&
+      last.resets_at === r.resetsAt &&
+      last.status === r.status
+    )
+      continue;
+    db.prepare(
+      `INSERT INTO rate_limit_readings (at, window, utilization, raw, resets_at, status, session_id, source)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      at,
+      r.window,
+      r.utilization,
+      r.raw,
+      r.resetsAt,
+      r.status,
+      sessionId,
+      source
+    );
+    added++;
+  }
+  return added;
+}
+
+export interface WindowReading {
+  pct: number;
+  resetsAt: number | null;
+  // When it was read (or, for an estimate, worked out).
+  at: number;
+  estimated: boolean;
+}
+
+export function lastReading(
+  window: LimitWindow,
+  before = Number.MAX_SAFE_INTEGER
+): { at: number; utilization: number; resetsAt: number | null } | null {
+  const r = db
+    .prepare(
+      `SELECT at, utilization, resets_at FROM rate_limit_readings
+       WHERE window = ? AND at <= ? ORDER BY at DESC, id DESC LIMIT 1`
+    )
+    .get(window, before) as
+    | { at: number; utilization: number; resets_at: number | null }
+    | undefined;
+  return r
+    ? { at: r.at, utilization: r.utilization, resetsAt: r.resets_at }
+    : null;
+}
+
+const WEEK = 7 * 24 * 3600 * 1000;
+
+export function weightedBetween(from: number, to: number): number {
+  const rows = db
+    .prepare(
+      `SELECT model, provider, input_tokens, cache_read_tokens, cache_write_5m_tokens,
+         cache_write_1h_tokens, output_tokens FROM usage_calls WHERE at > ? AND at <= ?`
+    )
+    .all(from, to) as TokenRow[];
+  let t = 0;
+  for (const r of rows) t += weighted(r);
+  return t;
+}
+
+// The weekly percent now, worked out from the last real reading: the usage
+// recorded in the week up to that reading stands for its percent, so the
+// week up to now stands for this one. Null before any reading.
+export function estimateWeekly(now: number): WindowReading | null {
+  const last = lastReading("seven_day", now);
+  if (!last || last.utilization <= 0) return null;
+  const then = weightedBetween(last.at - WEEK, last.at);
+  if (then <= 0) return null;
+  const pct = (weightedBetween(now - WEEK, now) / then) * last.utilization;
+  return {
+    pct: Math.round(pct * 10) / 10,
+    resetsAt: last.resetsAt,
+    at: now,
+    estimated: true,
+  };
+}
+
+// The window from a reading when it's fresh enough, else (weekly only) the
+// estimate, labelled.
+export function currentWindow(
+  window: LimitWindow,
+  now = Date.now()
+): WindowReading | null {
+  const last = lastReading(window, now);
+  const maxAge =
+    window === "five_hour"
+      ? 30 * 60_000
+      : readUsageConfig().weeklyStaleHours * 3_600_000;
+  // A reading from before its window reset describes the old window.
+  const live =
+    last && now - last.at <= maxAge && (!last.resetsAt || last.resetsAt > now);
+  if (last && live)
+    return {
+      pct: last.utilization,
+      resetsAt: last.resetsAt,
+      at: last.at,
+      estimated: false,
+    };
+  if (window === "seven_day") return estimateWeekly(now);
+  return null;
+}

package/lib/usage/rollup.ts

@@ -0,0 +1,90 @@
+/**
+ * One day of usage and quality, from the ledger and the quality readers.
+ * Rows keep their sums as well as their ratios, so any span of days
+ * aggregates as a ratio of sums: three days' cost per PR is their total cost
+ * over their total PRs, never a mean of three ratios.
+ */
+
+import { db } from "../db";
+import { currentWindow } from "./rate-limits";
+import {
+  escalationsIn,
+  escapesIn,
+  mergedTasks,
+  qualityOf,
+  scopeChangesIn,
+  type Gh,
+} from "./quality";
+
+export * from "./span";
+import { computeRollup, type CallGroup, type Rollup } from "./span";
+
+export const dayKey = (ms: number) => {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+};
+export const dayStart = (day: string) => {
+  const [y, m, d] = day.split("-").map(Number);
+  return new Date(y, m - 1, d).getTime();
+};
+export const dayEnd = (day: string) => {
+  const [y, m, d] = day.split("-").map(Number);
+  return new Date(y, m - 1, d + 1).getTime();
+};
+
+function groupsIn(from: number, to: number): CallGroup[] {
+  return db
+    .prepare(
+      `SELECT kind, role, model, provider, COUNT(*) AS calls,
+         SUM(input_tokens) AS input_tokens, SUM(cache_read_tokens) AS cache_read_tokens,
+         SUM(cache_write_5m_tokens) AS cache_write_5m_tokens,
+         SUM(cache_write_1h_tokens) AS cache_write_1h_tokens,
+         SUM(output_tokens) AS output_tokens,
+         SUM(ctx_tokens IS NOT NULL) AS ctxKnown, SUM(ctx_tokens > 200000) AS over200k
+       FROM usage_calls WHERE at >= ? AND at < ?
+       GROUP BY kind, role, model, provider`
+    )
+    .all(from, to) as CallGroup[];
+}
+
+export async function rollupDay(
+  day: string,
+  now = Date.now(),
+  gh?: Gh
+): Promise<Rollup> {
+  const from = dayStart(day);
+  const to = dayEnd(day);
+  const tasks = mergedTasks(from, to);
+  const q = qualityOf(tasks);
+  const weekly = currentWindow("seven_day", Math.min(now, to));
+  return computeRollup({
+    day,
+    groups: groupsIn(from, to),
+    merged: tasks.length,
+    clean: q.filter((t) => t.clean).length,
+    fixRounds: q.reduce((t, x) => t + x.fixRounds, 0),
+    escalations: escalationsIn(from, to),
+    scopeChanges: scopeChangesIn(from, to),
+    escapes: await escapesIn(tasks, gh),
+    weeklyPct: weekly?.pct ?? null,
+    weeklyEstimated: weekly?.estimated ?? false,
+  });
+}
+
+export function saveRollup(r: Rollup, final: boolean, now = Date.now()): void {
+  db.prepare(
+    `INSERT INTO usage_rollups (day, data, final, computed_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT(day) DO UPDATE SET data = excluded.data, final = excluded.final,
+       computed_at = excluded.computed_at`
+  ).run(r.day, JSON.stringify(r), final ? 1 : 0, now);
+}
+
+export function loadRollups(limit = 60): Rollup[] {
+  return (
+    db
+      .prepare(`SELECT data FROM usage_rollups ORDER BY day DESC LIMIT ?`)
+      .all(limit) as { data: string }[]
+  )
+    .map((r) => JSON.parse(r.data) as Rollup)
+    .reverse();
+}

package/lib/usage/span.ts

@@ -0,0 +1,152 @@
+/**
+ * The pure half of the daily rollup: one day from its inputs, and any span
+ * of days as ratios of sums. No database, so the Usage view can use it too.
+ * A day keeps its sums as well as its ratios, so three days' cost per PR is
+ * their total cost over their total PRs, never a mean of three ratios.
+ */
+
+import { weighted, family, type TokenRow } from "./weights";
+
+export interface CallGroup extends TokenRow {
+  kind: string;
+  role: string | null;
+  calls: number;
+  // Calls with a known context size, and those of them above 200k.
+  ctxKnown: number;
+  over200k: number;
+}
+
+export interface Rollup {
+  day: string;
+  weighted: number;
+  // Everything but a person's own sessions.
+  work: number;
+  review: number;
+  orchestrator: number;
+  mix: { opus: number; sonnet: number; haiku: number };
+  calls: number;
+  ctxKnown: number;
+  over200k: number;
+  merged: number;
+  clean: number;
+  fixRounds: number;
+  escalations: number;
+  scopeChanges: number;
+  escapes: number | null;
+  weeklyPct: number | null;
+  weeklyEstimated: boolean;
+}
+
+export interface DayInputs {
+  day: string;
+  groups: CallGroup[];
+  merged: number;
+  clean: number;
+  fixRounds: number;
+  escalations: number;
+  scopeChanges: number;
+  escapes: number | null;
+  weeklyPct: number | null;
+  weeklyEstimated: boolean;
+}
+
+export function computeRollup(i: DayInputs): Rollup {
+  const r: Rollup = {
+    day: i.day,
+    weighted: 0,
+    work: 0,
+    review: 0,
+    orchestrator: 0,
+    mix: { opus: 0, sonnet: 0, haiku: 0 },
+    calls: 0,
+    ctxKnown: 0,
+    over200k: 0,
+    merged: i.merged,
+    clean: i.clean,
+    fixRounds: i.fixRounds,
+    escalations: i.escalations,
+    scopeChanges: i.scopeChanges,
+    escapes: i.escapes,
+    weeklyPct: i.weeklyPct,
+    weeklyEstimated: i.weeklyEstimated,
+  };
+  for (const g of i.groups) {
+    const w = weighted(g);
+    if (w <= 0 && g.provider && g.provider !== "anthropic") continue;
+    r.weighted += w;
+    r.mix[family(g.model)] += w;
+    r.calls += g.calls;
+    r.ctxKnown += g.ctxKnown;
+    r.over200k += g.over200k;
+    if (g.role !== "interactive") r.work += w;
+    if (g.kind === "review" || g.kind === "gate") r.review += w;
+    if (g.role === "orchestrator") r.orchestrator += w;
+  }
+  return r;
+}
+
+// A span of days, as ratios of sums.
+export interface Span {
+  days: number;
+  weighted: number;
+  work: number;
+  merged: number;
+  clean: number;
+  costPerMerged: number | null;
+  costPerClean: number | null;
+  cleanRate: number | null;
+  reviewPerPr: number | null;
+  over200kShare: number | null;
+  orchestratorShare: number | null;
+  opusShare: number | null;
+  fixRoundsPerPr: number | null;
+  escalations: number;
+  scopeChanges: number;
+  escapes: number | null;
+}
+
+const ratio = (a: number, b: number) => (b > 0 ? a / b : null);
+
+export function spanOf(rows: Rollup[]): Span {
+  const sum = (f: (r: Rollup) => number) => rows.reduce((t, r) => t + f(r), 0);
+  const work = sum((r) => r.work);
+  const merged = sum((r) => r.merged);
+  const clean = sum((r) => r.clean);
+  const weightedTotal = sum((r) => r.weighted);
+  const known = rows.filter((r) => r.escapes !== null);
+  return {
+    days: rows.length,
+    weighted: weightedTotal,
+    work,
+    merged,
+    clean,
+    costPerMerged: ratio(work, merged),
+    costPerClean: ratio(work, clean),
+    cleanRate: ratio(clean, merged),
+    reviewPerPr: ratio(
+      sum((r) => r.review),
+      merged
+    ),
+    over200kShare: ratio(
+      sum((r) => r.over200k),
+      sum((r) => r.ctxKnown)
+    ),
+    orchestratorShare: ratio(
+      sum((r) => r.orchestrator),
+      weightedTotal
+    ),
+    opusShare: ratio(
+      sum((r) => r.mix.opus),
+      weightedTotal
+    ),
+    fixRoundsPerPr: ratio(
+      sum((r) => r.fixRounds),
+      merged
+    ),
+    escalations: sum((r) => r.escalations),
+    scopeChanges: sum((r) => r.scopeChanges),
+    escapes: known.length
+      ? known.reduce((t, r) => t + (r.escapes ?? 0), 0)
+      : null,
+  };
+}