samagotchi 0.59.0 → 0.61.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 399c5b5b4ad3423bd266545c1f190e9e269f070a26bc48350640bf774eea7c4b
-  data.tar.gz: 26bfce90ed8fe75c15c777943f07699803f70160f54559ae057ba31eb168d956
+  metadata.gz: a3f828171b95ef34cef1b89706f21a34822ea73dae63e55b2219767961241f7c
+  data.tar.gz: b12760887f0613c4e087f824f653e8ccc20e0602de55ef69fd8aed69a897a33c
 SHA512:
-  metadata.gz: 042a3460c486987f7bd120fa6615c5cdd65d1ca6da0edfe9548746b83d9b66c6ad532b7088c20af082751b9bfad64252fba93123845fb36cfa0875d1a54ec0bf
-  data.tar.gz: f441e37232ea17b6af0ca047aea5331d7e062b3563382656fb323118f8607459cf97540858fccae714691aabfe989dd666f8de379f2024bc7a4b024864b2a694
+  metadata.gz: e68486688dfe56739e1d05a68549d050f3cb73c369536c5fa097d832baabcfb42ba41917580ad9d0a4707ab3933550247177e92b0184dee2493b467be5773bad
+  data.tar.gz: 630eca4f31585d00938ad89b77275d25969384301b43c71415e20fac95be9fb22dfa60695f59afd1fe612e4cad8de94ead8ab949464c6ab7f21eb18fb8667357

data/CHANGELOG.md

@@ -8,6 +8,92 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [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
+
+- chi web has a favicon: χ on a blue-to-violet rounded square. Safari showed a "1" monogram before.
+- `chi --append-system-prompt FILE` (repeatable) and a config.yml `append_system_prompt:` list: a file's text goes
+  into the system prompt after AGENTS.md, in the cached part. A relative config entry is looked up where chi runs
+  (`append_system_prompt: [CLAUDE.md]`); the flag's files are saved in the session and kept by forks and continues.
+  `/stats` names the prompt's files on a `prompt files:` line.
+- An analytics `resumed` mark on the turn record of a step-limit Continue (`resumed: true`; every other turn has
+  `resumed: false`). `continue` also marks a reminder's and a wake's turn, so `script/model_notes_report` now counts
+  Continues from `resumed`, falling back to `continue` record by record for older files. `:turn_started` and the
+  `before_turn` hook payload carry `resumed` too.
+- A hook's or plugin's notice can be marked `fallback_for: :editor`: a line naming a file the viewer could open from
+  a ref. The web leaves it out for a viewer on this machine with `web.editor` set; a phone and the terminals show it.
+- `ctx.prompt_files` for plugins: the files whose text is in the session's system prompt now — the AGENTS.md chain
+  and the appended files — as absolute paths in prompt order.
+- The `agents-md` bundle, in the `core` profile (core 0.3.0: `chi update` installs it for existing core users):
+  a nested `AGENTS.md` of the session's checkout — one in a directory the session doesn't run in, which the
+  system prompt never sees — is steered into the conversation the first time a tool (`read`, `write` or
+  `edit`) touches a file under its directory, outermost first, once per session, and never re-injected after a
+  resume or a woken worker. It never stops generation or thinking, and leaves the chain's and appended
+  `AGENTS.md` files alone (`ctx.prompt_files`). Files in another repository, a nested repository or a
+  submodule are ignored. Opt out with `skip_agents_md: true`, as with the chain; `bundles: agents-md:`
+  settings: `tools`, `max_chars`. See "The agents-md bundle" in docs/plugins.md.
+
+### Changed
+
+- The default step limit (`turn.max_iterations`) is 300, up from 100: most long build turns now finish in one turn
+  instead of stopping at the step-limit question. Loops are caught by the loop-guard bundle, and check-in's card
+  (at 50 tool calls, then every 50) still says a turn is long without stopping it. `--no-interrupt` stays 1000.
+- Started in a subdirectory, chi loads every `AGENTS.md` from the top of the git work tree down to the current
+  directory, outermost first, instead of the subdirectory's replacing the root's. A further file is headed with its
+  directory ("Project specific description for pkg/:"); a session with one `AGENTS.md` gets the same prompt as before.
+
+### Fixed
+
+- A step-limit Continue no longer drops the turn's reasoning: on a chat host (`reasoning_history: turn`) the
+  continued turn sends the earlier replies' reasoning back as before the limit, and on a native host
+  (`/completion`) the prompt keeps the run's thought blocks, those before a mid-turn steer too. The model keeps its
+  thinking, and the first request after the Continue matches the last one before the limit (before the fix, a local
+  27B read most of a 17k prompt again: 24.9 s to the first token instead of 4.0 s). Continue's text is a steer, and on a chat host still starts
+  the reasoning afresh from it. After a `/model` change while the question stands, the Continue starts afresh.
+
+Update with `chi update`: the system bundle 0.60.0, the core profile 0.3.0 (now with agents-md) and the new
+agents-md 0.1.0 bundle.
+
 ## [0.59.0] - 2026-10-11
 
 ### Added
@@ -2576,7 +2662,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.59.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.61.0...HEAD
+[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
 [0.57.0]: https://github.com/dm1try/samagotchi/compare/v0.56.0...v0.57.0

data/README.md

@@ -76,8 +76,9 @@ It finds out whether the server is llama.cpp or OpenAI-compatible, picks the
 model (or asks, when there are several), sends one test request and writes
 the config. With a config already there, it adds a `hosts:` entry and keeps
 the rest of the file. Then it installs the `core` bundles (loop-guard,
-check-in, guardrails, slow-commands: the safety set for a small local model) and, on a
-terminal, offers `dev` (known-names, mcp, btw, skills, source-links). Edit the
+check-in, guardrails, slow-commands, agents-md: the safety set for a small
+local model) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
+source-links). Edit the
 file later as in [Configure](#configure); `chi bootstrap --help` has the
 options.
 

data/bin/chi

@@ -82,7 +82,7 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
+  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -120,6 +120,8 @@ parser = OptionParser.new do |opts|
                               "before the model's; default unsets it; /thinking changes it). With chi web: the default for the sessions " \
                               "its workers run, below a session's own [env SAMAGOTCHI_THINKING_LEVEL]") { |l| options[:thinking] = l }
   opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
