lux-hammer 0.3.22 → 0.3.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df3eb16fdf398c03d043585e48e4f9792d09b4427f0a0733eefa9725f1f97b0d
-  data.tar.gz: d36961cbeb0e10d44fa5119629a436aeed2d16fa384fbc0256dfb9cf1f9893ec
+  metadata.gz: 74dd44bca6cf689dcfe0396d90e05e51b0605821314fb6d5b742502662f4e8e8
+  data.tar.gz: a84eaa4fcce83f951905bab3419d18adfcce409cd0f9d2f23db910569443a2ce
 SHA512:
-  metadata.gz: 8429a1a3a276bca73309522c57c78f3283a78ed327cb0d4354757c3bccd06bf5a0202af888f5ebfa8e66c01850cb4cf927317b8c68970a18b3a9370ff5a70516
-  data.tar.gz: 68ffb3baf274099eae5e3c3398f77bbda5163c3867980772c737e06d211a8ce26de08702f51e53b8d27c067703eedaac482f5e4f7c2b133e638272ef10b319c6
+  metadata.gz: 044a31c525aba212012888f39d938fa37dc2e69e59097fa10f1dda53723b0a267dae2dad0e77887c19ad801a64fcb47e03b8aa95d916b04474d5239628a9b8f0
+  data.tar.gz: 3ec9940429c06e4bfb00669184fe3d4f78fff0ed693f857fcd37c682bf89b70a214f3a7e92e24826a1ab5889c62de26f05e0f9b78fe22c1c65b12227d4a18681

data/.version

@@ -1 +1 @@
-0.3.22
+0.3.23

data/recipes/lib/llm/plan.rb

@@ -455,11 +455,10 @@ module LlmPlan
       end
     end
 
-    # Columns at which the clause and the counts start, so rows line up.
-    # Problem rows share the path column, or they run into their own message.
+    # Columns at which the clause and the counts start, so rows line up. Taken
+    # from every planned path, so problem rows share the column too.
     def width
-      @width ||= (groups.flat_map { |group| group.files.map(&:path) + group.problems.map { |d| d.entry.path } }
-                        .map(&:length).max || 0) + 4
+      @width ||= (@outcome.bundle.entries.map { |entry| entry.path.length }.max || 0) + 4
     end
 
     def note_width
@@ -560,18 +559,28 @@ module LlmPlan
 
     private
 
-    # What a run did, in the past tense.
+    # What a run did, in the past tense. Sorted by path, same as the manifest -
+    # a landed list is read the same way a planned one is.
     def result
       rows = []
-      @outcome.applied.each { |applied| rows << ["  ok    #{applied.entry.path} (#{applied.note})", :green] }
-      @outcome.skipped.each { |entry|   rows << ["  ok    #{entry.path} (already applied)", :gray] }
-      rows << ['', nil] if rows.any? && @outcome.drifted.any?
+      landed = @outcome.applied.map { |applied| [applied.entry, applied.note] } +
+               @outcome.skipped.map { |entry| [entry, 'already applied'] }
+
+      unless landed.empty?
+        rows << [paint('Landed', :green), nil]
+        landed.sort_by { |entry, _| entry.path }.each { |entry, note| rows << [landed_row(entry, note), nil] }
+        rows << ['', nil]
+      end
 
       @outcome.drifted.each { |drifted| rows.concat drift_block(drifted) }
       rows.concat summary
       rows
     end
 
+    def landed_row(entry, note)
+      "  #{paint(entry.path.ljust(@manifest.width), :cyan)}#{paint(note, :gray)}"
+    end
+
     # What a run would do, for a human to approve. One line per file, grouped
     # and sorted, each with its own clause. Never counts of lines touched -
     # that says nothing about whether the change is the right one.

data/recipes/lib/llm/wrap.rb

@@ -17,6 +17,12 @@ require 'shellwords'
 # so text the program inserts for you (history recall, autocomplete, menu
 # picks) never shows up - that is the price of working with any program at all.
 #
+# A line starting with ! is taken over: it never reaches the child at all, it
+# runs in a shell here, and its output is shown in the bar (Bang, Pane). The
+# round trip that saves is the point - `!git status` typed at an agent is a
+# tool call, a permission check and a model turn for something the shell
+# answers in milliseconds, and this way it costs no context either.
+#
 # Wrapping a program hides it: the child lives on our PTY, in its own session,
 # so anything outside looking at the terminal sees this process and not the
 # program. Terminals that watch what is running in a pane - Herdr naming a tab,
@@ -45,6 +51,10 @@ module LlmWrap
   DRAIN_MAX ||= 262_144
   MAX_BLOCK ||= 1.5
 
+  # The bar grows to show ! output, and this is what it may never take: the
+  # child keeps at least this many rows whatever the output was.
+  MIN_CHILD ||= 5
+
   # Introducers of the escape sequences that carry a string payload:
   # OSC ], DCS P, SOS X, PM ^, APC _. They run to BEL or ST rather than to a
   # final byte, so both stream parsers here - KeyBuffer on the way in, OutScan
@@ -100,6 +110,87 @@ module LlmWrap
     end
   end
 
