@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/commands/stats.js

@@ -1,5 +1,170 @@
 #!/usr/bin/env node
 
+/**
+ * @typedef {Object} StatsOptions
+ * @property {string} [filePath]
+ * @property {string} [configuredPath]
+ * @property {string} [rootDir]
+ * @property {boolean} [ensureDir]
+ * @property {string} [groupBy]
+ * @property {boolean} [forWrite]
+ * @property {*} [config]
+ * @property {string} [repo]
+ * @property {string} [from]
+ * @property {string} [to]
+ * @property {Function} [deriveFixRoundsFn]
+ * @property {Function} [log]
+ * @property {Function} [error]
+ * @property {Function} [exit]
+ */
+
+/**
+ * @typedef {Object} CsvData
+ * @property {string[]} headers
+ * @property {Record<string, string>[]} rows
+ */
+
+/**
+ * @typedef {Object} NormalizeStatsRowOptions
+ * @property {string} [repo]
+ * @property {string} [rootDir]
+ */
+
+/**
+ * @typedef {Object} LoadStatsCsvOptions
+ * @property {string} [rootDir]
+ */
+
+/**
+ * @typedef {Object} TelemetryToStatsOptions
+ * @property {string} agentFamily
+ * @property {number} [durationMinutes]
+ * @property {string} [model]
+ */
+
+/**
+ * @typedef {Object} UpsertStatsRowOptions
+ * @property {string} [filePath]
+ * @property {string} [rootDir]
+ */
+
+/**
+ * @typedef {Object} RecordStageStatsOptions
+ * @property {string} slug
+ * @property {string} stage
+ * @property {string} [rootDir]
+ * @property {string} [filePath]
+ * @property {string} [date]
+ * @property {string} [implementer]
+ * @property {string} [reviewer]
+ * @property {string} [prFixRounds]
+ * @property {*} [telemetry]
+ * @property {number} [durationMinutes]
+ * @property {string|null} [model]
+ */
+
+/**
+ * @typedef {Object} RecordIntegrationStatsOptions
+ * @property {string} slug
+ * @property {string} [rootDir]
+ * @property {string} [filePath]
+ * @property {string} [date]
+ */
+
+/**
+ * @typedef {Object} RecordActiveStatsOptions
+ * @property {string} [stage]
+ * @property {string} slug
+ * @property {string} [rootDir]
+ * @property {string} [prFixRounds]
+ * @property {string} [model]
+ */
+
+/**
+ * @typedef {Object} RecordReviewStatsOptions
+ * @property {string} [stage]
+ * @property {string} slug
+ * @property {string} [rootDir]
+ * @property {string} [reviewer]
+ * @property {string} [implementer]
+ * @property {string} [prFixRounds]
+ * @property {string} [model]
+ */
+
+/**
+ * @typedef {Object} RenderWeeklyStatsReportOptions
+ * @property {Date|string} [today]
+ * @property {string|null} [rootDir]
+ */
+
+/**
+ * @typedef {Object} RenderRangeStatsReportOptions
+ * @property {string|null} [rootDir]
+ * @property {string} [from]
+ * @property {string} [to]
+  */
+/** @typedef {Object.<string, string|number|boolean|undefined>} StatsRow
+ * @property {string} [date]
+ * @property {string} [repo]
+ * @property {string} [mission]
+ * @property {string} [classification]
+ * @property {string} [implementer]
+ * @property {string} [pr_fix_rounds]
+ * @property {string} [provider]
+ * @property {string} [model]
+ * @property {string} [implementer_agent]
+ * @property {string} [reviewer_agent]
+ * @property {string} [stage]
+ * @property {string} [input_tokens]
+ * @property {string} [output_tokens]
+ * @property {string} [cached_tokens]
+ * @property {string} [context_tokens]
+ * @property {string} [tool_calls]
+ * @property {string} [openai_usage_before]
+ * @property {string} [openai_usage_after]
+ * @property {string} [openai_usage_delta]
+ * @property {string} [duration_minutes]
+ * @property {string} [cost_usd]
+ * @property {boolean} [isMerged]
+ * @property {string} [normalizedDate]
+ * @property {string} [normalizedMerged]
+ * @property {string} [review_count]
+ * @property {string} [reviewer]
+ * @property {string|boolean} [merged]
+ * @property {string|boolean} [has_pr]
+ * @property {string} [created_at]
+ * @property {string} [averageFixRounds]
+ * @property {number} [missions]
+ */
+
+/**
+ * @typedef {Object} MissionStats
+ * @property {string} implementer
+ * @property {number} missions
+ * @property {string} averageFixRounds
+ */
+
+/**
+ * @typedef {Object} AccModeOptions
+ * @property {'sum'|'max'|'replace'} [mode]
+ */
+
+/**
+ * @typedef {Object} StatsCsvPathOptions
+ * @property {string} [filePath]
+ * @property {string} [rootDir]
+ * @property {*} [config]
+ * @property {boolean} [forWrite]
+ */
+
+/**
+ * @typedef {Object} StatsCmdOptions
+ * @property {Function} [log]
+ * @property {Function} [error]
+ * @property {Function} [exit]
+ * @property {string} [rootDir]
+ */
+
 const fs = require('fs');
 const path = require('path');
 const fmt = require('../core/fmt');
