samagotchi 0.153.0 → 0.154.1

data/docs/cli.md

@@ -1,4 +1,4 @@
-# CLI and REPL
+# CLI and terminal
 
 ## Commands
 
@@ -7,8 +7,7 @@
 - `chi -p "your prompt"` — run a prompt, then stay attached
 - `chi -p "your prompt" --non-interactive` — run a prompt, print the answer, exit
 - `chi --resume <session-id>` — resume a prior session (in its worker)
-- `chi --no-shared [--resume <session-id>]` — the plain in-process REPL instead, for this run
-- `chi scratch [options]` — a one-time session in the plain in-process REPL, in this folder, that leaves nothing behind (see [Scratch sessions](#scratch-sessions))
+- `chi scratch [options]` — a one-time session in this folder, attached like plain `chi`, that leaves nothing behind (see [Scratch sessions](#scratch-sessions))
 - `chi --attach <session-id>` — attach the terminal to a session's worker (e.g. one started from the Web UI), waking one if it has exited
 - A session id can be shortened to any unique prefix (like git): `chi --attach 2ea8`. `--resume`, `--attach`, `sessions stop`, `sessions archive` and `sessions delete` take one; an ambiguous prefix lists the sessions it matches.
 - `chi web [--port 4567] [--open] [--scope=all] [--start-dir DIR]` — start the Web UI (single localhost port session control plane) on this git project's sessions (`--scope=all`, or a folder in no repo: `/?scope=all`, every session); if a chi web already runs on the port, print (with `--open`, open) its page for this folder and exit. Something else on the port (an older chi web too) exits 1 with "port N is in use"
@@ -441,11 +440,9 @@ invalid option (exit 1).
 
 | Flag | Purpose |
 |------|---------|
-| `-p`, `--prompt TEXT` | Feed `TEXT` as the first turn (also prefill-equivalent; `-p` feeds **and** runs). |
-| `--non-interactive` | Run a single turn then exit the REPL (sets a high iteration cap; implies `--no-interrupt`). Harmless no-op when given without `-p`. |
+| `-p`, `--prompt TEXT` | Run `TEXT` as the first turn, then stay attached to the session (`-p` feeds **and** runs); with `--non-interactive`, one turn and exit. |
+| `--non-interactive` | Run the `-p` prompt as one turn in this process, then exit: no worker, no TUI (sets a high iteration cap; implies `--no-interrupt`). Harmless no-op when given without `-p`. |
 | `--resume SESSION_ID` | Load a prior session's history instead of creating a fresh one. |
-| `--shared` | Run the session (new, or `--resume`'s) in a background worker and attach to it: the default, and the way to get it when `session.shared` is off. See [Sharing a session](#sharing-a-session). |
-| `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
 | `--remote NAME` | Before a session command (`chi --remote studio send …`) or the run flags (`chi --remote studio --attach ID`, `--resume ID`, `--dir DIR -p TEXT`): run it against that remote's sessions, through its chi web; beats `CHI_REMOTE`. Commands and flags that run on this machine only exit 2. See [Remote sessions](#remote-sessions). |
 | `--dir DIR` | With `--remote`: a new session's folder on that machine, its absolute path (required for a new session there). Without `--remote` it exits 2: cd there instead. |
@@ -462,8 +459,8 @@ invalid option (exit 1).
 | `--llm-context-apply RULE` | This session's own apply rule: `payoff`, `next_request` or `turn_end`. |
 | `--llm-context-budget TOKENS` | This session's own context budget: `64000`, `64k` (4k to 10M), or `off` (wins over the model's budget). |
 | `--no-interrupt` | Raise the tool-call limit to 1000 iterations for long tasks. |
-| `--no-default-input` | Skip prefilling the first REPL line from `SAMAGOTCHI_DEFAULT_INPUT`. |
-| `-v`, `--verbose` | Log at debug level (raw LLM responses, tool call/result payloads) and print every log record to stderr too. |
+| `--no-default-input` | Skip the default input (`SAMAGOTCHI_DEFAULT_INPUT`) typed into a new session's first prompt. |
+| `-v`, `--verbose` | Log at debug level (raw LLM responses, tool call/result payloads). Attached, the terminal shows this session's debug records above the prompt as they come, and a worker this chi starts logs at debug too; a worker that was already running keeps its own level (a one-line note says so). `chi web -v` logs at debug too (its `/api/` requests among them) and so does every worker it starts from then on (a new session, a wake, a restart: they all take `SAMAGOTCHI_LOG_LEVEL=debug`, `Config.cli_env`), into the same log; a worker already running keeps its level. With `--non-interactive`, every log record goes to stderr too. This machine only (exit 2 with `--remote`). |
 | `--version` | Print `chi <version>` and exit (`chi self` shows it with the paths). |
 
 Every setting in the config registry (`lib/samagotchi/config.rb`) that exposes a CLI
@@ -486,13 +483,12 @@ as an unknown key).
 |---------|----------|
 | `chi` | Start a fresh session in a worker and attach to it. |
 | `chi -p "refactor this"` | Start a session in a worker, send the prompt, **stay attached**. |
-| `chi -p "refactor this" --non-interactive` | Run one turn in this process, save, **exit** (no REPL, no worker). |
+| `chi -p "refactor this" --non-interactive` | Run one turn in this process, save, **exit** (no TUI, no worker). |
 | `chi --non-interactive` | Harmless no-op exit; no session created, no error. |
 | `chi --resume ID` | Resume session `ID` in a worker (or join the worker already running it) and attach. |
 | `chi --resume ID -p "next step" --non-interactive` | Resume `ID`, run the prompt, save, exit. |
 | `chi --resume ID -p "next step"` | Resume `ID`, send the prompt, **stay attached** to that session. |
-| `chi --no-shared [...]` | The same, in the plain in-process REPL. |
-| `chi scratch [-p ...] [--non-interactive]` | A new session in the plain REPL, deleted when it ends. |
+| `chi scratch [-p ...] [--non-interactive]` | A new session, attached (or one turn with `--non-interactive`), deleted when it ends. |
 
 Notes:
 
@@ -507,14 +503,14 @@ Notes:
   script, `chi send --new --wait` is the better entry point: stdout holds the
   answer alone (see [Starting a session](sessions.md#starting-a-session)).
 - `-p` always feeds **and** runs the prompt; there is no feed-and-edit variant. To
-  prefill (edit, not execute) the first REPL line, use the
+  prefill (edit, not execute) a new session's first prompt, use the
   `SAMAGOTCHI_DEFAULT_INPUT` environment variable instead.
 - Prompt history (↑) is one file shared by every session (see [Persistent Prompt
   History](#persistent-prompt-history)); `--resume` preserves the session's prior
   messages as turn context (a `-p` run on a resumed session never clobbers its
   conversation).
 - Non-interactive runs (`-p` with `--non-interactive`, or bare `--non-interactive`)
-  print only the final result output on stdout — no spinner, status line, or REPL.
+  print only the final result output on stdout — no spinner, status line, or prompt.
   Everything else goes to stderr: the `Session: ID` line first, before the turn;
   retry lines and hooks' notices as they come, the after_turn hooks' ones
   (source-links' `sources:`) after the answer; and the error of a failed turn,
@@ -531,19 +527,30 @@ Notes:
 
 ### Scratch sessions
 
-`chi scratch` is `chi --no-shared` for a session you won't keep: a quick
-question, a try-out. It takes the run options (`-p`, `--non-interactive`,
-`--model`, `--profile`, `--memory`, `--mute`, `-v`, …); `--resume`, `--attach`
-and `--shared` are refused. Its first line says it is a scratch session.
-
-- The session is deleted however it ends: `/exit`, Ctrl-D, Ctrl-C at the
-  prompt, an error, SIGTERM or SIGHUP. There is no recap, and the lines typed
-  are not added to the prompt history.
-- It never shows in `chi web`. A process killed with `kill -9` leaves its
-  session behind, marked `"scratch": true` in its session.json: `chi sessions
-  list` shows it as `[scratch]`, and the next sweep or `chi sessions clean`
-  deletes it. `chi --resume` and `--attach` refuse it (exit 1), so it never
-  turns into a kept session.
+`chi scratch` is plain `chi` for a session you won't keep: a quick question, a
+try-out. It takes the run options (`-p`, `--non-interactive`, `--model`,
+`--profile`, `--memory`, `--mute`, `-v`, …); `--resume` and `--attach` are
+refused. Its first line says it is a scratch session.
+
+- It runs attached, on a worker of its own. Ctrl-D, `/detach`, `/exit` and a
+  second Ctrl-C all end it: the terminal stops the worker and deletes the
+  session (`Scratch session deleted.`). `/archive` is refused. The lines typed
+  are not added to the prompt history. With `-p … --non-interactive` it is one
+  turn in this process, and the session is deleted as the run ends.
+- The worker deletes the session too once its terminal is gone (no terminal
+  stream left for about 28 s, twice the terminal's reconnect retries, so a
+  dropped stream that reconnects keeps it; or none came within 30 s), so a
+  closed terminal window or a `kill -9` of the terminal leaves nothing: a turn
+  still running then is cancelled first. Another client's stream never keeps
+  it. It refuses `chi sessions restart`.
+- It never shows in `chi web`, and only its terminal uses it: `chi send`, the
+  web's routes (a tab opened at its id too: its page and stream answer 409
+  `scratch`), `chi --resume` and `--attach` refuse it (exit 1), in one
+  wording: "that's a chi scratch session: only the terminal that started it
+  uses it (a leftover one is deleted at the next sweep: chi sessions clean)".
+  A session left behind when both died is marked `"scratch": true` in its
+  session.json: `chi sessions list` shows it as `[scratch]`, and the next
+  sweep or `chi sessions clean` deletes it.
 - Memories are read and preloaded as usual, but nothing is saved: `memory_write`
   answers "scratch session: nothing is saved", and `write`/`edit` into the
   memories folder are denied (a guardrail, rule `scratch-session`). `execute`
@@ -557,13 +564,13 @@ and `--shared` are refused. Its first line says it is a scratch session.
 
 ### Sharing a session
 
-Two different things share a session: `session.shared` is about UIs — several
-terminals and the Web UI attached to one worker — while `chi share` invites
-other people, participants with a link of their own (see
-[Participants](#participants)).
+Two different things share a session: several terminals and the Web UI
+attached to one worker, and `chi share`, which invites other people,
+participants with a link of their own (see [Participants](#participants)).
+This section is about the first.
 
 Plain `chi` runs the session in a background worker and attaches the terminal
-to it (`session.shared`, default `true`). A worker's session can have any number
+to it; every interactive `chi` does (plain, `-p`, `--resume`, `--attach`). A worker's session can have any number
 of UIs at once: the Web UI and attached terminals (`chi`, `--resume`,
 `--attach`). They all see the same turns as they happen, and any of them can send
 a prompt, also while a turn runs (it merges into that turn as steering: the model
@@ -639,7 +646,7 @@ In an attached terminal:
   was started), whichever terminal you attach from.
 - `-p` sends its prompt once attached, `--model` switches the worker's model
   first, and `--no-interrupt` applies to each prompt this terminal sends.
-- History, completion and the idle status line work as in the REPL.
+- Prompt history (↑), Tab completion and the idle status line work there.
 - The attached view needs reline 0.6.x to draw around the open prompt; with
   another version it prints plainly.
 
@@ -686,7 +693,7 @@ sessions restart ID`, the terminal with `/detach` and `chi --attach ID`), and
 the web's, `list_sessions`) and keeps them for good: the retention sweep never
 deletes an archived session, nor counts it. Its delegates go with it. A live
 worker is stopped first; a session running a turn (or with a delegate running
-one), open in a plain REPL, or a `chi scratch` one is refused. `chi sessions
+one), one a `--non-interactive` run has, or a `chi scratch` one is refused. `chi sessions
 list --archived` shows them too, marked `[archived]` (`archived: true` in
 `--format json`); `chi sessions unarchive ID...` brings them back, and so does
 a message you send to one (the web, an attached terminal, `chi send`), but not
@@ -701,7 +708,8 @@ it). See
 session file and its whole directory (notes, images, queued input). Each id
 (or unique prefix) gets one line: `deleted`, or `refused` with the reason. A
 session whose worker runs is refused unless `--force` stops the worker first;
-one open in a plain REPL is always refused ("close it there first"). Exit
+one a `--non-interactive` run has is always refused ("in use by a one-turn chi
+--non-interactive run or an older chi's terminal; let it finish first"). Exit
 status: 0 when all are gone, 1 when any was refused or unknown, 2 on a usage
 error. The Web UI deletes too: `delete` in the info bar, or the ✕ on a card in
 All sessions; it asks first and stops a live worker.
@@ -718,18 +726,12 @@ object `{session_id, status, live, metrics, settings}` (`settings`: the session'
 exits 0. An unknown or ambiguous id exits 1 with `chi sessions stop`'s
 wording. See [Sessions](sessions.md#cli).
 
-**The plain REPL.** Some launches run the session in this process instead, with
-no worker:
-
-- `--no-shared`, for one run, or `session.shared: false` in the config
-  (`SAMAGOTCHI_SESSION_SHARED=0`), for every run.
-- `--non-interactive`, a one-shot with no REPL.
-- `--verbose`, which attached mode can't honor (the worker prints nothing). It
-  prints a one-line note, `(session.shared: --verbose runs in a plain REPL)`.
-
-A session the REPL has open can't be shared: `--resume` and `--attach` on it say
-"close it there first", and the Web UI shows it read-only. `--attach`/`--shared`
-can't be combined with `--non-interactive` or `--verbose`.
+**One-turn runs.** `chi -p TEXT --non-interactive` (also with `--resume ID`)
+runs its turn in this process, with no worker, and holds the session until it
+ends. Meanwhile the session is "in use by a one-turn chi --non-interactive
+run or an older chi's terminal": `--resume`, `--attach`, `chi send`, `chi note` and the Web UI's sends
+refuse it, and the Web UI shows it read-only. `--attach` can't be combined with
+`--non-interactive`.
 
 ### Muting a memory
 
@@ -741,8 +743,8 @@ file and index line stay as they are; only this session doesn't see it.
 - `--memory` and `--mute` are session fields (`preloaded_memory_names`,
   `muted_memory_names` in the session's JSON), written before the worker
   starts. A worker respawned by `--resume`, `--attach` or `chi send` builds
-  the same prompt, and a REPL `--resume` of that session keeps the lists too
-  (merged with the flags it is given).
+  the same prompt, and a `--resume ID --non-interactive` one-shot keeps the
+  lists too (merged with the flags it is given).
 - A mute wins: `--mute user_preferences` drops that config baseline entry for
   one session, and `--memory x --mute x` is a mute (one warning line).
 - Names are checked before the launch, warnings only: `Warning: --memory 'x'
@@ -908,7 +910,7 @@ guardrails.parent_answers: soft)`). `/parent-answers hard|standard|soft` sets th
 session's own, `/parent-answers default` drops it; it is saved at once and
 holds from the next answer. It never goes looser than config.yml's (the reply
 says when config.yml's applies instead). Anyone may tighten it; only you loosen
-it, at the REPL, an attached terminal or the web: `chi send`, a piped or marked
+it, at an attached terminal or the web: `chi send`, a piped or marked
 attach and `chi -p --non-interactive` are refused. `/parent-answers` alone answers
 mid-turn too; a change waits for the turn's end. No chip: its reply is where the
 web shows it. See [Guardrails](guardrails.md#answers-from-a-parent-agent).
@@ -937,21 +939,19 @@ the model's `objectives` tool); [Objectives](sessions.md#objectives) has what th
   `check: …` under the move. Information only: it edits nothing, and it is refused for an objective with no move or a dropped one, and during a participant's turn. See [Objectives](sessions.md#objectives).
 
 All of them run mid-turn too. An edit answers with the new list at once and goes into the conversation between turns.
-Refused in a chi REPL's session (`--no-shared`), as `chi note` is; `/objectives` alone still answers there.
+Refused while a `--non-interactive` run has the session, as `chi note` is.
 
 A `/model`, `/llm-context`, `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
 asks first: the reply says what it costs, changes nothing, and names the line
 that applies it (`/thinking low --yes`, `/model qwen --default --yes`). `--yes` (or `-y`) applies it at once.
 The terminal puts that line in the next input (Enter applies it); the web's
 reply has an Apply button. `chi send ID "/thinking low"`,
-`chi -p "/thinking low" --non-interactive` and lines piped into the REPL apply
-without asking (a plain `chi -p` opens the REPL, which asks). See "Changes that
+and `chi -p "/thinking low" --non-interactive` apply without asking. See "Changes that
 restart the prompt cache" in [configuration.md](configuration.md).
 
 ### Typing during a turn
 
-The prompt stays open while a turn runs, in an attached terminal and in the plain
-REPL alike:
+The prompt stays open while a turn runs in an attached terminal:
 
 - A line you submit merges into the running turn at its next step (after the
   current tool call or answer): `(goes in at the next step)` at once, then
@@ -968,7 +968,7 @@ REPL alike:
   off; goes in at the next step)` (`steer.cut_after` is 0, per host/model:
   `steer_cut_after`, or no generation to cut).
 - `/queue TEXT` runs TEXT as a turn of its own after this one, in an attached
-  terminal, the plain REPL and the web composer alike: `(queued: runs after this
+  terminal and the web composer alike: `(queued: runs after this
   turn)` (the web draws it as a queued bubble until its turn starts). It never
   merges into the running turn, and a plain line sent after it still does.
   Several queued lines run one turn each, in the order sent; they still run
@@ -980,7 +980,7 @@ REPL alike:
   with images works the same way: it waits for the turn's end, and the lines
   sent after it still go in at the next step.
   At the open prompt (no turn running) `/cut TEXT` and `/queue TEXT` run TEXT
-  as a normal prompt, and the terminals say so: `(nothing is running: sent now)`.
+  as a normal prompt, and the terminal says so: `(nothing is running: sent now)`.
 - `/unqueue` (attached terminal) takes back the newest line this terminal
   queued that hasn't started: `removed: <its first 60 characters>`, and its text
   goes back into the input to change and send again (not over typed text: then
@@ -991,8 +991,7 @@ REPL alike:
   `(not removed: it already started)` when its turn won the race, `(not removed:
   it is already gone)` when another client removed it. Other terminals that
   showed it say `(a queued message was removed)`; the web drops its bubble. A
-  worker older than it is not asked: `(/unqueue needs a newer worker: …)`. In
-  the plain REPL it answers with a note (its own queue is not touched), and the
+  worker older than it is not asked: `(/unqueue needs a newer worker: …)`. The
   web's composer points at the × on the bubble.
 - **The web composer** has a row above the text field in a session (always
   there, so the composer never changes height): the keys while idle, and while
@@ -1050,24 +1049,16 @@ REPL alike:
   typed comes back once it closes. The choices then go, and one line stays:
   `? Pick a fruit → Banana`.
 - Ctrl-C cancels the turn and keeps what you typed.
-- In the plain REPL, Ctrl-D on an empty prompt (or `exit`, `/exit`, `/quit`) mid-turn
-  exits once the turn ends: `(exits after this turn; Ctrl-C cancels it)`
-  (`/exit --delete` deletes the session then too). In an
-  attached terminal it detaches at once and the turn goes on in the worker
-  (`/exit` then says the worker stays up: a turn is running).
-- `/archive` mid-turn archives once the turn ends:
-  `(archives after this turn; Ctrl-C cancels it)` in the plain REPL,
-  `(archives after this turn)` in an attached terminal, which also waits for
-  the commands queued behind the turn.
-
-With stdin that isn't a terminal (a pipe), the REPL reads a line only between
-turns.
+- Ctrl-D on an empty prompt mid-turn detaches at once and the turn goes on in
+  the worker (`/exit` then says the worker stays up: a turn is running).
+- `/archive` mid-turn archives once the turn ends: `(archives after this
+  turn)`; it also waits for the commands queued behind the turn.
 
 ### Images
 
 A model that can see images gets them these ways:
 
-- **`@path` in a prompt** (REPL, attached terminal, `-p`): `what's wrong in
+- **`@path` in a prompt** (attached terminal, `-p`): `what's wrong in
   @shot.png?`, `@~/Desktop/a.jpg`, `@"my shot.png"`. Each `@` token that names an
   image file (png, jpeg, gif, webp; bmp, tiff and heic are converted) goes with
   the prompt, and a dim line shows it: `[image shot.png 1280×800 · ~1.3k tokens]`.
@@ -1583,7 +1574,7 @@ chi --remote studio --dir /Users/me/app -p "hi"        # a new session there (--
   `--attach`/`--resume` they work as here (`--model`, `--thinking`,
   `--llm-context*` change the session; the others are named as ignored).
   `--non-interactive` (use `chi --remote studio send --new --dir D -m TEXT
-  --wait`), `--verbose`, `--no-shared`, `--memory`, `--mute` and
+  --wait`), `--verbose`, `--memory`, `--mute` and
   `--append-system-prompt` run on this machine only (exit 2).
 - `@path` images are this machine's files (read and downscaled here, then
   uploaded); Tab completes `/` commands and `@path`, not memory names. The
@@ -1736,8 +1727,7 @@ chi share revoke --all          # every link to every session
   `/share NAME [--agent] [--expires 3d] [--cap 2]` (the link and its QR code, once), `/participants` (the list),
   `/participants revoke [P]` (one participant, or everyone) and `/participants cap P DOLLARS`. They are `chi share`'s
   own, so under `chi --remote NAME` they reach that machine's chi web, as `chi --remote NAME share` does; an invite or
-  a revoke made with them isn't announced again by the `participants>` line. The REPL
-  (`--no-shared`) answers them with a note: a participant's turns run on the session's worker.
+  a revoke made with them isn't announced again by the `participants>` line.
 
 #### Review sessions
 
@@ -1806,8 +1796,7 @@ A short recap of the session, for when you come back to it: what you were
 working on, what came of it and what is still open, not a turn-by-turn log.
 
 - It is written once the session has sat idle for `recap.inactivity` (180 s)
-  after at least `recap.min_user_turns` (2) prompts, and as a worker (or the
-  REPL) exits, when something new was said since the last one. Each one
+  after at least `recap.min_user_turns` (2) prompts, and as a worker exits, when something new was said since the last one. Each one
   builds on the previous recap, so it only sends what is new.
 - It is saved with the session (`<session>/recap.json`) and shown as a dim
   `recap>` block when you attach or `--resume`, noting how many turns came
@@ -1835,8 +1824,8 @@ working on, what came of it and what is still open, not a turn-by-turn log.
 
 ## Time gaps (terminal)
 
-Both terminals (attached and the REPL) show when things happened without a
-time on every line:
+The attached terminal shows when things happened without a time on every
+line:
 
 - A dim divider marks a quiet gap of 10 minutes or more, before what comes
   next: `── 14:32 · 47 min later ──`, the date added when the day changed
@@ -1848,11 +1837,10 @@ time on every line:
   activity.
 - Attaching to a session whose last activity was 10 minutes ago or more
   says when, after the join block: `── last activity 14:32 · 47 min ago ──`
-  (from the newest timed message, else the saved recap's time). With
-  `--resume` the REPL marks the gap before the first prompt instead.
+  (from the newest timed message, else the saved recap's time).
 - A recap names the local time it was written: `recap 14:32>`, `recap 14:32
   (before the last 2 turns)>`.
-- Only live activity and the join: neither terminal replays the history, so
+- Only live activity and the join: the terminal doesn't replay the history, so
   older gaps aren't marked. `--non-interactive` prints none.
 
 ## Tool Activity Log
@@ -1872,14 +1860,15 @@ Parameter previews are normalized to one line and truncated to keep output conci
 This is separate from verbose mode:
 
 - Default output shows short activity status lines only.
-- `-v/--verbose` prints the debug log's records (raw LLM responses and full
-  tool call/result payloads among them) to stderr as well; see
+- `-v/--verbose` shows the session's debug records (raw LLM responses and full
+  tool call/result payloads among them): dim, above the prompt, in the
+  attached terminal; on stderr with `--non-interactive`. See
   [Debug Log File](configuration.md#debug-log-file).
 
 ## Persistent Prompt History
 
 Assist mode keeps a persistent prompt history across restarts, one for every
-chi prompt: the REPL, attached mode and the `chi web` composer (↑/↓ there)
+chi prompt: the attached terminal and the `chi web` composer (↑/↓ there)
 share it.
 
 - Default history file: `$XDG_STATE_HOME/samagotchi/history.json`
@@ -1895,7 +1884,7 @@ share it.
 Behavior details:
 
 - Prompt history is loaded on startup before the first `>` prompt.
-- A running REPL or attached TUI picks up the lines other chi processes (the
+- A running attached TUI picks up the lines other chi processes (the
   web, another terminal) added: before each `>` prompt and on the first ↑ at
   an open one (Ctrl-P, vi `k` too), when the file changed, its new lines join
   the ↑ list after the ones already there, without a
@@ -1914,7 +1903,7 @@ Behavior details:
 
 ## Status Line
 
-The REPL and attached mode show one status row under the prompt, drawn when what it says
+The attached terminal shows one status row under the prompt, drawn when what it says
 changes:
 
 ```
@@ -1932,11 +1921,11 @@ status> model=Qwen3.6-35B | ⑂ 2 running · 1 waiting | 2 participants | ctx=8.
 - `⑂ …`: this session's delegate children (forks aren't counted): how many run and how many wait
   for an answer; only the counts there are, nothing when none does (`/children` has the rest:
   done, failed, whether a reply was reported). The terminal reads them from the children's files
-  (the delegates in the session's `delegates.json`): an attached one when it joins, when a turn
-  ends and when a delegate's report merges into a turn, the REPL whenever it draws the row. A
+  (the delegates in the session's `delegates.json`) when it joins, when a turn
+  ends and when a delegate's report merges into a turn. A
   child that starts waiting on an approval (which doesn't wake the parent) shows at the next of
   those.
-- `N participants`: who is in the session's review now ([Participants](#participants)), attached only.
+- `N participants`: who is in the session's review now ([Participants](#participants)).
 - `ctx=`: the kernel's context estimate and its bucket, updated during a turn (on hosts that
   report none, `api: openai`, at the turn's end).
 - `mem:`: the memories the session read, with its `--memory` list; `muted:` its `--mute` list.
@@ -1960,7 +1949,7 @@ It lists the top 3 tools by count (ties go to the tool used first), the failed c
 (a call a guardrail or an approval blocked counts as a call, not as failed) and the last
 call with its parameters, cut to the terminal width. It starts over with each turn.
 
-- The REPL and attached mode: the second row of the activity slot, shown while the slot is (the
+- The terminal: the second row of the activity slot, shown while the slot is (the
   model generating or a tool running). Joining a turn mid-way seeds it from the turn so far.
 - The web: the activity panel's summary reads `activity · 12 tool calls (2 failed) · execute ×7 · …`
   (without `last:`: the rows show it).
@@ -1968,7 +1957,7 @@ call with its parameters, cut to the terminal width. It starts over with each tu
 ## Activity Row
 
 While a turn runs, one row above the prompt says what it is doing, the spinner frame first
-(the REPL and attached mode alike):
+(in the attached terminal):
 
 - `| thinking…` while the model starts, then `| thinking · <sentence>`: the newest complete
   sentence of its thinking, or of its answer (`writing ·`), like the web's thinking ticker: the
@@ -2003,7 +1992,7 @@ Behavior notes:
   tool steps keeps them, as a cancel does, with the dim `partial progress kept; !rollback restores the pre-turn state`
   (the model reads a note saying how many steps ran and why it stopped; `chi send --wait` and a delegating parent
   read `the turn failed after N tool steps: <why>; its work so far stays`). The
-  REPL and attached mode say the same; the web ends a failed turn whose steps stayed with `✕ turn failed: <summary>;
+  attached terminal says the same; the web ends a failed turn whose steps stayed with `✕ turn failed: <summary>;
   partial progress kept (!rollback restores the pre-turn state)`, after a reload too, and says `■ canceled (Ctrl-C)`
   (`stopped` for its Stop button, `by a hook` for a hook's). A turn a bundle's plugin stopped names it: `■ turn stopped by loop-guard` (the web:
   `■ stopped by loop-guard`).
@@ -2030,9 +2019,6 @@ Behavior notes:
   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`.
 - Continue goes on with the same turn: the model keeps the reasoning (thinking) of the run it continues, on chat and
   native hosts, so a local server's prompt cache stays warm. Continue's text is a steer: on a chat host the reasoning
   starts again from it. See "Reasoning history" in [configuration.md](configuration.md).

data/docs/configuration.md

@@ -64,11 +64,9 @@ model_aliases:
   small: your-small-model-id
   tiny: small-box:your-small-model-id  # alias may be bare or host:model (hybrid)
 
-# Plain chi runs its session in a background worker and attaches to it, so the
-# web UI can share it (default true; env SAMAGOTCHI_SESSION_SHARED). false keeps
-# the in-process REPL; --no-shared does for one run.
+# A session runs in a background worker; chi attaches to it, and the web UI
+# shares it.
 session:
-  shared: true
   # idle_exit_minutes: 30   # an unused worker exits after this (0 = never)
   # project_env: mise      # a worker's tools get its folder's `mise env` (off: the starter's env)
   # keep_empty: false       # true keeps sessions nothing happened in (default: deleted when left)
@@ -172,7 +170,6 @@ or `chi web` restart.
 | `system_one.host`, `system_one.model`, `system_one.timeout_ms`, `system_one.runs`, `system_one.judgments` | Next tool call or approval | Each ask reads them. |
 | `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
 | `recap.*` | Worker start | The engine builds its recap job at start, and again when it binds a session with its own `recap.enabled` or `recap.sentences` (`--set`, see "Per-session settings") and when `/recap on\|off\|default` changes the session's own value. |
-| `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
 | `session.idle_exit_minutes`, `session.project_env`, `session.carry_last_answer`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.task_wakes`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer and project env; the other values are read for the next corresponding decision. |
 | `session.retention_*`, `session.max_count`, `session.keep_status`, `session.sweep_interval_hours` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. The sweep interval is checked on the next hub tick. |
 | `web.*` except `web.participants.*` | `chi web` start | Restart `chi web` to change its bind address, port or page settings. |
@@ -355,10 +352,8 @@ For models on that host, chi uses the chat loop (its own OpenAI chat adapter): i
 takes the OpenAI base (`url:`, else `http://HOST:PORT/v1`) and streams messages plus
 function schemas from `/v1/chat/completions`; the model's reasoning (`reasoning_content`)
 shows as thinking. This works with Splash and with llama.cpp servers that
-expose the OpenAI-compatible chat endpoint. In verbose mode (`-v`), chi prints the loop the
-starting model uses (`[verbose] backend=chat` or `backend=native`); request
-bodies are not logged. The interactive REPL, `--prompt`,
-workers, and resumed sessions all use the loop of the model's host. Hosts without
+expose the OpenAI-compatible chat endpoint. Workers, `--non-interactive` one-shots and resumed
+sessions all use the loop of the model's host. Hosts without
 a chat `api:` keep using llama.cpp's native `/completion`.
 
 ### API keys from the Keychain
@@ -655,7 +650,7 @@ models:
   it, a delegate child starts without it (it runs at its model's level). Set it with:
   - `/thinking LEVEL` in the session (`/thinking default` unsets it, `/thinking` alone shows the level and where it
     came from);
-  - `chi --thinking LEVEL` on a run that starts or resumes a session (the REPL, `-p`, `--resume`, an attached one);
+  - `chi --thinking LEVEL` on a run that starts or resumes a session (plain `chi`, `-p`, `--resume`, an attached one);
   - `chi send --new --thinking LEVEL`;
   - the web's ⚙ panel in the session bar (its Thinking row), and the start page's ⚙ panel (`POST /api/sessions` takes `"thinking": "low"`;
     anything that isn't a level answers `400 invalid_thinking`).
@@ -849,15 +844,15 @@ first: an unknown host or a bad alias is an error at once, not a question.
   a full-prefix change also says preserved thinking in replies is dropped from then on.
 - `Nothing changed yet: send /thinking low --yes to apply.` names the line that applies it.
 - `--yes` (or `-y`, anywhere after the command) applies it at once.
-- The terminal (the REPL and an attached TUI) puts the `--yes` line in the next input: Enter applies it.
+- The attached terminal puts the `--yes` line in the next input: Enter applies it.
 - The web's reply bubble has an **Apply (restarts the cache)** button. The session bar's ⚙ panel is already an
   explicit choice: a tap sends the `--yes` line, and its note says what a change costs. Command bubbles are page-only, so
   the button is gone after a reload.
 - Only a person at a web tab or a chi TUI is asked. `chi send ID "/thinking low"`,
-  `chi -p "/thinking low" --non-interactive`, lines piped into the REPL, a delegate, a plugin and a card's action
+  `chi -p "/thinking low" --non-interactive`, a delegate, a plugin and a card's action
   apply directly, since nobody would see the question; so do the start flags (`chi --thinking`, `--model` and
   `--llm-context` on a resumed or attached session send `/thinking LEVEL --yes`, `/model NAME --yes` and
-  `/llm-context … --yes`). A plain `chi -p` opens the REPL, which asks.
+  `/llm-context … --yes`).
 
 ## Llama HTTP Timeouts
 
@@ -1107,7 +1102,7 @@ retry:
 `retry.empty_answer` is a different thing: the request worked, but the model's answer had no visible text and no
 tool calls (thinking only, or nothing; a thinking loop cut by the provider's output cap looks like this). chi then
 asks again in the same turn with a hidden note ("your last reply had no visible answer…"), at `temperature: 0.6`
-unless `sampling:` sets one; the REPL prints `↻ empty answer, asking again (1/1)` and the web shows it as a row of
+unless `sampling:` sets one; the terminal prints `↻ empty answer, asking again (1/1)` and the web shows it as a row of
 the step. `retry.empty_answer` (default `1`, at most `3`, env `SAMAGOTCHI_RETRY_EMPTY_ANSWER`, no CLI flag) is how
 many times per turn; `0` ends the turn at the empty answer as before. An answer cut because the context is full
 (90 % or more) is not retried. When the retries run out the turn ends with no answer: every UI shows one muted line,
@@ -1209,8 +1204,8 @@ The turn's prompt and its completed tool calls stay in the session.
 
 ## Debug Log File
 
-Every `chi` process (the REPL, the attached terminal, the background
-workers, `chi web`) appends tagged records to one log file, so you can see
+Every `chi` process (the attached terminal, a `--non-interactive` one-shot,
+the background workers, `chi web`) appends tagged records to one log file, so you can see
 what happened in a session, what went over the wire and why something
 failed, without `--verbose`.
 
@@ -1248,9 +1243,10 @@ One record is one line, plus indented payload lines at debug level:
   space, quote or `=` is a JSON string, so a record never spans lines;
   control characters (terminal colours in tool output) are escaped.
 - Tags: `turn` (a session's event trail), `http` (model requests),
-  `worker`, `bridge`, `web`, `attached`, `repl`, `idle`, `recap`, `hooks`,
+  `worker`, `bridge`, `web`, `attached`, `idle`, `recap`, `hooks`,
   `plugins`, `guardrails`, `config`, `memory`, `model` (debug dumps), `context` (attached context fetches),
-  `broadcast` (chi broadcast's triage).
+  `broadcast` (chi broadcast's triage), `toolkit`, `system_one`, `prompt` (a system prompt section left out
+  after an error).
 - The format is parsed by `Samagotchi::LogLine` (`parse`, `each_record`);
   keep tools that read it on that parser.
 
@@ -1259,7 +1255,9 @@ What each level adds:
 - `error`: crashes (a worker, a bridge connection, the idle scheduler, a
   recap) with the first 20 backtrace frames; failed model requests.
 - `warn`: retries (429, 5xx, network), failed turns, hook and guardrail
-  problems, config warnings. Warnings `chi` prints on stderr are logged too,
+  problems, config warnings, and a fallback after an error (a prompt section or a
+  Bridge reply chi left out, `Degrade`): once per process for each kind, later ones
+  at `debug`. Warnings `chi` prints on stderr are logged too,
   with the same text as `msg=`; a worker's (its stderr goes nowhere) now
   only reach the file.
 - `info`: turns, generations and tool calls with sizes and times (never the
@@ -1270,8 +1268,12 @@ What each level adds:
   and results, context status), probes and model lists, every web API and
   bridge request.
 
-`-v`/`--verbose` (the plain REPL only) logs at `debug` and prints every
-record to stderr as well.
+`-v`/`--verbose` logs at `debug`, in this chi and in a worker it starts
+(a worker that was already running keeps its own level, and a one-line note
+says so: one `chi web` started may log to another file). The attached
+terminal shows the session's records (by `sid`) dim, above the prompt, as
+they come; a `--non-interactive` one-shot prints every record to stderr
+as well.
 
 ### Rotation and secrets
 
@@ -1476,8 +1478,8 @@ work tree top when inside it, else with `~`.
   every request`). The files are saved in the session (`appended_prompt_files`),
   so a respawned worker builds the same prompt, and a fork or a continue keeps
   them; a delegate child doesn't. With `--attach` or `--resume` the flag is
-  ignored with one line, as `--memory` is; a REPL `--resume` (`--no-shared`)
-  adds them for that run only.
+  ignored with one line, as `--memory` is; a `--resume ID --non-interactive`
+  one-shot adds them for that run only.
 - The files' text is read at each prompt build, as AGENTS.md's is: an edit is
   picked up by a new process or a rebuild (`/model`). `/stats` lists the files
   in the prompt on its `prompt files:` line.
@@ -2215,7 +2217,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `recap.timeout` | `30` | yes | Seconds a recap request may take. |
 | `recap.min_user_turns` | `2` | yes | Prompts a session needs before it gets a recap. |
 | `recap.sentences` | `2-4` | yes | Recap length, `N` or `N-M` (1–10). Per session too: `--set recap.sentences=3`. |
-| `broadcast.active_hours` | `8` | | `chi broadcast` reaches a session a worker or a chi REPL runs, or whose last turn ended within this many hours. See [Broadcast](broadcast.md). |
+| `broadcast.active_hours` | `8` | | `chi broadcast` reaches a session a worker or a one-turn `--non-interactive` run has, or whose last turn ended within this many hours. See [Broadcast](broadcast.md). |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | | A Ruby regex for ticket ids; one in the note and in a session's branch (any case) or prompts delivers the broadcast there. See [Broadcast](broadcast.md). |
 | `broadcast.triage_model` | recap's | | The model that judges a recipient no tag matched (a model ref, as `recap.model`); unset: the recap's model, else `default.model`. A ~9B dense instruct model or larger; 4B-class ones say yes to nearly everything. See [Broadcast](broadcast.md#triage). |
 | `broadcast.triage_host_ref` | none | | A `hosts:` name for the triage model. |
@@ -2223,7 +2225,6 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `broadcast.triage_parallel` | `4` | | Triage requests at a time. |
 | `broadcast.triage_deadline` | `20` | | Seconds triage may take in all; a recipient not judged by then gets the note unchecked. |
 | `broadcast.threshold` | `0.5` | | The P(yes) a recipient needs, when the triage host gives logprobs; a plain yes or no is 1 or 0. |
-| `session.shared` | `true` | | Plain `chi` runs its session in a worker and attaches; `--no-shared` per run. |
 | `session.idle_exit_minutes` | `30` | yes | An unused worker exits after this; `0` = never. |
 | `session.project_env` | `mise` | | The commands a session's worker runs follow its project: `mise` runs them in the session folder's `mise env`, read once at worker start (`chi sessions restart` picks up a mise.toml edit); `off` doesn't ask mise: the tools keep the env of whoever started the worker (with a chi home, the home's `chi` still goes first on their PATH). See [Project env](sessions.md#project-env). |
 | `session.carry_last_answer` | `true` | | A continue's carry note holds the previous session's last answer after its recap; `false`: the recap only. See [Session chains](sessions.md#session-chains). |
@@ -2255,7 +2256,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `log.file` | state dir | yes | See "Debug Log File". |
 | `log.disable` | `false` | yes | No file logging. |
 | `log.level` | `info` | yes | `debug`, `info`, `warn`, `error`. |
-| `status.line` | `on` | yes | The status row under the prompt (the REPL's and attached mode's), `on` or `off`. |
+| `status.line` | `on` | yes | The status row under the attached terminal's prompt, `on` or `off`. |
 | `context.status` | `true` | yes | Context-usage telemetry for the model. See [context telemetry](internals/context-telemetry.md). |
 | `context.window_tokens` | server's, else 256000 | yes | Context window when the server doesn't report one. `models.<key>.window_tokens` and `hosts.<name>.window_tokens` come first; see "The context window". |
 | `models.<key>.window_tokens`, `hosts.<name>.window_tokens` | none | | A model's or host's context window when the server and its model list report none. |

data/docs/context.md

@@ -617,13 +617,13 @@ show the answer as it is.
   after a push links may be a few lines off until the next read. Without
   `gh` or its login, nothing is linked.
 - **Where it reads**: only in a session worker (the web, an attached chi),
-  whose answers the web shows while the session runs. The REPL and
-  `chi -p` read nothing (no `gh api` calls), so their answers have no links,
+  whose answers the web shows while the session runs. A
+  `chi -p … --non-interactive` run reads nothing (no `gh api` calls), so its answers have no links,
   in the web too; a scratch session never reads. The PR itself is still
   attached and its context still reaches the model everywhere.
 
 `line_links:` takes `false` (off), `true` (the default: a worker only) or
-`always` (the REPL and `chi -p` read too, so their answers are linked when
+`always` (a `chi -p … --non-interactive` run reads too, so its answers are linked when
 you open the session in the web later):
 
 ```yaml

data/docs/desktop.md

@@ -80,7 +80,7 @@ models and aliases (from [`chi models`](cli.md#listing-the-models)), at most nin
 The chooser needs a chi with `chi models`: an older helper works with a newer chi, not the reverse
 (`chi desktop upgrade` after updating chi).
 
-A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
+A session a one-turn `chi -p … --non-interactive` run has isn't listed: it takes no notes or messages.
 
 ## Images