samagotchi 0.101.0 → 0.103.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c75329bad389a0434a3f99db7d05d512a45864aa3ce08ecb8a6a7399bddbe33
-  data.tar.gz: c057af30d62ee4f72bf0b681c10edb0bd0bf5225e14a3e1470f4b0d726bbaf67
+  metadata.gz: 7c4a19357a9f5c94b3c76052abc018a034968ad8baf3520d50ace0ab581943b6
+  data.tar.gz: ec637848fd8dc33b292d836618753699bc8159962c6051d7b9b669beb31eb50f
 SHA512:
-  metadata.gz: d2324f636a992fe36e2c0250ed55cf979b574359fd7e0f67271ceaf8da0803ffd60fc70408d62c73af984a2f9310b6acbfef92bbaac61a6c272e20540e38c840
-  data.tar.gz: cffd6a4d948302b563f1e30cf5542be9db7e95a68cc07a97cdb2b81e008454f7fe605f8bb96946c6b43c0fccd1957d05ea764867fde4f976f4699f242d8897fe
+  metadata.gz: 5ca1a63b9c68e9b18b21fb2f2bf6503eb3cec3368e10410c4efce78dc5a853e842fc8ddd74bb5387d21f6b0d38c69f4abdb58a5320bf5c9e8272232ebf56234c
+  data.tar.gz: 7c86172b9193fc68c5c639989573c17f99af9621d118624684ace1483628a01cde8e609c2438368c297e534043fb86a165e94511e34dfd880171d77f2a75eb57

data/CHANGELOG.md

@@ -8,6 +8,70 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.103.0] - 2026-10-23
+
+### Added
+
+- Remote sessions: `chi --remote NAME send|answer|note|context|sessions …` (or `CHI_REMOTE=NAME`) runs the session
+  commands against another machine's sessions, through its `chi web --web-host lan`. `chi remote add NAME URL
+  --token-file FILE` checks the address and token and saves the remote (`chi remote ls`, `chi remote rm`).
+  `send --new` there needs `--dir`, a folder on that machine; what runs on this machine only (attach, `sessions
+  stats`, `context mute`, `broadcast`, …) is refused with exit 2. The next-step commands it prints (`chi answer …`,
+  `chi send --wait …`) carry `--remote NAME`; where chi points at `chi --attach` here it names that machine's chi web.
+  See [docs/cli.md](docs/cli.md#remote-sessions).
+- `/working-set pin KEY…` keeps an item from the model's `forget_outputs`: its reads, those to come too, stay
+  whole until `/working-set unpin KEY…`. `/working-set add KEY…` brings an item in: the next turn's line asks the
+  model to read it first (one tool call; what it reads is an ordinary read); `/working-set unadd KEY…` takes an
+  add back before then. In the web's working set list (still experimental, `web.working_set: true`), rows offer
+  `pin` / `unpin`, `+` adds an item, and a stale or forgotten row offers a refresh. See [docs/cli.md](docs/cli.md).
+
+### Changed
+
+- The guardrails bundle (0.9.3) asks for `chi --remote NAME context add --cmd …` and `chi --remote NAME broadcast`
+  as it does without `--remote`. Update with `chi update`.
+- claude-peer (0.4.2): `pair` through a remote (`CHI_REMOTE`, or `--remote NAME` in `CHI`) attaches only
+  `claude-outbox` and says chi there can't send to that Claude. Update with `chi update`.
+- codex-peer (0.3.3): the same for `pair` through a remote: it attaches only `codex-outbox`, says chi there can't
+  send to that Codex, and when chi can't reach the remote names Codex's sandbox `network_access` setting as a
+  possible cause. Update with `chi update`.
+- chi web's `POST /api/sessions/:id/stop` also answers `released`; `DELETE /api/sessions/:id` takes `force` (the
+  page sends it). Both are additive.
+
+### Fixed
+
+- The web's stage shrinks back when you close its steps list by hand, instead of keeping its grown height.
+- `/working-set`: a `memory_read` of several names is dropped, pinned or added as a whole (the reply names the
+  others); a quoted KEY keeps its spaces, in the TUI and the web; a file in the session's folder is shown by its
+  relative path.
+- The idle recap's summarize thread ends quietly, logged, on a failure.
+- On Linux a worker stops at once (not ~0.5 s later), and its address is gone before its streams end, so an attached UI follows a restarted worker straight away.
+
+## [0.102.0] - 2026-10-23
+
+### Added
+
+- `/working-set` lists the session's working set as the model has it: each file, memory and URL its turns read,
+  edited or fetched, with its state (`stale`, `forgotten`, `dropped`) and its size as sent. `/working-set drop KEY…`
+  takes an item out of what the model is sent (its reads go as a stub saying you dropped it, under any LLM context
+  strategy); `/working-set undrop KEY…` sends it whole again. A change applies from the next turn. In the web's
+  working set list (still experimental, `web.working_set: true`), rows offer `drop` / `undrop`; mid-turn they wait
+  for the turn's end, with an `undo`. See [docs/cli.md](docs/cli.md).
+- `--set` takes chi's own session settings too: `--set recap.enabled=false` or `--set recap.sentences=3` for this
+  session, over config.yml. A bad value or a key no session sets is an error (exit 2). See
+  [docs/configuration.md](docs/configuration.md#per-session-settings).
+- `/recap on|off|default` turns the idle recap on or off for this session, at once and in any UI (mid-turn too);
+  saved with the session.
+
+### Changed
+
+- `POST /api/sessions`: the field `bundle_settings` is now `settings` (it takes core keys too). No alias.
+- An attached TUI started before this release treats `/recap off` as the plain `/recap`; restart it.
+
+### Fixed
+
+- The web's working set no longer keeps the last item when the set is emptied, and a reply to an older request can
+  no longer overwrite a newer one.
+
 ## [0.101.0] - 2026-10-22
 
 ### Added
@@ -3828,7 +3892,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.101.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.103.0...HEAD
+[0.103.0]: https://github.com/dm1try/samagotchi/compare/v0.102.0...v0.103.0
+[0.102.0]: https://github.com/dm1try/samagotchi/compare/v0.101.0...v0.102.0
 [0.101.0]: https://github.com/dm1try/samagotchi/compare/v0.100.1...v0.101.0
 [0.100.1]: https://github.com/dm1try/samagotchi/compare/v0.100.0...v0.100.1
 [0.100.0]: https://github.com/dm1try/samagotchi/compare/v0.99.0...v0.100.0

data/bin/chi

@@ -8,7 +8,6 @@ $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "samagotchi/utf8_default"
 Samagotchi::Utf8Default.apply!
 
-require "optparse"
 require "samagotchi/config"
 
 begin
@@ -64,8 +63,23 @@ SUBCOMMANDS = {
   # list and remove memories (ls, rm; --scope, --format)
   "memory" => ["samagotchi/memory_command", "MemoryCommand"],
   # install, upgrade, uninstall, status, diff, list, build (--scope, --force, …)
-  "bundle" => ["samagotchi/bundle_command", "BundleCommand"]
+  "bundle" => ["samagotchi/bundle_command", "BundleCommand"],
+  # other machines' chi web, for chi --remote NAME (add, ls, rm)
+  "remote" => ["samagotchi/remote_command", "RemoteCommand"]
 }.freeze
+# chi --remote NAME <command> (or CHI_REMOTE=NAME): the session commands
+# against another machine's chi web; what runs here only is refused (exit 2).
+# chi remote, --version and --help run here as always.
+require "samagotchi/session_access/dispatch"
+begin
+  remote_run = Samagotchi::SessionAccess::Dispatch.from(ARGV)
+rescue Samagotchi::SessionAccess::Dispatch::Usage => e
+  warn "Error: #{e.message}"
+  exit 2
+end
+ARGV.replace(remote_run.argv)
+exit remote_run.run(SUBCOMMANDS) if remote_run.remote? && !remote_run.here?
+
 if (path, klass = SUBCOMMANDS[ARGV[0]])
   require path
   exit Samagotchi.const_get(klass).new(ARGV[1..] || []).run
@@ -76,183 +90,10 @@ end
 scratch = ARGV[0] == "scratch"
 ARGV.shift if scratch
 
-# no_interrupt / no_default_input start from config.yml or the env; the flags below turn them on.
-options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt"), non_interactive: false, no_default_input: Samagotchi::Config.get("no_default_input"), web: false, web_port: nil, web_open: false, web_markdown: nil }
-cli_overrides = {}
-
-# Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
-known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
-ARGV.each do |arg|
-  next unless arg.start_with?("--") && arg.include?("_")
-
-  # Allow --no-interrupt etc. already dash; underscore is always rejected for config flags
-  # We check raw ARGV before OptionParser normalizes
-  base = arg.split("=", 2).first
-  # If dashed version is a known flag (registry or hardcoded), reject underscore variant
-  dashed = base.tr("_", "-")
-  if known.include?(dashed) || known.include?(base)
-    warn "Unknown option: #{arg} (did you mean #{dashed}?)"
-    exit 1
-  end
-end
-
-parser = OptionParser.new do |opts|
-  opts.banner = <<~BANNER
-    Usage: chi [options]
-           chi bootstrap [HOST[:PORT]|URL]  first setup: find the model server, write config.yml
-           chi scratch [options]            a one-time session in this terminal: nothing is kept
-           chi web [--port PORT] [--open] [--scope=all]   the web UI
-           chi sessions <list|stop|restart|archive|unarchive|delete|prune|clean|stats>
-           chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
-           chi broadcast [-m TEXT] [--all] [--dry-run] | log | deliver   a note for every session it may concern
-           chi context <add|push|ls|show|refresh|rm|mute|unmute>   live external text attached to sessions
-           chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
-           chi answer ID --question QID --option N   answer a question a session waits on
-           chi memory <ls|rm> [--scope project|system]   the memories; rm moves one to the bundle trash
-           chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
-           chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
-           chi models [--format json] [TEXT]   the models --model takes, from every host
-           chi self                         version, paths, model and bundles
-           chi update [--dry-run]           update this chi, its bundles and the desktop helper
-    (each subcommand takes --help)
-
-  BANNER
-  opts.on("-p", "--prompt PROMPT", "Run PROMPT as the first turn, then stay in the REPL") { |p| options[:prompt] = p }
-  opts.on("--resume SESSION_ID", "Resume a previous session by its ID (or a unique prefix of it)") { |s| options[:resume] = s }
-  opts.on("--attach SESSION_ID", "Attach to a session's worker, waking one if it has exited; ID or a unique prefix") { |s| options[:attach] = s }
-  opts.on("--[no-]shared", "Run the session in a background worker and attach to it, so `chi web` can share it (the default, config session.shared; with --resume: that session); --no-shared runs a plain in-process REPL") { |v| options[:shared] = v }
-  opts.on("--model NAME", "Model for this run, not saved (overrides --resume's; config default.model) [env SAMAGOTCHI_DEFAULT_MODEL]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
-  opts.on("--profile NAME", Samagotchi::ModelProfile::NAMES,
-          "Prompt profile for every model in this run (#{Samagotchi::ModelProfile::NAMES.join("|")}) [alias for --model-profile]") { |p| cli_overrides["model.profile"] = p }
-  opts.on("--thinking LEVEL", Samagotchi::Thinking::LEVELS.map(&:to_s), "This session's own thinking level: off|low|medium|high|default (saved in the session, " \
-                              "before the model's; default unsets it; /thinking changes it). With chi web: the default for the sessions " \
-                              "its workers run, below a session's own [env SAMAGOTCHI_THINKING_LEVEL]") { |l| options[:thinking] = l }
-  opts.on("--toolkit NAME", "This session's toolkit, the tools its prompts declare: full|lean|child|a config or bundle one " \
-                           "(saved in the session; config toolkit.default; /toolkit changes it)") { |n| options[:toolkit] = n }
-  opts.on("--tool NAME", "Also declare this tool on top of the toolkit (repeatable; a comma list too)") { |t| (options[:tools] ||= []) << t }
-  # --no-tool is taken out of ARGV before parse! (OptionParser would read it
-  # as --tool's negation); this is its help line.
-  opts.separator "        --no-tool NAME               Leave this tool out of the toolkit (repeatable; a comma list too)"
-  opts.on("--set BUNDLE.KEY=VALUE", "A bundle setting for this session, over config.yml's bundles: (repeatable; a key the " \
-                                  "bundle's manifest lists in session_settings:; numbers and booleans (true, off, no) are typed, the rest is " \
-                                  "text; a value of the wrong type is refused; saved in the session: --set cost-cap.cap=3)") do |v|
-    (options[:sets] ||= []) << v
-  end
-  opts.on("--parent-answers LEVEL", "What a parent agent may answer on this session's questions: " \
-                                    "hard|standard|soft, only stricter than config.yml's guardrails.parent_answers (saved in the " \
-                                    "session; only you loosen it, with /parent-answers in the terminal or the web)") do |v|
-    options[:parent_answers] = v
-  end
-  opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
-  opts.on("--append-system-prompt FILE", "Put FILE's text into the system prompt, after AGENTS.md (repeatable; saved in the session; " \
-                                        "config append_system_prompt: is the baseline)") { |f| (options[:append_system_prompt] ||= []) << f }
-  opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
-  opts.on("--llm-context LAYERS", "This session's own LLM context strategy: none, or layers such as stale,forget (saved in the session, " \
-                                 "before the model's; /llm-context changes it)") { |v| (options[:llm_context] ||= {})[:strategy] = v }
-  opts.on("--llm-context-apply RULE", "This session's own apply rule for it: payoff|next_request|turn_end") { |v| (options[:llm_context] ||= {})[:apply] = v }
-  opts.on("--llm-context-budget TOKENS", "This session's own context budget: tokens (64000, 64k) or off") { |v| (options[:llm_context] ||= {})[:budget_tokens] = v }
-  opts.on("--no-interrupt", "Raise the tool call limit to 1000 iterations (useful for long tasks)") { options[:no_interrupt] = true; cli_overrides["no_interrupt"] = true }
-  opts.on("--non-interactive", "Run a single prompt and exit (no REPL, implies --no-interrupt)") { options[:non_interactive] = true }
-  opts.on("-v", "--verbose", "Print raw LLM responses and tool calls/results (runs a plain REPL, not attached)") { options[:verbose] = true }
-  opts.on("--no-default-input", "Skip default REPL input prefill") { options[:no_default_input] = true; cli_overrides["no_default_input"] = true }
-  opts.on("--port PORT", "Port for `chi web` (default: 4567, env SAMAGOTCHI_WEB_PORT)") { |p| options[:web_port] = p.to_i; cli_overrides["web.port"] = p.to_s }
-  opts.on("--open", "Open browser for `chi web`") { options[:web_open] = true }
-  opts.on("--new-token", "`chi web`: replace the LAN access token (web.host: lan); links and QR codes made with the old one stop working") { options[:new_token] = true }
-  opts.on("--scope VALUE", %w[project all],
-          "Which sessions `chi web` and `chi sessions list` show: project (the default: this folder's git project; " \
-          "every session outside a repo) or all") { |v| options[:scope] = v }
-  # Accepted values of string entries that the registry doesn't type as enums.
-  value_hints = { "status.line" => "on|off", "web.host" => "127.0.0.1|::1|localhost|lan|IP", "recap.sentences" => "N|N-M",
-                  "web.annotate_presets" => "text|text", "web.editor" => "vscode|vscode-insiders|cursor|zed|none|URL" }
-  # Universal config flags (implicit convention: ENV SAMAGOTCHI_* ↔ YAML dotted ↔ CLI --kebab)
-  # Generated from Samagotchi::Config registry — Option A: snake leaf in YAML, kebab in CLI.
-  Samagotchi::Config.cli_entries.each do |entry|
-    next if %w[no_interrupt no_default_input].include?(entry.key)
-    next if entry.key == "web.port" # already handled as --port
-    next if entry.key == "default.model" # alias --model above
-    next if entry.key == "web.markdown" # handled below with explicit inverse flags
-
-    case entry.type
-    when :bool
-      # --[no-]: a bool that defaults to on is only useful switched off.
-      opts.on("--[no-]#{entry.cli_flag.delete_prefix("--")}", "Set #{entry.key} (bool, default #{entry.default ? "on" : "off"}) [env #{entry.env_key}]") { |v| cli_overrides[entry.key] = v }
-    when :integer, :float, :string, :enum
-      desc = "Set #{entry.key} [env #{entry.env_key}]"
-      desc += " (#{entry.enum_values.join("|")})" if entry.type == :enum
-      desc += " (#{value_hints[entry.key]})" if value_hints.key?(entry.key)
-      desc += "; only without a hosts: config" if %w[server.host server.port].include?(entry.key)
-      if entry.type == :enum
-        opts.on("#{entry.cli_flag} VALUE", entry.enum_values, desc) { |v| cli_overrides[entry.key] = v }
-      else
-        opts.on("#{entry.cli_flag} VALUE", desc) { |v| cli_overrides[entry.key] = v }
-      end
-    end
-  end
-  opts.on("--web-markdown", "Render finalized LLM Markdown in `chi web` (requires optional commonmarker gem)") { options[:web_markdown] = true; cli_overrides["web.markdown"] = true }
-  opts.on("--no-web-markdown", "Disable Markdown rendering in `chi web`") { options[:web_markdown] = false; cli_overrides["web.markdown"] = false }
-  # Strict underscore rejection: --recap_base_url etc. are not registered and will raise OptionParser::InvalidOption
-  opts.on("--version", "Print chi's version") { puts "chi #{Samagotchi::VERSION}"; exit }
-  opts.on("-h", "--help", "Show help") { puts opts; exit }
-end
-# --no-tool NAME (or --no-tool=NAME), up to a "--". A flag that takes a
-# value (-p, --model …: the parser's own list) keeps its next word, so
-# `chi -p "--no-tool=x is broken"` is a prompt. A tool name never starts
-# with "-": `--no-tool --` or `--no-tool --model` is a missing argument.
-switches = parser.instance_variable_get(:@stack).flat_map { |list| list.list }
-                                          .select { |switch| switch.is_a?(OptionParser::Switch) }
-switch_flags = switches.flat_map { |switch| switch.long + switch.short }
-known_flags = (known + switch_flags).uniq
-takes_value = switches.select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }
-                      .flat_map { |switch| switch.long + switch.short }
-reject_prompt_flag = lambda do |flag, value|
-  if known_flags.include?(value)
-    warn "Error: #{flag} needs the prompt text right after it (got the flag #{value}) (see chi --help)"
-    exit 2
-  end
-end
-index = 0
-while index < ARGV.size && ARGV[index] != "--"
-  arg = ARGV[index]
-  if %w[-p --prompt].include?(arg)
-    reject_prompt_flag.call(arg, ARGV[index + 1])
-    index += 2
-  elsif arg.start_with?("--prompt=")
-    reject_prompt_flag.call("--prompt", arg.delete_prefix("--prompt="))
-    index += 1
-  elsif arg.start_with?("-p") && arg != "-p"
-    reject_prompt_flag.call("-p", arg.delete_prefix("-p").delete_prefix("="))
-    index += 1
-  else
-    index += takes_value.include?(arg) ? 2 : 1
-  end
-end
-missing_no_tool = lambda do
-  warn "Error: missing argument: --no-tool (see chi --help)"
-  exit 1
-end
-index = 0
-while index < ARGV.size && ARGV[index] != "--"
-  arg = ARGV[index]
-  if arg == "--no-tool"
-    value = ARGV[index + 1]
-    missing_no_tool.call if value.nil? || value.start_with?("-")
-    (options[:no_tools] ||= []) << ARGV.delete_at(index + 1)
-    ARGV.delete_at(index)
-  elsif arg.start_with?("--no-tool=")
-    value = arg.delete_prefix("--no-tool=")
-    missing_no_tool.call if value.empty? || value.start_with?("-")
-    options[:no_tools] = (options[:no_tools] || []) << value
-    ARGV.delete_at(index)
-  else
-    index += takes_value.include?(arg) ? 2 : 1
-  end
-end
-begin
-  parser.parse!
-rescue OptionParser::ParseError => e
-  warn "Error: #{e.message} (see chi --help)"
-  exit 1
-end
+# The run flags (RunOptions: the parser and its checks); what is left in
+# ARGV is `web` or a stray word.
+require "samagotchi/run_options"
+options, cli_overrides = Samagotchi::RunOptions.parse(ARGV)
 
 # The subcommands with their own parsers ran above; what parse! leaves is
 # `web` or nothing. Anything else is a typo, not a prompt: refuse it rather
@@ -358,7 +199,8 @@ end
   end
   next unless leftover
 
-  warn "Error: that's a leftover scratch session; it is deleted at the next sweep (chi sessions clean)"
+  require "samagotchi/launch_mode"
+  warn "Error: #{Samagotchi::LaunchMode::SCRATCH_LEFTOVER}"
   exit 1
 end
 
@@ -435,13 +277,14 @@ if options[:toolkit] || options[:tools] || options[:no_tools]
                                                            remove: options[:no_tools])
 end
 
-# --set BUNDLE.KEY=VALUE: a new session's bundle settings, checked here
-# against the installed bundles (a typo isn't saved).
+# --set KEY=VALUE / BUNDLE.KEY=VALUE: a new session's own settings, checked
+# here (a core key against its Config entry, a bundle's against the installed
+# bundles), so a typo isn't saved.
 if options[:sets]
-  require "samagotchi/bundle_session_settings"
+  require "samagotchi/session_config"
   begin
-    options[:bundle_settings] = Samagotchi::BundleSessionSettings.from_flags(options[:sets])
-  rescue Samagotchi::BundleSessionSettings::Error => e
+    options[:settings] = Samagotchi::SessionConfig.from_flags(options[:sets])
+  rescue Samagotchi::SessionConfig::Error => e
     warn "Error: #{e.message}"
     exit 2
   end
@@ -473,15 +316,7 @@ launch, launch_note = if scratch
 warn launch_note if launch_note
 
 if launch == :attached
-  conflict = { non_interactive: "--non-interactive", verbose: "--verbose" }
-             .find { |key, _flag| options[key] }
-  error = if options[:attach] && options[:shared]
-            "use either --attach ID or --shared"
-          elsif options[:attach] && options[:resume]
-            "--attach takes the session id; --resume goes with --shared"
-          elsif conflict
-            "--attach/--shared can't be combined with #{conflict.last}"
-          end
+  error = Samagotchi::LaunchMode.attached_conflict(options)
   if error
     warn "Error: #{error}"
     exit 1
@@ -500,7 +335,7 @@ if launch == :attached
                                                        appended_prompt_files: options[:appended_prompt_files] || [],
                                                        toolkit: options[:toolkit_value],
                                                        toolkit_flags: options[:toolkit_flags] || [],
-                                                       bundle_settings: options[:bundle_settings] || {},
+                                                       settings: options[:settings],
                                                        parent_answers: options[:parent_answers])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
@@ -523,7 +358,7 @@ begin
     appended_prompt_files: options[:appended_prompt_files] || [],
     toolkit: options[:toolkit_value],
     toolkit_flags: options[:toolkit_flags] || [],
-    bundle_settings: options[:bundle_settings] || {},
+    settings: options[:settings],
     parent_answers: options[:parent_answers],
     non_interactive: options[:non_interactive],
     model_name: options[:model],

data/docs/architecture.md

@@ -125,6 +125,11 @@ terminal renders the events it gets over the Bridge.
 - `bin/chi web` → builds `Web::Server` (Rack+WEBrick on `127.0.0.1:4567`, `--port`/`SAMAGOTCHI_WEB_PORT`, `--open`;
   `web.host: lan` adds a LAN address, `--new-token` replaces its access token).
 - `bin/chi sessions {list,stop,restart,archive,unarchive,delete,prune,clean,stats}` (`SessionsCommand`; not the REPL's `SessionCommands`) → retention & ordering (`SessionRetention`, `updated_at desc`, dry-run, test-only); `stop` is `SessionManager.stop_session(wait:)`, which waits for the worker to release `owner.lock`; `delete` (`SessionDeleteCommand`) is `SessionManager.delete_session(stop:)`, which the TUI's `/exit --delete` and the web's `DELETE /api/sessions/:id` use too.
+- Session commands (`chi send`, `answer`, `note`, a session's `context`, `sessions list/stop/restart/archive/unarchive/delete`) →
+  `SessionAccess` (`session_access.rb`): what they ask of a session goes through one backend object,
+  `SessionAccess::Local` (`session_access/local.rb`) on this machine's files and workers; a `--wait`'s pre-send state
+  (cursor, baseline, own turn) is `prepare_wait`'s `WaitStart`. `SessionAccess::Contract` lists which commands and flags
+  run against a remote and which on this machine only.
 - In REPL mode `TerminalUI` builds the `Engine` in process (`-p` and `--non-interactive` too);
   otherwise the session's `Worker` (`lib/samagotchi/worker.rb`, spawned by `SessionManager`) builds it.
 
@@ -311,7 +316,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   refused connection is `503 not_live`.
 - `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
 - `POST /session/:id/recap` — `/recap` in an attached TUI: `200 {enabled, saved, request,
-  min_user_turns}` (`{enabled: false}` without recaps); a new recap is asked for at once and
+  min_user_turns}` (`{enabled: false, session_off}` without recaps; `session_off` when the session's own
+  `/recap off` turned it off); a new recap is asked for at once and
   arrives as `:recap_ready`. Answers mid-turn too.
 - `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
   answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
