samagotchi 0.60.0 → 0.62.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee2aa2b12b6482c02486b2382cc1c287c394d0a323e3bbf851948e49d0ebb2b9
-  data.tar.gz: 7bddba2fddfbcc05dfccba0777a6163963f8e238a26d14b6fbfb49b3d0bc0827
+  metadata.gz: 68aeb876a7c4c04d7f2f5de4290a1c6089df3acd181bce7380ccb6bde9ef9de8
+  data.tar.gz: ed308c360b3942d9f3d08233762396493a018585103e50661dd17ea4bb0d123c
 SHA512:
-  metadata.gz: fb47d9df8beac57e413f22b01efdf8bbec31c7c9a5be400976b818d8e6dbe6931081b223568cbb3f345dee39c7f1ffc7a6b39def9e01b4033bdcf7ccda017cdd
-  data.tar.gz: 95b1879ed0ee9d093140d2dddaa9cc21c30031d45f7114b1c3311134d2f1082ad1f81480421a8da7f9cd61eb76d4d4aae65b8b29c08c0dd377dcbdab50c98f6d
+  metadata.gz: 8a3ecca6a15d1c2d0e4acf5531491116139b3423ca0e6fe2b4ad558f5c99b332b50672a700437f9d37c1397d9ed92e527b843e6577b11198906ff75ab16b4ecd
+  data.tar.gz: 949538fdd97549e09bd215353cbdf9dccbe42a21806b965ff828db5b708521791e939abd2d2cb93892c23660abbfabd3106bb492412eb505f52cc0cd742d6d99

data/CHANGELOG.md