+  opts.on("--append-system-prompt FILE", "Put FILE's text into the system prompt, after AGENTS.md (repeatable; saved in the session; " \
+                                        "config append_system_prompt: is the baseline)") { |f| (options[:append_system_prompt] ||= []) << f }
   opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
   opts.on("--llm-context LAYERS", "This session's own LLM context strategy: none, or layers such as stale,forget (saved in the session, " \
                                  "before the model's; /llm-context changes it)") { |v| (options[:llm_context] ||= {})[:strategy] = v }
@@ -308,6 +310,23 @@ if options[:llm_context]
   end
 end
 
+# --append-system-prompt: each file is checked here, before anything starts
+# (the user named it, so a missing one is an error), and made absolute
+# against this shell's cwd.
+if options[:append_system_prompt]
+  require "samagotchi/prompt_files"
+  options[:appended_prompt_files] = options[:append_system_prompt].map do |value|
+    path, reason = Samagotchi::PromptFiles.check_cli_file(value)
+    if reason
+      warn "Error: --append-system-prompt #{value}: #{reason}"
+      exit 1
+    end
+    chars = Samagotchi::PromptFiles.large_size(path)
+    warn "Warning: --append-system-prompt #{value} is #{chars} chars; it is in every request" if chars
+    path
+  end.uniq
+end
+
 chi_update_hint.call
 require "samagotchi/launch_mode"
 launch, launch_note = if scratch
@@ -341,7 +360,8 @@ if launch == :attached
                                                        memories: options[:memories] || [],
                                                        muted_memories: options[:muted] || [],
                                                        llm_context: options[:llm_context] || {},
-                                                       thinking: options[:thinking])
+                                                       thinking: options[:thinking],
+                                                       appended_prompt_files: options[:appended_prompt_files] || [])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
@@ -360,6 +380,7 @@ begin
     muted_memories: options[:muted] || [],
     llm_context: options[:llm_context] || {},
     thinking: options[:thinking],
