claude-multi-session 2.6.0 → 2.9.1

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to claude-multi-session will be documented in this file.
+
+## [2.9.1] - 2026-02-14
+### Fixed
+- Gate enforcement bug: gate stayed open forever after phase_gate passed, allowing spawns without verification
+- Gate now auto-closes when ALL workers from the current batch go idle
+- Added spawnedWorkers tracking to gate state
+- Test count: 48 → 49 (+1 gate auto-close test)
+
+## [2.9.0] - 2026-02-14
+### Changed
+- Replaced 120-second batch window timing hack with deterministic gate logic
+- phase_gate now explicitly opens/closes the spawn gate (no timing involved)
+- Gate error message changed from "PHASE GATE REQUIRED" to "GATE CLOSED"
+- phase_gate response now includes `_gate_phase` field instead of `_gate_generation`
+- Test count increased from 46 to 48 (2 new deterministic gate tests)
+
+### Removed
+- 120-second batch window constant
+- Time-based spawn batch detection (lastSpawnTime, spawnBatchCount fields)
+
+## [2.8.0] - 2026-02-13
+### Added
+- Inbox enforcement — workers MUST call team_check_inbox before artifact/contract tools
+- Auto-status — server auto-sets workers to "active" on spawn, "idle" on stop/kill
+- Convention completeness check in phase_gate (advisory, check 5 of 5)
+- File ownership tracking — 2 new tools: register_files, check_file_owner
+- Roster injection in team_spawn, phase_gate, send_message responses
+- 46 automated enforcement tests in test-enforcement.js
+
+### Fixed
+- roster.filter crash when roster.json contains object instead of array
+- Defensive Array.isArray() guards on all roster operations
+
+## [2.7.0] - 2026-02
+### Added
+- Gate-aware team_spawn — structural enforcement of phase_gate between spawn batches
+- phase_gate tool with 5 verification checks
+- team_reset tool for clearing state between runs
+- server_version tool for staleness detection
+
+## [2.6.0] - 2026-02
+### Added
+- Staleness warnings appended to all tool responses when version mismatch detected
+
+## [2.5.0] - 2026-01
+### Added
+- server_version tool
+- Improved orchestrator prompts
+
+## [2.4.0] - 2026-01
+### Added
+- Version detection feature
+- artifact_readers tool
+
+## [2.3.0] - 2026-01
+### Added
+- Initial release with convention system
+- Team coordination tools (team_spawn, team_ask, team_broadcast, etc.)
+- Artifact store with versioning and read tracking
+- Contract store with dependency resolution
+- Session management (spawn, pause, resume, fork, kill)

package/README.md

@@ -1,5 +1,13 @@
 # claude-multi-session
 
