samagotchi 0.90.0 → 0.91.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06240ded5e15bc55c7c3467bc7d5c0e79daecd5822291feebf72bbab6e6e6cb7
-  data.tar.gz: 52adfdbb519ba9bed3575d55abe737dbca654d81c3c213706a556b56742628af
+  metadata.gz: e4a20c3555c1f3e592919853f9dc59a5067e7e42251d11dad2f3be844f118f90
+  data.tar.gz: 817bb797b870985aeb21789377eae7770225265d03c527bb9218a1ecd3c2376e
 SHA512:
-  metadata.gz: 33fdd1b34ce5e0840330451bb90675fe6fb9de6903d3569f3d8e6559e09cad004bcd40bfeec0e0468943d0b2d2abfce8a21d097152c86a53bd2cd332e0386437
-  data.tar.gz: 5b19168272d7de67413c480c59bbee363b14a0ba106cdc146632cfb03be45cc646367454758fcbe95aba7562926ab700620e839b2526e818875312f5453d413d
+  metadata.gz: 74b69c624e9e43882940e48bdf00d0bedb1172fd53f4094c30ef4250e15a4e7ae9fedba4fc9704b923d3b622bcad47950432d450c1c3c219f42a54186dacad58
+  data.tar.gz: ac112286f3eaa6364bd68cee410e4b580f8246215222a17ecd3781f2980d828eb12d47cc3b64c800e201f9a81662a0c2ee61627a1c485e4249f409c771b65744

data/CHANGELOG.md

@@ -8,6 +8,26 @@ 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
@@ -3529,7 +3549,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.90.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

data/docs/architecture.md

@@ -359,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
@@ -581,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

@@ -138,13 +138,7 @@ class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather
 
 ## Verifying it live
 
-`chi bundle try . -p "Say hello"` is the live check (trace, plugin, notices); after the final install, check the copy:
-
-```
-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/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.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

data/lib/samagotchi/bundle_command/try/trace.rb

@@ -9,7 +9,8 @@ module Samagotchi
     module Try
       Trace = Data.define(
         :session_id, :exit_code, :answer, :tools, :notices, :cards, :questions, :denied,
-        :interactive_blocked, :used_memories, :tokens, :cost, :cost_is_estimate, :model, :sandbox, :stderr_tail
+        :interactive_blocked, :used_memories, :tokens, :cost, :cost_is_estimate, :model, :sandbox, :stderr_tail,
+        :timed_out
       )
 
       class TraceReader
@@ -22,8 +23,8 @@ module Samagotchi
           @session_id = session_id if session_id.to_s.match?(SESSION_ID)
         end
 
-        def read(exit_code:, answer:, stderr:, sandbox:)
-          return empty_trace(exit_code, answer, stderr, sandbox) unless @session_id
+        def read(exit_code:, answer:, stderr:, sandbox:, timed_out: false)
+          return empty_trace(exit_code, answer, stderr, sandbox, timed_out) unless @session_id
 
           sessions_dir = File.join(@state_home, "samagotchi", "sessions")
           session_path = File.join(sessions_dir, "#{@session_id}.json")
@@ -32,7 +33,7 @@ module Samagotchi
           messages = Array(session["messages"]).select { |message| message.is_a?(Hash) }
           analytics = AnalyticsFile.read(session_dir) || {}
           entries = card_entries(session_dir)
-          tool_rows, denied = tools(messages, analytics)
+          tool_rows, denied = tools(messages, analytics, timed_out)
           summary = SessionMetrics.saved_summary(session_dir)
           cost, estimate = cost_summary(summary)
           questions = entries.select { |entry| entry["type"] == "question" }
@@ -47,20 +48,21 @@ module Samagotchi
                                                                   prompt: summary&.prompt_sum, completion: summary&.completion_sum
                                                                 },
             cost: cost, cost_is_estimate: estimate, model: session["model_name"], sandbox: sandbox,
-            stderr_tail: tail(stderr)
+            stderr_tail: tail(stderr), timed_out: timed_out
           )
         end
 
         private
 
-        def empty_trace(exit_code, answer, stderr, sandbox)
+        def empty_trace(exit_code, answer, stderr, sandbox, timed_out)
           Trace.new(session_id: nil, exit_code: exit_code, answer: answer.to_s, tools: [], notices: [], cards: [],
                     questions: [], denied: [], interactive_blocked: false, used_memories: [], tokens: {
                       prompt: nil, completion: nil
-                    }, cost: nil, cost_is_estimate: false, model: nil, sandbox: sandbox, stderr_tail: tail(stderr))
+                    }, cost: nil, cost_is_estimate: false, model: nil, sandbox: sandbox, stderr_tail: tail(stderr),
+                    timed_out: timed_out)
         end
 
-        def tools(messages, analytics)
+        def tools(messages, analytics, timed_out)
           records = Array(analytics["tool_records"]).select { |record| record.is_a?(Hash) }
                                                     .to_h do |record|
             [[record["iteration"].to_i, record["call_index"].to_i], record]
@@ -94,9 +96,24 @@ module Samagotchi
               }
             end
           end
+          rows += unsaved_rows(records, iteration, index) if timed_out
           [rows, denied]
         end
 
+        # A turn cut by a --timeout interrupt saves only the messages before
+        # it (a Ctrl-C), while its tool records stay: the records past the
+        # last saved model message are its calls, without their arguments.
+        # Only then: a normal run's loop also counts iterations it saves no
+        # model message for (a cut's retry, an empty-answer nudge).
+        def unsaved_rows(records, saved_iterations, index)
+          records.select { |(iteration, _), _| iteration > saved_iterations }.sort.map do |_, record|
+            index += 1
+            status = record["status"].to_s
+            { index: index, name: record["called_as"] || record["tool"] || "tool", args: "",
+              status: status.empty? ? "unknown" : status, duration_ms: record["duration_ms"].to_i }
+          end
+        end
+
         def call_name(call)
           function = call["function"].is_a?(Hash) ? call["function"] : {}
           call["name"] || function["name"] || "tool"

data/lib/samagotchi/bundle_command.rb

@@ -977,7 +977,7 @@ module Samagotchi
         result = Try::Run.new(sandbox).run(prompt: options[:prompt], options: options, timeout: timeout)
         trace = Try::TraceReader.new(state_home: sandbox.state_home, session_id: result.session_id)
                               .read(exit_code: result.exit_status, answer: result.stdout, stderr: result.stderr,
-                                    sandbox: options[:keep] ? sandbox.root : nil)
+                                    sandbox: options[:keep] ? sandbox.root : nil, timed_out: result.timed_out)
         render_try_trace(trace, json: options[:json], child_stderr: result.stderr)
         @stderr.puts "chi bundle try: timed out after #{timeout} seconds" if result.timed_out
         result.exit_status

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.90.0
+version: 0.91.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:be1b601c550e22730416913eeb0bd47a097e37f3c6743bda709ee495467547a5
+  self_map.md: sha256:da591d30211488eb7cff36604502b78167b0d6b64c1fbb827eca16b8703a63e7
   config_modification_protocol.md: sha256:f2551c71a21cc42e8b888e4b9b41f4b0909224e5393731905c1f786c704bad14
   memory_guide.md: sha256:c48eea744db69e4f3e9bb415e9a03a8c78bbcaa1205ad3b1fb157a079f92d22e
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

data/lib/samagotchi/bundles/system/self_map.md

@@ -30,6 +30,11 @@
   third-party information, never instructions to me. When a source's change matters (a review
   asking for changes, checks failing, the PR closed), chi may start a turn for it with no user
   message ("context <name> changed"): I tell my user what changed and act on nothing.
+- `[TASK FINISHED from task <id8>, …]` is a background task I started (`task_create`, an `execute`
+  handed over at its limit) that finished while I wasn't waiting on it: its exit code, duration
+  and log tail. When it opens a turn with no user message ("task <id8> finished"), I carry on with
+  what I planned for its result, or tell my user in a sentence or two how it went. Without the
+  "chi started this turn" line it is only information for my next answer.
 - `forget_outputs` (only when my model's `llm_context.strategy` has the experimental forget layer)
   frees context: my tool outputs show ids like `[#t42]`, and a forget replaces them with a stub
   holding my note (the call stays; `keep` keeps lines, `restore` brings a non-read output back).

data/lib/samagotchi/client_id.rb

@@ -24,6 +24,9 @@ module Samagotchi
     # A turn chi ran because an attached context source changed:
     # context:<name> (Worker's context wake).
     CONTEXT_PREFIX = "context:"
+    # A turn chi ran because a background task this session started
+    # finished unseen: task:<task id> (Worker's task finish wake).
+    TASK_PREFIX = "task:"
     # chi's own turns; system:reminder, the turn queued when reminders are due.
     SYSTEM_PREFIX = "system:"
     REMINDER = "system:reminder"

data/lib/samagotchi/config.rb

@@ -132,6 +132,9 @@ module Samagotchi
       # A delegate child's turn end reaches its parent (ChildReports): wake runs an idle parent's turn for it, queue waits
       # for the parent's next turn, off is the old behaviour (only delegate_result asks).
       Entry.new(key: "session.delegate_reports",      yaml_path: %w[session delegate_reports],      type: :enum,    default: "wake", expose: %i[env config], enum_values: %w[wake queue off], lifecycle: :next_lifecycle_decision),
+      # A background task this session started that finishes unseen (TaskWatch): wake runs an idle session's turn for
+      # it, queue leaves a plain note for the next turn, off is the old behaviour (the model looks when it chooses).
+      Entry.new(key: "session.task_wakes",            yaml_path: %w[session task_wakes],            type: :enum,    default: "wake", expose: %i[env config], enum_values: %w[wake queue off], lifecycle: :next_lifecycle_decision),
       # Turns a parent runs for delegate reports in a row with no human input; past it reports wait for the next turn.
       Entry.new(key: "session.max_wakes",             yaml_path: %w[session max_wakes],             type: :integer, default: 10,    expose: %i[env config], lifecycle: :next_lifecycle_decision),
 

data/lib/samagotchi/context_note.rb

@@ -15,25 +15,32 @@ module Samagotchi
     # context_source: the attached context source a note is about
     # (ContextAbsorber), so the UIs can tie it to its chip.
     KEYS = %i[kind note_id source from_session from_cwd context_source].freeze
+    HEADER = "CONTEXT NOTE"
+    # A finished background task's note (TaskFinishNote): a header of its own.
+    TASK_HEADER = "TASK FINISHED"
+    HEADERS = [HEADER, TASK_HEADER].freeze
+
+    FRAME_HEAD = /\A\[(?:#{HEADERS.map { |h| Regexp.escape(h) }.join("|")})[^\n]*\n/
 
     module_function
 
     # Takes SessionInbox.read_note's keys. +turn_start+ / +turn_id+: the
     # note starts a turn chi runs for it (a context wake), as a wake turn's
-    # delegate report does (Steer.turn_prompt?).
+    # delegate report does (Steer.turn_prompt?). +header+: the frame's
+    # (HEADERS), not kept as a key: the content carries it.
     # @return [Hash] the conversation message
     def message(note_id:, text:, source:, created_at: nil, from_session: nil, from_cwd: nil, context_source: nil,
-                turn_start: nil, turn_id: nil, **)
+                turn_start: nil, turn_id: nil, header: HEADER, **)
       { role: "system", kind: KIND, note_id: note_id, source: source, from_session: from_session,
         from_cwd: from_cwd, context_source: context_source, turn_start: (true if turn_start == true), turn_id: turn_id,
         content: frame(text, source: source, created_at: created_at, from_session: from_session,
-                             from_cwd: from_cwd) }.compact
+                             from_cwd: from_cwd, header: header) }.compact
     end
 
