samagotchi 0.133.0 → 0.135.0

data/docs/guardrails.md

@@ -54,6 +54,11 @@ changed: `diff +3 −1` under the row on the web (closed, it survives a
 reload) and ` +3 −1` at the end of the terminal's tool line. The model never
 sees these diffs.
 
+The card also carries the ask's facts as `approval:` (tool, command or paths, where, rule, scopes, preview…):
+`Guardrails::Approval.payload` builds them as a `Guardrails::ApprovalFacts` value, which System 1 and the parent
+checks read in the worker; the card and the session file get its `to_h`, the same hash every UI reads, and a saved
+card comes back through `ApprovalFacts.from_h` (string or symbol keys, missing fields nil).
+
 Who answers:
 
 - REPL (`chi --no-shared`, with or without `-p`): at the `? ` prompt.
@@ -433,16 +438,46 @@ message:
   project env ([Project env](sessions.md#project-env)); a command that runs
   `mise` or `direnv` asks the owner (`ENV_LOADER`: they load the project's env
   files, and `.envrc`, `mise.local.toml` and its kin are secrets like `.env`),
-  and so does a write (by a file tool or a command) to mise's config
-  (`MISE_CONFIG`: the owner's next worker start runs its `[env]`);
+  and so does a write (by a file tool or a command) to mise's config, its
+  `.tool-versions` included (`MISE_CONFIG`: the owner's next worker start runs
+  its `[env]` and installs what it pins; a command asks when a part of it that
+  names one may write: `rm`, `mv`, `find … -delete` and `find … | xargs rm`
+  do, a read-only part such as `find . -name mise.toml && make` doesn't, the
+  list split at `;`, `&&`, `||` and newlines outside `( … )`; mise's own
+  writes, `mise use`/`mise set`, ask as runs of mise; a config that changes
+  without being named, by `git checkout`, `git stash pop`, `tar x`, `patch` or
+  `cp -r dir/. .`, isn't asked about: the owner's next restart runs it);
   and a command still
   running at the limit is killed, never handed over as a background task;
-- git settings that make git run a command (`core.hooksPath`,
-  `core.fsmonitor`, `core.sshCommand`, `core.pager`, `core.editor`, a `!`
-  alias) by `git config` or `git -c`, and `git config --global`/`--system`;
+- git config writes, whatever the key (any may make git run a command later
+  in the owner's name: hooks, `core.fsmonitor`, a filter, diff or merge
+  driver, a credential or gpg helper, `hook.<name>.command`, an include): a
+  pair turn's `git config` only reads, parsed strictly
+  (`PairCommand#git_config_read?`: `--get`, `--get-all`, `--get-regexp`,
+  `--get-urlmatch`, `--get-color(bool)`, `-l`/`--list`, `get`, `list` or a lone
+  key, with `--show-origin`, `--show-scope`, `--name-only`, `-z`, `--type=…`,
+  `--default`, `--file F` and the like, every word accounted for; any other
+  option, an abbreviation git would take (`--glob`, `--comm`), a short form
+  (`-t`) or a word too many is a write). Denied too: `git -c`, `--config-env`,
+  a clone's, init's or submodule's `-c`/`--config`, an assignment of
+  `GIT_CONFIG_*` or `GIT_TEMPLATE_DIR`, `git` under an alias, `git config` after
+  `xargs` or in `find -exec`, and an interpreter's script naming `git config`
+  or `git -c`, behind any of git's own options (`--attr-source X`,
+  `--shallow-file X`; one chi doesn't know is read both with and without the
+  next word as its value, `PairCommand.git_command_starts`), and by a
+  builtin's dashed name (`git-config`, `…/git-core/git-submodule foreach`:
+  judged as `git config`, `git submodule`). A command git runs now from its text (`git submodule foreach`,
+  `rebase --exec`, `bisect run`, a `filter-branch` filter, `--upload-pack`,
+  `--receive-pack`, `--extcmd`, an `ext::` URL) is read as a command of its
+  own and asks as an outside write. A `.gitattributes` write isn't asked
+  about: it only selects a driver, and defining one is what's denied;
   and writing git's hooks: a `write` or `edit` of a path in a `.git/hooks`
-  folder (as given or as it resolves), or a command that isn't read-only and
-  names one (`printf … > .git/hooks/pre-commit`, `cp x .git/hooks/`);
+  folder, a submodule's `.git/modules/<name>/hooks` too (as given or as it
+  resolves), or a command whose part that names one isn't read-only
+  (`printf … > .git/hooks/pre-commit`, `cp x .git/hooks/`), and installing
+  them: `git init`/`clone --template`, and the hook installers
+  (`PairCommand::HOOK_INSTALLERS`: `pre-commit install`, `husky`, `lefthook
+  install`, `simple-git-hooks`, `overcommit --install`);
 - running chi, by any wrapper (`bin/chi`, `bundle exec chi`, `ruby … bin/chi`,
   `env … chi`, `watch`, `npx`, `sh -c 'chi …'`, `$(chi …)`), in an assignment's
   value or an alias, a function, after `-exec`/`-c`/`-e`, but `chi --version` and
@@ -482,9 +517,40 @@ message:
 A script a command hands on is read too (`Guardrails::PairCommand`): one a
 shell runs (`sh -c`, `eval`, a heredoc or here-string) as a command of its
 own, one another interpreter runs (`ruby -e`, `python - <<EOF`) by its text
