cchubber 0.5.8 → 0.6.1

package/src/cli/index.js

@@ -5,7 +5,7 @@ import { existsSync, writeFileSync } from 'fs';
 import { homedir, platform } from 'os';
 import { exec } from 'child_process';
 import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { dirname } from 'path';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -18,7 +18,8 @@ import { readSessionMeta } from '../readers/session-meta.js';
 import { readCacheBreaks } from '../readers/cache-breaks.js';
 import { readClaudeMdStack } from '../readers/claude-md.js';
 import { readOAuthUsage } from '../readers/oauth-usage.js';
-import { analyzeUsage, fetchPricing } from '../analyzers/cost-calculator.js';
+import { analyzeUsage, fetchPricing, getLiteLLMRaw } from '../analyzers/cost-calculator.js';
+import { reprice } from '../analyzers/reprice.js';
 import { analyzeCacheHealth } from '../analyzers/cache-health.js';
 import { detectAnomalies } from '../analyzers/anomaly-detector.js';
 import { generateRecommendations } from '../analyzers/recommendations.js';
@@ -27,8 +28,11 @@ import { analyzeSessionIntelligence } from '../analyzers/session-intelligence.js
 import { analyzeModelRouting } from '../analyzers/model-routing.js';
 import { analyzeValueTrend } from '../analyzers/value-tracker.js';
 import { renderHTML } from '../renderers/html-report.js';
-import { renderTerminal } from '../renderers/terminal-summary.js';
-import { shouldSendTelemetry, sendTelemetry } from '../telemetry.js';
+import { renderTerminal, vsOneLiner } from '../renderers/terminal-summary.js';
+import { readPlan, monthsBilled } from '../readers/plan.js';
+import { runDrift, driftForReport } from '../analyzers/drift-run.js';
+import { shouldSendTelemetry, sendTelemetry, beaconConfig } from '../telemetry.js';
+import { spentWellLine } from '../renderers/spent-well.js';
 import { saveRun, getDelta, getHistory } from '../history.js';
 
 const args = process.argv.slice(2);
@@ -37,6 +41,10 @@ const flags = {
   json: args.includes('--json'),
   noTelemetry: args.includes('--no-telemetry'),
   noOpen: args.includes('--no-open'),
+  drift: args.includes('--drift'),
+  vs: args.includes('--vs'),
+  redact: args.includes('--redact'),
+  plan: (() => { const i = args.indexOf('--plan'); return i !== -1 && args[i + 1] ? args[i + 1] : null; })(),
   output: (() => {
     const idx = args.indexOf('--output') !== -1 ? args.indexOf('--output') : args.indexOf('-o');
     return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
@@ -62,7 +70,9 @@ if (flags.help) {
     --days, -d <n>     Analyze last N days (default: 30)
     --output, -o <path> Output HTML report to custom path
     --no-open          Don't auto-open the report in browser
-    --json             Output raw analysis as JSON
+    --json             Output raw analysis as JSON (includes reprice: your usage on other models)
+    --plan <usd>       Monthly plan price, if it can't be detected
+    --redact           Show drift detours as categories instead of your own words
     -h, --help         Show this help
 
   Examples:
@@ -70,6 +80,23 @@ if (flags.help) {
     cchubber --days 7           Last 7 days only
     cchubber -o report.html     Custom output path
     cchubber --json             Machine-readable output
+    cchubber --redact           Same report, drift detours as categories only
+
+  Nothing here needs a flag. The report that cchubber opens has a section for
+  how much of your last week went to what you said you'd do (read from a
+  PLAN.md, plan.md or TODO.md, computed locally), and one for
+  your usage on other models.
+
+  Your usage on other models needs no flag. The report that cchubber opens has
+  a section for it: your own tokens repriced on each frontier model's list
+  price, a race built from your real days, and buttons to download a card, copy
+  the text or post it on X. Prices come live from LiteLLM, plus a manual entry
+  for a listed model LiteLLM does not carry yet (used only until LiteLLM has
+  it). Offline it uses bundled prices dated 30 Sep 2026. When a plan you wrote
+  down is found (plan.md or similar) the section also shows how much of your
+  last week went to it, computed locally.
+  Same tokens on each model's list price, cache included. Another model would
+  use a different number of tokens, so this compares prices, not outcomes.
 
   Shipped with Mover OS at speed.
   https://moveros.dev
@@ -86,6 +113,14 @@ async function main() {
     process.exit(1);
   }
 
+  // Hidden, for scripts: `--vs --json` prints only the repricing (no report work). Plain `--vs` is an alias of the normal
+  // run that opens the report scrolled to its "Your usage on other models" section. Nothing needs the flag.
+  if (flags.vs && flags.json) return vsJsonMode(claudeDir);
+
+  // Hidden, for scripts: `--drift --json` prints only the drift analysis. Plain `--drift` is an alias of the normal run
+  // that opens the report scrolled to its drift section. Nothing needs the flag.
+  if (flags.drift && flags.json) return driftJsonMode(claudeDir);
+
   console.log(`
     /\\  _  /\\
    /  \\(_)/  \\   CC Hubber v${VERSION}
@@ -157,6 +192,14 @@ async function main() {
   if (communityStats) console.log(`  ✓ Community data: ${communityStats.totalReports} users from ${Object.keys(communityStats.countries || {}).length} countries`);
   else console.log('  ○ Community data unavailable (offline)');
 
+  // Your usage on other models. Never allowed to break the normal run.
+  let vsData = null;
+  try {
+    const live = getLiteLLMRaw();
+    vsData = reprice(costAnalysis, { raw: live?.data, fetchedAt: live?.fetchedAt });
+    console.log(vsData.offline ? '  ○ Other-model prices offline: bundled prices as of 30 Sep 2026' : '  ✓ Other-model prices: LiteLLM');
+  } catch { vsData = null; }
+
   const report = {
     generatedAt: new Date().toISOString(),
     periodDays: flags.days,
@@ -172,6 +215,7 @@ async function main() {
     recommendations,
     valueTrend,
     communityStats,
+    reprice: vsData,
     history: getHistory(),
   };
 
@@ -198,6 +242,12 @@ async function main() {
 
   renderTerminal(report);
 
+  // One line on what the same tokens would cost elsewhere; the rest is in the report.
+  try { const line = vsOneLiner(vsData); if (line) console.log(`\n  ${line}`); } catch {}
+
+  // The report's "Did you spend them well?" strip, pointed at from the terminal.
+  try { const line = spentWellLine(report); if (line) console.log(`\n  ${line}`); } catch {}
+
   // Anonymous telemetry (opt out: --no-telemetry or CC_HUBBER_TELEMETRY=0)
   if (shouldSendTelemetry(flags)) {
     console.log('  ○ Sharing anonymous stats...');
@@ -206,26 +256,84 @@ async function main() {
   }
 
   const outputPath = flags.output || join(process.cwd(), 'cchubber-report.html');
-  const html = renderHTML(report);
+  // Drift is part of the plain report: the last week against what you wrote down, computed locally (about 2 seconds).
+  const drift = driftForReport(claudeDir, { days: flags.days === 30 ? 7 : flags.days });
+  console.log(driftLine(drift));
+  const vsCtx = vsData ? vsContext(vsData, drift) : null;
+  const html = renderHTML(report, { vs: vsCtx, drift: { ...drift, redact: flags.redact }, telemetry: beaconConfig(flags) });
   writeFileSync(outputPath, html, 'utf-8');
   console.log(`\n  ✓ Report saved to: ${outputPath}`);
 
   if (!flags.noOpen) {
-    openInBrowser(outputPath);
+    openInBrowser(outputPath, flags.drift ? 'drift' : flags.vs ? 'vs' : '');
     console.log('  ✓ Opened in browser\n');
   }
 }
 
+// The terminal line for drift, honest about why there is no number when there is none.
+function driftLine(d) {
+  if (d.state === 'ok') return `  ✓ Drift: ${Math.round(d.drift.share * 100)}% of your last ${d.days} days went to what you said you'd do. It's in your report.`;
+  if (d.state === 'no-plan') return '  ○ Drift: no written plan found. Add a PLAN.md or TODO.md with a checklist to see it in your report.';
+  if (d.state === 'no-work') return `  ○ Drift: no Claude Code work in the last ${d.days} days, so nothing to measure.`;
+  return '  ○ Drift: could not be read this time. No number shown.';
+}
+
+// What the "other models" section needs beyond the repricing: the plan paid for (if detected), billing months over the
+// logged window, and the drift headline when a written plan was found.
+function vsContext(rp, drift) {
+  const plan = readPlan(flags.plan);
+  const dates = rp.dailyCum.dates;
+  const months = dates.length ? monthsBilled(dates[0], dates[dates.length - 1], plan?.since) : 1;
+  const driftPct = drift.state === 'ok' ? Math.round(drift.drift.share * 100) : null;
+  return { plan, months, driftPct };
+}
+
 function getClaudeDir() {
   const home = homedir();
   return join(home, '.claude');
 }
 
-function openInBrowser(filePath) {
+async function vsJsonMode(claudeDir) {
+  // Progress goes to stderr so stdout is clean JSON
+  const log = (m) => process.stderr.write(m + '\n');
+  log('  Reading local Claude Code data...');
+
+  const jsonlEntries = readAllJSONL(claudeDir);
+  const statsCache = readStatsCache(claudeDir);
+  if (jsonlEntries.length === 0 && !statsCache) {
+    console.error('  ✗ No usage data found. Use Claude Code first, then run CC Hubber.\n');
+    process.exit(1);
+  }
+  const sessionMeta = readSessionMeta(claudeDir);
+  const dailyFromJSONL = aggregateDaily(jsonlEntries);
+  const modelFromJSONL = aggregateByModel(jsonlEntries);
+
+  await fetchPricing();
+  const live = getLiteLLMRaw();
+  const costAnalysis = analyzeUsage(statsCache, sessionMeta, 99999, dailyFromJSONL, modelFromJSONL);
+  const rp = reprice(costAnalysis, { raw: live?.data, fetchedAt: live?.fetchedAt });
+  log(rp.offline ? '  ○ Offline: prices as of 30 Sep 2026 (bundled)' : '  ✓ Live prices from LiteLLM');
+  process.stdout.write(JSON.stringify(rp, null, 2) + '\n');
+}
+
+async function driftJsonMode(claudeDir) {
+  const days = flags.days === 30 ? 7 : flags.days; // 7-day week by default; --days overrides
+  process.stderr.write(`  Reading the last ${days} days of local sessions...\n`);
+  const drift = runDrift(claudeDir, { days });
+  if (!drift.available) {
+    console.error('  ✗ No agent work found in the window. Use Claude Code (or Codex) this week, then try again.\n');
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify(drift, null, 2) + '\n');
+}
+
+function openInBrowser(filePath, hash = '') {
   const p = platform();
-  const cmd = p === 'win32' ? `start "" "${filePath}"`
-    : p === 'darwin' ? `open "${filePath}"`
-    : `xdg-open "${filePath}"`;
+  // A file URL lets the browser scroll to a #section; a bare path cannot carry one.
+  const target = hash ? `${pathToFileURL(filePath).href}#${hash}` : filePath;
+  const cmd = p === 'win32' ? `start "" "${target}"`
+    : p === 'darwin' ? `open "${target}"`
+    : `xdg-open "${target}"`;
   exec(cmd, (err) => { if (err) console.log('  ○ Could not auto-open browser. Open the file manually.'); });
 }
 

package/src/data/frontier-models.js

@@ -0,0 +1,12 @@
+// The explicit comparison list for --vs. `id` is the LiteLLM key (model_prices_and_context_window.json).
+// Edit this list to add or drop a model; nothing else needs to change.
+export const FRONTIER_MODELS = [
+  { id: 'claude-fable-5-1', label: 'Claude Fable 5.1', maker: 'Anthropic' },
+  { id: 'claude-opus-5-5', label: 'Claude Opus 5.5', maker: 'Anthropic' },
+  { id: 'claude-sonnet-5-5', label: 'Claude Sonnet 5.5', maker: 'Anthropic' },
+  { id: 'gpt-6-astra', label: 'GPT-6 Astra', maker: 'OpenAI' },
+  { id: 'gpt-6-sol', label: 'GPT-6 Sol', maker: 'OpenAI' },
+  { id: 'gemini-4-argon', label: 'Gemini 4 Argon', maker: 'Google' },
+  { id: 'deepseek-v4-pro', label: 'DeepSeek V4 Pro', maker: 'DeepSeek' },
+  { id: 'moonshot/kimi-k3', label: 'Kimi K3', maker: 'Moonshot' },
+];

package/src/data/price-overrides.js

@@ -0,0 +1,16 @@
+// Manual prices for listed models that LiteLLM does not carry yet. Used ONLY when LiteLLM has no entry for the id,
+// so live data wins the day LiteLLM adds the model. All prices are USD per million tokens.
+//
+// A missing cacheWrite is deliberate: Google lists no cache-write premium, so reprice.js bills writes at the input
+// rate and records that in `filled` (an assumption, not a published price).
+export const PRICE_OVERRIDES = {
+  'gemini-4-argon': {
+    intro: { input: 2, output: 10, cacheRead: 0.10 },   // cached input is 95% off the input price
+    after: { input: 4, output: 20, cacheRead: 0.20 },   // standard price once the introductory period ends
+    sourceUrl: 'https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-4-argon/',
+    sourceName: 'blog.google',
+    checked: '2026-09-30',
+    note: 'introductory price',
+    assumption: 'Google lists no cache-write premium, so cache writes are priced at the input rate.',
+  },
+};

package/src/data/price-snapshot.json

@@ -0,0 +1,49 @@
+{
+  "date": "2026-09-30",
+  "source": "LiteLLM model_prices_and_context_window.json",
+  "note": "USD per million tokens as LiteLLM lists them; null means the field is absent (reprice.js fills it from the input price).",
+  "models": {
+    "claude-fable-5-1": {
+      "input": 10,
+      "output": 50,
+      "cacheRead": 0.25,
+      "cacheWrite": 12.5
+    },
+    "claude-opus-5-5": {
+      "input": 4,
+      "output": 20,
+      "cacheRead": 0.2,
+      "cacheWrite": 5
+    },
+    "claude-sonnet-5-5": {
+      "input": 2,
+      "output": 10,
+      "cacheRead": 0.2,
+      "cacheWrite": 2.5
+    },
+    "gpt-6-astra": {
+      "input": 10,
+      "output": 50,
+      "cacheRead": 1,
+      "cacheWrite": 12.5
+    },
+    "gpt-6-sol": {
+      "input": 2,
+      "output": 10,
+      "cacheRead": 0.2,
+      "cacheWrite": 2.5
+    },
+    "deepseek-v4-pro": {
+      "input": 1.32,
+      "output": 3.96,
+      "cacheRead": 0.044,
+      "cacheWrite": 0
+    },
+    "moonshot/kimi-k3": {
+      "input": 3,
+      "output": 15,
+      "cacheRead": 0.3,
+      "cacheWrite": null
+    }
+  }
+}

package/src/readers/jsonl-reader.js

@@ -8,24 +8,21 @@ import { homedir } from 'os';
  * Claude Code stores full conversation transcripts with token usage per message.
  */
 export function readAllJSONL(claudeDir) {
-  const projectsDir = join(claudeDir, 'projects');
-  const xdgDir = join(homedir(), '.config', 'claude', 'projects'); // XDG fallback for Linux
-
   const entries = [];
-
-  // Read from primary location
-  if (existsSync(projectsDir)) {
-    readProjectsDir(projectsDir, entries);
-  }
-
-  // XDG fallback (Linux with newer Claude Code)
-  if (existsSync(xdgDir) && xdgDir !== projectsDir) {
-    readProjectsDir(xdgDir, entries);
-  }
-
+  for (const dir of projectRoots(claudeDir)) readProjectsDir(dir, entries);
   return entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
 }
 
+/**
+ * Where Claude Code keeps its transcripts: ~/.claude/projects, plus the XDG path newer Linux builds use.
+ * Shared with the drift reader so both read the same sessions.
+ */
+export function projectRoots(claudeDir) {
+  const projectsDir = join(claudeDir, 'projects');
+  const xdgDir = join(homedir(), '.config', 'claude', 'projects');
+  return [projectsDir, xdgDir].filter((d, i, all) => all.indexOf(d) === i && existsSync(d));
+}
+
 function readProjectsDir(dir, entries) {
   try {
     const projectHashes = readdirSync(dir).filter(f => {

package/src/readers/plan.js

@@ -0,0 +1,56 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// Monthly list prices from claude.com/pricing and the Max plan help page, checked 29 Sep 2026 (US web prices, before tax).
+const PLAN_PRICES = { pro: 20, max_5x: 100, max_20x: 200 };
+const PLAN_NAMES = { pro: 'Claude Pro', max_5x: 'Claude Max 5x', max_20x: 'Claude Max 20x' };
+
+// Reads only the plan tier and start date from ~/.claude.json. Tokens and keys in that file are never touched.
+export function readPlan(override) {
+  if (override) {
+    const usd = Number(override);
+    if (Number.isFinite(usd) && usd > 0) return { key: 'custom', name: 'your plan', monthlyUSD: usd, since: null };
+  }
+  const file = join(homedir(), '.claude.json');
+  if (!existsSync(file)) return null;
+  try {
+    const acct = JSON.parse(readFileSync(file, 'utf-8')).oauthAccount || {};
+    const tier = String(acct.organizationRateLimitTier || acct.userRateLimitTier || '').toLowerCase();
+    const key = tier.includes('max_20x') ? 'max_20x' : tier.includes('max_5x') ? 'max_5x' : tier.includes('pro') ? 'pro' : null;
+    if (!key) return null;
+    return { key, name: PLAN_NAMES[key], monthlyUSD: PLAN_PRICES[key], since: acct.subscriptionCreatedAt || null };
+  } catch {
+    return null;
+  }
+}
+
+// `d` plus `k` months, clamped to the last day of a shorter month: a plan billed on the 31st renews 28 Feb, 31 Mar, 30 Apr.
+// (setUTCMonth alone rolls 31 Jan + 1 month over to 3 Mar, which silently drops February.)
+function addMonths(d, k) {
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth() + k;
+  const lastDay = new Date(Date.UTC(y, m + 1, 0)).getUTCDate();
+  return new Date(Date.UTC(y, m, Math.min(d.getUTCDate(), lastDay)));
+}
+
+// Billing months inside the window the logs cover: every charge whose month overlaps it. Counting only the logged window
+// keeps "paid" and "consumed" about the same days, since Claude Code prunes old transcripts by default.
+// Charges land on the subscription's own anniversary (`since`, when ~/.claude.json has it), not on the first logged day;
+// without it the first logged day stands in as the billing day.
+export function monthsBilled(firstDate, lastDate, since) {
+  const a = new Date(firstDate + 'T00:00:00Z');
+  const b = new Date(lastDate + 'T00:00:00Z');
+  if (isNaN(a) || isNaN(b) || b < a) return 1;
+  let anchor = a;
+  if (since) {
+    const s = new Date(String(since).slice(0, 10) + 'T00:00:00Z');
+    if (!isNaN(s) && s <= b) anchor = s;
+  }
+  let n = 0;
+  for (let k = 0; ; k++) {
+    if (addMonths(anchor, k) > b) break;
+    if (addMonths(anchor, k + 1) > a) n++;
+  }
+  return Math.max(1, n);
+}

package/src/readers/stated-plan.js

@@ -0,0 +1,187 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, dirname, resolve, relative, isAbsolute, sep } from 'path';
+import { homedir } from 'os';
+
+/**
+ * "What you said you'd do", when you wrote it down. Two kinds of written plan are read, both local:
+ *   - Mover OS: the day's Daily Note (Focus and Tasks), and the plan.md of the vault project a session ran in
+ *   - anywhere else: a PLAN.md, plan.md or TODO.md in the session's project folder
+ * Only checklist items and focus lines are read. Nothing else in these files is used, and nothing leaves the machine.
+ */
+
+const PLAN_NAMES = ['PLAN.md', 'plan.md', 'TODO.md', 'todo.md'];
+// A plan with more open items than this is a long-running tracker, not a short to-do list. It is still used, as the
+// project's vocabulary, but the report says "on the project" rather than "on this week's list".
+export const BIG_PLAN_ITEMS = 60;
+const CHECKBOX = /^\s*[-*+]\s+\[([ xX~\/>-])\]\s+(.+)$/;
+
+// Mover's vault, from ~/.mover/config.json. Only vaultPath is read.
+export function moverVault(configPath = join(homedir(), '.mover', 'config.json')) {
+  if (!existsSync(configPath)) return null;
+  try {
+    const vault = JSON.parse(readFileSync(configPath, 'utf-8')).vaultPath;
+    return typeof vault === 'string' && existsSync(vault) ? vault : null;
+  } catch {
+    return null;
+  }
+}
+
+// Checklist items and focus lines, cleaned of Obsidian syntax and Mover's bookkeeping tags
+export function cleanItem(text) {
+  return String(text)
+    .replace(/\[\[([^\]|]+)\|([^\]]+)\]\]/g, '$2')
+    .replace(/\[\[([^\]]+)\]\]/g, '$1')
+    .replace(/\s\^[\w-]+\s*$/, '')
+    .replace(/\[(Added|Due|Moved|Carried|From|UNVERIFIED|HYPOTHESIS ONLY)[^\]]*\]/gi, '')
+    .replace(/[*_`]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// A template placeholder like "[The ONE thing that makes today a win]" is not a plan
+const isPlaceholder = (s) => !s || /^\[.*\]$/.test(s) || /^\(.*\)$/.test(s);
+
+// Section headers that are structure or bookkeeping, not a statement of work
+const BORING_HEADER = /^(#+\s*)?(\d+\.|phase\b|execution log|the roadmap|the north star|the architecture|changelog|notes|project control|deferred|resolved|table of|contents|appendix|status|done|completed|in progress|todo|backlog|log\b)/i;
+
+export function parsePlanText(text) {
+  const open = [];   // still-to-do items: the plain reading of "what you said you'd do"
+  const all = [];    // every item, open or done, plus real section headers: the project's stated work, for matching
+  for (const line of String(text).split('\n')) {
+    const m = line.match(CHECKBOX);
+    if (m) {
+      const item = cleanItem(m[2]);
+      if (isPlaceholder(item) || m[1] === '-') continue; // placeholder or dropped
+      all.push(item);
+      // [x] done, [~] done but unchecked in Mover's convention; everything else is still open
+      if (!/[xX~]/.test(m[1])) open.push(item);
+      continue;
+    }
+    // Section headers carry the intent of long trackers (Mover writes the verbatim brief into each "## R157 ..."),
+    // which the terse checkboxes below them do not. Skip the structural and bookkeeping ones.
+    const h = line.match(/^(#{2,4})\s+(.+?)\s*#*$/);
+    if (h && !BORING_HEADER.test(line)) {
+      const item = cleanItem(h[2].replace(/[🏁🏗️⚡🧹🧠📚🔄🎓✅⚙️📋🔧]/gu, ''));
+      if (item.length > 6 && !isPlaceholder(item)) all.push(item);
+    }
+  }
+  return { open, all };
+}
+
+// A Daily Note's Focus lines (Single Test, The Hard Thing) and its task list. The Sacrifice is what you said you
+// would NOT do, so it is left out.
+export function parseDailyNote(text) {
+  const items = [];
+  let section = null;
+  for (const line of String(text).split('\n')) {
+    const h = line.match(/^##\s+(.+?)\s*$/);
+    if (h) { section = /^focus/i.test(h[1]) ? 'focus' : /^tasks/i.test(h[1]) ? 'tasks' : null; continue; }
+    if (/^#\s/.test(line)) { section = null; continue; }
+    if (section === 'focus') {
+      const f = line.match(/^\s*[-*]\s+\*\*(Single Test|The Hard Thing|Focus|Main Quest)[^*]*\*\*:?\s*(.+)$/i);
+      if (f) {
+        const item = cleanItem(f[2]);
+        if (!isPlaceholder(item)) items.push(item);
+      }
+    } else if (section === 'tasks') {
+      const m = line.match(CHECKBOX);
+      if (m && m[1] !== '-') {
+        const item = cleanItem(m[2]);
+        if (!isPlaceholder(item)) items.push(item);
+      }
+    }
+  }
+  return items;
+}
+
+export function dailyNotePath(vault, dayKey) {
+  return join(vault, '02_Areas', 'Engine', 'Dailies', dayKey.slice(0, 7), `Daily - ${dayKey}.md`);
+}
+
+const inside = (child, parent) => {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+// The plan file for a session's folder: in a Mover vault, the project's plan.md (or dev/plan.md); anywhere else,
+// the nearest PLAN.md / plan.md / TODO.md between the folder and its git root
+export function findPlanFile(cwd, vault) {
+  if (!cwd) return null;
+  const dir = resolve(cwd);
+  if (vault && inside(dir, join(vault, '01_Projects'))) {
+    const project = relative(join(vault, '01_Projects'), dir).split(sep)[0];
+    if (!project) return null;
+    const root = join(vault, '01_Projects', project);
+    for (const f of ['plan.md', join('dev', 'plan.md')]) if (existsSync(join(root, f))) return join(root, f);
+    return null;
+  }
+  const home = homedir();
+  let d = dir;
+  for (let i = 0; i < 6; i++) {
+    for (const name of PLAN_NAMES) {
+      const f = join(d, name);
+      try { if (statSync(f).isFile()) return f; } catch { /* not here */ }
+    }
+    if (existsSync(join(d, '.git')) || d === home) break;
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return null;
+}
+
+/**
+ * Plan lookup for the analyzer: planFor(cwd, dayKey) returns { sources: [...], items } or null.
+ * `notes` records plans that were found and set aside, so the report can say why.
+ */
+export function readStatedPlans({ vault = moverVault() } = {}) {
+  const planCache = new Map();
+  const dailyCache = new Map();
+  const notes = new Map();
+
+  const plan = (cwd) => {
+    const file = findPlanFile(cwd, vault);
+    if (!file) return null;
+    if (!planCache.has(file)) {
+      let parsed = null;
+      try { parsed = parsePlanText(readFileSync(file, 'utf-8')); } catch { /* unreadable */ }
+      const name = file.split(sep).pop();
+      if (parsed && parsed.all.length) {
+        const big = parsed.open.length > BIG_PLAN_ITEMS;
+        // A short to-do list is matched item by item. A long tracker is matched as a whole: any of the project's
+        // work counts as on the plan, so "on-plan" reads as "on this project".
+        planCache.set(file, { name, items: parsed.all, scope: big ? 'project' : 'list', open: parsed.open.length });
+        if (big) notes.set(file, { name, open: parsed.open.length, scope: 'project' });
+      } else {
+        planCache.set(file, null);
+      }
+    }
+    return planCache.get(file);
+  };
+
+  const daily = (dayKey) => {
+    if (!vault) return null;
+    if (!dailyCache.has(dayKey)) {
+      const file = dailyNotePath(vault, dayKey);
+      let items = [];
+      try { items = parseDailyNote(readFileSync(file, 'utf-8')); } catch { /* no note that day */ }
+      dailyCache.set(dayKey, items.length ? { name: 'Daily Note', items, scope: 'list' } : null);
+    }
+    return dailyCache.get(dayKey);
+  };
+
+  return {
+    mover: Boolean(vault),
+    // A day's Daily-Note focus is the sharpest statement of intent, so it leads; the project's plan backs it.
+    planFor(cwd, dayKey) {
+      const found = [daily(dayKey), plan(cwd)].filter(Boolean);
+      if (!found.length) return null;
+      return {
+        sources: found.map(f => f.name),
+        scope: found.some(f => f.scope === 'list') ? 'list' : 'project',
+        items: found.flatMap(f => f.items),
+      };
+    },
+    notes: () => [...notes.values()],
+  };
+}