samagotchi 0.102.0 → 0.104.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '084d47c40205bd43fa1126dd3169a0792cc6faee949899bf6b62d84a559d1501'
-  data.tar.gz: 23dde4e086c819fc43349cb20afed56121fb51bfb3b54b9be6e90fd8a332003b
+  metadata.gz: f4a794e9e201d233ca72705b62746997d6ef702804e18ad8a5bb1f85851ed454
+  data.tar.gz: 341e3b0cfcbc4367faed3782d600b2d934395eef7623499619f018b1984a06db
 SHA512:
-  metadata.gz: 763b8db4ab722ec994871d8d5e4e1238beda7ae846c9cf8bf5f9dc0f2c8d545eb767b7d82afcf35a8cb096f2f30461a8a793068c5359d5c926a7209e626c91b9
-  data.tar.gz: abb0665762926a27e66133b5326cf8b18658e5404047d9f1ce414c6455ac3ddffa15667c00ab6a6ad929a9d15d451f667ad11b702d08bccb9fa9053161415a5b
+  metadata.gz: 20bdcd9c915786fe5698401079a36e676ace823d4e42625c5b75fd2472d9990b342f1cc9c23e2a609bffee3b57df88c4fb9b6c927cdf0e182c1f7966fc5fde37
+  data.tar.gz: 64d05e8f627bb8c628e3510681b7acf1de4c37995175333614094d00333f66b1de28d91a6b2819f005e4d1e5150c8ffd189f6c9e2379044b89268188086231e6

data/CHANGELOG.md

@@ -8,6 +8,96 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.104.0] - 2026-10-23
+
+### Added
+
+- Remote attach: `chi --remote NAME --attach ID` (and `--resume ID`, `-p TEXT`, or `--dir DIR` for a new session
+  there, that machine's absolute path) runs the attached TUI on another machine's session, through its chi web:
+  the same lines and exit codes, every printed command spelled with `--remote NAME`, `@path` images from this
+  machine, a "(reconnecting…)" / "(reconnected)" line for about a minute of reconnects, and the version line naming
+  both machines. `--non-interactive`, `--verbose`, `--no-shared`, `--memory`, `--mute` and
+  `--append-system-prompt` stay this machine's (exit 2). `--dir` without `--remote` exits 2. `/exit`,
+  `/exit --delete`, `/archive`, `/stats` and `/recap` work through a remote as here, the status row counts the
+  session's delegates there, and a join shows the steps' durations and a failed turn's line from that machine's
+  saved records. See [docs/cli.md](docs/cli.md#remote-sessions).
+- Participants (experimental: identity only, the review itself comes in a later release): `chi share ID --name NAME
+  [--agent] [--expires 3d]` invites someone, or an agent, to review a session through chi web on the LAN with a link
+  of their own, printed once with a QR code (chi keeps only a digest of its token). `chi share ls [ID]` lists
+  participants and `chi share revoke ID [P] | --all` ends links; all three work through `--remote`. A link works for 7
+  days (1 hour to 30 days), until it is revoked, or until the session is archived or deleted. For now it opens a page
+  with the session's title and status; every other route answers it 403, and another session 404. chi web refuses to
+  start when another user can read its grants store. Through `--remote`, a revoked, expired or participant's token
+  gets its own message instead of "the token was refused". See [docs/cli.md](docs/cli.md#participants).
+- The bundle test kit (experimental) waits with `wait_for(what) { … }`, which raises
+  `Samagotchi::Testing::Waiting::TimedOut` naming what it waited for (and, with `seen:`, what it last saw), plus
+  `join!` and `pop!` with the same message. Every helper deadline is multiplied by `SPEC_TIME_SCALE` (default 1).
+  See [docs/plugins.md](docs/plugins.md#testing-a-bundle-experimental).
+
+### Changed
+
+- The bundle test kit's `wait_until!` is renamed `wait_for`, with no alias: a bundle spec that calls
+  `wait_until!` changes the name (same arguments).
+
+### Fixed
+
+- `chi --attach ID` (and `--resume ID`, and `chi --remote NAME --attach ID`) right after `/exit`, while the leaving
+  worker still writes its recap, waits for it with `(waiting for the session to finish its recap…)` (up to
+  `recap.timeout` plus 5 s) and then attaches, instead of failing "did not start its Bridge in time". A Ctrl-C while
+  an attach connects exits 130 without a backtrace.
+- `/queue TEXT` (or `/cut TEXT`) with no turn running says `(nothing is running: sent now)` in the REPL and the
+  attached terminal, instead of sending without a word.
+- The ctx % no longer dips at the start of each turn on a chat host (`api: openai` / `anthropic`): the turn's first
+  estimate, made before the host counts anything, left out the tool schemas; it now uses the last count's chars per
+  token.
+- Attached terminal: a command typed right after the text `/unqueue` put back in the input (`/unqueue` again,
+  `/queue TEXT`) runs as the command, with the text kept in the input, instead of going out joined to the text as
+  one prompt.
+- `chi --remote NAME sessions stop` waits up to 10 s there for the worker to let go, as `chi sessions stop` does
+  here (chi web waited 2 s, so a slow worker read "still shutting down" more often); the page's Stop still waits 2 s.
+- The terminal's status line, cut to the terminal's width, ends at a word with `…` instead of mid-word (in a pipe
+  too).
+
+Update with `chi update`.
+
+## [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 +3944,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.102.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.104.0...HEAD
+[0.104.0]: https://github.com/dm1try/samagotchi/compare/v0.103.0...v0.104.0
+[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
@@ -53,6 +52,8 @@ SUBCOMMANDS = {
   "send" => ["samagotchi/send_command", "SendCommand"],
   # answer the question a session waits on, then wait (--question, --option)
   "answer" => ["samagotchi/answer_command", "AnswerCommand"],
+  # invite participants to review a session, list them, revoke them
+  "share" => ["samagotchi/share_command", "ShareCommand"],
   # find a model server and write config.yml (--model, --name)
   "bootstrap" => ["samagotchi/bootstrap_command", "BootstrapCommand"],
   # bring an installed chi up to date
@@ -64,8 +65,31 @@ 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. Run flags under a
+# remote (--attach, --resume, -p, --dir: a session there in this terminal)
+# are parsed below and go to RemoteAttachCommand before this machine's
+# checks; the local-only ones are refused here.
+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)
+remote_attach = remote_run.remote? && !remote_run.here? && remote_run.run_flags?
+if remote_attach && (refusal = remote_run.refusal)
+  warn "Error: #{refusal}"
+  exit 2
+end
+exit remote_run.run(SUBCOMMANDS) if remote_run.remote? && !remote_run.here? && !remote_attach
+
 if (path, klass = SUBCOMMANDS[ARGV[0]])
   require path
   exit Samagotchi.const_get(klass).new(ARGV[1..] || []).run
@@ -76,185 +100,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
@@ -313,6 +162,29 @@ Samagotchi::Config.reload!(cli_overrides: cli_overrides) unless cli_overrides.em
 require "samagotchi/log"
 Samagotchi::Log.configure(level: options[:verbose] ? :debug : nil, mirror: options[:verbose])
 
+# chi --remote NAME --attach ID (--resume ID, --dir DIR, -p TEXT): the
+# attached TUI on that machine's session. Nothing below runs: it checks
+# this machine's sessions, memories and files.
+if remote_attach
+  unless ARGV.empty?
+    warn "Error: unknown command #{ARGV.first} (see chi --help)"
+    exit 1
+  end
+  require "samagotchi/remote_attach_command"
+  begin
+    entry = Samagotchi::Remotes.find(Samagotchi::Remotes.check_name!(remote_run.remote))
+  rescue Samagotchi::Remotes::Invalid => e
+    warn "Error: #{e.message}"
+    exit 2
+  end
+  exit Samagotchi::RemoteAttachCommand.new(options, access: Samagotchi::SessionAccess::Remote.new(entry)).run
+end
+# --dir names a folder on a remote; here the session starts in this one.
+if options[:dir]
+  warn "Error: --dir goes with --remote; cd there instead"
+  exit 2
+end
+
 # `chi web`: its flags (--port, --open, --web-view…) went through the parser above.
 options[:web] = true if web
 
@@ -360,7 +232,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 +349,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
@@ -508,6 +373,10 @@ if launch == :attached
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
+  rescue Interrupt
+    # Ctrl-C while it connects (a wait for a leaving worker, a late Bridge):
+    # no backtrace.
+    exit Samagotchi::CLI::Exit::INTERRUPTED
   end
   exit Samagotchi::TerminalUI::AttachLauncher.exit_status(ended)
 end

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.
 
@@ -464,7 +469,8 @@ Every route goes through `Bridge#dispatch`: an id other than the bridge's own se
 The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
 for client discovery. `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
 (503 `not_live` when the worker is not running; full history of any session is served by
-`GET /api/sessions/:id/output`). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
+`GET /api/sessions/:id/output`), as a byte pipe for the owner: `App#proxy_stream_body` gives `ProxyStreamBody` the
+request principal's frame filter (`App#stream_filter`, nil for the owner, the only principal today). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
 an earlier worker gets the `reset` snapshot, not a replay.
 
 **Session hub.** The cross-session layer (which sessions exist, who owns them, what changed)
@@ -499,6 +505,65 @@ 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`). Every `ROUTES` row also names who may use it, checked against
+the request's `Web::Principal` (`App#principal_for`): `owner`, or `participant` for a route a participant may use too.
+A participant (a `Web::Grants` token for one session) may use three: `GET /`, `GET /api/info` and `GET /api/sessions/:id`,
+each answered as theirs; every other route is `owner` (Permission below, and the participants routes in
+[internals/participants.md](internals/participants.md)); `spec/web/principal_spec.rb` fails on a row without one. How a request flows end to end, which checks run where and the trust
+model: [internals/remote-sessions.md](internals/remote-sessions.md).
+
+| Route | Permission | Body / params | Answer | Refusals |
+|---|---|---|---|---|
+| `GET /api/sessions/resolve?id=` | owner | an id or a unique prefix | 200 `{id}` | 404 `not_found`; 400 `ambiguous_id` with `ids` |
+| `GET /api/sessions/summaries` | owner | `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) | owner | `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) | owner | `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` | owner | `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` | owner | `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` | owner | `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) | owner | `{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` | owner | `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` | owner | | 200 `{status: detached}`: the session's own only | 409 `project_source` (chi context rm's words); 404 |
+| `POST /api/sessions/:id/stop` | owner | `wait?` (seconds, capped at `SessionManager::STOP_WAIT`, 10: `chi --remote NAME sessions stop` sends it) | 200 `{status: stopped, session_id, released}`: `released`, whether the worker let go within the wait (without one `STOP_WAIT_SECONDS`, 2 s: the page's Stop) | 409 `owned_by_tui` |
+| `DELETE /api/sessions/:id?force=` | owner | `force=true` stops a live worker first (the page sends it) | as before | 409 `worker_running` without it |
+| `GET /api/sessions/:id?brief=1` | participant (theirs: title, status, participants) | | 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) | owner | | 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` | owner | | 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` | owner | `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` | owner | | 200 `{session_id, live, stopped, owner: worker \| tui \| null, worker: {epoch, started_at, version, features} \| null, default_model, parent_strategy}` (`Local#worker`; never starts one; `default_model` is this machine's) | 404 |
+| `POST /api/sessions/:id/exit` | owner | `client_id` (passed on only when it is an attached TUI's, `tui:…`; any other is dropped), `delete` | 200 the worker's `{status: exiting, session_id, discard}` (`BridgeClient#request_exit`; never wakes one) | 409 `held` with the worker's `{status, reason, tasks, hint}`; 503 `not_live`; 501 `not_supported`; 504 `worker_timeout` |
+| `POST /api/sessions/:id/recap` | owner | | 200 the worker's `{enabled, saved, request, min_user_turns, session_off}` (`BridgeClient#request_recap`) | 503, 501, 504 as every relay |
+| `GET /api/sessions/:id/stats` | owner | | 200 `{session_id, metrics}`: the worker's stats, its state's metrics for a worker from before the stats route | 503 `not_live`; 504 `worker_timeout`; 502 `bridge_error` |
+| `GET /api/sessions/:id/children/counts` | owner | | 200 `{running, waiting, unreported}` (`ChildrenStatus.counts`, the delegates' files here) | 404 |
+| `GET /api/sessions/:id/turns/:turn_id/records` | owner | | 200 `{tool_records: […], turn_record: {…} \| null}` (`SessionMetrics.saved_tool_records` / `saved_turn_record`, as saved) | 400 `invalid_turn_id`; 404 |
+| `POST /api/sessions/:id/turn` (`no_interrupt`) | owner | `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) | owner | | | 501 `not_supported` for a builtin the worker lacks adds `command` (`"/title"`) and `message` |
+| `GET`/`POST`/`DELETE /api/sessions/:id/participants`, `GET`/`DELETE /api/participants` | owner | `chi share`'s (`name`, `kind`, `ttl`; `?id=p_…`) | the grants, never a token but POST's own once ([internals/participants.md](internals/participants.md)) | 400 `invalid_participant`; 404 |
+
+`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 routes a remote attached TUI needs: wake, worker, exit, recap, stats,
+children counts and a turn's records. Their refusals carry `{error, detail, message}`.
+
+`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 +684,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)). |