+    appended_prompt_files: options[:appended_prompt_files] || [],
     non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch

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. |
 
@@ -177,7 +177,8 @@ forwards the raw `KernelLoop` events unchanged (the low-level contract) and adds
 higher-level events so UIs get clean turn boundaries without inferring them:
 
 - `:turn_started` — `{ session_id:, prompt:, turn_id:, cut_after: }` (`cut_after`: the seconds a cut waits for this
-  model's thinking, `0` = never; plus `continue: true` for a continue turn, `images:` with the prompt's image refs)
+  model's thinking, `0` = never; plus `continue: true` for a continue turn, `resumed: true` for a step-limit Continue,
+  `images:` with the prompt's image refs)
 - `:turn_completed` — `{ result:, turn_summary:, display_pending: }` (`result`: the final
   `LLM::ModelResult`; `display_pending`: `after_turn` hooks may still present the answer)
 - `:turn_canceled` — `{ cancellation_reason:, cancelled_by:, duration_ms: }` (`cancelled_by`: the bundle or hook label that
@@ -296,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: *`).
@@ -317,11 +319,13 @@ 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.
 - `?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.
@@ -394,7 +398,8 @@ stream with a fresh `ThoughtStreamSplitter` (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped
 from `text:`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
 so later requests and resumed sessions pair them, and their reasoning (`thinking:`), which goes back as
-`reasoning_content` on the running turn's replies (`reasoning_history`). It has its own system prompt
+`reasoning_content` on the running turn's replies (`reasoning_history`; a step-limit Continue's
+turn goes on from the run it resumes, `reasoning_since:`). It has its own system prompt
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 
 `Engine#build_stream_event_handler` is the one seam both loops' streams pass
@@ -449,7 +454,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

@@ -189,6 +189,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
+| `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |
 | `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
 | `--llm-context LAYERS` | This session's own LLM context strategy: `none`, or layers such as `stale` or `stale,forget` (comma, space or `\|` separated). Saved in the session, before the model's `llm_context_strategy`. With `--resume` it is set on the resumed session; on an attached or resumed worker it runs as `/llm-context` before the first prompt (after `--model`'s `/model`). A value that isn't one is an error before anything starts. See "LLM context: a session's own strategy" in configuration.md. |
 | `--llm-context-apply RULE` | This session's own apply rule: `payoff`, `next_request` or `turn_end`. |
@@ -504,7 +505,8 @@ back from the next turn on, and where that came from (`session`,
 comes first; `/reasoning-history default` unsets it. It is saved and carried as
 `/thinking`'s is, and a native host ignores it (the reply says so). A change to
 or from `all` once an earlier reply has thinking rewrites the earlier replies;
-`drop` ↔ `turn` costs nothing. `/stats` shows it on its `reasoning history:`
+`drop` ↔ `turn` costs nothing. Under `turn` a step-limit Continue keeps the
+reasoning of the turn it continues. `/stats` shows it on its `reasoning history:`
 line, the web as the `reasoning` chip. See "Reasoning history" in
 [configuration.md](configuration.md).
 
@@ -997,7 +999,7 @@ Behavior notes:
 ## Iteration Limit Behavior
 
 - A turn's step limit (model ↔ tool rounds) is `turn.max_iterations` in config.yml (env
-  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `100`, an integer of 1 or more). `--no-interrupt` and
+  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `300`, an integer of 1 or more). `--no-interrupt` and
   `--non-interactive` turns get the larger of 1000 and it. Reminder turns follow it too.
 - Tool side effects that already ran before the limit are not rolled back.
 - `Samagotchi::KernelLoop#run` returns a resumable result object with the visible output plus the accumulated
@@ -1016,9 +1018,13 @@ Behavior notes:
 - In the plain REPL (`--no-shared`) the CLI asks at the `? ` prompt, with the choices listed under it: `yes` (Enter
   alone, or `/continue`) resumes, `no` stops, and `no, <explanation>` stops while keeping the reason in conversation
   context. Once answered, one line stays: `? The turn ran out of iterations. Continue it? → no, too slow`.
+- Continue goes on with the same turn: the model keeps the reasoning (thinking) of the run it continues, on chat and
+  native hosts, so a local server's prompt cache stays warm. Continue's text is a steer: on a chat host the reasoning
+  starts again from it. See "Reasoning history" in [configuration.md](configuration.md).
 - Stop keeps the interrupted turn's work in the conversation, as a Ctrl-C or a new prompt does, with a note for the
   model that it wasn't continued (or your reason); `!rollback` still erases it.
 - `--non-interactive` (`chi -p`) has nobody to ask: the turn ends there. A `chi send --wait` on a session nobody can
   answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`.
 - The check-in bundle's card closes as the turn ends, before the step-limit question opens, so the two never stand
-  together; with check-in's default `after: 50` and the limit of 100 a long turn usually shows a check-in card first.
+  together; with check-in's default `after: 50` and the limit of 300 a long turn shows check-in cards (at 50, 100, …)
+  well before it.

data/docs/configuration.md

@@ -81,6 +81,13 @@ session:
 memories:
   # - system/user_preferences
   # - project/feature-env-template
+
+# Files whose text goes into the system prompt after AGENTS.md (same as
+# --append-system-prompt, which adds to these). A relative entry is looked up
+# in the directory chi runs in; a missing one is skipped.
+append_system_prompt:
+  # - CLAUDE.md
+  # - ~/notes/house-rules.md
 ```
 
 Behavior:
@@ -108,8 +115,8 @@ Besides the settings sections, the file holds maps that are read by their
 own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
 "Images"), `model_aliases:`, `hooks:` (see [Hooks](hooks.md)),
 `guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
-settings for its hooks, see [Hooks: Settings](hooks.md#settings)) and
-`memories:`. Their entry names (host names, model ids, aliases) are yours to
+settings for its hooks, see [Hooks: Settings](hooks.md#settings)),
+`memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
 choose. The `memories:` list is the persistent baseline for preloaded memory entries —
 the same name shape as `--memory` (bare name or `scope/name`), merged under
 any per-run `--memory` values (config baseline first, deduped). A per-run