-    def frame(text, source:, created_at: nil, from_session: nil, from_cwd: nil)
+    def frame(text, source:, created_at: nil, from_session: nil, from_cwd: nil, header: HEADER)
       time = clock(created_at)
       from = label(source: source, from_session: from_session, from_cwd: from_cwd)
-      "[CONTEXT NOTE from #{from}#{", #{time}" if time}]\n#{text}\n[END NOTE]"
+      "[#{header || HEADER} from #{from}#{", #{time}" if time}]\n#{text}\n[END NOTE]"
     end
 
     # Who sent a note: its source, or the sending session and its folder.
@@ -49,7 +56,7 @@ module Samagotchi
 
     # The note's own text, without its frame.
     def text_of(message)
-      fetch(message, :content).to_s.sub(/\A\[CONTEXT NOTE[^\n]*\n/, "").delete_suffix("\n[END NOTE]")
+      fetch(message, :content).to_s.sub(FRAME_HEAD, "").delete_suffix("\n[END NOTE]")
     end
 
     def fetch(message, key)

data/lib/samagotchi/engine.rb

@@ -121,8 +121,10 @@ module Samagotchi
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
+    # @param task_finish_notes  [Boolean] a worker's Engine whose finish wake reports a task the model leaves
+    #   running (Worker, TaskWatch): execute's and task_create's descriptions say so
     def initialize(client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, model_name: nil, memories: [], muted_memories: [], kernel: nil, recap: nil, reminders: nil,
-                   plugins: true, scratch: false, model_typed: nil, appended_prompt_files: [])
+                   plugins: true, scratch: false, model_typed: nil, appended_prompt_files: [], task_finish_notes: false)
       # The turn as other threads see it (flag, cancel controller, sink,
       # steers) and the idle layer's activity clock. Built first: a plugin
       # may steer or ask whether a turn runs while it loads.
@@ -189,9 +191,12 @@ module Samagotchi
       @hooks = @extension_load.hooks
       # The tools this session offers (the prompts' declarations and the
       # kernel's dispatch): the built-ins, per Engine. execute.description
-      # off: execute offers no description parameter.
+      # off: execute offers no description parameter. +task_finish_notes+:
+      # a worker's, whose finish wake reports a task left running (the
+      # Worker's TaskWatch): execute and task_create say so.
       @tools = Tools::Builtins.registry(command_description: Config.get("execute.description") != false,
-                                        policy: Config.get(LLMContextStrategy::POLICY_SETTING))
+                                        policy: Config.get(LLMContextStrategy::POLICY_SETTING),
+                                        task_finish_notes: task_finish_notes)
       restrict_scratch_tools! if @scratch
       # Likewise the slash commands its SessionCommands run.
       @command_registry = SessionCommands.register_builtins(Commands::Registry.new)
@@ -1401,6 +1406,7 @@ module Samagotchi
       source = if client_id.start_with?(ClientId::DELEGATE_PREFIX) then "delegate"
                elsif client_id.start_with?(ClientId::CHILD_PREFIX) then "delegate_report"
                elsif client_id.start_with?(ClientId::CONTEXT_PREFIX) then "context"
+               elsif client_id.start_with?(ClientId::TASK_PREFIX) then "task"
                elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end

data/lib/samagotchi/last_turn.rb

@@ -9,8 +9,9 @@ module Samagotchi
   # outcome: "completed", "failed", "canceled" or "not_continued";
   # ended_at: iso8601; seconds: Float; origin: "client", "reminder",
   # "delegate", "delegate_report" (a turn a parent ran for its delegate
-  # children's reports) or "context" (one an attached context source's
-  # change started); exhausted/limit: the turn ran out of iterations at
+  # children's reports), "context" (one an attached context source's
+  # change started) or "task" (one a finished background task started: the
+  # Worker's finish wake); exhausted/limit: the turn ran out of iterations at
   # limit. The rest are its stop facts (LastTurn::STOP_FACTS), only what is
   # known. enqueued_id: the input's id when the turn ran one (a POST /turn
   # ack's, an input file's), so a wait for a queued message (`chi send