atris 3.61.0 → 3.63.0

package/commands/worktree.js

@@ -6,6 +6,7 @@ const { spawnSync } = require('child_process');
 const { hasFlag, readFlag } = require('../lib/arg-parser');
 const { stampLatestOpenBriefForWorktree } = require('../lib/brief-ledger');
 const { isConductorArtifact } = require('../lib/conductor-artifacts');
+const { fixMapDocs } = require('../lib/map-refs');
 const close = require('./close');
 
 const REGEN_ADAPTER_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
@@ -641,6 +642,7 @@ function shipHelp() {
   console.log('');
   console.log('  --target <ref>  override the default landing target (default: branch atris-base, else origin default branch)');
   console.log('  --local         merge into the local primary checkout instead of pushing and opening a PR');
+  console.log('  --no-map-refresh  skip the automatic refresh of moved map line references');
   console.log('  unstaged regenerated adapter files are skipped unless staged first or named in --message');
   console.log('  recommended flight verify: npm run test:fast && node --test <focused files>');
 }
@@ -725,6 +727,35 @@ function runShipHealthCheck(workspaceRoot, options = {}) {
   }
 }
 
+const MAP_REFRESH_COMMIT_MESSAGE = 'Refresh map references that moved';
+const MAP_REFRESH_TRAILER = 'Co-authored-by: Atris <299057014+atris-builder[bot]@users.noreply.github.com>';
+
+// Rewrites map line refs whose code moved (the same fix `atris doc-health
+// --fix-refs` applies), then commits only the rewritten map files. A human-only
+// remainder or an error never blocks the ship; pass --no-map-refresh to skip.
+function refreshMovedMapRefs(root, args = []) {
+  if (hasFlag(args, '--no-map-refresh')) return { skipped: true, refreshed: 0, left: 0 };
+  try {
+    const { changes, left } = fixMapDocs(root);
+    if (changes.length) {
+      const docs = [...new Set(changes.map(change => change.doc))];
+      runGit(['add', '--', ...docs], { cwd: root });
+      runGit(['commit', '-m', MAP_REFRESH_COMMIT_MESSAGE, '-m', MAP_REFRESH_TRAILER], { cwd: root });
+      console.log(`map: refreshed ${changes.length} moved references`);
+    } else {
+      console.log('map: references current');
+    }
+    if (left.length) {
+      console.log(`map: ${left.length} references need a human; run atris doc-health --fix-refs to see them`);
+    }
+    return { skipped: false, refreshed: changes.length, left: left.length };
+  } catch (error) {
+    const message = String((error && error.message) || error).toLowerCase().replace(/\s+/g, ' ').trim();
+    console.log(`map: refresh skipped (${message}); the ship continues`);
+    return { skipped: false, refreshed: 0, left: 0, error };
+  }
+}
+
 function shipWorktree(args) {
   if (hasFlag(args, '--help') || hasFlag(args, '-h') || args[0] === 'help') {
     shipHelp();
@@ -816,6 +847,12 @@ function shipWorktree(args) {
     if (!dryRun && !proofTreeMatches('head')) return 3;
   }
 
+  if (dryRun) {
+    console.log('map: skipped (dry-run)');
+  } else {
+    refreshMovedMapRefs(root, args);
+  }
+
   if (verify) {
     const beforeVerify = dryRun ? [] : statusSnapshot(root);
     console.log(`verify: ${verify}`);
@@ -1227,6 +1264,7 @@ function help() {
   console.log('  atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local]');
   console.log('    --target <ref>  override the default landing target (default: branch atris-base, else origin default branch)');
   console.log('    --local         merge into the local primary checkout instead of pushing and opening a PR');
+  console.log('    --no-map-refresh  skip the automatic refresh of moved map line references');
   console.log('    recommended verify: npm run test:fast && node --test <focused files>');
   console.log('  atris worktree status');
   console.log('  atris worktree guard [--allow-primary] [--allow-dirty]');
@@ -1270,6 +1308,7 @@ module.exports = {
   parseAgentFlightName,
   parseWorktrees,
   normalizeTargetRef,
+  refreshMovedMapRefs,
   slugify,
   taskTokens,
   statusCounts,

package/commands/youtube.js

@@ -7,7 +7,7 @@ const os = require('os');
 const path = require('path');
 const https = require('https');
 
-const YTNOTES_USAGE = 'usage: ytnotes <youtube-url> [youtube-url-or-playlist...] [haiku|atris-fast|gemini|grok|codex|cursor]';
+const YTNOTES_USAGE = 'usage: ytnotes <youtube-url> [youtube-url-or-playlist...] [auto|gemini|haiku|atris-fast|grok|codex|cursor]';
 const YTNOTES_HINT = 'zero credits, local captions + a fast engine';
 const NOTES_PLAYLIST_CAP = 10;
 
@@ -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('');
@@ -236,23 +238,31 @@ function captionHostAllowed(urlString) {
   }
 }
 
-function chooseCaptionTrack(info = {}) {
-  const preferred = ['en', 'en-orig', 'en-US', 'en-GB'];
-  const chooseFrom = (trackSets = {}) => {
-    for (const language of preferred) {
-      for (const track of trackSets[language] || []) {
-        if (track?.url && ['json3', 'vtt', 'srv3', 'ttml'].includes(track.ext)) return { language, track };
-      }
+// Caption tracks in the order to try them. Human subtitles first, then the
+// auto track in the language actually spoken ("en-orig", "es-orig"). YouTube's
+// machine-translated tracks (plain "en" on most English videos) are rate
+// limited with HTTP 429, so they only come after every real track.
+function captionTrackCandidates(info = {}) {
+  const candidates = [];
+  const add = (trackSets = {}, languages) => {
+    for (const language of languages) {
+      if (language === 'live_chat') continue;
+      const tracks = (trackSets[language] || []).filter((track) => track?.url);
+      const track = tracks.find((t) => ['json3', 'vtt', 'srv3', 'ttml'].includes(t.ext)) || tracks[0];
+      if (track && !candidates.some((c) => c.track === track)) candidates.push({ language, track });
     }
-    for (const [language, tracks] of Object.entries(trackSets)) {
-      for (const track of tracks || []) {
-        if (track?.url) return { language, track };
-      }
-    }
-    return null;
   };
+  const manual = info.subtitles || {};
+  const auto = info.automatic_captions || {};
+  add(manual, ['en', 'en-US', 'en-GB', ...Object.keys(manual).filter((l) => l.startsWith('en-'))]);
+  add(manual, Object.keys(manual));
+  add(auto, ['en-orig', ...Object.keys(auto).filter((l) => l.endsWith('-orig'))]);
+  add(auto, ['en', 'en-US', 'en-GB']);
+  return candidates;
+}
 
-  return chooseFrom(info.subtitles) || chooseFrom(info.automatic_captions);
+function chooseCaptionTrack(info = {}) {
+  return captionTrackCandidates(info)[0] || null;
 }
 
 function formatTimestampFromMs(ms) {
@@ -478,12 +488,14 @@ function parseYtDlpInfoJson(result) {
 }
 
 function localCaptionNames(id) {
-  // scripts/det/ytnotes keeps these VTT names plus leftover yt_<id>.clean.txt.
+  // scripts/det/ytnotes keeps these VTT names (.local.vtt = transcribed on this
+  // machine when the video had no captions) plus leftover yt_<id>.clean.txt.
   return [
     `yt_${id}.en.vtt`,
     `yt_${id}.en-orig.vtt`,
     `yt_${id}.en-US.vtt`,
     `yt_${id}.en-GB.vtt`,
+    `yt_${id}.local.vtt`,
     `yt_${id}.clean.txt`,
   ];
 }
@@ -521,14 +533,14 @@ function readLocalCaptionText({ url, id, workDir } = {}) {
 
 async function loadCaptionRaw(info, youtubeUrl, deps = {}) {
   const payload = info && typeof info === 'object' ? info : {};
-  const selected = chooseCaptionTrack(payload);
-  let raw = '';
-  if (selected?.track?.url) {
-    raw = await (deps.fetchCaptionText || fetchCaptionText)(selected.track.url);
-  }
-  if (String(raw || '').trim()) {
-    return { raw, language: selected?.language || 'unknown' };
-  }
+  const fetchText = deps.fetchCaptionText || fetchCaptionText;
+  // A blocked track (429) falls through to the next one instead of failing.
+  const candidates = captionTrackCandidates(payload).slice(0, 4);
+  for (const candidate of candidates) {
+    const raw = await fetchText(candidate.track.url);
+    if (String(raw || '').trim()) return { raw, language: candidate.language };
+  }
+  const selected = candidates[0];
   const local = readLocalCaptionText({
     url: youtubeUrl,
     id: payload.id,
@@ -559,7 +571,7 @@ async function extractLocalTranscript(youtubeUrl, deps = {}) {
   const result = runner('yt-dlp', ytDlpInfoArgs(youtubeUrl), {
     encoding: 'utf8',
     timeout: 20000,
-    maxBuffer: 10 * 1024 * 1024,
+    maxBuffer: 64 * 1024 * 1024,
   });
   const info = parseYtDlpInfoJson(result);
   const loaded = await loadCaptionRaw(info, youtubeUrl, deps);
@@ -3697,7 +3709,7 @@ async function extractTeachSource(youtubeUrl, deps = {}) {
   const result = runner('yt-dlp', ytDlpInfoArgs(youtubeUrl), {
     encoding: 'utf8',
     timeout: 20000,
-    maxBuffer: 10 * 1024 * 1024,
+    maxBuffer: 64 * 1024 * 1024,
   });
   const info = parseYtDlpInfoJson(result);
   const loaded = await loadCaptionRaw(info, youtubeUrl, deps);
@@ -3841,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') {
@@ -3870,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);
@@ -3968,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-ask.js

@@ -64,7 +64,43 @@ function parseBoundedInteger(raw, flag, min, max) {
   return value;
 }
 
-function normalizeAskJob(job, index) {
+// The ask job's roster line for this engine. Questions are not searches, so
+// a bare ask rides the engine's own default model; only an `## ask` section
+// that lists this engine as a live worker pins its model and effort. Layers
+// resolve the way every job resolves: this session, this project, all
+// projects. Never throws.
+function askRosterPin(engine, root) {
+  try {
+    const {
+      ENGINE_JOBS,
+      ROSTER_LAYERS,
+      readEngineRegistry,
+      readRosterState,
+      rosterWorkerWalk,
+    } = require('./engine-registry');
+    const registry = readEngineRegistry(root, { persist: false });
+    const state = readRosterState(root, { registry });
+    for (const layer of ROSTER_LAYERS) {
+      const pick = state[layer] && state[layer].picks && state[layer].picks.ask;
+      if (!pick || typeof pick !== 'object') continue;
+      const role = ENGINE_JOBS[pick.like] || 'navigator';
+      const step = rosterWorkerWalk(pick, role, registry).find(
+        (entry) => !entry.skip && entry.engine && entry.engine.id === engine
+      );
+      if (!step) continue;
+      const pin = {};
+      for (const field of ['roster_model', 'roster_effort']) {
+        if (step.engine[field]) pin[field] = step.engine[field];
+      }
+      return pin;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizeAskJob(job, index, pinFor = null) {
   if (!job || typeof job !== 'object' || Array.isArray(job)) {
     throw new Error(`job ${index + 1} must be an object`);
   }
@@ -78,10 +114,15 @@ function normalizeAskJob(job, index) {
   if (Buffer.byteLength(prompt) > MAX_ASK_PROMPT_BYTES) {
     throw new Error(`job ${index + 1} prompt must be ${MAX_ASK_PROMPT_BYTES} bytes or fewer`);
   }
-  const model = resolveAskModel(engine, job.model);
+  // No model named: the ask line's model and effort ride along when the
+  // roster has one for this engine. A named model means the roster does not
+  // decide.
+  const pin = !String(job.model || '').trim() && pinFor ? pinFor(engine) : {};
+  const model = resolveAskModel(engine, job.model || pin.roster_model || '');
+  const effort = askEffortArgs(engine, pin.roster_effort).length ? String(pin.roster_effort).trim().toLowerCase() : '';
   const label = String(job.label || '').trim();
   if (label.length > 80) throw new Error(`job ${index + 1} label must be 80 characters or fewer`);
-  return { engine, model, prompt, label };
+  return { engine, model, ...(effort ? { effort } : {}), prompt, label };
 }
 
 function labelAskJobs(jobs) {
@@ -166,14 +207,14 @@ function parseEngineAskArgs(args, { root = process.cwd(), readFile = fs.readFile
       throw new Error(`could not read --jobs ${jobsFile}: ${error.message}`);
     }
     if (!Array.isArray(parsed)) throw new Error('--jobs must contain a json array');
-    jobs = parsed.map(normalizeAskJob);
+    jobs = parsed.map((job, index) => normalizeAskJob(job, index, (engine) => askRosterPin(engine, root)));
   } else {
     if (!commonPrompt || !requestedEngines.length) throw new Error(askUsage());
     jobs = requestedEngines.map((requestedEngine, index) => normalizeAskJob({
       engine: requestedEngine,
       model: requestedModel,
       prompt: commonPrompt,
-    }, index));
+    }, index, (engine) => askRosterPin(engine, root)));
   }
 
   if (!jobs.length) throw new Error('at least one engine ask job is required');
@@ -205,8 +246,21 @@ function resolveAskModel(engine, modelName = '') {
   return RUNNER_PROFILE_DEFS[engine]?.model || DEFAULT_CLAUDE_RUNNER_MODEL;
 }
 
+// The effort flag as argv, from the same profile table the runners use
+// ("--effort high", "-c model_reasoning_effort=high"). Empty when the engine
+// takes no effort or not that word.
+function askEffortArgs(engine, effort) {
+  const word = String(effort || '').trim().toLowerCase();
+  const profile = RUNNER_PROFILE_DEFS[engine];
+  if (!word || !profile || !profile.effortFlag || !(profile.efforts || []).includes(word)) return [];
+  const parts = profile.effortFlag.split(/\s+/).filter(Boolean);
+  const last = parts.pop();
+  return last.endsWith('=') ? [...parts, `${last}${word}`] : [...parts, last, word];
+}
+
 function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
   timeoutMs = DEFAULT_ASK_TIMEOUT_MS,
+  effort = '',
 } = {}) {
   const engine = canonicalEngineName(engineName);
   const profile = RUNNER_PROFILE_DEFS[engine];
@@ -214,6 +268,7 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
   const model = resolveAskModel(engine, modelName);
   assertAskModelSupported(engine, model);
   const request = guardedPrompt(prompt);
+  const effortArgs = askEffortArgs(engine, effort);
 
   if (engine === 'atris-fast' || engine === 'composer') {
     return { engine, bin: profile.bin, args: ['--fast', '--cloud', '--print', request] };
@@ -225,6 +280,7 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
       args: [
         '-p', request,
         '--model', model || profile.model || DEFAULT_CLAUDE_RUNNER_MODEL,
+        ...effortArgs,
         '--tools', 'Read,Glob,Grep,WebSearch,WebFetch',
         '--permission-mode', 'plan',
         '--no-session-persistence',
@@ -235,7 +291,7 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
     return {
       engine,
       bin: profile.bin,
-      args: ['exec', ...(model ? ['-m', model] : []), '--sandbox', 'read-only', '--ephemeral', '--ignore-user-config', '--ignore-rules', '--color', 'never', request],
+      args: ['exec', ...(model ? ['-m', model] : []), ...effortArgs, '--sandbox', 'read-only', '--ephemeral', '--ignore-user-config', '--ignore-rules', '--color', 'never', request],
     };
   }
   if (engine === 'cursor') {
@@ -252,7 +308,7 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
     return {
       engine,
       bin: profile.bin,
-      args: ['--no-memory', '--no-subagents', '--permission-mode', 'plan', '--sandbox', 'read-only', ...(model ? ['--model', model] : []), '-p', request],
+      args: ['--no-memory', '--no-subagents', '--permission-mode', 'plan', '--sandbox', 'read-only', ...(model ? ['--model', model] : []), ...effortArgs, '-p', request],
     };
   }
   if (engine === 'agy') {
@@ -269,6 +325,7 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
         '--dangerously-skip-permissions',
         '--print-timeout', `${Math.max(1, Math.ceil(timeoutMs / 1000))}s`,
         ...(model ? ['--model', model] : []),
+        ...effortArgs,
         '-p', request,
       ],
     };
@@ -283,7 +340,7 @@ function buildReadOnlyEngineInvocation(engineName, prompt, modelName = '', {
   if (engine === 'opencode') {
     // `run` with a message is headless print mode; the built-in plan agent
     // keeps the ask read-only (verified live 2026-08-21, ~7s per lookup).
-    return { engine, bin: profile.bin, args: ['run', '--agent', 'plan', ...(model ? ['-m', model] : []), request] };
+    return { engine, bin: profile.bin, args: ['run', '--agent', 'plan', ...(model ? ['-m', model] : []), ...effortArgs, request] };
   }
   throw new Error(`engine ask has no read-only command for ${engine}`);
 }
@@ -480,7 +537,7 @@ async function runEngineAskJobs(jobs, {
   const answers = new Array(jobs.length);
   let nextIndex = 0;
   const execute = executeAskJob || (async (job) => {
-    const invocation = buildReadOnlyEngineInvocation(job.engine, job.prompt, job.model, { timeoutMs });
+    const invocation = buildReadOnlyEngineInvocation(job.engine, job.prompt, job.model, { timeoutMs, effort: job.effort || '' });
     return runAskProcess(invocation, { cwd: invocation.cwd || root, timeoutMs, signal, onOutputChunk });
   });
   const workerCount = Math.min(concurrency, jobs.length);
@@ -534,6 +591,51 @@ function recordEngineAskHealth(answers, root) {
   }
 }
 
+// One run-record line per answer, job "ask": the worker as it ran, its
+// seconds, how it ended, and tokens when printed. A cancelled ask is the
+// operator's stop, not the engine's result, so it writes nothing.
+function recordEngineAskRuns(answers, root, { timeoutMs = 0, startedAt = '' } = {}) {
+  let appendRosterRun;
+  let parseRunUsage;
+  let engineRunsView;
+  try {
+    ({ appendRosterRun, parseRunUsage } = require('./roster-runs'));
+    ({ engineRunsView } = require('./roster-models'));
+  } catch {
+    return;
+  }
+  const maxSeconds = Math.round(Number(timeoutMs) / 1000) || 0;
+  for (const answer of answers) {
+    if (!answer || answer.cancelled || answer.reason === 'cancelled') continue;
+    let outcome = 'landed';
+    let detail = '';
+    if (answer.timed_out || answer.reason === 'timeout') {
+      outcome = 'stalled';
+      detail = maxSeconds >= 60 ? `stalled at ${Math.round(maxSeconds / 60)} min` : `stalled at ${maxSeconds}s`;
+    } else if (!answer.ok) {
+      const credit = engineFailureHealthStatus({ ...answer, status: 'errored' }) === 'credit_out';
+      outcome = credit ? 'credit out' : 'failed';
+      detail = credit ? 'the engine hit its usage limit' : compactFailure(answer);
+    }
+    try {
+      appendRosterRun(root, {
+        at: startedAt || new Date(Date.now() - (Number(answer.duration_ms) || 0)).toISOString(),
+        job: 'ask',
+        engine: answer.engine,
+        model: answer.model || engineRunsView(answer.engine).model || '',
+        ...(answer.effort ? { effort: answer.effort } : {}),
+        ...(maxSeconds ? { max_seconds: maxSeconds } : {}),
+        seconds: Math.max(0, (Number(answer.duration_ms) || 0) / 1000),
+        outcome,
+        ...(detail ? { detail } : {}),
+        ...(answer.label ? { task: answer.label } : {}),
+        source: 'ask',
+        ...parseRunUsage({ stdout: answer.stdout, stderr: answer.stderr }),
+      });
+    } catch { /* best effort */ }
+  }
+}
+
 function engineAskReceipt(answers, { concurrency, timeoutMs, at = new Date().toISOString() }) {
   const receiptAnswers = answers.map((answer) => ({ ...answer, status: answerStatus(answer) }));
   const answered = receiptAnswers.filter((answer) => answer.status === 'answered').length;
@@ -670,6 +772,7 @@ async function runEngineAskCommand(args, root = process.cwd(), deps = {}) {
       onOutputChunk: (chunk, stream) => appendLiveLog(liveLogPath, chunk, stream),
     });
     recordEngineAskHealth(answers, root);
+    recordEngineAskRuns(answers, root, { timeoutMs: parsed.timeoutMs, startedAt });
     const receipt = engineAskReceipt(answers, {
       concurrency: parsed.concurrency,
       timeoutMs: parsed.timeoutMs,