samagotchi 0.89.0 → 0.91.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7e58a54e40f49c1617636172def63d9e6a3eaa3384ac33e26c0b55c75332555
-  data.tar.gz: 063a36d57a613a117e62b2882883c22e1ce413044c1e6d18e66aa1c8af0d6d83
+  metadata.gz: e4a20c3555c1f3e592919853f9dc59a5067e7e42251d11dad2f3be844f118f90
+  data.tar.gz: 817bb797b870985aeb21789377eae7770225265d03c527bb9218a1ecd3c2376e
 SHA512:
-  metadata.gz: 879572f97fd05fdff6f15d4c91c3f3ce30d480ff0022b1ad3fb0220423c124004c67908f97e85ad6309302720671938cc90da80c6315de0134c9240a9b477feb
-  data.tar.gz: 0faf651033f823e4eadc87926d4c370e3e8eb714a4f8106d735110bfe7c8517972a70a4e960448ccda3b8ac1679c796e93b587070255803eb57e24e8c984a2b1
+  metadata.gz: 74b69c624e9e43882940e48bdf00d0bedb1172fd53f4094c30ef4250e15a4e7ae9fedba4fc9704b923d3b622bcad47950432d450c1c3c219f42a54186dacad58
+  data.tar.gz: ac112286f3eaa6364bd68cee410e4b580f8246215222a17ecd3781f2980d828eb12d47cc3b64c800e201f9a81662a0c2ee61627a1c485e4249f409c771b65744

data/CHANGELOG.md

@@ -8,6 +8,42 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.91.0] - 2026-10-19
+
+### Added
+
+- A background task the model left running (`task_create`, an `execute` handed over at its limit) that finishes
+  unseen wakes the idle session for a short turn opened by a `TASK FINISHED` note (exit code, duration, log tail).
+  `session.task_wakes`: `wake` (default), `queue` (a note for the next turn) or `off`.
+
+### Changed
+
+- The bundle-authoring doc says `chi bundle try` is the live check; its `chi send` recipe for checking the installed
+  copy is gone.
+
+### Fixed
+
+- `chi bundle try --json` reports always carry `timed_out`; a run cut by `--timeout` lists the tool calls it made
+  (name, status and duration; their arguments aren't saved) instead of an empty `tools`.
+
+Update with `chi update` (the system bundle 0.91.0), then restart `chi web`.
+
+## [0.90.0] - 2026-10-19
+
+### Changed
+
+- SSE `tool_call_started` carries no `call`, `turn_completed` no `result`; read `tool`/`params`/`view` and
+  `turn_summary.output`. `?raw=1` on the worker's stream shows them.
+- docs/bundle-authoring.md (the guide chi reads to write a bundle) makes edit → `check --fix` → `test` → `try` the
+  loop, with `install --dev .` while iterating and `try` as the live check; its test example runs as written.
+
+### Fixed
+
+- `chi -p` followed by one of chi's own flags (`chi -p --non-interactive "text"`, `-p -v`) now exits 2 with a usage
+  error instead of taking the flag as the prompt.
+
+Update with `chi update` (the system bundle 0.90.0), then restart `chi web`.
+
 ## [0.89.0] - 2026-10-19
 
 ### Added
@@ -3513,7 +3549,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.89.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.91.0...HEAD
+[0.91.0]: https://github.com/dm1try/samagotchi/compare/v0.90.0...v0.91.0
+[0.90.0]: https://github.com/dm1try/samagotchi/compare/v0.89.0...v0.90.0
 [0.89.0]: https://github.com/dm1try/samagotchi/compare/v0.88.0...v0.89.0
 [0.88.0]: https://github.com/dm1try/samagotchi/compare/v0.87.0...v0.88.0
 [0.87.0]: https://github.com/dm1try/samagotchi/compare/v0.86.0...v0.87.0

data/bin/chi

@@ -74,6 +74,7 @@ options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt")
 cli_overrides = {}
 
 # Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
+known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
 ARGV.each do |arg|
   next unless arg.start_with?("--") && arg.include?("_")
 
@@ -82,7 +83,6 @@ 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 --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -191,8 +191,33 @@ end
 # value (-p, --model …: the parser's own list) keeps its next word, so
 # `chi -p "--no-tool=x is broken"` is a prompt. A tool name never starts
 # with "-": `--no-tool --` or `--no-tool --model` is a missing argument.
-takes_value = parser.instance_variable_get(:@stack).flat_map do |list|
-  list.list.select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }.flat_map { |switch| switch.long + switch.short }
+switches = parser.instance_variable_get(:@stack).flat_map { |list| list.list }
+                                          .select { |switch| switch.is_a?(OptionParser::Switch) }
+switch_flags = switches.flat_map { |switch| switch.long + switch.short }
+known_flags = (known + switch_flags).uniq
+takes_value = switches.select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }
+                      .flat_map { |switch| switch.long + switch.short }
+reject_prompt_flag = lambda do |flag, value|
+  if known_flags.include?(value)
+    warn "Error: #{flag} needs the prompt text right after it (got the flag #{value}) (see chi --help)"
+    exit 2
+  end
+end
+index = 0
+while index < ARGV.size && ARGV[index] != "--"
+  arg = ARGV[index]
+  if %w[-p --prompt].include?(arg)
+    reject_prompt_flag.call(arg, ARGV[index + 1])
+    index += 2
+  elsif arg.start_with?("--prompt=")
+    reject_prompt_flag.call("--prompt", arg.delete_prefix("--prompt="))
+    index += 1
+  elsif arg.start_with?("-p") && arg != "-p"
+    reject_prompt_flag.call("-p", arg.delete_prefix("-p").delete_prefix("="))
+    index += 1
+  else
+    index += takes_value.include?(arg) ? 2 : 1
+  end
 end
 missing_no_tool = lambda do
   warn "Error: missing argument: --no-tool (see chi --help)"

