samagotchi 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f0638cac2109278f683d0b6caeca1bb633786721471c1f366f2cf3bc459b43f
-  data.tar.gz: 988b05ee21480227d4a1ed814457dd26af11ed71bf21b3d6c62f863e07f18e1a
+  metadata.gz: 9668c1088aa3739aa60890e07c7d04cf41fb87debf9683b6cd42b6e6e61ee265
+  data.tar.gz: ecfd58cc93c0dee8d867936c75754f854da34cf436dce28fcbc442e7f61c6ec2
 SHA512:
-  metadata.gz: b7905a2a451c696ca057def8388137bc6a03523bd43a8e9405d2086a99b979f4804fe51c3bb3fd7fc444ade5ea7909339a29c99a3373b9ad3b254d8702210906
-  data.tar.gz: ce71c8a3a069014d738088e50372c9f50553bd9da12613a756c5941498ba2f3024f9954d2bbe672b10b6c0b00cc5c80cd296858ec84a1425e4ef3713e84cf0fd
+  metadata.gz: cd2b82ad80038fb47d35a7b76177312521548a61764963697bebe2cb3b5389fd2d604debba118a87bca43077f2f350b7a0c5f63878df73c5ad75382951246ca0
+  data.tar.gz: ef64847c760b05f8b6ee084fcd39b0ffc2595de21538c388ee7dc8c37f59a952bf4f55b2cf8db8df8187cf4600dd890e996bb94473a9af4e3e99a8cef8ed48af

data/CHANGELOG.md

@@ -8,6 +8,33 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-02
+
+### Added
+
+- `chi models [--format json] [--timeout S] [TEXT]` lists the names `--model` takes from every host (default first,
+  then `host:id`, then aliases), waiting at most 4 s for the hosts; exit 1 when no host listed.
+- The desktop helper chooses the model for a new session: ⌘M (or a click on the new row's model) opens a searchable
+  chooser of every host's models and aliases; the pick and five recent ones are remembered. Run `chi desktop upgrade`.
+
+### Changed
+
+- `chi self --model` prints an alias default as the ref it resolves to (`box:gemma-small`, not `small`).
+
+### Fixed
+
+- A failed turn's messages and its `turn_failed` event reach a joining client together (a snapshot taken in between
+  could show one without the other).
+- A Ctrl-C while an `after_turn` or `session_end` hook runs no longer cancels the turn that already answered: the
+  answer stays in the session (it was replaced with a cancel note and a second end event).
+- A web Stop sent right as a turn starts (while chi asks the model server for its settings, a first turn's /props
+  probe) cancels the turn at once; it used to answer "not running" and the turn ran on. A failed probe there now ends
+  the turn as failed instead of leaving the session marked running.
+- Reminders keep firing on their own while a session is idle. A reminder that a prompt's turn delivered just as the
+  idle check found it due, or a reminder turn that failed before it started, could stop them until the next prompt.
+
+Update with `chi update` (no bundle changes); run `chi desktop upgrade` for the desktop helper's model chooser.
+
 ## [0.11.0] - 2026-10-01
 
 ### Added
@@ -642,7 +669,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/dm1try/samagotchi/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/dm1try/samagotchi/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/dm1try/samagotchi/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/dm1try/samagotchi/compare/v0.9.0...v0.10.0

data/bin/chi

@@ -23,13 +23,13 @@ if ARGV[0] == "self"
   if %w[-h --help help].include?(ARGV[1])
     puts "Usage: chi self [--model]"
     puts "  Print version, source dir, config/memory/session paths, model/host and bundles."
-    puts "  --model  print only the model a new session starts on (exit 1 when none is configured)"
+    puts "  --model  print only the model a new session starts on, an alias resolved (exit 1 when none is configured)"
     exit 0
   end
   require "samagotchi/self_report"
   # The desktop helper's hint for its "New session" row: offline and quick.
   if ARGV[1] == "--model"
-    model = Samagotchi::SelfReport.model_name
+    model = Samagotchi::SelfReport.model_ref_name
     puts model if model
     exit(model ? 0 : 1)
   end
@@ -49,6 +49,8 @@ SUBCOMMANDS = {
   "bootstrap" => ["samagotchi/bootstrap_command", "BootstrapCommand"],
   # bring an installed chi up to date
   "update" => ["samagotchi/update_command", "UpdateCommand"],
+  # the models --model takes, from every host (--format, --timeout)
+  "models" => ["samagotchi/models_command", "ModelsCommand"],
   # the native "Send to chi" helper
   "desktop" => ["samagotchi/desktop_command", "DesktopCommand"],
   # install, upgrade, uninstall, status, diff, list, build (--scope, --force, …)
@@ -94,6 +96,7 @@ parser = OptionParser.new do |opts|
            chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
            chi bundle <install|upgrade|uninstall|status|diff|list|build>
            chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
+           chi models [--format json] [TEXT]   the models --model takes, from every host
            chi self                         version, paths, model and bundles
            chi update [--dry-run]           update this chi, its bundles and the desktop helper
     (each subcommand takes --help)

data/docs/architecture.md

@@ -159,7 +159,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 engine = Samagotchi::Engine.new(mode: :assist, model_name: "gemma4", memories: [])
 session = Samagotchi::Session.new_session(mode: "assist", model_name: "gemma4", working_directory: Dir.pwd)
 
-engine.run_turn(session, "hello", on_event: nil)   # => KernelLoop::Result (`.output`)
+engine.run_turn(session, "hello", on_event: nil)   # => LLM::ModelResult (`.output`)
 ```
 
 #### The `on_event` seam
@@ -169,7 +169,7 @@ forwards the raw `KernelLoop` events unchanged (the low-level contract) and adds
 higher-level events so UIs get clean turn boundaries without inferring them:
 
 - `:turn_started` — `{ session_id:, prompt: }`
-- `:turn_completed` — `{ result: }` (the final `KernelLoop::Result`)
+- `:turn_completed` — `{ result: }` (the final `LLM::ModelResult`)
 - `:turn_canceled` — `{ cancellation_reason: }`
 
 Every event is a `Hash` with a `:type` symbol key; the sink must not raise (the Engine
@@ -330,8 +330,8 @@ conversation (the prompt plus completed tool iterations) and emits
 `:turn_failed` with `error_kind:`, `retryable:`, `host:` and a one-line
 `summary:`, which the REPL, the attached TUI and the web show.
 
-**Usage and models.** `ModelResult#usage` is an `LLM::Usage` (server counts, else
-a chars/4 estimate, else zeros; never nil). Model lists are `LLM::ModelInfo`
+**Usage and models.** A turn's token counts are `SessionMetrics`', read from the
+stream events (server counts, else a chars/4 estimate). Model lists are `LLM::ModelInfo`
 (`HostRegistry#list_all_models`); the context window comes from the running
 server (`/props`), then the host's model list, then config.
 

data/docs/cli.md

@@ -19,7 +19,8 @@
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text to live sessions as context notes (see [Desktop helper](desktop.md))
-- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles; `chi self --model` prints only the model a new session starts on (the desktop helper's hint)
+- `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
+- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles; `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for every other command
 
@@ -66,6 +67,29 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   A bundle that fails to install makes the exit 1. `--dry-run` says what it
   would install.
 
+### Listing the models
+
+`chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and
+`chi send --new --model`, `/model`) takes, one per line:
+
+```sh
+$ chi models
+gemma-4                          # the default (default.model), first
+splash:incoai/Qwen3.8-27B-Splash # another host's id: host:id
+openrouter:qwen/qwen3.8-27b
+small -> box:gemma-small         # an alias and the ref it resolves to
+$ chi models qwen                # only the names containing "qwen" (any case)
+```
+
+- A default-host id is bare, except one with a `:` (`qwen3:8b`), which is written `<host>:qwen3:8b` so it can't
+  read as a host name. An id that an alias of the same name hides is left out.
+- Each run lists anew (no cache); `--timeout S` caps the wait for the hosts (default 4 s). A host that fails or doesn't
+  answer in time is noted on stderr (`chi models: box: no answer in 4 s`).
+- `--format json` prints one object: `default` (and `default_typed` when it was set as an alias), `default_host`,
+  `models` (`name`, `host`, `id`), `aliases` (`name`, `ref`, `host`) and `warnings`. The desktop helper's model
+  chooser reads it.
+- Exit 0 when any host listed its models, 1 when none did (the default is still printed), 2 on a usage error.
+
 ### Updating
 
 `chi update` brings an installed chi up to date and prints one table:

data/docs/desktop.md

@@ -35,8 +35,30 @@ The first row, **New session in <folder>** (⌘0), starts a session with the mes
 that of the most recently updated live session, else of the newest recent one, else your home folder. It is ticked
 alone (ticking it clears the sessions and the reverse) and is preselected when no session is live. ⌘⏎ on it beeps: a
 note needs a session. After the send the panel shows `started <id>…` for 3 s. On its right, in grey, the row names
-the model the new session starts on (`chi self --model`: `default.model` from config.yml, or its env override); it
-is left out when none is configured.
+the model the new session starts on (`chi self --model`: `default.model` from config.yml, or its env override; an
+alias as the model it names).
+
+### Choosing the model
+
+Click the model on the new row, or press **⌘M**, to choose another one for the new session. The chooser takes the
+place of the session list: a search field (focused), then **Default (<model>)** (`Default (small → box:gemma-small)`
+for an alias), your recent picks and every host's
+models and aliases (from [`chi models`](cli.md#listing-the-models)), at most nine at a time.
+
+- Type to search: every word must match the host or the id; names starting with what you typed rank first. A name
+  no host lists is offered at the bottom as "not listed" and sent as typed (a host that is down, a model just added).
+- ↑/↓ and ⏎, a click, or ⌘1…⌘9 pick; Esc (or ⌘M) closes the chooser only, a second Esc the panel. While an input
+  method is composing, ⏎, the arrows and Esc are its own.
+- The row then shows the pick in the accent colour, and ⏎ sends `chi send --new --model <name>`, the name exactly as
+  the chooser shows it; Default sends no `--model`. An existing session keeps its model (switch it there with `/model`).
+- The pick is remembered for the next open (and the last five in the recent list), for every folder. A remembered
+  model no host lists any more falls back to the default, with a note in the panel.
+- The list is fetched again at each open; the previous one shows meanwhile ("Loading models…" the first time after
+  the helper starts). Hosts that failed or took over 4 s are named under the list; the default and the recent picks
+  still work.
+
+The chooser needs a chi with `chi models`: an older helper works with a newer chi, not the reverse
+(`chi desktop upgrade` after updating chi).
 
 A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
 

data/lib/samagotchi/bridge.rb

@@ -153,7 +153,7 @@ module Samagotchi
       @capture_handle = @engine.subscribe(observer: capture_observer)
       @accumulator_handle = @engine.subscribe(observer: @accumulator)
       # A plugin's ctx.messages mid-turn holds the turn so far (plan O1).
-      @engine.running_turn_messages = -> { @accumulator.current_messages } if @engine.respond_to?(:running_turn_messages=)
+      @engine.running_turn_messages = -> { @accumulator.current_messages }
       @cards_handle = @engine.subscribe(observer: @cards)
       # One a worker that died left is not open.
       @pending_card.clear
@@ -180,7 +180,7 @@ module Samagotchi
       end
       @capture_handle&.unsubscribe
       @accumulator_handle&.unsubscribe
-      @engine.running_turn_messages = nil if @engine.respond_to?(:running_turn_messages=)
+      @engine.running_turn_messages = nil
       @cards_handle&.unsubscribe
       @pending_card_handle&.unsubscribe
       @pending_card&.clear
@@ -217,7 +217,7 @@ module Samagotchi
           continue_offer: @accumulator.continue_offer,
           guardrail_warning: @engine.guardrail_warning,
           plugin_warning: @engine.plugin_warning,
-          init_tasks: @engine.respond_to?(:init_tasks) ? @engine.init_tasks : [],
+          init_tasks: @engine.init_tasks,
           cards: @cards.list,
           commands: command_registry.listing,
           event_seq: seq,
@@ -242,7 +242,7 @@ module Samagotchi
 
     # The Engine's commands: the built-ins and its plugins'.
     def command_registry
-      @engine.respond_to?(:command_registry) ? @engine.command_registry : SessionCommands.builtin_registry
+      @engine.command_registry
     end
 
     # The single shared capture observer: appends every event to the ring.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.11.0
+version: 0.12.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

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

@@ -3,7 +3,8 @@
 // the clipboard (a screenshot too). No Dock icon (LSUIElement); it stays
 // running after the first launch. `ChiHelper --login on|off|status` (run
 // directly by chi desktop) manages the login item and exits;
-// `ChiHelper --kitty list|send` is the kitty targets' seam (Kitty.swift).
+// `ChiHelper --kitty list|send` is the kitty targets' seam (Kitty.swift),
+// `ChiHelper --model-pick` the model chooser's (Models.swift).
 import AppKit
 import ServiceManagement
 
@@ -101,6 +102,9 @@ struct ChiHelperMain {
     if args.count >= 2, args[1] == "--kitty" {
       exit(kittyCommand(Array(args.dropFirst(2))))
     }
+    if args.count >= 2, args[1] == "--model-pick" {
+      exit(modelPickCommand(Array(args.dropFirst(2))))
+    }
     let app = NSApplication.shared
     let delegate = AppDelegate()
     app.delegate = delegate

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

@@ -147,6 +147,25 @@ final class ChiRunner {
     }
   }
 
+  /// `chi models --format json`: every host's models and the aliases. Exit
+  /// 1 (no host listed) still prints the default and the warnings. 10 s:
+  /// the boot and chi's own 4 s cap on the hosts, with a margin.
+  func models(completion: @escaping (Result<ModelList, ChiError>) -> Void) {
+    run(["models", "--format", "json"], timeout: 10) { result in
+      switch result {
+      case .failure(let error): completion(.failure(error))
+      case .success(let r):
+        if r.timedOut { completion(.failure(.failed("chi models took over 10 s"))); return }
+        guard r.status == 0 || r.status == 1, let list = ModelList.decode(Data(r.stdout.utf8)) else {
+          let detail = r.stderr.isEmpty ? r.stdout : r.stderr
+          completion(.failure(.failed("chi models failed (exit \(r.status)): \(detail.prefix(300))")))
+          return
+        }
+        completion(.success(list))
+      }
+    }
+  }
+
   private func list(_ flags: [String], completion: @escaping (Result<[LiveSession], ChiError>) -> Void) {
     // Every project's sessions: the helper isn't in any one project (an
     // older chi ignores the flag).

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

@@ -0,0 +1,238 @@
+// The new session's model: `chi models --format json` (every host's
+// listing and the aliases, the names `--model` takes) and the chooser's pure
+// rules: its rows, search ranking, the remembered pick and the recent picks.
+// The helper never builds or rewrites a name: what a row says is what
+// `chi send --new --model` gets. `ChiHelper --model-pick` is the build
+// spec's seam (stdin: the payload).
+import Foundation
+
+/// `chi models --format json`; printed on exit 1 too (no host listed: the
+/// default alone).
+struct ModelList: Decodable, Equatable {
+  struct Model: Decodable, Equatable {
+    let name: String
+    let host: String
+    let id: String
+    /// An alias of the same name takes it elsewhere: not offered.
+    let shadowedBy: String?
+  }
+
+  struct Alias: Decodable, Equatable {
+    let name: String
+    let ref: String
+    let host: String?
+  }
+
+  let `default`: String?
+  let defaultTyped: String?
+  let defaultHost: String?
+  let models: [Model]
+  let aliases: [Alias]?
+  let warnings: [String]?
+
+  static func decode(_ data: Data) -> ModelList? {
+    let decoder = JSONDecoder()
+    decoder.keyDecodingStrategy = .convertFromSnakeCase
+    return try? decoder.decode(ModelList.self, from: data)
+  }
+
+  /// "default (small → box:gemma)" style: the default as the row shows it.
+  var defaultLabel: String? {
+    guard let name = `default` else { return nil }
+    if let typed = defaultTyped, !typed.isEmpty { return "\(typed) → \(name)" }
+    return name
+  }
+}
+
+/// One line of the chooser. +name+ is what `--model` gets (the default row's
+/// is the default's name, for show: picking it sends no `--model`).
+struct ModelRow: Equatable {
+  enum Kind: String { case standard = "default", listed, alias, typed }
+
+  let kind: Kind
+  let name: String
+  /// The host that listed it ("" when unknown: a recent pick before the list).
+  let host: String
+  /// What the search looks at besides the host: the id, an alias's name
+  /// and target, a typed name.
+  let id: String
+  let label: String
+}
+
+enum ModelPick {
+  static let pickKey = "newSessionModel"
+  static let recentKey = "recentModels"
+  static let maxRecent = 5
+  /// ⌘1…⌘9.
+  static let maxRows = 9
+
+  static func same(_ a: String, _ b: String) -> Bool { a.caseInsensitiveCompare(b) == .orderedSame }
+
+  /// Every name the list offers, default host first, an alias after its
+  /// host's ids; the default itself left out (it is the Default row).
+  static func rows(_ list: ModelList) -> [ModelRow] {
+    let defaultHost = list.defaultHost ?? ""
+    let listed = list.models.filter { $0.shadowedBy == nil }
+    var hosts: [String] = []
+    for host in listed.map(\.host) + (list.aliases ?? []).compactMap(\.host) where !hosts.contains(host) {
+      hosts.append(host)
+    }
+    hosts = hosts.filter { $0 == defaultHost } + hosts.filter { $0 != defaultHost }
+    var rows: [ModelRow] = []
+    for host in hosts {
+      for model in listed where model.host == host {
+        rows.append(ModelRow(kind: .listed, name: model.name, host: host, id: model.id,
+                             label: host == defaultHost ? model.id : "\(host) · \(model.id)"))
+      }
+      for alias in list.aliases ?? [] where alias.host == host {
+        rows.append(ModelRow(kind: .alias, name: alias.name, host: host, id: "\(alias.name) \(alias.ref)",
+                             label: "\(alias.name) → \(alias.ref)"))
+      }
+    }
+    for alias in list.aliases ?? [] where alias.host == nil {
+      rows.append(ModelRow(kind: .alias, name: alias.name, host: "", id: "\(alias.name) \(alias.ref)",
+                           label: "\(alias.name) → \(alias.ref)"))
+    }
+    guard let standard = list.default else { return rows }
+    return rows.filter { !same($0.name, standard) }
+  }
+
+  /// The chooser's rows, at most maxRows: Default first; with no query
+  /// the recent picks still offered (as they are while the list loads),
+  /// then the list; with one, the ranked matches and, when no row is named
+  /// exactly that, the typed name ("not listed").
+  static func chooserRows(list: ModelList?, fallbackDefault: String?, recents: [String], query: String) -> [ModelRow] {
+    let standardName = list?.default ?? fallbackDefault ?? ""
+    let standard = ModelRow(kind: .standard, name: standardName, host: list?.defaultHost ?? "", id: standardName,
+                            label: standardName.isEmpty ? "Default" : "Default (\(list?.defaultLabel ?? standardName))")
+    let all = list.map(rows) ?? []
+    let text = query.trimmingCharacters(in: .whitespacesAndNewlines)
+    var out: [ModelRow] = [standard]
+    if text.isEmpty {
+      for name in recents where !(list != nil && same(name, standardName)) {
+        if let row = all.first(where: { same($0.name, name) }) {
+          out.append(row)
+        } else if list == nil {
+          out.append(ModelRow(kind: .listed, name: name, host: "", id: name, label: name))
+        }
+      }
+      for row in all where !out.contains(where: { same($0.name, row.name) }) { out.append(row) }
+      return Array(out.prefix(maxRows))
+    }
+    let exact = all.contains { same($0.name, text) } || same(text, standardName)
+    let room = maxRows - 1 - (exact ? 0 : 1)
+    out += match(all, query: text).prefix(room)
+    if !exact {
+      out.append(ModelRow(kind: .typed, name: text, host: "", id: text, label: "\(text) — not listed"))
+    }
+    return out
+  }
+
+  /// Rows matching every word of +query+ on the host or the id, ranked
+  /// like the web's picker: substring-only rows first (at a segment start
+  /// cheaper), then subsequences of 3+ characters by their gaps, then the
+  /// shorter id, then list order.
+  static func match(_ rows: [ModelRow], query: String) -> [ModelRow] {
+    let words = query.lowercased().split(whereSeparator: \.isWhitespace).map(String.init)
+    guard !words.isEmpty else { return [] }
+    var found: [(row: ModelRow, index: Int, sub: Bool, cost: Int)] = []
+    for (index, row) in rows.enumerated() {
+      let host = Array(row.host.lowercased()), id = Array(row.id.lowercased())
+      var sub = true, cost = 0, ok = true
+      for word in words {
+        let w = Array(word)
+        let onId = matchWord(w, id), onHost = matchWord(w, host)
+        guard let pick = better(onHost, than: onId) ? onHost : onId else { ok = false; break }
+        sub = sub && pick.sub
+        cost += pick.cost
+      }
+      if ok { found.append((row, index, sub, cost)) }
+    }
+    found.sort { a, b in
+      if a.sub != b.sub { return a.sub }
+      if a.cost != b.cost { return a.cost < b.cost }
+      if a.row.id.count != b.row.id.count { return a.row.id.count < b.row.id.count }
+      return a.index < b.index
+    }
+    return found.map(\.row)
+  }
+
+  private static let separators = Set("/-:._ ")
+
+  private static func matchWord(_ word: [Character], _ text: [Character]) -> (sub: Bool, cost: Int)? {
+    guard !word.isEmpty, word.count <= text.count else { return nil }
+    var best: (sub: Bool, cost: Int)?
+    for i in 0...(text.count - word.count) where Array(text[i..<(i + word.count)]) == word {
+      let cost = i == 0 || separators.contains(text[i - 1]) ? 0 : 2
+      if best == nil || cost < best!.cost { best = (true, cost) }
+      if cost == 0 { break }
+    }
+    if best != nil || word.count < 3 { return best }
+    guard var at = text.firstIndex(of: word[0]) else { return nil }
+    var gaps = 0
+    for k in 1..<word.count {
+      guard let i = text[(at + 1)...].firstIndex(of: word[k]) else { return nil }
+      gaps += i - at - 1
+      at = i
+    }
+    return (false, 10 + gaps)
+  }
+
+  private static func better(_ a: (sub: Bool, cost: Int)?, than b: (sub: Bool, cost: Int)?) -> Bool {
+    guard let a else { return false }
+    guard let b else { return true }
+    return (a.sub && !b.sub) || (a.sub == b.sub && a.cost < b.cost)
+  }
+
+  /// The remembered pick for this open: kept while the list loads, and
+  /// once it is in, only when offered (as the list spells it) or when no
+  /// host listed anything (no way to tell); else the default, with a note.
+  static func keep(_ stored: String?, in list: ModelList?) -> (pick: String?, note: String?) {
+    guard let stored = stored?.trimmingCharacters(in: .whitespacesAndNewlines), !stored.isEmpty else { return (nil, nil) }
+    guard let list else { return (stored, nil) }
+    if let standard = list.default, same(standard, stored) { return (nil, nil) }
+    if let row = rows(list).first(where: { same($0.name, stored) }) { return (row.name, nil) }
+    if list.models.isEmpty { return (stored, nil) }
+    return (nil, "\(stored) isn't listed any more; using the default")
+  }
+
+  /// The recent picks after +name+: it first, no other copy (any case).
+  static func pushRecent(_ list: [String], _ name: String) -> [String] {
+    Array(([name] + list.filter { !same($0, name) }).prefix(maxRecent))
+  }
+}
+
+/// `ChiHelper --model-pick [--query Q] [--recent NAME]... [--stored NAME]
+/// [--push NAME]`: the payload on stdin, the chooser as JSON on stdout
+/// (rows, the kept pick and its note, the recents after --push). Exit 1
+/// when stdin isn't a payload.
+func modelPickCommand(_ args: [String]) -> Int32 {
+  var args = args
+  var query = "", recents: [String] = [], stored: String?, push: String?
+  while !args.isEmpty {
+    let arg = args.removeFirst()
+    switch arg {
+    case "--query" where !args.isEmpty: query = args.removeFirst()
+    case "--recent" where !args.isEmpty: recents.append(args.removeFirst())
+    case "--stored" where !args.isEmpty: stored = args.removeFirst()
+    case "--push" where !args.isEmpty: push = args.removeFirst()
+    default:
+      FileHandle.standardError.write("usage: ChiHelper --model-pick [--query Q] [--recent NAME]... [--stored NAME] [--push NAME]\n".data(using: .utf8)!)
+      return 2
+    }
+  }
+  guard let list = ModelList.decode(FileHandle.standardInput.readDataToEndOfFile()) else {
+    FileHandle.standardError.write("not a chi models payload\n".data(using: .utf8)!)
+    return 1
+  }
+  let rows = ModelPick.chooserRows(list: list, fallbackDefault: nil, recents: recents, query: query)
+  let kept = ModelPick.keep(stored, in: list)
+  var out: [String: Any] = [
+    "rows": rows.map { ["kind": $0.kind.rawValue, "name": $0.name, "label": $0.label] },
+    "pick": kept.pick ?? NSNull(), "note": kept.note ?? NSNull(), "warnings": list.warnings ?? [],
+  ]
+  if let push { out["recent"] = ModelPick.pushRecent(recents, push) }
+  let data = try! JSONSerialization.data(withJSONObject: out, options: [.sortedKeys])
+  print(String(decoding: data, as: UTF8.self))
+  return 0
+}