letsdo 0.3.0 → 0.6.1

data/lib/letsdo/session_recorder.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative 'duration'
+require_relative 'session_recorder/jsonl_writer'
+
+module Letsdo
+  # A mode-independent session metrics recorder. It receives the same
+  # loop-driver events as the TUI metrics facade, records per-run outcomes
+  # and durations, and can optionally emit a JSONL event stream.
+  #
+  # The recorder is intentionally free of TUI dependencies so it can be
+  # used in plain mode, TUI mode, or embedded contexts.
+  class SessionRecorder
+    Run = Struct.new(:task_id, :started_mono, :finished_mono, :elapsed_s,
+                     :exit_code, :outcome, keyword_init: true)
+
+    Summary = Struct.new(:done, :failed, :interrupted, :left, :session_s,
+                         :active_s, :waiting_s, :avg_s, :runs,
+                         keyword_init: true)
+
+    MAX_SUMMARY_RUNS = 10
+
+    HEADLINE = 'letsdo: session: %<done>d done, %<failed>d failed, ' \
+               '%<interrupted>d interrupted, %<left>s left open, %<session>s ' \
+               '(%<active>s in runs, %<waiting>s waiting, avg %<avg>s)'
+
+    # Rendering of the human-readable stop summary (TASK-63 C3). Kept nested
+    # so SessionRecorder stays within the class-length limit.
+    module SummaryFormat
+      private
+
+      def headline(summary)
+        left = summary.left.nil? ? 'unknown' : summary.left
+        format(HEADLINE, done: summary.done, failed: summary.failed,
+                         interrupted: summary.interrupted, left: left,
+                         session: format_duration(summary.session_s),
+                         active: format_duration(summary.active_s),
+                         waiting: format_duration(summary.waiting_s),
+                         avg: format_duration(summary.avg_s))
+      end
+
+      def run_lines(summary)
+        lines = summary.runs.first(MAX_SUMMARY_RUNS).map { |run| format_run(run) }
+        return lines unless summary.runs.length > MAX_SUMMARY_RUNS
+
+        lines << "letsdo:   … and #{summary.runs.length - MAX_SUMMARY_RUNS} more"
+      end
+
+      def format_run(run)
+        return "letsdo:   #{run.task_id} interrupted" if run.finished_mono.nil?
+
+        outcome = run.outcome == :done ? 'done' : 'failed'
+        "letsdo:   #{run.task_id} #{outcome} in #{format_duration(run.elapsed_s)}"
+      end
+
+      # Shared with the task-time write-back so summary and task record agree.
+      def format_duration(seconds)
+        Duration.format(seconds)
+      end
+    end
+    include SummaryFormat
+
+    # @param name [String] agent name
+    # @param handle [String] assignee handle
+    # @param clock [Proc] monotonic clock -> seconds; default
+    #        Process.clock_gettime(CLOCK_MONOTONIC)
+    # @param wall_clock [Proc] wall clock -> ISO8601 UTC string; default
+    #        Time.now.utc.iso8601
+    # @param metrics_io [IO, nil] optional append-only JSONL target
+    def initialize(name:, handle:, clock: nil, wall_clock: nil, metrics_io: nil)
+      @name = name
+      @handle = handle
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @wall_clock = wall_clock || -> { Time.now.utc.iso8601 }
+      @writer = JsonlWriter.new(metrics_io, name: name, handle: handle, wall_clock: @wall_clock)
+      @mutex = Mutex.new
+      @runs = []
+      @left = nil
+      @session_started = @clock.call
+      @session_stopped = false
+    end
+
+    # A run started for a task.
+    #
+    # @param task_id [String] task label
+    # @return [void]
+    def run_started(task_id)
+      @mutex.synchronize do
+        @runs << Run.new(task_id: task_id, started_mono: @clock.call)
+      end
+    end
+
+    # A run finished. The last still-open run is closed with the given
+    # exit code. If no run is open, this is a no-op.
+    #
+    # @param exit_code [Integer, nil] the run exit code
+    # @return [void]
+    def run_finished(exit_code = nil)
+      @mutex.synchronize do
+        run = @runs.reverse.find { |candidate| candidate.finished_mono.nil? }
+        return unless run
+
+        close_run(run, exit_code)
+        @writer.run_finished(run)
+      end
+    end
+
+    # The latest open-task count from the backlog provider.
+    #
+    # @param count [Integer, nil] number of open tasks; nil = the backlog
+    #        state is unreadable
+    # @return [void]
+    def provider_result(count)
+      @mutex.synchronize { @left = count }
+    end
+
+    # A point-in-time summary of the session metrics.
+    #
+    # waiting_s is a derived approximation: session time minus the sum of
+    # run durations. It therefore also includes polling, backlog reads and
+    # stop overhead, not only idle waiting for new tasks.
+    #
+    # @return [Summary] aggregate counts and durations
+    def summary
+      @mutex.synchronize { build_summary }
+    end
+
+    # Writes the session_stop JSONL event and returns the summary.
+    # The event is written only once per recorder instance.
+    #
+    # @return [Summary]
+    def session_stop
+      emit = claim_stop_event
+      result = summary
+      @writer.session_stop(result) if emit
+      result
+    end
+
+    # A human-readable summary suitable for stderr.
+    #
+    # @return [String]
+    def summary_line
+      s = summary
+      lines = [headline(s)] + run_lines(s)
+      lines.join("\n")
+    end
+
+    private
+
+    def close_run(run, exit_code)
+      run.finished_mono = @clock.call
+      run.elapsed_s = run.finished_mono - run.started_mono
+      run.exit_code = exit_code
+      run.outcome = exit_code&.zero? ? :done : :failed
+    end
+
+    def build_summary
+      session_s = @clock.call - @session_started
+      active_s = @runs.sum { |run| run.elapsed_s || 0.0 }
+      Summary.new(
+        done: count_outcome(:done), failed: count_outcome(:failed),
+        interrupted: @runs.count { |run| run.finished_mono.nil? }, left: @left,
+        session_s: session_s, active_s: active_s, waiting_s: session_s - active_s,
+        avg_s: average_done_run, runs: @runs.dup
+      )
+    end
+
+    def count_outcome(outcome)
+      @runs.count { |run| run.outcome == outcome }
+    end
+
+    def average_done_run
+      done = @runs.select { |run| run.outcome == :done }
+      return 0.0 if done.empty?
+
+      done.sum { |run| run.elapsed_s || 0.0 } / done.size
+    end
+
+    def claim_stop_event
+      @mutex.synchronize do
+        return false if @session_stopped
+
+        @session_stopped = true
+        @writer.enabled?
+      end
+    end
+  end
+end

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

@@ -29,7 +29,9 @@ module Letsdo
                             :current_task, :current_task_seconds, keyword_init: true)
 
       # @param name [String] agent name (CLI argument)
-      # @param handle [String] assignee handle (e.g. "@developer")
+      # @param handle [String] assignee (the bare tracker name, e.g.
+      #        "developer"; the header renders it with the display-only
+      #        '@' prefix)
       # @param clock [Proc] monotonic clock, callable → seconds; injected
       #        in tests
       # @param on_run_start [Proc, nil] called with the task label when a
@@ -60,8 +62,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/renderer.rb

@@ -66,11 +66,19 @@ module Letsdo
       end
 
       def self.header_line(metrics, width)
-        title = "letsdo · #{metrics.name} (#{metrics.handle})"
+        title = "letsdo · #{metrics.name} (#{display_handle(metrics)})"
         timer = "session #{Text.format_duration(metrics.session_seconds)}"
         Text.fit_line_with_right(title, timer, width)
       end
 
+      # The header keeps the historical "name (@assignee)" look: the '@'
+      # is display notation only (TASK-96) — the tracker value is the bare
+      # name, and a legacy @-prefixed handle is shown as stored.
+      def self.display_handle(metrics)
+        handle = metrics.handle.to_s
+        handle.start_with?('@') ? handle : "@#{handle}"
+      end
+
       # The state line: done/left plus either the running task with its
       # elapsed time, a waiting reason, or the PAUSED overlay.
       def self.state_line(metrics, width, paused, wait_seconds)

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.3.0'
+  VERSION = '0.6.1'
 end