taski 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ad85c90c371fc1ea2f61e1d7e9817c7a9cc3fa9f258be2bf1154ced5f4c0349
-  data.tar.gz: a56399d990f0a3ecfddff0f24b5a45c8319ea88e58299a3d3a22a2336295f5cc
+  metadata.gz: 6cf783b65df1fdbbb8c8f19d78467243ea1d054c1b47097cae24b11d22d30c56
+  data.tar.gz: f5a88d4f88a6babb6e121b93cd22066691563a539c722cd8a3e336258ebfe495
 SHA512:
-  metadata.gz: f6969545ce4924434c3e031dca9fff39a974dfd53ee73fb610979cdc3fd09842f50b8871efec23a79dd40d1985bb97c92b651744655a38a12edbdeb9c0f05daa
-  data.tar.gz: 94a9f76f2da179d4b202b788f3abf27531b8a1df4ccd186eb84a5c695dfcbca3c78f75f2350ba052dcb98b68da7427e60b0a493e67340c1d04440278b4c3ab7f
+  metadata.gz: ff7ccc6b57e2ed321a84406e2e8e913aac4ec5d9cf2e6f3d00f28cc9b22bbb6609147d500a3fca1dde7fe37bb921cd8ba00380c9b52962f71ea5e2331bef8e16
+  data.tar.gz: 5978f76dab28ef8cc3f57338a89996e9ba45fce7c897cf7739e7ada9076e5fc0006bb5663a1723c5492140fec8e14f5811100a8325e96dc56ebdf35684aeca0b

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-02-16
+
+### Added
+- Progress::Config API for declarative layout/theme configuration ([#180](https://github.com/ahogappa/taski/pull/180))
+- Split Layout::Tree into Tree::Live (TTY) and Tree::Event (non-TTY) with `Tree.for` factory ([#181](https://github.com/ahogappa/taski/pull/181))
+
+### Fixed
+- Add base64 as runtime dependency ([#182](https://github.com/ahogappa/taski/pull/182))
+- Use done_count instead of completed_count in completion display ([#179](https://github.com/ahogappa/taski/pull/179))
+- Pass skipped_count in Simple layout's render_final ([#179](https://github.com/ahogappa/taski/pull/179))
+- Show most recently started tasks first in simple progress display ([#178](https://github.com/ahogappa/taski/pull/178))
+
+## [0.9.1] - 2026-02-16
+
+### Changed
+- Replace raw arrays and hashes with FiberProtocol Data classes for typed protocol messages ([#175](https://github.com/ahogappa/taski/pull/175))
+- Add AST-guided start_dep speculative parallel execution for improved performance ([#175](https://github.com/ahogappa/taski/pull/175))
+- Add TaskProxy for lazy dependency resolution with unsafe proxy usage detection ([#175](https://github.com/ahogappa/taski/pull/175))
+- Remove static-graph-based task scheduling from Executor in favor of Fiber pull model ([#176](https://github.com/ahogappa/taski/pull/176))
+- Replace inline `Class.new(Taski::Task)` with named fixture classes in tests ([#174](https://github.com/ahogappa/taski/pull/174))
+- Add custom export methods section to README ([#172](https://github.com/ahogappa/taski/pull/172))
+
+### Fixed
+- Fix data race on `@next_thread_index` in enqueue/enqueue_clean ([#175](https://github.com/ahogappa/taski/pull/175))
+
 ## [0.9.0] - 2026-02-08
 
 ### Added

data/README.md

@@ -15,6 +15,7 @@
 - **Exports API**: Simple value sharing between tasks
 - **Real-time Progress**: Visual feedback with parallel task progress display
 - **Fiber-Based Execution**: Lightweight Fiber-based dependency resolution for efficient parallel execution
+- **Lazy Dependency Resolution**: Dependencies return lightweight proxies that defer resolution until the value is actually used, enabling better parallelism
 
 ## Quick Start
 
@@ -77,6 +78,46 @@ class Server < Taski::Task
 end
 ```
 
+### Custom Export Methods
+
+By default, `exports` generates a reader that returns the instance variable (e.g., `exports :value` reads `@value`). You can override this by defining your own instance method with the same name:
+
+**Fixed values** — no computation needed in `run`:
+
+```ruby
+class Config < Taski::Task
+  exports :timeout
+
+  def timeout
+    30
+  end
+
+  def run; end
+end
+
+Config.timeout  # => 30
+```
+
+**Shared logic between `run` and `clean`** — the method works as both an export and a regular instance method:
+
+```ruby
+class DatabaseSetup < Taski::Task
+  exports :connection
+
+  def connection
+    @connection ||= Database.connect
+  end
+
+  def run
+    connection.setup_schema
+  end
+
+  def clean
+    connection.close
+  end
+end
+```
+
 ### Conditional Logic - Runtime Selection
 
 Use `if` statements to switch behavior based on environment:
@@ -230,6 +271,8 @@ RandomTask.value  # => 99 (different value - fresh execution)
 DoubleConsumer.run  # RandomTask runs once, both accesses get same value
 ```
 
+When a task accesses a dependency (e.g., `SomeDep.value`), the result may be a lightweight proxy. The actual resolution is deferred until the value is used, allowing independent dependencies to execute in parallel transparently. This is automatic and requires no changes to your task code. Dependencies used in conditions or as arguments are automatically resolved synchronously for safety.
+
 ### Error Handling
 
 When a task fails, Taski wraps the error with task-specific context. Each task class automatically gets a `::Error` subclass for targeted rescue:

data/docs/GUIDE.md

@@ -7,6 +7,7 @@ This guide provides detailed documentation beyond the basics covered in the READ
 - [Error Handling](#error-handling)
 - [Lifecycle Management](#lifecycle-management)
 - [Progress Display](#progress-display)
+- [Lazy Dependency Resolution](#lazy-dependency-resolution)
 - [Debugging](#debugging)
 
 ---
@@ -354,6 +355,44 @@ ruby build.rb > build.log 2>&1
 
 ---
 
+## Lazy Dependency Resolution
+
+### How It Works
+
+When a task accesses a dependency's exported value (e.g., `DepTask.value`), Taski may return a lightweight **proxy object** instead of the actual value. This proxy defers dependency resolution until you call a method on it, at which point it transparently resolves the real value and forwards the method call.
+
+```ruby
+class FetchData < Taski::Task
+  exports :data
+  def run
+    @data = expensive_api_call
+  end
+end
+
+class ProcessData < Taski::Task
+  exports :result
+  def run
+    raw = FetchData.data       # May return a proxy (no blocking yet)
+    setup_environment          # Task continues while FetchData runs
+    @result = raw.transform    # Proxy resolves here — blocks if needed
+  end
+end
+```
+
+From the user's perspective, the proxy is completely transparent — it behaves exactly like the real value.
+
+### Why It Matters
+
+Proxy-based resolution enables better parallelism. A task can continue executing setup logic while its dependencies are still running, only blocking when the dependency value is actually used. This can significantly reduce total execution time when tasks have independent setup work before they need their dependencies.
+
+### Automatic Safety
+
+Taski uses static analysis (Prism AST parsing) to determine when proxy resolution is safe. Dependencies used in positions where the proxy could cause issues — such as conditions (`if dep_value`), method arguments, or other contexts where truthiness or identity matters — are automatically resolved synchronously instead of returning a proxy.
+
+You do not need to think about this in normal usage. The static analyzer examines your task's `run` method and only enables proxy resolution for dependency accesses that are confirmed safe (e.g., simple assignments like `x = Dep.value` followed by method calls on `x`).
+
+---
+
 ## Debugging
 
 ### Structured Logging
@@ -390,4 +429,4 @@ end
 
 **Static Analysis Requirements**
 
-Tasks must be defined in source files (not dynamically with `Class.new`) because static analysis uses Prism AST parsing which requires actual source files.
+Tasks must be defined in source files (not dynamically with `Class.new`) because static analysis uses Prism AST parsing which requires actual source files. Static analysis is used for dependency tree visualization, circular dependency detection, and optimizing dependency resolution (determining when lazy proxy resolution is safe vs. when synchronous resolution is required).

data/lib/taski/execution/executor.rb

@@ -5,8 +5,12 @@ require "etc"
 module Taski
   module Execution
     # Orchestrates run (Fiber-based) and clean (direct) phases of task execution.
-    # Delegates to Scheduler (dependency order), WorkerPool (worker threads),
-    # and ExecutionFacade (observer notifications).
+    # Delegates to Scheduler (state tracking / advisory proposals),
+    # WorkerPool (worker threads), and ExecutionFacade (observer notifications).
+    #
+    # Task execution is driven by the Fiber pull model — tasks start only when
+    # requested via Fiber.yield FiberProtocol::NeedDep. Scheduler may propose tasks,
+    # but Executor/Wrapper can reject proposals not backed by actual Fiber requests.
     class Executor
       class << self
         def execute(root_task_class, registry:, execution_facade:)
@@ -43,8 +47,6 @@ module Taski
 
           @worker_pool.start
 
-          pre_start_leaf_tasks
-
           enqueue_root_if_needed(root_task_class)
 
           run_main_loop(root_task_class)
@@ -83,10 +85,6 @@ module Taski
 
       # Run phase
 
-      def pre_start_leaf_tasks
-        @scheduler.next_ready_tasks.each { |task_class| enqueue_for_execution(task_class) }
-      end
-
       def enqueue_root_if_needed(root_task_class)
         return unless @scheduler.pending?(root_task_class)
 
@@ -98,24 +96,30 @@ module Taski
           break if @registry.abort_requested? && !@scheduler.running_tasks?
 
           event = @completion_queue.pop
-          handle_completion(event)
+          case event
+          in FiberProtocol::StartDepNotify => notify
+            @scheduler.mark_running(notify.task_class)
+          in FiberProtocol::TaskCompleted | FiberProtocol::TaskFailed
+            handle_completion(event)
+          else
+            raise "[BUG] unexpected completion queue event: #{event.inspect}"
+          end
         end
       end
 
       def handle_completion(event)
-        task_class = event[:task_class]
+        task_class = event.task_class
         Taski::Logging.debug(Taski::Logging::Events::EXECUTOR_TASK_COMPLETED, task: task_class.name)
 
-        if event[:error]
-          @scheduler.mark_failed(task_class)
-          log_error_detail(task_class, event[:error])
-          skip_pending_dependents(task_class)
-        else
+        case event
+        in FiberProtocol::TaskFailed => failed
+          @scheduler.mark_failed(failed.task_class)
+          log_error_detail(failed.task_class, failed.error)
+          skip_pending_dependents(failed.task_class)
+        in FiberProtocol::TaskCompleted
           @scheduler.mark_completed(task_class)
-        end
-
-        @scheduler.next_ready_tasks.each do |ready_class|
-          enqueue_for_execution(ready_class)
+        else
+          raise "[BUG] unexpected run completion event: #{event.inspect}"
         end
       end
 
@@ -192,13 +196,18 @@ module Taski
       end
 
       def handle_clean_completion(event)
-        task_class = event[:task_class]
+        task_class = event.task_class
         Taski::Logging.debug(Taski::Logging::Events::EXECUTOR_CLEAN_COMPLETED, task: task_class.name)
-        if event[:error]
-          @scheduler.mark_clean_failed(task_class)
-        else
+
+        case event
+        in FiberProtocol::CleanFailed => failed
+          @scheduler.mark_clean_failed(failed.task_class)
+        in FiberProtocol::CleanCompleted
           @scheduler.mark_clean_completed(task_class)
+        else
+          raise "[BUG] unexpected clean completion event: #{event.inspect}"
         end
+
         enqueue_ready_clean_tasks
       end
 

data/lib/taski/execution/fiber_protocol.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Taski
+  module Execution
+    module FiberProtocol
+      # === Fiber yields (task -> worker pool) ===
+      StartDep = Data.define(:task_class)
+      NeedDep = Data.define(:task_class, :method)
+
+      # === Fiber resume error signal (worker pool -> task) ===
+      DepError = Data.define(:error)
+
+      # === Completion queue events (worker pool -> executor) ===
+      StartDepNotify = Data.define(:task_class)
+      TaskCompleted = Data.define(:task_class, :wrapper)
+      TaskFailed = Data.define(:task_class, :wrapper, :error)
+      CleanCompleted = Data.define(:task_class, :wrapper)
+      CleanFailed = Data.define(:task_class, :wrapper, :error)
+
+      # === Worker thread commands (pool -> worker thread) ===
+      Execute = Data.define(:task_class, :wrapper)
+      ExecuteClean = Data.define(:task_class, :wrapper)
+      Resume = Data.define(:fiber, :value)
+      ResumeError = Data.define(:fiber, :error)
+    end
+  end
+end

data/lib/taski/execution/task_wrapper.rb

@@ -297,13 +297,13 @@ module Taski
       def notify_fiber_waiters_completed(waiters)
         waiters.each do |thread_queue, fiber, method|
           value = @task.public_send(method)
-          thread_queue.push([:resume, fiber, value])
+          thread_queue.push(FiberProtocol::Resume.new(fiber, value))
         end
       end
 
       def notify_fiber_waiters_failed(waiters, error)
         waiters.each do |thread_queue, fiber, _method|
-          thread_queue.push([:resume_error, fiber, error])
+          thread_queue.push(FiberProtocol::ResumeError.new(fiber, error))
         end
       end
     end

data/lib/taski/execution/worker_pool.rb

@@ -10,19 +10,22 @@ module Taski
 
     # WorkerPool manages N threads, each with its own command Queue.
     # Tasks are executed within Fibers on worker threads.
-    # When a Fiber yields [:need_dep, dep_class, method], the worker
-    # resolves the dependency via TaskWrapper#request_value:
     #
-    # - :completed → resume Fiber immediately with the value
-    # - :wait → park the Fiber (it will be resumed later via the thread's queue)
-    # - :start → start the dependency as a nested Fiber on the same thread
+    # Fiber protocol supports two yield types (FiberProtocol Data classes):
+    # - StartDep(task_class)          → non-blocking. Starts dep on another
+    #   thread and resumes the Fiber immediately. Used for speculative prestart.
+    # - NeedDep(task_class, method)   → blocking. Resolves dependency via
+    #   TaskWrapper#request_value:
+    #   - :completed → resume Fiber immediately with the value
+    #   - :wait → park the Fiber (it will be resumed later via the thread's queue)
+    #   - :start → start the dependency as a nested Fiber on the same thread
     #
-    # Worker threads process these commands:
-    # - [:execute, task_class, wrapper]       → create and drive a new Fiber
-    # - [:execute_clean, task_class, wrapper] → run clean directly (no Fiber)
-    # - [:resume, fiber, value]               → resume a parked Fiber with a value
-    # - [:resume_error, fiber, error]         → resume a parked Fiber with an error
-    # - :shutdown                             → exit the worker loop
+    # Worker threads process these commands (FiberProtocol Data classes):
+    # - Execute(task_class, wrapper)       → create and drive a new Fiber
+    # - ExecuteClean(task_class, wrapper)  → run clean directly (no Fiber)
+    # - Resume(fiber, value)               → resume a parked Fiber with a value
+    # - ResumeError(fiber, error)          → resume a parked Fiber with an error
+    # - :shutdown                          → exit the worker loop
     class WorkerPool
       attr_reader :worker_count
 
@@ -38,6 +41,7 @@ module Taski
         @fiber_contexts = {}
         @task_start_times_mutex = Mutex.new
         @task_start_times = {}
+        @enqueue_mutex = Mutex.new
       end
 
       def start
@@ -52,17 +56,21 @@ module Taski
 
       # Round-robins across worker threads.
       def enqueue(task_class, wrapper)
-        queue = @thread_queues[@next_thread_index % @worker_count]
-        @next_thread_index += 1
-        queue.push([:execute, task_class, wrapper])
-        Taski::Logging.debug(Taski::Logging::Events::WORKER_POOL_ENQUEUED, task: task_class.name, thread_index: (@next_thread_index - 1) % @worker_count)
+        @enqueue_mutex.synchronize do
+          queue = @thread_queues[@next_thread_index % @worker_count]
+          @next_thread_index += 1
+          queue.push(FiberProtocol::Execute.new(task_class, wrapper))
+          Taski::Logging.debug(Taski::Logging::Events::WORKER_POOL_ENQUEUED, task: task_class.name, thread_index: (@next_thread_index - 1) % @worker_count)
+        end
       end
 
       # Clean tasks run directly without Fiber wrapping.
       def enqueue_clean(task_class, wrapper)
-        queue = @thread_queues[@next_thread_index % @worker_count]
-        @next_thread_index += 1
-        queue.push([:execute_clean, task_class, wrapper])
+        @enqueue_mutex.synchronize do
+          queue = @thread_queues[@next_thread_index % @worker_count]
+          @next_thread_index += 1
+          queue.push(FiberProtocol::ExecuteClean.new(task_class, wrapper))
+        end
       end
 
       def shutdown
@@ -77,19 +85,17 @@ module Taski
           cmd = queue.pop
           break if cmd == :shutdown
 
-          case cmd[0]
-          when :execute
-            _, task_class, wrapper = cmd
-            drive_fiber(task_class, wrapper, queue)
-          when :resume
-            _, fiber, value = cmd
-            resume_fiber(fiber, value, queue)
-          when :resume_error
-            _, fiber, error = cmd
-            resume_fiber_with_error(fiber, error, queue)
-          when :execute_clean
-            _, task_class, wrapper = cmd
-            execute_clean_task(task_class, wrapper)
+          case cmd
+          in FiberProtocol::Execute => exec
+            drive_fiber(exec.task_class, exec.wrapper, queue)
+          in FiberProtocol::Resume => res
+            resume_fiber(res.fiber, res.value, queue)
+          in FiberProtocol::ResumeError => err
+            resume_fiber_with_error(err.fiber, err.error, queue)
+          in FiberProtocol::ExecuteClean => clean
+            execute_clean_task(clean.task_class, clean.wrapper)
+          else
+            raise "[BUG] unexpected worker command: #{cmd.inspect}"
           end
         end
       end
@@ -99,9 +105,16 @@ module Taski
       def drive_fiber(task_class, wrapper, queue)
         return if @registry.abort_requested?
 
+        analysis = Taski::StaticAnalysis::StartDepAnalyzer.analyze(task_class)
         fiber = Fiber.new do
           setup_run_thread_locals
-          wrapper.task.run
+          Thread.current[:taski_start_deps] = analysis.start_deps
+          (analysis.start_deps | analysis.sync_deps).each { |dep_class| Fiber.yield(FiberProtocol::StartDep.new(dep_class)) }
+          run_result = wrapper.task.run
+          resolve_proxy_exports(wrapper)
+          run_result
+        ensure
+          Thread.current[:taski_start_deps] = nil
         end
 
         now = Time.now
@@ -120,12 +133,16 @@ module Taski
         result = fiber.resume(resume_value)
 
         while fiber.alive?
-          if result.is_a?(Array) && result[0] == :need_dep
-            _, dep_class, method = result
-            handle_dependency(dep_class, method, fiber, task_class, wrapper, queue)
+          case result
+          in FiberProtocol::StartDep => start_dep
+            handle_start_dep(start_dep.task_class)
+            result = fiber.resume
+            next
+          in FiberProtocol::NeedDep => need_dep
+            handle_dependency(need_dep.task_class, need_dep.method, fiber, task_class, wrapper, queue)
             return # Fiber is either continuing or parked
           else
-            break
+            break # task.run returned a non-protocol value (normal completion)
           end
         end
 
@@ -142,12 +159,13 @@ module Taski
         when :completed
           drive_fiber_loop(fiber, task_class, wrapper, queue, status[1])
         when :failed
-          drive_fiber_loop(fiber, task_class, wrapper, queue, [:_taski_error, status[1]])
+          drive_fiber_loop(fiber, task_class, wrapper, queue, FiberProtocol::DepError.new(status[1]))
         when :wait
           store_fiber_context(fiber, task_class, wrapper)
         when :start
           store_fiber_context(fiber, task_class, wrapper)
-          start_dependency(dep_class, dep_wrapper, queue)
+          # dep_wrapper is already RUNNING (set atomically by request_value)
+          drive_fiber(dep_class, dep_wrapper, queue)
         end
       end
 
@@ -155,29 +173,52 @@ module Taski
       # Restores fiber context before resuming since teardown_thread_locals
       # cleared thread-local state when the fiber was parked.
       def resume_fiber(fiber, value, queue)
-        context = get_fiber_context(fiber)
-        return unless context
-
-        task_class, wrapper = context
-        setup_run_thread_locals
-        start_output_capture(task_class)
-        drive_fiber_loop(fiber, task_class, wrapper, queue, value)
+        resume_fiber_with_value(fiber, value, queue)
       end
 
       def resume_fiber_with_error(fiber, error, queue)
+        resume_fiber_with_value(fiber, FiberProtocol::DepError.new(error), queue)
+      end
+
+      def resume_fiber_with_value(fiber, resume_value, queue)
         context = get_fiber_context(fiber)
         return unless context
 
         task_class, wrapper = context
         setup_run_thread_locals
         start_output_capture(task_class)
-        drive_fiber_loop(fiber, task_class, wrapper, queue, [:_taski_error, error])
+        drive_fiber_loop(fiber, task_class, wrapper, queue, resume_value)
       end
 
-      # Start a dependency task as a new Fiber on this thread.
-      # The wrapper is already RUNNING (set atomically by request_value).
-      def start_dependency(dep_class, dep_wrapper, queue)
-        drive_fiber(dep_class, dep_wrapper, queue)
+      # Handle :start_dep — speculatively start a dependency on another thread.
+      # Non-blocking: the calling Fiber is resumed immediately after enqueueing.
+      # Uses mark_running to prevent duplicate starts.
+      def handle_start_dep(dep_class)
+        dep_wrapper = @registry.create_wrapper(dep_class, execution_facade: @execution_facade)
+        return unless dep_wrapper.mark_running
+
+        # Notify Executor so Scheduler can track the running state.
+        # Must be pushed before the execute command to guarantee ordering.
+        @completion_queue.push(FiberProtocol::StartDepNotify.new(dep_class))
+
+        @enqueue_mutex.synchronize do
+          target_queue = @thread_queues[@next_thread_index % @worker_count]
+          @next_thread_index += 1
+          target_queue.push(FiberProtocol::Execute.new(dep_class, dep_wrapper))
+        end
+      end
+
+      # Resolve any TaskProxy instances stored in exported ivars.
+      # After task.run, proxies assigned to @value etc. must be resolved
+      # while still inside the Fiber context so Fiber.yield works.
+      def resolve_proxy_exports(wrapper)
+        wrapper.task.class.exported_methods.each do |method|
+          ivar = :"@#{method}"
+          val = wrapper.task.instance_variable_get(ivar)
+          next unless val.respond_to?(:__taski_proxy_resolve__)
+          resolved = val.__taski_proxy_resolve__
+          wrapper.task.instance_variable_set(ivar, resolved)
+        end
       end
 
       def complete_task(task_class, wrapper, result)
@@ -185,7 +226,7 @@ module Taski
         duration = task_duration_ms(task_class)
         Taski::Logging.info(Taski::Logging::Events::TASK_COMPLETED, task: task_class.name, duration_ms: duration)
         wrapper.mark_completed(result)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper})
+        @completion_queue.push(FiberProtocol::TaskCompleted.new(task_class, wrapper))
         teardown_thread_locals
       end
 
@@ -195,7 +236,7 @@ module Taski
         duration = task_duration_ms(task_class)
         Taski::Logging.error(Taski::Logging::Events::TASK_FAILED, task: task_class.name, duration_ms: duration)
         wrapper.mark_failed(error)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper, error: error})
+        @completion_queue.push(FiberProtocol::TaskFailed.new(task_class, wrapper, error))
         teardown_thread_locals
       end
 
@@ -213,13 +254,13 @@ module Taski
         duration = ((Time.now - clean_start) * 1000).round(1)
         Taski::Logging.debug(Taski::Logging::Events::TASK_CLEAN_COMPLETED, task: task_class.name, duration_ms: duration)
         wrapper.mark_clean_completed(result)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper, clean: true})
+        @completion_queue.push(FiberProtocol::CleanCompleted.new(task_class, wrapper))
       rescue => e
         @registry.request_abort! if e.is_a?(Taski::TaskAbortException)
         duration = ((Time.now - clean_start) * 1000).round(1) if clean_start
         Taski::Logging.warn(Taski::Logging::Events::TASK_CLEAN_FAILED, task: task_class.name, duration_ms: duration)
         wrapper.mark_clean_failed(e)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper, error: e, clean: true})
+        @completion_queue.push(FiberProtocol::CleanFailed.new(task_class, wrapper, e))
       ensure
         stop_output_capture
         teardown_thread_locals

data/lib/taski/progress/config.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Taski
+  module Progress
+    # Configuration for progress display.
+    # Holds class references for Layout and Theme, and builds display instances lazily.
+    #
+    # @example
+    #   Taski.progress.layout = Taski::Progress::Layout::Tree
+    #   Taski.progress.theme = Taski::Progress::Theme::Detail
+    class Config
+      attr_reader :layout, :theme, :output
+
+      # @param on_invalidate [Proc, nil] Called when config changes (to clear external caches)
+      def initialize(&on_invalidate)
+        @layout = nil
+        @theme = nil
+        @output = nil
+        @cached_display = nil
+        @on_invalidate = on_invalidate
+      end
+
+      def layout=(klass)
+        validate_layout!(klass) if klass
+        @layout = klass
+        invalidate!
+      end
+
+      def theme=(klass)
+        validate_theme!(klass) if klass
+        @theme = klass
+        invalidate!
+      end
+
+      def output=(io)
+        @output = io
+        invalidate!
+      end
+
+      # Build a Layout instance from the current config.
+      # Returns a cached instance if config hasn't changed.
+      def build
+        @cached_display ||= build_display
+      end
+
+      # Reset all settings to defaults.
+      def reset
+        @layout = nil
+        @theme = nil
+        @output = nil
+        invalidate!
+      end
+
+      private
+
+      def invalidate!
+        @cached_display = nil
+        @on_invalidate&.call
+      end
+
+      def build_display
+        layout_ref = @layout || Layout::Simple
+        args = {}
+        args[:theme] = @theme.new if @theme
+        args[:output] = @output if @output
+
+        if layout_ref.respond_to?(:for)
+          layout_ref.for(**args)
+        else
+          layout_ref.new(**args)
+        end
+      end
+
+      def validate_layout!(klass)
+        # Accept a Class that inherits from Base, or a Module with .for factory
+        valid = (klass.is_a?(Class) && klass <= Layout::Base) ||
+          (klass.is_a?(Module) && klass.respond_to?(:for))
+        unless valid
+          raise ArgumentError, "layout must be a Layout::Base subclass or a module with .for, got #{klass.inspect}"
+        end
+      end
+
+      def validate_theme!(klass)
+        unless klass.is_a?(Class) && klass <= Theme::Base
+          raise ArgumentError, "theme must be a subclass of Taski::Progress::Theme::Base, got #{klass.inspect}"
+        end
+      end
+    end
+  end
+end