samagotchi 0.134.0 → 0.135.0

data/docs/internals/web-frontend.md

@@ -0,0 +1,262 @@
+# The web frontend: where state lives
+
+A map of `lib/samagotchi/web/public/` for whoever changes it: where the page keeps what it knows, how a change
+reaches the screen, and the guards every new piece should use. The modules' own header comments say what each one
+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
+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.
+
+**New exports go in new modules.** The static JS is served at unversioned URLs. Today every load revalidates
+(app.rb `serve_static` sends `Cache-Control: no-cache` with a content ETag, and `sw.js` has no fetch handler), but an
+open tab still holds the modules it loaded, and a proxy that ignores `no-cache` can serve an old one: a new export
+on an existing module, imported by a new version of another, then finds the old module without it and blanks the
+page. A factory dep a new version stops passing is the same hazard the other way round: the store's redraws took
+`updateInfoBar` and the chip controls out of `stream_handlers.js`'s deps (and `updateInfoBar`/`updateComposerMode`
+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`,
+`turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
+`session_fields.js`, `feature_gates.js` and `revise_stack.js` are new modules for that reason.
+
+## Two pages, two models
+
+| Page | Entry | Model |
+|---|---|---|
+| **Owner page**: the start page and a session page | `index.html` → `app.js` | **Render once, then patch.** A session's open (`select` → `resync` → `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`) 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.
+
+## Where state lives (owner page)
+
+| Holder | What | Who writes | How a change reaches the screen |
+|---|---|---|---|
+| **The session store** (`session_store.js`; app.js `store`) | `store.selected` (the open session's id), `store.current` and `store.sessions` (below) | through the store only (see The session store); other modules get getters (`selected: () => store.selected`, `state: () => store.current`) or the store itself (`stream_handlers.js`, `send_turn.js`, `session_actions.js`) | the store runs the redraws that read what changed (below); nobody calls them by hand |
+| **app.js module scope**: about 20 top-level `let`s (`streamControl`, `eventsControl`, `pageCapabilities`/`pageEditorUrl`, `pendingVerifyAnchor`, `pendingClaim`, `resyncsInFlight`/`resyncAgain`, `resyncAttempts`, `scopeError`…) | the page's mode and its streams | app.js only; other modules get getters and hooks | the writer touches the redraw that reads it (`store.touch("infoBar")`: the stream, versions, `restartingIds`), or calls a redraw only it feeds |
+| **`store.current`** (`session_state.js`: `emptySessionState` / `sessionStateFrom`; per field: `session_fields.js FIELDS`) | the open session's fields, about 40 (info bar, chips, verdicts, timing, worker, stream cursor) | `store.update` / `setStatus` from app.js, `stream_handlers.js`, `send_turn.js` (`firstPreview`, `owner`), `session_actions.js` (`status`); `forgetSession`'s `replaceCurrent`. Two writers in place, on purpose (D8 in `FIELDS`): live_timing.js's `activeTurn`, verdict_fresh.js's running list | the store runs the field's redraws (`FIELDS[key].redraws`) |
+| **`store.sessions`** (the hub's projection) | every card | `store.update({sessions})` from app.js: `openSessionEvents` (`applySessionEvent`), `refresh` (the list fallback), `addCreatedSession`, `applyView` (re-sorted), `replaceSelectedCard` (`setLiveStatus` through `setStatus`, `readTurnEnd`, `setUsedMemories`), the stream's close (`withoutWorker`); `session_actions.js` (`setSessions`) | the store: `lists` and `infoBar`. **Always a new array**; an entry is replaced, never changed in place. `followSelectedSession` copies the open one's owner and worker (`fieldsFromCard`) and, when not streaming, its status (`setStatus(…, "hub")`) into `store.current` |
+| **Factory closures**: the `create*` factories (popovers, panels, views) | each component's own state: open-for, busy, error, its own fetched list | the factory | an `onChange` hook back into app.js, or a getter the factory reads at draw time |
+| **The history DOM** | the conversation as drawn: which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), kept command bubbles, which texts were shown, unnamed badges, folded answers (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`) | `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` 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) |
+| **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 |
+
+The start page's own choices (the model, the ⚙ panel, the 🧰 list) live in `start_page.js`'s closure, never in
+`store.current`. A fresh chain link's picker reads both.
+
+## The session store
+
+`session_store.js` holds the open session's state; `session_fields.js` says what each field is. **Every write goes
+through the store**, never `current.X = …`:
+
+- `store.update({selected?, current?: {field: value}, sessions?})`: `current`'s fields are written into the same
+  object (it is replaced only by a session switch); `sessions` is always a new array (one changed in place isn't
+  seen).
+- `store.setStatus(value, source, {streaming})`: the one way `status` changes (below).
+- `store.replaceCurrent(state)`: `forgetSession` only; always a new object, so a stale async writer still holding the
+  old one writes there alone.
+- `store.batch(fn)`, `store.touch(name)`, `store.on(name, fn)`: the redraws (below).
+
+The ESLint block `samagotchi/session-writes` (eslint.config.js) enforces it in the six modules that hold the state
+(app.js, `stream_handlers.js`, `send_turn.js`, `session_actions.js`, `start_page.js`, `working_set_view.js`): an
+assignment, `++`, `delete` or `Object.assign` into `current`, `store.current` or `state()` is an error
+(`spec/web/public/lint_session_writes.test.js` runs it on a sample). An alias (`const st = state(); st.x = …`) isn't
+caught: don't write through one.
+
+**Read `store.current` fresh after every await.** A `const cur = store.current` held across an await pins the object
+from before it, which a session switch (`forgetSession`) may have replaced: app.js's `readTurnEnd`,
+`mergeTurnTiming`, `resync` and `refreshTimingFromSession` read it again after each await. Keep `store.sessions`
+reads fresh too.
+
+### Fields and their redraws
+
+`session_fields.js FIELDS` has one entry per `emptySessionState` key: its payload source (a partial re-read takes a
+field only when the payload carries it: `session_payload.js` reads its sources from here), its hub card source
+(`fieldsFromCard`: owner, workerVersion, workerFeatures, bridgeUp; never status), its redraws (store `ORDER` names)
+and its writers. A new field starts in `emptySessionState` and gets an entry (its spec checks both).
+
+A changed value (`!==`) marks its field's redraws; `sessions` marks `lists` and `infoBar` (the bar reads the list:
+the chain's ← → links, the children chip, the archived button, the card's title, the fresh link's picker); `selected`
+marks `paintActive`, `composer` and `infoBar`; `touch(name)` marks one redraw for an input the store doesn't hold
+(the clock, versions, the stream, `liveTurn.running`). They run synchronously, once each, at the end of the outermost
+`batch()` (at once for a bare write), in one `ORDER`: `lists`, `paintActive`, the chip popovers (`llmContextChip`,
+`thinkingChip`, `reasoningChip`, `workingSetStrategy`), `featureGates`, `composer`, `infoBar`. `lists` comes before
+the bar because `updateSessionTitle` reads the strip's active card; `composer` before the bar as `setTurnRunning`
+runs them. Not a rAF (a background tab runs none, and the title badge tests run there; the e2e per-frame checks would
+see the composer move a frame late) and not a microtask (code that reads the page right after a write would see it
+stale).
+
+**The redraws are registered, not called.** app.js registers each name once (`store.on`, at the bottom, once every
+piece a redraw calls exists): `lists` → `lists.render()`, `paintActive` → `lists.paintActive()`, the chips →
+`xControl.refresh()`, `workingSetStrategy` → `workingSet.strategyChanged()`, `featureGates` (below), `composer` →
+`updateComposerMode()`, `infoBar` → `updateInfoBar()`. A writer writes and stops there: no `updateInfoBar()` after
+a store write. A value written unchanged redraws nothing (a chunk with the same ctx %).
+
+An input the store doesn't hold calls `store.touch(name)` where it changes: `infoBar` for the clock (liveTurn's
+`onTick`), the versions (`noticeVersions`), `restartingIds`, the stream (`startStream`, `workerGone`), the working
+set's and the participants' `onChange`, the copy-attach timer, the continue and review in-flight sets
+(`session_actions.js`); `composer` and `infoBar` for `liveTurn.running` (`setTurnRunning`) and at the end of
+`renderSessionView` (a whole view drawn). Left as they are, on purpose: the `narrowScreen` listener calls
+`updateComposerMode()` (the bar doesn't read it), `applyStripHidden`/`applyView` call `updateSessionTitle()`, and
+`closeStream`/`stream.restart` set `streamControl = null` without a redraw (a resync or a workerGone follows).
+
+A function that writes more than once batches its synchronous part, so each redraw runs once: `select` (before its
+`await resync()`), `clearSelection`, the hub's `snapshot` and `session` events, `workerGone`, `setTurnRunning`,
+`turn_started` (inside `keepFollowing`, so the composer and the bar redraw before its scroll), `readTurnEnd` (after
+its timing merge), `setUsedMemories`, and `renderSessionView`'s field write only: the replay's own
+`setTurnRunning` redraws where they run, before `turnDom.flush()`. A stream handler writes one patch.
+
+`batch(fn)`:
+- `fn` is synchronous: one that returns a promise is refused (`console.error`, the redraws run at once). Batch an
+  async function's synchronous parts only, never across an await.
+- The redraws run in `finally`, also when `fn` throws (the page shows what was written), then `fn`'s error is
+  rethrown; a redraw error meanwhile goes to `console.error`. A throw never leaves the store inside a batch.
+- During a flush, a write, a touch or a batch's end only enqueues: the next pass runs it, after the current pass's
+  `ORDER`. Passes stop at 3 (`console.error` names the redraw). A redraw that throws doesn't stop the others; its
+  error is thrown after the flush.
+
+### `status`
+
+Six writers, each with its rule, all through `setStatus(value, source)` (`session_fields.js statusWrite`):
+
+| source | writer | applies | the open session's card |
+|---|---|---|---|
+| `payload` | `renderSessionView` | always | left alone |
+| `hub` | `followSelectedSession` | only while the stream isn't live | left alone (the card came from the hub) |
+| `stream` | `setLiveStatus` (`turn_*`, `workerGone`'s idle) | always | `withLiveStatus`: status, owner, `updated_at` |
+| `turnEnd` | `readTurnEnd`, the turn_canceled re-read (`refreshTimingFromSession`) | when the payload carries one (the caller skips it otherwise), and **not while a turn runs**: a re-read that lands after the next queued turn's `turn_started` doesn't write its stored "idle" over "running" (the test `mergeTurnTiming` keeps `activeTurn` by) | left alone: `readTurnEnd` writes its card itself after its timing merge, with `used_memory_names` |
+| `stop` | `session_actions.js stoppedWorker` | always | left alone (`workerGone`'s `withoutWorker` changes it) |
+
+`setStatus` answers whether it replaced the card; the new list redraws the lists and the bar by itself.
+
+### Feature gates
+
+A page action the open session's worker must support (its sidecar features and a live bridge) is a gate in
+`feature_gates.js`, registered as the store's `featureGates` redraw: `{name, unavailable(current), redraw}`. It runs
+when a field it reads changes (`workerFeatures`, `bridgeUp`), and a gate's `redraw` only when its answer flipped: a
+restart's hub event that brings the feature enables it, the worker going (`workerGone`'s `bridgeUp = false`) says
+it's unavailable. `forgetSession` and `renderSessionView` draw the history with the answer already, so they `prime()`
+the gates in the batch of their write, and nothing fires. Today two gates: `verify` (Verify fresh on a verdict's
+card, `redrawFresh`) and `revise` (the answers' Revise buttons and the composer's Revising chip, `redrawRevise`).
+Both refuse only a live worker without the feature: a worker that isn't up is woken by the send as a new one, which
+has it. A new action that needs a worker feature is one more entry.
+
+### Exceptions
+
+- **Writers in place (D8)**, named in `FIELDS`: live_timing.js sets `timing().activeTurn` (the running turn's own
+  clock; `mergeTurnTiming` keeps it), and verdict_fresh.js `startFresh` pushes onto `fresh.running`, which is
+  `store.current.verifyFresh`.
+- **Events, not state (D9)**: these stay direct calls next to their write: a `/model`'s picker sync
+  (`syncModelPick`), the working set's `commandRan`, the context chips on a note, the participants reload, a
+  verdict's own `renderFresh`. (The working set's `strategyChanged` and the Verify gate's `redrawFresh` follow
+  fields: they are registered redraws.)
+
+A partial re-read of the open session (a `?tail`/`?recent` read) goes through **`applySessionPayload(data,
+{fields})`** in app.js (`session_payload.js sessionFieldsFrom`): the named fields read as a full load reads them, a
+field whose source the payload doesn't carry left alone; its status goes through `setStatus(…, "turnEnd")`. Their
+redraws follow. Never copy payload keys into `store.current` by hand.
+
+The redraws, by their store names:
+- `infoBar` (`updateInfoBar()`): the session bar's buttons and info line (`info_bar_model.js sessionBar` →
+  `info_bar.js`), the annotate bar, the fold controls, `updateSessionTitle()` and the fresh link's picker. Cheap: it
+  runs on most writes and every clock tick.
+- `composer` (`updateComposerMode()`): the composer's placeholder, buttons and delivery line (selected, running,
+  owner).
+- `llmContextChip`, `thinkingChip`, `reasoningChip` (`xControl.refresh()`): an info-bar chip's **open popover** (the
+  chip itself is drawn by the bar); `workingSetStrategy`: the working set's open list.
+- `lists` / `paintActive` (`lists.render()` / `lists.paintActive()`): the strip and the all view from
+  `store.sessions`.
+- `featureGates`: the gates above.
+
+`forgetSession()` is the one reset: `select` and `clearSelection` both call it, so anything per-session that isn't
+in `store.current` (capabilities, the markdown warning and tip, the init row, the Verify claim, the armed Revise,
+the running turn's DOM) is cleared there, and the feature gates are primed for the empty session. A new per-session holder
+(an armed composer anchor like the Verify claim or the Revise) goes into it. The armed Revise
+(`pendingReviseAnchor`) is set only through `setReviseAnchor`, which redraws its chip and the Revise buttons (a
+redraw only it feeds, not a store field).
+
+## Render idioms
+
+Three, for one job. Pick by what the piece is:
+
+| Idiom | Where | Use it for |
+|---|---|---|
+| **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 |
+
+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,
+Esc, placement and resize); `context_chips.js`, `model_picker.js`, `ref_menu.js`, `command_list.js` and the lists'
+families/chains popovers still hand-roll theirs.
+
+## 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
+dropped. **`latest.js`** is the guard:
+
+- `stillOn(get, at = get())`: `() => true` while `get()` is still `at`. For a one-off read about the open session
+  (`const still = stillOn(openId); … await …; if (!still()) return;`). app.js has `openId = () => store.selected`.
+- `createLatest(get)`: `begin()` gives a guard that also goes stale when a newer ask begins; `drop()` makes every
+  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`) and app.js's
+turn-end re-reads (`readTurnEnd`, `refreshTimingFromSession`, `mergeTurnTiming`) and init-row timers. Still by hand
+(the id decides more than "drop it"): app.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
+uses `latest.js`.
+
+## API clients
+
+- `data.js api(path, opts)`: the owner page's. Throws an `Error` with the server's words, `.status`, `.code` (the
+  server's error code: match on it, never on the words) and `.body`; a signed-out proxy answer (401, a redirect,
+  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).
+
+## Streams
+
+| Stream | Opened by | Lifecycle |
+|---|---|---|
+| 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`) | app.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` |
+| 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`.
+
+## Storage keys
+
+Through `storage.js` (`readStored`/`writeStored`: storage can throw, a missing value is the default), except
+`notifications.js`, which takes an injected storage for its specs. Per-browser choices only: never anything that must
+reach another device or the server.
+
+| Key | Module | What |
+|---|---|---|
+| `chi_model`, `chi_model_recent` | `model_pick.js`, `model_picker.js`, `start_page.js` | the start page's model and its recent list |
+| `chi_composer_collapsed` | `composer_fold.js` | the composer folded |
+| `chi_composer_floor` | `composer_grip.js`, `composer_mount.js` | the composer's dragged height |
+| `chi_strip_hidden` (`chi_zen`: the old name, read once) | app.js | the session strip hidden |
+| `chi_stage_collapsed` | `stage_view.js` | the stage collapsed |
+| `chi_working_set_collapsed` | `working_set_rail.js` | the working set rail collapsed |
+| `chi_markdown_tip_dismissed` | `markdown_tip.js` | the markdown tip dismissed |
+| `chi_update_available_shown` | app.js | update notices already shown |
+| `chi_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 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
+`chi.authReloadAt` (`auth_lost.js`: one automatic reload a minute).

data/docs/sessions.md

@@ -6,6 +6,8 @@ Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/s
 
 **Verify verdicts:** a web Verify turn stamps its opening user message with `verify: {turn_id, quote}` (the selected source turn and quote; metadata only, never added to the prompt). When that turn completes and the final assistant reply's last non-empty line is a valid `Verdict: confirmed|refuted|unclear — <reason>`, the session file appends `{anchor: {turn_id, quote}, verdict, reason, by, check_turn_id, at}` to its optional `verdicts` array. `by` is the turn's author (nil for the owner), `check_turn_id` names the Verify turn, and `at` is its timestamp. The array is append-only; older files without it have no saved verdicts. An `unclear` verdict can be checked again by **Verify fresh** (a delegate child that gets only the claim; see *Delegating*): its verdict is appended to the parent's `verdicts` with `fresh: true`, `of` (the verdict it checked again) and `child_id`, from the parent's `fresh_verdicts/` dir, which its worker takes between turns. Verdicts are display state: none enters a prompt.
 
+**Revise stacks:** a web Revise turn (POST /turn `revises: {turn_id}`, the answer it rewrites) stamps its opening message (its prompt) with `revises: {turn_id}` at the turn's end, only when the turn completed with an answer (`AnswerTail`): a failed, canceled or empty turn revised nothing (`Engine#stamp_opening`). A draft no prompt carries (a stale page, a rolled-back turn) is no target: no stamp. A draft a stamped turn already revised is re-targeted to its stack's top, the newest version, so a stack is a chain `v1 ← v2 ← v3`. Like `verify`, it is metadata only, never added to the prompt (no change to a request's bytes); chi web's history passes it on the opening message (and on a wake turn's note), and `:turn_completed` carries the stamped `revises` (the participant view's too). The history also marks a Verify turn's opening `verify: true`: the page offers no Revise on its answer. The web page draws the stacks from these stamps (docs/cli.md, Revise). Like a Verify turn's, a Revise message waits for the running turn's end (`SessionInbox.turn_end_data?`), is sent only to a worker whose `bridge.json` names the `revise` feature (else 409 `revise_unavailable`), and a failed turn gives it back (`:prompt_restored`'s `revises`). Participants can't Revise: chi web and the Bridge drop it from their turns. Both anchors travel as one `TurnAnchors` inside chi; on the wire and in an input file each keeps its own key (`verify`, `revises`).
+
 **Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). Such a file, with a prompt, from the user, `chi send` or a delegating parent, also ends a running `task_wait` (`SessionInbox.steer_waiting?`, a peek the worker's turn polls through `Engine#input_waiting?`; never in a participant's turn): the file stays for the drain. A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). A session command recognized in a file runs without a turn; its outcome is kept at `input/settled/<enqueued_id>` (`completed`, `failed` for a command error, `canceled` with `cancel_reason` `busy` or `dropped` for one refused mid-turn or dropped as the worker left; `origin: command`) so `chi send --wait` ends instead of waiting for a turn that will not run, its detail saying `the command failed` or `the command was refused (busy)` rather than a turn's words. **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
 
 **Removing a queued message:** a message queued for after the running turn (`chi send --queue`, the web's Alt+Enter, `/queue TEXT` in a terminal), or one with images (it waits for the turn's end too), can be taken back while it still waits: the worker's Bridge (`POST /session/:id/turn/dequeue {enqueued_id}`, the `unqueue` feature) deletes its input file and every UI drops it (`:turn_dequeued`). It is a race with the turn's end, decided by the same rename the worker uses to take the file: once a turn took it the answer is `409 already_started` (it runs), and an id the worker no longer knows is `404 unknown_enqueued_id`. A plain message sent without `--queue` is not removable (`409 not_queued`): a running turn's next step may take it at any moment. A wait for its turn (`chi send --queue --wait`, a delegate follow-up's wait) ends at once with `removed` (the tombstone `input/removed/<enqueued_id>` says so), and a `chi -p` run whose queued prompt went ends with exit 1. The `200` carries the removed `prompt`: the web and the attached terminal put it back into the composer to edit (not its images). The images a removed message named stay in the session's `images/`. Not removable: a queued session command (`/queue /model x`: it waits in the worker, not in `input/`), a message in a stopped worker's inbox (the next worker runs it), and the plain REPL's (`--no-shared`) own queue.

