claude-multi-session 2.3.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.3.1",
+  "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/artifact-store.js

@@ -469,6 +469,45 @@ class ArtifactStore {
     }
   }
 
+  /**
+   * Track that a session read an artifact
+   * @param {string} artifactId - The artifact that was read
+   * @param {string} reader - The session name that read it
+   * @param {number} version - The version that was read
+   */
+  trackRead(artifactId, reader, version) {
+    if (!reader) return; // Skip if no reader identified
+
+    const readsPath = path.join(this.dataDir, artifactId, 'reads.json');
+
+    // Read existing reads log
+    let reads = readJsonSafe(readsPath, []);
+
+    // Add this read event
+    reads.push({
+      reader,
+      version,
+      readAt: new Date().toISOString(),
+    });
+
+    // Write back (not immutable — reads are append-only log)
+    const dir = path.join(this.dataDir, artifactId);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(readsPath, JSON.stringify(reads, null, 2));
+  }
+
+  /**
+   * Get the read log for an artifact
+   * @param {string} artifactId - The artifact to check
+   * @returns {Array} Array of read events: [{ reader, version, readAt }]
+   */
+  getReads(artifactId) {
+    const readsPath = path.join(this.dataDir, artifactId, 'reads.json');
+    return readJsonSafe(readsPath, []);
+  }
+
   /**
    * List artifacts with optional filtering
    * @param {Object} [filters={}] - Filter criteria
@@ -497,6 +536,17 @@ class ArtifactStore {
       results = results.filter(item => item.tags && item.tags.includes(tag));
     }
 
+    // Enrich with read counts
+    results = results.map(item => {
+      const reads = this.getReads(item.artifactId);
+      const uniqueReaders = [...new Set(reads.map(r => r.reader))];
+      return {
+        ...item,
+        readCount: reads.length,
+        uniqueReaders,
+      };
+    });
+
     return results;
   }
 

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,12 +572,15 @@ 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: {
         artifactId: { type: 'string', description: 'Artifact ID to retrieve' },
         version:    { type: 'number', description: 'Specific version number (omit for latest)' },
+        reader:     { type: 'string', description: 'Session name reading this artifact (for tracking who consumed it)' },
         team:       { type: 'string', description: 'Team name (default: "default")' },
       },
       required: ['artifactId'],
@@ -582,6 +602,20 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'artifact_readers',
+    description:
+      'Check who has read a specific artifact. Use this to verify that workers actually consumed shared artifacts like conventions or schemas.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID to check readers for' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId'],
+    },
+  },
+
   {
     name: 'artifact_history',
     description:
@@ -1124,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);
@@ -1161,6 +1199,8 @@ async function executeTool(toolName, args) {
         return handleArtifactGet(args);
       case 'artifact_list':
         return handleArtifactList(args);
+      case 'artifact_readers':
+        return handleArtifactReaders(args);
       case 'artifact_history':
         return handleArtifactHistory(args);
 
@@ -1580,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
 // =============================================================================
@@ -1867,7 +1933,13 @@ function handleArtifactGet(args) {
       return errorResult(`Artifact ${args.artifactId} not found`);
     }
 
-    return textResult(JSON.stringify({
+    // Track this read if a reader was specified
+    if (args.reader) {
+      artifactStore.trackRead(args.artifactId, args.reader, artifact.version);
+    }
+
+    // Build the response
+    const response = {
       artifactId: artifact.artifactId,
       version: artifact.version,
       type: artifact.type,
@@ -1878,7 +1950,15 @@ function handleArtifactGet(args) {
       summary: artifact.summary,
       lineage: artifact.lineage,
       team: teamName,
-    }, null, 2));
+      readBy: artifactStore.getReads(args.artifactId),
+    };
+
+    // 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);
   }
@@ -1908,6 +1988,8 @@ function handleArtifactList(args) {
         createdAt: a.createdAt,
         updatedAt: a.updatedAt,
         tags: a.tags,
+        readCount: a.readCount,
+        uniqueReaders: a.uniqueReaders,
       })),
     }, null, 2));
   } catch (err) {
@@ -1915,6 +1997,25 @@ function handleArtifactList(args) {
   }
 }
 
+function handleArtifactReaders(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { artifactStore } = getTeamInstances(teamName);
+
+    const reads = artifactStore.getReads(args.artifactId);
+    const uniqueReaders = [...new Set(reads.map(r => r.reader))];
+
+    return textResult(JSON.stringify({
+      artifactId: args.artifactId,
+      totalReads: reads.length,
+      uniqueReaders,
+      reads,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
 function handleArtifactHistory(args) {
   try {
     const teamName = args.team || 'default';
@@ -2453,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
 // =============================================================================
@@ -2522,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

@@ -66,15 +66,25 @@ Your inbox may contain:
 - Dependency artifacts you need before starting
 - Updated instructions from the orchestrator
 
-### Step 1.5: CHECK FOR SHARED CONVENTIONS
-Call \`mcp__multi-session__artifact_list\` and look for a conventions or API contract artifact.
-If one exists, call \`mcp__multi-session__artifact_get\` to read it and follow those conventions STRICTLY.
-Conventions may define: response format, status codes, naming rules, error format, file path rules.
+### Step 1.5: CHECK FOR SHARED CONVENTIONS AND DEPENDENCY ARTIFACTS
+Call \`mcp__multi-session__artifact_list\` and look for:
+- A conventions or API contract artifact (e.g., "shared-conventions")
+- Any dependency artifacts your task requires (e.g., "db-schema" if you're building routes)
 
-If NO convention artifact exists AND your work must match other workers' output:
+If found, call \`mcp__multi-session__artifact_get\` with your session name as the \`reader\` parameter:
+\`\`\`
+mcp__multi-session__artifact_get({ artifactId: "shared-conventions", reader: "${name}" })
+mcp__multi-session__artifact_get({ artifactId: "db-schema", reader: "${name}" })
+\`\`\`
+
+IMPORTANT: The \`reader\` parameter tracks that you consumed the artifact. This is how the orchestrator verifies workers actually read shared data. ALWAYS include your session name as \`reader\`.
+
+Follow the conventions STRICTLY. If NO convention artifact exists AND your work must match other workers' output:
 - 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.
 
@@ -112,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 |
 
@@ -466,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
@@ -517,6 +528,34 @@ mcp__multi-session__artifact_publish({
 
 NEVER assume workers will independently agree on conventions. Define them explicitly.
 
+### Phase Gate: VERIFY Before Spawning
+=== CRITICAL: MANDATORY VERIFICATION STEP ===
+Before spawning ANY worker that depends on a previous phase's output, you MUST:
+1. Call \`artifact_list()\` to confirm the dependency artifact was published
+2. Call \`artifact_get(artifactId)\` to confirm the artifact contains valid data
+3. ONLY THEN spawn the dependent workers
+
+Example phased workflow:
+\`\`\`
+// Phase 1: Spawn the database worker
+team_spawn({ name: "db-worker", ... })
+
+// PHASE GATE: Verify before Phase 2
+artifact_list()  // Confirm "db-schema" appears
+artifact_get({ artifactId: "db-schema" })  // Confirm it has valid table definitions
+
+// Phase 2: NOW spawn route workers (they depend on the schema)
+team_spawn({ name: "api-worker", ... })
+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:
 
@@ -565,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:
+
+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 intervene when:
-- A session status shows "BLOCKED" for more than a reasonable time
-- A contract has failed
-- The user asks for a status update
+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:
@@ -726,6 +763,7 @@ const ROLE_PROMPTS = {
 - Publish test results as artifacts with type "test-results" including: passed, failed, skipped counts and failure details
 - If tests fail due to bugs in another session's code, use \`team_send_message\` to notify them with the exact error and file path
 - Use the correct status values as defined in the database schema (e.g., "in_progress" not "in-progress")
+- IMPORTANT: When calling artifact_get, ALWAYS include reader: "<your-session-name>" so the orchestrator can verify you read the artifacts
 `,
 
   'database': `
@@ -822,7 +860,9 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 
 4. **Set up dependencies** — Use \`contract_create\` if Task B needs output from Task A.
 
-5. **Monitor** — Check progress with \`team_roster()\`, \`contract_list()\`, \`artifact_list()\`. Only intervene when a worker is BLOCKED or FAILED.
+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. **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.
 
@@ -907,14 +947,30 @@ WHY: Specific file, exact error, expected behavior, and how to verify.
 `;
 
 const ORCHESTRATOR_MONITORING = `
-## How to Monitor Without Micromanaging
+## Post-Phase Verification (MANDATORY)
+
+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:
 
-You MUST check progress using these tools after spawning workers — do NOT fall back to filesystem checks (Glob, Read) to verify worker output:
+### Verification Checklist (run between EVERY pair of phases)
+\`\`\`
+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
+\`\`\`
+
+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
+mcp__multi-session__artifact_readers({ artifactId: "db-schema" }) — Check who read it
+\`\`\`
 
+After all workers complete, verify every worker consumed the artifacts they needed:
 \`\`\`
-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_readers({ artifactId: "shared-conventions" })
+// Should list ALL route workers as readers
 \`\`\`
 
 ### When to Intervene
@@ -937,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 ===