letsdo 0.4.0 → 0.5.0

data/lib/letsdo/task_time_writeback.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'duration'
+require_relative 'capture'
+
+module Letsdo
+  # Opt-in per-task elapsed write-back (TASK-70; design TASK-63 C3.3).
+  #
+  # At session stop the CLI hands this provider-agnostic writer the session's
+  # run records and one fresh provider snapshot. Every run that exited 0 and
+  # whose task is no longer open gets a backlog comment recording the elapsed
+  # time:
+  #
+  #   backlog task edit <id> --comment 'letsdo: completed in 4m 12s' \
+  #           --comment-author @letsdo
+  #
+  # A task that is still open after its run is skipped — calling it completed
+  # would be wrong. The write-back is batched at stop (all agent runs are
+  # dead), so it cannot race the agent's own closing edit on the file-based
+  # backlog CLI.
+  #
+  # Failures never abort the stop path: a missing/renamed task or a failing
+  # command warns once for that task and is counted, so the summary can report
+  # how many comments were not written.
+  class TaskTimeWriteback
+    COMMENT_AUTHOR = '@letsdo'
+    COMMENT_PREFIX = 'letsdo: completed in'
+
+    # @param command [String] backlog CLI command (LETSDO_BACKLOG_COMMAND)
+    # @param cwd [String] project root the CLI runs in
+    # @param env [Hash, nil] child environment (nil = inherit the process one)
+    # @param stderr [IO] warning sink
+    def initialize(command:, cwd:, env: nil, stderr: $stderr)
+      @command = command
+      @cwd = cwd
+      @env = env
+      @stderr = stderr
+    end
+
+    # Writes one comment per eligible run.
+    #
+    # @param runs [Array<SessionRecorder::Run>] the session's run records
+    # @param open_tasks [Array<Providers::Task>, nil] fresh provider snapshot;
+    #        nil when the backlog is unreadable (nothing can be verified)
+    # @return [Integer] number of comments not written
+    def call(runs, open_tasks)
+      return skip_unreadable(runs) if open_tasks.nil?
+
+      open_ids = open_tasks.map(&:id)
+      eligible(runs, open_ids).count { |run| !write(run) }
+    end
+
+    private
+
+    # Done runs whose task is absent from the fresh snapshot, one entry per
+    # task (a task retried after a late success cannot get two comments).
+    def eligible(runs, open_ids)
+      runs.select { |run| run.outcome == :done }
+          .reject { |run| open_ids.include?(run.task_id) }
+          .uniq(&:task_id)
+    end
+
+    # Without a readable snapshot we cannot tell closed from still-open, so we
+    # write nothing and warn once instead of guessing.
+    def skip_unreadable(runs)
+      return 0 if runs.none? { |run| run.outcome == :done }
+
+      @stderr.puts('letsdo: cannot write task time comments: backlog unreadable')
+      0
+    end
+
+    def write(run)
+      _out, err, status = capture(run)
+      return true if status.success?
+
+      warn_once(run, failure_message(err, status))
+      false
+    rescue StandardError => e
+      warn_once(run, e.message)
+      false
+    end
+
+    def capture(run)
+      args = @env ? [@env, *argv(run)] : argv(run)
+      Letsdo::Capture.new(*args, chdir: @cwd).run
+    end
+
+    def argv(run)
+      [*Shellwords.split(@command), 'task', 'edit', run.task_id,
+       '--comment', "#{COMMENT_PREFIX} #{Duration.format(run.elapsed_s)}",
+       '--comment-author', COMMENT_AUTHOR]
+    end
+
+    def warn_once(run, reason)
+      @stderr.puts("letsdo: cannot write task time comment for #{run.task_id}: #{reason}")
+    end
+
+    def failure_message(err, status)
+      message = err.to_s.strip
+      return message unless message.empty?
+
+      "backlog exited with code #{status.exitstatus}"
+    end
+  end
+end

data/lib/letsdo/tui/metrics.rb

@@ -60,8 +60,13 @@ module Letsdo
       end
 
       # An agent run finished: increments the done counter and clears the
-      # current-task state.
-      def run_finished
+      # current-task state. The exit code is accepted for compatibility
+      # with the session recorder (TASK-69) but is ignored here — the
+      # header does not classify outcomes.
+      #
+      # @param _exit_code [Integer, nil] the run exit code (ignored)
+      # @return [void]
+      def run_finished(_exit_code = nil)
         @mutex.synchronize do
           @done += 1
           @current_task = nil

data/lib/letsdo/tui/session/terminal.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Tui
+    # Terminal lifecycle for the TUI session: entering/leaving the alternate
+    # screen, the tmux window label around it, and the SIGWINCH handler.
+    # Extracted from Session so the class stays within the class-length limit
+    # (same reason as SessionKeys / SessionView).
+    module SessionTerminal
+      private
+
+      # Prepares the session terminal: SIGWINCH tracking, the alternate
+      # screen, and — inside tmux — the agent-named window label.
+      def install_terminal
+        install_winch_handler
+        @terminal.enter
+        @title&.install(@name)
+      end
+
+      # Runs the full terminal cleanup on every exit path: stops the input
+      # thread, restores the tmux window label, leaves the alternate screen
+      # and restores the SIGWINCH handler.
+      def restore_terminal
+        stop_input_thread
+        @title&.restore
+        leave_terminal
+        restore_winch_handler
+      end
+
+      def leave_terminal
+        @terminal.leave
+      end
+
+      def install_winch_handler
+        Signal.trap('SIGWINCH') { @winch = true }
+      rescue ArgumentError
+        nil
+      end
+
+      def restore_winch_handler
+        Signal.trap('SIGWINCH', 'DEFAULT')
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/letsdo/tui/session/view.rb

@@ -10,8 +10,16 @@ module Letsdo
         repaint
         @last_repaint = @clock.call
         loop { break if @stop || !poll_once }
-      rescue StandardError
-        nil
+      rescue Letsdo::Stopped
+        raise
+      rescue StandardError => e
+        # A paint/input/resize failure here must not leave a blank,
+        # unresponsive TUI: record it and interrupt the run so it is surfaced
+        # after the terminal is restored (TASK-92).
+        return if @stop
+
+        @input_error = e
+        quit
       end
 
       def poll_once

data/lib/letsdo/tui/session.rb

@@ -2,6 +2,7 @@
 
 require_relative 'session/keys'
 require_relative 'session/view'
+require_relative 'session/terminal'
 
 module Letsdo
   module Tui
@@ -10,6 +11,7 @@ module Letsdo
     class Session
       include SessionKeys
       include SessionView
+      include SessionTerminal
 
       REPAINT_INTERVAL = 1.0
       IDLE_SLEEP = 0.01
@@ -23,15 +25,15 @@ module Letsdo
       end
 
       def run(&work)
-        install_winch_handler
-        @terminal.enter
-        run_work(&work)
+        install_terminal
+        result = run_work(&work)
+        raise_input_error!
+        result
       rescue Letsdo::Stopped
+        raise_input_error!
         0
       ensure
-        stop_input_thread
-        leave_terminal
-        restore_winch_handler
+        restore_terminal
       end
 
       def run_work(&work)
@@ -41,6 +43,23 @@ module Letsdo
         end
       end
 
+      # Re-raises a failure captured by the background input/render thread
+      # so a paint or input error is never silently swallowed into a blank,
+      # unresponsive TUI (TASK-92). Called after the work ends, on both the
+      # normal and the stopped path, before the ensure restores the terminal;
+      # the error therefore propagates only once the alternate screen is left.
+      #
+      # A fresh instance is raised rather than the captured object: quit
+      # interrupts the main thread from inside the input thread's rescue, so
+      # the injected Letsdo::Stopped already carries the captured error as its
+      # cause, and re-raising that object would form a circular cause chain.
+      def raise_input_error!
+        return unless @input_error
+
+        error = @input_error
+        raise error.class, error.message, error.backtrace
+      end
+
       private
 
       def assign_identity(opts)
@@ -53,6 +72,7 @@ module Letsdo
       def assign_io(opts)
         @terminal = opts.fetch(:terminal)
         @input = opts.fetch(:input)
+        @title = opts[:title]
         @refresh = opts[:refresh]
         @wait_seconds = opts.fetch(:wait_seconds, 10.0)
         @clock = opts[:clock] || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
@@ -72,6 +92,7 @@ module Letsdo
         @body_height = 1
         @seen_version = 0
         @input_thread = nil
+        @input_error = nil
       end
 
       # Enters raw mode on the keyboard for the duration of the block. Held
@@ -86,18 +107,6 @@ module Letsdo
         end
       end
 
-      def install_winch_handler
-        Signal.trap('SIGWINCH') { @winch = true }
-      rescue ArgumentError
-        nil
-      end
-
-      def restore_winch_handler
-        Signal.trap('SIGWINCH', 'DEFAULT')
-      rescue ArgumentError
-        nil
-      end
-
       def start_input_thread
         @input_thread = Thread.new { input_loop }
         @input_thread.report_on_exception = false
