atris 3.62.0 → 3.63.0

package/commands/transactions.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// atris transactions: every order, fee, trade, and wallet send, newest first.
+// Read only. Backend: GET /api/transactions.
+
+const { apiRequestJson } = require('../utils/api');
+const { loadCredentials } = require('../utils/auth');
+const { NOT_LOGGED_IN, tokenFrom, oneLine, printResult } = require('../lib/developer-api');
+const { parseFlags, formatCents, errorFrom } = require('../lib/commerce');
+
+const TX_KINDS = ['ticket', 'shop', 'flight', 'test_purchase', 'fee', 'trade', 'wallet_send'];
+
+function showTransactionsHelp(log = console.log) {
+  log(`usage: atris transactions [--since YYYY-MM-DD] [--kind k[,k]] [--limit n] [--include-quotes] [--json]
+
+list what you bought, paid in fees, traded, or sent, newest first. read only.
+
+  --since   only rows on or after this date, like 2026-09-01
+  --kind    ${TX_KINDS.join(', ')}
+  --limit   1 to 200 (default 50)
+  --include-quotes  also list quotes nobody approved`);
+}
+
+function clip(text, width) {
+  const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
+  return s.length > width ? `${s.slice(0, width - 1)}…` : s;
+}
+
+function whenText(value) {
+  const s = String(value || '');
+  const m = s.match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2})/);
+  return m ? `${m[1]} ${m[2]}` : clip(s, 16);
+}
+
+function renderTransactions(data = {}) {
+  const rows = Array.isArray(data.transactions) ? data.transactions : [];
+  const lines = [];
+  if (!rows.length) lines.push('No transactions yet.');
+  else {
+    const table = rows.map((r) => [
+      whenText(r.when),
+      clip(r.kind, 12),
+      clip(r.what, 40),
+      formatCents(r.amount_cents, r.currency),
+      clip(r.state, 16),
+    ]);
+    const head = ['WHEN', 'KIND', 'WHAT', 'AMOUNT', 'STATE'];
+    const widths = head.map((h, i) => Math.max(h.length, ...table.map((row) => row[i].length)));
+    const fmt = (row) => row.map((cell, i) => (i === 3 ? cell.padStart(widths[i]) : cell.padEnd(widths[i])))
+      .join('  ').trimEnd();
+    lines.push(fmt(head));
+    for (const row of table) lines.push(fmt(row));
+  }
+  const down = Object.entries(data.sources || {}).filter(([, v]) => v !== 'ok').map(([k]) => k);
+  if (down.length) lines.push('', `Partial list: could not load ${down.join(', ')}.`);
+  return lines.join('\n');
+}
+
+function buildQuery(flags) {
+  const params = new URLSearchParams();
+  if (flags.since != null) {
+    const since = String(flags.since).trim();
+    if (!/^\d{4}-\d{2}-\d{2}/.test(since)) return { ok: false, error: '--since must be a date like 2026-09-01' };
+    params.set('since', since);
+  }
+  const rawKind = flags.kind != null ? flags.kind : flags.kinds;
+  if (rawKind != null) {
+    const kinds = String(rawKind).split(',').map((k) => k.trim().toLowerCase()).filter(Boolean);
+    const bad = kinds.filter((k) => !TX_KINDS.includes(k));
+    if (bad.length || !kinds.length) return { ok: false, error: `--kind must be one of ${TX_KINDS.join(', ')}` };
+    params.set('kinds', kinds.join(','));
+  }
+  if (flags.limit != null) {
+    const limit = Number(flags.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) return { ok: false, error: '--limit must be a number from 1 to 200' };
+    params.set('limit', String(limit));
+  }
+  if (flags.include_quotes === true) params.set('include_quotes', 'true');
+  const qs = params.toString();
+  return { ok: true, path: qs ? `/transactions?${qs}` : '/transactions' };
+}
+
+async function transactionsCommand(args = [], deps = {}) {
+  const io = { log: deps.log || console.log, err: deps.err || console.error };
+  const { flags, pos } = parseFlags(args);
+  if (flags.help || pos[0] === 'help') {
+    showTransactionsHelp(io.log);
+    return 0;
+  }
+  const json = flags.json === true;
+  const fail = (error, status) => {
+    printResult({ json, ok: false, error, payload: { ok: false, error, ...(status ? { status } : {}) } }, io);
+    return 1;
+  };
+
+  const query = buildQuery(flags);
+  if (!query.ok) return fail(query.error);
+
+  const load = deps.loadCredentials || loadCredentials;
+  const request = deps.apiRequestJson || apiRequestJson;
+  const token = tokenFrom(load());
+  if (!token) return fail(NOT_LOGGED_IN);
+
+  try {
+    const result = await request(query.path, { method: 'GET', token });
+    if (!result || !result.ok) return fail(errorFrom(result), result && result.status);
+    const data = result.data || {};
+    printResult({ json, ok: true, text: renderTransactions(data), payload: { ok: true, ...data } }, io);
+    return 0;
+  } catch (error) {
+    return fail(oneLine(error && error.message));
+  }
+}
+
+module.exports = { transactionsCommand };

