swarmdo 1.54.1 → 1.58.1

package/.claude/helpers/statusline.cjs

@@ -105,7 +105,7 @@ function resolveCliBin() {
     ];
     try {
       const binDir = path.dirname(process.execPath);
-      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules')];
+      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules'), '/opt/homebrew/lib/node_modules', '/usr/local/lib/node_modules'];
       for (const prefix of [process.env.npm_config_prefix, process.env.PREFIX, path.join(home, '.npm-global')]) {
         if (prefix) globalModuleDirs.push(path.join(prefix, 'lib', 'node_modules'));
       }
@@ -148,6 +148,13 @@ function writeCache(data) {
  * and only counted ADRs in v3/implementation/adrs/ (missed v3/docs/adr/).
  */
 function getStatuslineData() {
+  // SWARMDO_STATUSLINE_NO_CLI: skip the CLI-delegation fork and render from local
+  // reads + stdin only. A cold render otherwise forks the hooks-statusline CLI
+  // (now more reachable via the global-node_modules probes below), and that fork
+  // can disturb the stdin cost payload; skipping it keeps renders fast, hermetic,
+  // and subprocess-free. Set by the statusline tests; usable by anyone who wants
+  // a no-fork statusline.
+  if (process.env.SWARMDO_STATUSLINE_NO_CLI) return buildLocalFallback();
   const cached = readCache();
   if (cached) return cached;
 
@@ -515,7 +522,7 @@ function getCostFromStdin() {
 // misses, the displayed version is meaningful (matches what the user
 // installed), not a stale hard-coded string.
 function getPkgVersion() {
-  let ver = '1.19.0';
+  let ver = '1.58.0';
   try {
     const home = os.homedir();
     const pkgPaths = [
@@ -531,7 +538,7 @@ function getPkgVersion() {
     // (bin/node_modules) layouts.
     try {
       const binDir = path.dirname(process.execPath);
-      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules')];
+      const globalModuleDirs = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules'), '/opt/homebrew/lib/node_modules', '/usr/local/lib/node_modules'];
       // #2221 follow-up: a custom npm prefix (e.g. ~/.npm-global) is decoupled from
       // the node binary location, so the binDir-derived probes above all miss. Also
       // probe the npm prefix from the environment and the common ~/.npm-global default.

package/README.md

@@ -2,7 +2,7 @@
 
 [![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.54.1-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
+[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.58.1-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/SwarmDo/swarmdo/blob/main/LICENSE)
 [![Website](https://img.shields.io/badge/swarmdo.com-e2a33c?style=for-the-badge&logoColor=black)](https://swarmdo.com)
 [![Star on GitHub](https://img.shields.io/github/stars/SwarmDo/swarmdo?style=for-the-badge&logo=github&color=gold)](https://github.com/SwarmDo/swarmdo)
@@ -271,7 +271,7 @@ The recent release train added a full day-to-day operations layer around the swa
 
 | Command | What it does |
 |---------|-------------|
-| `swarmdo usage` (alias `cost`) | Claude Code **spend analytics** from your local transcripts — `daily`, `weekly`, `monthly` (with a month-end spend projection), `models`, `projects`, `sessions`, live 5-hour `blocks` burn, `errors` (tool-failure analytics), `cache` (prompt-cache efficiency + $ saved), `diff` (period-over-period comparison with per-model movers), `reflect` (a wrapped-style retrospective — busiest day, streak, top models/projects, peak hour, delegation ratio — with a shareable `--html` dashboard), and `limits` (an official-quota **exhaustion forecaster** over Claude Code's `rate_limits`); the standard views take `--csv` for spreadsheet export |
+| `swarmdo usage` (alias `cost`) | Claude Code **spend analytics** from your local transcripts — `daily`, `weekly`, `monthly` (with a month-end spend projection), `models`, `projects`, `sessions`, live 5-hour `blocks` burn, `errors` (tool-failure analytics), `friction` (how often you interrupt Claude + which tool was running + dominant error categories), `cache` (prompt-cache efficiency + $ saved), `diff` (period-over-period comparison with per-model movers), `reflect` (a wrapped-style retrospective — busiest day, streak, top models/projects, peak hour, delegation ratio — with a shareable `--html` dashboard), and `limits` (an official-quota **exhaustion forecaster** over Claude Code's `rate_limits`); the standard views take `--csv` for spreadsheet export |
 | `swarmdo usage guard` | **Budget policy** — limits for the active 5h block / today / month via flags or `SWARMDO_GUARD_*` env → ok / warn / over; `--strict` exits 1, safe for CI gates and Stop hooks |
 | `swarmdo hud` | **One-screen ops HUD** — 5h block burn, task readiness, daemon workers, memory snapshots (`--watch`, `--json`) |
 | `swarmdo repair` (alias `tdd-repair`) | **Test-Driven Repair** — a bounded, budget-capped headless `claude` loop that fixes source until a failing test passes; dry-run unless `--confirm` |
@@ -293,6 +293,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo ownership` | **Who owns each file, and what breaks if they leave** — a per-file knowledge map + bus factor from git history: the dominant author, ownership concentration, and the fewest authors whose churn clears 50% (a lone owner is flagged ⚠ key-person), plus a repo-wide truck factor. `--since`, `--min-churn`, `--top`, `--csv`, `--format json`. code-maat main-dev / CodeScene "Knowledge Map"; also an MCP tool (`ownership`). Deterministic |
 | `swarmdo hidden-coupling` | **Co-change with no import edge** — join the two graphs swarmdo already owns (temporal `coupling` from git + `codegraph`'s import graph) and emit the set difference: file pairs that keep changing together yet nothing in the code links them ("logical minus structural coupling" — a config and its consumers, a schema and its mirror type). The co-edit `affected` can't see. `--since`, `--min-shared`, `--csv`, `--format json`. Grounded in Gall et al. (ICSM 1998). Deterministic |
 | `swarmdo standup` (alias `mine`) | **What did I do?** — your commits since your last working day, grouped by day with a diffstat. **Weekend-aware** (git-standup parity): on Monday it reaches back to Friday, on Sunday to Friday, otherwise to yesterday — one-command recall for a standup or for re-orienting at the start of a session. Defaults to the current git user; `--author <name>`/`--all` for teammates, `--days N` or `--since 2w` to override the window, `--format json`. Pure engine (weekend math + per-day fold) → fixture-tested. Deterministic |
+| `swarmdo commands` (alias `slash`) | **Hot/cold/orphan usage report** for your authored `.claude/` surface — which custom slash-commands (`.claude/commands/**`) and subagents (`.claude/agents/**`) you actually invoke (**hot**, with counts), which are **cold** (defined but never used → prune candidates), and which are **orphan** (invoked but undefined → a typo or a builtin). `config lint` says "are these valid?"; this says "are these used?" — joining the defined files against invocation counts mined from local transcripts (`<command-name>` markers + `subagent_type` fields). `--unused` prints just the prune list, `--unused --strict` is a CI gate (exit 1 if anything's dead), `--all` counts across every project, `--json`. Pure parsers + join → fixture-tested |
 | `swarmdo agent bridge` | **Link Claude Code agents ⇄ Swarmdo** — the fix for "Swarmdo is installed but never actually used." Swarmdo can't call Claude Code's `Agent` tool (only the main loop can), so `agent bridge register -n <name>` binds a real Claude Code agent into Swarmdo's registry (`swarmdo agent list` stops being empty) and **auto-spins-up a swarm from your config, enrolling the agent** — the next bind joins the same swarm. `bridge list` (bound vs native), `bridge sync --live a,b` (reconcile drift), `bridge advise "<prompt>"` (should this warrant a swarm? which roles?). Also MCP tools `agent_bridge_register`/`agent_bridge_list`. Pure engine → 16 tests |
 | `swarmdo testreport` | **JUnit/TAP → failure digest** — turn raw test-result files into the exact failing test names + `file:line` + assertion messages, instead of scanning hundreds of log lines. The front-half of the test→fix loop: feed the failures straight into `repair`. Reads a file, a directory, or stdin; `--ci` exits 1 on any failure, `--format json`. Also an MCP tool (`testreport`). Deterministic |
 | `swarmdo integrations` (alias `integrate`) | **Use swarmdo from Codex CLI, GitHub Copilot CLI, and pi** — one command wires AGENTS.md + each CLI's MCP config (idempotent, dry-run first, never touches your Claude Code setup) |
@@ -301,7 +302,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo mcp doctor` | **MCP config diagnosis** — missing binaries, bad URLs, malformed entries across `.mcp.json` + `~/.claude.json` |
 | `swarmdo config lint` | **Static config validation** — the pure shape layer for `swarmdo.config.json`, the `.claude/settings*.json` hooks block, `.mcp.json`, **`.claude/agents/*.md` subagents** (missing `name`/`description`, a `name` duplicated across files — CC silently loads only one — a bad `model`, malformed frontmatter), and **custom slash commands + skills** (malformed YAML that makes CC load empty metadata, a bad `effort`, an inline `` !`cmd` `` bash-injection that's inert or not covered by `allowed-tools`). `--strict` gates CI |
 | `swarmdo permissions` (alias `perms`) | **Audit your Claude Code permission rules** — static analysis of `permissions.allow`/`deny`/`ask` in `.claude/settings*.json`: flags allow↔deny conflicts (dead rules), over-broad `Bash(*)` grants, shadowed/redundant rules, duplicates, and malformed entries. `--strict` gates CI. Read-only; the static-safety sibling of `config lint` / `mcp doctor` |
-| `swarmdo comms` (alias `mailbox`) | **Cross-session agent mailbox** — one Claude Code session messages another by name (`send -t <session>`, `-t all` broadcasts, `inbox`, `read`, `watch`); sessions on the same repo share `.swarmdo/comms/`. `inbox --hook` surfaces new mail as prompt context without polling. Also MCP tools (`comms_send`/`comms_inbox`) |
+| `swarmdo comms` (alias `mailbox`) | **Cross-session, cross-tool agent mailbox** — one agent session (Claude Code, Codex, Copilot, or pi) messages another by name (`send -t <session>`, `-t all` broadcasts, `inbox`, `read`, `watch`); sessions on the same repo share `.swarmdo/comms/`. Non-Claude agents set `$SWARMDO_AGENT` for a stable identity. `inbox --hook` surfaces new mail as prompt context without polling. Also MCP tools (`comms_send`/`comms_inbox`) |
 | `swarmdo hooks memory-inject` | **Prompt-time semantic memory injection** — embeds each prompt, vector-searches your stored memories, and injects the most relevant under a token budget (recall at the moment of need); wire it with `hooks recipe memory-inject` |
 | `swarmdo hooks notify -d` | **Desktop notifications** — OS-native toast (macOS `osascript`, Linux `notify-send`) |
 | `swarmdo hooks recipe` | **One-command Claude Code hooks** — install `notify-done`/`notify-input` (desktop pings), `memory-inject` (relevant memories each prompt), `comms-inbox` (new mail as context), or `command-guard` (a PreToolUse deny hook that blocks dangerous bash — `rm -rf /`, pipe-to-shell, force-push to main — the net swarmdo needs when running headless); dry-run by default, idempotent merge that never clobbers your settings |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.54.1",
+  "version": "1.58.1",
   "description": "Swarmdo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@swarmdo/cli/dist/src/command-usage/usage.d.ts

@@ -0,0 +1,74 @@
+/**
+ * command-usage/usage.ts — a hot/cold/orphan USAGE report for a project's
+ * authored `.claude/` surface. `config lint` validates these files; this answers
+ * the orthogonal "are they actually used?" by joining the DEFINED set
+ * (`.claude/commands/**​/*.md` + `.claude/agents/**​/*.md`) against INVOCATION
+ * counts mined from the local transcripts (`<command-name>` markers +
+ * `"subagent_type"` fields). Three buckets: hot (defined & invoked), cold
+ * (defined, never invoked → prune candidates), orphan (invoked, not defined →
+ * typo / removed / builtin). #101.
+ *
+ * The parsers + join are pure and unit-tested; only collectCommandUsage touches
+ * the filesystem. Reuses defaultClaudeProjectDirs/findTranscriptFiles.
+ */
+export interface UsageItem {
+    name: string;
+    count: number;
+}
+export interface UsageBuckets {
+    /** defined AND invoked (count > 0), desc by count */
+    hot: UsageItem[];
+    /** defined but never invoked — prune candidates, sorted */
+    cold: string[];
+    /** invoked but not defined (typo / removed / builtin), sorted */
+    orphan: string[];
+}
+export interface CommandUsageReport {
+    commands: UsageBuckets;
+    agents: UsageBuckets;
+    filesScanned: number;
+    definedCommands: number;
+    definedAgents: number;
+    scope: 'project' | 'all';
+}
+/**
+ * Count custom slash-command invocations from raw transcript lines. Scoped to
+ * user-role lines (the `<command-name>` marker is injected on the user turn) so
+ * an assistant merely quoting the marker never inflates a count. The captured
+ * name is de-slashed (`/goal` → `goal`) to match the discovered-file key space.
+ * Pure.
+ */
+export declare function parseCommandInvocations(lines: string[]): Map<string, number>;
+/**
+ * Count subagent (Task tool) invocations by `subagent_type` from raw transcript
+ * lines. Not user-scoped — the field lives in an assistant `tool_use` block. Pure.
+ */
+export declare function parseSubagentInvocations(lines: string[]): Map<string, number>;
+/** Merge src counts into dest (dest mutated). */
+export declare function mergeCounts(dest: Map<string, number>, src: Map<string, number>): void;
+/**
+ * Join a DEFINED name list against INVOCATION counts into hot/cold/orphan. Both
+ * sides are compared de-slashed, so a defined `/build` matches a `build` count
+ * (agents carry no slash, so they're unaffected). Pure & deterministic. */
+export declare function joinUsage(defined: string[], counts: Map<string, number> | Record<string, number>): UsageBuckets;
+/**
+ * Discover the authored `.claude/` surface for a project. Command names use
+ * Claude Code's subdir namespacing (`.claude/commands/sDo/x.md` → `sDo:x`, top
+ * level → `x`) to match the `<command-name>` marker; agent names are the file
+ * basename (subagent_type is never namespaced). Pure w.r.t. inputs (reads fs).
+ */
+export declare function discoverAuthored(cwd: string): {
+    commands: string[];
+    agents: string[];
+};
+export interface CollectOptions {
+    cwd?: string;
+    /** scan every project's transcripts (default: only the current project) */
+    all?: boolean;
+}
+/** The encoded transcript-dir name Claude Code uses for a project path. */
+export declare function encodeProjectDir(cwd: string): string;
+/** Build the full report: discover authored files, mine invocation counts from
+ * the (project-scoped, or --all) transcripts, and join. fs-touching wrapper. */
+export declare function collectCommandUsage(opts?: CollectOptions): CommandUsageReport;
+//# sourceMappingURL=usage.d.ts.map

package/v3/@swarmdo/cli/dist/src/command-usage/usage.js

@@ -0,0 +1,161 @@
+/**
+ * command-usage/usage.ts — a hot/cold/orphan USAGE report for a project's
+ * authored `.claude/` surface. `config lint` validates these files; this answers
+ * the orthogonal "are they actually used?" by joining the DEFINED set
+ * (`.claude/commands/**​/*.md` + `.claude/agents/**​/*.md`) against INVOCATION
+ * counts mined from the local transcripts (`<command-name>` markers +
+ * `"subagent_type"` fields). Three buckets: hot (defined & invoked), cold
+ * (defined, never invoked → prune candidates), orphan (invoked, not defined →
+ * typo / removed / builtin). #101.
+ *
+ * The parsers + join are pure and unit-tested; only collectCommandUsage touches
+ * the filesystem. Reuses defaultClaudeProjectDirs/findTranscriptFiles.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defaultClaudeProjectDirs, findTranscriptFiles } from '../usage/transcript-usage.js';
+const uniqSort = (xs) => [...new Set(xs)].sort((a, b) => a.localeCompare(b));
+/**
+ * Count custom slash-command invocations from raw transcript lines. Scoped to
+ * user-role lines (the `<command-name>` marker is injected on the user turn) so
+ * an assistant merely quoting the marker never inflates a count. The captured
+ * name is de-slashed (`/goal` → `goal`) to match the discovered-file key space.
+ * Pure.
+ */
+export function parseCommandInvocations(lines) {
+    const counts = new Map();
+    for (const line of lines) {
+        if (!/"(?:type|role)"\s*:\s*"user"/.test(line))
+            continue;
+        for (const m of line.matchAll(/<command-name>([^<]+)<\/command-name>/g)) {
+            const name = m[1].trim().replace(/^\/+/, '');
+            if (!name || name === '…')
+                continue;
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/**
+ * Count subagent (Task tool) invocations by `subagent_type` from raw transcript
+ * lines. Not user-scoped — the field lives in an assistant `tool_use` block. Pure.
+ */
+export function parseSubagentInvocations(lines) {
+    const counts = new Map();
+    for (const line of lines) {
+        for (const m of line.matchAll(/"subagent_type"\s*:\s*"([^"]+)"/g)) {
+            const name = m[1].trim();
+            if (name)
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/** Merge src counts into dest (dest mutated). */
+export function mergeCounts(dest, src) {
+    for (const [k, v] of src)
+        dest.set(k, (dest.get(k) ?? 0) + v);
+}
+/**
+ * Join a DEFINED name list against INVOCATION counts into hot/cold/orphan. Both
+ * sides are compared de-slashed, so a defined `/build` matches a `build` count
+ * (agents carry no slash, so they're unaffected). Pure & deterministic. */
+export function joinUsage(defined, counts) {
+    const asMap = counts instanceof Map ? counts : new Map(Object.entries(counts));
+    const norm = (n) => n.replace(/^\/+/, '');
+    const get = (n) => asMap.get(norm(n)) ?? 0;
+    const definedNorm = new Set(defined.map(norm));
+    const hot = [];
+    const cold = [];
+    for (const d of defined) {
+        const c = get(d);
+        if (c > 0)
+            hot.push({ name: d, count: c });
+        else
+            cold.push(d);
+    }
+    const orphan = [];
+    for (const [k, v] of asMap) {
+        if (v > 0 && !definedNorm.has(norm(k)))
+            orphan.push(k);
+    }
+    hot.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+    return { hot, cold: uniqSort(cold), orphan: uniqSort(orphan) };
+}
+/** All `.md` files under `root`, as paths RELATIVE to root (recursive; skips
+ * dotfiles). Mirrors config.ts's walkMd so `config lint` and this command agree
+ * on what counts as "defined". */
+function walkMdRel(root) {
+    const out = [];
+    const rec = (dir, prefix) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            const rel = prefix ? `${prefix}/${e.name}` : e.name;
+            if (e.isDirectory())
+                rec(path.join(dir, e.name), rel);
+            else if (e.isFile() && e.name.endsWith('.md'))
+                out.push(rel);
+        }
+    };
+    rec(root, '');
+    return out;
+}
+/**
+ * Discover the authored `.claude/` surface for a project. Command names use
+ * Claude Code's subdir namespacing (`.claude/commands/sDo/x.md` → `sDo:x`, top
+ * level → `x`) to match the `<command-name>` marker; agent names are the file
+ * basename (subagent_type is never namespaced). Pure w.r.t. inputs (reads fs).
+ */
+export function discoverAuthored(cwd) {
+    const commands = walkMdRel(path.join(cwd, '.claude', 'commands')).map((rel) => rel.replace(/\.md$/, '').split('/').join(':'));
+    const agents = walkMdRel(path.join(cwd, '.claude', 'agents')).map((rel) => path.basename(rel).replace(/\.md$/, ''));
+    return { commands: uniqSort(commands), agents: uniqSort(agents) };
+}
+/** The encoded transcript-dir name Claude Code uses for a project path. */
+export function encodeProjectDir(cwd) {
+    return cwd.replace(/\//g, '-');
+}
+/** Build the full report: discover authored files, mine invocation counts from
+ * the (project-scoped, or --all) transcripts, and join. fs-touching wrapper. */
+export function collectCommandUsage(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const { commands: definedCommands, agents: definedAgents } = discoverAuthored(cwd);
+    const encoded = encodeProjectDir(cwd);
+    const cmdCounts = new Map();
+    const agentCounts = new Map();
+    let filesScanned = 0;
+    for (const dir of defaultClaudeProjectDirs()) {
+        for (const t of findTranscriptFiles(dir)) {
+            if (!opts.all && t.project !== encoded)
+                continue;
+            filesScanned++;
+            let content;
+            try {
+                content = fs.readFileSync(t.file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const fileLines = content.split('\n');
+            mergeCounts(cmdCounts, parseCommandInvocations(fileLines));
+            mergeCounts(agentCounts, parseSubagentInvocations(fileLines));
+        }
+    }
+    return {
+        commands: joinUsage(definedCommands, cmdCounts),
+        agents: joinUsage(definedAgents, agentCounts),
+        filesScanned,
+        definedCommands: definedCommands.length,
+        definedAgents: definedAgents.length,
+        scope: opts.all ? 'all' : 'project',
+    };
+}
+//# sourceMappingURL=usage.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * `swarmdo commands` (alias `slash`) — a hot/cold/orphan USAGE report for the
+ * project's authored `.claude/` slash-commands + subagents. `config lint` says
+ * "are these valid?"; this says "are these used?" by joining defined files
+ * against invocation counts mined from the local transcripts. #101.
+ *
+ *   swarmdo commands                # this project's authored surface
+ *   swarmdo commands --all          # count invocations across every project
+ *   swarmdo commands --unused       # only the cold (never-invoked) items
+ *   swarmdo commands --unused --strict   # exit 1 if anything is unused (CI gate)
+ *   swarmdo commands --json         # machine-readable
+ *
+ * Engine (../command-usage/usage.ts) is pure + fixture-tested; this thin layer
+ * renders and applies the --unused/--strict policy.
+ */
+import type { Command } from '../types.js';
+export declare const commandsCommand: Command;
+export default commandsCommand;
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1,107 @@
+/**
+ * `swarmdo commands` (alias `slash`) — a hot/cold/orphan USAGE report for the
+ * project's authored `.claude/` slash-commands + subagents. `config lint` says
+ * "are these valid?"; this says "are these used?" by joining defined files
+ * against invocation counts mined from the local transcripts. #101.
+ *
+ *   swarmdo commands                # this project's authored surface
+ *   swarmdo commands --all          # count invocations across every project
+ *   swarmdo commands --unused       # only the cold (never-invoked) items
+ *   swarmdo commands --unused --strict   # exit 1 if anything is unused (CI gate)
+ *   swarmdo commands --json         # machine-readable
+ *
+ * Engine (../command-usage/usage.ts) is pure + fixture-tested; this thin layer
+ * renders and applies the --unused/--strict policy.
+ */
+import { output } from '../output.js';
+import { collectCommandUsage } from '../command-usage/usage.js';
+/** Render one domain's hot/cold/orphan buckets. `slash` prefixes command names. */
+function renderBuckets(label, defined, b, slash) {
+    const nm = (n) => (slash ? `/${n}` : n);
+    output.writeln('');
+    output.writeln(output.bold(`${label}`) + output.dim(`  (${defined} defined · ${b.hot.length} hot · ${b.cold.length} cold · ${b.orphan.length} orphan)`));
+    if (b.hot.length > 0) {
+        output.printTable({
+            columns: [
+                { key: 'name', header: 'Hot (used)', width: 34 },
+                { key: 'count', header: 'Invocations', width: 12, align: 'right' },
+            ],
+            data: b.hot.map((h) => ({ name: nm(h.name), count: h.count.toLocaleString('en-US') })),
+        });
+    }
+    if (b.cold.length > 0) {
+        output.writeln(output.warning(`  cold (never invoked — prune candidates): `) + b.cold.map(nm).join('  '));
+    }
+    if (b.orphan.length > 0) {
+        output.writeln(output.dim(`  orphan (invoked, not defined — builtin or typo): `) + b.orphan.map(nm).join('  '));
+    }
+    if (b.hot.length === 0 && b.cold.length === 0 && b.orphan.length === 0) {
+        output.writeln(output.dim('  (none)'));
+    }
+}
+/** Print only the cold (unused) items — the prune list. Returns the cold count. */
+function renderUnused(report) {
+    const coldCmds = report.commands.cold;
+    const coldAgents = report.agents.cold;
+    const total = coldCmds.length + coldAgents.length;
+    output.writeln(output.bold('Unused (cold) authored items') + output.dim(`  (${report.scope} scope · ${report.filesScanned} transcript files)`));
+    if (total === 0) {
+        output.writeln(output.info('  none — every authored command and agent has been invoked 🎉'));
+        return 0;
+    }
+    if (coldCmds.length > 0)
+        output.writeln(`  commands: ${coldCmds.map((c) => `/${c}`).join('  ')}`);
+    if (coldAgents.length > 0)
+        output.writeln(`  agents:   ${coldAgents.join('  ')}`);
+    return total;
+}
+async function run(ctx) {
+    const cwd = ctx.cwd || process.cwd();
+    const all = ctx.flags.all === true;
+    const report = collectCommandUsage({ cwd, all });
+    if (ctx.flags.json === true) {
+        output.writeln(JSON.stringify(report, null, 2));
+        return { success: true, exitCode: 0 };
+    }
+    if (report.definedCommands === 0 && report.definedAgents === 0) {
+        output.writeln(output.info('nothing authored — no .claude/commands or .claude/agents in this project'));
+        return { success: true, exitCode: 0 };
+    }
+    if (ctx.flags.unused === true) {
+        const coldCount = renderUnused(report);
+        const strict = ctx.flags.strict === true;
+        const exitCode = strict && coldCount > 0 ? 1 : 0;
+        if (exitCode === 1)
+            output.writeln(output.dim(`exit 1 (--strict + ${coldCount} unused)`));
+        return { success: exitCode === 0, exitCode };
+    }
+    output.writeln(output.bold('Authored .claude/ surface — usage') + output.dim(`  (${report.scope} scope · ${report.filesScanned} transcript files)`));
+    renderBuckets('Commands', report.definedCommands, report.commands, true);
+    renderBuckets('Agents', report.definedAgents, report.agents, false);
+    const totalCold = report.commands.cold.length + report.agents.cold.length;
+    if (totalCold > 0) {
+        output.writeln('');
+        output.writeln(output.dim(`${totalCold} unused — see \`swarmdo commands --unused\` (add --strict for a CI gate)`));
+    }
+    return { success: true, exitCode: 0 };
+}
+export const commandsCommand = {
+    name: 'commands',
+    aliases: ['slash'],
+    description: "Usage report (hot/cold/orphan) for the project's authored .claude/ slash-commands & subagents",
+    options: [
+        { name: 'all', description: 'count invocations across every project (default: current project only)', type: 'boolean', default: false },
+        { name: 'unused', description: 'print only the cold (never-invoked) items — the prune list', type: 'boolean', default: false },
+        { name: 'strict', description: 'with --unused, exit 1 if anything is unused (CI gate)', type: 'boolean', default: false },
+        { name: 'json', description: 'machine-readable output', type: 'boolean', default: false },
+    ],
+    examples: [
+        { command: 'swarmdo commands', description: 'Hot/cold/orphan report for your authored .claude/ surface' },
+        { command: 'swarmdo commands --unused', description: 'List slash-commands & agents you defined but never invoke' },
+        { command: 'swarmdo commands --unused --strict', description: 'CI gate: fail if any authored command/agent is unused' },
+        { command: 'swarmdo slash --all --json', description: 'Cross-project invocation counts as JSON (alias)' },
+    ],
+    action: run,
+};
+export default commandsCommand;
+//# sourceMappingURL=commands.js.map

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

@@ -64,6 +64,10 @@ const commandLoaders = {
     // — commits since your last working day, grouped by day with a diffstat.
     standup: () => import('./standup.js'),
     mine: () => import('./standup.js'), // alias via loader key
+    // Hot/cold/orphan USAGE report for authored .claude/ slash-commands + subagents
+    // — the "dead-code report" for the authoring surface (config lint validates it).
+    commands: () => import('./commands.js'),
+    slash: () => import('./commands.js'), // alias via loader key
     // JUnit/TAP test-result parser (dorny/test-reporter demand) — raw results →
     // failing test + file:line + message; the front-half of the test→fix loop.
     testreport: () => import('./testreport.js'),
@@ -306,7 +310,7 @@ export async function getCommandsByCategory() {
     // three slots from 'statusline' onward (completionsCmd received the
     // statusline module, analyzeCmd received completions, …), scrambling the
     // categorized help. Every load now has a named slot.
-    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, couplingCmd, ownershipCmd, hiddenCouplingCmd, testreportCmd, compactSnapshotCmd, standupCmd,] = await Promise.all([
+    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, couplingCmd, ownershipCmd, hiddenCouplingCmd, testreportCmd, compactSnapshotCmd, standupCmd, commandsUsageCmd,] = await Promise.all([
         loadCommand('daemon'), loadCommand('doctor'), loadCommand('embeddings'), loadCommand('neural'),
         loadCommand('performance'), loadCommand('security'), loadCommand('swarmvector'), loadCommand('hive-mind'),
         loadCommand('config'), loadCommand('statusline'), loadCommand('compress'), loadCommand('efficiency'),
@@ -314,7 +318,7 @@ export async function getCommandsByCategory() {
         loadCommand('analyze'), loadCommand('route'), loadCommand('progress'), loadCommand('providers'),
         loadCommand('plugins'), loadCommand('deployment'), loadCommand('claims'), loadCommand('issues'),
         loadCommand('update'), loadCommand('process'), loadCommand('guidance'), loadCommand('appliance'),
-        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'), loadCommand('license'), loadCommand('sbom'), loadCommand('apply'), loadCommand('hotspots'), loadCommand('affected'), loadCommand('cycles'), loadCommand('coupling'), loadCommand('ownership'), loadCommand('hidden-coupling'), loadCommand('testreport'), loadCommand('compact-snapshot'), loadCommand('standup'),
+        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'), loadCommand('license'), loadCommand('sbom'), loadCommand('apply'), loadCommand('hotspots'), loadCommand('affected'), loadCommand('cycles'), loadCommand('coupling'), loadCommand('ownership'), loadCommand('hidden-coupling'), loadCommand('testreport'), loadCommand('compact-snapshot'), loadCommand('standup'), loadCommand('commands'),
     ]);
     return {
         primary: [
@@ -333,7 +337,7 @@ export async function getCommandsByCategory() {
             statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, couplingCmd, ownershipCmd, hiddenCouplingCmd, testreportCmd, compactSnapshotCmd, efficiencyCmd,
         ].filter(Boolean),
         analysis: [
-            analyzeCmd, routeCmd, progressCmd, usageCmd, hudCmd, codegraphCmd, standupCmd,
+            analyzeCmd, routeCmd, progressCmd, usageCmd, hudCmd, codegraphCmd, standupCmd, commandsUsageCmd,
         ].filter(Boolean),
         management: [
             providersCmd, pluginsCmd, deploymentCmd, claimsCmd,

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

@@ -15,6 +15,7 @@
 import { output } from '../output.js';
 import { aggregateBlocks, aggregateUsage, collectUsage, totalUsage, localDateKey, } from '../usage/transcript-usage.js';
 import { collectToolErrors, delegationFromReport } from '../usage/transcript-errors.js';
+import { collectFriction } from '../usage/transcript-friction.js';
 import { computeCacheStats } from '../usage/cache-stats.js';
 import { evaluateGuard } from '../usage/spend-guard.js';
 import { resolvePeriodPair, parseRange, diffPeriods, modelMovers } from '../usage/diff.js';
@@ -201,6 +202,53 @@ function runErrorsView(ctx, report) {
     }
     return { success: true, exitCode: 0 };
 }
+/** Friction view — how often you interrupt Claude (ESC mid-turn), which tool was
+ * running when you did, and what KIND of errors dominate. The sniffly axes that
+ * `usage errors` (error rate) left on the table (#102). */
+function runFrictionView(ctx, report) {
+    if (ctx.flags.json === true) {
+        output.writeln(JSON.stringify(report, null, 2));
+        return { success: true, exitCode: 0 };
+    }
+    const pct = (v) => `${(v * 100).toFixed(1)}%`;
+    if (ctx.flags.csv === true) {
+        // Category table export (parity with `usage --csv`).
+        const headers = ['category', 'count', 'share'];
+        const rows = report.categories.map((c) => [c.category, c.count, c.share.toFixed(4)]);
+        output.writeln(toCsv(headers, rows));
+        return { success: true, exitCode: 0 };
+    }
+    output.writeln(output.bold('Claude Code usage — friction'));
+    if (report.interruptions === 0 && report.totalErrors === 0) {
+        output.writeln(output.info(`no friction detected in ${report.filesScanned} transcript files`));
+        return { success: true, exitCode: 0 };
+    }
+    output.writeln(output.dim(`${report.filesScanned} files · ${fmtInt(report.interruptions)} interruption${report.interruptions === 1 ? '' : 's'} across ${fmtInt(report.assistantTurns)} assistant turns (${pct(report.interruptionRate)})`));
+    if (report.byTool.length > 0) {
+        output.writeln('');
+        output.writeln(output.bold('Interrupted while running'));
+        output.printTable({
+            columns: [
+                { key: 'tool', header: 'Tool / context', width: 22 },
+                { key: 'count', header: 'Interrupts', width: 12, align: 'right' },
+            ],
+            data: report.byTool.slice(0, 15).map((t) => ({ tool: t.tool, count: fmtInt(t.interruptions) })),
+        });
+    }
+    if (report.categories.length > 0) {
+        output.writeln('');
+        output.writeln(output.bold('Error categories') + output.dim(`  (${fmtInt(report.totalErrors)} tool errors)`));
+        output.printTable({
+            columns: [
+                { key: 'category', header: 'Category', width: 14 },
+                { key: 'count', header: 'Count', width: 10, align: 'right' },
+                { key: 'share', header: 'Share', width: 8, align: 'right' },
+            ],
+            data: report.categories.map((c) => ({ category: c.category, count: fmtInt(c.count), share: pct(c.share) })),
+        });
+    }
+    return { success: true, exitCode: 0 };
+}
 /** Cache view — prompt-cache efficiency + $ saved by caching (the #1 cost lever). */
 function runCacheView(ctx, collection) {
     const stats = computeCacheStats(aggregateUsage(collection.events, 'model'));
@@ -547,6 +595,13 @@ async function run(ctx) {
         const dirs = typeof dirFlag === 'string' ? [dirFlag] : Array.isArray(dirFlag) ? dirFlag.map(String) : undefined;
         return runErrorsView(ctx, collectToolErrors({ dirs, since, until }));
     }
+    if (viewName === 'friction') {
+        const since = typeof ctx.flags.since === 'string' ? ctx.flags.since : undefined;
+        const until = typeof ctx.flags.until === 'string' ? ctx.flags.until : undefined;
+        const dirFlag = ctx.flags.dir;
+        const dirs = typeof dirFlag === 'string' ? [dirFlag] : Array.isArray(dirFlag) ? dirFlag.map(String) : undefined;
+        return runFrictionView(ctx, collectFriction({ dirs, since, until }));
+    }
     if (viewName === 'cache') {
         const since = typeof ctx.flags.since === 'string' ? ctx.flags.since : undefined;
         const until = typeof ctx.flags.until === 'string' ? ctx.flags.until : undefined;
@@ -574,7 +629,7 @@ async function run(ctx) {
     }
     const view = VIEWS[viewName];
     if (!view) {
-        output.writeln(output.error(`unknown view: ${viewName} (expected ${Object.keys(VIEWS).join('|')}|blocks|errors|cache|guard|diff|reflect|limits)`));
+        output.writeln(output.error(`unknown view: ${viewName} (expected ${Object.keys(VIEWS).join('|')}|blocks|errors|friction|cache|guard|diff|reflect|limits)`));
         return { success: false, exitCode: 1 };
     }
     const since = typeof ctx.flags.since === 'string' ? ctx.flags.since : undefined;
@@ -667,6 +722,7 @@ export const usageCommand = {
         { command: 'swarmdo usage projects --json', description: 'Per-project totals as JSON' },
         { command: 'swarmdo usage monthly --csv > usage.csv', description: 'Export monthly spend to CSV' },
         { command: 'swarmdo cost sessions --limit 10', description: 'Ten most expensive sessions (alias)' },
+        { command: 'swarmdo usage friction', description: 'How often you interrupt Claude + which error kinds dominate' },
     ],
     action: run,
 };

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

@@ -14,7 +14,17 @@ export declare const RETENTION: {
 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". */
+/**
+ * This session's name, in precedence order:
+ *   explicit override (flag/param)
+ *   → $SWARMDO_SESSION   (set by Claude Code)
+ *   → $SWARMDO_AGENT     (harness-neutral — Codex/Copilot/pi agents export this)
+ *   → hostname → "me".
+ *
+ * The $SWARMDO_AGENT fallback lets a non-Claude agent declare a stable identity
+ * once (instead of passing `from`/`--self` on every call); without it, every
+ * agent on a host collapses to the shared hostname and direct addressing breaks.
+ */
 export declare function resolveSelf(flag?: unknown): string;
 /** Crypto-strong message id. */
 export declare function newMessageId(): string;

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

@@ -32,10 +32,24 @@ export function saveMailbox(cwd, box) {
     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". */
+/**
+ * This session's name, in precedence order:
+ *   explicit override (flag/param)
+ *   → $SWARMDO_SESSION   (set by Claude Code)
+ *   → $SWARMDO_AGENT     (harness-neutral — Codex/Copilot/pi agents export this)
+ *   → hostname → "me".
+ *
+ * The $SWARMDO_AGENT fallback lets a non-Claude agent declare a stable identity
+ * once (instead of passing `from`/`--self` on every call); without it, every
+ * agent on a host collapses to the shared hostname and direct addressing breaks.
+ */
 export function resolveSelf(flag) {
     const f = typeof flag === 'string' ? flag.trim() : '';
-    return f || (process.env.SWARMDO_SESSION || '').trim() || hostname() || 'me';
+    return (f ||
+        (process.env.SWARMDO_SESSION || '').trim() ||
+        (process.env.SWARMDO_AGENT || '').trim() ||
+        hostname() ||
+        'me');
 }
 /** Crypto-strong message id. */
 export function newMessageId() {