samagotchi 0.154.0 → 0.155.0

data/docs/internals/inline-widgets.md

@@ -0,0 +1,136 @@
+# Inline widgets: chi-ui blocks the page draws
+
+A model can write a ```` ```chi-ui ```` fence in an answer: YAML, `type:` first, a **picks** (rows of options to choose
+from, which fill the reply) or a **walk** (a scenario stepped through). Core draws it, not a bundle: the server parses
+the YAML once and the page draws from the parsed data. Where it doesn't draw (the terminal, `web.markdown` off, a
+refused block) the YAML reads as text. The server half (the parse) and the page half (the drawers) are below.
+
+What tells the model the blocks exist is the shipped inline-widgets bundle
+([bundles.md](../bundles.md#the-inline-widgets-bundle)): two prompt sections, `picks` and `walk`, each with an example
+its spec holds to a strict parse. Without it nothing here changes, and blocks already in a history still draw.
+
+## The path
+
+1. `Web::MarkdownRenderer#fences` walks the `code_block` nodes, as for block renderers' `data-lang`
+   ([block-renderers.md](block-renderers.md), The path), keeping each one's language and its literal
+   (`string_content`, the source between the fences, also inside a list item or a blockquote) as a `Fence`.
+2. After sanitize's walk, `mark_languages` pairs them with the `<pre>`s by position and, for a `chi-ui` one, calls
+   `InlineWidgets.parse(literal)`. The block gets `data-widget` (the JSON of the data with its `type`) or
+   `data-widget-error` (the one-line reason), and `data-widget-lenient` when the lenient pass was needed. A count
+   that differs sets nothing, as for `data-lang`.
+3. Every HTML path goes through `render`, so answers, cards, delegate reports and `/api/render` all carry the
+   attributes; which of them draw is the page's choice (answer texts only).
+4. `chi-ui` is `BlockRenderers::RESERVED`: a bundle's `block_renderers:` can't claim it, so the page never has two
+   drawers for one block.
+
+**Safety.** The JSON is an attribute value: Nokogiri escapes its quotes, and `<`, `>` and `&` in it are `\u` escapes
+(`JSON_MARKUP`), so the HTML holds no model markup even as attribute text. The page draws its strings as text.
+
+## The parse (`Samagotchi::InlineWidgets`)
+
+Pure Ruby, no web, no Engine. `parse(source)` returns a `Result`: `ok?`, `type`, `data` (string keys, JSON-ready),
+`lenient?`, `error`, and `widget_json`.
+
+- **Strings stay strings.** The YAML is never loaded: `Tree` reads Psych's node tree and takes each scalar's own text.
+  YAML 1.1 would make `- no` false (a real eval block has one), `id: 1.10` the float 1.1, and a date a `Date` that
+  `safe_load` refuses. A plain empty value, `~` or `null` is absent.
+- **Plain data only.** An anchor, an alias or a tag (`!ruby/object`, `!!str`) is refused, as is a second document, a
+  key that isn't a scalar, a root that isn't a mapping, text that isn't valid UTF-8, and nesting past 8 levels
+  (`MAX_DEPTH`; the deepest legal block nests 6). A stack overflow is rescued too, as the backstop: it is no
+  `StandardError`, so it would escape `render` and break every render of the history.
+- **Strict first, then the lenient pass.** Only a block Psych can't parse gets `Lenient.quote` and a second parse.
+  The pass is eval 0013's (`~/.claude/plans/evals/0013-inline-widgets/scripts/validate.rb`): the free-text values
+  (`title text why does sees behind when recommended`) and the list items that aren't mappings go in double quotes
+  unless they are one clean scalar already. It mends the traps models fell into: a colon in a value
+  (`does: Asked: ...`), a colon in an option (`- B: keep 1 h`), a value starting with a quoted word
+  (`text: "x" is called`). It is line by line, so a YAML error's line still points at the source. It can't mend a
+  comma in a flow list (`options: [A allow, B deny project, allow system]` is three options, so the recommended one
+  isn't one of them: eval round 1's failures), and a block that parses strictly into the wrong shape isn't retried.
+- **Folds.** A block that parses strictly can still have an option or a free-text value that YAML read as a mapping
+  of one pair of scalars (`- fix now: drop the command`). Where text is wanted (an option, `title`, `text`, `why`,
+  `does`, `sees`, `behind`, `when`, `recommended`), that mapping is taken as the text written: the source slice from
+  the key to the value's end when both sit on one line, else `key: value`. The Result is then `lenient?`. A mapping
+  of several pairs, or one holding a list or a mapping, stays an error, and so does one where an id, an actor, a
+  `next` or a `goto` goes. This is a mend, not a second lenient pass (`Tree#folds`, `Schema#text`).
+- **Normalised.** Ids are strings, unknown keys are dropped, optional values are absent rather than null, and text is
+  stripped. The page never sees model junk.
+
+### The schemas
+
+| | Required | Optional | Rules |
+|---|---|---|---|
+| picks | `rows`: rows of `id`, `text`, `options` (2-4 texts) | `title`; on a row `recommended`, `why` | ids unique; a row's options unique; `recommended` is one of the options |
+| walk | `title`, `actors` (2-5 texts), `steps`: steps of `id`, `actor`, `does` or `sees` | on a step `behind`, `next`, `cases` (each `when` + `goto`) | ids unique, none of them `end`; actors unique; `actor` is one of the actors; `next` names a step or is `end`, and not the step itself; every `goto` names a step |
+
+Eval round 1's `branches:` (the same shape as `cases:`) is read as `cases`.
+
+**`next: end`** ends the walk at that step: a branch that ends early, such as a success step written before the
+error step it must not run into. The normalised JSON keeps `"next": "end"`, and the page shows the step as the last
+one (its "end" tag, then "Start over"). A `goto` can't be `end`. In YAML:
+
+```yaml
+  - id: s4
+    actor: user
+    sees: the saved form
+    next: end
+```
+
+### The caps
+
+The source is at most 16 KB, checked before the parse. After it: a picks has at most 12 rows, a walk at most 30 steps
+and 2-5 unique actors, and every string is at most 300 characters. An error repeats at most 40 characters of a bad
+`type`, and never a tag.
+
+## The page (`inline_widgets.js`)
+
+`createWidgetDrawer` is a core drawer of `block_watch.js` (its header has the contract), wired in `app.js` ahead of the
+bundles' frame drawer through `createBlockHost`'s `drawers`. So a `chi-ui` block gets the watcher's paths: a reload, a
+session switch, a turn's end, Revise's clones, the stage's hand-off to `#history`.
+
+- **What it draws.** A `<pre>` with `data-widget` gets a light-DOM `<figure class="block-drawn widget">` right before it,
+  holding a `.widget-host` and the shared `.block-toggle` (block_source.js `setSourceShown`, the same icon; the
+  figure's `data-toggle-picture` makes its other label "Show the widget"). The `<pre>` stays, hidden: the DOM is the state, copy.js gives it its `.code-wrap`
+  copy button (it copies the YAML, which is the answer's text), and the toggle shows it. The toggle is in the light DOM
+  because a click in a shadow root reaches the page's delegated listeners retargeted at the host.
+- **Shadow DOM.** The host has an open shadow root holding the widget, with `widgets.css` adopted
+  (`adoptedStyleSheets`): the page fetches it once into a constructable `CSSStyleSheet` (`loadWidgetSheet`), and `draw`
+  returns a Promise that places the widget once it is there, so no widget flashes unstyled and the view held
+  (`holdingView`) measures the styled one. A failed fetch draws unstyled and the next draw tries again. Its words are then out of the bubble's `textContent`, which the shown-texts dedupe (`seedSeenFromDom`), copy's
+  fallback and an annotation's quote read, as with a renderer's `<img>`-only figure. chi's `:root` tokens reach it as
+  inherited custom properties, so light and dark follow the page. Playwright's locators pierce an open shadow root;
+  `page.evaluate`'s DOM calls don't. Whatever asks `document.activeElement` whether a field has the focus looks
+  through shadow roots (`composer_fold.js editable`, `stage_watch.js`), or typing in a note opens a folded composer.
+- **A clone redraws.** `cloneNode` doesn't copy a shadow root: a Revise clone (`revise_switch.js viewOf`) arrives with
+  the figure and an empty host, which `needsDraw` sees, and `draw` fills it again with a fresh widget and its own
+  listeners. A widget's position and picks live in the widget, so a clone or a rewrite starts over (accepted for v1).
+- **A refused block** (`data-widget-error`) stays source under `failBlock`'s muted `.block-note` ("Couldn't draw this
+  chi-ui block: …", an attribute CSS shows, a click copies it). Bad JSON or an unknown `type` fails the same way, from
+  the watcher. A `chi-ui` `<pre>` with neither attribute (an older server) is left alone.
+- **walk** (`widget_walk.js`): the swimlane (one column per actor, one row per step; the current, seen and a hovered
+  case's target marked; a click jumps), the step card (actor, `does`, "You see", the dashed "Behind it"), a fork's
+  "Which case?" buttons, Back / Next / Start over, the path taken, and ← → while the widget has the focus
+  (a move that removes or hides the focused button leaves the focus on the widget; a click on the current step is no
+  move). `walkRoutes`
+  resolves where a step goes: its `next` (`end`: nowhere), else the step below; a fork's `cases` as written, a case whose `when` is no
+  condition (round 1's `always`) reading as the usual path, alone it is the step's next. At a phone's width the
+  swimlane scrolls sideways inside the widget; the page doesn't.
+- **picks** (`widget_picks.js`): one row per item, its options as chips (`aria-pressed`), the recommended one marked
+  and picked to start with, a "+ note" per row, and "Fill reply".
+
+**The only way out is composer text.** Fill reply builds `id: option (note) · …` from the picked rows (a row with no
+pick is left out) and hands it to app.js's `fillComposer`, after a typed draft on a new line (`withDraft`; the draft
+is kept). It never sends: the owner reads the text and sends it or not. A walk has no way out at all. The model's
+strings reach the page through `textContent` and attributes only, never `innerHTML`, so a step reading
+`<img src=x onerror=…>` shows as those characters.
+
+**What doesn't draw.** The participant page (`participant.js` wires no block host), `web.markdown` off (no
+`data-lang`), a live answer while it streams (its YAML shows until the turn's end re-renders it as markdown), and
+anything outside `TEXTS`: cards, question replies, the asking slot, delegate reports. The terminal shows the YAML.
+
+## The fixtures
+
+`spec/fixtures/inline_widgets/` holds eval 0013's 78 real blocks (47 from round 2, 31 from round 1), one file each,
+and `manifest.yml`, the outcome (ok, lenient or error) the eval's `check()` gave each when they were copied, but for
+r2-deepseek-picks-review.2: its options are one-pair mappings, an error in the eval, and a fold (lenient) here.
+`spec/inline_widgets_spec.rb` checks every one gets it: all 47 of round 2's draw, and round 1's errors are the
+comma splits.

data/docs/internals/objectives.md

@@ -116,9 +116,9 @@ Bridge's `TurnAccumulator#current_messages`) leaves tool calls out. A move shows
 
 `action: propose` (`change` add, reword, done or drop; `id`; `text`; `note`, why) checks the change against the list
 (`Objectives::Proposal#refusal`: its line through `Objectives::Edit`, the edit the card's Apply runs, so the tool refuses
-what Apply would) and hands it to `Engine#propose_objective`, which keeps it until the turn is over,
-as `#context_choice`'s cards are kept. `run_turn`'s ensure shows them only for a turn that completed: a canceled or
-failed one drops them (`Engine#discard_objective_proposals`), so its Apply card never outlives a turn whose call a
+what Apply would) and hands it to `Engine#propose_objective` (`TurnStages::Objectives#propose`), which keeps it until the turn is over,
+as `TurnStages::ContextJudge`'s cards are kept. `run_turn`'s ensure (`TurnStages::Objectives#finally`) shows them only for a turn that completed: a canceled or
+failed one drops them, so its Apply card never outlives a turn whose call a
 rollback has taken out of the history, and nothing carries over to the next turn. A card is between turns (no
 `in_turn`), so it writes no `pending_card.json`, the stage doesn't say it waits, and it keeps its buttons over a
 restart (`CardStore` takes them only from a card shown in a turn). The same change twice in a turn is one card. A P3
@@ -139,7 +139,7 @@ any call. An add's text can't split on ` | `. The body names the line, for a ter
 
 `Objectives.view` (`List#to_view`) is what the page draws: the items, each with its last move, and `pending`, whether
 the newest list is a file still waiting. The session read (`objectives`, no key with no list) and the live
-`:objectives_updated` carry it. `Engine#announce_objectives` emits when the view differs from the last: after an edit,
+`:objectives_updated` carry it. `Engine#announce_objectives` (`TurnStages::Objectives#announce`) emits when the view differs from the last: after an edit,
 once a list note is in (`add_context_note`), at a turn's end (its moves) and after a rollback between turns. A session
 with no list emits nothing. Between two tabs that is all it takes. A participant gets neither: the event is in
 `ParticipantView::DROPPED`.
@@ -259,7 +259,9 @@ turn isn't on the page until the turn's end (`announce_objectives`), so its tap
 
 ## System 1 in audit
 
-`ObjectivesAudit`, off unless `objectives.system_one: audit`. See [system-one.md](../system-one.md#objectives-in-audit).
+`ObjectivesAudit`, off unless `objectives.system_one: audit`. `TurnStages::Objectives` asks it: `incoming` at an owner's
+turn's start (a person's prompt only), `outgoing` after the end event of a completed answer, `note` for a note added
+between turns (docs/internals/engine.md, "Turn stages"). See [system-one.md](../system-one.md#objectives-in-audit).
 
 ## Not in this version
 
@@ -269,4 +271,4 @@ Taking it out: old notes stay readable framed bubbles and keep being sent, and t
 stay as history; with a kit no longer declaring the tool, they are ordinary saved calls. The card's bundle uninstalls. The
 page's pieces are the `objectives_*.js` modules and `objectives.css`, wired in a few lines of `app.js`; without them a list note
 falls back to the default bubble once `noteBubbleTemplate`'s first line goes. Check this is `objectives_check.rb`, its line in the command and
-the `check` key; the audit is `objectives_audit.rb` and three calls in `Engine`. Old `objective_checks.jsonl` files and saved runs are then read by nothing.
+the `check` key; the audit is `objectives_audit.rb` and three calls in `TurnStages::Objectives`. Old `objective_checks.jsonl` files and saved runs are then read by nothing.

data/docs/internals/participants.md

@@ -214,10 +214,10 @@ the list's `mode` (the panel's words) and the grant's stamp: `Grant#mode` / the
 turns) stays review until the owner invites them again.
 
 A turn's mode is `ParticipantMode.for_turn(session, entry)`: `:pair` only for a stamped entry in a pair session.
-The worker decides it once at the turn's start (`GuardrailWiring#begin_turn` → `#turn_mode`, from the entry
+The worker decides it once at the turn's start (`GuardrailWiring#begin_turn` → `TurnStart#mode`, into the turn's `TurnContext#participant_mode`, from the entry
 `SessionParticipants#entry_for` reads), and everything in the turn reads that: the stamp on the opening message
 (`participant_mode`), the boundary in `GuardrailWiring#checks`, `ToolRunner#unreached_group_refusal` (through
-`KernelLoop#participant_mode`: a review turn's boundary words the refusal; a pair turn gets the owner's), the
+the call's `TurnContext`: a review turn's boundary words the refusal; a pair turn gets the owner's), the
 mid-turn stop and the cap notice's words. The system prompt's line is the pair one once an active participant is
 stamped pair (`SessionParticipants#prompt_mode`); the participant page's `viewer.mode` is their own grant's
 (`ParticipantMode.live_for`).
@@ -323,7 +323,7 @@ and `ctx.turn_author` names it ([hooks](../hooks.md#participants-turns)).
   their $2.00 review cap: their comments are refused until you raise it (chi share cap ID p_… AMOUNT)." (a working
   session's: "Alex reached their $2.00 cap: their turns stop and are refused until you raise it (…)"). A review
   turn's spend counts from its end, so a review turn can finish past the cap. A pair turn stops mid-turn: before each
-  generation (`KernelLoop#generation_guard`, both loops) `Engine#guard_participant_spend` asks the worker's check
+  generation (`KernelLoop::Services#generation_guard`, both loops) `Engine#guard_participant_spend` asks the worker's check
   (`Worker#participant_turn_stop`: `metrics.spend(author)` counts the running turn's finished generations) and, past
   the cap, stops the turn on the plugins' stop path (`HookRoutes#stop_turn`: "stopped the turn: Alex reached their
   $2.00 cap"), with the owner's notice once per cap. A generation's cost is known only when it ends, so a pair turn
@@ -469,7 +469,7 @@ fields: a field added to an event later reaches nobody until it is named there.
   its final assistant reply (`AnswerTail`: the turn's last assistant message with text) contains the quote. Matching is case-sensitive, collapses whitespace, and strips common
   Markdown presentation (links, headings, list/blockquote prefixes, emphasis and code delimiters) from both sides;
   this matches the rendered text the page selects without treating different casing as the same claim. The quote may
-  also be in the answer as the pages show it (`Engine#verify_quote_in?`, `Redact.text`: the session's
+  also be in the answer as the pages show it (`TurnStages::VerifyAnchors#quote_in?`, `Redact.text`: the session's
   folder relative, home `~`, secret shapes `[redacted]`): a participant's page has only that text, and the owner's
   page quotes it the same way (`owner_claim.js` `opts()`, `normalizeClaim`; `spec/fixtures/redact_cases.json` keeps the two
   sides alike), so a claim naming a path is taken on both. A fresh child
@@ -510,7 +510,7 @@ fields: a field added to an event later reaches nobody until it is named there.
     `pair` only for a grant stamped to act in a working session whose worker runs pair turns, else `review`). Every
     turn of a participant's child is theirs, whoever starts it (the owner typing into it, a continue, a reminder):
     `VerifyFreshOrigin#origin_for` sets the author in `Engine#begin_turn` and in the worker, so their boundary
-    (`GuardrailWiring#turn_mode` reads the saved mode, never a lookup), their System 1 skip, their once-only asks to
+    (`GuardrailWiring#begin_turn` reads the saved mode, never a lookup), their System 1 skip, their once-only asks to
     the owner and the stamps on their messages follow. The child has no `participants.json`: its participant lookups
     (`Session#participants_source_id`) read the parent's, so a revoke, an expiry or the parent's archive refuses the
     child's next turn and stops a pair turn mid-turn, as in the parent; their audit lines go to the parent's

data/docs/internals/prompt-caching.md

@@ -67,15 +67,21 @@ right-hand column happens.
   the loop, the thinking level, the turn's LLM context layers; a `/thinking` change builds under another key). All
   of them are dropped only on `@prompt_builder.reset!`: a model switch (`Engine#switch_model!`), a plugin's
   `tools_changed!` or `prompt_changed!` (`Engine#prompt_changed!`), a profile change, or a toolkit change
-  (`Engine#apply_toolkit!`). A per-turn rebuild would break everything below it.
+  (`Engine#apply_toolkit!`). A per-turn rebuild would break everything below it. `reset!` swaps in a new cache
+  (no lock; it runs on plugin and Bridge threads, and inside a build through the profile lookup): a build it lands
+  in returns the same bytes but is not kept, so the next build reads the sources again.
 - The tools layer is shared **per toolkit** (configuration.md, "Toolkits"): sessions on the same toolkit share it,
   and a chain's links keep theirs. A session's toolkit is saved when it is created and never resolved again from
   config. A change (`/toolkit`, `ctx.use_toolkit`) is applied only at a turn's start (`Engine#apply_toolkit!`,
-  beside `apply_staged_tools!`, then `reset!`): the chat loop builds `tools:` per request, so a mid-turn change
-  would differ from the turn's prompt. Under `full` nothing is filtered and no line is added: the bytes are what
-  they were before toolkits.
+  beside `apply_staged_tools!`, then `reset!`): the chat loop builds `tools:` per request from the turn's
+  `Tools::ToolSurface` (built once in `Engine#generate` from the Registry, under the layers the turn's prompt was
+  built with), so its requests declare what the turn's prompt does, and a mid-turn change shapes only the next
+  turn's surface. The native declarations, the not-loaded line and the kit prompt come from a surface too: each
+  `SystemPrompt` build reads the Registry once as `ToolSurface.for(registry, layers:)` (its `declared`, `left_out`
+  and `index_only`, its toolkit's prompt), so the three agree and match the turn's (engine.md, "ToolSurface"). Under `full` nothing is filtered and no line is added: the bytes are what they were before
+  toolkits.
 - A toolkit suggestion (`toolkit.suggest.mode: on`) is set before `apply_toolkit!` of the turn it was asked on
-  (`Engine#settle_toolkit_suggestion` → `ToolkitBinding#suggest`), and no request goes out before that, so on a
+  (`TurnStages::ToolkitSuggestion#settle` → `ToolkitBinding#suggest`), and no request goes out before that, so on a
   session's first turn it costs nothing. Its **deferred switch** (a later prompt after `undecided`, within
   `toolkit.suggest.defer_turns` / `defer_tokens`) is engine-side, so `/toolkit`'s CacheConfirm doesn't apply: it
   changes the declared tools at the front of the request, and the server re-reads **system prompt + tools +
@@ -169,7 +175,7 @@ right-hand column happens.
 The next turn's prompt differs from the turn's last request at its tail: the previous answer's thinking is
 stripped (the models' specs require it). A hybrid model on llama.cpp can only resume from a restore point, so the
 next turn prefills from well before the end, more with every turn. `PromptWarmup` moves that work into the time
-the user reads: after a completed turn, `Engine#warm_up_next_turn` formats the next prompt up to where the new
+the user reads: after a completed turn, `TurnStages::Warmup#after` formats the next prompt up to where the new
 user message starts (`KernelLoop#warmup_prompt`) and sends it in a thread (`Client#warm_up`: native
 `/completion`, `n_predict: 1`, not streamed, no retries, log purpose `warmup`, then a `model warmup` line with
 `cached=`, `prefilled=` and `prefill_ms=`).

data/docs/internals/web-frontend.md

@@ -24,7 +24,7 @@ page. A factory dep a new version stops passing is the same hazard the other way
 out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
 until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
 `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
-`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `version_notices.js`, `owner_claim.js`, `owner_verify.js`, `composer_mode.js`, `strip_hidden.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js` and the `objectives_*.js` modules are new modules for that reason. The last three `block_*` draw a bundle's fenced blocks: [block-renderers.md](block-renderers.md).
+`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`, `inline_widgets.js`, `widget_walk.js`, `widget_picks.js` 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
 
@@ -51,7 +51,7 @@ change.
 | **`store.current`** (`session_state.js`: `emptySessionState` / `sessionStateFrom`; per field: `session_fields.js FIELDS`) | the open session's fields, about 40 (info bar, chips, verdicts, timing, worker, stream cursor) | `store.update` / `setStatus` from app.js, `stream_handlers.js`, `send_turn.js` (`firstPreview`, `owner`), `session_actions.js` (`status`), `owner_verify.js` (`verdicts`, `verifyFresh`); `forgetSession`'s `replaceCurrent`. Two writers in place, on purpose (D8 in `FIELDS`): live_timing.js's `activeTurn`, verdict_fresh.js's running list | the store runs the field's redraws (`FIELDS[key].redraws`) |
 | **`store.sessions`** (the hub's projection) | every card | `store.update({sessions})` from app.js: `openSessionEvents` (`applySessionEvent`), `refresh` (the list fallback), `addCreatedSession`, `applyView` (re-sorted), `replaceSelectedCard` (`setLiveStatus` through `setStatus`, `readTurnEnd`, `setUsedMemories`), the stream's close (`withoutWorker`); `session_actions.js` (`setSessions`) | the store: `lists` and `infoBar`. **Always a new array**; an entry is replaced, never changed in place. `followSelectedSession` copies the open one's owner and worker (`fieldsFromCard`) and, when not streaming, its status (`setStatus(…, "hub")`) into `store.current` |
 | **Factory closures**: the `create*` factories (popovers, panels, views) | each component's own state: open-for, busy, error, its own fetched list | the factory | an `onChange` hook back into app.js, or a getter the factory reads at draw time |
-| **The history DOM** | the conversation as drawn: which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), what opens a turn (`TURN_PROMPT`, `bubbles.js`: a prompt or a wake's note, the same turns `Steer.turn_opening?` counts for a card's or the recap's `turns_since`), kept command bubbles, which texts were shown, unnamed badges, folded answers and long prompts (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`); the switcher's version on view is `revise_stack.js`'s own (a copy `.stack-view` before the top answer, the top `.stack-swapped`; never stored) | `bubbles.js`, `cards_place.js`, `question_cards.js`, `turn_block.js`/`stage_view.js`, `answer_fold.js`, `revise_stack.js`, `stream_handlers.js` (a live `turn_completed`'s `revises` and `verify` onto its prompt) | read back as state: `turn_range.js turnElements` (one walker for a turn's elements), `keptCommandBubbles`, `seedSeenFromDom`, `nameUnnamedBadges`/`nameVerdictCards`, `answer_fold.js` and `revise_stack.js` (their observers decorate every path that fills `#history`; the stacks are `stacks()` of the stamps, read again on each change, never a store field), `history_reveal.js revealInHistory` (the one way a jump unfolds what hides its target) |
+| **The history DOM** | the conversation as drawn: which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), what opens a turn (`TURN_PROMPT`, `bubbles.js`: a prompt or a wake's note, the same turns `Steer.turn_opening?` counts for a card's or the recap's `turns_since`), an opening's id for a card'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, by its count 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) |
 | **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 |
 

data/docs/internals/working-set.md

@@ -102,7 +102,8 @@ when it has outputs and none is `sent`. An edit-only item, a failed run's file o
 pending: [Steering: add and unadd](#steering-add-and-unadd)) (`Engine#emit_working_set`, `EventFanout`'s):
 - after each `:generation_started`, in `build_stream_event_handler` (`EventFanout`), from the running turn's
   conversation (`Engine#live_conversation`, read on the turn's thread) under the turn's strategy
-  (`@kernel.turn_settings.llm_context`). Both loops start a generation after `apply_llm_context!`, so the set is
+  (`TurnContext#settings`' `llm_context`; `EventFanout#working_set_llm_context`: the running turn's, the last turn's
+  until it has its own). Both loops start a generation after `apply_llm_context!`, so the set is
   what that request sends;
 - once in `Engine#end_turn`, after `replace_session_messages` and before the end event, from the kept messages (the
   turn-end apply has run by then);

data/docs/plugins.md

@@ -1387,6 +1387,8 @@ block_renderers:
   it refuses with "No memories to build".
 - The first installed bundle (by name) with a language draws it. A bundle whose `requires_chi` this chi doesn't meet
   draws nothing.
+- `chi-ui` is reserved: chi draws it itself (inline widgets, [internals/inline-widgets.md](internals/inline-widgets.md)),
+  so a manifest that lists it is refused.
 - **What it needs of the page:** `web.markdown` on (a default-off setting, and the commonmarker gem). With it off a
   fence has no language in the page and nothing draws, though a hint in the bundle's prompt section still reaches
   the model: say so in the bundle's README.

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, decision-card, web-search, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, decision-card, inline-widgets, web-search, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`

data/docs/sessions.md

@@ -6,7 +6,7 @@ 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`, and so does its live end event (`:turn_completed`'s `verify: true`, with its `turn_id`): 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?`; the Bridge takes either as `delivery: queue`, so it never cuts and its ack and `:turn_enqueued` say it queues), 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`).
+**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 (`TurnStages::VerifyAnchors#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`, and so does its live end event (`:turn_completed`'s `verify: true`, with its `turn_id`): 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?`; the Bridge takes either as `delivery: queue`, so it never cuts and its ack and `:turn_enqueued` say it queues), 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` or `delegate_result` and hands a running `execute` over as a task after 3 s (`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`.
 
@@ -110,7 +110,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 - New sessions set `test_run:true` when `SAMAGOTCHI_ENV=test` or `RACK_ENV=test` or `CI` is set (explicit flag, `metadata_version` 2). Old sessions without the flag load as `test_run:false`.
 - Test runs are tagged and obey the same retention. `chi sessions clean` deletes every test session whatever its age (`--days N`: only those older than N days); a live worker or a `keep_status` status still keeps one. `chi sessions prune --test-only` applies the usual age and count rules to test sessions only.
-- A `chi scratch` session (`"scratch": true`) is deleted when its terminal leaves (its worker deletes it too once its last client is gone); one left behind when both died is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
+- A `chi scratch` session (`"scratch": true`) is deleted when its terminal leaves (its worker deletes it too once its last client is gone); one left behind when both died is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it and its file is 30 s old (`SessionRetention::SCRATCH_START_GRACE`, the worker start grace: `chi scratch` saves the session before the worker it spawns takes the owner lock). `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
 - For ad-hoc manual QA use `SAMAGOTCHI_ENV=test XDG_STATE_HOME=/tmp/chi-test-$USER chi ...` to isolate from real state; the flag also marks sessions that `chi web` or an attached `chi` spawn (their workers inherit the environment), so `clean` finds them if they land in the real state.
 
 ## Session file
@@ -141,7 +141,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 | `parent_id` | The session that delegated this one or forked it (`ctx.sessions.fork`); `null` otherwise. See [Delegating](#delegating). | `SessionManager.spawn_session`; `ChildMove` writes a `parent.json` beside it instead of this file |
 | `scratch` | A `chi scratch` session, deleted when its terminal leaves. | creation |
 | `last_turn` | How the last turn ended (`LastTurn`), for a parent's wait and the web's notifications. | the Engine, at a turn's end |
-| `verdicts` | Verdict cards recorded by completed Verify turns, in append order. | `Engine#record_verdict`, `VerifyFresh` |
+| `verdicts` | Verdict cards recorded by completed Verify turns, in append order. | `TurnStages::VerifyAnchors#record_verdict`, `VerifyFresh` |
 | `delegate` | Started by the `delegate` tool (a fork has a `parent_id` but isn't one). | `Tools::Delegate` via `spawn_session` |
 | `llm_context` | The session's own LLM context values (strategy, apply rule, budget), over the model's; `null` with none. | creation (`--llm-context`), `/llm-context`; copied by a fork and a continue, not a delegate child |
 | `continues` | The previous link of a chain; `null` otherwise. See [Session chains](#session-chains). | `SessionContinue` |

data/docs/testing.md

@@ -60,6 +60,21 @@ 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 whole-turn goldens (`spec/engine_turn_golden_spec.rb`, `spec/fixtures/turn_goldens/`) run a real
+`Engine#run_turn` (its own KernelLoop, ChatLoop, ToolRunner, Gate and GuardrailWiring) over `FakeProviderServer` on
+the native (llama.cpp `/completion`, Qwen tool calls), `api: openai` and `api: anthropic` wires: a turn of two tool
+iterations (a muted `memory_read` and a `read`, then a `write` a config rule asks about, allowed through the question
+flow), a `before_turn` hook switching the model (the request names the new model with the old one's sampling), and a
+review participant's turn whose `write` the review boundary refuses. Each golden pins every request (the chi-set
+headers, the body in its key order, the native prompt as text), the turn's events (keys sorted; the context-status
+estimates and clock values masked), each `before_tool_call` payload, the approval asked and the session's messages.
+System 1, the toolkit suggestion, the context judge, the recap and the warm-up are off by config, so the order is the
+turn's own. The arch P3 refactors (TurnContext, turn stages, ToolSurface) keep them byte-identical: a phase that
+changes one stops and asks. An intended change elsewhere: `UPDATE_PROMPTS=1 bundle exec rspec
+spec/engine_turn_golden_spec.rb`, then read `git diff spec/fixtures/turn_goldens/`; a failure writes what the run got
+to `tmp/turn_goldens/<golden>.actual` and names the `diff` to run. Changes to the turn path (engine, kernel loop, chat loop,
+tool runner, gate, guardrail wiring, system prompt, tool declarations, registry) pick it in `script/affected-specs`.
+
 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`,
@@ -245,7 +260,7 @@ any other file requires it, so a spec file run alone still finds its requires. E
 | `reply_wait_looks.rb` | `ReplyWaitLooks`: counts a `ReplyWait`'s polls, so a step waits for the looks instead of a delay |
 | `stamps.rb` | *helper*: `next_stamp`, distinct ordered times for the lib's `now:` seams; the pinned history clock |
 | `task_dirs.rb` | `with_task_dir`: a tasks' folder of its own, every task stopped and its recorders joined after |
-| `test_kernel.rb` | `TestKernel`: `test_kernel` (a real `KernelLoop` to stub `#run` on) and `test_client` for Engine specs |
+| `test_kernel.rb` | `TestKernel`: `test_kernel` (a real `KernelLoop` to stub `#run` on; its options are `KernelLoop::Services` fields), `attach_services` (swap some of a kernel's services), `run_context` and `test_client` for Engine specs |
 | `thinking_off.rb` | shared context "thinking off": `SAMAGOTCHI_THINKING_LEVEL=off` for the example |
 | `virtual_terminal.rb` | `VirtualTerminal`: just enough VT100 to check what a Screen leaves on the terminal |
 | `waiting.rb` | *helper*: `SpecWaiting` (`wait_for`, `wait_until`, `join!`, `pop!`, …), the test kit's helpers ([Waiting and time](#waiting-and-time)) |

data/lib/samagotchi/answer_text.rb

@@ -13,7 +13,6 @@ module Samagotchi
   # thoughts and call markup inline: both hosts' thoughts come out, a thought
   # cut off before it closed too, then the calls and the wire tokens.
   module AnswerText
-    QWEN_THINK = %r{<think>.*?</think>}m
     # The template opened the block, so the text starts inside it.
     TEMPLATE_OPENED_THINK = %r{\A.*?</think>}m
 
@@ -25,7 +24,7 @@ module Samagotchi
       text = text.to_s.scrub
       template_opened = !text.include?("<think>")
       gemma = ToolCallParser::Gemma.new(ModelProfile.gemma4)
-      text = gemma.strip_thought(text).gsub(QWEN_THINK, "")
+      text = gemma.strip_thought(text).gsub(OutputFormatter::QWEN_THINK_RE, "")
       text = text.sub(TEMPLATE_OPENED_THINK, "") if template_opened
       text = ToolCallParser.strip_calls(gemma.strip_tool_calls(text), "<tool_call>", "</tool_call>")
       OutputFormatter.strip_markup(text) # drops a thought cut off before it closed

data/lib/samagotchi/block_renderers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
+  autoload :InlineWidgets, File.expand_path("inline_widgets", __dir__)
   autoload :Log, File.expand_path("log", __dir__)
   autoload :VERSION, File.expand_path("version", __dir__)
   module MemoryBundle
@@ -34,6 +35,9 @@ module Samagotchi
     # A language a block can carry: a fence's first word, downcased
     # (MarkdownRenderer sets it as data-lang under this same pattern).
     LANG = /\A[a-z0-9_+-]{1,32}\z/
+    # Languages core draws itself: a bundle's renderer for one would be a
+    # second drawer for the same block.
+    RESERVED = [InlineWidgets::LANG].freeze
 
     module_function
 
@@ -60,6 +64,7 @@ module Samagotchi
       unless lang.is_a?(String) && lang.match?(LANG)
         raise Invalid, "block_renderers: lang #{lang.inspect} isn't a fence's language (lowercase letters, digits, _ + -; at most 32)"
       end
+      raise Invalid, "block_renderers: #{lang} is drawn by chi itself; a bundle can't render it" if RESERVED.include?(lang)
 
       load = data["load"]
       unless load.is_a?(Array) && !load.empty? && load.all? { |file| file.is_a?(String) && file.match?(MemoryBundle::Manifest::SCRIPT_FILE) }

data/lib/samagotchi/bridge/card_places.rb

@@ -9,16 +9,22 @@ module Samagotchi
     # the recap share (Steer.turn_opening?); the store's turn log only orders
     # the ids. So a turn with no opening (a reminder, a Continue, a failed or
     # rolled-back one, a prompt stopped before the model) counts nothing, and
-    # an opening with no id (/continue no's reason, Qwen's recovery line) counts
-    # as it does on the page. Nothing orders such an opening against an entry, so
-    # an entry says how many it came after (+past_idless+, #idless_after). Pure:
-    # no Engine, no file.
+    # an opening with no turn id (/continue no's reason) counts as it does on
+    # the page. Nothing orders such an opening against an entry, so
+    # an entry says how many it came after (+past_idless+, #idless_after), and
+    # which one that is when it has an id (+after_opening+, #after_opening).
+    #
+    # The same place as a stamp (#opening_of): the id of the opening the entry
+    # comes after (a prompt's turn_id, a line's opening_id), which the page
+    # finds by its bubble, not by counting. Pure: no Engine, no file.
     class CardPlaces
       # @param turn_log [Array<String>] the turn ids, oldest first
       # @param messages [Array<Hash>] the messages the page draws
       def initialize(turn_log, messages)
         positions = turn_log.each_with_index.to_h
-        @ids = Array(messages).select { |message| Steer.turn_opening?(message) }.map { |message| message[:turn_id] || message["turn_id"] }
+        openings = Array(messages).select { |message| Steer.turn_opening?(message) }
+        @ids = openings.map { |message| message[:turn_id] || message["turn_id"] }
+        @stamps = openings.map { |message| stamp_of(message) }
         @openings = @ids.size
         @opened = @ids.compact.to_set
         @places = @ids.map { |id| positions[id] }
@@ -45,13 +51,44 @@ module Samagotchi
         entry[:base_since].to_i + since
       end
 
+      # The opening +entry+ comes after, as #turns_since counts: its id (a
+      # prompt's turn_id, a line's opening_id), the page's stamp. nil when it
+      # comes before every opening, when that opening has no id (a line an
+      # older chi wrote), or for an entry from an older file (+base_since+):
+      # the page counts those (turns_since).
+      # @param entry [Hash] a store's entry: :turn_id, :past_idless, :after_opening, :base_since
+      # @return [String, nil]
+      def opening_of(entry)
+        return nil if entry[:base_since]
+
+        at_or_before = counted_from(entry[:turn_id])
+        return nil unless at_or_before
+
+        run = at_or_before..(at_or_before + idless_run(at_or_before))
+        # The line it saved it came after, while that line is in the run (as
+        # the count past it, the two save together); else the count's.
+        after = entry[:after_opening] && @stamps.index(entry[:after_opening])
+        @stamps[after && run.cover?(after) ? after : [at_or_before + entry[:past_idless].to_i, run.end].min]
+      end
+
+      # The id of the last opening with no turn id right after the one
+      # +turn_id+ counts from (#idless_after's run), nil when there is none or
+      # it has no id either.
+      # @return [String, nil]
+      def after_opening(turn_id)
+        at_or_before = counted_from(turn_id)
+        return nil unless at_or_before
+
+        run = idless_run(at_or_before)
+        run.positive? ? @stamps[at_or_before + run] : nil
+      end
+
       # The openings with no id right after the one +turn_id+ counts from: what
       # an entry shown now has come after. A rollback can only shorten the run, so
       # a count read back against it never eats a later turn.
       # @return [Integer]
       def idless_after(turn_id)
-        position = @positions.fetch(turn_id, -1)
-        at_or_before = position >= 0 ? @last_at_or_before[position] : nil
+        at_or_before = counted_from(turn_id)
         at_or_before ? idless_run(at_or_before) : 0
       end
 
@@ -70,6 +107,18 @@ module Samagotchi
 
       private
 
+      # The last opening whose turn is at or before +turn_id+'s in the log
+      # (an index into the openings), nil for none.
+      def counted_from(turn_id)
+        position = @positions.fetch(turn_id, -1)
+        position >= 0 ? @last_at_or_before[position] : nil
+      end
+
+      def stamp_of(message)
+        id = message[:turn_id] || message["turn_id"] || message[:opening_id] || message["opening_id"]
+        id.is_a?(String) && !id.empty? ? id : nil
+      end
+
       def idless_run(opening)
         @ids.drop(opening + 1).take_while(&:nil?).size
       end