samagotchi 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9668c1088aa3739aa60890e07c7d04cf41fb87debf9683b6cd42b6e6e61ee265
-  data.tar.gz: ecfd58cc93c0dee8d867936c75754f854da34cf436dce28fcbc442e7f61c6ec2
+  metadata.gz: 760138c7792d414a15c39e074c5a6dc0ad44dfd0937c12707c3e6428a3544d43
+  data.tar.gz: d347cc3e3d7433292c40484beb73b95e2e3a9efb48ecd5ba5168b3c562c8d7e2
 SHA512:
-  metadata.gz: cd2b82ad80038fb47d35a7b76177312521548a61764963697bebe2cb3b5389fd2d604debba118a87bca43077f2f350b7a0c5f63878df73c5ad75382951246ca0
-  data.tar.gz: ef64847c760b05f8b6ee084fcd39b0ffc2595de21538c388ee7dc8c37f59a952bf4f55b2cf8db8df8187cf4600dd890e996bb94473a9af4e3e99a8cef8ed48af
+  metadata.gz: ae3585c68672ad0b163448b92c83e9f2d60dbc5efd60c47090170d80750ad20a08a5eae97aebf0dbc57629909db228de565a6a3a00ccb40bff9757ea66c3aeff
+  data.tar.gz: 4330ef708fe3ebc22f30e4cf249f88fb68a870eb1afd3be9894822e8e819ca25d393b34ffbabf56ef23ee784016b7cdcae9014d709f42db31fac88f501048ddb

data/CHANGELOG.md

