samagotchi 0.170.0 → 0.171.0

data/docs/internals/web-frontend.md

@@ -5,10 +5,11 @@ reaches the screen, and the guards every new piece should use. The modules' own
 does; this page says how they hang together. The server side is [architecture.md](../architecture.md) (Web);
 the working set's overlay is [working-set.md](working-set.md), participants are [participants.md](participants.md).
 
-No build step: `index.html` and `participant.html` load ES modules as they are, with lit-html (`vendor/`) as the
+No build step: `index.html` loads ES modules as they are, with lit-html (`vendor/`) as the
 only library. Pure modules (`*_model.js`, `session_state.js`, `sessions_list.js`, `turn_range.js`, …) touch no DOM
 and have `node --test` specs under `spec/web/public/` (happy-dom for the DOM ones); the pages as a whole are covered
-by `npm run e2e` (`spec/e2e/`). `app.js` has no unit spec.
+by `npm run e2e` (`spec/e2e/`). `app.js` has no unit spec of its own; `viewer_boot.test.js` boots the whole page
+(`page_boot.js`, happy-dom, in a process of its own) for what each viewer gets (The viewer, below).
 
 **Every module has a size cap, `app.js` its own**: `npm run lint` fails past `max-lines` in `eslint.config.js`
 (counted as `wc -l` counts, comments and blank lines too). Every `public/*.js` module: 1200 (`samagotchi/module-size`,
@@ -28,23 +29,19 @@ page. A factory dep a new version stops passing is the same hazard the other way
 out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
 until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
 `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
-`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `version_notices.js`, `owner_claim.js`, `owner_verify.js`, `composer_mode.js`, `strip_hidden.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js`, `block_watch.js`, `card_stamps.js`, `recap_stamp.js` (a saved recap's place by its `opening_id` stamp, else its count), `inline_widgets.js`, `widget_walk.js`, `widget_picks.js`, `history_shape.js` (the history's shape, live against a reload: the e2e reload checks and the opt-in reload check share its normalizer and its `ACCEPTED` allowlist), `turn_pieces.js` (a finished turn's one order and its answer rule: the live hand-off's `handOffOrder` and `turnEnded`, and a reload's `turnHistoryNodes`), `reload_check.js` (the opt-in `web.reload_check`: after the stage's hand-off, the turn against a reload of it, the counts posted), `turn_drawing.js` (a finished turn's drawing, `turn_drawings` in the show: its fold into steps and its end kind; `turn_block.js` draws it), `stage_stall.js` (the stage's quiet signal), `history_end.js` (the stage's one move of pieces to the history's end), `stage_opened.js` (a running turn opened in the history while a card waits: the lead-in bubble, the moves, the end fold), `stage_asking.js` (the stage's docked card and its fold: the docking and lead-in rules, the opening, a waiting card's own toggle, the folded row's text per kind, the fold's choice, reveal and the docked card's fold; `stage_view.js` wires it), `stage_waiting.js` (the stage's waiting cards as data, keyed by `data-qid` / `data-card-id`: kind, docked, approval, the stage's order, the shown card and its pager, the docked card's fold; `front`, `count`, `shown`, `blocking`), `stage_cards.js` (the cards that wait in the stage: `PENDING`, `ASKS`, `waitsInStage`, read by `stage_model.js placeKind`), `resync_reach.js` (a re-read that can't reach chi web keeps the drawn history; the status chip says retrying / offline, outside a turn), `session_sync.js` (the open session's sync: `select`, `resync` and its retries, the stream's life; the stream handle and the re-read bookkeeping are its own), `session_view.js` (the open session's view: `renderSessionView` draws a read, `forgetSession` resets the page for another session, `readTurnEnd`, `endTurnView`; app.js makes both right after the cards, each reaching the other and the later views through getters), `no_contact_fill.js` (a text field that isn't a contact form: autocomplete off and a name with no contact word, against iOS Safari's AutoFill Contact bar; a template's fields carry the same attributes, and its spec checks the page's markup for them) and the `objectives_*.js` modules are new modules for that reason. The last four `block_*` draw fenced blocks (`block_watch.js` finds and watches them, `block_host.js` is its frame drawer for a bundle's renderers): [block-renderers.md](block-renderers.md). `inline_widgets.js` is its core drawer for `chi-ui` blocks, drawing `widget_walk.js`'s and `widget_picks.js`'s widgets in a shadow root styled by `widgets.css`: [inline-widgets.md](inline-widgets.md).
+`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `version_notices.js`, `owner_claim.js`, `owner_verify.js`, `composer_mode.js`, `strip_hidden.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js`, `block_watch.js`, `card_stamps.js`, `recap_stamp.js` (a saved recap's place by its `opening_id` stamp, else its count), `inline_widgets.js`, `widget_walk.js`, `widget_picks.js`, `history_shape.js` (the history's shape, live against a reload: the e2e reload checks and the opt-in reload check share its normalizer and its `ACCEPTED` allowlist), `turn_pieces.js` (a finished turn's one order and its answer rule: the live hand-off's `handOffOrder` and `turnEnded`, and a reload's `turnHistoryNodes`), `reload_check.js` (the opt-in `web.reload_check`: after the stage's hand-off, the turn against a reload of it, the counts posted; it compares the turn's own cards and questions, dropping every entry CardStore attributes to another turn), `cards_offscreen.js` (the reload check's placer: `createCardsPlace`, `createBubbles` and `createQuestionCards` over a detached holder, every page hook inert - no stage, no scroll, no session id, no api, no storage - so a snapshot's cards land where a reload would put them without touching the page), `turn_drawing.js` (a finished turn's drawing, `turn_drawings` in the show: its fold into steps and its end kind; `turn_block.js` draws it), `stage_stall.js` (the stage's quiet signal), `history_end.js` (the stage's one move of pieces to the history's end), `stage_opened.js` (a running turn opened in the history while a card waits: the lead-in bubble, the moves, the end fold), `stage_asking.js` (the stage's docked card and its fold: the docking and lead-in rules, the opening, a waiting card's own toggle, the folded row's text per kind, the fold's choice, reveal and the docked card's fold; `stage_view.js` wires it), `stage_waiting.js` (the stage's waiting cards as data, keyed by `data-qid` / `data-card-id`: kind, docked, approval, the stage's order, the shown card and its pager, the docked card's fold, kept for this tab in `chi_asking_fold:<session>`; `front`, `count`, `shown`, `blocking`), `stage_cards.js` (the cards that wait in the stage: `PENDING`, `ASKS`, `waitsInStage`, read by `stage_model.js placeKind`), `resync_reach.js` (a re-read that can't reach chi web keeps the drawn history; the status chip says retrying / offline, outside a turn), `session_sync.js` (the open session's sync: `select`, `resync` and its retries, the stream's life; the stream handle and the re-read bookkeeping are its own), `session_view.js` (the open session's view: `renderSessionView` draws a read, `forgetSession` resets the page for another session, `readTurnEnd`, `endTurnView`; app.js makes both right after the cards, each reaching the other and the later views through getters), `participant_main.js`, `participant_bar.js`, `viewer_self.js`, `stage_owner_wait.js`, `participant_revise.js` (a participant's page: The participant's page, below), `ws_timeline.js`, `ws_cards.js`, `ws_peek.js`, `ws_reader.js`, `ws_way_in.js` (what chi has of a working-set item: below, The working set's reader), `no_contact_fill.js` (a text field that isn't a contact form: autocomplete off and a name with no contact word, against iOS Safari's AutoFill Contact bar; a template's fields carry the same attributes, and its spec checks the page's markup for them) and the `objectives_*.js` modules are new modules for that reason. The last four `block_*` draw fenced blocks (`block_watch.js` finds and watches them, `block_host.js` is its frame drawer for a bundle's renderers): [block-renderers.md](block-renderers.md). `inline_widgets.js` is its core drawer for `chi-ui` blocks, drawing `widget_walk.js`'s and `widget_picks.js`'s widgets in a shadow root styled by `widgets.css`: [inline-widgets.md](inline-widgets.md).
 
-## Two pages, two models
+## One page, every viewer
 
 | Page | Entry | Model |
 |---|---|---|
-| **Owner page**: the start page and a session page | `index.html` → `app.js` | **Render once, then patch.** A session's open (`session_sync.js` `select` → `resync` → `session_view.js` `renderSessionView`) draws the history from `GET /api/sessions/:id`; from then on each stream event changes the DOM in place (`stream_handlers.js`). The DOM *is* the log. The start page is the same app with `store.selected` null. |
-| **Participant page**: a review or pair link | `participant.html` → `participant.js` | **Re-read at a turn boundary, then a keyed redraw.** It reads `GET …/review`, draws it, and streams; an event that ends or changes a turn (`reloads`) marks the data stale and the page reads it again. `drawnMessages` keeps a message's node while its signature is unchanged; a small `live` overlay (`participant_model.js applyLive`) draws the running turn on top. |
-
-The participant page is **deliberately separate**: it shares leaf modules with the owner page (the annotate bar,
-claim links, `composer_mount.js`, the verdict card and Verify fresh, `verify_target.js`, `verify_preset.js`,
-`auth_lost.js`, `token_fragment.js`, `format.js`) but none of the data layer, the stream handling or the message
-rendering. It has its own `api` (`{status, ok, body}`, never throws, its own ended / auth-lost handling) and its own
-`EventSource`. Its parallel copies of the owner's Verify and claim helpers (`verifyFreshState`, `verifyAnchorFor`,
-`showPendingClaim`, `CLAIM_ROOTS`; the owner's are `owner_verify.js` and `owner_claim.js`) differ on purpose in places (the source kind `reply` vs `answer`, the server's
-`fresh_running` vs `verify_fresh`, no home/cwd in its claim options). Don't converge them as a side effect of another
-change.
+| **The main page**: the start page and a session page, the owner's and a participant's | `index.html` → `app.js` | **Render once, then patch.** A session's open (`session_sync.js` `select` → `resync` → `session_view.js` `renderSessionView`) draws the history from `GET /api/sessions/:id`; from then on each stream event changes the DOM in place (`stream_handlers.js`). The DOM *is* the log. The start page is the same app with `store.selected` null. |
+
+A participant's link (a review or pair grant) opens the same page: chi web serves them `index.html` stamped with
+their viewer (The viewer, below), their show and stream are filtered (`Web::ParticipantView`,
+[participants.md](participants.md#what-a-participant-sees)), and what is theirs on the page is
+`participant_main.js` (The participant's page, below). There is no second page: the participant page
+(`participant.html`, `participant.js`, `GET …/review`) went with the participant main page's Phase C.
 
 ## Where state lives (owner page)
 
@@ -58,7 +55,7 @@ change.
 | **The history DOM** | the conversation as drawn (a running turn's reason bubble, `.bubble.said`, is live only: see A turn opened in the history): which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), what opens a turn (`TURN_PROMPT`, `bubbles.js`: a prompt or a wake's note, the same turns `Steer.turn_opening?` counts for a card's `turns_since`), an opening's id for a card's and the saved recap's stamp (`data-turn-id` on a prompt, `data-opening-id` on a wake's note or `/continue no`'s reason line; `card_stamps.js` places a snapshot's card after the stamped opening, `recap_stamp.js` the saved recap after the last turn it covers, each by its count (`turns_since`) only without one), kept command bubbles, which texts were shown, unnamed badges, folded answers and long prompts (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`); the switcher's version on view is `revise_stack.js`'s own (a copy `.stack-view` before the top answer, the top `.stack-swapped`; never stored) | `bubbles.js`, `cards_place.js`, `question_cards.js`, `turn_block.js`/`stage_view.js`, `answer_fold.js`, `revise_stack.js`, `stream_handlers.js` (a live `turn_completed`'s `revises` and `verify` onto its prompt) | read back as state: `turn_range.js turnElements` (one walker for a turn's elements), `keptCommandBubbles`, `seedSeenFromDom`, `nameUnnamedBadges`/`nameVerdictCards`, `answer_fold.js` and `revise_stack.js` (their observers decorate every path that fills `#history`; the stacks are `stacks()` of the stamps, read again on each change, never a store field), `history_reveal.js revealInHistory` (the one way a jump unfolds what hides its target) |
 | **A drawn turn** (`turn_drawings` of the full read) | every finished turn, as live drew it: `turnGroups` groups by the stamps only, a turn's stamped items (`drawn: <turn_id>`) one group, and `turnHistoryNodes` draws it by feeding its drawing's events to a live turn block offscreen (`turn_block.js drawnTurnNodes`: the block's own handlers, as the stage's), the stage's extras (a reminder, merged lines, a card that asks or warns) and end as live, then the answer, the merged lines and the steps' texts from their saved items (markdown, refs). Each of its top-level elements carries `data-drawn`: `cards_place.js` leaves that turn's in-turn CardStore entries (`of_turn`) to it, and a kept reminder bubble of that turn (`data-turn-id`) stays out after a resync. chi web sends a drawing for every finished turn (one made from its messages where live wrote none): `drawnGroup` pairs the record the end names (`end.record_id`, by place for a turn saved before turn ids), else by the turn's id, and the answer's `data-answer-turn` is the end's own `turn_id` only (a made-up id, `m…` or `…~N`, keys none: no Revise). Nothing is rebuilt from messages: an item that comes unstamped is a `plain` group drawn as a plain row of its text (its prompt or answer bubble, no steps), the running turn's as expected (`runningTurnId`, the show's `current_turn`: it has no line yet), any other a miss, marked `data-undrawn`, logged once per render (`console.warn`) and counted by the reload check (`undrawn`), never a throw; a drawing with no parts (a minimal line) draws its prompt, answer and end | chi web (the show) | `renderHistory`, the reload check's render |
 | **localStorage** (`storage.js` `readStored`/`writeStored`, guarded) | per-browser choices only | the module that owns the choice | read at start (see Storage keys) |
