claude-multi-session 2.5.0 → 2.6.0

package/bin/setup.js

@@ -43,6 +43,10 @@ const CLAUDE_MD_END_MARKER = '<!-- claude-multi-session:end -->';
 
 // This teaches the main Claude session how to orchestrate team workers.
 // Wrapped in markers so we can find and remove it later.
+//
+// IMPORTANT: This content MUST stay in sync with docs/ORCHESTRATOR-CLAUDE.md.
+// When updating rules or adding features, update BOTH files.
+// Failure to sync caused all test runs 1-6 to use stale orchestrator rules.
 const STRATEGY_CONTENT = `
 ${CLAUDE_MD_START_MARKER}
 
@@ -52,11 +56,39 @@ You have access to a Multi-Session MCP server (\`mcp__multi-session__*\` tools)
 
 IMPORTANT: When the user asks you to build something complex (more than 2 related tasks), use the multi-session system to parallelize the work instead of doing everything yourself.
 
+## 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.
+
+## How to Orchestrate
+
+### Rule 0: Define shared conventions BEFORE spawning workers
+Before spawning workers, fill in the CONVENTION CHECKLIST. Either publish as an artifact (\`shared-conventions\`) or embed in every worker's prompt.
+
+=== 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.
+
+NEVER assume workers will independently agree on conventions — they won't.
+
 ### Rule 1: You are the ORCHESTRATOR — not the implementer
 - Plan the work, spawn workers, monitor progress
 - Do NOT implement code yourself when you can delegate
+- Do NOT create project foundation files (package.json, db.js, app.js, server.js) yourself — spawn a setup worker for Phase 0
 - Do NOT read full outputs from workers — check artifacts and contract status instead
 
+**Phase 0: Foundation Setup** — If the project needs shared infrastructure (database, app skeleton, package.json), spawn a \`setup\` worker FIRST. Wait for its \`project-foundation\` artifact before spawning other workers. Do NOT create these files yourself.
+
 ### Rule 2: Use team_spawn for multi-session work
 IMPORTANT: Spawn ALL independent workers in a SINGLE message with multiple tool calls. This makes them run in parallel.
 
@@ -64,10 +96,39 @@ IMPORTANT: Spawn ALL independent workers in a SINGLE message with multiple tool
 - Workers have team_ask, team_send_message, team_broadcast tools
 - They can publish and read artifacts directly
 - You should NOT relay messages between them
+- If workers need each other's output, tell them to use team_ask
+- Note: team_ask is a **fallback** for unexpected ambiguity. In well-orchestrated projects where you provide all context upfront, team_ask may never be called — this is the ideal case.
+
+### Rule 4: Post-Phase Verification (MANDATORY)
+After ALL workers in a phase complete, BEFORE spawning the next phase, STOP and fill in this checklist:
 
-### Rule 4: Monitor without micromanaging
-Use \`team_roster()\`, \`contract_list()\`, \`artifact_list()\` to check progress.
-Only intervene when a session is BLOCKED or FAILED.
+=== PHASE GATE CHECKPOINT (use phase_gate tool before EVERY team_spawn after Phase 0) ===
+
+Instead of manually running 4 separate tool calls, use the \`phase_gate\` tool which does ALL checks in one call:
+
+\`\`\`
+mcp__multi-session__phase_gate({
+  phase_completing: "Phase 0: Foundation",
+  phase_starting: "Phase 1: Routes",
+  expected_artifacts: ["project-foundation", "shared-conventions"],
+  expected_idle: ["setup"],
+  expected_readers: { "shared-conventions": ["api-dev", "db-dev"] }
+})
+\`\`\`
+
+The tool automatically:
+1. Checks all expected artifacts exist
+2. Validates artifact content and tracks the read as "orchestrator"
+3. Verifies all previous-phase workers are idle
+4. Confirms expected consumers actually read the artifacts
+
+Returns a structured pass/fail report with recommendation.
+PROCEED ONLY IF the report says ALL CHECKS PASSED.
+
+Count your phases upfront. If you have N phases, fill in this checkpoint exactly N-1 times (between every adjacent pair of phases). Skipping verification for later phases is the #1 cause of test failures.
+
+Only intervene in workers when a session is BLOCKED or FAILED.
+Do NOT verify worker output by reading files directly — check artifacts instead.
 
 ### Rule 5: Always tell workers to publish artifacts
 Every worker prompt should include instructions to:
@@ -76,22 +137,65 @@ Every worker prompt should include instructions to:
 3. Publish output as artifacts (\`artifact_publish\`)
 4. Broadcast completion (\`team_broadcast\`)
 5. Update status to idle when done (\`team_update_status\`)
+6. Follow shared conventions defined in Rule 0 (include them in the prompt or reference the conventions artifact)
+
+### Rule 6: Don't fix worker code yourself (pragmatic exception for trivial fixes)
+
+=== 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.
+
+If the failure is due to convention mismatch (wrong response format, etc.), that's YOUR fault — update the conventions and notify the affected workers.
+
+### Rule 7: Verify artifacts between phases (Phase Gates)
+Use the PHASE GATE CHECKPOINT from Rule 4 between every pair of phases. This is the same checklist — Rule 7 reinforces that it applies to EVERY phase transition, not just the first one.
+
+After all workers finish, verify they consumed shared artifacts:
+\`\`\`
+mcp__multi-session__artifact_readers({ artifactId: "shared-conventions" })
+\`\`\`
+This shows which workers actually read the conventions. If a worker is missing, they may have ignored the shared contract.
+
+NEVER trust a worker's self-reported completion — verify the artifact exists yourself.
+
+## Quick Reference
 
-### Quick Reference
 | You want to... | Use this tool |
 |----------------|---------------|
-| Multi-person project (3+ tasks) | \`team_spawn\` (multiple in parallel) |
-| Single isolated task | \`delegate_task\` |
-| Check who's working | \`team_roster\` |
+| Verify tools before starting | \`server_version\` |
+| Build a multi-person project | \`team_spawn\` (multiple in parallel) |
+| Run a single isolated task | \`delegate_task\` |
+| Check who's working on what | \`team_roster\` |
 | See published outputs | \`artifact_list\` |
-| Task completion status | \`contract_list\` |
-| Send correction to worker | \`send_message\` to that session |
+| See task completion status | \`contract_list\` |
+| Send a correction to a worker | \`send_message\` to that session |
+| Check who read an artifact | \`artifact_readers\` |
+| Verify phase completion | \`phase_gate\` |
+| Clean up between runs | \`team_reset\` |
 
 ### When NOT to Delegate
 - Simple tasks (< 5 min, < 3 files) — do it yourself
 - Just reading/exploring — use Read, Grep, Glob directly
 - Tightly coupled changes — must happen atomically
 
+### Resetting Between Runs
+Call \`team_reset({ confirm: true })\` to clean up all team state between orchestration runs. This clears artifacts, contracts, roster, and messages.
+
 ${CLAUDE_MD_END_MARKER}
 `;
 
