samagotchi 0.84.0 → 0.86.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5e180d3ef3bc5dd32bd646d471b1ef88e11083aba16f6908a8c4588b0173b4c
-  data.tar.gz: b337e5690f3094d5f3b0e8528aacbedab734211c9be60ed5ff314f6eb4299ea7
+  metadata.gz: 9bd5a2287b8113de9eb91acc1a735e6e132f339dd1569567e7cec6e1bea6637a
+  data.tar.gz: 2cfb2f0a9cc14bb226e227fcced1ce2efb16268707953423bd1db991070e36d5
 SHA512:
-  metadata.gz: 4ce619eccbfc69729b160a2b19c65d3b8e91d0f2b641fb6d4eb288d8fd12e9a147529745a8a3b5272270a2fabec6e597f423086c6574cb06f689816b32550568
-  data.tar.gz: 4a9922290d92cabab3aac30f17292119cc6e778243a7e1b57bd8260423a27446b34b978346056566619f8e358da8dabbd9e80f8bc3aa9fc198dab99e9b27b38c
+  metadata.gz: 3d5c8b88e0d4ab6fbebdb80d1705ae2904d6b5ac59b463099c9101f22161a912cbe56fe93da7cdcef672f62cc4162d212325c884f66a49aa27385a9aa71ba160
+  data.tar.gz: 3a54cc7c7629d902d1857e85b2f6fa43d2fb36805bf85ac733bfa4fba614c7a9488080dd40633c40e94ccae0749fdcce4f05c3fc7888b6e65931cd5cd492477d

data/CHANGELOG.md

