samagotchi 0.58.0 → 0.60.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6049cfd1f36b6aa77b8dfdfd9d437693f1d0c08257eb327838ccf9134db9fa27
-  data.tar.gz: d10c78ddf6e21e39689c3012214d4362844e090cac3624863a7a26195cc09769
+  metadata.gz: ee2aa2b12b6482c02486b2382cc1c287c394d0a323e3bbf851948e49d0ebb2b9
+  data.tar.gz: 7bddba2fddfbcc05dfccba0777a6163963f8e238a26d14b6fbfb49b3d0bc0827
 SHA512:
-  metadata.gz: 240fb5fc4a45ae15088c690cc45c034f8ced20a9b6844649719ebfe25b9cf8801ecc90601d2c464d8e24a9fe75feadc0d541c8fe3e2c9784a2bd65fce9c31767
-  data.tar.gz: 64353c0287ded0c59631dec4af9319592d354ae1dc6c3d8609c65fffb60554a841453c060580233884cc1d8f4ed93dcfdb4434bd2fe5bfedeb57fb9f51c9cc3a
+  metadata.gz: fb47d9df8beac57e413f22b01efdf8bbec31c7c9a5be400976b818d8e6dbe6931081b223568cbb3f345dee39c7f1ffc7a6b39def9e01b4033bdcf7ccda017cdd
+  data.tar.gz: 95b1879ed0ee9d093140d2dddaa9cc21c30031d45f7114b1c3311134d2f1082ad1f81480421a8da7f9cd61eb76d4d4aae65b8b29c08c0dd377dcbdab50c98f6d

data/CHANGELOG.md

@@ -8,6 +8,89 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.60.0] - 2026-10-11
+
+### Added
+
+- chi web has a favicon: χ on a blue-to-violet rounded square. Safari showed a "1" monogram before.
+- `chi --append-system-prompt FILE` (repeatable) and a config.yml `append_system_prompt:` list: a file's text goes
+  into the system prompt after AGENTS.md, in the cached part. A relative config entry is looked up where chi runs
+  (`append_system_prompt: [CLAUDE.md]`); the flag's files are saved in the session and kept by forks and continues.
+  `/stats` names the prompt's files on a `prompt files:` line.
+- An analytics `resumed` mark on the turn record of a step-limit Continue (`resumed: true`; every other turn has
+  `resumed: false`). `continue` also marks a reminder's and a wake's turn, so `script/model_notes_report` now counts
+  Continues from `resumed`, falling back to `continue` record by record for older files. `:turn_started` and the
+  `before_turn` hook payload carry `resumed` too.
+- A hook's or plugin's notice can be marked `fallback_for: :editor`: a line naming a file the viewer could open from
+  a ref. The web leaves it out for a viewer on this machine with `web.editor` set; a phone and the terminals show it.
+- `ctx.prompt_files` for plugins: the files whose text is in the session's system prompt now — the AGENTS.md chain
+  and the appended files — as absolute paths in prompt order.
+- The `agents-md` bundle, in the `core` profile (core 0.3.0: `chi update` installs it for existing core users):
+  a nested `AGENTS.md` of the session's checkout — one in a directory the session doesn't run in, which the
+  system prompt never sees — is steered into the conversation the first time a tool (`read`, `write` or
+  `edit`) touches a file under its directory, outermost first, once per session, and never re-injected after a
+  resume or a woken worker. It never stops generation or thinking, and leaves the chain's and appended
+  `AGENTS.md` files alone (`ctx.prompt_files`). Files in another repository, a nested repository or a
+  submodule are ignored. Opt out with `skip_agents_md: true`, as with the chain; `bundles: agents-md:`
+  settings: `tools`, `max_chars`. See "The agents-md bundle" in docs/plugins.md.
+
+### Changed
+
+- The default step limit (`turn.max_iterations`) is 300, up from 100: most long build turns now finish in one turn
+  instead of stopping at the step-limit question. Loops are caught by the loop-guard bundle, and check-in's card
+  (at 50 tool calls, then every 50) still says a turn is long without stopping it. `--no-interrupt` stays 1000.
+- Started in a subdirectory, chi loads every `AGENTS.md` from the top of the git work tree down to the current
+  directory, outermost first, instead of the subdirectory's replacing the root's. A further file is headed with its
+  directory ("Project specific description for pkg/:"); a session with one `AGENTS.md` gets the same prompt as before.
+
+### Fixed
+
+- A step-limit Continue no longer drops the turn's reasoning: on a chat host (`reasoning_history: turn`) the
+  continued turn sends the earlier replies' reasoning back as before the limit, and on a native host
+  (`/completion`) the prompt keeps the run's thought blocks, those before a mid-turn steer too. The model keeps its
+  thinking, and the first request after the Continue matches the last one before the limit (before the fix, a local
+  27B read most of a 17k prompt again: 24.9 s to the first token instead of 4.0 s). Continue's text is a steer, and on a chat host still starts
+  the reasoning afresh from it. After a `/model` change while the question stands, the Continue starts afresh.
+
+Update with `chi update`: the system bundle 0.60.0, the core profile 0.3.0 (now with agents-md) and the new
+agents-md 0.1.0 bundle.
+
+## [0.59.0] - 2026-10-11
+
+### Added
+
+- `hosts.<name>.steer_cut_after` and `models.<key>.steer_cut_after`: how long a message sent as a cut waits, per host
+  or model (`0` = never, e.g. a slow local thinker); `/model` shows the resolved one.
+
+### Changed
+
+- At its limit (`execute.timeout_sec`, 120 s), `execute` hands a command still running over as a background task
+  instead of killing it: the result names its `task_id` and the output so far, and `task_wait` waits for the rest.
+  The execute tool's description says so (the prompt changes once: a cached prompt prefix is rebuilt after the
+  upgrade). `execute.on_timeout: kill` keeps the old kill. The `!cmd` bang still kills at the limit. Command output
+  now goes through log files under the state dir, and the command's stdin is `/dev/null`. On Linux, a command that
+  writes through `/dev/stdout` or `/dev/stderr` loses its earlier output (known gap).
+- slow-commands bundle 0.2.0 (needs chi 0.59.0): a command `execute` handed over as a task at its limit counts as
+  slow, and the "a finished task took …" advice also reads handed-over tasks. A command is now remembered without
+  the `time` / `timeout N` wrappers and `env` a model adds (`timeout 300 rspec` and `rspec` are one entry), its
+  `X=…` assignments sorted and `NO_COLOR`, `FORCE_COLOR` and `TERM` left out; `/slow-commands` shows each as last
+  typed. With `execute.on_timeout: kill`, a `timeout N` past the execute limit is denied up front.
+- chi reads a project's AGENTS.md (the name other agent tools read) instead of AGENT.md: rename yours. AGENT.md is no
+  longer read. The setting that skips it is now `skip_agents_md` (env `SAMAGOTCHI_SKIP_AGENTS_MD`).
+
+### Fixed
+
+- A `timeout N cmd` (GNU coreutils) that moved to a process group of its own is now stopped with the command: by the
+  user's Stop, at the execute limit and by `task_stop`. It used to run on, orphaned.
+- A `task_create` the guardrails corrected (its result starts with a `ran as:` line) now counts as the session's own
+  task: the turn-end and cancel notes list it, a worker doesn't idle-exit under it, and the web's stop-task button
+  works for it.
+- Web: a blank line in a read's numbered file lines is empty, not a space, so copying the lines keeps the file
+  as it is.
+
+Update with `chi update`: it updates slow-commands (0.2.0: hand-overs and command wrappers). Then restart `chi web`.
+If your project has an AGENT.md, rename it to AGENTS.md.
+
 ## [0.58.0] - 2026-10-11
 
 ### Added
