swarmdo 1.30.0 → 1.45.0

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

@@ -759,6 +759,60 @@ const graphCommand = {
         return { success: true };
     }
 };
+// Doctor subcommand — classify blocked tasks live vs dead + a global deadlock
+// verdict (task-deps.ts::taskDagHealth). Airflow's upstream_failed + DAG
+// deadlock detection: surfaces a task that can NEVER run because a prerequisite
+// failed/was cancelled/is missing, and a whole-graph stall a dispatch loop would
+// otherwise spin on forever.
+const doctorCommand = {
+    name: 'doctor',
+    aliases: ['health'],
+    description: 'Diagnose the task DAG: which blocked tasks can still run (live) vs are permanently stuck because a dependency failed/was cancelled/is missing (dead), and whether the whole graph is deadlocked',
+    options: [
+        { name: 'json', description: 'Machine-readable output', type: 'boolean', default: false },
+        { name: 'ci', description: 'Exit 1 if the DAG is deadlocked or any task is permanently (dead) blocked — gate a dispatch loop', type: 'boolean', default: false }
+    ],
+    examples: [
+        { command: 'swarmdo task doctor', description: 'Show live-blocked vs dead-blocked tasks and any deadlock' },
+        { command: 'swarmdo task doctor --ci', description: 'Fail (exit 1) when the task graph is stuck' }
+    ],
+    action: async (ctx) => {
+        const { loadTaskStore } = await import('../mcp-tools/task-tools.js');
+        const { taskDagHealth } = await import('../mcp-tools/task-deps.js');
+        const store = loadTaskStore(ctx.cwd);
+        const health = taskDagHealth(store);
+        const stuck = health.deadlocked || health.deadBlocked.length > 0;
+        const code = ctx.flags.ci === true && stuck ? 1 : 0;
+        if (ctx.flags.json === true) {
+            output.printJson({
+                deadlocked: health.deadlocked,
+                liveBlocked: health.liveBlocked.map(t => t.taskId),
+                deadBlocked: health.deadBlocked.map(d => ({ taskId: d.task.taskId, rootCause: d.rootCause })),
+            });
+            return { success: code === 0, exitCode: code, data: health };
+        }
+        output.writeln();
+        if (health.deadlocked) {
+            output.writeln(output.error('⚠ DEADLOCKED') + output.dim(' — pending work exists but nothing is ready and nothing is running'));
+            output.writeln();
+        }
+        output.writeln(output.bold(`Live-blocked (${health.liveBlocked.length})`) + output.dim(' — waiting on deps that can still complete'));
+        for (const t of health.liveBlocked) {
+            output.writeln(`  ${output.dim('○')} ${t.taskId}  ${t.description.slice(0, 60)}`);
+        }
+        output.writeln();
+        output.writeln(output.bold(`Dead-blocked (${health.deadBlocked.length})`) + output.dim(' — a prerequisite failed/was cancelled/is missing; will NEVER run without intervention'));
+        for (const d of health.deadBlocked) {
+            output.writeln(`  ${output.error('✗')} ${d.task.taskId} ⇐ dead: ${d.rootCause.join(', ') || '(cycle)'}`);
+        }
+        if (!stuck) {
+            output.writeln();
+            output.printSuccess('task graph healthy — no permanent blocks or deadlock');
+        }
+        output.writeln();
+        return { success: code === 0, exitCode: code, data: health };
+    }
+};
 // parse-prd subcommand — decompose a PRD/spec doc into the task DAG (Task Master
 // parity). The LLM decomposition lives in ../task/parse-prd.ts (injectable +
 // unit-tested); this layer gates the billable call and creates the linked tasks.
