samagotchi 0.100.1 → 0.101.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47dbac4f107af7d9c7d9d571b907a1e9e777326732614ed34986f2dce954168a
-  data.tar.gz: 4335f033596dc75f3db80b754a347e36862d0fd07f1d72bafcc7a5c50ed539ff
+  metadata.gz: 6c75329bad389a0434a3f99db7d05d512a45864aa3ce08ecb8a6a7399bddbe33
+  data.tar.gz: c057af30d62ee4f72bf0b681c10edb0bd0bf5225e14a3e1470f4b0d726bbaf67
 SHA512:
-  metadata.gz: a2454b93c9271b14ba0349c2991f6b0312dfdee76fd6a90005feb38726025dad71b6b4f1701bcbb2622c3db786d86fe2e58636668aa2f7d43d0ac289cae36e5a
-  data.tar.gz: 8fef8d270b58719f286b57c840f1a5fc3a53de10fec01fdcc08ea3de1315de17d267a834759b05ae09c05ca80b8f27009329eb38ff0aaf9a7b6ab59585b3e1d3
+  metadata.gz: d2324f636a992fe36e2c0250ed55cf979b574359fd7e0f67271ceaf8da0803ffd60fc70408d62c73af984a2f9310b6acbfef92bbaac61a6c272e20540e38c840
+  data.tar.gz: cffd6a4d948302b563f1e30cf5542be9db7e95a68cc07a97cdb2b81e008454f7fe605f8bb96946c6b43c0fccd1957d05ea764867fde4f976f4699f242d8897fe

data/CHANGELOG.md

@@ -8,6 +8,27 @@ 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
@@ -3807,7 +3828,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.100.1...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

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

@@ -445,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/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/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.1
+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/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/host_keys.rb

@@ -21,16 +21,22 @@ module Samagotchi
     # Reads one generic password through /usr/bin/security (by absolute
     # path: the helper's PATH isn't the shell's) in its own process group,
     # killed at the deadline: a locked keychain or an access dialog must not
-    # hang a turn. nil on a miss, a non-zero exit, a timeout, no binary, or
-    # off macOS.
+    # hang a turn. The deadline covers the spawn too (macOS can hold a first
+    # exec for minutes while it scans the binary): the run is a thread the
+    # caller gives up on, and a pid that turns up late is killed and reaped
+    # there. nil on a miss, a non-zero exit, a timeout, no binary, or off
+    # macOS.
     class Keychain
       SECURITY = "/usr/bin/security"
       TIMEOUT = 5
 
-      def initialize(security: SECURITY, timeout: TIMEOUT, host_os: RbConfig::CONFIG["host_os"])
+      # +spawner+: how the run starts (Process.spawn's arguments; specs stall it).
+      def initialize(security: SECURITY, timeout: TIMEOUT, host_os: RbConfig::CONFIG["host_os"],
+                     spawner: Process.method(:spawn))
         @security = security
         @timeout = timeout
         @macos = host_os.to_s.include?("darwin")
+        @spawner = spawner
       end
 
       # @return [String, nil]
@@ -45,33 +51,44 @@ module Samagotchi
       private
 
       def run(name)
-        reader, writer = IO.pipe
-        pid = Process.spawn(@security, "find-generic-password", "-s", SERVICE, "-a", name, "-w",
-                            in: File::NULL, out: writer, err: File::NULL, pgroup: true)
-        writer.close
-        waiter = Process.detach(pid)
-        unless waiter.join(@timeout)
-          stop(pid, waiter)
-          Log.warn(:config, "keychain_timeout", name: name, seconds: @timeout)
-          return nil
+        lock = Mutex.new
+        pid = nil
+        late = false
+        worker = Thread.new do
+          Thread.current.report_on_exception = false
+          security(name) { |spawned| lock.synchronize { late ? stop(spawned) : pid = spawned } }
         end
-        return nil unless waiter.value.success?
+        return worker.value if worker.join(@timeout)
 
-        key = reader.read.to_s.chomp
-        key.strip.empty? ? nil : key
+        lock.synchronize do
+          late = true
+          stop(pid) if pid
+        end
+        Log.warn(:config, "keychain_timeout", name: name, seconds: @timeout)
+        nil
       rescue SystemCallError
         nil