@@ -8,6 +8,83 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.86.0] - 2026-10-18
+
+### Added
+
+- `chi bundle new NAME`, `chi bundle check [PATH] [--fix]` and `chi bundle test [PATH]` for writing a bundle: a
+  scaffold that checks clean and passes its test; a check that installs and loads the bundle in a sandbox and prints
+  one finding per line with a fix hint (manifest, sha256 lines, load errors with file:line, `requires_chi` floor,
+  trust, what it registers), `--fix` filling the sha lines; its tests run on chi's own Ruby and lib. `check` and
+  `test` run the bundle's code in their process: run them on code you'd install. docs/bundle-authoring.md (shipped
+  in the gem) is the first read.
+- chi tells you when a changed config.yml setting applies only after a restart ("server.port changed — applies after
+  a worker restart"; chi web's settings: after restarting chi web).
+- The `ruby` bundle (`chi bundle install ruby`, or the `dev` profile): an `execute` that ran RSpec and found no
+  examples at all (`0 examples, 0 failures`: a path, a `-e`/`--tag` filter or a `.rspec --pattern` that matched
+  nothing) steers a hint into the turn instead of leaving the run looking green.
+- A plugin's or a hook's `ask_user` takes `effects:` (option label => `:spend`, `:permit`, `:permit_wide`, `:deny`;
+  untagged = `:answer`), so a parent agent's answer is held to `guardrails.parent_answers`. The bundle test kit
+  records them (`bundle.questions.last.effects`). cost-cap 0.2.0 tags its Continue `:spend` and Stop `:deny`: under
+  `hard` a parent may only Stop it.
+
+### Changed
+
+- **What a parent agent may answer is one setting, `guardrails.parent_answers`** (`hard`, `standard`, `soft`), by
+  each option's effect, for every question: approvals, the step-limit Continue, relayed delegate approvals and plugin
+  and hook questions. **The default `soft` lets a parent give "Allow once"** (before, a parent could only deny an
+  approval); `standard` is the old default (deny, and Continue), `hard` lets a parent only deny, Stop or answer
+  plainly. A wider scope and any allow on chi's own config stay the user's. `chi send --wait`, `chi answer` and
+  `delegate_result` list what the parent may give. An invalid value warns and is `hard`. A parent's `/continue yes`
+  (`chi send ID -m '/continue yes'`, a piped `chi --attach`) is held to it too, as chi answer's.
+- SSE chunks carry chi's normalized `counts` instead of the provider's raw `payload` (and no `content`). An external
+  SSE client reading them moves to `counts` / `text` / `thinking`; `?raw=1` on the worker's stream shows the raw form.
+- At the top context bucket (no forget layer) the model's `[CONTEXT: …]` line asks for a short handoff note (state,
+  next step) instead of "summarize aggressively": "context critical — write a short handoff note (state, next step),
+  avoid large outputs, delegate broad work to subagents".
+- `guardrails.parent_approvals` and `turn.parent_continue` are removed: config.yml warns about them and names
+  `guardrails.parent_answers` (`parent_approvals: once` → `soft`; `turn.parent_continue: false` → `hard`). The old
+  pair `parent_approvals: once` with `turn.parent_continue: false` (Allow once but no Continue) has no equivalent:
+  the nearest is `hard`, which leaves both to the user.
+- The Bridge's and the relay's 403 for a refused parent answer is `parent_answer_refused`, with its `reason`
+  (was `parent_approval_refused` / `parent_continue_refused`).
+- The guardrails bundle's asks before answering chi's questions around `chi answer` (`chi-answer-piped`: `chi
+  --attach` or `chi -p` fed from a pipe or a file; `chi-answer-http`: `curl …/answer`) are the user's alone: a parent
+  agent's Allow is refused, as on chi's own config (guardrails bundle 0.9.2: its comment says so).
+
+### Fixed
+
+- `chi send --wait` no longer times out when a fallback input file carries a session command: the command's completion is recorded as that input's terminal outcome.
+- An image-only prompt sent from an attached terminal is no longer echoed again as an image line when its turn starts.
+- `chi send --queue --wait` (and a wait for a turn by its id) no longer waits until its timeout when the worker dies
+  in the middle of that turn: once the next worker settles it, the wait ends `canceled` with
+  `cancel_reason: worker_stopped` ("its worker exited mid-turn"). Another send's wait is not ended by it.
+- `chi web`'s end-of-turn re-read of the answer could keep a plugin's file ref outside the session's folder when
+  neither the worker nor the session hub named the folder (an older worker): it now takes the folder from the session
+  file, as a reload does, and drops the answer's file refs when no folder is known.
+
+Update with `chi update` (the system bundle 0.86.0, core 0.3.3, guardrails 0.9.2, cost-cap 0.2.0, dev 0.6.0 with the new ruby
+bundle 0.1.0), then restart `chi web`.
+
+## [0.85.0] - 2026-10-18
+
+### Added
+
+- A message queued for after the running turn can be taken back before it runs: the × on its bubble in the web,
+  `/unqueue` in an attached terminal (its newest queued line). Its text comes back into the input to change and send
+  again. Every UI drops it, and a `chi send --queue --wait` on it ends with `removed` (exit 1). `/queue` is now listed
+  in the attached terminal's Tab and `/help` too.
+
+### Fixed
+
+- On a phone, a queued message's text gets the bubble's full width, with its origin and after-turn badge above it.
+- A plugin's `ctx.settings` reads a session's `--set` values again after a failed read, instead of keeping config.yml's
+  alone until the worker restarts.
+- A `before_generation` hook now runs before the generation starts (`:generation_started`) in both loops: a question
+  it asks (the cost-cap's) no longer counts in the generation's time or leaves an empty generation on Stop.
+
+Update with `chi update` (the system bundle 0.85.0), then restart `chi web`.
+
 ## [0.84.0] - 2026-10-18
 
 ### Added
@@ -3389,7 +3466,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.84.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.86.0...HEAD
+[0.86.0]: https://github.com/dm1try/samagotchi/compare/v0.85.0...v0.86.0
+[0.85.0]: https://github.com/dm1try/samagotchi/compare/v0.84.0...v0.85.0
 [0.84.0]: https://github.com/dm1try/samagotchi/compare/v0.83.0...v0.84.0
 [0.83.0]: https://github.com/dm1try/samagotchi/compare/v0.82.0...v0.83.0
 [0.82.0]: https://github.com/dm1try/samagotchi/compare/v0.81.0...v0.82.0

data/docs/architecture.md

@@ -245,10 +245,33 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   too-old reconnects, and cursors from another worker's epoch, receive a `reset` marker carrying
   `session_state_snapshot`. `?snapshot=1` joins with a snapshot frame instead of a replay;
   `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
+  Each event goes out as clients get it (`Bridge::ClientEvent.project`, in `SSEWriter#write_event`, live
+  and replayed alike); only a `generation_chunk` changes, to chi's own format (the chunk contract below).
+  `?raw=1` writes events as the engine emitted them, for debugging on the worker's port: `chi web`'s
+  `/api/sessions/:id/stream` never passes it on (`Web::App#stream_query`).
   An attached terminal's stream (`EventStream` with `rediscover:`) looks for the session's live
   worker whenever it drops: a new one (a restart) is followed from its snapshot, and the terminal
   sends its requests there (`worker_changed`); it gives up after ~12 s, or at once when the session
   was stopped.
