letsdo 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9576e7f61d65dbf1379b3e4fcce4831f3162432b9039dc2153f7952201420091
-  data.tar.gz: 679c98fd2628270bb62cf2f35c6a9d13653dd75a3ebe48aa83abc77c3aeccd97
+  metadata.gz: f6c3ecf1ef07372a4f5b38843faafaf394ca49ee9ea73c48a59034c0c33ed1b9
+  data.tar.gz: 9349a23494802614dcdb7aa27d378b7ca2dae1512a395989678e166b3b68548d
 SHA512:
-  metadata.gz: 8a6744c21cd6681ac8fde456977962f8a1c8a79cfd8e8157091b0d3ba42848d29f982dd622880e7b7c03f82ec065d014d56da1b61a2f9cd954f3693fc2218f21
-  data.tar.gz: 2925952a1d86f40fc54d1e20e57c83cec89e0f07579c2a0336e2cc370b94c462516c9686c981aedc4b456120ec42fcd51859386685be342c8999ca5bcc3d53d7
+  metadata.gz: 74a49f0c9d8a27c25acc94205f57a9ba9f5e63ac18a8d97e15c270b02e661e45cd30da84fe998f382d6baaa5945f59148b4edf4e62db8b292150dcb56e4e0ad9
+  data.tar.gz: ca34be59f778f078ab0766088d70acb4fe1935d3021315f98a8d1c402c6897cc2267ff5a525c0e5db6c28d3f71238fb782f8972c3db844282353a263732b604d