@@ -446,10 +452,11 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
 - `?cards=1`: the cards, from `/tail`; the session file is only stat'ed for the 404.
 
 The stage view's working set (`web.working_set`) has its own read, `GET /api/sessions/:id/working_set`: the
-`WorkingSet` projection (`{items, at}`: each file, memory and URL live, stale or forgotten, with its tokens) of the
-worker's `/snapshot` messages, else the session file, under the session's LLM context strategy. Its live form is the
-`:working_set_updated` event. The page overlays it on the set it builds from its tool rows
-([internals/working-set.md](internals/working-set.md)).
+`WorkingSet` projection (`{items, at, running}`: each file, memory and URL live, stale or forgotten, with its tokens)
+of the worker's `/snapshot` messages, else the session file, under the session's LLM context strategy; while a turn
+runs, the snapshot's `working_set` (the running turn's last event, which the messages lag) when it has one. Its live form
+is the `:working_set_updated` event, which always wins over a GET's answer it overtook. The page overlays it on the
+set it builds from its tool rows ([internals/working-set.md](internals/working-set.md)).
 
 A worker without `/tail` (an older chi; `404 not_found`) is read through `/snapshot` in the same
 shape; any other failure (no worker, a 500, a timeout) reads the disk, trimmed to the newest
@@ -497,6 +504,54 @@ names its `chi_version` too.
 `GET /api/sessions` is the hub's projection too (its sort, paging and total). `Server` always builds
 a hub; an `App.new` without one answers both routes `503 no_hub`.
 