data/docs/testing.md

@@ -24,7 +24,9 @@ style pass: add a rule only for a bug class it would have caught. It runs in abo
 global (`name`, `status`, `open`…) passes even when its import is gone: give an export such a name only with care.
 It also checks `spec/e2e/` for one thing, the Playwright twin of `Samagotchi/SpecSleep`: no `page.waitForTimeout`.
 Wait for the state (a locator's `expect`, `data-phase`, an animation's end through `waitForFunction`); a pause that
-is the behaviour (a pointer's dwell) carries `// eslint-disable-line no-restricted-syntax -- why`.
+is the behaviour (a pointer's dwell) carries `// eslint-disable-line no-restricted-syntax -- why`. And in the six
+modules that hold the owner page's session state, one more: no write into `current`, `store.current` or `state()`
+in place (`samagotchi/session-writes`; the store is the write path, see internals/web-frontend.md, The session store).
 
 CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
 (`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
@@ -41,7 +43,7 @@ paths (replace them with placeholders), no PATH tools (the suite pins `rg` as fo
 that sets PATH to test the lookup is tagged `:real_rg`), no Ruby-version-dependent `inspect` (a Hash's or an
 exception's text changes between Ruby versions: write the string yourself).
 
-The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
+The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_block.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
 `chains.js`, `working_set_view.js`, `working_set_rail.js`, `unqueue.js`, `toasts.js`, `notice_links.js`, `start_page.js`, `start_settings.js`, `start_toolkit.js`, `session_actions.js`, `send_turn.js`, `composer_mount.js`, `dock_reserve.js`,
@@ -69,6 +71,28 @@ either router adds its row there; a row where a UI differs on purpose (or a foun
 `repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
 `CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
+## Levels
+
+Each level owns its own share; a detail is asserted once, at the lowest level that has it.
+
+| Level | Ruby | Web | Owns |
+|---|---|---|---|
+| Unit | a class, its collaborators stubbed or passed in | `npm test` (node; happy-dom for lit) | the details and the variants: a message's text, each refusal, the edge cases |
+| Functional | a component through its real seams in one process (an Engine on `test_kernel`, a real Bridge, `Web::App` on Rack) | chi web's routes (`spec/web/`, Rack) | the component's happy path and its main negative paths, and the payload it hands the next layer |
+| Process / e2e | a real `bin/chi`, worker or script (`run_chi`, a spawned process) | Playwright (`npm run e2e`) | one run per mechanism (the wiring a lower level can't see: a require, a spawn, a real browser), and a few whole journeys |
+
+- **The variants are the units'.** A higher-level spec says which mechanism it is the one test of and where its
+  variants live (`remote_attach_stream_spec.rb`, `steer_delivery_e2e_spec.rb`, `terminal_ui/attached_loop_bridge_spec.rb`).
+- **One real chi per mechanism** (spec/support/chi_cli.rb): a file keeps one `run_chi` per mechanism and forks the
+  rest (`fork_chi`). A script that runs chi (a bundle's `scripts/pair`) likewise: its mechanism on real chi, its
+  variants on a fake one (`FakeChiContext`).
+- **A spec that spawns per assertion gets a seam.** A unit spec that starts a process for every check (a `git`, a
+  Ruby boot) passes the collaborator in or fakes it: a guardrails `Context` takes `git:`, so give it one `GitInfo`
+  per example, as the wiring keeps one per turn.
+- **e2e** is for real-browser behaviour (layout, focus, reload, two tabs), one happy path per Ruby↔web mechanism and
+  a few journeys. Before adding a test, extend an existing journey's step; a variant goes to node, a Ruby↔web shape
+  variant to a shared fixture (`spec/fixtures/composer_routes.json`).
+
 ## Waiting and time
 
 A spec waits *for* something and never sleeps to wait: a fixed pause is too short on a loaded runner (a parallel
@@ -184,6 +208,7 @@ any other file requires it, so a spec file run alone still finds its requires. E
 | `env.rb` | *helper*: `with_env` sets ENV for a block and puts it back (nil unsets) |
 | `failing_saves.rb` | shared context "failing session saves": `Session#save` raising ENOSPC while `saves_fail`, and the worker's `save_failed` records |
 | `fake_chat_adapter.rb` | `FakeChatAdapter`: an `LLM::OpenAIChat` stand-in answering `#chat` with queued steps, recording each request |
+| `fake_chi_context.rb` | `FakeChiContext`: a fake `chi context add/show/push/rm/ls` for the peer bundles' `scripts/pair` variants, logging each call |
 | `fake_executables.rb` | `FakeExecutables`: fake commands (`gh`, `git`) for a spec's PATH, symlinks to one launcher (macOS's first-exec check is paid once) |
 | `fake_provider_server.rb` | `FakeProviderServer`: an in-process HTTP provider replaying spec/fixtures/providers, recording requests |
 | `fake_tailscale.rb` | A fake `tailscale` for `Web::Tunnel::Tailscale` (status, serve, lock from JSON files; argv.log) |

data/lib/samagotchi/bridge.rb

@@ -11,7 +11,7 @@ require_relative "atomic_file"
 require_relative "bridge_secret"
 require_relative "delivery"
 require_relative "session_inbox"
-require_relative "verify_anchor"
+require_relative "turn_anchors"
 
 require_relative "bridge/bounded_queue"
 require_relative "bridge/card_store"
@@ -634,7 +634,7 @@ module Samagotchi
     # turn (Guardrails::PairBoundary); a worker without it runs it as a
     # review turn, and chi web says so (Delivery::PAIR_FEATURE).
     FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE,
-                VerifyAnchor::FEATURE,
+                VerifyAnchor::FEATURE, ReviseAnchor::FEATURE,
                 SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
@@ -1073,7 +1073,10 @@ module Samagotchi
       # request's principal; the Bridge is loopback and trusts its caller).
       author = fetched(parsed, "author")
       author = nil unless author.is_a?(String) && !author.empty?
-      verify = VerifyAnchor.from(fetched(parsed, "verify"))
+      # A Verify turn's claim, a Revise turn's draft; a participant can't
+      # Revise (chi web drops it first, this is the worker's own layer).
+      anchors = TurnAnchors.from(parsed)
+      anchors = anchors.without_revises if Steer.participant_author?(author)
       if sid.to_s.strip.empty? || prompt.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400,
                 { error: "missing_fields", detail: "session_id and prompt are required" }]
@@ -1135,7 +1138,7 @@ module Samagotchi
         delivery = Delivery::QUEUE if @accumulator.participant_turn?
         queued_behind_turn = Delivery.queue?(delivery) && !@accumulator.current_turn.nil?
         enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                     no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, verify: verify).tap do |ok|
+                     no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, anchors: anchors).tap do |ok|
           next unless ok
 
           enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
@@ -1299,9 +1302,11 @@ module Samagotchi
 
     # Write a turn into this session's input dir, reusing the file IPC the
     # worker polls. Never calls run_turn across the boundary.
-    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil, author: nil, verify: nil)
+    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil, author: nil,
+                     anchors: nil)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, verify: verify)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author,
+                                            anchors: anchors)
     end
 
     # ── HTTP plumbing ────────────────────────────────────────────────────────

data/lib/samagotchi/bridge_client.rb

@@ -14,8 +14,10 @@ require_relative "bridge_client/event_stream"
 require_relative "bridge_client/stream_request"
 
 module Samagotchi
-  # Loaded on first use (a Verify turn): keeps the bundle test kit's load
-  # budget (spec/samagotchi/testing/sandbox_spec.rb).
+  # Loaded on first use (any turn's input, a Verify or a Revise turn's
+  # anchor): keeps the bundle test kit's load budget
+  # (spec/samagotchi/testing/sandbox_spec.rb).
+  autoload :TurnAnchors, File.expand_path("turn_anchors", __dir__)
   autoload :VerifyAnchor, File.expand_path("verify_anchor", __dir__)
 
   # Client side of a session worker's Bridge: the 127.0.0.1 HTTP + SSE server
@@ -192,16 +194,17 @@ module Samagotchi
     #   owner; sent only when given (SessionManager.deliver_turn)
     # @param pending_limit [Integer, nil] with a participant's +author+: how
     #   many of their turns may be running or waiting (429 too_many_turns past it)
+    # @param anchors [TurnAnchors, Hash, nil] a Verify turn's claim, a Revise
+    #   turn's draft: their own body keys ("verify", "revises")
     def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil, pending_limit: nil,
-                  verify: nil)
+                  anchors: nil)
       body = { session_id: @session_id, prompt: prompt, client_id: client_id }
       body[:no_interrupt] = true if no_interrupt
       body[:author] = author if author
       body[:pending_limit] = pending_limit if author && pending_limit
       body[:images] = images if images && !images.empty?
       body[:delivery] = delivery unless delivery.nil? || Delivery.next_step?(delivery)
-      anchor = VerifyAnchor.from(verify)
-      body[:verify] = anchor.to_file if anchor
+      body.merge!(TurnAnchors.from(anchors).to_file) if anchors
       body[:deadline] = deadline
       post("turn", body, read_body: true)
     end

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.134.0
+version: 0.135.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/config.rb

@@ -330,8 +330,6 @@ module Samagotchi
       Entry.new(key: "web.port",                 yaml_path: %w[web port],                 type: :integer, default: 4567,            expose: %i[env config cli], lifecycle: :web_start),
       Entry.new(key: "web.host",                 yaml_path: %w[web host],                 type: :string, default: "127.0.0.1",     expose: %i[env config cli], lifecycle: :web_start),
       Entry.new(key: "web.markdown",             yaml_path: %w[web markdown],             type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
-      # The page's view of a turn: stage (the running turn pinned above the composer) or turn (one block of generations, the live one at the bottom); ?view= overrides it per page load.
-      Entry.new(key: "web.view",                 yaml_path: %w[web view],                 type: :enum,    default: "stage",        expose: %i[env config cli], enum_values: %w[stage turn], lifecycle: :web_start),
       # The stage view's working set (files, memories and URLs the turn brought into context): a rail in the stage, a
       # footprint under each finished turn and a "set N" chip in place of the mem chip; ?working_set=1|0 overrides it per page load.
       Entry.new(key: "web.working_set",          yaml_path: %w[web working_set],          type: :bool,    default: true,            expose: %i[env config cli], lifecycle: :web_start),

data/lib/samagotchi/engine.rb

@@ -15,6 +15,7 @@ require_relative "steer"
 require_relative "turn_note"
 require_relative "turn_endings"
 require_relative "turn_origin"
+require_relative "revise_anchor"
 require_relative "verify_anchor"
 require_relative "web/participant_view"
 require_relative "verdict"
@@ -1631,10 +1632,11 @@ module Samagotchi
       seconds = turn.elapsed
       synchronize_events do
         kept, event = yield(seconds)
-        stamp_verify_anchor(kept, turn)
+        revises = stamp_opening(kept, turn, outcome)
         replace_session_messages(turn.session, kept) if kept
         verdict = record_verdict(turn, outcome)
         event[:verdict] = verdict if verdict
+        event[:revises] = revises.to_h if revises
         emit_working_set(turn.on_event, turn.session, turn.session.messages)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
@@ -1647,16 +1649,63 @@ module Samagotchi
     end
     private :end_turn
 
-    def stamp_verify_anchor(messages, turn)
-      return unless turn.verify && messages.is_a?(Array)
+    # The turn's anchors, stamped on its opening message (the prompt, or a
+    # wake turn's note) in the messages it keeps: display metadata, never
+    # in the prompt (LLM::ChatLoop#plain keeps them, no wire sends them).
+    # A Verify turn's claim however it ended; a Revise turn's draft only
+    # once it completed with an answer (#revision_target). Returns the
+    # stamped ReviseAnchor (the end event's revises), or nil.
+    def stamp_opening(messages, turn, outcome)
+      return unless messages.is_a?(Array)
+
+      revises = revision_target(messages, turn, outcome)
+      fields = { verify: turn.verify&.to_h, revises: revises&.to_h }.compact
+      return if fields.empty?
 
       opening = messages.reverse.find do |message|
-        (message[:role] || message["role"]).to_s == "user" &&
-          (message[:turn_id] || message["turn_id"]).to_s == turn.id
+        Steer.turn_prompt?(message) && (message[:turn_id] || message["turn_id"]).to_s == turn.id
       end
-      opening[:verify] = turn.verify.to_h if opening
+      return unless opening
+
+      opening.merge!(fields)
+      revises
+    end
+    private :stamp_opening
+
+    # The turn a Revise turn revised (D6: "this turn revised that one"):
+    # only a completed turn with an answer (AnswerTail) has revised
+    # anything. A draft no prompt in the messages carries is no target (a
+    # stale page, a rolled-back turn); one a stamped turn already revised
+    # is re-targeted to its stack's top, the newest version, which the
+    # person meant ("this draft").
+    def revision_target(messages, turn, outcome)
+      return unless turn.revises && outcome == "completed"
+
+      slice = AnswerTail.turn_slice(messages, turn.id)
+      return unless slice&.any? { |message| AnswerTail.answer?(message) }
+
+      target = turn.revises.turn_id
+      seen = [turn.id]
+      until seen.include?(target)
+        return reject_revise_anchor(turn.revises, :turn_missing) unless AnswerTail.turn_slice(messages, target)
+
+        seen << target
+        newer = messages.reverse.find do |message|
+          Steer.turn_prompt?(message) && ReviseAnchor.from(message[:revises] || message["revises"])&.turn_id == target
+        end
+        return ReviseAnchor.new(turn_id: target) unless newer
+
+        target = (newer[:turn_id] || newer["turn_id"]).to_s
+      end
+      reject_revise_anchor(turn.revises, :cycle)
+    end
+    private :revision_target
+
+    def reject_revise_anchor(anchor, reason)
+      Log.warn(:turn, "revise_anchor_rejected", turn_id: anchor.turn_id, reason:)
+      nil
     end
-    private :stamp_verify_anchor
+    private :reject_revise_anchor
 
     def verified_anchor(session, anchor)
       return unless anchor
@@ -2150,8 +2199,9 @@ module Samagotchi
     # Continue that starts cold (after a model change).
     # +wall+: the wall time it started (MessageTime.now, once): the
     # :turn_started event's at and its user message's (and reminders') stamp.
+    # +verify+, +revises+: a Verify turn's claim, a Revise turn's draft.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify) do
+                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify, :revises) do
       def resumed? = resumed ? true : false
 
       # The turn's boundary events carry the origin only when it names a
