muxr 0.1.11 → 0.2.0

data/lib/muxr/client.rb

@@ -29,11 +29,10 @@ module Muxr
 
     # Opens the socket. Returns true on success. Raises Errno::ENOENT /
     # Errno::ECONNREFUSED to the caller, which is bin/muxr's job to handle by
-    # spawning a server.
+    # spawning a server. HELLO is deferred to #run: it now carries the width
+    # probe's verdict, and the probe needs the TTY in raw mode first.
     def connect
       @sock = UNIXSocket.new(@socket_path)
-      rows, cols = terminal_size
-      Protocol.write(@sock, Protocol::HELLO, Protocol.encode_size(rows, cols))
       true
     end
 
@@ -41,8 +40,9 @@ module Muxr
       raise "must call #connect first" unless @sock
 
       enter_terminal_mode
-      install_winch_trap
       @running = true
+      send_hello          # may clear @running if the socket is already gone
+      install_winch_trap
 
       begin
         loop_forever
@@ -139,6 +139,28 @@ module Muxr
       @running = false
     end
 
+    # The opening handshake. Sent after the TTY is in raw mode so the width
+    # probe can read the terminal's CPR replies; its verdict (e.g. whether the
+    # terminal draws ambiguous-width glyphs wide) rides along in the payload so
+    # the server can align its emulator/Renderer with this exact terminal.
+    def send_hello
+      rows, cols = terminal_size
+      Protocol.write(@sock, Protocol::HELLO, Protocol.encode_size(rows, cols, probe_caps))
+    rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+      @running = false
+    end
+
+    # Run the width probe against the controlling terminal. Skipped (→ no caps,
+    # server keeps its defaults) when STDIN/STDOUT aren't a TTY — tests, pipes,
+    # CI — or if the probe raises for any reason; a failed probe must never stop
+    # the client from attaching.
+    def probe_caps
+      return {} unless STDIN.tty? && STDOUT.tty?
+      WidthProbe.run(out: STDOUT, input: STDIN)
+    rescue StandardError
+      {}
+    end
+
     def terminal_size
       IO.console.winsize
     rescue StandardError

data/lib/muxr/command_dispatcher.rb

@@ -4,6 +4,66 @@ module Muxr
   # rather than a hard error so the user never gets dropped out of the
   # multiplexer for a typo.
   class CommandDispatcher
+    # Command names offered by Tab-completion. Deliberately the canonical
+    # names only — the terse aliases (ls/q/exit/c/k/kill) still *work* when
+    # typed, but completing to a shorter alias would be surprising, and
+    # offering both halves would clutter the ambiguity list.
+    COMPLETIONS = %w[
+      layout drawer claude private save restore sessions attach
+      new close next prev master detach help quit silence ratio masters zoom sync rename reload capture
+    ].freeze
+
+    # Argument candidates for the commands that take a fixed vocabulary.
+    DRAWER_ARGS = %w[toggle show hide reset].freeze
+
+    # Tab-completion entry point. Given the current command buffer, returns
+    # [completed_line, candidates]: `completed_line` extends the active token
+    # to the longest common prefix of its matches (plus a trailing space on a
+    # unique match), and `candidates` is the full match list so the caller can
+    # show it when the completion is ambiguous. A no-match returns the line
+    # unchanged with an empty candidate list.
+    def self.complete(line)
+      line = line.to_s
+      words = line.split(/\s+/)
+      words.shift if words.first == "" # leading whitespace → drop the empty
+      at_new_token = !!(line =~ /\s\z/) || line.empty?
+
+      index = at_new_token ? words.length : words.length - 1
+      prefix = at_new_token ? "" : (words.last || "")
+
+      matches = candidates_for(index, words).select { |c| c.start_with?(prefix) }.sort
+      return [line, []] if matches.empty?
+
+      head = at_new_token ? words : words[0...index]
+      completed = common_prefix(matches)
+      new_line = (head + [completed]).join(" ")
+      new_line += " " if matches.length == 1
+      [new_line, matches]
+    end
+
+    # Candidate list for the token at `index` given the words typed so far.
+    # index 0 is the command name; index 1 is an argument keyed off the command.
+    def self.candidates_for(index, words)
+      return COMPLETIONS if index.zero?
+
+      case words[0]
+      when "layout" then Window::LAYOUTS.map(&:to_s)
+      when "drawer" then DRAWER_ARGS
+      when "silence" then %w[off]
+      when "sync" then %w[on off]
+      else []
+      end
+    end
+
+    def self.common_prefix(strings)
+      ref = strings.min_by(&:length) || ""
+      ref.length.downto(0) do |len|
+        pre = ref[0, len]
+        return pre if strings.all? { |s| s.start_with?(pre) }
+      end
+      ""
+    end
+
     def initialize(app)
       @app = app
     end
@@ -21,6 +81,7 @@ module Muxr
       when "save"    then @app.save_session
       when "restore" then @app.restore_session
       when "sessions", "ls" then @app.list_sessions
+      when "attach"  then @app.open_pane_picker
       when "quit", "q", "exit"
         @app.quit
       when "new", "c"
@@ -32,6 +93,14 @@ module Muxr
       when "master"  then @app.promote_master
       when "help"    then @app.show_help
       when "detach"  then @app.detach
+      when "silence" then @app.monitor_silence(args[0])
+      when "zoom"    then @app.toggle_zoom
+      when "sync"    then @app.set_sync(args[0])
+      when "reload"  then @app.reload_config
+      when "capture" then @app.capture_focused(args.join(" "))
+      when "rename"  then @app.rename_focused(args.join(" "))
+      when "ratio"   then @app.set_master_ratio(args[0])
+      when "masters" then @app.set_master_count(args[0])
       else
         @app.flash("unknown command: #{cmd}")
       end

data/lib/muxr/config.rb

@@ -0,0 +1,156 @@
+require "json"
+
+module Muxr
+  class Config
+    DEFAULT_PATH = File.join(Dir.home, ".muxr", "config.json").freeze
+
+    KEY_NAMES = {
+      "Tab"   => "\t",
+      "Enter" => "\r",
+      "Space" => " ",
+      "Esc"   => "\e"
+    }.freeze
+
+    RESERVED_NORMAL_KEYS = (["i", ":"] + ("1".."9").to_a).freeze
+    RESERVED_PREFIX_KEYS = (["\e", ":"] + ("1".."9").to_a).freeze
+
+    attr_reader :path, :errors, :layout, :scrollback, :master_ratio, :master_count,
+                :auto_spiral_min_cols, :auto_spiral_min_rows, :prefix,
+                :normal_keys, :prefix_keys
+
+    def self.path_from_env
+      path = ENV["MUXR_CONFIG"]
+      path.nil? || path.empty? ? DEFAULT_PATH : path
+    end
+
+    def self.load(path = path_from_env)
+      return new({}, path: path) unless File.exist?(path)
+      data = JSON.parse(File.read(path))
+      return new({}, path: path, errors: ["top level must be an object"]) unless data.is_a?(Hash)
+      new(data, path: path)
+    rescue JSON::ParserError => e
+      new({}, path: path, errors: ["not valid JSON: #{e.message.lines.first.strip}"])
+    rescue SystemCallError => e
+      new({}, path: path, errors: ["cannot read: #{e.message}"])
+    end
+
+    def self.key_from_name(name)
+      return nil unless name.is_a?(String) && !name.empty?
+      return KEY_NAMES[name] if KEY_NAMES.key?(name)
+      return (name[2].downcase.ord & 0x1f).chr if name.match?(/\AC-[a-zA-Z]\z/)
+      name if name.length == 1
+    end
+
+    def self.action_name(binding)
+      binding.is_a?(Array) ? binding.join(":") : binding.to_s
+    end
+
+    def self.actions
+      @actions ||= (InputHandler::NORMAL_BINDINGS.values + InputHandler::PREFIX_BINDINGS.values)
+                   .uniq.to_h { |binding| [action_name(binding), binding] }.freeze
+    end
+
+    def initialize(data, path: DEFAULT_PATH, errors: [])
+      @path = path
+      @errors = errors.dup
+      @normal_keys = {}
+      @prefix_keys = {}
+      @prefix = InputHandler::PREFIX
+      parse(data)
+    end
+
+    def empty?
+      @layout.nil? && @scrollback.nil? && @master_ratio.nil? && @master_count.nil? &&
+        @auto_spiral_min_cols.nil? && @auto_spiral_min_rows.nil? &&
+        @prefix == InputHandler::PREFIX && @normal_keys.empty? && @prefix_keys.empty?
+    end
+
+    private
+
+    KNOWN = %w[layout scrollback master_ratio master_count auto_spiral_min prefix keys].freeze
+
+    def parse(data)
+      (data.keys - KNOWN).each { |k| @errors << "unknown setting #{k.inspect}" }
+      parse_layout(data["layout"]) if data.key?("layout")
+      @scrollback = positive_integer("scrollback", data["scrollback"]) if data.key?("scrollback")
+      parse_ratio(data["master_ratio"]) if data.key?("master_ratio")
+      @master_count = positive_integer("master_count", data["master_count"]) if data.key?("master_count")
+      parse_auto(data["auto_spiral_min"]) if data.key?("auto_spiral_min")
+      parse_prefix(data["prefix"]) if data.key?("prefix")
+      parse_keys(data["keys"]) if data.key?("keys")
+    end
+
+    def parse_layout(value)
+      if value.is_a?(String) && LayoutManager::LAYOUTS.include?(value.to_sym)
+        @layout = value.to_sym
+      else
+        @errors << "layout: #{value.inspect} is not one of #{LayoutManager::LAYOUTS.join(", ")}"
+      end
+    end
+
+    def parse_ratio(value)
+      if value.is_a?(Numeric) && LayoutManager::RATIO_BOUNDS.cover?(value)
+        @master_ratio = value.to_f
+      else
+        @errors << "master_ratio: expected a number from #{LayoutManager::RATIO_BOUNDS.min} to #{LayoutManager::RATIO_BOUNDS.max}"
+      end
+    end
+
+    def parse_auto(value)
+      unless value.is_a?(Hash)
+        @errors << "auto_spiral_min: expected {\"cols\": 180, \"rows\": 30}"
+        return
+      end
+      @auto_spiral_min_cols = positive_integer("auto_spiral_min.cols", value["cols"]) if value.key?("cols")
+      @auto_spiral_min_rows = positive_integer("auto_spiral_min.rows", value["rows"]) if value.key?("rows")
+    end
+
+    def parse_prefix(value)
+      key = self.class.key_from_name(value)
+      if key && key.ord < 0x20 && key != "\e"
+        @prefix = key
+      else
+        @errors << "prefix: #{value.inspect} must be a control key like \"C-b\""
+      end
+    end
+
+    def parse_keys(value)
+      unless value.is_a?(Hash)
+        @errors << "keys: expected {\"normal\": {...}, \"prefix\": {...}}"
+        return
+      end
+      (value.keys - %w[normal prefix]).each { |k| @errors << "keys: unknown mode #{k.inspect}" }
+      parse_key_table("normal", value["normal"], @normal_keys, RESERVED_NORMAL_KEYS) if value.key?("normal")
+      parse_key_table("prefix", value["prefix"], @prefix_keys, RESERVED_PREFIX_KEYS + [@prefix]) if value.key?("prefix")
+    end
+
+    def parse_key_table(mode, table, into, reserved)
+      unless table.is_a?(Hash)
+        @errors << "keys.#{mode}: expected an object of key => action"
+        return
+      end
+      table.each do |name, action|
+        key = self.class.key_from_name(name)
+        if key.nil?
+          @errors << "keys.#{mode}: #{name.inspect} is not a key (use one character, C-x, Tab, Enter, Space or Esc)"
+        elsif reserved.include?(key)
+          @errors << "keys.#{mode}: #{name.inspect} is reserved"
+        elsif action.nil?
+          into[key] = nil
+        elsif action.is_a?(String) && action.start_with?(":") && action.length > 1
+          into[key] = [:run_command, action[1..]]
+        elsif self.class.actions.key?(action)
+          into[key] = self.class.actions[action]
+        else
+          @errors << "keys.#{mode}.#{name}: unknown action #{action.inspect}"
+        end
+      end
+    end
+
+    def positive_integer(name, value)
+      return value if value.is_a?(Integer) && value.positive?
+      @errors << "#{name}: expected a positive whole number"
+      nil
+    end
+  end
+end

data/lib/muxr/control_server.rb

@@ -1,3 +1,4 @@
+require "base64"
 require "json"
 require "socket"
 require "set"
@@ -33,6 +34,10 @@ module Muxr
     INTERNAL_ERROR   = -32603
 
     READ_CHUNK = 64 * 1024
+    # How long a half-finished pane move may hold a pane's pty paused before we
+    # assume the receiver is never coming back and resume reading it.
+    HANDOFF_TIMEOUT = 10.0
+    FLUSH_TIMEOUT = 2.0
 
     def initialize(app, socket_path)
       @app = app
@@ -41,6 +46,9 @@ module Muxr
       @clients = {}        # io => { read_buffer:, write_buffer: }
       @subscriptions = {}  # io => Set[pane_id]  (populated in step 3)
       @pending_runs  = []  # in-flight pane.run waiters (populated in step 3)
+      @mirrors   = {}      # pane_id => { io => [rows, cols] }
+      @mirror_geometry = {} # pane_id => [rows, cols] last announced to mirrors
+      @handoffs  = {}      # io => { pane:, deadline_at: }  in-flight pane moves
       @dispatcher = Dispatcher.new(app, self)
     end
 
@@ -57,6 +65,9 @@ module Muxr
       @clients.clear
       @subscriptions.clear
       @pending_runs.clear
