samagotchi 0.121.0 → 0.122.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78051f4f253f400d0b791fe2694f0dc3d07a19e7d1268ef30557ff3a780d8d64
-  data.tar.gz: c0bf5fbba8c530df5bf56a3947addddc0a9952a39f2077ddd5f59129683ba8f6
+  metadata.gz: 9ba0370c70db9c98a500766ef59cd8cedbf574852c60625679ed84c6a78d50d0
+  data.tar.gz: 937ffbf1066bc4acd34aaaf0ac19680c5099191f0bc87b8681863b362a280940
 SHA512:
-  metadata.gz: c438bac307263d1a56cd9a97b56a2c3ab7175d9be0944c4e327fb92a57c9fdd9ffb82bdac8ec7048ac780a4a9e5f3545a3186dfcb3fec7842e687e2d47099307
-  data.tar.gz: 2738c2cc9f4f81f34c3c88f02568066dced57578a88ac6d1e301ca62508a3e343179a97a7d6ef9d6778f463a00648d2aa0f0b1aded820e8bce7442b2601a0d8a
+  metadata.gz: c351af56a92b5df2cfabbd2d8a52ffefd76b1d7be74a92ffacd25f035d5ab6951214aa083a4d016beefd924cf2794d802c91ddf9ca4b437c860716f99e13ea76
+  data.tar.gz: f00a99184817060ca6d8741bee006bbdcacc3438896a48801a49e6694f4cb2c41868cbabca6f7cd27f807a475f752bf1a62acc580104159036dc033f7611965c

data/CHANGELOG.md

