samagotchi 0.102.0 → 0.103.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '084d47c40205bd43fa1126dd3169a0792cc6faee949899bf6b62d84a559d1501'
-  data.tar.gz: 23dde4e086c819fc43349cb20afed56121fb51bfb3b54b9be6e90fd8a332003b
+  metadata.gz: 7c4a19357a9f5c94b3c76052abc018a034968ad8baf3520d50ace0ab581943b6
+  data.tar.gz: ec637848fd8dc33b292d836618753699bc8159962c6051d7b9b669beb31eb50f
 SHA512:
-  metadata.gz: 763b8db4ab722ec994871d8d5e4e1238beda7ae846c9cf8bf5f9dc0f2c8d545eb767b7d82afcf35a8cb096f2f30461a8a793068c5359d5c926a7209e626c91b9
-  data.tar.gz: abb0665762926a27e66133b5326cf8b18658e5404047d9f1ce414c6455ac3ddffa15667c00ab6a6ad929a9d15d451f667ad11b702d08bccb9fa9053161415a5b
+  metadata.gz: 5ca1a63b9c68e9b18b21fb2f2bf6503eb3cec3368e10410c4efce78dc5a853e842fc8ddd74bb5387d21f6b0d38c69f4abdb58a5320bf5c9e8272232ebf56234c
+  data.tar.gz: 7c86172b9193fc68c5c639989573c17f99af9621d118624684ace1483628a01cde8e609c2438368c297e534043fb86a165e94511e34dfd880171d77f2a75eb57

data/CHANGELOG.md

@@ -8,6 +8,44 @@ 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
@@ -3854,7 +3892,8 @@ 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.102.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

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,185 +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 KEY=VALUE", "A setting for this session, saved in it (repeatable): a core key a session may set " \
-                             "(recap.enabled, recap.sentences; typed by the key, over CLI, env and config.yml), or BUNDLE.KEY over " \
-                             "config.yml's bundles: (a key the bundle's manifest lists in session_settings:; numbers and booleans " \
-                             "(true, off, no) are typed, the rest is text). A wrong key or value is refused: " \
-                             "--set recap.enabled=false, --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
@@ -360,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
 
@@ -476,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

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.
 
@@ -499,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
@@ -619,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)). |

data/docs/cli.md

