swarmdo 1.29.0 → 1.37.0

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

@@ -14,12 +14,21 @@
  */
 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';
+import { computeModelEfficiency } from '../usage/model-efficiency.js';
+import { detectSpikeDays } from '../usage/reflect.js';
 const VIEWS = {
     daily: { dimension: 'day', label: 'Date' },
+    weekly: { dimension: 'week', label: 'ISO week' },
     monthly: { dimension: 'month', label: 'Month' },
     models: { dimension: 'model', label: 'Model' },
     projects: { dimension: 'project', label: 'Project' },
@@ -376,6 +385,152 @@ 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.inputTokens += e.inputTokens; // needed for cache-savings pricing
+        row.totals.cacheWriteTokens += e.cacheWriteTokens;
+        row.totals.cacheReadTokens += e.cacheReadTokens;
+        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)`)}`);
+    if (r.spikeDays.length) {
+        const top = r.spikeDays.slice(0, 3).map((s) => `${s.day} ${fmtCost(s.costUsd)} (${s.ratioToMedian.toFixed(1)}×)`).join(', ');
+        output.writeln(`  Spike days         ${top}  ${output.dim('vs median')}`);
+    }
+    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 (r.cacheSavingsUsd > 0)
+        output.writeln(`  Cache saved        ${fmtCost(r.cacheSavingsUsd)}  ${output.dim('vs no caching')}`);
+    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 +564,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 +596,51 @@ 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 === 'models') {
+        // Effective cost per unit of useful output — surfaces models made expensive
+        // by heavy input/cache overhead, beyond their sticker output price.
+        const eff = computeModelEfficiency(aggregateUsage(collection.events, 'model'));
+        if (eff.length >= 2) {
+            const best = eff[0];
+            const worst = eff[eff.length - 1];
+            output.writeln(output.dim(`effective $/1M output — best ${best.model} ${fmtCost(best.costPerMOutput)}, worst ${worst.model} ${fmtCost(worst.costPerMOutput)}`));
+        }
+    }
+    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)`));
+        }
+    }
+    if (viewName === 'sessions') {
+        // Outlier-session detection: a single runaway session (one work unit) is more
+        // actionable than a spike day. Run the same median-ratio detector over ALL
+        // sessions (not the top-N display slice) so the baseline is representative.
+        const spikes = detectSpikeDays(aggregateUsage(collection.events, 'session').map((r) => ({ day: r.key, costUsd: r.totals.costUsd })));
+        if (spikes.length > 0) {
+            const top = spikes.slice(0, 3).map((s) => `${s.day} ${fmtCost(s.costUsd)} (${s.ratioToMedian.toFixed(1)}× median)`).join(', ');
+            output.writeln(output.dim(`outlier sessions: ${top}`));
+        }
+    }
     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);
@@ -449,18 +651,21 @@ async function run(ctx) {
 export const usageCommand = {
     name: 'usage',
     aliases: ['cost'],
-    description: 'Claude Code token & cost analytics from local transcripts (daily|monthly|models|projects|sessions)',
+    description: 'Claude Code token & cost analytics from local transcripts (daily|weekly|monthly|models|projects|sessions)',
     options: [
         { name: 'since', description: 'inclusive start date (YYYY-MM-DD or YYYYMMDD)', type: 'string' },
         { name: 'until', description: 'inclusive end date (YYYY-MM-DD or YYYYMMDD)', type: 'string' },
         { 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 weekly', description: 'Spend grouped by ISO week' },
         { 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/comms/mailbox.d.ts

@@ -0,0 +1,88 @@
+/**
+ * comms/mailbox.ts — pure engine for the cross-session agent mailbox (#44).
+ *
+ * A shared `.swarmdo/comms/store.json` lets any Claude Code session on the same
+ * repo/machine leave messages for another by session name ("multiplayer
+ * swarms"). This module is the pure, I/O-free core: the message model, immutable
+ * add, inbox filtering/ordering, read-state tracking, and retention. The command
+ * layer (`swarmdo comms`) supplies id/timestamp generation and fs persistence.
+ *
+ * A message addressed to `all` (case-insensitive) is a broadcast — it appears in
+ * every session's inbox.
+ */
+export interface Message {
+    id: string;
+    from: string;
+    to: string;
+    subject: string;
+    body: string;
+    /** ISO-8601 creation time. */
+    createdAt: string;
+    read: boolean;
+}
+export interface Mailbox {
+    messages: Record<string, Message>;
+    version: string;
+}
+/** The broadcast recipient — a message to this address reaches every inbox. */
+export declare const BROADCAST = "all";
+export declare function emptyMailbox(): Mailbox;
+/**
+ * Build a message. `id` and `createdAt` are injected (not generated here) so the
+ * engine stays pure and unit-testable; the command layer supplies a crypto id
+ * and the wall clock. from/to/subject are trimmed; a blank subject becomes
+ * '(no subject)'.
+ */
+export declare function createMessage(opts: {
+    id: string;
+    from: string;
+    to: string;
+    body: string;
+    createdAt: string;
+    subject?: string;
+}): Message;
+/** Immutably add a message. Same id is a no-op (idempotent delivery). */
+export declare function addMessage(box: Mailbox, msg: Message): Mailbox;
+export interface InboxFilter {
+    /** Recipient session name; matches this recipient plus `all` broadcasts. Omit for every message. */
+    to?: string;
+    /** Only messages from this sender (case-insensitive). */
+    from?: string;
+    /** Only unread messages. */
+    unreadOnly?: boolean;
+    /** Only messages created strictly after this ISO timestamp. */
+    since?: string;
+}
+/**
+ * Filter the mailbox to an inbox view, sorted NEWEST-FIRST (tiebreak by id).
+ * A `to` filter matches the named recipient and `all` broadcasts.
+ */
+export declare function filterInbox(box: Mailbox, filter?: InboxFilter): Message[];
+/** Count unread messages for a recipient (includes `all` broadcasts). */
+export declare function unreadCount(box: Mailbox, to?: string): number;
+/**
+ * Render a set of messages as a compact context block for hook delivery — the
+ * "surface new mail without polling" path. Returns '' for no messages (caller
+ * injects nothing). Each body is whitespace-collapsed and capped at maxBodyChars.
+ */
+export declare function renderInboxContext(messages: Message[], opts?: {
+    header?: string;
+    maxBodyChars?: number;
+}): string;
+/** Immutably mark the given ids read. Returns the new box + how many flipped unread→read. */
+export declare function markRead(box: Mailbox, ids: string[]): {
+    box: Mailbox;
+    marked: number;
+};
+/**
+ * Retention: drop READ messages older than maxAgeMs, then — if still over
+ * maxCount — drop the oldest READ messages until at the cap. UNREAD messages are
+ * never dropped (delivery is guaranteed until acknowledged). `nowMs` is injected
+ * to keep this pure.
+ */
+export declare function pruneMailbox(box: Mailbox, opts: {
+    maxAgeMs?: number;
+    maxCount?: number;
+    nowMs: number;
+}): Mailbox;
+//# sourceMappingURL=mailbox.d.ts.map

package/v3/@swarmdo/cli/dist/src/comms/mailbox.js

@@ -0,0 +1,138 @@
+/**
+ * comms/mailbox.ts — pure engine for the cross-session agent mailbox (#44).
+ *
+ * A shared `.swarmdo/comms/store.json` lets any Claude Code session on the same
+ * repo/machine leave messages for another by session name ("multiplayer
+ * swarms"). This module is the pure, I/O-free core: the message model, immutable
+ * add, inbox filtering/ordering, read-state tracking, and retention. The command
+ * layer (`swarmdo comms`) supplies id/timestamp generation and fs persistence.
+ *
+ * A message addressed to `all` (case-insensitive) is a broadcast — it appears in
+ * every session's inbox.
+ */
+/** The broadcast recipient — a message to this address reaches every inbox. */
+export const BROADCAST = 'all';
+export function emptyMailbox() {
+    return { messages: {}, version: '1.0.0' };
+}
+/**
+ * Build a message. `id` and `createdAt` are injected (not generated here) so the
+ * engine stays pure and unit-testable; the command layer supplies a crypto id
+ * and the wall clock. from/to/subject are trimmed; a blank subject becomes
+ * '(no subject)'.
+ */
+export function createMessage(opts) {
+    return {
+        id: opts.id,
+        from: (opts.from || '').trim() || 'unknown',
+        to: (opts.to || '').trim(),
+        subject: (opts.subject || '').trim() || '(no subject)',
+        body: opts.body ?? '',
+        createdAt: opts.createdAt,
+        read: false,
+    };
+}
+/** Immutably add a message. Same id is a no-op (idempotent delivery). */
+export function addMessage(box, msg) {
+    if (box.messages[msg.id])
+        return box;
+    return { ...box, messages: { ...box.messages, [msg.id]: msg } };
+}
+const eqCI = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+/**
+ * Filter the mailbox to an inbox view, sorted NEWEST-FIRST (tiebreak by id).
+ * A `to` filter matches the named recipient and `all` broadcasts.
+ */
+export function filterInbox(box, filter = {}) {
+    const all = Object.values(box.messages || {});
+    const filtered = all.filter((m) => {
+        if (filter.to !== undefined && !(eqCI(m.to, filter.to) || eqCI(m.to, BROADCAST)))
+            return false;
+        if (filter.from !== undefined && !eqCI(m.from, filter.from))
+            return false;
+        if (filter.unreadOnly && m.read)
+            return false;
+        if (filter.since !== undefined && !(m.createdAt > filter.since))
+            return false;
+        return true;
+    });
+    return filtered.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : a.id.localeCompare(b.id)));
+}
+/** Count unread messages for a recipient (includes `all` broadcasts). */
+export function unreadCount(box, to) {
+    return filterInbox(box, { to, unreadOnly: true }).length;
+}
+/**
+ * Render a set of messages as a compact context block for hook delivery — the
+ * "surface new mail without polling" path. Returns '' for no messages (caller
+ * injects nothing). Each body is whitespace-collapsed and capped at maxBodyChars.
+ */
+export function renderInboxContext(messages, opts = {}) {
+    if (!messages || messages.length === 0)
+        return '';
+    const header = opts.header ?? '## 📬 New messages (swarmdo comms)';
+    const maxBody = opts.maxBodyChars ?? 500;
+    const lines = [
+        header,
+        `You have ${messages.length} new message${messages.length === 1 ? '' : 's'} from other sessions:`,
+        '',
+    ];
+    for (const m of messages) {
+        const body = (m.body || '').replace(/\s+/g, ' ').trim();
+        const trimmed = body.length > maxBody ? body.slice(0, maxBody).trimEnd() + '…' : body;
+        lines.push(`- **from ${m.from}** — ${m.subject}: ${trimmed}`);
+    }
+    return lines.join('\n');
+}
+/** Immutably mark the given ids read. Returns the new box + how many flipped unread→read. */
+export function markRead(box, ids) {
+    const idSet = new Set(ids);
+    let marked = 0;
+    const messages = {};
+    for (const [id, m] of Object.entries(box.messages || {})) {
+        if (idSet.has(id) && !m.read) {
+            messages[id] = { ...m, read: true };
+            marked++;
+        }
+        else {
+            messages[id] = m;
+        }
+    }
+    return { box: marked ? { ...box, messages } : box, marked };
+}
+/**
+ * Retention: drop READ messages older than maxAgeMs, then — if still over
+ * maxCount — drop the oldest READ messages until at the cap. UNREAD messages are
+ * never dropped (delivery is guaranteed until acknowledged). `nowMs` is injected
+ * to keep this pure.
+ */
+export function pruneMailbox(box, opts) {
+    const entries = Object.values(box.messages || {});
+    const keep = new Map();
+    const droppableRead = [];
+    for (const m of entries) {
+        if (!m.read) {
+            keep.set(m.id, m);
+            continue;
+        }
+        const ageMs = opts.nowMs - Date.parse(m.createdAt);
+        if (opts.maxAgeMs !== undefined && Number.isFinite(ageMs) && ageMs > opts.maxAgeMs)
+            continue; // aged out
+        keep.set(m.id, m);
+        droppableRead.push(m);
+    }
+    if (opts.maxCount !== undefined && keep.size > opts.maxCount) {
+        // Drop oldest read first until at the cap (unread are never in droppableRead).
+        droppableRead.sort((a, b) => (a.createdAt < b.createdAt ? -1 : 1));
+        for (const m of droppableRead) {
+            if (keep.size <= opts.maxCount)
+                break;
+            keep.delete(m.id);
+        }
+    }
+    const messages = {};
+    for (const [id, m] of keep)
+        messages[id] = m;
+    return { ...box, messages };
+}
+//# sourceMappingURL=mailbox.js.map

package/v3/@swarmdo/cli/dist/src/comms/store.d.ts

@@ -0,0 +1,21 @@
+/**
+ * comms/store.ts — fs persistence + identity for the cross-session mailbox (#44).
+ *
+ * Shared by the `swarmdo comms` CLI command AND the comms_send/comms_inbox MCP
+ * tools so both read/write the SAME `.swarmdo/comms/store.json` under a given
+ * project root. The pure message logic lives in mailbox.ts; this is only I/O.
+ */
+import { type Mailbox } from './mailbox.js';
+/** Retention applied opportunistically on send: keep read messages ≤30d, ≤500 total. */
+export declare const RETENTION: {
+    maxAgeMs: number;
+    maxCount: number;
+};
+export declare function storePath(cwd: string): string;
+export declare function loadMailbox(cwd: string): Mailbox;
+export declare function saveMailbox(cwd: string, box: Mailbox): void;
+/** This session's name: explicit override → SWARMDO_SESSION → hostname → "me". */
+export declare function resolveSelf(flag?: unknown): string;
+/** Crypto-strong message id. */
+export declare function newMessageId(): string;
+//# sourceMappingURL=store.d.ts.map

package/v3/@swarmdo/cli/dist/src/comms/store.js

@@ -0,0 +1,44 @@
+/**
+ * comms/store.ts — fs persistence + identity for the cross-session mailbox (#44).
+ *
+ * Shared by the `swarmdo comms` CLI command AND the comms_send/comms_inbox MCP
+ * tools so both read/write the SAME `.swarmdo/comms/store.json` under a given
+ * project root. The pure message logic lives in mailbox.ts; this is only I/O.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { hostname } from 'node:os';
+import { emptyMailbox } from './mailbox.js';
+const STORE_REL = join('.swarmdo', 'comms', 'store.json');
+/** Retention applied opportunistically on send: keep read messages ≤30d, ≤500 total. */
+export const RETENTION = { maxAgeMs: 30 * 24 * 3600 * 1000, maxCount: 500 };
+export function storePath(cwd) {
+    return join(cwd, STORE_REL);
+}
+export function loadMailbox(cwd) {
+    try {
+        const p = storePath(cwd);
+        if (existsSync(p))
+            return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        /* corrupt/missing → fresh mailbox */
+    }
+    return emptyMailbox();
+}
+export function saveMailbox(cwd, box) {
+    const p = storePath(cwd);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(box, null, 2) + '\n', 'utf-8');
+}
+/** This session's name: explicit override → SWARMDO_SESSION → hostname → "me". */
+export function resolveSelf(flag) {
+    const f = typeof flag === 'string' ? flag.trim() : '';
+    return f || (process.env.SWARMDO_SESSION || '').trim() || hostname() || 'me';
+}
+/** Crypto-strong message id. */
+export function newMessageId() {
+    return 'msg_' + randomBytes(6).toString('hex');
+}
+//# sourceMappingURL=store.js.map

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

@@ -60,7 +60,10 @@ function collapseRepeats(lines, minRun) {
             j++;
         const run = j - i;
         out.push(lines[i]);
-        if (run >= minRun)
+        // `run > 1` guards the degenerate minRun=1 case: a single (non-repeated)
+        // line is a "run of 1" and must never get a `(×1)` marker — only genuine
+        // repeats (2+) collapse.
+        if (run > 1 && run >= minRun)
             out.push(`  … (×${run})`);
         else
             for (let k = 1; k < run; k++)

package/v3/@swarmdo/cli/dist/src/compact-snapshot/compact-snapshot.js

@@ -23,10 +23,15 @@ const DEFAULT_MAX_FILES = 12;
 export function porcelainPath(line) {
     if (!line || line.length < 4)
         return null;
+    const status = line.slice(0, 2); // XY status code
     let rest = line.slice(3); // strip the 2 status chars + the separating space
-    const arrow = rest.indexOf(' -> ');
-    if (arrow >= 0)
-        rest = rest.slice(arrow + 4); // rename/copy → destination path
+    // Only a rename/copy (status R or C) uses `<old> -> <new>`; for any other
+    // status a literal ` -> ` is part of the real filename and must NOT be split.
+    if (/[RC]/.test(status)) {
+        const arrow = rest.indexOf(' -> ');
+        if (arrow >= 0)
+            rest = rest.slice(arrow + 4); // destination path
+    }
     rest = rest.trim();
     if (rest.startsWith('"') && rest.endsWith('"') && rest.length >= 2) {
         rest = rest.slice(1, -1); // unwrap git's quoted path (escapes left as-is)

package/v3/@swarmdo/cli/dist/src/config-lint/lint.d.ts

@@ -31,7 +31,7 @@ export declare function lintSettingsHooks(file: string, obj: unknown): Finding[]
 /** .mcp.json: server entry SHAPES only (mcp doctor probes the runtime). */
 export declare function lintMcpConfig(file: string, obj: unknown): Finding[];
 /** Pre-1.4 layout leftovers: flat commands / unprefixed skill duplicates. */
-export declare function lintLegacyLayout(commandsRoot: string[], skills: string[]): Finding[];
+export declare function lintLegacyLayout(commandsRoot: string[], skills: string[], sdoCommands?: string[]): Finding[];
 export interface LintInput {
     swarmdoConfig?: {
         file: string;
@@ -46,6 +46,8 @@ export interface LintInput {
         raw: string | null;
     };
     commandsRoot?: string[];
+    /** entries under `.claude/commands/sDo/` — used to identify flat pre-1.4 twins */
+    sdoCommands?: string[];
     skills?: string[];
 }
 export interface LintReport {

package/v3/@swarmdo/cli/dist/src/config-lint/lint.js

@@ -158,11 +158,18 @@ export function lintMcpConfig(file, obj) {
     return out;
 }
 /** Pre-1.4 layout leftovers: flat commands / unprefixed skill duplicates. */
-export function lintLegacyLayout(commandsRoot, skills) {
+export function lintLegacyLayout(commandsRoot, skills, sdoCommands = []) {
     const out = [];
-    const flat = commandsRoot.filter((n) => n !== 'sDo');
+    // A flat command is a pre-1.4 swarmdo leftover ONLY if the same command also
+    // exists under sDo/ today (a twin) — mirroring the skill twin-check below.
+    // `.claude/commands/` is Claude Code's shared, ecosystem-wide slash-command
+    // dir, so a user's own command namespace or another plugin's coexisting with
+    // sDo/ must NOT be flagged merely for not being `sDo` (that was #66).
+    const base = (n) => n.replace(/\.md$/, '');
+    const sdoBase = new Set(sdoCommands.map(base));
+    const flat = commandsRoot.filter((n) => n !== 'sDo' && sdoBase.has(base(n)));
     if (flat.length > 0) {
-        out.push(f('.claude/commands', 'warn', 'pre-1.4-commands', `${flat.length} entr${flat.length === 1 ? 'y' : 'ies'} outside the sDo/ namespace (${flat.slice(0, 5).join(', ')}${flat.length > 5 ? ', …' : ''}) — swarmdo commands moved to /sDo:* in v1.4.0; re-run \`swarmdo init --force\` to migrate swarmdo-owned ones`));
+        out.push(f('.claude/commands', 'warn', 'pre-1.4-commands', `${flat.length} swarmdo command${flat.length === 1 ? '' : 's'} left flat outside the sDo/ namespace (${flat.slice(0, 5).join(', ')}${flat.length > 5 ? ', …' : ''}) — swarmdo commands moved to /sDo:* in v1.4.0; re-run \`swarmdo init --force\` to migrate them`));
     }
     const skillSet = new Set(skills);
     const dupes = skills.filter((s) => !s.startsWith('sdo-') && skillSet.has(`sdo-${s}`));
@@ -186,7 +193,7 @@ export function lintAll(input) {
         const { obj, findings: jf } = lintJson(input.mcpConfig.file, input.mcpConfig.raw);
         findings.push(...jf, ...lintMcpConfig(input.mcpConfig.file, obj));
     }
-    findings.push(...lintLegacyLayout(input.commandsRoot ?? [], input.skills ?? []));
+    findings.push(...lintLegacyLayout(input.commandsRoot ?? [], input.skills ?? [], input.sdoCommands ?? []));
     return {
         findings,
         errors: findings.filter((x) => x.severity === 'error').length,