-(chi, secrets, the environment, detaching). A heredoc written as data (`cat`,
+(chi, secrets, the environment, detaching). So is a command handed through a
+variable a program runs through a shell (`PairCommand::COMMAND_ENV`:
+`GIT_EDITOR`, `GIT_SEQUENCE_EDITOR`, `EDITOR`, `VISUAL`, `GIT_EXTERNAL_DIFF`,
+`GIT_SSH_COMMAND`, `GIT_SSH`, `GIT_PROXY_COMMAND`, `GIT_PAGER`, `PAGER`,
+`MANPAGER`, `GIT_ASKPASS`, `SSH_ASKPASS`, bash's `PROMPT_COMMAND`), as a prefix,
+`env`'s or `export`'s: read as `sh -c` would run it, for the refusals and for
+an outside write. An assigned value that keeps a `$(…)`, `${ …; }` or backticks
+as text (`PS4='$(…)' bash -x`, `PS0`, `PS1`, `$'\x24(…)'`: the shell expands it
+later), a prefix's, a bare assignment's or `export`'s (not `grep 'X=$(…)'`), is
+refused for what its `$(…)` runs (`PS4='$(git config …)'`), and otherwise the
+owner approves it (`PairBoundary::NET`: `CFLAGS='$(BASE)' make`).
+The program is found behind the wrappers (`env`, `sudo`, `timeout`, `xargs`,
+`nice`, `exec`, `command`, `builtin`, `xcrun`, `arch`, `script`'s file, `npx`,
+`bunx`, `uvx`, and two-word ones: `uv`/`poetry`/`pdm`/`hatch`/`pipx run`,
+`pnpm`/`yarn exec`/`dlx`, `npm exec`/`x`, `bun x`, `mise exec`/`x`) and their
+value options (`env -u X`, `sudo -u root`, `timeout -s KILL 5`; `xcrun -r`,
+`sudo -n` are flags). A command line a program takes as text is read as a
+command: `env -S S` (`-vS S` too), `script -c S`, `npx`/`npm exec -c S`
+(`--call`), `rsync -e S` (`--rsh`), ssh's (scp's, sftp's) `-o ProxyCommand=S`
+(`LocalCommand`, `KnownHostsCommand`: they run here), `hyperfine`'s arguments,
+`parallel`'s and `watch`'s. And as a net for a runner no list knows, any word
+but the program's (a wrapper's option value too) that names git is read as git
+from there, one naming chi before a chi command counts (`chronic chi share x`;
+not `cp bin/chi /tmp/x`), and a command line starting with git or chi is read
+as a command (`some-runner 'git config k v'`): a hit asks the owner
+(`PairBoundary::NET`), it doesn't refuse, since chi can't tell whether that
+word runs (`gh pr create --title 'git config fix'` asks too). A read stays a
+read, and a command that only reads (`rg 'git config'`) isn't netted. A heredoc written as data (`cat`,
 `tee`, `git commit -F -`) is not looked into: where it goes is checked. A
 command the checks can't read is refused, never let through on a text match.
+A program is told by its name in any case, on every disk (`GIT config`, `Chi
+share`, `/bin/SH -c`, `NOHUP`: a disk that folds case, macOS's default, runs
+them as git, chi, sh, nohup; `ShellLex.program_name`), and so is chi or git
+config in a script's text.
 
 And it **asks the owner** before a `write` or `edit` that may land outside the
 session's project root, and before a command that may write there, every time:
@@ -502,7 +568,51 @@ rule lowers it), so it comes even in auto mode. A command fails closed
   (`~/oth*`), `git -C`'s folder and the paths in a script it hands on (`sh -c`
   read as a command, `python -c`/`ruby -e`/a heredoc by the paths in its text)
   among them. The program's own word doesn't count (`/usr/bin/sed`), nor does
