yt-briefing 1.3.1 → 1.3.3

package/dist/lib/paths.js

@@ -54,6 +54,7 @@ export const REST_FILE = join(CACHE_DIR, 'queue-rest.json');
 export const PENDING_FILE = join(CACHE_DIR, 'pending.json');
 export const PREFETCH_FILE = join(CACHE_DIR, 'prefetch.json');
 export const LOG_FILE = join(CACHE_DIR, 'sweep.log');
+export const VIDEO_DATES_FILE = join(CACHE_DIR, 'video-dates.json'); // videoId → publishedAt, for the monotonic pointer
 // /yt-search (ad-hoc topic search → lazy triage → compare). All throwaway, under .cache/.
 export const SEARCH_QUEUE_FILE = join(CACHE_DIR, 'search-queue.json'); // ranked candidates + cursor
 export const SEARCH_PENDING_FILE = join(CACHE_DIR, 'search-pending.json'); // current candidate awaiting keep/skip

package/dist/lib/video-dates.js

@@ -0,0 +1,45 @@
+/**
+ * Publish dates of every video the sweep has listed, so a state pointer bump can refuse to
+ * move back in time (see pointerWouldRegress). Kept across --reset: the pointer outlives the
+ * queue. Best-effort cache — a missing or corrupt file only turns the guard off.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { VIDEO_DATES_FILE } from "./paths.js";
+/** Entries older than this are dropped on write; the channel listing looks back 45 days. */
+const KEEP_DAYS = 120;
+export function loadVideoDates() {
+    if (!existsSync(VIDEO_DATES_FILE))
+        return {};
+    try {
+        const d = JSON.parse(readFileSync(VIDEO_DATES_FILE, 'utf8'));
+        return d && typeof d === 'object' ? d : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge newly seen videos into the cache (atomic write); no-op when nothing is new. */
+export function rememberVideoDates(videos) {
+    const dates = loadVideoDates();
+    let changed = false;
+    for (const v of videos) {
+        if (!v.publishedAt || !Number.isFinite(Date.parse(v.publishedAt)) || dates[v.videoId] === v.publishedAt)
+            continue;
+        dates[v.videoId] = v.publishedAt;
+        changed = true;
+    }
+    if (!changed)
+        return;
+    const cutoff = Date.now() - KEEP_DAYS * 24 * 60 * 60 * 1000;
+    for (const [id, at] of Object.entries(dates))
+        if (Date.parse(at) < cutoff)
+            delete dates[id];
+    try {
+        mkdirSync(dirname(VIDEO_DATES_FILE), { recursive: true });
+        const tmp = `${VIDEO_DATES_FILE}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(dates));
+        renameSync(tmp, VIDEO_DATES_FILE);
+    }
+    catch { /* best-effort: the guard is only off for dates not written */ }
+}

package/dist/lib/yt-lib.js

@@ -46,6 +46,24 @@ export function parseState(content) {
 export function bumpStateFrontmatterDate(content, date) {
     return content.replace(/^updated:\s*\d{4}-\d{2}-\d{2}/m, `updated: ${date}`);
 }
+/** The state pointer of one type for a channel row (null when unset or the row is missing). */
+export function pointerFor(row, type) {
+    if (!row)
+        return null;
+    return type === 'longform' ? row.last_longform_id : type === 'short' ? row.last_short_id : row.last_live_id;
+}
+/**
+ * Would moving the pointer from `pointerId` to `videoId` move it back in time? `dates` maps
+ * videoIds to publishedAt. Unknown dates answer false (bump as before): only a known older
+ * video is refused. A stale skip applied after the pointer moved on used to rewind it, and
+ * the next queue listed already-rated videos again.
+ */
+export function pointerWouldRegress(pointerId, videoId, publishedAt, dates) {
+    if (!pointerId || pointerId === videoId || !publishedAt)
+        return false;
+    const at = dates[pointerId];
+    return !!at && Date.parse(at) > Date.parse(publishedAt);
+}
 /**
  * Per-video pointer bump. Updates one type's last_id for one channel.
  * Session counter increments only on first touch of the day (updated != date).

package/dist/yt-channel-pending.js

@@ -19,6 +19,7 @@ import { loadEnv } from "./lib/env.js";
 import { parseState } from "./lib/yt-lib.js";
 import { STATE_MD } from "./lib/paths.js";
 import { fetchChannelVideos } from "./lib/yt-api.js";
+import { loadVideoDates, rememberVideoDates } from "./lib/video-dates.js";
 loadEnv();
 const handle = process.argv[2];
 if (!handle) {
@@ -47,6 +48,10 @@ catch (e) {
     console.error(e.message);
     process.exit(1);
 }
+// Date cache read before this listing is added, so a pointer that left the window still has its
+// old date; then every listed video (the pointer too) is remembered for the monotonic bump.
+const videoDates = loadVideoDates();
+rememberVideoDates(videos);
 const pointerByType = {
     longform: row.last_longform_id,
     short: row.last_short_id,
@@ -74,10 +79,12 @@ for (const type of ['longform', 'short', 'live']) {
     }
     // normal: find pointer's publishedAt, take everything strictly newer
     const pointerVideo = ofType.find(v => v.videoId === pointerId);
+    // Pointer not in the fetched window: older than the lookback, or deleted/unlisted. Its date
+    // from the sweep's cache keeps already-seen videos out; without one, take the whole window.
+    const cachedTs = Date.parse(videoDates[pointerId] ?? '');
     const cutoffTs = pointerVideo
         ? new Date(pointerVideo.publishedAt).getTime()
-        : // pointer not in fetched window (older than --since cutoff) — take all videos of this type from response
-            -Infinity;
+        : Number.isFinite(cachedTs) ? cachedTs : -Infinity;
     for (const v of ofType) {
         if (new Date(v.publishedAt).getTime() <= cutoffTs)
             continue;

package/dist/yt-rating.js

@@ -27,7 +27,8 @@ import { spawn } from 'node:child_process';
 import { loadEnv } from "./lib/env.js";
 import { loadConfig } from "./lib/config.js";
 import { distillComment } from "./lib/distill.js";
-import { parseChannels, appendSkipTitle, appendNote, bumpStatePointer } from "./lib/yt-lib.js";
+import { parseChannels, parseState, appendSkipTitle, appendNote, bumpStatePointer, pointerFor, pointerWouldRegress } from "./lib/yt-lib.js";
+import { loadVideoDates } from "./lib/video-dates.js";
 import { CHANNELS_MD, STATE_MD, PENDING_FILE, QUEUE_FILE, profilePath } from "./lib/paths.js";
 loadEnv();
 function getArg(args, name) {
@@ -123,7 +124,14 @@ if (profileAfter !== profileBefore) {
 let stateBumped = false;
 if (!args.noState) {
     const stateBefore = readFileSync(STATE_MD, 'utf8');
-    const stateAfter = bumpStatePointer(stateBefore, args.channel, args.type, args.id, date);
+    // An older video rated after a newer one of the same channel was title-skipped must not
+    // rewind the pointer; the date comes from the sweep's cache of listed videos.
+    const pointer = pointerFor(parseState(stateBefore).find(r => r.handle === args.channel), args.type);
+    const dates = loadVideoDates();
+    const publishedAt = dates[args.id] ?? (() => { const p = loadPending(); return p.videoId === args.id ? p.publishedAt : undefined; })();
+    // Never rewind: re-bump the current pointer instead, so the day's session still counts.
+    const regress = pointer !== null && pointerWouldRegress(pointer, args.id, publishedAt, dates);
+    const stateAfter = bumpStatePointer(stateBefore, args.channel, args.type, regress ? pointer : args.id, date);
     if (stateAfter !== stateBefore) {
         writeFileSync(STATE_MD, stateAfter, 'utf8');
         stateBumped = true;

package/dist/yt-sweep.js

@@ -29,7 +29,8 @@
  *                                      rating) + `seen`. Foreground is the SOLE writer.
  *                                      Tagged with built_at; auto-rebuilt on a new day or via --reset.
  *   - <DATA_DIR>/.cache/queue-rest.json  background-fill handoff written by the --fill child.
- *   - <DATA_DIR>/.cache/pending.json   current ratable video's metadata for yt-rating.ts.
+ *   - <DATA_DIR>/.cache/pending.json   current ratable video's metadata for yt-rating.ts, plus its
+ *                                      emitted summary so a repeat sweep returns it unchanged.
  *   - <DATA_DIR>/.cache/prefetch.json  background-computed summary for the NEXT video.
  *
  *   All .cache/ files are throwaway (rebuilt each run; safe to delete / gitignore).
@@ -50,7 +51,8 @@
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, renameSync, appendFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_YOUTUBE } from "./lib/env.js";
-import { parseChannels, parseState, bumpStatePointer, isResolved } from "./lib/yt-lib.js";
+import { parseChannels, parseState, bumpStatePointer, isResolved, pointerFor, pointerWouldRegress } from "./lib/yt-lib.js";
+import { loadVideoDates, rememberVideoDates } from "./lib/video-dates.js";
 import { chat, claudeMissing } from "./lib/llm.js";
 import { outputLang } from "./lib/config.js";
 import { PKG_ROOT, CHANNELS_MD, STATE_MD, CACHE_DIR, QUEUE_FILE, REST_FILE, PENDING_FILE, PREFETCH_FILE, LOG_FILE, profilePath, script, } from "./lib/paths.js";
@@ -104,9 +106,14 @@ function run(cmd) {
     });
 }
 // ---------- state mutation (inline, crash-safe per write) ----------
-function bumpState(handle, type, videoId) {
+function bumpState(handle, type, videoId, publishedAt) {
     const before = readFileSync(STATE_MD, 'utf8');
-    const after = bumpStatePointer(before, handle, type, videoId, today);
+    const pointer = pointerFor(parseState(before).find(r => r.handle === handle), type);
+    // Never rewind: re-bump the current pointer instead, so the day's session still counts.
+    const regress = pointer !== null && pointerWouldRegress(pointer, videoId, publishedAt, loadVideoDates());
+    if (regress)
+        log(`pointer kept ${handle} ${type} ${pointer} (not rewound to older ${videoId})`);
+    const after = bumpStatePointer(before, handle, type, regress ? pointer : videoId, today);
     if (after !== before)
         writeFileSync(STATE_MD, after, 'utf8');
 }
@@ -116,20 +123,23 @@ function bumpState(handle, type, videoId) {
  */
 function persistSkip(item, status) {
     if (status !== 'no_transcript')
-        bumpState(item.channel, item.type, item.videoId);
+        bumpState(item.channel, item.type, item.videoId, item.publishedAt);
 }
 /**
- * Apply title-skips to state.md. Always bumps the pointer (a title-skip is final).
+ * Apply title-skips to state.md. Bumps the pointer (a title-skip is final) unless that would
+ * rewind it: a background fill's skips are listed against the pointer it saw when it started.
  * Idempotent — re-applying the same skip is a no-op. ONLY the foreground calls this.
  */
 function applyTitleSkips(skips) {
+    rememberVideoDates(skips);
     for (const s of skips) {
-        bumpState(s.channel, s.type, s.videoId);
+        bumpState(s.channel, s.type, s.videoId, s.publishedAt);
         recordSkip({ stage: 'title', channel: s.channel, videoId: s.videoId, title: s.title, reason: s.reason || 'title filter' });
     }
 }
 /** Append items, skipping any videoId already queued OR already resolved (seen). */
 function enqueue(queue, add) {
+    rememberVideoDates(add);
     const have = new Set([...queue.items.map(i => i.videoId), ...queue.seen]);
     for (const it of add)
         if (!have.has(it.videoId)) {
@@ -143,22 +153,30 @@ function dropHead(queue) {
     if (v)
         queue.seen.push(v.videoId);
 }
-function loadPrefetch(videoId) {
-    if (!existsSync(PREFETCH_FILE))
+/**
+ * A summary cached today for `videoId` in `file`: prefetch.json (the warmed next video) or
+ * pending.json (the head already emitted, so a repeat sweep returns it at once and unchanged).
+ */
+function loadCachedSummary(file, videoId) {
+    if (!existsSync(file))
         return null;
     try {
-        const p = JSON.parse(readFileSync(PREFETCH_FILE, 'utf8'));
-        if (p.videoId === videoId && p.built_at === today)
+        const p = JSON.parse(readFileSync(file, 'utf8'));
+        if (p.videoId === videoId && p.built_at === today && p.summary)
             return p.summary;
     }
     catch { /* corrupt → ignore */ }
     return null;
 }
+const loadPrefetch = (videoId) => loadCachedSummary(PREFETCH_FILE, videoId);
 /** Atomic write (temp + rename) so a concurrent reader never sees a partial file. */
+function writeAtomic(file, value) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value));
+    renameSync(tmp, file);
+}
 function writePrefetch(p) {
-    const tmp = `${PREFETCH_FILE}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(p));
-    renameSync(tmp, PREFETCH_FILE);
+    writeAtomic(PREFETCH_FILE, p);
 }
 function clearPrefetch() {
     if (existsSync(PREFETCH_FILE))
@@ -332,7 +350,7 @@ async function expandChannel(ref) {
     const skips = [];
     for (const it of candidates) {
         if (titleSkip.has(it.videoId))
-            skips.push({ channel: it.channel, type: it.type, videoId: it.videoId, title: it.title, reason: titleSkip.get(it.videoId) || 'title filter' });
+            skips.push({ channel: it.channel, type: it.type, videoId: it.videoId, title: it.title, reason: titleSkip.get(it.videoId) || 'title filter', publishedAt: it.publishedAt });
         else
             items.push(it);
     }
@@ -412,11 +430,7 @@ function loadQueue() {
 // ---------- advance (the lazy step) ----------
 /** state.md pointer for this item's type, or null if the channel has no row yet. */
 function statePointer(item) {
-    const row = parseState(readFileSync(STATE_MD, 'utf8')).find(r => r.handle === item.channel);
-    if (!row)
-        return null;
-    return item.type === 'longform' ? row.last_longform_id
-        : item.type === 'short' ? row.last_short_id : row.last_live_id;
+    return pointerFor(parseState(readFileSync(STATE_MD, 'utf8')).find(r => r.handle === item.channel), item.type);
 }
 /**
  * Pure-ish pipeline for one queue item: fetch transcript → substance check + summary.
@@ -458,10 +472,12 @@ async function advance(queue) {
             dropHead(queue);
             continue;
         }
-        // Warm prefetch from the background child? Use it and skip the live fetch + content filter.
-        const cached = loadPrefetch(item.videoId);
+        // Already emitted (the plugin re-runs the sweep after the briefing turn to open the rating
+        // dialog) or warmed by the background child? Use it and skip the live fetch + content filter.
+        const emitted = loadCachedSummary(PENDING_FILE, item.videoId);
+        const cached = emitted ?? loadPrefetch(item.videoId);
         if (cached)
-            log(`prefetch hit ${item.videoId}`);
+            log(`${emitted ? 'pending' : 'prefetch'} hit ${item.videoId}`);
         const result = cached
             ? { kind: 'ratable', summary: cached }
             : await processItem(item);
@@ -485,10 +501,12 @@ async function advance(queue) {
             channel: item.channel, videoId: item.videoId, title: item.title,
             type: item.type, publishedAt: item.publishedAt, is_baseline: item.is_baseline,
         };
-        writeFileSync(PENDING_FILE, JSON.stringify(pending));
+        writeAtomic(PENDING_FILE, { ...pending, summary: result.summary, built_at: today });
         writeFileSync(QUEUE_FILE, JSON.stringify(queue));
-        // Warm the NEXT video in the background while the user rates this one.
-        spawnPrefetch(queue.items[1]);
+        // Warm the NEXT video in the background while the user rates this one. A repeat emit of the
+        // same head already spawned that child; a second one would summarize the next video twice.
+        if (!emitted)
+            spawnPrefetch(queue.items[1]);
         emit({ status: 'rating_needed', summary: result.summary, pending, lang: LANG });
     }
     // All processed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "A self-learning YouTube briefing for Claude Code: it sweeps the channels you follow, filters noise in two stages (title, then transcript), gives you a short briefing of the rest in your language in the chat, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {

package/plugin/hooks/register.tsx

@@ -79,26 +79,28 @@ const STRAY_TAP_MS = 1500
 
 const CHOICES = ['OK', 'Weak', 'Research', 'Stop'] as const
 
-/** What a briefing turn must do, read from the system prompt while the loop runs. */
-function loopSection(reset: boolean): string {
-  const sweep = [...engine('yt-sweep'), ...(reset ? ['--reset'] : [])].join(' ')
+/** What the chat shows of each briefing prompt; the instructions ride along as unseen context. */
+const NEXT_TEXT = 'yt: next video'
+/** The first prompt of a /yt run: the only one that rebuilds the queue. */
+const FIRST_TEXT = 'yt: first video'
+
+/**
+ * What a briefing turn must do, read from the system prompt while the loop runs. The text is the
+ * same for every turn: a session-scoped section may be kept as first composed, so a per-turn
+ * `--reset` here once stuck to every turn and threw away the warmed next video each time.
+ */
+function loopSection(): string {
+  const sweep = engine('yt-sweep').join(' ')
   return [
-    `The yt-briefing plugin is running the person's YouTube briefing. A user message reading exactly "${NEXT_TEXT}" is its request for the next video:`,
-    `run \`${sweep}\`; it prints one JSON line. If \`status\` is \`rating_needed\`, answer with \`summary\` verbatim as your whole message, Markdown kept: nothing before or after it, no question, no tool call after it (the plugin opens the rating dialog itself).`,
+    `The yt-briefing plugin is running the person's YouTube briefing. A user message reading exactly "${FIRST_TEXT}" or "${NEXT_TEXT}" is its request for the next video:`,
+    `for "${FIRST_TEXT}" run \`${sweep} --reset\`, for "${NEXT_TEXT}" run \`${sweep}\`; it prints one JSON line. If \`status\` is \`rating_needed\`, answer with \`summary\` verbatim as your whole message, Markdown kept: nothing before or after it, no question, no tool call after it (the plugin opens the rating dialog itself).`,
     'Otherwise answer with one short line saying why there is nothing to rate. Write in the language of the summaries.',
   ].join('\n')
 }
 
-/** What the chat shows of each briefing prompt; the instructions ride along as unseen context. */
-const NEXT_TEXT = 'yt: next video'
-
-/** Whether the next briefing prompt starts a fresh sweep. */
-let resetNext = false
-
 /** Ask for a briefing once the hook that wants it has answered: one submitted from inside would wait on it. */
 function submitLater($: EngineInterface, reset: boolean) {
-  resetNext = reset
-  $.clock.after(0, () => void $.prompt.submit({ text: NEXT_TEXT, asUser: true }).catch(err => {
+  $.clock.after(0, () => void $.prompt.submit({ text: reset ? FIRST_TEXT : NEXT_TEXT, asUser: true }).catch(err => {
     looping = false
     $.ui.toast(`Could not continue the briefing: ${String(err)}`)
   }))
@@ -176,7 +178,7 @@ export const register: Register = on => {
   on('prompt.compose', async ($, e, next) => {
     const composed = await next(e)
     if (!looping) return composed
-    return { sections: [...composed.sections, { id: 'yt-briefing:loop', text: loopSection(resetNext), scope: 'session' as const }] }
+    return { sections: [...composed.sections, { id: 'yt-briefing:loop', text: loopSection(), scope: 'session' as const }] }
   })
 
   on('turn.complete', async ($, e, next) => {