@@ -34,6 +199,7 @@ const USAGE_NUMBERS = new Set([
 
 const VALID_CLASSIFICATIONS = new Set(['ai_sdlc', 'user_value', 'unknown']);
 const SHIPPED_STATS_CSV_PATH = path.join(__dirname, '..', 'data', 'stats.seed.csv');
+/** @type {import('../core/storage')|null} */
 let STORAGE = null;
 
 function getStorage() {
@@ -61,18 +227,23 @@ function resolveRepoStatsCsvPath(rootDir = process.cwd()) {
  * Callers that pass an explicit `filePath` (e.g. `--csv-file`) bypass this
  * resolver entirely.
  */
+/**
+ * @param {StatsOptions} options
+ */
 function resolveStatsPath(options = {}) {
-  if (options.filePath) return options.filePath;
-  if (options.configuredPath) return options.configuredPath;
+  if (options.filePath) {return options.filePath;}
+  if (options.configuredPath) {return options.configuredPath;}
 
   const storage = getStorage();
   const rootDir = options.rootDir || process.cwd();
   const destinationPath = storage.resolveStatsPath({ ensureDir: options.ensureDir !== false });
-  require('../core/persistent-data-migration').migrateStats({
-    sourcePaths: [resolveRepoStatsCsvPath(rootDir), SHIPPED_STATS_CSV_PATH],
-    destinationPath,
-    defaultRepo: resolveStatsRepoName(rootDir),
-  });
+  require('../core/persistent-data-migration').migrateStats(
+    /** @type{any} */({
+      sourcePaths: [resolveRepoStatsCsvPath(rootDir), SHIPPED_STATS_CSV_PATH],
+      destinationPath,
+      defaultRepo: resolveStatsRepoName(rootDir),
+    })
+  );
   return destinationPath;
 }
 
@@ -86,6 +257,9 @@ function resolveStatsPath(options = {}) {
  * package, or consuming repository. When a root is supplied, it is used only
  * as the legacy repo-root import source during one-time migration.
  */
+/**
+ * @param {string} legacyRuntimeRoot
+ */
 function resolveStatsFilePath(legacyRuntimeRoot) {
   return resolveStatsPath({ rootDir: legacyRuntimeRoot });
 }
@@ -96,6 +270,9 @@ function resolveStatsFilePath(legacyRuntimeRoot) {
  * workflow-owned integration CSV.
  */
 
+/**
+ * @param {string} line
+ */
 function parseCsvLine(line) {
   const result = [];
   let current = '';
@@ -120,14 +297,21 @@ function parseCsvLine(line) {
   return result;
 }
 
+/**
+ * @param {*} value
+ */
 function escapeCsvValue(value) {
   const stringValue = String(value ?? '');
-  if (!/[",\n]/.test(stringValue)) return stringValue;
+  if (!/[",\n]/.test(stringValue)) {return stringValue;}
   return `"${stringValue.replace(/"/g, '""')}"`;
 }
 
+/**
+ * @param {string} rootDir
+ * @param {string} repoRelativePath
+ */
 function resolveRepoRelativePath(rootDir, repoRelativePath) {
-  if (!repoRelativePath || typeof repoRelativePath !== 'string') return null;
+  if (!repoRelativePath || typeof repoRelativePath !== 'string') {return null;}
   return path.isAbsolute(repoRelativePath)
     ? repoRelativePath
     : path.join(rootDir, repoRelativePath);
@@ -139,23 +323,32 @@ function resolveRepoRelativePath(rootDir, repoRelativePath) {
  * resolves to the repo-root legacy import path. When PARALLIX_HOME is
  * initialized the effective parallix-owned path is via the storage resolver.
  */
+/**
+ * @param {string|StatsCsvPathOptions} options
+ */
 function resolveStatsCsvPath(options = {}) {
-  if (typeof options === 'string') return options;
+  if (typeof options === 'string') {return options;}
 
-  const filePath = options.filePath;
-  if (filePath) return filePath;
+  /** @type {StatsCsvPathOptions} */
+  const opts = options;
+  const filePath = opts.filePath;
+  if (filePath) {return filePath;}
 
-  const rootDir = options.rootDir || process.cwd();
-  const config = options.config || loadEffectiveConfig(rootDir);
+  const rootDir = opts.rootDir || process.cwd();
+  const config = opts.config || loadEffectiveConfig(rootDir);
   const configuredPath = config.adapters?.stats?.path;
   const repoPath = resolveRepoRelativePath(rootDir, configuredPath);
 
-  if (repoPath && (options.forWrite || fs.existsSync(repoPath))) {
+  if (repoPath && (opts.forWrite || fs.existsSync(repoPath))) {
     return repoPath;
   }
   return resolveRepoStatsCsvPath(rootDir);
 }
 
+/**
+ * @param {string} filePath
+ * @returns {CsvData}
+ */
 function loadCsv(filePath) {
   if (!fs.existsSync(filePath)) {
     return { headers: [], rows: [] };
@@ -171,6 +364,7 @@ function loadCsv(filePath) {
   const rows = [];
   for (let i = 1; i < lines.length; i += 1) {
     const values = parseCsvLine(lines[i]);
+    /** @type {Record<string, string>} */
     const row = {};
     headers.forEach((header, idx) => {
       row[header] = values[idx] || '';
@@ -180,6 +374,10 @@ function loadCsv(filePath) {
   return { headers, rows };
 }
 
+/**
+ * @param {string|null} filePath
+ * @param {LoadStatsCsvOptions} [options]
+ */
 function loadStatsCsv(filePath = null, options = {}) {
   // Resolve effective path: explicit filePath > config > PARALLIX_HOME
   let effectivePath = filePath;
@@ -208,6 +406,10 @@ function loadStatsCsv(filePath = null, options = {}) {
  * 'default' so legacy rows and integration rows share the (repo, mission, stage)
  * upsert key.
  */
+/**
+ * @param {StatsRow} row
+ * @param {NormalizeStatsRowOptions} options
+ */
 function normalizeStatsRow(row = {}, options = {}) {
   const repo = String(row.repo || options.repo || resolveStatsRepoName(options.rootDir)).trim();
   return {
@@ -235,6 +437,10 @@ function normalizeStatsRow(row = {}, options = {}) {
   };
 }
 
+/**
+ * @param {string} filePath
+ * @param {StatsRow[]} rows
+ */
 function saveStatsCsv(filePath, rows) {
   let effectivePath = filePath;
   if (!effectivePath) {
@@ -248,31 +454,40 @@ function saveStatsCsv(filePath, rows) {
   return effectivePath;
 }
 
+/**
+ * @param {string} dateStr
+ */
 function formatDate(dateStr) {
-  if (!dateStr) return '';
+  if (!dateStr) {return '';}
   try {
     const date = new Date(dateStr);
     return date.toISOString().split('T')[0];
-  } catch {
+  } catch (/** @type{any} */ _err) {
     return dateStr;
   }
 }
 
+/**
+ * @param {*} value
+ */
 function parseBooleanish(value) {
-  if (typeof value === 'boolean') return value;
-  if (value === null || value === undefined) return null;
+  if (typeof value === 'boolean') {return value;}
+  if (value === null || value === undefined) {return null;}
 
   const normalized = String(value).trim().toLowerCase();
-  if (!normalized || normalized === '—' || normalized === 'n/a') return null;
-  if (['yes', 'true', '1', 'y', 'merged', 'closed'].includes(normalized)) return true;
-  if (['no', 'false', '0', 'n', 'open'].includes(normalized)) return false;
+  if (!normalized || normalized === '—' || normalized === 'n/a') {return null;}
+  if (['yes', 'true', '1', 'y', 'merged', 'closed'].includes(normalized)) {return true;}
+  if (['no', 'false', '0', 'n', 'open'].includes(normalized)) {return false;}
   return null;
 }
 
+/**
+ * @param {StatsRow} row
+ */
 function normalizeRow(row) {
-  const reviewCount = Number.parseInt(row.review_count, 10) || 0;
+  const reviewCount = Number.parseInt(String(row.review_count || ''), 10) || 0;
   const mergedValue = Object.prototype.hasOwnProperty.call(row, 'merged')
-    ? row.merged
+    ? String(row.merged)
     : row.has_pr;
   let isMerged = parseBooleanish(mergedValue);
 
@@ -290,51 +505,72 @@ function normalizeRow(row) {
   };
 }
 
+/**
+ * @param {StatsRow[]} rows
+ */
 function normalizeRows(rows) {
   return rows.map(normalizeRow);
 }
 
+/**
+ * @param {StatsRow} row
+ */
 function statsMissionKey(row) {
   return `${String(row.repo || '').trim()}::${String(row.mission || '').trim().toLowerCase()}`;
 }
 
+/**
+ * @param {StatsRow[]} rows
+ * @param {string} field
+ */
 function groupBy(rows, field) {
+  /** @type {Record<string, StatsRow[]>} */
   const groups = {};
   for (const row of rows) {
-    const key = row[field] || 'unknown';
-    if (!groups[key]) groups[key] = [];
+    const key = String(row[field] || 'unknown');
+    if (!groups[key]) {groups[key] = [];}
     groups[key].push(row);
   }
   return groups;
 }
 
+/**
+ * @param {StatsRow[]} group
+ */
 function computeImplStats(group) {
   const total = group.length;
   const merged = group.filter(row => row.isMerged).length;
-  const totalReviews = group.reduce((sum, row) => sum + (Number.parseInt(row.review_count, 10) || 0), 0);
+  const totalReviews = group.reduce((sum, row) => sum + (Number.parseInt(String(row.review_count || ''), 10) || 0), 0);
   const avgReviews = total > 0 ? (totalReviews / total).toFixed(2) : '0.00';
-  const reviewRounds = group.reduce((sum, row) => sum + Math.max(1, Number.parseInt(row.review_count, 10) || 0), 0);
+  const reviewRounds = group.reduce((sum, row) => sum + Math.max(1, Number.parseInt(String(row.review_count || ''), 10) || 0), 0);
   const avgRounds = total > 0 ? (reviewRounds / total).toFixed(2) : '0.00';
   return { total, merged, totalReviews, avgReviews, reviewRounds, avgRounds };
 }
 
+/**
+ * @param {StatsRow[]} group
+ */
 function computePeriodStats(group) {
-  const dates = group.map(row => formatDate(row.normalizedDate)).filter(Boolean);
-  if (dates.length === 0) return null;
+  const dates = group.map(row => formatDate(String(row.normalizedDate))).filter(Boolean);
+  if (dates.length === 0) {return null;}
   const sorted = dates.sort();
   const first = sorted[0];
   const last = sorted[sorted.length - 1];
   const start = new Date(first);
   const end = new Date(last);
-  const days = Math.max(1, Math.ceil((end - start) / (1000 * 60 * 60 * 24)) + 1);
+  const days = Math.max(1, Math.ceil((Number(end) - Number(start)) / (1000 * 60 * 60 * 24)) + 1);
   const total = group.length;
   const merged = group.filter(row => row.isMerged).length;
   const open = total - merged;
-  const totalReviews = group.reduce((sum, row) => sum + (Number.parseInt(row.review_count, 10) || 0), 0);
+  const totalReviews = group.reduce((sum, row) => sum + (Number.parseInt(String(row.review_count || ''), 10) || 0), 0);
   const avgReviews = total > 0 ? (totalReviews / total).toFixed(2) : '0.00';
   return { period: `${first} → ${last}`, days, total, merged, open, totalReviews, avgReviews };
 }
 
+/**
+ * @param {{headers: string[], rows: StatsRow[]}} data
+ * @param {StatsOptions} options
+ */
 function generateMarkdownReport(data, options = {}) {
   const rows = normalizeRows(data.rows);
   const groupByField = options.groupBy;
@@ -350,7 +586,7 @@ function generateMarkdownReport(data, options = {}) {
 
   const overallMerged = rows.filter(row => row.isMerged).length;
   const overallOpen = rows.length - overallMerged;
-  const overallReviews = rows.reduce((sum, row) => sum + (Number.parseInt(row.review_count, 10) || 0), 0);
+  const overallReviews = rows.reduce((sum, row) => sum + (Number.parseInt(row.review_count || '', 10) || 0), 0);
   lines.push('## Overall Summary\n');
   lines.push(`- **Total PRs:** ${rows.length}`);
   lines.push(`- **Merged:** ${overallMerged}`);
@@ -362,9 +598,9 @@ function generateMarkdownReport(data, options = {}) {
   lines.push('## Per-PR Detail\n');
   lines.push('| Mission | Implementer | Reviewer | Reviews | Merged | Created |');
   lines.push('|---------|-------------|----------|---------|--------|---------|');
-  const sorted = [...rows].sort((a, b) => (a.normalizedDate || '').localeCompare(b.normalizedDate || ''));
+  const sorted = [...rows].sort((a, b) => String(a.normalizedDate || '').localeCompare(String(b.normalizedDate || '')));
   for (const row of sorted) {
-    lines.push(`| ${row.mission} | ${row.implementer} | ${row.reviewer} | ${row.review_count} | ${row.normalizedMerged} | ${formatDate(row.normalizedDate)} |`);
+    lines.push(`| ${/** @type {any} */ (row).mission} | ${/** @type {any} */ (row).implementer} | ${/** @type {any} */ (row).reviewer} | ${row.review_count} | ${row.normalizedMerged} | ${formatDate(String(row.normalizedDate))} |`);
   }
   lines.push('');
 
@@ -394,17 +630,17 @@ function generateMarkdownReport(data, options = {}) {
   } else if (groupByField === 'period') {
     const groups = {};
     for (const row of rows) {
-      const date = formatDate(row.normalizedDate);
-      if (!date) continue;
+      const date = formatDate(String(row.normalizedDate));
+      if (!date) {continue;}
       const month = date.substring(0, 7);
-      if (!groups[month]) groups[month] = [];
-      groups[month].push(row);
+      if (!/** @type {any} */ (groups)[month]) {/** @type {any} */ (groups)[month] = [];}
+      /** @type {any} */ (groups)[month].push(row);
     }
     lines.push('## By Period (Month)\n');
     lines.push('| Period | Days | PRs | Merged | Open | Total Reviews | Avg Reviews/PR |');
     lines.push('|--------|------|-----|--------|------|---------------|----------------|');
     for (const month of Object.keys(groups).sort()) {
-      const period = computePeriodStats(groups[month]);
+      const period = computePeriodStats(/** @type{StatsRow[]} */(/** @type {any} */ (groups)[month]));
       if (period) {
         lines.push(`| ${period.period} | ${period.days} | ${period.total} | ${period.merged} | ${period.open} | ${period.totalReviews} | ${period.avgReviews} |`);
       }
@@ -418,8 +654,8 @@ function generateMarkdownReport(data, options = {}) {
     if (mergedRows.length > 0) {
       lines.push('| Mission | Implementer | Reviews | Reviewer | Created |');
       lines.push('|---------|-------------|---------|----------|---------|');
-      for (const row of mergedRows.sort((a, b) => (a.normalizedDate || '').localeCompare(b.normalizedDate || ''))) {
-        lines.push(`| ${row.mission} | ${row.implementer} | ${row.review_count} | ${row.reviewer} | ${formatDate(row.normalizedDate)} |`);
+      for (const row of mergedRows.sort((a, b) => String(a.normalizedDate || '').localeCompare(String(b.normalizedDate || '')))) {
+        lines.push(`| ${/** @type {any} */ (row).mission} | ${/** @type {any} */ (row).implementer} | ${row.review_count} | ${/** @type {any} */ (row).reviewer} | ${formatDate(String(row.normalizedDate))} |`);
       }
     } else {
       lines.push('None.');
@@ -427,10 +663,9 @@ function generateMarkdownReport(data, options = {}) {
     lines.push('');
     lines.push('### Unmerged/Closed PRs\n');
     if (unmergedRows.length > 0) {
-      lines.push('| Mission | Implementer | Reviews | Reviewer | Created |');
       lines.push('|---------|-------------|---------|----------|---------|');
-      for (const row of unmergedRows.sort((a, b) => (a.normalizedDate || '').localeCompare(b.normalizedDate || ''))) {
-        lines.push(`| ${row.mission} | ${row.implementer} | ${row.review_count} | ${row.reviewer} | ${formatDate(row.normalizedDate)} |`);
+      for (const row of unmergedRows.sort((a, b) => String(a.normalizedDate || '').localeCompare(String(b.normalizedDate || '')))) {
+        lines.push(`| ${/** @type {any} */ (row).mission} | ${/** @type {any} */ (row).implementer} | ${row.review_count} | ${/** @type {any} */ (row).reviewer} | ${formatDate(String(row.normalizedDate))} |`);
       }
     } else {
       lines.push('None.');
@@ -442,26 +677,38 @@ function generateMarkdownReport(data, options = {}) {
   lines.push('```csv');
   lines.push(data.headers.join(','));
   for (const row of rows) {
-    lines.push(data.headers.map(header => row[header] || '').join(','));
+    lines.push(data.headers.map(header => /** @type{any} */(row)[header] || '').join(','));
   }
   lines.push('```\n');
 
   return lines.join('\n');
 }
 
+/**
+ * @param {*} value
+ */
 function isValidClassification(value) {
   return VALID_CLASSIFICATIONS.has(String(value || '').trim().toLowerCase());
 }
 
+/**
+ * @param {*} value
+ */
 function normalizeClassification(value) {
   const normalized = String(value || '').trim().toLowerCase();
   return isValidClassification(normalized) ? normalized : null;
 }
 
+/**
+ * @param {*} value
+ */
 function normalizeImplementer(value) {
   return String(value || '').trim().replace(/^@/, '').toLowerCase() || null;
 }
 
+/**
+ * @param {StatsRow} row
+ */
 function statsRowActorKey(row = {}) {
   const stage = String(row.stage || 'default').trim().toLowerCase() || 'default';
   if (stage === 'review') {
@@ -470,10 +717,17 @@ function statsRowActorKey(row = {}) {
   return normalizeImplementer(row.implementer_agent || row.implementer || '') || '';
 }
 
+/**
+ * @param {string} value
+ */
 function parseDateOnly(value) {
   return new Date(`${value}T00:00:00Z`);
 }
 
+/**
+ * @param {string} value
+ * @param {string} flagName
+ */
 function parseDateOnlyStrict(value, flagName) {
   const raw = String(value || '').trim();
   const label = flagName || 'date';
@@ -489,16 +743,26 @@ function parseDateOnlyStrict(value, flagName) {
   return date;
 }
 
+/**
+ * @param {Date} date
+ */
 function formatDateOnly(date) {
   return date.toISOString().slice(0, 10);
 }
 
+/**
+ * @param {Date} date
+ * @param {number} days
+ */
 function addDays(date, days) {
   const next = new Date(date.getTime());
   next.setUTCDate(next.getUTCDate() + days);
   return next;
 }
 
+/**
+ * @param {Date|string} today
+ */
 function parseToday(today = new Date()) {
   if (today instanceof Date) {
     return parseDateOnly(formatDateOnly(today));
@@ -506,6 +770,10 @@ function parseToday(today = new Date()) {
   return parseDateOnly(String(today));
 }
 
+/**
+ * @param {Date|string} endDate
+ * @param {number} days
+ */
 function createWindow(endDate, days) {
   const end = parseToday(endDate);
   const start = addDays(end, -(days - 1));
@@ -516,7 +784,11 @@ function createWindow(endDate, days) {
   };
 }
 
-function createRangeWindow({ from, to } = {}) {
+/**
+ * @param {{from?: string, to?: string}} range
+ */
+function createRangeWindow(range = {}) {
+  const { from, to } = range;
   if (!from) {
     throw new Error('Invalid date range argument --from: value is required when using range mode.');
   }
@@ -537,18 +809,29 @@ function createRangeWindow({ from, to } = {}) {
   };
 }
 
+/**
+ * @param {Date} today
+ */
 function buildWeeklyWindows(today = new Date()) {
   const current = createWindow(today, 7);
   const previous = createWindow(addDays(current.start, -1), 7);
   return { current, previous };
 }
 
+/**
+ * @param {StatsRow} row
+ * @param {{start: Date, end: Date}} window
+ */
 function rowInWindow(row, window) {
-  if (!row.date) return false;
-  const date = parseDateOnly(row.date);
+  if (!row.date) {return false;}
+  const date = parseDateOnly(String(row.date));
   return date >= window.start && date <= window.end;
 }
 
+/**
+ * @param {StatsRow[]} rows
+ * @param {{start: Date, end: Date}} window
+ */
 function summarizeMissionWindow(rows, window) {
   const windowRows = rows.filter(row => rowInWindow(row, window));
   // Deduplicate by mission so multi-stage telemetry rows don't inflate counts.
@@ -557,7 +840,7 @@ function summarizeMissionWindow(rows, window) {
   const seenMissions = new Set();
   const uniqueMissions = windowRows.filter(row => {
     const key = statsMissionKey(row);
-    if (seenMissions.has(key)) return false;
+    if (seenMissions.has(key)) {return false;}
     seenMissions.add(key);
     return true;
   });
@@ -586,8 +869,13 @@ function summarizeMissionWindow(rows, window) {
  * the event store isn't available (different repo / not checked out), leaving the
  * caller on the stored value.
  */
+/**
+ * @param {string} slug
+ * @param {string} rootDir
+ * @param {string} repo
+ */
 function deriveFixRoundsLocalAuthoritative(slug, rootDir, repo) {
-  if (!slug || !rootDir) return null;
+  if (!slug || !rootDir) {return null;}
   // Only derive for missions belonging to the current checkout's repo.
   if (repo && String(repo).trim() && String(repo).trim() !== resolveStatsRepoName(rootDir)) {
     return null;
@@ -599,45 +887,83 @@ function deriveFixRoundsLocalAuthoritative(slug, rootDir, repo) {
   return null;
 }
 
+/**
+ * @param {StatsRow[]} rows
+ * @param {{start: Date, end: Date}} window
+ * @param {{rootDir?: string|null, deriveFixRoundsFn?: Function}} [options]
+ */
 function summarizeAgentWindow(rows, window, options = {}) {
-  const { rootDir = null, deriveFixRoundsFn = deriveFixRoundsLocalAuthoritative } = options;
-  const groups = groupBy(rows.filter(row => rowInWindow(row, window)), 'implementer');
-  return Object.entries(groups)
-    .map(([implementer, group]) => {
-      // Deduplicate by repo+mission: keep one row per unique mission in each repo,
-      // preferring the row with the highest stored pr_fix_rounds.
-      const byMission = {};
-      for (const row of group) {
-        const key = statsMissionKey(row);
-        const prev = byMission[key];
-        const rounds = Number.parseInt(row.pr_fix_rounds, 10) || 0;
-        const prevRounds = prev ? (Number.parseInt(prev.pr_fix_rounds, 10) || 0) : -1;
-        if (!prev || rounds > prevRounds) byMission[key] = row;
+  /** @type {{rootDir?: string|null, deriveFixRoundsFn?: Function}} */
+  const opts = options;
+  const { rootDir = null, deriveFixRoundsFn = deriveFixRoundsLocalAuthoritative } = opts;
+  const windowRows = rows.filter(row => rowInWindow(row, window));
+  // Only count missions with a valid classification so the agent table totals
+  // align with the mission-count table (which also excludes null/invalid
+  // classifications via summarizeMissionWindow → validMissions).
+  const validWindowRows = windowRows.filter(row => normalizeClassification(row.classification) !== null);
+  // Deduplicate globally by (repo, mission) first so each mission is counted
+  // exactly once across all agent groups — matching the mission-count table.
+  // Prefer the row where model === implementer (the implementer's own model),
+  // since the implementer field is the last implementer who closed the mission.
+  // Among those, prefer the row with the highest fix rounds. Falls back to the
+  // row with the highest fix rounds when no implementer-row exists.
+  /** @type {Record<string, StatsRow>} */
+  const byMission = {};
+  for (const row of validWindowRows) {
+    const key = statsMissionKey(row);
+    const prev = byMission[key];
+    const rounds = Number.parseInt(String(row.pr_fix_rounds), 10) || 0;
+    const prevRounds = prev ? (Number.parseInt(String(prev.pr_fix_rounds), 10) || 0) : -1;
+    const modelTrimmed = (row.model && String(row.model).trim()) || '';
+    const implTrimmed = (row.implementer && String(row.implementer).trim()) || '';
+    const isImplementerRow = modelTrimmed && implTrimmed && modelTrimmed.toLowerCase() === implTrimmed.toLowerCase();
+    let prevIsImpl = false;
+    if (prev) {
+      const prevModelTrimmed = (prev.model && String(prev.model).trim()) || '';
+      const prevImplTrimmed = (prev.implementer && String(prev.implementer).trim()) || '';
+      prevIsImpl = prevModelTrimmed && prevImplTrimmed && prevModelTrimmed.toLowerCase() === prevImplTrimmed.toLowerCase();
+    }
+    if (!prev || (isImplementerRow && !prevIsImpl) || (isImplementerRow && prevIsImpl && rounds > prevRounds) || (!isImplementerRow && !prevIsImpl && rounds > prevRounds)) {
+      byMission[key] = row;
+    }
+  }
+  const uniqueMissions = Object.values(byMission);
+  /** @type {Record<string, StatsRow[]>} */
+  const groups = {};
+  for (const row of uniqueMissions) {
+    const displayKey = (row.model && String(row.model).trim()) || (row.implementer || 'unknown');
+    if (!groups[displayKey]) {groups[displayKey] = [];}
+    groups[displayKey].push(row);
+  }
+  // Build agent groups from the globally deduplicated missions.
+  // For each mission, trust local ground truth (events/branch history) over
+  // the stored value when available — this is what makes the report reflect
+  // the review loop rather than the (untrusted) CSV. `pr_fix_rounds` is a
+  // review-loop quantity, independent of whether the mission was integrated.
+  const roundsFor = (/** @type {any} */ row) => {
+    if (rootDir) {
+      const authoritative = deriveFixRoundsFn(row.mission, rootDir, row.repo);
+      if (authoritative !== null && authoritative !== undefined) {
+        return Number.parseInt(authoritative, 10) || 0;
       }
-      const uniqueGroup = Object.values(byMission);
-      // For each mission, trust local ground truth (events/branch history) over
-      // the stored value when available — this is what makes the report reflect
-      // the review loop rather than the (untrusted) CSV. `pr_fix_rounds` is a
-      // review-loop quantity, independent of whether the mission was integrated.
-      const roundsFor = (row) => {
-        if (rootDir) {
-          const authoritative = deriveFixRoundsFn(row.mission, rootDir, row.repo);
-          if (authoritative !== null && authoritative !== undefined) {
-            return Number.parseInt(authoritative, 10) || 0;
-          }
-        }
-        return Number.parseInt(row.pr_fix_rounds, 10) || 0;
-      };
-      const totalRounds = uniqueGroup.reduce((sum, row) => sum + roundsFor(row), 0);
+    }
+    return Number.parseInt(row.pr_fix_rounds, 10) || 0;
+  };
+  return Object.entries(groups)
+    .map(([displayKey, group]) => {
+      const totalRounds = group.reduce((sum, row) => sum + roundsFor(row), 0);
       return {
-        implementer,
-        missions: uniqueGroup.length,
-        averageFixRounds: uniqueGroup.length > 0 ? (totalRounds / uniqueGroup.length).toFixed(2) : '0.00',
+        implementer: displayKey,
+        missions: group.length,
+        averageFixRounds: group.length > 0 ? (totalRounds / group.length).toFixed(2) : '0.00',
       };
     })
     .sort((a, b) => a.implementer.localeCompare(b.implementer));
 }
 
+/**
+ * @param {MissionStats[]} rows
+ */
 function colorAverageFixRounds(rows) {
   const values = rows
     .map(row => Number.parseFloat(row.averageFixRounds))
@@ -652,23 +978,26 @@ function colorAverageFixRounds(rows) {
 
   return rows.map(row => {
     const value = Number.parseFloat(row.averageFixRounds);
-    if (!Number.isFinite(value)) return row.averageFixRounds;
+    if (!Number.isFinite(value)) {return row.averageFixRounds;}
     if (best === worst) {
-      return fmt.colorize(fmt.colors.green, row.averageFixRounds);
+      return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.green), row.averageFixRounds);
     }
     if (value === best) {
-      return fmt.colorize(fmt.colors.green, row.averageFixRounds);
+      return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.green), row.averageFixRounds);
     }
     if (value === worst) {
-      return fmt.colorize(fmt.colors.red, row.averageFixRounds);
+      return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.red), row.averageFixRounds);
     }
-    return fmt.colorize(fmt.colors.yellow, row.averageFixRounds);
+    return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.yellow), row.averageFixRounds);
   });
 }
 
+/**
+ * @param {MissionStats[]} rows
+ */
 function colorMissionCounts(rows) {
   const values = rows
-    .map(row => Number.parseInt(row.missions, 10))
+    .map(row => Number.parseInt(String(row.missions), 10))
     .filter(value => Number.isFinite(value));
 
   if (values.length === 0) {
@@ -679,21 +1008,25 @@ function colorMissionCounts(rows) {
   const worst = Math.min(...values);
 
   return rows.map(row => {
-    const value = Number.parseInt(row.missions, 10);
-    if (!Number.isFinite(value)) return String(row.missions);
+    const value = Number.parseInt(String(row.missions), 10);
+    if (!Number.isFinite(value)) {return String(row.missions);}
     if (best === worst) {
-      return fmt.colorize(fmt.colors.green, String(row.missions));
+      return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.green), String(row.missions));
     }
     if (value === best) {
-      return fmt.colorize(fmt.colors.green, String(row.missions));
+      return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.green), String(row.missions));
     }
     if (value === worst) {
-      return fmt.colorize(fmt.colors.red, String(row.missions));
+      return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.red), String(row.missions));
     }
-    return fmt.colorize(fmt.colors.yellow, String(row.missions));
+    return fmt.colorize(/** @type {import('node:util').InspectColor} */(fmt.colors.yellow), String(row.missions));
   });
 }
 
+/**
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ */
 function formatStatsTable(headers, rows) {
   const headerRow = headers.map(header => fmt.bold(header));
   const renderedRows = rows.map(row => row.map((cell, index) => {
@@ -709,8 +1042,14 @@ function formatStatsTable(headers, rows) {
   });
 }
 
-function renderWeeklyStatsReport(rows, { today = new Date(), rootDir = null } = {}) {
-  const windows = buildWeeklyWindows(today);
+/**
+ * @param {StatsRow[]} rows
+ * @param {RenderWeeklyStatsReportOptions} options
+ */
+function renderWeeklyStatsReport(rows, options = {}) {
+  const today = options.today || new Date();
+  const rootDir = options.rootDir || null;
+  const windows = buildWeeklyWindows(/** @type{Date} */(typeof today === 'string' ? parseDateOnly(today) : today));
   const currentMissionStats = summarizeMissionWindow(rows, windows.current);
   const previousMissionStats = summarizeMissionWindow(rows, windows.previous);
   const currentAgentStats = summarizeAgentWindow(rows, windows.current, { rootDir });
@@ -751,7 +1090,14 @@ function renderWeeklyStatsReport(rows, { today = new Date(), rootDir = null } =
   return lines.join('\n');
 }
 
-function renderRangeStatsReport(rows, { from, to, rootDir = null } = {}) {
+/**
+ * @param {StatsRow[]} rows
+ * @param {RenderRangeStatsReportOptions} options
+ */
+function renderRangeStatsReport(rows, options = {}) {
+  const from = options.from;
+  const to = options.to;
+  const rootDir = options.rootDir || null;
   const window = createRangeWindow({ from, to });
   const missionStats = summarizeMissionWindow(rows, window);
   const agentStats = summarizeAgentWindow(rows, window, { rootDir });
@@ -796,9 +1142,16 @@ const MISSION_PHASE_ORDER = [
  * a pure function of the supplied rows — re-running with the same stored rows
  * produces identical text.
  */
+/**
+ * @param {StatsRow[]} rows
+ * @param {string} slug
+ * @param {StatsOptions} options
+ */
 function renderMissionPhaseReport(rows, slug, options = {}) {
   const wanted = String(slug || '').trim().toLowerCase();
-  const wantedRepo = String(options.repo || resolveStatsRepoName(options.rootDir)).trim();
+  /** @type {StatsOptions} */
+  const opts = options;
+  const wantedRepo = String(opts.repo || resolveStatsRepoName(opts.rootDir)).trim();
   const missionRows = (rows || []).filter(row =>
     String(row.mission || '').trim().toLowerCase() === wanted &&
     String(row.repo || '').trim() === wantedRepo
@@ -807,12 +1160,12 @@ function renderMissionPhaseReport(rows, slug, options = {}) {
   const byStage = new Map();
   for (const row of missionRows) {
     const stage = String(row.stage || 'default').trim().toLowerCase() || 'default';
-    if (!byStage.has(stage)) byStage.set(stage, []);
+    if (!byStage.has(stage)) {byStage.set(stage, []);}
     byStage.get(stage).push(row);
   }
 
   for (const stageRows of byStage.values()) {
-    stageRows.sort((a, b) =>
+    stageRows.sort((/** @type{StatsRow} */ a, /** @type{StatsRow} */ b) =>
       statsRowActorKey(a).localeCompare(statsRowActorKey(b))
       || String(a.provider || '').localeCompare(String(b.provider || ''))
       || String(a.model || '').localeCompare(String(b.model || ''))
@@ -841,13 +1194,13 @@ function renderMissionPhaseReport(rows, slug, options = {}) {
     return lines.join('\n');
   }
 
-  const num = (row, key) => String(Number.parseInt(row[key], 10) || 0);
+  const num = (/** @type{StatsRow} */ row, /** @type{string} */ key) => String(Number.parseInt(String(row[key]), 10) || 0);
   // cost_usd is a fractional dollar value; parseInt would truncate (e.g.
   // 1.42 -> "1", 0.46 -> "0"), silently discarding sub-dollar costs. Format
   // as a rounded decimal, collapsing exact zeros to "0".
-  const cost = (value) => {
-    const n = Number.parseFloat(value);
-    if (!Number.isFinite(n) || n === 0) return '0';
+  const cost = (/** @type {string | number} */ value) => {
+    const n = Number.parseFloat(String(value));
+    if (!Number.isFinite(n) || n === 0) {return '0';}
     return String(Math.round(n * 100) / 100);
   };
   const tableRows = [];
@@ -876,7 +1229,7 @@ function renderMissionPhaseReport(rows, slug, options = {}) {
             ? (row.reviewer_agent || row.implementer_agent || row.implementer || '')
             : (row.implementer_agent || row.implementer || ''));
           const actorLower = displayActor.trim().toLowerCase();
-          if (actorLower === 'claude') return '—';
+          if (actorLower === 'claude') {return '—';}
           return (row.provider && row.provider.toLowerCase() === 'openai')
             ? num(row, 'openai_usage_after')
             : '—';
@@ -887,7 +1240,7 @@ function renderMissionPhaseReport(rows, slug, options = {}) {
   }
 
   const totals = ['input_tokens', 'output_tokens', 'cached_tokens', 'tool_calls', 'duration_minutes']
-    .map(key => missionRows.reduce((sum, row) => sum + (Number.parseInt(row[key], 10) || 0), 0));
+    .map(key => missionRows.reduce((sum, row) => sum + (Number.parseInt(String(row[key]), 10) || 0), 0));
   // Compute total cost from rounded individual costs so the total equals
   // the sum of displayed phase costs (avoids floating-point rounding drift).
   const totalCost = tableRows
@@ -902,8 +1255,11 @@ function renderMissionPhaseReport(rows, slug, options = {}) {
   return lines.join('\n');
 }
 
+/**
+ * @param {string} taskFilePath
+ */
 function deriveFixRoundsFromTaskText(taskFilePath) {
-  if (!taskFilePath || !fs.existsSync(taskFilePath)) return 0;
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return 0;}
   const content = fs.readFileSync(taskFilePath, 'utf8');
   const patterns = [
     /Review round\s+(\d+)/gi,
@@ -921,6 +1277,12 @@ function deriveFixRoundsFromTaskText(taskFilePath) {
   return Math.max(0, maxRound - 1);
 }
 
+/**
+ * @param {string} slug
+ * @param {string} finalImplementer
+ * @param {string} latestRound
+ * @param {string} [rootDir]
+ */
 function deriveFixRoundsFromReviewStateHistory(slug, finalImplementer, latestRound, rootDir = process.cwd()) {
   const normalizedImplementer = normalizeImplementer(finalImplementer);
   const round = Number.parseInt(latestRound, 10) || 1;
@@ -940,7 +1302,7 @@ function deriveFixRoundsFromReviewStateHistory(slug, finalImplementer, latestRou
   // The implementer sits on the right of the `->`. Match the earliest reviewing
   // round whose implementer is the final implementer. (An older format placed the
   // implementer inside the phase parens, e.g. `(reviewing <impl>)`; accept both.)
-  const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const esc = (/** @type{string} */ s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const reviewStatePattern = new RegExp(
     `^review-state\\(${esc(slug)}\\):\\s*round\\s+(\\d+)\\s+\\(reviewing[^)]*\\)\\s*\\[[^\\]]*->\\s*${esc(normalizedImplementer)}\\b`,
     'i'
@@ -953,7 +1315,7 @@ function deriveFixRoundsFromReviewStateHistory(slug, finalImplementer, latestRou
   for (const line of result.stdout.split('\n')) {
     const trimmed = line.trim();
     const match = trimmed.match(reviewStatePattern) || trimmed.match(legacyPattern);
-    if (!match) continue;
+    if (!match) {continue;}
     const candidateRound = Number.parseInt(match[1], 10);
     if (Number.isInteger(candidateRound) && candidateRound > 0) {
       firstFinalImplementerRound = candidateRound;
@@ -968,8 +1330,12 @@ function deriveFixRoundsFromReviewStateHistory(slug, finalImplementer, latestRou
   return Math.max(0, round - firstFinalImplementerRound);
 }
 
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ */
 function deriveFinalImplementerFromBranchHistory(slug, rootDir = process.cwd()) {
-  if (!slug) return null;
+  if (!slug) {return null;}
 
   const branches = [`mission/${slug}`, `origin/mission/${slug}`];
   for (const branch of branches) {
@@ -985,7 +1351,7 @@ function deriveFinalImplementerFromBranchHistory(slug, rootDir = process.cwd())
 
     for (const line of result.stdout.split('\n')) {
       const match = line.trim().match(activeImplementerPattern);
-      if (!match) continue;
+      if (!match) {continue;}
       const implementer = normalizeImplementer(match[1]);
       if (implementer) {
         return implementer;
@@ -996,15 +1362,19 @@ function deriveFinalImplementerFromBranchHistory(slug, rootDir = process.cwd())
   return null;
 }
 
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ */
 function deriveImplementerAndFixRoundsFromPrComments(slug, rootDir = process.cwd()) {
-  if (!slug) return null;
+  if (!slug) {return null;}
 
   // Only attempt Forgejo PR comment lookup when Forgejo review is enabled
-  if (!isForgejoReviewEnabled(rootDir)) return null;
+  if (!isForgejoReviewEnabled(rootDir)) {return null;}
 
   const forgejo = require('../tools/forgejo');
-  const token = forgejo.readToken(forgejo.resolveForgejoUser());
-  if (!token) return null;
+  const token = forgejo.readToken(/** @type{string} */(forgejo.resolveForgejoUser()));
+  if (!token) {return null;}
 
   const comments = forgejo.getCommentsSync(`mission/${slug}`, token);
   if (!Array.isArray(comments) || comments.length === 0) {
@@ -1012,7 +1382,7 @@ function deriveImplementerAndFixRoundsFromPrComments(slug, rootDir = process.cwd
   }
 
   const resolutionPattern = /^(?:#|##|###)\s*(?:Review\s+(?:Round|Attempt)\s+\d+\s+Resolution\b|Review\s+Follow-up\s+Resolution\b|Round\s+\d+\s+Resolution(?:\s+Summary)?\b|Round\s+resolution\b|Task-\d+\s+[—-]\s+Act-on-Review Round Resolution\b)/i;
-  const isResolutionComment = comment => comment.kind === 'issue-comment'
+  const isResolutionComment = (/** @type{*} */ comment) => comment.kind === 'issue-comment'
     && normalizeImplementer(comment.user)
     && resolutionPattern.test(String(comment.body || '').trim());
   const resolutionComments = comments
@@ -1087,20 +1457,24 @@ function deriveImplementerAndFixRoundsFromPrComments(slug, rootDir = process.cwd
  * Returns `{ implementer, prFixRounds, source: 'review-events' }` or null when no
  * usable round events exist.
  */
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ */
 function deriveFixRoundsFromReviewEvents(slug, rootDir = process.cwd()) {
-  if (!slug) return null;
+  if (!slug) {return null;}
   let events;
   try {
     // Guard against reading (and, as a side effect, creating) an events dir that
     // doesn't exist yet — this runs on every active-stage recording.
     const { findMissionDir } = require('../core/mission-utils');
     const missionDir = findMissionDir(slug, rootDir);
-    if (!missionDir || !fs.existsSync(path.join(missionDir, 'review-events'))) return null;
-    events = reviewEvents.readAllEvents(slug, { rootDir, log: () => {}, error: () => {} });
-  } catch (_) {
+    if (!missionDir || !fs.existsSync(path.join(missionDir, 'review-events'))) {return null;}
+    events = reviewEvents.readAllEvents(slug, /** @type{any} */({ rootDir, log: () => {}, error: () => {} }));
+  } catch (/** @type{any} */ _err) {
     return null;
   }
-  if (!Array.isArray(events) || events.length === 0) return null;
+  if (!Array.isArray(events) || events.length === 0) {return null;}
 
   // Collapse events into per-round facts: did the reviewer request changes, and
   // which implementer OWNED the round. A round can contain a mid-round handoff
@@ -1111,8 +1485,8 @@ function deriveFixRoundsFromReviewEvents(slug, rootDir = process.cwd()) {
   const rounds = new Map();
   for (const event of events) {
     const round = Number.parseInt(event.round, 10);
-    if (!Number.isInteger(round) || round <= 0) continue;
-    if (!rounds.has(round)) rounds.set(round, { requestedChanges: false, implementer: null, implementerTs: '' });
+    if (!Number.isInteger(round) || round <= 0) {continue;}
+    if (!rounds.has(round)) {rounds.set(round, { requestedChanges: false, implementer: null, implementerTs: '' });}
     const entry = rounds.get(round);
     if (event.event_type === reviewEvents.VALID_EVENT_TYPES.REVIEWER_OUTCOME
       && String(event.verdict || '').toLowerCase() === 'request-changes') {
@@ -1128,7 +1502,7 @@ function deriveFixRoundsFromReviewEvents(slug, rootDir = process.cwd()) {
       }
     }
   }
-  if (rounds.size === 0) return null;
+  if (rounds.size === 0) {return null;}
 
   // Final implementer = implementer of the highest-numbered round that names one.
   let finalImplementer = null;
@@ -1141,7 +1515,7 @@ function deriveFixRoundsFromReviewEvents(slug, rootDir = process.cwd()) {
   // rounds when no implementer could be attributed).
   let prFixRounds = 0;
   for (const [, entry] of rounds) {
-    if (!entry.requestedChanges) continue;
+    if (!entry.requestedChanges) {continue;}
     if (!finalImplementer || !entry.implementer || entry.implementer === finalImplementer) {
       prFixRounds += 1;
     }
@@ -1150,6 +1524,10 @@ function deriveFixRoundsFromReviewEvents(slug, rootDir = process.cwd()) {
   return { implementer: finalImplementer, prFixRounds, source: 'review-events' };
 }
 
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ */
 function deriveImplementerAndFixRounds(slug, rootDir = process.cwd()) {
   const reviewState = readReviewState(slug, rootDir);
 
@@ -1176,7 +1554,7 @@ function deriveImplementerAndFixRounds(slug, rootDir = process.cwd()) {
   if (historyImplementer) {
     return {
       implementer: historyImplementer,
-      prFixRounds: deriveFixRoundsFromReviewStateHistory(slug, historyImplementer, reviewState?.round, rootDir),
+      prFixRounds: deriveFixRoundsFromReviewStateHistory(slug, historyImplementer, String(/** @type {any} */ (reviewState)?.round ?? ''), rootDir),
       source: 'branch-history',
     };
   }
@@ -1185,17 +1563,20 @@ function deriveImplementerAndFixRounds(slug, rootDir = process.cwd()) {
     const implementer = normalizeImplementer(reviewState.implementer);
     return {
       implementer,
-      prFixRounds: deriveFixRoundsFromReviewStateHistory(slug, implementer, reviewState.round, rootDir),
+      // @ts-expect-error reviewState.round may be null
+      prFixRounds: deriveFixRoundsFromReviewStateHistory(slug, implementer, String(/** @type {any} */ (reviewState)?.round ?? '') || '', rootDir),
       source: 'review-state',
     };
   }
 
   const resolution = resolveTaskFile(slug, rootDir);
   if (resolution.ok) {
-    const implementer = normalizeImplementer(getTaskImplementer(resolution.taskFile) || getTaskAssignee(resolution.taskFile));
+    // @ts-expect-error resolution.taskFile may be undefined
+    const implementer = normalizeImplementer(getTaskImplementer(resolution.taskFile) || getTaskAssignee(resolution.taskFile) || '');
     if (implementer) {
       return {
         implementer,
+        // @ts-expect-error resolution.taskFile may be undefined
         prFixRounds: deriveFixRoundsFromTaskText(resolution.taskFile),
         source: 'backlog-fallback',
       };
@@ -1209,6 +1590,10 @@ function deriveImplementerAndFixRounds(slug, rootDir = process.cwd()) {
   };
 }
 
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ */
 function resolveMissionClassification(slug, rootDir = process.cwd()) {
   const resolution = resolveTaskFile(slug, rootDir);
   if (!resolution.ok) {
@@ -1219,7 +1604,8 @@ function resolveMissionClassification(slug, rootDir = process.cwd()) {
     };
   }
 
-  const classification = normalizeClassification(getTaskClassification(resolution.taskFile));
+  // @ts-expect-error resolution.taskFile may be undefined
+  const classification = normalizeClassification(getTaskClassification(resolution.taskFile) || '');
   if (!classification) {
     return {
       classification: null,
@@ -1234,30 +1620,45 @@ function resolveMissionClassification(slug, rootDir = process.cwd()) {
   };
 }
 
+/**
+ * @param {StatsRow} row
+ * @param {{normalizeImplementer?: boolean, normalizeClassification?: boolean, rootDir?: string}} options
+ */
 function canonicalizeStatsRow(row, options = {}) {
   const normalized = normalizeStatsRow(row, options);
+  /** @type {StatsRow} */
   const canonical = {
     ...normalized,
-    date: formatDateOnly(parseToday(row.date)),
+    date: formatDateOnly(parseToday(String(row.date))),
     repo: String(normalized.repo || resolveStatsRepoName(options.rootDir)).trim(),
     mission: String(row.mission).trim().toLowerCase(),
-    classification: normalizeClassification(row.classification),
-    implementer: normalizeImplementer(row.implementer),
+    classification: /** @type{string|number|boolean|undefined} */(normalizeClassification(row.classification)),
+    implementer: /** @type{string|number|boolean|undefined} */(normalizeImplementer(row.implementer)),
     stage: String(row.stage || '').trim().toLowerCase() || 'default',
   };
   for (const key of USAGE_NUMBERS) {
-    canonical[key] = String(Math.max(0, Number.parseInt(normalized[key], 10) || 0));
+    canonical[key] = String(Math.max(0, Number.parseInt(String(/** @type{any} */(normalized)[key]), 10) || 0));
   }
   return canonical;
 }
 
+/**
+ * @param {StatsRow} a
+ * @param {StatsRow} b
+ */
 function rowsEqual(a, b) {
   return STATS_HEADERS.every(header => String(a[header] || '') === String(b[header] || ''));
 }
 
+/**
+ * @param {StatsRow} row
+ * @param {UpsertStatsRowOptions} options
+ */
 function upsertStatsRow(row, options = {}) {
-  const filePath = options.filePath || resolveStatsPath({ ensureDir: true });
-  const canonicalRow = canonicalizeStatsRow(row, { rootDir: options.rootDir });
+  /** @type {UpsertStatsRowOptions} */
+  const opts = options;
+  const filePath = opts.filePath || resolveStatsPath({ ensureDir: true });
+  const canonicalRow = canonicalizeStatsRow(row, /** @type {any} */ ({ rootDir: opts.rootDir }));
   if (!canonicalRow.classification) {
     throw new Error(`Invalid classification for ${canonicalRow.mission}.`);
   }
@@ -1265,7 +1666,7 @@ function upsertStatsRow(row, options = {}) {
     throw new Error(`Invalid implementer for ${canonicalRow.mission}.`);
   }
 
-  const data = loadStatsCsv(filePath, { rootDir: options.rootDir });
+  const data = loadStatsCsv(filePath, { rootDir: opts.rootDir });
   const existingIndex = data.rows.findIndex(existing =>
     existing.repo === canonicalRow.repo &&
     existing.mission === canonicalRow.mission &&
@@ -1275,17 +1676,19 @@ function upsertStatsRow(row, options = {}) {
   let changed = false;
 
   if (existingIndex === -1) {
+    // @ts-expect-error canonicalRow type mismatch
     data.rows.push(canonicalRow);
     changed = true;
   } else if (!rowsEqual(data.rows[existingIndex], canonicalRow)) {
-    data.rows[existingIndex] = canonicalRow;
+      // @ts-expect-error canonicalRow type mismatch
+      data.rows[existingIndex] = canonicalRow;
     changed = true;
   }
 
   data.rows.sort((a, b) =>
-    a.date.localeCompare(b.date) ||
+    String(a.date).localeCompare(String(b.date)) ||
     String(a.repo || '').localeCompare(String(b.repo || '')) ||
-    a.mission.localeCompare(b.mission) ||
+    String(a.mission).localeCompare(String(b.mission)) ||
     String(a.stage || 'default').localeCompare(String(b.stage || 'default'))
   );
   if (changed) {
@@ -1295,12 +1698,14 @@ function upsertStatsRow(row, options = {}) {
   return { changed, row: canonicalRow, data };
 }
 
-function recordIntegrationStats({
-  slug,
-  rootDir = process.cwd(),
-  filePath = resolveStatsPath({ rootDir, forWrite: true }),
-  date = formatDateOnly(new Date()),
-} = {}) {
+/**
+ * @param {RecordIntegrationStatsOptions} options
+ */
+// @ts-expect-error recordIntegrationStats options missing slug
+function recordIntegrationStats(options = {}) {
+  /** @type {RecordIntegrationStatsOptions} */
+  const opts = options;
+  const { slug, rootDir = process.cwd(), filePath = resolveStatsPath({ rootDir, forWrite: true }), date = formatDateOnly(new Date()) } = opts;
   if (!slug) {
     throw new Error('recordIntegrationStats requires a mission slug.');
   }
@@ -1348,7 +1753,13 @@ function recordIntegrationStats({
  * before/after/delta attribution is deferred to the follow-up mission that adds
  * the regression model.
  */
-function telemetryToStatsFields(telemetry, { agentFamily, durationMinutes = 0, model } = {}) {
+/**
+ * @param {*} telemetry
+ * @param {TelemetryToStatsOptions} options
+ */
+// @ts-expect-error telemetryToStatsFields options missing agentFamily
+function telemetryToStatsFields(telemetry, options = {}) {
+  const { agentFamily, durationMinutes = 0, model } = options;
   const t = telemetry || null;
   const usageAfter = t && typeof t.usagePercent === 'number' ? Math.round(t.usagePercent) : 0;
   return {
@@ -1367,6 +1778,10 @@ function telemetryToStatsFields(telemetry, { agentFamily, durationMinutes = 0, m
   };
 }
 
+/**
+ * @param {StatsRow} a
+ * @param {StatsRow} b
+ */
 function sameStatsIdentity(a, b) {
   return a.repo === b.repo
     && a.mission === b.mission
@@ -1374,25 +1789,40 @@ function sameStatsIdentity(a, b) {
     && statsRowActorKey(a) === statsRowActorKey(b);
 }
 
-function accumulateIntegerStrings(existing, incoming, { mode = 'sum' } = {}) {
+/**
+ * @param {string} existing
+ * @param {string} incoming
+ * @param {AccModeOptions} [options]
+ */
+function accumulateIntegerStrings(existing, incoming, options = {}) {
+  /** @type {AccModeOptions} */
+  const opts = options;
   const current = Number.parseInt(existing, 10) || 0;
   const next = Number.parseInt(incoming, 10) || 0;
-  if (mode === 'max') return String(Math.max(current, next));
-  if (mode === 'replace') return String(next);
+  if (opts.mode === 'max') {return String(Math.max(current, next));}
+  if (opts.mode === 'replace') {return String(next);}
   return String(current + next);
 }
 
+/**
+ * @param {string} existing
+ * @param {string} incoming
+ */
 function accumulateDecimalStrings(existing, incoming) {
   const current = Number.parseFloat(existing) || 0;
   const next = Number.parseFloat(incoming) || 0;
   return String(current + next);
 }
 
+/**
+ * @param {string} existing
+ * @param {string} incoming
+ */
 function mergeLabel(existing, incoming) {
   const a = String(existing || '').trim();
   const b = String(incoming || '').trim();
-  if (!a) return b;
-  if (!b) return a;
+  if (!a) {return b;}
+  if (!b) {return a;}
   return a === b ? a : 'mixed';
 }
 
@@ -1400,22 +1830,17 @@ function mergeLabel(existing, incoming) {
  * Record one stage row (draft/active/review/...) keyed by (repo, mission, stage).
  * Shared by the draft launcher and the review-loop hooks. Token columns come
  * from `telemetry` when supplied, else honest zeros.
+  */
+/**
+ * @param {RecordStageStatsOptions} options
  */
-function recordStageStats({
-  slug,
-  stage,
-  rootDir = process.cwd(),
-  filePath = resolveStatsPath({ rootDir, forWrite: true }),
-  date = formatDateOnly(new Date()),
-  implementer,
-  reviewer = '',
-  prFixRounds = '0',
-  telemetry = null,
-  durationMinutes = 0,
-  model = null,
-} = {}) {
-  if (!slug) throw new Error('recordStageStats requires a mission slug.');
-  if (!stage) throw new Error('recordStageStats requires a stage.');
+// @ts-expect-error recordStageStats options missing slug/stage
+function recordStageStats(options = {}) {
+  /** @type {any} */
+  const opts = options;
+  const { slug, stage, rootDir = process.cwd(), filePath = resolveStatsPath({ rootDir, forWrite: true }), date = formatDateOnly(new Date()), implementer, reviewer = '', prFixRounds = '0', telemetry = null, durationMinutes = 0, model = null } = opts;
+  if (!slug) {throw new Error('recordStageStats requires a mission slug.');}
+  if (!stage) {throw new Error('recordStageStats requires a stage.');}
 
   const { classification, error: classificationError } = resolveMissionClassification(slug, rootDir);
   if (!classification) {
@@ -1436,21 +1861,13 @@ function recordStageStats({
   }, { filePath, rootDir });
 }
 
-function accumulateStageStats({
-  slug,
-  stage,
-  rootDir = process.cwd(),
-  filePath = resolveStatsPath({ rootDir, forWrite: true }),
-  date = formatDateOnly(new Date()),
-  implementer,
-  reviewer = '',
-  prFixRounds = '0',
-  telemetry = null,
-  durationMinutes = 0,
-  model = null,
-} = {}) {
-  if (!slug) throw new Error('accumulateStageStats requires a mission slug.');
-  if (!stage) throw new Error('accumulateStageStats requires a stage.');
+/**
+ * @param {{slug: string, stage: string, rootDir?: string, filePath?: string, date?: string, implementer?: string, reviewer?: string, prFixRounds?: string, telemetry?: {provider?: string, model?: string, inputTokens?: number, outputTokens?: number, cachedTokens?: number, totalTokens?: number, toolCalls?: number, usagePercent?: number, cost_usd?: number} | null, durationMinutes?: number, model?: string}} options
+ */
+function accumulateStageStats(/** @type {{slug: string, stage: string, rootDir?: string, filePath?: string, date?: string, implementer?: string, reviewer?: string, prFixRounds?: string, telemetry?: {provider?: string, model?: string, inputTokens?: number, outputTokens?: number, cachedTokens?: number, totalTokens?: number, toolCalls?: number, usagePercent?: number, cost_usd?: number} | null, durationMinutes?: number, model?: string}} */ options) {
+  const { slug, stage, rootDir = process.cwd(), filePath = resolveStatsPath({ rootDir, forWrite: true }), date = formatDateOnly(new Date()), implementer, reviewer = '', prFixRounds = '0', telemetry = null, durationMinutes = 0, model = null } = options;
+  if (!slug) {throw new Error('accumulateStageStats requires a mission slug.');}
+  if (!stage) {throw new Error('accumulateStageStats requires a stage.');}
 
   const { classification, error: classificationError } = resolveMissionClassification(slug, rootDir);
   if (!classification) {
@@ -1466,7 +1883,7 @@ function accumulateStageStats({
     implementer_agent: implementer || '',
     reviewer_agent: reviewer || '',
     stage,
-    ...telemetryToStatsFields(telemetry, { agentFamily, durationMinutes, model }),
+    ...telemetryToStatsFields(telemetry, { agentFamily, durationMinutes, model: model || undefined }),
   }, { rootDir });
 
   const data = loadStatsCsv(filePath, { rootDir });
@@ -1483,18 +1900,18 @@ function accumulateStageStats({
     pr_fix_rounds: incomingRow.pr_fix_rounds,
     implementer_agent: incomingRow.implementer_agent,
     reviewer_agent: incomingRow.reviewer_agent,
-    provider: mergeLabel(existing.provider, incomingRow.provider),
-    model: mergeLabel(existing.model, incomingRow.model),
-    input_tokens: accumulateIntegerStrings(existing.input_tokens, incomingRow.input_tokens),
-    output_tokens: accumulateIntegerStrings(existing.output_tokens, incomingRow.output_tokens),
-    cached_tokens: accumulateIntegerStrings(existing.cached_tokens, incomingRow.cached_tokens),
-    context_tokens: accumulateIntegerStrings(existing.context_tokens, incomingRow.context_tokens),
-    tool_calls: accumulateIntegerStrings(existing.tool_calls, incomingRow.tool_calls),
-    openai_usage_before: accumulateIntegerStrings(existing.openai_usage_before, incomingRow.openai_usage_before, { mode: 'replace' }),
-    openai_usage_after: accumulateIntegerStrings(existing.openai_usage_after, incomingRow.openai_usage_after, { mode: 'max' }),
-    openai_usage_delta: accumulateIntegerStrings(existing.openai_usage_delta, incomingRow.openai_usage_delta),
-    duration_minutes: accumulateIntegerStrings(existing.duration_minutes, incomingRow.duration_minutes),
-    cost_usd: accumulateDecimalStrings(existing.cost_usd, incomingRow.cost_usd),
+    provider: mergeLabel(String(existing.provider), String(incomingRow.provider)),
+    model: mergeLabel(String(existing.model), String(incomingRow.model)),
+    input_tokens: accumulateIntegerStrings(String(existing.input_tokens), String(incomingRow.input_tokens)),
+    output_tokens: accumulateIntegerStrings(String(existing.output_tokens), String(incomingRow.output_tokens)),
+    cached_tokens: accumulateIntegerStrings(String(existing.cached_tokens), String(incomingRow.cached_tokens)),
+    context_tokens: accumulateIntegerStrings(String(existing.context_tokens), String(incomingRow.context_tokens)),
+    tool_calls: accumulateIntegerStrings(String(existing.tool_calls), String(incomingRow.tool_calls)),
+    openai_usage_before: accumulateIntegerStrings(String(existing.openai_usage_before), String(incomingRow.openai_usage_before), { mode: 'replace' }),
+    openai_usage_after: accumulateIntegerStrings(String(existing.openai_usage_after), String(incomingRow.openai_usage_after), { mode: 'max' }),
+    openai_usage_delta: accumulateIntegerStrings(String(existing.openai_usage_delta), String(incomingRow.openai_usage_delta)),
+    duration_minutes: accumulateIntegerStrings(String(existing.duration_minutes), String(incomingRow.duration_minutes)),
+    cost_usd: accumulateDecimalStrings(String(existing.cost_usd), String(incomingRow.cost_usd)),
   };
 
   return upsertStatsRow(mergedRow, { filePath, rootDir });
@@ -1508,14 +1925,26 @@ function accumulateStageStats({
  * progresses; the final round's row then carries the true count even if the
  * mission is never integrated. The weekly summary reads it back per mission.
  */
+/**
+ * @param {string} slug
+ * @param {string} rootDir
+ * @param {string|null|undefined} provided
+ */
 function defaultPrFixRounds(slug, rootDir, provided) {
-  if (provided !== undefined && provided !== null) return provided;
-  if (!slug) return '0';
+  if (provided !== undefined && provided !== null) {return provided;}
+  if (!slug) {return '0';}
   const derived = deriveFixRoundsFromReviewEvents(slug, rootDir);
   return derived ? String(derived.prFixRounds) : '0';
 }
 
-function recordActiveStats({ stage = 'active', slug, rootDir = process.cwd(), prFixRounds, model, ...rest } = {}) {
+/**
+ * @param {RecordActiveStatsOptions} options
+ */
+// @ts-expect-error recordActiveStats options missing slug
+function recordActiveStats(options = {}) {
+  /** @type {any} */
+  const opts = options;
+  const { stage = 'active', slug, rootDir = process.cwd(), prFixRounds, model, ...rest } = opts;
   return recordStageStats({
     stage, slug, rootDir, model,
     prFixRounds: defaultPrFixRounds(slug, rootDir, prFixRounds),
@@ -1523,7 +1952,14 @@ function recordActiveStats({ stage = 'active', slug, rootDir = process.cwd(), pr
   });
 }
 
-function recordReviewStats({ stage = 'review', slug, rootDir = process.cwd(), reviewer, implementer, prFixRounds, model, ...rest } = {}) {
+/**
+ * @param {RecordReviewStatsOptions} options
+ */
+// @ts-expect-error recordReviewStats options missing slug
+function recordReviewStats(options = {}) {
+  /** @type {any} */
+  const opts = options;
+  const { stage = 'review', slug, rootDir = process.cwd(), reviewer, implementer, prFixRounds, model, ...rest } = opts;
   // A review row's TOKENS belong to the reviewer (telemetry is the reviewer's
   // session), but the row stays keyed to the MISSION'S implementer so the weekly
   // per-implementer summary counts the mission under whoever implemented it — not
@@ -1537,10 +1973,16 @@ function recordReviewStats({ stage = 'review', slug, rootDir = process.cwd(), re
   });
 }
 
+/**
+ * @param {CsvData} data
+ */
 function isIntegrationStatsDataset(data) {
   return LEGACY_HEADERS.every(header => data.headers.includes(header));
 }
 
+/**
+ * @param {Function} [log]
+ */
 function printStatsUsage(log = fmt.log.plain) {
   log(`Usage: px stats [<csv_file>|--csv-file <path>] [--today YYYY-MM-DD] [--from YYYY-MM-DD --to YYYY-MM-DD] [--output <file>] [--group-by implementer|period|merged]
 
@@ -1564,11 +2006,17 @@ Notes:
   - Legacy retrospective CSVs still render the markdown report.`);
 }
 
+/**
+ * @param {string[]} args
+ * @param {StatsCmdOptions} options
+ */
 function stats(args, options = {}) {
-  const log = options.log || fmt.log.plain;
-  const error = options.error || fmt.log.plainError;
-  const exit = options.exit || process.exit;
-  const rootDir = options.rootDir || process.cwd();
+  /** @type {StatsCmdOptions} */
+  const opts = options;
+  const log = opts.log || fmt.log.plain;
+  const error = opts.error || fmt.log.plainError;
+  const exit = opts.exit || process.exit;
+  const rootDir = opts.rootDir || process.cwd();
 
   if (args.includes('--help') || args.includes('-h')) {
     printStatsUsage(log);
@@ -1602,6 +2050,7 @@ function stats(args, options = {}) {
       continue;
     }
     if (arg === '--today' && i + 1 < args.length) {
+      // @ts-expect-error today is parsed as string but typed as Date
       today = args[i + 1];
       i += 1;
       continue;
@@ -1676,12 +2125,12 @@ function stats(args, options = {}) {
     if (isIntegrationStatsDataset(data)) {
       const rows = loadStatsCsv(inputFile, { rootDir }).rows;
       report = from !== null || to !== null
-        ? renderRangeStatsReport(rows, { from, to, rootDir })
+        ? renderRangeStatsReport(rows, { from: from || undefined, to: to || undefined, rootDir })
         : renderWeeklyStatsReport(rows, { today, rootDir });
     } else {
       report = generateMarkdownReport(data, { groupBy: groupByField });
     }
-  } catch (err) {
+  } catch (/** @type{any} */ err) {
     error(fmt.status('FAIL', err.message));
     exit(1);
     return;