data/docs/architecture.md

@@ -187,10 +187,15 @@ higher-level events so UIs get clean turn boundaries without inferring them:
   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)
+  `LLM::ModelResult`; Engine event (clients get it without `result`); `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
   stopped it, for `cancellation_reason: :hook`; else nil)
 
+These are the Engine's raw events. The worker's SSE projection omits `call` from
+`:tool_call_started` and `result` from `:turn_completed`; the answer remains in
+`turn_summary.output`.
+
 A turn started with `origin:` carries it on each of these (and `:turn_failed`).
 
 Every event is a `Hash` with a `:type` symbol key; the sink must not raise (the Engine
@@ -246,7 +251,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   `session_state_snapshot`. `?snapshot=1` joins with a snapshot frame instead of a replay;
   `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
   Each event goes out as clients get it (`Bridge::ClientEvent.project`, in `SSEWriter#write_event`, live
-  and replayed alike); only a `generation_chunk` changes, to chi's own format (the chunk contract below).
+  and replayed alike); `generation_chunk`, `tool_call_started` and `turn_completed` are projected to the
+  contracts below. The ring retains raw events for replay and `?raw=1`.
   `?raw=1` writes events as the engine emitted them, for debugging on the worker's port: `chi web`'s
   `/api/sessions/:id/stream` never passes it on (`Web::App#stream_query`).
   An attached terminal's stream (`EventStream` with `rediscover:`) looks for the session's live
@@ -265,6 +271,22 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
          "event_seq":812}
   ```
 
+  A `tool_call_started` frame keeps its row fields but omits the model's `call`:
+
+  ```
+  event: tool_call_started
+  data: {"type":"tool_call_started","iteration":2,"call_index":1,"tool":"write",
+         "params":"path=notes.txt","event_seq":812}
+  ```
+
+  A `turn_completed` frame omits `result`; `turn_summary.output` carries the answer:
+
+  ```
+  event: turn_completed
+  data: {"type":"turn_completed","turn_summary":{"output":"Done."},
+         "display_pending":false,"event_seq":813}
+  ```
+
   `counts` is `ContextUsage.normalize` of the provider's payload without `ctx_pct` (normalize computes it
   without the session's LLM context budget; a client counts `total_tokens` against the window or budget, as
   `ContextStatus#generation_done` does for the TUI) and with its nil keys left out: cumulative for the
@@ -337,8 +359,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
 - `POST /session/:id/exit` — ask the worker to exit now (`{client_id:}`). The worker checks with
   the event log held (`WorkerIdleExit#hold_for_request`): `200 {status: "exiting"}` and it leaves
   like an idle exit, or `409 {status: "held", reason:}` with `turn_running`, `input_queued`,
-  `continue_offered`, `client_connected` (a stream not named by the asker), `reminders` or
-  `starting`.
+  `continue_offered`, `client_connected` (a stream not named by the asker), `reminders`,
+  `background_tasks` (with `tasks: [{id, command}]`: tasks a finish wake watches) or `starting`.
 - `GET  /session/:id/state` — `session_state_snapshot` (JSON).
 - `GET  /session/:id/stats` — `Engine#stats_snapshot` for attached `/stats`: the metrics, with the context window and prompt profile asked from the server before the first turn.
 - `GET  /session/:id/snapshot` — the snapshot frame's content as one request (the web server renders
@@ -559,7 +581,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 
 | Component | Main file(s) | What it is |
 |---|---|---|
-| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
+| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`, `worker_wakes.rb`, `task_watch.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns and the wake turns nobody typed (delegate reports, a background task that finished unseen: [Finish wake](internals/background-tasks.md#finish-wake), attached context), exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
 | Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
 | Paths | `paths.rb` (`Paths`) | The XDG base dirs chi's files live under, read from the env on every call: `Paths.state_home` (`$XDG_STATE_HOME`, else `~/.local/state`) and `Paths.config_home` (`$XDG_CONFIG_HOME`, else `~/.config`), both defaults under `Dir.home`; a blank variable counts as unset, a relative one is made absolute from the current directory. `Paths.tilde` shows a path with `~` for the home folder. `SessionManager` hands a spawned worker the spawner's `XDG_STATE_HOME` / `XDG_CONFIG_HOME`, when set, made absolute, so a relative one isn't read from the session's folder. |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |

data/docs/bundle-authoring.md

@@ -9,23 +9,22 @@ files, what a hook sees, how to test, and what goes wrong. The full references a
 ```
 chi bundle new my-bundle     # ./my-bundle: manifest.yml, plugin.rb, test/my_bundle_test.rb, README.md
 cd my-bundle                 # edit plugin.rb and the test
-chi bundle test              # the tests, on chi's own Ruby and lib (exit status: the tests')
+chi bundle install --dev .   # once while iterating: link this folder; edits load in the next session
 chi bundle check --fix       # manifest, files, shas (--fix rewrites them), requires_chi, install + load in a sandbox
+chi bundle test              # tests on chi's own Ruby and lib (exit status: the tests')
 chi bundle try . -p "Say hello"  # one real model turn; trace the bundle in an isolated install sandbox
-chi bundle install .         # into the user's chi; a NEW session loads it (a running one doesn't)
-chi bundle install --dev .   # or as a link to this folder: edits apply at the next session, no re-install
+chi bundle uninstall my-bundle && chi bundle install .  # at the end: leave dev mode, copy it in
 ```
 
-While you write it, `install --dev .` (once; `uninstall NAME` leaves dev mode) then try it in chi: a new session
-loads the plugin and hooks from the folder as they are, with no sha check (that bundle only; memories are copied).
-Re-install with `--force` from the same PATH to pick up memory edits.
-Dev-linked scripts aren't chmodded, since that would change the source. Chi warns with a `chmod +x PATH/scripts/x`
-hint when a listed script isn't executable; set that bit on the source script.
+The loop is **edit → `check --fix` → `test` → `try`**. `install --dev .` links the folder once, so a new session
+loads your edits with no reinstall (a running one doesn't; `try` doesn't need the link: it installs into its own
+sandbox). Memories are copied: re-install with `--force` from the same PATH to pick up memory edits. At the end,
+`uninstall NAME` leaves dev mode and a plain `install .` copies the bundle in (chi refuses it over a dev link).
+Dev-linked scripts aren't chmodded: chi warns with a `chmod +x PATH/scripts/x` hint; set the bit on the source.
 
-`check` prints one finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, and exits 1 on any
-error. Run it after every edit: an install takes exactly what it checks. It installs into a temp sandbox, not
-the user's config or state, but `check` and `test` run the bundle's plugin and hooks in their own process, as
-written: run them on code you'd install.
+`check` prints one finding per line (`error|warn|info CODE file[:line]: message (fix: hint)`), exits 1 on any error
+and installs into a temp sandbox, not the user's config or state; run it after every edit. `check` and `test` run
+the bundle's plugin and hooks in their own process, as written: run them on code you'd install.
 
 ## Trying a bundle
 
@@ -87,29 +86,36 @@ that list is never fired (`check` warns). The two a bundle wants most, for an `e
 Match on `result:`, not `output:`. An execute's result is its `stdout:` and `stderr:` blocks (each left out when
 empty), then `exit: N` (`exit: 0 (no output)` when both were empty); a non-zero exit makes `status:` `"error"`.
 Act through `ctx`: `ctx.notify(text, level: :warn)`, `ctx.steer(text)` (a line the model reads before its next
-step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's own folder),
+step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's state folder),
 `ctx.cwd`, `ctx.log`. In a test, each recorded notice, steer or stop names its hook as `"plugin.rb (bundle
 my-bundle)"`, the plugin's label (a `hooks/x.rb` file's is `"x.rb (bundle my-bundle)"`).
 
 ## Testing it
 
-`chi bundle new` writes a Minitest test that passes as written: copy its shape. The kit (`samagotchi/testing`)
-loads the bundle's source through chi's own loaders, in a sandbox (temp HOME, config and state), and records what
-it did at chi's edges:
+`chi bundle new` writes a Minitest test that passes as written: copy its shape. The kit (`samagotchi/testing`) loads
+the bundle's source through chi's own loaders in a sandbox (temp HOME, config and state) and records what it did:
+`load_bundle`, then `bundle.command` / `bundle.fire`, and the effects in `bundle.notices`. `bundle.ctx.data_dir` and
+`sandbox.state_dir` are that test's temporary state, never the user's (the scaffold's plugin, tested):
 
 ```ruby
-bundle = load_bundle(BUNDLE, settings: { "greeting" => "hi" })   # in a Samagotchi::Testing::Case test
-bundle.command("/my-bundle chi")                     # → what the command returned
-bundle.fire(:after_tool_call, tool: "execute", status: "error", result: "exit: 1 (no output)", call: { … })
-bundle.tool_call({ name: "execute", content: "rm -rf /" }).deny?   # before_tool_call hooks, through the real gate
-bundle.tool("my_tool", path: "a.txt")                # a chi.tool, as the model calls it
-bundle.notices, bundle.steers, bundle.cards, bundle.stops, bundle.questions   # what it did
-bundle.answer({ selected: "yes" }); bundle.model_answers << "text"           # ask_user / ask_model answers
-bundle.http.stub(:get, "https://api.example/x", json: { ok: true })          # ctx.http, never the network
-bundle.set(cwd: dir, running: false); sandbox.config(hash); sandbox.fake_executable("gh", "echo '{}'")
-bundle.install                                        # installed as chi installs it: warnings, load failures
+require "minitest/autorun"
+require "samagotchi/testing/minitest"
+
+class MyBundleTest < Samagotchi::Testing::Case
+  def test_command_and_failed_execute_notice
+    bundle = load_bundle(File.expand_path("..", __dir__), settings: { "greeting" => "hi" })
+    assert_equal "hi, there", bundle.command("/my-bundle")
+    bundle.fire(:after_tool_call, tool: "execute", status: "error", call: { name: "execute", content: "false" },
+                                  result: "exit: 1 (no output)", output: "[execute]\nexit: 1 (no output)")
+    assert_equal "the command exited 1", bundle.notices.last.text
+    assert_equal File.join(sandbox.state_dir, "plugins", bundle.name), bundle.ctx.data_dir
+  end
+end
 ```
 
+`bundle.tool_call` runs guarded hooks; `bundle.tool` calls a registered tool. `bundle.steers`, `cards`, `stops` and
+`questions` record effects; `bundle.answer` / `model_answers` provide `ask_user` / `ask_model` answers.
+`bundle.http.stub` stubs `ctx.http`; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
 The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
 experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
 class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.
@@ -132,13 +138,7 @@ class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather
 
 ## Verifying it live
 
-After `chi bundle install .`, one real session shows it works with the user's chi:
-
-```
-chi send --new --wait --format json --dir /tmp/try -m "/my-bundle chi"   # the JSON names the session id
-grep plugin_loaded ~/.local/state/samagotchi/samagotchi.log | tail -1    # bundle=my-bundle commands=1 hooks=1
-chi sessions delete --force SESSION_ID                                    # leave no test session behind
-```
-
-(`$XDG_STATE_HOME/samagotchi/samagotchi.log` when `XDG_STATE_HOME` is set.) Then tell the user what it adds,
-how to use it, and that a new session picks it up.
+`chi bundle try . -p "..."` **is** the live check: a real model turn on the installed bundle, with its trace
+(tools, plugin, notices, cards). Don't repeat it with `chi send` sessions on the user's own install. After the
+final `chi bundle install .`, `chi bundle list` showing the bundle and its version is enough. Then tell the user
+what it adds, how to use it, and that a new session picks it up.

data/docs/cli.md

@@ -149,7 +149,10 @@ non-interactive mode. `--keep` retains the temporary sandbox and prints its path
 one experimental JSON object to stdout and human trace lines to stderr; its keys are `session_id`, `exit_code`,
 `answer`, `tools` (`index`, `name`, `args`, `status`, `duration_ms`), `notices`, `cards`, `questions`,
 `interactive_blocked`, `used_memories`, `tokens` (`prompt`, `completion`), `cost`, `cost_is_estimate`, `model`,
-`sandbox`, `denied` (1-based tool indexes) and `stderr_tail` (last 4,000 characters). Exit status: 2 for usage,
+`sandbox`, `denied` (1-based tool indexes), `stderr_tail` (last 4,000 characters) and `timed_out`. A run past
+`--timeout` is interrupted like a Ctrl-C and still prints the trace it got to, with `timed_out: true` (text output:
+the trace lines, then `timed out after N seconds` on stderr). That turn's messages aren't saved, so its tool calls
+come from their timing records: name, status and duration, with empty `args`. Exit status: 2 for usage,
 1 for install/turn failure or timeout, 130 for Ctrl-C, otherwise the child's status.
 
 `try` runs the bundle's code and the model's tools with your real HOME, account and keys. Its temporary working

data/docs/configuration.md

@@ -73,7 +73,8 @@ session:
   # keep_empty: false       # true keeps sessions nothing happened in (default: deleted when left)
   # max_children: 4         # running sessions one session may have delegated at a time (the delegate tool)
   # delegate_reports: wake  # a child's reply reaches its parent by itself: wake (an idle parent runs a turn), queue, off
-  # max_wakes: 10           # wake turns in a row (delegate reports, context, peers) with no human input
+  # task_wakes: wake        # a background task finishing unseen: wake (an idle session runs a turn), queue, off
+  # max_wakes: 10           # wake turns in a row (delegate reports, finished tasks, context, peers) with no human input
 
 # Baseline memories preloaded into the system prompt (same shape as --memory);
 # name entries you have, or chi warns at each start.
@@ -160,7 +161,7 @@ or `chi web` restart.
 | `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
 | `recap.*` | Worker start | The engine builds its recap job once. |
 | `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
-| `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
+| `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.task_wakes`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
 | `session.retention_*`, `session.max_count`, `session.keep_status`, `session.sweep_interval_hours` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. The sweep interval is checked on the next hub tick. |
 | `web.*` | `chi web` start | Restart `chi web` to change its bind address, port or page settings. |
 | `log.*` | Process start | Each process holds its configured log sink and level after first use; restart that process. |
@@ -1622,7 +1623,8 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `session.keep_empty` | `false` | | Keep sessions nothing happened in. |
 | `session.max_children` | `4` | | Running delegated sessions one session may have. |
 | `session.delegate_reports` | `wake` | | When a delegate child ends a turn, its reply reaches the parent: `wake` runs an idle parent's turn for it, `queue` waits for the parent's next turn, `off` leaves it to `delegate_result`. |
-| `session.max_wakes` | `10` | | Wake turns a session runs in a row with no human input: for delegate reports, attached context and peer answers; past it reports wait for the next turn and context updates arrive as notes. |
+| `session.task_wakes` | `wake` | | When a background task the session started (`task_create`, an `execute` handed over at its limit) finishes and the model hasn't seen it finish: `wake` runs an idle session's turn opened by a `TASK FINISHED` note, `queue` leaves the note for the next turn, `off` leaves it to `task_wait`. See [Finish wake](internals/background-tasks.md#finish-wake). |
+| `session.max_wakes` | `10` | | Wake turns a session runs in a row with no human input: for delegate reports, finished background tasks, attached context and peer answers; past it reports wait for the next turn and task finishes and context updates arrive as notes. |
 | `session.retention_days` | `14` | yes | Delete sessions not updated for N days; `0` = forever. See [Sessions](sessions.md). |
 | `session.max_count` | `500` | yes | Keep the newest N; `0` = uncapped. |
 | `session.keep_status` | none | yes | Comma list of statuses never pruned (a session a worker or `chi` has open is never pruned anyway). |

data/docs/internals/background-tasks.md

@@ -19,7 +19,7 @@ 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/`: each task's `tmp/tasks/<id>/task.json` is a `TaskRecord` (`lib/samagotchi/tools/task_record.rb`, a value object: `.from_file` reads it, `#to_file` is the JSON object written, an update is a `#with`). Its keys keep their order; `stderr_path` and `handed_over_by` (a handed-over execute) and `stop_requested_by` (a stop under way or done) are left out until set. `bundles/slow-commands` reads these files on its own, so the shape is a contract.
-- 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 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 restart hold, the finish wake's watch) 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>/` (always an absolute path: a relative `XDG_STATE_HOME` is taken from the directory chi started in; 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.
@@ -27,11 +27,36 @@ Behavior:
 - 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` (a `task_create` record's `exit_code_path` is absolute too; its `output_path` is relative). `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; `task_wait`'s output tail is followed by a `stderr_tail:` of at most 10 lines when that log isn't empty. A `task_create` task has one log (stdout and stderr together) and no `stderr_path`. A `task_wait` result longer than `max_tool_output_chars` keeps its header and the tail's end, with a gap line naming `output_path`, where the whole log already is (and `stderr_path`, when the record has one) (`ToolOutputCut`'s `:head_tail_ref`; nothing is copied; see [Tool output guardrails](tool-guardrails.md#the-runners-cut-max_tool_output_chars)).
-- 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.
+- Which tasks are a session's own (a cancelled turn's note, a worker's restart hold, the finish wake below, 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.
 - `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none) and `SAMAGOTCHI_SESSION_REASONING_HISTORY` (its own reasoning_history level, the same way). `chi self` reads the last three for its model, thinking level and reasoning history. The four are `TaskRuntime::MARKER_ENV_KEYS` (and `SessionManager::SESSION_MARKER_ENV`, which a spawned worker unsets). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 - They also pass on a set `XDG_STATE_HOME` / `XDG_CONFIG_HOME` made absolute (`Builtins.xdg_absolute`, via `Paths`), so a chi the command runs in another `cwd` (`chi send`) reads this chi's state and config. These aren't reserved: an XDG dir the model sets in `task_create`'s `env` stays its own.
 
+## Finish wake
+
+A task the model leaves running (it ends its turn: "I'll check when it's finished") is reported when it ends, so the result doesn't wait for the user's next message. `session.task_wakes` (env `SAMAGOTCHI_SESSION_TASK_WAKES`): `wake` (default), `queue` or `off` (no watch, as before).
+
+- **The watch** (`TaskWatch`, `task_watch.rb`) is the Worker's, in memory: the in-process REPL (`--no-shared`) has none, and a crash loses it (those tasks behave as before). The Worker's Engine observer feeds it the raw `:tool_call_completed` events, the input `Bridge#own_task_ids` reads too. A `task_create` result and an `execute` hand-over add the task (`TaskRuntime.created_id`: a `task_id:` the command printed doesn't count), the hand-over's limit kept for the note. What shows the model the end removes it: a `task_wait` with a final status, or with `wait_result: pattern_matched` (the model chose its own "done" marker); a `task_get` with a final status; any `task_stop`. `task_list` and a `read` of `output.log` don't: a model that read the log still gets the wake once. Tasks a tool starts inside an anytime command (`/btw` and the like) reach the same observer, so they are watched too.
+- **The idle tick**: with something watched, each idle pass (after delegate reports, before due reminders) refreshes the watched records (`TaskRuntime.get_record`, one `ps` per running task) and takes the finished ones, keeping only the ids the conversation still holds (`TaskRuntime.created_ids_in`: a `!rollback` or a restored turn may have dropped the result that started one; an LLM context strategy can't, since its stale and forget stubs are drawn in the request, never written over the saved result). A note that can't be written puts its task back for the next pass. An empty watch costs nothing. A task that finishes during a turn and is still unseen when the turn ends wakes on the next idle pass. One the user stopped with the web's stop-task button is dropped without a note.
+- **The note** is a context note under its own header (`ContextNote::TASK_HEADER`; `TaskFinishNote`), `note_id: task-<id>`, `source: task <id8>`:
+
+  ```
+  [TASK FINISHED from task 3f9a2c1d, 14:20]
+  Background task 3f9a2c1d finished: exit 0 after 6m12s (handed over by execute at its 120s limit).
+  command: bundle exec rspec spec
+  <task_wait's own text (TaskWait.finished_text): status, the log's last 10 lines, a stderr_tail>
+  chi started this turn because a background task you started finished; your user didn't write anything.
+  Carry on with what you planned to do with its result. If you planned nothing, tell your user in a sentence or two how it went.
+  [END NOTE]
+  ```
+
+  The duration runs from `started_at` to the `exit_code` file's mtime (the shell's EXIT trap wrote it as it ended; `finished_at` is when a refresh first noticed the end), else `finished_at`. The body is cut to `max_tool_output_chars` as a `task_wait` result is (`ToolOutputCut`'s `:head_tail_ref`, naming the logs).
+- **The wake turn**: the first finished task runs a continue turn from client `task:<id>` (`last_turn.origin: "task"`, labelled `task <id8> finished` in the TUI and the web; the web's bell rings at its end however short), whose first message is the note (`turn_start`, `turn_id`, written before the turn's checkpoint so a restore keeps it). It counts toward `session.max_wakes` with the other wakes (`WorkerWakes#task_open?`: no continue offer, not paused, past the 2 s start grace). Several tasks finishing together: one wake turn, the others plain notes before it.
+- **A plain note instead** (the same text without the last two lines, no turn start), written at once, with `queue`, the budget spent (the UIs hear `N finished background tasks noted; the model reads them with your next message` once per human input, the flag shared with the other wakes), wakes paused, a continue offer waiting, input queued, an exit asked for, or a **note-only** task: one started or waited on in a turn the user stopped (reasons `user`, `manual`, `ctrl_c`), since a wake telling the model to carry on would undo that Stop. A prompt's turn takes the finished ones as plain notes first.
+- **Failure**: a wake turn that fails and kept nothing, or is stopped and restored, turns its note back into the plain one (`WorkerInbound#unmark_wake`, as for a context wake) and pauses wakes until the user writes.
+- **Idle exit**: with `wake`, a watched task still running holds the worker's idle exit and `/exit` (`WorkerIdleExit`'s `:background_tasks`; the 409 lists the tasks, `{id, command}`, with a `hint` on stopping them, and the attached terminal names them and says to use the web's stop-task button or ask for `task_stop`), as reminders do. With `queue` they don't: nothing would wake for the end, so keeping the worker up isn't worth it; a task that ends after the worker left gets no note (the model sees its end at its next look, as before). A forgotten dev server keeps the worker up until it is stopped; a crash of that server wakes the session.
+- **The tool descriptions**: a worker's `execute` and `task_create` say "if you end your turn before it finishes, chi tells you when it does" (left out under `off` and in the REPL), fixed when the worker builds its Engine.
+
 Work that needs a model, not a shell command, goes to a child chi session instead: `delegate` / `delegate_result` have the same shape (start, then wait) and return only the child's final reply; see [Sessions: Delegating](../sessions.md#delegating).

data/docs/internals/bundles.md

@@ -24,7 +24,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 |---|---|
 | `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
 | `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
-| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: filtered-config `Sandbox` installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output. `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers. |
+| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: filtered-config `Sandbox` installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output (tool records the messages lack, from a turn a `--timeout` interrupt cut, become rows without args; `Run::Result#timed_out` becomes `timed_out`). `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers. |
 | `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
 | `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
 | `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / hook / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |

data/docs/internals/engine.md

@@ -489,12 +489,12 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:thinking_refused` / `:reasoning_history_refused` | the chat loop asked a step again without the thinking fields / the reasoning sent back; the Engine logs it and makes a once-per-session-and-host `:hook_notice` of it, the event itself never reaches the sink | `{iteration, model, level, detail}` |
 | `:pending_input_merged` | queued input joined the conversation | `{iteration, count, content, steers?, answer}` |
 | `:tool_dispatch_started` / `:tool_dispatch_completed` | around a batch | `{iteration, call_count}` |
-| `:tool_call_started` | before a call runs | see ToolRunner |
+| `:tool_call_started` | before a call runs | Engine event includes `call` (see ToolRunner); the Bridge's SSE frame omits it |
 | `:tool_call_completed` | after a call ran | see ToolRunner |
 | `:used_memories_updated` | a memory was read, and after the loop | `{used_memory_names, read_names?}` |
 | `:hook_notice` | a hook's or plugin's notify during a turn | `{hook, text, level}` (announced with `between_turns: true` outside a turn) |
 | `:guardrail_warning` | a guardrails line during a turn | `{message}` |
-| `:turn_completed` | normal end | `{result, turn_summary, display_pending}` |
+| `:turn_completed` | normal end | Engine event `{result, turn_summary, display_pending}`; the Bridge's SSE frame omits `result` (answer remains in `turn_summary.output`) |
 | `:turn_canceled` | Stop, hook stop, Ctrl-C | `{cancellation_reason, cancelled_by?, duration_ms}` |
 | `:turn_failed` | an error | `{error_class, message, duration_ms, error_kind?, retryable?, host?, summary?}` |
 | `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display, refs?}` (display a string, or nil; refs the count of the answer's refs, only when a hook attached some) |

data/docs/internals/prompt-caching.md

@@ -83,6 +83,10 @@ right-hand column happens.
   finishes booting between load and the first turn changes search answers only, so two sessions on the same
   toolkit with the same MCP cache send the same bytes. Whether find_tools/call_tool are declared at all reads the
   same two things (`Registry#index_needed?`), never live groups.
+- A worker's `execute` and `task_create` descriptions carry the finish wake's sentence ("if you end your turn before
+  it finishes, chi tells you when it does"; `Engine.new(task_finish_notes:)`, set once as the worker builds its
+  Engine); the `--no-shared` REPL's, and a worker's under `session.task_wakes: off`, don't. A session that moves
+  between the two, or whose worker restarts after `task_wakes` changed, misses the cache once.
 - On remote Claude, `LLM::PromptCache.mark` sends the system message as two text parts. The stable part carries
   breakpoint #1, so a **new session** reads it from the cache. The last non-system message carries breakpoint
   #2, so the **next request in the session** reads everything up to it. Mid and tail system messages never take

data/docs/sessions.md

@@ -17,7 +17,7 @@ Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/s
 
 A session is deleted if **expired by age OR overflow by count** (unless `keep_status` or the live-owner guard: a session a worker or `chi` still has open is never pruned). A session's `status` is its turn state (`idle`/`running`), not whether a worker is alive. Orphan dirs without a `*.json` are never deleted, except skeleton-only ones (see *Empty sessions*). Deletion removes both `*.json` and sidecar dir atomically. Set both `DAYS=0` and `MAX=0` to retain forever.
 
-**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered and no continue offer (the step-limit question) waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up. The session's status stays as it was, not `stopped`. With `"restart": true` (a worker whose sidecar lists the `restart` feature) the worker hands the session to a new worker on the newest chi installed: it leaves, then starts its successor once its lock is free, keeping even an empty session and writing no recap. Clients' streams don't hold a restart (a web tab and an attached terminal reconnect to the new worker); what would be lost does: a turn running or queued, a continue offer, a question or approval waiting, reminders, a `/btw` (or another anytime command) still running, a delegate's approval relay open or settled in the last 10 minutes, and background tasks this conversation started that still run (`WorkerIdleExit#hold_for_restart`; 409 `held` with `reason`). What lives only in the worker's memory goes: the event history a late client replays, the kept `/btw` answers, a plugin's in-memory state.
+**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered, no background task it watches for a [finish wake](internals/background-tasks.md#finish-wake) still running (with `session.task_wakes: wake`) and no continue offer (the step-limit question) waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up (for background tasks, which ones and how to stop them). The session's status stays as it was, not `stopped`. With `"restart": true` (a worker whose sidecar lists the `restart` feature) the worker hands the session to a new worker on the newest chi installed: it leaves, then starts its successor once its lock is free, keeping even an empty session and writing no recap. Clients' streams don't hold a restart (a web tab and an attached terminal reconnect to the new worker); what would be lost does: a turn running or queued, a continue offer, a question or approval waiting, reminders, a `/btw` (or another anytime command) still running, a delegate's approval relay open or settled in the last 10 minutes, and background tasks this conversation started that still run (`WorkerIdleExit#hold_for_restart`; 409 `held` with `reason`). What lives only in the worker's memory goes: the event history a late client replays, the kept `/btw` answers, a plugin's in-memory state.
 
 **Empty sessions:** a session nothing happened in is deleted when it is left, so `chi` → `/exit` leaves no trace. Empty means: no messages, no turn tried (a failed turn leaves a `last_prompt` and keeps it), no memory used, no pending question, nothing in `input/`, `notes/` or `images/`, nothing in its dir beyond the worker's skeleton, mode `assist`, and the default model. A session on another model (`/model`, `--model`) counts as prepared and stays (`SessionManager.discardable?`). The worker checks as it idle-exits or leaves on a client's request and deletes it once its lock is free, checking again first. The attached `/exit` then says `Detached; the session is empty: it will be discarded if nothing arrives before its worker stops.` (a note or prompt landing first keeps it). The REPL (`--no-shared`) does the same at `/exit` or Ctrl-D. The retention sweep catches those killed first: empty sessions over an hour old with no live owner, whatever `DAYS`/`MAX`, and skeleton-only dirs with no `*.json`. `session.keep_empty: true` (env `SAMAGOTCHI_SESSION_KEEP_EMPTY`) turns all of it off.
 
@@ -143,7 +143,7 @@ system message marked `kind: turn_note` (the UIs don't show it; they showed the
   the user, who may send it again.]` in the REPL and attached mode, where the prompt is given back;
   `… The user's last message was not answered.]` after `-p`, where the prompt stays in the session;
   `… The wake turn for the change in attached context pr-7 was not answered; chi starts no other wake turn until
-  the user writes.]` after a wake turn chi started (a context source's change, a delegate's report), not the user
+  the user writes.]` after a wake turn chi started (a context source's change, a delegate's report, a background task that finished), not the user
   (for a delegate's report it adds `chi keeps the report and brings it again with the user's next message.`);
 - cancelled (Ctrl-C, the web's stop): `[SYSTEM: the previous turn was cancelled (ctrl-c) after 12s; the reply
   above ends where it was cut off.]` (an answer or only narration had streamed), or `…; no answer had been shown.]` when only thinking had streamed;

data/lib/samagotchi/bridge/client_event.rb

@@ -10,8 +10,10 @@ module Samagotchi
     # the provider's raw `payload`, and no raw `content` (the chat loop's is
     # reasoning + content again, the native loop's the raw stream with its
     # tool-call bytes and thought tags): clients read `text`, `thinking`,
-    # `tool_call` and `counts`, never a provider's payload shape. `?raw=1` on
-    # the worker's stream skips this (debugging).
+    # `tool_call` and `counts`, never a provider's payload shape.
+    # :tool_call_started omits the model's `call`; clients render its row from
+    # the other fields. :turn_completed omits `result`; `turn_summary.output`
+    # carries the answer. `?raw=1` on the worker's stream skips this (debugging).
     #
     # Pure: the event is the one hash SessionObserver hands every observer
     # (the ring, TurnAccumulator, the other writers, SessionMetrics, hooks),
@@ -28,13 +30,19 @@ module Samagotchi
       # @param event [Hash] the engine's event (symbol keys; its payload has
       #   string keys)
       # @return [Hash] the event as clients get it: a copy for a
-      #   :generation_chunk, the same object for every other event
+      #   projected event, the same object for every other event
       def project(event)
-        return event unless event.is_a?(Hash) && event[:type].to_s == "generation_chunk"
+        return event unless event.is_a?(Hash)
 
-        projected = event.except(:payload, :content)
-        found = counts(event[:payload])
-        found ? projected.merge(counts: found) : projected
+        case event[:type].to_s
+        when "generation_chunk"
+          projected = event.except(:payload, :content)
+          found = counts(event[:payload])
+          found ? projected.merge(counts: found) : projected
+        when "tool_call_started" then event.except(:call)
+        when "turn_completed" then event.except(:result)
+        else event
+        end
       end
 
       # The payload's normalized counts, nil keys left out; nil when the

data/lib/samagotchi/bridge.rb

@@ -805,7 +805,8 @@ module Samagotchi
     # event log held, so no POST /turn lands between its check and its
     # answer; it leaves from its loop after this reply.
     # 200 {status: "exiting", discard?: the session is empty and goes} ({status: "restarting"} for a restart), or 409
-    # {status: "held", reason:} naming what keeps it up. A past +deadline+
+    # {status: "held", reason:} naming what keeps it up (with tasks: [{id:,
+    # command:}] and a hint: how to stop them, for background_tasks). A past +deadline+
     # (see #handle_post_turn), checked with the event log held: 408
     # deadline_passed, the worker not asked (its client said it didn't stop).
     # Returns [headers, status, body].
@@ -838,7 +839,11 @@ module Samagotchi
         return [{}, 200, body]
       end
 
-      [{}, 409, { status: "held", reason: reason.to_s, session_id: @session_id }]
+      # A hold may name what it waits for ({reason:, tasks:}: the background
+      # tasks a finish wake watches).
+      held = reason.is_a?(Hash) ? reason : { reason: reason }
+      [{}, 409, { status: "held", reason: held[:reason].to_s, tasks: held[:tasks], hint: held[:hint],
+                  session_id: @session_id }.compact]
     end
 
     # Queue a turn for this session through its file IPC (the worker polls