atris 3.49.0 → 3.51.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

@@ -26,9 +26,16 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('');
   output(`Usage: ${commandName} notes <youtube-url> [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('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.');
   output('');
@@ -47,6 +54,10 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_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('');
 }
 
@@ -82,7 +93,7 @@ function parseYoutubeArgs(argv = []) {
     return options;
   }
 
-  if (['process', 'analyze', 'watch'].includes(args[0])) {
+  if (['process', 'analyze'].includes(args[0])) {
     args.shift();
   }
 
@@ -506,6 +517,504 @@ function fileBriefFromNotes({ cwd, url, workDir, now } = {}) {
   }
 }
 
+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');
+}
+
+function emptyWatchState() {
+  return { channels: [], seen: {}, seeded: {}, seenByChannel: {} };
+}
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function loadWatchState(statePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const channels = Array.isArray(parsed?.channels) ? parsed.channels : [];
+    return {
+      channels,
+      seen: asObject(parsed?.seen),
+      seeded: asObject(parsed?.seeded),
+      seenByChannel: asObject(parsed?.seenByChannel),
+    };
+  } catch {
+    return emptyWatchState();
+  }
+}
+
+function saveWatchState(statePath, state) {
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  const payload = {
+    channels: (state.channels || []).map((row) => ({
+      channel: row.channel,
+      added: row.added,
+    })),
+    seen: asObject(state.seen),
+    seeded: asObject(state.seeded),
+    seenByChannel: asObject(state.seenByChannel),
+  };
+  fs.writeFileSync(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function stampNow(now) {
+  if (typeof now === 'function') now = now();
+  if (typeof now === 'string' && now) return now;
+  const value = now instanceof Date ? now : new Date(now || Date.now());
+  if (Number.isNaN(value.getTime())) return new Date().toISOString();
+  return value.toISOString();
+}
+
+function normalizeWatchChannel(input) {
+  const raw = String(input || '').trim();
+  if (!raw) throw new Error('Missing channel url or @handle. Run "atris youtube watch --help".');
+
+  let text = raw;
+  if (text.startsWith('@')) {
+    text = `https://www.youtube.com/${text}`;
+  } else if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(text)) {
+    if (/^(www\.)?youtube\.com\//i.test(text) || /^youtu\.be\//i.test(text)) {
+      text = `https://${text}`;
+    } else if (/^@?[\w.-]+$/.test(text)) {
+      text = `https://www.youtube.com/@${text.replace(/^@/, '')}`;
+    } else {
+      throw new Error(`Invalid channel: ${raw}`);
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(text);
+  } catch {
+    throw new Error(`Invalid channel: ${raw}`);
+  }
+
+  parsed.hash = '';
+  parsed.search = '';
+  let href = parsed.toString().replace(/\/+$/, '');
+  href = href.replace(/\/(videos|featured|streams|shorts)$/i, '');
+  return href;
+}
+
+function channelVideosUrl(channel) {
+  const base = String(channel || '').replace(/\/+$/, '');
+  if (/\/videos$/i.test(base)) return base;
+  return `${base}/videos`;
+}
+
+function parseFlatPlaylist(stdout) {
+  const videos = [];
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes('|')) continue;
+    const idx = trimmed.indexOf('|');
+    const id = trimmed.slice(0, idx).trim();
+    const title = trimmed.slice(idx + 1).trim();
+    if (id && id !== 'NA') videos.push({ id, title });
+  }
+  return videos;
+}
+
+function defaultChannelFetcher(videosUrl, deps = {}) {
+  const spawn = deps.spawnSync || spawnSync;
+  const result = spawn('yt-dlp', [
+    '--no-update',
+    '--flat-playlist',
+    '--playlist-end',
+    '3',
+    '--print',
+    '%(id)s|%(title)s',
+    videosUrl,
+  ], {
+    encoding: 'utf8',
+    timeout: 60000,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.error?.message || 'fetch failed').trim();
+    throw new Error(detail || 'fetch failed');
+  }
+  return parseFlatPlaylist(result.stdout);
+}
+
+function defaultNotesRunner(url, deps = {}) {
+  const script = path.join(__dirname, '..', 'scripts', 'det', 'ytnotes');
+  const spawn = deps.spawnSync || spawnSync;
+  return spawn(script, [url], { stdio: 'inherit' });
+}
+
+function resolveWatchStatePath(deps = {}) {
+  if (deps.statePath) return deps.statePath;
+  return watchStatePath(deps.cwd || process.cwd());
+}
+
+function channelSeenMap(state, channel) {
+  return asObject(asObject(state.seenByChannel)[channel]);
+}
+
+function markSeen(state, channel, id, timestamp) {
+  if (!state.seen || typeof state.seen !== 'object') state.seen = {};
+  if (!state.seenByChannel || typeof state.seenByChannel !== 'object') state.seenByChannel = {};
+  if (!state.seenByChannel[channel] || typeof state.seenByChannel[channel] !== 'object') {
+    state.seenByChannel[channel] = {};
+  }
+  state.seen[id] = timestamp;
+  state.seenByChannel[channel][id] = timestamp;
+}
+
+function addWatchChannel(channelInput, deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  if (!channelInput) {
+    output('usage: atris youtube watch add <channel-url-or-@handle>');
+    return 2;
+  }
+
+  let channel;
+  try {
+    channel = normalizeWatchChannel(channelInput);
+  } catch (err) {
+    output(err.message);
+    return 2;
+  }
+
+  const statePath = resolveWatchStatePath(deps);
+  const state = loadWatchState(statePath);
+  if (state.channels.some((row) => row.channel === channel)) {
+    output(`already watching ${channel}`);
+    return 0;
+  }
+
+  state.channels.push({
+    channel,
+    added: stampNow(deps.now),
+  });
+  saveWatchState(statePath, state);
+  output(`watching ${channel}`);
+  return 0;
+}
+
+function listWatchChannels(deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const state = loadWatchState(resolveWatchStatePath(deps));
+  if (!state.channels.length) {
+    output('no channels watched');
+    return 0;
+  }
+
+  state.channels.forEach((row, index) => {
+    const count = Object.keys(channelSeenMap(state, row.channel)).length;
+    output(`${index + 1}. ${row.channel} (${count} seen)`);
+  });
+  return 0;
+}
+
+function removeWatchChannel(rawNumber, deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const index = Number(rawNumber);
+  const statePath = resolveWatchStatePath(deps);
+  const state = loadWatchState(statePath);
+  if (!Number.isInteger(index) || index < 1 || index > state.channels.length) {
+    output('usage: atris youtube watch remove <number>');
+    return 2;
+  }
+
+  const [removed] = state.channels.splice(index - 1, 1);
+  saveWatchState(statePath, state);
+  output(`removed ${removed.channel}`);
+  return 0;
+}
+
+async function tickWatch(deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const statePath = resolveWatchStatePath(deps);
+  const fetcher = deps.fetcher || ((videosUrl) => defaultChannelFetcher(videosUrl, deps));
+  const runner = deps.runner || ((url) => defaultNotesRunner(url, deps));
+  const briefFiler = deps.briefFiler || fileBriefFromNotes;
+  const cwd = deps.cwd || process.cwd();
+  const workDir = deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
+  const timestamp = stampNow(deps.now);
+  const now = deps.now || timestamp;
+
+  const state = loadWatchState(statePath);
+  let totalNew = 0;
+  let totalBriefed = 0;
+
+  for (const row of state.channels) {
+    const videosUrl = channelVideosUrl(row.channel);
+    let videos;
+    try {
+      videos = await Promise.resolve(fetcher(videosUrl, row));
+    } catch {
+      output(`warning: channel ${row.channel} fetch failed`);
+      continue;
+    }
+    if (!Array.isArray(videos)) {
+      output(`warning: channel ${row.channel} fetch failed`);
+      continue;
+    }
+
+    const localSeen = channelSeenMap(state, row.channel);
+    const isFresh = !state.seeded[row.channel];
+    const unseen = videos.filter((video) => video?.id && !localSeen[video.id] && !state.seen[video.id]);
+    const newest = videos[0];
+    const toBrief = isFresh
+      ? (newest?.id ? [newest] : [])
+      : unseen;
+
+    if (isFresh) {
+      state.seeded[row.channel] = true;
+      for (const video of videos) {
+        if (video?.id) markSeen(state, row.channel, video.id, timestamp);
+      }
+    }
+
+    let briefed = 0;
+    for (const video of toBrief) {
+      if (!video?.id) continue;
+      const url = `https://www.youtube.com/watch?v=${video.id}`;
+      try {
+        runner(url, deps);
+      } catch {
+        // notes failure must not stop the rest of the tick
+      }
+      try {
+        briefFiler({ cwd, url, workDir, now });
+      } catch {
+        // brief filing must never break the watch tick
+      }
+      markSeen(state, row.channel, video.id, timestamp);
+      briefed += 1;
+    }
+
+    if (!isFresh) {
+      for (const video of unseen) {
+        if (video?.id) markSeen(state, row.channel, video.id, timestamp);
+      }
+    }
+
+    const newCount = isFresh ? (newest?.id ? 1 : 0) : unseen.length;
+    output(`channel ${row.channel}: ${newCount} new, ${briefed} briefed`);
+    totalNew += newCount;
+    totalBriefed += briefed;
+    saveWatchState(statePath, state);
+  }
+
+  output(`total: ${totalNew} new, ${totalBriefed} briefed`);
+  saveWatchState(statePath, state);
+  return 0;
+}
+
+async function watchCommand(args = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const sub = args[0];
+  if (!sub || ['help', '--help', '-h'].includes(sub)) {
+    showYoutubeHelp(output, deps.commandName || 'atris youtube');
+    return sub ? 0 : 2;
+  }
+  if (sub === 'add') return addWatchChannel(args[1], deps);
+  if (sub === 'list') return listWatchChannels(deps);
+  if (sub === 'remove') return removeWatchChannel(args[1], deps);
+  if (sub === 'tick') return tickWatch(deps);
+  output(`unknown watch command: ${sub}`);
+  return 2;
+}
+
 function runYoutubeNotes(args = [], deps = {}) {
   const output = deps.output || ((line = '') => console.error(line));
   const url = args[0];
@@ -539,6 +1048,16 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
     if (!deps.output && !deps.spawnSync) 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') {
+    const code = await watchCommand(argv.slice(1), { ...deps, output });
+    if (!deps.output && !deps.fetcher && !deps.runner && !deps.briefFiler) process.exit(code);
+    return code;
+  }
   const options = parseYoutubeArgs(argv);
   if (options.help) {
     showYoutubeHelp(output, deps.commandName || 'atris youtube');
@@ -559,5 +1078,19 @@ module.exports = {
   shouldRetryWithLocalTranscript,
   formatYoutubeResult,
   fileBriefFromNotes,
+  parseDigestArgs,
+  collectVideoBriefs,
+  buildDigestPrompt,
+  runYoutubeDigest,
+  normalizeWatchChannel,
+  channelVideosUrl,
+  parseFlatPlaylist,
+  loadWatchState,
+  saveWatchState,
+  addWatchChannel,
+  listWatchChannels,
+  removeWatchChannel,
+  tickWatch,
+  watchCommand,
   youtubeCommand,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.49.0",
+  "version": "3.51.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,
+};