samagotchi 0.100.1 → 0.102.0

data/docs/internals/working-set.md

@@ -0,0 +1,205 @@
+# The working set: what the model really has
+
+The stage view's working set (`web.working_set`, [cli.md](../cli.md#the-working-set)) shows the files, memories
+and URLs a session's tool runs brought into the model's context. The page builds the set itself from its tool rows
+(`working_set.js`, phase 1). The server says what the model still has of each item: **live**, **stale** (a file
+changed since the model last saw it) or **forgotten** (nothing of it is still sent), and its size in tokens. This
+page covers the server's side and how the page overlays it.
+
+## Stamps: `tool_stamps`
+
+`ToolRunner#run` stamps an ok `read`, `edit` or `write` (`result[:activity][:status] == "ok"`) with its file right
+after the call: `ToolRun#stamp`, `{path:, mtime_ns:, size:}`. The path is the one `FileRef.for` gives (the call's
+path against the session's folder, `File.expand_path`, no realpath). A stat that fails, or that isn't a file's (a
+directory), gives no stamp; nor does any other tool.
+
+Both `ToolResponse` shapes save the stamps as `tool_stamps`, one per run, read by the run's place
+(`ToolIds::Ref#run`):
+- `ToolResponse.joined` (the native loop's batch entry): `runs.map(&:stamp)`, only when one is non-nil, like
+  `tool_refs`.
+- `ToolResponse.single` (the chat loop's entry for one call): `[stamp]`, a one-stamp array like its `tool_ids`.
+
+`tool_stamps` is in `ToolResponse::SAVED_KEYS`, so `ChatLoop#plain` keeps it and no prompt or wire ever renders it
+(the exclusion specs: `spec/llm/chat_loop_spec.rb` "a file run's stamp", `spec/kernel_loop_spec.rb`). After a
+reload the stamp hashes have string keys; the projection reads both. A session saved before the stamps has none, so
+its files are never stale.
+
+The model's own successful `edit` or `write` stamps the file after it ran, so it never makes the file stale. Anything
+else that changes it does: a later `execute` (`sed`, `git checkout`), the user's editor, another session. A failed
+edit that changed the file anyway leaves the earlier stamp, so the file shows stale. On a filesystem with 1 s mtimes a
+same-size edit in the same second goes unseen (APFS keeps nanoseconds).
+
+## The projection: `WorkingSet.build`
+
+`Samagotchi::WorkingSet.build(conversation, cwd:, strategy:, stat: File.method(:stat))` (`lib/samagotchi/working_set.rb`)
+is pure and returns a `WorkingSet::Snapshot` (`items`, `at`: the conversation's size in entries, the web's ordering
+key). Each `WorkingSet::Item` is `kind` (`file`, `memory`, `url`), `key`, `state` (`live`, `stale`, `forgotten`,
+`dropped`), `tokens`, `ops`, `count` and
+`first_id` (the first run's ToolIds id).
+
+**Runs.** It pairs the runs twice with `LLMContextStale.paired_runs`: once on the stored conversation, once on what
+`LLMContextView.new(strategy:).messages(conversation)` sends (stubs keep their `[name]` lead, so they still pair).
+The two are matched by `ref.id`. The calls are the dispatched ones (`Tools::BuiltinCalls.build`), so aliases resolve
+as the loops resolve them. A run that doesn't pair (a "ran as:" corrected call, an output holding the run separator)
+is left out. So is a failed run (`LLMContextStale`'s rule: an `Error` after the `[name]` lead; a denied call's
+`Error:` too) and an interrupted one (`ToolResponse.interrupted_text?`).
+
+**Items** follow the page's `rowEntries`:
+- `read`, `edit` and `write` give a file, keyed by its `FileRef` path; `read` adds op `read`, `edit` and `write`
+  add op `edit`.
+- `memory_read` gives one memory per name (`Tools::MemoryRead.parse_names`; an empty name, the index listing, gives
+  none). A partial read ("a,b" where b is missing: the found bodies, then `Error: memory not found: b`) keeps the
+  found names only, and its tokens are split evenly among them.
+- `memory_write` gives the memory `call[:path]`, op `write`. A `remove: true` write stays in the set.
+- `web_fetch` gives the URL with its whitespace collapsed.
+
+**Tokens and forgotten.** Only content outputs (`read`, `memory_read`, `web_fetch`) carry tokens and decide
+forgotten. Their tokens are the sent text's length over `TokenUsage::CHARS_PER_TOKEN`, so a stub costs what the stub
+costs and kept lines count themselves. An image read counts its text only. `edit`, `write` and `memory_write`
+outputs are short confirmations whose content sits in the call's arguments, which no strategy cuts: they add ops
+and stamps, never tokens, and they never make an item forgotten.
+
+An item is **forgotten** when it has content outputs and none of them is still sent under the session's *current*
+strategy. A content output is still sent when:
+- its sent text equals the stored one, or the stored one with the forget layer's `[#id] ` after its lead;
+- no applied edit of a layer the strategy runs is saved on it (a staged edit doesn't count; an edit saved under a
+  strategy the session has since left, such as `/llm-context strategy none`, isn't sent, so the output is live
+  again);
+- it is a forget that keeps lines (`forget_outputs keep:`);
+- it is a stale stub an edit made ("superseded by a later edit", `llm_context.stale_edits`): the model wrote the
+  file, so what it has of it is current.
+
+A stale stub of an old read that a newer read superseded never strikes the file: the newer read is still sent. A file
+only edited or written is never forgotten.
+
+**Dropped** is a forgotten item whose content outputs all hold the user's applied `:drop` (the user's layer, sent
+under every strategy: [llm-context-forget.md](llm-context-forget.md)), so it is dropped under any strategy and after
+a switch. An item with one output dropped and another forgotten by the model is forgotten. Under none with no drop
+saved the build doesn't pair the sent conversation at all (the view returns the stored Array).
+
+**Stale** is a file item whose latest run left a stamp, and whose file now differs from that stamp in mtime or size,
+or is gone. No stamp, live. A forgotten item stays forgotten whatever its file did.
+
+**An item's outputs.** `WorkingSet.outputs_of(conversation, kind:, key:, strategy:, cwd:)` answers an item's
+content outputs (`WorkingSet::Output`: `id`, the tool_response entry's `index`, `derived` for a legacy entry's id,
+and `sent`, the rule above) in conversation order. It walks the runs exactly as `build` does (one shared
+`all_touches`), so what acts on an item's outputs and the projection never disagree: an item is forgotten exactly
+when it has outputs and none is `sent`. An edit-only item, a failed run's file or an unknown key has none; a
+`memory_read` of several names is an output of each name.
+
+**Cost.** Two `paired_runs` walks, one view build and one stat per file item. A 500-message session builds in about
+10 ms on an M5 Ultra and 75 ms on a CI runner; `spec/working_set_spec.rb` only guards against a blow-up (< 400 ms).
+
+## Delivery
+
+**The event.** The Engine emits `{type: :working_set_updated, items:, at:}` (`Engine#emit_working_set`):
+- after each `:generation_started`, in `build_stream_event_handler`, from the running turn's conversation
+  (`Engine#live_conversation`, read on the turn's thread) under the turn's strategy
+  (`@kernel.turn_settings.llm_context`). Both loops start a generation after `apply_llm_context!`, so the set is
+  what that request sends;
+- once in `Engine#end_turn`, after `replace_session_messages` and before the end event, from the kept messages (the
+  turn-end apply has run by then);
+- between turns, from `Engine#announce_working_set` (the session's messages, under the event lock; after a
+  `/working-set` op): announced
+  (`working_set_updated` is in `ANNOUNCEABLE_EVENTS`; held after a command's `command_ran` inside
+  `holding_announcements`), under the *next* turn's strategy (`SessionModelSettings#turn_llm_context`, as the
+  turn-end warm-up reads it; `TurnSettings` keeps the last turn's, stale after `/llm-context` or `/model`). While a
+  turn runs, the strategy is always the turn's.
+
+It is emitted only when the set differs from the last one emitted for the session (kept per session id), and never
+while the set is empty, so a tool-free turn on a fresh session emits nothing. One exception: when the last one had
+items and the set is empty now (a rollback removed the tool calls), one empty event goes out, so the page drops the
+stale items; it is remembered, so the next empty request sends none. It goes out whatever the web's flag;
+the Bridge (`ClientEvent.project`) passes it on unchanged, and the attached TUI ignores it.
+
+**The route.** `GET /api/sessions/:id/working_set` (`Web::App#handle_working_set`) answers the snapshot's `to_h`
+and `running`. With a live worker it builds from the worker's snapshot messages (as `handle_show` reads them, keys
+symbolized) and the worker's llm ctx chip. Without one it builds from the session file and its saved chip
+(`SessionSetting::LLM_CONTEXT`). The folder is the session's `working_directory`. `running` is true when the
+snapshot has a turn in progress (`current_turn`).
+
+**The GET while a turn runs.** A worker's snapshot messages are the session's, not the running turn's, so they lag
+its events. The snapshot also carries `working_set`: the running turn's last `:working_set_updated` (`{items, at}`),
+which the Bridge's `TurnAccumulator#working_set` folds from the event log. It is cleared at `:turn_started` and at
+the turn's end, so it is nil between turns and before the turn emitted one. While a turn runs and it is set, the GET
+answers it as is (no build, no stat): a page opened mid-turn gets the running turn's set at once, and its `at` is the
+event's, so the page takes it (below). Before the turn's first event the turn's set is still the session's (the
+Engine emits only a set that differs from the last one), and the GET builds from the messages as between turns; so
+does one from an older worker without the field, its answer then behind the turn's events, which the page keeps.
+
+## Steering: drop and undrop
+
+`/working-set drop KEY…` and `undrop KEY…` (`WorkingSetCommand`, `SessionCommands#working_set`; the web's list posts
+the same lines on `POST /api/sessions/:id/command`) act on the session's messages between turns: the line is
+`mid_turn: :queue`, so one sent while a turn runs waits for its end (bare `/working-set`, the listing, is
+`:anytime`). `WorkingSetSteer` does the work on a copy (`Engine#clone_messages`, then `LLMContextEdit.store`'s new
+edits Hashes), which `Engine#replace_messages` puts in place; the session is saved, the rollback window closes
+(`TurnFlow#note_conversation_changed`, as `!cmd`), the result says `changed: [:messages]` (the web reads the
+conversation again) and `Engine#announce_working_set` re-emits the set, held behind the command's `command_ran`.
+
+- **The outputs** are `WorkingSet.outputs_of` the item under the strategy the set is built under
+  (`Engine#working_set_strategy`): the ones still `sent` get an applied `:drop` (`by: "user"`), the edit each held
+  before kept in its `was:`. A drop's view is the user's layer ([llm-context-forget.md](llm-context-forget.md)).
+  The reply weighs the batch (`LLMContextApply.weigh`: what it frees, the tail the server reads again).
+- **undrop** takes the item's drops off and puts each `was:` back. Free when the drop never reached a request (its
+  op is still in the pending note), else the reply says the tail.
+- **Refusals** live on one exception, `WorkingSetSteer::Refused` (its `reason` and words): not in the working set;
+  nothing to drop (only edited or written; only a legacy entry's derived ids; none of it sent now); already
+  dropped; not dropped. `forget_outputs` uses the same words for a dropped output ("dropped by the user"): the
+  model can neither forget nor restore it. A `memory_read` of several names is one output of each: dropping one
+  name drops that read for the others too.
+- **The note**: the ops since the last turn are one tail system message, `kind: working_set` (in
+  `Prompt::ESCAPED_KINDS`), its ops in `working_set_ops`. It is pending while only system messages follow it
+  (`WorkingSetSteer.pending_note_index`); a later op joins it, and an inverse op (an undrop of a pending drop) takes
+  both off, the note too when nothing is left. A turn that sends it makes it history; the next op starts a new one.
+
+The projection shows a dropped item as `dropped` (below), the GET and the event alike.
+
+## The page's overlay
+
+The page keeps its row-derived items and their `at` ordinals (the step tags' jump path), and overlays the server's
+`state` and `tokens` by key (`working_set.js overlay`):
+- files by absolute path (the row's `ref.path`; a title fallback won't match, so it stays live);
+- memories by name;
+- URLs by the row's key, which is its params preview with whitespace collapsed, cut at 80 characters with a "…".
+  The "…" is stripped and the rest is matched as a prefix of the server's URL.
+
+An item the server doesn't know yet (a running call) stays live. Known mismatch: live rows' refs resolve against the
+worker's `Dir.pwd` (a real path), the server against `working_directory`, so a session under `/tmp` can miss
+(`/private/tmp`).
+
+`working_set_view.js` keeps one server snapshot per session; `working_set.js newerSnapshot` picks which. `at` can't
+order them: a rollback (a canceled turn's `end_turn`, a failed turn's `TurnFlow` restore) shortens the conversation,
+so the right set can have the smaller `at`. The page orders by what it saw instead:
+- an event is always taken. The stream delivers them in the order the Engine built them, so the newest event is the
+  server's latest set, a rollback's smaller (or empty) one too;
+- a GET's answer is dropped when an event came while it was on its way (the view counts the events it took and
+  compares the count at the ask with the count at the answer): the event may be newer;
+- else it is taken, unless it is `running` and its `at` is smaller than the kept one's (it is behind the running
+  turn's events: a GET built from the messages). A `running` GET answered from the turn's last event has that
+  event's `at`, so it is taken. An idle GET after a rollback the page missed (a resync) or after a file changed wins at any `at`.
+
+No server sequence: the GET is built in `chi web` from the worker's snapshot or the file, the events in the worker,
+and a worker's event count starts over when it respawns; the page's own order needs neither. The page asks for it when it seeds a
+session's set (load, resync) and when the list opens (a file changed while the session sat idle). The stream handler
+passes `working_set_updated` to it, and does nothing when the flag is off. A new snapshot redraws:
+- the session bar's chip and the open list;
+- the footprints, in place (`refreshFootprints`, the same node; a `data-ws-sig` of the items' states skips an
+  unchanged one);
+- the rail (`onServer`, the stage's `scheduleRefresh`).
+
+A state is the item's state now, not when its turn ran. A state change never refolds and never moves a line: the
+rail's line key carries the label's state and its forgotten count, which are patched in place.
+
+**Steering from the page.** The list's `drop`/`undrop` (and `undo`, `undo all`) post `/working-set` lines on the
+command route (`createWorkingSet`'s `sendLine`). Pending ops are the queued lines (`command_queued` with `waits:
+"turn_end"`, any client's, and the snapshot's `queued_commands` replay after a reload), parsed and netted by
+`working_set.js pendingSteers` until each one's `command_ran`; a seed clears them (the replay brings them back).
+A steer line names a file by its absolute path, a memory as `memory:NAME`, a URL by the server's full key. `dropped`
+is in `STATES`: struck like forgotten, and a group is `dropped` when all its members are.
+
+**Looks** (design spec §3, §5): a stale line is faded (`opacity: .55`); a forgotten one is struck in `--text-faint`
+at `opacity: .5`. A group shows `✂n` for its forgotten members. It is struck only when all its members are
+forgotten, and faded when all are stale or forgotten (`groupState`). The list's ops text says `stale` or `forgotten`
+in words (colour is never alone) and shows `~1.2k` tokens per row (`tokensText`). A footprint adds `n forgotten`,
+struck. Titles add `(stale)` or `(forgotten)` per member.

data/docs/plugins.md

@@ -780,15 +780,18 @@ The Engine itself is never handed to a plugin.
 
 A bundle's settings are config.yml's, for every session. A setting a session may have of its own (a child's cap,
 say) is one the manifest lists in `session_settings:`; `chi --set BUNDLE.KEY=VALUE` and `chi send --new --set …`
-then give it to a new session, saved with it (a respawn, a fork and a continued link keep it; a delegate child
+(which also take a few core keys, `--set recap.enabled=false`: see
+[Per-session settings](configuration.md#per-session-settings)) then give it to a new session, saved with it (a respawn, a fork and a continued link keep it; a delegate child
 doesn't). chi refuses a bundle that isn't installed (or whose plugin doesn't load) and a key the manifest doesn't
 list, so a typo isn't saved. A manifest that types a key (`session_settings: {cap: number}`: `number`, which
 takes off too, `boolean`, `string`, or `any`) gets only a value of that type: `--set my-bundle.cap=five` is refused,
 exit 2, as a key it doesn't list is (a mapping needs a chi newer than 0.91.0). Values are typed simply: an integer (`3`, `-1`) or a decimal (`2.5`, `.5`, `1e1`)
 is a number, `true`, `yes` and `on` are true, `false`, `no` and `off` are false (any case, as config.yml's YAML reads
 them), and anything else stays the text as given (`010`, `0x10`, `3:30`, `y`, `null`; YAML would read the first
-three as numbers and `null` as nothing); a key typed `string` keeps its text as given (`yes`, `5`, `1.10`); `POST /api/sessions` `bundle_settings` types its strings the same way and
-keeps JSON numbers and booleans. `ctx.settings` is the config's section with the session's values laid over it (one level: a session's
+three as numbers and `null` as nothing); a key typed `string` keeps its text as given (`yes`, `5`, `1.10`); `POST /api/sessions` `settings` (`{"my-bundle.cap": 3}`) types its strings the same way and
+keeps JSON numbers and booleans. A name that is a core session setting is always chi's: a manifest whose
+`session_settings:` key `K` makes `NAME.K` one (a bundle `recap` offering `enabled`) is refused at install, and
+`chi bundle check` reports it as an `error clash`, in the same words. `ctx.settings` is the config's section with the session's values laid over it (one level: a session's
 `cap` replaces the config's `cap`). Read such a key from `ctx.settings` where it is used, not in
 `initialize(settings)`: that runs once at load, before any session, and gets the config only.
 

data/docs/sessions.md

@@ -151,6 +151,13 @@ system message marked `kind: turn_note` (the UIs don't show it; they showed the
   nothing). The user's last message is still unanswered.]`, or `[SYSTEM: the previous turn's answer was refused by
   the provider (cyber). …]` when the provider refused it.
 
+After you drop or undrop an item of the working set between turns (`/working-set drop KEY`, the web list's
+`drop`; [cli.md](cli.md#the-working-set)), the next turn starts with one line about it (`kind: working_set`,
+escaped like a context note; the UIs don't show it): `[WORKING SET: since your last turn the user dropped
+lib/cart.rb from your context: you are sent a stub instead of its outputs; read it again only if the task needs
+it.]`. Every op since the last turn joins that one line, and an undrop before the next turn takes its drop off it.
+The drop itself is saved on the entries (`edits`, kind `drop`), so `--resume`, rollbacks and forks keep it.
+
 When the context window fills past 40% (then 60%, 80%), the native loop leaves a similar line (`kind: context`):
 `[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted
 and range reads over full-file dumps]`, once per rise; see [context telemetry](internals/context-telemetry.md).
@@ -211,9 +218,9 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
 - `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `removed` (a `--queue --wait` message taken back before it ran), `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` (`worker_stopped`: the turn waited for died with its worker and the next worker settled it) and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs; with an idle session whose last turn already ended, that ended turn is the answer: its reply, or its end when it left no reply — a turn that finished in the gap between waits is reported, not waited for. With none of those (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
-- `--set BUNDLE.KEY=VALUE` (with `--new`, repeatable) gives the new session a bundle setting of its own, as `chi --set` does (see *Bundle settings* below): `chi send --new --set cost-cap.cap=3 -m "…"` starts it with a $3 cap. A bundle or key the installed bundles don't offer, or a value of another type than the manifest gives the key (`cost-cap.cap=five`), is a usage error (exit 2), as is `--set` without `--new`.
+- `--set KEY=VALUE` (with `--new`, repeatable) gives the new session a setting of its own, as `chi --set` does (see *Session settings* below): a core key a session may set (`--set recap.enabled=false`) or a bundle's `BUNDLE.KEY` (`chi send --new --set cost-cap.cap=3 -m "…"` starts it with a $3 cap). A key no session sets (`guardrails.mode`), a bundle or key the installed bundles don't offer, or a value of another type than the key takes (`recap.enabled=maybe`, `cost-cap.cap=five`) is a usage error (exit 2), as is `--set` without `--new`.
 - `--parent-answers LEVEL` (with `--new`) gives the new session its own `guardrails.parent_answers` (`hard`, `standard`, `soft`), tighten-only: config.yml's applies when it is stricter, with `chi send: warning: --parent-answers soft is looser than config.yml's …`. See *Parent answers* below.
-- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit, bundle settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
+- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit, session settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
 
@@ -274,15 +281,25 @@ fork keep it, and a `delegate` child starts with its parent's as it is then (a l
 it). A value that isn't a level reads as `hard`. `/parent-answers` changes it; loosening it is yours alone (see
 [Guardrails](guardrails.md#answers-from-a-parent-agent)).
 
-## Bundle settings
-
-A session file's `bundle_settings` (`{"cost-cap": {"cap": 3}}`, `{}` for none and for a session from before them)
-holds the bundle settings it was created with: `chi --set BUNDLE.KEY=VALUE`, `chi send --new --set …`, or `POST
-/api/sessions` `bundle_settings` (an object of the same shape, checked the same way; `400 invalid_bundle_settings`
-otherwise). They never change after: a respawned or woken worker reads the same, and a continue (`continue →`,
-`chi send --new --continues`) and a fork (`ctx.sessions.fork`) copy them, as they copy the toolkit. A delegate
-child starts without (a bundle has its own setting for children, such as cost-cap's `child:`). A bundle's plugin
-reads them in `ctx.settings`, over config.yml's `bundles:` ([Per-session settings](plugins.md#per-session-settings)).
+## Session settings
+
+A session's own settings are what `chi --set`, `chi send --new --set …` or `POST /api/sessions` `settings` gave it
+at creation. One changes live: `/recap on|off|default` (any UI, or `chi send -m "/recap off" ID`) sets or removes
+`recap.enabled` and the worker saves it, so a respawn keeps it. The file keeps them in two fields:
+
+- `config_settings` (`{"recap.enabled": false}`): the core keys a session may set (`recap.enabled`,
+  `recap.sentences`; see [Per-session settings](configuration.md#per-session-settings)), typed by their key. They go
+  first, over the CLI, the environment and config.yml. A value the file holds for a key that is no longer settable, or
+  of another type, is dropped when the file is read.
+- `bundle_settings` (`{"cost-cap": {"cap": 3}}`): a bundle's settings, which its plugin reads in `ctx.settings`, over
+  config.yml's `bundles:` ([Per-session settings](plugins.md#per-session-settings)).
+
+Both are `{}` for none and for a session from before them. `POST /api/sessions` takes them flat, as `--set` names
+them (`"settings": {"recap.enabled": false, "cost-cap.cap": 3}`), checked the same way (`400 invalid_settings`
+otherwise; `settings` beside `continues` is refused). A respawned or woken worker reads the same, and a continue
+(`continue →`, `chi send --new --continues`) and a fork (`ctx.sessions.fork`) copy them, as they copy the toolkit. A
+delegate child starts without (a bundle has its own setting for children, such as cost-cap's `child:`), so its recap
+follows config.yml. `/stats` names them on a `settings:` line, and `chi sessions stats --format json` as `settings`.
 
 ## Delegating
 

data/docs/testing.md

@@ -23,6 +23,13 @@ style pass: add a rule only for a bug class it would have caught. It runs in abo
 `rake release:check`; `rake lint` stays RuboCop alone (CI's rubocop job has no node). A name that is also a browser
 global (`name`, `status`, `open`…) passes even when its import is gone: give an export such a name only with care.
 
+CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
+(`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
+to it with `PW_TEST_CONNECT_WS_ENDPOINT`, and traces and the report stay on the runner. Nothing is installed with
+apt. The tag is the installed `@playwright/test`'s version, read at run time, so bumping it in `package-lock.json`
+moves the image too (`spec/ci_playwright_image_spec.rb` keeps a pinned tag out of the workflow). To run the suite
+that way locally: `npx playwright run-server --port 3333`, then `PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:3333/ npm run e2e`.
+
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
@@ -34,7 +41,7 @@ exception's text changes between Ruby versions: write the string yourself).
 The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
-`chains.js`, `unqueue.js`, `toasts.js`, `notice_links.js`, `start_page.js`, `session_actions.js`, `send_turn.js`, `dock_reserve.js`,
+`chains.js`, `working_set_view.js`, `working_set_rail.js`, `unqueue.js`, `toasts.js`, `notice_links.js`, `start_page.js`, `session_actions.js`, `send_turn.js`, `dock_reserve.js`,
 `vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a devDependency only,
 never shipped; lit reads `document` as it loads). The shim's `markupOf(template)`,
 `htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments; the DOM writes text with only `&`, `<`, `>`

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -35,6 +35,7 @@ module Samagotchi
         @merged_origins = []
         @recap = nil
         @continue_offer = nil
+        @working_set = nil
       end
 
       def call(event)
@@ -192,6 +193,17 @@ module Samagotchi
       end
       private_class_method :with_images
 
+      # The running turn's working set: its last :working_set_updated
+      # ({items:, at:}, Engine#emit_working_set). The session's kept messages
+      # lag the running turn, so this is what a mid-turn read of the set
+      # answers (Web::App#handle_working_set).
+      # @return [Hash, nil] a copy; nil with no turn running, or before the
+      #   turn emitted one (its set is then the session's: the Engine emits
+      #   only a set that differs from the last one)
+      def working_set
+        @mutex.synchronize { @working_set && Marshal.load(Marshal.dump(@working_set)) }
+      end
+
       # @return [String, nil] the last idle recap, until a turn makes it stale
       def recap
         @mutex.synchronize { @recap }
@@ -249,6 +261,7 @@ module Samagotchi
                     parts: [], pending_question: nil }
           @turn[:resumed] = true if event[:resumed]
           @tool_started_at = {}
+          @working_set = nil
           @turn[:images] = event[:images] if event[:images]
           @turn[:cut_after] = event[:cut_after] if event[:cut_after]
         when :input_merged
@@ -261,6 +274,7 @@ module Samagotchi
         if Events::TURN_END.include?(type)
           @turn = nil
           @merged_origins = []
+          @working_set = nil
         elsif event[:event_seq]
           @turn[:event_seq] = event[:event_seq]
         end
@@ -321,6 +335,8 @@ module Samagotchi
           Array(event[:steers]).each do |steer|
             parts << { kind: "steer", iteration: event[:iteration], source: steer[:source].to_s, text: steer[:text].to_s.dup }
           end
+        when :working_set_updated
+          @working_set = { items: event[:items], at: event[:at] }
         when :reminder_injected
           parts << { kind: "reminder", reminders: Array(event[:reminders]).map(&:dup) }
         when :question_requested

data/lib/samagotchi/bridge.rb

@@ -246,7 +246,10 @@ module Samagotchi
     # with its own).
     # The commands queued for after the running turn (queued_commands,
     # TurnAccumulator#queued_commands) too.
-    # @return [Hash] {messages:, current_turn:, queued:, queued_commands:, recap:, saved_recap:, continue_offer:, pending_question:,
+    # working_set: the running turn's last :working_set_updated ({items:,
+    # at:}, TurnAccumulator#working_set), which the messages lag; nil
+    # between turns and before the turn emitted one.
+    # @return [Hash] {messages:, current_turn:, working_set:, queued:, queued_commands:, recap:, saved_recap:, continue_offer:, pending_question:,
     #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:}
     def snapshot
       @engine.synchronize_events do
@@ -254,6 +257,7 @@ module Samagotchi
         {
           messages: @engine.messages_checkpoint,
           current_turn: current_turn_with_generation,
+          working_set: @accumulator.working_set,
           queued: @accumulator.queued,
           queued_commands: @accumulator.queued_commands,
           recap: @accumulator.recap,
@@ -571,10 +575,12 @@ module Samagotchi
 
     # /recap in an attached TUI: the saved recap, and a new one asked for at
     # once (it arrives as :recap_ready). Answers mid-turn too.
-    # 200 {enabled:, saved:, request:, min_user_turns:}. Returns [headers, status, body].
+    # 200 {enabled:, saved:, request:, min_user_turns:}; off, session_off:
+    # whether the session's own setting (/recap off) turned it off.
+    # Returns [headers, status, body].
     def handle_recap(_session_id, _body = nil)
       recap = @engine.recap
-      return [{}, 200, { enabled: false }] unless recap
+      return [{}, 200, { enabled: false, session_off: @engine.recap_override == false }] unless recap
 
       saved = @engine.saved_recap
       [{}, 200, { enabled: true, saved: saved, request: @engine.request_recap.to_s, min_user_turns: recap.min_user_turns }]

data/lib/samagotchi/bundle_command/check.rb

@@ -78,7 +78,7 @@ module Samagotchi
           check_requires_chi(manifest)
           check_trust(manifest)
           check_clash(manifest)
-          check_install(manifest) unless missing || placeholders?
+          check_install(manifest) unless missing || placeholders? || manifest.session_settings_clash
           check_boundary(manifest)
           check_tests
         end
@@ -245,6 +245,10 @@ module Samagotchi
       # Before the sandbox: the user's installed bundles and chi's shipped ones.
       def check_clash(manifest)
         name = manifest.name
+        # A session setting --set would read as chi's own: the install refuses it.
+        if (clash = manifest.session_settings_clash)
+          add(:error, :clash, "manifest.yml", clash, line: manifest_line("session_settings"))
+        end
         shipped = MemoryBundle::Listing.shipped.map(&:name) + [MemoryBundle::SystemBundle::BUNDLE_NAME]
         if shipped.include?(name) && !shipped?
           add(:warn, :clash, "manifest.yml", "chi ships a bundle named #{name}; installing this one replaces chi's",

data/lib/samagotchi/bundle_command/try/command.rb

@@ -2,7 +2,7 @@
 
 require_relative "../../cli/exit"
 require_relative "../../cli/flags"
-require_relative "../../bundle_session_settings"
+require_relative "../../session_config"
 require_relative "../../thinking"
 require_relative "sandbox"
 require_relative "run"
@@ -73,7 +73,7 @@ module Samagotchi
           render = Render.new(stdout: @stdout, stderr: @stderr)
           sandbox = nil
           begin
-            sandbox = Sandbox.new(path, bundle_settings: settings.bundle, cost_cap: settings.cost_cap,
+            sandbox = Sandbox.new(path, settings: settings.bundle, cost_cap: settings.cost_cap,
                                         cost_cap_override: settings.cost_cap_override)
             sandbox.install
             result = Run.new(sandbox).run(prompt: options[:prompt], options: options, timeout: timeout)
@@ -133,7 +133,7 @@ module Samagotchi
           nil
         end
 
-        # The --set KEY=VALUE pairs, typed as BundleSessionSettings.typed:
+        # The --set KEY=VALUE pairs, typed as SessionConfig.typed:
         # cost-cap.cap is the run's cap, the others the tried bundle's.
         # @return [Settings, nil] nil after saying what's wrong
         def parse_settings(pairs)
@@ -143,18 +143,18 @@ module Samagotchi
           pairs.each do |pair|
             key, sep, value = pair.partition("=")
             if key == COST_CAP_KEY && !sep.empty?
-              cost_cap = BundleSessionSettings.typed(value)
+              cost_cap = SessionConfig.typed(value)
               override = true
               next if (cost_cap.is_a?(Numeric) && cost_cap >= 0) || cost_cap == false
 
               @stderr.puts "chi bundle try: --set #{COST_CAP_KEY} takes a non-negative number or off"
               return nil
             end
-            unless !sep.empty? && key.match?(BundleSessionSettings::KEY)
+            unless !sep.empty? && key.match?(SessionConfig::KEY)
               @stderr.puts "chi bundle try: --set takes KEY=VALUE, not #{pair}"
               return nil
             end
-            bundle[key] = BundleSessionSettings.typed(value)
+            bundle[key] = SessionConfig.typed(value)
           end
           Settings.new(bundle: bundle, cost_cap: cost_cap, cost_cap_override: override)
         end

data/lib/samagotchi/bundle_command/try/sandbox.rb

@@ -83,9 +83,9 @@ module Samagotchi
 
         attr_reader :root, :config_home, :state_home, :work_dir
 
-        def initialize(path, bundle_settings: {}, cost_cap: 1, cost_cap_override: false)
+        def initialize(path, settings: {}, cost_cap: 1, cost_cap_override: false)
           @path = File.realpath(path)
-          @bundle_settings = bundle_settings
+          @settings = settings
           @cost_cap = cost_cap
           @cost_cap_override = cost_cap_override
           read_manifest
@@ -153,7 +153,7 @@ module Samagotchi
           data["context"]&.delete("sources")
           data["bundles"] = { "cost-cap" => { "cap" => @cost_cap } }
           data["bundles"][@manifest.name] ||= {}
-          data["bundles"][@manifest.name].merge!(@bundle_settings)
+          data["bundles"][@manifest.name].merge!(@settings)
           data["bundles"]["cost-cap"]["cap"] = @cost_cap if @cost_cap_override
           @layout.write_config(data)
         end

data/lib/samagotchi/bundle_command.rb

@@ -863,17 +863,17 @@ module Samagotchi
       Try::Command.new(stdout: @stdout, stderr: @stderr).run(parsed)
     end
 
-    # --set KEY=VALUE values as typed (BundleSessionSettings.typed), or nil
+    # --set KEY=VALUE values as typed (SessionConfig.typed), or nil
     # after saying what's wrong.
     def check_settings(pairs, label:)
-      require_relative "bundle_session_settings"
+      require_relative "session_config"
       pairs.each_with_object({}) do |pair, out|
         key, sep, value = pair.partition("=")
-        unless !sep.empty? && key.match?(BundleSessionSettings::KEY)
+        unless !sep.empty? && key.match?(SessionConfig::KEY)
           @stderr.puts "chi bundle #{label}: --set takes KEY=VALUE, not #{pair}"
           return nil
         end
-        out[key] = BundleSessionSettings.typed(value)
+        out[key] = SessionConfig.typed(value)
       end
     end
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.100.1
+version: 0.102.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/commands/registry.rb

@@ -96,6 +96,10 @@ module Samagotchi
       end
       private_class_method :listed_mid_turn
 
+      # A name is taken once, with one exception: core may give a name two
+      # entries, one the UIs run (local) and one the session runs, each with
+      # its own match (/recap shows in a UI, /recap off runs in the worker).
+      # #listing then has the name twice, /help and Tab once.
       # @param anytime [Boolean] mid_turn: :anytime (a bundle's command)
       # @param mid_turn [Symbol, #call, nil] see Entry; nil takes +anytime+
       # @param match [#call, nil] the default matches the name alone or the
@@ -104,7 +108,7 @@ module Samagotchi
       # @return [Entry]
       def register(name, description, id: nil, anytime: false, mid_turn: nil, local: false, uis: nil, match: nil,
                    source: "core", annotations: [], &handler)
-        raise ArgumentError, "command #{name} is already registered" if @entries.any? { |entry| entry.name == name }
+        raise ArgumentError, "command #{name} is already registered" unless name_free?(name, local: local, source: source)
 
         entry = Entry.new(id: id || name.delete_prefix("/").to_sym, name: name, description: description,
                           mid_turn: mid_turn || (anytime ? :anytime : :refuse), local: local, uis: uis, match: match || default_match(name),
@@ -203,6 +207,13 @@ module Samagotchi
         @entries << entry
       end
 
+      def name_free?(name, local:, source:)
+        taken = @entries.select { |entry| entry.name == name }
+        return true if taken.empty?
+
+        source == "core" && taken.size == 1 && taken.first.source == "core" && !taken.first.local != !local
+      end
+
       def default_match(name)
         after = /\A#{Regexp.escape(name)}\s/
         ->(text) { text == name || after.match?(text) }