claude-multi-session 2.3.1 → 2.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "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

@@ -561,6 +561,7 @@ const TOOLS = [
       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 +583,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:
@@ -1161,6 +1176,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);
 
@@ -1867,6 +1884,11 @@ function handleArtifactGet(args) {
       return errorResult(`Artifact ${args.artifactId} not found`);
     }
 
+    // Track this read if a reader was specified
+    if (args.reader) {
+      artifactStore.trackRead(args.artifactId, args.reader, artifact.version);
+    }
+
     return textResult(JSON.stringify({
       artifactId: artifact.artifactId,
       version: artifact.version,
@@ -1878,6 +1900,7 @@ function handleArtifactGet(args) {
       summary: artifact.summary,
       lineage: artifact.lineage,
       team: teamName,
+      readBy: artifactStore.getReads(args.artifactId),
     }, null, 2));
   } catch (err) {
     return errorResult(err.message);
@@ -1908,6 +1931,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 +1940,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';

package/src/prompts.js

@@ -66,12 +66,20 @@ 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
 
@@ -517,6 +525,29 @@ 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 2: Spawn Workers (use team_spawn, NOT delegate_task)
 Spawn all independent workers at once. Example:
 
@@ -726,6 +757,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,6 +854,8 @@ 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.
 
+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.
 
 6. **Collect** — When all workers are idle, check \`artifact_list\` for published outputs and summarize results for the user.
@@ -917,6 +951,19 @@ mcp__multi-session__contract_list()     — See contract statuses
 mcp__multi-session__artifact_list()     — See published outputs
 \`\`\`
 
+### Phase Gate 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__artifact_readers({ artifactId: "shared-conventions" })
+// Should list ALL route workers as readers
+\`\`\`
+
 ### When to Intervene
 
 | Worker Status | What to Do |