samagotchi 0.18.1 → 0.20.0

data/docs/sessions.md

@@ -13,17 +13,19 @@ 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`.
+**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.
 
 **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 was empty, so it is discarded.` 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.
 
 **Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
 
+**Which chi a worker runs:** a new or woken worker runs the newest chi installed for this Ruby (`gem 'samagotchi', '>= 0.a'`, prereleases count), whoever starts it: a `chi web` or terminal still on an older chi starts it on the newest one, so a stale process doesn't spread old code. A worker already running keeps its version until it is restarted. Should the newest install fail to load, the worker runs the starter's own version and logs `boot_fallback` (its stdio is `/dev/null`). Under `bundle exec` the worker drops Bundler's env first, so it activates the newest gem too. Two consequences: a wrapper pin (`chi _0.17.0_ web`) pins only that process, not the workers it starts; and a source checkout (`bin/chi` in a worktree, `bundle exec`) starts its workers on its own `lib/`, but a session it made that is later woken by an installed chi (`chi web`, `chi send`) runs the installed code. The names an older starter hands a newer worker (the boot line, its env keys, `input/` files, the session JSON fields and the Bridge routes sessions use on each other) are pinned in `spec/worker_contract_spec.rb`.
+
 **Stopping a worker:** `chi sessions stop ID` marks the session stopped (an empty `<id>/stopped` file, not a session.json field, which a worker saving at that moment would write over; a resume removes it), sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal reports when a command or a question dismiss gets a 404, and the web when an answer, a dismiss, a command or a cancel does (`501 not_supported`; `BridgeClient.stale_worker_message`). The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s.
 
 **Deleting a session:** `chi sessions delete ID...`, `/exit --delete` in a terminal and the Web UI's delete all go through `SessionManager.delete_session`: it resolves a unique prefix, removes `<id>.json` and the whole `<id>/` dir, and returns what it removed. A session a plain REPL has open (`owner.lock` kind `tui`) is always refused. One a worker runs is refused unless the caller asks to stop it: then it stops the worker as `chi sessions stop` does and deletes once `owner.lock` is free (`--force` on the CLI, 10 s; the web always, 2 s; `/exit --delete` after the worker agreed to exit, 10 s). A worker that outlives the wait leaves the session in place. The web's route is `DELETE /api/sessions/:id` (200 `{status: "deleted", session_id, stopped}`; 409 `owned_by_tui` or `still_stopping`; 404).
 
