letsdo 0.3.0 → 0.5.0

data/lib/letsdo/cli/builder_metrics.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # Session recorder and metrics-file wiring for Letsdo::CLI::Builder.
+    # Kept in its own module so BuilderAssembly stays within the module-length
+    # limit.
+    module BuilderMetrics
+      # Returns the IO for the LETSDO_METRICS_FILE, or nil if unset or
+      # unwritable. Emits a warning to stderr on invalid path.
+      def metrics_io
+        path = @env['LETSDO_METRICS_FILE']
+        return nil if path.nil? || path.empty?
+
+        File.open(path, 'a', encoding: 'UTF-8')
+      rescue SystemCallError, IOError => e
+        @stderr.puts("letsdo: cannot open metrics file #{path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      def build_recorder(name)
+        Letsdo::SessionRecorder.new(name: name, handle: assignee_handle(name),
+                                    metrics_io: metrics_io)
+      end
+
+      def run_plain(name, recorder)
+        streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
+        agent = agent_for(name, streamer)
+        pause_gate = Control::PauseGate.new
+        reader = plain_control_reader(agent, pause_gate)
+        agent_loop(name, streamer, agent: agent, stderr: @stderr, metrics: recorder,
+                                   pause_gate: pause_gate).run
+      ensure
+        reader&.stop
+        finish_session(name, recorder)
+      end
+
+      # Plain-mode control (TASK-75): with a terminal stdin the reader maps
+      # p/q to the same actions as the TUI keys — the shared PauseGate plus
+      # the current backend (nil between runs is a no-op). Reader#start is a
+      # no-op when stdin is not a terminal (pipes, CI), so stopping stays
+      # signal-only there. The reader writes nothing, so the plain stream
+      # stays byte-identical.
+      def plain_control_reader(agent, pause_gate)
+        Control::Reader.new(input: @stdin, pause_gate: pause_gate,
+                            runner: -> { agent.backend }).tap(&:start)
+      end
+
+      # One shared stop path for plain and TUI mode (TASK-69/TASK-70): close
+      # the recorder, optionally write per-task elapsed back into the task
+      # records, then print the summary. Write-back failures are counted and
+      # reported, never raised.
+      def finish_session(name, recorder)
+        recorder.session_stop
+        not_written = task_time_comments(name, recorder)
+        @stderr.puts(recorder.summary_line)
+        @stderr.puts(comment_failure_line(not_written)) if not_written.positive?
+      end
+
+      # Opt-in (LETSDO_TASK_TIME_COMMENT=1): re-query the provider once at
+      # stop and comment the elapsed time on runs whose task is gone. Off by
+      # default — no subprocess, no task file mutation.
+      def task_time_comments(name, recorder)
+        return 0 unless @config.task_time_comment?
+
+        writeback = TaskTimeWriteback.new(command: backlog_command, cwd: @root,
+                                          env: ENV.to_h.merge(@env), stderr: @stderr)
+        writeback.call(recorder.summary.runs, final_open_tasks(name))
+      end
+
+      def final_open_tasks(name)
+        provider_for(assignee_handle(name)).call
+      end
+
+      def comment_failure_line(count)
+        "letsdo: #{count} #{count == 1 ? 'comment' : 'comments'} not written"
+      end
+    end
+  end
+end

data/lib/letsdo/cli/doctor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # `letsdo doctor` dispatch (TASK-71): builds the environment self-check
+    # from the same Letsdo::Config the rest of the CLI uses and returns its
+    # exit code. `doctor` is a reserved name -- it never launches an agent.
+    module CLIDoctor
+      private
+
+      def doctor_command
+        Doctor.new(config: Config.new(env: @env), stdout: @stdout, stdin: @stdin).run
+      end
+    end
+  end
+end

data/lib/letsdo/cli.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'shellwords'
-require_relative 'cli/launch'
 require_relative 'cli/init'
+require_relative 'cli/doctor'
+require_relative 'cli/builder'
 
 module Letsdo
   # Command-line argument parsing and running an agent orchestrator loop.
@@ -11,6 +11,8 @@ module Letsdo
   #   letsdo                       — usage and agent list, exit code 1;
   #   letsdo --version             — version, exit code 0;
   #   letsdo --help                — usage, exit code 0;
+  #   letsdo doctor                — environment self-check, exit 0 unless a
+  #                                  check FAILs (then 1); `doctor` is reserved;
   #   letsdo <name>                — run the <name> agent in the orchestrator
   #                                    loop until SIGINT/SIGTERM;
   #   letsdo <name> (no prompt)    — same, but on the built-in default prompt;
@@ -21,12 +23,11 @@ module Letsdo
   #   letsdo --init <name>         — same, flag-first form;
   #   letsdo <unknown option>      — "letsdo: unknown option: X" + usage, exit 1.
   class CLI
-    include CLILaunch
     include CLIInit
+    include CLIDoctor
 
     USAGE = 'Usage: letsdo <agent_name>'
     AGENTS_HEADER = 'Available agents:'
-    DEFAULT_WAIT_SECONDS = 10.0
 
     def self.run(argv, **opts)
       new(env: opts.fetch(:env, ENV), stdout: opts.fetch(:stdout, $stdout),
@@ -35,12 +36,13 @@ module Letsdo
     end
 
     def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
-      @env = env
       @stdout = stdout
       @stderr = stderr
+      @env = env
       @stdin = stdin
-      @sleeper = sleeper
-      @root = env.fetch('LETSDO_ROOT', Dir.pwd)
+      @root = Config.new(env: env).root
+      @builder = Builder.new(env: env, stdout: stdout, stderr: stderr,
+                             stdin: stdin, sleeper: sleeper)
     end
 
     def run(argv)
@@ -48,6 +50,7 @@ module Letsdo
       return print_version if version_flag?(arg)
       return print_help if help_flag?(arg)
       return usage_error if arg.nil?
+      return doctor_command if arg == 'doctor'
       return init_command(argv) if argv.include?('--init')
       return unknown_option(arg) if arg.start_with?('-')
 
@@ -56,6 +59,13 @@ module Letsdo
 
     private
 
+    def run_agent(arg)
+      @builder.run(arg)
+    rescue Letsdo::BackendUnavailableError => e
+      @stderr.puts("letsdo: #{e.message}")
+      2
+    end
+
     def version_flag?(arg)
       ['--version', '-v'].include?(arg)
     end
@@ -85,47 +95,6 @@ module Letsdo
       1
     end
 
-    def run_agent(name)
-      store = PromptStore.new(root: @root)
-      announce_default_prompt(name, store) if store.read(name).nil?
-      tui? ? run_agent_tui(name) : run_agent_plain(name)
-    end
-
-    # One-time fallback notification (before the first loop message): names
-    # the exact path checked and the placement hint. The agent still starts
-    # — Letsdo::Agent falls back to the built-in default prompt itself.
-    def announce_default_prompt(name, store)
-      @stderr.puts("letsdo: no prompt for #{name} at #{store.agent_path(name)}")
-      @stderr.puts("letsdo: using the built-in default prompt (create a prompt file with 'letsdo #{name} --init')")
-    end
-
-    def tui?
-      @stdout.tty? && @stdin.tty? && @env['TERM'].to_s != 'dumb'
-    end
-
-    def assignee_handle(name)
-      env_handle = @env['AGENT_ASSIGNEE_HANDLE']
-      env_handle && !env_handle.strip.empty? ? env_handle : "@#{name}"
-    end
-
-    def backlog_command
-      @env.fetch('LETSDO_BACKLOG_COMMAND', 'backlog')
-    end
-
-    def wait_seconds
-      value = @env['LETSDO_WAIT_SECONDS'].to_s.strip
-      value = @env['AGENT_WAIT_SECONDS'].to_s.strip if value.empty?
-      return DEFAULT_WAIT_SECONDS if value.empty?
-
-      Float(value)
-    rescue ArgumentError, TypeError
-      DEFAULT_WAIT_SECONDS
-    end
-
-    def pi_command
-      @env.fetch('LETSDO_PI_COMMAND', PiRunner::COMMAND)
-    end
-
     def print_usage(stream)
       stream.puts(USAGE)
       print_agents
@@ -135,13 +104,5 @@ module Letsdo
       @stdout.puts(AGENTS_HEADER)
       PromptStore.new(root: @root).list.each { |name| @stdout.puts("  #{name}") }
     end
-
-    def parse_pi_flags
-      value = @env['LETSDO_PI_FLAGS'].to_s
-      value = @env['AGENT_PI_FLAGS'].to_s if value.strip.empty?
-      return [] if value.strip.empty?
-
-      Shellwords.split(value)
-    end
   end
 end

data/lib/letsdo/config.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Letsdo
+  # The single place where every LETSDO_*/AGENT_* environment variable is
+  # read, with exactly the defaults and precedence the CLI, the Pi backend
+  # and AgentLoop used to apply inline. Giving env policy one home makes it
+  # testable in one place and gives future knobs (provider/backend
+  # selection) a single spot to add a variable.
+  #
+  # The env hash is injectable for tests and defaults to the process ENV.
+  class Config
+    DEFAULT_WAIT_SECONDS = 10.0
+    DEFAULT_PI_COMMAND = 'pi'
+    DEFAULT_BACKLOG_COMMAND = 'backlog'
+    DEFAULT_PROVIDER = 'backlog'
+    DEFAULT_BACKEND = 'pi'
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_CAP = 300.0
+
+    def initialize(env: ENV)
+      @env = env
+    end
+
+    # Project root with agents/ (and where the backlog CLI finds backlog/).
+    def root
+      @env.fetch('LETSDO_ROOT', Dir.pwd)
+    end
+
+    # Extra pi flags, split on whitespace. LETSDO_PI_FLAGS wins; when empty,
+    # AGENT_PI_FLAGS is the fallback (bin/agent-loop compatibility).
+    def pi_flags
+      value = @env['LETSDO_PI_FLAGS'].to_s
+      value = @env['AGENT_PI_FLAGS'].to_s if value.strip.empty?
+      return [] if value.strip.empty?
+
+      Shellwords.split(value)
+    end
+
+    # The agent's backlog assignee handle. Default: @<name> (handle = name);
+    # a blank override also falls back to the derived handle.
+    def assignee_handle(name)
+      handle = @env['AGENT_ASSIGNEE_HANDLE']
+      handle && !handle.strip.empty? ? handle : "@#{name}"
+    end
+
+    # Retry interval when no tasks are open. LETSDO_WAIT_SECONDS wins, then
+    # AGENT_WAIT_SECONDS; an invalid value falls back to the default.
+    def wait_seconds
+      value = @env['LETSDO_WAIT_SECONDS'].to_s.strip
+      value = @env['AGENT_WAIT_SECONDS'].to_s.strip if value.empty?
+      return DEFAULT_WAIT_SECONDS if value.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_WAIT_SECONDS
+    end
+
+    # The pi command used to run agents (same literal as Backends::Pi::COMMAND).
+    def pi_command
+      @env.fetch('LETSDO_PI_COMMAND', DEFAULT_PI_COMMAND)
+    end
+
+    # The Backlog.md CLI used as the task provider.
+    def backlog_command
+      @env.fetch('LETSDO_BACKLOG_COMMAND', DEFAULT_BACKLOG_COMMAND)
+    end
+
+    # Executable search path, used by `letsdo doctor` to resolve the
+    # configured command names. It lives here so doctor code never reads
+    # ENV directly (TASK-71).
+    def path
+      @env.fetch('PATH', '')
+    end
+
+    # The task provider name. Reads LETSDO_PROVIDER with default 'backlog'.
+    # An empty value falls back to 'backlog'.
+    def provider
+      @env['LETSDO_PROVIDER'].to_s.strip.empty? ? DEFAULT_PROVIDER : @env['LETSDO_PROVIDER'].to_s.strip
+    end
+
+    # The AI backend name. Reads LETSDO_BACKEND with default 'pi'.
+    # An empty value falls back to 'pi'.
+    def backend
+      @env['LETSDO_BACKEND'].to_s.strip.empty? ? DEFAULT_BACKEND : @env['LETSDO_BACKEND'].to_s.strip
+    end
+
+    # Whether [letsdo] traces are enabled in the Pi backend and AgentLoop.
+    def debug?
+      @env['LETSDO_DEBUG'] == '1'
+    end
+
+    # Whether per-task elapsed is written back into the task record as a
+    # backlog comment at session stop (TASK-70). Opt-in: only the literal
+    # '1' enables it, so no task file is ever modified by default.
+    def task_time_comment?
+      @env['LETSDO_TASK_TIME_COMMENT'] == '1'
+    end
+
+    # Give-up after N consecutive failed runs of the same task in a session
+    # (default 3). Any invalid value falls back to the default.
+    def max_retries
+      value = @env['LETSDO_MAX_RETRIES'].to_s.strip
+      return DEFAULT_MAX_RETRIES if value.empty?
+
+      Integer(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_MAX_RETRIES
+    end
+
+    # Base backoff seconds for the first retry; doubles per failure.
+    # Default = LETSDO_WAIT_SECONDS (the loop poll interval). An invalid
+    # value falls back to that default.
+    def retry_base
+      value = @env['LETSDO_RETRY_BASE'].to_s.strip
+      value.empty? ? wait_seconds : Float(value)
+    rescue ArgumentError, TypeError
+      wait_seconds
+    end
+
+    # Maximum backoff seconds (default 300). An invalid value falls back
+    # to the default.
+    def retry_cap
+      value = @env['LETSDO_RETRY_CAP'].to_s.strip
+      return DEFAULT_RETRY_CAP if value.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_RETRY_CAP
+    end
+  end
+end

data/lib/letsdo/control/reader.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Control
+    # The plain-mode control reader (TASK-94): when letsdo runs in plain
+    # line-stream mode (stdout not a TTY) but stdin IS a terminal, a
+    # background thread reads Enter-terminated commands and maps them to
+    # the same actions as the TUI keys (TASK-67/74 control model):
+    #
+    #   p - toggle pause: on -> Control::PauseGate#pause plus the running
+    #       backend's SIGSTOP (a no-op when nothing runs), off -> resume;
+    #   q - clean stop: Thread.main.raise(Letsdo::Stopped), the exact
+    #       teardown path of SIGINT/SIGTERM and the TUI 'q'.
+    #
+    # The reader only starts for a terminal stdin: with a pipe or
+    # /dev/null it never reads a single byte, so a user's piped stdin is
+    # left untouched and stopping stays signal-only. It writes nothing
+    # (no echo, no escape codes, no partial output) and its thread exits
+    # quietly on EOF or a read error.
+    class Reader
+      # @param input [IO] the stdin stream to read lines from
+      # @param pause_gate [Letsdo::Control::PauseGate, nil] the between-runs
+      #        gate toggled by 'p'
+      # @param runner [#call, nil] callable returning the current backend
+      #        (answers pause/resume) or nil; mirrors the TUI wiring, so a
+      #        nil between runs is simply a no-op
+      # @param on_stop [#call, nil] stop action; defaults to raising
+      #        Letsdo::Stopped into the main thread (injected in tests)
+      # @param tty [Boolean, nil] overrides the input.tty? check (tests only)
+      def initialize(input:, pause_gate: nil, runner: nil, on_stop: nil, tty: nil)
+        @input = input
+        @pause_gate = pause_gate
+        @runner = runner
+        @on_stop = on_stop
+        @tty = tty
+        @paused = false
+        @thread = nil
+      end
+
+      # Whether the reader may run: stdin must be a terminal that can be
+      # read line by line, otherwise a pipe, /dev/null or CI stdin would be
+      # read from (and stolen from the user's pipe).
+      #
+      # @return [Boolean]
+      def available?
+        @tty.nil? ? terminal_input? : @tty
+      end
+
+      # Starts the background reader thread. A non-terminal stdin starts
+      # nothing at all.
+      #
+      # @return [Thread, nil] the reader thread, or nil when not a terminal
+      def start
+        return nil unless available?
+        return @thread if @thread
+
+        @thread = build_thread
+      end
+
+      # Waits for the reader thread so tests and shutdown can join it.
+      #
+      # @param timeout [Numeric, nil] seconds to wait, nil waits forever
+      # @return [Thread, nil]
+      def join(timeout = nil)
+        @thread&.join(timeout)
+      end
+
+      # Ends the reader: kills the background thread when it is still
+      # blocked on input, so no reader outlives the run that started it.
+      # Safe to call when it was never started (non-TTY stdin).
+      #
+      # @return [void]
+      def stop
+        thread = @thread
+        return unless thread
+
+        thread.kill
+        thread.join(1)
+        @thread = nil
+      end
+
+      private
+
+      def terminal_input?
+        @input.respond_to?(:tty?) && @input.tty? && @input.respond_to?(:gets)
+      end
+
+      def build_thread
+        Thread.new { read_loop }.tap { |thread| thread.report_on_exception = false }
+      end
+
+      # Reads Enter-terminated commands until EOF or a read error; never
+      # writes and never lets an error escape the thread.
+      def read_loop
+        while (line = @input.gets)
+          handle_command(line)
+        end
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      def handle_command(line)
+        case line.strip
+        when 'p' then toggle_pause
+        when 'q' then request_stop
+        end
+      end
+
+      def toggle_pause
+        @paused = !@paused
+        action = @paused ? :pause : :resume
+        invoke(@pause_gate, action)
+        invoke(current_runner, action)
+      end
+
+      def current_runner
+        @runner.respond_to?(:call) ? @runner.call : @runner
+      end
+
+      def invoke(target, action)
+        return unless target.respond_to?(action)
+
+        target.public_send(action)
+      end
+
+      def request_stop
+        (@on_stop || -> { Thread.main.raise(Letsdo::Stopped) }).call
+      end
+    end
+  end
+end

data/lib/letsdo/control.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+require_relative 'control/reader'
+
 module Letsdo
-  # Agent-control primitives shared by the TUI and the orchestrator loop
-  # (TASK-67 control model): pausing between runs.
+  # Agent-control primitives shared by the TUI, the plain-mode reader and
+  # the orchestrator loop (TASK-67 control model): pausing between runs
+  # (PauseGate) and the stdin control reader (Reader).
   module Control
     # A thread-safe pause flag polled by Letsdo::AgentLoop between runs.
     #
-    # Mid-run suspension is handled by Letsdo::PiRunner#pause (SIGSTOP to
+    # Mid-run suspension is handled by Letsdo::Backends::Pi#pause (SIGSTOP to
     # the pi group, kernel-level freeze). Between runs there is no pi to
     # stop, so the pause lives in this gate: while #paused? is true the
     # loop must not start a new run, and it waits until #resume.

data/lib/letsdo/doctor/checks.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class Doctor
+    # The individual environment checks behind `letsdo doctor` (TASK-71).
+    # Every check returns { status:, message:, hint: } where the hint is
+    # mandatory for FAIL/WARN so the report is always actionable. Kept in its
+    # own module so Letsdo::Doctor stays within the class-length limit.
+    module DoctorChecks
+      MINIMUM_RUBY = '3.3'
+
+      private
+
+      def checks
+        [ruby_check, pi_check, backlog_check, root_check,
+         agents_md_check, agents_dir_check, tty_check]
+      end
+
+      # ruby >= 3.3 is the gemspec floor: below it letsdo still reports the
+      # problem as a WARN instead of a hard failure.
+      def ruby_check
+        return result('OK', "ruby #{RUBY_VERSION} (>= #{MINIMUM_RUBY})") if ruby_supported?
+
+        result('WARN', "ruby #{RUBY_VERSION} (< #{MINIMUM_RUBY})",
+               "upgrade Ruby to #{MINIMUM_RUBY} or newer")
+      end
+
+      def ruby_supported?
+        Gem::Version.new(RUBY_VERSION) >= Gem::Version.new(MINIMUM_RUBY)
+      end
+
+      def pi_check
+        command_check('pi', @config.pi_command, 'LETSDO_PI_COMMAND')
+      end
+
+      def backlog_check
+        command_check('backlog', @config.backlog_command, 'LETSDO_BACKLOG_COMMAND')
+      end
+
+      def command_check(label, command, env_var)
+        return result('OK', "#{label} command found: #{command}") if command_available?(command)
+
+        result('FAIL', "#{label} command not found: #{command}",
+               "install #{label} or set #{env_var}")
+      end
+
+      # An absolute or relative command path is checked directly; a bare name
+      # is resolved against the PATH exposed by Letsdo::Config.
+      def command_available?(command)
+        return File.executable?(command) if command.include?(File::SEPARATOR)
+
+        @config.path.split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, command))
+        end
+      end
+
+      def root_check
+        return result('OK', "project root #{@config.root} has backlog/tasks/") if backlog_tasks?
+
+        result('FAIL', "project root #{@config.root} has no backlog/tasks/",
+               'run `backlog init` or set LETSDO_ROOT to a Backlog.md project')
+      end
+
+      def backlog_tasks?
+        File.directory?(File.join(@config.root, 'backlog', 'tasks'))
+      end
+
+      def agents_md_check
+        path = File.join(@config.root, 'AGENTS.md')
+        return result('OK', "AGENTS.md present at #{path}") if File.file?(path)
+
+        result('WARN', "no AGENTS.md at #{path}",
+               'add AGENTS.md with the project instructions for agents')
+      end
+
+      def agents_dir_check
+        dir = File.join(@config.root, 'agents')
+        prompts = File.directory?(dir) ? Dir.children(dir).length : 0
+        return result('OK', "agents/ present with #{prompts} prompt(s)") if prompts.positive?
+
+        result('WARN', "agents/ missing or empty at #{dir}",
+               'create an agent prompt with `letsdo <name> --init`')
+      end
+
+      # TUI engages only when stdout is a TTY (plus stdin/TERM, checked at
+      # launch); an INFO line tells the user which mode a run would pick.
+      def tty_check
+        return result('INFO', 'stdout is a TTY - TUI mode') if @stdout.tty?
+
+        result('INFO', 'stdout is not a TTY - plain mode')
+      end
+
+      def result(status, message, hint = nil)
+        { status: status, message: message, hint: hint }
+      end
+    end
+  end
+end

data/lib/letsdo/doctor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'doctor/checks'
+
+module Letsdo
+  # `letsdo doctor`: one line per environment check with a status tag and an
+  # actionable hint for every FAIL/WARN (TASK-71). Exits 0 when nothing
+  # FAILs and 1 otherwise, so it can gate scripts.
+  #
+  # Every input comes from Letsdo::Config (env policy) plus the injected
+  # streams, so the command is fully testable without touching process ENV.
+  class Doctor
+    include DoctorChecks
+
+    def initialize(config:, stdout:, stdin: $stdin)
+      @config = config
+      @stdout = stdout
+      @stdin = stdin
+    end
+
+    # Prints the report and returns the process exit code: 1 when at least
+    # one check FAILed, 0 otherwise.
+    def run
+      results = checks
+      results.each { |check| print_result(check) }
+      results.any? { |check| check[:status] == 'FAIL' } ? 1 : 0
+    end
+
+    private
+
+    def print_result(check)
+      line = "[#{tag(check[:status])}] #{check[:message]}"
+      line += " - #{check[:hint]}" if check[:hint]
+      @stdout.puts(line)
+    end
+
+    # All tags render six characters wide, so the columns line up.
+    def tag(status)
+      status == 'OK' ? ' OK ' : status
+    end
+  end
+end

data/lib/letsdo/duration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Shared rendering of a duration in seconds as "4m 12s" / "12s" / "0s".
+  #
+  # The stop summary (TASK-69) and the opt-in per-task elapsed write-back
+  # (TASK-70) both use this one formatter, so the number a session reports
+  # and the number written into the task record can never drift apart.
+  module Duration
+    module_function
+
+    # @param seconds [Numeric] duration in seconds (negative values clamp to 0)
+    # @return [String] human-readable duration, e.g. "4m 12s"
+    def format(seconds)
+      total = [seconds.to_f, 0.0].max.round
+      minutes, secs = total.divmod(60)
+      return '0s' if minutes.zero? && secs.zero?
+      return "#{secs}s" if minutes.zero?
+
+      "#{minutes}m #{secs}s"
+    end
+  end
+end

data/lib/letsdo/errors.rb

@@ -9,4 +9,11 @@ module Letsdo
   # cleanly. Not a StandardError — nothing rescues it accidentally.
   class Stopped < StandardError
   end
+
+  # Raised when the AI backend process cannot be started (missing or
+  # non-executable binary). This is a configuration error, not a loop
+  # problem: the CLI catches it, prints a clear message and exits 2 instead
+  # of dying with a Ruby backtrace.
+  class BackendUnavailableError < Error
+  end
 end