samagotchi 0.10.0 → 0.11.0

data/lib/samagotchi/session_commands.rb

@@ -172,7 +172,8 @@ module Samagotchi
 
     private
 
-    def model_name = @engine.effective_model_name
+    # The resolved ref (what the session stores and --alias/--default write).
+    def model_name = @engine.effective_model_ref
 
     # A bundle plugin's command: its handler gets the text after the name;
     # what it returns is the output (nil: nothing to show), and a raise is
@@ -293,7 +294,7 @@ module Samagotchi
       session = @engine.session
       return unless session
 
-      session.model_name = model_name
+      @engine.store_model!(session)
       @save.call(session)
     end
 
@@ -309,7 +310,7 @@ module Samagotchi
     def model_command(input)
       suffix = input.delete_prefix(MODEL_COMMAND).strip
       if suffix.empty?
-        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{thinking_note}", false] if model_name == @default_model
+        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{thinking_note}", false] if model_name == @engine.model_ref_for(@default_model)
 
         return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}#{sampling_note}#{thinking_note}", false]
       end
@@ -405,7 +406,7 @@ module Samagotchi
       session = @engine.session
       return unless session.respond_to?(:model_name=)
 
-      session.model_name = model_name
+      @engine.store_model!(session)
       begin
         @save.call(session)
       rescue StandardError
@@ -468,13 +469,11 @@ module Samagotchi
 
       aliases = ConfigFile.model_aliases
       by_model = Hash.new { |h, k| h[k] = [] }
+      # A bare alias shows next to its id on every host, a host:model one
+      # only under its host.
       aliases.each do |alias_name, model_id|
-        # normalize bare comparison for orphan detection (strip host prefix if present)
-        _, bare = registry.parse_qualified_model(model_id)
-        key = (bare.empty? ? model_id : bare).to_s.downcase
-        by_model[key] << alias_name
-        # also index full ref for exact alias display
-        by_model[model_id.downcase] << alias_name unless key == model_id.downcase
+        host, bare = registry.parse_qualified_model(model_id)
+        by_model[host ? "#{host}:#{bare}".downcase : model_id.downcase] << alias_name
       end
       by_model.each_value { |v| v.uniq!; v.sort! }
 
@@ -500,7 +499,6 @@ module Samagotchi
           seen << identifier.to_s.downcase
           # also track host-qualified seen for orphan logic
           seen << "#{hname}:#{identifier}".downcase
-          seen << "#{hname}/#{identifier}".downcase
           next if batch_variants.include?(identifier)
 
           shown << [entry, identifier] if needle.empty? || identifier.to_s.downcase.include?(needle)
@@ -527,7 +525,7 @@ module Samagotchi
         end
       end
       # Warnings for unreachable hosts are already in lines; no failover
-      orphans = aliases.reject { |_, model_id| seen.include?(model_id.downcase) || seen.include?(registry.bare_name(model_id).downcase) }
+      orphans = aliases.reject { |_, model_id| seen.include?(model_id.downcase) || seen.include?(registry.parse_qualified_model(model_id).last.downcase) }
       unless orphans.empty? || !needle.empty?
         lines << ""
         lines << "orphan aliases (target not discovered):"

data/lib/samagotchi/session_manager.rb

@@ -7,6 +7,7 @@ require "time"
 require "securerandom"
 require "rbconfig"
 require_relative "atomic_file"
+require_relative "config"
 
 require_relative "session"
 require_relative "session_inbox"
@@ -126,9 +127,14 @@ module Samagotchi
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
                            title: nil)
       sd = state_dir || Session.default_state_dir
+      # The resolved ref is stored (a resumed session keeps its model when an
+      # alias is retargeted), with the name as typed beside it.
+      typed = Samagotchi::ModelProfile.check_host!(Samagotchi::ModelProfile.required_model_name(model_name))
+      ref = ConfigFile.model_ref(typed).ref
       session = Session.new_session(
         mode: mode,
-        model_name: Samagotchi::ModelProfile.check_host!(Samagotchi::ModelProfile.required_model_name(model_name)),
+        model_name: ref,
+        model_typed: typed == ref ? nil : typed,
         working_directory: working_directory || Dir.pwd,
         preloaded_memory_names: memories,
         muted_memory_names: muted_memories,
@@ -466,7 +472,7 @@ module Samagotchi
     #   when the session was never saved
     def self.discardable?(session_id, default_model:, state_dir: nil, model_name: default_model, used_memory_names: [],
                           unsaved: nil)
-      return false unless discard_empty? && model_name == default_model && Array(used_memory_names).empty?
+      return false unless discard_empty? && same_model?(model_name, default_model) && Array(used_memory_names).empty?
 
       sd = state_dir || Session.default_state_dir
       if unsaved && !File.exist?(Session.session_file(session_id, state_dir: sd))
@@ -488,13 +494,24 @@ module Samagotchi
       session = Session.load(session_id, state_dir: sd)
       return false unless no_conversation?(session.messages) && session.pending_question.nil? && session.used_memory_names.empty?
       return false unless session.last_prompt.to_s.strip.empty? && session.first_preview.to_s.strip.empty?
-      return false unless session.mode.to_s == "assist" && !default_model.nil? && session.model_name.to_s == default_model.to_s
+      return false unless session.mode.to_s == "assist" && !default_model.nil? && same_model?(session.model_name, default_model)
 
       empty_session_dir?(Session.session_dir(session_id, state_dir: sd))
     rescue ArgumentError, SystemCallError, JSON::ParserError
       false
     end
 
+    # Whether two model names resolve to the same ref (ModelRef#ref): a
+    # session stores the resolved ref, the default may be an alias.
+    def self.same_model?(one, other)
+      return true if one.to_s == other.to_s
+      return false if one.nil? || other.nil?
+
+      ConfigFile.model_ref(one).ref == ConfigFile.model_ref(other).ref
+    rescue StandardError
+      false
+    end
+
     # Only the system prompt (the REPL seeds one, a saved session keeps
     # it); a context note is a system message too, but with its kind.
     # A turn note (the tail system message after a failed, cancelled or empty

data/lib/samagotchi/sessions_command.rb

@@ -9,6 +9,8 @@ require_relative "session_metrics"
 require_relative "recap_store"
 require_relative "session_delete_command"
 require_relative "session_archive_command"
+require_relative "cli/command"
+require_relative "cli/flags"
 
 module Samagotchi
   # `chi sessions`: list, stop, archive/unarchive, delete, prune and clean
@@ -16,6 +18,8 @@ module Samagotchi
   # the subcommands have their own flags). Not SessionCommands, the REPL's
   # slash commands for sessions (session_commands.rb).
   class SessionsCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi sessions <list|stop|archive|unarchive|delete|prune|clean> [options]
         list [--sort updated_at|created_at] [--order desc|asc] [--limit N]
@@ -32,15 +36,32 @@ module Samagotchi
       Defaults: days=14 keep=500 keep_status=none (config: session.retention_days, session.max_count, session.keep_status)
     TEXT
 
-    # The value flags: "--flag V" or "--flag=V", converted with the method
-    # given (nil: the string as it is). Every argument is scanned, the values
-    # too (--cwd --live takes "--live" as the folder and turns --live on),
-    # a flag with nothing after it is ignored, and so is an unknown one.
-    VALUE_FLAGS = {
-      "--days" => [:days, :to_i], "--keep" => [:keep, :to_i], "--keep-status" => [:keep_status, nil],
-      "--sort" => [:sort, nil], "--order" => [:order, nil], "--limit" => [:limit, :to_i],
-      "--cwd" => [:cwd, nil], "--format" => [:format, nil], "--scope" => [:scope, nil]
+    STOP_USAGE = "Usage: chi sessions stop ID...\n"
+    SUBCOMMANDS = %w[list stop archive unarchive delete prune clean].freeze
+
+    # Each subcommand's flags ("--flag V" or "--flag=V" for a value): an
+    # unknown flag, a value flag with nothing after it or an argument where
+    # none is taken is a usage error (exit 2). The numbers become integers
+    # (#integers).
+    FLAGS = {
+      "list" => CLI::Flags.new(args: false) do |f|
+        %w[--sort --order --limit --cwd --format --scope].each { |name| f.value name }
+        f.switch "--live"
+        f.switch "--archived", key: :include_archived
+      end,
+      "stop" => CLI::Flags.new,
+      "prune" => CLI::Flags.new(args: false) do |f|
+        %w[--days --keep --keep-status].each { |name| f.value name }
+        f.switch "--dry-run"
+        f.switch "--test-only", "--test", key: :test_only
+      end,
+      "clean" => CLI::Flags.new(args: false) do |f|
+        f.value "--days"
+        f.switch "--dry-run"
+        f.switch "--all"
+      end
     }.freeze
+    INTEGER_OPTIONS = %i[days keep limit].freeze
 
     # @param argv [Array<String>] the arguments after "sessions"
     def initialize(argv, stdout: $stdout, stderr: $stderr)
@@ -50,61 +71,49 @@ module Samagotchi
     end
 
     # @return [Integer] exit status
+    # @return [Integer] exit status: 2 on a usage error
     def run
-      sub = @argv[0]
-      if sub.nil? || %w[-h --help help].include?(sub)
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
         @stdout.puts USAGE
         return 0
       end
-      @opts = parse_flags
-      case sub
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      case @sub
       when "delete"
-        Samagotchi::SessionDeleteCommand.new(@argv[1..], stdout: @stdout, stderr: @stderr).run
+        return Samagotchi::SessionDeleteCommand.new(@argv[1..], stdout: @stdout, stderr: @stderr).run
       when "archive", "unarchive"
-        Samagotchi::SessionArchiveCommand.new(sub, @argv[1..], stdout: @stdout, stderr: @stderr).run
+        return Samagotchi::SessionArchiveCommand.new(@sub, @argv[1..], stdout: @stdout, stderr: @stderr).run
+      end
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      @opts = integers(parsed.options)
+      case @sub
       when "list" then list
-      when "stop" then stop
-      when "prune", "clean" then prune(sub)
-      else
-        @stderr.puts "Unknown sessions subcommand: #{sub}. Use: list, stop, archive, unarchive, delete, prune, clean"
-        1
+      when "stop" then stop(parsed.args)
+      else prune(@sub)
       end
     end
 
     private
 
-    def parse_flags
-      opts = {
-        dry_run: @argv.include?("--dry-run"),
-        test_only: @argv.include?("--test-only") || @argv.include?("--test"),
-        live: @argv.include?("--live"),
-        include_archived: @argv.include?("--archived")
-      }
-      @argv.each_with_index do |arg, i|
-        nxt = @argv[i + 1]
-        VALUE_FLAGS.each do |flag, (key, convert)|
-          value = if arg == flag && nxt then nxt
-                  elsif arg.start_with?("#{flag}=") then arg.split("=", 2).last
-                  end
-          next unless value
+    def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi sessions #{@sub}" : "chi sessions"
+    def usage_text = @sub == "stop" ? STOP_USAGE : USAGE
 
-          opts[key] = convert ? value.public_send(convert) : value
-          break
-        end
-      end
-      opts
+    # quirk: a number that isn't one is 0 (--days=abc turns the age limit off)
+    def integers(options)
+      options.to_h { |key, value| [key, INTEGER_OPTIONS.include?(key) ? value.to_i : value] }
     end
 
     def list
       format, scope, cwd = @opts.values_at(:format, :scope, :cwd)
       unless format.nil? || %w[text json tsv].include?(format)
-        @stderr.puts "Unknown format #{format.inspect}: use --format text|json|tsv"
-        return 1
-      end
-      unless scope.nil? || %w[project all].include?(scope)
-        @stderr.puts "Unknown scope #{scope.inspect}: use --scope=project|all"
-        return 1
+        return usage_error("unknown format #{format.inspect}: use --format text|json|tsv")
       end
+      return usage_error("unknown scope #{scope.inspect}: use --scope=project|all") unless scope.nil? || %w[project all].include?(scope)
       # The current git project's sessions (Samagotchi::ProjectScope), like
       # chi web's; --scope=all, a folder in no repo or an explicit --cwd: every
       # project's.
@@ -202,12 +211,9 @@ module Samagotchi
       0
     end
 
-    def stop
-      ids = @argv[1..]
-      if ids.empty? || ids.any? { |arg| arg.start_with?("-") }
-        @stderr.puts "Usage: chi sessions stop ID..."
-        return 1
-      end
+    def stop(ids)
+      return usage_error("give session ids") if ids.empty?
+
       # Each id in turn, like chi sessions delete: stdout is flushed before an
       # error line, so the output keeps the order of the ids given.
       ok = ids.uniq.map do |given|
@@ -236,7 +242,7 @@ module Samagotchi
 
     def prune(sub)
       days, keep, keep_status, dry_run, test_only = @opts.values_at(:days, :keep, :keep_status, :dry_run, :test_only)
-      test_only = true if sub == "clean" && !@argv.include?("--all")
+      test_only = true if sub == "clean" && !@opts[:all]
       # Test sessions are throwaway: clean takes them whatever their age,
       # unless --days asks for the older ones only. Live workers and
       # keep_status still protect a session.

data/lib/samagotchi/steer.rb

@@ -74,6 +74,29 @@ module Samagotchi
       nil
     end
 
+    # One injection at an iteration boundary: drain +pending_input+ and, when
+    # anything was waiting, append the merge on the conversation tail (head
+    # mutation would invalidate the server's prefix KV cache) and emit
+    # :pending_input_merged. After a cancel the input stays queued: it runs
+    # as the next turn instead of dying with this one. +answer+ (a String,
+    # or a Proc called only on a merge) is the answer the merge follows, for
+    # the UIs; given, the drain is told it is the after-answer site (plugin
+    # steers are dropped there). A blank answer is none.
+    # @return [Boolean] whether anything was injected
+    def inject!(conversation, pending_input, iteration:, emit:, cancel_controller:, answer: nil)
+      return false unless pending_input
+      return false if cancel_controller&.cancelled?
+
+      merge = merge(drain(pending_input, at_answer: !answer.nil?))
+      return false if merge.empty?
+
+      answer = (answer.respond_to?(:call) ? answer.call : answer).to_s
+      conversation.concat(merge.messages)
+      emit.call({ type: :pending_input_merged, iteration: iteration, **merge.event_fields,
+                  answer: answer.strip.empty? ? nil : answer })
+      true
+    end
+
     # @return [Merge]
     def merge(items)
       items = Array(items)

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -92,9 +92,9 @@ module Samagotchi
         raise Error, e.message
       end
 
-      # --model as the REPL reads it: an alias resolved, a host prefix kept.
+      # --model as typed: spawn_session stores the resolved ref and this name.
       def model_ref(model)
-        ModelProfile.required_model_name(ConfigFile.resolve_model_alias(model))
+        ModelProfile.required_model_name(model)
       end
 
       # An existing session's prompt is built from its own session fields:

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -3,6 +3,7 @@
 require "set"
 require_relative "event_renderer"
 require_relative "formatting"
+require_relative "../prompt_history"
 require_relative "attached_view"
 require_relative "status_row"
 require_relative "input_support"
@@ -292,7 +293,7 @@ module Samagotchi
           show_recap
         elsif command_registry.command?(text)
           # The history keeps !cmds, as the REPL's does (prompts: #send_prompt).
-          persist_recent_history(text) if shell_line?(text)
+          persist_recent_history(text) if PromptHistory.shell_line?(text)
           send_command(text)
         else
           send_prompt(text)
@@ -435,7 +436,7 @@ module Samagotchi
         output = event[:output].to_s
         if output.empty?
           nil
-        elsif event[:status] == "busy" || shell_line?(event[:line])
+        elsif event[:status] == "busy" || PromptHistory.shell_line?(event[:line])
           @screen.commit(output)
           put_back_busy_command(event) if event[:status] == "busy"
         else
@@ -456,10 +457,6 @@ module Samagotchi
         @screen.commit("(the command is in the input history: ↑)") unless @reader&.prefill(event[:line].to_s)
       end
 
-      def shell_line?(line)
-        line.to_s.start_with?(SessionCommands::SHELL_BANG_PREFIX) && line.to_s.strip != SessionCommands::ROLLBACK_COMMAND
-      end
-
       def offer_continue(event)
         @continue_offer = { context: event[:context], no_interrupt: event[:no_interrupt] }
         sync_prompt

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -6,9 +6,11 @@ require "reline"
 
 require_relative "../config"
 require_relative "../memory_paths"
-require_relative "../paths"
+require_relative "../prompt_history"
 require_relative "../tools/memory"
 require_relative "../session_commands"
+require_relative "line_reader"
+require_relative "reline_history_hook"
 
 module Samagotchi
   class TerminalUI
@@ -21,9 +23,6 @@ module Samagotchi
     # Included for private use; it keeps state in @next_input_prefill and
     # reads @no_default_input.
     module InputSupport
-      PROMPT_HISTORY_FILE = "history.json"
-      PROMPT_HISTORY_STATE_DIR = "samagotchi"
-      PROMPT_HISTORY_LIMIT = 20
       AT_PATH_COMPLETION_PREFIX = "@"
       MEMORY_COMPLETION_PREFIX = "#"
       AT_PATH_COMPLETION_MAX_CANDIDATES = 200
@@ -43,12 +42,17 @@ module Samagotchi
       # One read at the main prompt. In multiline mode Enter submits, while
       # Meta+Enter/Alt+Enter inserts a newline on terminals that emit that
       # distinct sequence (for example kitty); Tab completes; a queued prefill
-      # is typed in first.
+      # is typed in first. Other processes' history lines are picked up
+      # before the read and again on the first ↑ of a walk.
       # @return [String, nil] the line, nil on Ctrl-D
       def read_prompt_line(prompt)
+        pick_up_history_lines
+        RelineHistoryHook.install if RelineHistoryHook.supported?
         input = with_scoped_at_path_completion do
           with_next_input_prefill do
-            Reline.readmultiline(prompt, true) { true }
+            RelineHistoryHook.with_refresh(method(:pick_up_history_lines)) do
+              Reline.readmultiline(prompt, true) { true }
+            end
           end
         end
         return nil if input.nil?
@@ -203,16 +207,12 @@ module Samagotchi
         }
       end
 
-      def history_file_path
-        explicit = Samagotchi::Config.get("history.file").to_s.strip
-        return explicit unless explicit.empty?
-
-        File.join(Paths.state_home, PROMPT_HISTORY_STATE_DIR, PROMPT_HISTORY_FILE)
-      end
-
       def load_persistent_history
-        entries = load_history_entries_from_disk
-        entries.last(PROMPT_HISTORY_LIMIT).each { |entry| Reline::HISTORY << entry }
+        @history_lock ||= Mutex.new
+        @history_own_lines ||= []
+        @history_signature = PromptHistory.signature
+        @history_seen = PromptHistory.entries
+        @history_seen.last(PromptHistory::LIMIT).each { |entry| Reline::HISTORY << entry }
       rescue StandardError
         nil
       end
@@ -221,31 +221,76 @@ module Samagotchi
       def persist_recent_history(input)
         return if @scratch
 
-        entries = normalize_history_entries(load_history_entries_from_disk)
-        entries << input
-        trimmed_entries = entries.last(PROMPT_HISTORY_LIMIT)
-        path = history_file_path
-        FileUtils.mkdir_p(File.dirname(path))
-        File.write(path, JSON.pretty_generate(trimmed_entries) + "\n")
+        own = PromptHistory.normalize([input]).first
+        history_lock.synchronize { history_own_lines << own } if own
+        begin
+          PromptHistory.append(input)
+        rescue StandardError
+          history_lock.synchronize { forget_own_line(own) } if own
+          raise
+        end
       rescue StandardError
         nil
       end
 
-      def load_history_entries_from_disk
-        path = history_file_path
-        return [] unless File.file?(path)
+      # Before a main-prompt read, and on the first ↑ of a walk at an open
+      # one (RelineHistoryHook): the lines other processes (the web,
+      # another TUI) added to the history file since we last looked join the
+      # ring. Only the file's new tail is appended, so a line this TUI read
+      # and didn't persist (/model, !rollback: Reline rings every read) stays
+      # put; other processes' lines land after it, the order between the two
+      # approximate. Our own appends are skipped (they're in the ring as
+      # read). Runs on the reader thread, while the main thread may persist
+      # the line just read; @history_own_lines is filled before each append
+      # lands, so either way a line is in the ring once. A scratch session
+      # keeps Reline's ring as it is.
+      #
+      # It runs inside LineReader's read, where a Reprompt or Stop lands at
+      # once. Both wait until the ring and what we last saw of the file agree
+      # (a raise in between would lose the new lines for good), then go on
+      # to LineReader; an ordinary error is swallowed.
+      def pick_up_history_lines
+        return if @scratch
 
-        raw = File.read(path)
-        parsed = JSON.parse(raw)
-        normalize_history_entries(parsed)
-      rescue JSON::ParserError
-        normalize_history_entries(raw.to_s.lines.map(&:chomp))
-      rescue StandardError
-        []
+        Thread.handle_interrupt(LineReader::Reprompt => :never, LineReader::Stop => :never) do
+          signature = PromptHistory.signature
+          next if signature == @history_signature
+
+          entries = PromptHistory.entries
+          fresh = PromptHistory.new_tail(@history_seen || [], entries)
+          @history_signature = signature
+          @history_seen = entries
+          history_lock.synchronize { add_others_lines(fresh) }
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The lines in +fresh+ go into the ring, except our own (each counted
+      # once). Under the history lock.
+      def add_others_lines(fresh)
+        own = history_own_lines
+        fresh.each do |line|
+          index = own.index(line)
+          next own.delete_at(index) if index
+
+          Reline::HISTORY << line
+        end
+      end
+
+      def forget_own_line(own)
+        index = history_own_lines.rindex(own)
+        history_own_lines.delete_at(index) if index
+      end
+
+      def history_own_lines
+        @history_own_lines ||= []
       end
 
-      def normalize_history_entries(entries)
-        Array(entries).map { |entry| entry.to_s.gsub(/\r\n?/, "\n").strip }.reject(&:empty?)
+      # Guards @history_own_lines: the main thread persists lines, the
+      # reader thread picks up others'. Never held across file IO.
+      def history_lock
+        @history_lock ||= Mutex.new
       end
 
       # The text as given ("Please " keeps its space); a blank one is none.

data/lib/samagotchi/terminal_ui/reline_history_hook.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "reline"
+
+require_relative "line_reader"
+
+module Samagotchi
+  class TerminalUI
+    # Prepended to Reline::LineEditor: the first ↑ of a history walk at the
+    # main prompt runs the refresh first, so lines other processes (the web,
+    # another TUI) added to the shared history since the prompt opened are
+    # in the ring it walks. Set per read with .with_refresh; any other read
+    # (a question, a continue prompt) gets Reline's own ↑.
+    #
+    # Kept apart from RelineSeam, whose supported? is all-or-nothing: drift
+    # here only turns this hook off. It overrides two private methods of
+    # reline 0.6.x (the Gemfile pins it), both with Reline's signature
+    # (key, arg: 1), which Reline's dispatch looks at for an arg: keyword:
+    # - ed_prev_history: ↑, Ctrl-P, vi command k and -.
+    # - previous_history: its alias, which inputrc's previous-history binds.
+    # It reads two ivars: @history_pointer (nil while not walking the
+    # history) and @line_index (the cursor's line in a multi-line buffer;
+    # ↑ off line 0 only moves up a line). Without them it is plain Reline.
+    # A failing refresh leaves plain ↑; LineReader's Reprompt and Stop go on.
+    module RelineHistoryHook
+      # Reline's methods the hook overrides, with their arities.
+      METHODS = { ed_prev_history: -2, previous_history: -2 }.freeze
+
+      class << self
+        # @return [Boolean] this Reline has every method the hook overrides
+        def supported?
+          METHODS.all? { |name, arity| reline_method(name)&.arity == arity }
+        end
+
+        def install
+          Reline::LineEditor.prepend(self) unless Reline::LineEditor.include?(self)
+        end
+
+        # Run a read (on this thread) whose first ↑ of a walk calls
+        # +refresh+ first.
+        # @param refresh [#call, nil]
+        def with_refresh(refresh)
+          was = Thread.current[:samagotchi_reline_history_refresh]
+          Thread.current[:samagotchi_reline_history_refresh] = refresh
+          yield
+        ensure
+          Thread.current[:samagotchi_reline_history_refresh] = was
+        end
+
+        # @return [#call, nil] the refresh of the read on this thread
+        def refresh = Thread.current[:samagotchi_reline_history_refresh]
+
+        private
+
+        # Reline's own implementation, past this module once it is prepended.
+        def reline_method(name)
+          method = Reline::LineEditor.instance_method(name)
+          method = method.super_method while method&.owner == self
+          method
+        rescue NameError
+          nil
+        end
+      end
+
+      private
+
+      def ed_prev_history(key, arg: 1)
+        refresh_history_before_walk
+        super
+      end
+
+      def previous_history(key, arg: 1)
+        refresh_history_before_walk
+        super
+      end
+
+      # Only at the start of a walk: appending to Reline::HISTORY mid-walk
+      # would shift what the pointer means.
+      def refresh_history_before_walk
+        refresh = RelineHistoryHook.refresh
+        return unless refresh
+        return unless instance_variable_defined?(:@history_pointer) && instance_variable_defined?(:@line_index)
+        return unless @history_pointer.nil? && @line_index.zero?
+
+        refresh.call
+      rescue LineReader::Reprompt, LineReader::Stop
+        raise
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end