+      end
+
+      # One run, start to reap; yields the pid as soon as there is one.
+      def security(name)
+        reader, writer = IO.pipe
+        pid = @spawner.call(@security, "find-generic-password", "-s", SERVICE, "-a", name, "-w",
+                            in: File::NULL, out: writer, err: File::NULL, pgroup: true)
+        writer.close
+        yield pid
+        key = reader.read.to_s.chomp
+        _, status = Process.wait2(pid)
+        status.success? && !key.strip.empty? ? key : nil
       ensure
         writer&.close unless writer&.closed?
         reader&.close
       end
 
-      def stop(pid, waiter)
+      def stop(pid)
         Process.kill(:KILL, -pid)
       rescue SystemCallError
         nil
-      ensure
-        waiter.join(1)
       end
     end
 

data/lib/samagotchi/testing/fake_executable.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "tmpdir"
 
 module Samagotchi
   module Testing
     # Fake commands for a test's PATH (Sandbox#fake_executable), cheap to
     # exec: macOS checks a new executable file on its first exec (about
-    # 0.5–1 s, once per file). A fake is a symlink to one launcher, made
-    # once per process, that runs the fake's body (<name>.sh beside the
-    # link) with /bin/sh: writing a new body costs nothing.
+    # 0.5–1 s, once per file; minutes on a busy machine). A fake is a
+    # symlink to the checked-in launcher, which runs the fake's body
+    # (<name>.sh beside the link) with /bin/sh: writing a new body costs
+    # nothing.
     module FakeExecutable
-      LAUNCHER = "#!/bin/sh\nexec /bin/sh \"$0.sh\" \"$@\"\n"
+      LAUNCHER = File.expand_path("fake_executable_launcher", __dir__)
 
       module_function
 
@@ -26,17 +26,7 @@ module Samagotchi
         path
       end
 
-      def launcher
-        @launcher ||= begin
-          dir = Dir.mktmpdir("chi-fake-exec")
-          owner = Process.pid
-          at_exit { FileUtils.rm_rf(dir) if Process.pid == owner }
-          File.join(dir, "launcher").tap do |path|
-            File.write(path, LAUNCHER)
-            File.chmod(0o755, path)
-          end
-        end
-      end
+      def launcher = LAUNCHER
     end
   end
 end

data/lib/samagotchi/testing/fake_executable_launcher

@@ -0,0 +1,6 @@
+#!/bin/sh
+# What every FakeExecutable (and spec/support/fake_executables.rb) fake
+# links to: runs the fake's body, <link>.sh, with /bin/sh. Checked in, not
+# written per process: macOS scans a just-written executable at its first
+# exec, which under a busy run can stall for minutes.
+exec /bin/sh "$0.sh" "$@"

data/lib/samagotchi/tool_response.rb

@@ -10,10 +10,11 @@ module Samagotchi
   module ToolResponse
     SEPARATOR = "\n\n---\n\n"
     # Saved with a result for the web's reload (a plugin tool's params line,
-    # label and row refs, an edit/write's diff) and for the LLMContextView (each
+    # label and row refs, an edit/write's diff), for the LLMContextView (each
     # run's chi-owned id, ToolIds, and a strategy's edits by id,
-    # LLMContextEdit); the prompt never renders them.
-    SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_refs tool_ids edits].freeze
+    # LLMContextEdit) and for WorkingSet (a file run's stamp, ToolRun#stamp);
+    # the prompt never renders them.
+    SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_refs tool_ids tool_stamps edits].freeze
     # The tools a chat result loaded (#single), saved with it.
     LOADED = :loaded
     # A run's "[name]" lead: the name, then a newline, a space or the end.
@@ -84,7 +85,7 @@ module Samagotchi
         entry[:image_counts] = runs.map { |run| Array(run.images).size }
       end
       saved = { tool_params: runs.map(&:shown_params), tool_labels: runs.map(&:shown_label),
-                tool_diffs: runs.map(&:diff), tool_refs: runs.map(&:refs) }
+                tool_diffs: runs.map(&:diff), tool_refs: runs.map(&:refs), tool_stamps: runs.map(&:stamp) }
       saved.each { |key, values| entry[key] = values if values.any? }
       entry[:tool_ids] = ids
       entry
@@ -92,8 +93,10 @@ module Samagotchi
 
     # The chat loop's entry for one call: its capped output, paired with the
     # call by +tool_call_id+, and its chi-owned id (a one-id +ids+, as
