samagotchi 0.152.0 → 0.154.0

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.
 
 ```
@@ -57,7 +57,8 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #   local System 1 host they wait for the turn's end: started before warm_up_next_turn, whose warm-up
   │     #   waits for them, or from run_turn's ensure; docs/context.md, The judge);
   │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, ToolIndex#refresh! for find_tools'
-  │     #   chi line, a prompt rebuild when it changed). A Stop during the probes or the waits returns false
+  │     #   chi line, a prompt rebuild when it changed; a warn notice per plugin tool that arrived mid-session
+  │     #   with nothing to reach it, Registry#stranded_names). A Stop during the probes or the waits returns false
   │     #   (the ask's line says canceled; an ensure marks one the turn never settled failed).
   │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
   │     #   (a frozen copy of the history, the prompt, and resumed)
@@ -119,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
@@ -172,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:
@@ -298,12 +305,13 @@ One iteration with tool calls:
                                       on_stream_event:, max_tool_output_chars:)
           → under TurnSettings#loads_tools, a direct call of a source tool's acts_as (mcp_fs_read) is wrapped
             into the call_tool call it stands for (Registry::Index#wrap, ToolIndex#wrap)
-          → first, the call's entry unwraps it (Registry::Entry#unwrap: a call_tool of chi/<built-in> becomes
-            that built-in's call with via: "call_tool", ToolIndex#unwrap); the rest sees the real call
+          → first, the call's entry unwraps it (Registry::Entry#unwrap: a call_tool of chi/<name>, a built-in or
+            a plugin tool, becomes that tool's call with via: "call_tool", ToolIndex#unwrap); the rest sees the
+            real call
           → a tool the session's toolkit leaves out (Registry#left_out; with via:, one Registry#indexed doesn't
             reach) skips the gate: no hooks, no card; KernelLoop#dispatch answers it (the call_tool route for a
             reachable tool, the not-loaded error for a removed one). Under TurnSettings#loads_tools a reachable
-            built-in called by its own name is no such call: it runs through the gate, and KernelLoop#dispatch
+            built-in or plugin tool called by its own name is no such call: it runs through the gate, and KernelLoop#dispatch
             takes it (#loaded_entry)
           → Guardrails::Gate#evaluate (the before_tool_call hooks, then the core checks)
           → :tool_call_started
@@ -424,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`.
@@ -515,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.
@@ -644,7 +652,9 @@ Engine initialization (in this order, among other things):
   the bundles' plugins load (load_plugins → ExtensionLoad#load_plugins; each plugin's ctx is a
     Plugin::Context over plugin_host, whose ctx.sessions it builds itself: the test kit passes its own, sessions:),
     then (plugins or not) @tool_index.declare(@tools): find_tools + call_tool (source "index", not core),
-    declared per toolkit by Registry#declared? (a source registered at load, or a reachable built-in) and
+    declared per toolkit by Registry#declared? (a source registered at load, or a tool registered then that
+    the toolkit leaves reachable: Registry::Index#loaded; Toolkit::Resolved#declares? treats built-ins and
+    plugin tools alike: full declares both, another kit its list and adds) and
     sets call_tool's unwrap (Tools::ToolIndex: the chi group from Registry#reachable_names, the sources'
     groups, search, call checks, the unwrap; a source runs the call with its own plugin Context)
   @reminder_store = ReminderStore.new (the kernel gets it), @reminder_queue, @reminders
@@ -773,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.
@@ -866,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,9 +469,9 @@ 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 (`claimOpts()`, `normalizeClaim`; `spec/fixtures/redact_cases.json` keeps the two
+  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
   checks the same anchor against its parent's history. A completed Verify reply whose final non-empty line has
   a valid `Verdict: confirmed|refuted|unclear — <reason>` appends a verdict to the session. Both pages place its card
@@ -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

@@ -108,15 +108,19 @@ right-hand column happens.
   Claude 5.x cost the preserved thinking each time).
 - find_tools' description is a function of the toolkit and the source groups **at load**: `ToolIndex#declare`
   snapshots source group names and description lines (name, summary, callable count). `ToolIndex#refresh!` (from
-  `ToolkitBinding#apply!`) filters that snapshot by the new toolkit and rebuilds the `chi` line from the built-ins
-  it reaches; it never consults live group names. The same group filter drives searches, deferred MCP tools and
-  whether `find_tools`/`call_tool` are declared (`Registry#index_needed?`). An MCP server that finishes booting
+  `ToolkitBinding#apply!` at a toolkit change, and from `Engine#apply_staged_tools!` when a plugin's tool set
+  changed) filters that snapshot by the toolkit and rebuilds the `chi` line from the built-ins and plugin tools it
+  reaches; it never consults live group names. The same group filter drives searches and deferred MCP tools.
+  Whether `find_tools`/`call_tool` are declared (`Registry#index_needed?`) reads the groups and the entries
+  registered at load (`Registry::Index#loaded`), never later ones: a plugin tool `chi.replace_tools` adds doesn't
+  bring them in, and a loaded plugin tool it later removes still counts, so `find_tools` stays declared, perhaps
+  with an empty `chi` group. That is deliberate: the declared tools stay the same for the worker's life. An MCP server that finishes booting
   between load and the first turn changes search answers only, so two sessions on the same toolkit with the same
   MCP cache send the same bytes. Kits that omit `groups:` keep their previous request bytes; switching only
   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-frontend.md

@@ -10,8 +10,9 @@ only library. Pure modules (`*_model.js`, `session_state.js`, `sessions_list.js`
 and have `node --test` specs under `spec/web/public/` (happy-dom for the DOM ones); the pages as a whole are covered
 by `npm run e2e` (`spec/e2e/`). `app.js` has no unit spec.
 
-**`app.js` has a size cap**: `npm run lint` fails past `max-lines` in `eslint.config.js` (counted as `wc -l` counts,
-a little over its size today). A new feature goes into a module of its own, wired from `app.js` in a few lines; a
+**`app.js` has a size cap**: `npm run lint` fails past `max-lines` in `eslint.config.js` (counted as `wc -l` counts:
+2000, ratcheted down from 2250 when the versions, the owner's claim links and Verify, the composer's mode and the
+strip's hide went into modules of their own, which left room for a few features' wiring). A new feature goes into a module of its own, wired from `app.js` in a few lines; a
 refactor that shrinks `app.js` ratchets the cap down with it. Never raise it: extract instead.
 
 **New exports go in new modules.** The static JS is served at unversioned URLs. Today every load revalidates
@@ -23,7 +24,7 @@ page. A factory dep a new version stops passing is the same hazard the other way
 out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
 until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
 `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
-`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js` and the `objectives_*.js` modules are new modules for that reason. The last three `block_*` draw a bundle's fenced blocks: [block-renderers.md](block-renderers.md).
+`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `version_notices.js`, `owner_claim.js`, `owner_verify.js`, `composer_mode.js`, `strip_hidden.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js` and the `objectives_*.js` modules are new modules for that reason. The last three `block_*` draw a bundle's fenced blocks: [block-renderers.md](block-renderers.md).
 
 ## Two pages, two models
 
@@ -37,7 +38,7 @@ claim links, `composer_mount.js`, the verdict card and Verify fresh, `verify_tar
 `auth_lost.js`, `token_fragment.js`, `format.js`) but none of the data layer, the stream handling or the message
 rendering. It has its own `api` (`{status, ok, body}`, never throws, its own ended / auth-lost handling) and its own
 `EventSource`. Its parallel copies of the owner's Verify and claim helpers (`verifyFreshState`, `verifyAnchorFor`,
-`showPendingClaim`, `CLAIM_ROOTS`) differ on purpose in places (the source kind `reply` vs `answer`, the server's
+`showPendingClaim`, `CLAIM_ROOTS`; the owner's are `owner_verify.js` and `owner_claim.js`) differ on purpose in places (the source kind `reply` vs `answer`, the server's
 `fresh_running` vs `verify_fresh`, no home/cwd in its claim options). Don't converge them as a side effect of another
 change.
 
@@ -46,8 +47,8 @@ change.
 | Holder | What | Who writes | How a change reaches the screen |
 |---|---|---|---|
 | **The session store** (`session_store.js`; app.js `store`) | `store.selected` (the open session's id), `store.current` and `store.sessions` (below) | through the store only (see The session store); other modules get getters (`selected: () => store.selected`, `state: () => store.current`) or the store itself (`stream_handlers.js`, `send_turn.js`, `session_actions.js`) | the store runs the redraws that read what changed (below); nobody calls them by hand |
-| **app.js module scope**: about 20 top-level `let`s (`streamControl`, `eventsControl`, `pageCapabilities`/`pageEditorUrl`, `pendingVerifyAnchor`, `pendingClaim`, `resyncsInFlight`/`resyncAgain`, `resyncAttempts`, `scopeError`…) | the page's mode and its streams | app.js only; other modules get getters and hooks | the writer touches the redraw that reads it (`store.touch("infoBar")`: the stream, versions, `restartingIds`), or calls a redraw only it feeds |
-| **`store.current`** (`session_state.js`: `emptySessionState` / `sessionStateFrom`; per field: `session_fields.js FIELDS`) | the open session's fields, about 40 (info bar, chips, verdicts, timing, worker, stream cursor) | `store.update` / `setStatus` from app.js, `stream_handlers.js`, `send_turn.js` (`firstPreview`, `owner`), `session_actions.js` (`status`); `forgetSession`'s `replaceCurrent`. Two writers in place, on purpose (D8 in `FIELDS`): live_timing.js's `activeTurn`, verdict_fresh.js's running list | the store runs the field's redraws (`FIELDS[key].redraws`) |
+| **app.js module scope**: about 20 top-level `let`s (`streamControl`, `eventsControl`, `pageCapabilities`/`pageEditorUrl`, `resyncsInFlight`/`resyncAgain`, `resyncAttempts`, `scopeError`…) | the page's mode and its streams | app.js only; other modules get getters and hooks | the writer touches the redraw that reads it (`store.touch("infoBar")`: the stream; `version_notices.js` does it for the versions and its `restarting` set), or calls a redraw only it feeds |
+| **`store.current`** (`session_state.js`: `emptySessionState` / `sessionStateFrom`; per field: `session_fields.js FIELDS`) | the open session's fields, about 40 (info bar, chips, verdicts, timing, worker, stream cursor) | `store.update` / `setStatus` from app.js, `stream_handlers.js`, `send_turn.js` (`firstPreview`, `owner`), `session_actions.js` (`status`), `owner_verify.js` (`verdicts`, `verifyFresh`); `forgetSession`'s `replaceCurrent`. Two writers in place, on purpose (D8 in `FIELDS`): live_timing.js's `activeTurn`, verdict_fresh.js's running list | the store runs the field's redraws (`FIELDS[key].redraws`) |
 | **`store.sessions`** (the hub's projection) | every card | `store.update({sessions})` from app.js: `openSessionEvents` (`applySessionEvent`), `refresh` (the list fallback), `addCreatedSession`, `applyView` (re-sorted), `replaceSelectedCard` (`setLiveStatus` through `setStatus`, `readTurnEnd`, `setUsedMemories`), the stream's close (`withoutWorker`); `session_actions.js` (`setSessions`) | the store: `lists` and `infoBar`. **Always a new array**; an entry is replaced, never changed in place. `followSelectedSession` copies the open one's owner and worker (`fieldsFromCard`) and, when not streaming, its status (`setStatus(…, "hub")`) into `store.current` |
 | **Factory closures**: the `create*` factories (popovers, panels, views) | each component's own state: open-for, busy, error, its own fetched list | the factory | an `onChange` hook back into app.js, or a getter the factory reads at draw time |
 | **The history DOM** | the conversation as drawn: which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), what opens a turn (`TURN_PROMPT`, `bubbles.js`: a prompt or a wake's note, the same turns `Steer.turn_opening?` counts for a card's or the recap's `turns_since`), kept command bubbles, which texts were shown, unnamed badges, folded answers and long prompts (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`); the switcher's version on view is `revise_stack.js`'s own (a copy `.stack-view` before the top answer, the top `.stack-swapped`; never stored) | `bubbles.js`, `cards_place.js`, `question_cards.js`, `turn_block.js`/`stage_view.js`, `answer_fold.js`, `revise_stack.js`, `stream_handlers.js` (a live `turn_completed`'s `revises` and `verify` onto its prompt) | read back as state: `turn_range.js turnElements` (one walker for a turn's elements), `keptCommandBubbles`, `seedSeenFromDom`, `nameUnnamedBadges`/`nameVerdictCards`, `answer_fold.js` and `revise_stack.js` (their observers decorate every path that fills `#history`; the stacks are `stacks()` of the stamps, read again on each change, never a store field), `history_reveal.js revealInHistory` (the one way a jump unfolds what hides its target) |
@@ -73,8 +74,9 @@ through the store**, never `current.X = …`:
   old one writes there alone.
 - `store.batch(fn)`, `store.touch(name)`, `store.on(name, fn)`: the redraws (below).
 
-The ESLint block `samagotchi/session-writes` (eslint.config.js) enforces it in the six modules that hold the state
-(app.js, `stream_handlers.js`, `send_turn.js`, `session_actions.js`, `start_page.js`, `working_set_view.js`): an
+The ESLint block `samagotchi/session-writes` (eslint.config.js) enforces it in the seven modules that hold the state
+(app.js, `stream_handlers.js`, `send_turn.js`, `session_actions.js`, `start_page.js`, `working_set_view.js`,
+`owner_verify.js`): an
 assignment, `++`, `delete` or `Object.assign` into `current`, `store.current` or `state()` is an error
 (`spec/web/public/lint_session_writes.test.js` runs it on a sample). An alias (`const st = state(); st.x = …`) isn't
 caught: don't write through one.
@@ -105,16 +107,16 @@ stale).
 **The redraws are registered, not called.** app.js registers each name once (`store.on`, at the bottom, once every
 piece a redraw calls exists): `lists` → `lists.render()`, `paintActive` → `lists.paintActive()`, `settingsPanel` →
 `settingsControl.refresh()`, `workingSetStrategy` → `workingSet.strategyChanged()`, `featureGates` (below), `composer` →
-`updateComposerMode()`, `infoBar` → `updateInfoBar()`. A writer writes and stops there: no `updateInfoBar()` after
+`composerMode.update()` (`composer_mode.js`), `infoBar` → `updateInfoBar()`. A writer writes and stops there: no `updateInfoBar()` after
 a store write. A value written unchanged redraws nothing (a chunk with the same ctx %).
 
 An input the store doesn't hold calls `store.touch(name)` where it changes: `infoBar` for the clock (liveTurn's
-`onTick`), the versions (`noticeVersions`), `restartingIds`, the stream (`startStream`, `workerGone`), the working
+`onTick`), the versions and the sessions restarting (`version_notices.js` `notice`, `restart`), the stream (`startStream`, `workerGone`), the working
 set's and the participants' `onChange`, the continue and review in-flight sets
 (`session_actions.js`); `composer` and `infoBar` for `liveTurn.running` (`setTurnRunning`, with `settingsPanel`:
 the open ⚙ panel's running-turn note) and at the end of `renderSessionView` (a whole view drawn). Left as they are,
-on purpose: the `narrowScreen` listener calls `updateComposerMode()` (the bar doesn't read it),
-`applyStripHidden`/`applyView` call `updateSessionTitle()`, and `closeStream`/`stream.restart` set
+on purpose: `composer_mode.js`'s phone-width listener calls its `update()` (the bar doesn't read it),
+`strip_hidden.js`'s apply and `applyView` call `updateSessionTitle()`, and `closeStream`/`stream.restart` set
 `streamControl = null` without a redraw (a resync or a workerGone follows).
 
 A function that writes more than once batches its synchronous part, so each redraw runs once: `select` (before its
@@ -178,7 +180,7 @@ The redraws, by their store names:
 - `infoBar` (`updateInfoBar()`): the session bar's buttons and info line (`info_bar_model.js sessionBar` →
   `info_bar.js`), the annotate bar, the fold controls, `updateSessionTitle()` and the fresh link's picker. Cheap: it
   runs on most writes and every clock tick.
-- `composer` (`updateComposerMode()`): the composer's placeholder, buttons and delivery line (selected, running,
+- `composer` (`composer_mode.js` `update()`): the composer's placeholder, buttons and delivery line (selected, running,
   owner).
 - `settingsPanel` (`settingsControl.refresh()`): the ⚙ chip's **open panel** (`settings_chip.js`; the chip itself is
   drawn by the bar), on `thinking`, `reasoningHistory` and `llmContext`; `workingSetStrategy`: the working set's open
