@calmo/task-runner 2.0.0 → 3.1.0

package/dist/WorkflowExecutor.js

@@ -5,97 +5,95 @@
 export class WorkflowExecutor {
     context;
     eventBus;
-    running = new Set();
+    stateManager;
+    strategy;
     /**
      * @param context The shared context object.
      * @param eventBus The event bus to emit events.
+     * @param stateManager Manages execution state.
+     * @param strategy Execution strategy.
      */
-    constructor(context, eventBus) {
+    constructor(context, eventBus, stateManager, strategy) {
         this.context = context;
         this.eventBus = eventBus;
+        this.stateManager = stateManager;
+        this.strategy = strategy;
     }
     /**
      * Executes the given steps.
      * @param steps The list of steps to execute.
+     * @param signal Optional AbortSignal for cancellation.
      * @returns A Promise that resolves to a map of task results.
      */
-    async execute(steps) {
+    async execute(steps, signal) {
         this.eventBus.emit("workflowStart", { context: this.context, steps });
-        const results = new Map();
+        this.stateManager.initialize(steps);
+        // Check if already aborted
+        if (signal?.aborted) {
+            this.stateManager.cancelAllPending("Workflow cancelled before execution started.");
+            const results = this.stateManager.getResults();
+            this.eventBus.emit("workflowEnd", { context: this.context, results });
+            return results;
+        }
         const executingPromises = new Set();
-        // Initial pass
-        this.processQueue(steps, results, executingPromises);
-        while (results.size < steps.length && executingPromises.size > 0) {
-            // Wait for the next task to finish
-            await Promise.race(executingPromises);
-            // After a task finishes, check for new work
-            this.processQueue(steps, results, executingPromises);
+        const onAbort = () => {
+            // Mark all pending tasks as cancelled
+            this.stateManager.cancelAllPending("Workflow cancelled.");
+        };
+        if (signal) {
+            signal.addEventListener("abort", onAbort);
         }
-        this.eventBus.emit("workflowEnd", { context: this.context, results });
-        return results;
-    }
-    /**
-     * Logic to identify tasks that can be started or must be skipped.
-     */
-    processQueue(steps, results, executingPromises) {
-        this.handleSkippedTasks(steps, results);
-        const readySteps = this.getReadySteps(steps, results);
-        for (const step of readySteps) {
-            const taskPromise = this.runStep(step, results).then(() => {
-                executingPromises.delete(taskPromise);
-            });
-            executingPromises.add(taskPromise);
+        try {
+            // Initial pass
+            this.processLoop(executingPromises, signal);
+            while (this.stateManager.hasPendingTasks() ||
+                this.stateManager.hasRunningTasks()) {
+                // Safety check: if no tasks are running and we still have pending tasks,
+                // it means we are stuck (e.g. cycle or unhandled dependency).
+                // Since valid graphs shouldn't have this, we break to avoid infinite loop.
+                if (executingPromises.size === 0) {
+                    break;
+                }
+                else {
+                    // Wait for the next task to finish
+                    await Promise.race(executingPromises);
+                }
+                if (signal?.aborted) {
+                    this.stateManager.cancelAllPending("Workflow cancelled.");
+                }
+                else {
+                    // After a task finishes, check for new work
+                    this.processLoop(executingPromises, signal);
+                }
+            }
+            // Ensure everything is accounted for (e.g. if loop exited early)
+            this.stateManager.cancelAllPending("Workflow cancelled.");
+            const results = this.stateManager.getResults();
+            this.eventBus.emit("workflowEnd", { context: this.context, results });
+            return results;
         }
-    }
-    /**
-     * Identifies steps that cannot run because a dependency failed.
-     */
-    handleSkippedTasks(steps, results) {
-        const pendingSteps = steps.filter((step) => !results.has(step.name) && !this.running.has(step.name));
-        for (const step of pendingSteps) {
-            const deps = step.dependencies ?? [];
-            const failedDep = deps.find((dep) => results.has(dep) && results.get(dep)?.status !== "success");
-            if (failedDep) {
-                const result = {
-                    status: "skipped",
-                    message: `Skipped due to failed dependency: ${failedDep}`,
-                };
-                results.set(step.name, result);
-                this.eventBus.emit("taskSkipped", { step, result });
+        finally {
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
             }
         }
     }
     /**
-     * Returns steps where all dependencies have finished successfully.
-     */
-    getReadySteps(steps, results) {
-        return steps.filter((step) => {
-            if (results.has(step.name) || this.running.has(step.name))
-                return false;
-            const deps = step.dependencies ?? [];
-            return deps.every((dep) => results.has(dep) && results.get(dep)?.status === "success");
-        });
-    }
-    /**
-     * Handles the lifecycle of a single task execution.
+     * Logic to identify tasks that can be started and run them.
      */
-    async runStep(step, results) {
-        this.running.add(step.name);
-        this.eventBus.emit("taskStart", { step });
-        try {
-            const result = await step.run(this.context);
-            results.set(step.name, result);
-        }
-        catch (e) {
-            results.set(step.name, {
-                status: "failure",
-                error: e instanceof Error ? e.message : String(e),
+    processLoop(executingPromises, signal) {
+        const toRun = this.stateManager.processDependencies();
+        // Execute ready tasks
+        for (const step of toRun) {
+            this.stateManager.markRunning(step);
+            const taskPromise = this.strategy.execute(step, this.context, signal)
+                .then((result) => {
+                this.stateManager.markCompleted(step, result);
+            })
+                .finally(() => {
+                executingPromises.delete(taskPromise);
             });
-        }
-        finally {
-            this.running.delete(step.name);
-            const result = results.get(step.name);
-            this.eventBus.emit("taskEnd", { step, result });
+            executingPromises.add(taskPromise);
         }
     }
 }

package/dist/WorkflowExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowExecutor.js","sourceRoot":"","sources":["../src/WorkflowExecutor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WorkflowExecutor.js","sourceRoot":"","sources":["../src/WorkflowExecutor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { TaskRunner } from "./TaskRunner.js";
+export { TaskRunnerBuilder } from "./TaskRunnerBuilder.js";
+export { TaskStateManager } from "./TaskStateManager.js";
+export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
+export type { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 export type { TaskStep } from "./TaskStep.js";
 export type { TaskResult } from "./TaskResult.js";
 export type { TaskStatus } from "./TaskStatus.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export { TaskRunner } from "./TaskRunner.js";
+export { TaskRunnerBuilder } from "./TaskRunnerBuilder.js";
+export { TaskStateManager } from "./TaskStateManager.js";
+export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/strategies/DryRunExecutionStrategy.d.ts

@@ -0,0 +1,16 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Execution strategy that simulates task execution without running the actual logic.
+ */
+export declare class DryRunExecutionStrategy<TContext> implements IExecutionStrategy<TContext> {
+    /**
+     * Simulates execution by returning a success result immediately.
+     * @param step The task step (ignored).
+     * @param context The shared context (ignored).
+     * @param signal Optional abort signal (ignored).
+     * @returns A promise resolving to a success result.
+     */
+    execute(_step: TaskStep<TContext>, _context: TContext, _signal?: AbortSignal): Promise<TaskResult>;
+}

package/dist/strategies/DryRunExecutionStrategy.js

@@ -0,0 +1,25 @@
+/**
+ * Execution strategy that simulates task execution without running the actual logic.
+ */
+export class DryRunExecutionStrategy {
+    /**
+     * Simulates execution by returning a success result immediately.
+     * @param step The task step (ignored).
+     * @param context The shared context (ignored).
+     * @param signal Optional abort signal (ignored).
+     * @returns A promise resolving to a success result.
+     */
+    async execute(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _step, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _context, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _signal) {
+        return Promise.resolve({
+            status: "success",
+            message: "Dry run: simulated success",
+        });
+    }
+}
+//# sourceMappingURL=DryRunExecutionStrategy.js.map

package/dist/strategies/DryRunExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DryRunExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/DryRunExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAGlC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO;IACX,6DAA6D;IAC7D,KAAyB;IACzB,6DAA6D;IAC7D,QAAkB;IAClB,6DAA6D;IAC7D,OAAqB;QAErB,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,4BAA4B;SACtC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/strategies/IExecutionStrategy.d.ts

@@ -0,0 +1,16 @@
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Interface for task execution strategies.
+ * Allows different execution behaviors (e.g., standard, dry-run, debugging).
+ */
+export interface IExecutionStrategy<TContext> {
+    /**
+     * Executes a single task step.
+     * @param step The task step to execute.
+     * @param context The shared context.
+     * @param signal Optional abort signal.
+     * @returns A promise resolving to the task result.
+     */
+    execute(step: TaskStep<TContext>, context: TContext, signal?: AbortSignal): Promise<TaskResult>;
+}

package/dist/strategies/IExecutionStrategy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IExecutionStrategy.js.map

package/dist/strategies/IExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/IExecutionStrategy.ts"],"names":[],"mappings":""}

package/dist/strategies/StandardExecutionStrategy.d.ts

@@ -0,0 +1,9 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Standard execution strategy that runs the task's run method.
+ */
+export declare class StandardExecutionStrategy<TContext> implements IExecutionStrategy<TContext> {
+    execute(step: TaskStep<TContext>, context: TContext, signal?: AbortSignal): Promise<TaskResult>;
+}

package/dist/strategies/StandardExecutionStrategy.js

@@ -0,0 +1,25 @@
+/**
+ * Standard execution strategy that runs the task's run method.
+ */
+export class StandardExecutionStrategy {
+    async execute(step, context, signal) {
+        try {
+            return await step.run(context, signal);
+        }
+        catch (e) {
+            // Check if error is due to abort
+            if (signal?.aborted &&
+                (e instanceof Error && e.name === "AbortError" || signal.reason === e)) {
+                return {
+                    status: "cancelled",
+                    message: "Task cancelled during execution",
+                };
+            }
+            return {
+                status: "failure",
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+}
+//# sourceMappingURL=StandardExecutionStrategy.js.map

package/dist/strategies/StandardExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StandardExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/StandardExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,yBAAyB;IAGpC,KAAK,CAAC,OAAO,CACX,IAAwB,EACxB,OAAiB,EACjB,MAAoB;QAEpB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,iCAAiC;YACjC,IACE,MAAM,EAAE,OAAO;gBACf,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,EACtE,CAAC;gBACD,OAAO;oBACL,MAAM,EAAE,WAAW;oBACnB,OAAO,EAAE,iCAAiC;iBAC3C,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;aAClD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/openspec/changes/add-concurrency-control/proposal.md

@@ -0,0 +1,14 @@
+# Change: Add Concurrency Control
+
+## Why
+The current implementation executes *all* independent tasks in parallel. In large graphs with many independent nodes, this could overwhelm system resources (CPU, memory) or trigger external API rate limits.
+
+## What Changes
+- Add `concurrency: number` optional property to `WorkflowExecutor`.
+- Modify `WorkflowExecutor.processLoop` to respect the concurrency limit.
+    - Track the active promise count.
+    - Only start new tasks from the ready queue if `active < concurrency`.
+    - Continue to defer ready tasks until slots open up.
+
+## Impact
+- **Affected Components**: `WorkflowExecutor`

package/openspec/changes/add-concurrency-control/tasks.md

@@ -0,0 +1,9 @@
+## Implementation
+- [ ] 1.1 Update `TaskRunnerExecutionConfig` to include an optional `concurrency` property.
+- [ ] 1.2 Update `WorkflowExecutor` to accept the `concurrency` limit.
+- [ ] 1.3 Implement a task queueing mechanism in `WorkflowExecutor` to manage pending tasks.
+- [ ] 1.4 Update execution logic to check available concurrency slots before starting a task.
+- [ ] 1.5 Ensure task completion triggers the execution of queued tasks.
+- [ ] 1.6 Verify that unlimited concurrency (default behavior) is preserved when no limit is set.
+- [ ] 1.7 Add unit tests for concurrency limits (e.g., ensure no more than N tasks run at once).
+- [ ] 1.8 Add integration tests with mixed dependencies and concurrency limits.

package/openspec/changes/add-task-retry-policy/proposal.md

@@ -0,0 +1,16 @@
+# Change: Add Task Retry Policy
+
+## Why
+Tasks currently run once and fail immediately if they throw an error or return a failure status. Network glitches or transient issues can therefore cause an entire workflow to fail unnecessarily.
+
+## What Changes
+- Add `TaskRetryConfig` interface to define retry behavior (attempts, delay, backoff).
+- Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
+- Implement `RetryingExecutionStrategy` which decorates any `IExecutionStrategy`.
+  - It catches failures from the inner strategy.
+  - It checks the retry policy.
+  - It waits and re-executes the step if applicable.
+
+## Impact
+- **New Components**: `RetryingExecutionStrategy`, `TaskRetryConfig`
+- **Affected Components**: `TaskStep` (interface update)

package/openspec/changes/add-task-retry-policy/tasks.md

@@ -0,0 +1,10 @@
+## Implementation
+- [ ] 1.1 Create `TaskRetryConfig` interface with `attempts`, `delay`, and `backoff`.
+- [ ] 1.2 Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
+- [ ] 1.3 Update execution logic to catch task failures.
+- [ ] 1.4 Implement retry loop/recursion checking `attempts` count.
+- [ ] 1.5 Implement delay logic with support for `fixed` and `exponential` backoff.
+- [ ] 1.6 Ensure `TaskResult` reflects the final status after retries (success if eventually succeeds, failure if all attempts fail).
+- [ ] 1.7 Add unit tests for successful retry after failure.
+- [ ] 1.8 Add unit tests for exhaustion of retry attempts (final failure).
+- [ ] 1.9 Add unit tests for backoff timing (mock timers).

package/openspec/changes/add-workflow-preview/proposal.md

@@ -0,0 +1,13 @@
+# Change: Add Workflow Preview
+
+## Why
+It can be difficult to understand the execution flow of complex dependency graphs just by looking at the code. Users also currently cannot easily verify the execution plan without running the side effects, which carries risk.
+
+## What Changes
+- Add a `DryRunExecutionStrategy` which implements `IExecutionStrategy`. This allows `WorkflowExecutor` to simulate execution without side effects.
+- Add a standalone utility `generateMermaidGraph(steps: TaskStep[])` to generate a Mermaid.js diagram of the dependency graph.
+- Expose these features via the main `TaskRunner` facade if applicable, or as separate utilities.
+
+## Impact
+- **New Components**: `DryRunExecutionStrategy`, `generateMermaidGraph`
+- **Affected Components**: `WorkflowExecutor` (indirectly, via strategy injection)

package/openspec/changes/add-workflow-preview/tasks.md

@@ -0,0 +1,7 @@
+## Implementation
+- [ ] 1.1 Update `TaskRunnerExecutionConfig` to include an optional `dryRun: boolean` property.
+- [ ] 1.2 Implement `dryRun` logic in `WorkflowExecutor` (traverse graph, validate order, skip `step.run()`, return `skipped` or `success` pseudo-status).
+- [ ] 1.3 Implement `getMermaidGraph(steps: TaskStep[])` method (can be static or instance method on `TaskRunner`).
+- [ ] 1.4 Ensure `dryRun` respects other configs like `concurrency` (if applicable) to simulate actual timing/order if possible, or just strict topological order.
+- [ ] 1.5 Add unit tests for `dryRun` ensuring no side effects occur.
+- [ ] 1.6 Add unit tests for `getMermaidGraph` output correctness (nodes and edges).

package/openspec/changes/archive/2026-01-18-add-external-task-cancellation/tasks.md

@@ -0,0 +1,10 @@
+## Implementation
+- [x] 1.1 Update `TaskRunner.execute` signature to accept an optional config object.
+- [x] 1.2 Implement logic within `TaskRunner` to listen for `AbortSignal` and initiate cancellation.
+- [x] 1.3 Implement global timeout mechanism using `AbortController` and `setTimeout`.
+- [x] 1.4 Propagate `AbortSignal` to individual `TaskStep` executions.
+- [x] 1.5 Ensure `TaskRunner` correctly handles tasks that are already aborted before execution.
+- [x] 1.6 Update `TaskResult` and `RunnerEvents` to reflect cancellation status.
+- [x] 1.7 Add unit tests for `AbortSignal` cancellation scenarios.
+- [x] 1.8 Add unit tests for global timeout scenarios.
+- [x] 1.9 Add integration tests covering both `AbortSignal` and timeout interactions.

package/openspec/changes/archive/2026-01-18-add-integration-tests/proposal.md

@@ -0,0 +1,18 @@
+# Change: Add Comprehensive Integration Tests
+
+## Why
+The current test suite relies heavily on unit tests and mocks. To ensure robust behavior in real-world scenarios, we need comprehensive integration tests that execute full task graphs without mocks, validating complex configurations and interactions.
+
+## What Changes
+- Create a dedicated `tests/integration-tests/` directory.
+- Implement 10-20 integration test scenarios covering:
+  - Linear and branching dependencies.
+  - Failure handling and propagation.
+  - Context mutation and sharing.
+  - Timing and concurrency (real execution).
+  - Cancellation and timeouts.
+  - Error recovery (if retry policy is implemented, otherwise standard error states).
+
+## Impact
+- Affected specs: `task-runner` (no functional changes to the runtime, but validates existing specs)
+- Affected code: `tests/integration-tests/*`

package/openspec/changes/archive/2026-01-18-add-integration-tests/tasks.md

@@ -0,0 +1,17 @@
+## Implementation
+- [x] 1.1 Setup `tests/integration-tests/` directory and test runner config if needed.
+- [x] 1.2 Implement Scenario 1: Basic linear workflow (A -> B -> C) success.
+- [x] 1.3 Implement Scenario 2: Branching workflow (A -> [B, C] -> D) success.
+- [x] 1.4 Implement Scenario 3: Task failure and downstream skipping (A -> B(fail) -> C(skip)).
+- [x] 1.5 Implement Scenario 4: Shared context mutation (A writes, B reads).
+- [x] 1.6 Implement Scenario 5: Large graph execution (e.g., 20+ nodes).
+- [x] 1.7 Implement Scenario 6: Mixed duration tasks (verifying parallel efficiency).
+- [x] 1.8 Implement Scenario 7: Cancellation via AbortSignal in mid-execution.
+- [x] 1.9 Implement Scenario 8: Global timeout interrupting long tasks.
+- [x] 1.10 Implement Scenario 9: Dynamic context validation (tasks validating context state).
+- [x] 1.11 Implement Scenario 10: Circular dependency detection (at runtime validation).
+- [x] 1.12 Implement Scenario 11: Missing dependency handling.
+- [x] 1.13 Implement Scenario 12: Complex "Diamond" dependency graph.
+- [x] 1.14 Implement Scenario 13: Tasks with side-effects (e.g., file I/O or simulated network).
+- [x] 1.15 Implement Scenario 14: Zero-dependency parallel burst (all run at once).
+- [x] 1.16 Verification: Ensure all integration tests pass consistently.

package/openspec/changes/archive/2026-01-18-refactor-core-architecture/proposal.md

@@ -0,0 +1,14 @@
+# Change: Refactor Core Architecture
+
+## Why
+When multiple developers work on the project, conflicts arise due to tight coupling and poor separation of concerns. Large classes like `WorkflowExecutor` are taking on too many responsibilities, and there is duplicated logic around graph traversal and state management.
+
+## What Changes
+- Decouple `WorkflowExecutor` from `EventBus` (pass a listener interface or use a mediating controller).
+- Extract `TaskExecutionStrategy` to allow pluggable execution modes (e.g., standard, dry-run, debug).
+- Centralize state management for task results and context, moving it out of the executor loop.
+- Standardize error handling and logging (QoL improvements).
+
+## Impact
+- Affected specs: `task-runner` (no behavior change, but structural refactor)
+- Affected code: `src/WorkflowExecutor.ts`, `src/TaskRunner.ts`, new files for extracted logic.

package/openspec/changes/archive/2026-01-18-refactor-core-architecture/tasks.md

@@ -0,0 +1,8 @@
+## Implementation
+- [x] 1.1 Extract `TaskStateManager` to handle `TaskResult` storage, updates, and context mutations.
+- [x] 1.2 Define `IExecutionStrategy` interface for running tasks (Strategy Pattern).
+- [x] 1.3 Refactor `WorkflowExecutor` to use `TaskStateManager` and `IExecutionStrategy`.
+- [x] 1.4 Move explicit event emission out of the core loop into the `TaskStateManager` or a dedicated `ExecutionObserver`.
+- [x] 1.5 Create a factory or builder for `TaskRunner` to simplify configuration for developers.
+- [x] 1.6 Verify that all existing tests pass with the new structure.
+- [x] 1.7 Add "Quality of Life" improvements (e.g., better error messages with specific task context).

package/openspec/changes/feat-per-task-timeout/proposal.md

@@ -0,0 +1,25 @@
+# Feature: Per-Task Timeout
+
+## 🎯 User Story
+"As a developer, I want to define a maximum execution time for specific tasks so that a single hung task (e.g., a stalled network request) fails fast without blocking the rest of the independent tasks or waiting for the global workflow timeout."
+
+## ❓ Why
+Currently, the `TaskRunner` allows a **global** timeout for the entire `execute()` call. However, this is insufficient for granular control:
+1.  **Varying Latency**: Some tasks are expected to be fast (local validation), others slow (data fetching). A global timeout of 30s is too loose for the fast ones.
+2.  **Boilerplate**: Developers currently have to manually implement `setTimeout`, `Promise.race`, and `AbortController` logic inside every `run()` method to handle timeouts properly.
+3.  **Resilience**: A single "zombie" task can hold up the entire pipeline until the global timeout kills everything. Per-task timeouts allow failing that specific task (and skipping its dependents) while letting other independent tasks continue.
+
+## 🛠️ What Changes
+1.  **Interface Update**: Update `TaskStep<T>` to accept an optional `timeout` property (in milliseconds).
+2.  **Execution Strategy**: Update `StandardExecutionStrategy` to:
+    -   Create a local timeout timer for the task.
+    -   Create a combined `AbortSignal` (merging the workflow's signal and the local timeout).
+    -   Race the task execution against the timer.
+    -   Return a specific failure result if the timeout wins.
+
+## ✅ Acceptance Criteria
+- [ ] A task with `timeout: 100` must fail if the `run` method takes > 100ms.
+- [ ] The error message for a timed-out task should clearly state "Task timed out after 100ms".
+- [ ] The `AbortSignal` passed to the task's `run` method must be triggered when the timeout occurs.
+- [ ] If the Global Workflow is cancelled *before* the task times out, the task should receive the cancellation signal immediately.
+- [ ] A task completing *before* the timeout should clear the timer to prevent open handles.

package/openspec/changes/feat-per-task-timeout/tasks.md

@@ -0,0 +1,27 @@
+# Engineering Tasks
+
+- [ ] **Task 1: Update Interface**
+  - Modify `src/TaskStep.ts` to add `timeout?: number;` to the `TaskStep` interface.
+  - Document the property (milliseconds).
+
+- [ ] **Task 2: Add Timeout Logic to StandardExecutionStrategy**
+  - Modify `src/strategies/StandardExecutionStrategy.ts`.
+  - Inside `execute`:
+    - Check if `step.timeout` is defined.
+    - If yes, create an `AbortController`.
+    - Set a `setTimeout` to trigger the controller.
+    - Use `Promise.race` (or simply pass the new signal and wait) to handle the timeout.
+    - **Crucial**: Ensure the new signal respects the *parent* `signal` (if global cancel happens, local signal must also abort).
+    - **Crucial**: Clean up the timer (`clearTimeout`) in a `finally` block.
+
+- [ ] **Task 3: Unit Tests**
+  - Create `tests/strategies/StandardExecutionStrategy.timeout.test.ts`.
+  - Test case: Task finishes before timeout (success).
+  - Test case: Task runs longer than timeout (failure/error).
+  - Test case: Task receives AbortSignal on timeout.
+  - Test case: Global cancellation overrides local timeout.
+
+- [ ] **Task 4: Integration Test**
+  - Update `tests/TaskRunner.test.ts` or create `tests/timeouts.test.ts`.
+  - Define a workflow with a slow task and a short timeout.
+  - Verify that the slow task fails, dependents are skipped, and independent tasks still complete (if any).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "",
   "repository": {
     "type": "git",