atris 3.58.5 → 3.58.7

package/lib/task-list-keeper.js

@@ -0,0 +1,192 @@
+'use strict';
+
+// Puts finished and untouched tasks off the visible list. History stays
+// archived. A current list costs one indexed lookup and no writes.
+
+const fs = require('fs');
+const path = require('path');
+const taskDb = require('./task-db');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const OPEN_STATUSES = new Set(['open', 'claimed', 'review']);
+
+// Failed rows already leave the today screen after 7 days. They stay
+// findable until 30 days, then they leave the list too.
+const IDLE_LIMITS_MS = {
+  claimed: 3 * DAY_MS,
+  open: 14 * DAY_MS,
+  review: 14 * DAY_MS,
+  failed: 30 * DAY_MS,
+};
+
+const REASONS = {
+  done: 'finished work left the list',
+  claimed: 'claimed work sat untouched for 3 days',
+  open: 'waiting work sat untouched for 14 days',
+  review: 'review sat untouched for 14 days',
+  failed: 'failed work sat untouched for 30 days',
+};
+
+const CANDIDATE_SQL = `
+  SELECT id, title, status, tag, updated_at, created_at, done_at, metadata
+    FROM tasks
+   WHERE workspace_root = ? AND status = 'done'
+  UNION ALL
+  SELECT id, title, status, tag, updated_at, created_at, done_at, metadata
+    FROM tasks
+   WHERE workspace_root = ? AND status = 'claimed' AND updated_at < ?
+  UNION ALL
+  SELECT id, title, status, tag, updated_at, created_at, done_at, metadata
+    FROM tasks
+   WHERE workspace_root = ? AND status = 'open' AND updated_at < ?
+  UNION ALL
+  SELECT id, title, status, tag, updated_at, created_at, done_at, metadata
+    FROM tasks
+   WHERE workspace_root = ? AND status = 'review' AND updated_at < ?
+  UNION ALL
+  SELECT id, title, status, tag, updated_at, created_at, done_at, metadata
+    FROM tasks
+   WHERE workspace_root = ? AND status = 'failed' AND updated_at < ?
+  UNION ALL
+  SELECT id, title, status, tag, updated_at, created_at, done_at, metadata
+    FROM tasks
+   WHERE workspace_root = ? AND tag = 'mission-blocker' AND status IN ('open', 'claimed', 'review')
+`;
+
+function actorName(actor) {
+  return actor || process.env.ATRIS_AGENT_ID || process.env.USER || 'task-list';
+}
+
+function decisionFor(row, now) {
+  if (!row || row.status === 'archived') return null;
+  if (row.status === 'done') {
+    return { reason: REASONS.done, fromDone: true, fromFailed: false };
+  }
+  if (!Object.prototype.hasOwnProperty.call(IDLE_LIMITS_MS, row.status)) return null;
+  const at = Number(row.updated_at || row.created_at || 0);
+  if (!((now - at) > IDLE_LIMITS_MS[row.status])) return null;
+  return { reason: REASONS[row.status], fromDone: false, fromFailed: row.status === 'failed' };
+}
+
+function selectCandidates(db, workspaceRoot, now) {
+  return db.prepare(CANDIDATE_SQL).all(
+    workspaceRoot,
+    workspaceRoot, now - IDLE_LIMITS_MS.claimed,
+    workspaceRoot, now - IDLE_LIMITS_MS.open,
+    workspaceRoot, now - IDLE_LIMITS_MS.review,
+    workspaceRoot, now - IDLE_LIMITS_MS.failed,
+    workspaceRoot,
+  );
+}
+
+function blockerFrom(row) {
+  if (!row || row.tag !== 'mission-blocker' || !OPEN_STATUSES.has(row.status)) return null;
+  let metadata = row.metadata;
+  if (typeof metadata === 'string') {
+    try { metadata = JSON.parse(metadata); } catch { metadata = null; }
+  }
+  if (!metadata || !metadata.mission_id || !metadata.mission_blocker_class) return null;
+  return { ...row, metadata };
+}
+
+function loadMissions(workspaceRoot) {
+  try {
+    return require('../commands/mission').listMissions(workspaceRoot) || [];
+  } catch {
+    return [];
+  }
+}
+
+function noteKeep(workspaceRoot, actor, count) {
+  if (!count || !workspaceRoot || !fs.existsSync(path.join(workspaceRoot, 'atris'))) return;
+  try {
+    const now = new Date();
+    const year = String(now.getFullYear());
+    const dir = path.join(workspaceRoot, 'atris', 'logs', year);
+    fs.mkdirSync(dir, { recursive: true });
+    const name = `${year}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}.md`;
+    const stamp = now.toTimeString().slice(0, 5);
+    fs.appendFileSync(path.join(dir, name), `## ${stamp} · Task list kept\n- count: ${count}\n- actor: ${actor}\n\n`);
+  } catch {
+    // The rows are already off the list. A missed note should not put them back.
+  }
+}
+
+function keepTaskList(db, { workspaceRoot, actor, now = Date.now(), missions } = {}) {
+  const who = actorName(actor);
+  const seen = new Set();
+  const toArchive = [];
+  const blockers = [];
+  for (const row of selectCandidates(db, workspaceRoot, now)) {
+    if (!row || seen.has(row.id)) continue;
+    seen.add(row.id);
+    const decision = decisionFor(row, now);
+    if (decision) {
+      toArchive.push({ id: row.id, previous_status: row.status, ...decision });
+      continue;
+    }
+    const blocker = blockerFrom(row);
+    if (blocker) blockers.push(blocker);
+  }
+
+  const missionList = Array.isArray(missions)
+    ? missions
+    : (blockers.length ? loadMissions(workspaceRoot) : []);
+  if (!toArchive.length && !(blockers.length && missionList.length)) {
+    return { put_away: [], reaped: [] };
+  }
+
+  const putAway = [];
+  let reaped = [];
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    for (const item of toArchive) {
+      const result = taskDb.archiveTask(db, {
+        id: item.id,
+        actor: who,
+        reason: item.reason,
+        fromDone: item.fromDone,
+        fromFailed: item.fromFailed,
+        skipLogs: true,
+      });
+      if (result.archived) {
+        putAway.push({ id: item.id, previous_status: item.previous_status, reason: item.reason });
+      }
+    }
+    if (blockers.length && missionList.length) {
+      reaped = taskDb.reapMissionBlockerTasks(db, {
+        workspaceRoot,
+        missions: missionList,
+        actor: who,
+        rows: blockers,
+        skipLogs: true,
+      }).closed || [];
+    }
+    db.exec('COMMIT');
+  } catch (error) {
+    try { db.exec('ROLLBACK'); } catch { /* the original error is the one to surface */ }
+    throw error;
+  }
+  noteKeep(workspaceRoot, who, putAway.length + reaped.length);
+  return { put_away: putAway, reaped };
+}
+
+function keepWorkspaceTaskList(cwd = process.cwd(), { actor } = {}) {
+  const dbPath = taskDb.getDbPath();
+  if (!dbPath || !fs.existsSync(dbPath)) {
+    return { put_away: [], reaped: [], skipped: 'no_db' };
+  }
+  const db = taskDb.open();
+  return keepTaskList(db, {
+    workspaceRoot: taskDb.workspaceRoot(cwd),
+    actor,
+    now: Date.now(),
+  });
+}
+
+module.exports = {
+  DAY_MS,
+  IDLE_LIMITS_MS,
+  keepTaskList,
+  keepWorkspaceTaskList,
+};