@@ -21,6 +21,8 @@
 - `chi context <add|push|ls|show|refresh|rm|mute|unmute> …` — attach live external text to sessions (a command chi runs every so often, or text pushed in); the model gets a short note when it changes and reads it with `context_read`; `chi context add <URL>` attaches a GitHub PR with the github-pr bundle (see [Attached context](context.md))
 - `chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one takes it at its next step; `--cut` asks it to cut long thinking for it; `--queue` runs it as a turn of its own after the running one, and `--queue --wait` waits for that turn's own answer); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead (`--new --continues ID|last:ID` the next link of that session's chain, see [Session chains](sessions.md#session-chains)), and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending — to an idle session whose last turn already ended, that ended turn's reply or end comes back; `--wait --turn T ID` with no message waits for exactly turn T, whether running, queued or last ended; `--format json` includes its `turn_id` when known, for waiting again after exit 3 or 4; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). What a parent may pick follows `guardrails.parent_answers`, or the session's own `parent_answers` when stricter (`soft`, the default: a deny, a plain answer, Continue and "Allow once"; `standard`: no allow; `hard`: no Continue either), never a wider scope or an allow on chi's own config; a refused pick exits 1 with what to answer instead (a convention, not a security boundary; see [Guardrails](guardrails.md#answers-from-a-parent-agent))
+- `chi remote add NAME URL [--token-file F | --token-stdin]`, `chi remote ls`, `chi remote rm NAME` — the other machines whose chi web the session commands reach with `--remote NAME` (see [Remote sessions](#remote-sessions))
+- `chi --remote NAME send|answer|note|context|sessions …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
 - `chi memory ls [--scope project|system] [--format text|json]` — the memories of both scopes (this folder's project first), one row each: scope, name, size, date, `from <bundle>`, the index description and its model overlays; `chi memory rm NAME [--scope project|system]` removes one as `memory_write` with `remove: true` does: its file and model overlays go to the bundle trash (the line names the dir; `chi bundle trash` lists and empties it) and its index line is dropped. NAME in both scopes without `--scope` exits 2 naming both; a missing NAME or a bundle's memory (`chi bundle uninstall` removes it) exits 1 (see [Memory: Listing and removing from the shell](memory.md#listing-and-removing-from-the-shell))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
@@ -278,6 +280,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--shared` | Run the session (new, or `--resume`'s) in a background worker and attach to it: the default, and the way to get it when `session.shared` is off. See [Sharing a session](#sharing-a-session). |
 | `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
+| `--remote NAME` | Before a session command (`chi --remote studio send …`): run it against that remote's sessions, through its chi web; beats `CHI_REMOTE`. Commands and flags that run on this machine only exit 2. See [Remote sessions](#remote-sessions). |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
 | `--toolkit NAME`, `--tool NAME`, `--no-tool NAME` | A new session's toolkit, the tools its prompts declare: `full` (every built-in), `lean`, `child`, one of config's `toolkit.kits` or a bundle's (without `--toolkit`: config's `toolkit.default`), with tools declared on top of it (`--tool`) or left out (`--no-tool`); both repeatable, a comma list too. Saved in the session as given; a respawned worker, a fork and a continue keep it. Ignored with `--attach`/`--resume` (one line, as `--memory`); `/toolkit` changes it. Not on `chi web` (config's `toolkit.default` covers its sessions). See [Toolkits](configuration.md#toolkits). |
@@ -611,16 +614,39 @@ KEY…` takes an item out of what the model is sent: every read of it still sent
 goes as a stub, `(dropped by the user) — read it again if the task needs it`,
 whatever the LLM context strategy (none too), and stays dropped across a
 strategy switch. KEY is a path (absolute or the session folder's), `memory:NAME`
-or a URL. `/working-set undrop KEY…` sends it whole again. A change applies
+or a URL; quote one with spaces (`"my notes/a b.md"`, as the listing shows it). `/working-set undrop KEY…` sends it whole again. A change applies
 from the next turn's first request, which also carries one line telling the
 model what you dropped or brought back (so it doesn't read it again by reflex);
 the reply says what it frees and the tail the server reads again (a drop changes
 history, so the prompt cache breaks there once). An undrop before that request
 undoes the drop for free. Refused, with why: an item only edited or written
 (nothing of it to drop), one not in the set, an older session's output chi
-can't name. The model can't undo a drop (`forget_outputs` refuses it).
-`/working-set` alone answers mid-turn too; `drop`/`undrop` sent while a turn
-runs wait for the turn's end.
+can't name. The model can't undo a drop (`forget_outputs` refuses it). One
+`memory_read` of several names is one output: dropping, undropping or pinning
+one name acts on that read whole, so on the others too, and the reply names
+them (`; the same memory_read holds memory tone: dropped with it`).
+`/working-set pin KEY…` keeps an item from the model's `forget_outputs` (the
+[forget layer](configuration.md#llm-context-the-forget-layer)): it refuses every
+read of it, those to come too, until `/working-set unpin KEY…`. A pin sends
+nothing different (no cache break) and is saved with the session, so a respawn,
+a continue and a fork keep it, across a strategy switch too; under a strategy
+without forget it waits until one has it (the reply says so). The listing marks
+it `pinned`, and under forget the next turn's line tells the model. A pinned
+item can't be dropped until you unpin it; a pin takes back a drop not yet sent
+(free), and asks you to undrop one already sent first.
+`/working-set add KEY…` brings an item in: the next turn's line asks the
+model to load it before anything else (`read` for a file, `memory_read` for
+`memory:NAME`, `web_fetch` for an http(s) URL), so it costs the model one tool
+call, and what it reads is an ordinary read (droppable, forgettable, in the
+set). Nothing is sent until then, and `/working-set unadd KEY…` takes an add
+back for free. On a stale or forgotten item it is a refresh (the model reads
+it again). Refused, with why: a file that isn't there (or a directory), a
+memory neither scope holds, a URL that isn't http(s), an item the model is
+sent whole now, a dropped one (undrop it instead), one already added. The
+listing's last line names the pending adds (`added lib/tax.rb`). The model is
+asked, not forced: a model may skip the read.
+`/working-set` alone answers mid-turn too; `drop`/`undrop`/`pin`/`unpin`/`add`/`unadd`
+sent while a turn runs wait for the turn's end.
 
 `/thinking` shows the thinking level the next turn runs at and where it came
 from (`session`, `--thinking` / `SAMAGOTCHI_THINKING_LEVEL`, `models: <key>`,
@@ -1009,13 +1035,26 @@ turn view ignores it.
   scope, `prompt` for a preloaded memory) that goes to the call. A file opens
   as its row's title does, a URL in a new tab. A row (on hover or keyboard
   focus) and a folded group offer `drop`, which runs `/working-set drop` (see
-  `/working-set` above); a dropped row offers `undrop`. Between turns it
+  `/working-set` above); a dropped row offers `undrop`, and so does one whose
+  drop holds on some reads only (`part dropped` in `/working-set`'s listing:
+  an older read stubbed by the stale layer, or a newer read sent). Between turns it
   applies at once; while a turn runs it waits for the turn's end: the row is
   dashed with `drops next turn` and an `undo`, and the list's foot counts the
-  pending changes (`undo all`), in every tab and after a reload. On a phone a
+  pending changes (`undo all`), in every tab and after a reload; the stage's
+  rail dashes the item's line too (its tooltip says `drops next turn`). On a phone a
   tap on a row opens its actions under it. `drop` is greyed, with why on
   hover, for an item only edited, a memory only preloaded, or one already
-  forgotten.
+  forgotten. Under a strategy with forget a row also offers `pin`
+  (`/working-set pin`, pending as `applies next turn` mid-turn); a pinned row
+  shows `📌` and `unpin` (under any strategy), and its `drop` is greyed until
+  you unpin it.
+  The list's foot (a phone's last row) takes a path, `memory:NAME` or a URL
+  and runs `/working-set add`: the item shows as a dashed `+ name` row with
+  `reads next turn` and an `undo` until the next turn starts (the model is then
+  asked to read it, and it joins the set as the model reads it). A stale or
+  forgotten row offers `refresh`, the same add of it. While a turn runs the
+  stage's rail shows an add queued for its end as a dashed `+ name · next turn`
+  line.
 
 Only `read`, `edit`, `write`, `memory_read`, `memory_write` and `web_fetch`
 calls that succeeded count; files an `execute` touched don't.
@@ -1031,6 +1070,8 @@ the same live, after a reload and in every tab:
 - **dropped** (struck): you dropped it (`/working-set drop`, the list's
   `drop`); its reads are sent as stubs under every strategy until you undrop
   it.
+- **pinned** (`📌`): you pinned it (`/working-set pin`, the list's `pin`);
+  `forget_outputs` refuses it.
 - **forgotten** (struck): nothing of the item's content is still sent to the
   model under the session's current LLM context strategy (`forget_outputs`
   forgot every read of it; see
@@ -1113,6 +1154,72 @@ access token", paste the token there (the part of the link after
 - On http the browser has no notifications: the bell is hidden on the phone,
   and the tab title still counts what needs you.
 
+### Remote sessions
+
+The session commands also reach another machine's sessions, through its chi
+web on the LAN: the sessions, workers, memories and code stay there. On the
+other machine (the Studio), run `chi web --web-host lan`; on this one (the
+laptop), add it once with its token (the part of its LAN link after
+`token=`, or its `$XDG_STATE_HOME/samagotchi/web-token` file):
+
+```sh
+chi remote add studio http://192.168.1.29:4567 --token-file studio-token
+# studio  http://192.168.1.29:4567  chi 0.103.0, LAN 192.168.1.29
+chi --remote studio send --new --dir /Users/me/projects/app --wait -m "fix the flaky spec"
+chi --remote studio answer ab12 --question q1 --option 1
+CHI_REMOTE=studio chi context push claude-outbox ab12 < answer.json
+```
+
+- `chi remote add NAME URL` checks the address and token first (`GET
+  /api/info`) and says what it found: the chi it runs and its LAN address, or
+  why not: nothing answers (start chi web there with `web.host: lan`), the
+  token was refused, or a hostname (chi web answers its LAN IP only: use the
+  IP, which changes with the Wi-Fi), or a chi too old for remote sessions.
+  Nothing is saved then. The remotes live in
+  `$XDG_CONFIG_HOME/samagotchi/remotes.yml` (0600), their tokens inside: a
+  token runs commands as you there. `chi remote ls` (`--format json`) never
+  prints one; `chi remote add` of an existing name replaces it.
+- `--remote NAME` goes before the command (`chi --remote studio note …`),
+  `CHI_REMOTE=NAME` in the environment does the same for every command a
+  script runs; the flag beats the variable, and there is no default remote.
+  An unknown name exits 2.
+- What runs there: `send` (every form: `--new`, `--wait`, `--queue`,
+  `--cut`, `--image`, a session command), `answer`, `note`, a session's
+  `context add|push|ls|show|rm` and `sessions
+  list|stop|restart|archive|unarchive|delete`. The rest runs on this machine
+  only and exits 2 with `chi <command> runs on this machine only: run it on
+  <remote>`: `context refresh|mute|unmute` and `--project`, `sessions
+  stats|prune|clean`, `broadcast`, the machine's own commands (`bundle`,
+  `memory`, `update`, …) and a session in this terminal (`--attach`, `-p`,
+  `--resume`: remote attach comes later). `chi remote`, `--version` and
+  `--help` always run here.
+- `send --new` needs `--dir`, that machine's absolute path (no folder of this
+  one is guessed); `--toolkit`, `--set` and `--parent-answers` are checked
+  against that machine's config and bundles. `sessions list` lists every
+  project's sessions there (`--scope=project --cwd DIR` one project's) in the
+  `--live` text form. `context` takes the session ids (no default session),
+  and a URL resolves through that machine's bundles.
+- That machine's config.yml decides what it checks for `send` and `answer`:
+  a parent agent's `/continue yes` and options (`guardrails.parent_answers`),
+  a loosening `/parent-answers`, images to a model that can't see them. Each
+  target refuses its own (`ab12  refused: …`), where this machine refuses
+  before sending to any.
+- Waits run on the server, 30 s at a time, until the answer or your own
+  `--timeout`; exit codes are the same. The commands chi prints for what to
+  do next work as pasted: they carry `--remote NAME` (`chi --remote studio
+  answer ab12 --question q1 --option N`, `chi --remote studio send --wait …`),
+  under `CHI_REMOTE` too. What runs on this machine only isn't offered:
+  where chi says `chi --attach ID` here it names that machine's chi web
+  (`chi web on studio shows it`), and `sessions stop` names no `chi
+  --resume`.
+- A remote that can't be reached names itself and why (`chi send: remote
+  studio (http://192.168.1.29:4567): connection refused`, exit 1; with
+  `--format json` an `error` object).
+- Plain http, the same as the phone's: use it on your home network.
+
+How it works inside (`SessionAccess`, chi web's routes, where each check runs):
+[internals/remote-sessions.md](internals/remote-sessions.md).
+
 ## Runtime Model Switch (Assist Mode)
 
 In interactive assist mode, you can switch the request model without restarting:

data/docs/configuration.md

@@ -1485,7 +1485,13 @@ models:
   forget keeps lines of it; a keep outside the output's lines, of a big file's head/tail preview, or holding all of
   it; an output too small for a stub to free anything; one already stubbed or forgotten; an unknown id, or one whose
   output chi can't pair with its call for sure (it shows no id). The system prompt, user messages, steers and context
-  notes have no ids.
+  notes have no ids. An output you dropped, or one of an item you pinned, is refused too (`dropped by the user`,
+  `pinned by the user: it stays in your context`).
+- **Pins.** `/working-set pin KEY…` (or the web list's `pin`, shown under forget only) keeps an item from the model's
+  forget: every read of it, those to come too, until `/working-set unpin KEY…` (see [cli.md](cli.md#the-working-set)).
+  It sends nothing different, so the prompt cache holds. The pins are the session's own (`working_set_pins` in the
+  session file): a respawned worker, a continue and a fork keep them, across a strategy switch too; a delegate child
+  starts without. Stale stubs still apply to a pinned file's superseded reads (its newer read is sent).
 - **When stubs reach the prompt** follows `llm_context.apply`, as `stale`'s do: the result says
   `applied, the next request sends the stubs (frees …)` or `staged until the turn ends`.
 - **Restore.** `forget_outputs(restore: ["t45"])` brings a forgotten output back with the next request, whatever

data/docs/guardrails.md

@@ -582,7 +582,8 @@ hooks, approvals, bundles or attached context sources, or a `.git/hooks`
 (`shell-touches-chi`, `touches: chi_dirs`), unless they only read
 (`skip_read_only`); `chi context add … --cmd` (`chi-context-cmd`, once at a
 time: a command chi will run every few minutes outside the guardrails; see
-[Attached context](context.md#safety)); `chi broadcast` (`chi-broadcast`,
+[Attached context](context.md#safety); the rule also sees `chi --remote NAME context add`, and a remote's `context push`
+reaches its session with the trust of its chi web token, as your own `chi context push` does there); `chi broadcast` (`chi-broadcast`,
 once at a time and only by the user: it is the user's command, which also
 refuses to run inside a session; see [Broadcast](broadcast.md)); removing a
 memory with `memory_write remove: true` (`memory-remove`, once at a time: