samagotchi 0.141.0 → 0.143.0

data/docs/internals/participants.md

@@ -1,11 +1,12 @@
 # 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; and their **review turns** (P3b): queued, read-only,
-limited and capped; and what they **see** (P4a): their page and its reads, all through one filter. Participants are
-experimental. An agent participant waits on its own turns' replies through the API. The code and docs say
-"participants" and "review", never "shared": `session.shared` already means "attached by default".
+chi web with a link of their own. This page is the identity layer: grants, the gate, the routes a participant
+reaches, and what is written where; and their **turns**: review turns queued, read-only, limited and capped, pair
+turns that act under the owner's guardrails; and what they **see**: their page and its reads, all through one
+filter. Participants are experimental. An agent participant waits on its own turns' replies through the API. The
+code and docs say "participants", "review" and "pair", never "shared": `session.shared` already means "attached by
+default".
 
 Participants reach chi web on the **LAN** (`web.host: lan`), or **behind an auth proxy** with `web.public_url`
 (experimental; docs/configuration.md, "Behind an auth proxy"): there every request needs a token, this machine's too,
@@ -43,9 +44,9 @@ participant** and **one role**, until it expires or is revoked.
   newer chi's: read (its links work, but a grant with keys this chi doesn't know is left out: such a key may
   restrict it, so it fails closed) and never written (`Grants::Newer`, one message saying to update chi; a revoke
   the gate can't write still refuses the grant). A grant's keys this chi doesn't know are kept on a rewrite
-  (`Grant#extra`), so a field a later chi adds the omit-if-default way survives. A chi from before the version check
-  doesn't look at it: **mixed installs** on one state dir are a hazard, as a chi before 0.109 (no `identity`) rewriting
-  the store unbinds every grant, and one before this change drops unknown keys. A stored `identity` that isn't one
+  (`Grant#extra`), so a field a later chi adds the omit-if-default way survives. **Mixed installs** on one state dir
+  are a hazard: an older chi that doesn't know `identity` unbinds every grant when it rewrites the store, and one
+  that doesn't keep a grant's unknown keys drops them. A stored `identity` that isn't one
   `#issue` would write (`false`, `""`, a list, upper case) makes the store Corrupt (fails closed). 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
@@ -648,7 +649,7 @@ invited to has none: its files stay byte for byte as they were.
   expires_at, removed_at, cap}]}`, rewritten by whoever changes a grant (chi web, `chi share`), inside the grants
   store's lock (`Grants#update`'s `on_write`), so two writers can't finish out of order and lose a revoke here. Never
   a token or a digest.
-  The worker reads it with `Participants.read` (P3a's system-prompt line, `ctx`).
+  The worker reads it with `Participants.read` (`SessionParticipants#refresh!`, for the system prompt's participants line).
 - **`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 since chi web started: ip, user agent; behind a
@@ -668,8 +669,8 @@ invited to has none: its files stay byte for byte as they were.
 
 What a participant writes is marked as theirs everywhere it is kept or sent. The
 author is `"p:<id>"` (`Grant#author`), stamped by chi web from the principal and never taken from a body. Absent
-means the owner: old sessions and every owner path read as the owner's, byte for byte as before (a pre-P3 session
-fixture loads and saves unchanged, `spec/turn_author_record_spec.rb`).
+means the owner: a turn or session with no author keys reads as the owner's and gains none on save
+(`spec/turn_author_record_spec.rb`).
 
 - **Messages.** A participant's opening message is saved raw with `author`, `author_name` (the name the sidecar gave
   the participant when it was written) and `participant_mode` (`ParticipantMode.of` when `Engine#run_turn` builds it, before any request carries it). Merged input and
@@ -741,7 +742,7 @@ participant TUI in v1.
   worker announces `:participants_changed` (`Engine#announce_participants`: `{participants: [{id, name, kind}],
   joined: […], left: [{…, reason: revoked | expired}]}`) to every UI; its start announces nobody. "Joined" means
   invited: participants have no presence of their own yet. `session_state_snapshot`'s `participants` names who is in
-  the review now, so a UI that joins has them. Owner frames only: no participant stream carries them (P4a's filter).
+  the review now, so a UI that joins has them. Owner frames only: no participant stream carries them (`Web::ParticipantView`).
 - **Lines.** A participant's prompt (`turn_enqueued`'s `author`, an origin's, a queued row's, a saved message's
   `author` / `author_name`) is led by their name (`Formatting#participant_prefix`: `Alex ▸ review>`, cleaned by
   `ParticipantName`, the id when the TUI knows no name), in a colour picked from their id. Each change is one line per

data/docs/internals/prompt-caching.md

@@ -80,19 +80,18 @@ right-hand column happens.
   `toolkit.suggest.defer_turns` / `defer_tokens`) is engine-side, so `/toolkit`'s CacheConfirm doesn't apply: it
   changes the declared tools at the front of the request, and the server re-reads **system prompt + tools +
   conversation** on that turn. The defer bound keeps that conversation small; its notice says "from this turn".
-  When System 1 runs on the model's own single-slot local server (`Engine#system_one_shares_local_host?`), any
-  ask takes the slot and evicts its cached prefix: a first-turn ask costs that cache even when nothing switches
-  (there is little cached on a session's first turn), so on mode asks only there, skips the deferred path, and
-  sends no worker warm-up.
 - The candidate judge (`context.candidates.mode`, `ContextJudge`) adds nothing to the model's request: its asks
   go to System 1 only, and nothing it answers enters the running turn's history: on mode's attach writes only the
-  session's context folder, and its note comes with the between-turn delivery (`ContextAbsorber`), never mid-turn. On a shared local server it asks after the turn's last request, not skipped: a
-  completed turn starts the asks right before its turn-end warm-up, and the warm-up waits for them
-  (`PromptWarmup#start`'s `after:`, `AFTER_SECONDS` at most), so it re-warms the prefix the asks evicted and the
-  next turn prefills only its own message. A turn that ended otherwise (a Stop, a failure: no warm-up) starts them
-  from `Engine#run_turn`'s ensure, and its next turn re-reads its prompt. Where no warm-up runs (`cache.warmup:
-  off`, a chat host) the asks still evict the prefix. Bounded either way: at most two judged asks per candidate (one
-  re-ask after `reask_after_turns` owner prompts), plus a deferred ask per owner prompt before a task is stated.
+  session's context folder, and its note comes with the between-turn delivery (`ContextAbsorber`), never mid-turn.
+  Its asks start beside the turn on any host. Bounded: at most two judged asks per candidate (one re-ask after
+  `reask_after_turns` owner prompts), plus a deferred ask per owner prompt before a task is stated.
+- System 1's asks (`SystemOne::Client`, `/v1/systemone`) go beside the turn on any host, the model's own Splash too,
+  because they don't cost the session its cached prompt there. Measured 2026-11-01 on a local Splash with a 60k-token
+  session: the next request still had 60,064 tokens cached in 0.13 s after 3 asks (0.09 s with none), and 60,160 cached
+  in 0.18 s after 10 asks during generation; asks answered in 108-158 ms during a turn, and those 10 took the
+  generation from 2.87 s to 4.43 s. An earlier guard skipped or deferred them on the assumption that an ask takes the
+  slot and evicts the prefix, never measured there; don't rebuild it from that assumption. Not measured: a prefix past
+  Splash's cache capacity (262144 tokens).
 - A kit's prompt text (`toolkit.kits.<name>.prompt:`, `chi.toolkit … prompt:`) sits after the appended files and
   before the memory indexes (`SystemPrompt#kit_prompt_section`): one prefix per kit, never per-session text, so
   sessions on the kit share it; a memory write (the indexes after it) doesn't move it. It is part of the
@@ -275,7 +274,8 @@ is prefilled once. The native and the chat loop use the same plan.
 ## Server-side settings worth knowing
 
 - **Splash:** `--persistent-cache` (with `--max-cache-disk`) keeps restore points across restarts. Splash learns
-  a new branch point on the 2nd session, so the 3rd one gets the full reuse.
+  a new branch point on the 2nd session, so the 3rd one gets the full reuse. System 1's asks on the same server leave
+  a session's cached prefix alone (measured 2026-11-01, above).
 - **llama.cpp:** `--cache-ram` (the host-memory prompt cache, 8 GiB by default in recent builds) is what keeps
   sessions apart: when a task starts on a slot, the idle slots' state goes to that cache, and an unpinned request
   restores the best match on whatever slot it gets. So a recap or another session between two turns costs

data/docs/internals/remote-sessions.md

@@ -7,7 +7,7 @@ sessions, workers, memories and code stay on that machine; this one only sends r
 User-facing behaviour is in [cli.md](../cli.md#remote-sessions). This page is the code's shape, for changing it.
 
 **The one rule:** the remote side is that machine's **chi web**, never a worker's Bridge. Bridges stay on loopback,
-and answer only a request that names their secret from `bridge.json` ([architecture.md](../architecture.md)).
+and answer only a request that names their secret from `bridge.json` ([bridge.md](bridge.md)).
 chi web answers each request by calling the same `SessionAccess::Local` operation the CLI would call there.
 
 ## The seam: `SessionAccess`

data/docs/internals/{tool-guardrails.md → tool-output-limits.md}

@@ -58,7 +58,7 @@ Implementation note:
 
 ## The runner's cut (`max_tool_output_chars`)
 
-After a tool's own limits, `ToolRunner` caps every result at `max_tool_output_chars` (default `10000`
+After a tool's own limits, `ToolRunner` caps every result but a `memory_read`'s at `max_tool_output_chars` (default `10000`
 characters, both loops). How a longer one is cut is the tool's policy, `ToolOutputCut::POLICIES` (by the
 built-in name; a tool with none gets `:head`):
 
@@ -67,7 +67,26 @@ built-in name; a tool with none gets `:head`):
 | `execute` | `:head_tail_file` | a short head, a long tail, one gap line between them; the whole output saved in the session's folder |
 | `task_wait` | `:head_tail_ref` | the same head and tail, the gap line naming the task's log (`output_path`, `Tools::RefText`); nothing saved |
 | `delegate`, `delegate_result` | `:head_tail_ref` | the same, the gap line naming the child's reply file (its `output/<timestamp>.txt`); nothing saved |
-| `read` and every other tool (`task_get`/`task_list`/`task_create`/`task_stop`, `web_fetch`, `memory_read`, `context_read`, plugin and MCP tools) | `:head` | the first chars, then `[cut: N of M chars; read it in parts]` |
+| `read` and every other tool (`task_get`/`task_list`/`task_create`/`task_stop`, `web_fetch`, `context_read`, plugin and MCP tools) | `:head` | the first chars, then `[cut: N of M chars; read it in parts]` |
+| `memory_read` | `:head`, its own cap | not cut by `max_tool_output_chars`; see below |
+
+`memory_read` is the one tool `max_tool_output_chars` does not cap, in any form (a name, a comma list, a blank name for the
+indexes): a memory is read whole, since a model that needs the skill pays for all of it anyway. `ToolRunner#output_cap`
+resolves the cap per call, so both loops get it (they both come through `ToolResponse.run_batch`). Two things can still
+cut a `memory_read` result, both with the same `:head` cut and a line that says where the rest is, since `memory_read`
+has no parts to read:
+
+- `memory.read_max_chars` (default `0`: none). A positive value caps the result at that many characters.
+- The overflow guard, with `memory.read_max_chars` at 0: a result over half the model's context window (in characters,
+  tokens x `context.chars_per_token`) is cut. A context overflow is a hard failure (`LLM::FailedTurn.keeps_work?` is
+  false), so the turn's work rolls back and a retry would repeat the same read. The window is the loop's own:
+  `KernelLoop#tool_output_window` (the client's probe, the turn's `window_tokens` setting), or for `LLM::ChatLoop` its
+  adapter's model list too (`ToolRunner.new(kernel, window:)`). An unknown window (`ContextWindow` falling back to
+  its default) has no guard. It checks this one result, not the context already used.
+
+The line is `[cut: N of M chars; the rest is in the memory's .md file in <the memories dir(s) searched>: read it with
+start_line]` ("the memories' .md files" for a comma list or the indexes). `ToolOutputCut::HEAD_CUT` does not match it.
+`read` on a memory's file keeps the `max_tool_output_chars` cut: it has line ranges.
 
 `:head_tail_file` is for output whose end matters: a test run's summary, an error, the `exit:` line. The head is
 `execute.cut_head_chars` at most (default `1000`) and never more than a quarter of the room; the tail gets

data/docs/internals/web-push.md

@@ -188,7 +188,7 @@ from saying it twice across restarts). The key's `chi:` prefix keeps sw.js from
 
 `updated` is sent by the **restarted** chi web (its AutoUpdate finds the run at `phase: web`): the exec ends the
 old process, and `Notifier#stop` does not flush the shows still in their hold, so a push queued just before it would
-be lost. Sending from the new process also proves it came up.
+be lost. Sending from the new process also proves it came up. The workers left then restart without another show.
 
 **Seeding**: `Notifier#start(hub)` subscribes with `snapshot: true` and takes the summaries as the seed, so what is
 open already never pushes. The hub's projection is empty before its first scan, so `Server.start` runs `hub.scan`

data/docs/memory.md

@@ -182,7 +182,7 @@ Working habits for this model:
   `model_notes_deepseek` (`models: *deepseek-v4*`) and `model_notes_tone`
   (`models: *`, concise answers for every model). Each note's provenance
   and evidence is in the bundle's `notes/README.md`, and its spec pins which
-  model ids load which note ([Plugins](plugins.md#the-model-notes-bundle)).
+  model ids load which note ([Bundles](bundles.md#the-model-notes-bundle)).
   - **Your own note of the same name wins.** The install skips a
     `model_notes_<name>.md` you already have and never owns it, so your note
     is what loads, the two never stack, and upgrades leave it alone.
@@ -225,7 +225,7 @@ memory's line are left out), so their size is paid on every request. Nothing cap
 or trims them; chi measures them (tokens estimated as characters /
 `context.chars_per_token`) and shows the size:
 
-- `chi self` has a `memory index` row:
+- `chi self` has a `memory index` row (and a `big memories` row, see [A memory's size](#a-memorys-size)):
   `system ~2.0k tokens (54 lines), project ~1.4k tokens (35 lines)`, with
   `, over 2500` inside the parentheses for a scope over
   `memory.index_warn_tokens`.
@@ -252,6 +252,36 @@ may each get it. Bundle installs and uninstalls and hand edits
 change index lines without a note; `chi self`'s row shows where an index
 stands.
 
+## A memory's size
+
+`memory_read` returns a memory whole: `max_tool_output_chars` does not cut it (see [Tool output
+guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)), so each read of a memory pays its
+size. Two limits stay:
+
+- `memory.read_max_chars` (default `0`, no fixed cap) caps a `memory_read` result at that many characters.
+- An overflow guard: with that at 0 and a known context window, a result over half the window is cut. A context
+  overflow fails the turn and rolls its work back, and a retry repeats the read. With an unknown window there is no guard.
+  It checks one result, not the context already used.
+
+A cut result ends with `[cut: N of M chars; the rest is in the memory's .md file in <dir>: read it with start_line]`;
+`read` the file with `start_line` for the rest.
+
+`memory.entry_warn_tokens` (default `5000`, about 20K characters at the default `context.chars_per_token`; `0` turns it
+off) is the size a write may take one memory to before the model is told. When a `memory_write` with content, or a
+`write`/`edit` on a memory file, takes a memory from at or under the limit to over it, the tool result ends with one note
+(a memory that did not exist counts as 0, so a first big write gets it):
+
+> Note: memory 'NAME' is now ~N tokens (over memory.entry_warn_tokens 5000), paid on each read. When you next have a moment, tighten it; split out only parts that are read separately, since each new memory adds an index line to every prompt. Don't remove or merge memories unless the user asks.
+
+Once per crossing, as the index's note: a write while the memory is already over gets none. None for a
+description-only write, a remove, the verbatim `index` write, a model overlay, a `model_notes_*` memory (it has its own
+warning), a bundle install or a hand edit. It is independent of `memory.index_warn_tokens`: with that at 0 this note
+still comes, and a write that crosses both has both notes. Nothing is said when a memory is read: that would repeat on
+every read. `chi self` has a `big memories` row instead: the memories over the limit in both scopes, largest first
+(5, then `+N more`), `none` when there are none, a bundle's tagged `from <bundle>` (the shipped
+`config_modification_protocol` is over on every install; the fix is upstream's). This is how a
+memory already over the limit gets seen.
+
 ## Skills
 
 A **skill** is a memory named `skill_<name>` that holds the steps of a
@@ -290,7 +320,7 @@ A skill is plain Markdown, no frontmatter:
 
 It is a memory like any other: `memory_read`, `chi --mute skill_release`,
 `chi bundle build` share it. The optional `skills` bundle (`chi bundle install
-skills`, [docs/plugins.md](plugins.md#the-skills-bundle)) adds `/skill save`,
+skills`, [docs/bundles.md](bundles.md#the-skills-bundle)) adds `/skill save`,
 `/skill list`, `/skill show`, `/skill diff`, keeps older versions with a
 one-line diff after each update, and nudges a model that skips a failing
 step instead of fixing the skill.