+[![npm version](https://img.shields.io/npm/v/claude-multi-session.svg)](https://www.npmjs.com/package/claude-multi-session)
+[![license](https://img.shields.io/npm/l/claude-multi-session.svg)](https://github.com/)
+[![node](https://img.shields.io/node/v/claude-multi-session.svg)](https://nodejs.org)
+
+> Multi-session orchestration system for Claude Code CLI. Spawn parallel workers that coordinate via artifacts and phase gates. 68 MCP tools. v2.9.0.
+
+---
+
 **Multi-session orchestrator for Claude Code CLI** — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically.
 
 Built on Claude CLI's `stream-json` protocol for efficient multi-turn conversations using a single long-lived process per session.

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * ╔══════════════════════════════════════════════════════════════╗

package/bin/setup.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * ╔══════════════════════════════════════════════════════════════╗
@@ -121,10 +121,15 @@ The tool automatically:
 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
+5. Convention completeness advisory — warns if \`shared-conventions\` artifact is missing or incomplete (checks all 10 checklist keys: responseFormat, errorFormat, statusCodes, namingConventions, filePaths, enumValues, booleanHandling, dateFormat, auditActions, sharedColumnNames)
+
+Check 5 is advisory (WARNING, not a gate failure) — the gate still passes/fails based on checks 1-4. But convention warnings are highly visible and should be addressed.
 
 Returns a structured pass/fail report with recommendation.
 PROCEED ONLY IF the report says ALL CHECKS PASSED.
 
+**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.
 
 Only intervene in workers when a session is BLOCKED or FAILED.
@@ -132,17 +137,17 @@ Do NOT verify worker output by reading files directly — check artifacts instea
 
 ### Rule 5: Always tell workers to publish artifacts
 Every worker prompt should include instructions to:
-1. Check inbox before starting (\`team_check_inbox\`)
+1. Check inbox before starting (\`team_check_inbox\`) — **ENFORCED**: artifact and contract tools are blocked until workers call this
 2. Use \`team_ask\` to communicate with teammates (NOT you)
-3. Publish output as artifacts (\`artifact_publish\`)
+3. Publish output as artifacts (\`artifact_publish\`) — auto-registers file ownership from \`files\`/\`filesCreated\`/\`filesModified\` in data
 4. Broadcast completion (\`team_broadcast\`)
-5. Update status to idle when done (\`team_update_status\`)
+5. ~~Update status to idle when done~~ — **AUTO-MANAGED**: status is automatically set to "active" on spawn and "idle" on stop/kill. Workers only need \`team_update_status\` for custom statuses like "blocked".
 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:
+STOP. Before editing any file a worker created, call \`check_file_owner({ file: "path/to/file" })\` to verify ownership, then answer these questions:
 
 1. Is this fix ≤ 3 lines?
    NO → \`send_message\` to worker or spawn fix-worker. Do NOT fix yourself.
@@ -173,19 +178,30 @@ This shows which workers actually read the conventions. If a worker is missing,
 
 NEVER trust a worker's self-reported completion — verify the artifact exists yourself.
 
-## Quick Reference
+## Auto-Behaviors (v2.7.0)
+
+These happen automatically — no action needed from you or the workers:
+- **Roster summary injection**: \`team_spawn\`, \`phase_gate\`, and \`send_message\` (to team workers) responses include a compact roster line: \`[Team: worker-a=active, worker-b=idle]\`
+- **Auto-status management**: Workers are set to "active" on spawn and "idle" when their session stops/is killed
+- **Inbox enforcement**: Workers are blocked from using artifact/contract tools until they call \`team_check_inbox\`
+- **File ownership tracking**: \`artifact_publish\` auto-registers file ownership from \`files\`/\`filesCreated\`/\`filesModified\` arrays in artifact data
+- **Convention completeness check**: \`phase_gate\` warns if \`shared-conventions\` artifact is missing or has incomplete fields
+
+## Quick Reference (68 tools)
 
 | You want to... | Use this tool |
 |----------------|---------------|
 | 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\` |
+| Check who's working on what | \`team_roster\` (also auto-injected in spawn/gate/message responses) |
 | See published outputs | \`artifact_list\` |
 | See task completion status | \`contract_list\` |
+| Verify phase completion | \`phase_gate\` |
 | Send a correction to a worker | \`send_message\` to that session |
 | Check who read an artifact | \`artifact_readers\` |
-| Verify phase completion | \`phase_gate\` |
+| Check file ownership (Rule 6) | \`check_file_owner\` |
+| Register file ownership | \`register_files\` |
 | Clean up between runs | \`team_reset\` |
 
 ### When NOT to Delegate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.6.0",
+  "version": "2.9.1",
   "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": {
@@ -17,12 +17,20 @@
   "keywords": [
     "claude",
     "claude-code",
+    "anthropic",
     "session-manager",
     "multi-session",
     "orchestrator",
+    "ai-agents",
+    "multi-agent",
+    "agent-coordination",
+    "mcp",
+    "model-context-protocol",
     "ai",
     "automation",
-    "cli"
+    "cli",
+    "parallel-tasks",
+    "workflow-automation"
   ],
   "author": "",
   "license": "MIT",
@@ -33,6 +41,7 @@
     "src/",
     "bin/",
     "README.md",
+    "CHANGELOG.md",
     "STRATEGY.md",
     "LICENSE"
   ],

package/src/artifact-store.js

@@ -111,7 +111,24 @@ class ArtifactStore {
     if (schema.required && Array.isArray(schema.required)) {
       for (const field of schema.required) {
         if (!(field in data)) {
-          errors.push(`field '${field}' is required`);
+          // Build helpful error message with type-specific suggestions
+          let errorMsg = `field '${field}' is required`;
+
+          // Add helpful suggestions for well-known types
+          const typeHints = {
+            'api-contract': `type 'api-contract' requires an 'endpoints' field. If this artifact isn't an API contract, use type 'custom' instead.`,
+            'schema-change': `type 'schema-change' requires a 'models' field. If this artifact isn't a database schema change, use type 'custom' instead.`,
+            'test-results': `type 'test-results' requires 'total', 'passed', and 'failed' fields. If this artifact isn't test results, use type 'custom' instead.`,
+            'component-spec': `type 'component-spec' requires a 'componentName' field. If this artifact isn't a component specification, use type 'custom' instead.`,
+            'file-manifest': `type 'file-manifest' requires a 'files' field. If this artifact isn't a file manifest, use type 'custom' instead.`,
+            'config-change': `type 'config-change' requires a 'changes' field. If this artifact isn't a configuration change, use type 'custom' instead.`
+          };
+
+          if (typeHints[type]) {
+            errorMsg = `Schema validation failed: ${typeHints[type]}`;
+          }
+
+          errors.push(errorMsg);
         }
       }
     }
@@ -399,10 +416,14 @@ class ArtifactStore {
       } catch (err) {
         // Handle race condition - file already exists
         if (err.code === 'EEXIST') {
-          // Retry with incremented version
-          version += 1;
+          // Re-read index to get actual latest version
+          const freshIndex = readJsonSafe(this.indexPath, {});
+          const freshLatest = freshIndex[artifactId]?.latestVersion || version;
+          version = freshLatest + 1;
+          const updatedData = { ...versionData, version, publishedAt: new Date().toISOString() };
           const retryPath = path.join(artifactDir, `v${version}.json`);
-          writeImmutable(retryPath, { ...versionData, version });
+          writeImmutable(retryPath, updatedData);
+          versionData = updatedData; // Update for index write below
         } else {
           throw err;
         }

package/src/mcp-server.js

@@ -76,6 +76,89 @@ let pipelineEngine = null;
 let snapshotEngine = null;
 let currentTeamName = null;
 
+// Phase gate enforcement state — deterministic open/close gate per team
+// team -> { gateOpen: boolean, phase: string|null, spawnCount: number, firstBatchFree: boolean }
+const _gateState = new Map();
+
+function getGateState(team) {
+  if (!_gateState.has(team)) {
+    _gateState.set(team, { gateOpen: false, phase: null, spawnCount: 0, firstBatchFree: true, spawnedWorkers: new Set() });
+  }
+  return _gateState.get(team);
+}
+
+// Inbox check enforcement state — tracks which workers have called team_check_inbox
+// "teamName:workerName" -> boolean (true = checked inbox)
+const _inboxCheckState = new Map();
+
+// Worker-to-team mapping — used to auto-update roster status on stop/kill
+// workerName -> teamName
+const _workerTeamMap = new Map();
+
+// File ownership tracking — maps filePath → { worker, team } for Rule 6 violation detection
+const _fileOwnership = new Map();
+
+/**
+ * Check if a caller is a team worker who hasn't checked their inbox yet.
+ * Returns an error string if blocked, or null if allowed to proceed.
+ */
+function checkInboxEnforcement(teamName, callerName) {
+  if (!callerName) return null;
+  const key = teamName + ':' + callerName;
+  if (_inboxCheckState.has(key) && !_inboxCheckState.get(key)) {
+    return 'BLOCKED: You must call team_check_inbox before using other team tools. This is mandatory step 1 of your workflow.';
+  }
+  return null;
+}
+
+/**
+ * Auto-set a team worker's roster status to idle when their session stops or is killed.
+ * Only acts if the worker is a known team worker (exists in _workerTeamMap).
+ */
+function autoSetWorkerIdle(workerName) {
+  const teamName = _workerTeamMap.get(workerName);
+  if (!teamName) return; // Not a team worker
+  try {
+    const { teamHub } = getTeamInstances(teamName);
+    teamHub.updateMember(workerName, { status: 'idle', task: 'Completed' });
+
+    // Auto-close gate when all spawned workers from current batch are idle
+    const gate = getGateState(teamName);
+    if (gate.spawnedWorkers.size > 0 && gate.spawnedWorkers.has(workerName)) {
+      const roster = teamHub.getRoster();
+      const safeRoster = Array.isArray(roster) ? roster : [];
+      const allIdle = [...gate.spawnedWorkers].every(name => {
+        const member = safeRoster.find(m => m.name === name);
+        return member && member.status === 'idle';
+      });
+      if (allIdle) {
+        gate.gateOpen = false;
+        gate.firstBatchFree = false;
+        gate.spawnedWorkers = new Set();
+      }
+    }
+  } catch (_) {
+    // Best-effort — don't fail the stop/kill if roster update fails
+  }
+}
+
+/**
+ * Build a compact one-line roster summary for a team.
+ * Returns e.g. "[Team: worker-a=active, worker-b=idle]" or "" if empty/error.
+ */
+function getRosterSummary(teamName) {
+  try {
+    const { teamHub } = getTeamInstances(teamName);
+    const roster = teamHub.getRoster();
+    // Defensive: ensure roster is an array
+    if (!Array.isArray(roster) || roster.length === 0) return '';
+    const pairs = roster.map(m => m.name + '=' + (m.status || 'unknown'));
+    return '\n[Team: ' + pairs.join(', ') + ']';
+  } catch (_) {
+    return '';
+  }
+}
+
 /**
  * Get or create Team Hub instances for a given team
  * This function lazily creates the instances on first use
@@ -995,6 +1078,38 @@ const TOOLS = [
     },
   },
 
+  // ── File Ownership (Rule 6 enforcement) ────────────────────────────────
+  {
+    name: 'register_files',
+    description:
+      'Register file ownership for a worker. Call this after creating or modifying files ' +
+      'so the system can track who owns which files and warn about Rule 6 violations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        worker: { type: 'string', description: 'Worker session name that owns these files' },
+        files:  { type: 'array', items: { type: 'string' }, description: 'Array of file paths to register' },
+        team:   { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['worker', 'files'],
+    },
+  },
+
+  {
+    name: 'check_file_owner',
+    description:
+      'Check who owns a file. Use this before directly editing a file to verify ' +
+      'whether it belongs to a worker (Rule 6: don\'t fix worker code yourself).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'File path to check ownership of' },
+        team: { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['file'],
+    },
+  },
+
   // ── Session Continuity (Layer 0) ──────────────────────────────────────
   {
     name: 'continuity_snapshot',
@@ -1333,6 +1448,12 @@ async function executeTool(toolName, args) {
       case 'team_reset':
         return handleTeamReset(args);
 
+      // ── File Ownership handlers ──
+      case 'register_files':
+        return handleRegisterFiles(args);
+      case 'check_file_owner':
+        return handleCheckFileOwner(args);
+
       // ── Session Continuity (Layer 0) handlers ──
       case 'continuity_snapshot': {
         const snap = new SessionSnapshot(args.projectPath);
@@ -1460,28 +1581,46 @@ async function handleSpawn(args) {
 }
 
 async function handleSend(args) {
-  // Auto-resume if session is not alive
-  if (!manager.sessions.has(args.name)) {
-    log(`Session "${args.name}" not alive. Auto-resuming...`);
-    const response = await manager.resume(args.name, args.message);
+  try {
+    // Check if target is a team worker for roster summary injection
+    const workerTeam = _workerTeamMap.get(args.name);
+    const rosterSuffix = workerTeam ? getRosterSummary(workerTeam) : '';
+
+    // Auto-resume if session is not alive
+    if (!manager.sessions.has(args.name)) {
+      log(`Session "${args.name}" not alive. Auto-resuming...`);
+      const response = await manager.resume(args.name, args.message);
+      return textResult(JSON.stringify({
+        session_name: args.name,
+        auto_resumed: true,
+        response: response?.text || '',
+        cost: response?.cost || 0,
+        turns: response?.turns || 0,
+        duration_ms: response?.duration || 0,
+      }, null, 2) + rosterSuffix);
+    }
+
+    const response = await manager.send(args.name, args.message);
     return textResult(JSON.stringify({
       session_name: args.name,
-      auto_resumed: true,
-      response: response?.text || '',
-      cost: response?.cost || 0,
-      turns: response?.turns || 0,
-      duration_ms: response?.duration || 0,
-    }, null, 2));
+      response: response.text,
+      cost: response.cost,
+      turns: response.turns,
+      duration_ms: response.duration,
+    }, null, 2) + rosterSuffix);
+  } catch (err) {
+    // Try to set worker status to error if this is a team worker
+    try {
+      const workerTeam = _workerTeamMap.get(args.name);
+      if (workerTeam) {
+        const { teamHub } = getTeamInstances(workerTeam);
+        teamHub.updateMember(args.name, { status: 'error', task: `Failed: ${err.message}` });
+      }
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+    return errorResult(err.message);
   }
-
-  const response = await manager.send(args.name, args.message);
-  return textResult(JSON.stringify({
-    session_name: args.name,
-    response: response.text,
-    cost: response.cost,
-    turns: response.turns,
-    duration_ms: response.duration,
-  }, null, 2));
 }
 
 async function handleResume(args) {
@@ -1521,6 +1660,10 @@ async function handleFork(args) {
 
 function handleStop(args) {
   manager.stop(args.name);
+
+  // Auto-set team worker status to idle when stopped
+  autoSetWorkerIdle(args.name);
+
   return textResult(JSON.stringify({
     session_name: args.name,
     status: 'stopped',
@@ -1530,6 +1673,10 @@ function handleStop(args) {
 
 function handleKill(args) {
   manager.kill(args.name);
+
+  // Auto-set team worker status to idle when killed
+  autoSetWorkerIdle(args.name);
+
   return textResult(JSON.stringify({
     session_name: args.name,
     status: 'killed',
@@ -1748,6 +1895,29 @@ async function handleTeamSpawn(args) {
     const teamName = args.team || 'default';
     const { teamHub } = getTeamInstances(teamName);
 
+    // Deterministic gate enforcement: phase_gate opens gate, spawns go through, next phase_gate closes and reopens
+    const gate = getGateState(teamName);
+
+    if (gate.firstBatchFree) {
+      // First batch before any phase_gate call — always allowed
+      gate.spawnCount++;
+      gate.spawnedWorkers.add(args.name);
+    } else if (gate.gateOpen) {
+      // Gate was opened by a passing phase_gate — allowed
+      gate.spawnCount++;
+      gate.spawnedWorkers.add(args.name);
+    } else {
+      // Gate is closed — block the spawn
+      return errorResult(
+        `GATE CLOSED: Cannot spawn workers. ` +
+        `Call phase_gate to verify phase "${gate.phase || 'previous'}" is complete before spawning the next batch.\n\n` +
+        `This is structural enforcement of Rule 4 (Phase Gate Verification).\n\n` +
+        `Example:\n` +
+        `phase_gate({ phase_completing: "${gate.phase || 'Phase N'}", phase_starting: "Phase N+1", ` +
+        `expected_artifacts: ["..."] })`
+      );
+    }
+
     // Join the team roster
     teamHub.joinTeam(args.name, {
       role: args.role || 'team member',
@@ -1755,6 +1925,12 @@ async function handleTeamSpawn(args) {
       model: args.model || 'sonnet',
     });
 
+    // Track inbox check enforcement — worker must call team_check_inbox before using artifact/contract tools
+    _inboxCheckState.set(teamName + ':' + args.name, false);
+
+    // Map worker name to team for auto-status updates on stop/kill
+    _workerTeamMap.set(args.name, teamName);
+
     // Get roster to build system prompt
     const roster = teamHub.getRoster();
 
@@ -1771,6 +1947,13 @@ async function handleTeamSpawn(args) {
       workDir: args.work_dir || process.cwd(),
     });
 
+    // Auto-set worker status to active with their task description
+    const taskDesc = args.task || args.prompt || 'Starting up';
+    teamHub.updateMember(args.name, {
+      status: 'active',
+      task: taskDesc.length > 100 ? taskDesc.slice(0, 100) + '...' : taskDesc,
+    });
+
     const result = {
       session_name: session.name,
       status: session.status,
@@ -1792,8 +1975,16 @@ async function handleTeamSpawn(args) {
       result._staleness_warning = `Server is stale! ${staleness.trim()}`;
     }
 
-    return textResult(JSON.stringify(result, null, 2));
+    return textResult(JSON.stringify(result, null, 2) + getRosterSummary(teamName));
   } catch (err) {
+    // Try to set worker status to error so phase_gate doesn't hang
+    try {
+      const teamName = args.team || 'default';
+      const { teamHub } = getTeamInstances(teamName);
+      teamHub.updateMember(args.name, { status: 'error', task: `Failed: ${err.message}` });
+    } catch (e) {
+      // Ignore cleanup errors
+    }
     return errorResult(err.message);
   }
 }
@@ -1843,6 +2034,12 @@ function handleTeamCheckInbox(args) {
     const teamName = args.team || 'default';
     const { teamHub } = getTeamInstances(teamName);
 
+    // Mark this worker as having checked their inbox
+    const inboxKey = teamName + ':' + args.name;
+    if (_inboxCheckState.has(inboxKey)) {
+      _inboxCheckState.set(inboxKey, true);
+    }
+
     const messages = teamHub.getInbox(args.name, {
       markRead: args.mark_read !== false,
       limit: args.limit || 20,
@@ -1929,11 +2126,13 @@ function handleTeamRoster(args) {
     const { teamHub } = getTeamInstances(teamName);
 
     const roster = teamHub.getRoster();
+    // Defensive: ensure roster is an array
+    const safeRoster = Array.isArray(roster) ? roster : [];
 
     return textResult(JSON.stringify({
       team: teamName,
-      count: roster.length,
-      members: roster.map(m => ({
+      count: safeRoster.length,
+      members: safeRoster.map(m => ({
         name: m.name,
         role: m.role,
         status: m.status,
@@ -1976,6 +2175,11 @@ function handleTeamUpdateStatus(args) {
 async function handleArtifactPublish(args) {
   try {
     const teamName = args.team || 'default';
+
+    // Inbox check enforcement — workers must call team_check_inbox first
+    const inboxBlock = checkInboxEnforcement(teamName, args.publisher);
+    if (inboxBlock) return errorResult(inboxBlock);
+
     const { artifactStore, resolver } = getTeamInstances(teamName);
 
     // Publish the artifact
@@ -1998,13 +2202,32 @@ async function handleArtifactPublish(args) {
       data: args.data,
     });
 
-    return textResult(JSON.stringify({
+    // Auto-register file ownership from artifact data
+    let filesRegistered = 0;
+    if (args.data && args.publisher) {
+      const fileLists = [args.data.files, args.data.filesCreated, args.data.filesModified].filter(Array.isArray);
+      for (const list of fileLists) {
+        for (const filePath of list) {
+          if (typeof filePath === 'string') {
+            _fileOwnership.set(filePath, { worker: args.publisher, team: teamName });
+            filesRegistered++;
+          }
+        }
+      }
+    }
+
+    const publishResult = {
       status: 'published',
       artifactId: result.artifactId,
       version: result.version,
       type: result.type,
       team: teamName,
-    }, null, 2));
+    };
+    if (filesRegistered > 0) {
+      publishResult.filesRegistered = filesRegistered;
+    }
+
+    return textResult(JSON.stringify(publishResult, null, 2));
   } catch (err) {
     return errorResult(err.message);
   }
@@ -2013,6 +2236,11 @@ async function handleArtifactPublish(args) {
 function handleArtifactGet(args) {
   try {
     const teamName = args.team || 'default';
+
+    // Inbox check enforcement — workers must call team_check_inbox first
+    const inboxBlock = checkInboxEnforcement(teamName, args.reader);
+    if (inboxBlock) return errorResult(inboxBlock);
+
     const { artifactStore } = getTeamInstances(teamName);
 
     const artifact = artifactStore.get(args.artifactId, args.version);
@@ -2137,6 +2365,11 @@ function handleArtifactHistory(args) {
 async function handleContractCreate(args) {
   try {
     const teamName = args.team || 'default';
+
+    // Inbox check enforcement — workers must call team_check_inbox first
+    const inboxBlock = checkInboxEnforcement(teamName, args.assigner);
+    if (inboxBlock) return errorResult(inboxBlock);
+
     const { contractStore, resolver, teamHub } = getTeamInstances(teamName);
 
     // Create the contract
@@ -2189,6 +2422,13 @@ function handleContractStart(args) {
     const teamName = args.team || 'default';
     const { contractStore } = getTeamInstances(teamName);
 
+    // Inbox check enforcement — look up the contract's assignee to check
+    const contractData = contractStore.get(args.contractId);
+    if (contractData) {
+      const inboxBlock = checkInboxEnforcement(teamName, contractData.assignee);
+      if (inboxBlock) return errorResult(inboxBlock);
+    }
+
     const contract = contractStore.start(args.contractId);
 
     return textResult(JSON.stringify({
@@ -2703,6 +2943,8 @@ function handlePhaseGate(args) {
 
     // Check 3: Workers idle
     const roster = teamHub.getRoster();
+    // Defensive: ensure roster is an array
+    const safeRoster = Array.isArray(roster) ? roster : [];
     const idleCheck = {
       check: 'workers_idle',
       results: [],
@@ -2710,8 +2952,8 @@ function handlePhaseGate(args) {
     };
 
     const workersToCheck = args.expected_idle
-      ? roster.filter(m => args.expected_idle.includes(m.name))
-      : roster;
+      ? safeRoster.filter(m => args.expected_idle.includes(m.name))
+      : safeRoster;
 
     for (const member of workersToCheck) {
       const isIdle = member.status === 'idle';
@@ -2766,8 +3008,58 @@ function handlePhaseGate(args) {
     }
     report.checks.push(readerCheck);
 
-    // Overall pass/fail
-    report.passed = report.checks.every(c => c.passed);
+    // Check 5: Convention completeness (advisory — does NOT affect pass/fail)
+    const requiredConventionFields = [
+      'responseFormat', 'errorFormat', 'statusCodes', 'namingConventions',
+      'filePaths', 'enumValues', 'booleanHandling', 'dateFormat',
+      'auditActions', 'sharedColumnNames',
+    ];
+    const conventionCheck = {
+      check: 'convention_completeness',
+      advisory: true,
+    };
+
+    const conventionArtifact = artifactStore.get('shared-conventions');
+    if (!conventionArtifact) {
+      conventionCheck.status = 'WARNING';
+      conventionCheck.message = "No 'shared-conventions' artifact found. Recommend publishing conventions before spawning workers.";
+    } else if (!conventionArtifact.data) {
+      conventionCheck.status = 'WARNING';
+      conventionCheck.message = "Convention artifact exists but has no data. Recommend re-publishing with all 10 fields.";
+    } else {
+      // Check that all required fields exist and are non-empty
+      const missing = requiredConventionFields.filter(f => {
+        if (!(f in conventionArtifact.data)) return true;
+        const value = conventionArtifact.data[f];
+        if (typeof value === 'string' && value.trim() === '') return true;
+        return false;
+      });
+
+      if (missing.length > 0) {
+        conventionCheck.status = 'WARNING';
+        conventionCheck.missingConventions = missing;
+        conventionCheck.message = `Convention artifact missing ${missing.length}/10 fields: ${missing.join(', ')}. Incomplete conventions cause format mismatches between workers.`;
+      } else {
+        conventionCheck.status = 'PASS';
+        conventionCheck.message = 'All 10 conventions defined.';
+      }
+    }
+    report.checks.push(conventionCheck);
+
+    // Overall pass/fail (convention check is advisory, excluded from gate decision)
+    report.passed = report.checks.filter(c => !c.advisory).every(c => c.passed);
+
+    // Deterministic gate: on pass, close current gate and open for next phase
+    if (report.passed) {
+      const gate = getGateState(teamName);
+      gate.firstBatchFree = false;
+      gate.gateOpen = true;
+      gate.phase = args.phase_starting || null;
+      gate.spawnCount = 0;
+      gate.spawnedWorkers = new Set();
+      _gateState.set(teamName, gate);
+      report._gate_phase = gate.phase;
+    }
 
     // Action recommendation
     if (report.passed) {
@@ -2777,7 +3069,56 @@ function handlePhaseGate(args) {
       report.recommendation = `BLOCKED: ${failures.join(', ')} failed. Fix these before proceeding to ${args.phase_starting}.`;
     }
 
-    return textResult(JSON.stringify(report, null, 2));
+    return textResult(JSON.stringify(report, null, 2) + getRosterSummary(teamName));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── File Ownership Handlers ────────────────────────────────────────────────
+
+function handleRegisterFiles(args) {
+  try {
+    const teamName = args.team || 'default';
+    let registered = 0;
+
+    for (const filePath of args.files) {
+      if (typeof filePath === 'string') {
+        _fileOwnership.set(filePath, { worker: args.worker, team: teamName });
+        registered++;
+      }
+    }
+
+    return textResult(JSON.stringify({
+      status: 'registered',
+      worker: args.worker,
+      filesRegistered: registered,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleCheckFileOwner(args) {
+  try {
+    const owner = _fileOwnership.get(args.file);
+
+    if (!owner) {
+      return textResult(JSON.stringify({
+        file: args.file,
+        owned: false,
+        message: 'No owner registered',
+      }, null, 2));
+    }
+
+    return textResult(JSON.stringify({
+      file: args.file,
+      owned: true,
+      worker: owner.worker,
+      team: owner.team,
+      warning: `This file belongs to worker "${owner.worker}". Rule 6: Do not edit worker files directly unless the fix is ≤3 lines and the worker is idle.`,
+    }, null, 2));
   } catch (err) {
     return errorResult(err.message);
   }
@@ -2854,7 +3195,7 @@ function handleTeamReset(args) {
     // Clear roster
     const rosterPath = path.join(baseDir, 'roster.json');
     if (fs.existsSync(rosterPath)) {
-      fs.writeFileSync(rosterPath, '{}');
+      fs.writeFileSync(rosterPath, '[]');
       summary.cleared.push('roster');
     }
 
@@ -2895,6 +3236,30 @@ function handleTeamReset(args) {
     snapshotEngine = null;
     currentTeamName = null;
 
+    // Clear gate enforcement state
+    _gateState.delete(teamName);
+
+    // Clear inbox check enforcement state for this team
+    for (const key of _inboxCheckState.keys()) {
+      if (key.startsWith(teamName + ':')) {
+        _inboxCheckState.delete(key);
+      }
+    }
+
+    // Clear worker-to-team mapping for this team
+    for (const [worker, team] of _workerTeamMap.entries()) {
+      if (team === teamName) {
+        _workerTeamMap.delete(worker);
+      }
+    }
+
+    // Clear file ownership entries for this team
+    for (const [filePath, owner] of _fileOwnership.entries()) {
+      if (owner.team === teamName) {
+        _fileOwnership.delete(filePath);
+      }
+    }
+
     summary.message = `Team "${teamName}" has been reset. ${summary.cleared.length} stores cleared.`;
 
     return textResult(JSON.stringify(summary, null, 2));
@@ -3119,3 +3484,18 @@ function startServer() {
 }
 
 module.exports = { startServer, TOOLS, executeTool };
+
+// Test-only exports — expose internal state for unit testing
+if (process.env.CMS_TEST_MODE) {
+  Object.assign(module.exports, {
+    _inboxCheckState,
+    _gateState,
+    _fileOwnership,
+    _workerTeamMap,
+    checkInboxEnforcement,
+    autoSetWorkerIdle,
+    getRosterSummary,
+    getTeamInstances,
+    getGateState,
+  });
+}

package/src/prompts.js

@@ -58,8 +58,9 @@ You have access to MCP tools that start with \`mcp__multi-session__team_*\` and
 
 === CRITICAL: MANDATORY WORKFLOW ===
 
-### Step 1: CHECK INBOX (Before Starting ANY Work)
-ALWAYS call \`mcp__multi-session__team_check_inbox\` FIRST, before doing anything else.
+### Step 1: CHECK INBOX (Before Starting ANY Work) — ENFORCED
+You MUST call \`mcp__multi-session__team_check_inbox\` FIRST — artifact and contract tools are blocked until you do.
+Calling \`artifact_publish\`, \`artifact_get\`, \`contract_create\`, or \`contract_start\` without checking inbox first will return a BLOCKED error.
 Your inbox may contain:
 - Task assignments or contracts from teammates
 - Questions that need IMMEDIATE replies
@@ -85,8 +86,8 @@ Follow the conventions STRICTLY. If NO convention artifact exists AND your work
 
 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.
+### Step 2: STATUS (Auto-Managed)
+Your status is automatically set to "active" when spawned and "idle" when your session stops. You do NOT need to call \`team_update_status\` for these transitions. Only call it if you need a custom status like "blocked" or to update your task description mid-work.
 
 ### Step 3: DO YOUR WORK
 Complete your assigned task using the standard coding tools (Read, Write, Edit, Bash, etc.).
@@ -99,18 +100,22 @@ mcp__multi-session__artifact_publish({
   type: "api-contract" | "schema-change" | "test-results" | "implementation" | "custom",
   name: "Human readable name",
   publisher: "${name}",
-  data: { /* your structured output */ },
+  data: {
+    /* your structured output */
+    filesCreated: ["src/routes/users.js", "src/models/user.js"],  // auto-registers file ownership
+    filesModified: ["src/app.js"]                                  // auto-registers file ownership
+  },
   summary: "Brief description of what this contains"
 })
 \`\`\`
+**File ownership tracking:** If your \`data\` object includes \`files\`, \`filesCreated\`, or \`filesModified\` arrays, the system automatically registers you as the owner of those files. This helps the orchestrator respect Rule 6 (don't fix worker code directly). You can also call \`register_files\` explicitly to register ownership of additional files.
 
 ### Step 5: CHECK INBOX AGAIN (After Major Steps)
 After completing significant work or before starting a new sub-task, check inbox again for messages from teammates.
 
 ### Step 6: SIGNAL COMPLETION
-When fully done, update your status to "idle" and broadcast a completion message:
+When fully done, broadcast a completion message. Your status will be automatically set to "idle" when your session ends, but you should still broadcast so teammates know:
 \`\`\`
-mcp__multi-session__team_update_status({ name: "${name}", status: "idle", task: "Completed: <summary>" })
 mcp__multi-session__team_broadcast({ from: "${name}", content: "Completed: <what you did>. Published artifact: <artifact-id>" })
 \`\`\`
 
@@ -140,7 +145,7 @@ mcp__multi-session__team_broadcast({ from: "${name}", content: "Completed: <what
 
 IMPORTANT: Follow these rules strictly. Violating them causes coordination failures.
 
-1. **ALWAYS check inbox before starting work.** Your teammates may have sent you critical information.
+1. **ALWAYS check inbox before starting work (ENFORCED).** Artifact and contract tools are blocked until you call \`team_check_inbox\`. Your teammates may have sent you critical information.
 
 2. **NEVER ask the orchestrator to relay messages.** Talk to teammates DIRECTLY using \`team_send_message\` or \`team_ask\`. The orchestrator should NOT be a message router.
 
@@ -608,6 +613,8 @@ The tool automatically:
 Returns a structured pass/fail report with recommendation.
 PROCEED ONLY IF the report says ALL CHECKS PASSED.
 
+**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:
 "Phase 0: [foundation], Phase 1: [routes], Phase 2: [tests], ..."
@@ -788,6 +795,58 @@ When done:
 // =============================================================================
 
 const ROLE_PROMPTS = {
+  'setup': `
+### Role-Specific: Setup / Foundation Worker
+
+Your job is to create the COMPLETE project foundation. Do not leave placeholders or TODOs.
+
+You MUST create ALL of these:
+1. **package.json** with all dependencies AND scripts (start, test, dev)
+2. **Database setup file** (schema, connection, initialization)
+3. **Main app file** (Express app with middleware — CORS, JSON parsing, error handling)
+4. **Server entry point** (server.js that imports app and calls app.listen on a port)
+5. **.gitignore**
+6. **Route mounting** in the main app file — use placeholder requires that Phase 1 workers will create:
+   \`\`\`javascript
+   const booksRoutes = require('./routes/books');
+   app.use('/books', booksRoutes);
+   \`\`\`
+   Create the routes/ directory and empty placeholder files so requires don't crash.
+
+CRITICAL: The project must be runnable with "npm start" after your phase completes, even if routes return empty responses. Do NOT leave comments like "// mount routes here" — actually mount them with placeholder requires.
+
+When done:
+- Publish a "project-foundation" artifact (type "custom") with file paths and connection details
+- Include: server port, database file path, all created files
+- Broadcast completion so Phase 1 workers can start
+`,
+
+  'foundation': `
+### Role-Specific: Setup / Foundation Worker
+
+Your job is to create the COMPLETE project foundation. Do not leave placeholders or TODOs.
+
+You MUST create ALL of these:
+1. **package.json** with all dependencies AND scripts (start, test, dev)
+2. **Database setup file** (schema, connection, initialization)
+3. **Main app file** (Express app with middleware — CORS, JSON parsing, error handling)
+4. **Server entry point** (server.js that imports app and calls app.listen on a port)
+5. **.gitignore**
+6. **Route mounting** in the main app file — use placeholder requires that Phase 1 workers will create:
+   \`\`\`javascript
+   const booksRoutes = require('./routes/books');
+   app.use('/books', booksRoutes);
+   \`\`\`
+   Create the routes/ directory and empty placeholder files so requires don't crash.
+
+CRITICAL: The project must be runnable with "npm start" after your phase completes, even if routes return empty responses. Do NOT leave comments like "// mount routes here" — actually mount them with placeholder requires.
+
+When done:
+- Publish a "project-foundation" artifact (type "custom") with file paths and connection details
+- Include: server port, database file path, all created files
+- Broadcast completion so Phase 1 workers can start
+`,
+
   'backend': `
 ### Role-Specific: Backend Developer
 - Publish API contracts as artifacts with type "api-contract" including: endpoints, methods, request/response schemas
@@ -919,6 +978,8 @@ IMPORTANT: You are the ORCHESTRATOR. Your job is to PLAN, SPAWN, and MONITOR —
 
 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.
 
 ### Critical Rule: Never Assign the Same File to Two Workers

package/src/store.js

@@ -16,6 +16,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { atomicWriteJson } = require('./atomic-io');
 
 // Default data directory in user's home
 const DEFAULT_DATA_DIR = path.join(os.homedir(), '.claude-multi-session');
@@ -54,7 +55,7 @@ class Store {
    * @param {Object<string, object>} sessions
    */
   saveAll(sessions) {
-    fs.writeFileSync(this.sessionsFile, JSON.stringify(sessions, null, 2), 'utf-8');
+    atomicWriteJson(this.sessionsFile, sessions);
   }
 
   /**

package/src/team-hub.js

@@ -19,6 +19,7 @@ const crypto = require('crypto');
 
 // Import our atomic file operations
 const { atomicWriteJson, readJsonSafe, appendJsonl } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
 
 /**
  * TeamHub class - manages team communication and roster
@@ -43,9 +44,13 @@ class TeamHub {
     const inboxDir = path.join(this.teamDir, 'inbox');
     const asksDir = path.join(this.teamDir, 'asks');
 
+    // Create locks directory for roster locking
+    this.locksDir = path.join(baseDir, 'team', teamName, 'locks');
+
     // Make sure all directories exist
     fs.mkdirSync(inboxDir, { recursive: true });
     fs.mkdirSync(asksDir, { recursive: true });
+    fs.mkdirSync(this.locksDir, { recursive: true });
 
     // Rate limiting: track message counts per sender
     // Map structure: { senderName: { count: number, windowStart: timestamp } }
@@ -66,7 +71,9 @@ class TeamHub {
   getRoster() {
     const rosterPath = path.join(this.teamDir, 'roster.json');
     // readJsonSafe returns empty array if file doesn't exist
-    return readJsonSafe(rosterPath, []);
+    const data = readJsonSafe(rosterPath, []);
+    // Defensive: ensure we always return an array, even if file contains {}
+    return Array.isArray(data) ? data : [];
   }
 
   /**
@@ -79,29 +86,37 @@ class TeamHub {
    * @param {string} options.model - AI model being used (e.g., 'sonnet', 'opus')
    */
   joinTeam(name, { role, task, model }) {
-    // Get current roster
-    const roster = this.getRoster();
-
-    // Create new member entry with all required fields
-    const newMember = {
-      name,
-      role,
-      task,
-      model,
-      status: 'active',
-      joinedAt: new Date().toISOString(),
-      lastSeen: new Date().toISOString()
-    };
+    // Acquire lock for roster modification
+    acquireLock(this.locksDir, 'roster');
+
+    try {
+      // Get current roster
+      const roster = this.getRoster();
+
+      // Create new member entry with all required fields
+      const newMember = {
+        name,
+        role,
+        task,
+        model,
+        status: 'active',
+        joinedAt: new Date().toISOString(),
+        lastSeen: new Date().toISOString()
+      };
 
-    // Remove existing entry if member is rejoining
-    const filtered = roster.filter(m => m.name !== name);
+      // Remove existing entry if member is rejoining
+      const filtered = roster.filter(m => m.name !== name);
 
-    // Add the new member
-    filtered.push(newMember);
+      // Add the new member
+      filtered.push(newMember);
 
-    // Save the updated roster
-    const rosterPath = path.join(this.teamDir, 'roster.json');
-    atomicWriteJson(rosterPath, filtered);
+      // Save the updated roster
+      const rosterPath = path.join(this.teamDir, 'roster.json');
+      atomicWriteJson(rosterPath, filtered);
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'roster');
+    }
   }
 
   /**
@@ -110,15 +125,23 @@ class TeamHub {
    * @param {string} name - Name of member to remove
    */
   leaveTeam(name) {
-    // Get current roster
-    const roster = this.getRoster();
-
-    // Filter out the member
-    const filtered = roster.filter(m => m.name !== name);
-
-    // Save the updated roster
-    const rosterPath = path.join(this.teamDir, 'roster.json');
-    atomicWriteJson(rosterPath, filtered);
+    // Acquire lock for roster modification
+    acquireLock(this.locksDir, 'roster');
+
+    try {
+      // Get current roster
+      const roster = this.getRoster();
+
+      // Filter out the member
+      const filtered = roster.filter(m => m.name !== name);
+
+      // Save the updated roster
+      const rosterPath = path.join(this.teamDir, 'roster.json');
+      atomicWriteJson(rosterPath, filtered);
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'roster');
+    }
   }
 
   /**
@@ -128,21 +151,29 @@ class TeamHub {
    * @param {Object} updates - Fields to update (status, task, role, etc.)
    */
   updateMember(name, updates) {
-    // Get current roster
-    const roster = this.getRoster();
-
-    // Find and update the member
-    const updated = roster.map(member => {
-      if (member.name === name) {
-        // Merge updates into existing member object
-        return { ...member, ...updates };
-      }
-      return member;
-    });
+    // Acquire lock for roster modification
+    acquireLock(this.locksDir, 'roster');
+
+    try {
+      // Get current roster
+      const roster = this.getRoster();
+
+      // Find and update the member
+      const updated = roster.map(member => {
+        if (member.name === name) {
+          // Merge updates into existing member object
+          return { ...member, ...updates };
+        }
+        return member;
+      });
 
-    // Save the updated roster
-    const rosterPath = path.join(this.teamDir, 'roster.json');
-    atomicWriteJson(rosterPath, updated);
+      // Save the updated roster
+      const rosterPath = path.join(this.teamDir, 'roster.json');
+      atomicWriteJson(rosterPath, updated);
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'roster');
+    }
   }
 
   /**