data/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-08
+
+### Changed
+
+- `Letsdo::CLI::Builder` extracted from `CLI` — all component assembly
+  (agent, provider, loop, TUI setup) now lives in Builder; `CLI` keeps only
+  argv parsing and delegates to Builder. The former `CLILaunch` module is
+  deleted. New `test/cli_builder_test.rb` covers Builder assembly and TUI
+  detection. Zero behavioral change.
+- The gemspec now has a user-facing description (what letsdo does and why)
+  instead of an internal class inventory; `required_ruby_version` is
+  narrowed from `>= 3.0` to `>= 3.3` to match what CI actually tests
+  (Ruby 3.0–3.2 are end-of-life); `bug_tracker_uri` and `documentation_uri`
+  metadata are added; and `spec.files` ships `CHANGELOG.md` and the gemspec
+  itself alongside the code, README and LICENSE.
+
+### Fixed
+
+- The documented Ruby 4.0.x install workaround now leads with fixing the
+  environment (`gem install rbs -v '>= 4.0.0'`), with `--no-document` as a
+  fallback — the rbs upgrade actually makes the plain `gem install letsdo`
+  post-install RDoc hook succeed instead of just skipping it. The CI
+  "Verify install" step now installs the built gem without `--no-document`,
+  repairs a broken rdoc/rbs pair when `require "rdoc"` fails, runs on Ruby
+  4.0 as well as 3.3, and checks `letsdo --version` — so the exact plain
+  install path a user runs (including the RDoc hook) is guarded against the
+  rdoc/rbs conflict crashing it again.
+
+## [0.3.0] - 2026-09-07
+
+### Added
+
+- `Letsdo::Watcher` — OS file-change watching of the backlog folder via
+  inotify (Linux, through Fiddle with no external gem) with a self-pipe
+  polling fallback; the orchestrator loop now wakes on a backlog change
+  instead of waiting out the full `LETSDO_WAIT_SECONDS` interval. The wake
+  replaces the idle-phase wait only — the startup check and the re-check
+  after each finished task stay immediate provider queries.
+
+### Fixed
+
+- An explicitly injected control/stop sleeper is honored over the watcher
+  idle path, so a CLI test that injects a sleeper completes normally even
+  with the loop watcher enabled — `rake test` no longer hangs in an infinite
+  idle wait.
+- `Letsdo::Capture` runs its child in its own process group and terminates
+  the whole group when the capture is interrupted, so a stopped capture can
+  no longer leave an orphaned grandchild holding the stdout/stderr pipes.
+- Quitting the TUI no longer leaves the terminal in raw mode: raw-mode entry
+  moved to the main thread, so the saved termios (echo + canonical line
+  editing) is restored on every quit path — the shell in a tmux pane stays
+  usable.
+- A tool-only agent run after a text run no longer writes a spurious blank
+  line on stdout (`OutputStreamer#finish` resets its last-char state).
+- `require "letsdo"` no longer eagerly loads `tty-cursor` (or any tty-* gem),
+  so `rake test` runs on a clean Ruby without the gem installed; the TUI
+  still loads its gems lazily on the interactive path.
+- Documented a Ruby 4.0.x install note: the post-install RDoc hook can crash
+  on a mismatched rdoc/rbs pair — install with `--no-document`.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+
+- `letsdo <name> --init` (and the flag-first form `letsdo --init <name>`)
+  creates `agents/<name>.md` with the starter default prompt
+  (`Letsdo::DefaultPrompt::TEXT`) so the prompt can be customized — the
+  agent is never started. An already existing file or an unsafe name
+  (contains `/` or `\`, or is `.`/`..`) is refused with a message on
+  stderr and exit 1; nothing is ever written outside `agents/`
+  (`Letsdo::PromptStore#create_agent`).
+- Built-in default prompt (`Letsdo::DefaultPrompt::TEXT`): `letsdo <name>`
+  starts the agent even without `agents/<name>.md` — the run falls back to
+  the built-in process-only prompt, and letsdo announces once on stderr
+  the exact path checked (`<root>/agents/<name>.md`) plus the
+  `letsdo <name> --init` placement hint. `UnknownAgentError` is removed:
+  with the fallback there are no unknown agents, the base `Letsdo::Error`
+  remains the package error surface.
+- Real pause semantics for the TUI 'p' key: mid-run the pi group is
+  suspended at the kernel level (SIGSTOP via `Letsdo::PiRunner#pause`,
+  resume via SIGCONT); between runs a shared `Letsdo::Control::PauseGate`
+  holds new runs until resume. The footer flips between `p pause` and
+  `p resume`.
+- `SIGHUP` (terminal closed) stops the loop the same way as `SIGINT`/
+  `SIGTERM`.
+- Prompt stop of a paused pi: `PiRunner#terminate` now reaps the child
+  during its grace wait (WNOHANG) instead of polling the process table,
+  so a signal-killed child's zombie state can no longer stall the stop
+  for the full grace period.
+- Gemspec metadata: `homepage`, `homepage_uri`, `source_code_uri`,
+  `changelog_uri`, `allowed_push_host`.
+- `CHANGELOG.md`.
+- Default RuboCop 1.77 as a development dependency; CI fails the build
+  on style violations.
+
+### Changed
+
+- Tool result bodies (indented stdout/stderr blocks, truncation notes,
+  `✖ Error:` markers) are no longer printed to the aux output; the stream
+  shows only tool invocations (`HH:MM:SS ⚙ name: args`) and a one-line
+  completion with duration (`✓/✖ name: done/error (Ns)`).
+- `Session#quit` sets the stop flag before raising `Letsdo::Stopped`, so
+  the input thread renders no frames during teardown.
+
+### Fixed
+
+- `rake test` no longer prints `Open3.capture3` reader-thread dumps
+  (`IOError: stream closed in another thread`): `Letsdo::BacklogTasks` now
+  captures the backlog CLI output through `Letsdo::Capture`, whose reader
+  threads tolerate the pipes being closed when a stop (TUI quit, signal)
+  interrupts an in-flight backlog call and whose cleanup reaps the child
+  even then.
+- CLI tests no longer collide on a shared `/tmp` “tasks already served”
+  marker after Minitest reseeds `Kernel.srand` per test class.
+
+## [0.1.0] - 2026-09-04
+
+### Added
+
+- Initial release of letsdo — a local agent worker for Backlog.md/markdown tasks.
+- OOP structure: `Letsdo::PromptStore` (agents/), `Letsdo::OutputStreamer` and
+  `Letsdo::PiRunner` (pi --mode json), `Letsdo::Agent` (one run), `Letsdo::Loop`
+  (orchestrator loop), `Letsdo::CLI`.
+- Interactive TUI (header metrics, scrollable stream) in TTY mode; plain
+  line-stream mode for pipes/CI/tests.
+- Minitest tests; CI (GitHub Actions) builds the gem and runs tests on every push.
+- Local executable `letsdo`.
+
+[Unreleased]: https://github.com/sergio-fry/letsdo/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/sergio-fry/letsdo/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/sergio-fry/letsdo/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/sergio-fry/letsdo/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sergio-fry/letsdo/releases/tag/v0.1.0

data/README.md

@@ -80,7 +80,7 @@ generation, any repeatable task flow you can express as assignee + prompt.
 
 ## Requirements
 
-- Ruby **>= 3.0**.
+- Ruby **>= 3.3**.
 - The [pi](https://github.com/earendil-works/pi) agent CLI on
   `PATH` — this is the AI backend that runs the agent (`pi --mode json`).
   The command is configurable via `LETSDO_PI_COMMAND`.
@@ -99,9 +99,17 @@ The gem is built from the repository:
 git clone git@github.com:sergio-fry/letsdo.git
 cd letsdo
 gem build letsdo.gemspec
-gem install letsdo-0.2.0.gem
+gem install letsdo-0.3.0.gem
 ```
 
+> **Ruby 4.0.x note.** Some Ruby 4.0.x builds ship default gems out of sync —
+> rdoc 8.0.0 declares `rbs >= 4.0.0` while rbs 3.x is bundled — so the
+> post-install RDoc hook can raise `Gem::ConflictError` even though the gem
+> files are already installed. Fix the environment by installing a matching
+> rbs first (`gem install rbs -v '>= 4.0.0'`); if that is not possible,
+> install the gem without documentation to skip the hook
+> (`gem install letsdo-0.3.0.gem --no-document`).
+
 or run it straight from the checkout without installing:
 
 ```sh
@@ -250,7 +258,7 @@ gem build letsdo.gemspec
 
 Cleanliness is enforced by the CI workflow
 (`.github/workflows/ci.yml`): gem build + `rake test` on every push,
-Ruby 3.3 (satisfies `required_ruby_version: ">= 3.0"`).
+Ruby 3.3 and 4.0 (satisfies `required_ruby_version: ">= 3.3"`).
 
 ## Alternatives
 

data/letsdo.gemspec

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "lib/letsdo/version"
+
+Gem::Specification.new do |spec|
+  spec.name    = "letsdo"
+  spec.version = Letsdo::VERSION
+  spec.authors = ["Sergei O. Udalov"]
+  spec.email   = ["udalov.x@mail.ru"]
+
+  spec.summary     = "A local agent worker for Backlog.md/markdown tasks"
+  spec.description = "letsdo turns a plain markdown backlog into a team of " \
+                     "autonomous local agents. Each agent is just a prompt " \
+                     "file in agents/; run `letsdo <name>` and it works " \
+                     "through every open task assigned to that agent, one " \
+                     "task per run, and stops cleanly on Ctrl+C. No " \
+                     "framework, no hosted platform — the backlog folder is " \
+                     "the single source of truth and task data never leaves " \
+                     "your machine."
+  spec.license = "MIT"
+
+  # Supported Ruby floor matches what CI actually tests (3.3 and 4.0).
+  # Ruby 3.0/3.1/3.2 are end-of-life, so claiming support for them while
+  # never testing them would be dishonest packaging.
+  spec.required_ruby_version = ">= 3.3"
+
+  # Runtime dependencies: the interactive TUI. Required lazily inside the
+  # tui classes so the plain line-stream mode (pipes/CI/tests) works with
+  # zero extra gems.
+  spec.add_runtime_dependency "tty-screen", "~> 0.8"
+  spec.add_runtime_dependency "tty-cursor", "~> 0.7"
+  spec.add_runtime_dependency "tty-reader", "~> 0.9"
+  spec.add_runtime_dependency "unicode-display_width", ">= 2.0"
+
+  # Development dependency: style checks (default RuboCop config, enforced
+  # in CI). Not installed by the CI workflow via bundler — the workflow
+  # installs the same constraint with `gem install` on a clean Ruby.
+  spec.add_development_dependency "rubocop", "~> 1.77.0"
+
+  # The AI backend is the external `pi` CLI (default, overridable via
+  # LETSDO_PI_COMMAND) — a runtime *requirement*, not a rubygem, so it is
+  # documented in the README rather than declared as a dependency.
+  spec.files         = Dir["lib/**/*.rb", "README.md", "LICENSE",
+                           "CHANGELOG.md", "letsdo.gemspec"]
+  spec.bindir        = "bin"
+  spec.executables   = ["letsdo"]
+  spec.require_paths = ["lib"]
+
+  spec.homepage = "https://github.com/sergio-fry/letsdo"
+
+  # source_code_uri shares the homepage URL on purpose (the source *is* the
+  # project home); homepage_uri is deliberately not duplicated in metadata
+  # because an identical homepage_uri + source_code_uri pair makes
+  # `gem build` warn.
+  spec.metadata["source_code_uri"]       = "https://github.com/sergio-fry/letsdo"
+  spec.metadata["bug_tracker_uri"]       = "https://github.com/sergio-fry/letsdo/issues"
+  spec.metadata["changelog_uri"]         = "https://github.com/sergio-fry/letsdo/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"]     = "https://github.com/sergio-fry/letsdo/blob/main/README.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["allowed_push_host"]     = "https://rubygems.org"
+end

data/lib/letsdo/agent_loop.rb

@@ -26,9 +26,14 @@ module Letsdo
       @stderr.puts('letsdo: stopped')
       0
     ensure
+      close_watcher
       restore_signal_handlers
     end
 
+    def close_watcher
+      @watcher&.close
+    end
+
     def debug(message)
       warn("[letsdo] loop: #{message}") if @debug
     end
@@ -51,8 +56,22 @@ module Letsdo
     def assign_control_opts(opts)
       @metrics = opts[:metrics]
       @pause_gate = opts[:pause_gate]
-      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
-      @sleeper = opts[:sleeper] || ->(seconds) { sleep(seconds) }
+      @debug = resolve_debug(opts)
+      @watcher = opts[:watcher] || (Watcher.new(path: opts[:watch_path]) if opts[:watch_path])
+      # Precedence is deliberate: an explicitly injected sleeper always wins
+      # over the watcher idle path — tests inject a stop/control sleeper that
+      # must never be bypassed by a configured watcher (TASK-84).
+      @sleeper = opts[:sleeper] || watcher_sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    def resolve_debug(opts)
+      return opts[:debug] unless opts[:debug].nil?
+
+      (opts[:config] || Config.new).debug?
+    end
+
+    def watcher_sleeper
+      @watcher && ->(seconds) { @watcher.wait(seconds) }
     end
 
     def run_until_stopped

data/lib/letsdo/capture.rb

@@ -33,6 +33,7 @@ module Letsdo
       @err_w.close
       readers = [quiet_reader(@out_r), quiet_reader(@err_r)]
       status = wait_and_reap(@pid)
+      @reaped = true
       [readers[0].value, readers[1].value, status]
     ensure
       cleanup
@@ -41,7 +42,7 @@ module Letsdo
     private
 
     def spawn_child
-      opts = { out: @out_w, err: @err_w }
+      opts = { out: @out_w, err: @err_w, pgroup: true }
       opts[:chdir] = @chdir if @chdir
       Process.spawn(*@args, **opts)
     end
@@ -62,12 +63,26 @@ module Letsdo
       status
     end
 
-    # Reaps pid if the normal wait never ran (the wait was interrupted by a
-    # stop); a no-op when the child was already reaped.
-    def reattach_reaper(pid)
+    # Kills the child's process group and reaps it when the normal wait was
+    # interrupted (a stop raised into the main thread). Killing the whole
+    # group also terminates any grandchildren that inherited the child's
+    # stdout/stderr pipes, so none of them is left holding the pipes open
+    # (TASK-84). A no-op when the child was already reaped normally.
+    def terminate_and_reap(pid)
       return unless pid
 
-      Process.detach(pid)
+      kill_group(pid)
+      reap(pid)
+    end
+
+    def kill_group(pid)
+      Process.kill('TERM', -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def reap(pid)
+      Process.wait2(pid)
     rescue Errno::ECHILD
       nil
     end
@@ -77,7 +92,7 @@ module Letsdo
       close_quietly(@err_w)
       close_quietly(@out_r)
       close_quietly(@err_r)
-      reattach_reaper(@pid)
+      terminate_and_reap(@pid) unless @reaped
     end
 
     def close_quietly(io)

data/lib/letsdo/cli/builder.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # TUI component assembly used by Letsdo::CLI::Builder. Kept in its own
+    # module so Builder stays within the class-length limit; mirrors the
+    # CLILaunch/CLIInit split pattern.
+    module BuilderTui
+      def run_tui(name)
+        ctx = tui_context(name)
+        session = Tui::Session.new(**ctx[:session])
+        session.run { ctx[:loop].run }
+      end
+
+      def tui_context(name)
+        parts = tui_parts(name)
+        {
+          loop: tui_loop(name, parts),
+          session: tui_session_args(name, **parts)
+        }
+      end
+
+      def tui_parts(name)
+        clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        handle = assignee_handle(name)
+        log = Tui::LogBuffer.new
+        {
+          clock: clock, handle: handle, log: log,
+          metrics: tui_metrics(name, handle, clock, log),
+          agent: agent_for(name, OutputStreamer.new(log: log)),
+          provider: provider_for(handle),
+          pause_gate: Control::PauseGate.new
+        }
+      end
+
+      def tui_loop(name, parts)
+        agent_loop(name, nil, agent: parts[:agent], provider: parts[:provider],
+                              handle: parts[:handle], stderr: parts[:log],
+                              metrics: parts[:metrics], pause_gate: parts[:pause_gate])
+      end
+
+      def tui_metrics(name, handle, clock, log)
+        Tui::Metrics.new(name: name, handle: handle, clock: clock,
+                         on_run_start: ->(_label) { log.divider })
+      end
+
+      def tui_session_args(name, **parts)
+        {
+          name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:metrics],
+          terminal: Tui::Terminal.new(stream: @stdout),
+          input: Tui::Input.new(stdin: @stdin),
+          refresh: -> { parts[:provider].call },
+          wait_seconds: wait_seconds, clock: parts[:clock],
+          pause_gate: parts[:pause_gate], runner: -> { parts[:agent].runner }
+        }
+      end
+    end
+
+    # Owns all component assembly for running an agent (TASK-54): builds the
+    # streamer, agent, backlog provider, orchestrator loop and the whole TUI,
+    # and decides plain vs TUI mode via stdout/stdin TTY + TERM. Parsing stays
+    # in Letsdo::CLI (TASK-54); this class is the wiring half — independently
+    # testable and free to grow with provider/backend selection (TASK-51/52)
+    # without bloating the parser.
+    class Builder
+      include BuilderTui
+
+      def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
+        @env = env
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = stdin
+        @sleeper = sleeper
+        @config = Config.new(env: env)
+        @root = @config.root
+      end
+
+      # Runs <name> in plain or TUI mode; returns the process exit code.
+      def run(name)
+        store = PromptStore.new(root: @root)
+        announce_default_prompt(name, store) if store.read(name).nil?
+        tui? ? run_tui(name) : run_plain(name)
+      end
+
+      private
+
+      def run_plain(name)
+        streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
+        agent_loop(name, streamer, stderr: @stderr).run
+      end
+
+      def agent_for(name, streamer)
+        Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
+                  command: pi_command)
+      end
+
+      def provider_for(handle)
+        BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
+                         env: ENV.to_h.merge(@env))
+      end
+
+      def agent_loop(name, streamer, **opts)
+        handle = opts[:handle] || assignee_handle(name)
+        agent = opts[:agent] || agent_for(name, streamer)
+        provider = opts[:provider] || provider_for(handle)
+        AgentLoop.new(name: name, handle: handle, agent: agent,
+                      task_provider: -> { provider.call },
+                      wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
+                      metrics: opts[:metrics], pause_gate: opts[:pause_gate],
+                      watcher: backlog_watcher)
+      end
+
+      def backlog_watcher
+        Watcher.new(path: File.join(@root, 'backlog'), poll_seconds: wait_seconds)
+      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)
+        @config.assignee_handle(name)
+      end
+
+      def backlog_command
+        @config.backlog_command
+      end
+
+      def wait_seconds
+        @config.wait_seconds
+      end
+
+      def pi_command
+        @config.pi_command
+      end
+
+      def parse_pi_flags
+        @config.pi_flags
+      end
+    end
+  end
+end

