atris 3.50.0 → 3.52.0

package/bin/atris.js

@@ -572,7 +572,7 @@ function showHelp() {
   console.log('  router     - inspect ax lane outcomes and promote gated reflex overrides');
   console.log('  sign       - Co-author trailer on every commit in an atris workspace (on/off/status)');
   console.log('  visualize  - Generate a Slack/deck-ready visual from a prompt');
-  console.log('  youtube    - Free local notes or 5-credit cloud process for YouTube videos');
+  console.log('  youtube    - Free local notes, weekly digest, or 5-credit cloud process for YouTube videos');
   console.log('');
   console.log('Experiments:');
   console.log('  experiments init [slug]     - Prepare atris/experiments/ or scaffold a pack');

package/commands/youtube.js

@@ -5,8 +5,9 @@ const fs = require('fs');
 const path = require('path');
 const https = require('https');
 
-const YTNOTES_USAGE = 'usage: ytnotes <youtube-url> [haiku|atris-fast|gemini|grok|codex|cursor]';
+const YTNOTES_USAGE = 'usage: ytnotes <youtube-url> [youtube-url-or-playlist...] [haiku|atris-fast|gemini|grok|codex|cursor]';
 const YTNOTES_HINT = 'zero credits, local captions + a fast engine';
+const NOTES_PLAYLIST_CAP = 10;
 
 const DEFAULT_QUERY = [
   'Create a timestamped YouTube brief for Atris.',
@@ -24,15 +25,18 @@ const ALLOWED_CAPTION_HOST_SUFFIXES = [
 
 function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('');
-  output(`Usage: ${commandName} notes <youtube-url> [engine]`);
+  output(`Usage: ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine]`);
   output(`       ${commandName} process <youtube-url> [options]`);
+  output(`       ${commandName} digest [--days N]`);
   output(`       ${commandName} watch add <channel-url-or-@handle>`);
   output(`       ${commandName} watch list`);
   output(`       ${commandName} watch remove <number>`);
   output(`       ${commandName} watch tick`);
   output(`       ${commandName} <youtube-url> [options]`);
   output('');
-  output('notes = free local notes, process = 5 credits cloud knowledge');
+  output('notes = free local notes for one url, several urls, or a playlist');
+  output('process = 5 credits cloud knowledge');
+  output('digest = one decision page from this week\'s video briefs');
   output('watch = subscribed channels turn into briefs without a human');
   output('Process a YouTube video through Atris using timestamped transcript-first analysis.');
   output('Falls back to cloud video processing when local captions are unavailable.');
@@ -50,8 +54,12 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('');
   output('Examples:');
   output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID`);
+  output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID https://youtu.be/OTHER_ID`);
+  output(`  ${commandName} notes https://www.youtube.com/playlist?list=PLAYLIST_ID`);
   output(`  ${commandName} https://www.youtube.com/watch?v=VIDEO_ID`);
   output(`  ${commandName} process https://youtu.be/VIDEO_ID --query "Key takeaways"`);
+  output(`  ${commandName} digest`);
+  output(`  ${commandName} digest --days 14`);
   output(`  ${commandName} watch add @veritasium`);
   output(`  ${commandName} watch tick`);
   output('');
@@ -460,6 +468,34 @@ function videoIdFromUrl(url) {
   return short ? short[1] : null;
 }
 
+function looksLikeYoutubeUrl(arg) {
+  const text = String(arg || '').trim();
+  if (!text || text.startsWith('-')) return false;
+  return /youtube\.com|youtu\.be/i.test(text);
+}
+
+function isPlaylistUrl(url) {
+  const text = String(url || '');
+  return /[?&]list=/.test(text) || /\/playlist(?:\?|$|\/)/i.test(text);
+}
+
+function parseNotesArgs(argv = []) {
+  const urls = [];
+  let engine = null;
+  let help = false;
+  for (const raw of argv) {
+    const arg = String(raw);
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      help = true;
+      continue;
+    }
+    if (arg.startsWith('-')) continue;
+    if (looksLikeYoutubeUrl(arg)) urls.push(arg);
+    else engine = arg;
+  }
+  return { urls, engine, help };
+}
+
 function dateStamp(now) {
   if (typeof now === 'string' && /^\d{4}-\d{2}-\d{2}/.test(now)) {
     return now.slice(0, 10);
@@ -508,11 +544,207 @@ function fileBriefFromNotes({ cwd, url, workDir, now } = {}) {
     fs.writeFileSync(journalPath, `${existing}${prefix}${line}\n`);
 
     console.log(`brief filed: ${relBrief}`);
+    return relBrief;
   } catch {
     // notes filing must never break the youtube command
   }
 }
 
+const DIGEST_ENGINE_TIMEOUT_MS = 240000;
+const DEFAULT_DIGEST_DAYS = 7;
+
+function addUtcDays(stamp, delta) {
+  const [year, month, day] = String(stamp || '').split('-').map(Number);
+  const value = new Date(Date.UTC(year, month - 1, day + Number(delta || 0)));
+  return value.toISOString().slice(0, 10);
+}
+
+function parseBriefDate(text) {
+  const match = String(text || '').match(/^date:\s*(\d{4}-\d{2}-\d{2})\s*$/m);
+  return match ? match[1] : null;
+}
+
+function isVideoBriefText(text) {
+  return /^source:\s*http/m.test(String(text || ''));
+}
+
+function briefTitleLine(text) {
+  const heading = firstHeading(text);
+  if (heading) return heading;
+  const first = String(text || '').split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  return first || '';
+}
+
+function dateInDigestWindow(dateStr, now, days) {
+  if (!dateStr) return false;
+  const today = dateStamp(now);
+  const start = addUtcDays(today, -(Number(days) - 1));
+  return dateStr >= start && dateStr <= today;
+}
+
+function parseDigestArgs(argv = []) {
+  const args = [...argv];
+  const options = { help: false, days: DEFAULT_DIGEST_DAYS };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      options.help = true;
+    } else if (arg === '--days') {
+      const raw = args[i + 1];
+      const value = Number(raw);
+      if (raw == null || String(raw).startsWith('--') || !Number.isInteger(value) || value <= 0) {
+        throw new Error('--days must be a positive integer');
+      }
+      options.days = value;
+      i += 1;
+    } else if (arg.startsWith('--days=')) {
+      const value = Number(arg.slice('--days='.length));
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error('--days must be a positive integer');
+      }
+      options.days = value;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function collectVideoBriefs({ cwd, now, days } = {}) {
+  const root = cwd || process.cwd();
+  const briefsDir = path.join(root, 'atris', 'wiki', 'briefs');
+  if (!fs.existsSync(briefsDir)) return [];
+
+  const rows = [];
+  for (const name of fs.readdirSync(briefsDir).sort()) {
+    if (!name.endsWith('.md') || name.startsWith('digest-')) continue;
+    const abs = path.join(briefsDir, name);
+    let body = '';
+    try {
+      if (!fs.statSync(abs).isFile()) continue;
+      body = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!isVideoBriefText(body)) continue;
+    const date = parseBriefDate(body);
+    if (!dateInDigestWindow(date, now, days)) continue;
+    rows.push({
+      name,
+      relPath: `atris/wiki/briefs/${name}`,
+      title: briefTitleLine(body),
+      date,
+      body,
+    });
+  }
+  rows.sort((a, b) => (a.date === b.date ? a.name.localeCompare(b.name) : a.date.localeCompare(b.date)));
+  return rows;
+}
+
+function buildDigestPrompt(briefs = []) {
+  const blocks = briefs.map((row) => [
+    `filename: ${row.name}`,
+    `title: ${row.title}`,
+    `path: ${row.relPath}`,
+    '',
+    row.body,
+  ].join('\n'));
+  return [
+    'Turn these video briefs into one decision-focused page.',
+    'Write a heading exactly: # what this week\'s videos changed',
+    'Then 3-6 decision-shaped findings. Each finding must name the brief it came from as a path.',
+    'Then one contradictions or tensions paragraph if any exist.',
+    'Then a 3-item do next list.',
+    'Use plain prose. Do not use em dashes.',
+    '',
+    'Briefs:',
+    '',
+    blocks.join('\n\n'),
+  ].join('\n');
+}
+
+function defaultDigestRunner(prompt, deps = {}) {
+  const spawn = deps.spawnSync || spawnSync;
+  return spawn('claude', ['-p', prompt, '--model', 'claude-haiku-4-5'], {
+    encoding: 'utf8',
+    timeout: DIGEST_ENGINE_TIMEOUT_MS,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+}
+
+function invokeDigestEngine(prompt, deps = {}) {
+  const runner = deps.runner || ((nextPrompt) => defaultDigestRunner(nextPrompt, deps));
+  const result = runner(prompt, deps);
+  if (typeof result === 'string') return result.trim();
+  if (!result || result.error || (result.status != null && result.status !== 0)) {
+    const detail = String(result?.stderr || result?.error?.message || 'digest engine failed').trim();
+    throw new Error(detail || 'digest engine failed');
+  }
+  return String(result.stdout || '').trim();
+}
+
+function appendDigestJournal({ cwd, date, relDigest }) {
+  const year = date.slice(0, 4);
+  const journalPath = path.join(cwd, 'atris', 'logs', year, `${date}.md`);
+  fs.mkdirSync(path.dirname(journalPath), { recursive: true });
+  let existing = '';
+  if (fs.existsSync(journalPath)) existing = fs.readFileSync(journalPath, 'utf8');
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  const line = `- [claimable] digest: what this week's videos changed -> ${relDigest}`;
+  fs.writeFileSync(journalPath, `${existing}${prefix}${line}\n`);
+}
+
+function runYoutubeDigest(args = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  let options;
+  try {
+    options = parseDigestArgs(args);
+  } catch (err) {
+    output(err.message);
+    return 2;
+  }
+  if (options.help) {
+    showYoutubeHelp(output, deps.commandName || 'atris youtube');
+    return 0;
+  }
+
+  const cwd = deps.cwd || process.cwd();
+  const now = deps.now || new Date();
+  const briefs = collectVideoBriefs({ cwd, now, days: options.days });
+  if (!briefs.length) {
+    output(`no video briefs in the last ${options.days} days`);
+    return 0;
+  }
+
+  const prompt = buildDigestPrompt(briefs);
+  let text;
+  try {
+    text = invokeDigestEngine(prompt, deps);
+  } catch (err) {
+    output(err.message || 'digest engine failed');
+    return 1;
+  }
+  if (!text) {
+    output('digest engine returned no text');
+    return 1;
+  }
+
+  const date = dateStamp(now);
+  const relDigest = `atris/wiki/briefs/digest-${date}.md`;
+  const header = [
+    `date: ${date}`,
+    `window: ${options.days} days`,
+    `sources: ${briefs.map((row) => row.relPath).join(', ')}`,
+  ].join('\n');
+  fs.mkdirSync(path.join(cwd, 'atris', 'wiki', 'briefs'), { recursive: true });
+  fs.writeFileSync(path.join(cwd, relDigest), `${header}\n\n${text}\n`);
+  appendDigestJournal({ cwd, date, relDigest });
+  output(`digest filed: ${relDigest} (${briefs.length} briefs)`);
+  return 0;
+}
+
 function watchStatePath(cwd = process.cwd()) {
   return path.join(cwd, '.atris', 'state', 'youtube_watch.json');
 }
@@ -816,37 +1048,194 @@ async function watchCommand(args = [], deps = {}) {
   return 2;
 }
 
-function runYoutubeNotes(args = [], deps = {}) {
-  const output = deps.output || ((line = '') => console.error(line));
-  const url = args[0];
-  const engine = args[1];
-  if (!url) {
-    output(YTNOTES_USAGE);
-    output(YTNOTES_HINT);
-    return 2;
+function defaultPlaylistExpander(playlistUrl, deps = {}) {
+  const spawn = deps.spawnSync || spawnSync;
+  const result = spawn('yt-dlp', [
+    '--no-update',
+    '--flat-playlist',
+    '--print',
+    '%(id)s|%(title)s',
+    playlistUrl,
+  ], {
+    encoding: 'utf8',
+    timeout: 60000,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  if (result.error || (result.status != null && result.status !== 0)) {
+    const detail = String(result.stderr || result.error?.message || 'playlist expand failed').trim();
+    throw new Error(detail || 'playlist expand failed');
   }
+  return parseFlatPlaylist(result.stdout);
+}
 
+function defaultNotesItemRunner(url, engine, deps = {}) {
   const script = path.join(__dirname, '..', 'scripts', 'det', 'ytnotes');
   const spawn = deps.spawnSync || spawnSync;
   const childArgs = engine ? [url, engine] : [url];
-  const result = spawn(script, childArgs, { stdio: 'inherit' });
-  if (result.status == null) return 1;
-  if (result.status === 0) {
-    fileBriefFromNotes({
+  return spawn(script, childArgs, { stdio: 'inherit' });
+}
+
+function readNowMs(deps = {}) {
+  if (typeof deps.nowMs === 'function') return Number(deps.nowMs()) || 0;
+  if (Number.isFinite(deps.nowMs)) return Number(deps.nowMs);
+  return Date.now();
+}
+
+function notesItemLabel(item = {}) {
+  return item.id || item.url || '';
+}
+
+function expandNotesTargets(urls = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.error(line));
+  const expander = deps.expander || ((playlistUrl) => defaultPlaylistExpander(playlistUrl, deps));
+  const items = [];
+  for (const url of urls) {
+    if (!isPlaylistUrl(url)) {
+      items.push({ url, id: videoIdFromUrl(url) });
+      continue;
+    }
+    let videos = [];
+    try {
+      videos = expander(url, deps);
+    } catch {
+      items.push({ url, id: videoIdFromUrl(url), failed: true });
+      continue;
+    }
+    if (!Array.isArray(videos) || videos.length === 0) {
+      items.push({ url, id: videoIdFromUrl(url), failed: true });
+      continue;
+    }
+    if (videos.length > NOTES_PLAYLIST_CAP) {
+      output(`playlist capped at ${NOTES_PLAYLIST_CAP} videos (${videos.length} found)`);
+      videos = videos.slice(0, NOTES_PLAYLIST_CAP);
+    }
+    for (const video of videos) {
+      if (!video?.id) continue;
+      items.push({
+        url: `https://www.youtube.com/watch?v=${video.id}`,
+        id: video.id,
+        title: video.title,
+      });
+    }
+  }
+  return items;
+}
+
+function invokeNotesRunner(url, engine, deps = {}) {
+  const runner = deps.runner;
+  if (runner) return runner(url, engine, deps);
+  return defaultNotesItemRunner(url, engine, deps);
+}
+
+function readRunnerStatus(result) {
+  if (typeof result === 'number') return result;
+  if (result && typeof result === 'object') {
+    return result.status == null ? 1 : result.status;
+  }
+  return 1;
+}
+
+function fileNotesBrief(url, deps = {}) {
+  const briefFiler = deps.briefFiler || fileBriefFromNotes;
+  try {
+    const filed = briefFiler({
       cwd: deps.cwd || process.cwd(),
       url,
       workDir: deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes'),
       now: deps.now || new Date(),
     });
+    return typeof filed === 'string' && filed ? filed : null;
+  } catch {
+    return null;
+  }
+}
+
+function runOneNotesItem(item, engine, deps = {}) {
+  const output = deps.output || ((line = '') => console.error(line));
+  const label = notesItemLabel(item);
+  if (item.failed) {
+    output(`${label}  0s  FAILED`);
+    return { url: item.url, id: item.id, seconds: 0, ok: false, brief: null };
+  }
+
+  const started = readNowMs(deps);
+  let status = 1;
+  try {
+    status = readRunnerStatus(invokeNotesRunner(item.url, engine, deps));
+  } catch {
+    status = 1;
+  }
+  const brief = status === 0 ? fileNotesBrief(item.url, deps) : null;
+  const seconds = Math.max(0, Math.round((readNowMs(deps) - started) / 1000));
+  const ok = status === 0;
+  output(`${label}  ${seconds}s  ${ok ? (brief || 'ok') : 'FAILED'}`);
+  return { url: item.url, id: item.id, seconds, ok, brief };
+}
+
+function formatNotesSummary(rows = []) {
+  const lines = ['url or id  seconds  result'];
+  for (const row of rows) {
+    const result = row.ok ? (row.brief || 'ok') : 'FAILED';
+    lines.push(`${notesItemLabel(row)}  ${row.seconds}s  ${result}`);
+  }
+  return lines.join('\n');
+}
+
+function runYoutubeNotesBatch({ urls, engine } = {}, deps = {}) {
+  const output = deps.output || ((line = '') => console.error(line));
+  const items = expandNotesTargets(urls || [], deps);
+  const rows = [];
+  for (const item of items) {
+    rows.push(runOneNotesItem(item, engine, deps));
+  }
+  if (rows.length) {
+    output('');
+    output(formatNotesSummary(rows));
   }
-  return result.status;
+  if (!rows.length) return 2;
+  return rows.some((row) => row.ok) ? 0 : 2;
+}
+
+function runSingleYoutubeNotes(url, engine, deps = {}) {
+  let result;
+  try {
+    result = invokeNotesRunner(url, engine, deps);
+  } catch {
+    return 1;
+  }
+  const status = readRunnerStatus(result);
+  if (status === 0) fileNotesBrief(url, deps);
+  return status;
+}
+
+function runYoutubeNotes(args = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.error(line));
+  const parsed = parseNotesArgs(args);
+  if (parsed.help) {
+    showYoutubeHelp(output, deps.commandName || 'atris youtube');
+    return 0;
+  }
+  if (!parsed.urls.length) {
+    output(YTNOTES_USAGE);
+    output(YTNOTES_HINT);
+    return 2;
+  }
+  if (parsed.urls.length === 1 && !isPlaylistUrl(parsed.urls[0])) {
+    return runSingleYoutubeNotes(parsed.urls[0], parsed.engine, deps);
+  }
+  return runYoutubeNotesBatch(parsed, deps);
 }
 
 async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
   if (argv[0] === 'notes') {
     const code = runYoutubeNotes(argv.slice(1), deps);
-    if (!deps.output && !deps.spawnSync) process.exit(code);
+    if (!deps.output && !deps.spawnSync && !deps.runner && !deps.expander) process.exit(code);
+    return code;
+  }
+  if (argv[0] === 'digest') {
+    const code = runYoutubeDigest(argv.slice(1), { ...deps, output });
+    if (!deps.output && !deps.runner) process.exit(code);
     return code;
   }
   if (argv[0] === 'watch') {
@@ -874,6 +1263,16 @@ module.exports = {
   shouldRetryWithLocalTranscript,
   formatYoutubeResult,
   fileBriefFromNotes,
+  looksLikeYoutubeUrl,
+  isPlaylistUrl,
+  parseNotesArgs,
+  expandNotesTargets,
+  runYoutubeNotesBatch,
+  runYoutubeNotes,
+  parseDigestArgs,
+  collectVideoBriefs,
+  buildDigestPrompt,
+  runYoutubeDigest,
   normalizeWatchChannel,
   channelVideosUrl,
   parseFlatPlaylist,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.50.0",
+  "version": "3.52.0",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {

package/scripts/det/ytnotes

@@ -163,7 +163,7 @@ process.stdin.on("end", () => {
 
 run_grok() {
   run_with_timeout 240 grok --verbatim --no-memory --no-plan --no-subagents \
-    --disable-web-search --max-turns 1 -p "$PROMPT"
+    --disable-web-search --max-turns 3 -p "$PROMPT"
 }
 
 run_haiku() {

package/scripts/det/ytrail-race.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+'use strict';
+
+// Race graded ytnotes engines. Reports only; never edits ytnotes.
+// Usage: node scripts/det/ytrail-race.js [url] [engines-csv]
+// Default url: https://www.youtube.com/watch?v=Z3JyAqh4ixg
+// Default engines: haiku,grok,cursor,atris-fast
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_URL = 'https://www.youtube.com/watch?v=Z3JyAqh4ixg';
+const DEFAULT_ENGINES = ['haiku', 'grok', 'cursor', 'atris-fast'];
+const DEFAULT_TIMEOUT_MS = 300000;
+const DEFAULT_ROOT = path.resolve(__dirname, '..', '..');
+const EVAL_LINE = /ytrail (pass|fail) (\S+) ([\d.]+)s words=\d+ quotes=(\d+)\/(\d+) heading=(?:yes|no)/;
+
+function parseArgs(argv) {
+  const url = argv[0] || DEFAULT_URL;
+  const engines = argv[1]
+    ? String(argv[1]).split(',').map((name) => name.trim()).filter(Boolean)
+    : DEFAULT_ENGINES.slice();
+  return { url, engines };
+}
+
+function parseEvalLine(text) {
+  const match = String(text || '').match(EVAL_LINE);
+  if (!match) return null;
+  return {
+    engine: match[2],
+    seconds: Number(match[3]),
+    pass: match[1] === 'pass',
+    quotesVerified: Number(match[4]),
+    quotesTotal: Number(match[5]),
+  };
+}
+
+function failedResult(engine, seconds) {
+  return {
+    engine,
+    seconds: Number(seconds) || 0,
+    pass: false,
+    quotesVerified: 0,
+    quotesTotal: 0,
+  };
+}
+
+function createDefaultRunner(options = {}) {
+  const root = options.root || DEFAULT_ROOT;
+  const evalPath = options.evalPath || path.join(root, 'scripts', 'det', 'ytrail-eval.js');
+  const cwd = options.cwd || root;
+  const env = options.env || process.env;
+  return function defaultRunner({ url, engine, timeoutMs }) {
+    const run = spawnSync(process.execPath, [evalPath, url, engine], {
+      encoding: 'utf8',
+      cwd,
+      env,
+      timeout: timeoutMs,
+    });
+    return {
+      stdout: String(run.stdout || ''),
+      stderr: String(run.stderr || ''),
+      status: run.status,
+      error: run.error || null,
+      timedOut: Boolean(run.error && run.error.code === 'ETIMEDOUT'),
+    };
+  };
+}
+
+function runOneEngine(engine, ctx) {
+  let run;
+  try {
+    run = ctx.runner({
+      url: ctx.url,
+      engine,
+      timeoutMs: ctx.timeoutMs,
+    });
+  } catch {
+    return failedResult(engine, 0);
+  }
+  if (!run || run.timedOut) {
+    return failedResult(engine, ctx.timeoutMs / 1000);
+  }
+  const parsed = parseEvalLine(run.stdout);
+  if (!parsed) return failedResult(engine, 0);
+  return {
+    engine,
+    seconds: parsed.seconds,
+    pass: parsed.pass,
+    quotesVerified: parsed.quotesVerified,
+    quotesTotal: parsed.quotesTotal,
+  };
+}
+
+function pickWinner(results) {
+  return results
+    .filter((row) => row.pass)
+    .slice()
+    .sort((a, b) => a.seconds - b.seconds)[0] || null;
+}
+
+function pad(value, width) {
+  const text = String(value);
+  return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+
+function formatTable(results) {
+  const engineWidth = Math.max(6, ...results.map((row) => String(row.engine).length));
+  const lines = [
+    `${pad('engine', engineWidth)}  seconds  pass  quotes`,
+  ];
+  for (const row of results) {
+    lines.push(
+      `${pad(row.engine, engineWidth)}  ${pad(row.seconds, 7)}  ${pad(row.pass ? 'yes' : 'no', 4)}  ${row.quotesVerified}/${row.quotesTotal}`
+    );
+  }
+  return lines.join('\n');
+}
+
+function formatVerdict(winner) {
+  if (!winner) return 'race winner: none';
+  return `race winner: ${winner.engine} (${winner.seconds}s, quotes ${winner.quotesVerified}/${winner.quotesTotal})`;
+}
+
+function writeLatest(root, report) {
+  const outDir = path.join(root, 'atris', 'benchmarks');
+  fs.mkdirSync(outDir, { recursive: true });
+  const payload = {
+    ts: report.ts,
+    url: report.url,
+    results: report.results,
+    winner: report.winner,
+  };
+  fs.writeFileSync(
+    path.join(outDir, 'ytrail-race-latest.json'),
+    `${JSON.stringify(payload, null, 2)}\n`
+  );
+}
+
+function runRace(options = {}) {
+  const url = options.url || DEFAULT_URL;
+  const engines = options.engines && options.engines.length
+    ? options.engines.slice()
+    : DEFAULT_ENGINES.slice();
+  const timeoutMs = options.timeoutMs == null ? DEFAULT_TIMEOUT_MS : options.timeoutMs;
+  const root = options.root || DEFAULT_ROOT;
+  const runner = options.runner || createDefaultRunner({ root });
+  const log = options.log || console.log;
+  const ts = options.ts || new Date().toISOString();
+
+  const results = [];
+  for (const engine of engines) {
+    results.push(runOneEngine(engine, { url, runner, timeoutMs }));
+  }
+
+  const winner = pickWinner(results);
+  const report = { ts, url, results, winner };
+  writeLatest(root, report);
+
+  log(formatTable(results));
+  log(formatVerdict(winner));
+
+  return {
+    ...report,
+    exitCode: winner ? 0 : 1,
+  };
+}
+
+function main(argv = process.argv.slice(2), options = {}) {
+  const parsed = parseArgs(argv);
+  const report = runRace({ ...options, ...parsed });
+  return report.exitCode;
+}
+
+if (require.main === module) {
+  process.exit(main());
+}
+
+module.exports = {
+  DEFAULT_URL,
+  DEFAULT_ENGINES,
+  DEFAULT_TIMEOUT_MS,
+  parseArgs,
+  parseEvalLine,
+  createDefaultRunner,
+  pickWinner,
+  formatTable,
+  formatVerdict,
+  runRace,
+  main,
+};