-    # #joined's tool_ids); a find_tools hit's +loaded+ names (saved on every
-    # chat backend: a wire that loads tools renders them, LLM::AnthropicWire).
+    # #joined's tool_ids) and its stamp (a one-stamp tool_stamps, likewise:
+    # read by the run's place); a find_tools hit's +loaded+ names (saved on
+    # every chat backend: a wire that loads tools renders them,
+    # LLM::AnthropicWire).
     def single(run, tool_call_id:, ids:)
       entry = { role: "tool_response", content: run.capped_output, tool_call_id: tool_call_id }
       entry[:images] = run.images if run.images&.any?
@@ -102,6 +105,7 @@ module Samagotchi
       entry[:tool_diffs] = run.diff if run.diff
       entry[:tool_refs] = run.refs if run.refs
       entry[:tool_ids] = ids
+      entry[:tool_stamps] = [run.stamp] if run.stamp
       entry[LOADED] = run.loaded if run.loaded&.any?
       entry
     end

data/lib/samagotchi/tool_runner.rb

@@ -3,6 +3,7 @@
 require_relative "tool_activity"
 require_relative "tool_row_fields"
 require_relative "row_refs"
+require_relative "file_ref"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
@@ -18,12 +19,14 @@ module Samagotchi
   # One call's result from ToolRunner#run, read by ToolResponse (the loops'
   # tool_response entries) and the loops' activity list. Fields a call didn't
   # produce (images, shown_params, shown_label, refs, diff, output_file,
-  # loaded) are nil. +loaded+: the tools a find_tools hit loads
-  # (Tools::ToolIndex::FoundText#loaded), by their wire names.
+  # loaded, stamp) are nil. +loaded+: the tools a find_tools hit loads
+  # (Tools::ToolIndex::FoundText#loaded), by their wire names. +stamp+: an
+  # ok read/edit/write's file right after it ran ({path:, mtime_ns:,
+  # size:}), what WorkingSet tells a file changed since by.
   ToolRun = Data.define(:output, :capped_output, :truncated, :activity, :images, :shown_params, :shown_label, :refs, :diff,
-                        :output_file, :loaded) do
+                        :output_file, :loaded, :stamp) do
     def initialize(output: nil, capped_output: nil, truncated: nil, activity: nil, images: nil, shown_params: nil,
-                   shown_label: nil, refs: nil, diff: nil, output_file: nil, loaded: nil)
+                   shown_label: nil, refs: nil, diff: nil, output_file: nil, loaded: nil, stamp: nil)
       super
     end
   end
@@ -153,11 +156,27 @@ module Samagotchi
                   images: images&.any? ? images : nil,
                   shown_params: params && plugin_tool?(call[:name]) ? params : nil,
                   shown_label: label, refs: refs.empty? ? nil : refs, diff: diff, output_file: output_file,
-                  loaded: result[:loaded])
+                  loaded: result[:loaded], stamp: status == "ok" ? file_stamp(call) : nil)
     end
 
     private
 
+    # An ok read/edit/write's file as it is now, right after the call:
+    # {path:, mtime_ns:, size:}, the path as FileRef has it (against the
+    # session's folder, no realpath). nil for any other tool, a path it
+    # can't place and a stat that fails or isn't a file's.
+    def file_stamp(call)
+      ref = FileRef.for(call[:name], call, cwd: session_cwd)
+      return nil unless ref
+
+      stat = File.stat(ref.path)
+      return nil unless stat.file?
+
+      { path: ref.path, mtime_ns: (stat.mtime.to_i * 1_000_000_000) + stat.mtime.nsec, size: stat.size }
+    rescue SystemCallError
+      nil
+    end
+
     # +output+ cut to +cap+ by its tool's policy (ToolOutputCut); an
     # execute result keeps its tail too, its whole output saved in the
     # session's folder.
@@ -310,7 +329,7 @@ module Samagotchi
     # The session's folder (the Engine's, KernelLoop#session_cwd), else the
     # process's: a bare kernel (specs) has none.
     def session_cwd
-      cwd = @kernel.respond_to?(:session_cwd) && @kernel.session_cwd&.call
+      cwd = @kernel.session_cwd&.call if @kernel.respond_to?(:session_cwd)
       cwd.to_s.empty? ? Dir.pwd : cwd
     end