samagotchi 0.101.0 → 0.103.0

data/docs/cli.md

@@ -16,11 +16,13 @@
 - `chi web --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages, the stage's asking text and a resolved question card's reply
 - `chi web --web-view turn` — draw turns with the turn view (each turn as one block of steps, the running one at the bottom of the history) instead of the default stage view (the running turn pinned above the composer); `?view=stage|turn` on the page URL overrides it (see [Web views](#web-views))
 - `chi web --web-working-set` — the stage view's working set (experimental, off by default; `--no-web-working-set` turns a config's `web.working_set: true` off): what each turn brought into the model's context, in the stage and under each finished turn; `?working_set=1|0` on the page URL overrides it (see [The working set](#the-working-set))
-- `chi sessions list|stop|restart|archive|unarchive|delete|prune|clean|stats` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). `stats ID` prints a session's cost, tokens and progress (a live worker's `GET stats`, else its saved `analytics.json`; `--format json` one object) without running a model turn. A usage error (an unknown subcommand or flag, a flag missing its value, `stop`, `restart` or `delete` with no ids, a bad `list --format` or `--scope`, a `--days`, `--keep` or `--limit` that isn't a whole number) exits 2; an unknown or refused session exits 1
+- `chi sessions list|stop|restart|archive|unarchive|delete|prune|clean|stats` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). `stats ID` prints a session's cost, tokens and progress, and its own settings (`--set`; a `settings:` line), from a live worker's `GET stats`, else its saved `analytics.json` (`--format json` one object, with `settings`), without running a model turn. A usage error (an unknown subcommand or flag, a flag missing its value, `stop`, `restart` or `delete` with no ids, a bad `list --format` or `--scope`, a `--days`, `--keep` or `--limit` that isn't a whole number) exits 2; an unknown or refused session exits 1
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi context <add|push|ls|show|refresh|rm|mute|unmute> …` — attach live external text to sessions (a command chi runs every so often, or text pushed in); the model gets a short note when it changes and reads it with `context_read`; `chi context add <URL>` attaches a GitHub PR with the github-pr bundle (see [Attached context](context.md))
 - `chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one takes it at its next step; `--cut` asks it to cut long thinking for it; `--queue` runs it as a turn of its own after the running one, and `--queue --wait` waits for that turn's own answer); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead (`--new --continues ID|last:ID` the next link of that session's chain, see [Session chains](sessions.md#session-chains)), and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending — to an idle session whose last turn already ended, that ended turn's reply or end comes back; `--wait --turn T ID` with no message waits for exactly turn T, whether running, queued or last ended; `--format json` includes its `turn_id` when known, for waiting again after exit 3 or 4; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). What a parent may pick follows `guardrails.parent_answers`, or the session's own `parent_answers` when stricter (`soft`, the default: a deny, a plain answer, Continue and "Allow once"; `standard`: no allow; `hard`: no Continue either), never a wider scope or an allow on chi's own config; a refused pick exits 1 with what to answer instead (a convention, not a security boundary; see [Guardrails](guardrails.md#answers-from-a-parent-agent))
+- `chi remote add NAME URL [--token-file F | --token-stdin]`, `chi remote ls`, `chi remote rm NAME` — the other machines whose chi web the session commands reach with `--remote NAME` (see [Remote sessions](#remote-sessions))
+- `chi --remote NAME send|answer|note|context|sessions …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
 - `chi memory ls [--scope project|system] [--format text|json]` — the memories of both scopes (this folder's project first), one row each: scope, name, size, date, `from <bundle>`, the index description and its model overlays; `chi memory rm NAME [--scope project|system]` removes one as `memory_write` with `remove: true` does: its file and model overlays go to the bundle trash (the line names the dir; `chi bundle trash` lists and empties it) and its index line is dropped. NAME in both scopes without `--scope` exits 2 naming both; a missing NAME or a bundle's memory (`chi bundle uninstall` removes it) exits 1 (see [Memory: Listing and removing from the shell](memory.md#listing-and-removing-from-the-shell))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
@@ -278,11 +280,12 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--shared` | Run the session (new, or `--resume`'s) in a background worker and attach to it: the default, and the way to get it when `session.shared` is off. See [Sharing a session](#sharing-a-session). |
 | `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
+| `--remote NAME` | Before a session command (`chi --remote studio send …`): run it against that remote's sessions, through its chi web; beats `CHI_REMOTE`. Commands and flags that run on this machine only exit 2. See [Remote sessions](#remote-sessions). |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
 | `--toolkit NAME`, `--tool NAME`, `--no-tool NAME` | A new session's toolkit, the tools its prompts declare: `full` (every built-in), `lean`, `child`, one of config's `toolkit.kits` or a bundle's (without `--toolkit`: config's `toolkit.default`), with tools declared on top of it (`--tool`) or left out (`--no-tool`); both repeatable, a comma list too. Saved in the session as given; a respawned worker, a fork and a continue keep it. Ignored with `--attach`/`--resume` (one line, as `--memory`); `/toolkit` changes it. Not on `chi web` (config's `toolkit.default` covers its sessions). See [Toolkits](configuration.md#toolkits). |
 | `--parent-answers LEVEL` | A new session's own `guardrails.parent_answers` (`hard`, `standard` or `soft`): what a parent agent may answer on its questions. It may only tighten config.yml's: the stricter of the two applies, and a looser one is saved as given with a warning (`--parent-answers soft is looser than config.yml's guardrails.parent_answers: standard; standard applies`). Saved in the session; a respawned worker, a fork and a continue keep it, a `delegate` child takes its parent's. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. Only you loosen it: `/parent-answers` in the terminal or the web. See [Guardrails](guardrails.md#answers-from-a-parent-agent). |
-| `--set BUNDLE.KEY=VALUE` | A bundle setting for a new session (repeatable; a later one of the same key wins), laid over config.yml's `bundles: <bundle>:` in what the bundle's plugin reads (`ctx.settings`): `--set cost-cap.cap=3`. The value is 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 in config.yml), anything else stays the text as given (`010`, `0x10`, `3:30`, `y`, `null`), and so does every value of a key the manifest types `string`. For cost-cap, `0`, a negative number or `off` is no cap. Only a key the installed bundle's manifest lists in `session_settings:` is taken, with a value of the type it gives the key: a bundle that isn't installed (or whose plugin doesn't load), a key it doesn't list (a record installed before the bundle listed it says to run `chi update` or `chi bundle upgrade NAME`), a value of another type (`--set cost-cap.cap=five`), or another shape (`--set foo`, `--set a.b.c=1`) is an error naming what it takes, exit 2, nothing started. Saved in the session; a respawned worker, a fork and a continue keep it, a delegate child doesn't. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. See [Per-session settings](plugins.md#per-session-settings). |
+| `--set KEY=VALUE` | A setting for a new session (repeatable; a later one of the same key wins). A core key a session may set (`recap.enabled`, `recap.sentences`) is typed by the key and goes first, over the CLI, env and config.yml: `--set recap.enabled=false` turns the idle recap off for this session; a value it doesn't take (`recap.enabled=maybe`) or a key no session sets (`guardrails.mode`) is an error, exit 2 (see [Per-session settings](configuration.md#per-session-settings)). Any other name is a bundle's `BUNDLE.KEY`, laid over config.yml's `bundles: <bundle>:` in what the bundle's plugin reads (`ctx.settings`): `--set cost-cap.cap=3`. The value is 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 in config.yml), anything else stays the text as given (`010`, `0x10`, `3:30`, `y`, `null`), and so does every value of a key the manifest types `string`. For cost-cap, `0`, a negative number or `off` is no cap. Only a key the installed bundle's manifest lists in `session_settings:` is taken, with a value of the type it gives the key: a bundle that isn't installed (or whose plugin doesn't load), a key it doesn't list (a record installed before the bundle listed it says to run `chi update` or `chi bundle upgrade NAME`), a value of another type (`--set cost-cap.cap=five`), or another shape (`--set foo`, `--set a.b.c=1`) is an error naming what it takes, exit 2, nothing started. Saved in the session; a respawned worker, a fork and a continue keep it, a delegate child doesn't. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. See [Per-session settings](plugins.md#per-session-settings). |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |
@@ -500,7 +503,8 @@ a terminal, headed by `<id8>  <status>  <model>`: a live worker answers its
 Bridge's `GET stats`, else the snapshot is rebuilt from the session's saved
 `analytics.json` (never starting a worker; a worker that does not answer in
 time falls back to the disk and the line says so). `--format json` prints one
-object `{session_id, status, live, metrics}`; a session with no
+object `{session_id, status, live, metrics, settings}` (`settings`: the session's own `--set` values, flat as
+`--set` names them, `{}` for none); a session with no
 `analytics.json` yet reports `metrics: null` (`(no metrics yet)` in text) and
 exits 0. An unknown or ambiguous id exits 1 with `chi sessions stop`'s
 wording. See [Sessions](sessions.md#cli).
@@ -602,6 +606,48 @@ the same values on its `llm context:` line. The web's info bar shows them as the
 through `/llm-context`. See "LLM context: a session's own strategy" in
 [configuration.md](configuration.md).
 
+`/working-set` lists the session's working set as the model has it (see [The
+working set](#the-working-set)): each file, memory and URL its turns read,
+edited or fetched, with its state (`stale`, `forgotten`, `dropped`) and what it
+costs as sent, then the changes the next turn starts with. `/working-set drop
+KEY…` takes an item out of what the model is sent: every read of it still sent
+goes as a stub, `(dropped by the user) — read it again if the task needs it`,
+whatever the LLM context strategy (none too), and stays dropped across a
+strategy switch. KEY is a path (absolute or the session folder's), `memory:NAME`
+or a URL; quote one with spaces (`"my notes/a b.md"`, as the listing shows it). `/working-set undrop KEY…` sends it whole again. A change applies
+from the next turn's first request, which also carries one line telling the
+model what you dropped or brought back (so it doesn't read it again by reflex);
+the reply says what it frees and the tail the server reads again (a drop changes
+history, so the prompt cache breaks there once). An undrop before that request
+undoes the drop for free. Refused, with why: an item only edited or written
+(nothing of it to drop), one not in the set, an older session's output chi
+can't name. The model can't undo a drop (`forget_outputs` refuses it). One
+`memory_read` of several names is one output: dropping, undropping or pinning
+one name acts on that read whole, so on the others too, and the reply names
+them (`; the same memory_read holds memory tone: dropped with it`).
+`/working-set pin KEY…` keeps an item from the model's `forget_outputs` (the
+[forget layer](configuration.md#llm-context-the-forget-layer)): it refuses every
+read of it, those to come too, until `/working-set unpin KEY…`. A pin sends
+nothing different (no cache break) and is saved with the session, so a respawn,
+a continue and a fork keep it, across a strategy switch too; under a strategy
+without forget it waits until one has it (the reply says so). The listing marks
+it `pinned`, and under forget the next turn's line tells the model. A pinned
+item can't be dropped until you unpin it; a pin takes back a drop not yet sent
+(free), and asks you to undrop one already sent first.
+`/working-set add KEY…` brings an item in: the next turn's line asks the
+model to load it before anything else (`read` for a file, `memory_read` for
+`memory:NAME`, `web_fetch` for an http(s) URL), so it costs the model one tool
+call, and what it reads is an ordinary read (droppable, forgettable, in the
+set). Nothing is sent until then, and `/working-set unadd KEY…` takes an add
+back for free. On a stale or forgotten item it is a refresh (the model reads
+it again). Refused, with why: a file that isn't there (or a directory), a
+memory neither scope holds, a URL that isn't http(s), an item the model is
+sent whole now, a dropped one (undrop it instead), one already added. The
+listing's last line names the pending adds (`added lib/tax.rb`). The model is
+asked, not forced: a model may skip the read.
+`/working-set` alone answers mid-turn too; `drop`/`undrop`/`pin`/`unpin`/`add`/`unadd`
+sent while a turn runs wait for the turn's end.
+
 `/thinking` shows the thinking level the next turn runs at and where it came
 from (`session`, `--thinking` / `SAMAGOTCHI_THINKING_LEVEL`, `models: <key>`,
 `hosts.<name>`, `thinking.level`). `/thinking off|low|medium|high` sets the
@@ -741,7 +787,7 @@ REPL alike:
   `cutting in…`, then `steered`. A phone shows the short form (`↳ after this
   thinking · 0:42`) with `cut in` and `queue` chips.
 - Commands answer, wait or are refused, by what they do:
-  - At once, beside the turn: `/stats`, `/recap`, `/help`, `/context`, a
+  - At once, beside the turn: `/stats`, `/recap` (and `/recap on|off|default`), `/help`, `/context`, a
     plugin's anytime command (`/btw`), and the commands that only show
     something: `/models` (with a filter too), and `/model`, `/llm-context`,
     `/thinking`, `/reasoning-history` and `/guardrails` alone.
@@ -987,7 +1033,28 @@ turn view ignores it.
   (used, preloaded, muted) and URLs, each with what was done to it (`read ×2`,
   `read, edited`, `preloaded`) and a step tag (`s3`, `t2·s3` in the session's
   scope, `prompt` for a preloaded memory) that goes to the call. A file opens
-  as its row's title does, a URL in a new tab.
+  as its row's title does, a URL in a new tab. A row (on hover or keyboard
+  focus) and a folded group offer `drop`, which runs `/working-set drop` (see
+  `/working-set` above); a dropped row offers `undrop`, and so does one whose
+  drop holds on some reads only (`part dropped` in `/working-set`'s listing:
+  an older read stubbed by the stale layer, or a newer read sent). Between turns it
+  applies at once; while a turn runs it waits for the turn's end: the row is
+  dashed with `drops next turn` and an `undo`, and the list's foot counts the
+  pending changes (`undo all`), in every tab and after a reload; the stage's
+  rail dashes the item's line too (its tooltip says `drops next turn`). On a phone a
+  tap on a row opens its actions under it. `drop` is greyed, with why on
+  hover, for an item only edited, a memory only preloaded, or one already
+  forgotten. Under a strategy with forget a row also offers `pin`
+  (`/working-set pin`, pending as `applies next turn` mid-turn); a pinned row
+  shows `📌` and `unpin` (under any strategy), and its `drop` is greyed until
+  you unpin it.
+  The list's foot (a phone's last row) takes a path, `memory:NAME` or a URL
+  and runs `/working-set add`: the item shows as a dashed `+ name` row with
+  `reads next turn` and an `undo` until the next turn starts (the model is then
+  asked to read it, and it joins the set as the model reads it). A stale or
+  forgotten row offers `refresh`, the same add of it. While a turn runs the
+  stage's rail shows an add queued for its end as a dashed `+ name · next turn`
+  line.
 
 Only `read`, `edit`, `write`, `memory_read`, `memory_write` and `web_fetch`
 calls that succeeded count; files an `execute` touched don't.
@@ -1000,6 +1067,11 @@ the same live, after a reload and in every tab:
   write doesn't make a file stale. Chi checks at each request and when you
   open the list, so a file changed while the session sat idle shows stale on
   opening it. A turn saved before chi kept that record shows its files live.
+- **dropped** (struck): you dropped it (`/working-set drop`, the list's
+  `drop`); its reads are sent as stubs under every strategy until you undrop
+  it.
+- **pinned** (`📌`): you pinned it (`/working-set pin`, the list's `pin`);
+  `forget_outputs` refuses it.
 - **forgotten** (struck): nothing of the item's content is still sent to the
   model under the session's current LLM context strategy (`forget_outputs`
   forgot every read of it; see
@@ -1007,7 +1079,7 @@ the same live, after a reload and in every tab:
   forget kept count as still sent. Under `/llm-context strategy none` nothing
   is cut, so a forgotten item is live again from the next request.
 
-The list says `stale` or `forgotten` in words with each row, and how many
+The list says `stale`, `forgotten` or `dropped` in words with each row, and how many
 tokens its content costs as sent (`~1.2k`); a folded group shows its forgotten
 members as `✂n`, and a footprint adds `n forgotten`.
 
@@ -1082,6 +1154,72 @@ access token", paste the token there (the part of the link after
 - On http the browser has no notifications: the bell is hidden on the phone,
   and the tab title still counts what needs you.
 
+### Remote sessions
+
+The session commands also reach another machine's sessions, through its chi
+web on the LAN: the sessions, workers, memories and code stay there. On the
+other machine (the Studio), run `chi web --web-host lan`; on this one (the
+laptop), add it once with its token (the part of its LAN link after
+`token=`, or its `$XDG_STATE_HOME/samagotchi/web-token` file):
+
+```sh
+chi remote add studio http://192.168.1.29:4567 --token-file studio-token
+# studio  http://192.168.1.29:4567  chi 0.103.0, LAN 192.168.1.29
+chi --remote studio send --new --dir /Users/me/projects/app --wait -m "fix the flaky spec"
+chi --remote studio answer ab12 --question q1 --option 1
+CHI_REMOTE=studio chi context push claude-outbox ab12 < answer.json
+```
+
+- `chi remote add NAME URL` checks the address and token first (`GET
+  /api/info`) and says what it found: the chi it runs and its LAN address, or
+  why not: nothing answers (start chi web there with `web.host: lan`), the
+  token was refused, or a hostname (chi web answers its LAN IP only: use the
+  IP, which changes with the Wi-Fi), or a chi too old for remote sessions.
+  Nothing is saved then. The remotes live in
+  `$XDG_CONFIG_HOME/samagotchi/remotes.yml` (0600), their tokens inside: a
+  token runs commands as you there. `chi remote ls` (`--format json`) never
+  prints one; `chi remote add` of an existing name replaces it.
+- `--remote NAME` goes before the command (`chi --remote studio note …`),
+  `CHI_REMOTE=NAME` in the environment does the same for every command a
+  script runs; the flag beats the variable, and there is no default remote.
+  An unknown name exits 2.
+- What runs there: `send` (every form: `--new`, `--wait`, `--queue`,
+  `--cut`, `--image`, a session command), `answer`, `note`, a session's
+  `context add|push|ls|show|rm` and `sessions
+  list|stop|restart|archive|unarchive|delete`. The rest runs on this machine
+  only and exits 2 with `chi <command> runs on this machine only: run it on
+  <remote>`: `context refresh|mute|unmute` and `--project`, `sessions
+  stats|prune|clean`, `broadcast`, the machine's own commands (`bundle`,
+  `memory`, `update`, …) and a session in this terminal (`--attach`, `-p`,
+  `--resume`: remote attach comes later). `chi remote`, `--version` and
+  `--help` always run here.
+- `send --new` needs `--dir`, that machine's absolute path (no folder of this
+  one is guessed); `--toolkit`, `--set` and `--parent-answers` are checked
+  against that machine's config and bundles. `sessions list` lists every
+  project's sessions there (`--scope=project --cwd DIR` one project's) in the
+  `--live` text form. `context` takes the session ids (no default session),
+  and a URL resolves through that machine's bundles.
+- That machine's config.yml decides what it checks for `send` and `answer`:
+  a parent agent's `/continue yes` and options (`guardrails.parent_answers`),
+  a loosening `/parent-answers`, images to a model that can't see them. Each
+  target refuses its own (`ab12  refused: …`), where this machine refuses
+  before sending to any.
+- Waits run on the server, 30 s at a time, until the answer or your own
+  `--timeout`; exit codes are the same. The commands chi prints for what to
+  do next work as pasted: they carry `--remote NAME` (`chi --remote studio
+  answer ab12 --question q1 --option N`, `chi --remote studio send --wait …`),
+  under `CHI_REMOTE` too. What runs on this machine only isn't offered:
+  where chi says `chi --attach ID` here it names that machine's chi web
+  (`chi web on studio shows it`), and `sessions stop` names no `chi
+  --resume`.
+- A remote that can't be reached names itself and why (`chi send: remote
+  studio (http://192.168.1.29:4567): connection refused`, exit 1; with
+  `--format json` an `error` object).
+- Plain http, the same as the phone's: use it on your home network.
+
+How it works inside (`SessionAccess`, chi web's routes, where each check runs):
+[internals/remote-sessions.md](internals/remote-sessions.md).
+
 ## Runtime Model Switch (Assist Mode)
 
 In interactive assist mode, you can switch the request model without restarting:
@@ -1120,7 +1258,16 @@ working on, what came of it and what is still open, not a turn-by-turn log.
   after it (`recap (before the last 2 turns)>`). One written while you sit at
   the prompt prints there.
 - `/recap` shows the saved one and asks for a new one when the chat moved on
-  (`writing a recap…`, then the recap when it comes).
+  (`writing a recap…`, then the recap when it comes). The web answers the bare
+  `/recap` with a note (the recap shows there by itself).
+- `/recap off` and `/recap on` turn the recap off or on for this session, at
+  once and in any UI (the web composer too, and mid-turn); `/recap default`
+  goes back to config.yml's. The reply says both: `recap: off (this session;
+  config.yml: on)`. It is the session's own `recap.enabled`, as `--set
+  recap.enabled=false` gives it (see [Per-session
+  settings](configuration.md#per-session-settings)): saved with the session,
+  so a respawned worker keeps it, and it beats config.yml (`/recap on` under
+  `recap: false` turns it on here). With it off, `/recap` says so.
 - One written while a continue offer waits (the last turn ran out of steps)
   says that turn stopped before the task was finished. Answering `no` counts
   as activity, so the next recap no longer says so.

data/docs/configuration.md

@@ -119,7 +119,8 @@ own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
 `guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
 settings for its hooks, see [Hooks: Settings](hooks.md#settings); a session's own
 `--set BUNDLE.KEY=VALUE`, for a key the bundle's manifest lists in `session_settings:`, lays over them, see
-[Per-session settings](plugins.md#per-session-settings)),
+[Per-session settings](plugins.md#per-session-settings); `--set KEY=VALUE` does the same for a few core keys,
+see "Per-session settings" below),
 `memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
 choose. The `memories:` list is the persistent baseline for preloaded memory entries —
 the same name shape as `--memory` (bare name or `scope/name`), merged under
@@ -160,7 +161,7 @@ or `chi web` restart.
 | `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
 | `guardrails.*` | Next tool call or approval | Guardrail rules and disable lists are reloaded when the config file changes; rule settings take effect on that evaluation. `guardrails.parent_answers` is checked when a parent answers a question. |
 | `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
-| `recap.*` | Worker start | The engine builds its recap job once. |
+| `recap.*` | Worker start | The engine builds its recap job at start, and again when it binds a session with its own `recap.enabled` or `recap.sentences` (`--set`, see "Per-session settings") and when `/recap on\|off\|default` changes the session's own value. |
 | `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
 | `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.task_wakes`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
 | `session.retention_*`, `session.max_count`, `session.keep_status`, `session.sweep_interval_hours` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. The sweep interval is checked on the next hub tick. |
@@ -172,6 +173,26 @@ or `chi web` restart.
 | `kitty.*`, `tmux.*` | `chi desktop upgrade` or desktop update | These settings are copied into the desktop helper's launch file. |
 | `model.profile`, `reasoning_history` | Not from config.yml | These are CLI/environment settings; `models:` and `hosts:` provide their model- and host-specific forms. |
 
+### Per-session settings
+
+A few core keys can be set for one session: `chi --set KEY=VALUE` (or `chi send --new --set KEY=VALUE`, or
+`POST /api/sessions` `settings`) at its creation, and `recap.enabled` later too with `/recap on`, `/recap off` or `/recap default`
+(at once; `default` removes the session's own value, see [Session recap](cli.md#session-recap)). The value is saved in the session file (`config_settings`), so a
+worker respawn, a continue and a fork keep it; a delegate child starts without it, on config.yml's. It goes first:
+
+    session (--set) → CLI → environment → config.yml → default
+
+- `recap.enabled`: `true` or `false` (also `yes`/`on`/`1`, `no`/`off`/`0`); `true` turns the recap on for the
+  session even under `recap: false`.
+- `recap.sentences`: `N` or `N-M` (1–10).
+
+A value is typed by its key and checked when given: `--set recap.enabled=maybe` is refused (`recap.enabled takes
+true or false, not "maybe"`), and so is a key no session sets (`--set guardrails.mode=strict`: not a session
+setting). The same `--set` takes a bundle's `BUNDLE.KEY` (see [Per-session settings](plugins.md#per-session-settings));
+a name that is a core key is always the core one, and a bundle can't offer a setting whose `NAME.KEY` is one.
+`/stats` lists a session's own values (`settings: recap.enabled=false · cost-cap.cap=3`), and `chi sessions stats
+--format json` has them as `settings`.
+
 ### Environment variables
 
 Every setting has an environment variable (except the ones the table marks
@@ -1464,7 +1485,13 @@ models:
   forget keeps lines of it; a keep outside the output's lines, of a big file's head/tail preview, or holding all of
   it; an output too small for a stub to free anything; one already stubbed or forgotten; an unknown id, or one whose
   output chi can't pair with its call for sure (it shows no id). The system prompt, user messages, steers and context
-  notes have no ids.
+  notes have no ids. An output you dropped, or one of an item you pinned, is refused too (`dropped by the user`,
+  `pinned by the user: it stays in your context`).
+- **Pins.** `/working-set pin KEY…` (or the web list's `pin`, shown under forget only) keeps an item from the model's
+  forget: every read of it, those to come too, until `/working-set unpin KEY…` (see [cli.md](cli.md#the-working-set)).
+  It sends nothing different, so the prompt cache holds. The pins are the session's own (`working_set_pins` in the
+  session file): a respawned worker, a continue and a fork keep them, across a strategy switch too; a delegate child
+  starts without. Stale stubs still apply to a pinned file's superseded reads (its newer read is sent).
 - **When stubs reach the prompt** follows `llm_context.apply`, as `stale`'s do: the result says
   `applied, the next request sends the stubs (frees …)` or `staged until the turn ends`.
 - **Restore.** `forget_outputs(restore: ["t45"])` brings a forgotten output back with the next request, whatever
@@ -1589,14 +1616,14 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `server.open_timeout` | `10` | yes | Connection timeout, seconds. |
 | `server.read_timeout` | `600` | yes | Read timeout, seconds. |
 | `server.first_token_timeout` | 120 remote, off local | | Seconds to the first token; `0` = off. `hosts.<name>.first_token_timeout` wins. |
-| `recap.enabled` | on | | `false` (or `recap: false`) turns the idle recap off. |
+| `recap.enabled` | on | | `false` (or `recap: false`) turns the idle recap off. Per session too: `--set recap.enabled=false`, or `/recap off` in the session (see "Per-session settings"). |
 | `recap.model` | session's | yes | Model that writes the recap: an id, alias or `host:model` (the host then picks where to ask; a bare id goes where a bare `--model` goes). |
 | `recap.host_ref` | session's | yes | A `hosts:` name to ask (`host:` is accepted too, also a host name, not a model ref). |
 | `recap.base_url` | none | yes | An OpenAI API base to ask instead (`http://h:8081/v1`). |
 | `recap.inactivity` | `180` | yes | Idle seconds before a recap. |
 | `recap.timeout` | `30` | yes | Seconds a recap request may take. |
 | `recap.min_user_turns` | `2` | yes | Prompts a session needs before it gets a recap. |
-| `recap.sentences` | `2-4` | yes | Recap length, `N` or `N-M` (1–10). |
+| `recap.sentences` | `2-4` | yes | Recap length, `N` or `N-M` (1–10). Per session too: `--set recap.sentences=3`. |
 | `broadcast.active_hours` | `8` | | `chi broadcast` reaches a session a worker or a chi REPL runs, or whose last turn ended within this many hours. See [Broadcast](broadcast.md). |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | | A Ruby regex for ticket ids; one in the note and in a session's branch (any case) or prompts delivers the broadcast there. See [Broadcast](broadcast.md). |
 | `broadcast.triage_model` | recap's | | The model that judges a recipient no tag matched (a model ref, as `recap.model`); unset: the recap's model, else `default.model`. A ~9B dense instruct model or larger; 4B-class ones say yes to nearly everything. See [Broadcast](broadcast.md#triage). |

data/docs/guardrails.md

@@ -582,7 +582,8 @@ hooks, approvals, bundles or attached context sources, or a `.git/hooks`
 (`shell-touches-chi`, `touches: chi_dirs`), unless they only read
 (`skip_read_only`); `chi context add … --cmd` (`chi-context-cmd`, once at a
 time: a command chi will run every few minutes outside the guardrails; see
-[Attached context](context.md#safety)); `chi broadcast` (`chi-broadcast`,
+[Attached context](context.md#safety); the rule also sees `chi --remote NAME context add`, and a remote's `context push`
+reaches its session with the trust of its chi web token, as your own `chi context push` does there); `chi broadcast` (`chi-broadcast`,
 once at a time and only by the user: it is the user's command, which also
 refuses to run inside a session; see [Broadcast](broadcast.md)); removing a
 memory with `memory_write remove: true` (`memory-remove`, once at a time:

data/docs/internals/bundles.md

@@ -32,7 +32,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
 | `PreparedSource` (source.rb) | one source normalized once (dir, owned, git commit): `BundleCommand` reads the bundle's name from its `manifest.yml` (the name for every kind of source, a git URL too) and hands it to the Installer (`prepared:`), so a source is cloned or extracted once per command |
 | `MemoryFiles` | which top-level `*.md` files of a bundle are its memories (`.select`: the `files:` list, else all but README/LICENSE and the like), `.unshipped` (listed, not shipped) and `.symlinks` (skipped: a symlink is never a memory) |
-| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `BundleSessionSettings` to check) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
+| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `SessionConfig` to check) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
 | `Installer` | one install/upgrade/dry run of one bundle (below) |
 | `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
 | `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |

data/docs/internals/engine.md

@@ -509,7 +509,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:question_requested` / `:question_answered` / `:question_cancelled` | `QuestionDesk`: a question is asked (an approval, `ask_user_question`, a hook's or plugin's `ask_user`, the step-limit Continue), answered, or withdrawn | `{pending_question}` / `{id, answer}` / `{id, reason}` |
 | `:plugin_init_wait` | a turn waits for plugin init tasks that provide tools (`PluginTasks`) | `{tasks: [{bundle, id, label}]}` |
 | `:used_memories_updated` | a memory was read, and after the loop | `{used_memory_names, read_names?}` |
-| `:working_set_updated` | after `:generation_started` (the running turn's conversation, the turn's strategy) and once in `end_turn` before the end event (the kept messages), only when the set differs from the last one emitted for the session and is not empty: a tool-free turn emits none (`Engine#emit_working_set`) | `{items: [{kind, key, state, tokens, ops, count, first_id}], at}` (`WorkingSet`, internals/working-set.md) |
+| `:working_set_updated` | after `:generation_started` (the running turn's conversation, the turn's strategy) and once in `end_turn` before the end event (the kept messages), only when the set differs from the last one emitted for the session and is not empty, except one empty event when the last one had items (a rollback emptied the set): a tool-free turn emits none (`Engine#emit_working_set`); between turns `Engine#announce_working_set` announces it under the next turn's strategy (after a `/working-set` op, held behind the command's `command_ran`) | `{items: [{kind, key, state (live\|stale\|forgotten\|dropped), tokens, ops, count, first_id, pinned, has_drop}], at, adds?: [{kind, key, label}]}` (`WorkingSet`, internals/working-set.md; `adds` while the user's adds are pending) |
 | `:hook_notice` | a hook's or plugin's notify during a turn | `{hook, text, level}` (announced with `between_turns: true` outside a turn) |
 | `:guardrail_warning` | a guardrails line during a turn | `{message}` |
 | `:turn_completed` | normal end | Engine event `{result, turn_summary, display_pending}`; the Bridge's SSE frame omits `result` (answer remains in `turn_summary.output`) |

data/docs/internals/llm-context-forget.md

@@ -35,12 +35,36 @@ lets the model forget its own tool outputs. The pieces:
 - **Restore** takes the forget off the entry (`LLMContextEdit.remove`, a new edits Hash); the next request sends the
   output again, outside the apply rule (the result says the tail the server reads again, and `ContextStatus#edited!`
   restarts the estimate). A read whose stub was sent isn't restored; a staged one is.
+- **Which edits are sent** is one predicate, `LLMContextView#sends?(edit)`: applied, and its kind one of the view's
+  layers or `:drop`. The view stubs by it and `WorkingSet` decides "still sent" by it. The view's layers are
+  `LLMContextStrategy::LAYERS` (`stale`, `forget`), the strategy's words, not `LLMContextEdit::KINDS`: whatever a
+  caller passes as the strategy, an edit kind no strategy names never becomes a layer that `apply_llm_context!` would
+  hand to `LLMContextApply.run!`. Under none the view has no layers and, unless an entry holds a drop
+  (`LLMContextEdit.drop_on?`, one scan), `#messages` returns the Array it was given.
+- **The user's layer, always on**: an edit of kind `:drop` (`by: "user"`, the working set's drop:
+  [working-set.md](working-set.md#steering-drop-and-undrop)) is sent under every strategy, none included, as
+  `(dropped by the user) — read it again if the task needs it` after the output's lead. It is saved applied by the
+  op itself, between turns, so the apply rule never holds it and no `[#id]` is added under none. One edit per id: a
+  drop on an output that holds another edit keeps that edit's saved Hash in its `was:`, and an undrop puts it back.
+  `LLMContextApply.measure`/`.weigh` and `#restored_line` build their views from the same class, so a drop counts in
+  them under none too. The model can't take a drop off: forget_outputs refuses to forget or restore a dropped
+  output, in `WorkingSetSteer::Refused`'s words ("dropped by the user").
+- **The user's pins**: an item the user pinned in the working set (`Session#working_set_pins`,
+  [working-set.md](working-set.md#steering-pin-and-unpin)) is guarded against the model's forget only: forget_outputs
+  refuses an output of it, in `WorkingSetSteer::Refused`'s words ("pinned by the user: it stays in your context").
+  `KernelLoop#forget_outputs` passes `LLMContextForget.call` a `pinned:` callable (`WorkingSet.pinned_ids` of the
+  session's pins, by the projection's pairing, the Engine's `working_set_pins`), asked once per forget; a pin covers
+  the item's later reads too. A restore of a pinned item's forget (one from before the pin) goes through. Stale stubs
+  still apply (a superseded read's newer read is sent, so the pin holds in substance), and a pin changes nothing that
+  is sent: no cache break.
 - **Stubs** (`LLMContextView`): `(forgotten) <note>` on the first output of a call's forgets in a row, `(forgotten
   with tN: see its note)` on the rest (a run of the same note, author and stamp, no other output between them),
   ` [restore: tN]` on a non-read with a stored id, then each kept range under `lines A-B kept:`. The entry keeps its
   role, tool_call_id and images bookkeeping as for stale, and a find_tools result's `loaded:`, so a Messages host
   still gets the load's references (anthropic.md, "Deferred tools"); only the sibling text is the stub.
-- **Offers**: `ContextStatus` (internals/context-telemetry.md).
+- **Offers**: `ContextStatus` (internals/context-telemetry.md). Its `TIDY`/`COMPACT` lines name no output, so a pin
+  has nothing to take out of them; the refusal is how the model learns of one if it tries (and the turn-start
+  `working_set` note says it was pinned).
 - **Persistence**: the edits ride on the entries (plan D3), so `--resume`, rollbacks and forks keep the stubs and the
   restores; `/stats` counts each applied batch's re-prefill.
 - **Measuring**: the bench's `forget_outputs` strategy (internals/llm-context-bench.md).

data/docs/internals/prompt-caching.md

@@ -56,7 +56,7 @@ right-hand column happens.
 │                ◄── remote Claude / Messages: breakpoint #2 on the last   │  the image cut moving
 │                    non-system message (Messages: its last user block)    │  a batch, history
 ├──────────────────────────────────────────────────────────────────────────┤  sanitizing (thinking
-│ tail notes   reminders, turn notes, steers (system/user messages)        │  stripped per spec)
+│ tail notes   reminders, turn notes, steers, the working-set note         │  stripped per spec)
 │ new prompt   this turn's user message                                    │
 └──────────────────────────────────────────────────────────────────────────┘
 ```
@@ -108,6 +108,13 @@ right-hand column happens.
   loaded name stays deferred, a stub once its source is gone), so the request after a load reads the whole prefix;
   the loaded definitions and the new result are the fresh part. A plugin's
   `ctx.load_tools` only appends (a system `tool_addition` after the user message, never a change to `tools`).
+- A user's working-set drop (`/working-set drop`, [working-set.md](working-set.md#steering-drop-and-undrop)) changes
+  an earlier entry: it is saved between turns, so the next turn's first request is the first to send the stub and
+  the cache breaks there once, from the dropped output's entry on (the command's reply says that tail; an undrop
+  after the drop was sent breaks it once more). It is sent under every strategy, so it is the one edit that rewrites
+  history under `none`; without a drop, `none` sends the stored Array as it is. Its `working_set` note (what the user
+  dropped or brought back) is a tail system message after the history, one per turn with ops, escaped as context
+  notes are (`Prompt::ESCAPED_KINDS`). The turn-end warm-up never warms a drop sent after the turn: it misses once.
 - Side requests (idle recap, `/btw`) go through `IdleClient` with their own short system prompt. On a current
   llama.cpp they don't evict the session (see the server settings below); chi never pins them to a slot.