samagotchi 0.145.0 → 0.146.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6055a05533de1a37a9e9393effa720eb2ca93f0db2715d7f806f83cae3086a8d
-  data.tar.gz: ac0a46f034b62cf4c0b6968d6bb9b07fdf8bae8ab331f4745b4a597ef45dd8c9
+  metadata.gz: 701bfb63903962a149abf5d17f39be6c043141e5e1b9ea952e7ba27b77ebe3d8
+  data.tar.gz: 7be23545775dc31bba230e8dfde6c896def7530d032cc8ae7f79d2a9b91d7782
 SHA512:
-  metadata.gz: 7e0ab9f589c50aa6c3fa7bdb37b64e17d9963191fa1878e624dd33d68f296d31bd107a09eb8feb5ae7bd85b9c7f2e6bbf1ff1c296ae1fd938a828160c7c5a488
-  data.tar.gz: 34688115cd7554ed4f660ab131dfcccb4dd7d15e24f72c7e32f6802d1a2c422d80cfea3cef47f18afc689eb653fc36102b5726d45129202f157d91f1d1db09b7
+  metadata.gz: 8e4a8bbbfa0398b816a6dd266a6b127f507e6329feaf2b5f37283f2eef76344a334e2bf60409978fab45ab714c56ca1c9c44754174222238d930845bc0f5d929
+  data.tar.gz: 139f5254bb1dbeec07cbdf6cb0033cdb34ce5eae967585a9ab9a843fb961528e0d16b77d562668789646b38b16eaca42e28f2338d49f4ebe47b42a58be6f9597

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.146.0] - 2026-11-03
+
+### Added
+
+- `chi memory usage [--scope project|system] [--top N] [--format text|json]` reports what the memories
+  cost, counted from the saved sessions: each scope's index tokens against `memory.index_warn_tokens` and
+  how many of its lines name a memory no session read, the memories read most by tokens with the share they
+  make of all read tokens, and the user's own memories no saved session read. It reads only — no grades, no
+  advice to delete, nothing written. [docs/memory.md](docs/memory.md) has the details.
+
+### Changed
+
+- A `delegate` child started with no `cwd:` whose task names another checkout of the repository gets a
+  `Warning:` line in the tool result naming that checkout and how to start the child there; the child still
+  runs in the parent's folder. [docs/sessions.md](docs/sessions.md#delegating)
+- The session option on a file ask says what it covers: "Allow edits to config.yml for the session"
+  rather than "Allow this call for the session".
+
+### Fixed
+
+- The session bar's status chip follows a question or approval card the moment it is answered,
+  instead of holding "waiting" until the next tick while the turn is already running again.
+- A parent agent may give Allow once on a delegate child's `child-boundary` ask under
+  `guardrails.parent_answers: soft`. It was refused with a false "changes chi's own config"; an ask
+  that really names chi's own files stays yours.
+- A parent agent's Deny on a child's approval says so: the child read "The user declined this call".
+- A delegate child's second report in one parent turn reaches the parent. A reply that came after a
+  reported question, while the parent's turn was still running, was lost with nothing left to wake it.
+
+Update with `chi update`.
+
 ## [0.145.0] - 2026-11-02
 
 ### Changed
@@ -5549,7 +5580,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.145.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.146.0...HEAD
+[0.146.0]: https://github.com/dm1try/samagotchi/compare/v0.145.0...v0.146.0
 [0.145.0]: https://github.com/dm1try/samagotchi/compare/v0.144.0...v0.145.0
 [0.144.0]: https://github.com/dm1try/samagotchi/compare/v0.143.0...v0.144.0
 [0.143.0]: https://github.com/dm1try/samagotchi/compare/v0.142.0...v0.143.0

data/docs/cli.md

@@ -30,7 +30,7 @@
 - `chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]`, `chi share ls [ID]`, `chi share cap ID P DOLLARS`, `chi share revoke ID [P] | --all` — invite a participant to a session through chi web on the LAN (read-only review turns in a review session, pair turns that act under your guardrails in a working session) (a link of their own, 7 days, a $2 spending cap), list them, change one's cap, revoke them (see [Participants](#participants))
 - `chi --remote NAME send|answer|note|context|sessions|share|review …` (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 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. `chi memory usage [--scope project|system] [--top N] [--format text|json]` reports what the memories cost over the saved sessions: each scope's index tokens and how many of its lines name a memory nobody read, the memories read most by tokens, and the user's own memories no saved session read (`--top` caps the rows per section, 10; no sessions says so and exits 0) — see [Memory: What the memories cost](memory.md#what-the-memories-cost)
 - `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))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `big memories` the memories over `memory.entry_warn_tokens` ([Memory](memory.md#a-memorys-size)), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)

data/docs/guardrails.md

@@ -81,7 +81,8 @@ Who answers:
 
 The model gets one line on a deny. A rule's or hook's deny reads
 `[execute] Error: denied by guardrail (rule git-push, bundle guardrails): git push publishes commits. The user was not asked. Do not retry it or reach the same result another way; ask the user how to proceed.`
-When the user picks Deny on an ask, it leads with the user's answer:
+When the user picks Deny on an ask, it leads with the user's answer (a parent
+agent's Deny says `The parent agent declined this call`):
 `[execute] Error: The user declined this call: "open a PR instead". It needed approval (rule git-push, bundle guardrails): git push publishes commits. Do not retry it or reach the same result another way; ask the user how to proceed.`
 
 ## Approvals
@@ -91,7 +92,7 @@ Allowing beyond "once" is stored in `$XDG_STATE_HOME/samagotchi/guardrails/appro
 
 | Scope | Allows |
 |---|---|
-| session | this exact call (tool + command, or paths) in this session |
+| session | this exact call in this session: the tool + command, or for a file tool its paths, so its label names them (`Allow edits to config.yml for the session`) and a later edit of that file needs no ask |
 | repo | this exact call in this repo (the cwd outside a repo), any session |
 | rule | anything this rule asks about in this repo |
 
@@ -234,6 +235,10 @@ other user-only rules (`chi-context-cmd`, `chi-broadcast`,
 `prompt-memory-write`, `model-overlay-write`, and `chi-answer-piped` /
 `chi-answer-http`, which answer a grandchild's question as the user).
 
+`child-boundary` isn't one of them: an ask before a delegate child acts outside
+its folder follows the level, so a `soft` parent may give Allow once. If that
+call names chi's own files, it is the user's as above.
+
 A plugin's or a hook's question (`ask_user`) tags its options the same way
 (`effects:`, see [Plugins](plugins.md)); an untagged one is a plain `answer`.
 

data/docs/internals/bridge.md

@@ -66,7 +66,9 @@ the "asking again" and steer-cut rows, ✂ rows and questions (with how they wer
 One per `GET /session/:id/stream` connection, and itself that connection's observer: `Engine#emit_event` calls
 `#call` on the turn's thread, so it only pushes onto a `BoundedQueue` (when full, the oldest entry goes and an
 overflow flag is set). The connection's own thread (`#serve!`) drains the queue onto the socket, so a slow client
-cannot stall a turn or another subscriber. `serve!` orders a join so that nothing is missed or doubled:
+cannot stall a turn or another subscriber. An event holding bytes JSON can't take goes out scrubbed
+(`SSEWriter#frame_json`, `LLM::Utf8Scrub`): a raise there would end this stream, and every later one for as long as the
+ring holds the event. `serve!` orders a join so that nothing is missed or doubled:
 
 1. subscribe the live queue first;
 2. capture `event_count` (the snapshot seq);

data/docs/internals/engine.md

@@ -805,7 +805,7 @@ Both loops:
   guessed from the block and it never enters the history (`:generation_completed`
   and `:after_generation` have already seen the text): `:generation_retrying` with `restarted` voids the streamed text, `:empty_answer_retry` with
   `malformed` goes out, and a hidden `TurnNote.malformed_retry` asks again at the retry temperature. It has its own budget, so `retry.empty_answer: 0`
-  doesn't turn it off, and a real tool call resets it. Two in a row fail the turn with `LLM::MalformedGeneration`, keeping its earlier steps. Each is
+  doesn't turn it off, and a real tool call resets it. Two in a row fail the turn with `LLM::MalformedGeneration`, keeping its earlier steps; a Stop that lands on a stray reply ends the turn cancelled, not failed, because a stopped turn skips this path. Each is
   logged as `generation_malformed` with the shape, finish reason, served model and the text's tail. `KernelLoop` has its own path (`ToolCallParser#malformed`).
 - **Empty-answer retry** (`EmptyAnswerRetry`): a generation with no visible text and no tool calls is asked
   again, up to `retry.empty_answer` times (at most 3), with a hidden nudge (`TurnNote.empty_retry`) on the tail.

data/docs/internals/web-frontend.md

@@ -23,7 +23,7 @@ page. A factory dep a new version stops passing is the same hazard the other way
 out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
 until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
 `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
-`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js` and `more_sheet.js` are new modules for that reason.
+`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep) and `worker_features.js` are new modules for that reason.
 
 ## Two pages, two models
 
@@ -152,7 +152,8 @@ restart's hub event that brings the feature enables it, the worker going (`worke
 it's unavailable. `forgetSession` and `renderSessionView` draw the history with the answer already, so they `prime()`
 the gates in the batch of their write, and nothing fires. Today two gates: `verify` (Verify fresh on a verdict's
 card, `redrawFresh`) and `revise` (the answers' Revise buttons and the composer's Revising chip, `redrawRevise`).
-Both refuse only a live worker without the feature: a worker that isn't up is woken by the send as a new one, which
+Both refuse only a live worker without the feature — `workerPredates(features, up, feature)` in
+`worker_features.js`, the rule both gates share: a worker that isn't up is woken by the send as a new one, which
 has it. A new action that needs a worker feature is one more entry.
 
 ### Exceptions

data/docs/memory.md

@@ -229,6 +229,8 @@ or trims them; chi measures them (tokens estimated as characters /
   `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`.
+- `chi memory usage` counts what the memories cost over the saved sessions: each scope's index tokens,
+  the memories read most, and the ones no session read (see [What the memories cost](#what-the-memories-cost)).
 - `/stats` has `memory index:     ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`,
   and the web's ctx tooltip (info bar and session card) the same line. It is
   what this session's prompt holds, measured when the prompt was built (after
@@ -282,6 +284,49 @@ every read. `chi self` has a `big memories` row instead: the memories over the l
 `config_modification_protocol` is over on every install; the fix is upstream's). This is how a
 memory already over the limit gets seen.
 
+## What the memories cost
+
+`chi memory usage [--scope project|system] [--top N] [--format text|json]` answers
+"where do my memories cost the most?" from the saved session files. It reads only: no
+writes, no model call, no grades, and no advice to delete anything. `chi self`'s `big memories`
+row still lists memories over `memory.entry_warn_tokens`; this is the other half — cost is
+size times reads, and a memory of 2k tokens read fifty times costs more than one of 8k read once.
+
+- **The header** says how many sessions were counted and the days they span, because retention
+  limits what can be seen: 14 days and 500 sessions by default, so "not read" means "not read
+  in the sessions still saved". Archived sessions count; test runs and sessions with no user
+  message do not, and the header says how many of those were left out. With nothing counted at
+  all, the line says what is in the dir instead of "nothing saved": the files that could not be
+  read and the sessions not counted.
+- **The indexes come first**, since both are sent with every prompt: their tokens (the same
+  figure `chi self` and `/stats` show), the `memory.index_warn_tokens` limit, and how many of
+  their *memory* lines name a memory no counted session read. The index's heading and a bold
+  line of prose are not memory lines, so they sit in neither the count nor its denominator.
+- **Most read, by tokens**: name, tokens, reads, the memory's size now (`-` when the line has no
+  file behind it), its scope, and `from <bundle>` for a bundle's memory (which the user cannot
+  tighten in place). The header of the section says what share the shown rows make of all read
+  tokens (`--top` caps the rows, 10 by default, at most 1000). If every read is of a name with
+  no memory now, the section says that instead of listing rows.
+- **Not read in saved sessions**: the count of the user's own memories no counted session read,
+  then the largest of them. A bundle's memories are not listed, and a memory the session was
+  started with (`--memory`, or config.yml's `memories:`) counts as used: the model has it in the
+  prompt without a read. A line says an index line is paid whether or not the memory is read, so
+  a never-read memory still costs its line.
+- Names read that no longer have a memory behind them are counted in one line, not as rows.
+
+A read is a `memory_read`, or a `read` of a memory's file, in either loop's saved shape (the chat
+loop's calls paired by `tool_call_id`, the native loop's call markup with one joined result). Its
+cost is the size of the result as it was saved — a cut result counts as it happened, a model overlay
+too, and `read`ing an overlay's file is a read of the memory it overlays — in tokens as the prompt
+estimates them (characters / `context.chars_per_token`). A comma list of names splits that one result
+by share, over every name asked for: `index` is not a row, but it is one of the names the share is
+worked out over. A project memory is credited only with the reads of
+sessions of this folder's project (worktrees of one repository share it); a system memory with every
+session's, whichever project they came from.
+
+Reads saved before whole reads hold cut results; when any counted read does, one line under "Most
+read" says so, since a big memory may cost more per read now than those numbers show.
+
 ## Skills
 
 A **skill** is a memory named `skill_<name>` that holds the steps of a

data/docs/sessions.md

@@ -452,7 +452,7 @@ mise.toml pins Ruby 3.4 gets that `ruby`, `gem` and `bundle` in its tools while
 The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `↑ <parent id>` in its info bar, its tooltip `delegated by session …`; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
 
 - `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one. The wait (`wait: true`, a later `delegate_result`) and the delegate report are for the reply of the child's turn the follow-up went to: its running turn, which it merges into, or the turn of its own it runs when the child is idle (`turn` in `delegates.json`, set when the child's worker names `turn_ids`), not a newer reply of a turn queued behind it. A follow-up merged as a steer into a turn the child started at that moment (a wake, a reminder, another message) gets that turn's reply or question. A child on its first turn, or with an older worker, gives its next reply, as before.
-- `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's.
+- `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's. With no `cwd:` and a task that names another checkout of the same repository (a path in the task belonging to a linked worktree, read from the files with `Guardrails::GitInfo.checkouts`, no git process), the result carries `Warning: this child runs in <folder>, but its task names <checkout>. If it should work there, stop it (chi sessions stop <id>) and call delegate again without session, with cwd: <checkout>.` One line however many are named; nothing for a path of the child's own checkout, a folder that isn't one, or a path with spaces. The child starts as it would anyway, and with `wait: true` (the default) the line comes after the child ran, so it only helps with `wait: false`. A `Warning:` for an unknown model id comes first, then this one. `Log.info(:worker, "delegate_other_checkout", parent:)` records each line.
 - `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one. After `wait: false` it isn't needed: the report brings the reply.
 - A wait also ends early when a person's message waits for the parent's turn's next step (the `task_wait` rule: `Engine#input_waiting?`, `SessionInbox.steer_waiting?`, never in a participant's turn): `ReplyWait`'s `message_waiting:` probe gives `:message_waiting`, checked after every outcome the child can arrive at (a reply, a question, an end, a gone worker) and a cancel, before the deadline, and the result says `no reply yet: a message from the user is waiting; the child keeps running. Read the message first.` with the same last line as a timeout's. The child is never touched, the cursor doesn't move (the reply still comes, as a report or at the next `delegate_result`), a relayed approval's outcome line stays in the result, and a reserved report reads as for a timeout. A delegate child's report doesn't end a wait. This holds for `delegate`'s own wait too (both go through `DelegateWait`).
 - A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.

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

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

data/lib/samagotchi/child_reports.rb

@@ -312,12 +312,12 @@ module Samagotchi
       own + strays
     end
 
-    # A second ring for a child taken earlier in this turn: read from where
-    # the first report left the cursor, keeping the first one's +before+.
+    # A second ring for a child taken earlier in this turn: this report's
+    # cursors (#report_for), both reports' rings.
     def merge_taken(earlier, report)
       return report unless earlier
 
-      report.with(before: earlier.before, rings: earlier.rings + report.rings)
+      report.with(rings: earlier.rings + report.rings)
     end
 
     # @return [Report, nil] nil when the child has nothing to report
@@ -325,7 +325,14 @@ module Samagotchi
       child = Session.load(child_id, state_dir: @state_dir)
       return nil unless child.parent_id == @session_id
 
-      before = @taken[child_id]&.after || Tools::DelegateCursors.get(@session_id, child_id, state_dir: @state_dir)
+      current = Tools::DelegateCursors.get(@session_id, child_id, state_dir: @state_dir)
+      earlier = @taken[child_id]
+      # Until the turn commits, the file holds the cursor from before the
+      # first report, plus its claim. A second ring reads on from where that
+      # report left it, and a commit moves on from the file's. If the model
+      # moved the cursor meanwhile (delegate_result), the file's is the truth.
+      kept = earlier && current.without_claim == earlier.before.without_claim ? earlier : nil
+      before = kept ? kept.after : current
       # A follow-up's turn (DelegateCursor#turn) is reported by its own
       # reply, as delegate_result takes it, not a newer queued turn's.
       wait = ReplyWait.call(child_id, state_dir: @state_dir, cursor: before.reply_file, baseline: before.baseline,
@@ -337,14 +344,14 @@ module Samagotchi
                                         turn: wait.status == :waiting_for_answer ? before.turn : nil)
                     .with_baseline(ReplyWait.baseline_of(wait.session))
       claim = Tools::ReportClaim.new(id: claim_id, file: wait.file, cursor: after)
-      return nil unless Tools::DelegateCursors.claim_report(@session_id, child_id, expected: before, claim: claim,
+      return nil unless Tools::DelegateCursors.claim_report(@session_id, child_id, expected: current, claim: claim,
                                                             state_dir: @state_dir)
 
       # A reported end is the follow-up turn's too (DelegateCursor#turn):
       # a later wait on it would repeat its reply.
       after = after.with(report_claim: claim)
       text = Tools::DelegateWait.finish(wait, child_id, timeout: 0, report: true)
-      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings, claim_id: claim_id,
+      Report.new(child_id: child_id, text: text, before: kept ? kept.before : before, after: after, rings: rings, claim_id: claim_id,
                  relay: relay?(wait) ? wait.question : nil)
     rescue ArgumentError
       nil # the child is gone

data/lib/samagotchi/guardrails/approval.rb

@@ -181,16 +181,17 @@ module Samagotchi
           return verdict.settle!(:deny, decided_by: "user", note: "The approval was cancelled.")
         end
 
+        who = answer.parent_agent? ? Verdict::PARENT_AGENT : "user"
         index = answer.selected_indices.first
         if index && index < scopes.size
-          verdict.settle!(:allow, decided_by: "user")
+          verdict.settle!(:allow, decided_by: who)
           verdict.scope = scopes[index]
           return verdict
         end
 
         freeform = answer.freeform.to_s.strip
-        note = freeform.empty? ? "The user declined this call." : "The user declined this call: #{freeform.inspect}."
-        verdict.settle!(:deny, decided_by: "user", note: note)
+        declined = "The #{who} declined this call"
+        verdict.settle!(:deny, decided_by: who, note: freeform.empty? ? "#{declined}." : "#{declined}: #{freeform.inspect}.")
       end
 
       # The rule's scopes; "rule" only when a rule id names what to approve.
@@ -206,12 +207,24 @@ module Samagotchi
         place = verdict.targets&.repo_root ? "in this repo (#{verdict.targets.repo_name})" : "in this directory"
         case scope
         when "once" then ONCE
-        when "session" then "Allow this call for the session"
+        when "session" then "Allow #{session_subject(verdict.targets)} for the session"
         when "repo" then "Allow this call #{place}"
         when "rule" then "Allow rule #{verdict.rule} #{place}"
         end
       end
 
+      # What a session answer covers, as Approvals.key_for keys it: a file
+      # tool's later calls on the same paths, else this one exact call.
+      def session_subject(targets)
+        return "this call" if targets.nil? || targets.command || targets.paths.empty?
+
+        what = targets.paths.one? ? File.basename(targets.paths.first) : "#{targets.paths.size} files"
+        "#{SESSION_VERBS.fetch(targets.tool, "#{targets.tool} on")} #{what}"
+      end
+
+      # How a session label names a file tool's calls.
+      SESSION_VERBS = { "edit" => "edits to", "write" => "writes to" }.freeze
+
       # How much of a plugin tool's arguments the question shows.
       ARGS_CHARS = 300
 

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -40,6 +40,10 @@ module Samagotchi
       # The guardrails bundle's ask before a memory removal: its paths are in
       # the config dir, yet a parent may answer it.
       MEMORY_REMOVE_RULE = "memory-remove"
+      # A delegate child's ask before it acts outside its folder. It carries
+      # the core source but isn't about chi's own files, so it follows the
+      # level like any other ask, unless it names them (#chi_files?).
+      CHILD_BOUNDARY_RULE = "child-boundary"
       # The guardrails bundle's shell-touches-chi, for a word it can't
       # resolve to a path (Guardrails::ShellPaths): CHI_TEXT and .git/hooks.
       CHI_SHELL_TEXT = Regexp.union(CHI_TEXT, %r{\.git/(?:modules/\S+/)?hooks})
@@ -68,7 +72,7 @@ module Samagotchi
         facts = ApprovalFacts.from_h(facts)
         return false if facts.nil?
         return true if PROTECTED_RULES.include?(facts.rule.to_s)
-        return true if facts.source.to_s == ProtectedPaths::SOURCE
+        return true if facts.source.to_s == ProtectedPaths::SOURCE && facts.rule.to_s != CHILD_BOUNDARY_RULE
         # A memory's file sits in the config dir, but removing one is the
         # memory-remove rule's ask, which a parent may answer.
         return false if facts.rule.to_s == MEMORY_REMOVE_RULE

data/lib/samagotchi/guardrails/verdict.rb

@@ -26,6 +26,8 @@ module Samagotchi
       PROTECTED_RULES = %w[chi-config chi-home chi-shim chi-hooks shell-touches-chi chi-context-cmd chi-broadcast prompt-memory-write
                            model-overlay-write chi-answer-piped chi-answer-http].freeze
       SCOPES = %w[once session repo rule].freeze
+      # Who answered an ask when it was a parent agent, not the user.
+      PARENT_AGENT = "parent agent"
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 
       attr_reader :decision, :reason, :rule, :source, :scopes, :decided_by
@@ -118,12 +120,12 @@ module Samagotchi
 
       # What the model gets for a deny (after the "[tool] Error: " prefix):
       # who decided, why, and not to route around it (or the voter's own
-      # advice). A user's deny leads with the user's answer, so it doesn't
-      # read as the rule refusing.
+      # advice). A deny on an ask leads with the answer, the user's or a
+      # parent agent's, so it doesn't read as the rule refusing.
       def deny_text
         reason = @reason.to_s.strip
         reason += "." unless reason.empty? || reason.match?(/[.!?]\z/)
-        parts = if @decided_by == "user" && @note
+        parts = if ["user", PARENT_AGENT].include?(@decided_by) && @note
                   [@note, "It needed approval (#{decider}):", reason]
                 else
                   ["denied by guardrail (#{decider}):", reason, @note || "The user was not asked."]

data/lib/samagotchi/memory_command.rb

@@ -5,42 +5,59 @@ require_relative "cli/command"
 require_relative "cli/exit"
 require_relative "cli/flags"
 require_relative "memory_paths"
+require_relative "system_prompt"
 require_relative "tools/memory"
 require_relative "memory_bundle/index_updater"
 require_relative "memory_bundle/provenance"
+require_relative "memory_usage"
 
 module Samagotchi
   # `chi memory`: the user's side of the memories (docs/memory.md). ls lists
   # both scopes' entries from their index.md lines and files, as memory_read
   # and the prompt see them; rm removes one as memory_write remove: true does
   # (Tools::MemoryWrite.remove: the file and its model overlays into the
-  # bundle trash, the index line dropped, a bundle's memory refused).
+  # bundle trash, the index line dropped, a bundle's memory refused); usage
+  # reports what the memories cost and what the saved sessions read
+  # (MemoryUsage, docs/memory.md "What the memories cost").
   class MemoryCommand
     include CLI::Command
 
     USAGE = <<~TEXT
-      Usage: chi memory <ls|rm> [options]
+      Usage: chi memory <ls|rm|usage> [options]
         ls [--scope project|system] [--format text|json]   the memories: both scopes (this folder's project
              first), or one; each with its size, date, the bundle it came from and its index description
         rm NAME [--scope project|system]   remove a memory: its file and its model overlays (NAME.<key>.md)
              move to the bundle trash (chi bundle trash lists and empties it) and its index line is dropped.
              Without --scope NAME must be in one scope only. A bundle's memory is refused: chi bundle
              uninstall removes it. NAME.<key> removes one model overlay alone.
+        usage [--scope project|system] [--top N] [--format text|json]   what the memories cost, counted from
+             the saved sessions: each scope's index tokens, the memories read most (by tokens), and the ones
+             no saved session read. --top is the rows per section (10, at most 1000); no sessions says so and exits 0.
     TEXT
 
-    SUBCOMMANDS = %w[ls rm].freeze
+    SUBCOMMANDS = %w[ls rm usage].freeze
     SCOPES = Tools::VALID_SCOPES
     # The description column's width in ls's text form (json has it all).
     DESCRIPTION_WIDTH = 60
     # ls's size column, right-aligned.
     SIZE_COLUMN = 2
+    # usage's rows per section, when --top is not given.
+    DEFAULT_TOP = 10
+    # The most rows --top may ask for: a report of more is unreadable, and a
+    # huge number used to raise out of Array#first.
+    TOP_LIMIT = 1000
 
     FLAGS = {
       "ls" => CLI::Flags.new(help: HELP_WORDS) do |f|
         f.value "--scope"
         f.value "--format"
       end,
-      "rm" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--scope" }
+      "rm" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--scope" },
+      "usage" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--scope"
+        f.value "--top"
+        f.value "--format"
+      end
     }.freeze
 
     # One memory of a scope. +date+ is the index line's (the file's mtime
@@ -94,7 +111,7 @@ module Samagotchi
       return [] unless File.directory?(dir)
 
       index_path = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
-      index_text = File.file?(index_path) ? File.read(index_path, encoding: "UTF-8") : ""
+      index_text = Tools::MemoryRead.read_text(index_path)
       # name => its line; the first one when a name has two. A name rm
       # would refuse (a path: "../x") isn't listed.
       lines = {}
@@ -191,6 +208,118 @@ module Samagotchi
 
     def clip(text) = text.length > DESCRIPTION_WIDTH ? "#{text[0, DESCRIPTION_WIDTH - 1]}…" : text
 
+    def run_usage(options, args)
+      return usage_error("usage takes no NAME (unexpected #{args.first})") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+      return usage_error("--top must be a positive integer") unless options[:top].nil? || options[:top].to_s.match?(/\A[1-9]\d*\z/)
+      return usage_error("--top must be at most #{TOP_LIMIT}") if options[:top].to_i > TOP_LIMIT
+
+      sessions, unreadable = MemoryUsage.load_sessions
+      report = MemoryUsage.new(
+        sessions: sessions, entries: self.class.entries(options[:scope]),
+        scopes: options[:scope] ? [options[:scope]] : SCOPES, unreadable: unreadable, root: Dir.pwd,
+        # config.yml's memories: plus the system memories every prompt carries
+        # (SystemPrompt::DEFAULT_SYSTEM_MEMORIES): both are in the prompt from
+        # the start, so no read is needed for them.
+        baseline: ConfigFile.preloaded_memories + SystemPrompt::DEFAULT_SYSTEM_MEMORIES
+      ).report(top: (options[:top] || DEFAULT_TOP).to_i)
+
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(report.to_h))
+      else
+        print_usage(report)
+      end
+      CLI::Exit::OK
+    end
+
+    def print_usage(report)
+      if report.sessions.zero?
+        why = []
+        why << "#{report.unreadable} #{report.unreadable == 1 ? "file" : "files"} that could not be read" if report.unreadable.positive?
+        why << "#{report.skipped} #{report.skipped == 1 ? "session" : "sessions"} not counted (test runs or no user message)" if report.skipped.positive?
+        @stdout.puts(why.empty? ? "no sessions to count: nothing saved in #{Session.default_state_dir}" : "no sessions to count: #{why.join(" and ")} in #{Session.default_state_dir}")
+        return
+      end
+
+      header = "#{report.sessions} #{report.sessions == 1 ? "session" : "sessions"} over " \
+               "#{report.days} #{report.days == 1 ? "day" : "days"}"
+      header += ", #{report.unreadable} unreadable #{report.unreadable == 1 ? "file" : "files"} skipped" if report.unreadable.positive?
+      header += ", #{report.skipped} #{report.skipped == 1 ? "session" : "sessions"} not counted (test run or no user message)" if report.skipped.positive?
+      @stdout.puts(header)
+      @stdout.puts
+
+      # The index comes first: it is paid on every prompt, reads only on a read.
+      print_table(["Indexes", "tokens", "limit", "index lines naming a memory no session read"],
+                  report.indexes.map do |index|
+                    [indent(index.scope), token_text(index.tokens), index.limit.positive? ? index.limit.to_s : "off",
+                     "#{index.unread_lines} of #{index.lines} (#{index.unread_percent}%)"]
+                  end, right: [1, 2])
+      @stdout.puts
+
+      if report.read_count.zero?
+        @stdout.puts("No memory reads in these sessions.")
+      elsif report.top.empty?
+        # Every read is of a name with no memory behind it: no rows to show.
+        @stdout.puts("Most read, by tokens: none of these reads names a memory still there " \
+                     "(#{report.unknown_names} #{report.unknown_names == 1 ? "name" : "names"} read, " \
+                     "#{token_text(report.read_tokens)} tokens)")
+      else
+        share = report.read_tokens.positive? ? (100.0 * report.top.sum(&:tokens) / report.read_tokens).round : 0
+        @stdout.puts("Most read, by tokens (these #{report.top.size} of #{report.read_names}: " \
+                     "#{share}% of #{token_text(report.read_tokens)} read tokens)")
+        print_table(%w[Memory tokens reads size scope from],
+                    report.top.map do |use|
+                      [indent(use.name), token_text(use.tokens), use.reads.to_s,
+                       size_text(use.size_tokens), use.scope, use.source.to_s]
+                    end, right: [1, 2])
+        if report.cut_reads.positive?
+          @stdout.puts(indent("note: #{report.cut_reads} of these reads came back cut (reads used to be cut), " \
+                              "so a big memory may cost more per read now than these numbers show"))
+        end
+      end
+      @stdout.puts
+
+      if report.not_read_total.zero?
+        @stdout.puts("Not read in saved sessions: nothing of your own to count (a bundle's memories are not listed)")
+      else
+        @stdout.puts("Not read in saved sessions: #{report.not_read_count} of #{report.not_read_total} of your own " \
+                     "memories (a bundle's are not listed)")
+        print_table(["", "size", "scope"], report.not_read.map { |entry| [indent(entry.name), size_text(entry.tokens), entry.scope] }, right: [1]) if report.not_read.any?
+        @stdout.puts(indent("An index line is paid whatever a session reads: a memory nobody opens still costs its line in every prompt."))
+      end
+
+      @stdout.puts(indent("Names read that have no memory now: #{report.unknown_names}")) if report.unknown_names.positive?
+    end
+
+    def indent(text) = "  #{text}"
+
+    # A token count as usage's columns show it: "450", "1.9k", "2.0M".
+    def token_text(value)
+      number = value.to_i
+      return number.to_s if number < 1000
+      return format("%.1fk", number / 1000.0) if number < 1_000_000
+
+      format("%.1fM", number / 1_000_000.0)
+    end
+
+    # A size column: "-" when the memory has no file to measure.
+    def size_text(tokens) = tokens.nil? ? "-" : token_text(tokens)
+
+    # A header row and its rows, two spaces apart; the +right+ columns align on
+    # their numbers.
+    def print_table(header, rows, right: [])
+      table = [header, *rows]
+      widths = table.transpose.map { |column| column.map { |cell| cell.to_s.length }.max }
+      table.each do |cells|
+        line = cells.each_with_index.map do |cell, index|
+          right.include?(index) ? cell.to_s.rjust(widths[index]) : cell.to_s.ljust(widths[index])
+        end
+        @stdout.puts(line.reject.with_index { |_, index| widths[index].zero? }.join("  ").rstrip)
+      end
+    end
+
     def run_rm(options, args)
       name = args.shift
       return usage_error("give the memory's NAME") unless name
@@ -229,9 +358,8 @@ module Samagotchi
 
     def present?(name, scope)
       dir = MemoryPaths.scope_dir(scope)
-      index = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
       File.file?(File.join(dir, "#{name}.md")) ||
-        (File.file?(index) && File.read(index, encoding: "UTF-8").match?(Tools::MemoryWrite.managed_pattern(name)))
+        Tools::MemoryRead.read_text(File.join(dir, "#{Tools::MEMORY_INDEX}.md")).match?(Tools::MemoryWrite.managed_pattern(name))
     end
   end
 end

data/lib/samagotchi/memory_paths.rb

@@ -51,6 +51,15 @@ module Samagotchi
       File.basename(common) == ".git" ? File.dirname(common) : common
     end
 
+    # The repository's common git dir of +cwd+ as an absolute real path (the
+    # same for every worktree of it), or nil outside any repository. Reads
+    # files only, no git process; #project_root turns it into a checkout
+    # folder, which a bare layout's container is not.
+    def common_git_dir(cwd = Dir.pwd)
+      gitdir = git_dir(cwd)
+      gitdir && File.realpath(common_dir(gitdir))
+    end
+
     # The top of the git work tree holding +cwd+: the directory with the
     # nearest .git (a linked worktree's own checkout, unlike #project_root);
     # nil outside any repository.