samagotchi 0.153.0 → 0.154.0

data/docs/guardrails.md

@@ -23,7 +23,7 @@ The UI shows the tool line first, then the approval under it.
 
 ## Ask
 
-The REPL, the attached TUI and the web show what would run, where and why:
+The attached TUI and the web show what would run, where and why:
 
 ```
 Approve tool call?
@@ -65,8 +65,7 @@ card comes back through `ApprovalFacts.from_h` (string or symbol keys, missing f
 
 Who answers:
 
-- REPL (`chi --no-shared`, with or without `-p`): at the `? ` prompt.
-- A shared session's worker (plain `chi` and `chi -p …` while `session.shared` is on, the default): any attached TUI or web page. With none attached,
+- A session's worker (plain `chi`, `chi -p …`, the web): any attached TUI or web page. With none attached,
   the approval waits (in the session file) and shows on attach.
 - `-p … --non-interactive`: nobody; the call is denied ("No one to approve it
   (non-interactive run)").
@@ -134,7 +133,7 @@ others come back to the parent's model with the block below. A dismissal
 always passes (the hook decides what no answer means): the strategy is a
 convention for an honest parent, not a barrier. This section is
 the path for other agents, and for a chi parent that can't host the relay (a
-`--no-shared` REPL, `--non-interactive`): there the model gets the question
+`--non-interactive` one-shot): there the model gets the question
 block and the rules below. With the relay, the same rules still hold for a
 parent model that answers its own relay card (a piped or marked `chi --attach`
 on the parent): that answer is a parent agent's, checked by the parent and
@@ -197,10 +196,10 @@ value that isn't a level reads as `hard`.
 config.yml's; `/parent-answers LEVEL` sets the session's own, `/parent-answers
 default` drops it (config.yml's applies). Anyone may tighten it, a parent too
 (`chi send ID -m "/parent-answers hard"`). Loosening it (toward `soft`, or
-`default`) is yours alone: the line must come from you at the REPL, an attached
+`default`) is yours alone: the line must come from you at an attached
 terminal or the web composer. chi refuses it (`loosening parent_answers is the
 user's: …`) from `chi send` (a parent's or yours: the worker can't tell them
-apart), from a piped or marked `chi --attach` or REPL, from `chi -p
+apart), from a piped or marked `chi --attach`, from `chi -p
 --non-interactive`, from a delegate's follow-up and from a plugin; `chi answer`
 has no command route. `--parent-answers` on `--attach`/`--resume` is ignored,
 never sent as the command.
@@ -277,7 +276,7 @@ no running turn, pending question or approval, queued prompt, or running
 background task; when one exists, stop it explicitly and then send a prompt.
 
 A parent may also type its answer into chi itself: a piped `chi --attach ID`
-or `printf '2\n' | chi --no-shared -p …`. So chi treats an answer as a
+or `printf '2\n' | chi -p …`. So chi treats an answer as a
 parent's, held to the same setting, when its input isn't a terminal or an
 agent marker is set: `CLAUDECODE` (Claude Code), `AI_AGENT`, `CODEX_THREAD_ID`
 (Codex CLI), or `SAMAGOTCHI_PARENT_SESSION`,
@@ -1327,9 +1326,8 @@ allows), and how many got no judgment. `--threshold` overrides
 for this run; `--dry-run` judges and prints without writing a line. Without a
 client (`mode: off`, or no `host`) it exits 2 saying what to set.
 
-Two limits on what the replay can see: `CardStore` keeps only the last 20
-questions per session, and a `--no-shared` REPL session never writes a
-`cards.json` at all, so its asks are not replayable.
+A limit on what the replay can see: `CardStore` keeps only the last 20
+questions per session, so older asks are not replayable.
 
 ## The guardrails bundle
 

data/docs/hooks.md

@@ -97,14 +97,14 @@ class Watchful
   def call(event)
     case event[:type]
     when :after_generation
-      # One line in the REPL, the attached TUI and the web ("<bundle>> text",
+      # One line in the attached TUI and the web ("<bundle>> text",
       # or "hook> text" for a config hook); level: :warn colours it.
       # fallback_for: :display marks a line a UI that renders the answer's
       # display may leave out (below).
       event[:notify].call("the model repeated itself", level: :warn)
     when :before_tool_call
-      # A single-select question through the question flow (REPL, attached
-      # TUI, web); returns {selected: [...], freeform:, selected_indices:}
+      # A single-select question through the question flow (the attached
+      # TUI, the web); returns {selected: [...], freeform:, selected_indices:}
       # or nil when there is no one to ask (--non-interactive), the
       # question was dismissed, or the options (or effects) were invalid.
       # effects: says what an option does for a parent agent's answer (see
@@ -156,7 +156,7 @@ that a UI that already shows it can leave the line out. The main value is
 links), for a UI that doesn't render that display. The hook never names a UI;
 each decides by what it renders. The web with markdown on (`web.markdown` and
 the commonmarker gem) leaves such a line out, live and after a reload; with
-markdown off it shows, as it does in the REPL, the attached TUI and
+markdown off it shows, as it does in the attached TUI and
 `chi -p`, which print the answer as text (in the web its http(s) URLs are
 links, as in any hook's notice line). The log keeps the line with
 `fallback_for=display`. `:editor` marks a line that names a file the viewer
@@ -304,8 +304,8 @@ end
   kept), on a live turn and after a reload. Its copy button copies the
   display text. The page learns about it from an `answer_display` event
   that comes after `turn_completed` (the hooks run after the turn ended).
-- **Terminals** (the REPL, the attached TUI) have printed the answer by then
-  and do not change it; use `event[:notify]` for something they should show.
+- **The terminal** (the attached TUI, a `--non-interactive` one-shot) has printed the answer by then
+  and does not change it; use `event[:notify]` for something it should show.
 
 A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:present].call { … } }`.
 