-<a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered (the step-limit question too); a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn refuses it), and an empty session is discarded instead; `chi scratch` refuses it. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and "include archived" by the all-sessions search shows them, dimmed with an `archived` badge. The info bar reads `archive · stop · delete` (`unarchive` on an archived one); archiving the open session stays on it, with an Undo toast.
+<a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered (the step-limit question too); a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn refuses it), and an empty session is discarded instead; `chi scratch` refuses it. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and "include archived" by the all-sessions search shows them, dimmed with an `archived` badge. The info bar marks a session whose live worker runs an older chi than the newest installed (`worker_version` in its summary): `chi 0.18.1 · Restart`, which asks to confirm and calls `POST /api/sessions/:id/restart` (a refusal's reason shows in a toast); a worker from before restarts shows `chi sessions stop ID` instead. The info bar reads `archive · stop · delete` (`unarchive` on an archived one); archiving the open session stays on it, with an Undo toast.
 
 **Lazy sweep:** automatic prune runs only while `chi web` runs, at most once per `session.sweep_interval_hours` (default 24): the web's session hub gives it a chance on its periodic full scan, and `GET /api/sessions` does too. No cron, and a terminal-only chi never sweeps. Manual prune is always available.
 
@@ -63,7 +65,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 **Ordering:**
 
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again); "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id}], warning?}`; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again); "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only. The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, sampling?}], warning?}`; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
 - The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
@@ -118,8 +120,8 @@ system message marked `kind: turn_note` (the UIs don't show it; they showed the
   before any answer: network error after 2 attempts (host main: Errno::ECONNREFUSED). The message went back to
   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;
-- cancelled (Ctrl-C, the web's stop): `[SYSTEM: the previous turn was cancelled (ctrl-c) after 12s; the answer
-  above ends where it was cut off.]`, or `…; no answer had been shown.]` when only thinking had streamed;
+- 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;
 - ended with nothing visible: `[SYSTEM: the previous turn ended with no visible answer (thinking only, or
   nothing). The user's last message is still unanswered.]`.
 

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -95,20 +95,31 @@ module Samagotchi
       # +base+, with -2, -3… when the name is taken or is the prefix of a
       # model id (chi would read "qwen3:8b" as host qwen3, model 8b).
       def host_name(base, requested: nil, model_ids: [])
+        host_name_with_reason(base, requested: requested, model_ids: model_ids).first
+      end
+
+      # [name, reason]: reason is :taken when the name was suffixed because
+      # config.yml already has it, :model_prefix when a model id's prefix
+      # would read as a host, nil when the name is free as given.
+      def host_name_with_reason(base, requested: nil, model_ids: [])
         taken = current_hosts.keys
         if requested
           name = requested.to_s.strip
           raise Error, "--name must match #{ConfigFile::HOST_NAME_RE.source}" unless name.match?(ConfigFile::HOST_NAME_RE)
           raise Error, "config.yml already has a host named '#{name}'; pick another --name" if taken.include?(name.downcase)
 
-          return name
+          return [name, nil]
         end
 
         prefixes = [*model_ids, configured_default_model].compact.map { |id| id.to_s.split(":", 2).first.downcase }
         name = base
         n = 1
-        name = "#{base}-#{n += 1}" while taken.include?(name) || prefixes.include?(name)
-        name
+        reason = nil
+        while taken.include?(name) || prefixes.include?(name)
+          reason ||= taken.include?(name) ? :taken : :model_prefix
+          name = "#{base}-#{n += 1}"
+        end
+        [name, reason]
       end
 
       # Write the entry. @param fields [Hash] the hosts entry (string keys,

data/lib/samagotchi/bootstrap_command.rb

@@ -3,6 +3,7 @@
 require "rbconfig"
 require_relative "config"
 require_relative "model_profile"
+require_relative "host_registry"
 require_relative "bootstrap/probe"
 require_relative "bootstrap/config_writer"
 require_relative "bootstrap/bundles"
@@ -235,9 +236,11 @@ module Samagotchi
 
     def test(result, model, key_env)
       done = Queue.new
-      waiting = Thread.new do
-        @stdout.puts("test: waiting for an answer (loading the model?)…") if done.pop(timeout: LOADING_AFTER).nil?
-      end
+      waiting = if loading_hint?(result)
+                  Thread.new do
+                    @stdout.puts("test: waiting for an answer (loading the model?)…") if done.pop(timeout: LOADING_AFTER).nil?
+                  end
+                end
       seconds = @probe.test_turn(result.candidate, model, key_env: key_env)
       @stdout.puts(format("test: answered in %.1f s", seconds))
       true
@@ -249,17 +252,25 @@ module Samagotchi
       waiting&.join
     end
 
+    # The "loading the model?" hint fits a local server (a llama.cpp loading
+    # weights); a remote provider's slow answer is the network, not a load.
+    def loading_hint?(result)
+      !HostRegistry.remote_address?(result.candidate.scheme, result.candidate.host)
+    end
+
     # 0 written, 1 written but not as planned, nil with @exit on a refusal.
     def write(result, model, key_env, options)
       writer = Bootstrap::ConfigWriter.new(path: @config_path, env: @env)
       fields = host_fields(result.candidate, result.native?, key_env)
       ids = result.models.map(&:id)
-      name = begin
-        writer.host_name(Bootstrap::ConfigWriter.derived_name(result.candidate.host), requested: options[:name], model_ids: ids)
+      base = Bootstrap::ConfigWriter.derived_name(result.candidate.host)
+      name, reason = begin
+        writer.host_name_with_reason(base, requested: options[:name], model_ids: ids)
       rescue Bootstrap::ConfigWriter::Error => e
         @exit = usage_error(e.message)
         return nil
       end
+      explain_name(base, name, reason)
       outcome = writer.write(name: name, fields: fields, model: model, dry_run: options[:dry_run])
       code = report(outcome, model)
       return code unless INSTALLS_BUNDLES.include?(outcome.kind)
@@ -269,6 +280,16 @@ module Samagotchi
       code
     end
 
+    # One line when the name wasn't free as derived: why chi picked another.
+    def explain_name(base, name, reason)
+      case reason
+      when :taken
+        @stdout.puts("a host named #{base} already exists; saved as #{name}, use --name to choose")
+      when :model_prefix
+        @stdout.puts("a model id starts with #{base} (chi would read it as a host); saved as #{name}, use --name to choose")
+      end
+    end
+
     # The system bundle, core, and dev when a terminal says yes: one line
     # each. 1 when something failed.
     def install_bundles(dry_run: false)

data/lib/samagotchi/bridge.rb

@@ -212,8 +212,10 @@ module Samagotchi
     # The pending question at the top level too: one asked between turns
     # (the step-limit question) belongs to no turn, so the accumulator
     # doesn't keep it.
+    # chi_version: the chi this worker runs (an attaching TUI compares it
+    # with its own).
     # @return [Hash] {messages:, current_turn:, queued:, recap:, saved_recap:, continue_offer:, pending_question:,
-    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, event_seq:, event_id:}
+    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:}
     def snapshot
       @engine.synchronize_events do
         seq = @engine.event_count
@@ -230,6 +232,7 @@ module Samagotchi
           init_tasks: @engine.init_tasks,
           cards: @cards.list,
           commands: command_registry.listing,
+          chi_version: Samagotchi::VERSION,
           event_seq: seq,
           event_id: event_id(seq)
         }
@@ -452,6 +455,12 @@ module Samagotchi
       !host.empty? && !LOOPBACK_NAMES.include?(host.downcase.sub(/:\d*\z/, ""))
     end
 
+    # What a client may ask of this worker beyond the routes, named in its
+    # sidecar (WorkerSidecar#features): a client checks a name here rather
+    # than a version.
+    # restart: POST /exit takes "restart": true (WorkerIdleExit#hold_for_restart).
+    FEATURES = ["restart"].freeze
+
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].
     # GET stream is served apart (#serve_sse owns the connection).
@@ -683,11 +692,13 @@ module Samagotchi
       @engine.announce(type: :command_queued, **command, **anytime)
     end
 
-    # A client asks the worker to exit now (`/exit` in the attached TUI). The
-    # worker decides with the 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}, or 409 {status: "held", reason:} naming what
-    # keeps it up. Returns [headers, status, body].
+    # A client asks the worker to exit now (`/exit` in the attached TUI), or
+    # with "restart": true to hand the session to a new worker on the newest
+    # chi installed (the "restart" feature). The worker decides with the
+    # 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. Returns [headers, status, body].
     def handle_exit_request(session_id, body)
       return [{}, 501, { error: "exit_unavailable" }] unless @on_exit_request
 
@@ -696,8 +707,12 @@ module Samagotchi
 
       client_id = fetched(parsed, "client_id")
       delete = fetched(parsed, "delete") == true
-      reason = @engine.synchronize_events { @on_exit_request.call(client_id, delete: delete) }
+      restart = fetched(parsed, "restart") == true
+      options = restart ? { delete: delete, restart: true } : { delete: delete }
+      reason = @engine.synchronize_events { @on_exit_request.call(client_id, **options) }
       if reason.nil?
+        return [{}, 200, { status: "restarting", session_id: @session_id }] if restart
+
         body = { status: "exiting", session_id: @session_id }
         body[:discard] = @exit_discards.call == true if @exit_discards
         return [{}, 200, body]
@@ -1029,9 +1044,10 @@ module Samagotchi
     end
 
     def write_sidecar
-      # version: the chi this worker runs (chi update reports older ones).
+      # version: the chi this worker runs (chi update and the web's badge
+      # report older ones); features: what a client may ask of it.
       WorkerSidecar.new(port: @port, bind: @bind, session_id: @session_id, started_at: Time.now.iso8601(3),
-                        version: Samagotchi::VERSION, input_format: @input_format).write(session_dir)
+                        version: Samagotchi::VERSION, input_format: @input_format, features: FEATURES).write(session_dir)
     rescue StandardError => e
       Log.warn(:bridge, "sidecar_write_failed", echo: "Bridge: failed to write #{WorkerSidecar::FILE}: #{e.class}: #{e.message}", error: e.class.name)
     end

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -17,8 +17,17 @@ module Samagotchi
     # not serve the session (404), it yields one synthetic
     # `{"type" => "stream_closed", "reason" => ...}` and stops. #close stops
     # it without that event.
+    #
+    # With +rediscover+, a failed connection first looks for the session's
+    # live worker (its sidecar): a new one (a restart) is followed from its
+    # snapshot, announced by a synthetic `{"type" => "worker_changed",
+    # "port" => ...}` first, since its event ids start over. (A new worker
+    # on the old one's port is the plain reconnect: its Bridge can't replay
+    # the old ids and sends a reset.)
     class EventStream
       DEFAULT_RECONNECT_DELAYS = [0.1, 0.25, 0.5, 1.0, 2.0].freeze
+      # Long enough for a restarted worker to boot (its Engine, the plugins).
+      REDISCOVER_DELAYS = [0.1, 0.25, 0.5, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 2.0, 2.0, 2.0].freeze
       HEADER_TIMEOUT = 5.0
 
       # @return [String, nil] the id of the last frame yielded (the reconnect cursor)
@@ -30,9 +39,13 @@ module Samagotchi
       #   tell this client's stream from others' (Bridge#open_streams_except)
       # @param reconnect_delays [Array<Float>] sleeps between failed attempts;
       #   one more failure than there are delays gives up
+      # @param rediscover [#call, nil] → a BridgeClient for the session's live
+      #   worker now, nil when there is none yet, or :gone to give up now
       # @yieldparam event [Hash] string-keyed event
-      def initialize(client, snapshot: true, client_id: nil, reconnect_delays: DEFAULT_RECONNECT_DELAYS, &on_event)
+      def initialize(client, snapshot: true, client_id: nil, reconnect_delays: DEFAULT_RECONNECT_DELAYS, rediscover: nil,
+                     &on_event)
         @client = client
+        @rediscover = rediscover
         params = []
         params << ["snapshot", "1"] if snapshot
         params << ["client_id", client_id] if client_id
@@ -86,6 +99,13 @@ module Samagotchi
             next
           end
 
+          case rediscover_worker
+          when :moved
+            failures = 0
+            next
+          when :gone then return finish("unreachable")
+          end
+
           failures += 1
           return finish("unreachable") if failures > @reconnect_delays.size
 
@@ -148,6 +168,22 @@ module Samagotchi
         nil
       end
 
+      # @return [Symbol, nil] :moved to a new worker's Bridge, :gone, or nil
+      def rediscover_worker
+        return nil unless @rediscover
+
+        found = @rediscover.call
+        return :gone if found == :gone
+        return nil if found.nil? || found.port == @client.port
+
+        @client = found
+        @last_event_id = nil
+        @on_event.call({ "type" => "worker_changed", "port" => found.port }) unless closed?
+        :moved
+      rescue StandardError
+        nil
+      end
+
       def finish(reason)
         @on_event.call({ "type" => "stream_closed", "reason" => reason }) unless closed?
       end

data/lib/samagotchi/bridge_client.rb

@@ -156,14 +156,16 @@ module Samagotchi
       post("command", payload, read_body: true)
     end
 
-    # POST /session/:id/exit: ask the worker to exit now. 200 = it will
-    # (status "exiting"), 409 = something keeps it up (reason), 404 with
+    # POST /session/:id/exit: ask the worker to exit now (+restart+: hand
+    # the session to a new worker, a worker with the "restart" feature). 200
+    # = it will (status "exiting"/"restarting"), 409 = something keeps it up (reason), 404 with
     # error "not_found" = a worker older than the route.
     # @param client_id [String] the asking UI, whose own streams don't hold
     # @return [Response]
-    def request_exit(client_id:, delete: false)
+    def request_exit(client_id:, delete: false, restart: false)
       body = { client_id: client_id }
       body[:delete] = true if delete
+      body[:restart] = true if restart
       post("exit", body, read_body: true)
     end
 
@@ -290,11 +292,13 @@ module Samagotchi
     # Follow the session's events on a reader thread (see EventStream).
     # @param snapshot [Boolean] join with a snapshot frame
     # @param client_id [String, nil] names the stream (see EventStream)
+    # @param rediscover [#call, nil] follows a new worker (see EventStream)
     # @yieldparam event [Hash] string-keyed event
     # @return [EventStream] started
-    def follow(snapshot: true, client_id: nil, reconnect_delays: EventStream::DEFAULT_RECONNECT_DELAYS, &on_event)
+    def follow(snapshot: true, client_id: nil, reconnect_delays: EventStream::DEFAULT_RECONNECT_DELAYS, rediscover: nil,
+               &on_event)
       EventStream.new(self, snapshot: snapshot, client_id: client_id, reconnect_delays: reconnect_delays,
-                            &on_event).start
+                            rediscover: rediscover, &on_event).start
     end
 
     # Open GET /session/:id/stream and read past the response headers.

data/lib/samagotchi/bundle_command.rb

@@ -263,6 +263,10 @@ module Samagotchi
       @stdout.puts "Provenance updated after interactive resolution."
       @stdout.puts "Upgrade resolved interactively."
       0
+    ensure
+      # An owned source (git/zip/tar) was kept for the incoming files above;
+      # the agent step is done with them now.
+      installer.cleanup_source!
     end
 
     def uninstall(rest)
@@ -353,15 +357,22 @@ module Samagotchi
           @stdout.puts "Bundle '#{name}' not installed."
           return 0
         end
-        @stdout.puts "Bundle: #{name} v#{st[:provenance][:version]} scope=#{st[:scope]} installed=#{st[:provenance][:installed_at]}"
-        @stdout.puts "Target: #{st[:target_dir]}"
+        @stdout.puts "Bundle: #{name} v#{st[:provenance][:version]} scope=#{status_scope(st)} installed=#{st[:provenance][:installed_at]}"
+        if st[:scope_error]
+          @stdout.puts "Target: (unknown scope: this chi can't resolve it; upgrade chi or reinstall the bundle)"
+        else
+          @stdout.puts "Target: #{st[:target_dir]}"
+        end
         st[:files].each do |k, info|
+          next @stdout.puts("  #{k}: unchecked") if info[:unchecked]
+
           mods = []
           mods << "conflict (kept your edits over v#{st[:provenance][:version]}: chi bundle diff #{name} #{k})" if info[:conflict]
           mods << "modified" if info[:modified]
           mods << "missing" if info[:missing]
-          mods << "no-index" unless info[:index_present]
+          mods << "no-index" unless info[:index_present] || info[:overlay]
           label = mods.empty? ? "ok" : mods.join(",")
+          label += " (model overlay)" if info[:overlay]
           @stdout.puts "  #{k}: #{label}"
         end
         # Hooks
@@ -408,15 +419,19 @@ module Samagotchi
           plugin = st[:plugin]
           mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
           mods += 1 if st[:hooks_requires_failure]
+          mods += 1 if st[:scope_error]
           plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
           includes = st[:provenance][:includes]
           includes_info = includes ? " includes=#{includes.join(",")}" : ""
-          @stdout.puts "  #{bname} v#{st[:provenance][:version]} scope=#{st[:scope]} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
+          @stdout.puts "  #{bname} v#{st[:provenance][:version]} scope=#{status_scope(st)} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
         end
       end
       return 0
     end
 
+    # "team (unknown)" for a scope this chi can't resolve (Status#bundle_status).
+    def status_scope(st) = st[:scope_error] ? "#{st[:scope]} (unknown)" : st[:scope]
+
     def diff(rest)
       args = rest.reject { |a| a.start_with?("--") }
       bname = args[0]
@@ -430,7 +445,11 @@ module Samagotchi
         @stderr.puts "Bundle '#{bname}' not installed"; return 1
       end
       scope = data[:scope]&.to_s || "system"
-      target_dir = Samagotchi::MemoryBundle::Installer.new(source: ".", name: bname, scope: scope).send(:resolve_target_dir, scope)
+      begin
+        target_dir = Samagotchi::MemoryPaths.scope_dir!(scope)
+      rescue ArgumentError => e
+        @stderr.puts "Bundle '#{bname}': #{e.message}"; return 1
+      end
       files = data[:files] || {}
       hooks = data[:hooks] || {}
       plugin_path = prov.plugin_path(data)

data/lib/samagotchi/bundles/check-in/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: check-in
-version: 0.2.0
+version: 0.2.1
 scope: system
 description: "Checks on a long turn: after N tool calls with no answer, a card asks the user (Nudge / Keep going / Stop), or the model is nudged to say what it has found"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:0a5ba60962206b3ec90bbaa0934a7284416aef495df8a70391d9ea47f7eb9ec1
+  sha256: sha256:afbd0ecf5a41eefe79786e089aa918728ebb0fed0e3b75f84d754a47ec6ade18
 requires_chi: ">= 0.3.0"

data/lib/samagotchi/bundles/check-in/plugin.rb

@@ -103,7 +103,11 @@ class Plugin
   def check_in(ctx, count, mode)
     case mode
     when "nudge"
-      ctx.notify("nudged the model after #{count} tool calls") if ctx.steer(message(count))
+      text = message(count)
+      if ctx.steer(text)
+        @mutex.synchronize { @nudge = { text: text, count: count } }
+        ctx.notify("nudged the model after #{count} tool calls")
+      end
     when "notify"
       ctx.notify("#{count} tool calls in this turn, no answer yet")
     else
@@ -117,15 +121,20 @@ class Plugin
     nudge_not_sent(event, ctx)
   end
 
-  # The card said "Nudged": if the turn ended before the nudge joined it
-  # (the model answered first, or the turn was stopped), the card says so.
+  # A nudge that was accepted but dropped before it joined the turn (the
+  # model answered first, or the turn was stopped): the card says so, or,
+  # for a mode nudge (no card), a notice does.
   def nudge_not_sent(event, ctx)
     id, nudge = @mutex.synchronize { [@card_id, @nudge] }
-    return unless id && nudge
+    return unless nudge
     return if steered?(event[:messages], nudge[:text])
 
     first = event[:status].to_s == "canceled" ? "The turn ended first" : "The answer came first"
-    ctx.card(id: id, title: "check-in", body: "#{first}; nudge not sent.")
+    if id
+      ctx.card(id: id, title: "check-in", body: "#{first}; nudge not sent.")
+    else
+      ctx.notify("#{first}; nudge not sent.", level: :warn)
+    end
   end
 
   # Whether this turn's messages (after its last prompt) have the steer.

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -5,8 +5,12 @@
 #
 # Fields: id, tool (a name, a list, or shell = execute + task_create),
 # command (Ruby regex), path (outside_repo or a glob), git (outside_repo:
-# a shell call runs commit/add/reset/… in another checkout), verdict (ask|deny),
-# reason, scopes (for an ask: once, session, repo, rule; default all).
+# a shell call runs commit/add/reset/… in another checkout), touches
+# (chi_dirs: a shell command names a path in chi's own dirs), skip_read_only
+# (true: a command that only reads, ls/cat/rg/sed -n/git log…, doesn't
+# match), modes (strict: only with guardrails.mode: strict; untagged rules
+# ask in every mode), verdict (ask|deny), reason, scopes (for an ask: once,
+# session, repo, rule; default all).
 # [^;&|\n]* keeps a match inside one command of a chain; the git rules match
 # the subcommand after optional global options (git -C dir push).
 rules:
@@ -31,9 +35,11 @@ rules:
     command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+branch\b[^;&|\n]*\s(-[a-zA-Z]*D|--delete\s+--force|--force\s+--delete)\b'
     verdict: ask
     reason: git branch -D deletes a branch even if it is not merged
+  # Strict mode only: a rebase rewrites local history, which the reflog keeps.
   - id: git-rebase
     tool: shell
     command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+rebase\b'
+    modes: [strict]
     verdict: ask
     reason: git rebase rewrites history
   - id: git-history-rewrite
@@ -44,10 +50,13 @@ rules:
 
   # ── deleting ───────────────────────────────────────────────────────────
   # rm with both -r and -f on an absolute path, ~, $HOME or a path with ..
-  # (a text heuristic; rm -rf build/ in the repo is not asked).
+  # (a text heuristic; rm -rf build/ in the repo is not asked), unless
+  # every rm -rf target is inside a tmp dir (rm: outside_tmp; /tmp itself,
+  # /tmp/* and a link out of it still ask).
   - id: rm-rf-wide
     tool: shell
     command: '\brm\b(?=[^;&|\n]*\s(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)(\s|$))(?=[^;&|\n]*\s(-[a-zA-Z]*f[a-zA-Z]*|--force)(\s|$))[^;&|\n]*\s(/|~|\$HOME|\S*\.\.)'
+    rm: outside_tmp
     verdict: ask
     reason: rm -rf on a path outside the working tree
 
@@ -65,10 +74,13 @@ rules:
 
   # ── work outside this session's repo, and git hooks ───────────────────
   # outside_repo: not in the session's repo (its folder outside a repo);
-  # tmp dirs and memory files don't count.
+  # tmp dirs and memory files don't count. Strict mode only, as is
+  # git-outside-repo; chi's own config and hooks still ask (core protected
+  # paths, shell-touches-chi).
   - id: write-outside-repo
     tool: [write, edit]
     path: outside_repo
+    modes: [strict]
     verdict: ask
     reason: writes outside this session's repo
   # cd/git -C into another checkout, then commit, add, reset, checkout,
@@ -80,6 +92,7 @@ rules:
   - id: git-outside-repo
     tool: shell
     git: outside_repo
+    modes: [strict]
     verdict: ask
     scopes: [once, session, rule]
     reason: runs git that changes another checkout, outside this session's repo
@@ -90,9 +103,15 @@ rules:
     reason: git hooks run code on every git command
 
   # ── chi's own config, hooks, rules and approvals, from the shell ───────
+  # The real dirs (config.yml's dir, hooks, the approval store, installed
+  # bundles, this repo's git hooks), not a look-alike under /tmp or chi's
+  # own lib/samagotchi/hooks source; a word that can't be resolved ($VAR,
+  # $(…), a glob) is matched as text. A command that only reads them (ls,
+  # cat, rg, sed -n) isn't asked about.
   - id: shell-touches-chi
     tool: shell
-    command: '(\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|memories/\.bundles|\.git/hooks)'
+    touches: chi_dirs
+    skip_read_only: true
     verdict: ask
     reason: the command names chi's config, hooks, guardrails or git hooks
 

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

@@ -1,10 +1,11 @@
 ---
 name: guardrails
-version: 0.4.0
+version: 0.5.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes and git in another checkout outside the session's repo, git hooks, answering chi around chi answer), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config from the shell, answering chi around chi answer; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
-# models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0
-requires_chi: ">= 0.18.0"
+# models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0;
+# skip_read_only:, touches:, rm: and modes: need 0.20.0
+requires_chi: ">= 0.20.0"
 files:
   guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

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

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.4.0
+version: 0.4.1
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:009dbb3b754958a6d9edb1e3b828f486aa0ddd09ff5b548f0c576abbfea18807
+  sha256: sha256:7c87e14dbdb20d32c37ef2a83f8d56448807ad26564a4034db4f6afbcf8a0323
 requires_chi: ">= 0.8.0"