-  `PATH=…`, nor a message's heredoc (`git commit -m "$(cat <<'EOF' … EOF)"`).
+  `PATH=…`, nor a message's heredoc (`git commit -m "$(cat <<'EOF' … EOF)"`);
+  and it runs no program that writes to its own place outside with no word
+  naming it (`Guardrails::ImplicitWriters`, examples rather than a closed
+  set: `npm`/`pnpm`/`bun`/`deno` global in any spelling (`-g`, `--global=true`,
+  `--location global`, `npm_config_global=true`), `npm`/`yarn`/`bun link`,
+  `npm config set`/`login` (`~/.npmrc`), `yarn global`, `pip install`/`pip
+  config` by any interpreter (`python3.12 -m pip`, `pypy3 -mpip`; with or
+  without `--user`: its site-packages is wherever its Python is; a project
+  venv's `.venv/bin/pip` and `-t`/`--target`/`--prefix` don't count), `uv pip
+  install --system`, `gem install`, `bundle config set` without `--local`,
+  `brew` but its reading verbs, `defaults write`, `cargo install`, `go
+  install`/`go env -w`, `pipx`, `uv tool`/`uv python install`, `dotnet tool
+  install -g`, `corepack enable`, `rustup`/`pyenv`/`rbenv`/`asdf`/`volta`/`nvm`
+  installs and globals, `code --install-extension`, `gh auth`/`config
+  set`/`extension install`, `launchctl` but its reading verbs, `git maintenance register`/`start`, `git
+  lfs install`/`update` (git's words from its subcommand on: not `git add
+  maintenance start`), `scalar register`/`clone`; a project
+  install such as `npm install` or `bundle install` and build caches don't
+  count), and no shell or interpreter that reads its script from stdin: one
+  on the receiving end of a pipe whatever its options (`… | sh`, `| bash -x`,
+  `| sh -e`, `| python3 -c 'exec(input())'`), `< file`, `bash -s`, `python3 -`,
+  or with no script at all: chi can't see that script. A shell's `-e`, `-x`
+  and `-o …` are flags, only `-c` (or a cluster holding it, `-ec`, `-cx`)
+  hands it a script: the first word after its options (`sh -c -- S`, `bash -c
+  -x S`), and fish's `--command S` (`--command=S`) or `-C`/`--init-command S`,
+  a command it runs first (also attached, `-C'S'`, in a cluster, `-lC S`, and
+  by a prefix fish takes, `--comm`, `--init`); an interpreter's own code flag does (`python -c`, `ruby -e`,
+  `node -e`/`-p`/`--eval=`, `perl -e`/`-E`, `php -r`/`-B`/`-R`/`-E`, `jruby`/`raku`/`julia -e`), alone or in a cluster
+  (`ruby -we`, `perl -le`, `node -pe`, `python3 -Ic`, `python3 -c'…'`;
+  `PairCommand.cluster_code_at`: a letter that takes the rest of the word,
+  `ruby -rset`, holds no code). A script file it names (`sh
+  run.sh`, `ruby x.rb`) is not read.
+
+  Accepted gaps (an accident guard for a trusted team): a script file the turn
+  wrote and then runs; inline scripts read only by their text for paths
+  (`find … -exec sh -c '…'`, `flock … sh -c`, `awk 'BEGIN{system(…)}'`,
+  `deno eval`); a `GIT_CONFIG_*` or a `COMMAND_ENV` variable set by `printf -v`
+  or `read` and exported (`printf -v GIT_PAGER …; export GIT_PAGER; git log`);
+  a variable outside `COMMAND_ENV` whose value a program runs (`LESSOPEN`,
+  `BROWSER`, a tool's own `*_EDITOR`; `GIT_EXEC_PATH` runs only a file the
+  turn wrote); an interpreter no list names (as `awk`); `npx -y`,
+  `npm exec`, `pnpm dlx`, `uvx`: they fetch into a cache, which doesn't count,
+  and run the package (judged as the program) as in-project work; a wrapper's
+  value option no list names (`uv run --with x git …` reads `x` as the program;
+  the net still reads the git or chi after it).
 
 Anything else asks: `rm -rf ~/x`, `sed -i … ~/x`, `curl -o ~/x`, `dd of=~/x`,
 `touch`/`mkdir` outside, `perl -pi … ~/x`, `cd .. && make`, `cd && make`, and
@@ -629,7 +739,8 @@ repo is in count as outside.
 `touches: chi_dirs` (shell tools) matches a command that names a path in chi's
 own folders: the config folder (`config.yml`, `memories/`), the hooks folder,
 the approval store, installed bundles (`memories/.bundles`), the session repo's
-git hooks (`core.hooksPath` honoured) or any `.git/hooks` outside a tmp folder.
+git hooks (`core.hooksPath` honoured) or any `.git/hooks` (a submodule's `.git/modules/<name>/hooks` too)
+outside a tmp folder.
 Each word is read as a path against the folder the command is in by then
 (`cd`, `pushd`/`popd` and `( … )` followed), with `~`, `$HOME` and
 `$XDG_CONFIG_HOME`/`$XDG_STATE_HOME` expanded and symlinks resolved. So
@@ -653,11 +764,18 @@ checked even after the database name, and only its read/display options are
 allowed (unknown options and dot-command arguments are rejected). `gh` allows
 only `run list|view`, `pr list|view|diff|checks`, `issue list|view` and
 `repo view`; `--web`/`-w`, `gh api` and `pr checks --watch` are not read-only.
+`test` and `[ … ]` (with its closing `]`) are read-only as one check, optionally after `!`: a file or string
+test (`-e`, `-f`, `-d`, `-s`, `-r`, `-w`, `-x`, `-L`, `-h`, `-b`, `-c`, `-p`, `-S`, `-g`, `-u`, `-k`, `-O`, `-G`,
+`-n`, `-z` with one operand) or a comparison (`=`, `==`, `!=`, `-eq`, `-ne`, `-lt`, `-le`, `-gt`, `-ge`), so
+`test -f x && cat x` and `[ -d dir ] && ls dir` only read; `-a`/`-o`, `( … )`, any other operator or a missing
+operand, and `[[ … ]]` are not.
 `$(…)`, backticks, `$VAR` (other than `$HOME`, `$XDG_*`, `$TMPDIR` and `$PWD`
 at a word's start), an env prefix, `sh -c`, `xargs`, `eval`, `sudo` and the
 like make a command not read-only, as does a `task_create` `env:` that sets `BASH_ENV`, `ENV`, `CDPATH`, `IFS`,
 `SHELLOPTS`, `BASHOPTS`, `BASH_FUNC_…`, `LD_PRELOAD`, `LD_AUDIT`, `DYLD_INSERT_LIBRARIES`, `GIT_EXTERNAL_DIFF`,
-`GIT_CONFIG_PARAMETERS` or `GIT_CONFIG_COUNT` (they change what its words run; `PATH` doesn't count). It errs
+or a git config variable (`GIT_CONFIG`, `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_SYSTEM`, `GIT_CONFIG_PARAMETERS`,
+`GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`/`VALUE_n`: `ShellGitDirs::CONFIG_ENV`) (they change what its words run; `PATH`
+doesn't count; a pair turn's command that assigns a git config variable is denied like `git -c`). It errs
 towards asking.
 
 A tool name may be a glob, so one rule covers a plugin's tools (an MCP server's,
@@ -798,6 +916,7 @@ every surface answers for the same paths):
 | in a dir: `under?` (case-folded on a folding disk; `fold: false` exact), `strictly_under?`, `within?` (root resolved too) | `PathResolve` | `under?`: ShellPaths, ReviewPaths, PairCommand, ChildBoundary, SelfProtect's words; `Outside.within?` and RmTargets' `strictly_under?` fold only when the dir exists (a missing session root keeps the case it was typed in); `within?`: ProtectedPaths, ScratchWrites, ParentApprovals, SelfProtect's paths |
 | tmp dirs and "not one the session is in" | `PathResolve.tmp_roots(session:)` (exact case) | Outside (`Outside.tmp_roots` is the list it and Targets read), RmTargets; `touches_chi?` takes all of them |
 | a shell word's `~`, `$HOME`, XDG dirs, `$TMPDIR` | `PathResolve.expand_word` | ShellPaths::Walk, ShellGitDirs; PairCommand has its own `~`/`$HOME` (`expand_tilde`) |
+| a program word's name: basename, case-folded on every disk (`GIT`, `/bin/SH`, `ſh`) | `ShellLex.program_name` / `.program?` | PairCommand, ImplicitWriters, SelfProtect's file runners, ShellGitDirs, SharedGit |
 | chi's dirs | `ChiDirs.protected` / `.touches` / `.self_protect` / `.review` | ParentApprovals, Targets, SelfProtect, ReviewPaths (`ProtectedPaths` and `ScratchWrites` get theirs from the wiring) |
 
 Left apart on purpose: `Targets.prompt_memory_path?` compares in any case on
@@ -1061,8 +1180,22 @@ gate below passes, in this order:
    it knew the dir: a script or heredoc body (`python3 -c '…'`, `cat >> x.md
    <<'EOF'`), a phrase (`echo "- a note"`) or a glob with no `/`. So
    `cd memories; cd ..`, `cd "${PWD%/*}"`, `cd $(dirname $PWD)` or `cd -`
-   loses the exemption, and the memories text then refuses it. A script body
-   is not looked into beyond its text: an accident guard, not containment.
+   loses the exemption, and the memories text then refuses it. So does a
+   script a shell or interpreter runs that climbs by its own calls
+   (`SelfProtect::SCRIPT_CLIMB`: `os.pardir`, `dirname`, `chdir`, `Dir.pwd`,
+   `Path.parent`, `rindex`, a slice from the end), and one chi can't see: a
+   script file (`cd memories && python3 x.py`) or stdin (`… | python3`,
+   `sh < f`, any interpreter or shell a pipe feeds, `| sh -x` too), by any
+   version's name (`python3.12`, `pypy3`, `Rscript`, `tclsh`), or a program
+   that runs a file (`SelfProtect::FILE_RUNNERS`: `make`, `rake`, `awk -f`,
+   `deno run`, `npm run`). A heredoc only written (`cat >> x.md <<'EOF'`) is
+   data whatever it says. A script body is not looked into beyond its text:
+   an accident guard, not containment (a script can build a path some other
+   way: `p.replace("memories", "config.yml")`, `p[0:len(p)-8]`, `.sub`,
+   `.slice` aren't caught). The price is some harmless commands the user now
+   answers: `python3 scripts/lint.py <memories>/notes.md`, `cat notes.md |
+   python3 -c …` from the memories folder, a climb word written as data by a
+   script (`File.write(".../notes.md", "dirname")`).
    A protected rule
    (`Verdict::PROTECTED_RULES`) may be listed by name and System 1 may answer
    it, but a call that really writes config.yml or the hooks is refused here;

data/docs/internals/background-tasks.md

@@ -45,6 +45,7 @@ Behavior:
 - `execute` and `task_create` both spawn with chi's own Ruby/Bundler setup scrubbed (`TaskRuntime.sanitized_spawn_env`): `RUBYOPT` loses its `-r…bundler/setup` flags (others stay) and `RUBYLIB`, `BUNDLE_GEMFILE`, `BUNDLE_BIN_PATH`, `BUNDLER_VERSION` are unset, so a project's `ruby -e` or `bundle exec` uses its own Gemfile when chi runs under `bundle exec`. `task_create` refuses those keys in the model's `env`; `execute`'s `env` comes from chi's callers (`Builtins`, `!cmd`), not the model, and is set over the scrub. An `execute` handed over at its limit keeps the process it spawned, so the task runs with the same env.
 - `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none) and `SAMAGOTCHI_SESSION_REASONING_HISTORY` (its own reasoning_history level, the same way). `chi self` reads the last three for its model, thinking level and reasoning history. The four are `ChildEnv::SESSION_MARKERS` (`TaskRuntime::MARKER_ENV_KEYS`), which a spawned worker unsets (`ChildEnv.unset`, merged into its spawn env). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 - They also pass on a set `XDG_STATE_HOME` / `XDG_CONFIG_HOME` made absolute (`Builtins.xdg_absolute`, via `Paths`), so a chi the command runs in another `cwd` (`chi send`) reads this chi's state and config. These aren't reserved: an XDG dir the model sets in `task_create`'s `env` stays its own.
