@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/utils.ts

@@ -1,586 +1,586 @@
-// ============================================================================
-// Utilities Module - Extracted from index.ts for testability
-// ============================================================================
-
-import { randomUUID } from 'crypto';
-
-// ============================================================================
-// Agent Persona Pool
-// Iconic sci-fi & fantasy character names for agents on the dashboard
-// ============================================================================
-
-export const AGENT_PERSONAS = [
-	// Star Wars
-	'Yoda',
-	'Leia',
-	'Han',
-	'Luke',
-	'Rey',
-	'Finn',
-	'Kylo',
-	'Mando',
-	'Grogu',
-	'Ahsoka',
-	// Lord of the Rings
-	'Frodo',
-	'Gandalf',
-	'Aragorn',
-	'Legolas',
-	'Gimli',
-	'Sam',
-	'Bilbo',
-	'Gollum',
-	// Star Trek
-	'Spock',
-	'Kirk',
-	'Picard',
-	'Data',
-	'Worf',
-	'Seven',
-	// Dune
-	'Paul',
-	'Chani',
-	'Duncan',
-	'Stilgar',
-	'Leto',
-	// The Matrix
-	'Neo',
-	'Trinity',
-	'Morpheus',
-	// Firefly
-	'Mal',
-	'River',
-	'Kaylee',
-	'Wash',
-	// Game of Thrones
-	'Arya',
-	'Tyrion',
-	'Dany',
-	'Bran',
-	// Marvel / Guardians
-	'Groot',
-	'Rocket',
-	'Gamora',
-	'Drax',
-	'Loki',
-	'Thor',
-	// Classic Sci-Fi AIs & Characters
-	'Ripley',
-	'Jarvis',
-	'Cortana',
-	'GLaDOS',
-] as const;
-
-export type AgentPersona = typeof AGENT_PERSONAS[number];
-
-// ============================================================================
-// Fallback Activities for Idle Agents
-// Suggested productive activities when no pending tasks exist
-// ============================================================================
-
-export const FALLBACK_ACTIVITIES = [
-	{
-		activity: 'feature_ideation',
-		title: 'Generate feature ideas',
-		description: 'Review the codebase and suggest improvements or new features. Use add_idea to record your findings.',
-		prompt: 'Explore the codebase, identify areas for improvement, and suggest 2-3 actionable feature ideas using add_idea.',
-	},
-	{
-		activity: 'feature_planning',
-		title: 'Plan features from ideas',
-		description: 'Take raw ideas and develop them into planned features with documentation.',
-		prompt: 'Call get_ideas to find ideas with status "raw" or "exploring". Pick one and develop it: research requirements, identify implementation steps, write a feature spec. Use update_idea to change status to "planned" and add a doc_url if you create documentation.',
-	},
-	{
-		activity: 'code_review',
-		title: 'Code standards review',
-		description: 'Check for inconsistencies, missing types, code smells, or patterns that could be improved.',
-		prompt: 'Review the codebase for code quality issues. Look for missing types, inconsistent patterns, or technical debt. Log findings with add_idea or add_task.',
-	},
-	{
-		activity: 'performance_audit',
-		title: 'Performance audit',
-		description: 'Identify potential performance bottlenecks or optimization opportunities.',
-		prompt: 'Analyze the codebase for performance issues: N+1 queries, unnecessary re-renders, expensive operations. Create tasks for fixes with add_task.',
-	},
-	{
-		activity: 'ux_review',
-		title: 'UX review',
-		description: 'Evaluate user flows and identify usability improvements.',
-		prompt: 'Review the UI components and user flows. Identify confusing interactions, missing feedback, or accessibility issues. Log improvements with add_idea.',
-	},
-	{
-		activity: 'cost_analysis',
-		title: 'Cost analysis',
-		description: 'Review infrastructure and API usage for cost optimization opportunities.',
-		prompt: 'Analyze the codebase for expensive operations: unnecessary API calls, inefficient queries, large bundle sizes. Suggest cost-saving alternatives with add_idea.',
-	},
-	{
-		activity: 'security_review',
-		title: 'Security review',
-		description: 'Check for common security issues: auth gaps, input validation, data exposure.',
-		prompt: 'Review the codebase for security concerns: authentication gaps, missing input validation, sensitive data handling. Create high-priority tasks for issues found.',
-	},
-	{
-		activity: 'test_coverage',
-		title: 'Test coverage analysis',
-		description: 'Find untested code paths and suggest test cases.',
-		prompt: 'Identify areas of the codebase with missing or weak test coverage. Create tasks for writing tests using add_task.',
-	},
-	{
-		activity: 'documentation_review',
-		title: 'Documentation review',
-		description: 'Identify missing or outdated documentation.',
-		prompt: 'Review existing docs and code comments. Identify gaps, outdated information, or confusing explanations. Log improvements with add_idea.',
-	},
-	{
-		activity: 'dependency_audit',
-		title: 'Dependency audit',
-		description: 'Review dependencies for updates, security issues, or unused packages.',
-		prompt: 'Check package.json for outdated dependencies, security vulnerabilities, or unused packages. Create tasks for updates with add_task.',
-	},
-	{
-		activity: 'validate_completed_tasks',
-		title: 'Validate completed tasks',
-		description: 'Review tasks completed by other agents to ensure quality.',
-		prompt: 'Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.',
-	},
-	{
-		activity: 'worktree_cleanup',
-		title: 'Clean up stale worktrees',
-		description: 'Find and remove git worktrees from completed or abandoned tasks.',
-		prompt: `Clean up stale git worktrees to reclaim disk space and prevent confusion:
-
-1. Call get_stale_worktrees(project_id) to find worktrees needing cleanup
-2. For each stale worktree returned:
-   a. Check if the worktree directory exists: ls -la <worktree_path>
-   b. If it exists, remove it: git worktree remove <worktree_path>
-   c. If removal fails (untracked files), use: git worktree remove --force <worktree_path>
-   d. Call clear_worktree_path(task_id) to mark it as cleaned up
-3. Run 'git worktree list' to verify cleanup
-4. Log any issues encountered with add_blocker if worktrees cannot be removed
-
-This prevents disk bloat from accumulated worktrees and keeps the workspace clean.`,
-	},
-] as const;
-
-export type FallbackActivity = typeof FALLBACK_ACTIVITIES[number];
-
-/**
- * Get a random fallback activity
- */
-export function getRandomFallbackActivity(): FallbackActivity {
-	const index = Math.floor(Math.random() * FALLBACK_ACTIVITIES.length);
-	return FALLBACK_ACTIVITIES[index];
-}
-
-/**
- * Fisher-Yates shuffle with a seed for reproducible randomness
- */
-function seededShuffle<T>(array: T[], seed: number): T[] {
-	const result = [...array];
-	let currentSeed = seed;
-
-	// Simple seeded random number generator (mulberry32)
-	const random = () => {
-		currentSeed = (currentSeed + 0x6D2B79F5) | 0;
-		let t = currentSeed;
-		t = Math.imul(t ^ (t >>> 15), t | 1);
-		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-	};
-
-	for (let i = result.length - 1; i > 0; i--) {
-		const j = Math.floor(random() * (i + 1));
-		[result[i], result[j]] = [result[j], result[i]];
-	}
-	return result;
-}
-
-/**
- * Select an available persona from the pool
- * Uses time-based seeding to ensure variety across sessions while maintaining
- * determinism within the same minute (for retry consistency).
- *
- * @param usedPersonas Set of personas currently in use
- * @param instanceId The instance ID for fallback naming
- * @returns The selected persona name
- */
-export function selectPersona(usedPersonas: Set<string>, instanceId: string): string {
-	const availablePersonas = AGENT_PERSONAS.filter((p) => !usedPersonas.has(p));
-	if (availablePersonas.length === 0) {
-		return `Agent-${instanceId.slice(0, 6)}`;
-	}
-
-	// Use current minute as seed for variety, plus some randomness for the final pick
-	// This ensures different starting points each minute while allowing retries to work
-	const minuteSeed = Math.floor(Date.now() / 60000);
-	const shuffled = seededShuffle(availablePersonas, minuteSeed);
-
-	// Pick randomly from the shuffled list for additional variety
-	return shuffled[Math.floor(Math.random() * shuffled.length)];
-}
-
-// ============================================================================
-// Rate Limiter
-// ============================================================================
-
-export interface RateLimitResult {
-	allowed: boolean;
-	remaining: number;
-	resetIn: number;
-}
-
-export class RateLimiter {
-	private requests: Map<string, { count: number; resetAt: number }> = new Map();
-	private readonly maxRequests: number;
-	private readonly windowMs: number;
-
-	constructor(maxRequests: number = 60, windowMs: number = 60000) {
-		this.maxRequests = maxRequests;
-		this.windowMs = windowMs;
-	}
-
-	check(key: string): RateLimitResult {
-		const now = Date.now();
-		const record = this.requests.get(key);
-
-		// If no record or window expired, create new record
-		if (!record || now >= record.resetAt) {
-			this.requests.set(key, { count: 1, resetAt: now + this.windowMs });
-			return { allowed: true, remaining: this.maxRequests - 1, resetIn: this.windowMs };
-		}
-
-		// Check if limit exceeded
-		if (record.count >= this.maxRequests) {
-			return { allowed: false, remaining: 0, resetIn: record.resetAt - now };
-		}
-
-		// Increment count
-		record.count++;
-		return { allowed: true, remaining: this.maxRequests - record.count, resetIn: record.resetAt - now };
-	}
-
-	// Clean up expired entries periodically
-	cleanup(): void {
-		const now = Date.now();
-		for (const [key, record] of this.requests.entries()) {
-			if (now >= record.resetAt) {
-				this.requests.delete(key);
-			}
-		}
-	}
-
-	// Expose for testing
-	getRequestCount(key: string): number | undefined {
-		return this.requests.get(key)?.count;
-	}
-}
-
-// ============================================================================
-// Task Validation Helpers
-// ============================================================================
-
-/**
- * Check if a task can be validated by the given session
- * @param task The task to validate
- * @param validatorSessionId The session trying to validate
- * @returns Object with canValidate boolean and reason if not allowed
- */
-export function canValidateTask(
-	task: { status: string; validated_at: string | null; working_agent_session_id: string | null },
-	validatorSessionId: string | null
-): { canValidate: boolean; reason?: string } {
-	if (task.status !== 'completed') {
-		return { canValidate: false, reason: 'Can only validate completed tasks' };
-	}
-
-	if (task.validated_at) {
-		return { canValidate: false, reason: 'Task has already been validated' };
-	}
-
-	// Note: Self-validation check would go here if we tracked who completed the task
-	// Currently, working_agent_session_id is cleared on completion
-
-	return { canValidate: true };
-}
-
-/**
- * Check if a task status transition is valid
- * @param currentStatus Current task status
- * @param newStatus Desired new status
- * @returns Object with isValid boolean and reason if not valid
- */
-export function isValidStatusTransition(
-	currentStatus: string,
-	newStatus: string
-): { isValid: boolean; reason?: string } {
-	const validTransitions: Record<string, string[]> = {
-		pending: ['in_progress', 'cancelled'],
-		in_progress: ['completed', 'pending', 'cancelled'],
-		completed: ['in_progress'], // Can reopen via validation failure
-		cancelled: ['pending'], // Can reactivate cancelled tasks
-	};
-
-	const allowed = validTransitions[currentStatus];
-	if (!allowed) {
-		return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
-	}
-
-	if (!allowed.includes(newStatus)) {
-		return {
-			isValid: false,
-			reason: `Cannot transition from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.join(', ')}`
-		};
-	}
-
-	return { isValid: true };
-}
-
-/**
- * Check if a deployment status transition is valid
- * @param currentStatus Current deployment status
- * @param newStatus Desired new status
- * @returns Object with isValid boolean and reason if not valid
- */
-export function isValidDeploymentStatusTransition(
-	currentStatus: string,
-	newStatus: string
-): { isValid: boolean; reason?: string } {
-	const validTransitions: Record<string, string[]> = {
-		pending: ['validating', 'failed'], // Can claim validation or cancel
-		validating: ['ready', 'failed'], // Validation passes or fails
-		ready: ['deploying', 'failed'], // Start deployment or cancel
-		deploying: ['deployed', 'failed'], // Deployment succeeds or fails
-		deployed: [], // Terminal state
-		failed: [], // Terminal state (create new deployment to retry)
-	};
-
-	const allowed = validTransitions[currentStatus];
-	if (!allowed) {
-		return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
-	}
-
-	if (!allowed.includes(newStatus)) {
-		return {
-			isValid: false,
-			reason: `Cannot transition deployment from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.length ? allowed.join(', ') : 'none (terminal state)'}`
-		};
-	}
-
-	return { isValid: true };
-}
-
-// ============================================================================
-// Git URL Parsing
-// ============================================================================
-
-/**
- * Extract project name from a git URL.
- * Handles various git URL formats:
- * - https://github.com/user/repo -> repo
- * - https://github.com/user/repo.git -> repo
- * - git@github.com:user/repo.git -> repo
- * - https://gitlab.com/user/repo -> repo
- * - ssh://git@github.com/user/repo.git -> repo
- *
- * @param gitUrl The git URL to parse
- * @returns The extracted project name, or 'my-project' if parsing fails
- */
-export function extractProjectNameFromGitUrl(gitUrl: string): string {
-	if (!gitUrl) {
-		return 'my-project';
-	}
-
-	// Match the last path segment, optionally removing .git suffix
-	// Works for:
-	// - /user/repo (https URLs)
-	// - /user/repo.git
-	// - :user/repo (ssh URLs like git@github.com:user/repo)
-	// - :user/repo.git
-	const match = gitUrl.match(/[/:]([^/:]+?)(?:\.git)?$/);
-	if (match && match[1]) {
-		return match[1];
-	}
-
-	return 'my-project';
-}
-
-/**
- * Normalize a git URL to a canonical format for consistent project lookup.
- *
- * Handles these variations:
- * - SSH format: `git@github.com:owner/repo` → `https://github.com/owner/repo`
- * - HTTPS with .git suffix: `https://github.com/owner/repo.git` → `https://github.com/owner/repo`
- * - Trailing slashes: `https://github.com/owner/repo/` → `https://github.com/owner/repo`
- * - Case variations: `https://GitHub.com/OWNER/Repo` → `https://github.com/owner/repo`
- * - HTTP protocol: `http://github.com/owner/repo` → `https://github.com/owner/repo`
- * - Bare domains: `github.com/owner/repo` → `https://github.com/owner/repo`
- *
- * @param gitUrl The git URL to normalize (can be null/undefined)
- * @returns Normalized URL in lowercase, or null if input is null/undefined/empty
- *
- * @example
- * normalizeGitUrl('git@github.com:Nonatomic/Vibescope.git')
- * // Returns: 'https://github.com/nonatomic/vibescope'
- *
- * normalizeGitUrl('https://github.com/Nonatomic/Vibescope/')
- * // Returns: 'https://github.com/nonatomic/vibescope'
- */
-export function normalizeGitUrl(gitUrl: string | null | undefined): string | null {
-	if (!gitUrl || typeof gitUrl !== 'string') {
-		return null;
-	}
-
-	let normalized = gitUrl.trim();
-
-	// Empty after trim
-	if (!normalized) {
-		return null;
-	}
-
-	// Convert SSH format: git@github.com:owner/repo → https://github.com/owner/repo
-	const sshMatch = normalized.match(/^git@([^:]+):(.+)$/);
-	if (sshMatch) {
-		normalized = `https://${sshMatch[1]}/${sshMatch[2]}`;
-	}
-
-	// Upgrade http to https
-	if (normalized.startsWith('http://')) {
-		normalized = normalized.replace('http://', 'https://');
-	}
-
-	// Ensure https protocol for URLs that don't have one
-	// but look like they should (e.g., "github.com/owner/repo")
-	if (!normalized.startsWith('https://') && !normalized.includes('://')) {
-		normalized = `https://${normalized}`;
-	}
-
-	// Remove trailing slashes first (so .git suffix removal works for urls like "repo.git/")
-	normalized = normalized.replace(/\/+$/, '');
-
-	// Remove .git suffix
-	normalized = normalized.replace(/\.git$/, '');
-
-	// Lowercase everything (GitHub/GitLab are case-insensitive for URLs)
-	normalized = normalized.toLowerCase();
-
-	return normalized;
-}
-
-// ============================================================================
-// Error Handling Utilities
-// Shared error extraction and type checking functions
-// ============================================================================
-
-/**
- * Extract a human-readable message from any error type.
- * Handles Error objects, strings, and unknown values.
- *
- * @example
- * try { ... } catch (e) {
- *   console.error(getErrorMessage(e));
- * }
- */
-export function getErrorMessage(error: unknown): string {
-	if (error instanceof Error) {
-		return error.message;
-	}
-	if (typeof error === 'string') {
-		return error;
-	}
-	return String(error);
-}
-
-/**
- * Type guard to check if a value is an object with an 'error' property.
- * Useful for checking API responses that may contain application-level errors.
- *
- * @example
- * if (hasErrorProperty(response.data)) {
- *   return error(getErrorMessage(response.data.error));
- * }
- */
-export function hasErrorProperty(value: unknown): value is { error: unknown } {
-	return typeof value === 'object' && value !== null && 'error' in value;
-}
-
-/**
- * Extract an error message from an API response body.
- * Handles the common pattern where API returns { error: string } or { error: { message: string } }.
- * Returns null if no error is found.
- *
- * @example
- * const apiError = extractApiError(response.data);
- * if (apiError) {
- *   return error(apiError);
- * }
- */
-export function extractApiError(data: unknown): string | null {
-	if (!hasErrorProperty(data)) {
-		return null;
-	}
-
-	const err = data.error;
-
-	// Direct string error
-	if (typeof err === 'string') {
-		return err;
-	}
-
-	// Nested error object with message property
-	if (typeof err === 'object' && err !== null && 'message' in err) {
-		const msg = (err as { message: unknown }).message;
-		if (typeof msg === 'string') {
-			return msg;
-		}
-	}
-
-	// Fallback for unknown error structure
-	return 'Unknown error';
-}
-
-// ============================================================================
-// Pagination Utilities
-// ============================================================================
-
-/**
- * Default pagination limits
- */
-export const PAGINATION_LIMITS = {
-	/** Default maximum limit for paginated results */
-	DEFAULT_MAX_LIMIT: 50,
-	/** Default limit when not specified */
-	DEFAULT_LIMIT: 20,
-	/** Smaller limit for task listings */
-	TASK_LIMIT: 20,
-} as const;
-
-/**
- * Cap pagination parameters to safe values.
- * Ensures limit is between 1 and maxLimit, and offset is non-negative.
- *
- * @param limit - Requested limit (will be capped between 1 and maxLimit)
- * @param offset - Requested offset (will be made non-negative)
- * @param maxLimit - Maximum allowed limit (default: PAGINATION_LIMITS.DEFAULT_MAX_LIMIT)
- * @returns Object with cappedLimit and safeOffset
- *
- * @example
- * const { cappedLimit, safeOffset } = capPagination(limit, offset);
- * const { data } = await query.range(safeOffset, safeOffset + cappedLimit - 1);
- *
- * @example
- * // With custom max limit
- * const { cappedLimit, safeOffset } = capPagination(limit, offset, 20);
- */
-export function capPagination(
-	limit: number | undefined,
-	offset: number | undefined,
-	maxLimit: number = PAGINATION_LIMITS.DEFAULT_MAX_LIMIT
-): { cappedLimit: number; safeOffset: number } {
-	const effectiveLimit = limit ?? PAGINATION_LIMITS.DEFAULT_LIMIT;
-	return {
-		cappedLimit: Math.min(Math.max(1, effectiveLimit), maxLimit),
-		safeOffset: Math.max(0, offset ?? 0)
-	};
-}
+// ============================================================================
+// Utilities Module - Extracted from index.ts for testability
+// ============================================================================
+
+import { randomUUID } from 'crypto';
+
+// ============================================================================
+// Agent Persona Pool
+// Iconic sci-fi & fantasy character names for agents on the dashboard
+// ============================================================================
+
+export const AGENT_PERSONAS = [
+	// Star Wars
+	'Yoda',
+	'Leia',
+	'Han',
+	'Luke',
+	'Rey',
+	'Finn',
+	'Kylo',
+	'Mando',
+	'Grogu',
+	'Ahsoka',
+	// Lord of the Rings
+	'Frodo',
+	'Gandalf',
+	'Aragorn',
+	'Legolas',
+	'Gimli',
+	'Sam',
+	'Bilbo',
+	'Gollum',
+	// Star Trek
+	'Spock',
+	'Kirk',
+	'Picard',
+	'Data',
+	'Worf',
+	'Seven',
+	// Dune
+	'Paul',
+	'Chani',
+	'Duncan',
+	'Stilgar',
+	'Leto',
+	// The Matrix
+	'Neo',
+	'Trinity',
+	'Morpheus',
+	// Firefly
+	'Mal',
+	'River',
+	'Kaylee',
+	'Wash',
+	// Game of Thrones
+	'Arya',
+	'Tyrion',
+	'Dany',
+	'Bran',
+	// Marvel / Guardians
+	'Groot',
+	'Rocket',
+	'Gamora',
+	'Drax',
+	'Loki',
+	'Thor',
+	// Classic Sci-Fi AIs & Characters
+	'Ripley',
+	'Jarvis',
+	'Cortana',
+	'GLaDOS',
+] as const;
+
+export type AgentPersona = typeof AGENT_PERSONAS[number];
+
+// ============================================================================
+// Fallback Activities for Idle Agents
+// Suggested productive activities when no pending tasks exist
+// ============================================================================
+
+export const FALLBACK_ACTIVITIES = [
+	{
+		activity: 'feature_ideation',
+		title: 'Generate feature ideas',
+		description: 'Review the codebase and suggest improvements or new features. Use add_idea to record your findings.',
+		prompt: 'Explore the codebase, identify areas for improvement, and suggest 2-3 actionable feature ideas using add_idea.',
+	},
+	{
+		activity: 'feature_planning',
+		title: 'Plan features from ideas',
+		description: 'Take raw ideas and develop them into planned features with documentation.',
+		prompt: 'Call get_ideas to find ideas with status "raw" or "exploring". Pick one and develop it: research requirements, identify implementation steps, write a feature spec. Use update_idea to change status to "planned" and add a doc_url if you create documentation.',
+	},
+	{
+		activity: 'code_review',
+		title: 'Code standards review',
+		description: 'Check for inconsistencies, missing types, code smells, or patterns that could be improved.',
+		prompt: 'Review the codebase for code quality issues. Look for missing types, inconsistent patterns, or technical debt. Log findings with add_idea or add_task.',
+	},
+	{
+		activity: 'performance_audit',
+		title: 'Performance audit',
+		description: 'Identify potential performance bottlenecks or optimization opportunities.',
+		prompt: 'Analyze the codebase for performance issues: N+1 queries, unnecessary re-renders, expensive operations. Create tasks for fixes with add_task.',
+	},
+	{
+		activity: 'ux_review',
+		title: 'UX review',
+		description: 'Evaluate user flows and identify usability improvements.',
+		prompt: 'Review the UI components and user flows. Identify confusing interactions, missing feedback, or accessibility issues. Log improvements with add_idea.',
+	},
+	{
+		activity: 'cost_analysis',
+		title: 'Cost analysis',
+		description: 'Review infrastructure and API usage for cost optimization opportunities.',
+		prompt: 'Analyze the codebase for expensive operations: unnecessary API calls, inefficient queries, large bundle sizes. Suggest cost-saving alternatives with add_idea.',
+	},
+	{
+		activity: 'security_review',
+		title: 'Security review',
+		description: 'Check for common security issues: auth gaps, input validation, data exposure.',
+		prompt: 'Review the codebase for security concerns: authentication gaps, missing input validation, sensitive data handling. Create high-priority tasks for issues found.',
+	},
+	{
+		activity: 'test_coverage',
+		title: 'Test coverage analysis',
+		description: 'Find untested code paths and suggest test cases.',
+		prompt: 'Identify areas of the codebase with missing or weak test coverage. Create tasks for writing tests using add_task.',
+	},
+	{
+		activity: 'documentation_review',
+		title: 'Documentation review',
+		description: 'Identify missing or outdated documentation.',
+		prompt: 'Review existing docs and code comments. Identify gaps, outdated information, or confusing explanations. Log improvements with add_idea.',
+	},
+	{
+		activity: 'dependency_audit',
+		title: 'Dependency audit',
+		description: 'Review dependencies for updates, security issues, or unused packages.',
+		prompt: 'Check package.json for outdated dependencies, security vulnerabilities, or unused packages. Create tasks for updates with add_task.',
+	},
+	{
+		activity: 'validate_completed_tasks',
+		title: 'Validate completed tasks',
+		description: 'Review tasks completed by other agents to ensure quality.',
+		prompt: 'Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.',
+	},
+	{
+		activity: 'worktree_cleanup',
+		title: 'Clean up stale worktrees',
+		description: 'Find and remove git worktrees from completed or abandoned tasks.',
+		prompt: `Clean up stale git worktrees to reclaim disk space and prevent confusion:
+
+1. Call get_stale_worktrees(project_id) to find worktrees needing cleanup
+2. For each stale worktree returned:
+   a. Check if the worktree directory exists: ls -la <worktree_path>
+   b. If it exists, remove it: git worktree remove <worktree_path>
+   c. If removal fails (untracked files), use: git worktree remove --force <worktree_path>
+   d. Call clear_worktree_path(task_id) to mark it as cleaned up
+3. Run 'git worktree list' to verify cleanup
+4. Log any issues encountered with add_blocker if worktrees cannot be removed
+
+This prevents disk bloat from accumulated worktrees and keeps the workspace clean.`,
+	},
+] as const;
+
+export type FallbackActivity = typeof FALLBACK_ACTIVITIES[number];
+
+/**
+ * Get a random fallback activity
+ */
+export function getRandomFallbackActivity(): FallbackActivity {
+	const index = Math.floor(Math.random() * FALLBACK_ACTIVITIES.length);
+	return FALLBACK_ACTIVITIES[index];
+}
+
+/**
+ * Fisher-Yates shuffle with a seed for reproducible randomness
+ */
+function seededShuffle<T>(array: T[], seed: number): T[] {
+	const result = [...array];
+	let currentSeed = seed;
+
+	// Simple seeded random number generator (mulberry32)
+	const random = () => {
+		currentSeed = (currentSeed + 0x6D2B79F5) | 0;
+		let t = currentSeed;
+		t = Math.imul(t ^ (t >>> 15), t | 1);
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+	};
+
+	for (let i = result.length - 1; i > 0; i--) {
+		const j = Math.floor(random() * (i + 1));
+		[result[i], result[j]] = [result[j], result[i]];
+	}
+	return result;
+}
+
+/**
+ * Select an available persona from the pool
+ * Uses time-based seeding to ensure variety across sessions while maintaining
+ * determinism within the same minute (for retry consistency).
+ *
+ * @param usedPersonas Set of personas currently in use
+ * @param instanceId The instance ID for fallback naming
+ * @returns The selected persona name
+ */
+export function selectPersona(usedPersonas: Set<string>, instanceId: string): string {
+	const availablePersonas = AGENT_PERSONAS.filter((p) => !usedPersonas.has(p));
+	if (availablePersonas.length === 0) {
+		return `Agent-${instanceId.slice(0, 6)}`;
+	}
+
+	// Use current minute as seed for variety, plus some randomness for the final pick
+	// This ensures different starting points each minute while allowing retries to work
+	const minuteSeed = Math.floor(Date.now() / 60000);
+	const shuffled = seededShuffle(availablePersonas, minuteSeed);
+
+	// Pick randomly from the shuffled list for additional variety
+	return shuffled[Math.floor(Math.random() * shuffled.length)];
+}
+
+// ============================================================================
+// Rate Limiter
+// ============================================================================
+
+export interface RateLimitResult {
+	allowed: boolean;
+	remaining: number;
+	resetIn: number;
+}
+
+export class RateLimiter {
+	private requests: Map<string, { count: number; resetAt: number }> = new Map();
+	private readonly maxRequests: number;
+	private readonly windowMs: number;
+
+	constructor(maxRequests: number = 60, windowMs: number = 60000) {
+		this.maxRequests = maxRequests;
+		this.windowMs = windowMs;
+	}
+
+	check(key: string): RateLimitResult {
+		const now = Date.now();
+		const record = this.requests.get(key);
+
+		// If no record or window expired, create new record
+		if (!record || now >= record.resetAt) {
+			this.requests.set(key, { count: 1, resetAt: now + this.windowMs });
+			return { allowed: true, remaining: this.maxRequests - 1, resetIn: this.windowMs };
+		}
+
+		// Check if limit exceeded
+		if (record.count >= this.maxRequests) {
+			return { allowed: false, remaining: 0, resetIn: record.resetAt - now };
+		}
+
+		// Increment count
+		record.count++;
+		return { allowed: true, remaining: this.maxRequests - record.count, resetIn: record.resetAt - now };
+	}
+
+	// Clean up expired entries periodically
+	cleanup(): void {
+		const now = Date.now();
+		for (const [key, record] of this.requests.entries()) {
+			if (now >= record.resetAt) {
+				this.requests.delete(key);
+			}
+		}
+	}
+
+	// Expose for testing
+	getRequestCount(key: string): number | undefined {
+		return this.requests.get(key)?.count;
+	}
+}
+
+// ============================================================================
+// Task Validation Helpers
+// ============================================================================
+
+/**
+ * Check if a task can be validated by the given session
+ * @param task The task to validate
+ * @param validatorSessionId The session trying to validate
+ * @returns Object with canValidate boolean and reason if not allowed
+ */
+export function canValidateTask(
+	task: { status: string; validated_at: string | null; working_agent_session_id: string | null },
+	validatorSessionId: string | null
+): { canValidate: boolean; reason?: string } {
+	if (task.status !== 'completed') {
+		return { canValidate: false, reason: 'Can only validate completed tasks' };
+	}
+
+	if (task.validated_at) {
+		return { canValidate: false, reason: 'Task has already been validated' };
+	}
+
+	// Note: Self-validation check would go here if we tracked who completed the task
+	// Currently, working_agent_session_id is cleared on completion
+
+	return { canValidate: true };
+}
+
+/**
+ * Check if a task status transition is valid
+ * @param currentStatus Current task status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export function isValidStatusTransition(
+	currentStatus: string,
+	newStatus: string
+): { isValid: boolean; reason?: string } {
+	const validTransitions: Record<string, string[]> = {
+		pending: ['in_progress', 'cancelled'],
+		in_progress: ['completed', 'pending', 'cancelled'],
+		completed: ['in_progress'], // Can reopen via validation failure
+		cancelled: ['pending'], // Can reactivate cancelled tasks
+	};
+
+	const allowed = validTransitions[currentStatus];
+	if (!allowed) {
+		return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
+	}
+
+	if (!allowed.includes(newStatus)) {
+		return {
+			isValid: false,
+			reason: `Cannot transition from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.join(', ')}`
+		};
+	}
+
+	return { isValid: true };
+}
+
+/**
+ * Check if a deployment status transition is valid
+ * @param currentStatus Current deployment status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export function isValidDeploymentStatusTransition(
+	currentStatus: string,
+	newStatus: string
+): { isValid: boolean; reason?: string } {
+	const validTransitions: Record<string, string[]> = {
+		pending: ['validating', 'failed'], // Can claim validation or cancel
+		validating: ['ready', 'failed'], // Validation passes or fails
+		ready: ['deploying', 'failed'], // Start deployment or cancel
+		deploying: ['deployed', 'failed'], // Deployment succeeds or fails
+		deployed: [], // Terminal state
+		failed: [], // Terminal state (create new deployment to retry)
+	};
+
+	const allowed = validTransitions[currentStatus];
+	if (!allowed) {
+		return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
+	}
+
+	if (!allowed.includes(newStatus)) {
+		return {
+			isValid: false,
+			reason: `Cannot transition deployment from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.length ? allowed.join(', ') : 'none (terminal state)'}`
+		};
+	}
+
+	return { isValid: true };
+}
+
+// ============================================================================
+// Git URL Parsing
+// ============================================================================
+
+/**
+ * Extract project name from a git URL.
+ * Handles various git URL formats:
+ * - https://github.com/user/repo -> repo
+ * - https://github.com/user/repo.git -> repo
+ * - git@github.com:user/repo.git -> repo
+ * - https://gitlab.com/user/repo -> repo
+ * - ssh://git@github.com/user/repo.git -> repo
+ *
+ * @param gitUrl The git URL to parse
+ * @returns The extracted project name, or 'my-project' if parsing fails
+ */
+export function extractProjectNameFromGitUrl(gitUrl: string): string {
+	if (!gitUrl) {
+		return 'my-project';
+	}
+
+	// Match the last path segment, optionally removing .git suffix
+	// Works for:
+	// - /user/repo (https URLs)
+	// - /user/repo.git
+	// - :user/repo (ssh URLs like git@github.com:user/repo)
+	// - :user/repo.git
+	const match = gitUrl.match(/[/:]([^/:]+?)(?:\.git)?$/);
+	if (match && match[1]) {
+		return match[1];
+	}
+
+	return 'my-project';
+}
+
+/**
+ * Normalize a git URL to a canonical format for consistent project lookup.
+ *
+ * Handles these variations:
+ * - SSH format: `git@github.com:owner/repo` → `https://github.com/owner/repo`
+ * - HTTPS with .git suffix: `https://github.com/owner/repo.git` → `https://github.com/owner/repo`
+ * - Trailing slashes: `https://github.com/owner/repo/` → `https://github.com/owner/repo`
+ * - Case variations: `https://GitHub.com/OWNER/Repo` → `https://github.com/owner/repo`
+ * - HTTP protocol: `http://github.com/owner/repo` → `https://github.com/owner/repo`
+ * - Bare domains: `github.com/owner/repo` → `https://github.com/owner/repo`
+ *
+ * @param gitUrl The git URL to normalize (can be null/undefined)
+ * @returns Normalized URL in lowercase, or null if input is null/undefined/empty
+ *
+ * @example
+ * normalizeGitUrl('git@github.com:Nonatomic/Vibescope.git')
+ * // Returns: 'https://github.com/nonatomic/vibescope'
+ *
+ * normalizeGitUrl('https://github.com/Nonatomic/Vibescope/')
+ * // Returns: 'https://github.com/nonatomic/vibescope'
+ */
+export function normalizeGitUrl(gitUrl: string | null | undefined): string | null {
+	if (!gitUrl || typeof gitUrl !== 'string') {
+		return null;
+	}
+
+	let normalized = gitUrl.trim();
+
+	// Empty after trim
+	if (!normalized) {
+		return null;
+	}
+
+	// Convert SSH format: git@github.com:owner/repo → https://github.com/owner/repo
+	const sshMatch = normalized.match(/^git@([^:]+):(.+)$/);
+	if (sshMatch) {
+		normalized = `https://${sshMatch[1]}/${sshMatch[2]}`;
+	}
+
+	// Upgrade http to https
+	if (normalized.startsWith('http://')) {
+		normalized = normalized.replace('http://', 'https://');
+	}
+
+	// Ensure https protocol for URLs that don't have one
+	// but look like they should (e.g., "github.com/owner/repo")
+	if (!normalized.startsWith('https://') && !normalized.includes('://')) {
+		normalized = `https://${normalized}`;
+	}
+
+	// Remove trailing slashes first (so .git suffix removal works for urls like "repo.git/")
+	normalized = normalized.replace(/\/+$/, '');
+
+	// Remove .git suffix
+	normalized = normalized.replace(/\.git$/, '');
+
+	// Lowercase everything (GitHub/GitLab are case-insensitive for URLs)
+	normalized = normalized.toLowerCase();
+
+	return normalized;
+}
+
+// ============================================================================
+// Error Handling Utilities
+// Shared error extraction and type checking functions
+// ============================================================================
+
+/**
+ * Extract a human-readable message from any error type.
+ * Handles Error objects, strings, and unknown values.
+ *
+ * @example
+ * try { ... } catch (e) {
+ *   console.error(getErrorMessage(e));
+ * }
+ */
+export function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) {
+		return error.message;
+	}
+	if (typeof error === 'string') {
+		return error;
+	}
+	return String(error);
+}
+
+/**
+ * Type guard to check if a value is an object with an 'error' property.
+ * Useful for checking API responses that may contain application-level errors.
+ *
+ * @example
+ * if (hasErrorProperty(response.data)) {
+ *   return error(getErrorMessage(response.data.error));
+ * }
+ */
+export function hasErrorProperty(value: unknown): value is { error: unknown } {
+	return typeof value === 'object' && value !== null && 'error' in value;
+}
+
+/**
+ * Extract an error message from an API response body.
+ * Handles the common pattern where API returns { error: string } or { error: { message: string } }.
+ * Returns null if no error is found.
+ *
+ * @example
+ * const apiError = extractApiError(response.data);
+ * if (apiError) {
+ *   return error(apiError);
+ * }
+ */
+export function extractApiError(data: unknown): string | null {
+	if (!hasErrorProperty(data)) {
+		return null;
+	}
+
+	const err = data.error;
+
+	// Direct string error
+	if (typeof err === 'string') {
+		return err;
+	}
+
+	// Nested error object with message property
+	if (typeof err === 'object' && err !== null && 'message' in err) {
+		const msg = (err as { message: unknown }).message;
+		if (typeof msg === 'string') {
+			return msg;
+		}
+	}
+
+	// Fallback for unknown error structure
+	return 'Unknown error';
+}
+
+// ============================================================================
+// Pagination Utilities
+// ============================================================================
+
+/**
+ * Default pagination limits
+ */
+export const PAGINATION_LIMITS = {
+	/** Default maximum limit for paginated results */
+	DEFAULT_MAX_LIMIT: 50,
+	/** Default limit when not specified */
+	DEFAULT_LIMIT: 20,
+	/** Smaller limit for task listings */
+	TASK_LIMIT: 20,
+} as const;
+
+/**
+ * Cap pagination parameters to safe values.
+ * Ensures limit is between 1 and maxLimit, and offset is non-negative.
+ *
+ * @param limit - Requested limit (will be capped between 1 and maxLimit)
+ * @param offset - Requested offset (will be made non-negative)
+ * @param maxLimit - Maximum allowed limit (default: PAGINATION_LIMITS.DEFAULT_MAX_LIMIT)
+ * @returns Object with cappedLimit and safeOffset
+ *
+ * @example
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset);
+ * const { data } = await query.range(safeOffset, safeOffset + cappedLimit - 1);
+ *
+ * @example
+ * // With custom max limit
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset, 20);
+ */
+export function capPagination(
+	limit: number | undefined,
+	offset: number | undefined,
+	maxLimit: number = PAGINATION_LIMITS.DEFAULT_MAX_LIMIT
+): { cappedLimit: number; safeOffset: number } {
+	const effectiveLimit = limit ?? PAGINATION_LIMITS.DEFAULT_LIMIT;
+	return {
+		cappedLimit: Math.min(Math.max(1, effectiveLimit), maxLimit),
+		safeOffset: Math.max(0, offset ?? 0)
+	};
+}