@@ -561,8 +568,13 @@ models:
   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 continue after a stop) sends nothing of the one
-  before it, an interrupted reply's partial thought included.
+  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).
 - `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.
@@ -586,7 +598,8 @@ models:
   | 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).
+  (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.
 - 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.
@@ -1074,13 +1087,50 @@ The helper reads these from its launch file: after editing them run
 If an AGENTS.md file is present in the project root, samagotchi injects its
 contents into the system prompt under a "Project specific description:" section.
 The project root is the top of the git work tree chi runs in (a linked
-worktree's own checkout), or the current directory outside a repository. An
-AGENTS.md in the current directory is read instead when there is one; only one
-file is read.
+worktree's own checkout), or the current directory outside a repository.
+
+Started in a subdirectory, chi loads the chain: every AGENTS.md from the work
+tree top down to the current directory, outermost first. The first keeps the
+plain header; each further one is headed with its directory, e.g. "Project
+specific description for pkg/:". Outside a repository only the current
+directory's AGENTS.md is read. Edits are picked up by a new process or a
+prompt rebuild (`/model`).
 
-To skip loading AGENTS.md, set `skip_agents_md: true` at the top level of
+To skip loading AGENTS.md (all of the chain), set `skip_agents_md: true` at the top level of
 `config.yml` (env `SAMAGOTCHI_SKIP_AGENTS_MD=true`).
 
+Nested `AGENTS.md` files (in directories the session doesn't run in) are
+steered into the conversation on first touch by the `agents-md` bundle
+([The agents-md bundle](plugins.md#the-agents-md-bundle)); `skip_agents_md`
+disables that steering too.
+
+## Appended prompt files
+
+`append_system_prompt:` (a top-level list) and `chi --append-system-prompt FILE`
+(repeatable) put a file's text into the system prompt right after the AGENTS.md
+chain and before the memory indexes, in the stable part a prompt cache keeps.
+Each file is one section, `Appended from <path>:`, the path relative to the
+work tree top when inside it, else with `~`.
+
+- The config list comes first, then the flag's files; a repeat, or a file the
+  AGENTS.md chain already holds, is left out, and so is an empty file.
+- A config entry: `~` is expanded, and a relative one is looked up in the
+  directory chi runs in, so `append_system_prompt: [CLAUDE.md]` loads a
+  project's `CLAUDE.md` wherever there is one. A missing entry is skipped
+  without a warning. The list is read when the session's engine starts (a new
+  process picks up an edit).
+- `--append-system-prompt FILE`: relative to the shell's directory. A missing,
+  unreadable or non-file `FILE` stops chi (`Error: --append-system-prompt FILE:
+  no such file`); above 32,000 chars it warns once (`… is N chars; it is in
+  every request`). The files are saved in the session (`appended_prompt_files`),
+  so a respawned worker builds the same prompt, and a fork or a continue keeps
+  them; a delegate child doesn't. With `--attach` or `--resume` the flag is
+  ignored with one line, as `--memory` is; a REPL `--resume` (`--no-shared`)
+  adds them for that run only.
+- The files' text is read at each prompt build, as AGENTS.md's is: an edit is
+  picked up by a new process or a rebuild (`/model`). `/stats` lists the files
+  in the prompt on its `prompt files:` line.
+
 ## LLM context: the forget layer
 
 Experimental, off by default. With `forget` in a model's `llm_context.strategy` (next to `stale`), chi offers that
@@ -1219,8 +1269,8 @@ Every setting below takes the three forms described in
 `config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment (not for one
 marked config.yml only) and, where the CLI
 column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
