samagotchi 0.9.0 → 0.10.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.3
 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:4f32b3457ada3392009e4a32b690e577ef0bb05d46c6cfed9ae02640119620d8
 requires_chi: ">= 0.9.0"

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

@@ -43,7 +43,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 +86,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 +170,14 @@ 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)
 
     @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 tool error ("[x] Error: …" raised, "[x]\nError: …" returned), or an
@@ -216,8 +215,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.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: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

data/lib/samagotchi/config_text_edit.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "psych"
+
+module Samagotchi
+  # Sets one section.key in config.yml text, line by line, so the user's
+  # comments and layout stay (YAML.dump would drop them), the way
+  # Bootstrap::ConfigWriter inserts a host. A key already in the block is
+  # replaced on its line (a comment after the old value goes with it), a new
+  # one goes at the end of the block, a missing section at the end of the
+  # file. The result is parsed again and must equal +expected+; when it
+  # doesn't, or the text is something a line edit can't handle (a flow-style
+  # section, anchors, a duplicate section), the whole file is dumped from
+  # +expected+ instead.
+  module ConfigTextEdit
+    DEFAULT_INDENT = 2
+
+    module_function
+
+    # @param text [String, nil] the file's text (nil: no file)
+    # @param section [String] a top-level key ("default")
+    # @param key [String] the key under it; an existing key matches in any case
+    # @param value [String] the value, written as a quoted string
+    # @param expected [Hash] the whole file's data after the change
+    # @return [String] the new text
+    def set(text, section:, key:, value:, expected:)
+      edited = text && edit(text, section, key, value)
+      edited && parse(edited) == expected ? edited : YAML.dump(expected)
+    rescue Psych::Exception
+      YAML.dump(expected)
+    end
+
+    def edit(text, section, key, value)
+      return nil if anchors?(text)
+
+      # A key the lines below can't see (flow style, odd quoting) would end up
+      # written twice, and YAML keeps the last one without a word.
+      original = parse(text)
+      original = {} unless original.is_a?(Hash)
+      section_data = original[section]
+      has_key = section_data.is_a?(Hash) && section_data.keys.any? { |k| k.to_s.downcase == key.downcase }
+
+      eol = text.include?("\r\n") ? "\r\n" : "\n"
+      lines = text.split(/(?<=\n)/)
+      lines[-1] = "#{lines[-1]}#{eol}" if lines.any? && !lines[-1].end_with?("\n")
+      header = /\A#{Regexp.escape(section)}:[ \t]*(#.*)?\z/
+      starts = lines.each_index.select { |i| lines[i].chomp.match?(header) }
+      return nil if starts.length > 1
+
+      return nil if starts.empty? && original.key?(section)
+
+      if starts.empty?
+        lines.concat(["#{section}:#{eol}", "#{" " * DEFAULT_INDENT}#{key}: #{scalar(value)}#{eol}"])
+        return lines.join
+      end
+
+      at = starts.first
+      stop = at + 1
+      stop += 1 while stop < lines.length && inside_block?(lines[stop])
+      children = lines[(at + 1)...stop].reject { |line| line.strip.empty? || comment?(line) }
+      child = children.first ? indent(children.first) : DEFAULT_INDENT
+      new_line = "#{" " * child}#{key}: #{scalar(value)}#{eol}"
+      found = ((at + 1)...stop).find { |i| indent(lines[i]) == child && key_of(lines[i])&.downcase == key.downcase }
+      if found
+        lines[found] = new_line
+      else
+        return nil if has_key
+
+        stop -= 1 while stop > at + 1 && (lines[stop - 1].strip.empty? || (comment?(lines[stop - 1]) && indent(lines[stop - 1]) < child))
+        lines.insert(stop, new_line)
+      end
+      lines.join
+    end
+
+    def key_of(line)
+      line[/\A\s*(["']?)([^"':#\s][^"':#]*?)\1:(?:\s|\z)/, 2]
+    end
+
+    def inside_block?(line)
+      return true if line.strip.empty?
+      return false if line.start_with?("---", "...")
+
+      line.start_with?(" ", "\t") || comment?(line)
+    end
+
+    def comment?(line) = line.lstrip.start_with?("#")
+    def indent(line) = line[/\A */].length
+
+    # JSON's quoting is valid YAML: model ids hold "/" and ":".
+    def scalar(value) = JSON.generate(value.to_s)
+
+    def parse(text) = YAML.safe_load(text, permitted_classes: [], aliases: false)
+
+    def anchors?(text)
+      stack = [Psych.parse_stream(text)]
+      until stack.empty?
+        node = stack.pop
+        return true if node.is_a?(Psych::Nodes::Alias) || (node.respond_to?(:anchor) && node.anchor)
+
+        stack.concat(Array(node.children)) if node.respond_to?(:children)
+      end
+      false
+    end
+  end
+end