clearctx 3.0.0

package/src/mcp-server.js

@@ -0,0 +1,3501 @@
+/**
+ * MCP Server — Model Context Protocol server for clearctx.
+ *
+ * This turns the multi-session system into NATIVE Claude Code tools.
+ * Instead of Claude running CLI commands via Bash, it calls tools directly:
+ *
+ *   mcp__multi-session__spawn_session
+ *   mcp__multi-session__send_message
+ *   mcp__multi-session__delegate_task
+ *   etc.
+ *
+ * Protocol: JSON-RPC 2.0 over stdio (newline-delimited JSON).
+ * Zero dependencies — implements the MCP protocol manually.
+ *
+ * How MCP works:
+ *   1. Claude Code starts this server as a child process
+ *   2. Claude sends JSON-RPC requests on stdin
+ *   3. Server responds with JSON-RPC responses on stdout
+ *   4. All debug/log output goes to stderr (never stdout)
+ *
+ * JSON-RPC methods handled:
+ *   - initialize         → capability negotiation
+ *   - notifications/initialized → client confirms init (no response)
+ *   - tools/list         → return available tools
+ *   - tools/call         → execute a tool and return result
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const SessionManager = require('./manager');
+const Delegate = require('./delegate');
+const { buildFullTeamPrompt, getOrchestratorGuideSection } = require('./prompts');
+
+// Team Hub imports — all the new Layer 1, 2, 3 modules
+const TeamHub = require('./team-hub');
+const ArtifactStore = require('./artifact-store');
+const ContractStore = require('./contract-store');
+const DependencyResolver = require('./dependency-resolver');
+const LineageGraph = require('./lineage-graph');
+const PipelineEngine = require('./pipeline-engine');
+const SnapshotEngine = require('./snapshot-engine');
+
+// Layer 0: Session Continuity Engine
+const SessionSnapshot = require('./session-snapshot');
+const DiffEngine = require('./diff-engine');
+const BriefingGenerator = require('./briefing-generator');
+const DecisionJournal = require('./decision-journal');
+const PatternRegistry = require('./pattern-registry');
+const StaleDetector = require('./stale-detector');
+
+// Capture version at load time — used to detect stale server processes
+const LOADED_VERSION = require('../package.json').version;
+
+// =============================================================================
+// Server State — persists across all tool calls
+// =============================================================================
+
+// Single SessionManager instance for the entire MCP server lifetime.
+// This means spawned sessions stay alive between tool calls — much more
+// efficient than the CLI where each command creates a new manager.
+const manager = new SessionManager();
+
+// Track delegates per session (for continue/finish/abort)
+const delegates = new Map();
+
+// Team Hub instances (created lazily on first team tool call)
+// These are cached per team name to avoid recreating them on every call
+let teamHub = null;
+let artifactStore = null;
+let contractStore = null;
+let resolver = null;
+let lineageGraph = null;
+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
+ * and caches them for subsequent calls to the same team
+ *
+ * @param {string} teamName - Name of the team (default: 'default')
+ * @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);
+    artifactStore = new ArtifactStore(teamName);
+    contractStore = new ContractStore(teamName);
+    resolver = new DependencyResolver(teamName);
+    lineageGraph = new LineageGraph(teamName);
+    pipelineEngine = new PipelineEngine(teamName);
+    snapshotEngine = new SnapshotEngine(teamName);
+
+    // Set pipeline engine reference in resolver (avoid circular dependency)
+    resolver.setPipelineEngine(pipelineEngine);
+
+    // Update the current team name
+    currentTeamName = teamName;
+  }
+
+  return { teamHub, artifactStore, contractStore, resolver, lineageGraph, pipelineEngine, snapshotEngine };
+}
+
+// =============================================================================
+// Tool Definitions — these appear in Claude's tool list
+// =============================================================================
+
+const TOOLS = [
+  // ── Session Management ──────────────────────────────────────────────────
+  {
+    name: 'spawn_session',
+    description:
+      'Start a new Claude Code session. Spawns a long-lived streaming process. ' +
+      'Optionally sends an initial prompt and returns the response. ' +
+      'The session stays alive for follow-up messages via send_message.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:           { type: 'string', description: 'Unique session name (e.g. "fix-auth", "build-login")' },
+        prompt:         { type: 'string', description: 'Initial prompt to send (optional — if omitted, session starts idle)' },
+        model:          { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model to use (default: sonnet)' },
+        work_dir:       { type: 'string', description: 'Working directory for the session (default: current directory)' },
+        permission_mode:{ type: 'string', enum: ['default', 'acceptEdits', 'bypassPermissions', 'plan'], description: 'Permission mode (default: default)' },
+        allowed_tools:  { type: 'array', items: { type: 'string' }, description: 'Restrict to specific tools (e.g. ["Read", "Glob", "Grep"])' },
+        system_prompt:  { type: 'string', description: 'Text to append to system prompt' },
+        max_budget:     { type: 'number', description: 'Max budget in USD for the session' },
+        agent:          { type: 'string', description: 'Agent to use for the session' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'send_message',
+    description:
+      'Send a follow-up message to an existing session. ' +
+      'The session keeps full conversation context — no restart needed. ' +
+      'If the session was stopped, it auto-resumes using the saved session ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:    { type: 'string', description: 'Session name' },
+        message: { type: 'string', description: 'Message to send' },
+      },
+      required: ['name', 'message'],
+    },
+  },
+
+  {
+    name: 'resume_session',
+    description:
+      'Resume a stopped/paused session. Uses --resume with the saved session ID ' +
+      'to restore the full conversation. Optionally sends a message immediately.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:    { type: 'string', description: 'Session name to resume' },
+        message: { type: 'string', description: 'Optional message to send after resuming' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'pause_session',
+    description: 'Pause a session. The process stays alive but no messages are accepted until resumed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to pause' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'fork_session',
+    description:
+      'Fork a session into a new one. The new session starts with all the parent\'s ' +
+      'conversation context. Useful for trying different approaches from the same starting point.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:     { type: 'string', description: 'Source session name to fork from' },
+        new_name: { type: 'string', description: 'Name for the new forked session' },
+        message:  { type: 'string', description: 'Initial message for the fork (default: "Continue from the forked conversation.")' },
+        model:    { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model for the forked session' },
+      },
+      required: ['name', 'new_name'],
+    },
+  },
+
+  {
+    name: 'stop_session',
+    description: 'Gracefully stop a session. Saves state so it can be resumed later with resume_session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to stop' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'kill_session',
+    description: 'Force kill a session immediately. Use when stop_session is not working.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to kill' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Information ─────────────────────────────────────────────────────────
+  {
+    name: 'get_session_status',
+    description: 'Get detailed status of a session — status, model, cost, turns, interactions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'get_last_output',
+    description: 'Get the last response text from a session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'list_sessions',
+    description:
+      'List all sessions (both alive and stopped). Shows name, status, model, cost, turns. ' +
+      'Optionally filter by status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', enum: ['ready', 'paused', 'stopped', 'killed', 'busy'], description: 'Filter by status (optional)' },
+      },
+    },
+  },
+
+  {
+    name: 'get_history',
+    description: 'Get full interaction history (all prompts and responses) for a session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'delete_session',
+    description: 'Permanently delete a session and all its data. Cannot be undone.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to delete' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Delegate (Control Loop + Safety) ────────────────────────────────────
+  {
+    name: 'delegate_task',
+    description:
+      'Smart task delegation with control loop and safety net. ' +
+      'Spawns a child session, sends the task, monitors for issues ' +
+      '(permission denials, cost overruns, turn limits), and returns structured output. ' +
+      'Use this for autonomous task execution with safety guardrails. ' +
+      'After delegation, use continue_task to send corrections if the result is not satisfactory. ' +
+      'Use for SINGLE isolated tasks. For multi-session projects with 3+ workers, use team_spawn instead.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:          { type: 'string', description: 'Unique name for this delegated task' },
+        task:          { type: 'string', description: 'Task description for the child session' },
+        model:         { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model to use (default: sonnet)' },
+        preset:        { type: 'string', enum: ['read-only', 'review', 'edit', 'full', 'plan'], description: 'Permission preset (default: edit)' },
+        max_cost:      { type: 'number', description: 'Max cost in USD before auto-kill (default: 2.00)' },
+        max_turns:     { type: 'number', description: 'Max agent turns before auto-kill (default: 50)' },
+        context:       { type: 'string', description: 'Extra context to prepend to the task' },
+        work_dir:      { type: 'string', description: 'Working directory for the child session' },
+        system_prompt: { type: 'string', description: 'Text to append to system prompt' },
+        agent:         { type: 'string', description: 'Agent to use' },
+        safety:        { type: 'boolean', description: 'Enable safety net (default: true). Set false to disable cost/turn/path limits.' },
+      },
+      required: ['name', 'task'],
+    },
+  },
+
+  {
+    name: 'continue_task',
+    description:
+      'Send a follow-up correction or instruction to a delegated task. ' +
+      'The child session retains its full conversation memory — it remembers ' +
+      'what it did, what files it touched, and what the original task was. ' +
+      'Use this to correct mistakes, request changes, or add requirements.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:    { type: 'string', description: 'Name of the delegated task to continue' },
+        message: { type: 'string', description: 'Follow-up instruction or correction' },
+      },
+      required: ['name', 'message'],
+    },
+  },
+
+  {
+    name: 'finish_task',
+    description: 'Finish a delegated task — stop the session cleanly. Call this when the task result is satisfactory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name of the delegated task to finish' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'abort_task',
+    description: 'Abort a delegated task immediately — force kill the session. Use when the task is going off track and corrections are not working.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name of the delegated task to abort' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Batch ───────────────────────────────────────────────────────────────
+  {
+    name: 'batch_spawn',
+    description:
+      'Spawn multiple sessions in parallel. Each session gets its own name, prompt, and model. ' +
+      'Returns results for all sessions. Use for parallel task execution.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessions: {
+          type: 'array',
+          description: 'Array of session specs to spawn in parallel',
+          items: {
+            type: 'object',
+            properties: {
+              name:   { type: 'string', description: 'Session name' },
+              prompt: { type: 'string', description: 'Initial prompt' },
+              model:  { type: 'string', description: 'Model to use' },
+            },
+            required: ['name', 'prompt'],
+          },
+        },
+      },
+      required: ['sessions'],
+    },
+  },
+
+  // ── Orchestrator Guide ──────────────────────────────────────────────────
+  {
+    name: 'get_orchestrator_guide',
+    description:
+      'Get the multi-session orchestration guide. Call this when you need to orchestrate ' +
+      'a complex multi-session project and want instructions on how to spawn workers, ' +
+      'set up dependencies, and monitor progress.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        section: {
+          type: 'string',
+          enum: ['full', 'quick-start', 'team-spawn', 'delegate', 'monitoring', 'when-to-use'],
+          description: 'Which section of the guide to return (default: full)',
+        },
+      },
+    },
+  },
+
+  // ── Server Version ─────────────────────────────────────────────────────
+  {
+    name: 'server_version',
+    description:
+      'Check the running MCP server version and detect staleness. ' +
+      'Call this if tools seem missing or behave unexpectedly.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // TEAM HUB v2 — 32 new tools for team collaboration
+  // ══════════════════════════════════════════════════════════════════════════
+
+  // ── Layer 1: Team Chat (8 tools) ────────────────────────────────────────
+  {
+    name: 'team_spawn',
+    description:
+      'Spawn a session with team system prompt injected. The session joins the team roster and ' +
+      'receives context about teammates, communication tools, and collaboration rules. ' +
+      'Spawn ALL independent workers in a SINGLE message. Workers coordinate directly via team_ask — do NOT relay messages.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:   { type: 'string', description: 'Unique session name (e.g. "db-dev", "api-dev")' },
+        prompt: { type: 'string', description: 'Initial prompt to send' },
+        role:   { type: 'string', description: 'Role in the team (e.g. "database", "backend", "QA")' },
+        task:   { type: 'string', description: 'Current task description' },
+        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'],
+    },
+  },
+
+  {
+    name: 'team_send_message',
+    description:
+      'Send a direct message to a specific teammate. The message appears in their inbox.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from:     { type: 'string', description: 'Sender session name' },
+        to:       { type: 'string', description: 'Recipient session name' },
+        content:  { type: 'string', description: 'Message content' },
+        priority: { type: 'string', enum: ['low', 'normal', 'high', 'urgent'], description: 'Message priority (default: normal)' },
+        team:     { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['from', 'to', 'content'],
+    },
+  },
+
+  {
+    name: 'team_broadcast',
+    description:
+      'Send a message to all team members. Appears in everyone\'s inbox.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from:     { type: 'string', description: 'Sender session name' },
+        content:  { type: 'string', description: 'Message content' },
+        priority: { type: 'string', enum: ['low', 'normal', 'high', 'urgent'], description: 'Message priority (default: normal)' },
+        team:     { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['from', 'content'],
+    },
+  },
+
+  {
+    name: 'team_check_inbox',
+    description:
+      'Check inbox for unread messages. Sessions should check their inbox before starting work ' +
+      'and after major steps to stay coordinated with the team.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:      { type: 'string', description: 'Session name whose inbox to check' },
+        mark_read: { type: 'boolean', description: 'Mark messages as read after retrieving (default: true)' },
+        limit:     { type: 'number', description: 'Max messages to return (default: 20)' },
+        team:      { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'team_ask',
+    description:
+      'Ask a teammate a question and WAIT for their reply. This is a blocking operation that polls ' +
+      'until the recipient replies or the timeout expires.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from:     { type: 'string', description: 'Sender session name' },
+        to:       { type: 'string', description: 'Recipient session name' },
+        question: { type: 'string', description: 'Question to ask' },
+        timeout:  { type: 'number', description: 'Timeout in milliseconds (default: 60000 = 1 minute)' },
+        team:     { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['from', 'to', 'question'],
+    },
+  },
+
+  {
+    name: 'team_reply',
+    description:
+      'Reply to a question you received. Use the message_id from the ask message in your inbox.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from:       { type: 'string', description: 'Your session name' },
+        message_id: { type: 'string', description: 'ID of the ask message you\'re replying to' },
+        answer:     { type: 'string', description: 'Your answer to the question' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['from', 'message_id', 'answer'],
+    },
+  },
+
+  {
+    name: 'team_roster',
+    description:
+      'View the current team roster with all members, their roles, status, and lastSeen times.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team: { type: 'string', description: 'Team name (default: "default")' },
+      },
+    },
+  },
+
+  {
+    name: 'team_update_status',
+    description:
+      'Update your own status in the team roster. Use this to keep teammates informed of what you\'re doing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:   { type: 'string', description: 'Your session name' },
+        status: { type: 'string', enum: ['active', 'busy', 'idle', 'offline'], description: 'Your current status' },
+        task:   { type: 'string', description: 'What you\'re currently working on' },
+        role:   { type: 'string', description: 'Your role (if it changed)' },
+        team:   { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Layer 2: Artifacts (4 tools) ─────────────────────────────────────────
+  {
+    name: 'artifact_publish',
+    description:
+      'Publish a structured artifact (versioned, immutable). This is how sessions exchange structured ' +
+      'data like API contracts, schemas, test results. Publishing triggers dependency resolution and pipelines.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId:   { type: 'string', description: 'Unique artifact ID (e.g. "api-contract-user-auth")' },
+        type:         { type: 'string', description: 'Artifact type (e.g. "api-contract", "schema-change", "test-results", "custom")' },
+        name:         { type: 'string', description: 'Human-readable name' },
+        data:         { type: 'object', description: 'The artifact data payload (validated against schema for well-known types)' },
+        summary:      { type: 'string', description: 'Brief summary of this version' },
+        tags:         { type: 'array', items: { type: 'string' }, description: 'Tags for filtering (e.g. ["auth", "v1"])' },
+        publisher:    { type: 'string', description: 'Session name publishing this artifact' },
+        derivedFrom:  { type: 'array', items: { type: 'string' }, description: 'Array of artifact IDs this was derived from (for lineage)' },
+        team:         { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId', 'type', 'name', 'data'],
+    },
+  },
+
+  {
+    name: 'artifact_get',
+    description:
+      'Read an artifact (latest version or specific version). ' +
+      'IMPORTANT: Pass your session name as the "reader" parameter to track artifact consumption. ' +
+      'The orchestrator uses this to verify workers actually read shared data.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID to retrieve' },
+        version:    { type: 'number', description: 'Specific version number (omit for latest)' },
+        reader:     { type: 'string', description: 'Session name reading this artifact (for tracking who consumed it)' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId'],
+    },
+  },
+
+  {
+    name: 'artifact_list',
+    description:
+      'List all artifacts with optional filters by type, publisher, or tag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type:      { type: 'string', description: 'Filter by artifact type' },
+        publisher: { type: 'string', description: 'Filter by publisher session name' },
+        tag:       { type: 'string', description: 'Filter by tag' },
+        team:      { type: 'string', description: 'Team name (default: "default")' },
+      },
+    },
+  },
+
+  {
+    name: 'artifact_readers',
+    description:
+      'Check who has read a specific artifact. Use this to verify that workers actually consumed shared artifacts like conventions or schemas.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID to check readers for' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId'],
+    },
+  },
+
+  {
+    name: 'artifact_history',
+    description:
+      'View the version history of an artifact.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId'],
+    },
+  },
+
+  // ── Layer 2: Contracts (8 tools) ─────────────────────────────────────────
+  {
+    name: 'contract_create',
+    description:
+      'Create a task contract and assign it to ANY teammate (peer-to-peer). Contracts define work with ' +
+      'inputs, outputs, dependencies, and acceptance criteria. The dependency resolver automatically advances ' +
+      'contracts when their dependencies are satisfied.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId:         { type: 'string', description: 'Unique contract ID (e.g. "build-auth-api")' },
+        title:              { type: 'string', description: 'Human-readable title' },
+        assignee:           { type: 'string', description: 'Session name who will do the work' },
+        assigner:           { type: 'string', description: 'Session name who created the contract' },
+        description:        { type: 'string', description: 'Detailed description of the work' },
+        inputs:             { type: 'object', description: 'Input artifacts and context for the assignee' },
+        expectedOutputs:    { type: 'array', description: 'What the assignee should produce' },
+        dependencies:       { type: 'array', description: 'Contract/artifact dependencies that must be satisfied first' },
+        acceptanceCriteria: { type: 'array', description: 'How we know the work is done' },
+        autoComplete:       { type: 'boolean', description: 'Auto-complete when criteria met (default: true)' },
+        timeoutMs:          { type: 'number', description: 'Timeout in milliseconds (null = no timeout)' },
+        maxRetries:         { type: 'number', description: 'Maximum reopen attempts (default: 3)' },
+        priority:           { type: 'string', enum: ['low', 'normal', 'high', 'urgent'], description: 'Priority level (default: normal)' },
+        team:               { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId', 'title', 'assignee', 'assigner'],
+    },
+  },
+
+  {
+    name: 'contract_start',
+    description:
+      'Start working on a contract. Transitions status from ready to in_progress and returns the contract ' +
+      'details with resolved input artifacts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId: { type: 'string', description: 'Contract ID to start' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId'],
+    },
+  },
+
+  {
+    name: 'contract_complete',
+    description:
+      'Mark a contract as completed. This triggers dependency resolution for downstream contracts and ' +
+      'evaluates reactive pipelines.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId:         { type: 'string', description: 'Contract ID to complete' },
+        summary:            { type: 'string', description: 'Summary of what was done' },
+        publishedArtifacts: { type: 'array', items: { type: 'string' }, description: 'Artifact IDs that were published' },
+        team:               { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId'],
+    },
+  },
+
+  {
+    name: 'contract_fail',
+    description:
+      'Mark a contract as failed. Notifies the assigner and triggers dependency resolution.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId: { type: 'string', description: 'Contract ID to fail' },
+        reason:     { type: 'string', description: 'Why the contract failed' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId', 'reason'],
+    },
+  },
+
+  {
+    name: 'contract_reopen',
+    description:
+      'Reopen a failed or completed contract for retry. Increments retryCount and transitions back to ready. ' +
+      'Rejects if retryCount >= maxRetries.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId: { type: 'string', description: 'Contract ID to reopen' },
+        reason:     { type: 'string', description: 'Why we are reopening' },
+        newInputs:  { type: 'object', description: 'Optional updated inputs' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId'],
+    },
+  },
+
+  {
+    name: 'contract_get',
+    description:
+      'Get full details of a contract including status, inputs, outputs, dependencies, and acceptance criteria.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId: { type: 'string', description: 'Contract ID' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId'],
+    },
+  },
+
+  {
+    name: 'contract_list',
+    description:
+      'List all contracts with optional filters by status, assignee, or assigner.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status:   { type: 'string', enum: ['pending', 'ready', 'in_progress', 'completed', 'failed'], description: 'Filter by status' },
+        assignee: { type: 'string', description: 'Filter by assignee session name' },
+        assigner: { type: 'string', description: 'Filter by assigner session name' },
+        team:     { type: 'string', description: 'Team name (default: "default")' },
+      },
+    },
+  },
+
+  {
+    name: 'contract_reassign',
+    description:
+      'Reassign a contract to a different session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractId:  { type: 'string', description: 'Contract ID' },
+        newAssignee: { type: 'string', description: 'New assignee session name' },
+        team:        { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['contractId', 'newAssignee'],
+    },
+  },
+
+  // ── Layer 3: Lineage (4 tools) ───────────────────────────────────────────
+  {
+    name: 'artifact_lineage',
+    description:
+      'Query the artifact lineage graph. Upstream shows what this was derived from. Downstream shows what ' +
+      'depends on this. Returns the full chain recursively.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID' },
+        direction:  { type: 'string', enum: ['upstream', 'downstream'], description: 'Which direction to traverse' },
+        version:    { type: 'number', description: 'Specific version (omit for latest)' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId', 'direction'],
+    },
+  },
+
+  {
+    name: 'artifact_impact',
+    description:
+      'Analyze the impact radius: "If I change this artifact, what downstream artifacts and contracts break?" ' +
+      'Returns all affected artifacts and contracts with impact depth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID to analyze' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId'],
+    },
+  },
+
+  {
+    name: 'artifact_stale',
+    description:
+      'Find all stale artifacts — artifacts derived from sources that have been updated to newer versions. ' +
+      'This helps identify what needs to be regenerated after changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team: { type: 'string', description: 'Team name (default: "default")' },
+      },
+    },
+  },
+
+  {
+    name: 'team_audit',
+    description:
+      'Get the full audit trail for an artifact: who created it, from what inputs, under which contract, ' +
+      'at what time. Follows the provenance chain upstream to the root.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: { type: 'string', description: 'Artifact ID' },
+        version:    { type: 'number', description: 'Specific version (omit for latest)' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['artifactId'],
+    },
+  },
+
+  // ── Layer 3: Pipelines (4 tools) ─────────────────────────────────────────
+  {
+    name: 'pipeline_create',
+    description:
+      'Create a reactive pipeline: "When X happens, automatically do Y." Pipelines contain trigger/condition/action ' +
+      'rules that fire when artifacts are published or contracts change status. This enables self-healing CI loops.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pipelineId: { type: 'string', description: 'Unique pipeline ID (e.g. "ci-loop")' },
+        rules:      { type: 'array', description: 'Array of trigger/condition/action rules' },
+        owner:      { type: 'string', description: 'Session name who owns this pipeline' },
+        enabled:    { type: 'boolean', description: 'Whether pipeline is active (default: true)' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['pipelineId', 'rules'],
+    },
+  },
+
+  {
+    name: 'pipeline_list',
+    description:
+      'List all pipelines with optional filter by owner. Shows execution counts and last fired times.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: { type: 'string', description: 'Filter by owner session name' },
+        team:  { type: 'string', description: 'Team name (default: "default")' },
+      },
+    },
+  },
+
+  {
+    name: 'pipeline_pause',
+    description:
+      'Pause a pipeline (disable without deleting). The pipeline stops evaluating rules.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pipelineId: { type: 'string', description: 'Pipeline ID to pause' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['pipelineId'],
+    },
+  },
+
+  {
+    name: 'pipeline_resume',
+    description:
+      'Resume a paused pipeline. It will start evaluating rules again on new events.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pipelineId: { type: 'string', description: 'Pipeline ID to resume' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['pipelineId'],
+    },
+  },
+
+  // ── Layer 3: Snapshots (4 tools) ─────────────────────────────────────────
+  {
+    name: 'team_snapshot',
+    description:
+      'Capture a snapshot of the entire team state (contracts, artifacts, pipelines). Use this before ' +
+      'risky operations or at major milestones.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        snapshotId:  { type: 'string', description: 'Unique snapshot ID (e.g. "pre-work", "all-complete")' },
+        label:       { type: 'string', description: 'Short label for this snapshot' },
+        description: { type: 'string', description: 'Longer description' },
+        team:        { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['snapshotId'],
+    },
+  },
+
+  {
+    name: 'team_snapshot_list',
+    description:
+      'List all snapshots with timestamp, label, and summary of what was captured.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team: { type: 'string', description: 'Team name (default: "default")' },
+      },
+    },
+  },
+
+  {
+    name: 'team_rollback',
+    description:
+      'Rollback to a previous snapshot. Resets contract and pipeline state. Artifact version files are ' +
+      'preserved on disk but can be marked as rolled-back in the index.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        snapshotId:        { type: 'string', description: 'Snapshot ID to rollback to' },
+        preserveArtifacts: { type: 'boolean', description: 'Keep artifact index entries (default: true)' },
+        team:              { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['snapshotId'],
+    },
+  },
+
+  {
+    name: 'team_replay',
+    description:
+      'Replay from a snapshot with optional overrides to contract inputs. Rollbacks to the snapshot, ' +
+      'applies modifications, then re-triggers dependency resolution. Use this to test "what if" scenarios.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        snapshotId: { type: 'string', description: 'Snapshot ID to replay from' },
+        overrides:  { type: 'object', description: 'Map of contractId -> { inputs: {...} } to override' },
+        team:       { type: 'string', description: 'Team name (default: "default")' },
+      },
+      required: ['snapshotId'],
+    },
+  },
+
+  // ── 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'],
+    },
+  },
+
+  // ── 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',
+    description: 'Capture a lightweight snapshot of the current project state (git state, file tree, working context). Use on session end.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        sessionName: { type: 'string', description: 'Name of the session capturing this snapshot' },
+        taskSummary: { type: 'string', description: 'What you were working on' },
+        activeFiles: { type: 'array', items: { type: 'string' }, description: 'Files read/edited this session' },
+        openQuestions: { type: 'array', items: { type: 'string' }, description: 'Unresolved questions' }
+      },
+      required: ['projectPath', 'sessionName']
+    }
+  },
+  {
+    name: 'continuity_briefing',
+    description: 'Generate a diff-aware session briefing. Shows what changed since last session, previous context, decisions, patterns. Use on session start.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        maxTokens: { type: 'number', description: 'Max briefing length in characters (default: 4000)' },
+        includeDecisions: { type: 'boolean', description: 'Include recent decisions (default: true)' },
+        includePatterns: { type: 'boolean', description: 'Include pattern rules (default: true)' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'continuity_status',
+    description: 'Quick status check: what changed since the last snapshot. Lighter than a full briefing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'continuity_diff',
+    description: 'Detailed diff between two snapshots or between latest snapshot and current state.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        fromSnapshot: { type: 'string', description: 'Source snapshot ID (default: latest)' },
+        toSnapshot: { type: 'string', description: 'Target snapshot ID (default: current state)' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'continuity_history',
+    description: 'List all snapshots for a project, newest first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        limit: { type: 'number', description: 'Max snapshots to return (default: 20)' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'continuity_stale_check',
+    description: 'Check if your previous session context is stale. Shows warnings about changed files, branch switches, etc.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'decision_add',
+    description: 'Record an architectural or design decision in the project decision journal.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        decision: { type: 'string', description: 'The decision made (e.g., "Use bcrypt over argon2")' },
+        reason: { type: 'string', description: 'Why this decision was made' },
+        files: { type: 'array', items: { type: 'string' }, description: 'Related file paths' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Tags for categorization' }
+      },
+      required: ['projectPath', 'decision']
+    }
+  },
+  {
+    name: 'decision_list',
+    description: 'List recent decisions from the project decision journal.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        limit: { type: 'number', description: 'Max decisions to return (default: 50)' },
+        tag: { type: 'string', description: 'Filter by tag' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'decision_search',
+    description: 'Search decisions by keyword across decision text, reasoning, and context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        keyword: { type: 'string', description: 'Search keyword (case-insensitive)' }
+      },
+      required: ['projectPath', 'keyword']
+    }
+  },
+  {
+    name: 'pattern_add',
+    description: 'Add a coding pattern rule. Patterns are corrections that persist across sessions (e.g., "Always use enum constants for status comparisons").',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        rule: { type: 'string', description: 'The pattern rule' },
+        context: { type: 'string', description: 'Where this pattern applies (e.g., "auth module")' },
+        example: { type: 'string', description: 'Code example or explanation' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Tags for categorization' }
+      },
+      required: ['projectPath', 'rule']
+    }
+  },
+  {
+    name: 'pattern_list',
+    description: 'List all coding patterns for a project.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        tag: { type: 'string', description: 'Filter by tag' }
+      },
+      required: ['projectPath']
+    }
+  },
+  {
+    name: 'pattern_remove',
+    description: 'Remove a coding pattern by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectPath: { type: 'string', description: 'Absolute path to the project directory' },
+        patternId: { type: 'string', description: 'Pattern ID to remove' }
+      },
+      required: ['projectPath', 'patternId']
+    }
+  }
+];
+
+// =============================================================================
+// 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
+// =============================================================================
+
+/**
+ * Execute a tool by name with given arguments.
+ * Returns { content: [{ type: "text", text: "..." }], isError?: true }
+ */
+async function executeTool(toolName, args) {
+  try {
+    switch (toolName) {
+      // ── Session Management ────────────────────────────────────────────
+      case 'spawn_session':
+        return await handleSpawn(args);
+      case 'send_message':
+        return await handleSend(args);
+      case 'resume_session':
+        return await handleResume(args);
+      case 'pause_session':
+        return handlePause(args);
+      case 'fork_session':
+        return await handleFork(args);
+      case 'stop_session':
+        return handleStop(args);
+      case 'kill_session':
+        return handleKill(args);
+
+      // ── Information ───────────────────────────────────────────────────
+      case 'get_session_status':
+        return handleStatus(args);
+      case 'get_last_output':
+        return handleLastOutput(args);
+      case 'list_sessions':
+        return handleList(args);
+      case 'get_history':
+        return handleHistory(args);
+      case 'delete_session':
+        return handleDelete(args);
+
+      // ── Delegate ──────────────────────────────────────────────────────
+      case 'delegate_task':
+        return await handleDelegate(args);
+      case 'continue_task':
+        return await handleContinue(args);
+      case 'finish_task':
+        return handleFinish(args);
+      case 'abort_task':
+        return handleAbort(args);
+
+      // ── Server Version ──────────────────────────────────────────────
+      case 'server_version':
+        return handleServerVersion(args);
+
+      // ── Orchestrator Guide ────────────────────────────────────────────
+      case 'get_orchestrator_guide':
+        return handleGetOrchestratorGuide(args);
+
+      // ── Batch ─────────────────────────────────────────────────────────
+      case 'batch_spawn':
+        return await handleBatch(args);
+
+      // ══════════════════════════════════════════════════════════════════
+      // Team Hub Tools
+      // ══════════════════════════════════════════════════════════════════
+
+      // ── Layer 1: Chat ─────────────────────────────────────────────────
+      case 'team_spawn':
+        return await handleTeamSpawn(args);
+      case 'team_send_message':
+        return handleTeamSendMessage(args);
+      case 'team_broadcast':
+        return handleTeamBroadcast(args);
+      case 'team_check_inbox':
+        return handleTeamCheckInbox(args);
+      case 'team_ask':
+        return await handleTeamAsk(args);
+      case 'team_reply':
+        return handleTeamReply(args);
+      case 'team_roster':
+        return handleTeamRoster(args);
+      case 'team_update_status':
+        return handleTeamUpdateStatus(args);
+
+      // ── Layer 2: Artifacts ────────────────────────────────────────────
+      case 'artifact_publish':
+        return await handleArtifactPublish(args);
+      case 'artifact_get':
+        return handleArtifactGet(args);
+      case 'artifact_list':
+        return handleArtifactList(args);
+      case 'artifact_readers':
+        return handleArtifactReaders(args);
+      case 'artifact_history':
+        return handleArtifactHistory(args);
+
+      // ── Layer 2: Contracts ────────────────────────────────────────────
+      case 'contract_create':
+        return await handleContractCreate(args);
+      case 'contract_start':
+        return handleContractStart(args);
+      case 'contract_complete':
+        return await handleContractComplete(args);
+      case 'contract_fail':
+        return await handleContractFail(args);
+      case 'contract_reopen':
+        return await handleContractReopen(args);
+      case 'contract_get':
+        return handleContractGet(args);
+      case 'contract_list':
+        return handleContractList(args);
+      case 'contract_reassign':
+        return handleContractReassign(args);
+
+      // ── Layer 3: Lineage ──────────────────────────────────────────────
+      case 'artifact_lineage':
+        return handleArtifactLineage(args);
+      case 'artifact_impact':
+        return handleArtifactImpact(args);
+      case 'artifact_stale':
+        return handleArtifactStale(args);
+      case 'team_audit':
+        return handleTeamAudit(args);
+
+      // ── Layer 3: Pipelines ────────────────────────────────────────────
+      case 'pipeline_create':
+        return handlePipelineCreate(args);
+      case 'pipeline_list':
+        return handlePipelineList(args);
+      case 'pipeline_pause':
+        return handlePipelinePause(args);
+      case 'pipeline_resume':
+        return handlePipelineResume(args);
+
+      // ── Layer 3: Snapshots ────────────────────────────────────────────
+      case 'team_snapshot':
+        return handleTeamSnapshot(args);
+      case 'team_snapshot_list':
+        return handleTeamSnapshotList(args);
+      case 'team_rollback':
+        return handleTeamRollback(args);
+      case 'team_replay':
+        return await handleTeamReplay(args);
+
+      // ── Phase Gate & Team Reset ──
+      case 'phase_gate':
+        return handlePhaseGate(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);
+        const result = snap.capture(args.sessionName, {
+          activeFiles: args.activeFiles,
+          taskSummary: args.taskSummary,
+          openQuestions: args.openQuestions
+        });
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'continuity_briefing': {
+        const gen = new BriefingGenerator(args.projectPath);
+        const result = gen.generate({
+          maxTokens: args.maxTokens,
+          includeDecisions: args.includeDecisions,
+          includePatterns: args.includePatterns
+        });
+        return textResult(result.markdown);
+      }
+      case 'continuity_status': {
+        const diff = new DiffEngine(args.projectPath);
+        const result = diff.diffFromLatest();
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'continuity_diff': {
+        const diff = new DiffEngine(args.projectPath);
+        let result;
+        if (args.fromSnapshot && args.toSnapshot) {
+          result = diff.diffBetween(args.fromSnapshot, args.toSnapshot);
+        } else {
+          result = diff.diffFromLatest();
+        }
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'continuity_history': {
+        const snap = new SessionSnapshot(args.projectPath);
+        const result = snap.list(args.limit || 20);
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'continuity_stale_check': {
+        const detector = new StaleDetector(args.projectPath);
+        const result = detector.check();
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'decision_add': {
+        const journal = new DecisionJournal(args.projectPath);
+        const result = journal.add({
+          decision: args.decision,
+          reason: args.reason,
+          files: args.files,
+          tags: args.tags
+        });
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'decision_list': {
+        const journal = new DecisionJournal(args.projectPath);
+        const result = journal.list({ limit: args.limit, tag: args.tag });
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'decision_search': {
+        const journal = new DecisionJournal(args.projectPath);
+        const result = journal.search(args.keyword);
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'pattern_add': {
+        const registry = new PatternRegistry(args.projectPath);
+        const result = registry.add({
+          rule: args.rule,
+          context: args.context,
+          example: args.example,
+          tags: args.tags
+        });
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'pattern_list': {
+        const registry = new PatternRegistry(args.projectPath);
+        const result = registry.list({ tag: args.tag });
+        return textResult(JSON.stringify(result, null, 2));
+      }
+      case 'pattern_remove': {
+        const registry = new PatternRegistry(args.projectPath);
+        const result = registry.remove(args.patternId);
+        return textResult(JSON.stringify(result, null, 2));
+      }
+
+      default:
+        return errorResult(`Unknown tool: ${toolName}`);
+    }
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Session Handlers ──────────────────────────────────────────────────────
+
+async function handleSpawn(args) {
+  const { session, response } = await manager.spawn(args.name, {
+    prompt: args.prompt,
+    model: args.model,
+    workDir: args.work_dir,
+    permissionMode: args.permission_mode,
+    allowedTools: args.allowed_tools,
+    systemPrompt: args.system_prompt,
+    maxBudget: args.max_budget,
+    agent: args.agent,
+  });
+
+  const result = {
+    session_name: session.name,
+    status: session.status,
+    model: session.model,
+    session_id: session.id,
+  };
+
+  if (response) {
+    result.response = response.text;
+    result.cost = response.cost;
+    result.turns = response.turns;
+    result.duration_ms = response.duration;
+  } else {
+    result.message = 'Session started (idle). Send a message with send_message.';
+  }
+
+  return textResult(JSON.stringify(result, null, 2));
+}
+
+async function handleSend(args) {
+  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,
+      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);
+  }
+}
+
+async function handleResume(args) {
+  const response = await manager.resume(args.name, args.message);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'resumed',
+    response: response?.text || null,
+    cost: response?.cost || 0,
+    turns: response?.turns || 0,
+  }, null, 2));
+}
+
+function handlePause(args) {
+  manager.pause(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'paused',
+  }, null, 2));
+}
+
+async function handleFork(args) {
+  const { session, response } = await manager.fork(args.name, args.new_name, {
+    message: args.message,
+    model: args.model,
+  });
+
+  return textResult(JSON.stringify({
+    source: args.name,
+    forked_as: args.new_name,
+    status: session.status,
+    response: response?.text || '',
+    cost: response?.cost || 0,
+    turns: response?.turns || 0,
+  }, null, 2));
+}
+
+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',
+    message: 'Session stopped. Can be resumed later with resume_session.',
+  }, null, 2));
+}
+
+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',
+  }, null, 2));
+}
+
+// ── Information Handlers ──────────────────────────────────────────────────
+
+function handleStatus(args) {
+  const info = manager.status(args.name);
+  return textResult(JSON.stringify({
+    name: info.name,
+    status: info.status,
+    model: info.model,
+    session_id: info.claudeSessionId || info.id,
+    work_dir: info.workDir,
+    total_cost: info.totalCostUsd || 0,
+    total_turns: info.totalTurns || 0,
+    interactions: info.interactionCount || (info.interactions || []).length,
+    pid: info.pid || null,
+  }, null, 2));
+}
+
+function handleLastOutput(args) {
+  const last = manager.lastOutput(args.name);
+  if (!last) {
+    return textResult(JSON.stringify({ session_name: args.name, output: null, message: 'No output yet.' }, null, 2));
+  }
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    prompt: last.prompt,
+    response: last.response,
+    cost: last.cost,
+    timestamp: last.timestamp,
+  }, null, 2));
+}
+
+function handleList(args) {
+  const sessions = manager.list(args.status);
+  const summary = sessions.map(s => ({
+    name: s.name,
+    status: s.status,
+    model: s.model,
+    total_cost: s.totalCostUsd || 0,
+    total_turns: s.totalTurns || 0,
+    interactions: s.interactionCount || (s.interactions || []).length,
+  }));
+  return textResult(JSON.stringify({ total: summary.length, sessions: summary }, null, 2));
+}
+
+function handleHistory(args) {
+  const hist = manager.history(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    interaction_count: hist.length,
+    interactions: hist.map((h, i) => ({
+      index: i,
+      prompt: h.prompt,
+      response: h.response,
+      cost: h.cost,
+      turns: h.turns,
+      duration_ms: h.duration,
+      timestamp: h.timestamp,
+    })),
+  }, null, 2));
+}
+
+function handleDelete(args) {
+  manager.delete(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'deleted',
+    message: 'Session permanently deleted.',
+  }, null, 2));
+}
+
+// ── Delegate Handlers ─────────────────────────────────────────────────────
+
+async function handleDelegate(args) {
+  // Create or reuse a delegate instance for this session
+  let delegate = delegates.get(args.name);
+  if (!delegate) {
+    delegate = new Delegate(manager);
+    delegates.set(args.name, delegate);
+  }
+
+  const result = await delegate.run(args.name, {
+    task: args.task,
+    model: args.model,
+    preset: args.preset,
+    workDir: args.work_dir,
+    maxCost: args.max_cost,
+    maxTurns: args.max_turns,
+    context: args.context,
+    systemPrompt: args.system_prompt,
+    agent: args.agent,
+    safety: args.safety,
+  });
+
+  return textResult(JSON.stringify(result, null, 2));
+}
+
+async function handleContinue(args) {
+  // Get or create delegate for this session
+  let delegate = delegates.get(args.name);
+  if (!delegate) {
+    delegate = new Delegate(manager);
+    delegates.set(args.name, delegate);
+  }
+
+  const result = await delegate.continue(args.name, args.message);
+  return textResult(JSON.stringify(result, null, 2));
+}
+
+function handleFinish(args) {
+  const delegate = delegates.get(args.name);
+  if (delegate) {
+    delegate.finish(args.name);
+    delegates.delete(args.name);
+  } else {
+    // No delegate — just stop the session
+    try { manager.stop(args.name); } catch (e) {}
+  }
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'finished',
+    message: 'Task finished. Session stopped.',
+  }, null, 2));
+}
+
+function handleAbort(args) {
+  const delegate = delegates.get(args.name);
+  if (delegate) {
+    delegate.abort(args.name);
+    delegates.delete(args.name);
+  } else {
+    try { manager.kill(args.name); } catch (e) {}
+  }
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'aborted',
+    message: 'Task aborted. Session killed.',
+  }, null, 2));
+}
+
+// ── Batch Handler ─────────────────────────────────────────────────────────
+
+async function handleBatch(args) {
+  const results = await manager.batch(args.sessions);
+  const summary = results.map(r => ({
+    name: r.session?.name || 'unknown',
+    status: r.error ? 'failed' : 'completed',
+    response: r.response?.text || null,
+    cost: r.response?.cost || 0,
+    error: r.error || null,
+  }));
+  return textResult(JSON.stringify({ total: summary.length, results: summary }, null, 2));
+}
+
+// ── Orchestrator Guide Handler ─────────────────────────────────────────────
+
+/**
+ * Return the orchestrator guide (or a specific section of it).
+ * Uses the section constants from src/prompts.js.
+ */
+function handleGetOrchestratorGuide(args) {
+  const section = args.section || 'full';
+  const guide = getOrchestratorGuideSection(section);
+  return textResult(guide);
+}
+
+/**
+ * Check the running MCP server version and detect staleness.
+ * Compares the version loaded into memory at startup against the
+ * version currently installed on disk (package.json).
+ */
+function handleServerVersion() {
+  let installedVersion = LOADED_VERSION;
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    installedVersion = pkg.version;
+  } catch (e) {
+    // If we can't read package.json at runtime, use loaded version
+  }
+
+  const stale = LOADED_VERSION !== installedVersion;
+  return textResult(JSON.stringify({
+    running: LOADED_VERSION,
+    installed: installedVersion,
+    stale,
+    message: stale
+      ? `Server is stale: running v${LOADED_VERSION} but v${installedVersion} is installed. Restart Claude Code to load new tools.`
+      : `Server is up to date (v${LOADED_VERSION}).`
+  }, null, 2));
+}
+
+// =============================================================================
+// Team Hub Handlers — Layer 1, 2, 3
+// =============================================================================
+
+// ── Layer 1: Team Chat Handlers ───────────────────────────────────────────
+
+/**
+ * Build team system prompt from roster.
+ * Delegates to the centralized prompt builder in src/prompts.js which applies
+ * production-quality prompt engineering techniques (identity anchoring, examples,
+ * anti-patterns, state machines, tool preference hierarchy, etc.)
+ */
+function buildTeamSystemPrompt(name, role, task, roster, teamName) {
+  return buildFullTeamPrompt({ name, role, task, roster, teamName });
+}
+
+async function handleTeamSpawn(args) {
+  try {
+    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',
+      task: args.task || 'Starting up',
+      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();
+
+    // Build team system prompt (now includes role-specific guidance, examples, anti-patterns)
+    const teamSystemPrompt = buildTeamSystemPrompt(args.name, args.role, args.task, roster, teamName);
+
+    // Spawn the session with team system prompt appended
+    // Default to bypassPermissions so team sessions can write files without manual approval
+    const { session, response } = await manager.spawn(args.name, {
+      prompt: args.prompt,
+      model: args.model,
+      systemPrompt: teamSystemPrompt,
+      permissionMode: args.permission_mode || 'bypassPermissions',
+      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,
+      model: session.model,
+      team: teamName,
+      role: args.role,
+      roster_size: roster.length,
+    };
+
+    if (response) {
+      result.response = response.text;
+      result.cost = response.cost;
+      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) + 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);
+  }
+}
+
+function handleTeamSendMessage(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { teamHub } = getTeamInstances(teamName);
+
+    teamHub.sendDirect(args.from, args.to, args.content, {
+      priority: args.priority || 'normal',
+    });
+
+    return textResult(JSON.stringify({
+      status: 'sent',
+      from: args.from,
+      to: args.to,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamBroadcast(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { teamHub } = getTeamInstances(teamName);
+
+    const count = teamHub.sendBroadcast(args.from, args.content, {
+      priority: args.priority || 'normal',
+    });
+
+    return textResult(JSON.stringify({
+      status: 'broadcast',
+      from: args.from,
+      recipients: count,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamCheckInbox(args) {
+  try {
+    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,
+    });
+
+    return textResult(JSON.stringify({
+      session: args.name,
+      team: teamName,
+      count: messages.length,
+      messages: messages.map(m => ({
+        id: m.id,
+        from: m.from,
+        type: m.type,
+        content: m.content,
+        timestamp: m.timestamp,
+        priority: m.priority,
+        replyTo: m.replyTo,
+      })),
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+async function handleTeamAsk(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { teamHub } = getTeamInstances(teamName);
+
+    // Create the ask
+    const askId = teamHub.createAsk(
+      args.from,
+      args.to,
+      args.question,
+      args.timeout || 60000
+    );
+
+    // Poll for reply
+    const reply = await teamHub.pollForReply(askId, args.timeout || 60000);
+
+    if (reply) {
+      return textResult(JSON.stringify({
+        status: 'answered',
+        question: args.question,
+        answer: reply.answer,
+        from: args.from,
+        to: args.to,
+        team: teamName,
+      }, null, 2));
+    } else {
+      return textResult(JSON.stringify({
+        status: 'timeout',
+        question: args.question,
+        message: 'No reply received within timeout period',
+        team: teamName,
+      }, null, 2));
+    }
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamReply(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { teamHub } = getTeamInstances(teamName);
+
+    teamHub.submitReply(args.from, args.message_id, args.answer);
+
+    return textResult(JSON.stringify({
+      status: 'replied',
+      message_id: args.message_id,
+      from: args.from,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamRoster(args) {
+  try {
+    const teamName = args.team || 'default';
+    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: safeRoster.length,
+      members: safeRoster.map(m => ({
+        name: m.name,
+        role: m.role,
+        status: m.status,
+        task: m.task,
+        model: m.model,
+        joinedAt: m.joinedAt,
+        lastSeen: m.lastSeen,
+      })),
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamUpdateStatus(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { teamHub } = getTeamInstances(teamName);
+
+    const updates = {};
+    if (args.status) updates.status = args.status;
+    if (args.task) updates.task = args.task;
+    if (args.role) updates.role = args.role;
+
+    teamHub.updateMember(args.name, updates);
+
+    return textResult(JSON.stringify({
+      status: 'updated',
+      name: args.name,
+      updates,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Layer 2: Artifact Handlers ────────────────────────────────────────────
+
+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
+    const result = artifactStore.publish(args.artifactId, {
+      type: args.type,
+      name: args.name,
+      data: args.data,
+      summary: args.summary,
+      tags: args.tags,
+      publisher: args.publisher,
+      derivedFrom: args.derivedFrom,
+    });
+
+    // Trigger dependency resolution and pipeline evaluation
+    await resolver.resolve({
+      type: 'artifact_published',
+      artifactId: args.artifactId,
+      artifactType: args.type,
+      version: result.version,
+      data: args.data,
+    });
+
+    // 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,
+    };
+    if (filesRegistered > 0) {
+      publishResult.filesRegistered = filesRegistered;
+    }
+
+    return textResult(JSON.stringify(publishResult, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+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);
+
+    if (!artifact) {
+      return errorResult(`Artifact ${args.artifactId} not found`);
+    }
+
+    // Track this read if a reader was specified
+    if (args.reader) {
+      artifactStore.trackRead(args.artifactId, args.reader, artifact.version);
+    }
+
+    // Build the response
+    const response = {
+      artifactId: artifact.artifactId,
+      version: artifact.version,
+      type: artifact.type,
+      name: artifact.name,
+      data: artifact.data,
+      publisher: artifact.publisher,
+      publishedAt: artifact.publishedAt,
+      summary: artifact.summary,
+      lineage: artifact.lineage,
+      team: teamName,
+      readBy: artifactStore.getReads(args.artifactId),
+    };
+
+    // Add prominent warning if reader param was not provided
+    if (!args.reader) {
+      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));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleArtifactList(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { artifactStore } = getTeamInstances(teamName);
+
+    const filters = {};
+    if (args.type) filters.type = args.type;
+    if (args.publisher) filters.publisher = args.publisher;
+    if (args.tag) filters.tag = args.tag;
+
+    const artifacts = artifactStore.list(filters);
+
+    return textResult(JSON.stringify({
+      team: teamName,
+      count: artifacts.length,
+      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);
+  }
+}
+
+function handleArtifactReaders(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { artifactStore } = getTeamInstances(teamName);
+
+    const reads = artifactStore.getReads(args.artifactId);
+    const uniqueReaders = [...new Set(reads.map(r => r.reader))];
+
+    return textResult(JSON.stringify({
+      artifactId: args.artifactId,
+      totalReads: reads.length,
+      uniqueReaders,
+      reads,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleArtifactHistory(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { artifactStore } = getTeamInstances(teamName);
+
+    const history = artifactStore.history(args.artifactId);
+
+    return textResult(JSON.stringify({
+      artifactId: args.artifactId,
+      team: teamName,
+      versions: history.length,
+      history: history.map(v => ({
+        version: v.version,
+        publishedAt: v.publishedAt,
+        publisher: v.publisher,
+        summary: v.summary,
+        derivedFrom: v.lineage?.derivedFrom || [],
+      })),
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Layer 2: Contract Handlers ────────────────────────────────────────────
+
+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
+    const contract = contractStore.create(args.contractId, {
+      title: args.title,
+      description: args.description,
+      assignee: args.assignee,
+      assigner: args.assigner,
+      inputs: args.inputs,
+      expectedOutputs: args.expectedOutputs,
+      dependencies: args.dependencies,
+      acceptanceCriteria: args.acceptanceCriteria,
+      autoComplete: args.autoComplete !== false,
+      timeoutMs: args.timeoutMs,
+      maxRetries: args.maxRetries,
+      priority: args.priority,
+    });
+
+    // Trigger dependency resolution to check if contract is immediately ready
+    await resolver.resolve({
+      type: 'contract_created',
+      contractId: args.contractId,
+    });
+
+    // If contract became ready, send inbox notification to assignee
+    const updatedContract = contractStore.get(args.contractId);
+    if (updatedContract.status === 'ready') {
+      teamHub.sendDirect(
+        'system',
+        args.assignee,
+        `Contract ready: ${args.title} (${args.contractId})`,
+        { priority: args.priority || 'normal' }
+      );
+    }
+
+    return textResult(JSON.stringify({
+      status: 'created',
+      contractId: contract.contractId,
+      initialStatus: updatedContract.status,
+      assignee: contract.assignee,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleContractStart(args) {
+  try {
+    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({
+      status: 'started',
+      contractId: contract.contractId,
+      title: contract.title,
+      inputs: contract.inputs,
+      expectedOutputs: contract.expectedOutputs,
+      acceptanceCriteria: contract.acceptanceCriteria,
+      startedAt: contract.startedAt,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+async function handleContractComplete(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { contractStore, resolver } = getTeamInstances(teamName);
+
+    // Complete the contract
+    contractStore.complete(args.contractId, {
+      summary: args.summary,
+      publishedArtifacts: args.publishedArtifacts,
+    });
+
+    // Trigger dependency resolution for cascade
+    await resolver.resolve({
+      type: 'contract_completed',
+      contractId: args.contractId,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'completed',
+      contractId: args.contractId,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+async function handleContractFail(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { contractStore, resolver } = getTeamInstances(teamName);
+
+    // Fail the contract
+    contractStore.fail(args.contractId, args.reason);
+
+    // Trigger dependency resolution
+    await resolver.resolve({
+      type: 'contract_failed',
+      contractId: args.contractId,
+      reason: args.reason,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'failed',
+      contractId: args.contractId,
+      reason: args.reason,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+async function handleContractReopen(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { contractStore, resolver } = getTeamInstances(teamName);
+
+    // Reopen the contract
+    const contract = contractStore.reopen(args.contractId, {
+      reason: args.reason,
+      newInputs: args.newInputs,
+    });
+
+    // Trigger dependency resolution
+    await resolver.resolve({
+      type: 'contract_reopened',
+      contractId: args.contractId,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'reopened',
+      contractId: contract.contractId,
+      retryCount: contract.retryCount,
+      currentStatus: contract.status,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleContractGet(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { contractStore } = getTeamInstances(teamName);
+
+    const contract = contractStore.get(args.contractId);
+
+    if (!contract) {
+      return errorResult(`Contract ${args.contractId} not found`);
+    }
+
+    return textResult(JSON.stringify({
+      contractId: contract.contractId,
+      title: contract.title,
+      status: contract.status,
+      assignee: contract.assignee,
+      assigner: contract.assigner,
+      inputs: contract.inputs,
+      expectedOutputs: contract.expectedOutputs,
+      dependencies: contract.dependencies,
+      acceptanceCriteria: contract.acceptanceCriteria,
+      retryCount: contract.retryCount,
+      maxRetries: contract.maxRetries,
+      createdAt: contract.createdAt,
+      startedAt: contract.startedAt,
+      completedAt: contract.completedAt,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleContractList(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { contractStore } = getTeamInstances(teamName);
+
+    const filters = {};
+    if (args.status) filters.status = args.status;
+    if (args.assignee) filters.assignee = args.assignee;
+    if (args.assigner) filters.assigner = args.assigner;
+
+    const contracts = contractStore.list(filters);
+
+    return textResult(JSON.stringify({
+      team: teamName,
+      count: contracts.length,
+      contracts: contracts.map(c => ({
+        contractId: c.contractId,
+        title: c.title,
+        status: c.status,
+        assignee: c.assignee,
+        assigner: c.assigner,
+        priority: c.priority,
+        retryCount: c.retryCount,
+        createdAt: c.createdAt,
+      })),
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleContractReassign(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { contractStore } = getTeamInstances(teamName);
+
+    contractStore.reassign(args.contractId, args.newAssignee);
+
+    return textResult(JSON.stringify({
+      status: 'reassigned',
+      contractId: args.contractId,
+      newAssignee: args.newAssignee,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Layer 3: Lineage Handlers ─────────────────────────────────────────────
+
+function handleArtifactLineage(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { lineageGraph } = getTeamInstances(teamName);
+
+    let result;
+    if (args.direction === 'upstream') {
+      result = lineageGraph.getUpstream(args.artifactId, args.version);
+    } else {
+      result = lineageGraph.getDownstream(args.artifactId, args.version);
+    }
+
+    return textResult(JSON.stringify({
+      artifactId: args.artifactId,
+      direction: args.direction,
+      chain: result,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleArtifactImpact(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { lineageGraph } = getTeamInstances(teamName);
+
+    const impact = lineageGraph.getImpact(args.artifactId);
+
+    return textResult(JSON.stringify({
+      artifactId: args.artifactId,
+      impactRadius: impact.impactRadius,
+      affectedArtifacts: impact.affectedArtifacts,
+      affectedContracts: impact.affectedContracts,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleArtifactStale(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { lineageGraph } = getTeamInstances(teamName);
+
+    const staleArtifacts = lineageGraph.findStale();
+
+    return textResult(JSON.stringify({
+      team: teamName,
+      count: staleArtifacts.length,
+      staleArtifacts: staleArtifacts,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamAudit(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { lineageGraph } = getTeamInstances(teamName);
+
+    const trail = lineageGraph.getAuditTrail(args.artifactId, args.version);
+
+    return textResult(JSON.stringify({
+      artifactId: args.artifactId,
+      auditTrail: trail,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Layer 3: Pipeline Handlers ────────────────────────────────────────────
+
+function handlePipelineCreate(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { pipelineEngine } = getTeamInstances(teamName);
+
+    const pipeline = pipelineEngine.create(args.pipelineId, {
+      rules: args.rules,
+      owner: args.owner,
+      enabled: args.enabled !== false,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'created',
+      pipelineId: pipeline.pipelineId,
+      rulesCount: pipeline.rules.length,
+      enabled: pipeline.enabled,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handlePipelineList(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { pipelineEngine } = getTeamInstances(teamName);
+
+    const filters = {};
+    if (args.owner) filters.owner = args.owner;
+
+    const pipelines = pipelineEngine.list(filters);
+
+    return textResult(JSON.stringify({
+      team: teamName,
+      count: pipelines.length,
+      pipelines: pipelines.map(p => ({
+        pipelineId: p.pipelineId,
+        owner: p.owner,
+        enabled: p.enabled,
+        rulesCount: p.rules.length,
+        executionCount: p.executionCount,
+        lastExecutedAt: p.lastExecutedAt,
+      })),
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handlePipelinePause(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { pipelineEngine } = getTeamInstances(teamName);
+
+    pipelineEngine.pause(args.pipelineId);
+
+    return textResult(JSON.stringify({
+      status: 'paused',
+      pipelineId: args.pipelineId,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handlePipelineResume(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { pipelineEngine } = getTeamInstances(teamName);
+
+    pipelineEngine.resume(args.pipelineId);
+
+    return textResult(JSON.stringify({
+      status: 'resumed',
+      pipelineId: args.pipelineId,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Layer 3: Snapshot Handlers ────────────────────────────────────────────
+
+function handleTeamSnapshot(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { snapshotEngine } = getTeamInstances(teamName);
+
+    const snapshot = snapshotEngine.createSnapshot(args.snapshotId, {
+      label: args.label,
+      description: args.description,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'created',
+      snapshotId: snapshot.snapshotId,
+      label: snapshot.label,
+      createdAt: snapshot.createdAt,
+      contractsCount: snapshot.contractsCount,
+      artifactsCount: snapshot.artifactsCount,
+      pipelinesCount: snapshot.pipelinesCount,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamSnapshotList(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { snapshotEngine } = getTeamInstances(teamName);
+
+    const snapshots = snapshotEngine.listSnapshots();
+
+    return textResult(JSON.stringify({
+      team: teamName,
+      count: snapshots.length,
+      snapshots: snapshots.map(s => ({
+        snapshotId: s.snapshotId,
+        label: s.label,
+        description: s.description,
+        createdAt: s.createdAt,
+        contractsCount: s.contractsCount,
+        artifactsCount: s.artifactsCount,
+      })),
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+function handleTeamRollback(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { snapshotEngine } = getTeamInstances(teamName);
+
+    const result = snapshotEngine.rollback(args.snapshotId, {
+      preserveArtifacts: args.preserveArtifacts !== false,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'rolled_back',
+      snapshotId: args.snapshotId,
+      restoredContracts: result.restoredContracts,
+      restoredPipelines: result.restoredPipelines,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+async function handleTeamReplay(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { snapshotEngine, resolver } = getTeamInstances(teamName);
+
+    // Replay from snapshot with overrides
+    const result = snapshotEngine.replay(args.snapshotId, {
+      overrides: args.overrides,
+    });
+
+    // Re-trigger dependency resolution to execute the workflow
+    await resolver.resolve({
+      type: 'replay_triggered',
+      snapshotId: args.snapshotId,
+    });
+
+    return textResult(JSON.stringify({
+      status: 'replayed',
+      snapshotId: args.snapshotId,
+      appliedOverrides: Object.keys(args.overrides || {}).length,
+      restoredContracts: result.restoredContracts,
+      team: teamName,
+    }, null, 2));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// =============================================================================
+// Phase Gate & Team Reset Handlers
+// =============================================================================
+
+function handlePhaseGate(args) {
+  try {
+    const teamName = args.team || 'default';
+    const { artifactStore, teamHub } = getTeamInstances(teamName);
+
+    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();
+    // Defensive: ensure roster is an array
+    const safeRoster = Array.isArray(roster) ? roster : [];
+    const idleCheck = {
+      check: 'workers_idle',
+      results: [],
+      passed: true,
+    };
+
+    const workersToCheck = args.expected_idle
+      ? safeRoster.filter(m => args.expected_idle.includes(m.name))
+      : safeRoster;
+
+    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);
+
+    // 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) {
+      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) + 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);
+  }
+}
+
+function handleTeamReset(args) {
+  try {
+    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(), '.clearctx', '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})`);
+        }
+      }
+    }
+
+    // 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);
+
+    // 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));
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// =============================================================================
+// 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,
+  };
+}
+
+// =============================================================================
+// MCP Protocol Handler — JSON-RPC 2.0 over stdio
+// =============================================================================
+
+/**
+ * Structured log to stderr (NEVER stdout — stdout is for MCP protocol only).
+ * Includes ISO timestamp and server version for debugging.
+ */
+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');
+}
+
+/**
+ * Send a JSON-RPC response on stdout.
+ */
+function sendResponse(id, result) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, result });
+  process.stdout.write(msg + '\n');
+}
+
+/**
+ * Send a JSON-RPC error on stdout.
+ */
+function sendError(id, code, message) {
+  const msg = JSON.stringify({
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  });
+  process.stdout.write(msg + '\n');
+}
+
+/**
+ * Handle an incoming JSON-RPC message.
+ */
+async function handleMessage(message) {
+  const { id, method, params } = message;
+
+  switch (method) {
+    // ── Initialize ────────────────────────────────────────────────────
+    case 'initialize':
+      sendResponse(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'clearctx',
+          version: LOADED_VERSION,
+        },
+      });
+      break;
+
+    // ── Initialized notification (no response needed) ─────────────────
+    case 'notifications/initialized':
+      log('Client initialized.');
+      break;
+
+    // ── List tools ────────────────────────────────────────────────────
+    case 'tools/list':
+      sendResponse(id, { tools: TOOLS });
+      break;
+
+    // ── Call a tool ───────────────────────────────────────────────────
+    case 'tools/call':
+      if (!params || !params.name) {
+        sendError(id, -32602, 'Missing tool name');
+        break;
+      }
+      try {
+        const result = await executeTool(params.name, params.arguments || {});
+        sendResponse(id, result);
+      } catch (err) {
+        sendResponse(id, errorResult(err.message));
+      }
+      break;
+
+    // ── Ping ──────────────────────────────────────────────────────────
+    case 'ping':
+      sendResponse(id, {});
+      break;
+
+    // ── Unknown method ────────────────────────────────────────────────
+    default:
+      if (id !== undefined) {
+        sendError(id, -32601, `Method not found: ${method}`);
+      }
+      // Notifications (no id) are silently ignored
+      break;
+  }
+}
+
+// =============================================================================
+// Start Server — read from stdin, write to stdout
+// =============================================================================
+
+function startServer() {
+  log('Starting MCP server...');
+
+  // Read newline-delimited JSON from stdin
+  const rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false,
+  });
+
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (e) {
+      log(`Failed to parse message: ${e.message}`);
+      // Send parse error if we can extract an id
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: 'Parse error' },
+      }) + '\n');
+      return;
+    }
+
+    // Validate JSON-RPC 2.0 format
+    if (message.jsonrpc !== '2.0') {
+      log(`Invalid JSON-RPC version: ${message.jsonrpc}`);
+      if (message.id !== undefined) {
+        sendError(message.id, -32600, 'Invalid Request: must use jsonrpc 2.0');
+      }
+      return;
+    }
+
+    await handleMessage(message);
+  });
+
+  rl.on('close', () => {
+    log('stdin closed. Shutting down...');
+    // Clean up — stop all live sessions
+    manager.stopAll();
+    process.exit(0);
+  });
+
+  // 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('unhandledRejection', (reason) => {
+    log(`Unhandled rejection: ${reason}`, 'error');
+    // Don't shutdown on unhandled rejections — log and continue
+  });
+
+  log('MCP server ready. Waiting for messages...');
+}
+
+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,
+  });
+}