claude-mission-control 1.5.0

package/lib/opener.js

@@ -0,0 +1,104 @@
+'use strict';
+// Launch a session in the configured terminal or the Claude desktop app.
+// Paths come from OUR collected state, never from the client.
+const { execFile } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { readConfig, detectTerminals, detectClaudeApp } = require('./config');
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function run(cmd, args) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: 10_000 }, (err) => {
+      resolve(err ? { ok: false, error: String(err.message).slice(0, 200) } : { ok: true });
+    });
+  });
+}
+
+function sq(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// Launch `shellCmd` in a new window of the configured terminal, cwd set.
+function launchInTerminal(cwd, shellCmd) {
+  const configured = readConfig().terminal;
+  const installed = detectTerminals();
+  const terminal = installed.some((t) => t.id === configured)
+    ? configured
+    : (installed[0] || { id: process.platform === 'win32' ? 'cmd' : 'terminal' }).id;
+
+  if (process.platform === 'win32') {
+    // Untested on real Windows — via `start` so the window detaches.
+    if (terminal === 'wt') {
+      return run('cmd', ['/c', 'start', '', 'wt', '-d', cwd, 'cmd', '/k', shellCmd]);
+    }
+    if (terminal === 'powershell') {
+      return run('cmd', ['/c', 'start', '', 'powershell', '-NoExit', '-Command',
+        `Set-Location -LiteralPath '${cwd.replace(/'/g, "''")}'; ${shellCmd}`]);
+    }
+    return run('cmd', ['/c', 'start', '', 'cmd', '/k', `cd /d "${cwd}" && ${shellCmd}`]);
+  }
+
+  if (process.platform === 'linux') {
+    const keepAlive = `cd ${sq(cwd)} && ${shellCmd}; exec bash -i`;
+    if (terminal === 'gnome-terminal') {
+      return run('gnome-terminal', [`--working-directory=${cwd}`, '--', 'bash', '-c', keepAlive]);
+    }
+    if (terminal === 'konsole') {
+      return run('konsole', ['--workdir', cwd, '-e', 'bash', '-c', keepAlive]);
+    }
+    if (terminal === 'kitty' || terminal === 'alacritty') {
+      return run(terminal, ['--working-directory', cwd, '-e', 'bash', '-c', keepAlive]);
+    }
+    return run('xterm', ['-e', 'bash', '-c', keepAlive]);
+  }
+
+  if (terminal === 'ghostty') {
+    return run('open', [
+      '-na', 'Ghostty.app', '--args',
+      `--working-directory=${cwd}`,
+      '-e', 'zsh', '-ilc', shellCmd,
+    ]);
+  }
+
+  // iTerm2 / Terminal.app: a temp .command file avoids AppleScript permission
+  // prompts. `exec zsh -i` keeps the window alive after the command exits.
+  const script = `#!/bin/zsh\ncd ${sq(cwd)}\n${shellCmd}\nexec zsh -i\n`;
+  const file = path.join(os.tmpdir(), `claude-dash-${Date.now()}-${Math.floor(Math.random() * 1e6)}.command`);
+  try {
+    fs.writeFileSync(file, script, { mode: 0o755 });
+  } catch (e) {
+    return Promise.resolve({ ok: false, error: String(e.message).slice(0, 200) });
+  }
+  const app = terminal === 'iterm' ? 'iTerm' : 'Terminal';
+  return run('open', ['-a', app, file]);
+}
+
+function openSession({ sessionId, cwd, target }) {
+  if (!UUID_RE.test(sessionId)) {
+    return Promise.resolve({ ok: false, error: 'invalid session id' });
+  }
+  if (target === 'app') {
+    if (!detectClaudeApp()) {
+      return Promise.resolve({ ok: false, error: 'Claude desktop app is not installed' });
+    }
+    // Claude desktop deep link: imports the CLI session transcript.
+    const url = `claude://resume?session=${sessionId}`;
+    if (process.platform === 'win32') return run('cmd', ['/c', 'start', '', url]);
+    if (process.platform === 'linux') return run('xdg-open', [url]);
+    return run('open', [url]);
+  }
+  if (target === 'terminal') {
+    if (!cwd) return Promise.resolve({ ok: false, error: 'unknown project path for session' });
+    return launchInTerminal(cwd, `claude --resume ${sessionId}`);
+  }
+  return Promise.resolve({ ok: false, error: 'unknown target' });
+}
+
+function openNewSession(cwd) {
+  return launchInTerminal(cwd, 'claude');
+}
+
+module.exports = { openSession, openNewSession };

package/lib/paths.js

@@ -0,0 +1,39 @@
+'use strict';
+// Shared path helpers: canonicalization, worktree grouping, project-dir encoding.
+const path = require('path');
+const os = require('os');
+
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+
+// Canonical form used for all internal keys and comparisons: resolved,
+// forward slashes on every platform (Windows paths become C:/Users/...),
+// no trailing slash. Display strings keep whatever the source gave us.
+function canonicalize(p) {
+  if (!p) return p;
+  // Don't run path.resolve on a Windows-style path when we're not on Windows
+  // (it would prefix the posix cwd) — those appear in tests and in data
+  // copied between machines.
+  const winStyle = /^[A-Za-z]:[\\/]/.test(p);
+  let r = winStyle && process.platform !== 'win32' ? p : path.resolve(p);
+  r = r.replace(/\\/g, '/');
+  if (r.length > 1 && r.endsWith('/')) r = r.slice(0, -1);
+  return r;
+}
+
+// A session run inside `<repo>/.claude/worktrees/<name>` belongs to <repo>.
+// Returns { root, worktree } where worktree is the worktree folder name or null.
+function worktreeRoot(p) {
+  const c = canonicalize(p);
+  const m = c.match(/^(.*)\/\.claude\/worktrees\/([^/]+)$/);
+  if (m) return { root: m[1], worktree: m[2] };
+  return { root: c, worktree: null };
+}
+
+// Encode a real path the way ~/.claude/projects dir names are built.
+// Forward-only (real path -> encoded); never decode, the mapping is lossy.
+// Windows drive colons become dashes too (best guess — unverified on Windows).
+function encodeProjectDir(p) {
+  return canonicalize(p).replace(/[/:. ]/g, '-');
+}
+
+module.exports = { CLAUDE_DIR, canonicalize, worktreeRoot, encodeProjectDir };

package/lib/plan.js

@@ -0,0 +1,58 @@
+'use strict';
+// Plan detection from Claude Code's own local account cache
+// (~/.claude.json -> oauthAccount). Local-only; no tokens are read.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CLAUDE_JSON = path.join(os.homedir(), '.claude.json');
+
+let cache = { mtimeMs: 0, plan: null };
+
+const TYPE_LABELS = {
+  claude_max: 'Max',
+  claude_pro: 'Pro',
+  claude_free: 'Free',
+  claude_team: 'Team',
+  claude_enterprise: 'Enterprise',
+};
+
+function planLabel(orgType, tier) {
+  const base = TYPE_LABELS[orgType] || (orgType ? orgType.replace(/^claude_/, '') : null);
+  if (!base) return null;
+  const mult = tier && tier.match(/_(\d+x)$/);
+  return mult ? `${base} ${mult[1]}` : base;
+}
+
+function readPlan() {
+  let st;
+  try {
+    st = fs.statSync(CLAUDE_JSON);
+  } catch {
+    return null;
+  }
+  if (st.mtimeMs === cache.mtimeMs) return cache.plan;
+  let plan = null;
+  try {
+    const oa = JSON.parse(fs.readFileSync(CLAUDE_JSON, 'utf8')).oauthAccount;
+    if (oa && (oa.organizationType || oa.emailAddress)) {
+      plan = {
+        label: planLabel(oa.organizationType, oa.organizationRateLimitTier) || 'unknown',
+        tier: oa.userRateLimitTier || oa.organizationRateLimitTier || null,
+        organization: oa.organizationName || null,
+        email: oa.emailAddress || null,
+        extraUsage: oa.hasExtraUsageEnabled === true,
+        billing: oa.billingType || null,
+      };
+    } else {
+      // No OAuth account cached — likely API-key auth.
+      plan = { label: 'API', tier: null, organization: null, email: null, extraUsage: false, billing: 'api' };
+    }
+  } catch {
+    /* keep null */
+  }
+  cache = { mtimeMs: st.mtimeMs, plan };
+  return plan;
+}
+
+module.exports = { readPlan, planLabel };

package/lib/pricing.js

@@ -0,0 +1,72 @@
+'use strict';
+// Estimated cost from token usage, at Anthropic list rates (USD per MTok).
+// Cache read = 0.1x input; cache write = 1.25x input (5-minute TTL).
+// These are list-price estimates — on a Max plan they show relative weight,
+// not billed dollars. Rates cached 2026-08; matched by id prefix.
+const RATES = [
+  { prefix: 'claude-fable-5', input: 10, output: 50 },
+  { prefix: 'claude-mythos', input: 10, output: 50 },
+  { prefix: 'claude-opus-4-1', input: 15, output: 75 },
+  { prefix: 'claude-opus-4-0', input: 15, output: 75 },
+  { prefix: 'claude-opus-4-2025', input: 15, output: 75 },
+  { prefix: 'claude-opus', input: 5, output: 25 }, // opus-5, 4-8, 4-7, 4-6, 4-5
+  { prefix: 'claude-sonnet', input: 3, output: 15 },
+  { prefix: 'claude-haiku-4', input: 1, output: 5 },
+  { prefix: 'claude-3-5-haiku', input: 0.8, output: 4 },
+  { prefix: 'claude-haiku', input: 1, output: 5 },
+];
+const DEFAULT_RATE = { input: 5, output: 25 }; // unknown model: assume opus-tier
+
+function rateFor(model) {
+  const m = String(model || '');
+  for (const r of RATES) if (m.startsWith(r.prefix)) return r;
+  return DEFAULT_RATE;
+}
+
+// usageByModel: { [model]: {input, output, cacheRead, cacheCreation} } (token counts)
+function estimateCost(usageByModel) {
+  let usd = 0;
+  for (const [model, u] of Object.entries(usageByModel || {})) {
+    const r = rateFor(model);
+    usd +=
+      ((u.input || 0) * r.input +
+        (u.output || 0) * r.output +
+        (u.cacheRead || 0) * r.input * 0.1 +
+        (u.cacheCreation || 0) * r.input * 1.25) /
+      1_000_000;
+  }
+  return usd;
+}
+
+function totalTokens(usageByModel) {
+  let t = 0;
+  for (const u of Object.values(usageByModel || {})) {
+    t += (u.input || 0) + (u.output || 0) + (u.cacheRead || 0) + (u.cacheCreation || 0);
+  }
+  return t;
+}
+
+// Highest budget threshold crossed (0, 75, 90, or 100), for one-shot alerts.
+function budgetLevel(spent, budget) {
+  if (!budget || budget <= 0) return 0;
+  const pct = (spent / budget) * 100;
+  if (pct >= 100) return 100;
+  if (pct >= 90) return 90;
+  if (pct >= 75) return 75;
+  return 0;
+}
+
+// Median response-time bucket as a label, from [<30s, <2m, <10m, <=30m] counts.
+const WAIT_LABELS = ['under 30s', 'under 2m', 'under 10m', 'under 30m'];
+function typicalWait(buckets) {
+  const total = (buckets || []).reduce((a, b) => a + b, 0);
+  if (!total) return null;
+  let cum = 0;
+  for (let i = 0; i < buckets.length; i++) {
+    cum += buckets[i];
+    if (cum * 2 >= total) return WAIT_LABELS[i];
+  }
+  return null;
+}
+
+module.exports = { estimateCost, totalTokens, rateFor, budgetLevel, typicalWait };

package/lib/quota.js

@@ -0,0 +1,43 @@
+'use strict';
+// Usage/quota widget data from ~/.claude/.statusline-usage-cache (KEY=VALUE).
+const fs = require('fs/promises');
+const path = require('path');
+const { CLAUDE_DIR } = require('./paths');
+
+const CACHE_FILE = path.join(CLAUDE_DIR, '.statusline-usage-cache');
+const STALE_MS = 2 * 60 * 60 * 1000; // statusline only updates while Claude runs
+
+async function readQuota() {
+  let raw;
+  try {
+    raw = await fs.readFile(CACHE_FILE, 'utf8');
+  } catch {
+    return null;
+  }
+  const kv = {};
+  for (const line of raw.split('\n')) {
+    const i = line.indexOf('=');
+    if (i > 0) kv[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  const ts = Number(kv.TIMESTAMP) || 0;
+  // TIMESTAMP may be epoch seconds or ms; normalize to ms.
+  const tsMs = ts > 1e12 ? ts : ts * 1000;
+  return {
+    utilization: num(kv.UTILIZATION),
+    weeklyUtilization: num(kv.WEEKLY_UTILIZATION),
+    costUsed: num(kv.COST_USED),
+    costLimit: num(kv.COST_LIMIT),
+    currency: kv.COST_CURRENCY || 'USD',
+    resetsAt: kv.RESETS_AT || null,
+    weeklyResetsAt: kv.WEEKLY_RESETS_AT || null,
+    profileName: kv.PROFILE_NAME || null,
+    stale: !tsMs || Date.now() - tsMs > STALE_MS,
+  };
+}
+
+function num(v) {
+  const n = parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+module.exports = { readQuota };

package/lib/registry.js

@@ -0,0 +1,69 @@
+'use strict';
+// Project registry from ~/.claude.json `projects` map, with worktree-root
+// normalization and case-insensitive dedupe (APFS is case-insensitive; the
+// registry really does contain e.g. both "Projects/" and "projects/" variants).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { canonicalize, worktreeRoot } = require('./paths');
+
+const CLAUDE_JSON = path.join(os.homedir(), '.claude.json');
+
+let cache = { mtimeMs: 0, projects: new Map() };
+
+// Returns Map<lowercasePath, {path, lastSessionId, lastSessionModified,
+//   lastStartTime, lastSessionFirstPrompt, lastCost}>
+function readRegistry() {
+  let st;
+  try {
+    st = fs.statSync(CLAUDE_JSON);
+  } catch {
+    return new Map();
+  }
+  if (st.mtimeMs === cache.mtimeMs) return cache.projects;
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(CLAUDE_JSON, 'utf8'));
+  } catch {
+    return cache.projects; // keep last good copy on parse failure (mid-write)
+  }
+
+  const merged = new Map();
+  for (const [rawPath, info] of Object.entries(data.projects || {})) {
+    const { root } = worktreeRoot(canonicalize(rawPath));
+    const key = root.toLowerCase();
+    const entry = merged.get(key) || { path: root, exists: null };
+    const modified = info.lastSessionModified || info.lastStartTime || 0;
+    const prevModified = entry.lastSessionModified || entry.lastStartTime || 0;
+    // Newest-activity variant wins for both metadata and display casing.
+    if (!merged.has(key) || modified >= prevModified) {
+      entry.path = pickExistingCasing(entry.path, root);
+      if (info.lastSessionId) entry.lastSessionId = info.lastSessionId;
+      if (modified) entry.lastSessionModified = modified;
+      if (info.lastStartTime) entry.lastStartTime = info.lastStartTime;
+      if (info.lastSessionFirstPrompt) entry.lastSessionFirstPrompt = info.lastSessionFirstPrompt;
+      if (typeof info.lastCost === 'number') entry.lastCost = info.lastCost;
+    }
+    merged.set(key, entry);
+  }
+  cache = { mtimeMs: st.mtimeMs, projects: merged };
+  return merged;
+}
+
+function pickExistingCasing(a, b) {
+  if (!a) return b;
+  if (a === b) return a;
+  // Prefer the variant that exists on disk with that exact casing.
+  for (const cand of [b, a]) {
+    try {
+      const real = fs.realpathSync.native(cand);
+      if (path.basename(real) === path.basename(cand)) return cand;
+    } catch {
+      /* missing path, try next */
+    }
+  }
+  return b;
+}
+
+module.exports = { readRegistry };

package/lib/search.js

@@ -0,0 +1,170 @@
+'use strict';
+// Search across every prompt ever sent (history.jsonl) and session titles.
+// Reads history on demand — it's under 1MB and a search is a click.
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { CLAUDE_DIR, worktreeRoot } = require('./paths');
+const { isIgnored } = require('./ignore');
+
+const HISTORY_FILE = path.join(CLAUDE_DIR, 'history.jsonl');
+const MAX_RESULTS = 60;
+
+// 'project:dashboard since:7d fix the build' -> filters plus remaining text.
+// project: substring-matches the canonical project path; since: takes Nd or
+// YYYY-MM-DD (local). Malformed values are dropped rather than erroring.
+function parseSearchQuery(q, now = Date.now()) {
+  let project = null;
+  let since = null;
+  const text = String(q)
+    .replace(/(?:^|\s)project:(\S+)/i, (_, v) => { project = v.toLowerCase(); return ' '; })
+    .replace(/(?:^|\s)since:(\S+)/i, (_, v) => {
+      const rel = /^(\d+)d$/i.exec(v);
+      const abs = /^(\d{4})-(\d{2})-(\d{2})$/.exec(v);
+      if (rel) since = now - Number(rel[1]) * 86400000;
+      else if (abs) since = new Date(Number(abs[1]), Number(abs[2]) - 1, Number(abs[3])).getTime();
+      return ' ';
+    })
+    .replace(/\s+/g, ' ')
+    .trim();
+  return { text, project, since };
+}
+
+function searchHistory(q) {
+  const { text, project, since } = parseSearchQuery(q);
+  const needle = text.toLowerCase();
+  return new Promise((resolve) => {
+    const matches = [];
+    const rl = readline.createInterface({
+      input: fs.createReadStream(HISTORY_FILE, { encoding: 'utf8' }),
+      crlfDelay: Infinity,
+    });
+    rl.on('line', (line) => {
+      if (!line.toLowerCase().includes(needle)) return;
+      try {
+        const rec = JSON.parse(line);
+        if (typeof rec.display !== 'string' || !rec.display.toLowerCase().includes(needle)) return;
+        const { root } = worktreeRoot(rec.project || '');
+        if (isIgnored(root)) return;
+        if (project && !root.toLowerCase().includes(project)) return;
+        if (since && !(rec.timestamp >= since)) return;
+        const i = rec.display.toLowerCase().indexOf(needle);
+        const start = Math.max(0, i - 60);
+        matches.push({
+          snippet: (start > 0 ? '…' : '') + rec.display.slice(start, i + needle.length + 120).replace(/\s+/g, ' '),
+          project: root,
+          timestamp: rec.timestamp || null,
+          sessionId: rec.sessionId || null,
+        });
+      } catch {
+        /* skip */
+      }
+    });
+    const done = () => {
+      matches.reverse(); // newest first
+      resolve(matches.slice(0, MAX_RESULTS));
+    };
+    rl.on('close', done);
+    rl.on('error', done);
+  });
+}
+
+// Title matches come from the collector's in-memory transcript groups.
+function searchTitles(q, transcriptGroups, sessionTitle) {
+  const { text, project, since } = parseSearchQuery(q);
+  const needle = text.toLowerCase();
+  const out = [];
+  for (const g of transcriptGroups.values()) {
+    if (isIgnored(g.path)) continue;
+    if (project && !g.path.toLowerCase().includes(project)) continue;
+    for (const m of g.sessions) {
+      if (since && !(m.lastActivityAt >= since)) continue;
+      const { title } = sessionTitle(m);
+      if (title && title.toLowerCase().includes(needle)) {
+        out.push({ title, project: g.path, sessionId: m.sessionId, lastActivityAt: m.lastActivityAt });
+      }
+    }
+  }
+  out.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  return out.slice(0, MAX_RESULTS);
+}
+
+// One transcript line against a lowercase needle -> {role, text, ts} | null.
+// Only real conversation text counts: tool results and harness noise don't.
+function transcriptLineMatch(line, needle) {
+  if (!line.toLowerCase().includes(needle)) return null;
+  if (line.includes('"tool_use_id"')) return null;
+  let rec;
+  try {
+    rec = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  const m = rec.message;
+  if (!m || (rec.type !== 'user' && rec.type !== 'assistant')) return null;
+  let text = null;
+  const c = m.content;
+  if (typeof c === 'string') text = c;
+  else if (Array.isArray(c)) {
+    const part = c.find((x) => x && x.type === 'text' && x.text && x.text.toLowerCase().includes(needle));
+    text = part && part.text;
+  }
+  if (!text) return null;
+  const t = text.trim();
+  if (t.startsWith('<') || t.startsWith('[SYSTEM') || t.startsWith('Caveat:') || t.startsWith('Base directory')) return null;
+  const i = t.toLowerCase().indexOf(needle);
+  if (i === -1) return null;
+  const start = Math.max(0, i - 60);
+  return {
+    role: rec.type === 'user' ? 'you' : 'claude',
+    text: (start > 0 ? '…' : '') + t.slice(start, i + needle.length + 140).replace(/\s+/g, ' '),
+    ts: rec.timestamp ? Date.parse(rec.timestamp) || null : null,
+  };
+}
+
+// Stream-search full transcripts, newest sessions first. No index, no cache:
+// ~200MB greps in a couple of seconds, and the result reports its coverage.
+const MAX_DEEP_RESULTS = 40;
+const MAX_PER_SESSION = 3;
+
+async function searchTranscripts(q, transcriptGroups) {
+  const { text, project, since } = parseSearchQuery(q);
+  const needle = text.toLowerCase();
+  if (!needle) return { matches: [], scanned: 0, total: 0, complete: true };
+  const sessions = [];
+  for (const g of transcriptGroups.values()) {
+    if (isIgnored(g.path)) continue;
+    if (project && !g.path.toLowerCase().includes(project)) continue;
+    for (const m of g.sessions) {
+      if (since && !(m.lastActivityAt >= since)) continue;
+      sessions.push({ file: m.file, sessionId: m.sessionId, project: g.path, lastActivityAt: m.lastActivityAt });
+    }
+  }
+  sessions.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  const matches = [];
+  let scanned = 0;
+  for (const s of sessions) {
+    if (matches.length >= MAX_DEEP_RESULTS) break;
+    scanned++;
+    await new Promise((resolve) => {
+      let found = 0;
+      const rl = readline.createInterface({
+        input: fs.createReadStream(s.file, { encoding: 'utf8' }),
+        crlfDelay: Infinity,
+      });
+      rl.on('line', (line) => {
+        if (matches.length >= MAX_DEEP_RESULTS || found >= MAX_PER_SESSION) return;
+        const hit = transcriptLineMatch(line, needle);
+        if (hit) {
+          found++;
+          matches.push({ ...hit, sessionId: s.sessionId, project: s.project });
+        }
+      });
+      rl.on('close', resolve);
+      rl.on('error', resolve);
+    });
+  }
+  return { matches, scanned, total: sessions.length, complete: scanned >= sessions.length };
+}
+
+module.exports = { searchHistory, searchTitles, parseSearchQuery, transcriptLineMatch, searchTranscripts };

package/lib/sessions.js

@@ -0,0 +1,61 @@
+'use strict';
+// Live Claude Code sessions from ~/.claude/sessions/<pid>.json.
+const fs = require('fs/promises');
+const path = require('path');
+const { CLAUDE_DIR } = require('./paths');
+
+const SESSIONS_DIR = path.join(CLAUDE_DIR, 'sessions');
+const STALE_MS = 24 * 60 * 60 * 1000; // updatedAt older than this => pid reuse, ignore
+
+async function readLiveSessions() {
+  let files;
+  try {
+    files = await fs.readdir(SESSIONS_DIR);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    try {
+      const raw = JSON.parse(await fs.readFile(path.join(SESSIONS_DIR, f), 'utf8'));
+      const pidFromName = parseInt(f, 10);
+      if (!raw.pid || raw.pid !== pidFromName) continue;
+      if (!isAlive(raw.pid)) continue;
+      const updated = raw.statusUpdatedAt || raw.updatedAt || raw.startedAt || 0;
+      if (Date.now() - updated > STALE_MS) continue;
+      out.push({
+        pid: raw.pid,
+        sessionId: raw.sessionId,
+        cwd: raw.cwd,
+        name: raw.name || null,
+        status: raw.status || 'unknown',
+        waitingFor: raw.waitingFor || null,
+        startedAt: raw.startedAt || null,
+        statusUpdatedAt: raw.statusUpdatedAt || raw.updatedAt || null,
+        kind: raw.kind || null,
+      });
+    } catch {
+      /* unreadable/partial file: skip */
+    }
+  }
+  out.sort((a, b) => rank(a) - rank(b) || (b.startedAt || 0) - (a.startedAt || 0));
+  return out;
+}
+
+function rank(s) {
+  if (s.status === 'waiting') return 0;
+  if (s.status === 'busy') return 1;
+  return 2;
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM'; // exists but not ours
+  }
+}
+
+module.exports = { readLiveSessions };

package/lib/tasks.js

@@ -0,0 +1,54 @@
+'use strict';
+// Todo lists for live sessions: ~/.claude/tasks/<sessionId>/<n>.json
+const fs = require('fs/promises');
+const path = require('path');
+const { CLAUDE_DIR } = require('./paths');
+
+const TASKS_DIR = path.join(CLAUDE_DIR, 'tasks');
+
+// cache: sessionId -> { mtimeMs, result }
+const cache = new Map();
+
+async function readTasks(sessionId) {
+  if (!sessionId) return null;
+  const dir = path.join(TASKS_DIR, sessionId);
+  let st;
+  try {
+    st = await fs.stat(dir);
+  } catch {
+    return null;
+  }
+  const hit = cache.get(sessionId);
+  if (hit && hit.mtimeMs === st.mtimeMs) return hit.result;
+
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return null;
+  }
+  const tasks = [];
+  for (const f of files) {
+    if (!/^\d+\.json$/.test(f)) continue;
+    try {
+      tasks.push(JSON.parse(await fs.readFile(path.join(dir, f), 'utf8')));
+    } catch {
+      /* skip partial writes */
+    }
+  }
+  if (!tasks.length) return null;
+  tasks.sort((a, b) => Number(a.id) - Number(b.id));
+  const current = tasks.find((t) => t.status === 'in_progress') || null;
+  const result = {
+    currentTask: current ? { subject: current.subject, activeForm: current.activeForm || current.subject } : null,
+    tasksSummary: {
+      completed: tasks.filter((t) => t.status === 'completed').length,
+      inProgress: tasks.filter((t) => t.status === 'in_progress').length,
+      pending: tasks.filter((t) => t.status === 'pending').length,
+    },
+  };
+  cache.set(sessionId, { mtimeMs: st.mtimeMs, result });
+  return result;
+}
+
+module.exports = { readTasks };