+  # Drawing shared by everything that puts a row in the bar: the prompt history
+  # and the ! output pane.
+  module Text
+    CYAN   = "\e[36m"
+    YELLOW = "\e[33m"
+    DIM    = "\e[2m"
+    GRAY   = "\e[38;5;245m"
+    REV    = "\e[7m"
+    RESET  = "\e[0m"
+
+    # Dashed, and deliberately not the solid U+2500 "─" it wants to be.
+    #
+    # A pane watcher works out where a program's own furniture is by looking for
+    # the last solid rule on the screen: Herdr hangs its "the prompt box is
+    # here" and "the permission dialog is here" regions off it. Our bar is below
+    # everything, so a solid rule down here becomes the last one and those
+    # regions land on the prompt history instead - detection then sees no prompt
+    # and no dialog, and the pane reads as neither idle nor blocked. Any glyph
+    # that is not box-drawing keeps the bar out of that reckoning; a dashed rule
+    # is also a fair signal that this row is not part of the program above.
+    RULE ||= '┄'
+
+    # Roughly the double-width ranges of UEAW - enough to keep CJK and emoji
+    # from overflowing the bar without pulling in a character-width gem.
+    WIDE ||= [
+      0x1100..0x115f, 0x2e80..0x303e, 0x3041..0x33ff, 0x3400..0x4dbf,
+      0x4e00..0x9fff, 0xa000..0xa4cf, 0xac00..0xd7a3, 0xf900..0xfaff,
+      0xfe30..0xfe6f, 0xff00..0xff60, 0xffe0..0xffe6,
+      0x1f300..0x1f64f, 0x1f900..0x1f9ff, 0x20000..0x2fffd
+    ].freeze
+    ZERO ||= [0xfe00..0xfe0f, 0x200b..0x200f].freeze
+
+    private
+
+    # A full-width rule with the label centred in it, marking off the bar from
+    # whatever the wrapped program is drawing above it.
+    def rule(cols, label)
+      return '' if cols <= 0
+
+      label = " #{label} "
+      pad   = cols - width(label)
+      return "#{GRAY}#{RULE * cols}#{RESET}" if pad < 2
+
+      left = pad / 2
+      "#{GRAY}#{RULE * left}#{label}#{RULE * (pad - left)}#{RESET}"
+    end
+
+    def dim(text)
+      "#{DIM}#{text}#{RESET}"
+    end
+
+    def clip(text, cells)
+      return '' if cells <= 0
+      return text if width(text) <= cells
+
+      out  = +''
+      used = 0
+      text.each_char do |ch|
+        w = char_width(ch)
+        break if used + w > cells - 1
+
+        out << ch
+        used += w
+      end
+      out << '…'
+    end
+
+    def width(text)
+      text.each_char.sum { |ch| char_width(ch) }
+    end
+
+    def char_width(char)
+      cp = char.ord
+      return 0 if cp == 0x200d || ZERO.any? { |r| r.cover?(cp) }
+
+      WIDE.any? { |r| r.cover?(cp) } ? 2 : 1
+    rescue RangeError
+      1
+    end
+  end
+
   # Taking the child's name costs us our own command line, and that is the only
   # record of how the pane was started - Herdr's clone-tab reads it back off the
   # foreground process to reopen the same wrapper. So leave it in a file named
@@ -218,6 +309,7 @@ module LlmWrap
       @origin   = origin
       @bar_rows = keep + 1     # the prompts, plus the rule above them
       @keys     = KeyBuffer.new(keep)
+      @pane     = nil          # the last ! command's output, while one is up
       @out      = OutScan.new
       @winch    = false
       @dirty    = true
@@ -324,8 +416,11 @@ module LlmWrap
     # child holding a saved cursor across this point would lose it - drawing
     # only once output has settled makes that vanishingly rare in practice.
     def draw_bar
+      lines = bar_lines
+      resize_bar(lines.size)
+
       out = +"\e7\e[r"
-      @keys.lines(@cols).each_with_index do |line, i|
+      lines.first(@bar_rows).each_with_index do |line, i|
         out << "\e[#{child_rows + 1 + i};1H\e[K" << line
       end
       out << "\e[1;#{child_rows}r\e8"
@@ -335,6 +430,37 @@ module LlmWrap
       @drawn_at = now
     end
 
+    # The prompt history, or the last ! command's output while one is up. Both
+    # are painted the same way; only the number of rows differs.
+    def bar_lines
+      @pane ? @pane.lines(@cols, max_bar) : @keys.lines(@cols)
+    end
+
+    def max_bar
+      [@rows - MIN_CHILD, 2].max
+    end
+
+    # A taller bar moves the line the child ends on, so the scroll region and
+    # the child's own idea of the screen have to move with it. Rows handed back
+    # still have our text on them and the child has no reason to touch them
+    # until it repaints, so clear them on the way out.
+    def resize_bar(rows)
+      rows = rows.clamp(1, max_bar)
+      return if rows == @bar_rows
+
+      back      = @bar_rows - rows      # positive when the bar shrinks
+      @bar_rows = rows
+
+      if back.positive?
+        out = +"\e7\e[r"
+        (child_rows - back + 1..child_rows).each { |row| out << "\e[#{row};1H\e[K" }
+        emit out << "\e8"
+      end
+
+      set_region
+      resize_child   # the kernel SIGWINCHes the child, which repaints itself
+    end
+
     def emit(str)
       $stdout.write(str)
     end
@@ -366,10 +492,27 @@ module LlmWrap
         ready[0].each do |io|
           if io.equal?($stdin)
             data = slurp($stdin) or return
-            @pty_in.write(data)
             taking = capture?
-            @dirty = true if taking && @keys.feed(data)
+
+            # KeyBuffer decides what the child is allowed to see: everything,
+            # unless a ! line is being typed, which is ours from the ! to the
+            # Enter. Nothing is captured at all while the child is asking for a
+            # password, and then it gets the bytes untouched.
+            if taking
+              @dirty = true if @keys.feed(data)
+              @pty_in.write(@keys.pass) unless @keys.pass.empty?
+            else
+              @pty_in.write(data)
+            end
+
             trace_in(data, taking)
+
+            # After the trace, so the log shows the line that ran before its
+            # output arrives, and after the write, so nothing waits on a shell.
+            if taking
+              @keys.bangs.each { |cmd| run_bang(cmd) }
+              close_pane if @keys.typing?
+            end
           else
             data = drain(@pty_out) or return
             $stdout.write(data)
@@ -389,6 +532,35 @@ module LlmWrap
       nil
     end
 
+    # A ! line never went to the child, so this is the whole of it: run it here
+    # and put the result in the bar. A bare ! puts the bar back to the prompt
+    # history, which is how you close the output without running anything.
+    #
+    # The pump is stopped while the shell runs, which is why Bang keeps a
+    # deadline on it. The command is painted before it runs so a slow one does
+    # not look like a hung terminal.
+    def run_bang(cmd)
+      return close_pane if cmd.empty?
+
+      @pane  = Bang.pending(cmd)
+      @dirty = true
+      paint
+
+      @pane = Bang.run(cmd)
+      trace('BANG', "#{cmd.inspect} -> exit=#{@pane.status.inspect} #{@pane.note}")
+      @dirty = true
+      paint
+    end
+
+    # The first keystroke of the next line takes the screen back: the output was
+    # for the question you were about to ask, and now you are asking it.
+    def close_pane
+      return unless @pane
+
+      @pane  = nil
+      @dirty = true
+    end
+
     def slurp(io)
       io.readpartial(CHUNK)
     rescue EOFError, Errno::EIO, IOError
@@ -623,6 +795,195 @@ module LlmWrap
     end
   end
 
+  # What a ! command left behind, as rows for the bar.
+  #
+  # It stays on this side of the wrapper. Nothing is typed into the child, so
+  # the output is not in the transcript and not in the model's context - and it
+  # is not painted over either, because these rows are outside the child's
+  # screen by construction, the same trick that keeps the prompt history safe.
+  class Pane
+    include Text
+
+    LABEL ||= 'shell'
+
+    attr_reader :cmd, :pwd, :out, :status, :note
+
+    def initialize(cmd, out: [], status: nil, note: nil)
+      @cmd    = cmd
+      @pwd    = Dir.pwd
+      @out    = out
+      @status = status
+      @note   = note
+    end
+
+    # Where it ran, what ran, then what it printed - under a rule saying whose
+    # rows these are. `max` is everything the bar is allowed to take.
+    #
+    # The command keeps the ! you typed rather than wearing a shell's $: it is
+    # the same row you were just looking at while typing it, and the bar is a
+    # record of what you typed.
+    def lines(cols, max)
+      head = [dim(clip(tilde(@pwd), cols)),
+              "#{YELLOW}!#{RESET} #{clip(@cmd, cols - 2)}"]
+      body = @out.empty? ? [dim('(no output)')] : @out.map { |line| clip(line, cols) }
+
+      [rule(cols, label)] + head + fit(body, max - 1 - head.size)
+    end
+
+    private
+
+    def label
+      bits = [LABEL]
+      bits << "exit #{@status}" if @status.to_i.positive?
+      bits << @note if @note
+      bits.join(' - ')
+    end
+
+    # Long output is cut from the bottom. The bar is a few rows and not a pager:
+    # what is worth reading here a command says first, and anything else is a
+    # pipe into head or a file away.
+    def fit(rows, room)
+      return rows if rows.size <= room
+      return [] if room < 1
+
+      rows.first(room - 1) << dim("… +#{rows.size - room + 1} more lines")
+    end
+
+    def tilde(path)
+      home = Dir.home
+      path.start_with?("#{home}/") || path == home ? path.sub(home, '~') : path
+    end
+  end
+
+  # Runs a ! line, here, instead of handing it to the agent.
+  module Bang
+    # A ! line is meant to be quick, and the pump is stopped while it runs: no
+    # keys reach the child and the screen does not repaint. Anything slower than
+    # this wants to be a real terminal, or the agent's own tools.
+    TIMEOUT ||= 10
+    MAX_OUT ||= 65_536
+    READ    ||= 4096
+
+    # `cd` on its own, with nothing that would need a shell to work out. Every !
+    # line gets a fresh shell, so a cd inside one dies with it and the pwd row
+    # above the output would be a lie the moment you tried. Do it here instead.
+    # This moves us and nothing else: the agent has its own working directory
+    # and we are not reaching into it.
+    CD ||= /\Acd(?:\s+(?<path>[^|&;<>()`$\n]*\S))?\z/
+
+    # Yours, non-interactive - so zsh syntax works, but ~/.zshrc is not read and
+    # your aliases and functions are not there. Loading it per line would cost
+    # more than the round trip this is here to save.
+    def self.shell
+      sh = ENV['SHELL'].to_s
+      sh.empty? ? '/bin/sh' : sh
+    end
+
+    def self.pending(cmd)
+      Pane.new(cmd, note: 'running')
+    end
+
+    def self.run(cmd)
+      cmd = cmd.strip
+      (m = CD.match(cmd)) ? chdir(cmd, m[:path]) : capture(cmd)
+    end
+
+    def self.chdir(cmd, path)
+      prev = Dir.pwd
+      Dir.chdir(target(path))
+      @back = prev
+      Pane.new(cmd, status: 0)
+    rescue SystemCallError => e
+      Pane.new(cmd, out: [e.message], status: 1)
+    end
+
+    def self.target(path)
+      case path
+      when nil then Dir.home
+      when '-' then @back || Dir.pwd
+      else File.expand_path(path)
+      end
+    end
+
+    def self.capture(cmd)
+      out  = String.new(encoding: Encoding::BINARY)
+      note = nil
+      # No keyboard: our stdin is the terminal, in raw mode, and a command that
+      # reads it would be taking the keystrokes meant for the agent. Anything
+      # wanting input is not a ! line.
+      io = IO.popen([shell, '-c', cmd], in: File::NULL, err: %i[child out], pgroup: true)
+      till = clock + TIMEOUT
+
+      loop do
+        # Waiting on the pipe and not on the process: a command that forks and
+        # leaves the pipe open (`something &`) holds this until the deadline,
+        # and then it is stopped like anything else that overstayed.
+        left = till - clock
+        if left <= 0 || !IO.select([io], nil, nil, left)
+          note = "timed out after #{TIMEOUT}s"
+          break
+        end
+
+        begin
+          out << io.readpartial(READ)
+        rescue EOFError
+          break
+        end
+
+        note = 'output cut' if out.bytesize >= MAX_OUT
+        break if note
+      end
+
+      stop(io) if note
+      Pane.new(cmd, out: rows(out), status: close(io), note: note)
+    rescue SystemCallError, IOError => e
+      Pane.new(cmd, out: [e.message], status: 1, note: 'did not run')
+    end
+
+    # Whatever it is doing, it does not get to outlive the line that started it -
+    # the wrapper is not pumping keys while it lives. TERM first, then insist,
+    # and the whole group because a shell -c is usually not the only process.
+    def self.stop(io)
+      Process.kill('TERM', -io.pid)
+      sleep 0.05
+      Process.kill('KILL', -io.pid)
+    rescue SystemCallError
+      nil
+    end
+
+    def self.close(io)
+      io.close
+      $?&.exitstatus
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def self.clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Output as bar rows: no escape sequences left to fight with our own colour
+    # or walk the cursor out of the pane, and tabs where a terminal would put
+    # them. The trailing newline every command ends with is not a blank row.
+    def self.rows(bytes)
+      text = bytes.dup.force_encoding(Encoding::UTF_8).scrub('')
+      out  = text.gsub(/\e\[[\d;?]*[ -\/]*[@-~]|\e[\]P^_X].*?(?:\a|\e\\)|\e./m, '')
+                 .split("\n", -1)
+                 .map { |line| untab(line).gsub(/[\x00-\x1f\x7f]/, '') }
+
+      out.pop while !out.empty? && out.last.empty?
+      out
+    end
+
+    def self.untab(line)
+      return line unless line.include?("\t")
+
+      line.each_char.with_object(+'') do |ch, out|
+        ch == "\t" ? out << ' ' * (8 - (out.length % 8)) : out << ch
+      end
+    end
+  end
+
   # Rebuilds the line you are typing from the raw byte stream on its way to the
   # child, and keeps the last `keep` submitted lines.
   #
@@ -630,10 +991,13 @@ module LlmWrap
   # reads can split a UTF-8 character or an escape sequence, so bytes are
   # accumulated in a binary buffer and only decoded when rendered.
   class KeyBuffer
+    include Text
+
     MAX_LEN     ||= 4096
     NO_PROMPTS  ||= '(nothing typed yet)'
     LABEL       ||= 'prompt history'
 
+    BANG  = 0x21
     CR    = 0x0d
     LF    = 0x0a
     ESC   = 0x1b
@@ -658,33 +1022,52 @@ module LlmWrap
     # CSI 27 ; <mods> ; <code> ~   (xterm modifyOtherKeys)
     XTERM_KEY ||= /\A\e\[27;(\d+);(\d+)~\z/
 
-    # Roughly the double-width ranges of UEAW - enough to keep CJK and emoji
-    # from overflowing the bar without pulling in a character-width gem.
-    WIDE ||= [
-      0x1100..0x115f, 0x2e80..0x303e, 0x3041..0x33ff, 0x3400..0x4dbf,
-      0x4e00..0x9fff, 0xa000..0xa4cf, 0xac00..0xd7a3, 0xf900..0xfaff,
-      0xfe30..0xfe6f, 0xff00..0xff60, 0xffe0..0xffe6,
-      0x1f300..0x1f64f, 0x1f900..0x1f9ff, 0x20000..0x2fffd
-    ].freeze
-    ZERO ||= [0xfe00..0xfe0f, 0x200b..0x200f].freeze
-
     def initialize(keep)
       @keep    = keep
       @prompts = []
       @buf     = binary
       @esc     = nil
       @paste   = false
+      @bang    = false
+      @bangs   = []
+      @pass    = binary
+      @hold    = binary
     end
 
+    # What the last feed decided, for the pump:
+    #
+    #   pass    the bytes the child is allowed to see. Everything, until a line
+    #           starts with !, and then nothing until that line is done with.
+    #   bangs   ! lines submitted in it, in order. An empty one is a bare !.
+    #   typing? there is a line on the go, so the screen is wanted for it.
+    attr_reader :pass, :bangs
+
+    def typing? = !@buf.empty?
+    def bang?   = @bang
+
     # The line being typed right now, for the debug trace.
     def pending
       decode(@buf)
     end
 
-    # Returns true when the pinned prompts changed.
+    # Returns true when what the bar shows changed.
     def feed(bytes)
-      changed = false
-      bytes.each_byte { |b| changed = true if @esc ? escape(b) : plain(b) }
+      @pass    = binary
+      @hold    = binary
+      @bangs   = []
+      changed  = false
+
+      bytes.each_byte do |b|
+        @hold << b
+        was = @bang
+        hit = @esc ? escape(b) : plain(b)
+        # A ! line redraws on every keystroke: the bar is the only place it is
+        # shown, so it has to keep up the way an input box would.
+        changed = true if hit || @bang || was
+        release unless @esc
+      end
+
+      release   # a sequence still arriving: the child waits no longer than today
       changed
     end
 
@@ -704,39 +1087,29 @@ module LlmWrap
         end
       end
 
-      [rule(cols)] + rows
+      rows[-1] = typing(cols) if @bang
+      [rule(cols, LABEL)] + rows
     end
 
     private
 
-    CYAN  = "\e[36m"
-    DIM   = "\e[2m"
-    GRAY  = "\e[38;5;245m"
-    RESET = "\e[0m"
-
-    # Dashed, and deliberately not the solid U+2500 "─" it wants to be.
-    #
-    # A pane watcher works out where a program's own furniture is by looking for
-    # the last solid rule on the screen: Herdr hangs its "the prompt box is
-    # here" and "the permission dialog is here" regions off it. Our bar is below
-    # everything, so a solid rule down here becomes the last one and those
-    # regions land on the prompt history instead - detection then sees no prompt
-    # and no dialog, and the pane reads as neither idle nor blocked. Any glyph
-    # that is not box-drawing keeps the bar out of that reckoning; a dashed rule
-    # is also a fair signal that this row is not part of the program above.
-    RULE ||= '┄'
-
-    # A full-width rule with the label centred in it, marking off the bar from
-    # whatever the wrapped program is drawing above it.
-    def rule(cols)
-      return '' if cols <= 0
+    # A ! line is not going anywhere near the child, so nothing else on screen
+    # is showing it: this row is the only place you can see what you are typing,
+    # cursor included. It takes the newest prompt's row, which comes back the
+    # moment the line is run or dropped.
+    def typing(cols)
+      text = decode(@buf).delete_prefix('!').lstrip
+      "#{YELLOW}!#{RESET} #{clip(text, cols - 4)}#{REV} #{RESET}"
+    end
 
-      label = " #{LABEL} "
-      pad   = cols - width(label)
-      return "#{GRAY}#{RULE * cols}#{RESET}" if pad < 2
+    # Bytes reach the child unless a ! line is holding them back. @swallow
+    # carries the Enter that ended one, which is ours and not the child's.
+    def release
+      return if @hold.empty?
 
-      left = pad / 2
-      "#{GRAY}#{RULE * left}#{label}#{RULE * (pad - left)}#{RESET}"
+      @pass << @hold unless @bang || @swallow
+      @swallow = false
+      @hold    = binary
     end
 
     def binary
@@ -748,7 +1121,7 @@ module LlmWrap
       when ESC          then @esc = binary << byte; false
       when CR, LF       then @paste ? (append("\n"); false) : submit
       when DEL, BS      then chop_char; false
-      when CTRL_U, CTRL_C then @buf = binary; false
+      when CTRL_U, CTRL_C then clear_line; false
       when CTRL_W       then drop_word; false
       when TAB          then false   # completion text is inserted by the app
       else
@@ -762,16 +1135,6 @@ module LlmWrap
     # bracketed-paste markers.
     def escape(byte)
       @esc << byte
-
-      if @esc.bytesize == 2
-        case byte
-        when 0x5b, 0x4f    then return false       # CSI / SS3: keep collecting
-        when *STRING_INTRO then return false       # OSC / DCS / APC / PM / SOS
-        when CR, LF        then @esc = nil; append("\n"); return false # Option+Enter
-        else @esc = nil; return false
-        end
-      end
-
       intro = @esc.getbyte(1)
 
       # String sequences run to BEL or ST (ESC \) rather than a final byte, and
@@ -779,12 +1142,34 @@ module LlmWrap
       # question the program asked - Codex queries the fg/bg colour on startup
       # and gets back "\e]10;rgb:cdcd/d6d6/f4f4\e\\" - so the whole thing is
       # dropped. Treating them as CSI would spill that payload into the prompt.
-      if STRING_INTRO.include?(intro)
+      # An ESC in here is the start of that ST, so this goes before the resync.
+      if @esc.bytesize > 2 && STRING_INTRO.include?(intro)
         @esc = nil if byte == BEL || (byte == 0x5c && @esc.getbyte(-2) == ESC)
         @esc = nil if @esc && @esc.bytesize > 1024  # unterminated: cut losses
         return false
       end
 
+      # An ESC part-way through a sequence never belongs to it: the one being
+      # collected was abandoned and a new one starts here. That is the ordinary
+      # shape of a bare Escape keypress followed by any other key - the terminal
+      # sends "\e" and then the next key's own sequence - and of a read that
+      # split one sequence off the end of another. Resync rather than give up:
+      # dropping the state would leave the rest of the new sequence to arrive as
+      # plain bytes, and "\e[27;1:3u" would land in the prompt as "[27;1:3u".
+      if byte == ESC
+        @esc = binary << byte
+        return false
+      end
+
+      if @esc.bytesize == 2
+        case byte
+        when 0x5b, 0x4f    then return false       # CSI / SS3: keep collecting
+        when *STRING_INTRO then return false       # OSC / DCS / APC / PM / SOS
+        when CR, LF        then @esc = nil; append("\n"); return false # Option+Enter
+        else @esc = nil; return false
+        end
+      end
+
       if intro == 0x4f                             # SS3 is always three bytes
         @esc = nil
         return false
@@ -796,7 +1181,9 @@ module LlmWrap
         return csi(seq)
       end
 
-      @esc = nil if @esc.bytesize > 32             # runaway guard
+      # Lost the thread of it. Keep swallowing to the final byte rather than
+      # dropping the state, for the same reason as the resync above.
+      @esc = @esc.byteslice(0, 2) if @esc.bytesize > 32
       false
     end
 
@@ -841,7 +1228,7 @@ module LlmWrap
       # image in Claude Code, which puts no typed text on the wire at all.
       if bits & CTRL != 0
         case code
-        when 117, 99 then @buf = binary              # ctrl-u, ctrl-c
+        when 117, 99 then clear_line                 # ctrl-u, ctrl-c
         when 119     then drop_word                  # ctrl-w
         end
         return false
@@ -865,13 +1252,48 @@ module LlmWrap
     end
 
     def append_byte(byte)
+      return if byte == BANG && !bang_char
+
       @buf << byte if @buf.bytesize < MAX_LEN
     end
 
     def append(str)
+      return if str == '!' && !bang_char
+
       @buf << str.b if @buf.bytesize < MAX_LEN
     end
 
+    # A ! in the first column is ours: from here to Enter nothing reaches the
+    # child and the line runs in a shell instead. Typed twice it is handed back,
+    # so `!!ls` arrives at the agent as `!ls` and its own bash mode is still
+    # there when that is what you wanted. A leading space is the other way out.
+    #
+    # False when the character has been dealt with and must not be appended.
+    def bang_char
+      if @bang && @buf == '!'.b
+        @bang = false      # the second !: this one is the child's, and the
+        return false       # buffer is already holding a ! for it
+      end
+
+      @bang = true if @buf.empty? && !@paste
+      true
+    end
+
+    def clear_line
+      end_bang
+      @buf = binary
+    end
+
+    # Ending a ! line takes the keystroke that ended it along: a backspace or a
+    # ctrl-c that cancelled one was editing our line and not the child's, and a
+    # ctrl-c in particular would interrupt the agent over nothing.
+    def end_bang
+      return unless @bang
+
+      @bang    = false
+      @swallow = true
+    end
+
     # Drop one whole character: back over any UTF-8 continuation bytes first.
     def chop_char
       return if @buf.empty?
@@ -879,6 +1301,7 @@ module LlmWrap
       i = @buf.bytesize - 1
       i -= 1 while i.positive? && (@buf.getbyte(i) & 0xc0) == 0x80
       @buf.slice!(i..)
+      end_bang if @buf.empty?
     end
 
     # Readline's unix-word-rubout: eat trailing whitespace, then the word, and
@@ -886,11 +1309,21 @@ module LlmWrap
     def drop_word
       @buf.sub!(/\s+\z/, '')
       @buf.sub!(/\S+\z/, '')
+      end_bang if @buf.empty?
     end
 
     def submit
       text = decode(@buf)
-      @buf = binary
+      bang = @bang
+      raw  = @buf
+      clear_line
+
+      # A ! line is not a prompt: it was never said to the agent, so it has no
+      # business in a history of what was.
+      if bang
+        @bangs << command(raw)
+        return true
+      end
 
       return false if text.empty? || @prompts.first == text
 
@@ -899,6 +1332,12 @@ module LlmWrap
       true
     end
 
+    # The line as a shell should see it, which is not how the bar sees it:
+    # newlines are separators a shell understands and must survive whole.
+    def command(bytes)
+      bytes.dup.force_encoding(Encoding::UTF_8).scrub('').strip.delete_prefix('!').strip
+    end
+
     # A bar row is one line, so a multi-line prompt - a continuation with
     # Shift/Option+Enter, or a pasted block - is flattened onto it: line breaks
     # show as a backslash + space, and clip() caps the result to the terminal
@@ -910,34 +1349,5 @@ module LlmWrap
       text.gsub(/[^\S\n]+/, ' ')        # runs of spaces/tabs, newlines kept
           .gsub(/ ?\n+ ?/) { '\ ' }     # block form: no backslash escaping here
     end
-
-    def clip(text, cells)
-      return '' if cells <= 0
-      return text if width(text) <= cells
-
-      out  = +''
-      used = 0
-      text.each_char do |ch|
-        w = char_width(ch)
-        break if used + w > cells - 1
-
-        out << ch
-        used += w
-      end
-      out << '…'
-    end
-
-    def width(text)
-      text.each_char.sum { |ch| char_width(ch) }
-    end
-
-    def char_width(char)
-      cp = char.ord
-      return 0 if cp == 0x200d || ZERO.any? { |r| r.cover?(cp) }
-
-      WIDE.any? { |r| r.cover?(cp) } ? 2 : 1
-    rescue RangeError
-      1
-    end
   end
 end

data/recipes/llm.rb

@@ -9,6 +9,7 @@ desc <<~TXT
     memory   persistent memory store (backs the Claude Code memory plugin)
     plan     apply a /plan bundle - sha1 checked, drift aware
     prompt   token-prefix prompt expander (UserPromptSubmit hook + CLI)
+    todo     per-project task queue for agents (./LLM_TODO.local.md)
 
   Commands:
     usage    subscription limits and per-model token usage
@@ -100,6 +101,17 @@ task :wrap do
     inserts for you (history recall, autocomplete, menu picks) will not show up, and
     nothing is captured while the program has echo off in canonical mode (sudo, ssh).
 
+    A line starting with ! is taken over: nothing reaches the wrapped program, the line
+    runs in $SHELL here, and the bar grows to show where it ran, what ran and what it
+    printed. That is a shell round trip instead of a tool call, a permission check and a
+    model turn - and it costs no context either, since the agent is never told.
+
+    Output stays up until you type anything at all, and a bare ! clears it too. Long
+    output is cut to the rows there are, and a command still running after 10s is killed,
+    since the wrapper is stopped while one runs. `cd` is handled here so that it sticks,
+    and moves nothing but the wrapper. Type !! to send a literal ! to the program instead,
+    which is how you reach Claude Code's own bash mode; a leading space does the same.
+
     Keys are decoded from plain bytes, the kitty keyboard protocol and xterm
     modifyOtherKeys, since a program can ask the terminal for any of the three (Claude
     Code turns on the last two). Mouse reports, focus events, arrows and Ctrl-<key> are
@@ -321,6 +333,287 @@ namespace :memory do
   end
 end
 
+TODO_GUIDE ||= <<~TXT
+  Per-project task queue in ./LLM_TODO.local.md - workable by humans and any agent.
+
+  Human usage:
+    llm todo:add "fix login redirect"   queue a task (pipe stdin for bulk / multi-line)
+    llm todo:list                       tasks by id, counts, format warnings
+    llm todo:pop + llm todo:done        take / finish a single task by hand
+
+    Edit the file freely: only the `# todo`, `# doing` and `# done` sections are
+    managed. `# plan`, `# idea` and any prose stay untouched. A task starts with
+    `*` at the line start and runs until the next `*` or header; when finished it
+    moves to `# done` verbatim.
+
+  LLM usage - one of these lines is the whole prompt:
+    "Run `llm todo go` and follow its output."               work through every task
+    "Run `llm todo pop`, do the task, run `llm todo done`."  do a single task
+
+    Task text is printed raw on stdout. `todo go` repeats the protocol after each
+    task and says when the queue is empty; `todo pop` re-prints the task in
+    progress, so an interrupted agent resumes instead of skipping ahead.
+TXT
+
+task :todo do
+  desc <<~D
+    How the todo queue works, for humans and LLMs.
+
+    #{TODO_GUIDE}
+  D
+  example 'todo'
+
+  proc do
+    say TODO_GUIDE
+    say ''
+    self.class.print_help 'todo:'
+  end
+end
+
+namespace :todo do
+  # Same story as :memory - helpers must live inside the namespace block.
+  private
+
+  TODO_FILE     ||= 'LLM_TODO.local.md'
+  TODO_SECTIONS ||= { todo: 'todo', doing: 'doing', done: 'done' }.freeze
+
+  def todo_path
+    File.join(Dir.pwd, TODO_FILE)
+  end
+
+  # Exact title match on purpose - "# done ideas" must stay an unmanaged section.
+  def todo_section_key(title)
+    case title.strip.downcase
+    when 'todo', 'pending'                     then :todo
+    when 'doing', 'in progress', 'in-progress' then :doing
+    when 'done', 'completed'                   then :done
+    end
+  end
+
+  # The tool manages only the `# todo`, `# doing` and `# done` sections (any
+  # heading level). Inside them a task starts at a `*` or `-` bullet in the
+  # first column and runs until the next bullet or header, so tasks can span
+  # multiple lines and move between sections verbatim. Every other section
+  # (`# plan`, `# idea`, ...) and any preamble is kept as-is and never touched.
+  # Returns [tasks, nodes]; nodes reproduce the document layout for todo_save.
+  def todo_parse
+    tasks = { todo: [], doing: [], done: [] }
+    nodes = []
+    return [tasks, nodes] unless File.file?(todo_path)
+
+    section = nil # managed section key, nil while inside a raw chunk
+    current = nil # lines of the task being collected
+
+    flush_task = lambda do
+      tasks[section] << current.join("\n").rstrip if current
+      current = nil
+    end
+
+    File.foreach(todo_path) do |raw|
+      line = raw.chomp
+      if (m = line.match(/^#+\s*(\S.*?)\s*$/))
+        flush_task.call
+        section = todo_section_key(m[1])
+        if section
+          nodes << [:section, section] unless nodes.include?([:section, section])
+        else
+          nodes << [:raw, [line]]
+        end
+      elsif section
+        if line =~ /^[-*]\s+(.*)$/
+          flush_task.call
+          current = [$1.strip]
+        elsif current
+          current << line.rstrip
+        end
+      else
+        nodes << [:raw, []] unless nodes.last && nodes.last[0] == :raw
+        nodes.last[1] << line.rstrip
+      end
+    end
+    flush_task.call
+    [tasks, nodes]
+  end
+
+  # Rewrite: managed sections in canonical form, raw chunks verbatim, original
+  # order kept. Managed sections missing from the file are appended at the end.
+  def todo_save(tasks, nodes)
+    order = nodes + (TODO_SECTIONS.keys - nodes.map { |t, v| v if t == :section }).map { |k| [:section, k] }
+
+    File.open(todo_path, 'w') do |io|
+      order.each_with_index do |(type, value), i|
+        io.puts unless i.zero?
+        if type == :section
+          io.puts "# #{TODO_SECTIONS[value]}"
+          tasks[value].each do |text|
+            io.puts
+            io.puts "* #{text}"
+          end
+        else
+          lines = value.dup
+          lines.pop while lines.any? && lines.last.empty?
+          lines.each { |l| io.puts l }
+        end
+      end
+    end
+  end
+
+  # One-line label for confirmations - multi-line tasks show their first line.
+  def todo_label(text)
+    first, rest = text.split("\n", 2)
+    rest ? "#{first} ..." : first
+  end
+
+  # Format sanity check for hand-edited files. Returns warning strings.
+  def todo_lint(tasks)
+    warns   = []
+    seen    = Hash.new(0)
+    section = :preamble
+    File.foreach(todo_path) do |raw|
+      line = raw.chomp
+      if (m = line.match(/^#+\s*(\S.*?)\s*$/))
+        key       = todo_section_key(m[1])
+        section   = key || :other
+        seen[key] += 1 if key
+      elsif section == :preamble && line =~ /^[-*]\s/
+        warns << "ignored bullet before any section header: #{line}"
+      end
+    end
+    TODO_SECTIONS.each_key do |key|
+      warns << "duplicate '# #{key}' sections - their tasks are merged" if seen[key] > 1
+      warns << "missing '# #{key}' section - will be added on next write" if seen[key].zero?
+    end
+    warns << "#{tasks[:doing].length} tasks in doing - expected at most 1" if tasks[:doing].length > 1
+    warns
+  end
+
+  task :add do
+    desc <<~DESC
+      Add task(s) to ./#{TODO_FILE} (created on first add).
+
+      Text comes from the argument (one task), or from stdin - there a `*` at
+      the start of a line begins a new task and following lines belong to it,
+      so multi-line tasks and whole lists can be piped in at once.
+    DESC
+    example 'todo add "migrate the user model to Sequel"'
+    example 'cat tasks.md | llm todo add'
+    opt :text, desc: 'task text (or pipe tasks on stdin)'
+
+    proc do |opts|
+      # unquoted multi-word input lands in :text + :args - join it back
+      arg = [opts[:text], *opts[:args]].compact.join(' ').strip
+      if arg.empty?
+        new_tasks = []
+        opts[:stdin].to_s.split("\n").each do |line|
+          if line =~ /^[-*]\s+(.*)$/
+            new_tasks << [$1.strip]
+          elsif new_tasks.any?
+            new_tasks.last << line.rstrip
+          elsif line.strip != ''
+            new_tasks << [line.rstrip]
+          end
+        end
+        new_tasks = new_tasks.map { |lines| lines.join("\n").rstrip }.reject(&:empty?)
+      else
+        new_tasks = [arg]
+      end
+      error 'usage: llm todo add <text> (or pipe tasks on stdin)' if new_tasks.empty?
+
+      tasks, nodes = todo_parse
+      tasks[:todo].concat new_tasks
+      todo_save tasks, nodes
+      new_tasks.each { |t| say "added: #{todo_label(t)}", :green }
+    end
+  end
+
+  task :pop do
+    desc <<~DESC
+      Print the current task and stop there - one task, no loop.
+
+      Moves the first todo task to doing if nothing is doing yet. Prints only
+      the raw task text (agent-friendly stdout). Re-running without `todo done`
+      prints the same task again, so an interrupted agent resumes instead of
+      starting the next one. Exits 1 when the list is empty.
+    DESC
+    example 'todo pop'
+
+    proc do
+      tasks, nodes = todo_parse
+      if tasks[:doing].empty?
+        error 'todo list is empty' if tasks[:todo].empty?
+        tasks[:doing] << tasks[:todo].shift
+        todo_save tasks, nodes
+      end
+      puts tasks[:doing].first
+    end
+  end
+
+  task :go do
+    desc <<~DESC
+      Agent entry point: work through the whole todo list.
+
+      Prints the current task (pop) followed by the loop protocol, so telling
+      any agent "run llm todo go" is enough to drain the queue. When the list
+      is empty it says so and tells the agent to stop and summarize.
+    DESC
+    example 'todo go'
+
+    proc do
+      tasks, nodes = todo_parse
+      if tasks[:doing].empty? && tasks[:todo].empty?
+        say 'All tasks done - stop the loop and summarize what was done.'
+        next
+      end
+      if tasks[:doing].empty?
+        tasks[:doing] << tasks[:todo].shift
+        todo_save tasks, nodes
+      end
+      say "TASK: #{tasks[:doing].first}"
+      say ''
+      say 'Do this task fully and verify it. Then run `llm todo done`, and `llm todo go` for the next one.'
+    end
+  end
+
+  task :done do
+    desc 'Mark the in-progress task as done'
+    example 'todo done'
+
+    proc do
+      tasks, nodes = todo_parse
+      error 'no task in progress (run: llm todo pop)' if tasks[:doing].empty?
+      text = tasks[:doing].shift
+      tasks[:done] << text
+      todo_save tasks, nodes
+      say "done: #{todo_label(text)}", :green
+    end
+  end
+
+  task :list do
+    alt :inspect
+    desc 'Inspect the todo file: tasks by id, counts, format validity warnings'
+    example 'todo list'
+
+    proc do
+      error "no #{TODO_FILE} in #{Dir.pwd} (run: llm todo add <text>)" unless File.file?(todo_path)
+      tasks, = todo_parse
+      id = 0
+      TODO_SECTIONS.each do |key, title|
+        say "#{title}:", :cyan
+        color = { todo: nil, doing: :yellow, done: :gray }[key]
+        tasks[key].each do |text|
+          first, *rest = text.split("\n")
+          say "#{(id += 1).to_s.rjust(3)}. #{first}", color
+          rest.each { |l| say "     #{l}", color }
+        end
+        say '  (none)', :gray if tasks[key].empty?
+      end
+      say ''
+      say "#{tasks[:todo].length} todo, #{tasks[:doing].length} doing, #{tasks[:done].length} done"
+      todo_lint(tasks).each { |w| say "warning: #{w}", :yellow }
+    end
+  end
+end
+
 namespace :prompt do
   TOKEN_PATTERN        ||= /[a-z0-9_-]+/.freeze
   TOKEN_LINE_RE        ||= /\A(?:\s*:[a-z0-9_-]+)+\s*\z/.freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.22
+  version: 0.3.23
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest