samagotchi 0.100.1 → 0.102.0

data/lib/samagotchi/config.rb

@@ -22,6 +22,10 @@ module Samagotchi
   autoload :ModelSetting, File.expand_path("model_settings", __dir__)
   # The per-model/host seconds a cut waits (like Thinking for the level).
   autoload :SteerCutAfter, File.expand_path("steer_cut_after", __dir__)
+  # A refused --set (Config.coerce! raises its Error), and recap.sentences'
+  # check (IdleRecap::RecapPrompt): both load on first use.
+  autoload :SessionConfig, File.expand_path("session_config", __dir__)
+  autoload :IdleRecap, File.expand_path("idle_recap", __dir__)
 
   # Unified configuration registry implementing the implicit convention:
   #   ENV    SAMAGOTCHI_ATTR            (UPPER + prefix + _ = nesting)
@@ -39,8 +43,12 @@ module Samagotchi
   module Config
     # invalid: what an enum's invalid value falls to, when not the default
     # (guardrails.parent_answers: the strictest).
+    # session: true for a key a session may set for itself (chi --set KEY=VALUE,
+    # SessionConfig; its value is read through Config.get(key, session:)),
+    # check: a lambda that takes a typed value and returns nil, or the
+    # "takes ..." phrase a refused --set names (recap.sentences' N or N-M).
     Entry = Struct.new(:key, :yaml_path, :type, :default, :expose, :enum_values, :yaml_aliases, :lifecycle, :invalid,
-                       keyword_init: true) do
+                       :session, :check, keyword_init: true) do
       def env_key
         "SAMAGOTCHI_" + yaml_path.map { |p| p.upcase }.join("_")
       end
@@ -64,6 +72,9 @@ module Samagotchi
       def config_exposed?
         expose.include?(:config)
       end
+
+      # Whether a session may set the key for itself (chi --set).
+      def session? = session == true
     end
 
     # Section names: lower alnum only, no _ or -.
@@ -93,7 +104,9 @@ module Samagotchi
       # off on local ones. hosts.<name>.first_token_timeout wins.
       Entry.new(key: "server.first_token_timeout", yaml_path: %w[server first_token_timeout], type: :integer, default: nil,          expose: %i[env config], lifecycle: :worker_start),
 
-      Entry.new(key: "recap.enabled",            yaml_path: %w[recap enabled],             type: :bool,   default: nil,              expose: %i[env config], lifecycle: :worker_start),
+      # Both session-settable (chi --set recap.enabled=false): RecapSetup reads them through the session's layer.
+      Entry.new(key: "recap.enabled",            yaml_path: %w[recap enabled],             type: :bool,   default: nil,              expose: %i[env config], lifecycle: :worker_start,
+                session: true),
       Entry.new(key: "recap.model",              yaml_path: %w[recap model],               type: :string, default: nil,              expose: %i[env config cli], lifecycle: :worker_start),
       Entry.new(key: "recap.base_url",           yaml_path: %w[recap base_url],            type: :string, default: nil,              expose: %i[env config cli], lifecycle: :worker_start),
       Entry.new(key: "recap.host_ref",           yaml_path: %w[recap host_ref],            type: :string, default: nil,              expose: %i[env config cli], yaml_aliases: %w[host], lifecycle: :worker_start),
@@ -101,7 +114,9 @@ module Samagotchi
       Entry.new(key: "recap.timeout",            yaml_path: %w[recap timeout],             type: :float,   default: nil,             expose: %i[env config cli], lifecycle: :worker_start),
       Entry.new(key: "recap.min_user_turns",     yaml_path: %w[recap min_user_turns],      type: :integer, default: nil,             expose: %i[env config cli], lifecycle: :worker_start),
       # "N-M" or "N" sentences (1-10); unset = 2-4. Parsed by RecapPrompt.sentences_range.