@@ -111,10 +120,6 @@ module Letsdo
 
         thread.join(INPUT_JOIN_TIMEOUT) || thread.kill
       end
-
-      def leave_terminal
-        @terminal.leave
-      end
     end
   end
 end

data/lib/letsdo/tui/window_title.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Letsdo
+  module Tui
+    # Names the tmux window after the running agent (TASK-90) and restores
+    # the previous label on exit.
+    #
+    # tmux labels a window after its foreground process (automatic-rename),
+    # which for letsdo is always "ruby" — useless when one agent runs per
+    # pane. Two tmux facts (verified against tmux 3.4) shape this class:
+    #
+    #   * an OSC-2 title escape only sets the *pane* title; the window label
+    #     still follows the process name;
+    #   * so the window must be renamed explicitly and automatic-rename
+    #     disabled for the session, or tmux overwrites the label.
+    #
+    # Every tmux call goes through an injectable runner (tests stub it) and
+    # every failure is swallowed: title handling may never break a session.
+    # Being inside tmux on a TTY stream is the gate, so outside tmux nothing
+    # is written and the tmux binary is never invoked.
+    class WindowTitle
+      # OSC-2 title escape; only emitted inside tmux (see #install).
+      TITLE_TEMPLATE = "\e]2;%s\a"
+      # automatic-rename value meaning "no explicit setting" (tmux default on).
+      UNSET = ''
+
+      # @param stream [IO] terminal output stream (title escapes go here)
+      # @param env [Hash, ENV] source of TMUX / TMUX_PANE
+      # @param runner [Proc, nil] callable(Array<String>) → stdout String;
+      #        defaults to the real tmux binary, stubbed in tests
+      def initialize(stream:, env:, runner: nil)
+        @stream = stream
+        @env = env
+        @runner = runner || method(:run_tmux)
+        @previous = nil
+      end
+
+      # Saves the current window label and labels the window with `name`.
+      # No-op outside tmux, or when the stream is not a TTY.
+      def install(name)
+        return unless tmux?
+
+        state = capture
+        return unless state
+
+        label(name)
+        write_title(name)
+        @previous = state
+      end
+
+      # Puts the saved label back and restores automatic-rename, unsetting
+      # the option when it had no explicit value before (no leftover state).
+      def restore
+        state = @previous
+        return unless state
+
+        @previous = nil
+        label(state[:name])
+        restore_automatic_rename(state[:automatic_rename])
+        write_title(state[:name])
+      end
+
+      # Whether a tmux session hosts this process and titles can be set.
+      def tmux?
+        return false unless @stream.respond_to?(:tty?) && @stream.tty?
+
+        !@env['TMUX'].to_s.empty?
+      end
+
+      private
+
+      # Renames the window, then disables automatic-rename so tmux keeps the
+      # label for the whole session.
+      def label(name)
+        tmux('rename-window', name)
+        tmux('set-option', '-w', 'automatic-rename', 'off')
+      end
+
+      def restore_automatic_rename(value)
+        return tmux('set-option', '-w', '-u', 'automatic-rename') if value == UNSET
+
+        tmux('set-option', '-w', 'automatic-rename', value)
+      end
+
+      # The current window label and automatic-rename value, or nil when the
+      # label cannot be read (no tmux, no server, failed command).
+      def capture
+        name = tmux('display-message', '-p', "\#{window_name}").to_s.strip
+        return nil if name.empty?
+
+        { name: name, automatic_rename: automatic_rename_option }
+      end
+
+      def automatic_rename_option
+        tmux('show-window-options', '-v', 'automatic-rename').to_s.strip
+      end
+
+      def write_title(text)
+        @stream.write(format(TITLE_TEMPLATE, text))
+        @stream.flush
+      end
+
+      # One tmux command through the injected runner; a missing binary, an
+      # unreachable server or a failed command all yield nil.
+      def tmux(*args)
+        @runner.call(window_args(*args))
+      rescue StandardError
+        nil
+      end
+
+      # Targets the pane letsdo runs in, so the commands act on the right
+      # window even when the tmux server has no attached client. `-t` is a
+      # command option and must follow the subcommand.
+      def window_args(*args)
+        pane = @env['TMUX_PANE'].to_s
+        return args if pane.empty?
+
+        [args.first, '-t', pane, *args.drop(1)]
+      end
+
+      # @param args [Array<String>] tmux arguments
+      # @return [String] the command's stdout
+      def run_tmux(args)
+        out, _err, status = Open3.capture3('tmux', *args)
+        raise "tmux failed: #{args.join(' ')}" unless status.success?
+
+        out
+      end
+    end
+  end
+end

