claude-multi-session 2.5.1 → 2.7.0

package/bin/setup.js

@@ -102,25 +102,30 @@ IMPORTANT: Spawn ALL independent workers in a SINGLE message with multiple tool
 ### Rule 4: Post-Phase Verification (MANDATORY)
 After ALL workers in a phase complete, BEFORE spawning the next phase, STOP and fill in this checklist:
 
-=== PHASE GATE CHECKPOINT (fill in before EVERY team_spawn after Phase 0) ===
+=== PHASE GATE CHECKPOINT (use phase_gate tool before EVERY team_spawn after Phase 0) ===
 
-Phase completing: ___  →  Phase starting: ___
+Instead of manually running 4 separate tool calls, use the \`phase_gate\` tool which does ALL checks in one call:
 
-1. \`artifact_list()\`
-   Expected artifacts: [___]
-   All present? YES / NO
-
-2. \`artifact_get({ artifactId: "___", reader: "orchestrator" })\`
-   Content valid and complete? YES / NO
+\`\`\`
+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"] }
+})
+\`\`\`
 
-3. \`team_roster()\`
-   All previous-phase workers idle? YES / NO
+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
 
-4. \`artifact_readers({ artifactId: "___" })\`
-   All expected consumers listed? YES / NO
+Returns a structured pass/fail report with recommendation.
+PROCEED ONLY IF the report says ALL CHECKS PASSED.
 
-PROCEED ONLY IF all answers are YES.
-If any is NO → diagnose and fix before continuing.
+**ENFORCED:** \`team_spawn\` will return an error if \`phase_gate\` was not called between spawn batches. The first batch (Phase 0) is free; every subsequent batch requires a passing \`phase_gate\` call first.
 
 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.
 
@@ -182,12 +187,17 @@ NEVER trust a worker's self-reported completion — verify the artifact exists y
 | 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}
 `;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.5.1",
+  "version": "2.7.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');
@@ -75,6 +76,10 @@ let pipelineEngine = null;
 let snapshotEngine = null;
 let currentTeamName = null;
 
+// Phase gate enforcement state — tracks gate calls vs spawn batches per team
+// team -> { gateCount: number, spawnBatchCount: number, lastSpawnTime: number }
+const _gateState = new Map();
+
 /**
  * Get or create Team Hub instances for a given team
  * This function lazily creates the instances on first use
@@ -84,6 +89,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 +438,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 +962,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 +1157,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 +1331,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);
@@ -1667,6 +1752,31 @@ async function handleTeamSpawn(args) {
     const teamName = args.team || 'default';
     const { teamHub } = getTeamInstances(teamName);
 
+    // Gate enforcement: require phase_gate between spawn batches
+    const state = _gateState.get(teamName) || { gateCount: 0, spawnBatchCount: 0, lastSpawnTime: 0 };
+    const now = Date.now();
+
+    // Detect new spawn batch (>5s since last spawn = new batch)
+    const isNewBatch = (now - state.lastSpawnTime) > 5000;
+    if (isNewBatch) {
+      state.spawnBatchCount++;
+    }
+    state.lastSpawnTime = now;
+    _gateState.set(teamName, state);
+
+    // Rule: spawnBatchCount must be <= gateCount + 1
+    // (first batch is free, every subsequent batch needs a gate)
+    if (state.spawnBatchCount > state.gateCount + 1) {
+      return errorResult(
+        `PHASE GATE REQUIRED: You have spawned ${state.spawnBatchCount - 1} batch(es) of workers ` +
+        `but only called phase_gate ${state.gateCount} time(s). ` +
+        `Call phase_gate() to verify the previous phase completed before spawning more workers.\n\n` +
+        `Example:\n` +
+        `phase_gate({ phase_completing: "Phase N", phase_starting: "Phase N+1", ` +
+        `expected_artifacts: ["..."] })`
+      );
+    }
+
     // Join the team roster
     teamHub.joinTeam(args.name, {
       role: args.role || 'team member',
@@ -1687,6 +1797,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 +1815,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 +2070,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 +2096,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 +2664,300 @@ 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);
+
+    // Track gate pass for spawn enforcement
+    if (report.passed) {
+      const state = _gateState.get(teamName) || { gateCount: 0, spawnBatchCount: 0, lastSpawnTime: 0 };
+      state.gateCount++;
+      _gateState.set(teamName, state);
+      report._gate_generation = state.gateCount;
+    }
+
+    // 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;
+
+    // Clear gate enforcement state
+    _gateState.delete(teamName);
+
+    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 +2965,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 +3015,7 @@ async function handleMessage(message) {
         },
         serverInfo: {
           name: 'claude-multi-session',
-          version: '1.0.0',
+          version: LOADED_VERSION,
         },
       });
       break;
@@ -2645,9 +3037,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 +3108,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,30 @@ 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
+Instead of manually running 4 separate tool calls, use the \`phase_gate\` tool which does ALL checks in one call:
 
-3. team_roster()
-   All previous-phase workers idle? YES / NO
+\`\`\`
+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"] }
+})
+\`\`\`
 
-4. artifact_readers({ artifactId: "___" })
-   All expected consumers listed? YES / NO (skip if Phase 0→1)
+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
 
-PROCEED ONLY IF all answers are YES.
-If any is NO → diagnose and fix before continuing.
+Returns a structured pass/fail report with recommendation.
+PROCEED ONLY IF the report says ALL CHECKS PASSED.
 
-NEVER skip verification. NEVER rely on a worker's self-reported completion — verify the artifact exists yourself.
+**ENFORCED:** \`team_spawn\` will return an error if \`phase_gate\` was not called between spawn batches. The first batch (Phase 0) is free; every subsequent batch requires a passing \`phase_gate\` call first.
 
 === PHASE COUNTING RULE ===
 At the start of planning, count and list your phases explicitly:
@@ -676,6 +681,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 +919,9 @@ 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.
+
+**Note:** \`team_spawn\` will return an error if \`phase_gate\` was not called between spawn batches. The first batch (Phase 0) is free; every subsequent batch requires a passing \`phase_gate\` call first.
 
 6. **Collect** — When all workers are idle, check \`artifact_list\` for published outputs and summarize results for the user.
 
@@ -973,6 +982,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 +1064,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 = `