letsdo 0.4.0 → 0.5.0

data/docs/usage.md

@@ -0,0 +1,295 @@
+# letsdo — usage guide
+
+This guide walks through running letsdo end to end: prerequisites, install,
+the first run, what a session looks like (plain line-stream and TUI), the
+orchestrator loop semantics, and how to run several agents at once.
+
+- [Prerequisites](#prerequisites)
+- [Install](#install)
+- [Project layout](#project-layout)
+- [First run](#first-run)
+- [A session in plain mode](#a-session-in-plain-mode)
+- [The interactive TUI](#the-interactive-tui)
+- [How the loop behaves](#how-the-loop-behaves)
+- [Running several agents](#running-several-agents)
+- [Environment self-check (doctor)](#environment-self-check-doctor)
+- [Exit codes](#exit-codes)
+- [Next steps](#next-steps)
+
+## Prerequisites
+
+- **Ruby >= 3.0**.
+- The **pi agent CLI** on `PATH` — the AI backend that actually runs each
+  agent (`pi --mode json`). Override the command with `LETSDO_PI_COMMAND`
+  (see the [configuration reference](config.md)).
+- The **Backlog.md CLI** (`backlog`) on `PATH` — the task provider reads the
+  runnable open tasks assigned to an agent via
+  `backlog task list --assignee <handle> --ready --sort priority`. Override
+  with `LETSDO_BACKLOG_COMMAND`.
+
+Tests and the gem build use only Ruby's bundled default gems (Minitest,
+Rake) — no `bundle install` needed.
+
+## Install
+
+Build and install the gem from the repository:
+
+```sh
+git clone git@github.com:sergio-fry/letsdo.git
+cd letsdo
+gem build letsdo.gemspec
+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
+cd letsdo
+./bin/letsdo --version
+```
+
+## Project layout
+
+letsdo works in a Backlog.md project root — a folder that holds your
+`backlog/` tasks and your `agents/` prompts:
+
+```
+your-backlog-project/
+├── backlog/            # the Backlog.md tasks (the single source of truth)
+├── agents/             # one prompt file per agent: agents/<name>.md
+└── ...                 # anything else — docs, code, etc.
+```
+
+The project root defaults to the current working directory and can be set
+explicitly with `LETSDO_ROOT`.
+
+## First run
+
+An agent is just a prompt file. Create one, then run the agent:
+
+```sh
+cd your-backlog-project
+
+# Option 1: scaffold a starter prompt, then customize it
+letsdo developer --init           # writes agents/developer.md, never runs the agent
+
+# Option 2: write agents/developer.md by hand
+# (see the prompt-authoring guide for what a good prompt contains)
+
+# Run the agent: it works through all open tasks assigned to @developer
+letsdo developer
+```
+
+No prompt file yet? The agent still runs on the built-in default prompt and
+letsdo tells you once how to create your own:
+
+```
+$ letsdo newcomer
+letsdo: no prompt for newcomer at /home/user/backlog-project/agents/newcomer.md
+letsdo: using the built-in default prompt (create a prompt file with 'letsdo newcomer --init')
+```
+
+`--init` never overwrites an existing prompt and never runs the agent: it
+fails with exit 1 when `agents/<name>.md` already exists or the name is
+unsafe (contains `/` or `\`, or is `.`/`..` — nothing is ever written
+outside `agents/`). Both argument orders work: `letsdo <name> --init` and
+`letsdo --init <name>`.
+
+## A session in plain mode
+
+When stdout is **not** a terminal (pipes, CI, `TERM=dumb`), letsdo prints a
+plain line stream:
+
+- **stdout** — only the agent's answer text, as it is generated.
+- **stderr** — service and tool lines with a shared `HH:MM:SS` prefix:
+
+  ```
+  HH:MM:SS ⚙ tool_name: arguments     tool call (bash → the command, read/write/edit → the path)
+  HH:MM:SS ✓ tool_name: done (3s)     tool completion, success
+  HH:MM:SS ✖ tool_name: error (3s)    tool completion, error
+  ```
+
+  Tool result bodies are never printed — the call line and its one-line
+  completion are the whole tool story, so the stream stays readable.
+
+- Loop service messages on stderr, e.g.:
+
+  ```
+  letsdo: developer has 3 open task(s)
+  letsdo: running developer for TASK-42
+  letsdo: no open tasks for developer, retrying in 10s
+  letsdo: backlog unavailable, retrying in 10s - run `letsdo doctor` to diagnose
+  letsdo: stopped
+  ```
+
+  When the backlog stays unreadable, only the first message of a run
+  carries the `letsdo doctor` hint; later retries repeat the short line.
+
+Stop the loop with `Ctrl+C` (`SIGINT`; `SIGTERM` and `SIGHUP` — terminal
+closed — work too) — a running pi child is terminated and the process
+exits with code 0. With `LETSDO_DEBUG=1` the loop additionally traces
+`[letsdo] loop: ...` decisions to stderr.
+
+### Pause and quit in plain mode
+
+When stdin is still a terminal (for example `letsdo developer > run.log`,
+where stdout is redirected but the keyboard is live), plain mode reads the
+same control keys as the TUI:
+
+| Key | Action |
+| --- | --- |
+| `p` | pause/resume: mid-run the running pi child is suspended at the kernel level (SIGSTOP); a second `p` resumes it (SIGCONT). Between runs the next task is held until resume. A no-op when nothing is running |
+| `q` | stop — identical to `Ctrl+C`: the pi child is terminated, the process exits with code 0 |
+
+The control reader writes nothing, so the plain stream stays
+byte-identical (no escape codes, no echoed input). When stdin is **not** a
+terminal (a pipe, `</dev/null`, CI), the reader is never started and the
+loop is stopped only by `SIGINT`/`SIGTERM`/`SIGHUP`.
+
+## The interactive TUI
+
+When stdout **and** stdin are terminals and `TERM` is not `dumb`, `letsdo
+<name>` starts a full-screen interface instead of the line stream:
+
+```
+letsdo · developer (@developer)            session 00:12:34
+done 3 · left 2 · task TASK-42 · 00:03:21
+├──────────────────────────────────────────────────────────┤
+…scrollable combined log: agent text, tool lines and loop
+ service messages in arrival order, newest at the bottom…
+↑/↓ PgUp/PgDn scroll · p pause · r refresh · q quit   (p resume while paused)
+```
+
+- **Header** — agent identity (`letsdo · <name> (@handle)`) and the session
+  timer (monotonic, ticks every second).
+- **State line** — tasks done in this session, tasks left (from the latest
+  backlog query), and either the running task with its elapsed time, a
+  waiting reason (`no open tasks (retry in 10s)` / `backlog unavailable
+  (retry in 10s)`), or `PAUSED` while the agent is suspended.
+- **Stream** — one combined log of everything the agent produces: answer
+  text deltas, tool lines and loop messages, exactly as OutputStreamer
+  emits them. The view follows the newest line automatically (tail -f).
+  While paused the frame freezes but the log keeps buffering, so nothing
+  is lost.
+- **Footer** — the key map; the `p` hint says `p pause` while the agent
+  runs and `p resume` while it is suspended.
+
+Keys:
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` | scroll one line (scrolling up leaves auto-follow) |
+| `PgUp` / `PgDn` | scroll one page |
+| `Home` / `End` | jump to top / back to the newest line (auto-follow) |
+| `p` | pause/resume the agent: mid-run the running pi is suspended at the kernel level (SIGSTOP — model generation and tool executions freeze, the frame shows `PAUSED`, the log keeps buffering); between runs the next task is held until resume. A second `p` resumes (SIGCONT). The footer flips between `p pause` and `p resume` |
+| `r` | immediate backlog re-query (updates the "left" counter) |
+| `q` | quit — identical to a stop signal: the pi child is terminated, the terminal is restored, exit code 0 |
+| `Ctrl+C` | same as `q` inside the TUI |
+
+Resizes (`SIGWINCH`) repaint the frame without corruption. Every exit path —
+quit, signal, agent loop end — restores the terminal (alternate screen
+left, cursor back). Inside tmux the window is labeled with the agent name
+for the whole session, so side-by-side agent panes stay distinguishable;
+the previous label (and automatic-rename) returns on exit. The TUI only
+renders when it is safe to do so; in any
+other context the output is byte-identical to the plain line stream, which
+is what keeps CI and pipes deterministic.
+
+## How the loop behaves
+
+`letsdo <name>` runs an orchestrator loop:
+
+1. **Query** — fetch all open tasks assigned to `@<name>` via the backlog
+   CLI (the assignee handle comes from `AGENT_ASSIGNEE_HANDLE`, default
+   `@<name>`).
+2. **Run** — take the next task and run the agent on it. **One run = one
+   task**; the agent must not pick up more than one task per run.
+3. **Repeat** — when a run finishes, query again.
+4. **Wait** — when no tasks are open (or the backlog is unreadable), wait
+   the retry interval (10 s by default, see `LETSDO_WAIT_SECONDS`) and
+   query again. An unreadable backlog pauses instead of crashing.
+5. **Stop** — `Ctrl+C` / `SIGTERM` / `SIGHUP` (or `q` in the TUI, and on a
+   terminal stdin in plain mode) stops the
+   loop immediately: the running pi child is terminated (even when it was
+   paused — SIGCONT comes before SIGTERM), the terminal is restored, exit
+   code 0.
+
+The waiting is interruptible — a stop signal unwinds the loop right away
+instead of waiting out the retry interval. A non-zero agent exit code is
+reported but does not stop the loop.
+
+Pause (`p` in the TUI or in plain mode on a terminal stdin) between runs
+sets a gate the loop polls before starting the next run: while paused, no
+new task is started even when the backlog has open ones; resume lets the
+queued task run.
+
+## Running several agents
+
+Agents run as separate processes, each with its own loop and its own
+assignee handle:
+
+```sh
+letsdo developer &   # works on @developer tasks
+letsdo analyst   &   # works on @analyst tasks
+```
+
+They coordinate through the shared backlog — nothing else in common. Any
+number of agents can run simultaneously; the backlog folder is the single
+source of truth.
+
+When the agents run in tmux panes, a TUI session labels its window with the
+agent name (`letsdo developer` → window `developer`) and restores the
+previous label on exit. tmux's automatic-rename is disabled for the session
+and restored afterwards, so the label stays put instead of being overwritten
+with the process name (`ruby`). Outside tmux nothing is written and the tmux
+binary is never invoked.
+
+## Environment self-check (doctor)
+
+`letsdo doctor` checks whether the environment can actually run the loop
+and prints one line per check with a status tag and an actionable hint:
+
+```
+$ letsdo doctor
+[ OK ] ruby 4.0.2 (>= 3.3)
+[ OK ] pi command found: pi
+[ OK ] backlog command found: backlog
+[ OK ] project root /home/user/backlog-project has backlog/tasks/
+[ OK ] AGENTS.md present at /home/user/backlog-project/AGENTS.md
+[ OK ] agents/ present with 1 prompt(s)
+[INFO] stdout is not a TTY - plain mode
+```
+
+Checks: Ruby version (`>= 3.3`), the `pi` command (`LETSDO_PI_COMMAND`),
+the `backlog` command (`LETSDO_BACKLOG_COMMAND`), `backlog/tasks/` under
+`LETSDO_ROOT`, `AGENTS.md`, a non-empty `agents/`, and whether stdout is a
+TTY (TUI vs plain mode). A missing command or project layout is a `[FAIL]`;
+a missing `AGENTS.md` or `agents/` is a `[WARN]`; the mode line is
+`[INFO]`. Every FAIL and WARN names the fix.
+
+It exits `0` when no check FAILs (warnings do not fail the run) and `1`
+otherwise. `doctor` is a reserved agent name: it always runs the self-check
+and never launches an agent.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | `--version` / `--help`; successful loop run and stop (incl. TUI `q`); `--init` created the prompt; `doctor` found no FAIL |
+| `1` | no arguments; unknown option; `--init` on an existing/unsafe name; `doctor` found at least one FAIL |
+| `2` | the AI backend command is missing (clean message, no backtrace) |
+
+## Next steps
+
+- [Prompt-authoring guide](prompts.md) — what to put into `agents/<name>.md`.
+- [Configuration reference](config.md) — every environment variable, its
+  default and where it is read.
+- The README — why letsdo exists and what it does.

data/letsdo.gemspec

@@ -40,8 +40,10 @@ Gem::Specification.new do |spec|
   # 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.
+  # User-facing guides live in docs/ and are linked from the README, so
+  # they must ship inside the gem for installed copies to be self-contained.
   spec.files         = Dir["lib/**/*.rb", "README.md", "LICENSE",
-                           "CHANGELOG.md", "letsdo.gemspec"]
+                           "CHANGELOG.md", "docs/**/*.md", "letsdo.gemspec"]
   spec.bindir        = "bin"
   spec.executables   = ["letsdo"]
   spec.require_paths = ["lib"]

data/lib/letsdo/agent.rb

@@ -2,40 +2,52 @@
 
 module Letsdo
   # A single agent run: reads the prompt from agents/<name>.md by agent name
-  # (falling back to the built-in default prompt when the file is missing)
-  # and runs pi with that prompt. Returns the pi exit code. There are no
-  # unknown agents — every name runs, with the file prompt when present and
-  # with Letsdo::DefaultPrompt::TEXT otherwise.
+  # (falling back to the built-in default prompt when the file is missing),
+  # prepends the agent's identity (name + backlog assignee handle, TASK-85)
+  # and delegates to the injected backend_factory. Returns the backend exit
+  # code. There are no unknown agents -- every name runs, with the file
+  # prompt when present and with Letsdo::DefaultPrompt::TEXT otherwise.
   #
   # This is the logic of one bin/agent run: a prompt store + an output
-  # streamer + a pi runner. The orchestrator (a loop while tasks exist)
-  # lives in Letsdo::Loop.
+  # streamer + a backend factory. The orchestrator (a loop while tasks
+  # exist) lives in Letsdo::Loop.
   class Agent
     # @param name [String] agent name (agents/<name>.md)
     # @param root [String] project root (agents/ lives there)
-    # @param flags [Array<String>] extra pi flags
+    # @param backend_factory [Proc] callable(prompt:, streamer:, model:) -> backend
+    #        The factory creates a fresh backend for each run.  The prompt
+    #        is read from PromptStore before the call; model comes from the
+    #        agent's front-matter config (nil when absent).  All flag/
+    #        command/env wiring is the factory's job -- Agent keeps no pi
+    #        vocabulary.
     # @param streamer [OutputStreamer] where to print output (by default
     #        the real stdout/stderr)
-    # @param command [String] the pi command (overridable for tests)
-    def initialize(name:, root:, flags: [], streamer: nil, command: PiRunner::COMMAND)
+    # @param handle [String, nil] the agent's backlog assignee handle
+    #        (Config#assignee_handle). Defaults to @<name>; the launcher
+    #        passes the resolved handle so the injected identity always
+    #        matches the handle the backlog tasks are assigned to.
+    def initialize(name:, root:, backend_factory:, streamer: nil, handle: nil)
       @name = name
       @root = root
-      @flags = flags
+      @backend_factory = backend_factory
       @streamer = streamer || OutputStreamer.new
-      @command = command
+      @handle = handle || "@#{name}"
     end
 
-    # The runner of the last/current run — lets the orchestrator terminate
-    # a running pi when the loop is stopped.
-    attr_reader :runner
+    # The backend of the last/current run -- lets the orchestrator
+    # terminate a running backend when the loop is stopped.
+    attr_reader :backend
 
     # Runs the agent once.
     #
-    # @return [Integer] pi exit code
+    # @return [Integer] backend exit code
     def run
       prompt = prompt_store.read(@name) || Letsdo::DefaultPrompt::TEXT
-      @runner = PiRunner.new(prompt: prompt, flags: @flags, streamer: @streamer, command: @command)
-      @runner.run
+      prompt = Letsdo::AgentIdentity.inject(prompt, name: @name, handle: @handle)
+      model  = prompt_store.config(@name)[:model]
+      @backend = @backend_factory.call(prompt: prompt, streamer: @streamer,
+                                       model: model)
+      @backend.run
     end
 
     private

data/lib/letsdo/agent_identity.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # The identity preamble letsdo injects into every agent's system prompt on
+  # launch (TASK-85). The launcher already knows the agent name and its
+  # backlog assignee handle; the prompt template may not. Injecting the two
+  # facts unconditionally keeps every agent aware of who it is and which
+  # tasks are its own — independent of the template content, for the
+  # built-in default prompt and for every custom agents/<name>.md alike.
+  #
+  # The handle is Config#assignee_handle, so the identity an agent reads
+  # matches the handle its backlog tasks are assigned to.
+  module AgentIdentity
+    # The identity block prepended to a prompt. It ends with a blank line so
+    # the original prompt keeps its own heading structure.
+    #
+    # @param name [String] agent name (also the backlog assignee name)
+    # @param handle [String] backlog assignee handle (Config#assignee_handle)
+    # @return [String]
+    def self.preamble(name:, handle:)
+      <<~TEXT
+        # Your identity
+
+        You are the agent `#{name}`. Your backlog assignee handle is `#{handle}`:
+        the tasks assigned to `#{handle}` are yours to work. Identify yourself
+        as this agent and use this handle in every tracked artifact you write.
+
+      TEXT
+    end
+
+    # Prepends the identity block to a prompt, leaving the prompt itself
+    # untouched.
+    #
+    # @param prompt [String] the agent's system prompt (file or default)
+    # @param name [String] agent name
+    # @param handle [String] backlog assignee handle
+    # @return [String] prompt with the identity block at the very top
+    def self.inject(prompt, name:, handle:)
+      "#{preamble(name: name, handle: handle)}#{prompt}"
+    end
+  end
+end

data/lib/letsdo/agent_loop/tasks.rb

@@ -2,31 +2,62 @@
 
 module Letsdo
   # Provider reporting and per-task run wrapping for AgentLoop.
+  #
+  # Retry coordination happens here: the provider batch is reconciled
+  # against the previous attempt (TASK-68), tasks in retry cooldown (or
+  # given up) are filtered out of the batch, and each run records its
+  # outcome for the next reconciliation.
   module AgentLoopTasks
     private
 
     def wrapped_provider
       lambda do
         tasks = @task_provider.call
-        @metrics&.provider_result(tasks&.length)
-        report_provider(tasks)
-        tasks
+        return provider_unavailable if tasks.nil?
+
+        reconcile_attempts(tasks)
+        filtered = reject_cooled_down(tasks)
+        @metrics&.provider_result(filtered.length)
+        report_provider(filtered, raw: tasks.length)
+        filtered
       end
     end
 
-    def report_provider(tasks)
-      if tasks.nil?
-        debug('provider: backlog unavailable')
-        @stderr.puts("letsdo: backlog unavailable, retrying in #{@wait_seconds}s")
-      elsif tasks.empty?
+    def report_provider(tasks, raw: nil)
+      if tasks.empty?
+        report_empty(raw)
+        return
+      end
+
+      debug("provider: #{tasks.length} open task(s)")
+      @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
+      report_backoff(raw - tasks.length) if raw && raw > tasks.length
+    end
+
+    def report_empty(raw)
+      if raw&.positive?
+        debug("provider: #{raw} open task(s) in retry backoff")
+        @stderr.puts("letsdo: no runnable tasks for #{@name} (retry backoff), " \
+                     "retrying in #{@wait_seconds}s")
+      else
         debug('provider: no open tasks')
         @stderr.puts("letsdo: no open tasks for #{@name}, retrying in #{@wait_seconds}s")
-      else
-        debug("provider: #{tasks.length} open task(s)")
-        @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
       end
     end
 
+    def report_backoff(skipped)
+      return unless skipped.positive?
+
+      @stderr.puts("letsdo: #{skipped} open task(s) in retry backoff")
+    end
+
+    def provider_unavailable
+      debug('provider: backlog unavailable')
+      @stderr.puts(unavailable_message)
+      @metrics&.provider_result(nil)
+      nil
+    end
+
     def wrapped_run
       lambda do |task|
         wait_while_paused
@@ -42,21 +73,68 @@ module Letsdo
       code = @run_one.call(task)
       debug("agent run exit #{code}")
       @stderr.puts("letsdo: #{@name} exited with code #{code}") if code != 0
+      @last_attempted[task_key(task)] = code
     ensure
-      @metrics&.run_finished
+      @metrics&.run_finished(code)
     end
 
     def task_label(task)
-      id = task.respond_to?(:[]) ? task['id'] : nil
+      id = task.respond_to?(:id) ? task.id : nil
       return id.to_s unless id.nil? || id.to_s.empty?
 
       task.to_s
     end
 
+    def task_key(task)
+      task_label(task)
+    end
+
     def wait_while_paused
       return unless @pause_gate
 
       @sleeper.call(AgentLoop::PAUSE_POLL_SECONDS) while @pause_gate.paused?
     end
+
+    # Compare tasks from the previous run batch with the fresh provider
+    # result: tasks still open are failures, tasks gone are successes.
+    # Tasks already in retry cooldown (or given up) were skipped and are
+    # NOT re-recorded as failed.
+    def reconcile_attempts(tasks)
+      return unless @last_attempted
+
+      fresh = tasks.to_h { |t| [task_key(t), true] }
+      @last_attempted.each_key { |key| reconcile_key(key, fresh) }
+      @last_attempted.clear
+    end
+
+    def reconcile_key(key, fresh)
+      if fresh.key?(key)
+        @retry_policy.record_failure(key)
+        log_give_up(key) if @retry_policy.failures(key) >= @retry_policy.max_retries
+      else
+        @retry_policy.record_success(key)
+      end
+    end
+
+    # Filters tasks that must not be attempted this batch (retry cooldown
+    # or give-up). A filtered task is also dropped from the attempted-set so
+    # the next reconciliation does not re-record it as failed.
+    def reject_cooled_down(tasks)
+      return tasks if tasks.nil? || tasks.empty?
+
+      tasks.reject do |task|
+        key = task_key(task)
+        cooled = @retry_policy.cooldown?(key) || @retry_policy.gave_up?(key)
+        @last_attempted.delete(key) if cooled
+        cooled
+      end
+    end
+
+    def log_give_up(task_key)
+      message = "letsdo: giving up on #{task_key} after " \
+                "#{@retry_policy.failures(task_key)} failed runs - " \
+                'task stays open, next session will retry it'
+      @stderr.puts(message)
+    end
   end
 end

data/lib/letsdo/agent_loop.rb

@@ -18,8 +18,7 @@ module Letsdo
     end
 
     def run
-      @loop = build_loop
-      install_signal_handlers
+      prepare_run
       debug("loop start (agent=#{@name}, handle=#{@handle}, wait=#{@wait_seconds}s)")
       run_until_stopped
       debug('loop stopped')
@@ -30,6 +29,15 @@ module Letsdo
       restore_signal_handlers
     end
 
+    # The `letsdo doctor` hint rides on the first unavailable backlog call
+    # of a run only: later nils repeat the same diagnosis, and a wall of
+    # hints would just add noise (TASK-93).
+    def unavailable_message
+      hint = @unavailable_hinted ? '' : ' - run `letsdo doctor` to diagnose'
+      @unavailable_hinted = true
+      "letsdo: backlog unavailable, retrying in #{@wait_seconds}s#{hint}"
+    end
+
     def close_watcher
       @watcher&.close
     end
@@ -38,8 +46,14 @@ module Letsdo
       warn("[letsdo] loop: #{message}") if @debug
     end
 
+    # Stop the running backend immediately.  The signal handler is
+    # invoked from the main thread (Ruby 4.0) or from a dedicated signal
+    # thread (3.x fallback via AGENT_SIGNAL_THREAD=1).  Thread.raise
+    # works reliably on CRuby 4.0: M:N fibers make threads interruptible
+    # everywhere, so a trap handler may safely raise Letsdo::Stopped on
+    # the main thread to unwind the current run.
     def on_signal(_signum)
-      @agent&.runner&.terminate_now
+      @agent&.backend&.terminate_now
       raise Letsdo::Stopped
     end
 
@@ -50,9 +64,28 @@ module Letsdo
       @run_one = opts[:run_one] || ->(_task) { @agent.run }
       @wait_seconds = opts.fetch(:wait_seconds, 10.0)
       @stderr = opts.fetch(:stderr, $stderr)
+      @retry_policy = build_retry_policy(opts)
+      @last_attempted = {}
       assign_control_opts(opts)
     end
 
+    def prepare_run
+      @loop = build_loop
+      install_signal_handlers
+      @unavailable_hinted = false
+    end
+
+    def build_retry_policy(opts)
+      return opts[:retry_policy] if opts[:retry_policy]
+
+      Letsdo::RetryPolicy.new(
+        base: opts.fetch(:retry_base, @wait_seconds),
+        cap: opts.fetch(:retry_cap, Letsdo::RetryPolicy::DEFAULT_CAP),
+        max_retries: opts.fetch(:max_retries, Letsdo::RetryPolicy::DEFAULT_MAX_RETRIES),
+        clock: opts[:clock]
+      )
+    end
+
     def assign_control_opts(opts)
       @metrics = opts[:metrics]
       @pause_gate = opts[:pause_gate]