samagotchi 0.101.0 → 0.102.0

data/docs/sessions.md

@@ -151,6 +151,13 @@ system message marked `kind: turn_note` (the UIs don't show it; they showed the
   nothing). The user's last message is still unanswered.]`, or `[SYSTEM: the previous turn's answer was refused by
   the provider (cyber). …]` when the provider refused it.
 
+After you drop or undrop an item of the working set between turns (`/working-set drop KEY`, the web list's
+`drop`; [cli.md](cli.md#the-working-set)), the next turn starts with one line about it (`kind: working_set`,
+escaped like a context note; the UIs don't show it): `[WORKING SET: since your last turn the user dropped
+lib/cart.rb from your context: you are sent a stub instead of its outputs; read it again only if the task needs
+it.]`. Every op since the last turn joins that one line, and an undrop before the next turn takes its drop off it.
+The drop itself is saved on the entries (`edits`, kind `drop`), so `--resume`, rollbacks and forks keep it.
+
 When the context window fills past 40% (then 60%, 80%), the native loop leaves a similar line (`kind: context`):
 `[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted
 and range reads over full-file dumps]`, once per rise; see [context telemetry](internals/context-telemetry.md).
@@ -211,9 +218,9 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
 - `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `removed` (a `--queue --wait` message taken back before it ran), `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` (`worker_stopped`: the turn waited for died with its worker and the next worker settled it) and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs; with an idle session whose last turn already ended, that ended turn is the answer: its reply, or its end when it left no reply — a turn that finished in the gap between waits is reported, not waited for. With none of those (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
-- `--set BUNDLE.KEY=VALUE` (with `--new`, repeatable) gives the new session a bundle setting of its own, as `chi --set` does (see *Bundle settings* below): `chi send --new --set cost-cap.cap=3 -m "…"` starts it with a $3 cap. A bundle or key the installed bundles don't offer, or a value of another type than the manifest gives the key (`cost-cap.cap=five`), is a usage error (exit 2), as is `--set` without `--new`.
+- `--set KEY=VALUE` (with `--new`, repeatable) gives the new session a setting of its own, as `chi --set` does (see *Session settings* below): a core key a session may set (`--set recap.enabled=false`) or a bundle's `BUNDLE.KEY` (`chi send --new --set cost-cap.cap=3 -m "…"` starts it with a $3 cap). A key no session sets (`guardrails.mode`), a bundle or key the installed bundles don't offer, or a value of another type than the key takes (`recap.enabled=maybe`, `cost-cap.cap=five`) is a usage error (exit 2), as is `--set` without `--new`.
 - `--parent-answers LEVEL` (with `--new`) gives the new session its own `guardrails.parent_answers` (`hard`, `standard`, `soft`), tighten-only: config.yml's applies when it is stricter, with `chi send: warning: --parent-answers soft is looser than config.yml's …`. See *Parent answers* below.
-- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit, bundle settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
+- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit, session settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
 
@@ -274,15 +281,25 @@ fork keep it, and a `delegate` child starts with its parent's as it is then (a l
 it). A value that isn't a level reads as `hard`. `/parent-answers` changes it; loosening it is yours alone (see
 [Guardrails](guardrails.md#answers-from-a-parent-agent)).
 
-## Bundle settings
-
-A session file's `bundle_settings` (`{"cost-cap": {"cap": 3}}`, `{}` for none and for a session from before them)
-holds the bundle settings it was created with: `chi --set BUNDLE.KEY=VALUE`, `chi send --new --set …`, or `POST
-/api/sessions` `bundle_settings` (an object of the same shape, checked the same way; `400 invalid_bundle_settings`
-otherwise). They never change after: a respawned or woken worker reads the same, and a continue (`continue →`,
-`chi send --new --continues`) and a fork (`ctx.sessions.fork`) copy them, as they copy the toolkit. A delegate
-child starts without (a bundle has its own setting for children, such as cost-cap's `child:`). A bundle's plugin
-reads them in `ctx.settings`, over config.yml's `bundles:` ([Per-session settings](plugins.md#per-session-settings)).
+## Session settings
+
+A session's own settings are what `chi --set`, `chi send --new --set …` or `POST /api/sessions` `settings` gave it
+at creation. One changes live: `/recap on|off|default` (any UI, or `chi send -m "/recap off" ID`) sets or removes
+`recap.enabled` and the worker saves it, so a respawn keeps it. The file keeps them in two fields:
+
+- `config_settings` (`{"recap.enabled": false}`): the core keys a session may set (`recap.enabled`,
+  `recap.sentences`; see [Per-session settings](configuration.md#per-session-settings)), typed by their key. They go
+  first, over the CLI, the environment and config.yml. A value the file holds for a key that is no longer settable, or
+  of another type, is dropped when the file is read.
+- `bundle_settings` (`{"cost-cap": {"cap": 3}}`): a bundle's settings, which its plugin reads in `ctx.settings`, over
+  config.yml's `bundles:` ([Per-session settings](plugins.md#per-session-settings)).
+
+Both are `{}` for none and for a session from before them. `POST /api/sessions` takes them flat, as `--set` names
+them (`"settings": {"recap.enabled": false, "cost-cap.cap": 3}`), checked the same way (`400 invalid_settings`
+otherwise; `settings` beside `continues` is refused). A respawned or woken worker reads the same, and a continue
+(`continue →`, `chi send --new --continues`) and a fork (`ctx.sessions.fork`) copy them, as they copy the toolkit. A
+delegate child starts without (a bundle has its own setting for children, such as cost-cap's `child:`), so its recap
+follows config.yml. `/stats` names them on a `settings:` line, and `chi sessions stats --format json` as `settings`.
 
 ## Delegating
 

data/docs/testing.md

@@ -23,6 +23,13 @@ style pass: add a rule only for a bug class it would have caught. It runs in abo
 `rake release:check`; `rake lint` stays RuboCop alone (CI's rubocop job has no node). A name that is also a browser
 global (`name`, `status`, `open`…) passes even when its import is gone: give an export such a name only with care.
 
+CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
+(`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
+to it with `PW_TEST_CONNECT_WS_ENDPOINT`, and traces and the report stay on the runner. Nothing is installed with
+apt. The tag is the installed `@playwright/test`'s version, read at run time, so bumping it in `package-lock.json`
+moves the image too (`spec/ci_playwright_image_spec.rb` keeps a pinned tag out of the workflow). To run the suite
+that way locally: `npx playwright run-server --port 3333`, then `PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:3333/ npm run e2e`.
+
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -35,6 +35,7 @@ module Samagotchi
         @merged_origins = []
         @recap = nil
         @continue_offer = nil
+        @working_set = nil
       end
 
       def call(event)
@@ -192,6 +193,17 @@ module Samagotchi
       end
       private_class_method :with_images
 
+      # The running turn's working set: its last :working_set_updated
+      # ({items:, at:}, Engine#emit_working_set). The session's kept messages
+      # lag the running turn, so this is what a mid-turn read of the set
+      # answers (Web::App#handle_working_set).
+      # @return [Hash, nil] a copy; nil with no turn running, or before the
+      #   turn emitted one (its set is then the session's: the Engine emits
+      #   only a set that differs from the last one)
+      def working_set
+        @mutex.synchronize { @working_set && Marshal.load(Marshal.dump(@working_set)) }
+      end
+
       # @return [String, nil] the last idle recap, until a turn makes it stale
       def recap
         @mutex.synchronize { @recap }
@@ -249,6 +261,7 @@ module Samagotchi
                     parts: [], pending_question: nil }
           @turn[:resumed] = true if event[:resumed]
           @tool_started_at = {}
+          @working_set = nil
           @turn[:images] = event[:images] if event[:images]
           @turn[:cut_after] = event[:cut_after] if event[:cut_after]
         when :input_merged
@@ -261,6 +274,7 @@ module Samagotchi
         if Events::TURN_END.include?(type)
           @turn = nil
           @merged_origins = []
+          @working_set = nil
         elsif event[:event_seq]
           @turn[:event_seq] = event[:event_seq]
         end
@@ -321,6 +335,8 @@ module Samagotchi
           Array(event[:steers]).each do |steer|
             parts << { kind: "steer", iteration: event[:iteration], source: steer[:source].to_s, text: steer[:text].to_s.dup }
           end
+        when :working_set_updated
+          @working_set = { items: event[:items], at: event[:at] }
         when :reminder_injected
           parts << { kind: "reminder", reminders: Array(event[:reminders]).map(&:dup) }
         when :question_requested

data/lib/samagotchi/bridge.rb

@@ -246,7 +246,10 @@ module Samagotchi
     # with its own).
     # The commands queued for after the running turn (queued_commands,
     # TurnAccumulator#queued_commands) too.
-    # @return [Hash] {messages:, current_turn:, queued:, queued_commands:, recap:, saved_recap:, continue_offer:, pending_question:,
+    # working_set: the running turn's last :working_set_updated ({items:,
+    # at:}, TurnAccumulator#working_set), which the messages lag; nil
+    # between turns and before the turn emitted one.
+    # @return [Hash] {messages:, current_turn:, working_set:, queued:, queued_commands:, recap:, saved_recap:, continue_offer:, pending_question:,
     #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:}
     def snapshot
       @engine.synchronize_events do
@@ -254,6 +257,7 @@ module Samagotchi
         {
           messages: @engine.messages_checkpoint,
           current_turn: current_turn_with_generation,
+          working_set: @accumulator.working_set,
           queued: @accumulator.queued,
           queued_commands: @accumulator.queued_commands,
           recap: @accumulator.recap,
@@ -571,10 +575,12 @@ module Samagotchi
 
     # /recap in an attached TUI: the saved recap, and a new one asked for at
     # once (it arrives as :recap_ready). Answers mid-turn too.
-    # 200 {enabled:, saved:, request:, min_user_turns:}. Returns [headers, status, body].
+    # 200 {enabled:, saved:, request:, min_user_turns:}; off, session_off:
+    # whether the session's own setting (/recap off) turned it off.
+    # Returns [headers, status, body].
     def handle_recap(_session_id, _body = nil)
       recap = @engine.recap
-      return [{}, 200, { enabled: false }] unless recap
+      return [{}, 200, { enabled: false, session_off: @engine.recap_override == false }] unless recap
 
       saved = @engine.saved_recap
       [{}, 200, { enabled: true, saved: saved, request: @engine.request_recap.to_s, min_user_turns: recap.min_user_turns }]

data/lib/samagotchi/bundle_command/check.rb

@@ -78,7 +78,7 @@ module Samagotchi
           check_requires_chi(manifest)
           check_trust(manifest)
           check_clash(manifest)
-          check_install(manifest) unless missing || placeholders?
+          check_install(manifest) unless missing || placeholders? || manifest.session_settings_clash
           check_boundary(manifest)
           check_tests
         end
@@ -245,6 +245,10 @@ module Samagotchi
       # Before the sandbox: the user's installed bundles and chi's shipped ones.
       def check_clash(manifest)
         name = manifest.name
+        # A session setting --set would read as chi's own: the install refuses it.
+        if (clash = manifest.session_settings_clash)
+          add(:error, :clash, "manifest.yml", clash, line: manifest_line("session_settings"))
+        end
         shipped = MemoryBundle::Listing.shipped.map(&:name) + [MemoryBundle::SystemBundle::BUNDLE_NAME]
         if shipped.include?(name) && !shipped?
           add(:warn, :clash, "manifest.yml", "chi ships a bundle named #{name}; installing this one replaces chi's",

data/lib/samagotchi/bundle_command/try/command.rb

@@ -2,7 +2,7 @@
 
 require_relative "../../cli/exit"
 require_relative "../../cli/flags"
-require_relative "../../bundle_session_settings"
+require_relative "../../session_config"
 require_relative "../../thinking"
 require_relative "sandbox"
 require_relative "run"
@@ -73,7 +73,7 @@ module Samagotchi
           render = Render.new(stdout: @stdout, stderr: @stderr)
           sandbox = nil
           begin
-            sandbox = Sandbox.new(path, bundle_settings: settings.bundle, cost_cap: settings.cost_cap,
+            sandbox = Sandbox.new(path, settings: settings.bundle, cost_cap: settings.cost_cap,
                                         cost_cap_override: settings.cost_cap_override)
             sandbox.install
             result = Run.new(sandbox).run(prompt: options[:prompt], options: options, timeout: timeout)
@@ -133,7 +133,7 @@ module Samagotchi
           nil
         end
 
-        # The --set KEY=VALUE pairs, typed as BundleSessionSettings.typed:
+        # The --set KEY=VALUE pairs, typed as SessionConfig.typed:
         # cost-cap.cap is the run's cap, the others the tried bundle's.
         # @return [Settings, nil] nil after saying what's wrong
         def parse_settings(pairs)
@@ -143,18 +143,18 @@ module Samagotchi
           pairs.each do |pair|
             key, sep, value = pair.partition("=")
             if key == COST_CAP_KEY && !sep.empty?
-              cost_cap = BundleSessionSettings.typed(value)
+              cost_cap = SessionConfig.typed(value)
               override = true
               next if (cost_cap.is_a?(Numeric) && cost_cap >= 0) || cost_cap == false
 
               @stderr.puts "chi bundle try: --set #{COST_CAP_KEY} takes a non-negative number or off"
               return nil
             end
-            unless !sep.empty? && key.match?(BundleSessionSettings::KEY)
+            unless !sep.empty? && key.match?(SessionConfig::KEY)
               @stderr.puts "chi bundle try: --set takes KEY=VALUE, not #{pair}"
               return nil
             end
-            bundle[key] = BundleSessionSettings.typed(value)
+            bundle[key] = SessionConfig.typed(value)
           end
           Settings.new(bundle: bundle, cost_cap: cost_cap, cost_cap_override: override)
         end

data/lib/samagotchi/bundle_command/try/sandbox.rb

@@ -83,9 +83,9 @@ module Samagotchi
 
         attr_reader :root, :config_home, :state_home, :work_dir
 
-        def initialize(path, bundle_settings: {}, cost_cap: 1, cost_cap_override: false)
+        def initialize(path, settings: {}, cost_cap: 1, cost_cap_override: false)
           @path = File.realpath(path)
-          @bundle_settings = bundle_settings
+          @settings = settings
           @cost_cap = cost_cap
           @cost_cap_override = cost_cap_override
           read_manifest
@@ -153,7 +153,7 @@ module Samagotchi
           data["context"]&.delete("sources")
           data["bundles"] = { "cost-cap" => { "cap" => @cost_cap } }
           data["bundles"][@manifest.name] ||= {}
-          data["bundles"][@manifest.name].merge!(@bundle_settings)
+          data["bundles"][@manifest.name].merge!(@settings)
           data["bundles"]["cost-cap"]["cap"] = @cost_cap if @cost_cap_override
           @layout.write_config(data)
         end

data/lib/samagotchi/bundle_command.rb

@@ -863,17 +863,17 @@ module Samagotchi
       Try::Command.new(stdout: @stdout, stderr: @stderr).run(parsed)
     end
 
-    # --set KEY=VALUE values as typed (BundleSessionSettings.typed), or nil
+    # --set KEY=VALUE values as typed (SessionConfig.typed), or nil
     # after saying what's wrong.
     def check_settings(pairs, label:)
-      require_relative "bundle_session_settings"
+      require_relative "session_config"
       pairs.each_with_object({}) do |pair, out|
         key, sep, value = pair.partition("=")
-        unless !sep.empty? && key.match?(BundleSessionSettings::KEY)
+        unless !sep.empty? && key.match?(SessionConfig::KEY)
           @stderr.puts "chi bundle #{label}: --set takes KEY=VALUE, not #{pair}"
           return nil
         end
-        out[key] = BundleSessionSettings.typed(value)
+        out[key] = SessionConfig.typed(value)
       end
     end
 

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

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

data/lib/samagotchi/commands/registry.rb

@@ -96,6 +96,10 @@ module Samagotchi
       end
       private_class_method :listed_mid_turn
 
+      # A name is taken once, with one exception: core may give a name two
+      # entries, one the UIs run (local) and one the session runs, each with
+      # its own match (/recap shows in a UI, /recap off runs in the worker).
+      # #listing then has the name twice, /help and Tab once.
       # @param anytime [Boolean] mid_turn: :anytime (a bundle's command)
       # @param mid_turn [Symbol, #call, nil] see Entry; nil takes +anytime+
       # @param match [#call, nil] the default matches the name alone or the
@@ -104,7 +108,7 @@ module Samagotchi
       # @return [Entry]
       def register(name, description, id: nil, anytime: false, mid_turn: nil, local: false, uis: nil, match: nil,
                    source: "core", annotations: [], &handler)
-        raise ArgumentError, "command #{name} is already registered" if @entries.any? { |entry| entry.name == name }
+        raise ArgumentError, "command #{name} is already registered" unless name_free?(name, local: local, source: source)
 
         entry = Entry.new(id: id || name.delete_prefix("/").to_sym, name: name, description: description,
                           mid_turn: mid_turn || (anytime ? :anytime : :refuse), local: local, uis: uis, match: match || default_match(name),
@@ -203,6 +207,13 @@ module Samagotchi
         @entries << entry
       end
 
+      def name_free?(name, local:, source:)
+        taken = @entries.select { |entry| entry.name == name }
+        return true if taken.empty?
+
+        source == "core" && taken.size == 1 && taken.first.source == "core" && !taken.first.local != !local
+      end
+
       def default_match(name)
         after = /\A#{Regexp.escape(name)}\s/
         ->(text) { text == name || after.match?(text) }

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
@@ -308,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).
@@ -324,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
 
@@ -342,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
 
@@ -406,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)
@@ -523,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
@@ -545,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
 
@@ -555,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