package/commands/youtube.js

@@ -40,6 +40,7 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`       ${commandName} watch list`);
   output(`       ${commandName} watch remove <number>`);
   output(`       ${commandName} watch tick`);
+  output(`       ${commandName} bench [--quick] [--case <name>]`);
   output(`       ${commandName} <youtube-url> [options]`);
   output('');
   output('search = free local discovery (ytsearch / yt-dlp), returns youtu.be links; rich free search writes one apply and a failing keep/revert pack; thin hands off to teach');
@@ -50,6 +51,7 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('process = 5 credits cloud knowledge (needs a filled Apply); rich process writes one apply and a failing keep/revert pack');
   output('digest = one decision page from this week\'s video briefs; rich digest writes one apply and a failing keep/revert pack');
   output('watch = subscribed channels turn into briefs without a human; add hands off to tick; tick hands off to teach when it briefed');
+  output('bench = run notes on real videos, uncached, and grade what a user gets; --quick runs the short video and the stranger checks');
   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('');
@@ -3851,6 +3853,20 @@ async function runYoutubeTeach(args = [], deps = {}) {
   return applyCode;
 }
 
+// Bench the notes feature end to end. The script prints its own lines.
+function runYoutubeBench(argv, deps = {}) {
+  const run = (deps.spawnSync || spawnSync)(
+    process.execPath,
+    [path.join(__dirname, '..', 'scripts', 'det', 'ytrail-bench.js'), ...argv],
+    { stdio: 'inherit' },
+  );
+  if (run.error) {
+    (deps.output || console.error)(`bench did not start: ${run.error.message}`);
+    return 1;
+  }
+  return typeof run.status === 'number' ? run.status : 1;
+}
+
 async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
   if (argv[0] === 'search') {
@@ -3880,6 +3896,11 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
     if (!deps.output && !deps.runner) process.exit(code);
     return code;
   }
+  if (argv[0] === 'bench') {
+    const code = runYoutubeBench(argv.slice(1), deps);
+    if (!deps.output && !deps.spawnSync) 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);
@@ -3978,5 +3999,6 @@ module.exports = {
   searchApplyRel,
   firstRichWatchLesson,
   fileTeachExperiment,
+  runYoutubeBench,
   youtubeCommand,
 };

package/lib/commerce.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Shared helpers for `atris buy` and `atris transactions`.
+// Backend: /api/commerce/* and /api/transactions (commerce_router.py).
+
+const { ROLLOUT_MESSAGE, oneLine } = require('./developer-api');
+
+// Flags whose values the backend reads as numbers.
+const NUMERIC_KEYS = new Set(['quantity', 'dollars', 'limit_price', 'min_each_usd', 'max_each_usd', 'limit']);
+
+function snake(key) {
+  return String(key).replace(/-/g, '_');
+}
+
+function coerce(key, value) {
+  if (value === true) return true;
+  const text = String(value);
+  if (/^[[{]/.test(text.trim())) {
+    try { return JSON.parse(text); } catch { /* keep as text */ }
+  }
+  if (NUMERIC_KEYS.has(key) && text.trim() !== '' && Number.isFinite(Number(text))) return Number(text);
+  return text;
+}
+
+// --event-url x --quantity 2 --accept-extras  ->  { event_url: 'x', quantity: 2, accept_extras: true }
+function parseFlags(argv = []) {
+  const flags = {};
+  const pos = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i]);
+    if (arg === '-h') { flags.help = true; continue; }
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      const rawKey = eq > 0 ? arg.slice(2, eq) : arg.slice(2);
+      const key = snake(rawKey);
+      if (eq > 0) { flags[key] = coerce(key, arg.slice(eq + 1)); continue; }
+      const next = argv[i + 1];
+      if (next != null && !String(next).startsWith('--')) { flags[key] = coerce(key, next); i += 1; } else flags[key] = true;
+      continue;
+    }
+    pos.push(arg);
+  }
+  return { flags, pos };
+}
+
+function formatCents(cents, currency = 'usd') {
+  if (cents == null || cents === '' || !Number.isFinite(Number(cents))) return '-';
+  const n = Number(cents) / 100;
+  const sign = n < 0 ? '-' : '';
+  const body = `$${Math.abs(n).toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ',')}`;
+  const code = String(currency || 'usd').toLowerCase();
+  return code === 'usd' ? `${sign}${body}` : `${sign}${body} ${code.toUpperCase()}`;
+}
+
+// "2026-09-29T18:04:00Z" -> "in 30 min" / "expired"
+function untilText(iso, now = Date.now()) {
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return '';
+  const mins = Math.round((at - now) / 60000);
+  if (mins <= 0) return 'expired';
+  if (mins < 90) return `in ${mins} min`;
+  return `in ${Math.round(mins / 60)} h`;
+}
+
+// The backend's error envelope is {"error": {"message", "type"}, "atris": {...}}.
+// A bare 404 with no envelope means the route itself is not deployed yet.
+function errorFrom(result) {
+  const data = result && result.data;
+  const envelope = data && typeof data === 'object' && data.error && typeof data.error === 'object';
+  if (result && Number(result.status) === 404 && !envelope) return ROLLOUT_MESSAGE;
+  if (envelope) return oneLine(data.error.message || data.error);
+  return oneLine(result && result.error);
+}
+
+module.exports = { parseFlags, formatCents, untilText, errorFrom };

package/lib/engine-registry.js

@@ -860,6 +860,22 @@ function resolveEngineModelWords(text) {
   throw new Error(`"${clean}" is not an engine or a model atris knows`);
 }
 
+// The engine a model name belongs to, read the same way a roster line is,
+// or '' when the name is not one atris can place. The claude cli's
+// own aliases ("default", "opusplan", with or without [1m]) count as claude.
+function modelEngineName(model) {
+  const base = String(model || '').trim().replace(CLAUDE_LONG_CONTEXT, '').trim();
+  try {
+    return resolveEngineModelWords(base).engine || '';
+  } catch {
+    return CLAUDE_MODEL_ALIASES.includes(base.toLowerCase()) ? 'claude' : '';
+  }
+}
+
+function isClaudeFamilyModel(model) {
+  return CLAUDE_FAMILY_ENGINES.includes(modelEngineName(model));
+}
+
 // What an engine can do by its seed, used to check hand-written lines before
 // any registry is read.
 function engineCanTake(engineId, role) {
@@ -2107,6 +2123,7 @@ module.exports = {
   setRosterPick,
   confirmRoster,
   normalizeRosterModel,
+  isClaudeFamilyModel,
   rosterModelLabel,
   parseRosterUntil,
   rosterPickExpired,

package/lib/known-commands.js

@@ -4,7 +4,7 @@ const knownCommands = ['init', 'guide', 'doctor', 'doc-health', 'install', 'work
                        'activate', '_activate', 'agent', 'team', 'chat', 'fast', 'ax', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'close', 'harvest', 'verify', 'recover', 'search', 'scout', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'taste', 'teach', 'plugin', 'experiments', 'bench', 'router', 'tree', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube', 'x-search',
                        'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'decide', 'agents', 'probe', 'worktree', 'land', 'caretaker', 'autoland', 'drive', 'aeo', 'slop', 'voice', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'sync-checkout',
-                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'balance', 'usage', 'api-key', 'topup', 'design', 'mcp', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
+                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'balance', 'usage', 'api-key', 'topup', 'buy', 'transactions', 'design', 'mcp', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'pack', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'fleet-report', 'loops', 'self-improve', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines', 'playbook', 'feed', 'brief', 'social', 'host', 'people', 'follow', 'unfollow', 'friends', 'msg', 'inbox', 'invite', 'join', 'rsi'];
 
 // Damerau-Levenshtein edit distance between two short strings. Counts an

package/lib/member-engine.js

@@ -8,6 +8,7 @@
 // words ("judge: opus 5.5"). The job's pick then comes from the roster.
 
 const fs = require('fs');
+const { memberRefusalReason } = require('./member-type');
 const path = require('path');
 const {
   ENGINE_JOBS,
@@ -204,6 +205,7 @@ function memberRosterEngine(memberName, root = process.cwd(), options = {}) {
   const name = String(memberName || '').trim();
   if (!name || name.includes('/') || name.includes('\\')) return null;
   try {
+    if (!memberCardRunnable(root, name)) return null;
     const picked = resolveEngineForMember(name, root, options);
     if (!picked.found && options.requireMember !== false) return null;
     return picked.roster_backed && picked.engine ? picked : null;
@@ -212,6 +214,18 @@ function memberRosterEngine(memberName, root = process.cwd(), options = {}) {
   }
 }
 
+// A person or odd-typed card never runs on an engine.
+function memberCardRunnable(root, name) {
+  const card = findMemberCard(root, name);
+  if (!card) return true;
+  try {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(fs.readFileSync(card, 'utf8'));
+    const match = block ? /^type:\s*(.*)$/m.exec(block[1]) : null;
+    const value = match ? match[1].trim().replace(/^["']|["']$/g, '') : '';
+    return !memberRefusalReason(name, value ? { type: value } : {});
+  } catch { return true; }
+}
+
 // A parked card stays on disk and still runs by name; this view (the roster
 // team block and the boot lineup) just leaves it out.
 function memberCardParked(root, name) {
@@ -232,7 +246,7 @@ function teamRosterView(root = process.cwd(), options = {}) {
       else if (layer.scope === 'project') warnings.push({ file: line.file, line: line.line, text: line.text, message: `there is no team member named ${line.member}, so the line does nothing` });
     }
   }
-  for (const name of [...names]) if (memberCardParked(root, name)) names.delete(name);
+  for (const name of [...names]) if (memberCardParked(root, name) || !memberCardRunnable(root, name)) names.delete(name);
   const rows = [...names].sort().map((name) => {
     const picked = resolveEngineForMember(name, root, { ...options, rosterState: state });
     const line = teamLineFor(state, name);

package/lib/member-scaffold.js

@@ -26,6 +26,8 @@ name: ${name}
 role: ${title}
 description: ${mission}
 version: 1.0.0
+# ai or human; a human member is a person and Atris never acts as them
+type: ai
 
 skills: []
 

package/lib/member-type.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// MEMBER.md `type:` says who a member is. Missing means ai and `agent` is an
+// alias for ai. `human` is a person: Atris can prepare work for them but never
+// acts as them. Any other value keeps the file readable but is never run.
+
+function memberTypeOf(frontmatter) {
+  const raw = frontmatter && frontmatter.type;
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (!value) return { type: 'ai', raw: '', runnable: true };
+  const lowered = value.toLowerCase();
+  if (lowered === 'ai' || lowered === 'agent') return { type: 'ai', raw: value, runnable: true };
+  if (lowered === 'human') return { type: 'human', raw: value, runnable: false };
+  return { type: 'other', raw: value, runnable: false };
+}
+
+// Plain sentence for why a member will not run; '' when it can run.
+function memberRefusalReason(name, frontmatter) {
+  const info = memberTypeOf(frontmatter);
+  if (info.runnable) return '';
+  if (info.type === 'human') {
+    return `${name} is a person, not an AI teammate; Atris can prepare work for them but cannot act as them`;
+  }
+  return `${name} has type '${info.raw}', which is neither ai nor human, so Atris won't run it`;
+}
+
+module.exports = { memberTypeOf, memberRefusalReason };

package/lib/runner-command.js

@@ -38,10 +38,12 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
     efforts: CLAUDE_EFFORTS,
   }),
   // No -m or effort unless the roster pins one: codex then reads its own
-  // ~/.codex/config.toml, which is what the roster view reports.
+  // ~/.codex/config.toml, which is what the roster view reports. Codex runs
+  // only OpenAI models, so a claude model name never reaches it.
   codex: Object.freeze({
     bin: 'codex',
     model: '',
+    ownModelsOnly: true,
     commandTemplate: '{bin} exec {pinnedModelFlag} {pinnedEffortFlag} {prompt}',
     effortFlag: '-c model_reasoning_effort=',
     efforts: Object.freeze(['low', 'medium', 'high', 'xhigh']),
@@ -211,6 +213,19 @@ function resolvePinnedRunnerModel(mission) {
   return explicit || runnerProfileValue('model');
 }
 
+// The model an engine is launched with. An engine that runs only its own
+// vendor's models drops a claude model name (a mission's stored default, a
+// claude env pin) and rides its own default instead.
+function runnerModelFor(engineId, model) {
+  const value = String(model || '').trim();
+  const name = String(engineId || '').trim().toLowerCase();
+  const def = RUNNER_PROFILE_DEFS[RUNNER_PROFILE_ALIASES[name] || name];
+  if (!value || !def || !def.ownModelsOnly) return value;
+  // Required here, not at the top: engine-registry requires this file.
+  const { isClaudeFamilyModel } = require('./engine-registry');
+  return isClaudeFamilyModel(value) ? '' : value;
+}
+
 function resolveClaudeRunnerBin() {
   const env = firstConfiguredEnv(['ATRIS_RUNNER_BIN']);
   if (env) return env;
@@ -265,6 +280,14 @@ function renderRunnerCommandTemplate(template, { promptFile, allowedTools, model
   // The pinned flags take their leading space with them, so an unpinned
   // launch reads exactly like the template without the placeholders.
   template = template.replace(/\s*\{pinnedModelFlag\}/g, pinnedModel ? ` --model ${shellWord(pinnedModel)}` : '');
+  // A model dropped for an engine that cannot run it leaves no gap either,
+  // and a literal "--model {model}", "-m{model}" or a quoted "{model}" goes
+  // with it, quotes and all.
+  if (!model) {
+    template = template
+      .replace(/\s*\{modelFlag\}/g, '')
+      .replace(/\s*(?:--model|-m)(?:\s+|=)?(["']?)\{model\}\1/g, '');
+  }
   // Checked even when the template has no slot, so an engine that cannot
   // take effort refuses instead of running at its default.
   const effortFlag = runnerEffortFlag(effort);
@@ -299,7 +322,18 @@ function buildRunnerCommand({ promptFile, allowedTools, model, effort } = {}) {
   const resolved = resolveClaudeRunnerModel({ model });
   const template = resolveClaudeRunnerCommandTemplate();
   if (template) {
-    return renderRunnerCommandTemplate(template, { promptFile, allowedTools, model: resolved, pinnedModel: resolvePinnedRunnerModel({ model }), effort });
+    // Both the profile and the program that actually runs count: a runner
+    // bin named codex (or a path ending in it) is codex under any profile.
+    const profile = resolveRunnerProfileName();
+    const binName = String(resolveClaudeRunnerBin()).split(/[\\/]/).pop();
+    const modelFor = (value) => runnerModelFor(binName, runnerModelFor(profile, value));
+    return renderRunnerCommandTemplate(template, {
+      promptFile,
+      allowedTools,
+      model: modelFor(resolved),
+      pinnedModel: modelFor(resolvePinnedRunnerModel({ model })),
+      effort,
+    });
   }
   const safePath = String(promptFile).replace(/'/g, "'\\''");
   let cmd = `${shellWord(resolveClaudeRunnerBin())} -p "$(cat '${safePath}')" --model ${shellWord(resolved)}`;
@@ -339,6 +373,7 @@ module.exports = {
   resolveRunnerProfile,
   resolveClaudeRunnerModel,
   resolvePinnedRunnerModel,
+  runnerModelFor,
   resolveClaudeRunnerBin,
   resolveClaudeRunnerCommandTemplate,
   buildRunnerAvailabilityCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.62.0",
+  "version": "3.63.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

@@ -4,7 +4,8 @@
 # No captions: if mlx_whisper is installed (uv tool install mlx-whisper, Apple
 # silicon), the audio is transcribed on this machine instead. Otherwise the
 # script prints the paid command. ATRIS_YTNOTES_LOCAL_TRANSCRIBE=0 turns it off.
-# Engines: auto (default: Gemini Flash through agy, Haiku if that fails),
+# Engines: auto (default: fastest installed writer that answers: Gemini
+# Flash through agy, then Haiku, Codex, Cursor),
 # gemini, haiku, atris-fast, grok, codex, cursor. ATRIS_YTNOTES_ENGINE sets the default.
 # Outputs: $WORK/yt_${ID}.clean.txt (transcript), $WORK/yt_${ID}.md (notes).
 set -euo pipefail
@@ -39,6 +40,30 @@ cd "$WORK"
 # #t= timestamp is stripped so leftover yt_<id> files still match. When VTT is
 # gone, leftover yt_<id>.clean.txt from a prior notes run is still a keep.
 # Another video's leftover clean.txt is not invent-keep.
+if ! command -v yt-dlp >/dev/null 2>&1; then
+  echo "This computer is missing yt-dlp, the free tool that reads YouTube captions." >&2
+  echo "Install it, then run the same command again:" >&2
+  echo "  Mac: brew install yt-dlp    Any computer: pipx install yt-dlp" >&2
+  exit 2
+fi
+
+# YouTube blocks old yt-dlp copies, and the failure looks like "no captions".
+# Warn when the version date (YYYY.MM.DD, maybe .N) is too old; keep going.
+# A version that does not parse stays silent.
+YTDLP_VERSION=$(yt-dlp --version 2>/dev/null) || true
+YTDLP_AGE=$(perl -MTime::Local -e '
+  my ($v, $max) = @ARGV;
+  exit 0 unless $max =~ /\A\d+\z/;
+  my ($y, $m, $d) = $v =~ /\A\s*(\d{4})\.(\d{1,2})\.(\d{1,2})(?:\.\d+)?\s*\z/ or exit 0;
+  my $t = eval { timelocal(0, 0, 12, $d, $m - 1, $y) };
+  exit 0 unless defined $t;
+  my $age = int((time - $t) / 86400);
+  print $age if $age > $max;
+' "$YTDLP_VERSION" "${ATRIS_YTNOTES_YTDLP_MAX_AGE_DAYS:-60}" 2>/dev/null) || true
+if [ -n "$YTDLP_AGE" ]; then
+  echo "Your yt-dlp is $YTDLP_AGE days old, and YouTube often blocks old copies. Update it: brew upgrade yt-dlp (Mac) or pipx upgrade yt-dlp" >&2
+fi
+
 existing=""
 for name in yt_*.en-orig.vtt yt_*.en.vtt yt_*.en-US.vtt yt_*.en-GB.vtt; do
   [ -e "$name" ] || continue
@@ -262,7 +287,7 @@ $TRANSCRIPT"
 run_with_timeout() {
   local seconds="$1"
   shift
-  perl -e '$seconds = shift @ARGV; alarm $seconds; exec @ARGV' "$seconds" "$@"
+  perl -e '$seconds = shift @ARGV; alarm $seconds; exec @ARGV or do { print STDERR "$ARGV[0]: not installed\n"; exit 127 }' "$seconds" "$@"
 }
 
 run_atris_fast() {
@@ -358,16 +383,41 @@ run_gemini() {
     --effort low --print-timeout 110s </dev/null
 }
 
-# Fastest writer that answers: Gemini, then Haiku. Buffered so a failed or
-# empty Gemini answer never reaches the notes file.
+# Fastest installed writer that answers: Gemini, Haiku, Codex, Cursor.
+# Buffered so a failed or empty answer never reaches the notes file.
+AUTO_WRITERS="agy:Gemini claude:Haiku codex:Codex cursor-agent:Cursor"
+
+run_writer() {
+  case "$1" in
+    agy) run_gemini ;;
+    claude) run_haiku ;;
+    codex) run_with_timeout 240 codex exec --sandbox read-only --skip-git-repo-check "$PROMPT" </dev/null ;;
+    cursor-agent) run_with_timeout 240 cursor-agent --trust -p "$PROMPT" ;;
+  esac
+}
+
 run_auto() {
-  local out=""
-  if out=$(run_gemini 2>"$WORK/yt_${ID}.engine.err") && printf '%s' "$out" | grep -q '[[:alnum:]]'; then
-    printf '%s\n' "$out"
-    return 0
+  local entry cmd label out tried=""
+  for entry in $AUTO_WRITERS; do
+    cmd="${entry%%:*}"
+    label="${entry#*:}"
+    command -v "$cmd" >/dev/null 2>&1 || continue
+    if [ -n "$tried" ]; then
+      echo "$tried did not answer; writing the notes with $label instead." >&2
+    fi
+    if out=$(run_writer "$cmd" 2>>"$WORK/yt_${ID}.engine.err") && printf '%s' "$out" | grep -q '[[:alnum:]]'; then
+      printf '%s\n' "$out"
+      echo "notes by $label" >&2
+      return 0
+    fi
+    tried="$label"
+  done
+  if [ -n "$tried" ]; then
+    echo "$tried did not answer, and no other AI writer is installed." >&2
+  else
+    echo "No AI writer is installed on this computer. Install one of: Claude Code (claude), Antigravity (agy), Codex (codex), Cursor (cursor-agent)." >&2
   fi
-  echo "Gemini did not answer; writing the notes with Haiku instead." >&2
-  run_haiku
+  return 3
 }
 
 {
@@ -385,10 +435,20 @@ run_auto() {
       run_gemini
       ;;
     grok)   run_grok ;;
-    codex)  run_with_timeout 240 codex exec --sandbox read-only --skip-git-repo-check "$PROMPT" </dev/null ;;
-    cursor) run_with_timeout 240 cursor-agent --trust -p "$PROMPT" ;;
+    codex)  run_writer codex ;;
+    cursor) run_writer cursor-agent ;;
     *) echo "unknown engine: $ENGINE (auto|gemini|haiku|atris-fast|grok|codex|cursor)" >&2; exit 1 ;;
   esac
-} | perl -0pe 's/\A.*?(?=# )//s' | tee "yt_${ID}.md"
+} | perl -0pe 's/\A.*?(?=# )//s' > "yt_${ID}.md" || true
+
+if ! grep -q '[[:alnum:]]' "yt_${ID}.md"; then
+  rm -f "yt_${ID}.md"
+  echo "No notes were written. The transcript is saved at $WORK/yt_${ID}.clean.txt" >&2
+  echo "Paid notes, 5 credits, refunded if it fails: atris youtube process \"$URL\"" >&2
+  exit 3
+fi
+# auto names its writer above; a pinned engine is named here.
+[ "$ENGINE" = "auto" ] || echo "notes by $ENGINE" >&2
+cat "yt_${ID}.md"
 
 node "$SCRIPT_DIR/ytquote-repair.js" "yt_${ID}.md" "yt_${ID}.clean.txt"