claude-multi-session 2.3.0 → 2.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.3.0",
+  "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,6 +66,23 @@ Your inbox may contain:
 - Dependency artifacts you need before starting
 - Updated instructions from the orchestrator
 
+### 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 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
+
 ### Step 2: UPDATE YOUR STATUS
 Call \`mcp__multi-session__team_update_status\` to set yourself as "active" with your current task.
 
@@ -137,6 +154,8 @@ IMPORTANT: Follow these rules strictly. Violating them causes coordination failu
 
 8. **If you are blocked, say so.** Update your status to "busy" with a note about what you're waiting for, and send a \`team_ask\` to the teammate who can unblock you.
 
+9. **ALWAYS use relative file paths in code.** When creating database files, configs, or any path in generated code, use RELATIVE paths (e.g., \`path.join(__dirname, '..', 'data.db')\`). NEVER hardcode absolute paths like \`C:\\...\` or \`/home/...\` — they break portability.
+
 <examples>
 
 <example>
@@ -458,6 +477,8 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 - Do NOT fix bugs found by one session yourself — tell that session to fix them
 - Do NOT act as a message router between sessions — they can talk directly
 - 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
 
 === CORRECT PATTERN ===
 1. Plan the work and identify parallel tasks
@@ -474,6 +495,59 @@ Break the user's request into independent work units. Identify:
 - What tasks are SEQUENTIAL (B needs output from A)
 - What ROLES are needed (backend, frontend, testing, etc.)
 
+### Phase 1.5: Define Shared Conventions
+IMPORTANT: Before spawning workers, define shared conventions that ALL workers must follow. Either:
+(a) Publish a conventions artifact that workers will read, OR
+(b) Include the same convention rules in every worker's prompt
+
+Conventions MUST cover:
+- **Response format:** e.g., "All endpoints return { data: <result> } for success"
+- **Error format:** e.g., "All errors return { error: <message> }"
+- **Status codes:** e.g., "201 for create, 200 for update/delete/read, 404 for not found, 400 for validation"
+- **Naming:** e.g., "snake_case for DB fields (in_progress not in-progress)"
+- **File paths:** "Use relative paths only — never absolute"
+
+\`\`\`
+// Example: publish conventions before spawning workers
+mcp__multi-session__artifact_publish({
+  artifactId: "shared-conventions",
+  type: "api-contract",
+  name: "Shared API Conventions",
+  data: {
+    responseFormat: "{ data: <result> }",
+    errorFormat: "{ error: <message> }",
+    statusCodes: { create: 201, read: 200, update: 200, delete: 200, notFound: 404, badRequest: 400 },
+    naming: "snake_case for DB fields",
+    paths: "relative only, never absolute"
+  }
+})
+\`\`\`
+
+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:
 
@@ -675,10 +749,15 @@ const ROLE_PROMPTS = {
 
   'testing': `
 ### Role-Specific: Test Engineer
-- ALWAYS check artifact_list for API contracts and schemas before writing tests
-- If dependencies are not yet published, use team_ask to check when they'll be ready
+- CRITICAL: NEVER assume response format, status codes, or field names. Before writing ANY test:
+  1. Check \`artifact_list\` for a shared-conventions or api-contract artifact
+  2. If found, use \`artifact_get\` to read it and match your assertions to those conventions
+  3. If NOT found, use \`team_ask\` to ask route/API workers: "What response format and status codes do your endpoints use?"
+  4. Only write tests AFTER you know the exact response shape
 - 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
+- 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': `
@@ -762,6 +841,8 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 
 1. **Plan** — Break the user's request into independent work units. Identify what can run in PARALLEL vs what is SEQUENTIAL.
 
+1.5. **Define Conventions** — Before spawning, define shared conventions (response format, status codes, naming) either as a published artifact or in each worker's prompt. Workers CANNOT coordinate on conventions after they start — define them upfront.
+
 2. **Spawn** — Use \`team_spawn\` to launch all independent workers in a SINGLE message with multiple tool calls. This makes them run in parallel. NEVER spawn workers one at a time sequentially.
 
 3. **Tell workers** — Every worker prompt MUST include instructions to:
@@ -773,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.
@@ -819,6 +902,7 @@ IMPORTANT: Always tell workers in their prompt to:
 3. Publish results as artifacts (\`artifact_publish\`)
 4. Broadcast completion (\`team_broadcast\`)
 5. Update their status when done (\`team_update_status\`)
+6. Follow shared conventions you defined (include the convention rules in the prompt OR tell them to read the conventions artifact)
 `;
 
 const ORCHESTRATOR_DELEGATE = `
@@ -859,7 +943,7 @@ WHY: Specific file, exact error, expected behavior, and how to verify.
 const ORCHESTRATOR_MONITORING = `
 ## How to Monitor Without Micromanaging
 
-Check progress periodically — do NOT read full outputs from workers:
+You MUST check progress using these tools after spawning workers — do NOT fall back to filesystem checks (Glob, Read) to verify worker output:
 
 \`\`\`
 mcp__multi-session__team_roster()      — See who's active/idle/blocked
@@ -867,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 |