-| **SSE** | see Streams | the server | owner page: events go into the DOM directly; participant page: an event marks the data stale |
+| **SSE** | see Streams | the server | events go into the DOM directly (a participant's through `participant_main.js wrapHandlers` first) |
 
 The objectives' strip keeps the list in its own closure (`objectives_strip.js`, seeded by `renderSessionView`, reset by
 `forgetSession`, updated by `objectives_updated`): [objectives.md](objectives.md#the-page).
@@ -203,6 +200,113 @@ the running turn's DOM) is cleared there, and the feature gates are primed for t
 (`pendingReviseAnchor`) is set only through `setReviseAnchor`, which redraws its chip and the Revise buttons (a
 redraw only it feeds, not a store field).
 
+## The viewer
+
+Who looks at the main page and what they may do there is the **viewer** (`viewer.js`), chi web's `Web::Viewer`
+(`lib/samagotchi/web/viewer.rb`: `Viewer.for(principal)` is the one place that decides it; the owner gets every
+capability). chi web stamps it on `<body>` (`data-viewer-kind`, `data-viewer-can`: the names, space-separated;
+`App#index_data_attributes`), and the owner's session show carries it as `viewer` next to `capabilities`. app.js
+makes one `viewer` from the body at boot; `setCapabilities` passes a show's `viewer` to `viewer.update` (it narrows
+the stamp, never widens it: the boot's controls were made from the stamp) and `forgetSession`'s
+`setCapabilities(null, null)` resets it to the stamp. A page with no stamp may do nothing. It is not the show's
+`capabilities` (what the page renders: markdown display, the editor) nor `refEditor()` (where a ref opens: the
+editor and its URL, refs.js's actions): those two are per request.
+
+**The null-control rule.** An owner-only control or call goes through `viewer.can(name)` where it is made, never at
+each use: a control the viewer may not use is not created and not wired (`const x = viewer.can("…") ? createX(…) :
+null`, then `x?.…` where it is read; a module's hook passed as `null`, as `stage_view.js onCancel`,
+`working_set_view.js sendLine`, `composer_mount.js loadHistory`), and its static element in `index.html` stays hidden
+(`viewer.control(el, name)` / `controls(els, name)`: the element when allowed, else hidden, marked `data-withheld`
+and `null`; index.html's `[data-withheld]{display:none!important}` beats an element's own `display` rule, which a
+bare `hidden` does not). A module the
+page reads everywhere takes a flag instead (`question_cards.js answers`, `block_host.js renderers`,
+`turn_block.js turnHistoryNodes`'s `apply`). No scattered `if (owner)`, and no 403 tolerated as a way of gating. The
+gates are boot-time: a show's narrower `viewer` changes what `viewer.can` answers later, not the controls made.
+
+| Capability | Controls | Calls |
+|---|---|---|
+| `sessions` | `#newBtn`, `#scope` (and `project_picker.js`), `#topStrip`, `#stripStatus`, `#stripGrip` (`strip_hidden.js`) | `refresh` (`GET /api/sessions`), `openSessionEvents` (`GET /api/events`), `/api/projects` |
+| `models` | `#modelPick` (never shown without the list) | `startPage.loadModels` (`GET /api/models`) |
+| `prompt_history` | ↑/↓ over the prompt history | `GET /api/history` (`loadHistory`) |
+| `push` | `#notifyBtn` (`notifications.js` not made; the tab title is set directly) | `/api/push*`, presence, the second `/api/events` stream |
+| `context` | the context chips (`context_chips.js`) | `…/context*` |
+| `working_set` | the stage's working set (`working_set_view.js`) | `GET …/working_set` |
+| `working_set_items` | the list rows' `▸` peek, the reader over the stage, a tool row's `timeline`, the ref menu's "What chi has" (`ws_reader.js createWorkingSetPreview`: not made without it, so `working_set_view.js` gets `peek: null`, `ws_way_in.js` stays off, `installRefClicks` gets `whatChiHas: null`) | `GET …/working_set/item` (on a tap only) |
+| `participants_admin` | the participants chip and panel, Copy link's participant target (`claimTarget`) | `…/participants*` |
+| `rename` | `#titleRenameBtn` | (`/title` goes as a session command) |
+| `images` | `#attachBtn`, `#attachInput`; paste and drop toast `IMAGES_NOT_HERE` | `POST …/images` |
+| `session_controls` | `#infoContinueBtn`, `#infoArchiveBtn`, `#infoStopBtn`, `#infoDeleteBtn`, `#infoMoreBtn` (the ⋯ sheet), the ⚙ chip and panel, the `/` list, the stage's task stop, the working set's drop/undrop | `POST …/command` (`composer.js`: without it a `/` or `!` line goes as a turn, and the worker decides), `…/stop`, `…/holds*`, `…/tasks/:id/stop`, `…/reload_check`, continue → (`POST /api/sessions`) |
+| `revise` | the answers' Revise (`revise_stack.js`) | (a Revise goes with `POST …/turn`) |
+| `revise_own_turn` (a participant's) | Revise on the answers to their own messages (`participant_revise.js`, `revise_stack.js mayRevise`); the stacks for everyone | (`POST …/turn` with `revises`, checked by chi web) |
+| `apply` | the Apply row (`turn_block.js`, `placeApply`, its click) | `GET …/apply` |
+| `answer_cards` | question, approval and continue cards (`question_cards.js`), System 1's "wrong" | `…/answer`, `…/question/dismiss`, `…/guardrails/wrong` |
+| `render` | | `POST /api/render` (`markdown_place.js`: step texts, a question's kept reply) |
+| `block_renderers` | a bundle's drawn blocks (the core `chi-ui` drawer stays) | `/api/block_renderers*` |
+| `stop_any_turn` | the stage's Stop turn (`onCancel`) | `POST …/cancel` |
+| `steer_any_turn` | none: the delivery line reads a participant's own `steer_own_turn` instead (`viewerTurn`) | |
+
+A participant's `can` (`Viewer::PARTICIPANT_CAPABILITIES`, in their show's `viewer` and on `<body>`) names
+capabilities of their own, not the owner's: `send` (the composer), `stop_own_turn` (Stop turn on a turn they
+started, `POST …/cancel` with its `turn_id`), `steer_own_turn` (a message during their own turn goes in at its next
+step, on a worker with `participant_steer`), `revise_own_turn` (Revise on the answer to their own message); and of the owner's only `working_set` and `images`, which their routes
+serve filtered: the working set's project files ([participants.md](participants.md#the-main-pages-show)); their own
+uploads within their cap and quota, read back only by them ([participants.md](participants.md#participant-images)).
+Their messages carry their own images as refs (thumbnails) and anyone else's as a count, which `images.js
+thumbsTemplate` draws as a muted "N images" line (`.thumbs-hidden`). `stop_any_turn` / `stop_own_turn` both make the
+stage's Stop turn (`onCancel`); a participant's shows on their own turn only (`stage_view.js canCancel`).
+
+The owner routes (`App::ROUTES` rows marked `:owner`) the page never calls without one of the above:
+`/api/update*` and `…/restart` (`version_notices.js`: its versions come only from the hub stream, `sessions`);
+`…/archive`, `…/unarchive`, `DELETE …/:id` (the bar's buttons, `session_controls`; the strip and the all view,
+`sessions`); `POST /api/sessions` from the start page (a participant's page opens the grant's session and never the start
+page) and the
+participants panel's review start (`participants_admin`); `GET …/images/:file` (a message's image refs; a
+participant's messages carry refs only for their own uploads, the one image a participant's route serves them); the objectives strip's posts and the plugin cards' actions (`…/command`:
+drawn only from the show's `objectives` / `cards` and their stream events, which `ParticipantView` drops). Not called
+by the page at all: `/api/sessions/summaries`, `…/output`, `…/notes`, `…/wake`, `…/worker`, `…/exit`, `…/recap`,
+`…/stats`, `…/children/counts`, `…/turns/:id/records`, `/api/participants`. `viewer_boot.test.js` pins the table:
+with every capability today's calls and controls, with none no owner call and no owner control, each one alone,
+and a participant's (their show, the working set and their stream, nothing else).
+
+## The participant's page
+
+What is a participant's on the main page is `participant_main.js`, made by app.js only when `viewer.kind()` is
+`participant` (`participant`, null on the owner's page) and wired in a few lines; its pure views are
+`participant_bar.js`. The page stays the owner's model (render once, then patch); the participant's parts only read:
+
+- **One session.** `<body data-session>` (the grant's) is the session `selectFromHash` opens, whatever the hash
+  names (an old `#s=ID` link, a claim link's `#s=…&t=…&q=…`, which `owner_claim.js` still shows); `allViewOpen` is
+  never true; there is no start page.
+- **Who they are** (`viewer_self.js`): set from each show's `viewer` (`setCapabilities` → `participant.shown`),
+  since `<body>` names no ids. `turn_events.js isOwn` counts their client id (`review:<grant>`, chi web's for every
+  tab of theirs) as the tab's own; a `turn_started` with `mine` starts their queued bubble (`bubbles.js
+  queuedOwnBubble`: no origin names its enqueued id to them). `turn_html.js userBubbleTemplate` gives their echo
+  their badge and the owner's prompts the "owner" label; `participant_names.js authorBadgeText` reads a pair turn as
+  the name alone for them ("· review" stays).
+- **The rows.** The top row: a plain logo (`.plain-brand`, not `#newBtn`), their name ("Alex · invited") and, on a
+  desktop, when the link ends. The bottom row (`#participantBar`) in `#infoText`'s place, drawn by the `infoBar`
+  redraw (`updateInfoBar` returns early): status, ctx %, the last speed (the turn's time while one runs), their
+  spend of the cap, and on a desktop what their turns may do (`RULES_TEXT`). Never the owner's cost, the model,
+  memories or a path.
+- **The running turn.** `wrapHandlers` wraps `stream_handlers.js`'s handlers: `turn_started`'s author and `mine`
+  decide Stop turn (`canCancel`) and the delivery line (`deliveryTurn` → `delivery_line.js viewerTurn`: their own
+  turn on a `participant_steer` worker takes the message at its next step, Alt+Enter queues; anyone else's queues it
+  as their own turn) and the placeholder (`composer_mode.js steers`); `question_requested` / `continue_offered`
+  (their `kind` alone) set the stage's waiting look (`stage_owner_wait.js`, through `stage_view.js ownerWait`), no
+  card; a turn's end reads the show again for their usage (the light re-reads carry no viewer).
+- **The closed composer** (`#participantClosed`): their cap reached (the show's `cap_reached`, or a send refused
+  `cap_reached`: the show read again), a send refused `session_stopped`, or a link that ended (`token_revoked`,
+  `token_expired`: a refused send's words, or `linkEnded`, `onAuthLost`'s handler, from a brief read's 401). The
+  refusals show the server's `detail` as it is (`send_turn.js closesOn`); every other refusal is the toast.
+- **Revise** (`participant_revise.js`): the stacks are installed for `revise_own_turn` too, so their page folds every
+  stack (the owner's included); the Revise button is `installReviseStacks`' `mayRevise`, `participantMayRevise`:
+  `mayReviseOwn` mirrors `ParticipantRevise` on `historyTurns`' list (their prompt's `data-author` or this tab's
+  echo, an answer, no `data-verify`, and only their own turns after it), false while the composer is closed
+  (`participant.closed()`; `onClosed` redraws on a flip). The gate is the `participant_revise` feature, its words
+  `PARTICIPANT_REVISE_UNAVAILABLE`, the one page copy of `ParticipantMessages::REVISE_UNAVAILABLE`. A send refused
+  `revise_not_own` / `revise_overtaken` is a failed line with the server's `detail`, the text and the chip kept
+  (`send_turn.js`).
+
 ## Render idioms
 
 Three, for one job. Pick by what the piece is:
@@ -211,7 +315,7 @@ Three, for one job. Pick by what the piece is:
 |---|---|---|
 | **lit `render(template, keptContainer)`** | most components (~26): the info bar, chips and their popovers, panels, the init row, the working set, `start_page.js` | anything redrawn while the user may be in it: lit keeps the nodes, so focus, typed text, an open `<details>` and a tooltip survive. **The default for new UI.** |
 | **lit as a string builder**: `turn_html.js elementOf(template)`, `lists_view.js` (a fresh fragment, then `replaceChildren`) | history bubbles appended once; the session lists | a node built once and then owned by the DOM (history), or a list redrawn whole. `lists_view.js` throws away lit's diffing and binds card listeners per draw, with an `entering` tracker for its animations |
-| **hand-built DOM** (`createElement`) | `question_cards.js`, `verdict_card.js`, `verdict_fresh.js`, `participant.js` (`el()`) and a few small ones | older pieces; don't add new ones this way |
+| **hand-built DOM** (`createElement`) | `question_cards.js`, `verdict_card.js`, `verdict_fresh.js` and a few small ones | older pieces; don't add new ones this way |
 
 Listeners: every factory is a page-lifetime singleton, so `addEventListener` without a remove is fine; a per-render
 listener lands on a fresh node. A popover goes through `chip_popover.js createChipPopover` (its own outside-click,
@@ -268,11 +372,11 @@ so a Safari tab's toolbar never covers the composer). index.html's `:root` names
 (`env(safe-area-inset-*)`, 0 on a desktop), and only these read them: main's padding (16px, or the inset where it is
 wider; its bottom is 16px less than `--safe-b`, since the session's card floats 16px above main's bottom; a phone's
 session panel has no bottom padding and runs to the screen's bottom, its card at `--dock-bottom`, 16px or the
-indicator's line), a bottom
-sheet's offset (`chip_popover.js place`: 8px above the indicator, or a keyboard's offset alone), the update sheet, the
-toast's fallback place (in a session `--toast-bottom` already sits it above the card), the lightbox's padding and the
-signed-out banner (`auth_lost.js`, `env()` itself: the participant page has no `--safe-*`). A new fixed or bottom-anchored
-piece reads `--safe-*`, never `env()`: the e2e set the names by hand (`web.spec.js`, a portrait phone and a landscape one),
+indicator's line), a bottom sheet's offset (`chip_popover.js place`: 8px above the indicator, or a keyboard's offset
+alone), the update sheet, the toast's fallback place (in a session `--toast-bottom` already sits it above the card), the
+lightbox's padding and the signed-out banner (`auth_lost.js`, `env()` itself).
+On phones, the standalone app also has a 12px body inset, keeping its content below iOS 26's blurred band under the
+clock. A new fixed or bottom-anchored piece reads `--safe-*`, never `env()`: the e2e set the names by hand (`web.spec.js`, a portrait phone and a landscape one),
 as Chromium has no insets. The theme-color metas are tokens.css's `--bg-top` per theme up to 600px wide (a phone's page starts from that colour at its top edge, so the status bar meets the top bar with no seam), else its `--bg` (`theme.test.js` pins them). An iOS 26 Home Screen app ignores them for the status bar strip: it paints the strip in the body's `background-color`, so a phone's body gradient keeps a `--bg-top` colour layer under it (black strip without one).
 In a session, the dock (composer card) shares the history's centered column, at most 960px wide; its right edge follows a classic scrollbar (`--history-sb`, 0 with overlay scrollbars; index.html and `dock_reserve.js`).
 
@@ -298,8 +402,13 @@ edge, with **a shrink for each asking form and after an answer** (`forgetContent
 frame (`frameTarget` returns null) and an unfold refits to what shows. Three things decide it, kept apart: the user's
 **choice** (the ▾ by hand, in memory, written to `chi_stage_collapsed`; never read back from storage to decide, so
 another tab's write doesn't apply live), **revealed** (a ref's "show in turn" opened it for this turn; the choice stays)
-and **the docked card's fold** (the waiting card the user folded, by its key). In the asking form only that fold counts:
-the ▾ and a tap on the folded row set or clear it and write nothing (another blocking card that comes to wait meanwhile
+and **the docked card's fold** (the waiting card the user folded, by its key, held in `chi_asking_fold:<session>`
+in sessionStorage: this tab's own, so a reload or a resync mid-turn draws it folded as it was — `stage_waiting.js`
+writes it on the fold and reads it back in `trackFold` once the replay has drawn the card; it goes when the card is
+answered or cancelled (`question_cards.js`), when the fold drops, when the turn hands off, and when the page opens
+another session (`session_sync.js`); `reset` clears the memory only, so the replay can take the fold back). In the
+asking form only that fold counts: the ▾ and a tap on the folded row set or clear it and write nothing to
+`chi_stage_collapsed` (another blocking card that comes to wait meanwhile
 drops it, so the stage opens on the front card), so a card always arrives open (in the card's task, before
 `question_cards.js focusWhenIdle` focuses it) and a new one never matches an old fold; the same card drawn again with its
 id keeps it. The fold reads the registry checked against the slots first (`reconcileWaiting`), so a card answered in
@@ -423,6 +532,25 @@ writes only when its text changes. Expanded, it is a right-aligned span in the n
 the timing line in the status row (`.ts-stall-head`). Hooks: `.turn-stage.stalled` and `data-stall` (1, 2, net) on
 the stage's root. The dot keeps blinking meanwhile.
 
+## The working set's reader
+
+What chi has of one working-set item ([working-set.md](working-set.md#timeline-what-the-model-has-of-one-item)):
+`ws_timeline.js` is the pure part (the server's events into cards newest first, reads merged by state, and between the same edits, into line
+slices, the file strip, the peek's pick, the step tags from the item's `runs`: working_set.js `itemsOfTurn` keeps each
+row's `tool_id` with its place), `ws_cards.js` the cards' templates (`diff_view.js` for diffs, `.read-line` for lines),
+`ws_peek.js` the popover's peek (one row at a time; working_set_view.js draws it under the row and grows the popover to
+`PEEK_WIDTH`, a phone's sheet to `SHEET_TALL`: `chip_popover.js` reads `width`/`sheetShare` as functions per
+placing), `ws_reader.js` the reader and the wiring (`createWorkingSetPreview`: the peek, the reader, `attach(workingSet)`
+for the set, its jumps and its list, and `whatChiHas` for refs.js), `ws_way_in.js` a tool row's `timeline` button (a
+flag turn_html.js reads; on only once the reader is attached). State: the reader's own closure (the open item, its
+answer, the tab), never `store.current`. The reader is a `section` in `#center` over the history and the composer
+(both `inert` while it is open, so their scroll place stays; a phone's is `position: fixed`). Each item answer goes
+through `createLatest` keyed by the session and the item; a new server snapshot (`onServer`) asks again while it is
+open (the route's messages lag a running turn). Leaving the session closes it and the peek: `session_view.js
+forgetSession` (a switch, the start page, + New, a deleted or archived session) calls `wsPreview.reset()`, so
+`#center` is never left inert, whatever the next session's GET does; close gives focus back to where it was at the
+open (not after a jump or a reset). Styles: `ws_preview.css`.
+
 ## Stale answers
 
 The page switches sessions, reopens a popover or asks again while a fetch is out. An answer for the old ask must be
@@ -434,11 +562,11 @@ dropped. **`latest.js`** is the guard:
   ask out stale (a close, a reset). For a list that is re-read.
 
 On it: `context_chips.js`, `project_picker.js`, `participants_panel.js` (`load`), `cards_place.js`
-(`refreshCardBodies`), `stream_handlers.js` (`answer_display`), `working_set_view.js` (`fetchServer`), the
+(`refreshCardBodies`), `stream_handlers.js` (`answer_display`), `working_set_view.js` (`fetchServer`), `ws_peek.js` and `ws_reader.js` (an item's timeline), the
 turn-end re-reads (`session_view.js` `readTurnEnd`, app.js's `refreshTimingFromSession`, `mergeTurnTiming`) and app.js's init-row timers. Still by hand
 (the id decides more than "drop it"): `session_sync.js` `resync`/`retryResync` (the re-read budget, `resyncAgain`), the stream's
 close, `session_actions.js` (continue/review open another session on purpose), `send_turn.js` (a failure for another
-session becomes a toast), and `participant.js` (its own `loadSeq`, the separate page). A new await in a component
+session becomes a toast). A new await in a component
 uses `latest.js`.
 
 ## API clients
@@ -448,7 +576,8 @@ uses `latest.js`.
   HTML) or a fetch that fails on a sign-in redirect reports to `auth_lost.js` (`onAuthLost`, set by app.js).
   `cantText(what, error)` is the toast.
 - `method_api.js methodApi(method, path, body)`: the same, as `notifications.js` and `push_devices.js` call it.
-- `participant.js api`: its own (see above).
+- A participant's page uses `data.js api` too: a 401 (their link ended) goes to `participant_main.js linkEnded`
+  (`onAuthLost` set again by app.js), never the owner's signed-out banner.
 
 ## Streams
 
@@ -457,10 +586,10 @@ uses `latest.js`.
 | The hub, `GET /api/events` (`data.js openEvents`) | app.js `openSessionEvents` (scoped by `?dir`) | `snapshot` then `session` / `session_gone` → `applySessionEvent` → `allSessions`; EventSource reconnects itself (a fresh snapshot); `onClosed` (a proxy sign-in on reconnect): probe, reopen after `EVENTS_REOPEN_MS` |
 | A second hub stream, unscoped | `notifications.js` (`allEvents`) on a project's page | the Home Screen app's device tidy-up across projects |
 | The open session, `GET /api/sessions/:id/stream?from_seq=` (`data.js openStream`) | `session_sync.js` `startStream` from `store.current.streamSeq` | events → `stream_handlers.js`. It closes itself on an error; the page resyncs (`resync`: a fresh render and a new stream from its cursor), once at once when it had opened, else after `STREAM_RETRY_MS`. Meanwhile a turn the stage holds reads "reconnecting…" (Quiet, under Frames), and the Bridge's `: ping` is invisible to the page. A re-read that can't reach chi web keeps the history it drew (`resync_reach.js`): the session bar's status chip says "retrying" while `retryResync` tries, "offline" once the tries ran out (`store.current.reach`; short words that fit the chip's reserved width, the full words in its tooltip), but only while no turn runs: during a turn the stage's "reconnecting…" is the one signal (on a phone the bar can hide its status) and the chip keeps the turn's word, and any hub event for the session then re-reads it (`followSelectedSession`); the next drawn re-read clears it. Only a first load (select's "Loading…") shows the error in the history |
-| The participant stream | `participant.js connect` | listens for `STREAM_EVENTS`, which is `Web::ParticipantView::EVENTS` (checked by `spec/web/participant_view_spec.rb`); reopened from fresh data when CLOSED |
 
-A new event type for the owner page is a handler in `stream_handlers.js` (the participant view spec makes it decide
-`EVENTS` or `DROPPED`); for the participant page also an entry in `STREAM_EVENTS`.
+A new event type is a handler in `stream_handlers.js`; the participant view spec makes it decide `EVENTS` or `DROPPED`,
+and checks that every type in `EVENTS` has a handler there or in `participant_main.js` (a participant's page opens
+the same stream, filtered).
 
 ## Storage keys
 
@@ -474,13 +603,15 @@ reach another device or the server.
 | `chi_composer_collapsed` | `composer_fold.js` | the composer folded (a card's text field folds it for the time it has the focus on a narrow or touch screen, `composer_grip.js watchCardField`, on top of this and of the visit's state: neither is written) |
 | `chi_composer_floor` | `composer_grip.js`, `composer_mount.js` | the composer's dragged height |
 | `chi_strip_hidden` (`chi_zen`: the old name, read once) | `strip_hidden.js` | the session strip hidden |
-| `chi_stage_collapsed` | `stage_view.js` | the stage collapsed by hand (not written from the asking form, whose fold is that question's only) |
+| `chi_stage_collapsed` | `stage_asking.js` | the stage collapsed by hand (not written from the asking form, whose fold is that question's only) |
 | `chi_working_set_collapsed` | `working_set_rail.js` | the working set rail collapsed |
 | `chi_markdown_tip_dismissed` | `markdown_tip.js` | the markdown tip dismissed |
 | `chi_update_available_shown` | `version_notices.js` | update notices already shown |
 | `chi_notify`, `chi_push_device` | `notifications.js` (an injected storage) | the bell's state, this device's push id |
 | `chi_answer_fold:<session>` | `answer_fold.js`, `revise_stack.js` | the answers and long prompts (`<turn id>:prompt`) folded by hand, and the Revise stubs unfolded by hand (`stub:<turn id>`) (swept with the session list) |
-| `chi_review_history:<grant>`, `chi_review_history_session:<session>` | `review_history.js` (participant page) | a participant's composer history |
 
-sessionStorage: `chi_client_id` (`turn_events.js`: this tab's client id, kept over a reload mid-turn) and
+sessionStorage (this tab only, `storage.js` `readSession`/`writeSession`/`removeSession`, guarded the same way):
+`chi_client_id` (`turn_events.js`: this tab's client id, kept over a reload mid-turn),
+`chi_asking_fold:<session>` (`stage_waiting.js`: the docked card the user folded and how many cards waited at the
+fold, so a reload or a resync mid-turn draws the asking form as they left it), and
 `chi.authReloadAt` (`auth_lost.js`: one automatic reload a minute).

data/docs/internals/working-set.md

@@ -13,6 +13,17 @@ after the call: `ToolRun#stamp`, `{path:, mtime_ns:, size:}`. The path is the on
 path against the session's folder, `File.expand_path`, no realpath). A stat that fails, or that isn't a file's (a
 directory), gives no stamp; nor does any other tool.
 
+An ok `memory_read` is stamped differently: `Tools::MemoryRead.call` returns a `Tools::MemoryRead::Result`, a String
+with `reads` besides it - per name read, the file that answered and the model overlay appended to it, if any (KernelLoop
+hands those to the runner as `result[:memory_reads]`). Its stamp is
+`{memories: {name => {path:, mtime_ns:, size:, overlay: {…}}}}`, one entry per name, with no `mtime_ns` at its top.
+That is compat N-1 in both directions: a reader that only knows file stamps (`WorkingSet.stamp_of` needs a top-level
+`mtime_ns`) sees nothing in it, and a session saved before memory stamps has no stamp at all - either way its memories
+are never stale. The name it read from, and its overlay, are what "changed since" is measured against, so a system
+memory the model read is stale when its file or the overlay read with it moved, even if a project memory of the same
+name exists. A `read`, `edit` or `write` of a memory's file is still a file item: the page has no memory row for
+that path, so counting it as the memory comes with the page builds that map it too.
+
 Both `ToolResponse` shapes save the stamps as `tool_stamps`, one per run, read by the run's place
 (`ToolIds::Ref#run`):
 - `ToolResponse.joined` (the native loop's batch entry): `runs.map(&:stamp)`, only when one is non-nil, like
@@ -84,7 +95,8 @@ saved the build doesn't pair the sent conversation at all (the view returns the
 dropped` and the page offers its undrop.
 
 **Stale** is a file item whose latest run left a stamp, and whose file now differs from that stamp in mtime or size,
-or is gone. No stamp, live. A forgotten item stays forgotten whatever its file did.
+or is gone. A memory item goes the same way: the entry's file differs from the stamped one, or the model overlay
+stamped with it does, or either is gone. No stamp, live. A forgotten item stays forgotten whatever its file did.
 
 **An item's outputs.** `WorkingSet.outputs_of(conversation, kind:, key:, strategy:, cwd:)` answers an item's
 content outputs (`WorkingSet::Output`: `id`, the tool_response entry's `index`, `derived` for a legacy entry's id,
@@ -93,8 +105,9 @@ content outputs (`WorkingSet::Output`: `id`, the tool_response entry's `index`,
 when it has outputs and none is `sent`. An edit-only item, a failed run's file or an unknown key has none; a
 `memory_read` of several names is an output of each name.
 
-**Cost.** Two `paired_runs` walks, one view build and one stat per file item. A 500-message session builds in about
-10 ms on an M5 Ultra and 75 ms on a CI runner; `spec/working_set_spec.rb` only guards against a blow-up (< 400 ms).
+**Cost.** Two `paired_runs` walks, one view build, a stat per file item and one per memory stamp. A 500-message
+session builds in about 10 ms on an M5 Ultra and 75 ms on a CI runner; `spec/working_set_spec.rb` only guards
+against a blow-up (< 400 ms).
 
 ## Delivery
 
@@ -122,10 +135,11 @@ a canceled continue's restore, a failed turn's) announces the set at once (`anno
 smaller set reaches the page then, not at the next request. It goes out whatever the web's flag;
 the Bridge (`ClientEvent.project`) passes it on unchanged, and the attached TUI ignores it.
 
-**The route.** `GET /api/sessions/:id/working_set` (`Web::App#handle_working_set`) answers the snapshot's `to_h`
+**The route.** `GET /api/sessions/:id/working_set` (`Web::WorkingSetRoutes#handle_working_set`, mixed into App) answers the snapshot's `to_h`
 and `running`. With a live worker it builds from the worker's snapshot messages (as `handle_show` (`Web::SessionShow`) reads them, keys
 symbolized) and the worker's `llm_context` summary. Without one it builds from the session file and its saved chip
-(`SessionSetting::LLM_CONTEXT`). The folder is the session's `working_directory`. `running` is true when the
+(`SessionSetting::LLM_CONTEXT`); both through `working_set_source` (a `WorkingSetRoutes::Source`), which the item's
+timeline route builds from too (Timeline, below). The folder is the session's `working_directory`. `running` is true when the
 snapshot has a turn in progress (`current_turn`). Between turns, a newer worker's `idle_working_set` is used directly;
 an older worker without that key still gets the file-build fallback.
 
@@ -138,6 +152,11 @@ event's, so the page takes it (below). Before the turn's first event the turn's
 Engine emits only a set that differs from the last one), and the GET builds from the messages as between turns; so
 does one from an older worker without the field, its answer then behind the turn's events, which the page keeps.
 
+**An item's timeline while a turn runs** (`GET …/working_set/item`, [Timeline](#timeline-what-the-model-has-of-one-item))
+has no such event to answer: it always builds from the snapshot's messages, so mid-turn it lags the turn's runs
+(the running turn's reads of the item are not in it yet). Accepted for v1: the page asks again on each
+`:working_set_updated` while its reader or a peek is open, and the turn's end brings the messages up to date.
+
 ## Steering: drop and undrop
 
 `/working-set drop KEY…` and `undrop KEY…` (`WorkingSetCommand`, `SessionCommands#working_set`; the web's list posts
@@ -214,6 +233,51 @@ projection), on both loops. It costs one model step; a model may skip it (the no
   A running turn's set has none (the note was sent when it started), so the Bridge snapshot's `working_set` and the
   GET's `running` answer leave it out.
 
+## Timeline: what the model has of one item
+
+**The projection.** `WorkingSet.timeline_of(conversation, kind:, key:, strategy:, cwd:)` answers a
+`WorkingSet::Timeline` (`kind`, `key`, `events`): every run of the item in conversation order, edits and writes too,
+from the same `all_touches` walk `build` and `outputs_of` use, so the set, the steer and the timeline never disagree
+on which runs are an item's. Each `WorkingSet::Event` is `tool_id` (ToolIds; `derived` for a legacy entry's), the
+tool_response entry's `index`, the global `step` (`LLMContextStale::PairedRun#step`: the page's step tags are its own,
+see below), `op` (`read`, `edit`, `write`, `memory_read`, `memory_write`, `fetch`), `sent` (the projection's
+`still_sent?`; an edit or a write always), `dropped` (the user's applied drop), `forgotten` (not sent, not by a drop),
+and what it holds:
+- a read: `lines` (`WorkingSet::Lines`: `first`, `last`, `whole`, `partial`) from `LLMContextStale.file_run`, never
+  re-parsed from the arguments: `last` is counted off the text, so an `end_line` past the file is clamped (its
+  `[read: end_line …]` note is taken off the `text`); a whole read over `read.truncate_at_bytes` (the head/tail
+  preview) and a ToolRunner-cut output are `partial`, shown as stored, kept out of the file strip and the merging.
+  `text`: the stored output without its `[read]` lead;
+- an edit or a write: `diff`, the saved `tool_diffs` (never re-diffed): `ToolResponse.joined` saves an array (one per
+  run, nil for none), `.single` the bare Hash, read as `MessageParts` does. nil for a no-op or a failed snapshot, maybe
+  `truncated`, `{skipped}` or `{error}`; `diff_view.js diffTemplate` draws them all;
+- a memory_read: the whole output (a read of several names is not split: `shared_with` names the others, as
+  `Output#shared_with` does), and `memory` (`WorkingSet::MemoryPart`, from the stamp): `scope` (a file under
+  `memories/projects/<key>/` is the project's, else the system's), `path`, `overlay_path`, and for a read of one name
+  the appended overlay's text (`overlay`, taken off `text`); nil for a session saved before memory stamps;
+- a memory_write: the text it wrote (its `content` argument); a fetch: the output.
+
+Merging overlapping reads, the newest-first order and the step tags are the page's (presentation): the page keeps
+each row's `tool_id` with its place (`working_set.js` items' `runs`), so an event's tag is its row's (`t3·s14`) and
+"go to the call" is the step tags' jump; a legacy row (no id) falls back to the server's global `step`. The file
+strip's length is the largest last line any read knows (a whole read's is the file's then), not a stat. The page:
+[web-frontend.md](web-frontend.md#the-working-sets-reader).
+
+**Now.** `WorkingSet.memory_now(conversation, key:, …)` answers what the memory's latest `memory_read` would answer
+now (`WorkingSet::Now`: `text`, `diff`, `gone`): each name that read read, from the file its stamp names, with the
+overlay stamped with it appended as `Tools::MemoryRead.call` appends it (`Model-specific guidance (<key>):`, the key
+off the overlay's file name), and a missing name's `Error:` tail kept; `diff` is `TextDiff.unified` of what the read
+sent against that (`EditPreview`'s shape, so `diff_view.js` draws it; an empty `text` is "no change"). `gone` when a
+file is; nil without a stamp.
+
+**The route.** `GET /api/sessions/:id/working_set/item?kind=&key=` (`WorkingSetRoutes#handle_working_set_item`,
+`:owner, :session`: a participant gets 403 from `not_permitted_for`) answers `timeline.to_h`, and with `&now=1` for a
+memory `now:` too. Unlike the set's route it never answers a worker's precomputed set: it builds from
+`working_set_source` (the worker's snapshot messages, else the file's; the session's strategy and folder). Its texts
+are whole (about 1.7k lines at the most seen in real sessions): the tool limits bound them (`read.truncate_at_bytes`,
+the ToolRunner cap), so the page asks this route, never a row's `output` (a 2000-char `ToolOutputCut::WEB_PREVIEW_CHARS`
+preview for a long one). 400 without a known `kind` and a `key`.
+
 ## The page's overlay
 
 The page keeps its row-derived items and their `at` ordinals (the step tags' jump path), and overlays the server's

data/docs/releasing.md

@@ -119,7 +119,8 @@ The agent does each step and stops where the user has to say yes.
    `spec/compat_spec.rb` names it, and the shim goes (or its date moves)
    before the release. The bump also refreshes `spec/shared/compat_wire/*.json`
    by running `UPDATE_COMPAT_WIRE=1 bundle exec rspec spec/compat/wire_readers_spec.rb`;
-   commit those fixtures with the release corpus.
+   commit those fixtures with the release corpus. If that refresh fails, the
+   bump is already written; follow its rerun command before reviewing or committing.
 5. **Check.** Add all release files, including the new compatibility corpus, then run it:
    `git add -A && git commit -m "Release X.Y.Z"` and `bundle exec rake release:check`.
    Fix anything it finds in new commits and run it again.