samagotchi 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd06759f4b1d8b5c2d799aed0a4a57940c34bfd663599fcd1dbbad4f4421c99
-  data.tar.gz: 040c8e4d3c4e3aee3f9605fded5676088c21a80b50426696a9cdee4a16f65d7a
+  metadata.gz: 9c7c0dfd8a859bb4808e10128560904cac788bc6bed8ec0b9d799425c6eee2fb
+  data.tar.gz: 4263cf99ea0998c74d7ae0f4e37d3bdbed8acc0140400082eed696da58e14847
 SHA512:
-  metadata.gz: 418ba106ef5c7f610fd831b93b3441ab1de00910b84a782d37bc3fe617dab833ce35073f4733dc2fe6bdca9d90dba5c7af6fba7b7df29edf60c72c08c99acff9
-  data.tar.gz: 8c78e649bbadc097d5cb9b3de7adaac3bcebeda06d04ea1a34f7cbfab531fcaf15e0bce7bbc25480eb28e18c47867cbd0226d57ac3cece9452e7912471aa55b5
+  metadata.gz: 16b8b6cda0d263cb6540e052d207483396a5fd4588e3e4ddd776e02bcc107fb63ef73e19835b20b44e5c95e850d30b018bf985d898c8a2b07e6ae7a7a2984034
+  data.tar.gz: ade20718b92e00ee24274d5b0cdce3ff102ae88487cb00af244168134f1f0c0d3259cb1e7f19ade71bf8fe442cba1a764bd6550c5d1911ef7cce558fabac044f

data/CHANGELOG.md

@@ -8,6 +8,152 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-03
+
+### Added
+
+- The guardrails bundle (0.4.0) asks before git that changes another checkout: `cd ../main && git commit`,
+  `git -C ../main add .`, an `execute` with `cwd:` there (commit, add, reset, checkout, switch, rebase, merge, push,
+  stash, rm, mv, cherry-pick, revert, pull, restore, am). Read-only git and tests there still run unasked. Its card
+  offers once, this session, or "rule in this repo" (stored, so later sessions there don't ask); switch it off with
+  `guardrails.disable: [git-outside-repo]`. Run `chi update` (or `chi bundle upgrade guardrails`) to get it.
+- Web: a tab left open across a `chi web` upgrade says so: when its event stream reconnects to a newer chi, a toast
+  `chi was updated to X` offers a Reload button (it never reloads by itself; ✕ dismisses it).
+- `chi bundle trash` lists the bundle trash (moved files from uninstalls/upgrades) oldest first, with file count,
+  size, and age; `--empty` deletes all folders, `--older-than DAYS` keeps only recent ones, `--dry-run` previews.
+- A turn that runs out of iterations now waits as a question (kind `continue`, the step-limit question):
+  `chi send --wait` exits 3 with it, `chi answer --option Continue|Stop` answers it, and the web badge and bell show
+  it. The web draws it as a card with Continue, Stop and a reason for Stop; `chi --attach` reads the continue words
+  at its prompt (Enter continues). A parent agent may Continue unless `turn.parent_continue: false` (config.yml only);
+  a delegate's goes back to the parent model.
+- `turn.max_iterations` (default 100, env `SAMAGOTCHI_TURN_MAX_ITERATIONS`) sets the per-turn step limit;
+  `--no-interrupt` turns get the larger of 1000 and it.
+
+### Changed
+
+- `write-outside-repo` and any `path: outside_repo` rule measure from the session's repo (not a plugin call's own
+  `cwd:`), with symlinks resolved: `/tmp/x` and `/private/tmp/x` are the same
+  folder, and a link in the repo that points elsewhere counts as outside. Writes into tmp folders (`$TMPDIR`, `/tmp`)
+  no longer ask, unless the session itself lives there. Hook events' `targets` gain `git_dirs`.
+- A one-word `/word` that no command answers (`/modle`) is no longer sent to the model as a prompt: every UI
+  (the REPL, the attached TUI, the web composer) prints `Unknown command /modle. Did you mean /model? /help lists
+  the commands.` instead, with the "Did you mean" part only when a command name is close. Lines that are prompts
+  (`/foo bar`, `/usr/bin/env is missing`) still go to the model.
+- `chi send --wait` reports `limit` instead of `no_answer` when a turn ran out of iterations and nobody can answer
+  (an older worker), with how to continue it.
+- Stop at the step limit (`/continue no`) keeps the turn's work, with a note for the model, instead of erasing the
+  prompt and everything the turn did; `!rollback` still erases it. Reminder turns follow `turn.max_iterations`.
+- The web page's end-of-turn and card re-reads fetch only what they show: the session's state, the last answer,
+  that turn's timings and the cards, from a new light worker read (`GET /session/:id/tail`) instead of the
+  whole conversation and timing history, so they stay the same size however long the session runs.
+- `execute` gives a command 120 s by default (was 30 s) before it is killed; `execute.timeout_sec` /
+  `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC` still set it.
+- An `execute` command killed at its time limit says how to run a long one: a second line
+  `(killed at the limit; for a long command use task_create, then task_wait)` follows `Error: command timed out after Ns`.
+- `read` with only `end_line` reads from line 1 instead of failing with "start_line must be provided". A range
+  `edit` with only `end_line` still refuses (it would overwrite the top of the file) and now says what to pass:
+  `pass start_line too (1-based, the first line to replace)`.
+- In a worktree or subfolder, the system prompt's "Project root" line now says it is only where shared project
+  memories come from, and to read, edit, run and commit in the current working directory; a model took the root for
+  its workspace and committed to the main checkout.
+
+### Fixed
+
+- Web: a session waiting on a plugin card (check-in's Nudge / Keep going / Stop) shows its "needs you" badge as a
+  pill on its session card again; it was drawn as a large empty circle over the card.
+- Web: with a prompt queued behind a turn, the next turn's live timing line no longer freezes or takes the
+  previous turn's number when the previous turn's re-read lands late.
+- `chi sessions list` shows the first message of a session that has no turn yet, such as one started with
+  `chi send --new -m "/model x"` or from the web start page; its row was blank.
+- Web: a terminal-only command (`/stats`, `/exit`, `/recap` …) typed as the start page's first message is answered on
+  the start page; it no longer starts a session just to show that reply.
+
+Update with `chi update`: the guardrails bundle moves to 0.4.0 (the `git-outside-repo` rule; it needs chi 0.18.0).
+
+## [0.17.0] - 2026-10-03
+
+### Added
+
+- The system prompt names the model the session runs on: `Model: this session runs on box:gemma-small (host box,
+  box.test:8080; model key gemma-small).`, plus a line to answer "which model are you" from it, not from training
+  (a fine-tune often knows only its base model's name), and that model-only guidance goes in
+  `memory_write current_model_only: true` overlays. A local llama.cpp host whose `/props` names another model adds
+  `; the server says it serves <name>`. The line changes only with `/model`.
+- `execute` and `task_create` export `SAMAGOTCHI_SESSION_MODEL`, the session's model ref (it follows `/model`; the
+  model's `env` can't set it).
+- Plugins: `ctx.model` (the session's model ref, right after `/model` too) and `ctx.model_key` (its memory overlay
+  key).
+- `chi self` has a `model key` row: the memory overlay key of the model it reports.
+
+### Changed
+
+- `chi self` run by a session's `execute` reports **that session's** model, and its host, loop, profile, thinking and
+  served model: `model  splash:… (this session abcd1234; default main:…)`. Before, it showed the config default
+  (or the `--model` the worker started with), wrong after `/model`, for web-picker and `chi send --new --model`
+  sessions and delegate children. Elsewhere the row reads `main:… (default)`. `chi self --model` is still the default.
+- The identity memory and the preloaded memories (`--memory`, config `memories:`) get their model overlays
+  (`<name>.<key>.md`) in the system prompt, as `memory_read` gives them.
+- A session's live state (what the web and an attached terminal read from its worker) no longer carries every turn's
+  and tool call's timing record, only the newest turn's: reads stay the same size however long the session runs. The
+  full history stays in the session's `analytics.json`.
+- A memory a bundle installed says so in its `index.md` line, and so in the prompt's memory index:
+  `- **memory_guide** · system · 2026-10-03 · 5120 · from samagotchi-system — …`. `memory_write` and `write`/`edit`
+  keep the tag; a same-name memory the install skipped gets none. Bundles installed earlier get it on their next
+  install or upgrade (the system bundle: with the next chi version).
+- `chi bundle uninstall` (and an upgrade dropping a file the new version no longer ships) moves the bundle's memory
+  files to `<memories>/.bundles/.trash/<bundle>-<time>/` instead of deleting them, and says where:
+  `Moved to the trash: notes.md (…/.trash/notes-bundle-20261003-120000)`. Nothing empties the trash; delete it by hand.
+- `chi bundle build` leaves out the memories an installed bundle owns (the system bundle's `identity.md`, a shipped
+  bundle's memory), one line each: `Left out identity.md: installed by bundle samagotchi-system (name it to include
+  it)`; naming a file in `FILES...` includes it. It now prints the builder's warnings.
+- An `index.md` line a bundle install, upgrade or uninstall couldn't write or remove is now a warning
+  (`index.md: line for notes not updated (…)`) instead of passing silently; `chi bundle uninstall` of a profile
+  prints its bundles' warnings too.
+- Web: a composer line is a command only when it names one of the session's commands (or is `!…`); an unknown
+  `/word` (a path like `/usr/bin/env …`, a typo) goes to the model as a prompt, as in a terminal, instead of being
+  refused with `not a session command`.
+- Web: a window under 700 px tall hides the latest-sessions strip by itself (the `▾ N sessions` pill shows it again
+  until the window is tall), so a question or approval card in the turn's stage has room for its choices and
+  buttons. Taller windows and phones are unchanged.
+
+### Fixed
+
+- `chi self`'s `served model` row for a chat host (`api: openai`), or a server without `/props`, says
+  `reported per turn (the server has no /props)`; it said `unknown (no answer from the server's /props)`, which a
+  model took to mean the server never said what it served.
+- `chi bundle uninstall` no longer deletes a memory the user had before the install. A bundle now records (and
+  so upgrades and removes) only the files it wrote; a same-name file that was already there is reported
+  `Skipped` and stays the user's, on install, re-install and upgrade. Before, it was recorded with the user's
+  content as its base, so uninstall removed it without `--force`: a third-party bundle shipping `notes.md`, or
+  `chi bundle build` then installing the result on the same machine. An upgrade no longer reports such a file as
+  a conflict (or `chi update --dry-run` as kept). Bundles installed before this fix may still list such a file;
+  uninstall now moves it to the trash (below) rather than deleting it.
+- A memory file two installed bundles list (one an older install adopted, like `identity.md` under both
+  `samagotchi-system` and a `chi bundle build` of your memories) stays when one of them is uninstalled, or drops it
+  in an upgrade: `Kept identity.md: bundle samagotchi-system has it too`. It goes with the last one.
+- Web: after a reload, a turn with an empty retry mid-turn shows each tool row's own duration; the rows took their
+  records by iteration, so every call after the retry showed the wrong one, or none.
+- Attached TUI: `/detach` typed at a question's `?` prompt detaches (the question stays open), as Ctrl-D does; it
+  was read as an answer and refused as an unknown option.
+- Attached TUI: joining a turn while a tool call runs (a long `delegate`, a slow command), its row's duration counts
+  from the call's start, not from the join.
+- Web: in a short window a question or approval card that opens in the turn's stage is scrolled into view (its
+  choices and buttons); it sat below the prompt and headline, out of sight.
+- A session command sent as a message runs as the command, as typed in a terminal: `chi send -m "/model x" ID`,
+  `chi send --new -m "/model x"`, `chi -p "/model x"` (attached and `--non-interactive`) and the web start page's
+  first message went to the model as a prompt. `chi send` says `sent as a session command`; with `--wait` there is
+  no reply to wait for (exit 0, `--format json` status `command`). An unknown `/word` still goes to the model.
+- macOS 26: a dead worker's leftover `bridge.json` no longer counts as a live worker. Ruby's `Socket.tcp` with a
+  connect timeout returns the socket of a refused connect there, so the check said live: clients tried its port
+  first, `chi update` listed the dead worker as running, and an approval relay kept watching a parent that was gone.
+- REPL with piped input: when the input ends at a question or approval, no bare `? ` line is left above its
+  `(denied)` / `(cancelled)` summary.
+- Web: an approval from a delegate its parent isn't waiting on directly rings once (the parent's relayed card), not
+  twice: a child's approval now waits 3.5 s (was 1.5 s) for the relay before it notifies on its own. Only delegated
+  children's approvals wait; one nobody relays rings that much later.
+
+Update with `chi update` (no bundle changes; the system bundle upgrades itself with chi).
+
 ## [0.16.0] - 2026-10-03
 
 ### Added
@@ -856,7 +1002,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.16.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.18.0...HEAD
+[0.18.0]: https://github.com/dm1try/samagotchi/compare/v0.17.0...v0.18.0
+[0.17.0]: https://github.com/dm1try/samagotchi/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/dm1try/samagotchi/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/dm1try/samagotchi/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/dm1try/samagotchi/compare/v0.13.0...v0.14.0

data/README.md

@@ -201,6 +201,8 @@ npm test             # web frontend specs
 npm run e2e          # web UI happy paths in Chromium, fake model (once: npx playwright install chromium)
 ```
 
+Integration specs against a live model server, and what the suite isolates: [docs/testing.md](docs/testing.md).
+
 ## License
 
 MIT, see [LICENSE](LICENSE).

data/docs/architecture.md

@@ -177,12 +177,19 @@ rescues sink errors). A new UI (web, API) supplies its own `on_event` and
 renders whatever it needs from the stream + final `Result`. The public Engine API:
 
 ```ruby
-engine.run_turn(session, prompt, on_event: nil, max_iterations: 100, cancel_controller: nil)
+engine.run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil) # nil: turn.max_iterations
 engine.run(session: nil, prompt: "...", on_event: nil)   # create/resume session + run
 engine.system_prompt     # fully built system prompt string
 engine.session           # current session (Engine owns create/resume)
 ```
 
+The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance,
+AGENT.md, the working directory, **the model** (`Model: this session runs on
+<ref> (host …; model key …)` and a line telling the model to answer "which model
+are you" from it, not from training), the session id and log, the memory indexes,
+the identity and the preloaded memories. It is built once per loop and rebuilt only
+by a model switch (or changed tools), so the model line costs no KV churn.
+
 #### Subscribing to the live stream (and the bridge)
 
 For an **always-on** consumer (an external SSE client, a second UI), use
@@ -249,9 +256,36 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
 - `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
-  the messages itself, then streams from its `event_seq`).
+  the messages itself, then streams from its `event_seq`). Read by the web's full show
+  (`GET /api/sessions/:id`, `?parts=1`) and the plugin's `list_sessions`; every message is copied.
+- `GET  /session/:id/tail` — the page's light re-read (`Bridge#tail_frame`): `session_state_snapshot`,
+  `answer` (the last message a UI shows as an answer, `AnswerTail`: the one message, copied alone),
+  `cards` (`CardStore#list`), `event_seq`, `event_id`, all taken in one event-log hold; no message
+  list, so it costs the same however long the session is. `?turn_id=` answers that turn's answer
+  (an unknown or missing id: the newest); the only route that reads its query.
 - `OPTIONS *` — CORS preflight (`Access-Control-Allow-Origin: *`).
 
+The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` frames
+(`SessionMetrics#snapshot`) carry the session's totals and only the recent timing records: the
+newest turn the worker finished and any it hasn't saved yet (at most 20 turns), with their tool
+calls and the running turn's finished ones. The full history is the session's `analytics.json`,
+which `SessionMetrics#persist` rewrites after each turn; the web server merges the two by id.
+
+The page's frequent reads of `GET /api/sessions/:id` stay light too:
+- `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,
+  used_memory_names}, messages: [the answer], markdown_warning, timing}`, from the worker's `/tail`
+  alone (no session file parsed, no `analytics.json`); `timing` carries the worker's recent records
+  and `turn_count` (finished turns). The page merges the records by id (`timing.js mergeTiming`) and
+  finishes the ended turn's own line by its `turn_id` (sent as `&turn_id=`, which also picks that
+  turn's answer). A plain `?tail=1` (a tab opened before this) gets the whole timing.
+- `?timing=1`: the whole timing (`analytics.json` merged with the worker's `/state`) and
+  `turn_count`, when the page's merge came up short.
+- `?cards=1`: the cards, from `/tail`; the session file is only stat'ed for the 404.
+
+A worker without `/tail` (an older chi; `404 not_found`) is read through `/snapshot` in the same
+shape; any other failure (no worker, a 500, a timeout) reads the disk, trimmed to the newest
+turn's records with `recent=1`.
+
 Every route goes through `Bridge#dispatch`: an id other than the bridge's own session is
 `404 unknown_session`, and a handler that raises answers `500 bridge_error` (logged as
 `handler_failed`) rather than dropping the connection.
@@ -267,6 +301,8 @@ never pulls from the page: `chi web` runs one `Samagotchi::Web::SessionHub` (a t
 the server, no daemon) that keeps an in-memory projection of the session list and pushes
 changes to every open tab over `GET /api/events` (SSE: a `snapshot` frame on every connect,
 then `session` for an upsert and `session_gone` for a removal, `: ping` while idle, no replay).
+The snapshot names chi's version: a tab served by another one (its `<body data-version>`) offers a
+reload in a toast, since an open tab keeps its old JS across a `chi web` upgrade.
 Files stay the source of truth and workers don't know the hub. Its watcher is a 1 s tick that
 stats the sessions dir (every session writer goes tmp + rename, which bumps the dir's mtime) and
 each `<id>/` folder (recap.json, bridge.json, the stopped and archived markers), re-parsing only the files whose mtime or size

data/docs/cli.md

@@ -21,9 +21,9 @@
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). An approval can be denied, not allowed, unless `guardrails.parent_approvals: once` (a convention, not a security boundary; see [Guardrails](guardrails.md#approvals-from-a-parent-agent))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
-- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles; `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
+- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
-- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument
+- `chi bundle install|upgrade|uninstall|status|diff|list|build|trash` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument
 
 ### First setup
 
@@ -283,7 +283,12 @@ In an attached terminal:
 - The prompt stays open while a turn runs; see [Typing during a turn](#typing-during-a-turn).
 - `/model`, `/models`, `/guardrails`, `/continue`, `!rollback` and `!commands` run in the
   worker, and every UI sees their output; `/stats` and `/recap` work too. The
-  Web UI's composer takes the same commands.
+  Web UI's composer takes the same commands, and so do `-p "/model x"` and
+  `chi send -m "/model x"`. A `/word` the session doesn't know (a path, a
+  typo) goes to the model as a prompt; a one-word `/word` that no command
+  answers (`/modle`) is not sent: the UI prints `Unknown command /modle. Did
+  you mean /model? /help lists the commands.` (the "Did you mean" part only
+  when a name is close).
 - `!commands` and the model's tools run in the session's directory (where it
   was started), whichever terminal you attach from.
 - `-p` sends its prompt once attached, `--model` switches the worker's model
@@ -395,7 +400,9 @@ REPL alike:
 - `/stats` and `/recap` answer at once, and in an attached terminal so do `/help`
   and a plugin's anytime command (`/btw`). Other commands (`!cmd`, `/model`, `/models`,
   `!rollback`, `/continue`, `/guardrails`) say `busy: wait for the turn to end`
-  and go back into the prompt, so Enter runs them once the turn ends.
+  and go back into the prompt, so Enter runs them once the turn ends. A
+  one-word `/word` no command answers (`/modle`) is not steering text either:
+  the hint prints and the line is dropped.
 - A question (`ask_user_question`, a guardrails approval) turns the prompt into
   a yellow `? ` and lists its choices under it, fitted to the terminal; only a
   line submitted there answers it (a number, `1,3`, a label, `y`/`n` for an
@@ -801,8 +808,29 @@ Behavior notes:
 
 ## Iteration Limit Behavior
 
-- `max_iterations` remains a hard safety cap on tool-call rounds.
-- Tool side effects that already ran before the cap are not rolled back.
-- `Samagotchi::KernelLoop#run` now returns a resumable result object with the visible output plus the accumulated conversation.
-- If the cap is reached while tool calls are still pending, the result is marked resumable so callers can continue from the saved conversation instead of restarting from scratch.
-- In assist mode, the CLI then asks at the `? ` prompt, with the choices listed under it: `yes` (Enter alone, or `/continue`) resumes, `no` cancels, and `no, <explanation>` cancels while keeping the reason in conversation context. Once answered, one line stays: `? The turn ran out of iterations. Continue it? → no, too slow`.
+- A turn's step limit (model ↔ tool rounds) is `turn.max_iterations` in config.yml (env
+  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `100`, an integer of 1 or more). `--no-interrupt` and
+  `--non-interactive` turns get the larger of 1000 and it. Reminder turns follow it too.
+- Tool side effects that already ran before the limit are not rolled back.
+- `Samagotchi::KernelLoop#run` returns a resumable result object with the visible output plus the accumulated
+  conversation. If the limit is reached while tool calls are still pending, the result is marked resumable so callers
+  can continue from the saved conversation instead of restarting from scratch. The session's `last_turn` records it
+  (`"exhausted": true, "limit": N`).
+- In a session's worker (plain `chi`, the web, `chi send`) the offer waits as a question between turns, the
+  **step-limit question** (kind `continue`, header "Step limit", options Continue / Stop): the session reads
+  `waiting` in the lists, the web shows a card with Continue and Stop and a reason box (a reason goes with Stop), the
+  session card's badge reads `out of steps` and the bell rings ("hit its step limit"). `chi send --wait` exits 3 with
+  it and `chi answer --option Continue|Stop` answers it (see [chi as a sub-agent](sub-agent.md)). It can't be
+  dismissed. A new message instead (or a due reminder) drops it and the partial turn stays; a typed `/continue …`
+  answers it too. If the worker exits (a stop, a crash), the offer goes with it.
+- In the attached terminal (`chi --attach`) the question's prompt reads the continue words: Enter alone, `yes`, `y`
+  or `/continue` continue; `no` stops; `no, <reason>` stops and tells the model why; `1` and `2` pick the options.
+- In the plain REPL (`--no-shared`) the CLI asks at the `? ` prompt, with the choices listed under it: `yes` (Enter
+  alone, or `/continue`) resumes, `no` stops, and `no, <explanation>` stops while keeping the reason in conversation
+  context. Once answered, one line stays: `? The turn ran out of iterations. Continue it? → no, too slow`.
+- Stop keeps the interrupted turn's work in the conversation, as a Ctrl-C or a new prompt does, with a note for the
+  model that it wasn't continued (or your reason); `!rollback` still erases it.
+- `--non-interactive` (`chi -p`) has nobody to ask: the turn ends there. A `chi send --wait` on a session nobody can
+  answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`.
+- The check-in bundle's card closes as the turn ends, before the step-limit question opens, so the two never stand
+  together; with check-in's default `after: 50` and the limit of 100 a long turn usually shows a check-in card first.

data/docs/configuration.md

@@ -279,14 +279,14 @@ spec. It requires the model to call `execute` and return the current UTC date:
 
 ```shell
 SAMAGOTCHI_INTEGRATION=1 \
-SAMAGOTCHI_SERVER_HOST=192.0.2.10 SAMAGOTCHI_SERVER_PORT=8000 \
-SAMAGOTCHI_DEFAULT_MODEL=incoai/Qwen3.8-27B-Splash \
-bundle exec rspec spec/integration/chat_loop_spec.rb -fd < /dev/null
+SAMAGOTCHI_INTEGRATION_HOST=192.0.2.10 SAMAGOTCHI_INTEGRATION_PORT=8000 \
+SAMAGOTCHI_INTEGRATION_MODEL=incoai/Qwen3.8-27B-Splash \
+bundle exec rspec spec/integration/chat_loop_spec.rb
 ```
 
 The same test works against a llama.cpp OpenAI-compatible server by changing
 the host, port, and model values. The test is skipped unless
-`SAMAGOTCHI_INTEGRATION=1` is set.
+`SAMAGOTCHI_INTEGRATION=1` is set; see [Testing](testing.md).
 
 oMLX's known tool-call limitation (a stream filter that strips markup) only
 affects its `/v1/chat/completions` endpoint, not the `/v1/completions` endpoint
@@ -869,6 +869,8 @@ described in their own sections.
 | `retry.base_delay` | `0.5` | yes | |
 | `retry.max_delay` | `8.0` | yes | |
 | `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
+| `turn.max_iterations` | `100` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
+| `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |
 | `update.desktop` | `true` | | `false`: `chi update` leaves the desktop helper alone (`--no-desktop`). |
@@ -882,14 +884,14 @@ described in their own sections.
 | `execute.truncate_at_bytes` | `65536` | yes | The same for `execute` output. |
 | `execute.preview_bytes` | `12288` | yes | |
 | `execute.telemetry_threshold_pct` | `80` | yes | |
-| `execute.timeout_sec` | `30` | yes | Seconds one `execute` command may run before it is stopped. |
+| `execute.timeout_sec` | `120` | yes | Seconds one `execute` command may run before it is stopped. |
 | `web.port` | `4567` | `--port` | `chi web`'s port. See [CLI](cli.md). |
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
 | `web.view` | `stage` | yes | How `chi web` draws a turn: `stage` (the running turn pinned above the composer) or `turn` (one block per turn in the history). See [CLI](cli.md#web-views). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
 | `history.file` | state dir | | Prompt history path, shared by the TUI and the web composer. |
-| `no_interrupt` | `false` | `--no-interrupt` | Raise the tool-call limit of a turn to 1000; a top-level key. |
+| `no_interrupt` | `false` | `--no-interrupt` | Raise the step limit of a turn to 1000 (or `turn.max_iterations`, when larger); a top-level key. |
 | `no_default_input` | `false` | `--no-default-input` | Don't pre-fill `default.input`; a top-level key. |
 | `skip_agent_md` | `false` | | Don't load AGENT.md; a top-level key (see below). |
 

data/docs/guardrails.md

@@ -118,6 +118,12 @@ directory, the rule) stay with the web and the terminal. An approval that
 doesn't offer "once" can't be allowed from a parent, and neither can one whose
 offered scopes are missing or don't fit its options: then only Deny goes.
 
+A child that has to work in another folder (`write-outside-repo`,
+`git-outside-repo`) is denied this way too. Start it in that folder instead
+(`chi send --new --dir PATH`), or have your user allow "rule … in this repo"
+once on the web (it is stored for later sessions in that repo), or switch the
+rules off: `guardrails: {disable: [write-outside-repo, git-outside-repo]}`.
+
 Whatever the setting, a parent can't allow a call on chi's own files: a
 `write`, `edit` or `execute` on the config dir (config.yml, installed bundles'
 rules), the hooks dir or the approval store, by its rule (`chi-config`,
@@ -126,6 +132,11 @@ config.yml rewrite would allow everything from then on, so those stay with the
 user: `chi answer` and the worker refuse the allow with `only the user can
 allow it`.
 
+A turn's step-limit question (kind `continue`) isn't an approval: Continue
+grants no permission, so a parent may answer it either way by default.
+`turn.parent_continue: false` (config.yml only, like `parent_approvals`)
+makes parents stop-only. See [chi as a sub-agent](sub-agent.md#the-step-limit).
+
 The guardrails settings (`enabled`, `small_models`, `parent_approvals`) are
 read from config.yml only: they have no environment variable, and a worker
 chi starts unsets every `SAMAGOTCHI_GUARDRAILS_*` it would inherit. What a
@@ -182,9 +193,16 @@ guardrails:
       tool: [write, edit]
       path: outside_repo     # or a glob: "**/.git/hooks/**", "/etc/**", "config/*.yml"
       verdict: ask
-      reason: writes outside the repository
+      reason: writes outside this session's repo
+    - id: git-outside-repo
+      tool: shell
+      git: outside_repo      # a shell call runs commit/add/reset/… in another checkout
+      verdict: ask
+      scopes: [once, session, rule]
 ```
 
+A rule gives at least one of `tool`, `command`, `path` and `git`.
+
 A tool name may be a glob, so one rule covers a plugin's tools (an MCP server's,
 say): `tool: "mcp_*"` or `tool: ["mcp_{git,gh}_*", web_fetch]` (`*`, `?`, `[…]` and
 `{a,b}`, matched with `File.fnmatch`). `/guardrails` lists the glob as given.
@@ -203,11 +221,30 @@ All the fields a rule gives must match. Absolute and `**/` globs match the
 resolved path; other globs match the path relative to the repo root. Paths
 resolve the way the tools resolve them (against the cwd; `~` expanded).
 
-`outside_repo` leaves out a memory's file: a `*.md` right in the project or
-system memories folder (not `index.md`, not a hidden file). `write`/`edit`
-there is what `memory_write` does unasked, and the model is told to `edit` a
-memory for a small change. The memories folder's `index.md`, `.bundles/`, and
-the rest of chi's config folder still count as outside.
+`outside_repo` is measured from the session's repo: the git work tree its
+folder is in (a linked worktree is its own), or the folder itself outside a
+repo. Not the call's own `cwd:`: an `execute` with `cwd:` in another checkout
+is outside. Symlinks are resolved on both sides (`/tmp` and `/private/tmp` are
+one folder; a link in the repo that points elsewhere is outside). Never outside:
+
+- a memory's file: a `*.md` right in the project or system memories folder (not
+  `index.md`, not a hidden file). `write`/`edit` there is what `memory_write`
+  does unasked, and the model is told to `edit` a memory for a small change.
+  The memories folder's `index.md`, `.bundles/`, and the rest of chi's config
+  folder still count as outside, as does chi's state folder (sessions,
+  approvals);
+- a tmp folder (`$TMPDIR`, `/tmp`, `/var/tmp`), unless the session's repo is
+  itself in that tmp folder: a sandbox there still gets asked about its siblings.
+
+`git: outside_repo` (shell tools only) reads the command for git subcommands
+that change a checkout: `commit`, `add`, `reset`, `checkout`, `switch`,
+`rebase`, `merge`, `push`, `stash` (not `stash list`/`show`), `rm`, `mv`,
+`cherry-pick`, `revert`, `pull`, `restore`, `am`. It follows `cd`,
+`pushd`/`popd`, `( … )`, `git -C`, `--git-dir`/`--work-tree`, `GIT_DIR`/`GIT_WORK_TREE`
+and the call's `cwd:`, and matches when one of them runs outside the session's
+repo (the same `outside_repo` as above). `cd /other && git status`, `git -C
+/other log` and `cd /other && bundle exec rspec` don't match. A folder the text
+doesn't tell (`cd $REPO`, `cd "$(…)"`, `cd -`) doesn't either; see Limits.
 
 To switch off single rules (a bundle's, say) without editing its files, list
 them under `disable:`. A plain id switches off every rule with that id; `bundle:id`
@@ -268,7 +305,10 @@ installs a default rule set plus a short memory telling the model not to
 route around a deny. It asks before `git push`, `reset --hard`, `clean -f`,
 `branch -D`, `rebase`, `filter-branch`/`filter-repo`; `rm -rf` on `/`, `~`,
 `$HOME` or `..` paths; `curl … | sh` and `base64 -d … | sh`; writes outside the
-repo; shell commands that name chi's config, hooks or guardrails or
+session's repo (`write-outside-repo`) and git that changes another checkout
+(`git-outside-repo`: `cd ../main && git commit`, `git -C ../main add .`; it
+offers once, this session and "rule in this repo", the last stored for later
+sessions in that repo); shell commands that name chi's config, hooks or guardrails or
 `.git/hooks`; and answering chi's questions around `chi answer`: `chi --attach`
 or `chi -p` with stdin from a pipe, a here-string or a file
 (`chi-answer-piped`), and `curl`/`wget` to a session's `/answer` route
@@ -354,6 +394,9 @@ it as `~` or `$HOME`, so the model rarely has to spell it.
 
 Text matching on shell commands stops accidents, not a model set on getting
 around it: `sh -c`, base64, a script written earlier, `git -C` variants and
-aliases can get past a regex. `!cmd` lines typed by you are not checked. The only
+aliases can get past a regex. `outside_repo` covers the file tools and git
+only: `sed -i`, `cp` or `cat > file` into another folder from the shell aren't
+asked about, and neither is git run through `sh -c`, a script, an alias, `make`
+or a folder in a variable. `!cmd` lines typed by you are not checked. The only
 real defence against an adversarial model is isolation (a sandbox, a git
 identity without push rights).

data/docs/hooks.md

@@ -341,7 +341,10 @@ the voter's own (a guard that wants the model to retry a corrected call:
 `event[:context]` is `{cwd:, repo_root:, branch:, session_id:, interface:, origin:}`
 (`interface` is `:repl`, `:worker` or `:non_interactive`). `event[:targets]` is
 what the call acts on, resolved as the tools resolve it:
-`{command:, paths:, cwd:, repo_root:, outside_repo:}`.
+`{command:, paths:, cwd:, repo_root:, outside_repo:, git_dirs:}`. `outside_repo`
+is measured from the session's repo, not the call's `cwd:`; `git_dirs` lists where
+a shell call runs git that changes a checkout (`"unknown"` for a folder the
+text doesn't tell; `[]` for other tools).
 
 The older flag still works: `event[:blocked] = true` with an optional
 `event[:block_reason]`. It is folded into the verdict after each hook (so it

data/docs/internals/background-tasks.md

@@ -22,5 +22,6 @@ Behavior:
 - `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) and `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown). `chi self` reads the latter for its `model` row.
 
 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/memory.md

@@ -23,6 +23,8 @@ Each memory entry may have a companion file named `<name>.<model-key>.md` in the
 
 - **Key derivation**: The harness normalizes the model name sent to the server, without its host prefix (`box:qwen3.6-35b-a3b` keys as `qwen3.6-35b-a3b`; an alias keys as its target, and the alias's own key is read when the target has no overlay) (lowercase, replace non-alphanumeric with `-`, squeeze dashes) to derive the file key. For example, `qwen3.6-35b-a3b` → `qwen3-6-35b-a3b`.
 - **Saving overlays**: Pass `current_model_only: true` to `memory_write` (the harness resolves the model key automatically). This writes the content as `<name>.<model-key>.md` and skips index maintenance.
+- **Which key is mine**: the system prompt's `Model:` line names the session's model key, and `chi self` (via `execute`) has a `model key` row; both follow `/model`.
+- **In the system prompt**: the identity memory and the preloaded memories (`--memory`, config `memories:`) get their overlays too, as `memory_read` gives them; after `/model` the rebuilt prompt carries the new model's.
 - **Dormancy**: Overlays are only active under the matching model key; other models see the base entry only.
 - **Invariant**: The base entry is the contract. Overlays only add model-specific guidance and never contradict the base protocol.
 
@@ -80,6 +82,45 @@ skills`, [docs/plugins.md](plugins.md#the-skills-bundle)) adds `/skill save`,
 one-line diff after each update, and nudges a model that skips a failing
 step instead of fixing the skill.
 
+## What a bundle owns
+
+A bundle owns the memory files it wrote, nothing else. `chi bundle install`
+copies each of its `*.md` files into the scope dir; a file of the same name
+that is already there is left as it is and reported `Skipped` (`--force`
+overwrites it, and then the bundle owns it). A skipped file stays yours: the
+bundle doesn't record it, so `chi bundle upgrade` never merges into it and
+`chi bundle uninstall` never removes it. That holds for a file the user wrote,
+for `chi bundle build` then installing the result on the same machine, and
+for a file another bundle installed.
+
+- **The index says where a memory came from.** The `index.md` line of a file
+  a bundle installed ends in `· from <bundle>`, before the description:
+  `- **memory_guide** · system · 2026-10-03 · 5120 · from samagotchi-system —
+  …`. `memory_write`, `write` and `edit` keep it. A bundle installed by chi
+  0.16 or earlier gets it on its next install or upgrade.
+- **Uninstall moves, it doesn't delete.** The bundle's memory files go to
+  `$XDG_CONFIG_HOME/samagotchi/memories/.bundles/.trash/<bundle>-<YYYYmmdd-HHMMSS>/`,
+  and the output names them and the dir:
+  `Moved to the trash: notes.md (…/.trash/team-notes-20261003-120000)`. So
+  does an upgrade's removal of a file the new version no longer ships. A
+  file you edited still needs `--force`. `chi bundle trash` lists the trash
+  (oldest first, with file count, size, and age); `--empty` deletes all
+  folders, `--older-than DAYS` keeps only recent ones, and `--dry-run`
+  previews. Hooks, rules and the plugin live in the bundle's own dir and
+  are deleted with it.
+- **A file two bundles list stays** until the last of them is uninstalled
+  (`Kept identity.md: bundle samagotchi-system has it too`); its index line
+  then names the bundle that still has it.
+- **Installs by chi 0.16 or earlier** recorded skipped files too. Such a bundle may
+  still list a file that was yours; uninstalling it moves that file to the
+  trash rather than deleting it, so check the `Moved to the trash` line and
+  move a file back if it was yours (and its line in `index.md` comes back
+  with the next `memory_write`, `write` or `edit` of it).
+- **`chi bundle build`** packs your memories, not other bundles': a memory an
+  installed bundle owns is left out with a line (`Left out identity.md:
+  installed by bundle samagotchi-system (name it to include it)`); naming it
+  in `FILES...` includes it.
+
 ## Bundle profiles: core and dev
 
 Every bundle chi ships (the system bundle aside) belongs to one of two

data/docs/plugins.md

@@ -229,8 +229,9 @@ chi's own. Path and command rules need to know what a call acts on, and that
 is what `targets:` says:
 
 - `paths:`: files the call reads or writes, absolute or relative to `cwd:`
-  (else the session's directory). `path:` globs, `outside_repo` and the
-  protected paths (chi's config, …) match them.
+  (else the session's directory). `path:` globs, `outside_repo` (measured
+  from the session's repo, whatever the call's `cwd:`) and the protected
+  paths (chi's config, …) match them.
 - `command:`: a shell command the call runs; `command:` rules match it.
 - `cwd:`: where it runs, for the repo root and relative paths.
 
@@ -478,6 +479,8 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.session_id` | the session's id (nil before there is one) |
 | `ctx.cwd` | the session's working directory |
 | `ctx.repo_root` | the git checkout holding `cwd`, or nil |
+| `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
+| `ctx.model_key` | that model's memory overlay key (`<name>.<key>.md`, what `memory_write current_model_only` writes) |
 | `ctx.settings` | the bundle's settings, frozen |
 | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use. A session's own state goes in `sessions/<id>.json` or `sessions/<id>/` there: chi removes it when the session is deleted, discarded or pruned |
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |