claude-multi-session 2.3.2 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Multi-session orchestrator for Claude Code CLI — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically",
   "main": "src/index.js",
   "bin": {

package/src/mcp-server.js

@@ -25,6 +25,8 @@
  *   - tools/call         → execute a tool and return result
  */
 
+const fs = require('fs');
+const path = require('path');
 const readline = require('readline');
 const SessionManager = require('./manager');
 const Delegate = require('./delegate');
@@ -47,6 +49,9 @@ const DecisionJournal = require('./decision-journal');
 const PatternRegistry = require('./pattern-registry');
 const StaleDetector = require('./stale-detector');
 
+// Capture version at load time — used to detect stale server processes
+const LOADED_VERSION = require('../package.json').version;
+
 // =============================================================================
 // Server State — persists across all tool calls
 // =============================================================================
@@ -390,6 +395,18 @@ const TOOLS = [
     },
   },
 
+  // ── Server Version ─────────────────────────────────────────────────────
+  {
+    name: 'server_version',
+    description:
+      'Check the running MCP server version and detect staleness. ' +
+      'Call this if tools seem missing or behave unexpectedly.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+
   // ══════════════════════════════════════════════════════════════════════════
   // TEAM HUB v2 — 32 new tools for team collaboration
   // ══════════════════════════════════════════════════════════════════════════
@@ -555,7 +572,9 @@ const TOOLS = [
   {
     name: 'artifact_get',
     description:
-      'Read an artifact (latest version or specific version).',
+      'Read an artifact (latest version or specific version). ' +
+      'IMPORTANT: Pass your session name as the "reader" parameter to track artifact consumption. ' +
+      'The orchestrator uses this to verify workers actually read shared data.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1139,6 +1158,10 @@ async function executeTool(toolName, args) {
       case 'abort_task':
         return handleAbort(args);
 
+      // ── Server Version ──────────────────────────────────────────────
+      case 'server_version':
+        return handleServerVersion(args);
+
       // ── Orchestrator Guide ────────────────────────────────────────────
       case 'get_orchestrator_guide':
         return handleGetOrchestratorGuide(args);
@@ -1597,6 +1620,32 @@ function handleGetOrchestratorGuide(args) {
   return textResult(guide);
 }
 
+/**
+ * Check the running MCP server version and detect staleness.
+ * Compares the version loaded into memory at startup against the
+ * version currently installed on disk (package.json).
+ */
+function handleServerVersion() {
+  let installedVersion = LOADED_VERSION;
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    installedVersion = pkg.version;
+  } catch (e) {
+    // If we can't read package.json at runtime, use loaded version
+  }
+
+  const stale = LOADED_VERSION !== installedVersion;
+  return textResult(JSON.stringify({
+    running: LOADED_VERSION,
+    installed: installedVersion,
+    stale,
+    message: stale
+      ? `Server is stale: running v${LOADED_VERSION} but v${installedVersion} is installed. Restart Claude Code to load new tools.`
+      : `Server is up to date (v${LOADED_VERSION}).`
+  }, null, 2));
+}
+
 // =============================================================================
 // Team Hub Handlers — Layer 1, 2, 3
 // =============================================================================
@@ -1889,7 +1938,8 @@ function handleArtifactGet(args) {
       artifactStore.trackRead(args.artifactId, args.reader, artifact.version);
     }
 
-    return textResult(JSON.stringify({
+    // Build the response
+    const response = {
       artifactId: artifact.artifactId,
       version: artifact.version,
       type: artifact.type,
@@ -1901,7 +1951,14 @@ function handleArtifactGet(args) {
       lineage: artifact.lineage,
       team: teamName,
       readBy: artifactStore.getReads(args.artifactId),
-    }, null, 2));
+    };
+
+    // Add nudge if reader param was not provided
+    if (!args.reader) {
+      response._hint = 'Tip: Pass your session name as the "reader" parameter to track artifact consumption. Example: artifact_get({ artifactId: "...", reader: "your-session-name" })';
+    }
+
+    return textResult(JSON.stringify(response, null, 2));
   } catch (err) {
     return errorResult(err.message);
   }
@@ -2497,6 +2554,28 @@ function errorResult(message) {
   return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
 }
 
+/**
+ * Append a staleness warning to tool results if the server version is outdated.
+ * Reads package.json from disk on each call to detect post-install version drift.
+ * @param {Object} result - The tool result object
+ * @returns {Object} The result, possibly with a staleness warning appended
+ */
+function appendStalenessWarning(result) {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (pkg.version !== LOADED_VERSION) {
+      const warning = `\n\n⚠️ STALE SERVER: Running v${LOADED_VERSION} but v${pkg.version} is installed. Restart Claude Code to load updated tools.`;
+      if (result && result.content && result.content[0] && result.content[0].text) {
+        result.content[0].text += warning;
+      }
+    }
+  } catch (e) {
+    // Silently ignore — staleness check is best-effort
+  }
+  return result;
+}
+
 // =============================================================================
 // MCP Protocol Handler — JSON-RPC 2.0 over stdio
 // =============================================================================
@@ -2566,7 +2645,9 @@ async function handleMessage(message) {
         break;
       }
       try {
-        const result = await executeTool(params.name, params.arguments || {});
+        let result = await executeTool(params.name, params.arguments || {});
+        // Append staleness warning if server version is outdated
+        result = appendStalenessWarning(result);
         sendResponse(id, result);
       } catch (err) {
         sendResponse(id, errorResult(err.message));

package/src/prompts.js

@@ -83,6 +83,8 @@ Follow the conventions STRICTLY. If NO convention artifact exists AND your work
 - Use \`team_ask\` to ask the relevant teammate about their format BEFORE writing code
 - NEVER guess or assume format — mismatches cause test failures
 
+Note: team_ask is a **fallback mechanism** for when information wasn't available upfront. If your orchestrator provided thorough prompts with all needed context and conventions, you may never need team_ask — this is the ideal case.
+
 ### Step 2: UPDATE YOUR STATUS
 Call \`mcp__multi-session__team_update_status\` to set yourself as "active" with your current task.
 
@@ -120,7 +122,7 @@ mcp__multi-session__team_broadcast({ from: "${name}", content: "Completed: <what
 | \`team_check_inbox\` | BEFORE starting work, AFTER major steps |
 | \`team_send_message\` | Direct message to a specific teammate |
 | \`team_broadcast\` | Announce something to ALL teammates |
-| \`team_ask\` | Ask a teammate a question and WAIT for reply |
+| \`team_ask\` | Ask a teammate a question and WAIT for reply (fallback — use when info wasn't provided upfront) |
 | \`team_reply\` | Reply to a question you received (IMMEDIATELY) |
 | \`team_update_status\` | Update what you're working on |
 
@@ -474,8 +476,9 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 
 === CRITICAL: ANTI-PATTERN — DO NOT DO THIS ===
 - Do NOT spawn a session, read its output, then manually relay that output to another session
-- Do NOT fix bugs found by one session yourself — tell that session to fix them
+- Do NOT fix bugs found by one session yourself UNLESS the fix is ≤ 3 lines AND the worker session has completed. For trivial fixes, you may fix directly but MUST broadcast the change and re-publish any affected artifacts
 - Do NOT act as a message router between sessions — they can talk directly
+- Note: team_ask is a **fallback** for unexpected ambiguity. In well-orchestrated projects where you provide all context upfront in worker prompts, team_ask may never be called — this is the ideal case and means your prompts were thorough enough.
 - Do NOT do implementation work that should be delegated
 - Do NOT fix code yourself when a worker's tests fail — send corrections to the worker that wrote the failing code
 - Do NOT assume workers will agree on response formats — define shared conventions before spawning
@@ -548,6 +551,11 @@ team_spawn({ name: "test-worker", ... })
 
 NEVER skip verification. NEVER rely on a worker's self-reported completion — verify the artifact exists yourself.
 
+=== PHASE COUNTING RULE ===
+At the start of planning, count and list your phases explicitly:
+"Phase 1: [description], Phase 2: [description], ..."
+This creates a self-check — you can verify you ran the verification checklist between each pair.
+
 ### Phase 2: Spawn Workers (use team_spawn, NOT delegate_task)
 Spawn all independent workers at once. Example:
 
@@ -596,18 +604,16 @@ mcp__multi-session__contract_create({
 })
 \`\`\`
 
-### Phase 4: Monitor (Don't Micromanage)
-Check progress periodically:
-\`\`\`
-mcp__multi-session__team_roster()      — See who's active/idle/blocked
-mcp__multi-session__contract_list()     — See contract statuses
-mcp__multi-session__artifact_list()     — See published outputs
-\`\`\`
+### Phase 4: Post-Phase Verification (MANDATORY)
+After ALL workers in a phase complete, and BEFORE spawning the next phase, you MUST run this verification checklist:
 
-Only intervene when:
-- A session status shows "BLOCKED" for more than a reasonable time
-- A contract has failed
-- The user asks for a status update
+1. \`artifact_list()\` — confirm all expected artifacts from this phase exist
+2. \`artifact_get()\` on each critical artifact — verify the content is valid and complete
+3. \`team_roster()\` — confirm all phase workers show 'idle' or 'done' status
+
+Only proceed to the next phase when ALL checks pass.
+
+IMPORTANT: Count your phases at the start of planning. If you have N phases, you MUST perform this verification checklist exactly N-1 times (between every adjacent pair of phases). Skipping verification for later phases is the #1 cause of test failures in multi-session projects.
 
 ### Phase 5: Collect Results
 When all workers are done:
@@ -856,7 +862,7 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 
 4.5. **Phase Gate** — Before spawning workers that depend on previous workers' output, VERIFY the dependency artifact exists by calling \`artifact_list()\` and \`artifact_get()\`. Never trust self-reported completion — verify the artifact.
 
-5. **Monitor** — Check progress with \`team_roster()\`, \`contract_list()\`, \`artifact_list()\`. Only intervene when a worker is BLOCKED or FAILED.
+5. **Post-Phase Verification** — After each phase completes, run the verification checklist: \`artifact_list()\` to confirm artifacts exist, \`artifact_get()\` to verify content, \`team_roster()\` to confirm workers are idle. Only proceed when all checks pass. If you have N phases, verify N-1 times.
 
 6. **Collect** — When all workers are idle, check \`artifact_list\` for published outputs and summarize results for the user.
 
@@ -941,17 +947,20 @@ WHY: Specific file, exact error, expected behavior, and how to verify.
 `;
 
 const ORCHESTRATOR_MONITORING = `
-## How to Monitor Without Micromanaging
+## Post-Phase Verification (MANDATORY)
 
-You MUST check progress using these tools after spawning workers — do NOT fall back to filesystem checks (Glob, Read) to verify worker output:
+After ALL workers in a phase complete, and BEFORE spawning the next phase, you MUST run this verification checklist. Do NOT fall back to filesystem checks (Glob, Read) to verify worker output — use these tools:
 
+### Verification Checklist (run between EVERY pair of phases)
 \`\`\`
-mcp__multi-session__team_roster()      — See who's active/idle/blocked
-mcp__multi-session__contract_list()     — See contract statuses
-mcp__multi-session__artifact_list()     — See published outputs
+mcp__multi-session__artifact_list()     — Confirm all expected artifacts from this phase exist
+mcp__multi-session__artifact_get()      — Verify each critical artifact has valid, complete content
+mcp__multi-session__team_roster()       — Confirm all phase workers show 'idle' or 'done' status
 \`\`\`
 
-### Phase Gate Verification
+Only proceed to the next phase when ALL checks pass.
+
+### Dependency Verification
 Between spawn phases, use these to verify dependencies:
 \`\`\`
 mcp__multi-session__artifact_get({ artifactId: "db-schema" })     — Verify artifact content
@@ -984,7 +993,7 @@ When a worker is BLOCKED:
 
 NEVER do these:
 - Do NOT read the worker's full output to understand the problem — their status message should tell you
-- Do NOT implement the fix yourself — tell the worker to fix it
+- Do NOT implement fixes > 3 lines yourself — tell the worker to fix it or spawn a fix-worker. For trivial fixes (≤ 3 lines) where the worker is already done, you may fix directly but MUST broadcast the change and re-publish affected artifacts
 - Do NOT act as a message router between workers — they can use \`team_ask\` directly
 
 === ANTI-PATTERN — DO NOT DO THIS ===