samagotchi 0.58.0 → 0.59.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6049cfd1f36b6aa77b8dfdfd9d437693f1d0c08257eb327838ccf9134db9fa27
-  data.tar.gz: d10c78ddf6e21e39689c3012214d4362844e090cac3624863a7a26195cc09769
+  metadata.gz: 399c5b5b4ad3423bd266545c1f190e9e269f070a26bc48350640bf774eea7c4b
+  data.tar.gz: 26bfce90ed8fe75c15c777943f07699803f70160f54559ae057ba31eb168d956
 SHA512:
-  metadata.gz: 240fb5fc4a45ae15088c690cc45c034f8ced20a9b6844649719ebfe25b9cf8801ecc90601d2c464d8e24a9fe75feadc0d541c8fe3e2c9784a2bd65fce9c31767
-  data.tar.gz: 64353c0287ded0c59631dec4af9319592d354ae1dc6c3d8609c65fffb60554a841453c060580233884cc1d8f4ed93dcfdb4434bd2fe5bfedeb57fb9f51c9cc3a
+  metadata.gz: 042a3460c486987f7bd120fa6615c5cdd65d1ca6da0edfe9548746b83d9b66c6ad532b7088c20af082751b9bfad64252fba93123845fb36cfa0875d1a54ec0bf
+  data.tar.gz: f441e37232ea17b6af0ca047aea5331d7e062b3563382656fb323118f8607459cf97540858fccae714691aabfe989dd666f8de379f2024bc7a4b024864b2a694

data/CHANGELOG.md

@@ -8,6 +8,42 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [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 +2576,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.58.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.59.0...HEAD
+[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/docs/architecture.md

@@ -176,8 +176,8 @@ 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, `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 +198,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).

data/docs/cli.md

@@ -291,7 +291,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
@@ -530,11 +530,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

data/docs/configuration.md

@@ -876,26 +876,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 +1071,15 @@ 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
+AGENTS.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`).
+To skip loading AGENTS.md, set `skip_agents_md: true` at the top level of
+`config.yml` (env `SAMAGOTCHI_SKIP_AGENTS_MD=true`).
 
 ## LLM context: the forget layer
 
@@ -1291,7 +1304,8 @@ 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). |
+| `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` | `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). |
 | `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). |
@@ -1307,7 +1321,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 +1333,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

@@ -56,7 +56,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | `: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
@@ -222,7 +222,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

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.

data/docs/internals/engine.md

@@ -29,7 +29,7 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │
   ├── prepare_turn(turn, images)
   │     # Emits :turn_started {session_id, prompt, turn_id, continue: true (only on a continue),
-  │     #                      images (only when there are any)}
+  │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
   │     # refresh_profile! (may ask the server's /props once)
   │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name is set in generate)
   │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools
@@ -298,12 +298,12 @@ What the running generation streams, fed by the Engine's stream handler: whether
 `cut`: `/cut TEXT`, `chi send --cut`) may cut it. `SteerCut#cut_for_steer` answers `:now`, `:waits` or `:off`; the
 Bridge acks it as `cut`.
 A generation is cuttable while it has streamed only thinking, is still thinking, and has thought for at least
-`steer.cut_after` seconds (`cuttable?(min_age)`). It has `started!`, `chunk!`, `retrying!` and `finished!`.
+the model's cut wait (`SteerCutAfter.resolve`: `steer_cut_after` per models:/hosts: entry, else `steer.cut_after`) seconds (`cuttable?(min_age)`). It has `started!`, `chunk!`, `retrying!` and `finished!`.
 
 ### WaitingSteer
 
 A message that may cut the generation but came too early (the generation hadn't been thinking long enough). It
-waits until the thinking passes `steer.cut_after` (the Engine checks on each thinking chunk), until a drain hands
+waits until the thinking passes the model's cut wait (the Engine checks on each thinking chunk), until a drain hands
 the message to the model at a boundary, or until the turn ends (`clear!` in `release_turn`).
 
 ## Events
@@ -322,7 +322,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 
 | Event | When | Payload |
 |---|---|---|
-| `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, images?}` |
+| `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, images?, cut_after}` |
 | `:reminder_injected` | due reminders went into the turn | `{reminders}` |
 | `:context_status` | every request (unless `context.status` is off), the current estimate before it | `{iteration, status, usage, bucket, source}` (internals/context-telemetry.md) |
 | `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price}` (`price`: the turn's `ModelPrice#to_h`, nil without one; native adds `profile`, `profile_source`) |
@@ -495,7 +495,7 @@ thought after the cue, kept in the model message so the next prompt starts with
 5. **A stable system prompt for the cache.** `SystemPrompt#build` caches the prompt per Engine, keyed by
    `[chat, thinking, layers]` (chat/native, the thinking level, the turn's LLM context layers), and is reset
    only on a model switch, a tools change or a profile change. The stable part (base prompt, identity,
-   memories, AGENT.md, memory indexes) comes before the volatile tail (model, working directory, session).
+   memories, AGENTS.md, memory indexes) comes before the volatile tail (model, working directory, session).
    prompt-caching.md covers this in detail.
 
 ## Key files

data/docs/internals/prompt-caching.md

@@ -29,9 +29,9 @@ right-hand column happens.
 │   [native thinking token] base prompt                                    │
 │   rg guidance                                                            │  /thinking level,
 │   system identity (+ model overlay)                                      │  /model, editing a
-│   model notes (model_notes_* matching the model)                         │  memory / AGENT.md
+│   model notes (model_notes_* matching the model)                         │  memory / AGENTS.md
 │   explicit (preloaded) memories                                          │
-│   AGENT.md                                                               │  (picked up by a new
+│   AGENTS.md                                                              │  (picked up by a new
 │   project + system memory indexes                                        │  process or a rebuild)
 │                         ◄── remote Claude: cache_control breakpoint #1   │
 ├──────────────────────────────────────────────────────────────────────────┤

data/docs/internals/tool-guardrails.md

@@ -39,7 +39,8 @@ Configuration (config.yml `execute.*` keys and CLI flags too, as for `read`):
 - `SAMAGOTCHI_EXECUTE_TRUNCATE_AT_BYTES` (default `65536`): output above this size is truncated.
 - `SAMAGOTCHI_EXECUTE_PREVIEW_BYTES` (default `12288`): total preview budget split across head and tail.
 - `SAMAGOTCHI_EXECUTE_TELEMETRY_THRESHOLD_PCT` (default `80`): include estimated output token impact only when threshold is crossed.
-- `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC` (`execute.timeout_sec`, default `120`): a command running longer is stopped and answers `Error: command timed out after …s`.
+- `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC` (`execute.timeout_sec`, default `120`): what a command still running then gets is `execute.on_timeout`.
+- `SAMAGOTCHI_EXECUTE_ON_TIMEOUT` (`execute.on_timeout`, default `task`): `task` hands the command over as a background task, not killed; the result starts `Still running at the 120s limit: moved to a background task, not killed.` (`Execute::HANDED_OVER`), then its `task_id:` and the tails of stdout and stderr so far, and `task_wait` waits for it. `kill` stops it and answers `Error: command timed out after …s` (`Execute::TIMEOUT_PREFIX`) with the hint to use `task_create`. The `!cmd` bang always kills. See [Background tasks](background-tasks.md).
 
 Implementation note:
 

data/docs/plugins.md

@@ -1178,12 +1178,14 @@ bootstrap` installs it with the `core` profile). It is written only against
 this API (`lib/samagotchi/bundles/slow-commands/plugin.rb`), with `chi.on`
 hooks and a `/slow-commands` command, and has no memory file.
 
-`execute` kills a command at its limit (120 s, `execute.timeout_sec`). A full
-test suite or a build takes longer, so the model loses those two minutes,
-then starts it again with `task_create` and `task_wait`; the next session
-does the same. slow-commands remembers such a command for the project:
-
-- An `execute` that **timed out**, or ran **`warn_ratio` of the limit** or
+At its limit (120 s, `execute.timeout_sec`) `execute` hands a command still
+running over as a background task (`execute.on_timeout: task`, the default),
+or kills it (`kill`). A full test suite or a build takes longer, so each run
+first blocks the turn for those two minutes (and, in kill mode, loses them,
+then starts again with `task_create` and `task_wait`); the next session does
+the same. slow-commands remembers such a command for the project:
+
+- An `execute` that **timed out** or was **handed over** at the limit, or ran **`warn_ratio` of the limit** or
   longer (default 0.8, so 96 s of 120), is recorded as slow. A later run of
   it under half the limit **with exit 0** drops the entry; a fast failure (a
   load error) doesn't, since it says nothing about how long the suite takes.
@@ -1203,6 +1205,10 @@ does the same. slow-commands remembers such a command for the project:
 - **Once per command per turn**: the same `execute` again in that turn runs.
   The model insisting is a signal (maybe the suite got faster), and that run
   records the new truth. A new turn denies again.
+- In kill mode (`execute.on_timeout: kill`), a **`timeout N` past the limit**
+  is denied up front, with no history: execute stops the command first, so
+  `timeout` never fires. In task mode it runs on as a task until `timeout`
+  fires. `timeout`'s exit codes (124, 137) mean nothing special here.
 
 A command is the same when its project and its text match. The project is
 the session's git checkout (else its working directory). The text is the
@@ -1216,6 +1222,20 @@ one with a `$(…)`, backticks or a heredoc `cat` or `tee` reads (the key
 can't tell two of those apart). A heredoc script (`python3 - <<'EOF'`)
 keeps its body in the key, so each script is its own command.
 
+Wrappers a model adds by habit don't make a new command: at the start of
+each simple command (so after a leading `cd X &&` too), `time [-p]` and
+`timeout`/`gtimeout` with its options and duration are left out, so
+`timeout 300 bundle exec rspec` and `bundle exec rspec` are one entry. `X=…`
+assignments stay, sorted (`SPEC=… rake spec` is not `rake spec`), except
+`NO_COLOR`, `FORCE_COLOR` and `TERM` (`CI` stays: jest or vitest without it
+can sit in watch mode); a plain `env X=… cmd` is `X=…
+cmd`, and an `env` with an option (`-C`, `-i`, `-u`) stays as typed. The
+list shows each entry as it was last typed.
+
+Since 0.2.0 (chi 0.59.0) a hand-over counts as timed out, and the advice's
+duration also reads a handed-over task, whose `exit_code` file is in the
+state dir (the record's `exit_code_path`).
+
 Entries live in `$XDG_STATE_HOME/samagotchi/plugins/slow-commands/commands.json`,
 shared by every session (another session's record counts at once) and
 forgotten after `ttl_days`.

data/docs/sessions.md

@@ -158,7 +158,7 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 ```
 
 - With both stdin and `-m`, stdin is context: each line becomes a `> ` quote (as web annotations quote a selection), then a blank line, then the message. With only one, it goes in as is. A terminal on stdin is ignored. Both empty is a usage error; over 16 KiB is refused, never cut.
-- It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then, and cuts nothing. `--cut` asks for a cut, as `/cut TEXT` in a terminal does: a generation that has streamed only thinking for `steer.cut_after` seconds is cut (now, or once its thinking passes that), and the step starts again with the message. To an idle session `--cut` sends normally. `--cut --wait` into a running turn is refused like any `--wait` there (`busy: a turn is running`).
+- It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then, and cuts nothing. `--cut` asks for a cut, as `/cut TEXT` in a terminal does: a generation that has streamed only thinking for `steer.cut_after` seconds (per host/model: `steer_cut_after`) is cut (now, or once its thinking passes that), and the step starts again with the message. To an idle session `--cut` sends normally. `--cut --wait` into a running turn is refused like any `--wait` there (`busy: a turn is running`).
 - A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Only sessions on this machine: Bridges listen on 127.0.0.1.
 - Fire and forget: it returns once the message is queued and never prints the answer; that shows in whatever is attached. A guardrail "ask" waits for a UI to answer it, so with nothing attached the turn stalls there until one attaches (`chi --attach ID`).
 - `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image stops the send (exit 1; with `--wait --format json`, an `error` line) and nothing is sent; more than 20 is a usage error (exit 2). Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: one known not to (the host's model list says text-only, `vision: false` in `models:` or `hosts:`, a native llama.cpp without a vision model) is refused before anything is sent, with the reason (`<id>  refused: gemma can't take images (…); send text only or switch the model (/model)`); the other sessions of the same send still get it, and the exit is 1. With `--new` nothing is started. When chi can't tell (a native host whose `/props` doesn't answer, a list that doesn't say), the message is sent as before and a text-only model fails the turn in the session. A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -240,6 +240,7 @@ module Samagotchi
                     parts: [], pending_question: nil }
           @tool_started_at = {}
           @turn[:images] = event[:images] if event[:images]
+          @turn[:cut_after] = event[:cut_after] if event[:cut_after]
         when :input_merged
           @merged_origins = Array(event[:origins])
           dequeue(@merged_origins)

data/lib/samagotchi/bridge.rb

@@ -29,7 +29,6 @@ require_relative "version"
 require_relative "worker_sidecar"
 require_relative "relay_verifier"
 require_relative "relay_watcher"
-require_relative "tools/task_create"
 require_relative "tools/task_runtime"
 
 module Samagotchi
@@ -581,9 +580,13 @@ module Samagotchi
       [{}, 200, { status: record["status"], stop_reason: record["stop_reason"], task_id: task_id }]
     end
 
+    # The tasks this session started: its history's (created_ids_in) and
+    # this turn's rows, a task_create's or an execute handed over at its
+    # limit (only after its HANDED_OVER line: its output can print a
+    # "task_id:" line of its own).
     def own_task_ids
       running = Array(@accumulator.current_turn&.dig(:parts)).filter_map do |part|
-        part[:output].to_s[/\A(?:\[task_create\]\n)?task_id: (\S+)/, 1] if part[:kind] == "tool" && part[:tool] == Tools::TaskCreate::NAME
+        Tools::TaskRuntime.created_id(part[:tool], part[:output]) if part[:kind] == "tool"
       end
       Tools::TaskRuntime.created_ids_in(@engine.messages_checkpoint) | running
     end
@@ -873,6 +876,7 @@ module Samagotchi
       cut = @engine.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty? && Delivery.cut?(delivery)
       ack = { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id, delivery: delivery }
       ack[:cut] = cut.to_s if cut
+      ack[:cut_after] = @engine.steer_cut_after if cut == :waits
       [{}, 202, ack]
     end
 

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,11 +1,12 @@
 ---
 name: slow-commands
-version: 0.1.0
+version: 0.2.0
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:00a35b8f930d8f99a908b99c5eb3a5e97b1209c63c616037072580d92d3c8639
-# after_tool_call's call:, elapsed_ms: and result: (0.57.0)
-requires_chi: ">= 0.57.0"
+  sha256: sha256:bf2cfccbcadedcd85ea0b53f2d263c8729e14ed8cf310bca4a56affe50181292
+# Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
+# call:, elapsed_ms: and result: (0.57.0)
+requires_chi: ">= 0.59.0"