claude-multi-session 2.3.2 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.3.2",
+  "version": "2.5.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 |
 
@@ -470,12 +472,17 @@ You have access to a Multi-Session MCP server that lets you spawn and coordinate
 
 IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR — not to do the implementation work yourself. Delegate implementation to worker sessions.
 
+## Step 0: Verify Your Tools
+Before starting ANY orchestration work, call \`server_version()\` to verify you're running the latest MCP tools. If the response shows a version mismatch, tell the user to restart Claude Code before proceeding — stale tools cause phantom failures.
+
 ## CORE PRINCIPLE: Orchestrate, Don't Implement
 
 === 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 create project foundation files (package.json, db.js, app.js, server.js) yourself — spawn a setup worker for Phase 0
 - 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
@@ -487,6 +494,25 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 4. Monitor progress via team_roster and contract_list
 5. Only intervene if a session is stuck or failed
 
+=== FIX PROTOCOL (when you must fix worker code directly) ===
+STOP. Before editing any file a worker created, answer these questions:
+
+1. Is this fix ≤ 3 lines?
+   NO → send_message to worker or spawn fix-worker. Do NOT fix yourself.
+   YES → continue to step 2.
+
+2. Is the worker done (idle status in team_roster)?
+   NO → send_message to worker. Do NOT fix yourself.
+   YES → continue to step 3.
+
+3. Make the fix.
+
+4. Broadcast: team_broadcast({ from: "orchestrator", content: "Fixed [file]:[lines] — [description of change]" })
+
+5. Re-publish: If the fix changes data in a published artifact, call artifact_publish to update it.
+
+NEVER skip steps 4-5. Unannounced fixes cause downstream workers to use stale assumptions.
+
 ## STEP-BY-STEP: How to Run a Multi-Session Project
 
 ### Phase 1: Plan
@@ -495,17 +521,45 @@ 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 0: Foundation Setup (if needed)
+If the project needs shared infrastructure (database connection, app skeleton, package.json, shared utilities), spawn a **setup worker** as Phase 0 BEFORE other workers.
+
+=== CRITICAL: DO NOT create foundation files yourself — delegate to a setup worker ===
+
+\`\`\`
+mcp__multi-session__team_spawn({
+  name: "setup",
+  role: "project setup",
+  task: "Create project foundation: package.json, database connection, app skeleton",
+  prompt: "Initialize the project. Create package.json, install dependencies, set up the database connection file, and create the Express app skeleton. When done, publish a 'project-foundation' artifact listing all files you created and any connection details (DB path, port, etc.). Then broadcast completion and set status to idle."
+})
+\`\`\`
+
+Wait for the setup worker to finish and publish its artifact. Then run the PHASE GATE CHECKPOINT before spawning Phase 1 workers.
+
+NOT every project needs Phase 0. Skip it if:
+- The project already has package.json and dependencies installed
+- There's no shared infrastructure to set up
+- The foundation is trivial (1-2 config lines that fit in each worker's prompt)
+
 ### 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"
+=== CONVENTION CHECKLIST (define every item before spawning) ===
+□ Response format: e.g., { data: <result> }
+□ Error format: e.g., { error: <message> }
+□ Status codes: create=201, read=200, update=200, delete=200, notFound=404, badRequest=400, conflict=409
+□ Naming: e.g., snake_case for DB columns, camelCase for JS variables
+□ File paths: relative only, never absolute
+□ Enum/status values: list EXACT strings (e.g., "pending", "in_progress", "completed" — NOT "Pending" or "InProgress")
+□ Boolean handling: true/false vs 1/0 — pick one, specify it
+□ Date format: ISO 8601 strings, Unix timestamps, or other — specify which
+□ Audit/log action names: exact strings (e.g., "created" vs "create" vs "CREATE")
+□ Shared column names: list exact DB column names for tables multiple workers reference
+
+Missing even ONE item causes convention mismatches that the orchestrator then has to fix manually — which violates Rule 6.
 
 \`\`\`
 // Example: publish conventions before spawning workers
@@ -526,28 +580,36 @@ 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 CHECKPOINT (fill in and run before EVERY team_spawn after Phase 0) ===
 
-// PHASE GATE: Verify before Phase 2
-artifact_list()  // Confirm "db-schema" appears
-artifact_get({ artifactId: "db-schema" })  // Confirm it has valid table definitions
+Before spawning the next phase, STOP and fill in this checklist:
 
-// Phase 2: NOW spawn route workers (they depend on the schema)
-team_spawn({ name: "api-worker", ... })
-team_spawn({ name: "test-worker", ... })
-\`\`\`
+Phase completing: ___  →  Phase starting: ___
+
+1. artifact_list()
+   Expected artifacts: [___]
+   All present? YES / NO
+
+2. artifact_get({ artifactId: "___", reader: "orchestrator" })
+   Content valid and complete? YES / NO
+
+3. team_roster()
+   All previous-phase workers idle? YES / NO
+
+4. artifact_readers({ artifactId: "___" })
+   All expected consumers listed? YES / NO (skip if Phase 0→1)
+
+PROCEED ONLY IF all answers are YES.
+If any is NO → diagnose and fix before continuing.
 
 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 0: [foundation], Phase 1: [routes], Phase 2: [tests], ..."
+If you have N phases, you MUST fill in this checkpoint exactly N-1 times.
+
 ### Phase 2: Spawn Workers (use team_spawn, NOT delegate_task)
 Spawn all independent workers at once. Example:
 
@@ -596,18 +658,8 @@ 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
-\`\`\`
-
-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
+### Between Every Phase: Run the Phase Gate Checkpoint
+After ALL workers in a phase complete, run the PHASE GATE CHECKPOINT above before spawning the next phase. This is NOT optional. N phases = N-1 checkpoints. 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:
@@ -837,11 +889,15 @@ const ORCHESTRATOR_QUICK_START = `
 
 IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR — not to implement code yourself.
 
-### The 6-Step Protocol
+### The Protocol
+
+0. **Verify tools** — Call \`server_version()\` to confirm you're running the latest MCP server. If versions mismatch, tell the user to restart Claude Code.
+
+0.5. **Foundation** — If the project needs shared infrastructure (database, app skeleton, package.json), spawn a \`setup\` worker as Phase 0. Wait for its \`project-foundation\` artifact before proceeding. Do NOT create foundation files yourself.
 
 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.
+1.5. **Define Conventions** — Before spawning, fill in the CONVENTION CHECKLIST: response format, error format, status codes, naming, file paths, exact enum values, boolean handling, date format, audit action names, and shared column names. Publish as an artifact OR embed in every worker's prompt. Missing conventions = test failures you'll have to fix yourself.
 
 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.
 
@@ -856,7 +912,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,28 +997,33 @@ 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 the Phase Gate Checkpoint. Do NOT fall back to filesystem checks (Glob, Read) to verify worker output — use these tools:
 
-\`\`\`
-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 Gate Checkpoint (run between EVERY pair of phases)
 
-### 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
-\`\`\`
+Before spawning the next phase, STOP and fill in this checklist:
 
-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
-\`\`\`
+Phase completing: ___  →  Phase starting: ___
+
+1. artifact_list()
+   Expected artifacts: [___]
+   All present? YES / NO
+
+2. artifact_get({ artifactId: "___", reader: "orchestrator" })
+   Content valid and complete? YES / NO
+
+3. team_roster()
+   All previous-phase workers idle? YES / NO
+
+4. artifact_readers({ artifactId: "___" })
+   All expected consumers listed? YES / NO
+
+PROCEED ONLY IF all answers are YES.
+If any is NO → diagnose and fix before continuing.
+
+If you have N phases, you MUST fill in this checkpoint exactly N-1 times.
 
 ### When to Intervene
 
@@ -984,7 +1045,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. For trivial fixes, follow the FIX PROTOCOL above (steps 1-5: check size → check worker status → fix → broadcast → re-publish)
 - Do NOT act as a message router between workers — they can use \`team_ask\` directly
 
 === ANTI-PATTERN — DO NOT DO THIS ===