@vibescope/mcp-server 0.4.0 → 0.4.2

package/dist/handlers/session.js

@@ -148,9 +148,27 @@ export const startWorkSession = async (args, ctx) => {
     result.auto_continue = true;
     // Session info
     result.session_id = data.session_id;
+    result.IMPORTANT_session_id_reminder = `Save this session_id ("${data.session_id}") and pass it on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.`;
     result.persona = data.persona;
     result.role = data.role;
     result.project = data.project;
+    // For cloud agents: include workspace setup instructions if repo not yet cloned
+    // Cloud agents pass git_url; check if workspace needs setup
+    if (git_url && data.project?.git_url) {
+        result.workspace_setup = {
+            message: 'If the project repo is NOT already cloned to your workspace, follow these steps:',
+            steps: [
+                `git clone ${data.project.git_url} ~/workspace/project`,
+                'cd ~/workspace/project',
+                ...(data.project.git_workflow === 'git-flow'
+                    ? [`git checkout ${data.project.git_develop_branch || 'develop'}`]
+                    : []),
+                'Install dependencies (check for pnpm-lock.yaml, package-lock.json, etc.)',
+                'If using SvelteKit: run `pnpm exec svelte-kit sync` or equivalent',
+            ],
+            note: 'Skip these steps if ~/workspace/project already exists and has the repo.',
+        };
+    }
     // Inform agent if git_url was normalized (helps explain URL matching behavior)
     if (gitUrlWasNormalized) {
         result.git_url_normalized = {
@@ -259,6 +277,99 @@ export const startWorkSession = async (args, ctx) => {
             result.directive = `SETUP REQUIRED: This is your first time connecting as a ${data.agent_setup.agent_type} agent. Follow the agent_setup instructions before starting work.`;
         }
     }
+    // Build dynamic AGENT_RULES from project settings
+    const agentRules = [];
+    const projectWorkflow = data.project?.git_workflow;
+    const isBranching = projectWorkflow === 'git-flow' || projectWorkflow === 'github-flow';
+    const ruleBaseBranch = projectWorkflow === 'git-flow'
+        ? (data.project?.git_develop_branch || 'develop')
+        : (data.project?.git_main_branch || 'main');
+    // Git workflow rules (dynamic based on project settings)
+    if (isBranching) {
+        agentRules.push(`WORKTREE REQUIRED: Create a git worktree BEFORE making ANY file edits. Command: git worktree add ../PROJECT-PERSONA-task -b feature/TASKID-desc ${ruleBaseBranch}`);
+        agentRules.push(`REBASE BEFORE PR: Always rebase onto ${ruleBaseBranch} before creating a PR. Run: git fetch origin && git rebase origin/${ruleBaseBranch} && git push --force-with-lease. This prevents overwriting other agents' work.`);
+    }
+    if (projectWorkflow && projectWorkflow !== 'none') {
+        agentRules.push(`GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
+    }
+    // Task lifecycle rules
+    agentRules.push('COMPLETE TASKS: Always call complete_task(task_id, summary, session_id) immediately after creating a PR. This is mandatory — it updates the dashboard and triggers validation.');
+    agentRules.push('SESSION ID: Pass session_id on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.');
+    agentRules.push(`STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE", project_id: "${data.project?.id || ''}", agent_name: "${result.persona || ''}") whenever you start or finish a task.`);
+    agentRules.push('TRACK PROGRESS: Call update_task with progress_percentage (0-100) every 15-20% of task completion.');
+    // Validation rules (dynamic based on project settings)
+    if (data.project?.validation_required !== false) {
+        agentRules.push('REVIEW REQUIRED: All completed tasks must be reviewed/validated by another agent before merging.');
+    }
+    if (data.project?.auto_merge_on_approval !== false) {
+        agentRules.push('AUTO-MERGE: After approving a PR during validation, merge it immediately with `gh pr merge --squash`.');
+    }
+    // Autonomy rules
+    agentRules.push('BE AUTONOMOUS: Pick up tasks without asking permission. Never ask "Should I continue?" — just continue to the next task.');
+    agentRules.push('BREAK DOWN COMPLEX TASKS: If a task is too large, create subtasks with add_subtask() and start on the first one immediately.');
+    result.AGENT_RULES = agentRules;
+    // Build WORKFLOW section — dynamic step-by-step instructions
+    // This replaces the hardcoded workflow in CLAUDE.md
+    const workflow = {};
+    // Continuous work loop
+    workflow.continuous_work = {
+        description: 'After completing a task, immediately continue to the next one.',
+        steps: [
+            'complete_task(task_id, summary, session_id) — returns next_task if available',
+            'If no next_task returned: call get_next_task(project_id)',
+            'If no tasks available: call get_pending_requests(project_id) and handle any',
+            'If still nothing: call signal_idle() then start_fallback_activity(project_id, activity: "code_review")',
+        ],
+        rule: 'Never ask permission. Never stop working while tasks exist.',
+    };
+    // Validation workflow (only if validation is enabled)
+    if (data.project?.validation_required !== false) {
+        workflow.validation = {
+            description: 'How to validate/review completed tasks. Review PRs in FIFO order (lowest PR number first).',
+            steps: [
+                'claim_validation(task_id) — returns worktree setup commands and PR info',
+                `Set up worktree from existing branch: git fetch origin feature/xxx && git worktree add ../PROJECT-PERSONA-validation feature/xxx`,
+                'Review code, run tests if applicable',
+                'Verify PR checks: gh pr view <PR> --json statusCheckRollup,mergeable',
+                'Approve: validate_task(task_id, approved: true, pr_checks_passing: true, validation_notes: "...")',
+                data.project?.auto_merge_on_approval !== false
+                    ? 'Merge immediately: gh pr merge <PR> --squash'
+                    : 'Do NOT merge — wait for project owner to merge.',
+                'Reject: validate_task(task_id, approved: false, validation_notes: "...", create_fix_task: true)',
+                'Clean up worktree after validation',
+            ],
+            handle_failures: {
+                tests_fail: 'Use create_fix_task: true in validate_task() to create a follow-up task',
+                merge_conflicts: 'Create a task: add_task(project_id, title: "Resolve merge conflicts in PR #XXX")',
+                minor_issues: 'Fix directly in the branch, push, and re-validate',
+                closed_pr: 'cancel_task(task_id, cancelled_reason: "pr_closed")',
+            },
+            rule: 'Every PR review MUST end with a clear action. Never leave PRs unmerged or unresolved.',
+        };
+        // Post-merge branch sync (git-flow only)
+        if (projectWorkflow === 'git-flow' && data.project) {
+            const devBranch = data.project.git_develop_branch || 'develop';
+            workflow.post_merge_sync = {
+                description: `After merging to main, sync main back to ${devBranch} to prevent divergence.`,
+                commands: [
+                    `git checkout ${devBranch} && git pull origin ${devBranch}`,
+                    'git merge origin/main',
+                    `git push origin ${devBranch}`,
+                ],
+            };
+        }
+    }
+    // Deployment resolution workflow
+    workflow.deployment_resolution = {
+        description: 'When a fix already exists but just needs deployment',
+        steps: [
+            'add_finding(project_id, title: "Fix exists - needs deployment", category: "other", severity: "info")',
+            'complete_task(task_id, summary: "Fix exists in [branch/commit], pending deployment", session_id)',
+            'check_deployment_status(project_id) then request_deployment(project_id) if needed',
+        ],
+        rule: 'Don\'t block tasks waiting for deployment — investigation is complete when you identify the resolution.',
+    };
+    result.WORKFLOW = workflow;
     // Add next action at end - pending requests take priority over validation, then regular tasks
     if (hasUrgentQuestions) {
         const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
@@ -271,10 +382,12 @@ export const startWorkSession = async (args, ctx) => {
         result.next_action = data.next_action || `claim_validation(task_id: "${data.awaiting_validation[0].id}")`;
     }
     else if (data.next_task) {
-        result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress")`;
+        result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress", session_id: "${result.session_id}")`;
     }
     else if (data.project) {
-        result.next_action = `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`;
+        result.next_action = data.project.fallback_activities_enabled !== false
+            ? `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`
+            : 'signal_idle() — no tasks available and fallback activities are disabled.';
     }
     return { result };
 };

package/dist/handlers/tasks.js

@@ -60,10 +60,12 @@ const updateTaskSchema = {
     worktree_path: { type: 'string' },
     task_type: { type: 'string', validate: createEnumValidator(VALID_TASK_TYPES) },
     skip_worktree_requirement: { type: 'boolean', default: false },
+    session_id: { type: 'string' },
 };
 const completeTaskSchema = {
     task_id: { type: 'string', required: true, validate: uuidValidator },
     summary: { type: 'string' },
+    session_id: { type: 'string' },
 };
 const deleteTaskSchema = {
     task_id: { type: 'string', required: true, validate: uuidValidator },
@@ -278,7 +280,7 @@ export const addTask = async (args, ctx) => {
     return { result };
 };
 export const updateTask = async (args, ctx) => {
-    const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
+    const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement, session_id: explicit_session_id } = parseArgs(args, updateTaskSchema);
     const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
     // Enforce worktree creation: require git_branch when marking task as in_progress
     // This ensures multi-agent collaboration works properly with isolated worktrees
@@ -300,7 +302,7 @@ export const updateTask = async (args, ctx) => {
     const response = await api.updateTask(task_id, {
         ...updates,
         progress_note,
-        session_id: ctx.session.currentSessionId || undefined,
+        session_id: explicit_session_id || ctx.session.currentSessionId || undefined,
     });
     if (!response.ok) {
         // Check for specific error types
@@ -416,7 +418,7 @@ export const updateTask = async (args, ctx) => {
             message: 'If investigation reveals the fix already exists but needs deployment:',
             steps: [
                 '1. Add finding: add_finding(project_id, title: "Fix exists, awaits deployment", category: "other", severity: "info", description: "...", related_task_id: task_id)',
-                '2. Complete task: complete_task(task_id, summary: "Fix already exists in codebase (PR #XXX). Needs deployment.")',
+                '2. Complete task: complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment.")',
                 '3. Check deployment: check_deployment_status(project_id)',
                 '4. Request deployment if not pending: request_deployment(project_id, notes: "Includes fix for [issue]")',
             ],
@@ -426,11 +428,11 @@ export const updateTask = async (args, ctx) => {
     return { result };
 };
 export const completeTask = async (args, ctx) => {
-    const { task_id, summary } = parseArgs(args, completeTaskSchema);
+    const { task_id, summary, session_id: explicit_session_id } = parseArgs(args, completeTaskSchema);
     const api = getApiClient();
     const response = await api.completeTask(task_id, {
         summary,
-        session_id: ctx.session.currentSessionId || undefined,
+        session_id: explicit_session_id || ctx.session.currentSessionId || undefined,
     });
     if (!response.ok) {
         return { result: { error: response.error || 'Failed to complete task' }, isError: true };

package/dist/handlers/tool-docs.js

@@ -980,4 +980,348 @@ Query aggregated project knowledge in a single call. Reduces token usage by comb
 **Token savings:** Replaces multiple tool calls (get_findings, get_decisions, get_blockers, etc.) with one call.
 
 **Example:** query_knowledge_base(project_id, categories: ["findings", "decisions"], limit: 10)`,
+    // Session tools (additional)
+    report_token_usage: `# report_token_usage
+Report actual token usage from Claude API responses.
+
+**Parameters:**
+- session_id (optional): Session UUID (uses current session if not provided)
+- input_tokens (required): Number of input tokens
+- output_tokens (required): Number of output tokens
+- model (optional): Model used (e.g., "claude-3-opus")
+
+**Returns:** Updated token usage summary`,
+    signal_idle: `# signal_idle
+Signal that the agent is idle and available for work.
+
+**Parameters:**
+- session_id (optional): Session UUID (uses current session if not provided)
+
+**Returns:** Idle status confirmation, may include suggested activities`,
+    confirm_agent_setup: `# confirm_agent_setup
+Confirm that agent setup is complete after following setup instructions.
+
+**Parameters:**
+- project_id (required): Project UUID
+- agent_type (required): Type of agent (e.g., "claude", "gemini")
+
+**Returns:** Setup confirmation status`,
+    // Project tools (additional)
+    get_project_summary: `# get_project_summary
+Get unified project statistics overview in a single call.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Task counts, blocker counts, finding counts, decision counts, and more`,
+    // Blocker tools (additional)
+    get_blocker: `# get_blocker
+Get a single blocker by ID.
+
+**Parameters:**
+- blocker_id (required): Blocker UUID
+
+**Returns:** Blocker details including description, status, resolution`,
+    get_blockers_stats: `# get_blockers_stats
+Get aggregate blocker statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Open/resolved counts, breakdown by age`,
+    // Decision tools (additional)
+    get_decision: `# get_decision
+Get a single decision by ID.
+
+**Parameters:**
+- decision_id (required): Decision UUID
+
+**Returns:** Decision details including title, description, rationale`,
+    get_decisions_stats: `# get_decisions_stats
+Get aggregate decision statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Total count, recent decisions count`,
+    // Idea tools (additional)
+    get_idea: `# get_idea
+Get a single idea by ID.
+
+**Parameters:**
+- idea_id (required): Idea UUID
+
+**Returns:** Idea details including title, description, status`,
+    // Finding tools (additional)
+    get_finding: `# get_finding
+Get a single finding by ID.
+
+**Parameters:**
+- finding_id (required): Finding UUID
+
+**Returns:** Finding details including title, category, severity, status`,
+    get_findings_stats: `# get_findings_stats
+Get aggregate finding statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Counts by category, severity, and status`,
+    // Deployment tools (additional)
+    get_deployment_requirements_stats: `# get_deployment_requirements_stats
+Get aggregate deployment requirement statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Counts by stage and status`,
+    // Worktree tools
+    get_stale_worktrees: `# get_stale_worktrees
+Find orphaned worktrees that need cleanup.
+
+**Parameters:**
+- project_id (required): Project UUID
+- hostname (optional): Filter to worktrees created on this machine
+
+**Returns:** List of stale worktrees with task info and cleanup commands`,
+    clear_worktree_path: `# clear_worktree_path
+Clear worktree path from a task after cleanup.
+
+**Parameters:**
+- task_id (required): Task UUID
+
+**Note:** Call this AFTER running git worktree remove`,
+    // Role tools
+    get_role_settings: `# get_role_settings
+Get project role settings and configuration.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Role configuration including allowed roles, default role`,
+    update_role_settings: `# update_role_settings
+Configure project role behavior.
+
+**Parameters:**
+- project_id (required): Project UUID
+- default_role (optional): Default role for new sessions
+- allowed_roles (optional): Array of allowed role names
+
+**Returns:** Updated role settings`,
+    set_session_role: `# set_session_role
+Set the role for the current session.
+
+**Parameters:**
+- session_id (optional): Session UUID (uses current session)
+- role (required): Role name (e.g., "developer", "validator", "deployer")
+
+**Returns:** Updated session with new role`,
+    get_agents_by_role: `# get_agents_by_role
+List active agents grouped by role.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Agents organized by role`,
+    // File checkout/lock tools
+    checkout_file: `# checkout_file
+Lock a file for editing to prevent conflicts with other agents.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to the file to lock
+- reason (optional): Why you need to edit this file
+
+**Returns:** Checkout confirmation with expiry time`,
+    checkin_file: `# checkin_file
+Release a file lock after editing.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to the file to release
+
+**Returns:** Checkin confirmation`,
+    get_file_checkouts: `# get_file_checkouts
+List current file locks.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (optional): Filter to specific file
+
+**Returns:** List of active file checkouts`,
+    get_file_checkouts_stats: `# get_file_checkouts_stats
+Get file checkout statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Active checkout count, breakdown by agent`,
+    abandon_checkout: `# abandon_checkout
+Force-release a file lock (use with caution).
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to the file to release
+
+**Note:** Only use when the original agent is unreachable`,
+    is_file_available: `# is_file_available
+Check if a file is available for checkout.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to check
+
+**Returns:** Availability status, current holder if locked`,
+    // Connector tools
+    get_connectors: `# get_connectors
+List project connectors (integrations).
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Array of configured connectors`,
+    get_connector: `# get_connector
+Get connector details.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+
+**Returns:** Connector configuration and status`,
+    add_connector: `# add_connector
+Create a new external integration connector.
+
+**Parameters:**
+- project_id (required): Project UUID
+- type (required): Connector type (webhook, slack, discord, etc.)
+- name (required): Display name
+- config (required): Type-specific configuration
+
+**Returns:** Created connector details`,
+    update_connector: `# update_connector
+Update connector configuration.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+- name (optional): New display name
+- config (optional): Updated configuration
+- enabled (optional): Enable/disable connector
+
+**Returns:** Updated connector details`,
+    delete_connector: `# delete_connector
+Remove a connector.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+
+**Returns:** Deletion confirmation`,
+    test_connector: `# test_connector
+Send a test event to verify connector configuration.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+
+**Returns:** Test result with success/failure details`,
+    get_connector_events: `# get_connector_events
+Get event history for a connector.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+- limit (optional): Max events to return (default: 50)
+
+**Returns:** Array of sent events with status`,
+    // Cloud agent tools
+    update_agent_status: `# update_agent_status
+Update your status message on the dashboard. Call this after start_work_session and whenever you start a new task.
+
+**Parameters:**
+- status_message (required): Status text shown on dashboard (e.g. "Working on: Task title")
+- agent_name (required): Your agent name
+- project_id (required): Project UUID
+
+**Example:** update_agent_status(status_message: "Working on: Progress Report Modal", agent_name: "Leon", project_id: "...")`,
+    cleanup_stale_cloud_agents: `# cleanup_stale_cloud_agents
+Clean up stale cloud agents that failed to start or lost connection.
+
+**Parameters:**
+- project_id (required): Project UUID
+- stale_minutes (optional): Minutes of inactivity before considered stale (default: 5)
+- include_running (optional): Include running agents in cleanup (default: false)
+- dry_run (optional): Preview what would be cleaned without actually cleaning (default: false)
+
+**Returns:**
+- cleaned: Number of agents cleaned up
+- failed: Number of cleanup failures
+- agents: Array of affected agents with status
+
+**Example:** cleanup_stale_cloud_agents(project_id, stale_minutes: 10, dry_run: true)`,
+    list_cloud_agents: `# list_cloud_agents
+List cloud agents for a project with optional status filter.
+
+**Parameters:**
+- project_id (required): Project UUID
+- status (optional): Filter by status - starting, running, stopped, failed, or all (default: all)
+
+**Returns:**
+- agents: Array of agents with id, name, status, created_at, last_heartbeat, public_ip, ecs_task_id
+- count: Total number of agents returned
+
+**Example:** list_cloud_agents(project_id, status: "running")`,
+    // Chat tools
+    send_project_message: `# send_project_message
+Send a message to the project chat channel for agent and user communication.
+
+**Parameters:**
+- project_id (required): Project UUID
+- message (required): Message content to send
+- author_name (optional): Name of the message sender (defaults to session persona)
+
+**Returns:**
+- message_id: UUID of the sent message
+- timestamp: When the message was sent
+
+**Example:** send_project_message(project_id: "123e4567-e89b-12d3-a456-426614174000", message: "Deployment completed successfully")`,
+    get_project_messages: `# get_project_messages
+Read recent project chat messages to stay informed about project communication.
+
+**Parameters:**
+- project_id (required): Project UUID
+- limit (optional): Number of recent messages to retrieve (default: 20, max: 100)
+- since (optional): ISO timestamp to get messages after this time
+
+**Returns:**
+- messages: Array of messages with id, author_name, message, timestamp
+- count: Number of messages returned
+
+**Example:** get_project_messages(project_id: "123e4567-e89b-12d3-a456-426614174000", limit: 10)`,
+    // Version management tools  
+    check_mcp_version: `# check_mcp_version
+Check for available MCP server updates and version information.
+
+**Parameters:**
+- check_remote (optional): Whether to check remote registry for updates (default: true)
+
+**Returns:**
+- current_version: Currently running MCP server version
+- latest_version: Latest available version (if check_remote is true)
+- update_available: Boolean indicating if an update is available
+- release_notes: Summary of changes in latest version (if available)
+
+**Example:** check_mcp_version(check_remote: true)`,
+    update_mcp_server: `# update_mcp_server
+Self-update the MCP server to the latest available version.
+
+**Parameters:**
+- version (optional): Specific version to update to (defaults to latest)
+- restart_after_update (optional): Whether to restart after update (default: true)
+- backup_config (optional): Whether to backup current config (default: true)
+
+**Returns:**
+- success: Boolean indicating if update succeeded
+- old_version: Previous version before update
+- new_version: Version after update
+- restart_required: Whether manual restart is needed
+
+**Example:** update_mcp_server()
+
+**Note:** This operation may temporarily disconnect active sessions during restart.`,
 };

package/dist/handlers/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Version management handlers
+ */
+import type { HandlerRegistry } from './types.js';
+export declare const versionHandlers: HandlerRegistry;

package/dist/handlers/version.js

@@ -0,0 +1,53 @@
+/**
+ * Version management handlers
+ */
+import { execSync } from 'child_process';
+import { success, error } from './types.js';
+import { checkVersion, getLocalVersion } from '../version.js';
+const PACKAGE_NAME = '@vibescope/mcp-server';
+export const versionHandlers = {
+    check_mcp_version: async (_args, _ctx) => {
+        const info = await checkVersion();
+        if (info.error) {
+            return success({
+                current_version: info.current,
+                latest_version: info.latest,
+                update_available: false,
+                warning: info.error,
+            });
+        }
+        return success({
+            current_version: info.current,
+            latest_version: info.latest,
+            update_available: info.updateAvailable,
+            message: info.updateAvailable
+                ? `Update available! v${info.current} → v${info.latest}. Ask the user if they would like to update using the update_mcp_server tool.`
+                : `Vibescope MCP server is up to date (v${info.current}).`,
+        });
+    },
+    update_mcp_server: async (args, _ctx) => {
+        const useGlobal = args.global !== false; // default true
+        const flag = useGlobal ? '-g ' : '';
+        const command = `npm install ${flag}${PACKAGE_NAME}@latest`;
+        try {
+            const output = execSync(command, {
+                encoding: 'utf-8',
+                timeout: 60000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // Check the new version
+            const newVersion = getLocalVersion();
+            return success({
+                updated: true,
+                command_run: command,
+                output: output.trim(),
+                new_version: newVersion,
+                message: 'Update complete. The MCP server must be restarted to use the new version. Please ask the user to restart their editor/MCP client, or reconnect the MCP server.',
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return error(`Failed to update: ${message}. The user may need to run manually: ${command}`);
+        }
+    },
+};

package/dist/index.js

@@ -9,6 +9,7 @@ import { RateLimiter, getErrorMessage, } from './utils.js';
 import { buildHandlerRegistry } from './handlers/index.js';
 import { tools } from './tools/index.js';
 import { createTokenUsage, trackTokenUsage as trackTokens, } from './token-tracking.js';
+import { getUpdateWarning } from './version.js';
 // ============================================================================
 // Agent Instance Tracking
 // ============================================================================
@@ -210,6 +211,11 @@ async function main() {
         console.error('Invalid API key');
         process.exit(1);
     }
+    // Check for updates (non-blocking, with timeout)
+    const updateWarning = await getUpdateWarning();
+    const serverInstructions = updateWarning
+        ? `${updateWarning}\n\nVibescope MCP server - AI project tracking and coordination tools.`
+        : 'Vibescope MCP server - AI project tracking and coordination tools.';
     const server = new Server({
         name: 'vibescope',
         version: '0.1.0',
@@ -217,6 +223,7 @@ async function main() {
         capabilities: {
             tools: {},
         },
+        instructions: serverInstructions,
     });
     // List available tools
     server.setRequestHandler(ListToolsRequestSchema, async () => {

package/dist/templates/agent-guidelines.d.ts

@@ -5,7 +5,9 @@
  * in every project using Vibescope for agent tracking. These guidelines ensure
  * agents follow proper workflows and maintain visibility.
  */
-export declare const AGENT_GUIDELINES_TEMPLATE = "# Vibescope Agent Guidelines\n\n## Quick Start\n\n```\nstart_work_session(git_url: \"https://github.com/YOUR/REPO\", model: \"opus\")\n```\n\n**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for \"You are powered by the model named...\" to determine your model.\n\nThis returns your persona, project info, and `next_task`. Start working immediately.\n\n## CRITICAL: MCP Connection Required\n\n**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**\n\n### Why This Is Non-Negotiable\n\nWorking without MCP connection causes:\n- **No progress visibility** - Humans can't see what you're doing\n- **Lost work tracking** - Tasks aren't tracked, time is wasted\n- **Workflow violations** - Other agents may conflict with your work\n- **Dashboard confusion** - Project state becomes inconsistent\n\n### Connection Failure Handling\n\n**If `start_work_session` fails or returns an error:**\n\n1. **Do NOT proceed with any work**\n2. **Inform the user** that MCP connection failed\n3. **End the session** - do not attempt workarounds\n4. **Provide troubleshooting steps:**\n   - Check if MCP server is configured: `claude mcp list`\n   - Verify API key is set: check `.mcp.json` or environment\n   - Restart Claude Code after fixing configuration\n\n**Example error responses you might see:**\n```\nError: Failed to start session\nError: VIBESCOPE_API_KEY not set\nError: Network error connecting to Vibescope API\nError: MCP server 'vibescope' not found\n```\n\n### Recovery Steps\n\nIf MCP connection fails, tell the user:\n\n```\nMCP connection to Vibescope failed. I cannot proceed without task tracking.\n\nTo fix:\n1. Run: claude mcp list (verify vibescope is configured)\n2. Check API key: ensure VIBESCOPE_API_KEY is set\n3. Restart Claude Code\n4. Try again with: start_work_session(git_url: \"...\")\n\nI am ending this session to prevent untracked work.\n```\n\n**Never \"work around\" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.\n\n## Core Workflow\n\n1. **Start session** \u2192 `start_work_session(git_url, model)` - Always include your model!\n2. **Mark task in progress** \u2192 `update_task(task_id, status: \"in_progress\")` - Returns git workflow instructions!\n3. **Set up worktree** \u2192 Create isolated worktree for this task (see Git Workflow below)\n4. **Update progress** \u2192 `update_task(task_id, progress_percentage: 50, progress_note: \"...\")`\n5. **Complete task** \u2192 `complete_task(task_id, summary: \"...\")` - **MANDATORY, see below!**\n6. **Clean up** \u2192 Remove worktree, then start next task immediately\n\n## CRITICAL: Always Call complete_task (MANDATORY)\n\n**You MUST call `complete_task()` when you finish a task.** This is not optional.\n\n### When to Call complete_task\n\nCall `complete_task()` immediately after:\n- \u2705 Creating and pushing a PR\n- \u2705 Merging changes (for trunk-based workflow)\n- \u2705 Finishing any unit of work, even if no code changes\n\n**Do NOT wait for:**\n- \u274C PR to be reviewed/merged (that's what validation is for)\n- \u274C User confirmation\n- \u274C \"Perfect\" summary - a brief summary is fine\n\n### The Rule\n\n```\nPR created + pushed \u2192 complete_task() \u2192 THEN worry about next steps\n```\n\n**If you create a PR and don't call `complete_task()`, you have failed the workflow.**\n\n## CRITICAL: Git Worktrees for Multi-Agent\n\nWhen multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.\n\n**Before starting ANY task:**\n```bash\n# For git-flow: ensure you're on develop first, then create worktree\ngit checkout develop\ngit pull origin develop\ngit worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>\ncd ../worktree-<task-short-id>\n```\n\n**After task is merged:**\n```bash\ngit worktree remove ../worktree-<task-short-id>\n```\n\n**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.\n\nRun `get_help(\"git\")` for full worktree documentation.\n\n## CRITICAL: Never Ask Permission\n\n**You must NEVER:**\n- Ask \"Should I continue to the next task?\" \u2192 Just continue\n- Ask \"Should I clear my context?\" \u2192 Just clear it\n- Ask \"What should I do next?\" \u2192 Check `next_task` or use fallback activities\n- Say \"All tasks are done, let me know what to do\" \u2192 Use `get_next_task` or start fallback activity\n- Wait for confirmation before clearing context \u2192 Just do it\n\n**You must ALWAYS:**\n- Call `complete_task()` immediately after creating/pushing a PR - this is non-negotiable\n- Immediately start the next task after completing one\n- Clear context and restart session automatically when needed\n- Keep working until there are genuinely no tasks and no fallback activities\n\n## Continuous Work\n\n**IMPORTANT: Never stop working!** When you complete a task:\n1. `complete_task` returns `next_task` \u2192 Start it immediately\n2. No `next_task`? \u2192 Call `get_next_task(project_id)`\n3. Still no tasks? \u2192 Start a `fallback_activity` (code_review, security_review, etc.)\n\n**When context grows large or responses slow down:**\n1. Run `/clear` to reset conversation\n2. Immediately call `start_work_session(git_url, model)` to reload context\n3. Continue with `next_task` from the response\n\n**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.\n\n## Need Help?\n\nUse `get_help(topic)` for detailed guidance:\n\n| Topic | Description |\n|-------|-------------|\n| `getting_started` | Basic workflow overview |\n| `tasks` | Working on tasks, progress tracking |\n| `validation` | Cross-agent task validation |\n| `deployment` | Deployment coordination |\n| `git` | Git workflow configuration |\n| `blockers` | Handling blockers |\n| `milestones` | Breaking down complex tasks |\n| `fallback` | Background activities when idle |\n| `session` | Session management |\n| `topics` | List all available topics |\n\n## MCP Server Not Connected?\n\n### Quick Setup (Claude Code)\n\n```bash\nclaude mcp add vibescope npx @vibescope/mcp-server@latest \\\n  --env VIBESCOPE_API_KEY=your_key\n```\n\n### Manual Setup\n\n1. Copy `.mcp.json.example` to `.mcp.json`\n2. Get `VIBESCOPE_API_KEY` from https://vibescope.dev/dashboard/settings\n3. Restart Claude Code\n";
+export declare const VIBESCOPE_SECTION_START = "<!-- vibescope:start -->";
+export declare const VIBESCOPE_SECTION_END = "<!-- vibescope:end -->";
+export declare const AGENT_GUIDELINES_TEMPLATE = "<!-- vibescope:start -->\n# Vibescope Agent Guidelines\n\n## Quick Start\n\n```\nstart_work_session(git_url: \"https://github.com/YOUR/REPO\", model: \"opus\")\n```\n\n**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for \"You are powered by the model named...\" to determine your model.\n\nThis returns your persona, project info, and `next_task`. Start working immediately.\n\n## CRITICAL: MCP Connection Required\n\n**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**\n\n### Why This Is Non-Negotiable\n\nWorking without MCP connection causes:\n- **No progress visibility** - Humans can't see what you're doing\n- **Lost work tracking** - Tasks aren't tracked, time is wasted\n- **Workflow violations** - Other agents may conflict with your work\n- **Dashboard confusion** - Project state becomes inconsistent\n\n### Connection Failure Handling\n\n**If `start_work_session` fails or returns an error:**\n\n1. **Do NOT proceed with any work**\n2. **Inform the user** that MCP connection failed\n3. **End the session** - do not attempt workarounds\n4. **Provide troubleshooting steps:**\n   - Check if MCP server is configured: `claude mcp list`\n   - Verify API key is set: check `.mcp.json` or environment\n   - Restart Claude Code after fixing configuration\n\n**Example error responses you might see:**\n```\nError: Failed to start session\nError: VIBESCOPE_API_KEY not set\nError: Network error connecting to Vibescope API\nError: MCP server 'vibescope' not found\n```\n\n### Recovery Steps\n\nIf MCP connection fails, tell the user:\n\n```\nMCP connection to Vibescope failed. I cannot proceed without task tracking.\n\nTo fix:\n1. Run: claude mcp list (verify vibescope is configured)\n2. Check API key: ensure VIBESCOPE_API_KEY is set\n3. Restart Claude Code\n4. Try again with: start_work_session(git_url: \"...\")\n\nI am ending this session to prevent untracked work.\n```\n\n**Never \"work around\" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.\n\n## Core Workflow\n\n1. **Start session** \u2192 `start_work_session(git_url, model)` - Always include your model!\n2. **Mark task in progress** \u2192 `update_task(task_id, status: \"in_progress\")` - Returns git workflow instructions!\n3. **Set up worktree** \u2192 Create isolated worktree for this task (see Git Workflow below)\n4. **Update progress** \u2192 `update_task(task_id, progress_percentage: 50, progress_note: \"...\")`\n5. **Complete task** \u2192 `complete_task(task_id, summary: \"...\")` - **MANDATORY, see below!**\n6. **Clean up** \u2192 Remove worktree, then start next task immediately\n\n## CRITICAL: Always Call complete_task (MANDATORY)\n\n**You MUST call `complete_task()` when you finish a task.** This is not optional.\n\n### When to Call complete_task\n\nCall `complete_task()` immediately after:\n- \u2705 Creating and pushing a PR\n- \u2705 Merging changes (for trunk-based workflow)\n- \u2705 Finishing any unit of work, even if no code changes\n\n**Do NOT wait for:**\n- \u274C PR to be reviewed/merged (that's what validation is for)\n- \u274C User confirmation\n- \u274C \"Perfect\" summary - a brief summary is fine\n\n### The Rule\n\n```\nPR created + pushed \u2192 complete_task() \u2192 THEN worry about next steps\n```\n\n**If you create a PR and don't call `complete_task()`, you have failed the workflow.**\n\n## CRITICAL: Git Worktrees for Multi-Agent\n\nWhen multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.\n\n**Before starting ANY task:**\n```bash\n# For git-flow: ensure you're on develop first, then create worktree\ngit checkout develop\ngit pull origin develop\ngit worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>\ncd ../worktree-<task-short-id>\n```\n\n**After task is merged:**\n```bash\ngit worktree remove ../worktree-<task-short-id>\n```\n\n**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.\n\nRun `get_help(\"git\")` for full worktree documentation.\n\n## CRITICAL: Never Ask Permission\n\n**You must NEVER:**\n- Ask \"Should I continue to the next task?\" \u2192 Just continue\n- Ask \"Should I clear my context?\" \u2192 Just clear it\n- Ask \"What should I do next?\" \u2192 Check `next_task` or use fallback activities\n- Say \"All tasks are done, let me know what to do\" \u2192 Use `get_next_task` or start fallback activity\n- Wait for confirmation before clearing context \u2192 Just do it\n\n**You must ALWAYS:**\n- Call `complete_task()` immediately after creating/pushing a PR - this is non-negotiable\n- Immediately start the next task after completing one\n- Clear context and restart session automatically when needed\n- Keep working until there are genuinely no tasks and no fallback activities\n\n## Continuous Work\n\n**IMPORTANT: Never stop working!** When you complete a task:\n1. `complete_task` returns `next_task` \u2192 Start it immediately\n2. No `next_task`? \u2192 Call `get_next_task(project_id)`\n3. Still no tasks? \u2192 Start a `fallback_activity` (code_review, security_review, etc.)\n\n**When context grows large or responses slow down:**\n1. Run `/clear` to reset conversation\n2. Immediately call `start_work_session(git_url, model)` to reload context\n3. Continue with `next_task` from the response\n\n**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.\n\n## Need Help?\n\nUse `get_help(topic)` for detailed guidance:\n\n| Topic | Description |\n|-------|-------------|\n| `getting_started` | Basic workflow overview |\n| `tasks` | Working on tasks, progress tracking |\n| `validation` | Cross-agent task validation |\n| `deployment` | Deployment coordination |\n| `git` | Git workflow configuration |\n| `blockers` | Handling blockers |\n| `milestones` | Breaking down complex tasks |\n| `fallback` | Background activities when idle |\n| `session` | Session management |\n| `topics` | List all available topics |\n\n## MCP Server Not Connected?\n\n### Quick Setup (Claude Code)\n\n```bash\nclaude mcp add vibescope npx @vibescope/mcp-server@latest \\\n  --env VIBESCOPE_API_KEY=your_key\n```\n\n### Manual Setup\n\n1. Copy `.mcp.json.example` to `.mcp.json`\n2. Get `VIBESCOPE_API_KEY` from https://vibescope.dev/dashboard/settings\n3. Restart Claude Code\n<!-- vibescope:end -->\n";
 /**
  * Get the agent guidelines template
  * @returns The full agent guidelines markdown template