@@ -7,6 +7,113 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.122.0] - 2026-10-27
+
+### Added
+
+- Toolkit kits accept an optional `description:` (config `toolkit.kits` and `chi.toolkit`): what the kit is for, read
+  by the toolkit suggestion, never sent in a prompt.
+- A memory named `toolkit_<name>` defines a kit (one YAML block with `base`, `add`, `remove`, `groups` and a required
+  `description`); project memories win over system ones, config and bundle kits over both, and `/toolkit` shows the
+  source. chi's memory guide says when to write one.
+- Toolkit suggestion audit (`toolkit.suggest.mode: audit`, off by default): System 1 is asked which described kit fits
+  a new session's first prompt, in the background, without changing the session or delaying its turn; `chi toolkit
+  report` grades the suggestions against the tools each session then used.
+
+### Fixed
+
+- `chi sessions restart` on a stopped (SIGSTOPped, Ctrl-Z) worker refuses at once with its pid and `kill -CONT PID`,
+  instead of ~70 s of silence before "didn't take the restart".
+- `chi --remote NAME sessions restart` refusals keep their reasons (what the worker still has running) and name the
+  remote `chi --remote NAME sessions stop` command.
+- chi web's stream, and a remote terminal, say a running worker "didn't answer" instead of "no live worker".
+- The model's hint about a same-named project's memory folder asks the user first instead of offering an `mv`.
+- A participant's wait answers revoked (401) when their grant disappears mid-wait, not "chi web is stopping".
+- A bad `web.start_dir` says it came from config.yml (not `--start-dir`), and a relative one resolves from home.
+- A remote `chi note` whose reply has no status is a clear refusal instead of a crash.
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`).
+
+## [0.121.1] - 2026-10-27
+
+### Fixed
+
+- `chi sessions restart` can recover an unreachable, secret-refusing, newer-protocol or stuck-start worker without a
+  stop marker, but refuses when disk shows a running turn, pending question, queued input or running background task.
+- chi web now opens a session stream before answering: a missing, leaving or unreachable worker gets 503, a Bridge
+  refusal gets 502 instead of an empty 200 or SSE frame, and the opened socket closes when the stream ends. Remote
+  stream retries distinguish 503 from a 502 `bridge_secret`, and `/stats` reports secret refusals consistently.
+- A plugin's `ctx.sessions.fork` reports a child chi won't start as `Samagotchi::Plugin::Sessions::Error` with chi's
+  own reason (the session's model is gone from the config, or its toolkit is a `toolkit.kits` kit with an invalid
+  `groups:`) instead of handing the bundle the raw `Toolkit::Refused` or `ModelProfile::MissingModel`.
+- A `toolkit.kits` kit whose `groups:` isn't a name or a list (a map such as `{chrome: true}`) no longer loads
+  silently with its base's groups: chi, `chi send --new`, chi web and `delegate` refuse a new session on it, naming
+  the kit and the reason, and a session already saved on it reaches no tool-index group until config.yml is fixed.
+- A worker's liveness is one rule everywhere, the owner lock plus the sidecar's pid, with no port probe: after a
+  `kill -9` whose port another session's Bridge took, `chi send`, `--attach` and chi web no longer take the dead
+  worker for live (they wake a new one). A worker on a newer sidecar protocol is not driven by an older chi: a wake
+  answers 409 `worker_newer`.
+- System 1 no longer auto-allows a command that changes chi's own config through a spelling its check missed
+  (`$XDG_CONFIG_HOME/samagotchi/config.yml`, `$HOME/.config/…`, `memories/../config.yml`, `cd ~/.config && …`): it
+  refuses by the same test that makes an ask the user's alone, so such a call goes to the user. Memory files still
+  can be auto-allowed.
+- `chi guardrails replay` no longer judges an ask again that System 1 already judged live (audit or on mode), which
+  counted each such decision twice and let a rule pass `min_record` early: a live label now carries the card's
+  `question_id`, and a live line without one is matched by its session and call digest.
+- Stopping a turn while System 1 judges one of its approvals no longer opens an approval card for the stopped turn
+  (nor logs the cancel as a failed judgment): the call is denied with "The turn was stopped".
+- A participant no longer reads a one-time link code (`chc_…`, as in an invite link a reply quotes) or a Bridge's
+  `X-Chi-Bridge` secret: both are redacted like `chp_` tokens.
+- An agent participant's `chi --remote … send --wait` goes on after chi web restarts: chi web reads whose turn it is
+  from the claimed input file, the last turn or the refused turn's record, not only its memory (it answered 403).
+- chi web's participants routes (list, invite, revoke, cap) answer a grants store chi can't write (unreadable, or a
+  newer chi's) with 409 `grants_unwritable` and the store's own message, not a 500 with a backtrace on every refresh.
+- A participant name or an annotate preset holding `\&`, `` \` `` or `\'` no longer breaks chi web's page: it was read
+  as a backreference when the page's attributes went in.
+- One push subscription with a `p256dh` key off the P-256 curve no longer stops every push: chi web refuses such a
+  subscribe (400 `invalid_subscription`), and one already on disk fails that device alone, so the other devices still
+  get the push, `POST /api/push/test` answers that device as failed instead of a 500, and `chi web push test` prints
+  its failure instead of a backtrace.
+- The notifications sheet's switches always show what chi web has: "this device" no longer stays on after iOS's
+  Don't Allow, nor "Long turns done" moved after its change failed.
+- Turning push off on a flaky connection no longer drops this phone's subscription while chi web keeps the device:
+  chi web is told first, and a failure leaves the bell on with the error. The Home Screen app whose first `GET
+  /api/push` failed (chi web restarting, a phone just woken) tries again when it comes back to the front instead of
+  staying in tab mode until a reload.
+- `chi --help` lists `chi guardrails replay` (seeding System 1's record), the one subcommand it left out.
+- The participants panel's Cap form no longer sets a $0 cap when its field is cleared, nor sends a negative or
+  over-$1000 one: it refuses as the Invite's cap field does ("A cap is dollars, 0 to 1000.").
+- A double tap on the web's Stop no longer asks twice (two confirms, or two stops): a second Stop of the same session
+  while the first one asks the worker what still runs, or stops it, does nothing.
+- A participant's comment box keeps what they typed while their last comment was on its way (it was cleared when the
+  comment was accepted), and an error under the box (a refusal, "Images can't go in a review comment yet") goes at
+  their next edit or send instead of staying until a comment went through.
+- An invite whose participants panel closed before chi web answered no longer loses its one-time link (the grant was
+  made, so the owner had to revoke and invite again): a sticky toast names it with Copy link.
+- A participant's thread no longer jumps when a read fails and again when it recovers: "Can't reach the session —
+  retrying…" (and "This session is gone.") shows over the thread's top instead of as a new row in the header.
+- A participant's wait on a turn whose worker died in it is no longer refused (403) after chi web restarts: the turn's
+  canceled (`worker_stopped`) record keeps whose turn it was.
+- claude-peer (0.4.5): `pair` run as `bash pair` or by zsh no longer refuses every call with its usage (only `sh
+  pair` kept the id and the `--inbox-socket` path), and a carriage return or another control character in what it
+  pushes (the cwd) is escaped, so chi's JSON read no longer refuses the push.
+- codex-peer (0.3.4): a carriage return or another control character in what `pair` pushes (the cwd) is escaped, as
+  claude-peer's is, so chi's JSON read no longer refuses the push.
+- A toolkit's `groups:` match source groups in any case and with `{a,b}` braces, as the guardrails rules' `models:`
+  do (`groups: [Chrome]` missed `chrome`), and a config kit's `groups:` that isn't a name or a list (a map) is refused
+  with a line, the kit loading without it, instead of matching its stringified pairs.
+- A plugin's `chi.toolkit(groups:)` that isn't a name, a list or `:all` (a map) is a load error ("toolkit NAME: groups
+  must be a list of group names or globs"), as a config kit's is refused, instead of matching its stringified pairs.
+- `chi bundle check`'s `requires-chi-floor` sees a keyword added later: `chi.toolkit(prompt:)` (0.72.0),
+  `chi.toolkit(groups:)` (0.121.0), `ctx.ask_model(model:)` (0.80.0) and `ctx.sessions.send(delivery:)` (0.64.0).
+- A remote `chi share` (or `share ls`/`cap`/`revoke`) whose chi web can't read its grants store prints the store's own
+  line, as a local one does, instead of "… answered 409 grants_unwritable: …".
+- `chi web push test`'s line for a push that failed before the push service answered reads "failed (12 ms)", not
+  "failed  (12 ms)".
+
+Update with `chi update` (claude-peer 0.4.5, codex-peer 0.3.4, github-pr 0.5.1), then restart `chi web` and
+`chi sessions restart` the running sessions.
+
 ## [0.121.0] - 2026-10-26
 
 ### Added
@@ -4551,7 +4658,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.121.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.122.0...HEAD
+[0.122.0]: https://github.com/dm1try/samagotchi/compare/v0.121.1...v0.122.0
+[0.121.1]: https://github.com/dm1try/samagotchi/compare/v0.121.0...v0.121.1
 [0.121.0]: https://github.com/dm1try/samagotchi/compare/v0.120.0...v0.121.0
 [0.120.0]: https://github.com/dm1try/samagotchi/compare/v0.119.0...v0.120.0
 [0.119.0]: https://github.com/dm1try/samagotchi/compare/v0.118.0...v0.119.0

data/bin/chi

@@ -70,6 +70,8 @@ SUBCOMMANDS = {
   "bundle" => ["samagotchi/bundle_command", "BundleCommand"],
   # the System 1 record: replay the asks this machine's sessions already answered
   "guardrails" => ["samagotchi/guardrails_command", "GuardrailsCommand"],
+  # audit suggestions for which toolkit fits a session's first prompt
+  "toolkit" => ["samagotchi/toolkit_report_command", "ToolkitReportCommand"],
   # other machines' chi web, for chi --remote NAME (add, ls, rm)
   "remote" => ["samagotchi/remote_command", "RemoteCommand"]
 }.freeze
@@ -230,7 +232,8 @@ if options[:web]
                                       working_set: Samagotchi::Config.get("web.working_set"),
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
                                       editor: Samagotchi::Config.get("web.editor"),
-                                      start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"))
+                                      start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"),
+                                      start_dir_from: options[:start_dir] ? :flag : :config)
 end
 
 # --resume and --attach take a unique id prefix too, like git.
@@ -391,7 +394,7 @@ if launch == :attached
                                                        toolkit_flags: options[:toolkit_flags] || [],
                                                        settings: options[:settings],
                                                        parent_answers: options[:parent_answers])
-  rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
+  rescue Samagotchi::TerminalUI::AttachLauncher::Error, Samagotchi::Toolkit::Refused => e
     warn "Error: #{e.message}"
     exit 1
   rescue Interrupt
@@ -427,7 +430,8 @@ begin
   # limit, or Ctrl-C cancelled it.
   exit 1 if %i[turn_failed empty_answer iteration_limit].include?(ended)
   exit Samagotchi::CLI::Exit::INTERRUPTED if ended == :interrupted
-rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel => e
+rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel,
+       Samagotchi::Toolkit::Refused => e
   warn "Error: #{e.message}"
   exit 1
 rescue Samagotchi::LLM::ProviderError => e

data/docs/architecture.md

@@ -393,14 +393,18 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   worker.
 - **The secret.** Every request, on every route (the stream, the reads such as `state` and `stats`, the writes, and
   an unknown path), names the Bridge's secret in `X-Chi-Bridge`; one without it, or with another one, is
-  `403 bridge_secret` with one message (`BridgeSecret::REFUSED`: restart chi web, re-attach terminals and restart
-  older session workers), after the browser and proxy checks and before any route (`Bridge#secret_ok?`,
+  `403 bridge_secret` with one session-specific message (`BridgeSecret.refused`): "session ID's worker refused
+  this chi's request (it didn't name its secret): a chi web or terminal started before chi was updated can't
+  reach it; restart chi web, re-attach with `chi --attach ID`, or restart the worker with `chi sessions restart
+  ID`." `chi sessions restart` can also recover when the worker cannot be asked: TERM + resume if disk shows no
+  running turn, pending question or approval, queued input, or running background task. The check is after the
+  browser and proxy checks and before any route (`Bridge#secret_ok?`,
   `OpenSSL.secure_compare`). No route is left open: what the reads show is the session itself. Only a request that
   got past it counts as client activity, so a refused one (an older chi web's polls) never holds the idle exit. Each Bridge makes its own (`SecureRandom.hex(32)`, 64 hex
   characters) when it starts and writes it to `bridge.json`, which is 0600 from the moment it exists
   (`AtomicFile` creates the temporary file with that mode, then renames it), so only this machine's user can read
   it: a forward that adds no proxy header, or another local account, reaches the port but not a session. Clients get
-  it only from the sidecar: `BridgeClient.discover`/`.wait_for`/`.for_sidecar` take the port and the secret from the
+  it only from the sidecar: `WorkerLink.client`/`.await` and `BridgeClient.for_sidecar` take the port and the secret from the
   same read (chi web makes its client from the sidecar for every request, the attached terminal again on a
   `worker_changed`), so a respawned worker's new one is used and nothing passes a port by hand. A worker from before
   the secret writes none and asks for none; a chi web or attached terminal from before it sends none, so a worker
@@ -408,7 +412,7 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   (`BridgeClient::Response#secret_refused?`) and shows the one message: chi web's relays answer 502 `bridge_secret`,
   `chi answer` and a parent's approval relay say it instead of "refused", and an event stream ends with reason
   `bridge_secret` once rediscovery finds no newer worker (the attached terminal's closing line), never retrying in
-  silence; chi web's stream proxy passes no refusal on as frames. The secret is never logged (a refusal logs
+  silence; chi web's stream proxy answers 502 `bridge_secret`, never passing the refusal on as frames. The secret is never logged (a refusal logs
   `secret_refused` with the path, at most once a minute), never in an event, a reply, `/api/info` or a session
   file, and `WorkerSidecar`, `BridgeClient` and `Bridge` leave it out of `#inspect`.
 
@@ -491,10 +495,30 @@ Every route goes through `Bridge#dispatch`: an id other than the bridge's own se
 `handler_failed`) rather than dropping the connection.
 
 The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