@@ -569,7 +569,7 @@ the voter's own (a guard that wants the model to retry a corrected call:
 `Retry with "…".`).
 
 `event[:context]` is `{cwd:, repo_root:, branch:, session_id:, interface:, origin:}`
-(`interface` is `:repl`, `:worker` or `:non_interactive`). `event[:targets]` is
+(`interface` is `:worker` or `:non_interactive`). `event[:targets]` is
 what the call acts on, resolved as the tools resolve it:
 `{command:, paths:, cwd:, repo_root:, outside_repo:, git_dirs:}`. `outside_repo`
 is measured from the session's repo, not the call's `cwd:`; `git_dirs` lists where
@@ -855,8 +855,8 @@ qualified ref:
 
 **Where `{repo}` and `{host}` come from.** Without a named group that took
 part, they come from `git remote get-url <remote>` run in the session's
-working directory (the worker's; the in-process REPL's is the terminal's
-current directory). `remote:` picks the remote, default `origin` — a fork
+working directory (the worker's; a `--non-interactive` one-shot's is the
+terminal's current directory). `remote:` picks the remote, default `origin` — a fork
 sets `remote: upstream`. Git applies `insteadOf` rewrites and includes, and a
 worktree reports its main repo's remote. The URL forms understood are
 `https://`, `http://`, `ssh://`, `git://` (credentials and port dropped) and

data/docs/internals/attached-context.md

@@ -125,11 +125,11 @@ name (or whose hint is its URL) is attached, *declined* while the declined marke
   "PR", branch names ≥ 6 chars with `/ - _`, exact URLs, fenced code blanked). Only `OwnerPrompt` texts count
   (`owner_texts`), so a participant's message, a steer, a note or a reminder never attaches anything; a review
   session skips all of it.
-- **Where it runs.** `before_turn` (from `Worker#run_prompt` before the absorb, and the REPL's turn start): attach
+- **Where it runs.** `before_turn` (from `Worker#run_prompt` before the absorb, and a `--non-interactive` one-shot's turn start, `TerminalUI`): attach
   each proposed candidate the owner's prompts so far mention (`attach` writes a session `Source` through
   `source_for`: a URL resolves through `ContextProviders`, else the candidate's own `cmd`), then `first_fetch` them
   together within `FIRST_FETCH_SECONDS` (10) so the note lands in this turn; cut short, the fetch records nothing and
-  the poller tries soon. `after_propose` does the same for a late proposal. The REPL has no absorber running, so
+  the poller tries soon. `after_propose` does the same for a late proposal. A one-shot has no absorber running, so
   `deliver_notes` runs one.
 - Forks and continues take no candidates.
 

data/docs/internals/background-tasks.md

@@ -36,8 +36,7 @@ Behavior:
   ends the wait when a person's message waits for the turn's next step (`Engine#input_waiting?`, run_turn's
   `input_waiting:` probe through the kernel's `PeerView`): in a worker an input file that the next boundary merges
   from the user, `chi send` or a delegating parent (`SessionInbox.steer_waiting?`; never a queued, image or
-  participant's one, never a plugin's steer or a child's report, never during a participant's turn), in the REPL
-  (`--no-shared`) a line in its steering queue. The probe only peeks: the drain still merges the message at the
+  participant's one, never a plugin's steer or a child's report, never during a participant's turn). The probe only peeks: the drain still merges the message at the
   next boundary. The result says `note: a message from the user is waiting; the task is STILL RUNNING.`, how to wait
   again or stop it (`TaskWait::MESSAGE_WAITING_NOTE`), and `waited: Ns`; the task keeps running and stays watched
   (below). A task that finished meanwhile gives its finished result, as after a Stop. A `chi -p` turn has no probe. The same probe ends a blocking `delegate_result` (and `delegate`'s wait) early; see [Sessions: Delegating](../sessions.md).
@@ -51,7 +50,7 @@ Behavior:
 
 A task the model leaves running (it ends its turn: "I'll check when it's finished") is reported when it ends, so the result doesn't wait for the user's next message. `session.task_wakes` (env `SAMAGOTCHI_SESSION_TASK_WAKES`): `wake` (default), `queue` or `off` (no watch, as before).
 
-- **The watch** (`TaskWatch`, `task_watch.rb`) is the Worker's (`WorkerTaskWakes`, `worker_task_wakes.rb`, which writes the notes; the Worker runs the wake turn), in memory: the in-process REPL (`--no-shared`) has none, and a crash loses it (those tasks behave as before). The Worker's Engine observer feeds it the raw `:tool_call_completed` events, the input `Bridge#own_task_ids` reads too. A `task_create` result and an `execute` hand-over add the task (`TaskRuntime.created_id`: a `task_id:` the command printed doesn't count), the hand-over's limit kept for the note. What shows the model the end removes it: a `task_wait` with a final status, or with `wait_result: pattern_matched` (the model chose its own "done" marker); a `task_get` with a final status; any `task_stop`. `task_list` and a `read` of `output.log` don't: a model that read the log still gets the wake once. Tasks a tool starts inside an anytime command (`/btw` and the like) reach the same observer, so they are watched too.
+- **The watch** (`TaskWatch`, `task_watch.rb`) is the Worker's (`WorkerTaskWakes`, `worker_task_wakes.rb`, which writes the notes; the Worker runs the wake turn), in memory: a `--non-interactive` one-shot has none, and a crash loses it (those tasks behave as before). The Worker's Engine observer feeds it the raw `:tool_call_completed` events, the input `Bridge#own_task_ids` reads too. A `task_create` result and an `execute` hand-over add the task (`TaskRuntime.created_id`: a `task_id:` the command printed doesn't count), the hand-over's limit kept for the note. What shows the model the end removes it: a `task_wait` with a final status, or with `wait_result: pattern_matched` (the model chose its own "done" marker); a `task_get` with a final status; any `task_stop`. `task_list` and a `read` of `output.log` don't: a model that read the log still gets the wake once. Tasks a tool starts inside an anytime command (`/btw` and the like) reach the same observer, so they are watched too.
 - **The idle tick**: with something watched, each idle pass (after delegate reports, before due reminders) refreshes the watched records (`TaskRuntime.get_record`, one `ps` per running task) and takes the finished ones, keeping only the ids the conversation still holds (`TaskRuntime.created_ids_in`: a `!rollback` or a restored turn may have dropped the result that started one; an LLM context strategy can't, since its stale and forget stubs are drawn in the request, never written over the saved result). A note that can't be written puts its task back for the next pass. An empty watch costs nothing. A task that finishes during a turn and is still unseen when the turn ends wakes on the next idle pass. One the user stopped with the web's stop-task button is dropped without a note.
 - **The note** is a context note under its own header (`ContextNote::TASK_HEADER`; `TaskFinishNote`), `note_id: task-<id>`, `source: task <id8>`:
 
@@ -70,6 +69,6 @@ A task the model leaves running (it ends its turn: "I'll check when it's finishe
 - **A plain note instead** (the same text without the last two lines, no turn start), written at once, with `queue`, the budget spent (the UIs hear `N finished background tasks noted; the model reads them with your next message` once per human input, the flag shared with the other wakes), wakes paused, a continue offer waiting, input queued, an exit asked for, or a **note-only** task: one started or waited on in a turn the user stopped (reasons `user`, `manual`, `ctrl_c`), since a wake telling the model to carry on would undo that Stop. A prompt's turn takes the finished ones as plain notes first.
 - **Failure**: a wake turn that fails and kept nothing, or is stopped and restored, turns its note back into the plain one (`WorkerInbound#unmark_wake`, as for a context wake) and pauses wakes until the user writes.
 - **Idle exit**: with `wake`, a watched task holds the worker's idle exit (`WorkerIdleExit`'s `:background_tasks`) until its wake is taken: while it runs, and once it finished until the next idle pass takes it (`TaskWatch#holding`, in memory, no `ps`), so one that ends between the pass's look and the exit's check still wakes the session. A still-running one holds `/exit` too (`TaskWatch#running`, read once per request by `WorkerIdleExit#request_hold`; the 409 lists the tasks, `{id, command, age_seconds}`, with a `hint` on stopping them, and the attached terminal names them and says to use the web's stop-task button or ask for `task_stop`), as reminders do. When the only holds are ones the user can stop, the 409 carries `holds` too and the terminal asks whether to stop them all (`HoldStop`, which stops these tasks the same way `task_stop` does). A note-only task holds neither (no wake would come for it), nor does one whose note, or the look for it (the conversation's task ids unreadable), failed 3 times (`TaskWatch::MAX_FAILURES`: it is still tried at each look, but can't keep the worker up for good). With `queue` nothing holds: nothing would wake for the end, so keeping the worker up isn't worth it. As the worker leaves (any exit but a stop, a signal or an `/exit --delete`), the tasks that finished since the last look are written as plain notes; a task that ends after the worker left gets no note (the model sees its end at its next look, as before). A forgotten dev server keeps the worker up until it is stopped; a crash of that server wakes the session.
-- **The tool descriptions**: a worker's `execute` and `task_create` say "if you end your turn before it finishes, chi tells you when it does" (left out under `off` and in the REPL), fixed when the worker builds its Engine.
+- **The tool descriptions**: a worker's `execute` and `task_create` say "if you end your turn before it finishes, chi tells you when it does" (left out under `off` and in a `--non-interactive` one-shot), fixed when the worker builds its Engine.
 
 Work that needs a model, not a shell command, goes to a child chi session instead: `delegate` / `delegate_result` have the same shape (start, then wait) and return only the child's final reply; see [Sessions: Delegating](../sessions.md#delegating).

data/docs/internals/block-renderers.md

@@ -30,6 +30,10 @@ model. The TUI is untouched: it shows a fence as source.
    clone arrives with both. On failure the `<pre>` stays, marked `data-block-failed`, with one muted line: an attribute CSS
    shows, never markup, and not in the bubble's `textContent`, which the page's dedupe and an annotation read (`copy.js`'s rule). CSS content can't be selected, so a click on the line copies its words.
    The toggle has an icon and an `aria-label`, no text (`copy.js`'s rule). A jump into the source shows it (`revealInHistory`).
+   For a screen reader: the hidden `<pre>` isn't read, so the `<img>`'s alt names the toggle that shows it ("mermaid
+   diagram, its source under the Show the source button"). The natural size, a click on the picture, is also a
+   `.block-zoom` button (icon, `aria-label`, `aria-pressed`) for the keyboard: before the toggle, shown on keyboard focus
+   only, and taking no pointer while hidden, so the mouse's view is as it was.
 6. Cache: a `Map` on `lang + theme + source`, about 200 entries, holding the `data:` URL; a later `bubble.innerHTML` wipes the
    figure and the observer redraws in the same pass. No `crypto.subtle`: it's undefined on a plain-http LAN address. A system
    theme change redraws through the figure (a hidden `<pre>` never intersects).

data/docs/internals/bridge.md

@@ -98,11 +98,11 @@ the "asking again" and steer-cut rows, ✂ rows and questions (with how they wer
   `chi guardrails replay` reads. A plain upgrade doesn't reach this: a worker already running seeded before and keeps its own version 1
   file, and a spawn runs the newest chi installed (`SessionManager.worker_command`), unless that activation raises LoadError: the boot
   line then falls back to the spawner's or the home's pinned version, which can be older. Otherwise it takes an older process starting
-  on a session a newer one wrote: a downgrade, a chi home whose newest chi is older (`home_older_than_spawner`), or a REPL or `bin/chi`
+  on a session a newer one wrote: a downgrade, a chi home whose newest chi is older (`home_older_than_spawner`), or a `bin/chi`
   from an older gem or checkout on the same state dir. Nothing on this side stops
   it: an older chi can't be changed, and having it read the file would mean writing fake `turns` counters into every file.
 - **A killed turn needs nothing special.** `TurnCheckpoint` keeps a running turn's prompt in the session file, with its id from
-  the start (`Worker#run_engine_turn` settles it first), so it counts as any opening. A REPL keeps no running turn in the
+  the start (`Worker#run_engine_turn` settles it first), so it counts as any opening. A `--non-interactive` one-shot keeps no running turn in the
   session, so a kill takes the prompt along and there's nothing to count.
 
 ## SSEWriter
@@ -401,7 +401,7 @@ for client discovery, with the Bridge's secret (see above).
 **Worker link.** Every client asks `WorkerLink` (`worker_link.rb`) whether a session's worker can be reached, never
 reading `bridge.json` or probing a port itself: `WorkerLink.resolve(session_dir, unlink:, owner:)` answers a typed
 outcome. The rule is the owner lock plus the sidecar's `pid`; there is no port probe (a port can be reused by another
-session's Bridge, a free lock is the kernel's proof the worker died). In order: no lock holder, or a chi REPL's: a
+session's Bridge, a free lock is the kernel's proof the worker died). In order: no lock holder, or a one-shot's (kind `"tui"`): a
 sidecar is `Stale(:lock_free)` (removed with `unlink: true`, only if it is still the file that was read and the lock,
 read again just before, is still free: a worker that took it meanwhile is resolved as that worker), else `None`;
 a holder with no kind yet: `Starting`; a leaving worker: `Leaving` (marked before its Bridge stops, on every way out:

data/docs/internals/context-telemetry.md

@@ -55,7 +55,7 @@ session's first counted turn. A
 hook's switch (`before_turn`) sends nothing: its turn's first request counts on the new model anyway.
 
 A process that loads the session on another model than its last turn ran on (`Engine#session=`:
-`SessionMetrics#last_model_ref` differs from `effective_model_ref`; a `--resume`'d REPL with `--model`, a worker woken
+`SessionMetrics#last_model_ref` differs from `effective_model_ref`; a `--resume`'d one-shot with `--model`, a worker woken
 after a `/model` with no turn since) drops the old window (`forget_model_reports!`) and calls
 `announce_switched_context!(configured_only: true)`: the configured window only
 (`EffectiveModel#configured_context_window`, no `/props` GET or model list, since a worker runs it before its Bridge

data/docs/internals/engine.md

@@ -1,8 +1,8 @@
 # Engine: the core agent loop
 
 The Engine (`lib/samagotchi/engine.rb`) runs a session's turns. It owns the turn lifecycle, the hooks and
-plugins, and the model↔tool cycle, and it reports what happens as events, so every UI (the REPL, a worker
-behind the web and the attached TUI, one-shot CLI runs) runs turns the same way without the Engine knowing how
+plugins, and the model↔tool cycle, and it reports what happens as events, so every UI (a worker behind the web
+and the attached TUI, a `--non-interactive` one-shot) runs turns the same way without the Engine knowing how
 they render.
 
 ```
@@ -120,7 +120,7 @@ StandardError in run_turn:
      # error_kind, retryable, host and summary.
   → re-raised
 
-Interrupt (Ctrl-C; the REPL only: a worker traps INT, see the signal row below):
+Interrupt (Ctrl-C; a one-shot only: a worker traps INT, see the signal row below):
   → if turn.ended: re-raised only
   → turn.controller.cancel!(:ctrl_c)
   → end_turn(turn, "canceled"): ctrl_c_messages keeps the loop's conversation, else turn.messages
@@ -173,6 +173,12 @@ Stopped before the model was asked (prepare_turn returned false):
   → LLM::ModelResult(text: "", canceled: true, cancellation_reason: reason)
 ```
 
+**Degrading.** Work that has a fallback when it fails (a prompt section left out, an empty list from the Bridge) runs
+in `Degrade.call(area, event, fallback:, rescue:) { … }` (`degrade.rb`): same rescue class and fallback as a bare rescue,
+plus one WARN in the debug log per process for each `[area, event]` (DEBUG after; nothing on stderr). A bare `rescue`
+whose body is only a literal (`nil`, `false`, `[]`, `{}`, `""`, `0`) is flagged in lib by the `Samagotchi/SilentRescue`
+cop; a silence that is right (a client gone, a routine probe, Log's own internals) carries `# degrade-ok: why`.
+
 ## The model↔tool loop
 
 The Engine does not talk to models directly. `Engine#backend` picks the loop the effective model's host speaks:
@@ -426,7 +432,7 @@ what a resolve gives, all without a `/model`. Frozen, so any thread may hold one
 - Never resolved (they hold on a broken resolve): `effective_model_ref`, `bare_model_name`,
   `guardrail_model_name`, `sync_model_key!`, `served_model(probe: false)` (`HostRegistry#model_ref`/`#bare_name`).
 - Readers on other threads: the Bridge (`/state`, `/stats`, the SSE reset, a steer's cut wait), the worker's
-  command thread, the recap thread and plugin threads (`session_model_recap_target`), the REPL.
+  command thread, the recap thread and plugin threads (`session_model_recap_target`).
 - `ModelChoice` (`ModelBinding#choice`) holds the name and the typed name as one value, so a reader on another
   thread never pairs one model's name with another's typed name.
 - `EffectiveModel.of_session` builds a saved session's (no worker): `Web::App`, `LLMContextStrategy.for_session`.
@@ -517,7 +523,7 @@ drain hands the message to the model at a boundary, or until the turn ends (`Ste
 ### The turn's sink (`on_event`) and the observers
 
 `Engine#emit_event` (`EventFanout#emit_event`, `event_fanout.rb`, which also builds the loops' stream handler and
-emits the working set) sends each turn event to the turn's sink (`on_event`, the REPL's renderer) and then to the
+emits the working set) sends each turn event to the turn's sink (`on_event`, a one-shot's renderer) and then to the
 persistent observers (`Engine#subscribe`), which get a copy with a monotonic `event_seq`. The observers are the
 metrics, the debug log, the thinking tails, and in a worker the Bridge, which streams to the web and the attached
 TUI. Errors in the sink or an observer are caught; they never break the turn.
@@ -777,7 +783,7 @@ The verdict is one of:
 - **allow**: the call runs.
 - **deny**: that call's output is replaced with denial text; the rest of the batch still runs.
 - **ask**: `Gate#settle_ask` first looks for a stored approval that covers the call. Otherwise
-  `Engine#request_approval` asks the user through the question flow (REPL, attached TUI, web). A
+  `Engine#request_approval` asks the user through the question flow (attached TUI, web). A
   `--non-interactive` run has no one to ask, so the call is denied. An approval wider than this once is stored.
 
 docs/guardrails.md covers the rules and the approval scopes.
@@ -870,7 +876,27 @@ Paths are under `lib/samagotchi/`.
 
 | File | Role |
 |---|---|
-| `engine.rb` | Engine: turn lifecycle, event emission, plugins, model switching |
+| `engine.rb` | Engine: the wiring (`initialize`, the `build_*` methods, the kernel), the turn skeleton (`run_turn`, `begin_turn`, `prepare_turn`'s ordered steps, `generate`, `end_turn`) and `shutdown`; the rest is in its parts, below |
+| `engine/steering.rb` | `Engine::SteeringPart`: steering the running turn (or the next), the drains, the cut, the activity clock, the cancel |
+| `engine/side_requests.rb` | `Engine::SideRequestsPart`: ctx.ask_model's and Check this's side requests, their side usage, System 1's recording |
+| `engine/recap.rb` | `Engine::RecapPart`: the idle recap job and `/recap`, the idle scheduler's start and stop |
+| `engine/models.rb` | `Engine::ModelsPart`: the model's names, identity and notes, `/model`'s switch, the profile, the loop it runs on |
+| `engine/model_settings.rb` | `Engine::ModelSettingsPart`: the session's model settings (SessionModelSettings) and the snapshots (EngineSnapshots), forwarded |
+| `engine/events.rb` | `Engine::EventsPart`: observers, `#announce`, the event lock, held announcements, load events, the emit helpers |
+| `engine/cards.rb` | `Engine::CardsPart`: `#show_card`, anytime commands and their threads |
+| `engine/objectives.rb` | `Engine::ObjectivesPart`: the objectives' view, proposals and audit |
+| `engine/messages.rb` | `Engine::MessagesPart`: the session messages API (out-of-turn edits, checkpoints, the live conversation) |
+| `engine/plugins.rb` | `Engine::PluginsPart`: loading plugins, init tasks and staged tools, `Plugin::Host` |
+| `engine/hooks.rb` | `Engine::HooksPart`: turn-scoped hooks, the hook runtime (HookRoutes, forwarded), reminders |
+| `engine/guardrails.rb` | `Engine::GuardrailsPart`: the guardrails' readers and the first turn's load warnings |
+| `engine/participants.rb` | `Engine::ParticipantsPart`: the turn's author, a pair turn's stop, the participants line |
+| `engine/session.rb` | `Engine::SessionPart`: `#session=`, the state dir, the relay's view, the system prompt and its memory names |
+| `engine/verify.rb` | `Engine::VerifyPart`: Verify and Revise anchors at a turn's end, the verdict |
+| `engine/questions.rb` | `Engine::QuestionsPart`: ask-user-question (QuestionDesk, forwarded) |
+| `engine/toolkit.rb` | `Engine::ToolkitPart`: the toolkit, `ctx.load_tools`, System 1's toolkit suggestion |
+| `engine/context_judge.rb` | `Engine::ContextJudgePart`: the attached-context candidate judge and its cards |
+| `engine/turn_helpers.rb` | `Engine::TurnHelpersPart`: a turn's settings, images, model ref, used memories, the turn-end warm-up |
+| `engine/turn_end.rb` | `Engine::TurnEndPart`: the normal ending and after-turn hooks, release, what an ending keeps, last_turn, the answer's display |
 | `event_fanout.rb` | `EventFanout`: how an event reaches the turn's sink and the observers (`emit_event`), the loops' stream handler, the working set's emit and dedupe; the Engine forwards |
 | `engine_snapshots.rb` | `EngineSnapshots`: the UIs' read model, `session_state_snapshot` (cheap, never raises) and `stats_snapshot` (may probe `/props`); the Engine forwards |
 | `model_binding.rb` | `ModelBinding`: the model choice and the prompt profile resolved for it, under one mutex, and the overlay keys; the Engine forwards |

data/docs/internals/objectives.md

@@ -71,8 +71,8 @@ the payload, so an edit and a continue carry none: a new link starts with no las
   counts. A leading `[done]`, `[dropped]` or `[active]` is stripped, so a text can't pass for a status. Any whitespace
   collapses, Unicode line separators too, so each item stays one line of the frame.
 - It never writes session.json and runs on any thread: it only adds a file to `notes/`.
-- It is refused in a session a chi REPL owns (`--no-shared`), with the reason `chi note` gives
-  (`NoteDelivery::REPL_REFUSAL`). A show still answers there.
+- It is refused while a `--non-interactive` one-shot has the session, with the reason `chi note` gives
+  (`NoteDelivery::ONE_SHOT_REFUSAL`, in `OwnerLock::TUI_BUSY`'s words).
 - A second edit stacks on an unabsorbed first, since the current list reads the pending file.
 - `WorkerInbound#absorb_notes` adds only the newest list in a batch and deletes the others, so edits made during a
   turn cost one entry. It runs between turns: an idle edit lands at the worker's next pass (the fallback tick, or just
@@ -115,7 +115,8 @@ Bridge's `TurnAccumulator#current_messages`) leaves tool calls out. A move shows
 ## Proposals
 
 `action: propose` (`change` add, reword, done or drop; `id`; `text`; `note`, why) checks the change against the list
-(`Objectives::Proposal#refusal`) and hands it to `Engine#propose_objective`, which keeps it until the turn is over,
+(`Objectives::Proposal#refusal`: its line through `Objectives::Edit`, the edit the card's Apply runs, so the tool refuses
+what Apply would) and hands it to `Engine#propose_objective`, which keeps it until the turn is over,
 as `#context_choice`'s cards are kept. `run_turn`'s ensure shows them only for a turn that completed: a canceled or
 failed one drops them (`Engine#discard_objective_proposals`), so its Apply card never outlives a turn whose call a
 rollback has taken out of the history, and nothing carries over to the next turn. A card is between turns (no
@@ -226,7 +227,7 @@ notes said, what tools returned, and the agent's visible answers labelled `[agen
 newest 24,000 kept). Without those answers a claim about what the agent said or asked could only come back `unclear`. So the request says they settle
 what was said or asked and are never proof of work, which needs a tool's output or a person's word. That rule is words to a model, not a mechanism: a
 probe on Qwen3.8 Flash Next held it 3 of 3 (only the agent's "all pass": `unclear`), and a verdict is information only either way.
-The record never holds the agent's thinking (`own_words`: a chat entry's `thinking` and `anthropic_content` aren't read; a native
+The record never holds the agent's thinking (`AnswerText.visible`, the rule the continue note's last answer and decision-card's `/short` share: a chat entry's `thinking` and `anthropic_content` aren't read; a native
 entry's content is the raw response, so its inline thoughts, a thought cut off unclosed, and its call markup come out), the system prompt, the list's
 notes, a continue's carry note, an earlier session's answer that would read as outside news
 (`Objectives.outside_note?`, the rule the audit shares), or the objectives tool's calls, since a move isn't evidence for itself.
@@ -237,7 +238,7 @@ stays inside; the request says that what's inside is data and its instructions a
 the frame to hold; a model may still be swayed by text inside it, which is why a verdict is information only.
 
 **Its host.** The model is the session's, or `objectives.check_model`, whose host may be another one. The whole user text goes through
-`Web::ParticipantView::Redact.text`, chi's participant redaction: known key shapes and `token=`-style values become `[redacted]`, and
+`Samagotchi::Redact.text`, chi's participant redaction: known key shapes and `token=`-style values become `[redacted]`, and
 the home folder `~`. That is by pattern, so a secret of another shape still goes.
 
 **State.** `objective_checks.jsonl` beside the session: a `running` line, then one with `verdict` (confirmed, refuted, unclear,

data/docs/internals/participants.md

@@ -5,8 +5,8 @@ chi web with a link of their own. This page is the identity layer: grants, the g
 reaches, and what is written where; and their **turns**: review turns queued, read-only, limited and capped, pair
 turns that act under the owner's guardrails; and what they **see**: their page and its reads, all through one
 filter. Participants are experimental. An agent participant waits on its own turns' replies through the API. The
-code and docs say "participants", "review" and "pair", never "shared": `session.shared` already means "attached by
-default".
+code and docs say "participants", "review" and "pair", never "shared": that word means several UIs
+on one worker.
 
 Participants reach chi web on the **LAN** (`web.host: lan`), or **behind an auth proxy** with `web.public_url`
 (experimental; docs/configuration.md, "Behind an auth proxy"): there every request needs a token, this machine's too,
@@ -18,7 +18,7 @@ works on this machine only) is the participant, never the owner.
 
 ## Grants
 
-A grant (`Web::Grants`, `lib/samagotchi/web/grants.rb`) binds **one random token** to **one session**, **one
+A grant (`Grants`, `lib/samagotchi/grants.rb`) binds **one random token** to **one session**, **one
 participant** and **one role**, until it expires or is revoked.
 
 - **Token.** `chp_` + 43 URL-safe characters (32 random bytes, as the owner's `Web::Token`). The prefix lets the gate
@@ -57,7 +57,7 @@ participant** and **one role**, until it expires or is revoked.
   an invite can't keep only its own grant and lose every other digest. The owner's invite, cap, revoke and list are
   refused with one message naming the file (`Grants::Corrupt`: `chi share` exits 1, chi web answers 500 with it);
   an archive or delete still goes ahead. Fix the file, or move it aside to end every link.
-- **Exposure** (`exposure`, `Web::ParticipantExposure`; the review-composer plan's D3): what the participant learns
+- **Exposure** (`exposure`, `ParticipantExposure`; the review-composer plan's D3): what the participant learns
   of the review's usage, their review data's `viewer.usage` ([below](#what-a-participant-sees)). One level today,
   `own`, every grant's: their own spend and cap, their own queued turns and queue limit, their link's expiry, and the
   session's model; never another participant's or the owner's usage, nor the session's. `ParticipantExposure::LEVELS`
@@ -469,7 +469,7 @@ fields: a field added to an event later reaches nobody until it is named there.
   its final assistant reply (`AnswerTail`: the turn's last assistant message with text) contains the quote. Matching is case-sensitive, collapses whitespace, and strips common
   Markdown presentation (links, headings, list/blockquote prefixes, emphasis and code delimiters) from both sides;
   this matches the rendered text the page selects without treating different casing as the same claim. The quote may
-  also be in the answer as the pages show it (`Engine#verify_quote_in?`, `ParticipantView::Redact.text`: the session's
+  also be in the answer as the pages show it (`Engine#verify_quote_in?`, `Redact.text`: the session's
   folder relative, home `~`, secret shapes `[redacted]`): a participant's page has only that text, and the owner's
   page quotes it the same way (`owner_claim.js` `opts()`, `normalizeClaim`; `spec/fixtures/redact_cases.json` keeps the two
   sides alike), so a claim naming a path is taken on both. A fresh child
@@ -555,7 +555,7 @@ fields: a field added to an event later reaches nobody until it is named there.
   paste, drop or pick with one line (the image button is hidden) until participant images land. The grip's floor and
   the fold are the owner page's keys (`chi_composer_floor`, `chi_composer_collapsed`), per browser. The owner's
   participant view mounts none: its dock stays hidden.
-- **Redaction** (`ParticipantView::Redact`, on every string that goes out): secret shapes (`sk-…`, `ghp_…`,
+- **Redaction** (`Samagotchi::Redact`, `lib/samagotchi/redact.rb`, on every string that goes out): secret shapes (`sk-…`, `ghp_…`,
   `github_pat_…`, `AKIA…`, `xox…-`, `chp_…`, `AIza…`, `rk_live_…`, JWTs, Slack webhooks, private key blocks, an
   `Authorization:` header's value, any `…token` / `…api_key` / `…secret` / `…password` value, `=` or `:`, quoted or
   not, and a URL's password), the owner's web token, the session's folder (shown as relative paths) and the home
@@ -749,7 +749,7 @@ participant TUI in v1.
   participant; the status row counts who is in.
 - **Commands.** `/share`, `/participants` (`TerminalUI::ParticipantCommands`) run `ShareCommand` for the attached
   session through the link's `SessionAccess` (`AttachLink#session_access`: `Local`, or the remote's), so their words
-  and refusals are `chi share`'s, led by the command as typed. The REPL answers them with a note.
+  and refusals are `chi share`'s, led by the command as typed.
 
 ## Invariants
 

data/docs/internals/prompt-caching.md

@@ -120,7 +120,7 @@ right-hand column happens.
   groups changes the prompt key and asks `/toolkit` to confirm the cache cost once the session has history.
 - A worker's `execute` and `task_create` descriptions carry the finish wake's sentence ("if you end your turn before
   it finishes, chi tells you when it does"; `Engine.new(task_finish_notes:)`, set once as the worker builds its
-  Engine); the `--no-shared` REPL's, and a worker's under `session.task_wakes: off`, don't. A session that moves
+  Engine); a `--non-interactive` one-shot's, and a worker's under `session.task_wakes: off`, don't. A session that moves
   between the two, or whose worker restarts after `task_wakes` changed, misses the cache once.
 - On remote Claude, `LLM::PromptCache.mark` sends the system message as two text parts. The stable part carries
   breakpoint #1, so a **new session** reads it from the cache. The last non-system message carries breakpoint

data/docs/internals/remote-sessions.md

@@ -69,9 +69,9 @@ command, or a flag of a supported command is missing from both lists, or when th
 exist. **A new session command or flag fails that spec until you choose one.**
 
 `Contract::RUN` does the same for bin/chi's run flags (`RunOptions.switches`): `SUPPORTED` (`--attach`, `--resume`,
-`-p`, `--shared`, `--model`, `--thinking`, `--llm-context*`, `--toolkit`, `--tool`, `--no-tool`, `--set`,
+`-p`, `--model`, `--thinking`, `--llm-context*`, `--toolkit`, `--tool`, `--no-tool`, `--set`,
 `--parent-answers`, `--no-interrupt`, `--no-default-input`, `--dir`, `--help`, `--version`) or `LOCAL_ONLY`
-(`--no-shared`, `--non-interactive` and `--verbose`: the in-process REPL, P4-D4; `--memory`, `--mute`,
+(`--non-interactive`: one turn in this process, P4-D4; `--verbose`: this machine's debug log; `--memory`, `--mute`,
 `--append-system-prompt`: this machine's memories and files, P4-D2/D3; `chi web`'s flags; `--profile`). A config
 registry flag (`--recap-base-url` …) is this machine's config: `LOCAL_ONLY` without being listed
 (`Contract.run_status`). The contract spec fails on a run flag in neither.
@@ -152,7 +152,7 @@ the session commands*. Keep that table in step with `SessionAccessRoutes`.
 - **A remote attach.** Before the loop runs (resolve, create, wake, the feature check) every failure is
   `AttachLauncher::Error` or the command's own line, exit 1 (`BadRequest`: exit 2): the wake's 409 `owned_by_tui`
   is `OwnedByTUI` (its message is the one `chi --attach` prints here too: `AttachLauncher.connect` now uses it), its
-  409 `scratch` and 504 `worker_timeout` are `Refused` with `LaunchMode::SCRATCH_LEFTOVER` / `BRIDGE_LATE`'s words
+  409 `scratch` and 504 `worker_timeout` are `Refused` with `Session::SCRATCH_REFUSED` / `BRIDGE_LATE`'s words
   (`Remote#attach_wake`). Once the loop runs, `WebBridgeClient` turns every `RemoteFailed` into `Unreachable`
   (an `IOError`), so the loop's rescues catch it and `AttachedLoop#worker_down` prints its message as is ("could not
   send the prompt (remote studio (http://…): the token was refused …)"); the stream's end is worded by its reason
@@ -190,7 +190,7 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
 | `context`'s default session (`SAMAGOTCHI_PARENT_SESSION`, `ContextCommand#inside_session`) | client | no default: ids are required (`added_by` still reads it) |
 | A context URL's provider (`ContextProviders.resolve`) | client's bundles | server's bundles (`Remote#context_add_url`) |
 | UI-only slash commands (`SessionCommands.ui_only_entry`), `--image` ingest, note text (`SessionInbox.checked_text`), push text (`ContextSources.parse_output`) | client | client too (the server checks note and push text again) |
-| A remote attach's `--attach`/`--resume` id (`Session.resolve_id`), the leftover scratch check, the "open in a chi REPL" refusal | client (bin/chi, `AttachLauncher.connect`) | server: `Remote#resolve`, then `POST …/wake`'s 409s |
+| A remote attach's `--attach`/`--resume` id (`Session.resolve_id`), the leftover scratch check, the one-turn run's refusal (`OwnerLock::TUI_BUSY`) | client (bin/chi, `AttachLauncher.connect`) | server: `Remote#resolve`, then `POST …/wake`'s 409s |
 | A new attached session's `--toolkit`, `--set`, `--thinking`, `--llm-context*`, `--parent-answers`, `--model` | client (bin/chi) | server: `POST /api/sessions` with `idle: true` and `SetupWords`; its warnings printed as `send --new` prints them |
 | The status row's default model, the newest chi for the version line, what a parent may pick (exit 3) | client | server: the wake's `default_model`, `installed`, `parent_strategy` (the last read again from `GET …/worker` at report time) |
 | `@path` images (ingest, convert, downscale) | client, into the session's `images/` | client, into a scratch dir, then uploaded (`POST …/images`) |
@@ -213,7 +213,7 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
   (`App#principal(req)`), so a handler reads the principal and never trusts the body for it. Each `ROUTES` row names
   who may use it (its permission column, `:owner` or `:participant`; `Principal#permits?`; any other answers 403
   `not_permitted`). The owner passes every route (`local_viewer?` only hides `editor_url`). A participant, a
-  `Web::Grants` token for one session, reaches only the `:participant` rows, and another session's id is a 404
+  `Grants` token for one session, reaches only the `:participant` rows, and another session's id is a 404
   ([participants.md](participants.md)). A turn's author comes from the principal
   (`Principal#author`, nil for the owner) and rides with the turn (`SessionManager.deliver_turn(author:)` →
   `BridgeClient#post_turn` → `Bridge#handle_post_turn` → the input file, the fallback's too → the turn's `origin`);
@@ -297,7 +297,7 @@ bin/chi ── RunOptions.parse ── a remote, run flags ──> RemoteAttachC
 **chi web's routes** (tabled in [architecture.md](../architecture.md)): `POST …/wake` (`Local#wake`: the live worker
 as is, else `SessionManager.resume_session` and `WorkerLink.await`, at most `WAKE_MAX_WAIT` 10 s, the attach's
 `BRIDGE_WAIT` here, after waiting for a worker still leaving to let go of its lock, `OwnerLock.await_release`: its
-recap on leave's timeout plus 5 s; a leftover scratch session is refused in `LaunchMode::SCRATCH_LEFTOVER`'s words, a late Bridge
+recap on leave's timeout plus 5 s; a leftover scratch session is refused in `Session::SCRATCH_REFUSED`'s words, a late Bridge
 in `LaunchMode::BRIDGE_LATE`'s; a worker on a newer sidecar protocol is refused, 409 `worker_newer`, never resumed over) and `GET …/worker` (`Local#worker`: live, the stop marker, the owner, `leaving` and `leave_seconds` when its worker
 is leaving, `WorkerState#leaving?`, `stuck` for a worker that never published its Bridge, `skew` for a newer protocol; it never starts one; it also names that machine's `default_model`), both answering the worker as `{epoch, started_at, version,
 features}`; `POST …/exit` (the worker's exit, `client_id` passed on only when it is a `tui:` one), `POST …/recap`,
@@ -436,7 +436,7 @@ the closing line reads `stopped` as `unreachable`, the words it always had.
     writes the stream's GET (host, port, path, extra headers) and reads its headers, for a stream through chi web too.
   - `RunOptions.parse(argv)` is bin/chi's one run-flag parser (`RunOptions.switches` lists its flags), so a remote
     branch can take the parsed options before bin/chi's local checks; `LaunchMode.attached_conflict` and
-    `LaunchMode::SCRATCH_LEFTOVER` / `BRIDGE_LATE` are the words both would print.
+    `Session::SCRATCH_REFUSED` / `BRIDGE_LATE` are the words both would print.
 
   An https chi web (a pod behind a proxy) needs TLS and chunked decoding in `StreamRequest`.
 - **Shared sessions (guests, roles).** The only access point is `App#token_gate`: one token, the owner's. Roles would

data/docs/internals/web-push.md

@@ -75,7 +75,7 @@ dropped that way, and an unknown id is ignored.
 That is how a subscription iOS revoked silently (Apple keeps answering 201, so `:gone` never comes) leaves the store:
 the user turns the bell off and on, the page has no live subscription to delete, and the new one replaces it. Every write is a read-change-write under
 `store.lock` (chi web's request threads and the sender thread both write). A `subscriptions.json` that doesn't read
-lists no device and is never written over. `Store#check_permissions!` uses `Web::PrivateFiles.check!`, the check the
+lists no device and is never written over. `Store#check_permissions!` uses `PrivateFiles.check!`, the check the
 grants use, worded with what the folder holds; `Server.launch` runs it (`Push.preflight!`, with the contact and the
 key) before any tunnel goes up, and a refusal is one `Error:` line, exit 1.
 

data/docs/memory.md

@@ -33,8 +33,8 @@ dir has a folder of the same basename with another hash, chi says so, naming bot
 `mv` that fixes it (a name match can't prove it's the same project, so nothing is renamed for you):
 
 - at session start, a `memory>` load warning (a `:guardrail_warning` with label `memory`; the attached
-  TUI, the REPL, `--non-interactive` and the web show it; a UI that attaches later gets it from the
-  worker's cards), once per worker or REPL process, so a respawn or resume says it again;
+  TUI, `--non-interactive` and the web show it; a UI that attaches later gets it from the
+  worker's cards), once per worker or `--non-interactive` process, so a respawn or resume says it again;
 - under a `memory_read` miss that looked in project scope (`scope: "project"` or none), and under the
   project index read, on a `Hint:` line after `Error: memory not found: …`. A system-scope read never
   gets it.