samagotchi 0.102.0 → 0.104.0

data/docs/cli.md

@@ -21,6 +21,10 @@
 - `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 share ID --name NAME [--agent] [--expires 3d]`, `chi share ls [ID]`, `chi share revoke ID [P] | --all` — invite a participant to review a session through chi web on the LAN (a link of their own, 7 days), list them, revoke them (see [Participants](#participants))
+- `chi --remote NAME send|answer|note|context|sessions|share …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
+- `chi --remote NAME --attach ID` (`--resume ID`, `--dir DIR [-p TEXT]`) — the attached TUI on a session of that machine (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,6 +282,8 @@ 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 …`) or the run flags (`chi --remote studio --attach ID`, `--resume ID`, `--dir DIR -p TEXT`): 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). |
+| `--dir DIR` | With `--remote`: a new session's folder on that machine, its absolute path (required for a new session there). Without `--remote` it exits 2: cd there instead. |
 | `--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). |
@@ -611,16 +617,39 @@ 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. `/working-set undrop KEY…` sends it whole again. A change applies
+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).
-`/working-set` alone answers mid-turn too; `drop`/`undrop` sent while a turn
-runs wait for the turn's end.
+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>`,
@@ -724,12 +753,14 @@ REPL alike:
   with images works the same way: it waits for the turn's end, and the lines
   sent after it still go in at the next step.
   At the open prompt (no turn running) `/cut TEXT` and `/queue TEXT` run TEXT
-  as a normal prompt.
+  as a normal prompt, and the terminals say so: `(nothing is running: sent now)`.
 - `/unqueue` (attached terminal) takes back the newest line this terminal
   queued that hasn't started: `removed: <its first 60 characters>`, and its text
   goes back into the input to change and send again (not over typed text: then
   it is in the input history, ↑; not with input from a pipe; its images don't
-  come back), then the one before it on the next `/unqueue`; `(nothing queued: …)` when none waits,
+  come back), then the one before it on the next `/unqueue`. A command typed
+  after that text without clearing it (`fix it/unqueue`, `fix it/queue more`)
+  runs as the command, and the text stays in the input. `(nothing queued: …)` when none waits,
   `(not removed: it already started)` when its turn won the race, `(not removed:
   it is already gone)` when another client removed it. Other terminals that
   showed it say `(a queued message was removed)`; the web drops its bubble. A
@@ -1009,13 +1040,26 @@ turn view ignores it.
   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. 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`. Between turns it
+  `/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. On a phone a
+  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.
+  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.
@@ -1031,6 +1075,8 @@ the same live, after a reload and in every tab:
 - **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
@@ -1113,6 +1159,141 @@ 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` and the machine's own commands (`bundle`,
+  `memory`, `update`, …). `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, an attach as well (`chi --remote studio --attach
+  ab12 shows it`, `sessions stop`'s `chi --remote studio --resume ab12`).
+- 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.
+
+A session there in this terminal (the attached TUI, through that machine's
+chi web; its worker stays there):
+
+```sh
+chi --remote studio --attach ab12                      # attach (wakes its worker if it exited)
+chi --remote studio --resume ab12 -p "go on"           # resume there, run one turn, stay attached
+chi --remote studio --dir /Users/me/app -p "hi"        # a new session there (--dir required), one turn, stay
+```
+
+- The same TUI and exit codes (0 detached, 3 a question left waiting with
+  input from a pipe, 1 otherwise), every printed command with `--remote
+  studio`. Prompts, session commands, `/model`, `!cmd` (a shell command **on
+  that machine**, under its guardrails), `/queue`, `/cut`, `/unqueue`,
+  `/detach`, `/exit`, `/exit --delete`, `/archive`, `/stats` and `/recap` work
+  as here, on that machine's session (`/exit --delete` deletes it there).
+  The status row's children segment counts its delegates there, and a join
+  shows the steps' durations and a failed turn's line from its saved records
+  there. A chi web too old for one of them says so in one line ("remote
+  studio runs chi X, too old for this command through --remote: update chi
+  there").
+- A new session needs `--dir`, that machine's absolute path; `--model`,
+  `--thinking`, `--llm-context*`, `--toolkit`, `--tool`, `--no-tool`, `--set`
+  and `--parent-answers` are checked there (exit 2 for a bad one). With
+  `--attach`/`--resume` they work as here (`--model`, `--thinking`,
+  `--llm-context*` change the session; the others are named as ignored).
+  `--non-interactive` (use `chi --remote studio send --new --dir D -m TEXT
+  --wait`), `--verbose`, `--no-shared`, `--memory`, `--mute` and
+  `--append-system-prompt` run on this machine only (exit 2).
+- `@path` images are this machine's files (read and downscaled here, then
+  uploaded); Tab completes `/` commands and `@path`, not memory names. The
+  prompt history (↑) and `no_interrupt` / `no_default_input` are this
+  terminal's.
+- When chi web can't be reached the TUI says "(lost the connection to
+  studio; reconnecting…)" and tries for about a minute, then "(reconnected)";
+  what it missed is replayed or resynced. A prompt typed meanwhile is usually
+  accepted there and runs when a worker reads it. A worker that went away
+  (not stopped) is woken again. The end is worded by why: "The session was
+  stopped on studio. Resume it with: chi --remote studio --resume ab12", the
+  token refused, chi web unreachable, the worker gone, the session deleted.
+- The version line names both machines: the worker older than what studio
+  has installed (`chi --remote studio sessions restart ab12`), this terminal
+  older than studio (`chi update` here).
+
+How it works inside (`SessionAccess`, chi web's routes, where each check runs):
+[internals/remote-sessions.md](internals/remote-sessions.md).
+
+### Participants
+
+A session's owner can invite **participants**, people or agents, to review it through chi web on the LAN
+(`web.host: lan`), each with a link of their own that reaches that one session:
+
+```sh
+chi share 3f9a1c2e --name Alex
+# p_7c01d2aa  Alex (human, reviewer) · session 3f9a1c2e · expires 2026-10-30 14:02
+# http://192.168.1.29:4567/?token=chp_…#s=3f9a1c2e-…
+# (shown once: chi keeps only its digest; chi share revoke 3f9a1c2e p_7c01d2aa ends it)
+chi share ls                    # every session's participants (--format json; never a token)
+chi share revoke 3f9a1c2e       # every link to that session; add a participant id for one
+chi share revoke --all          # every link to every session
+```
+
+- The link is printed once (with a QR code at a terminal): chi keeps only a digest of its token. Send it to the
+  participant; opening it sets their browser's cookie, as the owner's LAN link does. `--agent` marks an agent
+  participant, which uses the token as `Authorization: Bearer` (e.g. `chi --remote` with that token).
+- It works for 7 days (`--expires Nh` or `Nd`, 1 hour to 30 days), until it is revoked, or until the session is
+  archived or deleted. A revoked or expired link shows "This review link has expired or was revoked."
+- For now a participant sees a page with the session's title and status; comments and the review itself come in
+  a later chi. They can't reach anything else: every other route answers them 403, another session 404.
+- `chi --remote studio share …` invites on studio: the link names studio's LAN address. Locally, the link names
+  this machine's chi web; without one on the LAN, chi says the link opens on this machine only.
+- The owner's own token and the `chi web --new-token` rotation are separate: rotating it ends no participant's link.
+
+How it works inside (grants, the gate, the routes, the audit trail):
+[internals/participants.md](internals/participants.md).
+
 ## Runtime Model Switch (Assist Mode)
 
 In interactive assist mode, you can switch the request model without restarting:

data/docs/configuration.md

@@ -1485,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

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:
@@ -594,7 +595,8 @@ only by the user: these change a model's system prompt for later sessions (see
 [Model notes](memory.md#model-notes); a shell command reaches them only under
 `shell-touches-chi`'s text heuristic); and answering chi's
 questions around `chi answer`: `chi --attach` or `chi -p` with stdin from a
-pipe, a here-string or a file, not `/dev/null` (`chi-answer-piped`), and `curl`/`wget` to a
+pipe, a here-string or a file, not `/dev/null` (`chi-answer-piped`, which also sees
+`chi --remote NAME --attach|--resume|-p` and `CHI_REMOTE=NAME chi …`), and `curl`/`wget` to a
 session's `/answer` route (`chi-answer-http`), both once or for the session, and only by the
 user (a parent agent allowing one would answer as the user).
 `chi answer` itself isn't asked about. It denies writes into `.git/hooks`.

data/docs/internals/context-telemetry.md

@@ -12,8 +12,12 @@ resumed session's line already names):
 
 Both loops do this, before each request (`ContextStatus`, one per turn). The
 chat loop's estimate counts the conversation's text and tool calls, not the
-tool schemas it sends, until the host's first count (its `usage`). The event
-carries a `status` string using this prefix:
+tool schemas it sends, until the host's first count (its `usage`). So that a
+turn's first request doesn't dip below the last turn's count (the schemas are
+thousands of tokens), the loop keeps the last counted request's chars per token
+(`ContextStatus#counted_chars_per_token`, on `KernelLoop` / `ChatLoop`) and the
+next turn's estimate before its first count uses it instead of
+`context.chars_per_token`. The event carries a `status` string using this prefix:
 
 `CONTEXT_STATUS ...`
 

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, 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}], 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`) |
@@ -518,7 +518,10 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display, refs?}` (display a string, or nil; refs the count of the answer's refs, only when a hook attached some) |
 
 The boundary events (`:turn_started`, `:turn_completed`, `:turn_canceled`, `:turn_failed`) also carry `origin`
-when the turn was queued with one.
+when the turn was queued with one: `{client_id:, enqueued_id:}`, plus `author:` when someone other than the session's
+owner wrote it (its input file's `author`, stamped by chi web from the request's `Web::Principal`). An owner's turn
+has no `author` anywhere: not in its input file, its origin or the session. `GuardrailWiring#begin_turn` gets the
+origin, and `#turn_author` reads its author for the gate's checks.
 
 ### Hook points (not events)
 

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

@@ -49,12 +49,22 @@ lets the model forget its own tool outputs. The pieces:
   `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/participants.md

@@ -0,0 +1,137 @@
+# Participants: identity and routes
+
+A session's owner can invite **participants** to review it: people, or agents, who reach that one session through
+chi web with a link of their own. This page is the identity layer (the shared-sessions plan's P2): grants, the gate,
+the routes a participant reaches, and what is written where. A participant can't send a turn yet (P3), and their page
+shows only the session's title and status until the full participant UI lands (P4). The code and docs say
+"participants" and "review", never "shared": `session.shared` already means "attached by default".
+
+Until `web.public_url` lands, participants are a **LAN** feature (`web.host: lan`): a loopback peer is always the
+owner, and a reverse proxy on the same machine would make every visitor loopback.
+
+## Grants
+
+A grant (`Web::Grants`, `lib/samagotchi/web/grants.rb`) binds **one random token** to **one session**, **one
+participant** and **one role**, until it expires or is revoked.
+
+- **Token.** `chp_` + 43 URL-safe characters (32 random bytes, as the owner's `Web::Token`). The prefix lets the gate
+  look up only participant tokens, and a leaked one is recognisable. It is shown **once**, in the link chi share or
+  `POST …/participants` prints; chi keeps only its **SHA-256 digest**. Lookup digests the presented token and
+  compares it with every grant's digest (`Rack::Utils.secure_compare`).
+- **Participant.** The grant's `id`, `p_<8 hex>`, names the participant: a turn they send will be authored
+  `"p:<id>"` (`Grant#author`, `Principal#author`; P3). `kind` is `human` or `agent` (D11: an agent uses the same
+  token, as a Bearer header; there is no agent UI). `role` is `reviewer`, the only one in v1. `name` is cleaned to
+  one line of at most 64 characters with no brackets (`Grants.clean_name`), so it can't forge P3's
+  `[Review contribution from …]` header.
+- **Lifetime (D8).** 7 days by default (`chi share --expires Nh|Nd`, 1 hour to 30 days). Revoked by the owner
+  (`chi share revoke`, `DELETE …/participants`), and by an **archive** (the session and its delegates) or a
+  **delete** (`SessionManager.archive_session` / `delete_session` → `Participants.end_sessions`). A session pruned by
+  retention, or archived or deleted by a process that didn't revoke, is caught by the gate: a live grant whose session
+  file is gone or archived is revoked on sight (`revoked_by: gone | archive`). Unarchiving doesn't restore a grant.
+  An ended grant stays in the store for 30 days, so its token answers `token_revoked` / `token_expired` rather than a
+  bare 401; then it goes.
+- **Store.** `$XDG_STATE_HOME/samagotchi/web-grants/grants.json`, next to `web-token`: the file 0600, in its own 0700
+  folder, written whole (`AtomicFile`) under a lock file (`grants.lock`) since chi web and a local `chi share` both
+  write it. Readers follow its mtime (a `chi share revoke` in another process takes effect at chi web's next request).
+  `last_used_at` is written at most once a minute per grant. **chi web refuses to start** when that folder or file can
+  be read by another user, or isn't this user's (`Grants.check_permissions!`, one message naming the `chmod`). Only
+  those two are checked: the state dir above is often 0755, and that's fine. Never point `XDG_STATE_HOME` at a
+  shared folder.
+- Rotating the owner token (`chi web --new-token`) never touches grants; `chi share revoke --all` ends them all.
+
+## The gate
+
+`App#principal_for` resolves every request to a `Web::Principal`:
+
+1. A loopback peer, or a chi web not on the LAN: the **owner** (unchanged).
+2. The owner's token (Bearer, then the cookie; `?token=` on the page's trade): the **owner**. Checked first, so the
+   owner's requests never touch the grants store (measured: no change to an owner route's time).
+3. A `chp_` token whose grant is active: a **participant** (`Principal.new(kind: :participant, grant:)`).
+4. Anything else: nil. `#token_gate` answers an ended grant's token **401 `token_revoked`** or **401
+   `token_expired`** (the page: "This review link has expired or was revoked. Ask the session's owner for a new
+   one."), any other **401 `unauthorized`** as before.
+
+The `?token=` trade sets the `chi_token` cookie to the token that was presented, the owner's or the participant's
+(one at a time per browser: a participant link opened in the owner's browser replaces the owner's cookie there).
+
+Then `#route`, for each matching `ROUTES` row:
+
+1. A participant on a `/api/sessions/:id…` route whose id isn't their grant's session gets **404 `not_found`**, the
+   same answer as a session that doesn't exist, before the permission check: they can't learn which sessions exist.
+2. A route whose permission the principal lacks (`Principal#permits?`) gets **403 `not_permitted`**, worded for the
+   role: "a participant can't do that: only the session's owner can".
+
+`spec/web/participant_gate_spec.rb` walks `ROUTES`: every `:owner` row answers a participant 403, and every session
+row answers another session's id 404, so a new route is covered without a new example.
+
+## What a participant reaches (P2)
+
+| Route | Permission | A participant gets |
+|---|---|---|
+| `GET /` | participant | the participant page (server-rendered, no script): "Alex's review", the session's title and status, "Comments open soon", the participants' names. Never the owner's page, where every route would refuse them. |
+| `GET /api/info` | participant | `{app, version, features}` (what `SessionAccess::Remote`'s check needs); not `pid`, `cwd`, `lan`, `installed` |
+| `GET /api/sessions/:id` | participant | their session only, whatever the query (`brief`, `cards`, `tail`, `timing`): `{session: {id, title, status, participants: [{id, name, kind, role}]}}` (the active ones). `title` is the session's own title, or "an untitled session": never `display_title`'s fallback, the first prompt's opening words |
+
+Everything else is `:owner`, `POST …/turn` included (P3 opens it). Static assets (`/app.js`, …) are served to any
+principal past the gate: they are the public frontend.
+
+**Streams.** No stream route is a participant's yet (`App#stream_filter` raises for one, until P4's filter). The
+seam for ending them is in place: `App#stream_running(principal)` is the proxy's running check (asked every
+`BridgeClient::STREAM_POLL`), and for a participant it is false once the grant is revoked or expired, so P4's
+participant streams close within a poll of a revoke, including one made by `chi share revoke` in another process.
+
+## The owner's routes
+
+| Route | Body / params | Answer | Refusals |
+|---|---|---|---|
+| `GET /api/sessions/:id/participants` | | 200 `{participants: [grant]}`, every state | |
+| `GET /api/participants` | | 200 `{participants: [grant]}`, every session's | |
+| `POST /api/sessions/:id/participants` | `name`, `kind` (`human`/`agent`), `ttl` (seconds) | 201 `{participant: grant, token, link, lan}`: the token and the link once; `link` names this chi web's LAN address (`http://IP:PORT/?token=…#s=<id>`), `lan` false when it has none | 400 `invalid_participant` (name, kind, ttl, an archived session); 404 |
+| `DELETE /api/sessions/:id/participants[?id=p_…]` | | 200 `{revoked: [grant]}`: one participant, or the session's | 400 `invalid_participant` |
+| `DELETE /api/participants` | | 200 `{revoked: [grant]}`: every session's | |
+
+A grant here is `Grant#public_h`: `id, session_id, kind, name, role, created_at, expires_at, revoked_at, revoked_by,
+last_used_at, state` (`active | revoked | expired`). Never the token or its digest.
+
+`chi share` (docs/cli.md) uses them through `--remote`, and `SessionAccess::Local`'s same-named operations here
+(`participants`, `invite`, `revoke_participants`; `ParticipantView`, `Invitation`). A local invite's link names
+the local chi web's LAN address when one runs (its `GET /api/info`), else `127.0.0.1` with a line saying it opens on
+this machine only.
+
+## Files in the session dir
+
+Neither is in the session JSON (chi web never saves that, and a worker would overwrite a field it added), and
+neither is copied to a continue, a fork or a delegate (a continue starts with no participants). A session nobody was
+invited to has neither: its files stay byte for byte as they were.
+
+- **`participants.json`** (0600, `Participants.write`): `{participants: [{id, kind, name, role, added_at,
+  expires_at, removed_at}]}`, rewritten by whoever changes a grant (chi web, `chi share`). Never a token or a digest.
+  The worker reads it with `Participants.read` (P3a's system-prompt line, `ctx`).
+- **`participants.jsonl`** (0600, append-only, `Participants.log`): one JSON line per event, with `at`: `issued`
+  (participant, name, kind, role, expires_at), `revoked` (participant, by), `expired` (the first refused use after the
+  expiry, once per chi web), `peer` (the first use and each new peer address since chi web started: ip, user agent),
+  `refused` (method, path, reason; at most once a minute per route). It goes with the session (retention, delete).
+
+## Errors through `--remote`
+
+Each condition has one message, owned by its `SessionAccess` class and built from the remote's label
+(`Remote.access_error`, keyed by chi web's error code, for any route):
+
+| Code | Class | Message |
+|---|---|---|
+| 401 `token_revoked` | `TokenRevoked` (an `AuthRefused`) | `this review link was revoked by the session's owner` |
+| 401 `token_expired` | `TokenExpired` (an `AuthRefused`) | `this review link expired: ask the session's owner for a new one` |
+| 403 `not_permitted` | `NotPermitted` | `this token is a participant's: only the session's owner can do that` |
+| 429 `too_many_turns` | `TooManyTurns` (P3b) | `this participant has too many turns waiting: wait for one to finish` |
+| 429 `cap_reached` | `CapReached` (P3b) | `this participant's spending cap is reached: ask the session's owner to raise it` |
+
+A 401 `unauthorized` stays `AuthRefused`'s "the token was refused".
+
+## Invariants
+
+- The owner is a loopback peer or the owner's token; nothing else. A participant token never widens to the owner.
+- A participant reaches one session, through the `:participant` rows only; another session is a 404.
+- No token is written anywhere: the grants store has digests, the sidecar and the audit trail have neither.
+- Owner sessions are unchanged: no sidecar, no audit file, no key in the session JSON until a grant exists.
+- P2 lets no participant reach `POST …/turn`, `/command`, `/answer` or a stream. P3 adds the turn, with the author
+  stamped from the principal (never the body), and the worker's review boundary.