+**chi web's routes for the session commands.** chi's session commands (`chi send`, `answer`, `note`, a session's
+`context`, `sessions list/stop/restart/archive/unarchive/delete`) run against another machine's sessions through its
+chi web (the remote-sessions plan; `SessionAccess::Contract` says which commands and flags may). The page's routes
+cover most of it; `Web::SessionAccessRoutes` (`web/session_access_routes.rb`, in `App`'s `ROUTES`) adds the rest, each
+calling the `SessionAccess::Local` operation of the same name, so a remote backend maps 1:1 onto them. Every one is
+token-gated like the rest (LAN mode: `Authorization: Bearer`), and one that takes an id is a `:session` route (an id
+that isn't one, or no such session: 404 `not_found`). How a request flows end to end, which checks run where and the trust
+model: [internals/remote-sessions.md](internals/remote-sessions.md).
+
+| Route | Body / params | Answer | Refusals |
+|---|---|---|---|
+| `GET /api/sessions/resolve?id=` | an id or a unique prefix | 200 `{id}` | 404 `not_found`; 400 `ambiguous_id` with `ids` |
+| `GET /api/sessions/summaries` | `dir` (a folder: its project; none: every project), `cwd`, `live=1`, `archived=1`, `tests=0`, `sort`, `order`, `limit` | 200: the rows `chi sessions list` prints (`SessionManager.session_summaries`: `status`, `live`, `busy`, `owner`, `recap`, `ctx_pct`, `waiting`, `waiting_id`, `title`, `preview`, …) | 400 `invalid_dir`, `invalid_cwd` |
+| `POST /api/sessions` (more fields) | `toolkit`, `tools`, `no_tools`, `parent_answers`; `client_id` (`cli:send`/`cli:answer`: the first line is checked as chi send checks it); `check_vision: true` (images follow) | 201 adds `model_warning` and `parent_answers_warning` (a level looser than config.yml's, capped) | 400 `invalid_toolkit`, `invalid_parent_answers`, `invalid_continues` (beside `continues`); 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
+| `POST /api/sessions/:id/turn` (more fields) | `client_id` as above; `check_vision: true` with `images` | as before | 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
+| `POST /api/sessions/:id/wait/prepare` | `question_id` (absent: the pending one; `null`: none), `turn`, `created`, `busy` (+ `queue`) | 200 `{session_id, cursor, baseline: {messages, question_id, last_turn}, own_turn, known_turn, running, live, settled, last_turn_id}` (`WaitStart`) | 409 `busy`, `waiting` (`SendCommand::Busy`'s words, and its fields: `question`, `parent_strategy`) |
+| `POST /api/sessions/:id/wait` | `cursor`, `baseline`, `turn`, `queued`, `ended_before`, `owner_grace`, `timeout` (capped at 30 s) | 200: `ReplyWait::Result`'s fields (`status`: `done`, `waiting_for_answer`, `no_reply`, `error`, `stopped`, `worker_gone`, or `timeout`: ask again; `text`, `file`, `question` as `PendingQuestion#to_file`, `outcome`, `limit`, `error_kind`, `retryable`, `cancel_reason`, `stopped_by`, `kept_steps`, `turn_id`, `origin`; never the session) and `parent_strategy` `{name, allowed, origin}` (`ParentReport.strategy_for`, this server's config.yml) | 400 `invalid_wait`; 503 `server_stopping` |
+| `POST /api/sessions/:id/notes` | `text`, `source` (default `cli`, never `broadcast`) | 200 `{status: queued \| waits, session_id, queued}` (`NoteDelivery`) | 409 `owned_by_tui` (`status: refused`); 400 `note_rejected`, `missing_fields`, `invalid_source` |
+| `POST /api/sessions/:id/context` (more bodies) | `{name, push: true, why, hint}` or `{name, cmd, every, why, hint}` beside the page's `{url, why, hint}`; `added_by` `cli`/`agent` (else `web`) | 201 `{status: attached, name}` | 400 `invalid_source`; 409 `exists` |
+| `POST /api/sessions/:id/context/:name/push` | `text`, `summary`, `wake`, `hint` (a source's JSON output, checked the same way) | 200 `{status: pushed, name, before, revision, changed}` | 404 `not_found`; 409 `not_push`; 400 `invalid_text` |
+| `DELETE /api/sessions/:id/context/:name?own=1` | | 200 `{status: detached}`: the session's own only | 409 `project_source` (chi context rm's words); 404 |
+| `POST /api/sessions/:id/stop` | | 200 `{status: stopped, session_id, released}`: `released`, whether the worker let go within `STOP_WAIT_SECONDS` (2 s) | 409 `owned_by_tui` |
+| `DELETE /api/sessions/:id?force=` | `force=true` stops a live worker first (the page sends it) | as before | 409 `worker_running` without it |
+| `GET /api/sessions/:id?brief=1` | | 200 `{brief, session: {id, status (the file's), title, display_title, project_root, working_directory, model_name, model_typed, parent_answers, owner}, pending_question}` (the file's; no messages): `Remote#show` | 404 |
+| `POST /api/sessions/:id/turn` (its 202) | | the ack with `via`: `bridge` or `file` (the input file: a remote `chi send --wait` follows that turn) | |
+| `GET /api/sessions/:id/context?full=1`, `…/context/:name?full=1` | | each row with `source` (`Source#to_h`, its command too; the page's rows never carry one), `snapshot` (`Snapshot#to_h`, no text) and `shadowed`, shadowed project sources included | |
+| `POST /api/sessions/:id/wake` | `wait` (seconds, default and most 10: `WAKE_MAX_WAIT`) | 200 `{session_id, woke, worker: {epoch, started_at, version, features}, model_name, default_model, parent_strategy, installed}`: the live worker as is (`woke: false`), else resumed and its Bridge waited for (`Local#wake`); `default_model` and `installed` are this machine's | 409 `owned_by_tui`, `scratch` (`LaunchMode::SCRATCH_LEFTOVER`); 504 `worker_timeout` (`LaunchMode::BRIDGE_LATE`); 400 `invalid_wait`; 404 |
+| `GET /api/sessions/:id/worker` | | 200 `{session_id, live, stopped, owner: worker \| tui \| null, worker: {epoch, started_at, version, features} \| null, parent_strategy}` (`Local#worker`; never starts one) | 404 |
+| `POST /api/sessions/:id/turn` (`no_interrupt`) | `no_interrupt: true`: the turn runs with the raised iteration limit (`SessionManager.deliver_turn(no_interrupt:)`, to the Bridge or the input file) | as before | |
+| `POST /api/sessions/:id/command` (its 501) | | | 501 `not_supported` for a builtin the worker lacks adds `command` (`"/title"`) and `message` |
+
+`GET /api/info` names the feature `session_commands` (`SessionAccessRoutes::FEATURE`): `SessionAccess::Remote` asks it
+once before its first request, and a chi web without it (or `serve_static`'s 404 for a path no route takes) is "remote NAME runs chi X, too
+old for this command through --remote: update chi there (chi update)". The feature `remote_attach`
+(`SessionAccessRoutes::ATTACH_FEATURE`) names the wake and worker routes a remote attached TUI needs.
+
+`POST …/answer` passes on `client_id` only when it is chi answer's (`cli:answer`), so the worker holds the answer to
+its `guardrails.parent_answers`; any other is dropped, so a forwarded id can only tighten. The worker's 403
+`parent_answer_refused` (with `reason`) and a dismissal's 409 `not_dismissable` pass through; a 408 (the worker read it
+past its deadline) is sent once more, as `SessionAccess::Local#answer` does, and a second is `504 worker_timeout`.
+
+A refusal an exception raises carries, next to `error` and `detail` (the page's words), `message` (the exception's own,
+verbatim) and the fields its class is built from, so a remote client raises the same class with the same text:
+`owned_by_tui` (`session_id`), `worker_running`/`still_stopping` (`DeleteRefused`: `session_id`, `reason`), `busy`/
+`scratch` (`ArchiveRefused`: `session_id`, `reason`, `busy_id`), a restart's `held`/`not_running`/`unsupported`/
+`failed` (`RestartRefused`: `session_id`, `reason`, `version`), a continue's `continued`/`open_children`/`folder_gone`
+(`SessionContinue::Refused`: `session_id`, `reason`, `ids`) and `ambiguous_id` (`Session::AmbiguousId`: `ids`).
+
 ## Model loops and adapters
 
 A model ref (`--model`, `/model`, `default.model`, an alias's target) is parsed
@@ -609,7 +664,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Paths | `paths.rb` (`Paths`) | The XDG base dirs chi's files live under, read from the env on every call: `Paths.state_home` (`$XDG_STATE_HOME`, else `~/.local/state`) and `Paths.config_home` (`$XDG_CONFIG_HOME`, else `~/.config`), both defaults under `Dir.home`; a blank variable counts as unset, a relative one is made absolute from the current directory. `Paths.tilde` shows a path with `~` for the home folder. `SessionManager` hands a spawned worker the spawner's `XDG_STATE_HOME` / `XDG_CONFIG_HOME`, when set, made absolute, so a relative one isn't read from the session's folder. |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
 | Bundle authoring | `bundle_command.rb` (`BundleCommand`), `bundle_command/{scaffold,check,test_run}.rb`, `bundle_command/try/{run,sandbox,trace}.rb`, `testing.rb` + `testing/` (the test kit) | `chi bundle new`, `check`, `test` and `try`, and the kit a bundle's tests load it with ([bundle-authoring.md](bundle-authoring.md), [internals/bundles.md](internals/bundles.md)). |
-| Bundle session settings | `bundle_session_settings.rb` (`BundleSessionSettings`) | A session's own `--set BUNDLE.KEY=VALUE` values, checked against the manifest's `session_settings:`, laid over `bundles: <name>:` in `ctx.settings` ([plugins.md](plugins.md)). |
+| Session config (`--set`) | `session_config.rb` (`SessionConfig`, `SessionConfig::Settings`) | A session's own settings as one value (`Session#settings`, `SessionSetup#settings`): `core`, the `--set KEY=VALUE` values of the core keys marked `session: true` (`Config::Entry`), typed by `Config.coerce!` and read first through `Config.get(key, session:)` (`RecapSetup`; `Engine#session=` rebuilds the recap job, `IdleScheduler#replace_job`), file key `config_settings`; `bundles`, the `--set BUNDLE.KEY=VALUE` values, checked against the manifest's `session_settings:`, laid over `bundles: <name>:` in `ctx.settings` ([plugins.md](plugins.md)), file key `bundle_settings`. `SessionConfig.clash` refuses a bundle setting named like a core one (install, `chi bundle check`). See [configuration.md](configuration.md#per-session-settings). |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb`, `plugin/context.rb` (`ctx`), `plugin/http.rb` + `plugin/http_transport.rb` (`ctx.http`), `plugin/card.rb` (`Plugin::Card`) | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources; what its handlers get as `ctx` ([plugins.md](plugins.md)). |
 | Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([plugins.md](plugins.md#the-claude-peer-bundle)). |
 | Shipped bundles | `bundles/` (`mcp`, `github-pr`, `loop-guard`, `skills`, `source-links`, …) | Bundles that ship with chi. |
@@ -617,6 +672,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/data_readers.rb`, `guardrails/rules.rb`, `guardrails/protected_paths.rb`, `guardrails/parent_policy.rb` + `guardrails/parent_approvals.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing (and the commands that only read a heredoc as data), YAML rules, the core checks on chi's own files, approvals, what a parent agent may answer (`guardrails.parent_answers`) ([guardrails.md](guardrails.md)). |
 | Delegation | `tools/delegate.rb`, `tools/delegate_result.rb`, `tools/delegate_wait.rb`, `child_reports.rb`, `tools/delegate_relay.rb`, `relay_desk.rb`, `relay_verifier.rb`, `relay_watcher.rb` | Child sessions a session starts and waits on, and their approval relay ([sessions.md](sessions.md#delegating)). |
 | send / broadcast | `send_command.rb` (`SendCommand`), `broadcast_command.rb` (`BroadcastCommand`), `broadcast/` | `chi send` and `chi broadcast` ([broadcast.md](broadcast.md), [sub-agent.md](sub-agent.md)). |
+| Session access | `session_access.rb` (`SessionAccess`: `NewSession`, `SetupWords`, `WaitStart`, `SessionView`, `Created`, `ContextEntry`, `ContextPush`, the errors `RemoteFailed`, `RemoteTooOld`, `Refused`, `BadRequest`), `session_access/local.rb` (`SessionAccess::Local`), `session_access/remote.rb` (`SessionAccess::Remote`), `session_access/http_transport.rb`, `session_access/web_bridge_client.rb` (`SessionAccess::WebBridgeClient`, a remote attach's worker through chi web), `session_access/dispatch.rb` (`SessionAccess::Dispatch`), `session_access/contract.rb` (`SessionAccess::Contract`), `remotes.rb` (`Remotes`), `remote_command.rb` (`chi remote`), `web/session_access_routes.rb` (`Web::SessionAccessRoutes`) | The seam between the session commands and where the sessions live: `Local` is this machine's (the `SessionManager`, `ReplyWait`, `NoteDelivery`, `ContextSources` and Bridge calls the commands made); `Remote` is another machine's, the same methods as requests to its chi web's routes of the same name (Bearer token, `HTTPTransport`), results as Local's value objects and refusals as the classes Local's callees raise, built from the fields chi web sends; waits and prefixes run on the server, a wait asked again per 30 s slice. `Dispatch` is bin/chi's front for `--remote NAME` / `CHI_REMOTE` (taken off before the subcommand lookup): it refuses what the contract table lists `local_only` (exit 2, one message) and runs the command with a `Remote` on the `Remotes` entry (`$XDG_CONFIG_HOME/samagotchi/remotes.yml`, 0600). chi web's routes answer from `Local` (*chi web's routes for the session commands* above). Checks that read this machine's config or files (vision, parent answers, the cwd's project, `SAMAGOTCHI_PARENT_SESSION`) stay in the commands and are skipped under a `Remote`, where chi web's create, turn and wait routes run the vision, parent-answers and busy checks with the server's config and the worker checks a parent's answer. See [internals/remote-sessions.md](internals/remote-sessions.md). |
 | Idle work | `idle_scheduler.rb` (`IdleScheduler`), `idle_recap.rb` (`IdleRecap`), `idle_reminders.rb` | One poller for an idle session's recap and reminders. |
 | Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |