atris 3.58.5 → 3.58.7

package/commands/youtube.js

@@ -42,12 +42,12 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`       ${commandName} watch tick`);
   output(`       ${commandName} <youtube-url> [options]`);
   output('');
-  output('search = free local discovery (ytsearch / yt-dlp), returns youtu.be links; rich free search prints one failing check; hands off to teach');
-  output('search --paid = 5 credits, watch permalinks + titles from Atris; rich paid search prints one failing check; hands off to teach');
+  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');
+  output('search --paid = 5 credits, watch permalinks + titles from Atris; rich paid search writes one apply and a failing keep/revert pack; thin hands off to teach');
   output('notes = free local notes to stdout; ephemeral unless --save; hands off to teach');
   output('teach = one chapter from local captions; bare teach resumes unpaid checks, then the next chapter after recap or skip');
   output('rich ephemeral notes/teach print one apply next-step and one failing check (no files)');
-  output('process = 5 credits cloud knowledge (needs a filled Apply); rich process prints one failing check');
+  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('Process a YouTube video through Atris using timestamped transcript-first analysis.');
@@ -211,8 +211,16 @@ function youtubeFailureError(result) {
     ? ' Run "atris login --force".'
     : result.status === 402
       ? ' Check Atris credits.'
-      : '';
-  return new Error(`YouTube processing failed (${result.status}): ${resultErrorText(result)}.${hint}`);
+      : result.status === 502
+        ? ' YouTube processing is unavailable; retry in a few seconds.'
+        : '';
+  const credits = paidSearchCredits(result.data);
+  const refundHint = result.status === 502 && creditsRefundedExplicitly(credits)
+    ? ' credits refunded.'
+    : '';
+  const lines = [`YouTube processing failed (${result.status}): ${resultErrorText(result)}.${hint}${refundHint}`];
+  lines.push(...formatCreditsLines(credits));
+  return new Error(lines.join('\n'));
 }
 
 function captionHostAllowed(urlString) {
@@ -275,6 +283,51 @@ function parseVttTimestampMs(value) {
   return ((hours * 3600) + (minutes * 60) + seconds) * 1000 + millis;
 }
 
+function parseCleanTimestampMs(value) {
+  const match = String(value || '').trim().match(/^(?:(\d{1,2}):)?(\d{1,2}):(\d{2})$/);
+  if (!match) return null;
+  const hours = Number(match[1] || 0);
+  const minutes = Number(match[2] || 0);
+  const seconds = Number(match[3] || 0);
+  if (![hours, minutes, seconds].every(Number.isFinite)) return null;
+  if (minutes > 59 || seconds > 59) return null;
+  return ((hours * 3600) + (minutes * 60) + seconds) * 1000;
+}
+
+function parseCleanTranscriptCues(raw) {
+  const cues = [];
+  let startMs = 0;
+  let sawStamp = false;
+  const pending = [];
+  const flush = () => {
+    const text = pending.join(' ').replace(/\s+/g, ' ').trim();
+    pending.length = 0;
+    if (!text) return;
+    const cue = { startMs, text };
+    if (cues.length && cues[cues.length - 1].text === cue.text && cues[cues.length - 1].startMs === cue.startMs) {
+      return;
+    }
+    cues.push(cue);
+  };
+  for (const line of String(raw).split(/\r?\n/)) {
+    const stripped = line.trim();
+    if (!stripped) continue;
+    const stamp = stripped.match(/^\[(\d{1,2}:\d{2}(?::\d{2})?)\]$/);
+    if (stamp) {
+      flush();
+      const parsed = parseCleanTimestampMs(stamp[1]);
+      if (parsed != null) {
+        startMs = parsed;
+        sawStamp = true;
+      }
+      continue;
+    }
+    pending.push(stripped.replace(/<[^>]+>/g, ''));
+  }
+  flush();
+  return sawStamp && cues.length ? cues : [];
+}
+
 function fetchCaptionText(urlString, redirects = 0) {
   if (!captionHostAllowed(urlString)) {
     return Promise.resolve(null);
@@ -372,7 +425,7 @@ function parseCaptionCues(raw) {
     return cues;
   }
 
-  return [];
+  return parseCleanTranscriptCues(raw);
 }
 
 function parseCaptionText(raw) {
@@ -406,33 +459,117 @@ function parseCaptionText(raw) {
   return segments.join(' ');
 }
 
+function parseYtDlpInfoJson(result) {
+  const kept = [];
+  for (const line of String((result && result.stdout) || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^(WARNING|ERROR|INFO)\b/i.test(trimmed)) continue;
+    kept.push(trimmed);
+  }
+  const raw = kept.join('\n').trim();
+  if (!raw) return null;
+  try {
+    const info = JSON.parse(raw);
+    return info && typeof info === 'object' && !Array.isArray(info) ? info : null;
+  } catch {
+    return null;
+  }
+}
+
+function localCaptionNames(id) {
+  // scripts/det/ytnotes keeps these VTT names 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}.clean.txt`,
+  ];
+}
+
+function captionLookupIds({ url, id } = {}) {
+  const ids = [];
+  const seen = new Set();
+  const add = (value) => {
+    const text = String(value || '').trim();
+    if (!text || seen.has(text)) return;
+    seen.add(text);
+    ids.push(text);
+  };
+  add(id);
+  add(videoIdFromUrl(url));
+  return ids;
+}
+
+function readLocalCaptionText({ url, id, workDir } = {}) {
+  if (!workDir) return '';
+  for (const videoId of captionLookupIds({ url, id })) {
+    for (const name of localCaptionNames(videoId)) {
+      const abs = path.join(workDir, name);
+      try {
+        if (!fs.existsSync(abs)) continue;
+        const text = fs.readFileSync(abs, 'utf8');
+        if (String(text).trim()) return text;
+      } catch {
+        // try the next written caption file
+      }
+    }
+  }
+  return '';
+}
+
+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 local = readLocalCaptionText({
+    url: youtubeUrl,
+    id: payload.id,
+    workDir: deps.workDir,
+  });
+  if (!String(local || '').trim()) return null;
+  return { raw: local, language: selected?.language || 'en' };
+}
+
+function ytDlpInfoArgs(youtubeUrl) {
+  return ['-J', '--skip-download', '--no-warnings', '--no-playlist', youtubeUrl];
+}
+
+function teachSourceVideoId(info, youtubeUrl) {
+  const fromUrl = videoIdFromUrl(youtubeUrl);
+  const fromInfo = info && info.id;
+  const entries = info && Array.isArray(info.entries) ? info.entries : [];
+  const fromEntry = entries[0] && entries[0].id;
+  if (info && (info._type === 'playlist' || entries.length)) {
+    return fromUrl || fromEntry || fromInfo;
+  }
+  return fromInfo || fromUrl;
+}
+
 async function extractLocalTranscript(youtubeUrl, deps = {}) {
   if (process.env.ATRIS_YOUTUBE_LOCAL_TRANSCRIPT === '0') return null;
   const runner = deps.spawnSync || spawnSync;
-  const result = runner('yt-dlp', ['-J', '--skip-download', '--no-warnings', youtubeUrl], {
+  const result = runner('yt-dlp', ytDlpInfoArgs(youtubeUrl), {
     encoding: 'utf8',
     timeout: 20000,
     maxBuffer: 10 * 1024 * 1024,
   });
-  if (result.error || result.status !== 0 || !result.stdout) return null;
-
-  let info;
-  try {
-    info = JSON.parse(result.stdout);
-  } catch {
-    return null;
-  }
-
-  const selected = chooseCaptionTrack(info);
-  if (!selected?.track?.url) return null;
-  const rawCaption = await (deps.fetchCaptionText || fetchCaptionText)(selected.track.url);
-  const transcript = parseCaptionText(rawCaption);
+  const info = parseYtDlpInfoJson(result);
+  const loaded = await loadCaptionRaw(info, youtubeUrl, deps);
+  const transcript = parseCaptionText(loaded && loaded.raw);
   if (!transcript) return null;
 
   return {
     transcriptText: transcript.slice(0, LOCAL_TRANSCRIPT_MAX_CHARS),
-    language: selected.language || 'unknown',
-    durationSeconds: Number(info.duration || 0) || undefined,
+    language: loaded.language || 'unknown',
+    durationSeconds: Number((info && info.duration) || 0) || undefined,
   };
 }
 
@@ -468,6 +605,12 @@ async function processYoutube(options, deps = {}) {
     if (!result.ok && result.status === 401 && !auth.minted) {
       const remint = await ensureBilled('youtube', { ...deps, forceMint: true });
       if (remint?.ok && remint.token) {
+        if (!options.json) {
+          const print = typeof deps.output === 'function' ? deps.output : () => {};
+          for (const line of formatCreditsLines(paidSearchCredits(result.data))) {
+            print(line);
+          }
+        }
         auth = remint;
         result = await apiFn('/agent/process_youtube', {
           method: 'POST',
@@ -484,7 +627,10 @@ async function processYoutube(options, deps = {}) {
   const localExtractor = deps.extractLocalTranscript || extractLocalTranscript;
   let localTranscript = null;
   try {
-    localTranscript = await localExtractor(options.youtubeUrl, deps);
+    localTranscript = await localExtractor(options.youtubeUrl, {
+      ...deps,
+      workDir: deps.workDir || notesWorkDir(deps),
+    });
   } catch {
     localTranscript = null;
   }
@@ -501,6 +647,12 @@ async function processYoutube(options, deps = {}) {
     if (transcriptResult.status === 401 || transcriptResult.status === 402 || transcriptResult.status === 400) {
       throw youtubeFailureError(transcriptResult);
     }
+    if (!options.json) {
+      const print = typeof deps.output === 'function' ? deps.output : () => {};
+      for (const line of formatCreditsLines(paidSearchCredits(transcriptResult.data))) {
+        print(line);
+      }
+    }
   }
 
   const result = await requestYoutube(buildYoutubePayload(options));
@@ -537,11 +689,8 @@ function formatYoutubeResult(data) {
       : '';
     lines.push(`Processing: ${method}${source}`);
   }
-  if (data?.credits_used !== undefined || data?.credits_remaining !== undefined) {
-    const used = data.credits_used !== undefined ? data.credits_used : '?';
-    const remaining = data.credits_remaining !== undefined ? data.credits_remaining : '?';
-    lines.push(`Credits: ${used} used, ${remaining} remaining`);
-  }
+  const creditLines = formatCreditsLines(paidSearchCredits(data));
+  if (creditLines.length) lines.push(...creditLines);
   const analysis = processAnalysisText(data);
   if (analysis) {
     lines.push('');
@@ -551,11 +700,13 @@ function formatYoutubeResult(data) {
 }
 
 function videoIdFromUrl(url) {
-  const text = String(url || '');
+  const text = String(url || '').split('#')[0];
   const watch = text.match(/[?&]v=([^&]+)/);
   if (watch) return watch[1];
   const short = text.match(/youtu\.be\/([^?&/]+)/);
-  return short ? short[1] : null;
+  if (short) return short[1];
+  const pathId = text.match(/\/(?:shorts|embed|live|v|e)\/([^?&/]+)/i);
+  return pathId ? pathId[1] : null;
 }
 
 function videoIdFromArg(arg) {
@@ -569,7 +720,7 @@ function videoIdFromArg(arg) {
 function looksLikeYoutubeUrl(arg) {
   const text = String(arg || '').trim();
   if (!text || text.startsWith('-')) return false;
-  return /youtube\.com|youtu\.be/i.test(text);
+  return /youtube\.com|youtu\.be|youtube-nocookie\.com/i.test(text);
 }
 
 function isPlaylistUrl(url) {
@@ -666,6 +817,10 @@ function applySidecarRel(id) {
   return applyGate.applySidecarRel('youtube', id);
 }
 
+function notesApplyRel(id) {
+  return applyGate.applySidecarRel('notes', experimentIdToken(id));
+}
+
 function notesExperimentSlug(id) {
   return `notes-${experimentIdToken(id)}`;
 }
@@ -694,6 +849,14 @@ function readNotesText({ url, workDir } = {}) {
   }
 }
 
+function notesWorkDir(deps = {}) {
+  return deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
+}
+
+function keptPrintedNotes({ url, workDir } = {}) {
+  return Boolean(String(readNotesText({ url, workDir }) || '').trim());
+}
+
 function saveRichNotes(url, deps = {}) {
   const workDir = deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
   const lesson = notesLessonFromText(readNotesText({ url, workDir }));
@@ -707,7 +870,7 @@ function saveRichNotes(url, deps = {}) {
     url,
     lesson,
     slug: id ? notesExperimentSlug(id) : null,
-    applyRel: id ? applySidecarRel(id) : null,
+    applyRel: id ? notesApplyRel(id) : null,
   });
   return { thin: false, brief, packRel, lesson };
 }
@@ -719,7 +882,7 @@ function ensureNotesApply({ cwd, url, packRel, now, output } = {}) {
   return applyGate.ensureApply({
     cwd,
     source: url,
-    rel: id ? applySidecarRel(id) : null,
+    rel: id ? notesApplyRel(id) : null,
     now,
     output,
     incompleteMessage: slug
@@ -800,12 +963,15 @@ function unsaveYoutubeNotes(target, deps = {}) {
   };
   add(briefRel);
   add(applyRel);
+  add(notesApplyRel(id));
   for (const section of sections) {
     add(teachBriefRel(id, section));
     add(applySidecarRel(`${id}-s${section}`));
   }
   for (const rel of listTeachSidecarRels(cwd, id)) add(rel);
   add(notesExperimentRel(id));
+  add(processApplyRel(id));
+  add(processExperimentRel(id));
   for (const section of sections) add(teachExperimentRel(id, section));
 
   const removed = [];
@@ -850,9 +1016,89 @@ function ensureProcessApply({ cwd, url, now, output } = {}) {
     output,
     incompleteMessage: PROCESS_APPLY_MESSAGE,
     required: true,
+    human: true,
+  });
+}
+
+function processExperimentSlug(id) {
+  return `process-${experimentIdToken(id)}`;
+}
+
+function processExperimentRel(id) {
+  return `atris/experiments/${processExperimentSlug(id)}`;
+}
+
+function processApplyRel(id) {
+  return applyGate.applySidecarRel('process', experimentIdToken(id));
+}
+
+function saveRichProcess({ cwd, url, lesson } = {}) {
+  if (isThinTeachLesson(lesson)) {
+    return { thin: true, packRel: null, lesson };
+  }
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  const id = videoIdFromUrl(url);
+  const packRel = fileTeachExperiment({
+    cwd,
+    url,
+    lesson,
+    slug: id ? processExperimentSlug(id) : null,
+    applyRel: id ? processApplyRel(id) : null,
+  });
+  return { thin: false, packRel, lesson, source: url };
+}
+
+function ensureProcessLearnerApply({ cwd, url, packRel, now, output, source } = {}) {
+  const id = videoIdFromUrl(url);
+  const pack = packRel || (id ? processExperimentRel(id) : null);
+  const slug = pack ? path.basename(pack) : null;
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  return applyGate.ensureApply({
+    cwd,
+    source: source || url || (id ? `process:${id}` : 'process'),
+    rel: id ? processApplyRel(id) : null,
+    now,
+    output,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : applyGate.ephemeralApplyMessage('process'),
+    required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
   });
 }
 
+function mintRichProcess({ cwd, url, data, now, output, ensureApply, json } = {}) {
+  const print = typeof output === 'function' ? output : (line = '') => console.log(line);
+  const lesson = notesLessonFromText(processAnalysisText(data));
+  if (isThinTeachLesson(lesson)) {
+    printProcessLearnerGate(data, { json }, print);
+    return 0;
+  }
+  const saved = saveRichProcess({ cwd, url, lesson });
+  const applyFn = ensureApply || ensureProcessLearnerApply;
+  const applyCode = applyFn({
+    cwd,
+    url,
+    packRel: saved.packRel,
+    now,
+    output: print,
+    source: url,
+  });
+  if (ensureApply) return applyCode;
+  const id = videoIdFromUrl(url);
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: id ? processApplyRel(id) : null,
+    lesson: saved.lesson,
+    output: print,
+    json,
+  });
+  if (baseline !== 0) return baseline;
+  return applyCode;
+}
+
 const DIGEST_ENGINE_TIMEOUT_MS = 240000;
 const DEFAULT_DIGEST_DAYS = 7;
 
@@ -1082,6 +1328,15 @@ function ensureWatchApply({ cwd, url, packRel, now, output, source } = {}) {
   });
 }
 
+function firstRichWatchLesson(urls, workDir) {
+  for (const url of Array.isArray(urls) ? urls : []) {
+    if (!url) continue;
+    const lesson = notesLessonFromText(readNotesText({ url, workDir }));
+    if (!isThinTeachLesson(lesson)) return { url, lesson };
+  }
+  return null;
+}
+
 function saveRichWatch({ cwd, url, lesson } = {}) {
   if (isThinTeachLesson(lesson)) {
     return { thin: true, packRel: null, lesson };
@@ -1258,15 +1513,22 @@ function channelVideosUrl(channel) {
   return `${base}/videos`;
 }
 
+function looksLikeFlatVideoId(id) {
+  const text = String(id || '');
+  if (/^(NA|None)$/i.test(text)) return false;
+  return /^[A-Za-z0-9_-]+$/.test(text);
+}
+
 function parseFlatPlaylist(stdout) {
   const videos = [];
   for (const line of String(stdout || '').split(/\r?\n/)) {
     const trimmed = line.trim();
     if (!trimmed || !trimmed.includes('|')) continue;
+    if (/^(WARNING|ERROR|INFO)\b/i.test(trimmed)) 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 });
+    if (looksLikeFlatVideoId(id)) videos.push({ id, title });
   }
   return videos;
 }
@@ -1276,6 +1538,7 @@ function defaultChannelFetcher(videosUrl, deps = {}) {
   const result = spawn('yt-dlp', [
     '--no-update',
     '--flat-playlist',
+    '--no-warnings',
     '--playlist-end',
     '3',
     '--print',
@@ -1286,11 +1549,13 @@ function defaultChannelFetcher(videosUrl, deps = {}) {
     timeout: 60000,
     maxBuffer: 2 * 1024 * 1024,
   });
+  const videos = parseFlatPlaylist(result && result.stdout);
+  if (videos.length) return videos;
   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);
+  return videos;
 }
 
 function defaultNotesRunner(url, deps = {}) {
@@ -1420,6 +1685,7 @@ async function tickWatch(deps = {}) {
   let totalNew = 0;
   let totalBriefed = 0;
   let firstBriefedUrl = null;
+  const briefedUrls = [];
 
   for (const row of state.channels) {
     const videosUrl = channelVideosUrl(row.channel);
@@ -1466,6 +1732,7 @@ async function tickWatch(deps = {}) {
       }
       markSeen(state, row.channel, video.id, timestamp);
       briefed += 1;
+      briefedUrls.push(url);
       if (!firstBriefedUrl) firstBriefedUrl = url;
     }
 
@@ -1485,34 +1752,35 @@ async function tickWatch(deps = {}) {
   output(`total: ${totalNew} new, ${totalBriefed} briefed`);
   saveWatchState(statePath, state);
   if (totalBriefed > 0) {
-    if (firstBriefedUrl) {
-      const lesson = notesLessonFromText(readNotesText({ url: firstBriefedUrl, workDir }));
-      if (isThinTeachLesson(lesson)) {
-        printLearnerCheckGate(output, lesson, { includeCheck: true });
-        printYoutubeTeachNext(firstBriefedUrl, {}, output);
-        return 0;
-      }
-      const saved = saveRichWatch({ cwd, url: firstBriefedUrl, lesson });
+    const rich = firstRichWatchLesson(briefedUrls, workDir);
+    if (rich) {
+      const saved = saveRichWatch({ cwd, url: rich.url, lesson: rich.lesson });
       const ensureApply = deps.ensureApply || ensureWatchApply;
       const applyCode = ensureApply({
         cwd,
-        url: firstBriefedUrl,
+        url: rich.url,
         packRel: saved.packRel,
         now,
         output,
-        source: firstBriefedUrl,
+        source: rich.url,
       });
       if (deps.ensureApply) return applyCode;
-      const id = videoIdFromUrl(firstBriefedUrl);
+      const id = videoIdFromUrl(rich.url);
       const baseline = proveSavedLearnerBaseline({
         cwd,
         applyRel: id ? watchApplyRel(id) : null,
-        lesson,
+        lesson: rich.lesson,
         output,
       });
       if (baseline !== 0) return baseline;
       return applyCode;
     }
+    if (firstBriefedUrl) {
+      const lesson = notesLessonFromText(readNotesText({ url: firstBriefedUrl, workDir }));
+      printLearnerCheckGate(output, lesson, { includeCheck: true });
+      printYoutubeTeachNext(firstBriefedUrl, {}, output);
+      return 0;
+    }
     printYoutubeTeachNext(firstBriefedUrl, {}, output);
     return 0;
   }
@@ -1541,6 +1809,7 @@ function defaultPlaylistExpander(playlistUrl, deps = {}) {
   const result = spawn('yt-dlp', [
     '--no-update',
     '--flat-playlist',
+    '--no-warnings',
     '--print',
     '%(id)s|%(title)s',
     playlistUrl,
@@ -1549,11 +1818,13 @@ function defaultPlaylistExpander(playlistUrl, deps = {}) {
     timeout: 60000,
     maxBuffer: 2 * 1024 * 1024,
   });
+  const videos = parseFlatPlaylist(result && result.stdout);
+  if (videos.length) return videos;
   if (result.error || (result.status != null && result.status !== 0)) {
     const detail = String(result.stderr || result.error?.message || 'playlist expand failed').trim();
     throw new Error(detail || 'playlist expand failed');
   }
-  return parseFlatPlaylist(result.stdout);
+  return videos;
 }
 
 function defaultNotesItemRunner(url, engine, deps = {}) {
@@ -1647,15 +1918,20 @@ function runOneNotesItem(item, engine, deps = {}) {
   }
 
   const started = readNowMs(deps);
-  let status = 1;
+  let result = { status: 1 };
   try {
-    status = readRunnerStatus(invokeNotesRunner(item.url, engine, deps));
-  } catch {
-    status = 1;
+    result = invokeNotesRunner(item.url, engine, deps);
+  } catch (err) {
+    result = { status: 1, stderr: String((err && err.message) || err || '') };
   }
+  const status = readRunnerStatus(result);
   let brief = null;
   let lesson = null;
-  let ok = status === 0;
+  let ok = status === 0 || keptPrintedNotes({
+    url: item.url,
+    workDir: notesWorkDir(deps),
+    result,
+  });
   if (ok && deps.save) {
     const saved = saveRichNotes(item.url, deps);
     if (saved.thin) {
@@ -1728,7 +2004,7 @@ function runYoutubeNotesBatch({ urls, engine, save, json } = {}, deps = {}) {
     }));
     const baseline = proveSavedLearnerBaseline({
       cwd: deps.cwd || process.cwd(),
-      applyRel: id ? applySidecarRel(id) : null,
+      applyRel: id ? notesApplyRel(id) : null,
       lesson,
       output,
       json: asJson,
@@ -1743,10 +2019,16 @@ function runSingleYoutubeNotes(url, engine, deps = {}) {
   try {
     result = invokeNotesRunner(url, engine, deps);
   } catch {
-    return 1;
+    result = { status: 1 };
   }
   const status = readRunnerStatus(result);
-  if (status !== 0) return status;
+  if (status !== 0 && !keptPrintedNotes({
+    url,
+    workDir: notesWorkDir(deps),
+    result,
+  })) {
+    return status == null ? 1 : status;
+  }
   const output = deps.output || ((line = '') => console.error(line));
   if (!deps.save) {
     const json = deps.json === true;
@@ -1773,7 +2055,7 @@ function runSingleYoutubeNotes(url, engine, deps = {}) {
   const id = videoIdFromUrl(url);
   const baseline = proveSavedLearnerBaseline({
     cwd,
-    applyRel: id ? applySidecarRel(id) : null,
+    applyRel: id ? notesApplyRel(id) : null,
     lesson: saved.lesson,
     output,
     json: deps.json === true,
@@ -1827,14 +2109,14 @@ function showYoutubeSearchHelp(output = console.log, commandName = 'atris youtub
   output('');
   output('Free local discovery. Uses ytsearch on PATH when present, else the');
   output('bundled scripts/det/ytsearch, else yt-dlp ytsearchN with the same print contract.');
-  output('Does not bill credits. A hit prints one next: atris youtube teach <first-url>.');
-  output('A rich hit prints one failing check (score 0). A thin hit prints check: fill this.');
+  output('Does not bill credits. A thin hit prints check: fill this and one next: atris youtube teach <first-url>.');
+  output('A rich hit writes one apply and a failing keep/revert pack (score 0).');
   output('');
   output(`--paid buys watch permalinks from Atris (${PAID_SEARCH_COST_HINT}).`);
   output('Requires login. Same auth path as atris youtube process.');
-  output('A hit also prints one next: atris youtube teach <first-url>.');
-  output('A rich hit prints one failing check (score 0). A thin hit prints check: fill this.');
-  output('Empty or failed paid search refunds the credits.');
+  output('A rich hit writes one apply and a failing keep/revert pack (score 0).');
+  output('A thin hit prints check: fill this and one next: atris youtube teach <first-url>.');
+  output('Empty or failed paid search prints credits refunded only when the server marks a refund.');
   output('');
   output('Options:');
   output(`  --limit <n>         Max results (default: ${DEFAULT_SEARCH_LIMIT})`);
@@ -1913,10 +2195,12 @@ function parseSearchStdout(stdout = '') {
   for (const line of String(stdout || '').split(/\r?\n/)) {
     const trimmed = line.trim();
     if (!trimmed || !trimmed.includes('|')) continue;
+    if (/^(WARNING|ERROR|INFO)\b/i.test(trimmed)) continue;
     const parts = trimmed.split(/\s*\|\s*/).map((part) => part.trim());
     if (parts.length < 5) continue;
     const url = parts[parts.length - 1];
     if (!/^https?:\/\/(?:www\.)?(?:youtube\.com\/|youtu\.be\/)/i.test(url)) continue;
+    if (!looksLikeFlatVideoId(videoIdFromUrl(url))) continue;
     const row = {
       title: parts[0] || '',
       channel: parts[1] || '',
@@ -2079,9 +2363,8 @@ function paidSearchCredits(data) {
   return { used, remaining, refunded };
 }
 
-function creditsWereRefunded(credits) {
+function creditsRefundedExplicitly(credits) {
   if (!credits) return false;
-  if (credits.used === 0) return true;
   if (credits.refunded === true) return true;
   return typeof credits.refunded === 'number' && credits.refunded > 0;
 }
@@ -2091,7 +2374,7 @@ function formatCreditsLines(credits) {
   if (credits.used !== undefined || credits.remaining !== undefined) {
     lines.push(`Credits: ${credits.used !== undefined ? credits.used : '?'} used, ${credits.remaining !== undefined ? credits.remaining : '?'} remaining`);
   }
-  if (creditsWereRefunded(credits)) {
+  if (creditsRefundedExplicitly(credits)) {
     lines.push('credits refunded');
   }
   return lines;
@@ -2118,7 +2401,7 @@ function youtubeSearchFailureError(result) {
         ? ' YouTube search is unavailable; retry in a few seconds.'
         : '';
   const credits = paidSearchCredits(result.data);
-  const refundHint = result.status === 502 && creditsWereRefunded(credits)
+  const refundHint = result.status === 502 && creditsRefundedExplicitly(credits)
     ? ' credits refunded.'
     : '';
   const lines = [`YouTube search failed (${result.status}): ${resultErrorText(result)}.${hint}${refundHint}`];
@@ -2147,6 +2430,12 @@ async function requestPaidYoutubeSearch(options, deps = {}) {
   if (!result.ok && result.status === 401 && !auth.minted) {
     const remint = await ensureBilled('youtube', { ...deps, forceMint: true });
     if (remint?.ok && remint.token) {
+      if (!options.json) {
+        const print = typeof deps.output === 'function' ? deps.output : () => {};
+        for (const line of formatCreditsLines(paidSearchCredits(result.data))) {
+          print(line);
+        }
+      }
       auth = remint;
       result = await call(auth.token);
     }
@@ -2178,9 +2467,7 @@ async function runPaidYoutubeSearch(options, deps = {}) {
     return 2;
   }
   output(rendered);
-  printSearchLearnerGate(videos, options, output);
-  printSearchTeachNext(videos, options, output);
-  return 0;
+  return gateSearchLearner(videos, options, output, deps);
 }
 
 function searchLessonText(rows) {
@@ -2190,6 +2477,93 @@ function searchLessonText(rows) {
     .join('\n');
 }
 
+function searchExperimentSlug(query) {
+  return `search-${applyGate.applySlug(query)}`;
+}
+
+function searchExperimentRel(query) {
+  return `atris/experiments/${searchExperimentSlug(query)}`;
+}
+
+function searchApplyRel(query) {
+  return applyGate.applySidecarRel('search', applyGate.applySlug(query));
+}
+
+function searchApplyNow(now) {
+  if (typeof now === 'function') {
+    const value = now();
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) return value;
+    const ms = Number(value);
+    if (Number.isFinite(ms) && ms > 0) return new Date(ms).toISOString().slice(0, 10);
+    return undefined;
+  }
+  return now;
+}
+
+function saveRichSearch({ cwd, query, lesson } = {}) {
+  if (isThinTeachLesson(lesson)) {
+    return { thin: true, packRel: null, lesson };
+  }
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  const packRel = fileTeachExperiment({
+    cwd,
+    lesson,
+    slug: query ? searchExperimentSlug(query) : null,
+    applyRel: query ? searchApplyRel(query) : null,
+  });
+  return { thin: false, packRel, lesson, source: query };
+}
+
+function ensureSearchApply({ cwd, query, packRel, now, output, source } = {}) {
+  const pack = packRel || (query ? searchExperimentRel(query) : null);
+  const slug = pack ? path.basename(pack) : null;
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  return applyGate.ensureApply({
+    cwd,
+    source: source || query || 'search',
+    rel: query ? searchApplyRel(query) : null,
+    now,
+    output,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : applyGate.ephemeralApplyMessage('search'),
+    required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
+  });
+}
+
+function mintRichSearch({ cwd, query, rows, now, output, ensureApply, json } = {}) {
+  const print = typeof output === 'function' ? output : (line = '') => console.log(line);
+  const lesson = notesLessonFromText(searchLessonText(rows));
+  if (json) return { thin: false, code: 0, lesson };
+  if (isThinTeachLesson(lesson)) {
+    printSearchLearnerGate(rows, { json: false }, print);
+    return { thin: true, code: 0, lesson };
+  }
+  const saved = saveRichSearch({ cwd, query, lesson });
+  const applyFn = ensureApply || ensureSearchApply;
+  const applyCode = applyFn({
+    cwd,
+    query,
+    packRel: saved.packRel,
+    now: searchApplyNow(now),
+    output: print,
+    source: query,
+  });
+  if (ensureApply) return { thin: false, code: applyCode, lesson: saved.lesson };
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: query ? searchApplyRel(query) : null,
+    lesson: saved.lesson,
+    output: print,
+    json,
+  });
+  if (baseline !== 0) return { thin: false, code: baseline, lesson: saved.lesson };
+  return { thin: false, code: applyCode, lesson: saved.lesson };
+}
+
 function printSearchLearnerGate(rows, options, output) {
   printLearnerCheckGate(output, notesLessonFromText(searchLessonText(rows)), {
     includeCheck: true,
@@ -2197,6 +2571,40 @@ function printSearchLearnerGate(rows, options, output) {
   });
 }
 
+function gateSearchLearner(rows, options, output, deps = {}) {
+  if (options && options.json) return 0;
+  const minted = mintRichSearch({
+    cwd: deps.cwd || process.cwd(),
+    query: options && options.query,
+    rows,
+    now: deps.now,
+    output,
+    ensureApply: deps.ensureApply,
+    json: false,
+  });
+  if (minted.thin) printSearchTeachNext(rows, options, output);
+  return minted.code;
+}
+
+function printSearchOutcome(rows, options, output, deps = {}) {
+  printSearchRows(rows, options, output);
+  return gateSearchLearner(rows, options, output, deps);
+}
+
+function resultStdout(result) {
+  if (typeof result === 'string') return result;
+  return String((result && result.stdout) || '');
+}
+
+function searchRowsFromResult(result) {
+  return parseSearchStdout(resultStdout(result));
+}
+
+function finishSuccessfulSearch(rows, options, output, deps) {
+  writeLocalSearchCache(options.query, rows, deps);
+  return printSearchOutcome(rows, options, output, deps);
+}
+
 function commandOnPath(name, deps = {}) {
   const spawn = deps.spawnSync || spawnSync;
   const result = spawn('sh', ['-c', `command -v ${shellSingleQuote(name)}`], {
@@ -2313,6 +2721,9 @@ async function runYoutubeSearch(args = [], deps = {}) {
     return 2;
   }
 
+  let rows = searchRowsFromResult(result);
+  if (rows.length) return finishSuccessfulSearch(rows, options, output, deps);
+
   let status = searchRunnerStatus(result);
   if (status != null && status !== 0 && isLocalSearchRateLimited(result)) {
     await waitLocalSearchBackoff(deps);
@@ -2326,15 +2737,16 @@ async function runYoutubeSearch(args = [], deps = {}) {
       output('ytsearch and yt-dlp not found. Install yt-dlp or put ytsearch on PATH.');
       return 2;
     }
+    rows = searchRowsFromResult(result);
+    if (rows.length) return finishSuccessfulSearch(rows, options, output, deps);
     status = searchRunnerStatus(result);
     if (status != null && status !== 0 && isLocalSearchRateLimited(result)) {
       const cached = readFreshLocalSearchCache(options.query, deps);
       if (cached) {
-        const rows = cached.rows.slice(0, options.limit);
-        printSearchRows(rows, options, output);
-        printSearchTeachNext(rows, options, output);
+        const cachedRows = cached.rows.slice(0, options.limit);
+        const code = printSearchOutcome(cachedRows, options, output, deps);
         output(LOCAL_SEARCH_CACHE_NOTE);
-        return 0;
+        return code;
       }
       output(LOCAL_SEARCH_RATE_LIMIT_MESSAGE);
       return status == null ? 1 : status;
@@ -2347,19 +2759,9 @@ async function runYoutubeSearch(args = [], deps = {}) {
     return status == null ? 1 : status;
   }
 
-  const stdout = typeof result === 'string' ? result : String((result && result.stdout) || '');
-  const rows = parseSearchStdout(stdout);
-  if (!rows.length) {
-    output('no videos found');
-    if (!options.json) printWatchTickNext(output);
-    return 2;
-  }
-
-  writeLocalSearchCache(options.query, rows, deps);
-  printSearchRows(rows, options, output);
-  printSearchLearnerGate(rows, options, output);
-  printSearchTeachNext(rows, options, output);
-  return 0;
+  output('no videos found');
+  if (!options.json) printWatchTickNext(output);
+  return 2;
 }
 
 const YTTEACH_USAGE = 'usage: atris youtube teach <youtube-url> [--section N] [--save] [--recap TEXT] [--skip] | owed | next';
@@ -3292,33 +3694,23 @@ async function extractTeachSource(youtubeUrl, deps = {}) {
     return deps.extractTeachSource(youtubeUrl, deps);
   }
   const runner = deps.spawnSync || spawnSync;
-  const result = runner('yt-dlp', ['-J', '--skip-download', '--no-warnings', youtubeUrl], {
+  const result = runner('yt-dlp', ytDlpInfoArgs(youtubeUrl), {
     encoding: 'utf8',
     timeout: 20000,
     maxBuffer: 10 * 1024 * 1024,
   });
-  if (result.error || result.status !== 0 || !result.stdout) return null;
-
-  let info;
-  try {
-    info = JSON.parse(result.stdout);
-  } catch {
-    return null;
-  }
-
-  const selected = chooseCaptionTrack(info);
-  if (!selected?.track?.url) return null;
-  const rawCaption = await (deps.fetchCaptionText || fetchCaptionText)(selected.track.url);
-  const cues = parseCaptionCues(rawCaption);
+  const info = parseYtDlpInfoJson(result);
+  const loaded = await loadCaptionRaw(info, youtubeUrl, deps);
+  const cues = parseCaptionCues(loaded && loaded.raw);
   if (!cues.length) return null;
 
   return {
-    id: info.id || videoIdFromUrl(youtubeUrl),
-    title: info.title || '',
+    id: teachSourceVideoId(info, youtubeUrl),
+    title: (info && info.title) || '',
     url: youtubeUrl,
-    durationSeconds: Number(info.duration || 0) || undefined,
-    language: selected.language || 'unknown',
-    chapters: normalizeChapters(info.chapters, info.duration),
+    durationSeconds: Number((info && info.duration) || 0) || undefined,
+    language: loaded.language || 'unknown',
+    chapters: normalizeChapters(info && info.chapters, info && info.duration),
     cues,
   };
 }
@@ -3368,7 +3760,10 @@ async function runYoutubeTeach(args = [], deps = {}) {
     }
   }
 
-  const source = await (deps.extractTeachSource || extractTeachSource)(parsed.url, deps);
+  const source = await (deps.extractTeachSource || extractTeachSource)(parsed.url, {
+    ...deps,
+    workDir: deps.workDir || notesWorkDir(deps),
+  });
   if (!source || !Array.isArray(source.cues) || !source.cues.length) {
     output('no english captions for this url. teach stays local and will not call process.');
     return 2;
@@ -3492,7 +3887,15 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
       output(JSON.stringify(data, null, 2));
     } else {
       output(formatYoutubeResult(data));
-      printProcessLearnerGate(data, {}, output);
+      const mintCode = mintRichProcess({
+        cwd: deps.cwd || process.cwd(),
+        url: options.youtubeUrl,
+        data,
+        now: deps.now,
+        output,
+        ensureApply: deps.ensureApply,
+      });
+      if (mintCode !== 0) status = mintCode;
     }
   } catch (err) {
     if (!err.applyRequired) output(err.message);
@@ -3510,10 +3913,12 @@ module.exports = {
   parseYoutubeArgs,
   buildYoutubePayload,
   extractLocalTranscript,
+  parseYtDlpInfoJson,
   processYoutube,
   shouldRetryWithLocalTranscript,
   formatYoutubeResult,
   fileBriefFromNotes,
+  keptPrintedNotes,
   ensureNotesApply,
   unsaveYoutubeNotes,
   APPLY_NEXT_MESSAGE,
@@ -3541,6 +3946,7 @@ module.exports = {
   extractTeachNumbers,
   extractTeachMechanisms,
   extractTeachSource,
+  readLocalCaptionText,
   oneTeachCheck,
   learnerCheckFromLesson,
   scoreLearnerNeedles,
@@ -3556,6 +3962,11 @@ module.exports = {
   notesExperimentSlug,
   digestExperimentSlug,
   watchExperimentSlug,
+  processExperimentSlug,
+  processApplyRel,
+  searchExperimentSlug,
+  searchApplyRel,
+  firstRichWatchLesson,
   fileTeachExperiment,
   youtubeCommand,
 };