@@ -8,6 +8,119 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-02
+
+### Added
+
+- The web marks a session that waits for you: its card gets a warn border, a pulsing dot and a `question`,
+  `approval` or `needs you` badge, and it moves to the top of the strip and the all-sessions view until answered
+  (the order holds while the pointer is over the list).
+- `models.<key>.window_tokens` and `hosts.<name>.window_tokens` in config.yml set a model's or a host's context window
+  for when the server and its model list report none (the model's wins over the host's, and both over
+  `context.window_tokens`); the server's `n_ctx` still wins over all of them.
+
+### Fixed
+
+- chi starts under `LC_ALL=C` (or another US-ASCII locale): `chi -p` crashed with `Encoding::CompatibilityError` while
+  building the system prompt from a memory index with non-ASCII text. chi and its workers read their files as UTF-8
+  whatever the locale.
+- The `mcp` bundle (0.4.0, `chi update`) attaches an image an MCP tool names inside its text
+  (`Saved screenshot to /tmp/shot.png.`), not only a text that is the bare path; the same checks apply (an image by
+  its bytes, under the temp dir or the server's `cwd`).
+- An MCP server that sends `notifications/tools/list_changed` has its tools listed again (`mcp` 0.4.0): its saved list
+  and the model's tools are replaced from the next turn on. They were only logged.
+- An MCP server that exits mid-session starts again on its next call (`mcp` 0.4.0), up to 3 times a session; its tools
+  failed until chi restarted.
+- A burst of plugin notices no longer pushes cards and questions out of what a reloaded web page or a joining
+  `chi --attach` shows: the worker keeps the last 20 of each apart, and never drops a question still waiting for its
+  answer.
+- `/checkin off`, `/checkin mode …` and `/checkin 30` last for the session across a worker's restart (an idle exit,
+  `chi send` waking it): the `check-in` bundle (0.2.0, `chi update`) saves them per session and reads them back.
+- `printf '2\n' | chi --attach ID` on a session already waiting on a question answers it: the piped line could be read
+  before the question arrived and go in as a new prompt, and the attach then hung.
+- A REPL reading its answers from a pipe shows each answer line once (`? 2`), not `? ? 2`, above why it was refused
+  or invalid.
+- A plugin's cards and a turn's hook notices (loop-guard's "stopped the turn" card and its `loop: … denied` rows,
+  check-in's, any bundle's) stay after the worker goes: the worker saves them in the session's folder
+  (`cards.json`, the same last-20 caps), the web shows them in place for a stopped session, and a later worker starts
+  from them. They used to vanish with an idle exit, a restart or `chi sessions stop`.
+- The web marks a tool call a guardrail denied (loop-guard, the `guardrails` bundle, a parent's or the user's Deny)
+  `blocked` in red, as the TUI does, live and after a reload; it showed a green `done`.
+
+### Changed
+
+- A host is remote by its address, not by its API key: an `https` url or a public IP address. A llama.cpp on the LAN
+  started with `--api-key` (`api_key_env:`) is now local again: chi asks its `/props` for the context window and the
+  served model, keeps its model list for 60 s, and gives it no first-token limit. `hosts.<name>.remote: true|false`
+  decides it for a host chi gets wrong (an http host named by a public DNS name counts as local).
+- Codex CLI counts as a parent agent: an answer typed into `chi --attach` or the REPL from a command Codex runs
+  (`CODEX_THREAD_ID` set) is held to `guardrails.parent_approvals`, as one from Claude Code is.
+- `delegate` and `delegate_result` report a child's wait with the status words of `chi send --wait --format json`:
+  `answered` (was `done`), `question` (was `waiting_for_answer`), `failed`, `canceled` or `no_answer` (was `no_reply`),
+  and `running` when the parent's turn is canceled (was `canceled`).
+
+Update with `chi update` (bundles: mcp 0.4.0, check-in 0.2.0).
+
+## [0.13.0] - 2026-10-02
+
+### Added
+
+- `chi send --wait --format json` prints one JSON object on stdout however the wait ends: the reply, a question with its
+  options and the `chi answer` command for it, or the status and a detail line, for scripts and parent agents.
+- `chi answer ID --question QID --option N` (or `--text`, `--dismiss`) answers the question a session waits on and
+  waits for what comes next, as `chi send --wait` does, so an agent running chi as a sub-agent can answer chi's
+  questions itself. `chi send --wait -m` to a session waiting for an answer is refused with the `chi answer` command
+  for it.
+- An approval answered with `chi answer` can be denied, not allowed: allowing is the user's (the web, `chi --attach`).
+  `guardrails.parent_approvals: once` in config.yml (no environment variable) lets "Allow
+  once" through, never a wider scope, and never on a call that changes chi's own config, hooks or guardrail rules; an approval whose offered scopes are missing lets only Deny through. The worker
+  checks it again with its own config (`chi answer` marks its answers); the web and `chi --attach` keep every scope.
+- `chi sessions list` shows a session waiting for an answer as `waiting`; `--format json` has `waiting` (`question`,
+  `approval` or `hook`) and `waiting_id`, the question's id for `chi answer --question`.
+- docs/sub-agent.md: running chi as another agent's sub-agent, with instructions to paste into its `CLAUDE.md` /
+  `AGENTS.md`.
+
+### Changed
+
+- The `guardrails` bundle (0.3.0) asks before answering chi's questions around `chi answer`: `chi --attach` / `chi -p`
+  with stdin from a pipe, a here-string or a file, and `curl`/`wget` to a session's `/answer` route.
+- An answer typed into `chi --attach` or the REPL counts as a parent agent's, held to `guardrails.parent_approvals`,
+  when stdin isn't a terminal or `CLAUDECODE`, `AI_AGENT` or `SAMAGOTCHI_PARENT_SESSION` is set: a piped `y` no
+  longer allows an approval at any scope. chi's `execute` and `task_create` export `SAMAGOTCHI_PARENT_SESSION` (the
+  session's id) into the commands they run, and the model's `task_create` env can't set it.
+- `guardrails.enabled` and `guardrails.small_models` are config.yml only: `SAMAGOTCHI_GUARDRAILS_ENABLED=false` no
+  longer switches guardrails off, and a worker unsets every `SAMAGOTCHI_GUARDRAILS_*` it inherits, so a parent agent
+  starting or waking a session can't switch its guardrails off. `XDG_CONFIG_HOME` still picks the config dir.
+- `chi send --wait` exits 4 (not 1) when `--timeout` passes with the turn still running.
+- Attached `chi -p` from a script exits 3 (not 1) when it leaves a question or an approval waiting for an answer,
+  and prints the whole question on stderr with the `chi answer` command for it, as `chi send --wait` does.
+- For an approval, the question block, `answer_with` and the refusal tell a parent agent to deny it and tell its
+  user (`--option Deny --text WHY`), not `--option N` or `chi --attach`; other questions keep their wording.
+- `chi send --wait`'s exit 3 prints the whole question on stderr: its text, numbered options and how to answer it.
+- `delegate` / `delegate_result` on a child waiting for an answer give the whole question: its text, numbered options
+  and the `chi answer` command for it.
+- `chi send --image` with a missing file or one that isn't an image exits 1 (not 2, which is for usage errors), and
+  with `--wait --format json` prints the JSON error line.
+
+### Fixed
+
+- The web no longer notifies about, or draws, a question a chi REPL is asking: the web can't answer it there.
+- `delegate_result` on a child whose worker died says `worker_gone` instead of waiting for, or reporting, a question
+  nobody can answer; `chi send --wait` and `chi answer` no longer report such a question as waiting either.
+- Answers from Splash no longer start with two blank lines (a workaround until Splash drops them itself).
+- An error in chi's work after a turn's answer no longer also reports the answered turn as failed.
+- A Stop while a turn is still starting (chi asking the model server about the model) now ends the turn there: no before-turn hooks run and a due reminder stays due.
+- `recap.model` set to a model id without a host no longer turns the recap off: it asks the host a bare `--model` goes to.
+- AGENT.md is found at the top of the git work tree when chi runs in a subdirectory (one in the current directory still wins).
+- `execute.timeout_sec` in config.yml (or `--execute-timeout-sec`) sets how long an `execute` command may run, like `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC`; it no longer warns as an unknown key.
+- A bundle's `requires_chi` now applies to its hooks too, not only its plugin: on a too-old chi they don't load, with a notice.
+- `chi bundle install` and `chi bundle status` say when a bundle's hooks won't load because chi is older than its `requires_chi`, also for a bundle without a plugin.
+- A model named with a disabled host's prefix (`box:model` where `hosts.box` has `enabled: false`) is refused with "host 'box' is disabled" instead of going to the default host as a model id.
+- A Stop while a turn is still starting no longer uses up the warning about guardrails or plugins that failed to load: the next turn shows it.
+- A plugin or MCP tool call reads the same in logs, rows and hooks' `content` whatever the model format or Ruby version: its arguments as JSON (Qwen calls showed Ruby's Hash#inspect, which changed in Ruby 3.4). A plugin tool returning a Hash or Array gives the model JSON too.
+
+Update with `chi update` (bundles: guardrails 0.3.0).
+
 ## [0.12.0] - 2026-10-02
 
 ### Added
@@ -669,7 +782,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.12.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/dm1try/samagotchi/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/dm1try/samagotchi/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/dm1try/samagotchi/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/dm1try/samagotchi/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/dm1try/samagotchi/compare/v0.10.0...v0.10.1

data/README.md

@@ -14,9 +14,16 @@ command.
 ## Requirements
 
 - Ruby 3.3+
-- A model server: [llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server`
-  by default; mlx-lm, oMLX and OpenAI-compatible servers also work
-  (see [Configuration](docs/configuration.md#model-server-transport))
+- A model server: any OpenAI-compatible chat completions server, or
+  [llama.cpp](https://github.com/ggml-org/llama.cpp)'s `llama-server` through
+  its own API (the native path, and the default)
+
+Tested: llama.cpp native (Qwen, Gemma 4), [Splash](https://github.com/incoai/splash)
+over the OpenAI API, and [OpenRouter](https://openrouter.ai) (remote, OpenAI API
+with `api_key_env`). vLLM, LM Studio, Ollama, mlx-lm, oMLX and other
+OpenAI-compatible servers should work over the OpenAI API but are not tested;
+mlx-lm and oMLX also have native transports, see
+[Configuration](docs/configuration.md#model-server-transport).
 
 ## Install
 
@@ -59,7 +66,7 @@ Point chi at your model server; it works out the rest and writes
 
 ```sh
 chi bootstrap 192.168.1.29:8081          # llama.cpp on another machine
-chi bootstrap localhost:11434            # Ollama (any OpenAI-compatible server)
+chi bootstrap localhost:11434            # any OpenAI-compatible server
 chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
 chi bootstrap                            # look on this machine's usual ports
 ```
@@ -86,9 +93,8 @@ server:
   port: 8080
 ```
 
-`server:` is a llama.cpp `llama-server`. For any other OpenAI-compatible
-server (vLLM, LM Studio, Ollama, a gateway), name it under `hosts:` with
-`api: openai` instead:
+`server:` is a llama.cpp `llama-server`. For an OpenAI-compatible server,
+name it under `hosts:` with `api: openai` instead:
 
 ```yaml
 default:
@@ -145,6 +151,12 @@ stdin plus `-m` puts the stdin above the message as a `>` quote. `chi send --new
 starts a session with the message instead (it shows in the web at once), and
 `--wait` blocks and prints the answer.
 
+Another agent (Claude Code, Codex) can run chi as a sub-agent the same way:
+`chi send --new --wait --format json` returns chi's reply, or the question chi
+stopped on, which the agent answers with `chi answer`. See
+[chi as a sub-agent](docs/sub-agent.md) for a snippet to paste into its
+`CLAUDE.md` / `AGENTS.md`.
+
 ### Send to chi (macOS)
 
 `chi desktop install` builds a small native helper: select text in any app →
@@ -173,6 +185,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Configuration](docs/configuration.md): `config.yml`, hosts, model server transports, timeouts, retries, logs
 - [Memory](docs/memory.md): scopes and model-specific overlays
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`
+- [chi as a sub-agent](docs/sub-agent.md): `chi send --wait --format json`, `chi answer`, instructions for a parent agent
 - [Desktop helper](docs/desktop.md): `chi desktop`, the macOS "Send to chi" Service and hotkey
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals
 - [Hooks](docs/hooks.md): plugin hooks and bundle hooks

data/bin/chi

@@ -3,13 +3,10 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 
-# No locale at all (an app started from Finder or launchd, `env -i`): files
-# would read as US-ASCII, and chi's session JSON is UTF-8. Workers this
-# process spawns inherit the LANG.
-if Encoding.default_external == Encoding::US_ASCII && %w[LC_ALL LC_CTYPE LANG].none? { |key| ENV[key] }
-  ENV["LANG"] = "en_US.UTF-8"
-  Encoding.default_external = Encoding::UTF_8
-end
+# LC_ALL=C or no locale at all: files would read as US-ASCII, and chi's
+# memories and sessions are UTF-8 (Utf8Default).
+require "samagotchi/utf8_default"
+Samagotchi::Utf8Default.apply!
 
 require "optparse"
 require "samagotchi/config"
@@ -45,6 +42,8 @@ SUBCOMMANDS = {
   "note" => ["samagotchi/note_command", "NoteCommand"],
   # a message into sessions as the user's (-m)
   "send" => ["samagotchi/send_command", "SendCommand"],
+  # answer the question a session waits on, then wait (--question, --option)
+  "answer" => ["samagotchi/answer_command", "AnswerCommand"],
   # find a model server and write config.yml (--model, --name)
   "bootstrap" => ["samagotchi/bootstrap_command", "BootstrapCommand"],
   # bring an installed chi up to date
@@ -94,6 +93,7 @@ parser = OptionParser.new do |opts|
            chi sessions <list|stop|archive|unarchive|delete|prune|clean>
            chi note [--source NAME] [-m TEXT] ID...|--all   background context for 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 bundle <install|upgrade|uninstall|status|diff|list|build>
            chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
            chi models [--format json] [TEXT]   the models --model takes, from every host
@@ -106,7 +106,7 @@ parser = OptionParser.new do |opts|
   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 selector (runtime only, overrides --resume) [alias for --default-model]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
+  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), "How much the model thinks this run: off|low|medium|high|default (outranks config.yml; " \
@@ -311,7 +311,7 @@ if launch == :attached
     warn "Error: #{e.message}"
     exit 1
   end
-  exit(ended == :detached ? 0 : 1)
+  exit Samagotchi::TerminalUI::AttachLauncher.exit_status(ended)
 end
 
 begin

data/docs/architecture.md

@@ -156,7 +156,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 #### Using the core
 
 ```ruby
-engine = Samagotchi::Engine.new(mode: :assist, model_name: "gemma4", memories: [])
+engine = Samagotchi::Engine.new(model_name: "gemma4", memories: [])
 session = Samagotchi::Session.new_session(mode: "assist", model_name: "gemma4", working_directory: Dir.pwd)
 
 engine.run_turn(session, "hello", on_event: nil)   # => LLM::ModelResult (`.output`)
@@ -223,7 +223,9 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   refused connection is `503 not_live`.
 - `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
 - `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
-  answered first or it is gone, `400` for an invalid selection.
+  answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
+  (`chi answer`, a parent agent) an allow on an approval beyond the worker's
+  `guardrails.parent_approvals` is `403 parent_approval_refused`, the question still open.
 - `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
   `200`, or `409` when it is no longer pending.
 - `POST /session/:id/command` — a session command (`/model`, `/models`, `!rollback`, `!cmd`,

data/docs/cli.md

@@ -17,19 +17,20 @@
 - `chi web --web-view turn` — draw turns with the turn view (each turn as one block of steps, the running one at the bottom of the history) instead of the default stage view (the running turn pinned above the composer); `?view=stage|turn` on the page URL overrides it (see [Web views](#web-views))
 - `chi sessions list|stop|archive|unarchive|delete|prune|clean` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). A usage error (an unknown subcommand or flag, a flag missing its value, `stop` or `delete` with no ids, a bad `list --format` or `--scope`) exits 2; an unknown or refused session exits 1
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
-- `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); 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, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
-- `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text to live sessions as context notes (see [Desktop helper](desktop.md))
+- `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); 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, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; `--format json` prints one JSON object instead; 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`). An approval can be denied, not allowed, unless `guardrails.parent_approvals: once` (a convention, not a security boundary; see [Guardrails](guardrails.md#approvals-from-a-parent-agent))
+- `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))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles; `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
-- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for every other command
+- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument
 
 ### First setup
 
 `chi bootstrap TARGET` names the model server and writes the config for it:
 
 ```sh
-chi bootstrap 192.168.1.29:8081          # host:port (port 8080 when none)
+chi bootstrap 192.168.1.29:8081          # host:port (an IP or localhost: port 8080 when none; a domain: https 443, then http 80)
 chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
 chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
 ```
@@ -179,7 +180,8 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 
 Every setting in the config registry (`lib/samagotchi/config.rb`) that exposes a CLI
 flag also works as `--kebab-case VALUE`, e.g. `--server-host`, `--server-port`,
-`--read-truncate-at-bytes`. `chi --help` lists them all.
+`--read-truncate-at-bytes`; an on/off setting is `--[no-]kebab-case` with no value
+(`--context-status`, `--no-context-status`). `chi --help` lists them all.
 
 **Which loop runs.** There is no backend flag: the model's host decides. A host with
 `api: openai` in config.yml is driven through the OpenAI chat API (streamed; a remote
@@ -204,11 +206,22 @@ as an unknown key).
 
 Notes:
 
+- Attached `chi -p …` with stdin not a terminal (a script, an agent's shell)
+  leaves when its input ends and the turn is done. Exit status: 0 the turn
+  ended, 3 a question or an approval waits for an answer (stderr gets the
+  whole question as `chi send --wait` prints it, with the
+  `chi answer ID --question QID --option N` command; the worker keeps it
+  open, and `chi answer` or the web answers it), 1 the turn failed or the
+  worker went away. For a
+  script, `chi send --new --wait` is the better entry point: stdout holds the
+  answer alone (see [Starting a session](sessions.md#starting-a-session)).
 - `-p` always feeds **and** runs the prompt; there is no feed-and-edit variant. To
   prefill (edit, not execute) the first REPL line, use the
   `SAMAGOTCHI_DEFAULT_INPUT` environment variable instead.
-- Prompt history is persisted per session; `--resume` preserves prior messages as
-  turn context (a `-p` run on a resumed session never clobbers existing history).
+- Prompt history (↑) is one file shared by every session (see [Persistent Prompt
+  History](#persistent-prompt-history)); `--resume` preserves the session's prior
+  messages as turn context (a `-p` run on a resumed session never clobbers its
+  conversation).
 - Non-interactive runs (`-p` with `--non-interactive`, or bare `--non-interactive`)
   print only the final result output — no spinner, status line, or REPL.
 
@@ -357,6 +370,16 @@ file and index line stay as they are; only this session doesn't see it.
 - The `read` tool on `memories/<name>.md` is not refused (a guardrails rule
   can protect the path if wanted).
 
+### Session commands
+
+`/help` lists the commands this session takes, the installed bundles' too, each
+with a line on what it does. `/stats` shows the session's numbers: turns, tool
+calls (by tool, with errors), iterations, tokens in/out summed over every
+request, generation latency, cancellations, retries, context used and window,
+the prompt profile and the model the server says it ran. `/recap` is in
+[Session recap](#session-recap), `/model` and `/models` in [Runtime Model
+Switch](#runtime-model-switch-assist-mode).
+
 ### Typing during a turn
 
 The prompt stays open while a turn runs, in an attached terminal and in the plain
@@ -368,7 +391,8 @@ REPL alike:
   A line that comes after the turn's last step runs as the next turn, and so
   does one sent after Ctrl-C: it doesn't merge into the turn being cancelled.
   Reminder turns take merged lines too.
-- `/stats` and `/recap` answer at once. Other commands (`!cmd`, `/model`,
+- `/stats` and `/recap` answer at once, and in an attached terminal so do `/help`
+  and a plugin's anytime command (`/btw`). Other commands (`!cmd`, `/model`, `/models`,
   `!rollback`, `/continue`, `/guardrails`) say `busy: wait for the turn to end`
   and go back into the prompt, so Enter runs them once the turn ends.
 - A question (`ask_user_question`, a guardrails approval) turns the prompt into
@@ -601,7 +625,7 @@ In interactive assist mode, you can switch the request model without restarting:
 
 - `/model <name>`: set a session-scoped model override.
 - `/model host:model` or `/model host:alias`: qualified host routing (only `:` names a host; `openai/gpt-4o` is a model id). `host:alias` applies the alias; an alias whose target names another host is refused (`alias 'tiny' names host 'box', not 'openrouter'`). Aliases apply once: an alias pointing to another alias sends that name as written.
-- `/model --default <name>`: set session model and persist as new default in `config.yml` (also updates `SAMAGOTCHI_DEFAULT_MODEL` for future sessions; supports `host:model` full ref).
+- `/model --default <name>`: set session model and persist as new default (`default.model`) in `config.yml` for future sessions (supports `host:model` full ref). It writes only the file: an exported `SAMAGOTCHI_DEFAULT_MODEL` (or `--model`) still wins over it.
 - `/model <name> --alias <alias>`: create alias for current effective model (alias value may be bare or `host:model`).
 - `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`).
 - `/model clear` (or `default`/`none`/`off`): clear the session override, reverting to the configured default.
@@ -724,7 +748,7 @@ A long, tool-heavy turn says what it has been doing. From the turn's 3rd tool ca
 a dim row under the activity row tallies its calls, with no model call:
 
 ```
-12 tool calls (2 failed) · execute ×7 · read_file ×3 · edit_file ×2 · last: execute command=bundle exec rspec
+12 tool calls (2 failed) · execute ×7 · read ×3 · edit ×2 · last: execute command=bundle exec rspec
 ```
 
 It lists the top 3 tools by count (ties go to the tool used first), the failed calls

data/docs/configuration.md

@@ -49,8 +49,9 @@ hosts:
 # url:, else http://host:port/v1) with its api_key_env; base_url is an OpenAI API
 # base as given (e.g. http://h:8081/v1). model is a model ref like any other: an
 # alias is applied, and its host:/the alias's host picks the host when host_ref
-# is left out (a model naming another host than host_ref turns recap off with a
-# warning). recap: false turns it off.
+# is left out; a model naming no host goes where a bare --model goes (the
+# default host). A model naming another host than host_ref turns recap off with
+# a warning. recap: false turns it off.
 recap:
   # host_ref: small-box
   # model: your-small-model-id
@@ -114,8 +115,9 @@ any per-run `--memory` values (config baseline first, deduped). A per-run
 
 ### Environment variables
 
-Every setting has an environment variable: `SAMAGOTCHI_` plus its dotted
-name in upper case, with `_` for each dot. `default.model` is
+Every setting has an environment variable (except the ones the table marks
+config.yml only): `SAMAGOTCHI_` plus its dotted name in upper case, with `_`
+for each dot. `default.model` is
 `SAMAGOTCHI_DEFAULT_MODEL`, `server.read_timeout` is
 `SAMAGOTCHI_SERVER_READ_TIMEOUT`. Use them to override the file for one run or
 one shell (`SAMAGOTCHI_LOG_LEVEL=debug chi`); keep lasting choices in the file.
@@ -230,6 +232,37 @@ hosts:
     api_key_env: BOX_LLAMA_KEY
 ```
 
