samagotchi 0.66.0 → 0.68.0

data/lib/samagotchi/desktop/macos/Panel.swift

@@ -1,13 +1,14 @@
 // The Spotlight-like panel: a message line on top, the images (a screenshot,
 // Finder files, drops) as thumbnails, the text (selection or clipboard)
 // below as quoted context, then a "New session" row, an "Everyone it
-// concerns" row and the targets: live sessions, agents in kitty windows
-// (Kitty.swift), recent sessions. ⏎ sends a message (`chi send`, or `chi
-// send --new` on the new row, with `--image` per image; pasted with Enter
-// into a kitty window), ⌘⏎ a note (`chi note`, text only; `chi broadcast`
-// on the Everyone row, Broadcast.swift), ⌥⏎ a paste without Enter (kitty
-// windows only), ⇧⏎ a newline. ⌘M (or a click on the new row's model) opens the model
-// chooser for a new session in place of the targets (Models.swift).
+// concerns" row and the targets: live sessions, agents in terminals
+// (AgentTerminal.swift: kitty windows, tmux panes), recent sessions. ⏎ sends a message
+// (`chi send`, or `chi send --new` on the new row, with `--image` per image;
+// pasted with Enter into an agent's terminal), ⌘⏎ a note (`chi note`, text
+// only; `chi broadcast` on the Everyone row, Broadcast.swift), ⌥⏎ a paste
+// without Enter (agents in terminals only), ⇧⏎ a newline. ⌘M (or a click on
+// the new row's model) opens the model chooser for a new session in place of
+// the targets (Models.swift).
 import AppKit
 import SwiftUI
 
@@ -31,14 +32,18 @@ final class PanelModel: ObservableObject {
   /// @State and don't ship it ("plugin for module 'SwiftUIMacros' not found").
   @Published var hoveredImage: UUID?
   @Published var sessions: [LiveSession] = []
-  /// Agent windows in kitty; kittyOn when launch.json has a kitty section.
-  @Published var kittyWindows: [KittyWindow] = []
-  @Published var kittyOn = false
-  /// Set once the kitty listing answered: "no agents in kitty" or an error.
-  @Published var kittyNote: String?
-  /// Chi session ids and kitty window keys (never alike: UUIDs vs paths).
+  /// Agents in terminals, and the terminals launch.json switches on
+  /// (none: no agent rows and no note).
+  @Published var agentTargets: [AgentTarget] = []
+  @Published var agentTerminalNames: [String] = []
+  /// Set once the listing answered with no rows: "no agents in kitty"
+  /// (the terminals that answered).
+  @Published var agentNote: String?
+  /// Why a terminal can't be asked, with or without rows; " · " between two.
+  @Published var agentErrors: String?
+  /// Chi session ids and agent keys (never alike: UUIDs vs paths).
   @Published var selected: Set<String> = []
-  /// The user changed the selection: a late kitty listing keeps it.
+  /// The user changed the selection: a late agent listing keeps it.
   var touched = false
   /// The "New session" row; never together with sessions (`--new` takes no ids).
   @Published var newSelected = false
@@ -79,15 +84,15 @@ final class PanelModel: ObservableObject {
   /// A note's text (stdin of `chi note`): the message line, then the context.
   var noteText: String { [trimmedPrompt, hasContext ? text : ""].filter { !$0.isEmpty }.joined(separator: "\n\n") }
   var sendEnabled: Bool {
-    canSend && (newSelected || everyoneSelected || !selectedIds.isEmpty || !selectedKitty.isEmpty)
+    canSend && (newSelected || everyoneSelected || !selectedIds.isEmpty || !selectedAgents.isEmpty)
       && (!trimmedPrompt.isEmpty || hasContext)
   }
   var live: [LiveSession] { sessions.filter { !$0.recent } }
 
   /// One list for rows, ⌘ numbers and selection: live sessions (oldest
-  /// started first: their numbers stay put), then kitty windows, then
-  /// recent sessions.
-  var targets: [Target] { live.map(Target.chi) + kittyWindows.map(Target.kitty) + recent.map(Target.chi) }
+  /// started first: their numbers stay put), then agents in terminals,
+  /// then recent sessions.
+  var targets: [Target] { live.map(Target.chi) + agentTargets.map(Target.agent) + recent.map(Target.chi) }
 
   /// Up to maxImages; the rest is dropped (and its temp files deleted).
   func add(_ new: [PanelImage]) {
@@ -190,11 +195,11 @@ final class PanelModel: ObservableObject {
   }
 
   /// The last choice, where still live or listed; else the only live
-  /// session; else, with none live and no kitty window chosen, the new row.
+  /// session; else, with none live and no agent chosen, the new row.
   /// A recent (stopped) one is never preselected: a message would wake it.
   func preselect() {
     let last = Set(UserDefaults.standard.stringArray(forKey: Self.lastChoiceKey) ?? [])
-    selected = last.intersection(Set(live.map(\.id) + kittyWindows.map(\.key)))
+    selected = last.intersection(Set(live.map(\.id) + agentTargets.map(\.key)))
     if selected.isEmpty, live.count == 1 { selected = [live[0].id] }
     newSelected = live.isEmpty && selected.isEmpty
   }
@@ -239,31 +244,49 @@ final class PanelModel: ObservableObject {
     sessions.filter { selected.contains($0.id) && $0.valid }.map(\.id)
   }
 
-  var selectedKitty: [KittyWindow] { kittyWindows.filter { selected.contains($0.key) } }
+  /// A listing's answer: the rows, "no agents in kitty" when there are
+  /// none, and why a terminal can't be asked.
+  func showAgents(_ targets: [AgentTarget], errors: [(name: String, error: AgentTerminalError)]) {
+    agentTargets = targets
+    let answered = agentTerminalNames.filter { name in !errors.contains { $0.name == name } }
+    agentNote = targets.isEmpty && !answered.isEmpty ? "no agents in \(answered.joined(separator: " or "))" : nil
+    agentErrors = errors.isEmpty ? nil : errors.map(\.error.description).joined(separator: " · ")
+  }
+
+  /// ⌥⏎'s refusal: names the terminals switched on.
+  var pasteOnlyRefusal: String {
+    switch Set(agentTerminalNames) {
+    case ["tmux"]: return "Paste only is for tmux panes"
+    case ["kitty", "tmux"]: return "Paste only is for agents in kitty or tmux"
+    default: return "Paste only is for kitty windows"
+    }
+  }
+
+  var selectedAgents: [AgentTarget] { agentTargets.filter { selected.contains($0.key) } }
 
   /// Who the message goes to, for the placeholder: chi, or the one agent
-  /// when only kitty windows running it are chosen.
+  /// when only terminals running it are chosen.
   var addressee: String {
     if everyoneSelected { return "everyone it concerns" }
-    let agents = Set(selectedKitty.map(\.agent))
+    let agents = Set(selectedAgents.map(\.agent))
     return agents.count == 1 && selectedIds.isEmpty && !newSelected ? agents.first! : "chi"
   }
 }
 
-/// A row of the panel: a chi session or an agent in a kitty window.
+/// A row of the panel: a chi session or an agent in a terminal.
 enum Target: Identifiable {
   case chi(LiveSession)
-  case kitty(KittyWindow)
+  case agent(AgentTarget)
 
   var id: String {
     switch self {
     case .chi(let session): return session.id
-    case .kitty(let window): return window.key
+    case .agent(let target): return target.key
     }
   }
 }
 
-/// ⏎ message, ⌘⏎ note, ⌥⏎ paste (kitty windows only: no Enter).
+/// ⏎ message, ⌘⏎ note, ⌥⏎ paste (agents in terminals only: no Enter).
 enum SendKind { case message, note, paste }
 
 struct PanelView: View {
@@ -349,19 +372,19 @@ struct PanelView: View {
         default:
           newRow
           everyoneRow
-          let live = model.live.count, kitty = model.kittyWindows.count
+          let live = model.live.count, agents = model.agentTargets.count
           ForEach(Array(model.targets.prefix(9).enumerated()), id: \.element.id) { index, target in
-            if index == live && kitty > 0 { groupHeader("kitty", first: index == 0) }
-            if index == live + kitty && !model.recent.isEmpty {
-              if kitty == 0 { kittyNoteLine }
+            if index == live && agents > 0 { groupHeader(agentHeader, first: index == 0) }
+            if index == live + agents && !model.recent.isEmpty {
+              agentNoteLines
               groupHeader("recent", first: index == 0)
             }
             switch target {
             case .chi(let session): row(session, index: index)
-            case .kitty(let window): kittyRow(window, index: index)
+            case .agent(let agent): agentRow(agent, index: index)
             }
           }
-          if model.recent.isEmpty && kitty == 0 { kittyNoteLine }
+          if model.recent.isEmpty { agentNoteLines }
         }
       }
     }
@@ -377,34 +400,47 @@ struct PanelView: View {
     .padding(.horizontal, 8).padding(.top, first ? 2 : 6)
   }
 
-  /// "no agents in kitty" (or why kitty can't be asked) where the kitty
-  /// rows would be; nothing without a kitty section.
-  @ViewBuilder var kittyNoteLine: some View {
-    if model.kittyOn, let note = model.kittyNote {
-      HStack(spacing: 6) {
-        Image(systemName: "terminal").font(.system(size: 11))
-        Text(note).font(.system(size: 11)).lineLimit(1)
-      }
-      .foregroundColor(.secondary.opacity(0.7))
-      .padding(.horizontal, 8).padding(.vertical, 4)
+  /// The agent rows' divider: the terminal's name ("kitty").
+  var agentHeader: String { model.agentTerminalNames.count == 1 ? model.agentTerminalNames[0] : "agents" }
+
+  /// After the agent rows: "no agents in kitty" where they would be, and
+  /// why a terminal can't be asked (beside another's rows too); nothing
+  /// without a terminal section.
+  @ViewBuilder var agentNoteLines: some View {
+    if !model.agentTerminalNames.isEmpty {
+      if model.agentTargets.isEmpty, let note = model.agentNote { agentNoteLine(note) }
+      if let errors = model.agentErrors { agentNoteLine(errors) }
     }
   }
 
-  func kittyRow(_ window: KittyWindow, index: Int) -> some View {
-    let on = model.selected.contains(window.key)
-    return Button(action: { model.toggle(window.key) }) {
+  func agentNoteLine(_ text: String) -> some View {
+    HStack(spacing: 6) {
+      Image(systemName: "terminal").font(.system(size: 11))
+      Text(text).font(.system(size: 11)).lineLimit(1)
+    }
+    .foregroundColor(.secondary.opacity(0.7))
+    .padding(.horizontal, 8).padding(.vertical, 4)
+  }
+
+  func agentRow(_ target: AgentTarget, index: Int) -> some View {
+    let on = model.selected.contains(target.key)
+    return Button(action: { model.toggle(target.key) }) {
       HStack(spacing: 10) {
         Image(systemName: on ? "checkmark.circle.fill" : "circle")
           .font(.system(size: 16))
           .foregroundColor(on ? .accentColor : .secondary)
         VStack(alignment: .leading, spacing: 1) {
-          Text(window.title.isEmpty ? window.label : "\(window.agent) · \(window.title)")
+          Text(target.title.isEmpty ? target.label : "\(target.agent) · \(target.title)")
             .font(.system(size: 13, weight: .medium)).lineLimit(1)
-          Text(window.shortCwd).font(.system(size: 11)).foregroundColor(.secondary).lineLimit(1)
+          Text(target.shortCwd).font(.system(size: 11)).foregroundColor(.secondary).lineLimit(1)
         }
         Spacer()
+        // Which terminal, when two are on.
+        if model.agentTerminalNames.count > 1 {
+          Text(target.terminal).font(.system(size: 10)).foregroundColor(.secondary)
+        }
         Image(systemName: "terminal").font(.system(size: 12)).foregroundColor(.secondary)
-          .help("\(window.agent) in a kitty window: ⏎ pastes and presses Enter, ⌥⏎ only pastes")
+          .help("\(target.agent) in \(target.whereabouts): ⏎ pastes and presses Enter, ⌥⏎ only pastes")
         Text("⌘\(index + 1)").font(.system(size: 11, design: .rounded)).foregroundColor(.secondary)
       }
       .padding(.horizontal, 8).padding(.vertical, 6)
@@ -610,9 +646,9 @@ struct PanelView: View {
         .frame(maxWidth: .infinity, alignment: .leading)
 
       // ⏎, ⌘⏎ and ⌥⏎ are handled by the panel (KeyPanel.sendEvent),
-      // whatever has the focus; the buttons are for the mouse. Only kitty
-      // windows chosen: Paste instead of Note.
-      if !model.selectedKitty.isEmpty && model.selectedIds.isEmpty && !model.newSelected {
+      // whatever has the focus; the buttons are for the mouse. Only agents
+      // in terminals chosen: Paste instead of Note.
+      if !model.selectedAgents.isEmpty && model.selectedIds.isEmpty && !model.newSelected {
         Button("Paste ⌥⏎") { send(.paste) }
           .disabled(!model.sendEnabled)
           .help("paste it into the agent's input without Enter: add more, then press Enter there")
@@ -622,7 +658,7 @@ struct PanelView: View {
           .help("share it as a note with every session it concerns (chi broadcast); starts no turn")
       } else {
         Button("Note ⌘⏎") { send(.note) }
-          .disabled(!model.sendEnabled || !model.selectedKitty.isEmpty || model.newSelected)
+          .disabled(!model.sendEnabled || !model.selectedAgents.isEmpty || model.newSelected)
           .help(model.newSelected ? "a note needs a session: pick one, or ⏎ starts a new one with the message"
                                   : "add it as background the model sees on its next turn; starts no turn")
       }
@@ -733,8 +769,8 @@ final class KeyPanel: NSPanel {
 final class PanelController: NSObject, NSWindowDelegate {
   let model = PanelModel()
   let runner = ChiRunner()
-  /// This open's kitty runner (launch.json read at each open).
-  private var kitty: KittyRunner?
+  /// This open's agent terminals (launch.json read at each open).
+  private var agents: AgentTerminals?
   private var panel: KeyPanel!
   private var returnTo: NSRunningApplication?
   /// Images a running `chi send` still reads: not deleted on close.
@@ -858,7 +894,7 @@ final class PanelController: NSObject, NSWindowDelegate {
     placeOnActiveScreen()
     panel.makeKeyAndOrderFront(nil)
     loadSessions()
-    loadKitty()
+    loadAgents()
     loadModel()
     loadModels()
   }
@@ -891,22 +927,17 @@ final class PanelController: NSObject, NSWindowDelegate {
 
   /// Beside the chi listing, never blocking or failing it: a listing that
   /// answers after the sessions preselects again unless the user chose.
-  private func loadKitty() {
-    let runner = KittyRunner(launchPath: self.runner.launchPath)
-    kitty = runner
-    model.kittyOn = runner.settings != nil
-    model.kittyWindows = []
-    model.kittyNote = nil
-    guard model.kittyOn else { return }
-    runner.windows { [weak self] result in
-      guard let self, self.kitty === runner else { return }
-      switch result {
-      case .success(let windows):
-        self.model.kittyWindows = windows
-        self.model.kittyNote = windows.isEmpty ? "no agents in kitty" : nil
-      case .failure(let error):
-        self.model.kittyNote = error.description
-      }
+  private func loadAgents() {
+    let terminals = AgentTerminals(launchPath: runner.launchPath)
+    agents = terminals
+    model.agentTerminalNames = terminals.names
+    model.agentTargets = []
+    model.agentNote = nil
+    model.agentErrors = nil
+    guard !terminals.isEmpty else { return }
+    terminals.list { [weak self] targets, errors in
+      guard let self, self.agents === terminals else { return }
+      self.model.showAgents(targets, errors: errors)
       if self.model.phase != .loading && !self.model.touched { self.model.preselect() }
     }
   }
@@ -939,13 +970,13 @@ final class PanelController: NSObject, NSWindowDelegate {
   }
 
   /// Fans out: one `chi send` / `chi note` for the chi sessions (or the new
-  /// row) and one paste per kitty window, with one combined line when all
-  /// finished. Images the helper wrote are copied for kitty first (chi's
+  /// row) and one paste per agent, with one combined line when all
+  /// finished. Images the helper wrote are copied for the agents first (chi's
   /// send deletes them) and deleted only after every job.
   func send(_ kind: SendKind) {
     if model.everyoneSelected { broadcast(kind); return }
     let ids = model.selectedIds
-    let windows = model.selectedKitty
+    let windows = model.selectedAgents
     let new = model.newSelected
     if kind == .note, !windows.isEmpty {
       NSSound.beep()
@@ -954,7 +985,7 @@ final class PanelController: NSObject, NSWindowDelegate {
     }
     if kind == .paste, windows.isEmpty || !ids.isEmpty || new {
       NSSound.beep()
-      model.message = "Paste only is for kitty windows"
+      model.message = model.pasteOnlyRefusal
       return
     }
     // A note into a session that doesn't exist yet makes no sense.
@@ -977,29 +1008,34 @@ final class PanelController: NSObject, NSWindowDelegate {
     }
     let images = kind == .note ? [] : model.images
     inFlight.formUnion(images.map(\.id))
-    let kittyText = windows.isEmpty ? "" : Kitty.text(context: model.hasContext ? model.text : "", message: model.trimmedPrompt,
+    let agentText = windows.isEmpty ? "" : AgentText.text(context: model.hasContext ? model.text : "", message: model.trimmedPrompt,
                                                      imagePaths: ImageIntake.keepForPaste(images), pasteOnly: kind == .paste)
 
     let open = opens
     let group = DispatchGroup()
     var chiOutcome: SendOutcome?
-    var kittyOutcomes: [(KittyWindow, KittyError?)] = []
+    var agentOutcomes: [(AgentTarget, AgentTerminalError?)] = []
+    let terminals = agents ?? AgentTerminals(launchPath: runner.launchPath)
     if new || !ids.isEmpty {
       group.enter()
       sendToChi(kind, ids: ids, new: new, images: images) { outcome in chiOutcome = outcome; group.leave() }
     }
     for window in windows {
+      guard let terminal = terminals.terminal(for: window.key) else {
+        agentOutcomes.append((window, .failed("not an agent: \(window.key)")))
+        continue
+      }
       group.enter()
-      (kitty ?? KittyRunner(launchPath: runner.launchPath)).send(key: window.key, text: kittyText, pasteOnly: kind == .paste) { result in
-        if case .failure(let error) = result { kittyOutcomes.append((window, error)) } else { kittyOutcomes.append((window, nil)) }
+      terminal.send(key: window.key, text: agentText, pasteOnly: kind == .paste) { result in
+        if case .failure(let error) = result { agentOutcomes.append((window, error)) } else { agentOutcomes.append((window, nil)) }
         group.leave()
       }
     }
     group.notify(queue: .main) { [weak self] in
       guard let self else { return }
       self.inFlight.subtract(images.map(\.id))
-      let pasted = windows.filter { w in kittyOutcomes.contains { $0.0 == w && $0.1 == nil } }
-      let failed = kittyOutcomes.compactMap { outcome in outcome.1.map { "\(outcome.0.label): \($0.description)" } }
+      let pasted = windows.filter { w in agentOutcomes.contains { $0.0 == w && $0.1 == nil } }
+      let failed = agentOutcomes.compactMap { outcome in outcome.1.map { "\(outcome.0.label): \($0.description)" } }
       let ok = (chiOutcome?.ok ?? true) && failed.isEmpty
       // Sent: the temp files go (and the thumbnails). Else they stay for
       // another try, unless the panel was closed or reopened meanwhile.

data/lib/samagotchi/desktop/macos/ProcessRunner.swift

@@ -1,6 +1,6 @@
 // Runs one outside program without a shell: stdin written from a
 // background queue, stdout/stderr drained as they come (no pipe deadlock on
-// big input or output), a time limit. ChiRunner and KittyRunner use it.
+// big input or output), a time limit. ChiRunner and the agent terminals use it.
 import Foundation
 
 struct ChiResult {

data/lib/samagotchi/desktop/macos/Tmux.swift

@@ -0,0 +1,239 @@
+// Agent CLIs (claude, codex, …) in tmux panes as panel targets, through the
+// tmux binary (`tmux -u -S <socket> …`): every server whose socket is in the
+// launch file's socket dir (tmux's own `-L` place). The settings come from
+// launch.json's "tmux" section (chi desktop bakes it from config.yml's
+// tmux:, binary and socket dir resolved then); without it there are no tmux
+// targets. One of the AgentTerminals (AgentTerminal.swift).
+import Foundation
+
+struct TmuxSettings: Decodable, Equatable {
+  let binary: String
+  let socketDir: String
+  let agents: [String]
+
+  enum CodingKeys: String, CodingKey {
+    case socketDir = "socket_dir"
+    case binary, agents
+  }
+}
+
+/// The pure parts: list-panes and ps rows into targets, keys.
+enum Tmux {
+  /// One pane of `list-panes -a -F listFormat`.
+  struct Pane: Equatable {
+    let id: String
+    let tty: String
+    let command: String
+    let path: String
+    let inMode: Bool
+    /// "main:1.0": session, window index, pane index.
+    let place: String
+    let host: String
+    let serverPid: String
+    let title: String
+  }
+
+  /// Tab-separated, the title last (a tab in a title can't shift the
+  /// fields). `#{pid}` is the server's: pane ids restart with a server.
+  static let listFormat = ["#{pane_id}", "#{pane_tty}", "#{pane_current_command}", "#{pane_current_path}",
+                           "#{pane_dead}", "#{pane_in_mode}", "#{session_name}:#{window_index}.#{pane_index}",
+                           "#{host}", "#{pid}", "#{pane_title}"].joined(separator: "\t")
+
+  /// The live panes of one list-panes; dead ones (remain-on-exit) dropped.
+  static func panes(listPanes: String) -> [Pane] {
+    listPanes.split(separator: "\n").compactMap { line in
+      let f = line.split(separator: "\t", maxSplits: 9, omittingEmptySubsequences: false).map(String.init)
+      guard f.count == 10, f[0].hasPrefix("%"), f[4] != "1" else { return nil }
+      return Pane(id: f[0], tty: f[1], command: f[2], path: f[3], inMode: f[5] == "1", place: f[6], host: f[7],
+                  serverPid: f[8], title: f[9])
+    }
+  }
+
+  /// The foreground programs' names per tty ("ttys003", no /dev/), from
+  /// `ps -A -o pgid=,tpgid=,tty=,args=`: a process whose group is its
+  /// terminal's foreground group; the basenames of its first two words, as
+  /// kitty's cmdline[0] and [1] (the native claude sets its title to
+  /// "claude"; codex runs as `node …/codex`). Only +ttys+ are kept.
+  static func foreground(ps: String, ttys: Set<String>) -> [String: [String]] {
+    var found: [String: [String]] = [:]
+    for line in ps.split(separator: "\n") {
+      let f = line.split(separator: " ", maxSplits: 3, omittingEmptySubsequences: true).map(String.init)
+      guard f.count == 4, ttys.contains(f[2]), f[0] == f[1] else { continue }
+      let names = f[3].split(separator: " ").prefix(2).map { AgentText.programName(String($0)) }.filter { !$0.isEmpty }
+      found[f[2], default: []] += names
+    }
+    return found
+  }
+
+  /// "/dev/ttys003" → "ttys003", ps's spelling.
+  static func ttyName(_ tty: String) -> String { tty.hasPrefix("/dev/") ? String(tty.dropFirst(5)) : tty }
+
+  /// The panes whose foreground program is an agent: matched on ps's names
+  /// when ps has the tty, else on pane_current_command (not both: with `*`
+  /// the last name wins, and the native claude's current command is its
+  /// version, "2.1.296"). A title equal to the host name is tmux's default:
+  /// none.
+  static func targets(panes: [Pane], foreground: [String: [String]], agents: [String], socket: String) -> [AgentTarget] {
+    panes.compactMap { pane in
+      let fromPs = foreground[ttyName(pane.tty)] ?? []
+      let names = fromPs.isEmpty ? [pane.command].filter { !$0.isEmpty } : fromPs
+      guard let agent = AgentText.agent(names: names, agents: agents) else { return nil }
+      return AgentTarget(terminal: "tmux", key: "tmux:\(socket)#\(pane.serverPid)#\(pane.id)", agent: agent,
+                         title: pane.title == pane.host ? "" : AgentText.cleanTitle(pane.title), cwd: pane.path,
+                         place: pane.place, names: names)
+    }
+  }
+
+  /// A `tmux:<socket>#<server pid>#<pane id>` key back into its parts.
+  static func parse(key: String) -> (socket: String, serverPid: String, paneId: String)? {
+    guard key.hasPrefix("tmux:") else { return nil }
+    let rest = key.dropFirst("tmux:".count)
+    guard let paneHash = rest.lastIndex(of: "#") else { return nil }
+    let paneId = String(rest[rest.index(after: paneHash)...])
+    let head = rest[..<paneHash]
+    guard let pidHash = head.lastIndex(of: "#") else { return nil }
+    let pid = String(head[head.index(after: pidHash)...])
+    let socket = String(head[..<pidHash])
+    guard !socket.isEmpty, Int(pid) != nil, paneId.hasPrefix("%"), Int(paneId.dropFirst()) != nil else { return nil }
+    return (socket, pid, paneId)
+  }
+}
+
+final class TmuxRunner: AgentTerminal {
+  let name = "tmux"
+  let settings: TmuxSettings
+  let queue: DispatchQueue
+  let env: [String: String]
+  let listTimeout: TimeInterval = 2
+  let sendTimeout: TimeInterval = 5
+
+  /// @param queue where completions run (the main queue in the app)
+  init(settings: TmuxSettings, queue: DispatchQueue = .main,
+       env: [String: String] = ProcessInfo.processInfo.environment) {
+    self.settings = settings
+    self.queue = queue
+    self.env = env
+  }
+
+  /// The helper's env minus tmux's own variables: a helper started from a
+  /// pane must not lean on that pane's server.
+  private var tmuxEnv: [String: String] { env.filter { $0.key != "TMUX" && $0.key != "TMUX_PANE" } }
+
+  func owns(key: String) -> Bool { Tmux.parse(key: key) != nil }
+
+  private var binaryError: AgentTerminalError? {
+    let binary = settings.binary
+    if binary.isEmpty { return .config("tmux not found: set tmux.binary, then chi update") }
+    guard FileManager.default.isExecutableFile(atPath: binary) else {
+      return .config("tmux not found at \(binary): set tmux.binary, then chi update")
+    }
+    return nil
+  }
+
+  /// The servers' sockets: the socket files in socket_dir (none when it is
+  /// missing). A stale one (a killed server's) drops out at list-panes.
+  func sockets() -> [String] {
+    let dir = settings.socketDir
+    let names = (try? FileManager.default.contentsOfDirectory(atPath: dir)) ?? []
+    return names.sorted().map { (dir as NSString).appendingPathComponent($0) }
+      .filter { (try? FileManager.default.attributesOfItem(atPath: $0)[.type] as? FileAttributeType) == .typeSocket }
+  }
+
+  /// Agent panes of every live server; one ps over all of them names the
+  /// foreground programs (if it fails, pane_current_command alone).
+  func list(completion: @escaping (Result<[AgentTarget], AgentTerminalError>) -> Void) {
+    if let error = binaryError { queue.async { completion(.failure(error)) }; return }
+    let sockets = self.sockets()
+    guard !sockets.isEmpty else { queue.async { completion(.success([])) }; return }
+    let group = DispatchGroup()
+    let lock = NSLock()
+    var bySocket: [String: [Tmux.Pane]] = [:]
+    for socket in sockets {
+      group.enter()
+      tmux(socket, ["list-panes", "-a", "-F", Tmux.listFormat], timeout: listTimeout, on: .global()) { result in
+        if case .success(let r) = result, r.status == 0, !r.timedOut {
+          let panes = Tmux.panes(listPanes: r.stdout)
+          lock.lock(); bySocket[socket] = panes; lock.unlock()
+        }
+        group.leave()
+      }
+    }
+    group.notify(queue: queue) {
+      let all = sockets.flatMap { socket in (bySocket[socket] ?? []).map { (socket, $0) } }
+      guard !all.isEmpty else { completion(.success([])); return }
+      let ttys = Set(all.map { Tmux.ttyName($0.1.tty) })
+      ProcessRunner.run(executable: "/bin/ps", args: ["-A", "-ww", "-o", "pgid=,tpgid=,tty=,args="], env: self.tmuxEnv,
+                        timeout: self.listTimeout, queue: self.queue) { result in
+        var foreground: [String: [String]] = [:]
+        if case .success(let r) = result, r.status == 0, !r.timedOut {
+          foreground = Tmux.foreground(ps: r.stdout, ttys: ttys)
+        }
+        let agents = self.settings.agents
+        completion(.success(sockets.flatMap { socket in
+          Tmux.targets(panes: bySocket[socket] ?? [], foreground: foreground, agents: agents, socket: socket)
+        }))
+      }
+    }
+  }
+
+  /// Checks the pane (same server, alive), leaves copy mode, pastes +text+
+  /// through a named buffer (`paste-buffer -p`: bracketed only when the
+  /// program asked for it; `-r`: newlines as given), then presses Enter
+  /// unless +pasteOnly+. One tmux call: claude and codex submitted reliably
+  /// with the Enter right after the paste's end marker, a large paste too.
+  func send(key: String, text: String, pasteOnly: Bool, completion: @escaping (Result<Void, AgentTerminalError>) -> Void) {
+    guard let (socket, serverPid, pane) = Tmux.parse(key: key) else {
+      queue.async { completion(.failure(.failed("not a tmux pane: \(key)"))) }; return
+    }
+    if let error = binaryError { queue.async { completion(.failure(error)) }; return }
+    // A missing pane: exit 0 and no output (not an error), so the id is
+    // checked too.
+    let probe = ["display-message", "-p", "-t", pane, "#{pid} #{pane_id} #{pane_dead} #{pane_in_mode} #{pane_mode}"]
+    tmux(socket, probe, timeout: listTimeout) { result in
+      guard case .success(let r) = result, !r.timedOut else {
+        completion(.failure(.from(result, "tmux display-message"))); return
+      }
+      let f = r.stdout.trimmingCharacters(in: .whitespacesAndNewlines).split(separator: " ").map(String.init)
+      guard r.status == 0, f.count >= 4, f[0] == serverPid, f[1] == pane, f[2] == "0" else {
+        completion(.failure(.closed("pane closed"))); return
+      }
+      let mode = f.count > 4 ? f[4] : ""
+      let paste = { self.paste(socket, pane: pane, text: text, pasteOnly: pasteOnly, completion: completion) }
+      guard f[3] == "1" else { paste(); return }
+      guard mode == "copy-mode" || mode == "view-mode" else {
+        completion(.failure(.failed("pane in \(mode.isEmpty ? "a mode" : mode)"))); return
+      }
+      // Copy mode would eat the Enter: left first (the scroll position goes).
+      self.tmux(socket, ["send-keys", "-t", pane, "-X", "cancel"], timeout: self.sendTimeout) { result in
+        guard case .success(let r) = result, r.status == 0, !r.timedOut else {
+          completion(.failure(.from(result, "tmux send-keys -X cancel"))); return
+        }
+        paste()
+      }
+    }
+  }
+
+  private func paste(_ socket: String, pane: String, text: String, pasteOnly: Bool,
+                     completion: @escaping (Result<Void, AgentTerminalError>) -> Void) {
+    let buffer = "chi-helper-\(UUID().uuidString)"
+    var args = ["load-buffer", "-b", buffer, "-", ";", "paste-buffer", "-p", "-r", "-d", "-b", buffer, "-t", pane]
+    if !pasteOnly { args += [";", "send-keys", "-t", pane, "Enter"] }
+    tmux(socket, args, stdin: Data(text.utf8), timeout: sendTimeout) { result in
+      guard case .success(let r) = result, r.status == 0, !r.timedOut else {
+        // A failed chain stops there and may leave the buffer behind.
+        self.tmux(socket, ["delete-buffer", "-b", buffer], timeout: self.sendTimeout) { _ in
+          completion(.failure(.from(result, "tmux paste")))
+        }
+        return
+      }
+      completion(.success(()))
+    }
+  }
+
+  /// `-u`: UTF-8 output even with launchd's bare env (no LANG).
+  private func tmux(_ socket: String, _ args: [String], stdin: Data? = nil, timeout: TimeInterval,
+                    on queue: DispatchQueue? = nil, completion: @escaping (Result<ChiResult, ChiError>) -> Void) {
+    ProcessRunner.run(executable: settings.binary, args: ["-u", "-S", socket] + args, env: tmuxEnv,
+                      stdin: stdin, timeout: timeout, queue: queue ?? self.queue, completion: completion)
+  }
+}