swarmdo 1.29.0 → 1.30.0

package/.claude/helpers/auto-memory-hook.mjs

@@ -13,7 +13,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -52,13 +52,30 @@ async function gracefulExit(signal) {
 process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });
 process.on('SIGINT', () => { gracefulExit('SIGINT'); });
 
-// Ensure data dir
-if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
-
 // ============================================================================
 // Simple JSON File Backend (implements IMemoryBackend interface)
 // ============================================================================
 
+// Collapse entries that are the SAME memory — identical content signature but
+// distinct ids — keeping the first occurrence. The auto-memory bridge
+// historically re-imported every session with a fresh random id, bloating the
+// store ~22x (#53); this heals already-bloated stores and de-dupes defensively.
+// Keyed by namespace + content hash (or raw content) so genuinely distinct
+// memories are never merged. Pure.
+function dedupeByContentSignature(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of entries) {
+    const ns = (e && e.namespace) || 'default';
+    const body = (e && e.metadata && e.metadata.contentHash) || (e && (e.content || e.value)) || '';
+    const sig = ns + '\u0001' + body;
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    out.push(e);
+  }
+  return out;
+}
+
 class JsonFileBackend {
   constructor(filePath) {
     this.filePath = filePath;
@@ -70,7 +87,12 @@ class JsonFileBackend {
       try {
         const data = JSON.parse(readFileSync(this.filePath, 'utf-8'));
         if (Array.isArray(data)) {
-          for (const entry of data) this.entries.set(entry.id, entry);
+          // Collapse content-duplicates left by the pre-#53 import bug (same
+          // memory re-imported each session under a fresh id). Auto-heals an
+          // already-bloated store by rewriting it once when dupes are dropped.
+          const deduped = dedupeByContentSignature(data);
+          for (const entry of deduped) this.entries.set(entry.id, entry);
+          if (deduped.length < data.length) this._persist();
         }
       } catch { /* start fresh */ }
     }
@@ -617,33 +639,44 @@ async function doImportAll() {
 // Main
 // ============================================================================
 
-const command = process.argv[2] || 'status';
-
-// Dynamic import() failures can surface as unhandled rejections on a later
-// microtask even when the awaiting call site already caught them, which would
-// otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
-// reason under SWARMDO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
-// (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
-process.on('unhandledRejection', (reason) => {
-  if (DEBUG) {
-    const detail = reason && reason.message ? reason.message : String(reason);
-    process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
-  }
-});
-
-try {
-  switch (command) {
-    case 'import': await doImport(); break;
-    case 'import-all': await doImportAll(); break;
-    case 'sync': await doSync(); break;
-    case 'status': await doStatus(); break;
-    default:
-      console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
-      process.exit(1);
+// Only dispatch CLI commands when this file is executed directly
+// (`node auto-memory-hook.mjs …`), NOT when it is imported by a test —
+// importing must not run a command or exit the process (#53 regression test
+// imports JsonFileBackend + dedupeByContentSignature below).
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  // Ensure data dir (only when actually running a command, not on import)
+  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+  const command = process.argv[2] || 'status';
+
+  // Dynamic import() failures can surface as unhandled rejections on a later
+  // microtask even when the awaiting call site already caught them, which would
+  // otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
+  // reason under SWARMDO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
+  // (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
+  process.on('unhandledRejection', (reason) => {
+    if (DEBUG) {
+      const detail = reason && reason.message ? reason.message : String(reason);
+      process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
+    }
+  });
+
+  try {
+    switch (command) {
+      case 'import': await doImport(); break;
+      case 'import-all': await doImportAll(); break;
+      case 'sync': await doSync(); break;
+      case 'status': await doStatus(); break;
+      default:
+        console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
+        process.exit(1);
+    }
+  } catch (err) {
+    // Hooks must never crash Claude Code - fail silently
+    dim(`Error (non-critical): ${err.message}`);
   }
-} catch (err) {
-  // Hooks must never crash Claude Code - fail silently
-  dim(`Error (non-critical): ${err.message}`);
+  // Ensure clean exit for Claude Code hooks (exit 0 = success, no stderr = no error)
+  process.exit(0);
 }
-// Ensure clean exit for Claude Code hooks (exit 0 = success, no stderr = no error)
-process.exit(0);
+
+// Exported for unit tests (the run-guard above keeps import side-effect-free).
+export { JsonFileBackend, dedupeByContentSignature };

package/README.md

@@ -2,7 +2,7 @@
 
 [![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.29.0-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
+[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.30.0-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/SwarmDo/swarmdo/blob/main/LICENSE)
 [![Website](https://img.shields.io/badge/swarmdo.com-e2a33c?style=for-the-badge&logoColor=black)](https://swarmdo.com)
 [![Star on GitHub](https://img.shields.io/github/stars/SwarmDo/swarmdo?style=for-the-badge&logo=github&color=gold)](https://github.com/SwarmDo/swarmdo)
@@ -271,7 +271,7 @@ The recent release train added a full day-to-day operations layer around the swa
 
 | Command | What it does |
 |---------|-------------|
-| `swarmdo usage` (alias `cost`) | Claude Code **spend analytics** from your local transcripts — `daily`, `monthly`, `models`, `projects`, `sessions`, live 5-hour `blocks` burn, `errors` (tool-failure analytics), `cache` (prompt-cache efficiency + $ saved), and `diff` (period-over-period comparison with per-model movers) |
+| `swarmdo usage` (alias `cost`) | Claude Code **spend analytics** from your local transcripts — `daily`, `monthly` (with a month-end spend projection), `models`, `projects`, `sessions`, live 5-hour `blocks` burn, `errors` (tool-failure analytics), `cache` (prompt-cache efficiency + $ saved), `diff` (period-over-period comparison with per-model movers), `reflect` (a wrapped-style retrospective — busiest day, streak, top models/projects, peak hour, delegation ratio — with a shareable `--html` dashboard), and `limits` (an official-quota **exhaustion forecaster** over Claude Code's `rate_limits`); the standard views take `--csv` for spreadsheet export |
 | `swarmdo usage guard` | **Budget policy** — limits for the active 5h block / today / month via flags or `SWARMDO_GUARD_*` env → ok / warn / over; `--strict` exits 1, safe for CI gates and Stop hooks |
 | `swarmdo hud` | **One-screen ops HUD** — 5h block burn, task readiness, daemon workers, memory snapshots (`--watch`, `--json`) |
 | `swarmdo repair` (alias `tdd-repair`) | **Test-Driven Repair** — a bounded, budget-capped headless `claude` loop that fixes source until a failing test passes; dry-run unless `--confirm` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Swarmdo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@swarmdo/cli/.claude/helpers/auto-memory-hook.mjs

@@ -13,7 +13,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -52,13 +52,30 @@ async function gracefulExit(signal) {
 process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });
 process.on('SIGINT', () => { gracefulExit('SIGINT'); });
 
-// Ensure data dir
-if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
-
 // ============================================================================
 // Simple JSON File Backend (implements IMemoryBackend interface)
 // ============================================================================
 
+// Collapse entries that are the SAME memory — identical content signature but
+// distinct ids — keeping the first occurrence. The auto-memory bridge
+// historically re-imported every session with a fresh random id, bloating the
+// store ~22x (#53); this heals already-bloated stores and de-dupes defensively.
+// Keyed by namespace + content hash (or raw content) so genuinely distinct
+// memories are never merged. Pure.
+function dedupeByContentSignature(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of entries) {
+    const ns = (e && e.namespace) || 'default';
+    const body = (e && e.metadata && e.metadata.contentHash) || (e && (e.content || e.value)) || '';
+    const sig = ns + '\u0001' + body;
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    out.push(e);
+  }
+  return out;
+}
+
 class JsonFileBackend {
   constructor(filePath) {
     this.filePath = filePath;
@@ -70,7 +87,12 @@ class JsonFileBackend {
       try {
         const data = JSON.parse(readFileSync(this.filePath, 'utf-8'));
         if (Array.isArray(data)) {
-          for (const entry of data) this.entries.set(entry.id, entry);
+          // Collapse content-duplicates left by the pre-#53 import bug (same
+          // memory re-imported each session under a fresh id). Auto-heals an
+          // already-bloated store by rewriting it once when dupes are dropped.
+          const deduped = dedupeByContentSignature(data);
+          for (const entry of deduped) this.entries.set(entry.id, entry);
+          if (deduped.length < data.length) this._persist();
         }
       } catch { /* start fresh */ }
     }
@@ -371,32 +393,43 @@ async function doStatus() {
 // Main
 // ============================================================================
 
-const command = process.argv[2] || 'status';
-
-// Dynamic import() failures can surface as unhandled rejections on a later
-// microtask even when the awaiting call site already caught them, which would
-// otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
-// reason under SWARMDO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
-// (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
-process.on('unhandledRejection', (reason) => {
-  if (DEBUG) {
-    const detail = reason && reason.message ? reason.message : String(reason);
-    process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
-  }
-});
-
-try {
-  switch (command) {
-    case 'import': await doImport(); break;
-    case 'sync': await doSync(); break;
-    case 'status': await doStatus(); break;
-    default:
-      console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
-      break;
+// Only dispatch CLI commands when this file is executed directly
+// (`node auto-memory-hook.mjs …`), NOT when it is imported by a test —
+// importing must not run a command or exit the process (#53 regression test
+// imports JsonFileBackend + dedupeByContentSignature below).
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  // Ensure data dir (only when actually running a command, not on import)
+  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+  const command = process.argv[2] || 'status';
+
+  // Dynamic import() failures can surface as unhandled rejections on a later
+  // microtask even when the awaiting call site already caught them, which would
+  // otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
+  // reason under SWARMDO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
+  // (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
+  process.on('unhandledRejection', (reason) => {
+    if (DEBUG) {
+      const detail = reason && reason.message ? reason.message : String(reason);
+      process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
+    }
+  });
+
+  try {
+    switch (command) {
+      case 'import': await doImport(); break;
+      case 'sync': await doSync(); break;
+      case 'status': await doStatus(); break;
+      default:
+        console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
+        break;
+    }
+  } catch (err) {
+    // Hooks must never crash Claude Code - fail silently
+    try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
   }
-} catch (err) {
-  // Hooks must never crash Claude Code - fail silently
-  try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
+  // Force clean exit — process.exitCode alone isn't enough if async errors override it
+  process.exit(0);
 }
-// Force clean exit — process.exitCode alone isn't enough if async errors override it
-process.exit(0);
+
+// Exported for unit tests (the run-guard above keeps import side-effect-free).
+export { JsonFileBackend, dedupeByContentSignature };

package/v3/@swarmdo/cli/dist/src/commands/usage.js

@@ -14,10 +14,16 @@
  */
 import { output } from '../output.js';
 import { aggregateBlocks, aggregateUsage, collectUsage, totalUsage, localDateKey, } from '../usage/transcript-usage.js';
-import { collectToolErrors } from '../usage/transcript-errors.js';
+import { collectToolErrors, delegationFromReport } from '../usage/transcript-errors.js';
 import { computeCacheStats } from '../usage/cache-stats.js';
 import { evaluateGuard } from '../usage/spend-guard.js';
 import { resolvePeriodPair, parseRange, diffPeriods, modelMovers } from '../usage/diff.js';
+import { computeReflection, monthsBefore, hourSparkline } from '../usage/reflect.js';
+import { renderReflectionHtml } from '../usage/reflect-html.js';
+import { forecastWindow, parseRateLimits, worstStatus, formatForecast, formatLimitSegment } from '../usage/limits.js';
+import { readFileSync } from 'node:fs';
+import { toCsv } from '../util/csv.js';
+import { projectMonthEnd, daysInMonthOf } from '../usage/spend-forecast.js';
 const VIEWS = {
     daily: { dimension: 'day', label: 'Date' },
     monthly: { dimension: 'month', label: 'Month' },
@@ -376,6 +382,143 @@ function runGuardView(ctx, collection) {
         output.writeln(output.dim('exit 1 (--strict + over budget)'));
     return { success: exitCode === 0, exitCode };
 }
+const PERIOD_MONTHS = { '1m': 1, '3m': 3, '6m': 6, '12m': 12 };
+/** `usage reflect` — a wrapped-style retrospective over the local transcripts (#47). */
+function runReflectView(ctx, collection) {
+    const periodFlag = (typeof ctx.flags.period === 'string' ? ctx.flags.period : '3m').toLowerCase();
+    const months = PERIOD_MONTHS[periodFlag];
+    if (!months) {
+        output.printError(`unknown --period "${periodFlag}" (expected ${Object.keys(PERIOD_MONTHS).join('|')})`);
+        return { success: false, exitCode: 1 };
+    }
+    const to = localDateKey(new Date());
+    const from = monthsBefore(to, months);
+    const dayRows = aggregateUsage(collection.events, 'day').map((r) => ({ key: r.key, totals: r.totals }));
+    const md = new Map();
+    const pd = new Map(); // per-(project, day) for top projects
+    const hourHistogram = new Array(24).fill(0); // local-hour cost, windowed to [from,to]
+    for (const e of collection.events) {
+        const k = `${e.model}\u0000${e.dateKey}`;
+        const row = md.get(k) ?? { key: e.model, day: e.dateKey, totals: { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0 } };
+        row.totals.costUsd += e.costUsd;
+        row.totals.totalTokens += e.inputTokens + e.outputTokens + e.cacheWriteTokens + e.cacheReadTokens;
+        md.set(k, row);
+        // per-(project, day) fold (space separator is safe — dateKey is fixed-width)
+        const pk = `${e.project} ${e.dateKey}`;
+        const prow = pd.get(pk) ?? { key: e.project, day: e.dateKey, totals: { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0 } };
+        prow.totals.costUsd += e.costUsd;
+        prow.totals.totalTokens += e.inputTokens + e.outputTokens + e.cacheWriteTokens + e.cacheReadTokens;
+        pd.set(pk, prow);
+        if (e.dateKey >= from && e.dateKey <= to)
+            hourHistogram[new Date(e.timestampMs).getHours()] += e.costUsd;
+    }
+    const reflection = computeReflection(dayRows, [...md.values()], from, to, {}, [...pd.values()], hourHistogram);
+    // Delegation ratio (#47): reuse the (windowed) tool-error scan to count Task
+    // (subagent) calls vs all tool calls — the parsing is already tested there.
+    const delDirFlag = ctx.flags.dir;
+    const delDirs = typeof delDirFlag === 'string' ? [delDirFlag] : Array.isArray(delDirFlag) ? delDirFlag.map(String) : undefined;
+    const delegation = delegationFromReport(collectToolErrors({ dirs: delDirs, since: from, until: to }));
+    if (ctx.flags.json === true) {
+        output.printJson({ ...reflection, delegation });
+        return { success: true, data: reflection };
+    }
+    if (ctx.flags.html === true) {
+        output.writeln(renderReflectionHtml(reflection, { generatedAt: to, delegation }));
+        return { success: true, exitCode: 0 };
+    }
+    const r = reflection;
+    const pctStr = (x) => `${Math.round(x * 100)}%`;
+    const arrow = r.trend.direction === 'up' ? '↑' : r.trend.direction === 'down' ? '↓' : '→';
+    output.writeln(output.bold(`Usage reflect  ${r.period.from}..${r.period.to}`) + output.dim(`  (${periodFlag}, ${r.period.spanDays} days)`));
+    if (r.totals.activeDays === 0) {
+        output.writeln(output.info('no Claude Code activity in this window'));
+        return { success: true, exitCode: 0 };
+    }
+    output.writeln('');
+    output.writeln(`  Total spend        ${output.bold(fmtCost(r.totals.costUsd))}  ${output.dim(`across ${r.totals.activeDays} active day${r.totals.activeDays === 1 ? '' : 's'} of ${r.period.spanDays}`)}`);
+    output.writeln(`  Total tokens       ${r.totals.totalTokens.toLocaleString()}`);
+    if (r.busiestDay)
+        output.writeln(`  Busiest day        ${r.busiestDay.day}  ${output.dim(`(${fmtCost(r.busiestDay.costUsd)}, ${r.busiestDay.totalTokens.toLocaleString()} tok)`)}`);
+    output.writeln(`  Longest streak     ${r.longestStreak} day${r.longestStreak === 1 ? '' : 's'}`);
+    output.writeln(`  Avg / active day   ${fmtCost(r.avgCostPerActiveDay)}`);
+    output.writeln(`  Cache read share   ${pctStr(r.cacheReadPct)}`);
+    if (delegation.toolCalls > 0) {
+        output.writeln(`  Delegation         ${pctStr(delegation.ratio)}  ${output.dim(`(${delegation.taskCalls} of ${delegation.toolCalls} tool calls to subagents)`)}`);
+    }
+    output.writeln(`  Cost trend         ${arrow} ${fmtCost(r.trend.firstHalfCost)} → ${fmtCost(r.trend.secondHalfCost)} ${output.dim(`(${r.trend.direction})`)}`);
+    if (r.peakHour)
+        output.writeln(`  Peak hour          ${String(r.peakHour.hour).padStart(2, '0')}:00  ${output.dim(`(${fmtCost(r.peakHour.value)})`)}`);
+    if (r.hourHistogram.some((v) => v > 0)) {
+        output.writeln(`  By hour            ${hourSparkline(r.hourHistogram)}  ${output.dim('0…23')}`);
+    }
+    if (r.topModels.length) {
+        output.writeln('');
+        output.writeln(output.bold('  Top models'));
+        r.topModels.forEach((m, i) => {
+            output.writeln(`    ${i + 1}. ${m.model.padEnd(22)} ${fmtCost(m.costUsd).padStart(9)}  ${output.dim(pctStr(m.pct))}`);
+        });
+    }
+    if (r.topProjects.length) {
+        output.writeln('');
+        output.writeln(output.bold('  Top projects'));
+        r.topProjects.forEach((p, i) => {
+            const name = p.model.length > 34 ? '…' + p.model.slice(-33) : p.model;
+            output.writeln(`    ${i + 1}. ${name.padEnd(34)} ${fmtCost(p.costUsd).padStart(9)}  ${output.dim(pctStr(p.pct))}`);
+        });
+    }
+    return { success: true, exitCode: 0 };
+}
+/** `usage limits` — forecast the official 5h/7d quota windows from the
+ * statusline rate_limits payload (stdin or --payload). #46. */
+function runLimitsView(ctx) {
+    const nowMs = Date.now();
+    let raw = typeof ctx.flags.payload === 'string' ? ctx.flags.payload : '';
+    if (!raw && !process.stdin.isTTY) {
+        try {
+            raw = readFileSync(0, 'utf8');
+        }
+        catch { /* no piped input */ }
+    }
+    if (!raw.trim()) {
+        output.writeln(output.info("no rate_limits payload — pipe Claude Code's statusline JSON in, or pass --payload '<json>'"));
+        output.writeln(output.dim('  e.g. in a statusline command:  … | swarmdo usage limits'));
+        return { success: true, exitCode: 0 };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        output.printError('payload is not valid JSON');
+        return { success: false, exitCode: 1 };
+    }
+    const windows = parseRateLimits(payload);
+    if (windows.length === 0) {
+        output.writeln(output.info('no five_hour / seven_day rate_limits found in the payload'));
+        return { success: true, exitCode: 0 };
+    }
+    const forecasts = windows.map((w) => ({ label: w.label, f: forecastWindow(w.state, nowMs) }));
+    if (ctx.flags.json === true) {
+        output.printJson(forecasts.map((x) => ({ label: x.label, ...x.f })));
+        return { success: true, data: forecasts };
+    }
+    if (ctx.flags.oneline === true) {
+        // Compact statusline-ready indicator, e.g. "5h 72%⚠ · 7d 12%".
+        output.writeln(formatLimitSegment(forecasts));
+        const worstOne = worstStatus(forecasts.map((x) => x.f));
+        return { success: true, exitCode: ctx.flags.strict === true && worstOne === 'over' ? 1 : 0 };
+    }
+    const worst = worstStatus(forecasts.map((x) => x.f));
+    output.writeln(output.bold('Usage limits') + output.dim(`  (${worst})`));
+    for (const { label, f } of forecasts) {
+        const line = formatForecast(label, f, nowMs);
+        output.writeln('  ' + (f.status === 'over' ? output.error(line) : f.status === 'warn' ? line : output.dim(line)));
+    }
+    const exitCode = ctx.flags.strict === true && worst === 'over' ? 1 : 0;
+    if (exitCode === 1)
+        output.writeln(output.dim('exit 1 (--strict + cap reached)'));
+    return { success: exitCode === 0, exitCode };
+}
 async function run(ctx) {
     const viewName = (ctx.args[0] || 'daily').toLowerCase();
     if (viewName === 'blocks') {
@@ -409,9 +552,17 @@ async function run(ctx) {
         const dirs = typeof dirFlag === 'string' ? [dirFlag] : Array.isArray(dirFlag) ? dirFlag.map(String) : undefined;
         return runDiffView(ctx, collectUsage({ dirs }));
     }
+    if (viewName === 'reflect') {
+        const dirFlag = ctx.flags.dir;
+        const dirs = typeof dirFlag === 'string' ? [dirFlag] : Array.isArray(dirFlag) ? dirFlag.map(String) : undefined;
+        return runReflectView(ctx, collectUsage({ dirs }));
+    }
+    if (viewName === 'limits') {
+        return runLimitsView(ctx); // reads the rate_limits payload from stdin/--payload, not transcripts
+    }
     const view = VIEWS[viewName];
     if (!view) {
-        output.writeln(output.error(`unknown view: ${viewName} (expected ${Object.keys(VIEWS).join('|')}|blocks|errors|cache|guard|diff)`));
+        output.writeln(output.error(`unknown view: ${viewName} (expected ${Object.keys(VIEWS).join('|')}|blocks|errors|cache|guard|diff|reflect|limits)`));
         return { success: false, exitCode: 1 };
     }
     const since = typeof ctx.flags.since === 'string' ? ctx.flags.since : undefined;
@@ -433,12 +584,31 @@ async function run(ctx) {
         output.writeln(JSON.stringify(jsonPayload(viewName, collection, rows, grand, since, until), null, 2));
         return { success: true, exitCode: 0, data: grand };
     }
+    if (ctx.flags.csv === true) {
+        // Portable export for spreadsheets / expense reports.
+        const headers = ['key', 'costUsd', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'totalTokens', 'entries'];
+        const csvRows = rows.map((r) => [r.key, r.totals.costUsd, r.totals.inputTokens, r.totals.outputTokens, r.totals.cacheReadTokens, r.totals.cacheWriteTokens, r.totals.totalTokens, r.totals.entries]);
+        output.writeln(toCsv(headers, csvRows));
+        return { success: true, exitCode: 0, data: grand };
+    }
     if (collection.events.length === 0) {
         output.writeln(output.info(`no usage entries found in ${collection.filesScanned} transcript files`));
         return { success: true, exitCode: 0 };
     }
     output.writeln(output.bold(`Claude Code usage — ${viewName}`) + (since || until ? output.dim(`  (${since ?? '…'} → ${until ?? '…'})`) : ''));
     renderTable(view.label, rows, grand);
+    if (viewName === 'monthly') {
+        // Month-end pace projection for the current calendar month.
+        const today = localDateKey(new Date());
+        const curMonth = today.slice(0, 7);
+        const dom = Number(today.slice(8, 10));
+        const curRow = rows.find((r) => r.key === curMonth);
+        const dim = daysInMonthOf(curMonth);
+        if (curRow && dom > 0 && Number.isFinite(dim)) {
+            const p = projectMonthEnd(curRow.totals.costUsd, dom, dim);
+            output.writeln(output.dim(`${curMonth} on pace for ~${fmtCost(p.projectedUsd)}  (${fmtCost(p.monthToDateUsd)} over ${dom}/${p.daysInMonth} days · ~${fmtCost(p.remainingUsd)} to go)`));
+        }
+    }
     output.writeln(output.dim(`${collection.filesScanned} transcript files · ${grand.entries} billed responses · sources: ${collection.dirsScanned.join(', ')}`));
     if (collection.unpricedModels.length > 0) {
         const { unpricedResponses, unpricedTokens } = unpricedStats(collection.events);
@@ -456,11 +626,13 @@ export const usageCommand = {
         { name: 'dir', description: 'explicit Claude projects dir (replaces auto-discovery)', type: 'string' },
         { name: 'limit', description: 'max rows for models/projects/sessions views', type: 'number' },
         { name: 'json', description: 'machine-readable output', type: 'boolean', default: false },
+        { name: 'csv', description: 'CSV export (daily|monthly|models|projects|sessions views)', type: 'boolean', default: false },
     ],
     examples: [
         { command: 'swarmdo usage', description: 'Daily token/cost table across all local Claude Code sessions' },
         { command: 'swarmdo usage models --since 2026-07-01', description: 'Spend per model this month' },
         { command: 'swarmdo usage projects --json', description: 'Per-project totals as JSON' },
+        { command: 'swarmdo usage monthly --csv > usage.csv', description: 'Export monthly spend to CSV' },
         { command: 'swarmdo cost sessions --limit 10', description: 'Ten most expensive sessions (alias)' },
     ],
     action: run,

package/v3/@swarmdo/cli/dist/src/usage/limits.d.ts

@@ -0,0 +1,77 @@
+/**
+ * limits.ts — forecast when a Claude Code usage window will hit its cap.
+ *
+ * Claude Code passes an official `rate_limits` payload to statusline scripts:
+ * for the rolling 5-hour and 7-day windows it reports `used_percentage` and
+ * `resets_at`. This is the projection layer on top — at the current burn rate,
+ * when will the window hit 100%, and does that land before the window resets?
+ * ("at this pace you hit the weekly cap Thu 14:00, 6h before it resets").
+ *
+ * Pure + deterministic: it takes a normalized window state + an injected `now`
+ * (the statusline shim maps the raw payload to WindowState — see #46), so the
+ * projection math is unit-tested with zero clock or wire-format coupling.
+ */
+export type LimitStatus = 'ok' | 'warn' | 'over';
+/** Rolling-window durations Claude Code reports (5-hour + 7-day caps). */
+export declare const FIVE_HOUR_MS: number;
+export declare const SEVEN_DAY_MS: number;
+export interface NamedWindow {
+    /** short label, '5h' | '7d' */
+    label: string;
+    state: WindowState;
+}
+/**
+ * Map Claude Code's statusline `rate_limits` payload to normalized windows.
+ * Tolerant of shape drift: accepts the payload bare or wrapped in `rate_limits`,
+ * snake_case or camelCase keys, and epoch-seconds / epoch-ms / ISO `resets_at`.
+ * Windows missing usage or a reset time are dropped. Pure.
+ */
+export declare function parseRateLimits(payload: unknown): NamedWindow[];
+export interface WindowState {
+    /** percent of the window's quota consumed, 0..100 */
+    usedPercentage: number;
+    /** window duration in ms (5h = 18_000_000, 7d = 604_800_000) */
+    windowMs: number;
+    /** epoch ms when the window resets to 0% */
+    resetsAtMs: number;
+}
+export interface LimitForecast {
+    usedPercentage: number;
+    resetsAtMs: number;
+    /** ms from now until the window resets (never negative) */
+    msToReset: number;
+    /** projected epoch ms when usage reaches 100% at the current burn rate, or
+     *  null when it can't be projected (no burn yet, already at/over 100%, or the
+     *  window hasn't started per the clock) */
+    exhaustionMs: number | null;
+    /** true when exhaustion is projected at or before the window resets */
+    willExhaust: boolean;
+    status: LimitStatus;
+}
+/**
+ * Forecast a single window. Burn rate is `usedPercentage / elapsed`, where
+ * elapsed = now − windowStart and windowStart = resetsAt − windowMs. Pure.
+ */
+export declare function forecastWindow(w: WindowState, nowMs: number, opts?: {
+    warnPct?: number;
+}): LimitForecast;
+/** Worst status across windows (over > warn > ok). Pure. */
+export declare function worstStatus(forecasts: LimitForecast[]): LimitStatus;
+/**
+ * The binding window — the one that constrains you first. A window projected to
+ * exhaust before reset outranks one that won't; among those that will, the
+ * earlier exhaustion wins; otherwise the higher used_percentage. null for [].
+ */
+export declare function bindingWindow(forecasts: LimitForecast[]): LimitForecast | null;
+/** Compact human duration for a ms span, e.g. 9000000 → "2h30m", 90000 → "1m". */
+export declare function humanizeMs(ms: number): string;
+/** Ultra-compact one-line indicator for a statusline, e.g. "5h 72%⚠ · 7d 12%".
+ * `!` marks an over-cap window, `⚠` an at-risk one. Pure. */
+export declare function formatLimitSegment(forecasts: Array<{
+    label: string;
+    f: LimitForecast;
+}>): string;
+/** One-line summary for a window, e.g. "5h window: 42% used, resets in 2h14m —
+ * on pace to hit the cap in ~1h20m (before reset)". `label` names the window. */
+export declare function formatForecast(label: string, f: LimitForecast, nowMs: number): string;
+//# sourceMappingURL=limits.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/limits.js

@@ -0,0 +1,134 @@
+/**
+ * limits.ts — forecast when a Claude Code usage window will hit its cap.
+ *
+ * Claude Code passes an official `rate_limits` payload to statusline scripts:
+ * for the rolling 5-hour and 7-day windows it reports `used_percentage` and
+ * `resets_at`. This is the projection layer on top — at the current burn rate,
+ * when will the window hit 100%, and does that land before the window resets?
+ * ("at this pace you hit the weekly cap Thu 14:00, 6h before it resets").
+ *
+ * Pure + deterministic: it takes a normalized window state + an injected `now`
+ * (the statusline shim maps the raw payload to WindowState — see #46), so the
+ * projection math is unit-tested with zero clock or wire-format coupling.
+ */
+/** Rolling-window durations Claude Code reports (5-hour + 7-day caps). */
+export const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+export const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+/** Coerce an epoch-seconds, epoch-ms, or ISO-string timestamp to epoch ms. */
+function toEpochMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v < 1e12 ? v * 1000 : v; // secs vs ms
+    if (typeof v === 'string') {
+        const t = Date.parse(v);
+        return Number.isNaN(t) ? null : t;
+    }
+    return null;
+}
+function pickWindow(obj, windowMs, label) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const o = obj;
+    const used = (o.used_percentage ?? o.usedPercentage);
+    const resetsAtMs = toEpochMs(o.resets_at ?? o.resetsAt);
+    if (typeof used !== 'number' || !Number.isFinite(used) || resetsAtMs === null)
+        return null;
+    return { label, state: { usedPercentage: Math.max(0, Math.min(100, used)), windowMs, resetsAtMs } };
+}
+/**
+ * Map Claude Code's statusline `rate_limits` payload to normalized windows.
+ * Tolerant of shape drift: accepts the payload bare or wrapped in `rate_limits`,
+ * snake_case or camelCase keys, and epoch-seconds / epoch-ms / ISO `resets_at`.
+ * Windows missing usage or a reset time are dropped. Pure.
+ */
+export function parseRateLimits(payload) {
+    const p = payload && typeof payload === 'object' ? payload : {};
+    const rl = (p.rate_limits ?? p.rateLimits ?? p);
+    const out = [];
+    const w5 = pickWindow(rl.five_hour ?? rl.fiveHour, FIVE_HOUR_MS, '5h');
+    const w7 = pickWindow(rl.seven_day ?? rl.sevenDay, SEVEN_DAY_MS, '7d');
+    if (w5)
+        out.push(w5);
+    if (w7)
+        out.push(w7);
+    return out;
+}
+/**
+ * Forecast a single window. Burn rate is `usedPercentage / elapsed`, where
+ * elapsed = now − windowStart and windowStart = resetsAt − windowMs. Pure.
+ */
+export function forecastWindow(w, nowMs, opts = {}) {
+    const warnPct = opts.warnPct ?? 80;
+    const used = w.usedPercentage;
+    const msToReset = Math.max(0, w.resetsAtMs - nowMs);
+    const windowStartMs = w.resetsAtMs - w.windowMs;
+    const elapsed = nowMs - windowStartMs;
+    let exhaustionMs = null;
+    if (used >= 100) {
+        // already exhausted — mark exhaustion as "now"
+        exhaustionMs = nowMs;
+    }
+    else if (used > 0 && elapsed > 0) {
+        const msTo100 = ((100 - used) * elapsed) / used; // (remaining%) / (used%/elapsed)
+        exhaustionMs = nowMs + msTo100;
+    }
+    const willExhaust = exhaustionMs !== null && exhaustionMs <= w.resetsAtMs;
+    const status = used >= 100 ? 'over' : (willExhaust || used >= warnPct) ? 'warn' : 'ok';
+    return { usedPercentage: used, resetsAtMs: w.resetsAtMs, msToReset, exhaustionMs, willExhaust, status };
+}
+/** Worst status across windows (over > warn > ok). Pure. */
+export function worstStatus(forecasts) {
+    const rank = { ok: 0, warn: 1, over: 2 };
+    return forecasts.reduce((acc, f) => (rank[f.status] > rank[acc] ? f.status : acc), 'ok');
+}
+/**
+ * The binding window — the one that constrains you first. A window projected to
+ * exhaust before reset outranks one that won't; among those that will, the
+ * earlier exhaustion wins; otherwise the higher used_percentage. null for [].
+ */
+export function bindingWindow(forecasts) {
+    if (forecasts.length === 0)
+        return null;
+    return [...forecasts].sort((a, b) => {
+        if (a.willExhaust !== b.willExhaust)
+            return a.willExhaust ? -1 : 1;
+        if (a.willExhaust && b.willExhaust)
+            return a.exhaustionMs - b.exhaustionMs;
+        return b.usedPercentage - a.usedPercentage;
+    })[0];
+}
+/** Compact human duration for a ms span, e.g. 9000000 → "2h30m", 90000 → "1m". */
+export function humanizeMs(ms) {
+    if (ms <= 0)
+        return '0m';
+    const totalMin = Math.floor(ms / 60_000);
+    const d = Math.floor(totalMin / 1440);
+    const h = Math.floor((totalMin % 1440) / 60);
+    const m = totalMin % 60;
+    if (d > 0)
+        return `${d}d${h > 0 ? `${h}h` : ''}`;
+    if (h > 0)
+        return `${h}h${m > 0 ? `${m}m` : ''}`;
+    return `${m}m`;
+}
+/** Ultra-compact one-line indicator for a statusline, e.g. "5h 72%⚠ · 7d 12%".
+ * `!` marks an over-cap window, `⚠` an at-risk one. Pure. */
+export function formatLimitSegment(forecasts) {
+    if (forecasts.length === 0)
+        return 'limits: n/a';
+    const mark = (s) => (s === 'over' ? '!' : s === 'warn' ? '⚠' : '');
+    return forecasts.map(({ label, f }) => `${label} ${Math.round(f.usedPercentage)}%${mark(f.status)}`).join(' · ');
+}
+/** One-line summary for a window, e.g. "5h window: 42% used, resets in 2h14m —
+ * on pace to hit the cap in ~1h20m (before reset)". `label` names the window. */
+export function formatForecast(label, f, nowMs) {
+    const head = `${label}: ${Math.round(f.usedPercentage)}% used, resets in ${humanizeMs(f.msToReset)}`;
+    if (f.status === 'over')
+        return `${head} — CAP REACHED`;
+    if (f.willExhaust && f.exhaustionMs !== null) {
+        const inMs = Math.max(0, f.exhaustionMs - nowMs);
+        const before = humanizeMs(f.resetsAtMs - f.exhaustionMs);
+        return `${head} — on pace to hit the cap in ~${humanizeMs(inMs)} (${before} before reset)`;
+    }
+    return `${head} — on pace to stay under the cap`;
+}
+//# sourceMappingURL=limits.js.map

package/v3/@swarmdo/cli/dist/src/usage/reflect-html.d.ts

@@ -0,0 +1,23 @@
+/**
+ * reflect-html.ts — render a Reflection (see reflect.ts) into a self-contained,
+ * shareable HTML dashboard for `swarmdo usage reflect --html`.
+ *
+ * Pure + deterministic: it takes an already-computed Reflection and returns a
+ * complete HTML document string with all CSS inlined (no external requests, no
+ * clock — any timestamp is passed in), so it unit-tests without a browser or a
+ * network. Every user-controlled string (model ids, project paths) is HTML-
+ * escaped. See #47.
+ */
+import type { Reflection } from './reflect.js';
+/** HTML-escape a string for safe interpolation into text or attributes. */
+export declare function escapeHtml(s: string): string;
+/** Render the retrospective to a complete self-contained HTML document. Pure. */
+export declare function renderReflectionHtml(r: Reflection, opts?: {
+    generatedAt?: string;
+    delegation?: {
+        taskCalls: number;
+        toolCalls: number;
+        ratio: number;
+    };
+}): string;
+//# sourceMappingURL=reflect-html.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/reflect-html.js

@@ -0,0 +1,94 @@
+/**
+ * reflect-html.ts — render a Reflection (see reflect.ts) into a self-contained,
+ * shareable HTML dashboard for `swarmdo usage reflect --html`.
+ *
+ * Pure + deterministic: it takes an already-computed Reflection and returns a
+ * complete HTML document string with all CSS inlined (no external requests, no
+ * clock — any timestamp is passed in), so it unit-tests without a browser or a
+ * network. Every user-controlled string (model ids, project paths) is HTML-
+ * escaped. See #47.
+ */
+/** HTML-escape a string for safe interpolation into text or attributes. */
+export function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+const num = (n) => n.toLocaleString('en-US');
+const pct = (x) => `${Math.round(x * 100)}%`;
+/** A labelled proportional bar (width is % of the largest value in its group). */
+function bar(label, valueText, fillPct) {
+    const w = Math.max(0, Math.min(100, fillPct));
+    return `<div class="bar"><div class="bar-label" title="${escapeHtml(label)}">${escapeHtml(label)}</div>`
+        + `<div class="bar-track"><div class="bar-fill" style="width:${w.toFixed(1)}%"></div></div>`
+        + `<div class="bar-val">${escapeHtml(valueText)}</div></div>`;
+}
+function shareBars(rows) {
+    if (!rows.length)
+        return '<p class="empty">—</p>';
+    const max = Math.max(...rows.map((r) => r.costUsd), 0) || 1;
+    return rows.map((r) => bar(r.model, `${usd(r.costUsd)} · ${pct(r.pct)}`, (r.costUsd / max) * 100)).join('');
+}
+function hourBars(hist) {
+    if (!hist.some((v) => v > 0))
+        return '<p class="empty">—</p>';
+    const max = Math.max(...hist) || 1;
+    const cells = hist.map((v, h) => {
+        const hpct = (v / max) * 100;
+        return `<div class="hour" title="${String(h).padStart(2, '0')}:00 — ${usd(v)}">`
+            + `<div class="hour-bar" style="height:${hpct.toFixed(1)}%"></div>`
+            + `<div class="hour-tick">${h % 6 === 0 ? String(h).padStart(2, '0') : ''}</div></div>`;
+    }).join('');
+    return `<div class="hours">${cells}</div>`;
+}
+function stat(label, value) {
+    return `<div class="stat"><div class="stat-val">${escapeHtml(value)}</div><div class="stat-label">${escapeHtml(label)}</div></div>`;
+}
+/** Render the retrospective to a complete self-contained HTML document. Pure. */
+export function renderReflectionHtml(r, opts = {}) {
+    const arrow = r.trend.direction === 'up' ? '↑' : r.trend.direction === 'down' ? '↓' : '→';
+    const peak = r.peakHour ? `${String(r.peakHour.hour).padStart(2, '0')}:00` : '—';
+    const busiest = r.busiestDay ? `${r.busiestDay.day} (${usd(r.busiestDay.costUsd)})` : '—';
+    const gen = opts.generatedAt ? `<p class="gen">generated ${escapeHtml(opts.generatedAt)}</p>` : '';
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Claude Code Reflect — ${escapeHtml(r.period.from)}..${escapeHtml(r.period.to)}</title>
+<style>
+:root{--bg:#0f1117;--card:#181b24;--fg:#e6e8ee;--muted:#8b90a0;--accent:#7c9cff;--track:#262a36}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;padding:32px}
+.wrap{max-width:840px;margin:0 auto}
+h1{font-size:22px;margin:0 0 2px}.sub{color:var(--muted);margin:0 0 24px}.gen{color:var(--muted);font-size:12px;margin:24px 0 0}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:28px}
+.stat{background:var(--card);border-radius:12px;padding:16px}
+.stat-val{font-size:22px;font-weight:600}.stat-label{color:var(--muted);font-size:12px;margin-top:4px}
+h2{font-size:14px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted);margin:28px 0 12px}
+.bar{display:grid;grid-template-columns:minmax(0,1fr) 3fr minmax(0,auto);align-items:center;gap:10px;margin:6px 0}
+.bar-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:13px}
+.bar-track{background:var(--track);border-radius:6px;height:14px;overflow:hidden}
+.bar-fill{background:var(--accent);height:100%;border-radius:6px}
+.bar-val{font-size:12px;color:var(--muted);white-space:nowrap}
+.hours{display:flex;align-items:flex-end;gap:3px;height:90px}
+.hour{flex:1;display:flex;flex-direction:column;justify-content:flex-end;align-items:center;height:100%}
+.hour-bar{width:100%;background:var(--accent);border-radius:3px 3px 0 0;min-height:1px}
+.hour-tick{font-size:9px;color:var(--muted);margin-top:4px;height:12px}
+.empty{color:var(--muted)}
+</style></head><body><div class="wrap">
+<h1>Claude Code Reflect ${escapeHtml(arrow)}</h1>
+<p class="sub">${escapeHtml(r.period.from)} .. ${escapeHtml(r.period.to)} · ${r.period.spanDays} days · ${r.totals.activeDays} active</p>
+<div class="grid">
+${stat('Total spend', usd(r.totals.costUsd))}
+${stat('Total tokens', num(r.totals.totalTokens))}
+${stat('Avg / active day', usd(r.avgCostPerActiveDay))}
+${stat('Longest streak', `${r.longestStreak} day${r.longestStreak === 1 ? '' : 's'}`)}
+${stat('Peak hour', peak)}
+${stat('Cache read', pct(r.cacheReadPct))}
+${stat('Busiest day', busiest)}
+${stat('Trend', `${arrow} ${pct(r.trend.firstHalfCost > 0 ? (r.trend.secondHalfCost - r.trend.firstHalfCost) / r.trend.firstHalfCost : 0)}`)}
+${opts.delegation && opts.delegation.toolCalls > 0 ? stat('Delegation', pct(opts.delegation.ratio)) : ''}
+</div>
+<h2>Cost by hour of day</h2>${hourBars(r.hourHistogram)}
+<h2>Top models</h2>${shareBars(r.topModels)}
+<h2>Top projects</h2>${shareBars(r.topProjects)}
+${gen}
+</div></body></html>`;
+}
+//# sourceMappingURL=reflect-html.js.map

package/v3/@swarmdo/cli/dist/src/usage/reflect.d.ts

@@ -0,0 +1,105 @@
+/**
+ * reflect.ts — a "wrapped"-style retrospective over Claude Code usage.
+ *
+ * Anthropic's Reflect (2026-07-09) summarizes claude.ai *chats*; it doesn't
+ * touch Claude Code terminal work. swarmdo already parses the local transcripts
+ * for `usage daily/monthly/blocks/errors/cache`, so this is the retrospective
+ * layer on top: fold the existing per-day and per-(model,day) aggregation rows
+ * into headline stats — totals, the busiest day, the top models, the longest
+ * active-day streak, the cost trend, and cache efficiency.
+ *
+ * Pure + deterministic: it takes already-aggregated rows (no transcripts, no
+ * clock — the period bounds are passed in), so the whole thing is unit-tested
+ * without touching disk. The command layer in ../commands/usage.ts feeds it the
+ * rows the parser already produces. See #47.
+ */
+import type { DayRow, ModelRow } from './diff.js';
+export interface ModelShare {
+    model: string;
+    costUsd: number;
+    totalTokens: number;
+    /** share of total cost, 0..1 (0 when the period cost is 0) */
+    pct: number;
+}
+export interface ReflectionTotals {
+    costUsd: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    entries: number;
+    /** days in [from,to] with any token activity */
+    activeDays: number;
+}
+export interface Reflection {
+    period: {
+        from: string;
+        to: string; /** inclusive calendar span in days */
+        spanDays: number;
+    };
+    totals: ReflectionTotals;
+    /** highest-cost active day in the period, or null if the period is empty */
+    busiestDay: {
+        day: string;
+        costUsd: number;
+        totalTokens: number;
+    } | null;
+    /** models ranked by cost desc (capped to opts.topModels) */
+    topModels: ModelShare[];
+    /** projects ranked by cost desc (ModelShare.model holds the project path) */
+    topProjects: ModelShare[];
+    /** busiest local hour-of-day by cost (0..23), or null if no activity */
+    peakHour: {
+        hour: number;
+        value: number;
+    } | null;
+    /** cost per local hour-of-day, as supplied by the caller (length 24 when set) */
+    hourHistogram: number[];
+    /** longest run of consecutive active calendar days */
+    longestStreak: number;
+    /** cacheRead / (input + cacheWrite + cacheRead), 0..1 */
+    cacheReadPct: number;
+    /** total cost / active days (0 when no active days) */
+    avgCostPerActiveDay: number;
+    /** first-half vs second-half spend across the period */
+    trend: {
+        firstHalfCost: number;
+        secondHalfCost: number;
+        direction: 'up' | 'down' | 'flat';
+    };
+}
+export interface ReflectOptions {
+    /** how many models to keep in topModels (default 5) */
+    topModels?: number;
+    /** relative change below which the trend reads 'flat' (default 0.05 = 5%) */
+    flatThreshold?: number;
+}
+/** The calendar day after an ISO date (handles month/year rollover). Pure. */
+export declare function nextDay(iso: string): string;
+/**
+ * The ISO date `n` whole months before `iso`, clamping the day to the target
+ * month's length so "Mar 31 − 1 month" is Feb 28/29 (not a rolled-over Mar 3).
+ * Pure. Used to derive a `--period 1m|3m|…` window start from today.
+ */
+export declare function monthsBefore(iso: string, n: number): string;
+/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+export declare function spanDays(from: string, to: string): number;
+/** Longest run of consecutive calendar days present in the set. Pure. */
+export declare function longestStreakOf(days: string[]): number;
+/** Render a numeric series as a Unicode block sparkline (one char per bucket).
+ * Zero buckets are blank; the rest scale ▁..█ against the max. Pure — used for
+ * the terminal cost-by-hour view (the HTML dashboard draws the same data). */
+export declare function hourSparkline(hist: number[]): string;
+/** Window + aggregate `{key, day, totals}` rows into cost-ranked shares. Pure.
+ * Reused for both models and projects (ModelShare.model carries whichever key). */
+export declare function rankShares(rows: ModelRow[], from: string, to: string, totalCost: number, topN: number): ModelShare[];
+/** Busiest bucket in a per-hour cost histogram (argmax; earliest hour wins ties),
+ * or null when every bucket is empty. Pure. */
+export declare function peakHourOf(hourHistogram: number[]): {
+    hour: number;
+    value: number;
+} | null;
+/** Fold pre-aggregated usage rows into a retrospective. Pure. */
+export declare function computeReflection(dayRows: DayRow[], modelRows: ModelRow[], from: string, to: string, opts?: ReflectOptions, projectRows?: ModelRow[], hourHistogram?: number[]): Reflection;
+//# sourceMappingURL=reflect.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/reflect.js

@@ -0,0 +1,165 @@
+/**
+ * reflect.ts — a "wrapped"-style retrospective over Claude Code usage.
+ *
+ * Anthropic's Reflect (2026-07-09) summarizes claude.ai *chats*; it doesn't
+ * touch Claude Code terminal work. swarmdo already parses the local transcripts
+ * for `usage daily/monthly/blocks/errors/cache`, so this is the retrospective
+ * layer on top: fold the existing per-day and per-(model,day) aggregation rows
+ * into headline stats — totals, the busiest day, the top models, the longest
+ * active-day streak, the cost trend, and cache efficiency.
+ *
+ * Pure + deterministic: it takes already-aggregated rows (no transcripts, no
+ * clock — the period bounds are passed in), so the whole thing is unit-tested
+ * without touching disk. The command layer in ../commands/usage.ts feeds it the
+ * rows the parser already produces. See #47.
+ */
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** The calendar day after an ISO date (handles month/year rollover). Pure. */
+export function nextDay(iso) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const dt = new Date(y, m - 1, d + 1);
+    const yy = dt.getFullYear();
+    const mm = String(dt.getMonth() + 1).padStart(2, '0');
+    const dd = String(dt.getDate()).padStart(2, '0');
+    return `${yy}-${mm}-${dd}`;
+}
+/**
+ * The ISO date `n` whole months before `iso`, clamping the day to the target
+ * month's length so "Mar 31 − 1 month" is Feb 28/29 (not a rolled-over Mar 3).
+ * Pure. Used to derive a `--period 1m|3m|…` window start from today.
+ */
+export function monthsBefore(iso, n) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const monthIndex = m - 1 - n; // may be negative — Date normalizes the year
+    const lastDay = new Date(y, monthIndex + 1, 0).getDate();
+    const dt = new Date(y, monthIndex, Math.min(d, lastDay));
+    const yy = dt.getFullYear();
+    const mm = String(dt.getMonth() + 1).padStart(2, '0');
+    const dd = String(dt.getDate()).padStart(2, '0');
+    return `${yy}-${mm}-${dd}`;
+}
+/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+export function spanDays(from, to) {
+    const a = new Date(from + 'T00:00:00');
+    const b = new Date(to + 'T00:00:00');
+    return Math.floor((b.getTime() - a.getTime()) / 86_400_000) + 1;
+}
+/** Longest run of consecutive calendar days present in the set. Pure. */
+export function longestStreakOf(days) {
+    const uniq = [...new Set(days)].sort();
+    let best = 0;
+    let run = 0;
+    let prev = null;
+    for (const d of uniq) {
+        run = prev !== null && nextDay(prev) === d ? run + 1 : 1;
+        if (run > best)
+            best = run;
+        prev = d;
+    }
+    return best;
+}
+const within = (key, from, to) => key >= from && key <= to;
+const SPARK_BLOCKS = ' ▁▂▃▄▅▆▇█'; // index 0 = empty (zero), 1..8 = ▁..█ scaled to max
+/** Render a numeric series as a Unicode block sparkline (one char per bucket).
+ * Zero buckets are blank; the rest scale ▁..█ against the max. Pure — used for
+ * the terminal cost-by-hour view (the HTML dashboard draws the same data). */
+export function hourSparkline(hist) {
+    const max = Math.max(0, ...hist);
+    if (max <= 0)
+        return ' '.repeat(hist.length);
+    return hist.map((v) => SPARK_BLOCKS[v <= 0 ? 0 : Math.min(8, 1 + Math.floor((v / max) * 7))]).join('');
+}
+/** Window + aggregate `{key, day, totals}` rows into cost-ranked shares. Pure.
+ * Reused for both models and projects (ModelShare.model carries whichever key). */
+export function rankShares(rows, from, to, totalCost, topN) {
+    const per = new Map();
+    for (const r of rows) {
+        if (!within(r.day, from, to))
+            continue;
+        const slot = per.get(r.key) ?? { costUsd: 0, totalTokens: 0 };
+        slot.costUsd += r.totals.costUsd;
+        slot.totalTokens += r.totals.totalTokens;
+        per.set(r.key, slot);
+    }
+    return [...per.entries()]
+        .map(([key, v]) => ({ model: key, costUsd: v.costUsd, totalTokens: v.totalTokens, pct: totalCost > 0 ? v.costUsd / totalCost : 0 }))
+        .filter((m) => m.costUsd > 0 || m.totalTokens > 0)
+        .sort((a, b) => b.costUsd - a.costUsd || b.totalTokens - a.totalTokens || (a.model < b.model ? -1 : 1))
+        .slice(0, topN);
+}
+/** Busiest bucket in a per-hour cost histogram (argmax; earliest hour wins ties),
+ * or null when every bucket is empty. Pure. */
+export function peakHourOf(hourHistogram) {
+    let best = -1;
+    let bestVal = 0;
+    for (let h = 0; h < hourHistogram.length; h++) {
+        if (hourHistogram[h] > bestVal) {
+            bestVal = hourHistogram[h];
+            best = h;
+        }
+    }
+    return best < 0 ? null : { hour: best, value: bestVal };
+}
+/** Fold pre-aggregated usage rows into a retrospective. Pure. */
+export function computeReflection(dayRows, modelRows, from, to, opts = {}, projectRows = [], hourHistogram = []) {
+    if (!DATE.test(from) || !DATE.test(to))
+        throw new Error(`bad period bounds: ${from}..${to}`);
+    if (from > to)
+        throw new Error(`period "${from}..${to}" is reversed (from > to)`);
+    const topN = opts.topModels ?? 5;
+    const flat = opts.flatThreshold ?? 0.05;
+    const days = dayRows.filter((r) => within(r.key, from, to));
+    const totals = {
+        costUsd: 0, totalTokens: 0, inputTokens: 0, outputTokens: 0,
+        cacheReadTokens: 0, cacheWriteTokens: 0, entries: 0, activeDays: 0,
+    };
+    let busiestDay = null;
+    const activeDayKeys = [];
+    const mid = spanDays(from, to) / 2;
+    let firstHalfCost = 0;
+    let secondHalfCost = 0;
+    for (const r of days) {
+        const t = r.totals;
+        totals.costUsd += t.costUsd;
+        totals.totalTokens += t.totalTokens;
+        totals.inputTokens += t.inputTokens;
+        totals.outputTokens += t.outputTokens;
+        totals.cacheReadTokens += t.cacheReadTokens;
+        totals.cacheWriteTokens += t.cacheWriteTokens;
+        if (t.totalTokens > 0) {
+            totals.activeDays += 1;
+            activeDayKeys.push(r.key);
+        }
+        if (!busiestDay || t.costUsd > busiestDay.costUsd) {
+            busiestDay = { day: r.key, costUsd: t.costUsd, totalTokens: t.totalTokens };
+        }
+        // Trend: which half of the period does this day fall in?
+        if (spanDays(from, r.key) <= mid)
+            firstHalfCost += t.costUsd;
+        else
+            secondHalfCost += t.costUsd;
+    }
+    // A period with zero active days has no meaningful busiest day.
+    if (totals.activeDays === 0)
+        busiestDay = null;
+    // Cost-ranked shares over the same window, for both models and projects.
+    const topModels = rankShares(modelRows, from, to, totals.costUsd, topN);
+    const topProjects = rankShares(projectRows, from, to, totals.costUsd, topN);
+    const inputSide = totals.inputTokens + totals.cacheWriteTokens + totals.cacheReadTokens;
+    const relChange = firstHalfCost > 0 ? (secondHalfCost - firstHalfCost) / firstHalfCost : (secondHalfCost > 0 ? 1 : 0);
+    const direction = Math.abs(relChange) < flat ? 'flat' : relChange > 0 ? 'up' : 'down';
+    return {
+        period: { from, to, spanDays: spanDays(from, to) },
+        totals,
+        busiestDay,
+        topModels,
+        topProjects,
+        peakHour: peakHourOf(hourHistogram),
+        hourHistogram,
+        longestStreak: longestStreakOf(activeDayKeys),
+        cacheReadPct: inputSide > 0 ? totals.cacheReadTokens / inputSide : 0,
+        avgCostPerActiveDay: totals.activeDays > 0 ? totals.costUsd / totals.activeDays : 0,
+        trend: { firstHalfCost, secondHalfCost, direction },
+    };
+}
+//# sourceMappingURL=reflect.js.map

package/v3/@swarmdo/cli/dist/src/usage/spend-forecast.d.ts

@@ -0,0 +1,28 @@
+/**
+ * spend-forecast.ts — project month-end Claude Code spend from month-to-date
+ * burn, for budgeting ("on pace for ~$420 this month").
+ *
+ * The quota forecaster (limits.ts) answers "will I hit the rolling cap"; this
+ * answers "what will the calendar month cost at the current daily average".
+ * Pure + deterministic: month-to-date total, the day-of-month, and the days in
+ * the month are passed in, so it's unit-tested without a clock.
+ */
+export interface SpendProjection {
+    monthToDateUsd: number;
+    dayOfMonth: number;
+    daysInMonth: number;
+    /** month-to-date / day-of-month */
+    dailyAverageUsd: number;
+    /** dailyAverage × daysInMonth — projected month-end total */
+    projectedUsd: number;
+    /** projectedUsd − monthToDateUsd — the remaining projected spend */
+    remainingUsd: number;
+}
+/** Days in the calendar month of an ISO `YYYY-MM` (or `YYYY-MM-DD`). Pure. */
+export declare function daysInMonthOf(iso: string): number;
+/**
+ * Project month-end spend at the current daily average. `dayOfMonth` is how many
+ * days (inclusive of today) have accrued the month-to-date total. Pure.
+ */
+export declare function projectMonthEnd(monthToDateUsd: number, dayOfMonth: number, daysInMonth: number): SpendProjection;
+//# sourceMappingURL=spend-forecast.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/spend-forecast.js

@@ -0,0 +1,33 @@
+/**
+ * spend-forecast.ts — project month-end Claude Code spend from month-to-date
+ * burn, for budgeting ("on pace for ~$420 this month").
+ *
+ * The quota forecaster (limits.ts) answers "will I hit the rolling cap"; this
+ * answers "what will the calendar month cost at the current daily average".
+ * Pure + deterministic: month-to-date total, the day-of-month, and the days in
+ * the month are passed in, so it's unit-tested without a clock.
+ */
+/** Days in the calendar month of an ISO `YYYY-MM` (or `YYYY-MM-DD`). Pure. */
+export function daysInMonthOf(iso) {
+    const [y, m] = iso.split('-').map(Number);
+    if (!Number.isFinite(y) || !Number.isFinite(m) || m < 1 || m > 12)
+        return NaN;
+    return new Date(y, m, 0).getDate(); // day 0 of the next month = last day of this one
+}
+/**
+ * Project month-end spend at the current daily average. `dayOfMonth` is how many
+ * days (inclusive of today) have accrued the month-to-date total. Pure.
+ */
+export function projectMonthEnd(monthToDateUsd, dayOfMonth, daysInMonth) {
+    const dailyAverageUsd = dayOfMonth > 0 ? monthToDateUsd / dayOfMonth : 0;
+    const projectedUsd = dailyAverageUsd * daysInMonth;
+    return {
+        monthToDateUsd,
+        dayOfMonth,
+        daysInMonth,
+        dailyAverageUsd,
+        projectedUsd,
+        remainingUsd: Math.max(0, projectedUsd - monthToDateUsd),
+    };
+}
+//# sourceMappingURL=spend-forecast.js.map

package/v3/@swarmdo/cli/dist/src/usage/transcript-errors.d.ts

@@ -31,6 +31,20 @@ export interface ToolErrorReport {
     filesScanned: number;
     sessionsWithErrors: number;
 }
+export interface Delegation {
+    /** tool_use calls to the `Task` tool (subagent spawns) */
+    taskCalls: number;
+    /** all tool_use calls */
+    toolCalls: number;
+    /** taskCalls / toolCalls, 0..1 (0 when no tool calls) */
+    ratio: number;
+}
+/**
+ * Delegation ratio: what fraction of tool calls spawned a subagent (the `Task`
+ * tool), from an already-collected tool report. The report's parsing/counting
+ * is the tested collectToolErrors path — this just extracts the Task share. Pure.
+ */
+export declare function delegationFromReport(report: Pick<ToolErrorReport, 'tools' | 'totalCalls'>): Delegation;
 export interface ParsedLine {
     type?: string;
     timestamp?: string;

package/v3/@swarmdo/cli/dist/src/usage/transcript-errors.js

@@ -12,6 +12,16 @@
  */
 import * as fs from 'node:fs';
 import { defaultClaudeProjectDirs, findTranscriptFiles, normalizeDateBound } from './transcript-usage.js';
+/**
+ * Delegation ratio: what fraction of tool calls spawned a subagent (the `Task`
+ * tool), from an already-collected tool report. The report's parsing/counting
+ * is the tested collectToolErrors path — this just extracts the Task share. Pure.
+ */
+export function delegationFromReport(report) {
+    const taskCalls = report.tools.find((t) => t.tool === 'Task')?.calls ?? 0;
+    const toolCalls = report.totalCalls;
+    return { taskCalls, toolCalls, ratio: toolCalls > 0 ? taskCalls / toolCalls : 0 };
+}
 export function newAccum() {
     return { idToTool: new Map(), calls: new Map(), errors: new Map(), sigs: new Map(), sessionsWithErrors: new Set() };
 }

package/v3/@swarmdo/cli/dist/src/util/csv.d.ts

@@ -0,0 +1,14 @@
+/**
+ * csv.ts — minimal RFC 4180 CSV serialization for exporting tabular command
+ * output (e.g. `usage --csv` into a spreadsheet / expense report).
+ *
+ * Pure and dependency-free. A field is quoted only when it must be — it contains
+ * a comma, a double-quote, or a line break — and interior double-quotes are
+ * doubled. Rows are joined with '\n' (LF), which every spreadsheet importer
+ * accepts.
+ */
+/** Quote + escape a single CSV field per RFC 4180 (only when necessary). Pure. */
+export declare function escapeCsvField(value: string | number | boolean | null | undefined): string;
+/** Serialize a header row + data rows to a CSV string. Pure. */
+export declare function toCsv(headers: string[], rows: Array<Array<string | number | boolean | null | undefined>>): string;
+//# sourceMappingURL=csv.d.ts.map

package/v3/@swarmdo/cli/dist/src/util/csv.js

@@ -0,0 +1,20 @@
+/**
+ * csv.ts — minimal RFC 4180 CSV serialization for exporting tabular command
+ * output (e.g. `usage --csv` into a spreadsheet / expense report).
+ *
+ * Pure and dependency-free. A field is quoted only when it must be — it contains
+ * a comma, a double-quote, or a line break — and interior double-quotes are
+ * doubled. Rows are joined with '\n' (LF), which every spreadsheet importer
+ * accepts.
+ */
+/** Quote + escape a single CSV field per RFC 4180 (only when necessary). Pure. */
+export function escapeCsvField(value) {
+    const s = value === null || value === undefined ? '' : String(value);
+    return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+/** Serialize a header row + data rows to a CSV string. Pure. */
+export function toCsv(headers, rows) {
+    const line = (cells) => cells.map(escapeCsvField).join(',');
+    return [line(headers), ...rows.map(line)].join('\n');
+}
+//# sourceMappingURL=csv.js.map

package/v3/@swarmdo/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmdo/cli",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "type": "module",
   "description": "Swarmdo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",