swarmdo 1.29.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/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/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.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