@@ -2540,7 +2623,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.58.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.60.0...HEAD
+[0.60.0]: https://github.com/dm1try/samagotchi/compare/v0.59.0...v0.60.0
+[0.59.0]: https://github.com/dm1try/samagotchi/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/dm1try/samagotchi/compare/v0.57.0...v0.58.0
 [0.57.0]: https://github.com/dm1try/samagotchi/compare/v0.56.0...v0.57.0
 [0.56.0]: https://github.com/dm1try/samagotchi/compare/v0.55.0...v0.56.0

data/README.md

@@ -76,8 +76,9 @@ It finds out whether the server is llama.cpp or OpenAI-compatible, picks the
 model (or asks, when there are several), sends one test request and writes
 the config. With a config already there, it adds a `hosts:` entry and keeps
 the rest of the file. Then it installs the `core` bundles (loop-guard,
-check-in, guardrails, slow-commands: the safety set for a small local model) and, on a
-terminal, offers `dev` (known-names, mcp, btw, skills, source-links). Edit the
+check-in, guardrails, slow-commands, agents-md: the safety set for a small
+local model) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
+source-links). Edit the
 file later as in [Configure](#configure); `chi bootstrap --help` has the
 options.
 

data/bin/chi

@@ -82,7 +82,7 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --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)
+  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --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)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -120,6 +120,8 @@ parser = OptionParser.new do |opts|
                               "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("--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 }
@@ -308,6 +310,23 @@ if options[:llm_context]
   end
 end
 
+# --append-system-prompt: each file is checked here, before anything starts
+# (the user named it, so a missing one is an error), and made absolute
+# against this shell's cwd.
+if options[:append_system_prompt]
+  require "samagotchi/prompt_files"
+  options[:appended_prompt_files] = options[:append_system_prompt].map do |value|
+    path, reason = Samagotchi::PromptFiles.check_cli_file(value)
+    if reason
+      warn "Error: --append-system-prompt #{value}: #{reason}"
+      exit 1
+    end
+    chars = Samagotchi::PromptFiles.large_size(path)
+    warn "Warning: --append-system-prompt #{value} is #{chars} chars; it is in every request" if chars
+    path
+  end.uniq
+end
+
 chi_update_hint.call
 require "samagotchi/launch_mode"
 launch, launch_note = if scratch
@@ -341,7 +360,8 @@ if launch == :attached
                                                        memories: options[:memories] || [],
                                                        muted_memories: options[:muted] || [],
                                                        llm_context: options[:llm_context] || {},