+      @mirrors.clear
+      @handoffs.each_key { |io| abort_handoff(io) }
+      @mirror_geometry.clear
       if @server
         @server.close rescue nil
         @server = nil
@@ -120,9 +131,172 @@ module Muxr
       end
     end
 
+    def mirrored?(pane_id)
+      @mirrors.key?(pane_id.to_s)
+    end
+
+    # Relay one chunk of a pane's raw PTY output to every muxr server mirroring
+    # it. Base64 because NDJSON can't carry arbitrary binary; the receiving
+    # server feeds the decoded bytes straight into its replica emulator, so the
+    # mirror is a byte-exact copy rather than a text snapshot.
+    def on_pane_raw(pane_id, chunk)
+      viewers = @mirrors[pane_id.to_s]
+      return if viewers.nil? || viewers.empty?
+      encoded = Base64.strict_encode64(chunk)
+      viewers.each_key do |io|
+        emit_event(io, "event.pane.mirror", { "pane" => pane_id.to_s, "data" => encoded })
+      end
+    end
+
+    def add_mirror(io, pane, rows, cols)
+      id = pane.id.to_s
+      (@mirrors[id] ||= {})[io] = [rows, cols]
+      apply_mirror_constraint(pane)
+    end
+
+    def update_mirror(io, pane, rows, cols)
+      viewers = @mirrors[pane.id.to_s]
+      return false unless viewers&.key?(io)
+      viewers[io] = [rows, cols]
+      apply_mirror_constraint(pane)
+      true
+    end
+
+    def remove_mirror(io, pane_id)
+      viewers = @mirrors[pane_id.to_s]
+      return false unless viewers&.delete(io)
+      if viewers.empty?
+        @mirrors.delete(pane_id.to_s)
+        @mirror_geometry.delete(pane_id.to_s)
+      end
+      pane = pane_by_id(pane_id)
+      apply_mirror_constraint(pane) if pane
+      true
+    end
+
+    # The PTY has to fit inside every viewport looking at it — this server's own
+    # layout and each mirroring server's — so the owner runs it at the smallest.
+    # nil once the last mirror leaves, which hands the pane back to the local
+    # layout at full size.
+    def apply_mirror_constraint(pane)
+      viewers = @mirrors[pane.id.to_s]
+      if viewers.nil? || viewers.empty?
+        pane.mirror_size = nil
+      else
+        pane.mirror_size = [viewers.values.map(&:first).min, viewers.values.map(&:last).min]
+      end
+      pane.clamp_to_mirrors!
+      @app.invalidate
+    end
+
+    def mirror_geometry_event(pane)
+      term = pane.terminal
+      {
+        "pane"     => pane.id.to_s,
+        "rows"     => term.rows,
+        "cols"     => term.cols,
+        "snapshot" => Base64.strict_encode64(term.dump_ansi)
+      }
+    end
+
+    # A mirror's replica emulator must match the owner's geometry exactly — the
+    # relayed byte stream addresses absolute rows and columns. Whenever the
+    # owner's grid changes shape we push the new size along with a full repaint
+    # so the replica can resize and resync in one step.
+    def push_mirror_geometry
+      return if @mirrors.empty?
+      gone = []
+      @mirrors.each do |pane_id, viewers|
+        pane = pane_by_id(pane_id)
+        unless pane
+          viewers.each_key { |io| emit_event(io, "event.pane.gone", { "pane" => pane_id }) }
+          gone << pane_id
+          next
+        end
+        size = [pane.terminal.rows, pane.terminal.cols]
+        next if @mirror_geometry[pane_id] == size
+        @mirror_geometry[pane_id] = size
+        payload = mirror_geometry_event(pane)
+        viewers.each_key { |io| emit_event(io, "event.pane.geometry", payload) }
+      end
+      gone.each do |pane_id|
+        @mirrors.delete(pane_id)
+        @mirror_geometry.delete(pane_id)
+      end
+    end
+
     # Called once per IO.select tick. Resolves any pane.run waiters whose
     # idle window has elapsed or whose timeout has fired.