data/lib/letsdo/cli.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require 'shellwords'
-require_relative 'cli/launch'
 require_relative 'cli/init'
+require_relative 'cli/builder'
 
 module Letsdo
   # Command-line argument parsing and running an agent orchestrator loop.
@@ -21,12 +20,10 @@ 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
 
     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 +32,11 @@ module Letsdo
     end
 
     def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
-      @env = env
       @stdout = stdout
       @stderr = stderr
-      @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)
@@ -51,7 +47,7 @@ module Letsdo
       return init_command(argv) if argv.include?('--init')
       return unknown_option(arg) if arg.start_with?('-')
 
-      run_agent(arg)
+      @builder.run(arg)
     end
 
     private
@@ -85,47 +81,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 +90,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,71 @@
+# 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, PiRunner 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'
+
+    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 PiRunner::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
+
+    # Whether [letsdo] traces are enabled in PiRunner and AgentLoop.
+    def debug?
+      @env['LETSDO_DEBUG'] == '1'
+    end
+  end
+end

data/lib/letsdo/output_streamer.rb

@@ -37,10 +37,14 @@ module Letsdo
     end
 
     def finish
-      return unless @last_char && @last_char != "\n"
-
-      text_sink.write("\n")
-      text_sink.flush unless @log
+      if @last_char && @last_char != "\n"
+        text_sink.write("\n")
+        text_sink.flush unless @log
+      end
+      # Reset so the next run's finish is a no-op unless new text arrived —
+      # otherwise a tool-only run after a text run writes a spurious blank
+      # line (TASK-77).
+      @last_char = nil
     end
 
     private