-      Entry.new(key: "recap.sentences",          yaml_path: %w[recap sentences],           type: :string,  default: nil,             expose: %i[env config cli], lifecycle: :worker_start),
+      Entry.new(key: "recap.sentences",          yaml_path: %w[recap sentences],           type: :string,  default: nil,             expose: %i[env config cli], lifecycle: :worker_start,
+                session: true,
+                check: ->(value) { "N or N-M (1-#{IdleRecap::RecapPrompt::MAX_SENTENCES})" unless IdleRecap::RecapPrompt.sentences_range(value) }),
 
       # chi broadcast (Broadcast::Recipients, Broadcast::Tags): a session that ended no turn in this many hours (and
       # no worker or REPL runs) gets no broadcast; a ticket id in the note and in a session's branch or prompts
@@ -289,6 +304,9 @@ module Samagotchi
       Entry.new(key: "web.markdown",             yaml_path: %w[web markdown],             type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
       # The page's view of a turn: stage (the running turn pinned above the composer) or turn (one block of generations, the live one at the bottom); ?view= overrides it per page load.
       Entry.new(key: "web.view",                 yaml_path: %w[web view],                 type: :enum,    default: "stage",        expose: %i[env config cli], enum_values: %w[stage turn], lifecycle: :web_start),
+      # The stage view's working set (files, memories and URLs the turn brought into context): a rail in the stage, a
+      # footprint under each finished turn and a "set N" chip in place of the mem chip; ?working_set=1|0 overrides it per page load.
+      Entry.new(key: "web.working_set",          yaml_path: %w[web working_set],          type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
       # Quick replies next to Annotate in the page's selection bubble, "|"-separated (a YAML list works too); "" leaves only Annotate.
       Entry.new(key: "web.annotate_presets",     yaml_path: %w[web annotate_presets],     type: :string, default: "Agreed|Could you please elaborate?", expose: %i[env config cli], lifecycle: :web_start),
       # What a file ref (a tool row's file, a diff line) opens on this machine: a preset (vscode, vscode-insiders, cursor, zed, none) or a URL template with {path} and an optional {line} (Web::Editor).
@@ -305,7 +323,7 @@ module Samagotchi
 
     # Top-level maps and lists read by their own code, whose entry names and
     # contents are the user's: ConfigFile.model_aliases / preloaded_memories /
-    # appended_prompt_files, Hooks::Loader, Engine#read_bundle_settings.
+    # appended_prompt_files, Hooks::Loader, ConfigFile.bundle_settings.
     FREE_FORM_MAPS = %w[model_aliases hooks bundles memories append_system_prompt].freeze
     # Maps of named entries and the keys an entry may hold
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
@@ -321,6 +339,10 @@ module Samagotchi
     # And toolkit's kits (Toolkit.kits).
     SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze, "toolkit" => %w[kits].freeze }.freeze
 
+    # What a :bool value reads as (Config.coerce!), YAML 1.1's words and 1/0.
+    BOOL_WORDS = { "1" => true, "true" => true, "yes" => true, "on" => true,
+                   "0" => false, "false" => false, "no" => false, "off" => false }.freeze
+
     # Fast lookup maps
     BY_KEY = ENTRIES.each_with_object({}) { |e, h| h[e.key] = e }.freeze
 
@@ -339,58 +361,70 @@ module Samagotchi
         ENTRIES.select(&:cli_exposed?)
       end
 
-      # Coercion helpers
-      def coerce(entry, raw)
+      # The entries a session may set for itself (Entry#session?).
+      def session_entries
+        ENTRIES.select(&:session?)
+      end
+
+      # +raw+ as +entry+'s type, strictly: a value of another shape raises.
+      # :string as given (a YAML list joined with |), :integer, :float,
+      # :bool (true/yes/on/1, false/no/off/0/""), :enum in its canonical
+      # case; nil for nil, and for a blank value of any other type than
+      # :string and :bool. #coerce is its lenient twin (config.yml, env).
+      # @raise [SessionConfig::Error] "KEY takes WHAT, not RAW"
+      def coerce!(entry, raw)
         return nil if raw.nil?
+        # A YAML list for a "|"-separated setting (web.annotate_presets).
+        # As given, trailing spaces included ("Please ").
+        return raw.is_a?(Array) ? raw.join("|") : raw.to_s if entry.type == :string
 
-        # For string, preserve as-is (including trailing spaces like "Please ")
-        if entry.type == :string
-          # A YAML list for a "|"-separated setting (web.annotate_presets).
-          str = raw.is_a?(Array) ? raw.join("|") : raw.to_s
-          return nil if str.empty? && entry.type != :string
+        str = raw.to_s.strip
+        return false if entry.type == :bool && str.empty?
+        return nil if str.empty?
+
+        value = case entry.type
+                when :integer then Integer(str, exception: false)
+                when :float then Float(str, exception: false)
+                when :bool then BOOL_WORDS[str.downcase]
+                when :enum then entry.enum_values.find { |v| v.downcase == str.downcase }
+                else str
+                end
+        raise SessionConfig::Error, "#{entry.key} takes #{takes(entry)}, not #{raw.to_s.inspect}" if value.nil?
+
+        value
+      end
 
-          return str
+      # What +entry+'s type takes, as a refusal names it.
+      def takes(entry)
+        case entry.type
+        when :integer then "an integer"
+        when :float then "a number"
+        when :bool then "true or false"
+        when :enum then "#{entry.enum_values[0..-2].join(", ")} or #{entry.enum_values.last}"
+        else "text"
         end
-        str = raw.to_s.strip
-        return nil if str.empty? && entry.type != :string
+      end
 
+      # +raw+ as +entry+'s type (#coerce!), leniently: a value of another
+      # shape warns and falls back (the default; false for a bool; an
+      # enum's +invalid+ when it has one).
+      def coerce(entry, raw)
+        coerce!(entry, raw)
+      rescue SessionConfig::Error
         case entry.type
-        when :string
-          str
         when :integer
-          Integer(str, exception: false).tap do |v|
-            if v.nil?
-              Log.warn(:config, "invalid_value", echo: "Warning: invalid integer for #{entry.key} (#{entry.env_key}): #{raw.inspect} — using default", key: entry.key)
-              return entry.default
-            end
-          end
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid integer for #{entry.key} (#{entry.env_key}): #{raw.inspect} — using default", key: entry.key)
+          entry.default
         when :float
-          val = Float(str, exception: false)
-          if val.nil?
-            Log.warn(:config, "invalid_value", echo: "Warning: invalid float for #{entry.key}: #{raw.inspect}", key: entry.key)
-            return entry.default
-          end
-          val
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid float for #{entry.key}: #{raw.inspect}", key: entry.key)
+          entry.default
         when :bool
-          case str.downcase
-          when "1", "true", "yes", "on" then true
-          when "0", "false", "no", "off", "" then false
-          else
-            Log.warn(:config, "invalid_value", echo: "Warning: invalid bool for #{entry.key}: #{raw.inspect} — treating as false", key: entry.key)
-            false
-          end
-        when :enum
-          lowered = str.downcase
-          allowed = entry.enum_values.map(&:downcase)
-          unless allowed.include?(lowered)
-            using = entry.invalid ? "using #{entry.invalid}" : "using default"
-            Log.warn(:config, "invalid_value", echo: "Warning: invalid value for #{entry.key}: #{raw.inspect} (allowed: #{entry.enum_values.join(", ")}) — #{using}", key: entry.key)
-            return entry.invalid || entry.default
-          end
-          # return canonical casing from enum_values
-          entry.enum_values.find { |v| v.downcase == lowered }
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid bool for #{entry.key}: #{raw.inspect} — treating as false", key: entry.key)
+          false
         else
-          str
+          using = entry.invalid ? "using #{entry.invalid}" : "using default"
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid value for #{entry.key}: #{raw.inspect} (allowed: #{entry.enum_values.join(", ")}) — #{using}", key: entry.key)
+          entry.invalid || entry.default
         end
       end
 
@@ -403,10 +437,14 @@ module Samagotchi
       end
 
       # Same as #resolve, plus the layer the value came from:
-      # :cli, :env, :file or :default.
-      def resolve_with_origin(key, file_data: nil, env: ENV, cli_overrides: {})
+      # :session, :cli, :env, :file or :default. +session+ is a session's
+      # own values (SessionConfig::Settings#core, typed): a session-settable
+      # key's value there goes first, over the CLI (a worker gets its CLI
+      # as env, and the session's value was given for this session).
+      def resolve_with_origin(key, file_data: nil, env: ENV, cli_overrides: {}, session: nil)
         entry = find_by_key(key)
         raise ArgumentError, "unknown config key: #{key}" unless entry
+        return [session[entry.key], :session] if entry.session? && session&.key?(entry.key)
 
         # CLI wins
         if cli_overrides.key?(entry.key)
@@ -520,8 +558,9 @@ module Samagotchi
         end
       end
 
-      def get(key)
-        get_with_origin(key).first
+      # The live value of +key+; +session+ as #resolve_with_origin takes it.
+      def get(key, session: nil)
+        get_with_origin(key, session: session).first
       end
 
       # default.max_tokens: the most tokens one generation may produce, or
@@ -542,8 +581,8 @@ module Samagotchi
       end
 
       # [value, origin] for the live value #get returns; origin is one of
-      # :cli, :env, :file, :default.
-      def get_with_origin(key)
+      # :session, :cli, :env, :file, :default.
+      def get_with_origin(key, session: nil)
         entry = find_by_key(key)
         raise ArgumentError, "unknown config key: #{key}" unless entry
 
@@ -552,7 +591,7 @@ module Samagotchi
         # overrides captured via reload!
         path = Samagotchi::ConfigFile.global_path rescue nil
         file_data = Samagotchi::ConfigFile.read_yaml(path: path) if path
-        resolve_with_origin(entry.key, file_data: file_data, env: ENV, cli_overrides: cli_overrides)
+        resolve_with_origin(entry.key, file_data: file_data, env: ENV, cli_overrides: cli_overrides, session: session)
       end
 
       # Problems with the keys of a parsed config.yml, one message per key the

data/lib/samagotchi/engine.rb

@@ -84,6 +84,7 @@ require_relative "relay_desk"
 require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
 require_relative "prompt_warmup"
+require_relative "working_set"
 
 module Samagotchi
   # Engine owns the core agent logic: system prompt construction, tool
@@ -106,6 +107,8 @@ module Samagotchi
 
     # What memory_write answers in a scratch session.
     SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
+    # The session setting /recap on|off|default writes (#recap_override=).
+    RECAP_ENABLED_KEY = "recap.enabled"
 
     # @param client             [Client, nil] defaults to Client.new
     # @param profile            [ModelProfile, Symbol, String, nil]
@@ -231,9 +234,9 @@ module Samagotchi
       # across UIs.
       @turn_state.restart_clock!
       @side_client_mutex = Mutex.new
-      @recap = RecapSetup.build(recap, engine: self, host_registry: @host_registry,
-                                session_target: -> { session_model_recap_target },
-                                session_id: -> { @session&.id }, state_dir: -> { session_state_dir })
+      # Kept for a rebuild under a bound session's own recap values.
+      @recap_kwarg = recap
+      @recap = build_recap
       # One shared poller for the whole idle layer (reminders + optional
       # recap). Both jobs read the activity seam above; the scheduler owns
       # the single background thread and isolates per-job failures.
@@ -785,7 +788,7 @@ module Samagotchi
     # UIs need in the event log, emitted outside any turn's stream.
     ANNOUNCEABLE_EVENTS = %i[turn_enqueued turn_dequeued input_merged prompt_restored continue_offered continue_resolved
                              command_queued command_ran context_added card hook_notice guardrail_warning
-                             plugin_init_started plugin_init_finished].freeze
+                             plugin_init_started plugin_init_finished working_set_updated].freeze
 
     # Put a transport-level event into the ordered event log. Unlike turn
     # events it reaches only persistent observers (no turn sink, no memory
