@claudetools/tools 0.8.4 → 0.8.6

package/dist/cli.js

@@ -12,6 +12,7 @@ import { startServer } from './index.js';
 import { startWatcher, stopWatcher, watcherStatus } from './watcher.js';
 import { generateCodebaseMap, generateCodebaseMapLocal } from './helpers/codebase-mapper.js';
 import { contextStatus, contextEvict, contextSummarise, contextReset, } from './context-cli.js';
+import { runTests } from './test-runner.js';
 // Get version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -61,6 +62,9 @@ Commands:
   context evict    Manually trigger eviction cycle
   context summarise Summarise and compress exchanges
   context reset    Clear session state
+  test             Run integration test suite
+  test --verbose   Run tests with detailed output
+  test --json      Output results in JSON format
 
 Running without options starts the MCP server.
 
@@ -206,6 +210,16 @@ else if (positionals[0] === 'context') {
             process.exit(1);
     }
 }
+else if (positionals[0] === 'test') {
+    // Handle test command
+    const testArgs = process.argv.slice(3); // Get args after 'test'
+    const verbose = testArgs.includes('--verbose');
+    const json = testArgs.includes('--json');
+    runTests({ verbose, json }).catch((error) => {
+        console.error('Test run failed:', error);
+        process.exit(1);
+    });
+}
 else {
     // Start MCP server
     startServer();

package/dist/handlers/tool-handlers.js

@@ -11,8 +11,8 @@ import { recordToolCall, getToolCallWarnings } from '../helpers/session-validati
 import { queryDependencies, analyzeImpact } from '../helpers/dependencies.js';
 import { checkPatterns } from '../helpers/patterns.js';
 import { formatContextForClaude } from '../helpers/formatter.js';
-import { compactTaskList, compactTaskCreated, compactTaskStart, compactTaskComplete, compactTaskClaim, compactTaskRelease, compactStatusUpdate, compactContextAdded, compactHeartbeat, compactSummary, } from '../helpers/compact-formatter.js';
-import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getActiveTaskCount, } from '../helpers/tasks.js';
+import { shortId, compactTaskList, compactTaskCreated, compactTaskStart, compactTaskComplete, compactTaskClaim, compactTaskRelease, compactStatusUpdate, compactContextAdded, compactHeartbeat, compactTaskHandoff, compactSummary, } from '../helpers/compact-formatter.js';
+import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, handoffTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getEpicAggregate, getActiveTaskCount, reviseEpic, } from '../helpers/tasks.js';
 import { detectTimedOutTasks, retryTask, failTask, autoRetryTimedOutTasks, } from '../helpers/tasks-retry.js';
 import { detectLibrariesFromPlan } from '../helpers/library-detection.js';
 import { handleGenerateApi, handleGenerateFrontend, handleGenerateComponent, handleListGenerators, handleValidateSpec, handleListPatterns, handleGetPattern, handleDetectPatterns, handleInitProject, } from './codedna-handlers.js';
@@ -133,9 +133,8 @@ export function registerToolHandlers(server) {
                     const entity2 = args?.entity2;
                     const context = args?.context;
                     const is_critical = args?.is_critical;
-                    // Commercial-grade storage with blocking verification
+                    // Storage with read-after-write verification (DO-level)
                     const MAX_RETRIES = 3;
-                    const VERIFY_DELAY_MS = 200;
                     let lastError = null;
                     let storedFactId = null;
                     let storedIsCritical = false;
@@ -144,32 +143,24 @@ export function registerToolHandlers(server) {
                     for (let attempt = 1; attempt <= MAX_RETRIES && !verified; attempt++) {
                         attempts = attempt;
                         try {
-                            // Step 1: Store the fact
                             mcpLogger.info('STORE', `Attempt ${attempt}/${MAX_RETRIES}: Storing "${entity1} ${relationship} ${entity2}"${is_critical ? ' [CRITICAL]' : ''}`);
                             const result = await storeFact(projectId, entity1, relationship, entity2, context, { is_critical });
                             storedFactId = result.fact_id;
                             storedIsCritical = result.is_critical;
                             mcpLogger.info('STORE', `Storage response: ${JSON.stringify(result)}`);
                             if (!result.success || !result.fact_id) {
-                                lastError = new Error(`Storage returned unsuccessful: ${JSON.stringify(result)}`);
+                                lastError = new Error(`Storage returned unsuccessful: ${result.error || 'Unknown error'}`);
                                 mcpLogger.warn('STORE', `Attempt ${attempt} failed: ${lastError.message}`);
                                 continue;
                             }
-                            // Step 2: Wait briefly for eventual consistency
-                            await new Promise(resolve => setTimeout(resolve, VERIFY_DELAY_MS));
-                            // Step 3: Verify the fact is retrievable by searching for it
-                            mcpLogger.info('STORE', `Verifying fact ${storedFactId} is retrievable...`);
-                            const searchQuery = `${entity1} ${relationship} ${entity2}`;
-                            const searchResult = await searchMemory(projectId, searchQuery, 5);
-                            // Check if our fact appears in results
-                            const factFound = searchResult.relevant_facts?.some(f => f.fact?.includes(entity1) && f.fact?.includes(entity2)) || false;
-                            if (factFound) {
+                            // Check DO-level verification (read-after-write in Durable Object)
+                            if (result.verified) {
                                 verified = true;
-                                mcpLogger.info('STORE', `✓ Fact verified as retrievable`);
+                                mcpLogger.info('STORE', `✓ Fact verified at storage layer (ID: ${storedFactId})`);
                             }
                             else {
-                                lastError = new Error(`Fact stored but not found in search results`);
-                                mcpLogger.warn('STORE', `Attempt ${attempt}: Stored but not retrievable. Search returned ${searchResult.relevant_facts?.length || 0} facts.`);
+                                lastError = new Error(`Storage verification failed at DO level`);
+                                mcpLogger.warn('STORE', `Attempt ${attempt}: Storage layer verification failed`);
                             }
                         }
                         catch (err) {
@@ -827,6 +818,73 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_plan_revise': {
+                    const epicId = args?.epic_id;
+                    const addTasks = args?.add_tasks;
+                    const removeTaskIds = args?.remove_task_ids;
+                    const updateTasks = args?.update_tasks;
+                    try {
+                        const result = await reviseEpic(DEFAULT_USER_ID, projectId, epicId, {
+                            add_tasks: addTasks,
+                            remove_task_ids: removeTaskIds,
+                            update_tasks: updateTasks,
+                        });
+                        mcpLogger.toolResult(name, true, timer(), `Epic ${shortId(epicId)} revised: +${result.added.length} tasks, -${result.removed.length} tasks, ~${result.updated.length} tasks`);
+                        let output = `# Epic Revised: ${result.epic.title}\n\n`;
+                        output += `**Epic ID:** \`${result.epic.id}\`\n`;
+                        output += `**Status:** ${result.epic.status}\n\n`;
+                        if (result.added.length > 0) {
+                            output += `## Added Tasks (${result.added.length})\n\n`;
+                            result.added.forEach((task, i) => {
+                                output += `${i + 1}. **${task.title}** (\`${shortId(task.id)}\`)`;
+                                if (task.estimated_effort)
+                                    output += ` - ${task.estimated_effort}`;
+                                output += `\n`;
+                                if (task.description)
+                                    output += `   ${task.description}\n`;
+                            });
+                            output += '\n';
+                        }
+                        if (result.removed.length > 0) {
+                            output += `## Cancelled Tasks (${result.removed.length})\n\n`;
+                            result.removed.forEach((taskId, i) => {
+                                output += `${i + 1}. \`${shortId(taskId)}\` (cancelled)\n`;
+                            });
+                            output += '\n';
+                        }
+                        if (result.updated.length > 0) {
+                            output += `## Updated Tasks (${result.updated.length})\n\n`;
+                            result.updated.forEach((task, i) => {
+                                output += `${i + 1}. **${task.title}** (\`${shortId(task.id)}\`) - Context added with update details\n`;
+                            });
+                            output += '\n';
+                        }
+                        // Get updated epic status
+                        const epicStatus = await getEpicStatus(DEFAULT_USER_ID, projectId, epicId);
+                        output += `## Current Status\n\n`;
+                        output += `**Total Tasks:** ${epicStatus.totalTasks}\n`;
+                        output += `**Progress:** ${epicStatus.percentComplete}% complete\n`;
+                        output += `**By Status:**\n`;
+                        Object.entries(epicStatus.byStatus).forEach(([status, count]) => {
+                            if (count > 0) {
+                                output += `- ${status}: ${count}\n`;
+                            }
+                        });
+                        return {
+                            content: [{ type: 'text', text: output }],
+                        };
+                    }
+                    catch (error) {
+                        mcpLogger.toolResult(name, false, timer(), error instanceof Error ? error.message : 'Unknown error');
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `Error revising epic: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                                }],
+                            isError: true,
+                        };
+                    }
+                }
                 case 'task_start': {
                     const taskId = args?.task_id;
                     const agentId = args?.agent_id || 'claude-code';
@@ -1048,6 +1106,19 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_handoff': {
+                    const taskId = args?.task_id;
+                    const newWorkerType = args?.new_worker_type;
+                    const reason = args?.reason;
+                    const agentId = args?.agent_id || 'claude-code';
+                    const result = await handoffTask(DEFAULT_USER_ID, projectId, taskId, agentId, newWorkerType, reason);
+                    mcpLogger.toolResult(name, true, timer());
+                    // Compact output
+                    const output = compactTaskHandoff(result.data.task, result.data.handed_off, result.data.new_worker_type);
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 // =========================================================================
                 // ORCHESTRATION HANDLERS
                 // =========================================================================
@@ -1100,7 +1171,12 @@ export function registerToolHandlers(server) {
                     output += `**Task:** ${context.task.title}\n`;
                     output += `**Task ID:** \`${context.task.id}\`\n`;
                     output += `**Worker Type:** ${context.worker.name} (\`${context.worker.id}\`)\n`;
-                    output += `**Status:** ${context.task.status}\n\n`;
+                    output += `**Status:** ${context.task.status}\n`;
+                    // Display lock expiry warning if present
+                    if (context.lockWarning?.warning && context.lockWarning.message) {
+                        output += `\n${context.lockWarning.message}\n`;
+                    }
+                    output += `\n`;
                     output += `## System Prompt for Worker\n\n`;
                     output += `\`\`\`\n${context.systemPrompt}\`\`\`\n\n`;
                     if (context.parentTask) {
@@ -1224,6 +1300,47 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_aggregate': {
+                    const epicId = args?.epic_id;
+                    const includePending = args?.include_pending || false;
+                    const aggregate = await getEpicAggregate(DEFAULT_USER_ID, projectId, epicId, includePending);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Epic Aggregate: ${aggregate.epic.title}\n\n`;
+                    output += `**Epic ID:** \`${epicId}\`\n`;
+                    output += `**Epic Status:** ${aggregate.epic.status}\n`;
+                    output += `**Description:** ${aggregate.epic.description}\n\n`;
+                    output += `## Summary Statistics\n\n`;
+                    output += `- **Total Tasks:** ${aggregate.summary_stats.total}\n`;
+                    output += `- **Completed:** ${aggregate.summary_stats.completed}\n`;
+                    output += `- **In Progress:** ${aggregate.summary_stats.in_progress}\n`;
+                    output += `- **Pending:** ${aggregate.summary_stats.pending}\n\n`;
+                    output += `## Task Work Logs\n\n`;
+                    if (aggregate.tasks.length === 0) {
+                        output += `No tasks ${includePending ? '' : 'with work logs '}found for this epic.\n`;
+                    }
+                    else {
+                        for (const task of aggregate.tasks) {
+                            const statusEmoji = task.status === 'done' ? '✅' : task.status === 'in_progress' ? '🔄' : '📋';
+                            output += `### ${statusEmoji} ${task.title}\n`;
+                            output += `- **Task ID:** \`${task.id}\`\n`;
+                            output += `- **Status:** ${task.status}\n`;
+                            if (task.completed_at) {
+                                const completedDate = new Date(task.completed_at).toLocaleString();
+                                output += `- **Completed:** ${completedDate}\n`;
+                            }
+                            if (task.work_log) {
+                                output += `- **Work Log:**\n\n`;
+                                output += `  ${task.work_log}\n\n`;
+                            }
+                            else {
+                                output += `- **Work Log:** None\n\n`;
+                            }
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 case 'task_detect_timeouts': {
                     const timedOut = await detectTimedOutTasks(DEFAULT_USER_ID, projectId);
                     mcpLogger.toolResult(name, true, timer());
@@ -1278,6 +1395,10 @@ export function registerToolHandlers(server) {
                         if (result.error?.includes('Retry limit exceeded')) {
                             output += `The task has been marked as **failed** permanently.\n`;
                         }
+                        else if (result.retryAfter) {
+                            output += `**Retry After:** ${result.retryAfter}\n`;
+                            output += `The task is in exponential backoff. Please wait before retrying.\n`;
+                        }
                     }
                     return {
                         content: [{ type: 'text', text: output }],

package/dist/helpers/api-client.d.ts

@@ -33,6 +33,8 @@ export declare function storeFact(projectId: string, entity1: string, relationsh
     success: boolean;
     fact_id: string;
     is_critical: boolean;
+    verified?: boolean;
+    error?: string;
 }>;
 export declare function getContext(projectId: string, query?: string, userId?: string): Promise<MemoryContext>;
 export declare function getSummary(projectId: string, userId?: string): Promise<string>;

package/dist/helpers/api-client.js

@@ -64,7 +64,18 @@ export async function injectContext(projectId, query, userId = DEFAULT_USER_ID)
     const response = await apiRequest(`/api/v1/memory/${userId}/${projectId}/inject`, 'POST', {
         query,
     });
-    return response.data;
+    // Transform API response to match expected interface
+    // Handle cases where context or metadata might be missing
+    return {
+        augmentedSystemPrompt: response.data.context || '',
+        metadata: response.data.metadata || {
+            memoryNeeded: false,
+            retrievalTimeMs: 0,
+            factsScored: 0,
+            factsIncluded: 0,
+            avgRelevanceScore: 0,
+        },
+    };
 }
 /**
  * List all cached documentation libraries (global cache)

package/dist/helpers/circuit-breaker.d.ts

@@ -0,0 +1,28 @@
+export interface CircuitState {
+    failures: number;
+    lastFailure: number;
+    openedAt: number | null;
+}
+/**
+ * Record a worker failure
+ * Increments failure count and potentially opens the circuit
+ */
+export declare function recordWorkerFailure(workerType: string): void;
+/**
+ * Check if circuit is open for a worker type
+ * Auto-closes circuit if cooldown period has elapsed
+ */
+export declare function isCircuitOpen(workerType: string): boolean;
+/**
+ * Get circuit status for all worker types
+ * Useful for monitoring and debugging
+ */
+export declare function getCircuitStatus(): Map<string, CircuitState>;
+/**
+ * Manually reset a circuit (for testing or admin override)
+ */
+export declare function resetCircuit(workerType: string): void;
+/**
+ * Reset all circuits (for testing)
+ */
+export declare function resetAllCircuits(): void;

package/dist/helpers/circuit-breaker.js

@@ -0,0 +1,97 @@
+// =============================================================================
+// Circuit Breaker for Worker Failure Tracking
+// =============================================================================
+//
+// Implements the circuit breaker pattern to prevent dispatching tasks to
+// failing workers. Tracks failures per worker type and opens circuit after
+// threshold is reached. Circuit auto-closes after cooldown period.
+//
+// Circuit States:
+// - CLOSED: Normal operation, tasks dispatched
+// - OPEN: Too many failures, tasks NOT dispatched to this worker type
+// - HALF_OPEN: Cooldown complete, attempting recovery (not implemented yet)
+//
+// Configuration
+const FAILURE_THRESHOLD = 3; // Open circuit after N failures
+const FAILURE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes window for counting failures
+const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes cooldown before auto-close
+// In-memory circuit state (per worker type)
+const circuits = new Map();
+/**
+ * Record a worker failure
+ * Increments failure count and potentially opens the circuit
+ */
+export function recordWorkerFailure(workerType) {
+    const now = Date.now();
+    const state = circuits.get(workerType) || {
+        failures: 0,
+        lastFailure: 0,
+        openedAt: null,
+    };
+    // If circuit is already open, don't count new failures
+    if (state.openedAt !== null) {
+        return;
+    }
+    // Check if last failure was outside the window
+    if (now - state.lastFailure > FAILURE_WINDOW_MS) {
+        // Reset failure count (new window)
+        state.failures = 1;
+    }
+    else {
+        // Within window, increment
+        state.failures++;
+    }
+    state.lastFailure = now;
+    // Check if we should open the circuit
+    if (state.failures >= FAILURE_THRESHOLD) {
+        state.openedAt = now;
+        console.warn(`[Circuit Breaker] OPENED for worker type: ${workerType} (${state.failures} failures)`);
+    }
+    circuits.set(workerType, state);
+}
+/**
+ * Check if circuit is open for a worker type
+ * Auto-closes circuit if cooldown period has elapsed
+ */
+export function isCircuitOpen(workerType) {
+    const state = circuits.get(workerType);
+    // No failures recorded = closed
+    if (!state || state.openedAt === null) {
+        return false;
+    }
+    const now = Date.now();
+    const timeSinceOpened = now - state.openedAt;
+    // Check if cooldown has elapsed
+    if (timeSinceOpened >= COOLDOWN_MS) {
+        // Auto-close circuit
+        state.openedAt = null;
+        state.failures = 0;
+        circuits.set(workerType, state);
+        console.info(`[Circuit Breaker] AUTO-CLOSED for worker type: ${workerType} (cooldown elapsed)`);
+        return false;
+    }
+    // Still in cooldown
+    return true;
+}
+/**
+ * Get circuit status for all worker types
+ * Useful for monitoring and debugging
+ */
+export function getCircuitStatus() {
+    // Return a copy of the current state
+    return new Map(circuits);
+}
+/**
+ * Manually reset a circuit (for testing or admin override)
+ */
+export function resetCircuit(workerType) {
+    circuits.delete(workerType);
+    console.info(`[Circuit Breaker] RESET for worker type: ${workerType}`);
+}
+/**
+ * Reset all circuits (for testing)
+ */
+export function resetAllCircuits() {
+    circuits.clear();
+    console.info('[Circuit Breaker] RESET ALL circuits');
+}

package/dist/helpers/compact-formatter.d.ts

@@ -49,3 +49,5 @@ export declare function compactMemoryIndex(entries: {
     relevance: number;
     is_critical?: boolean;
 }[]): string;
+/** Compact task handoff */
+export declare function compactTaskHandoff(task: Task, handedOff: boolean, newWorkerType: string): string;

package/dist/helpers/compact-formatter.js

@@ -128,3 +128,9 @@ export function compactMemoryIndex(entries) {
         return `${i + 1}. ${critical}${e.summary.slice(0, 60)} (${rel}%) [${shortId(e.id)}]`;
     }).join('\n');
 }
+/** Compact task handoff */
+export function compactTaskHandoff(task, handedOff, newWorkerType) {
+    if (!handedOff)
+        return `❌ Failed to hand off: ${task.title}`;
+    return `🔄 Handed off: ${task.title} → ${newWorkerType} (ready for re-dispatch)`;
+}

package/dist/helpers/tasks-retry.d.ts

@@ -7,12 +7,19 @@ export interface TimedOutTask {
 export interface RetryMetadata {
     retryCount: number;
     lastFailedAt: string;
+    lastRetryAt?: string;
     lastError?: string;
     failureHistory: Array<{
         timestamp: string;
         error?: string;
     }>;
 }
+/**
+ * Calculate exponential backoff delay in milliseconds
+ * Formula: delay_ms = min(1000 * 2^retry_count, 300000)
+ * Max delay is 5 minutes (300000ms)
+ */
+export declare function calculateBackoffDelay(retryCount: number): number;
 /**
  * Detect tasks that have timed out (lock expired while in_progress)
  * These are likely abandoned or failed tasks
@@ -28,8 +35,10 @@ export declare function retryTask(userId: string, projectId: string, taskId: str
         task: Task;
         retryCount: number;
         retriesRemaining: number;
+        retryAfter?: string;
     };
     error?: string;
+    retryAfter?: string;
 }>;
 /**
  * Mark a task as failed with context

package/dist/helpers/tasks-retry.js

@@ -11,10 +11,22 @@ function getRetryMetadata(task) {
     return {
         retryCount: metadata.retryCount || 0,
         lastFailedAt: metadata.lastFailedAt || '',
+        lastRetryAt: metadata.lastRetryAt,
         lastError: metadata.lastError,
         failureHistory: metadata.failureHistory || [],
     };
 }
+/**
+ * Calculate exponential backoff delay in milliseconds
+ * Formula: delay_ms = min(1000 * 2^retry_count, 300000)
+ * Max delay is 5 minutes (300000ms)
+ */
+export function calculateBackoffDelay(retryCount) {
+    const baseDelay = 1000; // 1 second
+    const maxDelay = 300000; // 5 minutes
+    const delay = baseDelay * Math.pow(2, retryCount);
+    return Math.min(delay, maxDelay);
+}
 /**
  * Update retry metadata
  */
@@ -27,6 +39,7 @@ function updateRetryMetadata(metadata, error) {
         ...metadata,
         retryCount,
         lastFailedAt: timestamp,
+        lastRetryAt: timestamp,
         lastError: error,
         failureHistory: [
             ...failureHistory,
@@ -90,6 +103,23 @@ export async function retryTask(userId, projectId, taskId, maxRetries = 3, error
             error: `Retry limit exceeded (${maxRetries} retries)`,
         };
     }
+    // Check exponential backoff window
+    if (retryMetadata.lastRetryAt && retryMetadata.retryCount > 0) {
+        const lastRetryTime = new Date(retryMetadata.lastRetryAt);
+        const now = new Date();
+        const timeSinceLastRetry = now.getTime() - lastRetryTime.getTime();
+        const backoffDelay = calculateBackoffDelay(retryMetadata.retryCount);
+        if (timeSinceLastRetry < backoffDelay) {
+            const remainingBackoff = backoffDelay - timeSinceLastRetry;
+            const retryAfterTime = new Date(now.getTime() + remainingBackoff);
+            const retryAfter = retryAfterTime.toISOString();
+            return {
+                success: false,
+                error: `Task is in backoff window. Please wait ${Math.ceil(remainingBackoff / 1000)} seconds before retrying.`,
+                retryAfter,
+            };
+        }
+    }
     // Update metadata with failure info
     const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
     // Update task with retry metadata and reset status

package/dist/helpers/tasks.d.ts

@@ -127,15 +127,30 @@ export declare function heartbeatTask(userId: string, projectId: string, taskId:
         new_expires_at: string;
     };
 }>;
-export declare const DEFAULT_MAX_PARALLEL = 5;
+export declare const EFFORT_WEIGHTS: {
+    readonly xs: 1;
+    readonly s: 2;
+    readonly m: 4;
+    readonly l: 8;
+    readonly xl: 16;
+};
+export declare const LOCK_DURATION_BY_EFFORT: {
+    readonly xs: 15;
+    readonly s: 30;
+    readonly m: 60;
+    readonly l: 120;
+    readonly xl: 240;
+};
+export declare const DEFAULT_CAPACITY_BUDGET = 20;
 /**
- * Get count of currently active tasks
- * Returns both in_progress and claimed (locked) task counts
+ * Get effort-weighted load of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts, plus effort-weighted load
  */
 export declare function getActiveTaskCount(userId: string, projectId: string, epicId?: string): Promise<{
     inProgress: number;
     claimed: number;
     total: number;
+    effortLoad: number;
 }>;
 /**
  * Get all tasks ready for parallel dispatch
@@ -143,9 +158,17 @@ export declare function getActiveTaskCount(userId: string, projectId: string, ep
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
- * - Respects max parallel limit by considering currently active tasks
+ * - Respects effort-weighted capacity budget
  */
-export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, maxParallel?: number): Promise<DispatchableTask[]>;
+export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, capacityBudget?: number): Promise<DispatchableTask[]>;
+/**
+ * Check if task lock is about to expire and return warning
+ */
+export declare function getLockExpiryWarning(lockExpiresAt: string | null): {
+    warning: boolean;
+    minutes_remaining: number;
+    message?: string;
+};
 /**
  * Get full execution context for a worker agent
  */
@@ -156,11 +179,41 @@ export declare function getExecutionContext(userId: string, projectId: string, t
     context: TaskContext[];
     parentTask?: Task;
     siblingTasks?: Task[];
+    lockWarning?: {
+        warning: boolean;
+        minutes_remaining: number;
+        message?: string;
+    };
 }>;
 /**
  * Find newly unblocked tasks after a completion and update their status to ready
  */
 export declare function resolveTaskDependencies(userId: string, projectId: string, completedTaskId: string, epicId?: string): Promise<Task[]>;
+/**
+ * Aggregate work_log context from all tasks in an epic
+ * Used by orchestrator to synthesize final results
+ */
+export declare function getEpicAggregate(userId: string, projectId: string, epicId: string, includePending?: boolean): Promise<{
+    epic: {
+        id: string;
+        title: string;
+        description: string;
+        status: string;
+    };
+    tasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+        work_log: string | null;
+        completed_at: string | null;
+    }>;
+    summary_stats: {
+        total: number;
+        completed: number;
+        in_progress: number;
+        pending: number;
+    };
+}>;
 /**
  * Get epic status with progress tracking
  * Auto-completes epic if all child tasks are done
@@ -173,3 +226,36 @@ export declare function getEpicStatus(userId: string, projectId: string, epicId:
     allComplete: boolean;
     autoCompleted: boolean;
 }>;
+export declare function handoffTask(userId: string, projectId: string, taskId: string, agentId: string, newWorkerType: string, reason: string): Promise<{
+    success: boolean;
+    data: {
+        task: Task;
+        handed_off: boolean;
+        new_worker_type: string;
+    };
+}>;
+/**
+ * Revise an existing epic by adding/removing/updating tasks
+ * Enables iterative planning without recreating the entire epic
+ */
+export declare function reviseEpic(userId: string, projectId: string, epicId: string, changes: {
+    add_tasks?: {
+        title: string;
+        description?: string;
+        effort?: string;
+        domain?: string;
+        blocked_by?: string[];
+    }[];
+    remove_task_ids?: string[];
+    update_tasks?: {
+        task_id: string;
+        title?: string;
+        description?: string;
+        effort?: string;
+    }[];
+}): Promise<{
+    epic: Task;
+    added: Task[];
+    removed: string[];
+    updated: Task[];
+}>;