data/lib/letsdo/tui.rb

@@ -7,6 +7,8 @@
 # timer, tasks remaining, current-task elapsed, waiting/PAUSED states), a
 # scrollable combined log and a key-help footer, and repaints from a
 # background input thread. Non-TTY output stays the plain line-stream.
+# Inside tmux the window is labeled with the agent name for the session and
+# the previous label is restored on exit (TASK-90).
 #
 # Components:
 #   Letsdo::Tui::LogBuffer  - thread-safe combined log (streamer target)
@@ -14,11 +16,13 @@
 #   Letsdo::Tui::Renderer   - pure function: state → framed String
 #   Letsdo::Tui::Terminal   - alt screen, cursor, frame rendering
 #   Letsdo::Tui::Input      - tty-reader key decoding (injectable)
+#   Letsdo::Tui::WindowTitle - names the tmux window after the agent
 #   Letsdo::Tui::Session    - controller: terminal lifecycle + input thread
 
 require_relative 'tui/log_buffer'
 require_relative 'tui/metrics'
 require_relative 'tui/renderer'
 require_relative 'tui/terminal'
+require_relative 'tui/window_title'
 require_relative 'tui/input'
 require_relative 'tui/session'

data/lib/letsdo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letsdo
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/letsdo.rb

@@ -6,33 +6,44 @@
 #   Letsdo::Errors           - error hierarchy (Letsdo::Error and others)
 #   Letsdo::PromptStore      - access to agents/*.md prompts
 #   Letsdo::DefaultPrompt    - the built-in default prompt (fallback run, --init template)
+#   Letsdo::AgentIdentity    - the identity block injected into every agent prompt
 #   Letsdo::OutputStreamer   - where and how agent text and service lines are printed
-#   Letsdo::PiRunner         - running pi --mode json and parsing the event stream
+#   Letsdo::Backends::Pi     - running pi --mode json and parsing the event stream
 #   Letsdo::Agent            - a single agent run: prompt from agents/ or default + pi
 #   Letsdo::Capture          - interruption-safe child stdout/stderr capture
 #   Letsdo::BacklogTasks     - open tasks from the backlog CLI (the task provider)
 #   Letsdo::Loop             - generic orchestrator: tasks → runs → waiting
+#   Letsdo::RetryPolicy      - per-task retry/backoff/give-up policy (used at AgentLoop level)
 #   Letsdo::AgentLoop        - letsdo wiring: provider + agent + signals + messages
-#   Letsdo::Control          - agent-control primitives (PauseGate)
+#   Letsdo::Control          - agent-control primitives (PauseGate, Reader)
+#   Letsdo::Doctor           - `letsdo doctor` environment self-check
 #   Letsdo::Tui              - the interactive TUI (LogBuffer, Metrics,
-#                              Renderer, Terminal, Input, Session)
+#                              Renderer, Terminal, WindowTitle, Input, Session)
 #   Letsdo::CLI              - command-line arguments, usage, exit code
 #
 # Entry point — bin/letsdo (a thin wrapper over Letsdo::CLI).
 
 require_relative 'letsdo/version'
 require_relative 'letsdo/errors'
+require_relative 'letsdo/duration'
 require_relative 'letsdo/config'
 require_relative 'letsdo/prompt_store'
 require_relative 'letsdo/default_prompt'
+require_relative 'letsdo/agent_identity'
 require_relative 'letsdo/output_streamer'
-require_relative 'letsdo/pi_runner'
+require_relative 'letsdo/backends/backend'
+require_relative 'letsdo/backends/pi'
 require_relative 'letsdo/agent'
 require_relative 'letsdo/capture'
-require_relative 'letsdo/backlog_tasks'
+require_relative 'letsdo/providers/backlog'
 require_relative 'letsdo/loop'
+require_relative 'letsdo/retry_policy'
 require_relative 'letsdo/watcher'
 require_relative 'letsdo/agent_loop'
+require_relative 'letsdo/session_recorder'
+require_relative 'letsdo/task_time_writeback'
+require_relative 'letsdo/metrics/fanout'
 require_relative 'letsdo/control'
+require_relative 'letsdo/doctor'
 require_relative 'letsdo/tui'
 require_relative 'letsdo/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsdo
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -95,27 +95,45 @@ files:
 - LICENSE
 - README.md
 - bin/letsdo
+- docs/config.md
+- docs/prompts.md
+- docs/task-selection.md
+- docs/usage.md
 - letsdo.gemspec
 - lib/letsdo.rb
 - lib/letsdo/agent.rb
+- lib/letsdo/agent_identity.rb
 - lib/letsdo/agent_loop.rb
 - lib/letsdo/agent_loop/tasks.rb
-- lib/letsdo/backlog_tasks.rb
+- lib/letsdo/backends/backend.rb
+- lib/letsdo/backends/pi.rb
+- lib/letsdo/backends/pi/events.rb
 - lib/letsdo/capture.rb
 - lib/letsdo/cli.rb
 - lib/letsdo/cli/builder.rb
+- lib/letsdo/cli/builder_assembly.rb
+- lib/letsdo/cli/builder_metrics.rb
+- lib/letsdo/cli/doctor.rb
 - lib/letsdo/cli/init.rb
 - lib/letsdo/config.rb
 - lib/letsdo/control.rb
+- lib/letsdo/control/reader.rb
 - lib/letsdo/default_prompt.rb
+- lib/letsdo/doctor.rb
+- lib/letsdo/doctor/checks.rb
+- lib/letsdo/duration.rb
 - lib/letsdo/errors.rb
 - lib/letsdo/loop.rb
+- lib/letsdo/metrics/fanout.rb
 - lib/letsdo/output_streamer.rb
 - lib/letsdo/output_streamer/arg_summary.rb
-- lib/letsdo/pi_runner.rb
-- lib/letsdo/pi_runner/events.rb
-- lib/letsdo/pi_runner/process.rb
 - lib/letsdo/prompt_store.rb
+- lib/letsdo/providers/backlog.rb
+- lib/letsdo/providers/task.rb
+- lib/letsdo/retry_policy.rb
+- lib/letsdo/session_recorder.rb
+- lib/letsdo/session_recorder/jsonl_writer.rb
+- lib/letsdo/task_time_writeback.rb
 - lib/letsdo/tui.rb
 - lib/letsdo/tui/input.rb
 - lib/letsdo/tui/log_buffer.rb
@@ -123,8 +141,10 @@ files:
 - lib/letsdo/tui/renderer.rb
 - lib/letsdo/tui/session.rb
 - lib/letsdo/tui/session/keys.rb
+- lib/letsdo/tui/session/terminal.rb
 - lib/letsdo/tui/session/view.rb
 - lib/letsdo/tui/terminal.rb
+- lib/letsdo/tui/window_title.rb
 - lib/letsdo/version.rb
 - lib/letsdo/watcher.rb
 homepage: https://github.com/sergio-fry/letsdo

data/lib/letsdo/backlog_tasks.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'shellwords'
-
-module Letsdo
-  # Task provider for Letsdo::Loop backed by the real backlog CLI:
-  #
-  #   backlog task list --assignee <handle> --exclude-status Done --json
-  #
-  # Returns the list of open tasks assigned to the handle (an Array, empty
-  # when there are none), or nil when the backlog state is unreadable — the
-  # CLI is not on PATH, failed, or its output is not the expected JSON. The
-  # loop treats nil as "pause and retry, do not run the agent".
-  #
-  # The command runs in the project root (cwd), where the backlog CLI finds
-  # the backlog/ folder — the same context as a single agent run.
-  class BacklogTasks
-    # @param handle [String] assignee handle to filter by (e.g. "@developer")
-    # @param command [String] backlog CLI command (overridable for tests)
-    # @param cwd [String, nil] project root for the CLI; nil = inherit cwd
-    # @param env [Hash, nil] environment for the CLI child (nil = inherit
-    #        the process environment; injected in tests to control the
-    #        fake backlog scenarios)
-    def initialize(handle:, command: 'backlog', cwd: nil, env: nil)
-      @handle = handle
-      @command = command
-      @cwd = cwd
-      @env = env
-    end
-
-    # Reads the open tasks once.
-    #
-    # @return [Array<Hash>, nil] open tasks; nil when the backlog is unreadable
-    def call
-      args = @env ? [@env, *command_line] : command_line
-      out, _err, status = Letsdo::Capture.new(*args, chdir: @cwd).run
-      return nil unless status.success?
-
-      tasks = JSON.parse(out)['tasks']
-      tasks.is_a?(Array) ? tasks : nil
-    rescue Errno::ENOENT, JSON::ParserError, TypeError
-      nil
-    end
-
-    private
-
-    # [command..., task, list, --assignee <handle>, --exclude-status Done, --json]
-    def command_line
-      [
-        *Shellwords.split(@command),
-        'task', 'list',
-        '--assignee', @handle,
-        '--exclude-status', 'Done',
-        '--json'
-      ]
-    end
-  end
-end