samagotchi 0.141.0 → 0.142.0

data/docs/internals/bridge.md

@@ -0,0 +1,380 @@
+# The Bridge
+
+The Bridge (`lib/samagotchi/bridge.rb`, `Samagotchi::Bridge`) is a session worker's only live client transport: a
+localhost HTTP server in the worker's process, next to the `Engine` it reads and drives. chi web and the attached
+terminal are its clients; no browser reaches it. [architecture.md](../architecture.md) places it among the layers;
+this page is the surface: what it keeps, how a client joins and catches up, and every route.
+
+## What a Bridge keeps
+
+`Bridge#start` binds a port (OS-assigned, `127.0.0.1`), then subscribes four persistent observers to the Engine
+(`Engine#subscribe`, the thread-safe fan-out whose events all carry a monotonic `event_seq`). Each is cheap and
+rescues its own errors: an observer must never break the running turn.
+
+| Piece | File (`bridge/`) | Holds |
+|-------|------------------|-------|
+| `RingBuffer` | `ring_buffer.rb` | The last `ring_capacity` (256) raw events by `event_seq`, in memory, for a reconnect's replay. The capture observer feeds it. |
+| `TurnAccumulator` | `turn_accumulator.rb` | The turn in progress, folded from events. |
+| `CardStore` | `card_store.rb` | The last cards and notices, saved in `cards.json`. |
+| `PendingCard` | `pending_card.rb` | `pending_card.json` `{id:, bundle:}`: the running turn's open card with actions (check-in's Nudge), written and removed with that card, so chi web's hub, which watches files and not workers, can notify. |
+
+Per connection there is an `SSEWriter` (with a `BoundedQueue`); `ClientEvent` and `EventId` are pure helpers. The
+Bridge also owns its **epoch** (`SecureRandom.hex(4)`: `event_seq` starts over in each worker, so the epoch says
+whose seq a cursor is) and its **secret**; both are published in `bridge.json` (`WorkerSidecar`) with the port.
+
+## TurnAccumulator
+
+A joining UI must draw a turn already half done, and the ring may have dropped its early events. The accumulator
+folds the event log into one hash, `current_turn`: the prompt, `turn_id`, origin, `at`, and ordered `parts`
+(generation, thinking, text, tool, input, steer, reminder, notice), plus `pending_question`. A tool part keeps its
+row fields (`ToolRowFields`), its output cut head-and-tail at `ToolOutputCut::WEB_PREVIEW_CHARS` so a joined row is the
+row a reload draws, and `elapsed_ms` while it runs (the accumulator times running calls itself, `clock:`). A
+`notice` part holds the event of a row that is neither text nor a tool call (`TurnNotice::FIELDS`: a hook's notice,
+the "asking again" row, a steer's cut, a ✂ row, a question and its answer), so a join replays it through the handler
+that drew it live.
+
+The turn is cleared on its terminal event (`Events::TURN_END`), the same event that brings its messages into the
+session, so a snapshot shows a turn in exactly one of the two places. Beside the turn it keeps what a snapshot also
+needs and the messages lag: `queued` turns (`:turn_enqueued` until started, merged or dequeued), `queued_commands`,
+the idle `recap` (until a turn starts), a pending `continue_offer`, and the running turn's `working_set`.
+
+Three other users: `replay_events(turn)` turns a `current_turn` back into the live events that would have drawn it
+(the web's `snapshotEvents` replays them; `spec/shared/turn_snapshot.json` pins both sides); `messages_of` gives a
+plugin's `ctx.messages` the turn so far (`Engine#running_turn_messages`); `participant_turn?` tells `POST /turn` that
+a participant's review turn runs, so the owner's input queues behind it.
+
+## CardStore
+
+The cards a plugin or the Engine shows (`Engine#show_card`), hook notices, load warnings (`:guardrail_warning`),
+the "asking again" and steer-cut rows, ✂ rows and questions (with how they were answered), for a UI that joins later:
+`snapshot[:cards]` and `GET /tail`'s `cards`.
+
+- **Placement is relative.** An entry carries `turns` and lists with `turns_since` (turns completed after it) and
+  `current` (a card of the running turn). A card that comes mid-turn but isn't the turn's (an anytime command's, such as
+  `/btw`) goes after that turn (`during`). A card with an earlier card's id replaces it in place.
+- **Caps.** `CAPACITY` (20) each for notices, ✂ rows (`LLM_CONTEXT_TYPES`) and cards, so one burst cannot push out
+  another kind. An open question (an approval too) is never pushed out.
+- **Saved.** With a `path` (`cards.json` in the session's folder) the store rewrites the file after each event in
+  `SAVED_ON`, and a later worker's store starts from it, so a turn's cards outlive the worker; `CardStore.saved(dir)` is
+  what chi web reads for a session no worker runs. Load warnings are the worker's own (each start announces them)
+  and an unanswered question waits for no one: neither is saved or seeded. An entry from an earlier worker lists with
+  `earlier: true`; one shown during a turn comes back **without its actions** (their turn no longer runs), while a
+  between-turns card keeps its buttons.
+
+## SSEWriter
+
+One per `GET /session/:id/stream` connection, and itself that connection's observer: `Engine#emit_event` calls
+`#call` on the turn's thread, so it only pushes onto a `BoundedQueue` (when full, the oldest entry goes and an
+overflow flag is set). The connection's own thread (`#serve!`) drains the queue onto the socket, so a slow client
+cannot stall a turn or another subscriber. `serve!` orders a join so that nothing is missed or doubled:
+
+1. subscribe the live queue first;
+2. capture `event_count` (the snapshot seq);
+3. replay the ring's events in `(from_seq, snapshot]`;
+4. drain the queue for `seq > snapshot`; a per-connection high-water mark drops what step 3 already wrote.
+
+`?snapshot=1` replaces 2-3: subscribe and `Bridge#snapshot_frame` happen as one step with the event log held
+(`Engine#synchronize_events`), the client gets one `snapshot` frame, and live events follow from the next seq.
+
+A **`reset`** frame (the same content, numbered with its own seq) is written when a cursor cannot be replayed: it is
+from another epoch, ahead of the engine (a restarted worker), behind the ring's window (a cursor at `oldest - 1` has
+seen everything before the window and replays), or the queue overflowed since the last drain. A cold connect replays
+the whole window. Replay state is in memory per worker; there is no durable resume.
+
+Each frame is `id: <seq>-<epoch>` (`EventId`: the seq first so a reader that takes it as a number still gets the
+seq), `event: <type>`, `data: <json>`. A `: ping` goes out after `heartbeat_interval` (15 s) of silence. A watcher
+thread reads the socket for EOF so a hang-up is noticed at once, not at the next write, and `Bridge#open_streams_except`
+(used by `POST /exit`) stops counting that stream.
+
+**ClientEvent.** Every event is projected on its way out, live and replayed alike (`ClientEvent.project`, pure: the
+event hash is shared by every observer and is never mutated). `generation_chunk` loses `payload` and `content` and
+gains `counts`; `tool_call_started` loses `call`; `turn_completed` loses `result`; everything else, `event_seq`
+included, passes through. `?raw=1` skips the projection (debugging). Add a field to the wire only here, when a client
+needs it.
+
+## Routes and reads
+
+The route list, the wire shapes, the browser/proxy refusals and the secret, as the Bridge answers them. Every route
+goes through `Bridge#dispatch`.
+
+The Bridge exposes:
+
+
+- `GET  /session/:id/stream` — SSE stream of engine + kernel events, each with an
+  `id: <event_seq>-<epoch>` cursor (the epoch is drawn per worker's Bridge, since `event_seq` starts
+  over in each worker; snapshots and `/state` carry it as `event_id`); resume via `Last-Event-ID` /
+  `?from_seq=` (a plain `event_seq` is still accepted); a `: ping` heartbeat keeps idle proxies alive;
+  too-old reconnects, and cursors from another worker's epoch, receive a `reset` marker carrying
+  `session_state_snapshot`. `?snapshot=1` joins with a snapshot frame instead of a replay;
+  `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
+  Each event goes out as clients get it (`Bridge::ClientEvent.project`, in `SSEWriter#write_event`, live
+  and replayed alike); `generation_chunk`, `tool_call_started` and `turn_completed` are projected to the
+  contracts below. The ring retains raw events for replay and `?raw=1`.
+  `?raw=1` writes events as the engine emitted them, for debugging on the worker's port: `chi web`'s
+  `/api/sessions/:id/stream` never passes it on (`Web::App#stream_query`).
+  An attached terminal's stream (`EventStream` with `rediscover:`) looks for the session's live
+  worker whenever it drops: a new one (a restart) is followed from its snapshot, and the terminal
+  sends its requests there (`worker_changed`); it gives up after ~12 s, or at once when the session
+  was stopped.
+
+  The wire chunk (the contract; the engine's own event keeps the provider's `payload` and the raw `content`):
+
+  ```
+  event: generation_chunk
+  data: {"type":"generation_chunk","iteration":2,"text":"…","thinking":"",
+         "tool_call":true,                                   // only when set
+         "counts":{"prompt_tokens":489,"completion_tokens":12,
+                   "total_tokens":501,"context_window_tokens":32768},  // only when the server reported counts
+         "event_seq":812}
+  ```
+
+  A `tool_call_started` frame keeps its row fields but omits the model's `call`:
+
+  ```
+  event: tool_call_started
+  data: {"type":"tool_call_started","iteration":2,"call_index":1,"tool":"write",
+         "params":"path=notes.txt","event_seq":812}
+  ```
+
+  A `turn_completed` frame omits `result`; `turn_summary.output` carries the answer:
+
+  ```
+  event: turn_completed
+  data: {"type":"turn_completed","turn_summary":{"output":"Done."},
+         "display_pending":false,"event_seq":813}
+  ```
+
+  `counts` is `ContextUsage.normalize` of the provider's payload without `ctx_pct` (normalize computes it
+  without the session's LLM context budget; a client counts `total_tokens` against the window or budget, as
+  `ContextStatus#generation_done` does for the TUI) and with its nil keys left out: cumulative for the
+  request, a missing key means unknown (never 0), `prompt_tokens` includes cached tokens, and
+  `context_window_tokens` is there only when the payload reported a window itself (llama.cpp's `/completion`
+  doesn't: the client uses `generation_started`'s). Unknown provider fields never cross; a field is added here
+  when a client needs it, never as a catch-all bag. Details: [internals/context-telemetry.md](context-telemetry.md).
+- `POST /session/:id/turn` — fire-and-forget turn creation; returns `202` with an `enqueued_id`
+  (delivery is at-least-once via the worker's file-IPC input path — it never calls `run_turn`
+  across the HTTP boundary). Only the bridge's own session: another id, in the path or the body's
+  `session_id`, is `404 unknown_session`. Inspect results through the read surface, not the turn response.
+  An optional `deadline` (epoch seconds; `BridgeClient` sends 5/6 of its read timeout ahead) makes
+  a request read after it (a worker frozen by sleep or SIGSTOP) answer `408 deadline_passed` and
+  not run: a client that timed out has said the message was not sent. `/answer`,
+  `/question/dismiss`, `/command`, `/turn/dequeue` and `/exit` take the same `deadline` (a command is
+  checked with the event log held, as a turn is), and the Bridge logs `turn_expired`, `answer_expired`,
+  `dismiss_expired`, `command_expired`, `dequeue_expired` or `exit_expired`. The web app answers either
+  kind of timeout with `504 worker_timeout` ("… so the command was not run"). `/cancel` and `/recap` take none.
+  The web relays answer, dismiss, command and cancel the same way (`App#relay`): a 408 or a read
+  timeout is `504 worker_timeout`; a Bridge 404 for a route an older worker lacks is
+  `501 not_supported` with the restart hint; a Bridge `404 unknown_session`, no bridge or a
+  refused connection is `503 not_live`.
+- `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
+- `POST /session/:id/recap` — `/recap` in an attached TUI: `200 {enabled, saved, request,
+  min_user_turns}` (`{enabled: false, session_off}` without recaps; `session_off` when the session's own
+  `/recap off` turned it off); a new recap is asked for at once and
+  arrives as `:recap_ready`. Answers mid-turn too.
+- `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
+  answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
+  (`chi answer`, a parent agent) the answer is checked by `Guardrails::ParentPolicy` in
+  `QuestionDesk#answer`: the question carries each option's effect (`effects`, set by its asker:
+  `Approval.payload`, `ContinueOffer`, `Relay.card`; derived for an untagged one) and `user_only`,
+  and an option beyond the worker's `guardrails.parent_answers` (tightened by the session's own
+  `parent_answers`: `ParentPolicy.for_session`) is `403 parent_answer_refused` (with its `reason`),
+  the question still open. `chi answer` makes the same check first, from the session file.
+- `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
+  `200`, or `409` when it is no longer pending.
+- `POST /session/:id/tasks/stop` — `{task_id}`: stop a background task as the user
+  (`TaskRuntime.stop_task by: "user"`, the web's stop-task button on a running `task_wait`;
+  web route `POST /api/sessions/:id/tasks/:task_id/stop`). Only a task this conversation's
+  `task_create` started, or an `execute` handed over as a task at its limit (`TaskRuntime.created_ids_in` on the
+  saved messages, or the running turn's accumulator); answers once the
+  task is gone: `200 {status, stop_reason, task_id}`, `404 task_not_found`, `409 not_running`.
+  The worker names it in its sidecar features (`task_stop`).
+- `POST /session/:id/turn/dequeue` — `{enqueued_id, client_id?, deadline?}`: take back a queued message
+  (one that waits for the running turn's end: `--queue`, Alt+Enter, `/queue TEXT`, or a message
+  with images) before a turn takes it (web route `POST /api/sessions/:id/turn/:enqueued_id/dequeue`,
+  the × on a queued bubble; `/unqueue` in the attached TUI). Under the event log, like its enqueue:
+  `SessionInbox.take_queued_input` writes a tombstone (`input/removed/<enqueued_id>`, for `ReplyWait`'s
+  `turn:`), claims the file as the drain does (one rename wins; a lost claim takes the tombstone back),
+  deletes it, and the Bridge announces `:turn_dequeued`. `200 {status: "removed", enqueued_id, prompt}`, `409 already_started`
+  (a turn took it), `409 not_queued` (a next-step message: a drain may merge it any moment), `404
+  unknown_enqueued_id`. It never wakes the worker. The worker names it in its sidecar features (`unqueue`).
+  A worker's start prunes the `input/removed/` and `input/settled/` tombstones older than a week
+  (`SessionInbox::TOMBSTONE_MAX_AGE`, log `tombstones_pruned`); otherwise they go with the session dir.
+- `POST /session/:id/relay` — the approval relay, on a delegated child's worker
+  (`{action, relay_id, question_id}`): `opened` / `closed` (with a `reason`) set or clear the
+  pending question's `relayed_to` mark (`QuestionDesk#annotate`, `:question_relay`); `answered`
+  makes the child ask its parent's Bridge for the answer (`RelayVerifier`) and take it only for
+  this child and the question pending now. `200`, `409` no longer pending, `403` a parent agent's
+  pick beyond the child's own `guardrails.parent_answers` and session `parent_answers` (`parent_answer_refused`; the
+  relay card in the parent was held to the parent's), `422 relay_unverified` (the question
+  stays open).
+- `POST /session/:id/relay/status` — on a parent's worker, `{relay_id}`: what its `RelayDesk`
+  (memory only) holds for that relay (`child_id`, `child_question_id`, `state`, `answer`, `by`);
+  `404` for an unknown id. A POST with a body because routes match exact paths.
+- `POST /session/:id/command` — a session command (`/model`, `/models`, `!rollback`, `!cmd`,
+  `/continue`) for the worker loop; `202` with a `command_id` its `:command_ran` names, `400` when
+  the line isn't one. A `:command_ran` carries `thinking`, `reasoning_history` and `llm_context`
+  (the summaries the next turn runs under) when the command changed them or the model, and
+  `confirm: {line, text}` when a `/thinking` or `/reasoning-history` change from a `web:` or `tui:`
+  client asks first (`CacheConfirm`; nothing changed, `line` applies it).
+- `POST /session/:id/exit` — ask the worker to exit now (`{client_id:, delete?, restart?, deadline?}`; `delete`:
+  `/exit --delete`, no recap written; `restart: true`: hand the session to a new worker on the newest chi
+  installed, `200 {status: "restarting"}`; an empty session's `exiting` carries `discard: true`). The worker checks with
+  the event log held (`WorkerIdleExit#hold_for_request`): `200 {status: "exiting"}` and it leaves
+  like an idle exit, or `409 {status: "held", reason:}` with `turn_running`, `input_queued`,
+  `continue_offered`, `client_connected` (a stream not named by the asker), `reminders`,
+  `background_tasks` (with `tasks: [{id, command}]`: the running tasks a finish wake watches), `starting`, or
+  `leaving_exit` / `leaving_delete` / `leaving_restart` when another client's exit of another kind is already taken
+  (`Worker#claim_exit`, claimed before a stop-all; the words are `WorkerIdleExit::LEAVING_WORDS`). A second exit of
+  the kind already taken is answered `200` as that one.
+- `GET  /session/:id/state` — `session_state_snapshot` (JSON).
+- `GET  /session/:id/stats` — `Engine#stats_snapshot` for attached `/stats`: the metrics, with the context window and prompt profile asked from the server before the first turn.
+- `GET  /session/:id/snapshot` — the snapshot frame's content as one request (the web server renders
+  the messages itself, then streams from its `event_seq`). Read by the web's full show
+  (`GET /api/sessions/:id`, `?parts=1`) and the plugin's `list_sessions`; every message is copied.
+- `GET  /session/:id/tail` — the page's light re-read (`Bridge#tail_frame`): `session_state_snapshot`,
+  `working_directory` (the session's folder, which the web checks the answer's file refs against),
+  `answer` (the last message a UI shows as an answer, `AnswerTail`: the one message, copied alone),
+  `cards` (`CardStore#list`; a card an earlier worker showed during a turn comes back read-only, with no
+  actions: its turn no longer runs), `event_seq`, `event_id`, all taken in one event-log hold; no message
+  list, so it costs the same however long the session is. `?turn_id=` answers that turn's answer
+  (an unknown or missing id: the newest); the only route that reads its query.
+- No browser: only chi's own clients talk to a Bridge. A request with an `Origin` header, a `Sec-Fetch-Site`
+  other than `none`, or a `Host` that isn't loopback (a DNS-rebound page) is `403 cross_origin`
+  (`Bridge#browser_request?`, before any route); there is no CORS and no `OPTIONS` route. The browser reaches a
+  worker only through `chi web`. A request carrying any trace a proxy adds (`ProxyTrace`: `X-Forwarded-*`,
+  `Forwarded`, `X-Real-IP`, `X-Auth-Request-*`, `Cf-*`…, underscore twins too) is `403 proxied`
+  (`Bridge#proxied_request?`): an auth proxy that forwards every local port and adds such a header doesn't reach a
+  worker.
+- **The secret.** Every request, on every route (the stream, the reads such as `state` and `stats`, the writes, and
+  an unknown path), names the Bridge's secret in `X-Chi-Bridge`; one without it, or with another one, is
+  `403 bridge_secret` with one session-specific message (`BridgeSecret.refused`): "session ID's worker refused
+  this chi's request (it didn't name its secret): a chi web or terminal started before chi was updated can't
+  reach it; restart chi web, re-attach with `chi --attach ID`, or restart the worker with `chi sessions restart
+  ID`." `chi sessions restart` can also recover when the worker cannot be asked: TERM + resume if disk shows no
+  running turn, pending question or approval, queued input, or running background task. The check is after the
+  browser and proxy checks and before any route (`Bridge#secret_ok?`,
+  `OpenSSL.secure_compare`). No route is left open: what the reads show is the session itself. Only a request that
+  got past it counts as client activity, so a refused one (an older chi web's polls) never holds the idle exit. Each Bridge makes its own (`SecureRandom.hex(32)`, 64 hex
+  characters) when it starts and writes it to `bridge.json`, which is 0600 from the moment it exists
+  (`AtomicFile` creates the temporary file with that mode, then renames it), so only this machine's user can read
+  it: a forward that adds no proxy header, or another local account, reaches the port but not a session. Clients get
+  it only from the sidecar: `WorkerLink.client`/`.await` and `BridgeClient.for_sidecar` take the port and the secret from the
+  same read (chi web makes its client from the sidecar for every request, the attached terminal again on a
+  `worker_changed`), so a respawned worker's new one is used and nothing passes a port by hand. A worker from before
+  the secret writes none and asks for none; a chi web or attached terminal from before it sends none, so a worker
+  the newer chi started refuses it until it is restarted. A client tells that refusal from a route's own 403
+  (`BridgeClient::Response#secret_refused?`) and shows the one message: chi web's relays answer 502 `bridge_secret`,
+  `chi answer` and a parent's approval relay say it instead of "refused", and an event stream ends with reason
+  `bridge_secret` once rediscovery finds no newer worker (the attached terminal's closing line), never retrying in
+  silence; chi web's stream proxy answers 502 `bridge_secret`, never passing the refusal on as frames. The secret is never logged (a refusal logs
+  `secret_refused` with the path, at most once a minute), never in an event, a reply, `/api/info` or a session
+  file, and `WorkerSidecar`, `BridgeClient` and `Bridge` leave it out of `#inspect`.
+
+The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` frames
+(`SessionMetrics#snapshot`) carry the session's totals and only the recent timing records: the
+newest turn the worker finished and any it hasn't saved yet (at most 20 turns), with their tool
+calls and the running turn's finished ones. The full history is the session's `analytics.json`,
+which `SessionMetrics#persist` rewrites after each turn; the web server merges the two by id.
+The totals' `tokens` block adds the cached, cache-write and reasoning sums, the reported cost (`cost_sum`) and the
+estimated one (`cost_estimate_sum`, from `hosts.<name>.models` prices; 0 for none), the decode time and tokens
+behind the average speed (`avg_decode_tps`) and the last speeds (`last_decode_tps`,
+`last_prefill_tps`, `tps_source`: `server` or `estimate`). `model_segments` (always present) splits those sums
+by model after a `/model` switch: one row per run of consecutive turns on one model (`SessionMetrics::ModelSegment`,
+keyed on the turn records' `model_ref`), in order, with its turns, token and cost sums, speeds and the switch's prefill
+(`prefill_tokens`, `prefill_cost_estimate`: the sums of its turn records' `switch_prefill_tokens` and
+`switch_prefill_cost_estimate`, [sessions.md](../sessions.md)); `[]` with one model, the oldest rows folded into one (`folded_segments`)
+past 6; a running turn counts in its model's row (`ended_at` null). The rows add up to `tokens`. They are derived from
+the records, never read back. Each `generation_completed` event
+carries the generation's `speed` (`{decode_tps, source}`, null without one), its own prompt-cache
+counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
+those running `tokens` and `model_segments`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
+it, so the web's info bar updates per generation without parsing chunk payloads.
+Side requests (the idle recap, a plugin's `ctx.ask_model` such as `/btw`) are counted apart, in a `side` block
+(only when there were any; `SessionMetrics::SideTotals`: requests, token sums, `cost_sum` null until reported,
+`cost_estimate_sum` from the target host's price, `by_kind`): `IdleClient` hands each reply's usage to its
+`on_usage:` callback, `Engine#note_side_usage`, which folds it (`SessionMetrics#add_side`) and announces
+`:side_usage` (`kind`, the whole `side` block) under the event lock, so the blocks arrive in fold order, then saves
+`analytics.json` between turns (a running turn's end saves it). `tokens`, `model_segments` and the turn records
+stay the turns' only. `SessionMetrics#persist` is serialized (its own mutex, taken before the metrics one), so two
+threads' saves land in snapshot order.
+A bundle's `ctx.cost` reads the same sums (`SessionMetrics#cost`, a frozen `SessionMetrics::Cost`): the `tokens`
+block's `cost_sum` and `cost_estimate_sum` with the running turn's finished generations folded in, plus the `side`
+block's, so it counts what earlier workers spent too ([plugins.md](../plugins.md)). Its `ctx.usage` reads the work
+(`SessionMetrics#usage`, a frozen `SessionMetrics::Usage`): the snapshot's `turns`, `tool_calls_total` /
+`tool_calls_by_tool` and `iterations_total`, and `active_ms`, the generations' `gen_ms` plus the finished tool
+records' `duration_ms` (tallied per tool as they are counted; `ask_user_question`'s, a wait on the user, left out).
+
+The page's frequent reads of `GET /api/sessions/:id` stay light too:
+- `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,
+  used_memory_names}, messages: [the answer, with its display and display_refs (re-read on an `answer_display` with a display or refs)], markdown_warning, timing}`, from the worker's `/tail`
+  alone (no session file parsed, no `analytics.json`); `timing` carries the worker's recent records
+  and `turn_count` (finished turns). The page merges the records by id (`timing.js mergeTiming`) and
+  finishes the ended turn's own line by its `turn_id` (sent as `&turn_id=`, which also picks that
+  turn's answer). A tail read's timing is always the newest turn's; `recent=1` is accepted and not needed.
+  The page binds an answer's `display_refs` to its bubble (`answer_refs.js`: on a reload's render and on this
+  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A question's
+  refs (`pending_question.refs`, `:question_asked`) pair the same way (`markdown_place.js` `linkRefsIn`/`pairRefsIn`):
+  `question_requested` (or a snapshot's pending question) keeps them on the asking step's gen
+  (`turn_model.js` `questionRefs`) before the card draws, so the stage's asking slot (`stage_slots.js`
+  `drawAsking(text, refs)`) pairs them on its raw draw and again after its markdown swap; the card pairs its
+  question text and its kept reply (`question_cards.js`); the step's closed `.gen-text` takes them
+  (`turn_block.js`; on a reload its `data-answer-at`, the message's `display_refs`) and `linkTextRefs` pairs it at
+  the turn's end and after a reload. A closed step's text is markdown too with `web.markdown` on: a reload's
+  from its message's `html` (`turn_block.js` `textTemplate`), a live turn's from `POST /api/render` on its step's
+  first open after the turn's end (`markdown_place.js` `renderStepTexts`, which pairs its refs again after the
+  swap); the text as written stays on it as `data-copy-source` (`stepText`, a reloaded card's kept reply). A file ref outside the
+  session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
+  session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
+  file ref is dropped rather than shown unchecked.
+  A plugin tool's row refs (`refs`, `RowRefs`) ride its tool events and, on a reload, its part (saved as
+  `tool_refs`); `turn_block.js` binds them to the row's title (`refs.js bindRowRefs`: the first on the title,
+  the others in its menu).
+- `?timing=1`: the whole timing (`analytics.json` merged with the worker's `/state`) and
+  `turn_count`, when the page's merge came up short.
+- `?cards=1`: the cards, from `/tail`; the session file is only stat'ed for the 404.
+
+The stage view's working set (`web.working_set`) has its own read, `GET /api/sessions/:id/working_set`: the
+`WorkingSet` projection (`{items, at, running}`: each file, memory and URL live, stale or forgotten, with its tokens)
+of the worker's `/snapshot` messages, else the session file, under the session's LLM context strategy; while a turn
+runs, the snapshot's `working_set` (the running turn's last event, which the messages lag) when it has one. Its live form
+is the `:working_set_updated` event, which always wins over a GET's answer it overtook. The page overlays it on the
+set it builds from its tool rows ([internals/working-set.md](working-set.md)).
+
+A worker without `/tail` (an older chi; `404 not_found`) is read through `/snapshot` in the same
+shape; any other failure (no worker, a 500, a timeout) reads the disk, trimmed to the newest
+turn's records.
+
+Every route goes through `Bridge#dispatch`: an id other than the bridge's own session is
+`404 unknown_session`, and a handler that raises answers `500 bridge_error` (logged as
+`handler_failed`) rather than dropping the connection.
+
+The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
+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
+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:
+`Worker#teardown` marks it too, with `TEARDOWN_LEAVE_WAIT`); a worker whose sidecar names no port or another
+pid than the holder's (a worker that has not written its own yet): `Starting`, `stuck` once it has held the lock
+past `START_LIMIT` (30 s) with none; a sidecar whose `protocol` is newer than `WorkerLink::PROTOCOL`: `Skew` (a
+newer worker; never driven, `wake` answers 409 `worker_newer`); else `Live` (its sidecar; `#client` makes the one
+`BridgeClient`). A sidecar with no `pid` is an older worker's: the lock alone says it is live. `owner:` is the
+holder as the caller already read it (nil: free), so one read serves a summary and its status. `WorkerLink.client` is
+the Live's client or nil; `WorkerLink.await` polls for a new worker's Live (an `until:` check tells a restart's
+successor from the old worker); chi web's `App#worker_link` / `#await_worker_link` wrap them. The Bridge writes
+`pid` and `protocol` with its port and removes its sidecar on stop only when the file still carries its epoch.
+
+`chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
+(503 `not_live` for no worker, a leaving or stuck worker, or an unreachable Bridge; 502 `worker_newer` for skew and
+`bridge_error` / `bridge_secret` for a refused Bridge; 200 only after the Bridge answers; full history of any session
+is served by `GET /api/sessions/:id/output`). It opens the Bridge before answering and gives the one opened socket to
+`App#proxy_stream_body` / `ProxyStreamBody`, which closes it when the body or hijacked client ends. The owner's stream
+is a byte pipe; the body gives it the request's frame filter (`App#stream_filter`: nil for the owner; for a participant, and the owner's participant view
+`?as=participant`, a `Web::ParticipantStreamFilter`, which cuts the Bridge's chunks into frames and writes each again
+from `Web::ParticipantView.event`'s allowlist, dropping every other event; only `from_seq` and `snapshot` reach the
+Bridge; [internals/participants.md](participants.md#what-a-participant-sees)). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
+an earlier worker gets the `reset` snapshot, not a replay.

data/docs/internals/bundles.md

@@ -43,6 +43,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |
 | `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
 | `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
+| `EntrySize` | one memory's size in tokens: `memory.entry_warn_tokens`' crossing note after a memory write, `chi self`'s `big memories` row |
 | `IndexSize` | one scope's memory index as the prompt carries it (tokens, lines, bytes): `memory.index_warn_tokens`' crossing note after a memory write, `chi self`'s summary, the prompt's figures (`SystemPrompt`) |
 | `Placeholder` | `{{placeholder}}` patterns left in an installed memory, one line per file from `Installer#detect_placeholders`; a hint, never a gate |
 

data/docs/internals/context-telemetry.md

@@ -86,7 +86,7 @@ Configuration:
 - `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` / `context.window_tokens`: context window size for when neither the server nor the model's or host's config gives one (step 4 of the lookup below).
 - `models.<key>.window_tokens` / `hosts.<name>.window_tokens` (config file only): the window for one model, or for every model on a host (step 3 below).
 - `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (default `4.0`): heuristic ratio for char-to-token estimation.
-- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` / `context.status_thresholds` (default `20,40,60,80`): comma-separated threshold percentages. They set the buckets, and the buckets' guidance gates the model's own `[CONTEXT: …]` line. (`context.status_cadence` is gone: the event streams on every request.)
+- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` / `context.status_thresholds` (default `20,40,60,80`): comma-separated threshold percentages. They set the buckets, and the buckets' guidance gates the model's own `[CONTEXT: …]` line; the `:context_status` event streams on every request.
 
 The `context.*` settings are read once, when the turn's `ContextStatus` is built, so a change counts from the next turn.
 

data/docs/internals/engine.md

@@ -348,12 +348,12 @@ One iteration with tool calls:
 - For edit and write: diffs the file before and after, and refreshes a memory's index line
   (`MemoryBundle::IndexSync`).
 - Attaches returned images, at most `MAX_IMAGES_PER_RESULT` (4) per result.
-- Scrubs bytes that aren't UTF-8, and caps the output at `max_tool_output_chars` by the tool's `ToolOutputCut`
+- Scrubs bytes that aren't UTF-8, and caps the output at `max_tool_output_chars` (a `memory_read`'s is `memory.read_max_chars`, 0: none, with an overflow guard at half a known window) by the tool's `ToolOutputCut`
   policy: `read` and most tools are cut to their head and end with `[cut: N of M chars; read it in parts]` (N
   kept of M, the whole within the cap unless the cap is shorter than that line); an `execute` result keeps a head
   and a long tail with a gap line between them, its whole output saved in `sessions/<id>/tool_output/`
   (`ToolOutputFiles`, through `KernelLoop#session_dir`, which the Engine sets). See
-  [Tool output guardrails](tool-guardrails.md#the-runners-cut-max_tool_output_chars). The model (both loops), the
+  [Tool output guardrails](tool-output-limits.md#the-runners-cut-max_tool_output_chars). The model (both loops), the
   event and the after_tool_call hook get that text.
 - Emits `:tool_call_completed` {iteration, call_count, call_index, tool, output, output_truncated, output_file,
   activity, images, diff, waited_ms, view, ref, refs}, then fires `:after_tool_call` {iteration, tool, output,
@@ -598,9 +598,12 @@ Where a participant's author (`"p:<id>"`; `Steer.participant_author?`: any autho
   `Worker#run_prompt` checks their link and cap (`participant_refusal`: `participants.json`'s entry and cap against
   `SessionMetrics#spend`) before their turn starts and after it ends (the owner's notice, once per cap). A Continue
   keeps the offer turn's author (`ContinueOffer#run_continue_turn`, from `last_turn.author`).
-- **The gate**: `GuardrailWiring#review_boundary` (`Guardrails::ReviewBoundary`) is the first core check; it reads
-  `#turn_author` and denies a participant's turn all but `Toolkit::REVIEW_TOOLS` (not `forget_outputs`)
-  (docs/guardrails.md). The declared tools stay the session's (D3: no rebuild per author).
+- **The gate**: `GuardrailWiring#participant_boundary` is the core check after the load failures, picked by
+  `#turn_mode`: `Guardrails::PairBoundary` for a pair turn, `Guardrails::ReviewBoundary` for a review one. Both read
+  `#turn_author` and are no-ops for the owner's turns; the review boundary denies a participant's turn everything
+  outside `Toolkit::REVIEW_TOOLS` (not `forget_outputs`), the pair boundary denies secrets, owner-voiced tools and
+  `ask_user_question` and always asks before a write that may land outside the project (docs/guardrails.md).
+  The declared tools stay the session's (D3: no rebuild per author).
 - **Hooks and plugins**: `Engine#turn_author` (the running turn's participant author, nil otherwise) is the hook
   runtime's `turn_author` (`Hooks::Registry#with_runtime` adds `author:` to every event of such a turn) and the
   plugin host's (`ctx.turn_author`).
@@ -719,7 +722,7 @@ loops). It is display-only and never reaches the wire (prompt-caching.md, rule 7
 model's opens, never from `QuestionDesk`: `Engine#request_question` (the kernel's `question_handler`, after
 `AskUserQuestion.validate`; not with `interface == :non_interactive`) and the guardrail wiring's `ask:` lambda
 (`GuardrailWiring#request_approval`, after a stored approval and the non-interactive deny). So `ask_for_hook`, a
-relayed approval (`EnginePeers#open_question` → `Engine#open_question`) and `post` (the step-limit question) never
+relayed approval (`Engine::RelayPeer#open_question` → `Engine#open_question`) and `post` (the step-limit question) never
 fire it. `QuestionAsked.fire` is a no-op without a subscriber (`Registry#any?`); else it finds the live
 conversation's last `role: "model"` entry (`Engine#live_conversation`, one lookup for both loops: a ChatLoop batch may
 end in a tool result), builds an `AnswerRefs` on that step alone with the question caps (50 / 32 KiB), fires with the
@@ -752,16 +755,12 @@ step's text ([architecture.md](../architecture.md), the `display_refs` paragraph
 `ToolRunner` asks the kernel's `Guardrails::Gate` (set by the Engine from `GuardrailWiring`) before each call;
 the gate is not itself a hook. `Gate#evaluate` fires the `:before_tool_call` hooks (the voters, e.g. the
 known-names bundle or a config hook), which vote through `event[:guardrail]` (`deny!`, `ask!`) or the legacy
-`event[:blocked]` flag. A deny stays a deny for the hooks after it. Then the core checks run on the final call,
-in `GuardrailWiring#checks` order:
-
-1. load failures (`Guardrails::LoadFailures`): a required hook or rule file that failed to load denies every call;
-2. `rules.hook_asks`: with guardrails disabled, a hook's ask is dropped (a deny still applies);
-3. protected paths;
-4. `ScratchWrites` (a `chi scratch` session only): write and edit under the memories folder are denied;
-5. `ChildBoundary` (a delegate child only): a change outside its folder asks;
-6. the rules (config and bundles, e.g. the guardrails bundle's `rules.yml`; a rule can match the tool, its
-   targets and the model).
+`event[:blocked]` flag. A deny stays a deny for the hooks after it; a hook's ask is dropped when guardrails are
+disabled. Then the core checks run on the final call in `GuardrailWiring#checks` order
+(`lib/samagotchi/guardrail_wiring.rb`): the load failures first, then the participant's boundary
+(`participant_boundary`, `PairBoundary` for a pair turn else `ReviewBoundary`), then the hook asks, the protected
+paths, the scratch writes, the delegate child's boundary, the rules. That method is the order; it is not spelled
+out here so this page can't drift from it.
 
 A gate that raises denies the call.
 
@@ -795,6 +794,13 @@ Engine
 
 Both loops:
 
+- <a id="a-reply-that-is-only-a-tool-call"></a>**A reply that is only a tool call** (`LLM::StrayToolCall`, `LLM::ChatLoop` only): a reply with no tool
+  calls whose whole text is one closed tool-call block, which the host couldn't read, isn't an answer. A reply opening with prose or a fence stays
+  an answer, and the check is one string test on a normal one. Nothing is guessed from the block and it never enters the history (`:generation_completed`
+  and `:after_generation` have already seen the text): `:generation_retrying` with `restarted` voids the streamed text, `:empty_answer_retry` with
+  `malformed` goes out, and a hidden `TurnNote.malformed_retry` asks again at the retry temperature. It has its own budget, so `retry.empty_answer: 0`
+  doesn't turn it off, and a real tool call resets it. Two in a row fail the turn with `LLM::MalformedGeneration`, keeping its earlier steps. Each is
+  logged as `generation_malformed` with the shape, finish reason, served model and the text's tail. `KernelLoop` has its own path (`ToolCallParser#malformed`).
 - **Empty-answer retry** (`EmptyAnswerRetry`): a generation with no visible text and no tool calls is asked
   again, up to `retry.empty_answer` times (at most 3), with a hidden nudge (`TurnNote.empty_retry`) on the tail.
   The retry request runs at temperature 0.6 when the configured sampling sets no temperature; a configured one
@@ -884,7 +890,7 @@ Paths are under `lib/samagotchi/`.
 | `llm/native_backend.rb` | Wraps KernelLoop as a backend (`#complete` calls `#run`) |
 | `llm/model_result.rb` | `LLM::ModelResult`, what a backend returns |
 | `tool_runner.rb` | Per-call path (gate, start/complete events, output cap, images, diffs) |
-| `tool_output_cut.rb`, `tool_output_files.rb` | `ToolOutputCut`: how a tool's output longer than `max_tool_output_chars` is cut, by the tool's policy (`POLICIES`; `:head` for a tool with none); `ToolOutputFiles`: the whole output of an execute cut that way, saved in the session's `tool_output/` folder ([tool-guardrails.md](tool-guardrails.md)) |
+| `tool_output_cut.rb`, `tool_output_files.rb` | `ToolOutputCut`: how a tool's output longer than `max_tool_output_chars` (a `memory_read`'s: `memory.read_max_chars`) is cut, by the tool's policy (`POLICIES`; `:head` for a tool with none); `ToolOutputFiles`: the whole output of an execute cut that way, saved in the session's `tool_output/` folder ([tool-output-limits.md](tool-output-limits.md)) |
 | `tool_row_fields.rb`, `row_refs.rb` | `ToolRowFields`: a tool row's fields beyond its params (`ACTIVITY_KEYS`, `EVENT_KEYS`), the same live and on a reload; `RowRefs`: a plugin tool's row refs (`refs:`), checked, capped and saved with the result |
 | `tool_response.rb` | Per-batch dispatch and tool_response entries (joined for native, single for chat) |
 | `empty_answer_retry.rb` | The empty-answer and cut retry budget |
@@ -914,5 +920,5 @@ Paths are under `lib/samagotchi/`.
 | `worker_wakes.rb` | `WorkerWakes`: a worker's wake budget for the turns nobody typed (`session.max_wakes`) |
 | `task_watch.rb`, `task_finish_note.rb` | `TaskWatch`: the background tasks a worker's session started that the model hasn't seen finish; `TaskFinishNote`: the note one leaves when it does ([background-tasks.md](background-tasks.md#finish-wake)) |
 | `side_usage.rb` | `SideUsage`: one side request's usage (a recap, `ctx.ask_model`), folded into the session's side sums (`:side_usage`) |
-| `bridge/client_event.rb` | `Bridge::ClientEvent.project`: what an SSE client gets for an engine event ([architecture.md](../architecture.md)) |
+| `bridge/client_event.rb` | `Bridge::ClientEvent.project`: what an SSE client gets for an engine event ([bridge.md](bridge.md)) |
 | `guardrails/parent_policy.rb` | `Guardrails::ParentPolicy`: which options of a question a parent agent may pick (`guardrails.parent_answers`) |

data/docs/internals/participants.md

@@ -1,11 +1,12 @@
 # Participants: identity and routes
 
 A session's owner can invite **participants** to review it: people, or agents, who reach that one session through
-chi web with a link of their own. This page is the identity layer (the shared-sessions plan's P2): grants, the gate,
-the routes a participant reaches, and what is written where; and their **review turns** (P3b): queued, read-only,
-limited and capped; and what they **see** (P4a): 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" and "review", never "shared": `session.shared` already means "attached by default".
+chi web with a link of their own. This page is the identity layer: grants, the gate, the routes a participant
+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".
 
 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,
@@ -43,9 +44,9 @@ participant** and **one role**, until it expires or is revoked.
   newer chi's: read (its links work, but a grant with keys this chi doesn't know is left out: such a key may
   restrict it, so it fails closed) and never written (`Grants::Newer`, one message saying to update chi; a revoke
   the gate can't write still refuses the grant). A grant's keys this chi doesn't know are kept on a rewrite
-  (`Grant#extra`), so a field a later chi adds the omit-if-default way survives. A chi from before the version check
-  doesn't look at it: **mixed installs** on one state dir are a hazard, as a chi before 0.109 (no `identity`) rewriting
-  the store unbinds every grant, and one before this change drops unknown keys. A stored `identity` that isn't one
+  (`Grant#extra`), so a field a later chi adds the omit-if-default way survives. **Mixed installs** on one state dir
+  are a hazard: an older chi that doesn't know `identity` unbinds every grant when it rewrites the store, and one
+  that doesn't keep a grant's unknown keys drops them. A stored `identity` that isn't one
   `#issue` would write (`false`, `""`, a list, upper case) makes the store Corrupt (fails closed). Readers follow its mtime (a `chi share revoke` in another process takes effect at chi web's next request).
   `last_used_at` is written at most once a minute per grant. **chi web refuses to start** when that folder or file can
   be read by another user, or isn't this user's (`Grants.check_permissions!`, one message naming the `chmod`). Only
@@ -648,7 +649,7 @@ invited to has none: its files stay byte for byte as they were.
   expires_at, removed_at, cap}]}`, rewritten by whoever changes a grant (chi web, `chi share`), inside the grants
   store's lock (`Grants#update`'s `on_write`), so two writers can't finish out of order and lose a revoke here. Never
   a token or a digest.
-  The worker reads it with `Participants.read` (P3a's system-prompt line, `ctx`).
+  The worker reads it with `Participants.read` (`SessionParticipants#refresh!`, for the system prompt's participants line).
 - **`participants.jsonl`** (0600, append-only, `Participants.log`): one JSON line per event, with `at`: `issued`
   (participant, name, kind, role, expires_at), `revoked` (participant, by), `expired` (the first refused use after the
   expiry, once per chi web), `peer` (the first use and each new peer since chi web started: ip, user agent; behind a
@@ -668,8 +669,8 @@ invited to has none: its files stay byte for byte as they were.
 
 What a participant writes is marked as theirs everywhere it is kept or sent. The
 author is `"p:<id>"` (`Grant#author`), stamped by chi web from the principal and never taken from a body. Absent
-means the owner: old sessions and every owner path read as the owner's, byte for byte as before (a pre-P3 session
-fixture loads and saves unchanged, `spec/turn_author_record_spec.rb`).
+means the owner: a turn or session with no author keys reads as the owner's and gains none on save
+(`spec/turn_author_record_spec.rb`).
 
 - **Messages.** A participant's opening message is saved raw with `author`, `author_name` (the name the sidecar gave
   the participant when it was written) and `participant_mode` (`ParticipantMode.of` when `Engine#run_turn` builds it, before any request carries it). Merged input and
@@ -741,7 +742,7 @@ participant TUI in v1.
   worker announces `:participants_changed` (`Engine#announce_participants`: `{participants: [{id, name, kind}],
   joined: […], left: [{…, reason: revoked | expired}]}`) to every UI; its start announces nobody. "Joined" means
   invited: participants have no presence of their own yet. `session_state_snapshot`'s `participants` names who is in
-  the review now, so a UI that joins has them. Owner frames only: no participant stream carries them (P4a's filter).
+  the review now, so a UI that joins has them. Owner frames only: no participant stream carries them (`Web::ParticipantView`).
 - **Lines.** A participant's prompt (`turn_enqueued`'s `author`, an origin's, a queued row's, a saved message's
   `author` / `author_name`) is led by their name (`Formatting#participant_prefix`: `Alex ▸ review>`, cleaned by
   `ParticipantName`, the id when the TUI knows no name), in a colour picked from their id. Each change is one line per

data/docs/internals/remote-sessions.md

@@ -7,7 +7,7 @@ sessions, workers, memories and code stay on that machine; this one only sends r
 User-facing behaviour is in [cli.md](../cli.md#remote-sessions). This page is the code's shape, for changing it.
 
 **The one rule:** the remote side is that machine's **chi web**, never a worker's Bridge. Bridges stay on loopback,
-and answer only a request that names their secret from `bridge.json` ([architecture.md](../architecture.md)).
+and answer only a request that names their secret from `bridge.json` ([bridge.md](bridge.md)).
 chi web answers each request by calling the same `SessionAccess::Local` operation the CLI would call there.
 
 ## The seam: `SessionAccess`

data/docs/internals/{tool-guardrails.md → tool-output-limits.md}

@@ -58,7 +58,7 @@ Implementation note:
 
 ## The runner's cut (`max_tool_output_chars`)
 
-After a tool's own limits, `ToolRunner` caps every result at `max_tool_output_chars` (default `10000`
+After a tool's own limits, `ToolRunner` caps every result but a `memory_read`'s at `max_tool_output_chars` (default `10000`
 characters, both loops). How a longer one is cut is the tool's policy, `ToolOutputCut::POLICIES` (by the
 built-in name; a tool with none gets `:head`):
 
@@ -67,7 +67,26 @@ built-in name; a tool with none gets `:head`):
 | `execute` | `:head_tail_file` | a short head, a long tail, one gap line between them; the whole output saved in the session's folder |
 | `task_wait` | `:head_tail_ref` | the same head and tail, the gap line naming the task's log (`output_path`, `Tools::RefText`); nothing saved |
 | `delegate`, `delegate_result` | `:head_tail_ref` | the same, the gap line naming the child's reply file (its `output/<timestamp>.txt`); nothing saved |
-| `read` and every other tool (`task_get`/`task_list`/`task_create`/`task_stop`, `web_fetch`, `memory_read`, `context_read`, plugin and MCP tools) | `:head` | the first chars, then `[cut: N of M chars; read it in parts]` |
+| `read` and every other tool (`task_get`/`task_list`/`task_create`/`task_stop`, `web_fetch`, `context_read`, plugin and MCP tools) | `:head` | the first chars, then `[cut: N of M chars; read it in parts]` |
+| `memory_read` | `:head`, its own cap | not cut by `max_tool_output_chars`; see below |
+
+`memory_read` is the one tool `max_tool_output_chars` does not cap, in any form (a name, a comma list, a blank name for the
+indexes): a memory is read whole, since a model that needs the skill pays for all of it anyway. `ToolRunner#output_cap`
+resolves the cap per call, so both loops get it (they both come through `ToolResponse.run_batch`). Two things can still
+cut a `memory_read` result, both with the same `:head` cut and a line that says where the rest is, since `memory_read`
+has no parts to read:
+
+- `memory.read_max_chars` (default `0`: none). A positive value caps the result at that many characters.
+- The overflow guard, with `memory.read_max_chars` at 0: a result over half the model's context window (in characters,
+  tokens x `context.chars_per_token`) is cut. A context overflow is a hard failure (`LLM::FailedTurn.keeps_work?` is
+  false), so the turn's work rolls back and a retry would repeat the same read. The window is the loop's own:
+  `KernelLoop#tool_output_window` (the client's probe, the turn's `window_tokens` setting), or for `LLM::ChatLoop` its
+  adapter's model list too (`ToolRunner.new(kernel, window:)`). An unknown window (`ContextWindow` falling back to
+  its default) has no guard. It checks this one result, not the context already used.
+
+The line is `[cut: N of M chars; the rest is in the memory's .md file in <the memories dir(s) searched>: read it with
+start_line]` ("the memories' .md files" for a comma list or the indexes). `ToolOutputCut::HEAD_CUT` does not match it.
+`read` on a memory's file keeps the `max_tool_output_chars` cut: it has line ranges.
 
 `:head_tail_file` is for output whose end matters: a test run's summary, an error, the `exit:` line. The head is
 `execute.cut_head_chars` at most (default `1000`) and never more than a quarter of the room; the tail gets