-`model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`) are
-described in their own sections.
+`model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`,
+`append_system_prompt:`) are described in their own sections.
 
 | Setting | Default | CLI | What it does |
 |---|---|---|---|
@@ -1306,7 +1356,7 @@ described in their own sections.
 | `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
 | `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. `models.<key>.steer_cut_after` and `hosts.<name>.steer_cut_after` come first; see [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
 | `models.<key>.steer_cut_after`, `hosts.<name>.steer_cut_after` | none | | A model's or host's seconds a cut waits for its thinking: whole seconds, `0` = never (e.g. a slow local thinker). `/model` shows the resolved one. See [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
-| `turn.max_iterations` | `100` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
+| `turn.max_iterations` | `300` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
 | `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |

data/docs/hooks.md

@@ -50,8 +50,8 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | Event | When it fires | Event payload |
 |-------|--------------|---------------|
 | `: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), 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)) }` |
+| `: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)), 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) }` |
@@ -117,7 +117,7 @@ known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
 `event[:notify]` also takes `fallback_for:`, what the line stands in for, so
-that a UI that already shows it can leave the line out. The one value is
+that a UI that already shows it can leave the line out. The main value is
 `:display`: the line repeats what the hook's
 [`event[:present]`](#presenting-the-answer-display-only) display shows (its
 links), for a UI that doesn't render that display. The hook never names a UI;
@@ -125,7 +125,13 @@ each decides by what it renders. The web with markdown on (`web.markdown` and
 the commonmarker gem) leaves such a line out, live and after a reload; with
 markdown off it shows, as it does in the REPL, the attached TUI and
 `chi -p`, which print the answer as text. The log keeps the line with
-`fallback_for=display`. Another value, or none, shows the line everywhere.
+`fallback_for=display`. `:editor` marks a line that names a file the viewer
+could open from a ref in its editor: the web leaves it out for a viewer on
+this machine with `web.editor` set, and every other UI and viewer (a phone,
+the terminals) shows it. Name only a file the page shows as a ref (one a
+tool row touched): a loopback viewer with `web.editor` set never sees the
+line, so a file it can't open from a ref would be lost to it. Another value,
+or none, shows the line everywhere.
 Mark a line only when the display really shows all of it (source-links marks
 its note only when the answer links every URL the note names). It needs chi
 0.35.0: an older chi's `event[:notify]` raises `ArgumentError` on the keyword,
@@ -269,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
@@ -507,7 +584,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
+- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle: