swarmdo 1.30.0 → 1.37.0

package/v3/@swarmdo/cli/dist/src/permissions/audit.d.ts

@@ -0,0 +1,50 @@
+/**
+ * permissions/audit.ts — static analyzer for Claude Code permission rules (#80).
+ *
+ * Claude Code reads `permissions.allow` / `deny` / `ask` arrays from
+ * `.claude/settings.json` (+ `settings.local.json` + `~/.claude/settings.json`),
+ * each entry a `Tool` or `Tool(specifier)` rule, with precedence deny > ask >
+ * allow. Users hand-edit these and get them wrong: a rule in both allow and deny
+ * (silently dead), a specific allow already covered by a broader one, or an
+ * over-broad `Bash(*)` that re-grants what deny was fencing off.
+ *
+ * This is the PURE rule layer — parse + set logic, no fs/network — so the whole
+ * analysis is unit-testable; the command reads the settings files.
+ */
+export type PermSeverity = 'error' | 'warn' | 'info';
+export interface PermFinding {
+    severity: PermSeverity;
+    /** kebab-case finding type */
+    rule: string;
+    message: string;
+    /** the rule string(s) the finding is about */
+    subjects: string[];
+}
+export interface ParsedRule {
+    tool: string;
+    /** undefined = a bare tool rule (grants the whole tool) */
+    specifier?: string;
+}
+export type ParseResult = ParsedRule | {
+    error: string;
+};
+export interface PermissionSets {
+    allow?: string[];
+    deny?: string[];
+    ask?: string[];
+}
+/** Parse one `Tool` or `Tool(specifier)` rule. */
+export declare function parseRule(raw: string): ParseResult;
+/**
+ * Does `broad` grant everything `specific` grants (same tool)? A bare tool or a
+ * `*` specifier covers anything on that tool; otherwise the broad specifier is
+ * glob-matched against the specific one (exact equality included).
+ */
+export declare function covers(broad: ParsedRule, specific: ParsedRule): boolean;
+/**
+ * Analyze a merged permission ruleset. Reports: allow↔deny conflicts (dead allow
+ * rules), allow rules shadowed by a broader allow, over-broad whole-tool grants,
+ * exact duplicates, and malformed rules. Order: errors, then warns, then infos.
+ */
+export declare function auditPermissions(perms: PermissionSets): PermFinding[];
+//# sourceMappingURL=audit.d.ts.map

package/v3/@swarmdo/cli/dist/src/permissions/audit.js

@@ -0,0 +1,127 @@
+/**
+ * permissions/audit.ts — static analyzer for Claude Code permission rules (#80).
+ *
+ * Claude Code reads `permissions.allow` / `deny` / `ask` arrays from
+ * `.claude/settings.json` (+ `settings.local.json` + `~/.claude/settings.json`),
+ * each entry a `Tool` or `Tool(specifier)` rule, with precedence deny > ask >
+ * allow. Users hand-edit these and get them wrong: a rule in both allow and deny
+ * (silently dead), a specific allow already covered by a broader one, or an
+ * over-broad `Bash(*)` that re-grants what deny was fencing off.
+ *
+ * This is the PURE rule layer — parse + set logic, no fs/network — so the whole
+ * analysis is unit-testable; the command reads the settings files.
+ */
+/** Parse one `Tool` or `Tool(specifier)` rule. */
+export function parseRule(raw) {
+    const s = (raw ?? '').trim();
+    if (!s)
+        return { error: 'empty rule' };
+    const open = s.indexOf('(');
+    if (open === -1) {
+        // Bare tool, e.g. `Bash` or `WebFetch`.
+        if (!/^[A-Za-z_][\w-]*$/.test(s))
+            return { error: 'invalid tool name' };
+        return { tool: s };
+    }
+    if (!s.endsWith(')'))
+        return { error: 'unbalanced parentheses' };
+    const tool = s.slice(0, open);
+    if (!tool)
+        return { error: 'missing tool name' };
+    if (!/^[A-Za-z_][\w-]*$/.test(tool))
+        return { error: 'invalid tool name' };
+    const specifier = s.slice(open + 1, s.length - 1);
+    if (specifier.trim() === '')
+        return { error: 'empty specifier' };
+    return { tool, specifier };
+}
+function isParsed(r) {
+    return r.tool !== undefined;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Turn a specifier glob (`*` = any run) into an anchored matcher. */
+function specifierMatches(broadSpec, target) {
+    const re = new RegExp('^' + broadSpec.split('*').map(escapeRegex).join('.*') + '$');
+    return re.test(target);
+}
+/**
+ * Does `broad` grant everything `specific` grants (same tool)? A bare tool or a
+ * `*` specifier covers anything on that tool; otherwise the broad specifier is
+ * glob-matched against the specific one (exact equality included).
+ */
+export function covers(broad, specific) {
+    if (broad.tool !== specific.tool)
+        return false;
+    if (broad.specifier === undefined)
+        return true; // bare tool grants all
+    if (broad.specifier === '*')
+        return true;
+    if (specific.specifier === undefined)
+        return false; // broad is scoped, specific is the whole tool
+    return specifierMatches(broad.specifier, specific.specifier);
+}
+/** True for a rule that grants an entire tool (`Bash` or `Bash(*)`). */
+function isWholeTool(r) {
+    return r.specifier === undefined || r.specifier === '*';
+}
+/**
+ * Analyze a merged permission ruleset. Reports: allow↔deny conflicts (dead allow
+ * rules), allow rules shadowed by a broader allow, over-broad whole-tool grants,
+ * exact duplicates, and malformed rules. Order: errors, then warns, then infos.
+ */
+export function auditPermissions(perms) {
+    const findings = [];
+    const parsed = { allow: [], deny: [], ask: [] };
+    for (const list of ['allow', 'deny', 'ask']) {
+        for (const raw of perms[list] ?? []) {
+            const r = parseRule(raw);
+            if (!isParsed(r)) {
+                findings.push({ severity: 'error', rule: 'malformed-rule', message: `${list} rule "${raw}" is malformed: ${r.error}`, subjects: [raw] });
+            }
+            else {
+                parsed[list].push({ raw, parsed: r });
+            }
+        }
+    }
+    // conflict: an allow rule that some deny rule covers is dead (deny wins).
+    for (const a of parsed.allow) {
+        const killer = parsed.deny.find((d) => covers(d.parsed, a.parsed));
+        if (killer) {
+            findings.push({ severity: 'error', rule: 'conflict', message: `allow "${a.raw}" is dead — deny "${killer.raw}" overrides it (deny wins)`, subjects: [a.raw, killer.raw] });
+        }
+    }
+    // over-broad: an allow rule granting a whole tool defeats scoped denies.
+    for (const a of parsed.allow) {
+        if (isWholeTool(a.parsed)) {
+            findings.push({ severity: 'warn', rule: 'over-broad', message: `allow "${a.raw}" grants every ${a.parsed.tool} call — narrow it or a scoped deny can't fence it off`, subjects: [a.raw] });
+        }
+    }
+    // exact duplicates within a list.
+    for (const list of ['allow', 'deny', 'ask']) {
+        const seen = new Set();
+        const dupped = new Set();
+        for (const e of parsed[list]) {
+            if (seen.has(e.raw))
+                dupped.add(e.raw);
+            else
+                seen.add(e.raw);
+        }
+        for (const raw of dupped) {
+            findings.push({ severity: 'info', rule: 'duplicate', message: `${list} rule "${raw}" is listed more than once`, subjects: [raw] });
+        }
+    }
+    // shadowed-allow: a scoped allow rule already covered by a broader, different allow.
+    for (const a of parsed.allow) {
+        if (isWholeTool(a.parsed))
+            continue; // whole-tool grants are flagged as over-broad, not shadowed
+        const broader = parsed.allow.find((b) => b.raw !== a.raw && covers(b.parsed, a.parsed));
+        if (broader) {
+            findings.push({ severity: 'info', rule: 'shadowed-allow', message: `allow "${a.raw}" is redundant — already covered by "${broader.raw}"`, subjects: [a.raw, broader.raw] });
+        }
+    }
+    const order = { error: 0, warn: 1, info: 2 };
+    return findings.sort((x, y) => order[x.severity] - order[y.severity]);
+}
+//# sourceMappingURL=audit.js.map

package/v3/@swarmdo/cli/dist/src/plugins/store/search.js

@@ -60,7 +60,7 @@ export function searchPlugins(registry, options = {}) {
     }
     // Security audit filter
     if (options.hasSecurityAudit !== undefined) {
-        plugins = plugins.filter(p => options.hasSecurityAudit ? p.securityAudit !== undefined : true);
+        plugins = plugins.filter(p => options.hasSecurityAudit ? p.securityAudit !== undefined : p.securityAudit === undefined);
     }
     // Sort
     const sortBy = options.sortBy || 'downloads';

package/v3/@swarmdo/cli/dist/src/redact/redact.js

@@ -45,9 +45,14 @@ export const RULES = [
  * `key`, `credential`, `creds` so `PRIVATE_KEY=`/`ENCRYPTION_KEY=`/`DB_CREDENTIAL=`
  * secrets reach the entropy check). The `[:=]` immediately after the keyword
  * anchors it, so `keyboard=`/`monkey_val=` don't match; the entropy + length
- * gates keep low-entropy values (paths, short flags) from being flagged.
+ * gates keep low-entropy values (paths, short flags) from being flagged. The
+ * value class also stops at the URL/query delimiters `&`, `?`, `#` (absent from
+ * base64/base64url/hex token alphabets): otherwise a query-string secret like
+ * `client_secret=…&api_key=…` over-captures past the `&` into the next secret,
+ * and that inflated span — overlapping a range the high-confidence RULES pass
+ * already claimed — gets dropped entirely, leaving the first secret unredacted.
  */
-const ASSIGNMENT_RE = /(?:pass(?:word|phrase|wd)?|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|auth[_-]?token|client[_-]?secret|credential|creds|key)["']?\s*[:=]\s*["']?([^\s"'`,;]{8,})/gi;
+const ASSIGNMENT_RE = /(?:pass(?:word|phrase|wd)?|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|auth[_-]?token|client[_-]?secret|credential|creds|key)["']?\s*[:=]\s*["']?([^\s"'`,;&?#]{8,})/gi;
 /** Shannon entropy in bits/char. Pure; used by the assignment fallback. */
 export function shannonEntropy(s) {
     if (!s)

package/v3/@swarmdo/cli/dist/src/release/release.js

@@ -49,7 +49,7 @@ export function planRelease(input) {
     for (const f of TRIO_FILES)
         steps.push({ kind: 'bump-json', file: f, version: next });
     steps.push({ kind: 'bump-lock', file: LOCK_FILE, version: next });
-    steps.push({ kind: 'sync-docs', version: next, files: DOC_FILES });
+    steps.push({ kind: 'sync-docs', version: next, files: [...DOC_FILES] }); // copy — a pure plan must not alias the module constant
     steps.push({ kind: 'exec', title: 'commit release', cmd: 'git', args: ['commit', '-am', `release: ${tag}`], cwd: root });
     steps.push({ kind: 'exec', title: 'push main', cmd: 'git', args: ['push', 'origin', 'main'], cwd: root });
     if (!input.skipPublish) {

package/v3/@swarmdo/cli/dist/src/sbom/sbom.d.ts

@@ -30,6 +30,8 @@ interface NpmLockEntry {
     license?: unknown;
     dev?: boolean;
     optional?: boolean;
+    /** npm workspace symlink — a local monorepo package, not a registry dependency. */
+    link?: boolean;
 }
 interface NpmLock {
     name?: string;

package/v3/@swarmdo/cli/dist/src/sbom/sbom.js

@@ -58,6 +58,11 @@ export function componentsFromNpmLock(lock, opts = {}) {
             continue; // the root project entry
         if (!key.includes('node_modules/'))
             continue;
+        // Skip workspace symlinks (`link:true`, no version) — they're the project's
+        // own local packages, not third-party components; emitting them fabricates a
+        // phantom `@name@0.0.0` purl that pollutes vuln scanners / regulators.
+        if (entry.link)
+            continue;
         if (opts.productionOnly && entry.dev)
             continue;
         const name = nameFromKey(key);

package/v3/@swarmdo/cli/dist/src/swarmvector/semantic-router.js

@@ -31,8 +31,13 @@ export class SemanticRouter {
                 throw new Error(`Embedding must be Float32Array of length ${this.dimension}`);
             }
         }
-        // Normalize embeddings for cosine similarity
-        const normalizedEmbeddings = embeddings.map(emb => this.normalize(emb));
+        // Normalize ONLY for cosine (cosine = dot product of unit vectors). The
+        // dotProduct and euclidean metrics are magnitude-sensitive, so they must
+        // keep the raw vectors — normalizing them unconditionally silently turned
+        // both into cosine and could flip the ranking.
+        const normalizedEmbeddings = this.metric === 'cosine'
+            ? embeddings.map(emb => this.normalize(emb))
+            : embeddings.map(emb => Float32Array.from(emb));
         this.intents.set(name, {
             name,
             embeddings: normalizedEmbeddings,
@@ -47,7 +52,7 @@ export class SemanticRouter {
         if (!(embedding instanceof Float32Array) || embedding.length !== this.dimension) {
             throw new Error(`Embedding must be Float32Array of length ${this.dimension}`);
         }
-        const normalizedQuery = this.normalize(embedding);
+        const normalizedQuery = this.metric === 'cosine' ? this.normalize(embedding) : embedding;
         const scores = [];
         // Calculate best score for each intent
         for (const [intentName, intent] of this.intents) {

package/v3/@swarmdo/cli/dist/src/testreport/testreport.js

@@ -97,8 +97,15 @@ export function parseJUnit(xml) {
         const suite = attrs.classname ?? attrs.suite ?? '';
         if (attrs.time)
             durationMs += Math.round(parseFloat(attrs.time) * 1000) || 0;
-        const fail = body.match(/<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/);
-        const isSkipped = /<skipped\b[^>]*\/?>/.test(body);
+        // Strip captured stdout/stderr before scanning for failure/skip markers: their
+        // text (pytest/jest-junit/gotestsum embed logs, often in CDATA) can contain
+        // literal <failure…>/<error…>-looking content that must NOT be read as a real
+        // failure element on an otherwise-passing test.
+        const scanBody = body
+            .replace(/<system-(out|err)\b[^>]*>[\s\S]*?<\/system-\1>/g, '')
+            .replace(/<system-(out|err)\b[^>]*\/>/g, '');
+        const fail = scanBody.match(/<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/);
+        const isSkipped = /<skipped\b[^>]*\/?>/.test(scanBody);
         if (fail) {
             failed++;
             const fAttrs = parseAttrs(fail[2]);

package/v3/@swarmdo/cli/dist/src/transcript/export.js

@@ -141,6 +141,7 @@ export function summarizeFile(fs_stat) {
     let firstPrompt = '';
     try {
         const content = fs.readFileSync(fs_stat.file, 'utf8');
+        const lines = [];
         for (const raw of content.split('\n')) {
             if (!raw.trim())
                 continue;
@@ -151,17 +152,20 @@ export function summarizeFile(fs_stat) {
             catch {
                 continue;
             }
+            lines.push(line);
             if (line.type && !RENDERABLE.has(line.type))
                 continue;
-            const role = line.message?.role;
-            if (role === 'user' || role === 'assistant')
-                turns++;
-            if (!firstPrompt && role === 'user') {
+            if (!firstPrompt && line.message?.role === 'user') {
                 const txt = cleanUserText(contentToText(line.message?.content) || (typeof line.message?.content === 'string' ? line.message.content : ''));
                 if (txt)
                     firstPrompt = txt.replace(/\s+/g, ' ').slice(0, 100);
             }
         }
+        // Count turns EXACTLY as exportSession does — render, then count role
+        // headings — so `transcript list` and `transcript export` can never disagree
+        // (#70). A pure tool-result carrier line renders no heading, so it's not a
+        // turn; the old raw per-line count inflated `list` for any session with tools.
+        turns = countRenderedTurns(renderTranscriptMarkdown(lines));
     }
     catch { /* unreadable */ }
     return { sessionId: sessionIdFromFile(fs_stat.file), file: fs_stat.file, project: fs_stat.project, turns, firstPrompt, mtimeMs: fs_stat.mtimeMs, sizeBytes: fs_stat.sizeBytes };

package/v3/@swarmdo/cli/dist/src/update/checker.d.ts

@@ -23,6 +23,7 @@ export interface UpdateConfig {
     exclude: string[];
 }
 declare const DEFAULT_CONFIG: UpdateConfig;
+export declare function getUpdateType(current: string, latest: string): 'major' | 'minor' | 'patch' | 'none';
 export declare function getInstalledVersion(packageName: string): string | null;
 export declare function checkForUpdates(config?: UpdateConfig): Promise<{
     results: UpdateCheckResult[];

package/v3/@swarmdo/cli/dist/src/update/checker.js

@@ -45,11 +45,16 @@ async function fetchPackageInfo(packageName) {
         return null;
     }
 }
-function getUpdateType(current, latest) {
+export function getUpdateType(current, latest) {
     if (!semver.valid(current) || !semver.valid(latest)) {
         return 'none';
     }
-    if (semver.eq(current, latest)) {
+    // Only a strictly-NEWER latest is an update. Without this guard the
+    // per-field comparisons below misclassify a same-or-OLDER latest: e.g.
+    // current 1.30.2 vs latest 1.29.5 has patch 5 > 2, so it would report
+    // 'patch' and auto-update could DOWNGRADE. `gt` also subsumes the equality
+    // case (eq → not gt → 'none'). (#79)
+    if (!semver.gt(latest, current)) {
         return 'none';
     }
     if (semver.major(latest) > semver.major(current)) {

package/v3/@swarmdo/cli/dist/src/usage/model-efficiency.d.ts

@@ -0,0 +1,29 @@
+/**
+ * model-efficiency.ts — rank models by their EFFECTIVE cost per unit of useful
+ * output in your actual usage.
+ *
+ * A model's list output price is fixed, but what you really pay per output token
+ * also carries the input + cache cost of every request amortized over the output
+ * it produced. A model driven with huge contexts can effectively cost far more
+ * per output token than its sticker price — this surfaces that, per model, from
+ * the same aggregation the `usage models` view already computes.
+ *
+ * Pure: it folds already-summed per-model totals, no transcripts, no clock.
+ */
+import type { UsageTotals } from './transcript-usage.js';
+export interface ModelEfficiency {
+    model: string;
+    costUsd: number;
+    outputTokens: number;
+    /** effective $ per 1,000,000 output tokens (cost / output × 1e6) */
+    costPerMOutput: number;
+}
+/**
+ * Effective cost per 1M output tokens per model, cheapest first. Models with no
+ * cost or no output are dropped (no meaningful ratio). Pure.
+ */
+export declare function computeModelEfficiency(models: Array<{
+    key: string;
+    totals: UsageTotals;
+}>): ModelEfficiency[];
+//# sourceMappingURL=model-efficiency.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/model-efficiency.js

@@ -0,0 +1,28 @@
+/**
+ * model-efficiency.ts — rank models by their EFFECTIVE cost per unit of useful
+ * output in your actual usage.
+ *
+ * A model's list output price is fixed, but what you really pay per output token
+ * also carries the input + cache cost of every request amortized over the output
+ * it produced. A model driven with huge contexts can effectively cost far more
+ * per output token than its sticker price — this surfaces that, per model, from
+ * the same aggregation the `usage models` view already computes.
+ *
+ * Pure: it folds already-summed per-model totals, no transcripts, no clock.
+ */
+/**
+ * Effective cost per 1M output tokens per model, cheapest first. Models with no
+ * cost or no output are dropped (no meaningful ratio). Pure.
+ */
+export function computeModelEfficiency(models) {
+    return models
+        .filter((m) => m.totals.costUsd > 0 && m.totals.outputTokens > 0)
+        .map((m) => ({
+        model: m.key,
+        costUsd: m.totals.costUsd,
+        outputTokens: m.totals.outputTokens,
+        costPerMOutput: (m.totals.costUsd / m.totals.outputTokens) * 1_000_000,
+    }))
+        .sort((a, b) => a.costPerMOutput - b.costPerMOutput || (a.model < b.model ? -1 : 1));
+}
+//# sourceMappingURL=model-efficiency.js.map

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

@@ -81,6 +81,7 @@ ${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))}
+${r.cacheSavingsUsd > 0 ? stat('Cache saved', usd(r.cacheSavingsUsd)) : ''}
 ${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)) : ''}

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

@@ -14,6 +14,7 @@
  * rows the parser already produces. See #47.
  */
 import type { DayRow, ModelRow } from './diff.js';
+import { type TranscriptModelPrice } from './claude-pricing.js';
 export interface ModelShare {
     model: string;
     costUsd: number;
@@ -45,6 +46,8 @@ export interface Reflection {
         costUsd: number;
         totalTokens: number;
     } | null;
+    /** active days whose cost is an outlier vs the median (possible runaways) */
+    spikeDays: SpikeDay[];
     /** models ranked by cost desc (capped to opts.topModels) */
     topModels: ModelShare[];
     /** projects ranked by cost desc (ModelShare.model holds the project path) */
@@ -68,12 +71,16 @@ export interface Reflection {
         secondHalfCost: number;
         direction: 'up' | 'down' | 'flat';
     };
+    /** $ prompt-caching saved this period (vs paying full input rate); 0 if no priced models */
+    cacheSavingsUsd: number;
 }
 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;
+    /** price resolver for cache-savings (injected for tests; default = the real table) */
+    resolvePrice?: (model: string) => TranscriptModelPrice | undefined;
 }
 /** The calendar day after an ISO date (handles month/year rollover). Pure. */
 export declare function nextDay(iso: string): string;
@@ -87,6 +94,25 @@ export declare function monthsBefore(iso: string, n: number): string;
 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;
+export interface SpikeDay {
+    day: string;
+    costUsd: number;
+    /** costUsd / median active-day cost */
+    ratioToMedian: number;
+}
+/**
+ * Days whose cost is an outlier vs the median active-day cost — a heads-up for
+ * runaway sessions. Median (not mean) so the spikes don't inflate the baseline.
+ * Needs ≥3 active days for a meaningful median; a floor keeps trivially-cheap
+ * days from tripping the ratio. Sorted by cost desc. Pure.
+ */
+export declare function detectSpikeDays(days: Array<{
+    day: string;
+    costUsd: number;
+}>, opts?: {
+    minRatio?: number;
+    minCostUsd?: number;
+}): SpikeDay[];
 /** 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). */

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

@@ -13,6 +13,8 @@
  * without touching disk. The command layer in ../commands/usage.ts feeds it the
  * rows the parser already produces. See #47.
  */
+import { modelCacheSavings } from './cache-stats.js';
+import { resolveTranscriptPrice } from './claude-pricing.js';
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 /** The calendar day after an ISO date (handles month/year rollover). Pure. */
 export function nextDay(iso) {
@@ -58,6 +60,27 @@ export function longestStreakOf(days) {
     }
     return best;
 }
+/**
+ * Days whose cost is an outlier vs the median active-day cost — a heads-up for
+ * runaway sessions. Median (not mean) so the spikes don't inflate the baseline.
+ * Needs ≥3 active days for a meaningful median; a floor keeps trivially-cheap
+ * days from tripping the ratio. Sorted by cost desc. Pure.
+ */
+export function detectSpikeDays(days, opts = {}) {
+    const minRatio = opts.minRatio ?? 2.5;
+    const minCostUsd = opts.minCostUsd ?? 0.5;
+    const costs = days.map((d) => d.costUsd).filter((c) => c > 0).sort((a, b) => a - b);
+    if (costs.length < 3)
+        return [];
+    const mid = costs.length >> 1;
+    const median = costs.length % 2 ? costs[mid] : (costs[mid - 1] + costs[mid]) / 2;
+    if (median <= 0)
+        return [];
+    return days
+        .filter((d) => d.costUsd >= minCostUsd && d.costUsd >= minRatio * median)
+        .map((d) => ({ day: d.day, costUsd: d.costUsd, ratioToMedian: d.costUsd / median }))
+        .sort((a, b) => b.costUsd - a.costUsd);
+}
 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).
@@ -145,6 +168,25 @@ export function computeReflection(dayRows, modelRows, from, to, opts = {}, proje
     // 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);
+    // $ saved by prompt caching this period: fold windowed per-model token counts,
+    // then price each via the (injected) resolver. Unpriced models contribute 0.
+    const resolvePrice = opts.resolvePrice ?? resolveTranscriptPrice;
+    const cacheTokens = new Map();
+    for (const r of modelRows) {
+        if (!within(r.day, from, to))
+            continue;
+        const s = cacheTokens.get(r.key) ?? { inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0 };
+        s.inputTokens += r.totals.inputTokens;
+        s.cacheWriteTokens += r.totals.cacheWriteTokens;
+        s.cacheReadTokens += r.totals.cacheReadTokens;
+        cacheTokens.set(r.key, s);
+    }
+    let cacheSavingsUsd = 0;
+    for (const [model, tok] of cacheTokens) {
+        const sv = modelCacheSavings(tok, resolvePrice(model));
+        if (sv !== null)
+            cacheSavingsUsd += sv;
+    }
     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';
@@ -152,6 +194,7 @@ export function computeReflection(dayRows, modelRows, from, to, opts = {}, proje
         period: { from, to, spanDays: spanDays(from, to) },
         totals,
         busiestDay,
+        spikeDays: detectSpikeDays(days.map((r) => ({ day: r.key, costUsd: r.totals.costUsd }))),
         topModels,
         topProjects,
         peakHour: peakHourOf(hourHistogram),
@@ -160,6 +203,7 @@ export function computeReflection(dayRows, modelRows, from, to, opts = {}, proje
         cacheReadPct: inputSide > 0 ? totals.cacheReadTokens / inputSide : 0,
         avgCostPerActiveDay: totals.activeDays > 0 ? totals.costUsd / totals.activeDays : 0,
         trend: { firstHalfCost, secondHalfCost, direction },
+        cacheSavingsUsd,
     };
 }
 //# sourceMappingURL=reflect.js.map

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

@@ -77,7 +77,14 @@ export declare function normalizeDateBound(raw: string | undefined): string | un
  * report must not fail because one session file is mid-write.
  */
 export declare function collectUsage(opts?: CollectOptions): UsageCollection;
-export type UsageDimension = 'day' | 'month' | 'model' | 'project' | 'session';
+export type UsageDimension = 'day' | 'week' | 'month' | 'model' | 'project' | 'session';
+/**
+ * ISO-8601 week key for a `YYYY-MM-DD` date, e.g. '2026-W28'. The week belongs to
+ * the year of its Thursday, so a late-December / early-January week can carry the
+ * neighbouring ISO year (e.g. 2025-12-31 → 2026-W01, 2027-01-01 → 2026-W53).
+ * Keys sort chronologically as strings. Pure.
+ */
+export declare function isoWeekKey(iso: string): string;
 /**
  * Group events along one dimension. Time dimensions sort chronologically;
  * the rest sort by descending cost (what a "top spenders" view wants).

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

@@ -209,8 +209,28 @@ function toUsageEvent(line, project, seen, unpriced) {
         costSource,
     };
 }
+/**
+ * ISO-8601 week key for a `YYYY-MM-DD` date, e.g. '2026-W28'. The week belongs to
+ * the year of its Thursday, so a late-December / early-January week can carry the
+ * neighbouring ISO year (e.g. 2025-12-31 → 2026-W01, 2027-01-01 → 2026-W53).
+ * Keys sort chronologically as strings. Pure.
+ */
+export function isoWeekKey(iso) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    const dayNum = (date.getUTCDay() + 6) % 7; // Mon=0 … Sun=6
+    date.setUTCDate(date.getUTCDate() - dayNum + 3); // Thursday of this week
+    const isoYear = date.getUTCFullYear();
+    const jan4 = new Date(Date.UTC(isoYear, 0, 4)); // Jan 4 is always in week 1
+    const jan4Day = (jan4.getUTCDay() + 6) % 7;
+    const week1Monday = new Date(jan4);
+    week1Monday.setUTCDate(jan4.getUTCDate() - jan4Day);
+    const week = 1 + Math.round((date.getTime() - week1Monday.getTime()) / (7 * 86_400_000));
+    return `${isoYear}-W${String(week).padStart(2, '0')}`;
+}
 const DIMENSION_KEY = {
     day: (e) => e.dateKey,
+    week: (e) => isoWeekKey(e.dateKey),
     month: (e) => e.monthKey,
     model: (e) => e.model,
     project: (e) => e.project,
@@ -253,7 +273,7 @@ export function aggregateUsage(events, dimension) {
         addEvent(t, e);
     }
     const rows = Array.from(groups.entries()).map(([key, totals]) => ({ key, totals }));
-    if (dimension === 'day' || dimension === 'month') {
+    if (dimension === 'day' || dimension === 'week' || dimension === 'month') {
         rows.sort((a, b) => a.key.localeCompare(b.key));
     }
     else {

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

@@ -7,6 +7,28 @@
  * (`swarmdo sbom | …`, `pack`, `compact`, `redact`) truncates at the ~64 KiB
  * pipe buffer. Awaiting the write callback guarantees the data reached the OS
  * before we hand control back. For a TTY (synchronous) this is a no-op await.
+ *
+ * Broken-pipe (EPIPE) handling: when the reader closes the pipe early (`… |
+ * head`), Node emits an `'error'` event on the stdout Socket — often
+ * ASYNCHRONOUSLY, after our write callback has already fired — and an unhandled
+ * `'error'` event crashes the process with a raw stack trace. A per-write
+ * listener therefore doesn't cover it (it's gone by the time the async error
+ * lands). So we install ONE persistent EPIPE guard per stream that swallows the
+ * broken pipe (normal producer termination) while still rethrowing any other
+ * stream error, and additionally resolve the write promise on an EPIPE callback.
+ * The `stream` param is injectable so this is unit-testable without a subprocess.
+ */
+/** The subset of a writable stream writeStdout needs (process.stdout satisfies it). */
+export interface WritableLike {
+    write(data: string, cb: (err?: Error | null) => void): boolean;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+}
+/**
+ * Install (once per stream) a persistent `'error'` handler that swallows EPIPE —
+ * a closed reader is normal termination for a Unix producer, not a crash — and
+ * rethrows everything else so genuine stream errors still surface. Exported for
+ * the CLI entry point to arm stdout/stderr before any write happens.
  */
-export declare function writeStdout(data: string): Promise<void>;
+export declare function guardStreamEpipe(stream: WritableLike): void;
+export declare function writeStdout(data: string, stream?: WritableLike): Promise<void>;
 //# sourceMappingURL=stdout.d.ts.map