claude-inbox 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 389bed9e67e4ee7dbcadbd64b1b70e8ca1118e54d2f06dae2d23e53d4acdf5cb
-  data.tar.gz: c3de7db6f528d68cff26d6b55dbae00f34cd5289491ad3b25bbc992f49b1b7b3
+  metadata.gz: 6194693f8175ae0767d58a3f9f90e746122f831a33675c2928e2120ccba4e895
+  data.tar.gz: d1f08c4e9341d115a7775fff9702fef6342b3771b9a76e3bc0fd957af79d04ef
 SHA512:
-  metadata.gz: c619164c4ae1ec60af3f2b86b35f97d7b85ae81983ee807a4654a6eb38cba557956788bae49069368e93dff8a38a158c665be47d44970f3fdb21075958e4fd59
-  data.tar.gz: 47ee2bce01e277e185329a6770627176f1f046733d005aa31df952250a12eeb1816bc0878ae3fb898f4c87e9cdac7ebb8fa75f3038008702cffbff47ba6c34ea
+  metadata.gz: 721c56943e7dbf8155b99c32befb179b471b5f1971ce7031fa9e0d33e747c083fa6a1dfd2441f5d72c6bebc56897ac342bc783abaa36b34bc2eff5aee0ebd7ca
+  data.tar.gz: 7424b14a131fdfd6ff488e2cef38781bbb046b375d847d094ada5be48f6789db5b9135335a3d6592374028f2c92a506235e10e8adfe91fb53cfe4f2d5c6c4fff

data/README.md

@@ -40,7 +40,7 @@ a fullscreen terminal.
 
 `/inbox` opens it, `ctrl+x tab` focuses it and `esc` leaves. The keys are the
 ones below, with `ge` for `G`, `n` `p` for `Tab` `Shift+Tab`, and no `a`,
-`P`, `X`, `Ctrl-x`, `/`, `R` or `U`. `Enter`, or a click on a row, switches to the
+`P`, `X`, `Ctrl-x`, `/`, `R` or `U`, and `s` has no `5`. `Enter`, or a click on a row, switches to the
 session when you attached through `claude-inbox`.
 
 It opens when a session starts. To stop that, set
@@ -50,7 +50,8 @@ It opens when a session starts. To stop that, set
 ## Sections
 
 1. **Pinned.** Rows you pinned with `t`.
-2. **Needs you.** Blocked or failed sessions you haven't attached to yet.
+2. **Needs you.** Blocked or failed sessions, or ones whose pull request has
+   failing checks or changes requested, that you haven't attached to yet.
 3. **Active.** Everything else that's running or not yet settled, including
    interactive terminals.
 4. **Snoozed.** Sorted by wake time. Collapsed.
@@ -59,8 +60,12 @@ It opens when a session starts. To stop that, set
 
 Under each row is what the session is waiting on, what it produced, or its
 status line. A row with a pull request shows it as `#885 open`, `#885 merged`
-and so on. A steady `◌` with `idle · 1 shell` means the agent stopped and is
-waiting on a shell or sub-agent it started.
+and so on, with `✗ checks`, `changes requested` or `conflicts` after it when
+something is wrong, and `+2` after it when the session has two more.
+A steady `◌` with `idle · 1 shell` means the agent stopped
+and is waiting on a shell or sub-agent it started. A `●` marks a session you
+haven't attached to since it got blocked, in red, or finished, in blue; one
+you have attached to since is dimmed, unless `/color` tints it.
 
 ## Keys
 
@@ -78,12 +83,13 @@ Vim bindings. Arrows and the mouse work too.
 | `n` | new session |
 | `N` | pair a phone |
 | `t` | pin / unpin |
-| `s` | snooze: `1` 15m · `2` 1h · `3` tomorrow 9am · `4` until woken |
+| `s` | snooze: `1` 15m · `2` 1h · `3` tomorrow 9am · `4` until woken · `5` custom |
 | `u` | wake a snoozed session, or bring back a settled one |
 | `x` | settle by hand |
 | `a` | set a local alias |
-| `o` | open the pull request in the browser |
+| `o` | open the pull request in the browser; with several, `o` again opens the one that matters, `1`… another |
 | `w` | open the session at claude.ai/code |
+| `y` | copy the pull request url, or the session's address; with several, `y` again copies the one that matters, `1`… another |
 | `P` | link a pull request by hand (empty clears) |
 | `X` | stop the session; `Enter` resumes it later |
 | `Ctrl-x` | delete the session, transcript and worktree for good |
@@ -112,8 +118,8 @@ lists them all.
 A snoozed session wakes when its timer runs out, when you press `u`, or when
 it becomes blocked or failed.
 
-Attaching to a needs-you session moves it to Active until its state changes
-again.
+Attaching to a needs-you session moves it to Active until its state, or its
+pull request's health, changes again.
 
 A session settles when you press `x` or when all its pull requests are merged
 or closed. A session without a pull request only settles by hand.
@@ -149,6 +155,13 @@ covers ssh, the JSON API and an iOS Shortcut.
 Pull requests show up when a session's transcript links to them. Install
 `gh` to keep their state current. Use `P` to link one by hand.
 
+## Notifications
+
+`--notify` sends a macOS notification through
+[terminal-notifier](https://github.com/julienXX/terminal-notifier) when a
+session needs you or finishes. `brew install terminal-notifier` first;
+the first launch asks permission to notify.
+
 ## Usage bars
 
 The header can show your 5-hour and 7-day rate limit usage:

data/lib/claude_inbox/actions.rb

@@ -74,6 +74,13 @@ module ClaudeInbox
       at.positive? && Time.at(at) >= @clock.call - GRACE
     end
 
+    # A preset by name, or the wake time a typed snooze became, which the
+    # relay sends as the epoch's digits.
+    def snooze_choice(choice)
+      return choice.to_sym if SNOOZES.include?(choice)
+      choice.to_i if choice.is_a?(String) && choice.match?(/\A\d+\z/)
+    end
+
     def apply(store, request, keys)
       id = request["id"]
       return false unless keys.include?(id)
@@ -83,8 +90,9 @@ module ClaudeInbox
       when "pin" then store.toggle_pin(id)
       when "acknowledge" then store.acknowledge(id)
       when "snooze"
-        return false unless SNOOZES.include?(request["choice"])
-        store.snooze(id, request["choice"].to_sym)
+        choice = snooze_choice(request["choice"])
+        return false unless choice
+        store.snooze(id, choice)
       else
         return false
       end

data/lib/claude_inbox/agents_client.rb

@@ -179,7 +179,7 @@ module ClaudeInbox
     # merely flagged: attach lands on the session that asked for it, so there
     # is nothing useful to show or act on directly.
     def classify_origins(sessions)
-      pids = sessions.select { |s| s.interactive? && s.pid }.map(&:pid)
+      pids = sessions.filter_map { |s| s.pid if s.interactive? }
       return sessions if pids.empty?
       rows = ps_rows(pids)
       assign_origins(sessions, origins_from(rows), self.class.bridge_ids(rows))

data/lib/claude_inbox/app/browsing.rb

@@ -3,14 +3,17 @@
 module ClaudeInbox
   class App
     # o opens the selected session's pull request and w its claude.ai/code
-    # page, through whatever opens URLs on this platform.
+    # page, through whatever opens URLs on this platform; y copies the one
+    # of those the session has, or its id. With several PRs, o and y ask
+    # which first.
     module Browsing
       private
 
       def open_pr
-        pr = selected_session&.pr
-        return notice("no pull request linked — P sets one") unless pr
-        open_in_browser(pr.url, pr.short)
+        session = selected_session
+        return notice("no pull request linked — P sets one") unless session&.pr
+        return @modal = Dialog::PrPicker.new(:open, session) if session.prs.size > 1
+        open_in_browser(session.pr.url, session.pr.short)
       end
 
       def open_remote
@@ -19,6 +22,34 @@ module ClaudeInbox
         open_in_browser(url, "claude.ai/code")
       end
 
+      def yank
+        session = selected_session
+        return notice("nothing to copy") unless session
+        return @modal = Dialog::PrPicker.new(:copy, session) if session.prs.size > 1
+        copy_to_clipboard(*yank_target(session))
+      end
+
+      def pr_picked
+        kind, pr = @modal.kind, @modal.choice
+        @modal = nil
+        (kind == :open) ? open_in_browser(pr.url, pr.short) : copy_to_clipboard(pr.url, pr.short)
+      end
+
+      def copy_to_clipboard(text, what)
+        in_background do
+          @queue << [:notice, @clipboard.call(text) ? "copied #{what}" : "no clipboard tool found"]
+        end
+      end
+
+      # A link set by hand wins over the scan, as it does once the poll lands.
+      def yank_target(session)
+        linked = @store.pr_for(session.key)
+        return [linked, "#" + linked[%r{/pull/(\d+)}, 1]] if linked
+        return [session.pr.url, session.pr.short] if session.pr
+        return [session.remote_url, session.remote_url] if session.remote_url
+        [session.key, session.key]
+      end
+
       def open_in_browser(url, what)
         opener = RUBY_PLATFORM.include?("darwin") ? "open" : "xdg-open"
         notice("opening #{what}")

data/lib/claude_inbox/app/triaging.rb

@@ -43,6 +43,7 @@ module ClaudeInbox
       end
 
       def snooze_chosen
+        return @modal = Dialog::Prompt.new(:snooze, @modal.id, "") if @modal.choice == :custom
         @store.snooze(@modal.id, @modal.choice)
         @modal = nil
       end
@@ -63,6 +64,10 @@ module ClaudeInbox
         value = @modal.value.strip
         if @modal.kind == :alias
           @store.set_alias(@modal.id, value)
+        elsif @modal.kind == :snooze
+          wake_at = SnoozeTime.parse(value, Time.now)
+          return notice("try 45m, 2h, 3d, 17:00, 5pm, fri, tomorrow or tonight") unless wake_at
+          @store.snooze(@modal.id, wake_at)
         elsif value.empty? || PullRequests.valid_url?(value)
           @store.set_pr(@modal.id, value)
           @poller.soon

data/lib/claude_inbox/app.rb

@@ -13,11 +13,14 @@ require_relative "remote/listener"
 require_relative "new_session_form"
 require_relative "pull_requests"
 require_relative "reaper"
+require_relative "notifier"
 require_relative "poller"
 require_relative "rate_limits"
 require_relative "session_request"
 require_relative "actions"
+require_relative "clipboard"
 require_relative "snapshot"
+require_relative "snooze_time"
 require_relative "switch"
 require_relative "trust"
 require_relative "mod"
@@ -46,9 +49,11 @@ module ClaudeInbox
     # so both are off unless `bin/claude-inbox` switches them on.
     def initialize(client: AgentsClient.new, store: Store.new, pull_requests: PullRequests.new,
       rate_limits: RateLimits.new, reaper: Reaper.disabled, snapshot: Snapshot.disabled, switch: Switch.disabled,
-      actions: Actions.disabled, listen: nil, updater: nil, argv: [], out: $stdout, input: $stdin, color: true,
-      trust: Trust.method(:projects), terminal: Terminal.new(out, input), queue: Queue.new, pane_offer: Mod::Offer.disabled)
+      actions: Actions.disabled, notifier: Notifier.disabled, listen: nil, updater: nil, argv: [], out: $stdout, input: $stdin, color: true,
+      trust: Trust.method(:projects), terminal: Terminal.new(out, input), queue: Queue.new, pane_offer: Mod::Offer.disabled,
+      clipboard: Clipboard.method(:copy))
       @client = client
+      @clipboard = clipboard
       @store = store
       @snapshot = snapshot
       @switch = switch
@@ -63,7 +68,7 @@ module ClaudeInbox
       @input = Input.new(input, out)
       @queue = queue
       @poller = Poller.new(client: client, store: store, pull_requests: pull_requests,
-        reaper: reaper, queue: @queue, snapshot: snapshot, actions: actions)
+        reaper: reaper, queue: @queue, snapshot: snapshot, actions: actions, notifier: notifier)
       @listener = listen ? Remote::Listener.new(client: client, store: store, queue: @queue, **listen) : Remote::Listener.disabled
       @selected = nil
       @row_items = []
@@ -193,6 +198,7 @@ module ClaudeInbox
       case @modal.press(name, key)
       when :cancel then @modal = nil
       when :snooze then snooze_chosen
+      when :pick then pr_picked
       when :confirm
         kind, id = @modal.kind, @modal.id
         @modal = nil
@@ -233,6 +239,7 @@ module ClaudeInbox
       when :link_pr then open_pr_editor
       when :open_pr then open_pr
       when :open_remote then open_remote
+      when :yank then yank
       when :stop then open_confirm(:stop)
       when :delete then open_confirm(:delete)
       when :refresh then @poller.soon

data/lib/claude_inbox/cli.rb

@@ -6,6 +6,7 @@ require_relative "app"
 require_relative "config"
 require_relative "headless"
 require_relative "mod"
+require_relative "notifier"
 require_relative "updater"
 require_relative "writer_lock"
 
@@ -56,9 +57,10 @@ module ClaudeInbox
     def app_options
       opts = options[:fixture] ? fixture_options : live_options
       opts[:color] = options[:color]
+      opts[:notifier] = notifier
       return opts if options[:fixture] || writer_lock.take(role: "inbox")
       opts.merge(store: Store.new(writable: false, relay: Actions.new), reaper: Reaper.disabled,
-        snapshot: Snapshot.disabled, actions: Actions.disabled, pane_offer: Mod::Offer.disabled)
+        snapshot: Snapshot.disabled, actions: Actions.disabled, pane_offer: Mod::Offer.disabled, notifier: Notifier.disabled)
     end
 
     private
@@ -111,7 +113,7 @@ module ClaudeInbox
 
     def headless
       abort "claude-inbox: --headless takes no --fixture" if options[:fixture]
-      Headless.new(client: AgentsClient.new, store: Store.new, updater: updater).run
+      Headless.new(client: AgentsClient.new, store: Store.new, updater: updater, notifier: notifier).run
     end
 
     # Only what a check within the day already found: a cold launch never waits
@@ -154,6 +156,8 @@ module ClaudeInbox
       @updater ||= Updater.new if options[:update_check] && !options[:fixture]
     end
 
+    def notifier = options[:notify] ? Notifier.new : Notifier.disabled
+
     # Held for the life of this process by this reference.
     def writer_lock = (@lock ||= WriterLock.new)
 
@@ -172,6 +176,7 @@ module ClaudeInbox
         p.on("--headless", "Keep the pane's snapshot fresh without a screen") { opts[:headless] = true }
         p.on("--reap", "Delete background sessions idle 14 days") { opts[:reap] = true }
         p.on("--no-color", "Draw without color") { opts[:color] = false }
+        p.on("--notify", "Send a desktop notification when a session needs you or finishes") { opts[:notify] = true }
         p.on("--auto-update", "Install a release found today before launching") { opts[:auto_update] = true }
         p.on("--no-update-check", "Never look for a newer release") { opts[:update_check] = false }
         # --listen-lan wins over --listen, whichever came last.

data/lib/claude_inbox/clipboard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "subprocess"
+
+module ClaudeInbox
+  # Puts text on the system clipboard through the tool this platform has:
+  # pbcopy on macOS, wl-copy or xclip elsewhere.
+  module Clipboard
+    TOOLS = {"pbcopy" => [], "wl-copy" => [], "xclip" => %w[-selection clipboard]}.freeze
+
+    class Failed < StandardError; end
+
+    module_function
+
+    # True once a tool took the text, false when none is on PATH.
+    def copy(text, platform: RUBY_PLATFORM, path: ENV.fetch("PATH", ""), run: Subprocess.method(:capture))
+      argv = command(platform: platform, path: path)
+      return false unless argv
+      result = run.call(*argv, input: text)
+      raise Failed, "#{File.basename(argv.first)} failed: #{result.err.strip}" unless result.success?
+      true
+    end
+
+    # The argv that writes the clipboard here, or nil without a tool on PATH.
+    def command(platform: RUBY_PLATFORM, path: ENV.fetch("PATH", ""))
+      names = platform.include?("darwin") ? %w[pbcopy] : %w[wl-copy xclip]
+      dirs = path.split(File::PATH_SEPARATOR)
+      names.each do |name|
+        dir = dirs.find { |d| File.executable?(File.join(d, name)) }
+        return [File.join(dir, name), *TOOLS[name]] if dir
+      end
+      nil
+    end
+  end
+end

data/lib/claude_inbox/config.rb

@@ -8,7 +8,7 @@ module ClaudeInbox
   module Config
     PATH = File.join(Dir.home, ".config", "claude-inbox", "config")
 
-    def self.argv(typed, path: PATH)
+    def self.argv(typed, path:)
       args(path) + typed
     end
 

data/lib/claude_inbox/dialog.rb

@@ -32,7 +32,8 @@ module ClaudeInbox
         ["1", "15 minutes", :m15],
         ["2", "1 hour", :h1],
         ["3", "tomorrow 9am", :tomorrow_9am],
-        ["4", "until I wake it", :until_woken]
+        ["4", "until I wake it", :until_woken],
+        ["5", "custom", :custom]
       ].freeze
 
       attr_reader :choice
@@ -52,6 +53,44 @@ module ClaudeInbox
       end
     end
 
+    # `o` open and `y` copy on a session with several PRs: the headline
+    # first, and the same key again takes it. The PR is read from `choice`.
+    class PrPicker < Dialog
+      WIDTH = 64
+      KEYS = {open: "o", copy: "y"}.freeze
+      VERBS = {open: "open", copy: "copy"}.freeze
+
+      attr_reader :choice
+
+      def initialize(kind, session)
+        super(kind, session.key)
+        @prs = [session.pr, *session.prs.reject { |pr| pr.equal?(session.pr) }].first(9)
+      end
+
+      def title = " #{VERBS.fetch(kind).capitalize} pull request "
+
+      def lines(width, _caret)
+        (@prs.each_with_index.map { |pr, i| "  #{i + 1}  #{label(pr)}" } +
+          ["", "  #{KEYS.fetch(kind)}  #{VERBS.fetch(kind)} #{@prs.first.short} · esc cancel"])
+          .map { |line| Text.truncate(line, width) }
+      end
+
+      def press(name, key)
+        return :cancel if name == :escape || key == "q"
+        @choice = @prs.first if key == KEYS.fetch(kind) || name == :return || name == :enter
+        @choice = @prs[key.to_i - 1] if key.to_s.match?(/\A[1-9]\z/)
+        @choice && :pick
+      end
+
+      private
+
+      # A bare #190 is ambiguous only once the list spans repos.
+      def label(pr)
+        name = (@prs.map(&:repo).uniq.size > 1) ? pr.qualified : pr.short
+        ["#{name} #{pr.state&.downcase}".strip, pr.trouble, pr.title].compact.join(" · ")
+      end
+    end
+
     # `X` stop, `Ctrl-x` delete and Enter on a remote row all ask first and
     # all take `y`, but the words differ because the outcomes do: read the
     # box before answering.
@@ -118,11 +157,12 @@ module ClaudeInbox
       end
     end
 
-    # `a` alias and `P` pull request: one line of text, read from `value`
-    # once :save comes back. Empty means clear.
+    # `a` alias, `P` pull request and `s` `5` snooze: one line of text, read
+    # from `value` once :save comes back. Empty means clear.
     class Prompt < Dialog
-      TITLES = {alias: " Alias ", pr: " Pull request "}.freeze
-      QUESTIONS = {alias: "  New alias:", pr: "  Pull request URL (empty clears):"}.freeze
+      TITLES = {alias: " Alias ", pr: " Pull request ", snooze: " Snooze "}.freeze
+      QUESTIONS = {alias: "  New alias:", pr: "  Pull request URL (empty clears):",
+                   snooze: "  Wake at (2h, 5pm, fri, tonight):"}.freeze
 
       def initialize(kind, id, value)
         super(kind, id)

data/lib/claude_inbox/headless.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "actions"
+require_relative "notifier"
 require_relative "poller"
 require_relative "pull_requests"
 require_relative "reaper"
@@ -15,13 +16,13 @@ module ClaudeInbox
   # exits at once while an inbox holds the writer lock.
   class Headless
     def initialize(client:, store:, pull_requests: PullRequests.new, actions: Actions.new, snapshot: Snapshot.new,
-      lock: WriterLock.new, updater: nil)
+      lock: WriterLock.new, updater: nil, notifier: Notifier.disabled)
       @lock = lock
       @snapshot = snapshot
       @updater = updater
       @queue = Queue.new
       @poller = Poller.new(client: client, store: store, pull_requests: pull_requests, reaper: Reaper.disabled,
-        queue: @queue, snapshot: snapshot, actions: actions)
+        queue: @queue, snapshot: snapshot, actions: actions, notifier: notifier)
     end
 
     # False when the lock is held, by an inbox or another headless process.

data/lib/claude_inbox/images.rb

@@ -53,7 +53,10 @@ module ClaudeInbox
     end
 
     # ".png", ".jpg", ".gif" or ".webp" by the magic number, or nil.
-    def self.extension(bytes) = MAGIC.find { |_, magic| magic.match?(bytes.b) }&.first
+    def self.extension(bytes)
+      data = bytes.b
+      MAGIC.find { |_, magic| magic.match?(data) }&.first
+    end
 
     CLIPBOARD_PNG = <<~APPLESCRIPT
       on run argv

data/lib/claude_inbox/keymap.rb

@@ -24,7 +24,7 @@ module ClaudeInbox
       "h" => :fold_close,
       "s" => :snooze, "u" => :wake, "a" => :alias, "x" => :settle, "X" => :stop,
       :ctrl_x => :delete,
-      "o" => :open_pr, "P" => :link_pr, "t" => :toggle_pin, "w" => :open_remote,
+      "o" => :open_pr, "P" => :link_pr, "t" => :toggle_pin, "w" => :open_remote, "y" => :yank,
       "R" => :refresh, "U" => :update, "n" => :new_session, "N" => :remote_pairing,
       :tab => :next_section, :back_tab => :prev_section,
       "/" => :filter, :escape => :escape,

data/lib/claude_inbox/mouse.rb

@@ -3,20 +3,20 @@
 module ClaudeInbox
   # Parses SGR mouse reports ("\e[<Cb;Cx;Cy(M|m)", emitted once App turns on
   # \e[?1000h\e[?1006h) into clicks and wheel ticks. Pure: no terminal, no
-  # IO. Row/col are the terminal's own 1-based coordinates, so callers can
-  # index straight into what they just painted.
+  # IO. Row is the terminal's own 1-based row, so callers can index straight
+  # into what they just painted.
   module Mouse
     SEQUENCE = /\e\[<(\d+);(\d+);(\d+)([Mm])/
 
-    Event = Struct.new(:kind, :row, :col)
+    Event = Struct.new(:kind, :row)
 
     # A raw keypress can glue several reports together the same way a fast
     # "esc gg" glues onto one read (see Input#split_keys), so this scans
     # rather than matching once.
     def self.events(raw)
-      raw.scan(SEQUENCE).filter_map do |cb, col, row, type|
+      raw.scan(SEQUENCE).filter_map do |cb, _col, row, type|
         kind = kind_for(cb.to_i, type)
-        Event.new(kind, row.to_i, col.to_i) if kind
+        Event.new(kind, row.to_i) if kind
       end
     end
 

data/lib/claude_inbox/new_session_form.rb

@@ -303,7 +303,7 @@ module ClaudeInbox
 
     def field_label(f)
       on = f.equal?(focused)
-      (on ? @theme.cyan_bold("▶ ") : "  ") + (on ? @p.bold(Text.pad(f.label, 14)) : @p.dim(Text.pad(f.label, 14)))
+      (on ? @theme.yellow_bold("▶ ") : "  ") + (on ? @p.bold(Text.pad(f.label, 14)) : @p.dim(Text.pad(f.label, 14)))
     end
 
     # The cell the cursor sits on, drawn as a block by inverting it: a bar

data/lib/claude_inbox/notifier.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "notifier_app"
+require_relative "subprocess"
+
+module ClaudeInbox
+  # Desktop notifications for --notify: a row that came to need you or a
+  # background session that finished between one poll and the next, said
+  # through terminal-notifier. `diff` decides, `deliver` says it.
+  class Notifier
+    MISSING = "terminal-notifier not found"
+    # The sections a row is heard from: not snoozed, not settled.
+    WATCHED = %i[pinned needs_you active].freeze
+
+    # Marks the one that wants you, so it stands out from a finished one.
+    BADGE = {"needs you" => "🔴 "}.freeze
+
+    Notification = Data.define(:key, :kind, :label, :line) do
+      def message = "#{BADGE[kind]}#{line ? "#{kind}: #{line}" : kind}"
+    end
+
+    def self.disabled = new(enabled: false)
+
+    # The notifications `after` earns over `before`, two Sections of the same
+    # moment: one per row whose alert changed, with the row's own line. A row
+    # that only changed section has nothing new to say: the first gh refresh
+    # un-settles one whose open PR the cache did not know, and a snoozed
+    # row's timer runs out.
+    def self.diff(before, after)
+      was = alerts(before)
+      rows(after).filter_map do |row|
+        kind = alert(row)
+        Notification.new(key: row.key, kind: kind, label: row.label, line: row.session.summary) if kind && was[row.key] != kind
+      end
+    end
+
+    # key => "needs you", "finished" or nil, over every row, snoozed and settled too.
+    def self.alerts(sections) = sections.all.to_h { |row| [row.key, alert(row)] }
+
+    def self.rows(sections) = WATCHED.flat_map { |name| sections[name] }
+
+    # Interactive sessions stay quiet: you are in that terminal.
+    def self.alert(row)
+      return nil unless row.session.background?
+      if row.session.needs_you? then "needs you" unless row.acknowledged?
+      elsif row.session.effective_state == "done" then "finished"
+      end
+    end
+
+    def initialize(app: NotifierApp.new, run: Subprocess.method(:capture), enabled: true)
+      @app = app
+      @run = run
+      @enabled = enabled
+      @primed = false
+      @given_up = false
+    end
+
+    # Sends what `diff` finds, off the calling thread, and yields the one
+    # notice a binary that will not run earns. The first call only primes,
+    # and readies the app: every row already blocked at startup would
+    # otherwise fire at once.
+    def deliver(before, after, &notice)
+      return unless @enabled
+      return prime unless @primed
+      notifications = self.class.diff(before, after)
+      return if notifications.empty? || @given_up
+      Thread.new do
+        notifications.each do |n|
+          r = @run.call(*@app.command, "-title", n.label, "-message", n.message, "-group", n.key)
+          next if r.success?
+          @given_up = true
+          notice&.call((r.status.exitstatus == 127) ? MISSING : "terminal-notifier: #{r.err.lines.first.to_s.strip}")
+          break
+        end
+      end
+    end
+
+    private
+
+    def prime
+      @primed = true
+      Thread.new { @app.prepare }
+    end
+  end
+end