@@ -8,6 +8,102 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.62.0] - 2026-10-13
+
+### Added
+
+- Plugins: `chi.tool(…, refs: ->(args) { [...] })` gives a tool call's web row its refs (a ticket, a PR, a file
+  under the session's folder) with their URL actions: the row's title opens the first, its `▾` menu offers the
+  rest, on a phone too. Saved with the result, so a reload shows them. See docs/plugins.md, "Refs on a tool's
+  row".
+
+### Changed
+
+- Web: the stage view no longer jumps: it keeps its height while a turn runs, its chip stays put when the answer
+  arrives, and the finished turn slides away instead of collapsing. The stage floats above the composer (its rising at
+  a turn's start moves nothing, and the history behind it glides instead of jumping); content changes inside it (the
+  first words of a reply, an answered card, a short answer), so a card you answer stays where it is; it grows with a
+  short ease when a card or the answer needs room; its chip is its footer (the steps open right above it); and when
+  the turn moves into the history the stage slides away under the composer, then the turn appears there.
+- Web: on a phone the top bar no longer gains a row mid-turn when the hidden strip's pill grows ("· 1 waiting"), which
+  pushed the whole session down; the pill drops its session count while it says live or waiting.
+- Web: while a question or approval waits in the stage view, the stage shows the whole text of the reply that asked
+  it, not only its last sentence.
+- Web: the model's question or its own approval, once answered, keeps the reply that asked it (a delegate's relayed
+  approval, a hook's question and the step limit don't): two muted lines under its `question → answer` line, the
+  whole text when the card is open, live and after a reload.
+- Web: a finished turn's steps block shows its outline when its steps said something: open, one line per step that
+  wrote text (a mid-turn note reads without a click), and each run of tool-only steps folded into one `· N steps`
+  line that shows them. Live (both views) and after a reload; a turn whose steps said nothing collapses as before.
+- Web: question and approval cards answer from the keyboard. Enter in the response box or on an option submits
+  (never Deny or Dismiss), and a new card takes the focus when the message box is empty.
+- github-pr 0.5.0: a `path:line` it links in an answer is also a file ref, so the web's ref menu offers the file in
+  this checkout (editor, show in turn, copy) and a "PR diff" (or "File at head") action. Needs chi 0.61.0; run
+  `chi update`.
+- source-links 0.5.0: each ref it links in an answer gets an "Open in <source>" action in the web's ref menu; a
+  source's new `kind:` key names its refs' kind (default `issue`). Needs chi 0.61.0; run `chi update`.
+- Chat hosts (`api: openai`) keep the running turn's reasoning across a mid-turn steer under `reasoning_history:
+  turn`, as native hosts do: a person's line, a plugin's nudge (check-in, agents-md) or a step-limit Continue's text no
+  longer drops the reasoning of the replies before it, so the request after it extends the one before and the
+  server's prompt cache holds. A `!cmd` run while the step-limit question stands still starts past itself. On a stock
+  Qwen template (Splash) the benefit needs `chat_template_kwargs.preserve_thinking: true`; see
+  [docs/configuration.md](docs/configuration.md#reasoning-history).
+
+### Fixed
+
+- A turn run in the REPL (`--no-shared`) keeps the answer's display and refs (source-links' and github-pr's links,
+  a hook's `present`), so the web shows them when it opens the session; before, the save dropped them.
+- A command a signal to chi stopped (a worker's TERM, HUP or INT mid-`execute`) says "stopped by a signal to chi",
+  not "stopped by the user"; one it kept from starting says "not run, a signal to chi stopped the turn".
+  slow-commands 0.2.1 doesn't count either as slow.
+- A turn whose worker was killed (SIGKILL, a crash) keeps its tokens, speed and timings up to its last checkpoint:
+  the session's stats count it as a canceled turn (`worker_stopped`); before, they lost it.
+- Web: hovering a ref with a ▾ at the very end of a line no longer pushes it onto the next line.
+- Web: a failed `+ URL` attach keeps the "why" you typed (it was emptied), and a context chip with the keyboard
+  focus keeps it when the chips refresh.
+
+Update with `chi update`: the system bundle 0.62.0, github-pr 0.5.0, source-links 0.5.0 and slow-commands 0.2.1.
+Then restart `chi web`.
+
+## [0.61.0] - 2026-10-12
+
+### Added
+
+- Hooks and plugins can attach refs to the answer: `event[:refs].call(match:, kind:, target:, label:, actions:)` on
+  `:after_turn`, stored as `display_refs` on the answer (display only: the model never sees them). The web pairs them
+  with the answer's links and text: their actions join the ref's menu, live and after a reload. Caps: 200 refs and
+  256 KiB per answer; a refused ref is logged as `refs_rejected`. See
+  [docs/hooks.md](docs/hooks.md#refs-on-the-answer-display-only).
+
+### Changed
+
+- A ref's values are capped (`Ref`, `RefAction`): a label at most 200 characters, at most 8 actions, a target id
+  200 and a path 4,096 characters; an action's id 64 and label 100. An action URL with userinfo
+  (`https://user:pass@host/`) is refused, and the web page refuses one too.
+
+### Fixed
+
+- A worker that gets TERM, HUP or INT (`chi sessions stop`, a closed terminal, a process-tree teardown) stops its
+  running turn as a Stop with reason `signal` and saves it, then exits; before, the turn and its prompt were lost.
+  A stopped session's worker now saves the turn it kept too.
+- A worker killed mid-turn (SIGKILL, a crash) no longer loses the whole turn: the worker writes the turn so far to
+  the session file with an `interrupted_turn` mark (the prompt as the turn starts, then its iteration boundaries,
+  at most every 10 s), so it loses only what came after its last written boundary. The next worker (or a
+  `--no-shared` REPL resuming the session) ends that turn as canceled with a note the model reads
+  (`cancelled (worker-stopped)`), so the session is idle again.
+- Workers outlive whoever spawned them: a worker leaves the spawner's process tree (forked again, `setsid`,
+  reparented to init), so a tool tearing down a background `chi send --wait`, or a closing terminal, no longer
+  kills it mid-turn (run #43 lost a 169-step turn that way).
+- A card shown during a turn by a worker that has since exited comes back read-only: no buttons. A stale check-in
+  card's Nudge steered the next worker's turn on every click. Cards shown between turns (github-pr's offer, btw,
+  coordinator) keep their buttons.
+- check-in nudges once per check-in: repeated Nudge clicks (or `/checkin nudge`) on the same check-in answer
+  "check-in: already nudged at N tool calls" instead of steering the turn again. Run #43 got 12 identical nudges.
+- Web: a ref's `▾` sits in room the ref makes on hover, never over the next words.
+
+Update with `chi update`: the system bundle 0.61.0 and check-in 0.2.4 (nudges once per check-in). Then restart
+`chi web`.
+
 ## [0.60.0] - 2026-10-11
 
 ### Added
@@ -2623,7 +2719,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.60.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.62.0...HEAD
+[0.62.0]: https://github.com/dm1try/samagotchi/compare/v0.61.0...v0.62.0
+[0.61.0]: https://github.com/dm1try/samagotchi/compare/v0.60.0...v0.61.0
 [0.60.0]: https://github.com/dm1try/samagotchi/compare/v0.59.0...v0.60.0
 [0.59.0]: https://github.com/dm1try/samagotchi/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/dm1try/samagotchi/compare/v0.57.0...v0.58.0

data/docs/architecture.md

@@ -97,7 +97,7 @@ terminal renders the events it gets over the Bridge.
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, and the HTTP both share. |
 | Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, forget_outputs, plus runtime/output-guardrails. |
 | Bundles | `lib/samagotchi/memory_bundle/*`, `BundleCommand` | `chi bundle`: install/upgrade (3-way merge), build, uninstall; the install record under `.bundles/<name>/` that the hook, guardrail and plugin loaders read ([internals/bundles.md](internals/bundles.md)). |
-| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` forks/spawns one worker process per session; its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. |
+| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` forks/spawns one worker process per session; its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. The spawned process (own process group) forks the worker, which `setsid`s and is reparented to init once its starter exits (it waits until the worker holds `owner.lock`, so the spawner's `Process.detach` waiter tells a starting worker): nothing that walks the spawner's process tree reaches it (`SAMAGOTCHI_WORKER_DETACH=1`, `detach_from_spawner`). The lock's pid is the worker's; `spawn`'s `child_pid` is its starter's. |
 | Web | `Samagotchi::Web::App`, `Samagotchi::Web::Server`, `Samagotchi::Web::SessionHub` | Rack+WEBrick single-port `127.0.0.1:4567` (index.html + `/api/*` + SSE). The hub is chi web's projection of the session list, pushed to every tab over `GET /api/events`. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File `sessions/<uuid>.json` + sidecar `input/`/`output/`; retention 14d/500, `updated_at desc`, lazy sweep. |
 
@@ -297,7 +297,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   (`GET /api/sessions/:id`, `?parts=1`) and the plugin's `list_sessions`; every message is copied.
 - `GET  /session/:id/tail` — the page's light re-read (`Bridge#tail_frame`): `session_state_snapshot`,
   `answer` (the last message a UI shows as an answer, `AnswerTail`: the one message, copied alone),
-  `cards` (`CardStore#list`), `event_seq`, `event_id`, all taken in one event-log hold; no message
+  `cards` (`CardStore#list`; a card an earlier worker showed during a turn comes back read-only, with no
+  actions: its turn no longer runs), `event_seq`, `event_id`, all taken in one event-log hold; no message
   list, so it costs the same however long the session is. `?turn_id=` answers that turn's answer
   (an unknown or missing id: the newest); the only route that reads its query.
 - `OPTIONS *` — CORS preflight (`Access-Control-Allow-Origin: *`).
@@ -318,11 +319,16 @@ it, so the web's info bar updates per generation without parsing chunk payloads.
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:
 - `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,
-  used_memory_names}, messages: [the answer], markdown_warning, timing}`, from the worker's `/tail`
+  used_memory_names}, messages: [the answer, with its display and display_refs (re-read on an `answer_display` with a display or refs)], markdown_warning, timing}`, from the worker's `/tail`
   alone (no session file parsed, no `analytics.json`); `timing` carries the worker's recent records
   and `turn_count` (finished turns). The page merges the records by id (`timing.js mergeTiming`) and
   finishes the ended turn's own line by its `turn_id` (sent as `&turn_id=`, which also picks that
   turn's answer). A plain `?tail=1` (a tab opened before this) gets the whole timing.
+  The page binds an answer's `display_refs` to its bubble (`answer_refs.js`: on a reload's render and on this
+  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan.
+  A plugin tool's row refs (`refs`, `RowRefs`) ride its tool events and, on a reload, its part (saved as
+  `tool_refs`); `turn_view.js` binds them to the row's title (`refs.js bindRowRefs`: the first on the title,
+  the others in its menu).
 - `?timing=1`: the whole timing (`analytics.json` merged with the worker's `/state`) and
   `turn_count`, when the page's merge came up short.
 - `?cards=1`: the cards, from `/tail`; the session file is only stat'ed for the 404.
@@ -451,7 +457,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 
 | Component | Main file(s) | What it is |
 |---|---|---|
-| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. |
+| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). |
 | Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, hooks, services ([plugins.md](plugins.md)). |

data/docs/cli.md

@@ -689,14 +689,23 @@ the step's reasoning), the running tool with what it does, and the last
 three calls. A plugin's or hook's notice and a plugin's nudge ("check-in
 nudged the model") show ahead of those calls for about 4 s, as their rows
 wait in the closed block. A card that needs you (a question, an approval, check-in)
-sits in the stage too. The chip under it, `N steps · M tool calls` with one
-tick per call, opens the turn view's block in place (newest step first
+sits in the stage too. While a question or approval waits, the stage shows
+the whole text of the reply that asked it (in place of its newest
+sentence) above the card, until you answer. Once answered, the model's
+question or its own approval keeps that reply (a delegate's relayed
+approval, a hook's question and the step limit don't): two muted lines
+under its `question → answer` line, the whole text when you open the card,
+in both views and after a reload. The chip at the stage's bottom edge, `N steps · M tool
+calls` with one tick per call, opens the turn view's block right above it (newest step first
 while it runs; a tick opens its step). `▾` folds the stage to its status
-row, remembered in this browser. When the turn ends the answer shows in
+row, remembered in this browser. The stage keeps its height while a turn
+runs: it grows, with a short ease, when a card or the answer needs room and gives the room back
+only when the turn moves into the history. When the turn ends the answer shows in
 the stage, and the whole turn moves up into the history once you are not
 using the stage (the pointer over it, a touch or scroll in the last 4 s,
-keyboard focus or a selection keep it) for 1.5 s; sending the next message
-moves it at once. The history is never scrolled while a turn runs, and only
+keyboard focus or a selection keep it) for 1.5 s: the stage slides away
+under the composer, then the turn appears in the history. Sending the next
+message moves it at once. The history is never scrolled while a turn runs, and only
 follows the hand-off if you were at its end. The `/` command list opens
 over the stage's lower edge.
 
@@ -714,9 +723,14 @@ again). When a step ends its thinking closes to a plain `thinking` line
 (unless you opened it); a step that only thought shows that line alone. The
 live narration is a box of about three lines that fills sentence by
 sentence (a sentence shows once it is complete) and scrolls to the newest
-when full. When the turn ends the block collapses to its summary (`3 steps
-· 8 tool calls · execute ×7 · read ×1`) and the answer expands from the
-box into a normal bubble under it (Markdown, annotate). A plain answer
+when full. When the turn ends the block shows its outline when any of its steps said
+something: it stays open on one line per step that wrote text (that text's
+first line, so a mid-turn note reads without a click), and each run of steps
+that only called tools or thought sits behind one `· N steps` line that
+shows them; old turns open the same way after a reload. A turn whose steps
+said nothing collapses the block to its summary (`3 steps
+· 8 tool calls · execute ×7 · read ×1`). Either way the answer expands from
+the box into a normal bubble under it (Markdown, annotate). A plain answer
 without tools ends exactly as it does today. Rows the code collapses stay
 as you toggled them. A reloaded session shows the same block
 from the saved messages (each step's thinking, narration, tool parameters

data/docs/configuration.md

@@ -521,9 +521,10 @@ What each backend gets:
 
 On chat hosts: llama.cpp honours both off switches but ignores the effort (when its `/props` says
 `chat_template_caps.supports_reasoning_effort: false`, chi says so once per session and host, from the `/props`
-answer the turn already fetched for the window); Splash takes `reasoning_effort` (off only
-through `none`) and scales with it; OpenRouter translates `reasoning_effort` per model (some can't turn thinking off:
-Qwen3-30B-A3B thinks anyway, gpt-oss refuses).
+answer the turn already fetched for the window); Splash honours both off switches and passes the effort to the
+model's template, which decides: Qwen3.6's ignores it (`low`, `medium` and `high` think the same), and the server's
+`--default-reasoning-effort` decides what `default` means there; OpenRouter translates `reasoning_effort` per model
+(some can't turn thinking off: Qwen3-30B-A3B thinks anyway, gpt-oss refuses).
 
 When the model thinks although the level is `off`, chi says so once per session and host
 (`thinking> warning: off wasn't honoured by … (N chars of thinking)`) and logs `thinking_not_honoured` each time.
@@ -558,26 +559,39 @@ hosts:
     url: https://api.deepseek.com/v1
     api: openai
     api_key_env: DEEPSEEK_API_KEY
-    reasoning_history: all   # its API wants every earlier reply's reasoning when tools are sent
+    reasoning_history: all   # with tools its API wants every earlier reply's reasoning: under turn, turn 2 fails
 models:
   some-model:
     reasoning_history: drop
 ```
 
-- `turn` (the default) sends the running turn's reasoning: each reply since the last user message carries its
-  reasoning as `reasoning_content`, which is what Qwen's, Gemma 4's and DeepSeek's chat templates and the hosted APIs
-  (OpenRouter takes it for DeepSeek, Qwen and other text-reasoning models) expect. The running turn starts at the
-  last message you sent (a prompt, or a steer: as the chat template counts it) and never before the turn's own start,
-  so a turn that goes on by itself (a reminder, a context wake, a delegate report's wake) sends nothing of the one
-  before it, an interrupted reply's partial thought included. A **step-limit Continue** is the same turn going on: it
-  keeps the reasoning of the run it continues (back to the first run of a chain of Continues), so its first request
-  matches the last one before the limit and the server's prompt cache stays warm. Continue's text, or a `!cmd` run
-  while the step-limit question stands, is a user message: the reasoning before it goes, as for any steer, and that
-  Continue reads the conversation again once (a re-prefill on a local server). After a `/model` change while the
-  question stands the Continue starts afresh (no other model's reasoning is sent).
+- `turn` (the default) sends the running turn's reasoning: each reply since the turn's start carries its reasoning
+  as `reasoning_content` (OpenRouter takes it for DeepSeek, Qwen and other text-reasoning models). A steer, a plugin's
+  nudge (check-in, agents-md) or a Continue's text merged into the turn doesn't reset it, as on a native host: the
+  request after it is the one before plus the steer, so the server's prompt cache holds. A turn that goes on by itself
+  (a reminder, a context wake, a delegate report's wake) sends nothing of the one before it, an interrupted reply's
+  partial thought included. A **step-limit Continue** is the same turn going on: it keeps the reasoning of the run it
+  continues (back to the first run of a chain of Continues), so its first request matches the last one before the
+  limit and the server's prompt cache stays warm; Continue's text keeps it too. A `!cmd` run while the step-limit
+  question stands is a user message added after the run: the reasoning before it goes, and that Continue reads the
+  conversation again once (a re-prefill on a local server). After a `/model` change while the question stands the
+  Continue starts afresh (no other model's reasoning is sent).
+- **A stock Qwen template (Splash, vLLM, SGLang; llama.cpp with Qwen's own template)** renders an earlier reply's
+  reasoning only after the last user message: a steer hides the reasoning before it whatever chi sends, and the
+  prompt changes there. `sampling: {chat_template_kwargs: {preserve_thinking: true}}` on the host renders every
+  reasoning chi sends (a reply sent without any renders an empty think block; adding it restarts the prompt cache
+  once). What it costs by level, with it on: under `turn` a steer no longer re-reads the turn, but each new turn still
+  reads the conversation again from the previous turn's first reply (that turn's reasoning leaves the request); under
+  `all` every request extends the one before (append-only), at the cost of a prompt that keeps the reasoning of every
+  turn. Without it (the template's default) both re-read from the reply before each user message. A strict server
+  that rejects unknown fields ("Unrecognized request argument supplied: chat_template_kwargs": OpenAI proper, some
+  gateways) fails every request with it, so set it only on a host you know takes it.
+- A **direct DeepSeek API** host (`api.deepseek.com`) with tools wants the reasoning of every earlier reply, earlier
+  turns included, and answers HTTP 400 without it: under `turn` every turn after one that thought fails. Set
+  `reasoning_history: all` there (the example above). DeepSeek through OpenRouter takes `turn`.
 - `drop` sends none (what chi did before this setting).
 - `all` sends every reply's reasoning, earlier turns too. It sends only the field: a local template that leaves out
-  earlier turns' reasoning (Qwen's) needs `sampling: {chat_template_kwargs: {preserve_thinking: true}}` as well.
+  earlier turns' reasoning (Qwen's) needs `preserve_thinking` as well (above).
 - Order, first set wins: the session's own level, `SAMAGOTCHI_REASONING_HISTORY` (the whole process; for A/B runs),
   the `models:` entry (found the way `profile:` is), the `hosts:` entry, then `turn`. Anything else than a level warns
   once and counts as unset. A host's level reaches a worker when it starts, as its `sampling:` does.
@@ -597,9 +611,8 @@ models:
   | to or from `all`, once an earlier reply has thinking | every earlier reply gains or loses its reasoning: a server that renders it (hosted APIs, llama.cpp's default template) reads the conversation again from the first earlier thought |
   | nothing thought yet, the same level, or a native host | none |
 
-- The native loop (`/completion`) ignores it: it always keeps the running turn's reasoning, a mid-turn steer included
-  (the chat loop starts again after a steer), and a step-limit Continue keeps the thoughts of the run it continues,
-  a mid-turn steer's earlier ones included.
+- The native loop (`/completion`) ignores it: it always keeps the running turn's reasoning, a mid-turn steer included,
+  and a step-limit Continue keeps the thoughts of the run it continues, a mid-turn steer's earlier ones included.
 - When a host answers a request that sent reasoning back with an HTTP 400 about reasoning, chi asks again without it,
   sends none to that model from then on (until the worker restarts) and says so once. If the request without it is
   refused too, the thinking fields get the same fallback ("Thinking") and the reasoning goes back on the next step.

data/docs/context.md

@@ -346,6 +346,14 @@ show the answer as it is.
   at the PR's head commit (a removed one: at its base), which has every
   line.
 - Code blocks, markdown links and URLs are left alone.
+- **The ref menu**: each linked reference is also a
+  [file ref](hooks.md#refs-on-the-answer-display-only) on the answer: the
+  file in this checkout (the repository's root + the PR's path), so its
+  menu has the editor, show-in-turn and copy targets, plus **PR diff** (or
+  **File at head**, **File at base** for a removed file), the link's URL.
+  Only for a PR of this checkout's repository (one of its git remotes
+  names it on github.com): another project's PR keeps its links only.
+  Bundle 0.5.0, chi 0.61.0.
 - The PR's files are read with `gh api` in the background when a turn
   starts (and when a PR is attached while it runs), at most once a minute,
   and read again only when the PR's head moved; the answer is linked from

data/docs/guardrails.md

@@ -35,7 +35,8 @@ Approve tool call?
 
 In a terminal, answer with a number, the exact label, `y` (Allow once) or `n`
 (Deny); add `; reason` to tell the model why (`n; open a PR instead`). An empty
-answer, Ctrl-C, the web's Deny button or a cancelled turn deny it. The prompt stays open during turns: when the question comes up it turns
+answer, Ctrl-C, the web's Deny button or a cancelled turn deny it (on the web card, Enter in the reason box or
+on an option submits, never denies). The prompt stays open during turns: when the question comes up it turns
 into a yellow `? `, with the call and the options listed under it; only a line
 submitted there answers it (never one typed before), and what you had typed comes back
 once it closes. On a short terminal the list shrinks (the hint row, then the `in`/`why`

data/docs/hooks.md

@@ -51,7 +51,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 |-------|--------------|---------------|
 | `:session_start` | The first turn this chi process runs for the session (so again after `--resume`, a worker that idle-exited and woke, or a restart) | `{ type: :session_start, session_id: "..." }` |
 | `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), resumed: true \| false (true on a step-limit Continue, which resumes the run before it; false on every other turn, a reminder's or a wake's too), messages: [...] (the history before this turn) }` |
-| `:after_turn` | After a turn completed or was stopped once the model was asked (not after one that failed, was cut short by an interrupt signal (SIGINT), or was stopped before its `:before_turn` hooks) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
+| `:after_turn` | After a turn completed or was stopped once the model was asked (not after one that failed, was cut short by an interrupt signal (SIGINT), or was stopped before its `:before_turn` hooks) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), refs: (see [Refs on the answer](#refs-on-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N, restarted: true (only on the first fire after a dropped stream was asked again) }` |
@@ -275,6 +275,77 @@ end
 
 A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:present].call { … } }`.
 
+## Refs on the answer (display only)
+
+`:after_turn` also carries `refs:`, a callable that attaches a **ref** to the
+turn's answer: a thing the answer mentions (an issue, a file, a commit) as
+data, with links to open it. Like `present`, it is display only.
+
+```ruby
+class JiraRefs
+  def call(event)
+    return unless event[:type] == :after_turn
+
+    answer = event[:messages].last
+    return unless answer && answer[:role] == "model"
+
+    answer[:content].to_s.scan(/\b[A-Z][A-Z0-9]+-\d+\b/).uniq.each do |key|
+      event[:refs].call(match: key, kind: "issue", target: { id: key }, label: key,
+                        actions: [{ id: "open", label: "Open in Jira", url: "https://jira.example.com/browse/#{key}" }])
+    end
+  end
+end
+```
+
+- The call: `event[:refs].call(match:, kind:, target:, label: nil, actions: [])`,
+  keywords only (String or Symbol keys inside `target` and `actions`).
+  - `match`: the text in the answer the ref stands for (at most 500 characters).
+  - `kind`: a short lowercase word. `"file"` takes `target: {path:, line:, end_line:}`
+    (the lines optional); a relative path is resolved against the session's
+    folder, an absolute one is kept as given. Any other kind (`"issue"`,
+    `"commit"`, …) takes `target: {id:}`.
+  - `label`: what a UI shows for it (optional, at most 200 characters).
+  - `actions`: links a UI offers on top of the kind's own, each
+    `{id:, label:, url:}`; http(s) URLs only, without userinfo (`user:pass@`),
+    at most 8, opened in a new tab.
+- It returns `true` when the ref is kept (or was there already: a duplicate
+  is kept once), `false` when it is refused, and `nil` when the turn has no
+  answer (as `present`: after a cancelled, failed or empty turn) or the call
+  comes after the hooks ran (a plugin that kept `event[:refs]`: the refs are
+  stored by then).
+- Caps: 200 refs and 256 KiB (the list's JSON) per answer; an action's id
+  at most 64 characters and its label 100; a target id 200, a path 4,096.
+- A refused ref is logged as `refs_rejected` with the hook's label and the
+  reason, each reason once per hook per answer (the same again is logged at
+  debug with its count). The call never raises into the hook.
+- Refs are independent of `present`: a rejected `present` keeps them, and a
+  ref whose `match` isn't in the shown text is still stored (a UI drops it).
+- They are kept as `display_refs` on the answer's model message in the
+  session file, next to `display`, and the `answer_display` event says how
+  many (`refs: N`). The model never sees them (as `display`), and a fork
+  (`chi.sessions.fork(messages: ctx.messages)`) starts without them.
+- **The web** pairs each ref with the shown answer (its rendered markdown,
+  or the `present`ed display), live (with the turn-end read when the refs
+  are stored by then, else on the `answer_display` event) and on a reload. It looks, over all the answer's refs, for:
+  1. a link whose href is one of the ref's action URLs;
+  2. else a link whose text is `match`;
+  3. else `match` as a whole word inside one run of plain text (not in a
+     code block or another link), or an inline code that is `match` alone.
+     The word's edges are checked within that run only: text in the next
+     element doesn't count (`JIRA-1<em>2</em>` pairs `JIRA-1`).
+
+  The ref binds every occurrence its first finding step finds (a ref paired
+  with its link leaves a plain mention of the same text alone); a ref
+  nothing pairs is dropped. Markdown changes text: `__init__.py` renders
+  bold, escapes and entities differ, a match across emphasis or code isn't
+  one run, so keep a markdown link to the ref's URL, or match the rendered
+  text. The ref's actions join its menu (a link's own target is labelled by
+  the action with its URL); a `file` ref keeps the editor, show-in-turn and
+  copy targets; `label` is its hover title when it differs from the text.
+  **Terminals** ignore them.
+
+A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:refs].call(…) }`.
+
 ## Settings
 
 A hook class whose `initialize` takes an argument gets its settings: **one
@@ -565,6 +636,7 @@ bundles:
         pattern: '\bGH-(\d+)\b'   # full form: a regex
         url: 'https://github.com/org/repo/issues/{match}'
         case_insensitive: false   # optional, default false
+        kind: issue               # optional: the refs' kind, default issue
     max: 10                       # optional: refs per line, default 10
     note: false                   # optional: no sources line, default true
 ```
@@ -583,6 +655,13 @@ text ([`fallback_for: :display`](#what-a-hook-can-do-the-runtime)); it shows
 when it names one the answer doesn't link (a ref only in code, two sources on
 one ref) and whenever markdown is off. Bundle 0.4.0 needs chi 0.35.0 for that.
 
+Each ref the answer links is also a [ref on the
+answer](#refs-on-the-answer-display-only): kind `issue` (or the source's
+`kind:`, a short lowercase word other than `file`), target `{id: "JIRA-123"}`,
+label `JIRA JIRA-123`, and one action, **Open in JIRA** (the source's name),
+its URL. The web's ref menu on the link shows it. A ref whose URL isn't
+http(s) stays a markdown link only. Bundle 0.5.0 needs chi 0.61.0 for that.
+
 The `prefix:` form compiles to `\b<prefix>-(\d+)\b` and the URL is
 `base_url` + the full ref text (`JIRA-123`). The `pattern:` form takes a
 regex and a `url:` template with placeholders (below). `case_insensitive:

