samagotchi 0.10.1 → 0.12.0

data/lib/samagotchi/bundles/known-names/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: known-names
-version: 0.1.3
+version: 0.1.4
 scope: system
 description: Catches a near-miss of a protected name (home folder, login, git name, repo name, names from config) in a tool call and rejects it with the right spelling; mode ask / correct optional
 trust_level: reviewed
@@ -8,7 +8,7 @@ files:
   known_names.md: sha256:d5348b95b6c655017b541910b36e384220da280818160201f6ec9a50e1e4287c
 hooks:
   known_names.rb:
-    sha256: sha256:443777b7d6208ff7b2b668a4510db853826a507bd44ea23ea2428fa4b2df5686
+    sha256: sha256:c0845c9b6d04ec884c4641441d8a0ba3482283f4ee3e00c8b3bf99efb0c635b1
     event: before_tool_call
     on_error: log
     priority: 50

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

@@ -1,10 +1,10 @@
 ---
 name: skills
-version: 0.1.4
+version: 0.1.5
 scope: system
 description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:cc5b3bcfd571e17074776f48c8d28184475f2a4becd06d70edbacd7381e1f306
-requires_chi: ">= 0.9.0"
+  sha256: sha256:9bd637f8fa933b03434e4ccdcbf2547aa011993b8044f2739ee7d50f995d2882
+requires_chi: ">= 0.11.0"

data/lib/samagotchi/bundles/skills/plugin.rb

@@ -173,10 +173,10 @@ class Plugin
     nil
   end
 
+  # A failed step is a call whose status (core's, from the full output) is
+  # error: a denied call is blocked, a stopped task_wait stopped.
   def step_failed(event, ctx)
-    tool = event[:tool].to_s
-    output = event[:output].to_s
-    return if NOT_FAILURES.include?(tool) || guardrail_deny?(tool, output) || !failure?(tool, output)
+    return if NOT_FAILURES.include?(event[:tool].to_s) || event[:status] != "error"
 
     @failed = true
     return if @nudged || @read.any? { |name| @written.include?(name) }
@@ -184,26 +184,6 @@ class Plugin
     @nudged = ctx.steer(format(NUDGE, @read.join(", ")))
   end
 
-  # A denied call, by its first line: a legacy veto, a rule's, hook's or
-  # core's deny, or the user's (declined, approval cancelled). Core's
-  # wording (ToolRunner#denied, Verdict#deny_text).
-  def guardrail_deny?(tool, output)
-    output.match?(/\A\[#{Regexp.escape(tool)}\] Error: (?:blocked by guardrail: |denied by guardrail \(|[^\n]*? It needed approval \()/)
-  end
-
-  # A tool error ("[x] Error: …" raised, "[x]\nError: …" returned), or an
-  # execute that exited non-zero; its "exit: N" line may be cut off by the
-  # hook's output cap, and then an Error: line near the top counts.
-  def failure?(tool, output)
-    return true if output.match?(/\A\[#{Regexp.escape(tool)}\](?: |\n)Error:/)
-    return false unless tool == "execute"
-
-    exit_line = output.match(/^exit: (\d+)(?: \(no output\))?\s*\z/)
-    return exit_line[1] != "0" if exit_line
-
-    output.lines.first(20).any? { |line| line.match?(/\A\s*Error:/i) }
-  end
-
   def after_turn(ctx)
     changed_elsewhere(ctx)
     return unless @nudge && @failed

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -56,7 +56,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
-- `model_aliases:` map of alias → model id (`ConfigFile.resolve_model_alias`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid).
+- `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
 - `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
 - `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: `--thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.10.1
+version: 0.12.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:93c788fadaf98adeb8946b4a357d2372bd6ebb439042d7cef8dda8fb44187315
-  config_modification_protocol.md: sha256:d8bdf062d5afce7430ead7f49439c1d1ed197a6261dc69a7c884f4b814266b12
+  config_modification_protocol.md: sha256:dddd083d6f419674e6e0cc39118ca9785583a557e4950af1a9b028e52e8a3e0c
   memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/client.rb

@@ -90,6 +90,21 @@ module Samagotchi
         openai_compatible? ? payload.dig("choices", 0, "text").to_s : payload.fetch("content", "")
       end
 
+      # Why the stream stopped, from its last payload, as an OpenAI finish
+      # reason ("length" for the token cap or a full context, "stop"
+      # otherwise); nil for a payload that doesn't say. llama.cpp's
+      # /completion names it stop_type ("limit", "eos", "word"); the
+      # OpenAI-compatible servers send their own finish_reason.
+      def finish_reason_from(payload)
+        return nil unless payload.is_a?(Hash)
+        return payload.dig("choices", 0, "finish_reason") if openai_compatible?
+
+        case payload["stop_type"]
+        when "limit" then "length"
+        when "eos", "word" then "stop"
+        end
+      end
+
       # The request's `model` field for this transport (nil = omit the field):
       #   - llama.cpp: forward the selector (SAMAGOTCHI_DEFAULT_MODEL) verbatim.
       #   - mlx_lm.server: omit `model` entirely (use whatever was loaded via the
@@ -248,7 +263,12 @@ module Samagotchi
         content, payload = parsed_chunk
         shown.call unless content.to_s.empty?
         result << content
-        on_chunk&.call(content: content, payload: payload)
+        next unless on_chunk
+
+        chunk = { content: content, payload: payload }
+        finish_reason = @transport.finish_reason_from(payload)
+        chunk[:finish_reason] = finish_reason if finish_reason
+        on_chunk.call(**chunk)
       end
       result
     rescue LLM::BadRequest => e

data/lib/samagotchi/config.rb

@@ -8,6 +8,7 @@ require "set"
 require_relative "atomic_file"
 require_relative "config_text_edit"
 require_relative "log"
+require_relative "model_ref"
 require_relative "paths"
 
 module Samagotchi
@@ -436,7 +437,44 @@ module Samagotchi
           else
             [key_problem(key)].compact
           end
+        end + model_ref_problems(data)
+      end
+
+      # What a model ref in config.yml won't do as written: an alias whose
+      # target is another alias (aliases apply once, ModelRef), a ref that
+      # starts with "<host>/" (only ':' names a host).
+      def model_ref_problems(data)
+        hosts = data["hosts"].is_a?(Hash) ? data["hosts"] : {}
+        aliases = data["model_aliases"].is_a?(Hash) ? data["model_aliases"] : {}
+        default = data["default"]["model"] if data["default"].is_a?(Hash)
+        refs = [["default.model", default], *aliases.map { |name, target| ["model_aliases.#{name}", target] }]
+        slash = refs.filter_map { |where, ref| host_slash_problem(where, ref, hosts) }
+        names = aliases.keys.map { |k| k.to_s.strip.downcase }
+        chains = aliases.filter_map do |name, target|
+          _, inner = ModelRef.split(target, hosts: hosts)
+          next unless names.include?(inner.downcase)
+
+          "config: model_aliases.#{name} points to the alias '#{inner}'; aliases don't chain, so '#{inner}' is sent as written"
         end
+        slash + chains + hosts.keys.filter_map { |name| family_host_problem(name.to_s) }
+      end
+
+      # Model families whose ids carry a ':' tag on Ollama and friends
+      # (qwen3:8b, llama3.1:70b): a host named like one takes those refs.
+      MODEL_FAMILY_HOST_RE = /\A(?:qwen|llama|codellama|gemma|mistral|mixtral|deepseek|phi|granite|starcoder|smollm|olmo)[\d.]*\z/i
+
+      def family_host_problem(name)
+        return nil unless name.match?(MODEL_FAMILY_HOST_RE)
+
+        "config: hosts.#{name} is named like a model family: a ref such as '#{name}:8b' (an Ollama tag) " \
+          "goes to host #{name} as '8b'; rename the host if you use such ids"
+      end
+
+      def host_slash_problem(where, ref, hosts)
+        prefix, rest = ref.to_s.strip.split("/", 2)
+        return nil if rest.to_s.empty? || !hosts.keys.map { |k| k.to_s.downcase }.include?(prefix.downcase)
+
+        "config: #{where} '#{ref}' starts with the host '#{prefix}' and '/': only ':' names a host now (#{prefix}:#{rest})"
       end
 
       # Dotted keys config.yml may set: config-exposed entries (snake and kebab
@@ -831,28 +869,9 @@ module Samagotchi
     end
 
     # Parse a model string that may be qualified as "host_alias:model"
-    # Returns [host_alias_or_nil, bare_model]
+    # Returns [host_alias_or_nil, bare_model] (ModelRef.split)
     def parse_host_qualified_model(raw, hosts: nil)
-      value = raw.to_s.strip
-      return [nil, value] if value.empty?
-      # Try split on first ':' or '/' where prefix matches a known host
-      hosts_map = hosts || {}
-      # Normalize keys downcase
-      lowered_keys = hosts_map.keys.map(&:downcase)
-      # Check ':' split
-      if value.include?(":")
-        prefix, rest = value.split(":", 2)
-        if lowered_keys.include?(prefix.strip.downcase) && !rest.strip.empty?
-          return [prefix.strip.downcase, rest.strip]
-        end
-      end
-      if value.include?("/")
-        prefix, rest = value.split("/", 2)
-        if lowered_keys.include?(prefix.strip.downcase) && !rest.strip.empty?
-          return [prefix.strip.downcase, rest.strip]
-        end
-      end
-      [nil, value]
+      ModelRef.split(raw, hosts: hosts)
     end
 
     # Hosted providers' names, which no local model family uses: as a
@@ -989,25 +1008,10 @@ module Samagotchi
       nil
     end
 
-    def resolve_model_alias(raw, env: ENV, path: global_path(env: env), hosts: nil)
-      value = raw.to_s.strip
-      return value if value.empty?
-
-      aliases = model_aliases(env: env, path: path)
-      # Host-qualified handling: "host:alias" -> "host:resolved"
-      # This allows /model small-box:small where "small" is an alias.
-      if value.include?(":") || value.include?("/")
-        hosts_map = hosts || hosts_config(env: env, path: path)
-        host, bare = parse_host_qualified_model(value, hosts: hosts_map)
-        if host && !bare.to_s.strip.empty?
-          resolved_bare = aliases.fetch(bare.downcase, bare)
-          # Preserve the separator the user used (: or /)
-          sep = value.downcase.include?("#{host}:") ? ":" : (value.downcase.include?("#{host}/") ? "/" : ":")
-          return "#{host}#{sep}#{resolved_bare}"
-        end
-      end
-
-      aliases.fetch(value.downcase, value)
+    # +raw+ parsed against config.yml's hosts (or +hosts+) and aliases.
+    # @return [ModelRef]
+    def model_ref(raw, env: ENV, path: global_path(env: env), hosts: nil)
+      ModelRef.parse(raw, hosts: hosts || hosts_config(env: env, path: path), aliases: model_aliases(env: env, path: path))
     end
 
     # Words /model takes as arguments (clear/default/none/off reset the

data/lib/samagotchi/context_status.rb

@@ -5,7 +5,7 @@ require_relative "context_usage"
 require_relative "context_window"
 
 module Samagotchi
-  # One turn's context tracking for KernelLoop#run: how full the window is
+  # One turn's context tracking for either loop: how full the window is
   # before each request (the server's last prompt count plus an estimate for
   # what the turn appended since, else a chars-per-token estimate), the
   # bucket that puts it in, and what comes of that:
@@ -95,18 +95,18 @@ module Samagotchi
 
     def enabled? = @enabled
 
-    # Before a request: estimate +prompt+'s usage against +window+ (this
-    # request's ContextWindow::Resolved) and update the status line's
-    # value. A rise into a bucket that asks the model for a change leaves
-    # a line for #take_guidance.
-    # +image_tokens+: the images' estimate (their base64 is not in +prompt+).
+    # Before a request: estimate the usage of a prompt of +prompt_chars+
+    # against +window+ (this request's ContextWindow::Resolved) and update
+    # the status line's value. A rise into a bucket that asks the model for
+    # a change leaves a line for #take_guidance.
+    # +image_tokens+: the images' estimate (their base64 is not in the chars).
     #
     # @return [Hash, nil] the :context_status event's fields (without
     #   :type/:iteration) when the emit gate fires, else nil
-    def observe(prompt, iteration_index:, window:, image_tokens: 0)
+    def observe(prompt_chars, iteration_index:, window:, image_tokens: 0)
       return nil unless @enabled
 
-      usage = estimate(prompt, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
+      usage = estimate(prompt_chars, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
       bucket = bucket_for(usage[:estimated_pct])
       # The status line's value, every iteration; the gate below decides
       # only the event and the model's guidance line.
@@ -135,7 +135,8 @@ module Samagotchi
       normalized
     end
 
-    # After a generation: +usage+ is its own server counts (nil: none), for
+    # After a generation: +usage+ is its own server counts ({prompt_tokens:,
+    # total_tokens:, context_window_tokens:}; nil: none), for
     # +prompt_chars+/+image_tokens+ as sent. The next estimate adds only
     # what the turn appended since (answer, tool results), and the status
     # line's value counts the answer. Without counts the pre-generation
@@ -161,21 +162,21 @@ module Samagotchi
     # `window` is this request's ContextWindow::Resolved. A window the
     # stream payload reports itself still wins.
     # +counted+: the prompt the server's prompt_tokens counted ({chars:,
-    # image_tokens:}); what +prompt+ has on top of it (the answer, tool
+    # image_tokens:}); what the prompt has on top of it (the answer, tool
     # results since) is added as an estimate, so the value doesn't read low
     # during a long tool loop. A prompt shorter than that one (trimmed) or
     # none known: the server's count alone.
-    def estimate(prompt, window:, server_usage: nil, image_tokens: 0, counted: nil)
+    def estimate(prompt_chars, window:, server_usage: nil, image_tokens: 0, counted: nil)
       window_source = window.source
       window_source = :server if server_usage && server_usage[:context_window_tokens]
 
       if server_usage && server_usage[:prompt_tokens]
         window_tokens = server_usage[:context_window_tokens] || window.tokens
-        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt, image_tokens, counted)
+        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt_chars, image_tokens, counted)
         source = "server"
       else
         window_tokens = window.tokens
-        used_tokens = (prompt.length / @chars_per_token).ceil + image_tokens
+        used_tokens = (prompt_chars / @chars_per_token).ceil + image_tokens
         source = "estimate"
       end
 
@@ -191,11 +192,11 @@ module Samagotchi
 
     private
 
-    # The estimate for what +prompt+ added since the +counted+ one.
-    def appended_tokens(prompt, image_tokens, counted)
+    # The estimate for what the prompt added since the +counted+ one.
+    def appended_tokens(prompt_chars, image_tokens, counted)
       return 0 unless counted
 
-      chars = prompt.length - counted[:chars]
+      chars = prompt_chars - counted[:chars]
       return 0 unless chars.positive?
 
       (chars / @chars_per_token).ceil + [image_tokens - counted[:image_tokens].to_i, 0].max

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
+}