swarmdo 1.29.0 → 1.37.0

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

@@ -0,0 +1,280 @@
+/**
+ * comms.ts — `swarmdo comms` — a cross-session agent mailbox (#44).
+ *
+ *   swarmdo comms send -t <session> -m "<message>"   leave a message for a session
+ *   swarmdo comms inbox [-t <self>] [-u]              list your messages (newest first)
+ *   swarmdo comms read <id>                           show a full message + mark it read
+ *
+ * Any Claude Code session on the same repo shares `.swarmdo/comms/store.json`, so
+ * one session can message another by name ("multiplayer swarms"). Address `all`
+ * to broadcast. The message model, filtering, and retention live in the pure
+ * comms/mailbox.ts engine; this layer is fs persistence + presentation.
+ */
+import { output } from '../output.js';
+import { createMessage, addMessage, filterInbox, unreadCount, markRead, pruneMailbox, renderInboxContext, } from '../comms/mailbox.js';
+import { loadMailbox, saveMailbox, resolveSelf, newMessageId, RETENTION } from '../comms/store.js';
+/** Compact relative age, e.g. "3m", "2h", "5d", or "now". */
+function relAge(iso, nowMs) {
+    const ms = nowMs - Date.parse(iso);
+    if (!Number.isFinite(ms) || ms < 0)
+        return '—';
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return 'now';
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    return `${Math.floor(h / 24)}d`;
+}
+const sendCommand = {
+    name: 'send',
+    description: 'Send a message to another session (address "all" to broadcast)',
+    options: [
+        { name: 'to', short: 't', description: 'Recipient session name (or "all")', type: 'string' },
+        { name: 'message', short: 'm', description: 'Message body', type: 'string' },
+        { name: 'subject', short: 's', description: 'Subject line', type: 'string' },
+        { name: 'from', short: 'f', description: 'Sender name (default: this session)', type: 'string' },
+        { name: 'json', description: 'Machine-readable output', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo comms send -t reviewer -m "auth PR is ready" -s "PR #42"', description: 'Message the "reviewer" session' },
+        { command: 'swarmdo comms send -t all -m "rebasing main in 5min"', description: 'Broadcast to every session' },
+    ],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        const to = (ctx.flags.to || ctx.args[0] || '').trim();
+        const body = (ctx.flags.message ?? ctx.args[1] ?? '').toString();
+        if (!to) {
+            output.printError('Recipient required. Use --to/-t <session> (or "all").');
+            return { success: false, exitCode: 1 };
+        }
+        if (!body.trim()) {
+            output.printError('Message body required. Use --message/-m "<text>".');
+            return { success: false, exitCode: 1 };
+        }
+        const from = resolveSelf(ctx.flags.from);
+        const msg = createMessage({
+            id: newMessageId(),
+            from,
+            to,
+            subject: ctx.flags.subject,
+            body,
+            createdAt: new Date().toISOString(),
+        });
+        let box = addMessage(loadMailbox(cwd), msg);
+        box = pruneMailbox(box, { ...RETENTION, nowMs: Date.now() });
+        saveMailbox(cwd, box);
+        if (ctx.flags.json === true) {
+            output.printJson({ sent: true, id: msg.id, to: msg.to, from: msg.from });
+            return { success: true, data: { id: msg.id } };
+        }
+        output.printSuccess(`Sent to ${output.highlight(msg.to)} — id ${output.dim(msg.id)}`);
+        return { success: true, data: { id: msg.id } };
+    },
+};
+const inboxCommand = {
+    name: 'inbox',
+    aliases: ['list'],
+    description: 'List messages addressed to you (newest first)',
+    options: [
+        { name: 'to', short: 't', description: 'Whose inbox (default: this session)', type: 'string' },
+        { name: 'from', short: 'f', description: 'Only messages from this sender', type: 'string' },
+        { name: 'unread', short: 'u', description: 'Only unread messages', type: 'boolean' },
+        { name: 'since', description: 'Only messages after this ISO timestamp', type: 'string' },
+        { name: 'mark-read', description: 'Mark all shown messages as read', type: 'boolean' },
+        { name: 'hook', description: 'Emit unread messages as UserPromptSubmit additionalContext JSON, then mark them read (for hook delivery)', type: 'boolean' },
+        { name: 'json', description: 'Machine-readable output', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo comms inbox', description: 'Your unread + read messages' },
+        { command: 'swarmdo comms inbox -u --mark-read', description: 'Show unread, then mark them read' },
+    ],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        const self = resolveSelf(ctx.flags.to);
+        // --hook: delivery path. Emit unread mail as UserPromptSubmit additionalContext
+        // and mark it read so it surfaces once, without polling. Hook-safe: NEVER
+        // errors (that would break the prompt) and stays silent when there's no mail.
+        if (ctx.flags.hook === true) {
+            try {
+                if (process.env.SWARMDO_COMMS_DISABLE === '1')
+                    return { success: true };
+                const box = loadMailbox(cwd);
+                const unread = filterInbox(box, { to: self, unreadOnly: true });
+                if (unread.length > 0) {
+                    const block = renderInboxContext(unread);
+                    process.stdout.write(JSON.stringify({
+                        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block },
+                    }) + '\n');
+                    const { box: next, marked } = markRead(box, unread.map((m) => m.id));
+                    if (marked > 0)
+                        saveMailbox(cwd, next);
+                }
+            }
+            catch {
+                /* never fail a hook */
+            }
+            return { success: true };
+        }
+        const box = loadMailbox(cwd);
+        const inbox = filterInbox(box, {
+            to: self,
+            from: ctx.flags.from,
+            unreadOnly: ctx.flags.unread === true,
+            since: ctx.flags.since,
+        });
+        const now = Date.now();
+        if (ctx.flags.json === true) {
+            output.printJson({ to: self, unread: unreadCount(box, self), messages: inbox });
+        }
+        else if (inbox.length === 0) {
+            output.printInfo(`No messages for ${output.highlight(self)}.`);
+        }
+        else {
+            output.writeln(output.bold(`Inbox: ${self}`) + output.dim(`  (${unreadCount(box, self)} unread)`));
+            output.printTable({
+                columns: [
+                    { key: 'flag', header: '', width: 2 },
+                    { key: 'id', header: 'ID', width: 14 },
+                    { key: 'from', header: 'From', width: 16 },
+                    { key: 'subject', header: 'Subject', width: 34 },
+                    { key: 'age', header: 'Age', width: 6, align: 'right' },
+                ],
+                data: inbox.map((m) => ({ flag: m.read ? ' ' : '●', id: m.id, from: m.from, subject: m.subject, age: relAge(m.createdAt, now) })),
+            });
+            output.writeln(output.dim('● = unread · read a message:  swarmdo comms read <id>'));
+        }
+        if (ctx.flags['mark-read'] === true && inbox.length > 0) {
+            const { box: next, marked } = markRead(box, inbox.map((m) => m.id));
+            if (marked > 0)
+                saveMailbox(cwd, next);
+            if (ctx.flags.json !== true)
+                output.printInfo(`Marked ${marked} read.`);
+        }
+        return { success: true, data: { to: self, count: inbox.length } };
+    },
+};
+const readCommand = {
+    name: 'read',
+    description: 'Show a full message and mark it read',
+    options: [{ name: 'json', description: 'Machine-readable output', type: 'boolean' }],
+    examples: [{ command: 'swarmdo comms read msg_ab12cd34ef56', description: 'Open a message by id' }],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        const id = (ctx.args[0] || '').trim();
+        if (!id) {
+            output.printError('Message id required:  swarmdo comms read <id>');
+            return { success: false, exitCode: 1 };
+        }
+        const box = loadMailbox(cwd);
+        const m = box.messages[id];
+        if (!m) {
+            output.printError(`No message with id ${id}.`);
+            return { success: false, exitCode: 1 };
+        }
+        const { box: next, marked } = markRead(box, [id]);
+        if (marked > 0)
+            saveMailbox(cwd, next);
+        if (ctx.flags.json === true) {
+            output.printJson({ ...m, read: true });
+            return { success: true, data: { id } };
+        }
+        output.writeln();
+        output.printList([
+            `${output.bold('From')}:    ${m.from}`,
+            `${output.bold('To')}:      ${m.to}`,
+            `${output.bold('Subject')}: ${m.subject}`,
+            `${output.bold('Sent')}:    ${m.createdAt}`,
+        ]);
+        output.writeln();
+        output.writeln(m.body);
+        output.writeln();
+        return { success: true, data: { id } };
+    },
+};
+const watchCommand = {
+    name: 'watch',
+    description: 'Live-tail your inbox — print new messages as they arrive (Ctrl-C to stop)',
+    options: [
+        { name: 'to', short: 't', description: 'Whose inbox (default: this session)', type: 'string' },
+        { name: 'from', short: 'f', description: 'Only messages from this sender', type: 'string' },
+        { name: 'interval', short: 'i', description: 'Poll interval in seconds', type: 'number', default: 5 },
+    ],
+    examples: [
+        { command: 'swarmdo comms watch', description: 'Live-tail your inbox' },
+        { command: 'swarmdo comms watch -i 2', description: 'Poll every 2 seconds' },
+    ],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        const self = resolveSelf(ctx.flags.to);
+        const from = ctx.flags.from;
+        const intervalMs = Math.max(1, Number(ctx.flags.interval ?? 5)) * 1000;
+        // Only surface messages that arrive AFTER watch starts.
+        let cursor = new Date().toISOString();
+        output.printInfo(`Watching ${output.highlight(self)}'s inbox every ${intervalMs / 1000}s (Ctrl-C to stop)…`);
+        return await new Promise((resolve) => {
+            const tick = () => {
+                try {
+                    const box = loadMailbox(cwd);
+                    // filterInbox is newest-first; reverse to print in arrival order.
+                    const fresh = filterInbox(box, { to: self, from, since: cursor }).reverse();
+                    for (const m of fresh) {
+                        output.writeln(`${output.dim(new Date(m.createdAt).toLocaleTimeString())} ${output.bold(m.from)} › ${m.subject}: ${m.body.replace(/\s+/g, ' ').trim()}`);
+                        if (m.createdAt > cursor)
+                            cursor = m.createdAt;
+                    }
+                }
+                catch {
+                    /* keep watching despite a transient read error */
+                }
+            };
+            const timer = setInterval(tick, intervalMs);
+            const stop = () => {
+                clearInterval(timer);
+                output.writeln();
+                output.printInfo('Stopped watching.');
+                resolve({ success: true });
+            };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+        });
+    },
+};
+export const commsCommand = {
+    name: 'comms',
+    aliases: ['mailbox'],
+    description: 'Cross-session agent mailbox — message another session by name',
+    subcommands: [sendCommand, inboxCommand, readCommand, watchCommand],
+    options: [],
+    examples: [
+        { command: 'swarmdo comms send -t reviewer -m "PR ready"', description: 'Send a message' },
+        { command: 'swarmdo comms inbox -u', description: 'List your unread messages' },
+        { command: 'swarmdo comms read <id>', description: 'Open a message' },
+    ],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        const self = resolveSelf();
+        const box = loadMailbox(cwd);
+        const unread = unreadCount(box, self);
+        output.writeln();
+        output.writeln(output.bold('Cross-session agent mailbox'));
+        output.writeln();
+        output.writeln(`You are ${output.highlight(self)} — ${unread} unread message${unread === 1 ? '' : 's'}.`);
+        output.writeln();
+        output.writeln('Usage: swarmdo comms <send|inbox|read|watch> [options]');
+        output.printList([
+            `${output.highlight('send')}   - Send a message (\`-t <session> -m "…"\`, \`-t all\` to broadcast)`,
+            `${output.highlight('inbox')}  - List your messages (\`-u\` unread, \`--mark-read\`, \`--hook\`)`,
+            `${output.highlight('read')}   - Show a full message by id and mark it read`,
+            `${output.highlight('watch')}  - Live-tail your inbox for new messages`,
+        ]);
+        output.writeln();
+        output.writeln(output.dim('Sessions on the same repo share .swarmdo/comms/. Name yourself with $SWARMDO_SESSION.'));
+        return { success: true, data: { self, unread } };
+    },
+};
+export default commsCommand;
+//# sourceMappingURL=comms.js.map

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

@@ -34,8 +34,12 @@ function optsFromFlags(ctx) {
     };
     if (typeof ctx.flags['min-run'] === 'number')
         opts.minRun = ctx.flags['min-run'];
-    else if (typeof ctx.flags['min-run'] === 'string')
-        opts.minRun = parseInt(ctx.flags['min-run'], 10) || 3;
+    else if (typeof ctx.flags['min-run'] === 'string') {
+        // Explicit NaN check, NOT `|| 3` — the documented `--min-run 0` ("disables")
+        // is falsy and would otherwise be silently coerced back to the default 3.
+        const parsed = parseInt(ctx.flags['min-run'], 10);
+        opts.minRun = Number.isNaN(parsed) ? 3 : parsed;
+    }
     const win = ctx.flags.window;
     if (typeof win === 'string' && /^\d+:\d+$/.test(win)) {
         const [head, tail] = win.split(':').map((n) => parseInt(n, 10));

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

@@ -438,6 +438,7 @@ const lintCommand = {
             settingsFiles: [read('.claude/settings.json'), read('.claude/settings.local.json')],
             mcpConfig: read('.mcp.json'),
             commandsRoot: list('.claude/commands'),
+            sdoCommands: list('.claude/commands/sDo'),
             skills: list('.claude/skills'),
         });
         const failed = report.errors > 0 || (ctx.flags.strict === true && report.warnings > 0);

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

@@ -8,6 +8,8 @@ import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { storeCommand } from './transfer-store.js';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { bridgeSearchEntries } from '../memory/memory-bridge.js';
+import { selectInjectionMemories, mapSearchResultsToCandidates, extractPromptFromPayload, } from '../memory-inject/select.js';
 /**
  * #1686 — `?? 0` only defaults null/undefined; NaN slips through and
  * surfaces as `"NaN"` (or earlier crashed `.toFixed`) in the metrics
@@ -731,6 +733,122 @@ const routeCommand = {
         }
     }
 };
+/**
+ * Read a Claude Code hook payload from stdin (JSON on UserPromptSubmit), with a
+ * short timeout so it never hangs when stdin isn't closed (a known Windows
+ * failure mode). Returns '' for a TTY or on any error — the caller then simply
+ * injects nothing.
+ */
+async function readHookStdin(timeoutMs = 1500) {
+    if (process.stdin.isTTY)
+        return '';
+    return new Promise((resolve) => {
+        let data = '';
+        const finish = (v) => {
+            try {
+                process.stdin.pause();
+            }
+            catch { /* noop */ }
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(data), timeoutMs);
+        try {
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (c) => { data += c; });
+            process.stdin.on('end', () => { clearTimeout(timer); finish(data); });
+            process.stdin.on('error', () => { clearTimeout(timer); finish(data); });
+            process.stdin.resume();
+        }
+        catch {
+            clearTimeout(timer);
+            finish('');
+        }
+    });
+}
+const DEFAULT_INJECT_NAMESPACES = ['claude-memories', 'auto-memory', 'patterns'];
+/**
+ * memory-inject — the #43 prompt-time semantic memory injection hook. Embeds the
+ * submitted prompt, vector-searches AgentDB across the memory namespaces, and
+ * emits the most relevant stored memories as UserPromptSubmit `additionalContext`
+ * under a strict token budget. Wired for the hook path: it NEVER errors out
+ * (that would break the user's prompt) and stays silent when nothing is relevant.
+ */
+const memoryInjectCommand = {
+    name: 'memory-inject',
+    description: 'Inject relevant stored memories into the prompt (UserPromptSubmit hook)',
+    options: [
+        { name: 'prompt', short: 'p', description: 'Prompt text (else read the hook JSON from stdin)', type: 'string' },
+        { name: 'namespaces', description: 'Comma-separated namespaces to search', type: 'string', default: DEFAULT_INJECT_NAMESPACES.join(',') },
+        { name: 'budget', description: 'Max tokens of injected context', type: 'number', default: 800 },
+        { name: 'min-relevance', description: 'Minimum relevance score (0..1)', type: 'number', default: 0.35 },
+        { name: 'top-k', short: 'K', description: 'Max memories to inject', type: 'number', default: 5 },
+        { name: 'limit', description: 'Max search results to rank', type: 'number', default: 20 },
+        { name: 'preview', description: 'Print the block for humans instead of emitting hook JSON', type: 'boolean' },
+        { name: 'db', description: 'Path to the memory database', type: 'string' },
+    ],
+    examples: [
+        { command: 'swarmdo hooks memory-inject -p "refactor the auth module" --preview', description: 'Preview relevant memories for a prompt' },
+        { command: "echo '{\"prompt\":\"fix bug\"}' | swarmdo hooks memory-inject", description: 'Run as a UserPromptSubmit hook' },
+    ],
+    action: async (ctx) => {
+        const preview = Boolean(ctx.flags.preview);
+        // A hook must NEVER break the user's prompt: swallow every error and emit nothing.
+        try {
+            if (process.env.SWARMDO_MEMORY_INJECT_DISABLE === '1')
+                return { success: true };
+            let prompt = (ctx.flags.prompt || ctx.args.join(' ')).trim();
+            if (!prompt)
+                prompt = extractPromptFromPayload(await readHookStdin());
+            if (!prompt)
+                return { success: true }; // nothing to search on
+            const namespaces = String(ctx.flags.namespaces ?? DEFAULT_INJECT_NAMESPACES.join(','))
+                .split(',').map((s) => s.trim()).filter(Boolean);
+            const minRelevance = ctx.flags.minRelevance ?? 0.35;
+            const topK = ctx.flags.topK ?? 5;
+            const limit = Math.max(ctx.flags.limit ?? 20, topK);
+            const search = await bridgeSearchEntries({
+                query: prompt,
+                namespace: 'all',
+                limit,
+                threshold: minRelevance,
+                fullContent: true,
+                dbPath: ctx.flags.db,
+            });
+            const rows = (search && search.success ? search.results : []);
+            const candidates = mapSearchResultsToCandidates(rows, namespaces);
+            const result = selectInjectionMemories(candidates, {
+                budgetTokens: ctx.flags.budget ?? 800,
+                minRelevance,
+                topK,
+            });
+            if (preview) {
+                if (!result.block) {
+                    output.printInfo('No relevant memories to inject.');
+                }
+                else {
+                    output.writeln(result.block);
+                    output.writeln();
+                    output.printInfo(`Injected ${result.used.length} memor${result.used.length === 1 ? 'y' : 'ies'} ` +
+                        `(~${result.tokensUsed} tokens${result.skipped ? `, ${result.skipped} skipped` : ''}).`);
+                }
+                return { success: true, data: { used: result.used.length, skipped: result.skipped, tokensUsed: result.tokensUsed } };
+            }
+            // Hook mode: emit additionalContext JSON ONLY when there's something to add,
+            // so an irrelevant prompt leaves Claude's context untouched.
+            if (result.block) {
+                process.stdout.write(JSON.stringify({
+                    hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: result.block },
+                }) + '\n');
+            }
+            return { success: true };
+        }
+        catch (err) {
+            if (preview)
+                output.printError(`Memory injection failed: ${String(err)}`);
+            return { success: true }; // never fail the hook
+        }
+    },
+};
 // Explain subcommand
 const explainCommand = {
     name: 'explain',
@@ -4447,7 +4565,7 @@ const notifyCommand = {
 const recipeCommand = {
     name: 'recipe',
     aliases: ['recipes'],
-    description: 'Install ready-made Claude Code hook recipes (desktop notify) into settings — dry-run unless --apply',
+    description: 'Install ready-made Claude Code hook recipes (desktop notify, memory injection) into settings — dry-run unless --apply',
     options: [
         { name: 'apply', type: 'boolean', description: 'write the change (default: preview only)', default: false },
         { name: 'shared', type: 'boolean', description: 'target .claude/settings.json (shared/committed) instead of settings.local.json', default: false },
@@ -4553,6 +4671,7 @@ export const hooksCommand = {
         sessionEndCommand,
         sessionRestoreCommand,
         routeCommand,
+        memoryInjectCommand,
         explainCommand,
         pretrainCommand,
         buildAgentsCommand,
@@ -4610,6 +4729,7 @@ export const hooksCommand = {
             `${output.highlight('session-end')}     - End current session and persist state`,
             `${output.highlight('session-restore')} - Restore a previous session`,
             `${output.highlight('route')}           - Route tasks to optimal agents`,
+            `${output.highlight('memory-inject')}   - Inject relevant memories into the prompt (UserPromptSubmit)`,
             `${output.highlight('explain')}         - Explain routing decisions`,
             `${output.highlight('pretrain')}        - Bootstrap intelligence from repository`,
             `${output.highlight('build-agents')}    - Generate optimized agent configs`,

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

@@ -13,7 +13,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { output } from '../output.js';
-import { parseGitLog, computeHotspots, formatHotspots } from '../hotspots/hotspots.js';
+import { parseGitLog, computeHotspots, formatHotspots, hotspotsToCsv } from '../hotspots/hotspots.js';
 const SORT_KEYS = ['risk', 'churn', 'commits', 'authors'];
 /** Read a numeric flag that the parser may deliver as a number OR a string. */
 function numFlag(v, def) {
@@ -33,6 +33,7 @@ async function run(ctx) {
     }
     // Global --format (text|json|table); text and table both render the table.
     const asJson = ctx.flags.format === 'json';
+    const asCsv = ctx.flags.csv === true; // dedicated flag (global --format has no csv choice)
     // Capture history: SOH-delimited header + numstat, no merges. `%aN` (not
     // `%an`) resolves author names through `.mailmap`, so name/email variants of
     // the same person fold into one identity — otherwise the author-spread factor
@@ -50,7 +51,10 @@ async function run(ctx) {
     }
     const now = Date.now();
     const spots = computeHotspots(parseGitLog(raw), now, { by, top: top > 0 ? top : undefined, minCommits });
-    if (asJson) {
+    if (asCsv) {
+        process.stdout.write(hotspotsToCsv(spots) + '\n');
+    }
+    else if (asJson) {
         process.stdout.write(JSON.stringify({ generated: new Date(now).toISOString(), by, count: spots.length, hotspots: spots }, null, 2) + '\n');
     }
     else {
@@ -72,10 +76,12 @@ export const hotspotsCommand = {
         { name: 'top', description: 'keep only the top N files (default 20; 0 = all)', type: 'string' },
         { name: 'min-commits', description: 'drop files with fewer than N commits (default 1)', type: 'string' },
         { name: 'by', description: `sort key: ${SORT_KEYS.join('|')} (default risk)`, type: 'string' },
+        { name: 'csv', description: 'export the ranking as CSV (for spreadsheets)', type: 'boolean' },
     ],
     examples: [
         { command: 'swarmdo hotspots src --since 90d', description: 'Risk hotspots under src/ in the last 90 days' },
         { command: 'swarmdo hotspots --by churn --top 10 --format json', description: 'Top-10 by churn as JSON' },
+        { command: 'swarmdo hotspots --csv > hotspots.csv', description: 'Export the risk ranking to CSV' },
     ],
     action: run,
 };

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

@@ -100,6 +100,12 @@ const commandLoaders = {
     // Isolated git worktrees for parallel work (claude-squad/vibe-kanban demand)
     worktree: () => import('./worktree.js'),
     wt: () => import('./worktree.js'), // alias via loader key
+    // Cross-session agent mailbox (multiplayer swarms — dorsa_rohani demand)
+    comms: () => import('./comms.js'),
+    mailbox: () => import('./comms.js'), // alias via loader key
+    // Static audit of Claude Code permission rules (conflicts / dead / over-broad)
+    permissions: () => import('./permissions.js'),
+    perms: () => import('./permissions.js'), // alias via loader key
     // Export Claude Code sessions to Markdown (conversation-exporter demand)
     transcript: () => import('./transcript.js'),
     tx: () => import('./transcript.js'), // alias via loader key

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

@@ -0,0 +1,14 @@
+/**
+ * permissions.ts — `swarmdo permissions` (alias `perms`) — audit Claude Code
+ * permission rules for conflicts, dead/shadowed rules, and over-broad grants.
+ *
+ * Complements `config lint` (which validates the hooks block): this reads the
+ * `permissions.allow` / `deny` / `ask` arrays from `.claude/settings.json` +
+ * `settings.local.json` (+ `~/.claude/settings.json` with `--global`), merges
+ * them into the effective ruleset Claude Code enforces, and runs the pure
+ * permissions/audit.ts analyzer. Read-only — never edits settings.
+ */
+import type { Command } from '../types.js';
+export declare const permissionsCommand: Command;
+export default permissionsCommand;
+//# sourceMappingURL=permissions.d.ts.map

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

@@ -0,0 +1,92 @@
+/**
+ * permissions.ts — `swarmdo permissions` (alias `perms`) — audit Claude Code
+ * permission rules for conflicts, dead/shadowed rules, and over-broad grants.
+ *
+ * Complements `config lint` (which validates the hooks block): this reads the
+ * `permissions.allow` / `deny` / `ask` arrays from `.claude/settings.json` +
+ * `settings.local.json` (+ `~/.claude/settings.json` with `--global`), merges
+ * them into the effective ruleset Claude Code enforces, and runs the pure
+ * permissions/audit.ts analyzer. Read-only — never edits settings.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { output } from '../output.js';
+import { auditPermissions } from '../permissions/audit.js';
+const strArray = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+/** Extract permissions.allow/deny/ask from a settings file, or null if none. */
+function readPerms(file) {
+    try {
+        if (!existsSync(file))
+            return null;
+        const obj = JSON.parse(readFileSync(file, 'utf8'));
+        const perm = obj?.permissions;
+        if (!perm || typeof perm !== 'object')
+            return null;
+        const sets = { allow: strArray(perm.allow), deny: strArray(perm.deny), ask: strArray(perm.ask) };
+        return sets.allow.length + sets.deny.length + sets.ask.length > 0 ? sets : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const permissionsCommand = {
+    name: 'permissions',
+    aliases: ['perms'],
+    description: 'Audit Claude Code permission rules (allow/deny/ask) for conflicts, dead/shadowed rules, and over-broad grants',
+    options: [
+        { name: 'global', description: 'Also include ~/.claude/settings.json', type: 'boolean' },
+        { name: 'strict', description: 'Exit 1 if any error-severity finding (CI gate)', type: 'boolean' },
+        { name: 'json', description: 'Machine-readable output', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo permissions', description: "Audit this project's permission rules" },
+        { command: 'swarmdo permissions --global --strict', description: 'Include user-global settings; fail on conflicts' },
+    ],
+    action: async (ctx) => {
+        const cwd = ctx.cwd || process.cwd();
+        const files = [join(cwd, '.claude', 'settings.json'), join(cwd, '.claude', 'settings.local.json')];
+        if (ctx.flags.global === true)
+            files.push(join(homedir(), '.claude', 'settings.json'));
+        const used = [];
+        const merged = { allow: [], deny: [], ask: [] };
+        for (const file of files) {
+            const p = readPerms(file);
+            if (!p)
+                continue;
+            used.push(file);
+            merged.allow.push(...(p.allow ?? []));
+            merged.deny.push(...(p.deny ?? []));
+            merged.ask.push(...(p.ask ?? []));
+        }
+        const totalRules = merged.allow.length + merged.deny.length + merged.ask.length;
+        if (used.length === 0) {
+            if (ctx.flags.json === true)
+                output.printJson({ files: [], rules: 0, findings: [] });
+            else
+                output.printInfo('No permission rules found in .claude/settings*.json.');
+            return { success: true };
+        }
+        const findings = auditPermissions(merged);
+        const errors = findings.filter((f) => f.severity === 'error').length;
+        const warns = findings.filter((f) => f.severity === 'warn').length;
+        if (ctx.flags.json === true) {
+            output.printJson({ files: used, rules: totalRules, findings });
+        }
+        else if (findings.length === 0) {
+            output.printSuccess(`permissions audit: ${totalRules} rule(s) across ${used.length} file(s) — no issues`);
+        }
+        else {
+            const icon = (s) => (s === 'error' ? '✖' : s === 'warn' ? '⚠' : '·');
+            output.writeln(output.bold('Permission audit') + output.dim(`  (${totalRules} rules, ${used.length} file${used.length === 1 ? '' : 's'})`));
+            for (const x of findings)
+                output.writeln(`  ${icon(x.severity)} ${output.dim(`[${x.rule}]`)} ${x.message}`);
+            output.writeln('');
+            output.writeln(`${errors} error${errors === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'}, ${findings.length - errors - warns} info`);
+        }
+        const failed = ctx.flags.strict === true && errors > 0;
+        return { success: !failed, exitCode: failed ? 1 : 0, data: { rules: totalRules, findings } };
+    },
+};
+export default permissionsCommand;
+//# sourceMappingURL=permissions.js.map