letsdo 0.4.0 → 0.6.1

data/lib/letsdo/session_recorder/jsonl_writer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Letsdo
+  class SessionRecorder
+    # Writes the optional JSON Lines metrics stream for a session recorder:
+    # a session_start line on construction, one run_finished line per closed
+    # run and a session_stop line at the end. With a nil IO the writer is a
+    # no-op, so callers need no nil checks.
+    class JsonlWriter
+      # @param io [IO, nil] append-only target; nil disables the writer
+      # @param name [String] agent name
+      # @param handle [String] assignee handle
+      # @param wall_clock [Proc] -> ISO8601 UTC timestamp string
+      def initialize(io, name:, handle:, wall_clock:)
+        @io = io
+        @name = name
+        @handle = handle
+        @wall_clock = wall_clock
+        session_start if enabled?
+      end
+
+      # @return [Boolean] whether an output target is configured
+      def enabled?
+        !@io.nil?
+      end
+
+      # Writes the opening session_start line (no-op when disabled).
+      #
+      # @return [void]
+      def session_start
+        write(session_start_payload)
+      end
+
+      # @param run [SessionRecorder::Run] a closed run record
+      # @return [void]
+      def run_finished(run)
+        write(
+          'event' => 'run_finished', 'task' => run.task_id, 'exit' => run.exit_code,
+          'outcome' => run.outcome.to_s, 'elapsed_s' => run.elapsed_s,
+          'ts' => @wall_clock.call
+        )
+      end
+
+      # @param summary [SessionRecorder::Summary] the final aggregate
+      # @return [void]
+      def session_stop(summary)
+        write(
+          'event' => 'session_stop', 'agent' => @name, 'handle' => @handle,
+          'ts' => @wall_clock.call, 'done' => summary.done, 'failed' => summary.failed,
+          'interrupted' => summary.interrupted, 'left' => summary.left,
+          'session_s' => summary.session_s, 'runs_s' => summary.active_s
+        )
+      end
+
+      private
+
+      def session_start_payload
+        { 'event' => 'session_start', 'agent' => @name, 'handle' => @handle,
+          'ts' => @wall_clock.call }
+      end
+
+      def write(payload)
+        return unless enabled?
+
+        @io.puts(JSON.generate(payload))
+        @io.flush if @io.respond_to?(:flush)
+      end
+    end
+  end
+end

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