samagotchi 0.100.0 → 0.101.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10cafc8e1deb147528195213bd69b946f428918a8c344c57022b2c905cd2f4fb
-  data.tar.gz: 6b6764b06a4effc61ac2edd1d2221d7afd232b2a8ce3470f0b14280d3ded432d
+  metadata.gz: 6c75329bad389a0434a3f99db7d05d512a45864aa3ce08ecb8a6a7399bddbe33
+  data.tar.gz: c057af30d62ee4f72bf0b681c10edb0bd0bf5225e14a3e1470f4b0d726bbaf67
 SHA512:
-  metadata.gz: a4da078e7bb452a96fbc8d38f9565946fa12a3e3b8185e35f26032fcc2a3ae76249ec5ad7712dd12b74fec0f52db5fac7c03890f5074fca747985944b50f8e26
-  data.tar.gz: 3cc980b577869624c31a8c577b69612198569875d5c3b1e2f9070a4aebed2b5d4e6d4d29d44e25e56e2144b2346f4017352dca2e7a01b2898bc6fa5046b4459e
+  metadata.gz: d2324f636a992fe36e2c0250ed55cf979b574359fd7e0f67271ceaf8da0803ffd60fc70408d62c73af984a2f9310b6acbfef92bbaac61a6c272e20540e38c840
+  data.tar.gz: cffd6a4d948302b563f1e30cf5542be9db7e95a68cc07a97cdb2b81e008454f7fe605f8bb96946c6b43c0fccd1957d05ea764867fde4f976f4699f242d8897fe

data/CHANGELOG.md

@@ -8,6 +8,42 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.101.0] - 2026-10-22
+
+### Added
+
+- Web (experimental, off by default): the stage view's **working set**, which shows what defines the model's
+  context: the files it read or edited, the memories, the fetched URLs and the preloaded and muted memories. It
+  shows when each one came in, folded into a few lines beside the stage. It replaces the mem chip with
+  `● set N`, adds a footprint line under each finished turn, and opens a list whose step tags jump to the call.
+  Items say whether the model still has them: **stale** (faded) when the file changed after the model last saw it,
+  through `execute`, your editor or anything else (the model's own edits don't count); **forgotten** (struck)
+  when the LLM context strategy no longer sends any of it. Each row shows its size in tokens. Turn it on with
+  `web.working_set: true`, `chi web --web-working-set` or `?working_set=1`. See
+  [docs/cli.md](docs/cli.md#the-working-set).
+
+### Fixed
+
+- macOS: reading a host's API key from the Keychain can no longer hang chi past its 5 s deadline when starting
+  `security` stalls (a first run scanned by XProtect): chi warns and goes on without the key.
+
+Update with `chi update`.
+
+## [0.100.1] - 2026-10-22
+
+### Fixed
+
+- The web's `continue →` no longer takes a draft left over from another session (or the start page) as the new
+  link's first message: the opener goes in, and the toast's **Restore draft** brings the draft back. A draft written
+  in the continued session still stays.
+- work-cap 0.1.1: a changed `bundles: work-cap:` setting reaches a running session (the caps are resolved again when the
+  settings change; the state file still wins per meter), and an empty key (`tool_calls:` with no value) falls through to
+  `child:` / `default:` instead of reading as "off"; `off`, `false` and `0` stay an explicit no cap.
+- Web: a closed step's text in the history renders as markdown (with `web.markdown` on) and keeps its source refs,
+  live and after a reload, as the answer does.
+- A hook entry in config.yml's `hooks:` that isn't a mapping, or has no `path:`, warns naming it
+  (`hooks.before_turn[0]`) instead of vanishing; the event's other entries still load.
+
 ## [0.100.0] - 2026-10-22
 
 ### Added
@@ -3792,7 +3828,9 @@ 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.100.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.101.0...HEAD
+[0.101.0]: https://github.com/dm1try/samagotchi/compare/v0.100.1...v0.101.0
+[0.100.1]: https://github.com/dm1try/samagotchi/compare/v0.100.0...v0.100.1
 [0.100.0]: https://github.com/dm1try/samagotchi/compare/v0.99.0...v0.100.0
 [0.99.0]: https://github.com/dm1try/samagotchi/compare/v0.98.0...v0.99.0
 [0.98.0]: https://github.com/dm1try/samagotchi/compare/v0.97.0...v0.98.0

data/bin/chi

@@ -333,6 +333,7 @@ if options[:web]
   view = Samagotchi::Config.get("web.view")
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
                                       markdown: markdown, view: view, new_token: options[:new_token],
+                                      working_set: Samagotchi::Config.get("web.working_set"),
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
                                       editor: Samagotchi::Config.get("web.editor"))
 end

data/docs/architecture.md

@@ -431,7 +431,10 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
   `drawAsking(text, refs)`) pairs them on its raw draw and again after its markdown swap; the card pairs its
   question text and its kept reply (`question_cards.js`); the step's closed `.gen-text` takes them
   (`turn_view.js`; on a reload its `data-answer-at`, the message's `display_refs`) and `linkTextRefs` pairs it at
-  the turn's end and after a reload. A file ref outside the
+  the turn's end and after a reload. A closed step's text is markdown too with `web.markdown` on: a reload's
+  from its message's `html` (`turn_view.js` `textTemplate`), a live turn's from `POST /api/render` on its step's
+  first open after the turn's end (`markdown_place.js` `renderStepTexts`, which pairs its refs again after the
+  swap); the text as written stays on it as `data-copy-source` (`stepText`, a reloaded card's kept reply). A file ref outside the
   session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
   session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
   file ref is dropped rather than shown unchecked.
@@ -442,6 +445,12 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
   `turn_count`, when the page's merge came up short.
 - `?cards=1`: the cards, from `/tail`; the session file is only stat'ed for the 404.
 
+The stage view's working set (`web.working_set`) has its own read, `GET /api/sessions/:id/working_set`: the
+`WorkingSet` projection (`{items, at}`: each file, memory and URL live, stale or forgotten, with its tokens) of the
+worker's `/snapshot` messages, else the session file, under the session's LLM context strategy. Its live form is the
+`:working_set_updated` event. The page overlays it on the set it builds from its tool rows
+([internals/working-set.md](internals/working-set.md)).
+
 A worker without `/tail` (an older chi; `404 not_found`) is read through `/snapshot` in the same
 shape; any other failure (no worker, a 500, a timeout) reads the disk, trimmed to the newest
 turn's records.

data/docs/cli.md

@@ -15,6 +15,7 @@
 - `chi web --web-host lan` — the Web UI on your home network too, for your phone: a link with an access token and its QR code (see [chi web on your phone](#chi-web-on-your-phone)); `chi web --new-token` replaces the token
 - `chi web --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages, the stage's asking text and a resolved question card's reply
 - `chi web --web-view turn` — draw turns with the turn view (each turn as one block of steps, the running one at the bottom of the history) instead of the default stage view (the running turn pinned above the composer); `?view=stage|turn` on the page URL overrides it (see [Web views](#web-views))
+- `chi web --web-working-set` — the stage view's working set (experimental, off by default; `--no-web-working-set` turns a config's `web.working_set: true` off): what each turn brought into the model's context, in the stage and under each finished turn; `?working_set=1|0` on the page URL overrides it (see [The working set](#the-working-set))
 - `chi sessions list|stop|restart|archive|unarchive|delete|prune|clean|stats` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). `stats ID` prints a session's cost, tokens and progress (a live worker's `GET stats`, else its saved `analytics.json`; `--format json` one object) without running a model turn. A usage error (an unknown subcommand or flag, a flag missing its value, `stop`, `restart` or `delete` with no ids, a bad `list --format` or `--scope`, a `--days`, `--keep` or `--limit` that isn't a whole number) exits 2; an unknown or refused session exits 1
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi context <add|push|ls|show|refresh|rm|mute|unmute> …` — attach live external text to sessions (a command chi runs every so often, or text pushed in); the model gets a short note when it changes and reads it with `context_read`; `chi context add <URL>` attaches a GitHub PR with the github-pr bundle (see [Attached context](context.md))
@@ -956,6 +957,60 @@ steps saved before that have none, so they show no thinking. An `edit` or
 made (up to 120 lines or 8 KB), live and after a reload (see
 [Guardrails](guardrails.md#ask) for the diff an approval shows first).
 
+### The working set
+
+`web.working_set: true` (or `chi web --web-working-set`,
+`SAMAGOTCHI_WEB_WORKING_SET=true`; `?working_set=1` or `?working_set=0` on the
+page URL for one page load) shows, in the stage view, what a turn brought into
+the model's context: the files it read, edited or wrote, the memories it read
+or wrote and the URLs it fetched. Off by default while it is tried out; the
+turn view ignores it.
+
+- **The rail**, on the right of the stage's live slots: the running turn's set
+  in four lines, folded as it grows (files under one folder become
+  `…/web/public/ · 9 files ✎2`, memories `◆ 3 memories`, else `N files · K
+  dirs`), with the newest entries marked for a few seconds and the context
+  ring once its fill is known. It never changes the stage's height. Its `–`
+  folds it to one line (`SET 17 + ◆ name`), kept per browser; a click opens the
+  list. In a stage narrower than 760 px it is one line under the last calls;
+  on a phone it isn't shown.
+- **The footprint**, one line under each finished turn's block, live and after
+  a reload: `touched …/web/public/ · 4 files · ◆ 2 memories s2–10 · +1 url ·
+  edited 1`. A step tag (`s2`) goes to that call's row; the rest opens the
+  turn's list. A turn that touched nothing has none.
+- **The `set N` chip** in the session bar, in place of the `mem N` chip (whose
+  tooltip goes too): the session's whole set, preloaded (`--memory`) and muted
+  (`--mute`) memories included; its dot lights when the set changed since you
+  last opened it.
+- **The list** the three open (a bottom sheet on a phone): this turn or the
+  whole session, files grouped by folder (a group opens in place), memories
+  (used, preloaded, muted) and URLs, each with what was done to it (`read ×2`,
+  `read, edited`, `preloaded`) and a step tag (`s3`, `t2·s3` in the session's
+  scope, `prompt` for a preloaded memory) that goes to the call. A file opens
+  as its row's title does, a URL in a new tab.
+
+Only `read`, `edit`, `write`, `memory_read`, `memory_write` and `web_fetch`
+calls that succeeded count; files an `execute` touched don't.
+
+What the model still has of each item comes from chi, not the page, so it is
+the same live, after a reload and in every tab:
+- **stale** (faded): the file changed since the model last read, edited or
+  wrote it, whatever changed it (a later `execute` such as `sed` or `git
+  checkout`, your editor, another session). The model's own successful edit or
+  write doesn't make a file stale. Chi checks at each request and when you
+  open the list, so a file changed while the session sat idle shows stale on
+  opening it. A turn saved before chi kept that record shows its files live.
+- **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
+  [the forget layer](configuration.md#llm-context-the-forget-layer)). Lines a
+  forget kept count as still sent. Under `/llm-context strategy none` nothing
+  is cut, so a forgotten item is live again from the next request.
+
+The list says `stale` or `forgotten` in words with each row, and how many
+tokens its content costs as sent (`~1.2k`); a folded group shows its forgotten
+members as `✂n`, and a footprint adds `n forgotten`.
+
 ### Web annotate presets
 
 Selecting text in an answer, a thinking block, a tool row or one of your

data/docs/configuration.md

@@ -1689,6 +1689,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
 | `web.view` | `stage` | yes | How `chi web` draws a turn: `stage` (the running turn pinned above the composer) or `turn` (one block per turn in the history). See [CLI](cli.md#web-views). |
+| `web.working_set` | `false` | yes | The stage view's working set (experimental): the files, memories and URLs a turn brought into the model's context, in a rail in the stage, a footprint line under each finished turn and a `set N` chip in place of the mem chip. `?working_set=1` or `?working_set=0` on the page URL overrides it for that page load; the turn view ignores it. See [CLI: the working set](cli.md#the-working-set). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
 | `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
 | `history.file` | state dir | | Prompt history path, shared by the TUI and the web composer. |

data/docs/hooks.md

@@ -28,6 +28,8 @@ hooks:
 
 Each event key holds a list of entries. A `hooks:` that isn't a mapping, or an event key that isn't a list
 (`before_turn: guard.rb`), warns at each start and loads nothing for it; an empty key loads nothing, silently.
+An entry that isn't a mapping (`- guard.rb`) or has no `path:` warns the same way, naming it
+(`hooks.before_turn[0]`, counted from 0), and is skipped alone: the key's other entries load.
 
 ## Plugin Format
 

data/docs/internals/engine.md

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

data/docs/internals/working-set.md

@@ -0,0 +1,130 @@
+# The working set: what the model really has
+
+The stage view's working set (`web.working_set`, [cli.md](../cli.md#the-working-set)) shows the files, memories
+and URLs a session's tool runs brought into the model's context. The page builds the set itself from its tool rows
+(`working_set.js`, phase 1). The server says what the model still has of each item: **live**, **stale** (a file
+changed since the model last saw it) or **forgotten** (nothing of it is still sent), and its size in tokens. This
+page covers the server's side and how the page overlays it.
+
+## Stamps: `tool_stamps`
+
+`ToolRunner#run` stamps an ok `read`, `edit` or `write` (`result[:activity][:status] == "ok"`) with its file right
+after the call: `ToolRun#stamp`, `{path:, mtime_ns:, size:}`. The path is the one `FileRef.for` gives (the call's
+path against the session's folder, `File.expand_path`, no realpath). A stat that fails, or that isn't a file's (a
+directory), gives no stamp; nor does any other tool.
+
+Both `ToolResponse` shapes save the stamps as `tool_stamps`, one per run, read by the run's place
+(`ToolIds::Ref#run`):
+- `ToolResponse.joined` (the native loop's batch entry): `runs.map(&:stamp)`, only when one is non-nil, like
+  `tool_refs`.
+- `ToolResponse.single` (the chat loop's entry for one call): `[stamp]`, a one-stamp array like its `tool_ids`.
+
+`tool_stamps` is in `ToolResponse::SAVED_KEYS`, so `ChatLoop#plain` keeps it and no prompt or wire ever renders it
+(the exclusion specs: `spec/llm/chat_loop_spec.rb` "a file run's stamp", `spec/kernel_loop_spec.rb`). After a
+reload the stamp hashes have string keys; the projection reads both. A session saved before the stamps has none, so
+its files are never stale.
+
+The model's own successful `edit` or `write` stamps the file after it ran, so it never makes the file stale. Anything
+else that changes it does: a later `execute` (`sed`, `git checkout`), the user's editor, another session. A failed
+edit that changed the file anyway leaves the earlier stamp, so the file shows stale. On a filesystem with 1 s mtimes a
+same-size edit in the same second goes unseen (APFS keeps nanoseconds).
+
+## The projection: `WorkingSet.build`
+
+`Samagotchi::WorkingSet.build(conversation, cwd:, strategy:, stat: File.method(:stat))` (`lib/samagotchi/working_set.rb`)
+is pure and returns a `WorkingSet::Snapshot` (`items`, `at`: the conversation's size in entries, the web's ordering
+key). Each `WorkingSet::Item` is `kind` (`file`, `memory`, `url`), `key`, `state`, `tokens`, `ops`, `count` and
+`first_id` (the first run's ToolIds id).
+
+**Runs.** It pairs the runs twice with `LLMContextStale.paired_runs`: once on the stored conversation, once on what
+`LLMContextView.new(strategy:).messages(conversation)` sends (stubs keep their `[name]` lead, so they still pair).
+The two are matched by `ref.id`. The calls are the dispatched ones (`Tools::BuiltinCalls.build`), so aliases resolve
+as the loops resolve them. A run that doesn't pair (a "ran as:" corrected call, an output holding the run separator)
+is left out. So is a failed run (`LLMContextStale`'s rule: an `Error` after the `[name]` lead; a denied call's
+`Error:` too) and an interrupted one (`ToolResponse.interrupted_text?`).
+
+**Items** follow the page's `rowEntries`:
+- `read`, `edit` and `write` give a file, keyed by its `FileRef` path; `read` adds op `read`, `edit` and `write`
+  add op `edit`.
+- `memory_read` gives one memory per name (`Tools::MemoryRead.parse_names`; an empty name, the index listing, gives
+  none). A partial read ("a,b" where b is missing: the found bodies, then `Error: memory not found: b`) keeps the
+  found names only, and its tokens are split evenly among them.
+- `memory_write` gives the memory `call[:path]`, op `write`. A `remove: true` write stays in the set.
+- `web_fetch` gives the URL with its whitespace collapsed.
+
+**Tokens and forgotten.** Only content outputs (`read`, `memory_read`, `web_fetch`) carry tokens and decide
+forgotten. Their tokens are the sent text's length over `TokenUsage::CHARS_PER_TOKEN`, so a stub costs what the stub
+costs and kept lines count themselves. An image read counts its text only. `edit`, `write` and `memory_write`
+outputs are short confirmations whose content sits in the call's arguments, which no strategy cuts: they add ops
+and stamps, never tokens, and they never make an item forgotten.
+
+An item is **forgotten** when it has content outputs and none of them is still sent under the session's *current*
+strategy. A content output is still sent when:
+- its sent text equals the stored one, or the stored one with the forget layer's `[#id] ` after its lead;
+- no applied edit of a layer the strategy runs is saved on it (a staged edit doesn't count; an edit saved under a
+  strategy the session has since left, such as `/llm-context strategy none`, isn't sent, so the output is live
+  again);
+- it is a forget that keeps lines (`forget_outputs keep:`);
+- it is a stale stub an edit made ("superseded by a later edit", `llm_context.stale_edits`): the model wrote the
+  file, so what it has of it is current.
+
+A stale stub of an old read that a newer read superseded never strikes the file: the newer read is still sent. A file
+only edited or written is never forgotten.
+
+**Stale** is a file item whose latest run left a stamp, and whose file now differs from that stamp in mtime or size,
+or is gone. No stamp, live. A forgotten item stays forgotten whatever its file did.
+
+**Cost.** Two `paired_runs` walks, one view build and one stat per file item. A 500-message session builds in about
+10 ms on an M5 Ultra and 75 ms on a CI runner; `spec/working_set_spec.rb` only guards against a blow-up (< 400 ms).
+
+## Delivery
+
+**The event.** The Engine emits `{type: :working_set_updated, items:, at:}` (`Engine#emit_working_set`):
+- after each `:generation_started`, in `build_stream_event_handler`, from the running turn's conversation
+  (`Engine#live_conversation`, read on the turn's thread) under the turn's strategy
+  (`@kernel.turn_settings.llm_context`). Both loops start a generation after `apply_llm_context!`, so the set is
+  what that request sends;
+- once in `Engine#end_turn`, after `replace_session_messages` and before the end event, from the kept messages (the
+  turn-end apply has run by then).
+
+It is emitted only when the set differs from the last one emitted for the session (kept per session id), and never
+while the set is empty, so a tool-free turn on a fresh session emits nothing. It goes out whatever the web's flag;
+the Bridge (`ClientEvent.project`) passes it on unchanged, and the attached TUI ignores it.
+
+**The route.** `GET /api/sessions/:id/working_set` (`Web::App#handle_working_set`) answers the snapshot's `to_h`.
+With a live worker it builds from the worker's snapshot messages (as `handle_show` reads them, keys symbolized) and
+the worker's llm ctx chip. Without one it builds from the session file and its saved chip
+(`SessionSetting::LLM_CONTEXT`). The folder is the session's `working_directory`. A worker's snapshot holds the
+session's messages, not the running turn's, so a GET during a turn answers an older `at` than that turn's events,
+and the page keeps the events' set.
+
+## The page's overlay
+
+The page keeps its row-derived items and their `at` ordinals (the step tags' jump path), and overlays the server's
+`state` and `tokens` by key (`working_set.js overlay`):
+- files by absolute path (the row's `ref.path`; a title fallback won't match, so it stays live);
+- memories by name;
+- URLs by the row's key, which is its params preview with whitespace collapsed, cut at 80 characters with a "…".
+  The "…" is stripped and the rest is matched as a prefix of the server's URL.
+
+An item the server doesn't know yet (a running call) stays live. Known mismatch: live rows' refs resolve against the
+worker's `Dir.pwd` (a real path), the server against `working_directory`, so a session under `/tmp` can miss
+(`/private/tmp`).
+
+`working_set_view.js` keeps one server snapshot per session and takes a new one only when its `at` is at least the
+kept one's (`newerSnapshot`): a GET that answers after a newer event never wins. The page asks for it when it seeds a
+session's set (load, resync) and when the list opens (a file changed while the session sat idle). The stream handler
+passes `working_set_updated` to it, and does nothing when the flag is off. A new snapshot redraws:
+- the session bar's chip and the open list;
+- the footprints, in place (`refreshFootprints`, the same node; a `data-ws-sig` of the items' states skips an
+  unchanged one);
+- the rail (`onServer`, the stage's `scheduleRefresh`).
+
+A state is the item's state now, not when its turn ran. A state change never refolds and never moves a line: the
+rail's line key carries the label's state and its forgotten count, which are patched in place.
+
+**Looks** (design spec §3, §5): a stale line is faded (`opacity: .55`); a forgotten one is struck in `--text-faint`
+at `opacity: .5`. A group shows `✂n` for its forgotten members. It is struck only when all its members are
+forgotten, and faded when all are stale or forgotten (`groupState`). The list's ops text says `stale` or `forgotten`
+in words (colour is never alone) and shows `~1.2k` tokens per row (`tokensText`). A footprint adds `n forgotten`,
+struck. Titles add `(stale)` or `(forgotten)` per member.

data/docs/sessions.md

@@ -237,7 +237,7 @@ A session can **continue** an earlier one: "the next run of the same routine" (a
 - **If the continue fails part-way:** a new link that fails to start gives its moved delegates back before it is deleted (each gets a note saying so; its worker is stopped first, if one started, and a worker that won't stop is reported, the link left), with any report one of them rang it with meanwhile; the previous link, back in the lists, is woken for reports waiting. A continue that dies in the middle leaves a `move.json` in the new link's folder: the new link's next worker finishes that move (only the delegates it names, and without a second note to one already told) as it starts. Until the new link's own worker holds it, a ring from a moved delegate doesn't start another (a `starting` marker in its folder, which that worker removes; a stale one, over 60 s old or from a process that is gone, is ignored). An open delegate below an archived delegate refuses the continue (`under archived …`): unarchive that one, or archive this one.
 - **Refused too:** a link that is continued already (naming the link that continues it; continue that one, or `last:<id>`), a previous link whose folder is gone, and one whose model's host can't run it when no default model is configured to fall back to. A refusal starts nothing and archives nothing; a new link that fails to start puts back what was archived. Every refusal that can be known up front (the archive's ones included) comes before the recap wait. One continue of a session runs at a time (a lock in its folder; other chains don't wait), so a double click finds the first one's link and is refused, while a `last:<id>` continue that waited follows the chain to its new end.
 - **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context` or `thinking` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none), and `opener`: the previous link's first typed message, in full, when that link continues one itself (`null` otherwise: a chain's first link's first message is its task); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
-- **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with an opener in the composer, not sent (a draft already there stays instead): the previous link's own first typed message when that link continues one (the 201's `opener`; a `!shell` line isn't taken), else `Continue where we left off.`. So whatever you sent on the last link comes back on the next one, and editing it once changes it for every later link; the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. When the previous link's model's host is gone the link starts on the default model and the toast carries the server's `model_warning` too, and then stays until closed. A fresh link (one with no turn yet, however it was made: `continue →`, `chi send --new --continues`, a reload) shows the model picker in its composer with the link's model, until its first turn starts (a failed or canceled first turn ends it too); a pick runs `/model <name>` in the link (a command bubble; the info bar follows) and changes neither the start page's remembered model nor its Recent list, and a Send right after it waits for the `/model` to be taken. A link a chi REPL owns, or one continued already, shows none. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `open in a chi REPL; close it there`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its id, its full start (`2026-10-10 14:32`) and its preview in the tooltip; a neighbour that started on the open link's own day shows its time instead (`← 09:12`, `14:32 →`). A link made by `continue →` inherits the previous link's preview (and its title, if it has one) when it is created, so its card keeps its chain's title whatever opener it is sent, and its top bar and browser tab show its card's title. A link whose title is the opener and nothing else (a `chi send --new --continues` link whose first message is `Continue where we left off.`) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ #N` chip (`#N of M` when later links aren't listed; its tooltip `Session chain: link N of M`) opens a popover of the other links, newest first (`#N`, its date, with its time (`2026-10-17 14:32`) when another link of the chain started the same day, its own title when it differs from the card's (a link inherits its chain's, so mostly it doesn't), else its recap's first sentence, else its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or "include archived" is on: every link is a card of its own then, its chip `#N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
+- **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with an opener in the composer, not sent (a draft written in this session stays instead; one carried over from another session or the start page gives way to the opener, and the toast's **Restore draft** brings it back): the previous link's own first typed message when that link continues one (the 201's `opener`; a `!shell` line isn't taken), else `Continue where we left off.`. So whatever you sent on the last link comes back on the next one, and editing it once changes it for every later link; the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. When the previous link's model's host is gone the link starts on the default model and the toast carries the server's `model_warning` too, and then stays until closed. A fresh link (one with no turn yet, however it was made: `continue →`, `chi send --new --continues`, a reload) shows the model picker in its composer with the link's model, until its first turn starts (a failed or canceled first turn ends it too); a pick runs `/model <name>` in the link (a command bubble; the info bar follows) and changes neither the start page's remembered model nor its Recent list, and a Send right after it waits for the `/model` to be taken. A link a chi REPL owns, or one continued already, shows none. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `open in a chi REPL; close it there`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its id, its full start (`2026-10-10 14:32`) and its preview in the tooltip; a neighbour that started on the open link's own day shows its time instead (`← 09:12`, `14:32 →`). A link made by `continue →` inherits the previous link's preview (and its title, if it has one) when it is created, so its card keeps its chain's title whatever opener it is sent, and its top bar and browser tab show its card's title. A link whose title is the opener and nothing else (a `chi send --new --continues` link whose first message is `Continue where we left off.`) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ #N` chip (`#N of M` when later links aren't listed; its tooltip `Session chain: link N of M`) opens a popover of the other links, newest first (`#N`, its date, with its time (`2026-10-17 14:32`) when another link of the chain started the same day, its own title when it differs from the card's (a link inherits its chain's, so mostly it doesn't), else its recap's first sentence, else its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or "include archived" is on: every link is a card of its own then, its chip `#N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
 - **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT]` (see *Starting a session*).
 - **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain.
 

data/docs/testing.md

@@ -34,7 +34,7 @@ exception's text changes between Ruby versions: write the string yourself).
 The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
-`chains.js`, `unqueue.js`, `toasts.js`, `notice_links.js`, `start_page.js`, `session_actions.js`, `send_turn.js`, `dock_reserve.js`,
+`chains.js`, `working_set_view.js`, `working_set_rail.js`, `unqueue.js`, `toasts.js`, `notice_links.js`, `start_page.js`, `session_actions.js`, `send_turn.js`, `dock_reserve.js`,
 `vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a devDependency only,
 never shipped; lit reads `document` as it loads). The shim's `markupOf(template)`,
 `htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments; the DOM writes text with only `&`, `<`, `>`

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

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

data/lib/samagotchi/bundles/work-cap/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: work-cap
-version: 0.1.0
+version: 0.1.1
 scope: system
 description: "A per-session work cap (tool calls, active minutes) across turns: at a cap the turn pauses on Continue (another cap's worth) / Stop with the session's totals, a warning at 80% goes to the user only; /workcap shows or sets it"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:d4de4b835d1657223517f3d6a5d8a9b089b7c8fad08ed077f72748369323bd65
+  sha256: sha256:f4ce7ea7f5801490a29e232c41c7bca2007c140d21f1a78bbfb60e6b6fd4f64b
 # ask_user's effects: are in chi 0.92.0; ctx.usage is new in the next chi
 requires_chi: ">= 0.100.0"
 # chi --set work-cap.tool_calls=400 / work-cap.minutes=60: the session's own caps, a number or off

data/lib/samagotchi/bundles/work-cap/plugin.rb

@@ -12,9 +12,10 @@
 # prompt text. cost-cap (the $ cap) is its sibling; the wordings follow it.
 #
 # Settings (config.yml, bundles: work-cap:), from ctx.settings, never at
-# load: the caps are resolved once per session (see State below), so a
-# config change reaches a running session through /workcap or a new
-# session; warn_at and ignore_tools are read at each check.
+# load: the caps are resolved once per session and settings (see State
+# below), again when ctx.settings changes, so a config change reaches a
+# running session (the state file still wins per meter); warn_at and
+# ignore_tools are read at each check.
 #   tool_calls: 400   this session's own tool-call cap (session_settings:,
 #                     chi --set work-cap.tool_calls=400); 0/off: none
 #   minutes: 60       this session's own cap on active minutes, same rules
@@ -26,8 +27,10 @@
 #                     tools whose calls and time aren't counted (waiting:
 #                     delegate blocks on its child by default)
 # Each meter resolves on its own: its own value, else child:'s for a
-# delegate, else default:'s. A value that doesn't read (tool_calls: many)
-# warns the user once and the next one is used, never a silent "no cap".
+# delegate, else default:'s. An empty key (YAML nil) is unset and falls
+# through; off, false and 0 are an explicit "no cap". A value that doesn't
+# read (tool_calls: many) warns the user once and the next one is used,
+# never a silent "no cap".
 #
 # What counts: ctx.usage's tool calls and active time (generations plus
 # finished tool calls, never a question's wait), less ignore_tools'.
@@ -36,8 +39,8 @@
 # "step": 400}, "minutes": {"cap": null}}, written by /workcap and by
 # Continue; a meter's "cap": null is off for the session, over the config;
 # a meter missing from the file comes from the settings. Resolved once per
-# session id (ctx.delegate? parses the session file) and kept until
-# /workcap or Continue writes a new one.
+# session id and settings (ctx.delegate? parses the session file) and kept
+# until /workcap or Continue writes a new file, or the settings change.
 require "json"
 require "fileutils"
 
@@ -57,7 +60,7 @@ class Plugin
 
   def initialize(_settings)
     @mutex = Mutex.new
-    @resolved = nil        # {session:, meters: {meter => {cap:, step:, key:}}, unreadable: {name => value}}
+    @resolved = nil        # {session:, settings:, meters: {meter => {cap:, step:, key:}}, unreadable: {name => value}}
     @warned = {}           # meter => [session id, cap] the share warning was given for
     @unread_warned = nil   # the session id the "isn't a number" notice was given for
   end
@@ -101,7 +104,8 @@ class Plugin
   def self.float_text(text) = text.sub(/\.(?=e|\z)/i, ".0")
 
   # Whether +value+ reads as a cap or as none: a number (text too), off,
-  # false or nil; not "many", true or a list.
+  # false or nil (nil is unset, not none: #first_readable skips it); not
+  # "many", true or a list.
   def self.readable?(value, meter)
     case value
     when false, nil then true
@@ -269,16 +273,17 @@ class Plugin
 
   # The session's caps now: per meter the state file's, else the session's
   # own value (--set), else child:'s for a delegate, else default:'s.
-  # Cached per session id.
+  # Cached per session id and settings (a config change resolves again).
   def resolve(ctx)
     session = ctx.session_id
+    settings = ctx.settings
     cached = @mutex.synchronize { @resolved }
-    return cached if cached && cached[:session] == session
+    return cached if cached && cached[:session] == session && cached[:settings] == settings
 
     saved = state(ctx, session)
     configured = configured(ctx)
     meters = METERS.to_h { |meter| [meter, saved[meter] || configured[:meters][meter]] }
-    resolved = { session: session, meters: meters, unreadable: configured[:unreadable] }
+    resolved = { session: session, settings: settings, meters: meters, unreadable: configured[:unreadable] }
     @mutex.synchronize { @resolved = resolved }
   end
 
@@ -301,9 +306,9 @@ class Plugin
   end
 
   # Per meter the first of its own value, child:'s (a delegate's) and
-  # default:'s that is set and reads (.readable?); the ones set that don't
-  # read (and a child:/default: that isn't a mapping) are kept for the
-  # notice (#unreadable).
+  # default:'s that is set (an empty key, nil, isn't) and reads
+  # (.readable?); the ones set that don't read (and a child:/default: that
+  # isn't a mapping) are kept for the notice (#unreadable).
   def configured(ctx)
     settings = ctx.settings
     unreadable = {}
@@ -327,6 +332,8 @@ class Plugin
       next unless values.key?(meter)
 
       value = values[meter]
+      next if value.nil?
+
       unless self.class.readable?(value, meter)
         unreadable[name] = value
         next
@@ -360,12 +367,15 @@ class Plugin
       {}
     end
     saved = {} unless saved.is_a?(Hash)
-    saved[meter] = data
+    saved[meter] = data.transform_values { |value| whole(value) }
     Samagotchi::AtomicFile.write(path, "#{JSON.generate(saved)}\n")
     # Resolved again at the next use, from the file now holding the meter.
     @mutex.synchronize { @resolved = nil }
   end
 
+  # 800.0 as 800 (a whole cap is saved as an Integer), 2.5 as it is.
+  def whole(value) = value.is_a?(Float) && value.finite? && value == value.to_i ? value.to_i : value
+
   def state_path(ctx, session) = File.join(ctx.data_dir, "sessions", "#{session.gsub(/[^A-Za-z0-9_.-]/, "_")}.json")
 
   def count(value) = self.class.count(value)

data/lib/samagotchi/config.rb

@@ -289,6 +289,9 @@ module Samagotchi
       Entry.new(key: "web.markdown",             yaml_path: %w[web markdown],             type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
       # The page's view of a turn: stage (the running turn pinned above the composer) or turn (one block of generations, the live one at the bottom); ?view= overrides it per page load.
       Entry.new(key: "web.view",                 yaml_path: %w[web view],                 type: :enum,    default: "stage",        expose: %i[env config cli], enum_values: %w[stage turn], lifecycle: :web_start),
+      # The stage view's working set (files, memories and URLs the turn brought into context): a rail in the stage, a
+      # footprint under each finished turn and a "set N" chip in place of the mem chip; ?working_set=1|0 overrides it per page load.
+      Entry.new(key: "web.working_set",          yaml_path: %w[web working_set],          type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
       # Quick replies next to Annotate in the page's selection bubble, "|"-separated (a YAML list works too); "" leaves only Annotate.
       Entry.new(key: "web.annotate_presets",     yaml_path: %w[web annotate_presets],     type: :string, default: "Agreed|Could you please elaborate?", expose: %i[env config cli], lifecycle: :web_start),
       # What a file ref (a tool row's file, a diff line) opens on this machine: a preset (vscode, vscode-insiders, cursor, zed, none) or a URL template with {path} and an optional {line} (Web::Editor).

data/lib/samagotchi/engine.rb

@@ -84,6 +84,7 @@ require_relative "relay_desk"
 require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
 require_relative "prompt_warmup"
+require_relative "working_set"
 
 module Samagotchi
   # Engine owns the core agent logic: system prompt construction, tool
@@ -1459,6 +1460,7 @@ module Samagotchi
       synchronize_events do
         kept, event = yield(seconds)
         replace_session_messages(turn.session, kept) if kept
+        emit_working_set(turn.on_event, turn.session, turn.session.messages)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
@@ -2835,11 +2837,39 @@ module Samagotchi
 
         event = with_generation_report(event) if event[:type] == :generation_completed
         emit_event(on_event, event)
+        # What this request sends: both loops start a generation after
+        # their apply_llm_context!.
+        emit_working_set(on_event, @session, live_conversation) if event[:type] == :generation_started
         watch.feed(**progress) if watch && progress
         @thinking_notices.generation_completed(event) if event[:type] == :generation_completed
       end
     end
 
+    # The working set (WorkingSet) as the model has it, as a
+    # :working_set_updated event ({items:, at:}): at each request (the
+    # stream handler's :generation_started, from the running turn's
+    # conversation) and at turn end (#end_turn, from the session's kept
+    # messages). Only when it differs from the last one emitted for this
+    # session, and never while it is empty, so a tool-free turn emits
+    # none. The web overlays it on the rows' set; other UIs ignore it.
+    def emit_working_set(on_event, session, conversation)
+      return unless session && conversation
+
+      llm_context = @kernel.respond_to?(:turn_settings) ? @kernel.turn_settings&.llm_context : nil
+      snapshot = WorkingSet.build(conversation, cwd: session.working_directory,
+                                                strategy: llm_context&.strategy || LLMContextView::NONE)
+      return if snapshot.empty?
+
+      items = snapshot.items.map(&:to_h)
+      return if @working_set_emitted == [session.id, items]
+
+      @working_set_emitted = [session.id, items]
+      emit_event(on_event, { type: :working_set_updated, items: items, at: snapshot.at })
+    rescue StandardError => e
+      Log.warn(:turn, "working_set_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+    end
+    private :emit_working_set
+
     # A :generation_completed with the generation's decode speed (`speed:`
     # {decode_tps:, source:}, nil without one), the session's running
     # token totals (`tokens:`, the snapshot's block) and its per-model rows

data/lib/samagotchi/hooks/loader.rb

@@ -110,8 +110,8 @@ module Samagotchi
             next
           end
 
-          configs.each do |cfg|
-            next unless cfg.is_a?(Hash) && cfg["path"]
+          configs.each_with_index do |cfg, index|
+            next unless valid_entry?(event_type, cfg, index)
 
             definitions << {
               event_type: event_type.to_s,
@@ -125,6 +125,21 @@ module Samagotchi
         definitions
       end
 
+      # A hook entry is a mapping with a path:; anything else warns, naming
+      # the entry (hooks.EVENT[N], from 0), and is skipped alone.
+      def self.valid_entry?(event_type, cfg, index)
+        where = "hooks.#{event_type}[#{index}]"
+        unless cfg.is_a?(Hash)
+          Log.warn(:hooks, "hooks_entry_invalid", echo: "[samagotchi:hooks] config.yml #{where}: must be a mapping with a path:; ignored", event: event_type.to_s, index: index)
+          return false
+        end
+        return true if cfg["path"].is_a?(String) && !cfg["path"].strip.empty?
+
+        Log.warn(:hooks, "hooks_entry_no_path", echo: "[samagotchi:hooks] config.yml #{where}: has no path:; ignored", event: event_type.to_s, index: index)
+        false
+      end
+      private_class_method :valid_entry?
+
       # Load a plugin from the hooks directory.
       # Returns an instance of the plugin class. Instances are cached per
       # [path, settings] across Engines: two entries with different