+- Every runner starts from the session's project env, `ProjectEnv.tools_env`: the overlay a spawned worker computed once at boot (`SessionManager.apply_project_env` → `ProjectEnv.compute` → `ProjectEnv.install!`; its folder's `mise env`, and the chi shim's dir first on PATH so `chi` is the chi home's), less `ProjectEnv::TOOLS_DROP` (`RUBYOPT`, `RUBYLIB`, Bundler's: the scrub above sets those). Outside a worker (`ProjectEnv::NONE`) it is `{}`. The sites: `execute` and `task_create` (`Tools::Builtins#project_env`, under the markers and the model's `env`; a participant's turn gets `{}`), the user's `!cmd` (`SessionCommands#shell`) and a context source's command (`ContextFetch#env_for`). MCP servers take `ProjectEnv.current.env` whole under the server's own keys (`bundles/mcp/plugin.rb` `server_env`: no `TOOLS_DROP`, no participant rule). chi's own process env is never changed, and the project env never enters the prompt. User docs: [Project env](../sessions.md#project-env); the launch side: [How chi launches itself](../architecture.md#how-chi-launches-itself).
 
 ## Finish wake
 

data/docs/internals/engine.md

@@ -76,7 +76,10 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #   messages, goes IDLE, records last_turn (enqueued_id: the turn's input, from its origin;
   │     #   a continue turn's origin carries its offer turn's, ContinueOffer#run_continue_turn),
   │     #   and :turn_completed {result, turn_summary, display_pending} or :turn_canceled
-  │     #   {cancellation_reason, cancelled_by, duration_ms} is emitted
+  │     #   {cancellation_reason, cancelled_by, duration_ms} is emitted; before the replace,
+  │     #   stamp_opening puts a Verify turn's `verify` and a completed Revise turn's `revises`
+  │     #   (re-targeted to its stack's top) on the opening message, metadata never sent, and
+  │     #   :turn_completed carries `verdict` / `revises` when there are
   │     # then the :after_turn hook (status, messages, present: the AnswerDisplay presenter,
   │     #   refs: the AnswerRefs adder)
   │     # store_answer_display (one replace of the answer: `display` and/or `display_refs`;
@@ -330,7 +333,7 @@ One iteration with tool calls:
   stored under the real path; at most `RowRefs::MAX_REFS` and `MAX_BYTES`). `ToolRowFields.for` can't build it (no plugins on a reload), so the run carries it
   as `refs:`, saved with the result as `tool_refs` (`ToolResponse::SAVED_KEYS`, never sent), and
   `MessageParts#tool_part` reads it back through `RowRefs.for_display` (checked again). The page binds them to the
-  row's title (`refs.js bindRowRefs`, from `turn_view.js` live and on a reload): the first ref on it, the rest in its
+  row's title (`refs.js bindRowRefs`, from `turn_block.js` live and on a reload): the first ref on it, the rest in its
   menu.
 - Settles an ask verdict after `:tool_call_started`, so a UI shows the tool line and then the approval.
 - Dispatches through `KernelLoop#dispatch_tool_call`, or writes the denial text. Unknown tools are answered in
@@ -545,7 +548,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:working_set_updated` | after `:generation_started` (the running turn's conversation, the turn's strategy) and once in `end_turn` before the end event (the kept messages), only when the set differs from the last one emitted for the session and is not empty, except one empty event when the last one had items (a rollback emptied the set): a tool-free turn emits none (`Engine#emit_working_set`); between turns `Engine#announce_working_set` announces it under the next turn's strategy (after a `/working-set` op, held behind the command's `command_ran`) | `{items: [{kind, key, state (live\|stale\|forgotten\|dropped), tokens, ops, count, first_id, pinned, has_drop}], at, adds?: [{kind, key, label}]}` (`WorkingSet`, internals/working-set.md; `adds` while the user's adds are pending) |
 | `:hook_notice` | a hook's or plugin's notify during a turn | `{hook, text, level}` (announced with `between_turns: true` outside a turn) |
 | `:guardrail_warning` | a guardrails line during a turn | `{message}` |