data/lib/letsdo/pi_runner.rb

@@ -30,7 +30,7 @@ module Letsdo
       @command = opts.fetch(:command, COMMAND)
       @pending_tools = {}
       @reaped_status = nil
-      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
+      @debug = opts[:debug].nil? ? (opts[:config] || Config.new).debug? : opts[:debug]
     end
 
     def run

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

@@ -7,11 +7,9 @@ module Letsdo
       private
 
       def input_loop
-        with_raw_input do
-          repaint
-          @last_repaint = @clock.call
-          loop { break if @stop || !poll_once }
-        end
+        repaint
+        @last_repaint = @clock.call
+        loop { break if @stop || !poll_once }
       rescue StandardError
         nil
       end

data/lib/letsdo/tui/session.rb

@@ -25,8 +25,7 @@ module Letsdo
       def run(&work)
         install_winch_handler
         @terminal.enter
-        start_input_thread
-        work.call
+        run_work(&work)
       rescue Letsdo::Stopped
         0
       ensure
@@ -35,6 +34,13 @@ module Letsdo
         restore_winch_handler
       end
 
+      def run_work(&work)
+        with_raw_input do
+          start_input_thread
+          work.call
+        end
+      end
+
       private
 
       def assign_identity(opts)
@@ -68,6 +74,10 @@ module Letsdo
         @input_thread = nil
       end
 
+      # Enters raw mode on the keyboard for the duration of the block. Held
+      # by the main thread (not the killable input thread) so the terminal
+      # state is restored on every quit path — a killed input thread would
+      # leave the shared tty in raw mode and break the calling shell (TASK-83).
       def with_raw_input(&block)
         if @input.stdin.tty? && @input.stdin.respond_to?(:raw)
           @input.stdin.raw(&block)

data/lib/letsdo/tui/terminal.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'tty-cursor'
-
 module Letsdo
   module Tui
     # Thin wrapper over the terminal: alternate screen, cursor handling and
@@ -36,19 +34,28 @@ module Letsdo
 
       # Enters the alternate screen and hides the cursor.
       def enter
-        write(ENTER_ALT_SCREEN + TTY::Cursor.hide)
+        write(ENTER_ALT_SCREEN + cursor.hide)
       end
 
       # Shows the cursor and leaves the alternate screen.
       def leave
-        write(TTY::Cursor.show + LEAVE_ALT_SCREEN)
+        write(cursor.show + LEAVE_ALT_SCREEN)
       end
 
       # Repaints the whole frame: cursor to the top left, then the frame.
       #
+      # Row separators are written as CRLF (\r\n), never bare LF. The TUI
+      # input thread holds stdin in io-console raw mode for the whole
+      # session, and raw mode clears OPOST on the shared tty — without it a
+      # bare \n no longer implies a carriage return, so every row after the
+      # first would start at the previous row's end column and the frame
+      # would wrap/scroll into the "blank activity pane" scramble (TASK-82).
+      # Explicit CRLF renders correctly both in raw mode and on terminals
+      # whose ONLCR already expands \n (a doubled CR is harmless).
+      #
       # @param frame [String] the rendered screen (see Letsdo::Tui::Renderer)
       def render(frame)
-        write(HOME + frame)
+        write(HOME + frame.gsub("\n", "\r\n"))
       end
 
       # The current terminal size.
@@ -61,6 +68,14 @@ module Letsdo
 
       private
 
+      # Loaded lazily (like tty-screen/tty-reader) so requiring letsdo on a
+      # clean Ruby loads no tty-* gems — only the interactive TTY path needs
+      # them (TASK-78).
+      def cursor
+        require 'tty-cursor' unless defined?(TTY::Cursor)
+        TTY::Cursor
+      end
+
       def write(text)
         @stream.write(text)
         @stream.flush

data/lib/letsdo/version.rb

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

data/lib/letsdo/watcher.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'fiddle/import'
+
+module Letsdo
+  # OS file-change watcher for the backlog folder.
+  #
+  # On Linux it subscribes to inotify (via Fiddle, no external gem) and wakes
+  # as soon as a backlog entry changes; everywhere else it degrades to the
+  # same periodic polling a plain sleeper would do. Either way the wait is
+  # interruptible — a signal trap raising Letsdo::Stopped breaks the
+  # underlying IO.select — and an internal self-pipe lets #wake interrupt a
+  # blocked #wait from another thread.
+  class Watcher
+    # inotify event masks we subscribe to (Linux <sys/inotify.h>).
+    IN_ACCESS       = 0x00000001
+    IN_MODIFY       = 0x00000002
+    IN_ATTRIB       = 0x00000004
+    IN_CLOSE_WRITE  = 0x00000008
+    IN_CLOSE_NOWRITE = 0x00000010
+    IN_OPEN         = 0x00000020
+    IN_MOVED_FROM   = 0x00000040
+    IN_MOVED_TO     = 0x00000080
+    IN_CREATE       = 0x00000100
+    IN_DELETE       = 0x00000200
+    IN_DELETE_SELF  = 0x00000400
+    IN_MOVE_SELF    = 0x00000800
+
+    RELEVANT_MASK = IN_CREATE | IN_MODIFY | IN_CLOSE_WRITE | IN_DELETE |
+                    IN_MOVED_FROM | IN_MOVED_TO | IN_DELETE_SELF | IN_MOVE_SELF
+
+    EXCLUDED_DIR = '.locks'
+
+    # @param path [String] the watched folder (its direct entries)
+    # @param poll_seconds [Float] fallback poll interval / select timeout
+    def initialize(path:, poll_seconds: 10.0)
+      @poll_seconds = poll_seconds
+      @wake_r, @wake_w = IO.pipe
+      @backend = build_backend(path)
+    end
+
+    # Blocks until a relevant backlog change, an explicit #wake, or the poll
+    # timeout. Irrelevant events (e.g. .locks churn) keep the wait going for
+    # the remainder of the timeout.
+    #
+    # @return [Symbol] :change, :wake, or :timeout
+    def wait(timeout = @poll_seconds)
+      deadline = monotonic + timeout
+      loop do
+        result = wait_once(deadline)
+        return result if result
+      end
+    end
+
+    # Interrupts a blocked #wait from another thread.
+    def wake
+      @wake_w.write_nonblock('.')
+    rescue IO::WaitWritable, Errno::EPIPE
+      nil
+    end
+
+    def close
+      @backend&.close
+      close_io(@wake_w)
+      close_io(@wake_r)
+    end
+
+    private
+
+    def wait_once(deadline)
+      remaining = deadline - monotonic
+      return :timeout if remaining <= 0
+
+      ready = IO.select(read_fds, nil, nil, remaining)
+      return :timeout if ready.nil?
+      return :wake if wake_ready?(ready)
+
+      @backend.relevant_event? ? :change : nil
+    end
+
+    def read_fds
+      fds = [@wake_r]
+      fds << @backend.io if @backend
+      fds
+    end
+
+    def wake_ready?(ready)
+      return false unless ready.first.include?(@wake_r)
+
+      drain_wake
+      true
+    end
+
+    def drain_wake
+      @wake_r.read_nonblock(4096)
+    rescue IO::WaitReadable, EOFError
+      nil
+    end
+
+    def build_backend(path)
+      InotifyBackend.new(path, RELEVANT_MASK)
+    rescue InotifyBackend::Unavailable, Fiddle::DLError
+      nil
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def close_io(io)
+      io.close unless io.nil? || io.closed?
+    rescue IOError
+      nil
+    end
+
+    # Linux inotify backend. Construction raises InotifyBackend::Unavailable
+    # when inotify is missing or the watch cannot be set up, so the watcher
+    # falls back to polling through its self-pipe timeout.
+    class InotifyBackend
+      # libc inotify bindings via Fiddle (no external gem).
+      module Lib
+        extend Fiddle::Importer
+        dlload Fiddle.dlopen(nil)
+        extern 'int inotify_init1(int)'
+        extern 'int inotify_add_watch(int, const char*, uint32_t)'
+      end
+
+      # Signals that inotify is unavailable and the watcher should fall back.
+      class Unavailable < StandardError; end
+
+      IN_CLOEXEC = 0x00080000
+      EVENT_HEADER_SIZE = 16
+
+      attr_reader :io
+
+      def initialize(path, mask)
+        fd = Lib.inotify_init1(IN_CLOEXEC)
+        guard(fd)
+        @io = IO.new(fd, 'r', autoclose: true)
+        guard(Lib.inotify_add_watch(fd, path, mask))
+      rescue Unavailable, Fiddle::DLError
+        @io&.close
+        raise Unavailable
+      end
+
+      # Drains pending events and reports whether any relevant (non-.locks)
+      # entry changed.
+      def relevant_event?
+        buffer = @io.read_nonblock(8192)
+        parse_relevant(buffer)
+      rescue IO::WaitReadable, EOFError
+        false
+      end
+
+      def close
+        @io&.close
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def guard(value)
+        raise Unavailable if value.negative?
+      end
+
+      def parse_relevant(buffer)
+        offset = 0
+        relevant = false
+        while offset + EVENT_HEADER_SIZE <= buffer.bytesize
+          _wd, mask, _cookie, len = buffer.byteslice(offset, EVENT_HEADER_SIZE).unpack('L4')
+          name = buffer.byteslice(offset + EVENT_HEADER_SIZE, len).to_s.sub(/\0.*/m, '')
+          relevant ||= relevant_mask?(mask) && !excluded?(name)
+          offset += EVENT_HEADER_SIZE + len
+        end
+        relevant
+      end
+
+      def relevant_mask?(mask)
+        (mask & Watcher::RELEVANT_MASK) != 0
+      end
+
+      def excluded?(name)
+        name == Watcher::EXCLUDED_DIR || name.start_with?("#{Watcher::EXCLUDED_DIR}/")
+      end
+    end
+  end
+end

data/lib/letsdo.rb

@@ -22,6 +22,7 @@
 
 require_relative 'letsdo/version'
 require_relative 'letsdo/errors'
+require_relative 'letsdo/config'
 require_relative 'letsdo/prompt_store'
 require_relative 'letsdo/default_prompt'
 require_relative 'letsdo/output_streamer'
@@ -30,6 +31,7 @@ require_relative 'letsdo/agent'
 require_relative 'letsdo/capture'
 require_relative 'letsdo/backlog_tasks'
 require_relative 'letsdo/loop'
+require_relative 'letsdo/watcher'
 require_relative 'letsdo/agent_loop'
 require_relative 'letsdo/control'
 require_relative 'letsdo/tui'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsdo
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -79,10 +79,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.77.0
-description: 'letsdo — a local agent worker for Backlog.md/markdown tasks. OOP structure:
-  Letsdo::PromptStore (agents/), Letsdo::OutputStreamer and Letsdo::PiRunner (pi --mode
-  json), Letsdo::Agent (one run), Letsdo::Loop (orchestrator loop), Letsdo::CLI. Minitest
-  tests. Will later be split into a separate repository.'
+description: letsdo turns a plain markdown backlog into a team of autonomous local
+  agents. Each agent is just a prompt file in agents/; run `letsdo <name>` and it
+  works through every open task assigned to that agent, one task per run, and stops
+  cleanly on Ctrl+C. No framework, no hosted platform — the backlog folder is the
+  single source of truth and task data never leaves your machine.
 email:
 - udalov.x@mail.ru
 executables:
@@ -90,9 +91,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - bin/letsdo
+- letsdo.gemspec
 - lib/letsdo.rb
 - lib/letsdo/agent.rb
 - lib/letsdo/agent_loop.rb
@@ -100,8 +103,9 @@ files:
 - lib/letsdo/backlog_tasks.rb
 - lib/letsdo/capture.rb
 - lib/letsdo/cli.rb
+- lib/letsdo/cli/builder.rb
 - lib/letsdo/cli/init.rb
-- lib/letsdo/cli/launch.rb
+- lib/letsdo/config.rb
 - lib/letsdo/control.rb
 - lib/letsdo/default_prompt.rb
 - lib/letsdo/errors.rb
@@ -122,13 +126,15 @@ files:
 - lib/letsdo/tui/session/view.rb
 - lib/letsdo/tui/terminal.rb
 - lib/letsdo/version.rb
+- lib/letsdo/watcher.rb
 homepage: https://github.com/sergio-fry/letsdo
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sergio-fry/letsdo
   source_code_uri: https://github.com/sergio-fry/letsdo
+  bug_tracker_uri: https://github.com/sergio-fry/letsdo/issues
   changelog_uri: https://github.com/sergio-fry/letsdo/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/sergio-fry/letsdo/blob/main/README.md
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org
 rdoc_options: []
@@ -138,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/letsdo/cli/launch.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-module Letsdo
-  # Builds the agent, provider, and orchestrator loop for CLI run paths.
-  module CLILaunch
-    private
-
-    def run_agent_plain(name)
-      streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
-      agent_loop(name, streamer, stderr: @stderr).run
-    end
-
-    def run_agent_tui(name)
-      ctx = tui_context(name)
-      session = Tui::Session.new(**ctx[:session])
-      session.run { ctx[:loop].run }
-    end
-
-    def tui_context(name)
-      parts = tui_parts(name)
-      {
-        loop: tui_loop(name, parts),
-        session: tui_session_args(name, **parts)
-      }
-    end
-
-    def tui_parts(name)
-      clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
-      handle = assignee_handle(name)
-      log = Tui::LogBuffer.new
-      {
-        clock: clock, handle: handle, log: log,
-        metrics: tui_metrics(name, handle, clock, log),
-        agent: agent_for(name, OutputStreamer.new(log: log)),
-        provider: provider_for(handle),
-        pause_gate: Control::PauseGate.new
-      }
-    end
-
-    def tui_loop(name, parts)
-      agent_loop(name, nil, agent: parts[:agent], provider: parts[:provider],
-                            handle: parts[:handle], stderr: parts[:log],
-                            metrics: parts[:metrics], pause_gate: parts[:pause_gate])
-    end
-
-    def tui_metrics(name, handle, clock, log)
-      Tui::Metrics.new(name: name, handle: handle, clock: clock,
-                       on_run_start: ->(_label) { log.divider })
-    end
-
-    def tui_session_args(name, **parts)
-      {
-        name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:metrics],
-        terminal: Tui::Terminal.new(stream: @stdout),
-        input: Tui::Input.new(stdin: @stdin),
-        refresh: -> { parts[:provider].call },
-        wait_seconds: wait_seconds, clock: parts[:clock],
-        pause_gate: parts[:pause_gate], runner: -> { parts[:agent].runner }
-      }
-    end
-
-    def agent_for(name, streamer)
-      Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
-                command: pi_command)
-    end
-
-    def provider_for(handle)
-      BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
-                       env: ENV.to_h.merge(@env))
-    end
-
-    def agent_loop(name, streamer, **opts)
-      handle = opts[:handle] || assignee_handle(name)
-      agent = opts[:agent] || agent_for(name, streamer)
-      provider = opts[:provider] || provider_for(handle)
-      AgentLoop.new(name: name, handle: handle, agent: agent,
-                    task_provider: -> { provider.call },
-                    wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
-                    metrics: opts[:metrics], pause_gate: opts[:pause_gate])
-    end
-  end
-end