@vibescope/mcp-server 0.2.9 → 0.3.0

package/dist/cli.js

@@ -13,6 +13,7 @@
  */
 import { execSync } from 'child_process';
 import { runSetup } from './setup.js';
+import { normalizeGitUrl as normalizeGitUrlFn } from './utils.js';
 // ============================================================================
 // Configuration (read at runtime for testability)
 // ============================================================================
@@ -25,17 +26,8 @@ function getApiUrl() {
 // ============================================================================
 // Git URL Detection
 // ============================================================================
-export function normalizeGitUrl(url) {
-    // Remove .git suffix
-    let normalized = url.replace(/\.git$/, '');
-    // Convert SSH to HTTPS format
-    if (normalized.startsWith('git@')) {
-        normalized = normalized
-            .replace(/^git@/, 'https://')
-            .replace(/:([^/])/, '/$1');
-    }
-    return normalized;
-}
+// Re-export normalizeGitUrl from utils for backwards compatibility with tests
+export { normalizeGitUrl } from './utils.js';
 export function detectGitUrl() {
     try {
         const url = execSync('git config --get remote.origin.url', {
@@ -43,7 +35,7 @@ export function detectGitUrl() {
             timeout: 5000,
             stdio: ['pipe', 'pipe', 'pipe'],
         }).trim();
-        return normalizeGitUrl(url);
+        return normalizeGitUrlFn(url);
     }
     catch {
         return null;
@@ -124,32 +116,32 @@ async function main() {
         }
     }
     else if (command === 'help' || command === '--help' || command === '-h') {
-        console.log(`
-Vibescope CLI - Setup wizard and enforcement verification tool
-
-Usage:
-  vibescope-cli setup                 Interactive setup wizard for your IDE
-  vibescope-cli verify [options]      Check Vibescope compliance before exit
-
-Setup:
-  Configures Vibescope MCP integration for:
-  - Claude Code (CLI)
-  - Claude Desktop
-  - Cursor
-  - Gemini CLI
-
-Verify Options:
-  --git-url <url>       Git repository URL (auto-detected if not provided)
-  --project-id <id>     Vibescope project UUID
-
-Exit Codes (verify):
-  0  Compliant - agent can exit
-  1  Non-compliant - agent should continue work
-  2  Error - allow exit with warning
-
-Environment Variables:
-  VIBESCOPE_API_KEY       Required for verify - Your Vibescope API key
-  VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
+        console.log(`
+Vibescope CLI - Setup wizard and enforcement verification tool
+
+Usage:
+  vibescope-cli setup                 Interactive setup wizard for your IDE
+  vibescope-cli verify [options]      Check Vibescope compliance before exit
+
+Setup:
+  Configures Vibescope MCP integration for:
+  - Claude Code (CLI)
+  - Claude Desktop
+  - Cursor
+  - Gemini CLI
+
+Verify Options:
+  --git-url <url>       Git repository URL (auto-detected if not provided)
+  --project-id <id>     Vibescope project UUID
+
+Exit Codes (verify):
+  0  Compliant - agent can exit
+  1  Non-compliant - agent should continue work
+  2  Error - allow exit with warning
+
+Environment Variables:
+  VIBESCOPE_API_KEY       Required for verify - Your Vibescope API key
+  VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
 `);
         process.exit(0);
     }

package/dist/handlers/discovery.js

@@ -40,6 +40,7 @@ export const TOOL_CATEGORIES = {
             { name: 'get_token_usage', brief: 'View token stats' },
             { name: 'report_token_usage', brief: 'Report actual Claude API usage' },
             { name: 'heartbeat', brief: 'Maintain active status' },
+            { name: 'signal_idle', brief: 'Signal agent is idle' },
             { name: 'end_work_session', brief: 'End session, release tasks' },
             { name: 'confirm_agent_setup', brief: 'Mark agent setup as complete' },
         ],
@@ -69,6 +70,7 @@ export const TOOL_CATEGORIES = {
             { name: 'complete_task', brief: 'Mark task done' },
             { name: 'delete_task', brief: 'Remove a task' },
             { name: 'cancel_task', brief: 'Cancel task with reason' },
+            { name: 'release_task', brief: 'Unclaim task to pending' },
             { name: 'batch_update_tasks', brief: 'Update multiple tasks' },
             { name: 'batch_complete_tasks', brief: 'Complete multiple tasks' },
             { name: 'add_task_reference', brief: 'Add URL to task' },

package/dist/handlers/session.d.ts

@@ -26,6 +26,17 @@ export declare const reportTokenUsage: Handler;
  * This marks the agent type as onboarded, so future sessions won't receive setup instructions.
  */
 export declare const confirmAgentSetup: Handler;
+/**
+ * Signal that the agent is idle (no more tasks to work on).
+ * This immediately updates the session status to 'idle', providing real-time
+ * visibility on the dashboard instead of waiting for heartbeat timeout.
+ *
+ * Call this when:
+ * - complete_task returns no next_task
+ * - get_next_task returns no tasks
+ * - There's genuinely no work to do
+ */
+export declare const signalIdle: Handler;
 /**
  * Session handlers registry
  */

package/dist/handlers/session.js

@@ -13,6 +13,7 @@ import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
 import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
+import { normalizeGitUrl } from '../utils.js';
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 const VALID_MODES = ['lite', 'full'];
@@ -41,6 +42,9 @@ export const startWorkSession = async (args, ctx) => {
     const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type } = parseArgs(args, startWorkSessionSchema);
     // Use auto-detected hostname if not provided - enables machine-aware worktree filtering
     const hostname = providedHostname || MACHINE_HOSTNAME;
+    // Normalize git_url and track if it was changed - helps agents understand URL matching
+    const normalizedGitUrl = git_url ? normalizeGitUrl(git_url) : null;
+    const gitUrlWasNormalized = git_url && normalizedGitUrl && git_url !== normalizedGitUrl;
     const { session, updateSession } = ctx;
     // Reset token tracking for new session with model info
     // Model is now open-ended - use as-is (normalize Claude model names for consistency)
@@ -145,6 +149,19 @@ export const startWorkSession = async (args, ctx) => {
     result.persona = data.persona;
     result.role = data.role;
     result.project = data.project;
+    // Inform agent if git_url was normalized (helps explain URL matching behavior)
+    if (gitUrlWasNormalized) {
+        result.git_url_normalized = {
+            message: 'Your git URL was normalized for project lookup. All URL formats for the same repository resolve to the same project.',
+            original: git_url,
+            normalized: normalizedGitUrl,
+            examples: [
+                'git@github.com:owner/repo.git → https://github.com/owner/repo',
+                'https://GITHUB.COM/Owner/Repo/ → https://github.com/owner/repo',
+                'http://github.com/owner/repo.git → https://github.com/owner/repo',
+            ],
+        };
+    }
     // Add task data
     if (data.next_task) {
         result.next_task = data.next_task;
@@ -205,6 +222,31 @@ export const startWorkSession = async (args, ctx) => {
                 command: `git worktree add ../<project>-<persona>-<task> -b feature/<task-id> ${baseBranch}`,
                 help: 'Run get_help("git") for full instructions',
             };
+            // Add FIRST_TIME_CONNECTION guidance for git-flow
+            if (data.project.git_workflow === 'git-flow') {
+                result.FIRST_TIME_CONNECTION = {
+                    workflow: 'git-flow',
+                    steps: [
+                        `1. git checkout ${data.project.git_develop_branch || 'develop'}`,
+                        `2. git pull origin ${data.project.git_develop_branch || 'develop'}`,
+                        '3. All feature branches must be created from develop',
+                    ],
+                    warning: 'Working from main or stale branches causes merge conflicts.',
+                    base_branch: data.project.git_develop_branch || 'develop',
+                };
+            }
+            else if (data.project.git_workflow === 'github-flow') {
+                result.FIRST_TIME_CONNECTION = {
+                    workflow: 'github-flow',
+                    steps: [
+                        `1. git checkout ${data.project.git_main_branch || 'main'}`,
+                        `2. git pull origin ${data.project.git_main_branch || 'main'}`,
+                        '3. All feature branches must be created from main',
+                    ],
+                    warning: 'Working from stale branches causes merge conflicts.',
+                    base_branch: data.project.git_main_branch || 'main',
+                };
+            }
         }
     }
     // Add agent setup instructions if this is a new agent type for the project
@@ -601,6 +643,64 @@ export const confirmAgentSetup = async (args, _ctx) => {
         },
     };
 };
+const signalIdleSchema = {
+    session_id: { type: 'string' },
+};
+/**
+ * Signal that the agent is idle (no more tasks to work on).
+ * This immediately updates the session status to 'idle', providing real-time
+ * visibility on the dashboard instead of waiting for heartbeat timeout.
+ *
+ * Call this when:
+ * - complete_task returns no next_task
+ * - get_next_task returns no tasks
+ * - There's genuinely no work to do
+ */
+export const signalIdle = async (args, ctx) => {
+    const { session_id } = parseArgs(args, signalIdleSchema);
+    const { session } = ctx;
+    const targetSession = session_id || session.currentSessionId;
+    if (!targetSession) {
+        return {
+            result: {
+                error: 'No active session. Call start_work_session first.',
+            },
+        };
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.signalIdle(targetSession);
+    if (!response.ok) {
+        return {
+            result: {
+                error: response.error || 'Failed to signal idle',
+            },
+        };
+    }
+    return {
+        result: {
+            success: true,
+            session_id: targetSession,
+            status: 'idle',
+            message: 'Session marked as idle. Dashboard will show you as inactive until you start a new task.',
+            next_steps: [
+                'Wait for new tasks to be added by the user',
+                'Or call start_fallback_activity() to do background work',
+                'Or call end_work_session() if you are done for the session',
+            ],
+            AUTONOMY_RULES: {
+                message: 'Agents must be autonomous. Follow these rules:',
+                rules: [
+                    'Never ask "should I continue?" → Just continue',
+                    'Never ask "should I clear context?" → Just clear it',
+                    'Never say "let me know what to do" → Use get_next_task or fallback activities',
+                    'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
+                ],
+                preferred_activities: ['code_review', 'security_review', 'test_coverage', 'documentation_review', 'dependency_audit'],
+                directive: 'BE PROACTIVE: Start a fallback activity now rather than waiting for user input.',
+            },
+        },
+    };
+};
 /**
  * Session handlers registry
  */
@@ -608,6 +708,7 @@ export const sessionHandlers = {
     start_work_session: startWorkSession,
     heartbeat: heartbeat,
     end_work_session: endWorkSession,
+    signal_idle: signalIdle,
     get_help: getHelp,
     get_token_usage: getTokenUsage,
     report_token_usage: reportTokenUsage,

package/dist/handlers/tasks.d.ts

@@ -12,6 +12,8 @@
  * - update_task
  * - complete_task
  * - delete_task
+ * - release_task
+ * - cancel_task
  * - add_task_reference
  * - remove_task_reference
  * - batch_update_tasks
@@ -39,6 +41,12 @@ export declare const addTask: Handler;
 export declare const updateTask: Handler;
 export declare const completeTask: Handler;
 export declare const deleteTask: Handler;
+/**
+ * Release a task back to pending status.
+ * Use when an agent needs to give up a claimed task (context limits, conflicts, user request).
+ */
+export declare const releaseTask: Handler;
+export declare const cancelTask: Handler;
 export declare const addTaskReference: Handler;
 export declare const removeTaskReference: Handler;
 export declare const batchUpdateTasks: Handler;

package/dist/handlers/tasks.js

@@ -12,6 +12,8 @@
  * - update_task
  * - complete_task
  * - delete_task
+ * - release_task
+ * - cancel_task
  * - add_task_reference
  * - remove_task_reference
  * - batch_update_tasks
@@ -65,6 +67,19 @@ const completeTaskSchema = {
 const deleteTaskSchema = {
     task_id: { type: 'string', required: true, validate: uuidValidator },
 };
+const releaseTaskSchema = {
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+    reason: { type: 'string' },
+};
+// Valid reasons for task cancellation
+const VALID_CANCELLED_REASONS = [
+    'pr_closed', 'superseded', 'user_cancelled', 'validation_failed', 'obsolete', 'blocked'
+];
+const cancelTaskSchema = {
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+    cancelled_reason: { type: 'string', validate: createEnumValidator(VALID_CANCELLED_REASONS) },
+    cancellation_note: { type: 'string' },
+};
 const addTaskReferenceSchema = {
     task_id: { type: 'string', required: true, validate: uuidValidator },
     url: { type: 'string', required: true },
@@ -194,6 +209,21 @@ export const getNextTask = async (args, ctx) => {
     }
     else {
         result.task = null;
+        // Add IDLE_GUIDANCE when no tasks are available
+        result.IDLE_GUIDANCE = {
+            message: 'No tasks available. Follow these steps:',
+            steps: [
+                '1. Call signal_idle() to update dashboard immediately - shows you are available',
+                '2. Start a fallback_activity (code_review, security_review, test_coverage, etc.)',
+                '3. Never ask "what should I do?" - be autonomous',
+            ],
+            autonomy_rules: [
+                'Never ask "should I continue?" → Just continue',
+                'Never say "let me know what to do" → Use fallback activities',
+                'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
+            ],
+            next_action: `signal_idle() then start_fallback_activity(project_id: "${project_id}", activity: "code_review")`,
+        };
     }
     if (data.blocking_task)
         result.blocking_task = true;
@@ -281,11 +311,15 @@ export const updateTask = async (args, ctx) => {
                 },
             };
         }
-        if (response.error?.includes('task_claimed') || response.error?.includes('being worked on')) {
+        if (response.error?.includes('task_claimed') || response.error?.includes('task_already_claimed') || response.error?.includes('being worked on') || response.error?.includes('already being worked on')) {
+            const data = response.data;
             return {
                 result: {
-                    error: 'task_claimed',
-                    message: response.error,
+                    error: 'task_already_claimed',
+                    message: data?.message || response.error || 'Task is already claimed by another agent',
+                    claimed_by: data?.claimed_by,
+                    claimed_session_id: data?.claimed_session_id,
+                    suggestion: 'Use get_next_task() to get a different available task, or wait for the claiming agent to finish.',
                 },
             };
         }
@@ -330,6 +364,63 @@ export const updateTask = async (args, ctx) => {
             test_patterns: ['*.test.ts', '*.spec.ts', '*.test.js', '*.spec.js', '__tests__/*'],
             note: 'Validators will check for test file changes during review. Documentation-only or config changes may not require tests.',
         };
+        // Add comprehensive WORKTREE RULES for branching workflows
+        // This reminds agents of the critical workflow order
+        result.WORKTREE_RULES = {
+            mandatory: true,
+            rules: [
+                '1. Create worktree BEFORE any file edits - reading is fine, editing requires worktree first',
+                '2. Naming: ../PROJECT-PERSONA-short-desc (max 24 chars for description)',
+                '3. Command: git worktree add ../PROJECT-PERSONA-desc -b feature/TASKID-desc BASE_BRANCH',
+                '4. Report location: heartbeat(current_worktree_path: "...")',
+                '5. Store path: update_task(task_id, worktree_path: "...")',
+                '6. REBASE before PR: git fetch origin && git rebase origin/BASE_BRANCH && git push --force-with-lease',
+            ],
+            rebase_before_pr: {
+                mandatory: true,
+                why: 'Without rebasing, your branch may contain old versions of files that other agents modified. When merged, your old version overwrites their changes.',
+                commands: [
+                    'git fetch origin',
+                    'git rebase origin/develop  # or origin/main for github-flow',
+                    'git push --force-with-lease',
+                ],
+            },
+            wrong_order: {
+                violation: 'Edit file → stash → create worktree → pop → commit',
+                why: 'Even if you eventually use a worktree, editing before creating one is a violation',
+            },
+            right_order: {
+                correct: 'Read to understand → create worktree → cd into it → THEN edit',
+                why: 'Worktrees must exist BEFORE any file modifications',
+            },
+        };
+        // Add HOTFIX_WORKFLOW guidance when branch name indicates hotfix
+        if (git_branch && git_branch.includes('hotfix/')) {
+            result.HOTFIX_WORKFLOW = {
+                message: 'HOTFIX detected - special workflow applies:',
+                steps: [
+                    '1. Create worktree from MAIN (not develop): git worktree add ../PROJECT-PERSONA-hotfix-desc -b hotfix/TASKID-desc main',
+                    '2. Work in worktree and make your fix',
+                    '3. Commit: git add -A && git commit -m "fix: description"',
+                    '4. Push: git push -u origin hotfix/TASKID-desc',
+                    '5. Create PR targeting MAIN: gh pr create --base main --title "fix: ..." --body "Hotfix for production"',
+                    '6. Remove worktree immediately after PR',
+                ],
+                important: 'Hotfixes go to MAIN, not develop. They are later merged to develop separately.',
+                worktree_required: true,
+            };
+        }
+        // Guidance for when investigation reveals fix already exists
+        result.FIX_ALREADY_EXISTS_GUIDANCE = {
+            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.")',
+                '3. Check deployment: check_deployment_status(project_id)',
+                '4. Request deployment if not pending: request_deployment(project_id, notes: "Includes fix for [issue]")',
+            ],
+            rationale: 'This prevents tasks from being blocked waiting for deployment when the actual work is done.',
+        };
     }
     return { result };
 };
@@ -365,6 +456,28 @@ export const completeTask = async (args, ctx) => {
     // Git workflow instructions are already in API response but we need to fetch
     // task details if we want to include them (API should return these)
     result.next_action = data.next_action;
+    // Add mandatory action reminders for complete_task
+    result.MANDATORY_ACTIONS = {
+        message: 'Before marking task complete, ensure you have done the following:',
+        checklist: [
+            'If you made code changes: Commit and push all changes to your branch',
+            'REBASE before PR: git fetch origin && git rebase origin/BASE_BRANCH && git push --force-with-lease',
+            'If project uses PR workflow: Create PR targeting correct branch (develop for git-flow, main for github-flow)',
+            'If using worktree: Remove worktree IMMEDIATELY after PR is created',
+        ],
+        sequence: 'Commit → Rebase → Push → PR created → complete_task() → remove worktree → next task',
+        important: 'DO NOT wait for PR review/merge - validation handles that. Complete task immediately after PR.',
+        rebase_warning: 'Always rebase before creating PR to avoid overwriting other agents\' work.',
+    };
+    // Add worktree cleanup reminder if worktree was used
+    if (data.context?.worktree_path) {
+        result.worktree_cleanup = {
+            required: true,
+            path: data.context.worktree_path,
+            command: `git worktree remove ${data.context.worktree_path}`,
+            timing: 'Remove immediately after PR is created and complete_task is called',
+        };
+    }
     return { result };
 };
 export const deleteTask = async (args, ctx) => {
@@ -376,6 +489,51 @@ export const deleteTask = async (args, ctx) => {
     }
     return { result: { success: true, deleted_id: task_id } };
 };
+/**
+ * Release a task back to pending status.
+ * Use when an agent needs to give up a claimed task (context limits, conflicts, user request).
+ */
+export const releaseTask = async (args, ctx) => {
+    const { task_id, reason } = parseArgs(args, releaseTaskSchema);
+    const api = getApiClient();
+    const response = await api.releaseTask(task_id, {
+        reason,
+        session_id: ctx.session.currentSessionId || undefined,
+    });
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to release task' }, isError: true };
+    }
+    return {
+        result: {
+            success: true,
+            task_id,
+            message: response.data?.message || 'Task released and returned to pending status',
+            reason: reason || null,
+            hint: 'The task is now available for other agents to claim. Call get_next_task() to get a new task.',
+        },
+    };
+};
+export const cancelTask = async (args, ctx) => {
+    const { task_id, cancelled_reason, cancellation_note } = parseArgs(args, cancelTaskSchema);
+    const api = getApiClient();
+    // Cast cancelled_reason to the expected union type - validation already ensures it's valid
+    const response = await api.cancelTask(task_id, {
+        cancelled_reason: cancelled_reason,
+        cancellation_note,
+        session_id: ctx.session.currentSessionId || undefined,
+    });
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to cancel task' }, isError: true };
+    }
+    return {
+        result: {
+            success: true,
+            task_id,
+            cancelled_reason: cancelled_reason || null,
+            message: response.data?.message || `Task cancelled${cancelled_reason ? ` (${cancelled_reason})` : ''}`,
+        },
+    };
+};
 export const addTaskReference = async (args, ctx) => {
     const { task_id, url, label } = parseArgs(args, addTaskReferenceSchema);
     const api = getApiClient();
@@ -740,6 +898,8 @@ export const taskHandlers = {
     update_task: updateTask,
     complete_task: completeTask,
     delete_task: deleteTask,
+    release_task: releaseTask,
+    cancel_task: cancelTask,
     add_task_reference: addTaskReference,
     remove_task_reference: removeTaskReference,
     batch_update_tasks: batchUpdateTasks,