samagotchi 0.170.0 → 0.171.0

data/docs/internals/participants.md

@@ -175,17 +175,20 @@ row answers another session's id 404, so a new route is covered without a new ex
 
 | Route | Permission | A participant gets |
 |---|---|---|
-| `POST /api/sessions/:id/turn` | participant | a queued review turn of their own ([Turns](#turns)) |
+| `POST /api/sessions/:id/turn` | participant | a turn of their own, or a line into their own running turn at its next step ([Turns](#turns)) |
+| `POST /api/sessions/:id/cancel` | participant | their own running turn stopped, named by its `turn_id` ([Turns](#turns), Stopping their turn); no `turn_id`, the owner's turn or another participant's: 403 `not_permitted`, audited |
 | `POST /api/sessions/:id/turn/:eid/dequeue` | participant | their own queued turn back; another's (the owner's included) is 403 `not_permitted` |
 | `GET /api/sessions/resolve?id=` | participant | their session for its id or a prefix of it; anything else 404 as no session (never an ambiguity listing others) |
 | `POST /api/sessions/:id/wait/prepare`, `…/wait` | participant | only for a turn of theirs (`turn`: the enqueued id `POST …/turn` answered; else 403); `wait/prepare` answers only what that wait needs, `{session_id, baseline: {last_turn}, known_turn, live, last_turn_id}` (`last_turn_id` only when it is their turn), never the owner's cursor, message count, question or running turn; the answer trimmed to `{status, text, turn_id, outcome, cancel_reason}`, the reply's `text` through `ParticipantView.reply` (no thinking or tool call, redacted) and any other text (an error's exception, a failed turn's summary) `ParticipantMessages::TURN_FAILED`; a question or approval their turn raised, or their turn held by the owner's step-limit Continue offer ([Turns](#turns)), is `{status: "waiting_for_owner", detail: "waiting for the session's owner"}` with nothing of it; a revoke or the expiry ends a `wait` already running (401 `token_revoked` / `token_expired`), as it ends their stream |
-| `GET /` | participant | the participant page's shell (`participant.html`, its body's `data-session` and `data-name` the grant's; `participant.js` reads the rest through the two routes below). Never the owner's page, where every route would refuse them. |
-| `GET /api/sessions/:id/review` | participant | the page's data, filtered ([What a participant sees](#what-a-participant-sees)): `{viewer, session: {id, title, status}, subjects, participants, messages, current_turn, waiting_for_owner, queued: {mine, others}, last_event_id}`; a participant's `viewer` has their `usage` |
+| `GET /` | participant | the main page (`index.html`) stamped for them (`App#participant_index_data`: their viewer, the grant's session and its title; [web-frontend.md](web-frontend.md#the-participants-page)); the page reads the rest through the show and the stream below |
 | `GET /api/sessions/:id/stream` | participant | the session's stream through `ParticipantStreamFilter` (only `from_seq` and `snapshot` reach the Bridge); it ends within a poll of a revoke or the expiry |
+| `GET /api/sessions/:id/working_set` | participant | the working set's project files only (`ParticipantView.working_set`), with `running` |
+| `POST /api/sessions/:id/images` | participant | their upload ([Participant images](#participant-images)): refused at their cap, past their attempts or quota, a bmp/tiff/heic; the reply `{file, name, width, height}` |
+| `GET /api/sessions/:id/images/<name>` | participant | only an image they uploaded, `Cache-Control: no-store`; any other the 404 a missing file gets |
 | `GET /api/info` | participant | `{app, version, features}` (what `SessionAccess::Remote`'s check needs); not `pid`, `cwd`, `lan`, `installed` |
-| `GET /api/sessions/:id` | participant | their session only, whatever the query (`brief`, `cards`, `tail`, `timing`): `{session: {id, title, status, participants: [{id, name, kind, role}]}}` (the active ones). `title` is the session's own title, or "an untitled session": never `display_title`'s fallback, the first prompt's opening words |
+| `GET /api/sessions/:id` | participant | the main page's show in the owner's shape, every part filtered (`Web::ParticipantShow`, [The main page's show](#the-main-pages-show)); `?tail=1` and `?timing=1` filtered, `?cards=1` `{cards: []}`; `?brief=1` (what `SessionAccess::Remote#show` reads) `{session: {id, title, status, participants: [{id, name, kind, role}]}}` (the active ones). `title` is the session's own title, or "an untitled session": never `display_title`'s fallback, the first prompt's opening words |
 
-Everything else is `:owner`: `/answer`, `/command`, `/images` (an image a prompt carried is "[image]" on their page),
+Everything else is `:owner`: `/answer`, `/command`,
 `/output` (the raw replies), the hub's `/api/events`, the cap route. Static assets (`/app.js`, …) are served to any principal past the gate: they are the public frontend.
 
 ## Turns
@@ -219,34 +222,65 @@ The worker decides it once at the turn's start (`GuardrailWiring#begin_turn` →
 (`participant_mode`), the boundary in `GuardrailWiring#checks`, `ToolRunner#unreached_group_refusal` (through
 the call's `TurnContext`: a review turn's boundary words the refusal; a pair turn gets the owner's), the
 mid-turn stop and the cap notice's words. The system prompt's line is the pair one once an active participant is
-stamped pair (`SessionParticipants#prompt_mode`); the participant page's `viewer.mode` is their own grant's
+stamped pair (`SessionParticipants#prompt_mode`); their show's `viewer.mode` is their own grant's
 (`ParticipantMode.live_for`).
 
 A participant's `POST /api/sessions/:id/turn` (`ParticipantAccess#handle_participant_turn`) takes only the body's
-`prompt`. Three layers keep it a participant's own turn, inside its mode's boundary.
+`prompt`, `delivery` and `images` (refs to their own uploads). Three layers keep it out of anyone else's turn, inside its mode's boundary: it goes into a
+running turn only when that turn is theirs (at its next step, as the owner's message does), else it runs as a turn
+of its own after it.
 
 **chi web.** The author is the grant's (`p:<id>`) and the client id `review:<id>` (`ClientId.review`: a human's
-input, origin `review`, source `participant`, labelled `review`); the body's `client_id`, `author`, `delivery`,
-`no_interrupt` and `images` never count. Refused before delivery, each audited:
+input, origin `review`, source `participant`, labelled `review`); the body's `client_id`, `author` and
+`no_interrupt` never count, its `images` only as refs to their own uploads, and its `delivery` only as `queue` or
+next step (none: next step).
+Refused before delivery, each audited:
 
 - a line starting `!` or `/` (after leading spaces): 403 `not_permitted`, so no shell line, session command or
   plugin command (v1);
-- images: 403 `not_permitted` (D10);
-- the grant's cap: 429 `cap_reached`, from the session's saved analytics (`SessionMetrics.saved_spend`).
-
-It goes out as `delivery: queue` (D6) with `pending_limit` = the grant's queue limit + 1 (the running one), never
+- a cut (`delivery: cut`): 403 `not_permitted`: a participant's message never cuts a generation;
+- the grant's cap: 429 `cap_reached`, from the session's saved analytics (`SessionMetrics.saved_spend`);
+- a Revise draft (`revises: {turn_id}`, `ParticipantAccess#participant_revise_refusal`): a live worker without
+  `participant_revise` (`ReviseAnchor::PARTICIPANT_FEATURE`): 409 `revise_unavailable` in
+  `ParticipantMessages::REVISE_UNAVAILABLE` (never `ReviseAnchor::UNAVAILABLE`'s owner words, which
+  `#participant_turn_result` also maps for a worker without Revise at all); then `ParticipantRevise.refusal` over the
+  messages a live worker's snapshot has (`show_reads(...).raw_messages`: the file lags it mid-turn and just after a
+  turn's end), the file's only with no live worker. The turn must open with their prompt (the author chi web
+  stamped), have an answer and not be a Verify turn, else 403 `revise_not_own` (a missing turn id answers the same:
+  no existence oracle); every turn opening after it (`ParticipantRevise.opening?`: not the owner's `!` lines, which
+  they never see) must be theirs too, else 409 `revise_overtaken`. The audit line names the turn id (`revises`),
+  accepted or refused. The worker checks the same rule again at the stamp (`TurnStages::VerifyAnchors#revision_target`,
+  up to the Revise turn itself): one overtaken after the send silently becomes a plain turn (it runs and answers, no
+  stack, no notice to them or the owner), logged only as `revise_anchor_rejected`. `SessionManager::Delivery` also
+  refuses a participant's Revise to a live worker without `participant_revise` (`ReviseAnchor::PARTICIPANT_UNAVAILABLE`);
+- images (`ParticipantImages#participant_images_refusal`, D10 lifted), in this order so nothing tells them which
+  files exist: not a list of at most 20 `{file, name}` refs (no `path`): 400 `bad_images` (`IMAGES_SHAPE`); any
+  ref they didn't upload (`ParticipantUploads`, read once), whether its file is there or not: 403 `not_permitted`;
+  only then the files (`ImageStore.check_refs`; one of theirs gone: 400 `bad_images`, `IMAGE_GONE`, the file named
+  only in the audit line); then the model: 422 `no_vision` in `ParticipantMessages::NO_VISION` when chi send's
+  check (`SendCommand.vision_answer`) says it takes no images (its full words, which name the model and `/model`,
+  only in the audit line's `detail`). The check reads the session's saved model, which can lag a live `/model`;
+  the Engine's own no-vision failure stays the backstop (their turn then fails, `TURN_FAILED`). Their refs go to
+  `deliver_turn` as `images:`; the turn's audit line counts them (`images`), accepted or refused by the worker.
+
+It goes out with that delivery and `pending_limit` = the grant's queue limit + 1 (the running one), never
 into the owner's prompt history. The Bridge counts the author's running and queued turns under its event lock and
 answers 429 `too_many_turns` past it; with no worker, their waiting input files are counted, and the new one
 written, under the session dir's `participants.lock` (`SessionManager.deliver_turn`), so two at once can't both
-pass. The ack is 202 with
-`delivery: "queue"`; chi web keeps enqueued id → grant (the last 1000), which `dequeue` and `wait` check, falling
+pass. The ack is 202 with the worker's
+`delivery` (`queue`: a turn of its own; `next_step`: into their running turn, or the next turn of an idle worker; a
+file, with no worker yet, reads `queue`); chi web keeps enqueued id → grant (the last 1000), which `dequeue` and `wait` check, falling
 back after a restart to the author the session's files keep (`ParticipantAccess#turn_author`): the waiting or claimed
 input file's, then `last_turn`'s or the settled record's (a refused turn's, `TurnCheckpoint.record_refused`; one whose
 worker died, `TurnCheckpoint.settle`, from its checkpoint mark's `author`).
 
-**The worker.** A participant's input file waits for its own turn whatever its delivery says
-(`SessionInbox.waits_for_turn_end?`), so a drain never merges it into another author's turn; the Bridge queues their
-`POST /turn` whatever it asks and never cuts for it; a participant's `/word` or `!line` is refused by the Bridge (403)
+**The worker.** A participant's input file goes into a running turn only of its own author
+(`SessionInbox.waits_for_turn_end?` / `turn_end_data?` with the running turn's participant author, which the worker
+keeps from the turn's origin, `Worker#@turn_author`), so a drain never merges it into another author's turn, and a
+participant's turn takes nobody else's line; the Bridge queues their `POST /turn` unless their own turn runs
+(`Bridge#same_author_steer?`, under the event log) and never cuts for it; a line merged into their own turn first
+gets the checks their queued turn gets at its start (below: the link, the cap), and one refused is dropped as that turn
+would be, never merged; a participant's `/word` or `!line` is refused by the Bridge (403)
 and dropped from the worker's file path. A participant's turn goes only to a worker that names the `review_turns`
 feature (409 `review_unavailable` otherwise: it has no boundary; restart it), and never as a file while a worker
 that may be older holds the session (504 `worker_timeout`: send again). Before a queued participant turn starts, the
@@ -260,14 +294,29 @@ Verify turn's anchor (`VerifyAnchor`, `{turn_id, quote}`: a UUID and a quote of
 anchor, or a Verify fresh check, sent to a connected worker without it is refused 409 `verify_unavailable`
 (`VerifyAnchor::UNAVAILABLE`: "restart this session to use Verify"; `SessionManager` checks `worker_has?` before it
 delivers, on the features of the sidecar its client was made from), since an older worker would run it as a plain prompt. A session with no connected worker is not gated: the
-worker that starts for it is current. The participant page's session summary carries `verify_unavailable`
-(`VerifyAnchor.worker_unavailable?`, from the worker's features; `participant_review.rb`), and the page disables
+worker that starts for it is current. A participant's show carries `session.verify_unavailable`
+(`VerifyAnchor.worker_unavailable?`, from the worker's features; `participant_show.rb`), and the page disables
 Verify and Verify fresh with a "restart this session" hint.
-**The owner's input during a review turn queues.** While a participant's turn runs, the owner's input never merges
+**Their message during their own turn goes in at its next step.** A worker names `participant_steer`
+(`Delivery::OWN_TURN_STEER_FEATURE`) when it does; one without it queues every participant message, which is safe by
+construction, so the feature only says what will really happen (chi web's ack, the page's delivery line). A
+message sent while someone else's turn runs (the owner's, another participant's) queues behind it as their own turn.
+
+**Stopping their turn.** `POST …/cancel` from a participant (`ParticipantAccess#participant_cancel`) names the
+turn by its `turn_id`: chi web reads the live snapshot's running turn, requires it to be that turn and theirs (its
+author the grant's), and asks the worker to cancel that turn id (`BridgeClient#cancel(turn_id:)`), which
+`TurnState#cancel!` compares under its lock (409 `turn_mismatch`): a turn that ended and gave way to another
+person's between the read and the cancel is never stopped. Without a `turn_id` (the Bridge would cancel whatever
+runs), or for a turn not theirs, it is 403 `not_permitted`, audited. It is relayed only to a worker that names
+`cancel_turn_id` (`Delivery::CANCEL_TURN_ID_FEATURE`): an older one ignores the id and would stop whatever runs, the
+owner's next turn too, so it is 409 `cancel_unavailable` (`ParticipantMessages::CANCEL_UNAVAILABLE`), audited, until
+the owner restarts it. The reason is the server's (`user`), never the body's.
+
+**The owner's input during a participant's turn queues.** While a participant's turn runs, the owner's input never merges
 into it, from any client (the web, an attached TUI, `chi send` without `--queue`): the Bridge's `POST /turn` makes it
-`delivery: queue` whatever it asked, so it never steers or cuts (`TurnAccumulator#participant_turn?`, under the event
-lock), and its ack and `:turn_enqueued` say `queue`; the worker's drain takes no input file during a participant's
-turn (`Worker#pending_input_drain`, for a file the Bridge never saw), so each runs as the owner's own turn after it.
+`delivery: queue` whatever it asked, so it never steers or cuts (`Bridge#same_author_steer?`, under the event
+lock), and its ack and `:turn_enqueued` say `queue`; the worker's drain takes only the participant's own lines
+during their turn (`Worker#pending_input_drain`, for a file the Bridge never saw), so each runs as the owner's own turn after it.
 The web's delivery line says so (`participantTurn`: Enter queues, no cut), the TUI prints its queued note, `chi send`
 says `(queued: runs after the current turn)` and its `--wait` waits for that turn (`ReplyWait::Target.message`). The owner's
 own turns steer as before. A step-limit Continue of a participant's turn (the owner answers it) continues as theirs: its origin (a `TurnOrigin`,
@@ -283,8 +332,9 @@ turns run in the order they came, each through the link and cap check above as i
 offer too and so releases them. A held file isn't queued input for the idle-exit policy (`Worker#input_pending?`): `/exit`
 and `chi sessions restart` name what waits, the offer (`continue_offered`), not a queued prompt. The offer lives in
 the worker: a worker that restarts has none, and runs them.
-Their `wait` always waits as for a queued turn of theirs, never for the next reply past a cursor (which could be
-anyone's); on a held turn it answers `waiting_for_owner` (`ReplyWait::Poll#held`), the offer asked before the wait
+Their `wait` waits on their turn's id, never for the next reply past a cursor (which could be anyone's); a line
+merged into their own running turn is followed into it by its merge record (`ReplyWait::Poll#follow_merge`: chi web
+waits with `queued: false`, and the poll asks `turn_end_data?` as for its author's own turn); on a held turn it answers `waiting_for_owner` (`ReplyWait::Poll#held`), the offer asked before the wait
 began too. A chi client gets it through `--remote` with a participant's token in `remotes.yml`: `chi --remote NAME
 send --wait --turn T ID` reaches only participant routes (resolve, `wait/prepare` and `wait` on their turn), and
 `ParentReport` reads `waiting_for_owner` as its own status, exit 3 like a question, its detail
@@ -337,14 +387,54 @@ and `ctx.turn_author` names it ([hooks](../hooks.md#participants-turns)).
 participant once the grant is revoked or expired, so their stream closes within a poll of a revoke, including one
 made by `chi share revoke` in another process; the page then reads a 401 and shows the ended-link page.
 
+## Participant images
+
+A participant attaches images to their own turns, as the owner does (`Viewer::PARTICIPANT_CAPABILITIES`' `images`:
+the composer's paste, drop and image button). Review and pair grants alike: an image is input, not tool power; their
+cap and the quota bound the cost (their turn's image tokens count to their cap by author, `SessionMetrics.saved_spend`;
+later turns that re-send it in history are the owner's). `ImageStore` is content-addressed and keeps no metadata, so
+who uploaded what is chi web's own record, `ParticipantUploads` (`participant_images.json`, [Files in the session
+dir](#files-in-the-session-dir)), keyed by (file, grant): an owner's or another grant's identical image never
+changes hands, and nothing else (a ref's `source` or `name`, the body's `author`, a message) grants a file.
+
+**Upload** (`POST …/images`, `ParticipantImages#participant_image_upload`). Every upload counts as an attempt first,
+before the cap check (a cap-refused one too). Refused, in order: their cap (429
+`cap_reached`); past `Grants::MAX_IMAGE_ATTEMPTS` (80) uploads tried, refused ones counted (429
+`too_many_image_attempts`); the owner's size cap (413 `too_large`); not an image chi stores (422 `bad_image`, in
+`ParticipantMessages::BAD_IMAGE`, never `ImageStore`'s words: an image tool's output may name a host path); a
+bmp, tiff or heic (422 `unsupported_image`, `IMAGE_TYPE`: sniffed with `ImageHeader.read` before `ingest`, so sips
+or magick never converts their bytes from those formats); a header with no size, or over 40 megapixels or 12000 px
+on a side (422 `image_too_big`, `IMAGE_TOO_BIG`; a phone's 4032×3024 passes); at `Grants::MAX_IMAGES` (40)
+distinct files (429 `too_many_images`), unless the bytes are a file they own already (as stored unchanged,
+`ImageStore.file_name_for`: a downscaled or re-encoded one is refused). A png/jpeg/gif/webp over the store's limits
+is still downscaled by `ImageStore.fit`, so the tool does read their bytes: their conversions run one at a time
+(`@participant_conversion_mutex`), and every conversion (anyone's) is killed past `ImageResizer::TIMEOUT` (60 s),
+magick reading the sniffed format's coder under `-limit memory 256MiB -limit disk 1GiB -limit area 64MP`. An
+upload that raises is audited (`internal_error`) before chi web's 500. The quota is checked under `@participant_images_mutex`, the
+image ingested, then checked again and recorded under it (a race past it is refused there; the stored file may stay
+in `images/`, unreachable to them). Each answer is an `image` audit line. The reply is the ref without `source`,
+`mime` or `bytes`.
+
+**Read back** (`GET …/images/<name>`, `SessionControl#handle_image`): a participant gets the file only when
+`ParticipantUploads.owned?` says they uploaded it (the record proves they had the bytes), with `Cache-Control:
+no-store`; anything else (the owner's, another grant's, a guess) is the same 404 a missing file gets, body and
+headers alike. A revoked or expired grant is refused by the gate (401) as on every route.
+
+**Their turn** takes only refs they uploaded ([Turns](#turns)); **what they see** is their own images as thumbnails
+and anyone else's as "N images" ([What a participant sees](#what-a-participant-sees)). A corrupt or unreadable
+record fails closed (every grant at quota, owning nothing, `Log.warn`); the owner can delete the file. Not covered:
+a participant's `chi --remote … --image`; a failed turn of theirs gives the text back without its chips; Apply
+doesn't mention a proposal's images.
+
 ## What a participant sees
 
-D5 (a): prompts and replies with their authors, one-line tool rows, turn boundaries, the queue and waiting states.
+D5 (a): prompts and replies with their authors, one-line tool rows, turn boundaries, the queue and waiting states
+(and for what kind of thing: an approval, a question, a continue offer); for the main page (2026-11-13) also the
+context's fill, the speed, each turn's time and the working set's file names.
 Not tool output or arguments, thinking, approvals' and questions' content, memories (text or names), context notes,
-plugin steers, automatic and delegate input, cards, command output, the working set (the user decided: not), cost
-(but their own usage, as their grant's exposure shows it),
-timing (durations, records: only the wall time `at` of each prompt, reply and turn start, for the page's gap lines
-and hover times, D6 of the session-time-gaps plan), host paths or the owner's prompt history. Every read a participant reaches goes through one module,
+plugin steers, automatic and delegate input, cards, command output, the working set's memories and URLs, cost
+(but their own usage, as their grant's exposure shows it), tokens and cost per model, guardrail judgments,
+host paths or the owner's prompt history. Every read a participant reaches goes through one module,
 `Web::ParticipantView` (`lib/samagotchi/web/participant_view.rb`), whose every answer is a new hash built from named
 fields: a field added to an event later reaches nobody until it is named there.
 
@@ -354,12 +444,18 @@ fields: a field added to an event later reaches nobody until it is named there.
   type and turn id; `turn_completed` may also carry an allowlisted verdict card), `generation_chunk` (its visible
   `text` only; a thinking-only chunk is dropped),
   `generation_retrying` (`restarted`), `tool_call_started` (the tool's name, and for a file tool the path relative to
-  the session's folder when it is inside it; never when that folder is home or `/`), `tool_call_completed` (its status word), and bare markers (the type
-  alone) for the queue (`turn_enqueued`, `turn_dequeued`, `input_merged`), the owner's question, approval or Continue
-  offer and their answers, and `snapshot` / `reset`: the page re-reads its review data at each (the latest read
-  wins), draws no live event from a turn's start or end until that re-read, and then streams again from the data's
-  `last_event_id`, so the events after its snapshot replay onto it; a read that fails (unreachable, a 5xx) keeps the
-  page and is retried with a backoff under a "retrying" line. Refusals show the server's `detail`. Every other type,
+  the session's folder when it is inside it, as the owner's `ref`
+  `{kind: "file", path, line, end_line}`; never when that folder is home or `/`),
+  `tool_call_completed` (its status word); the viewer's **own** queue events in the owner's shape (`turn_enqueued`:
+  `enqueued_id`, `client_id`, `prompt`, `delivery`, `author`, their image refs; `turn_dequeued`: its `enqueued_id`, never
+  the client that took it back, the filter knowing their ids from the `turn_enqueued` it sent them and from
+  `ParticipantAccess#own_turn?`; `input_merged`: the count and origins of their own lines only), anyone else's bare;
+  `question_requested` and `continue_offered` with one derived `kind` (`.waiting_kind`: `approval` for a guardrail's
+  approval or a relayed one, `continue` for the step-limit question and every offer, `question` else); the main
+  page's numbers (`context_status`: usage's `estimated_pct` and token counts, `bucket`, a switch's
+  `context_window_tokens`, never `status`, the model-facing line; `generation_completed`: its `speed` only;
+  `working_set_updated`: `.working_set`, below); and bare markers (the type alone) for the answers to a question or
+  offer, and `snapshot` / `reset` (the page re-reads the session at a `reset`, as the owner's). Every other type,
   known (`DROPPED`) or new, is dropped. `spec/web/participant_view_spec.rb` scans every `type: :name` chi emits and
   every handler of the web's stream, and fails until a new one is named in `EVENTS` or `DROPPED`.
 - **The frames** (`Web::ParticipantStreamFilter`). The Bridge's chunks are cut into frames (`\r?\n\r?\n`, a partial
@@ -372,8 +468,8 @@ fields: a field added to an event later reaches nobody until it is named there.
   and never after a key word whose value is still to come, `Redact::OPEN_VALUE`; past 1600 with no such space,
   the line's last unbroken run and the rest of that line go out as one `[redacted]`). The owner's stream never
   goes through it (a byte pipe).
-- **The conversation** (`.messages`, over `App#messages_for_display(parts: true)`, `Web::MessageDisplay`; no turn drawings: the
-  participant page rebuilds every turn from its messages, [bridge.md](bridge.md#turndrawings)): a user message only when it is a
+- **The conversation** (`.messages`, over `App#messages_for_display(parts: true)`, `Web::MessageDisplay`; each finished
+  turn's drawing comes with the show, [The main page's show](#the-main-pages-show)): a user message only when it is a
   turn's prompt (it has the turn's id) or a person's merged line, and never one from a source that isn't a person's;
   so the owner's `!` line and its output, a delegate's report (a wake turn's too), and the notes chi adds (a declined
   Continue) never show. A turn no person sent (its record's `automatic`, `SessionMetrics`: a task's or a plugin's,
@@ -384,11 +480,55 @@ fields: a field added to an event later reaches nobody until it is named there.
   links group by `[data-turn-id]`). A raw loop's saved
   reply is cut before the display reads it (`.visible_raw`): what came before a bare `</think>` and everything from
   an unclosed thought or tool call on, which the display would only untag. Each
-  prompt carries its author and an image count; replies their text and their step's tool rows. Notes, steers and
+  prompt carries its author and its images: the viewer's own as refs, anyone else's as a count
+  (`.image_refs`, below); replies their text and their step's tool rows. Notes, steers and
   empty-answer markers are dropped. The reply's
   `html` is rendered from the filtered text. The turn in progress (`.current_turn`, over the Bridge snapshot's) gives
   its start's fields, the text so far, its tool rows (with `running`) and `waiting_for_owner`.
+- **Images** (`.image_refs`, on a message, a `turn_started` (so the running turn and the drawings) and a queued
+  entry): the viewer's own as `[{file, name, width, height}]`, only refs to a stored image (`ImageStore::REF_RE`;
+  any other dropped), never `source`, `bytes` or `mime`; anyone else's (the owner's, another participant's) as a
+  count, which the page draws as a muted "N images" line (`images.js thumbsTemplate`).
 - **The queue.** Their own queued turns (enqueued id and text, for Take back) and how many others wait.
+- **The working set** (`.working_set`: the event and `GET …/working_set`): the file items inside the project, the
+  key made relative, with `state`, `tokens`, `ops`, `count`, `pinned`, and the set's `at`. Never a memory or URL
+  item, a path outside the project, `first_id`, `has_drop` or the pending `adds`.
+
+### The main page's show
+
+`GET /api/sessions/:id` for a participant (`Web::ParticipantShow#participant_main_show`) is the main page's read
+in the owner's shape (`SessionShow#owner_show`'s keys, from the same `show_reads`), every part through
+`ParticipantView`: the one read their page makes (the participant page's `GET …/review` is gone).
+`spec/web/participant_show_spec.rb` holds its parity: no key the owner's lacks but the
+verdicts' (`fresh_running`, `session.verify_unavailable`).
+
+- `messages` as the review read's (a turn's opening with its Revise stamp, `revises: {turn_id}`, and a Verify
+  turn's `verify: true`, a boolean, never the quote; `turn_completed` carries both too), stamped `drawn` (the turn whose drawing draws them); `turn_drawings` each
+  finished turn's drawing replayed event by event through `.event` (no cards), its start's prompt the filtered
+  messages' prompt of that turn, else none (an automatic turn, a wake, a delegate child's task: a made drawing's
+  start has no origin to say so), its end `.drawing_end` (type, turn id, duration, kept steps; never a failure's
+  words or a cancel's reason).
+- `current_turn` (`.current_turn`: its start, text, tool rows, `waiting_for_owner` and `kind`, and the generation's
+  phase, `generation: {thinking_only, age}`, the delivery line's clock), `replay` (the join's events through
+  `.event`) and `queued` (the viewer's own entries, `.queued_entry`).
+- `session`: id, participant title, status (idle when a worker says running with no turn), `bridge_up`,
+  `worker_features`, `verdicts` (filtered, as the review's) and `verify_unavailable`.
+- `viewer`: `Web::Viewer`'s kind, id, name, `can` (`Viewer::PARTICIPANT_CAPABILITIES`: `send`, `stop_own_turn`,
+  `steer_own_turn`, `revise_own_turn`, and of the owner's `working_set` and `images`), `client_id` (`review:<grant id>`, which chi web gives their
+  turns), their `participant_kind`, `mode`, `cap_reached` and `usage`, `session_stopped`, and
+  `waiting_for_owner` (the kind the session waits on, the review read's rule: the running turn's question, a
+  Continue offer, a question between turns; nil when nothing).
+- `timing` (`.timing`): the session's clock, each turn record's id, times, `duration_ms`, `decode_tps` and
+  `tps_source`, the running turn's start, the context's `used_tokens` and `window_tokens`. Never `tool_records`,
+  `active_tools`, `tokens`, `model_segments`, `memory_index`, `side`, nor a record's cost, tokens, model, author,
+  cancel reason or failure.
+- Empty or nil: `history`, `commands`, `cards`, `init_tasks`, `queued_commands`, `recap`, `saved_recap`,
+  `continue_offer`, `pending_question`, `failed_turn`, the warnings, the markdown tips; `capabilities` never names
+  the editor.
+
+The main page's `<body>` for a participant (`App#participant_index_data`): `version`, `session`,
+`session-title`, the Annotate presets, the viewer and `working-set` (the owner's `web.working_set`); nothing of the
+owner's machine (`home`, the folders, `project-*`, `back-*`).
 - **Their usage** (`viewer.usage`, `ParticipantReview#review_usage`, built from named fields by the exposure policy
   beside `ParticipantView`'s): the fields their grant's exposure shows
   ([Grants](#grants)); at `own`, `{spent, cap, queued, queue_limit, expires_at, model}`. `spent` is dollars: the saved
@@ -397,62 +537,33 @@ fields: a field added to an event later reaches nobody until it is named there.
   running turn shows before it is saved; the two are never added), read from the Bridge snapshot the review already
   reads. `queued` counts their own queued turns on the worker; `model` is the session's model as its host is sent it
   (the alias applied, no host name), live else saved, redacted. Every source reads the grant's own author: another
-  participant's spend, the owner's and the session's totals never reach them (the red-team spec checks the body). The
-  owner's participant view has none. The page draws it as one line in the comment box card's footer
-  (`.composer-card-foot`, `usageItems`): "$0.42 of
-  $2.00 cap · 1/3 queued · link: 6 d left · model", each with a title in words; warn colours from 80% of the cap, a
-  full queue and a link's last day, "over" at the cap. The key hint is the line above the text field, wrapping to at most two (hidden on a
-  phone). The usage is cut at the end (the model first); folded, it stays as the card's footer under the grip. It is redrawn at each re-read (a
-  turn's end, a queued or taken-back comment), not while a turn streams.
+  participant's spend, the owner's and the session's totals never reach them (the red-team spec checks the body). Their
+  page draws the spend of the cap in its bottom row ("$0.42 of $2.00 used") and the link's end in its top row; it reads
+  the show again at each turn's end for it (the light re-reads carry no viewer).
 - **A fork's note.** A review fork (`chi review --from`, `/coordinate review`) starts with a note holding the source's
   recap and, from the coordinator, its handoff's body: a participant's review turn reads it like the rest of the
   history and may quote it (host paths, worktree names). That is by design (it is what the review is about); the
   owner chose to share it. Nothing else of the source comes along.
-- **The subjects** (`subjects`, a review session's: [docs/sessions.md](../sessions.md#review-sessions)): each
-  `{path, text, truncated, html}` (`html` for markdown only, rendered from the redacted text), or `{path, missing:
-  true}`. Every read checks the path again with `Guardrails::ReviewPaths` (a review turn's own check: under the
-  project root, as given and as it resolves, never a secret file or chi's own), so a subject that became a symlink
-  out of the project, or a session file edited to name `.env` or `../x`, is `missing`, never read. The text is cut
-  at 256 KiB (`SUBJECT_BYTES`) and redacted. The real path is what is checked and opened, with `O_NOFOLLOW`: a
-  symlink swapped in for the file itself after the check isn't read. That guards the last path component only: a
-  folder on the way swapped for a symlink between the check and the open is still followed. Doing that takes write
-  access to the project tree, the owner's, so it isn't a participant's way out; the next read checks again.
-  `[]` for a session that isn't a review session. The page's title for a
-  review session with no title of its own is `review of docs/plan.md` (`+N` for more), never the first prompt. The
-  page shows them as the Plan: beside the thread on a wide screen (≥ 1100 px), a Plan | Thread toggle on a narrower
-  one (the thread first, the composer pinned in both views); several subjects get a file picker. It re-reads them
-  with the rest at every turn boundary and redraws the Plan only when they changed.
-- **Annotate** (`participant_annotate.js` over the owner's `annotate_bar.js`, styled by the shared
-  `annotate_bar.css`). A participant who can comment selects text in the Plan or the thread and gets **Annotate** and
-  the owner's `web.annotate_presets` (the participant shell's `data-annotate-presets`, as `index.html`'s), which append
-  the quote to the comment box; nothing is sent. Labels: the Plan `From docs/plan.md:` (the subject shown), a comment
-  `From Sam's comment:` / `From my earlier comment:` / `From the owner's message:` (the message's `data-by`,
-  `data-name`), a reply none. Not annotatable: the reply still streaming, tool rows, waiting lines, gap lines, the
-  header, the Plan's truncation note. No plugin pills (a review turn refuses `/` lines), and none of it in the owner's
-  participant view (no presets in its shell) or while `can_comment` is false. On a touch screen the bar docks above the
-  composer. A re-read keeps unchanged thread nodes and the Plan's (redrawn only on change), so a selection survives it.
-  After the presets comes the built-in **Verify** (`verify_preset.js`, on the owner's page too): the quote, then
-  "Verify this claim against the code. If this session's context doesn't settle it, say so. End with a line
-  `Verdict: confirmed|refuted|unclear — <one-line reason>`." It fills the box like any preset and never sends.
-  It is offered only where the Engine will take the claim (`verify_target.js`, the bar's `offeredPreset`): a
-  selection in the final answer of an ended turn, the last answer bubble (the owner's `.bubble.output` that isn't a
-  delegate report's reply; a participant's last `.p-msg.reply > .p-bubble`) between the turn's opening
-  (`[data-turn-id]`) and the next one (or, on the owner's page, a context note: a wake turn opens with one; a
-  participant's page gets a wake turn's opening as an automatic turn).
-  Anywhere else (an earlier reply, a step, a prompt, a line merged mid-turn, the Plan, the running turn) the button
-  is hidden and the bar keeps its other actions.
+- **No file view.** A review session's subjects are not sent to a participant (their page has no file panel; they ask
+  chi to quote the part they need: [docs/sessions.md](../sessions.md#review-sessions)). Its title for a review session
+  with no title of its own is `review of docs/plan.md` (`+N` for more), never the first prompt.
+- **Annotate** is the main page's (`annotate_bar.js`): a selection in the conversation offers **Annotate** and the
+  owner's `web.annotate_presets` (their `<body>`'s `data-annotate-presets`), which append the quote to the composer,
+  then the built-in **Verify** (`verify_preset.js`), offered only where the Engine takes the claim (`verify_target.js`
+  `OWNER_FINAL`: the final answer of an ended turn). No plugin pills (their show's `commands` is empty) and no Copy
+  link (no participants panel).
 - **Deep links to a claim** (`claim_link.js`). The owner selects text in a turn's answer, step or own message and
   Annotate's **Copy link** copies `<base>/#s=<id>&t=<turn8>&q=<quote>&p=<prefix>`: `base` the participants list's
   `link_base` (`ParticipantsAdmin#participant_base`: `web.public_url`'s origin, else the LAN address, else the Host),
   `t` the turn's id (its first 8 characters, the opening message's `data-turn-id`), `q` the selection's rendered
   text (whitespace collapsed, at most 200 characters) and `p` up to 32 characters before it in the same bubble, both
-  URL-encoded by `URLSearchParams`. The text is read as the participant page shows it, by `Redact`'s own rules
+  URL-encoded by `URLSearchParams`. The text is read as a participant's page shows it, by `Redact`'s own rules
   mirrored in JS (`spec/fixtures/redact_cases.json` holds cases both sides must read the same): secret shapes
   `[redacted]`, whole even when the selection cuts into one, so a link never carries a secret; on the owner's page
   also the session's folder relative and the home folder `~` (the page's `data-home`). Not the owner's token (the
   page doesn't hold it). With no person (`kind: human`) active in the session, Copy link gives the owner's own form,
-  `#/s/<id>?t=…&q=…&p=…`; the owner's page also opens the participant form. Opening one: the turn's bubbles
-  (`.p-msg > .p-bubble`; the owner's answers, own messages and steps) are searched for the prefix and quote, then
+  `#/s/<id>?t=…&q=…&p=…`; the main page opens either form (`owner_claim.js`, a participant's page too: its one
+  session is the claim's). Opening one: the turn's bubbles (answers, own messages and steps) are searched for the prefix and quote, then
   the quote alone; the match's bubble is ringed (`.claim-hit`), a closed `<details>` around it opened, and the quote
   highlighted (the CSS Highlight API, `::highlight(chi-claim)`, where the browser has it). A quote not found (text
   that reads differently) rings the turn's opening. A turn no opening carries (a non-person turn the page doesn't
@@ -478,11 +589,10 @@ fields: a field added to an event later reaches nobody until it is named there.
   a valid `Verdict: confirmed|refuted|unclear — <reason>` appends a verdict to the session. Both pages place its card
   in the source turn, right after the bubble that holds the quote (the answer's, matched as a claim link reads the
   page; a quote not found yet goes at the turn's end), name its author, show the reason and quote, and link to the
-  checking turn; a live completion adds the card without a reload. The participant view receives only the card fields through its allowlist, with the
+  checking turn; a live completion adds the card without a reload. A participant receives only the card fields through its allowlist, with the
   quote and reason redacted by the view's normal rules, never the full reply.
 - **Verify fresh** (`VerifyFresh`, `verdict_fresh.js`). An `unclear` card has a **Verify fresh** button (the owner's
-  page always; a participant's while `can_comment`, i.e. while their grant could run a turn now; never in the owner's
-  participant view). It is `POST /api/sessions/:id/verdicts/:check_turn_id/fresh` (`VerifyFreshRoutes`, `:owner`
+  page always; a participant's while their grant could run a turn now). It is `POST /api/sessions/:id/verdicts/:check_turn_id/fresh` (`VerifyFreshRoutes`, `:owner`
   and `:participant`), which starts a **fresh child**: a delegate child (`spawn_session`, `delegate: true`,
   `parent_id`) in the session's own folder (no worktree; a folder outside git too), on its model, whose first and only
   prompt is the claim, quoted, and "Verify this claim against the files here. You have none of the original session's
@@ -539,38 +649,34 @@ fields: a field added to an event later reaches nobody until it is named there.
     data). The card shows "Verifying fresh…" while the child runs (the summary's `verify_fresh` `{of, child_id}`,
     the review data's `fresh_running`, ids only) and the fresh verdict as a `fresh: ✅ confirmed — …` line on the same
     card. The original stays unclear, so the button stays, as **Verify fresh again**: each press is another paid
-    child (a participant's against their cap). The participant view passes `fresh` and `of`, never the child's id (a
+    child (a participant's against their cap). `ParticipantView` passes `fresh` and `of`, never the child's id (a
     participant can't open it). No push
     for a fresh verdict yet (`Attention` pushes a verdict at a turn's end).
-- **The comment box** is the owner's composer (`composer_mount.js`, styled by the shared `composer.css`), mounted by
-  `participant.js` with a subset on. It has: the height that grows with the text, the grip (drag to resize,
-  double-click resets, click or drag down folds it; folded, the grip is the handle on the card's top edge and typing on the
-  page opens it; Annotate opens it for the visit), the one-row layout of the owner's session composer (Send at its
-  bottom right; a phone keeps it one row), and ↑/↓ over the participant's own comments: the ones the server took from
-  this browser, in localStorage under `chi_review_history:<grant id>` (`review_history.js`; the grant id is the review
-  data's `viewer.id`), at most 50, forgotten when the link ends (a 401 with chi's words), never the owner's `GET
-  /api/history` (the owner may open a link in the same browser). It lacks: the `/` list and plugin pills (a review turn
-  refuses `/` lines), the delivery line and its steer/queue choices (every comment is `POST …/turn`, a queued review
-  turn; Alt+Enter is Enter), the model picker, Stop turn (the owner page's sits in its stage's status row; this
-  page has no stage), and images: the chips are mounted but `imagesOff` refuses a
-  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.
+- **The composer** is the owner's, with what is theirs (`participant_main.js`; [web-frontend.md](web-frontend.md#the-participants-page)):
+  no `/` list or plugin pills, no ↑/↓ prompt history (the owner's `GET /api/history`), no model picker. Images go
+  in as the owner's do (paste, drop, the image button), within their quota ([Participant images](#participant-images));
+  a refused upload or send keeps the chips and toasts the server's words. While their own turn runs, a message goes in at its next step on a
+  worker with `participant_steer` (Alt+Enter queues it); while anyone else's runs, it goes in as their own turn after
+  it, and the delivery line says so. Stop turn shows on their own turn only. At their cap, in a stopped session, or
+  once their link ended, the composer gives way to one line (the cap's own words; the server's for the others) and
+  the conversation stays readable. A turn of theirs that waits for the owner (an approval, a question, a Continue
+  offer) gives the stage its waiting look with one line naming the kind, never a card.
 - **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
   folder (`~`). Defence in depth only: the allowlist is the control; a reply that paraphrases a secret isn't caught.
 - **Errors.** A participant's 404 and 500 carry fixed words, never an exception's (which may name a path); so does their `wait` on a turn that failed (`TURN_FAILED`).
-- **The owner's participant view.** The owner reaches the same reads: `/?as=participant#s=<id>` serves the participant
-  page, `GET …/review` is always the filtered view, and `…/stream?as=participant` goes through the same filter, with
-  no participant of their own (nothing `mine`, no composer). It is the server's filter, never a page imitating it.
+- **No "view as a participant" for the owner.** The owner's `/?as=participant` view went with the participant page
+  (2026-11-13: every read on the main page would need the flag threaded through, and one missed read would show
+  unfiltered data in a view that claims to be the participant's).
 
-The red-team spec (`spec/participant_red_team_spec.rb`) reads the stream, the review, every show variant, `/output`
-and an image as a participant, with an approval, a question, a tool's call and output, thinking, a memory, a steer,
-a delegate report, an unknown event and host paths in the session, and finds none of them. It also names a secret,
-a file outside the project and a symlink out of it as subjects in the session file and reads none of them through
-`…/review`, and has `chi review` refuse each as a subject.
+The red-team spec (`spec/participant_red_team_spec.rb`) reads the stream, every show variant, `/output` and images
+they didn't upload (a guessed name, the owner's by its hash: 404) as a participant, sends another's image refs
+(the owner's, another participant's, a guessed hash, a forged `source`: 403), with an approval, a question, a tool's call and output, thinking, a memory, a steer, a delegate
+report, an unknown event and host paths in the session, and finds none of them. It also names a secret and a file
+outside the project as subjects in a review session's file and reads none of them in the show, and has `chi review`
+refuse each as a subject.
 
 ## The owner's controls
 
@@ -660,9 +766,15 @@ invited to has none: its files stay byte for byte as they were.
   it, or `(none)`, once a minute per grant and identity whatever the path; at most 256 refusals a minute are
   remembered and audited; or `what: command`, a participant's `/word` or
   `!line` the Bridge or the worker refused), `turn` (chars, `status: accepted` with its enqueued id, or `refused` with
-  the reason: `not_permitted`, `too_many_turns`, `cap_reached`, `review_unavailable`, `worker_timeout`), `cap` (a new
+  the reason: `not_permitted`, `too_many_turns`, `cap_reached`, `bad_images`, `no_vision` with its `detail`,
+  `review_unavailable`, `worker_timeout`; `images`: how many it carried), `image` (an upload: `status` accepted with
+  its `file` and `bytes`, or refused with the `reason`; never its name), `cap` (a new
   cap), `verify_fresh` (`of`, `status`, the child and mode or the reason). A Verify fresh child's participants' lines
   are its parent's. It goes with the session (retention, delete).
+- **`participant_images.json`** (0600, `ParticipantUploads`, chi web only, beside `participants.json`, not under
+  `images/`: no route serves it): `{images: [{file, grant_id, at}], attempts: {<grant id>: n}}`, which image files
+  each grant uploaded and how many uploads each tried. Written whole (`AtomicFile`) under chi web's
+  `@participant_images_mutex`. It goes with the session.
 - **`participants.lock`** (0600, empty): the lock a participant's turn file is counted and written under when no
   worker runs ([Turns](#turns)).
 
@@ -698,13 +810,13 @@ means the owner: a turn or session with no author keys reads as the owner's and
 - **Records.** `last_turn.author`, the analytics turn record's `author`, `turn_enqueued`'s `author`, and the
   Bridge's queued rows. `turn_started` carries `author`, `author_name` and `participant_mode` on a participant's turn
   (the owner's carries none), and so does the Bridge's turn snapshot and its replay. The owner's history
-  (`MessageDisplay`) and the participant view pass a participant message's `participant_mode` on: the author badge
-  reads "Alex · review" or "Alex · pair" (a prompt drawn while queued takes its mode at `turn_started`).
+  (`MessageDisplay`) and `ParticipantView` pass a participant message's `participant_mode` on: the author badge
+  reads "Alex · review" or "Alex · pair" (to a participant, a pair turn is the name alone, the owner's prompt "owner") (a prompt drawn while queued takes its mode at `turn_started`).
 - **Side models' transcripts.** The idle recap's (`IdleRecap::TranscriptFilter`) leads a participant's message with
   "(a review contribution from Alex, a participant; not the user's words)", and `ctx.ask_model`'s names its paragraph
   `Participant`. The UI's readers name them: `TurnAccumulator.messages_of` gives a participant's prompt and merged
   input `author` and `author_name`, `Merge#event_fields` names the merged text's author when one participant wrote all
-  of it, and the web's display messages carry both (the owner's badge, the participant page).
+  of it, and the web's display messages carry both (the badges).
 - **Through `--remote`.** `SessionAccess::WebBridgeClient#post_turn` takes `author:` and drops it: the remote chi web
   stamps the author from the token.
 
@@ -763,16 +875,20 @@ participant TUI in v1.
 - A participant reaches one session, through the `:participant` rows only; another session is a 404.
 - No token is written anywhere: the grants store has digests, the sidecar and the audit trail have neither.
 - Owner sessions are unchanged: no sidecar, no audit file, no key in the session JSON until a grant exists.
-- No participant reaches `/command`, `/answer`, `/output` or an image. Their turn's author and client id are stamped
+- No participant reaches `/command`, `/answer`, `/output` or an image they didn't upload. Their turn's author and client id are stamped
   from the principal, never the body.
-- Everything a participant reads (their stream, the review, the show) is built by `ParticipantView` from named fields;
-  an event type it doesn't name is dropped. The owner's participant view reads through the same filter.
-- A participant's turn is always a queued turn of its own (chi web, the Bridge, the inbox), never a command or a
+- Everything a participant reads (their stream, the show) is built by `ParticipantView` from named fields;
+  an event type it doesn't name is dropped.
+- A participant's message is a turn of its own, or goes into their own running turn at its next step (chi web, the
+  Bridge, the inbox), never into anyone else's turn and never a cut, a command or a
   shell line (chi web, the Bridge, the worker), and runs only on a worker with the review boundary: in a review
   session it denies everything but reads of the project; in a working session (a worker with `pair_turns`) the pair
   boundary denies secrets and owner-voiced tools, the owner's guardrails decide the rest, and every ask is the
   owner's, once only.
 - A participant's message is never sent without its review header, and never merged into the owner's message.
-- The owner's input is never merged into a participant's running turn (the Bridge queues it, the drain takes none):
-  it runs as the owner's own turn after it.
+- The owner's input is never merged into a participant's running turn (the Bridge queues it, the drain takes only
+  the participant's own lines): it runs as the owner's own turn after it.
+- A participant stops only a turn they started, named by its id, which the worker compares under its lock.
+- A participant revises only their own answer with only their own turns after it, checked by chi web at the send and
+  by the worker at the stamp (`ParticipantRevise`); their Revise never folds anyone else's turn.
 - A participant's turn never answers or drops the owner's Continue offer: it waits until the owner has.