@@ -890,7 +944,7 @@ const parsePrdCommand = {
 export const taskCommand = {
     name: 'task',
     description: 'Task management commands',
-    subcommands: [createCommand, parsePrdCommand, listCommand, statusCommand, cancelCommand, assignCommand, retryCommand, dispatchCommand, readyCommand, graphCommand],
+    subcommands: [createCommand, parsePrdCommand, listCommand, statusCommand, cancelCommand, assignCommand, retryCommand, dispatchCommand, readyCommand, graphCommand, doctorCommand],
     options: [],
     examples: [
         { command: 'swarmdo task create -t implementation -d "Add user auth"', description: 'Create a task' },
@@ -917,7 +971,8 @@ export const taskCommand = {
             `${output.highlight('assign')}  - Assign task to agent(s)`,
             `${output.highlight('retry')}   - Retry a failed task`,
             `${output.highlight('ready')}   - List ready vs dependency-blocked tasks`,
-            `${output.highlight('graph')}   - Show the dependency graph`
+            `${output.highlight('graph')}   - Show the dependency graph`,
+            `${output.highlight('doctor')}  - Diagnose live vs dead blocks + deadlock (--ci gates)`
         ]);
         output.writeln();
         output.writeln('Run "swarmdo task <subcommand> --help" for subcommand help');

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

@@ -24,8 +24,11 @@ import { forecastWindow, parseRateLimits, worstStatus, formatForecast, formatLim
 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' },
@@ -401,6 +404,9 @@ function runReflectView(ctx, collection) {
         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)
@@ -439,9 +445,15 @@ function runReflectView(ctx, collection) {
     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)`)}`);
     }
@@ -597,6 +609,16 @@ async function run(ctx) {
     }
     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());
@@ -609,6 +631,16 @@ async function run(ctx) {
             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);
@@ -619,7 +651,7 @@ 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' },
@@ -630,6 +662,7 @@ export const usageCommand = {
     ],
     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' },

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/agents-lint.d.ts

@@ -0,0 +1,30 @@
+/**
+ * agents-lint.ts — static validation of Claude Code subagent definitions
+ * (`.claude/agents/*.md`).
+ *
+ * Each subagent file is YAML frontmatter (`name` + `description` required;
+ * `tools`, `model` optional) plus a system-prompt body. Claude Code SILENTLY
+ * ignores a subagent whose frontmatter is malformed, whose `name` collides with
+ * another file, or whose `model` is invalid — so "why isn't my subagent
+ * loading?" is an undebuggable footgun, and users mass-copy these files from
+ * large community collections where typos ride along. This catches those
+ * before CC does.
+ *
+ * Pure: parsed text in, findings out — same `Finding` shape + report machinery
+ * as the rest of config-lint; the command layer only reads files.
+ */
+import type { Finding } from './lint.js';
+/** Models a Claude Code subagent `model:` field may name. */
+export declare const AGENT_MODELS: string[];
+/** Lint ONE subagent file's raw text. Pure. */
+export declare function lintAgentFile(file: string, raw: string): Finding[];
+export interface AgentFile {
+    file: string;
+    raw: string;
+}
+/**
+ * Lint a set of subagent files: every per-file rule PLUS cross-file duplicate
+ * `name` detection (Claude Code loads only one of a colliding pair). Pure.
+ */
+export declare function lintAgents(files: AgentFile[]): Finding[];
+//# sourceMappingURL=agents-lint.d.ts.map

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

@@ -0,0 +1,87 @@
+/**
+ * agents-lint.ts — static validation of Claude Code subagent definitions
+ * (`.claude/agents/*.md`).
+ *
+ * Each subagent file is YAML frontmatter (`name` + `description` required;
+ * `tools`, `model` optional) plus a system-prompt body. Claude Code SILENTLY
+ * ignores a subagent whose frontmatter is malformed, whose `name` collides with
+ * another file, or whose `model` is invalid — so "why isn't my subagent
+ * loading?" is an undebuggable footgun, and users mass-copy these files from
+ * large community collections where typos ride along. This catches those
+ * before CC does.
+ *
+ * Pure: parsed text in, findings out — same `Finding` shape + report machinery
+ * as the rest of config-lint; the command layer only reads files.
+ */
+import { parse as parseYaml } from 'yaml';
+const f = (file, severity, rule, message) => ({ file, severity, rule, message });
+/** Models a Claude Code subagent `model:` field may name. */
+export const AGENT_MODELS = ['sonnet', 'opus', 'haiku', 'inherit'];
+// Leading (optional BOM) `---` fence, YAML body (non-greedy) up to a closing
+// `---` on its own line, then the optional system-prompt body. CRLF-tolerant.
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+function parseAgent(raw) {
+    const m = raw.replace(/^\uFEFF/, "").match(FRONTMATTER_RE);
+    if (!m)
+        return { meta: null, body: '', malformed: 'no YAML frontmatter block (a subagent file must start with `---` … `---`)' };
+    const body = m[2] ?? '';
+    let fm;
+    try {
+        fm = parseYaml(m[1]);
+    }
+    catch (e) {
+        return { meta: null, body, malformed: `frontmatter is not valid YAML: ${e.message}` };
+    }
+    if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) {
+        return { meta: null, body, malformed: 'frontmatter must be a YAML mapping of key: value' };
+    }
+    return { meta: fm, body };
+}
+function lintParsed(file, p) {
+    if (p.malformed)
+        return [f(file, 'error', 'agent-malformed-frontmatter', p.malformed)];
+    const out = [];
+    const meta = p.meta;
+    if (typeof meta.name !== 'string' || meta.name.trim() === '') {
+        out.push(f(file, 'error', 'agent-missing-name', 'frontmatter is missing a non-empty `name`'));
+    }
+    if (typeof meta.description !== 'string' || meta.description.trim() === '') {
+        out.push(f(file, 'error', 'agent-missing-description', 'frontmatter is missing a non-empty `description` (Claude Code routes to a subagent by its description)'));
+    }
+    if (meta.model !== undefined && !AGENT_MODELS.includes(String(meta.model))) {
+        out.push(f(file, 'error', 'agent-bad-model', `model "${String(meta.model)}" is not one of: ${AGENT_MODELS.join(', ')}`));
+    }
+    if (p.body.trim() === '') {
+        out.push(f(file, 'warn', 'agent-empty-body', 'no system prompt below the frontmatter — the subagent has no instructions'));
+    }
+    return out;
+}
+/** Lint ONE subagent file's raw text. Pure. */
+export function lintAgentFile(file, raw) {
+    return lintParsed(file, parseAgent(raw));
+}
+/**
+ * Lint a set of subagent files: every per-file rule PLUS cross-file duplicate
+ * `name` detection (Claude Code loads only one of a colliding pair). Pure.
+ */
+export function lintAgents(files) {
+    const out = [];
+    const nameToFiles = new Map();
+    for (const { file, raw } of files) {
+        const p = parseAgent(raw);
+        out.push(...lintParsed(file, p));
+        const name = p.meta && typeof p.meta.name === 'string' ? p.meta.name.trim() : '';
+        if (name) {
+            const arr = nameToFiles.get(name) ?? [];
+            arr.push(file);
+            nameToFiles.set(name, arr);
+        }
+    }
+    for (const [name, group] of nameToFiles) {
+        if (group.length > 1) {
+            out.push(f(group[0], 'error', 'agent-duplicate-name', `subagent name "${name}" is declared by ${group.length} files (${group.join(', ')}) — Claude Code loads only one; rename the rest`));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=agents-lint.js.map

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

@@ -17,6 +17,7 @@ export interface Finding {
 }
 export declare const TOPOLOGIES: string[];
 export declare const MEMORY_BACKENDS: string[];
+import { type AgentFile } from './agents-lint.js';
 export declare const KNOWN_CONFIG_KEYS: string[];
 export declare const HOOK_EVENTS: string[];
 /** Parse a JSON file's raw text; a null raw means "file absent" (fine). */
@@ -31,7 +32,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,7 +47,11 @@ 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[];
+    /** `.claude/agents/*.md` subagent definitions (raw text per file) */
+    agentFiles?: AgentFile[];
 }
 export interface LintReport {
     findings: Finding[];