swarmdo 1.30.0 → 1.45.0

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

@@ -12,6 +12,7 @@ const f = (file, severity, rule, message) => ({ file, severity, rule, message })
 export const TOPOLOGIES = ['hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive'];
 export const MEMORY_BACKENDS = ['agentdb', 'sqlite', 'hybrid', 'memory'];
 import { parseOpenRouterConfig } from '../providers/openrouter-config.js';
+import { lintAgents } from './agents-lint.js';
 export const KNOWN_CONFIG_KEYS = ['topology', 'maxAgents', 'strategy', 'consensus', 'memory', 'memoryBackend', 'hnsw', 'neural', 'embeddings', 'providers', 'mcp', 'logging', 'daemon', 'hooks', 'version', 'openrouter', '$schema'];
 // Current Claude Code hook events (source: code.claude.com/docs/en/hooks).
 // Kept in sync with the runtime; a stale list here false-warns on valid hooks.
@@ -158,11 +159,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 +194,9 @@ 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 ?? []));
+    if (input.agentFiles?.length)
+        findings.push(...lintAgents(input.agentFiles));
     return {
         findings,
         errors: findings.filter((x) => x.severity === 'error').length,

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

@@ -0,0 +1,56 @@
+/**
+ * coupling.ts — temporal (co-change) coupling mined from git history.
+ *
+ * "Which files change together?" — the EMPIRICAL complement to `affected`'s
+ * STATIC import graph. Files that repeatedly land in the same commit are
+ * coupled in practice even when no import edge connects them (a JSON schema and
+ * its TS type, a serializer/deserializer split across modules, a feature flag
+ * and its consumers, a doc that must track an API). Surfacing that lets an agent
+ * or a maintainer catch the edit they'd otherwise forget.
+ *
+ * This is code-maat's `coupling`/`soc` analysis (Tornhill, *Your Code as a
+ * Crime Scene*), productized as "Change Coupling" in CodeScene. The scoring core
+ * is a pure fold over the SAME `git log --numstat` dump `hotspots` already
+ * parses, so it reuses that Commit type + parseGitLog and is unit-tested without
+ * a repo.
+ */
+import type { Commit } from '../hotspots/hotspots.js';
+export interface CouplingPair {
+    /** the lexicographically smaller path of the pair */
+    a: string;
+    /** the lexicographically larger path of the pair */
+    b: string;
+    /** commits touching BOTH a and b */
+    shared: number;
+    /** commits touching a (within the file cap) */
+    aCommits: number;
+    /** commits touching b (within the file cap) */
+    bCommits: number;
+    /** shared / min(aCommits, bCommits) ∈ (0,1]; 1.0 = they never move apart */
+    degree: number;
+}
+export interface CouplingOptions {
+    /** drop pairs sharing fewer than this many commits (default 2) — support threshold */
+    minShared?: number;
+    /**
+     * skip commits touching more than this many files (default 30; 0 = no cap).
+     * A sweeping rename/format/license commit would otherwise couple everything
+     * it touches — the code-maat noise convention drops those wide commits.
+     */
+    maxFiles?: number;
+    /** keep only the top N pairs after ranking (default: all) */
+    top?: number;
+    /** keep only pairs involving this exact path (a "what couples with X?" query) */
+    focus?: string;
+}
+/**
+ * Rank co-changing file pairs. Pure + deterministic.
+ *
+ * degree(A,B) = shared / min(commits(A), commits(B)) — the fraction of the
+ * rarer file's commits that also touched the other. Symmetric, in (0,1].
+ */
+export declare function computeCoupling(commits: Commit[], opts?: CouplingOptions): CouplingPair[];
+export declare function couplingToCsv(pairs: CouplingPair[]): string;
+/** Human-readable table. Pure. */
+export declare function formatCoupling(pairs: CouplingPair[]): string;
+//# sourceMappingURL=coupling.d.ts.map

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

@@ -0,0 +1,86 @@
+/**
+ * coupling.ts — temporal (co-change) coupling mined from git history.
+ *
+ * "Which files change together?" — the EMPIRICAL complement to `affected`'s
+ * STATIC import graph. Files that repeatedly land in the same commit are
+ * coupled in practice even when no import edge connects them (a JSON schema and
+ * its TS type, a serializer/deserializer split across modules, a feature flag
+ * and its consumers, a doc that must track an API). Surfacing that lets an agent
+ * or a maintainer catch the edit they'd otherwise forget.
+ *
+ * This is code-maat's `coupling`/`soc` analysis (Tornhill, *Your Code as a
+ * Crime Scene*), productized as "Change Coupling" in CodeScene. The scoring core
+ * is a pure fold over the SAME `git log --numstat` dump `hotspots` already
+ * parses, so it reuses that Commit type + parseGitLog and is unit-tested without
+ * a repo.
+ */
+import { toCsv } from '../util/csv.js';
+const US = '\x1f'; // pair-key separator (never appears in a file path)
+/**
+ * Rank co-changing file pairs. Pure + deterministic.
+ *
+ * degree(A,B) = shared / min(commits(A), commits(B)) — the fraction of the
+ * rarer file's commits that also touched the other. Symmetric, in (0,1].
+ */
+export function computeCoupling(commits, opts = {}) {
+    const minShared = opts.minShared ?? 2;
+    const maxFiles = opts.maxFiles ?? 30;
+    const fileCommits = new Map(); // path → # commits touching it
+    const pairShared = new Map(); // "a\x1fb" → # commits touching both
+    for (const c of commits) {
+        const paths = [...new Set(c.files.map((f) => f.path))].filter(Boolean);
+        if (maxFiles > 0 && paths.length > maxFiles)
+            continue; // skip sweeping commits (both counts + pairs)
+        for (const p of paths)
+            fileCommits.set(p, (fileCommits.get(p) ?? 0) + 1);
+        const sorted = paths.slice().sort(); // canonical (a<b) pair keys
+        for (let i = 0; i < sorted.length; i++) {
+            for (let j = i + 1; j < sorted.length; j++) {
+                const key = sorted[i] + US + sorted[j];
+                pairShared.set(key, (pairShared.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, shared] of pairShared) {
+        if (shared < minShared)
+            continue;
+        const sep = key.indexOf(US);
+        const a = key.slice(0, sep);
+        const b = key.slice(sep + 1);
+        if (opts.focus && a !== opts.focus && b !== opts.focus)
+            continue;
+        const aCommits = fileCommits.get(a) ?? 0;
+        const bCommits = fileCommits.get(b) ?? 0;
+        const denom = Math.min(aCommits, bCommits) || 1;
+        const degree = Math.round((shared / denom) * 100) / 100;
+        pairs.push({ a, b, shared, aCommits, bCommits, degree });
+    }
+    // deterministic: strongest coupling first, then most-shared, then path order
+    pairs.sort((x, y) => y.degree - x.degree ||
+        y.shared - x.shared ||
+        (x.a < y.a ? -1 : x.a > y.a ? 1 : 0) ||
+        (x.b < y.b ? -1 : x.b > y.b ? 1 : 0));
+    return opts.top && opts.top > 0 ? pairs.slice(0, opts.top) : pairs;
+}
+export function couplingToCsv(pairs) {
+    const headers = ['fileA', 'fileB', 'degree', 'shared', 'commitsA', 'commitsB'];
+    const rows = pairs.map((p) => [p.a, p.b, p.degree, p.shared, p.aCommits, p.bCommits]);
+    return toCsv(headers, rows);
+}
+/** Human-readable table. Pure. */
+export function formatCoupling(pairs) {
+    if (pairs.length === 0)
+        return 'no co-change coupling found (raise --since or lower --min-shared)';
+    const lines = [];
+    lines.push('rank  degree  shared  commits(A/B)  files');
+    pairs.forEach((p, i) => {
+        const rank = String(i + 1).padStart(4);
+        const degree = `${Math.round(p.degree * 100)}%`.padStart(6);
+        const shared = String(p.shared).padStart(6);
+        const ab = `${p.aCommits}/${p.bCommits}`.padStart(11);
+        lines.push(`${rank}  ${degree}  ${shared}  ${ab}  ${p.a}  ↔  ${p.b}`);
+    });
+    return lines.join('\n');
+}
+//# sourceMappingURL=coupling.js.map

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

@@ -36,6 +36,26 @@ const VITE_BUILTINS = new Set(['MODE', 'BASE_URL', 'PROD', 'DEV', 'SSR']);
 export function extractEnvRefs(source, file) {
     const out = [];
     const lines = source.split('\n');
+    // Map a byte offset in `source` to its 1-based line, for the whole-source
+    // destructure scan below (which can span lines). lineStart[i] = the offset
+    // where line i+1 begins; binary-search for the last start <= offset.
+    const lineStart = [0];
+    for (let k = 0; k < source.length; k++)
+        if (source[k] === '\n')
+            lineStart.push(k + 1);
+    const lineAt = (index) => {
+        let lo = 0, hi = lineStart.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (lineStart[mid] <= index)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    };
+    // Member-style reads (process.env.X, os.getenv('X'), …) are inherently
+    // single-line — scan line by line so each ref carries its own line number.
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (!line.includes('env') && !line.includes('getenv'))
@@ -50,21 +70,27 @@ export function extractEnvRefs(source, file) {
                 out.push({ key, file, line: i + 1 });
             }
         }
-        // Destructuring reads: `const { PORT, DB_URL } = process.env` (each property
-        // key is an env-var reference). The `(?![.[])` guard keeps it to the bare
-        // `process.env` object, not `= process.env.FOO`. Single-line, like the rest.
-        DESTRUCTURE_RE.lastIndex = 0;
-        let dm;
-        while ((dm = DESTRUCTURE_RE.exec(line)) !== null) {
-            for (const part of dm[1].split(',')) {
-                // The env-var name is the property key — left of a rename `:` or default `=`.
-                const key = part.trim().split(/[:=]/)[0].trim();
-                if (!/^[A-Za-z_$][\w$]*$/.test(key))
-                    continue; // skip `...rest`, empties
-                if (VITE_BUILTINS.has(key))
-                    continue;
-                out.push({ key, file, line: i + 1 });
+    }
+    // Destructuring reads: `const { PORT, DB_URL } = process.env`. Scanned over the
+    // WHOLE source, not per line — a Prettier-wrapped list spans lines:
+    //   const {\n  PORT,\n  DB_URL,\n} = process.env
+    // The regex's `\s*`/`[^}]+` already match newlines, so running it per line was
+    // exactly what hid multi-line destructures (a false-clean `env --ci`). The
+    // `(?![.[])` guard keeps it to the bare object, not `= process.env.FOO`; each
+    // property key maps back to its own line via its offset.
+    DESTRUCTURE_RE.lastIndex = 0;
+    let dm;
+    while ((dm = DESTRUCTURE_RE.exec(source)) !== null) {
+        const bodyStart = dm.index + dm[0].indexOf(dm[1]);
+        let partOffset = 0;
+        for (const part of dm[1].split(',')) {
+            // The env-var name is the property key — left of a rename `:` or default `=`.
+            const key = part.trim().split(/[:=]/)[0].trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(key) && !VITE_BUILTINS.has(key)) { // skip `...rest`, empties, builtins
+                const kOff = part.indexOf(key);
+                out.push({ key, file, line: lineAt(bodyStart + partOffset + (kOff < 0 ? 0 : kOff)) });
             }
+            partOffset += part.length + 1; // + the comma consumed by split
         }
     }
     return out;

package/v3/@swarmdo/cli/dist/src/hooks-recipe/command-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * command-guard.ts — classify a bash command as safe or blockable, for a
+ * PreToolUse/Bash hook that emits Claude Code's `permissionDecision: "deny"`.
+ *
+ * swarmdo runs headless `claude -p --dangerously-skip-permissions` in its
+ * daemon / worker / repair flows; that flag skips the interactive approval
+ * prompt but NOT hooks, so a PreToolUse deny is the only remaining guardrail.
+ * The denylist is deliberately CONSERVATIVE — it blocks a small set of clearly
+ * destructive / irreversible / remote-exec commands and lets everything else
+ * through, so a routine `rm -rf ./build`, `rm -rf node_modules`, or a
+ * feature-branch force-push is never blocked. Pure + injection-free → fully
+ * unit-tested. This is defense-in-depth, not a sandbox: a determined command
+ * (indirection through a variable, an obscure tool) can still get through.
+ */
+export interface GuardVerdict {
+    block: boolean;
+    /** why it was blocked (present only when block === true) */
+    reason?: string;
+    /** the matched rule id (stable identifier, useful for tests/telemetry) */
+    rule?: string;
+}
+interface Rule {
+    id: string;
+    reason: string;
+    test: (c: string) => boolean;
+}
+/** The denylist. Order determines which reason is reported when several match. */
+export declare const GUARD_RULES: Rule[];
+/** Classify a bash command; blocks on the first matching danger rule, else allows. */
+export declare function classifyCommand(command: string): GuardVerdict;
+/**
+ * Extract the Bash command from a PreToolUse hook payload (the JSON Claude Code
+ * pipes on stdin: `{ "tool_name": "Bash", "tool_input": { "command": "…" } }`).
+ * Tolerant — returns '' when absent or unparseable, so the hook simply allows.
+ */
+export declare function extractBashCommand(payload: string): string;
+/** The PreToolUse deny payload Claude Code honors to hard-block a tool call. */
+export declare function denyOutput(reason: string): {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'deny';
+        permissionDecisionReason: string;
+    };
+};
+export {};
+//# sourceMappingURL=command-guard.d.ts.map

package/v3/@swarmdo/cli/dist/src/hooks-recipe/command-guard.js

@@ -0,0 +1,120 @@
+/**
+ * command-guard.ts — classify a bash command as safe or blockable, for a
+ * PreToolUse/Bash hook that emits Claude Code's `permissionDecision: "deny"`.
+ *
+ * swarmdo runs headless `claude -p --dangerously-skip-permissions` in its
+ * daemon / worker / repair flows; that flag skips the interactive approval
+ * prompt but NOT hooks, so a PreToolUse deny is the only remaining guardrail.
+ * The denylist is deliberately CONSERVATIVE — it blocks a small set of clearly
+ * destructive / irreversible / remote-exec commands and lets everything else
+ * through, so a routine `rm -rf ./build`, `rm -rf node_modules`, or a
+ * feature-branch force-push is never blocked. Pure + injection-free → fully
+ * unit-tested. This is defense-in-depth, not a sandbox: a determined command
+ * (indirection through a variable, an obscure tool) can still get through.
+ */
+/** `rm` invoked with BOTH a recursive and a force flag (combined `-rf`/`-fr` or separate). */
+function isRecursiveForceRm(c) {
+    if (!/\brm\b/.test(c))
+        return false;
+    const recursive = /(?:^|\s)-[a-z]*r[a-z]*(?=\s|$)/i.test(c) || /(?:^|\s)--recursive\b/.test(c);
+    const force = /(?:^|\s)-[a-z]*f[a-z]*(?=\s|$)/i.test(c) || /(?:^|\s)--force\b/.test(c);
+    return recursive && force;
+}
+/** Does the command target a root / home / top-level system path (the only rm targets we block)? */
+function hasCriticalTarget(c) {
+    if (/--no-preserve-root\b/.test(c))
+        return true;
+    // a bare `/`, `~`, `$HOME`/`${HOME}` token, optionally with a trailing `/` or `/*` or `*`
+    if (/(?:^|\s)(?:\/|~|\$\{?HOME\}?)(?:\/\s|\/$|\/\*|\*|\s|$)/.test(c))
+        return true;
+    // a top-level system directory
+    if (/(?:^|\s)\/(?:etc|usr|bin|sbin|var|lib|lib64|boot|sys|proc|dev|root|opt)(?:\/|\s|\*|$)/.test(c))
+        return true;
+    return false;
+}
+/** The denylist. Order determines which reason is reported when several match. */
+export const GUARD_RULES = [
+    {
+        id: 'rm-rf-critical',
+        reason: 'recursive force-delete of a root, home, or system path (rm -rf /, ~, or --no-preserve-root)',
+        test: (c) => isRecursiveForceRm(c) && hasCriticalTarget(c),
+    },
+    {
+        id: 'pipe-to-shell',
+        reason: 'piping remote content straight into a shell (curl/wget … | sh) — remote code execution',
+        test: (c) => /(?:\bcurl\b|\bwget\b)[^|]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh|dash|ksh|fish)\b/.test(c),
+    },
+    {
+        id: 'force-push-protected',
+        reason: 'force-push to a protected branch (main/master) — use --force-with-lease',
+        test: (c) => /\bgit\s+push\b/.test(c) && /(?:--force(?!-with-lease)\b|(?:^|\s)-f\b)/.test(c) && /\b(?:main|master)\b/.test(c),
+    },
+    {
+        id: 'chmod-world-writable',
+        reason: 'world-writable permissions (chmod 777)',
+        test: (c) => /\bchmod\s+(?:-[a-z]+\s+)*(?:0?777|a\+rwx|ugo\+rwx)\b/i.test(c),
+    },
+    {
+        id: 'dd-to-device',
+        reason: 'dd writing directly to a block device (of=/dev/…) — data-destroying',
+        test: (c) => /\bdd\b[^|;&]*\bof=\/dev\/(?:sd|nvme|disk|hd|mmcblk|vd|xvd)/.test(c),
+    },
+    {
+        id: 'mkfs',
+        reason: 'formatting a filesystem (mkfs) — data-destroying',
+        test: (c) => /\bmkfs(?:\.\w+)?\b/.test(c),
+    },
+    {
+        id: 'redirect-to-device',
+        reason: 'redirecting output onto a raw block device (> /dev/sd…) — data-destroying',
+        test: (c) => /(?:^|\s)>{1,2}\s*\/dev\/(?:sd|nvme|disk|hd|mmcblk|vd|xvd)/.test(c),
+    },
+    {
+        id: 'fork-bomb',
+        reason: 'shell fork bomb',
+        test: (c) => /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(c.replace(/\s+/g, ' ')),
+    },
+];
+/** Classify a bash command; blocks on the first matching danger rule, else allows. */
+export function classifyCommand(command) {
+    const c = (command ?? '').trim();
+    if (!c)
+        return { block: false };
+    for (const r of GUARD_RULES) {
+        // a bad regex must never crash the hook (and thus never wrongly block)
+        try {
+            if (r.test(c))
+                return { block: true, reason: r.reason, rule: r.id };
+        }
+        catch { /* skip */ }
+    }
+    return { block: false };
+}
+/**
+ * Extract the Bash command from a PreToolUse hook payload (the JSON Claude Code
+ * pipes on stdin: `{ "tool_name": "Bash", "tool_input": { "command": "…" } }`).
+ * Tolerant — returns '' when absent or unparseable, so the hook simply allows.
+ */
+export function extractBashCommand(payload) {
+    if (!payload || !payload.trim())
+        return '';
+    try {
+        const o = JSON.parse(payload);
+        const cmd = o?.tool_input?.command ?? o?.command;
+        return typeof cmd === 'string' ? cmd : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** The PreToolUse deny payload Claude Code honors to hard-block a tool call. */
+export function denyOutput(reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    };
+}
+//# sourceMappingURL=command-guard.js.map

package/v3/@swarmdo/cli/dist/src/hooks-recipe/recipe.js

@@ -23,6 +23,28 @@ export const RECIPES = [
         title: 'Desktop ping when Claude needs input',
         description: 'Fires a desktop notification when Claude is waiting for input or a permission decision (Notification hook).',
     },
+    {
+        name: 'memory-inject',
+        event: 'UserPromptSubmit',
+        command: 'swarmdo hooks memory-inject',
+        title: 'Inject relevant memories into each prompt',
+        description: 'On every prompt, semantically searches your stored memories (claude-memories/auto-memory/patterns) and injects the most relevant ones as context under a token budget (UserPromptSubmit hook). Powered by `swarmdo hooks memory-inject`. Opt-in: adds a small per-prompt search.',
+    },
+    {
+        name: 'comms-inbox',
+        event: 'UserPromptSubmit',
+        command: 'swarmdo comms inbox --hook',
+        title: 'Surface new cross-session messages each prompt',
+        description: 'On every prompt, injects any unread messages other sessions sent to this one (multiplayer swarms) as context, then marks them read — so mail surfaces without polling (UserPromptSubmit hook). Powered by `swarmdo comms inbox --hook`. Opt-in.',
+    },
+    {
+        name: 'command-guard',
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'swarmdo hooks guard-bash',
+        title: 'Block dangerous bash commands before they run',
+        description: 'Inspects every Bash tool call and hard-blocks a conservative denylist of destructive commands (rm -rf / , curl|sh, force-push to main, chmod 777, dd to a device, mkfs, fork bombs) via Claude Code’s PreToolUse `permissionDecision: "deny"`. Powered by `swarmdo hooks guard-bash`. Opt-in — the one guardrail that still fires under `--dangerously-skip-permissions`.',
+    },
 ];
 export function findRecipe(name) {
     const n = (name ?? '').trim().toLowerCase();
@@ -37,7 +59,12 @@ export function hasRecipe(settings, r) {
     const events = hooks?.[r.event];
     if (!Array.isArray(events))
         return false;
-    return events.some((e) => e && typeof e === 'object' && Array.isArray(e.hooks) &&
+    // Match on matcher too: the same command under a DIFFERENT matcher is a
+    // distinct binding, so a matcher-scoped recipe isn't "already installed" just
+    // because its command appears elsewhere (matcher-less recipes compare
+    // undefined === undefined, unchanged).
+    return events.some((e) => e && typeof e === 'object' && e.matcher === r.matcher &&
+        Array.isArray(e.hooks) &&
         e.hooks.some((h) => h?.command === r.command));
 }
 /** Additively merge a recipe into a settings object. Pure: returns a new object,

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

@@ -64,6 +64,9 @@ export declare function resolveRenamePath(raw: string): string;
 export declare function parseGitLog(raw: string): Commit[];
 /** Aggregate commits into per-file hotspots, scored and ranked. Pure. */
 export declare function computeHotspots(commits: Commit[], now: number, opts?: HotspotOptions): FileHotspot[];
+/** Export the ranking as CSV for spreadsheets / tech-debt review. Epoch dates
+ * render as ISO `YYYY-MM-DD` (UTC). Pure. */
+export declare function hotspotsToCsv(spots: FileHotspot[]): string;
 /** Human-readable table. Pure. */
 export declare function formatHotspots(spots: FileHotspot[], now: number): string;
 //# sourceMappingURL=hotspots.d.ts.map

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

@@ -15,6 +15,7 @@
  *   <SOH>%H<US>%an<US>%aI      ← one header line per commit
  *   <added>\t<deleted>\t<path> ← one numstat line per file ('-' for binary)
  */
+import { toCsv } from '../util/csv.js';
 const SOH = '\x01'; // start-of-commit marker (git --format=format:%x01...)
 const US = '\x1f'; // field separator (%x1f)
 /**
@@ -134,6 +135,14 @@ export function computeHotspots(commits, now, opts = {}) {
         out = out.slice(0, opts.top);
     return out;
 }
+/** Export the ranking as CSV for spreadsheets / tech-debt review. Epoch dates
+ * render as ISO `YYYY-MM-DD` (UTC). Pure. */
+export function hotspotsToCsv(spots) {
+    const isoDay = (ms) => (ms > 0 ? new Date(ms).toISOString().slice(0, 10) : '');
+    const headers = ['path', 'risk', 'commits', 'churn', 'authors', 'firstTouched', 'lastTouched'];
+    const rows = spots.map((s) => [s.path, s.risk, s.commits, s.churn, s.authors, isoDay(s.firstTouched), isoDay(s.lastTouched)]);
+    return toCsv(headers, rows);
+}
 /** Human-readable table. Pure. */
 export function formatHotspots(spots, now) {
     if (spots.length === 0)

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

@@ -20,6 +20,7 @@ import { commands, getCommandsByCategory, getCommand, getCommandAsync, getComman
 import { suggestCommand } from './suggest.js';
 import { runStartupUpdateCheck } from './update/index.js';
 import { migrateStorageDir } from './storage-migration.js';
+import { guardStreamEpipe } from './util/stdout.js';
 // Read version from package.json at runtime
 function getPackageVersion() {
     try {
@@ -68,6 +69,13 @@ export class CLI {
      */
     async run(args = process.argv.slice(2)) {
         try {
+            // #78 — Arm the EPIPE guard on stdout/stderr before ANY write happens, so
+            // `swarmdo <cmd> | head` (reader closes the pipe early) terminates cleanly
+            // instead of crashing with an unhandled 'error' event + raw stack trace.
+            // Covers every write path (output.writeln, console, writeStdout), not just
+            // writeStdout callers. Idempotent per stream.
+            guardStreamEpipe(process.stdout);
+            guardStreamEpipe(process.stderr);
             // One-time storage migration: rename a legacy `.claude-flow/` data dir
             // to `.swarmdo/` so users upgrading across the clean-break rename keep
             // their agent registry, swarm state, task store, and sessions. Cheap

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

@@ -39,7 +39,10 @@ export function classifyLicense(pkg) {
     if (Array.isArray(arr) && arr.length) {
         const types = arr
             .map((e) => (typeof e === 'string' ? e : e?.type))
-            .filter((t) => typeof t === 'string' && !!t.trim());
+            .filter((t) => typeof t === 'string' && !!t.trim())
+            // Normalize each entry like the singular `license`/`{type}` branches above,
+            // so npm sentinels (`SEE LICENSE IN …`, `UNLICENSED`) become UNKNOWN here too.
+            .map(normalizeNpmLicense);
         if (types.length)
             return types.join(' OR ');
     }

package/v3/@swarmdo/cli/dist/src/mcp-client.js

@@ -15,6 +15,7 @@ import { memoryTools } from './mcp-tools/memory-tools.js';
 import { configTools } from './mcp-tools/config-tools.js';
 import { hooksTools } from './mcp-tools/hooks-tools.js';
 import { taskTools } from './mcp-tools/task-tools.js';
+import { commsTools } from './mcp-tools/comms-tools.js';
 import { sessionTools } from './mcp-tools/session-tools.js';
 import { hiveMindTools } from './mcp-tools/hive-mind-tools.js';
 import { workflowTools } from './mcp-tools/workflow-tools.js';
@@ -25,6 +26,7 @@ import { envTools } from './mcp-tools/env-tools.js';
 import { licenseTools } from './mcp-tools/license-tools.js';
 import { applyTools } from './mcp-tools/apply-tools.js';
 import { hotspotsTools } from './mcp-tools/hotspots-tools.js';
+import { couplingTools } from './mcp-tools/coupling-tools.js';
 import { affectedTools } from './mcp-tools/affected-tools.js';
 import { cyclesTools } from './mcp-tools/cycles-tools.js';
 import { testreportTools } from './mcp-tools/testreport-tools.js';
@@ -107,6 +109,7 @@ const TOOL_GROUPS = {
     config: () => configTools,
     hooks: () => hooksTools,
     task: () => taskTools,
+    comms: () => commsTools,
     session: () => sessionTools,
     'hive-mind': () => hiveMindTools,
     workflow: () => workflowTools,
@@ -117,6 +120,7 @@ const TOOL_GROUPS = {
     license: () => licenseTools,
     apply: () => applyTools,
     hotspots: () => hotspotsTools,
+    coupling: () => couplingTools,
     affected: () => affectedTools,
     cycles: () => cyclesTools,
     testreport: () => testreportTools,

package/v3/@swarmdo/cli/dist/src/mcp-tools/comms-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Comms MCP Tools — cross-session agent mailbox (#44).
+ *
+ * Thin wrappers over the pure comms/mailbox.ts engine + comms/store.ts fs
+ * persistence, so an in-Claude session can message another session (or read its
+ * own inbox) without shelling out. Same `.swarmdo/comms/store.json` the
+ * `swarmdo comms` CLI uses.
+ */
+import { type MCPTool } from './types.js';
+export declare const commsTools: MCPTool[];
+//# sourceMappingURL=comms-tools.d.ts.map