@@ -2215,6 +2265,9 @@ module Samagotchi
     # @param id [String, nil] the turn's id (a new uuid when nil): a caller
     #   that put the turn's first message in the session already (a context
     #   wake's note) names it with this id
+    # @param verify [VerifyAnchor, nil] a Verify turn's claim (its verdict)
+    # @param revises [ReviseAnchor, nil] a Revise turn's draft: stamped on
+    #   the prompt at the turn's end, metadata only (#stamp_opening)
     #
     # An Interrupt (SIGINT) cancels the turn: what it got to is kept in the
     # session as after a Stop (the prompt, the loop's finished tool
@@ -2226,9 +2279,11 @@ module Samagotchi
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
     def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false,
-                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil, verify: nil, input_waiting: nil)
+                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil, verify: nil, revises: nil,
+                 input_waiting: nil)
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
-                                         continue: continue, id: id, verify: verify, input_waiting: input_waiting)
+                                         continue: continue, id: id, verify: verify, revises: revises,
+                                         input_waiting: input_waiting)
       if continue
         turn.resumed = resumed
         turn.resume_from = resume_from
@@ -2276,7 +2331,8 @@ module Samagotchi
     # The turn's state before anything can fail it: the session running,
     # the turn flag, its cancel controller and sink. The cross-thread state
     # is set here and cleared in #release_turn only.
-    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil, input_waiting: nil)
+    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil, revises: nil,
+                   input_waiting: nil)
       origin = TurnOrigin.of(origin)
       # A participant's Verify fresh child: every turn is theirs (their
       # author, boundary and cap), whoever started it.
@@ -2304,7 +2360,8 @@ module Samagotchi
 
       Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
                controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-               id: id || SecureRandom.uuid, wall: MessageTime.now, verify: VerifyAnchor.from(verify))
+               id: id || SecureRandom.uuid, wall: MessageTime.now, verify: VerifyAnchor.from(verify),
+               revises: ReviseAnchor.from(revises))
     end
     private :begin_turn