@@ -806,6 +809,34 @@ module Samagotchi
       @session_observer.synchronize(&)
     end
 
+    # The working set's :working_set_updated, announced between turns
+    # (after a command changed what the next request sends), when it
+    # differs from the last one emitted (#emit_working_set). Under the
+    # event lock, so it is ordered with the change's own events.
+    def announce_working_set(session = @session)
+      return unless session
+
+      synchronize_events { emit_working_set(nil, session, session.messages) }
+    end
+
+    # The strategy the working set is built under now, as LLMContextView
+    # takes it: the running turn's, else the next turn's (#emit_working_set).
+    # /working-set's ops act under it.
+    # @return [Symbol, Array<Symbol>]
+    def working_set_strategy
+      working_set_llm_context&.strategy || LLMContextView::NONE
+    end
+
+    # Replace the current session's conversation, between turns (a
+    # /working-set op's copy: #clone_messages, then its edits).
+    # @param messages [Array<Hash>]
+    # @return [Array<Hash>] the session's messages
+    def replace_messages(messages)
+      raise ArgumentError, "no current session" unless @session
+
+      replace_session_messages(@session, messages)
+    end
+
     # Add a context note to the session's conversation, between turns: a
     # tail system message the next turn sees, announced as :context_added.
     # The array is replaced, not mutated, and the append and the event
@@ -1130,6 +1161,8 @@ module Samagotchi
     # price_host: the effective model's host, whose hosts.<name>.models
     # prices the cost estimate names. kit_prompt: the next turn's kit
     # prompt text ({kit:, tokens:}), only when its toolkit has one.
+    # settings: the session's own settings ({"recap.enabled" => false}),
+    # only when it has some.
     # @return [Hash] @metrics.snapshot, filled in
     def stats_snapshot
       snapshot = @metrics.snapshot
@@ -1144,6 +1177,9 @@ module Samagotchi
                                 price_host: model.host_name)
       kit_prompt = kit_prompt_stats
       snapshot = snapshot.merge(kit_prompt: kit_prompt) if kit_prompt
+      # The session's own settings (chi --set), as --set names them.
+      settings = @session&.settings&.flat || {}
+      snapshot = snapshot.merge(settings: settings) unless settings.empty?
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(model)
         if window
@@ -1459,6 +1495,7 @@ module Samagotchi
       synchronize_events do
         kept, event = yield(seconds)
         replace_session_messages(turn.session, kept) if kept
+        emit_working_set(turn.on_event, turn.session, turn.session.messages)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
@@ -1720,6 +1757,8 @@ module Samagotchi
       @session = session
       # One session per REPL/worker process: its records carry this sid.
       Log.session_id = session.id if session&.id
+      # Its own recap values (chi --set recap.enabled=false) rebuild the job.
+      rebuild_recap!
       # A woken worker's /stats and status line count the turns before it.
       bind_metrics(session)
       @used_memories.absorb(session)
@@ -1750,6 +1789,66 @@ module Samagotchi
     # @return [IdleRecap, nil] the idle recap detector, or nil when disabled
     attr_reader :recap
 
+    # Whether a continue offer waits (the Worker's or the REPL's TurnFlow),
+    # for the recap job: this one and any rebuilt one (IdleRecap#awaiting_continue=).
+    def recap_awaiting_continue=(callable)
+      @recap_awaiting_continue = callable
+      @recap&.awaiting_continue = callable
+    end
+
+    # The idle recap job (RecapSetup.build) under the current session's own
+    # recap values, which it records.
+    # @return [IdleRecap, nil]
+    def build_recap
+      @recap_built_for = session_recap_values
+      recap = RecapSetup.build(@recap_kwarg, engine: self, host_registry: @host_registry,
+                                             session_target: -> { session_model_recap_target },
+                                             session_id: -> { @session&.id }, state_dir: -> { session_state_dir },
+                                             session_config: -> { @session&.settings&.core })
+      recap.awaiting_continue = @recap_awaiting_continue if recap && @recap_awaiting_continue
+      recap
+    end
+    private :build_recap
+
+    # The bound session's own recap.* values ({} for none).
+    def session_recap_values
+      (@session&.settings&.core || {}).select { |key, _| key.start_with?("recap.") }
+    end
+    private :session_recap_values
+
+    # A new recap job when the bound session's own recap values differ from
+    # the ones the current job was built under (none at start): the old one
+    # is dropped (an attempt in flight goes stale) and the scheduler swaps
+    # it, keeping its one thread. Binding the same session again changes
+    # nothing (the REPL binds it twice).
+    def rebuild_recap!
+      return if session_recap_values == @recap_built_for
+
+      old = @recap
+      old&.invalidate!
+      @recap = build_recap
+      @idle_scheduler&.replace_job(old, @recap)
+    end
+
+    # /recap on|off|default: the bound session's own recap.enabled (true,
+    # false; nil removes it, so config.yml's applies again), and the recap
+    # job rebuilt under it at once. It doesn't save: the command says
+    # changed: [:recap] and its host saves (Worker#run_command).
+    # @param enabled [Boolean, nil]
+    # @raise [ArgumentError] no session is bound
+    def recap_override=(enabled)
+      raise ArgumentError, "no session" unless @session
+
+      core = @session.settings.core.dup
+      enabled.nil? ? core.delete(RECAP_ENABLED_KEY) : core[RECAP_ENABLED_KEY] = enabled
+      @session.settings = @session.settings.with(core: core)
+      rebuild_recap!
+    end
+
+    # The bound session's own recap.enabled (/recap on|off, --set), or nil.
+    # @return [Boolean, nil]
+    def recap_override = @session&.settings&.core&.fetch(RECAP_ENABLED_KEY, nil)
+
     # Write the recap now, before the session is left (IdleRecap#write_now).
     # @return [String, nil] the recap written, nil when none was (recap off,
     #   nothing new, an error, the timeout)