+
+  The wire chunk (the contract; the engine's own event keeps the provider's `payload` and the raw `content`):
+
+  ```
+  event: generation_chunk
+  data: {"type":"generation_chunk","iteration":2,"text":"…","thinking":"",
+         "tool_call":true,                                   // only when set
+         "counts":{"prompt_tokens":489,"completion_tokens":12,
+                   "total_tokens":501,"context_window_tokens":32768},  // only when the server reported counts
+         "event_seq":812}
+  ```
+
+  `counts` is `ContextUsage.normalize` of the provider's payload without `ctx_pct` (normalize computes it
+  without the session's LLM context budget; a client counts `total_tokens` against the window or budget, as
+  `ContextStatus#generation_done` does for the TUI) and with its nil keys left out: cumulative for the
+  request, a missing key means unknown (never 0), `prompt_tokens` includes cached tokens, and
+  `context_window_tokens` is there only when the payload reported a window itself (llama.cpp's `/completion`
+  doesn't: the client uses `generation_started`'s). Unknown provider fields never cross; a field is added here
+  when a client needs it, never as a catch-all bag. Details: [internals/context-telemetry.md](internals/context-telemetry.md).
 - `POST /session/:id/turn` — fire-and-forget turn creation; returns `202` with an `enqueued_id`
   (delivery is at-least-once via the worker's file-IPC input path — it never calls `run_turn`
   across the HTTP boundary). Only the bridge's own session: another id, in the path or the body's
@@ -270,8 +293,11 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   arrives as `:recap_ready`. Answers mid-turn too.
 - `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
   answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
-  (`chi answer`, a parent agent) an allow on an approval beyond the worker's
-  `guardrails.parent_approvals` is `403 parent_approval_refused`, the question still open.
+  (`chi answer`, a parent agent) the answer is checked by `Guardrails::ParentPolicy` in
+  `QuestionDesk#answer`: the question carries each option's effect (`effects`, set by its asker:
+  `Approval.payload`, `ContinueOffer`, `Relay.card`; derived for an untagged one) and `user_only`,
+  and an option beyond the worker's `guardrails.parent_answers` is `403 parent_answer_refused`
+  (with its `reason`), the question still open. `chi answer` makes the same check first.
 - `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
   `200`, or `409` when it is no longer pending.
 - `POST /session/:id/tasks/stop` — `{task_id}`: stop a background task as the user
@@ -281,12 +307,21 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   saved messages, or the running turn's accumulator); answers once the
   task is gone: `200 {status, stop_reason, task_id}`, `404 task_not_found`, `409 not_running`.
   The worker names it in its sidecar features (`task_stop`).
+- `POST /session/:id/turn/dequeue` — `{enqueued_id, client_id?}`: take back a queued message
+  (one that waits for the running turn's end: `--queue`, Alt+Enter, `/queue TEXT`, or a message
+  with images) before a turn takes it (web route `POST /api/sessions/:id/turn/:enqueued_id/dequeue`,
+  the × on a queued bubble; `/unqueue` in the attached TUI). Under the event log, like its enqueue:
+  `SessionInbox.take_queued_input` claims the file as the drain does (one rename wins), deletes it,
+  leaves a tombstone (`input/removed/<enqueued_id>`, for `ReplyWait`'s `turn:`), and the Bridge
+  announces `:turn_dequeued`. `200 {status: "removed", enqueued_id, prompt}`, `409 already_started`
+  (a turn took it), `409 not_queued` (a next-step message: a drain may merge it any moment), `404
+  unknown_enqueued_id`. It never wakes the worker. The worker names it in its sidecar features (`unqueue`).
 - `POST /session/:id/relay` — the approval relay, on a delegated child's worker
   (`{action, relay_id, question_id}`): `opened` / `closed` (with a `reason`) set or clear the
   pending question's `relayed_to` mark (`QuestionDesk#annotate`, `:question_relay`); `answered`
   makes the child ask its parent's Bridge for the answer (`RelayVerifier`) and take it only for
   this child and the question pending now. `200`, `409` no longer pending, `403` a parent agent's
-  allow beyond the child's `guardrails.parent_approvals`, `422 relay_unverified` (the question
+  pick beyond the child's own `guardrails.parent_answers` (`parent_answer_refused`), `422 relay_unverified` (the question
   stays open).
 - `POST /session/:id/relay/status` — on a parent's worker, `{relay_id}`: what its `RelayDesk`
   (memory only) holds for that relay (`child_id`, `child_question_id`, `state`, `answer`, `by`);
@@ -360,7 +395,8 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
   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 file ref outside the
   session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
-  session list entry's.
+  session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
+  file ref is dropped rather than shown unchecked.
   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).
@@ -404,7 +440,7 @@ session every 10 s, so a `kill -9` shows within a second. The summary (`Web::Ses
 shared with `/api/sessions` and the session view) carries `owner`, `project_root` and
 `bridge_up` (the sidecar is there *and* the lock is held: the page attaches its stream on it), and
 from that sidecar `worker_version` (the chi the worker runs) and `worker_features`
-(`Bridge::FEATURES`, what a client may ask of it beyond the routes: `restart`, `task_stop`, `reparent`,
+(`Bridge::FEATURES`, what a client may ask of it beyond the routes: `restart`, `task_stop`, `reparent`, `unqueue`,
 `delivery`, a worker that queues a message for after the turn; `SessionManager.deliver_turn` and
 the attached TUI refuse a queue to a worker without it, which would steer; `turn_ids`, a worker whose running
 turn's mark, continue turn and Stop carry the turn's `enqueued_id`, which `chi answer`, `chi send --wait` with no
@@ -437,7 +473,9 @@ both go through `ToolRunner` (events, hooks, veto, output cap) and
 chat `tool_calls`) are built by one table, `Tools::BuiltinCalls`, from the
 parsed `{name, args}` (derived from `TOOL_SCHEMAS`), so a call looks the same to
 hooks and tools whichever model made it. Both loops' `generation_chunk` carries
-`thinking:`, `text:` and `content:` (both): the chat loop's thinking is the
+`thinking:`, `text:`, `content:` and the provider's `payload:` (the Bridge projects it for its
+clients: `text`, `thinking`, `tool_call` and chi's `counts`, no `payload` or `content`; see the
+Bridge's stream above): the chat loop's thinking is the
 server's `reasoning_content`; the raw-prompt loop splits each generation's
 stream with a fresh `ThoughtStreamSplitter` (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped

data/docs/bundle-authoring.md

@@ -0,0 +1,125 @@
+# Writing a bundle
+
+Read this first when someone asks for new chi functionality "as a bundle". It is the short path: the loop, the
+files, what a hook sees, how to test, and what goes wrong. The full references are in this same `docs/` folder:
+[plugins.md](plugins.md) (the `chi.*` API and `ctx`) and [hooks.md](hooks.md) (every event's fields).
+
+## The loop
+
+```
+chi bundle new my-bundle     # ./my-bundle: manifest.yml, plugin.rb, test/my_bundle_test.rb, README.md
+cd my-bundle                 # edit plugin.rb and the test
+chi bundle test              # the tests, on chi's own Ruby and lib (exit status: the tests')
+chi bundle check --fix       # manifest, files, shas (--fix rewrites them), requires_chi, install + load in a sandbox
+chi bundle install .         # into the user's chi; a NEW session loads it (a running one doesn't)
+```
+
+`check` prints one finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, and exits 1 on any
+error. Run it after every edit: an install takes exactly what it checks. It installs into a temp sandbox, not
+the user's config or state, but `check` and `test` run the bundle's plugin and hooks in their own process, as
+written: run them on code you'd install.
+
+## The files
+
+```yaml
+# manifest.yml
+name: my-bundle              # a plain name; chi bundle install takes it from here
+version: 0.1.0
+scope: system
+description: "What it adds, in one line"
+requires_chi: ">= 0.85.0"    # the chi it needs (new writes the running one; check warns when a call needs newer)
+plugin:
+  file: plugin.rb
+  sha256: sha256:<hex>       # `chi bundle check --fix` fills it; never compute it by hand
+# files:                     # memories it installs (top-level *.md); without files: every *.md but README & co.
+#   my_notes.md: sha256:<hex>
+# hooks:                     # hooks/*.rb files (a plugin's chi.on is usually simpler)
+# needs: [gh]                # outside commands it relies on
+```
+
+`plugin.rb` defines `class Plugin` with `register(chi)`; `initialize(settings)` (optional) gets config.yml
+`bundles: my-bundle:` as a Hash with string keys, once, when the plugin loads. A value a session may set
+(`chi --set my-bundle.KEY=V`, listed in the manifest's `session_settings:`) is read from `ctx.settings` at call
+time. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
+
+## What a hook sees
+
+`chi.on(event) { |event, ctx| … }` gets a Hash. The events, in a turn's order: `session_start`, `before_turn`,
+`before_generation`, `generation_progress`, `after_generation`, `before_tool_call`, `after_tool_call`,
+`after_turn`, `session_end` (the fields of each: [hooks.md, Hook Events](hooks.md#hook-events)). A symbol not in
+that list is never fired (`check` warns). The two a bundle wants most, for an `execute`:
+
+```ruby
+# before_tool_call: vote on the call before it runs
+{ type: :before_tool_call, iteration: 1,
+  call: { name: "execute", content: "rm -rf build" }, params: "execute rm -rf build",
+  guardrail: verdict,        # event[:guardrail].deny!("why") / .ask!("why"); ctx.stop_turn denies and stops the turn
+  context: { cwd: "/work", repo_root: nil, branch: nil, session_id: "…", interface: :worker, origin: nil },
+  targets: { command: "rm -rf build", paths: [], cwd: "/work", repo_root: nil, outside_repo: false, git_dirs: [] },
+  blocked: false, block_reason: nil }
+
+# after_tool_call: what it did
+{ type: :after_tool_call, iteration: 1, tool: "execute", status: "error",   # "ok" | "error" | "blocked" | "stopped"
+  call: { name: "execute", content: "make test" }, elapsed_ms: 812,
+  result: "stdout:\nok\n\nstderr:\n1 failed\n\nexit: 1",                    # the tool's own text, never cut
+  output: "[execute]\nstdout:\n…" }                                          # what the model reads: may be cut
+```
+
+Match on `result:`, not `output:`. An execute's result is its `stdout:` and `stderr:` blocks (each left out when
+empty), then `exit: N` (`exit: 0 (no output)` when both were empty); a non-zero exit makes `status:` `"error"`.
+Act through `ctx`: `ctx.notify(text, level: :warn)`, `ctx.steer(text)` (a line the model reads before its next
+step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's own folder),
+`ctx.cwd`, `ctx.log`. In a test, each recorded notice, steer or stop names its hook as `"plugin.rb (bundle
+my-bundle)"`, the plugin's label (a `hooks/x.rb` file's is `"x.rb (bundle my-bundle)"`).
+
+## Testing it
+
+`chi bundle new` writes a Minitest test that passes as written: copy its shape. The kit (`samagotchi/testing`)
+loads the bundle's source through chi's own loaders, in a sandbox (temp HOME, config and state), and records what
+it did at chi's edges:
+
+```ruby
+bundle = load_bundle(BUNDLE, settings: { "greeting" => "hi" })   # in a Samagotchi::Testing::Case test
+bundle.command("/my-bundle chi")                     # → what the command returned
+bundle.fire(:after_tool_call, tool: "execute", status: "error", result: "exit: 1 (no output)", call: { … })
+bundle.tool_call({ name: "execute", content: "rm -rf /" }).deny?   # before_tool_call hooks, through the real gate
+bundle.tool("my_tool", path: "a.txt")                # a chi.tool, as the model calls it
+bundle.notices, bundle.steers, bundle.cards, bundle.stops, bundle.questions   # what it did
+bundle.answer({ selected: "yes" }); bundle.model_answers << "text"           # ask_user / ask_model answers
+bundle.http.stub(:get, "https://api.example/x", json: { ok: true })          # ctx.http, never the network
+bundle.set(cwd: dir, running: false); sandbox.config(hash); sandbox.fake_executable("gh", "echo '{}'")
+bundle.install                                        # installed as chi installs it: warnings, load failures
+```
+
+The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
+experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
+class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.
+
+## Pitfalls
+
+- **Shas.** Every file the manifest names has a sha256 line, and an edit makes it stale: the install then warns
+  of a checksum mismatch, and a line with no sha installs unchecked. `chi bundle check --fix` rewrites them; run it
+  after the last edit.
+- **requires_chi.** Use the chi the user runs (`chi --version`). `check` warns when the plugin calls something
+  newer than the floor (`ctx.http` needs 0.80.0, `ctx.cost` 0.83.0).
+- **trust_level.** Leave it out. `reviewed` / `trusted` are for someone who reviewed the bundle, not its author.
+- **Restart.** A session loads bundles when it starts: after an install or a settings change, the user starts a
+  new session (or `chi sessions restart ID`).
+- **chi's internals.** A bundle may use `chi.*`, `ctx` and the names
+  [plugins.md, Stable for bundles](plugins.md#stable-for-bundles) lists; any other `Samagotchi::` name may change
+  in any release (`check` warns: `boundary`).
+- **Load errors.** A plugin that raises at load is skipped and the session goes on: `check` shows the error at its
+  `plugin.rb:LINE`.
+
+## Verifying it live
+
+After `chi bundle install .`, one real session shows it works with the user's chi:
+
+```
+chi send --new --wait --format json --dir /tmp/try -m "/my-bundle chi"   # the JSON names the session id
+grep plugin_loaded ~/.local/state/samagotchi/samagotchi.log | tail -1    # bundle=my-bundle commands=1 hooks=1
+chi sessions delete --force SESSION_ID                                    # leave no test session behind
+```
+
+(`$XDG_STATE_HOME/samagotchi/samagotchi.log` when `XDG_STATE_HOME` is set.) Then tell the user what it adds,
+how to use it, and that a new session picks it up.

data/docs/cli.md

@@ -19,12 +19,12 @@
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi context <add|push|ls|show|refresh|rm|mute|unmute> …` — attach live external text to sessions (a command chi runs every so often, or text pushed in); the model gets a short note when it changes and reads it with `context_read`; `chi context add <URL>` attaches a GitHub PR with the github-pr bundle (see [Attached context](context.md))
 - `chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one takes it at its next step; `--cut` asks it to cut long thinking for it; `--queue` runs it as a turn of its own after the running one, and `--queue --wait` waits for that turn's own answer); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead (`--new --continues ID|last:ID` the next link of that session's chain, see [Session chains](sessions.md#session-chains)), and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending — to an idle session whose last turn already ended, that ended turn's reply or end comes back; `--wait --turn T ID` with no message waits for exactly turn T, whether running, queued or last ended; `--format json` includes its `turn_id` when known, for waiting again after exit 3 or 4; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
-- `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). An approval can be denied, not allowed, unless `guardrails.parent_approvals: once` (a convention, not a security boundary; see [Guardrails](guardrails.md#approvals-from-a-parent-agent))
+- `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). What a parent may pick follows `guardrails.parent_answers` (`soft`, the default: a deny, a plain answer, Continue and "Allow once"; `standard`: no allow; `hard`: no Continue either), never a wider scope or an allow on chi's own config; a refused pick exits 1 with what to answer instead (a convention, not a security boundary; see [Guardrails](guardrails.md#answers-from-a-parent-agent))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
-- `chi bundle install|upgrade|uninstall|status|diff|list|build|trash` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument
+- `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
 ### First setup
 
@@ -87,6 +87,39 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   A bundle that fails to install makes the exit 1. `--dry-run` says what it
   would install.
 
+### Writing a bundle: new, test, check
+
+The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bundle-authoring.md)):
+
+- `chi bundle new NAME [--dir DIR]` writes `DIR/NAME/` (default `./NAME`; refused when it exists; `NAME` is
+  `a-z` first, then `a-z`, `0-9`, `-`, `_`, as a slash command): `manifest.yml` (a block-form `plugin:` entry with
+  its sha filled, `requires_chi: ">= <this chi>"`), `plugin.rb` (a `/NAME` command and an `after_tool_call` hook),
+  `test/NAME_test.rb` (Minitest on the bundle test kit, passing as written) and `README.md`, then prints the next
+  steps. Exit 1 when it refuses, 2 for usage.
+- `chi bundle test [PATH] [-- ARGS]` runs the bundle's tests on the Ruby and the lib chi runs on, outside any
+  Bundler env: `test/**/*_test.rb` on Minitest (`-r samagotchi/testing/minitest`), or else `spec/` on RSpec with
+  the kit (`--options /dev/null -r samagotchi/testing/rspec`, as `rake bundles:specs`). `ARGS` go to the runner
+  (`-- -n /name/`). Exit status: the tests'; 1 with no tests; 2 for usage, or when minitest / rspec doesn't load on
+  chi's Ruby. The tests run the bundle's code as written, with your environment (the kit sandboxes each
+  test's HOME and XDG dirs, not the process).
+- `chi bundle check [PATH] [--fix] [--set KEY=VALUE]` (PATH defaults to `.`) checks it as an install takes it, one
+  finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, then `ok|failed: N errors, N
+  warnings`. Exit 1 on any error, 0 otherwise, 2 for usage. It installs and loads the bundle in a temp sandbox
+  (HOME, config and state), not in yours, but in chi's own process: the plugin's and hooks' code runs as written,
+  so run it (and `test`) on code you'd install. The codes, in order: `manifest` (a parse error, verbatim; the run
+  stops), `missing-file`, `unlisted` (warn: a file an install leaves out, by `MemoryFiles`' rules, so a README
+  isn't one), `sha` (a stale or placeholder sha, or a plugin / hook / script entry with no sha line; `--fix`
+  rewrites the first two and prints `fixed sha FILE → sha256:…`), `requires-chi` (this chi doesn't satisfy it:
+  error; missing on a bundle with code: warn), `requires-chi-floor` (warn: the plugin calls an API newer than the
+  oldest chi `requires_chi` admits, from `Plugin::Api::SINCE`), `trust` (warn: `trust_level: reviewed|trusted` on a
+  bundle chi doesn't ship), `clash` (warn: a name chi ships, or one installed from elsewhere; the sandboxed install
+  then forces), `install` (each Installer warning, a `needs` one as warn, and each plugin or hook load failure at
+  the source `file:line`; skipped while a placeholder sha is unfilled), `registered` (info: each command, tool,
+  hook with its priority, init, toolkit, tool source and peer source), `hook-event` (warn: a `chi.on` event chi
+  never fires), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed
+  exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
+  `chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
+
 ### Listing the models
 
 `chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and
@@ -607,6 +640,17 @@ REPL alike:
   sent after it still go in at the next step.
   At the open prompt (no turn running) `/cut TEXT` and `/queue TEXT` run TEXT
   as a normal prompt.
+- `/unqueue` (attached terminal) takes back the newest line this terminal
+  queued that hasn't started: `removed: <its first 60 characters>`, and its text
+  goes back into the input to change and send again (not over typed text: then
+  it is in the input history, ↑; not with input from a pipe; its images don't
+  come back), then the one before it on the next `/unqueue`; `(nothing queued: …)` when none waits,
+  `(not removed: it already started)` when its turn won the race, `(not removed:
+  it is already gone)` when another client removed it. Other terminals that
+  showed it say `(a queued message was removed)`; the web drops its bubble. A
+  worker older than it is not asked: `(/unqueue needs a newer worker: …)`. In
+  the plain REPL it answers with a note (its own queue is not touched), and the
+  web's composer points at the × on the bubble.
 - **The web composer** has a row above the text field in a session (always
   there, so the composer never changes height): the keys while idle, and while
   the turn runs the delivery line, where a message sent now goes in (`↳ goes in after this
@@ -616,7 +660,11 @@ REPL alike:
   **Alt+Enter** (Option+Enter) or `queue for after the turn` queues it, like
   `/queue TEXT`, and the bubble is dashed (`after this turn`), below the
   running turn's card with the commands queued for its end, until its turn
-  starts; `cut in now` cuts, like `/cut TEXT` (by click only: it throws the
+  starts; its **×** (`Remove from queue`, once the worker acked it) takes it
+  back before it runs, in every tab (a toast says why when it can't: it
+  already started, it is gone, no live worker), and puts its text back into an
+  empty composer to change and send again (a draft stays: the text is then in
+  the toast; images don't come back); `cut in now` cuts, like `/cut TEXT` (by click only: it throws the
   thinking away). Cut is enabled only while the step has streamed nothing but
   thinking and cutting is on for the model (the line says `cuts at about 0:25
   if you choose cut in now` until the thinking passes `steer_cut_after`, and
@@ -1138,7 +1186,9 @@ Behavior notes:
 - 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'`.
+  answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`
+  (not under `guardrails.parent_answers: hard`: a parent agent's `/continue yes`, sent with `chi send` or typed into a
+  piped `chi --attach`, is held to it as `chi answer --option Continue` is, and refused there).
 - 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 300 a long turn shows check-in cards (at 50, 100, …)
   well before it.

data/docs/configuration.md

@@ -131,7 +131,8 @@ The config reader checks the file's modification time and size whenever a
 setting is read. That makes a changed value available to a live reader; it
 does not reload every object that already holds a snapshot. "Worker start"
 includes a worker respawn. A running turn keeps the settings it already
-resolved.
+resolved. chi tells you when a changed setting applies only after a worker
+or `chi web` restart.
 
 | Key | Applies | Note |
 |---|---|---|
@@ -144,6 +145,7 @@ resolved.
 | `models.<key>.profile` | Session start or `/model` | It is resolved when that model is selected; editing it does not switch the current model's profile by itself. |
 | Other `models.<key>.*` settings | Next turn or model lookup | Sampling, thinking, vision, context, window, price and steer settings are resolved from the file for their next use. |
 | `thinking.level` | Next turn start | A session's own `/thinking` level is saved in that session and takes precedence; a running turn keeps its level. |
+| `turn.max_iterations` | Next turn start | The configured step limit is resolved when each turn begins. |
 | `cache.*` | Next request or turn-end warm-up | Cache key and TTL are read for a request; warm-up is checked after a turn. |
 | `retry.max`, `retry.base_delay`, `retry.max_delay` | Worker start | The client's network retry policy is built with its HTTP client. |
 | `retry.empty_answer` | Next empty-answer retry | It is checked when a turn needs to retry an empty answer. |
@@ -154,12 +156,12 @@ resolved.
 | `thinking.turn_preamble`, `skip_agents_md` | Prompt rebuild | A running engine caches its built prompt; a new worker or `/model` rebuild uses the changed value. |
 | `context.*` except `context.every_seconds`, `llm_context.*` except `llm_context.policy`, `steer.cut_after`, `memory.index_warn_tokens`, `status.line` | Next matching turn, display, poll or write | Readers resolve these settings when they perform that operation. Session-specific LLM context and thinking values remain saved in the session. |
 | `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
-| `guardrails.*` | Next tool call or approval | Guardrail rules and disable lists are reloaded when the config file changes; rule settings take effect on that evaluation. |
+| `guardrails.*` | Next tool call or approval | Guardrail rules and disable lists are reloaded when the config file changes; rule settings take effect on that evaluation. `guardrails.parent_answers` is checked when a parent answers a question. |
 | `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
 | `recap.*` | Worker start | The engine builds its recap job once. |
 | `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
 | `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
-| `session.retention_*` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. |
+| `session.retention_*`, `session.max_count`, `session.keep_status`, `session.sweep_interval_hours` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. The sweep interval is checked on the next hub tick. |
 | `web.*` | `chi web` start | Restart `chi web` to change its bind address, port or page settings. |
 | `log.*` | Process start | Each process holds its configured log sink and level after first use; restart that process. |
 | `history.file` | Next history access | The TUI and web composer resolve its path when they read or append history. |
@@ -1145,6 +1147,8 @@ Bridge acks `delivery: "queue"` while a turn runs (to an idle session the messag
 `next_step`). A worker whose sidecar doesn't name the `delivery` feature (older than queueing) would steer it, so the
 sender refuses it (`409 delivery_unavailable`, "restart it"), and so does a worker that answers the request with a
 400 `delivery_unavailable`.
+Until its turn starts, a queued message can be taken back: `/unqueue` in an attached terminal, the × on its bubble
+in the web ([sessions.md](sessions.md), *Removing a queued message*).
 
 ## Server errors
 
@@ -1629,7 +1633,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `guardrails.enabled` | `true` | | `false`: no rules, and hooks' asks are dropped (a deny still applies). config.yml only: a worker unsets any `SAMAGOTCHI_GUARDRAILS_*` it inherits. See [Guardrails](guardrails.md). |
 | `guardrails.mode` | `auto` | | Which rules vote: `auto` leaves out the rules tagged `modes: [strict]` (in the guardrails bundle: `git rebase`, writes and git outside the session's repo); `strict` runs them all. An unknown value warns and is `auto`. config.yml only. See [Guardrails](guardrails.md#modes). |
 | `guardrails.small_models` | `auto` | | Which models get the `models: small` rules: `auto` (32B or less by the size in the name, an MoE's active size), a list of globs, or `[]`. config.yml only. See [Guardrails](guardrails.md#rules-for-some-models). |
-| `guardrails.parent_approvals` | `off` | | What `chi answer` lets a parent agent allow on an approval: `off` (deny only) or `once` ("Allow once", never a wider scope). config.yml only: no environment variable (a parent can still pick the config dir with `XDG_CONFIG_HOME`). A convention for an honest parent, not a security boundary. See [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
+| `guardrails.parent_answers` | `soft` | | Which options a parent agent (`chi answer`) may pick on a session's question, by their effect: `hard` (a deny, a Stop, a plain answer), `standard` (+ Continue and other spending options), `soft` (+ "Allow once"); never a wider scope or an allow on chi's own config. An invalid value warns and is `hard`. Replaces `guardrails.parent_approvals` and `turn.parent_continue`. config.yml only: no environment variable (a parent can still pick the config dir with `XDG_CONFIG_HOME`). A convention for an honest parent, not a security boundary. See [Guardrails](guardrails.md#answers-from-a-parent-agent). |
 | `log.file` | state dir | yes | See "Debug Log File". |
 | `log.disable` | `false` | yes | No file logging. |
 | `log.level` | `info` | yes | `debug`, `info`, `warn`, `error`. |
@@ -1673,7 +1677,6 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `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` | `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`). |
 | `update.desktop` | `true` | | `false`: `chi update` leaves the desktop helper alone (`--no-desktop`). |