@@ -305,8 +409,27 @@ function addGuide(scope) {
     existing = fs.readFileSync(claudeMdPath, 'utf-8');
   }
 
-  // Check if our section already exists (avoid duplicates)
+  // Check if our section already exists
   if (existing.includes(CLAUDE_MD_START_MARKER)) {
+    // Extract current content between markers and compare with latest
+    const startIdx = existing.indexOf(CLAUDE_MD_START_MARKER);
+    const endIdx = existing.indexOf(CLAUDE_MD_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1) {
+      const currentContent = existing.slice(startIdx, endIdx + CLAUDE_MD_END_MARKER.length).trim();
+      const newContent = STRATEGY_CONTENT.trim();
+      if (currentContent === newContent) {
+        result.skipped = true;
+        return result;
+      }
+      // Content is stale — replace our section, preserve user's other content
+      const before = existing.slice(0, startIdx).trimEnd();
+      const after = existing.slice(endIdx + CLAUDE_MD_END_MARKER.length).trimStart();
+      const updated = (before ? before + '\n\n' : '') + newContent + (after ? '\n\n' + after : '\n');
+      fs.writeFileSync(claudeMdPath, updated, 'utf-8');
+      result.updated = true;
+      return result;
+    }
+    // Malformed markers — skip to be safe
     result.skipped = true;
     return result;
   }
@@ -410,10 +533,15 @@ function runPostinstallHint() {
       write('  Run "cms-setup" to configure orchestrator guide.');
       write('');
     } else {
-      // Already registered — just print a hint
+      // Already registered — check if CLAUDE.md guide needs updating
       write('');
-      write('  claude-multi-session: Already configured.');
-      write('  Run "cms-setup" to reconfigure or "cms-setup --uninstall" to remove.');
+      const guideResult = addGuide('global');
+      if (guideResult.updated) {
+        write('  claude-multi-session: Orchestrator guide updated in ~/.claude/CLAUDE.md');
+        write('  Restart Claude Code to use the latest rules.');
+      } else {
+        write('  claude-multi-session: Already configured and up to date.');
+      }
       write('');
     }
   } catch {
@@ -563,9 +691,19 @@ async function runInteractiveSetup(flags) {
   if (wantGuide === null) {
     // Tell the user what will happen before they confirm
     if (guideAlreadyInjected) {
-      // Already there — no need to ask
-      clack.log.info(`Orchestrator guide already in ${guideDisplayPath} — nothing to do.`);
-      wantGuide = false;
+      // Check if content is stale
+      const currentFile = fs.readFileSync(guideTargetPath, 'utf-8');
+      const startIdx = currentFile.indexOf(CLAUDE_MD_START_MARKER);
+      const endIdx = currentFile.indexOf(CLAUDE_MD_END_MARKER);
+      const currentContent = currentFile.slice(startIdx, endIdx + CLAUDE_MD_END_MARKER.length).trim();
+      const isStale = currentContent !== STRATEGY_CONTENT.trim();
+      if (isStale) {
+        clack.log.warn(`Orchestrator guide in ${guideDisplayPath} is outdated.`);
+        wantGuide = true; // Auto-update — addGuide handles the replacement
+      } else {
+        clack.log.info(`Orchestrator guide in ${guideDisplayPath} is up to date.`);
+        wantGuide = false;
+      }
     } else if (guideFileExists) {
       // File exists — reassure user their content is safe
       clack.log.info(`Found existing ${guideDisplayPath} — your content will be preserved.`);
@@ -599,8 +737,10 @@ async function runInteractiveSetup(flags) {
   if (wantGuide) {
     const guideResult = addGuide(scope);
 
-    if (guideResult.skipped) {
-      clack.log.warn('Orchestrator guide already in CLAUDE.md — skipped.');
+    if (guideResult.updated) {
+      clack.log.success(`Updated orchestrator guide in ${guideDisplayPath} (new rules synced)`);
+    } else if (guideResult.skipped) {
+      clack.log.info('Orchestrator guide already up to date — skipped.');
     } else if (guideResult.created) {
       clack.log.success(`Created ${guideDisplayPath} with orchestrator guide`);
     } else {

package/package.json

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

@@ -278,13 +278,29 @@ class Delegate {
 
   /**
    * Handle a permission denial by sending approval.
+   * Max 2 retries to prevent infinite permission loops.
    */
   async _handlePermissionRetry(name, deniedText) {
+    // Track retry count per session
+    if (!this._permRetries) this._permRetries = new Map();
+    const retries = (this._permRetries.get(name) || 0) + 1;
+    this._permRetries.set(name, retries);
+
+    if (retries > 2) {
+      return null; // Give up after 2 retries
+    }
+
     try {
       const response = await this.manager.send(
         name,
         'Yes, you have permission. Go ahead and proceed with all file operations. Do not ask for permission again — you are fully authorized.'
       );
+
+      // Check if response still indicates permission denial
+      if (response && this._isPermissionDenied(response.text)) {
+        return null; // Still denied, don't retry further
+      }
+
       return response;
     } catch (err) {
       return null;

package/src/mcp-server.js

@@ -27,6 +27,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const readline = require('readline');
 const SessionManager = require('./manager');
 const Delegate = require('./delegate');
@@ -84,6 +85,11 @@ let currentTeamName = null;
  * @returns {Object} Object with all team instances
  */
 function getTeamInstances(teamName = 'default') {
+  // Validate team name to prevent path traversal attacks
+  if (!/^[a-zA-Z0-9_-]+$/.test(teamName)) {
+    throw new Error(`Invalid team name "${teamName}": must contain only alphanumeric characters, hyphens, and underscores`);
+  }
+
   // If team name changed or instances not yet created, recreate them
   if (!teamHub || currentTeamName !== teamName) {
     teamHub = new TeamHub(teamName);
@@ -428,6 +434,7 @@ const TOOLS = [
         model:  { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model to use (default: sonnet)' },
         permission_mode: { type: 'string', enum: ['default', 'acceptEdits', 'bypassPermissions', 'plan'], description: 'Permission mode. Use bypassPermissions to allow sessions to write files without approval (default: bypassPermissions)' },
         team:   { type: 'string', description: 'Team name (default: "default")' },
+        work_dir: { type: 'string', description: 'Working directory for the session (default: current directory)' },
       },
       required: ['name', 'prompt'],
     },
@@ -951,6 +958,43 @@ const TOOLS = [
     },
   },
 
+  // ── Phase Gate & Team Reset ─────────────────────────────────────────
+  {
+    name: 'phase_gate',
+    description:
+      'Run all 4 phase gate checks in a single call. Verifies: (1) expected artifacts exist, ' +
+      '(2) artifact content is valid, (3) all previous-phase workers are idle, (4) expected consumers read artifacts. ' +
+      'Returns a structured pass/fail report. Use this BETWEEN every pair of phases.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase_completing:    { type: 'string', description: 'Name of the phase that just completed (e.g. "Phase 0: Foundation")' },
+        phase_starting:      { type: 'string', description: 'Name of the phase about to start (e.g. "Phase 1: Routes")' },
+        expected_artifacts:  { type: 'array', items: { type: 'string' }, description: 'Artifact IDs that should exist before proceeding' },
+        expected_idle:       { type: 'array', items: { type: 'string' }, description: 'Worker names that should be idle (optional — if omitted, checks ALL roster members)' },
+        expected_readers:    { type: 'object', description: 'Map of artifactId -> array of expected reader names. E.g. {"shared-conventions": ["api-dev", "db-dev"]}' },
+        team:                { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['phase_completing', 'phase_starting', 'expected_artifacts'],
+    },
+  },
+
+  {
+    name: 'team_reset',
+    description:
+      'Reset all team state — clear artifacts, contracts, roster, messages. ' +
+      'Use this between orchestration runs to start fresh. Optionally preserve specific artifacts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team:               { type: 'string', description: 'Team name (default: "default")' },
+        preserve_artifacts: { type: 'array', items: { type: 'string' }, description: 'Artifact IDs to keep (optional)' },
+        confirm:            { type: 'boolean', description: 'Must be true to execute (safety check)' },
+      },
+      required: ['confirm'],
+    },
+  },
+
   // ── Session Continuity (Layer 0) ──────────────────────────────────────
   {
     name: 'continuity_snapshot',
@@ -1109,6 +1153,37 @@ const TOOLS = [
   }
 ];
 
+// =============================================================================
+// Staleness Warning — cached check for version drift
+// =============================================================================
+
+/**
+ * Check if the server is stale and return a warning string if so.
+ * Called on every tool response to ensure stale servers are noticed.
+ */
+function getStalenessWarning() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (LOADED_VERSION !== pkg.version) {
+      return `\n\n⚠️ STALE SERVER: Running v${LOADED_VERSION} but v${pkg.version} is installed. Restart Claude Code to load updated tools.`;
+    }
+  } catch (e) {
+    // Ignore — can't check staleness
+  }
+  return '';
+}
+
+// Cache the staleness check result for 60 seconds to avoid reading package.json on every call
+let _stalenessCache = { warning: '', checkedAt: 0 };
+function getCachedStalenessWarning() {
+  const now = Date.now();
+  if (now - _stalenessCache.checkedAt > 60000) {
+    _stalenessCache = { warning: getStalenessWarning(), checkedAt: now };
+  }
+  return _stalenessCache.warning;
+}
+
 // =============================================================================
 // Tool Handlers — execute each tool and return result
 // =============================================================================
@@ -1252,6 +1327,12 @@ async function executeTool(toolName, args) {
       case 'team_replay':
         return await handleTeamReplay(args);
 
+      // ── Phase Gate & Team Reset ──
+      case 'phase_gate':
+        return handlePhaseGate(args);
+      case 'team_reset':
+        return handleTeamReset(args);
+
       // ── Session Continuity (Layer 0) handlers ──
       case 'continuity_snapshot': {
         const snap = new SessionSnapshot(args.projectPath);
@@ -1687,6 +1768,7 @@ async function handleTeamSpawn(args) {
       model: args.model,
       systemPrompt: teamSystemPrompt,
       permissionMode: args.permission_mode || 'bypassPermissions',
+      workDir: args.work_dir || process.cwd(),
     });
 
     const result = {
@@ -1704,6 +1786,12 @@ async function handleTeamSpawn(args) {
       result.turns = response.turns;
     }
 
+    // Auto version check on first spawn
+    const staleness = getCachedStalenessWarning();
+    if (staleness) {
+      result._staleness_warning = `Server is stale! ${staleness.trim()}`;
+    }
+
     return textResult(JSON.stringify(result, null, 2));
   } catch (err) {
     return errorResult(err.message);
@@ -1953,9 +2041,9 @@ function handleArtifactGet(args) {
       readBy: artifactStore.getReads(args.artifactId),
     };
 
-    // Add nudge if reader param was not provided
+    // Add prominent warning 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" })';
+      response._WARNING = '⚠️ UNTRACKED READ: You did not pass the "reader" parameter. This read will NOT be tracked. The orchestrator cannot verify you consumed this artifact. Fix: artifact_get({ artifactId: "' + args.artifactId + '", reader: "YOUR-SESSION-NAME" })';
     }
 
     return textResult(JSON.stringify(response, null, 2));
@@ -1979,18 +2067,22 @@ function handleArtifactList(args) {
     return textResult(JSON.stringify({
       team: teamName,
       count: artifacts.length,
-      artifacts: artifacts.map(a => ({
-        artifactId: a.artifactId,
-        type: a.type,
-        name: a.name,
-        publisher: a.publisher,
-        latestVersion: a.latestVersion,
-        createdAt: a.createdAt,
-        updatedAt: a.updatedAt,
-        tags: a.tags,
-        readCount: a.readCount,
-        uniqueReaders: a.uniqueReaders,
-      })),
+      artifacts: artifacts.map(a => {
+        const reads = artifactStore.getReads(a.artifactId);
+        const readers = [...new Set(reads.map(r => r.reader))];
+        return {
+          artifactId: a.artifactId,
+          type: a.type,
+          name: a.name,
+          publisher: a.publisher,
+          latestVersion: a.latestVersion,
+          createdAt: a.createdAt,
+          updatedAt: a.updatedAt,
+          tags: a.tags,
+          readCount: reads.length,
+          readers: readers,
+        };
+      }),
     }, null, 2));
   } catch (err) {
     return errorResult(err.message);
@@ -2543,37 +2635,289 @@ async function handleTeamReplay(args) {
 }
 
 // =============================================================================
-// Result Helpers
+// Phase Gate & Team Reset Handlers
 // =============================================================================
 
-function textResult(text) {
-  return { content: [{ type: 'text', text }] };
-}
+function handlePhaseGate(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { artifactStore, teamHub } = getTeamInstances(teamName);
 
-function errorResult(message) {
-  return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    const report = {
+      gate: `${args.phase_completing} → ${args.phase_starting}`,
+      timestamp: new Date().toISOString(),
+      checks: [],
+      passed: true,
+    };
+
+    // Check 1: Expected artifacts exist
+    const allArtifacts = artifactStore.list({});
+    const existingIds = new Set(allArtifacts.map(a => a.artifactId));
+    const artifactCheck = {
+      check: 'artifacts_exist',
+      expected: args.expected_artifacts,
+      found: [],
+      missing: [],
+      passed: true,
+    };
+
+    for (const id of args.expected_artifacts) {
+      if (existingIds.has(id)) {
+        artifactCheck.found.push(id);
+      } else {
+        artifactCheck.missing.push(id);
+        artifactCheck.passed = false;
+      }
+    }
+    report.checks.push(artifactCheck);
+
+    // Check 2: Artifact content valid (get each artifact with reader="orchestrator")
+    const contentCheck = {
+      check: 'artifacts_valid',
+      results: [],
+      passed: true,
+    };
+
+    for (const id of artifactCheck.found) {
+      const artifact = artifactStore.get(id);
+      // Track read as orchestrator
+      artifactStore.trackRead(id, 'orchestrator', artifact?.version);
+
+      if (!artifact) {
+        contentCheck.results.push({ artifactId: id, valid: false, reason: 'Could not read artifact' });
+        contentCheck.passed = false;
+      } else if (!artifact.data || (typeof artifact.data === 'object' && Object.keys(artifact.data).length === 0)) {
+        contentCheck.results.push({ artifactId: id, valid: false, reason: 'Artifact data is empty' });
+        contentCheck.passed = false;
+      } else {
+        contentCheck.results.push({
+          artifactId: id,
+          valid: true,
+          version: artifact.version,
+          publisher: artifact.publisher,
+          summary: artifact.summary || '(no summary)',
+        });
+      }
+    }
+    report.checks.push(contentCheck);
+
+    // Check 3: Workers idle
+    const roster = teamHub.getRoster();
+    const idleCheck = {
+      check: 'workers_idle',
+      results: [],
+      passed: true,
+    };
+
+    const workersToCheck = args.expected_idle
+      ? roster.filter(m => args.expected_idle.includes(m.name))
+      : roster;
+
+    for (const member of workersToCheck) {
+      const isIdle = member.status === 'idle';
+      idleCheck.results.push({
+        name: member.name,
+        status: member.status,
+        task: member.task,
+        idle: isIdle,
+      });
+      if (!isIdle) {
+        idleCheck.passed = false;
+      }
+    }
+    report.checks.push(idleCheck);
+
+    // Check 4: Artifact readers verification
+    const readerCheck = {
+      check: 'artifact_readers',
+      results: [],
+      passed: true,
+    };
+
+    if (args.expected_readers) {
+      for (const [artifactId, expectedReaders] of Object.entries(args.expected_readers)) {
+        const reads = artifactStore.getReads(artifactId);
+        const actualReaders = [...new Set(reads.map(r => r.reader))];
+        const missing = expectedReaders.filter(r => !actualReaders.includes(r));
+
+        readerCheck.results.push({
+          artifactId,
+          expectedReaders,
+          actualReaders,
+          missingReaders: missing,
+          allRead: missing.length === 0,
+        });
+
+        if (missing.length > 0) {
+          readerCheck.passed = false;
+        }
+      }
+    } else {
+      // If no expected readers specified, just show who read what
+      for (const id of artifactCheck.found) {
+        const reads = artifactStore.getReads(id);
+        const readers = [...new Set(reads.map(r => r.reader))];
+        readerCheck.results.push({
+          artifactId: id,
+          readers,
+          readCount: reads.length,
+        });
+      }
+    }
+    report.checks.push(readerCheck);
+
+    // Overall pass/fail
+    report.passed = report.checks.every(c => c.passed);
+
+    // Action recommendation
+    if (report.passed) {
+      report.recommendation = `ALL CHECKS PASSED. Safe to proceed to ${args.phase_starting}.`;
+    } else {
+      const failures = report.checks.filter(c => !c.passed).map(c => c.check);
+      report.recommendation = `BLOCKED: ${failures.join(', ')} failed. Fix these before proceeding to ${args.phase_starting}.`;
+    }
+
+    return textResult(JSON.stringify(report, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
 }
 
-/**
- * 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) {
+function handleTeamReset(args) {
   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;
+    if (!args.confirm) {
+      return errorResult('Must pass confirm: true to reset team state. This is destructive and cannot be undone.');
+    }
+
+    const teamName = args.team || 'default';
+    const baseDir = path.join(os.homedir(), '.claude-multi-session', 'team', teamName);
+
+    const summary = {
+      team: teamName,
+      cleared: [],
+      preserved: args.preserve_artifacts || [],
+    };
+
+    // Clear artifacts (except preserved ones)
+    const artifactsDir = path.join(baseDir, 'artifacts');
+    if (fs.existsSync(artifactsDir)) {
+      const indexPath = path.join(artifactsDir, 'index.json');
+      if (fs.existsSync(indexPath)) {
+        try {
+          const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+          const preserveSet = new Set(args.preserve_artifacts || []);
+
+          if (preserveSet.size > 0) {
+            // Filter out preserved artifacts
+            const filtered = {};
+            for (const [id, entry] of Object.entries(index)) {
+              if (preserveSet.has(id)) {
+                filtered[id] = entry;
+              }
+            }
+            fs.writeFileSync(indexPath, JSON.stringify(filtered, null, 2));
+            summary.cleared.push(`artifacts (kept ${preserveSet.size} preserved)`);
+          } else {
+            fs.writeFileSync(indexPath, '{}');
+            summary.cleared.push('artifacts');
+          }
+
+          // Clean data directory (version files and reads)
+          const dataDir = path.join(artifactsDir, 'data');
+          if (fs.existsSync(dataDir)) {
+            const artifactDirs = fs.readdirSync(dataDir);
+            for (const dir of artifactDirs) {
+              if (!preserveSet.has(dir)) {
+                const dirPath = path.join(dataDir, dir);
+                // Remove all files in the directory
+                const files = fs.readdirSync(dirPath);
+                for (const file of files) {
+                  fs.unlinkSync(path.join(dirPath, file));
+                }
+                fs.rmdirSync(dirPath);
+              }
+            }
+          }
+        } catch (e) {
+          summary.cleared.push(`artifacts (error: ${e.message})`);
+        }
       }
     }
-  } catch (e) {
-    // Silently ignore — staleness check is best-effort
+
+    // Clear contracts
+    const contractsPath = path.join(baseDir, 'contracts.json');
+    if (fs.existsSync(contractsPath)) {
+      fs.writeFileSync(contractsPath, '{}');
+      summary.cleared.push('contracts');
+    }
+
+    // Clear roster
+    const rosterPath = path.join(baseDir, 'roster.json');
+    if (fs.existsSync(rosterPath)) {
+      fs.writeFileSync(rosterPath, '{}');
+      summary.cleared.push('roster');
+    }
+
+    // Clear messages
+    const messagesDir = path.join(baseDir, 'messages');
+    if (fs.existsSync(messagesDir)) {
+      const files = fs.readdirSync(messagesDir);
+      for (const file of files) {
+        fs.unlinkSync(path.join(messagesDir, file));
+      }
+      summary.cleared.push('messages');
+    }
+
+    // Clear pipelines
+    const pipelinesPath = path.join(baseDir, 'pipelines.json');
+    if (fs.existsSync(pipelinesPath)) {
+      fs.writeFileSync(pipelinesPath, '{}');
+      summary.cleared.push('pipelines');
+    }
+
+    // Clear locks
+    const locksDir = path.join(baseDir, 'locks');
+    if (fs.existsSync(locksDir)) {
+      const lockFiles = fs.readdirSync(locksDir);
+      for (const file of lockFiles) {
+        fs.unlinkSync(path.join(locksDir, file));
+      }
+      summary.cleared.push('locks');
+    }
+
+    // Reset in-memory team instances
+    teamHub = null;
+    artifactStore = null;
+    contractStore = null;
+    resolver = null;
+    lineageGraph = null;
+    pipelineEngine = null;
+    snapshotEngine = null;
+    currentTeamName = null;
+
+    summary.message = `Team "${teamName}" has been reset. ${summary.cleared.length} stores cleared.`;
+
+    return textResult(JSON.stringify(summary, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
   }
-  return result;
+}
+
+// =============================================================================
+// Result Helpers
+// =============================================================================
+
+function textResult(text) {
+  return {
+    content: [{ type: 'text', text: text + getCachedStalenessWarning() }],
+  };
+}
+
+function errorResult(message) {
+  return {
+    content: [{ type: 'text', text: `Error: ${message}` + getCachedStalenessWarning() }],
+    isError: true,
+  };
 }
 
 // =============================================================================
@@ -2581,10 +2925,18 @@ function appendStalenessWarning(result) {
 // =============================================================================
 
 /**
- * Log to stderr (NEVER stdout — stdout is for MCP protocol only).
+ * Structured log to stderr (NEVER stdout — stdout is for MCP protocol only).
+ * Includes ISO timestamp and server version for debugging.
  */
-function log(msg) {
-  process.stderr.write(`[multi-session-mcp] ${msg}\n`);
+function log(msg, level = 'info') {
+  const entry = JSON.stringify({
+    ts: new Date().toISOString(),
+    level,
+    server: 'multi-session-mcp',
+    version: LOADED_VERSION,
+    msg,
+  });
+  process.stderr.write(entry + '\n');
 }
 
 /**
@@ -2623,7 +2975,7 @@ async function handleMessage(message) {
         },
         serverInfo: {
           name: 'claude-multi-session',
-          version: '1.0.0',
+          version: LOADED_VERSION,
         },
       });
       break;
@@ -2645,9 +2997,7 @@ async function handleMessage(message) {
         break;
       }
       try {
-        let result = await executeTool(params.name, params.arguments || {});
-        // Append staleness warning if server version is outdated
-        result = appendStalenessWarning(result);
+        const result = await executeTool(params.name, params.arguments || {});
         sendResponse(id, result);
       } catch (err) {
         sendResponse(id, errorResult(err.message));
@@ -2718,17 +3068,51 @@ function startServer() {
     process.exit(0);
   });
 
-  // Handle process signals gracefully
-  process.on('SIGTERM', () => {
-    log('SIGTERM received. Shutting down...');
-    manager.stopAll();
+  // Graceful shutdown handler — works on Windows (SIGINT, SIGBREAK) and Unix (SIGTERM)
+  let shuttingDown = false;
+  function gracefulShutdown(signal) {
+    if (shuttingDown) return; // Prevent double-shutdown
+    shuttingDown = true;
+    log(`${signal} received. Graceful shutdown starting...`);
+
+    // Stop accepting new work
+    rl.close();
+
+    // Kill all spawned child sessions
+    try {
+      manager.stopAll();
+      log('All sessions stopped.');
+    } catch (err) {
+      log(`Error stopping sessions: ${err.message}`, 'error');
+    }
+
+    // Force exit after 5 second timeout if cleanup hangs
+    const forceTimer = setTimeout(() => {
+      log('Shutdown timeout exceeded. Force exiting.', 'warn');
+      process.exit(1);
+    }, 5000);
+    forceTimer.unref(); // Don't keep process alive just for this timer
+
     process.exit(0);
+  }
+
+  process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+  process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+  // Windows-specific: SIGBREAK is sent on Ctrl+Break
+  if (process.platform === 'win32') {
+    process.on('SIGBREAK', () => gracefulShutdown('SIGBREAK'));
+  }
+
+  // Handle uncaught errors gracefully
+  process.on('uncaughtException', (err) => {
+    log(`Uncaught exception: ${err.message}\n${err.stack}`, 'error');
+    gracefulShutdown('uncaughtException');
   });
 
-  process.on('SIGINT', () => {
-    log('SIGINT received. Shutting down...');
-    manager.stopAll();
-    process.exit(0);
+  process.on('unhandledRejection', (reason) => {
+    log(`Unhandled rejection: ${reason}`, 'error');
+    // Don't shutdown on unhandled rejections — log and continue
   });
 
   log('MCP server ready. Waiting for messages...');

package/src/prompts.js

@@ -295,7 +295,11 @@ function buildDelegatePrompt(task, context, name) {
 
 You are "${name || 'worker'}" — an autonomous delegated worker session. You were spawned to complete a specific task independently, with no team communication tools. Your only job is to finish this task thoroughly and report back.
 
-IMPORTANT: You are operating under safety limits (cost and turn caps). Work efficiently — do not waste turns on unnecessary exploration or over-engineering.
+IMPORTANT: You are operating under STRICT safety limits. Your session will be AUTO-KILLED without warning if you exceed:
+- **Cost limit:** ~$2.00 USD (default)
+- **Turn limit:** ~50 agent turns (default)
+- **Time limit:** ~5 minutes (default)
+Work efficiently — do not waste turns on unnecessary exploration or over-engineering.
 
 === CRITICAL: MANDATORY WORKFLOW ===
 
@@ -581,29 +585,28 @@ NEVER assume workers will independently agree on conventions. Define them explic
 
 ### Phase Gate: VERIFY Before Spawning
 
-=== PHASE GATE CHECKPOINT (fill in and run before EVERY team_spawn after Phase 0) ===
+=== PHASE GATE CHECKPOINT (use phase_gate tool before EVERY team_spawn after Phase 0) ===
 
-Before spawning the next phase, STOP and fill in this checklist:
-
-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
+Instead of manually running 4 separate tool calls, use the \`phase_gate\` tool which does ALL checks in one call:
 
-4. artifact_readers({ artifactId: "___" })
-   All expected consumers listed? YES / NO (skip if Phase 0→1)
+\`\`\`
+mcp__multi-session__phase_gate({
+  phase_completing: "Phase 0: Foundation",
+  phase_starting: "Phase 1: Routes",
+  expected_artifacts: ["project-foundation", "shared-conventions"],
+  expected_idle: ["setup"],
+  expected_readers: { "shared-conventions": ["api-dev", "db-dev"] }
+})
+\`\`\`
 
-PROCEED ONLY IF all answers are YES.
-If any is NO → diagnose and fix before continuing.
+The tool automatically:
+1. Checks all expected artifacts exist
+2. Validates artifact content and tracks the read as "orchestrator"
+3. Verifies all previous-phase workers are idle
+4. Confirms expected consumers actually read the artifacts
 
-NEVER skip verification. NEVER rely on a worker's self-reported completion — verify the artifact exists yourself.
+Returns a structured pass/fail report with recommendation.
+PROCEED ONLY IF the report says ALL CHECKS PASSED.
 
 === PHASE COUNTING RULE ===
 At the start of planning, count and list your phases explicitly:
@@ -676,6 +679,8 @@ When all workers are done:
 | Workers need to communicate | \`team_spawn\` (has team tools) | \`delegate_task\` (isolated) |
 | Quick one-off task | \`delegate_task\` | \`team_spawn\` |
 | Need safety limits (cost/turns) | \`delegate_task\` | \`team_spawn\` |
+| Verify phase completion | \`phase_gate\` |
+| Clean up between runs | \`team_reset\` |
 
 ## WHAT GOES WRONG (And How to Avoid It)
 
@@ -912,7 +917,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. **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.
+5. **Post-Phase Verification** — After each phase completes, call \`phase_gate()\` which runs ALL verification checks in one call: confirms artifacts exist, validates content, checks workers are idle, and verifies artifact readers. Only proceed when it reports ALL CHECKS PASSED. 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.
 
@@ -973,6 +978,8 @@ Use \`delegate_task\` for SINGLE, isolated tasks that don't need team communicat
 | Single isolated task | \`delegate_task\` |
 | Quick one-off task | \`delegate_task\` |
 | Need safety limits (cost/turns) | \`delegate_task\` |
+| Verify phase completion | \`phase_gate\` |
+| Clean up between runs | \`team_reset\` |
 
 ### Lifecycle: delegate_task → continue_task → finish_task
 
@@ -1053,6 +1060,16 @@ NEVER do these:
 - Do NOT fix bugs found by one worker — tell that worker to fix them
 - Do NOT act as a message router — workers can talk directly via team_ask
 - Do NOT keep sending corrections endlessly — if 3 corrections don't work, abort and re-spawn
+
+### Resetting Between Runs
+Use \`team_reset\` to clean up all team state between orchestration runs:
+\`\`\`
+mcp__multi-session__team_reset({ confirm: true })
+\`\`\`
+This clears artifacts, contracts, roster, messages, and pipelines. Optionally preserve specific artifacts:
+\`\`\`
+mcp__multi-session__team_reset({ confirm: true, preserve_artifacts: ["shared-conventions"] })
+\`\`\`
 `;
 
 const ORCHESTRATOR_WHEN_TO_USE = `