-                                                       thinking: options[:thinking])
+                                                       thinking: options[:thinking],
+                                                       appended_prompt_files: options[:appended_prompt_files] || [])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
@@ -360,6 +380,7 @@ begin
     muted_memories: options[:muted] || [],
     llm_context: options[:llm_context] || {},
     thinking: options[:thinking],
+    appended_prompt_files: options[:appended_prompt_files] || [],
     non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch

data/docs/architecture.md

@@ -176,8 +176,9 @@ engine.run_turn(session, "hello", on_event: nil)   # => LLM::ModelResult (`.outp
 forwards the raw `KernelLoop` events unchanged (the low-level contract) and adds a few
 higher-level events so UIs get clean turn boundaries without inferring them:
 
-- `:turn_started` — `{ session_id:, prompt:, turn_id: }` (plus `continue: true` for a continue
-  turn, `images:` with the prompt's image refs)
+- `:turn_started` — `{ session_id:, prompt:, turn_id:, cut_after: }` (`cut_after`: the seconds a cut waits for this
+  model's thinking, `0` = never; plus `continue: true` for a continue turn, `resumed: true` for a step-limit Continue,
+  `images:` with the prompt's image refs)
 - `:turn_completed` — `{ result:, turn_summary:, display_pending: }` (`result`: the final
   `LLM::ModelResult`; `display_pending`: `after_turn` hooks may still present the answer)
 - `:turn_canceled` — `{ cancellation_reason:, cancelled_by:, duration_ms: }` (`cancelled_by`: the bundle or hook label that
@@ -198,7 +199,7 @@ engine.session           # current session (Engine owns create/resume)
 ```
 
 The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance, the
-identity and the preloaded memories, AGENT.md, the memory indexes, and last **the
+identity and the preloaded memories, AGENTS.md, the memory indexes, and last **the
 model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
 the model to answer "which model are you" from it, not from training), the working
 directory and the session id and log (Gemma's native tool declarations still follow).
@@ -394,7 +395,8 @@ stream with a fresh `ThoughtStreamSplitter` (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped
 from `text:`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
 so later requests and resumed sessions pair them, and their reasoning (`thinking:`), which goes back as
-`reasoning_content` on the running turn's replies (`reasoning_history`). It has its own system prompt
+`reasoning_content` on the running turn's replies (`reasoning_history`; a step-limit Continue's
+turn goes on from the run it resumes, `reasoning_since:`). It has its own system prompt
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 
 `Engine#build_stream_event_handler` is the one seam both loops' streams pass

data/docs/cli.md

@@ -189,6 +189,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--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. |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
+| `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |
 | `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
 | `--llm-context LAYERS` | This session's own LLM context strategy: `none`, or layers such as `stale` or `stale,forget` (comma, space or `\|` separated). Saved in the session, before the model's `llm_context_strategy`. With `--resume` it is set on the resumed session; on an attached or resumed worker it runs as `/llm-context` before the first prompt (after `--model`'s `/model`). A value that isn't one is an error before anything starts. See "LLM context: a session's own strategy" in configuration.md. |
 | `--llm-context-apply RULE` | This session's own apply rule: `payoff`, `next_request` or `turn_end`. |
@@ -291,7 +292,7 @@ of UIs at once: the Web UI and attached terminals (`chi`, `--resume`,
 a prompt, also while a turn runs (it merges into that turn as steering: the model
 is told it is a steer and who sent it). Steering waits for the model's next step
 and cuts nothing. `/cut TEXT` in a terminal or the web composer (or `chi send --cut`) asks for a cut:
-once the model has streamed only thinking for `steer.cut_after` seconds (default
+once the model has streamed only thinking for `steer.cut_after` seconds (per host/model: `steer_cut_after`; default
 20), now or while your message waits, that generation is cut and the step starts again with your message, marked
 `↪ cut in for your message` (see
 [configuration.md](configuration.md#messages-during-a-running-turn-steer-and-cut)). The web
@@ -504,7 +505,8 @@ back from the next turn on, and where that came from (`session`,
 comes first; `/reasoning-history default` unsets it. It is saved and carried as
 `/thinking`'s is, and a native host ignores it (the reply says so). A change to
 or from `all` once an earlier reply has thinking rewrites the earlier replies;
-`drop` ↔ `turn` costs nothing. `/stats` shows it on its `reasoning history:`
+`drop` ↔ `turn` costs nothing. Under `turn` a step-limit Continue keeps the
+reasoning of the turn it continues. `/stats` shows it on its `reasoning history:`
 line, the web as the `reasoning` chip. See "Reasoning history" in
 [configuration.md](configuration.md).
 
@@ -530,11 +532,12 @@ REPL alike:
   does one sent after Ctrl-C: it doesn't merge into the turn being cancelled.
   Reminder turns take merged lines too.
 - `/cut TEXT` asks for a cut: a generation that has streamed only thinking for
-  `steer.cut_after` seconds is cut and the step starts again with TEXT. The dim
+  `steer.cut_after` seconds (per host/model: `steer_cut_after`) is cut and the
+  step starts again with TEXT. The dim
   line says what happened: `(cut in now)`, `(cuts in once the thinking passes
   20 s)` (it waits for the thinking; the step may end first) or `(cutting is
-  off; goes in at the next step)` (`steer.cut_after: 0`, or no generation to
-  cut).
+  off; goes in at the next step)` (`steer.cut_after` is 0, per host/model:
+  `steer_cut_after`, or no generation to cut).
 - `/queue TEXT` (plain REPL only) runs TEXT as a turn of its own after this
   one: `(queued: runs after this turn)`. An attached terminal says
   `(/queue isn't available in an attached session yet)` and sends nothing (the web
@@ -996,7 +999,7 @@ Behavior notes:
 ## Iteration Limit Behavior
 
 - A turn's step limit (model ↔ tool rounds) is `turn.max_iterations` in config.yml (env
-  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `100`, an integer of 1 or more). `--no-interrupt` and
+  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `300`, an integer of 1 or more). `--no-interrupt` and
   `--non-interactive` turns get the larger of 1000 and it. Reminder turns follow it too.
 - Tool side effects that already ran before the limit are not rolled back.
 - `Samagotchi::KernelLoop#run` returns a resumable result object with the visible output plus the accumulated
@@ -1015,9 +1018,13 @@ Behavior notes:
 - In the plain REPL (`--no-shared`) the CLI asks at the `? ` prompt, with the choices listed under it: `yes` (Enter
   alone, or `/continue`) resumes, `no` stops, and `no, <explanation>` stops while keeping the reason in conversation
   context. Once answered, one line stays: `? The turn ran out of iterations. Continue it? → no, too slow`.
+- Continue goes on with the same turn: the model keeps the reasoning (thinking) of the run it continues, on chat and
+  native hosts, so a local server's prompt cache stays warm. Continue's text is a steer: on a chat host the reasoning
+  starts again from it. See "Reasoning history" in [configuration.md](configuration.md).
 - Stop keeps the interrupted turn's work in the conversation, as a Ctrl-C or a new prompt does, with a note for the
   model that it wasn't continued (or your reason); `!rollback` still erases it.
 - `--non-interactive` (`chi -p`) has nobody to ask: the turn ends there. A `chi send --wait` on a session nobody can
   answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`.
 - The check-in bundle's card closes as the turn ends, before the step-limit question opens, so the two never stand
-  together; with check-in's default `after: 50` and the limit of 100 a long turn usually shows a check-in card first.
+  together; with check-in's default `after: 50` and the limit of 300 a long turn shows check-in cards (at 50, 100, …)
+  well before it.

data/docs/configuration.md

@@ -81,6 +81,13 @@ session:
 memories:
   # - system/user_preferences
   # - project/feature-env-template
+
+# Files whose text goes into the system prompt after AGENTS.md (same as
+# --append-system-prompt, which adds to these). A relative entry is looked up
+# in the directory chi runs in; a missing one is skipped.
+append_system_prompt:
+  # - CLAUDE.md
+  # - ~/notes/house-rules.md
 ```
 
 Behavior:
@@ -108,8 +115,8 @@ Besides the settings sections, the file holds maps that are read by their
 own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
 "Images"), `model_aliases:`, `hooks:` (see [Hooks](hooks.md)),
 `guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
-settings for its hooks, see [Hooks: Settings](hooks.md#settings)) and
-`memories:`. Their entry names (host names, model ids, aliases) are yours to
+settings for its hooks, see [Hooks: Settings](hooks.md#settings)),
+`memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
 choose. The `memories:` list is the persistent baseline for preloaded memory entries —
 the same name shape as `--memory` (bare name or `scope/name`), merged under
 any per-run `--memory` values (config baseline first, deduped). A per-run
@@ -561,8 +568,13 @@ models:
   reasoning as `reasoning_content`, which is what Qwen's, Gemma 4's and DeepSeek's chat templates and the hosted APIs
   (OpenRouter takes it for DeepSeek, Qwen and other text-reasoning models) expect. The running turn starts at the
   last message you sent (a prompt, or a steer: as the chat template counts it) and never before the turn's own start,
-  so a turn that goes on by itself (a reminder, a context wake, a continue after a stop) sends nothing of the one
-  before it, an interrupted reply's partial thought included.
+  so a turn that goes on by itself (a reminder, a context wake, a delegate report's wake) sends nothing of the one
+  before it, an interrupted reply's partial thought included. A **step-limit Continue** is the same turn going on: it
+  keeps the reasoning of the run it continues (back to the first run of a chain of Continues), so its first request
+  matches the last one before the limit and the server's prompt cache stays warm. Continue's text, or a `!cmd` run
+  while the step-limit question stands, is a user message: the reasoning before it goes, as for any steer, and that
+  Continue reads the conversation again once (a re-prefill on a local server). After a `/model` change while the
+  question stands the Continue starts afresh (no other model's reasoning is sent).
 - `drop` sends none (what chi did before this setting).
 - `all` sends every reply's reasoning, earlier turns too. It sends only the field: a local template that leaves out
   earlier turns' reasoning (Qwen's) needs `sampling: {chat_template_kwargs: {preserve_thinking: true}}` as well.
@@ -586,7 +598,8 @@ models:
   | nothing thought yet, the same level, or a native host | none |
 
 - The native loop (`/completion`) ignores it: it always keeps the running turn's reasoning, a mid-turn steer included
-  (the chat loop starts again after a steer).
+  (the chat loop starts again after a steer), and a step-limit Continue keeps the thoughts of the run it continues,
+  a mid-turn steer's earlier ones included.
 - When a host answers a request that sent reasoning back with an HTTP 400 about reasoning, chi asks again without it,
   sends none to that model from then on (until the worker restarts) and says so once. If the request without it is
   refused too, the thinking fields get the same fallback ("Thinking") and the reasoning goes back on the next step.
@@ -876,26 +889,39 @@ Assist-mode UX:
 ## Messages during a running turn: steer and cut
 
 A message for a running turn goes in at its next step and cuts nothing. A message sent as a cut (`/cut TEXT` in a
-terminal or the web composer, `chi send --cut`) cuts the model's generation once it has streamed only thinking for `steer.cut_after`
-seconds (default `20`, env `SAMAGOTCHI_STEER_CUT_AFTER`, `0` = never; counted from its first thinking token, so the
-wait for a busy server doesn't count) and still does, and the model starts the step again with the message
-(`↪ cut in for your message`). One that comes earlier cuts once the thinking passes `steer.cut_after`, unless the
-step ends first and the message goes in there. A plain message (from the web composer, `chi send` without `--cut`,
-a parent agent) never asks for a cut. Such a cut spends no `retry.empty_answer` attempt and sends no hidden note; only
-the cut thinking is lost. A generation that has streamed visible text or a tool call is never cut, and a plugin's steer
+terminal or the web composer, `chi send --cut`) cuts the model's generation once it has streamed only thinking for
+that model's cut wait (`steer.cut_after` seconds, default `20`, `0` = never; counted from its first thinking token,
+so the wait for a busy server doesn't count) and still does, and the model starts the step again with the message
+(`↪ cut in for your message`). One that comes earlier cuts once the thinking passes it, unless the step ends first
+and the message goes in there. A plain message (from the web composer, `chi send` without `--cut`, a parent agent)
+never asks for a cut. Such a cut spends no `retry.empty_answer` attempt and sends no hidden note; only the cut
+thinking is lost. A generation that has streamed visible text or a tool call is never cut, and a plugin's steer
 (`ctx.steer`, `ctx.sessions.send`) never cuts.
 
-`/queue TEXT` in the plain REPL runs TEXT as a turn of its own after the running one; the attached terminal and the web
-don't queue yet, and a request that asks the Bridge or the web for `delivery: "queue"` is refused (400
-`delivery_unavailable`).
-
-`steer.cut_after` (default `20`, env `SAMAGOTCHI_STEER_CUT_AFTER`):
+The wait resolves per model, in this order: env `SAMAGOTCHI_STEER_CUT_AFTER`, then
+`models.<key>.steer_cut_after`, `hosts.<name>.steer_cut_after`, `steer.cut_after` in config.yml, then 20. `0` means
+never cut (a slow local thinker is left alone); a bad value warns and is ignored, like the other keys here.
 
 ```yaml
 steer:
   cut_after: 20   # seconds of thinking-only output before a cut may land; 0 = never
+
+hosts:
+  splash:
+    host: splash.lan
+    steer_cut_after: 0   # never cut: a slow local thinker
+
+models:
+  qwen:
+    steer_cut_after: 60  # a big model thinks a while before it answers
 ```
 
+`/model` shows the resolved wait (`; steer cut: after 60 s (models: qwen)`, `; steer cut: never (hosts.splash)`).
+
+`/queue TEXT` in the plain REPL runs TEXT as a turn of its own after the running one; the attached terminal and the web
+don't queue yet, and a request that asks the Bridge or the web for `delivery: "queue"` is refused (400
+`delivery_unavailable`).
+
 ## Server errors
 
 An error status or a server's error event fails the turn with the server's
@@ -1058,15 +1084,52 @@ The helper reads these from its launch file: after editing them run
 
 ## Project specific description
 
-If an AGENT.md file is present in the project root, samagotchi injects its
+If an AGENTS.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`).
+worktree's own checkout), or the current directory outside a repository.
+
+Started in a subdirectory, chi loads the chain: every AGENTS.md from the work
+tree top down to the current directory, outermost first. The first keeps the
+plain header; each further one is headed with its directory, e.g. "Project
+specific description for pkg/:". Outside a repository only the current
+directory's AGENTS.md is read. Edits are picked up by a new process or a
+prompt rebuild (`/model`).
+
+To skip loading AGENTS.md (all of the chain), set `skip_agents_md: true` at the top level of
+`config.yml` (env `SAMAGOTCHI_SKIP_AGENTS_MD=true`).
+
+Nested `AGENTS.md` files (in directories the session doesn't run in) are
+steered into the conversation on first touch by the `agents-md` bundle
+([The agents-md bundle](plugins.md#the-agents-md-bundle)); `skip_agents_md`
+disables that steering too.
+
+## Appended prompt files
+
+`append_system_prompt:` (a top-level list) and `chi --append-system-prompt FILE`
+(repeatable) put a file's text into the system prompt right after the AGENTS.md
+chain and before the memory indexes, in the stable part a prompt cache keeps.
+Each file is one section, `Appended from <path>:`, the path relative to the
+work tree top when inside it, else with `~`.
+
+- The config list comes first, then the flag's files; a repeat, or a file the
+  AGENTS.md chain already holds, is left out, and so is an empty file.
+- A config entry: `~` is expanded, and a relative one is looked up in the
+  directory chi runs in, so `append_system_prompt: [CLAUDE.md]` loads a
+  project's `CLAUDE.md` wherever there is one. A missing entry is skipped
+  without a warning. The list is read when the session's engine starts (a new
+  process picks up an edit).
+- `--append-system-prompt FILE`: relative to the shell's directory. A missing,
+  unreadable or non-file `FILE` stops chi (`Error: --append-system-prompt FILE:
+  no such file`); above 32,000 chars it warns once (`… is N chars; it is in
+  every request`). The files are saved in the session (`appended_prompt_files`),
+  so a respawned worker builds the same prompt, and a fork or a continue keeps
+  them; a delegate child doesn't. With `--attach` or `--resume` the flag is
+  ignored with one line, as `--memory` is; a REPL `--resume` (`--no-shared`)
+  adds them for that run only.
+- The files' text is read at each prompt build, as AGENTS.md's is: an edit is
+  picked up by a new process or a rebuild (`/model`). `/stats` lists the files
+  in the prompt on its `prompt files:` line.
 
 ## LLM context: the forget layer
 
@@ -1206,8 +1269,8 @@ Every setting below takes the three forms described in
 `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.
+`model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`,
+`append_system_prompt:`) are described in their own sections.
 
 | Setting | Default | CLI | What it does |
 |---|---|---|---|
@@ -1291,8 +1354,9 @@ described in their own sections.
 | `retry.base_delay` | `0.5` | yes | |
 | `retry.max_delay` | `8.0` | yes | |
 | `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
-| `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. See [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
-| `turn.max_iterations` | `100` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
+| `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. `models.<key>.steer_cut_after` and `hosts.<name>.steer_cut_after` come first; see [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
+| `models.<key>.steer_cut_after`, `hosts.<name>.steer_cut_after` | none | | A model's or host's seconds a cut waits for its thinking: whole seconds, `0` = never (e.g. a slow local thinker). `/model` shows the resolved one. See [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
+| `turn.max_iterations` | `300` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
 | `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |
@@ -1307,7 +1371,8 @@ 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` | `120` | yes | Seconds one `execute` command may run before it is stopped. |
+| `execute.timeout_sec` | `120` | yes | Seconds one `execute` command may run before `execute.on_timeout` applies. |
+| `execute.on_timeout` | `task` | yes | What happens to a command still running at that limit: `task` keeps it running as a background task (the result names its `task_id`; `task_wait` waits for it, `task_stop` stops it), `kill` stops it (`Error: command timed out after …s`). The `!cmd` bang always kills. See [Background tasks](internals/background-tasks.md). |
 | `execute.description` | `true` | | `execute` offers the model an optional `description` (a few words on what the command does), shown as the tool row's title in `chi web` and in place of the command in the TUI's tool line. `false`: the parameter isn't declared, and rows show the command's first step. |
 | `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). |
@@ -1318,8 +1383,8 @@ described in their own sections.
 | `history.file` | state dir | | Prompt history path, shared by the TUI and the web composer. |
 | `no_interrupt` | `false` | `--no-interrupt` | Raise the step limit of a turn to 1000 (or `turn.max_iterations`, when larger); a top-level key. |
 | `no_default_input` | `false` | `--no-default-input` | Don't pre-fill `default.input`; a top-level key. |
-| `skip_agent_md` | `false` | | Don't load AGENT.md; a top-level key (see below). |
+| `skip_agents_md` | `false` | | Don't load AGENTS.md; a top-level key (see below). |
 
-`max_tool_output_chars`, `skip_agent_md`, `no_interrupt` and
+`max_tool_output_chars`, `skip_agents_md`, `no_interrupt` and
 `no_default_input` have no section: in `config.yml` they are top-level keys as
 written (`max_tool_output_chars: 20000`).

data/docs/hooks.md

@@ -50,13 +50,13 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | Event | When it fires | Event payload |
 |-------|--------------|---------------|
 | `:session_start` | The first turn this chi process runs for the session (so again after `--resume`, a worker that idle-exited and woke, or a restart) | `{ type: :session_start, session_id: "..." }` |
-| `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
+| `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), resumed: true \| false (true on a step-limit Continue, which resumes the run before it; false on every other turn, a reminder's or a wake's too), messages: [...] (the history before this turn) }` |
 | `:after_turn` | After a turn completed or was stopped once the model was asked (not after one that failed, was cut short by an interrupt signal (SIGINT), or was stopped before its `:before_turn` hooks) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N, restarted: true (only on the first fire after a dropped stream was asked again) }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
-| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (the text the model gets: capped at max_tool_output_chars, a cut one ending in a [cut: N of M chars …] line), status: "ok" \| "error" \| "blocked" \| "stopped", call: {...} (the call that ran, as the gate left it), elapsed_ms: N (the tool's own run, without an approval wait; nil for a denied call), result: "..." (the tool's own text: no "[read]" lead, no "ran as:" line, never cut) }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped. Match on `result:`, not `output:`: it is what the tool said (`Error: command timed out after 120s` for an execute killed at its limit, `Samagotchi::Tools::Execute::TIMEOUT_PREFIX`) |
+| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (the text the model gets: capped at max_tool_output_chars, a cut one ending in a [cut: N of M chars …] line), status: "ok" \| "error" \| "blocked" \| "stopped", call: {...} (the call that ran, as the gate left it), elapsed_ms: N (the tool's own run, without an approval wait; nil for a denied call), result: "..." (the tool's own text: no "[read]" lead, no "ran as:" line, never cut) }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped. Match on `result:`, not `output:`: it is what the tool said (`Error: command timed out after 120s` for an execute killed at its limit in kill mode, `Samagotchi::Tools::Execute::TIMEOUT_PREFIX`; `Still running at the 120s limit: …` for one handed over as a task, `Samagotchi::Tools::Execute::HANDED_OVER`) |
 | `:session_end` | After each turn `:after_turn` fires for, after it (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
 Every event also carries the hook runtime (next section): `hook:` (the label
@@ -117,7 +117,7 @@ known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
 `event[:notify]` also takes `fallback_for:`, what the line stands in for, so
-that a UI that already shows it can leave the line out. The one value is
+that a UI that already shows it can leave the line out. The main value is
 `:display`: the line repeats what the hook's
 [`event[:present]`](#presenting-the-answer-display-only) display shows (its
 links), for a UI that doesn't render that display. The hook never names a UI;
@@ -125,7 +125,13 @@ each decides by what it renders. The web with markdown on (`web.markdown` and
 the commonmarker gem) leaves such a line out, live and after a reload; with
 markdown off it shows, as it does in the REPL, the attached TUI and
 `chi -p`, which print the answer as text. The log keeps the line with
-`fallback_for=display`. Another value, or none, shows the line everywhere.
+`fallback_for=display`. `:editor` marks a line that names a file the viewer
+could open from a ref in its editor: the web leaves it out for a viewer on
+this machine with `web.editor` set, and every other UI and viewer (a phone,
+the terminals) shows it. Name only a file the page shows as a ref (one a
+tool row touched): a loopback viewer with `web.editor` set never sees the
+line, so a file it can't open from a ref would be lost to it. Another value,
+or none, shows the line everywhere.
 Mark a line only when the display really shows all of it (source-links marks
 its note only when the answer links every URL the note names). It needs chi
 0.35.0: an older chi's `event[:notify]` raises `ArgumentError` on the keyword,
@@ -222,7 +228,7 @@ What a cut is, in detail:
 - A Stop from the user right after a cut is a plain cancel.
 - A cut for a message (one sent as a cut, `/cut TEXT` or `chi send --cut`,
   into a generation that has streamed only thinking for `steer.cut_after`
-  seconds; other messages go in at the next step and never cut)
+  seconds, per host/model: `steer_cut_after`; other messages go in at the next step and never cut)
   is not a plugin's cut: it sends no hidden note and spends no retry; the
   message goes in and the UIs print `↪ cut in for your message`. The
   stream's `generation_completed` says `stopped_by: "steer"`, and
@@ -507,7 +513,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
+- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:

data/docs/internals/background-tasks.md

@@ -20,7 +20,14 @@ Behavior:
 - `execute`, `task_create` and the `!cmd` shell bang run the command in a non-login shell: `/bin/sh -c` on Linux; on macOS, when `/bin/zsh` is there, `/bin/zsh --emulate sh +o ignore_braces +o sh_glob -o bash_rematch +o bsd_echo -c` (macOS's `/bin/sh` is bash 3.2, which can't parse an apostrophe in a heredoc inside `"$( )"`, the usual commit message shape). That mode reads no rc files and keeps POSIX word splitting, unmatched globs left as is, `{1..3}`, `[[ … =~ (…) ]]` with `BASH_REMATCH`, arrays, `$'…'`, `&>` and echo expanding `\t`. Bash-only builtins and variables (`shopt`, `BASH_VERSION`, `${!prefix*}`, `read -p`) are not there.
 - Task metadata and output are persisted under `tmp/tasks/`.
 - A task record keeps its process's pid and start time (`pid_started`). Before `task_stop` signals, the pid must still lead its own process group and must not have started at another time; otherwise the pid was reused by another process, nothing is signalled and the task ends as failed. A start time that can't be read at that moment (a failed `ps`) falls back to the group check, as does a record without `pid_started` (from an older chi). `task_get`, `task_list`, `task_wait`'s polls and the running-task lists (a cancelled turn's note, a worker's idle exit) make the same check, so a task whose pid was reused reads as exited (failed) at once, not as running until a `task_stop`; on macOS that is one `ps` per running task per check (~5 ms).
+- A stop (`task_stop`, the user's Stop of an `execute`, the execute limit in kill mode) TERMs the task's process group, then KILLs it after a grace. The groups its processes started are stopped too: a GNU `timeout N cmd` (without `--foreground`) moves itself and its command to a group of its own. `ProcessGroup.stop` finds them with one `ps -A -o pid=,ppid=,pgid=` (~40 ms on macOS) before the TERM and again before the KILL, walking down from the group's members. A process whose parent already exited (reparented to init, e.g. a setsid'd `cmd &`, or a backgrounded `timeout N cmd &` after its shell exited) is not found and runs on.
 - Task listing is workspace-scoped (current project only).
+- `execute` runs its command with stdout and stderr in two logs under `$XDG_STATE_HOME/samagotchi/execute/<id>/` (outside the workspace: `git status` and `rm -rf tmp` never see them), stdin `/dev/null` and the same `exit_code` wrapper as a task. Its own copies of the logs hold a shared `flock` across the spawn: while a fresh exclusive `flock` fails, some process the command started still has them open. When the shell exits, a background child still holding them (`server &`) gets 1.5 s, then its group is stopped; one holding none (`nohup server >log 2>&1 &`) is left alone. A holder that left the group (setsid) is out of the stop's reach: it runs on, the result ends with the "left running" hint, and its dir stays for it to write to (the sweep removes it once no one holds the logs). Otherwise a finished command's dir is removed. Known gap on Linux: a command that writes through `/dev/stdout` or `/dev/stderr` (`echo b >/dev/stdout`) reopens the log file itself with `O_TRUNC`, so the output before it is lost (macOS dups the descriptor; the fix would be a relay pipe). The check needs the state dir on a local file system: over NFS, `flock` is emulated with `fcntl` locks, which children don't inherit.
+- The exit code: the command runs after an EXIT trap that writes the shell's status to the `exit_code` file (`TaskRuntime.wrapped_shell_command`, shared with `task_create`), so `exit N`, a `set -e` failure and a trailing `\` or `|` in the command all record what the shell exited with. A command that sets its own EXIT trap replaces it: `execute` still reports the shell's status, and a handed-over one gets its code from chi's waiter while that chi runs; a `task_create` task ends failed with no exit code.
+- A stop of an `execute` (the user's Stop, the limit in kill mode) is done once the shell is reaped and nothing holds the logs: a child that ignores TERM after its shell died gets the KILL.
+- A command still running at `execute.timeout_sec` is handed over as a task (`execute.on_timeout: task`, the default; `kill` stops it instead, and the `!cmd` bang always kills): the result starts `Still running at the 120s limit: moved to a background task, not killed.`, then `task_id: …` and the tails of both logs so far. A timeout during the 1.5 s background grace is a kill (the shell is gone, nothing to hand over). If the record can't be written, the command is killed. `TaskRuntime.adopt` writes a record for the process execute already started, with `handed_over_by: "execute"`. Its logs stay where execute wrote them, so the record's paths are absolute: `output_path` (stdout), `stderr_path` (stderr, a log of its own) and `exit_code_path`. `started_at` (and `created_at`) is the spawn time, not the hand-over's; `pid_started` is read at the hand-over, while execute's detach waiter is still running. From there it is an ordinary task: `task_wait`, `task_get`, `task_list` and `task_stop` treat it as any other. Its dir gets a `task` back-pointer file holding the record's absolute path. Once per process, the first `execute` sweeps `…/execute/`: a dir whose logs no process holds is removed when it has no back-pointer and is a day old (chi died mid-command), when its record is gone, or when it is 14 days old. The records live in each project's `tmp/tasks`, which the state dir can't list: hence the back-pointer.
+- `task_wait` and `task_get` show `stderr_path` when the record has one; where `task_wait` returns an output tail, a `stderr_tail:` of at most 10 lines follows it when that log isn't empty. A `task_create` task has one log (stdout and stderr together) and no `stderr_path`.
+- Which tasks are a session's own (a cancelled turn's note, the turn-end note, a worker's idle exit, the web's stop-task button): the ids its `task_create` results and its handed-over executes name (`TaskRuntime.created_ids_in`, `created_id`). An execute's id is read only after its first line (`Execute::HANDED_OVER`, through `TaskRuntime.handed_over_id`; the web has a JS twin in `task_stop.js`), not from a `task_id:` line inside a run, which the command can print. (A command that prints the `---` separator chi joins a turn's results with, then a hand-over line, still fakes one: a known gap.) Either result may start with the `ran as: …` line of a gate-corrected call.
 - `task_get` returns metadata and `output_path`; use `read` for output contents.
 - `task_wait` accepts `timeout`, `tail_lines` (maximum 100), and `done_pattern` (a regular expression string).
 - `task_create` accepts `env` as a JSON object string for deterministic overrides such as `PATH`; use an absolute interpreter path when that is simpler. Ruby/Bundler isolation variables remain protected.