moflo 4.9.33 → 4.9.34

package/dist/src/cli/commands/doctor-fixes.js

@@ -10,6 +10,7 @@ import { join } from 'path';
 import { output } from '../output.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { repairHookWiring } from '../services/hook-wiring.js';
+import { getDaemonLockHolder } from '../services/daemon-lock.js';
 import { findZombieProcesses } from './doctor-zombies.js';
 import { installClaudeCode, runCommand } from './doctor-checks-runtime.js';
 /** Run a shell command as a fix action. Returns true on exit code 0. */
@@ -181,6 +182,37 @@ export async function autoFixCheck(check) {
         'Gate Health': async () => {
             return fixGateHealthHooks();
         },
+        'Embedding hygiene': async () => {
+            // The session-start launcher already runs the same migration BEFORE
+            // daemon/MCP boot — that's where consumer autoheal happens. Running
+            // it here mid-session is unsafe because any long-lived moflo writer
+            // (daemon, MCP server) holds its own sql.js in-memory snapshot from
+            // before we'd repair, and on its next flush dumps the stale buffer
+            // back to disk, clobbering the repair. Pre-#1046 we shelled out to
+            // `npx moflo embeddings init` here and falsely reported success
+            // when the writeback clobber was about to undo it.
+            // `getDaemonLockHolder` validates both PID liveness AND
+            // that the process is actually a moflo daemon (Windows PID
+            // recycling is real — see daemon-lock.ts:isDaemonProcess).
+            if (getDaemonLockHolder(process.cwd()) !== null) {
+                output.writeln(output.dim('  Embedding hygiene is repaired automatically by the session-start launcher.'));
+                output.writeln(output.dim('  Restart Claude Code (or run `flo daemon stop` first) to apply.'));
+                return false;
+            }
+            // No daemon — safe to run the migration in-process. In-process is
+            // preferred over `runFixCommand` because the migration's TTY/stderr
+            // progress UI is then visible to the user, and any thrown error
+            // surfaces in the autoFixCheck try/catch instead of being swallowed
+            // by a child-process exit code.
+            try {
+                const { runEmbeddingsMigrationIfNeeded } = await import('../services/embeddings-migration.js');
+                return await runEmbeddingsMigrationIfNeeded();
+            }
+            catch (e) {
+                output.writeln(output.warning(`  Embeddings migration failed: ${errorDetail(e)}`));
+                return false;
+            }
+        },
         'Status Line': async () => {
             const settingsPath = join(process.cwd(), '.claude', 'settings.json');
             if (!existsSync(settingsPath))

package/dist/src/cli/services/claude-model-rates.js

@@ -0,0 +1,54 @@
+/**
+ * Per-model USD/1M rates. Lookup goes through {@link rateForModel}, which
+ * normalises the transcript's loose model names ("opus", "claude-opus-4-7",
+ * "haiku-4-5", etc.) onto a canonical key.
+ */
+export const CLAUDE_RATES = {
+    // Opus 4.x family
+    opus: { input: 15, output: 75, cacheCreate: 18.75, cacheRead: 1.5 },
+    // Sonnet 4.x family
+    sonnet: { input: 3, output: 15, cacheCreate: 3.75, cacheRead: 0.3 },
+    // Haiku 4.x family
+    haiku: { input: 0.8, output: 4, cacheCreate: 1, cacheRead: 0.08 },
+    // Unknown — zeroed out so the cost UI shows $0 for unrecognised models
+    // rather than guessing wrong. The model name still surfaces in the
+    // distribution card so the user can see the gap.
+    unknown: { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 },
+};
+/** Canonical model keys, ordered most-expensive → cheapest for stable display. */
+export const CANONICAL_MODELS = ['opus', 'sonnet', 'haiku', 'unknown'];
+/**
+ * Map a transcript model name to a canonical rate key. Recognises:
+ *   - bare family names: "opus", "sonnet", "haiku"
+ *   - dated/dotted variants: "claude-opus-4-7", "claude-3-5-sonnet-20241022"
+ *   - case-insensitive
+ * Anything else falls through to `'unknown'`.
+ */
+export function canonicalModelKey(model) {
+    if (!model || typeof model !== 'string')
+        return 'unknown';
+    const lower = model.toLowerCase();
+    if (lower.includes('opus'))
+        return 'opus';
+    if (lower.includes('sonnet'))
+        return 'sonnet';
+    if (lower.includes('haiku'))
+        return 'haiku';
+    return 'unknown';
+}
+/** Resolve a `ClaudeRate` row for the given (possibly raw) model name. */
+export function rateForModel(model) {
+    return CLAUDE_RATES[canonicalModelKey(model)] ?? CLAUDE_RATES.unknown;
+}
+/**
+ * Compute USD cost for a single usage record.
+ * Rates are per 1M tokens; divide by 1e6 once at the end.
+ */
+export function costFromUsage(rate, usage) {
+    const i = usage.input ?? 0;
+    const o = usage.output ?? 0;
+    const cc = usage.cacheCreate ?? 0;
+    const cr = usage.cacheRead ?? 0;
+    return ((i * rate.input + o * rate.output + cc * rate.cacheCreate + cr * rate.cacheRead) / 1_000_000);
+}
+//# sourceMappingURL=claude-model-rates.js.map

package/dist/src/cli/services/claude-stats.js

@@ -0,0 +1,303 @@
+/**
+ * Claude Stats aggregator — issue #1044.
+ *
+ * Reads `~/.claude/projects/<encoded-cwd>/*.jsonl` line-by-line and produces
+ * the JSON shape consumed by The Luminarium's "Claude Stats" tab. Pure I/O
+ * + reduce; no persistent storage, no network.
+ *
+ * Performance posture:
+ *   - Streaming readline (not `readFileSync().split('\n')`) — transcripts
+ *     can grow to tens of MB and we don't want to balloon dashboard memory.
+ *   - Aggregate counters only — message bodies are dropped after extracting
+ *     `usage`, `model`, `tool_use.name`, `tool_result.is_error`.
+ *   - 30s TTL cache keyed on the most-recent file mtime in the project dir
+ *     so consecutive dashboard polls reuse the prior aggregation when no
+ *     transcript has changed.
+ */
+import { createReadStream } from 'node:fs';
+import { stat, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { canonicalModelKey, costFromUsage, rateForModel } from './claude-model-rates.js';
+// ============================================================================
+// Path resolution
+// ============================================================================
+/**
+ * Encode a CWD the same way Claude Code does for `~/.claude/projects/<dir>`.
+ * Replaces `\`, `/`, and `:` with `-` so `C:\Users\eric\Projects\moflo` →
+ * `C--Users-eric-Projects-moflo`.
+ */
+export function encodeCwdForClaudeProjects(cwd) {
+    return cwd.replace(/[\\/:]/g, '-');
+}
+/** Absolute path to `~/.claude/projects/<encoded-cwd>` for the given CWD. */
+export function claudeProjectDirFor(cwd) {
+    return join(homedir(), '.claude', 'projects', encodeCwdForClaudeProjects(cwd));
+}
+const CACHE_TTL_MS = 30_000;
+let cache = null;
+/** Test-only — drop the in-memory cache so the next call re-aggregates. */
+export function _resetClaudeStatsCache() {
+    cache = null;
+}
+// ============================================================================
+// Aggregation
+// ============================================================================
+const DAY_MS = 86_400_000;
+function emptyWindow() {
+    return { sessions: new Set(), input: 0, output: 0, cacheCreate: 0, cacheRead: 0, costUsd: 0 };
+}
+function freezeWindow(w) {
+    const total = w.input + w.output + w.cacheCreate + w.cacheRead;
+    return {
+        sessions: w.sessions.size,
+        tokens: {
+            input: w.input,
+            output: w.output,
+            cacheCreate: w.cacheCreate,
+            cacheRead: w.cacheRead,
+            total,
+        },
+        costUsd: round4(w.costUsd),
+    };
+}
+function round4(n) {
+    return Math.round(n * 10_000) / 10_000;
+}
+function makeAggregator() {
+    return {
+        today: emptyWindow(),
+        last7d: emptyWindow(),
+        last30d: emptyWindow(),
+        lifetime: emptyWindow(),
+        modelMessages: new Map(),
+        modelTokens: new Map(),
+        toolCounts: new Map(),
+        sessions: new Map(),
+        parseErrors: 0,
+    };
+}
+/** Walk one parsed JSONL line and update the aggregator. */
+function consumeLine(agg, line, now) {
+    const ts = line.timestamp ? Date.parse(line.timestamp) : NaN;
+    const sessionId = line.sessionId;
+    if (sessionId && Number.isFinite(ts)) {
+        const meta = agg.sessions.get(sessionId);
+        if (meta) {
+            if (ts < meta.firstTs)
+                meta.firstTs = ts;
+            if (ts > meta.lastTs)
+                meta.lastTs = ts;
+        }
+        else {
+            agg.sessions.set(sessionId, { firstTs: ts, lastTs: ts, hasError: false });
+        }
+    }
+    // Tool-error detection: tool_result blocks with is_error: true.
+    // These appear on `type:"user"` lines whose message.content is an array
+    // of tool_result blocks. We only check is_error so we don't have to
+    // copy any payloads.
+    const content = line.message?.content;
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const b = block;
+            if (b.type === 'tool_use' && typeof b.name === 'string') {
+                agg.toolCounts.set(b.name, (agg.toolCounts.get(b.name) ?? 0) + 1);
+            }
+            else if (b.type === 'tool_result' && b.is_error === true && sessionId) {
+                const meta = agg.sessions.get(sessionId);
+                if (meta)
+                    meta.hasError = true;
+            }
+        }
+    }
+    // Only assistant lines carry billable usage. Skip everything else.
+    if (line.type !== 'assistant')
+        return;
+    const usage = line.message?.usage;
+    if (!usage)
+        return;
+    const input = usage.input_tokens ?? 0;
+    const output = usage.output_tokens ?? 0;
+    const cc = usage.cache_creation_input_tokens ?? 0;
+    const cr = usage.cache_read_input_tokens ?? 0;
+    const totalThisLine = input + output + cc + cr;
+    const modelKey = canonicalModelKey(line.message?.model);
+    const rate = rateForModel(line.message?.model);
+    const cost = costFromUsage(rate, { input, output, cacheCreate: cc, cacheRead: cr });
+    agg.modelMessages.set(modelKey, (agg.modelMessages.get(modelKey) ?? 0) + 1);
+    agg.modelTokens.set(modelKey, (agg.modelTokens.get(modelKey) ?? 0) + totalThisLine);
+    // Lifetime always.
+    bump(agg.lifetime, sessionId, input, output, cc, cr, cost);
+    // Bucketed windows — only when we have a usable timestamp.
+    if (Number.isFinite(ts)) {
+        const ageMs = now - ts;
+        if (ageMs >= 0 && ageMs < DAY_MS)
+            bump(agg.today, sessionId, input, output, cc, cr, cost);
+        if (ageMs >= 0 && ageMs < 7 * DAY_MS)
+            bump(agg.last7d, sessionId, input, output, cc, cr, cost);
+        if (ageMs >= 0 && ageMs < 30 * DAY_MS)
+            bump(agg.last30d, sessionId, input, output, cc, cr, cost);
+    }
+}
+function bump(w, sessionId, input, output, cc, cr, cost) {
+    if (sessionId)
+        w.sessions.add(sessionId);
+    w.input += input;
+    w.output += output;
+    w.cacheCreate += cc;
+    w.cacheRead += cr;
+    w.costUsd += cost;
+}
+// ============================================================================
+// File walking
+// ============================================================================
+/** List the `.jsonl` files in a project dir, returning [path, mtime, size]. */
+async function listTranscripts(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const candidates = entries.filter(n => n.endsWith('.jsonl'));
+    // Stat in parallel — at ~700 files a serial loop is the dominant cost
+    // before any file content is read.
+    const stats = await Promise.all(candidates.map(async (name) => {
+        const full = join(dir, name);
+        try {
+            const s = await stat(full);
+            return s.isFile() ? { path: full, mtimeMs: s.mtimeMs, size: s.size } : null;
+        }
+        catch {
+            // Skip transient ENOENT (file rotated mid-listing) and perms errors.
+            return null;
+        }
+    }));
+    return stats.filter((s) => s !== null);
+}
+async function streamFile(agg, path, now) {
+    const stream = createReadStream(path, { encoding: 'utf-8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const raw of rl) {
+        if (!raw)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            agg.parseErrors++;
+            continue;
+        }
+        consumeLine(agg, parsed, now);
+    }
+}
+/**
+ * Build the JSON shape returned by `GET /api/claude-stats`.
+ *
+ * Returns an `available: false` shape when the project dir doesn't exist or
+ * holds no transcripts — the dashboard renders a "no sessions found" empty
+ * state from that signal.
+ */
+export async function aggregateClaudeStats(cwd, options = {}) {
+    const startedAt = Date.now();
+    const dir = options.projectDir ?? claudeProjectDirFor(cwd);
+    const now = options.now ?? Date.now();
+    const files = await listTranscripts(dir);
+    if (files.length === 0) {
+        return emptyShape(dir, Date.now() - startedAt);
+    }
+    // Cache key: max(mtime) + sum(size). If neither shifts, the prior
+    // aggregation is still valid. Also folds in the number of files so a
+    // delete invalidates correctly.
+    const maxMtime = files.reduce((m, f) => Math.max(m, f.mtimeMs), 0);
+    const totalSize = files.reduce((s, f) => s + f.size, 0);
+    const cacheKey = `${dir}|${files.length}|${maxMtime}|${totalSize}`;
+    if (!options.skipCache && cache && cache.key === cacheKey && Date.now() - cache.cachedAt < CACHE_TTL_MS) {
+        return cache.value;
+    }
+    const agg = makeAggregator();
+    for (const f of files) {
+        try {
+            await streamFile(agg, f.path, now);
+        }
+        catch (err) {
+            // One bad file shouldn't blank the whole tab.
+            console.warn(`[claude-stats] failed to read ${f.path}: ${err.message ?? err}`);
+        }
+    }
+    const value = freezeAggregator(agg, dir, Date.now() - startedAt);
+    cache = { key: cacheKey, value, cachedAt: Date.now() };
+    return value;
+}
+/** Build the all-zero shape — exported so the dashboard route handler can
+ *  reuse it on its own catch path without re-declaring the structure. */
+export function emptyClaudeStatsShape(dir = null, elapsedMs = 0) {
+    return emptyShape(dir, elapsedMs);
+}
+function emptyShape(dir, elapsedMs) {
+    const empty = freezeWindow(emptyWindow());
+    return {
+        available: false,
+        projectDir: dir,
+        windows: { today: empty, last7d: empty, last30d: empty, lifetime: empty },
+        models: [],
+        tools: [],
+        errorSessions: 0,
+        sessionDurationMs: { median: 0, p95: 0 },
+        totalSessions: 0,
+        parseErrors: 0,
+        elapsedMs,
+    };
+}
+function freezeAggregator(agg, dir, elapsedMs) {
+    const models = [];
+    for (const key of agg.modelMessages.keys()) {
+        models.push({
+            model: key,
+            messages: agg.modelMessages.get(key) ?? 0,
+            tokens: agg.modelTokens.get(key) ?? 0,
+        });
+    }
+    models.sort((a, b) => b.tokens - a.tokens);
+    const tools = Array.from(agg.toolCounts, ([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 10);
+    let errorSessions = 0;
+    const durations = [];
+    for (const meta of agg.sessions.values()) {
+        if (meta.hasError)
+            errorSessions++;
+        const span = meta.lastTs - meta.firstTs;
+        if (span > 0)
+            durations.push(span);
+    }
+    durations.sort((a, b) => a - b);
+    const median = durations.length ? durations[Math.floor(durations.length / 2)] : 0;
+    const p95 = durations.length ? durations[Math.min(durations.length - 1, Math.floor(durations.length * 0.95))] : 0;
+    return {
+        available: true,
+        projectDir: dir,
+        windows: {
+            today: freezeWindow(agg.today),
+            last7d: freezeWindow(agg.last7d),
+            last30d: freezeWindow(agg.last30d),
+            lifetime: freezeWindow(agg.lifetime),
+        },
+        models,
+        tools,
+        errorSessions,
+        sessionDurationMs: { median, p95 },
+        totalSessions: agg.sessions.size,
+        parseErrors: agg.parseErrors,
+        elapsedMs,
+    };
+}
+//# sourceMappingURL=claude-stats.js.map

package/dist/src/cli/services/daemon-dashboard.js

@@ -15,6 +15,7 @@
 import { createServer } from 'node:http';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { handleMemoryStore, handleMemoryDelete, handleMemoryBatch, matchMemoryRpcRoute, } from './daemon-memory-rpc.js';
+import { aggregateClaudeStats, emptyClaudeStatsShape } from './claude-stats.js';
 export const DEFAULT_DASHBOARD_PORT = 3117;
 /**
  * Process-wide promise for the shared MemoryAccessor. Memoized as a *promise*
@@ -253,6 +254,23 @@ async function handleMemoryStats() {
         return { namespaces: {}, totalEntries: 0, available: false };
     }
 }
+/**
+ * Build the `/api/claude-stats` response (#1044).
+ *
+ * Reads `~/.claude/projects/<encoded-cwd>/*.jsonl` for the daemon's CWD
+ * and returns the aggregated shape consumed by the Claude Stats tab.
+ * Failures degrade to an empty shape rather than 500ing — the dashboard
+ * is read-only context, never the user's primary workflow.
+ */
+async function handleClaudeStats() {
+    try {
+        return await aggregateClaudeStats(process.cwd());
+    }
+    catch (err) {
+        console.warn(`[dashboard] claude-stats failed: ${err.message ?? err}`);
+        return emptyClaudeStatsShape();
+    }
+}
 // ============================================================================
 // Flo Run Context — build and store human-readable run metadata
 // ============================================================================
@@ -418,6 +436,9 @@ async function handleRequest(req, res, daemon, opts) {
         else if (url === '/api/memory/stats') {
             sendJson(res, 200, await handleMemoryStats());
         }
+        else if (url === '/api/claude-stats') {
+            sendJson(res, 200, await handleClaudeStats());
+        }
         else {
             sendJson(res, 404, { error: 'Not found' });
         }
@@ -709,14 +730,16 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
   <div id="panel-schedules" class="panel" style="display:none"><div id="schedules-active"></div><div id="schedules-events"></div></div>
   <div id="panel-executions" class="panel" style="display:none"></div>
   <div id="panel-memory" class="panel" style="display:none"></div>
+  <div id="panel-claude-stats" class="panel" style="display:none"></div>
   <div id="poll-indicator" class="poll-indicator"></div>
   <script>
     // Tab navigation — plain DOM, no framework
-    const tabIds = ['workers', 'schedules', 'executions', 'memory'];
-    const tabLabels = ['Workers', 'Schedules', 'Flo Runs', 'Memory'];
+    const tabIds = ['workers', 'schedules', 'executions', 'memory', 'claude-stats'];
+    const tabLabels = ['Workers', 'Schedules', 'Flo Runs', 'Memory', 'Claude Stats'];
     let activeTab = 'workers';
 
     function switchTab(id) {
+      const prev = activeTab;
       activeTab = id;
       tabIds.forEach(t => {
         document.getElementById('panel-' + t).style.display = t === id ? '' : 'none';
@@ -724,6 +747,12 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
       document.querySelectorAll('.nav-tab').forEach(el => {
         el.classList.toggle('active', el.dataset.tab === id);
       });
+      // Tabs whose data is fetched lazily (currently only Claude Stats)
+      // need an immediate poll on entry — otherwise the user waits up to
+      // the 5s polling interval for first paint.
+      if (id === 'claude-stats' && prev !== id && typeof poll === 'function') {
+        poll();
+      }
     }
 
     // Build nav tabs
@@ -1019,20 +1048,132 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
         '<table><thead><tr><th>Namespace</th><th>Entries</th></tr></thead><tbody>' + rows + '</tbody></table>';
     }
 
+    // Format: 1234567 → "1.23M", 5432 → "5.43K"
+    const fmtCount = (n) => {
+      if (n == null) return '-';
+      if (n < 1000) return String(n);
+      if (n < 1_000_000) return (n / 1000).toFixed(2) + 'K';
+      if (n < 1_000_000_000) return (n / 1_000_000).toFixed(2) + 'M';
+      return (n / 1_000_000_000).toFixed(2) + 'B';
+    };
+    // USD with two decimals; sub-cent renders as "<$0.01".
+    const fmtUsd = (n) => {
+      if (n == null) return '-';
+      if (n === 0) return '$0.00';
+      if (n < 0.01) return '<$0.01';
+      return '$' + n.toFixed(2);
+    };
+
+    function renderClaudeStats(cs) {
+      const el = document.getElementById('panel-claude-stats');
+      if (!cs) { el.innerHTML = '<div class="empty">Loading...</div>'; return; }
+
+      // Always-visible disclaimer banner — kept verbatim per the issue's
+      // wording so the user understands the scope and limits at a glance.
+      const disclaimer =
+        '<div style="background:#161b22;border:1px solid #30363d;border-left:3px solid #d29922;border-radius:6px;padding:10px 14px;margin-bottom:16px;color:#c9d1d9;font-size:0.85rem;line-height:1.5">' +
+        '<strong>Local stats only.</strong> Counts what Claude Code wrote to disk for THIS project on THIS machine. ' +
+        'Doesn\\'t include claude.ai web sessions, other projects, other devices, or your account-level plan quota. ' +
+        'Cost is a local estimate using current public model rates.' +
+        '</div>';
+
+      if (!cs.available) {
+        el.innerHTML = disclaimer +
+          '<div class="empty">No Claude Code sessions found in this project' +
+          (cs.projectDir ? ' (looked in <code style="color:#8b949e">' + esc(cs.projectDir) + '</code>)' : '') +
+          '</div>';
+        return;
+      }
+
+      const w = cs.windows;
+
+      // Summary windows (today / 7d / 30d / lifetime).
+      const winRow = (label, win) => {
+        return '<tr><td style="font-weight:600">' + label + '</td>' +
+          '<td>' + fmtCount(win.sessions) + '</td>' +
+          '<td>' + fmtCount(win.tokens.total) + '</td>' +
+          '<td>' + fmtCount(win.tokens.input) + '</td>' +
+          '<td>' + fmtCount(win.tokens.output) + '</td>' +
+          '<td>' + fmtCount(win.tokens.cacheCreate) + '</td>' +
+          '<td>' + fmtCount(win.tokens.cacheRead) + '</td>' +
+          '<td>' + fmtUsd(win.costUsd) + '</td></tr>';
+      };
+      const winTable =
+        '<h2>Sessions, Tokens, Cost</h2>' +
+        '<table><thead><tr>' +
+          '<th>Window</th><th>Sessions</th><th>Total Tokens</th>' +
+          '<th>Input</th><th>Output</th><th>Cache Create</th><th>Cache Read</th><th>Est. Cost</th>' +
+        '</tr></thead><tbody>' +
+        winRow('Today', w.today) +
+        winRow('Last 7 days', w.last7d) +
+        winRow('Last 30 days', w.last30d) +
+        winRow('Lifetime', w.lifetime) +
+        '</tbody></table>';
+
+      // Model distribution.
+      const modelRows = (cs.models && cs.models.length)
+        ? cs.models.map(m => '<tr><td>' + esc(m.model) + '</td>' +
+            '<td>' + fmtCount(m.messages) + '</td>' +
+            '<td>' + fmtCount(m.tokens) + '</td></tr>').join('')
+        : '<tr><td colspan="3" class="empty">No model data</td></tr>';
+      const modelsTable =
+        '<h2>Models Used</h2>' +
+        '<table><thead><tr><th>Model</th><th>Messages</th><th>Total Tokens</th></tr></thead>' +
+        '<tbody>' + modelRows + '</tbody></table>';
+
+      // Top-10 tools.
+      const toolRows = (cs.tools && cs.tools.length)
+        ? cs.tools.map(t => '<tr><td>' + esc(t.name) + '</td><td>' + fmtCount(t.count) + '</td></tr>').join('')
+        : '<tr><td colspan="2" class="empty">No tool calls recorded</td></tr>';
+      const toolsTable =
+        '<h2>Top Tools</h2>' +
+        '<table><thead><tr><th>Tool</th><th>Calls</th></tr></thead>' +
+        '<tbody>' + toolRows + '</tbody></table>';
+
+      // Headline cards.
+      const cards =
+        '<div class="grid">' +
+        '<div class="stat-card"><div class="label">Total Sessions</div><div class="value">' + fmtCount(cs.totalSessions) + '</div></div>' +
+        '<div class="stat-card"><div class="label">Sessions w/ Errors</div><div class="value">' + fmtCount(cs.errorSessions) + '</div></div>' +
+        '<div class="stat-card"><div class="label">Median Duration</div><div class="value">' + fmtDuration(cs.sessionDurationMs.median) + '</div></div>' +
+        '<div class="stat-card"><div class="label">p95 Duration</div><div class="value">' + fmtDuration(cs.sessionDurationMs.p95) + '</div></div>' +
+        '</div>';
+
+      // Footer note linking to the rate-table source comment.
+      const footer =
+        '<div class="dim" style="margin-top:12px">' +
+        'Cost estimate uses rates from <code>src/cli/services/claude-model-rates.ts</code> ' +
+        '(USD/1M tokens, list price). Aggregation took ' + fmtDuration(cs.elapsedMs) +
+        (cs.parseErrors ? ' &middot; ' + cs.parseErrors + ' lines skipped (parse error)' : '') +
+        '</div>';
+
+      el.innerHTML = disclaimer + cards + winTable + modelsTable + toolsTable + footer;
+    }
+
     // Polling
     const poll = async () => {
       try {
-        const [s, sc, w, m] = await Promise.all([
+        // Claude Stats aggregation walks the user's transcript dir — only
+        // pull it when the tab is visible so steady-state polling stays
+        // four lightweight endpoints. Switching to the tab triggers an
+        // immediate poll so the user doesn't wait up to 5s for first paint.
+        const wantClaudeStats = activeTab === 'claude-stats';
+        const fetches = [
           fetch('/api/status').then(r => r.json()),
           fetch('/api/schedules').then(r => r.json()),
           fetch('/api/spells').then(r => r.json()),
           fetch('/api/memory/stats').then(r => r.json()),
-        ]);
+          wantClaudeStats
+            ? fetch('/api/claude-stats').then(r => r.json()).catch(() => null)
+            : Promise.resolve(null),
+        ];
+        const [s, sc, w, m, cs] = await Promise.all(fetches);
         renderStatus(s);
         renderWorkers(s);
         renderSchedules(sc);
         renderExecutions(w);
         renderMemory(m);
+        if (wantClaudeStats) renderClaudeStats(cs);
         document.getElementById('poll-indicator').textContent = 'Last poll: ' + new Date().toLocaleTimeString();
       } catch (e) {
         console.error('Poll failed:', e);

package/dist/src/cli/spells/core/auth-error-classifier.js

@@ -0,0 +1,92 @@
+/**
+ * Auth-Error Classifier
+ *
+ * Pattern-matches step-failure text against known upstream auth-shaped
+ * signals (HTTP 401, OAuth `invalid_grant`, MS Graph `IDX1410x`, etc.).
+ * The runner uses the result to offer in-product credential clearing +
+ * re-prompt + single-retry instead of looping forever on a stale token.
+ *
+ * Design: pure function, no I/O, no `/g` flag (statefulness was banned in
+ * `feedback_publish_catches_straggler_bugs.md`). Adding upstream-specific
+ * signals is a one-line addition to {@link AUTH_ERROR_PATTERNS}.
+ *
+ * Story #1042.
+ */
+/**
+ * Initial pattern table from issue #1042. Order matters — high-confidence
+ * upstream-specific patterns come before generic literals so the most
+ * actionable `reason` is reported when a message matches several rules.
+ */
+export const AUTH_ERROR_PATTERNS = [
+    {
+        name: 'msal-idx141',
+        pattern: /\bIDX1410[0-9]\b/,
+        confidence: 'high',
+        reason: 'Microsoft Identity token rejection (IDX1410x)',
+    },
+    {
+        name: 'invalid-auth-token',
+        pattern: /InvalidAuthenticationToken/i,
+        confidence: 'high',
+        reason: 'Microsoft Graph InvalidAuthenticationToken',
+    },
+    {
+        name: 'github-bad-creds',
+        pattern: /\bBad\s+credentials\b/i,
+        confidence: 'high',
+        reason: 'GitHub Bad credentials',
+    },
+    {
+        name: 'oauth-invalid-grant',
+        pattern: /\binvalid_grant\b/i,
+        confidence: 'high',
+        reason: 'OAuth2 invalid_grant',
+    },
+    {
+        name: 'oauth-expired-token',
+        pattern: /\bexpired[_\s-]token\b/i,
+        confidence: 'high',
+        reason: 'OAuth2 expired_token',
+    },
+    {
+        name: 'token-expired-camel',
+        pattern: /\bTokenExpired\b/,
+        confidence: 'high',
+        reason: 'TokenExpired',
+    },
+    {
+        name: 'http-401',
+        pattern: /(?:^|[^0-9])401(?:[^0-9]|$)/,
+        confidence: 'high',
+        reason: 'HTTP 401 (unauthorized)',
+    },
+    {
+        name: 'http-403',
+        pattern: /(?:^|[^0-9])403(?:[^0-9]|$)/,
+        confidence: 'low',
+        reason: 'HTTP 403 (forbidden)',
+    },
+    {
+        name: 'unauthorized-word',
+        pattern: /\bUnauthorized\b/,
+        confidence: 'low',
+        reason: 'unauthorized literal',
+    },
+];
+/**
+ * Match `text` against the pattern table. Returns the first matching
+ * pattern (highest-priority hit) or null.
+ *
+ * `text` is treated as the entire stderr/error blob from a failed step;
+ * patterns are non-anchored on purpose so they catch multi-line outputs.
+ */
+export function classifyAuthError(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return null;
+    for (const pattern of AUTH_ERROR_PATTERNS) {
+        if (pattern.pattern.test(text))
+            return { pattern };
+    }
+    return null;
+}
+//# sourceMappingURL=auth-error-classifier.js.map

package/dist/src/cli/spells/core/runner.js

@@ -9,6 +9,9 @@ import { rollbackSteps } from './rollback-orchestrator.js';
 import { buildCredentialPatterns, addCredentialPattern, collectCredentialNames } from './credential-masker.js';
 import { executeSingleStep } from './step-executor.js';
 import { collectPrerequisites, resolveUnmetPrerequisites } from './prerequisite-checker.js';
+import { classifyAuthError } from './auth-error-classifier.js';
+import { readLineFromStdin } from './stdin-reader.js';
+import { acquireTTYLock } from './tty-lock.js';
 import { collectPreflights, checkPreflights, formatPreflightErrors, partitionPreflightResults, runResolutionCommand, } from './preflight-checker.js';
 import { DENY_ALL_GATEWAY } from './capability-gateway.js';
 import { resolveEffectiveSandbox, formatSandboxLog, DEFAULT_SANDBOX_CONFIG, } from './platform-sandbox.js';
@@ -229,6 +232,18 @@ export class SpellCaster {
                 let result = await this.runStep(step, state, i);
                 const resultIdx = stepResults.length;
                 stepResults.push(result);
+                // Auth-error recovery (issue #1042): if a step fails with an upstream
+                // auth-shaped signal AND the spell declares credential prereqs, offer
+                // (TTY) or surface (non-TTY) the chance to clear + re-prompt + retry
+                // once. The recovery returns a new result (success or marked failure)
+                // that replaces the original; null means no recovery happened.
+                if (result.status === 'failed') {
+                    const recovered = await this.tryAuthErrorRecovery(definition, step, state, i, result);
+                    if (recovered) {
+                        result = recovered;
+                        stepResults[resultIdx] = result;
+                    }
+                }
                 if (result.status === 'succeeded' && result.output) {
                     if (step.output)
                         variables[step.output] = result.output.data;
@@ -395,6 +410,179 @@ export class SpellCaster {
         const ctxBuilder = (v, a, sid, si, sig) => this.buildContext(v, a, sid, si, sig, state.effectiveSandbox);
         return executeSingleStep(step, state, index, this.registry, ctxBuilder);
     }
+    /**
+     * Issue #1042 — react to upstream auth-shaped errors at step-failure time.
+     *
+     * The runner already validates credentials at preflight (#1007/#1009), but
+     * preflight can't know whether a value the upstream accepts today still
+     * works tomorrow. When a step fails with output that matches the auth
+     * pattern table AND the spell has env-typed credential prereqs, we offer
+     * (TTY) or surface (non-TTY) clearing + re-prompt + a single retry.
+     *
+     * Returns a replacement {@link StepResult} when recovery ran (success on
+     * retry, or a `CREDENTIAL_LIKELY_STALE`-coded failure when non-TTY or when
+     * the retry hits the same auth-shape — second-failure short-circuit). Null
+     * means recovery did not run; the caller should fall through to the
+     * normal failure path with the original result intact.
+     */
+    async tryAuthErrorRecovery(definition, step, state, stepIndex, result) {
+        const errorText = this.collectStepErrorText(result);
+        const match = classifyAuthError(errorText);
+        if (!match)
+            return null;
+        const credPrereqs = collectPrerequisites(definition, this.registry)
+            .filter((p) => typeof p.envKey === 'string' && p.envKey.length > 0);
+        if (credPrereqs.length === 0)
+            return null;
+        const credKeys = credPrereqs.map(p => p.envKey);
+        // Low-confidence patterns (HTTP 403, bare "Unauthorized") are too noisy
+        // to drive destructive credential clearing — a 403 typically means
+        // "wrong scope" not "expired token", and "Unauthorized" appears in many
+        // unrelated 4xx responses. Surface a hint and fall through to the
+        // normal failure path so the user sees the real error.
+        if (match.pattern.confidence === 'low') {
+            console.log(`[spell] Step "${step.id}" failed with a possible auth signal (${match.pattern.reason}).`);
+            console.log(`[spell] If "${credKeys.join(', ')}" is stale, run \`flo spell credentials unset ${credKeys[0]}\` and re-cast.`);
+            return null;
+        }
+        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        const externalConfirm = state.options.authErrorConfirm;
+        if (!interactive && !externalConfirm) {
+            // Non-TTY (cron, headless, daemon spawn) with no host-supplied prompt
+            // hook: surface a dedicated error code so schedulers can route this
+            // to "stale credential, needs human" instead of generic step failure.
+            return this.markCredentialLikelyStale(result, match, credKeys, /* afterReprompt */ false);
+        }
+        // TTY path (or test/host-injected confirm). With a single credential
+        // the default is Y (per #1042 issue body); with multiple credentials we
+        // flip the default to N so a single typo doesn't trash a working
+        // credential alongside a stale one. The injected hook fully replaces
+        // both detection and the readline call.
+        const defaultYes = credKeys.length === 1;
+        let confirmed;
+        if (externalConfirm) {
+            try {
+                confirmed = await externalConfirm({
+                    stepId: step.id,
+                    pattern: match.pattern.name,
+                    reason: match.pattern.reason,
+                    credKeys,
+                });
+            }
+            catch {
+                return null;
+            }
+        }
+        else {
+            const lock = acquireTTYLock();
+            try {
+                console.log('');
+                console.log(`[spell] Step "${step.id}" failed with what looks like a credential error.`);
+                console.log(`[spell] Detected: ${match.pattern.reason}`);
+                console.log(`[spell] Stored credential${credKeys.length === 1 ? '' : 's'}: ${credKeys.join(', ')}`);
+                if (!defaultYes) {
+                    console.log(`[spell] Multiple credentials in scope — only confirm if you want ALL of them re-prompted.`);
+                }
+                const noun = credKeys.length === 1 ? 'this credential' : 'these credentials';
+                const promptSuffix = defaultYes ? '[Y/n]' : '[y/N]';
+                const prompt = `Clear ${noun} and re-prompt? ${promptSuffix} `;
+                let answer = '';
+                try {
+                    answer = await readLineFromStdin(prompt, state.options.signal);
+                }
+                catch {
+                    // Abort or stdin closed → carry forward the original failure.
+                    return null;
+                }
+                const trimmed = answer.trim().toLowerCase();
+                const isYes = trimmed === 'y' || trimmed === 'yes';
+                confirmed = isYes || (defaultYes && trimmed === '');
+            }
+            finally {
+                lock.release();
+            }
+        }
+        if (!confirmed)
+            return null;
+        // Clear store + process.env so the resolver re-prompts. `delete` is
+        // optional on the accessor — read-only fixtures may omit it.
+        for (const key of credKeys) {
+            if (typeof this.credentials.delete === 'function') {
+                try {
+                    await this.credentials.delete(key);
+                }
+                catch { /* surface as re-prompt fallthrough */ }
+            }
+            delete process.env[key];
+        }
+        // Don't force re-prompt here — we just deleted the value from the store
+        // and process.env, so the standard resolution chain naturally falls
+        // through to the TTY prompt (or, in test mode, lets the host inject a
+        // replacement via the credentials accessor's get() method).
+        const resolution = await resolveUnmetPrerequisites(credPrereqs, {
+            abortSignal: state.options.signal,
+            credentials: this.credentials,
+        });
+        if (!resolution.ok) {
+            return this.markCredentialLikelyStale(result, match, credKeys, /* afterReprompt */ true);
+        }
+        // Refresh resolvedCredentials + credential masking patterns so the retry
+        // sees the new value the same way the first attempt did.
+        for (const key of credKeys) {
+            try {
+                const fresh = await this.credentials.get(key);
+                if (fresh !== undefined) {
+                    state.resolvedCredentials[key] = fresh;
+                    addCredentialPattern(state.credentialPatterns, fresh);
+                }
+            }
+            catch { /* keep going — the env var is set, that's the load-bearing path */ }
+        }
+        console.log(`[spell] Retrying "${step.id}" with refreshed credentials...`);
+        const retried = await this.runStep(step, state, stepIndex);
+        if (retried.status === 'failed') {
+            const retryErrorText = this.collectStepErrorText(retried);
+            if (classifyAuthError(retryErrorText)) {
+                // Second auth-shape failure — short-circuit so we don't loop.
+                return this.markCredentialLikelyStale(retried, match, credKeys, /* afterReprompt */ true);
+            }
+        }
+        return retried;
+    }
+    collectStepErrorText(result) {
+        const parts = [];
+        if (result.error)
+            parts.push(result.error);
+        const out = result.output;
+        if (out && typeof out === 'object') {
+            if (typeof out.error === 'string')
+                parts.push(out.error);
+            // Step outputs frequently embed the upstream payload under data.{stderr,error,message}.
+            const data = out.data;
+            if (data && typeof data === 'object') {
+                for (const key of ['stderr', 'error', 'message', 'body']) {
+                    const v = data[key];
+                    if (typeof v === 'string')
+                        parts.push(v);
+                }
+            }
+        }
+        return parts.join('\n');
+    }
+    markCredentialLikelyStale(result, match, credKeys, afterReprompt) {
+        const keyLabel = credKeys.join(', ');
+        const suffix = afterReprompt
+            ? ` Re-prompt accepted but the upstream still rejected the credential — manual intervention required.`
+            : ` Run \`flo spell credentials unset ${credKeys[0]}\` (or any key above) and re-cast on a TTY.`;
+        const prefix = `CREDENTIAL_LIKELY_STALE [${match.pattern.name}: ${match.pattern.reason}] for ${keyLabel}.`;
+        const original = result.error ? ` Underlying error: ${result.error}` : '';
+        return {
+            ...result,
+            status: 'failed',
+            errorCode: 'CREDENTIAL_LIKELY_STALE',
+            error: `${prefix}${suffix}${original}`,
+        };
+    }
     async doRollback(completed, state, results) {
         await rollbackSteps(completed, this.registry, (i) => this.buildContext(state.variables, state.resolvedArgs, state.spellId, i, state.options.signal, state.effectiveSandbox), results);
     }

package/dist/src/cli/spells/credentials/default-store.js

@@ -122,5 +122,6 @@ export const lockedNoopAccessor = {
     async get() { return undefined; },
     async has() { return false; },
     async store() { },
+    async delete() { return false; },
 };
 //# sourceMappingURL=default-store.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.33';
+export const VERSION = '4.9.34';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.33",
+  "version": "4.9.34",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -97,7 +97,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.32",
+    "moflo": "^4.9.33",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"