package/lib/todo-fallback.js

@@ -80,15 +80,21 @@ function parseSection(content, sectionName) {
     const bracketTaskMatch = line.match(/^- \*\*\[([^\]\n]+)\]\*\*\s+(.+)$/);
     if (bracketTaskMatch) {
       if (current) tasks.push(current);
-      const { allTags, tag } = tagsFromText(bracketTaskMatch[2]);
+      // Compact rows carry display-only verification previews. Never execute
+      // a clipped command; the full command lives in task show or the DB.
+      const titleOnly = content.includes('<!-- ATRIS_TODO_COMPACT:2 -->') && /^(Backlog|Completed)$/i.test(sectionName);
+      const compact = !titleOnly && bracketTaskMatch[2].match(/^(.*?) · ([^·]+?)(?: · verify: (.*))?$/);
+      const title = compact ? compact[1] : bracketTaskMatch[2];
+      const { allTags, tag } = tagsFromText(title);
       current = {
         id: bracketTaskMatch[1],
-        title: cleanTaskTitle(bracketTaskMatch[2]),
+        title: cleanTaskTitle(title),
         tag,
         tags: allTags,
-        claimed: null,
+        claimed: compact && compact[2] !== 'unassigned' ? compact[2].trim() : null,
         stage: null,
         verify: null,
+        ...(compact || titleOnly ? { verify_preview: compact ? compact[3] || null : null } : {}),
       };
       continue;
     }

package/lib/todo.js

@@ -1,6 +1,7 @@
 // SHIM. Same export surface as the legacy markdown parser, but reads from the
 // SQLite task store first when ATRIS_TASK_DB=1 is set, falling back to the
-// pure markdown parser at lib/todo-fallback.js.
+// pure markdown parser at lib/todo-fallback.js. Compact generated boards also
+// consult an existing store so verification previews never replace commands.
 //
 // All 3 callers (commands/autopilot.js, commands/status.js, commands/run.js)
 // inherit the strangler without changing their import path.
@@ -22,12 +23,14 @@ function dbToShimRow(row) {
     ? metadata.verify.trim()
     : null;
   const claimed = row.claimed_by || metadata.claimed || null;
+  const tags = [...new Set([row.tag, ...(Array.isArray(metadata.todo_tags) ? metadata.todo_tags : []),
+    ...(Array.isArray(metadata.tags) ? metadata.tags : [])].filter(Boolean))];
   // Map DB row → the shape the existing consumers expect from parseTodo().
   return {
     id: row.id,
     title: row.title,
-    tag: row.tag || null,
-    tags: row.tag ? [row.tag] : [],
+    tag: tags.includes('endgame') ? 'endgame' : (row.tag || tags[0] || null),
+    tags,
     claimed,
     stage: row.status === 'claimed' ? 'in_progress' : (metadata.stage || null),
     verify,
@@ -38,25 +41,29 @@ function dbToShimRow(row) {
 function dbBuckets(workspaceRoot) {
   const taskDb = require('./task-db');
   const db = taskDb.open();
-  const rows = taskDb.listTasks(db, { workspaceRoot, limit: 500 });
+  const rows = taskDb.withTaskDisplayRefs(taskDb.listTasks(db, { workspaceRoot, limit: 500 }));
   // Need raw source_key for merge dedup, plus the shim shape for callers.
   const backlog = [];
   const inProgress = [];
   const review = [];
   const completed = [];
   const sourceKeys = new Set();
+  const sourceRefs = new Set();
   // Query directly so the shim can dedup against markdown by the strong key
   // even if future list filters hide rows.
   const stmt = db.prepare('SELECT id, source_key FROM tasks WHERE workspace_root = ? AND source_key IS NOT NULL');
   for (const r of stmt.all(workspaceRoot)) sourceKeys.add(r.source_key);
   for (const r of rows) {
+    for (const ref of [r.id, r.display_id, r.legacy_ref, r.metadata?.todo_id]) {
+      if (ref) sourceRefs.add(String(ref).toLowerCase());
+    }
     const shaped = dbToShimRow(r);
     if (r.status === 'open') backlog.push(shaped);
     else if (r.status === 'claimed') inProgress.push(shaped);
     else if (r.status === 'review') review.push(shaped);
     else if (r.status === 'done' || r.status === 'failed') completed.push(shaped);
   }
-  return { backlog, inProgress, review, completed, sourceKeys };
+  return { backlog, inProgress, review, completed, sourceKeys, sourceRefs };
 }
 
 function mergeBuckets(dbBuck, mdBuck, todoPath) {
@@ -71,6 +78,7 @@ function mergeBuckets(dbBuck, mdBuck, todoPath) {
   for (const k of ['backlog', 'inProgress', 'review', 'completed']) {
     for (const r of dbBuck[k]) { out[k].push(r); seenTitles.add(norm(r.title)); }
     for (const r of mdBuck[k]) {
+      if (r.id && dbBuck.sourceRefs?.has(String(r.id).toLowerCase())) continue;
       const sk = todoPath ? taskDb.sourceKey(todoPath, r.title) : null;
       if (sk && dbBuck.sourceKeys && dbBuck.sourceKeys.has(sk)) continue;
       if (seenTitles.has(norm(r.title))) continue;
@@ -81,14 +89,19 @@ function mergeBuckets(dbBuck, mdBuck, todoPath) {
 }
 
 function parseTodo(todoPath) {
-  // Legacy pure-markdown path.
-  if (!TASK_DB_ENABLED) return fallback.parseTodoFile(todoPath);
+  const mdBuck = fallback.parseTodoFile(todoPath);
+  const compact = Object.values(mdBuck).some(rows => rows.some(row => Object.hasOwn(row, 'verify_preview')));
+  // Compact generated boards omit full commands. Resolve them from existing
+  // durable state even without the legacy opt-in, without minting a database.
+  if (!TASK_DB_ENABLED && !compact) return mdBuck;
 
   // DB-first merged view. Workspace scope = directory containing todoPath
   // (or its parent), so the DB stays per-repo.
   const path = require('path');
   const fs = require('fs');
-  const taskDb = require('./task-db');
+  let taskDb;
+  try { taskDb = require('./task-db'); } catch { return mdBuck; }
+  if (!TASK_DB_ENABLED && !fs.existsSync(taskDb.getDbPath())) return mdBuck;
   let workspaceRoot;
   try {
     const todoAbs = path.resolve(todoPath);
@@ -106,9 +119,8 @@ function parseTodo(todoPath) {
   } catch (e) {
     // If sqlite blew up (missing in node, perms), don't break the legacy path.
     if (process.env.ATRIS_DEBUG) console.error('[todo shim] db read failed:', e.message);
-    return fallback.parseTodoFile(todoPath);
+    return mdBuck;
   }
-  const mdBuck = fallback.parseTodoFile(todoPath);
   return mergeBuckets(dbBuck, mdBuck, todoPath);
 }
 

package/mcp/atris-mcp/index.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// atris mcp, a stdio Model Context Protocol server exposing the design API.
+// Tools: design_extract, design_check, design_search.
+// Auth resolves the same way as the CLI: ATRIS_API_KEY, then
+// the logged-in atris token, then ~/.atris/design-api-key.
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import designApi from '../../lib/design-api.js';
+
+const { resolveDesignKey, designRequest, pollDesignJob, billingOf } = designApi;
+
+export const TOOLS = [
+  {
+    name: 'design_extract',
+    description: 'extract a site\'s design system (colors, typography, layout, voice) as json. costs 10 credits, 2 on a cache hit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'site url to extract, e.g. https://stripe.com' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'design_check',
+    description: 'score how closely a page follows a reference brand. costs 20 credits.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source_url: { type: 'string', description: 'page being checked' },
+        reference_url: { type: 'string', description: 'brand url to check against' },
+      },
+      required: ['source_url', 'reference_url'],
+    },
+  },
+  {
+    name: 'design_search',
+    description: 'search brands already extracted by atris design. costs 1 credit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'plain words, e.g. "dark developer tools brand"' },
+        limit: { type: 'number', description: 'max results' },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+function terminal(job) {
+  const s = String((job && job.status) || '').toLowerCase();
+  return s === 'completed' || s === 'failed' || s === 'error' || s === 'succeeded';
+}
+
+function withBilling(data) {
+  const bill = billingOf(data);
+  return {
+    ...(data && typeof data === 'object' ? data : { result: data }),
+    credits_charged: bill.credits,
+    balance_remaining_usd: bill.balanceUsd,
+  };
+}
+
+function ok(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(withBilling(data), null, 2) }] };
+}
+
+function fail(message) {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+async function callApi(pathname, options, key) {
+  const res = await designRequest(pathname, { ...options, key });
+  if (!res.ok) throw new Error(`http ${res.status}: ${res.error || 'request failed'}`);
+  if (!res.data || typeof res.data !== 'object') {
+    throw new Error('the design api returned an empty response');
+  }
+  return res.data;
+}
+
+async function runJob(first, pollPath, key) {
+  if (!first || typeof first !== 'object') {
+    throw new Error('the design api returned an empty response');
+  }
+  let job = first;
+  if (!terminal(job) && !job.id) {
+    throw new Error('the design api returned no job id');
+  }
+  if (!terminal(job) && job.id) {
+    let failures = 0;
+    const polled = await pollDesignJob(async () => {
+      try {
+        const out = await callApi(pollPath, {}, key);
+        failures = 0;
+        return out;
+      } catch (error) {
+        failures += 1;
+        if (failures >= 3) return { status: 'failed', id: job.id, error: (error && error.message) || String(error) };
+        return { status: 'polling' };
+      }
+    });
+    if (polled.timedOut) {
+      throw new Error(`still running after 3 minutes. job id: ${job.id}, poll: ${pollPath}`);
+    }
+    job = polled.job || job;
+  }
+  if (job.status !== 'completed') {
+    throw new Error(`job ${job.id || 'unknown'} did not finish: ${job.error || job.status || 'unknown'} (poll: ${pollPath})`);
+  }
+  return job;
+}
+
+export async function handleTool(name, args = {}, key) {
+  if (name === 'design_extract') {
+    const url = String(args.url || '').trim();
+    if (!url) return fail('design_extract needs a url');
+    const first = await callApi('/design/extractions', { method: 'POST', body: { url } }, key);
+    return ok(await runJob(first, `/design/extractions/${first.id}`, key));
+  }
+  if (name === 'design_check') {
+    const source = String(args.source_url || '').trim();
+    const reference = String(args.reference_url || '').trim();
+    if (!source || !reference) return fail('design_check needs source_url and reference_url');
+    const first = await callApi('/design/adherence', {
+      method: 'POST',
+      body: { source_url: source, reference_url: reference },
+    }, key);
+    return ok(await runJob(first, `/design/adherence/${first.id}`, key));
+  }
+  if (name === 'design_search') {
+    const query = String(args.query || '').trim();
+    if (!query) return fail('design_search needs a query');
+    const body = { query };
+    if (Number.isInteger(args.limit) && args.limit > 0) body.limit = args.limit;
+    return ok(await callApi('/design/search', { method: 'POST', body }, key));
+  }
+  return fail(`unknown tool: ${name}`);
+}
+
+export function createServer() {
+  const server = new Server(
+    { name: 'atris', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const key = resolveDesignKey();
+    if (!key) {
+      return fail('no api key found. set ATRIS_API_KEY or run: atris login (or save a key in ~/.atris/design-api-key)');
+    }
+    try {
+      return await handleTool(request.params.name, request.params.arguments || {}, key);
+    } catch (error) {
+      return fail(`design call failed: ${(error && error.message) || error}`);
+    }
+  });
+
+  return server;
+}
+
+// Auto-start only when run directly (`atris mcp`, `npx atris-mcp`,
+// node index.mjs); realpathSync resolves the npm bin symlink.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+if (invokedPath && invokedPath === fileURLToPath(import.meta.url)) {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "atris",
-  "version": "3.58.5",
+  "version": "3.58.7",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {
     "atris": "bin/atris",
-    "ax": "ax"
+    "ax": "ax",
+    "atris-mcp": "mcp/atris-mcp/index.mjs"
   },
   "files": [
     "ax",
@@ -19,6 +20,7 @@
     "scripts/det/",
     "utils/",
     "lib/",
+    "mcp/",
     "templates/",
     "README.md",
     "AGENTS.md",
@@ -99,5 +101,8 @@
   "bugs": {
     "url": "https://github.com/atrislabs/atris/issues"
   },
-  "homepage": "https://github.com/atrislabs/atris#readme"
+  "homepage": "https://github.com/atrislabs/atris#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  }
 }

package/scripts/det/ytnotes

@@ -8,7 +8,7 @@ set -euo pipefail
 USAGE="usage: ytnotes <youtube-url> [haiku|atris-fast|gemini|grok|codex|cursor]"
 
 case "${1:-}" in
-  *youtube.com*|*youtu.be*) ;;
+  *youtube.com*|*youtu.be*|*youtube-nocookie.com*) ;;
   *) echo "$USAGE" >&2; exit 2 ;;
 esac
 
@@ -20,24 +20,135 @@ WORK="${TMPDIR:-/tmp}/ytnotes"
 mkdir -p "$WORK"
 cd "$WORK"
 
+# Printed metadata and a written English VTT are a hit even when yt-dlp exits 429.
+# A leaked WARNING|ERROR print line is not the video id.
+# Manual English is --write-subs. Auto English is often en-orig / en-US / en-GB.
+# Teach parses leftover yt_<id>.clean.txt stamps as cues.
+# Empty --print still keeps a VTT written in this run (id from the watch /
+# shorts / embed / live / e / nocookie embed URL or the new filename). A copied
+# #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.
+existing=""
+for name in yt_*.en.vtt yt_*.en-orig.vtt yt_*.en-US.vtt yt_*.en-GB.vtt; do
+  [ -e "$name" ] || continue
+  existing="$existing $name"
+done
+
 META=$(yt-dlp --no-update --quiet --no-warnings --skip-download \
-  --write-auto-subs --sub-format vtt --sub-langs en \
+  --write-subs --write-auto-subs --sub-format vtt --sub-langs "en,en-orig,en-US,en-GB" \
   --no-simulate \
   -o "yt_%(id)s" \
   --print "%(id)s|%(title)s|%(channel)s|%(duration_string)s" \
-  "$URL" 2>/dev/null)
-ID="${META%%|*}"
-INFO="${META#*|}"
-
-VTT="yt_${ID}.en.vtt"
-if [ ! -s "$VTT" ]; then
-  echo "No English captions found for $URL. Falling back is manual (atris youtube process, 5 credits)." >&2
-  exit 2
+  "$URL" 2>/dev/null) || true
+# Skip WARNING/ERROR/INFO print leaks and NA/None sentinels. Keep the last
+# id|title line so notes stay on yt_<id>.md and keep can find them after a
+# later error. Same sentinel bar as watch/search looksLikeFlatVideoId.
+ID=""
+INFO=""
+while IFS= read -r line || [ -n "$line" ]; do
+  trimmed="${line#"${line%%[![:space:]]*}"}"
+  case "$trimmed" in
+    WARNING*|ERROR*|INFO*|warning*|error*|info*) continue ;;
+  esac
+  case "$trimmed" in
+    *'|'*)
+      cand="${trimmed%%|*}"
+      folded=$(printf '%s' "$cand" | tr '[:upper:]' '[:lower:]')
+      case "$folded" in
+        ''|na|none) continue ;;
+      esac
+      case "$cand" in
+        *[!A-Za-z0-9_-]*) continue ;;
+      esac
+      ID="$cand"
+      INFO="${trimmed#*|}"
+      ;;
+  esac
+done <<EOF
+$META
+EOF
+if [ -z "$ID" ]; then
+  case "$URL" in
+    *'?v='*|*'&v='*)
+      ID="${URL#*'?v='}"
+      if [ "$ID" = "$URL" ]; then
+        ID="${URL#*'&v='}"
+      fi
+      ID="${ID%%&*}"
+      ID="${ID%%\?*}"
+      ;;
+    *'youtu.be/'*)
+      ID="${URL#*'youtu.be/'}"
+      ID="${ID%%\?*}"
+      ID="${ID%%&*}"
+      ID="${ID%%/*}"
+      ;;
+    *'/shorts/'*)
+      ID="${URL#*'/shorts/'}"
+      ID="${ID%%\?*}"
+      ID="${ID%%&*}"
+      ID="${ID%%/*}"
+      ;;
+    *'/embed/'*)
+      ID="${URL#*'/embed/'}"
+      ID="${ID%%\?*}"
+      ID="${ID%%&*}"
+      ID="${ID%%/*}"
+      ;;
+    *'/e/'*)
+      ID="${URL#*'/e/'}"
+      ID="${ID%%\?*}"
+      ID="${ID%%&*}"
+      ID="${ID%%/*}"
+      ;;
+    *'/live/'*)
+      ID="${URL#*'/live/'}"
+      ID="${ID%%\?*}"
+      ID="${ID%%&*}"
+      ID="${ID%%/*}"
+      ;;
+  esac
+  ID="${ID%%#*}"
+fi
+
+VTT=""
+if [ -n "$ID" ]; then
+  for name in "yt_${ID}.en.vtt" "yt_${ID}.en-orig.vtt" "yt_${ID}.en-US.vtt" "yt_${ID}.en-GB.vtt"; do
+    if [ -s "$name" ]; then
+      VTT="$name"
+      break
+    fi
+  done
+fi
+if [ -z "$VTT" ]; then
+  for name in yt_*.en.vtt yt_*.en-orig.vtt yt_*.en-US.vtt yt_*.en-GB.vtt; do
+    [ -s "$name" ] || continue
+    case " $existing " in
+      *" $name "*) continue ;;
+    esac
+    VTT="$name"
+    if [ -z "$ID" ]; then
+      ID="${name#yt_}"
+      ID="${ID%%.*}"
+    fi
+    break
+  done
+fi
+if [ -z "$VTT" ]; then
+  if [ -n "$ID" ] && [ -s "yt_${ID}.clean.txt" ]; then
+    : # leftover cleaned transcript from a prior notes run
+  else
+    echo "No English captions found for $URL. Falling back is manual (atris youtube process, 5 credits)." >&2
+    exit 2
+  fi
 fi
 
 # Strip VTT cruft, drop only nearby rolling-caption duplicates, and keep one
 # time anchor every 30 seconds. Raw auto-captions are mostly timestamp spam:
 # the 21-minute canary is 210 KB raw, 95 KB with the old cleaner, and 22 KB here.
+# Leftover clean.txt is already cleaned; do not overwrite it with an empty VTT pass.
+if [ -n "$VTT" ]; then
 sed -E 's/<[^>]*>//g; s/&gt;/>/g; s/&amp;/\&/g; s/&quot;/"/g' "$VTT" | awk '
 function seconds(ts, parts) {
   split(ts, parts, ":")
@@ -69,6 +180,7 @@ function seconds(ts, parts) {
   for (i = 5; i > 0; i--) recent[i] = recent[i - 1]
   recent[0] = line
 }' > "yt_${ID}.clean.txt"
+fi
 
 TRANSCRIPT=$(<"yt_${ID}.clean.txt")