-| `:turn_completed` | normal end | Engine event `{result, turn_summary, display_pending}`; the Bridge's SSE frame omits `result` (answer remains in `turn_summary.output`) |
+| `:turn_completed` | normal end | Engine event `{result, turn_summary, display_pending}`, plus `verdict` (a Verify turn's recorded verdict) and `revises` (a Revise turn's stamp, `{turn_id}`) when there are; the Bridge's SSE frame omits `result` (answer remains in `turn_summary.output`) |
 | `:turn_canceled` | Stop, hook stop, Ctrl-C | `{cancellation_reason, cancelled_by?, duration_ms}` |
 | `:turn_failed` | an error | `{error_class, message, duration_ms, error_kind?, retryable?, host?, summary?}` |
 | `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display, refs?}` (display a string, or nil; refs the count of the answer's refs, only when a hook attached some) |

data/docs/internals/participants.md

@@ -195,11 +195,12 @@ Everything else is `:owner`: `/answer`, `/command`, `/images` (an image a prompt
   to act: the turn only reads (`Guardrails::ReviewBoundary`), and proposes what the owner applies ([Apply](#apply)).
 - **`:pair`**, a working session's participant invited to act: the turn acts with the session's tools under the
   owner's guardrails, its asks go to the owner and offer once only, and `Guardrails::PairBoundary` denies secrets,
-  chi itself and chi web on loopback, background and scheduled jobs, the environment and credential printers, git's
-  hooks, owner-voiced tools and the owner's task outputs, and the model's own question, and asks before a command
-  that makes a link and before a write that may land outside the project, failing closed (a session at or above
-  home has none: every write asks) ([guardrails](../guardrails.md#a-participants-pair-boundary)). No Apply: it
-  acted itself.
+  chi itself and chi web on loopback, background and scheduled jobs, the environment and credential printers, git
+  config writes (reads only) and git's hooks, owner-voiced tools and the owner's task outputs, and the model's own question, and asks before a command
+  that makes a link and before a write that may land outside the project, failing closed (a global install or a
+  user config write that names no path, `Guardrails::ImplicitWriters`, and a script read from stdin count; a
+  session at or above home has none: every write asks) ([guardrails](../guardrails.md#a-participants-pair-boundary)).
+  No Apply: it acted itself.
 
 `ParticipantMode.of(session, features:)` is the session's: what a participant invited now gets. No session is
 `:review`. A worker names `pair_turns` (`Delivery::PAIR_FEATURE`) when it runs pair turns; one without it runs
@@ -582,7 +583,7 @@ message's `author_name`, `turn_started`'s, or the panel's list (`participant_nam
 A review turn proposes; the owner applies (D4, §3 Apply-as-quote). A pair turn acted itself: no Apply under it
 (`ReviewApply.review_turn?`: a participant's opening message not stamped `pair`; the route answers it
 `not_review_turn`, and its "latest" skips it). Under each participant's review turn that has a
-reply, the owner's page shows **Apply** (`review_apply.js`; drawn by the history render, `turn_view.js`, and at a live
+reply, the owner's page shows **Apply** (`review_apply.js`; drawn by the history render, `turn_block.js`, and at a live
 turn's end from its `turn_started`'s turn id and author, in the stage while the stage holds the turn; a full-width
 button on a phone). It reads `GET …/apply?turn=T` and puts the answer in the composer, after whatever is typed there,
 never sent: the owner reads it, edits it, sends it or not. While the composer holds it (`deliveryControl.hold()`,

data/docs/internals/tool-guardrails.md

@@ -50,6 +50,8 @@ Configuration (config.yml `execute.*` keys and CLI flags too, as for `read`):
 - `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC` (`execute.timeout_sec`, default `120`): what a command still running then gets is `execute.on_timeout`.
 - `SAMAGOTCHI_EXECUTE_ON_TIMEOUT` (`execute.on_timeout`, default `task`): `task` hands the command over as a background task, not killed; the result starts `Still running at the 120s limit: moved to a background task, not killed.` (`Execute::HANDED_OVER`), then its `task_id:` and the tails of stdout and stderr so far, and `task_wait` waits for it. `kill` stops it and answers `Error: command timed out after …s` (`Execute::TIMEOUT_PREFIX`) with the hint to use `task_create`. The `!cmd` bang always kills. See [Background tasks](background-tasks.md).
 
+The env a command runs in (the session's project env, `ProjectEnv.tools_env`, then the Ruby/Bundler scrub and chi's markers) is the same for `execute`, `task_create`, `!cmd` and context sources: see [Background tasks](background-tasks.md).
+
 Implementation note:
 
 - Shared logic lives in `lib/samagotchi/tools/output_guardrails.rb` and is used by `read` and `execute`, and by `edit` (its env switches) and `delegate_wait` (the head+tail preview of a child's long reply).

data/docs/internals/web-frontend.md

@@ -0,0 +1,262 @@
+# The web frontend: where state lives
+
+A map of `lib/samagotchi/web/public/` for whoever changes it: where the page keeps what it knows, how a change
+reaches the screen, and the guards every new piece should use. The modules' own header comments say what each one
+does; this page says how they hang together. The server side is [architecture.md](../architecture.md) (Web);
+the working set's overlay is [working-set.md](working-set.md), participants are [participants.md](participants.md).
+
+No build step: `index.html` and `participant.html` load ES modules as they are, with lit-html (`vendor/`) as the
+only library. Pure modules (`*_model.js`, `session_state.js`, `sessions_list.js`, `turn_range.js`, …) touch no DOM
+and have `node --test` specs under `spec/web/public/` (happy-dom for the DOM ones); the pages as a whole are covered
+by `npm run e2e` (`spec/e2e/`). `app.js` has no unit spec.
+
+**New exports go in new modules.** The static JS is served at unversioned URLs. Today every load revalidates
+(app.rb `serve_static` sends `Cache-Control: no-cache` with a content ETag, and `sw.js` has no fetch handler), but an
+open tab still holds the modules it loaded, and a proxy that ignores `no-cache` can serve an old one: a new export
+on an existing module, imported by a new version of another, then finds the old module without it and blanks the
+page. A factory dep a new version stops passing is the same hazard the other way round: the store's redraws took
+`updateInfoBar` and the chip controls out of `stream_handlers.js`'s deps (and `updateInfoBar`/`updateComposerMode`
+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`,
+`turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
+`session_fields.js`, `feature_gates.js` and `revise_stack.js` are new modules for that reason.
+
+## Two pages, two models
+
+| Page | Entry | Model |
+|---|---|---|
+| **Owner page**: the start page and a session page | `index.html` → `app.js` | **Render once, then patch.** A session's open (`select` → `resync` → `renderSessionView`) draws the history from `GET /api/sessions/:id`; from then on each stream event changes the DOM in place (`stream_handlers.js`). The DOM *is* the log. The start page is the same app with `store.selected` null. |
+| **Participant page**: a review or pair link | `participant.html` → `participant.js` | **Re-read at a turn boundary, then a keyed redraw.** It reads `GET …/review`, draws it, and streams; an event that ends or changes a turn (`reloads`) marks the data stale and the page reads it again. `drawnMessages` keeps a message's node while its signature is unchanged; a small `live` overlay (`participant_model.js applyLive`) draws the running turn on top. |
+
+The participant page is **deliberately separate**: it shares leaf modules with the owner page (the annotate bar,
+claim links, `composer_mount.js`, the verdict card and Verify fresh, `verify_target.js`, `verify_preset.js`,
+`auth_lost.js`, `token_fragment.js`, `format.js`) but none of the data layer, the stream handling or the message
+rendering. It has its own `api` (`{status, ok, body}`, never throws, its own ended / auth-lost handling) and its own
+`EventSource`. Its parallel copies of the owner's Verify and claim helpers (`verifyFreshState`, `verifyAnchorFor`,
+`showPendingClaim`, `CLAIM_ROOTS`) differ on purpose in places (the source kind `reply` vs `answer`, the server's
+`fresh_running` vs `verify_fresh`, no home/cwd in its claim options). Don't converge them as a side effect of another
+change.
+
+## Where state lives (owner page)
+
+| Holder | What | Who writes | How a change reaches the screen |
+|---|---|---|---|
+| **The session store** (`session_store.js`; app.js `store`) | `store.selected` (the open session's id), `store.current` and `store.sessions` (below) | through the store only (see The session store); other modules get getters (`selected: () => store.selected`, `state: () => store.current`) or the store itself (`stream_handlers.js`, `send_turn.js`, `session_actions.js`) | the store runs the redraws that read what changed (below); nobody calls them by hand |
+| **app.js module scope**: about 20 top-level `let`s (`streamControl`, `eventsControl`, `pageCapabilities`/`pageEditorUrl`, `pendingVerifyAnchor`, `pendingClaim`, `resyncsInFlight`/`resyncAgain`, `resyncAttempts`, `scopeError`…) | the page's mode and its streams | app.js only; other modules get getters and hooks | the writer touches the redraw that reads it (`store.touch("infoBar")`: the stream, versions, `restartingIds`), or calls a redraw only it feeds |
+| **`store.current`** (`session_state.js`: `emptySessionState` / `sessionStateFrom`; per field: `session_fields.js FIELDS`) | the open session's fields, about 40 (info bar, chips, verdicts, timing, worker, stream cursor) | `store.update` / `setStatus` from app.js, `stream_handlers.js`, `send_turn.js` (`firstPreview`, `owner`), `session_actions.js` (`status`); `forgetSession`'s `replaceCurrent`. Two writers in place, on purpose (D8 in `FIELDS`): live_timing.js's `activeTurn`, verdict_fresh.js's running list | the store runs the field's redraws (`FIELDS[key].redraws`) |
+| **`store.sessions`** (the hub's projection) | every card | `store.update({sessions})` from app.js: `openSessionEvents` (`applySessionEvent`), `refresh` (the list fallback), `addCreatedSession`, `applyView` (re-sorted), `replaceSelectedCard` (`setLiveStatus` through `setStatus`, `readTurnEnd`, `setUsedMemories`), the stream's close (`withoutWorker`); `session_actions.js` (`setSessions`) | the store: `lists` and `infoBar`. **Always a new array**; an entry is replaced, never changed in place. `followSelectedSession` copies the open one's owner and worker (`fieldsFromCard`) and, when not streaming, its status (`setStatus(…, "hub")`) into `store.current` |
+| **Factory closures**: the `create*` factories (popovers, panels, views) | each component's own state: open-for, busy, error, its own fetched list | the factory | an `onChange` hook back into app.js, or a getter the factory reads at draw time |
+| **The history DOM** | the conversation as drawn: which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), kept command bubbles, which texts were shown, unnamed badges, folded answers (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`) | `bubbles.js`, `cards_place.js`, `question_cards.js`, `turn_block.js`/`stage_view.js`, `answer_fold.js`, `revise_stack.js`, `stream_handlers.js` (a live `turn_completed`'s `revises` onto its prompt) | read back as state: `turn_range.js turnElements` (one walker for a turn's elements), `keptCommandBubbles`, `seedSeenFromDom`, `nameUnnamedBadges`/`nameVerdictCards`, `answer_fold.js` and `revise_stack.js` (their observers decorate every path that fills `#history`; the stacks are `stacks()` of the stamps, read again on each change, never a store field), `history_reveal.js revealInHistory` (the one way a jump unfolds what hides its target) |
+| **localStorage** (`storage.js` `readStored`/`writeStored`, guarded) | per-browser choices only | the module that owns the choice | read at start (see Storage keys) |
+| **SSE** | see Streams | the server | owner page: events go into the DOM directly; participant page: an event marks the data stale |
+
+The start page's own choices (the model, the ⚙ panel, the 🧰 list) live in `start_page.js`'s closure, never in
+`store.current`. A fresh chain link's picker reads both.
+
+## The session store
+
+`session_store.js` holds the open session's state; `session_fields.js` says what each field is. **Every write goes
+through the store**, never `current.X = …`:
+
+- `store.update({selected?, current?: {field: value}, sessions?})`: `current`'s fields are written into the same
+  object (it is replaced only by a session switch); `sessions` is always a new array (one changed in place isn't
+  seen).
+- `store.setStatus(value, source, {streaming})`: the one way `status` changes (below).
+- `store.replaceCurrent(state)`: `forgetSession` only; always a new object, so a stale async writer still holding the
+  old one writes there alone.
+- `store.batch(fn)`, `store.touch(name)`, `store.on(name, fn)`: the redraws (below).
+
+The ESLint block `samagotchi/session-writes` (eslint.config.js) enforces it in the six modules that hold the state
+(app.js, `stream_handlers.js`, `send_turn.js`, `session_actions.js`, `start_page.js`, `working_set_view.js`): an
+assignment, `++`, `delete` or `Object.assign` into `current`, `store.current` or `state()` is an error
+(`spec/web/public/lint_session_writes.test.js` runs it on a sample). An alias (`const st = state(); st.x = …`) isn't
+caught: don't write through one.
+
+**Read `store.current` fresh after every await.** A `const cur = store.current` held across an await pins the object
+from before it, which a session switch (`forgetSession`) may have replaced: app.js's `readTurnEnd`,
+`mergeTurnTiming`, `resync` and `refreshTimingFromSession` read it again after each await. Keep `store.sessions`
+reads fresh too.
+
+### Fields and their redraws
+
+`session_fields.js FIELDS` has one entry per `emptySessionState` key: its payload source (a partial re-read takes a
+field only when the payload carries it: `session_payload.js` reads its sources from here), its hub card source
+(`fieldsFromCard`: owner, workerVersion, workerFeatures, bridgeUp; never status), its redraws (store `ORDER` names)
+and its writers. A new field starts in `emptySessionState` and gets an entry (its spec checks both).
+
+A changed value (`!==`) marks its field's redraws; `sessions` marks `lists` and `infoBar` (the bar reads the list:
+the chain's ← → links, the children chip, the archived button, the card's title, the fresh link's picker); `selected`
+marks `paintActive`, `composer` and `infoBar`; `touch(name)` marks one redraw for an input the store doesn't hold
+(the clock, versions, the stream, `liveTurn.running`). They run synchronously, once each, at the end of the outermost
+`batch()` (at once for a bare write), in one `ORDER`: `lists`, `paintActive`, the chip popovers (`llmContextChip`,
+`thinkingChip`, `reasoningChip`, `workingSetStrategy`), `featureGates`, `composer`, `infoBar`. `lists` comes before
+the bar because `updateSessionTitle` reads the strip's active card; `composer` before the bar as `setTurnRunning`
+runs them. Not a rAF (a background tab runs none, and the title badge tests run there; the e2e per-frame checks would
+see the composer move a frame late) and not a microtask (code that reads the page right after a write would see it
+stale).
+
+**The redraws are registered, not called.** app.js registers each name once (`store.on`, at the bottom, once every
+piece a redraw calls exists): `lists` → `lists.render()`, `paintActive` → `lists.paintActive()`, the chips →
+`xControl.refresh()`, `workingSetStrategy` → `workingSet.strategyChanged()`, `featureGates` (below), `composer` →
+`updateComposerMode()`, `infoBar` → `updateInfoBar()`. A writer writes and stops there: no `updateInfoBar()` after
+a store write. A value written unchanged redraws nothing (a chunk with the same ctx %).
+
+An input the store doesn't hold calls `store.touch(name)` where it changes: `infoBar` for the clock (liveTurn's
+`onTick`), the versions (`noticeVersions`), `restartingIds`, the stream (`startStream`, `workerGone`), the working
+set's and the participants' `onChange`, the copy-attach timer, the continue and review in-flight sets
+(`session_actions.js`); `composer` and `infoBar` for `liveTurn.running` (`setTurnRunning`) and at the end of
+`renderSessionView` (a whole view drawn). Left as they are, on purpose: the `narrowScreen` listener calls
+`updateComposerMode()` (the bar doesn't read it), `applyStripHidden`/`applyView` call `updateSessionTitle()`, and
+`closeStream`/`stream.restart` set `streamControl = null` without a redraw (a resync or a workerGone follows).
+
+A function that writes more than once batches its synchronous part, so each redraw runs once: `select` (before its
+`await resync()`), `clearSelection`, the hub's `snapshot` and `session` events, `workerGone`, `setTurnRunning`,
+`turn_started` (inside `keepFollowing`, so the composer and the bar redraw before its scroll), `readTurnEnd` (after
+its timing merge), `setUsedMemories`, and `renderSessionView`'s field write only: the replay's own
+`setTurnRunning` redraws where they run, before `turnDom.flush()`. A stream handler writes one patch.
+
+`batch(fn)`:
+- `fn` is synchronous: one that returns a promise is refused (`console.error`, the redraws run at once). Batch an
+  async function's synchronous parts only, never across an await.
+- The redraws run in `finally`, also when `fn` throws (the page shows what was written), then `fn`'s error is
+  rethrown; a redraw error meanwhile goes to `console.error`. A throw never leaves the store inside a batch.
+- During a flush, a write, a touch or a batch's end only enqueues: the next pass runs it, after the current pass's
+  `ORDER`. Passes stop at 3 (`console.error` names the redraw). A redraw that throws doesn't stop the others; its
+  error is thrown after the flush.
+
+### `status`
+
+Six writers, each with its rule, all through `setStatus(value, source)` (`session_fields.js statusWrite`):
+
+| source | writer | applies | the open session's card |
+|---|---|---|---|
+| `payload` | `renderSessionView` | always | left alone |
+| `hub` | `followSelectedSession` | only while the stream isn't live | left alone (the card came from the hub) |
+| `stream` | `setLiveStatus` (`turn_*`, `workerGone`'s idle) | always | `withLiveStatus`: status, owner, `updated_at` |
+| `turnEnd` | `readTurnEnd`, the turn_canceled re-read (`refreshTimingFromSession`) | when the payload carries one (the caller skips it otherwise), and **not while a turn runs**: a re-read that lands after the next queued turn's `turn_started` doesn't write its stored "idle" over "running" (the test `mergeTurnTiming` keeps `activeTurn` by) | left alone: `readTurnEnd` writes its card itself after its timing merge, with `used_memory_names` |
+| `stop` | `session_actions.js stoppedWorker` | always | left alone (`workerGone`'s `withoutWorker` changes it) |
+
+`setStatus` answers whether it replaced the card; the new list redraws the lists and the bar by itself.
+
+### Feature gates
+
+A page action the open session's worker must support (its sidecar features and a live bridge) is a gate in
+`feature_gates.js`, registered as the store's `featureGates` redraw: `{name, unavailable(current), redraw}`. It runs
+when a field it reads changes (`workerFeatures`, `bridgeUp`), and a gate's `redraw` only when its answer flipped: a
+restart's hub event that brings the feature enables it, the worker going (`workerGone`'s `bridgeUp = false`) says
+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
+has it. A new action that needs a worker feature is one more entry.
+
+### Exceptions
+
+- **Writers in place (D8)**, named in `FIELDS`: live_timing.js sets `timing().activeTurn` (the running turn's own
+  clock; `mergeTurnTiming` keeps it), and verdict_fresh.js `startFresh` pushes onto `fresh.running`, which is
+  `store.current.verifyFresh`.
+- **Events, not state (D9)**: these stay direct calls next to their write: a `/model`'s picker sync
+  (`syncModelPick`), the working set's `commandRan`, the context chips on a note, the participants reload, a
+  verdict's own `renderFresh`. (The working set's `strategyChanged` and the Verify gate's `redrawFresh` follow
+  fields: they are registered redraws.)
+
+A partial re-read of the open session (a `?tail`/`?recent` read) goes through **`applySessionPayload(data,
+{fields})`** in app.js (`session_payload.js sessionFieldsFrom`): the named fields read as a full load reads them, a
+field whose source the payload doesn't carry left alone; its status goes through `setStatus(…, "turnEnd")`. Their
+redraws follow. Never copy payload keys into `store.current` by hand.
+
+The redraws, by their store names:
+- `infoBar` (`updateInfoBar()`): the session bar's buttons and info line (`info_bar_model.js sessionBar` →
+  `info_bar.js`), the annotate bar, the fold controls, `updateSessionTitle()` and the fresh link's picker. Cheap: it
+  runs on most writes and every clock tick.
+- `composer` (`updateComposerMode()`): the composer's placeholder, buttons and delivery line (selected, running,
+  owner).
+- `llmContextChip`, `thinkingChip`, `reasoningChip` (`xControl.refresh()`): an info-bar chip's **open popover** (the
+  chip itself is drawn by the bar); `workingSetStrategy`: the working set's open list.
+- `lists` / `paintActive` (`lists.render()` / `lists.paintActive()`): the strip and the all view from
+  `store.sessions`.
+- `featureGates`: the gates above.
+
+`forgetSession()` is the one reset: `select` and `clearSelection` both call it, so anything per-session that isn't
+in `store.current` (capabilities, the markdown warning and tip, the init row, the Verify claim, the armed Revise,
+the running turn's DOM) is cleared there, and the feature gates are primed for the empty session. A new per-session holder
+(an armed composer anchor like the Verify claim or the Revise) goes into it. The armed Revise
+(`pendingReviseAnchor`) is set only through `setReviseAnchor`, which redraws its chip and the Revise buttons (a
+redraw only it feeds, not a store field).
+
+## Render idioms
+
+Three, for one job. Pick by what the piece is:
+
+| Idiom | Where | Use it for |
+|---|---|---|
+| **lit `render(template, keptContainer)`** | most components (~26): the info bar, chips and their popovers, panels, the init row, the working set, `start_page.js` | anything redrawn while the user may be in it: lit keeps the nodes, so focus, typed text, an open `<details>` and a tooltip survive. **The default for new UI.** |
+| **lit as a string builder**: `turn_html.js elementOf(template)`, `lists_view.js` (a fresh fragment, then `replaceChildren`) | history bubbles appended once; the session lists | a node built once and then owned by the DOM (history), or a list redrawn whole. `lists_view.js` throws away lit's diffing and binds card listeners per draw, with an `entering` tracker for its animations |
+| **hand-built DOM** (`createElement`) | `question_cards.js`, `verdict_card.js`, `verdict_fresh.js`, `participant.js` (`el()`) and a few small ones | older pieces; don't add new ones this way |
+
+Listeners: every factory is a page-lifetime singleton, so `addEventListener` without a remove is fine; a per-render
+listener lands on a fresh node. A popover goes through `chip_popover.js createChipPopover` (its own outside-click,
+Esc, placement and resize); `context_chips.js`, `model_picker.js`, `ref_menu.js`, `command_list.js` and the lists'
+families/chains popovers still hand-roll theirs.
+
+## Stale answers
+
+The page switches sessions, reopens a popover or asks again while a fetch is out. An answer for the old ask must be
+dropped. **`latest.js`** is the guard:
+
+- `stillOn(get, at = get())`: `() => true` while `get()` is still `at`. For a one-off read about the open session
+  (`const still = stillOn(openId); … await …; if (!still()) return;`). app.js has `openId = () => store.selected`.
+- `createLatest(get)`: `begin()` gives a guard that also goes stale when a newer ask begins; `drop()` makes every
+  ask out stale (a close, a reset). For a list that is re-read.
+
+On it: `context_chips.js`, `project_picker.js`, `participants_panel.js` (`load`), `cards_place.js`
+(`refreshCardBodies`), `stream_handlers.js` (`answer_display`), `working_set_view.js` (`fetchServer`) and app.js's
+turn-end re-reads (`readTurnEnd`, `refreshTimingFromSession`, `mergeTurnTiming`) and init-row timers. Still by hand
+(the id decides more than "drop it"): app.js `resync`/`retryResync` (the re-read budget, `resyncAgain`), the stream's
+close, `session_actions.js` (continue/review open another session on purpose), `send_turn.js` (a failure for another
+session becomes a toast), and `participant.js` (its own `loadSeq`, the separate page). A new await in a component
+uses `latest.js`.
+
+## API clients
+
+- `data.js api(path, opts)`: the owner page's. Throws an `Error` with the server's words, `.status`, `.code` (the
+  server's error code: match on it, never on the words) and `.body`; a signed-out proxy answer (401, a redirect,
+  HTML) or a fetch that fails on a sign-in redirect reports to `auth_lost.js` (`onAuthLost`, set by app.js).
+  `cantText(what, error)` is the toast.
+- `method_api.js methodApi(method, path, body)`: the same, as `notifications.js` and `push_devices.js` call it.
+- `participant.js api`: its own (see above).
+
+## Streams
+
+| Stream | Opened by | Lifecycle |
+|---|---|---|
+| The hub, `GET /api/events` (`data.js openEvents`) | app.js `openSessionEvents` (scoped by `?dir`) | `snapshot` then `session` / `session_gone` → `applySessionEvent` → `allSessions`; EventSource reconnects itself (a fresh snapshot); `onClosed` (a proxy sign-in on reconnect): probe, reopen after `EVENTS_REOPEN_MS` |
+| A second hub stream, unscoped | `notifications.js` (`allEvents`) on a project's page | the Home Screen app's device tidy-up across projects |
+| The open session, `GET /api/sessions/:id/stream?from_seq=` (`data.js openStream`) | app.js `startStream` from `store.current.streamSeq` | events → `stream_handlers.js`. It closes itself on an error; the page resyncs (`resync`: a fresh render and a new stream from its cursor), once at once when it had opened, else after `STREAM_RETRY_MS` |
+| The participant stream | `participant.js connect` | listens for `STREAM_EVENTS`, which is `Web::ParticipantView::EVENTS` (checked by `spec/web/participant_view_spec.rb`); reopened from fresh data when CLOSED |
+
+A new event type for the owner page is a handler in `stream_handlers.js` (the participant view spec makes it decide
+`EVENTS` or `DROPPED`); for the participant page also an entry in `STREAM_EVENTS`.
+
+## Storage keys
+
+Through `storage.js` (`readStored`/`writeStored`: storage can throw, a missing value is the default), except
+`notifications.js`, which takes an injected storage for its specs. Per-browser choices only: never anything that must
+reach another device or the server.
+
+| Key | Module | What |
+|---|---|---|
+| `chi_model`, `chi_model_recent` | `model_pick.js`, `model_picker.js`, `start_page.js` | the start page's model and its recent list |
+| `chi_composer_collapsed` | `composer_fold.js` | the composer folded |
+| `chi_composer_floor` | `composer_grip.js`, `composer_mount.js` | the composer's dragged height |
+| `chi_strip_hidden` (`chi_zen`: the old name, read once) | app.js | the session strip hidden |
+| `chi_stage_collapsed` | `stage_view.js` | the stage collapsed |
+| `chi_working_set_collapsed` | `working_set_rail.js` | the working set rail collapsed |
+| `chi_markdown_tip_dismissed` | `markdown_tip.js` | the markdown tip dismissed |
+| `chi_update_available_shown` | app.js | update notices already shown |
+| `chi_notify`, `chi_push_device` | `notifications.js` (an injected storage) | the bell's state, this device's push id |
+| `chi_answer_fold:<session>` | `answer_fold.js`, `revise_stack.js` | the answers folded by hand, and the Revise stubs unfolded by hand (`stub:<turn id>`) (swept with the session list) |
+| `chi_review_history:<grant>`, `chi_review_history_session:<session>` | `review_history.js` (participant page) | a participant's composer history |
+
+sessionStorage: `chi_client_id` (`turn_events.js`: this tab's client id, kept over a reload mid-turn) and
+`chi.authReloadAt` (`auth_lost.js`: one automatic reload a minute).

data/docs/plugins.md

@@ -1310,7 +1310,8 @@ bundle.shutdown
   value, or raises `Samagotchi::Testing::Waiting::TimedOut` ("timed out after 5 s waiting for <what>", plus
   `; last saw: <value>` from the `seen:` callable). `join!(thread, what)` and `pop!(queue, what)` are
   `Thread#join` and `Queue#pop` with that deadline and message; `wait_until { }` returns the block's last value
-  instead of raising, for a wait whose timeout is fine; `process_gone?(pid)`. Every deadline is multiplied by
+  instead of raising, for a wait whose timeout is fine; `process_gone?(pid)`; `time_bound(seconds, below: nil)`, a
+  wall-clock upper bound scaled the same way and kept under `below:` (the unscaled deadline it tells apart from). Every deadline is multiplied by
   `SPEC_TIME_SCALE` (default 1, at least 1; chi's CI sets 2), so a slow runner gets headroom.
 - **Model notes:** `sandbox.model_notes_for(model_id, small: nil, cwd: nil)` lists the model notes chi would load
   into the prompt for a bare model id (`deepseek/deepseek-v4.1-flash`, no host prefix), from the sandbox's