+**Remote or local.** chi treats a host as a remote provider by its address, not
+by its key: an `https` url, or an `http` IP address outside the loopback,
+private (`10.*`, `172.16–31.*`, `192.168.*`, IPv6 `fc00::/7`), link-local and
+CGNAT/Tailscale (`100.64.0.0/10`) nets. An `http` host given by a name
+(`localhost`, `box`, `mac.local`) is local: chi doesn't look names up. A remote
+host keeps its model list for 10 minutes, gets a 120-second first-token limit,
+and isn't asked for llama.cpp's `/props` (its context window and served model
+come from its model list and each turn). `remote: true` or `remote: false` on a
+host decides it instead, e.g. for a llama.cpp behind an https proxy on the LAN:
+
+```yaml
+hosts:
+  lab:
+    url: https://llm.lab.example/v1
+    api: openai
+    api_key_env: LAB_KEY
+    remote: false
+```
+
+A host without `port:` (and without `url:`) uses port 8080. `enabled: false`
+turns an entry off without deleting it: chi skips it as if it weren't there
+(not in `chi models`, never the default host; `box:model` then counts as an
+unknown host prefix, see [Llama Model Routing](#llama-model-routing)):
+
+```yaml
+hosts:
+  box:
+    host: 192.0.2.20
+    enabled: false
+```
+
 For models on that host, chi uses the chat loop (its own OpenAI chat adapter): it
 takes the OpenAI base (`url:`, else `http://HOST:PORT/v1`) and streams messages plus
 function schemas from `/v1/chat/completions`; the model's reasoning (`reasoning_content`)
@@ -467,7 +500,7 @@ hosts:
 ```
 
 `hosts.<name>.first_token_timeout` wins over `server.first_token_timeout` (`SAMAGOTCHI_SERVER_FIRST_TOKEN_TIMEOUT`),
-which applies to every host. With neither set, remote hosts (an API key or an https url) get 120 seconds and local
+which applies to every host. With neither set, remote hosts (see "Remote or local" above) get 120 seconds and local
 servers no limit: a long prompt evaluation is normal there, and the read timeout catches a dead server.
 
 Every chat request carries the session's id as a `Session-Id` header (next to `User-Agent: chi/<version>`). A
@@ -493,11 +526,33 @@ to the default host. Only exact ids count, never a substring: `/model gemma` on
 a box that lists `gemma-3-12b` needs `box:gemma` or the exact id. The lists are
 known only after `/models` ran (nothing is fetched before the first turn), so
 until then an unqualified name goes to the default host; use `host:model` to pin
-one. A **remote** host (one with `api_key_env:` or an `https` url) keeps its model
-list for 10 minutes (60s for local hosts). For a chat host the context window comes from
-the running server (llama.cpp's `/props`), else the window the host's model list
-gives (`context_length`, `context_window`, `max_model_len` or llama.cpp's
-`meta.n_ctx`), else `context.window_tokens`.
+one. A **remote** host (an `https` url or a public address; see "Remote or local") keeps its model
+list for 10 minutes (60s for local hosts).
+
+**The context window** (what the context status and `ctx=` count against) comes from,
+first to last:
+
+1. the running server (llama.cpp's `/props` `n_ctx`; a remote host isn't asked),
+2. the window the host's model list gives (`context_length`, `context_window`,
+   `max_model_len` or llama.cpp's `meta.n_ctx`),
+3. `models.<key>.window_tokens` (the key as `sampling:` looks a model up), else
+   `hosts.<name>.window_tokens`,
+4. `context.window_tokens`, else 256000.
+
+The settings only fill in when the server and its list report nothing: what the
+server runs with is the window that counts. Set one for a provider whose list has
+no window:
+
+```yaml
+hosts:
+  work:
+    url: https://llm.work.example/v1
+    api: openai
+    window_tokens: 131072
+models:
+  qwen3-8b:
+    window_tokens: 32768
+```
 
 Only `:` names a host: `/` is part of a model id (`openai/gpt-4o` is an
 OpenRouter id and goes to the default host as written, even with a host named
@@ -741,6 +796,10 @@ The helper reads these from its launch file: after editing them run
 
 If an AGENT.md file is present in the project root, samagotchi injects its
 contents into the system prompt under a "Project specific description:" section.
+The project root is the top of the git work tree chi runs in (a linked
+worktree's own checkout), or the current directory outside a repository. An
+AGENT.md in the current directory is read instead when there is one; only one
+file is read.
 
 To skip loading AGENT.md, set `skip_agent_md: true` at the top level of
 `config.yml` (env `SAMAGOTCHI_SKIP_AGENT_MD=true`).
@@ -749,7 +808,8 @@ To skip loading AGENT.md, set `skip_agent_md: true` at the top level of
 
 Every setting below takes the three forms described in
 [Environment variables](#environment-variables): a nested key in
-`config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment and, where the CLI
+`config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment (not for one
+marked config.yml only) and, where the CLI
 column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 `model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`) are
 described in their own sections.
@@ -767,7 +827,7 @@ described in their own sections.
 | `server.read_timeout` | `600` | yes | Read timeout, seconds. |
 | `server.first_token_timeout` | 120 remote, off local | | Seconds to the first token; `0` = off. `hosts.<name>.first_token_timeout` wins. |
 | `recap.enabled` | on | | `false` (or `recap: false`) turns the idle recap off. |
-| `recap.model` | session's | yes | Model that writes the recap: an id, alias or `host:model` (the host then picks where to ask). |
+| `recap.model` | session's | yes | Model that writes the recap: an id, alias or `host:model` (the host then picks where to ask; a bare id goes where a bare `--model` goes). |
 | `recap.host_ref` | session's | yes | A `hosts:` name to ask (`host:` is accepted too, also a host name, not a model ref). |
 | `recap.base_url` | none | yes | An OpenAI API base to ask instead (`http://h:8081/v1`). |
 | `recap.inactivity` | `180` | yes | Idle seconds before a recap. |
@@ -785,20 +845,23 @@ described in their own sections.
 | `image.max_side` | `1568` | | See "Images". |
 | `image.max_bytes` | `3750000` | | See "Images". |
 | `image.max_per_request` | `20` | | See "Images". |
-| `guardrails.enabled` | `true` | | See [Guardrails](guardrails.md). |
-| `guardrails.small_models` | `auto` | | Which models get the `models: small` rules: `auto` (32B or less by the size in the name, an MoE's active size), a list of globs, or `[]`. See [Guardrails](guardrails.md#rules-for-some-models). |
+| `guardrails.enabled` | `true` | | `false`: no rules, and hooks' asks are dropped (a deny still applies). config.yml only: a worker unsets any `SAMAGOTCHI_GUARDRAILS_*` it inherits. See [Guardrails](guardrails.md). |
+| `guardrails.small_models` | `auto` | | Which models get the `models: small` rules: `auto` (32B or less by the size in the name, an MoE's active size), a list of globs, or `[]`. config.yml only. See [Guardrails](guardrails.md#rules-for-some-models). |
+| `guardrails.parent_approvals` | `off` | | What `chi answer` lets a parent agent allow on an approval: `off` (deny only) or `once` ("Allow once", never a wider scope). config.yml only: no environment variable (a parent can still pick the config dir with `XDG_CONFIG_HOME`). A convention for an honest parent, not a security boundary. See [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `log.file` | state dir | yes | See "Debug Log File". |
 | `log.disable` | `false` | yes | No file logging. |
 | `log.level` | `info` | yes | `debug`, `info`, `warn`, `error`. |
 | `status.line` | `on` | yes | The status row under the prompt (the REPL's and attached mode's), `on` or `off`. |
 | `context.status` | `true` | yes | Context-usage telemetry for the model. See [context telemetry](internals/context-telemetry.md). |
-| `context.window_tokens` | server's, else 256000 | yes | Context window when the server doesn't report one. |
+| `context.window_tokens` | server's, else 256000 | yes | Context window when the server doesn't report one. `models.<key>.window_tokens` and `hosts.<name>.window_tokens` come first; see "The context window". |
+| `models.<key>.window_tokens`, `hosts.<name>.window_tokens` | none | | A model's or host's context window when the server and its model list report none. |
 | `context.chars_per_token` | `4.0` | yes | Estimate ratio when the server reports no usage. |
 | `context.status_thresholds` | `20,40,60,80` | yes | Percentages that trigger a status. |
 | `context.status_cadence` | `0` | yes | Also every N rounds; `0` = thresholds only. |
 | `thinking.turn_preamble` | `true` | yes | Ask a `qwen36` model to open its thinking with a short `TURN:` line (the step label). |
 | `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't. See "Thinking". |
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
+| `hosts.<name>.remote` | by address | | `true`/`false`: treat the host as a remote provider or a local server. See "Remote or local". |
 | `max_tool_output_chars` | `10000` | yes | Tool output kept in the conversation; a top-level key (see below). |
 | `retry.max` | `5` | yes | See "Llama Network Retry Behavior". |
 | `retry.base_delay` | `0.5` | yes | |
@@ -817,6 +880,7 @@ described in their own sections.
 | `execute.truncate_at_bytes` | `65536` | yes | The same for `execute` output. |
 | `execute.preview_bytes` | `12288` | yes | |
 | `execute.telemetry_threshold_pct` | `80` | yes | |
+| `execute.timeout_sec` | `30` | yes | Seconds one `execute` command may run before it is stopped. |
 | `web.port` | `4567` | `--port` | `chi web`'s port. See [CLI](cli.md). |
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |

data/docs/desktop.md

@@ -105,8 +105,9 @@ off until you set it up:
    `kitty.agents` picks the programs listed (default `claude|codex|gemini|aider|opencode|cursor-agent|amp|goose`, a
    YAML list works too; `"*"` lists every window, shells too), `kitty.binary` the kitty to run (default
    `/Applications/kitty.app/Contents/MacOS/kitty`). See [Configuration](configuration.md#desktop-helper-agents-in-kitty).
-3. Run `chi desktop upgrade` (or `chi update`): the helper reads these from its launch file, so **after every edit of
-   `kitty:`** run it again. No rebuild when only the settings changed.
+3. Run `chi update` (or `chi desktop upgrade`): the helper reads these from its launch file, so **after every edit of
+   `kitty:`** run it again. `chi update` only rewrites the launch file when only the settings changed (no rebuild);
+   `chi desktop upgrade` always rebuilds.
 
 The helper finds the sockets itself: kitty adds `-<pid>` to a `listen_on` path from kitty.conf (and fills in
 `{kitty_pid}`), `~` and variables the helper knows are expanded, others (`${KITTY_PID}`) stay as written, as kitty
@@ -188,12 +189,15 @@ using it. `status` prints the baked dirs.
 The helper uses only these commands, so it could ship on its own later:
 
 - `chi sessions list --live --scope=all --format json` and `chi sessions list --limit 20 --scope=all --format json` →
-  `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap}]` (it uses `id`, `desc`, `cwd`, `busy`, `updated_at`;
+  `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (it uses `id`, `desc`, `cwd`, `busy`, `updated_at`;
   "recent" = rows of the second call that aren't live and have `owner: null`; only UUID-shaped ids go on to chi).
-- `chi send [-m LINE] ID...` with the text on stdin (or none) and `chi note --source NAME ID...` with the text on
-  stdin → one line per session on stdout; exit 0 means all sent or queued, 1 means some were refused or failed.
+- `chi send [-m LINE] [--image PATH]... ID...` and `chi send --new --dir DIR [--model NAME] [-m LINE] [--image PATH]...`
+  with the text on stdin (or none), and `chi note [--source NAME] ID...` with the text on stdin → one line per session
+  on stdout; exit 0 means all sent or queued, 1 means some were refused or failed.
+- `chi self --model` → the model a new session starts on (the panel's hint).
+- `chi models --format json` → the models the hosts offer (the new-session model picker).
 
-Each call is stopped after 10 s. A stopped `chi note` says the note may be partly delivered.
+Each call is stopped after 10 s, a send with images after 30 s. A stopped `chi note` says the note may be partly delivered.
 
 ## Troubleshooting