+    # A pane whose fd has been sent to another server but whose move hasn't
+    # been committed yet. It stays in the layout and keeps its Terminal, but we
+    # stop reading its pty: two servers reading one master would split the byte
+    # stream between them.
+    def handing_off?(pane)
+      @handoffs.any? { |_io, h| h[:pane].equal?(pane) }
+    end
+
+    def handoff_count
+      @handoffs.length
+    end
+
+    # Phase one of a move. The fd goes across first and the emulator state
+    # follows, because the receiver has to take the fd out of the socket with
+    # recvmsg before any plain read swallows the byte carrying it. Nothing is
+    # torn down here — until the far side commits, the pane is still ours and
+    # #abort_handoff puts it straight back to work.
+    def begin_handoff(io, request_id, pane)
+      state = pane.terminal.dump_transfer.merge(
+        "pane"    => pane.id.to_s,
+        "pid"     => pane.pid,
+        "cwd"     => safe_pane_cwd(pane),
+        "name"    => (pane.name if pane.respond_to?(:name)),
+        "session" => @app.session.name
+      )
+      respond_result(io, id: request_id, result: { "ready" => true })
+      return unless flush_blocking(io)
+      io.send_io(pane.io)
+      @handoffs[io] = { pane: pane, deadline_at: monotonic_now + HANDOFF_TIMEOUT }
+      write_json(io, { "id" => request_id, "result" => state })
+      @app.invalidate
+      true
+    rescue SystemCallError, IOError
+      abort_handoff(io)
+      false
+    end
+
+    # Phase two: the receiver has the fd and a working pane, so let go for
+    # real. The pty is closed here and the child is detached rather than
+    # killed — it belongs to the other server now.
+    def commit_handoff(io)
+      handoff = @handoffs.delete(io)
+      return nil unless handoff
+      pane = handoff[:pane]
+      pane.relinquish!
+      @app.session.window.remove_pane(pane)
+      @app.renderer.reset_frame! if @app.respond_to?(:renderer) && @app.renderer
+      @app.invalidate
+      pane
+    end
+
+    # The move fell through (receiver died, gave up, or never answered). We
+    # never stopped owning the pane, so there is nothing to undo but the
+    # read pause.
+    def abort_handoff(io)
+      handoff = @handoffs.delete(io)
+      return false unless handoff
+      @app.invalidate
+      true
+    end
+
+    def expire_handoffs
+      return if @handoffs.empty?
+      now = monotonic_now
+      @handoffs.select { |_io, h| now >= h[:deadline_at] }.each_key { |io| abort_handoff(io) }
+    end
+
     def tick
+      expire_handoffs
+      push_mirror_geometry
       return if @pending_runs.empty?
       now = monotonic_now
       completed = []
@@ -222,8 +396,12 @@ module Muxr
     end
 
     def drop_client(io)
+      abort_handoff(io)
       @clients.delete(io)
       @subscriptions.delete(io)
+      # A mirroring server that went away releases its claim on pane geometry:
+      # the pane snaps back to the owner's own layout size.
+      @mirrors.keys.each { |pane_id| remove_mirror(io, pane_id) }
       # Any pane.run waiters owned by this client are silently abandoned —
       # there's nobody to respond to.
       @pending_runs.reject! { |r| r[:client_io] == io } unless @pending_runs.empty?
@@ -299,6 +477,28 @@ module Muxr
       write_json(io, { "method" => method, "params" => params })
     end
 
+    # Push everything queued for +io+ out now. Only used ahead of send_io,
+    # where the fd has to land after bytes the receiver has already been told
+    # to expect; everywhere else the event loop's buffered drain is right.
+    def flush_blocking(io)
+      state = @clients[io]
+      return false unless state
+      deadline = monotonic_now + FLUSH_TIMEOUT
+      until state[:write_buffer].empty?
+        return false if monotonic_now >= deadline
+        drain_client(io)
+        next if state[:write_buffer].empty?
+        IO.select(nil, [io], nil, deadline - monotonic_now)
+      end
+      true
+    end
+
+    def safe_pane_cwd(pane)
+      pane.respond_to?(:cwd) ? pane.cwd : nil
+    rescue StandardError
+      nil
+    end
+
     def write_json(io, hash)
       return unless @clients.key?(io)
       line = JSON.generate(hash) + "\n"
@@ -347,6 +547,13 @@ module Muxr
       when "pane.run"         then pane_run(params, client_io, request_id)
       when "pane.subscribe"   then pane_subscribe(params, client_io)
       when "pane.unsubscribe" then pane_unsubscribe(params, client_io)
+      when "pane.mirror"        then pane_mirror(params, client_io)
+      when "pane.mirror_resize" then pane_mirror_resize(params, client_io)
+      when "pane.unmirror"      then pane_unmirror(params, client_io)
+      when "pane.redraw"        then pane_redraw(params)
+      when "pane.move"          then pane_move(params, client_io, request_id)
+      when "pane.move_commit"   then pane_move_commit(client_io)
+      when "pane.move_abort"    then pane_move_abort(client_io)
       when "layout.set"       then layout_set(params)
       when "layout.cycle"     then layout_cycle
       when "drawer.toggle"    then drawer_action(:toggle_drawer)
@@ -406,6 +613,11 @@ module Muxr
           entry["cwd"] = safe_cwd(pane)
           entry["rows"] = pane.terminal.rows
           entry["cols"] = pane.terminal.cols
+          # Present on a pane borrowed from another session: "<session>:<id>"
+          # there. Reads and input work as usual and reach the real shell, but
+          # pane.kill only drops the mirror.
+          entry["origin"] = pane.origin if pane.respond_to?(:origin) && pane.origin
+          entry["name"] = pane.name if pane.respond_to?(:name) && pane.name
         end
         entry
       end
@@ -536,6 +748,79 @@ module Muxr
       { "pane" => pane.id.to_s, "subscribed" => false, "was_subscribed" => removed }
     end
 
+    # Hand a pane to another muxr server as a live mirror: it gets a full ANSI
+    # snapshot of the grid now and every subsequent raw PTY byte as it arrives,
+    # while the pane itself stays right here, running and usable. Input the
+    # mirror collects comes back through pane.send_input.
+    def pane_mirror(params, client_io)
+      pane = find_pane(params)
+      ensure_not_private!(pane, "pane.mirror")
+      rows = clamp_int(params["rows"], min: 1, max: 1000, default: pane.terminal.rows)
+      cols = clamp_int(params["cols"], min: 1, max: 1000, default: pane.terminal.cols)
+      @server.add_mirror(client_io, pane, rows, cols)
+      @app.invalidate
+      @server.mirror_geometry_event(pane).merge(
+        "session" => @app.session.name,
+        "cwd"     => safe_cwd(pane)
+      )
+    end
+
+    def pane_mirror_resize(params, client_io)
+      pane = find_pane(params)
+      rows = clamp_int(params["rows"], min: 1, max: 1000, default: pane.terminal.rows)
+      cols = clamp_int(params["cols"], min: 1, max: 1000, default: pane.terminal.cols)
+      unless @server.update_mirror(client_io, pane, rows, cols)
+        raise Error.new("pane.mirror_resize: not mirroring pane #{pane.id}")
+      end
+      { "pane" => pane.id.to_s, "rows" => rows, "cols" => cols }
+    end
+
+    def pane_unmirror(params, client_io)
+      pane = find_pane(params)
+      removed = @server.remove_mirror(client_io, pane.id)
+      @app.invalidate
+      { "pane" => pane.id.to_s, "mirrored" => false, "was_mirrored" => removed }
+    end
+
+    # Hand the pane over for good: the pty fd itself crosses the socket, so the
+    # shell keeps running with all its state and simply belongs to the other
+    # server afterwards. Deferred because the reply, the fd and the emulator
+    # state have to be interleaved in one exact order — see #begin_handoff.
+    def pane_move(params, client_io, request_id)
+      raise Error.new("pane.move: missing request id") unless request_id
+      pane = find_pane(params)
+      ensure_not_private!(pane, "pane.move")
+      if pane.respond_to?(:mirror?) && pane.mirror?
+        raise Error.new("pane.move: pane #{pane.id} is itself borrowed from #{pane.origin}; move it from there")
+      end
+      # Panes already promised to another server don't count as ours: two moves
+      # in flight at once must not be able to empty the session between them,
+      # which would shut the server down out from under the user.
+      if @app.session.window.panes.length - @server.handoff_count <= 1
+        raise Error.new("pane.move: pane #{pane.id} is the last pane in session #{@app.session.name}; moving it would end that session")
+      end
+      raise Error.new("pane.move: pane #{pane.id} is already being moved") if @server.handing_off?(pane)
+      @server.begin_handoff(client_io, request_id, pane)
+      :deferred
+    end
+
+    def pane_move_commit(client_io)
+      pane = @server.commit_handoff(client_io)
+      raise Error.new("pane.move_commit: no move in flight") unless pane
+      { "pane" => pane.id.to_s, "moved" => true }
+    end
+
+    def pane_move_abort(client_io)
+      { "aborted" => @server.abort_handoff(client_io) }
+    end
+
+    def pane_redraw(params)
+      pane = find_pane(params)
+      ensure_not_private!(pane, "pane.redraw")
+      pane.request_redraw
+      { "pane" => pane.id.to_s }
+    end
+
     def layout_set(params)
       name = params["layout"].to_s
       sym = name.to_sym
@@ -602,7 +887,7 @@ module Muxr
         end
         [raw, wire]
       elsif params[text_key].is_a?(String)
-        text = params[text_key]
+        text = decode_text(params[text_key], params["base64"])
         [text.b, wrap_bracketed(text, bracketed)]
       elsif required
         raise Error.new("missing #{text_key} (or `keys`)")
@@ -611,6 +896,16 @@ module Muxr
       end
     end
 
+    # Keystrokes relayed from a mirroring server arrive base64-encoded: input
+    # bytes are not always valid UTF-8 (Alt- sequences, mouse reports) and JSON
+    # strings must be.
+    def decode_text(text, base64)
+      return text unless base64
+      Base64.strict_decode64(text)
+    rescue ArgumentError
+      raise Error.new("data: malformed base64")
+    end
+
     def clamp_int(value, min:, max:, default:)
       v = value.is_a?(Integer) ? value : default
       v.clamp(min, max)
@@ -632,8 +927,11 @@ module Muxr
       else
         id = id_or_slot.to_s
         pane = win.panes.find { |p| p.id.to_s == id }
-        raise Error.new("pane: no pane with id #{id.inspect}") unless pane
-        pane
+        return pane if pane
+        named = win.panes.select { |p| p.respond_to?(:name) && p.name == id }
+        raise Error.new("pane: #{named.length} panes are named #{id.inspect}; use an id") if named.length > 1
+        raise Error.new("pane: no pane with id or name #{id.inspect}") if named.empty?
+        named.first
       end
     end