@@ -2835,11 +2934,61 @@ module Samagotchi
 
         event = with_generation_report(event) if event[:type] == :generation_completed
         emit_event(on_event, event)
+        # What this request sends: both loops start a generation after
+        # their apply_llm_context!.
+        emit_working_set(on_event, @session, live_conversation) if event[:type] == :generation_started
         watch.feed(**progress) if watch && progress
         @thinking_notices.generation_completed(event) if event[:type] == :generation_completed
       end
     end
 
+    # The working set (WorkingSet) as the model has it, as a
+    # :working_set_updated event ({items:, at:}): at each request (the
+    # stream handler's :generation_started, from the running turn's
+    # conversation) and at turn end (#end_turn, from the session's kept
+    # messages). Only when it differs from the last one emitted for this
+    # session, and never while it is empty — except one empty event,
+    # remembered, when the last one for this session had items (a
+    # rollback removed the tool calls), so a tool-free turn emits none
+    # and the next empty request sends nothing more. The web overlays it
+    # on the rows' set; other UIs ignore it.
+    #
+    # Between turns (#announce_working_set: no +on_event+) it is
+    # announced, under the next turn's strategy.
+    def emit_working_set(on_event, session, conversation)
+      return unless session && conversation
+
+      snapshot = WorkingSet.build(conversation, cwd: session.working_directory, strategy: working_set_strategy)
+
+      items = snapshot.items.map(&:to_h)
+      last = @working_set_emitted
+      if items.empty?
+        return unless last && last[0] == session.id && !last[1].empty?
+      elsif last == [session.id, items]
+        return
+      end
+
+      @working_set_emitted = [session.id, items]
+      event = { type: :working_set_updated, items: items, at: snapshot.at }
+      on_event ? emit_event(on_event, event) : announce_or_hold(event)
+    rescue StandardError => e
+      Log.warn(:turn, "working_set_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+    end
+    private :emit_working_set
+
+    # The strategy the set is built under: the running turn's
+    # (TurnSettings#llm_context: what its requests send); between turns
+    # the next turn's (as #warm_up_next_turn: the turn's settings keep the
+    # last turn's, stale after a /llm-context or /model change), the last
+    # turn's when it can't be resolved.
+    def working_set_llm_context
+      turn = @kernel.respond_to?(:turn_settings) ? @kernel.turn_settings&.llm_context : nil
+      return turn if turn_running?
+
+      @model_settings.turn_llm_context || turn
+    end
+    private :working_set_llm_context
+
     # A :generation_completed with the generation's decode speed (`speed:`
     # {decode_tps:, source:}, nil without one), the session's running
     # token totals (`tokens:`, the snapshot's block) and its per-model rows

data/lib/samagotchi/host_keys.rb

@@ -21,16 +21,22 @@ module Samagotchi
     # Reads one generic password through /usr/bin/security (by absolute
     # path: the helper's PATH isn't the shell's) in its own process group,
     # killed at the deadline: a locked keychain or an access dialog must not
-    # hang a turn. nil on a miss, a non-zero exit, a timeout, no binary, or
-    # off macOS.
+    # hang a turn. The deadline covers the spawn too (macOS can hold a first
+    # exec for minutes while it scans the binary): the run is a thread the
+    # caller gives up on, and a pid that turns up late is killed and reaped
+    # there. nil on a miss, a non-zero exit, a timeout, no binary, or off
+    # macOS.
     class Keychain
       SECURITY = "/usr/bin/security"
       TIMEOUT = 5
 
-      def initialize(security: SECURITY, timeout: TIMEOUT, host_os: RbConfig::CONFIG["host_os"])
+      # +spawner+: how the run starts (Process.spawn's arguments; specs stall it).
+      def initialize(security: SECURITY, timeout: TIMEOUT, host_os: RbConfig::CONFIG["host_os"],
+                     spawner: Process.method(:spawn))
         @security = security
         @timeout = timeout
         @macos = host_os.to_s.include?("darwin")
+        @spawner = spawner
       end
 
       # @return [String, nil]
@@ -45,33 +51,44 @@ module Samagotchi
       private
 
       def run(name)
-        reader, writer = IO.pipe
-        pid = Process.spawn(@security, "find-generic-password", "-s", SERVICE, "-a", name, "-w",
-                            in: File::NULL, out: writer, err: File::NULL, pgroup: true)
-        writer.close
-        waiter = Process.detach(pid)
-        unless waiter.join(@timeout)
-          stop(pid, waiter)
-          Log.warn(:config, "keychain_timeout", name: name, seconds: @timeout)
-          return nil
+        lock = Mutex.new
+        pid = nil
+        late = false
+        worker = Thread.new do
+          Thread.current.report_on_exception = false
+          security(name) { |spawned| lock.synchronize { late ? stop(spawned) : pid = spawned } }
         end
-        return nil unless waiter.value.success?
+        return worker.value if worker.join(@timeout)
 
-        key = reader.read.to_s.chomp
-        key.strip.empty? ? nil : key
+        lock.synchronize do
+          late = true
+          stop(pid) if pid
+        end
+        Log.warn(:config, "keychain_timeout", name: name, seconds: @timeout)
+        nil
       rescue SystemCallError
         nil
+      end
+
+      # One run, start to reap; yields the pid as soon as there is one.
+      def security(name)
+        reader, writer = IO.pipe
+        pid = @spawner.call(@security, "find-generic-password", "-s", SERVICE, "-a", name, "-w",
+                            in: File::NULL, out: writer, err: File::NULL, pgroup: true)
+        writer.close
+        yield pid
+        key = reader.read.to_s.chomp
+        _, status = Process.wait2(pid)
+        status.success? && !key.strip.empty? ? key : nil
       ensure
         writer&.close unless writer&.closed?
         reader&.close
       end
 
-      def stop(pid, waiter)
+      def stop(pid)
         Process.kill(:KILL, -pid)
       rescue SystemCallError
         nil
-      ensure
-        waiter.join(1)
       end
     end
 

data/lib/samagotchi/idle_scheduler.rb

@@ -25,7 +25,7 @@ module Samagotchi
       raise ArgumentError, "IdleScheduler requires an engine" unless engine
 
       @engine = engine
-      @jobs = jobs.compact
+      @jobs = jobs.compact.freeze
       @thread = nil
       @stopped = false
     end
@@ -49,6 +49,21 @@ module Samagotchi
       @thread = nil
     end
 
+    # Swap the job +old+ for +new+ (Engine#session= rebuilding the recap):
+    # nil +old+ adds +new+, nil +new+ drops +old+. The list is replaced
+    # whole, so a tick on the thread steps the old list or the new one; a
+    # running scheduler keeps its one thread, and one with no jobs yet
+    # starts it once #start is called.
+    def replace_job(old, new)
+      jobs = if @jobs.any? { |job| job.equal?(old) }
+               @jobs.map { |job| job.equal?(old) ? new : job }
+             else
+               @jobs + [new]
+             end
+      @jobs = jobs.compact.freeze
+      self
+    end
+
     # One step across all jobs. Public so specs can drive it deterministically.
     def tick
       return if @stopped