data/docs/internals/engine.md

@@ -56,9 +56,11 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     # end_turn(turn, "completed" | "canceled"): under the event lock the session gets the kept
   │     #   messages, goes IDLE, records last_turn, and :turn_completed {result, turn_summary,
   │     #   display_pending} or :turn_canceled {cancellation_reason, cancelled_by, duration_ms} is emitted
-  │     # then the :after_turn hook (status, messages, present: the AnswerDisplay presenter)
-  │     # store_answer_display (:answer_display to the observers when a hook changed the answer,
-  │     #   or display: nil when the web was told to wait for it)
+  │     # then the :after_turn hook (status, messages, present: the AnswerDisplay presenter,
+  │     #   refs: the AnswerRefs adder)
+  │     # store_answer_display (one replace of the answer: `display` and/or `display_refs`;
+  │     #   :answer_display {display, refs: N} to the observers when a hook changed the answer or
+  │     #   attached refs, or display: nil when the web was told to wait for it)
   │     # then the :session_end hook
   │
   ├── warm_up_next_turn(turn, result)
@@ -86,7 +88,7 @@ StandardError in run_turn:
      # error_kind, retryable, host and summary.
   → re-raised
 
-Interrupt (Ctrl-C):
+Interrupt (Ctrl-C; the REPL only: a worker traps INT, see the signal row below):
   → if turn.ended: re-raised only
   → turn.controller.cancel!(:ctrl_c)
   → end_turn(turn, "canceled"): ctrl_c_messages keeps turn.messages with TurnNote.cancelled(:ctrl_c)
@@ -102,6 +104,17 @@ A Stop (Engine#cancel_current_turn!, e.g. the Bridge's POST cancel) or a hook's
   → complete_turn keeps the loop's conversation (tool iterations included) with a
      TurnNote.cancelled note; a text streamed before the cancel stays, marked [interrupted]
 
+A worker's TERM, HUP or INT (WorkerSignals, trapped by a spawned worker only):
+  → a Stop with reason :signal (Worker#signalled, off the trap, retried until the loop leaves)
+  → :turn_canceled {cancellation_reason: :signal}, saved by the Worker as after any turn;
+     Worker#run returns :signal (:stopped with the stop marker), takes no new work
+  → not ended within Worker::SIGNAL_GRACE (a turn that ended and runs its after_turn hooks gets
+     SIGNAL_HARD_EXIT more, uncanceled): the session saved as it is, SignalException raised in the
+     loop's thread, only while the loop runs (never into start, serve or the teardown, which runs whole)
+  → the process ends SIGNAL_HARD_EXIT (10 s) after that at the latest (exit!); a signal after the
+     loop left brings only that hard exit, and run_session_loop restores the default handlers
+  → run_session_loop: exit 0, no discard; input queued behind the stopped turn wakes a new worker
+
 Stopped before the model was asked (prepare_turn returned false):
   → stopped_before_model(turn) → end_turn(turn, "canceled")
   → nothing kept, :turn_canceled {cancellation_reason, cancelled_by, duration_ms}
@@ -183,14 +196,15 @@ The differences from the native loop:
 - A model turn's saved reasoning (`thinking:`) goes back as `reasoning_content` per the turn's
   `TurnSettings#reasoning_history` (`ReasoningHistory.resolve`, the session's own level first:
   `Session#reasoning_history`, `/reasoning-history`): `all` on every model message, `turn` past
-  `ChatLoop#reasoning_boundary`: the later of the last query (a `role: "user"` entry: a prompt, a steer, merged input,
-  the chat template's `last_query_index`; or a `turn_start` entry) and the Run's start (`Run`'s `@start`, the
-  conversation length at `#complete`), so a continue turn (reminder, context wake, delegate report wake) replays
-  nothing of the run before. A step-limit Continue's Run starts where the run it resumes did: `#complete`'s
-  `reasoning_since:` (the Engine's `resume_from`, checked against the messages' length in `#resumed_run_start`) is
-  the Run's `@start`. `Run#prompt_chars` counts it (`#reasoning_chars`). The native loop differs on a steer:
-  `KernelLoop#inject_pending_input!` doesn't re-sanitize, so native keeps the turn's reasoning across a mid-turn
-  steer, where the chat loop starts again (as the template does).
+  `ChatLoop#reasoning_boundary`: the Run's `@reasoning_start`, fixed once per Run by `ReasoningHistory.run_start`
+  (the rule `KernelLoop#start_turn` uses too) from the Run's start (the conversation length at `#complete`), so a
+  continue turn (reminder, context wake, delegate report wake) replays nothing of the run before. Entries the Run
+  merges (a person's line, a plugin's steer, a Continue's text) don't move it, as natively (nothing re-sanitizes
+  within a run): the request after a steer extends the one before. A step-limit Continue's Run starts where the run
+  it resumes did: `#complete`'s `reasoning_since:` (the Engine's `resume_from`, checked against the messages' length
+  in `#resumed_run_start`), past a user entry added after that run's last reply (a `!cmd`'s output). Without
+  `since:` (`#reasoning_chars` from outside a Run) the boundary is the last query (a `role: "user"` or `turn_start`
+  entry). `Run#prompt_chars` counts it (`#reasoning_chars`).
 - A 400 about reasoning (`BadRequest#reasoning_refused?`) for a request that sent reasoning back asks the step again
   without it; when that goes through, `#reasoning_history_refused!` marks the model (worker lifetime) and
   `:reasoning_history_refused` goes out. When it is refused too, the thinking-fields fallback (`#thinking_refused!`,
@@ -227,13 +241,22 @@ One iteration with tool calls:
 - Runs the gate first, so `:tool_call_started` shows the call that will run (a before_tool_call hook may
   replace it; known-names corrects a misspelled name this way, and the model gets one line saying what ran).
 - Emits `:tool_call_started` {iteration, call_count, call_index, tool, call, params, label (plugin tools),
-  title, called_as, view, ref}. The row fields (title, called_as, view, ref) come from `ToolRowFields.for`, which the
+  title, called_as, view, ref, refs}. The row fields (title, called_as, view, ref) come from `ToolRowFields.for`, which the
   reload (`Web::MessageParts#tool_part`) calls too. `ToolRowFields::ACTIVITY_KEYS` (title, called_as) travel
-  inside `activity` on the completed event; `EVENT_KEYS` (view, ref) go top-level on both events.
+  inside `activity` on the completed event; `EVENT_KEYS` (view, ref, refs) go top-level on both events.
   `Bridge::TurnAccumulator` (snapshot and replay) and the web (`activity.js` `ACTIVITY_FIELDS` /
   `EVENT_FIELDS`) copy them by these lists, so a new row field is added there. `ref` is `FileRef.for` (a
   read/write/edit's file against the cwd, `{kind: "file", path, line?, end_line?}`); the web opens it in the editor
   that `Web::Editor` (web.editor) names, for a local viewer only (`App#viewer_capabilities`).
+  `refs` is a plugin tool's row refs: its registry entry's `refs` (chi.tool's `refs:` lambda, `Api.per_call`), run
+  once per call by `RowRefs.for` (never raises: a raise or a non-list gives none, `tool_refs_failed`; each entry a
+  `Ref`, a bad one dropped, `tool_refs_rejected`; a relative file resolved against the session's folder
+  (`KernelLoop#session_cwd`, else the process's), one outside it (its spelling or its real path) dropped, a kept one
+  stored under the real path; at most `RowRefs::MAX_REFS` and `MAX_BYTES`). `ToolRowFields.for` can't build it (no plugins on a reload), so the run carries it
+  as `refs:`, saved with the result as `tool_refs` (`ToolResponse::SAVED_KEYS`, never sent), and
+  `MessageParts#tool_part` reads it back through `RowRefs.for_display` (checked again). The page binds them to the
+  row's title (`refs.js bindRowRefs`, from `turn_view.js` live and on a reload): the first ref on it, the rest in its
+  menu.
 - Settles an ask verdict after `:tool_call_started`, so a UI shows the tool line and then the approval.
 - Dispatches through `KernelLoop#dispatch_tool_call`, or writes the denial text. Unknown tools are answered in
   `KernelLoop#dispatch` ("Error: no such tool ...", never repeating the wrong name).
@@ -299,6 +322,17 @@ end
   turn through the Bridge (`POST cancel` → `Engine#cancel_current_turn!`).
 - `on_event` is the turn's sink.
 - `ended` is set by `end_turn`.
+- The live conversation: both loops register the array they append to on the kernel
+  (`KernelLoop#llm_context_turn`, `LLMContextForget::Turn#conversation`; `KernelLoop#start_turn`,
+  `ChatLoop::Run#initialize`). `Engine#live_conversation` returns it while a turn runs (nil otherwise: the kernel
+  never clears it). A worker's drain (`Worker#pending_input_drain`, on the turn's thread at every iteration
+  boundary) copies it, with the lines that boundary merges, into `Session#turn_checkpoint` (`TurnCheckpoint`):
+  every save while the turn runs writes that copy with an `interrupted_turn` mark instead of the session's
+  messages, written at the first boundary and then at most every 10 s, so a killed worker loses at most that much
+  of its turn. `session.messages` itself is untouched until the turn ends. When the checkpoint writes, the worker
+  also calls `Engine#checkpoint_metrics` (`SessionMetrics#persist(running_turn: true)`): `analytics.json` gets the
+  running turn's record so far as a killed turn's (canceled, `worker_stopped`), which the next worker loads; the
+  turn's end writes over it.
 
 ### GenerationPhase
 
@@ -352,7 +386,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:turn_completed` | normal end | `{result, turn_summary, display_pending}` |
 | `:turn_canceled` | Stop, hook stop, Ctrl-C | `{cancellation_reason, cancelled_by?, duration_ms}` |
 | `:turn_failed` | an error | `{error_class, message, duration_ms, error_kind?, retryable?, host?, summary?}` |
-| `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display}` (a string, or nil) |
+| `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display, refs?}` (display a string, or nil; refs the count of the answer's refs, only when a hook attached some) |
 
 The boundary events (`:turn_started`, `:turn_completed`, `:turn_canceled`, `:turn_failed`) also carry `origin`
 when the turn was queued with one.
@@ -410,6 +444,14 @@ puts the hook runtime on the event: `event[:hook]` (the hook's label) and five h
 
 From `:after_turn` and `:session_end` there is no turn left: `stop_turn` and `steer` return false.
 
+`:after_turn` adds two of its own, built by `complete_turn` on the stored conversation's last message when it is the
+model's: `event[:present]` (`AnswerDisplay`, the answer's `display` text) and `event[:refs]` (`AnswerRefs`, refs kept
+as `display_refs`: caps, validation, relative file paths resolved against the session's folder, `refs_rejected`
+logged). Both are display only: `AnswerDisplay::DISPLAY_ONLY` lists `display`, `empty_answer` and `display_refs`, which
+`strip`/`strip_all` drop from every model-facing copy (hooks' `messages:`, the recap, `ctx.messages`,
+after_generation), while `KernelLoop#sanitize_history` and `ChatLoop#plain` copy them so the stored conversation keeps
+them across turns. `Web::App#messages_for_display` sends `display_refs` re-validated (`AnswerRefs.for_display`).
+
 ### Hook lifecycle
 
 - **Bundle hooks** (`Registry#register_bundle`) and **config hooks** (`register_persistent`, from config.yml)

data/docs/internals/prompt-caching.md

@@ -127,7 +127,14 @@ is prefilled once. The native and the chat loop use the same plan.
    a per-session value in the stable part. A guard spec checks that model, location and session are the last
    sections (`spec/system_prompt_model_spec.rb`).
 2. **History is append-only.** Never rewrite an earlier message. Add a note at the tail instead. If a model's
-   spec forces a rewrite (e.g. stripping previous-turn thinking), accept the re-prefill and note it.
+   spec forces a rewrite (e.g. stripping previous-turn thinking), accept the re-prefill and note it. Within a
+   turn both loops keep the turn's replies as sent across a mid-turn steer, a plugin's nudge and a Continue's text
+   (`ReasoningHistory.run_start` fixes where the run's reasoning starts), so the request after a steer is the one
+   before plus the steer; a new turn drops the previous turn's reasoning under `turn` (one re-prefill from its
+   first reply, on a server that renders it; a stock Qwen template without `preserve_thinking` re-renders from the
+   reply before every user message whatever chi sends). A worker's
+   mid-turn checkpoint (`TurnCheckpoint`) is append-only too (the history plus what the loop appended) and
+   never changes the request bytes.
 3. **Deterministic order.** Tools, memory lists and anything else that's rendered from a hash or a set needs a
    fixed sort. Plugin tools are sorted by (bundle, name) whatever order their plugins finished starting in
    (R5a).