feat(desires): add doctor check and sm_desire_paths MCP tool

- Doctor: reports tool failure count in last 7d, warns on unknown tools
- MCP tool: sm_desire_paths with summary/list modes, category filter, days param
- Reads from ~/.stackmemory/desire-paths/*.jsonl (written by Phase 3 hook)

Author: StackMemory Bot (CLI)

src/cli/commands/setup.ts

@@ -6,7 +6,14 @@
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+} from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
@@ -593,7 +600,66 @@ export function createDoctorCommand(): Command {
         }
       }
 
-      // 11. Check file permissions
+      // 11. Check desire paths (unmet agent needs in last 7d)
+      {
+        const desireDir = join(homedir(), '.stackmemory', 'desire-paths');
+        if (existsSync(desireDir)) {
+          try {
+            const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+            const files = readdirSync(desireDir).filter(
+              (f) => f.startsWith('desire-') && f.endsWith('.jsonl')
+            );
+            let totalFailures = 0;
+            let unknownTools = 0;
+            for (const file of files) {
+              const lines = readFileSync(join(desireDir, file), 'utf-8')
+                .split('\n')
+                .filter(Boolean);
+              for (const line of lines) {
+                try {
+                  const entry = JSON.parse(line);
+                  if (new Date(entry.ts).getTime() < cutoff) continue;
+                  totalFailures++;
+                  if (entry.category === 'unknown_tool') unknownTools++;
+                } catch {
+                  // skip malformed
+                }
+              }
+            }
+            if (totalFailures > 0) {
+              results.push({
+                name: 'Desire Paths',
+                status: unknownTools > 0 ? 'warn' : 'ok',
+                message: `${totalFailures} tool failures in last 7d (${unknownTools} unknown tools)`,
+                fix:
+                  unknownTools > 0
+                    ? 'Run: stackmemory desires summary'
+                    : undefined,
+              });
+            } else {
+              results.push({
+                name: 'Desire Paths',
+                status: 'ok',
+                message: 'No tool failures in last 7d',
+              });
+            }
+          } catch {
+            results.push({
+              name: 'Desire Paths',
+              status: 'ok',
+              message: 'Desire path logging active (no data yet)',
+            });
+          }
+        } else {
+          results.push({
+            name: 'Desire Paths',
+            status: 'ok',
+            message: 'Desire path logging not yet active',
+          });
+        }
+      }
+
+      // 12. Check file permissions
       const homeStackmemory = join(homedir(), '.stackmemory');
       if (existsSync(homeStackmemory)) {
         try {

src/integrations/mcp/server.ts

@@ -20,11 +20,13 @@ import {
 } from './schemas.js';
 import {
   readFileSync,
+  readdirSync,
   existsSync,
   mkdirSync,
   writeFileSync,
   appendFileSync,
 } from 'fs';
+import { homedir } from 'os';
 import { compactPlan } from '../../orchestrators/multimodal/utils.js';
 import { filterPending } from './pending-utils.js';
 import { join, dirname } from 'path';
@@ -1797,6 +1799,10 @@ class LocalStackMemoryMCP {
               result = await this.handleSmDigest(args);
               break;
 
+            case 'sm_desire_paths':
+              result = this.handleDesirePaths(args);
+              break;
+
             default:
               throw new Error(`Unknown tool: ${name}`);
           }
@@ -3589,6 +3595,128 @@ ${typeBreakdown}`,
     }
   }
 
+  /** Handle sm_desire_paths tool — read and aggregate desire path logs */
+  private handleDesirePaths(args: Record<string, unknown>) {
+    const mode = String(args.mode || 'summary');
+    const days = Number(args.days || 7);
+    const limit = Number(args.limit || 20);
+    const categoryFilter = args.category ? String(args.category) : undefined;
+
+    const desireDir = join(homedir(), '.stackmemory', 'desire-paths');
+
+    if (!existsSync(desireDir)) {
+      return {
+        content: [{ type: 'text', text: 'No desire path data found.' }],
+      };
+    }
+
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const files = readdirSync(desireDir).filter(
+      (f) => f.startsWith('desire-') && f.endsWith('.jsonl')
+    );
+
+    interface DesireEntry {
+      ts: string;
+      tool: string;
+      error: string;
+      category: string;
+      cwd?: string;
+      source?: string;
+    }
+
+    const entries: DesireEntry[] = [];
+    for (const file of files) {
+      const lines = readFileSync(join(desireDir, file), 'utf-8')
+        .split('\n')
+        .filter(Boolean);
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line) as DesireEntry;
+          if (new Date(entry.ts).getTime() < cutoff) continue;
+          if (categoryFilter && entry.category !== categoryFilter) continue;
+          entries.push(entry);
+        } catch {
+          // skip malformed
+        }
+      }
+    }
+
+    if (entries.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `No desire path data in the last ${days} day(s).`,
+          },
+        ],
+      };
+    }
+
+    if (mode === 'list') {
+      const recent = entries
+        .sort((a, b) => b.ts.localeCompare(a.ts))
+        .slice(0, limit);
+
+      const lines = recent.map(
+        (e) =>
+          `${e.ts.slice(0, 19)} ${e.tool} [${e.category}]\n  ${e.error.slice(0, 120)}`
+      );
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Recent desire paths (${recent.length}/${entries.length}):\n\n${lines.join('\n\n')}`,
+          },
+        ],
+      };
+    }
+
+    // Summary mode
+    const byTool = new Map<
+      string,
+      { count: number; category: string; lastSeen: string }
+    >();
+    for (const e of entries) {
+      const existing = byTool.get(e.tool);
+      if (!existing || e.ts > existing.lastSeen) {
+        byTool.set(e.tool, {
+          count: (existing?.count || 0) + 1,
+          category: e.category,
+          lastSeen: e.ts,
+        });
+      } else {
+        existing.count++;
+      }
+    }
+
+    const sorted = [...byTool.entries()].sort(
+      (a, b) => b[1].count - a[1].count
+    );
+
+    const byCat = new Map<string, number>();
+    for (const e of entries) {
+      byCat.set(e.category, (byCat.get(e.category) || 0) + 1);
+    }
+
+    const toolLines = sorted.map(
+      ([tool, data]) =>
+        `${tool}: ${data.count}x [${data.category}] (last: ${data.lastSeen.slice(0, 10)})`
+    );
+    const catLines = [...byCat.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .map(([cat, count]) => `  ${cat}: ${count}`);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Desire Path Summary (last ${days}d, ${entries.length} total failures)\n\nBy Tool:\n${toolLines.join('\n')}\n\nBy Category:\n${catLines.join('\n')}`,
+        },
+      ],
+    };
+  }
+
   private async handleSmDigest(args: any) {
     const period = String(args.period || 'today') as DigestPeriod;
     if (!['today', 'yesterday', 'week'].includes(period)) {

src/integrations/mcp/tool-definitions.ts

@@ -35,6 +35,7 @@ export class MCPToolDefinitions {
       ...this.getTeamTools(),
       ...this.getCordTools(),
       ...this.getDigestTools(),
+      ...this.getDesirePathTools(),
     ];
   }
 
@@ -1231,6 +1232,45 @@ export class MCPToolDefinitions {
     ];
   }
 
+  /**
+   * Desire path analysis tools
+   */
+  private getDesirePathTools(): MCPToolDefinition[] {
+    return [
+      {
+        name: 'sm_desire_paths',
+        description:
+          'Analyze failed tool calls (desire paths) — what agents want but cannot get. Use mode "summary" for aggregated counts or "list" for recent failures.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mode: {
+              type: 'string',
+              enum: ['summary', 'list'],
+              description: 'Output mode: summary (aggregated) or list (recent)',
+              default: 'summary',
+            },
+            limit: {
+              type: 'number',
+              default: 20,
+              description: 'Max entries to return (list mode only)',
+            },
+            category: {
+              type: 'string',
+              enum: ['unknown_tool', 'handler_error', 'invalid_params'],
+              description: 'Filter by failure category',
+            },
+            days: {
+              type: 'number',
+              default: 7,
+              description: 'Look back N days',
+            },
+          },
+        },
+      },
+    ];
+  }
+
   /**
    * Multi-agent team collaboration tools
    */
@@ -1513,6 +1553,8 @@ export class MCPToolDefinitions {
         return this.getCordTools();
       case 'digest':
         return this.getDigestTools();
+      case 'desire_paths':
+        return this.getDesirePathTools();
       default:
         return [];
     }