samagotchi 0.9.0 → 0.10.1

data/lib/samagotchi/bundles/loop-guard/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: loop-guard
-version: 0.2.0
+version: 0.2.2
 scope: system
 description: "Breaks loops: the same tool call with the same result again and again in one turn is denied with advice (after a few denies the turn stops with a card), and thinking that repeats itself while it streams is cut and the model asked again"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:5a0dc653a654e73d881767c8b7b9486d4ac02cfc7823a150132593ffa2cbba04
+  sha256: sha256:e62c68d1a2280adf55b150488d0d85bbbc35ffce54dfed387a86adceb85e4d34
 requires_chi: ">= 0.6.0"

data/lib/samagotchi/bundles/loop-guard/plugin.rb

@@ -187,13 +187,13 @@ end
 class Plugin
   DEFAULT_IGNORE = %w[task_wait task_get delegate_result list_sessions list_reminders].freeze
   # Built-in tools carry flat fields; plugin and unknown tools carry args:.
-  KEY_FIELDS = %i[content path start_line end_line cwd env scope].freeze
+  # An edit's text is its old_text/new_text.
+  KEY_FIELDS = %i[content path start_line end_line cwd env scope old_text new_text].freeze
   SHORT_CHARS = 60
   THOUGHT_CHARS = 80
   SOURCE = "bundle loop-guard"
 
   def initialize(settings = {})
-    settings = {} unless settings.is_a?(Hash)
     @deny_after = positive(settings["deny_after"]) || 2
     @stop_after = positive(settings["stop_after"]) || 4
     @ignore = settings.key?("ignore_tools") ? Array(settings["ignore_tools"]).map(&:to_s) : DEFAULT_IGNORE
@@ -234,16 +234,16 @@ class Plugin
       ctx.notify("thinking repeats itself (#{what})", level: :warn)
     when "retry"
       @thinking_loops += 1
-      return stop_thinking(event, ctx, found, what) if @thinking_loops > 1
+      return stop_thinking(ctx, found, what) if @thinking_loops > 1
 
-      ctx.notify("thinking repeats itself (#{what}): cut", level: :warn) if event[:stop_generation]&.call("its thinking kept repeating itself")
+      ctx.notify("thinking repeats itself (#{what}): cut", level: :warn) if ctx.stop_generation("its thinking kept repeating itself")
     else
-      stop_thinking(event, ctx, found, what)
+      stop_thinking(ctx, found, what)
     end
   end
 
-  def stop_thinking(event, ctx, found, what)
-    return unless event[:stop_turn]&.call("the model's thinking kept repeating itself (#{what})")
+  def stop_thinking(ctx, found, what)
+    return unless ctx.stop_turn("the model's thinking kept repeating itself (#{what})")
 
     lines = found.sentences.first(3).map { |sentence| "- \"#{cut(sentence, THOUGHT_CHARS)}\"" }
     ctx.card(title: "loop-guard stopped the turn",
@@ -288,7 +288,7 @@ class Plugin
     verdict.deny!("repeated call", source: SOURCE, advice: advice(key, times))
     warn(ctx, key, "repeated, denied")
     @denials += 1
-    stop(event, ctx) if @denials == @stop_after
+    stop(ctx) if @denials == @stop_after
   end
 
   # A call's result, paired with the before_tool_call that keyed it. A call
@@ -308,8 +308,8 @@ class Plugin
     @previews[key] = preview(output)
   end
 
-  def stop(event, ctx)
-    event[:stop_turn]&.call("the model kept repeating the same calls")
+  def stop(ctx)
+    ctx.stop_turn("the model kept repeating the same calls")
     repeated = @attempts.select { |key, n| n > 1 && @last_result[key] && @results[[key, @last_result[key]]] >= @deny_after }
     lines = repeated.map do |key, n|
       "- `#{short_key(key)}`: #{n} times, the same result each time (#{@previews[key]})"

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

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.3.1
+version: 0.3.2
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:f7bfcaae51863c0dc2b057b0d30f79b7bed7935891e817fa7373f787e5c4ca5e
-requires_chi: ">= 0.1.37"
+  sha256: sha256:61b195a5621ddf57ba69a505aff06d620d6459e836d736205343a251b0fecb71
+requires_chi: ">= 0.8.0"

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

@@ -421,10 +421,8 @@ class Plugin
 
   # Written aside and renamed: workers share the dir.
   def save_cache(server, ctx)
-    path = cache_path(server, ctx)
-    tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-    File.write(tmp, JSON.generate({ digest: server.digest, saved_at: Time.now.utc.iso8601, tools: server.listed }))
-    File.rename(tmp, path)
+    Samagotchi::AtomicFile.write(cache_path(server, ctx),
+                                 JSON.generate({ digest: server.digest, saved_at: Time.now.utc.iso8601, tools: server.listed }))
   rescue SystemCallError => e
     ctx.log.warn("mcp_cache_not_written", server: server.name, msg: e.message)
   end

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

@@ -1,10 +1,10 @@
 ---
 name: skills
-version: 0.1.1
+version: 0.1.4
 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:ecf76de5d0f4d07a0e87b96cdc13b0bbc22369f8eea843bfd22c6fade469dfca
+  sha256: sha256:cc5b3bcfd571e17074776f48c8d28184475f2a4becd06d70edbacd7381e1f306
 requires_chi: ">= 0.9.0"

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

@@ -25,8 +25,11 @@
 # execute with "exit: N", N ≠ 0, or with no exit line an Error: line near
 # the top; any tool's "[tool] Error: …") steers the model once to find out
 # why and fix the skill, unless a skill read was changed already (by any
-# tool, see above). At the turn's end, a failed step with no change to a
-# skill read gets a notice line.
+# tool, see above). A call a guardrail or the user denied (its first line
+# "[tool] Error: blocked by guardrail: …", "… denied by guardrail (…): …" or
+# "… <the user's answer> It needed approval (…): …") isn't a failed step:
+# it says nothing about the skill. At the turn's end, a failed step with no
+# change to a skill read gets a notice line.
 #
 # Settings (config.yml, bundles: skills:):
 #   history_keep: 20   older versions kept per skill
@@ -43,7 +46,6 @@ class Plugin
   USAGE = "usage: /skill save [name] [--system] | list | show <name> | diff <name> [N]"
 
   def initialize(settings = {})
-    settings = {} unless settings.is_a?(Hash)
     @history_keep = positive(settings["history_keep"]) || 20
     @nudge = settings.key?("nudge") ? settings["nudge"] != false : true
     @stash = nil
@@ -87,7 +89,7 @@ class Plugin
     @stash = nil
     stash = nil unless stash && stash[:tool] == event[:tool].to_s
     changed_elsewhere(ctx) unless stash
-    step_failed(event) if @nudge && !@read.empty?
+    step_failed(event, ctx) if @nudge && !@read.empty?
     return unless stash
 
     now = File.file?(stash[:path]) ? File.read(stash[:path]) : nil
@@ -171,14 +173,22 @@ class Plugin
     nil
   end
 
-  def step_failed(event)
+  def step_failed(event, ctx)
     tool = event[:tool].to_s
-    return if NOT_FAILURES.include?(tool) || !failure?(tool, event[:output].to_s)
+    output = event[:output].to_s
+    return if NOT_FAILURES.include?(tool) || guardrail_deny?(tool, output) || !failure?(tool, output)
 
     @failed = true
     return if @nudged || @read.any? { |name| @written.include?(name) }
 
-    @nudged = !!event[:steer]&.call(format(NUDGE, @read.join(", ")))
+    @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
@@ -216,8 +226,7 @@ class Plugin
 
     stamp = Time.now.utc.strftime("%Y%m%dT%H%M%S.%6NZ")
     path = File.join(dir, "#{stamp}.md")
-    File.write("#{path}.tmp", content)
-    File.rename("#{path}.tmp", path)
+    Samagotchi::AtomicFile.write(path, content)
     versions(dir).drop(@history_keep).each { |old| File.delete(old) }
   rescue SystemCallError => e
     ctx.log.warn(:history_failed, skill: name, error: e.class.name, msg: e.message)

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -92,7 +92,6 @@ class SourceLinks
   end
 
   def initialize(settings = {})
-    settings = {} unless settings.is_a?(Hash)
     @sources = compile_sources(settings["sources"])
     max = settings["max"].to_i
     @max = max.positive? ? max : DEFAULT_MAX

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: source-links
-version: 0.3.0
+version: 0.3.1
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
@@ -8,7 +8,7 @@ files:
   source_links.md: sha256:aebd37f1e25491780994ecc4afc20ed6e8db32b724dc038302bb050177efada8
 hooks:
   source_links.rb:
-    sha256: sha256:0ee86a932efc90d81777855c81dea16510710d7371fe8b6b146a5a16b29794c2
+    sha256: sha256:574ea0c2b36f80dde410c4251753d70cbeea081d129f3f3547f41370e3990993
     event: after_turn
     on_error: log
     priority: 90

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

@@ -113,7 +113,7 @@ bundles:
 
 A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cover every MCP tool; see `docs/guardrails.md`. The mcp bundle saves each server's tool list in `$XDG_STATE_HOME/samagotchi/plugins/mcp/tools-<server>.json` (keyed by a digest of command/env/cwd): a changed server config is picked up by the next session start, which shows "Starting MCP server x (config changed, …)".
 
-**Preservation rule**: `ConfigFile.write_default_model!` and `ConfigFile.write_model_alias!` both load raw YAML (including nested sections and maps), mutate one key (`raw_data["default"]["model"] = ...` for new form), write atomically via `tmp`+`rename`. Never overwrite the file with only scalar keys — that would clobber `hooks:` / `model_aliases:` / `hosts:` / `recap:` / `guardrails:` / `bundles:`.
+**Preservation rule**: `ConfigFile.write_default_model!` and `ConfigFile.write_model_alias!` (`/model --default`, `/model --alias`) change one key on its own line of the text (`ConfigTextEdit`: the user's comments and layout stay; a new key goes at the end of its section, a missing section at the end of the file), check that the result parses to the old data plus that key (else they dump the whole file from it), and write through `AtomicFile` (a unique temp file renamed over config.yml, through a symlink, keeping its mode). Never overwrite the file with only scalar keys — that would clobber `hooks:` / `model_aliases:` / `hosts:` / `recap:` / `guardrails:` / `bundles:`.
 
 ## Workflow for any config edit
 
@@ -121,7 +121,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
 3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"`.
 4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it returns one `config: unknown key '…' (did you mean '…'?)` per key chi doesn't read (every config-exposed `Config::ENTRIES` key is known as written, including the section-less `max_tool_output_chars` and `skip_agent_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:` are free-form, host and model entries are checked against `Config::MAP_ENTRY_KEYS`). An empty list means no warning at start.
-5. **Write atomically**: `FileUtils.mkdir_p(File.dirname(path))`, `File.write("#{path}.tmp", YAML.dump(raw_data))`, `File.rename("#{path}.tmp", path)`.
+5. **Write**: change only the lines you mean to, with the edit tool, so the user's comments and layout stay; `YAML.dump` of the whole hash drops every comment, so rewrite the file only when it has none worth keeping. From Ruby, write atomically with `Samagotchi::AtomicFile.write(path, text)` (a unique temp file renamed over it), never through a fixed `"#{path}.tmp"` that another chi may be writing at the same time.
 6. Nothing else to update: config.yml values are never copied into `ENV`, and every `Config.get` reads the file again when it changed, so the next read (and every worker started after the write) sees the new value with origin `:file`. What a running worker set up at its start (`hosts:`, guardrail rules, bundle settings) waits for its restart. CLI overrides (`--model`, `--recap-model`, …) win over the file until the process exits; a worker gets its spawner's CLI settings through its env (`Config.cli_env`).
 
 ## Validations

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.9.0
+version: 0.10.1
 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:24e95727488daa80ac3008e020d8be098c7a1882153b7a61aba35450f72b86b7
+  config_modification_protocol.md: sha256:d8bdf062d5afce7430ead7f49439c1d1ed197a6261dc69a7c884f4b814266b12
   memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/cli/command.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module CLI
+    # The usage side of a subcommand: its error lines, usage errors (exit 2)
+    # and help. The including class sets @stdout and @stderr and defines
+    # #command_name ("chi send"); its usage text is USAGE unless it
+    # overrides #usage_text.
+    module Command
+      USAGE_EXIT = 2
+      HELP_WORDS = %w[-h --help help].freeze
+
+      private
+
+      def usage_text = self.class::USAGE
+
+      # What follows a usage error's line: the usage, or nil for a short
+      # "(see chi … --help)" at the end of the line instead.
+      def usage_on_error = usage_text
+
+      # stderr isn't buffered, stdout is when it's a pipe: flush the lines
+      # already printed, so the output keeps the order of the ids given.
+      def error_line(text)
+        @stdout.flush
+        @stderr.puts(text)
+      end
+
+      # @return [Integer] the usage exit status
+      def usage_error(message)
+        usage = usage_on_error
+        error_line("#{command_name}: #{message}#{usage ? "" : " (see #{command_name} --help)"}")
+        @stderr.puts(usage) if usage
+        USAGE_EXIT
+      end
+
+      # +argv+ through +flags+ (a Flags), help and usage errors done.
+      # @return [Flags::Result, Integer] the result, or the exit status
+      #   after the help (0) or a usage error (2)
+      def parse_flags(flags, argv, defaults = {})
+        parsed = flags.parse(argv, defaults)
+        if parsed.help
+          @stdout.puts(usage_text)
+          return 0
+        end
+        return usage_error(parsed.error.message) if parsed.error
+
+        parsed
+      end
+    end
+  end
+end

data/lib/samagotchi/cli/flags.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module CLI
+    # A subcommand's flags as a table (the subcommands bin/chi dispatches
+    # before OptionParser): each flag's names, whether it takes a value
+    # ("--flag V", or "--flag=V" for a long name) and whether it repeats.
+    # #parse walks argv once, in order, and stops at the first help word or
+    # error; what isn't a flag is a positional argument.
+    #
+    #   FLAGS = CLI::Flags.new(help: %w[-h --help help]) do |f|
+    #     f.value "-m", "--message"
+    #     f.value "--image", key: :images, repeat: true
+    #     f.switch "--new"
+    #   end
+    #   FLAGS.parse(argv, images: []) # => Result
+    class Flags
+      Flag = Struct.new(:key, :value, :repeat, :set, :refusal, keyword_init: true)
+
+      # kind :unknown (an undeclared flag, a switch given =V, or a
+      # positional where none are taken), :missing (a value flag with no
+      # value after it) or :refused (a flag declared with #refuse); +arg+ is
+      # the argument as given.
+      Error = Data.define(:kind, :arg, :refusal) do
+        def message
+          case kind
+          when :unknown then "unknown option #{arg}"
+          when :missing then "#{arg} needs a value"
+          else refusal
+          end
+        end
+      end
+
+      # +options+ by key, +args+ the positionals in order; +help+ true when
+      # a help word stopped the parse; +error+ nil or an Error.
+      Result = Data.define(:options, :args, :help, :error)
+
+      # @param help [Array<String>] words that stop the parse with help
+      #   (not when they are a flag's value)
+      # @param flag_pattern [Regexp] what an undeclared flag looks like (an
+      #   unknown option); other arguments are positionals
+      # @param dash_values [Boolean] false: a value flag followed by a
+      #   "--…" argument has no value
+      # @param args [Boolean] false: a positional is an unknown option
+      def initialize(help: [], flag_pattern: /\A-/, dash_values: true, args: true)
+        @help = help
+        @flag_pattern = flag_pattern
+        @dash_values = dash_values
+        @args = args
+        @flags = {}
+        yield self if block_given?
+      end
+
+      # A flag without a value: options[key] = +set+. The key defaults to
+      # the last name without its dashes, snake_cased.
+      def switch(*names, key: nil, set: true)
+        add(names, Flag.new(key: key, value: false, set: set))
+      end
+
+      # A flag with a value; +repeat+: options[key] collects them in an array.
+      def value(*names, key: nil, repeat: false)
+        add(names, Flag.new(key: key, value: true, repeat: repeat))
+      end
+
+      # A flag that is an error, with +message+ (a flag that doesn't exist
+      # on purpose).
+      def refuse(*names, message)
+        add(names, Flag.new(refusal: message))
+      end
+
+      # @param defaults [Hash] the options before any flag (not changed)
+      # @return [Result]
+      def parse(argv, defaults = {})
+        options = defaults.dup
+        args = []
+        rest = argv.dup
+        until rest.empty?
+          arg = rest.shift
+          return Result.new(options: options, args: args, help: true, error: nil) if @help.include?(arg)
+
+          name, inline = arg.start_with?("--") && arg.include?("=") ? arg.split("=", 2) : [arg, nil]
+          flag = @flags[name]
+          flag = nil if inline && !flag&.value
+          unless flag
+            return failure(options, args, :unknown, arg) if !@args || arg.match?(@flag_pattern)
+
+            args << arg
+            next
+          end
+          return failure(options, args, :refused, arg, flag.refusal) if flag.refusal
+          next options[flag.key] = flag.set unless flag.value
+
+          unless inline
+            return failure(options, args, :missing, arg) if rest.empty? || (!@dash_values && rest.first.start_with?("--"))
+
+            inline = rest.shift
+          end
+          options[flag.key] = flag.repeat ? [*options[flag.key], inline] : inline
+        end
+        Result.new(options: options, args: args, help: false, error: nil)
+      end
+
+      private
+
+      def add(names, flag)
+        flag.key ||= names.last.sub(/\A-+/, "").tr("-", "_").to_sym unless flag.refusal
+        names.each { |name| @flags[name] = flag }
+        self
+      end
+
+      def failure(options, args, kind, arg, refusal = nil)
+        Result.new(options: options, args: args, help: false, error: Error.new(kind: kind, arg: arg, refusal: refusal))
+      end
+    end
+  end
+end

data/lib/samagotchi/config.rb

@@ -6,6 +6,7 @@ require "fileutils"
 require "uri"
 require "set"
 require_relative "atomic_file"
+require_relative "config_text_edit"
 require_relative "log"
 require_relative "paths"
 
@@ -893,33 +894,39 @@ module Samagotchi
       nil
     end
 
-    def write_default_model!(model_name, env: ENV, path: global_path(env: env))
-      resolved = model_name.to_s.strip
-      raise ArgumentError, "model name is required" if resolved.empty?
+    # A top-level section of config.yml as written (nil when absent or the
+    # file doesn't parse); a reader checks its shape.
+    def section(name, env: ENV, path: global_path(env: env))
+      data = read_yaml(path: path)
+      data.is_a?(Hash) ? data[name] : nil
+    end
 
-      if resolved.include?(":") || resolved.include?("/")
-        sep = resolved.include?(":") ? ":" : "/"
-        prefix = resolved.split(sep, 2).first.to_s.strip.downcase
-        begin
-          hosts = hosts_config(env: env, path: path)
-          if hosts && !hosts.empty? && !hosts.key?(prefix) && prefix.match?(HOST_NAME_RE)
-          end
-        rescue StandardError
-          nil
-        end
+    # config.yml `bundles:`: each bundle's settings by name, for its hooks.
+    # @return [Hash{String => Hash}] {} when absent; a section that isn't a
+    #   mapping warns and counts as absent
+    def bundle_settings(env: ENV, path: global_path(env: env))
+      raw = section("bundles", env: env, path: path)
+      return {} if raw.nil?
+      unless raw.is_a?(Hash)
+        Log.warn(:hooks, "bundles_section_invalid", echo: "[samagotchi:hooks] config.yml bundles: must be a mapping of bundle name to settings; ignored")
+        return {}
       end
 
-      raw_data = read_yaml(env: env, path: path) || {}
+      raw.each_with_object({}) { |(name, value), acc| acc[name.to_s] = value.is_a?(Hash) ? value : {} }
+    rescue StandardError
+      {}
+    end
 
-      raw_data["default"] ||= {}
-      if raw_data["default"].is_a?(Hash)
-        raw_data["default"]["model"] = resolved
-      else
-        raw_data["default"] = { "model" => resolved }
-      end
-      FileUtils.mkdir_p(File.dirname(path))
-      AtomicFile.write(path, YAML.dump(raw_data))
-      clear_yaml_cache!(path)
+    # Sets default.model in config.yml; the rest of the file, comments
+    # included, stays as written (ConfigTextEdit).
+    def write_default_model!(model_name, env: ENV, path: global_path(env: env))
+      resolved = model_name.to_s.strip
+      raise ArgumentError, "model name is required" if resolved.empty?
+
+      expected = deep_copy(read_yaml(env: env, path: path) || {})
+      expected["default"] = {} unless expected["default"].is_a?(Hash)
+      expected["default"]["model"] = resolved
+      write_config_key(path, "default", "model", resolved, expected)
       Samagotchi::Config.reload!(cli_overrides: Samagotchi::Config.cli_overrides)
       true
     end
@@ -1003,50 +1010,58 @@ module Samagotchi
       aliases.fetch(value.downcase, value)
     end
 
+    # Words /model takes as arguments (clear/default/none/off reset the
+    # runtime model), so no alias may be named after one.
     RESERVED_MODEL_ALIASES = %w[clear default none off].freeze
 
-    def write_model_alias!(alias_name, model_name, env: ENV, path: global_path(env: env))
+    # What is wrong with +alias_name+ as an alias for +target+, or nil.
+    def model_alias_error(alias_name, target)
       alias_key = alias_name.to_s.strip
-      raise ArgumentError, "alias name is required" if alias_key.empty?
-      raise ArgumentError, "model name is required" if model_name.to_s.strip.empty?
+      return "alias name is required" if alias_key.empty?
 
       lowered_key = alias_key.downcase
-      raise ArgumentError, "alias name '#{alias_key}' is reserved" if RESERVED_MODEL_ALIASES.include?(lowered_key)
-      raise ArgumentError, "alias name must not contain whitespace" if alias_key.match?(/\s/)
-      raise ArgumentError, "alias name must not start with '-'" if alias_key.start_with?("-")
-      raise ArgumentError, "alias name must not contain '/'" if alias_key.include?("/")
-      unless alias_key.match?(/\A[a-z0-9][a-z0-9._-]*\z/i)
-        raise ArgumentError, "alias name must match /[a-z0-9][a-z0-9._-]*/i (got '#{alias_key}')"
-      end
+      return "alias name '#{alias_key}' is reserved" if RESERVED_MODEL_ALIASES.include?(lowered_key)
+      return "alias name must not contain whitespace" if alias_key.match?(/\s/)
+      return "alias name must not start with '-'" if alias_key.start_with?("-")
+      return "alias name must not contain '/'" if alias_key.include?("/")
+      return "alias name must match /[a-z0-9][a-z0-9._-]*/i (got '#{alias_key}')" unless alias_key.match?(/\A[a-z0-9][a-z0-9._-]*\z/i)
+      return "alias must not point to itself" if lowered_key == target.to_s.strip.downcase
 
-      resolved_model = model_name.to_s.strip
-      raise ArgumentError, "alias must not point to itself" if lowered_key == resolved_model.downcase
-
-      raw_data = read_yaml(env: env, path: path) || {}
+      nil
+    end
 
-      aliases_hash = raw_data[MODEL_ALIASES_KEY]
-      unless aliases_hash.is_a?(Hash)
-        aliases_hash = {}
-        raw_data[MODEL_ALIASES_KEY] = aliases_hash
-      end
+    def write_model_alias!(alias_name, model_name, env: ENV, path: global_path(env: env))
+      error = model_alias_error(alias_name, model_name)
+      raise ArgumentError, error if error
+      raise ArgumentError, "model name is required" if model_name.to_s.strip.empty?
 
-      # Normalize existing alias keys to downcase to avoid duplicates like Qwen/qwen
-      normalized = {}
-      aliases_hash.each do |k, v|
-        nk = k.to_s.strip.downcase
-        next if nk.empty?
-        normalized[nk] = v.to_s.strip unless v.to_s.strip.empty?
-      end
-      raw_data[MODEL_ALIASES_KEY] = normalized
+      lowered_key = alias_name.to_s.strip.downcase
+      resolved_model = model_name.to_s.strip
 
-      previous = normalized[lowered_key]
-      normalized[lowered_key] = resolved_model
+      previous = model_aliases(env: env, path: path)[lowered_key]
+      expected = deep_copy(read_yaml(env: env, path: path) || {})
+      aliases = expected[MODEL_ALIASES_KEY].is_a?(Hash) ? expected[MODEL_ALIASES_KEY] : {}
+      aliases.delete_if { |k, _| k.to_s.strip.downcase == lowered_key }
+      aliases[lowered_key] = resolved_model
+      expected[MODEL_ALIASES_KEY] = aliases
+      write_config_key(path, MODEL_ALIASES_KEY, lowered_key, resolved_model, expected)
+      previous
+    end
 
-      FileUtils.mkdir_p(File.dirname(path))
-      AtomicFile.write(path, YAML.dump(raw_data))
+    # Write +section+.+key+ = +value+ into config.yml (+expected+: the whole
+    # file's data after it), through a symlink, keeping the file's mode.
+    def write_config_key(path, section, key, value, expected)
+      target = File.exist?(path) ? File.realpath(path) : path
+      text = File.file?(target) ? File.read(target, encoding: "UTF-8") : nil
+      FileUtils.mkdir_p(File.dirname(target))
+      perm = File.stat(target).mode & 0o7777 if text
+      AtomicFile.write(target, ConfigTextEdit.set(text, section: section, key: key, value: value, expected: expected), perm: perm)
       clear_yaml_cache!(path)
-      previous
     end
+    private_class_method :write_config_key
+
+    def deep_copy(data) = Marshal.load(Marshal.dump(data))
+    private_class_method :deep_copy
 
     def nonempty_str(value)
       str = value.to_s.strip