-for client discovery, with the Bridge's secret (see above). `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
-(503 `not_live` when the worker is not running; full history of any session is served by
-`GET /api/sessions/:id/output`), as a byte pipe for the owner: `App#proxy_stream_body` gives `ProxyStreamBody` the
-request's frame filter (`App#stream_filter`: nil for the owner; for a participant, and the owner's participant view
+for client discovery, with the Bridge's secret (see above).
+
+**Worker link.** Every client asks `WorkerLink` (`worker_link.rb`) whether a session's worker can be reached, never
+reading `bridge.json` or probing a port itself: `WorkerLink.resolve(session_dir, unlink:, owner:)` answers a typed
+outcome. The rule is the owner lock plus the sidecar's `pid`; there is no port probe (a port can be reused by another
+session's Bridge, a free lock is the kernel's proof the worker died). In order: no lock holder, or a chi REPL's: a
+sidecar is `Stale(:lock_free)` (removed with `unlink: true`, only if it is still the file that was read), else `None`;
+a holder with no kind yet: `Starting`; a leaving worker: `Leaving` (marked before its Bridge stops, on every way out:
+`Worker#teardown` marks it too, with `TEARDOWN_LEAVE_WAIT`); a worker whose sidecar names no port or another
+pid than the holder's (a worker that has not written its own yet): `Starting`, `stuck` once it has held the lock
+past `START_LIMIT` (30 s) with none; a sidecar whose `protocol` is newer than `WorkerLink::PROTOCOL`: `Skew` (a
+newer worker; never driven, `wake` answers 409 `worker_newer`); else `Live` (its sidecar; `#client` makes the one
+`BridgeClient`). A sidecar with no `pid` is an older worker's: the lock alone says it is live. `owner:` is the
+holder as the caller already read it (nil: free), so one read serves a summary and its status. `WorkerLink.client` is
+the Live's client or nil; `WorkerLink.await` polls for a new worker's Live (an `until:` check tells a restart's
+successor from the old worker); chi web's `App#worker_link` / `#await_worker_link` wrap them. The Bridge writes
+`pid` and `protocol` with its port and removes its sidecar on stop only when the file still carries its epoch.
+
+`chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
+(503 `not_live` for no worker, a leaving or stuck worker, or an unreachable Bridge; 502 `worker_newer` for skew and
+`bridge_error` / `bridge_secret` for a refused Bridge; 200 only after the Bridge answers; full history of any session
+is served by `GET /api/sessions/:id/output`). It opens the Bridge before answering and gives the one opened socket to
+`App#proxy_stream_body` / `ProxyStreamBody`, which closes it when the body or hijacked client ends. The owner's stream
+is a byte pipe; the body gives it the request's frame filter (`App#stream_filter`: nil for the owner; for a participant, and the owner's participant view
 `?as=participant`, a `Web::ParticipantStreamFilter`, which cuts the Bridge's chunks into frames and writes each again
 from `Web::ParticipantView.event`'s allowlist, dropping every other event; only `from_seq` and `snapshot` reach the
 Bridge; [internals/participants.md](internals/participants.md#what-a-participant-sees)). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
@@ -531,7 +555,7 @@ moved through `Session.summary_from_file`. Liveness is probed, since a killed ow
 file trace: the owner lock every tick for the sessions the projection believes owned, and every
 session every 10 s, so a `kill -9` shows within a second. The summary (`Web::SessionSummary`,
 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
+`bridge_up` (`WorkerLink` answers Live: a worker holds the lock and its sidecar names its pid; 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`, `unqueue`,
 `delivery`, a worker that queues a message for after the turn; `SessionManager.deliver_turn` and
@@ -577,12 +601,12 @@ model: [internals/remote-sessions.md](internals/remote-sessions.md).
 | `GET /api/sessions/:id/worker` | owner | | 200 `{session_id, live, stopped, owner: worker \| tui \| null, worker: {epoch, started_at, version, features} \| null, default_model, parent_strategy}` (`Local#worker`; never starts one; `default_model` is this machine's) | 404 |
 | `POST /api/sessions/:id/exit` | owner | `client_id` (passed on only when it is an attached TUI's, `tui:…`; any other is dropped), `delete` | 200 the worker's `{status: exiting, session_id, discard}` (`BridgeClient#request_exit`; never wakes one) | 409 `held` with the worker's `{status, reason, tasks, hint}`; 503 `not_live`; 501 `not_supported`; 504 `worker_timeout` |
 | `POST /api/sessions/:id/recap` | owner | | 200 the worker's `{enabled, saved, request, min_user_turns, session_off}` (`BridgeClient#request_recap`) | 503, 501, 504 as every relay |
-| `GET /api/sessions/:id/stats` | owner | | 200 `{session_id, metrics}`: the worker's stats, its state's metrics for a worker from before the stats route | 503 `not_live`; 504 `worker_timeout`; 502 `bridge_error` |
+| `GET /api/sessions/:id/stats` | owner | | 200 `{session_id, metrics}`: the worker's stats, its state's metrics for a worker from before the stats route | 503 `not_live`; 504 `worker_timeout`; 502 `bridge_secret` or `bridge_error` |
 | `GET /api/sessions/:id/children/counts` | owner | | 200 `{running, waiting, unreported}` (`ChildrenStatus.counts`, the delegates' files here) | 404 |
 | `GET /api/sessions/:id/turns/:turn_id/records` | owner | | 200 `{tool_records: […], turn_record: {…} \| null}` (`SessionMetrics.saved_tool_records` / `saved_turn_record`, as saved) | 400 `invalid_turn_id`; 404 |
 | `POST /api/sessions/:id/turn` (`no_interrupt`) | owner | `no_interrupt: true`: the turn runs with the raised iteration limit (`SessionManager.deliver_turn(no_interrupt:)`, to the Bridge or the input file) | as before | |
 | `POST /api/sessions/:id/command` (its 501) | owner | | | 501 `not_supported` for a builtin the worker lacks adds `command` (`"/title"`) and `message` |
-| `GET`/`POST`/`DELETE /api/sessions/:id/participants`, `GET`/`DELETE /api/participants` | owner | `chi share`'s (`name`, `kind`, `ttl`; `?id=p_…`) | the grants, never a token but POST's own once ([internals/participants.md](internals/participants.md)) | 400 `invalid_participant`; 404 |
+| `GET`/`POST`/`DELETE /api/sessions/:id/participants`, `GET`/`DELETE /api/participants` | owner | `chi share`'s (`name`, `kind`, `ttl`; `?id=p_…`) | the grants, never a token but POST's own once ([internals/participants.md](internals/participants.md)) | 400 `invalid_participant`; 404; 409 `grants_unwritable` (the store doesn't read: its words, which a remote `chi share` prints as a local one does) |
 | `GET /api/sessions/:id/apply[?turn=T]` | owner | `turn`: a turn id or a prefix (none: the latest review turn with a reply) | 200 `{text, turn_id, author, author_name}` (`ReviewApply`): the owner's Apply of a participant's review turn, for the composer, never sent ([internals/participants.md](internals/participants.md)) | 404 `not_found`; 400 `not_review_turn`; 409 `no_reply` |
 | `POST /api/sessions` (`review`) | owner | `review: {subjects: [project files], from: a session id}`; never with `prompt`, `preview`, `idle` or `continues` (a `from` takes the source's folder and setup) | 201 as a create's: an idle review session (`ReviewStart.start`, or `ReviewStart.fork` with `from`) | 400 `invalid_review` (`ReviewStart::Refused`'s words: a subject, a gone folder); with `from` also 404 `not_found`, 400 `ambiguous_id` |
 
@@ -723,8 +747,10 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Shipped bundles | `bundles/` (`mcp`, `github-pr`, `loop-guard`, `skills`, `source-links`, …) | Bundles that ship with chi. |
 | Hooks | `hooks/registry.rb` (`Hooks::Registry`), `hooks/loader.rb`, `hook_routes.rb` (`HookRoutes`), `event_routes.rb` (`EventRoutes`) | Hook registration and dispatch; what a hook or plugin does beyond reading its event (notice, question, stop, steer) routed to the UIs (cards and notices through one set of routes) ([hooks.md](hooks.md)). |
 | Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/data_readers.rb`, `guardrails/rules.rb`, `guardrails/protected_paths.rb`, `guardrails/parent_policy.rb` + `guardrails/parent_approvals.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing (and the commands that only read a heredoc as data), YAML rules, the core checks on chi's own files, approvals, what a parent agent may answer (`guardrails.parent_answers`) ([guardrails.md](guardrails.md)). |
+| System 1 | `system_one.rb`, `system_one/` (`SystemOne::Client`, `ApprovalQuestion`, `Log`, `Record`, `SelfProtect`, `Similar`, the backends), `guardrail_wiring.rb` (`GuardrailWiring#request_approval`), `guardrails_command.rb` (`chi guardrails replay`) | The approval judge: a model's `p` for each ask, logged to `judgments.jsonl` with the user's answer; in `on` mode an ask on a listed rule with a clean record is allowed once without the user. Labelled by `/guardrails wrong` (`SessionCommands`) and the web's **should have asked** (the Bridge's `POST guardrails/wrong`) ([guardrails.md](guardrails.md#system-1-experimental)). |
 | Delegation | `tools/delegate.rb`, `tools/delegate_result.rb`, `tools/delegate_wait.rb`, `child_reports.rb`, `tools/delegate_relay.rb`, `relay_desk.rb`, `relay_verifier.rb`, `relay_watcher.rb` | Child sessions a session starts and waits on, and their approval relay ([sessions.md](sessions.md#delegating)). |
 | send / broadcast | `send_command.rb` (`SendCommand`), `broadcast_command.rb` (`BroadcastCommand`), `broadcast/` | `chi send` and `chi broadcast` ([broadcast.md](broadcast.md), [sub-agent.md](sub-agent.md)). |
+| Worker link | `worker_link.rb` (`WorkerLink`: `Live`, `Starting`, `Leaving`, `Skew`, `Stale`, `None`), `worker_sidecar.rb` (`WorkerSidecar`) | Whether a session's worker can be reached and the client for it: every Bridge client asks `WorkerLink.resolve` / `.client` / `.await` (*Worker link* above); `WorkerSidecar` is the `bridge.json` it reads. |
 | Session access | `session_access.rb` (`SessionAccess`: `NewSession`, `SetupWords`, `WaitStart`, `SessionView`, `Created`, `ContextEntry`, `ContextPush`, the errors `RemoteFailed`, `RemoteTooOld`, `Refused`, `BadRequest`), `session_access/local.rb` (`SessionAccess::Local`), `session_access/remote.rb` (`SessionAccess::Remote`), `session_access/http_transport.rb`, `session_access/web_bridge_client.rb` (`SessionAccess::WebBridgeClient`, a remote attach's worker through chi web), `session_access/dispatch.rb` (`SessionAccess::Dispatch`), `session_access/contract.rb` (`SessionAccess::Contract`), `remotes.rb` (`Remotes`), `remote_command.rb` (`chi remote`), `web/session_access_routes.rb` (`Web::SessionAccessRoutes`) | The seam between the session commands and where the sessions live: `Local` is this machine's (the `SessionManager`, `ReplyWait`, `NoteDelivery`, `ContextSources` and Bridge calls the commands made); `Remote` is another machine's, the same methods as requests to its chi web's routes of the same name (Bearer token, `HTTPTransport`), results as Local's value objects and refusals as the classes Local's callees raise, built from the fields chi web sends; waits and prefixes run on the server, a wait asked again per 30 s slice. `Dispatch` is bin/chi's front for `--remote NAME` / `CHI_REMOTE` (taken off before the subcommand lookup): it refuses what the contract table lists `local_only` (exit 2, one message) and runs the command with a `Remote` on the `Remotes` entry (`$XDG_CONFIG_HOME/samagotchi/remotes.yml`, 0600). chi web's routes answer from `Local` (*chi web's routes for the session commands* above). Checks that read this machine's config or files (vision, parent answers, the cwd's project, `SAMAGOTCHI_PARENT_SESSION`) stay in the commands and are skipped under a `Remote`, where chi web's create, turn and wait routes run the vision, parent-answers and busy checks with the server's config and the worker checks a parent's answer. See [internals/remote-sessions.md](internals/remote-sessions.md). |
 | Idle work | `idle_scheduler.rb` (`IdleScheduler`), `idle_recap.rb` (`IdleRecap`), `idle_reminders.rb` | One poller for an idle session's recap and reminders. |
 | Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |

data/docs/bundle-authoring.md

@@ -130,7 +130,8 @@ class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather
   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, `ctx.usage` 0.100.0, `ctx.sessions.children` 0.34.0). A keyword added
-  later it can't see: `ctx.ask_model(model:)` needs 0.80.0, `ctx.sessions.send(delivery:)` 0.64.0.
+  later counts too (`ctx.ask_model(model:)` 0.80.0, `ctx.sessions.send(delivery:)` 0.64.0, `chi.toolkit(prompt:)`
+  0.72.0, `chi.toolkit(groups:)` 0.121.0), when the call is written on `ctx` / `chi` itself (not through a variable).
 - **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`).

data/docs/cli.md

@@ -38,6 +38,7 @@
 - `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)
 
 - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
+- `chi toolkit report [--days N]` — grade toolkit suggestion audits: the kit on mode would have run (the suggested kit when it would have applied it, else the default) against the tools the session called from that turn on (only that turn when the toolkit was chosen since), `call_tool` targets included, for both the chat and the raw-prompt loop. Each is *covers*, *short of a tool* (naming the tools), *wider than needed* (a narrower kit offered in the same ask would also have covered) or *ungradable* (calls it can't read back); then a per-kit tally with what on mode would have done. Includes archived sessions and caps the report at 14 days and 500 sessions. Reads `toolkit_suggestions.jsonl` (each ask logs every offered kit's rules, expanded against the called tools here); it never runs the model or changes a session. Local only; `--days` must be a positive whole number.
 
 - `chi bundle try PATH -p TEXT [options]` — install a bundle in a temporary, filtered sandbox, run one real model turn,
   and print its trace (see [Trying a bundle](#trying-a-bundle)).
@@ -518,10 +519,16 @@ chi installed, without stopping it: an attached terminal and the web's tabs
 move to the new worker. It is refused, with the reason, while something would
 be lost: a turn running or queued, a question or approval waiting, reminders,
 a `/btw` still running, an approval relayed from a delegate, or background
-tasks the session started. A session with no running worker needs none (its
-next prompt starts one on the newest chi), and a worker from before restarts
-needs `chi sessions stop ID`. The Web UI's `POST /api/sessions/:id/restart`
-does the same (409 with `reason` and `detail` when it can't). An attached
+tasks the session started. If the worker cannot be asked (a refused Bridge,
+protocol mismatch or stuck start), chi sends it TERM and resumes only when
+disk shows no running turn, pending question or approval, queued prompt, or
+running background task; otherwise it says to run `chi sessions stop ID`, then
+send any prompt. That fallback may lose reminders, a running `/btw`, and other
+in-memory state. A session with no running worker needs no restart (its next
+prompt starts one on the newest chi), and an older worker without restart
+support needs `chi sessions stop ID`. The Web UI's
+`POST /api/sessions/:id/restart` does the same (409 with `reason` and `detail`
+when it can't). An attached
 terminal says at the join, in one `chi>` line, when the worker or the terminal
 runs an older chi than the newest installed (the worker moves with `chi
 sessions restart ID`, the terminal with `/detach` and `chi --attach ID`), and

data/docs/configuration.md

@@ -163,6 +163,7 @@ or `chi web` restart.
 | `append_system_prompt` | Worker start for the file list | The config list is not saved in the session file. File text is read when the prompt is built; `/model` rebuilds it, while an already-built prompt is cached. CLI `--append-system-prompt` files are saved in the session. |
 | `toolkit.default`, `toolkit.child` | Session creation | The chosen toolkit is saved; changing the defaults does not move existing sessions. |
 | `toolkit.kits`, `execute.description`, `llm_context.policy` | Worker start | These are held by the engine's toolkit or tool registry. |
+| `toolkit.suggest.mode`, `toolkit.suggest.threshold`, `toolkit.suggest.defer_turns`, `toolkit.suggest.defer_tokens` | Worker start | Suggestion settings are config-only and are resolved when the worker runs its audit. |
 | `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`, `web.participants.*` | 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. A participant's grant keeps the expiry and cap it was issued with; `web.participants.*` is what the next invite gets, and the cap and queue of a grant from before caps. |
 | `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
@@ -1398,7 +1399,7 @@ toolkit:
   default: lean        # the sessions you start (unset: full)
   child: child         # delegate children (unset: full)
   kits:                # your own, on a base
-    audit: { base: lean, add: [web_fetch, delegate], remove: [memory_write] }
+    audit: { base: lean, add: [web_fetch, delegate], remove: [memory_write], description: "Code review and inspection" }
     terse: { base: lean, prompt: "- Be concise in your responses" }
     web: { base: lean, groups: [chrome] }
     coding: { base: lean, groups: [] }
@@ -1414,12 +1415,36 @@ toolkit:
 | `review` | `read`, `memory_read` (not `forget_outputs`, even under the `forget` layer): what a [participant's](internals/participants.md#turns) turn may call, whatever the session declares (the review boundary, [guardrails](guardrails.md#a-participants-review-boundary)). Reserved: `toolkit.kits.review` is refused ("review is reserved for participants' turns"), and a bundle can't declare it. A session may run on it too, as any kit |
 
 - **Plugin tools** are declared in every toolkit unless its `remove:` names them, and so is `forget_outputs` under
-  the `forget` layer. A `kits:` entry takes `base:` (default `full`), `add:`, `remove:`, `prompt:` and `groups:`
+  the `forget` layer. A `kits:` entry takes `base:` (default `full`), `add:`, `remove:`, `prompt:`, `groups:` and
+  `description:`
   (any other key, a typo or a `tools:` list, is ignored with a warning); it can't reuse a built-in's name
   (`review`'s least of all: it is the participants' boundary). A bundle declares its own with `chi.toolkit`
-  ([plugins](plugins.md#chitoolkitname-base-add--remove--prompt-nil-groups-nil)).
-- **Tool-index groups.** `groups:` selects source groups by name or glob (`chrome`, `db*`); for the MCP bundle
-  each group is a server. Selectors are sorted and deduplicated and match the groups declared when plugins load.
+  ([plugins](plugins.md#chitoolkitname-base-add--remove--prompt-nil-groups-nil-description-nil)).
+  `description:` is optional classifier input, up to 300 characters; it is not included in the session prompt.
+- **Memory kits.** A memory named `toolkit_<name>.md` defines kit `<name>` with one fenced YAML block containing
+  optional `base:`, `add:`, `remove:` and `groups:`, plus a required `description:` (up to 300 characters).
+  `prompt:` is refused. A memory kit may use a config or bundle kit as its base. Built-ins cannot be redefined.
+  The precedence is built-ins, config, bundles, then memory kits; within memories, project scope wins over system
+  scope. Muted memory kits are skipped, and `/toolkit` shows each one's `memory:project` or `memory:system` source.
+  Kits are read once per worker, so changes take effect when a new worker starts. See
+  [Toolkit memories](memory.md#toolkit-memories) for the format and when to create one.
+- **Audit suggestions.** `toolkit.suggest.mode: audit` asks System 1 which described kit fits an eligible new session's
+  prompt, without changing its toolkit or delaying the turn. It offers the configured default as the fallback and
+  `undecided` for greetings or check-ins. Only a default-origin session with at least two described candidates is
+  asked; chosen or inherited toolkits, delegate children, review sessions and participant turns are skipped. After
+  `undecided`, later owner prompts may be asked again within both defer limits. `toolkit.suggest.mode: on` is accepted
+  but behaves exactly like `audit` in this build. The default is `off`. System 1's host, model and timeout come from
+  `guardrails.system_one.*`; the suggestion threshold and defer limits are its own settings below. Suggestions are
+  kept in `toolkit_suggestions.jsonl`; `chi toolkit report` grades them against the session's tool calls. One ask
+  runs at a time (a turn that comes while one still runs goes unasked, with an info line), and a kit that doesn't
+  resolve (a missing base, a cycle) is left out of the candidates. A worker that exits waits about a second for a
+  running ask, so a one-shot `-p --non-interactive` run may end before its suggestion is logged.
+- **Tool-index groups.** `groups:` selects source groups by name or glob (`chrome`, `db*`; any case, `{a,b}` braces,
+  as the guardrails rules' `models:`); for the MCP bundle each group is a server. Anything but a name or a list (a
+  map such as `{chrome: true}`) refuses every new session on that kit or on a kit built on it, on every surface (chi,
+  `chi send --new`, chi web, `delegate`, a continue or a fork): `toolkit.kits.NAME: groups must be a list of group
+  names or globs; fix config.yml to start a session on toolkit KIT`. A session already saved on it keeps running,
+  its kit reaching no group (with a `toolkit>` warning) until config.yml is fixed. Selectors are sorted and deduplicated and match the groups declared when plugins load.
   An omitted key inherits the base's selectors; `full` and `lean` (and `child`, which is on `lean`) reach all
   groups, `review` (the participants' kit) reaches none, `groups: ["*"]` matches every group, and `groups: []`
   reaches none. A kit whose base doesn't resolve (an unknown name, a cycle) falls back to `full`, which reaches
@@ -1947,7 +1972,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `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_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`. A session's own `parent_answers` (`chi --parent-answers`, `/parent-answers`) may only tighten it. 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). |
-| `guardrails.system_one.mode` | `off` | | System 1, the cheap judgment that answers an ask before the user sees it: `off` (the default), `audit` (judge every ask, log it, never decide), `on` (also allowed to allow a call once, behind the gates in [System 1](guardrails.md#system-1)). An unknown value warns and is `off`. Experimental. config.yml only. See [Guardrails](guardrails.md#system-1). |
+| `guardrails.system_one.mode` | `off` | | System 1, the cheap judgment that answers an ask before the user sees it: `off` (the default), `audit` (judge every ask, log it, never decide), `on` (also allowed to allow a call once, behind the gates in [System 1](guardrails.md#system-1-experimental)). An unknown value warns and is `off`. Experimental. config.yml only. See [Guardrails](guardrails.md#system-1-experimental). |
 | `guardrails.system_one.host` | none | | The `hosts:` entry serving `/v1/systemone` (a local Splash, or the hosted Jev API); unset: no judgment. config.yml only. |
 | `guardrails.system_one.model` | none | | The judgment model; unset uses the host's first model, and a host that names none has no judgment. config.yml only. |
 | `guardrails.system_one.rules` | none | | The rule ids System 1 may answer for in `on` mode: `"git-push|git-rebase"` or a YAML list, parsed like `guardrails.small_models`. Nothing is auto-allowed while it is unset; the `chi-answer-piped`, `chi-answer-http` and `chi-broadcast` rules never are, however they are listed. config.yml only. |
@@ -1978,6 +2003,10 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `context.peer_turns` | `3` | yes | Wake turns in a row a peer agent's answers may start (a peer bundle's outbox source, such as `codex-outbox`), with no message typed in the web or a TUI in between (`chi send` doesn't count); within `session.max_wakes`. Then answers wait as notes, and the UIs hear it once. An answer whose summary ends its verdicts with `VERDICT OK` wakes once to close the round, counted toward `session.max_wakes` only. `0`: a peer source wakes like any other. See [Waking](context.md#waking). |
 | `toolkit.default` | `full` | | The toolkit a new session is stored on: the tools its prompts declare (`full`, `lean`, `child`, one of `toolkit.kits` or a bundle's). `chi --toolkit` picks one per session. See "Toolkits". |
 | `toolkit.child` | `full` | | A delegate child's toolkit, unless its `delegate` call names one (`toolkit:`). See "Toolkits". |
+| `toolkit.suggest.mode` | `off` | | `audit` asks System 1 for a toolkit suggestion without changing the session; `on` currently behaves the same as `audit`. The System 1 host, model and timeout come from `guardrails.system_one.*`. config.yml only. |
+| `toolkit.suggest.threshold` | `0.5` | | Minimum confidence for a non-default toolkit suggestion. config.yml only. |
+| `toolkit.suggest.defer_turns` | `3` | | Maximum owner-prompt number for another ask after `undecided` (the owner's own prompts: not steers, notes, reminders or `!` command output). config.yml only. |
+| `toolkit.suggest.defer_tokens` | `5000` | | Maximum estimated conversation size for another ask after `undecided` (characters / 4). config.yml only. |
 | `reasoning_history` | `turn` | | Which of its reasoning a chat host's model gets back: `drop`, `turn`, `all`; environment only (`SAMAGOTCHI_REASONING_HISTORY`), below a session's own level (`/reasoning-history`), above the `models:`/`hosts:` entries. See "Reasoning history". |
 | `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't; a session's own level outranks them all, and `--thinking` sets it on a session run (on `chi web` it sets this). See "Thinking". |
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
@@ -2023,7 +2052,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `web.working_set` | `true` | yes | The stage view's working set: the files, memories and URLs a turn brought into the model's context, in a rail in the stage, a footprint line under each finished turn and a `set N` chip in place of the mem chip; `false` brings the mem chip back. `?working_set=1` or `?working_set=0` on the page URL overrides it for that page load; the turn view ignores it. See [CLI: the working set](cli.md#the-working-set). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
 | `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
-| `web.start_dir` | the folder `chi web` runs in | | The folder `chi web` starts in (`chi web --start-dir DIR` for one run): its page (the printed link, a bare `/`, the LAN link and QR code, the Home Screen app) opens on that folder's project, outside a repo on every session, and a new session from the all view starts there; `/?scope=all` is every project. `~` and a relative path work; one that isn't a folder stops `chi web` from starting. `chi web` never changes its own folder. See [CLI](cli.md). |
+| `web.start_dir` | the folder `chi web` runs in | | The folder `chi web` starts in (`chi web --start-dir DIR` for one run): its page (the printed link, a bare `/`, the LAN link and QR code, the Home Screen app) opens on that folder's project, outside a repo on every session, and a new session from the all view starts there; `/?scope=all` is every project. `~` and a relative path (resolved from your home folder) work; one that isn't a folder stops `chi web` from starting. `chi web` never changes its own folder. See [CLI](cli.md). |
 | `web.participants.expires` | `7d` | | How long a participant's link lasts unless `chi share --expires` says otherwise: `Nh` or `Nd`, 1h to 30d. See [participants](internals/participants.md). |
 | `web.participants.cap` | `2.0` | | What a participant's turns, and the side calls they cause, may cost you in dollars unless `chi share --cap` says otherwise ($0 to $1000); at the cap their next comment is refused (429 `cap_reached`) and you get a notice. `chi share cap ID P DOLLARS` changes one grant's. |
 | `web.participants.queue` | `3` | | How many of a participant's turns may wait behind their running one (0 to 20); one more is refused (429 `too_many_turns`). |

data/docs/guardrails.md

@@ -243,6 +243,16 @@ with its `reason`; `chi answer` exits 1 with the line), checked against the
 question pending at that moment. Answers from the web and an attached
 terminal keep every option.
 
+If `chi answer` reaches a worker that refuses its Bridge secret (`403
+bridge_secret`), it prints a session-specific recovery message rather than
+treating that as a refused answer: `"session ID's worker refused this chi's
+request (it didn't name its secret): a chi web or terminal started before chi
+was updated can't reach it; restart chi web, re-attach with chi --attach ID,
+or restart the worker with chi sessions restart ID"`. `chi sessions restart
+ID` can also recover when the worker cannot be asked, but only if disk shows
+no running turn, pending question or approval, queued prompt, or running
+background task; when one exists, stop it explicitly and then send a prompt.
+
 A parent may also type its answer into chi itself: a piped `chi --attach ID`
 or `printf '2\n' | chi --no-shared -p …`. So chi treats an answer as a
 parent's, held to the same setting, when its input isn't a terminal or an
@@ -656,14 +666,29 @@ a body that isn't JSON, a question with no answer, a request longer than
 `timeout_ms`. A nil means "ask the user", which is what the caller would
 have done anyway.
 
+Toolkit suggestions are a separate audit use of System 1. When
+`toolkit.suggest.mode` is `audit` (or `on`, which is audit-only in this
+build), the engine asks a `choice` question from a background thread after
+the turn starts. This uses the same configured host, model and timeout, but
+is gated by `toolkit.suggest.mode`, not `guardrails.system_one.mode`, and it
+never changes the session's toolkit. Its audit records use the `toolkit` tag
+and are written to `toolkit_suggestions.jsonl` beside the guardrail logs.
+To avoid competing with the session's model, it skips (one info line) when
+the System 1 host is the model's local host: the same `hosts:` name, or
+another entry for the same server root (scheme, host and port). There is no
+reliable single-slot signal, so this host-identity check is the available
+contention guard. The session's own checks come first; the kits and the
+suggestion log are read only for a session that can be asked, the log only
+after an earlier `undecided`.
+
 ### What the audit writes
 
 With a client, `GuardrailWiring#request_approval` asks System 1 one `noul`
 question, `allow`, before the user is asked. Its instruction is a constant
 in code (`SystemOne::ApprovalQuestion::INSTRUCTIONS`), reviewed like a
 prompt; the state is the ask's own facts — the rule and its source, the
-reason, the tool, the command (or the paths) cut to 2000 characters, the
-edit's diff, the cwd, the repo and branch, and the session's title when it
+reason, the tool, the command (or the paths) cut to 2000 characters
+(`ApprovalQuestion::TEXT_CHARS`), the edit's diff, the cwd, the repo and branch, and the session's title when it
 has one. A memory ask also names what it is about: the entry and its scope,
 and for a removal the description that entry's index line carries
 (`Targets#memory`, read into the card by `Guardrails::Approval`): a path
@@ -680,11 +705,13 @@ Each judgment is a line in `judgments.jsonl`, beside `approvals.json` in
 `$XDG_STATE_HOME/samagotchi/guardrails/` (`SystemOne::Log`): 0600, appended
 under an exclusive `flock` (several workers write it), and rewritten —
 keeping the newest half of its lines — once it passes 5 MB. A line is never
-rewritten to add its label:
+rewritten to add its label. Its `call` is shorter than the state's: cut to 300
+characters (`ApprovalQuestion::CALL_CHARS`), with `call_digest` the SHA256 of
+the whole call:
 
 ```json
 {"kind":"judgment","id":"…","at":"…","session_id":"…","rule":"git-push","source":"config","tool":"execute","call":"git push origin main","call_digest":"<sha256 of the whole call>","repo_name":"samagotchi","p":0.97,"threshold":0.8,"model":"Qwen3.8-Flash","latency_ms":180,"decision":"audit","origin":"live"}
-{"kind":"label","id":"…","at":"…","answer":"allow_once"}
+{"kind":"label","id":"…","at":"…","answer":"allow_once","question_id":"…"}
 ```
 
 `decision` is what the judgment led to: `audit` (audit mode), `asked` (on
@@ -692,7 +719,9 @@ mode, the user was asked), `auto` (on mode, System 1 answered for the user).
 A judgment that never arrived is logged too, with `p` null, so the failures
 count as well. The label line, keyed by the judgment's id, is what the user
 did: `allow_once`, `allow_wide` (any scope wider than once), `deny`, or
-`none` for an ask that was cancelled. **A parent agent's answer is not the
+`none` for an ask that was cancelled. A live label carries the card's
+`question_id` when the user answered (the judgment is written before the card
+exists), so a replay knows the ask was judged. **A parent agent's answer is not the
 user's: its allow labels nothing. Its deny is a label only where the parent
 could have allowed instead** — the ask is not `user_only` and the session's
 parent level permits a permit (`Guardrails::ParentPolicy`); a parent that was
@@ -704,6 +733,10 @@ their last label.
 Everything about the log is best-effort: a write that fails is one
 `Log.warn(:guardrails, "system_one_log_failed", …)` and the approval goes on
 as if System 1 were not there.
+A turn stopped while the judge is asked is not a failed judgment: the cancel
+(`LLM::RequestCancelled`) goes through `SystemOne::Client#ask`, no line is
+written, and the call is denied without a card; a turn that stopped as the
+judgment came back opens no card either.
 
 `ruby script/system-one-probe HOST [MODEL]` asks three fixed approval-like
 questions through the client and prints each probability and the latency of
@@ -722,13 +755,18 @@ gate below passes, in this order:
    questions — `chi-answer-piped`, `chi-answer-http`, `chi-broadcast` — which
    are never auto-allowed, even when listed
    (`SystemOne::SelfProtect::NEVER_AUTO`);
-4. the call does not change chi itself (`SystemOne::SelfProtect.refuse?`): no
-   edit or write whose paths include config.yml in chi's config dir, anything
-   under the hooks dir, the installed bundles dir or the guardrails store (where
-   `approvals.json` and `judgments.jsonl` live), and no `execute` or
-   `task_create` command naming any of them — the `~/.config/samagotchi`
-   spelling counts too. The memories dir is deliberately not one of these:
-   reading or appending a memory file can be auto-allowed. A protected rule
+4. the call does not change chi itself (`SystemOne::SelfProtect.refuse?`), by
+   the same test that makes an ask one only the user may answer
+   (`ParentApprovals.chi_files?`): no edit or write whose paths are in chi's
+   config dir (config.yml), the hooks dir, the installed bundles dir, the
+   guardrails store (where `approvals.json` and `judgments.jsonl` live) or the
+   attached context dir, and no `execute` or `task_create` command naming any
+   of them, however it spells them (`ParentApprovals::CHI_TEXT`:
+   `$XDG_CONFIG_HOME/samagotchi/config.yml`, `~/.config/samagotchi/…`, a
+   `cd ~/.config` then `samagotchi/config.yml`). The memories dir is
+   deliberately not one of these: reading or appending a memory file can be
+   auto-allowed, unless the command has a `..` segment (`memories/../config.yml`
+   climbs out of it). A protected rule
    (`Verdict::PROTECTED_RULES`) may be listed by name and System 1 may answer
    it, but a call that really writes config.yml or the hooks is refused here;
 5. the judgment's `p` is at least `guardrails.system_one.threshold` (0.8);
@@ -744,11 +782,14 @@ Then the judgment's `decision` is `auto`, the verdict settles as
 written to `approvals.json` — the next call is judged again. **No question is
 opened, so no card appears, no `:question_asked` hook fires, and no
 notification is sent.** The verdict's activity carries
-`note: "auto-allowed by System 1 (p=0.97)"`, `judgment_id` and `p`; the line
-that shows it in the terminal and the web is P3b, and is not rendered yet, so
-today an auto-allowed call simply looks like a call that never needed
-approval. If the judgment line cannot be written to the log, the ask goes to
-the user.
+`note: "auto-allowed by System 1 (p=0.97)"`, `judgment_id` and `p`, and the
+call's tool row shows it: the terminal's tool line ends in
+`· auto-allowed (System 1, p=0.97)`
+(`TerminalUI::Formatting#format_tool_guardrail_suffix`, live and when
+attaching to a saved turn), and the web's activity row carries
+**auto-allowed · System 1** with `rule …, p=…, allowed once` on hover and the
+owner's **should have asked** button (below). The stage trail shows no mark.
+If the judgment line cannot be written to the log, the ask goes to the user.
 
 A delegate child answers from its own session's settings: its System 1 can
 auto-allow a call even when the child's `parent_answers: hard` bars a parent
@@ -778,8 +819,11 @@ whose `pending_question.approval` is there and that have an `answer` or were
 `cancelled`. A label is the scope the user took — `allow_once` for "Allow once",
 `allow_wide` for a wider one, `deny` for anything else, `none` for a cancelled
 ask. Skipped: a question no one answered, a relay card, which carries no
-approval of its own, and a question id a previous replay already logged — so
-running it twice adds nothing. A parent agent's answer is not the user's: its
+approval of its own, a question id a previous replay already logged — so
+running it twice adds nothing — and an ask already judged live (audit or on
+mode): by the `question_id` its label carries, or, for a live judgment with
+none (a cancelled ask, an older line), by its session and `call_digest`, one
+card per such line. A parent agent's answer is not the user's: its
 allow is skipped, and its deny is replayed only where the parent could have
 allowed (the card is not `user_only` and the session's parent level permits a
 permit). A cards file that doesn't parse is skipped with one warning line,

data/docs/internals/anthropic.md

@@ -130,7 +130,7 @@ gets a 400 `messages.N.content.M: Invalid signature in thinking block. The block
 conversation.`, and its last sentence says what changed ("The `system` prompt differs …"). chi's history is
 append-only within a process, so what changes the prefix is:
 
-1. **A system-prompt rebuild** (`SystemPrompt#build` is cached per process and key; `PromptBuilder#reset!` drops it):
+1. **A system-prompt rebuild** (`SystemPrompt#build` is cached per process and key; `SystemPrompt#reset!` drops it):
    a new process (`--resume`, a respawn after `session.idle_exit_minutes`, a crash) after a memory index line, an
    AGENTS.md, an appended file, a model note or a bundle memory changed; `/model` (the tail's `Model:` line, its
    overlays and notes); `/thinking` (another key); a toolkit or profile change; a plugin's `tools_changed!`; the