@@ -190,7 +192,8 @@ The redraws, by their store names:
 `forgetSession()` is the one reset: `select` and `clearSelection` both call it, so anything per-session that isn't
 in `store.current` (capabilities, the markdown warning and tip, the init row, the Verify claim, the armed Revise,
 the running turn's DOM) is cleared there, and the feature gates are primed for the empty session. A new per-session holder
-(an armed composer anchor like the Verify claim or the Revise) goes into it. The armed Revise
+(an armed composer anchor like the Verify claim or the Revise) goes into it. The armed Verify claim is
+`owner_verify.js`'s holder (`anchor()`, `set(a)`, `clear(a?)`: `clear(a)` lets go only of `a`). The armed Revise
 (`pendingReviseAnchor`) is set only through `setReviseAnchor`, which redraws its chip and the Revise buttons (a
 redraw only it feeds, not a store field).
 
@@ -222,7 +225,7 @@ each keeps one set of handlers, confirmations and in-flight rules. A chip the sh
 matters at exactly 600 px, where the CSS is a phone's but the shell (`SHEET_MAX`, `<`) still draws a popover, not a sheet.
 A new chip on the bar needs its place in that CSS's hidden list and a row in `moreRows`, and its attention state in the row, or
 it is lost on a phone. `app.js`'s `updateInfoBar` feeds the sheet (`update`) on every redraw; its rows and actions draw into
-fixed slots, so a row that joins keeps the focus where it was. The `narrowScreen` listener closes the sheet when the window grows.
+fixed slots, so a row that joins keeps the focus where it was. `composer_mode.js`'s phone-width listener closes the sheet when the window grows.
 
 
 ## The stage's height
@@ -321,11 +324,11 @@ reach another device or the server.
 | `chi_model`, `chi_model_recent` | `model_pick.js`, `model_picker.js`, `start_page.js` | the start page's model and its recent list |
 | `chi_composer_collapsed` | `composer_fold.js` | the composer folded (a card's text field folds it for the time it has the focus on a narrow or touch screen, `composer_grip.js watchCardField`, on top of this and of the visit's state: neither is written) |
 | `chi_composer_floor` | `composer_grip.js`, `composer_mount.js` | the composer's dragged height |
-| `chi_strip_hidden` (`chi_zen`: the old name, read once) | app.js | the session strip hidden |
+| `chi_strip_hidden` (`chi_zen`: the old name, read once) | `strip_hidden.js` | the session strip hidden |
 | `chi_stage_collapsed` | `stage_view.js` | the stage collapsed |
 | `chi_working_set_collapsed` | `working_set_rail.js` | the working set rail collapsed |
 | `chi_markdown_tip_dismissed` | `markdown_tip.js` | the markdown tip dismissed |
-| `chi_update_available_shown` | app.js | update notices already shown |
+| `chi_update_available_shown` | `version_notices.js` | update notices already shown |
 | `chi_notify`, `chi_push_device` | `notifications.js` (an injected storage) | the bell's state, this device's push id |
 | `chi_answer_fold:<session>` | `answer_fold.js`, `revise_stack.js` | the answers and long prompts (`<turn id>:prompt`) folded by hand, and the Revise stubs unfolded by hand (`stub:<turn id>`) (swept with the session list) |
 | `chi_review_history:<grant>`, `chi_review_history_session:<session>` | `review_history.js` (participant page) | a participant's composer history |

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.